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: found issues before merge. Reviewed August 8, 2026, 9:43 PM ET / August 9, 2026, 01:43 UTC.

ClawSweeper review

What this changes

The PR adds a design for a budget-bounded DigitalOcean and Scaleway hosted live-smoke tier and links it from the existing provider live-smoke guide.

Merge readiness

⚠️ Ready for maintainer review - 7 items remain

Keep open: this is a useful bounded hosted-smoke design, but its unchanged sweeper policy conflicts with Crabbox’s durable-claim deletion contract and needs a security/operations decision before it can become repository guidance.

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

Review scores

Measure	Result	What it means
Overall readiness	🦐 gold shrimp (3/6)	The proposal is detailed and bounded, but a material lifecycle-safety conflict blocks it from being a merge-ready policy document.
Proof confidence	🌊 off-meta tidepool	Not applicable: Real behavior proof is not required because this PR only changes files under docs/.
Patch quality	🦐 gold shrimp (3/6)	Security review found an item that needs attention.

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	5 items	Sweeper deletion policy: The proposal says the independent sweeper must not depend on a local Crabbox claim, while allowing deletion from complete provider metadata and project checks. Current deletion contract: Current main requires DigitalOcean and Scaleway deletion to have canonical ownership tags and an exact local claim for the same provider scope and resource. Vision safety boundary: VISION.md requires destructive operations to verify ownership bound to the exact provider, resource, and claim.
Findings	4 actionable findings	[P1] Require a durable claim before sweeper deletion [P3] Move repository chronology out of generic docs [P3] Make the trusted-repository guard configurable
Security	Needs attention	Sweeper lacks a durable ownership claim: The proposed independent sweeper may delete provider resources after cancellation using metadata and project checks while expressly excluding a Crabbox claim, contrary to the current claim-gated deletion contract.

How this fits together

Provider live-smoke documentation defines how Crabbox adapters are validated from hermetic tests through opt-in real-provider checks. This proposal would govern a future scheduled credentialed tier that creates provider resources and must safely clean them up.

flowchart TD
A[Provider adapter] --> B[Guarded live smoke]
B --> C[Hosted smoke policy]
C --> D[Protected trigger and credentials]
D --> E[Provider resource]
E --> F[Cleanup job]
C --> G[Durable ownership claim]
G --> F
F --> H[Independent sweeper]

Loading

Decision needed

Question	Recommendation
Should Crabbox sponsor a scheduled hosted smoke tier only if its independent sweeper verifies a cancellation-surviving durable claim bound to the exact provider, project, and resource?	Require durable claims before activation: Revise the proposal to preserve the claim boundary through cancellation and defer workflow activation until that design is approved.

Why: The claim store and operational ownership of a funded destructive sweeper are security and operations policy choices that the documentation cannot safely infer.

Before merge

• Require a durable claim before sweeper deletion (P1) - Late finding on unchanged content: the proposal says the sweeper must not depend on a Crabbox claim, yet current main and VISION.md require an exact provider/resource claim for destructive cleanup. Specify a cancellation-surviving durable claim and require it before any deletion.
• Move repository chronology out of generic docs (P3) - Late finding on unchanged content: this new feature document embeds repository-specific PR chronology, contrary to the repository policy for neutral documentation. Keep the reusable tier description here and move historical references to release or issue context.
• Make the trusted-repository guard configurable (P3) - Late finding on unchanged content: a literal repository name makes the proposed workflow guidance repository-specific. Describe a fixed maintainer-configured trusted repository value instead, and keep it independent of dispatch input.
• Derive ownership metadata from runtime context (P3) - Late finding on unchanged content: the static repository value and passed-in run identity invite copied or caller-controlled metadata. Require adapters or runners to derive the repository and run identity from trusted runtime context when creating the resource.
• Resolve security concern: Sweeper lacks a durable ownership claim - The proposed independent sweeper may delete provider resources after cancellation using metadata and project checks while expressly excluding a Crabbox claim, contrary to the current claim-gated deletion contract.
• Resolve merge risk (P1) - As written, a cancellation-surviving sweeper could delete resources from tags and project membership without the exact durable claim required by current lifecycle safety policy.

Findings

• [P1] Require a durable claim before sweeper deletion — docs/features/hosted-live-smoke.md:168-172
• [P3] Move repository chronology out of generic docs — docs/features/hosted-live-smoke.md:6-13
• [P3] Make the trusted-repository guard configurable — docs/features/hosted-live-smoke.md:65-66
• [high] Sweeper lacks a durable ownership claim — docs/features/hosted-live-smoke.md:168

Agent review details

Security

Needs attention: The documentation introduces a future destructive-sweeper policy that lacks the durable claim required by the repository’s ownership boundary.

Review metrics

Metric	Value	Why it matters
Documentation surface	289 added, 10 changed lines across 2 documentation files	The prose establishes future policy for credentialed scheduled resource creation and deletion despite adding no executable workflow.

Merge-risk options

Maintainer options:

1. Restore claim-gated cleanup (recommended)
   Require a durable, cancellation-surviving claim check before the future sweeper may delete any provider resource.
2. Pause the hosted policy
   Keep the existing guide’s statement that hosted live smoke awaits separate policy rather than merging an unsafe deletion model.

Technical review

Best possible solution:

Revise the design to require a cancellation-surviving durable claim bound to the exact provider, project, and resource before any sweeper deletion, then obtain explicit approval for the funded operational tier.

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

Not applicable: this is a documentation-only proposal; current-source comparison nevertheless confirms that its proposed deletion rule conflicts with the existing claim-gated contract.

Is this the best way to solve the issue?

No. A durable claim that survives runner cancellation is needed before provider tags and project membership can authorize destructive sweeping.

Full review comments:

• [P1] Require a durable claim before sweeper deletion — docs/features/hosted-live-smoke.md:168-172
  Late finding on unchanged content: the proposal says the sweeper must not depend on a Crabbox claim, yet current main and VISION.md require an exact provider/resource claim for destructive cleanup. Specify a cancellation-surviving durable claim and require it before any deletion.
  Confidence: 0.99
  Late finding: first raised on code an earlier review cycle already covered.
• [P3] Move repository chronology out of generic docs — docs/features/hosted-live-smoke.md:6-13
  Late finding on unchanged content: this new feature document embeds repository-specific PR chronology, contrary to the repository policy for neutral documentation. Keep the reusable tier description here and move historical references to release or issue context.
  Confidence: 0.97
  Late finding: first raised on code an earlier review cycle already covered.
• [P3] Make the trusted-repository guard configurable — docs/features/hosted-live-smoke.md:65-66
  Late finding on unchanged content: a literal repository name makes the proposed workflow guidance repository-specific. Describe a fixed maintainer-configured trusted repository value instead, and keep it independent of dispatch input.
  Confidence: 0.95
  Late finding: first raised on code an earlier review cycle already covered.
• [P3] Derive ownership metadata from runtime context — docs/features/hosted-live-smoke.md:134-142
  Late finding on unchanged content: the static repository value and passed-in run identity invite copied or caller-controlled metadata. Require adapters or runners to derive the repository and run identity from trusted runtime context when creating the resource.
  Confidence: 0.93
  Late finding: first raised on code an earlier review cycle already covered.

Overall correctness: patch is incorrect
Overall confidence: 0.98

AGENTS.md: found and applied where relevant.

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

Labels

Label changes:

• add rating: 🦐 gold shrimp: Overall readiness is 🦐 gold shrimp; proof is 🌊 off-meta tidepool and patch quality is 🦐 gold shrimp.
• remove rating: 🦪 silver shellfish: Current PR rating is rating: 🦐 gold shrimp, so this older rating label is no longer current.

Label justifications:

• P2: The design concerns a future funded lifecycle tier with meaningful but not currently active security and operational impact.
• merge-risk: 🚨 security-boundary: Its proposed sweeper deletion rule omits the durable ownership claim required by current lifecycle safety policy.
• rating: 🦐 gold shrimp: Overall readiness is 🦐 gold shrimp; proof is 🌊 off-meta tidepool and patch quality is 🦐 gold shrimp.
• status: ⏳ waiting on author: ClawSweeper has contributor-facing work open and is waiting for author action. Not applicable: Real behavior proof is not required because this PR only changes files under docs/.

Evidence

Security concerns:

• [high] Sweeper lacks a durable ownership claim — docs/features/hosted-live-smoke.md:168
  The proposed independent sweeper may delete provider resources after cancellation using metadata and project checks while expressly excluding a Crabbox claim, contrary to the current claim-gated deletion contract.
  Confidence: 0.99

What I checked:

• Sweeper deletion policy: The proposal says the independent sweeper must not depend on a local Crabbox claim, while allowing deletion from complete provider metadata and project checks. (docs/features/hosted-live-smoke.md:168, 5e78d383276c)
• Current deletion contract: Current main requires DigitalOcean and Scaleway deletion to have canonical ownership tags and an exact local claim for the same provider scope and resource. (docs/commands/stop.md:123, ce9487f55205)
• Vision safety boundary: VISION.md requires destructive operations to verify ownership bound to the exact provider, resource, and claim. (VISION.md:6, ce9487f55205)
• Unchanged prior-review content: The current PR head is the same SHA reviewed previously; the prior sweep/neutrality findings remain visible on unchanged added documentation. (docs/features/hosted-live-smoke.md:168, 5e78d383276c)
• Existing guide provenance: The current live-smoke validation tiers and claim-retention guidance date to this current-main commit. (docs/features/provider-live-smoke.md:17, 1f2bb8bdd234)

Likely related people:

• Patrick Erichsen: Blame attributes the current validation-tier and claim-retention guidance to this commit. (role: recent live-smoke guide contributor; confidence: high; commits: 1f2bb8bdd234; files: docs/features/provider-live-smoke.md)
• steipete: Authored the merged lifecycle-tier foundation that this proposal extends. (role: introduced merged hermetic lifecycle tier; confidence: medium; commits: 5b39acb1d8d0; files: docs/features/provider-live-smoke.md)

Rank-up moves

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

• Define a cancellation-surviving durable claim and make it mandatory for sweeper deletion.
• Remove repository-specific narrative and derive future ownership metadata from trusted runtime context.
• Obtain maintainer approval for the funded credential and sweeper operating model.

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 (58 earlier review cycles; latest 8 shown)

• reviewed 2026-08-08T01:29:51.512Z sha 5e78d38 :: needs changes before merge. :: [P3] Remove repository-specific workflow chronology | [P3] Parameterize the trusted-repository guard | [P3] Derive ownership metadata from runtime identity
• reviewed 2026-08-08T06:23:30.997Z sha 5e78d38 :: needs changes before merge. :: [P3] Remove repository-specific workflow chronology | [P3] Parameterize the trusted-repository guard | [P3] Derive ownership metadata from runtime identity
• reviewed 2026-08-08T08:10:30.626Z sha 5e78d38 :: found issues before merge. :: [P3] Remove repository-specific workflow chronology | [P3] Parameterize the trusted-repository guard | [P3] Derive ownership metadata from runtime identity
• reviewed 2026-08-08T14:06:21.032Z sha 5e78d38 :: found issues before merge. :: [P3] Remove repository-specific workflow chronology | [P3] Parameterize the trusted-repository guard | [P3] Derive ownership metadata from runtime identity
• reviewed 2026-08-08T17:23:33.158Z sha 5e78d38 :: needs changes before merge. :: [P3] Remove repository-specific workflow chronology | [P3] Parameterize the trusted-repository guard | [P3] Derive ownership metadata from runtime identity
• reviewed 2026-08-08T19:16:35.910Z sha 5e78d38 :: found issues before merge. :: [P3] Remove repository-specific workflow chronology | [P3] Parameterize the trusted-repository guard | [P3] Derive ownership metadata from runtime identity
• reviewed 2026-08-08T20:46:25.556Z sha 5e78d38 :: found issues before merge. :: [P3] Remove repository-specific workflow chronology | [P3] Parameterize the trusted-repository guard | [P3] Derive ownership metadata from runtime identity
• reviewed 2026-08-08T22:43:23.478Z sha 5e78d38 :: found issues before merge. :: [P1] Require a durable ownership claim for sweeper deletes | [P3] Remove repository-specific workflow chronology | [P3] Parameterize the trusted-repository guard | [P3] Derive ownership metadata from runtime identity