docs: design bounded hosted live smoke tier

[steipete]

Summary

• propose a bounded tier-two hosted live-smoke design with a literal first-phase allowlist of DigitalOcean and Scaleway, selected for their small fixed instance shapes, dedicated lifecycle runners, provider-native ownership metadata, and verified cleanup surfaces
• define the live-smoke protected-environment boundary, schedule/manual-only triggers, main-only checkout guards, least-privilege provisioning and sweeper credentials, rotation policy, and the required-reviewer tradeoff for scheduled reconciliation
• set explicit USD 0.25 per-provider, USD 0.50 per-scheduled-run, and USD 20 monthly ceilings, enforced through dedicated provider projects, one-resource quotas, hard project credit limits, fixed shapes, TTLs, sequential execution, and workflow timeouts
• specify targeted always-run cleanup plus an independent 15-minute provider-native sweeper, cancellation/failure classifications, sanitized evidence, and an exact maintainer activation checklist
• cross-link the proposal from the existing provider live-smoke guide; this PR adds no active workflow and no secrets

This is the design-only tier-two follow-up for #944. It builds on the hermetic lifecycle gate from #948, the secretless hosted end-to-end tier from #981, and the provider-specific live-test documentation work in #979.

Verification

$ scripts/check-docs.sh
checked 56 command docs: command surface ok
checked provider matrix: 79 providers
validated publishable Crabbox Agent Skill: 488 lines, canonical and projection identical
checked 238 markdown files: internal links ok
validated registry-ready Crabbox Zed extension: 10 tasks, 3 snippets
executed 10 Zed tasks through the Crabbox CLI boundary
built docs site: dist/docs-site
tests 14; pass 14; fail 0
normalized navigation counts across 233 pages; 79 providers

$ node scripts/check-docs-links.mjs
checked 238 markdown files: internal links ok

$ node scripts/build-docs-site.mjs
built docs site: dist/docs-site

$ git diff --check origin/main..HEAD
# clean

$ autoreview --mode local --stream-engine-output
autoreview clean: no accepted/actionable findings reported
overall: patch is correct (0.99)

No live provider proof applies: this is a documentation-only proposal, deliberately adds no active workflow, and performs no provider mutation. The generated dist/docs-site artifact was removed after validation.

Security and activation

No repository or environment secret is added or referenced by executable code. The proposal keeps all future funded credentials inside the live-smoke environment and blocks activation until dedicated provider projects, hard caps, separately scoped sweepers, destructive canary proof, shape tests, and the maintainer checklist are complete.

No changelog entry: documentation-only design proposal, as requested.

[clawsweeper]

Codex review: needs maintainer review before merge. Reviewed July 31, 2026, 11:21 AM ET / 15:21 UTC.

ClawSweeper review

What this changes

The branch adds a design-only document for a bounded hosted provider live-smoke tier and links that proposal from the existing provider live-smoke guide.

Merge readiness

⚠️ Ready for maintainer review - 4 items remain

This PR remains necessary as a maintainer-owned design decision: it documents a future funded hosted live-smoke tier but does not activate it. The supplied PR context and the prior seven review cycles identify no line-level defect, while accepting the document would still establish policy expectations for protected credentials, spend caps, scheduled reconciliation, and operational ownership; the local read-only inspection command could not run because the sandbox rejected network-namespace setup.

Priority: P3
Reviewed head: 5e78d383276c34bb50aefe942411ff7b5ffac73f
Owner decision: Required. See Decision needed.

Review scores

Measure	Result	What it means
Overall readiness	🐚 platinum hermit (4/6)	The submitted documentation is focused and has no concrete correctness finding in the supplied review context, but merge readiness depends on a maintainer policy decision rather than further contributor proof.
Proof confidence	🌊 off-meta tidepool	Not applicable: Real behavior proof is not required because this PR only changes files under docs/.
Patch quality	🐚 platinum hermit (4/6)	No actionable review findings were identified.

Verification

Check	Result	Evidence
Real behavior	Not applicable	Not applicable: Real behavior proof is not required because this PR only changes files under docs/.
Evidence reviewed	4 items	Submitted scope: The supplied PR metadata describes a documentation-only change: one new hosted-live-smoke design document and one cross-link from the existing provider live-smoke guide; it explicitly adds no workflow, secrets, or executable provider mutation. Existing review continuity: The supplied prior ClawSweeper review records seven completed cycles at the same head with no review findings and the same unresolved maintainer-policy concern: whether to accept the operational commitment implied by future funded live-smoke infrastructure. Related implementation history: The supplied related-item context shows the hermetic connector lifecycle gate was merged in commit 5b39acb, so this proposal is a separate hosted-tier policy follow-up rather than a replacement for existing secretless validation.
Findings	None	None.
Security	None	None.

How this fits together

Crabbox provider adapters are exercised through hermetic and opt-in live smoke tiers. This proposal sits above those existing checks: it defines the policy boundary that would govern any future scheduled, credentialed provider lifecycle validation and cleanup process.

flowchart LR
  A[Provider adapters] --> B[Hermetic and opt-in smoke checks]
  B --> C[Hosted live-smoke design]
  C --> D[Protected environment and credentials]
  C --> E[Spend, TTL, and concurrency limits]
  D --> F[Scheduled provider lifecycle run]
  E --> F
  F --> G[Cleanup and orphan sweeper]
  G --> H[Sanitized maintainer evidence]

Loading

Decision needed

Question	Recommendation
Should Crabbox merge this design as the accepted policy baseline for a future funded, credentialed hosted live-smoke tier, including the implied operational ownership for provider projects, budgets, cleanup, and reconciliation?	Approve the policy baseline: Merge the design as the accepted prerequisite for later implementation while keeping workflow activation separately gated by its checklist.

Why: The patch is intentionally non-executable, so its main effect is to set repository policy and signal acceptance of future operational obligations; source review cannot safely substitute for an owner’s decision to take on those obligations.

Before merge

• Resolve merge risk (P1) - Merging the design may be interpreted as committing the repository to fund provider projects, operate protected credentials, respond to failed cleanup, and maintain a scheduled sweeper before an accountable maintainer explicitly accepts those responsibilities.
• Resolve merge risk (P1) - The local review environment could not inspect the current checkout, so current-main wording and any matching internal maintainer notes could not be independently verified.
• Complete next step (P2) - A maintainer must decide whether this design should establish repository policy for future funded provider operations; no narrow code repair is appropriate.

Agent review details

Security

None.

Review metrics

Metric	Value	Why it matters
Documentation scope	2 files affected; 295 additions, 4 deletions	The branch is documentation-only but establishes a broad future operational policy surface.

Merge-risk options

Maintainer options:

1. Approve the operational boundary before merge (recommended)
   Merge only after a maintainer explicitly accepts that this documentation becomes the policy baseline for future protected credentials, budgets, cleanup, and scheduled reconciliation.
2. Pause until ownership is named
   Keep the PR open if no maintainer is ready to own the future funded-provider and orphan-recovery responsibilities described by the design.

Technical review

Best possible solution:

Have an accountable maintainer either approve this document as the repository’s future hosted-live-smoke policy or narrow it to clearly non-binding design notes; activate no workflow until the named credential, budget, cleanup, and ownership checklist is accepted.

Do we have a high-confidence way to reproduce the issue?

Not applicable: this PR proposes documentation and policy rather than reporting a runtime defect. Its stated non-activation boundary is visible in the supplied diff, but the local checkout could not be inspected.

Is this the best way to solve the issue?

Unclear: the proposed document is a coherent way to record safeguards, but whether it is the right policy baseline depends on a maintainer explicitly accepting the future funded-provider operational commitment.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against 5aa1c3983874.

Labels

Label justifications:

• P3: This is a design and documentation proposal for optional future validation infrastructure, not a current user-facing regression.
• merge-risk: 🚨 other: The non-code change can still create an ambiguous maintainer commitment around funded provider operations, protected credentials, and cleanup ownership.
• rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🌊 off-meta tidepool and patch quality is 🐚 platinum hermit.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Not applicable: Real behavior proof is not required because this PR only changes files under docs/.

Evidence

What I checked:

• Submitted scope: The supplied PR metadata describes a documentation-only change: one new hosted-live-smoke design document and one cross-link from the existing provider live-smoke guide; it explicitly adds no workflow, secrets, or executable provider mutation. (docs/features/hosted-live-smoke.md:1, 5e78d383276c)
• Existing review continuity: The supplied prior ClawSweeper review records seven completed cycles at the same head with no review findings and the same unresolved maintainer-policy concern: whether to accept the operational commitment implied by future funded live-smoke infrastructure. (5e78d383276c)
• Related implementation history: The supplied related-item context shows the hermetic connector lifecycle gate was merged in commit 5b39acb, so this proposal is a separate hosted-tier policy follow-up rather than a replacement for existing secretless validation. (5b39acb1d8d0)
• Repository inspection blocked: A read-only local inspection of AGENTS.md, current docs, VISION.md, notes, status, and HEAD did not execute because the sandbox failed before command startup with bwrap: loopback: Failed RTM_NEWADDR: Operation not permitted; this review therefore relies on the supplied PR and related-item context rather than claiming current-tree verification.

Likely related people:

• steipete: The supplied context credits this contributor with the current PR and the previously merged hermetic lifecycle gate that this proposal explicitly builds on. (role: prior hosted-tier contributor; confidence: medium; commits: 5e78d383276c, 5b39acb1d8d0; files: docs/features/hosted-live-smoke.md, docs/features/provider-live-smoke.md)
• zozo123: The supplied related history identifies this contributor as author of the merged secretless connector end-to-end smoke workflow and provider live-test documentation that define the adjacent validation boundary. (role: adjacent live-smoke contributor; confidence: medium; commits: 2d7c995e1c73, df75fa5146cb; files: docs/features/provider-live-smoke.md)

Rank-up moves

Optional improvements that raise the rating; they are not merge blockers.

• Obtain explicit maintainer acceptance or narrowing of the future credential, funding, cleanup, and scheduled-reconciliation commitment.

Rating scale

Score	Internal tier	Crab rank	Meaning
6/6	S	🦀 challenger crab	Exceptional readiness
5/6	A	🦞 diamond lobster	Very strong readiness
4/6	B	🐚 platinum hermit	Good normal PR; ordinary maintainer review
3/6	C	🦐 gold shrimp	Useful, but confidence is limited
2/6	D	🦪 silver shellfish	Proof or implementation needs work
1/6	F	🧂 unranked krab	Not merge-ready
N/A	NA	🌊 off-meta tidepool	Rating does not apply

Overall follows the weaker of proof and patch quality.
Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

Workflow

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

History

Review history (7 earlier review cycles)

• reviewed 2026-07-28T03:33:37.826Z sha 5e78d38 :: needs maintainer review before merge. :: none
• reviewed 2026-07-30T01:14:18.993Z sha 5e78d38 :: needs maintainer review before merge. :: none
• reviewed 2026-07-30T11:52:46.519Z sha 5e78d38 :: needs maintainer review before merge. :: none
• reviewed 2026-07-30T13:37:30.770Z sha 5e78d38 :: needs maintainer review before merge. :: none
• reviewed 2026-07-30T18:29:13.574Z sha 5e78d38 :: needs maintainer review before merge. :: none
• reviewed 2026-07-31T02:54:00.225Z sha 5e78d38 :: needs maintainer review before merge. :: none
• reviewed 2026-07-31T06:31:19.811Z sha 5e78d38 :: needs maintainer review before merge. :: none