tickmarkr 1.97.0 → 2.1.0

package/README.md

@@ -13,7 +13,8 @@ tickmarkr is a spec-driven orchestration harness for AI coding agent CLIs. You w
 acceptance criteria; the engine routes tasks to the best installed agent CLI (claude-code, codex,
 cursor-agent, opencode, grok, pi, kimi) by cost and capability, dispatches work in git worktrees for
 change isolation — as interactive TUIs when running under [herdr](https://herdr.dev), headless
-subprocesses otherwise — and independently verifies each committed result by checking for no new
+subprocesses otherwise, or in [Orca](https://onorca.dev) terminals when you name that driver
+yourself — and independently verifies each committed result by checking for no new
 baseline failures per task, then strictly verifying the integration tip. Green tasks consolidate onto a
 `tickmarkr/<runId>` branch; merging to your mainline is always your call, never automated. Engage
 with full visibility into routing decisions, worker progress, and gate verdicts — or run headless
@@ -250,6 +251,23 @@ and first-attempt success rate. Cost reporting follows strict honesty rules and
 When running under [herdr](https://herdr.dev), tickmarkr creates a labeled pane-and-tab workspace
 for real-time visibility (optional — omit `--driver herdr` or run headless if preferred).
 
+### Orca: an explicit-selection execution surface
+
+[Orca](https://onorca.dev) is the third execution surface, and the only one you must ask for by
+name: `--driver orca` or `driver: orca` in config. `--driver auto` never selects it — auto picks
+herdr when a herdr session is live and subprocess otherwise — so Orca is never inherited from an
+ambient environment variable, and an Orca that is installed but unreachable is not silently
+downgraded to a hidden subprocess worker either. Naming it is the whole gate; its runtime failures
+stay Orca's, reported as failures.
+
+What Orca supplies is terminals. What tickmarkr keeps is everything that decides whether work
+ships: **it creates and owns the git worktree** for every task (Orca is told which checkout to bind
+its terminal to, and never makes one), **it runs the full gate battery** — build, test, lint,
+evidence, scope, acceptance, review — against the commits that land there, and **it holds merge
+authority**, consolidating only green tasks onto the run's `tickmarkr/<runId>` integration branch.
+Orca is given no say over any of the three. Merging that branch to your mainline remains your call,
+exactly as with every other driver.
+
 tickmarkr borrows audit-firm vocabulary for its roles: **you** are the *Partner* (final sign-off),
 workers are the *field team*, the acceptance judge is the *EQR* (engagement quality reviewer), and
 the frontier-model consult is the *National Office*. The terms below use that vocabulary:

package/dist/brand.d.ts

@@ -48,6 +48,34 @@ export declare const TOKENS: {
     readonly dim: (s: string) => string;
     readonly bold: (s: string) => string;
 };
+/** Exact operator-approved live colours. Values stay hex so the authority is inspectable. */
+export declare const LIVE_PALETTE: {
+    /** muted teal — brand identity and pass */
+    readonly brand: "#90C4A4";
+    /** cornflower blue — running state and information */
+    readonly running: "#5A76AE";
+    /** ice — primary text */
+    readonly text: "#E6FDFF";
+    /** cloud — chrome and secondary text */
+    readonly chrome: "#D9D7DD";
+    /** amethyst — attention and failure */
+    readonly attention: "#B07BAC";
+};
+export type LiveRole = keyof typeof LIVE_PALETTE;
+/** Semantic live tokens. Aliases are intentional; no token introduces a sixth colour. */
+export declare const LIVE: {
+    readonly brand: (s: string) => string;
+    readonly pass: (s: string) => string;
+    readonly running: (s: string) => string;
+    readonly information: (s: string) => string;
+    readonly text: (s: string) => string;
+    readonly primaryText: (s: string) => string;
+    readonly chrome: (s: string) => string;
+    readonly secondaryText: (s: string) => string;
+    readonly attention: (s: string) => string;
+    readonly failure: (s: string) => string;
+    readonly chip: (s: string) => string;
+};
 /**
  * The glyph vocabulary — plain characters only; color layers on via tokens so
  * shape survives NO_COLOR. Bracket toggles ([x]/[ ]) are forbidden on every surface.

package/dist/brand.js

@@ -122,6 +122,47 @@ export const dim = sgr("2");
 export const bold = sgr("1");
 /** Every semantic color token, for sweeps: each is TTY-gated and NO_COLOR-aware. */
 export const TOKENS = { brand, brandChip, ok, fail, warn, dim, bold };
+// ── operator live-surface palette (v1.99) ───────────────────────────────────
+// The tokens above remain the global design system for one-shot surfaces. LIVE is the closed
+// five-colour system for long-running operator surfaces. Semantic aliases below deliberately share
+// renderers: glyphs and words retain the distinction between pass/brand, running/information,
+// chrome/secondary text, and attention/failure when colour is unavailable.
+/** Exact operator-approved live colours. Values stay hex so the authority is inspectable. */
+export const LIVE_PALETTE = {
+    /** muted teal — brand identity and pass */
+    brand: "#90C4A4",
+    /** cornflower blue — running state and information */
+    running: "#5A76AE",
+    /** ice — primary text */
+    text: "#E6FDFF",
+    /** cloud — chrome and secondary text */
+    chrome: "#D9D7DD",
+    /** amethyst — attention and failure */
+    attention: "#B07BAC",
+};
+const liveSgr = (hex) => {
+    const channels = hex.slice(1).match(/.{2}/gu).map((channel) => Number.parseInt(channel, 16));
+    return sgr(`38;2;${channels.join(";")}`);
+};
+const liveBrand = liveSgr(LIVE_PALETTE.brand);
+const liveRunning = liveSgr(LIVE_PALETTE.running);
+const liveText = liveSgr(LIVE_PALETTE.text);
+const liveChrome = liveSgr(LIVE_PALETTE.chrome);
+const liveAttention = liveSgr(LIVE_PALETTE.attention);
+/** Semantic live tokens. Aliases are intentional; no token introduces a sixth colour. */
+export const LIVE = {
+    brand: liveBrand,
+    pass: liveBrand,
+    running: liveRunning,
+    information: liveRunning,
+    text: liveText,
+    primaryText: liveText,
+    chrome: liveChrome,
+    secondaryText: liveChrome,
+    attention: liveAttention,
+    failure: liveAttention,
+    chip: liveBrand,
+};
 /**
  * The glyph vocabulary — plain characters only; color layers on via tokens so
  * shape survives NO_COLOR. Bracket toggles ([x]/[ ]) are forbidden on every surface.

package/dist/cli/commands/compile.js

@@ -3,8 +3,28 @@ import { parseArgs } from "node:util";
 import { collateralLints, sourceScopeLints } from "../../compile/collateral.js";
 import { compileSource } from "../../compile/index.js";
 import { saveGraph, stateDirName } from "../../graph/graph.js";
+import { formatPriorFindingEvidence, readPriorRunEvidence } from "../../run/journal.js";
+import { shGit } from "../../run/git.js";
 import { acquireRunLock, releaseRunLock } from "../../run/lock.js";
 import { harnessLine, resolveHarness } from "../harness.js";
+async function mergedPendingDiagnostics(cwd, pending, merges) {
+    const head = await shGit("git rev-parse HEAD", cwd);
+    const base = head.code === 0 ? head.stdout.trim() : "";
+    if (!/^[0-9a-f]{40}$/i.test(base))
+        return [];
+    const lines = [];
+    for (const taskId of pending) {
+        const candidates = merges.filter((merge) => merge.taskId === taskId).reverse();
+        for (const merge of candidates) {
+            const ancestor = await shGit(`git merge-base --is-ancestor ${merge.commit} ${base}`, cwd);
+            if (ancestor.code !== 0)
+                continue;
+            lines.push(`${taskId}: merged in run ${merge.runId}; compiles as pending (plan not marked done) — this dispatch rebuilds it`);
+            break; // one pure-information line per pending task, newest reachable merge wins
+        }
+    }
+    return lines;
+}
 // v1.89 T4: harnessFrom is the resolver's INPUT (see plan.ts); the default is the INVOKED entrypoint
 // (`process.argv[1]`, the bin symlink), never this module's own url — that names an internal module.
 export async function compile(argv, cwd = process.cwd(), harnessFrom = process.argv[1]) {
@@ -22,6 +42,11 @@ export async function compile(argv, cwd = process.cwd(), harnessFrom = process.a
     // resolve against the target repo, not the process cwd (the CLI test passes a tmp repo)
     // Both modes reach the same pure compiler; --dry-run only removes the lock/write side effect below.
     const g = compileSource(isAbsolute(src) ? src : join(cwd, src), values.type, cwd);
+    // One bounded read supplies both cross-run surfaces: unresolved findings below and merge facts for
+    // the ancestry check. Neither fact mutates the compiled graph; status and every readiness predicate
+    // remain the source compiler's answer.
+    const prior = readPriorRunEvidence(cwd, g.tasks);
+    const mergedPending = await mergedPendingDiagnostics(cwd, new Set(g.tasks.filter((task) => task.status === "pending").map((task) => task.id)), prior.merges);
     const stateDir = stateDirName(cwd);
     if (!values["dry-run"]) {
         // HARD-01 / Sol #3: hold the same link(2) run lock as the daemon around saveGraph so compile
@@ -41,5 +66,11 @@ export async function compile(argv, cwd = process.cwd(), harnessFrom = process.a
     const diagnostics = scopeLints.length
         ? `\nscope lints:\n${scopeLints.map((lint) => `  ! ${lint}`).join("\n")}`
         : "";
-    return `${harnessLine(resolveHarness(harnessFrom))}\n${summary}${diagnostics}`;
+    const priorFindings = prior.findings.length
+        ? `\nprior-run evidence:\n${prior.findings.map((finding) => `  ${formatPriorFindingEvidence(finding)}`).join("\n")}`
+        : "";
+    const mergeHistory = mergedPending.length
+        ? `\nmerge history:\n${mergedPending.map((line) => `  ${line}`).join("\n")}`
+        : "";
+    return `${harnessLine(resolveHarness(harnessFrom))}\n${summary}${diagnostics}${priorFindings}${mergeHistory}`;
 }

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

@@ -2,6 +2,7 @@ import { type ClaudeAlias } from "../../adapters/claude-code.js";
 import type { WorkerAdapter } from "../../adapters/types.js";
 import { type KimiDoctorTurnResult } from "../../adapters/kimi.js";
 import { type CatalogReadResult } from "../../adapters/catalog-remote.js";
+import { type ShResult } from "../../run/git.js";
 /** Where a newer `table_<date>.csv` is discovered — the deployed site builds filenames by
  *  concatenation and publishes no index, so the release listing is the only enumerable surface. */
 export declare const LIVEBENCH_RELEASES_URL = "https://api.github.com/repos/LiveBench/livebench.github.io/contents/public";
@@ -15,7 +16,24 @@ export type DoctorOpts = {
     /** init's between-acts surface: status rows only — the model matrix and inline drift stay
      *  behind `tickmarkr doctor` (files are still written; only the RETURNED string shrinks). */
     compact?: boolean;
+    /** Test seam for the same `orca status --json` transport production invokes. */
+    orcaStatusProbe?: (cwd: string, binary: string) => Promise<ShResult>;
+    /** Test seam for shell-path discovery; absence remains a normal doctor row, never an exception. */
+    resolveOrcaBinary?: (cwd: string) => string | undefined;
 };
+type OrcaCapability = {
+    verdict: "pass" | "fail";
+    detail: string;
+};
+/**
+ * Orca's status body is deliberately interpreted by T1's one shared envelope parser. Doctor owns
+ * only capability presentation: it may classify an absent executable, but it never invents a second
+ * permissive JSON reader for a malformed or refused status response.
+ *
+ * Capability-row `detail` stays hermetic — never `OrcaError.message`, which embeds volatile CLI
+ * stderr (Electron timestamps), so the row is byte-stable across runs.
+ */
+export declare function probeOrcaCapability(cwd: string, opts?: Pick<DoctorOpts, "orcaStatusProbe" | "resolveOrcaBinary">): Promise<OrcaCapability>;
 export declare function runnerIgnoreFinding(cwd: string): {
     verdict: "pass" | "warn";
     detail: string;
@@ -71,3 +89,4 @@ export declare function selfShadowFinding(ownVersion: string, cwd?: string, reso
  */
 export declare function liveBenchStalenessFinding(now: Date): string | undefined;
 export declare function doctor(_argv: string[], cwd?: string, adapters?: WorkerAdapter[], opts?: DoctorOpts): Promise<string>;
+export {};

package/dist/cli/commands/doctor.js

@@ -6,14 +6,17 @@ import { detectPackageManager, turboContinueFindings } from "../../gates/baselin
 import { version } from "./version.js";
 import { allAdapters, binaryShadowWarnings, detectCandidateClis, flagDriftWarnings, modelAliasExclusions, modelAliasLine, probeAll, probeModels, resolveShellBinary, servableExclusions, servabilityLine, writeDoctor } from "../../adapters/registry.js";
 import { CLAUDE_ALIAS_IDENTITY_STAMPS, claudeCode, resolveClaudeAliasIdentity } from "../../adapters/claude-code.js";
+import { shq } from "../../adapters/types.js";
 import { BANNER, compactTokens, dim, fail, kvRow, legend, ok, rule, statusRow, title } from "../../brand.js";
 import { tickmarkrDir, stateDirName } from "../../graph/graph.js";
 import { catalogModelAdvisory, catalogTierRanking, declaredModelWindow, hasWindowsConfig, modelLints, suggestOverlay, ttyVisual } from "../../adapters/model-lints.js";
 import { loadConfig, overlayPreferShapes } from "../../config/config.js";
 import { HerdrDriver } from "../../drivers/herdr.js";
+import { parseEnvelope } from "../../drivers/orca.js";
 import { kimi, probeKimiDoctorTurn } from "../../adapters/kimi.js";
 import { denyPreferCollisionLine, denyPreferCollisions, disallowedBy, excludedChannels, exclusionLine, preferRanks } from "../../route/preference.js";
 import { LIVEBENCH_TABLE_DATE, readCachedCatalog, refreshCatalogCommand } from "../../adapters/catalog-remote.js";
+import { sh } from "../../run/git.js";
 /** Where a newer `table_<date>.csv` is discovered — the deployed site builds filenames by
  *  concatenation and publishes no index, so the release listing is the only enumerable surface. */
 export const LIVEBENCH_RELEASES_URL = "https://api.github.com/repos/LiveBench/livebench.github.io/contents/public";
@@ -21,6 +24,57 @@ export const LIVEBENCH_TABLE_MAX_AGE_DAYS = 90;
 const visual = () => process.stdout.isTTY === true && process.env.NO_COLOR === undefined;
 const alignedStatusRow = (verdict, key, value) => `  ${statusRow(verdict, kvRow(key, value).slice(2))}`;
 const attentionRow = (text) => `  ${statusRow("warn", text)}`;
+/**
+ * Orca's status body is deliberately interpreted by T1's one shared envelope parser. Doctor owns
+ * only capability presentation: it may classify an absent executable, but it never invents a second
+ * permissive JSON reader for a malformed or refused status response.
+ *
+ * Capability-row `detail` stays hermetic — never `OrcaError.message`, which embeds volatile CLI
+ * stderr (Electron timestamps), so the row is byte-stable across runs.
+ */
+export async function probeOrcaCapability(cwd, opts = {}) {
+    const binary = opts.resolveOrcaBinary ? opts.resolveOrcaBinary(cwd) : resolveShellBinary("orca", cwd).resolved;
+    if (!binary)
+        return { verdict: "fail", detail: "CLI not installed" };
+    let response;
+    try {
+        response = await (opts.orcaStatusProbe ?? ((probeCwd, executable) => sh(`${shq(executable)} status --json`, probeCwd, 10_000)))(cwd, binary);
+    }
+    catch {
+        // The seam (or the shell) never reaching a verdict is a failed probe, never an exception out of
+        // doctor: an absent or sick runtime must still render its row.
+        return { verdict: "fail", detail: "CLI installed but runtime probe failed" };
+    }
+    try {
+        // Do this before accepting the process result: Orca's documented refused transport is rc=1
+        // with an ok:false envelope on stdout, and parseEnvelope preserves that refusal fail-closed.
+        const envelope = parseEnvelope("status", response.stdout);
+        if (response.code !== 0 || response.timedOut) {
+            return {
+                verdict: "fail",
+                detail: `CLI installed but runtime probe failed — orca status exited ${response.code}${response.timedOut ? " after timeout" : ""}`,
+            };
+        }
+        const runtime = envelope.result.runtime;
+        const reachable = typeof runtime === "object" && runtime !== null && !Array.isArray(runtime)
+            ? runtime.reachable
+            : undefined;
+        if (reachable === true)
+            return { verdict: "pass", detail: `runtime reachable (${envelope.runtimeId})` };
+        if (reachable === false)
+            return { verdict: "fail", detail: "CLI installed but runtime unreachable" };
+        return { verdict: "fail", detail: "CLI installed but runtime probe failed — status carries no reachability proof" };
+    }
+    catch {
+        // Only the shared parser reads this body. Every shape it rejects — unparseable, non-object,
+        // ok:false refusal, no result, or absent/`none` `_meta.runtimeId` — is a FAILED probe, never
+        // an unreachable-runtime claim: a doctor that re-read those bytes with its own permissive
+        // reader would call malformed metadata "installed but unreachable". Unreachable is proven only
+        // by a well-formed envelope that says `reachable:false` (the shape a live orca CLI emits with
+        // its runtime down — tests/helpers/fake-orca.ts).
+        return { verdict: "fail", detail: "CLI installed but runtime probe failed" };
+    }
+}
 function detectRunner(cwd) {
     const readIf = (p) => (existsSync(join(cwd, p)) ? readFileSync(join(cwd, p), "utf8") : "");
     let pkg = {};
@@ -373,6 +427,11 @@ export async function doctor(_argv, cwd = process.cwd(), adapters = allAdapters(
     }
     if (trustNa.length)
         rows.push(`  ${dim("=")} ${dim(`n/a (${trustNa.length}): ${trustNa.join(", ")}`)}`);
+    // Orca is an explicit choice, so its health is capability information rather than an auto-routing
+    // input. A failed probe never changes pickDriver's auto ordering or substitutes subprocess.
+    const orca = await probeOrcaCapability(cwd, opts);
+    rows.push(legend("execution runtime:"));
+    rows.push(alignedStatusRow(orca.verdict, "orca", orca.detail));
     for (const [role, sel] of [["judge", cfg.judge], ["consult", cfg.consult]]) {
         if (!health[sel.adapter]?.installed) {
             rows.push(attentionRow(`${role} runs on ${sel.adapter}:${sel.model} — NOT installed; that gate will fail closed until you install it or remap cfg.${role}`));

package/dist/cli/commands/init.js

@@ -12,11 +12,14 @@ import { Journal } from "../../run/journal.js";
 import { doctor } from "./doctor.js";
 import { assembleFleetEditor } from "./fleet.js";
 const SCAFFOLD_SPEC = "tickmarkr.spec.md";
-// Operator-approved (2026-07-17) environments footer — three rows; no npm install for herdr
-// (npm package "herdr" is a reserved 0.0.0 placeholder as of that date).
+// Operator-approved (2026-07-17) environments footer — no npm install for herdr (npm package
+// "herdr" is a reserved 0.0.0 placeholder as of that date). The orca row joins it with the v2.1
+// driver: it is a THIRD execution surface an operator selects outright — `auto` still resolves
+// herdr-else-subprocess and never picks it, so the footer names it beside the other two choices.
 const ENVIRONMENTS_FOOTER = [
     "environments:",
     "  herdr — the full cockpit — every worker, judge, and consult is a visible pane you can watch and unblock · https://herdr.dev",
+    "  orca — visible terminals in the Orca app — an explicit driver choice: set driver: orca (auto never picks it) · https://onorca.dev",
     "  claude code — tickmarkr init --agent installs the /tkr skills + AGENTS.md so Claude Code (or any agent CLI) drives the loop natively",
     "  anywhere — no herdr? same fail-closed gates, headless subprocess driver",
 ].join("\n");

package/dist/cli/commands/resume.js

@@ -1,20 +1,31 @@
+import { parseArgs } from "node:util";
 import { loadConfig } from "../../config/config.js";
-import { pickDriver } from "../../drivers/index.js";
+import { parseDriverOverride, pickDriver } from "../../drivers/index.js";
 import { loadGraph } from "../../graph/graph.js";
 import { formatSummary, runDaemon } from "../../run/daemon.js";
-import { formatJournalNarration } from "../../run/journal.js";
 import { denyPreferCollisionLine, denyPreferCollisions } from "../../route/preference.js";
+import { narrationSink, bindNarration } from "./run.js";
 const summaryGreen = (s) => s.failed.length === 0 && s.human.length === 0 && s.blocked.length === 0 && s.pending.length === 0
     && s.tipVerify !== "failed";
 export async function resume(argv, cwd = process.cwd()) {
-    const runId = argv[0];
+    const { values, positionals } = parseArgs({
+        args: argv,
+        options: {
+            "graph-changed": { type: "boolean" },
+            "retry-failed": { type: "boolean" },
+            driver: { type: "string" },
+        },
+        allowPositionals: true,
+    });
+    const runId = positionals[0];
     if (!runId)
-        throw new Error("usage: tickmarkr resume <run-id> [--graph-changed] [--retry-failed]");
+        throw new Error("usage: tickmarkr resume <run-id> [--graph-changed] [--retry-failed] [--driver <auto|herdr|subprocess|orca>]");
+    const driverOverride = parseDriverOverride(values.driver);
     // T3: --graph-changed is the operator's audited release of the engagement-identity guard (Sol #2 /
     // Fable F2) — the daemon refuses a mismatched/unbound journal unless this is set, then journals a
     // graph-rehash event naming both hashes. Strip the flag before runId resolution so a bare id still wins.
-    const graphChanged = argv.includes("--graph-changed");
-    const retryFailed = argv.includes("--retry-failed");
+    const graphChanged = values["graph-changed"] ?? false;
+    const retryFailed = values["retry-failed"] ?? false;
     const cfg = loadConfig(cwd);
     // v1.87 T3 (OBS-162, twice-carried workaround): the preflight runs AFTER the graph is read and
     // sees only the shapes the resumed graph carries. A deny∩prefer collision on a shape no resumed
@@ -25,13 +36,19 @@ export async function resume(argv, cwd = process.cwd()) {
     if (collisions.length) {
         throw new Error(collisions.map(denyPreferCollisionLine).join("; "));
     }
+    const narrate = narrationSink(runId);
     const s = await runDaemon(cwd, {
         runId,
         resume: true,
         graphChanged,
         retryFailed,
-        driver: pickDriver(cfg),
-        narrate: (event) => console.log(formatJournalNarration(event)),
+        // bound to the same sink the daemon gets, so a driver-journaled recovery reaches this rail too
+        driver: bindNarration(pickDriver(cfg, driverOverride), narrate),
+        // v1.99 T2: the ONE narration sink — the quiet rail on a TTY, the raw journal formatter on a
+        // pipe. A resumed run meets the same surface a fresh one does; printing the raw formatter here
+        // would leave `resume` as the last place the old unfiltered dump survives. Bound to the run id
+        // the operator named, so a resumed run's lifecycle rows name THIS run and not a generic word.
+        narrate,
     });
     const out = `resumed ${s.runId} — ${formatSummary(s)}`;
     return { out, code: summaryGreen(s) ? 0 : 2 };

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

@@ -1,6 +1,66 @@
+import type { ExecutorDriver } from "../../drivers/types.js";
 import { type JournalEvent } from "../../run/journal.js";
-export declare const narrationLine: (event: JournalEvent) => string;
+/** Closed repetitive set the rail suppresses on a TTY. An ungated `phase-start` joins them below —
+ *  it is a phase counter, while a phase-start CARRYING a gate is the gate start the rail draws. */
+export declare const TTY_NOISE_EVENTS: readonly ["worker-contact", "worker-status"];
+type RailTone = "pass" | "fail" | "attention" | "active" | "neutral";
+/** Closed retained set: the short operator label and the row's default tone. Labels are the rail's
+ *  own vocabulary — a raw journal event name is what this surface exists to stop printing. A `pass`
+ *  or `ok` datum on the event overrides the default tone, so one gate row can read either way.
+ *
+ *  MEMBERSHIP RULE — the daemon journals far more than this, and an allowlist built from whatever
+ *  the tests happened to cover masks real events. An event earns a row when it changes what the run
+ *  will DO next or reports an OUTCOME of it: a routing decision, a worker result, a gate start or
+ *  verdict, a repair, an escalation, a merge, a run lifecycle step. Everything else — how the daemon
+ *  got there (worktree setup, launch mechanics, baseline and routing lints) and every poll-time
+ *  observation (contact reads, quota banners, held dead-verdicts, context samples) — stays off the
+ *  rail and on the pipe, where it is byte-identical to the raw journal.
+ *
+ *  Applying that rule is what put `graph-rehash` and the worker-nudge family here: a rehash is the
+ *  operator's audited `--graph-changed` release, journaled by the resumed run through THIS sink, and
+ *  a nudge is a decision the daemon takes on the operator's behalf (it contacts the worker and arms a
+ *  grace deadline that force-concludes the wait), whose answered/failed/expired rows are that
+ *  decision's outcome. Neither is mechanics, and both reach this process's narrate callback. */
+export declare const RAIL_ROWS: Record<string, {
+    label: string;
+    tone: RailTone;
+}>;
+/**
+ * One rail row, or null when the TTY rail suppresses this event. Never wider than `columns`: the
+ * identity and the label are clipped SEPARATELY and the detail takes only what they leave, so a row
+ * can never wrap into a second line and can never lose its meaning to a long identity.
+ */
+export declare function narrationRow(event: JournalEvent, runId: string, columns?: number): string | null;
+/** The narration line for one event of the run named by `runId`: the raw journal formatter on a pipe
+ *  (byte-identical, every event), the quiet rail on a TTY. Null means the rail suppressed it — the
+ *  caller prints nothing. */
+export declare const narrationLine: (event: JournalEvent, runId: string) => string | null;
+/**
+ * The daemon's narration sink, BOUND TO THE RUN IT NARRATES: the rail on a TTY, the raw journal
+ * formatter on a pipe, and nothing at all for an event the rail suppressed. EVERY command that drives
+ * a daemon owes its narration to this sink - a second call site that prints `formatJournalNarration`
+ * itself is a surface where the rail does not exist, and the operator meets the old unfiltered dump
+ * under the newly stacked board.
+ *
+ * The binding is what puts a real identity on the run-scoped rows: the daemon's `narrate` callback is
+ * handed one event and nothing else, and the lifecycle events carry no run id of their own, so the
+ * run id can only come from the command that owns the run. Both daemon-driving commands supply it:
+ * `run` below mints the id it then passes to the daemon, and `resume` (src/cli/commands/resume.ts)
+ * carries the id the operator named.
+ */
+export declare const narrationSink: (runId: string) => (event: JournalEvent) => void;
+/**
+ * The run's driver, BOUND to the run's narration sink.
+ *
+ * A driver journals events of its own that the daemon never sees: `dispatch-retry` is appended by
+ * HerdrDriver from inside a pane recovery, through a Journal it opens itself (src/drivers/herdr.ts).
+ * Unbound, that event lands in the file and on the pipe while the rail — the operator's only live
+ * surface — stays silent about a redispatch that already happened. Both daemon-driving commands
+ * wrap their driver here so neither can forget the binding.
+ */
+export declare function bindNarration<D extends ExecutorDriver>(driver: D, narrate: (event: JournalEvent) => void): D;
 export declare function run(argv: string[], cwd?: string): Promise<{
     out: string;
     code: number;
 }>;
+export {};