tickmarkr 2.4.1 → 2.5.0

package/dist/cli/commands/stats.js

@@ -1,6 +1,7 @@
 import { existsSync, readdirSync } from "node:fs";
 import { join } from "node:path";
 import { stateDirName } from "../../graph/graph.js";
+import { assignmentChannel, buildOperatorRecord, formatOperatorRecordRow } from "../../report/operator-record.js";
 import { Journal } from "../../run/journal.js";
 import { normalizeGateOutcome } from "../../run/outcome.js";
 // The operator-facing schema is deliberately closed. Adding a fact to the table therefore requires
@@ -17,20 +18,15 @@ export const STATS_COLUMNS = [
     "infra reds",
     "within-task rescues",
 ];
-const assignmentAuthor = (data) => {
-    const assignment = data.assignment;
-    if (!assignment || typeof assignment !== "object")
-        return undefined;
-    const { adapter, model } = assignment;
-    return typeof adapter === "string" && typeof model === "string"
-        ? `${adapter}:${model}`
-        : undefined;
-};
+const assignmentAuthor = assignmentChannel;
 // Current journals write the reviewer into review prose; the structured field is also accepted so
 // journals produced through gateResultJournalData retain their stronger identity representation.
 const reviewerFrom = (data) => {
     if (typeof data.reviewer === "string" && data.reviewer.trim())
         return data.reviewer.trim();
+    const meta = typeof data.meta === "object" && data.meta !== null ? data.meta : undefined;
+    if (meta && "reviewer" in meta && typeof meta.reviewer === "string" && meta.reviewer.trim())
+        return meta.reviewer.trim();
     if (typeof data.details !== "string")
         return undefined;
     return /\breviewer(?:\s+|:\s*)([\w@./+-]+:[\w@./+-]+)/iu.exec(data.details)?.[1];
@@ -79,8 +75,10 @@ export function collectChannelStats(cwd = process.cwd()) {
         }
         return channel;
     };
+    const allEvents = [];
     for (const runId of runIds) {
         const events = Journal.open(cwd, runId).read();
+        allEvents.push(...events);
         const tasks = new Map();
         for (const [eventIndex, event] of events.entries()) {
             if (!event.taskId)
@@ -124,6 +122,16 @@ export function collectChannelStats(cwd = process.cwd()) {
                 }
                 continue;
             }
+            if (event.event === "review-leg2") {
+                const author = dispatchedAuthorFor(history, event.data)
+                    ?? (typeof event.data.author === "string" && event.data.author.includes(":") ? event.data.author : undefined);
+                if (author) {
+                    const reviewer = reviewerFrom(event.data);
+                    if (reviewer)
+                        channelFor(author).reviewers.add(reviewer);
+                }
+                continue;
+            }
             if (event.event !== "gate-result")
                 continue;
             const author = dispatchedAuthorFor(history, event.data);
@@ -170,26 +178,37 @@ export function collectChannelStats(cwd = process.cwd()) {
             infraReds: channel.infraReds,
             rescues: [...channel.rescues].sort((a, b) => a.localeCompare(b, "en")),
         })),
+        operatorRecords: buildOperatorRecord(allEvents),
     };
 }
 const percent = (rate) => `${Number((rate * 100).toFixed(1))}%`;
 export function renderStats(report) {
     const lines = [`tickmarkr stats — ${report.runs} run${report.runs === 1 ? "" : "s"}`];
-    if (report.channels.length === 0)
+    if (report.channels.length === 0 && (!report.operatorRecords || report.operatorRecords.length === 0)) {
         return [...lines, "no channels"].join("\n");
-    lines.push(STATS_COLUMNS.join(" | "));
-    for (const channel of report.channels) {
-        lines.push([
-            channel.author,
-            channel.reviewers.join(", ") || "—",
-            channel.dispatches,
-            channel.deliveries,
-            percent(channel.deliveryRate),
-            channel.attemptsToGreen === null ? "—" : Number(channel.attemptsToGreen.toFixed(2)),
-            channel.realReds,
-            channel.infraReds,
-            channel.rescues.join("; ") || "—",
-        ].join(" | "));
+    }
+    if (report.channels.length > 0) {
+        lines.push(STATS_COLUMNS.join(" | "));
+        for (const channel of report.channels) {
+            lines.push([
+                channel.author,
+                channel.reviewers.join(", ") || "—",
+                channel.dispatches,
+                channel.deliveries,
+                percent(channel.deliveryRate),
+                channel.attemptsToGreen === null ? "—" : Number(channel.attemptsToGreen.toFixed(2)),
+                channel.realReds,
+                channel.infraReds,
+                channel.rescues.join("; ") || "—",
+            ].join(" | "));
+        }
+    }
+    if (report.operatorRecords && report.operatorRecords.length > 0) {
+        lines.push("");
+        lines.push("channels:");
+        for (const row of report.operatorRecords) {
+            lines.push(`  ${formatOperatorRecordRow(row)}`);
+        }
     }
     return lines.join("\n");
 }

package/dist/cli/commands/status.js

@@ -13,9 +13,8 @@ import { isPidLive, runLockRunId, runStatusLine } from "../../run/lock.js";
 import { normalizeGateOutcome } from "../../run/outcome.js";
 import { desiredPanes } from "../../run/reconcile.js";
 import { normalizeStallSnapshot } from "../../run/stall.js";
-import { armWatchSupervision, readSupervision, supervisionText } from "../../run/supervision.js";
+import { armWatchSupervision, observeNamedRun, WATCH_OWNER_ENV, readSupervision, supervisionText } from "../../run/supervision.js";
 import { deriveRunCockpitData, } from "../../tui/cockpit/derive.js";
-import { COCKPIT_COLUMN_FLOOR } from "../../tui/cockpit/layout.js";
 import { cellWidth, fitCells, wrapCells } from "../../tui/cockpit/width.js";
 import { version } from "./version.js";
 // The board is a LIVE surface, so it draws through brand.ts's operator role map and never the vivid
@@ -1093,7 +1092,7 @@ binaryVersion, now = Date.now(), animationFrame = 0, workerLiveness = new Map(),
     }
     // TTY: the operator-approved task table. The daemon gives this surface a ~110-column pane first;
     // narrower terminals keep the same facts in stacked rows. Every cut/wrap goes through width.ts.
-    const boardColumns = Math.max(COCKPIT_COLUMN_FLOOR, width);
+    const boardColumns = Math.max(40, width);
     const dot = dim(" · ");
     const separator = `  ${dim("│")}  `;
     const tipFailed = tipPhase?.state === "failed";
@@ -1343,6 +1342,15 @@ export async function status(argv, cwd = process.cwd(), opts = {}) {
     const sleep = opts.sleep ?? defaultSleep;
     const now = opts.now ?? Date.now;
     const bounded = Number.isFinite(iterations);
+    // Bounded snapshots and printed twins never import Ink. Public interactive watch
+    // selects its run once through the same launcher as manual UI.
+    if (!bounded && !eventStream && !argv.includes("--plain") && process.stdin.isTTY === true && process.stdout.isTTY === true) {
+        const { ui } = await import("./ui.js");
+        const result = await ui([...(namedRunId ? [namedRunId] : []), "--view", "run"], {}, cwd);
+        if (typeof result !== "string")
+            throw new Error(result.out);
+        return "";
+    }
     const frames = [];
     const eventLines = [];
     const sep = "\n---\n";
@@ -1455,7 +1463,8 @@ export async function status(argv, cwd = process.cwd(), opts = {}) {
     // it INVERTS it: armSupervision's interval outlives the board in any host that outlives one board, so
     // a dead board keeps writing and reads ARMED. That is the over-claiming direction, the one an operator
     // acts on, and the one this instrument exists to close.
-    const armed = bounded ? undefined : armWatchSupervision(cwd, opts.supervisionBeatMs);
+    const boardObservation = !bounded && namedRunId && process.env[WATCH_OWNER_ENV] ? observeNamedRun(cwd, namedRunId) : undefined;
+    const armed = bounded || boardObservation ? undefined : armWatchSupervision(cwd, opts.supervisionBeatMs);
     let alternateScreen = false;
     const leaveAlternateScreen = () => {
         if (!alternateScreen)
@@ -1491,6 +1500,8 @@ export async function status(argv, cwd = process.cwd(), opts = {}) {
         if (exitingFromSignal)
             return;
         exitingFromSignal = true;
+        armed?.disarm();
+        boardObservation?.close();
         if (titleSaved) {
             process.removeListener("exit", restoreTitle);
             restoreTitle();
@@ -1507,6 +1518,8 @@ export async function status(argv, cwd = process.cwd(), opts = {}) {
         process.stdout.write(ENTER_ALTERNATE_SCREEN);
         alternateScreen = true;
         process.once("exit", leaveAlternateScreen);
+    }
+    if (!bounded) {
         for (const [signal, code] of [["SIGINT", 130], ["SIGTERM", 143]]) {
             const handler = exitFromSignal(code);
             signalHandlers.push([signal, handler]);
@@ -1515,6 +1528,8 @@ export async function status(argv, cwd = process.cwd(), opts = {}) {
     }
     try {
         for (let i = 0; i < iterations; i++) {
+            if (boardObservation?.stopRequested())
+                break;
             const nowMs = now();
             const decisionEvents = eventStream || webhookUrl ? consumeDecisionEvents() : [];
             let frame;
@@ -1558,6 +1573,7 @@ export async function status(argv, cwd = process.cwd(), opts = {}) {
         // armSupervision's presence files). Otherwise the first pane closed would render the second
         // pane's own tier down while it is drawing frames.
         armed?.disarm();
+        boardObservation?.close();
         if (titleSaved) {
             process.removeListener("exit", restoreTitle);
             restoreTitle();

package/dist/cli/commands/ui.js

@@ -1,64 +1,53 @@
+import { join } from "node:path";
+import { Journal, parseRunId } from "../../run/journal.js";
+import { stateDirName } from "../../graph/graph.js";
+import { JournalTail } from "../../tui/cockpit/live-store.js";
 const NON_TTY_MSG = "tickmarkr ui: the cockpit requires a TTY — use `tickmarkr fleet --print` or `tickmarkr status --watch` for line-mode output";
-/**
- * The setup surface's own flag. `tickmarkr ui --setup [run-id]` opens the one
- * surface that writes — parked human decisions, approved or upheld through the
- * production command path behind an explicit confirm.
- */
-const SETUP_FLAG = "--setup";
 export async function ui(argv, io = {}, cwd = process.cwd()) {
     const input = io.input ?? process.stdin;
     const output = io.output ?? process.stdout;
-    if (input.isTTY !== true || output.isTTY !== true) {
+    if (input.isTTY !== true || output.isTTY !== true)
         return { out: NON_TTY_MSG, code: 1 };
-    }
-    if (argv.includes("--demo")) {
-        const { runCockpitDemo } = await import("../../tui/cockpit/demo.js");
-        const { version } = await import("./version.js");
-        await runCockpitDemo({
-            input,
-            output,
-            binaryVersion: await version(),
-        });
-        return "ui: closed";
-    }
-    const setup = argv.includes(SETUP_FLAG);
-    const unknownFlag = argv.find((arg) => arg.startsWith("-") && arg !== SETUP_FLAG);
-    if (unknownFlag) {
-        return { out: `tickmarkr ui: unknown flag ${unknownFlag}`, code: 1 };
-    }
-    const live = await import("../../tui/cockpit/live.js");
-    const { version } = await import("./version.js");
-    const binaryVersion = await version();
-    const explicit = argv.find((arg) => !arg.startsWith("-"));
-    let runId;
+    let explicit;
+    let view = "home";
+    let setup = false;
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === "--setup")
+            setup = true;
+        else if (arg === "--view") {
+            const value = argv[++i];
+            if (value !== "home" && value !== "run" && value !== "evidence")
+                return { out: "tickmarkr ui: --view must be home, run or evidence", code: 1 };
+            view = value;
+        }
+        else if (arg.startsWith("-"))
+            return { out: `tickmarkr ui: unknown flag ${arg}`, code: 1 };
+        else if (explicit !== undefined)
+            return { out: "tickmarkr ui: expected at most one run ID", code: 1 };
+        else
+            explicit = arg;
+    }
+    let runId = null;
     try {
-        runId = live.selectEngagementRunId(cwd, explicit);
+        runId = explicit === undefined ? Journal.latestRunId(cwd, { withJournal: true }) : parseRunId(explicit);
+        // Refuse an invalid explicit target before importing or borrowing the terminal.
+        if (runId) {
+            const initial = new JournalTail(join(cwd, stateDirName(cwd), "runs", runId, "journal.jsonl")).poll();
+            if (initial.status === "unreadable" || initial.status === "corrupt")
+                throw new Error(initial.error?.error ?? initial.errors[0]?.error ?? "journal corrupt");
+        }
     }
     catch (error) {
-        return { out: `tickmarkr ui: ${error.message}`, code: 1 };
-    }
-    if (runId === null) {
-        return {
-            out: "tickmarkr ui: no engagement found — start one with `tickmarkr run` first",
-            code: 1,
-        };
+        return { out: `tickmarkr ui: cannot read engagement ${runId ?? explicit ?? "latest"}: ${error.message}`, code: 1 };
     }
-    // Refuse before drawing anything: unreadable journal bytes must never
-    // become a plausible surface derived from nothing.
-    try {
-        live.deriveLiveRunCockpitData(live.loadEngagementSource(cwd, runId), binaryVersion);
-    }
-    catch (error) {
-        return {
-            out: `tickmarkr ui: cannot read engagement ${runId}: ${error.message}`,
-            code: 1,
-        };
-    }
-    if (setup) {
-        const { runSetupDecisionsCockpit } = await import("../../tui/cockpit/setup-cockpit.js");
-        await runSetupDecisionsCockpit({ input, output, cwd, runId });
-        return "ui: closed";
-    }
-    await live.runLiveCockpit({ input, output, cwd, runId, binaryVersion });
+    const { runLiveCockpit } = await import("../../tui/cockpit/live.js");
+    const { version } = await import("./version.js");
+    const options = {
+        input, output, cwd, runId: runId ?? "run-no-run", binaryVersion: await version(),
+        observeRun: runId !== null, initialView: runId === null ? "home" : setup ? "run" : view,
+        initialParks: setup,
+    };
+    await runLiveCockpit(options);
     return "ui: closed";
 }

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

@@ -1 +1 @@
-export declare function unlock(_argv: string[], cwd?: string): Promise<string>;
+export declare function unlock(argv: string[], cwd?: string): Promise<string>;

package/dist/cli/commands/unlock.js

@@ -1,11 +1,61 @@
-import { unlockRun } from "../../run/lock.js";
-// LOCK-03: thin formatter over unlockRun. A live-holder refusal propagates as the throw — the
-// dispatcher prints `tickmarkr unlock: …` and exits 1 (src/cli/index.ts).
-export async function unlock(_argv, cwd = process.cwd()) {
-    const r = unlockRun(cwd);
-    if (!r.held)
-        return "no lock held — nothing to remove";
-    if (r.garbage)
+import { createHash } from "node:crypto";
+import { createInterface } from "node:readline/promises";
+import { parseArgs } from "node:util";
+import { commitGarbageUnlock, commitUnlock, previewGarbageUnlock, previewUnlock } from "../../run/lock.js";
+// LOCK-03/R16-17: thin formatter over lock.ts's preview/commit pair. `tickmarkr unlock <run-id>`
+// recovers a valid, provably-dead lock naming exactly that run (R17: a run ID is required — no
+// bare "unlock whatever is there"); `tickmarkr unlock --garbage` recovers an unparseable snapshot
+// identified by bytes/inode instead, never inventing a run ID. Both mutate only after TTY
+// confirmation or --yes, and both re-check fresh at commit time — this command never trusts the
+// preview it showed the operator for the removal itself.
+export async function unlock(argv, cwd = process.cwd()) {
+    const { values, positionals } = parseArgs({
+        args: argv,
+        options: { garbage: { type: "boolean" }, yes: { type: "boolean" } },
+        allowPositionals: true,
+    });
+    const confirm = async (question) => {
+        if (values.yes)
+            return true;
+        if (process.stdin.isTTY !== true || process.stdout.isTTY !== true)
+            return false;
+        const rl = createInterface({ input: process.stdin, output: process.stdout });
+        try {
+            return /^(?:y|yes)$/i.test((await rl.question(`${question} [y/N] `)).trim());
+        }
+        finally {
+            rl.close();
+        }
+    };
+    if (values.garbage) {
+        const preview = previewGarbageUnlock(cwd);
+        if (!preview.held)
+            return "no lock held — nothing to remove";
+        if (!preview.eligible)
+            throw new Error(preview.reason);
+        const bytes = preview.raw.length === 0 ? "empty" : `${preview.raw.length} byte${preview.raw.length === 1 ? "" : "s"}`;
+        const digest = createHash("sha256").update(preview.raw).digest("hex");
+        if (!(await confirm(`Remove garbage lock (${bytes}, inode ${preview.ino}, sha256 ${digest})?`))) {
+            throw new Error("unlock --garbage: not confirmed (pass --yes or confirm at a TTY)");
+        }
+        const commit = commitGarbageUnlock(cwd, { ino: preview.ino, raw: preview.raw });
+        if (!commit.removed)
+            throw new Error(commit.reason);
         return "removed garbage lock (unparseable payload)";
-    return `removed stale lock — holder pid ${r.pid}${r.runId ? ` (run ${r.runId})` : ""} is dead`;
+    }
+    const runId = positionals[0];
+    if (!runId)
+        throw new Error("usage: tickmarkr unlock <run-id> [--yes] | tickmarkr unlock --garbage [--yes]");
+    const preview = previewUnlock(cwd, runId);
+    if (!preview.held)
+        return "no lock held — nothing to remove";
+    if (!preview.eligible)
+        throw new Error(preview.reason);
+    if (!(await confirm(`Remove lock held by dead pid ${preview.pid} (run ${preview.runId})?`))) {
+        throw new Error("unlock: not confirmed (pass --yes or confirm at a TTY)");
+    }
+    const commit = commitUnlock(cwd, preview);
+    if (!commit.removed)
+        throw new Error(commit.reason);
+    return `removed stale lock — holder pid ${commit.pid} (run ${commit.runId}) is dead`;
 }

package/dist/cli/help.d.ts

@@ -0,0 +1,219 @@
+type Help = {
+    usage: string;
+    description: string;
+    options: Record<string, string>;
+    examples: string[];
+};
+export declare const COMMAND_HELP: {
+    init: {
+        usage: string;
+        description: string;
+        options: {
+            "--global-dir <path>": string;
+            "--agent": string;
+            "--force": string;
+            "--docs": string;
+            "--fresh": string;
+            "--yes": string;
+        };
+        examples: string[];
+    };
+    doctor: {
+        usage: string;
+        description: string;
+        options: {
+            "--models": string;
+            "--fix": string;
+            "--fix-only": string;
+            "--cached": string;
+            "--cached-only": string;
+            "--probe-preflight": string;
+            "--preflight": string;
+            "--refresh-catalog": string;
+            "--catalog-only": string;
+        };
+        examples: string[];
+    };
+    fleet: {
+        usage: string;
+        description: string;
+        options: {
+            "--print": string;
+            "--why": string;
+            "--global-dir <path>": string;
+            "--fresh": string;
+        };
+        examples: string[];
+    };
+    compile: {
+        usage: string;
+        description: string;
+        options: {
+            "--type <speckit|prd|gsd|native>": string;
+            "--dry-run": string;
+            "--strict": string;
+        };
+        examples: string[];
+    };
+    scope: {
+        usage: string;
+        description: string;
+        options: {
+            "--preview": string;
+            "--yes": string;
+            "--force": string;
+        };
+        examples: string[];
+    };
+    plan: {
+        usage: string;
+        description: string;
+        options: {
+            "--mode <risk-based|partner-led|staff-led>": string;
+            "--driver <auto|herdr|subprocess|orca>": string;
+        };
+        examples: string[];
+    };
+    run: {
+        usage: string;
+        description: string;
+        options: {
+            "--concurrency <N>": string;
+            "--driver <auto|herdr|subprocess|orca>": string;
+            "--route-strict": string;
+            "--no-explore": string;
+            "--mode <risk-based|partner-led|staff-led>": string;
+            "--quality": string;
+            "--supersedes <run-id>": string;
+        };
+        examples: string[];
+    };
+    status: {
+        usage: string;
+        description: string;
+        options: {
+            "--oneline": string;
+            "--watch": string;
+            "--plain": string;
+            "--events": string;
+            "--jsonl": string;
+            "--decision-events": string;
+            "--webhook <url>": string;
+        };
+        examples: string[];
+    };
+    stats: {
+        usage: string;
+        description: string;
+        options: {};
+        examples: string[];
+    };
+    resume: {
+        usage: string;
+        description: string;
+        options: {
+            "--graph-changed": string;
+            "--retry-failed": string;
+            "--driver <auto|herdr|subprocess|orca>": string;
+        };
+        examples: string[];
+    };
+    report: {
+        usage: string;
+        description: string;
+        options: {
+            "--md": string;
+            "--compare <baseline-run-id>": string;
+            "--bundle <path>": string;
+        };
+        examples: string[];
+    };
+    profile: {
+        usage: string;
+        description: string;
+        options: {
+            "--explain <shape> <adapter:model> [sub|api]": string;
+            "--weight <0|0.5>": string;
+            "--reason <text>": string;
+        };
+        examples: string[];
+    };
+    ui: {
+        usage: string;
+        description: string;
+        options: {
+            "--view <home|run|evidence>": string;
+            "--setup": string;
+        };
+        examples: string[];
+    };
+    unlock: {
+        usage: string;
+        description: string;
+        options: {
+            "--garbage": string;
+            "--yes": string;
+        };
+        examples: string[];
+    };
+    approve: {
+        usage: string;
+        description: string;
+        options: {
+            "--by <name>": string;
+            "--reason <text>": string;
+            "--waive": string;
+            "--uphold": string;
+            "--recheck": string;
+            "--review-rounds <N>": string;
+        };
+        examples: string[];
+    };
+    beat: {
+        usage: string;
+        description: string;
+        options: {
+            "--seat <identity>": string;
+            "--arm-id <identity>": string;
+            "--pct <0..100>": string;
+            "--threshold-pct <0..100>": string;
+            "--stand-down": string;
+        };
+        examples: string[];
+    };
+    version: {
+        usage: string;
+        description: string;
+        options: {
+            "--dist": string;
+        };
+        examples: string[];
+    };
+    verify: {
+        usage: string;
+        description: string;
+        options: {
+            "--base <ref>": string;
+            "--criteria <file>": string;
+            "--task <id>": string;
+            "--files <glob>": string;
+            "--author <adapter:model>": string;
+            "--baseline <path>": string;
+            "--record <run-id>": string;
+            "--json": string;
+            "--no-review": string;
+            "--no-acceptance": string;
+        };
+        examples: string[];
+    };
+    eval: {
+        usage: string;
+        description: string;
+        options: {};
+        examples: string[];
+    };
+};
+export declare const PROFILE_HELP: Record<string, Help>;
+export declare function hasHelpFlag(argv: readonly string[]): boolean;
+export declare function commandHelp(command: string, argv?: readonly string[]): string;
+export {};