reasonix 0.14.0 → 0.15.0

package/dist/index.d.ts

@@ -1,20 +1,7 @@
 import { SpawnOptions } from 'node:child_process';
 import { WriteStream } from 'node:fs';
 
-/**
- * Retry layer for DeepSeek API calls.
- *
- * Wraps a `fetch` function so that transient failures (rate limiting, server
- * overload, network blips) don't kill an agent session. We explicitly DO NOT
- * retry:
- *   - 4xx client errors other than 408 / 429 (bad key, bad request, ...)
- *   - aborted requests (user cancelled)
- *   - mid-stream body read errors (retrying costs money AND would desync)
- *
- * Retrying is controlled by attempt count + exponential backoff with jitter.
- * If the server sends a `Retry-After` header we honor it (capped by
- * `maxBackoffMs` so a misconfigured upstream can't park us forever).
- */
+/** No retry on aborts or mid-stream body errors — re-billing the user for desynced output is worse than failing. */
 interface RetryOptions {
     /** Maximum total attempts (including the first). Default 4. */
     maxAttempts?: number;
@@ -69,13 +56,7 @@ interface ChatMessage {
     name?: string;
     tool_call_id?: string;
     tool_calls?: ToolCall[];
-    /**
-     * R1 `reasoning_content` captured from the assistant's thinking turn.
-     * DeepSeek's thinking mode 400s with "reasoning_content in the
-     * thinking mode must be passed back" when a tool-loop continuation
-     * omits it from the preceding assistant message. Round-tripped for
-     * deepseek-reasoner turns with tool_calls; absent for deepseek-chat.
-     */
+    /** Must round-trip in tool-loop continuations — thinking mode 400s without it. */
     reasoning_content?: string | null;
 }
 interface RawUsage {
@@ -97,20 +78,7 @@ interface ChatRequestOptions {
     responseFormat?: {
         type: "json_object" | "text";
     };
-    /**
-     * Explicitly toggle V4 thinking mode. Serialized as
-     * `extra_body.thinking.type = enabled|disabled`. Omit to let the
-     * server default apply (thinking enabled). Mainly used so the loop
-     * can pin the mode per model: `deepseek-chat` → disabled (legacy
-     * non-thinking compat), everything else → enabled.
-     */
     thinking?: "enabled" | "disabled";
-    /**
-     * Per-request reasoning-effort cap. Serialized as the top-level
-     * `reasoning_effort` field. DeepSeek accepts `high` (standard) or
-     * `max` (Agent-class, auto-applied to Claude-Code-style flows per
-     * the V4 docs). Reasonix pins `max` because every turn is agent-like.
-     */
     reasoningEffort?: "high" | "max";
 }
 
@@ -144,13 +112,6 @@ interface StreamChunk {
     finishReason?: string;
     raw: any;
 }
-/**
- * Response shape for DeepSeek's `/user/balance` endpoint. One entry
- * per currency the account is funded in (typically CNY, sometimes
- * USD). `total_balance` is the spendable figure; `granted_balance`
- * counts promotional credits that expire, `topped_up_balance` is
- * what the user paid for and keeps.
- */
 interface BalanceInfo {
     currency: string;
     total_balance: string;
@@ -161,12 +122,6 @@ interface UserBalance {
     is_available: boolean;
     balance_infos: BalanceInfo[];
 }
-/**
- * Response shape for DeepSeek's `/models` endpoint. Mirrors the OpenAI
- * models list shape DeepSeek copied — `id` is the model name to pass to
- * `/chat/completions`, `owned_by` is the provider string (always
- * `"deepseek"` today).
- */
 interface ModelInfo {
     id: string;
     object: "model";
@@ -192,22 +147,11 @@ declare class DeepSeekClient {
     private readonly _fetch;
     constructor(opts?: DeepSeekClientOptions);
     private buildPayload;
-    /**
-     * Fetch the current DeepSeek account balance. Separate endpoint
-     * from chat completions, no billing impact. Returns null on any
-     * network/auth failure so callers can gate the balance display
-     * without a hard error — the rest of the session works regardless.
-     */
+    /** Returns null on failure so callers can degrade — session must keep working without balance UI. */
     getBalance(opts?: {
         signal?: AbortSignal;
     }): Promise<UserBalance | null>;
-    /**
-     * Fetch the model catalog DeepSeek currently exposes. Today this is
-     * `deepseek-chat` (V3) and `deepseek-reasoner` (R1), but querying is
-     * the only way to learn about new ones without a Reasonix release.
-     * Returns null on any network/auth failure so callers can degrade
-     * gracefully — e.g. `/models` falls back to the hardcoded hint.
-     */
+    /** Returns null on failure — callers fall back to a hardcoded model hint. */
     listModels(opts?: {
         signal?: AbortSignal;
     }): Promise<ModelList | null>;
@@ -215,19 +159,7 @@ declare class DeepSeekClient {
     stream(opts: ChatRequestOptions): AsyncGenerator<StreamChunk>;
 }
 
-/**
- * Pillar 2 — R1 Thought Harvesting.
- *
- * Takes the `reasoning_content` emitted by a thinking model (deepseek-reasoner
- * / R1) and extracts a structured plan state by making a cheap secondary call
- * to V3 in JSON mode. The typed state is intended for the orchestrator to
- * branch on — e.g. trigger self-consistency sampling when `uncertainties.length
- * > 2`, or surface the subgoals to the user.
- *
- * Opt-in: loops disable harvesting by default. Failures (bad JSON, API error,
- * empty reasoning) return an empty TypedPlanState — the main turn is never
- * aborted because of a harvest hiccup.
- */
+/** Harvest failures return an empty state — main turn must never abort on a hiccup here. */
 
 interface TypedPlanState {
     subgoals: string[];
@@ -249,19 +181,7 @@ declare function emptyPlanState(): TypedPlanState;
 declare function isPlanStateEmpty(s: TypedPlanState | null | undefined): boolean;
 declare function harvest(reasoningContent: string | null | undefined, client?: DeepSeekClient, options?: HarvestOptions, signal?: AbortSignal): Promise<TypedPlanState>;
 
-/**
- * Self-consistency branching.
- *
- * When enabled, the loop fans out into N parallel samples per turn (varied
- * temperatures), runs Pillar 2 harvest on each, and selects the sample with
- * the fewest flagged uncertainties (ties broken by answer length — a crude
- * Occam prior).
- *
- * The unique opportunity here: because DeepSeek is ~20× cheaper than Claude,
- * running N=3–5 samples per turn is still cheaper than a single Claude call,
- * while the majority-confidence selection tends to dominate single-sample
- * answers on fuzzy multi-step reasoning tasks.
- */
+/** N parallel samples; selector picks fewest uncertainties with shorter-answer tie-break (Occam prior). */
 
 interface BranchSample {
     index: number;
@@ -279,10 +199,7 @@ interface BranchOptions {
     harvestOptions?: HarvestOptions;
     /** Custom selector. Default: min uncertainties, tie-break shortest answer. */
     selector?: BranchSelector;
-    /**
-     * Fires as each sample finishes (main call + harvest both complete).
-     * Useful for progress UI. Not awaited; exceptions are swallowed.
-     */
+    /** Not awaited; exceptions swallowed. Fires when sample's main + harvest both complete. */
     onSampleDone?: (sample: BranchSample) => void;
 }
 interface BranchResult {
@@ -301,53 +218,13 @@ declare function aggregateBranchUsage(samples: readonly BranchSample[]): {
     promptCacheMissTokens: number;
 };
 
-/**
- * Hooks — user-defined automation that fires at well-known points in
- * the agent loop. Mirrors the two-scope layout we use for memory and
- * skills:
- *
- *   - `<project>/.reasonix/settings.json` — committable per-project
- *   - `~/.reasonix/settings.json`         — every session
- *
- * A hook is a shell command. We invoke it with stdin = a JSON
- * payload describing the event, and interpret the exit code:
- *
- *   - `0` — pass; loop continues normally
- *   - `2` — block; for `PreToolUse` / `UserPromptSubmit` the
- *     loop refuses to continue with that step and surfaces the
- *     hook's stderr as the reason. For `PostToolUse` / `Stop` block
- *     is meaningless (the action already happened) — treat as warn.
- *   - anything else — warn; loop continues but stderr is rendered
- *     to the user as an inline notice.
- *
- * stdin JSON shape (one envelope per event):
- *
- *   {
- *     "event":    "PreToolUse" | "PostToolUse" | "UserPromptSubmit" | "Stop",
- *     "cwd":      "<absolute project root or process.cwd()>",
- *     "toolName": "<string>",   // tool events only
- *     "toolArgs": <unknown>,    // tool events only — already JSON-decoded
- *     "toolResult": "<string>", // PostToolUse only — same body the model sees
- *     "prompt":   "<string>",   // UserPromptSubmit only
- *     "lastAssistantText": "<string>", // Stop only
- *     "turn":     <number>,     // Stop only
- *   }
- *
- * Hooks are executed in order: project scope first, then global.
- * `Pre*` events stop dispatching at the first block; non-block
- * outcomes accumulate into a single report so the UI can render
- * each warning inline.
- */
+/** Shell-command hooks; project scope first, then global. Exit 0=pass, 2=block on Pre*, other=warn. */
 type HookEvent = "PreToolUse" | "PostToolUse" | "UserPromptSubmit" | "Stop";
 /** All four events as a const array — drives slash listing + validation. */
 declare const HOOK_EVENTS: readonly HookEvent[];
 type HookScope = "project" | "global";
 interface HookConfig {
-    /**
-     * Tool-name pattern (PreToolUse / PostToolUse only). Anchored regex.
-     * Omitted or `"*"` matches every tool. Ignored for prompt / Stop
-     * events (they have no tool name to match against).
-     */
+    /** Anchored regex; `"*"` / omitted = every tool. Pre/PostToolUse only. */
     match?: string;
     /** Shell command to run. Spawned through the platform shell. */
     command: string;
@@ -355,11 +232,7 @@ interface HookConfig {
     description?: string;
     /** Per-hook timeout override in ms. */
     timeout?: number;
-    /**
-     * Working directory for the spawned process. Defaults to:
-     *   - project scope → the project root
-     *   - global scope  → process.cwd()
-     */
+    /** Defaults: project scope → project root; global scope → process.cwd(). */
     cwd?: string;
 }
 /** Shape of `<scope>/.reasonix/settings.json` — only `hooks` for now. */
@@ -377,14 +250,7 @@ interface ResolvedHook extends HookConfig {
 interface HookOutcome {
     /** Which hook fired. */
     hook: ResolvedHook;
-    /**
-     * Decision:
-     *   - `pass`    — exit 0
-     *   - `block`   — exit 2 on a blocking event (otherwise downgraded to `warn`)
-     *   - `warn`    — non-zero exit that is not a successful block
-     *   - `timeout` — the spawn was killed past `timeout`
-     *   - `error`   — could not spawn at all (missing command, etc.)
-     */
+    /** pass=exit 0; block=exit 2 on blocking event; warn=other non-zero; timeout=killed; error=spawn failed. */
     decision: "pass" | "block" | "warn" | "timeout" | "error";
     exitCode: number | null;
     /** Captured stdout (trimmed). May be empty. */
@@ -392,12 +258,7 @@ interface HookOutcome {
     /** Captured stderr (trimmed). The block / warn message comes from here. */
     stderr: string;
     durationMs: number;
-    /**
-     * True when stdout or stderr crossed the per-stream byte cap and was
-     * truncated. The hook still completed; the loop just sees a clipped
-     * view of its output. Surfaced via `formatHookOutcomeMessage` so the
-     * user knows their script wrote more than Reasonix kept.
-     */
+    /** Output crossed the per-stream byte cap; surfaced so user knows we kept less than the script wrote. */
     truncated?: boolean;
 }
 /** Aggregate report for `runHooks`. */
@@ -413,16 +274,7 @@ declare const HOOK_SETTINGS_DIRNAME = ".reasonix";
 declare function globalSettingsPath(homeDirOverride?: string): string;
 /** Where the project settings.json lives for a given root. */
 declare function projectSettingsPath(projectRoot: string): string;
-/**
- * Pull every configured hook out of the project + global settings
- * files, in the order they should fire (project first, global second,
- * within each scope: array order from the file).
- *
- * Returns a flat list — the dispatcher filters by event + match
- * pattern at run time. Loading is cheap (one or two JSON files), so
- * we don't memoize across processes; re-load is allowed via
- * `/hooks reload` and on every fresh App mount.
- */
+/** Project hooks fire before global; within a scope, array order. */
 interface LoadHookSettingsOptions {
     /** Absolute project root, if any. Without it, only global hooks load. */
     projectRoot?: string;
@@ -430,12 +282,7 @@ interface LoadHookSettingsOptions {
     homeDir?: string;
 }
 declare function loadHooks(opts?: LoadHookSettingsOptions): ResolvedHook[];
-/**
- * True if `toolName` matches the hook's `match` field. `"*"` and
- * undefined match everything. Otherwise we anchor the field as a
- * regex — partial-name matches don't fire, so `"file"` would not
- * trigger on `read_file` (use `".*file"` for that).
- */
+/** Match field is an ANCHORED regex — `"file"` won't trigger on `read_file`; use `".*file"`. */
 declare function matchesTool(hook: ResolvedHook, toolName: string): boolean;
 /** Payload envelope passed to hook stdin. */
 interface HookPayload {
@@ -462,27 +309,11 @@ interface HookSpawnResult {
     timedOut: boolean;
     /** True iff spawn() itself failed (ENOENT, EACCES, …). */
     spawnError?: Error;
-    /**
-     * True iff stdout or stderr was capped at the byte limit. The hook
-     * still ran to completion / timeout, but downstream consumers see a
-     * truncated view of its output. Surface this in the UI so a hook
-     * author who relies on long output knows the loop didn't see all
-     * of it.
-     */
+    /** Output capped at byte limit — hook ran to completion but consumers see clipped view. */
     truncated?: boolean;
 }
 type HookSpawner = (input: HookSpawnInput) => Promise<HookSpawnResult>;
-/**
- * Format a hook outcome as a single-line UI string. Used by both the
- * loop (for `warning` events) and the App (for UserPromptSubmit /
- * Stop outcomes). Centralizing keeps the language consistent across
- * scopes.
- */
 declare function formatHookOutcomeMessage(outcome: HookOutcome): string;
-/**
- * Decide the hook's outcome decision from raw spawn results.
- * Pulled out as a pure function so tests can pin the matrix.
- */
 declare function decideOutcome(event: HookEvent, raw: HookSpawnResult): "pass" | "block" | "warn" | "timeout" | "error";
 interface RunHooksOptions {
     payload: HookPayload;
@@ -490,13 +321,7 @@ interface RunHooksOptions {
     /** Test seam — defaults to a real `spawn`. */
     spawner?: HookSpawner;
 }
-/**
- * Filter hooks down to the ones that match `payload.event` (and
- * `payload.toolName`, for tool events), then run them in order.
- * Stops at the first `block` outcome on a blocking event so a
- * gating hook can prevent later hooks from incorrectly seeing a
- * success that wasn't going to happen.
- */
+/** Stops at first `block` so a gating hook can prevent later hooks running against a phantom success. */
 declare function runHooks(opts: RunHooksOptions): Promise<HookReport>;
 
 interface ImmutablePrefixOptions {
@@ -506,54 +331,18 @@ interface ImmutablePrefixOptions {
 }
 declare class ImmutablePrefix {
     readonly system: string;
-    /**
-     * Backing array for `toolSpecs`. Originally `Object.freeze`d at
-     * construction (hence the class name) — but `addTool` now lets the
-     * dashboard register `semantic_search` after a mid-session
-     * `reasonix index` build without forcing the user to restart. Each
-     * add is documented to cost one cache-miss turn (the cached prefix
-     * on DeepSeek's side is keyed by the full tool list); subsequent
-     * turns re-cache against the new shape.
-     */
+    /** Each `addTool` costs one cache-miss turn — DeepSeek's prefix cache is keyed by full tool list. */
     private _toolSpecs;
     readonly fewShots: readonly ChatMessage[];
-    /**
-     * Cached SHA-256 of the prefix payload. Computed lazily on first
-     * `fingerprint` access, invalidated only by mutations that go
-     * through `addTool` (the one legitimate post-construction mutation
-     * path). The TUI reads `fingerprint` on every render — without the
-     * cache, that means a fresh `JSON.stringify` + sha256 over the
-     * full prefix (system prompt + tools list + few-shots, typically
-     * 5-10KB) on every keystroke.
-     *
-     * The lazy-init also acts as a cheap drift guard: if some future
-     * code path mutates `_toolSpecs` directly without going through
-     * `addTool`, `fingerprint` will return the stale cached value
-     * while the actual prefix sent to DeepSeek diverges — the cache
-     * miss would be the first symptom. {@link verifyFingerprint}
-     * lets dev / test code assert the cache matches reality.
-     */
+    /** Invalidated only via `addTool`; bypassing it leaves cache stale → fingerprint diverges from sent prefix. */
     private _fingerprintCache;
     constructor(opts: ImmutablePrefixOptions);
     get toolSpecs(): readonly ToolSpec[];
     toMessages(): ChatMessage[];
     tools(): ToolSpec[];
-    /**
-     * Add a tool spec to the prefix. Returns `true` if added, `false`
-     * if a tool with the same name was already present (callers can
-     * decide whether to ignore or surface the no-op). The model picks
-     * up the new tool on the next turn after the cache busts once.
-     */
     addTool(spec: ToolSpec): boolean;
     get fingerprint(): string;
-    /**
-     * Recompute the fingerprint from scratch and assert it matches the
-     * cached value. Returns the freshly-computed hash on success; throws
-     * with a diff if the cache drifted, which always indicates a bug —
-     * either a non-`addTool` mutation path was added, or `addTool`
-     * forgot to invalidate the cache. Dev / test only; the live loop
-     * doesn't call this on the hot path.
-     */
+    /** Dev/test only — throws on cache drift, which always means a non-`addTool` mutation slipped in. */
     verifyFingerprint(): string;
     private computeFingerprint;
 }
@@ -561,13 +350,7 @@ declare class AppendOnlyLog {
     private _entries;
     append(message: ChatMessage): void;
     extend(messages: ChatMessage[]): void;
-    /**
-     * Bulk-replace entries. Intentionally named to be hard to reach for —
-     * this is the one mutation path that breaks the log's append-only
-     * spirit, reserved for compaction flows (`/compact`) and recovery
-     * where the caller has consciously decided to drop old history. Any
-     * other use is almost certainly wrong; append() is what you want.
-     */
+    /** The one append-only-breaking path — reserved for `/compact` + recovery. Use `append()` otherwise. */
     compactInPlace(replacement: ChatMessage[]): void;
     get entries(): readonly ChatMessage[];
     toMessages(): ChatMessage[];
@@ -580,33 +363,9 @@ declare class VolatileScratch {
     reset(): void;
 }
 
-/**
- * Predicate the breaker consults to decide whether a call mutates state.
- * Mutating calls clear the recent-args buffer: re-reading a file after
- * `edit_file` shouldn't count as "saw the same args before" — the file
- * legitimately changed. Wire this from the caller using whatever source
- * of truth is appropriate (e.g. the ToolRegistry's `readOnly` /
- * `readOnlyCheck` flags). When undefined, every call is tracked the
- * old way — preserves the original behavior for callers that don't
- * thread a registry through.
- */
+/** Mutating calls clear prior read-only entries so a post-edit re-read isn't flagged as repeat. */
 type IsMutating = (call: ToolCall) => boolean;
-/**
- * Call-storm breaker.
- *
- * Detects (tool, args) tuples repeating within a sliding window and suppresses
- * the offending call. Surfaces a synthetic tool_result advising the model to
- * change strategy on its next turn.
- *
- * Buffer entries are tagged read-only vs mutating. When a mutating call
- * runs, the breaker drops prior read-only entries — a re-read of the
- * same path after `edit_file` is fresh, not a repeat. Mutating calls
- * still count among themselves, so a model looping on identical
- * `edit_file` invocations still trips on the threshold.
- *
- * Without an `isMutating` predicate everything is tracked the same way
- * (back-compat for callers that don't thread a registry through).
- */
+/** Tracks (name, args) repeats; mutating calls clear prior read-only entries while still counting amongst themselves. */
 declare class StormBreaker {
     private readonly windowSize;
     private readonly threshold;
@@ -620,16 +379,7 @@ declare class StormBreaker {
     reset(): void;
 }
 
-/**
- * Schema flattening for DeepSeek tool calls.
- *
- * DeepSeek loses arguments on schemas that are deep (>2 levels of nesting) or
- * wide (>10 leaf parameters). This module transforms such schemas into a
- * dot-notation flat schema and re-nests the model's arguments before dispatch.
- *
- * Example:
- *   { user: { profile: { name, age } } }   ⇄   "user.profile.name", "user.profile.age"
- */
+/** DeepSeek drops args on schemas >2 levels deep or >10 leaves; flatten to dot-paths and re-nest after dispatch. */
 
 interface FlattenDecision {
     shouldFlatten: boolean;
@@ -640,14 +390,7 @@ declare function analyzeSchema(schema: JSONSchema | undefined): FlattenDecision;
 declare function flattenSchema(schema: JSONSchema): JSONSchema;
 declare function nestArguments(flatArgs: Record<string, unknown>): Record<string, unknown>;
 
-/**
- * Truncation recovery for tool-call argument JSON cut off mid-structure
- * (typically when the model hits max_tokens before finishing the JSON object).
- *
- * Strategy is purely local: balance braces, close strings, fill missing values
- * with `null`. We deliberately do NOT make a continuation API call here — that
- * decision belongs to the loop, which knows about budgets.
- */
+/** Local-only repair (balance braces, close strings, fill nulls); continuation calls belong to the loop, which owns budgets. */
 interface TruncationRepairResult {
     repaired: string;
     changed: boolean;
@@ -655,14 +398,7 @@ interface TruncationRepairResult {
 }
 declare function repairTruncatedJson(input: string): TruncationRepairResult;
 
-/**
- * Scavenge tool calls leaked into reasoning_content.
- *
- * R1 sometimes emits tool-call JSON inside <think>…</think> and then forgets
- * to surface it in `tool_calls`. This pass extracts plausible calls and
- * proposes them to the loop, which decides whether to merge them with the
- * declared calls.
- */
+/** R1 sometimes emits tool-call JSON inside reasoning_content and forgets `tool_calls`; recover those calls. */
 
 interface ScavengeOptions {
     /** Names of tools the model may legitimately call. Other names are ignored. */
@@ -676,17 +412,7 @@ interface ScavengeResult {
 }
 declare function scavengeToolCalls(reasoningContent: string | null | undefined, opts: ScavengeOptions): ScavengeResult;
 
-/**
- * Pillar 3 — Tool-Call Repair pipeline.
- *
- * Order of passes per turn:
- *   1. scavenge       — recover tool calls leaked into <think>
- *   2. truncation     — close any half-emitted argument JSON
- *   3. storm breaker  — drop call-storm repeats
- *
- * Schema flattening is applied during loop construction (it changes what we
- * advertise to the model), not per-turn.
- */
+/** Pass order: scavenge → truncation → storm. Schema flatten runs at loop construction, not per-turn. */
 
 interface RepairReport {
     scavenged: number;
@@ -699,26 +425,14 @@ interface ToolCallRepairOptions {
     stormWindow?: number;
     stormThreshold?: number;
     maxScavenge?: number;
-    /**
-     * Optional predicate the storm breaker consults to identify state-
-     * changing calls — those clear the sliding window so a post-edit
-     * verify-read isn't mistaken for a repeat. Production callers wire
-     * this off the ToolRegistry's `readOnly` / `readOnlyCheck` flags;
-     * tests that don't supply it keep the original behavior.
-     */
+    /** Mutating calls clear the storm window so a post-edit verify-read isn't seen as a repeat. */
     isMutating?: IsMutating;
 }
 declare class ToolCallRepair {
     private readonly storm;
     private readonly opts;
     constructor(opts: ToolCallRepairOptions);
-    /**
-     * Drop the StormBreaker's sliding window of recent (name, args)
-     * signatures. Called at the start of every user turn — a fresh user
-     * message is a new intent, so carrying old repetition state into it
-     * would turn a valid "try again with different input" flow into a
-     * false-positive block.
-     */
+    /** Called at start of every user turn — fresh intent shouldn't inherit old repetition state. */
     resetStorm(): void;
     process(declaredCalls: ToolCall[], reasoningContent: string | null, content?: string | null): {
         calls: ToolCall[];
@@ -742,11 +456,6 @@ interface TurnStats {
 interface SessionSummary {
     turns: number;
     totalCostUsd: number;
-    /**
-     * Input-side (prompt) cost aggregated across the session. Split
-     * from totalCostUsd so the panel can render "cost $X (in $Y · out
-     * $Z)" — users asked for visibility into where the spend lands.
-     */
     totalInputCostUsd: number;
     /** Output-side (completion) cost aggregated across the session. */
     totalOutputCostUsd: number;
@@ -755,19 +464,8 @@ interface SessionSummary {
     /** @deprecated. Same as claudeEquivalentUsd — synthetic ratio, not a real measurement. */
     savingsVsClaudePct: number;
     cacheHitRatio: number;
-    /**
-     * Most recent turn's prompt-token count. Used by the TUI's context
-     * gauge: we can't know the next call's cost without making it, but
-     * the last turn's prompt tokens is the floor (next call is last
-     * prompt + user delta + any new tool outputs).
-     */
+    /** Floor estimate for next call — actual cost = this + user delta + new tool outputs. */
     lastPromptTokens: number;
-    /**
-     * Most recent turn's USD cost. Complements `totalCostUsd` so the TUI
-     * can render "this turn: $X · session: $Y" — users asked for a
-     * per-turn signal so a mid-session jump from flash to pro is
-     * immediately visible, not hidden inside the session aggregate.
-     */
     lastTurnCostUsd: number;
 }
 declare class SessionStats {
@@ -782,14 +480,6 @@ declare class SessionStats {
     summary(): SessionSummary;
 }
 
-/**
- * Per-call context a tool `fn` can optionally consume. Today the only
- * field is `signal`, plumbed through so long-running tools (MCP calls,
- * HTTP requests) can abort when the user presses Esc. Omitted fields
- * stay optional — tools written against the pre-0.4.9 signature keep
- * working; they just ignore cancellation, which is fine for fast
- * local work where "await finishes" happens before the next tick anyway.
- */
 interface ToolCallContext {
     signal?: AbortSignal;
 }
@@ -797,74 +487,29 @@ interface ToolDefinition<A = any, R = any> {
     name: string;
     description?: string;
     parameters?: JSONSchema;
-    /**
-     * Marks a tool as read-only: safe to invoke during plan mode. `true`
-     * for tools that only observe (read_file, list_directory, search, web
-     * fetch/search). Leave undefined / `false` for anything that can write,
-     * execute, or mutate state.
-     *
-     * The registry enforces this at dispatch: non-readonly tools called
-     * while `planMode` is on return a refusal string the model can
-     * learn from, instead of actually running.
-     */
+    /** Safe in plan mode — registry refuses non-readonly calls when `planMode` is on. */
     readOnly?: boolean;
-    /**
-     * Dynamic read-only check for tools whose safety depends on arguments
-     * — `run_command` with an allowlisted argv is safe, `run_command
-     * rm -rf` isn't. Called with the parsed arguments; `true` means "treat
-     * as read-only for plan mode". Takes precedence over `readOnly` when
-     * both are set.
-     */
+    /** Per-args check; takes precedence over `readOnly`. e.g. `run_command` + allowlisted argv. */
     readOnlyCheck?: (args: A) => boolean;
     fn: (args: A, ctx?: ToolCallContext) => R | Promise<R>;
 }
 interface ToolRegistryOptions {
-    /**
-     * Auto-flatten schemas that exceed depth/width thresholds before sending
-     * them to the model. Re-nests arguments transparently on dispatch.
-     * Default: true. Pass false to opt out.
-     */
+    /** Auto-flatten + re-nest at dispatch; default true. */
     autoFlatten?: boolean;
 }
-/**
- * Callback form for `setToolInterceptor` — receives the tool name and
- * already-parsed arguments; returns a string to short-circuit dispatch
- * (the returned value becomes the tool result the model sees), or
- * `null` / `undefined` to fall through to the registered tool fn.
- *
- * Used by `reasonix code`'s edit-mode gate: `edit_file` / `write_file`
- * are intercepted in "review" mode (queued into pendingEdits, returning
- * "queued for /apply") or handled inline in "auto" mode (snapshot +
- * apply, then surface an undo banner). Other tools pass through.
- */
+/** String return short-circuits dispatch; null/undefined falls through to the tool fn. */
 type ToolInterceptor = (name: string, args: Record<string, unknown>) => string | null | undefined | Promise<string | null | undefined>;
 declare class ToolRegistry {
     private readonly _tools;
     private readonly _autoFlatten;
-    /**
-     * When true, `dispatch` refuses any tool whose `readOnly` flag isn't
-     * set (and whose `readOnlyCheck` doesn't pass on the specific args).
-     * Drives `reasonix code`'s Plan Mode — the model can still explore
-     * via read tools but its writes and non-allowlisted shell calls are
-     * bounced until the user approves a submitted plan.
-     */
     private _planMode;
-    /**
-     * Optional hook run after arg parsing but before tool.fn. Lets the TUI
-     * reroute specific tool calls (e.g. edit_file in review mode) without
-     * modifying the tool definitions themselves.
-     */
     private _interceptor;
     constructor(opts?: ToolRegistryOptions);
     /** Enable / disable plan-mode enforcement at dispatch. */
     setPlanMode(on: boolean): void;
     /** True when the registry is currently refusing non-readonly calls. */
     get planMode(): boolean;
-    /**
-     * Install or clear the dispatch interceptor. At most one interceptor
-     * is active at a time — calling twice replaces the previous. Pass
-     * `null` to remove.
-     */
+    /** At most one interceptor active; calling twice replaces. */
     setToolInterceptor(fn: ToolInterceptor | null): void;
     register<A, R>(def: ToolDefinition<A, R>): this;
     has(name: string): boolean;
@@ -881,29 +526,11 @@ declare class ToolRegistry {
 }
 
 type EventRole = "assistant_delta" | "assistant_final"
-/**
- * Emitted as `tool_calls[].function.arguments` streams in. A tool
- * call with a large arguments payload produces no `content` or
- * `reasoning_content` bytes — this is the only signal the UI has
- * that the stream is alive during that window.
- */
+/** Only liveness signal during a large-args tool call (no content/reasoning bytes). */
  | "tool_call_delta"
-/**
- * Yielded immediately before a tool is dispatched. Lets the TUI put
- * up a "▸ tool<X> running…" spinner while the tool's Promise is
- * pending — otherwise the UI looks frozen whenever a tool call
- * takes more than a few hundred ms (a big `filesystem_edit_file`
- * is a typical trigger).
- */
+/** Pre-dispatch ping so the TUI can show a spinner during long tool awaits. */
  | "tool_start" | "tool" | "done" | "error" | "warning"
-/**
- * Transient "what's happening right now" indicator. Emitted during
- * silent phases — between a tool result and the next iteration's
- * first streaming byte, and right before harvest — so the TUI can
- * show a spinner with explanatory text instead of looking frozen.
- * The UI clears it on the next primary event (assistant_delta,
- * tool_start, tool, assistant_final, error).
- */
+/** Transient indicator for silent phases; UI clears on next primary event. */
  | "status" | "branch_start" | "branch_progress" | "branch_done";
 interface BranchSummary {
     budget: number;
@@ -924,26 +551,13 @@ interface LoopEvent {
     content: string;
     reasoningDelta?: string;
     toolName?: string;
-    /**
-     * Raw JSON-string arguments the model sent for a tool call (role === "tool").
-     * Populated so transcripts can persist *why* a tool was called, not just
-     * what it returned. Needed by `reasonix diff` to explain divergences.
-     */
+    /** Raw args JSON — needed by `reasonix diff` to explain why a tool was called. */
     toolArgs?: string;
     /** Cumulative arguments-string length for `role === "tool_call_delta"`. */
     toolCallArgsChars?: number;
-    /**
-     * Zero-based index of the tool call this delta belongs to. Surfaces
-     * multi-tool turns: on a response emitting 4 write_file calls the UI
-     * can show "building call 3/?" instead of a context-free spinner.
-     */
+    /** Zero-based index of the tool call this delta belongs to (multi-tool progress). */
     toolCallIndex?: number;
-    /**
-     * Count of prior tool calls (this turn) whose arguments have finished
-     * streaming into valid JSON. Not all ready calls have been dispatched
-     * yet — dispatch still happens post-stream — but the user gets "2
-     * ready" progress feedback while later calls keep streaming.
-     */
+    /** Count of tool calls whose args have parsed as valid JSON (UI progress, not dispatch gate). */
     toolCallReadyCount?: number;
     stats?: TurnStats;
     planState?: TypedPlanState;
@@ -951,15 +565,7 @@ interface LoopEvent {
     branch?: BranchSummary;
     branchProgress?: BranchProgress;
     error?: string;
-    /**
-     * True on `assistant_final` events emitted by the no-tools fallback
-     * when the loop hit its budget, was aborted, or tripped the
-     * token-context guard. Consumers that act on assistant text (notably
-     * the code-mode edit applier) MUST treat these as display-only —
-     * the model is "wrapping up," not proposing new work. Applying
-     * SEARCH/REPLACE blocks found in a forced summary caused the
-     * "analysis became edits" bug in v0.4.1 and earlier.
-     */
+    /** Display-only — code-mode applier MUST skip SEARCH/REPLACE in forced-summary text. */
     forcedSummary?: boolean;
 }
 interface CacheFirstLoopOptions {
@@ -969,94 +575,27 @@ interface CacheFirstLoopOptions {
     model?: string;
     maxToolIters?: number;
     stream?: boolean;
-    /**
-     * Pillar 2 — structured harvesting of R1 reasoning into a typed plan state.
-     * Pass `true` for defaults or an options object. Off by default (adds a
-     * cheap but non-zero V3 call per turn).
-     */
     harvest?: boolean | HarvestOptions;
-    /**
-     * Self-consistency branching. Pass a number for just a budget (e.g. 3) or
-     * a full `BranchOptions` object. Disables streaming for the branched turn
-     * because all samples must complete before selection. Auto-enables harvest
-     * since the default selector scores samples by plan-state uncertainty.
-     */
+    /** Branching disables streaming (need all samples) and force-enables harvest (selector input). */
     branch?: number | BranchOptions;
-    /**
-     * Reasoning-effort cap. See {@link ReconfigurableOptions} — default
-     * `max` for Reasonix (agent-class use per DeepSeek V4 docs).
-     */
     reasoningEffort?: "high" | "max";
-    /**
-     * Master switch for auto-escalation paths. See ReconfigurableOptions
-     * — defaults to `true` (current behavior); the `flash` and `pro`
-     * presets pass `false` to lock the running session to one model.
-     */
     autoEscalate?: boolean;
-    /**
-     * Soft USD budget for the entire session. When set, the loop:
-     *   - Emits a one-shot warning event when cumulative cost crosses 80%
-     *   - Refuses to run the next turn once cumulative cost ≥ budget,
-     *     yielding an error that explains how to bump or clear the cap
-     *
-     * Default `undefined` — no cap, no warnings. Reasonix is the cost-
-     * focused agent; the budget is opt-in so users new to the tool
-     * don't get blocked at $0.50 wondering what happened, but heavy /
-     * headless / CI users have a clean circuit breaker available.
-     */
+    /** Soft USD cap — warns at 80%, refuses next turn at 100%. Opt-in (default no cap). */
     budgetUsd?: number;
-    /**
-     * Session name. When set, the loop pre-loads the session's prior messages
-     * into its log on construction, and appends every new log entry to
-     * `~/.reasonix/sessions/<name>.jsonl` so the next run can resume.
-     */
     session?: string;
-    /**
-     * Resolved hook list — loaded from `<project>/.reasonix/settings.json`
-     * + `~/.reasonix/settings.json` by the CLI before constructing the loop.
-     * The loop dispatches `PreToolUse` and `PostToolUse` events itself; the
-     * CLI handles `UserPromptSubmit` and `Stop` since they live at the App
-     * boundary. Empty / unset → no hooks fire (the runtime cost of an empty
-     * filter is one ms). See `src/hooks.ts` for the full contract.
-     */
+    /** PreToolUse + PostToolUse only — UserPromptSubmit / Stop live at the App boundary. */
     hooks?: ResolvedHook[];
-    /**
-     * `cwd` reported to hooks via the stdin payload. Defaults to `process.cwd()`.
-     * `reasonix code` overrides this to the sandbox root so a hook that does
-     * `cd $REASONIX_CWD` lands in the project, not in the user's shell home.
-     */
+    /** `cwd` reported to hooks; `reasonix code` sets this to the sandbox root, not shell home. */
     hookCwd?: string;
 }
-/**
- * Pillar 1 — Cache-First Loop.
- *
- * - prefix is immutable (cache target)
- * - log is append-only (preserves prior-turn prefix)
- * - scratch is per-turn volatile (never sent upstream)
- *
- * Yields a stream of events so a TUI can render progressively.
- */
 interface ReconfigurableOptions {
     model?: string;
     harvest?: boolean | HarvestOptions;
     branch?: number | BranchOptions;
     stream?: boolean;
-    /**
-     * Reasoning-effort cap sent per turn (V4 thinking mode only;
-     * deepseek-chat ignores it). Reasonix pins `max` by default because
-     * DeepSeek's V4 docs flag Claude-Code-style agent loops as the
-     * canonical `max` use case. `/effort high` lets a user step down
-     * mid-session for cheaper, faster turns on simple tasks.
-     */
+    /** V4 thinking mode only; deepseek-chat ignores. */
     reasoningEffort?: "high" | "max";
-    /**
-     * Master switch for the auto-escalation paths — both the
-     * `<<<NEEDS_PRO>>>` marker scavenge and the failure-count threshold.
-     * `true` (default) preserves the original "flash baseline, jump to
-     * pro when struggling" behavior. `false` locks the active turn to
-     * whatever `model` is set to — used by the `flash` and `pro` presets
-     * which want a hard model commitment.
-     */
+    /** `false` pins to `model` — kills both NEEDS_PRO marker scavenge and failure-count threshold. */
     autoEscalate?: boolean;
 }
 declare class CacheFirstLoop {
@@ -1074,156 +613,28 @@ declare class CacheFirstLoop {
     harvestOptions: HarvestOptions;
     branchEnabled: boolean;
     branchOptions: BranchOptions;
-    /** See ReconfigurableOptions — mutable so `/effort` can flip mid-session. */
     reasoningEffort: "high" | "max";
-    /**
-     * Auto-escalation toggle. `true` lets the loop self-promote to pro
-     * mid-turn (NEEDS_PRO marker / failure threshold); `false` keeps it
-     * pinned to `model`. Mutable so the dashboard's preset switcher can
-     * flip it live alongside `model`.
-     */
     autoEscalate: boolean;
-    /**
-     * Soft USD budget — see {@link CacheFirstLoopOptions.budgetUsd}.
-     * Mutable so `/budget` slash can set / change / clear it mid-session.
-     * `null` (the default) disables all budget checks.
-     */
     budgetUsd: number | null;
-    /**
-     * Set the first time a turn crosses 80% of the budget so the warning
-     * doesn't repeat every turn afterwards. Cleared by `setBudget` (any
-     * change re-arms the warning, including raising the cap above the
-     * current spend).
-     */
+    /** One-shot 80% warning latch — cleared by setBudget so a bump re-arms at the new boundary. */
     private _budgetWarned;
     sessionName: string | null;
-    /**
-     * Hook list, mutable so `/hooks reload` can swap it without
-     * reconstructing the loop. Default empty — the filter cost on a
-     * tool call is one array length check.
-     */
     hooks: ResolvedHook[];
-    /**
-     * `cwd` reported to hook stdin. Mutable so `/cwd` can switch the
-     * working directory mid-session — the App keeps it in sync with
-     * the same currentRootDir that drives tool re-registration.
-     */
     hookCwd: string;
     /** Number of messages that were pre-loaded from the session file. */
     readonly resumedMessageCount: number;
     private _turn;
     private _streamPreference;
-    /**
-     * AbortController per active turn. Threaded through the DeepSeek
-     * HTTP calls AND every tool dispatch so Esc actually cancels the
-     * in-flight network/subprocess work — not "we'll get to it after
-     * the current call finishes." Re-created at the start of each
-     * `step()` (the prior turn's signal has already fired).
-     */
+    /** Threaded through HTTP + every tool dispatch so Esc cancels in-flight work, not after. */
     private _turnAbort;
-    /**
-     * "Next turn should run on pro, regardless of this.model." Set by the
-     * `/pro` slash command; consumed at the next turn's start (flipping
-     * `_escalateThisTurn` on and self-clearing) so it's a fire-and-forget
-     * single-turn upgrade. Survives across multiple slash inputs so
-     * typing `/pro` and then hesitating a while before submitting a real
-     * message still applies.
-     */
     private _proArmedForNextTurn;
-    /**
-     * Active for the current turn only — true means every model call
-     * this turn uses pro instead of `this.model`. Turned on by EITHER
-     * the pro-armed consumption OR the mid-turn auto-escalation
-     * threshold (see `_turnFailureCount`). Cleared at turn end.
-     */
     private _escalateThisTurn;
-    /**
-     * Visible-failure count for the current turn. Incremented by tool
-     * dispatch paths when a result matches a known "flash is struggling"
-     * shape (SEARCH-not-found errors, scavenge / truncation / storm
-     * repair fires). Once it hits {@link FAILURE_ESCALATION_THRESHOLD},
-     * the remainder of the turn's model calls auto-upgrade to pro so
-     * the user doesn't watch flash retry the same edit 5 times.
-     */
     private _turnFailureCount;
-    /**
-     * Per-type breakdown of failure signals counted toward the turn's
-     * auto-escalation threshold. Surfaced in the warning when the
-     * threshold trips so the user sees what kind of trouble flash
-     * actually hit ("3× search-mismatch, 2× truncated") rather than
-     * just a bare count. Reset alongside _turnFailureCount.
-     */
     private _turnFailureTypes;
     constructor(opts: CacheFirstLoopOptions);
-    /**
-     * Shrink the log by re-truncating oversized tool results to a tighter
-     * token cap, and persist the result back to disk so the next launch
-     * doesn't re-inherit a fat session file. Returns a summary the TUI
-     * can display.
-     *
-     * The cap is in DeepSeek V3 tokens (not chars) — so CJK text gets
-     * capped at the same effective context footprint as English instead
-     * of slipping past a char cap at 2× the token cost. Default 4000
-     * tokens, matching the token-aware dispatch cap from 0.5.2.
-     *
-     * Only tool-role messages are touched (same rationale as
-     * {@link healLoadedMessages}). User and assistant messages carry
-     * authored intent we can't mechanically shrink without losing
-     * meaning.
-     */
-    /**
-     * Conservative args-only shrink fired after every tool response —
-     * strictly about ONE thing: stop oversized `edit_file` / `write_file`
-     * arguments from riding every future turn's prompt.
-     *
-     * Why this is worth doing AUTOMATICALLY (not just on /compact):
-     * Each tool-call arguments string sticks in the log verbatim. On a
-     * coding session with ~10 edits, that's 20-40K tokens of stale
-     * SEARCH/REPLACE text riding along on every turn. Even at a 98.9%
-     * cache hit rate the input cost still adds up linearly (cache-hit
-     * price × tokens × turns). Compacting IMMEDIATELY after the tool
-     * responds means the next turn's prompt is already smaller — the
-     * shrink is a one-time write that saves every future prompt.
-     *
-     * Threshold rationale: 800 tokens ≈ 3 KB. A typical 20-line edit's
-     * args land well under that; massive rewrites (whole-file content,
-     * 100+ line refactors) land above and get the compaction. Small
-     * edits stay byte-verbatim so nothing common-case changes.
-     *
-     * Safety: we ONLY shrink args whose tool has ALREADY responded.
-     * Structurally that's every call in `log.toMessages()` at this
-     * point — the current turn's assistant/tool pairing is by
-     * construction closed by the time we get here (append happens
-     * AFTER dispatch). The in-flight assistant message being built
-     * lives in scratch, not the log, so this pass can't touch it.
-     *
-     * Model impact: the model may occasionally want to reference the
-     * exact SEARCH text of a prior edit — it then reads the file
-     * directly (which shows current state) or looks at the preceding
-     * assistant text (which has its plan). Losing the stale args is a
-     * net win: one extra read_file vs. dragging N KB of stale text
-     * through every subsequent turn.
-     */
+    /** Shrink huge edit_file/write_file args post-dispatch — tool result already explains. */
     private compactToolCallArgsAfterResponse;
-    /**
-     * Fired at the END of a turn (just before `done` is yielded). Shrinks
-     * every tool RESULT in the log that exceeds {@link TURN_END_RESULT_CAP_TOKENS}
-     * to a tight cap so the NEXT turn's prompt doesn't re-pay for big
-     * reads or searches done earlier. Unlike the reactive 40/80%
-     * thresholds which react to context pressure, this runs unconditionally
-     * — the win is preventive: each turn's big outputs get trimmed before
-     * they ride into the next prompt. Saves compounding cost on long
-     * sessions.
-     *
-     * Why compact the JUST-finished turn's results too (not just older
-     * turns)? The same-turn iters already consumed the raw content to
-     * make their decisions — the log is only carried forward for future
-     * prompts. And "let me re-read the file" is vastly cheaper than
-     * "carry this 12KB result in every future turn's prompt forever."
-     *
-     * Safe by construction: args-compact for THIS turn already ran
-     * inside `compactToolCallArgsAfterResponse`; this pass is orthogonal.
-     */
+    /** Preventive end-of-turn shrink — trim big results before they ride into the next prompt. */
     private autoCompactToolResultsOnTurnEnd;
     compact(maxTokens?: number): {
         healedCount: number;
@@ -1231,40 +642,14 @@ declare class CacheFirstLoop {
         charsSaved: number;
     };
     appendAndPersist(message: ChatMessage): void;
-    /**
-     * Start a fresh conversation WITHOUT exiting. Drops every message
-     * in the in-memory log AND rewrites the session file to empty so
-     * a resume won't re-hydrate the old turns. Unlike `/forget`, which
-     * deletes the session entirely, this keeps the session name and
-     * config intact — it's the "new chat" button.
-     *
-     * The immutable prefix (system prompt + tool specs) is preserved
-     * — that's the cache-first invariant, not part of the conversation.
-     * Returns the number of messages dropped so the UI can show it.
-     */
+    /** "New chat" — drops messages but keeps session + immutable prefix (cache-first invariant). */
     clearLog(): {
         dropped: number;
     };
-    /**
-     * Reconfigure model/harvest/branch/stream mid-session. The loop's log,
-     * scratch, and stats are preserved — only the per-turn behavior changes.
-     * Used by the TUI's slash commands and by library callers who want to
-     * flip a knob between turns.
-     */
     configure(opts: ReconfigurableOptions): void;
-    /**
-     * Set / change / clear the soft USD budget. `null` (or any non-
-     * positive number) disables the cap entirely. Re-arms the 80%
-     * warning so a user who bumps the cap mid-session sees a fresh
-     * threshold message at the new boundary.
-     */
+    /** `null` disables the cap; any change re-arms the 80% warning. */
     setBudget(usd: number | null): void;
-    /**
-     * Arm pro for the next turn (consumed at turn start). Called by
-     * `/pro`. Idempotent — repeated calls stay armed, `disarmPro()`
-     * clears. Separate from `/preset max` which persistently switches
-     * this.model; armed state is strictly single-turn.
-     */
+    /** Single-turn upgrade consumed at next step() — distinct from `/preset max` (persistent). */
     armProForNextTurn(): void;
     /** Cancel `/pro` arming before the next turn starts. */
     disarmPro(): void;
@@ -1272,131 +657,31 @@ declare class CacheFirstLoop {
     get proArmed(): boolean;
     /** UI surface — true while the current turn is running on pro (armed or auto-escalated). */
     get escalatedThisTurn(): boolean;
-    /**
-     * Model the current model call should use. Defaults to `this.model`;
-     * upgrades to {@link ESCALATION_MODEL} when the turn is armed for
-     * pro (via `/pro`) or has hit the failure-escalation threshold.
-     * Same thinking + effort policy applies regardless — pro defaults
-     * to thinking=enabled and effort=max, which the current turn wanted
-     * anyway when flash was struggling.
-     */
     private modelForCurrentCall;
-    /**
-     * Parse the escalation marker out of the model's leading content.
-     * Returns `{ matched: true, reason? }` for both bare and reason-
-     * carrying forms. Only the FIRST line matters — the model is
-     * instructed to emit the marker as the first output token if at
-     * all. Matches anywhere else in the text are normal content
-     * references (e.g. the user asked about the marker itself).
-     */
+    /** Anchored to lead — mid-text matches are normal content (user asking about the marker). */
     private parseEscalationMarker;
     /** Convenience boolean — same gate the streaming path used to call. */
     private isEscalationRequest;
-    /**
-     * Could `buf` STILL plausibly become the full marker as more chunks
-     * arrive? Drives the streaming buffer's flush decision: while this
-     * is true we keep accumulating; once it's false (or the buffer
-     * exceeds the byte limit) we flush so the user isn't staring at a
-     * delayed display for arbitrary content that just happens to start
-     * with `<`.
-     */
+    /** Drives streaming flush — while plausibly partial, keep accumulating; else flush. */
     private looksLikePartialEscalationMarker;
-    /**
-     * Check whether a tool result string looks like a "flash struggled"
-     * signal and, if so, increment the turn's failure counter. Escalates
-     * the REST of the current turn to pro once the threshold is hit.
-     * Idempotent after escalation — further failures don't re-escalate,
-     * but the turn is already on pro so it doesn't matter.
-     *
-     * Return: `true` when this call tipped the turn into escalation
-     * mode (so the loop can surface a one-time warning to the user).
-     */
+    /** Returns true ONLY on the tipping call — caller surfaces a one-shot warning. */
     private noteToolFailureSignal;
-    /**
-     * Render `_turnFailureTypes` as a comma-separated breakdown like
-     * "2× search-mismatch, 1× truncated" for the auto-escalation
-     * warning. Empty if no types have been recorded yet (defensive —
-     * the warning sites only call this after a bump).
-     */
     private formatFailureBreakdown;
     private buildMessages;
-    /**
-     * Signal the currently-running {@link step} to stop **now**. Cancels
-     * the in-flight network request (DeepSeek HTTP/SSE) AND any tool call
-     * currently dispatching (MCP `notifications/cancelled` + promise
-     * reject). The loop itself also sees `signal.aborted` at each
-     * iteration boundary and exits quickly instead of looping again.
-     * Called by the TUI on Esc.
-     */
     abort(): void;
-    /**
-     * Drop everything in the log after (and including) the most recent
-     * user message. Used by `/retry` so the caller can re-send that
-     * message with a fresh turn instead of layering another response on
-     * top of the prior exchange. Returns the content of the dropped user
-     * message, or `null` if there isn't one yet.
-     *
-     * Persists by rewriting the session file — otherwise the next
-     * launch would rehydrate the old exchange and `/retry` would seem
-     * to have done nothing.
-     */
+    /** Drop the last user message + everything after; caller re-sends. Persists to session file. */
     retryLastUser(): string | null;
     step(userInput: string): AsyncGenerator<LoopEvent>;
     private forceSummaryAfterIterLimit;
     run(userInput: string, onEvent?: (ev: LoopEvent) => void): Promise<string>;
-    /**
-     * Build an assistant message for the log. The `producingModel` arg is
-     * the model that actually generated this turn (flash, pro, the
-     * forced-summary flash call, `this.model` for synthetics, etc.) —
-     * NOT `this.model`, because escalation + forced-summary can both
-     * route a single turn to a different model.
-     *
-     * The single invariant this encodes: if the producing model is
-     * thinking-mode, `reasoning_content` MUST be present on the
-     * persisted message — even as an empty string. DeepSeek's validator
-     * 400s the NEXT request if any historical thinking-mode assistant
-     * turn is missing it. We used to gate on `reasoning.length > 0`,
-     * which silently dropped the field whenever the stream emitted zero
-     * reasoning deltas or the API returned `reasoning_content: null` —
-     * both legitimate edge cases the 0.5.15/0.5.18 fixes missed.
-     */
+    /** Thinking-mode producer ⇒ reasoning_content MUST be set (even ""), or next call 400s. */
     private assistantMessage;
-    /**
-     * Synthetic assistant message (abort notices, future system injections)
-     * — no real API round trip. Delegates to {@link assistantMessage} with
-     * `this.model` as the stand-in producer, so the same thinking-mode
-     * invariant applies: reasoner sessions get an empty-string
-     * `reasoning_content`; V3 sessions get nothing.
-     */
+    /** Abort notices etc — uses this.model as stand-in producer for the thinking-mode stamp. */
     private syntheticAssistantMessage;
 }
-/**
- * R1 occasionally hallucinates tool-call markup as plain text when the
- * real tool channel has been closed — typically our forced-summary
- * path, where `tools: undefined` is supposed to force prose but isn't
- * always respected. The markup isn't parsed by our tool-call path
- * (the API response's structured `tool_calls` field is empty), so
- * it's just noise in the user's view. Strip known envelope shapes.
- *
- * Exported so tests can exercise it against concrete R1 outputs.
- */
+/** Strip hallucinated tool-call envelopes — `tools: undefined` doesn't always force prose. */
 declare function stripHallucinatedToolMarkup(s: string): string;
-/**
- * Enforce tool_calls ↔ tool pairing across a message log. DeepSeek
- * rejects two shapes at the API boundary:
- *   (a) assistant with tool_calls not followed by matching tool
- *       responses ("insufficient tool messages following tool_calls")
- *   (b) tool message without a preceding assistant.tool_calls with
- *       the matching tool_call_id ("must be a response to a preceding
- *       message with 'tool_calls'")
- *
- * Corrupted session files from earlier builds have hit both. This pass
- * rebuilds the message stream so only well-formed (assistant.tool_calls
- * + all matching responses) groups survive. Plain user/assistant/system
- * messages (no tool_calls) always pass through.
- *
- * Exported so both char-based and token-based heal can compose it.
- */
+/** Drops both unpaired assistant.tool_calls and stray tool messages — DeepSeek 400s on either. */
 declare function fixToolCallPairing(messages: ChatMessage[]): {
     messages: ChatMessage[];
     droppedAssistantCalls: number;
@@ -1407,67 +692,19 @@ declare function healLoadedMessages(messages: ChatMessage[], maxChars: number):
     healedCount: number;
     healedFrom: number;
 };
-/**
- * Token-aware counterpart of {@link healLoadedMessages}. Used at
- * session-load time so resumed sessions come back capped at the same
- * token budget (not char budget) as live tool results — CJK text no
- * longer slips past at 2× the intended token cost when re-hydrated.
- *
- * Still does the same structural pass for tool_calls ↔ tool pairing;
- * that logic is orthogonal to the truncation cap.
- */
+/** Token-cap variant — char cap would let CJK slip past at 2× the intended token cost. */
 declare function healLoadedMessagesByTokens(messages: ChatMessage[], maxTokens: number): {
     messages: ChatMessage[];
     healedCount: number;
     tokensSaved: number;
     charsSaved: number;
 };
-/**
- * Turn raw `DeepSeek NNN: {json}` errors into short actionable hints.
- * Client code throws these verbatim from the HTTP layer (see client.ts);
- * this is the one place the UI text layer reads to decide what the user
- * actually needs to do about it.
- *
- * Covered codes (per DeepSeek's error-code doc):
- *   - 400 + "maximum context length" → context-overflow, point at /forget
- *   - 400 generic → strip the JSON, show inner message
- *   - 401 → API key rejected, point at `reasonix setup`
- *   - 402 → balance depleted, link to top-up page
- *   - 422 → param error, show inner message (usually explains which field)
- *
- * 429/500/502/503/504 are swallowed by retry.ts before they reach here;
- * if they DO reach here (all retries exhausted), the raw string already
- * says "DeepSeek 503: server busy" etc. which is informative enough.
- */
+/** Single text-layer DeepSeek-error formatter — 429/5xx never reach here (retry.ts swallows). */
 declare function formatLoopError(err: Error): string;
 
-/**
- * Expand `@path/to/file` mentions in a user prompt to inline file
- * content.
- *
- * Why: most interactive coding sessions start with "look at X, then
- * change Y". Typing `@src/loop.ts` reads faster and cheaper than
- * "look at src/loop.ts (and the model fires read_file, and we pay for
- * the round trip)" — the model sees the file content from turn 1
- * instead of round-tripping a tool call for it.
- *
- * Shape: the user's text is kept verbatim. Expanded file contents are
- * appended in a "Referenced files" block at the end, each wrapped in
- * `<file path="...">...</file>` so the model can cite them back
- * unambiguously.
- *
- * Safety: paths must resolve inside `rootDir` (no `..` escape, no
- * absolute paths), must exist as a regular file, and must be under
- * `maxBytes`. Missing / too-large / escaping paths get a short note
- * appended instead of content so the user sees why it was skipped.
- */
+/** Expand `@path` mentions inline. Paths must resolve inside rootDir; escapes / oversize get a skip note, not content. */
 /** Caps match tool-result dispatch truncation (0.5.2). */
 declare const DEFAULT_AT_MENTION_MAX_BYTES: number;
-/**
- * Default directory names skipped when listing files for the picker.
- * Matches what most repos gitignore AND keeps the picker off the
- * hottest bloat — `node_modules` alone can be 100k+ entries.
- */
 declare const DEFAULT_PICKER_IGNORE_DIRS: readonly string[];
 interface ListFilesOptions {
     /** Cap the walk once we've collected this many entries. Default 500. */
@@ -1475,23 +712,7 @@ interface ListFilesOptions {
     /** Directory names to skip entirely. Defaults to {@link DEFAULT_PICKER_IGNORE_DIRS}. */
     ignoreDirs?: readonly string[];
 }
-/**
- * Walk `root` recursively and return relative file paths (forward-slash
- * separator, regardless of platform) for the `@` picker.
- *
- * Synchronous on purpose: this runs once at App mount (and on each turn
- * so newly-created files show up) and blocks the render thread for a
- * predictable ~10-50ms on a moderate repo. An async variant would need
- * to coordinate with the Ink render loop; sync fits the rest of the
- * TUI's single-turn-per-tick model cleanly.
- *
- * Skips:
- *   - directories in `ignoreDirs` (default: DEFAULT_PICKER_IGNORE_DIRS)
- *   - any directory whose name starts with `.` (covers `.git`,
- *     `.vscode`, dotfile vendors). Dotfile REGULAR FILES (`.env`,
- *     `.gitignore`, `.prettierrc`) are kept — users reference them.
- *   - entries the walker can't read (permission errors, broken links).
- */
+/** Sync on purpose — fits the TUI's single-turn-per-tick model. Skips dot-DIRS but keeps dotfiles. */
 declare function listFilesSync(root: string, opts?: ListFilesOptions): string[];
 interface FileWithStats {
     /** Relative path with forward-slash separator. */
@@ -1499,46 +720,12 @@ interface FileWithStats {
     /** Modification time (Date.getTime() / ms since epoch). 0 when stat failed. */
     mtimeMs: number;
 }
-/**
- * Same walk as {@link listFilesSync} but also statS each file for
- * modification time. Used by the `@` picker to surface recently-
- * edited files first — matches VS Code Quick Open / similar UX.
- *
- * Stat failures don't throw: the entry is kept with `mtimeMs: 0` so
- * it still appears in the picker (just sinks to the bottom of the
- * recency sort).
- */
+/** Stat failures kept as `mtimeMs: 0` — entry still appears, sinks to bottom of recency sort. */
 declare function listFilesWithStatsSync(root: string, opts?: ListFilesOptions): FileWithStats[];
-/**
- * Async variant of {@link listFilesWithStatsSync}. Same walk semantics
- * (DFS, alphabetical, respects ignore + maxResults), but each
- * directory's entries are stat'd in parallel via `Promise.all`,
- * which slashes wall-clock time on Windows where individual stat
- * syscalls are 3-5x slower than Linux.
- *
- * Use this from the TUI mount path so a 500-file repo doesn't add
- * 200-300ms of synchronous block to first paint. Sync variant is
- * kept for paths where the caller can't `await` (server APIs,
- * test scaffolding).
- */
+/** Parallel stat per directory — Windows stat syscalls are 3-5× slower than Linux. */
 declare function listFilesWithStatsAsync(root: string, opts?: ListFilesOptions): Promise<FileWithStats[]>;
-/**
- * Prefix pattern used by the `@` picker to detect an IN-PROGRESS
- * mention at the END of the input buffer. Captures the partial path
- * (which may be empty — just `@`) so the picker can use it as a
- * substring filter.
- *
- * Distinct from {@link AT_MENTION_PATTERN} (which finds completed
- * mentions anywhere in the text for expansion-at-submit). This one
- * fires on the trailing token only, anchored at end-of-input.
- */
+/** Trailing-token only, anchored at end-of-input — distinct from `AT_MENTION_PATTERN` which scans all. */
 declare const AT_PICKER_PREFIX: RegExp;
-/**
- * Return the picker state for a given input buffer: the partial query
- * (may be empty string — just `@`) and the buffer offset of the `@`
- * character. `null` when the buffer doesn't end in a mention-in-
- * progress.
- */
 declare function detectAtPicker(input: string): {
     query: string;
     atOffset: number;
@@ -1548,42 +735,10 @@ type PickerCandidate = string | FileWithStats;
 interface RankPickerOptions {
     /** Upper bound on returned entries. Default 40. */
     limit?: number;
-    /**
-     * Paths the user or model has touched recently (via tool calls like
-     * `read_file` / `edit_file`). Matching paths get a recency boost so
-     * the picker surfaces "stuff I just looked at" near the top.
-     */
     recentlyUsed?: readonly string[];
 }
-/**
- * Filter and rank candidate files against the picker's partial query.
- *
- * Empty query:
- *   - Sort by "recently used" bucket first (if provided), then mtime
- *     descending (newer first), then path alpha.
- *   - Pure-string input (no mtime data) falls back to alpha since
- *     recency info isn't available.
- *
- * Non-empty query:
- *   - Case-insensitive substring match, with a basename-prefix boost
- *     so `lo` floats `loop.ts`-shaped paths to the top.
- *   - Ties broken first by recently-used membership, then mtime.
- *
- * Back-compat: passes `string[]` through the same logic (mtime = 0,
- * recently-used still honored).
- */
 declare function rankPickerCandidates(files: readonly PickerCandidate[], query: string, limitOrOpts?: number | RankPickerOptions): string[];
-/**
- * Matches `@` at a word boundary (start-of-string or preceded by
- * whitespace) followed by a path-like token. Deliberately rejects `@`
- * embedded in longer words (email addresses, mentions on social sites)
- * by requiring the word boundary.
- *
- * Path charset keeps it to the characters that appear in real repo
- * paths — letters, digits, `_` `-` `.` `/` `\`. Trailing `.` (e.g.
- * `@foo.ts.`) is stripped before lookup so a sentence-terminating
- * period doesn't break the mention.
- */
+/** Word-boundary anchor rejects `@` embedded in emails / social handles; trailing `.` stripped before lookup. */
 declare const AT_MENTION_PATTERN: RegExp;
 interface AtMentionExpansion {
     /** The raw `@path` token as it appeared in the text. */
@@ -1600,10 +755,6 @@ interface AtMentionExpansion {
 interface AtMentionOptions {
     /** Max file size in bytes before a mention is skipped. */
     maxBytes?: number;
-    /**
-     * Optional file-system overrides for tests. Real callers omit these;
-     * the helper falls through to `node:fs`.
-     */
     fs?: {
         exists: (path: string) => boolean;
         isFile: (path: string) => boolean;
@@ -1611,36 +762,12 @@ interface AtMentionOptions {
         read: (path: string) => string;
     };
 }
-/**
- * Expand `@path` mentions in `text`. Returns the (possibly augmented)
- * text plus a per-mention report so the caller can surface expansions
- * in the UI.
- */
 declare function expandAtMentions(text: string, rootDir: string, opts?: AtMentionOptions): {
     text: string;
     expansions: AtMentionExpansion[];
 };
 
-/**
- * Project memory — a user-authored `REASONIX.md` in the project root
- * that gets pinned into the immutable-prefix system prompt.
- *
- * Design notes:
- *
- *   - The file lands in `ImmutablePrefix.system`, so the whole memory
- *     block is hashed into the cache prefix fingerprint. Editing the
- *     file invalidates the prefix; unchanged memory across sessions
- *     keeps the DeepSeek prefix cache warm. That matches Pillar 1 —
- *     memory is a deliberate, stable prefix, not per-turn drift.
- *   - Only one source: the working-root `REASONIX.md`. No parent walk,
- *     no `~/.reasonix/REASONIX.md`, no CLAUDE.md fallback. User-global
- *     memory can come later; for v1 one file == one mental model.
- *   - Truncated at 8 000 chars (≈ 2k tokens). `.gitignore` gets 2 000
- *     because it's a constraint dump; memory gets more headroom because
- *     it's deliberate instructions.
- *   - Opt-out via `REASONIX_MEMORY=off|false|0`. No CLI flag — memory
- *     is a file, `rm REASONIX.md` is the other opt-out.
- */
+/** REASONIX.md pinned into ImmutablePrefix.system; edits invalidate the prefix-cache fingerprint. */
 declare const PROJECT_MEMORY_FILE = "REASONIX.md";
 declare const PROJECT_MEMORY_MAX_CHARS = 8000;
 interface ProjectMemory {
@@ -1653,44 +780,13 @@ interface ProjectMemory {
     /** True iff `originalChars > PROJECT_MEMORY_MAX_CHARS`. */
     truncated: boolean;
 }
-/**
- * Read `REASONIX.md` from `rootDir`. Returns `null` when the file is
- * missing, unreadable, or empty (whitespace-only counts as empty — an
- * empty memory file shouldn't perturb the cache prefix).
- */
+/** Empty / whitespace-only files return null so they don't perturb the cache prefix. */
 declare function readProjectMemory(rootDir: string): ProjectMemory | null;
-/**
- * Resolve whether project memory should be read. Default: on.
- * `REASONIX_MEMORY=off|false|0` turns it off (CI, reproducing issues,
- * intentional offline runs).
- */
 declare function memoryEnabled(): boolean;
-/**
- * Return `basePrompt` with the project's `REASONIX.md` appended as a
- * "Project memory" section. No-op when the file is absent, empty, or
- * memory is disabled via env.
- *
- * The appended block is deterministic — identical input ⇒ identical
- * output — so every session that opens against the same memory file
- * gets the same prefix hash.
- */
+/** Deterministic — same memory file always yields the same prefix hash. */
 declare function applyProjectMemory(basePrompt: string, rootDir: string): string;
 
-/**
- * User memory — `~/.reasonix/memory/` markdown notes pinned into the
- * immutable-prefix system prompt across sessions.
- *
- * Two scopes:
- *   - `global`  → `~/.reasonix/memory/global/`         (cross-project)
- *   - `project` → `~/.reasonix/memory/<hash>/`          (per sandbox root)
- *
- * Each scope has an always-loaded `MEMORY.md` index plus zero-or-more
- * `<name>.md` detail files loaded on demand via `recall_memory`.
- *
- * Distinct from `src/project-memory.ts` (REASONIX.md) in purpose:
- *   REASONIX.md        is committable, team-shared project memory.
- *   ~/.reasonix/memory is user-private memory, never committed.
- */
+/** User-private memory pinned into the immutable prefix; distinct from committable REASONIX.md. */
 declare const USER_MEMORY_DIR = "memory";
 declare const MEMORY_INDEX_FILE = "MEMORY.md";
 /** Cap on the index file content loaded into the prefix, per scope. */
@@ -1719,10 +815,7 @@ interface WriteInput {
     description: string;
     body: string;
 }
-/**
- * Throws on filename injection attempts (`../foo`, `foo/bar`, leading
- * dots, etc.). Allowed: 3-40 chars, alnum + `_` + `-` + interior `.`.
- */
+/** Throws on path-injection (../, /, leading dot). Allowed: 3-40 chars, alnum/_/-, interior `.`. */
 declare function sanitizeMemoryName(raw: string): string;
 /** Stable 16-hex-char hash of an absolute sandbox root path. */
 declare function projectHash(rootDir: string): string;
@@ -1736,10 +829,6 @@ declare class MemoryStore {
     pathFor(scope: MemoryScope, name: string): string;
     /** True iff this store is configured with a project scope available. */
     hasProjectScope(): boolean;
-    /**
-     * Read the `MEMORY.md` index for a scope. Returns post-cap content
-     * (with a truncation marker if clipped), or `null` when absent / empty.
-     */
     loadIndex(scope: MemoryScope): {
         content: string;
         originalChars: number;
@@ -1747,108 +836,36 @@ declare class MemoryStore {
     } | null;
     /** Read one memory file's body (frontmatter stripped). Throws if missing. */
     read(scope: MemoryScope, name: string): MemoryEntry;
-    /**
-     * List every memory in this store. Scans both scopes (skips project
-     * scope if unconfigured). Silently skips malformed files; the index
-     * must stay queryable even if one file is hand-edited into nonsense.
-     */
+    /** Skips malformed files — index stays queryable even if one file is hand-edited into nonsense. */
     list(): MemoryEntry[];
-    /**
-     * Write a new memory (or overwrite existing). Creates the scope dir,
-     * writes the `.md` file, and regenerates `MEMORY.md`. Returns the
-     * absolute path written to.
-     */
     write(input: WriteInput): string;
     /** Delete one memory + its index line. No-op if the file is already gone. */
     delete(scope: MemoryScope, rawName: string): boolean;
-    /**
-     * Rebuild `MEMORY.md` from the `.md` files currently in the scope dir.
-     * Called after every write/delete. Sorted by name for stable prefix
-     * hashing — two stores with the same set of files produce byte-identical
-     * MEMORY.md content, keeping the cache prefix reproducible.
-     */
+    /** Sorted by name — same file set must produce byte-identical MEMORY.md for stable prefix hashing. */
     private regenerateIndex;
 }
-/**
- * Append `MEMORY_GLOBAL` and (optionally) `MEMORY_PROJECT` blocks to
- * `basePrompt`. Omits a block entirely when its index is absent — an
- * empty tag would add bytes to the prefix hash without content.
- * Respects `REASONIX_MEMORY=off` via `memoryEnabled()` from
- * `project-memory.ts`.
- */
+/** Empty index → omit the whole block (otherwise we'd add bytes to the prefix hash for nothing). */
 declare function applyUserMemory(basePrompt: string, opts?: {
     homeDir?: string;
     projectRoot?: string;
 }): string;
-/**
- * Compose every lazy-loaded prefix block in one call: project REASONIX.md,
- * global REASONIX.md (`#g` destination), user memory indexes (global +
- * per-project), and the skills index. Drop-in replacement for
- * `applyProjectMemory` at CLI entry points. Stacking order is stable —
- * the prefix hash only changes when block *content* changes, not when
- * this helper is called a second time with the same filesystem state.
- */
 declare function applyMemoryStack(basePrompt: string, rootDir: string): string;
 
-/**
- * Built-in filesystem tools for `reasonix code`.
- *
- * Why native instead of the official `@modelcontextprotocol/server-filesystem`:
- *   - No subprocess overhead — every call is 50-200 ms cheaper.
- *   - Schema shapes tuned for R1: `edit_file` takes a single
- *     SEARCH/REPLACE string instead of `string="false"`-encoded
- *     JSON arrays, which was the biggest single source of DSML
- *     hallucinations in 0.4.x.
- *   - Sandbox enforcement lives here so Reasonix can reason about
- *     it (tests cover path-traversal, symlink-escape, and the
- *     cwd-outside-root case) rather than trusting an external server.
- *   - No `npx install` / network dependency in `reasonix code`.
- *
- * Tool names + argument shapes intentionally mirror the official
- * filesystem server so R1's muscle memory carries over. The only
- * intentional divergence is `edit_file`, noted above.
- */
+/** Native FS tools — sandbox enforced here, not delegated. `edit_file` takes a single SEARCH/REPLACE string. */
 
 interface FilesystemToolsOptions {
     /** Absolute directory the tools may read/write. Paths outside this are refused. */
     rootDir: string;
-    /**
-     * When `false`, register only read-side tools (read_file, list_directory,
-     * search_files, get_file_info, directory_tree). Useful for read-only
-     * workflows where the model should never mutate the tree. Default: true.
-     */
+    /** false → register only read-side tools. Default true. */
     allowWriting?: boolean;
-    /**
-     * Cap for a single file read, in bytes. Prevents a stray `read_file`
-     * on a multi-GB blob from OOM'ing Node. 2 MB is enough for any realistic
-     * source file (the biggest single-file TypeScript project checked in to
-     * GitHub is ~500 KB); pass higher when working with data files.
-     */
+    /** Per-read byte cap; floor against OOM on a multi-GB blob. */
     maxReadBytes?: number;
-    /**
-     * Cap for total bytes returned from search_files / directory_tree /
-     * grep, so the model can't accidentally pull down the whole tree as
-     * one giant string. 256 KB by default.
-     */
+    /** Cap on total bytes from listing/grep tools — bounds tree-as-one-string accidents. */
     maxListBytes?: number;
 }
 declare function registerFilesystemTools(registry: ToolRegistry, opts: FilesystemToolsOptions): ToolRegistry;
 
-/**
- * `remember` / `forget` / `recall_memory` — tools that let the model
- * read and write the user-memory store across sessions.
- *
- * Scope rules:
- *   - `global`  — always available (no sandbox needed).
- *   - `project` — requires a `projectRoot` on MemoryStore. In chat mode
- *     (no sandbox), the tools still register but a `scope=project` call
- *     returns a structured refusal so the model can try `global` instead.
- *
- * Memory changes are written eagerly but NOT re-loaded into the prefix
- * mid-session (cache invariant). The user notices at `/new` or the next
- * launch — or they can read fresh content via `recall_memory` which
- * always hits disk.
- */
+/** Writes are eager but the prefix is NOT re-loaded mid-session — keeps prompt-cache stable. */
 
 interface MemoryToolsOptions {
     /** Sandbox root for the `project` scope. Omit for chat mode. */
@@ -1858,50 +875,13 @@ interface MemoryToolsOptions {
 }
 declare function registerMemoryTools(registry: ToolRegistry, opts?: MemoryToolsOptions): ToolRegistry;
 
-/**
- * ask_choice — the primitive for "user needs to pick between alternatives".
- *
- * Why it exists: `submit_plan` is for ONE concrete plan the user approves.
- * Models routinely misused it to present A/B/C option menus, leaving the
- * user stuck with an approve/refine/cancel picker that had no way to
- * select a route. `ask_choice` gives branching its own tool so plan
- * mode stays about one actionable thing at a time.
- *
- * Shape mirrors `submit_plan`:
- *   1. Model calls `ask_choice` with a question and 2–4 options.
- *   2. The tool throws `ChoiceRequestedError`; the registry serializes
- *      the payload via `toToolResult`.
- *   3. TUI parses the tagged error, mounts `ChoiceConfirm`, user picks
- *      one option (or types a custom answer via the escape hatch, or
- *      cancels).
- *   4. A synthetic user message feeds the choice back — "user picked
- *      <id>" or "user answered: <text>" — and the loop resumes.
- *
- * Auto-flatten note: the `options` array of objects is exactly the
- * schema shape that DeepSeek V3/R1 is known to drop. `ToolRegistry`
- * auto-flattens and re-nests on dispatch (Pillar 3), so we don't need
- * to hand-flatten here. We still `sanitizeOptions` at runtime because
- * even with flatten-repair, models occasionally emit empty strings or
- * miss fields entirely.
- */
+/** Branching primitive separate from submit_plan; throws ChoiceRequestedError so the TUI can mount a picker and the model stops. */
 
-/**
- * One option in a branching question. `id` is what gets fed back to
- * the model when the user picks; keep it short and stable (A, B, C,
- * or option-1 / option-2 / ...). `summary` is optional extra context
- * the UI shows as a dimmed sub-line under the title.
- */
 interface ChoiceOption {
     id: string;
     title: string;
     summary?: string;
 }
-/**
- * Thrown by `ask_choice`. Carries the branching question plus the
- * options list out to the TUI via the `toToolResult` protocol. The
- * error message tells the model to STOP so it doesn't race past the
- * picker with more tool calls — same pattern as `PlanProposedError`.
- */
 declare class ChoiceRequestedError extends Error {
     readonly question: string;
     readonly options: ChoiceOption[];
@@ -1915,47 +895,17 @@ declare class ChoiceRequestedError extends Error {
     };
 }
 interface ChoiceToolOptions {
-    /**
-     * Side-channel preview fired when the model asks. The tool-result
-     * event also carries the payload; this is the earlier hook for
-     * test harnesses or alternative UIs that don't want to parse JSON.
-     */
     onChoiceRequested?: (question: string, options: ChoiceOption[]) => void;
 }
 declare function registerChoiceTool(registry: ToolRegistry, opts?: ChoiceToolOptions): ToolRegistry;
 
-/**
- * Shared types for Plan Mode. Consumed by plan-errors.ts (error
- * classes carry these as fields) and plan-core.ts (tool registration
- * validates against them). Kept in a separate module so a consumer
- * that only wants the types doesn't pull in either the error classes
- * or the registration machinery.
- */
 type PlanStepRisk = "low" | "med" | "high";
-/**
- * Structured step in a submitted plan. Optional — plans can still be
- * pure markdown. When provided, each step is addressable by `id` so
- * the model can later mark it complete via `mark_step_complete`.
- */
 interface PlanStep {
     id: string;
     title: string;
     action: string;
-    /**
-     * Optional self-reported risk level. Drives the colored dot gutter
-     * in PlanConfirm / PlanCheckpointConfirm: green (low) / yellow
-     * (med) / red (high). High-risk steps are the ones the user should
-     * actually read before approving — everything else is noise.
-     * Omitted when the model didn't categorize (treated as neutral).
-     */
     risk?: PlanStepRisk;
 }
-/**
- * Payload surfaced by `mark_step_complete` via `PlanCheckpointError`.
- * The TUI parses the tool result JSON, pushes a `✓ step` progress row,
- * and mounts the checkpoint picker. `kind` is kept on the payload so
- * consumers that peek at the JSON can dispatch on a stable tag.
- */
 interface StepCompletion {
     kind: "step_completed";
     stepId: string;
@@ -1964,33 +914,13 @@ interface StepCompletion {
     notes?: string;
 }
 
-/**
- * Error classes for Plan Mode tools. Each one implements the
- * `toToolResult` protocol so `ToolRegistry.dispatch` serializes the
- * structured payload into the tool-result JSON — the TUI parses that
- * shape to mount the right picker (approve / checkpoint / revise).
- *
- * Types live in plan-types.ts; registration logic in plan-core.ts.
- * Dependency direction: plan-core → plan-errors → plan-types.
- */
+/** Plan-mode errors carry `toToolResult` so dispatch serializes structured payloads the TUI parses to mount pickers. */
 
-/**
- * Thrown by `submit_plan` when the model has produced a plan for the
- * user to approve. Carries the markdown body, optional structured
- * steps, and an optional one-line summary. The TUI uses all three to
- * render the PlanConfirm picker.
- */
 declare class PlanProposedError extends Error {
     readonly plan: string;
     readonly steps?: PlanStep[];
     readonly summary?: string;
     constructor(plan: string, steps?: PlanStep[], summary?: string);
-    /**
-     * Structured tool-result shape. Consumed by the TUI to extract the
-     * plan without regex-scraping the error message. Optional fields
-     * are omitted from the payload when absent so consumers don't see
-     * `undefined` keys in the JSON.
-     */
     toToolResult(): {
         error: string;
         plan: string;
@@ -1998,13 +928,6 @@ declare class PlanProposedError extends Error {
         summary?: string;
     };
 }
-/**
- * Thrown by `mark_step_complete`. The registry serializes the
- * structured payload via `toToolResult`, the TUI catches the error
- * tag and pauses the loop until the user decides continue / revise /
- * stop. The error message tells the model to stop calling tools so
- * it doesn't race past the picker.
- */
 declare class PlanCheckpointError extends Error {
     readonly stepId: string;
     readonly title?: string;
@@ -2020,19 +943,7 @@ declare class PlanCheckpointError extends Error {
         error: string;
     } & StepCompletion;
 }
-/**
- * Thrown by `revise_plan`. Carries the proposed remaining-step list,
- * a one-sentence reason, and an optional updated summary out to the
- * TUI. Mirrors PlanProposedError / PlanCheckpointError. The picker
- * shows a diff between the current remaining steps and the proposed
- * ones; the user accepts (replaces) or rejects (keeps current).
- *
- * Why a separate tool from submit_plan: revising is surgical (replace
- * the tail of an in-flight plan), submitting is a fresh proposal.
- * Different intent, different UI. Calling submit_plan again mid-
- * execution would reset the whole plan including done steps, which
- * is heavier than usually needed.
- */
+/** Surgical replace of in-flight plan tail; submit_plan would reset done steps. */
 declare class PlanRevisionProposedError extends Error {
     readonly reason: string;
     readonly remainingSteps: PlanStep[];
@@ -2046,195 +957,51 @@ declare class PlanRevisionProposedError extends Error {
     };
 }
 
-/**
- * Plan Mode tool registration. Owns `registerPlanTool` — which wires
- * `submit_plan`, `mark_step_complete`, and `revise_plan` into a
- * ToolRegistry — plus the arg sanitizers these tools share.
- *
- * Structure rationale: the three registrations are parallel in shape
- * (each throws a structured error the TUI renders as a picker), so
- * they're broken out into `registerSubmitPlan` / `registerMarkStep` /
- * `registerRevisePlan` — one per screen of logic rather than one
- * 230-line `registerPlanTool` body. Tool descriptions live at the top
- * as named constants so the function bodies stay readable; the strings
- * themselves are long because they teach the model when to call each
- * tool, which is load-bearing behavior.
- *
- * Dependency direction: plan-core → plan-errors → plan-types.
- */
-
 interface PlanToolOptions {
-    /**
-     * Optional side-channel callback fired when the model submits a plan.
-     * The TUI uses this to preview the plan in real time (the tool-result
-     * event is also emitted; this is just earlier and friendlier to
-     * test harnesses that don't want to parse JSON).
-     */
     onPlanSubmitted?: (plan: string, steps?: PlanStep[]) => void;
-    /**
-     * Optional callback fired when the model marks a step complete via
-     * `mark_step_complete`. Analogous to `onPlanSubmitted` — the tool
-     * event carries the same payload, but this firing point is earlier
-     * and avoids JSON parsing for consumers that don't need it.
-     */
     onStepCompleted?: (update: StepCompletion) => void;
-    /**
-     * Optional preview callback fired when the model proposes a plan
-     * revision via `revise_plan`. Same earlier-than-event timing as
-     * the other on* hooks.
-     */
     onPlanRevisionProposed?: (reason: string, remainingSteps: PlanStep[], summary?: string) => void;
 }
 declare function registerPlanTool(registry: ToolRegistry, opts?: PlanToolOptions): ToolRegistry;
 
-/**
- * Subagent runtime — isolated child loops for offloading exploration or
- * self-contained subtasks.
- *
- * Two surfaces sit on top of the same `spawnSubagent` core:
- *
- *   1. `registerSubagentTool` — exposes a low-level `spawn_subagent`
- *      function-call tool. Library API. NOT registered into the model
- *      tool list by `reasonix code` since 0.4.26 — Skills (with
- *      `runAs: subagent` frontmatter) became the user-facing surface.
- *      Kept exported because library callers and tests still want
- *      direct access to the primitive.
- *
- *   2. `run_skill` (in src/tools/skills.ts) — when the resolved skill
- *      has `runAs: subagent`, it calls `spawnSubagent` with the skill
- *      body as the system prompt and the user's `arguments` as the
- *      task. Subagent skills are listed in the pinned Skills index
- *      with a 🧬 marker, which gives the model a clear pattern-match
- *      trigger without forcing it to reason about "is this task big
- *      enough to delegate."
- *
- * Why R1 specifically benefits:
- *   - R1 reasoning tokens are expensive AND inflate the parent context.
- *     A subagent runs its own private loop, then surfaces only the
- *     distilled final answer back to the parent — the main session
- *     never sees the reasoning trail.
- *
- * Invariants common to both surfaces:
- *   - Serial only — no parallel spawn (MVP).
- *   - Inherits parent's tool registry MINUS `spawn_subagent` itself
- *     (no recursion via the tool API) and MINUS `submit_plan`
- *     (subagents don't propose plans to the user).
- *   - No hooks, no session — runs are ephemeral.
- *   - Lower default `maxToolIters` than the parent (16 vs 64).
- *   - Independent prefix cache (subagent's prefix has its own
- *     fingerprint).
- *   - Parent registry's plan-mode state propagates: subagents can't
- *     escape `/plan`.
- *   - Non-streaming child loop — the parent isn't watching deltas, so
- *     streaming would only add an SSE parser to the critical path.
- *     Cancellation still works via the AbortSignal.
- */
+/** Isolated child loop. Inherits parent registry minus spawn_subagent + submit_plan; no hooks; non-streaming. */
 
-/**
- * Live event emitted by a running subagent. Surfaced via the optional
- * `sink` ref the TUI attaches its handler to. Side-channel only — these
- * events do NOT pass through the parent loop's `LoopEvent` stream
- * because subagents run inside a tool-dispatch frame, after the parent's
- * `step()` has already yielded `tool_start` and is awaiting the result.
- */
+/** Side-channel — subagents run inside a tool-dispatch frame, can't go through parent's `LoopEvent` stream. */
 interface SubagentEvent {
     kind: "start" | "progress" | "end";
-    /** First ~30 chars of the task prompt — used for the TUI status row. */
     task: string;
-    /** Skill that spawned this subagent, when applicable. Stamped on every event so the TUI/logger can attribute without extra plumbing. */
     skillName?: string;
-    /** Model id the child loop ran on. Stamped alongside skillName. */
     model?: string;
-    /** Iteration count inside the child loop (number of tool results so far). */
     iter?: number;
-    /** Wall-clock ms since the subagent started. */
     elapsedMs?: number;
-    /** First ~120 chars of the final assistant message. Set on `end`. */
     summary?: string;
-    /** Error message if the subagent failed. Set on `end`. */
     error?: string;
-    /** Total turns the subagent took. Set on `end`. */
     turns?: number;
-    /** Total USD spent inside the child loop. Set on `end`. */
     costUsd?: number;
-    /** Aggregated child-loop Usage (sum across turns). Set on `end`. */
     usage?: Usage;
 }
-/**
- * Mutable ref the registration writes through. The TUI sets `.current`
- * to its own handler on mount; nothing receives events before that
- * happens (and headless callers leave `.current = null`, which is the
- * library-mode default — they read the final result from the helper's
- * return value instead).
- */
 interface SubagentSink {
     current: ((ev: SubagentEvent) => void) | null;
 }
 interface SubagentToolOptions {
-    /** Shared DeepSeek client. */
     client: DeepSeekClient;
-    /**
-     * Default system prompt used when the model doesn't pass one. Project
-     * memory (REASONIX.md) is appended automatically when `projectRoot` is
-     * set.
-     */
     defaultSystem?: string;
-    /** Project root for `applyProjectMemory` lookup. Omit in chat mode. */
     projectRoot?: string;
-    /** Default model. `deepseek-v4-flash` by default (see DEFAULT_SUBAGENT_MODEL). */
     defaultModel?: string;
-    /** Iteration ceiling. Lower than the parent (16 by default). */
     maxToolIters?: number;
-    /** Maximum chars returned in the tool result. */
     maxResultChars?: number;
-    /** Optional sink the TUI attaches its handler to for live updates. */
     sink?: SubagentSink;
 }
-/**
- * Register the spawn_subagent tool into the parent registry. Library
- * surface — `reasonix code` does NOT call this since 0.4.26 (Skills
- * with `runAs: subagent` are the user-facing surface), but library
- * consumers who want the low-level tool can opt in.
- */
+/** Library surface only — `reasonix code` uses Skills `runAs: subagent` as the user-facing path. */
 declare function registerSubagentTool(parentRegistry: ToolRegistry, opts: SubagentToolOptions): ToolRegistry;
-/**
- * Build a child ToolRegistry that copies every tool from `parent` except
- * those whose names are in `exclude`. Plan-mode state propagates so a
- * subagent spawned while the parent is under `/plan` cannot escape it.
- *
- * Exported for tests + library callers who want the same fork behavior
- * for their own nested-loop patterns.
- */
+/** Plan-mode state propagates — a subagent spawned under `/plan` MUST NOT escape it. */
 declare function forkRegistryExcluding(parent: ToolRegistry, exclude: ReadonlySet<string>): ToolRegistry;
 
-/**
- * Long-running process registry — the "background run" counterpart to
- * `run_command`. `run_command` spawns a child, waits for it to exit,
- * then returns combined output; perfect for tests / builds / one-shots
- * but useless for `npm run dev` / `python -m http.server` / watchers,
- * which never exit and just time the tool out.
- *
- * JobRegistry lets the model fire-and-almost-forget: we spawn the
- * child, wait at most `waitSec` (default 3s) OR until output matches
- * a readiness regex, then return the startup preview plus a job id.
- * The child keeps running in the background; later tool calls tail
- * its output, stop it, or list what's still alive.
- *
- * Shape-wise this is modeled on Claude Code's `BashOutput` / `KillBash`
- * pair. We diverge on one point: ready-signal detection is on by default
- * because dev servers almost universally print "Local:", "listening on",
- * "ready in N ms", "compiled successfully" when they come up — short-
- * circuiting the wait on those keeps the model's first tool-result
- * useful ("server is up at http://localhost:5173") instead of spending
- * the full 3s on a stabilization timer.
- */
+/** Background process registry for never-exiting commands; ready-signal detection short-circuits the startup wait. */
 interface JobStartOptions {
     /** Absolute path to cwd for the spawned child. */
     cwd: string;
-    /**
-     * Max seconds to wait for the initial burst before returning. Capped
-     * at 30. A ready-signal match short-circuits this. Default 3.
-     */
+    /** Capped at 30; ready-signal match short-circuits. Default 3. */
     waitSec?: number;
     /** Signal plumbed through from the calling tool's AbortSignal. */
     signal?: AbortSignal;
@@ -2262,10 +1029,7 @@ interface JobRecord {
     exitCode: number | null;
     /** Combined stdout+stderr, ring-trimmed. */
     output: string;
-    /**
-     * Total bytes ever written by the child (not just what's in `output`).
-     * Useful for "how much got dropped" diagnostics.
-     */
+    /** Counts all bytes the child wrote, not just what's still buffered in `output`. */
     totalBytesWritten: number;
     /** True iff the child is still alive. */
     running: boolean;
@@ -2275,36 +1039,17 @@ interface JobRecord {
 declare class JobRegistry {
     private readonly jobs;
     private nextId;
-    /**
-     * Spawn a background child. Resolves after `waitSec` OR on ready
-     * signal OR on early exit, whichever comes first. The child continues
-     * to run (and buffer output) regardless of which path fires.
-     */
+    /** Resolves on (a) ready signal, (b) early exit, or (c) waitSec deadline — child keeps running regardless. */
     start(command: string, opts: JobStartOptions): Promise<JobStartResult>;
-    /**
-     * Read a job's accumulated output. `since` lets a caller poll
-     * incrementally: pass the byte count returned from the last call to
-     * get only newly-written content. Returns both full output and a
-     * running snapshot so the caller can use whichever.
-     */
     read(id: number, opts?: {
         since?: number;
         tailLines?: number;
     }): JobReadResult | null;
-    /**
-     * Send SIGTERM, wait `graceMs`, then SIGKILL if still alive. Returns
-     * the final job record (or null when the job id is unknown). Safe to
-     * call on an already-exited job — returns the record unchanged.
-     */
+    /** SIGTERM, wait graceMs, then SIGKILL. Idempotent on already-exited jobs. */
     stop(id: number, opts?: {
         graceMs?: number;
     }): Promise<JobRecord | null>;
     list(): JobRecord[];
-    /**
-     * Best-effort kill of every still-running job. Called on TUI shutdown
-     * so dev servers don't outlive the Reasonix process. Resolves after
-     * every child has closed or a hard deadline passes (3s total).
-     */
     shutdown(deadlineMs?: number): Promise<void>;
     /** Count of still-running jobs — drives the TUI status-bar indicator. */
     runningCount(): number;
@@ -2320,109 +1065,25 @@ interface JobReadResult {
     spawnError?: string;
 }
 
-/**
- * Native shell tool — lets the model run commands inside the sandbox
- * root so it can actually verify its own work (run tests, check git
- * status, inspect a lockfile, etc.). Without this the coding-mode
- * loop is "write code, hope it works, ask the user to run it" —
- * defeats the purpose.
- *
- * Safety model:
- *   - Commands run with `cwd` pinned to the registered root. No
- *     path traversal via the command itself is enforced (users can
- *     `cat ../outside.txt`); the trust boundary is the directory
- *     you opened Reasonix from.
- *   - Commands are matched against a read-only / testing allowlist.
- *     Allowlisted commands execute immediately and return stdout +
- *     stderr merged. Everything else throws with a clear message —
- *     the UI translates that into an `/apply`-style confirm gate so
- *     the user sees the exact command before it runs.
- *   - Default timeout: 60s. Output cap: matches tool-result budget.
- *   - Every command that DOES run is spawned with `shell: false` and
- *     a tokenized argv — no string-to-shell interpolation, so the
- *     model can't accidentally construct a chained `rm` via quoting.
- *
- * This is intentionally narrower than what Claude Code / Aider ship:
- * we gate more commands behind confirmation by default. Users who
- * trust the model can widen the allowlist by instantiating their
- * own tool registry.
- */
+/** cwd pinned to root; non-allowlisted commands throw to a UI confirm gate; spawn is `shell: false`, tokenized argv only. */
 
 interface ShellToolsOptions {
     /** Directory to run commands in. Must be an absolute path. */
     rootDir: string;
     /** Seconds before an individual command is killed. Default: 60. */
     timeoutSec?: number;
-    /**
-     * Per-command stdout+stderr cap in characters. Default: 32_000 to
-     * match the tool-result budget.
-     */
     maxOutputChars?: number;
-    /**
-     * Extra command-name prefixes the user explicitly trusts. Added on
-     * top of the built-in allowlist. Examples: `["my-ci-script", "lint"]`.
-     *
-     * Accepts either a fixed array (captured once at registration) or a
-     * getter called on every dispatch. The getter form is load-bearing:
-     * when the TUI's `ShellConfirm` writes a new prefix to config mid-
-     * session, the running `run_command` must pick it up immediately —
-     * otherwise the same command gets re-prompted until the next launch.
-     */
+    /** Getter form is load-bearing — newly-persisted "always allow" prefixes MUST take effect mid-session. */
     extraAllowed?: readonly string[] | (() => readonly string[]);
-    /**
-     * When true, skip the allowlist entirely and auto-run every command.
-     * Off by default — this is an escape hatch for non-interactive use
-     * (CI, benchmarks) where a human can't be in the loop to confirm.
-     *
-     * Accepts either a static boolean (captured once) or a getter called
-     * on every dispatch. The getter form is what `reasonix code` uses to
-     * wire `editMode === "yolo"` into the registry: flipping the mode
-     * mid-session must take effect on the next tool call without forcing
-     * a re-registration. Static `true` is fine for CI / benchmark code.
-     */
+    /** Getter form lets `editMode === "yolo"` flip mid-session without re-registering tools. */
     allowAll?: boolean | (() => boolean);
-    /**
-     * Background-process registry shared between `run_background`,
-     * `job_output`, `stop_job`, `list_jobs`, and the /jobs /kill slashes.
-     * When omitted, the registrar builds its own — but the caller
-     * usually wants to provide one so the TUI can tail it too.
-     */
     jobs?: JobRegistry;
 }
-/**
- * Tokenize a shell-ish command string into argv. Handles single/double
- * quoting; rejects unclosed quotes. Does NOT expand env vars, globs,
- * backticks, or `$(…)` — the goal is to prevent the model from
- * accidentally (or not) sneaking arbitrary shells past the allowlist
- * via concatenation. Exported for testing.
- */
+/** No env / glob / backtick / `$(…)` expansion — prevents bypass of allowlist via concatenation. */
 declare function tokenizeCommand(cmd: string): string[];
-/**
- * Scan `cmd` for a shell operator (`|`, `||`, `>`, `>>`, `<`, `<<`,
- * `&`, `&&`, `2>`, `2>>`, `2>&1`, `&>`) that appears unquoted at a
- * token boundary. Returns the operator string, or null if none.
- *
- * Why this exists: `run_command` documents "no shell expansion, no
- * pipes, no redirects" (the tool spawns argv directly, not through a
- * shell), but when the model writes `dir | findstr foo` the `|`
- * survives tokenization as a standalone token and gets quoted as the
- * literal string `"|"` by `quoteForCmdExe` — cmd.exe sees it as an
- * argument, not an operator, so the pipe silently fails. Detecting
- * operators up front lets us throw a clear error ("split into separate
- * calls") instead of letting the command run with surprising results.
- *
- * Quoted operators (`grep "a|b"`) and operator characters embedded in
- * larger tokens (`--flag=1&2`) are NOT flagged — those are literal
- * argv bytes and are safe to pass through.
- *
- * Exported for testing.
- */
+/** Up-front detection — without it, `dir | findstr foo` quotes `|` literal and pipe silently fails. */
 declare function detectShellOperator(cmd: string): string | null;
-/**
- * Return true when `cmd` matches an allowlisted prefix. Exported for
- * testing. Match is on the space-normalized leading tokens so
- * `git   status  -s ` and `git status` both match `git status`.
- */
+/** Match on space-normalized leading tokens — `git   status  -s` matches the `git status` prefix. */
 declare function isAllowed(cmd: string, extra?: readonly string[]): boolean;
 interface RunCommandResult {
     exitCode: number | null;
@@ -2437,95 +1098,28 @@ declare function runCommand(cmd: string, opts: {
     maxOutputChars?: number;
     signal?: AbortSignal;
 }): Promise<RunCommandResult>;
-/**
- * Test/override hooks for {@link resolveExecutable}. Omitting any field
- * falls through to the real process globals — the runtime call path
- * uses defaults; tests inject `platform` + `env` + `isFile` to exercise
- * Windows-specific lookup from a Linux CI runner without touching
- * actual fs.
- */
 interface ResolveExecutableOptions {
     platform?: NodeJS.Platform;
     env?: {
         PATH?: string;
         PATHEXT?: string;
     };
-    /** Predicate swapped in by tests to avoid creating real files. */
     isFile?: (path: string) => boolean;
-    /** Path.join used for the lookup. Defaults to Windows semantics on Windows. */
     pathDelimiter?: string;
 }
-/**
- * Resolve a bare command name (e.g. `npm`) to its on-disk path via
- * PATH × PATHEXT on Windows. Returns the input unchanged on non-Windows
- * platforms, when the input is already a path (contains `/`, `\`, or is
- * absolute), or when no match is found in PATH × PATHEXT (caller gets a
- * natural ENOENT from spawn, which surfaces cleanly).
- *
- * Why this exists: `child_process.spawn` with `shell: false` invokes
- * Windows `CreateProcess`, which does not honor `PATHEXT` and does not
- * search for `.cmd` / `.bat` wrappers. Node-ecosystem tools ship as
- * `npm.cmd`, `npx.cmd`, `yarn.cmd`, etc., so a bare `npm` fails with
- * ENOENT under `shell: false`. Flipping to `shell: true` would work
- * but reintroduces shell-expansion (pipes, redirects, chained cmds)
- * that the tool was explicitly designed to forbid. This resolver
- * threads the needle.
- */
+/** CreateProcess ignores PATHEXT — bare `npm` fails ENOENT under `shell:false` without this resolver. */
 declare function resolveExecutable(cmd: string, opts?: ResolveExecutableOptions): string;
-/**
- * Prepare `(bin, args, spawnOpts)` for the runCommand spawn call,
- * applying Windows-specific workarounds for (a) PATHEXT lookup and
- * (b) the CVE-2024-27980 prohibition on direct `.cmd`/`.bat` spawns.
- *
- * Exported so tests can assert the transformation without booting an
- * actual child process.
- */
+/** Windows workarounds: PATHEXT lookup + CVE-2024-27980 prohibition on direct `.cmd`/`.bat` spawn. */
 declare function prepareSpawn(argv: readonly string[], opts?: ResolveExecutableOptions): {
     bin: string;
     args: string[];
     spawnOverrides: SpawnOptions;
 };
-/**
- * Locate `-Command` / `-c` in `args` and prepend the UTF-8 setup prelude
- * to its value. Returns the patched args, or `null` when no `-Command`
- * arg is present (in which case we leave the invocation untouched —
- * inline-expression and script-file modes have their own conventions
- * we don't want to silently rewrite).
- *
- * Why not always wrap: PowerShell's quoting semantics are finicky enough
- * that adding a prelude to a script file invocation could break it.
- * `-Command` is the case the model actually uses, and where mojibake
- * matters; targeting just it keeps the blast radius small.
- *
- * Exported for tests.
- */
+/** Targets `-Command` only — PowerShell quoting is finicky enough that wrapping script-file mode could break it. */
 declare function injectPowerShellUtf8(args: readonly string[]): string[] | null;
-/**
- * Prefix a cmd.exe command line with `chcp 65001 >nul &` so output
- * (from cmd.exe and any child it spawns) is UTF-8-encoded. Without
- * this, on Chinese / Japanese / Korean Windows, `dir`, `findstr`,
- * `where`, etc. emit text in the system codepage (CP936, CP932,
- * CP949, …) and `chunk.toString()` — which decodes as UTF-8 — produces
- * garbled mojibake the model then sees as poisoned input on the next
- * turn.
- *
- * Scope: chcp affects ONLY this cmd.exe instance, which exits after
- * `/c`. No global console state changes. Single `&` (not `&&`) so the
- * command still runs even on the rare Windows builds where chcp
- * itself returns a non-zero exit (Win7 quirks; harmless on Win10+).
- *
- * Exported so tests can verify the wrapping shape.
- */
+/** Single `&` (not `&&`) so the command still runs on Win7 where chcp can return non-zero. */
 declare function withUtf8Codepage(cmdline: string): string;
-/**
- * Quote an argument so cmd.exe parses it back as a single token. We
- * always wrap in double quotes when the arg contains whitespace or
- * any cmd.exe metacharacter, doubling embedded quotes per cmd.exe's
- * `""` escape rule. Bare alphanumeric args pass through unquoted for
- * readability in logs.
- *
- * Exported for test coverage of the quoting semantics.
- */
+/** Doubles embedded quotes per cmd.exe's `""` escape rule; bare alnum passes through unquoted. */
 declare function quoteForCmdExe(arg: string): string;
 /** Error thrown by `run_command` when the command isn't allowlisted. */
 declare class NeedsConfirmationError extends Error {
@@ -2535,22 +1129,7 @@ declare class NeedsConfirmationError extends Error {
 declare function registerShellTools(registry: ToolRegistry, opts: ShellToolsOptions): ToolRegistry;
 declare function formatCommandResult(cmd: string, r: RunCommandResult): string;
 
-/**
- * Built-in web search + fetch tools.
- *
- *   - `web_search(query, topK?)` — Mojeek's public search page. No API
- *     key, no signup. We originally shipped this backed by DuckDuckGo's
- *     HTML endpoint, but DDG started serving anti-bot interstitials
- *     (HTTP 202 with a challenge page) for every unauthenticated POST.
- *     Mojeek runs its own independent index, is bot-friendly, and
- *     returns parseable HTML.
- *   - `web_fetch(url)` — HTTP GET + naïve HTML-to-text extraction.
- *
- * Both are registered by default on `reasonix chat` / `reasonix code`;
- * set `search: false` in config (or `REASONIX_SEARCH=off`) to turn
- * them off. The model decides when to call them based on the query —
- * no slash command required.
- */
+/** web_search uses Mojeek (DDG returns anti-bot 202 to unauthenticated POSTs); web_fetch sniffs HTML to text. */
 
 interface SearchResult {
     title: string;
@@ -2575,44 +1154,11 @@ interface WebSearchOptions {
     topK?: number;
     signal?: AbortSignal;
 }
-/**
- * Search the public web via Mojeek. Returns up to `topK` ranked
- * results with title, url, snippet.
- *
- * Mojeek is an independent index (not a Google/Bing front-end) which
- * means coverage on niche or very recent topics can be thinner, but
- * it's reliable from scripts and doesn't gate on cookies or sessions.
- * If the response has 0 results we distinguish "truly empty" from
- * "layout changed or blocked" so the caller isn't left guessing.
- */
+/** Distinguishes "truly 0 results" from "layout changed / blocked" so callers can tell. */
 declare function webSearch(query: string, opts?: WebSearchOptions): Promise<SearchResult[]>;
-/**
- * Extract results from a Mojeek search page.
- *
- * Mojeek's stable shape (as of April 2026):
- *   <a … class="ob" href="URL"> … breadcrumb … </a>
- *   <h2><a class="title" href="URL">Title</a></h2>
- *   <p class="s">snippet text …</p>
- *
- * We do two tolerant passes — title anchors, then snippet paragraphs —
- * and pair them positionally. Attribute order inside a tag varies
- * between versions, so each pass captures the whole element and we
- * re-extract href / inner text with a second regex. Exported for
- * unit testing against a fixture.
- */
+/** Title-anchor + snippet-paragraph passes paired positionally — robust to attribute reorder. */
 declare function parseMojeekResults(html: string): SearchResult[];
-/**
- * Download a URL, strip HTML down to readable text, return it. Times
- * out at 15s, caps extracted text at 32k chars to fit the tool-result
- * budget.
- */
 declare function webFetch(url: string, opts?: WebFetchOptions): Promise<PageContent>;
-/**
- * Strip HTML to readable text. Removes scripts/styles/nav/footer/aside
- * blocks first, then tags, then collapses whitespace. Not a Readability
- * clone — purpose-built to keep the extracted text small enough for the
- * tool-result budget while preserving paragraph breaks.
- */
 declare function htmlToText(html: string): string;
 interface WebToolsOptions {
     /** Default top-K for `web_search` when the model doesn't specify. */
@@ -2620,30 +1166,10 @@ interface WebToolsOptions {
     /** Byte cap for `web_fetch` extracted text. */
     maxFetchChars?: number;
 }
-/**
- * Register `web_search` + `web_fetch` on a ToolRegistry. The model
- * invokes them automatically when a question needs current info —
- * no slash command from the user is required.
- */
 declare function registerWebTools(registry: ToolRegistry, opts?: WebToolsOptions): ToolRegistry;
 declare function formatSearchResults(query: string, results: SearchResult[]): string;
 
-/**
- * Session persistence.
- *
- * Every turn's log entries (user / assistant / tool messages) are appended to
- * a JSONL file under `~/.reasonix/sessions/<name>.jsonl`. Next time the user
- * starts the CLI with the same session name, the loop pre-loads the file
- * into its AppendOnlyLog so the new turn has full prior context.
- *
- * Design notes:
- *   - JSONL rather than JSON so concurrent writes don't corrupt.
- *   - 0600 permissions on Unix (chmod no-ops on Windows).
- *   - Name sanitization keeps paths safe: only [\w-] and CJK letters pass;
- *     anything else is replaced with underscore, max 64 chars.
- *   - The loop's stats/session aren't persisted — only the message log.
- *     Cost accounting resets each run (by design — old costs are sunk).
- */
+/** JSONL append-only message log under `~/.reasonix/sessions/`; concurrent-write safe. */
 
 interface SessionInfo {
     name: string;
@@ -2660,32 +1186,9 @@ declare function appendSessionMessage(name: string, message: ChatMessage): void;
 declare function listSessions(): SessionInfo[];
 declare function deleteSession(name: string): boolean;
 
-/**
- * Minimal `.env` loader; no dependency on dotenv.
- *
- * Reads KEY=VALUE lines and populates `process.env` for keys not already set.
- * Silently no-ops if the file is missing. Safe to call from library entry
- * points, CLI commands, examples, and benchmark runners.
- */
 declare function loadDotenv(path?: string): void;
 
-/**
- * Transcript format — the canonical "audit log" of a Reasonix session.
- *
- * Design split:
- *   - Session file (`~/.reasonix/sessions/<name>.jsonl`) stores only the
- *     `ChatMessage`s the model needs to resume. See session.ts.
- *   - Transcript file (this module) stores every LoopEvent with usage, cost,
- *     model, and prefix fingerprint attached where available — enough for
- *     replay and diff to reconstruct economics.
- *
- * The two are different contracts: sessions are the user's *memory*;
- * transcripts are the *receipts*. Don't conflate them.
- *
- * Backward compatibility: all fields beyond {ts, turn, role, content} are
- * optional on read. A v0.1 transcript (pre-usage) still parses and renders
- * — it just shows cost/cache as n/a.
- */
+/** Transcripts are receipts (cost/usage/prefix); sessions are memory (ChatMessages). Don't conflate. */
 
 interface TranscriptRecord {
     /** ISO-8601 timestamp at emit time. */
@@ -2706,28 +1209,14 @@ interface TranscriptRecord {
     cost?: number;
     /** Model id that produced this turn. */
     model?: string;
-    /**
-     * The ImmutablePrefix fingerprint at this turn. Lets diff prove two runs
-     * share a prefix — i.e. any cache-hit delta is attributable to log
-     * stability, not to a different system prompt.
-     */
+    /** Lets diff attribute cache-hit delta to log stability vs prompt change. */
     prefixHash?: string;
-    /**
-     * Structured plan state extracted by the Pillar 2 harvester. Present on
-     * assistant_final records when harvest was enabled and produced non-empty
-     * state. Omitted entirely when harvest is off or produced nothing —
-     * absence means "no data", not "empty plan".
-     */
+    /** Absent means "no data", not "empty plan". */
     planState?: TypedPlanState;
     /** Optional error message (role === "error"). */
     error?: string;
 }
 interface TranscriptMeta {
-    /**
-     * Optional metadata written as the first line of a transcript. Lets
-     * downstream tooling know what it's reading without guessing.
-     * Recognized by a special role "_meta".
-     */
     version: 1;
     source: string;
     model?: string;
@@ -2740,11 +1229,6 @@ interface ReadTranscriptResult {
     meta: TranscriptMeta | null;
     records: TranscriptRecord[];
 }
-/**
- * Build a TranscriptRecord from a LoopEvent. Extra fields (model,
- * prefixHash) that the LoopEvent doesn't carry are passed in separately
- * because they're session-level, not event-level.
- */
 declare function recordFromLoopEvent(ev: LoopEvent, extra: {
     model: string;
     prefixHash: string;
@@ -2761,30 +1245,11 @@ declare function writeMeta(stream: WriteStream, meta: TranscriptMeta): void;
  * Convenience: open a stream, write meta, return stream.
  */
 declare function openTranscriptFile(path: string, meta: TranscriptMeta): WriteStream;
-/**
- * Parse a transcript file. Returns meta (if the first line is a _meta record)
- * and the full record list.
- *
- * Robustness contract:
- *   - Empty lines are skipped.
- *   - Malformed JSON lines are skipped silently (do not crash on partial
- *     files — live chats may be mid-write).
- *   - Records missing optional fields still parse — they're just rendered
- *     with n/a where the optional value would go.
- */
+/** Tolerant: empty / malformed lines skipped, missing optionals OK — live chats may be mid-write. */
 declare function readTranscript(path: string): ReadTranscriptResult;
 declare function parseTranscript(raw: string): ReadTranscriptResult;
 
-/**
- * Replay — reconstruct session economics from a transcript file.
- *
- * Given a transcript written by App.tsx or the bench runner, rebuild a
- * SessionSummary-compatible aggregate (turn count, total cost, cache-hit
- * ratio, vs-Claude estimate) without replaying the LLM calls.
- *
- * The whole point is offline auditing: a reader should be able to reproduce
- * the headline numbers from a transcript alone, without an API key.
- */
+/** Reconstruct session economics from a transcript alone — offline audit, no API key. */
 
 interface ReplayStats extends SessionSummary {
     /** Per-turn stats, in turn order. Only assistant_final records contribute. */
@@ -2804,35 +1269,13 @@ interface ReplayStats extends SessionSummary {
     /** Sum of subgoals across all harvested turns. */
     totalSubgoals: number;
 }
-/**
- * Parse a transcript file and compute replay stats. Throws only on I/O
- * errors; malformed lines inside the file are skipped silently.
- */
 declare function replayFromFile(path: string): {
     parsed: ReadTranscriptResult;
     stats: ReplayStats;
 };
 declare function computeReplayStats(records: TranscriptRecord[]): ReplayStats;
 
-/**
- * Diff — compare two transcripts and produce a summary + divergence report.
- *
- * Two transcripts are "comparable" when they stem from the same task (or
- * the same user prompt). Alignment is by turn number: assistant_final #N
- * in A pairs with assistant_final #N in B. If one side ran more turns, the
- * extras are labeled "only in A" / "only in B".
- *
- * What we compute:
- *   - Aggregate deltas: turns, tool calls, cache hit, cost, token counts
- *   - First divergence: the lowest turn where A and B's tool calls or
- *     assistant text differ meaningfully
- *   - Prefix-stability story: how many unique prefix hashes each side used
- *
- * Non-goals (deliberately):
- *   - LLM-judge quality comparison
- *   - Per-token delta rendering — not useful at the fidelity we're at
- *   - Embedding similarity — Levenshtein ratio is cheap and good enough
- */
+/** Transcript diff — pairs assistant_final by turn number; unmatched extras become only_in_a / only_in_b. */
 
 interface DiffSide {
     label: string;
@@ -2846,13 +1289,6 @@ interface TurnPair {
     bAssistant?: TranscriptRecord;
     aTools: TranscriptRecord[];
     bTools: TranscriptRecord[];
-    /**
-     * Classification of the pair:
-     *   "match"      — both sides present, text & tool calls within threshold
-     *   "diverge"    — both sides present, but text or tool calls differ
-     *   "only_in_a"  — assistant_final in A but not B
-     *   "only_in_b"  — assistant_final in B but not A
-     */
     kind: "match" | "diverge" | "only_in_a" | "only_in_b";
     /** When kind === "diverge", a short one-liner pointing at what differs. */
     divergenceNote?: string;
@@ -2870,11 +1306,7 @@ declare function diffTranscripts(a: {
     label: string;
     parsed: ReadTranscriptResult;
 }): DiffReport;
-/**
- * Normalized Levenshtein similarity ratio in [0, 1]. 1 = identical.
- * Early-exits for long strings (> 2000 chars) with a cheap token-overlap
- * estimate to keep diff fast on chatty transcripts.
- */
+/** Falls back to token-overlap above 2000 chars to keep diff fast on chatty transcripts. */
 declare function similarity(a: string, b: string): number;
 interface RenderOptions {
     /** Monochrome output (for file redirection or piping). Defaults to true. */
@@ -2883,26 +1315,7 @@ interface RenderOptions {
 declare function renderSummaryTable(report: DiffReport, _opts?: RenderOptions): string;
 declare function renderMarkdown(report: DiffReport): string;
 
-/**
- * MCP (Model Context Protocol) type definitions.
- *
- * Hand-rolled rather than importing @modelcontextprotocol/sdk because:
- *   - Reasonix's value-add isn't reimplementing the protocol, but *caching*
- *     it. Owning the types lets us tune them for our integration (strip
- *     fields we don't use, add the ones we do like Reasonix's prefixHash).
- *   - Zero dependencies — consistent with how we wrote the DeepSeek client.
- *   - If Anthropic bumps the SDK and introduces a breaking change, we're
- *     insulated as long as we keep up with the spec itself.
- *
- * Spec reference: https://spec.modelcontextprotocol.io/ (2024-11-05 draft
- * at time of writing). Reasonix models the subset it consumes: tools
- * list/call, resources list/read, prompts list/get, plus the init
- * handshake. Sampling and progress notifications remain deferred.
- *
- * Transport note: the wire format for stdio MCP is **newline-delimited
- * JSON** (NDJSON), not the LSP-style Content-Length header framing that
- * some readers might expect. One JSON-RPC message per line.
- */
+/** MCP types (spec 2024-11-05). Stdio wire format is NDJSON — one JSON-RPC message per line, no Content-Length framing. */
 type JsonRpcId = string | number;
 interface JsonRpcRequest<P = unknown> {
     jsonrpc: "2.0";
@@ -2968,13 +1381,6 @@ interface ListToolsResult {
     tools: McpTool[];
     nextCursor?: string;
 }
-/**
- * Server → client notification emitted during a long-running request
- * that the client subscribed to via `_meta.progressToken`. `progress`
- * and `total` are typically matched units (files scanned, bytes
- * processed, etc.); `total` may be missing when the server can't
- * estimate the upper bound up front.
- */
 interface ProgressNotificationParams {
     progressToken: string | number;
     progress: number;
@@ -3004,11 +1410,6 @@ interface CallToolResult {
     /** True = tool raised an error; the content describes it. */
     isError?: boolean;
 }
-/**
- * A resource the server can expose — think "file the model can read."
- * The URI is opaque to the client: servers may use `file://`, custom
- * schemes, or bare strings. Reasonix doesn't interpret them.
- */
 interface McpResource {
     uri: string;
     name: string;
@@ -3020,12 +1421,7 @@ interface ListResourcesResult {
     resources: McpResource[];
     nextCursor?: string;
 }
-/**
- * One resource can return multiple content blobs (e.g. the file + a
- * side-car). `text` is the common case for UTF-8 content; `blob` is
- * base64-encoded bytes for binary content. Servers populate exactly
- * one of the two for each entry.
- */
+/** Server populates exactly one of `text` (UTF-8) or `blob` (base64) per entry. */
 interface McpResourceContentsText {
     uri: string;
     mimeType?: string;
@@ -3040,10 +1436,6 @@ type McpResourceContents = McpResourceContentsText | McpResourceContentsBlob;
 interface ReadResourceResult {
     contents: McpResourceContents[];
 }
-/**
- * A parameterizable prompt template the server exposes. Clients fetch
- * it with `prompts/get` and pass the result to the model as-is.
- */
 interface McpPromptArgument {
     name: string;
     description?: string;
@@ -3058,12 +1450,6 @@ interface ListPromptsResult {
     prompts: McpPrompt[];
     nextCursor?: string;
 }
-/**
- * MCP prompt messages are modeled after chat completions: role + content.
- * Content can be a text block OR (per the spec) a resource/image block;
- * Reasonix cares about text in v1, but surfaces the raw array so callers
- * can render other kinds if they need to.
- */
 interface McpPromptMessage {
     role: "user" | "assistant";
     content: McpContentBlock | McpPromptResourceBlock;
@@ -3081,23 +1467,8 @@ declare const MCP_PROTOCOL_VERSION = "2024-11-05";
 /** Type guard — success vs error response. */
 declare function isJsonRpcError(msg: JsonRpcResponse): msg is JsonRpcError;
 
-/**
- * Stdio transport for MCP.
- *
- * MCP's stdio wire format is **newline-delimited JSON** (one JSON-RPC
- * message per line). We spawn the server as a child process, write
- * frames to its stdin, parse its stdout line-by-line as they arrive.
- *
- * Transport is abstracted behind an interface so unit tests can fake it
- * with an in-process duplex pair — spawning real servers in unit tests
- * is flaky and slow.
- */
+/** MCP stdio = newline-delimited JSON-RPC; transport iface lets tests fake it without spawning. */
 
-/**
- * A transport sends JSON-RPC messages upstream and surfaces messages
- * arriving downstream via an async iterator. One instance per server
- * connection.
- */
 interface McpTransport {
     /** Send one JSON-RPC message. Resolves when the bytes are accepted. */
     send(message: JsonRpcMessage): Promise<void>;
@@ -3116,19 +1487,9 @@ interface StdioTransportOptions {
     replaceEnv?: boolean;
     /** CWD for the child. Default: process.cwd(). */
     cwd?: string;
-    /**
-     * Spawn through a shell. Default: true on win32 (needed to resolve
-     * `.cmd` wrappers like `npx.cmd`, `pnpm.cmd`), false elsewhere.
-     * Explicitly pass `false` to opt out on Windows; pass `true` to force
-     * it on POSIX (rarely needed).
-     */
+    /** Default true on win32 to resolve `.cmd`/`.bat` wrappers (npx.cmd etc.). */
     shell?: boolean;
 }
-/**
- * Spawn `command args...` as a child process and use its stdin/stdout as
- * an MCP transport. Stderr is forwarded to the parent's stderr so server
- * diagnostics are still visible.
- */
 declare class StdioTransport implements McpTransport {
     private readonly child;
     private readonly queue;
@@ -3145,12 +1506,6 @@ declare class StdioTransport implements McpTransport {
     private push;
 }
 
-/**
- * MCP client — request/response correlation, initialize handshake,
- * tools/list, tools/call. Built on top of a McpTransport so the same
- * logic works against a real stdio server or an in-process fake.
- */
-
 interface McpClientOptions {
     transport: McpTransport;
     clientInfo?: McpClientInfo;
@@ -3180,50 +1535,21 @@ declare class McpClient {
     get protocolVersion(): string;
     /** Optional free-form instructions the server provides at handshake. */
     get serverInstructions(): string | undefined;
-    /**
-     * Complete the initialize → initialized handshake. Must be called
-     * before any other method (otherwise compliant servers reject).
-     */
+    /** Compliant servers reject other methods until this completes. */
     initialize(): Promise<InitializeResult>;
     /** List tools the server exposes. */
     listTools(): Promise<ListToolsResult>;
-    /**
-     * Invoke a tool by name. When `onProgress` is supplied, attaches a
-     * fresh progress token so the server can send incremental updates
-     * via `notifications/progress`; they're routed to the callback until
-     * the final response arrives (or the request times out, in which
-     * case the handler is simply dropped — no extra notification).
-     *
-     * When `signal` is supplied, aborting it:
-     *   1) fires `notifications/cancelled` to the server (MCP 2024-11-05
-     *      way of saying "forget this request, I no longer care"), and
-     *   2) rejects the pending promise immediately with an AbortError,
-     *      so the caller doesn't have to wait for the subprocess to
-     *      finish its in-flight file write or network request.
-     * The server MAY still emit a late response; we drop it in dispatch
-     * since the request id is gone from `pending`.
-     */
+    /** Abort sends `notifications/cancelled` and rejects immediately; late server responses are dropped. */
     callTool(name: string, args?: Record<string, unknown>, opts?: {
         onProgress?: McpProgressHandler;
         signal?: AbortSignal;
     }): Promise<CallToolResult>;
-    /**
-     * List resources the server exposes. Supports a pagination cursor;
-     * callers interested in the full set should loop on `nextCursor`.
-     * Servers that don't support resources respond with method-not-found
-     * (−32601) — we surface that as a thrown Error so callers can gate
-     * on the `serverCapabilities.resources` field first.
-     */
+    /** Throws on method-not-found; callers should gate on `serverCapabilities.resources` first. */
     listResources(cursor?: string): Promise<ListResourcesResult>;
     /** Read the contents of a resource by URI. */
     readResource(uri: string): Promise<ReadResourceResult>;
     /** List prompt templates the server exposes. */
     listPrompts(cursor?: string): Promise<ListPromptsResult>;
-    /**
-     * Fetch a rendered prompt by name. `args` supplies values for any
-     * required template arguments; the server validates. Returns messages
-     * ready to prepend to the model's input.
-     */
     getPrompt(name: string, args?: Record<string, string>): Promise<GetPromptResult>;
     /** Close the transport and reject any outstanding requests. */
     close(): Promise<void>;
@@ -3234,27 +1560,7 @@ declare class McpClient {
     private dispatch;
 }
 
-/**
- * HTTP+SSE transport for MCP (spec version 2024-11-05).
- *
- * Wire shape:
- *   1. Client opens GET to the SSE URL with `Accept: text/event-stream`.
- *   2. Server's first SSE event is `event: endpoint`, `data: <url>` — the
- *      URL (relative or absolute) the client must POST JSON-RPC requests
- *      to. All subsequent server → client messages arrive as `event: message`
- *      SSE frames carrying a JSON-RPC response or server-initiated frame.
- *   3. Client POSTs each outgoing JSON-RPC frame to the endpoint URL.
- *      The POST response body is ignored — replies land on the SSE stream.
- *
- * This transport exists so Reasonix can talk to hosted/remote MCP servers
- * (e.g. a company's internal knowledge server fronted by auth). Stdio
- * covers local subprocesses; SSE covers everything else.
- *
- * Note: the newer "Streamable HTTP" transport (2025 spec) folds the POST
- * and SSE streams onto a single endpoint. We stay on 2024-11-05 here —
- * that's what `MCP_PROTOCOL_VERSION` advertises in the initialize handshake
- * and what currently-published servers implement.
- */
+/** MCP HTTP+SSE transport (spec 2024-11-05) — POST endpoint URL arrives as the first `event: endpoint` SSE frame. */
 
 interface SseTransportOptions {
     /** SSE endpoint URL, e.g. `https://mcp.example.com/sse`. */
@@ -3262,10 +1568,6 @@ interface SseTransportOptions {
     /** Extra headers sent on both the SSE GET and the JSON-RPC POSTs (e.g. `Authorization`). */
     headers?: Record<string, string>;
 }
-/**
- * Open an SSE stream to `url`, parse incoming events into JsonRpcMessages,
- * POST outgoing frames to the endpoint URL the server advertises.
- */
 declare class SseTransport implements McpTransport {
     private readonly url;
     private readonly headers;
@@ -3289,40 +1591,7 @@ declare class SseTransport implements McpTransport {
     private markClosed;
 }
 
-/**
- * Streamable HTTP transport for MCP (spec version 2025-03-26).
- *
- * Wire shape (single endpoint, no separate POST URL handshake):
- *
- *   1. Client POSTs each outgoing JSON-RPC frame to the endpoint with
- *      `Accept: application/json, text/event-stream`. The server picks
- *      ONE of three responses:
- *        a. `202 Accepted`, no body → notification or response
- *           was accepted; nothing more to deliver.
- *        b. `200 OK`, `Content-Type: application/json` → body is a
- *           single JSON-RPC response (or batch). Connection closes.
- *        c. `200 OK`, `Content-Type: text/event-stream` → an SSE
- *           stream of `event: message` frames carrying responses,
- *           server-initiated requests, and notifications. Stream may
- *           close after the matching response or stay open longer.
- *   2. The server may include `Mcp-Session-Id: <opaque>` on the response
- *      to `initialize`. Client echoes that header on every subsequent
- *      request. A 404 on a request with a session id means the session
- *      expired — caller must reinitialize.
- *
- * Compared to 2024-11-05 HTTP+SSE:
- *   - No two-endpoint dance (no `event: endpoint` handshake).
- *   - Replies arrive on the POST response, not on a separate GET stream.
- *   - Session continuity is explicit (`Mcp-Session-Id`), not implicit.
- *
- * Not yet implemented in this transport (acceptable for v1):
- *   - Long-lived GET stream for unsolicited server-initiated frames
- *     (sampling requests, etc.). Most MCP servers we care about today
- *     don't issue server-initiated requests, and POST-only handles
- *     full request/response/notification traffic. Add when a real
- *     server we're integrating against needs it.
- *   - Resumability via `Last-Event-ID` on reconnect.
- */
+/** MCP Streamable HTTP transport (2025-03-26) — POST-only; no long-lived GET stream, no Last-Event-ID resume. */
 
 interface StreamableHttpTransportOptions {
     /** Streamable HTTP endpoint URL, e.g. `https://mcp.example.com/mcp`. */
@@ -3351,46 +1620,16 @@ declare class StreamableHttpTransport implements McpTransport {
     private pushMessage;
 }
 
-/**
- * Bridge: register an MCP server's tools into a Reasonix ToolRegistry.
- *
- * This is the integration surface. Once done, `CacheFirstLoop` sees the
- * MCP tools as if they were native — they inherit Cache-First + repair
- * (scavenge / truncation / storm) automatically. That's the payoff: any
- * MCP ecosystem tool, wrapped in Reasonix's Pillar 1 + Pillar 3 benefits.
- */
-
 interface BridgeOptions {
-    /**
-     * Prefix prepended to every MCP tool name when registered. Defaults to
-     * empty (no prefix). Useful when bridging multiple servers into one
-     * registry and names collide — e.g. `fs` + `gh` both exposing `search`.
-     */
+    /** Prefix for tool names — disambiguates collisions when bridging multiple servers. */
     namePrefix?: string;
     /** Registry to populate. Creates a fresh one if omitted. */
     registry?: ToolRegistry;
     /** Auto-flatten deep schemas (Pillar 3). Defaults to the registry's own default (true). */
     autoFlatten?: boolean;
-    /**
-     * Per-tool-call result cap, in characters. If a tool returns more than
-     * this, the result is truncated and a `[…truncated N chars…]` marker is
-     * appended before the last KB so the model still sees a useful tail.
-     * Defaults to {@link DEFAULT_MAX_RESULT_CHARS}.
-     *
-     * Why this exists: DeepSeek V3's context is 131,072 tokens. A single
-     * `read_file` against a big source file can return >3 MB of text
-     * (~900k tokens) and permanently poison the session — every subsequent
-     * turn rebuilds the history and 400s. This cap is a floor. Users who
-     * legitimately want bigger payloads can raise it explicitly.
-     */
+    /** Cap on tool result chars; head+tail truncation. Floor against context-poisoning oversized reads. */
     maxResultChars?: number;
-    /**
-     * Callback fired for every `notifications/progress` frame the server
-     * emits during any bridged tool call. Includes the registered
-     * (prefix-applied) tool name so a multi-server UI can attribute
-     * progress correctly. Absent → no `_meta.progressToken` is sent and
-     * the server won't emit progress for these calls.
-     */
+    /** Absent → no `_meta.progressToken` sent and server won't emit progress. */
     onProgress?: (info: {
         toolName: string;
         progress: number;
@@ -3398,22 +1637,8 @@ interface BridgeOptions {
         message?: string;
     }) => void;
 }
-/**
- * 32,000 chars ≈ 8k English tokens, or ~16k CJK tokens. Small enough to
- * fit comfortably in history even across 5–10 tool calls, large enough
- * that most file reads and directory listings fit un-truncated.
- */
 declare const DEFAULT_MAX_RESULT_CHARS = 32000;
-/**
- * Token-aware cap for tool results, in DeepSeek V3 tokens.
- *
- * 8,000 tokens ≈ 6% of DeepSeek V3's 131K context. One oversized tool
- * result can't eat more than that no matter what character density the
- * content has. The char cap (32K chars) only bounds tokens for English
- * — CJK text at 1 char/token blows past 16K tokens under the same
- * ceiling. With the tokenizer shipped in 0.5.0 we can cap the thing
- * that actually matters.
- */
+/** ~6% of DeepSeek V3 context. Char cap alone fails on CJK (~1 char/token). */
 declare const DEFAULT_MAX_RESULT_TOKENS = 8000;
 interface BridgeResult {
     registry: ToolRegistry;
@@ -3425,86 +1650,18 @@ interface BridgeResult {
         reason: string;
     }>;
 }
-/**
- * Walk a connected `McpClient`'s tools/list result, register each into a
- * Reasonix `ToolRegistry`. Each registered `fn` proxies through the
- * client's tools/call. Tool results are flattened into a string (joining
- * text blocks with newlines, prefixing image blocks as placeholders) so
- * they fit Reasonix's existing tool-dispatch contract.
- */
 declare function bridgeMcpTools(client: McpClient, opts?: BridgeOptions): Promise<BridgeResult>;
 interface FlattenOptions {
     /** Cap the flattened string at this many characters. Default: no cap. */
     maxChars?: number;
 }
-/**
- * Turn an MCP CallToolResult into a string — the contract Reasonix's
- * ToolRegistry.dispatch returns. We:
- *   - join text blocks with newlines (most common case)
- *   - stringify image blocks as placeholders (LLM can't use bytes anyway
- *     in Reasonix's current surface; image support comes with multimodal
- *     prompts later)
- *   - prefix error results with "ERROR: " so the calling model sees the
- *     failure clearly even through JSON mode
- *   - optionally truncate to `maxChars` so a single oversized tool result
- *     (e.g. a big `read_file`) can't poison the session by blowing past
- *     the model's context window
- */
 declare function flattenMcpResult(result: CallToolResult, opts?: FlattenOptions): string;
-/**
- * Keep the head AND a short tail so the model sees both "what the tool
- * started returning" and "how it ended". Head-only loses file endings
- * (e.g. an error message appended at the bottom of a stack trace); the
- * 1KB tail window covers that while costing almost nothing. Exported for
- * tests and reuse by non-MCP tool adapters that want the same policy.
- */
+/** Head + 1KB tail so error messages at end of stack traces aren't lost. */
 declare function truncateForModel(s: string, maxChars: number): string;
-/**
- * Token-aware truncation. Same head+tail policy as `truncateForModel`,
- * but sizes the slices against a DeepSeek V3 token budget instead of a
- * raw character count — so CJK text (which previously survived at 2×
- * the token cost per char) gets capped at the same effective context
- * footprint as English.
- *
- * Strategy: fast path when `s.length <= maxTokens` (every token is ≥1
- * char, so this bounds tokens ≤ maxTokens — skip tokenize entirely).
- * Short-ish strings are confirmed against the real token count.
- * Long strings go straight to char-sliced head+tail with one or two
- * tokenize-verify-and-shrink rounds per slice — we deliberately never
- * tokenize the full input, because pathological repetitive text
- * (megabytes of `AAAA…`) can cost 30s+ on the pure-TS BPE port.
- */
+/** Never tokenizes full input — pathological repetitive text (`AAAA…`) costs 30s+ on the pure-TS BPE port. */
 declare function truncateForModelByTokens(s: string, maxTokens: number): string;
 
-/**
- * Parse the `--mcp` CLI argument into a transport-tagged spec.
- *
- * Accepted forms:
- *   "name=command args..."             → stdio, namespaced (tools prefixed with `name_`)
- *   "command args..."                  → stdio, anonymous
- *   "name=https://host/sse"            → HTTP+SSE (2024-11-05), namespaced
- *   "https://host/sse"                 → HTTP+SSE (2024-11-05), anonymous
- *   "name=streamable+https://host/mcp" → Streamable HTTP (2025-03-26), namespaced
- *   "streamable+https://host/mcp"      → Streamable HTTP (2025-03-26), anonymous
- *   ("http://" / "streamable+http://" also honored — useful for local dev.)
- *
- * The identifier regex before `=` is deliberately narrow
- * (`[a-zA-Z_][a-zA-Z0-9_]*`) so Windows drive letters ("C:\\...") and
- * other strings containing `=` or `:` don't accidentally trigger the
- * namespace branch. If a user ever wants their command to literally start
- * with `foo=...` as a bare command, they can wrap it in quotes inside the
- * shell command string.
- *
- * Transport selection:
- *   - body starts with `streamable+http(s)://` → Streamable HTTP. The
- *     `streamable+` prefix is stripped from the URL we hand the transport.
- *   - body starts with `http(s)://`            → HTTP+SSE (2024-11-05).
- *     Default for plain http URLs to preserve back-compat with users who
- *     already have `--mcp https://...` config entries pointed at SSE
- *     servers; opt into Streamable HTTP explicitly.
- *   - anything else                            → stdio (including ws://,
- *     which will surface later as a spawn error).
- */
+/** Plain http:// stays HTTP+SSE for back-compat; Streamable HTTP is opt-in via the `streamable+` URL prefix. */
 interface StdioMcpSpec {
     transport: "stdio";
     /** Namespace prefix applied to each registered tool, or null if anonymous. */
@@ -3529,16 +1686,7 @@ interface StreamableHttpMcpSpec {
 type McpSpec = StdioMcpSpec | SseMcpSpec | StreamableHttpMcpSpec;
 declare function parseMcpSpec(input: string): McpSpec;
 
-/**
- * Gather a full inspection report from an initialized MCP client:
- * server info, capabilities, tools, resources, prompts. Methods the
- * server doesn't support come back as `{ supported: false }` instead
- * of throwing, so a CLI or UI can render a consistent "what this
- * server exposes" summary even against minimal implementations.
- *
- * Pure with respect to I/O beyond the passed-in client — the CLI
- * layer owns argument parsing, connection setup, and printing.
- */
+/** Unsupported list methods surface as `{supported:false}` instead of throwing — minimal servers still get a clean report. */
 
 interface InspectionReport {
     protocolVersion: string;
@@ -3559,39 +1707,10 @@ type SectionResult<T> = {
     supported: false;
     reason: string;
 };
-/**
- * Run an inspection against a **already-initialized** client. Caller
- * is responsible for `initialize()` before this and `close()` after.
- * We keep this pure so unit tests can feed in a FakeMcpTransport and
- * verify the aggregate shape without spinning up a real process.
- */
+/** Caller owns initialize() / close() — keeps this pure so tests can feed a FakeMcpTransport. */
 declare function inspectMcpServer(client: McpClient): Promise<InspectionReport>;
 
-/**
- * Aider-style SEARCH/REPLACE edit blocks.
- *
- * The model emits blocks in this exact shape, one or more per response:
- *
- *   path/to/file.ts
- *   <<<<<<< SEARCH
- *   exact existing lines (whitespace-sensitive)
- *   =======
- *   replacement lines
- *   >>>>>>> REPLACE
- *
- * We chose this over unified diffs because:
- *   - Models produce it reliably — no line-number drift.
- *   - It tolerates multi-edit responses without ambiguity over which
- *     hunk belongs to which file.
- *   - Aider has years of evidence that this format works even against
- *     weaker models than DeepSeek R1, so it's a conservative pick.
- *
- * The SEARCH text must match the file byte-for-byte. Empty SEARCH is a
- * sentinel for "create new file" — the REPLACE becomes the whole file.
- * If SEARCH doesn't match we refuse the edit and surface the failure;
- * we do NOT guess or fuzzy-match. A wrong silent edit is worse than a
- * missing one — the user can re-ask with the exact current content.
- */
+/** SEARCH must match byte-for-byte; empty SEARCH = create new file. No fuzzy match — silent wrong edit beats a missing one. */
 interface EditBlock {
     /** Path as written by the model — relative to rootDir, or absolute. */
     path: string;
@@ -3627,42 +1746,13 @@ declare function applyEditBlocks(blocks: EditBlock[], rootDir: string): ApplyRes
 interface EditSnapshot {
     /** Path relative to rootDir, as the block named it. */
     path: string;
-    /**
-     * File content before the edit batch was applied. `null` means the
-     * file didn't exist yet — restoring that means deleting whatever the
-     * edit created.
-     */
+    /** `null` = file didn't exist; restore means delete. */
     prevContent: string | null;
 }
-/**
- * Capture the current state of every file an edit batch is about to
- * touch, so `/undo` can roll back if the user doesn't like the result.
- * De-duplicates by path because one batch can contain multiple blocks
- * for the same file, and we only want one "before" snapshot per file.
- */
+/** De-duped by path — one "before" snapshot per file even with multiple blocks. */
 declare function snapshotBeforeEdits(blocks: EditBlock[], rootDir: string): EditSnapshot[];
-/**
- * Restore files to their snapshotted state. Snapshots with
- * `prevContent === null` were created by the edit, so undo = delete.
- * Otherwise the prior content is written back, replacing whatever the
- * edit left behind.
- */
 declare function restoreSnapshots(snapshots: EditSnapshot[], rootDir: string): ApplyResult[];
 
-/**
- * System prompt used by `reasonix code`. Teaches the model:
- *
- *   1. It has a filesystem MCP bridge rooted at the user's CWD.
- *   2. To modify files it emits SEARCH/REPLACE blocks (not
- *      `write_file` — that would whole-file rewrite and kill diff
- *      reviewability).
- *   3. Read first, edit second — SEARCH must match byte-for-byte.
- *   4. Be concise. The user can read a diff faster than prose.
- *
- * Kept short on purpose. Long system prompts eat context budget that
- * the Cache-First Loop is trying to conserve. The SEARCH/REPLACE spec
- * is the one unavoidable bloat; we trim everything else.
- */
 declare const CODE_SYSTEM_PROMPT = "You are Reasonix Code, a coding assistant. You have filesystem tools (read_file, write_file, edit_file, list_directory, directory_tree, search_files, search_content, get_file_info) rooted at the user's working directory, plus run_command / run_background for shell.\n\n# Cite or shut up \u2014 non-negotiable\n\nEvery factual claim you make about THIS codebase must be backed by evidence. Reasonix VALIDATES the citations you write \u2014 broken paths or out-of-range lines render in **red strikethrough with \u274C** in front of the user.\n\n**Positive claims** (a file exists, a function does X, a feature IS implemented) \u2014 append a markdown link to the source:\n\n- \u2705 Correct: `The MCP client supports listResources [listResources](src/mcp/client.ts:142).`\n- \u274C Wrong:   `The MCP client supports listResources.` \u2190 no citation, looks authoritative but unverifiable.\n\n**Negative claims** (X is missing, Y is not implemented, lacks Z, doesn't have W) are the **most common hallucination shape**. They feel safe to write because no citation seems possible \u2014 but that's exactly why you must NOT write them on instinct.\n\nIf you are about to write \"X is missing\" or \"Y is not implemented\" \u2014 **STOP**. Call `search_content` for the relevant symbol or term FIRST. Only then:\n\n- If the search returns matches \u2192 you were wrong; correct yourself and cite the matches.\n- If the search returns nothing \u2192 state the absence with the search query as your evidence: `No callers of \\`foo()\\` found (search_content \"foo\").`\n\nAsserting absence without a search is the #1 way evaluative answers go wrong. Treat the urge to write \"missing\" as a red flag in your own reasoning.\n\n# When to propose a plan (submit_plan)\n\nYou have a `submit_plan` tool that shows the user a markdown plan and lets them Approve / Refine / Cancel before you execute. Use it proactively when the task is large enough to deserve a review gate:\n\n- Multi-file refactors or renames.\n- Architecture changes (moving modules, splitting / merging files, new abstractions).\n- Anything where \"undo\" after the fact would be expensive \u2014 migrations, destructive cleanups, API shape changes.\n- When the user's request is ambiguous and multiple reasonable interpretations exist \u2014 propose your reading as a plan and let them confirm.\n\nSkip submit_plan for small, obvious changes: one-line typo, clear bug with a clear fix, adding a missing import, renaming a local variable. Just do those.\n\nPlan body: one-sentence summary, then a file-by-file breakdown of what you'll change and why, and any risks or open questions. If some decisions are genuinely up to the user (naming, tradeoffs, out-of-scope possibilities), list them in an \"Open questions\" section \u2014 the user sees the plan in a picker and has a text input to answer your questions before approving. Don't pretend certainty you don't have; flagged questions are how the user tells you what they care about. After calling submit_plan, STOP \u2014 don't call any more tools, wait for the user's verdict.\n\n**Do NOT use submit_plan to present A/B/C route menus.** The approve/refine/cancel picker has no branch selector \u2014 a menu plan strands the user. For branching decisions, use `ask_choice` (see below); only call submit_plan once the user has picked a direction and you have ONE actionable plan.\n\n# When to ask the user to pick (ask_choice)\n\nYou have an `ask_choice` tool. **If the user is supposed to pick between alternatives, the tool picks \u2014 you don't enumerate the choices as prose.** Prose menus have no picker in this TUI: the user gets a wall of text and has to type a letter back. The tool fires an arrow-key picker that's strictly better.\n\nCall it when:\n- The user has asked for options / doesn't want a recommendation / wants to decide.\n- You've analyzed multiple approaches and the final call is theirs.\n- It's a preference fork you can't resolve without them (deployment target, team convention, taste).\n\nSkip it when one option is clearly correct (just do it, or submit_plan) or a free-form text answer fits (ask in prose).\n\nEach option: short stable id (A/B/C), one-line title, optional summary. `allowCustom: true` when their real answer might not fit. Max 6. A ~1-sentence lead-in before the call is fine (\"I see three directions \u2014 letting you pick\"); don't repeat the options in it. After the call, STOP.\n\n# Plan mode (/plan)\n\nThe user can ALSO enter \"plan mode\" via /plan, which is a stronger, explicit constraint:\n- Write tools (edit_file, write_file, create_directory, move_file) and non-allowlisted run_command calls are BOUNCED at dispatch \u2014 you'll get a tool result like \"unavailable in plan mode\". Don't retry them.\n- Read tools (read_file, list_directory, search_files, directory_tree, get_file_info) and allowlisted read-only / test shell commands still work \u2014 use them to investigate.\n- You MUST call submit_plan before anything will execute. Approve exits plan mode; Refine stays in; Cancel exits without implementing.\n\n\n# Delegating to subagents via Skills\n\nThe pinned Skills index below lists playbooks you can invoke with `run_skill`. Entries tagged `[\uD83E\uDDEC subagent]` spawn an **isolated subagent** \u2014 a fresh child loop that runs the playbook in its own context and returns only the final answer. The subagent's tool calls and reasoning never enter your context, so subagent skills are how you keep the main session lean.\n\n**When you call `run_skill`, the `name` is ONLY the identifier before the tag** \u2014 e.g. `run_skill({ name: \"explore\", arguments: \"...\" })`, NOT `\"[\uD83E\uDDEC subagent] explore\"` and NOT `\"explore [\uD83E\uDDEC subagent]\"`. The tag is display sugar; the name argument is just the bare identifier.\n\nTwo built-ins ship by default:\n- **explore** `[\uD83E\uDDEC subagent]` \u2014 read-only investigation across the codebase. Use when the user says things like \"find all places that...\", \"how does X work across the project\", \"survey the code for Y\". Pass `arguments` describing the concrete question.\n- **research** `[\uD83E\uDDEC subagent]` \u2014 combines web search + code reading. Use for \"is X supported by lib Y\", \"what's the canonical way to Z\", \"compare our impl to the spec\".\n\nWhen to delegate (call `run_skill` with a subagent skill):\n- The task would otherwise need >5 file reads or searches.\n- You only need the conclusion, not the exploration trail.\n- The work is self-contained (you can describe it in one paragraph).\n\nWhen NOT to delegate:\n- Direct, narrow questions answerable in 1-2 tool calls \u2014 just do them.\n- Anything where you need to track intermediate results yourself (planning, multi-step edits).\n- Anything that requires user interaction (subagents can't submit plans or ask you for clarification).\n\nAlways pass a clear, self-contained `arguments` \u2014 that text is the **only** context the subagent gets.\n\n# When to edit vs. when to explore\n\nOnly propose edits when the user explicitly asks you to change, fix, add, remove, refactor, or write something. Do NOT propose edits when the user asks you to:\n- analyze, read, explore, describe, or summarize a project\n- explain how something works\n- answer a question about the code\n\nIn those cases, use tools to gather what you need, then reply in prose. No SEARCH/REPLACE blocks, no file changes. If you're unsure what the user wants, ask.\n\nWhen you do propose edits, the user will review them and decide whether to `/apply` or `/discard`. Don't assume they'll accept \u2014 write as if each edit will be audited, because it will.\n\nReasonix runs an **edit gate**. The user's current mode (`review` or `auto`) decides what happens to your writes; you DO NOT see which mode is active, and you SHOULD NOT ask. Write the same way in both cases.\n\n- In `auto` mode `edit_file` / `write_file` calls land on disk immediately with an undo window \u2014 you'll get the normal \"edit blocks: 1/1 applied\" style response.\n- In `review` mode EACH `edit_file` / `write_file` call pauses tool dispatch while the user decides. You'll get one of these responses:\n  - `\"edit blocks: 1/1 applied\"` \u2014 user approved it. Continue as normal.\n  - `\"User rejected this edit to <path>. Don't retry the same SEARCH/REPLACE\u2026\"` \u2014 user said no to THIS specific edit. Do NOT re-emit the same block, do NOT switch tools to sneak it past the gate (write_file \u2192 edit_file, or text-form SEARCH/REPLACE). Either take a clearly different approach or stop and ask the user what they want instead.\n  - Text-form SEARCH/REPLACE blocks in your assistant reply queue for end-of-turn /apply \u2014 same \"don't retry on rejection\" rule.\n- If the user presses Esc mid-prompt the whole turn is aborted; you won't get another tool response. Don't keep spamming tool calls after an abort.\n\n# Editing files\n\nWhen you've been asked to change a file, output one or more SEARCH/REPLACE blocks in this exact format:\n\npath/to/file.ext\n<<<<<<< SEARCH\nexact existing lines from the file, including whitespace\n=======\nthe new lines\n>>>>>>> REPLACE\n\nRules:\n- Always read_file first so your SEARCH matches byte-for-byte. If it doesn't match, the edit is rejected and you'll have to retry with the exact current content.\n- One edit per block. Multiple blocks in one response are fine.\n- To create a new file, leave SEARCH empty:\n    path/to/new.ts\n    <<<<<<< SEARCH\n    =======\n    (whole file content here)\n    >>>>>>> REPLACE\n- Do NOT use write_file to change existing files \u2014 the user reviews your edits as SEARCH/REPLACE. write_file is only for files you explicitly want to overwrite wholesale (rare).\n- Paths are relative to the working directory. Don't use absolute paths.\n\n# Trust what you already know\n\nBefore exploring the filesystem to answer a factual question, check whether the answer is already in context: the user's current message, earlier turns in this conversation (including prior tool results from `remember`), and the pinned memory blocks at the top of this prompt. When the user has stated a fact or you have remembered one, it outranks what the files say \u2014 don't re-derive from code what the user already told you. Explore when you genuinely don't know.\n\n# Exploration\n\n- Skip dependency, build, and VCS directories unless the user explicitly asks. The pinned .gitignore block (if any, below) is your authoritative denylist.\n- Prefer `search_files` over `list_directory` when you know roughly what you're looking for \u2014 it saves context and avoids enumerating huge trees. Note: `search_files` matches file NAMES; for searching file CONTENTS use `search_content`.\n- Available exploration tools: `read_file`, `list_directory`, `directory_tree`, `search_files` (filename match), `search_content` (content grep \u2014 use for \"where is X called\", \"find all references to Y\"), `get_file_info`. Don't call `grep` or other tools that aren't in this list \u2014 they don't exist as functions.\n\n# Path conventions\n\nTwo different rules depending on which tool:\n\n- **Filesystem tools** (`read_file`, `list_directory`, `search_files`, `edit_file`, etc.): paths are sandbox-relative. `/` means the project root, `/src/foo.ts` means `<project>/src/foo.ts`. Both relative (`src/foo.ts`) and POSIX-absolute (`/src/foo.ts`) forms work.\n- **`run_command`**: the command runs in a real OS shell with cwd pinned to the project root. Paths inside the shell command are interpreted by THAT shell, not by us. **Never use leading `/` in run_command arguments** \u2014 Windows treats `/tests` as drive-root `F:\\tests` (non-existent), POSIX shells treat it as filesystem root. Use plain relative paths (`tests`, `./tests`, `src/loop.ts`) instead.\n\n# When the user wants to switch project / working directory\n\nIf the user asks to switch / change / open a different directory or project (\"\u5207\u6362\u5230...\", \"switch to ...\", \"let's work in ...\", \"open the X project\"), call **`change_workspace`** with the absolute target path. The tool always requires the user's explicit approval via a TUI modal \u2014 your call surfaces a \"switch / deny\" prompt, and STOPS your turn until they pick. After approval the filesystem / shell / memory tools re-register against the new root and your subsequent calls land there.\n\nHard rules:\n- Do NOT try to switch via `run_command` (`cd`, `pushd`, etc.) \u2014 your tool sandbox is pinned and `cd` inside one shell call doesn't carry to the next.\n- Do NOT chain other tool calls in the same turn as `change_workspace` \u2014 wait for the user's confirmation. Their next message will tell you whether the switch happened.\n- Do NOT call `change_workspace` to \"preview\" a sibling directory; only when the user explicitly asked to change projects.\n- The user can also type `/cwd <path>` themselves \u2014 fine, you'll see the new root take effect on the next turn either way.\n\n# Foreground vs. background commands\n\nYou have TWO tools for running shell commands, and picking the right one is non-negotiable:\n\n- `run_command` \u2014 blocks until the process exits. Use for: **tests, builds, lints, typechecks, git operations, one-shot scripts**. Anything that naturally returns in under a minute.\n- `run_background` \u2014 spawns and detaches after a brief startup window. Use for: **dev servers, watchers, any command with \"dev\" / \"serve\" / \"watch\" / \"start\" in the name**. Examples: `npm run dev`, `pnpm dev`, `yarn start`, `vite`, `next dev`, `uvicorn app:app --reload`, `flask run`, `python -m http.server`, `cargo watch`, `tsc --watch`, `webpack serve`.\n\n**Never use run_command for a dev server.** It will block for 60s, time out, and the user will see a frozen tool call while the server was actually running fine. Always `run_background`, then `job_output` to peek at the logs when you need to verify something.\n\nAfter `run_background`, tools available to you:\n- `job_output(jobId, tailLines?)` \u2014 read recent logs to verify startup / debug errors.\n- `list_jobs` \u2014 see every job this session (running + exited).\n- `stop_job(jobId)` \u2014 SIGTERM \u2192 SIGKILL after grace. Stop before switching port / config.\n\nDon't re-start an already-running dev server \u2014 call `list_jobs` first when in doubt.\n\n# Scope discipline on \"run it\" / \"start it\" requests\n\nWhen the user's request is to **run / start / launch / serve / boot up** something, your job is ONLY:\n\n1. Start it (`run_background` for dev servers, `run_command` for one-shots).\n2. Verify it came up (read a ready signal via `job_output`, or fetch the URL with `web_fetch` if they want you to confirm).\n3. Report what's running, where (URL / port / pid), and STOP.\n\nDo NOT, in the same turn:\n- Run `tsc` / type-checkers / linters unless the user asked for it.\n- Scan for bugs to \"proactively\" fix. The page rendering is success.\n- Clean up unused imports, dead code, or refactor \"while you're here.\"\n- Edit files to improve anything the user didn't mention.\n\nIf you notice an obvious issue, MENTION it in one sentence and wait for the user to say \"fix it.\" The cost of over-eagerness is real: you burn tokens, make surprise edits the user didn't want, and chain into cascading \"fix the new error I just introduced\" loops. The storm-breaker will cut you off, but the user still sees the mess.\n\n\"It works\" is the end state. Resist the urge to polish.\n\n# Style\n\n- Show edits; don't narrate them in prose. \"Here's the fix:\" is enough.\n- One short paragraph explaining *why*, then the blocks.\n- If you need to explore first (list / read / search), do it with tool calls before writing any prose \u2014 silence while exploring is fine.\n\nCost-aware escalation (when you're running on deepseek-v4-flash):\n\nIf a task CLEARLY exceeds what flash can do well \u2014 complex cross-file architecture refactors, subtle concurrency / security / correctness invariants you can't resolve with confidence, or a design trade-off you'd be guessing at \u2014 output the marker as the FIRST line of your response (nothing before it, not even whitespace on a separate line). This aborts the current call and retries this turn on deepseek-v4-pro, one shot.\n\nTwo accepted forms:\n- `<<<NEEDS_PRO>>>` \u2014 bare marker, no rationale.\n- `<<<NEEDS_PRO: <one-sentence reason>>>>` \u2014 preferred. The reason text appears in the user-visible warning (\"\u21E7 flash requested escalation \u2014 <your reason>\"), so they understand WHY a more expensive call is happening. Keep it under ~150 chars, no newlines, no nested `>` characters. Examples: `<<<NEEDS_PRO: cross-file refactor across 6 modules with circular imports>>>` or `<<<NEEDS_PRO: subtle session-token race; flash would likely miss the locking invariant>>>`.\n\nDo NOT emit any other content in the same response when you request escalation. Use this sparingly: normal tasks \u2014 reading files, small edits, clear bug fixes, straightforward feature additions \u2014 stay on flash. Request escalation ONLY when you would otherwise produce a guess or a visibly-mediocre answer. If in doubt, attempt the task on flash first; the system also escalates automatically if you hit 3+ repair / SEARCH-mismatch errors in a single turn (the user sees a typed breakdown).\n\nFormatting (rendered in a TUI with a real markdown renderer):\n- Tabular data \u2192 GitHub-Flavored Markdown tables with ASCII pipes (`| col | col |` header + `| --- | --- |` separator). Never use Unicode box-drawing characters (\u2502 \u2500 \u253C \u250C \u2510 \u2514 \u2518 \u251C \u2524) \u2014 they look intentional but break terminal word-wrap and render as garbled columns at narrow widths.\n- Keep table cells short (one phrase each). If a cell needs a paragraph, use bullets below the table instead.\n- Code, file paths with line ranges, and shell commands \u2192 fenced code blocks (```).\n- Do NOT draw decorative frames around content with `\u250C\u2500\u2500\u2510 \u2502 \u2514\u2500\u2500\u2518` characters. The renderer adds its own borders; extra ASCII art adds noise and shatters at narrow widths.\n- For flow charts and diagrams: a plain bullet list with `\u2192` or `\u2193` between steps. Don't try to draw boxes-and-arrows in ASCII; it never survives word-wrap.\n";
 interface CodeSystemPromptOptions {
     /** True when semantic_search is registered for this run. Adds an
@@ -3672,116 +1762,24 @@ interface CodeSystemPromptOptions {
 }
 declare function codeSystemPrompt(rootDir: string, opts?: CodeSystemPromptOptions): string;
 
-/**
- * User-level config storage for the Reasonix CLI.
- *
- * Lookup order for the API key:
- *   1. `DEEPSEEK_API_KEY` env var (highest priority — for CI / power users)
- *   2. `~/.reasonix/config.json` (set by the first-run setup flow)
- *
- * The library itself never touches the config file — it only reads
- * `DEEPSEEK_API_KEY` from the environment. The CLI is responsible for
- * pulling from the config file and exposing it via env var to the loop.
- *
- * Beyond the API key, the config also remembers the user's *defaults*
- * from `reasonix setup`: preset, MCP servers, session. This is what
- * makes `reasonix chat` with no flags "just work" after first-run.
- */
-/**
- * Preset names — three model-commitment levels.
- *   - `auto`  — flash baseline + auto-escalate to pro on hard turns
- *               (NEEDS_PRO marker / failure-count threshold both fire).
- *               Default. Closest match to the legacy `smart` preset.
- *   - `flash` — flash always. No auto-escalation. `/pro` still works
- *               for one-shot manual escalation. Cheapest predictable.
- *   - `pro`   — pro always. No downgrade. ~3× cost vs flash at the
- *               2026-04 discount rate; more outside the window.
- *
- * Legacy `fast | smart | max` names stay in the union for back-compat
- * with existing `~/.reasonix/config.json` files; resolvePreset() maps
- * them to the new semantics.
- */
+/** Library reads only DEEPSEEK_API_KEY from env; the CLI bridges config.json → env var. */
+/** Legacy `fast|smart|max` kept for back-compat with existing config.json files. */
 type PresetName = "auto" | "flash" | "pro" | "fast" | "smart" | "max";
-/**
- * How `reasonix code` handles model-issued tool calls. Two axes folded
- * into one enum because users think about "how trusting am I right now?"
- * as a single dial, not as "writes vs shell" pairs.
- *
- *   - "review" — queue edits into pendingEdits (user /apply or `y` to
- *                commit); shell commands NOT on the read-only allowlist
- *                hit ShellConfirm. Default.
- *   - "auto"   — apply edits immediately, snapshot for /undo, show a
- *                short undo banner. Shell still goes through ShellConfirm
- *                for non-allowlisted commands.
- *   - "yolo"   — apply edits immediately AND auto-approve every shell
- *                command. No prompts at all. Use when you trust the
- *                current direction and just want to iterate fast; /undo
- *                still rolls back individual edit batches.
- *
- * Persisted so `/mode <x>` survives a relaunch. Missing → "review".
- *
- * Codex-equivalence note: review ≈ untrusted, auto ≈ on-request,
- * yolo ≈ never.
- */
+/** Single trust dial: review queues edits + gates shell; auto applies + gates shell; yolo skips both gates. */
 type EditMode = "review" | "auto" | "yolo";
-/**
- * reasoning_effort cap for the model. "max" is the agent-class default;
- * "high" is cheaper / faster. Persisted so `/effort high` survives a
- * relaunch — earlier versions silently reverted to "max" on every new
- * session, which burned budget unexpectedly.
- */
 type ReasoningEffort = "high" | "max";
 interface ReasonixConfig {
     apiKey?: string;
     baseUrl?: string;
-    /**
-     * Default preset for `reasonix chat` / `reasonix run` when no flags override.
-     * Maps to model + autoEscalate (see presets.ts). Missing → "auto".
-     */
     preset?: PresetName;
-    /**
-     * Edit-gate mode for `reasonix code`. See EditMode doc. Absent → "review".
-     */
     editMode?: EditMode;
-    /**
-     * Set to `true` the first time we've shown the "Shift+Tab cycles
-     * review/AUTO" onboarding tip in `reasonix code`. Once seen, we stop
-     * posting the tip — the bottom status bar carries the knowledge
-     * forward without further nagging.
-     */
     editModeHintShown?: boolean;
-    /**
-     * Last reasoning_effort chosen via `/effort`. Loaded on launch so
-     * "high" stays "high" — default is "max" when unset.
-     */
     reasoningEffort?: ReasoningEffort;
-    /**
-     * Default MCP server specs to bridge on every `reasonix chat`, in the
-     * same `"name=cmd args..."` format that `--mcp` takes. Stored as strings
-     * so `reasonix setup` stays symmetrical with the flag — one parser, one
-     * format in the config file, grep-friendly.
-     */
+    /** Stored as `--mcp`-format strings so one parser handles both flag and config. */
     mcp?: string[];
-    /**
-     * Default session name (null/missing → "default", which is what the
-     * CLI has been doing anyway). `reasonix setup` lets users pick a name
-     * or opt into ephemeral.
-     */
     session?: string | null;
-    /** Marks that `reasonix setup` has completed at least once. */
     setupCompleted?: boolean;
-    /**
-     * Whether `web_search` + `web_fetch` tools are registered. Default:
-     * enabled (no key required — backed by DuckDuckGo's public HTML
-     * endpoint). Set to `false` to keep the session offline.
-     */
     search?: boolean;
-    /**
-     * Per-project state keyed by absolute directory path. Written by the
-     * "always allow" choice on a shell confirmation prompt; merged into
-     * `registerShellTools({ extraAllowed })` when `reasonix code` runs
-     * against that directory again.
-     */
     projects?: {
         [absoluteRootDir: string]: {
             shellAllowed?: string[];
@@ -3798,27 +1796,7 @@ declare function isPlausibleKey(key: string): boolean;
 /** Mask a key for display: `sk-abcd...wxyz`. */
 declare function redactKey(key: string): string;
 
-/**
- * Version module.
- *
- * Two jobs:
- *
- *   1. Expose `VERSION` sourced from the real `package.json` so the
- *      constant never drifts from what npm publishes. Works in dev
- *      (`tsx src/...`) AND after `tsup` bundles to `dist/` — both
- *      layouts sit two levels below the manifest, so a short
- *      walk-up finds it.
- *
- *   2. Offer an opt-in `getLatestVersion()` that hits the npm
- *      registry with a bounded timeout and a 24-hour on-disk
- *      cache at `~/.reasonix/version-cache.json`. Returns `null`
- *      on any failure — offline / restricted-network launches
- *      should stay silent rather than nag the user.
- *
- * The CLI wires `getLatestVersion` asynchronously at App mount
- * (never in a hot path) and renders the outcome in the stats
- * panel when there's a newer published version.
- */
+/** VERSION sourced from package.json so it never drifts from npm; latest-check returns null on any failure. */
 /** TTL for the on-disk cache entry. 24h keeps noise low; users who
  * want a fresh check can run `reasonix update` which passes
  * `force: true`. */
@@ -3840,71 +1818,14 @@ interface GetLatestVersionOptions {
     /** Network timeout override (tests). */
     timeoutMs?: number;
 }
-/**
- * Resolve the latest published `reasonix` version from the npm registry.
- *
- * Returns `null` on any network / parse failure. Callers treat `null`
- * as "don't know, don't nag the user." The cache entry is only
- * written on a successful fetch — a bad registry response won't
- * poison the cache.
- */
+/** Returns null on failure; cache only writes on success so bad responses can't poison it. */
 declare function getLatestVersion(opts?: GetLatestVersionOptions): Promise<string | null>;
-/**
- * Semver compare. Returns a negative number when `a < b`, positive
- * when `a > b`, zero when equal.
- *
- * Minimal pre-release handling: when the CORE (`x.y.z`) parts match,
- * any version WITH a suffix (`-rc.1`, `-alpha.4`) compares LOWER
- * than the bare version. That matches npm's dist-tag semantics —
- * `reasonix@latest` resolves to a real release, not a pre-release.
- *
- * We're deliberately not pulling in `semver` (~50KB). The three
- * cases we care about are: current > latest (future build, no
- * prompt), current < latest (prompt), current === latest (no prompt).
- */
+/** Pre-release with same core sorts BELOW the bare version — matches npm `latest` dist-tag semantics. */
 declare function compareVersions(a: string, b: string): number;
-/**
- * Heuristic: did this process launch via `npx` / `pnpm dlx` instead
- * of a global install? The update command takes different advice in
- * each case — a global install can `npm i -g reasonix@latest`, while
- * npx just needs its cache to roll over on next launch.
- *
- * Signals checked, in order:
- *   - `process.argv[1]` contains `_npx` (npm's ephemeral dir name)
- *   - `process.argv[1]` contains `.pnpm` + `dlx`
- *   - `npm_config_user_agent` contains `npx/`
- *
- * Any one hit → npx. False negatives are safe (worst case we suggest
- * `npm i -g` to an npx user, which is a valid way to upgrade too).
- */
+/** False negatives are safe — `npm i -g` works for npx users too. */
 declare function isNpxInstall(): boolean;
 
-/**
- * Persistent per-turn usage log at `~/.reasonix/usage.jsonl`.
- *
- * Each line is a single `UsageRecord` — one turn's tokens + cost
- * snapshot — appended after every `assistant_final` event. This is
- * what drives `reasonix stats` (the dashboard, no-arg form), so the
- * user can see how much they've spent vs what the equivalent Claude
- * spend would have been. The Pillar 1 pitch (94–97% cost reduction
- * vs Claude, from the v0.3 hard-number table) becomes a fact users
- * can verify on their own machine.
- *
- * Format choices:
- *   - **append-only JSONL** — one line per turn, durable, survives
- *     abrupt exits. A corrupted tail line loses at most one record.
- *   - **flat keys, no nesting** — readable with `jq` / `cut` / `awk`;
- *     the model doesn't need to parse this, humans do.
- *   - **best-effort writes** — disk errors never propagate into the
- *     turn. We log nothing (no `console.error`) because the TUI is
- *     rendering Ink; a silent skip is the least-worst failure mode.
- *   - **no PII, no prompts, no completions** — the log contains
- *     tokens and costs, that's it. Sessions are identified by the
- *     user-chosen name (never a prompt).
- *
- * This file is deliberately NOT wired through project memory or
- * skills — those are content pins. Usage is pure telemetry.
- */
+/** Append-only JSONL of per-turn tokens + cost; best-effort writes, never blocks the turn. No prompts/completions logged. */
 
 /** One turn's snapshot — serialized verbatim as a JSONL line. */
 interface UsageRecord {
@@ -3922,10 +1843,7 @@ interface UsageRecord {
     costUsd: number;
     /** What the same turn would have cost at Claude Sonnet 4.6 rates. */
     claudeEquivUsd: number;
-    /**
-     * Distinguishes ordinary parent-loop turns from subagent summary rows.
-     * Absent on pre-0.5.14 records — treat as "turn" when missing.
-     */
+    /** Absent on legacy records — treat as "turn" when missing. */
     kind?: "turn" | "subagent";
     /** Present when `kind === "subagent"`. Attribution metadata for the /stats roll-up. */
     subagent?: {
@@ -3953,26 +1871,8 @@ interface AppendUsageInput {
     kind?: "turn" | "subagent";
     subagent?: UsageRecord["subagent"];
 }
-/**
- * Append one record and return it. Swallows disk errors — the TUI
- * should keep working even if `~/.reasonix/` is read-only.
- *
- * Returns the record that was written (or would have been written
- * if the disk had cooperated) so tests / callers can assert on the
- * computed cost fields without a round trip through the log file.
- *
- * On every Nth append the log is checked for size; if it crosses
- * {@link USAGE_COMPACTION_THRESHOLD_BYTES} we drop records older
- * than {@link USAGE_RETENTION_DAYS}. Cheaper than a startup-time
- * scan because most processes don't reach the threshold; the size
- * check is one statSync regardless.
- */
+/** Returns the record so tests can assert cost fields without re-reading the log. */
 declare function appendUsage(input: AppendUsageInput): UsageRecord;
-/**
- * Read + parse the log. Malformed lines are silently skipped so a
- * single corrupted write (half-flushed on power loss, user hand-edit)
- * doesn't throw away the rest of the history.
- */
 declare function readUsageLog(path?: string): UsageRecord[];
 /** One row of the `reasonix stats` dashboard — a rolled-up window. */
 interface UsageBucket {
@@ -3986,15 +1886,7 @@ interface UsageBucket {
     cacheMissTokens: number;
     costUsd: number;
     claudeEquivUsd: number;
-    /**
-     * USD that DeepSeek's prompt cache shaved off the bill — sum of
-     * `cacheHitTokens × (missPrice − hitPrice)` per record. Recomputed
-     * from the current pricing table on every aggregate, not frozen at
-     * write time, so a price-cut announcement updates retroactively. The
-     * trade-off is mild inconsistency with `costUsd` (which IS frozen);
-     * acceptable because cache savings is a "what does this mechanism
-     * give me" narrative, not a billing record.
-     */
+    /** Recomputed from current pricing each aggregate — intentionally NOT frozen with `costUsd`. */
     cacheSavingsUsd: number;
 }
 /** Cache hit ratio for a bucket — zero denominator returns 0. */
@@ -4022,11 +1914,7 @@ interface UsageAggregate {
     firstSeen: number | null;
     /** Latest record's ts, or `null` when the log is empty. */
     lastSeen: number | null;
-    /**
-     * Subagent-specific rollup. Undefined when no subagent records exist
-     * in the log so consumers can cheaply skip the section. Counts reflect
-     * subagent SPAWNS (not internal child-loop turns) — one row per run.
-     */
+    /** Undefined when no subagent records exist; counts spawns, not internal child-loop turns. */
     subagents?: SubagentAggregate;
 }
 /** Rolled-up view of all `kind: "subagent"` records. */
@@ -4042,15 +1930,7 @@ interface SubagentAggregate {
         durationMs: number;
     }>;
 }
-/**
- * Fold a flat record list into the dashboard shape — rolling windows
- * plus model / session histograms. Windows are INCLUSIVE of boundary:
- *   - today = last 24h (rolling, not calendar-day)
- *   - week  = last 7d
- *   - month = last 30d
- *   - all   = every record
- * Rolling windows avoid "it's 00:03, 'today' is empty" surprises.
- */
+/** Rolling 24h/7d/30d windows — avoids "it's 00:03, 'today' is empty" surprises. */
 declare function aggregateUsage(records: UsageRecord[], opts?: AggregateOptions): UsageAggregate;
 /** File-size helper for the stats header — "1.2 MB" etc. Returns "" if missing. */
 declare function formatLogSize(path?: string): string;