feat(repair): define durable cluster intake intents

[RomneyDa]

Summary

This is 3/5 in the cluster-fixer reliability stack, based on PR 882.

• Defines the durable cluster-intake record and ledger schemas.
• Binds exact job bytes, digest, store identity, target repository, stable dispatch key, model/runner policy, and selector summary into one authenticated intent.
• Makes repeated delivery idempotent and prevents a newer store or stale replay from overwriting an already accepted cluster.
• Validates path ownership, payload size, workflow input bounds, and fail-closed policy before append.
• Adds the publication CLI and regression tests for duplicate intake, stale stores, unrelated-job preservation, and policy binding.

Validation

• pnpm run build:all
• 7 focused durable-intent publication tests
• Included in the full stack's static, lint, and regression validation

Stack

1. Candidate selection and historical dedupe
2. Durable intake queue priority
3. This PR — durable intake intent contract
4. Exactly-once dispatch and recovery
5. Workflow cutover and result publication hardening

No merge/automerge or production gate is enabled.

[clawsweeper]

Codex review: needs maintainer review before merge. Reviewed July 27, 2026, 3:19 AM ET / 07:19 UTC.

ClawSweeper review

What this changes

Adds authenticated, idempotent durable cluster-intake intents, queue publication, candidate filtering/history helpers, and regression coverage for the repair-cluster workflow.

Merge readiness

⚠️ Ready for maintainer review - 5 items remain

Keep this PR open for maintainer review. It is a MEMBER-authored, stacked durability change that defines a persistent intake contract and is a prerequisite for the open downstream dispatch and workflow-cutover PRs; GitHub currently reports the branch as dirty against current main, so it needs a clean rebase and integration review rather than cleanup closure.

Priority: P2
Reviewed head: 37025f886633344cb6e9ab085c7119464135bc5f
Owner decision: Required. See Decision needed.

Review scores

Measure	Result	What it means
Overall readiness	🦐 gold shrimp (3/6)	The PR has substantial focused coverage and green supplied checks, but its current dirty merge state and persistent-contract scope require rebased integration review before it is merge-ready.
Proof confidence	🌊 off-meta tidepool	Not applicable: This is a MEMBER-authored internal automation PR, so the external-contributor proof gate does not apply; before merge, maintainers should still require a redacted controlled durable-intake publication/materialization result after rebase.
Patch quality	🦐 gold shrimp (3/6)	No actionable review findings were identified.

Verification

Check	Result	Evidence
Real behavior	Not applicable	Not applicable: This is a MEMBER-authored internal automation PR, so the external-contributor proof gate does not apply; before merge, maintainers should still require a redacted controlled durable-intake publication/materialization result after rebase.
Evidence reviewed	5 items	Stack dependency: The PR body identifies this as layer 3 of a five-part durable cluster-intake stack; its lower dependency #882 is merged into the supplied current-main SHA, while its dispatch successor #884 and cutover successor #873 remain open. Persistent contract surface: The proposed branch introduces the intake and ledger schemas plus HMAC/digest validation in the repair lane, and expands the durable state-append queue with a cluster_intake record kind; this is a merge-sensitive state and dispatch boundary rather than a disposable patch. Focused coverage: The PR includes focused tests for intake publication idempotency, live candidate fencing, cluster-history deduplication, ranking, append-client receipts, queue migration, and coordinator fairness.
Findings	None	None.
Security	None	None.

How this fits together

The repair lane turns candidate clusters into state-backed planning jobs for OpenClaw repositories. This PR packages selected jobs into a signed intake record, appends it to the durable state queue, and leaves later materialization and dispatch to the next stack layer.

flowchart LR
  A[Gitcrawl cluster candidates] --> B[Live eligibility filter]
  B --> C[Authenticated intake intent]
  C --> D[Durable state append queue]
  D --> E[Intake ledger]
  E --> F[Exactly-once materializer]
  F --> G[Planning workflow dispatch]

Loading

Decision needed

Question	Recommendation
Should maintainers accept this durable intake contract as the next ordered layer after the merged queue-priority work, once its dirty branch has been rebased and its resulting state migration is reviewed?	Rebase and merge as stack layer 3: Resolve the current merge state, revalidate the migration and publication path, then land this contract before the dependent dispatch and cutover layers.

Why: The PR creates persistent state and signed dispatch-policy boundaries, and its downstream stack depends on the exact contract; deciding whether that contract is the repository’s intended long-term repair-lane interface requires maintainer judgment.

Before merge

• Resolve merge risk (P1) - GitHub currently reports the branch dirty against current main; resolving the stacked-base conflict can change the effective migration and queue behavior, so the rebased result needs focused validation before merge.
• Resolve merge risk (P1) - This PR introduces a durable intake/ledger format and cryptographic policy binding. A compatibility error could leave existing queue rows unreadable or make valid repair intake fail closed.
• Resolve merge risk (P1) - The contract is useful only when integrated in order with the open exactly-once dispatch and workflow-cutover layers, so isolated green checks do not prove the complete production lifecycle.
• Complete next step (P2) - Maintainer review is required because this MEMBER-authored PR introduces a durable signed state contract and currently needs a clean rebase before its effective merge result can be approved.

Agent review details

Security

None.

Review metrics

Metric	Value	Why it matters
Change surface	18 files affected; 2,413 added, 97 removed	The PR spans durable queue schema, repair CLI, selection helpers, and regression suites, so reviewing only the new CLI would miss state-contract effects.
Stack position	3 of 5 layers	Two prerequisite layers are merged, while two downstream layers remain open and depend on this contract.

Merge-risk options

Maintainer options:

1. Rebase and validate the durable migration (recommended)
   Resolve the dirty merge state, verify existing queue rows retain their retry history, and run the focused intake/queue regression suites on the rebased head.
2. Accept the new contract explicitly
   Merge after maintainers accept the intake ledger, runner/model binding, and fail-closed policy as the intended durable repair-lane contract.
3. Pause the stack
   Defer this layer and its dependent PRs if maintainers do not want to commit to the persistent intake format yet.

Technical review

Best possible solution:

Rebase this layer cleanly onto current main, preserve compatibility with existing durable queue rows, then merge it before the dependent dispatch and workflow-cutover PRs with a controlled end-to-end durable-intake exercise.

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

Not applicable as a feature/infrastructure PR: the relevant validation is a controlled durable-intake publication and materialization run rather than reproduction of a pre-existing user bug.

Is this the best way to solve the issue?

Unclear until the dirty branch is rebased. The durable-intent approach is coherent with the merged queue-priority layer, but maintainers must confirm the persistent schema and policy contract before the dependent stack lands.

AGENTS.md: found and applied where relevant.

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

Labels

Label changes:

• add merge-risk: 🚨 compatibility: The PR changes durable append and ledger schemas that must continue to preserve existing state rows through upgrades.
• add merge-risk: 🚨 security-boundary: The new intent binds job bytes and runner/model policy through authenticated validation, making any contract mistake security-relevant.
• add merge-risk: 🚨 availability: Intake publication and queue coordination sit on the path that creates repair work, so an integration error can stall or prevent dispatch.

Label justifications:

• P2: This is a bounded but merge-sensitive repair-automation improvement, not an active user-facing outage.
• merge-risk: 🚨 compatibility: The PR changes durable append and ledger schemas that must continue to preserve existing state rows through upgrades.
• merge-risk: 🚨 availability: Intake publication and queue coordination sit on the path that creates repair work, so an integration error can stall or prevent dispatch.
• merge-risk: 🚨 security-boundary: The new intent binds job bytes and runner/model policy through authenticated validation, making any contract mistake security-relevant.
• rating: 🦐 gold shrimp: Overall readiness is 🦐 gold shrimp; proof is 🌊 off-meta tidepool and patch quality is 🦐 gold shrimp.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Not applicable: This is a MEMBER-authored internal automation PR, so the external-contributor proof gate does not apply; before merge, maintainers should still require a redacted controlled durable-intake publication/materialization result after rebase.

Evidence

What I checked:

• Stack dependency: The PR body identifies this as layer 3 of a five-part durable cluster-intake stack; its lower dependency feat(state): prioritize durable cluster intake #882 is merged into the supplied current-main SHA, while its dispatch successor feat(repair): dispatch durable cluster jobs exactly once #884 and cutover successor fix(repair): cut over durable cluster intake publication #873 remain open. (src/repair/cluster-intake-state.ts, 37025f886633)
• Persistent contract surface: The proposed branch introduces the intake and ledger schemas plus HMAC/digest validation in the repair lane, and expands the durable state-append queue with a cluster_intake record kind; this is a merge-sensitive state and dispatch boundary rather than a disposable patch. (src/repair/cluster-intake-state.ts, 37025f886633)
• Focused coverage: The PR includes focused tests for intake publication idempotency, live candidate fencing, cluster-history deduplication, ranking, append-client receipts, queue migration, and coordinator fairness. (test/repair/publish-cluster-intake.test.ts, 37025f886633)
• Merge status: Supplied pull-request metadata reports mergeable: false and mergeableState: dirty against current main at 390d521, so the reviewed head is not presently landable without rebase/conflict resolution. (390d52176b82)
• Current-area provenance: RomneyDa authored the candidate commit and the immediately preceding merged stack layers: fix(repair): rank cluster candidates for landable bugs #881 merged as d1c837e and feat(state): prioritize durable cluster intake #882 merged as current main commit 390d521. (src/repair/state-writer-coordinator.ts, 390d52176b82)

Likely related people:

• RomneyDa: Authored the proposed durable-intake contract and the two preceding merged layers that established candidate selection and queue priority. (role: recent repair-lane contributor; confidence: high; commits: d1c837ea2f63, 390d52176b82, 37025f886633; files: src/repair/cluster-intake-state.ts, src/repair/state-append-client.ts, dashboard/state-writer-coordinator.ts)

Rank-up moves

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

• Rebase onto current main and resolve the reported dirty merge state.
• Run the focused queue migration, intake publication, and candidate-filtering suites on the resulting head.
• Capture a redacted controlled append-to-materialization result before landing the dependent stack layers.

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 (1 earlier review cycle)

• reviewed 2026-07-27T04:56:39.049Z sha 37025f8 :: needs maintainer review before merge. :: none

[clawsweeper]

ClawSweeper status: review started.

I am starting a fresh review of this pull request: feat(repair): define durable cluster intake intents This is item 1/1 in the current shard. Shard 0/1.

This placeholder means the worker is alive and reading the current context. I will edit this same comment with the actual review when the claws are done clicking.

Crustacean status: shell secured, claws on keyboard, evidence pebbles being sorted.