tickmarkr 2.4.1 → 2.5.0

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

@@ -0,0 +1,289 @@
+import { type JournalEvent } from "../../run/journal.js";
+import { type OperatorRecord } from "../../run/operator-state.js";
+export declare const OBSERVATION_INTERVAL_MS = 1000;
+export declare const STORE_LIMITS: {
+    readonly history: 256;
+    readonly historyBytes: number;
+    readonly recordBytes: number;
+    readonly readBytes: number;
+    readonly subscribers: 64;
+    readonly metrics: 12;
+    readonly errors: 32;
+};
+export interface SourceError {
+    source: string;
+    error: string;
+    line?: number;
+    id?: string;
+}
+export interface JournalLine extends Omit<OperatorRecord, "event"> {
+    event?: JournalEvent;
+    raw: string;
+    error?: string;
+    offset: number;
+    endOffset: number;
+}
+export interface TailSnapshot {
+    source: string;
+    generation: number;
+    identity?: string;
+    offset: number;
+    lines: number;
+    history: readonly JournalLine[];
+    errors: readonly SourceError[];
+    malformedCount: number;
+    pending: {
+        line: number;
+        bytes: number;
+    } | undefined;
+    backlogBytes: number;
+    status: "readable" | "pending" | "corrupt" | "unreadable";
+    error?: SourceError;
+    lastSuccessfulReadAt?: number;
+    bytesRead: number;
+}
+/** Byte-offset tail with a fixed read budget. Idle observations stat, but read no journal bytes. */
+export declare class JournalTail {
+    readonly source: string;
+    private readonly hooks;
+    private st?;
+    private offset;
+    private line;
+    private generation;
+    private carry;
+    private carryBytes;
+    private lineOffset;
+    private history;
+    private historyBytes;
+    private errors;
+    private malformedCount;
+    private bytesRead;
+    private lastSuccessfulReadAt?;
+    private failure?;
+    constructor(source: string, hooks?: {
+        record?: (record: OperatorRecord) => void;
+        reset?: () => void;
+    });
+    private reset;
+    poll(now?: number): TailSnapshot;
+    private appendCarry;
+    snapshot(): TailSnapshot;
+    /** Demand paging scans with fixed buffers, independent of the retained history; no growing line index. */
+    page(firstLine: number, count?: number, generation?: number): readonly JournalLine[];
+}
+export interface CachedSource<T = unknown> {
+    source: string;
+    identity?: string;
+    value?: T;
+    status: "readable" | "absent" | "unreadable";
+    error?: string;
+    observedAt: number;
+}
+export interface LiveStoreOptions {
+    cwd: string;
+    runId: string;
+    now?: () => number;
+    configPath?: string;
+    cachePath?: string;
+    isDaemonAlive?: (pid: number) => boolean;
+}
+/** C1 mount/C6 reader boundary. No timers or presence writes: the mount owns scheduling and disarm. */
+export declare function createLiveStore(options: LiveStoreOptions): {
+    snapshot: () => {
+        sequence: number;
+        observedAt: number;
+        delayed: boolean;
+        freshness: string;
+        operator: import("../../run/operator-state.js").OperatorSnapshot;
+        journal: TailSnapshot;
+        graph: CachedSource<{
+            version: 1;
+            spec: {
+                source: "speckit" | "gsd" | "prd" | "native";
+                paths: string[];
+                hash: string;
+                base?: string | undefined;
+            };
+            tasks: {
+                id: string;
+                title: string;
+                goal: string;
+                shape: "plan" | "spec" | "implement" | "tests" | "docs" | "migration" | "ui" | "refactor" | "chore";
+                complexity: number;
+                deps: string[];
+                files: string[];
+                context: string[];
+                acceptance: (string | {
+                    oracle: "command";
+                    command: string;
+                    text?: string | undefined;
+                } | {
+                    oracle: "test";
+                    test: string;
+                    text?: string | undefined;
+                } | {
+                    oracle: "judge";
+                    text: string;
+                })[];
+                gates: ("build" | "test" | "lint" | "evidence" | "scope" | "acceptance" | "review")[];
+                humanGate: boolean;
+                status: "pending" | "running" | "gated" | "failed" | "done" | "human";
+                evidence: {
+                    commits: string[];
+                    artifacts: string[];
+                    gateResults: unknown[];
+                };
+                scopeHints?: {
+                    paths: string[];
+                    confidence?: number | undefined;
+                    reason?: string | undefined;
+                }[] | undefined;
+                routingHints?: {
+                    pin?: {
+                        via: string;
+                        model: string;
+                    } | undefined;
+                    floor?: "cheap" | "mid" | "frontier" | undefined;
+                    source?: string | undefined;
+                    escalate?: boolean | undefined;
+                } | undefined;
+                timeoutMinutes?: number | undefined;
+            }[];
+            mode?: "partner-led" | "risk-based" | "staff-led" | undefined;
+        }>;
+        config: CachedSource<string>;
+        cache: CachedSource<any>;
+        lock: {
+            state: string;
+            alive: boolean | undefined;
+            expired: boolean | undefined;
+            source: string;
+            identity?: string;
+            value?: {
+                pid: number;
+                runId: string;
+                startedAt: number;
+            } | undefined;
+            status: "readable" | "absent" | "unreadable";
+            error?: string;
+            observedAt: number;
+        };
+        supervision: import("../../run/supervision.js").TierLiveness[];
+        errors: SourceError[];
+        actionsEnabled: boolean;
+        viewport: {
+            columns: number;
+            rows: number;
+        };
+        inputSequence: number;
+        metrics: {
+            observedAt: number;
+            bytesRead: number;
+        }[];
+    };
+    refresh: () => {
+        sequence: number;
+        observedAt: number;
+        delayed: boolean;
+        freshness: string;
+        operator: import("../../run/operator-state.js").OperatorSnapshot;
+        journal: TailSnapshot;
+        graph: CachedSource<{
+            version: 1;
+            spec: {
+                source: "speckit" | "gsd" | "prd" | "native";
+                paths: string[];
+                hash: string;
+                base?: string | undefined;
+            };
+            tasks: {
+                id: string;
+                title: string;
+                goal: string;
+                shape: "plan" | "spec" | "implement" | "tests" | "docs" | "migration" | "ui" | "refactor" | "chore";
+                complexity: number;
+                deps: string[];
+                files: string[];
+                context: string[];
+                acceptance: (string | {
+                    oracle: "command";
+                    command: string;
+                    text?: string | undefined;
+                } | {
+                    oracle: "test";
+                    test: string;
+                    text?: string | undefined;
+                } | {
+                    oracle: "judge";
+                    text: string;
+                })[];
+                gates: ("build" | "test" | "lint" | "evidence" | "scope" | "acceptance" | "review")[];
+                humanGate: boolean;
+                status: "pending" | "running" | "gated" | "failed" | "done" | "human";
+                evidence: {
+                    commits: string[];
+                    artifacts: string[];
+                    gateResults: unknown[];
+                };
+                scopeHints?: {
+                    paths: string[];
+                    confidence?: number | undefined;
+                    reason?: string | undefined;
+                }[] | undefined;
+                routingHints?: {
+                    pin?: {
+                        via: string;
+                        model: string;
+                    } | undefined;
+                    floor?: "cheap" | "mid" | "frontier" | undefined;
+                    source?: string | undefined;
+                    escalate?: boolean | undefined;
+                } | undefined;
+                timeoutMinutes?: number | undefined;
+            }[];
+            mode?: "partner-led" | "risk-based" | "staff-led" | undefined;
+        }>;
+        config: CachedSource<string>;
+        cache: CachedSource<any>;
+        lock: {
+            state: string;
+            alive: boolean | undefined;
+            expired: boolean | undefined;
+            source: string;
+            identity?: string;
+            value?: {
+                pid: number;
+                runId: string;
+                startedAt: number;
+            } | undefined;
+            status: "readable" | "absent" | "unreadable";
+            error?: string;
+            observedAt: number;
+        };
+        supervision: import("../../run/supervision.js").TierLiveness[];
+        errors: SourceError[];
+        actionsEnabled: boolean;
+        viewport: {
+            columns: number;
+            rows: number;
+        };
+        inputSequence: number;
+        metrics: {
+            observedAt: number;
+            bytesRead: number;
+        }[];
+    };
+    requestRefresh: () => Promise<void>;
+    subscribe: (listener: () => void) => () => void;
+    input: () => void;
+    resize: (columns: number, rows: number) => void;
+    page: (firstLine: number, count?: number, generation?: number) => readonly JournalLine[];
+    diagnostics: () => {
+        subscriptions: number;
+        pendingReads: number;
+        metrics: number;
+    };
+    dispose: () => void;
+};
+export type LiveStore = ReturnType<typeof createLiveStore>;
+export type LiveStoreSnapshot = ReturnType<LiveStore["snapshot"]>;

package/dist/tui/cockpit/live-store.js

@@ -0,0 +1,308 @@
+import { closeSync, fstatSync, openSync, readFileSync, readSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { graphPath, stateDirName } from "../../graph/graph.js";
+import { validateGraph } from "../../graph/schema.js";
+import { parseRunId } from "../../run/journal.js";
+import { isPidLive, STALE_MS } from "../../run/lock.js";
+import { readTierLiveness, SUPERVISION_TIERS } from "../../run/supervision.js";
+import { OperatorStateFold } from "../../run/operator-state.js";
+export const OBSERVATION_INTERVAL_MS = 1_000;
+export const STORE_LIMITS = { history: 256, historyBytes: 2 * 1024 * 1024, recordBytes: 1024 * 1024, readBytes: 1024 * 1024, subscribers: 64, metrics: 12, errors: 32 };
+const errorText = (e) => e instanceof Error ? e.message : String(e);
+const fileIdentity = (st) => `${st.dev}:${st.ino}`;
+const stamp = (st) => `${fileIdentity(st)}:${st.size}:${st.mtimeNs}:${st.ctimeNs}`;
+function decodeLine(bytes, source, line, offset, endOffset, generation, oversized = false) {
+    const base = { source, line, id: `${source}#L${line}`, offset, endOffset, generation };
+    let raw = "";
+    try {
+        if (oversized)
+            throw new Error(`record exceeds ${STORE_LIMITS.recordBytes} bytes; page raw evidence from disk`);
+        raw = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+        if (!raw.trim())
+            return { ...base, raw };
+        const e = JSON.parse(raw);
+        if (!e || typeof e !== "object" || typeof e.ts !== "string" || !Number.isFinite(Date.parse(e.ts)) || typeof e.event !== "string" || !e.data || typeof e.data !== "object" || Array.isArray(e.data) || (e.taskId !== undefined && typeof e.taskId !== "string"))
+            throw new Error("invalid journal record");
+        return { ...base, raw, event: e };
+    }
+    catch (e) {
+        return { ...base, raw: raw || bytes.toString("utf8"), error: errorText(e) };
+    }
+}
+/** Byte-offset tail with a fixed read budget. Idle observations stat, but read no journal bytes. */
+export class JournalTail {
+    source;
+    hooks;
+    st;
+    offset = 0;
+    line = 0;
+    generation = 0;
+    carry = Buffer.alloc(0);
+    carryBytes = 0;
+    lineOffset = 0;
+    history = [];
+    historyBytes = 0;
+    errors = [];
+    malformedCount = 0;
+    bytesRead = 0;
+    lastSuccessfulReadAt;
+    failure;
+    constructor(source, hooks = {}) {
+        this.source = source;
+        this.hooks = hooks;
+    }
+    reset() {
+        this.offset = 0;
+        this.line = 0;
+        this.carry = Buffer.alloc(0);
+        this.carryBytes = 0;
+        this.lineOffset = 0;
+        this.history = [];
+        this.historyBytes = 0;
+        this.errors = [];
+        this.malformedCount = 0;
+        this.generation++;
+        this.hooks.reset?.();
+    }
+    poll(now = Date.now()) {
+        let fd;
+        try {
+            const st = statSync(this.source, { bigint: true });
+            if (!st.isFile())
+                throw new Error("journal source is not a regular file");
+            if (!this.st || fileIdentity(st) !== fileIdentity(this.st) || st.size < this.st.size || (st.size === this.st.size && stamp(st) !== stamp(this.st)))
+                this.reset();
+            if (Number(st.size) > this.offset) {
+                fd = openSync(this.source, "r");
+                if (stamp(fstatSync(fd, { bigint: true })) !== stamp(st))
+                    throw new Error("journal changed before read; retry observation");
+                let remaining = STORE_LIMITS.readBytes;
+                const buffer = Buffer.allocUnsafe(Math.min(64 * 1024, Number(st.size) - this.offset));
+                while (this.offset < Number(st.size) && remaining > 0) {
+                    const count = readSync(fd, buffer, 0, Math.min(buffer.length, Number(st.size) - this.offset, remaining), this.offset);
+                    if (!count)
+                        throw new Error("journal truncated during read");
+                    this.bytesRead += count;
+                    remaining -= count;
+                    let begin = 0;
+                    for (let index = 0; index < count; index++)
+                        if (buffer[index] === 10) {
+                            this.appendCarry(buffer.subarray(begin, index));
+                            const endOffset = this.offset + index + 1;
+                            const row = decodeLine(this.carry, this.source, ++this.line, this.lineOffset, endOffset, this.generation, this.carryBytes > STORE_LIMITS.recordBytes);
+                            this.history.push(row);
+                            this.historyBytes += Buffer.byteLength(row.raw);
+                            while (this.history.length > STORE_LIMITS.history || this.historyBytes > STORE_LIMITS.historyBytes)
+                                this.historyBytes -= Buffer.byteLength(this.history.shift().raw);
+                            if (row.error) {
+                                this.malformedCount++;
+                                this.errors.push({ source: row.source, error: row.error, line: row.line, id: row.id });
+                                if (this.errors.length > STORE_LIMITS.errors)
+                                    this.errors.shift();
+                            }
+                            if (row.event)
+                                this.hooks.record?.({ ...row, event: row.event });
+                            this.carry = Buffer.alloc(0);
+                            this.carryBytes = 0;
+                            this.lineOffset = endOffset;
+                            begin = index + 1;
+                        }
+                    this.appendCarry(buffer.subarray(begin, count));
+                    this.offset += count;
+                }
+            }
+            this.st = st;
+            this.failure = undefined;
+            this.lastSuccessfulReadAt = now;
+        }
+        catch (e) {
+            this.failure = { source: this.source, error: errorText(e) };
+        }
+        finally {
+            if (fd !== undefined)
+                closeSync(fd);
+        }
+        return this.snapshot();
+    }
+    appendCarry(bytes) {
+        this.carryBytes += bytes.length;
+        const available = Math.max(0, STORE_LIMITS.recordBytes - this.carry.length);
+        if (available && bytes.length)
+            this.carry = Buffer.concat([this.carry, bytes.subarray(0, available)]);
+    }
+    snapshot() {
+        return {
+            source: this.source, generation: this.generation, identity: this.st && fileIdentity(this.st), offset: this.offset, lines: this.line,
+            history: this.history.slice(), errors: this.errors.slice(), malformedCount: this.malformedCount,
+            pending: this.carryBytes ? { line: this.line + 1, bytes: this.carryBytes } : undefined,
+            backlogBytes: Math.max(0, Number(this.st?.size ?? 0) - this.offset),
+            status: this.failure ? "unreadable" : this.malformedCount ? "corrupt" : this.carryBytes ? "pending" : "readable",
+            error: this.failure, lastSuccessfulReadAt: this.lastSuccessfulReadAt, bytesRead: this.bytesRead,
+        };
+    }
+    /** Demand paging scans with fixed buffers, independent of the retained history; no growing line index. */
+    page(firstLine, count = 32, generation = this.generation) {
+        if (!Number.isInteger(firstLine) || firstLine < 1)
+            throw new Error("evidence line must be a positive integer");
+        if (generation !== this.generation)
+            throw new Error("evidence belongs to a replaced journal");
+        const rows = [];
+        const reader = new JournalTail(this.source, { record: undefined });
+        // Read only enough for the requested page. The retained scanner window is bounded, even on huge files.
+        const fd = openSync(this.source, "r");
+        try {
+            const st = fstatSync(fd, { bigint: true });
+            if (this.st && stamp(st) !== stamp(this.st))
+                throw new Error("journal changed; refresh before paging");
+            const buffer = Buffer.allocUnsafe(64 * 1024);
+            let position = 0, line = 0, start = 0;
+            const limit = Math.max(1, Math.min(STORE_LIMITS.history, Math.floor(count)));
+            while (position < Number(st.size) && rows.length < limit) {
+                const n = readSync(fd, buffer, 0, buffer.length, position);
+                if (!n)
+                    break;
+                let begin = 0;
+                for (let i = 0; i < n; i++)
+                    if (buffer[i] === 10) {
+                        if (line + 1 >= firstLine)
+                            reader.appendCarry(buffer.subarray(begin, i));
+                        line++;
+                        if (line >= firstLine)
+                            rows.push(decodeLine(reader.carry, this.source, line, start, position + i + 1, generation, reader.carryBytes > STORE_LIMITS.recordBytes));
+                        reader.carry = Buffer.alloc(0);
+                        reader.carryBytes = 0;
+                        start = position + i + 1;
+                        begin = i + 1;
+                        if (rows.length >= limit)
+                            break;
+                    }
+                if (line + 1 >= firstLine && rows.length < limit)
+                    reader.appendCarry(buffer.subarray(begin, n));
+                position += n;
+            }
+            if (stamp(fstatSync(fd, { bigint: true })) !== stamp(st))
+                throw new Error("journal changed during evidence read");
+            return rows;
+        }
+        finally {
+            closeSync(fd);
+        }
+    }
+}
+class JsonSource {
+    path;
+    parse;
+    cached;
+    constructor(path, parse) {
+        this.path = path;
+        this.parse = parse;
+    }
+    read(now) {
+        try {
+            const st = statSync(this.path, { bigint: true });
+            const id = stamp(st);
+            if (this.cached?.identity === id && this.cached.status === "readable")
+                return this.cached = { ...this.cached, observedAt: now };
+            if (!st.isFile() || st.size > BigInt(STORE_LIMITS.recordBytes))
+                throw new Error("source is not a bounded regular file");
+            const value = this.parse(readFileSync(this.path, "utf8"));
+            return this.cached = { source: this.path, identity: id, value, status: "readable", observedAt: now };
+        }
+        catch (e) {
+            const absent = e.code === "ENOENT";
+            return this.cached = { source: this.path, status: absent ? "absent" : "unreadable", error: absent ? undefined : errorText(e), observedAt: now };
+        }
+    }
+}
+/** C1 mount/C6 reader boundary. No timers or presence writes: the mount owns scheduling and disarm. */
+export function createLiveStore(options) {
+    const now = options.now ?? Date.now;
+    const state = join(options.cwd, stateDirName(options.cwd));
+    let fold = new OperatorStateFold();
+    const tail = new JournalTail(join(state, "runs", parseRunId(options.runId), "journal.jsonl"), {
+        reset: () => { fold = new OperatorStateFold(); }, record: record => fold.apply(record),
+    });
+    const graph = new JsonSource(graphPath(options.cwd), raw => validateGraph(JSON.parse(raw)));
+    const config = new JsonSource(options.configPath ?? join(state, "config.yaml"), raw => raw);
+    const cache = new JsonSource(options.cachePath ?? join(state, "doctor.json"), JSON.parse);
+    const lock = new JsonSource(join(state, "graph.lock"), raw => {
+        const v = JSON.parse(raw);
+        if (!v || !Number.isInteger(v.pid) || v.pid < 1 || typeof v.runId !== "string" || typeof v.startedAt !== "number")
+            throw new Error("invalid lock payload");
+        return v;
+    });
+    const listeners = new Set();
+    let sequence = 0, lastObservation, inputSequence = 0;
+    let viewport = { columns: 120, rows: 40 };
+    let disposed = false;
+    let queued;
+    const metrics = [];
+    function observe() {
+        const observedAt = now();
+        const delayed = lastObservation !== undefined && observedAt - lastObservation > 2 * OBSERVATION_INTERVAL_MS;
+        const journal = tail.poll(observedAt);
+        const graphReading = graph.read(observedAt);
+        const configReading = config.read(observedAt);
+        const cacheReading = cache.read(observedAt);
+        const owner = lock.read(observedAt);
+        const alive = owner.status === "readable" && owner.value ? (options.isDaemonAlive ?? isPidLive)(owner.value.pid) : undefined;
+        const lockState = owner.status === "absent" ? "absent" : owner.status === "unreadable" ? "unreadable" : owner.value?.runId !== options.runId ? "foreign" : alive ? "alive" : "dead";
+        const supervision = SUPERVISION_TIERS.map(t => readTierLiveness(options.cwd, t, observedAt));
+        const errors = [journal.error, ...journal.errors, ...[graphReading, configReading, cacheReading, owner].filter(s => s.error).map(s => ({ source: s.source, error: s.error })), ...supervision.filter(s => s.state === "UNREADABLE").map(s => ({ source: join(state, "supervision", s.tier), error: "unreadable supervision" }))].filter((e) => !!e);
+        metrics.push({ observedAt, bytesRead: journal.bytesRead });
+        if (metrics.length > STORE_LIMITS.metrics)
+            metrics.shift();
+        lastObservation = observedAt;
+        const readable = journal.status === "readable" && journal.backlogBytes === 0;
+        return {
+            sequence: ++sequence, observedAt, delayed, freshness: errors.length ? "failed" : delayed ? "delayed" : "fresh",
+            operator: fold.snapshot({ graph: graphReading.status === "readable" ? graphReading.value : undefined, sequence, observedAt, readable }),
+            journal, graph: graphReading, config: configReading, cache: cacheReading,
+            lock: { ...owner, state: lockState, alive, expired: owner.identity ? observedAt - Number(owner.identity.split(":")[3]) / 1e6 > STALE_MS : undefined },
+            supervision, errors, actionsEnabled: readable && !errors.length && !delayed,
+            viewport, inputSequence, metrics: metrics.slice(),
+        };
+    }
+    let snapshot = observe();
+    const publish = () => { for (const listener of listeners)
+        listener(); };
+    const refresh = () => { if (!disposed) {
+        snapshot = observe();
+        publish();
+    } return snapshot; };
+    return {
+        snapshot: () => snapshot, refresh,
+        requestRefresh: () => {
+            if (disposed)
+                return Promise.resolve();
+            return queued ??= Promise.resolve().then(() => { refresh(); }).finally(() => { queued = undefined; });
+        },
+        subscribe: (listener) => {
+            if (disposed)
+                throw new Error("store is disposed");
+            if (listeners.size >= STORE_LIMITS.subscribers)
+                throw new Error("store subscription limit reached");
+            listeners.add(listener);
+            return () => { listeners.delete(listener); };
+        },
+        input: () => {
+            if (!disposed) {
+                inputSequence++;
+                const nextSequence = ++sequence;
+                snapshot = { ...snapshot, sequence: nextSequence, operator: { ...snapshot.operator, sequence: nextSequence }, inputSequence };
+                publish();
+            }
+        },
+        resize: (columns, rows) => {
+            if (!disposed) {
+                viewport = { columns, rows };
+                const nextSequence = ++sequence;
+                snapshot = { ...snapshot, sequence: nextSequence, operator: { ...snapshot.operator, sequence: nextSequence }, viewport };
+                publish();
+            }
+        },
+        page: (firstLine, count, generation) => tail.page(firstLine, count, generation),
+        diagnostics: () => ({ subscriptions: listeners.size, pendingReads: queued ? 1 : 0, metrics: metrics.length }),
+        dispose: () => { disposed = true; listeners.clear(); },
+    };
+}

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

@@ -1,3 +1,4 @@
+import { type ShellDelivery } from "./live-runtime.js";
 import type { CockpitGraph, RunCockpitData, RunCockpitSource } from "./derive.js";
 import { type RunInteractionState, type RunKeyEvent } from "./keys.js";
 import { type PointerReport, type PointerSurface } from "./pointer.js";
@@ -78,7 +79,11 @@ export type LiveCockpitDelivery = {
     readonly pointer: (report: PointerReport) => boolean;
     readonly batch: <Result>(deliver: () => Result) => Result;
 };
-export declare function runLiveCockpit({ input, output, cwd, runId, binaryVersion, refreshMs, now, debug, onDelivery, }: {
+/**
+ * The retired single-view mount remains exported only for its historical
+ * compatibility suite. Product callers must use {@link runLiveCockpit}.
+ */
+export declare function runLegacyCockpit({ input, output, cwd, runId, binaryVersion, refreshMs, now, debug, onDelivery, }: {
     input: NodeJS.ReadStream;
     output: NodeJS.WriteStream;
     cwd: string;
@@ -91,3 +96,18 @@ export declare function runLiveCockpit({ input, output, cwd, runId, binaryVersio
     /** Observe and control the production delivery boundary. */
     onDelivery?: (delivery: LiveCockpitDelivery) => void;
 }): Promise<void>;
+/** The production cockpit entry: one measured FINAL shell mounting C3–C5. */
+export declare function runLiveCockpit(options: {
+    input: NodeJS.ReadStream;
+    output: NodeJS.WriteStream;
+    cwd: string;
+    runId: string;
+    binaryVersion: string;
+    refreshMs?: number;
+    now?: () => number;
+    debug?: boolean;
+    /** Compatibility observer retained for the pre-existing production-mount harness. */
+    onDelivery?: (delivery: ShellDelivery) => void;
+    onShellDelivery?: (delivery: ShellDelivery) => void;
+    environment?: NodeJS.ProcessEnv;
+}): Promise<void>;

package/dist/tui/cockpit/live.js

@@ -1,3 +1,4 @@
+import { borrowRuntimeTimeline, runConsolidatedCockpit } from "./live-runtime.js";
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { render, useApp, useInput } from "ink";
@@ -441,7 +442,12 @@ function LiveApp({ delivery, size, refreshMs, }) {
         onCommittedFrame: commitFrame,
     });
 }
-export async function runLiveCockpit({ input, output, cwd, runId, binaryVersion, refreshMs = REFRESH_MS, now = Date.now, debug = false, onDelivery, }) {
+/**
+ * The retired single-view mount remains exported only for its historical
+ * compatibility suite. Product callers must use {@link runLiveCockpit}.
+ */
+export async function runLegacyCockpit({ input, output, cwd, runId, binaryVersion, refreshMs = REFRESH_MS, now = Date.now, debug = false, onDelivery, }) {
+    const releaseTimeline = borrowRuntimeTimeline();
     // Subscribe before Ink mounts so no stale-size repaint can overtake the
     // surface's newly planned frame — and before the delivery exists, which
     // routes every input against this measurement.
@@ -498,8 +504,13 @@ export async function runLiveCockpit({ input, output, cwd, runId, binaryVersion,
                 }
                 finally {
                     size.close();
+                    releaseTimeline();
                 }
             }
         }
     }
 }
+/** The production cockpit entry: one measured FINAL shell mounting C3–C5. */
+export async function runLiveCockpit(options) {
+    return runConsolidatedCockpit(options);
+}