tickmarkr 2.4.1 → 2.5.0

package/dist/cli/help.js

@@ -0,0 +1,212 @@
+// Descriptions live beside dispatch, not in mutating command bodies. The parser/registry drift
+// test checks these option names against production source; adding a command requires help here.
+export const COMMAND_HELP = {
+    init: {
+        usage: "init [options]", description: "Set up repository/global config, a starter spec and adapter health.",
+        options: {
+            "--global-dir <path>": "Use this global configuration directory.",
+            "--agent": "Install agent skills; combine with --docs for guidance files.",
+            "--force": "Refresh existing managed agent skills/docs when installing them.",
+            "--docs": "Include agent guidance documents with --agent.",
+            "--fresh": "Force fresh adapter probes instead of reusing recent health.",
+            "--yes": "Skip the interactive setup wizard and use defaults.",
+        }, examples: ["init --yes", "init --agent --force --docs"],
+    },
+    doctor: {
+        usage: "doctor [options]", description: "Probe configured adapters and models and print diagnostics. Default probing may make model calls and refresh a stale catalog.",
+        options: {
+            "--models": "Include full per-model diagnostics.",
+            "--fix": "Run normal probes and repair the test-runner ignore when a safe edit exists.",
+            "--fix-only": "Repair and verify the test-runner ignore locally; skip model probes and catalog refresh.",
+            "--cached": "Read cached diagnostics without probing or refreshing the catalog.",
+            "--cached-only": "Alias for --cached.",
+            "--probe-preflight": "Disclose configured model/probe counts and affected files without probing.",
+            "--preflight": "Alias for --probe-preflight.",
+            "--refresh-catalog": "Refresh only the model catalog; use as the sole option.",
+            "--catalog-only": "Alias for --refresh-catalog; use as the sole option.",
+        }, examples: ["doctor --probe-preflight", "doctor --fix-only", "doctor --models", "doctor --refresh-catalog"],
+    },
+    fleet: {
+        usage: "fleet [options]", description: "Edit fleet configuration interactively, or print it for scripts.",
+        options: {
+            "--print": "Print fleet configuration without opening the editor.",
+            "--why": "Include routing eligibility explanations in printed output.",
+            "--global-dir <path>": "Use this global configuration directory.",
+            "--fresh": "Refresh adapter health; may make model calls.",
+        }, examples: ["fleet --print --why", "fleet"],
+    },
+    compile: {
+        usage: "compile <spec-dir-or-md> [options]", description: "Compile source into .tickmarkr/graph.json; acceptance criteria are required.",
+        options: {
+            "--type <speckit|prd|gsd|native>": "Select the source format explicitly.",
+            "--dry-run": "Validate and report without saving the graph.",
+            "--strict": "Treat all native authoring lint findings as blocking errors.",
+        }, examples: ["compile feature.spec.md --type native --dry-run", "compile feature.spec.md --strict"],
+    },
+    scope: {
+        usage: "scope <intent-file> [options]", description: "Draft a native spec beside an answered intent. Authoring requires TTY confirmation or --yes and may make model calls.",
+        options: {
+            "--preview": "Validate locally and show cached candidate, destination and call budget; no probes, model calls or writes.",
+            "--yes": "Confirm the disclosed authoring action without a TTY prompt.",
+            "--force": "Allow overwriting the destination spec after confirmation.",
+        }, examples: ["scope feature.intent.md --preview", "scope feature.intent.md --yes", "scope feature.intent.md --yes --force"],
+    },
+    plan: {
+        usage: "plan [options]", description: "Print the compiled graph's routing preview, cost estimate and floor lints without dispatching workers.",
+        options: {
+            "--mode <risk-based|partner-led|staff-led>": "Preview routing under the selected mode.",
+            "--driver <auto|herdr|subprocess|orca>": "Preview the execution driver; orca is explicit-only.",
+        }, examples: ["plan", "plan --mode risk-based --driver subprocess"],
+    },
+    run: {
+        usage: "run [options]", description: "Execute the compiled graph with production preflight, gates and run locking.",
+        options: {
+            "--concurrency <N>": "Set a positive integer worker concurrency.",
+            "--driver <auto|herdr|subprocess|orca>": "Choose the execution driver; orca is explicit-only.",
+            "--route-strict": "Refuse routing conflicts and lints before dispatch.",
+            "--no-explore": "Disable learned routing exploration for this run.",
+            "--mode <risk-based|partner-led|staff-led>": "Override the routing mode for this run.",
+            "--quality": "Compatibility alias for --mode partner-led; cannot combine with --mode.",
+            "--supersedes <run-id>": "Record that this engagement supersedes the named run.",
+        }, examples: ["run --concurrency 2 --driver subprocess --route-strict"],
+    },
+    status: {
+        usage: "status [<run-id>] [options]", description: "Show a named run or the latest run. With --watch --events, stdout is one JSON document per decision event and stderr carries keepalive lines. Do not merge stdout and stderr (2>&1 corrupts the JSON document stream).",
+        options: {
+            "--oneline": "Print a compact snapshot and exit.",
+            "--watch": "Follow updates; on a TTY open Run unless plain output or event streaming is selected.",
+            "--plain": "Use line-mode output with --watch, including on a TTY.",
+            "--events": "With --watch, replay and follow decision events as JSON documents on stdout.",
+            "--jsonl": "Alias for --events.",
+            "--decision-events": "Alias for --events.",
+            "--webhook <url>": "With --watch, POST decision events to this URL.",
+        }, examples: ["status --oneline", "status run-example --watch --plain", "status run-example --watch --events"],
+    },
+    stats: {
+        usage: "stats", description: "Print all-run channel delivery, failure, rescue, author and reviewer statistics. Takes no run ID.",
+        options: {}, examples: ["stats"],
+    },
+    resume: {
+        usage: "resume <run-id> [options]", description: "Continue a run from its journal through production preflight and gates.",
+        options: {
+            "--graph-changed": "Accept and journal a changed graph identity for this run.",
+            "--retry-failed": "Retry failed tasks.",
+            "--driver <auto|herdr|subprocess|orca>": "Choose the execution driver; orca is explicit-only.",
+        }, examples: ["resume run-example --driver subprocess", "resume run-example --retry-failed"],
+    },
+    report: {
+        usage: "report [<run-id>] [options]", description: "Report on a named or latest run. Markdown goes to stdout; redirect stdout to save an execution record beside the spec.",
+        options: {
+            "--md": "Write the Markdown execution record to stdout; does not create a Markdown file.",
+            "--compare <baseline-run-id>": "Include cost, gate and duration deltas with an environment comparability guard.",
+            "--bundle <path>": "Write a portable JSON proof bundle to this local path.",
+        }, examples: ["report run-example --md > feature.record.md", "report run-example --compare run-baseline", "report run-example --bundle proof.json"],
+    },
+    profile: {
+        usage: "profile [reset|discount <run-id> [<task-id>]|discounts] [options]",
+        description: "Show learned routing, reset the history cursor, append a discount or list discounts. Use profile <operation> --help for details.",
+        options: {
+            "--explain <shape> <adapter:model> [sub|api]": "Explain the learned score for a shape and channel (default billing: sub).",
+            "--weight <0|0.5>": "Required for discount: set the evidence weight.",
+            "--reason <text>": "Required for discount: explain the evidence claim.",
+        }, examples: ["profile", "profile --explain implement fake:fake-1 sub", "profile discount run-example T1 --weight 0.5 --reason 'infra incident'", "profile discounts", "profile reset"],
+    },
+    ui: {
+        usage: "ui [<run-id>] [options]", description: "Open the cockpit on a TTY. Delivered views: 1 Home, 4 Run, 5 Evidence. Fleet, Plan and Health remain CLI commands: tickmarkr fleet, tickmarkr plan, tickmarkr doctor. Without a TTY use tickmarkr fleet --print or tickmarkr status --watch.",
+        options: {
+            "--view <home|run|evidence>": "Choose a delivered view; default home (an empty repository opens Home).",
+            "--setup": "Open Run Parks for the positional run ID, or latest run; overrides --view.",
+        }, examples: ["ui", "ui run-example --view run", "ui run-example --view evidence", "ui --setup run-example"],
+    },
+    unlock: {
+        usage: "unlock <run-id> [--yes] | tickmarkr unlock --garbage [--yes]", description: "Remove only a matching, provably dead run lock after confirmation. Live, inaccessible or changed holders refuse; commit rechecks the preview.",
+        options: {
+            "--garbage": "Recover an unparseable lock identified by its bytes/inode; no run ID is invented.",
+            "--yes": "Confirm removal without a TTY prompt; all holder and race checks still apply.",
+        }, examples: ["unlock run-example --yes", "unlock --garbage --yes"],
+    },
+    approve: {
+        usage: "approve <run-id> <task-id> [options]", description: "Append a validated park decision. A running owner may enact it; a closed run requires a separate resume. Decisions cannot be undone.",
+        options: {
+            "--by <name>": "Name the actor (default: current OS user).",
+            "--reason <text>": "Record the decision reason.",
+            "--waive": "Waive only the identified failed gate.",
+            "--uphold": "Uphold a review failure and fund a fixed attempt.",
+            "--recheck": "Request rechecking an infra or failed-gate park; satisfies no gate.",
+            "--review-rounds <N>": "Set a positive integer review-round ceiling with the decision.",
+        }, examples: ["approve run-example T1 --by operator --reason 'ready to proceed'", "approve run-example T1 --recheck --reason 'infra recovered'"],
+    },
+    beat: {
+        usage: "beat <orchestrator|orchestrator-context|overseer|overseer-context|watch> --seat <identity> [options]",
+        description: "Write one supervision beat. The supervising seat's watcher loop repeats it; stopped beats become STALE.",
+        options: {
+            "--seat <identity>": "Required: identify the supervising pane or agent.",
+            "--arm-id <identity>": "Identify this supervision arm.",
+            "--pct <0..100>": "Report current context consumption percentage.",
+            "--threshold-pct <0..100>": "Set the context warning threshold (default 75).",
+            "--stand-down": "Record an explicit handoff and stand down this tier.",
+        }, examples: ["beat overseer --seat supervisor", "beat overseer --seat supervisor --stand-down"],
+    },
+    version: {
+        usage: "version [--dist]", description: "Print the installed package version. Top-level aliases: --version and -v.",
+        options: { "--dist": "Also print the resolved build directory and distribution fingerprint." },
+        examples: ["version", "version --dist"],
+    },
+    verify: {
+        usage: "verify [--base <ref>] [--criteria <file> | --task <id>] [options]",
+        description: "Verify the committed merge-base(base, HEAD)..HEAD diff without a daemon or retries. The verdict and JSON result are written to stdout; progress and diagnostics are written to stderr. Do not merge stdout and stderr (2>&1 corrupts the verdict stream).",
+        options: {
+            "--base <ref>": "Compare against merge-base(ref, HEAD); default main.",
+            "--criteria <file>": "Read acceptance criteria from a file; use this or --task.",
+            "--task <id>": "Read acceptance criteria and default file scope from a compiled task.",
+            "--files <glob>": "Declare file scope; repeat for multiple globs (overrides task scope).",
+            "--author <adapter:model>": "Identify the author channel for independent reviewer selection.",
+            "--baseline <path>": "Read an existing baseline JSON file instead of capturing one.",
+            "--record <run-id>": "Append verification results to the named run journal.",
+            "--json": "Print a machine-readable verdict on stdout.",
+            "--no-review": "Disable semantic review; deterministic gates remain mandatory.",
+            "--no-acceptance": "Disable semantic acceptance even when criteria are supplied.",
+        }, examples: ["verify --base main --task T1 --files 'src/**' --files 'tests/**' --author fake:fake-1 --json", "verify --base main --baseline baseline.json --record run-example --no-review --no-acceptance"],
+    },
+    eval: {
+        usage: "eval [<fixtures-root>]", description: "Discover and validate fixture start/solution directories, seed valid fixtures into temporary git repositories, then clean them up. Defaults to fixtures/eval in the current directory.",
+        options: {}, examples: ["eval", "eval ./fixtures", "eval -- --help"],
+    },
+};
+export const PROFILE_HELP = {
+    reset: {
+        usage: "profile reset", description: "Move the learned-history cursor to the latest run. Writes .tickmarkr/profile-since; preserves all telemetry. Help never resets it.",
+        options: {}, examples: ["profile reset"],
+    },
+    discount: {
+        usage: "profile discount <run-id> [<task-id>] --weight <0|0.5> --reason <text>", description: "Append an evidence discount to .tickmarkr/profile-discounts. Omitting the task ID discounts the entire run.",
+        options: { "--weight <0|0.5>": "Required evidence weight.", "--reason <text>": "Required nonempty reason for the evidence claim." },
+        examples: ["profile discount run-example T1 --weight 0.5 --reason 'infra incident'"],
+    },
+    discounts: {
+        usage: "profile discounts", description: "List recorded evidence discounts without modifying them.", options: {}, examples: ["profile discounts"],
+    },
+};
+export function hasHelpFlag(argv) {
+    for (const arg of argv) {
+        if (arg === "--")
+            break;
+        if (arg === "--help" || arg === "-h")
+            return true;
+    }
+    return false;
+}
+export function commandHelp(command, argv = []) {
+    const operation = argv.find((arg) => arg !== "--help" && arg !== "-h");
+    const nested = command === "profile" && operation && Object.hasOwn(PROFILE_HELP, operation) ? PROFILE_HELP[operation] : undefined;
+    const help = nested ?? (Object.hasOwn(COMMAND_HELP, command) ? COMMAND_HELP[command] : undefined);
+    if (!help)
+        return `usage: tickmarkr ${command}\n  --help, -h  Show help without running the command.`;
+    return [
+        `usage: tickmarkr ${help.usage}`, help.description, "", "Options:",
+        ...Object.entries(help.options).map(([flag, description]) => `  ${flag}  ${description}`),
+        "  --help, -h  Show help without running the command.",
+        "", "Examples:", ...help.examples.map((example) => `  tickmarkr ${example}`),
+        "", "Help flags are recognized only before --; arguments after -- are literal data.",
+    ].join("\n");
+}

package/dist/cli/index.d.ts

@@ -1,11 +1,51 @@
 #!/usr/bin/env node
+import { approve } from "./commands/approve.js";
+import { beat } from "./commands/beat.js";
+import { compile } from "./commands/compile.js";
+import { doctor } from "./commands/doctor.js";
+import { evalCommand } from "./commands/eval.js";
+import { fleet } from "./commands/fleet.js";
+import { init } from "./commands/init.js";
+import { plan } from "./commands/plan.js";
+import { profile } from "./commands/profile.js";
+import { report } from "./commands/report.js";
+import { resume } from "./commands/resume.js";
+import { run } from "./commands/run.js";
+import { scope } from "./commands/scope.js";
+import { stats } from "./commands/stats.js";
+import { status } from "./commands/status.js";
+import { ui } from "./commands/ui.js";
+import { unlock } from "./commands/unlock.js";
+import { verify } from "./commands/verify.js";
+import { version } from "./commands/version.js";
 export type CommandResult = string | {
     out: string;
     code: number;
 };
 export type CommandMap = Record<string, (argv: string[]) => Promise<CommandResult>>;
-export declare const COMMANDS: CommandMap;
-export declare const USAGE = "tickmarkr \u2014 spec-driven orchestration harness for AI coding agents\nusage: tickmarkr <command>\n  init          guided setup + doctor; init --agent [--force] [--docs] adds agent skills/docs\n  doctor        re-probe adapters, herdr, auth; print capability matrix (--fix writes the test-runner ignore when a safe edit exists)\n  fleet         interactive fleet editor (fleet --print for CI drift checks)\n  compile <src> spec \u2192 .tickmarkr/graph.json (fails without acceptance criteria)\n  scope <intent> draft a compiled native spec beside an answered intent (--force to overwrite)\n  plan          dry-run routing table + cost estimate + floor lints\n  eval          run checked-in fixtures against every channel in isolated temp repos\n  run           execute the graph (--concurrency N --driver auto|herdr|subprocess|orca --route-strict; orca runs only when named)\n  status        live run state (--watch --events: JSON documents on stdout, keepalives on stderr; 2>&1 corrupts the stream)\n  stats         all-run channel delivery, red, rescue, author and reviewer statistics\n  verify        run the gate battery standalone against merge-base(--base, HEAD)..HEAD \u2014 verdict/JSON on stdout, progress on stderr; 2>&1 corrupts the verdict stream (--base main --criteria <file> | --task <id> [--files <glob>] [--author adapter:model] [--no-review] [--json])\n  resume <id>   continue a run from its journal\n  report <id>   cost/quality report (--md for committable execution record)\n  profile       show learned routing profile (profile reset = forget history via cursor, keeps telemetry)\n  ui            open the Fleet Studio TUI (full-screen tabbed cockpit)\n  unlock        remove a stale/garbage run lock (refuses if the holder is alive)\n  beat <tier>   record one supervision beat for orchestrator|orchestrator-context|overseer|overseer-context|watch, --seat <identity> required (--stand-down to hand off); a supervising seat's own watcher loop calls it, and status reads the tier STALE once the beats stop\n  approve <id> <task>  release a park (--uphold sides with the reviewer and funds a fixed attempt; --by <name> --reason <text>); takes effect on resume";
+export declare const COMMANDS: {
+    init: typeof init;
+    doctor: typeof doctor;
+    fleet: typeof fleet;
+    compile: typeof compile;
+    scope: typeof scope;
+    plan: typeof plan;
+    run: typeof run;
+    status: typeof status;
+    stats: typeof stats;
+    resume: typeof resume;
+    report: typeof report;
+    profile: typeof profile;
+    ui: typeof ui;
+    unlock: typeof unlock;
+    approve: typeof approve;
+    beat: typeof beat;
+    version: typeof version;
+    verify: typeof verify;
+    eval: typeof evalCommand;
+};
+export type RegisteredCommand = keyof typeof COMMANDS;
+export declare const USAGE = "tickmarkr \u2014 spec-driven orchestration harness for AI coding agents\nusage: tickmarkr <command>\n  init          guided setup + doctor; init --agent [--force] [--docs] adds agent skills/docs\n  doctor        re-probe adapters, herdr, auth; print capability matrix (--fix writes the test-runner ignore when a safe edit exists)\n  fleet         interactive fleet editor (fleet --print for CI drift checks)\n  compile <src> spec \u2192 .tickmarkr/graph.json (fails without acceptance criteria)\n  scope <intent> preview locally with --preview; draft after confirmation or --yes (--force to overwrite)\n  plan          dry-run routing table + cost estimate + floor lints\n  eval          discover and validate fixtures, seed isolated temp repos, then clean them up\n  run           execute the graph (--concurrency N --driver auto|herdr|subprocess|orca --route-strict; orca runs only when named)\n  status        live run state (--watch --events: JSON documents on stdout, keepalives on stderr; 2>&1 corrupts the stream)\n  stats         all-run channel delivery, red, rescue, author and reviewer statistics\n  verify        run the gate battery standalone against merge-base(--base, HEAD)..HEAD \u2014 verdict/JSON on stdout, progress on stderr; 2>&1 corrupts the verdict stream (--base main --criteria <file> | --task <id> [--files <glob>] [--author adapter:model] [--no-review] [--json])\n  resume <id>   continue a run from its journal\n  report <id>   cost/quality report (--md writes Markdown to stdout; redirect to save a record)\n  profile       show learned routing profile (profile reset = forget history via cursor, keeps telemetry)\n  ui            open Home, Run or Evidence (--view home|run|evidence; --setup <id> opens Run Parks)\n  unlock        remove a stale/garbage run lock (refuses if the holder is alive)\n  beat <tier>   record one supervision beat for orchestrator|orchestrator-context|overseer|overseer-context|watch, --seat <identity> required (--stand-down to hand off); a supervising seat's own watcher loop calls it, and status reads the tier STALE once the beats stop\n  approve <id> <task>  release a park (--uphold sides with the reviewer and funds a fixed attempt; --by <name> --reason <text>); takes effect on resume\n  version       print the installed version (--dist adds build location and fingerprint)\n\nUse tickmarkr <command> --help (or -h) for all options and examples.\nUse tickmarkr profile <operation> --help for nested profile help.";
 export declare function dispatch(cmd: string | undefined, argv: string[], commands?: CommandMap): Promise<{
     out: string;
     code: number;

package/dist/cli/index.js

@@ -20,6 +20,7 @@ import { ui } from "./commands/ui.js";
 import { unlock } from "./commands/unlock.js";
 import { verify } from "./commands/verify.js";
 import { version } from "./commands/version.js";
+import { commandHelp, hasHelpFlag } from "./help.js";
 const normalize = (r) => typeof r === "string" ? { out: r, code: 0 } : r;
 export const COMMANDS = {
     init, doctor, fleet, compile, scope, plan, run, status, stats, resume, report, profile, ui, unlock, approve, beat, version, verify, eval: evalCommand,
@@ -33,33 +34,47 @@ usage: tickmarkr <command>
   doctor        re-probe adapters, herdr, auth; print capability matrix (--fix writes the test-runner ignore when a safe edit exists)
   fleet         interactive fleet editor (fleet --print for CI drift checks)
   compile <src> spec → .tickmarkr/graph.json (fails without acceptance criteria)
-  scope <intent> draft a compiled native spec beside an answered intent (--force to overwrite)
+  scope <intent> preview locally with --preview; draft after confirmation or --yes (--force to overwrite)
   plan          dry-run routing table + cost estimate + floor lints
-  eval          run checked-in fixtures against every channel in isolated temp repos
+  eval          discover and validate fixtures, seed isolated temp repos, then clean them up
   run           execute the graph (--concurrency N --driver auto|herdr|subprocess|orca --route-strict; orca runs only when named)
   status        live run state (--watch --events: JSON documents on stdout, keepalives on stderr; 2>&1 corrupts the stream)
   stats         all-run channel delivery, red, rescue, author and reviewer statistics
   verify        run the gate battery standalone against merge-base(--base, HEAD)..HEAD — verdict/JSON on stdout, progress on stderr; 2>&1 corrupts the verdict stream (--base main --criteria <file> | --task <id> [--files <glob>] [--author adapter:model] [--no-review] [--json])
   resume <id>   continue a run from its journal
-  report <id>   cost/quality report (--md for committable execution record)
+  report <id>   cost/quality report (--md writes Markdown to stdout; redirect to save a record)
   profile       show learned routing profile (profile reset = forget history via cursor, keeps telemetry)
-  ui            open the Fleet Studio TUI (full-screen tabbed cockpit)
+  ui            open Home, Run or Evidence (--view home|run|evidence; --setup <id> opens Run Parks)
   unlock        remove a stale/garbage run lock (refuses if the holder is alive)
   beat <tier>   record one supervision beat for orchestrator|orchestrator-context|overseer|overseer-context|watch, --seat <identity> required (--stand-down to hand off); a supervising seat's own watcher loop calls it, and status reads the tier STALE once the beats stop
-  approve <id> <task>  release a park (--uphold sides with the reviewer and funds a fixed attempt; --by <name> --reason <text>); takes effect on resume`;
+  approve <id> <task>  release a park (--uphold sides with the reviewer and funds a fixed attempt; --by <name> --reason <text>); takes effect on resume
+  version       print the installed version (--dist adds build location and fingerprint)
+
+Use tickmarkr <command> --help (or -h) for all options and examples.
+Use tickmarkr profile <operation> --help for nested profile help.`;
 // pure, testable dispatcher: resolves a command, forwards argv, shapes the result — no side effects.
 // unknown/missing cmd → USAGE (exit 1 if a cmd was typed, 0 for bare `tickmarkr`); a handler throw becomes
 // a one-line `tickmarkr <cmd>: <message>` (never a raw stack) at exit 1.
 export async function dispatch(cmd, argv, commands = COMMANDS) {
-    if (cmd && VERSION_FLAGS.has(cmd))
-        return { out: await version(argv), code: 0 };
     const usage = process.stdout.isTTY ? BANNER + USAGE : USAGE;
     if (!cmd || HELP_CMDS.has(cmd))
         return { out: usage, code: 0 };
-    const fn = commands[cmd];
+    if (VERSION_FLAGS.has(cmd))
+        cmd = "version";
+    const fn = Object.hasOwn(commands, cmd) ? commands[cmd] : undefined;
     if (!fn)
         return { out: usage, code: 1 };
+    if (hasHelpFlag(argv))
+        return { out: commandHelp(cmd, argv), code: 0 };
     try {
+        // These two legacy handlers scan the entire argv for help before parsing. Preserve their
+        // direct-call API, but never let a literal positional turn back into help at the CLI boundary.
+        // verify accepts no positionals; status accepts a run ID, which cannot start with a dash.
+        const separator = argv.indexOf("--");
+        const literalHelp = separator < 0 ? undefined : argv.slice(separator + 1).find((arg) => arg === "--help" || arg === "-h");
+        if (literalHelp && (fn === verify || fn === status)) {
+            throw new Error(`literal argument ${JSON.stringify(literalHelp)} after -- ${fn === verify ? "is not accepted: verify takes no positional arguments" : "is not a valid run ID"}`);
+        }
         return normalize(await fn(argv));
     }
     catch (err) {

package/dist/drivers/herdr.d.ts

@@ -1,5 +1,5 @@
 import { type JournalEvent } from "../run/journal.js";
-import { type ExecutorDriver, type NotifyOpts, type PanesToCloseOpts, type Slot, type SlotOpts } from "./types.js";
+import { type ExecutorDriver, type FocusTarget, type FocusResult, type NotifyOpts, type PanesToCloseOpts, type Slot, type SlotOpts } from "./types.js";
 export declare const TRAILER_SAFE_FLOOR_COLS = 108;
 export declare const TRAILER_WIDTH_MARGIN = 2;
 export declare const DELIVERY_ATTEMPTS = 3;
@@ -69,6 +69,7 @@ export declare class HerdrDriver implements ExecutorDriver {
     private ws;
     private callerPane;
     private watches;
+    private watchTokens;
     constructor(bin?: string, workersPerTab?: number, time?: HerdrTimeSource, journal?: DriverJournal | undefined);
     private appendDispatchRetry;
     private appendPaneClose;
@@ -126,9 +127,13 @@ export declare class HerdrDriver implements ExecutorDriver {
     notify(msg: string, opts?: NotifyOpts): Promise<void>;
     close(slot: Slot): Promise<void>;
     private closeGrouped;
-    private ownedWatchPanes;
+    private watchPanes;
+    /** Name collisions never confer repository ownership. Unknown boards stay protected. */
+    private retireWatch;
+    focus(target: FocusTarget): Promise<FocusResult>;
     private watchSlot;
     private discardSplit;
+    /** Only this repository's matching run may replace its acknowledged board. */
     narrator(cwd: string, command: string, runId?: string): Promise<Slot>;
     reconcile(desired: Set<string>, runId: string, opts?: PanesToCloseOpts): Promise<void>;
     worktree(repo: string, branch: string, baseRef: string): Promise<string>;

package/dist/drivers/herdr.js

@@ -6,7 +6,7 @@ import { declaredInputBoxForWorkerName, matchesEmptyInputBox, matchesInputBox, m
 import { consumePaneLaunchIntent, PANE_IDENTITY_ENV, paneIdentityLine } from "../brand.js";
 import { createWorktree, sh } from "../run/git.js";
 import { Journal } from "../run/journal.js";
-import { readSupervision } from "../run/supervision.js";
+import { readSupervision, readWatchBoard, reserveWatchBoard, stopWatchBoard, WATCH_OWNER_ENV } from "../run/supervision.js";
 import { herdrSealShellPrefix } from "./subprocess.js";
 import { canonicalizeLegacyName, formatOwnedName, panesToClose, parseOwnedName } from "./types.js";
 // VIS-09 P43-03: adopted safety floor from 43-MEASUREMENT.md (narrowest safe 53 → floor 108).
@@ -103,6 +103,7 @@ export function boardSplitPlan(_callerCols) {
  *  `role:"other", taskId:"<the whole name>"` for any unrecognised string, so keying on taskId alone
  *  makes EVERY one-off pane its own "task" and gives it a group tab. `watch` is excluded for the same
  *  reason in the other direction — its taskId is the literal "run", which is a board, not a task. */
+const shortTitle = (text) => [...text].slice(0, 20).join("");
 const TASK_TAB_ROLES = new Set(["worker", "judge", "review", "consult"]);
 export function taskGroupOf(name) {
     const { role, taskId } = canonicalizeLegacyName(name, "");
@@ -123,10 +124,10 @@ export function taskGroupOf(name) {
 export function tabLabelFor(name) {
     const { role, taskId, attempt } = canonicalizeLegacyName(name, "");
     if (!TASK_TAB_ROLES.has(role) || !taskId.trim())
-        return name;
+        return shortTitle(name);
     if (role !== "worker")
-        return `${role.toUpperCase()} ${taskId}`;
-    return attempt > 0 ? `${taskId}↻${attempt}` : taskId;
+        return shortTitle(`${role.toUpperCase()} ${taskId}`);
+    return shortTitle(attempt > 0 ? `${taskId}↻${attempt}` : taskId);
 }
 /** Gate panes ride with the task they belong to and never consume the tab cap; everything else does.
  *  Scoped to the three GATE roles deliberately — an earlier cut of this said "not a worker", which let
@@ -168,6 +169,7 @@ export class HerdrDriver {
     ws = process.env.HERDR_WORKSPACE_ID;
     callerPane = process.env.HERDR_PANE_ID;
     watches = new Map();
+    watchTokens = new WeakMap();
     constructor(bin = "herdr", workersPerTab = 3, time = SYSTEM_TIME, journal) {
         this.bin = bin;
         this.workersPerTab = workersPerTab;
@@ -469,7 +471,7 @@ export class HerdrDriver {
         // the worktree — that root pane IS the worker pane. The old one-shot `agent start … -- bash` verb
         // (which named a fresh bash pane) was removed; 0.7.5's `agent start` only ATTACHES to a DETECTED
         // agent CLI, so tickmarkr names the bash pane itself via `pane rename` and types the worker command in.
-        const t = await this.herdr(`tab create --label ${shq(label)} --no-focus --workspace ${shq(this.ws)} --cwd ${shq(cwd)}`);
+        const t = await this.herdr(`tab create --label ${shq(shortTitle(label))} --no-focus --workspace ${shq(this.ws)} --cwd ${shq(cwd)}`);
         if (t.code !== 0)
             throw new Error(`herdr tab create failed (exit ${t.code}, refusing untargeted placement): ${t.stderr || t.stdout}`);
         let res;
@@ -597,7 +599,7 @@ export class HerdrDriver {
         const label = !token ? entry.label
             : entry.label === token ? `${token}${glyph}`
                 : `${entry.label} · ${token}${glyph}`;
-        const cmd = `tab rename ${shq(entry.tabId)} ${shq(label)}`;
+        const cmd = `tab rename ${shq(entry.tabId)} ${shq(shortTitle(label))}`;
         const ok = async () => (await this.herdr(cmd)).code === 0;
         if (await ok() || await ok())
             return;
@@ -1113,12 +1115,10 @@ export class HerdrDriver {
         await this.herdr(`notification show ${shq(msg)} --sound ${opts?.tier === "attention" ? "request" : opts?.sound ?? "request"}`);
     }
     async close(slot) {
-        if (this.watches.get(slot.name)?.id === slot.id) {
+        if (parseOwnedName(slot.name)?.role === "watch") {
+            await this.retireWatch(slot);
             this.watches.delete(slot.name);
-            const pane = await this.namedPaneId(slot.name);
-            if (pane)
-                await this.herdr(`pane close ${shq(pane)}`);
-            return; // run-end reconcile may already have reaped it; never close a compacted stale id
+            return;
         }
         if (slot.group && this.groups.has(slot.group)) {
             return this.serial(() => this.closeGrouped(slot));
@@ -1158,29 +1158,63 @@ export class HerdrDriver {
                 this.groups.delete(slot.group); // group dies when all generations gone
         }
     }
-    // Every surviving tickmarkr-owned board in this workspace — a PRIOR run's and one already wearing
-    // this run's own name alike. Both are retired before a new board opens (narrator): what a pane this
-    // process did not create is actually RUNNING cannot be read back, and the pre-v1.94 implementation
-    // launched a bare `tickmarkr status --watch`, which follows the newest journal.
-    async ownedWatchPanes() {
+    async watchPanes(name) {
         if (!this.ws)
             throw new Error("herdr watch placement requires HERDR_WORKSPACE_ID — refusing unseeded pane");
         const list = await this.herdr("pane list");
         if (list.code !== 0)
             throw new Error(`herdr pane list failed: ${list.stderr || list.stdout}`);
+        const panes = JSON.parse(list.stdout).result?.panes;
+        if (!Array.isArray(panes))
+            throw new Error("herdr pane list returned no panes");
+        return panes.filter(p => p.workspace_id === this.ws && p.label === name);
+    }
+    /** Name collisions never confer repository ownership. Unknown boards stay protected. */
+    async retireWatch(slot) {
+        const runId = parseOwnedName(slot.name)?.runId;
+        const owner = runId ? readWatchBoard(slot.cwd, runId) : undefined;
+        const matches = await this.watchPanes(slot.name);
+        if (matches.length === 0)
+            throw new Error(`watch ${slot.name} closed without presence acknowledgement; cleanup unconfirmed`);
+        if (!owner || owner.driver !== this.id || owner.name !== slot.name || owner.workspace !== this.ws ||
+            (this.watchTokens.has(slot) && this.watchTokens.get(slot) !== owner.token) ||
+            owner.pane !== slot.id || matches.length !== 1 || matches[0]?.pane_id !== owner.pane) {
+            throw new Error(`watch ownership unknown or foreign for ${slot.name}; existing board protected`);
+        }
+        await stopWatchBoard(owner, this.time);
+        const verified = await this.watchPanes(slot.name);
+        if (verified.length !== 1 || verified[0]?.pane_id !== owner.pane)
+            throw new Error("watch target changed after acknowledgement; pane protected");
+        const closed = await this.herdr(`pane close ${shq(owner.pane)}`);
+        if (closed.code !== 0 || await this.paneStillOpen(owner.pane))
+            throw new Error(`watch ${slot.name} survived acknowledged close`);
+    }
+    async focus(target) {
+        const { slot, runId, taskId, attempt } = target;
+        if (slot.name !== formatOwnedName({ role: "worker", taskId, attempt, runId }) || !target.workspace || target.workspace !== this.ws) {
+            return { status: "foreign", reason: "Recorded run/task/attempt or workspace does not match this driver" };
+        }
+        const r = await this.herdr("pane list", slot.cwd);
+        if (r.code !== 0)
+            return { status: "unsupported", reason: "Cannot verify the live pane list" };
         let panes;
         try {
-            panes = JSON.parse(list.stdout).result?.panes;
+            panes = JSON.parse(r.stdout).result?.panes;
         }
         catch {
-            throw new Error(`herdr pane list returned unparseable JSON: ${list.stdout}`);
+            return { status: "unsupported", reason: "Unreadable pane list" };
         }
         if (!Array.isArray(panes))
-            throw new Error(`herdr pane list returned no panes: ${list.stdout}`);
-        return panes.filter((p) => {
-            const owned = typeof p.label === "string" ? parseOwnedName(p.label) : null;
-            return p.workspace_id === this.ws && typeof p.pane_id === "string" && owned?.role === "watch" && owned.taskId === "run";
-        }).map((p) => p.pane_id);
+            return { status: "unsupported", reason: "Missing pane list" };
+        const named = panes.filter(p => p.label === slot.name && p.workspace_id === target.workspace);
+        if (!named.length)
+            return { status: panes.some(p => p.pane_id === slot.id) ? "foreign" : "closed", reason: "Recorded pane is no longer owned by this attempt; open task evidence" };
+        if (named.length !== 1 || named[0]?.pane_id !== slot.id || (slot.tabId && named[0]?.tab_id !== slot.tabId)) {
+            return { status: "foreign", reason: "Live pane identity differs from the recorded task attempt" };
+        }
+        const focused = await this.herdr(`pane focus ${shq(slot.id)}`, slot.cwd);
+        return focused.code === 0 ? { status: "focused", reason: `Verified ${slot.name} in ${target.workspace}` }
+            : { status: "unsupported", reason: focused.stderr || focused.stdout || "Host refused pane focus" };
     }
     // T2: the watch is a sibling of the daemon's own pane, never a separate tab — placed to the RIGHT
     // of it, always, whatever the terminal measures. Its durable owned name is how a
@@ -1243,38 +1277,34 @@ export class HerdrDriver {
         }
         throw new Error(orphan === null ? why : `${why} — and the split pane ${pane} survived its close (${orphan})`);
     }
-    // T6 narrator: the run's single live status surface, RUNNING THE COMMAND THIS CALL SUPPLIED. Only
-    // a board this driver instance itself opened is reused (this.watches); any other surviving board —
-    // a prior run's, or one already carrying this run's canonical name after a resume — is retired and
-    // re-split, because adoption cannot restart or even read the process inside it and a pre-v1.94 pane
-    // is running the bare `tickmarkr status --watch`, which narrates the newest journal instead of this
-    // run. The retirement is VERIFIED gone before the replacement splits: reconcile is no backstop here
-    // (panesToClose skips role "watch" by design, types.ts:92), so an unverified close would leave two
-    // boards bound to different runs. Failures propagate — the daemon swallows.
+    /** Only this repository's matching run may replace its acknowledged board. */
     async narrator(cwd, command, runId) {
-        const name = runId ? formatOwnedName({ role: "watch", taskId: "run", attempt: 0, runId }) : `narrator-watch-${process.pid}`;
+        if (!this.ws)
+            throw new Error("herdr watch placement requires HERDR_WORKSPACE_ID");
+        if (!runId)
+            throw new Error("herdr narrator requires a run identity");
+        const name = formatOwnedName({ role: "watch", taskId: "run", attempt: 0, runId });
         return this.serial(async () => {
+            const matches = await this.watchPanes(name);
             const cached = this.watches.get(name);
-            if (cached)
+            if (cached && matches.length === 1 && matches[0]?.pane_id === cached.id &&
+                readWatchBoard(cwd, runId)?.token === this.watchTokens.get(cached))
                 return cached;
-            const stale = await this.ownedWatchPanes();
-            for (const pane of stale)
-                await this.herdr(`pane close ${shq(pane)}`);
-            if (stale.length) {
-                const survived = (await this.ownedWatchPanes()).filter((p) => stale.includes(p));
-                if (survived.length)
-                    throw new Error(`herdr watch retire failed: ${survived.join(", ")} survived close — refusing a second board`);
-            }
-            const s = await this.watchSlot(cwd, name);
-            this.watches.set(name, s);
+            if (matches.length > 1)
+                throw new Error(`watch ownership ambiguous for ${name}; existing boards protected`);
+            if (matches.length === 1)
+                await this.retireWatch({ id: matches[0].pane_id, name, cwd });
+            const slot = await this.watchSlot(cwd, name);
+            const owner = reserveWatchBoard({ repo: cwd, runId, driver: this.id, workspace: this.ws, pane: slot.id, name });
+            this.watchTokens.set(slot, owner.token);
             try {
-                await this.deliverPersistentShellCommand(s, command);
+                await this.deliverPersistentShellCommand(slot, `${WATCH_OWNER_ENV}=${shq(owner.token)} ${command}`);
+                this.watches.set(name, slot);
+                return slot;
             }
-            catch (err) {
-                this.watches.delete(name);
-                throw err;
+            catch (error) {
+                throw new Error(`watch launch unconfirmed for ${name}; pane protected: ${String(error)}`);
             }
-            return s;
         });
     }
     // OBS-17 T2 / v1.22b T1: close THIS RUN'S OWN tickmarkr-owned panes that should not exist

package/dist/drivers/orca.d.ts

@@ -1,6 +1,6 @@
 import { type ShResult } from "../run/git.js";
 import { type JournalEvent } from "../run/journal.js";
-import { type ExecutorDriver, type NotifyOpts, type Slot, type SlotOpts } from "./types.js";
+import { type ExecutorDriver, type FocusTarget, type FocusResult, type NotifyOpts, type Slot, type SlotOpts } from "./types.js";
 /** The response families the ONE shared envelope parser serves. There is no second JSON seam. */
 export declare const ORCA_RESPONSE_FAMILIES: readonly ["status", "create", "list", "read", "send", "wait", "show", "close", "worktree-current", "worktree-set", "hooks-status"];
 export type OrcaFamily = (typeof ORCA_RESPONSE_FAMILIES)[number];
@@ -200,7 +200,8 @@ export declare class OrcaDriver implements ExecutorDriver {
     waitAgentStatus(slot: Slot, status: string, timeoutMs: number): Promise<boolean>;
     sendKey(slot: Slot, key: string): Promise<void>;
     nudge(slot: Slot, message: string): Promise<boolean>;
-    narrator(cwd: string, command: string, runId?: string): Promise<Slot>;
+    narrator(_cwd: string, _command: string, runId?: string): Promise<Slot>;
+    focus(target: FocusTarget): Promise<FocusResult>;
     project(taskId: string, state: "in-progress" | "in-review" | "completed"): Promise<void>;
     private setWorkspaceStatus;
     notify(msg: string, opts?: NotifyOpts): Promise<void>;