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

package/dist/types/live/visualizer.d.ts

@@ -0,0 +1,30 @@
+import { type Component } from "@oh-my-pi/pi-tui";
+/** Distinct states of a realtime call connection. */
+export type LivePhase = "connecting" | "listening" | "working" | "speaking" | "muted" | "error";
+/** Configuration callbacks for user interactions in the visualizer. */
+export interface LiveVisualizerOptions {
+    onStop(): void;
+    onToggleMute(): void;
+}
+/** A compact, fixed-height terminal component for displaying a realtime call. */
+export declare class LiveVisualizer implements Component {
+    #private;
+    readonly wantsKeyRelease = false;
+    constructor(options: LiveVisualizerOptions);
+    /** Updates the current call phase. */
+    setPhase(phase: LivePhase): void;
+    /** Updates the microphone volume level (0..1). */
+    setInputLevel(level: number): void;
+    /** Advances the spectrum animation and its peak decay. */
+    setFrame(frame: number): void;
+    /** Updates the user's streaming voice transcript. */
+    setTranscript(text: string): void;
+    /** Clears the user's voice transcript row. */
+    clearTranscript(): void;
+    /** Processes user keypresses. */
+    handleInput(data: string): void;
+    /** Clears the render cache. */
+    invalidate(): void;
+    /** Renders the microphone spectrum into a compact fixed-height panel. */
+    render(width: number): readonly string[];
+}

package/dist/types/lsp/client.d.ts

@@ -69,10 +69,25 @@ export declare function notifyWorkspaceWatchedFiles(cwd: string, changes: readon
  * Increments version, sends didChange and didSave notifications.
  */
 export declare function refreshFile(client: LspClient, filePath: string, signal?: AbortSignal): Promise<void>;
+/**
+ * Tear down a specific client instance using the LSP shutdown/exit handshake.
+ *
+ * Removes the client from the registry by identity first (never evicting a
+ * newer client already republished under the same key), then performs a bounded
+ * graceful shutdown, force-killing and awaiting confirmed process exit.
+ *
+ * @returns `true` once the process is confirmed exited, `false` if it outlived
+ * the shutdown budget — callers reporting a restart must treat `false` as a
+ * failed teardown, not a completed restart.
+ */
+export declare function shutdownClientInstance(client: LspClient): Promise<boolean>;
 /**
  * Shutdown a specific client by key.
+ *
+ * @returns `true` when the client is gone (already absent or confirmed exited),
+ * `false` if a live process outlived the shutdown budget.
  */
-export declare function shutdownClient(key: string): Promise<void>;
+export declare function shutdownClient(key: string): Promise<boolean>;
 /**
  * Send an LSP request and wait for response.
  *

package/dist/types/mcp/config-writer.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/mcp/oauth-discovery.d.ts

@@ -55,6 +55,7 @@ export declare function analyzeAuthError(error: Error, serverUrl?: string): Auth
  */
 export declare function fetchResourceMetadataScopes(resourceMetadataUrl: string, opts?: {
     fetch?: FetchImpl;
+    signal?: AbortSignal;
 }): Promise<string | undefined>;
 /**
  * Try to discover OAuth endpoints by querying the server's well-known endpoints.
@@ -64,4 +65,5 @@ export declare function discoverOAuthEndpoints(serverUrl: string, authServerUrl?
     fetch?: FetchImpl;
     protectedResource?: string;
     protectedScopes?: string;
+    signal?: AbortSignal;
 }): Promise<OAuthEndpoints | null>;

package/dist/types/mcp/smithery-auth.d.ts

@@ -2,7 +2,7 @@ type SmitheryCliAuthSession = {
     sessionId: string;
     authUrl: string;
 };
-type SmitheryCliPollResponse = {
+export type SmitheryCliPollResponse = {
     status: "pending" | "success" | "error";
     apiKey?: string;
     message?: string;

package/dist/types/mcp/smithery-auth.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/memory-backend/tool-names.d.ts

@@ -0,0 +1,2 @@
+/** Built-in tools whose availability depends on the selected memory backend. */
+export declare const MEMORY_BACKEND_TOOL_NAMES: readonly ["retain", "recall", "reflect", "memory_edit", "learn"];

package/dist/types/modes/components/assistant-message.d.ts

@@ -14,6 +14,7 @@ export declare class AssistantMessageComponent extends Container {
     private readonly thinkingRenderers;
     private readonly imageBudget?;
     private proseOnlyThinking;
+    setTextColorTransform(transform?: (text: string) => string): void;
     constructor(message?: AssistantMessage, hideThinkingBlock?: boolean, onImageUpdate?: (() => void) | undefined, thinkingRenderers?: readonly AssistantThinkingRenderer[], imageBudget?: ImageBudget | undefined, proseOnlyThinking?: boolean);
     /**
      * Show or clear the slim cache-invalidation divider above this turn. Set at

package/dist/types/modes/components/custom-message.d.ts

@@ -1,6 +1,6 @@
 import { Container } from "@oh-my-pi/pi-tui";
 import type { MessageRenderer } from "../../extensibility/extensions/types.js";
-import type { CustomMessage } from "../../session/messages.js";
+import { type CustomMessage } from "../../session/messages.js";
 /**
  * Component that renders a custom message entry from extensions.
  * Uses distinct styling to differentiate from user messages.

package/dist/types/modes/components/login-dialog.d.ts

@@ -15,8 +15,8 @@ export declare class LoginDialogComponent extends Container {
      * is offered as an additional local shortcut so narrow local terminals still
      * have a truncation-safe copy target (viewport clipping on a long authorize
      * URL silently drops trailing OAuth query parameters — e.g.
-     * `code_challenge_method=S256`). The OSC 8 hyperlink carries the full URL
-     * for terminals that support click-through.
+     * `code_challenge_method=S256`). Every physical URL row carries its own OSC 8
+     * link to the full URL, so clicking any wrapped fragment opens the same target.
      */
     showAuth(url: string, instructions?: string, launchUrl?: string): void;
     /**

package/dist/types/modes/components/message-frame.d.ts

@@ -9,7 +9,7 @@
  */
 import type { TextContent } from "@oh-my-pi/pi-ai";
 import type { Box, Component } from "@oh-my-pi/pi-tui";
-import { type Theme } from "../../modes/theme/theme.js";
+import { type Theme, type ThemeColor } from "../../modes/theme/theme.js";
 /** Message shape consumed by the shared frame. */
 export interface FramedMessage {
     customType: string;
@@ -31,14 +31,18 @@ export interface RebuildFrameOptions<M extends FramedMessage> {
     expanded: boolean;
     /** Icon glyph shown before the customType in the default header (e.g. a hook/extension icon). */
     icon?: string;
+    /** Hide the default type header while retaining the message body. */
+    hideHeader?: boolean;
+    /** Semantic color for the outline, defaulting to the muted border. */
+    borderColor?: ThemeColor;
     /** Collapse the markdown body to this many lines when `expanded` is false. Omit to never collapse. */
     collapseAfterLines?: number;
     customRenderer?: FramedRenderer<M>;
 }
 /**
  * Attempt the custom renderer; on failure or undefined return, populate `box`
- * with the default outlined card — an `icon customType` header + markdown body —
- * and return undefined. When the custom renderer succeeds, return its Component
- * so the caller can mount it and skip the default box.
+ * with the configured outline, optional type header, and markdown body. When
+ * the custom renderer succeeds, return its Component so the caller can mount
+ * it and skip the default box.
  */
 export declare function renderFramedMessage<M extends FramedMessage>(opts: RebuildFrameOptions<M>): Component | undefined;

package/dist/types/modes/components/plan-review-overlay.d.ts

@@ -18,6 +18,28 @@
  */
 import { type Component } from "@oh-my-pi/pi-tui";
 import type { HookSelectorSlider } from "./hook-selector.js";
+/** Serializable annotations retained by the plan-review owner between overlays. */
+export interface PlanReviewAnnotationState {
+    annotations: Array<{
+        section: {
+            index: number;
+            title: string;
+            /** Heading ancestry from the document root, when emitted by this overlay. */
+            path?: string[];
+            /** Hash of the section source, used to reject ambiguous moved headings. */
+            contentHash?: string;
+        };
+        target: {
+            kind: "section";
+        } | {
+            kind: "line";
+            row: number;
+            context: string;
+            contextTruncated?: boolean;
+        };
+        note: string;
+    }>;
+}
 export interface PlanReviewOverlayCallbacks {
     /** Invoked with the chosen option label (never a disabled one). */
     onPick: (label: string) => void;
@@ -33,6 +55,8 @@ export interface PlanReviewOverlayCallbacks {
     onPlanEdited?: (content: string) => void;
     /** Invoked with the Refine feedback markdown whenever annotations change. */
     onFeedbackChange?: (feedback: string) => void;
+    /** Invoked with a serializable annotation snapshot whenever annotations change. */
+    onAnnotationStateChange?: (state: PlanReviewAnnotationState) => void;
 }
 export interface PlanReviewOverlayOptions {
     /** Prompt rendered above the options (e.g. "Plan mode - next step"). */
@@ -48,6 +72,8 @@ export interface PlanReviewOverlayOptions {
     slider?: HookSelectorSlider;
     /** Display label for the external-editor key, surfaced in the footer help. */
     externalEditorLabel?: string;
+    /** Serializable annotations restored into this overlay instance. */
+    annotationState?: PlanReviewAnnotationState;
 }
 export declare class PlanReviewOverlay implements Component {
     #private;

package/dist/types/modes/components/session-account-selector.d.ts

@@ -0,0 +1,11 @@
+import { Container, type SgrMouseEvent } from "@oh-my-pi/pi-tui";
+import type { SessionPinAccount } from "../../slash-commands/helpers/session-pin.js";
+/** Account picker opened by `/session pin` for the current model provider. */
+export declare class SessionAccountSelectorComponent extends Container {
+    #private;
+    constructor(providerName: string, accounts: readonly SessionPinAccount[], onSelect: (account: SessionPinAccount) => void, onCancel: () => void);
+    /** Forward keyboard navigation and cancellation when the wrapper owns focus. */
+    handleInput(keyData: string): void;
+    /** Route mouse selection through the title rows into the account list. */
+    routeMouse(event: SgrMouseEvent, line: number, col: number): void;
+}

package/dist/types/modes/components/settings-defs.d.ts

@@ -45,7 +45,13 @@ export interface TextInputSettingDef extends BaseSettingDef {
 export interface ProviderLimitsSettingDef extends BaseSettingDef {
     type: "providerLimits";
 }
-export type SettingDef = BooleanSettingDef | EnumSettingDef | SubmenuSettingDef | TextInputSettingDef | ProviderLimitsSettingDef;
+/** Array-of-enum setting edited as a toggle list; `ordered` lists render positions and support reordering. */
+export interface MultiSelectSettingDef extends BaseSettingDef {
+    type: "multiselect";
+    options: OptionList;
+    ordered: boolean;
+}
+export type SettingDef = BooleanSettingDef | EnumSettingDef | SubmenuSettingDef | TextInputSettingDef | ProviderLimitsSettingDef | MultiSelectSettingDef;
 /** Get all setting definitions with UI */
 export declare function getAllSettingDefs(): SettingDef[];
 /**

package/dist/types/modes/components/status-line/component.jj-cache.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/modes/components/tool-execution.d.ts

@@ -92,7 +92,15 @@ export declare class ToolExecutionComponent extends Container implements NativeS
      * immutable native scrollback before the result replaces them.
      */
     getNativeScrollbackLiveRegionStart(): number | undefined;
-    /** Keeps the in-flight `vibe_wait` TV wall out of immutable native scrollback. */
+    /**
+     * Keeps in-flight TV-wall frames out of immutable native scrollback: the
+     * `vibe_wait` wall and displaceable snapshots (`hub` waiting polls, `todo`
+     * lists). Their frames replace each other rather than append, and their
+     * rows mutate every spinner tick — an unpinned commit records a per-tick
+     * frozen snapshot AND force-seals the block (see TranscriptContainer's
+     * committed-snapshot seal), so the next poll stacks a new frame instead of
+     * displacing this one.
+     */
     isNativeScrollbackLiveRegionPinned(): boolean;
     /**
      * Whether this block has reached a terminal state for transcript freezing.

package/dist/types/modes/controllers/command-controller.d.ts

@@ -60,4 +60,4 @@ export declare function renderProviderSection(details: ProviderDetails, uiTheme:
  * Example output: `Quota: 7d window · 67% used · resets in 3.2d`
  */
 export declare function formatCompactQuota(provider: string, reports: UsageReport[], nowMs: number, activeAccount?: OAuthAccountIdentity): string | null;
-export declare function renderUsageReports(reports: UsageReport[], uiTheme: typeof theme, nowMs: number, availableWidth: number, resolveActiveAccount?: (provider: string) => OAuthAccountIdentity | undefined): string;
+export declare function renderUsageReports(reports: UsageReport[], uiTheme: typeof theme, nowMs: number, availableWidth: number, resolveActiveAccount?: (provider: string) => OAuthAccountIdentity | undefined, usageModelSelectors?: readonly string[]): string;

package/dist/types/modes/controllers/event-controller.d.ts

@@ -24,5 +24,10 @@ export declare class EventController {
      * Drops the candidate when it is no longer a displaceable todo.
      */
     inheritDisplaceableTodo(component: ToolExecutionComponent | null | undefined): void;
-    sendCompletionNotification(): void;
+    sendErrorNotification(event: Extract<AgentSessionEvent, {
+        type: "agent_end";
+    }>): void;
+    sendCompletionNotification(event: Extract<AgentSessionEvent, {
+        type: "agent_end";
+    }>): void;
 }

package/dist/types/modes/controllers/live-command-controller.d.ts

@@ -0,0 +1,14 @@
+import type { InteractiveModeContext } from "../types.js";
+/** Owns the editor-replacing visualizer and realtime session lifecycle for `/live`. */
+export declare class LiveCommandController {
+    #private;
+    constructor(ctx: InteractiveModeContext);
+    /** Whether a live session is connected, connecting, or closing. */
+    get active(): boolean;
+    /** Start live mode, or stop the currently active session. */
+    handleCommand(): Promise<void>;
+    /** Stop the active live session and restore the editor. */
+    stop(): Promise<void>;
+    /** Release UI resources during synchronous InteractiveMode teardown. */
+    dispose(): void;
+}

package/dist/types/modes/controllers/selector-controller.d.ts

@@ -55,6 +55,7 @@ export declare class SelectorController {
     }): Promise<boolean>;
     handleSessionDeleteCommand(): Promise<void>;
     showOAuthSelector(mode: "login" | "logout", providerId?: string): Promise<void>;
+    showSessionPinSelector(): Promise<void>;
     showResetUsageSelector(): Promise<void>;
     showDebugSelector(): Promise<void>;
     showAgentHub(observers: SessionObserverRegistry, options?: {

package/dist/types/modes/interactive-mode.d.ts

@@ -27,6 +27,7 @@ import type { EvalExecutionComponent } from "./components/eval-execution.js";
 import type { HookEditorComponent } from "./components/hook-editor.js";
 import type { HookInputComponent } from "./components/hook-input.js";
 import type { HookSelectorComponent, HookSelectorSlider } from "./components/hook-selector.js";
+import { type PlanReviewAnnotationState } from "./components/plan-review-overlay.js";
 import { StatusLineComponent } from "./components/status-line/index.js";
 import type { ToolExecutionHandle } from "./components/tool-execution.js";
 import { TranscriptContainer } from "./components/transcript-container.js";
@@ -247,6 +248,8 @@ export declare class InteractiveMode implements InteractiveModeContext {
         onExternalEditor?: () => void;
         onPlanEdited?: (content: string) => void;
         onFeedbackChange?: (feedback: string) => void;
+        annotationState?: PlanReviewAnnotationState;
+        onAnnotationStateChange?: (state: PlanReviewAnnotationState) => void;
         initialIndex?: number;
     }, extra?: {
         slider?: HookSelectorSlider;
@@ -340,6 +343,8 @@ export declare class InteractiveMode implements InteractiveModeContext {
     handleRenameCommand(title: string): Promise<void>;
     handleMemoryCommand(text: string): Promise<void>;
     handleSTTToggle(): Promise<void>;
+    /** Start or stop the Codex-backed realtime voice surface. */
+    handleLiveCommand(): Promise<void>;
     showDebugSelector(): Promise<void>;
     showAgentHub(options?: {
         requireContent?: boolean;
@@ -371,6 +376,7 @@ export declare class InteractiveMode implements InteractiveModeContext {
     handleResumeSession(sessionPath: string): Promise<void>;
     handleSessionDeleteCommand(): Promise<void>;
     showOAuthSelector(mode: "login" | "logout", providerId?: string): Promise<void>;
+    showSessionPinSelector(): Promise<void>;
     showResetUsageSelector(): Promise<void>;
     showProviderSetup(): Promise<void>;
     showHookConfirm(title: string, message: string): Promise<boolean>;

package/dist/types/modes/theme/theme.d.ts

@@ -1,7 +1,7 @@
 import type { ThinkingLevel } from "@oh-my-pi/pi-agent-core";
 import type { Effort } from "@oh-my-pi/pi-ai";
 import type { EditorTheme, MarkdownTheme, SelectListTheme, SettingsListTheme, SymbolTheme } from "@oh-my-pi/pi-tui";
-export { getLanguageFromPath } from "../../utils/lang-from-path.js";
+export { getLanguageFromPath, isMarkdownPath } from "../../utils/lang-from-path.js";
 export type SymbolPreset = "unicode" | "nerd" | "ascii";
 /**
  * All available symbol keys organized by category.

package/dist/types/modes/types.d.ts

@@ -61,7 +61,7 @@ export type SubmittedUserInput = {
     cancelled: boolean;
     started: boolean;
 };
-export type TodoStatus = "pending" | "in_progress" | "completed" | "abandoned";
+export type TodoStatus = "pending" | "in_progress" | "completed" | "abandoned" | "blocked";
 export type TodoItem = {
     content: string;
     status: TodoStatus;
@@ -334,6 +334,8 @@ export interface InteractiveModeContext {
     handleRenameCommand(title: string): Promise<void>;
     handleMemoryCommand(text: string): Promise<void>;
     handleSTTToggle(): Promise<void>;
+    /** Start or stop the Codex-backed realtime voice session. */
+    handleLiveCommand(): Promise<void>;
     executeCompaction(customInstructionsOrOptions?: string | CompactOptions, isAuto?: boolean): Promise<CompactionOutcome>;
     openInBrowser(urlOrPath: string): void;
     refreshSlashCommandState(cwd?: string): Promise<void>;
@@ -356,6 +358,7 @@ export interface InteractiveModeContext {
     handleResumeSession(sessionPath: string): Promise<void>;
     handleSessionDeleteCommand(): Promise<void>;
     showOAuthSelector(mode: "login" | "logout", providerId?: string): Promise<void>;
+    showSessionPinSelector(): Promise<void>;
     showResetUsageSelector(): Promise<void>;
     showProviderSetup(): Promise<void>;
     showHookConfirm(title: string, message: string): Promise<boolean>;

package/dist/types/modes/utils/context-usage.d.ts

@@ -22,16 +22,26 @@ export interface ContextBreakdown {
     /** Estimated snapcompact wire savings; set when requested and a snapcompact.* setting is enabled. */
     snapcompact?: SnapcompactSavingsEstimate;
 }
+/** Stable inputs used to cache non-message token estimates. */
+export interface NonMessageTokenSource {
+    readonly systemPrompt?: string[];
+    readonly agent?: {
+        readonly state?: {
+            readonly tools?: ReadonlyArray<Pick<Tool, "name" | "description" | "parameters">>;
+        };
+    };
+    readonly skills?: readonly Skill[];
+}
 export declare function estimateSkillsTokens(skills: readonly Skill[]): number;
 export declare function estimateToolSchemaTokens(tools: ReadonlyArray<Pick<Tool, "name" | "description" | "parameters">>): number;
-export declare function computeNonMessageTokens(session: AgentSession): number;
+export declare function computeNonMessageTokens(session: NonMessageTokenSource): number;
 /**
  * Shared helper for the four non-message token totals used by
  * `computeContextBreakdown` (/context panel). Keep this category split stable:
  * the status-line fast path intentionally uses the equivalent collapsed total
  * in `computeNonMessageTokens`.
  */
-export declare function computeNonMessageBreakdown(session: AgentSession): {
+export declare function computeNonMessageBreakdown(session: NonMessageTokenSource): {
     skillsTokens: number;
     toolsTokens: number;
     systemContextTokens: number;

package/dist/types/plan-mode/plan-files.d.ts

@@ -0,0 +1,10 @@
+import { type LocalProtocolOptions } from "../internal-urls/index.js";
+/** Reads a plan from a local URL or cwd-relative filesystem path. */
+export declare function readPlanFile(planFilePath: string, options: {
+    localProtocolOptions: LocalProtocolOptions;
+    cwd: string;
+}): Promise<string | null>;
+/** Lists session-local plan files from newest to oldest. */
+export declare function listPlanFiles(options: {
+    localProtocolOptions: LocalProtocolOptions;
+}): Promise<string[]>;

package/dist/types/registry/agent-lifecycle.d.ts

@@ -14,10 +14,14 @@
  * - ensureLive during an in-flight park either cancels the park (session still
  *   live) or waits for detach+park and then revives.
  * - Concurrent ensureLive/park operations coalesce per id.
+ *
+ * Every adoption, park, and revival is bound to the exact {@link AgentRef} it
+ * started from, so stale async work (a late finalizer, a cancelled initializer,
+ * a superseded revive) can never clobber a newer same-id ref.
  */
 import type { AgentSession } from "../session/agent-session.js";
-import { type AgentRef, AgentRegistry } from "./agent-registry.js";
-export type AgentReviver = () => Promise<AgentSession>;
+import { type AgentRef, type AgentRefExpectation, AgentRegistry } from "./agent-registry.js";
+export type AgentReviver = (expected: AgentRef) => Promise<AgentSession>;
 /**
  * Builds a reviver for a `parked` ref restored from disk (Agent Hub scan,
  * collab mirror, resumed process) that carries a sessionFile but no in-memory
@@ -48,10 +52,12 @@ export declare class AgentLifecycleManager {
     /**
      * Take ownership of a finished subagent. Caller has already set registry
      * status to "idle". Arms the TTL timer (idleTtlMs <= 0 adopts without one).
+     * When `expected` is given, the adoption is refused if the id no longer
+     * resolves to that ref (or that ref's session).
      */
-    adopt(id: string, opts: AdoptOptions): void;
-    /** True if the id is adopted (parked or live). */
-    has(id: string): boolean;
+    adopt(id: string, opts: AdoptOptions, expected?: AgentRefExpectation): void;
+    /** True if the id is adopted (parked or live) — and, when `expected` is given, still bound to that ref. */
+    has(id: string, expected?: AgentRefExpectation): boolean;
     /**
      * True when this manager owns `registry` — i.e. its adopt/park/revive state
      * describes that registry's refs. Lets a caller holding a specific registry
@@ -62,9 +68,10 @@ export declare class AgentLifecycleManager {
     /**
      * True while {@link park} is disposing this agent's session (lets dispose
      * hooks distinguish park from teardown). False once the park is cancelled
-     * by ensureLive or after detach+dispose completes.
+     * by ensureLive or after detach+dispose completes. When `expected` is
+     * given, only a park bound to that ref (or its session) counts.
      */
-    isParking(id: string): boolean;
+    isParking(id: string, expected?: AgentRefExpectation): boolean;
     /**
      * Dispose the live session, detach it from the registry, and mark the
      * agent `parked`. No-op unless the id is adopted and live.
@@ -84,8 +91,13 @@ export declare class AgentLifecycleManager {
      * cancelled (session still live) or awaited to completion before revive.
      */
     ensureLive(id: string): Promise<AgentSession>;
-    /** Hard removal: dispose if live, unregister from registry, drop timers. */
-    release(id: string): Promise<void>;
+    /**
+     * Hard removal: dispose if live, unregister from registry, drop timers.
+     * When `expected` is given, only a ref matching it is released; a stale
+     * release can never take down a newer same-id ref. Returns true when a
+     * matching ref was released.
+     */
+    release(id: string, expected?: AgentRefExpectation): Promise<boolean>;
     /** Teardown everything (process exit / main session dispose). */
     dispose(): Promise<void>;
 }

package/dist/types/registry/agent-registry.d.ts

@@ -39,6 +39,7 @@ export interface AgentRef {
     /** Short gist of what the agent is currently doing (latest intent or tool), for the work-aware roster. Display-only. */
     activity?: string;
 }
+export type AgentRefExpectation = AgentRef | AgentSession;
 export type RegistryEvent = {
     type: "registered";
     ref: AgentRef;
@@ -65,7 +66,13 @@ export declare class AgentRegistry {
     /** Reset the global registry. Test-only. */
     static resetGlobalForTests(): void;
     register(input: RegisterInput): AgentRef;
-    setStatus(id: string, status: AgentStatus): void;
+    /**
+     * Register a new id only when it is absent, or reuse the exact ref a parked
+     * revival was authorized to revive. A missing expected ref is a failed CAS:
+     * callers must never claim an id after its prior generation disappeared.
+     */
+    registerIfAvailable(input: RegisterInput, expected: AgentRef | null): AgentRef | undefined;
+    setStatus(id: string, status: AgentStatus, expected?: AgentRefExpectation): boolean;
     /**
      * Record a short activity gist for the work-aware roster. Display-only and
      * read on demand (`irc list`, peer roster), so it emits no event — keeping
@@ -81,9 +88,9 @@ export declare class AgentRegistry {
      * every caller is safe without sanitizing at its own call site.
      */
     setActivity(id: string, activity: string): void;
-    attachSession(id: string, session: AgentSession, sessionFile?: string | null): void;
-    detachSession(id: string): void;
-    unregister(id: string): void;
+    attachSession(id: string, session: AgentSession, sessionFile?: string | null, expected?: AgentRefExpectation): boolean;
+    detachSession(id: string, expected?: AgentRefExpectation): boolean;
+    unregister(id: string, expected?: AgentRefExpectation): boolean;
     get(id: string): AgentRef | undefined;
     list(): AgentRef[];
     /**

package/dist/types/sdk.d.ts

@@ -16,7 +16,7 @@ import type { HindsightSessionState } from "./hindsight/state.js";
 import { type LocalProtocolOptions } from "./internal-urls/index.js";
 import { MCPManager, type MCPToolsLoadResult } from "./mcp/index.js";
 import type { MnemopiSessionState } from "./mnemopi/state.js";
-import { AgentRegistry } from "./registry/agent-registry.js";
+import { type AgentRef, AgentRegistry } from "./registry/agent-registry.js";
 import { AgentSession, type PlanYolo, type Prewalk } from "./session/agent-session.js";
 import type { AuthStorage } from "./session/auth-storage.js";
 import { SessionManager } from "./session/session-manager.js";
@@ -29,6 +29,8 @@ import { type WorkspaceTree } from "./workspace-tree.js";
 export interface CreateAgentSessionOptions {
     /** Working directory for project-local discovery. Default: getProjectDir() */
     cwd?: string;
+    /** Additional workspace directories beyond cwd (multi-root), absolute or cwd-relative. */
+    additionalDirectories?: string[];
     /** Global config directory. Default: ~/.omp/agent */
     agentDir?: string;
     /** Spawns to allow. Default: "*" */
@@ -180,6 +182,13 @@ export interface CreateAgentSessionOptions {
     agentDisplayName?: string;
     /** Optional shared agent registry for IRC routing. Default: AgentRegistry.global(). */
     agentRegistry?: AgentRegistry;
+    /**
+     * Registry generation authorized for this creation. `null` requires the id
+     * to be absent; an AgentRef allows a parked revival to reuse only that ref.
+     * Undefined preserves legacy unconditional registration for external SDK callers.
+     * @internal
+     */
+    expectedAgentRef?: AgentRef | null;
     /** Parent task ID prefix for nested artifact naming (e.g., "Extensions") */
     parentTaskPrefix?: string;
     /**
@@ -205,6 +214,11 @@ export interface CreateAgentSessionOptions {
     settingsManager?: Settings | Promise<Settings>;
     /** Whether UI is available (enables interactive tools like ask). Default: false */
     hasUI?: boolean;
+    /**
+     * Defer `confirm` reserve-policy fallback until AgentSession prompt-time UI is configured.
+     * ACP uses this while capabilities are negotiated without enabling UI-only tools.
+     */
+    deferUsageReserveConfirmation?: boolean;
     /**
      * Opt-in OpenTelemetry instrumentation forwarded to the underlying Agent.
      * Passing `{}` enables the loop's GenAI-semantic-convention spans. See

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

@@ -1,5 +1,18 @@
-import type { SecretEntry } from "./obfuscator.js";
-export { deobfuscateSessionContext, deobfuscateToolArguments, obfuscateMessages, obfuscateProviderContext, type SecretEntry, SecretObfuscator, } from "./obfuscator.js";
+import { type SecretEntry } from "./obfuscator.js";
+/**
+ * Per-install secret key for the placeholder digest. Persisted under the agent
+ * config directory and never sent to a provider, so model-visible placeholders
+ * cannot be reversed by dictionary-hashing candidate secrets. Stable across
+ * sessions so persisted transcripts deobfuscate consistently. Defaults to
+ * `getAgentDir()` — the same directory `createAgentSession()` passes as
+ * `agentDir` — so a caller relying on the default reads/writes the identical
+ * key file live sessions use, per `~/.omp/agent/secret-placeholder.key` in
+ * docs/secrets.md.
+ */
+export declare function getSecretPlaceholderKey(keyDir?: string): Promise<string>;
+/** Return an existing placeholder key for redaction without creating a new key file. */
+export declare function getExistingSecretPlaceholderKey(keyDir?: string): Promise<string | undefined>;
+export { deobfuscateSessionContext, deobfuscateToolArguments, obfuscateMessages, obfuscateProviderContext, type SecretEntry, SecretObfuscator, secretEntriesNeedPlaceholderKey, secretEntryNeedsPlaceholderKey, } from "./obfuscator.js";
 /**
  * Load secrets from project-local and global secrets.yml files.
  * Project-local entries override global entries with matching content.