tickmarkr 2.4.1 → 2.5.0

package/README.md

@@ -79,7 +79,7 @@ tickmarkr init                 # guided setup + doctor; scaffolds config and spe
 tickmarkr compile tickmarkr.spec.md # spec → task graph (fails without acceptance criteria)
 tickmarkr plan                 # dry-run routing decisions + cost estimate
 tickmarkr run                  # execute, route to best CLI, gate every result (--concurrency N)
-tickmarkr report <runId> --md  # engagement record in Markdown
+tickmarkr report <runId> --md  # Markdown on stdout; redirect to save beside the spec
 ```
 
 That's the flow: `init` scaffolds config, you write tasks with `acceptance[]` criteria, `compile`
@@ -113,16 +113,51 @@ Consent rules — every write is additive, never destructive:
 
 ## Monitor and supervise
 
+`tickmarkr ui [runId]` opens one cockpit with **1 Home, 4 Run, 5 Evidence**. Without a
+run ID it selects the latest journal; an empty repository opens Home. Use
+`tickmarkr ui <runId> --view run` or `--view evidence` to open a delivered view directly.
+`tickmarkr ui --setup <runId>` opens Run Parks and preserves the requested run identity.
+Fleet/Bootstrap and Plan/Health are explicit follow-ons: keys 2/3/6 are not installed.
+Use the existing `tickmarkr fleet`, `tickmarkr init`, `tickmarkr plan` and `tickmarkr doctor`
+commands for those workflows.
+
+`?` opens the shortcut sheet; Tab/Shift-Tab move focus through visible regions, Enter opens
+selection, and Esc closes the deepest overlay. `q` quits; text-entry mode keeps `q1?`
+literal. Run shows every task in the matching graph, its recorded attempt/path/pane/alarm,
+and current-attempt gate evidence. `o` requests focus of the recorded owned pane when the
+driver supports it; unavailable panes leave an evidence diagnostic. Evidence keeps original
+journal `#L` identities, full verdict paging, and a stable selection with Follow off.
+
 ```bash
-tickmarkr status               # engagement state (--watch to follow live)
+tickmarkr status <runId>        # preserved printed engagement state
+tickmarkr status <runId> --oneline # compact snapshot, then exit
+tickmarkr status <runId> --watch # TTY: Run cockpit; non-TTY: line output
+tickmarkr status <runId> --watch --plain # preserved line/ANSI fallback, including on a TTY
 tickmarkr resume <runId>       # continue an engagement from the local execution log
-tickmarkr approve <runId> <taskId>   # approve a parked task (--reason to document)
+tickmarkr approve <runId> <taskId>   # append permission for a non-gate park; see below
 tickmarkr report <runId>       # cost/quality report
+tickmarkr report <runId> --md > feature.record.md # explicit file write beside your spec
 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.
+For machines, `tickmarkr status <runId> --watch --events` replays and follows projected
+decision events as one JSON document per stdout line. `--jsonl` and `--decision-events`
+are aliases; keep stderr keepalives separate (never `2>&1`). This projection is distinct
+from raw `journal.jsonl`. Webhook delivery remains opt-in via `--webhook <url>`.
+Preserved printed twins also include separate `fleet --print` and `fleet --why` outputs,
+`plan`, `doctor`, `report --compare <baseline-runId>`, `report --bundle <path>` (an explicit
+proof-bundle write), and `stats` (all runs, no run ID). Report retains its learning preview
+and comparison warnings; absent metering stays “not measurable,” never an invented $0.
+
+A manual cockpit keeps its final receipt at run-end and follows a later resume of that run.
+By default, the daemon-owned board requests graceful shutdown at run-end and closes only its owned pane
+after checking its watch presence stood down; unconfirmed cleanup is reported. The existing
+`visibility.keepPanes: forever` debug override preserves panes. Herdr keeps
+task/gate grouping, short titles, and the board beside its caller without taking focus.
+Quitting or orderly signals restore raw mode, pointer tracking, title and alternate screen,
+and release only that observer's presence. Green tasks land on `tickmarkr/<runId>`;
+merge to your mainline is always your call.
 
 ### Escalation and consults
 
@@ -133,15 +168,57 @@ away from a failing adapter will never retry it in subsequent `tickmarkr resume`
 
 ### Approving tasks
 
-`tickmarkr approve` unblocks two task states:
-
-**Human gates** (attempt budget ≥ 1):
-- The task finished with a result but gates require human judgment (`humanGate: true` in the spec)
-- Approving records the Partner's verdict and the task proceeds to merge
-
-**Attempt-budget exhaustion**:
-- 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
+The recorded partial-human-park case has **1/3 merged**, human T2, blocked T3, and a
+passed tip verify. It is **PARTIAL**, not green: T2's `humanGate: true` parks it **before
+dispatch**. In Run (`4`, or `tickmarkr ui --setup <runId>`), select T2, press `a` for
+Actions, choose Approve with Enter, and review the confirmation: run/task, original park
+`#L`, actor/reason, exact `tickmarkr approve` argv, append-only consequence and enactor.
+Only `y` confirms; `n`/Esc cancel, and Enter never confirms.
+
+Read the receipt's newly appended `task-approved` line, actor/reason and disposition back
+from the journal. Approval records permission; it does not dispatch work, pass a gate or
+mark the task done. With no live owner the receipt says **approved; resume required**.
+Exit the observer and run `tickmarkr resume <runId>` explicitly. A matching live daemon
+can enact the release at its next task boundary; a different live run must end before this
+one resumes. Keep any resume refusal and its remediation visible, including a deny/prefer
+config conflict; repair the source/config as directed, never edit the compiled graph to
+force success. After resume, CURRENT TIP is PENDING until fresh evidence arrives. Completion
+requires the latest run-end, a nonfailed known tip result, and empty `failed`, `human`,
+`blocked` and `pending` buckets; the completed case has 3/3 recorded merges. An unrelated
+graph says “not comparable” and supplies no borrowed denominator. Historical GATES RAN
+does not establish current completion.
+
+The CLI twin for the same decision is
+`tickmarkr approve <runId> T2 --by operator --reason 'ready to proceed'`, followed by the
+receipt check and explicit resume above. Other parks have different permitted decisions:
+
+| Park | Decision and effect |
+|---|---|
+| Human gate / other non-gate park | Plain approve records permission to dispatch. |
+| Attempt cap | Plain approve grants a fresh attempt budget; prior routing exclusions remain. |
+| Infrastructure | Plain approve or `--recheck`; recheck reruns the declared battery and satisfies no gate. |
+| Failed review gate | `--waive` satisfies only that identified gate; `--uphold` funds one fixed attempt carrying findings; `--recheck` reruns the battery. |
+| Other failed gate | `--waive` or `--recheck`; plain approve refuses. |
+| Tombstone / gate failure without identifying evidence | Diagnostic only; no invented decision. |
+
+Decisions are append-only and cannot be undone. Unknown tasks, duplicate decisions and
+changed parks refuse; no success receipt is claimed without reading back the append.
+
+### Help and recovery
+
+`tickmarkr ui --help`, `tickmarkr eval --help`, `tickmarkr unlock --help` and
+`tickmarkr profile reset --help` print guidance without opening a UI, seeding fixtures,
+unlocking or resetting history. Help flags are recognized before `--`; arguments after
+it are literal data. Help examples describe operations; printing them never executes them.
+
+Recovery remains explicit: `unlock <runId>` targets a matching provably dead lock;
+`unlock --garbage` handles malformed lock bytes without inventing a run ID. Both require
+confirmation (`--yes` for non-TTY) and refuse live, inaccessible or changed holders.
+`doctor --cached` reads cached diagnostics; `doctor --probe-preflight` discloses probe
+counts/files; `doctor --fix-only` repairs locally without model probes or catalog refresh.
+Default doctor and `--fix` still probe. `doctor --refresh-catalog` refreshes only the catalog.
+`scope <intent-file> --preview` is a local, non-writing preview; authoring requires TTY
+confirmation or `--yes` and can make model calls.
 
 ## Choosing your fleet: `tickmarkr fleet`
 
@@ -155,7 +232,7 @@ tickmarkr plan            # lint the resolved routing table against your spec
 tickmarkr run             # dispatch with the fleet you confirmed
 ```
 
-`tickmarkr doctor` is a pure sensor; `tickmarkr fleet` is the actuator. The browser is one
+`tickmarkr doctor` probes and records health; `tickmarkr fleet` edits routing config. The browser is one
 two-pane surface: the left rail lists views (**All models**, **Shapes**, **Steering**) and every
 installed agent CLI with its auth state and model count; the right pane is a searchable model list
 with tier, context, price, and probe-latency columns. `Space` allows/denies, `Enter` classifies an
@@ -283,7 +360,7 @@ the frontier-model consult is the *National Office*. The terms below use that vo
   - (bare token) — member is running normally
 - **cleanup · <taskId>**: overflow/teardown generation tabs. When a new generation starts (on retry escalation), a new cleanup tab
   opens labeled with the newest live member's task ID; it auto-closes when the generation completes
-- **watch**: a single pane running `tickmarkr status --watch` — the senior's glanceable engagement monitor
+- **watch**: a single owned pane running `tickmarkr ui <runId> --view run` — the same Run cockpit opened by TTY `status --watch`
 
 ### Pane naming (when visibility.llm = pane)
 
@@ -311,13 +388,17 @@ This keeps the Partner focused on decisions that require attention, not noise.
 
 tickmarkr closes exactly what it owns and no longer needs, no matter how any process died.
 
-Every pane and tab tickmarkr creates receives a **parseable ownership name** encoding the pane's role, task, attempt, and run:
+Tabs use short human labels (at most 20 characters); panes carry durable ownership names:
 - `<taskId>` — the task's tab, holding its worker and its judge/review/consult panes
 - `cleanup · <taskId>` — teardown generation tab for overflow attempts
-- `watch` — status monitor pane
-- `<role> · <taskId> · A<attempt> · R<runId>` — judge, review, consult, and worker panes (formats like `judge · task-abc123 · A1 · Rrun-20260713-175532`)
+- `tickmarkr:watch:run:0:<runId>` — daemon-owned Run board
+- `tickmarkr:<role>:<taskId>:<attempt>:<runId>` — durable judge, review, consult and worker pane names; display titles may be shorter
 
-tickmarkr creates all owned panes only within the run's workspace; any tickmarkr-owned panes discovered outside the run's workspace (from prior runs or placement bugs) are reconciled and closed. Any pane not matching the ownership contract is **foreign** — created by you or another tool — and is never closed automatically.
+Reconciliation stays within the run's workspace. It can retire another run's panes only
+when this repository's journal evidence proves that run ended; live or unknown runs and
+other workspaces remain protected. Pane names outside the ownership contract are **foreign**.
+Board replacement additionally checks repository/run ownership and its acknowledged watch
+presence; matching a short tab label is never sufficient.
 
 **Desired-state reconciliation**: A pure function computes the exact set of panes that should exist from the local journal at any moment:
 - Worker panes for all in-flight task attempts
@@ -326,12 +407,14 @@ tickmarkr creates all owned panes only within the run's workspace; any tickmarkr
 - Empty set (after engagement end)
 
 The daemon reconciles at every safe point:
-1. **Run start** — clean up any orphaned panes from crashed earlier runs of the same repo
+1. **Run start** — reconcile this run and older runs proven ended in this repository
 2. **Resume** — reconcile the restarted journal state and close panes for superseded attempts
 3. **After terminal events** (task done, failed, human gate) — close the corresponding worker/gate pane and its emptied tab
-4. **At engagement end** — close all remaining owned panes and tabs
+4. **At engagement end** — close remaining owned panes and tabs, with graceful board shutdown
 
-Reconciliation failures (herdr unavailable, a pane vanished mid-sweep) never fail the engagement — visibility is cosmetic, gates are law.
+`visibility.keepPanes: forever` disables this sweep. Reconciliation failures (herdr
+unavailable, a pane vanished mid-sweep) do not replace gate verdicts; unconfirmed board
+cleanup is journaled and reported.
 
 ### Workspace trust
 
@@ -372,10 +455,13 @@ them; worker-declared deviations are recorded as notes, not authority.
 
 If you clone this repo and use Claude Code, project skills are installed in `.claude/skills/`:
 
-- **`/tickmarkr-loop`** — compile a spec, review the routing plan, run the engagement, and commit the Markdown record
-- **`/tickmarkr-auto`** — autonomous multi-phase runs (GSD milestones, etc.)
+- **[/tickmarkr-loop](skills/tickmarkr-loop/SKILL.md)** — compile a spec, review the routing plan, run the engagement, and commit the Markdown record
+- **[/tickmarkr-auto](skills/tickmarkr-auto/SKILL.md)** — autonomous multi-phase runs (GSD milestones, etc.)
 
 These are optional — the CLI works standalone. Skills are repo-scoped and ship in the npm tarball for agents working in projects that have run `tickmarkr init --agent`.
+The canonical sources live in `skills/`; this repository's installed `.claude/skills/` links
+resolve there. The [overseer skill](skills/tickmarkr-overseer/SKILL.md) links to the same
+loop walkthrough for cockpit and decision guidance; skill names remain unchanged.
 
 ## Contributing
 

package/dist/adapters/claude-code.js

@@ -3,7 +3,7 @@ import { readdirSync, readFileSync, realpathSync, statSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { parseWorkerResult } from "./prompt.js";
-import { channelsFromConfig, declareInputBox, MODEL_ID_RE, shq, TokenUsageSchema } from "./types.js";
+import { channelsFromConfig, declareInputBox, MODEL_ID_RE, promptFitsArgv, shq, TokenUsageSchema } from "./types.js";
 // SPEND-01/SPEND-11: claude writes a per-session JSONL to ~/.claude/projects/<slug>/ where slug is the
 // realpath'd cwd with every non-alphanumeric char replaced by "-" (verified 114/114 — 36-DIAGNOSIS.md).
 // The old `/`-only formula missed the "." in `.tickmarkr/worktrees/…` — ENOENT on every worktree dispatch.
@@ -239,7 +239,12 @@ export const claudeCode = {
     // live check ate the prompt), and --prompt-suggestions takes an OPTIONAL value — appended directly
     // before the prompt it would swallow it the same way. So the setting's value is always followed by
     // another flag, never by the prompt positional.
-    interactiveCommand: (promptFile, model) => `claude --model ${shq(model)} --strict-mcp-config --mcp-config '{"mcpServers":{}}' --settings '{"promptSuggestionEnabled":false}' --prompt-suggestions false --permission-mode bypassPermissions "$(cat ${shq(promptFile)})"`,
+    // OBS-931: the same ONE-argv-string hazard as codex (OBS-930) — over promptArgvCeiling() the TUI
+    // launch would E2BIG on Linux, so it returns null → worker-mode-fallback → the headless form.
+    // resumeCommand keeps the shape: its contract returns a string (composer delivery is 2.4.3 work).
+    interactiveCommand: (promptFile, model) => promptFitsArgv(promptFile)
+        ? `claude --model ${shq(model)} --strict-mcp-config --mcp-config '{"mcpServers":{}}' --settings '{"promptSuggestionEnabled":false}' --prompt-suggestions false --permission-mode bypassPermissions "$(cat ${shq(promptFile)})"`
+        : null,
     trustDialog: CLAUDE_TRUST_DIALOG,
     inputBox: CLAUDE_INPUT_BOX,
     // A resumed attempt lands in the same painted editor, so it carries the same ghost-text suppression

package/dist/adapters/codex.d.ts

@@ -4,6 +4,7 @@ export declare function readCodexModelsCache(path?: string): {
     fetchedAt?: string;
 };
 export declare const CODEX_TRUST_DIALOG: TrustDialog;
+export declare const CODEX_INPUT_BOX: import("./types.js").InputBox;
 export declare function seedCodexTrust(repoRoot: string, configPath?: string): TrustVerdict;
 export declare function hasCodexTrustedProject(text: string, root: string): boolean;
 export declare function codexConfigMcpServerNames(configPath?: string): string[];

package/dist/adapters/codex.js

@@ -3,7 +3,7 @@ import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { probeVersion } from "./claude-code.js";
 import { parseWorkerResult } from "./prompt.js";
-import { channelsFromConfig, MODEL_ID_RE, shq, TokenUsageSchema } from "./types.js";
+import { channelsFromConfig, declareInputBox, MODEL_ID_RE, promptFitsArgv, shq, TokenUsageSchema } from "./types.js";
 // SPEND-07: codex writes per-session JSONL to ~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl — date-partitioned,
 // NOT cwd-keyed. session_meta.payload.cwd is FILE-SCOPED (one codex exec per cwd). token_count events carry
 // per-turn DELTAS in payload.info.last_token_usage; we read POST-HOC (never the pane, never the trailer).
@@ -95,6 +95,56 @@ export const CODEX_TRUST_DIALOG = {
     fingerprint: "Do you trust the contents of this directory?",
     key: "Enter",
 };
+// OBS-930 / OBS-136: the codex TUI's composer, CAPTURED (codex 0.153.4, herdr pane read, 2026-09-05
+// 15:48Z — tests/fixtures/codex-input-box, provenance in its README), never guessed:
+//     (background row)
+//     › Ask Codex to do anything        ← U+203A, ASCII space, then the DIM placeholder (empty) or the draft
+//     (background row)
+//     gpt-5.6-luna medium · /private/tmp/tkr-obs930-smoke   ← footer: <model> <effort> · <cwd>
+// Two facts a fingerprint alone would get wrong: (1) a submitted turn is echoed into the transcript
+// with the SAME caret (`› You are a smoke test.`), and so is the trust dialog's cursor (`› 1. Yes,
+// continue`) — only the composer is followed by the footer row, so the footer is the anchor, exactly
+// as claude's editor is anchored by its rules; (2) an EMPTY composer paints its placeholder as text,
+// so "empty" is a closed allowlist of captured placeholders (0.153.4 above; 0.144.5's
+// `Run /review on my current changes` from tests/fixtures/codex-mcp-spinner). An unknown placeholder
+// reads as occupied and a submit onto it fails closed by name (OBS-140) — a fixture-capture chore,
+// never a drive-by widening. `match` is THE COMPOSER IS PAINTED (true while empty, true mid-turn);
+// `emptyMatch` is painted AND carrying nothing — the only positive evidence a submit registered.
+const CODEX_ANSI_SGR_RE = /\u001B\[[0-9;]*m/g;
+const CODEX_CARET_RE = /^› /;
+const CODEX_PLACEHOLDER_RE = /^› (?:Ask Codex to do anything|Run \/review on my current changes)$/;
+const CODEX_FOOTER_RE = /^\S+(?: \S+)? · \S/;
+// A wrapped or multi-line draft grows the composer downward before the footer.
+// ponytail: a fixed window, not a parser — raise it if a real capture ever shows a taller composer.
+const CODEX_MAX_COMPOSER_ROWS = 8;
+function matchesCodexComposer(paneText, empty) {
+    const lines = paneText.replace(CODEX_ANSI_SGR_RE, "").split("\n").map((l) => l.trim());
+    const caret = empty ? CODEX_PLACEHOLDER_RE : CODEX_CARET_RE;
+    return lines.some((line, i) => {
+        if (!caret.test(line))
+            return false;
+        for (let below = i + 1; below < lines.length && below <= i + CODEX_MAX_COMPOSER_ROWS; below++) {
+            if (CODEX_FOOTER_RE.test(lines[below]))
+                return true;
+            // only the composer's own rows may sit between the caret row and the footer: the background
+            // rows (blank in a text read) and a draft's continuation rows — never another caret row
+            if (lines[below] !== "" && CODEX_CARET_RE.test(lines[below]))
+                return false;
+        }
+        return false;
+    });
+}
+export const CODEX_INPUT_BOX = declareInputBox("codex", {
+    fingerprint: "› ",
+    match: (paneText) => matchesCodexComposer(paneText, false),
+    emptyMatch: (paneText) => matchesCodexComposer(paneText, true),
+    // As for claude (OBS-342): a fresh codex worker slot is a shell awaiting its launch line; every
+    // later delivery is a TUI turn awaiting this composer.
+    firstDeliveryIsLaunch: true,
+    // The 2026-09-05 capture painted the composer ~10 s after the trust answer with MCP suppressed;
+    // claude's bound, kept for the same cold-start reasons.
+    readinessTimeoutMs: 30_000,
+});
 // v1.22 T5 / OBS-16: codex keys trust on absolute path under [projects."<root>"] trust_level="trusted"
 // in ~/.codex/config.toml (CODEX_HOME relocates the dir). Worktrees inherit parent-project trust when
 // the REPO ROOT is trusted — seed the root once, cover every future worktree. Idempotent: a second
@@ -186,14 +236,24 @@ export const codex = {
     channels: (cfg) => channelsFromConfig("codex", cfg),
     // v1.65 T3: every flag the command builder below hardcodes (incl. codexMcpSuppressionFlags' -c/
     // --disable and GITDIR_WRITABLE's -c) — all listed by top-level `codex --help`, verified 2026-07-22.
-    hardcodedFlags: { binary: "codex", flags: ["--sandbox", "--model", "-c", "--disable", "--dangerously-bypass-hook-trust"] },
+    hardcodedFlags: { binary: "codex", flags: ["--sandbox", "-a", "-s", "--model", "-c", "--disable", "--dangerously-bypass-hook-trust"] },
     // --sandbox workspace-write is the autonomous sandbox mode (codex v0.144.1+)
     // MCP suppression built per dispatch (config can change between runs) — see codexMcpSuppressionFlags.
     // CODEX_HOOK_TRUST (OBS-125) clears the per-worktree "Hooks need review" gate while keeping the sandbox.
     headlessCommand: (promptFile, model) => `codex exec --sandbox workspace-write ${CODEX_HOOK_TRUST} ${codexMcpSuppressionFlags()} ${GITDIR_WRITABLE} --model ${shq(model)} - < ${shq(promptFile)}`,
-    // OBS-889: Codex's TUI has no file/stdin prompt form. Returning null makes the daemon journal
-    // worker-mode-fallback before it runs the argv-safe headless command in the visible pane.
-    interactiveCommand: () => null,
+    // OBS-930: the visible pane runs the REAL TUI. Codex's TUI takes its prompt only as the [PROMPT]
+    // positional (`codex --help`, 0.153.4 — no file/stdin form), so the launch inlines the file exactly
+    // as the claude adapter does: the prompt is the LAST positional and every flag value is followed by
+    // a flag, never by the prompt. The argv hazard that once forbade this (OBS-889: `countLiveSuites`
+    // matched a suite word 140 KB into a finished worker's argv) is closed on the counter side — the
+    // census reads a command's first four tokens only — and those four never carry a suite word here.
+    // Same sandbox, hook trust and MCP suppression as the headless form; `-a never` is the TUI's
+    // autonomous approval policy (exec has no approvals to configure).
+    // OBS-930 (Linux): the inlined prompt is ONE argv string and Linux caps one at 131072 bytes, so a
+    // prompt over promptArgvCeiling() returns null → worker-mode-fallback → the headless form (types.ts).
+    interactiveCommand: (promptFile, model) => promptFitsArgv(promptFile)
+        ? `codex -a never -s workspace-write ${CODEX_HOOK_TRUST} ${codexMcpSuppressionFlags()} ${GITDIR_WRITABLE} --model ${shq(model)} "$(cat ${shq(promptFile)})"`
+        : null,
     invoke(task, _cwd, a, ctx) {
         return { command: this.headlessCommand(ctx.promptFile, a.model) };
     },
@@ -202,6 +262,7 @@ export const codex = {
     // "Do you trust this directory?" (OBS-16). doctor-only side effect.
     trust: (repoRoot) => seedCodexTrust(repoRoot),
     trustDialog: CODEX_TRUST_DIALOG,
+    inputBox: CODEX_INPUT_BOX,
     // v1.5 MODEL-01: file read only (no `codex models` subcommand exists, verified 2026-07-10).
     // Already fails OPEN to [] internally — advisory detection, unlike gates' fail-closed.
     listModels: async () => readCodexModelsCache().models,

package/dist/adapters/types.d.ts

@@ -185,5 +185,9 @@ export declare function channelKey(c: {
     model: string;
 }): string;
 export declare function shq(s: string): string;
+export declare const PROMPT_ARGV_CEILING_LINUX = 120000;
+export declare const PROMPT_ARGV_CEILING_DEFAULT = 900000;
+export declare function promptArgvCeiling(platform?: string): number;
+export declare function promptFitsArgv(promptFile: string, platform?: string): boolean;
 export declare const QUOTA_RE: RegExp;
 export declare const MODEL_ID_RE: RegExp;

package/dist/adapters/types.js

@@ -1,3 +1,4 @@
+import { statSync } from "node:fs";
 import { z } from "zod";
 // SPEND-01/06: normalized token counts — the measurable fact. NO cost field, ever: CLIs report
 // cost:0 on sub plans and notional list prices on others (LIVE-CHECK finding 3); money is Phase 18's
@@ -232,6 +233,38 @@ export function channelKey(c) {
 export function shq(s) {
     return `'${s.replaceAll("'", `'\\''`)}'`;
 }
+// OBS-930 (Linux) / OBS-931: a TUI launch inlines the prompt file as ONE argv string — "$(cat prompt)"
+// as the last positional. Linux caps a single argv string at MAX_ARG_STRLEN = PAGE_SIZE × 32 =
+// 131072 bytes (E2BIG: CI run 33979013874, ubuntu, `codex: Argument list too long` on a 140 KB
+// prompt); darwin enforces only the 1 MB total ARG_MAX, which is why the macOS export proof passed.
+// A real worker prompt is 60–150 KB (OBS-889 measured 149,417 bytes), so on a Linux host the launch
+// fails in production, not only in the test. Ceilings are named BY PLATFORM — never a probe of the
+// running kernel at dispatch time:
+//   linux  120_000 — the cap is per STRING and every flag is its own argv entry, so only the prompt
+//                    counts against it; "$(cat …)" strips nothing but trailing newlines, so the
+//                    file's byte size IS the string's. 131072 − 120000 leaves ~11 KB of headroom.
+//   others 900_000 — under the 1 MB total that darwin/BSD enforce across argv + envp.
+// Over the ceiling the adapter returns null: the daemon journals worker-mode-fallback
+// {reason:"adapter"} and runs the headless form in the visible pane — the pre-OBS-930 behaviour,
+// now only for oversized prompts. An unreadable file is "not proven oversized" and keeps the TUI
+// rendering: the daemon writes the prompt before it builds the launch, a missing file fails the
+// same way in either form, and docs-truth renders the command against a placeholder path.
+// OBS-931 (2.4.3): the real fix is prompt delivery through the composer for large prompts.
+export const PROMPT_ARGV_CEILING_LINUX = 120_000;
+export const PROMPT_ARGV_CEILING_DEFAULT = 900_000;
+export function promptArgvCeiling(platform = process.platform) {
+    return platform === "linux" ? PROMPT_ARGV_CEILING_LINUX : PROMPT_ARGV_CEILING_DEFAULT;
+}
+export function promptFitsArgv(promptFile, platform = process.platform) {
+    let bytes;
+    try {
+        bytes = statSync(promptFile).size;
+    }
+    catch {
+        return true;
+    }
+    return bytes <= promptArgvCeiling(platform);
+}
 // Quota exhaustion is detected from CLI errors, never predicted (spec §4).
 // ZAI coding-plan exhaustion text: "Insufficient balance or no resource package. Please recharge."
 // Anchor the distinctive full phrase, not the two-word "insufficient balance" fragment — that fires

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

@@ -1,3 +1,4 @@
+import { Journal, type JournalEvent } from "../../run/journal.js";
 export declare const APPROVAL_DISPOSITIONS: readonly ["dispatch", "waive-gate", "re-dispatch", "fund-fixed-attempt", "fresh-budget"];
 export type ApprovalDisposition = (typeof APPROVAL_DISPOSITIONS)[number];
 /**
@@ -8,6 +9,47 @@ export type ApprovalDisposition = (typeof APPROVAL_DISPOSITIONS)[number];
  */
 export declare const APPROVAL_ENACTS: Record<ApprovalDisposition, string>;
 export declare function approvalDispositionForRelease(release: unknown): ApprovalDisposition;
+/** The closed verb set every decision surface may name. Nothing outside it reaches this command. */
+export declare const DECISION_VERBS: readonly ["approve", "waive", "uphold", "recheck"];
+export type DecisionVerb = (typeof DECISION_VERBS)[number];
+/** The newest park a decision binds to, read the one way this command reads it. */
+export interface NewestPark {
+    /** Index into the journal's event array; `line` is the physical 1-based journal line. */
+    index: number;
+    line: number;
+    ts: string | undefined;
+    /** The daemon-recorded kind (task-human data.kind), never inferred from prose. */
+    kind: string | undefined;
+    reason: string | undefined;
+    /** The newest failed gate before the park — the gate a waive would satisfy. */
+    failedGate: string | undefined;
+    /** A pre-dispatch human gate whose reason marks it permanent by design (see isTombstonePark). */
+    tombstone: boolean;
+}
+/**
+ * There is no closed park kind for a declaration-shaped retirement, so the evidence is the one the
+ * daemon recorded: a pre-dispatch human-gate park whose reason carries the task's own title, where the
+ * spec declares the tombstone. Read narrowly on purpose — every other kind is actionable regardless of prose.
+ */
+export declare function isTombstonePark(kind: string | undefined, reason: string | undefined): boolean;
+export declare function newestPark(events: readonly JournalEvent[], taskId: string, 
+/** Physical zero-based source indexes corresponding one-for-one with `events`. */
+sourceIndexes?: readonly number[]): NewestPark | undefined;
+/** Parsed events paired with their immutable physical JSONL identities. */
+export declare function readJournalEvents(journal: Journal): {
+    events: JournalEvent[];
+    sourceIndexes: number[];
+};
+/**
+ * FINAL §3.3's decision menu as data: human-gate/attempt-cap/other non-gate parks → approve; infra →
+ * approve or recheck; review gate-fail → waive/uphold/recheck; other gate-fail → waive/recheck; a
+ * gate-fail park with no failed-gate evidence, or a tombstone → nothing (a diagnostic, never a
+ * fabricated verb). The refusals in `approve` below enforce the same table; this is the one place a
+ * surface may read it from, so what a menu offers and what the command accepts cannot drift.
+ */
+export declare function permittedDecisionVerbs(park: Pick<NewestPark, "kind" | "failedGate" | "tombstone"> | undefined): readonly DecisionVerb[];
+/** The release marker this command appends for a verb on a park — the fact a read-back must match. */
+export declare function releaseForDecision(verb: DecisionVerb, park: Pick<NewestPark, "kind" | "failedGate">): string | undefined;
 export type ApprovalStatus = "deferred-live" | "recorded-no-owner";
 /** The requested run plus the different live run currently blocking its repository, when present. */
 export interface ApprovalRunOwner {

package/dist/cli/commands/approve.js

@@ -27,6 +27,73 @@ export function approvalDispositionForRelease(release) {
     return "dispatch";
 }
 import { acquireApprovalSerialization, runLockOwner } from "../../run/lock.js";
+/** The closed verb set every decision surface may name. Nothing outside it reaches this command. */
+export const DECISION_VERBS = ["approve", "waive", "uphold", "recheck"];
+/**
+ * There is no closed park kind for a declaration-shaped retirement, so the evidence is the one the
+ * daemon recorded: a pre-dispatch human-gate park whose reason carries the task's own title, where the
+ * spec declares the tombstone. Read narrowly on purpose — every other kind is actionable regardless of prose.
+ */
+export function isTombstonePark(kind, reason) {
+    // Declaration retirements use an explicit title marker: either an em-dash-delimited
+    // `— tombstone` suffix or the canonical `tombstone, never dispatched` phrase. A task title
+    // that merely discusses tombstones is still an ordinary, actionable human gate.
+    return kind === "human-gate"
+        && /(?:\s—\s+tombstone\b|\btombstone,\s*never dispatched\b)/iu.test(reason ?? "");
+}
+export function newestPark(events, taskId, 
+/** Physical zero-based source indexes corresponding one-for-one with `events`. */
+sourceIndexes) {
+    for (let i = events.length - 1; i >= 0; i--) {
+        const e = events[i];
+        if (e.event !== "task-human" || e.taskId !== taskId)
+            continue;
+        const kind = typeof e.data.kind === "string" ? e.data.kind : undefined;
+        const reason = typeof e.data.reason === "string" ? e.data.reason : undefined;
+        return {
+            index: i, line: (sourceIndexes?.[i] ?? i) + 1, ts: typeof e.ts === "string" ? e.ts : undefined, kind, reason,
+            failedGate: failedGateForNewestPark(events, taskId, i), tombstone: isTombstonePark(kind, reason),
+        };
+    }
+    return undefined;
+}
+/** Parsed events paired with their immutable physical JSONL identities. */
+export function readJournalEvents(journal) {
+    const tracked = journal.readTracked();
+    return {
+        events: tracked.map((row) => row.raw),
+        sourceIndexes: tracked.map((row) => row.sourceIndex),
+    };
+}
+/**
+ * FINAL §3.3's decision menu as data: human-gate/attempt-cap/other non-gate parks → approve; infra →
+ * approve or recheck; review gate-fail → waive/uphold/recheck; other gate-fail → waive/recheck; a
+ * gate-fail park with no failed-gate evidence, or a tombstone → nothing (a diagnostic, never a
+ * fabricated verb). The refusals in `approve` below enforce the same table; this is the one place a
+ * surface may read it from, so what a menu offers and what the command accepts cannot drift.
+ */
+export function permittedDecisionVerbs(park) {
+    if (!park || park.tombstone)
+        return [];
+    if (park.kind === "gate-fail") {
+        if (park.failedGate === undefined)
+            return [];
+        return park.failedGate === "review" ? ["waive", "uphold", "recheck"] : ["waive", "recheck"];
+    }
+    if (park.kind === "infra")
+        return ["approve", "recheck"];
+    return ["approve"];
+}
+/** The release marker this command appends for a verb on a park — the fact a read-back must match. */
+export function releaseForDecision(verb, park) {
+    if (verb === "waive")
+        return GATE_SATISFIED_RELEASE;
+    if (verb === "uphold")
+        return REVIEW_UPHELD_RELEASE;
+    if (verb === "recheck")
+        return RECHECK_RELEASE;
+    return park.kind === ATTEMPT_CAP_RELEASE ? ATTEMPT_CAP_RELEASE : undefined;
+}
 // THE liveness rule, written once. The lock is REPOSITORY-wide, so a live owner of some OTHER run is
 // not an owner of this one and sweeps none of its approvals — claiming otherwise is the same
 // falsehood in a new shape. Liveness itself comes from lock.ts's runLockOwner (the same inspect() the
@@ -74,19 +141,13 @@ export async function approve(argv, cwd = process.cwd()) {
         }
         // OBS-18: only the most recent task-human for this task decides whether this approval grants a
         // fresh attempt budget. The closed daemon-issued kind, never a human prose string, controls release.
-        const events = journal.read();
-        let lastHumanIndex = -1;
-        for (let i = events.length - 1; i >= 0; i--) {
-            if (events[i].event === "task-human" && events[i].taskId === taskId) {
-                lastHumanIndex = i;
-                break;
-            }
-        }
-        const lastHuman = events[lastHumanIndex];
-        const capPark = lastHuman?.data.kind === ATTEMPT_CAP_RELEASE;
-        const gateFailPark = lastHuman?.data.kind === "gate-fail";
-        const infraPark = lastHuman?.data.kind === "infra";
-        const failedGate = gateFailPark ? failedGateForNewestPark(events, taskId, lastHumanIndex) : undefined;
+        const { events, sourceIndexes } = readJournalEvents(journal);
+        const park = newestPark(events, taskId, sourceIndexes);
+        const lastHuman = park === undefined ? undefined : events[park.index];
+        const capPark = park?.kind === ATTEMPT_CAP_RELEASE;
+        const gateFailPark = park?.kind === "gate-fail";
+        const infraPark = park?.kind === "infra";
+        const failedGate = gateFailPark ? park?.failedGate : undefined;
         if (gateFailPark && !failedGate) {
             throw new Error(`task ${taskId} is parked on gate-fail but has no failed gate result on the newest park — refusing to infer one`);
         }
@@ -137,6 +198,12 @@ export async function approve(argv, cwd = process.cwd()) {
                 choices.push(`--uphold (disposition fund-fixed-attempt)`);
             throw new Error(`task ${taskId} is parked on failed gate ${failedGate}; plain approve has disposition only for non-gate parks — pass ${choices.join(" or ")}`);
         }
+        // A tombstone has no verb in permittedDecisionVerbs (the named decisions above already refused it
+        // as a non-gate park); the command enforces the same table for plain approve, so a surface that
+        // skips the helper still cannot release it.
+        if (park?.tombstone) {
+            throw new Error(`task ${taskId}'s newest park is a tombstone (${park.reason ?? "no reason"}) — permanent by design; no verb releases it`);
+        }
         journal.append("task-approved", taskId, {
             by,
             ...(reason ? { reason } : {}),