tickmarkr 1.58.0 → 1.59.0

package/README.md

@@ -415,9 +415,15 @@ These are optional — the CLI works standalone. Skills are repo-scoped and ship
 
 ## Contributing
 
-See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, the green bar (build/test/lint), and 
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, the green bar (build/test/lint), and
 design invariants. Pull requests welcome; non-trivial changes should include test coverage.
 
+**Boundaries:** this repo is a squashed export of private development — each release is a verified
+snapshot, not a live mirror of every commit. Before tickmarkr 2.0, minor versions may break with every
+break noted in [CHANGELOG.md](CHANGELOG.md). Support is best effort for the latest version only;
+accepted contributions are credited via `Co-authored-by:` on the release commit. Details in
+[CONTRIBUTING.md](CONTRIBUTING.md).
+
 ## Documentation
 
 - **[LICENSE](LICENSE)** — MIT license

package/dist/cli/commands/init.js

@@ -1,5 +1,6 @@
-import { appendFileSync, existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { appendFileSync, cpSync, existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
+import { fileURLToPath } from "node:url";
 import { createInterface } from "node:readline/promises";
 import { parseArgs } from "node:util";
 import { allAdapters, formatDoctorAgeForInit, formatDoctorReport, initDoctorReuse } from "../../adapters/registry.js";
@@ -61,7 +62,7 @@ function nextSteps(cwd, scaffoldedSpec) {
     return `next: edit ${scaffoldedSpec}, then tickmarkr compile ${scaffoldedSpec} && tickmarkr plan && tickmarkr run`;
 }
 const visual = () => process.stdout.isTTY === true && process.env.NO_COLOR === undefined;
-const AGENT_SKILLS = ["tickmarkr-loop", "tickmarkr-auto"];
+const AGENT_SKILLS = ["tickmarkr-loop", "tickmarkr-auto", "tickmarkr-overseer"];
 const DOCS_BEGIN = "<!-- tickmarkr:agent-docs begin -->";
 const DOCS_END = "<!-- tickmarkr:agent-docs end -->";
 const AGENT_DOCS = `${DOCS_BEGIN}
@@ -110,9 +111,16 @@ A run is green only when the run-end event exists in the journal AND tip verify
 When relaying missions between agents, never use bare send-text (\`herdr agent send\` / pane send-text) — it omits Enter. Use \`herdr pane run <pane> "<message>"\` or \`herdr notification show "<message>"\`. Confirm delivery by reading the target pane afterward; never report "relayed" without read-back.
 ${DOCS_END}
 `;
-const skillsRoot = (cwd) => existsSync(join(cwd, ".claude", "skills")) ? join(cwd, ".claude", "skills") : join(cwd, ".agents", "skills");
-const skillPath = (cwd, skill) => join(skillsRoot(cwd), skill, "SKILL.md");
-const skillsInstalled = (cwd) => AGENT_SKILLS.every((s) => existsSync(skillPath(cwd, s)));
+// Every applicable host location gets the skills, each paired with its own repository guidance
+// file: codex discovers .agents/skills + AGENTS.md (always applicable); claude discovers
+// .claude/skills + CLAUDE.md (applicable when the repo already shows claude usage).
+const hostTargets = (cwd) => {
+    const targets = [{ skillsDir: join(cwd, ".agents", "skills"), docPath: join(cwd, "AGENTS.md") }];
+    if (existsSync(join(cwd, ".claude")) || existsSync(join(cwd, "CLAUDE.md")))
+        targets.push({ skillsDir: join(cwd, ".claude", "skills"), docPath: join(cwd, "CLAUDE.md") });
+    return targets;
+};
+const skillsInstalled = (cwd) => hostTargets(cwd).every((t) => AGENT_SKILLS.every((s) => existsSync(join(t.skillsDir, s, "SKILL.md"))));
 const wizardDriverDefault = () => process.env.HERDR_ENV === "1" ? "herdr" : "auto";
 async function installAgentFiles(cwd, force, docs, notes) {
     const interactive = process.stdin.isTTY === true && process.stdout.isTTY === true;
@@ -124,31 +132,30 @@ async function installAgentFiles(cwd, force, docs, notes) {
         return /^(?:y|yes)$/i.test((await prompt.question(`${question} [y/N] `)).trim());
     };
     try {
-        for (const skill of AGENT_SKILLS) {
-            const dest = skillPath(cwd, skill);
-            const exists = existsSync(dest);
-            if (exists && !force && !(await confirm(`Overwrite ${dest}?`))) {
-                notes.push(`skipped existing ${dest}; pass --force to overwrite it`);
-                continue;
+        for (const { skillsDir, docPath } of hostTargets(cwd)) {
+            for (const skill of AGENT_SKILLS) {
+                const dest = join(skillsDir, skill, "SKILL.md");
+                const exists = existsSync(dest);
+                if (exists && !force && !(await confirm(`Overwrite ${dest}?`))) {
+                    notes.push(`skipped existing ${dest}; pass --force to overwrite it`);
+                    continue;
+                }
+                // whole skill dir, not just SKILL.md — the overseer ships its pane-watcher script
+                cpSync(fileURLToPath(new URL(`../../../skills/${skill}`, import.meta.url)), join(skillsDir, skill), { recursive: true });
+                notes.push(`${exists ? "overwrote" : "wrote"} ${dest}`);
+            }
+            const current = existsSync(docPath) ? readFileSync(docPath, "utf8") : "";
+            if (current.includes(DOCS_BEGIN) || current.includes(`<!-- ${LEGACY_PREFIX}:agent-docs begin -->`)
+                || current.includes(DOCS_END) || current.includes(`<!-- ${LEGACY_PREFIX}:agent-docs end -->`)) {
+                notes.push(`kept existing tickmarkr agent docs in ${docPath}`);
+            }
+            else if (docs || await confirm(`Append tickmarkr agent docs to ${docPath}?`)) {
+                appendFileSync(docPath, `${current ? current.endsWith("\n") ? "\n" : "\n\n" : ""}${AGENT_DOCS}`);
+                notes.push(`appended tickmarkr agent docs to ${docPath}`);
+            }
+            else {
+                notes.push(`skipped agent docs for ${docPath}; pass --docs to append them`);
             }
-            mkdirSync(join(skillsRoot(cwd), skill), { recursive: true });
-            writeFileSync(dest, readFileSync(new URL(`../../../skills/${skill}/SKILL.md`, import.meta.url)), exists ? undefined : { flag: "wx" });
-            notes.push(`${exists ? "overwrote" : "wrote"} ${dest}`);
-        }
-        const claude = join(cwd, "CLAUDE.md");
-        const agents = join(cwd, "AGENTS.md");
-        const docPath = existsSync(claude) || !existsSync(agents) ? claude : agents;
-        const current = existsSync(docPath) ? readFileSync(docPath, "utf8") : "";
-        if (current.includes(DOCS_BEGIN) || current.includes(`<!-- ${LEGACY_PREFIX}:agent-docs begin -->`)
-            || current.includes(DOCS_END) || current.includes(`<!-- ${LEGACY_PREFIX}:agent-docs end -->`)) {
-            notes.push(`kept existing tickmarkr agent docs in ${docPath}`);
-        }
-        else if (docs || await confirm(`Append tickmarkr agent docs to ${docPath}?`)) {
-            appendFileSync(docPath, `${current ? current.endsWith("\n") ? "\n" : "\n\n" : ""}${AGENT_DOCS}`);
-            notes.push(`appended tickmarkr agent docs to ${docPath}`);
-        }
-        else {
-            notes.push(`skipped agent docs for ${docPath}; pass --docs to append them`);
         }
     }
     finally {
@@ -183,7 +190,7 @@ async function runInitWizard(cwd) {
         let installSkills = false;
         if (!skillsInstalled(cwd)) {
             const skillsDef = existsSync(join(cwd, ".claude", "skills")) && !skillsInstalled(cwd);
-            installSkills = await askYesNo(rl, "Install agent skills (tickmarkr-loop/tickmarkr-auto)?", skillsDef);
+            installSkills = await askYesNo(rl, "Install agent skills (tickmarkr-loop/tickmarkr-auto/tickmarkr-overseer)?", skillsDef);
         }
         return { overlay: { driver, concurrency, visibility: { llm } }, installSkills };
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tickmarkr",
-  "version": "1.58.0",
+  "version": "1.59.0",
   "description": "Spec in, verified work out.",
   "type": "module",
   "license": "MIT",
@@ -31,6 +31,7 @@
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "lint": "oxlint src tests scripts",
+    "pretest": "npm run build",
     "test": "vitest run",
     "test:coverage": "vitest run --coverage",
     "schema": "tsx scripts/emit-schema.ts",

package/skills/tickmarkr-auto/SKILL.md

@@ -14,7 +14,9 @@ When working in a multi-agent terminal environment, decide your role before star
 
 - **Orchestrator:** your session was started to execute the mission. Rename your own tab/pane `ORCH · <version>` (short labels: ≤20 chars, `ROLE · token`) and run the loop below.
 - **Supervisor with a live orchestrator:** do not start a second run. Relay the mission to the existing orchestrator with a [verified handoff](#verified-handoffs-agent-to-agent-messaging), then supervise it as OVERSEER.
-- **Primary session without an orchestrator:** rename your own tab `OVERSEER · <version>` and your agent `overseer`, spawn one child orchestration session with `--permission-mode bypassPermissions`, label its tab `ORCH · <version>` and name its agent, give it the mission and these rules verbatim, then supervise it. Do not drive a duplicate single-tier run yourself. Before spawning, confirm any PREVIOUS orchestrator has stood down (monitors stopped, input box empty — dim ghost-text suggestions are UI, not queued input; ANSI-verify before alarming) and close its tab — the journal, records, and ledger hold the story; scrollback is disposable.
+- **Primary session without an orchestrator:** rename your own tab `OVERSEER · <version>` and your agent `overseer`, spawn one child orchestration session with your host's launch form, label its tab `ORCH · <version>` and name its agent, give it the mission and these rules verbatim, then supervise it. Do not drive a duplicate single-tier run yourself. Before spawning, confirm any PREVIOUS orchestrator has stood down (monitors stopped, input box empty — dim ghost-text suggestions are UI, not queued input; ANSI-verify before alarming) and close its tab — the journal, records, and ledger hold the story; scrollback is disposable.
+  - **Claude Code:** `herdr agent start orchestrator --cwd <repo> --no-focus -- claude --permission-mode bypassPermissions`
+  - **Codex:** `herdr agent start orchestrator --cwd <repo> --no-focus -- codex --ask-for-approval never --sandbox workspace-write`
 
 Outside a multi-agent terminal environment, run the loop directly.
 

package/skills/tickmarkr-loop/SKILL.md

@@ -13,7 +13,9 @@ When working in a multi-agent terminal environment, decide your role before star
 
 - **Orchestrator:** your session was started to execute the mission. Rename your own tab/pane `ORCH · <version>` (short labels: ≤20 chars, `ROLE · token`) and run the loop below.
 - **Supervisor with a live orchestrator:** do not start a second run. Relay the mission to the existing orchestrator with a [verified handoff](#verified-handoffs-agent-to-agent-messaging), then supervise it as OVERSEER.
-- **Primary session without an orchestrator:** rename your own tab `OVERSEER · <version>` and your agent `overseer`, spawn one child orchestration session with `--permission-mode bypassPermissions`, label its tab `ORCH · <version>` and name its agent, give it the mission and these rules verbatim, then supervise it. Do not drive a duplicate single-tier run yourself. Before spawning, confirm any PREVIOUS orchestrator has [stood down](#stand-down-mission-end-and-retirement) and close its tab.
+- **Primary session without an orchestrator:** rename your own tab `OVERSEER · <version>` and your agent `overseer`, spawn one child orchestration session with your host's launch form, label its tab `ORCH · <version>` and name its agent, give it the mission and these rules verbatim, then supervise it. Do not drive a duplicate single-tier run yourself. Before spawning, confirm any PREVIOUS orchestrator has [stood down](#stand-down-mission-end-and-retirement) and close its tab.
+  - **Claude Code:** `herdr agent start orchestrator --cwd <repo> --no-focus -- claude --permission-mode bypassPermissions`
+  - **Codex:** `herdr agent start orchestrator --cwd <repo> --no-focus -- codex --ask-for-approval never --sandbox workspace-write`
 
 Outside a multi-agent terminal environment, run the loop directly.
 

package/skills/tickmarkr-overseer/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: tickmarkr-overseer
+description: "Use when the user asks to oversee/supervise/babysit an autonomous tickmarkr run in a Herdr workspace (e.g. '/tickmarkr-overseer run the milestone', 'supervise this tickmarkr run', 'babysit this pipeline'). Requires HERDR_ENV=1. The skill argument is the mission (what to run end-to-end)."
+---
+
+# Overseer (tickmarkr)
+
+Become the OVERSEER for this workspace. Do no heavy work directly — build and supervise a two-tier
+hierarchy of VISIBLE agents (you → orchestrator → tickmarkr's own worker fleet), and route human decisions
+to the user with evidence.
+
+The mission is the skill argument. If empty, ask the user what to run end-to-end before doing anything else.
+Requires `HERDR_ENV=1`; if unset, say so and stop.
+
+## Setup
+
+0. **Adopt before you build.** If this workspace already has a supervision hierarchy — an
+   OVERSEER/ORCHESTRATOR tab, a live agent named `*orch*`, or a `<repo>/<state-dir>/overseer/` dir
+   (state dir = `.tickmarkr/`; legacy standalone `<repo>/.overseer/` counts
+   too) — do NOT spawn a duplicate (two orchestrators risk two concurrent tickmarkr runs in one repo,
+   which tickmarkr forbids). Read that dir's `DECISIONS.md` + `ORCH-BRIEF.md`, check the existing agents'
+   status, and either ADOPT the
+   existing orchestrator (updated brief, re-armed watchers) or, if the old hierarchy is dead, archive the
+   stale brief and build fresh.
+1. Load the `herdr` skill. `herdr pane list` to map the workspace — the focused pane is yours. Rename your
+   tab OVERSEER; create ONE tab ORCHESTRATOR.
+   **Live tab labels (standing operator rule, 2026-07-12):** on every decision or state change (role
+   handoff, task done/merged, run end) rename the affected tabs — and keep labels SHORT: the role as the
+   main name plus at most ONE hot-state token. Vocabulary: ORCH carries the milestone and progress
+   fraction (`ORCH · v1.19 4/5`, updated on every task-done); WORKERS carries the task token (tickmarkr
+   updates it). Never long context strings or ✓-chains.
+2. **Orchestrator**: Launch the orchestrator with your agent host. For Claude Code, use `herdr agent start orchestrator --cwd <repo> --no-focus -- claude --permission-mode bypassPermissions` (pin a strong model with `--model <m>` if the operator has a policy). For Codex, use `herdr agent start orchestrator --cwd <repo> --no-focus -- codex --ask-for-approval never --sandbox workspace-write` (add `--model <m>` to specify the model). Workers you never spawn — tickmarkr spawns its own visible worker panes.
+3. **Standing instructions travel as a brief FILE, never as pane text** — PTY input truncates at ~1024B and a
+   truncated brief silently drops policy. Write the full brief to `<repo>/.tickmarkr/overseer/ORCH-BRIEF.md`
+   (inside the tickmarkr state dir — already self-gitignored, no exclude step needed), then send one line:
+   `herdr pane run <orch> "Read .tickmarkr/overseer/ORCH-BRIEF.md and follow it exactly."` The brief MUST contain: the
+   mission, the pane mechanics below, rules 1–2, and require a verbatim one-sentence acknowledgment of the
+   human-checkpoint rule before anything is dispatched. Delete the dir at mission end.
+4. Arm the watcher (Supervision). Report the hierarchy map (pane ids + names) to the user.
+
+## Supervising tickmarkr as the executor
+
+When the mission runs `/tickmarkr-auto` (tickmarkr dispatches the workers), supervision changes shape:
+
+- **Give the run a live surface.** `tickmarkr run` is stdout-silent until run-end by design — split a pane in the
+  ORCHESTRATOR tab running `tickmarkr status --watch`. Narration also arrives as herdr notifications.
+- **Watch the journal, not the panes.** The append-only journal
+  (`.tickmarkr/runs/<runId>/journal.jsonl`) is the
+  source of truth. Arm a background watcher on `run-end` / `task-human` / `task-failed` / `consult-verdict`
+  events; never sleep-poll inside an agent turn.
+- **Daemon liveness ≠ journal activity.** A dead daemon emits no events, so journal watchers sleep through
+  its death. `tickmarkr status` prints last-event age + daemon pid liveness; check it before diagnosing a stall.
+  Recovery is `tickmarkr resume <runId>` — crash-safe by design (journal replay restores attempt counts and
+  consult channel bans).
+- **Gate quiet ≠ idle.** Between `worker-result` and the batched `gate-result`s tickmarkr runs shell gates plus a
+  headless LLM judge/review with little visible signal — check the journal timestamps before intervening.
+- **Classify gate failures before reacting.** The same fingerprint failing across DIFFERENT workers, or a
+  scope/test catch-22 (attempt N edits a file → scope gate fails; attempt N+1 leaves it → test gate fails),
+  is a PLAN defect: widen `files_modified` in the phase PLAN, recompile the phase dir after the run ends or
+  the task parks, release (`human → pending`), resume. A cross-vendor review rejection with concrete findings
+  is a REAL defect — let the escalation ladder work.
+- **Dialog watchers go stale per attempt.** Every retry/escalation may spawn a new pane; re-arm dialog
+  watchers on each `task-dispatch` journal event.
+
+## Pane mechanics that bite
+
+- **Verified send protocol**: `herdr agent send` writes WITHOUT Enter, and `pane run`'s Enter can be swallowed
+  by bracketed-paste on long payloads. Robust sequence: read the pane (bare prompt required) → send-text →
+  sleep 2–3s → send-keys Enter → read back (input empty / agent `working`). Never report "briefed" without
+  the read-back. Long content goes in a brief file, never pane text.
+- **Guard-before-Enter** (race-safe prompt answering): chain with `&&` — pane get shows `blocked` && pane
+  read shows the expected option under the cursor && only then send-keys. If no longer `blocked`, someone
+  already answered; do nothing.
+- `herdr wait agent-status` exits 1 on timeout, 0 on match — but ALSO 0 (with an error JSON) when the pane is
+  GONE. Never chain `wait && act` without confirming the pane exists.
+- Stale typed input is unclearable via CLI — supersede it:
+  `pane run "<-- disregard everything before this arrow (stale draft). ACTUAL: <message>"`.
+
+## Supervision watcher
+
+Arm the bundled watcher as its OWN Bash call with `run_in_background` — chaining it after other commands
+with `&` orphans it from the wake chain. It prints one wake reason and exits; re-arm after every wake.
+
+```bash
+.claude/skills/tickmarkr-overseer/scripts/watch-panes.sh WORKER_PANE ORCH_PANE [--fast-blocked]
+```
+
+Default mode wakes only when both panes are quiet (dropped handoff) or the orchestrator blocks; the
+orchestrator gets a 90s grace window to handle worker blocks first. For long parked stretches a targeted
+`herdr wait agent-status <pane> --status <s> --timeout <ms>` beats the watcher. When parking a human
+checkpoint, also fire `herdr notification show "HUMAN CHECKPOINT: <gate>" --sound request`.
+
+## Specialist pipeline rules
+
+- **Dedicated consultant tab**: Consultants (agents spawned to gather synthesis input for decisions like SCOPER analysis or architectural reviews) must run in a DEDICATED tab separate from the ORCHESTRATOR tab. When the orchestrator stands down, the consultant panes should persist so their assessments remain available for review and reference.
+- **Scoper worktree rule**: The SCOPER (or any worktree-based specialist synthesizing into the spec pipeline) must do ALL git operations in a dedicated worktree (e.g., `git worktree add /private/tmp/tkr-scoper-v155 -b spec/...`), never switching the main checkout's branch. This prevents race conditions between the specialist's branch operations and the orchestrator's shipping logic.
+
+## Non-negotiable rules
+
+1. **Takeover rule**: only act on a worker if it needs input AND the orchestrator is not `working`.
+2. **Human checkpoints (absolute)**: any gate marked `autonomous: false` or asking for product/visual
+   sign-off is NEVER auto-answered — regardless of how obviously correct the highlighted option looks. Leave
+   it blocked and bring the user the decision WITH evidence. If the mission explicitly delegates authority,
+   routine-class gates may be overseer-decided after polling the operator first — but spend and ship gates
+   NEVER self-decide.
+3. **Trust disk over transcripts**: verify artifacts on disk before building on them; a subagent killed
+   mid-flight still renders "Done" without writing its artifact.
+4. **Report concisely on every state change**: what happened, who handled it, what's next. Lead with the
+   outcome. Surface product decisions; never make them.
+5. **Log every abnormality** to `.planning/OBSERVATIONS.md` (or the project's ledger), even mid-run.

package/skills/tickmarkr-overseer/scripts/watch-panes.sh

@@ -0,0 +1,93 @@
+#!/usr/bin/env bash
+# watch-panes.sh — Herdr overseer watcher.
+# Polls worker + orchestrator agent_status via `herdr pane get`, prints ONE wake
+# reason to stdout, then exits. Run it via the Bash tool with run_in_background
+# so the overseer is re-invoked when it fires. Re-run (re-arm) after every wake.
+#
+# Usage:
+#   watch-panes.sh WORKER_PANE ORCH_PANE [--fast-blocked] [--cap-seconds N] [--settle-seconds N]
+#
+# Options:
+#   --fast-blocked     Wake fast (20s debounce) whenever the WORKER blocks, even
+#                      if the orchestrator is working. Use during stretches with
+#                      human checkpoints. Without it, a blocked worker gets a 90s
+#                      grace window for the orchestrator to handle it first
+#                      (takeover rule), and only wakes if BOTH panes are quiet.
+#   --cap-seconds N    Max watch duration (default 14400 = 4h).
+#   --settle-seconds N Initial sleep before polling (default 60) so a
+#                      just-dispatched turn can start without an instant refire.
+#
+# Wake reasons printed:
+#   WORKER_PANE_GONE / ORCH_PANE_GONE   — a pane disappeared
+#   ORCH:blocked WORKER:<s>             — orchestrator itself needs input
+#   WORKER:blocked ORCH:<s>             — worker blocked (fast-blocked mode)
+#   WORKER:<s> ORCH:<s>                 — both quiet: dropped handoff / done
+#   WATCH_CAP_REACHED ...               — cap hit, everything still working
+set -u
+WORKER="${1:?worker pane id required}"
+ORCH="${2:?orchestrator pane id required}"
+shift 2
+FAST_BLOCKED=false
+CAP=14400
+SETTLE=60
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --fast-blocked) FAST_BLOCKED=true ;;
+    --cap-seconds) CAP="$2"; shift ;;
+    --settle-seconds) SETTLE="$2"; shift ;;
+  esac
+  shift
+done
+
+get_status() {
+  herdr pane get "$1" 2>/dev/null | python3 -c '
+import sys, json
+try:
+    d = json.load(sys.stdin)
+    p = d.get("result", {}).get("pane", d.get("result", {}))
+    print(p.get("agent_status", "unknown"))
+except Exception:
+    print("gone")
+' 2>/dev/null || echo gone
+}
+
+# Transient CLI/server failures also read as "gone" — recheck before declaring.
+confirmed_gone() {
+  sleep 5
+  [ "$(get_status "$1")" = "gone" ]
+}
+
+END=$((SECONDS + CAP))
+sleep "$SETTLE"
+while [ $SECONDS -lt $END ]; do
+  WS=$(get_status "$WORKER")
+  OS=$(get_status "$ORCH")
+  if [ "$WS" = "gone" ]; then
+    confirmed_gone "$WORKER" && { echo "WORKER_PANE_GONE ORCH:$(get_status "$ORCH")"; exit 0; }
+    continue
+  fi
+  if [ "$OS" = "gone" ]; then
+    confirmed_gone "$ORCH" && { echo "ORCH_PANE_GONE WORKER:$(get_status "$WORKER")"; exit 0; }
+    continue
+  fi
+  # orchestrator itself stuck on a prompt (debounced)
+  if [ "$OS" = "blocked" ]; then
+    sleep 15
+    [ "$(get_status "$ORCH")" = "blocked" ] && { echo "ORCH:blocked WORKER:$WS"; exit 0; }
+  fi
+  # human-checkpoint mode: wake fast on any persisting worker block
+  if $FAST_BLOCKED && [ "$WS" = "blocked" ]; then
+    sleep 20
+    [ "$(get_status "$WORKER")" = "blocked" ] && { echo "WORKER:blocked ORCH:$(get_status "$ORCH")"; exit 0; }
+  fi
+  # standard mode: worker needs attention AND orchestrator is not driving
+  if [ "$WS" != "working" ]; then
+    sleep 90
+    WS2=$(get_status "$WORKER"); OS2=$(get_status "$ORCH")
+    if [ "$WS2" != "working" ] && [ "$OS2" != "working" ]; then
+      echo "WORKER:$WS2 ORCH:$OS2"; exit 0
+    fi
+  fi
+  sleep 20
+done
+echo "WATCH_CAP_REACHED WORKER:$(get_status "$WORKER") ORCH:$(get_status "$ORCH")"