Merge pull request #262 from openclaw/codex/cluster-fixer-docs-ops

docs: document cluster fixer operations visibility

Author: RomneyDa

dashboard/worker.ts

@@ -1070,6 +1070,7 @@ async function statusSnapshot(env, ctx) {
       automerge: automerge.items,
       closed_items: closed.items,
       closed_stats: closed.stats,
+      operation_counts: operationEventCounts(storedEvents),
       events: recentActivityEvents(storedEvents, closed.items),
       failed_runs: failedRuns.slice(0, 10).map((run) => workflowRunSummary(run)),
     },
@@ -2351,6 +2352,70 @@ function recentActivityEvents(storedEvents, closedItems) {
     .slice(0, 25);
 }
 
+function operationEventCounts(storedEvents) {
+  const counts = {
+    inherited_label_cleanups: 0,
+    self_heal_conflict_repairs: 0,
+    failed_review_retries: 0,
+    failed_review_retry_exhaustions: 0,
+    bot_owned_proof_decisions_requested: 0,
+    bot_owned_proof_dispatches: 0,
+  };
+  for (const event of Array.isArray(storedEvents) ? storedEvents : []) {
+    countOperationEvent(event, counts);
+  }
+  return counts;
+}
+
+function countOperationEvent(event, counts) {
+  const key = [event.event_type, event.mode, event.stage, event.status]
+    .map((value) =>
+      String(value || "")
+        .toLowerCase()
+        .replaceAll("-", "_"),
+    )
+    .join(" ");
+  if (
+    key.includes("inherited_label_cleanup") ||
+    key.includes("replacement_label_cleanup") ||
+    key.includes("removed_inherited_labels")
+  ) {
+    counts.inherited_label_cleanups += 1;
+  }
+  if (
+    key.includes("self_heal_conflict") ||
+    key.includes("conflict_self_heal") ||
+    key.includes("clawsweeper_self_rebase")
+  ) {
+    counts.self_heal_conflict_repairs += 1;
+  }
+  if (
+    key.includes("failed_review_retry_exhausted") ||
+    key.includes("failed_review_retries_exhausted")
+  ) {
+    counts.failed_review_retry_exhaustions += 1;
+  } else if (key.includes("failed_review_retry")) {
+    counts.failed_review_retries += 1;
+  }
+  if (
+    key.includes("bot_owned_proof_decision_requested") ||
+    key.includes("maintainer_proof_decision_requested") ||
+    key.includes("needs_maintainer_proof_decision") ||
+    key.includes("bot_proof_decision_planned") ||
+    key.includes("bot_proof_decision_posted")
+  ) {
+    counts.bot_owned_proof_decisions_requested += 1;
+  }
+  if (
+    key.includes("bot_owned_proof_dispatched") ||
+    key.includes("bot_owned_proof_capture_dispatched") ||
+    key.includes("bot_proof_mantis_request_planned") ||
+    key.includes("bot_proof_mantis_request_posted")
+  ) {
+    counts.bot_owned_proof_dispatches += 1;
+  }
+}
+
 function activityEventFromClosedItem(item) {
   return {
     event_type: "clawsweeper.item_closed",
@@ -4100,6 +4165,8 @@ a:hover { color: #89c8ff; text-decoration: underline; }
       <h2>✅ Closed by ClawSweeper</h2>
       <div id="closed-stats"></div>
       <div id="closed"></div>
+      <h2>🧭 Operations</h2>
+      <div id="operations"></div>
       <h2>📡 Recent Activity</h2>
       <div id="events"></div>
     </aside>
@@ -4224,6 +4291,7 @@ function renderDashboard(data, note) {
   renderAutomerge(data.recent.automerge || []);
   renderClosedStats(data.recent.closed_stats);
   renderClosedItems(data.recent.closed_items || []);
+  renderOperations(data.recent.operation_counts);
   renderEvents(data.recent.events || []);
 }
 function renderPipeline(rows) {
@@ -4276,6 +4344,18 @@ function renderClosedStats(stats) {
   const safe = stats || { total: 0, issues: 0, prs: 0, window_hours: 24 };
   document.getElementById("closed-stats").innerHTML = '<div class="closed-stats"><div class="closed-stat"><span>' + esc((safe.window_hours || 24) + "h total") + '</span><strong>' + fmt.format(safe.total || 0) + '</strong></div><div class="closed-stat"><span>Issues</span><strong>' + fmt.format(safe.issues || 0) + '</strong></div><div class="closed-stat"><span>PRs</span><strong>' + fmt.format(safe.prs || 0) + '</strong></div></div>';
 }
+function renderOperations(counts) {
+  const safe = counts || {};
+  const rows = [
+    ["Inherited labels", safe.inherited_label_cleanups || 0],
+    ["Conflict self-heal", safe.self_heal_conflict_repairs || 0],
+    ["Review retries", safe.failed_review_retries || 0],
+    ["Retry exhausted", safe.failed_review_retry_exhaustions || 0],
+    ["Proof decisions", safe.bot_owned_proof_decisions_requested || 0],
+    ["Proof dispatches", safe.bot_owned_proof_dispatches || 0]
+  ];
+  document.getElementById("operations").innerHTML = '<div class="closed-stats">' + rows.map(row => '<div class="closed-stat"><span>' + esc(row[0]) + '</span><strong>' + fmt.format(row[1]) + '</strong></div>').join("") + '</div>';
+}
 function renderEvents(rows) {
   if (!rows.length) {
     document.getElementById("events").innerHTML = '<div class="empty">Listening for signals from the fleet...</div>';

docs/proof-nudges.md

@@ -22,6 +22,31 @@ A pull request is eligible only when all of these are true:
 
 The lane skips maintainer-authored, bot-authored, security-sensitive, and release-style pull requests. It also skips pull requests with `proof: supplied`, `proof: sufficient`, or `proof: override`, because those need review or policy handling rather than another contributor reminder.
 
+## Bot-Owned Proof Handling
+
+Bot-owned replacement PRs are deliberately outside the contributor nudge lane.
+Do not make normal proof nudges comment on bot-authored PRs as if a contributor
+needs to respond. The `bot-proof` lane handles ClawSweeper-owned PRs that are
+blocked on real behavior proof.
+
+The bot-owned lane is status-only unless an approved Mantis proof suggestion is
+available. It is eligible only when the live PR is open and not draft, the
+author is the ClawSweeper GitHub App, the latest
+ClawSweeper review says real behavior proof blocks merge, and that review head
+SHA still matches the live head SHA. It must skip PRs with `proof: supplied`,
+`proof: sufficient`, or `proof: override`.
+
+When the review includes an approved Mantis-style proof suggestion, the lane
+posts a durable Mantis proof request comment. Otherwise it updates one durable
+status comment asking maintainers to choose proof capture, proof override, or
+pause. It does not post contributor reminders.
+
+For dashboard accounting, status-only maintainer requests use
+`bot_proof_decision_planned` or `bot_proof_decision_posted`. Mantis proof
+requests use `bot_proof_mantis_request_planned` or
+`bot_proof_mantis_request_posted`. Hosted dashboard events with those tokens are
+counted in the proof operation counters.
+
 ## Marker
 
 Cooldown state lives in the reminder comment body:
@@ -70,11 +95,16 @@ Scheduled operation uses repository variables:
 - `CLAWSWEEPER_PROOF_NUDGES_LIMIT`: optional scheduled batch size, default `10`.
 - `CLAWSWEEPER_PROOF_NUDGES_MIN_AGE_DAYS`: optional first-nudge age gate, default `5`.
 - `CLAWSWEEPER_PROOF_NUDGES_COOLDOWN_DAYS`: optional same-head cooldown, default `7`.
+- `CLAWSWEEPER_BOT_PROOF_SCHEDULED=1`: include the bot-owned proof lane in scheduled runs.
+- `CLAWSWEEPER_BOT_PROOF_EXECUTE=1`: allow scheduled bot-owned proof runs to post status comments and labels. Without this, scheduled bot-proof runs remain dry-run only.
 
 Suggested rollout:
 
 1. Run the proof-nudge workflow manually with `execute=false`.
 2. Set `CLAWSWEEPER_PROOF_NUDGES_SCHEDULED=1` to collect scheduled dry-run reports.
 3. Set `CLAWSWEEPER_PROOF_NUDGES_EXECUTE=1` only after the scheduled reports look correct.
+4. Run the bot-owned proof lane manually with `bot_proof=true` and `bot_proof_execute=false`.
+5. Set `CLAWSWEEPER_BOT_PROOF_SCHEDULED=1` only after dry-run reports look correct.
+6. Set `CLAWSWEEPER_BOT_PROOF_EXECUTE=1` only after generated comments and labels have been reviewed.
 
 This first version intentionally has no auto-close behavior. Any escalation after repeated proof nudges needs a separate maintainer policy decision.

docs/repair/auto-update-prs.md

@@ -259,6 +259,66 @@ state is enough to dispatch repair. That lets Codex rebase or resolve conflicts
 before the next exact-head review instead of waiting for a later pass marker or
 new maintainer comment.
 
+## ClawSweeper-Owned Conflict Self-Heal
+
+The conflict self-heal lane is for open pull requests that ClawSweeper itself
+owns. When enabled, it may dispatch a bounded repair for a PR only when all of these
+are true:
+
+- the author is the ClawSweeper GitHub App;
+- the head branch is in the base repository and starts with `clawsweeper/`;
+- the PR is open and the live merge state is `CONFLICTING`, `DIRTY`, or
+  `BEHIND`;
+- the exact head SHA is captured before dispatch and still matches when the
+  worker starts;
+- no waiting or dispatched self-heal attempt already covers that PR/head;
+- the self-heal per-head and per-PR caps still allow another attempt.
+
+Self-heal is repair-only. It does not add `clawsweeper:automerge`, it does not
+request a merge, and it does not treat a successful rebase as approval. After a
+successful push, the next required step is an exact-item ClawSweeper review for
+the new head. The PR can merge only through the normal automerge gates or a
+human maintainer path.
+
+The self-heal scanner has dedicated attempt caps:
+
+```bash
+--max-attempts-per-pr 10
+--max-attempts-per-head 2
+```
+
+The durable status comment records the detected merge state, targeted head SHA,
+job path, repair run URL, and current status. The generated job uses
+`job_intent: clawsweeper_self_rebase`, blocks close/merge/label actions, and
+pins `expected_head_sha` so stale jobs stop without mutating. For dashboard
+accounting, emit a `/api/events` payload whose event type, mode, stage, or
+status contains `clawsweeper_self_rebase` or `conflict_self_heal`.
+
+## Replacement Label Cleanup
+
+Replacement PR labels must describe the replacement PR, not stale lifecycle
+state from a source PR. Replacement creation filters source labels so it does
+not copy `close:*`, `stale`, `rating:*`, `status:*`, `proof:*`,
+`triage: needs-real-behavior-proof`, `merge-risk:*`, `size:*`, or `P*`
+priority labels.
+
+Use the cleanup command to inspect existing open ClawSweeper replacement PRs
+for inherited source labels:
+
+```bash
+pnpm run repair:cleanup-replacement-labels -- --repo openclaw/openclaw
+```
+
+The command writes `.artifacts/replacement-label-cleanup.json` by default. It
+is dry-run by default. To remove lifecycle labels from matching PRs, pass
+`--execute` with `CLAWSWEEPER_ALLOW_EXECUTE=1`; execute mode removes only
+`stale` and `close:*` labels.
+
+For dashboard accounting, publish the cleanup total through `pnpm run status`
+with `--inherited-label-cleanups`, or send a `/api/events` payload whose event
+type, mode, stage, or status contains `replacement_label_cleanup` or
+`inherited_label_cleanup`.
+
 ClawSweeper edits one durable review comment in place. The router keys its
 ledger by comment id plus `updated_at`, and response markers include the target
 PR head SHA, so an edited ClawSweeper comment can trigger a new repair after

docs/repair/operations.md

@@ -7,6 +7,45 @@ commands, finalizers, self-heal, gates, and ledgers, see
 For the trusted ClawSweeper-to-ClawSweeper PR repair loop, see
 [`docs/repair/auto-update-prs.md`](auto-update-prs.md).
 
+## Cluster Repair Operations Counters
+
+The README dashboard and hosted live dashboard expose passive counters for the
+cluster repair lanes. These counters are observational only; they do not
+enable repair, merge, close, proof dispatch, or label mutation.
+
+Record-backed dashboard counters read recent markdown records and count these
+signals:
+
+- `replacement_label_cleanup` or `inherited_label_cleanup` for replacement-label cleanup;
+- `clawsweeper_self_rebase` or `conflict_self_heal` for ClawSweeper-owned conflict repair;
+- `failed_review_retry_status: dispatched` or an action containing
+  `failed_review_retry` for an exact failed-review retry dispatch;
+- `failed_review_retry_status: exhausted` or an action containing
+  `failed_review_retry_exhausted` for retry cap exhaustion;
+- `bot_proof_decision_planned`, `bot_proof_decision_posted`, or
+  `needs_maintainer_proof_decision` for status-only maintainer proof decisions;
+- `bot_proof_mantis_request_planned` or `bot_proof_mantis_request_posted` for
+  approved Mantis proof requests.
+
+The hosted dashboard counts the same names from `/api/events` payloads when the
+event type, mode, stage, or status contains the matching token. Lanes that
+mutate GitHub or dispatch another workflow should emit a durable record or
+status comment and a hosted-dashboard event when that hook is available.
+
+Manual workflow status updates can publish the same counters directly:
+
+```bash
+pnpm run status -- \
+  --state "Working" \
+  --detail "Cluster repair dry-run completed." \
+  --inherited-label-cleanups 3 \
+  --self-heal-conflict-repairs 1 \
+  --failed-review-retries 2 \
+  --failed-review-retry-exhaustions 1 \
+  --bot-owned-proof-decisions-requested 1 \
+  --bot-owned-proof-dispatches 0
+```
+
 For commit-review findings, ClawSweeper dispatches
 `clawsweeper_commit_finding` to this repository. ClawSweeper fetches the latest
 markdown report, writes `results/commit-findings/<repo-slug>/<sha>.md`, and