codsh-bundle 0.6.0 → 0.7.0

package/lib/types/bang.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Running a `!` line in the person's own shell.
+ * @module codsh-bundle/src/bang
+ */
+/** The login shell, falling back to sh. */
+export declare function userShell(): string;

package/lib/types/completion.d.ts

@@ -30,6 +30,17 @@ export type CompletionResult = [completions: string[], substring: string];
  * @returns the score, or undefined when it does not match.
  */
 export declare function fuzzyScore(needle: string, hay: string): number | undefined;
+/**
+ * Rank candidates that contain `typed`, prefix hits first.
+ *
+ * A fragment anywhere in the name is enough to offer it; an exact prefix still
+ * outranks a buried hit, so `/p` keeps `plan` above `compact`.
+ * @param items - the candidates.
+ * @param typed - what was typed, without a leading `/` `$` `@`.
+ * @param nameOf - the name to match against.
+ * @returns matching items, prefix then substring.
+ */
+export declare function rankContains<T>(items: readonly T[], typed: string, nameOf: (item: T) => string): T[];
 /** Drop the cached workspace walk, so a test controls what the next Tab sees. */
 export declare function resetFileIndex(): void;
 /**
@@ -43,3 +54,12 @@ export declare function resetFileIndex(): void;
  * @returns a completer over the word under the cursor.
  */
 export declare function createCompleter(commands: () => readonly CompletableCommand[], cwd: string): (line: string) => CompletionResult;
+/**
+ * Turn `$name` skill gestures into the `/name` tokens dsh injects.
+ *
+ * Only names in `known` are rewritten, so an ordinary `$amount` stays prose.
+ * @param text - the submitted line.
+ * @param known - user-invocable skill names.
+ * @returns the line with known `$name` tokens rewritten as `/name`.
+ */
+export declare function expandSkillGestures(text: string, known: ReadonlySet<string>): string;

package/lib/types/console.d.ts

@@ -56,10 +56,13 @@ export declare class TerminalConsole {
     /** Display columns available for one line, never below {@link MIN_COLUMNS}. */
     get columns(): number;
     /**
-     * Columns content may be laid out for: one less than the width, because the
-     * viewport wraps at that boundary. Markdown layout MUST use this figure — a
-     * table laid out one column wider is refolded by the viewport, and its rows
-     * shear apart.
+     * Columns content may be laid out for.
+     *
+     * One less than the width so a row cannot wrap the terminal, and on a
+     * viewport two less again for the left gutter. Markdown, the live line, and
+     * the chrome MUST use this figure — a box laid out one gutter wider is
+     * truncated with an ellipsis on every row, and a live line that fills the
+     * width wraps into the box beneath it.
      */
     get contentColumns(): number;
     /** Whether the output stream is a terminal. */
@@ -89,6 +92,15 @@ export declare class TerminalConsole {
      * Give the terminal back. Idempotent: every exit path calls it.
      */
     leaveScreen(): void;
+    /**
+     * Hand the real TTY to a child, then take the viewport back.
+     *
+     * Raw mode and the alternate screen both have to go: the shell needs cooked
+     * input and the person's own buffer, the way Claude Code and opencode yield
+     * `!` to sh. SIGINT is swallowed here so Ctrl-C reaches the child.
+     * @param work - runs while this process is not reading the keyboard.
+     */
+    runInForeground<T>(work: () => Promise<T>): Promise<T>;
     /** Whether this surface currently holds its own screen. */
     get owningScreen(): boolean;
     /**
@@ -101,6 +113,11 @@ export declare class TerminalConsole {
      * @param text - the styled line, or the empty string for none.
      */
     setScrollNotice(text: string): void;
+    /**
+     * Float rows over the transcript just above the chrome.
+     * @param rows - the overlay, or empty to clear it.
+     */
+    setOverlay(rows: readonly string[]): void;
     /**
      * Scroll the transcript by a whole viewport.
      * @param direction - -1 for back into history, 1 towards the tail.
@@ -108,6 +125,32 @@ export declare class TerminalConsole {
     scrollPage(direction: -1 | 1): void;
     /** Return to the tail of the transcript. */
     scrollToBottom(): void;
+    /**
+     * Search the owned scrollback.
+     * @param query - the needle.
+     */
+    searchTranscript(query: string): {
+        query: string;
+        hits: number;
+        index: number;
+    } | undefined;
+    /**
+     * Step to another hit of the current query.
+     * @param direction - 1 towards the tail, -1 towards the head.
+     */
+    nextTranscriptHit(direction: 1 | -1): {
+        query: string;
+        hits: number;
+        index: number;
+    } | undefined;
+    /** Close find. Transcript content is untouched. */
+    clearTranscriptSearch(): void;
+    /** Incremental find over the scrollback, absent when find is closed. */
+    get transcriptSearch(): {
+        query: string;
+        hits: number;
+        index: number;
+    } | undefined;
     /** Physical rows currently scrolled out of view; zero means at the tail. */
     get scrolledBy(): number;
     /**
@@ -172,8 +215,14 @@ export declare class TerminalConsole {
      * @param rule - a styled left rule for the whole block, `''` for none.
      * @param label - what the block is, for the readout naming what the pointer
      * is over.
+     * @param enter - child session a click opens instead of folding, when set.
      */
-    appendFold(summary: readonly string[], full: readonly string[], rule?: string, label?: string): void;
+    appendFold(summary: readonly string[], full: readonly string[], rule?: string, label?: string, enter?: string): void;
+    /**
+     * What a click on a view-card does.
+     * @param handler - receives the child session id; omit to restore folding.
+     */
+    setEnter(handler: ((id: string) => void) | undefined): void;
     /**
      * Swap every collapsible block between summary and full form.
      * @returns false when there is nothing to toggle.
@@ -241,6 +290,11 @@ export declare class TerminalConsole {
      * @param handler - receives the raw payload, e.g. `rgb:1e1e/1e1e/2e2e`.
      */
     onBackground(handler: (payload: string) => void): void;
+    /**
+     * Adopt the light- or dark-background hover fill.
+     * @param light - true when OSC 11 named a light color.
+     */
+    setLight(light: boolean): void;
     /**
      * Set the terminal window title.
      * @param title - the title text; control bytes are the terminal's to reject.

package/lib/types/editor.d.ts

@@ -30,6 +30,29 @@ export interface EditorView {
     selected: number;
     /** The token under the cursor, which is what the candidates matched. */
     token: string;
+    /** Reverse history search, absent when not searching. */
+    search?: {
+        query: string;
+        hits: number;
+        index: number;
+    };
+    /**
+     * Known `/command` and `$skill` spans in the buffer, in code points.
+     *
+     * Painted in the box so a finished gesture reads as one, not as prose.
+     */
+    hits: readonly GestureHit[];
+}
+/** A `/command` or `$skill` in the buffer that names something real. */
+export interface GestureHit {
+    /** Buffer line index. */
+    row: number;
+    /** First code point of the token. */
+    start: number;
+    /** Code point after the token. */
+    end: number;
+    /** Which kind of gesture it is. */
+    kind: 'command' | 'skill';
 }
 /** What the caller must do after a key. */
 export type EditorAction = {
@@ -61,6 +84,15 @@ export interface EditorSources {
      * @returns candidates to offer, best first.
      */
     commandArguments?(command: string, typed: string): readonly Candidate[];
+    /**
+     * User-invocable skills for a `$` mention.
+     *
+     * Absent or empty means `$` is ordinary text.
+     */
+    skills?(): readonly {
+        name: string;
+        description: string;
+    }[];
 }
 /** A multi-line prompt editor. */
 export declare class Editor {
@@ -75,6 +107,8 @@ export declare class Editor {
     private browsing;
     /** The buffer set aside while history is being browsed. */
     private stashed;
+    /** Reverse-i-search over {@link history}, absent when the box is typing. */
+    private search;
     constructor(sources: EditorSources);
     /** What to render. */
     get view(): EditorView;
@@ -137,6 +171,13 @@ export declare class Editor {
     private tokenStart;
     /** The token under the cursor. */
     private token;
+    /**
+     * Spans in the buffer that name a registered command or skill.
+     *
+     * `/` only counts at the start of the first line, matching how a command is
+     * submitted. `$` counts as a word anywhere, matching how a skill is invoked.
+     */
+    private gestureHits;
     /**
      * Recompute the candidate list for the token under the cursor.
      *
@@ -178,6 +219,23 @@ export declare class Editor {
     private wordRight;
     /** Drop the word before the cursor. */
     private killWord;
+    /**
+     * Open reverse search over history, stashing the draft.
+     * @returns always `none`.
+     */
+    private openSearch;
+    /**
+     * Keys while reverse-i-search is open.
+     * @param key - the decoded keystroke.
+     * @returns what the caller must do about it.
+     */
+    private handleSearch;
+    /** History entries matching the query, newest first. */
+    private searchHits;
+    /** Put the current hit in the buffer, or the stashed draft when none match. */
+    private applySearch;
+    /** Put the draft that search set aside back in the buffer. */
+    private restoreSearchStash;
     /**
      * Close the menu, or report Escape when there is none to close.
      * @returns `none` when a menu was dismissed, otherwise `escape`.

package/lib/types/inputbox.d.ts

@@ -1,7 +1,7 @@
 /**
  * The input box: a framed, multi-line prompt that wraps long lines, grows with
  * its content, and windows when it grows past its budget — with the completion
- * menu under it.
+ * menu overlaid on the transcript above it.
  *
  * Pure layout. It turns an {@link EditorView} into the rows of the bottom region
  * and says where the terminal cursor belongs, so the drawing code has no opinion
@@ -24,11 +24,23 @@ export interface BoxOptions {
     hint?: string | undefined;
     /** Styles the frame; absent frames dim. A mode announces itself here. */
     accent?: ((text: string) => string) | undefined;
+    /**
+     * Whether the box is in shell mode (`!` at the start of the first line).
+     *
+     * The frame and gutter announce it; the leading `!` is the gutter, not a
+     * second character in the buffer.
+     */
+    shell?: boolean | undefined;
 }
 /** The rows to draw and where the cursor goes among them. */
 export interface BoxLayout {
     /** Rows, top to bottom, each already fitted to the terminal. */
     rows: string[];
+    /**
+     * Completion menu, painted over the transcript just above the box so
+     * opening it cannot grow the chrome or shake the output.
+     */
+    overlay: string[];
     /** Index into {@link rows} where the cursor belongs. */
     cursorRow: number;
     /** Display column of the cursor on that row, from zero. */

package/lib/types/keys.d.ts

@@ -60,6 +60,10 @@ export type Key = {
     kind: 'expand-output';
 } | {
     kind: 'toggle-todos';
+} | {
+    kind: 'history-search';
+} | {
+    kind: 'transcript-search';
 } | {
     kind: 'page';
     direction: -1 | 1;

package/lib/types/prompt.d.ts

@@ -91,6 +91,10 @@ export declare class Prompt {
     private todos;
     /** Whether the todo readout shows every item or only the one in flight. */
     private todosExpanded;
+    /** Incremental find over the transcript, absent when find is closed. */
+    private finding;
+    /** Whether the shortcuts overlay is occupying chrome. */
+    private shortcutsOpen;
     /** The assistant line still arriving, shown above the box. */
     private streaming;
     /** Frame styling for the current mode, e.g. plan mode's accent. */
@@ -145,7 +149,8 @@ export declare class Prompt {
     setFlash(text: string): void;
     /**
      * Set the status row, the region's always-current last line.
-     * @param text - the styled row, or undefined to drop it.
+     * @param text - the full styled row, or undefined to drop it. Truncation is
+     *   applied at paint time so a resize can grow the line back.
      */
     setStatus(text: string | undefined): void;
     /**
@@ -230,6 +235,17 @@ export declare class Prompt {
      * @returns the rows, empty when no list is live.
      */
     private todoRows;
+    /**
+     * Keys while transcript find is open: typing is the query, arrows step,
+     * Escape closes. The transcript is not edited.
+     * @param key - the decoded keystroke.
+     */
+    private onFindKey;
+    /**
+     * The find readout, or undefined when find is closed.
+     * @param columns - display columns available.
+     */
+    private findRow;
     /** Recompose and redraw the bottom region. */
     private render;
 }

package/lib/types/screen.d.ts

@@ -15,6 +15,8 @@
  * that relative erase arithmetic keeps producing.
  * @module codsh-bundle/src/screen
  */
+/** Blank columns to the left of every painted row, so text is not flush to the window. */
+export declare const GUTTER = 2;
 /** Where the cursor belongs within the chrome rows. */
 export interface ChromeCursor {
     row: number;
@@ -28,6 +30,8 @@ export interface HoverBlock {
     lines: number;
     /** Whether it is showing that full form now. */
     expanded: boolean;
+    /** Whether a click opens the named child session rather than folding. */
+    enter?: boolean;
 }
 /** What the screen writes to and measures itself against. */
 export interface ScreenHost {
@@ -64,12 +68,16 @@ export declare class Screen {
     private offset;
     /** What to show while scrolled back, drawn over the viewport's top row. */
     private notice;
+    /** Completion menu painted over the viewport, just above the chrome. */
+    private overlay;
     /** A mouse selection over the transcript, in physical-row coordinates. */
     private selection;
     /** Collapsed blocks in the transcript, in order, with both of their forms. */
     private folds;
     /** The block the pointer rests on, or undefined when it rests on none. */
     private hovered;
+    /** Whether OSC 11 named a light background; the hover fill picks a shade. */
+    private light;
     /**
      * Physical row ranges the blocks occupy, or undefined when they need
      * measuring again.
@@ -82,16 +90,36 @@ export declare class Screen {
     private ranges;
     /** Whether the folds currently show their full form. */
     private expanded;
+    /** Incremental find over the owned scrollback, absent when find is closed. */
+    private find;
     /** The last painted frame, so a repaint only touches rows that changed. */
     private painted;
     /** Width the current frame was painted at, to detect a resize. */
     private paintedColumns;
     private active;
+    /** Opens a child session when a view-card is clicked. */
+    private enterHandler;
     constructor(host: ScreenHost);
+    /**
+     * What a click on a view-card does.
+     * @param handler - receives the child session id; omit to restore folding.
+     */
+    setEnter(handler: ((id: string) => void) | undefined): void;
     /** Whether the alternate screen is currently held. */
     get entered(): boolean;
+    /**
+     * Adopt the light- or dark-background hover fill.
+     * @param light - true when OSC 11 named a light color.
+     */
+    setLight(light: boolean): void;
     /** Physical rows scrolled up out of view; zero means the tail is showing. */
     get scrolledBy(): number;
+    /** Incremental find over the scrollback, absent when find is closed. */
+    get transcriptSearch(): {
+        query: string;
+        hits: number;
+        index: number;
+    } | undefined;
     /** Take the alternate screen and start reporting the mouse. */
     enter(): void;
     /**
@@ -119,8 +147,9 @@ export declare class Screen {
      * @param full - the expanded lines, already styled.
      * @param rule - a styled left rule for the whole block, `''` for none.
      * @param label - what the block is, for the hover readout that names it.
+     * @param enter - child session a click opens instead of folding, when set.
      */
-    appendFold(summary: readonly string[], full: readonly string[], rule?: string, label?: string): void;
+    appendFold(summary: readonly string[], full: readonly string[], rule?: string, label?: string, enter?: string): void;
     /**
      * Turn the last `count` appended lines into a collapsible block after the
      * fact.
@@ -206,6 +235,14 @@ export declare class Screen {
      * @param text - the styled notice, already fitted.
      */
     setScrollNotice(text: string): void;
+    /**
+     * Float rows over the viewport just above the chrome.
+     *
+     * The chrome's height does not change, so opening a completion menu cannot
+     * shake the transcript. Empty clears the layer.
+     * @param rows - the overlay, top to bottom.
+     */
+    setOverlay(rows: readonly string[]): void;
     /**
      * Scroll the transcript.
      * @param delta - rows to move; negative scrolls back into history.
@@ -218,6 +255,33 @@ export declare class Screen {
     scrollPage(direction: -1 | 1): void;
     /** Jump back to the tail, which is also what a new submission does. */
     scrollToBottom(): void;
+    /**
+     * Search the owned scrollback.
+     *
+     * Hits are physical rows, case-insensitive. A new query starts on the
+     * newest hit so recent output is what find lands on first.
+     * @param query - the needle; empty means no hits yet.
+     * @returns the current find state.
+     */
+    searchTranscript(query: string): {
+        query: string;
+        hits: number;
+        index: number;
+    };
+    /**
+     * Step to another hit of the current query.
+     * @param direction - 1 towards the tail, -1 towards the head.
+     * @returns the current find state, or undefined when find is closed.
+     */
+    nextTranscriptHit(direction: 1 | -1): {
+        query: string;
+        hits: number;
+        index: number;
+    } | undefined;
+    /** Close find. Transcript content is untouched. */
+    clearTranscriptSearch(): void;
+    /** Scroll so the current hit is in the viewport, then paint. */
+    private revealFindHit;
     /**
      * Drop the transcript, keeping the chrome.
      *
@@ -278,6 +342,8 @@ export declare class Screen {
      * way dragging past an edge keeps selecting, instead of refusing it.
      * @returns the position, or undefined when it misses the content.
      */
+    /** Whether a terminal row sits on the floating completion layer. */
+    private coversOverlay;
     private locate;
     /** Rows the transcript viewport occupies. */
     private viewportHeight;

package/lib/types/selector.d.ts

@@ -27,6 +27,8 @@ export interface SelectSpec {
     multi?: boolean;
     /** Label for a trailing "type your own" row; absent offers none. */
     custom?: string;
+    /** Whether typing filters the list instead of digits/shortcuts settling. */
+    filterable?: boolean;
 }
 /** How one selection ended. */
 export type SelectOutcome = {
@@ -47,11 +49,14 @@ export type SelectorStep = {
 export declare class Selector {
     private readonly spec;
     private selected;
+    private query;
     private readonly checked;
     constructor(spec: SelectSpec);
+    /** Original option indices currently shown, in order. */
+    private matching;
     /** How many rows the widget offers, the custom row included. */
     private get count();
-    /** Whether a row index is the custom "type your own" row. */
+    /** Whether a visible row index is the custom "type your own" row. */
     private isCustom;
     /**
      * Apply one key.
@@ -66,11 +71,17 @@ export declare class Selector {
      */
     private typed;
     /**
-     * Settle on a row.
-     * @param index - the row accepted.
+     * Settle on a visible row.
+     * @param index - the visible row accepted.
      * @returns the settled step.
      */
     private accept;
+    /**
+     * Settle on an original option index.
+     * @param original - the option's index in the spec.
+     * @returns the settled step.
+     */
+    private acceptOriginal;
     /**
      * Render the widget.
      * @param theme - styling for the marker, shortcuts, and details.

package/lib/types/ship.d.ts

@@ -1,15 +1,16 @@
 /**
  * The `/ship` prompt: a canned workflow that takes a one-sentence requirement
- * from idea to shipped, verified code — a research-grounded interview, a
- * confirmed spec (gate 1), an approved plan (gate 2), then autonomous landing
- * until the spec's acceptance criteria pass.
+ * from idea to shipped, verified code — a grill-me interview (design tree,
+ * frontier rounds), then automatic to-spec (gate 1), automatic to-tickets
+ * (gate 2), then autonomous TDD landing until the spec's acceptance criteria
+ * pass.
  *
  * The spec FILE is the workflow's memory, not the conversation: the approved
- * plan is written into it, its Status line names the phase, its checkboxes
+ * tickets are written into it, its Status line names the phase, its checkboxes
  * are the progress, and a bare /ship offers to resume whatever it finds
  * unfinished. Conversations get interrupted, compacted, and cleared; the file
  * survives all three, which is what makes the landing reliable rather than
  * merely well-intentioned.
  */
 /** The `/ship` prompt body; `$ARGUMENTS` is the typed one-sentence requirement. */
-export declare const SHIP_PROMPT = "Run the /ship workflow: take the one-sentence requirement below from idea to shipped, verified code in this repository. The requirement, exactly as typed:\n\n<idea>\n$ARGUMENTS\n</idea>\n\nIf the idea between the <idea> tags is empty, that is not an error. First look for unfinished work: scan the repository's spec directory (docs/specs/, or the repo's own design-document convention) for a spec whose Status line is not `shipped` \u2014 a bare /ship most likely means \"carry on\", so offer through ask_user_question to resume that spec from the phase its Status names, with everything below applying from that phase onward. Only when there is nothing to resume, ask for the one-sentence requirement with ask_user_question and use the answer as the idea. Images accompanying the command \u2014 [Image #N] tokens, <pasted-image> context, attached image blocks \u2014 are part of the requirement: a mockup or a screenshot is requirements material, so read it and cite what it shows in the interview.\n\nPhase 1 \u2014 grounded interview. Research before you ask: read the repository layout, the docs, and the code paths the idea touches, so every question is informed by what actually exists. Then interrogate the idea with ask_user_question, one focused question per call, never a batch. Cover, as far as they are genuinely open: who this is for and what success looks like, scope and explicit non-goals, constraints (compatibility, performance, security, dependencies), edge cases and failure behavior, and how the result should be verified. Prefer concrete options grounded in what you found over open-ended prompts. Do not ask what inspection can answer \u2014 where code lives or how current behavior works is yours to find out. Stop when answers stop changing the design; do not pad the interview to look thorough.\n\nPhase 2 \u2014 the spec (gate 1). Write the agreed design to a spec file inside the repository. Follow the repo's existing convention for design documents if one exists (a specs, rfcs, or ADR directory); otherwise create docs/specs/<kebab-case-slug>.md. The spec must stand alone for a reader without this conversation: the one-sentence requirement, background, each interview decision with its reason, scope and non-goals, constraints, edge cases, and a numbered list of acceptance criteria where every criterion names the exact command that proves it and the output that counts as passing \u2014 the final phase runs those commands verbatim, so a criterion without a command is not finished. Give the file a `Status:` line (interviewing, confirmed, planned, landing, shipped) and keep it current at every phase change: it is what lets an interrupted /ship resume instead of starting over. Present the spec file path and a compact summary through ask_user_question and get an explicit yes. If the answer amends or rejects it, update the file and ask again. Do not proceed on silence or a vague reply.\n\nPhase 3 \u2014 the plan (gate 2). Only after the spec is confirmed, produce an implementation plan: ordered milestones with the files each touches, the tests each milestone adds or changes, which acceptance criterion each milestone satisfies, and the commands that prove the whole thing (build, typecheck, test). Present the plan through ask_user_question and get an explicit yes; fold rejections back in and present again. Once approved, write the plan into the spec file as a `## Plan` section with one checkbox per milestone \u2014 an approved plan lives on disk, not in a conversation that can be compacted or lost. Then, still before any implementation code, establish the ground: check the working tree is clean (uncommitted unrelated changes are the user's to decide about \u2014 ask), and run the plan's proof commands once, recording the baseline in the spec. A baseline that is already red changes what \"green\" will mean, so surface it here rather than discovering it under your own diff. Write no implementation code before this gate passes, and do not use todo_write before it either \u2014 it tracks landing, not the interview.\n\nPhase 4 \u2014 landing. After gate 2, work autonomously; return to the user only for a genuine blocker that contradicts the spec, never for routine decisions. Either way the spec file \u2014 not this conversation \u2014 is the working memory: re-read it before starting each milestone, tick the milestone's checkbox and update Status as you go, and commit after each milestone turns green \u2014 small commits are the progress that survives a crash and the history a reviewer can walk. Choose the mechanism by the approved plan's size. If it has at most three milestones and you expect the whole change to fit comfortably in this session's context, implement in-session: track the milestones with todo_write, and for each one implement, run the tests, fix until green, then commit before moving on. If it is larger \u2014 four or more substantially independent milestones, or work you expect to exceed what one session can hold \u2014 the user running /ship is their explicit request for a fresh-agent Ralph loop: call the ralph tool once, with an objective that names the spec file path as the single source of truth, instructs each round to read the spec from disk (plan, checkboxes, baseline), pick the first unchecked milestone, implement and test it, then commit and tick its checkbox, and defines completion as every acceptance criterion in the spec passing. Bound the loop: budget about three rounds per milestone, and instruct it to stop and report rather than continue past two consecutive rounds that tick nothing.\n\nPhase 5 \u2014 done means verified. The workflow ends only when every acceptance criterion passes with you actually running its named command and reading the real output. After a Ralph loop returns, run every proof command again yourself \u2014 the loop's word is a report, not a verification. Never report a result you did not run, and never weaken a criterion to make it pass; if one cannot be met, say so plainly and why. When a decision changes mid-flight, update the spec file first so the file on disk stays the truth. Set Status to shipped only after that final run, and close with an honest report listing each criterion, the command that proved it, and what it printed \u2014 plus anything left open.\n\nIf the session is in plan mode, the plan-mode rules win: nothing here authorizes writes while it is active. Tell the user this workflow needs to write the spec file and ask them to leave plan mode before continuing past the interview.";
+export declare const SHIP_PROMPT = "Run the /ship workflow: take the one-sentence requirement below from idea to shipped, verified code in this repository. The requirement, exactly as typed:\n\n<idea>\n$ARGUMENTS\n</idea>\n\nIf the idea between the <idea> tags is empty, that is not an error. First look for unfinished work: scan the repository's spec directory (docs/specs/, or the repo's own design-document convention) for a spec whose Status line is not `shipped` \u2014 a bare /ship most likely means \"carry on\", so offer through ask_user_question to resume that spec from the phase its Status names, with everything below applying from that phase onward. Only when there is nothing to resume, ask for the one-sentence requirement with ask_user_question and use the answer as the idea. Images accompanying the command \u2014 [Image #N] tokens, <pasted-image> context, attached image blocks \u2014 are part of the requirement: a mockup or a screenshot is requirements material, so read it and cite what it shows in the interview.\n\nPhase 1 \u2014 grill-me. Research before you ask: read the repository layout, CONTEXT.md if it exists, the docs, ADRs, and the code paths the idea touches. Finding facts is your job, never the user's \u2014 where code lives or how current behavior works is yours to find out; do not ask anything inspection can answer. Then map the idea as a design tree: every decision branches into the decisions that hang off it. Work the tree in rounds. The frontier is every decision whose prerequisites are already settled \u2014 the questions you can ask now without guessing at answers you have not heard yet. Each round, put the whole frontier into a single ask_user_question call (the tool accepts a list of questions; do not serialize independent frontier questions across separate calls). For each question: a short title, a body grounded in what you found, concrete options rather than an open prompt, and your recommended answer as the first option with a description that says so. Then wait for that call to return before the next round. A question whose answer depends on another still open in this round belongs to a later round. Each round of answers reshapes the tree \u2014 settled decisions push the frontier outward. The session is done when the frontier is empty: every branch visited, nothing left silently assumed. Confirm shared understanding through ask_user_question before writing the spec. Do not pad the interview to look thorough, and do not act on the design until that confirmation.\n\nPhase 2 \u2014 automatic to-spec (gate 1). Do not interview further \u2014 synthesize what the grill already settled and what the codebase already is. Write the spec to a file inside the repository. Follow the repo's existing convention for design documents if one exists (a specs, rfcs, or ADR directory); otherwise create docs/specs/<kebab-case-slug>.md. Use the project's domain glossary throughout, and respect ADRs in the area you are touching. The spec must stand alone for a reader without this conversation, with these sections in order: a `Status:` line (interviewing, confirmed, planned, landing, shipped) kept current at every phase change; the one-sentence requirement; Problem Statement (from the user's perspective); Solution (from the user's perspective); each grill decision with its reason; User Stories (numbered, \"As an <actor>, I want a <feature>, so that <benefit>\", covering the feature); Implementation Decisions (modules, interfaces, architecture, contracts \u2014 no file paths or code snippets unless a prototype encoded a decision more precisely than prose); Testing Decisions (what a good test is here: external behavior at public seams, not internals; the seams this spec will be tested at, preferring existing ones; prior art in the repo); Out of Scope; and a numbered list of acceptance criteria where every criterion names the exact command that proves it and the output that counts as passing \u2014 the final phase runs those commands verbatim, so a criterion without a command is not finished. Record the proposed seams in Testing Decisions; the fewer across the codebase, the better \u2014 the ideal number is one. Present the spec file path and a compact summary through ask_user_question and get an explicit yes. If the answer amends or rejects it, update the file and ask again. Do not proceed on silence or a vague reply.\n\nPhase 3 \u2014 automatic to-tickets (gate 2). Only after the spec is confirmed, and without another interview, break the spec into tracer-bullet tickets: each a narrow but complete vertical slice through every layer it needs (not a horizontal slice of one layer), demoable or verifiable on its own, sized to fit a single fresh context window. Give each ticket its blocking edges \u2014 the other tickets that must complete before it can start. Prefactoring that makes the change easy comes first. A wide refactor (one mechanical change whose blast radius fans across the codebase) is the exception: sequence it expand\u2013contract, not as a fake tracer bullet. Present the breakdown through ask_user_question as a numbered list (title, blocked by, what it delivers) and get an explicit yes; fold rejections back in and present again. Once approved, write the tickets into the spec file as a `## Plan` section with one checkbox per ticket \u2014 an approved plan lives on disk, not in a conversation that can be compacted or lost. Each checkbox names the ticket, what it delivers, and which tickets block it. Then, still before any implementation code, establish the ground: check the working tree is clean (uncommitted unrelated changes are the user's to decide about \u2014 ask), and run the spec's proof commands once, recording the baseline in the spec. A baseline that is already red changes what \"green\" will mean, so surface it here rather than discovering it under your own diff. Write no implementation code before this gate passes, and do not use todo_write before it either \u2014 it tracks landing, not the grill.\n\nPhase 4 \u2014 automatic landing. After gate 2, work autonomously; return to the user only for a genuine blocker that contradicts the spec, never for routine decisions. Either way the spec file \u2014 not this conversation \u2014 is the working memory: re-read it before starting each ticket, tick the ticket's checkbox and update Status as you go, and commit after each ticket turns green \u2014 small commits are the progress that survives a crash and the history a reviewer can walk. Implement test-first at the seams the spec recorded: red before green, one seam and one test and one minimal implementation per cycle, through the public interface, never internals. Do not write a test at an unconfirmed seam. Do not bulk-write tests then bulk-implement \u2014 vertical slices, matching the tickets. Run typecheck and the focused tests each cycle; run the full suite the spec named once at the end of the ticket. Choose the mechanism by the approved plan's size. If it has at most three tickets and you expect the whole change to fit comfortably in this session's context, implement in-session: track the tickets with todo_write, and for each one red-green, run the tests, fix until green, then commit before moving on. If it is larger \u2014 four or more substantially independent tickets, or work you expect to exceed what one session can hold \u2014 the user running /ship is their explicit request for a fresh-agent Ralph loop: call the ralph tool once, with an objective that names the spec file path as the single source of truth, instructs each round to read the spec from disk (plan, checkboxes, baseline, seams), pick the first unchecked ticket whose blockers are ticked, implement it test-first at those seams, then commit and tick its checkbox, and defines completion as every acceptance criterion in the spec passing. Bound the loop: budget about three rounds per ticket, and instruct it to stop and report rather than continue past two consecutive rounds that tick nothing.\n\nPhase 5 \u2014 done means verified. The workflow ends only when every acceptance criterion passes with you actually running its named command and reading the real output. After a Ralph loop returns, run every proof command again yourself \u2014 the loop's word is a report, not a verification. Never report a result you did not run, and never weaken a criterion to make it pass; if one cannot be met, say so plainly and why. When a decision changes mid-flight, update the spec file first so the file on disk stays the truth. Set Status to shipped only after that final run, and close with an honest report listing each criterion, the command that proved it, and what it printed \u2014 plus anything left open.\n\nIf the session is in plan mode, the plan-mode rules win: nothing here authorizes writes while it is active. Tell the user this workflow needs to write the spec file and ask them to leave plan mode before continuing past the interview.";

package/lib/types/spinner.d.ts

@@ -43,6 +43,8 @@ export declare class Spinner {
     constructor(surface: LiveSurface, theme: Theme, label: SpinnerLabel, 
     /** Injected so tests advance time without waiting for it. */
     now?: () => number);
+    /** Current verb, updated as tools fire so the line names what is in flight. */
+    private activity;
     /** Whether the indicator is running. */
     get running(): boolean;
     /**
@@ -58,6 +60,11 @@ export declare class Spinner {
     pause(): void;
     /** Stop the indicator: the turn is over, and the next one starts at zero. */
     stop(): void;
+    /**
+     * Name what is in flight. The next tick (or this one, if running) shows it.
+     * @param verb - e.g. `Reading`, `Running`. Empty restores the default verb.
+     */
+    setActivity(verb: string): void;
     /** Paint the current frame. */
     private draw;
 }

package/lib/types/status.d.ts

@@ -78,10 +78,11 @@ export declare function gitBranch(cwd: string): Promise<string | undefined>;
  * a fresh session reads as short rather than as broken.
  * @param facts - what to report.
  * @param theme - styling for the segments.
- * @param columns - display columns available; a longer line is cut, never wrapped.
- * @returns the line, unstyled when the theme is plain.
- */
-export declare function statusLine(facts: StatusFacts, theme: Theme, columns: number): string;
+   * @param columns - display columns available; a longer line is cut, never
+   *   wrapped. Omit to keep the full line, so a later paint can re-fit it.
+   * @returns the line, unstyled when the theme is plain.
+   */
+export declare function statusLine(facts: StatusFacts, theme: Theme, columns?: number): string;
 /**
  * Render the fuller readout `/status` answers with.
  *

package/lib/types/transcript.d.ts

@@ -68,6 +68,17 @@ export declare const FOLD_LABELS: {
     readonly thinking: "thinking";
     readonly answer: "answer";
 };
+/**
+ * The child session a continuable subagent result names, when the card can
+ * open that session.
+ *
+ * Continuable starts return `started subagent <id>` (and a JSON form with the
+ * same id). One-shot background jobs name a job, not a session, and are not a
+ * view.
+ * @param text - the tool result's visible text.
+ * @returns the child session id, or undefined when this result is not a view.
+ */
+export declare function childSessionId(text: string): string | undefined;
 /** A finished answer longer than this many rendered lines becomes a fold. */
 export declare const ANSWER_FOLD_LINES = 24;
 /** How many of its head lines a collapsed answer keeps visible. */
@@ -111,6 +122,8 @@ export declare class Transcript {
     private label;
     /** The left rule the block {@link render} just returned belongs to. */
     private rule;
+    /** Child session a click on this card should open, when the result names one. */
+    private enter;
     constructor(options: TranscriptOptions, presenters: ToolPresenters);
     /**
      * Shorten an absolute path inside the workspace to a workspace-relative one.
@@ -171,6 +184,14 @@ export declare class Transcript {
      * @returns the label, or `''` when the block has no name of its own.
      */
     takeLabel(): string;
+    /**
+     * The child session the block {@link render} just returned can open.
+     *
+     * A click on that card enters the child's transcript rather than folding
+     * the card. Taken once, like {@link takeFold}.
+     * @returns the child session id, or undefined when the card is not a view.
+     */
+    takeEnter(): string | undefined;
     /**
      * The left rule for the block {@link render} just returned, `''` when the
      * block stands flush.