tickmarkr 2.5.4 → 2.5.6

package/dist/run/merge.js

@@ -2,8 +2,10 @@ import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { shq } from "../adapters/types.js";
 import { ceilingKillResult, classifyFreshRunnerOutput, classifyRunnerOutput, fileCountDeficit, waitForCalmWindow, effectiveCeilingMs, fingerprint, freshFailures, } from "../gates/baseline.js";
+import { evaluateManifestedTest, isVitestTestCommand } from "../gates/test-manifest.js";
+import { computeVerificationIdentity, formatReusedDetails, getVerdictStore, getWorktreeTree, resolveStateDir, isInfraResult, } from "../gates/cache.js";
 import { tickmarkrDir } from "../graph/graph.js";
-import { describeCapacity, gitHead, linkNodeModules, resolveIntegrationBranch, sameCapacity, sh, shGit, shGitOk, WORKTREES_DIR } from "./git.js";
+import { describeCapacity, gitHead, linkNodeModules, resolveIntegrationBranch, resolvedCapacity, sameCapacity, sh, shGit, shGitOk, WORKTREES_DIR } from "./git.js";
 export function integrationBranch(cfg, runId) {
     return `${cfg.integrationBranchPrefix}${runId}`;
 }
@@ -120,6 +122,11 @@ export async function verifyIntegrationTip(intWt, commands, runDir, baseline) {
         }
         return results;
     }
+    const stateDir = resolveStateDir(intWt, runDir);
+    const store = getVerdictStore(stateDir);
+    // Publish only after the entire verification completes. The daemon kills a cancelled
+    // verifier process, so completed early gates must remain in memory until then.
+    const pending = new Map();
     for (const [gate, cmd] of gatesToRun) {
         if (runStartCommands !== undefined) {
             const expectedCmd = gate === "test"
@@ -150,6 +157,73 @@ export async function verifyIntegrationTip(intWt, commands, runDir, baseline) {
         const entry = gate === "test" && (hasTipCommand || (!identity.test && identity.tipTest))
             ? baseline?.commands.tipTest
             : baseline?.commands[gate];
+        // A distinct tipTest selects a different forgiveness entry even when the command
+        // converges with the task command. Include that effective entry in the identity.
+        const verificationBaseline = baseline ? { commands: { ...baseline.commands } } : undefined;
+        if (verificationBaseline) {
+            if (entry)
+                verificationBaseline.commands[gate] = entry;
+            else
+                delete verificationBaseline.commands[gate];
+        }
+        // A tip verifier may reuse only a completed green from its own scope.
+        const id = await computeVerificationIdentity({
+            worktree: intWt,
+            gate,
+            scope: "tip",
+            command: cmd,
+            baseline: verificationBaseline,
+            selectedSet: undefined,
+            capacity: resolvedCapacity(),
+        });
+        // Persistent reuse requires the run's durable journal. Without it there is no
+        // recorded cycle provenance to reconcile with the caller's capacity checks.
+        const hit = journalFound ? store.get(id) : undefined;
+        if (hit && id && hit.pass && !isInfraResult(hit)) {
+            results.push({
+                gate,
+                cmd,
+                pass: hit.pass,
+                exitCode: hit.exitCode ?? 0,
+                fingerprints: hit.meta?.fingerprints ?? [],
+                ...(hit.meta?.forgiven ? { forgiven: true } : {}),
+                details: formatReusedDetails(hit.details, id),
+                ...(hit.meta?.reportPath ? { reportPath: hit.meta.reportPath } : {}),
+                ...(hit.meta?.spawnedCommand ? { spawnedCommand: hit.meta.spawnedCommand } : {}),
+                ...(hit.meta?.artifact ? { artifact: hit.meta.artifact } : {}),
+            });
+            continue;
+        }
+        if (id && journalFound)
+            pending.set(gate, id);
+        // VL-1: tip verify and standalone verify read the SAME invocation-bound report the gate would —
+        // a detected vitest test command never reaches the stdout-count/file-count path below (this
+        // gate's own manifest is always the FULL suite; verify has no selected screen to hold). A
+        // scripted test command that is not the detected runner falls through unchanged.
+        if (gate === "test" && isVitestTestCommand(cmd, intWt)) {
+            const outcome = await evaluateManifestedTest(cmd, intWt, {
+                baselineDurations: entry?.fileDurations,
+                longestFile: entry?.longestFile,
+                overallCeilingMs: effectiveCeilingMs(entry),
+                artifactDir: runDir,
+            });
+            const artifact = join(runDir, `tip-verify-${gate}.log`);
+            if (!outcome.pass)
+                writeFileSync(artifact, outcome.details);
+            results.push({
+                gate,
+                cmd,
+                pass: outcome.pass,
+                exitCode: outcome.exitCode,
+                reportPath: outcome.reportPath,
+                spawnedCommand: outcome.meta.spawnedCommand,
+                fingerprints: outcome.meta.failingTests ?? [],
+                details: outcome.details,
+                ...(outcome.classification ? { cause: outcome.classification } : {}),
+                ...(outcome.pass ? {} : { artifact }),
+            });
+            continue;
+        }
         // OBS-534: the ceiling is the BATTERY's, derived by effectiveCeilingMs from the same baseline entry
         // this loop already reads for forgiveness two lines down — never the flat DEFAULT_SHELL_TIMEOUT_MS
         // `sh` defaults to. A suite whose capture measured 600007ms carries a recorded 1800021ms ceiling;
@@ -216,7 +290,7 @@ export async function verifyIntegrationTip(intWt, commands, runDir, baseline) {
         const pass = !deficit && (r.code === 0 || greenTeardown || forgiven);
         if (!pass)
             writeFileSync(artifact, raw);
-        results.push({
+        const tipResult = {
             gate,
             cmd,
             pass,
@@ -233,7 +307,21 @@ export async function verifyIntegrationTip(intWt, commands, runDir, baseline) {
             ...(forgiven && !deficit ? { forgiven: true } : {}),
             ...(cause ? { cause } : {}),
             ...(pass ? {} : { artifact }),
-        });
+        };
+        results.push(tipResult);
+    }
+    // Recheck through the Git runner before publishing: cancellation disables further
+    // spawns in the daemon child, and a command that changed the tree invalidates reuse.
+    const completedTree = pending.size ? await getWorktreeTree(intWt) : undefined;
+    for (const result of results) {
+        const id = pending.get(result.gate);
+        if (id && id.tree === completedTree && !isInfraResult(result)) {
+            store.set(id, { ...result, meta: {
+                    fingerprints: result.fingerprints, forgiven: result.forgiven,
+                    reportPath: result.reportPath, spawnedCommand: result.spawnedCommand,
+                    artifact: result.artifact,
+                } });
+        }
     }
     return results;
 }

package/dist/run/operator-state.d.ts

@@ -30,11 +30,19 @@ export interface OperatorTask {
     evidence?: EvidenceIdentity;
     mergeEvidence?: EvidenceIdentity;
     gates: Record<string, OperatorGate>;
+    /** BD-1: the board's per-task counters — latest dispatch channel, review verdicts drawn, human parks. */
+    channel?: string;
+    reviewRounds: number;
+    parks: number;
 }
 export interface OperatorSnapshot {
     sequence: number;
     observedAt: number;
     lastEventAt?: string;
+    firstEventAt?: string;
+    /** BD-1 header counts: run-resume and escalation rows seen. */
+    resumes: number;
+    escalations: number;
     lifecycle: "PENDING" | "RUNNING" | "PARTIAL" | "APPROVED" | "COMPLETE" | "UNKNOWN";
     label: string;
     green: boolean;
@@ -63,6 +71,9 @@ export declare class OperatorStateFold {
     private approved;
     private tipFailed;
     private lastEventAt?;
+    private firstEventAt?;
+    private resumes;
+    private escalations;
     private passed;
     private total;
     apply(record: OperatorRecord): void;

package/dist/run/operator-state.js

@@ -16,11 +16,19 @@ export class OperatorStateFold {
     approved = false;
     tipFailed = false;
     lastEventAt;
+    firstEventAt;
+    resumes = 0;
+    escalations = 0;
     passed = 0;
     total = 0;
     apply(record) {
         const { event: e } = record;
         this.lastEventAt = e.ts;
+        this.firstEventAt ??= e.ts;
+        if (e.event === "run-resume")
+            this.resumes++;
+        if (e.event === "escalation")
+            this.escalations++;
         const ref = identity(record);
         if (e.event === "run-start" || e.event === "run-resume") {
             if (e.event === "run-start" && !this.start) {
@@ -72,6 +80,9 @@ export class OperatorStateFold {
             t.path = typeof e.data.worktree === "string" ? e.data.worktree : typeof e.data.cwd === "string" ? e.data.cwd : undefined;
             t.pane = typeof e.data.pane === "string" ? e.data.pane : undefined;
             t.alarmMs = typeof e.data.alarmMs === "number" ? e.data.alarmMs : undefined;
+            const a = e.data.assignment;
+            if (a && typeof a.adapter === "string" && typeof a.model === "string")
+                t.channel = `${a.adapter}:${a.model}`;
         }
         if (e.event === "task-done")
             t.state = "completed";
@@ -85,6 +96,7 @@ export class OperatorStateFold {
             t.state = "failed";
         if (e.event === "task-human") {
             t.state = "human";
+            t.parks++;
             t.parkKind = typeof e.data.kind === "string" ? e.data.kind : undefined;
         }
         if (e.event === "task-blocked")
@@ -98,6 +110,8 @@ export class OperatorStateFold {
         if (typeof gate === "string" && GATE_NAMES.includes(gate)) {
             if (e.event === "gate-start")
                 t.gates[gate] = { state: "running", evidence: ref };
+            if (e.event === "gate-result" && gate === "review")
+                t.reviewRounds++;
             if (e.event === "gate-result")
                 t.gates[gate] = {
                     state: e.data.disabled === true ? "disabled" : e.data.skipped === true ? "not-run" : e.data.pass === true ? "passed" : e.data.pass === false ? "failed" : "unknown", evidence: ref,
@@ -107,7 +121,7 @@ export class OperatorStateFold {
     task(id) {
         let t = this.tasks.get(id);
         if (!t) {
-            t = { id, state: "unknown", merged: false, dispatches: 0, gates: emptyGates() };
+            t = { id, state: "unknown", merged: false, dispatches: 0, reviewRounds: 0, parks: 0, gates: emptyGates() };
             this.tasks.set(id, t);
         }
         return t;
@@ -117,7 +131,7 @@ export class OperatorStateFold {
         const comparable = this.comparableTo(hash);
         const ids = comparable ? [...graph.tasks.map(t => t.id), ...[...this.tasks.keys()].filter(id => !graph.tasks.some(t => t.id === id))] : [...this.tasks.keys()];
         const tasks = ids.map(id => {
-            const t = this.tasks.get(id) ?? { id, state: "unknown", merged: false, dispatches: 0, gates: emptyGates() };
+            const t = this.tasks.get(id) ?? { id, state: "unknown", merged: false, dispatches: 0, reviewRounds: 0, parks: 0, gates: emptyGates() };
             return { ...t, title: comparable ? graph.tasks.find(g => g.id === id)?.title : undefined, gates: Object.fromEntries(Object.entries(t.gates).map(([g, cell]) => [g, { ...cell }])) };
         });
         const buckets = Object.fromEntries(bucketNames.map(k => [k, this.end?.buckets[k] === undefined ? undefined : [...this.end.buckets[k]]]));
@@ -134,7 +148,7 @@ export class OperatorStateFold {
             && bucketNames.every(k => buckets[k]?.length === 0);
         const lifecycle = !readable || !this.start ? "UNKNOWN" : this.active ? "RUNNING" : this.approved ? "APPROVED" : green ? "COMPLETE" : this.end ? "PARTIAL" : "PENDING";
         return {
-            sequence, observedAt, lastEventAt: this.lastEventAt, lifecycle,
+            sequence, observedAt, lastEventAt: this.lastEventAt, firstEventAt: this.firstEventAt, resumes: this.resumes, escalations: this.escalations, lifecycle,
             label: this.approved ? "approved; resume required" : lifecycle,
             green, currentTip, comparable, comparison: comparable ? "matching graph" : "not comparable",
             merged,

package/dist/run/recovery.d.ts

@@ -0,0 +1,8 @@
+import type { GateResult } from "../gates/types.js";
+import type { JournalEvent } from "./journal.js";
+export type FailureDisposition = "infrastructure" | "behavioral" | "unknown";
+export type VerificationRetryCause = "infrastructure" | "host-starved";
+/** Structured verifier evidence wins; neither an exit code nor prose proves infrastructure. */
+export declare function failureDisposition(result: Pick<GateResult, "pass" | "meta">): FailureDisposition;
+/** Reserve before re-execution. Interrupted reservations and new subjects never refill the task cap. */
+export declare function reserveInfrastructureRetry(events: readonly JournalEvent[], taskId: string, subject: string, append: (event: string, taskId: string, data: Record<string, unknown>) => void, cause?: VerificationRetryCause): boolean;

package/dist/run/recovery.js

@@ -0,0 +1,25 @@
+/** Structured verifier evidence wins; neither an exit code nor prose proves infrastructure. */
+export function failureDisposition(result) {
+    if (result.pass)
+        return "unknown";
+    if (result.meta?.classification === "regression")
+        return "behavioral";
+    if (result.meta?.infra === true && result.meta?.classification === "infra")
+        return "infrastructure";
+    return "unknown";
+}
+/** Reserve before re-execution. Interrupted reservations and new subjects never refill the task cap. */
+export function reserveInfrastructureRetry(events, taskId, subject, append, cause = "infrastructure") {
+    const used = events.filter((e) => e.taskId === taskId && e.event === "infra-retry-reserved");
+    const malformed = used.some((e) => typeof e.data.subject !== "string" || !e.data.subject
+        || (e.data.cause !== "infrastructure" && e.data.cause !== "host-starved"));
+    const reason = !subject ? "unknown-subject" : malformed ? "invalid-accounting"
+        : used.some((e) => e.data.subject === subject) ? "subject-allowance-exhausted"
+            : used.length >= 2 ? "task-allowance-exhausted" : undefined;
+    if (reason) {
+        append("infra-retry-denied", taskId, { subject, cause, reason, consumed: used.length });
+        return false;
+    }
+    append("infra-retry-reserved", taskId, { subject, cause, consumed: used.length + 1 });
+    return true;
+}

package/dist/run/repair-selection.d.ts

@@ -0,0 +1,12 @@
+import type { JournalEvent } from "./journal.js";
+export interface RepairSelectionDecision {
+    selectTests: boolean;
+    requiredFiles: string[];
+    reason: "no-test-failure" | "known-failing-files" | "legacy-test-failure" | "unattributed-test-failure" | "full-suite-failure";
+}
+type SelectionEvent = Pick<JournalEvent, "event" | "taskId" | "data">;
+/** Diagnostic selection only: neither a narrow pass nor this decision can authorize integration.
+ * Distrust and known failing files survive later green results, approvals and resume. A historical
+ * ambiguous failure is never reinterpreted using a newly enabled policy. */
+export declare function repairSelectionDecision(events: readonly SelectionEvent[], taskId: string, enabled: boolean): RepairSelectionDecision;
+export {};

package/dist/run/repair-selection.js

@@ -0,0 +1,56 @@
+/** These are literal repository-relative identities. Existence and selection support are checked
+ * against the current worktree by the gate; this journal fold cannot establish either. */
+function fileIdentities(value) {
+    if (!Array.isArray(value) || value.length === 0 || value.some((file) => typeof file !== "string" || !file || /[\\\x00-\x1f\x7f]/.test(file)
+        || /^[A-Za-z]:/.test(file) || file.split("/").some((part) => !part || part === "." || part === ".."))) {
+        return undefined;
+    }
+    return [...new Set(value)].sort();
+}
+/** Diagnostic selection only: neither a narrow pass nor this decision can authorize integration.
+ * Distrust and known failing files survive later green results, approvals and resume. A historical
+ * ambiguous failure is never reinterpreted using a newly enabled policy. */
+export function repairSelectionDecision(events, taskId, enabled) {
+    const required = new Set();
+    let distrust;
+    for (const event of events) {
+        if (event.taskId !== taskId || event.event !== "gate-result"
+            || event.data.gate !== "test" || event.data.pass !== false)
+            continue;
+        const data = event.data;
+        if (!enabled) {
+            distrust ??= "legacy-test-failure";
+            continue;
+        }
+        // Only the recorded closed disposition can exempt infrastructure. Contradictory structured
+        // failure evidence cannot turn a behavioral failure into a harmless infrastructure event.
+        if (data.disposition === "infrastructure" && data.classification !== "regression"
+            && (data.failingFiles === undefined || (Array.isArray(data.failingFiles) && data.failingFiles.length === 0)))
+            continue;
+        if (data.disposition !== "behavioral" || typeof data.commit !== "string"
+            || !/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/i.test(data.commit)) {
+            distrust ??= "unattributed-test-failure";
+            continue;
+        }
+        // A replacement full-suite failure follows a passing screen in the current pipeline. No
+        // ordinary full-suite failure establishes that a selector safely covers the failed behavior.
+        if (data.fullSuite === true) {
+            distrust ??= "full-suite-failure";
+            continue;
+        }
+        const selected = fileIdentities(data.selectedTests);
+        const failing = fileIdentities(data.failingFiles);
+        if (!selected || !failing || failing.some((file) => !selected.includes(file))
+            || (data.fullSuite !== undefined && data.fullSuite !== false)) {
+            distrust ??= "unattributed-test-failure";
+            continue;
+        }
+        for (const file of failing)
+            required.add(file);
+    }
+    return {
+        selectTests: distrust === undefined,
+        requiredFiles: [...required].sort(),
+        reason: distrust ?? (required.size ? "known-failing-files" : "no-test-failure"),
+    };
+}

package/dist/run/stall.d.ts

@@ -10,6 +10,10 @@ export declare function harvestCpuFlatWindowMs(resolutionMs: number): number;
 /** Test seam — pin the quantization-aware flat window without changing production policy. */
 export declare function setHarvestCpuFlatMsForTests(ms: number): void;
 export declare function resetHarvestCpuFlatMsForTests(): void;
+/** The dispatch shell records its foreground group in an attempt-unique artifact. */
+export declare function readOwnedProcessGroup(path: string): number | undefined;
+/** Never infer ownership from a task name or scan another attempt's marker when reaping. */
+export declare function reapOwnedProcessGroup(group: number | undefined, cwd: string): Promise<number[] | null>;
 export declare function workerTreeCpuMs(marker: string, cwd: string): Promise<{
     ms: number;
     resolutionMs: number;
@@ -17,6 +21,7 @@ export declare function workerTreeCpuMs(marker: string, cwd: string): Promise<{
 export declare class WorkerTreeCpuAccountant {
     private marker;
     private cwd;
+    private group?;
     private active;
     private loop;
     private live;
@@ -24,7 +29,7 @@ export declare class WorkerTreeCpuAccountant {
     private gaps;
     private consecutiveGaps;
     private latest;
-    constructor(marker: string, cwd: string);
+    constructor(marker: string, cwd: string, group?: (() => number | undefined) | undefined);
     private sample;
     start(): Promise<void>;
     read(): {

package/dist/run/stall.js

@@ -52,6 +52,51 @@ function parsePsCpu(raw) {
         + Math.round(Number(m[4]) * 1000);
     return { ms, frac: m[4].includes(".") };
 }
+/** The dispatch shell records its foreground group in an attempt-unique artifact. */
+export function readOwnedProcessGroup(path) {
+    try {
+        const raw = readFileSync(path, "utf8").trim();
+        const group = /^\d+$/.test(raw) ? Number(raw) : 0;
+        return Number.isSafeInteger(group) && group > 1 ? group : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Never infer ownership from a task name or scan another attempt's marker when reaping. */
+export async function reapOwnedProcessGroup(group, cwd) {
+    if (group === undefined)
+        return null;
+    const own = await shGit(`ps -o pgid= -p ${process.pid}`, cwd, 5_000);
+    // An in-process driver fixture (or a non-isolating host) can share the daemon's
+    // group. It is not an owned worker group: let the driver's close retire that slot.
+    if (own.code !== 0 || !/^\d+$/.test(own.stdout.trim()) || Number(own.stdout.trim()) === group)
+        return null;
+    try {
+        process.kill(-group, "SIGKILL");
+    }
+    catch (error) {
+        if (error.code !== "ESRCH")
+            throw error;
+    }
+    let survivors = [];
+    // SIGKILL delivery and process retirement are asynchronous. Bound the confirmation
+    // grace, retaining names if a process is still present after it.
+    for (let probe = 0; probe < 5; probe++) {
+        const snapshot = await shGit("ps -Awwo pid=,pgid=,stat=", cwd, 5_000);
+        if (snapshot.code !== 0)
+            return null;
+        survivors = snapshot.stdout.split("\n").flatMap((line) => {
+            const row = /^\s*(\d+)\s+(\d+)\s+(\S+)/.exec(line);
+            return row && Number(row[2]) === group && !row[3].startsWith("Z") ? [Number(row[1])] : [];
+        });
+        if (survivors.length === 0)
+            break;
+        if (probe < 4)
+            await new Promise((resolve) => setTimeout(resolve, 50));
+    }
+    return survivors;
+}
 let linuxClockTickMs;
 function linuxProcessCpuMs(pid, cwd) {
     if (!existsSync("/proc/self/stat"))
@@ -81,7 +126,7 @@ function linuxProcessCpuMs(pid, cwd) {
 // Every non-seeded worker process descends from its attempt-unique dispatch script. One ps snapshot
 // finds that root and its descendants. An empty tree is measurable zero; a failed or unparseable
 // snapshot is undefined because missing evidence can never prove inactivity.
-async function workerTreeCpuSnapshot(marker, cwd) {
+async function workerTreeCpuSnapshot(marker, cwd, group) {
     const snapshot = await shGit("ps -Awwo pid=,ppid=,time=,command=", cwd, 15_000);
     if (snapshot.code !== 0)
         return undefined;
@@ -97,6 +142,16 @@ async function workerTreeCpuSnapshot(marker, cwd) {
     if (rows.length === 0)
         return undefined;
     const tree = new Set(rows.filter((p) => p.cmd.includes(marker)).map((p) => p.pid));
+    if (group !== undefined) {
+        const groups = await shGit("ps -Awwo pid=,pgid=", cwd, 15_000);
+        if (groups.code !== 0)
+            return undefined;
+        for (const line of groups.stdout.split("\n")) {
+            const row = /^\s*(\d+)\s+(\d+)\s*$/.exec(line);
+            if (row && Number(row[2]) === group)
+                tree.add(row[1]);
+        }
+    }
     // ps output is not topologically ordered; relax the parent -> child closure until stable.
     for (let grew = true; grew;) {
         grew = false;
@@ -141,6 +196,7 @@ export async function workerTreeCpuMs(marker, cwd) {
 export class WorkerTreeCpuAccountant {
     marker;
     cwd;
+    group;
     active = false;
     loop;
     live = new Map();
@@ -148,12 +204,13 @@ export class WorkerTreeCpuAccountant {
     gaps = 0;
     consecutiveGaps = 0;
     latest;
-    constructor(marker, cwd) {
+    constructor(marker, cwd, group) {
         this.marker = marker;
         this.cwd = cwd;
+        this.group = group;
     }
     async sample() {
-        const snapshot = await workerTreeCpuSnapshot(this.marker, this.cwd);
+        const snapshot = await workerTreeCpuSnapshot(this.marker, this.cwd, this.group?.());
         if (snapshot === undefined) {
             this.gaps++;
             this.live.clear();

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

@@ -0,0 +1,96 @@
+import { type RunGraph } from "../../graph/schema.js";
+import type { OperatorSnapshot } from "../../run/operator-state.js";
+/** The prototype's palette (tasks-redesign.mjs:24-30): xterm-256 indices, stated once. */
+export declare const BOARD_PALETTE: {
+    readonly chrome: 238;
+    readonly mute: 243;
+    readonly body: 252;
+    readonly faint: 240;
+    readonly accent: 75;
+    readonly pass: 71;
+    readonly fail: 174;
+    readonly warn: 179;
+    readonly park: 140;
+};
+/** The seven gates, declaration order; every cell is exactly CELL columns wide. */
+export declare const BOARD_GATES: readonly ["build", "test", "lint", "evidence", "scope", "acceptance", "review"];
+export declare const BOARD_CELL = 3;
+export declare const BOARD_AREA_W = 16;
+export declare const BOARD_DEPS_W = 14;
+export declare const BOARD_NOTE_RESERVE = 28;
+export declare const BOARD_FIXED: number;
+export declare const BOARD_EFFORT_BAR_MAX = 46;
+/** The board's own key hints — only the ones the Run view handles; nothing advertised is inert. */
+export declare const BOARD_KEYS: readonly ["↑↓ move", "↵ task detail", "q quit"];
+/** Width band the Run view draws in (RULING-231-19 §2: ≥150 full · 110–149 note wraps · <110 stack). */
+export type BoardBand = "full" | "wrap" | "stacked";
+export declare const boardBand: (columns: number) => BoardBand;
+export declare const stripBoardAnsi: (s: string) => string;
+/** ANSI-aware clip at `n` visible cells (prototype `clip`), cut on a grapheme boundary so a
+ * double-cell glyph never crosses the limit and an emoji is never emitted as a lone surrogate;
+ * a clipped line closes its own colour. */
+export declare function clipBoard(s: string, n: number): string;
+export declare const BOARD_AREA_ORDER: string[];
+/** {codes, unmapped} — abstentions applied, set semantics, misses reported rather than dropped. */
+export declare function areasFor(files: readonly string[]): {
+    codes: string[];
+    unmapped: string[];
+};
+export interface BoardInput {
+    readonly runId: string;
+    readonly snapshot: OperatorSnapshot;
+    readonly graph?: Pick<RunGraph, "tasks">;
+    /** The clock the header's elapsed/ago fields read. */
+    readonly now: number;
+    /** A live daemon holds this run's lock. */
+    readonly live?: boolean;
+    /** The task the focus marker sits on; absent draws the prototype's plain indent. */
+    readonly selection?: string;
+    /** Footer key hints, joined the prototype's way; `false` leaves the footer to the caller (see boardFooter). */
+    readonly keys?: readonly string[] | false;
+    readonly colour?: boolean;
+}
+/** One task row, in the parts the Run view recomposes per width band. */
+export interface BoardRow {
+    readonly id: string;
+    /** indent (or the focus marker) + id + area + deps + title */
+    readonly head: string;
+    /** the seven gate cells */
+    readonly strip: string;
+    /** channel + attempts */
+    readonly tail: string;
+    /** `◍ parked ×n · ↻ n review rounds · ✖ gate` / `waiting on …` / `in flight`, joined by ` · ` */
+    readonly note: string;
+    /** The note's segments, so a band can wrap it across continuation rows without cutting one. */
+    readonly noteParts: readonly string[];
+}
+export interface BoardFrame {
+    /** Header through the gate header rule, in the prototype's order. */
+    readonly top: readonly string[];
+    readonly rows: readonly BoardRow[];
+    /** Header row parts, aligned to the row parts. */
+    readonly gateHeader: {
+        readonly head: string;
+        readonly strip: string;
+        readonly tail: string;
+    };
+    /** Legend, retired ids, rule, effort fold, footer. */
+    readonly bottom: readonly string[];
+    readonly width: number;
+    readonly lbl: number;
+    readonly chan: number;
+}
+/** The prototype's frame, sectioned. `renderBoard` joins it row for row. */
+export declare function boardFrame(input: BoardInput, width: number): BoardFrame;
+/** The footer row: the key hints in chrome, the prototype's leading space kept. */
+export declare const boardFooter: (keys: readonly string[], colour?: boolean) => string;
+/** The prototype's frame as lines, one row per task, unclipped — exactly what the design signed off. */
+export declare function renderBoard(input: BoardInput, width: number): string[];
+/**
+ * The Run view's three width bands over the same frame: full draws the prototype's rows; wrap
+ * puts a note that does not fit on its own second row; stacked draws the gate cells, channel and
+ * attempts under the row so nothing is truncated away.
+ */
+export declare function renderBoardLines(input: BoardInput, width: number): string[];
+/** Pack note segments greedily into rows of `avail` cells; a segment wider than a row splits at the cell. */
+export declare function wrapNote(parts: readonly string[], sep: string, firstAvail: number, avail: number): string[];