feat(b-0530): cron-sentinel-mutex — detect concurrent Otto-CLI sessions

[AceHack]

Summary

Implements the cheap-effort mitigation from B-0530 + the worktree-prune-race root-cause analysis landed in PR #3370. Closes the "narration-over-action drift" Lior flagged in PR #3373 by shipping the action-side parity proof for the documentation already on main.

What lands

• tools/orchestrator-checks/cron-sentinel-mutex.ts (103 lines) — diagnostic that detects concurrent Otto-CLI claude-code sessions via spawnSync("pgrep", ["-afl", "claude-code"]) (same args-as-array pattern as sibling verify-branch.ts, no shell, no injection).
• tools/orchestrator-checks/cron-sentinel-mutex.test.ts (91 lines) — 8 tests covering empty/self-exclusion/ancestor-exclusion/malformed-input/format paths.

Design choices

• Diagnostic, not a gate: returns a structured MutexResult; callers (the <<autonomous-loop>> tick body) decide whether to defer. Exit-0 in the no-peers case, exit-(1+peer-count) clamped to 250 for shell composition. JSON output via --json.
• Ancestor filtering: skip processes that lack the claude-code stdio-mode flags (--output-format/--input-format); avoids flagging the Claude.app helper / disclaimer wrappers as peers.
• Importable: export-ed helpers + if (import.meta.main) main() guard so tests can import without side effects.

Test plan

• bunx tsc --noEmit clean
• bun test: 8 pass / 0 fail (15 expect calls)
• semgrep --config .semgrep.yml --error: 0 findings
• Live smoke detected 3 concurrent claude-code sessions (real-world validation)
• CI green
• Auto-merge fires

Next step (not in this PR)

Wire the mutex into the <<autonomous-loop>> substrate so the tick body invokes it at the top and bus-publishes a deferral envelope when peers are detected. That's a follow-up commit; this PR ships the building block.

🤖 Generated with Claude Code

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 7bcd1a5e41

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[Copilot]

Pull request overview

Adds a new Bun/TypeScript diagnostic under tools/orchestrator-checks/ to detect concurrent claude-code (Otto-CLI) sessions by scanning the process list, with unit tests intended to cover parsing/filtering/formatting cases. This supports the broader goal of mitigating multi-session self-contention that can lead to git worktree/pack lock races.

Changes:

• Introduce cron-sentinel-mutex.ts to detect peer claude-code processes (PID + cmdline capture) and return a structured MutexResult.
• Add --json output mode and diagnostic exit-code behavior for shell composition.
• Add bun:test unit tests covering common parsing and filtering scenarios plus output formatting.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

File	Description
tools/orchestrator-checks/cron-sentinel-mutex.ts	Implements the mutex diagnostic via spawnSync("pgrep", ...), filters peers, formats output, and provides a CLI entrypoint.
tools/orchestrator-checks/cron-sentinel-mutex.test.ts	Adds unit tests for peer detection rules and formatting.

Comments suppressed due to low confidence (3)

tools/orchestrator-checks/cron-sentinel-mutex.ts:41

• P0: checkPeerSessions ignores spawnSync failures (e.g., pgrep missing/permission errors). In those cases stdout will be empty and the function returns peerDetected=false, silently failing open and defeating the mutex. Consider surfacing an error in the result and/or treating spawn errors as a detected-peer/blocked condition so contention doesn’t recur unnoticed.

  const result = spawnFn("pgrep", ["-afl", PROCESS_NAME_PATTERN], {
    encoding: "utf8",
  });

  const stdout = typeof result.stdout === "string" ? result.stdout : "";
  const lines = stdout.split("\n").filter((line) => line.trim().length > 0);

tools/orchestrator-checks/cron-sentinel-mutex.ts:58

• P1: The ancestor-filtering comment says to "require the ... flags" (plural), but the condition only rejects processes that have neither flag. That means a process with only --output-format (or only --input-format) will be treated as a peer, which may reintroduce false positives. If the intent is to require both stdio-mode flags, change the predicate accordingly (and align the comment).

    // Skip ancestors / disclaimer-helper / finder-service matches:
    // require the claude-code stdio-mode flags to mark a real peer.
    const cmdline = match[2] ?? "";
    if (!cmdline.includes("--output-format") && !cmdline.includes("--input-format")) {
      continue;
    }

tools/orchestrator-checks/cron-sentinel-mutex.ts:101

• P1: --json mode always exits 0 (process.exit(0)), which contradicts the documented diagnostic exit-code scheme and makes it hard to use --json in shell composition (you have to parse JSON to know whether peers exist). Consider emitting JSON but preserving the same exit code as main() (or document that --json intentionally forces success).

if (import.meta.main) {
  const args = process.argv.slice(2);
  if (args.includes("--json")) {
    const r = checkPeerSessions();
    console.log(JSON.stringify(r, null, 2));
    process.exit(0);
  }

[AceHack]

Fixed in the latest commit (0b3d03b):

Thread 1 (P1 — distinguish pgrep failures): Added checks for result.error (spawn failure, e.g., binary missing) and result.status > 1 (pgrep runtime error). Both cases now return a structured pgrepError field instead of silently reporting no peers. formatResult also surfaces the error with a "mutex state unknown" message. +3 new tests covering spawn-error, status-2 exit, and error-format rendering.

Thread 2 (P0 — sonarjs/no-os-command-from-path): Added // eslint-disable-next-line sonarjs/no-os-command-from-path before the spawnFn("pgrep", ...) call with rationale comment explaining that pgrep is a known system binary and the args-array form prevents shell injection.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 0b3d03b1af

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: b746bf7c4b

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".