tickmarkr 1.48.2 → 1.50.0

package/README.md

@@ -11,7 +11,7 @@
 
 tickmarkr is a spec-driven orchestration harness for AI coding agent CLIs. You write a spec with
 acceptance criteria; the engine routes tasks to the best installed agent CLI (claude-code, codex,
-cursor-agent, opencode, grok, pi) by cost and capability, dispatches work in git worktrees for
+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
 baseline failures per task, then strictly verifying the integration tip. Green tasks consolidate onto a
@@ -51,8 +51,8 @@ prefer, every example below works with either.
 - **macOS or Linux.** Every command shells out through `bash`, so native Windows is not
   supported — use WSL (untested).
 - Node ≥ 20 and `git` on PATH.
-- At least one agent CLI on PATH (`claude`, `codex`, `cursor-agent`, `opencode`, `grok`, or
-  `pi`), authenticated through its own login. tickmarkr never handles vendor API keys itself.
+- At least one agent CLI on PATH (`claude`, `codex`, `cursor-agent`, `opencode`, `grok`, `pi`,
+  or `kimi`), authenticated through its own login. tickmarkr never handles vendor API keys itself.
 
 Then verify your fleet:
 
@@ -63,7 +63,11 @@ tickmarkr doctor   # probes installed adapters, herdr, auth; prints the capabili
 **Expect `doctor` (and `init`, which runs it) to take a while on first run:** auth detection is
 one real, short LLM call per configured model per installed CLI — honest, but not instant. A
 machine with three CLIs and several models each can take a minute or more; each probe is capped
-at 30s.
+at 60s.
+
+`doctor` also sweeps a catalog of known agent CLIs that have no adapter yet and prints an
+advisory `detected — no adapter; not routable` row for any found on PATH — a freshly installed
+harness is visible the day it lands, and never routed until an adapter ships for it.
 
 ## Quickstart (5 minutes)
 
@@ -113,6 +117,7 @@ tickmarkr resume <runId>       # continue an engagement from the local execution
 tickmarkr approve <runId> <taskId>   # approve a parked task (--reason to document)
 tickmarkr report <runId>       # cost/quality report
 tickmarkr profile              # show the learned routing profile
+tickmarkr profile --explain <shape> <channel>  # why a channel ranks where it does for a shape
 ```
 
 Green tasks land on `tickmarkr/<runId>`; merge to your mainline is always your call.
@@ -136,6 +141,41 @@ away from a failing adapter will never retry it in subsequent `tickmarkr resume`
 - The task has burned its full attempt budget without reaching a conclusive result
 - Approving grants a fresh attempt budget, routing around all previously-failed channels and adapters
 
+## Choosing your fleet: `tickmarkr fleet`
+
+`tickmarkr doctor` is a pure sensor; `tickmarkr fleet` is the actuator. It walks four screens —
+fleet overview, membership (allow/deny), model tiers, and per-shape routing — and ends in a
+unified diff of your config overlay that is written **only on explicit confirm**. Pressing Enter
+through every screen writes nothing. Assigning a tier to a model that has no classification yet
+requires a typed benchmark-provenance note, stored as a config comment beside the assignment.
+
+```bash
+tickmarkr fleet          # interactive editor (requires a TTY)
+tickmarkr fleet --print  # effective fleet state (repo > global > defaults), non-interactive — good for CI drift checks
+```
+
+Routing obeys a strict precedence — **pin > prefer > floors > marginal-cost auto**:
+
+- **pin** a shape to an exact channel: `map: { plan: { via: claude-code, model: fable } }`
+- **prefer**-rank adapters per shape: `map: { implement: { prefer: [cursor-agent, codex] } }`
+- **floors** set the minimum capability band per shape (`migration: frontier`, `tests: cheap`);
+  auto-routing then picks the cheapest authed channel at or above the floor
+- **deny/allow** bench models or whole adapters without touching tiers (see `deny.models` below)
+- **tiers** classify models into bands — only classified, doctor-authed models ever route
+
+More levers, all optional and absent-safe (absent config keeps default behavior):
+
+- `routing.explore` — fence the exploration budget: `mode: off`, `excludeShapes`,
+  `excludeComplexityAtOrAbove`, and a per-channel `cap`; `run --no-explore` disables
+  exploration probes for a single run
+- `tiers.<adapter>.windows` — declare context-window sizes per model; doctor grows a window
+  column and `plan` warns (advisory, never blocking) when a task's payload estimate exceeds
+  the routed model's window
+- `routing.sla` — per-shape latency expectations, surfaced as advisory plan lints against the
+  learned performance profile
+- `run --quality` — raise every capability floor one band for that run (it never lowers one),
+  disable exploration, and record the original and raised floor in routing provenance
+
 ## Model scoping and auth detection
 
 Each agent CLI exposes a list of available models. tickmarkr's routing works only with **classified** models — those you explicitly enter into the config under `tiers`. The `tickmarkr doctor` command probes these models to detect auth status and records the results, which routing consumes to avoid 401/403 dispatch failures.

package/dist/brand.d.ts

@@ -1,9 +1,71 @@
+import type { OwnedName } from "./drivers/types.js";
 export declare const BANNER: string;
 /** ANSI-stripped, trailing-space-trimmed twin of BANNER — README hero and other plain surfaces. */
 export declare const PLAIN_BANNER: string;
+export declare const PANE_IDENTITY_ENV = "TICKMARKR_PANE_IDENTITY";
+/** One-line pane identity through the T1 ownership contract: role · task · attempt · run. */
+export declare function paneIdentityLine(o: OwnedName): string;
 export declare function bannerShell(): string;
 export declare const TICKMARKR_EXIT_TRAILER = "printf '\\nTICKMARKR_''EXIT:%s\\n' $?";
 /** OBS-50: visible-pane bootstrap script — banner + agent command + byte-identical exit trailer. */
 export declare function paneDispatchScript(body: string[]): string;
 /** OBS-50: one short herdr pane-run line; bootstrap lives in the script file beside the prompt. */
 export declare function paneDispatchCommand(scriptPath: string): string;
+/** The settled brand green ramp (256-color), bright → deep — the BANNER hues. */
+export declare const BRAND_RAMP: readonly [84, 78, 41, 35];
+/** Brand green (ramp anchor 41) — the tickmark hue; also the ok/pass/authed verdict color. */
+export declare const brand: (s: string) => string;
+/** Ok verdicts (pass/authed/green) render in the brand green ramp — same hue as the tickmark. */
+export declare const ok: (s: string) => string;
+/** Fail verdicts (unauthed/red) — red, always paired with the ✗ shape. */
+export declare const fail: (s: string) => string;
+/** Attention (warn/lint) — amber, always paired with the ! shape. */
+export declare const warn: (s: string) => string;
+/** Chrome (legends, rules, parentheticals, inactive state) — dim. */
+export declare const dim: (s: string) => string;
+/** Emphasis (titles, selection, the product name) — bold. */
+export declare const bold: (s: string) => string;
+/** Every semantic color token, for sweeps: each is TTY-gated and NO_COLOR-aware. */
+export declare const TOKENS: {
+    readonly brand: (s: string) => string;
+    readonly ok: (s: string) => string;
+    readonly fail: (s: string) => string;
+    readonly warn: (s: string) => string;
+    readonly dim: (s: string) => string;
+    readonly bold: (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.
+ */
+export declare const GLYPHS: {
+    /** Cursor row pointer in list pickers. */
+    readonly pointer: "❯";
+    /** Active toggle: THE brand tickmark — always rendered via brand(), never brackets. */
+    readonly toggleActive: "✓";
+    /** Inactive toggle: dim circle — always rendered via dim(). */
+    readonly toggleInactive: "○";
+    /** Pass verdict. */
+    readonly pass: "✓";
+    /** Fail verdict. */
+    readonly fail: "✗";
+    /** Attention/warn verdict. */
+    readonly attention: "!";
+    /** Neutral/skip — the dash. */
+    readonly neutral: "-";
+};
+/** The active toggle as rendered: brand green tickmark on a TTY, plain ✓ otherwise. */
+export declare const toggleActive: () => string;
+/** The inactive toggle as rendered: dim circle on a TTY, plain ○ otherwise. */
+export declare const toggleInactive: () => string;
+/** Dominant title line — one glance answers "what am I looking at". Bold on a TTY. */
+export declare const title: (text: string) => string;
+/** Single dim legend line under a title (key hints) — never scattered, never a paragraph. */
+export declare const legend: (text: string) => string;
+/** Horizontal rule sized to the terminal (capped at 100 cols) — dim chrome. */
+export declare const rule: (width?: number) => string;
+/** Aligned key-value row: dim key, plain value. Padding applied BEFORE styling so columns hold. */
+export declare const kvRow: (key: string, value: string, keyWidth?: number) => string;
+export type Verdict = "pass" | "fail" | "warn" | "neutral";
+/** Status row: verdict glyph FIRST, then the label — glyph-first, distinct shape per verdict. */
+export declare const statusRow: (verdict: Verdict, label: string) => string;

package/dist/brand.js

@@ -12,11 +12,21 @@ export const BANNER = [
 ].join("\n");
 /** ANSI-stripped, trailing-space-trimmed twin of BANNER — README hero and other plain surfaces. */
 export const PLAIN_BANNER = BANNER.replace(/\x1b\[[0-9;]*m/g, "").replace(/[ \t]+$/gm, "");
-// Shell one-liner that prints the banner inside a pane before a gate command runs. ESC bytes are
+// T5: the pane identity every visible pane announces under the logo. HerdrDriver seeds this env var
+// into each pane shell at slot() time (paneIdentityLine of the pane's T1 owned name); the banner's
+// identity line reads it at pane runtime, so every role — worker/judge/review/consult — wears the
+// same header without the dispatch call sites threading identity through the script.
+export const PANE_IDENTITY_ENV = "TICKMARKR_PANE_IDENTITY";
+/** One-line pane identity through the T1 ownership contract: role · task · attempt · run. */
+export function paneIdentityLine(o) {
+    return `${o.role} · ${o.taskId} · attempt ${o.attempt}${o.runId ? ` · ${o.runId}` : ""}`;
+}
+// Shell one-liner that prints the banner inside a pane before a gate command runs, followed by ONE
+// dim identity line (the seeded $TICKMARKR_PANE_IDENTITY, else a bare "tickmarkr"). ESC bytes are
 // carried as printf %b escapes (never raw control bytes in a command string crossing the herdr socket).
 export function bannerShell() {
     const printable = BANNER.replaceAll("\x1b", "\\033").replaceAll("\n", "\\n");
-    return `printf '%b\\n' '${printable}'`;
+    return `printf '%b\\n' '${printable}' "\\033[2m\${${PANE_IDENTITY_ENV}:-tickmarkr}\\033[0m"`;
 }
 // OBS-50: quote-split exit marker — herdr echoes the typed command into the transcript that
 // waitOutput matches, so the literal must not appear unsplit in the dispatch line.
@@ -29,3 +39,65 @@ export function paneDispatchScript(body) {
 export function paneDispatchCommand(scriptPath) {
     return `bash ${shq(scriptPath)}`;
 }
+// ── design system (v1.50) ── contract: docs/codebase/CLI-DESIGN.md ──────────
+// Every cockpit surface styles through these tokens/glyphs/helpers. Styled only
+// on a real TTY with NO_COLOR unset; otherwise output is the plain text itself
+// (non-TTY surfaces stay byte-pinned and machine-consumable).
+/** The settled brand green ramp (256-color), bright → deep — the BANNER hues. */
+export const BRAND_RAMP = [84, 78, 41, 35];
+const visual = () => process.stdout.isTTY === true && process.env.NO_COLOR === undefined;
+const sgr = (code) => (s) => visual() ? `\x1b[${code}m${s}${R}` : s;
+/** Brand green (ramp anchor 41) — the tickmark hue; also the ok/pass/authed verdict color. */
+export const brand = sgr(`38;5;${BRAND_RAMP[2]}`);
+/** Ok verdicts (pass/authed/green) render in the brand green ramp — same hue as the tickmark. */
+export const ok = brand;
+/** Fail verdicts (unauthed/red) — red, always paired with the ✗ shape. */
+export const fail = sgr("31");
+/** Attention (warn/lint) — amber, always paired with the ! shape. */
+export const warn = sgr("33");
+/** Chrome (legends, rules, parentheticals, inactive state) — dim. */
+export const dim = sgr("2");
+/** Emphasis (titles, selection, the product name) — bold. */
+export const bold = sgr("1");
+/** Every semantic color token, for sweeps: each is TTY-gated and NO_COLOR-aware. */
+export const TOKENS = { brand, ok, fail, warn, dim, bold };
+/**
+ * The glyph vocabulary — plain characters only; color layers on via tokens so
+ * shape survives NO_COLOR. Bracket toggles ([x]/[ ]) are forbidden on every surface.
+ */
+export const GLYPHS = {
+    /** Cursor row pointer in list pickers. */
+    pointer: "❯",
+    /** Active toggle: THE brand tickmark — always rendered via brand(), never brackets. */
+    toggleActive: "✓",
+    /** Inactive toggle: dim circle — always rendered via dim(). */
+    toggleInactive: "○",
+    /** Pass verdict. */
+    pass: "✓",
+    /** Fail verdict. */
+    fail: "✗",
+    /** Attention/warn verdict. */
+    attention: "!",
+    /** Neutral/skip — the dash. */
+    neutral: "-",
+};
+/** The active toggle as rendered: brand green tickmark on a TTY, plain ✓ otherwise. */
+export const toggleActive = () => brand(GLYPHS.toggleActive);
+/** The inactive toggle as rendered: dim circle on a TTY, plain ○ otherwise. */
+export const toggleInactive = () => dim(GLYPHS.toggleInactive);
+/** Dominant title line — one glance answers "what am I looking at". Bold on a TTY. */
+export const title = (text) => bold(text);
+/** Single dim legend line under a title (key hints) — never scattered, never a paragraph. */
+export const legend = (text) => dim(text);
+/** Horizontal rule sized to the terminal (capped at 100 cols) — dim chrome. */
+export const rule = (width = Math.min(process.stdout.columns ?? 80, 100)) => dim("─".repeat(width));
+/** Aligned key-value row: dim key, plain value. Padding applied BEFORE styling so columns hold. */
+export const kvRow = (key, value, keyWidth = 14) => `  ${dim(key.padEnd(keyWidth))} ${value}`;
+const VERDICT = {
+    pass: () => ok(GLYPHS.pass),
+    fail: () => fail(GLYPHS.fail),
+    warn: () => warn(GLYPHS.attention),
+    neutral: () => dim(GLYPHS.neutral),
+};
+/** Status row: verdict glyph FIRST, then the label — glyph-first, distinct shape per verdict. */
+export const statusRow = (verdict, label) => `${VERDICT[verdict]()} ${label}`;

package/dist/cli/commands/doctor.js

@@ -1,36 +1,15 @@
 import { writeFileSync } from "node:fs";
 import { join } from "node:path";
-import { allAdapters, detectCandidateClis, formatCandidateCliRow, probeAll, probeModels, readAutoPrefer, servableExclusions, servabilityLine, writeDoctor } from "../../adapters/registry.js";
-import { BANNER } from "../../brand.js";
+import { allAdapters, detectCandidateClis, probeAll, probeModels, readAutoPrefer, servableExclusions, servabilityLine, writeDoctor } from "../../adapters/registry.js";
+import { BANNER, dim, fail, kvRow, legend, ok, rule, statusRow, title } from "../../brand.js";
 import { tickmarkrDir, stateDirName } from "../../graph/graph.js";
 import { declaredModelWindow, hasWindowsConfig, modelLints, suggestOverlay, ttyVisual } from "../../adapters/model-lints.js";
 import { DEFAULT_CONFIG, loadConfig, overlayPreferShapes } from "../../config/config.js";
 import { HerdrDriver } from "../../drivers/herdr.js";
 import { disallowedBy, excludedChannels, exclusionLine, preferRanks } from "../../route/preference.js";
-// same gate + palette as status's audit-ledger frame: styled only on a real TTY, plain otherwise
 const visual = () => process.stdout.isTTY === true && process.env.NO_COLOR === undefined;
-const color = (text, code) => `\x1b[${code}m${text}\x1b[0m`;
-// TTY-only line pass: color the verdict symbols, dim the chrome (section titles, parentheticals,
-// n/a rows). Padding is untouched — every rewrite swaps equal-width text or wraps it in ANSI.
-function stylize(out) {
-    if (!visual())
-        return out;
-    const rule = color("─".repeat(Math.min(process.stdout.columns ?? 80, 100)), 2);
-    return out.split("\n").map((line) => {
-        if (line.startsWith("tickmarkr doctor"))
-            return ` ${color("✓", 32)} ${color("tickmarkr", 1)} doctor ${color("· capability matrix", 2)}\n${rule}`;
-        if (/^(workspace trust|model status|model drift)/.test(line))
-            return color(line, 2);
-        return line
-            .replace(/^(\s+)✓ /, (_, s) => `${s}${color("✓", 32)} `)
-            .replace(/^(\s+)✗ /, (_, s) => `${s}${color("✗", 31)} `)
-            .replace(/^(\s+)! /, (_, s) => `${s}${color("!", 33)} `)
-            .replace(/^(\s+)= (.*)$/, (_, s, rest) => `${s}${color(`= ${rest}`, 2)}`)
-            .replace(/(\(auth assumed; verified at dispatch \(failover on auth\/quota errors\)\))/, (m) => color(m, 2))
-            .replace(/\bauthed\b(?!:)/, color("authed", 32))
-            .replace(/\bunauthed:/, color("unauthed:", 33));
-    }).join("\n");
-}
+const alignedStatusRow = (verdict, key, value) => `  ${statusRow(verdict, kvRow(key, value).slice(2))}`;
+const attentionRow = (text) => `  ${statusRow("warn", text)}`;
 export async function doctor(_argv, cwd = process.cwd(), adapters = allAdapters(), opts = {}) {
     const cfg = loadConfig(cwd);
     // banner at START — the logo greets the operator before the ~60s probe wait, never trailing it (operator report 2026-07-17)
@@ -63,48 +42,49 @@ export async function doctor(_argv, cwd = process.cwd(), adapters = allAdapters(
     const rows = adapters.map((a) => {
         const h = health[a.id];
         const state = !h.installed ? "not installed" : `${h.version ?? "installed"}${h.note ? ` (${h.note})` : ""}`;
-        return `  ${h.installed ? "✓" : "✗"} ${a.id.padEnd(14)} ${state}`;
+        return alignedStatusRow(h.installed ? "pass" : "fail", a.id, state);
     });
     // v1.48 T1: advisory sweep for known agent CLIs with no adapter — never written to doctor.json health.
-    rows.push(...detectCandidateClis().map(formatCandidateCliRow));
-    rows.push(`  ${HerdrDriver.available() ? "✓" : "✗"} herdr          ${HerdrDriver.available() ? "driver available (HERDR_ENV=1)" : "not detected — subprocess driver will be used"}`);
+    rows.push(...detectCandidateClis().map(({ binary, version }) => alignedStatusRow("warn", binary, `detected: ${version ?? "version unknown"} (no tickmarkr adapter — not routable)`)));
+    const herdr = HerdrDriver.available();
+    rows.push(alignedStatusRow(herdr ? "pass" : "fail", "herdr", herdr ? "driver available (HERDR_ENV=1)" : "not detected — subprocess driver will be used"));
     // v1.22 T5: workspace-trust pre-flight — per installed adapter: trusted | seeded | action-required | n/a.
     // action-required names the exact one-time command (or dialog) the operator must run once.
-    rows.push("workspace trust:");
+    rows.push(legend("workspace trust:"));
     for (const a of adapters) {
         if (!health[a.id]?.installed)
             continue;
         if (!a.trust) {
-            rows.push(`  = ${a.id.padEnd(14)} trust: n/a`);
+            rows.push(`  ${dim("=")} ${kvRow(a.id, "trust: n/a").slice(2)}`);
             continue;
         }
         try {
             const v = a.trust(cwd);
             if (v.status === "trusted")
-                rows.push(`  ✓ ${a.id.padEnd(14)} trust: trusted`);
+                rows.push(alignedStatusRow("pass", a.id, "trust: trusted"));
             else if (v.status === "seeded")
-                rows.push(`  ✓ ${a.id.padEnd(14)} trust: seeded`);
+                rows.push(alignedStatusRow("pass", a.id, "trust: seeded"));
             else
-                rows.push(`  ! ${a.id.padEnd(14)} trust: action-required — run ONCE: ${v.command}`);
+                rows.push(alignedStatusRow("warn", a.id, `trust: action-required — run ONCE: ${v.command}`));
         }
         catch (e) {
             // fail closed on the trust line only — never abort the rest of doctor
-            rows.push(`  ! ${a.id.padEnd(14)} trust: action-required — run ONCE: (trust check failed: ${e instanceof Error ? e.message : String(e)})`);
+            rows.push(alignedStatusRow("warn", a.id, `trust: action-required — run ONCE: (trust check failed: ${e instanceof Error ? e.message : String(e)})`));
         }
     }
     for (const [role, sel] of [["judge", cfg.judge], ["consult", cfg.consult]]) {
         if (!health[sel.adapter]?.installed) {
-            rows.push(`  ! ${role} runs on ${sel.adapter}:${sel.model} — NOT installed; that gate will fail closed until you install it or remap cfg.${role}`);
+            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}`));
         }
     }
-    rows.push(...modelLints(cfg, health, adapters, { tty: ttyVisual(), stateDir: stateDirName(cwd), overlayPreferShapes: overlayPreferShapes(cwd) }).map((l) => `  ! ${l}`));
+    rows.push(...modelLints(cfg, health, adapters, { tty: ttyVisual(), stateDir: stateDirName(cwd), overlayPreferShapes: overlayPreferShapes(cwd) }).map(attentionRow));
     const excluded = excludedChannels(cfg, adapters, health);
     if (excluded.length)
-        rows.push(`  ! ${exclusionLine(excluded)}`);
+        rows.push(attentionRow(exclusionLine(excluded)));
     // HYG-07(a): doctor just probed fresh (probeAll above), so servability attribution is current by construction.
     const servable = servableExclusions(cfg, adapters, health);
     if (servable.length)
-        rows.push(`  ! ${servabilityLine(servable)}`);
+        rows.push(attentionRow(servabilityLine(servable)));
     // MODEL-05/06: print-only drift fragment; advisory, whole-line-commented additions, tickmarkr NEVER applies it.
     // TTY gets a one-line summary + the fragment as a file (the full dump drowned everything else,
     // v1.33.1 onboarding); machine/CI surface keeps the inline dump — layout is pinned by tests.
@@ -114,7 +94,7 @@ export async function doctor(_argv, cwd = process.cwd(), adapters = allAdapters(
         if (visual()) {
             const overlayPath = join(tickmarkrDir(cwd), "doctor-overlay.yaml");
             writeFileSync(overlayPath, frag);
-            drift = `\nmodel drift: unclassified models detected — paste-ready overlay written to ${overlayPath} (advisory; tickmarkr never applies it)`;
+            drift = `\n  ${statusRow("warn", `model drift: unclassified models detected — paste-ready overlay written to ${overlayPath} ${dim("(advisory; tickmarkr never applies it)")}`)}`;
         }
         else {
             drift = `\nmodel drift — paste-ready overlay (advisory; tickmarkr never applies):\n${frag}`;
@@ -137,20 +117,24 @@ export async function doctor(_argv, cwd = process.cwd(), adapters = allAdapters(
         if (!models.length && !unclassified.length)
             return [];
         const w = Math.max(8, ...models.map((m) => m.length));
-        const rows = [`  ${a.id}`];
+        const rows = [`  ${dim(a.id)}`];
         for (const m of models) {
             const v = h.modelAuth?.[m];
-            const auth = !v ? "unknown" : v.authed ? "authed" : `unauthed: ${trunc(v.reason ?? "probe failed", 40)} (${dateOf(v.probedAt)})`;
+            const auth = !v
+                ? dim("unknown")
+                : v.authed
+                    ? ok("authed")
+                    : `${fail("unauthed:")} ${trunc(v.reason ?? "probe failed", 40)} (${dateOf(v.probedAt)})`;
             const d = disallowedBy({ adapter: a.id, model: m }, cfg.routing);
             const denied = d?.by === "deny" ? d.entry : "—";
             const pref = preferRanks({ adapter: a.id, model: m }, cfg).map((p) => `${p.shape}#${p.rank}`).join(",") || "—";
             const windowCol = showWindows
                 ? ` ${String(declaredModelWindow(cfg, a.id, m) ?? "—").padEnd(8)}`
                 : "";
-            rows.push(`    ${m.padEnd(w)} ${classified[m].padEnd(8)}${windowCol} ${auth}  denied=${denied}  prefer=${pref}`);
+            rows.push(`    ${m.padEnd(w)} ${classified[m].padEnd(8)}${windowCol} ${auth}  ${dim("denied=")}${denied}  ${dim("prefer=")}${pref}`);
         }
         if (unclassified.length)
-            rows.push(`    (${unclassified.length} more listed, unclassified)`);
+            rows.push(`    ${dim(`(${unclassified.length} more listed, unclassified)`)}`);
         return rows;
     });
     const autoPrefer = readAutoPrefer(cwd);
@@ -162,11 +146,14 @@ export async function doctor(_argv, cwd = process.cwd(), adapters = allAdapters(
             const seed = DEFAULT_CONFIG.routing.map[shape]?.prefer ?? [];
             if (!auto.length && !seed.length)
                 return []; // nothing derived, nothing seeded — an empty line is noise
-            return [`    prefer ${shape} (auto): ${auto.join(" > ")} — seed was [${seed.join(", ")}]`];
+            return [`    ${dim(`prefer ${shape} (auto):`)} ${auto.join(" > ")} ${dim("— seed was")} [${seed.join(", ")}]`];
         })
         : [];
     const modelSummary = modelStatus.length || preferStatus.length
-        ? `\nmodel status:\n${[...modelStatus, ...preferStatus].join("\n")}`
+        ? `\n${legend("model status:")}\n${[...modelStatus, ...preferStatus].join("\n")}`
         : "";
-    return stylize(`tickmarkr doctor — capability matrix:\n${rows.join("\n")}${modelSummary}${drift}\nwrote ${stateDirName(cwd)}/doctor.json`);
+    const header = visual()
+        ? `${statusRow("pass", `${title("tickmarkr doctor")} ${legend("· capability matrix")}`)}\n${rule()}`
+        : "tickmarkr doctor — capability matrix:";
+    return `${header}\n${rows.join("\n")}${modelSummary}${drift}\nwrote ${stateDirName(cwd)}/doctor.json`;
 }

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

@@ -1,5 +1,19 @@
 import type { WorkerAdapter } from "../../adapters/types.js";
-export declare function fleet(argv: string[], cwd?: string, adapters?: WorkerAdapter[]): Promise<string | {
+export type FleetInput = NodeJS.ReadableStream & {
+    isTTY?: boolean;
+    setRawMode?: (mode: boolean) => unknown;
+    pause: () => unknown;
+    resume: () => unknown;
+};
+export type FleetOutput = {
+    isTTY?: boolean;
+    write: (chunk: string) => unknown;
+};
+export type FleetIO = {
+    input?: FleetInput;
+    output?: FleetOutput;
+};
+export declare function fleet(argv: string[], cwd?: string, adapters?: WorkerAdapter[], io?: FleetIO): Promise<string | {
     out: string;
     code: number;
 }>;

package/dist/cli/commands/fleet.js

@@ -1,14 +1,17 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname } from "node:path";
+import { emitKeypressEvents } from "node:readline";
 import { createInterface } from "node:readline/promises";
 import { parseArgs } from "node:util";
 import { allAdapters, discoverChannels, doctorAgeMs, initDoctorReuse, readAutoPrefer } from "../../adapters/registry.js";
 import { fleetUnclassifiedModels } from "../../adapters/model-lints.js";
+import { GLYPHS, bold, legend as legendText, toggleActive, toggleInactive } from "../../brand.js";
 import { fleetEditableFromConfig, fleetEditableEquals, fleetRepoOverlayFromDelta, formatFleetPrint, globalConfigDir, loadConfig, overlayPreferShapes, readOverlayFile, repoOverlayPath, repoOverlayYaml, unifiedYamlDiff, } from "../../config/config.js";
 import { SHAPES, TIERS } from "../../graph/schema.js";
 import { route } from "../../route/router.js";
 import { loadRoutingProfile } from "../../run/journal.js";
 const NON_TTY_MSG = "tickmarkr fleet: interactive fleet editor requires a TTY — use `tickmarkr fleet --print` for non-interactive output";
+const QUIT = "fleet: quit without writing";
 const isDeniedAdapter = (id, editable) => editable.denyAdapters.includes(id);
 const isDeniedModel = (adapter, model, editable) => editable.denyModels.includes(`${adapter}:${model}`);
 function previewTask(shape) {
@@ -56,10 +59,88 @@ function proposedOverlayText(initial, editable, repoRoot) {
     const merged = fleetRepoOverlayFromDelta(initial, editable, readOverlayFile(repoOverlayPath(repoRoot)));
     return repoOverlayYaml(merged, provenanceMap(editable));
 }
-async function ask(rl, prompt) {
-    return (await rl.question(prompt)).trim();
+const isAbort = (k) => k.name === "escape" || k.name === "q" || (k.ctrl === true && k.name === "c");
+const isNext = (k) => k.name === "return" || k.name === "enter";
+const isToggle = (k) => k.name === "space";
+function moveCursor(k, cursor, count) {
+    if (count === 0)
+        return cursor;
+    if (k.name === "down" || k.name === "j")
+        return Math.min(cursor + 1, count - 1);
+    if (k.name === "up" || k.name === "k")
+        return Math.max(cursor - 1, 0);
+    return cursor;
 }
-export async function fleet(argv, cwd = process.cwd(), adapters = allAdapters()) {
+// step title (bold) + one dim key legend + rows; exactly one pointer glyph on the cursor row
+function listFrame(title, legend, rows, cursor) {
+    const lines = [bold(title), legendText(legend)];
+    rows.forEach((r, i) => lines.push(i === cursor ? `${GLYPHS.pointer} ${bold(r)}` : `  ${r}`));
+    return lines;
+}
+// Keypress terminal over the (injectable) input stream. Keypress events are decoded by
+// node's own emitKeypressEvents ON THE STREAM — no readline interface is held in keypress
+// mode, so the production path and the test seam are the same decoder (OBS-69).
+function openTerm(input, output) {
+    emitKeypressEvents(input);
+    const queue = [];
+    let pending = null;
+    const onKeypress = (str, key) => {
+        const k = key && (key.name !== undefined || key.sequence !== undefined) ? key : { name: str, sequence: str };
+        if (pending) {
+            const fn = pending;
+            pending = null;
+            fn(k);
+        }
+        else
+            queue.push(k);
+    };
+    const setRaw = (on) => void input.setRawMode?.(on);
+    input.on("keypress", onKeypress);
+    setRaw(true);
+    input.resume();
+    let prevLines = 0;
+    return {
+        key() {
+            const buffered = queue.shift();
+            if (buffered)
+                return Promise.resolve(buffered);
+            return new Promise((resolve) => {
+                pending = resolve;
+            });
+        },
+        frame(lines) {
+            const erase = prevLines > 0 ? `\x1b[${prevLines}F\x1b[0J` : "";
+            output.write(`${erase}${lines.join("\n")}\n`);
+            prevLines = lines.length;
+        },
+        // typed entry leaves keypress mode: raw off, transient line interface, closed after the
+        // question; keys the line editor leaked into the decoder are dropped (type-ahead kept)
+        async askTyped(prompt) {
+            const typedFrom = queue.length;
+            setRaw(false);
+            const rl = createInterface({
+                input: input,
+                output: output,
+            });
+            try {
+                return (await rl.question(prompt)).trim();
+            }
+            finally {
+                rl.close();
+                setRaw(true);
+                queue.splice(typedFrom);
+                prevLines = 0;
+            }
+        },
+        // every exit path: raw mode off, zero keypress listeners, stream paused (OBS-70)
+        close() {
+            input.off("keypress", onKeypress);
+            setRaw(false);
+            input.pause();
+        },
+    };
+}
+export async function fleet(argv, cwd = process.cwd(), adapters = allAdapters(), io = {}) {
     const { values } = parseArgs({
         args: argv,
         options: {
@@ -70,7 +151,9 @@ export async function fleet(argv, cwd = process.cwd(), adapters = allAdapters())
     });
     const globalDir = values["global-dir"] ?? globalConfigDir();
     const print = values.print ?? false;
-    const interactive = process.stdin.isTTY === true && process.stdout.isTTY === true;
+    const input = io.input ?? process.stdin;
+    const output = io.output ?? process.stdout;
+    const interactive = input.isTTY === true && output.isTTY === true;
     if (print)
         return formatFleetPrint(cwd, { globalDir });
     if (!interactive)
@@ -87,153 +170,194 @@ export async function fleet(argv, cwd = process.cwd(), adapters = allAdapters())
     const initial = fleetEditableFromConfig(cfg);
     const editable = structuredClone(initial);
     const health = cached;
-    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    const term = openTerm(input, output);
     try {
-        // screen 0 — sensor freshness
+        // step 1/4 — probe data
         const ageLine = formatAge(doctorAgeMs(cwd));
-        let step = await ask(rl, `tickmarkr fleet — scope your fleet\n  probe data: ${ageLine} (.tickmarkr/doctor.json)\n  [Enter] use it   [r] refresh via doctor   [q] quit\n> `);
-        if (/^q$/i.test(step))
-            return "fleet: quit without writing";
-        if (/^r$/i.test(step)) {
-            return "fleet: run `tickmarkr doctor` to refresh probe data, then re-run `tickmarkr fleet` (doctor is the sensor; fleet never re-probes)";
+        term.frame(listFrame("step 1/4 · probe data", "enter continue · r refresh via doctor · esc/q quit", [`probe data: ${ageLine} (.tickmarkr/doctor.json)`], 0));
+        for (;;) {
+            const k = await term.key();
+            if (isAbort(k))
+                return QUIT;
+            if (k.name === "r") {
+                return "fleet: run `tickmarkr doctor` to refresh probe data, then re-run `tickmarkr fleet` (doctor is the sensor; fleet never re-probes)";
+            }
+            if (isNext(k))
+                break;
         }
-        // screen 1 — adapter membership (deny adapters)
+        // step 2/4 — agent CLIs (space toggles adapter deny)
         const installed = adapters.filter((a) => health[a.id]?.installed);
-        const adapterLines = installed.map((a, i) => {
+        const adapterRows = () => installed.map((a) => {
             const h = health[a.id];
             const on = !isDeniedAdapter(a.id, editable);
-            const mark = on ? "x" : " ";
-            const auth = h?.authed ? "authed" : "unauthed";
-            return `  ${i + 1}. [${mark}] ${a.id}  ${h?.version ?? "installed"}  ${auth}`;
+            return `${on ? toggleActive() : toggleInactive()} ${a.id}  ${h?.version ?? "installed"}  ${h?.authed ? "authed" : "unauthed"}`;
         });
-        step = await ask(rl, `screen 1/4 — agent CLIs  [number]=toggle  [Enter]=next\n${adapterLines.join("\n")}\n> `);
-        if (/^q$/i.test(step))
-            return "fleet: quit without writing";
-        if (step && step !== "") {
-            const n = Number.parseInt(step, 10);
-            if (Number.isInteger(n) && n >= 1 && n <= installed.length) {
-                const id = installed[n - 1].id;
+        const listLegend = "↑↓/jk move · space toggle · enter next · esc/q quit";
+        let aCursor = 0;
+        term.frame(listFrame("step 2/4 · agent CLIs", listLegend, adapterRows(), aCursor));
+        for (;;) {
+            const k = await term.key();
+            if (isAbort(k))
+                return QUIT;
+            if (isNext(k))
+                break;
+            let changed = false;
+            const moved = moveCursor(k, aCursor, installed.length);
+            if (moved !== aCursor) {
+                aCursor = moved;
+                changed = true;
+            }
+            else if (isToggle(k) && installed.length > 0) {
+                const id = installed[aCursor].id;
                 const idx = editable.denyAdapters.indexOf(id);
                 if (idx === -1)
                     editable.denyAdapters.push(id);
                 else
                     editable.denyAdapters.splice(idx, 1);
                 editable.denyAdapters.sort();
+                changed = true;
             }
+            if (changed)
+                term.frame(listFrame("step 2/4 · agent CLIs", listLegend, adapterRows(), aCursor));
         }
-        // screen 2 — models per enabled adapter
+        // step 3/4 — models per enabled adapter (space toggles deny, t assigns tier from the row)
         const enabledAdapters = installed.filter((a) => !isDeniedAdapter(a.id, editable));
         for (const a of enabledAdapters) {
-            const classified = editable.tiers[a.id] ?? {};
-            const models = Object.keys(classified);
-            const unclassified = fleetUnclassifiedModels(cfg, health, adapters).filter((u) => u.adapter === a.id);
-            const rows = [];
-            let row = 1;
-            const indexFor = new Map();
-            for (const m of models) {
-                const tier = classified[m];
-                const denied = isDeniedModel(a.id, m, editable) ? "deny" : "allow";
-                const mark = denied === "deny" ? " " : "x";
-                rows.push(`  ${row}. [${mark}] ${m}  ${tier?.tier ?? "???"}  ${denied === "deny" ? "denied" : "allowed"}`);
-                indexFor.set(String(row), { kind: "classified", model: m });
-                row++;
-            }
-            for (const u of unclassified) {
-                rows.push(`  ${row}. ( ) ${u.model}  ???  unclassified${u.detectedAt ? ` (${u.detectedAt})` : ""}`);
-                indexFor.set(String(row), { kind: "unclassified", model: u.model });
-                row++;
-            }
-            step = await ask(rl, `screen 2/4 — models · ${a.id}  [number]=toggle deny  [t <n> <tier>]=assign tier  [Enter]=next\n${rows.join("\n")}\n> `);
-            if (/^q$/i.test(step))
-                return "fleet: quit without writing";
-            if (step.startsWith("t ")) {
-                const [, numRaw, tierRaw] = step.split(/\s+/);
-                const tier = tierRaw;
-                if (!indexFor.has(numRaw) || !TIERS.includes(tier)) {
-                    return { out: "fleet: tier assignment requires a valid model number and tier (cheap|mid|frontier)", code: 1 };
+            const unclassifiedAll = fleetUnclassifiedModels(cfg, health, adapters).filter((u) => u.adapter === a.id);
+            const rowsData = () => [
+                ...Object.keys(editable.tiers[a.id] ?? {}).map((m) => ({ kind: "classified", model: m })),
+                ...unclassifiedAll
+                    .filter((u) => !editable.tiers[a.id]?.[u.model])
+                    .map((u) => ({ kind: "unclassified", model: u.model, detectedAt: u.detectedAt })),
+            ];
+            const renderRows = (rows) => rows.map((r) => {
+                if (r.kind === "unclassified") {
+                    return `( ) ${r.model}  ???  unclassified${r.detectedAt ? ` (${r.detectedAt})` : ""}`;
                 }
-                const target = indexFor.get(numRaw);
-                if (target.kind !== "unclassified") {
-                    return { out: "fleet: tier reassignment on classified models is not supported in v1 — edit config directly", code: 1 };
+                const tier = editable.tiers[a.id]?.[r.model];
+                const denied = isDeniedModel(a.id, r.model, editable);
+                return `${denied ? toggleInactive() : toggleActive()} ${r.model}  ${tier?.tier ?? "???"}  ${denied ? "denied" : "allowed"}`;
+            });
+            const title = `step 3/4 · models · ${a.id}`;
+            const modelsLegend = "↑↓/jk move · space toggle · t tier · enter next · esc/q quit";
+            let mCursor = 0;
+            term.frame(listFrame(title, modelsLegend, renderRows(rowsData()), mCursor));
+            for (;;) {
+                const k = await term.key();
+                if (isAbort(k))
+                    return QUIT;
+                if (isNext(k))
+                    break;
+                const rows = rowsData();
+                let changed = false;
+                const moved = moveCursor(k, mCursor, rows.length);
+                if (moved !== mCursor) {
+                    mCursor = moved;
+                    changed = true;
                 }
-                const note = await ask(rl, "benchmark provenance note (required): ");
-                if (!note.trim())
-                    return { out: "fleet: assigning a tier to an unclassified model requires a typed benchmark-provenance note", code: 1 };
-                editable.tiers[a.id] ??= {};
-                editable.tiers[a.id][target.model] = { tier, provenance: note.trim() };
-            }
-            else if (step && /^\d+$/.test(step)) {
-                const target = indexFor.get(step);
-                if (target?.kind === "classified") {
-                    const key = `${a.id}:${target.model}`;
+                else if (isToggle(k) && rows[mCursor]?.kind === "classified") {
+                    const key = `${a.id}:${rows[mCursor].model}`;
                     const idx = editable.denyModels.indexOf(key);
                     if (idx === -1)
                         editable.denyModels.push(key);
                     else
                         editable.denyModels.splice(idx, 1);
                     editable.denyModels.sort();
+                    changed = true;
                 }
+                else if (k.name === "t" && rows[mCursor]) {
+                    if (rows[mCursor].kind === "classified") {
+                        return { out: "fleet: tier reassignment on classified models is not supported in v1 — edit config directly", code: 1 };
+                    }
+                    const tier = (await term.askTyped(`tier (${TIERS.join("|")})> `));
+                    if (!TIERS.includes(tier))
+                        return { out: `fleet: invalid tier ${tier}`, code: 1 };
+                    const note = await term.askTyped("benchmark provenance note (required): ");
+                    if (!note)
+                        return { out: "fleet: assigning a tier to an unclassified model requires a typed benchmark-provenance note", code: 1 };
+                    editable.tiers[a.id] ??= {};
+                    editable.tiers[a.id][rows[mCursor].model] = { tier, provenance: note };
+                    changed = true;
+                }
+                if (changed)
+                    term.frame(listFrame(title, modelsLegend, renderRows(rowsData()), mCursor));
             }
         }
-        // screen 3 — per-shape routing
+        // step 4/4 — shape routing (typed entry for pin/tier/prefer from the highlighted row)
         const channels = discoverChannels(cfg, adapters, health);
         const profile = loadRoutingProfile(cwd, cfg, { preview: true });
         const autoPrefer = readAutoPrefer(cwd);
         const overlayShapes = overlayPreferShapes(cwd, { globalDir });
-        for (let si = 0; si < SHAPES.length; si++) {
-            const shape = SHAPES[si];
-            const entry = editable.map[shape] ?? {};
-            let now = "";
+        const shapeRows = () => SHAPES.map((shape) => {
+            let now;
             try {
                 const r = route(previewTask(shape), { ...cfg, routing: { ...cfg.routing, map: editable.map, floors: editable.floors } }, channels, profile);
-                now = `${r.provenance}\n       → ${r.assignment.adapter}:${r.assignment.model} (${r.assignment.channel}, ${r.assignment.tier})`;
+                now = `${r.assignment.adapter}:${r.assignment.model} (${r.assignment.channel}, ${r.assignment.tier})`;
             }
             catch (e) {
                 now = e.message;
             }
-            const autoNote = autoPrefer?.[shape] && !overlayShapes.has(shape)
-                ? `\n  auto-prefer active — explicit prefer overrides it`
-                : "";
-            step = await ask(rl, `screen 3/4 — shape routing · ${shape} (${si + 1}/${SHAPES.length})\n  now: ${now}\n  [1] auto within tier  [2] pin channel  [3] edit tier  [4] edit prefer  [Enter]=keep${autoNote}\n> `);
-            if (/^q$/i.test(step))
-                return "fleet: quit without writing";
-            if (!step)
-                continue;
-            if (step === "1") {
+            const auto = autoPrefer?.[shape] && !overlayShapes.has(shape) ? "  (auto-prefer active)" : "";
+            return `${shape}  →  ${now}${auto}`;
+        });
+        const shapesTitle = "step 4/4 · shape routing";
+        const shapesLegend = "↑↓/jk move · a auto · p pin · t tier · f prefer · enter next · esc/q quit";
+        let sCursor = 0;
+        term.frame(listFrame(shapesTitle, shapesLegend, shapeRows(), sCursor));
+        for (;;) {
+            const k = await term.key();
+            if (isAbort(k))
+                return QUIT;
+            if (isNext(k))
+                break;
+            const shape = SHAPES[sCursor];
+            const entry = editable.map[shape] ?? {};
+            let changed = false;
+            const moved = moveCursor(k, sCursor, SHAPES.length);
+            if (moved !== sCursor) {
+                sCursor = moved;
+                changed = true;
+            }
+            else if (k.name === "a") {
                 const next = { ...entry };
                 delete next.pin;
                 editable.map[shape] = next;
+                changed = true;
             }
-            else if (step === "2") {
-                const pin = await ask(rl, "pin adapter:model> ");
+            else if (k.name === "p") {
+                const pin = await term.askTyped("pin adapter:model> ");
                 const i = pin.indexOf(":");
                 if (i < 1)
                     return { out: "fleet: pin must be adapter:model", code: 1 };
                 editable.map[shape] = { pin: { via: pin.slice(0, i), model: pin.slice(i + 1) } };
+                changed = true;
             }
-            else if (step === "3") {
-                const tier = await ask(rl, `tier (${TIERS.join("|")})> `);
+            else if (k.name === "t") {
+                const tier = (await term.askTyped(`tier (${TIERS.join("|")})> `));
                 if (!TIERS.includes(tier))
                     return { out: `fleet: invalid tier ${tier}`, code: 1 };
                 const next = { ...entry, tier };
                 delete next.pin;
                 editable.map[shape] = next;
+                changed = true;
             }
-            else if (step === "4") {
-                const pref = await ask(rl, "prefer (comma-separated adapters or adapter:model)> ");
-                const prefer = pref.split(",").map((s) => s.trim()).filter(Boolean);
-                editable.map[shape] = { ...entry, prefer };
+            else if (k.name === "f") {
+                const pref = await term.askTyped("prefer (comma-separated adapters or adapter:model)> ");
+                editable.map[shape] = { ...entry, prefer: pref.split(",").map((s) => s.trim()).filter(Boolean) };
+                changed = true;
             }
+            if (changed)
+                term.frame(listFrame(shapesTitle, shapesLegend, shapeRows(), sCursor));
         }
-        // review — unified diff + confirm
+        // review — unified diff + typed confirm
         const before = currentRepoOverlayText(cwd);
         const after = proposedOverlayText(initial, editable, cwd);
         if (fleetEditableEquals(initial, editable) || before === after) {
             return "fleet: no overlay changes (empty diff)";
         }
         const diff = unifiedYamlDiff(before, after, repoOverlayPath(cwd));
-        process.stdout.write(`\n${diff}\n`);
-        const confirm = await ask(rl, "write overlay? [y/N] ");
+        output.write(`\n${diff}\n`);
+        const confirm = await term.askTyped("write overlay? [y/N] ");
         if (!/^y(?:es)?$/i.test(confirm))
             return "fleet: discarded overlay changes";
         const merged = fleetRepoOverlayFromDelta(initial, editable, readOverlayFile(repoOverlayPath(cwd)));
@@ -244,6 +368,6 @@ export async function fleet(argv, cwd = process.cwd(), adapters = allAdapters())
         return `fleet: wrote ${path}`;
     }
     finally {
-        rl.close();
+        term.close();
     }
 }

package/dist/cli/commands/init.js

@@ -5,7 +5,7 @@ import { parseArgs } from "node:util";
 import { allAdapters, formatDoctorAgeForInit, formatDoctorReport, initDoctorReuse } from "../../adapters/registry.js";
 import { configTemplate, DEFAULT_CONFIG, globalConfigDir, loadConfig } from "../../config/config.js";
 import { LEGACY_PREFIX, specTemplate } from "../../compile/native.js";
-import { BANNER } from "../../brand.js";
+import { BANNER, kvRow, legend, rule, statusRow, title } from "../../brand.js";
 import { tickmarkrDir } from "../../graph/graph.js";
 import { Journal } from "../../run/journal.js";
 import { doctor } from "./doctor.js";
@@ -264,5 +264,25 @@ export async function init(argv, cwd = process.cwd()) {
     }
     if (values.agent)
         await installAgentFiles(cwd, values.force ?? false, values.docs ?? false, notes);
-    return `${notes.join("\n")}\n${doc}\n${nextSteps(cwd, SCAFFOLD_SPEC)}\n${ENVIRONMENTS_FOOTER}`;
+    const next = nextSteps(cwd, SCAFFOLD_SPEC);
+    if (!visual())
+        return `${notes.join("\n")}\n${doc}\n${next}\n${ENVIRONMENTS_FOOTER}`;
+    const noteRows = notes.map((note) => `  ${statusRow(/^(?:wrote|overwrote|appended)/.test(note) ? "pass" : note.startsWith("skipped") ? "warn" : "neutral", note)}`);
+    const footerRows = ENVIRONMENTS_FOOTER.split("\n").slice(1).map((line) => {
+        const separator = line.indexOf(" — ");
+        return kvRow(line.slice(2, separator), line.slice(separator + 1), 12);
+    });
+    return [
+        title("tickmarkr init"),
+        legend("· setup notes"),
+        rule(),
+        ...noteRows,
+        doc,
+        title("next steps"),
+        legend("· continue from the repository's current state"),
+        rule(),
+        kvRow("next", next.replace(/^next:\s*/, "")),
+        legend("environments:"),
+        ...footerRows,
+    ].join("\n");
 }

package/dist/cli/commands/plan.js

@@ -1,5 +1,6 @@
 import { allAdapters, discoverChannels, doctorAgeMs, modelAuthExclusions, probeAll, readDoctor, servableExclusions, servabilityLine } from "../../adapters/registry.js";
 import { formatModelAuthLine, contextWindowLints, modelLints, ttyVisual } from "../../adapters/model-lints.js";
+import { GLYPHS, dim, rule, title, warn } from "../../brand.js";
 import { collateralLints } from "../../compile/collateral.js";
 import { loadConfig } from "../../config/config.js";
 import { loadGraph } from "../../graph/graph.js";
@@ -7,6 +8,22 @@ import { excludedChannels, exclusionLine } from "../../route/preference.js";
 import { route, RoutingError } from "../../route/router.js";
 import { modelId } from "../../gates/review.js";
 import { loadRoutingProfile } from "../../run/journal.js";
+// T4 (v1.50): TTY-only brand pass — the title helper frames the routing table, lint/unroutable
+// markers carry the attention glyph, section labels dim to chrome (the doctor/status system).
+// Gated on ttyVisual(): the non-TTY surface returns untouched (byte-pinned, machine-consumable).
+const stylizePlan = (out) => {
+    if (!ttyVisual())
+        return out;
+    return out.split("\n").map((line, i) => {
+        if (i === 0)
+            return `${title(line)}\n${rule()}`;
+        if (/^(routing|context window|scope) lints:$/.test(line))
+            return dim(line);
+        return line
+            .replace(/^(\s+)! /, (_, s) => `${s}${warn(GLYPHS.attention)} `)
+            .replace(/^(  \S+\s+\S+\s+)!! /, (_, p) => `${p}${warn("!!")} `);
+    }).join("\n");
+};
 const fleetCanCrossVendorReview = (channels) => {
     for (let i = 0; i < channels.length; i++)
         for (let j = 0; j < channels.length; j++)
@@ -114,5 +131,5 @@ export async function plan(_argv, cwd = process.cwd(), adapters = allAdapters())
     const scopeLints = collateralLints(g.tasks, cwd);
     if (scopeLints.length)
         lines.push("", "scope lints:", ...scopeLints.map((l) => `  ! ${l}`));
-    return lines.join("\n");
+    return stylizePlan(lines.join("\n"));
 }

package/dist/cli/commands/report.js

@@ -1,5 +1,7 @@
 import { parseArgs } from "node:util";
+import { ttyVisual } from "../../adapters/model-lints.js";
 import { addUsage } from "../../adapters/types.js";
+import { dim, rule, title } from "../../brand.js";
 import { loadConfig } from "../../config/config.js";
 import { estimateCosts } from "../../report/cost.js";
 import { cellsOf, cellSummary } from "../../route/profile.js";
@@ -287,6 +289,16 @@ function textReport(runId, events, rows, cwd) {
         `  probes this run (route-deviation explore): ${probes}`,
     ].join("\n");
 }
+// T4 (v1.50): TTY-only brand pass over the text report — title frame + dim section chrome; row
+// text and alignment untouched (the doctor/status system). Gated on ttyVisual(): the non-TTY
+// surface returns untouched, and --md never styles (the record is a document surface).
+const stylizeReport = (out) => {
+    if (!ttyVisual())
+        return out;
+    return out
+        .replace(/^.*$/m, (first) => `${title(first)}\n${rule()}`) // non-global /m ⇒ first line only
+        .replace(/^(engagement summary — audit trail:|spend — tokens[^\n]*|spend — money:|learning \([^\n]*)$/gm, (l) => dim(l));
+};
 export async function report(argv, cwd = process.cwd()) {
     const { values, positionals } = parseArgs({
         args: argv,
@@ -302,5 +314,5 @@ export async function report(argv, cwd = process.cwd()) {
         const rows = j.readTelemetry();
         return renderMarkdownRecord(runId, events, estimateCosts(rows, loadConfig(cwd).cost), rows);
     }
-    return textReport(runId, events, j.readTelemetry(), cwd);
+    return stylizeReport(textReport(runId, events, j.readTelemetry(), cwd));
 }

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

@@ -1,3 +1,5 @@
+import { type JournalEvent } from "../../run/journal.js";
+export declare const narrationLine: (event: JournalEvent) => string;
 export declare function run(argv: string[], cwd?: string): Promise<{
     out: string;
     code: number;

package/dist/cli/commands/run.js

@@ -6,6 +6,22 @@ import { loadGraph } from "../../graph/graph.js";
 import { formatSummary, runDaemon } from "../../run/daemon.js";
 import { route, QUALITY_ENV, NO_EXPLORE_ENV } from "../../route/router.js";
 import { formatJournalNarration, loadRoutingProfile } from "../../run/journal.js";
+import { ttyVisual } from "../../adapters/model-lints.js";
+import { statusRow } from "../../brand.js";
+// T4 (v1.50): lifecycle verdict glyphs on the live narration stream — glyph-first, message text
+// unchanged (the doctor/status visual system). TTY-gated: the piped narration surface stays
+// byte-identical to formatJournalNarration.
+const NARRATION_VERDICTS = {
+    "task-dispatch": "neutral",
+    "task-done": "pass",
+    "task-failed": "fail",
+    "task-human": "warn",
+};
+export const narrationLine = (event) => {
+    const line = formatJournalNarration(event);
+    const verdict = NARRATION_VERDICTS[event.event];
+    return verdict !== undefined && ttyVisual() ? statusRow(verdict, line) : line;
+};
 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 run(argv, cwd = process.cwd()) {
@@ -46,7 +62,7 @@ export async function run(argv, cwd = process.cwd()) {
         const s = await runDaemon(cwd, {
             concurrency: values.concurrency ? Number(values.concurrency) : undefined,
             driver: pickDriver(cfg, values.driver),
-            narrate: (event) => console.log(formatJournalNarration(event)),
+            narrate: (event) => console.log(narrationLine(event)),
         });
         const out = `run ${s.runId} finished — ${formatSummary(s)} (merge to main is a human decision)`;
         return { out, code: summaryGreen(s) ? 0 : 2 };

package/dist/cli/commands/status.js

@@ -1,4 +1,4 @@
-import { BANNER } from "../../brand.js";
+import { BANNER, GLYPHS, dim, fail, legend, ok, rule, statusRow, title, warn } from "../../brand.js";
 import { blockedTasks, graphDefinitionHash, loadGraph, pendingTasks } from "../../graph/graph.js";
 import { GATE_NAMES } from "../../graph/schema.js";
 import { Journal, engagementComparable } from "../../run/journal.js";
@@ -19,17 +19,8 @@ const attemptStartIdx = (events, taskId) => {
     return idx;
 };
 const visual = () => process.stdout.isTTY === true && process.env.NO_COLOR === undefined;
-const color = (text, code, enabled) => enabled ? `\x1b[${code}m${text}\x1b[0m` : text;
-const taskBox = (status, unicode) => {
-    if (unicode) {
-        if (status === "done")
-            return "✓";
-        if (status === "failed")
-            return "✗";
-        if (status === "human")
-            return "⏸";
-        return "☐";
-    }
+// non-TTY machine surface only — the TTY frame draws task verdicts via statusRow
+const taskBox = (status) => {
     if (status === "done")
         return "[x]";
     if (status === "failed" || status === "human")
@@ -37,8 +28,10 @@ const taskBox = (status, unicode) => {
     return "[ ]";
 };
 const gateBox = (state, unicode) => {
-    if (unicode)
-        return state === "pass" ? "✓" : state === "fail" ? "✗" : state === "skip" ? "·" : "☐";
+    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");
@@ -59,9 +52,12 @@ const gateStates = (task, events) => {
     }
     return GATE_NAMES.map((gate) => task.gates.includes(gate) ? outcomes.get(gate) ?? "open" : "skip");
 };
-// verdict semantics only: pass green, fail red, skip/open dim chrome — everything else stays quiet
-const GATE_STATE_COLOR = { pass: 32, fail: 31, skip: 2, open: 2 };
-const gateChain = (states, unicode) => GATE_NAMES.map((gate, i) => color(`${GATE_KEYS[gate]}${gateBox(states[i], unicode)}`, GATE_STATE_COLOR[states[i]], unicode)).join(" ");
+// verdict semantics only: pass brand green, fail red, skip/open dim chrome — everything else stays quiet
+const GATE_STATE_TOKEN = { pass: ok, fail, skip: dim, open: dim };
+const gateChain = (states, unicode) => GATE_NAMES.map((gate, i) => {
+    const chip = `${GATE_KEYS[gate]}${gateBox(states[i], unicode)}`;
+    return unicode ? GATE_STATE_TOKEN[states[i]](chip) : chip;
+}).join(" ");
 // plain (uncolored) chip width for column math — ANSI codes have zero display width
 const gateChainWidth = (unicode) => GATE_NAMES.reduce((w, gate) => w + GATE_KEYS[gate].length + (unicode ? 1 : 3) + 1, -1);
 const shortGoal = (goal, max) => {
@@ -159,61 +155,62 @@ const renderFrame = (cwd) => {
         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 statusColor = (st) => st === "done" ? 32 : st === "failed" ? 31 : st === "human" ? 33 : 36;
     if (!unicode) {
         // machine/CI surface — layout unchanged (pipes, greps, and the golden pins depend on it)
         const rows = cells.map(({ t, st, label, assignCol, states }) => {
             const chain = gateChain(states, false);
-            const prefix = `  ${taskBox(st, false)} ${t.id} `;
+            const prefix = `  ${taskBox(st)} ${t.id} `;
             const suffix = `  ${chain}  ${String(st)}${label}  ${assignCol}`;
             return `${prefix}${shortGoal(t.goal, Math.max(0, width - prefix.length - suffix.length))}${suffix}`;
         });
         const header = runId
             ? `tickmarkr status${divider}run ${runId}${!comparable ? `${divider}${NOT_COMPARABLE_NOTICE}` : ""}${divider}${liveness(events).replaceAll(" · ", divider)}${divider}${done}/${g.tasks.length} done`
             : `tickmarkr status${divider}no runs yet${divider}${done}/${g.tasks.length} done`;
-        const legend = `  gates: ${GATE_NAMES.map((gate) => `${GATE_KEYS[gate]} ${gate}`).join(divider)}`;
-        return [header, legend, ...rows].join("\n");
+        const legendLine = `  gates: ${GATE_NAMES.map((gate) => `${GATE_KEYS[gate]} ${gate}`).join(divider)}`;
+        return [header, legendLine, ...rows].join("\n");
     }
-    // TTY: audit-ledger frame — bold brand mark, dim chrome, semantic color only on verdicts,
-    // completion gauge, and column-aligned rows (pad plain text FIRST, colorize after: ANSI has
-    // zero display width and would corrupt padEnd math)
-    const dim = (s) => color(s, 2, true);
+    // TTY: cockpit frame composed through src/brand.ts (CLI-DESIGN.md) — dominant run title,
+    // dim chrome, semantic color only on verdicts, completion gauge, and column-aligned status
+    // rows (pad plain text FIRST, colorize after: ANSI has zero display width and would corrupt
+    // padEnd math)
     const dot = dim(" · ");
     const anyFailed = cells.some((c) => c.st === "failed");
     const gaugeCells = 10;
     const fill = g.tasks.length ? Math.round((done / g.tasks.length) * gaugeCells) : 0;
-    const gauge = (fill ? color("█".repeat(fill), anyFailed ? 31 : 32, true) : "") + (fill < gaugeCells ? dim("░".repeat(gaugeCells - fill)) : "");
+    const gauge = (fill ? (anyFailed ? fail : ok)("█".repeat(fill)) : "") + (fill < gaugeCells ? dim("░".repeat(gaugeCells - fill)) : "");
     const live = liveness(events)
-        .replace(/\bdead\b/, color("dead", 31, true))
-        .replace(/\bfinished\b/, color("finished", 2, true))
-        .replace(/\balive\b/, color("alive", 32, true))
+        .replace(/\bdead\b/, fail("dead"))
+        .replace(/\bfinished\b/, dim("finished"))
+        .replace(/\balive\b/, ok("alive"))
         .replaceAll(" · ", dot);
     const tally = `${done}/${g.tasks.length} done`;
-    const header = ` ${color("✓", 32, true)} ${color("tickmarkr", 1, true)}${dot}` +
+    const header = ` ${title(runId ? `run ${runId}` : "tickmarkr")}${dot}` +
         (runId
-            ? `run ${runId}${dot}${!comparable ? `${NOT_COMPARABLE_NOTICE}${dot}` : ""}${live}${dot}`
+            ? `${!comparable ? `${warn(NOT_COMPARABLE_NOTICE)}${dot}` : ""}${live}${dot}`
             : `no runs yet${dot}`) +
-        `${gauge} ${done === g.tasks.length && g.tasks.length > 0 ? color(tally, 32, true) : tally}`;
-    const rule = dim("─".repeat(Math.min(width, 100)));
-    const legend = dim(`   gates: ${GATE_NAMES.map((gate) => `${GATE_KEYS[gate]} ${gate}`).join(" · ")}`);
+        `${gauge} ${done === g.tasks.length && g.tasks.length > 0 ? ok(tally) : tally}`;
+    const hr = rule(Math.min(width, 100));
+    const gatesLegend = legend(`   gates: ${GATE_NAMES.map((gate) => `${GATE_KEYS[gate]} ${gate}`).join(" · ")}`);
+    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).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 box = color(taskBox(st, true), st === "done" ? 32 : st === "failed" ? 31 : st === "human" ? 33 : 2, true);
         const goal = shortGoal(t.goal, goalW).padEnd(goalW);
-        const statusCell = color(String(st), statusColor(st), true) +
-            (label ? (label === " starved" ? color(label, 31, true) : dim(label)) : "") +
+        const stWord = st === "done" ? ok(String(st)) : st === "failed" ? fail(String(st)) : st === "human" ? warn(String(st)) : String(st);
+        const statusCell = stWord +
+            (label ? (label === " starved" ? fail(label) : dim(label)) : "") +
             " ".repeat(stW - (String(st) + label).length);
-        return `  ${box} ${t.id.padEnd(idW)} ${goal}  ${gateChain(states, true)}  ${statusCell}  ${dim(assignCol)}`;
+        return `  ${statusRow(taskVerdict(st), `${t.id.padEnd(idW)} ${goal}  ${gateChain(states, true)}  ${statusCell}  ${dim(assignCol)}`)}`;
     });
-    return [header, rule, legend, ...rows].join("\n");
+    return [header, hr, gatesLegend, ...rows].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
     if (!argv.includes("--watch"))
-        return renderFrame(cwd);
+        return visual() ? BANNER + renderFrame(cwd) : renderFrame(cwd);
     const iterations = opts.iterations ?? Infinity;
     const sleep = opts.sleep ?? defaultSleep;
     const bounded = Number.isFinite(iterations);
@@ -223,7 +220,7 @@ export async function status(argv, cwd = process.cwd(), opts = {}) {
     for (let i = 0; i < iterations; i++) {
         const frame = renderFrame(cwd);
         if (tty)
-            process.stdout.write(`\x1b[2J\x1b[H${BANNER}${frame}\n\x1b[2m watching · refresh ${REFRESH_MS / 1000}s · ^C to quit\x1b[0m`);
+            process.stdout.write(`\x1b[2J\x1b[H${BANNER}${frame}\n${legend(` watching · refresh ${REFRESH_MS / 1000}s · ^C to quit`)}`);
         else
             process.stdout.write(frame + sep);
         if (bounded)

package/dist/drivers/herdr.js

@@ -1,4 +1,5 @@
 import { shq } from "../adapters/types.js";
+import { PANE_IDENTITY_ENV, paneIdentityLine } from "../brand.js";
 import { createWorktree, sh } from "../run/git.js";
 import { herdrSealShellPrefix } from "./subprocess.js";
 import { canonicalizeLegacyName, formatOwnedName, panesToClose, parseOwnedName } from "./types.js";
@@ -115,6 +116,8 @@ export class HerdrDriver {
         const rootPane = res?.root_pane?.pane_id; // auto-created shell pane (SKILL:343)
         if (typeof tabId !== "string" || !tabId)
             throw new Error(`herdr tab create returned no tab_id (refusing untargeted placement): ${t.stdout}`);
+        // T5: the banner's pane identity line, derived from the T1 owned name (legacy names pass through).
+        const identity = shq(paneIdentityLine(canonicalizeLegacyName(name, "")));
         let r = await this.herdr(`agent start ${shq(name)} --cwd ${shq(cwd)} --tab ${shq(tabId)} --no-focus -- bash`);
         if (r.code !== 0 && /agent_name_taken/.test(r.stderr + r.stdout)) {
             // DEFECT-01: a prior (killed) process's kept pane still holds this durable name — reclaim it.
@@ -149,7 +152,7 @@ export class HerdrDriver {
         // worker GETS, not a rule it must remember (P40-02 probe leak). Fail closed: a failed seed rejects.
         // v1.22 T3 / OBS-17: also strip HERDR_ENV + socket path so the worker cannot open/mutate panes in
         // the operator's session. Daemon-side this.herdr() calls keep process.env (unsealed).
-        const seed = await this.herdr(`pane run ${shq(id)} ${shq(`export HERDR_WORKSPACE_ID=${shq(this.ws)}; ${herdrSealShellPrefix()}`)}`);
+        const seed = await this.herdr(`pane run ${shq(id)} ${shq(`export HERDR_WORKSPACE_ID=${shq(this.ws)}; export ${PANE_IDENTITY_ENV}=${identity}; ${herdrSealShellPrefix()}`)}`);
         if (seed.code !== 0)
             throw new Error(`herdr workspace-id seed failed (refusing untargeted pane): ${seed.stderr || seed.stdout}`);
         return { id, name, cwd, tabId };
@@ -260,7 +263,8 @@ export class HerdrDriver {
         // like a failed cd (return null → caller falls back to a per-slot tab). this.ws is guaranteed set —
         // joinGroup runs only after the first member's tabSlot succeeded, which requires it (VIS-10).
         // v1.22 T3: same env seal as tabSlot — strip control-plane vars after the workspace seed.
-        const seed = await this.herdr(`pane run ${shq(pane)} ${shq(`export HERDR_WORKSPACE_ID=${shq(this.ws)}; ${herdrSealShellPrefix()}`)}`);
+        // T5: same brand identity seed as tabSlot — every group member's banner announces its own name.
+        const seed = await this.herdr(`pane run ${shq(pane)} ${shq(`export HERDR_WORKSPACE_ID=${shq(this.ws)}; export ${PANE_IDENTITY_ENV}=${shq(paneIdentityLine(canonicalizeLegacyName(name, "")))}; ${herdrSealShellPrefix()}`)}`);
         if (seed.code !== 0) {
             await this.herdr(`pane close ${shq(pane)}`);
             return null;

package/dist/run/daemon.js

@@ -5,6 +5,7 @@ import { join } from "node:path";
 import { trailerPattern, 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 } from "../brand.js";
 import { loadConfig } from "../config/config.js";
 import { herdrSealShellPrefix, SubprocessDriver } from "../drivers/subprocess.js";
 import { formatOwnedName } from "../drivers/types.js";
@@ -489,7 +490,9 @@ export async function runDaemon(repoRoot, opts = {}) {
                 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.
-                    await driver.run(slot, `${icmd}; ${exitMarkerCmd}`);
+                    // T5: the pane announces itself first — same brand header (logo + dim identity) as the
+                    // judge/review/consult dispatch scripts; one printf one-liner, dispatch mechanics unchanged.
+                    await driver.run(slot, `${bannerShell()}; ${icmd}; ${exitMarkerCmd}`);
                     let paged = false;
                     // v1.22 T5 / OBS-19: auto-answer a fingerprint-matched trust dialog exactly once per slot.
                     // Any other blocked/idle dialog still pages the operator (paged latch below).
@@ -576,7 +579,8 @@ export async function runDaemon(repoRoot, opts = {}) {
                 }
                 else {
                     const inv = adapter.invoke(t, wt, assignment, { promptFile });
-                    await driver.run(slot, `${inv.command}; ${exitMarkerCmd}`);
+                    // T5: same brand header as the interactive path and the gate/consult dispatch scripts.
+                    await driver.run(slot, `${bannerShell()}; ${inv.command}; ${exitMarkerCmd}`);
                     // OBS-54: headless workers have the same output-inactivity budget as visible panes.
                     const stallWindowMs = taskTimeoutMinutes * 60_000;
                     let lastOutput = await driver.read(slot, 500);

package/package.json

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