tickmarkr 1.80.0 → 1.81.0

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

@@ -2,7 +2,7 @@ type StudioIO = {
     input: NodeJS.ReadStream;
     output: NodeJS.WriteStream;
 };
-export declare function ui(argv: string[], io?: Partial<StudioIO>): Promise<string | {
+export declare function ui(argv: string[], io?: Partial<StudioIO>, cwd?: string): Promise<string | {
     out: string;
     code: number;
 }>;

package/dist/cli/commands/ui.js

@@ -1,5 +1,5 @@
-const NON_TTY_MSG = "tickmarkr ui: studio requires a TTY — use `tickmarkr fleet --print` or `tickmarkr status --watch` for line-mode output";
-export async function ui(argv, io = {}) {
+const NON_TTY_MSG = "tickmarkr ui: the cockpit requires a TTY — use `tickmarkr fleet --print` or `tickmarkr status --watch` for line-mode output";
+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) {
@@ -15,7 +15,38 @@ export async function ui(argv, io = {}) {
         });
         return "ui: closed";
     }
-    const { runStudioInk } = await import("../../tui/ink/studio-app.js");
-    await runStudioInk({ input, output });
+    const unknownFlag = argv.find((arg) => arg.startsWith("-"));
+    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;
+    try {
+        runId = live.selectEngagementRunId(cwd, explicit);
+    }
+    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,
+        };
+    }
+    // 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,
+        };
+    }
+    await live.runLiveCockpit({ input, output, cwd, runId, binaryVersion });
     return "ui: closed";
 }

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

@@ -19,50 +19,11 @@ export type KeybarItem = {
     readonly label: string;
 };
 export declare const KEYBAR_KEYS: {
-    readonly run: readonly [{
-        readonly key: "↑↓";
-        readonly label: "Move";
-    }, {
-        readonly key: "⏎";
-        readonly label: "Open";
-    }, {
-        readonly key: "←";
-        readonly label: "Back";
-    }, {
-        readonly key: "Tab";
-        readonly label: "Panel";
-    }, {
-        readonly key: "?";
-        readonly label: "Help";
-    }, {
-        readonly key: "q";
-        readonly label: "Quit";
-    }, {
-        readonly key: "f";
-        readonly label: "Follow";
-    }, {
-        readonly key: "/";
-        readonly label: "Filter";
-    }];
-    readonly setup: readonly [{
-        readonly key: "↑↓";
-        readonly label: "Move";
-    }, {
-        readonly key: "⏎";
+    readonly run: readonly import("./keys.js").KeybarEntry[];
+    readonly setup: readonly [import("./keys.js").KeybarEntry, {
+        readonly key: string;
         readonly label: "Next";
-    }, {
-        readonly key: "←";
-        readonly label: "Back";
-    }, {
-        readonly key: "Tab";
-        readonly label: "Panel";
-    }, {
-        readonly key: "?";
-        readonly label: "Help";
-    }, {
-        readonly key: "q";
-        readonly label: "Quit";
-    }, {
+    }, import("./keys.js").KeybarEntry, import("./keys.js").KeybarEntry, import("./keys.js").KeybarEntry, import("./keys.js").KeybarEntry, {
         readonly key: "␣";
         readonly label: "Toggle";
     }, {
@@ -171,9 +132,11 @@ export declare function StatusStrip({ items, width, }: {
     items: readonly StatusStripItem[];
     width: number;
 }): ReactElement;
-export declare function JournalRowPanel({ rows, width, focused, title, }: {
+export declare function JournalRowPanel({ rows, width, focused, title, selection, }: {
     rows: readonly JournalRow[];
     width?: number | string;
     focused?: boolean;
     title?: string;
+    /** Index of the row the pointer marks; undefined draws no pointer. */
+    selection?: number;
 }): ReactElement;

package/dist/tui/cockpit/components.js

@@ -6,22 +6,16 @@ import { GLYPHS } from "../../brand.js";
 import { COCKPIT_DATA_RAMP, COCKPIT_INKS, TEXT_EMPHASIS_TOKENS, } from "./theme.js";
 import { SPARKLINE_BUCKET_WINDOW } from "./derive.js";
 export { SPARKLINE_BUCKET_WINDOW } from "./derive.js";
+import { keybarEntries, RUN_KEY_BINDINGS } from "./keys.js";
 const SPARKLINE_GLYPHS = ["▁", "▂", "▃", "▄", "▅", "▆", "▇", "█"];
 const BAND_GAP_COLUMNS = 1;
 const PANEL_HORIZONTAL_CHROME = 4;
 const READABLE_PANEL_COLUMNS = 20;
 export const PANEL_CHROME_ROWS = 3;
 export const BAND_CONTINUATION_PREFIX = "↳ ";
-const RUN_KEYS = [
-    { key: "↑↓", label: "Move" },
-    { key: "⏎", label: "Open" },
-    { key: "←", label: "Back" },
-    { key: "Tab", label: "Panel" },
-    { key: "?", label: "Help" },
-    { key: "q", label: "Quit" },
-    { key: "f", label: "Follow" },
-    { key: "/", label: "Filter" },
-];
+// The run keybar is generated from the registered handlers (keys.ts), so a
+// key with no handler cannot be advertised here.
+const RUN_KEYS = keybarEntries(RUN_KEY_BINDINGS);
 const SETUP_ADDITIONAL_KEYS = [
     { key: "␣", label: "Toggle" },
     { key: "a", label: "All" },
@@ -275,6 +269,6 @@ export function Keybar({ surface, width, }) {
 export function StatusStrip({ items, width, }) {
     return (_jsx(OneLineItems, { width: width, label: "cockpit status", children: items.map((item, index) => (_jsxs(Box, { flexShrink: 0, children: [index > 0 && _jsx(BodyText, { emphasis: "dim", children: " \u00B7 " }), _jsx(StateGlyph, { state: item.state }), _jsxs(BodyText, { children: [" ", item.text] })] }, `${item.state}:${item.text}`))) }));
 }
-export function JournalRowPanel({ rows, width, focused, title = "JOURNAL", }) {
-    return (_jsx(Panel, { title: title, focused: focused, width: width, children: rows.map((row, index) => (_jsxs(Box, { flexDirection: "row", flexWrap: "nowrap", height: 1, overflow: "hidden", children: [_jsx(BodyText, { emphasis: "dim", children: row.time }), _jsx(BodyText, { children: " " }), _jsx(StateGlyph, { state: row.state }), _jsxs(BodyText, { children: [" ", row.text] })] }, row.id ?? `${row.time}:${row.state}:${index}`))) }));
+export function JournalRowPanel({ rows, width, focused, title = "JOURNAL", selection, }) {
+    return (_jsx(Panel, { title: title, focused: focused, width: width, children: rows.map((row, index) => (_jsxs(Box, { flexDirection: "row", flexWrap: "nowrap", height: 1, overflow: "hidden", children: [_jsx(BodyText, { emphasis: "dim", children: row.time }), _jsx(BodyText, { children: " " }), _jsx(StateGlyph, { state: row.state }), _jsx(BodyText, { children: " " }), index === selection && (_jsxs(BodyText, { emphasis: "strong", children: [GLYPHS.pointer, " "] })), _jsx(BodyText, { children: row.text })] }, row.id ?? `${row.time}:${row.state}:${index}`))) }));
 }

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

@@ -0,0 +1,149 @@
+/**
+ * THE key contract for the run cockpit. This registry is the single source of
+ * truth for both halves of a key: what the keybar advertises and what the key
+ * does. The keybar's entries are derived from these bindings (`keybarEntries`),
+ * so a key with no registered handler cannot be drawn — an advertised key that
+ * does nothing is not expressible.
+ */
+/** The subset of an ink key event the run bindings discriminate on. */
+export type RunKeyEvent = {
+    readonly input: string;
+    readonly key: {
+        readonly upArrow?: boolean;
+        readonly downArrow?: boolean;
+        readonly leftArrow?: boolean;
+        readonly return?: boolean;
+        readonly tab?: boolean;
+        readonly escape?: boolean;
+        readonly backspace?: boolean;
+        readonly delete?: boolean;
+        readonly ctrl?: boolean;
+    };
+};
+/**
+ * The observable interaction state of the run surface. RunCockpitFrame renders
+ * every field of it — selection pointer, panel focus, opened event, follow
+ * indicator, filter prompt, help overlay — so the initial state below renders
+ * byte-identical to a frame that carries no interaction state at all, and every
+ * transition away from it is a change an operator can see.
+ */
+export type RunInteractionState = {
+    /** The journal row the pointer marks — moved by ↑↓, -1 while nothing is selected. */
+    readonly selection: number;
+    /** The focused panel, index into RUN_PANEL_FOCUS_ORDER — cycled by Tab. */
+    readonly panel: number;
+    /** The selection opened by ⏎, or null once ← returns from it. */
+    readonly opened: number | null;
+    /** Follow mode — toggled by f; drawn as a status-strip indicator while on. */
+    readonly follow: boolean;
+    /** The / prompt is open and taking filter text. */
+    readonly filterPrompt: boolean;
+    /** The text the journal is narrowed to — empty shows every row. */
+    readonly filterQuery: string;
+    /** Help overlay — toggled by ?. */
+    readonly help: boolean;
+    /** Quit requested by q. */
+    readonly quit: boolean;
+};
+export declare function initialRunInteractionState(): RunInteractionState;
+/**
+ * The panels Tab cycles focus through, in cycle order; index 0 is the focus
+ * the surface opens with, so the initial frame is the one the anchors pin.
+ */
+export declare const RUN_PANEL_FOCUS_ORDER: readonly ["RUN", "VIEWS", "KEYS"];
+export type RunKeyBinding = {
+    /** The glyph the keybar draws, e.g. "↑↓". */
+    readonly key: string;
+    /** The promise the keybar draws next to the glyph, e.g. "Move". */
+    readonly label: string;
+    /** Whether a key event activates this binding. */
+    readonly matches: (event: RunKeyEvent) => boolean;
+    /** The state transition the label promises. */
+    readonly apply: (state: RunInteractionState, event: RunKeyEvent) => RunInteractionState;
+    /**
+     * How a binding that carries on/off state reports it — the brand's reserved
+     * toggle glyphs, never bracket toggles. Present exactly on the bindings
+     * whose state is on/off.
+     */
+    readonly report?: (state: RunInteractionState) => string;
+};
+/** A toggle's on/off report: the brand's reserved glyphs, never brackets. */
+export declare function toggleReport(label: string, on: boolean): string;
+/**
+ * Every key the run surface advertises, in keybar order. Each entry carries
+ * its handler, so advertisement and behaviour cannot drift apart.
+ */
+export declare const RUN_KEY_BINDINGS: readonly RunKeyBinding[];
+/** The panels the setup surface cycles through, in their painted order. */
+export declare const SETUP_PANEL_FOCUS_ORDER: readonly ["SETUP", "HARNESSES", "KEYS"];
+/**
+ * The observable state owned by setup's bindings. Its initial value is the
+ * already-pinned setup frame: step two, the harness body focused, nothing
+ * selected, no modal action open. Every handler moves away from that state in
+ * a way SetupCockpitFrame paints.
+ */
+export type SetupInteractionState = {
+    readonly selection: number;
+    readonly panel: number;
+    readonly step: number;
+    readonly selected: readonly number[];
+    readonly all: boolean;
+    readonly probeRevision: number;
+    readonly savePrompt: boolean;
+    readonly saved: boolean;
+    readonly help: boolean;
+    readonly quit: boolean;
+};
+export declare function initialSetupInteractionState(): SetupInteractionState;
+export type SetupKeyBinding = {
+    readonly key: string;
+    readonly label: string;
+    readonly matches: (event: RunKeyEvent) => boolean;
+    readonly apply: (state: SetupInteractionState, event: RunKeyEvent) => SetupInteractionState;
+    readonly report?: (state: SetupInteractionState) => string;
+};
+/**
+ * Every setup advertisement and handler, in the exact order the surface has
+ * always drawn. The global six are registered here with setup semantics; the
+ * six setup-only bindings follow them on the same surface registry.
+ */
+export declare const SETUP_KEY_BINDINGS: readonly SetupKeyBinding[];
+/** One surface-aware registry serves both cockpit renderers and dispatchers. */
+export declare const SURFACE_KEY_BINDINGS: {
+    readonly run: readonly RunKeyBinding[];
+    readonly setup: readonly SetupKeyBinding[];
+};
+/** Save confirmation owns input until it is accepted or dismissed. */
+export declare function applySetupPromptInput(event: RunKeyEvent, state: SetupInteractionState): SetupInteractionState | undefined;
+/**
+ * The transitions of the open / prompt. The prompt is not an advertised key,
+ * so it has no binding — but its transitions live here beside the registry
+ * because they rewrite the same interaction state: characters grow the query,
+ * backspace shrinks it, ⏎ applies it (the journal stays narrowed), escape
+ * cancels it. Anything else the prompt swallows unchanged.
+ */
+export declare function applyFilterInput(event: RunKeyEvent, state: RunInteractionState): RunInteractionState | undefined;
+/** What an advertisement looks like once the handler is stripped away. */
+export type KeybarEntry = {
+    readonly key: string;
+    readonly label: string;
+};
+/**
+ * The keybar's entries, derived from a binding registry. This is the only way
+ * a keybar list is produced: remove a handler and its entry disappears.
+ */
+export declare function keybarEntries(bindings: readonly {
+    readonly key: string;
+    readonly label: string;
+}[]): readonly KeybarEntry[];
+/** The binding a key event activates, or undefined when no handler owns it. */
+export declare function resolveRunKeyBinding(bindings: readonly RunKeyBinding[], event: RunKeyEvent): RunKeyBinding | undefined;
+/**
+ * Send a key event to the registry: the matching binding's handler produces
+ * the next interaction state. An event no handler owns changes nothing.
+ */
+export declare function dispatchRunKey(event: RunKeyEvent, state: RunInteractionState, bindings?: readonly RunKeyBinding[]): RunInteractionState | undefined;
+/** The setup binding a key event activates, or undefined when none owns it. */
+export declare function resolveSetupKeyBinding(bindings: readonly SetupKeyBinding[], event: RunKeyEvent): SetupKeyBinding | undefined;
+/** Send a key event through the setup half of the shared surface registry. */
+export declare function dispatchSetupKey(event: RunKeyEvent, state: SetupInteractionState, bindings?: readonly SetupKeyBinding[]): SetupInteractionState | undefined;

package/dist/tui/cockpit/keys.js

@@ -0,0 +1,265 @@
+import { GLYPHS } from "../../brand.js";
+export function initialRunInteractionState() {
+    return {
+        selection: -1,
+        panel: 0,
+        opened: null,
+        follow: false,
+        filterPrompt: false,
+        filterQuery: "",
+        help: false,
+        quit: false,
+    };
+}
+/**
+ * The panels Tab cycles focus through, in cycle order; index 0 is the focus
+ * the surface opens with, so the initial frame is the one the anchors pin.
+ */
+export const RUN_PANEL_FOCUS_ORDER = ["RUN", "VIEWS", "KEYS"];
+/** A toggle's on/off report: the brand's reserved glyphs, never brackets. */
+export function toggleReport(label, on) {
+    return `${label} ${on ? GLYPHS.toggleActive : GLYPHS.toggleInactive}`;
+}
+/**
+ * Every key the run surface advertises, in keybar order. Each entry carries
+ * its handler, so advertisement and behaviour cannot drift apart.
+ */
+export const RUN_KEY_BINDINGS = [
+    {
+        key: "↑↓",
+        label: "Move",
+        matches: ({ key }) => key.upArrow === true || key.downArrow === true,
+        apply: (state, { key }) => ({
+            ...state,
+            selection: Math.max(-1, state.selection + (key.upArrow === true ? -1 : 1)),
+        }),
+    },
+    {
+        key: "⏎",
+        label: "Open",
+        matches: ({ key }) => key.return === true,
+        apply: (state) => state.selection >= 0 ? { ...state, opened: state.selection } : state,
+    },
+    {
+        key: "←",
+        label: "Back",
+        matches: ({ key }) => key.leftArrow === true,
+        apply: (state) => ({ ...state, opened: null }),
+    },
+    {
+        key: "Tab",
+        label: "Panel",
+        matches: ({ key }) => key.tab === true,
+        apply: (state) => ({
+            ...state,
+            panel: (state.panel + 1) % RUN_PANEL_FOCUS_ORDER.length,
+        }),
+    },
+    {
+        key: "?",
+        label: "Help",
+        matches: ({ input }) => input === "?",
+        apply: (state) => ({ ...state, help: !state.help }),
+    },
+    {
+        key: "q",
+        label: "Quit",
+        matches: ({ input }) => input === "q",
+        apply: (state) => ({ ...state, quit: true }),
+    },
+    {
+        key: "f",
+        label: "Follow",
+        matches: ({ input }) => input === "f",
+        apply: (state) => ({ ...state, follow: !state.follow }),
+        report: (state) => toggleReport("Follow", state.follow),
+    },
+    {
+        key: "/",
+        label: "Filter",
+        matches: ({ input }) => input === "/",
+        apply: (state) => ({ ...state, filterPrompt: true, filterQuery: "" }),
+    },
+];
+/** The panels the setup surface cycles through, in their painted order. */
+export const SETUP_PANEL_FOCUS_ORDER = ["SETUP", "HARNESSES", "KEYS"];
+export function initialSetupInteractionState() {
+    return {
+        selection: -1,
+        panel: 1,
+        step: 2,
+        selected: [],
+        all: false,
+        probeRevision: 0,
+        savePrompt: false,
+        saved: false,
+        help: false,
+        quit: false,
+    };
+}
+function setupStep(state, delta) {
+    return { ...state, step: Math.min(6, Math.max(1, state.step + delta)) };
+}
+/**
+ * Every setup advertisement and handler, in the exact order the surface has
+ * always drawn. The global six are registered here with setup semantics; the
+ * six setup-only bindings follow them on the same surface registry.
+ */
+export const SETUP_KEY_BINDINGS = [
+    {
+        key: "↑↓",
+        label: "Move",
+        matches: ({ key }) => key.upArrow === true || key.downArrow === true,
+        apply: (state, { key }) => ({
+            ...state,
+            selection: key.upArrow === true
+                ? Math.max(0, state.selection - 1)
+                : state.selection + 1,
+        }),
+    },
+    {
+        key: "⏎",
+        label: "Next",
+        matches: ({ key }) => key.return === true,
+        apply: (state) => setupStep(state, 1),
+    },
+    {
+        key: "←",
+        label: "Back",
+        matches: ({ key }) => key.leftArrow === true,
+        apply: (state) => setupStep(state, -1),
+    },
+    {
+        key: "Tab",
+        label: "Panel",
+        matches: ({ key }) => key.tab === true,
+        apply: (state) => ({
+            ...state,
+            panel: (state.panel + 1) % SETUP_PANEL_FOCUS_ORDER.length,
+        }),
+    },
+    {
+        key: "?",
+        label: "Help",
+        matches: ({ input }) => input === "?",
+        apply: (state) => ({ ...state, help: !state.help }),
+    },
+    {
+        key: "q",
+        label: "Quit",
+        matches: ({ input }) => input === "q",
+        apply: (state) => ({ ...state, quit: true }),
+    },
+    {
+        key: "␣",
+        label: "Toggle",
+        matches: ({ input }) => input === " ",
+        apply: (state) => {
+            const selection = Math.max(0, state.selection);
+            const selected = state.selected.includes(selection)
+                ? state.selected.filter((index) => index !== selection)
+                : [...state.selected, selection];
+            return { ...state, selection, selected, all: false };
+        },
+        report: (state) => toggleReport("Selection", state.all || state.selected.length > 0),
+    },
+    {
+        key: "a",
+        label: "All",
+        matches: ({ input }) => input === "a",
+        apply: (state) => ({ ...state, all: true, selected: [] }),
+    },
+    {
+        key: "r",
+        label: "Re-probe",
+        matches: ({ input }) => input === "r",
+        apply: (state) => ({ ...state, probeRevision: state.probeRevision + 1 }),
+    },
+    {
+        key: "s",
+        label: "Save",
+        matches: ({ input }) => input === "s",
+        apply: (state) => ({ ...state, savePrompt: true }),
+        report: (state) => toggleReport("Saved", state.saved),
+    },
+    {
+        key: "n",
+        label: "Next",
+        matches: ({ input }) => input === "n",
+        apply: (state) => setupStep(state, 1),
+    },
+    {
+        key: "p",
+        label: "Prev",
+        matches: ({ input }) => input === "p",
+        apply: (state) => setupStep(state, -1),
+    },
+];
+/** One surface-aware registry serves both cockpit renderers and dispatchers. */
+export const SURFACE_KEY_BINDINGS = {
+    run: RUN_KEY_BINDINGS,
+    setup: SETUP_KEY_BINDINGS,
+};
+/** Save confirmation owns input until it is accepted or dismissed. */
+export function applySetupPromptInput(event, state) {
+    if (!state.savePrompt)
+        return undefined;
+    if (event.input === "y" || event.key.return === true) {
+        return { ...state, savePrompt: false, saved: true };
+    }
+    if (event.input === "n" || event.key.escape === true) {
+        return { ...state, savePrompt: false };
+    }
+    return state;
+}
+/**
+ * The transitions of the open / prompt. The prompt is not an advertised key,
+ * so it has no binding — but its transitions live here beside the registry
+ * because they rewrite the same interaction state: characters grow the query,
+ * backspace shrinks it, ⏎ applies it (the journal stays narrowed), escape
+ * cancels it. Anything else the prompt swallows unchanged.
+ */
+export function applyFilterInput(event, state) {
+    if (!state.filterPrompt)
+        return undefined;
+    const { input, key } = event;
+    if (key.return === true)
+        return { ...state, filterPrompt: false };
+    if (key.escape === true) {
+        return { ...state, filterPrompt: false, filterQuery: "" };
+    }
+    if (key.backspace === true || key.delete === true) {
+        return { ...state, filterQuery: [...state.filterQuery].slice(0, -1).join("") };
+    }
+    if (input.length === 1 && key.ctrl !== true) {
+        return { ...state, filterQuery: state.filterQuery + input };
+    }
+    return state;
+}
+/**
+ * The keybar's entries, derived from a binding registry. This is the only way
+ * a keybar list is produced: remove a handler and its entry disappears.
+ */
+export function keybarEntries(bindings) {
+    return bindings.map(({ key, label }) => ({ key, label }));
+}
+/** The binding a key event activates, or undefined when no handler owns it. */
+export function resolveRunKeyBinding(bindings, event) {
+    return bindings.find((binding) => binding.matches(event));
+}
+/**
+ * Send a key event to the registry: the matching binding's handler produces
+ * the next interaction state. An event no handler owns changes nothing.
+ */
+export function dispatchRunKey(event, state, bindings = RUN_KEY_BINDINGS) {
+    const binding = resolveRunKeyBinding(bindings, event);
+    return binding?.apply(state, event);
+}
+/** The setup binding a key event activates, or undefined when none owns it. */
+export function resolveSetupKeyBinding(bindings, event) {
+    return bindings.find((binding) => binding.matches(event));
+}
+/** Send a key event through the setup half of the shared surface registry. */
+export function dispatchSetupKey(event, state, bindings = SETUP_KEY_BINDINGS) {
+    return resolveSetupKeyBinding(bindings, event)?.apply(state, event);
+}

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

@@ -0,0 +1,31 @@
+import type { RunCockpitData, RunCockpitSource } from "./derive.js";
+/**
+ * THE engagement selection rule — stated once, here, so it can change in one
+ * place without touching the renderer or the command: an explicit engagement
+ * reference from the command line wins; the bare command opens the most
+ * recently started engagement that has a readable journal.
+ */
+export declare function selectEngagementRunId(cwd: string, explicit?: string): string | null;
+/**
+ * The journal bytes of a real engagement — never a committed capture. A read
+ * failure throws: the caller refuses rather than drawing from nothing.
+ */
+export declare function loadEngagementSource(cwd: string, runId: string): RunCockpitSource;
+export declare function formatEventAge(ageMs: number): string;
+/**
+ * Live derivation over a real engagement's journal bytes. The header's
+ * elapsed field additionally states how long ago the engagement's last event
+ * arrived, so an engagement that has stopped moving reads as stale rather
+ * than as current. Throws on unreadable bytes (empty capture, no run-start) —
+ * the caller refuses instead of rendering a plausible surface from nothing.
+ */
+export declare function deriveLiveRunCockpitData(source: RunCockpitSource, binaryVersion: string, now?: () => number): RunCockpitData;
+export declare function runLiveCockpit({ input, output, cwd, runId, binaryVersion, refreshMs, now, }: {
+    input: NodeJS.ReadStream;
+    output: NodeJS.WriteStream;
+    cwd: string;
+    runId: string;
+    binaryVersion: string;
+    refreshMs?: number;
+    now?: () => number;
+}): Promise<void>;

package/dist/tui/cockpit/live.js

@@ -0,0 +1,135 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { render, useApp, useInput } from "ink";
+import { createElement, useEffect, useState } from "react";
+import { stateDirName } from "../../graph/graph.js";
+import { Journal, parseRunId } from "../../run/journal.js";
+import { deriveRunCockpitData, RunCockpitFrame } from "./run-cockpit.js";
+import { applyFilterInput, dispatchRunKey, initialRunInteractionState, SURFACE_KEY_BINDINGS, } from "./keys.js";
+// ponytail: fixed 2s re-derive cadence, matching `status --watch`; promote to a
+// config knob only if an operator asks.
+const REFRESH_MS = 2_000;
+/**
+ * THE engagement selection rule — stated once, here, so it can change in one
+ * place without touching the renderer or the command: an explicit engagement
+ * reference from the command line wins; the bare command opens the most
+ * recently started engagement that has a readable journal.
+ */
+export function selectEngagementRunId(cwd, explicit) {
+    if (explicit !== undefined)
+        return parseRunId(explicit);
+    return Journal.latestRunId(cwd, { withJournal: true });
+}
+/**
+ * The journal bytes of a real engagement — never a committed capture. A read
+ * failure throws: the caller refuses rather than drawing from nothing.
+ */
+export function loadEngagementSource(cwd, runId) {
+    const id = parseRunId(runId);
+    const path = join(cwd, stateDirName(cwd), "runs", id, "journal.jsonl");
+    const raw = readFileSync(path, "utf8");
+    return { fileName: `${id}.journal.jsonl`, raw };
+}
+// The same s/m/h age vocabulary `status` speaks (status.ts fmtAge).
+export function formatEventAge(ageMs) {
+    const safe = Math.max(0, ageMs);
+    if (safe < 90_000)
+        return `${Math.floor(safe / 1_000)}s`;
+    if (safe < 5_400_000)
+        return `${Math.floor(safe / 60_000)}m`;
+    return `${Math.floor(safe / 3_600_000)}h`;
+}
+function lastEventMs(raw) {
+    const lines = raw.split("\n");
+    for (let index = lines.length - 1; index >= 0; index -= 1) {
+        const line = lines[index].trim();
+        if (!line)
+            continue;
+        try {
+            const parsed = JSON.parse(line);
+            const ms = typeof parsed.ts === "string" ? Date.parse(parsed.ts) : NaN;
+            if (Number.isFinite(ms))
+                return ms;
+        }
+        catch {
+            // a torn trailing line does not hide the event written before it
+        }
+    }
+    return undefined;
+}
+/**
+ * Live derivation over a real engagement's journal bytes. The header's
+ * elapsed field additionally states how long ago the engagement's last event
+ * arrived, so an engagement that has stopped moving reads as stale rather
+ * than as current. Throws on unreadable bytes (empty capture, no run-start) —
+ * the caller refuses instead of rendering a plausible surface from nothing.
+ */
+export function deriveLiveRunCockpitData(source, binaryVersion, now = Date.now) {
+    const data = deriveRunCockpitData(source, binaryVersion);
+    const lastMs = lastEventMs(source.raw);
+    const staleness = lastMs === undefined
+        ? "last event unknown"
+        : `last event ${formatEventAge(now() - lastMs)} ago`;
+    return { ...data, elapsed: `${data.elapsed} · ${staleness}` };
+}
+function LiveApp({ cwd, runId, binaryVersion, columns, rows, refreshMs, now, }) {
+    const { exit } = useApp();
+    const [data, setData] = useState(() => deriveLiveRunCockpitData(loadEngagementSource(cwd, runId), binaryVersion, now));
+    const [interaction, setInteraction] = useState(initialRunInteractionState);
+    useEffect(() => {
+        const timer = setInterval(() => {
+            try {
+                setData(deriveLiveRunCockpitData(loadEngagementSource(cwd, runId), binaryVersion, now));
+            }
+            catch {
+                // a torn read mid-append keeps the last good frame rather than blanking the surface
+            }
+        }, refreshMs);
+        return () => clearInterval(timer);
+    }, [cwd, runId, binaryVersion, refreshMs, now]);
+    useInput((input, key) => {
+        if (key.ctrl && input === "c") {
+            exit();
+            return;
+        }
+        // While the / prompt is open it owns the keyboard: characters grow the
+        // query and no advertised binding fires.
+        if (interaction.filterPrompt) {
+            const prompted = applyFilterInput({ input, key }, interaction);
+            if (prompted !== undefined)
+                setInteraction(prompted);
+            return;
+        }
+        const next = dispatchRunKey({ input, key }, interaction, SURFACE_KEY_BINDINGS.run);
+        if (next === undefined)
+            return;
+        setInteraction(next);
+        if (next.quit)
+            exit();
+    });
+    return createElement(RunCockpitFrame, { data, columns, rows, interaction });
+}
+export async function runLiveCockpit({ input, output, cwd, runId, binaryVersion, refreshMs = REFRESH_MS, now = Date.now, }) {
+    const columns = output.columns ?? 80;
+    const rows = output.rows ?? 24;
+    const app = render(createElement(LiveApp, {
+        cwd,
+        runId,
+        binaryVersion,
+        columns,
+        rows,
+        refreshMs,
+        now,
+    }), {
+        stdin: input,
+        stdout: output,
+        exitOnCtrlC: false,
+        patchConsole: false,
+    });
+    try {
+        await app.waitUntilExit();
+    }
+    finally {
+        app.unmount();
+    }
+}

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

@@ -1,5 +1,6 @@
 import { type ReactElement } from "react";
 import type { RunCockpitData } from "./derive.js";
+import { type RunInteractionState } from "./keys.js";
 export { deriveRunCockpitData } from "./derive.js";
 export type { RunCockpitData } from "./derive.js";
 export { PANEL_CHROME_ROWS } from "./components.js";
@@ -12,8 +13,14 @@ export { PANEL_CHROME_ROWS } from "./components.js";
 export declare function wrappedRows(text: string, columns: number): number;
 /** The rows a bordered panel occupies when its body wraps into `columns`. */
 export declare function panelRows(lines: readonly string[], columns: number): number;
-export declare function RunCockpitFrame({ data, columns, rows, }: {
+export declare function RunCockpitFrame({ data, columns, rows, interaction, }: {
     data: RunCockpitData;
     columns: number;
     rows?: number;
+    /**
+     * The run surface's interaction state. Omitted — or at its initial value —
+     * the frame is byte-identical to the pinned appearance; every transition a
+     * binding makes is drawn from it.
+     */
+    interaction?: RunInteractionState;
 }): ReactElement;

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

@@ -3,6 +3,7 @@ import { Box } from "ink";
 import { cloneElement, } from "react";
 import { GLYPHS, PLAIN_COMPACT_LOCKUP, } from "../../brand.js";
 import { allocateBandColumns, BandLines, BodyText, CockpitGrid, composeBandLine, JournalRowPanel, KEYBAR_KEYS, Keybar, Panel, PANEL_CHROME_ROWS, ProgressMeter, StatTile, StatusStrip, } from "./components.js";
+import { RUN_PANEL_FOCUS_ORDER, RUN_KEY_BINDINGS, } from "./keys.js";
 import { resolveCockpitLayout, } from "./layout.js";
 export { deriveRunCockpitData } from "./derive.js";
 export { PANEL_CHROME_ROWS } from "./components.js";
@@ -88,19 +89,61 @@ function NarrowHeaderBand({ columns, content, rightStrong = false, }) {
     const widths = allocateBandColumns(columns, content, NARROW_HEADER_ALLOCATION);
     return (_jsxs(CockpitGrid, { columns: columns, columnContents: content, allocation: NARROW_HEADER_ALLOCATION, children: [_jsx(BandLines, { columns: Math.max(1, widths[0]), lines: content[0].lines, emphasis: "strong" }), _jsx(Box, { alignItems: "flex-end", flexDirection: "column", children: _jsx(BandLines, { columns: Math.max(1, widths[1]), lines: content[1].lines, emphasis: rightStrong ? "strong" : "normal" }) })] }));
 }
-function NavigationPanel() {
-    return (_jsxs(Panel, { title: "VIEWS", width: 16, children: [_jsxs(BodyText, { emphasis: "strong", children: [GLYPHS.pointer, " Run"] }), _jsx(BodyText, { children: "  Tasks" }), _jsx(BodyText, { children: "  Gates" }), _jsx(BodyText, { children: "  Journal" }), _jsx(BodyText, { children: "  Fleet" })] }));
+function NavigationPanel({ focused = false }) {
+    return (_jsxs(Panel, { title: "VIEWS", width: 16, focused: focused, children: [_jsxs(BodyText, { emphasis: "strong", children: [GLYPHS.pointer, " Run"] }), _jsx(BodyText, { children: "  Tasks" }), _jsx(BodyText, { children: "  Gates" }), _jsx(BodyText, { children: "  Journal" }), _jsx(BodyText, { children: "  Fleet" })] }));
 }
-function KeysPanel() {
-    return (_jsx(Panel, { title: "KEYS", width: 16, children: KEYBAR_KEYS.run.map((item) => (_jsxs(Box, { children: [_jsx(BodyText, { emphasis: "strong", children: item.key }), _jsxs(BodyText, { children: [" ", item.label] })] }, item.key))) }));
+function KeysPanel({ focused = false }) {
+    return (_jsx(Panel, { title: "KEYS", width: 16, focused: focused, children: KEYBAR_KEYS.run.map((item) => (_jsxs(Box, { children: [_jsx(BodyText, { emphasis: "strong", children: item.key }), _jsxs(BodyText, { children: [" ", item.label] })] }, item.key))) }));
 }
-function SizedJournalPanel({ rows, bodyRows, }) {
+/** The journal rows an interaction state leaves visible. */
+function visibleJournalRows(rows, interaction) {
+    const query = interaction?.filterQuery.trim().toLowerCase() ?? "";
+    if (query === "")
+        return rows;
+    return rows.filter((row) => row.text.toLowerCase().includes(query));
+}
+function SizedJournalPanel({ rows, bodyRows, title, selection, }) {
     const visible = rows.slice(0, bodyRows);
     const emptyRows = Math.max(0, bodyRows - visible.length);
-    const journal = JournalRowPanel({ rows: visible });
+    const journal = JournalRowPanel({ rows: visible, title, selection });
     const journalProps = journal.props;
     return cloneElement(journal, {}, journalProps.children, emptyRows > 0 ? _jsx(Box, { height: emptyRows }, "journal-space") : null);
 }
+/** A body panel (help overlay, opened event) padded to the journal's rows. */
+function SizedLinesPanel({ title, lines, bodyRows, }) {
+    const visible = lines.slice(0, bodyRows);
+    const emptyRows = Math.max(0, bodyRows - visible.length);
+    return (_jsxs(Panel, { title: title, children: [visible.map((line, index) => (_jsx(BodyText, { children: line }, `${index}:${line}`))), emptyRows > 0 && _jsx(Box, { height: emptyRows })] }));
+}
+/** The lines the help overlay draws: every advertised key and its promise. */
+function helpLines() {
+    return RUN_KEY_BINDINGS.map((binding) => `${binding.key} ${binding.label}`);
+}
+/** The lines the opened-event view draws for one journal row. */
+function eventLines(row) {
+    return [`${row.time} · ${row.state}`, row.text];
+}
+/**
+ * What the journal's slot of the RUN panel draws under an interaction state:
+ * the help overlay while ? is up, the opened event while ⏎'s choice stands,
+ * otherwise the journal itself — narrowed by the filter, marked at the
+ * selection, titled with the open / prompt.
+ */
+function JournalBody({ data, interaction, bodyRows, }) {
+    const rows = visibleJournalRows(data.journalRows, interaction);
+    if (interaction?.help === true) {
+        return _jsx(SizedLinesPanel, { title: "HELP", lines: helpLines(), bodyRows: bodyRows });
+    }
+    const opened = interaction?.opened ?? null;
+    if (opened !== null && opened < rows.length) {
+        return (_jsx(SizedLinesPanel, { title: "EVENT", lines: eventLines(rows[opened]), bodyRows: bodyRows }));
+    }
+    return (_jsx(SizedJournalPanel, { rows: rows, bodyRows: bodyRows, title: interaction?.filterPrompt === true
+            ? `JOURNAL /${interaction.filterQuery}`
+            : undefined, selection: interaction === undefined || interaction.selection < 0
+            ? undefined
+            : interaction.selection }));
+}
 function RunStats({ data, mode, }) {
     if (mode === "summary") {
         return (_jsx(BodyText, { children: `tasks ${data.tasks.done}/${data.tasks.total} · gates ${data.gates.passed}/${data.gates.total} · pass ${data.passRate.value}%` }));
@@ -154,7 +197,7 @@ function compactJournalRows(rows, layout, data, columns) {
         + 3; // journal border and title
     return Math.max(1, Math.min(layout.journalRows, Math.floor(rows) - fixedRows));
 }
-function LadderRunPanel({ data, layout, columns, rows, compactMeterWidth, }) {
+function LadderRunPanel({ data, layout, columns, rows, compactMeterWidth, interaction, focused = true, }) {
     const compactBodyRows = compactJournalRows(rows, layout, data, columns);
     // The approved bordered progress panel has the same meter/caption as the
     // compact form plus its border, title row and closing border. It is restored
@@ -169,16 +212,27 @@ function LadderRunPanel({ data, layout, columns, rows, compactMeterWidth, }) {
     const journalBodyRows = approvedArrangement
         ? compactBodyRows - approvedProgressChromeRows
         : compactBodyRows;
-    return (_jsxs(Panel, { title: "RUN", focused: true, flexGrow: 1, children: [_jsx(RunStats, { data: data, mode: layout.stats.mode }), layout.elements.progressBar && (approvedArrangement
+    return (_jsxs(Panel, { title: "RUN", focused: focused, flexGrow: 1, children: [_jsx(RunStats, { data: data, mode: layout.stats.mode }), layout.elements.progressBar && (approvedArrangement
                 ? (_jsx(ApprovedProgress, { data: data, caption: layout.elements.progressCaption }))
-                : (_jsx(CompactProgress, { data: data, caption: layout.elements.progressCaption, meterWidth: compactMeterWidth }))), _jsx(SizedJournalPanel, { rows: data.journalRows, bodyRows: journalBodyRows })] }));
-}
-function LegacyRunPanel({ data }) {
-    return (_jsxs(Panel, { title: "RUN", focused: true, flexGrow: 1, children: [_jsx(RunStats, { data: data, mode: "tiles" }), _jsxs(Panel, { title: "PROGRESS", children: [_jsx(ProgressMeter, { value: data.progress, width: 28 }), _jsx(BodyText, { emphasis: "dim", children: data.progressCaption })] }), _jsx(JournalRowPanel, { rows: data.journalRows })] }));
-}
-export function RunCockpitFrame({ data, columns, rows, }) {
+                : (_jsx(CompactProgress, { data: data, caption: layout.elements.progressCaption, meterWidth: compactMeterWidth }))), _jsx(JournalBody, { data: data, interaction: interaction, bodyRows: journalBodyRows })] }));
+}
+function LegacyRunPanel({ data, interaction, focused = true, }) {
+    const rows = visibleJournalRows(data.journalRows, interaction);
+    return (_jsxs(Panel, { title: "RUN", focused: focused, flexGrow: 1, children: [_jsx(RunStats, { data: data, mode: "tiles" }), _jsxs(Panel, { title: "PROGRESS", children: [_jsx(ProgressMeter, { value: data.progress, width: 28 }), _jsx(BodyText, { emphasis: "dim", children: data.progressCaption })] }), _jsx(JournalBody, { data: data, interaction: interaction, bodyRows: rows.length })] }));
+}
+export function RunCockpitFrame({ data, columns, rows, interaction, }) {
+    const focus = interaction === undefined
+        ? 0
+        : interaction.panel % RUN_PANEL_FOCUS_ORDER.length;
+    const focusedPanel = RUN_PANEL_FOCUS_ORDER[focus] ?? "RUN";
+    // Follow mode reports its on state as a status-strip item carrying the
+    // brand's reserved active-toggle glyph; off it draws nothing, so the pinned
+    // frame is untouched.
+    const statusItems = interaction?.follow === true
+        ? [...data.statusItems, { state: "active", text: "Follow" }]
+        : data.statusItems;
     if (rows === undefined) {
-        return (_jsxs(Box, { flexDirection: "column", width: columns, children: [_jsx(IdentityHeader, { data: data, columns: columns }), _jsxs(Box, { flexDirection: "row", gap: 1, children: [_jsx(NavigationPanel, {}), _jsx(LegacyRunPanel, { data: data }), _jsx(KeysPanel, {})] }), _jsx(StatusStrip, { items: data.statusItems, width: columns }), _jsx(Keybar, { surface: "run", width: columns })] }));
+        return (_jsxs(Box, { flexDirection: "column", width: columns, children: [_jsx(IdentityHeader, { data: data, columns: columns }), _jsxs(Box, { flexDirection: "row", gap: 1, children: [_jsx(NavigationPanel, { focused: focusedPanel === "VIEWS" }), _jsx(LegacyRunPanel, { data: data, interaction: interaction, focused: focusedPanel === "RUN" }), _jsx(KeysPanel, { focused: focusedPanel === "KEYS" })] }), _jsx(StatusStrip, { items: statusItems, width: columns }), _jsx(Keybar, { surface: "run", width: columns })] }));
     }
     const layout = resolveCockpitLayout(columns, rows);
     if (layout.renderer === "plain")
@@ -190,5 +244,5 @@ export function RunCockpitFrame({ data, columns, rows, }) {
             ...layout,
             stats: { ...layout.stats, mode: "summary", rows: 1 },
         };
-    return (_jsxs(Box, { flexDirection: "column", width: columns, children: [_jsx(IdentityHeader, { data: data, columns: columns, secondary: layout.elements.secondaryHeader }), _jsxs(Box, { flexDirection: "row", gap: showSideRails ? 1 : 0, children: [showSideRails && _jsx(NavigationPanel, {}), _jsx(LadderRunPanel, { data: data, layout: contentLayout, columns: columns, rows: rows, compactMeterWidth: showSideRails ? undefined : 24 }), showSideRails && _jsx(KeysPanel, {})] }), _jsx(StatusStrip, { items: data.statusItems, width: columns }), _jsx(Keybar, { surface: "run", width: columns })] }));
+    return (_jsxs(Box, { flexDirection: "column", width: columns, children: [_jsx(IdentityHeader, { data: data, columns: columns, secondary: layout.elements.secondaryHeader }), _jsxs(Box, { flexDirection: "row", gap: showSideRails ? 1 : 0, children: [showSideRails && _jsx(NavigationPanel, { focused: focusedPanel === "VIEWS" }), _jsx(LadderRunPanel, { data: data, layout: contentLayout, columns: columns, rows: rows, compactMeterWidth: showSideRails ? undefined : 24, interaction: interaction, focused: focusedPanel === "RUN" }), showSideRails && _jsx(KeysPanel, { focused: focusedPanel === "KEYS" })] }), _jsx(StatusStrip, { items: statusItems, width: columns }), _jsx(Keybar, { surface: "run", width: columns })] }));
 }

package/dist/tui/cockpit/setup-cockpit.d.ts

@@ -2,6 +2,7 @@ import { type ReactElement } from "react";
 import { type TickmarkrConfig } from "../../config/config.js";
 import { type ComponentState, type JournalRow } from "./components.js";
 import type { DemoCaptures } from "./demo.js";
+import { type SetupInteractionState, type SetupKeyBinding } from "./keys.js";
 export type SetupCockpitData = {
     readonly binaryVersion: string;
     readonly harnesses: readonly {
@@ -34,8 +35,10 @@ export declare function deriveSetupCockpitData(captures: DemoCaptures, binaryVer
  * describes the fleet.
  */
 export declare const SETUP_DETAIL_ORDER: readonly ["detected", "consultsAndReviewers", "overlayDiff", "fleetAndGates"];
-export declare function SetupCockpitFrame({ data, columns, rows, }: {
+export declare function SetupCockpitFrame({ data, columns, rows, interaction, bindings, }: {
     data: SetupCockpitData;
     columns: number;
     rows?: number;
+    interaction?: SetupInteractionState;
+    bindings?: readonly SetupKeyBinding[];
 }): ReactElement;

package/dist/tui/cockpit/setup-cockpit.js

@@ -5,10 +5,12 @@ import { parse } from "yaml";
 import { BANNER, GLYPHS, PLAIN_BANNER, } from "../../brand.js";
 import { DEFAULT_CONFIG, INTEGRITY_FLOOR_SHAPES, TIER_RANK, TickmarkrConfigSchema, unifiedYamlDiff, } from "../../config/config.js";
 import { SHAPES } from "../../graph/schema.js";
-import { allocateBandColumns, BandLines, BodyText, CockpitGrid, composeBandLine, JournalRowPanel, KEYBAR_KEYS, Keybar, measureBandRows, Panel, StateGlyph, StatTile, StatusStrip, } from "./components.js";
+import { allocateBandColumns, BandLines, BodyText, CockpitGrid, composeBandLine, JournalRowPanel, measureBandRows, Panel, StateGlyph, StatTile, StatusStrip, } from "./components.js";
 import { FULL_JOURNAL_ROWS, resolveCockpitLayout, } from "./layout.js";
 import { deriveRunCockpitData, PANEL_CHROME_ROWS, panelRows, wrappedRows, } from "./run-cockpit.js";
+import { initialSetupInteractionState, keybarEntries, SETUP_PANEL_FOCUS_ORDER, SURFACE_KEY_BINDINGS, } from "./keys.js";
 const APPROVED_SIDE_RAIL_COLUMN_FLOOR = 80;
+const setupAdditionalBindings = (bindings) => bindings.filter((binding) => !SURFACE_KEY_BINDINGS.run.some((runBinding) => runBinding.key === binding.key));
 function deepMerge(base, overlay) {
     if (overlay === undefined || overlay === null)
         return base;
@@ -158,28 +160,79 @@ export function deriveSetupCockpitData(captures, binaryVersion) {
 function identityBannerLines() {
     return (process.env.NO_COLOR === undefined ? BANNER : PLAIN_BANNER).trimEnd().split("\n");
 }
-function identityVersionLines(data) {
-    return [`v${data.binaryVersion} · binary ${GLYPHS.pass}`, "setup · step 2/6"];
+function identityVersionLines(data, interaction) {
+    return [
+        `v${data.binaryVersion} · binary ${GLYPHS.pass}`,
+        `setup · step ${interaction?.step ?? 2}/6`,
+    ];
 }
-function IdentityHeader({ data, secondary = true, }) {
+function IdentityHeader({ data, secondary = true, interaction, }) {
     const mark = identityBannerLines();
-    const [version, step] = identityVersionLines(data);
+    const [version, step] = identityVersionLines(data, interaction);
     return (_jsxs(Box, { justifyContent: "space-between", children: [_jsx(Box, { flexDirection: "column", children: (secondary ? mark : mark.slice(0, 1)).map((line, index) => (_jsx(BodyText, { emphasis: "strong", children: line }, `${index}:${line}`))) }), _jsxs(Box, { flexDirection: "column", alignItems: "flex-end", children: [_jsx(BodyText, { emphasis: "strong", children: version }), secondary && _jsx(BodyText, { children: step })] })] }));
 }
-function NavigationPanel({ width = 16, compact = false, }) {
+function NavigationPanel({ width = 16, compact = false, step = 2, focused = false, }) {
+    const entries = [
+        "Detect",
+        "Harnesses",
+        "Fleet",
+        "Gates",
+        "Consults",
+        "Reviewers",
+        "Review",
+    ];
     if (!compact) {
-        return (_jsxs(Panel, { title: "SETUP", width: width, children: [_jsx(BodyText, { children: "  Detect" }), _jsxs(BodyText, { emphasis: "strong", children: [GLYPHS.pointer, " Harnesses"] }), _jsx(BodyText, { children: "  Fleet" }), _jsx(BodyText, { children: "  Gates" }), _jsx(BodyText, { children: "  Consults" }), _jsx(BodyText, { children: "  Reviewers" }), _jsx(BodyText, { children: "  Review" })] }));
+        return (_jsx(Panel, { title: "SETUP", width: width, focused: focused, children: entries.map((entry, index) => (_jsxs(BodyText, { emphasis: index + 1 === step ? "strong" : "normal", children: [index + 1 === step ? `${GLYPHS.pointer} ` : "  ", entry] }, entry))) }));
     }
-    return (_jsxs(Panel, { title: "SETUP", width: width, children: [_jsx(Box, { height: 1, overflow: "hidden", children: _jsx(BodyText, { children: "  Detect" }) }), _jsx(Box, { height: 1, overflow: "hidden", children: _jsxs(BodyText, { emphasis: "strong", children: [GLYPHS.pointer, " Harnesses"] }) }), _jsx(Box, { height: 1, overflow: "hidden", children: _jsx(BodyText, { children: "  Fleet" }) }), _jsx(Box, { height: 1, overflow: "hidden", children: _jsx(BodyText, { children: "  Gates" }) }), _jsx(Box, { height: 1, overflow: "hidden", children: _jsx(BodyText, { children: "  Consults" }) }), _jsx(Box, { height: 1, overflow: "hidden", children: _jsx(BodyText, { children: "  Reviewers" }) }), _jsx(Box, { height: 1, overflow: "hidden", children: _jsx(BodyText, { children: "  Review" }) })] }));
+    return (_jsx(Panel, { title: "SETUP", width: width, focused: focused, children: entries.map((entry, index) => (_jsx(Box, { height: 1, overflow: "hidden", children: _jsxs(BodyText, { emphasis: index + 1 === step ? "strong" : "normal", children: [index + 1 === step ? `${GLYPHS.pointer} ` : "  ", entry] }) }, entry))) }));
 }
-function KeysPanel({ width = 16 }) {
-    return (_jsx(Panel, { title: "KEYS", width: width, children: KEYBAR_KEYS.setup.map((item) => (_jsxs(Box, { children: [_jsx(BodyText, { emphasis: "strong", children: item.key }), _jsxs(BodyText, { children: [" ", item.label] })] }, item.key))) }));
+function KeysPanel({ bindings, width = 16, focused = false, }) {
+    return (_jsx(Panel, { title: "KEYS", width: width, focused: focused, children: keybarEntries(bindings).map((item) => (_jsxs(Box, { children: [_jsx(BodyText, { emphasis: "strong", children: item.key }), _jsxs(BodyText, { children: [" ", item.label] })] }, item.key))) }));
 }
-function CompactKeysPanel({ width = 16 }) {
+function CompactKeysPanel({ bindings, width = 16, focused = false, }) {
     const contentColumns = Math.max(1, width - 4);
-    return (_jsx(Panel, { title: "KEYS", width: width, children: KEYBAR_KEYS.setupAdditional.map((item) => (_jsxs(Box, { flexDirection: "row", flexWrap: "nowrap", height: 1, overflow: "hidden", children: [_jsx(BodyText, { emphasis: "strong", children: item.key }), _jsxs(BodyText, { children: [" ", item.label.slice(0, Math.max(0, contentColumns - [...item.key].length - 1))] })] }, item.key))) }));
+    return (_jsx(Panel, { title: "KEYS", width: width, focused: focused, children: keybarEntries(setupAdditionalBindings(bindings)).map((item) => (_jsxs(Box, { flexDirection: "row", flexWrap: "nowrap", height: 1, overflow: "hidden", children: [_jsx(BodyText, { emphasis: "strong", children: item.key }), _jsxs(BodyText, { children: [" ", item.label.slice(0, Math.max(0, contentColumns - [...item.key].length - 1))] })] }, item.key))) }));
+}
+function SetupKeybar({ bindings, width, }) {
+    return (_jsx(Box, { flexDirection: "row", flexWrap: "nowrap", width: width, height: 1, overflow: "hidden", "aria-label": "setup cockpit keys", children: keybarEntries(bindings).map((item, index) => (_jsxs(Box, { flexShrink: 0, children: [index > 0 && _jsx(BodyText, { emphasis: "dim", children: " \u00B7 " }), _jsx(BodyText, { emphasis: "strong", children: item.key }), _jsxs(BodyText, { emphasis: "dim", children: [" ", item.label] })] }, item.key))) }));
+}
+function SetupInteractionPanel({ data, interaction, bindings, }) {
+    if (interaction?.savePrompt === true) {
+        return (_jsx(LinePanel, { title: "SAVE", lines: ["confirm save · y yes · n cancel", ...overlayDiffLines(data)], columns: 72 }));
+    }
+    if (interaction?.help === true) {
+        return (_jsx(LinePanel, { title: "HELP", lines: keybarEntries(bindings).map((item) => `${item.key} ${item.label}`), columns: 72 }));
+    }
+    return null;
+}
+function setupStatusItems(data, interaction) {
+    const items = [
+        { state: "neutral", text: `overlay ${data.overlayTarget}` },
+        { state: "pass", text: "base untouched" },
+        interaction?.saved === true
+            ? { state: "active", text: "changes saved" }
+            : { state: "warn", text: `${data.stagedChanges.length} changes unsaved` },
+    ];
+    if (interaction !== undefined) {
+        if (interaction.all)
+            items.push({ state: "active", text: "all selected" });
+        else if (interaction.selected.length > 0) {
+            items.push({ state: "active", text: "selection selected" });
+        }
+        else if (interaction.selection >= 0) {
+            items.push({ state: "neutral", text: `selection ${interaction.selection + 1}` });
+        }
+        if (interaction.probeRevision > 0) {
+            items.push({ state: "pass", text: `re-probed ${interaction.probeRevision}` });
+        }
+        if (interaction.panel !== 1) {
+            const panel = SETUP_PANEL_FOCUS_ORDER[interaction.panel] ?? "HARNESSES";
+            items.push({ state: "neutral", text: `panel ${panel}` });
+        }
+    }
+    return items;
 }
-function fullKeysFit(rows, layout, data, columns) {
+function fullKeysFit(rows, layout, data, columns, bindings) {
     if (!layout.elements.secondaryHeader)
         return false;
     const wrappedKeyRows = {
@@ -187,7 +240,7 @@ function fullKeysFit(rows, layout, data, columns) {
         "folded-keys": 2,
         stacked: 4,
     }[layout.arrangement];
-    const panelRows = KEYBAR_KEYS.setup.length
+    const panelRows = bindings.length
         + wrappedKeyRows
         + 3; // panel borders and title row
     return headerRowsFor(layout, data, columns) + 2 + panelRows <= Math.floor(rows);
@@ -423,7 +476,7 @@ function baseRows(layout, data, columns, inner) {
         + statRowsFor(layout, data, inner)
         + PANEL_CHROME_ROWS; // review border and title
 }
-function LadderSetupPanel({ data, layout, columns, rows, }) {
+function LadderSetupPanel({ data, layout, columns, rows, interaction, bindings, focused = true, }) {
     const inner = contentInnerWidth(columns, layout);
     const preferredReviewRows = Math.min(FULL_JOURNAL_ROWS, layout.journalRows);
     const base = baseRows(layout, data, columns, inner);
@@ -434,34 +487,32 @@ function LadderSetupPanel({ data, layout, columns, rows, }) {
     const visibleReviewRows = details.complete
         ? spare
         : Math.min(preferredReviewRows, spare);
-    return (_jsxs(Panel, { title: "HARNESSES", focused: true, flexGrow: 1, children: [_jsx(SetupStats, { data: data, mode: layout.stats.mode }), details.retained.has("detected") && (_jsx(HarnessRows, { rows: details.detected, columns: Math.max(1, inner - 6) })), details.retained.has("fleetAndGates") && (_jsx(LineBand, { columns: inner, panels: [
-                    lineBandContent("FLEET", fleetLines(data)),
-                    lineBandContent("GATES", gatesLines(data)),
-                ] })), details.retained.has("consultsAndReviewers") && (_jsx(LineBand, { columns: inner, panels: [
-                    lineBandContent("CONSULTS", consultsLines(data)),
-                    lineBandContent("REVIEWERS", reviewersLines(data)),
-                ] })), details.retained.has("overlayDiff") && (_jsx(LinePanel, { title: "OVERLAY DIFF", lines: overlayDiffLines(data), columns: Math.max(1, inner - 4), emphasis: "dim" })), _jsx(SizedReviewPanel, { rows: data.reviewRows, bodyRows: visibleReviewRows })] }));
-}
-function SetupPanel({ data, inner, }) {
-    return (_jsxs(Panel, { title: "HARNESSES", focused: true, flexGrow: 1, children: [_jsxs(CockpitGrid, { children: [_jsx(StatTile, { label: "FOUND", value: data.counts.found, samples: [data.counts.found] }), _jsx(StatTile, { label: "AUTHENTICATED", value: data.counts.authenticated, samples: [data.counts.authenticated] }), _jsx(StatTile, { label: "ROUTABLE", value: data.counts.routable, samples: [data.counts.routable] })] }), _jsx(HarnessRows, { rows: detectedRows(data), columns: Math.max(1, inner - 6) }), _jsx(LineBand, { columns: inner, panels: [
-                    lineBandContent("FLEET", fleetLines(data)),
-                    lineBandContent("GATES", gatesLines(data)),
-                ] }), _jsx(LineBand, { columns: inner, panels: [
-                    lineBandContent("CONSULTS", consultsLines(data)),
-                    lineBandContent("REVIEWERS", reviewersLines(data)),
-                ] }), _jsx(LinePanel, { title: "OVERLAY DIFF", lines: overlayDiffLines(data), columns: Math.max(1, inner - 4), emphasis: "dim" }), _jsx(SizedReviewPanel, { rows: data.reviewRows, bodyRows: data.reviewRows.length })] }));
-}
-export function SetupCockpitFrame({ data, columns, rows, }) {
+    const interactionPanel = SetupInteractionPanel({ data, interaction, bindings });
+    return (_jsx(Panel, { title: "HARNESSES", focused: focused, flexGrow: 1, children: interactionPanel ?? (_jsxs(_Fragment, { children: [_jsx(SetupStats, { data: data, mode: layout.stats.mode }), details.retained.has("detected") && (_jsx(HarnessRows, { rows: details.detected, columns: Math.max(1, inner - 6) })), details.retained.has("fleetAndGates") && (_jsx(LineBand, { columns: inner, panels: [
+                        lineBandContent("FLEET", fleetLines(data)),
+                        lineBandContent("GATES", gatesLines(data)),
+                    ] })), details.retained.has("consultsAndReviewers") && (_jsx(LineBand, { columns: inner, panels: [
+                        lineBandContent("CONSULTS", consultsLines(data)),
+                        lineBandContent("REVIEWERS", reviewersLines(data)),
+                    ] })), details.retained.has("overlayDiff") && (_jsx(LinePanel, { title: "OVERLAY DIFF", lines: overlayDiffLines(data), columns: Math.max(1, inner - 4), emphasis: "dim" })), _jsx(SizedReviewPanel, { rows: data.reviewRows, bodyRows: visibleReviewRows })] })) }));
+}
+function SetupPanel({ data, inner, interaction, bindings, focused = true, }) {
+    const interactionPanel = SetupInteractionPanel({ data, interaction, bindings });
+    return (_jsx(Panel, { title: "HARNESSES", focused: focused, flexGrow: 1, children: interactionPanel ?? (_jsxs(_Fragment, { children: [_jsxs(CockpitGrid, { children: [_jsx(StatTile, { label: "FOUND", value: data.counts.found, samples: [data.counts.found] }), _jsx(StatTile, { label: "AUTHENTICATED", value: data.counts.authenticated, samples: [data.counts.authenticated] }), _jsx(StatTile, { label: "ROUTABLE", value: data.counts.routable, samples: [data.counts.routable] })] }), _jsx(HarnessRows, { rows: detectedRows(data), columns: Math.max(1, inner - 6) }), _jsx(LineBand, { columns: inner, panels: [
+                        lineBandContent("FLEET", fleetLines(data)),
+                        lineBandContent("GATES", gatesLines(data)),
+                    ] }), _jsx(LineBand, { columns: inner, panels: [
+                        lineBandContent("CONSULTS", consultsLines(data)),
+                        lineBandContent("REVIEWERS", reviewersLines(data)),
+                    ] }), _jsx(LinePanel, { title: "OVERLAY DIFF", lines: overlayDiffLines(data), columns: Math.max(1, inner - 4), emphasis: "dim" }), _jsx(SizedReviewPanel, { rows: data.reviewRows, bodyRows: data.reviewRows.length })] })) }));
+}
+export function SetupCockpitFrame({ data, columns, rows, interaction, bindings = SURFACE_KEY_BINDINGS.setup, }) {
+    const currentInteraction = interaction ?? initialSetupInteractionState();
+    const focusedPanel = SETUP_PANEL_FOCUS_ORDER[currentInteraction.panel]
+        ?? "HARNESSES";
     if (rows === undefined) {
         const inner = Math.max(1, Math.floor(columns) - (2 * 16) - 2 - 4);
-        return (_jsxs(Box, { flexDirection: "column", width: columns, children: [_jsx(IdentityHeader, { data: data }), _jsxs(Box, { flexDirection: "row", gap: 1, children: [_jsx(NavigationPanel, {}), _jsx(SetupPanel, { data: data, inner: inner }), _jsx(KeysPanel, {})] }), _jsx(StatusStrip, { width: columns, items: [
-                        { state: "neutral", text: `overlay ${data.overlayTarget}` },
-                        { state: "pass", text: "base untouched" },
-                        {
-                            state: "warn",
-                            text: `${data.stagedChanges.length} changes unsaved`,
-                        },
-                    ] }), _jsx(Keybar, { surface: "setup", width: columns })] }));
+        return (_jsxs(Box, { flexDirection: "column", width: columns, children: [_jsx(IdentityHeader, { data: data, interaction: currentInteraction }), _jsxs(Box, { flexDirection: "row", gap: 1, children: [_jsx(NavigationPanel, { step: currentInteraction.step, focused: focusedPanel === "SETUP" }), _jsx(SetupPanel, { data: data, inner: inner, interaction: currentInteraction, bindings: bindings, focused: focusedPanel === "HARNESSES" }), _jsx(KeysPanel, { bindings: bindings, focused: focusedPanel === "KEYS" })] }), _jsx(StatusStrip, { width: columns, items: setupStatusItems(data, currentInteraction) }), _jsx(SetupKeybar, { bindings: bindings, width: columns })] }));
     }
     const layout = resolveCockpitLayout(columns, rows);
     if (layout.renderer === "plain")
@@ -473,16 +524,9 @@ export function SetupCockpitFrame({ data, columns, rows, }) {
             ...layout,
             stats: { ...layout.stats, mode: "summary", rows: 1 },
         };
-    const showFullSidePanels = fullKeysFit(rows, contentLayout, data, columns);
+    const showFullSidePanels = fullKeysFit(rows, contentLayout, data, columns, bindings);
     const resolvedSidePanelWidth = sidePanelWidth(contentLayout);
-    return (_jsxs(Box, { flexDirection: "column", width: columns, children: [_jsx(IdentityHeader, { data: data, secondary: layout.elements.secondaryHeader }), _jsxs(Box, { flexDirection: "row", gap: showSideRails ? 1 : 0, children: [showSideRails && (_jsx(Box, { width: resolvedSidePanelWidth, flexShrink: 0, children: _jsx(NavigationPanel, { width: resolvedSidePanelWidth, compact: !contentLayout.elements.secondaryHeader }) })), _jsx(LadderSetupPanel, { data: data, layout: contentLayout, columns: columns, rows: rows }), showSideRails && (showFullSidePanels
-                        ? (_jsx(Box, { width: resolvedSidePanelWidth, flexShrink: 0, children: _jsx(KeysPanel, { width: resolvedSidePanelWidth }) }))
-                        : (_jsx(Box, { width: resolvedSidePanelWidth, flexShrink: 0, children: _jsx(CompactKeysPanel, { width: resolvedSidePanelWidth }) })))] }), _jsx(StatusStrip, { width: columns, items: [
-                    { state: "neutral", text: `overlay ${data.overlayTarget}` },
-                    { state: "pass", text: "base untouched" },
-                    {
-                        state: "warn",
-                        text: `${data.stagedChanges.length} changes unsaved`,
-                    },
-                ] }), _jsx(Keybar, { surface: "setup", width: columns })] }));
+    return (_jsxs(Box, { flexDirection: "column", width: columns, children: [_jsx(IdentityHeader, { data: data, secondary: layout.elements.secondaryHeader, interaction: currentInteraction }), _jsxs(Box, { flexDirection: "row", gap: showSideRails ? 1 : 0, children: [showSideRails && (_jsx(Box, { width: resolvedSidePanelWidth, flexShrink: 0, children: _jsx(NavigationPanel, { width: resolvedSidePanelWidth, compact: !contentLayout.elements.secondaryHeader, step: currentInteraction.step, focused: focusedPanel === "SETUP" }) })), _jsx(LadderSetupPanel, { data: data, layout: contentLayout, columns: columns, rows: rows, interaction: currentInteraction, bindings: bindings, focused: focusedPanel === "HARNESSES" }), showSideRails && (showFullSidePanels
+                        ? (_jsx(Box, { width: resolvedSidePanelWidth, flexShrink: 0, children: _jsx(KeysPanel, { bindings: bindings, width: resolvedSidePanelWidth, focused: focusedPanel === "KEYS" }) }))
+                        : (_jsx(Box, { width: resolvedSidePanelWidth, flexShrink: 0, children: _jsx(CompactKeysPanel, { bindings: bindings, width: resolvedSidePanelWidth, focused: focusedPanel === "KEYS" }) })))] }), _jsx(StatusStrip, { width: columns, items: setupStatusItems(data, currentInteraction) }), _jsx(SetupKeybar, { bindings: bindings, width: columns })] }));
 }

package/package.json

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