@try-works/dsh-recursive-mode 0.4.6 → 0.4.8

package/README.md

@@ -386,10 +386,17 @@ from `session/event`, with a cheap shape test first, because that event fires fo
 observer **waits** — bounded, polling, with a timeout — and reports "no settlement yet" only after actually
 waiting. The park remains as the fallback, so an unobserved round is never an approval.
 
-**Action records are written for every delegation**, and they carry `Execution Mode` and `Status`. After a
-failed delegation, they now also carry **`Failure:`** — because `Status: failed` on its own cannot distinguish a
-child that ran and failed from a child that never started. That distinction cost three rounds of investigation
-before the field existed.
+**Action records are written for every delegation**, and they carry `Execution Mode` and a `Status` with
+**three** values, not two: `accepted`, `failed`, and `parked (still running; no settlement yet)`. The third
+state exists because a round whose child had not settled is **not** a failure — the delegation interface says
+so, and `recursive_review` already reports it as `parked` — and a binary status forced it to read as one: a live
+run's record said `Status: failed` with *"the child never reported, or never ran"*, the main agent concluded its
+reviewer was dead and obtained the review another way, and the child replied eighteen minutes later. A `failed`
+record carries **`Failure:`** with its cause; a parked record carries **`Parked:`** instead — stating only what
+is known ("no settlement had landed when the wait ended … the child may still be working"), naming the
+`childId`, and saying that resuming with that id is the next step. `operations/operations.jsonl` records the
+same distinction (`parked` rather than `unaccepted`), because the operation log had the identical conflation.
+That distinction cost three rounds of investigation before the third state existed.
 
 ---
 

package/lib/client/contract.d.ts

@@ -55,6 +55,16 @@ export interface ClientSlots {
 /** A registered slot's options. */
 export interface SlotOptions {
     name: string;
+    /**
+     * The dispatch key of a KEYED seat (`tool.call.toolview` is one), required there and ignored elsewhere.
+     *
+     * ⚠ THIS FIELD WAS MISSING AND ITS ABSENCE WAS NOT COSMETIC: `slots.ts` registers the run-start spec sheet
+     * on `tool.call.toolview` under the tool's wire name, and the harness's own options type makes `key`
+     * mandatory for a keyed slot (`KindOptions` in `packages/client/ui-slots`, where a keyed registration with
+     * no key THROWS `keyed slot "<name>" requires options.key`). Without the field here the face did not match
+     * the API it describes, so `tsc --noEmit` rejected the registration and the sheet was unreachable code.
+     */
+    key?: string;
     id?: string;
     order?: number;
     label?: string;

package/lib/client/doc-viewer.d.ts

@@ -6,6 +6,27 @@ export interface DocLine {
     text: string;
     /** table: data rows (header separator row dropped); first row is the header. */
     cells?: string[][];
+    /**
+     * li: the item WAS a `- [ ]` / `- [x]` task box, and whether it was ticked.
+     *
+     * ⚠ THIS IS A FIELD ON `li`, NOT A NEW KIND, ON PURPOSE. A task box is a list item — it keeps the bullet
+     * layout, the line index and the search behaviour every existing `li` has — and the ONE thing the reader
+     * must be able to see that a plain string cannot carry is the BOX ITSELF. The scaffolded Phase 0 template
+     * ships seven unticked boxes, so "is this still the template?" is partly a question about these marks.
+     *
+     * ⚠ AND THE BOX IS NOT LEFT IN `text`. `text` is the item's CONTENT, exactly the shape the base parser
+     * already produces for a plain bullet, so `search`/`copy` and every other consumer of a line's text see the
+     * words rather than the syntax. The tick survives as this field, and the renderer draws the mark back.
+     */
+    checked?: boolean;
+    /**
+     * plain: this line is a `Coverage:` / `Approval:` GATE reading, and how it reads.
+     *
+     * Same reasoning as `checked`: a gate line is a line of text, so it stays `plain` and gains the one fact
+     * the renderer cannot re-derive — whether it currently says PASS or FAIL, which is exactly what a person
+     * must be able to see before approving the document that contains it.
+     */
+    gate?: 'pass' | 'fail';
 }
 /** Inline segment parsed from line text (bold / code span / link). */
 export interface InlineSegment {
@@ -17,6 +38,12 @@ export interface InlineSegment {
  * Markdown -> line tokens. Base is parsePlan (blank/h1-h4/li/plain, MIT),
  * extended for fenced code blocks (one code line per block) and pipe tables
  * (one table line per block, header separator row dropped).
+ *
+ * AND EXTENDED FOR WHAT THE RUN ARTIFACTS ACTUALLY CONTAIN — the task boxes and gate readings the
+ * scaffolded `00-requirements.md` ships (`- [ ] …`, `Coverage: FAIL`, `Approval: FAIL`), because a preview
+ * that renders an unticked box and a FAIL gate as generic body text hides the two marks a person who is
+ * being asked to approve the document most needs to see. Both are additive FIELDS on the existing `li` and
+ * `plain` kinds, so no line is retyped, no character is dropped, and every existing caller keeps working.
  */
 export declare function parseDoc(plan: string): DocLine[];
 /**
@@ -31,6 +58,29 @@ export interface DocViewerProps {
     theme: BoardTheme;
     onClose: () => void;
 }
+/**
+ * Render one parsed line as a React element. Headings/bullets get parsePlan
+ * sizing; code/table get block layout; inline markup applies to plain-ish text.
+ *
+ * ⚠ ONE RENDERER, TWO READERS. `DocViewer` and the run-start spec sheet's preview both come through here,
+ * so a mark that means "unticked box" or "gate reads FAIL" cannot mean one thing in the phase-doc viewer and
+ * another in the document a person is approving. Exported for that reason alone.
+ */
+export declare function lineElement(line: DocLine, i: number, isCurrent?: boolean): ReactNode;
+/**
+ * The parsed lines as elements — the preview built from `parseDoc` + `lineElement`, with no shell of its own.
+ *
+ * ⚠ THIS IS WHAT MAKES A SECOND RENDERER UNNECESSARY. Any surface that wants to show a run artifact as a
+ * PREVIEW (the phase-doc viewer's body, the run-start spec sheet's document body) renders these nodes inside
+ * whatever frame it owns, so the markdown is parsed and drawn exactly once in the plugin. `keyBase` namespaces
+ * the React keys when several of these are on screen at once; `current` is the vim cursor line, which the
+ * spec sheet never sets.
+ */
+export declare function PreviewLines({ lines, keyBase, current }: {
+    lines: DocLine[];
+    keyBase?: string;
+    current?: number;
+}): ReactNode;
 /**
  * The per-phase doc viewer. Fetches the route on mount / fileName change.
  * Vim nav + / search + n/N + Esc; y copies the doc. Esc closes search first,

package/lib/client/spec-sheet-view.d.ts

@@ -0,0 +1,237 @@
+/**
+ * Pure display model for the RUN-START SPEC SHEET.
+ *
+ * WHY THIS MODULE EXISTS. `src/client/spec-sheet.tsx` renders the Phase 0 document beside the run-start
+ * question so a person can read what they are approving. Everything that DECIDES what the sheet says is
+ * here instead: reading the tool call's own arguments, classifying the document, and choosing the fetch
+ * state. It is pure (no React, no fs, no session window), which is what lets the spec drive every branch —
+ * a stub, a filled document, a missing file, a failed route, a call with no runId — without a browser.
+ *
+ * ⚠ THE VERDICT COMES FROM THE TEXT, NEVER FROM THE FETCH. `loading`, `absent`, `error` and `loaded` are
+ * four different facts, and a single "not loaded" would collapse them — which is how a client comes to
+ * render an empty box for a failure and a failure for a document nobody has written yet.
+ *
+ * ⚠ AND IT IS NODE-FREE. This file is reached by the BROWSER bundle. Reading the artifact belongs to the
+ * server half (`run-start.ts`, `recursive_ask.tool.ts`); this half only ever DISPLAYS what the read-only
+ * `/doc` route returned.
+ */
+import { type ArtifactMarkerHit, type ArtifactVerdict } from '../run-spec.ts';
+/**
+ * The wire name of the tool whose call row the sheet replaces.
+ *
+ * `tool.call.toolview` is a KEYED seat dispatched by this exact string, so a typo renders nothing at all
+ * rather than rendering wrongly — the failure mode the harness documents for a keyed seat.
+ */
+export declare const RUN_START_TOOL_NAME = "recursive_ask";
+/**
+ * The Phase 0 artifact the run-start decision is recorded in.
+ *
+ * ⚠ DUPLICATED DELIBERATELY, AND PINNED BY A TEST. `run-start.ts` holds the same string, but importing it
+ * here would pull `node:fs` / `node:crypto` into the browser bundle through `status.ts` and take the page
+ * down for a constant. `tests/spec-sheet.spec.ts` asserts this value EQUALS `RUN_START_ARTIFACT`, so the copy
+ * cannot drift; the client only ever reads through it and never writes.
+ */
+export declare const RUN_START_SPEC_FILE = "00-requirements.md";
+/** The gate id whose question this sheet accompanies. */
+export declare const RUN_START_GATE_ID = "run-start";
+/** The tool call's own arguments, as far as the client reads them. */
+export interface RecursiveAskArgs {
+    /** The gate id the call asked for; null when the call did not name one. */
+    gate: string | null;
+    /** The run whose spec the call is about; null when absent or blank. */
+    runId: string | null;
+    /** The artifact the call named, if any (the run-start gate never lets a caller redirect it). */
+    artifact: string | null;
+    /** The approval label the call carried, when it carried one. */
+    answer: string | null;
+}
+/**
+ * Read the arguments out of the raw JSON the model dispatched.
+ *
+ * A malformed or empty payload yields all-nulls rather than throwing: a truncated mid-stream argument string
+ * is a normal sight on this seat (the harness exposes preparing calls with no arguments at all), and a view
+ * that threw on one would take the transcript down with it.
+ */
+export declare function parseRecursiveAskArgs(argsRaw: string | null): RecursiveAskArgs;
+/**
+ * The parts of the owner's call block this sheet reads.
+ *
+ * Structurally typed rather than imported: the toolview owner passes one of three phase shapes
+ * (`preparing` carries no arguments, `start` carries `argsRaw`, `result` carries the paired call — which is
+ * NULL when window truncation left the call outside the loaded window).
+ */
+export type SpecSheetBlock = {
+    readonly phase: 'preparing';
+} | {
+    readonly phase: 'start';
+    readonly argsRaw: string;
+} | {
+    readonly phase: 'result';
+    readonly call?: {
+        readonly name: string;
+        readonly argsRaw: string;
+    } | null;
+} | null;
+/** What the sheet could read from the call: its arguments, or WHY it could not. */
+export type CallRead = 
+/** The call's arguments were dispatched and parsed. */
+{
+    readonly ok: true;
+    readonly args: RecursiveAskArgs;
+}
+/** No block was supplied at all. */
+ | {
+    readonly ok: false;
+    readonly reason: 'missing';
+}
+/** The call is still PREPARING: the owner dispatches no arguments until the call starts. */
+ | {
+    readonly ok: false;
+    readonly reason: 'preparing';
+}
+/** The call settled, but the loaded window left its call head outside, so no arguments are available. */
+ | {
+    readonly ok: false;
+    readonly reason: 'truncated';
+};
+/**
+ * Read the call's arguments out of whichever phase the owner supplied.
+ *
+ * ⚠ THE THREE FAILURES ARE KEPT APART. "No block", "the arguments have not been dispatched yet" and "the
+ * window truncated the call" are three different facts, and a client that collapsed them into one empty
+ * argument set would tell a person the call named no run — a claim about the CALLER, made on evidence about
+ * the CLIENT.
+ */
+export declare function readCall(block: SpecSheetBlock | undefined): CallRead;
+/** Is this the run-start gate? Everything else keeps the generic tool row. */
+export declare function isRunStartCall(args: RecursiveAskArgs): boolean;
+/** Whether this call is one the sheet claims at all: the run-start gate, with a run named. */
+export declare function isSpecSheetCall(read: CallRead): boolean;
+/** Where the fetch of the document stands. */
+export type SpecFetchState = 'loading' | 'loaded' | 'absent' | 'error';
+/** The fetch outcome, as the component holds it. */
+export interface SpecFetch {
+    state: SpecFetchState;
+    text?: string | null;
+    error?: string | null;
+}
+/** Everything the sheet renders from — pure data, so the spec can assert it without a renderer. */
+export interface SpecSheetModel {
+    /** The run the call names, or null. */
+    runId: string | null;
+    /** The workspace root the live route resolved, or null while it has not answered. */
+    root: string | null;
+    /** The artifact this sheet shows. */
+    file: string;
+    /** The fetch's state. */
+    state: SpecFetchState;
+    /** Why an `error` state happened, in the route's own words. */
+    error: string | null;
+    /** The document's text VERBATIM, or null when there is nothing to show. */
+    text: string | null;
+    /** `run-spec.ts`'s verdict over that text, or null when there is no text. */
+    verdict: ArtifactVerdict | null;
+    /** The marker hits, in line order (empty when filled, and when there is no text). */
+    evidence: ArtifactMarkerHit[];
+    /** The call's own arguments, so the sheet can show which decision is being asked. */
+    args: RecursiveAskArgs;
+}
+/**
+ * Build the sheet's model from what the client actually has.
+ *
+ * ⚠ THE TEXT IS ONLY EVER TAKEN FROM A `loaded` FETCH. A stale body from a previous run is not shown against
+ * a new run id, because "this is the document" is the one claim this seat exists to make truthfully.
+ */
+export declare function specSheetModel(input: {
+    args: RecursiveAskArgs;
+    root: string | null;
+    fetch: SpecFetch;
+    file?: string;
+}): SpecSheetModel;
+/** The document's path, as it should be PRINTED (never as it is fetched). */
+export declare function specPath(runId: string | null, root: string | null, file: string): string;
+/**
+ * How the sheet is showing the document.
+ *
+ * ⚠ TWO MODES, AND THE SECOND ONE IS NOT A CONVENIENCE. The rendered preview is what makes the document
+ * REVIEWABLE — reading `##` and `- [ ]` is not reading a spec — but a person is still being asked to approve
+ * the document, and a preview is an interpretation. `raw` is the escape hatch that lets them check the
+ * interpretation against the bytes, so "the preview is not paraphrasing or hiding anything" is a claim they
+ * can verify rather than one they have to take on trust.
+ */
+export type SpecViewMode = 'preview' | 'raw';
+/** The mode a freshly mounted sheet opens in: the rendered document. */
+export declare const SPEC_DEFAULT_MODE: SpecViewMode;
+/** The toggle's own label, ALWAYS naming the mode that is on screen — never the one a click would reach. */
+export declare const SPEC_MODE_LABEL: Record<SpecViewMode, string>;
+/** What the toggle does next, in the imperative, so the control reads as an action and its state reads apart. */
+export declare const SPEC_TOGGLE_LABEL: Record<SpecViewMode, string>;
+/** One line describing what is on screen, in both modes, for the announced status. */
+export declare const SPEC_MODE_NOTE: Record<SpecViewMode, string>;
+/** The other mode — what one press of the toggle reaches. */
+export declare function otherMode(mode: SpecViewMode): SpecViewMode;
+/** The toggle as a pure control description: its label, its pressed state and what it will do. */
+export interface SpecViewToggle {
+    /** The mode currently on screen. */
+    mode: SpecViewMode;
+    /** The button's accessible name — the ACTION it performs. */
+    action: string;
+    /** Whether the control is pressed, i.e. whether the verbatim source is the thing on screen. */
+    pressed: boolean;
+    /** The line a status region announces, which names the mode CURRENTLY on screen. */
+    announce: string;
+}
+/**
+ * Describe the toggle for a mode.
+ *
+ * ⚠ `pressed` IS DERIVED FROM THE MODE, NEVER STORED BESIDE IT. A second boolean that could disagree with the
+ * mode is how a control comes to say "pressed" while the rendered document is on screen — and this is the one
+ * control whose whole job is to tell the reader which of the two things they are looking at.
+ */
+export declare function specViewToggle(mode: SpecViewMode): SpecViewToggle;
+/**
+ * What the body should be built from, so the two modes cannot be confused for one another.
+ *
+ * `preview` carries the TEXT to parse (parsing happens in the component, from the one parser this plugin
+ * has); `raw` carries the TEXT to print. Both are the same bytes: neither mode reads a different source.
+ */
+export type SpecBodyContent = {
+    readonly mode: 'preview';
+    readonly text: string;
+} | {
+    readonly mode: 'raw';
+    readonly text: string;
+};
+/**
+ * Decide the body content for a document text and a mode.
+ *
+ * ⚠ NULL TEXT IS NOT `''`. A `null` document is one that was never loaded, and it must not be printed as an
+ * empty document — "there is nothing here" and "the document is empty" are different claims, and this seat
+ * exists to make claims a reader can trust.
+ */
+export declare function specBodyContent(text: string | null, mode: SpecViewMode): SpecBodyContent | null;
+/** The verdict in the plainest words available — no hedging, and nothing that reads as encouragement. */
+export declare const UNFILLED_NOTICE = "This document is still the UNFILLED TEMPLATE. There is no spec to approve yet.";
+/** The same verdict as one phrase, for a status/data attribute. */
+export declare const UNFILLED_SHORT = "unfilled template";
+/** What the sheet says when the block it was given carries no dispatched call. */
+export declare const NO_CALL_NOTICE = "This panel could not read the tool call it belongs to, so it cannot say which run spec the question is about.";
+/** What the sheet says while the call is still preparing (its arguments are not dispatched yet). */
+export declare const PREPARING_NOTICE = "This tool call has not been dispatched yet, so its arguments \u2014 and the run it names \u2014 are not available.";
+/** What the sheet says when the loaded window truncated the call head away. */
+export declare const TRUNCATED_NOTICE = "The loaded window left this call's own arguments outside it, so the run spec it names cannot be resolved here.";
+/** The labels the run-start gate offers, echoed so the sheet can state what is being decided. */
+export declare const RUN_START_APPROVE_LABEL = "Start run";
+export declare const RUN_START_HOLD_LABEL = "Hold";
+/** The gate's own question, quoted verbatim rather than paraphrased. */
+export declare const RUN_START_QUESTION = "Approve phase 0 and start this run? Approving creates an armed goal the harness will keep driving.";
+/** What each offered label means, quoted from the gate's own option descriptions. */
+export declare const RUN_START_OPTION_MEANING: string;
+/**
+ * The recorded decision, when this call carries one.
+ *
+ * ⚠ A `Hold` IS NOT AN APPROVAL and is not printed as one. The test is the same VALUE test the server makes
+ * (`run-start.ts::isRunStartApproval` — the approving label, not the mere presence of a decision line), so
+ * the sheet can never describe a hold as an approval.
+ */
+export declare function decisionLine(answer: string | null): string | null;

package/lib/client/spec-sheet.d.ts

@@ -0,0 +1,103 @@
+/**
+ * THE RUN-START SPEC SHEET — the document beside the question it decides.
+ *
+ * THE DEFECT THIS ANSWERS. The owner asked for a run spec, the plugin scaffolded one and raised the
+ * `run-start` gate — "start this run or hold?" — and NOBODY WAS SHOWN THE DOCUMENT:
+ * *"the card ui for accepting the spec appeared, but i was never shown the spec before that so how could i
+ * approve if i havent seen it"*. The gate was decidable before it was readable.
+ *
+ * ⚠ WHERE THIS RENDERS, AND WHY NOT IN `conversation.approval.detail`. That seat was the first candidate —
+ * its catalog summary reads "Optional detail for the Tool call correlated with an approval request" — and it
+ * is the WRONG one, for a reason that is structural rather than stylistic:
+ *
+ *   1. `conversation.composer` is a CHAIN slot: its entries' selectors run in order and the FIRST non-null
+ *      match renders. `ui-approval` claims it with `select: pendingInteraction instanceof PendingApproval`
+ *      and declares `conversation.approval.detail` as its child; `ui-user-questions` claims it with
+ *      `select: pendingInteraction instanceof PendingQuestion` and declares
+ *      `conversation.plan-review.actions` instead. They are two mutually exclusive cells of ONE chain.
+ *   2. The run-start gate is asked through the USER-QUESTIONS channel (`askRunStartDirectly` →
+ *      `channel.ask(...)`, correlated by `wait: { callId: exec.callId }`), so while it is pending the
+ *      pending interaction IS a `PendingQuestion` — the question composer owns the composer, and
+ *      `conversation.approval.detail` is not mounted at all. A sheet registered there would render on the
+ *      one occasion it is not needed and never on the one it is.
+ *   3. `tool.call.toolview` keyed by tool name is the seat that exists exactly while THIS tool call is on
+ *      screen, is unclaimed for `recursive_ask` (the harness's own `ask_user_question` IS claimed, which is
+ *      the parallel that matters), and hands the view its own `callId`, the session `cwd` and the frozen
+ *      call block — which is how the `runId` is read out of the call's own arguments.
+ *
+ * WHAT IT SHOWS — AND THE DEFECT THAT CHANGED IT. This seat first showed the ACTUAL bytes of
+ * `.recursive/run/<runId>/00-requirements.md` as RAW TEXT, on the reasoning that verbatim is the honest
+ * thing to print. The honest answer to "is that a preview?" was NO, and the owner was being asked to APPROVE
+ * what they read: *reading `##` headings and pipe-table syntax is not reviewing a spec*. So the default is now
+ * a RENDERED PREVIEW — headings, lists, fenced code and pipe tables drawn as such — and the verbatim text is
+ * one press away behind "View source".
+ *
+ * ⚠ AND THE RAW MODE IS NOT DECORATION. A preview is an INTERPRETATION, and this seat asks a person to
+ * approve a document on the strength of it. The raw view exists so that "the preview is not paraphrasing or
+ * hiding anything" is a claim the reader can CHECK against the bytes rather than one they must take from the
+ * renderer. Its state is carried by `aria-pressed` and repeated in a `role="status"` line that names the mode
+ * on screen, so the mode is announced and not merely coloured.
+ *
+ * ⚠ ONE RENDERER, NOT TWO. The markdown is parsed and drawn by `doc-viewer.tsx` — `parseDoc` and its
+ * `PreviewLines` — the same code path the phase-doc viewer uses. A second markdown renderer in one plugin
+ * would be a second answer to "what does this document say", which is the defect this plugin exists to
+ * refuse. What `parseDoc` could not carry for a real `00-requirements.md` (the task boxes and the gate
+ * readings the template ships) was added THERE, for both readers, rather than forked here.
+ *
+ * WHAT IT STILL REFUSES TO DO. It is READ-ONLY (R9): the sheet has no approve/hold control, because a second
+ * control that looks like the question card's would be a second way to answer one question — the sheet may
+ * change HOW the document is shown, never WHETHER it is approved. And the honesty rule of
+ * `settings-view.ts` is unchanged: when the artifact is still the unfilled template the rendered view says so
+ * loudly and the unfilled marks stay visible AS unfilled (`☐ …` items and `Coverage: FAIL` gates are drawn as
+ * exactly that), so a pretty preview of an empty form can never read as an approvable spec.
+ *
+ * ACCESSIBILITY. The outer element is a `region` named by its own heading (`aria-labelledby`); the document
+ * body is a focusable (`tabIndex=0`) scrolling box with its own `aria-label` and `aria-readonly`, so the
+ * keyboard reaches the text and can scroll it without the decision controls leaving the viewport (the cap is
+ * CSS `max-height` with `overflow-y: auto`). The box is the SAME element in both modes, so toggling never
+ * drops focus. Escape is swallowed deliberately, because on a dialog-ish surface Escape is the key that
+ * dismisses and dismissing this sheet must never be read as a decision; and the one transition it has is none
+ * under `prefers-reduced-motion` (see the `.rec-spec` rules in `styles.ts`). No modal is used: nothing here
+ * needs a focus trap, and a trap would take the keyboard away from the decision controls.
+ */
+import { type ReactNode } from 'react';
+import type { SessionListStateLike, SnapshotSelectorHook, WorkspaceListStateLike } from './contract.ts';
+import { type SpecSheetBlock, type SpecSheetModel } from './spec-sheet-view.ts';
+export { RUN_START_TOOL_NAME, RUN_START_SPEC_FILE, parseRecursiveAskArgs, isRunStartCall, specPath, specSheetModel, decisionLine, UNFILLED_NOTICE, UNFILLED_SHORT, NO_CALL_NOTICE, PREPARING_NOTICE, TRUNCATED_NOTICE, SPEC_DEFAULT_MODE, SPEC_MODE_LABEL, SPEC_MODE_NOTE, SPEC_TOGGLE_LABEL, otherMode, specBodyContent, specViewToggle, } from './spec-sheet-view.ts';
+export type { SpecSheetModel, SpecSheetBlock, SpecFetchState, RecursiveAskArgs, SpecViewMode, SpecViewToggle } from './spec-sheet-view.ts';
+/** The session-standard hooks the seat is given, all optional so the spec can render the sheet alone. */
+export interface SpecSheetProps {
+    /** The owner's call block; `null` when the owner supplied none (a window-truncated caller). */
+    block?: SpecSheetBlock;
+    /** The session workspace root the owner supplied (`ToolCallCommonProps.cwd`). */
+    cwd?: string;
+    useSessions?: SnapshotSelectorHook<SessionListStateLike>;
+    useWorkspaces?: SnapshotSelectorHook<WorkspaceListStateLike>;
+}
+/**
+ * Resolve the workspace root the `/doc` route will accept.
+ *
+ * ⚠ THE ROOT CANNOT BE THE SESSION CWD BY GUESSWORK. The route re-validates whatever root it is handed
+ * against the host's own workspace registry (`live-route.ts`: `resolveRoot(undefined, root)` must return the
+ * same canonical path), so the root used here is the one the live route ITSELF answered with; the workspace
+ * path is the hydration hint every other seat passes, and the owner-supplied `cwd` is the last resort.
+ */
+export declare function resolveSpecRoot(snapshotRoot: string | null | undefined, workspacePath: string, cwd: string): string | null;
+/**
+ * The seat component: renders the spec sheet for ONE `recursive_ask` tool call, and NOTHING for any other.
+ *
+ * Returning `null` is how an unclaimed key behaves, so a `tdd-mode` / `qa-signoff` / `gate-block` ask, or a
+ * preparing call whose arguments have not been dispatched yet, keeps the generic tool row it has today.
+ */
+export declare function RunStartSpecSheet({ block, cwd, useSessions, useWorkspaces }: SpecSheetProps): ReactNode;
+/**
+ * The body, from a MODEL — split out so the spec can drive every state (stub, filled, absent, error, a
+ * recorded Hold, a recorded approval) without a route, a session, or a fetch.
+ *
+ * The MODE is local state and starts at the rendered preview (`SPEC_DEFAULT_MODE`); everything that decides
+ * what the sheet SAYS still comes from the pure model, so a spec can assert the words and the marks without
+ * mounting a component.
+ */
+export declare function RunStartSpecSheetBody({ model }: {
+    model: SpecSheetModel;
+}): ReactNode;

package/lib/client/use-live.d.ts

@@ -1,9 +1,25 @@
 import { type LiveRecursiveState, type LiveScope } from './host-api.ts';
 /** Snapshot shape the board/strip consume (null = not loaded / no recursive root). */
 export type LiveProjectionSnapshot = LiveRecursiveState | null;
+/** Options for {@link useLiveProjection}. */
+export interface LiveProjectionOptions {
+    /**
+     * Skip the route entirely (default true).
+     *
+     * ⚠ THIS EXISTS FOR THE PER-CALL SEATS, NOT THE PANELS. A `tool.call.toolview` entry mounts once per Tool
+     * call in the transcript, so a seat that always subscribed would open one `/state` fetch and one SSE
+     * stream per call row. A row that has nothing to show passes `enabled: false` and asks nothing. The hook
+     * itself stays UNCONDITIONAL at every call site — a conditional hook is the run 13 crash, and the flag is
+     * how a caller keeps the call order fixed while making the request conditional.
+     */
+    enabled?: boolean;
+}
 /**
  * Subscribe to the live route for one scope. Returns the current state. The SSE
  * feed pushes full frames on every fs change; a dropped stream (sleep/error)
  * triggers one refetch so the board never serves a stale fold.
+ *
+ * @param scope - sessionId PRIMARY + cwd fallback hint (host resolves the root).
+ * @param options - `enabled: false` clears the snapshot and never fetches.
  */
-export declare function useLiveProjection(scope: LiveScope): LiveProjectionSnapshot;
+export declare function useLiveProjection(scope: LiveScope, options?: LiveProjectionOptions): LiveProjectionSnapshot;