fix(pi): route decision-owned wake batches to main

[kunchenguid]

Intent

Every needs-decision event must skip the supervision branch and come straight to the main session - not only no-mistakes ask-user findings, but every needs-decision: product calls, destructive choices, captain holds, and second-mate escalations.

The accepted routing rule this change implements: when ONE COALESCED signal or stale trigger batch contains any needs-decision row, deliver the ENTIRE batch to main. Do not split that same batch between the supervision branch and a later main wake. This whole-batch routing is the replacement for an earlier per-row approach that split a mixed batch, reserving routine rows for the supervision branch while sending only the needs-decision rows to main; that earlier approach is superseded and must not be reintroduced.

Ordinary task-local heartbeat, signal, and stale routing stays unchanged, and the implementation stays narrowly limited to the needs-decision signal path.

What Changed

• Classify needs-decision, captain-held, and second-mate escalation signals as main-owned events.
• Route an entire coalesced signal or stale trigger batch to main when it contains a decision-owned task, including task aliases and unresolved open decisions.
• Preserve independent routing for unrelated task-local rows and heartbeat reviews, with expanded regression coverage and documentation.

Risk Assessment

✅ Low: The routing changes are narrowly scoped, preserve heartbeat and routine task behavior, and the reviewed signal, stale, alias, cache, and symlink paths satisfy the stated invariants without a substantiated defect.

Testing

The successful baseline was supplemented with focused watcher, branch-dispatch, and Pi-extension tests covering needs-decision, captain-held, second-mate escalation, stale aliases, mixed batches, routine routing, and heartbeat independence. An executable integration artifact confirms a mixed batch is rejected by supervision and delivered intact to main; one unrelated stock-renderer compatibility case skipped because installed Pi 0.80.10 predates 0.84.4.

Evidence: Whole-batch needs-decision routing through the Pi watcher interface

Source: Whole-batch needs-decision routing through the Pi watcher interface

{
  "scenario": "coalesced signal for task-a (needs decision) plus task-b (routine)",
  "queuedRows": [
    "needs-decision: task-a.status",
    "signal: task-b.status"
  ],
  "supervisionBranchOffer": {
    "eligible": false,
    "message": "signal: task-a.status task-b.status",
    "projects": [
      "~/.no-mistakes/worktrees/016d88035d58/01M1R51AGSZ8VZ3NY8XG9T9QXD/.test-evidence-tmp/home/projects/approved"
    ]
  },
  "mainSessionWake": "⁣FIRSTMATE_OP: v1 watcher: FIRSTMATE WATCHER WAKE: signal: task-a.status task-b.status\n\nRun bin/fm-wake-drain.sh first and handle the queued wake. Watcher continuity is extension-owned.",
  "observedWholeBatch": true,
  "result": "PASS"
}

Pipeline

Updates from git push no-mistakes

✅ **intent** - passed

✅ No issues found.

✅ **Rebase** - passed

✅ No issues found.

🔧 **Review** - 1 issue found → auto-fixed (9) ✅

• 🚨 .pi/extensions/lib/fm-branch-dispatch.ts:202 - Intent requires “every needs-decision” and any stale trigger batch containing one to reach main, but stale classification only recognizes a final captain-held line. With a mapped task whose status ends needs-decision: choose destructive cleanup and a queued stale row, this check does not populate needsDecisionKeys; scope.eligible remains true and offerWakeToBranch can send the wake to supervision. The same bypass occurs when an earlier durable decision remains open behind a later unrelated status line. Classify stale rows using the durable open-decision semantics, while retaining captain-held detection, at this shared boundary.

🔧 Fix: Route stale open decisions directly to main
2 issues (1 error, 1 warning) still open:

• 🚨 bin/fm-classify-lib.sh:1657 - Intent explicitly requires second-mate escalations to reach main, but fm_pending_reply_maybe_escalate writes them as blocked [key=pending-reply-…] (bin/fm-pending-reply-lib.sh:1239), while the changed classifier sets the main-only marker only when the verb equals needs-decision. The resulting signal row retains a signal: payload, remains branch-eligible, and offerWakeToBranch can deliver it to supervision. Extend the narrowly scoped decision signal classification to recognize this concrete second-mate escalation class and route its whole coalesced batch to main.
• ⚠️ .pi/extensions/lib/fm-branch-dispatch.ts:151 - The new stale-path fold hardcodes resolved and captain-held, despite the authoritative status fold supporting FM_CLASSIFY_RESOLVE_VERB and FM_CLASSIFY_CAPTAIN_HELD_VERB. For example, with a configured resolution verb, needs-decision [key=x] followed by that resolution remains falsely open here and routes an ordinary stale wake to main; a configured captain-hold verb can instead be missed and offered to the branch. Use the configured verbs so stale routing agrees with the repository's durable fold semantics.

🔧 Fix: Honor configured verbs in stale decision routing
2 errors still open:

• 🚨 bin/fm-classify-lib.sh:1657 - Intent requires “every needs-decision” including “second-mate escalations” to reach main. However, fm_pending_reply_maybe_escalate writes these as blocked [key=pending-reply-…] (bin/fm-pending-reply-lib.sh:1239), while the changed classifier marks only the needs-decision verb. The resulting signal retains a signal: payload, remains branch-eligible, and can be delivered to supervision. Extend the decision-owned signal classification to recognize this concrete escalation class and route its coalesced batch wholly to main.
• 🚨 .pi/extensions/lib/fm-branch-dispatch.ts:155 - The new stale decision fold hardcodes pending-reply- as reserved instead of honoring FM_CLASSIFY_RESERVED_KEY_PREFIXES, unlike the authoritative shell fold. For example, with FM_CLASSIFY_RESERVED_KEY_PREFIXES=secret-, needs-decision [key=pending-reply-x]: choose cleanup is a valid open decision in the authoritative fold, but this code skips it and can offer its stale wake to supervision. Make this fold use the configured reserved-prefix semantics so every supported open decision routes to main and ordinary stale routing remains consistent.

🔧 Fix: Route second-mate escalations and configured decisions to main
1 error still open:

• 🚨 .pi/extensions/lib/fm-branch-dispatch.ts:245 - Intent requires captain holds to reach main, but status parsing removes only empty strings, not whitespace-only lines. For captain-held [key=route]: awaiting captain\n \n, hasOpenNeedsDecision treats the hold as closing the decision and the final-line check examines " ", so the stale row remains branch-eligible. This contradicts the repository’s last_status_line semantics, which ignore whitespace-only lines. Filter status lines by non-whitespace content before selecting the current declaration.

🔧 Fix: Ignore trailing whitespace after captain holds
1 warning still open:

• ⚠️ .pi/extensions/lib/fm-branch-dispatch.ts:244 - Each queued stale row rereads and refolds its task's entire append-only status log synchronously. Multiple unread reminders for one task therefore multiply work on Pi's UI thread; for example, 50 stale rows for a 20 MB status log parse roughly 1 GB per eligibility check without changing the result. Cache the decision classification per status path within scopeForUnreadWake so each task is read and folded at most once per scan.

🔧 Fix: Cache stale decision classification per status file
1 error still open:

• 🚨 .pi/extensions/fm-primary-pi-watch.ts:622 - Intent requires ordinary signal routing to remain unchanged and whole-batch main routing only when that coalesced batch contains a needs-decision row. This key-only cross-reference also matches older unread rows. If task-a's needs-decision row remains queued and a later routine signal batch for task-a arrives, scope.needsDecisionKeys still contains task-a.status, so the later routine batch is incorrectly forced to main without error. Distinguishing queue history from the triggering batch may require a batch identity or equivalent protocol change, so the remedy needs user authorization.

🔧 Fix: Document unread decision precedence for later task wakes
1 warning still open:

• ⚠️ .pi/extensions/lib/fm-branch-dispatch.ts:253 - The per-scan cache still rereads each unread stale row's entire append-only status log on every scopeForUnreadWake call. Concretely, one unread stale decision for a task with a 20 MB status log makes every later routine signal or heartbeat synchronously read and fold that 20 MB file on Pi's UI thread, even when the file is unchanged. Cache classifications across scans using file identity/size/mtime invalidation, preserving fail-closed behavior when metadata or reads fail.

🔧 Fix: Cache unchanged stale decisions across scope scans
2 errors still open:

• 🚨 .pi/extensions/fm-primary-pi-watch.ts:624 - The documented precedence says an unread decision forces every later signal or stale trigger for the same task to main, but this compares raw queue keys rather than task identity. For task-a, an unread decision signal is keyed task-a.status; after the status is resolved, a later stale trigger is keyed fm-window. The stale fold no longer marks the resolved status, the keys do not match, and the stale batch is offered to supervision. Preserve the approved same-task precedence across status-file and window aliases.
• 🚨 .pi/extensions/lib/fm-branch-dispatch.ts:157 - The new stale classifier uses statSync and readFileSync, both of which follow task.status symlinks. A mapped stale row can therefore make the Pi extension synchronously read an arbitrary symlink target and let that external content control main-versus-branch routing. This violates the repository's authoritative status-fold boundary, which explicitly rejects status-file symlinks in status_open_decisions. Reject symlinks with lstatSync before versioning or reading, failing the scope closed.

🔧 Fix: Resolve decision aliases and reject symlinked statuses
1 error still open:

• 🚨 bin/fm-watch.sh:1771 - Intent requires every captain hold to reach main, but signal payloads are marked main-only only when FM_SIGNAL_NEEDS_DECISION_FILES contains the file. status_is_captain_relevant excludes captain-held, so a captain-held append surfaced through the documented no-verb fallback (for example after the crew ends without positive working evidence) is queued with an ordinary signal: payload. scopeForUnreadWake then treats that signal row as branch-eligible and the captain hold can enter supervision. Extend the main-only marker to surfaced captain-held signal files and cover that executable path.

🔧 Fix: Route surfaced captain-held signals directly to main
✅ Re-checked - no issues remain.

✅ **Test** - passed

✅ No issues found.

• bin/fm-test-run.sh --changed --exclude-family real-herdr-gated
• Baseline: bin/fm-test-run.sh --changed --exclude-family real-herdr-gated
• bin/fm-test-run.sh tests/fm-watch-triage.test.sh tests/fm-pi-branch-extension.test.sh tests/fm-pi-watch-extension.test.sh
• Manual executable Pi integration: queued one needs-decision signal and one routine signal in the same coalesced batch, captured the supervision offer and main-session wake, and verified whole-batch main routing
• Verified testing left the git worktree clean and removed .test-evidence-tmp

✅ **Document** - passed

✅ No issues found.

✅ **Lint** - passed

✅ No issues found.

✅ **Push** - passed

✅ No issues found.

[greptile-apps]

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains.

_{Reviews (3): Last reviewed commit: "no-mistakes(ci): Fixed the CI regression..." | Re-trigger Greptile}