tickmarkr 2.6.5 → 2.6.7

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 ?? "");

package/dist/cli/commands/doctor.js

@@ -15,6 +15,7 @@ import { HerdrDriver } from "../../drivers/herdr.js";
 import { ORCA_FIXTURE_VERSION, parseEnvelope, resolveOrcaCliBinary } from "../../drivers/orca.js";
 import { kimi, probeKimiDoctorTurn } from "../../adapters/kimi.js";
 import { recordCodexCommit } from "../../adapters/codex-commit-check.js";
+import { codex } from "../../adapters/codex.js";
 import { denyPreferCollisionLine, denyPreferCollisions, disallowedBy, excludedChannels, exclusionLine, observedSeat, preferRanks } from "../../route/preference.js";
 import { CATALOG_REFRESH_TIMEOUT_MS, LIVEBENCH_TABLE_DATE, formatCatalogRefreshLegs, readCachedCatalog, refreshCatalogCommand } from "../../adapters/catalog-remote.js";
 import { sh } from "../../run/git.js";
@@ -672,7 +673,8 @@ export async function doctor(_argv, cwd = process.cwd(), adapters = allAdapters(
         const h = health[a.id];
         // OBS-503: a crash-on-version verdict carries its reason in note — print it instead of the lie.
         const state = !h.installed ? (h.note ?? "not installed") : `${h.version ?? "installed"}${h.note ? ` (${h.note})` : ""}`;
-        const healthy = h.installed && (a.id !== kimi.id || h.authed);
+        // v2.6.6 T9 (K): a Codex sandbox escape is a BLOCKING security warning — never a passing row
+        const healthy = h.installed && (a.id !== kimi.id || h.authed) && !(a.id === codex.id && h.codexCommit === "escape");
         return alignedStatusRow(healthy ? "pass" : "fail", a.id, state);
     });
     const reviewDemotions = recentReviewDemotions(cwd);