fix(review): publish exact merge readiness state

[vincentkoc]

Related: openclaw/openclaw#120232

What Problem This Solves

Resolves a problem where a durable ClawSweeper review could expose contradictory
merge guidance: visible risks, findings, proof gaps, or required actions remained
in the review body while machine-readable automation state reported the exact
head as ready.

Publication recovery could also leave an older ready verdict authoritative after
a fail-closed fallback, adopt an unverified comment mutation, or clean up
competing bot comments before the active lease owner had established the
canonical durable review.

Why This Change Was Made

ClawSweeper now derives visible before-merge guidance and machine-readable state
from one normalized readiness result. Every valid generated review contains one
versioned exact-head state marker:

<!-- clawsweeper-review-state:<ready|blocked|needs-changes> item=<n> sha=<40hex> v=1 -->

The existing clawsweeper-review-version marker remains the durable identity.
Repair routing uses the structured work_candidate field; independent guidance
is accepted as ready only when it is one bounded gate-only sentence. Missing,
negative, multi-sentence, targeted-validation, unrelated-CI, or otherwise
non-routine guidance fails closed.

Durable publication verifies the exact mutation identity and body. Oversized or
malformed output publishes a bounded blocked fallback, preserves its causal veto
over older ready comments, and requires a complete v1 review from a newer lease
before ready state can supersede it. After the fallback is patched, canonical
selection keeps using monotonic lease identity rather than client timestamps, so
an older lease with a later clock value cannot retake authority. Generic
publication no longer owns competing-comment deletion; the active lease
lifecycle owns cleanup after durable publication is verified.

This is one owner-boundary repair across readiness normalization, durable review
identity, publication, and lease cleanup. It does not change config, persistence,
SQLite, the dashboard status contract, or OpenClaw product behavior.

User Impact

Maintainers and downstream consumers such as Clownfish can distinguish
ready, blocked, and needs-changes for one exact item and head without
parsing human prose. A visible blocker cannot coexist with hidden ready state,
and stale workers cannot erase or overwrite the fail-closed publication barrier.

There is no end-user OpenClaw behavior change.

Compatibility And Automation Decisions

v1 marker commitment

Owner decision: adopt the v1 marker as a supported additive producer
contract.

• Consumers may rely on the exact state, item, sha, and v=1 fields only
  when the paired durable review identity has the same exact head, a valid
  review time, a non-sentinel lease owner, and a positive lease comment ID.
• Readers must ignore unknown future versions or states and fail closed when a
  required v1 field or paired identity is missing or invalid.
• Additive metadata may be introduced without changing v1 readers.
• An incompatible semantic or grammar change requires a new marker version,
  coordinated consumer support, and a documented deprecation path before v1 is
  removed.
• The marker is advisory input to normal exact-head, checks, mergeability, and
  policy gates; it is never standalone merge authority.

publication recovery and cleanup

Owner decision: accept the lease-owned recovery model.

• One verified durable exact-head review is canonical.
• An identity-less blocked fallback vetoes older ready state until a fresh,
  newer lease publishes a complete v1 durable review.
• Canonical review ordering follows the monotonic lease comment ID; timestamps
  are tie-breakers only after causal lease identity agrees.
• Only the active lease owner cleans competing ClawSweeper comments after the
  canonical publication is verified.
• Contributor-owned comments are never adopted or deleted by this recovery
  path.

These decisions resolve the previous compatibility and automation merge-risk
questions and the applicable Rank-up move to record the v1 evolution policy.

Evidence

Exact range and LOC

• Base: 36179dceb26fbeca33d8a863746b4cf83e325e09
• Exact head: 85abed7ee41f940699832c2b1374493d5d0e677d
• Exact tree: 9bb9602e06c348b58d0112703212d8eb7cedbff9
• Frozen range SHA-256:
  7187d2c27f2689adffa09efe746557a4892f7c3218bbd1999db6cf3c63a966bb
• Full 793-file source manifest SHA-256:
  e7dc0592ad7664e0a6aa0a133cdb2c4801a51c3c14e783cf9ecad5d516249915
• Latest signed exact-head commit:
  fix(review): preserve causal fallback authority
• Total: 33 files, +3023/-553

Classification	Files	Additions	Deletions
Production (src/**)	18	1007	359
Model-visible prompt	1	14	0
Contract generator tooling	1	189	0
Tests	12	1749	194
Generated contract fixture	1	64	0

The positive production delta implements the versioned readiness contract,
verified publication identity, fail-closed causal barrier, and lease-owned
cleanup boundary. The branch removes duplicate presentation and generic cleanup
paths, and its test/tooling coverage is larger than the production change.

Focused validation and review

• All three TypeScript projects built successfully at the exact head.
• 110 focused tests passed:
  • readiness contract: 21
  • durable publication: 7
  • review rendering/lifecycle: 35
  • proof and repair routing: 24
  • security and merge-risk routing: 22
  • prompt contract: 1
• Generated v1 fixture SHA-256:
  9f99287118f93a22bbd067f1c9834cd83761becd13ab97db5c1568f296e1ce87
• Precommit Codex autoreview: no P0 findings.
  • text SHA-256:
    65b6795bdbad7a436f4bca32c3a21ffab0c8fd10c65ede0721c2a70e23b49df9
  • JSON SHA-256:
    9d921092d2be9435d887e3c7536772655932a1166186496b8ef2b359c479e005
• Committed-branch Codex autoreview against the exact base: no P0 findings.
  • text SHA-256:
    df1c095253bdf6a236baa6c0291ed79e8c202e1c418da913433af0d1204d48de
  • JSON SHA-256:
    ba647e9c85ecc6561e83d2281a4422ea0c062ee5babd9229b6536f6b7d8042fe
• Formatting and frozen-range git diff --check passed.
• Exact-head hosted CI is required after this head is pushed; older green checks
  are not treated as current evidence.

Prior finding and Rank-up disposition

• False-ready imperative guidance: resolved by the exact-head commit.
  work_candidate is authoritative for repair routing, while only an explicit
  allowlist of gate-only sentences can remain ready. Table-driven regressions
  cover routine gates, imperative remediation, negative CI, targeted
  validation, unrelated CI, missing guidance, findings, proof gaps, and
  security routing.
• Incomplete successor cleared the fallback veto: resolved. A successor
  must contain one supported v1 state marker paired with one durable version
  marker for the same exact head, plus a valid timestamp, lease owner, and
  positive lease comment ID. Missing state, unsupported state, malformed or
  mismatched head, and sentinel ownership all remain fail-closed.
• Timestamp ordering could retake authority after fallback replacement:
  resolved. Canonical selection now ranks complete reviews by monotonic lease
  comment ID before timestamp tie-breakers. Regression and live GitHub-client
  proof cover an older lease carrying a later timestamp.
• Mixed-format risk text could drop actionable continuation lines: resolved.
  Risk entries now preserve bullet and continuation prose before routine/action
  classification; the regression remains blocked and visible.
• v1 compatibility/evolution commitment: resolved in
  v1 marker commitment.
• Publication recovery and cleanup acceptance: resolved in
  publication recovery and cleanup.
• Stale detector/classifier scope claim: removed. This branch does not claim
  to change src/clawsweeper-change-detection.ts.
• OpenClaw Bay evidence: recorded below.

Real Behavior Proof

Local isolated producer and lifecycle proof

Claim: Durable review rendering emits one exact-head readiness state
consistent with visible guidance, fails closed for unresolved structured or
prose guidance, preserves security/proof/typed-finding blockers, verifies
publication identity, enforces the causal fallback barrier, and exposes a
producer-generated v1 fixture.

Exercised surface: Compiled readiness normalization, review rendering,
automation markers, repair/proof/security routing, durable publication, lease
lifecycle, prompt contract, and fixture generator.

Scenario or fixture:

• queue_fix_pr routes repair without reason-text parsing;
• routine whole-sentence CI/review gates remain ready;
• non-routine, missing, negative, multi-sentence, targeted-validation, and
  unrelated-CI guidance fail closed;
• findings emit needs-changes, while blocked queue/security states emit no
  repair marker;
• proof gaps block pass and repair markers;
• opted-in security repair and unopted security review remain distinct;
• malformed or oversized publication produces a bounded blocked fallback;
• incomplete or malformed higher-lease successors cannot clear that fallback;
• older and stale ready comments remain vetoed until a complete fresh review;
• an older lease with a later timestamp cannot retake canonical authority;
• mixed-format risk continuation text remains visible and blocks readiness;
• generic cleanup is deferred to lease ownership;
• the generated fixture is byte-identical to the checked-in contract.

Command and environment: Docker-backed Crabbox local-container, lease
cbx_dedbbf57f57a, Colima Linux arm64, node:24-bookworm, Node v24.18.1,
pnpm 11.10.0, 3 CPUs, 6 GiB memory, 30-minute TTL, bridge networking. The run
installed from the frozen lockfile, built all three TypeScript projects, ran
the 110 focused tests, regenerated the v1 fixture, and compared exact bytes.

Observable result: 110/110 focused tests passed. Every asserted readiness,
publication, routing, security, prompt, and lifecycle observation is true. The
source manifest, head, tree, base, and frozen range match the values above.

Artifact or trace:

• Retained artifact:
  .crabbox/runs/cbx_dedbbf57f57a/cbx_dedbbf57f57a-artifacts.tgz
• Artifact SHA-256:
  93ffb0eaed22b818013654b2e03ff8765769f89896a8ee5fe6e89882765bc562
• Proof JSON:
  .artifacts/clawsweeper-1059-85abed7e-local-container-proof.json
• Proof JSON SHA-256:
  e9af38b7ad835ea012758f38188bf19e039e8a3762c9bdfc6bad3fb68ccc30ce
• Proof script SHA-256:
  16d30dbb61acbe2a7ad7d73b5d476e3624b39e8f1f3226a02d66f8bd004c0799
• Run log SHA-256:
  61f78f9b6772a907288a4d68474bbdc94c6fb665e811edfe8cf17fc774218e89

Lease and release: Crabbox reported leaseStopped: true; the local-container
lease list is empty and the container ID is absent.

Limits: This proves the producer and durable lifecycle in isolated Linux.
It does not replace hosted CI or downstream Clownfish integration proof.

Production GitHub-client proof

Claim: The compiled production GitHub client preserves exact identity and
causal recovery semantics against real GitHub comment create, read, patch, and
delete operations.

Exercised surface: createGitHubRuntime, createGitHubExecution,
createReviewCommentIdentity, createReviewCommentAutomation,
createReviewCommentState, and createReviewCommentPublication.

Scenario: Nonce-tagged disposable comments on this PR exercised offset
timestamp canonicalization and parser round-trip, same-head bounded fallback
reuse, wrong-head and conflicting-timestamp rejection, identity-less fallback
POST, older/stale ready vetoes, stale overwrite rejection, rejection of an
incomplete higher-lease successor, valid fresh-lease PATCH recovery, rejection
of a later timestamp from an older lease, server readback, and cleanup.

Observable result: Every production-client observation is true. The bounded
fallbacks were 1,231 and 807 bytes, wrong-head/oversized metadata was absent,
the incomplete successor left the fallback unchanged, the complete fresh review
won despite the older lease's later timestamp, and every disposable comment
deletion was verified by a follow-up 404.

Artifact or trace:

• Proof JSON SHA-256:
  814408a1061953c1c98f99b4a033220979315a18026c00fa3c79d1f16b25fd8b
• Proof script SHA-256:
  80ca83116882c38a0ed61336e0a11798b4457f9088e7d87dcb57c4a945a03a25
• Run log SHA-256:
  062592001b5718f66c210ebfb9b245f8041a3b2de089e3754ecdc9fe9889fdba
• Cleanup audit: a fresh GitHub API read returned zero
  clawsweeper-production-client-proof comments.

Limits: This was a narrow production API proof against disposable comments
on #1059. It did not alter the
durable ClawSweeper review comment, labels,
branch, checks, readiness, or merge state.

OpenClaw Bay impact

OpenClaw Bay is unaffected:

• the range has no dashboard/** changes;
• Bay remains an observer-only /api/status surface;
• the v1 marker is produced and consumed by durable review-comment paths, not
  the Bay status contract;
• no queue, workflow, recovery, deploy, rollback, or mutation control is added
  to Bay.

Release Notes

No CHANGELOG.md entry is included. ClawSweeper's normal repair workflow keeps
release-note context in the PR body and commit history; changelog changes are
release-owned.

[clawsweeper]

Codex review: needs changes before merge. Reviewed August 29, 2026, 3:50 PM ET / 19:50 UTC.

ClawSweeper review

What this changes

Adds an exact-head readiness marker and hardens ClawSweeper’s durable review-comment publication, recovery ordering, and lease ownership.

Regression provenance

Possible regression — suspected (reviewed change). No predecessor PR is attributed.

Merge readiness

⚠️ Ready for maintainer review - 3 items remain

Keep open: the prior P2 apply-batch blocker remains on the unchanged head, and this MEMBER-authored PR is not eligible for automated cleanup.

Priority: P2
Reviewed head: 85abed7ee41f940699832c2b1374493d5d0e677d

Review scores

Measure	Result	What it means
Overall readiness	🦐 gold shrimp (3/6)	The branch has substantial focused coverage and a concrete remaining P2 apply-flow defect.
Proof confidence	🌊 off-meta tidepool	Not applicable: Not applicable as a MEMBER-authored PR under the contributor proof gate; the supplied body nevertheless describes production GitHub-comment lifecycle evidence, while the remaining concern is an untested apply-batch continuation path.
Patch quality	🦐 gold shrimp (3/6)	1 actionable review finding remain.

Verification

Check	Result	Evidence
Real behavior	Not applicable	Not applicable: Not applicable as a MEMBER-authored PR under the contributor proof gate; the supplied body nevertheless describes production GitHub-comment lifecycle evidence, while the remaining concern is an untested apply-batch continuation path.
Evidence reviewed	6 items	Verified fallback throws a distinct error: After a bounded blocked fallback is successfully found or written for an oversized review, publication throws DurableReviewPublicationBlockedError instead of returning the synced comment. Apply loop rethrows the published-fallback error: The introduced catch branch rethrows the special error rather than recording a terminal skip and continuing the selected-item loop. Outer command terminates on non-budget errors: The apply command’s outer handler calls its failure hook and rethrows all errors except runtime-budget yields, so the special error aborts the batch.
Findings	1 actionable finding	[P2] Record a published fallback as a terminal item skip
Security	None	None.

How this fits together

ClawSweeper renders a durable GitHub review comment from a report, then its apply lane publishes that comment and continues through selected repository items. The new readiness state is consumed by review presentation and repair/automerge gating.

flowchart LR
  A[Review report] --> B[Readiness normalization]
  B --> C[Durable comment rendering]
  C --> D[GitHub publication]
  D --> E[Apply decision batch]
  E --> F[Later selected items]
  D --> G[Blocked fallback comment]

Loading

Before merge

• Record a published fallback as a terminal item skip (P2) - A verified oversized-comment fallback reaches this branch after the durable blocked comment is already published, but rethrowing it escapes the apply loop and aborts all later selected items. Record the fallback as a per-item skip and continue; this concern was also visible on the unchanged prior reviewed head.
• Resolve merge risk (P2) - An oversized durable review can successfully publish its blocked fallback but still terminate the entire apply invocation, leaving later selected records unprocessed until another run.
• Complete next step (P2) - A narrow source-proven apply-loop repair and focused continuation regression test are available.

Findings

• [P2] Record a published fallback as a terminal item skip — src/clawsweeper-apply-decision-workflow.ts:1910-1912

Agent review details

Security

None.

Review metrics

Metric	Value	Why it matters
Changed surface	33 files, +3023/-553	The readiness and publication change spans the renderer, state selection, apply workflow, and focused tests.
Production versus tests	production +1007/-359; tests +1749/-194	The added test volume is substantial, but it does not cover apply-batch continuation after the special publication error.

Merge-risk options

Maintainer options:

1. Continue after a verified fallback (recommended)
   Handle the published fallback as a per-item terminal skip and add an apply-batch regression test proving a later item still runs.
2. Pause this branch
   Keep the branch draft if batch-wide termination after a successful fallback is not acceptable for the apply lane.

Copy recommended automerge instruction

@clawsweeper automerge

Special instructions:
Record a verified blocked fallback as a terminal item skip, release the active lease, and continue the selected-item batch; add focused continuation coverage.

Technical review

Best possible solution:

Publish the blocked fallback, record this item as a terminal publication skip, release its lease, and continue processing later selected records.

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

Yes, by source: make a rendered durable comment exceed 60 KiB during an apply batch with a later selected item; the verified fallback throws through the command wrapper before that item is processed.

Is this the best way to solve the issue?

No: the fallback must remain fail-closed for its own item, but the apply workflow should persist a terminal skip and continue the batch rather than rethrowing it.

Full review comments:

• [P2] Record a published fallback as a terminal item skip — src/clawsweeper-apply-decision-workflow.ts:1910-1912
  A verified oversized-comment fallback reaches this branch after the durable blocked comment is already published, but rethrowing it escapes the apply loop and aborts all later selected items. Record the fallback as a per-item skip and continue; this concern was also visible on the unchanged prior reviewed head.
  Confidence: 0.99
  Late finding: first raised on code an earlier review cycle already covered.

Overall correctness: patch is incorrect
Overall confidence: 0.99

AGENTS.md: found and applied where relevant.

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

Labels

Label justifications:

• P2: A bounded fallback case can abort an apply batch, affecting automation throughput without an immediate end-user outage.
• merge-risk: 🚨 automation: The introduced error path stops the apply command after a successful fallback publication, preventing later selected automation work.
• 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: Not applicable as a MEMBER-authored PR under the contributor proof gate; the supplied body nevertheless describes production GitHub-comment lifecycle evidence, while the remaining concern is an untested apply-batch continuation path.

Evidence

Acceptance criteria:

• [P2] Run the narrow apply-decision regression test covering fallback publication and next-item continuation.
• [P1] Run pnpm run check on Node 24 or newer.

What I checked:

• Verified fallback throws a distinct error: After a bounded blocked fallback is successfully found or written for an oversized review, publication throws DurableReviewPublicationBlockedError instead of returning the synced comment. (src/clawsweeper-review-comment-publication.ts:426, 85abed7ee41f)
• Apply loop rethrows the published-fallback error: The introduced catch branch rethrows the special error rather than recording a terminal skip and continuing the selected-item loop. (src/clawsweeper-apply-decision-workflow.ts:1910, 85abed7ee41f)
• Outer command terminates on non-budget errors: The apply command’s outer handler calls its failure hook and rethrows all errors except runtime-budget yields, so the special error aborts the batch. (src/clawsweeper-command-operations.ts:567, 85abed7ee41f)
• Existing coverage stops at publication: The added publication test verifies that the special error is thrown after fallback publication, but does not exercise apply-loop continuation to a later selected item. (test/review-comment-publication.test.ts:202, 85abed7ee41f)
• Prior finding remains unchanged: The current checkout is the same 85abed7 head reviewed on August 22; no newer patch changes the affected apply workflow path. (src/clawsweeper-apply-decision-workflow.ts:1910, 85abed7ee41f)
• Current main-area ownership: The base-branch history shows Peter Steinberger’s recent apply-workflow maintenance in commit 5bfa2d9. (src/clawsweeper-apply-decision-workflow.ts:1910, 5bfa2d9f256d)

Likely related people:

• Peter Steinberger: Recent main-branch history includes apply-workflow maintenance around batching and coalescing races. (role: recent area contributor; confidence: high; commits: 5bfa2d9f256d, 480d56953f38; files: src/clawsweeper-apply-decision-workflow.ts)

Rank-up moves

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

• Handle a verified blocked fallback as a terminal item skip and prove that the next selected item is processed.

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

• reviewed 2026-08-09T13:59:49.645Z sha 85abed7 :: needs maintainer review before merge. :: none
• reviewed 2026-08-09T14:33:47.214Z sha 85abed7 :: needs changes before merge. :: [P2] Record fallback publication as a terminal item skip
• reviewed 2026-08-09T16:42:15.131Z sha 85abed7 :: needs changes before merge. :: [P2] Record fallback publication as a terminal item skip
• reviewed 2026-08-09T18:04:09.026Z sha 85abed7 :: needs changes before merge. :: [P2] Record blocked fallback as a terminal item skip
• reviewed 2026-08-09T19:11:19.041Z sha 85abed7 :: needs changes before merge. :: [P2] Record blocked fallback publication as an item skip
• reviewed 2026-08-09T21:04:14.892Z sha 85abed7 :: needs changes before merge. :: [P2] Record blocked fallback publication as an item skip
• reviewed 2026-08-09T22:50:47.119Z sha 85abed7 :: needs changes before merge. :: [P2] Record blocked fallback publication as an item skip
• reviewed 2026-08-22T07:07:59.010Z sha 85abed7 :: found issues before merge. :: [P2] Record a published fallback as a terminal item skip

[vincentkoc]

@clawsweeper re-review

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: when the review finishes, ClawSweeper will create the durable review comment if needed or update the existing comment in place.

Re-review progress:

• State: Complete
• Detail: The durable review result and its route handoff completed.
• Run: https://github.com/openclaw/clawsweeper/actions/runs/31213062620
• Updated: 2026-08-07T19:48:25.491Z