tickmarkr 1.66.0 → 1.68.0

package/dist/cli/commands/run.js

@@ -4,6 +4,7 @@ import { ROUTING_MODES } from "../../config/config.js";
 import { pickDriver } from "../../drivers/index.js";
 import { loadGraph } from "../../graph/graph.js";
 import { formatSummary, resolveRunMode, runDaemon } from "../../run/daemon.js";
+import { isRunLockLive } from "../../run/lock.js";
 import { route, NO_EXPLORE_ENV } from "../../route/router.js";
 import { formatJournalNarration, loadRoutingProfile } from "../../run/journal.js";
 import { ttyVisual } from "../../adapters/model-lints.js";
@@ -65,6 +66,14 @@ export async function run(argv, cwd = process.cwd()) {
             throw new Error(`--route-strict: refusing to dispatch — ${conflict}`);
         console.warn(`tickmarkr: !! ${conflict}`);
     }
+    // OBS-107 (v1.67 T5): advisory only — a stale compiled graph with prior terminal statuses and no
+    // live daemon will otherwise finish with zero work and confuse the operator. The recompile remedy
+    // is named; dispatch proceeds unchanged.
+    const TERMINAL_STATUSES = ["done", "failed", "human"];
+    if (graph.tasks.some((t) => TERMINAL_STATUSES.includes(t.status)) && !isRunLockLive(cwd)) {
+        console.warn("tickmarkr: compiled graph carries terminal statuses from a prior run and no daemon is active — "
+            + "run `tickmarkr compile <src>` to recompile; proceeding with stale graph");
+    }
     const noExplore = !!values["no-explore"];
     const exploreCtx = noExplore ? { noExplore } : undefined;
     if (noExplore)

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

@@ -1,5 +1,25 @@
+import { type Task, type TaskStatus } from "../../graph/schema.js";
+import { type JournalEvent } from "../../run/journal.js";
 export type StatusOpts = {
     iterations?: number;
     sleep?: (ms: number) => Promise<void>;
 };
+export declare const GATE_KEYS: {
+    readonly build: "B";
+    readonly test: "T";
+    readonly lint: "L";
+    readonly evidence: "E";
+    readonly scope: "S";
+    readonly acceptance: "A";
+    readonly review: "R";
+};
+export declare const taskBox: (status: TaskStatus) => string;
+export declare const gateBox: (state: "open" | "pass" | "fail" | "skip", unicode: boolean) => string;
+export type GateState = "open" | "pass" | "fail" | "skip";
+export declare const defaultGateStates: (task: Task) => GateState[];
+export declare const gateStates: (task: Task, events: JournalEvent[]) => GateState[];
+export declare const gateChain: (states: GateState[], unicode: boolean) => string;
+export declare const failedGates: (states: GateState[]) => string[];
+export declare const humanGateSuffix: (t: Task, st: TaskStatus, states: GateState[]) => string;
+export declare const shortGoal: (goal: string, max: number) => string;
 export declare function status(argv: string[], cwd?: string, opts?: StatusOpts): Promise<string>;

package/dist/cli/commands/status.js

@@ -9,7 +9,7 @@ const NOT_COMPARABLE_NOTICE = "graph recompiled since this run — task states n
 // The timer must keep the process ALIVE: an unref'd timer here let the event loop drain after the
 // first frame, so a live `--watch` printed once and exited 0 (OBS-11). Never unref this.
 const defaultSleep = (ms) => new Promise((r) => setTimeout(r, ms));
-const GATE_KEYS = { build: "B", test: "T", lint: "L", evidence: "E", scope: "S", acceptance: "A", review: "R" };
+export const GATE_KEYS = { build: "B", test: "T", lint: "L", evidence: "E", scope: "S", acceptance: "A", review: "R" };
 const attemptStartIdx = (events, taskId) => {
     let idx = -1;
     for (let i = 0; i < events.length; i++) {
@@ -21,22 +21,22 @@ const attemptStartIdx = (events, taskId) => {
 };
 const visual = () => process.stdout.isTTY === true && process.env.NO_COLOR === undefined;
 // non-TTY machine surface only — the TTY frame draws task verdicts via statusRow
-const taskBox = (status) => {
+export const taskBox = (status) => {
     if (status === "done")
         return "[x]";
     if (status === "failed" || status === "human")
         return "[!]";
     return "[ ]";
 };
-const gateBox = (state, unicode) => {
+export const gateBox = (state, unicode) => {
     if (unicode) {
         // shared glyph vocabulary: pass/fail verdicts, dash for skip, dim circle for not-yet-run
         return state === "pass" ? GLYPHS.pass : state === "fail" ? GLYPHS.fail : state === "skip" ? GLYPHS.neutral : GLYPHS.toggleInactive;
     }
     return state === "pass" ? "[x]" : state === "fail" ? "[!]" : state === "skip" ? "." : "[ ]";
 };
-const defaultGateStates = (task) => GATE_NAMES.map((gate) => task.gates.includes(gate) ? "open" : "skip");
-const gateStates = (task, events) => {
+export const defaultGateStates = (task) => GATE_NAMES.map((gate) => task.gates.includes(gate) ? "open" : "skip");
+export const gateStates = (task, events) => {
     const outcomes = new Map();
     const start = attemptStartIdx(events, task.id);
     if (start >= 0) {
@@ -57,12 +57,10 @@ const gateStates = (task, events) => {
 const GATE_STATE_TOKEN = { pass: ok, fail, skip: dim, open: dim };
 // TTY cells are bare glyphs in fixed GATE_NAMES order — gate identity lives once in the frame
 // legend, and in words on a failing row; non-TTY keeps the letter+box chips (byte-pinned surface)
-const gateChain = (states, unicode) => GATE_NAMES.map((gate, i) => unicode
+export const gateChain = (states, unicode) => GATE_NAMES.map((gate, i) => unicode
     ? GATE_STATE_TOKEN[states[i]](gateBox(states[i], true))
     : `${GATE_KEYS[gate]}${gateBox(states[i], false)}`).join(" ");
-// plain (uncolored) cell width for column math — ANSI codes have zero display width
-const gateChainWidth = (unicode) => GATE_NAMES.reduce((w, gate) => w + (unicode ? 1 : GATE_KEYS[gate].length + 3) + 1, -1);
-const failedGates = (states) => GATE_NAMES.filter((_, i) => states[i] === "fail");
+export const failedGates = (states) => GATE_NAMES.filter((_, i) => states[i] === "fail");
 // plain-text form of the failed-gate words for column math; rendered with a dim dot + red names
 const failedSuffix = (states) => {
     const f = failedGates(states);
@@ -72,8 +70,8 @@ const failedSuffix = (states) => {
 // awaited approval is named from task state alone — never from gate results. Failed gates win the
 // cell when present: a post-approval park is not awaiting the designed gate. Plain text for column
 // math; rendered with a dim dot + warn words. TTY-only — the non-TTY surface stays byte-pinned.
-const humanGateSuffix = (t, st, states) => st === "human" && t.humanGate && failedGates(states).length === 0 ? " · awaiting approval" : "";
-const shortGoal = (goal, max) => {
+export const humanGateSuffix = (t, st, states) => st === "human" && t.humanGate && failedGates(states).length === 0 ? " · awaiting approval" : "";
+export const shortGoal = (goal, max) => {
     const clause = goal.split(/[,;.?!]/, 1)[0].trim();
     if (clause.length <= max)
         return clause;
@@ -182,10 +180,13 @@ const renderFrame = (cwd) => {
     const done = effective.tasks.filter((t) => t.status === "done").length;
     const cells = g.tasks.map((t) => {
         const st = replayed?.get(t.id) ?? t.status;
-        const label = starved.has(t.id) ? " starved" : activity.cells.has(t.id) ? ` ${activity.cells.get(t.id)}` : "";
+        const isStarved = starved.has(t.id);
+        const phrase = isStarved ? undefined : activity.cells.get(t.id);
+        const label = isStarved ? " starved" : phrase ? ` ${phrase}` : "";
         const channel = assignments.get(t.id) ?? "-";
-        const assignCol = contexts.has(t.id) ? `${channel}${divider}ctx ${contexts.get(t.id)}` : channel;
-        return { t, st, label, assignCol, states: comparable ? gateStates(t, events) : defaultGateStates(t) };
+        const ctx = contexts.get(t.id);
+        const assignCol = ctx !== undefined ? `${channel}${divider}ctx ${ctx}` : channel;
+        return { t, st, label, assignCol, isStarved, phrase, channel, ctx, states: comparable ? gateStates(t, events) : defaultGateStates(t) };
     });
     if (!unicode) {
         // machine/CI surface — layout unchanged (pipes, greps, and the golden pins depend on it)
@@ -227,26 +228,39 @@ const renderFrame = (cwd) => {
     // rows: the line names task ids, and rows must stay the first id-bearing lines for grep consumers.
     const nowLine = activity.now ? [legend(`   now: ${activity.now}`)] : [];
     const gatesLegend = legend(`   gates: ${GATE_NAMES.join(" · ")}`);
+    // Two-line card per task (operator request, v1.67): line 1 carries identity + verdict — glyph,
+    // id, goal at full width, and only SHORT status words. Line 2 carries the machinery, dim and
+    // aligned under the goal: gate chain, live activity phrase (or channel), ctx. Long channel names
+    // and activity phrases live on line 2 only, so they can never squeeze the goal or wrap line 1.
     const taskVerdict = (st) => st === "done" ? "pass" : st === "failed" ? "fail" : st === "human" ? "warn" : "neutral";
     const idW = Math.max(...cells.map((c) => c.t.id.length), 2);
-    const stW = Math.max(...cells.map((c) => (String(c.st) + c.label + failedSuffix(c.states) + humanGateSuffix(c.t, c.st, c.states)).length));
-    const chainW = gateChainWidth(true);
-    const assignW = Math.max(...cells.map((c) => c.assignCol.length));
-    const goalW = Math.max(8, width - (5 + idW) - 2 - chainW - 2 - stW - 2 - assignW);
-    const rows = cells.map(({ t, st, label, assignCol, states }) => {
-        const goal = shortGoal(t.goal, goalW).padEnd(goalW);
+    // plain-text status suffixes for width math only — starved / failed gate names / approval hint
+    const suffixPlain = (c) => (c.isStarved ? " · starved" : "") + failedSuffix(c.states) + humanGateSuffix(c.t, c.st, c.states);
+    const stW = Math.max(...cells.map((c) => String(c.st).length + suffixPlain(c).length));
+    const avail = Math.max(8, width - (5 + idW) - 2 - stW);
+    const goals = cells.map((c) => shortGoal(c.t.goal, avail));
+    const goalW = Math.max(8, ...goals.map((s) => s.length));
+    const indent = " ".repeat(idW + 5); // line 2 starts under the goal column
+    const rows = cells.map(({ t, st, states, isStarved, phrase, channel, ctx }, i) => {
         const stWord = st === "done" ? ok(String(st)) : st === "failed" ? fail(String(st)) : st === "human" ? warn(String(st)) : String(st);
         // a fail names its gate in words right here — the one moment gate identity is needed on a row
         const f = failedGates(states);
         const human = humanGateSuffix(t, st, states);
         const statusCell = stWord +
-            (label ? (label === " starved" ? fail(label) : dim(label)) : "") +
-            (f.length ? dim(" · ") + fail(f.join(", ")) : "") +
-            (human ? dim(" · ") + warn("awaiting approval") : "") +
-            " ".repeat(stW - (String(st) + label + failedSuffix(states) + human).length);
-        return `  ${statusRow(taskVerdict(st), `${t.id.padEnd(idW)} ${goal}  ${gateChain(states, true)}  ${statusCell}  ${dim(assignCol)}`)}`;
-    });
-    return [header, hr, gatesLegend, ...rows, ...nowLine].join("\n");
+            (isStarved ? dot + fail("starved") : "") +
+            (f.length ? dot + fail(f.join(", ")) : "") +
+            (human ? dot + warn("awaiting approval") : "");
+        const line1 = `  ${statusRow(taskVerdict(st), `${t.id.padEnd(idW)} ${goals[i].padEnd(goalW)}  ${statusCell}`)}`;
+        // activity already names its channel for in-flight attempts — never repeat it
+        const detail = [
+            ...(phrase ? [phrase, ...(phrase.includes(channel) || channel === "-" ? [] : [channel])] : [channel]),
+            ...(ctx !== undefined ? [`ctx ${ctx}`] : []),
+        ].join(" · ");
+        return [line1, `${indent}${gateChain(states, true)}  ${dim(detail)}`, ""];
+    }).flat();
+    if (!nowLine.length)
+        rows.pop(); // cards end blank-separated; drop the dangling one
+    return [header, hr, gatesLegend, "", ...rows, ...nowLine].join("\n");
 };
 export async function status(argv, cwd = process.cwd(), opts = {}) {
     // cockpit surface: banner + frame on a TTY (doctor's pattern); pipes get the bare frame

package/dist/compile/collateral.d.ts

@@ -4,6 +4,7 @@ import { type Task } from "../graph/schema.js";
  * Each line names the task id and at least one missing collateral test path.
  */
 export declare function collateralLints(tasks: ReadonlyArray<Pick<Task, "id" | "files">>, repoRoot: string): string[];
+export declare function newDirectoryLints(tasks: ReadonlyArray<Pick<Task, "id" | "files">>, repoRoot: string): string[];
 /**
  * OBS-76 class: sweep src/ for out-of-scope source files that reference a symbol the acceptance
  * criteria name — the v1.52 router.ts omission, named at plan time instead of one judge round in.

package/dist/compile/collateral.js

@@ -145,20 +145,69 @@ function criteriaSymbols(acceptance) {
     }
     return [...out].sort();
 }
+const ARCH_PAGES = ["docs/codebase/ARCHITECTURE.md", "docs/codebase/STRUCTURE.md"];
+function topLevelSrcDir(file) {
+    const parts = file.replace(/^\.\//, "").replace(/\/+$/, "").split("/");
+    if (parts[0] !== "src" || parts.length < 2 || !parts[1])
+        return undefined;
+    return parts[1];
+}
+function existingSrcTopLevels(repoRoot) {
+    const out = new Set();
+    let entries;
+    try {
+        entries = readdirSync(join(repoRoot, "src"), { withFileTypes: true });
+    }
+    catch {
+        return out;
+    }
+    for (const e of entries) {
+        if (e.isDirectory())
+            out.add(e.name);
+    }
+    return out;
+}
+// OBS-108 (v1.67 T5): a task whose files[] creates a new top-level src/ directory must also
+// include the architecture pages the docs-truth suite pins. Advisory only — never blocks compile.
+export function newDirectoryLints(tasks, repoRoot) {
+    const existing = existingSrcTopLevels(repoRoot);
+    const lines = [];
+    for (const t of tasks) {
+        // OBS-22: scopeGate accepts picomatch globs; advisory warnings must agree.
+        const scoped = picomatch(t.files.map((f) => f.replace(/^\.\//, "")), { dot: true });
+        const newDirs = new Set();
+        for (const f of t.files) {
+            const dir = topLevelSrcDir(f);
+            if (!dir || existing.has(dir))
+                continue;
+            newDirs.add(`src/${dir}/`);
+        }
+        if (!newDirs.size)
+            continue;
+        const missing = ARCH_PAGES.filter((p) => !scoped(p));
+        if (!missing.length)
+            continue;
+        const dirList = [...newDirs].sort().join(", ");
+        const dirLabel = newDirs.size > 1 ? "directories" : "directory";
+        lines.push(`${t.id}: new top-level source ${dirLabel} ${dirList} must include ${missing.join(" and ")} in files[]`);
+    }
+    return lines;
+}
 /**
  * OBS-76 class: sweep src/ for out-of-scope source files that reference a symbol the acceptance
  * criteria name — the v1.52 router.ts omission, named at plan time instead of one judge round in.
  * Advisory plan output only, same contract as collateralLints.
  */
 export function sourceScopeLints(tasks, repoRoot) {
+    const newDirLints = newDirectoryLints(tasks, repoRoot);
     const perTask = tasks
         .map((t) => ({ t, needles: criteriaSymbols(t.acceptance) }))
         .filter((x) => x.needles.length);
     if (!perTask.length)
-        return [];
+        return newDirLints;
     const srcFiles = walkCode(repoRoot, "src");
     if (!srcFiles.length)
-        return [];
+        return newDirLints;
     const read = makeReader(repoRoot);
     const lines = [];
     for (const { t, needles } of perTask) {
@@ -183,5 +232,5 @@ export function sourceScopeLints(tasks, repoRoot) {
         const tail = hits.length > MAX_HITS_PER_TASK ? " (capped)" : "";
         lines.push(`${t.id}: criteria implicate out-of-scope source not in files[]: ${listed}${tail}`);
     }
-    return lines;
+    return [...newDirLints, ...lines];
 }

package/dist/gates/run-gates.js

@@ -72,16 +72,23 @@ export async function runGates(task, ctx) {
         // worker attempt — exactly what this fix forbids; only its meta-carries-channel pattern is mirrored.
         // Straight-line single `if` — NO loop/counter/knob: exactly-once by construction (a knob is a
         // fail-closed weakening vector); a second garbage verdict fails the gate closed exactly as today.
+        // T6: exclusion mirrors consult reroute semantics — the flaked channel's whole adapter is banned, not
+        // just its exact channel key, so an outage window cannot re-select the vendor being routed around.
+        // If no other adapter is live, the exclusion degrades to a channel-level reroute within the same
+        // adapter so a single-adapter fleet still retries (matching the daemon's unknown-excludeAdapter
+        // degradation path).
         if (a.meta?.unparseable === true && typeof a.meta.judge === "string") {
             const flakedKey = a.meta.judge;
-            const candidate = ctx.channels
-                .filter((c) => channelKey(c) !== flakedKey)
+            const flakedAdapter = flakedKey.slice(0, flakedKey.indexOf(":"));
+            const pick = (pool) => pool
                 // pickReviewer's sort (review.ts:37): TIER_RANK desc, marginalCostRank asc — proven ordering; both
-                // symbols already imported by a sibling gate file. No vendor-diversity axis (the judge isn't review).
+                // symbols already imported by a sibling gate file.
                 .sort((x, y) => TIER_RANK[y.tier] - TIER_RANK[x.tier] || marginalCostRank(x) - marginalCostRank(y))[0];
-            // ponytail: same-channel fallback when the fleet has no alternative (D-03). One judge call against a
-            // deterministic garbage source is wasted, bounded; fail-closed unchanged on a second garbage verdict.
-            const retry = candidate ?? { adapter: ctx.cfg.judge.adapter, model: ctx.cfg.judge.model };
+            const crossAdapter = pick(ctx.channels.filter((c) => c.adapter !== flakedAdapter));
+            const sameAdapter = pick(ctx.channels.filter((c) => c.adapter === flakedAdapter && channelKey(c) !== flakedKey));
+            // Prefer a different adapter; if the fleet only has one adapter, retry on a different channel of
+            // that adapter; if the fleet has only one channel, fall back to the original judge config.
+            const retry = crossAdapter ?? sameAdapter ?? { adapter: ctx.cfg.judge.adapter, model: ctx.cfg.judge.model };
             const retryAdapter = getAdapter(retry.adapter, ctx.adapters);
             const retryJvia = ctx.via
                 // unconditional -r1 suffix: under keepPanes:forever a same-channel retry cannot collide with the

package/dist/run/daemon.js

@@ -4,7 +4,7 @@ import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { stringify } from "yaml";
-import { classifyDeadChannel, trailerPattern, writePrompt } from "../adapters/prompt.js";
+import { classifyDeadChannel, NO_TRAILER_SUMMARY, trailerPattern, UNPARSEABLE_TRAILER_SUMMARY, writePrompt } from "../adapters/prompt.js";
 import { allAdapters, discoverChannels, getAdapter, probeAll, readDoctor } from "../adapters/registry.js";
 import { addUsage, channelKey, matchesTrustDialog, QUOTA_RE } from "../adapters/types.js";
 import { bannerShell, paneDispatchCommand } from "../brand.js";
@@ -658,6 +658,7 @@ export async function runDaemon(repoRoot, opts = {}) {
                 let output;
                 let exitCode;
                 let timedOut = false;
+                let settleParsed;
                 if (interactive) {
                     // v1.2 interactive: the TUI doesn't exit on completion — the trailer is the finish line.
                     // The exit wrapper still fires if the TUI dies (crash/quit): fast-fail instead of burning the timeout.
@@ -748,6 +749,29 @@ export async function runDaemon(repoRoot, opts = {}) {
                         await driver.waitAgentStatus(slot, "idle", 5_000); // settle, then re-harvest the final render
                         output = await driver.read(slot, 1000);
                     }
+                    // T5 / OBS-111: an interactive harvest can race the TUI's final paint. When the pane
+                    // contains the nonce token but the JSON hasn't balanced yet, settle and re-read through
+                    // the existing pane-read seam once or twice before recording a malformed-trailer cause.
+                    if (interactive) {
+                        const stallWindowMs = taskTimeoutMinutes * 60_000;
+                        const settleDeadline = attemptStart + stallWindowMs;
+                        const settleDelayMs = 1_000;
+                        const maxSettleRetries = 2;
+                        let settleTries = 0;
+                        settleParsed = adapter.parse(output, nonce);
+                        while (settleParsed.summary === UNPARSEABLE_TRAILER_SUMMARY && settleTries < maxSettleRetries) {
+                            const remaining = settleDeadline - Date.now();
+                            if (remaining <= 0)
+                                break;
+                            await new Promise((r) => setTimeout(r, Math.min(settleDelayMs, remaining)));
+                            output = await driver.read(slot, 1000);
+                            settleParsed = adapter.parse(output, nonce);
+                            settleTries++;
+                        }
+                        if (settleParsed.summary !== UNPARSEABLE_TRAILER_SUMMARY) {
+                            finished = settleParsed.summary !== NO_TRAILER_SUMMARY;
+                        }
+                    }
                 }
                 else {
                     await driver.run(slot, paneDispatchCommand(dispatchScript));
@@ -800,7 +824,7 @@ export async function runDaemon(repoRoot, opts = {}) {
                     tokens = addUsage(tokens, attemptUsage);
                     metered++;
                 }
-                const result = adapter.parse(output, nonce);
+                const result = settleParsed ?? adapter.parse(output, nonce);
                 const cause = classifyWorkerResultCause({ output, ok: result.ok, finished, exitCode, summary: result.summary, timedOut });
                 journal.append("worker-result", t.id, {
                     ok: result.ok, summary: result.summary, deviations: result.deviations, finished, exitCode,

package/dist/run/git.d.ts

@@ -1,5 +1,7 @@
 import { ROUTING_ENV_SEAMS } from "../route/router.js";
 export { ROUTING_ENV_SEAMS };
+export declare const FORK_CAP_ENV = "VITEST_MAX_FORKS";
+export declare const DEFAULT_FORK_CAP = "6";
 export interface ShResult {
     code: number;
     stdout: string;

package/dist/run/git.js

@@ -5,6 +5,12 @@ import { shq } from "../adapters/types.js";
 import { tickmarkrDir } from "../graph/graph.js";
 import { ROUTING_ENV_SEAMS } from "../route/router.js";
 export { ROUTING_ENV_SEAMS };
+// OBS-110: gate/baseline/tip-verify children are vitest suites; without a fork cap, concurrent
+// full-suite gate runs fork a worker-per-core pool per worktree and saturate the operator box.
+// Default to a modest cap through the environment so vitest honors it natively; never pass it
+// as argv (OBS-55) so child test oracles stay intact. The operator's own export wins.
+export const FORK_CAP_ENV = "VITEST_MAX_FORKS";
+export const DEFAULT_FORK_CAP = "6";
 // stdin "ignore": same class as HARD-05 / SubprocessDriver — never leave an open pipe a child can block on
 // (pi -p / codex exec wait for stdin EOF). timedOut distinguishes SIGKILL-timeout from a real nonzero exit.
 function shell(cmd, cwd, timeoutMs, login) {
@@ -15,6 +21,9 @@ function shell(cmd, cwd, timeoutMs, login) {
     const env = { ...process.env };
     for (const k of ROUTING_ENV_SEAMS)
         delete env[k];
+    // OBS-110: apply the default fork cap only when the operator has not already set one.
+    if (!(FORK_CAP_ENV in env))
+        env[FORK_CAP_ENV] = DEFAULT_FORK_CAP;
     return new Promise((resolve) => {
         // detached: bash gets its own process group so a timeout can kill the whole tree —
         // SIGKILLing bash alone orphans grandchildren (codex/pi) that hold the stdio pipes

package/dist/tui/app.d.ts

@@ -1,5 +1,7 @@
 import { type OutputStream } from "../tui/engine.js";
 import type { InputStream } from "../tui/input.js";
+import type { FleetEditable } from "../config/config.js";
+import { type FleetEdit } from "./staging.js";
 export type View = {
     id: string;
     label: string;
@@ -7,17 +9,32 @@ export type View = {
         cols: number;
         rows: number;
     }): string[];
+    /** Optional per-view key handler (e.g. up/down cursor movement). */
+    key?(name: string): void;
 };
 export type StudioOptions = {
     input: InputStream;
     output: OutputStream;
+    /** Loaded fleet state the buffer wraps. Defaults to an empty editable for the no-arg shell path. */
+    loaded?: FleetEditable;
+    /** Repository root used for overlay paths and live-run detection. Defaults to cwd. */
+    repoRoot?: string;
+    /** Global config directory override. */
+    globalDir?: string;
 };
 export declare class StudioApp {
     private engine;
     private views;
     private active;
     private showingHelp;
+    private confirmingQuit;
+    private showingSave;
+    private saveTarget;
+    private saveProposal;
     private notice;
+    private staging;
+    private repoRoot;
+    private globalDir;
     private _lines;
     private resolveExit;
     readonly exited: Promise<void>;
@@ -30,11 +47,26 @@ export declare class StudioApp {
     start(): void;
     /** Restore the terminal and release the input stream. */
     stop(): void;
+    /** Apply an edit to the staging buffer and repaint. Intended as the test seam and future edit hook. */
+    stageEdit(edit: FleetEdit): void;
+    private get isModalOpen();
     private bindKeys;
+    private handleEscape;
+    private handleQuit;
+    private handleSaveOpen;
+    private handleSaveToggle;
+    private handleConfirm;
+    private handleCancel;
+    private executeSave;
+    private closeSave;
+    private handleRevert;
     private setView;
+    private forwardViewKey;
     private showNotice;
     private paint;
     private buildFrame;
     private renderTabBar;
+    private renderStatusBar;
     private renderHelp;
+    private renderQuitConfirm;
 }