tickmarkr 2.6.6 → 2.6.7

package/dist/adapters/claude-code.js

@@ -216,6 +216,7 @@ export function probeVersion(bin) {
 // OBS-1182: an absent effort renders nothing, so the CLI keeps its own default. Every builder places
 // it right after --model's value and before another flag, never before the prompt positional.
 const claudeEffortFlag = (effort) => (effort ? ` --effort ${shq(effort)}` : "");
+const WORKER_SETTINGS = `'{"promptSuggestionEnabled":false,"remoteControlAtStartup":false}'`;
 export const claudeCode = {
     id: "claude-code",
     vendor: "anthropic",
@@ -253,17 +254,22 @@ export const claudeCode = {
     // live check ate the prompt), and --prompt-suggestions takes an OPTIONAL value — appended directly
     // before the prompt it would swallow it the same way. So the setting's value is always followed by
     // another flag, never by the prompt positional.
+    // Remote Control is OFF for workers: a user's remoteControlAtStartup otherwise registers every pane
+    // worker as a Remote Control session and a local peer, an input channel tickmarkr never records (607 of
+    // 607 interactive workers on one host, 2026-10-05). --settings outranks the user setting (live-checked
+    // against claude 2.1.289: the banner's /rc marker is gone with the key, present without it). The -p form
+    // never registers.
     // OBS-931: the same ONE-argv-string hazard as codex (OBS-930) — over promptArgvCeiling() the TUI
     // launch would E2BIG on Linux, so it returns null → worker-mode-fallback → the headless form.
     // resumeCommand keeps the shape: its contract returns a string (composer delivery is 2.4.3 work).
     interactiveCommand: (promptFile, model, effort) => promptFitsArgv(promptFile)
-        ? `claude --model ${shq(model)}${claudeEffortFlag(effort)} --strict-mcp-config --mcp-config '{"mcpServers":{}}' --settings '{"promptSuggestionEnabled":false}' --prompt-suggestions false --permission-mode bypassPermissions "$(cat ${shq(promptFile)})"`
+        ? `claude --model ${shq(model)}${claudeEffortFlag(effort)} --strict-mcp-config --mcp-config '{"mcpServers":{}}' --settings ${WORKER_SETTINGS} --prompt-suggestions false --permission-mode bypassPermissions "$(cat ${shq(promptFile)})"`
         : null,
     trustDialog: CLAUDE_TRUST_DIALOG,
     inputBox: CLAUDE_INPUT_BOX,
     // A resumed attempt lands in the same painted editor, so it carries the same ghost-text suppression
     // and the same value-then-flag placement.
-    resumeCommand: (sessionId, promptFile, model, effort) => `claude -r ${shq(sessionId)} --model ${shq(model)}${claudeEffortFlag(effort)} --strict-mcp-config --mcp-config '{"mcpServers":{}}' --settings '{"promptSuggestionEnabled":false}' --prompt-suggestions false --permission-mode bypassPermissions "$(cat ${shq(promptFile)})"`,
+    resumeCommand: (sessionId, promptFile, model, effort) => `claude -r ${shq(sessionId)} --model ${shq(model)}${claudeEffortFlag(effort)} --strict-mcp-config --mcp-config '{"mcpServers":{}}' --settings ${WORKER_SETTINGS} --prompt-suggestions false --permission-mode bypassPermissions "$(cat ${shq(promptFile)})"`,
     invoke(task, _cwd, a, ctx) {
         return { command: this.headlessCommand(ctx.promptFile, a.model, a.effort) };
     },

package/dist/adapters/codex-commit-check.d.ts

@@ -31,6 +31,7 @@ export declare function recordCodexCommit(adapters: WorkerAdapter[], health: Rec
 /** Plan's headline beneath a Codex worker row; null for every other worker and for an allowed probe.
  *  An absent field is unknown, but only the real adapter earns the line — stubs stay byte-identical. */
 export declare function codexCommitHeadline(worker: string, adapters: WorkerAdapter[], health: Record<string, AuthHealth>): string | null;
-/** Plan's one line for Codex's NON-worker roles (judge, review, consult): they launch with the same grant, so
- *  only an escape earns it — allowed, protected and unknown concern commits, which those roles never make. */
+/** Plan's one line for Codex's NON-worker roles (judge, review, consult). v2.6.7 T4: those seats launch
+ *  grantless, but they run in the same repository whose shared metadata a Codex worker's grant let the sandbox
+ *  write — so an escape still blocks; allowed, protected and unknown concern commits, which they never make. */
 export declare function codexEscapeRoleLine(roles: string[], adapters: WorkerAdapter[], health: Record<string, AuthHealth>): string | null;

package/dist/adapters/codex-commit-check.js

@@ -4,10 +4,28 @@ import { existsSync, mkdtempSync, readFileSync, rmdirSync, rmSync } from "node:f
 import { tmpdir } from "node:os";
 import { basename, dirname, join } from "node:path";
 import { promisify } from "node:util";
+import { assertGitTrust, GitTrustRefusal, protectedGitEnv } from "../run/git-trust.js";
 import { CODEX_GIT_GRANT, codex } from "./codex.js";
 import { shq } from "./types.js";
 const exec = promisify(execFile);
 const git = async (cwd, ...args) => (await exec("git", args, { cwd })).stdout.trim();
+// v2.6.7 T4: host git after the sandbox has had the fixture — validation and cleanup — runs the uncached trust
+// check and the forced child config on every call, so seat-rewritten metadata can neither run a config program
+// nor answer for the probe's commit.
+const hostGit = async (cwd, ...args) => {
+    assertGitTrust(cwd);
+    return (await exec("git", args, { cwd, env: protectedGitEnv(process.env) })).stdout.trim();
+};
+/** The fixture checkout's trust after the sandbox returned or threw: a refusal is reported with its path. */
+const fixtureRefusal = (worktree) => {
+    try {
+        assertGitTrust(worktree);
+        return undefined;
+    }
+    catch (e) {
+        return unknown(e instanceof GitTrustRefusal ? `the sandbox left untrusted fixture git metadata (${e.message})` : `fixture git trust unreadable (${String(e)})`);
+    }
+};
 const CONTROL = "tickmarkr-codex-commit-control";
 // $1 control, $2 token, $3 hostile hooks member, $4 hostile common-root member. The commit disables hooks (the
 // probe asks what the sandbox permits, never what a user hook decides) and forces the reflog so common/logs is
@@ -48,12 +66,12 @@ const contradictory = (out) => {
     }
     return false;
 };
-const tipOf = async (repo, ref) => git(repo, "rev-parse", "--verify", "--quiet", `${ref}^{commit}`).catch(() => undefined);
+const tipOf = async (repo, ref) => hostGit(repo, "rev-parse", "--verify", "--quiet", `${ref}^{commit}`).catch(() => undefined);
 // This probe's commit and nothing else: one parent (the fixture base), its token in the subject and the control.
 const isProbeCommit = async (repo, commit, base, token) => {
     try {
-        return await git(repo, "log", "-1", "--format=%P %s", commit) === `${base} tickmarkr-probe ${token}`
-            && await git(repo, "cat-file", "blob", `${commit}:${CONTROL}`) === token;
+        return await hostGit(repo, "log", "-1", "--format=%P %s", commit) === `${base} tickmarkr-probe ${token}`
+            && await hostGit(repo, "cat-file", "blob", `${commit}:${CONTROL}`) === token;
     }
     catch {
         return false;
@@ -70,6 +88,7 @@ export async function probeCodexCommit(repoRoot, sandbox = codexSandbox, signal)
     let lock;
     let base;
     let hostile = [];
+    let sandboxed = false;
     try {
         const commonDir = await git(repoRoot, "rev-parse", "--path-format=absolute", "--git-common-dir");
         lock = join(commonDir, "worktrees", basename(worktree), "index.lock");
@@ -84,11 +103,15 @@ export async function probeCodexCommit(repoRoot, sandbox = codexSandbox, signal)
         const control = join(worktree, CONTROL);
         if (existsSync(lock))
             return unknown("a foreign index.lock already holds the fixture worktree");
+        sandboxed = true;
         const out = await sandbox({ worktree, commonDir, branch, control, lock, hostileHook, hostileRoot, token, signal });
-        // An escape on disk dominates; every other verdict needs consistent receipts AND disk.
+        // An escape on disk dominates; every other verdict needs consistent receipts AND disk — and trusted metadata.
         const escape = escaped(hostile, token);
         if (escape)
             return escape;
+        const refused = fixtureRefusal(worktree);
+        if (refused)
+            return refused;
         if (contradictory(out))
             return unknown("the sandbox receipts contradict each other");
         if (!/^control=ok$/m.test(out) || !holds(control, token))
@@ -118,6 +141,9 @@ export async function probeCodexCommit(repoRoot, sandbox = codexSandbox, signal)
         const escape = escaped(hostile, token);
         if (escape)
             return escape;
+        const refused = sandboxed ? fixtureRefusal(worktree) : undefined;
+        if (refused)
+            return refused;
         return unknown(signal?.aborted ? "probe cancelled" : `probe did not run (${(e instanceof Error ? e.message : String(e)).split("\n")[0]})`);
     }
     finally {
@@ -132,7 +158,7 @@ export async function probeCodexCommit(repoRoot, sandbox = codexSandbox, signal)
         // prune — that would take an earlier probe's preserved foreign lock (or anyone's prunable worktree).
         const foreign = lock !== undefined && existsSync(lock);
         if (lock && !foreign) {
-            await git(repoRoot, "worktree", "remove", "--force", worktree).catch(() => undefined);
+            await hostGit(repoRoot, "worktree", "remove", "--force", worktree).catch(() => undefined);
             // a failed `worktree add` leaves metadata git no longer removes by path: drop this probe's own directory
             rmSync(dirname(lock), { recursive: true, force: true });
             try {
@@ -145,7 +171,7 @@ export async function probeCodexCommit(repoRoot, sandbox = codexSandbox, signal)
         // Metadata preserved for a foreign lock keeps its branch too: that checkout's HEAD still names it.
         const tip = base === undefined || foreign ? undefined : await tipOf(repoRoot, ref);
         if (tip && base && (tip === base || await isProbeCommit(repoRoot, tip, base, token))) {
-            await git(repoRoot, "update-ref", "-d", ref, tip).catch(() => undefined);
+            await hostGit(repoRoot, "update-ref", "-d", ref, tip).catch(() => undefined);
         }
         rmSync(parent, { recursive: true, force: true });
     }
@@ -159,7 +185,7 @@ const NOTE = {
 const CONSEQUENCE = {
     protected: "; a Codex worker cannot commit in its worktree",
     allowed: "",
-    escape: "; every Codex role (worker, judge, review, consult) launches with this grant — stop Codex seats and inspect .git/hooks and git config --list --show-origin (core.hooksPath, core.fsmonitor, filter.*, diff.external)",
+    escape: "; every Codex worker (headless and interactive) launches with this grant, while judge, review and consult seats launch grantless — stop Codex seats and inspect .git/hooks and git config --list --show-origin (core.hooksPath, core.fsmonitor, filter.*, diff.external)",
     unknown: "",
 };
 const STATUSES = new Set(Object.keys(NOTE));
@@ -196,10 +222,11 @@ export function codexCommitHeadline(worker, adapters, health) {
         ? "    worker restriction: unknown — the codex linked-worktree commit probe has no verdict; run tickmarkr doctor"
         : null;
 }
-/** Plan's one line for Codex's NON-worker roles (judge, review, consult): they launch with the same grant, so
- *  only an escape earns it — allowed, protected and unknown concern commits, which those roles never make. */
+/** Plan's one line for Codex's NON-worker roles (judge, review, consult). v2.6.7 T4: those seats launch
+ *  grantless, but they run in the same repository whose shared metadata a Codex worker's grant let the sandbox
+ *  write — so an escape still blocks; allowed, protected and unknown concern commits, which they never make. */
 export function codexEscapeRoleLine(roles, adapters, health) {
     if (!roles.length || !adapters.includes(codex) || codexCommitStatus(health) !== "escape")
         return null;
-    return `BLOCKING security warning: codex sandbox escape (doctor probe) — Codex ${roles.join("/")} seats launch with the worker grant that let the sandbox write shared git metadata; ${ESCAPE_ACTION}`;
+    return `BLOCKING security warning: codex sandbox escape (doctor probe) — Codex ${roles.join("/")} seats launch grantless, but the Codex worker grant let the sandbox write shared git metadata they run against; ${ESCAPE_ACTION}`;
 }

package/dist/adapters/codex.js

@@ -97,7 +97,9 @@ function codexRetirement(upgrade) {
 // tickmarkr worktrees keep their gitdir under the MAIN repo's .git/worktrees/<name> — outside the
 // workspace-write sandbox root — so git commit dies on index.lock (incident run-20260709-104447
 // P87-08: "Unable to create …/.git/worktrees/…/index.lock"). Expanded by the launching shell at the
-// worktree cwd, for EVERY Codex role (worker, judge, review, consult share these builders).
+// worktree cwd, for Codex WORKERS only: v2.6.7 T4 (D-1046) — invoke() (the headless worker form, including
+// the interactive size fallback) and interactiveCommand carry it; headlessCommand, which judge, review,
+// consult and the model probe launch, carries no writable_roots at all (those seats never commit).
 // v2.6.6 T9 (K, D-912): the grant is exactly what a linked-worktree branch commit writes — the worktree's
 // own gitdir (only when it differs from the common dir), common/objects, common/refs, common/logs. The
 // shipped [common] grant (and D-910's [common, gitdir]) let a sandboxed seat write <common>/hooks and
@@ -254,6 +256,8 @@ export function codexMcpSuppressionFlags(configPath) {
     }
     return flags.join(" ");
 }
+// The one headless form: `grant` is "" for every non-worker seat and ` ${CODEX_GIT_GRANT}` for the worker.
+const codexExec = (promptFile, model, effort, grant) => `codex exec --sandbox workspace-write ${CODEX_HOOK_TRUST} ${codexMcpSuppressionFlags()}${grant}${codexEffortFlag(effort)} --model ${shq(model)} - < ${shq(promptFile)}`;
 export const codex = {
     id: "codex",
     vendor: "openai",
@@ -268,14 +272,16 @@ export const codex = {
     // --sandbox workspace-write is the autonomous sandbox mode (codex v0.144.1+)
     // MCP suppression built per dispatch (config can change between runs) — see codexMcpSuppressionFlags.
     // CODEX_HOOK_TRUST (OBS-125) clears the per-worktree "Hooks need review" gate while keeping the sandbox.
-    headlessCommand: (promptFile, model, effort) => `codex exec --sandbox workspace-write ${CODEX_HOOK_TRUST} ${codexMcpSuppressionFlags()} ${CODEX_GIT_GRANT}${codexEffortFlag(effort)} --model ${shq(model)} - < ${shq(promptFile)}`,
+    // v2.6.7 T4 (D-1046): grantless — judge, review, consult and probe-model seats read the checkout and
+    // never commit, so they get no writable git metadata. Workers launch through invoke() below.
+    headlessCommand: (promptFile, model, effort) => codexExec(promptFile, model, effort, ""),
     // OBS-930: the visible pane runs the REAL TUI. Codex's TUI takes its prompt only as the [PROMPT]
     // positional (`codex --help`, 0.153.4 — no file/stdin form), so the launch inlines the file exactly
     // as the claude adapter does: the prompt is the LAST positional and every flag value is followed by
     // a flag, never by the prompt. The argv hazard that once forbade this (OBS-889: `countLiveSuites`
     // matched a suite word 140 KB into a finished worker's argv) is closed on the counter side — the
     // census reads a command's first four tokens only — and those four never carry a suite word here.
-    // Same sandbox, hook trust and MCP suppression as the headless form; `-a never` is the TUI's
+    // Same sandbox, hook trust, MCP suppression and worker grant as invoke()'s headless worker form; `-a never` is the TUI's
     // autonomous approval policy (exec has no approvals to configure).
     // OBS-930 (Linux): the inlined prompt is ONE argv string and Linux caps one at 131072 bytes, so a
     // prompt over promptArgvCeiling() returns null → worker-mode-fallback → the headless form (types.ts).
@@ -283,7 +289,7 @@ export const codex = {
         ? `codex -a never -s workspace-write ${CODEX_HOOK_TRUST} ${codexMcpSuppressionFlags()} ${CODEX_GIT_GRANT}${codexEffortFlag(effort)} --model ${shq(model)} "$(cat ${shq(promptFile)})"`
         : null,
     invoke(task, _cwd, a, ctx) {
-        return { command: this.headlessCommand(ctx.promptFile, a.model, a.effort) };
+        return { command: codexExec(ctx.promptFile, a.model, a.effort, ` ${CODEX_GIT_GRANT}`) };
     },
     parse: parseWorkerResult,
     // v1.22 T5: seed [projects."<repoRoot>"] trust_level="trusted" so fresh worktrees never stall on

package/dist/cli/commands/beat.d.ts

@@ -1,3 +1,8 @@
 import { type SupervisionTier } from "../../run/supervision.js";
-export declare function beat(argv: string[], cwd?: string): Promise<string>;
+import { type BeatLifecycleDeps } from "../../run/beat-lifecycle.js";
+export declare function beat(argv: string[], cwd?: string, deps?: BeatLifecycleDeps): Promise<string | {
+    out: string;
+    code: number;
+}>;
+/** Record an explicit hand-off: the tier reads DISARMED, a stood-down tier, not a dead one. */
 export declare function standDownTier(repoRoot: string, tier: SupervisionTier, seat: string): string;

package/dist/cli/commands/beat.js

@@ -1,99 +1,146 @@
-import { randomUUID } from "node:crypto";
-import { mkdirSync, renameSync, writeFileSync } from "node:fs";
-import { dirname } from "node:path";
-import { tickmarkrDir } from "../../graph/graph.js";
-import { SUPERVISION_BEAT_MS, SUPERVISION_DEFAULT_THRESHOLD_PCT, SUPERVISION_STALE_MS, SUPERVISION_TIERS, beatSupervision, newSupervisionArm, resolveSupervisionRoot, supervisionStandDownPath, } from "../../run/supervision.js";
-// One-shot ticks reuse a durable arm; only --new-arm (or --loop) acknowledges a stand-down.
-// The loop runs in this process, so its recorded pid belongs to the actual repeating writer.
-// Writes are unguarded and a refused ONE-SHOT tick THROWS: the shipped watcher gates on the exit
-// code with stdout discarded, so a refusal that exits 0 leaves a live watcher believing it is armed
-// while status reads DISARMED. Only the loop returns on stand-down — exiting is its designed end.
-const VALUE_OPTIONS = ["--seat", "--arm-id", "--pct", "--threshold-pct"];
-export async function beat(argv, cwd = process.cwd()) {
-    const standDown = argv.includes("--stand-down");
-    const seat = seatOf(argv);
-    const pct = percentageOf(argv, "--pct");
-    const thresholdPct = percentageOf(argv, "--threshold-pct") ?? SUPERVISION_DEFAULT_THRESHOLD_PCT;
-    const armId = optionOf(argv, "--arm-id");
-    const named = argv.find((a, i) => !a.startsWith("--") && !VALUE_OPTIONS.includes(argv[i - 1] ?? ""));
-    if (!isTier(named)) {
-        throw new Error(`usage: tickmarkr beat <${SUPERVISION_TIERS.join("|")}> --seat <identity> ` +
-            `[--new-arm] [--loop] [--arm-id <identity> --pct <0..100> --threshold-pct <0..100>] [--stand-down] — ` +
-            `got ${named ? `\`${named}\`` : "no tier"}`);
+import { parseArgs } from "node:util";
+import { SUPERVISION_BEAT_MS, SUPERVISION_DEFAULT_THRESHOLD_PCT, SUPERVISION_STALE_MS, SUPERVISION_TIERS, beatSupervision, locateSupervisionRoot, newSupervisionArm, publishStandDown, readSupervisionArm, resolveSupervisionRoot, } from "../../run/supervision.js";
+import { BEAT_GENERATION_ENV, beatStatus, defaultBeatDeps, startBeat, stopBeat, withLegacyClaim, } from "../../run/beat-lifecycle.js";
+// Two forms share one strict parser. The lifecycle verbs `start|stop|status <tier>` own a DETACHED loop
+// (src/run/beat-lifecycle.ts); the legacy `<tier>` form keeps its duties: one-shot ticks reuse a durable
+// arm, only --new-arm (or --loop) acknowledges a stand-down, and --status is the read-only status verb.
+// Every refusal is NONZERO: the shipped watcher gates on the exit code with stdout discarded, so a refusal
+// that exits 0 leaves a live watcher believing it is armed while status reads DISARMED — and a loop that is
+// stood down, superseded or cannot write exits nonzero with its reason instead of going silently quiet.
+const VERBS = ["start", "stop", "status"];
+const LEGACY_WRITER_OPTIONS = ["new-arm", "loop", "arm-id", "pct", "threshold-pct", "stand-down"];
+const usage = (got) => `usage: tickmarkr beat <start|stop|status> <tier> --seat <identity> | tickmarkr beat <${SUPERVISION_TIERS.join("|")}> --seat <identity> ` +
+    `[--new-arm] [--loop] [--arm-id <identity> --pct <0..100> --threshold-pct <0..100>] [--stand-down] [--status] — ` +
+    `got ${got ? `\`${got}\`` : "no tier"}`;
+export async function beat(argv, cwd = process.cwd(), deps = defaultBeatDeps()) {
+    const parsed = parseBeat(argv);
+    const { verb, tier, seat, values } = parsed;
+    if (verb === "status" || values.status) {
+        // Read-only by construction: locating the root never creates it, and a repository without a state
+        // dir has, truthfully, no beat recorded.
+        const { root, state } = locateSupervisionRoot(cwd);
+        return state ? beatStatus(root, tier, seat, deps) : { out: `${tier} ABSENT — no state directory`, code: 0 };
     }
     // SUP-05: NO SEAT, NO BEAT — and the refusal comes before any write, so a refused invocation leaves
-    // the tier exactly as it found it. In one-shot mode the exitedWriterPid it records has
-    // already exited by the time anyone reads the record, so tier + writer + instant is a beat nobody can
-    // attribute to a seat. Measured 2026-08-26: a consult seat ran the documented loop verbatim and the
-    // board read that tier ARMED with no seat of that tier having armed anything, and a seatless ARMED
-    // reads as coverage — worse than ABSENT, because ABSENT sends someone to look.
+    // the tier exactly as it found it. Tier + writer + instant is a beat nobody can attribute to a seat
+    // (measured 2026-08-26), and a seatless ARMED reads as coverage — worse than ABSENT.
     if (!seat) {
-        throw new Error(`${named} needs --seat <identity> — a beat that names no seat arms a tier nobody occupies` +
+        throw new Error(`${verb ? `${verb} ${tier}` : tier} needs --seat <identity> — a beat that names no seat arms a tier nobody occupies` +
             " (pass the seat's own pane id or agent name)");
     }
     // A beat names repository state, never the caller's incidental directory. Resolution is read-only
     // and happens before every write, so a non-repository invocation cannot create the state it claims.
     const repoRoot = resolveSupervisionRoot(cwd);
-    if (standDown)
-        return standDownTier(repoRoot, named, seat);
-    const loop = argv.includes("--loop");
-    const arm = argv.includes("--new-arm") || loop ? newSupervisionArm(repoRoot, named, armId) : undefined;
+    if (verb === "start")
+        return startBeat(repoRoot, tier, seat, deps);
+    if (verb === "stop")
+        return stopBeat(repoRoot, tier, seat, deps);
+    const generation = deps.env[BEAT_GENERATION_ENV]?.trim() || undefined;
+    const writer = (settled = false, arm) => ({ generation, seat, settled, arm, deps });
+    if (values["stand-down"]) {
+        return withLegacyClaim(repoRoot, tier, writer(), (recheck) => { recheck(); return standDownTier(repoRoot, tier, seat); });
+    }
+    const loop = values.loop === true;
+    const armId = values["arm-id"];
+    const pct = percentage(values.pct, "--pct");
+    const thresholdPct = percentage(values["threshold-pct"], "--threshold-pct") ?? SUPERVISION_DEFAULT_THRESHOLD_PCT;
     // Context arm ids retain their existing obligation semantics; they do not implicitly re-arm liveness.
-    const observation = pct === undefined ? undefined : { armId: armId ?? arm?.armId ?? seat, pct, thresholdPct };
-    do {
-        if (!beatSupervision(repoRoot, named, seat, observation, { arm, armId, loop })) {
-            const refusal = `${named} DISARMED — stood down; use --new-arm to resume beating`;
-            if (loop)
-                return refusal;
-            throw new Error(refusal);
+    const observe = (arm) => pct === undefined ? undefined : { armId: armId ?? arm?.armId ?? seat, pct, thresholdPct };
+    // EVERY mutation — the one-shot tick, the arm, and each later loop tick — runs under the tier claim, and
+    // `recheck` re-reads that claim and the tier's ownership immediately before the write: a generation-carrying
+    // writer mutates only while its COMPLETE generation (token, seat, pid once settled, and the owner's durable
+    // arm id + epoch) is on record; every other writer only while no detached beat owns the tier. `created` marks
+    // the arm this same claim just published: an owned re-arm rebinds the owner record to it — only while that arm
+    // and the owner checked before it are still the ones on disk — and is checked again as that new generation
+    // before its beat. A running loop carries its arm into every check. A claim someone else holds refuses with
+    // no bytes changed.
+    const tick = (recheck, arm, created = false) => {
+        recheck(arm, created);
+        if (beatSupervision(repoRoot, tier, seat, observe(arm), { arm, armId, loop }))
+            return;
+        const current = arm && readSupervisionArm(repoRoot, tier);
+        if (arm && (current?.armId !== arm.armId || current.armEpoch !== arm.armEpoch)) {
+            throw new Error(`${tier} superseded — a newer arm replaced this loop's arm ${arm.armId}; exiting`);
         }
-        if (!loop)
-            break;
-        await new Promise((resolve) => setTimeout(resolve, SUPERVISION_BEAT_MS));
-    } while (loop);
-    return `${named} ARMED as ${seat} — beat again every ${SUPERVISION_BEAT_MS / 1_000}s; the tier reads STALE ${SUPERVISION_STALE_MS / 1_000}s after the last beat`;
-}
-/** `--seat <identity>` or `--seat=<identity>`; blank and missing are the same answer — none. */
-function seatOf(argv) {
-    const seat = optionOf(argv, "--seat")?.trim();
-    return seat && !seat.startsWith("--") ? seat : undefined;
+        throw new Error(`${tier} DISARMED — stood down; use --new-arm to resume beating`);
+    };
+    if (values["new-arm"] || loop) {
+        const arm = await withLegacyClaim(repoRoot, tier, writer(), (recheck) => {
+            recheck();
+            const created = newSupervisionArm(repoRoot, tier, armId);
+            tick(recheck, created, true);
+            return created;
+        });
+        // ponytail: a running loop outlasts a brief claim holder (a repeat start, a status-side stop) for ~5 s of
+        // retries, then refuses nonzero; a per-tick deadline if holders ever legitimately run longer.
+        const waits = { tries: 20, sleep: deps.sleep };
+        while (loop) {
+            await deps.sleep(SUPERVISION_BEAT_MS);
+            await withLegacyClaim(repoRoot, tier, writer(true, arm), (recheck) => tick(recheck, arm), waits);
+        }
+    }
+    else
+        await withLegacyClaim(repoRoot, tier, writer(), (recheck) => tick(recheck));
+    return `${tier} ARMED as ${seat} — beat again every ${SUPERVISION_BEAT_MS / 1_000}s; the tier reads STALE ${SUPERVISION_STALE_MS / 1_000}s after the last beat`;
 }
-/** A `--name value` or `--name=value` option, excluding a missing value or the next flag. */
-function optionOf(argv, name) {
-    const inline = argv.find((a) => a.startsWith(`${name}=`))?.slice(name.length + 1).trim();
-    const spaced = argv[argv.indexOf(name) + 1]?.trim();
-    const value = inline ?? (argv.includes(name) ? spaced : undefined);
-    return value && !value.startsWith("--") ? value : undefined;
+/** Unknown, duplicate, conflicting or empty options refuse here — before anything is read or written. */
+function parseBeat(argv) {
+    let parsed;
+    try {
+        parsed = parseArgs({
+            args: argv, allowPositionals: true, strict: true, tokens: true,
+            options: {
+                seat: { type: "string" }, "new-arm": { type: "boolean" }, loop: { type: "boolean" },
+                "arm-id": { type: "string" }, pct: { type: "string" }, "threshold-pct": { type: "string" },
+                "stand-down": { type: "boolean" }, status: { type: "boolean" },
+            },
+        });
+    }
+    catch (error) {
+        throw new Error(`${error.message} — ${usage(undefined).replace(/ — got .*$/, "")}`);
+    }
+    const seen = new Set();
+    for (const token of parsed.tokens) {
+        if (token.kind !== "option")
+            continue;
+        if (seen.has(token.name))
+            throw new Error(`duplicate --${token.name} — pass each option once`);
+        seen.add(token.name);
+        if (typeof token.value === "string" && !token.value.trim())
+            throw new Error(`--${token.name} needs a non-empty value`);
+    }
+    const values = parsed.values;
+    const [first, ...rest] = parsed.positionals;
+    const verb = VERBS.includes(first ?? "") ? first : undefined;
+    const named = verb ? rest[0] : first;
+    if (!isTier(named))
+        throw new Error(usage(verb && named === undefined ? `${verb} with no tier` : named));
+    const extra = (verb ? rest.slice(1) : rest)[0];
+    if (extra !== undefined)
+        throw new Error(`unexpected argument \`${extra}\` — ${usage(named).replace(/ — got .*$/, "")}`);
+    const readOnly = verb !== undefined || values.status;
+    const writer = LEGACY_WRITER_OPTIONS.find((name) => values[name] !== undefined);
+    if (readOnly && writer)
+        throw new Error(`--${writer} conflicts with ${verb ? `beat ${verb}` : "--status"}`);
+    if (verb && values.status)
+        throw new Error(`--status conflicts with beat ${verb}`);
+    const withStandDown = values["stand-down"] && LEGACY_WRITER_OPTIONS.find((name) => name !== "stand-down" && values[name] !== undefined);
+    if (withStandDown)
+        throw new Error(`--${withStandDown} conflicts with --stand-down`);
+    return { ...(verb ? { verb } : {}), tier: named, ...(values.seat ? { seat: values.seat.trim() } : {}), values };
 }
-function percentageOf(argv, name) {
-    const raw = optionOf(argv, name);
-    if (raw === undefined) {
-        if (argv.includes(name) || argv.some((a) => a.startsWith(`${name}=`))) {
-            throw new Error(`${name} needs a number from 0 through 100`);
-        }
+function percentage(raw, name) {
+    if (raw === undefined)
         return undefined;
-    }
     const value = Number(raw);
     if (!Number.isFinite(value) || value < 0 || value > 100) {
         throw new Error(`${name} must be a number from 0 through 100`);
     }
     return value;
 }
-// Stand-down is a RECORDED act, not a silence: the marker tells a reader this watcher left on purpose,
-// so the tier reads DISARMED rather than ageing out as a death. Published atomically — written aside,
-// renamed over — because a torn marker is rejected by the reader, and a rejected stand-down reports a
-// deliberate hand-off as a death.
+/** Record an explicit hand-off: the tier reads DISARMED, a stood-down tier, not a dead one. */
 export function standDownTier(repoRoot, tier, seat) {
-    tickmarkrDir(repoRoot); // the write path DOES create — markers land inside the gitignored state dir
-    const p = supervisionStandDownPath(repoRoot, tier);
-    const tmp = `${p}.${randomUUID()}.tmp`;
-    mkdirSync(dirname(p), { recursive: true });
-    // The marker names the seat for the same reason the beat does: "someone stood this tier down" is not
-    // a hand-off anyone can act on, and on a seat tier the reader rejects an anonymous one outright.
-    writeFileSync(tmp, JSON.stringify({
-        tier, seat, standDownId: randomUUID(), exitedWriterPid: process.pid, disarmedAt: new Date().toISOString(),
-    }) + "\n");
-    renameSync(tmp, p);
+    publishStandDown(repoRoot, tier, seat);
     return `${tier} DISARMED — ${seat} handed off; status reads it stood down, not dead`;
 }
 const isTier = (v) => SUPERVISION_TIERS.includes(v ?? "");