tickmarkr 2.4.1 → 2.5.0

package/dist/tui/cockpit/run-view.d.ts

@@ -0,0 +1,100 @@
+import type { ReactElement } from "react";
+import type { ApprovalRunOwner } from "../../cli/commands/approve.js";
+import { type GateName, type RunGraph } from "../../graph/schema.js";
+import type { JournalEvent } from "../../run/journal.js";
+import { type GateOutcome } from "../../run/outcome.js";
+import type { OperatorGateState, OperatorSnapshot, OperatorTask } from "../../run/operator-state.js";
+import { type DecisionCommand, type DecisionPreview, type DecisionSession, type RunDecision } from "./decision-actions.js";
+/** A journal line as C2's store exposes it — physical line, parsed event when readable. */
+export interface RunEvidenceRow {
+    readonly line: number;
+    readonly event?: JournalEvent;
+    readonly error?: string;
+}
+export type EvidencePage = (firstLine: number, count?: number) => readonly RunEvidenceRow[];
+export interface EvidenceLookup {
+    (line: number): RunEvidenceRow | undefined;
+    /** All known later rows, filling the evicted gap through the store's page accessor. */
+    later(line: number): readonly RunEvidenceRow[];
+}
+/** Bounded history first, then the store's page accessor for an evicted line. */
+export declare function evidenceLookup(rows: readonly RunEvidenceRow[], page?: EvidencePage): EvidenceLookup;
+export declare const GATE_CELL_LETTERS: Record<OperatorGateState, string>;
+/** The outcome selector's vocabulary — a classification of the row, never a word search. */
+export declare const OUTCOME_FILTERS: readonly ["all", "infra failure", "work failure", "pass", "unknown"];
+export type OutcomeFilter = (typeof OUTCOME_FILTERS)[number];
+export type OutcomeClass = Exclude<OutcomeFilter, "all"> | "not a verdict";
+export interface RunGateCell {
+    readonly gate: GateName;
+    readonly state: OperatorGateState;
+    readonly letter: string;
+    readonly line?: number;
+    readonly outcome?: GateOutcome;
+    readonly outcomeClass: OutcomeClass;
+    readonly labels: readonly string[];
+    /** The verdict text the evidence row carries, split into lines for paging. */
+    readonly verdict: readonly string[];
+}
+/**
+ * The current attempt's seven cells in declaration order. `rows` supplies the later journal rows
+ * that give a cell its inherited/satisfied label; only rows for this task after the evidence line count.
+ */
+export declare function runGateCells(task: OperatorTask, evidence: EvidenceLookup, rows?: readonly RunEvidenceRow[]): readonly RunGateCell[];
+export declare const VERDICT_WINDOW = 10;
+export interface RunViewSession {
+    readonly selection: number;
+    /** Index into GATE_NAMES of the gate whose verdict is open. */
+    readonly verdictGate: number;
+    readonly verdictOffset: number;
+    readonly outcomeFilter: OutcomeFilter;
+    readonly decisions: DecisionSession;
+}
+export declare const initialRunViewSession: () => RunViewSession;
+export interface RunViewKeyEvent {
+    readonly input: string;
+    readonly key: {
+        readonly upArrow?: boolean;
+        readonly downArrow?: boolean;
+        readonly leftArrow?: boolean;
+        readonly rightArrow?: boolean;
+        readonly return?: boolean;
+        readonly escape?: boolean;
+        readonly pageUp?: boolean;
+        readonly pageDown?: boolean;
+    };
+}
+export interface RunViewKeyResult {
+    readonly session: RunViewSession;
+    readonly open?: DecisionCommand;
+    readonly confirm?: DecisionPreview;
+}
+/**
+ * ↑↓ select a task, ←→ choose the verdict gate, PageUp/PageDown page the verdict, x cycles the
+ * outcome selector, and a/Enter/y/n/Esc are the decision flow's. A digit is never a view switch here.
+ */
+export declare function applyRunViewKey(session: RunViewSession, event: RunViewKeyEvent, ctx: {
+    tasks: readonly OperatorTask[];
+    decisions: readonly RunDecision[];
+    verdictLines: number;
+}): RunViewKeyResult;
+/**
+ * The one-line lifecycle summary drawn above the matrix. Unresolved members come from the tasks'
+ * current recorded states (the run-end buckets are C2's green authority, invalidated by a resume);
+ * a closed run whose record lacks a bucket says so rather than reading absence as empty.
+ */
+export declare function runSummaryLine(s: OperatorSnapshot): string;
+/** One matrix row: id, state, the seven letters in declaration order, the recorded attempt. */
+export declare function runTaskRow(t: OperatorTask, cells: readonly Pick<RunGateCell, "letter">[]): string;
+export interface RunViewProps {
+    readonly snapshot: OperatorSnapshot;
+    /** Journal rows the store retains (C2 `journal.history`); evidence outside them reaches `page`. */
+    readonly rows: readonly RunEvidenceRow[];
+    readonly page?: EvidencePage;
+    readonly graph?: RunGraph;
+    readonly decisions: readonly RunDecision[];
+    readonly session: RunViewSession;
+    readonly columns: number;
+    readonly run: ApprovalRunOwner;
+}
+/** The Run body. Every line is measured through the width module; nothing overflows its column. */
+export declare function RunView({ snapshot, rows, page, graph, decisions, session, columns, run }: RunViewProps): ReactElement;

package/dist/tui/cockpit/run-view.js

@@ -0,0 +1,202 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { Box } from "ink";
+import { GLYPHS } from "../../brand.js";
+import { GATE_NAMES } from "../../graph/schema.js";
+import { normalizeGateOutcome } from "../../run/outcome.js";
+import { BodyText, Panel } from "./components.js";
+import { applyDecisionKey, decisionConfirmLines, decisionKeybar, decisionReceiptLines, initialDecisionSession, } from "./decision-actions.js";
+import { fitCells, wrapCells } from "./width.js";
+/** Bounded history first, then the store's page accessor for an evicted line. */
+export function evidenceLookup(rows, page) {
+    const retained = [...rows].sort((a, b) => a.line - b.line);
+    const recovered = new Map();
+    const safelyPage = (firstLine, count) => {
+        try {
+            return page?.(firstLine, count) ?? [];
+        }
+        catch {
+            return [];
+        }
+    };
+    const lookup = ((line) => retained.find((row) => row.line === line) ?? recovered.get(line) ?? safelyPage(line, 1)[0]);
+    lookup.later = (line) => {
+        const later = retained.filter((row) => row.line > line);
+        const firstRetained = later[0]?.line;
+        // If the evidence itself is retained, every later row is retained too: history is a tail.
+        // Otherwise page only the evicted gap. This recovers durable reuse/approval markers without
+        // retaining the journal or repeatedly scanning the live tail on ordinary renders.
+        if (!page || retained.some((row) => row.line === line))
+            return later;
+        let candidate = line + 1;
+        while (firstRetained === undefined || candidate < firstRetained) {
+            const count = firstRetained === undefined ? 256 : Math.min(256, firstRetained - candidate);
+            const batch = safelyPage(candidate, count);
+            if (batch.length === 0)
+                break;
+            for (const row of batch)
+                recovered.set(row.line, row);
+            const next = batch[batch.length - 1].line + 1;
+            if (next <= candidate)
+                break;
+            candidate = next;
+        }
+        return [...recovered.values(), ...later]
+            .filter((row) => row.line > line)
+            .sort((a, b) => a.line - b.line);
+    };
+    return lookup;
+}
+export const GATE_CELL_LETTERS = {
+    passed: "P", failed: "F", running: "R", "not-run": "-", disabled: "D", unknown: "?",
+};
+/** The outcome selector's vocabulary — a classification of the row, never a word search. */
+export const OUTCOME_FILTERS = ["all", "infra failure", "work failure", "pass", "unknown"];
+const BASELINE_GATES = new Set(["build", "test", "lint"]);
+const str = (v) => (typeof v === "string" && v.trim() !== "" ? v : undefined);
+function outcomeClassOf(outcome, state) {
+    if (!outcome)
+        return state === "passed" || state === "failed" ? "unknown" : "not a verdict";
+    switch (outcome.kind) {
+        case "infra": return "infra failure";
+        case "failed": return "work failure";
+        case "passed": return "pass";
+        case "unavailable": return "unknown";
+        default: return "not a verdict";
+    }
+}
+function outcomeLabel(outcome) {
+    switch (outcome.kind) {
+        case "passed": return "passed";
+        case "failed": return "failed (work)";
+        case "infra": return `infra failure — ${outcome.reason} (${outcome.retryable ? "retryable" : "terminal"})`;
+        case "skipped": return `skipped — ${outcome.reason}`;
+        case "declined": return `declined — ${outcome.reason}`;
+        case "held": return `held — ${outcome.reason}`;
+        case "unavailable": return `unknown — ${outcome.reason}`;
+    }
+}
+/**
+ * The current attempt's seven cells in declaration order. `rows` supplies the later journal rows
+ * that give a cell its inherited/satisfied label; only rows for this task after the evidence line count.
+ */
+export function runGateCells(task, evidence, rows = []) {
+    return GATE_NAMES.map((gate) => {
+        const cell = task.gates[gate] ?? { state: "unknown" };
+        const line = cell.evidence?.line;
+        const row = line === undefined ? undefined : evidence(line);
+        const data = row?.event?.data;
+        const labels = [];
+        let outcome;
+        if (data === undefined) {
+            labels.push(line === undefined ? { "not-run": "not run", disabled: "disabled by policy", running: "running", unknown: "unknown", passed: "passed", failed: "failed" }[cell.state] : `evidence #L${line} unavailable`);
+        }
+        else if (data.disabled === true) {
+            labels.push("disabled by policy");
+        }
+        else if (row?.event?.event === "gate-start") {
+            labels.push("running");
+        }
+        else {
+            outcome = normalizeGateOutcome(data);
+            labels.push(outcomeLabel(outcome));
+            // Baseline forgiveness is recorded only in the battery's own details text (baseline.ts); read it
+            // from that row alone, for the three gates that battery runs, never from any other prose.
+            if (BASELINE_GATES.has(gate) && data.pass === true && /\(forgiven\)/u.test(String(data.details ?? "")))
+                labels.push("baseline-forgiven (pre-existing failures)");
+            if (data.replayMeasurement === true)
+                labels.push("replayed measurement");
+            if (gate === "review") {
+                labels.push(`reviewer ${str(data.reviewer) ?? "unknown"}`, `reviewer tier ${str(data.reviewerTier) ?? "unknown"}`, `author tier ${str(data.authorTier) ?? "unknown"}`, `reviewer floor ${str(data.reviewerFloor) ?? "unknown"}`);
+            }
+        }
+        for (const later of line === undefined ? rows : evidence.later(line)) {
+            if (line === undefined || later.line <= line || later.event?.taskId !== task.id)
+                continue;
+            const e = later.event;
+            if (e.event === "gate-reused" && e.data.gate === gate)
+                labels.push(`inherited from ${str(e.data.commit) ?? "unknown commit"} · #L${later.line}`);
+            if (e.event === "task-approved" && e.data.release === "gate-satisfied" && e.data.gate === gate)
+                labels.push(`satisfied by approval #L${later.line}`);
+        }
+        const verdict = typeof data?.details === "string" ? data.details.split("\n") : [];
+        return { gate, state: cell.state, letter: GATE_CELL_LETTERS[cell.state], ...(line === undefined ? {} : { line }), ...(outcome ? { outcome } : {}), outcomeClass: outcomeClassOf(outcome, cell.state), labels, verdict };
+    });
+}
+export const VERDICT_WINDOW = 10;
+export const initialRunViewSession = () => ({ selection: 0, verdictGate: GATE_NAMES.indexOf("review"), verdictOffset: 0, outcomeFilter: "all", decisions: initialDecisionSession() });
+const clamp = (v, lo, hi) => Math.max(lo, Math.min(hi, v));
+/**
+ * ↑↓ select a task, ←→ choose the verdict gate, PageUp/PageDown page the verdict, x cycles the
+ * outcome selector, and a/Enter/y/n/Esc are the decision flow's. A digit is never a view switch here.
+ */
+export function applyRunViewKey(session, event, ctx) {
+    const task = ctx.tasks[session.selection];
+    const selected = task === undefined ? undefined : ctx.decisions.find((d) => d.taskId === task.id);
+    const decided = applyDecisionKey(session.decisions, event, selected);
+    if (decided.handled)
+        return { session: { ...session, decisions: decided.session }, ...(decided.open ? { open: decided.open } : {}), ...(decided.confirm ? { confirm: decided.confirm } : {}) };
+    if (event.key.upArrow === true || event.key.downArrow === true) {
+        const selection = clamp(session.selection + (event.key.upArrow === true ? -1 : 1), 0, Math.max(0, ctx.tasks.length - 1));
+        return { session: { ...session, selection, verdictOffset: 0 } };
+    }
+    if (event.key.leftArrow === true || event.key.rightArrow === true) {
+        return { session: { ...session, verdictGate: clamp(session.verdictGate + (event.key.leftArrow === true ? -1 : 1), 0, GATE_NAMES.length - 1), verdictOffset: 0 } };
+    }
+    if (event.key.pageUp === true || event.key.pageDown === true) {
+        const last = Math.max(0, ctx.verdictLines - VERDICT_WINDOW);
+        return { session: { ...session, verdictOffset: clamp(session.verdictOffset + (event.key.pageUp === true ? -VERDICT_WINDOW : VERDICT_WINDOW), 0, last) } };
+    }
+    if (event.input === "x") {
+        return { session: { ...session, outcomeFilter: OUTCOME_FILTERS[(OUTCOME_FILTERS.indexOf(session.outcomeFilter) + 1) % OUTCOME_FILTERS.length] } };
+    }
+    return { session };
+}
+const UNRESOLVED = ["failed", "human", "blocked", "pending"];
+/**
+ * The one-line lifecycle summary drawn above the matrix. Unresolved members come from the tasks'
+ * current recorded states (the run-end buckets are C2's green authority, invalidated by a resume);
+ * a closed run whose record lacks a bucket says so rather than reading absence as empty.
+ */
+export function runSummaryLine(s) {
+    const members = UNRESOLVED.map((k) => { const ids = s.tasks.filter((t) => t.state === k).map((t) => t.id); return ids.length === 0 ? "" : `${k} ${ids.join(",")}`; }).filter(Boolean);
+    const unknownBuckets = s.latestRunEnd === undefined ? [] : UNRESOLVED.filter((k) => s.buckets[k] === undefined);
+    return [
+        `${s.merged}/${s.planned ?? "?"} merged`,
+        ...members,
+        ...(unknownBuckets.length === 0 ? [] : [`run-end bucket ${unknownBuckets.join("/")} unknown`]),
+        `current-cycle tip ${s.currentTip.toUpperCase()}`,
+        s.label, s.comparison, `snapshot #${s.sequence}`,
+    ].join(" | ");
+}
+const attemptLabel = (t) => (t.attempt !== undefined ? `attempt ${t.attempt}` : t.dispatches === 0 ? "never dispatched" : "attempt unknown");
+const parkOf = (t) => (t.state === "human" ? `human · ${t.parkKind ?? "unknown kind"}` : t.state);
+/** One matrix row: id, state, the seven letters in declaration order, the recorded attempt. */
+export function runTaskRow(t, cells) {
+    return `${t.id.padEnd(4)} ${parkOf(t).padEnd(20)} ${cells.map((c) => c.letter).join("  ")}  ${attemptLabel(t)}`;
+}
+const MATRIX_HEADER = `${"Task".padEnd(4)} ${"state".padEnd(20)} ${GATE_NAMES.map((g) => g.slice(0, 2)).join(" ")}  latest attempt`;
+const MATRIX_LEGEND = "P pass · F fail · R running · - not run · D disabled · ? unknown | declaration order, not a timeline · acceptance/review concurrent, optional";
+/** The Run body. Every line is measured through the width module; nothing overflows its column. */
+export function RunView({ snapshot, rows, page, graph, decisions, session, columns, run }) {
+    const inner = Math.max(1, Math.floor(columns) - 4);
+    const fit = (text) => fitCells(text, inner);
+    const decisionLines = (lines) => lines.flatMap((line) => wrapCells(line, inner));
+    const lookup = evidenceLookup(rows, page);
+    const tasks = snapshot.tasks;
+    const selection = Math.min(session.selection, Math.max(0, tasks.length - 1));
+    const task = tasks[selection];
+    const cells = task === undefined ? [] : runGateCells(task, lookup, rows);
+    const shown = cells.filter((c) => session.outcomeFilter === "all" || c.outcomeClass === session.outcomeFilter);
+    const verdictCell = cells[session.verdictGate];
+    const verdict = verdictCell?.verdict ?? [];
+    const from = Math.min(session.verdictOffset, Math.max(0, verdict.length - 1));
+    const window = verdict.slice(from, from + VERDICT_WINDOW);
+    const decision = task === undefined ? undefined : decisions.find((d) => d.taskId === task.id);
+    const { menu, confirming, receipt, notice } = session.decisions;
+    const blocked = task === undefined ? [] : graph?.tasks.filter((g) => g.deps.includes(task.id)).map((g) => g.id) ?? decision?.blocks ?? [];
+    return (_jsxs(Box, { flexDirection: "column", width: columns, children: [_jsxs(Panel, { title: `RUN / ${snapshot.lifecycle}`, focused: true, children: [_jsx(BodyText, { emphasis: "dim", children: fit(runSummaryLine(snapshot)) }), _jsx(BodyText, { emphasis: "dim", children: fit(`  ${MATRIX_HEADER}`) }), tasks.map((t, i) => (_jsx(BodyText, { emphasis: i === selection ? "strong" : "normal", children: fit(`${i === selection ? `${GLYPHS.pointer} ` : "  "}${runTaskRow(t, GATE_NAMES.map((gate) => ({ letter: GATE_CELL_LETTERS[t.gates[gate].state] })))}`) }, t.id))), tasks.length === 0 && _jsx(BodyText, { children: fit("no tasks recorded — no plan") }), _jsx(BodyText, { emphasis: "dim", children: fit(MATRIX_LEGEND) })] }), task !== undefined && (_jsxs(Panel, { title: `SELECTED / ${task.id}${task.title ? ` · ${task.title}` : ""}`, children: [_jsx(BodyText, { children: fit(`state ${parkOf(task)} · ${attemptLabel(task)} · dispatches ${task.dispatches} · path ${task.path ?? "unknown"} · pane ${task.pane ?? "unknown"} · alarm ${task.alarmMs === undefined ? "unknown" : `${task.alarmMs}ms`}${task.mergeEvidence ? ` · merged #L${task.mergeEvidence.line}` : ""}`) }), _jsx(BodyText, { emphasis: "dim", children: fit(`outcome filter ${session.outcomeFilter} (x cycles) · ${shown.length} of ${cells.length} gates shown`) }), shown.map((c) => (_jsx(BodyText, { children: fit(`${c.letter} ${c.gate.padEnd(10)} ${c.labels.join(" · ")}${c.line === undefined ? "" : ` · #L${c.line}`}`) }, c.gate)))] })), verdictCell !== undefined && (_jsxs(Panel, { title: `VERDICT / ${verdictCell.gate}${verdictCell.line === undefined ? "" : ` #L${verdictCell.line}`} · ${verdict.length === 0 ? "no verdict text" : `lines ${from + 1}–${from + window.length} of ${verdict.length}`}`, children: [window.map((line, i) => _jsx(BodyText, { children: fit(`${String(from + i + 1).padStart(4)} ${line}`) }, `${from + i}:${line}`)), _jsx(BodyText, { emphasis: "dim", children: fit("←→ gate · PageUp/PageDown page") })] })), task?.state === "human" && (_jsx(Panel, { title: `PARK / ${task.id}`, children: decision === undefined
+                    ? _jsx(BodyText, { children: fit("park evidence unavailable — refresh before deciding") })
+                    : (_jsxs(_Fragment, { children: [_jsx(BodyText, { children: fit(`#L${decision.park.line} ${decision.park.kind ?? "unknown kind"}${decision.park.failedGate ? ` · failed gate ${decision.park.failedGate}` : ""} · ${decision.park.reason ?? "no reason recorded"}`) }), _jsx(BodyText, { children: fit(`blocks ${blocked.length === 0 ? "nothing" : blocked.join(", ")} · attempts ${decision.attempts}`) }), _jsx(BodyText, { children: fit(decision.verbs.length === 0 ? `diagnostic: ${decision.diagnostic ?? "no verb"}` : `decisions: ${decision.verbs.join(" · ")} (a Actions)`) }), _jsx(BodyText, { emphasis: "dim", children: fit(run.live ? "matching live daemon enacts a release at its next task boundary" : run.blockingRunId ? `other live run ${run.blockingRunId} holds the lock; resume after it ends` : "no live owner: a release records permission; resume dispatches") })] })) })), menu !== null && (_jsx(Panel, { title: `ACTIONS / ${menu.taskId}`, focused: true, children: menu.verbs.length === 0
+                    ? _jsx(BodyText, { children: fit(`no decision — ${decision?.diagnostic ?? "no verb for this park"}`) })
+                    : menu.verbs.map((verb, i) => _jsx(BodyText, { emphasis: i === menu.selection ? "strong" : "normal", children: fit(`${i === menu.selection ? `${GLYPHS.pointer} ` : "  "}${verb}`) }, verb)) })), confirming !== null && (_jsx(Panel, { title: `CONFIRM ${confirming.command.verb.toUpperCase()}`, focused: true, children: decisionLines(decisionConfirmLines(confirming)).map((line, i) => _jsx(BodyText, { children: line }, `${i}:${line}`)) })), receipt !== null && (_jsx(Panel, { title: receipt.ok ? "RECEIPT · appended" : "RECEIPT · refused", children: decisionLines(decisionReceiptLines(receipt)).map((line, i) => _jsx(BodyText, { children: line }, `${i}:${line}`)) })), notice !== null && _jsx(BodyText, { children: notice }), _jsx(BodyText, { emphasis: "dim", children: fitCells(["↑↓ Task", "←→ Verdict gate", "PgUp/PgDn Page", "x Outcome", decisionKeybar(session.decisions, decision)].filter(Boolean).join(" · "), Math.max(1, Math.floor(columns))) })] }));
+}

package/dist/tui/cockpit/shell.d.ts

@@ -0,0 +1,50 @@
+import { type ReactNode } from "react";
+import { type ShellPlan } from "./layout.js";
+import { SHELL_BINDINGS } from "./keys.js";
+import type { LiveStoreSnapshot } from "./live-store.js";
+export type ShellView = "home" | "run" | "evidence";
+export type ShellFocus = ShellPlan["focus"][number];
+export interface ShellState {
+    view: ShellView;
+    focus: ShellFocus;
+    scroll: number;
+    help: boolean;
+    evidenceSection?: number;
+    canOpen?: boolean;
+    shortcutColumns?: number;
+    canResize?: boolean;
+    editorKind?: "filter" | "export";
+    editor?: string;
+    query: string;
+    overlay?: readonly string[];
+    overlayOffset: number;
+    quit: boolean;
+    staged: readonly string[];
+    reviewing: boolean;
+}
+export declare const initialShellState: () => ShellState;
+export declare const shellHelp: (bindings?: readonly (typeof SHELL_BINDINGS)[number][]) => string[];
+export interface ShellPaintRow {
+    evidenceId?: string;
+    text: string;
+    column: number;
+    row: number;
+    columns: number;
+    rows: number;
+}
+export type ShellCommit = ShellPlan & {
+    paintedRows: readonly ShellPaintRow[];
+    contentRows: number;
+    scroll: number;
+};
+/** Chrome remains outside the clipped, paged leaf at every measured size. */
+export declare function CockpitShell({ snapshot, state, columns, rows, version, children, onCommit, colour }: {
+    snapshot: LiveStoreSnapshot;
+    state: ShellState;
+    columns: number;
+    rows: number;
+    version: string;
+    children: ReactNode;
+    onCommit?: (plan: ShellCommit) => void;
+    colour?: "truecolor" | "reduced" | "none";
+}): import("react").JSX.Element;

package/dist/tui/cockpit/shell.js

@@ -0,0 +1,74 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { Box, Text } from "ink";
+import { useLayoutEffect, useRef, useState } from "react";
+import { ShellPresentation, ShellTheme } from "./components.js";
+import { planShell } from "./layout.js";
+import { SHELL_BINDINGS, shellBindings } from "./keys.js";
+import { SHELL_PALETTE, SHELL_REDUCED_PALETTE } from "./theme.js";
+import { fitCells } from "./width.js";
+export const initialShellState = () => ({ view: "home", focus: "content", scroll: 0, help: false, query: "", overlayOffset: 0, quit: false, staged: [], reviewing: false });
+export const shellHelp = (bindings = SHELL_BINDINGS) => [
+    ...bindings.map(b => `${b.key} ${b.label}`),
+    "Shift-Tab reverses focus; folded regions are skipped.",
+    "Esc closes deepest overlay; it never quits.",
+    "Text: q1? is literal; Enter applies; Esc cancels.",
+    "Confirm: y alone confirms; n/Esc cancels.",
+    "Tab now moves focus; view numbers are 1/4/5.",
+    "Fleet: tickmarkr fleet", "Plan: tickmarkr plan", "Health: tickmarkr doctor",
+];
+/** Read the Yoga geometry that actually painted, including clipped/scrolled leaves.
+ * Targets are resolved from these rows, never from guessed header offsets. */
+function paintedRows(root) {
+    const result = [];
+    const textOf = (node) => node.nodeName === "#text"
+        ? node.nodeValue : node.childNodes.map(textOf).join("");
+    const visit = (node, x, y, inheritedEvidence) => {
+        if (node.style.display === "none")
+            return;
+        const evidenceId = typeof node.attributes.shellEvidence === "string" ? node.attributes.shellEvidence : inheritedEvidence;
+        const column = x + (node.yogaNode?.getComputedLeft() ?? 0);
+        const row = y + (node.yogaNode?.getComputedTop() ?? 0);
+        if (node.nodeName === "ink-text")
+            result.push({ evidenceId, text: textOf(node), column, row,
+                columns: node.yogaNode?.getComputedWidth() ?? 0, rows: node.yogaNode?.getComputedHeight() ?? 0 });
+        else
+            for (const child of node.childNodes)
+                if (child.nodeName !== "#text")
+                    visit(child, column, row, evidenceId);
+    };
+    visit(root, 0, 0);
+    return result;
+}
+/** Chrome remains outside the clipped, paged leaf at every measured size. */
+export function CockpitShell({ snapshot, state, columns, rows, version, children, onCommit, colour = "truecolor" }) {
+    const plan = planShell(columns, rows, state.shortcutColumns);
+    const root = useRef(null);
+    const leaf = useRef(null);
+    const [contentRows, setContentRows] = useState(0);
+    const scroll = Math.min(state.scroll, Math.max(0, contentRows - plan.bodyRows));
+    useLayoutEffect(() => {
+        const measured = Math.ceil(leaf.current?.yogaNode?.getComputedHeight() ?? 0);
+        if (!state.overlay && !state.help && state.editor === undefined)
+            setContentRows(measured);
+        if (plan.refused)
+            onCommit?.({ ...plan, paintedRows: [], contentRows: 0, scroll: 0 });
+        else if (root.current)
+            onCommit?.({ ...plan, paintedRows: paintedRows(root.current), contentRows: overlay?.length ?? measured, scroll: displayOffset });
+    });
+    const palette = colour === "reduced" ? SHELL_REDUCED_PALETTE : SHELL_PALETTE;
+    const ink = (color) => colour === "none" ? undefined : color;
+    const line = (text, width = columns, color = palette.text) => _jsx(Text, { color: ink(color), wrap: "truncate-end", children: fitCells(text.replace(/[\x00-\x1f\x7f]/g, " "), width) });
+    if (plan.refused)
+        return _jsxs(Box, { flexDirection: "column", width: columns, backgroundColor: ink(palette.surface), children: [line("Need at least 40x14; resize or q Quit"), line("q Quit | Ctrl-C Quit")] });
+    const op = snapshot.operator;
+    const bindings = shellBindings(state);
+    const overlay = state.editor !== undefined ? [`${state.editorKind === "export" ? "Export destination" : "Filter"}: ${state.editor}`, "Enter Apply | Esc Cancel"] : state.overlay ?? (state.help ? shellHelp(bindings) : undefined);
+    const totalRows = overlay?.length ?? contentRows;
+    const displayOffset = overlay ? Math.min(state.overlayOffset, Math.max(0, totalRows - plan.bodyRows)) : scroll;
+    const position = `${totalRows ? displayOffset + 1 : 0}–${Math.min(totalRows, displayOffset + plan.bodyRows)}/${totalRows} | ${Math.max(0, totalRows - plan.bodyRows)} hidden`;
+    const keybar = bindings.filter(b => ["focus", "open", "actions", "help", "quit"].includes(b.action) && (columns >= 60 || b.action !== "focus")).map(b => `${b.key} ${columns < 60 && b.action === "actions" ? "Act" : b.label}`).join(" | ");
+    const status = columns < 60 ? `${op.label} | tip ${op.currentTip.toUpperCase()}` : `${op.label} | MERGED ${op.merged}/${op.planned ?? "?"} | CURRENT TIP ${op.currentTip.toUpperCase()} | ${snapshot.freshness}`;
+    return _jsx(ShellPresentation.Provider, { value: true, children: _jsx(ShellTheme.Provider, { value: { mode: colour, palette }, children: _jsxs(Box, { ref: root, flexDirection: "column", width: columns, height: rows, flexShrink: 0, backgroundColor: ink(palette.surface), children: [line(`tickmarkr ${version} | ${state.view.toUpperCase()} | ${snapshot.journal.source.split("/").at(-2) ?? "run identity unknown"}`), line(columns < 60
+                        ? `1H 4R 5E | ${position}`
+                        : `1 Home  4 Run  5 Evidence | ${state.focus} | ${position}`), line("─".repeat(columns), columns, palette.chrome), _jsxs(Box, { height: plan.bodyRows, flexShrink: 0, flexDirection: "row", overflow: "hidden", children: [_jsx(Box, { width: 1, flexDirection: "column", children: Array.from({ length: plan.bodyRows }, (_, i) => _jsx(Text, { color: ink(palette.chrome), children: "\u2502" }, i)) }), plan.rail > 0 && _jsxs(_Fragment, { children: [_jsx(Box, { width: plan.rail, flexDirection: "column", children: ["1 Home", "4 Run", "5 Evidence", "", "CLI:", "fleet", "plan", "doctor"].map((t, i) => _jsx(Text, { color: ink(palette.chrome), children: fitCells(t, plan.rail) }, i)) }), _jsx(Box, { width: 1, flexDirection: "column", children: Array.from({ length: plan.bodyRows }, (_, i) => _jsx(Text, { color: ink(palette.chrome), children: "\u2502" }, i)) })] }), _jsxs(Box, { width: plan.bodyColumns, height: plan.bodyRows, flexDirection: "column", overflow: "hidden", flexShrink: 0, children: [overlay?.slice(displayOffset, displayOffset + plan.bodyRows).map((t, i) => _jsx(Text, { wrap: "truncate-end", color: ink(palette.text), children: fitCells(t, plan.bodyColumns) }, i)), _jsx(Box, { ref: leaf, display: overlay ? "none" : "flex", flexDirection: "column", flexShrink: 0, marginTop: -scroll, children: children })] }), plan.shortcuts > 0 && _jsxs(_Fragment, { children: [_jsx(Box, { width: 1, flexDirection: "column", children: Array.from({ length: plan.bodyRows }, (_, i) => _jsx(Text, { color: ink(palette.chrome), children: "\u2502" }, i)) }), _jsx(Box, { width: plan.shortcuts, flexDirection: "column", children: bindings.map(b => _jsx(Text, { color: ink(palette.chrome), wrap: "truncate-end", children: fitCells(`${b.key} ${b.label}`, plan.shortcuts) }, b.key)) })] }), _jsx(Box, { width: 1, flexDirection: "column", children: Array.from({ length: plan.bodyRows }, (_, i) => _jsx(Text, { color: ink(palette.chrome), children: "\u2502" }, i)) })] }), line("─".repeat(columns), columns, palette.chrome), line(status), line(keybar), line("─".repeat(columns), columns, palette.chrome)] }) }) });
+}

package/dist/tui/cockpit/theme.d.ts

@@ -165,3 +165,30 @@ export type PaletteGuardVerdict = {
  * are intentionally ignored: only parsed colour values can earn a verdict.
  */
 export declare function guardDataRamp(candidate: readonly ColourValue[], surface?: HexColour): PaletteGuardVerdict;
+/** FINAL live palette. Printed TOKENS and historical evidence remain independent. */
+export declare const SHELL_PALETTE: {
+    readonly surface: "#1a1a19";
+    readonly text: "#E6FDFF";
+    readonly chrome: "#D9D7DD";
+    readonly passed: "#90C4A4";
+    readonly running: "#5A76AE";
+    readonly human: "#ffaf00";
+    readonly failure: "#B07BAC";
+    readonly unknown: "#D9D7DD";
+    readonly disabled: "#D9D7DD";
+};
+export declare const SHELL_REDUCED_PALETTE: {
+    readonly surface: "black";
+    readonly text: "whiteBright";
+    readonly chrome: "white";
+    readonly passed: "green";
+    readonly running: "blue";
+    readonly human: "yellow";
+    readonly failure: "magenta";
+    readonly unknown: "white";
+    readonly disabled: "white";
+};
+export type ShellColourMode = "truecolor" | "reduced" | "none";
+export type ShellPalette = typeof SHELL_PALETTE | typeof SHELL_REDUCED_PALETTE;
+/** Resolve the real terminal environment once, at mount time. */
+export declare function resolveShellColourMode(environment?: NodeJS.ProcessEnv): ShellColourMode;

package/dist/tui/cockpit/theme.js

@@ -174,3 +174,24 @@ export function guardDataRamp(candidate, surface = COCKPIT_SURFACE) {
         issues,
     };
 }
+/** FINAL live palette. Printed TOKENS and historical evidence remain independent. */
+export const SHELL_PALETTE = {
+    surface: "#1a1a19", text: "#E6FDFF", chrome: "#D9D7DD",
+    passed: "#90C4A4", running: "#5A76AE", human: "#ffaf00",
+    failure: "#B07BAC", unknown: "#D9D7DD", disabled: "#D9D7DD",
+};
+export const SHELL_REDUCED_PALETTE = {
+    surface: "black", text: "whiteBright", chrome: "white",
+    passed: "green", running: "blue", human: "yellow",
+    failure: "magenta", unknown: "white", disabled: "white",
+};
+/** Resolve the real terminal environment once, at mount time. */
+export function resolveShellColourMode(environment = process.env) {
+    if (Object.hasOwn(environment, "NO_COLOR"))
+        return "none";
+    const colourTerm = environment.COLORTERM?.toLowerCase() ?? "";
+    const term = environment.TERM?.toLowerCase() ?? "";
+    return /^(truecolor|24bit)$/u.test(colourTerm) || /(truecolor|24bit|direct)/u.test(term)
+        ? "truecolor"
+        : "reduced";
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tickmarkr",
-  "version": "2.4.1",
+  "version": "2.5.0",
   "description": "Spec in, verified work out.",
   "type": "module",
   "license": "MIT",

package/skills/tickmarkr-auto/SKILL.md

@@ -8,6 +8,15 @@ argument-hint: "[spec-or-directory ...]"
 
 Use this to execute a requested sequence of repository specs. It is SDD-agnostic: each target can be any file or directory accepted by `tickmarkr compile`.
 
+Use the canonical loop skill's [cockpit, parked decisions and printed twins](../tickmarkr-loop/SKILL.md#cockpit-parked-decisions-and-printed-twins)
+for each target: delivered views are **1 Home, 4 Run, 5 Evidence**; Fleet/Bootstrap and
+Plan/Health remain follow-ons with CLI entries. The recorded 1/3 merged, human T2, blocked
+T3 case stays PARTIAL despite tip pass. Review the Run confirmation, read back the appended
+`task-approved` receipt, and explicitly `tickmarkr resume <runId>` when no live owner exists;
+approval records permission and never dispatches work itself. Non-TTY readers keep `status`,
+`report` and default-watch line output, with `--watch --plain` as the TTY fallback.
+Keep `name: tickmarkr-auto` and the installed links to canonical `skills/` intact.
+
 ## Two-tier by default — role check before the loop
 
 When working in a multi-agent terminal environment, decide your role before starting:
@@ -85,5 +94,5 @@ After sending, **confirm delivery** by reading the target pane and verifying the
 3. **Plan** — run `tickmarkr plan`. Review routes, capability-floor warnings, and human gates before execution.
 4. **Run** — run `tickmarkr run`. Watch the run journal for its terminal events rather than polling agents, using the shipped watcher — `.claude/skills/tickmarkr-overseer/scripts/watch-journal.sh <state-dir>/runs 20 28800` — which takes a line baseline at arm time, then wakes ONCE on `run-end`, `task-human`, `task-failed` or `consult-verdict` and grades the run-end summary against every green clause for you. Re-arm after every wake. ⛔ Never `tail -F | grep -m1` (run-end is the journal's last line, so tail never notices the broken pipe and the watcher hangs forever) and never a pane-level done wait (it fires on every agent turn end, not mission end). ⚠ A bare whole-file `grep -q '"event":"run-end"'` is the trap the watcher exists to avoid: on a resume it matches the PREVIOUS run's run-end and returns instantly, so a re-armed watcher reads as coverage that does not exist. Resolve blocked interactions in the relevant agent session.
 5. **Verify and consolidate** — continue only after a green run. A run is green when the run-end event exists in the journal, the tip verify is not "failed", and the summary's `failed`, `human`, `blocked` and `pending` buckets are all empty — a run with a parked task is partial, not green. Tickmarkr consolidates accepted work on `tickmarkr/<runId>` and never signs off to the main branch. A human controls any later release merge.
-6. **Record** — write `tickmarkr report <runId> --md` beside the source spec and commit the execution record when the repository tracks those records.
+6. **Record** — `tickmarkr report <runId> --md` prints Markdown to stdout; redirect explicitly beside the spec (for example `tickmarkr report <runId> --md > feature.record.md`) and commit the execution record when the repository tracks those records.
 7. **Continue** — move to the next requested target. If a target fails or is parked, stop with the journal evidence rather than silently skipping it.

package/skills/tickmarkr-loop/SKILL.md

@@ -90,4 +90,75 @@ When spawning consultants (agents gathering synthesis input for decisions like S
 3. **Plan** — run `tickmarkr plan`. Review the routing table, capability-floor warnings, and every human gate, including work that each gate blocks.
 4. **Run** — run `tickmarkr run`. Watch the run journal for its terminal events rather than polling agents, using the shipped watcher — `.claude/skills/tickmarkr-overseer/scripts/watch-journal.sh <state-dir>/runs 20 28800` — which takes a line baseline at arm time, then wakes ONCE on `run-end`, `task-human`, `task-failed` or `consult-verdict` and grades the run-end summary against every green clause for you. Re-arm after every wake. ⛔ Never `tail -F | grep -m1` (run-end is the journal's last line, so tail never notices the broken pipe and the watcher hangs forever) and never a pane-level done wait (it fires on every agent turn end, not mission end). ⚠ A bare whole-file `grep -q '"event":"run-end"'` is the trap the watcher exists to avoid: on a resume it matches the PREVIOUS run's run-end and returns instantly, so a re-armed watcher reads as coverage that does not exist. Resolve blocked interactions in the agent session; do not turn them into proxy questions.
 5. **Verify and consolidate** — accept only a green run. A run is green when the run-end event exists in the journal, the tip verify is not "failed", and the summary's `failed`, `human`, `blocked` and `pending` buckets are all empty — a run with a parked task is partial, not green. Tickmarkr consolidates accepted task work on `tickmarkr/<runId>`; it never signs off to the main branch. A human may later merge that integration branch through the repository's normal release process.
-6. **Record** — write `tickmarkr report <runId> --md` beside the source spec and commit the execution record when the repository tracks those records. Then [stand down](#stand-down-mission-end-and-retirement).
+6. **Record** — `tickmarkr report <runId> --md` prints Markdown to stdout. Redirect it explicitly beside the source spec (for example `tickmarkr report <runId> --md > feature.record.md`) and commit the execution record when the repository tracks those records. Then [stand down](#stand-down-mission-end-and-retirement).
+
+## Cockpit, parked decisions and printed twins
+
+The shipped cockpit is **1 Home, 4 Run, 5 Evidence**: `tickmarkr ui [runId]` defaults to
+Home on the latest journal, or empty Home with no run. `tickmarkr ui <runId> --view run`
+and `--view evidence` select delivered views; `tickmarkr ui --setup <runId>` opens Run
+Parks for that run. Fleet/Bootstrap and Plan/Health are follow-ons; keys 2/3/6 are not
+installed. Continue using `fleet`, `init`, `plan` and `doctor` as CLI workflows.
+
+Walk the recorded partial-human-park case before declaring green: **1/3 merged**, human
+T2, blocked T3, tip passed is **PARTIAL**. T2 is a `humanGate: true` park before dispatch.
+In Run select T2, press `a` Actions, choose Approve with Enter, then read the confirmation's
+run/task, original park `#L`, actor/reason, exact argv, consequence and enactor. Only `y`
+confirms; `n`/Esc cancel; Enter never confirms. Read the receipt's appended `task-approved`
+line and actor/reason back from the journal. Approval records permission, never dispatch,
+a passed gate or task completion. With no live owner it says **approved; resume required**:
+exit the observer and run `tickmarkr resume <runId>` explicitly. A matching live daemon
+enacts at its next task boundary; if a different live run owns the repository lock, wait
+for that run to end before resuming this one.
+
+For a non-TTY decision, the same command is
+`tickmarkr approve <runId> T2 --by operator --reason 'ready to proceed'`; check its receipt
+and explicitly resume. Preserve resume refusals and repair the named source/config issue
+(including deny/prefer conflicts); never edit the compiled graph to force a result. Resume
+makes CURRENT TIP PENDING; historical GATES RAN does not prove completion. The completed
+case has 3/3 recorded merges, a latest run-end, a nonfailed known tip result and empty
+`failed`, `human`, `blocked`, `pending` buckets. A mismatched graph is “not comparable.”
+
+Run offers only validated park verbs: human/attempt-cap/other non-gate parks allow approve;
+infra allows approve or `--recheck`; review gate-fail allows `--waive`, `--uphold` or
+`--recheck`; other gate-fail allows waive/recheck. Waive satisfies only the identified
+failed gate, uphold funds a fixed attempt carrying review findings, and recheck reruns the
+declared battery without satisfying a gate. Attempt-cap approval resets the budget while
+retaining routing exclusions. Tombstones and failures without identified gate evidence
+are diagnostic-only. Decisions cannot be undone; stale or duplicate decisions refuse.
+
+Use `tickmarkr status <runId>` and `tickmarkr status <runId> --oneline` for preserved
+snapshots. `tickmarkr status <runId> --watch` opens Run on a TTY and uses line output on
+non-TTY; `--watch --plain` keeps the line/ANSI fallback even on a TTY. `--watch --events`
+replays and follows projected decision JSON documents on stdout; `--jsonl` and
+`--decision-events` are aliases. Keep stderr keepalives separate, never `2>&1`; raw
+`journal.jsonl` remains distinct. Webhooks require explicit opt-in. `report` retains text,
+learning preview and comparison warnings; `report --md` stays stdout, `--compare
+<baseline-runId>` compares records, `--bundle <path>` writes a proof bundle, and `stats`
+reports all runs without a run ID. Keep `fleet --print` and `fleet --why` separate.
+Absent usage/cost evidence remains “not measurable.”
+
+Manual UI keeps a receipt at run-end and observes a later resume of that same run. The
+daemon-owned board by default gracefully stops its own watch presence before closing its owned pane;
+unconfirmed cleanup is reported; `visibility.keepPanes: forever` preserves panes. It preserves Herdr grouping, short titles and placement
+beside the caller without taking focus. `q`, Ctrl-C and SIGTERM restore raw/pointer/title/
+alternate-screen state and release only this observer's presence. `?` opens shortcuts,
+Tab/Shift-Tab traverse visible focus, and Esc closes the deepest overlay. Text input keeps
+`q1?` literal. Evidence retains original `#L` pointers and full verdict paging with stable
+selection while Follow is off; Run's `o` focuses only a verified owned pane, otherwise
+showing its evidence diagnostic. Missing historical reviewer-floor metadata stays unknown.
+
+For inert guidance use `tickmarkr ui --help`, `tickmarkr eval --help`,
+`tickmarkr unlock --help` and `tickmarkr profile reset --help`. Before `--`, help returns
+without UI/probes/writes; after `--`, arguments are literal data. Displayed examples do
+not execute. Recovery uses `unlock <runId>` for a matching dead lock or `unlock --garbage`
+for malformed bytes, with confirmation (`--yes` for non-TTY) and identity recheck; live,
+inaccessible or changed holders refuse. `doctor --cached`, `--probe-preflight`,
+`--fix-only` and `--refresh-catalog` distinguish cached reads, budget disclosure, local
+repair and catalog refresh; default doctor and `--fix` still probe. `scope <intent-file>
+--preview` performs no probes, model calls or writes; authoring requires confirmation or
+`--yes`. These actions remain CLI entries until their follow-on views ship.
+
+Keep this skill's canonical identity `tickmarkr-loop`; sibling skills link to this
+walkthrough. In this repository `skills/` is canonical and installed `.claude/skills/`
+files resolve to it; change the canonical source, never create a second help skill.

package/skills/tickmarkr-overseer/SKILL.md

@@ -12,6 +12,18 @@ to the user with evidence.
 The mission is the skill argument. If empty, ask the user what to run end-to-end before doing anything else.
 Requires `HERDR_ENV=1`; if unset, say so and stop.
 
+Use the canonical loop skill's [cockpit, parked decisions and printed twins](../tickmarkr-loop/SKILL.md#cockpit-parked-decisions-and-printed-twins)
+when reading or relaying operator evidence. Delivered views are **1 Home, 4 Run, 5 Evidence**;
+Fleet/Bootstrap and Plan/Health remain follow-ons with existing CLI entries. A recorded
+1/3 merged, human T2, blocked T3 run is PARTIAL despite tip pass. The orchestrator owns
+the Run confirmation and read-back of the appended `task-approved` receipt after a ruling;
+permission is not dispatch, and a closed run needs explicit `tickmarkr resume <runId>`.
+Manual UI retains the receipt; the daemon-owned board gracefully stands down only its own
+presence before closing its owned pane. Non-TTY supervision keeps `status`, `report` and
+default-watch line output (`--watch --plain` is also available on a TTY). Keep the canonical
+`tickmarkr-overseer` identity and installed links to `skills/`; the linked walkthrough is
+the shared guidance source, not a new help skill.
+
 **THE ENGINE IS THE DEFAULT EXECUTOR.** A mission that names a milestone, a phase, or a spec runs the
 loop: `tickmarkr compile` → `plan` → `run` → `report`, and the JOURNAL is the record. `compile` ingests
 GSD phase plans (`src/compile/gsd.ts`), so *"this repo uses GSD"* is not a reason to bypass it. The