@oh-my-pi/pi-coding-agent 17.0.9 → 17.1.0

package/dist/types/session/turn-recovery.d.ts

@@ -0,0 +1,225 @@
+import { type Agent, type AgentMessage, type ThinkingLevel } from "@oh-my-pi/pi-agent-core";
+import type { AssistantMessage, CodexCompactionContext, Model, ToolChoice } from "@oh-my-pi/pi-ai";
+import type { ModelRegistry } from "../config/model-registry.js";
+import type { Settings } from "../config/settings.js";
+import type { ConfiguredThinkingLevel } from "../thinking.js";
+import type { AgentSessionEvent } from "./agent-session-events.js";
+import type { InitialRetryFallbackState } from "./agent-session-types.js";
+import { type RetryFallbackSelector } from "./retry-fallback-chains.js";
+import type { SessionManager } from "./session-manager.js";
+/** Result shape shared with automatic maintenance recovery. */
+export interface RecoveryCompactionResult {
+    deferredHandoff: boolean;
+    continuationScheduled: boolean;
+    automaticContinuationBlocked?: boolean;
+    historyRewritten?: boolean;
+}
+/** Capabilities borrowed from the owning AgentSession. */
+export interface TurnRecoveryHost {
+    agent: Agent;
+    sessionManager: SessionManager;
+    settings: Settings;
+    modelRegistry: ModelRegistry;
+    configWarnings: string[];
+    model(): Model | undefined;
+    thinkingLevel(): ThinkingLevel | undefined;
+    configuredThinkingLevel(): ConfiguredThinkingLevel | undefined;
+    setThinkingLevel(level: ConfiguredThinkingLevel | undefined): void;
+    isDisposed(): boolean;
+    isStreaming(): boolean;
+    isCompacting(): boolean;
+    abortInProgress(): boolean;
+    streamingEditAbortTriggered(): boolean;
+    promptGeneration(): number;
+    sessionId(): string;
+    emitSessionEvent(event: AgentSessionEvent): Promise<void>;
+    scheduleAgentContinue(options: {
+        delayMs?: number;
+        generation?: number;
+    }): void;
+    waitForSessionMessagePersistence(message: AssistantMessage): Promise<void>;
+    appendSessionMessage(message: AssistantMessage): void;
+    sessionMessageAlreadyPersisted(message: AssistantMessage): boolean;
+    setModelWithProviderSessionReset(model: Model): void;
+    resetCurrentResponsesProviderSession(reason: string): void;
+    maybeAutoRedeemCodexReset(): Promise<boolean>;
+    runAutoCompaction(reason: "overflow" | "threshold" | "idle" | "incomplete", willRetry: boolean, deferred?: boolean, allowDefer?: boolean, options?: {
+        autoContinue?: boolean;
+        triggerContextTokens?: number;
+        suppressContinuation?: boolean;
+        suppressHandoff?: boolean;
+        phase?: CodexCompactionContext["phase"];
+        terminalTextAnswer?: boolean;
+    }): Promise<RecoveryCompactionResult>;
+    withBashBranchTransition<T>(operation: () => T): T;
+}
+/** Construction-time retry state restored from model selection. */
+export interface TurnRecoveryOptions {
+    initialRetryFallback?: InitialRetryFallbackState;
+}
+/** Owns terminal-stop recovery, automatic retries, and fallback routing. */
+export declare class TurnRecovery {
+    #private;
+    constructor(host: TurnRecoveryHost, options?: TurnRecoveryOptions);
+    /** Current automatic retry attempt. */
+    get attempt(): number;
+    /** Promise settled when the active retry saga finishes. */
+    get retryPromise(): Promise<void> | undefined;
+    /** Resolved selector while fallback routing owns the current model. */
+    get retryFallbackModel(): string | undefined;
+    /** Resets per-prompt recovery counters and terminal-stop acceptance. */
+    resetForNewPrompt(): void;
+    /** Sets whether one terminal empty stop is accepted for the current prompt. */
+    setAcceptTerminalEmptyStop(accept: boolean): void;
+    /** Closes a successful retry saga and annotates recovered persisted errors. */
+    onAssistantSettledSuccessfully(message: AssistantMessage): Promise<void>;
+    /** Closes a failed retry saga when no compaction continuation took ownership. */
+    onErrorSettledWithoutRetry(message: AssistantMessage, compaction: RecoveryCompactionResult): Promise<void>;
+    /** Persists an otherwise skipped terminal empty error turn. */
+    persistTerminalEmptyErrorTurn(message: AssistantMessage): Promise<void>;
+    /** Handles empty terminal assistant turns and schedules bounded recovery. */
+    handleEmptyAssistantStop(message: AssistantMessage): Promise<boolean>;
+    /** Classifies suspicious terminal stops and schedules bounded recovery. */
+    handleUnexpectedAssistantStop(message: AssistantMessage): Promise<boolean>;
+    /** Removes a persisted failed assistant turn after its persistence slot settles. */
+    dropPersistedAssistantTurn(message: AssistantMessage): Promise<void>;
+    /** Runs recovery compaction and restores the failed turn when no rewrite occurs. */
+    runRecoveryCompactionWithRollback(reason: "overflow" | "incomplete", message: AssistantMessage, allowDefer: boolean, options: {
+        autoContinue: boolean;
+        triggerContextTokens?: number;
+    }): Promise<RecoveryCompactionResult>;
+    /** Restores the configured primary after fallback cooldown expiry. */
+    maybeRestoreRetryFallbackPrimary(): Promise<void>;
+    /** Applies automatic retry, credential rotation, and model fallback policy. */
+    handleRetryableError(message: AssistantMessage, options?: {
+        allowModelFallback?: boolean;
+        fireworksFastFallback?: boolean;
+        hardErrorFallback?: boolean;
+        preserveFailedTurn?: boolean;
+    }): Promise<boolean>;
+    /** Prompts after transient overlap with a prior agent run. */
+    promptAgentWithIdleRetry(messages: AgentMessage[], options?: {
+        toolChoice?: ToolChoice;
+    }): Promise<void>;
+    /** Parses provider retry and rate-limit reset hints into a delay. */
+    parseRetryAfterMsFromError(errorMessage: string): number | undefined;
+    /** Resolve the pending retry promise */
+    resolveRetry(): void;
+    removeAssistantMessageFromActiveContext(assistantMessage: AssistantMessage, reason?: string): void;
+    /**
+     * Drop an assistant turn from BOTH the live agent context and the persisted
+     * session branch (reparenting the leaf to the turn's parent), so a discarded
+     * turn does not resurface on reload. Used for empty/reasoning-only stops and
+     * the Gemini header-runaway interrupt, which must not replay a partial,
+     * loop-fueling thinking block.
+     */
+    discardAssistantTurn(assistantMessage: AssistantMessage): void;
+    /**
+     * Retry an empty, reason-less provider abort: a turn with no content that
+     * carries the generic sentinel (bare `abort()`), whether the provider
+     * finalized it as `stopReason: "aborted"` or leaked it as `stopReason:
+     * "error"` (a stalled/dropped stream reported as an error rather than an
+     * abort — issue #5375). Only fires while the session is neither aborting nor
+     * tearing down. A user/lifecycle abort (`#abortInProgress`), a dispose-driven
+     * abort (`#isDisposed`), or a session-induced streaming-edit guard abort
+     * (`StreamingEditGuard.abortTriggered` — auto-generated-file guard or failed-patch
+     * preview) is deliberate and MUST settle the turn instead: routing it through
+     * retry would orphan `#retryPromise` on a continuation the guard skips
+     * (hanging the in-flight `prompt()`) or silently undo the guard's intended
+     * abort. Deliberate user interrupts (`UserInterrupt`) and silent aborts carry
+     * their own marker, not the generic sentinel, so they never match here.
+     */
+    isRetryableReasonlessAbort(message: AssistantMessage): boolean;
+    /**
+     * Check if an error is retryable (transient errors or usage limits).
+     * Context overflow is NOT retryable (handled by compaction instead).
+     * Usage-limit errors are retryable because the retry handler performs credential switching.
+     */
+    isRetryableError(message: AssistantMessage): boolean;
+    /**
+     * Resume a stalled turn after every emitted tool call has produced a result.
+     * Cursor calls must also carry the server-execution marker. The failed
+     * assistant/tool-result pair stays in context so completed side effects are
+     * continued from rather than replayed.
+     */
+    canResumeResolvedStreamStall(message: AssistantMessage): boolean;
+    /** Checks whether a provider error represents a classifier refusal. */
+    isClassifierRefusal(message: AssistantMessage): boolean;
+    /** Clears fallback ownership after an explicit model change. */
+    clearActiveRetryFallback(): void;
+    /** Checks whether a fallback selector remains in cooldown. */
+    isRetryFallbackSelectorSuppressed(selector: RetryFallbackSelector): boolean;
+    /** Records the cooldown that should suppress a failing selector. */
+    noteRetryFallbackCooldown(currentSelector: string, retryAfterMs: number | undefined, errorMessage: string): void;
+    /**
+     * Map the failing model selector to the chain key that owns it, by
+     * specificity: an exact model-selector key, then a `provider/*` wildcard,
+     * then a model role whose current assignment matches, then `default`.
+     * Model-oriented keys win over roles so a chain follows the model across
+     * role reassignments.
+     */
+    resolveRetryFallbackRole(currentSelector: string, currentModel?: Model | null | undefined): string | undefined;
+    /** Finds fallback candidates that follow the active selector. */
+    findRetryFallbackCandidates(role: string, currentSelector: string, currentModel?: Model | null | undefined): RetryFallbackSelector[];
+    applyRetryFallbackCandidate(role: string, selector: RetryFallbackSelector, currentSelector: string, options?: {
+        pinFallback?: boolean;
+        apiKey?: string;
+        signal?: AbortSignal;
+    }): Promise<void>;
+    /**
+     * True when the current turn failed on a Fireworks Fast (`-fast`) model in a
+     * way that should degrade to the reliable base (Standard) model. Fast is a
+     * speed-optimized router with no SLA, so any *pre-content* failure — a
+     * transient overload/5xx or a hard "router/model not found / unsupported" —
+     * is worth retrying on the base id. Skips failures the base model shares:
+     * context overflow (compaction's job), usage limits and auth errors (same
+     * account/key), and turns that already emitted a tool call (replaying would
+     * duplicate work). Requires the base model to exist in the registry.
+     */
+    isFireworksFastFallbackEligible(message: AssistantMessage): boolean;
+    /**
+     * True when a turn failed with a hard (non-retryable) provider error but a
+     * configured `retry.fallbackChains` entry covers the active model: the same
+     * model is not worth retrying, yet a DIFFERENT model is a fresh chance, so
+     * the chain is consulted before the error becomes final. Skips failures a
+     * model switch cannot fix or must not replay: cancellations (abort-flavored
+     * errors are not model faults), context overflow (compaction's job),
+     * classifier refusals (chain consult is handled on the retryable path with
+     * `pinFallback`), and turns that already emitted a tool call (replaying
+     * could duplicate work).
+     */
+    isHardErrorFallbackEligible(message: AssistantMessage): boolean;
+    /**
+     * Cancel in-progress retry.
+     */
+    abortRetry(): void;
+    /** Whether auto-retry is currently in progress */
+    get isRetrying(): boolean;
+    /** Whether auto-retry is enabled */
+    get autoRetryEnabled(): boolean;
+    /**
+     * Toggle auto-retry setting.
+     */
+    setAutoRetryEnabled(enabled: boolean): void;
+    /**
+     * Manually retry the last failed assistant turn.
+     * Removes the error message from active agent state when present and
+     * re-attempts with a fresh retry budget.
+     *
+     * A stream that stalls or aborts mid-tool-call ends the turn with
+     * `stopReason: "error" | "aborted"` and then appends one synthetic
+     * {@link isSyntheticToolResultMessage tool_result} per emitted tool call to
+     * preserve the provider's tool_use/tool_result pairing (see
+     * `createAbortedToolResult` in `agent-loop.ts`). Those placeholders trail the
+     * failed assistant turn, so the retry lookback walks back over them before
+     * checking the assistant message; it strips both the placeholders and the
+     * failed turn before re-attempting.
+     *
+     * A restored session deliberately omits failed assistant turns from provider
+     * context. In that case, the persisted display transcript remains the source
+     * of truth for whether the current branch has a retryable failed tail.
+     *
+     * @returns true if retry was initiated, false if no failed turn to retry or agent is busy
+     */
+    retry(): Promise<boolean>;
+}

package/dist/types/system-prompt.d.ts

@@ -72,6 +72,8 @@ export interface BuildSystemPromptOptions {
     skillsSettings?: SkillsSettings;
     /** Working directory. Default: getProjectDir() */
     cwd?: string;
+    /** Additional workspace directories beyond cwd (multi-root), absolute. Injected into the project prompt. */
+    additionalWorkspaceRoots?: string[];
     /** Pre-loaded context files (skips discovery if provided). */
     contextFiles?: Array<{
         path: string;

package/dist/types/task/executor.d.ts

@@ -17,6 +17,7 @@ import type { HindsightSessionState } from "../hindsight/state.js";
 import type { LocalProtocolOptions } from "../internal-urls/index.js";
 import type { MCPManager } from "../mcp/manager.js";
 import type { MnemopiSessionState } from "../mnemopi/state.js";
+import { type AgentReviver } from "../registry/agent-lifecycle.js";
 import type { AgentSession } from "../session/agent-session.js";
 import type { ArtifactManager } from "../session/artifacts.js";
 import type { AuthStorage } from "../session/auth-storage.js";
@@ -44,6 +45,8 @@ export declare function buildBudgetNotice(requests: number, budget: number): str
 /** Options for subagent execution */
 export interface ExecutorOptions {
     cwd: string;
+    /** Additional workspace directories to seed on the subagent session (multi-root). */
+    additionalDirectories?: string[];
     worktree?: string;
     agent: AgentDefinition;
     task: string;
@@ -249,7 +252,7 @@ export declare function finalizeSubagentLifecycle(args: {
     keepAlive: boolean;
     isolated: boolean;
     agentIdleTtlMs: number;
-    reviveSession: (() => Promise<AgentSession>) | null;
+    reviveSession: AgentReviver | null;
 }): Promise<void>;
 /** Options for {@link runSubagentFollowUpTurn}. */
 export interface FollowUpTurnOptions {

package/dist/types/task/output-manager.d.ts

@@ -3,13 +3,15 @@
  *
  * The first allocation of a given name keeps the name as-is; subsequent
  * allocations of the same name get a `-2`, `-3`, … suffix. On resume, scans
- * existing output files so previously written outputs are never overwritten.
+ * existing output and child-session files so prior state is never overwritten.
  */
 export declare class AgentOutputManager {
     #private;
     constructor(getArtifactsDir: () => string | null, options?: {
         parentPrefix?: string;
     });
+    /** Reserve final IDs discovered outside the output directory scan. */
+    reserve(ids: Iterable<string>): Promise<void>;
     /**
      * Allocate a unique ID.
      *

package/dist/types/tools/approval.d.ts

@@ -16,6 +16,7 @@ export interface ResolvedApproval {
     tier: ToolTier;
     reason?: string;
     override: boolean;
+    source?: "tool" | "user" | "mode";
 }
 /**
  * Evaluate a tool's own approval declaration against `args` and return the

package/dist/types/tools/browser/launch.d.ts

@@ -14,6 +14,7 @@ export declare const BROWSER_PROTOCOL_TIMEOUT_MS = 60000;
 export declare function loadPuppeteer(): Promise<typeof Puppeteer>;
 export declare function loadPuppeteerInWorker(safeDir: string): Promise<typeof Puppeteer>;
 export declare function ensureChromiumExecutable(): Promise<string | undefined>;
+/** Options shared by headless Chromium consumers. */
 export interface LaunchHeadlessOptions {
     headless: boolean;
     viewport?: {
@@ -21,6 +22,10 @@ export interface LaunchHeadlessOptions {
         height: number;
         deviceScaleFactor?: number;
     };
+    /** Additional Chromium arguments merged with the centralized launch defaults. */
+    args?: readonly string[];
+    /** Additional exact Puppeteer default arguments to suppress. */
+    ignoreDefaultArgs?: readonly string[];
 }
 export declare function launchHeadlessBrowser(opts: LaunchHeadlessOptions): Promise<Browser>;
 export declare function applyViewport(page: Page, viewport?: {

package/dist/types/tools/image-gen.d.ts

@@ -1,7 +1,8 @@
 import { type Model } from "@oh-my-pi/pi-ai";
 import { type ModelRegistry } from "../config/model-registry.js";
 import type { CustomTool } from "../extensibility/custom-tools/types.js";
-export type ImageProvider = "antigravity" | "gemini" | "openai" | "openai-codex" | "openrouter" | "xai";
+import { type ImageProvider } from "./image-providers.js";
+export type { ImageProvider } from "./image-providers.js";
 export type ImageProviderPreference = ImageProvider | "auto";
 declare const responseModalitySchema: import("arktype/internal/variants/string.ts").StringType<"IMAGE" | "TEXT", {}>;
 export declare const imageGenSchema: import("arktype/internal/variants/object.ts").ObjectType<{
@@ -59,9 +60,8 @@ interface InlineImageData {
     mimeType: string;
 }
 export declare function isImageProviderPreference(value: unknown): value is ImageProviderPreference;
-/** Set the preferred image provider from settings */
-export declare function setPreferredImageProvider(provider: ImageProviderPreference): void;
+/** Set the configured image-provider priority from settings; invalid IDs are dropped. */
+export declare function setImageProviderOrder(providers: readonly string[]): void;
 export declare const imageGenTool: CustomTool<typeof imageGenSchema, ImageGenToolDetails>;
 export declare function getImageGenTools(_modelRegistry?: ModelRegistry, _activeModel?: Model): Promise<Array<CustomTool<typeof imageGenSchema, ImageGenToolDetails>>>;
 export declare function getImageGenToolsWithRegistry(_modelRegistry: ModelRegistry, _activeModel?: Model): Promise<Array<CustomTool<typeof imageGenSchema, ImageGenToolDetails>>>;
-export {};

package/dist/types/tools/image-providers.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Image Generation Providers
+ *
+ * Leaf module (no runtime deps) shared by the image_gen tool, the settings
+ * schema, and settings migrations — mirrors `web/search/types.ts` so the
+ * provider list, auto order, and settings choices never drift apart.
+ */
+/** Image generation backends, in settings/tool vocabulary. */
+export type ImageProvider = "antigravity" | "gemini" | "openai" | "openai-codex" | "openrouter" | "xai";
+/** Auto-resolution fallback order when no configured entry or session provider matches. */
+export declare const AUTO_IMAGE_PROVIDER_ORDER: readonly ImageProvider[];
+/** Settings choices for `providers.imageOrder` (labels shared with the retired single-preference enum). */
+export declare const IMAGE_PROVIDER_CHOICES: readonly [{
+    readonly value: "openai";
+    readonly label: "OpenAI";
+    readonly description: "OPENAI_API_KEY (gpt-image-2) or active GPT model; falls back to a connected Codex subscription";
+}, {
+    readonly value: "openai-codex";
+    readonly label: "OpenAI Codex (ChatGPT)";
+    readonly description: "Uses a connected Codex / ChatGPT subscription — no OPENAI_API_KEY needed";
+}, {
+    readonly value: "antigravity";
+    readonly label: "Antigravity";
+    readonly description: "Requires google-antigravity OAuth";
+}, {
+    readonly value: "xai";
+    readonly label: "xAI Grok Imagine";
+    readonly description: "Requires xAI Grok OAuth or XAI_API_KEY";
+}, {
+    readonly value: "gemini";
+    readonly label: "Gemini";
+    readonly description: "Requires GEMINI_API_KEY";
+}, {
+    readonly value: "openrouter";
+    readonly label: "OpenRouter";
+    readonly description: "Requires OPENROUTER_API_KEY";
+}];
+export declare function isImageProviderId(value: unknown): value is ImageProvider;

package/dist/types/tools/index.d.ts

@@ -19,6 +19,7 @@ import type { ArtifactManager } from "../session/artifacts.js";
 import type { ClientBridge } from "../session/client-bridge.js";
 import type { CustomMessage } from "../session/messages.js";
 import type { UsageStatistics } from "../session/session-entries.js";
+import type { SessionManager } from "../session/session-manager.js";
 import type { ToolChoiceQueue } from "../session/tool-choice-queue.js";
 import type { AgentOutputManager } from "../task/output-manager.js";
 import { type StructuredSubagentSchemaMode } from "../task/types.js";
@@ -106,6 +107,8 @@ export interface DeferredDiagnosticsEntry {
 export interface ToolSession {
     /** Current working directory */
     cwd: string;
+    /** Additional workspace directories beyond cwd (multi-root), forwarded to subagents. */
+    additionalDirectories?: string[];
     /** Whether UI is available */
     hasUI: boolean;
     /**
@@ -177,6 +180,8 @@ export interface ToolSession {
     getEvalSessionId?: () => string | null;
     /** Get session file */
     getSessionFile: () => string | null;
+    /** Parent session journal used by tools that persist runtime lifecycle state. */
+    sessionManager?: Pick<SessionManager, "appendCustomEntry" | "ensureOnDisk" | "flush" | "getBranch" | "getEntries">;
     /** Get eval kernel owner ID for session-scoped retained-kernel cleanup. */
     getEvalKernelOwnerId?: () => string | null;
     /** Reject new eval work once session disposal has started. */

package/dist/types/tools/path-utils.d.ts

@@ -236,6 +236,14 @@ export declare function partitionExistingPaths(items: string[], cwd: string, spl
     basePath: string;
 }): Promise<PartitionedPaths>;
 export declare function resolveReadPath(filePath: string, cwd: string): string;
+/**
+ * Find a unique workspace entry whose trailing path matches a missing authored path.
+ * Returns `null` for no match, ambiguity, timeout, or scan failure.
+ */
+export declare function findUniqueWorkspaceSuffix(rawPath: string, cwd: string, signal?: AbortSignal): Promise<{
+    absolutePath: string;
+    displayPath: string;
+} | null>;
 /** Local file materialized from a readable external URL for shared tool-scope resolution. */
 export interface ResolvedExternalSearchUrl {
     /** Absolute or cwd-relative file path to search. */

package/dist/types/tools/todo.d.ts

@@ -5,17 +5,21 @@ import type { RenderResultOptions } from "../extensibility/custom-tools/types.js
 import type { Theme } from "../modes/theme/theme.js";
 import type { ToolSession } from "../sdk.js";
 import type { SessionEntry } from "../session/session-entries.js";
-export type TodoStatus = "pending" | "in_progress" | "completed" | "abandoned";
+export type TodoStatus = "pending" | "in_progress" | "completed" | "abandoned" | "blocked";
 /** Operation names accepted by the todo tool and echoed in successful result details. */
-export type TodoOperation = "init" | "start" | "done" | "rm" | "drop" | "append" | "view";
+export type TodoOperation = "init" | "start" | "done" | "rm" | "drop" | "block" | "unblock" | "append" | "view";
 export interface TodoItem {
     content: string;
     status: TodoStatus;
+    /** When `status === "blocked"`, an optional note on what the task is waiting for. */
+    blocker?: string;
 }
 export interface TodoPhase {
     name: string;
     tasks: TodoItem[];
 }
+/** Whether an unknown value is a persisted todo phase. */
+export declare function isTodoPhase(value: unknown): value is TodoPhase;
 export interface TodoCompletionTransition {
     phase: string;
     content: string;
@@ -28,7 +32,7 @@ export interface TodoToolDetails {
     completedTasks?: TodoCompletionTransition[];
 }
 declare const todoSchema: import("arktype/internal/variants/object.ts").ObjectType<{
-    op: "append" | "done" | "drop" | "init" | "rm" | "start" | "view";
+    op: "append" | "block" | "done" | "drop" | "init" | "rm" | "start" | "unblock" | "view";
     list?: {
         phase: string;
         items: string[];
@@ -36,6 +40,7 @@ declare const todoSchema: import("arktype/internal/variants/object.ts").ObjectTy
     task?: string | undefined;
     phase?: string | undefined;
     items?: string[] | undefined;
+    reason?: string | undefined;
 }, {}>;
 type TodoParams = TodoSchema;
 type TodoSchema = typeof todoSchema.infer;
@@ -107,7 +112,7 @@ export declare class TodoTool implements AgentTool<typeof todoSchema, TodoToolDe
     readonly summary = "Write a structured todo list to track progress within a session";
     readonly description: string;
     readonly parameters: import("arktype/internal/variants/object.ts").ObjectType<{
-        op: "append" | "done" | "drop" | "init" | "rm" | "start" | "view";
+        op: "append" | "block" | "done" | "drop" | "init" | "rm" | "start" | "unblock" | "view";
         list?: {
             phase: string;
             items: string[];
@@ -115,6 +120,7 @@ export declare class TodoTool implements AgentTool<typeof todoSchema, TodoToolDe
         task?: string | undefined;
         phase?: string | undefined;
         items?: string[] | undefined;
+        reason?: string | undefined;
     }, {}>;
     readonly concurrency = "exclusive";
     readonly strict = true;

package/dist/types/tools/xdev.d.ts

@@ -47,6 +47,8 @@ export declare const XDEV_KEEP_TOP_LEVEL: Record<string, true>;
  * declared `loadMode`.
  */
 export declare const XDEV_TRANSPORT_TOOLS: Record<string, true>;
+/** Controls which mounted-device docs are inlined into the system prompt. */
+export type XdevDocsMode = "inline" | "builtins" | "catalog";
 /**
  * Whether an enabled tool is presented under `xd://` (rather than top-level)
  * while the `xd://` transport is active. Discoverable tools mount unless they
@@ -120,7 +122,9 @@ export declare class XdevRegistry {
      * Dynamic mounts embed at most {@link EXTERNAL_DESCRIPTION_CAP} description
      * chars (schema always intact); `read xd://<tool>` returns the full text.
      */
-    docsAll(): string;
+    docsAll(mode?: XdevDocsMode, inlinePatterns?: readonly string[]): string;
+    /** Docs for selected mounted devices under the configured prompt-doc policy. */
+    docsFor(names: Iterable<string>, mode: XdevDocsMode, inlinePatterns?: readonly string[]): string;
     /**
      * Execute a device write: `content` is the JSON args object (empty, `?`, or
      * `help` returns docs). Args validate against the wrapped tool's schema —

package/dist/types/tts/streaming-player.d.ts

@@ -18,6 +18,19 @@ export interface StreamingPlayerLookup {
  * - win32: none (PowerShell `SoundPlayer` is file-only).
  */
 export declare function streamingPlayerCommandsFor(platform: NodeJS.Platform, sampleRate: number, lookup?: StreamingPlayerLookup): PlayerCommand[];
+/**
+ * Test seams for {@link StreamingAudioPlayer}: override backend discovery and
+ * the per-file fallback so playback logic can be exercised without a real audio
+ * device. Both default to the platform lookup and {@link playAudioFile}.
+ */
+export interface StreamingPlayerOptions {
+    /** Ordered backend commands for a sample rate; defaults to {@link streamingPlayerCommandsFor}. */
+    commandsFor?: (sampleRate: number) => PlayerCommand[];
+    /** Per-file fallback playback; defaults to {@link playAudioFile}. */
+    playAudio?: (wavPath: string, signal: AbortSignal) => Promise<void>;
+    /** Max seconds of streamed PCM retained for the nonzero-exit replay; defaults to {@link REPLAY_RETENTION_SECONDS}. */
+    replayRetentionSeconds?: number;
+}
 /**
  * Single-session gapless player. Lifecycle: {@link start} once, {@link write}
  * chunks in order, then {@link end} to drain or {@link stop} to abort. Not
@@ -25,6 +38,7 @@ export declare function streamingPlayerCommandsFor(platform: NodeJS.Platform, sa
  */
 export declare class StreamingAudioPlayer {
     #private;
+    constructor(options?: StreamingPlayerOptions);
     /** Pick a backend and begin draining. Idempotent; the first call's rate wins. */
     start(sampleRate: number): void;
     /** Queue a mono float32 PCM chunk for playback in arrival order. */

package/dist/types/tts/vocalizer.d.ts

@@ -11,6 +11,11 @@ export declare class Vocalizer {
     constructor(createPlayer?: () => VocalizerPlayer);
     /** Wire (or drop) the per-session enhanced-rewrite service. */
     setEnhancer(enhancer: SpeechEnhancer | null): void;
+    /**
+     * Suppress new vocalization until the returned idempotent release function runs.
+     * Existing synthesis and playback stop immediately; nested scopes release independently.
+     */
+    suspend(): () => void;
     /**
      * Stream a delta of assistant text into the pipeline. No-op when
      * vocalization is disabled. The synthesis session (worker, player) is only

package/dist/types/utils/jj.d.ts

@@ -1,3 +1,4 @@
+import * as git from "./git.js";
 /** Result from a completed `jj` subprocess invocation. */
 export interface JjCommandResult {
     /** Process exit code reported by `jj`. */
@@ -32,14 +33,41 @@ export declare class JjCommandError extends Error {
     /** Create an error for a failed checked `jj` command. */
     constructor(args: readonly string[], result: JjCommandResult);
 }
+declare function parseWorkingCopyLabel(raw: string): string | null;
+declare function parseStatusSummary(raw: string): git.GitStatusSummary;
 /** Run `jj diff --git` for the current workspace commit and return the raw Git-format diff text. */
 export declare const diff: ((cwd: string, options?: DiffOptions) => Promise<string>) & {
     /** List changed file paths. */
     changedFiles(cwd: string, options?: Pick<DiffOptions, "files" | "signal">): Promise<string[]>;
 };
+/** Jujutsu working-copy metadata used by status displays. */
+export declare const workingCopy: {
+    /**
+     * Label `@` with its nearest bookmark, falling back to its short change ID.
+     * Returns `null` when `jj` is unavailable or the query fails.
+     */
+    label(cwd: string, signal?: AbortSignal): Promise<string | null>;
+    /** Parse working-copy label query output. */
+    parseLabel: typeof parseWorkingCopyLabel;
+};
+/** Jujutsu working-copy status derived from the changes in `@`. */
+export declare const status: {
+    /**
+     * Count changes in `@` relative to its parent using the Git status shape.
+     * Jujutsu has no index, so `staged` is always zero.
+     */
+    summary(cwd: string, signal?: AbortSignal): Promise<git.GitStatusSummary | null>;
+    /** Parse `jj diff --summary` output into status counts. */
+    parse: typeof parseStatusSummary;
+};
 export declare const repo: {
     /** Clear cached workspace roots. Intended for tests that mutate JJ metadata under an existing path. */
     clearRootCache(): void;
+    /**
+     * Resolve the current workspace root synchronously from on-disk metadata.
+     * Intended for render paths that cannot await filesystem I/O.
+     */
+    rootSync(cwd: string): string | null;
     /** Resolve the current Jujutsu workspace root, or `null` when `cwd` is not in a JJ repository. */
     root(cwd: string): Promise<string | null>;
     /** Full Jujutsu workspace metadata. */
@@ -72,3 +100,4 @@ export declare const repo: {
  * - `false` for directories backed by neither tool.
  */
 export declare function isPureJjRepo(cwd: string): Promise<boolean>;
+export {};

package/dist/types/utils/lang-from-path.d.ts

@@ -2,6 +2,7 @@
  * Language id for syntax highlighting and UI (icons, read tool), or undefined if unknown.
  */
 export declare function getLanguageFromPath(filePath: string): string | undefined;
+export declare function isMarkdownPath(filePath: string): boolean;
 /**
  * LSP language identifier; falls back to `plaintext`.
  */

package/dist/types/utils/title-generator.d.ts

@@ -24,6 +24,36 @@ export declare function formatSessionTerminalTitle(sessionName: string | undefin
  */
 export declare function setTerminalTitle(title: string): void;
 export declare function setSessionTerminalTitle(sessionName: string | undefined, cwd?: string): void;
+/**
+ * Set a terminal title from an extension's `setTitle()`. Unlike the session base
+ * title, this owns the terminal verbatim: the run-state separator will not rewrite
+ * it on the next spinner tick or state change. Cleared when the app next sets an
+ * authoritative session title via {@link setSessionTerminalTitle}.
+ */
+export declare function setExtensionTerminalTitle(title: string): void;
+export type TerminalTitleState = "idle" | "working" | "attention";
+/**
+ * Compose the terminal title from the `π` brand, a state-carrying SEPARATOR, and
+ * the session label. The brand never gains a prefix glyph — the separator slot
+ * expresses the run state instead. Pure (no I/O) so the state→separator contract
+ * is unit-testable:
+ *   - `idle` (user's turn):  `π > label`  — reads like a prompt awaiting input;
+ *   - `working`:             `π ⠋ label`  — spinner frames animate the separator;
+ *   - `attention`:           `π ! label`  — agent blocked on the user;
+ *   - disabled:              `π: label`   — the pre-state layout.
+ * Without a label the separator trails the brand (`π >`) so the state stays visible.
+ */
+export declare function buildTerminalTitleWithState(label: string | undefined, state: TerminalTitleState, frame: number, enabled: boolean): string;
+/**
+ * Reflect the agent run state in the terminal title's separator: `working`
+ * animates spinner frames in the separator slot, `idle` shows `>` (your turn),
+ * `attention` shows `!` (agent blocked on you). Gated off by `tui.titleState`.
+ */
+export declare function setTerminalTitleState(state: TerminalTitleState): void;
+/** Enable/disable the run-state separator (driven by the `tui.titleState` setting). */
+export declare function setTerminalTitleStateEnabled(enabled: boolean): void;
+/** Stop the spinner timer; call on session/UI teardown. */
+export declare function disposeTerminalTitleState(): void;
 /**
  * Save the current terminal title on terminals that support xterm window ops.
  */