@timurproko/a1 0.2.7-dev.1275 → 0.2.7-dev.1285

package/README.md

@@ -73,7 +73,11 @@ a1 --session <id>
 
 When a session exits, A1 prints the `a1 --session <id>` command that resumes it; a custom session store is included in the printed command. Closing the terminal ends the agent, as it does for Pi.
 
-Bare A1 automatically names unnamed sessions from the first prompt and regenerates automatic names on the next prompt after a worktree-context change. Manual `/name` renames are preserved. Names appear after footer stats, with a secondary-accent reveal for automatic changes. Agent settings offers **Session name format** with Kebab case (default), Sentence case, and Title Case for future generated names, or **Automatic session name** to disable naming; see [session names](docs/features/session-naming.md) for details.
+If a saved session's folder was moved or deleted, recovery offers **Continue**, **Fork**, or **Cancel**. Continue uses the current folder for this run and asks again on the next resume. Fork keeps the original and creates a new session ID in the current folder, so later resumes no longer ask. This also applies to session import and extension-triggered switching.
+
+Bare A1 automatically names unnamed sessions from the current task and relevant discussion, using up to three descriptive words and 32 characters, and regenerates on the next prompt after a worktree-context change. Manual `/name` renames are preserved. Names appear after footer stats, with a secondary-accent reveal for automatic changes; narrow footers reduce stats before shortening the name. Agent settings offers **Session name format** with Sentence case (default, first choice), Kebab case, and Title Case for future generated names, or **Automatic session name** to disable naming. Valid saved formats are preserved; see [session names](docs/features/session-naming.md) for details.
+
+Inside an A1 agent session, `a1 worktree enter <branch>` creates or resumes a task checkout and attaches it. `a1 worktree attach <path>` attaches an existing checkout; `a1 worktree detach` releases it without deleting work. A1 handles coordination and ordinary recovery internally; successful attachment needs no second inventory check. See [worktree commands](docs/features/worktrees.md).
 
 Show all commands:
 

package/dist/app/session-shell/apps-dialog.d.ts

@@ -1,4 +1,4 @@
-import type { TerminalComponentPort } from "../../contracts/presentation/index.js";
+import { type TerminalComponentPort } from "../../contracts/presentation/index.js";
 import { type UiTheme } from "../../ui/components/index.js";
 declare const APPS: readonly [{
     readonly id: "agent";

package/dist/app/session-shell/apps-dialog.js

@@ -1,3 +1,4 @@
+import { wrapChoiceIndex } from "../../contracts/presentation/index.js";
 import { LineInput, handleLineInputKey, ShortcutRegistry, configureDialogChoiceCapacity, renderSteppedDialogPanel } from "../../ui/components/index.js";
 const APPS = [
     { id: "agent", label: "Agent" },
@@ -49,7 +50,7 @@ export class AppsDialog {
             return;
         }
         if (action === "previous" || action === "next") {
-            this.#index = Math.max(0, Math.min(matches.length - 1, this.#index + (action === "next" ? 1 : -1)));
+            this.#index = wrapChoiceIndex(this.#index, action === "next" ? 1 : -1, matches.length);
         }
         else {
             handleLineInputKey(this.#input, key);

package/dist/app/session-shell/dialog-coordinator.d.ts

@@ -12,6 +12,7 @@ interface SessionDialogPorts {
     readonly viewport?: () => {
         rows: number;
     };
+    readonly inPlaceSession?: boolean;
     readonly root: Pick<OwnedUiSessionShellRoot, "chrome" | "setInputSurface" | "usesDefaultInputSurface">;
     readonly routeHost: UiRouteHost | null;
     readonly dialogs: Pick<OwnedUiShellComponents["dialogs"], "dialog" | "selector">;
@@ -22,11 +23,7 @@ interface SessionDialogPorts {
     readonly routeClosed?: (route: string) => void;
     readonly startupRoute?: StartupRoute;
 }
-/**
- * Owns the one modal overlay a session shows at a time, whichever source opened it: an owned route,
- * a local selector, or a backend dialog. Opening one hides the previous one, and every close path
- * clears the same state.
- */
+/** Coordinates owned routes, dock dialogs, and backend overlays through one replacement/close lifecycle. */
 export declare class SessionDialogCoordinator {
     #private;
     constructor(ports: SessionDialogPorts);
@@ -39,6 +36,8 @@ export declare class SessionDialogCoordinator {
     /** Mirrors the backend's pending dialog; locally owned routes and selectors are left alone when it has none. */
     syncBackend(dialog: OwnedUiDialog | null): void;
     openRoute(route: string, input?: UiRouteInput, onClosed?: () => void | Promise<void>): OwnedUiCommandResult;
+    /** Close the route before global abort. */
+    handleInputRouteInterrupt(data: string): boolean;
     claimsRoute(name: string): boolean;
     /** Retains a route requested before the runtime runs; the latest request wins. */
     retainStartupRoute(route: string): void;

package/dist/app/session-shell/dialog-coordinator.js

@@ -1,10 +1,7 @@
+import { InputRoute } from "./input-route.js";
 const OVERLAY_OPTIONS = { width: "70%", maxHeight: "80%", anchor: "center", inputCoordination: "owned" };
 const STARTUP_ROUTE_RETRY_MS = 25;
-/**
- * Owns the one modal overlay a session shows at a time, whichever source opened it: an owned route,
- * a local selector, or a backend dialog. Opening one hides the previous one, and every close path
- * clears the same state.
- */
+/** Coordinates owned routes, dock dialogs, and backend overlays through one replacement/close lifecycle. */
 export class SessionDialogCoordinator {
     #ports;
     #handle;
@@ -12,6 +9,7 @@ export class SessionDialogCoordinator {
     #source;
     #route;
     #apps;
+    #inputRoute;
     #startupRoute;
     #startupRouteTimer;
     constructor(ports) {
@@ -133,24 +131,54 @@ export class SessionDialogCoordinator {
         this.#handle?.hide();
         this.#source = "route";
         this.#route = route;
+        const closed = (rendered) => {
+            if (rendered) {
+                try {
+                    void onClosed?.()?.catch(() => undefined);
+                }
+                catch { /* Rationale: a failed acknowledgement stays pending. */ }
+                this.#ports.routeClosed?.(route);
+            }
+        };
+        if (route === "session" && this.#ports.inPlaceSession) {
+            const component = new InputRoute(surface, {
+                requestRender: () => this.#ports.terminal.requestRender(),
+                closed: rendered => { this.closeInputSurface(); closed(rendered); },
+                released: () => { if (this.#handle === handle)
+                    this.#clear(); },
+                key: data => this.#ports.presentation?.terminalRuntime.legacyKeyInput(data) ?? data,
+                exit: () => this.#ports.exit(),
+            });
+            const handle = { hide: () => component.close(), close: () => component.close() };
+            this.#handle = handle;
+            this.#inputRoute = component;
+            this.#id = surface.id;
+            this.#ports.root.setInputSurface(component);
+            this.#ports.terminal.requestRender();
+            return { outcome: "completed", diagnostic: null };
+        }
         const handle = this.#ports.terminal.openRoute(surface, {
             exit: () => this.#ports.exit(),
             closed: rendered => {
                 if (this.#handle === handle)
                     this.#clear();
-                if (rendered) {
-                    try {
-                        void onClosed?.()?.catch(() => undefined);
-                    }
-                    catch { /* Rationale: a failed acknowledgement stays pending. */ }
-                    this.#ports.routeClosed?.(route);
-                }
+                closed(rendered);
             },
         });
         this.#handle = handle;
         this.#id = surface.id;
         return { outcome: "completed", diagnostic: null };
     }
+    /** Close the route before global abort. */
+    handleInputRouteInterrupt(data) {
+        if (this.#inputRoute === undefined || this.#apps !== undefined)
+            return false;
+        const key = this.#ports.presentation?.terminalRuntime.legacyKeyInput(data) ?? data;
+        if (key !== "\u0003")
+            return false;
+        this.#inputRoute.handleInput(key);
+        return true;
+    }
     claimsRoute(name) {
         return this.#ports.routeHost?.claims(name) ?? false;
     }
@@ -197,5 +225,6 @@ export class SessionDialogCoordinator {
         this.#id = undefined;
         this.#source = undefined;
         this.#route = undefined;
+        this.#inputRoute = undefined;
     }
 }

package/dist/app/session-shell/input-route.d.ts

@@ -0,0 +1,23 @@
+import type { OwnedUiShellComponentPort } from "../../contracts/owned-ui/index.js";
+import type { UiRouteSurface } from "../../ui/apps/index.js";
+import type { PaneMouseEvent } from "../../ui/components/index.js";
+type InputRouteOptions = {
+    readonly requestRender: () => void;
+    readonly closed: (rendered: boolean) => void;
+    readonly exit: () => void;
+    readonly released: () => void;
+    readonly key: (data: string) => string;
+};
+/** Hosts a bounded dock route. */
+export declare class InputRoute implements OwnedUiShellComponentPort {
+    #private;
+    constructor(surface: UiRouteSurface, options: InputRouteOptions);
+    render(width: number): readonly string[];
+    renderInDock(width: number, maxHeight: number): readonly string[];
+    handleInput(data: string): void;
+    handleLocalMouse(event: PaneMouseEvent): void;
+    invalidate(): void;
+    close(): void;
+    dispose(): void;
+}
+export {};

package/dist/app/session-shell/input-route.js

@@ -0,0 +1,59 @@
+/** Hosts a bounded dock route. */
+export class InputRoute {
+    #surface;
+    #options;
+    #disposed = false;
+    #rendered = false;
+    constructor(surface, options) {
+        this.#surface = surface;
+        this.#options = options;
+        surface.onRenderRequested(() => { if (!this.#disposed)
+            this.#refresh(); });
+        surface.onExitRequested(() => { this.close(); options.exit(); });
+    }
+    render(width) { return this.renderInDock(width, 24); }
+    renderInDock(width, maxHeight) {
+        if (this.#disposed)
+            return [];
+        const frame = this.#surface.render(width, Math.max(1, Math.min(24, maxHeight)));
+        this.#rendered = true;
+        return frame;
+    }
+    handleInput(data) {
+        if (this.#disposed)
+            return;
+        const key = this.#options.key(data);
+        // Compatibility: close even while the deferred document is loading.
+        if (key === "\u001b" || key === "\u0003") {
+            this.close();
+            return;
+        }
+        this.#surface.handleInput(key);
+        this.#refresh();
+    }
+    handleLocalMouse(event) {
+        if (this.#disposed)
+            return;
+        this.#surface.handleMouse(event);
+        this.#refresh();
+    }
+    invalidate() { }
+    close() {
+        if (this.#disposed)
+            return;
+        this.#options.closed(this.#rendered);
+        this.dispose();
+    }
+    dispose() {
+        if (this.#disposed)
+            return;
+        this.#disposed = true;
+        this.#surface.close();
+        this.#options.released();
+    }
+    #refresh() {
+        if (this.#surface.isClosed())
+            this.close();
+        this.#options.requestRender();
+    }
+}

package/dist/app/session-shell/session-selectors.d.ts

@@ -28,8 +28,8 @@ export declare class SessionSelectors implements WorkflowSelectors {
     #private;
     constructor(ports: SessionSelectorPorts);
     showThinkingSelector(): Promise<void>;
-    /** The Skills dialog: a replacement input like the model selector, applying the chosen skill through the prompt path. */
-    showSkillsSelector(skills: readonly OwnedUiShellSkillSummary[]): void;
+    /** Applies a dock-selected skill through the prompt path. */
+    showSkillsSelector(skills: readonly OwnedUiShellSkillSummary[]): Promise<void> | undefined;
     showModelSelector(initialSearchInput?: string): void;
     showForkSelector(): void;
     showLogoutSelector(): Promise<void>;
@@ -39,7 +39,7 @@ export declare class SessionSelectors implements WorkflowSelectors {
     showLoginProviderSelector(authType?: "oauth" | "api_key", initialSearchInput?: string): void;
     showSessionSelector(): Promise<void>;
     showSettingsSelector(): void;
-    showTrustSelector(): void;
+    showTrustSelector(): Promise<void> | undefined;
     showScopedModelsSelector(): void;
     /** The bare-A1 unified Models dialog: switch on Enter, scope on Space, persist on Ctrl+S, all through the engine. */
     showModelsDialog(initialQuery?: string): void | Promise<void>;

package/dist/app/session-shell/session-selectors.js

@@ -77,7 +77,7 @@ export class SessionSelectors {
             releasePresentation?.();
         }
     }
-    /** The Skills dialog: a replacement input like the model selector, applying the chosen skill through the prompt path. */
+    /** Applies a dock-selected skill through the prompt path. */
     showSkillsSelector(skills) {
         const close = this.#dialogs.closeInputSurface;
         const component = this.#presenters.components.dialogs.skillsSelector({
@@ -89,6 +89,7 @@ export class SessionSelectors {
             onCancel: close,
         });
         this.#present(component);
+        return component.ready;
     }
     showModelSelector(initialSearchInput) {
         this.#presenters.openModelSelector(this.#dialogHost, initialSearchInput);
@@ -214,6 +215,7 @@ export class SessionSelectors {
             onCancel: close,
         });
         this.#present(component);
+        return component.ready;
     }
     showScopedModelsSelector() {
         this.#presenters.openScopedModelsSelector(this.#dialogHost);
@@ -261,9 +263,12 @@ export class SessionSelectors {
         if (result.diagnostic === "Branch summarization cancelled")
             await this.showTreeSelector(entryId);
     }
-    // Invariant: a selector replaces the editor in the input dock and paints in the same frame.
+    // Performance: retain the frame until a deferred selector is ready.
     #present(component) {
+        const release = component?.ready === undefined ? undefined : this.#terminal.beginPresentationHold();
         this.#root.setInputSurface(component);
+        void component?.ready?.finally(() => { release?.(); if (!this.#ports.disposed())
+            this.#terminal.requestRender(); });
         this.#terminal.requestRender();
     }
 }

package/dist/app/session-shell/session-shell-root.d.ts

@@ -1,8 +1,7 @@
 import type { OwnedUiShellComponents, OwnedUiShellHotkeysPresentation, OwnedUiShellClipboardContent, OwnedUiShellComponentPort, OwnedUiShellEditorPort, OwnedUiShellHeaderOptions, OwnedUiShellHeaderPort, OwnedUiShellHistoryEditor, OwnedUiShellImageAssetResolver, OwnedUiShellKeybindingsHost, OwnedUiShellLoadedResourcesPort, OwnedUiShellViewComponentPort } from "../../contracts/owned-ui/index.js";
-import type { TerminalComponentPort, TerminalInputCoordinationScheduler, TerminalInputDiagnosticsEvent, TerminalInputSurfaceKind, TerminalLayoutNode, TerminalPort } from "../../contracts/presentation/index.js";
+import type { TerminalComponentPort, TerminalInputSurfaceKind, TerminalLayoutNode } from "../../contracts/presentation/index.js";
 import type { ShellPresentationPorts, ThemeSource } from "../../contracts/presentation/index.js";
-import type { OwnedUiBackgroundSettingsPort, OwnedUiPromptSuggestionGeneratorPort, OwnedUiSessionBackend, OwnedUiSessionPresenters, OwnedUiSessionViewModel, OwnedUiTranscriptRendererPort, OwnedUiViewportSettings, OwnedUiViewportSettingsPort, OwnedUiQuitOutroSettingsPort, SuggestionDecision, SuggestionDiagnosticObserver } from "../../contracts/owned-ui/index.js";
-import type { UiRouteHost, UiRouteInput } from "../../ui/apps/contracts.js";
+import type { OwnedUiPromptSuggestionGeneratorPort, OwnedUiSessionPresenters, OwnedUiSessionViewModel, OwnedUiTranscriptRendererPort, OwnedUiViewportSettings, SuggestionDecision, SuggestionDiagnosticObserver } from "../../contracts/owned-ui/index.js";
 import type { TranscriptViewportFrame, TranscriptViewportFrameDescriptor } from "../../ui/components/transcript-viewport.js";
 import { PromptChipStore, type PreparedPrompt } from "./prompt-chips.js";
 import type { PastePreparationClientOptions } from "./paste-preparation-client.js";
@@ -15,70 +14,8 @@ import type { PasteEvent, PasteSource } from "./paste-protocol.js";
 import { DockChrome } from "./dock-chrome.js";
 import { WorkflowOutput } from "./workflow-output.js";
 import { TranscriptDocument } from "./transcript-document.js";
-import type { StreamPresentationScheduler } from "./stream-presentation-coalescer.js";
-type OwnedUiTerminalPort = TerminalPort;
-type OwnedUiStartupOptions = OwnedUiShellHeaderOptions;
-/** The engine session the shell presents and the composition's decisions about it. */
-export interface OwnedUiShellEngineOptions {
-    readonly backend: OwnedUiSessionBackend;
-    readonly cwd: string;
-    /**
-     * Declared A1-owned routes. A route this host claims resolves to its app;
-     * every other route continues to the pinned workflow table unchanged.
-     */
-    readonly routeHost?: UiRouteHost;
-    /** One product-owned route presented after the first usable frame and any startup modal. */
-    readonly startupRoute?: {
-        readonly route: string;
-        readonly input?: UiRouteInput;
-        readonly onClosed?: () => void | Promise<void>;
-    };
-    /** Bare A1 selects the owned bounded viewport; comparison profiles stay pinned. */
-    readonly sessionLayout?: "pinned" | "custom-viewport";
-}
-/** Terminal, startup, viewport, and presentation-cadence seams; production leaves most at their defaults. */
-export interface OwnedUiShellPresentationOptions {
-    readonly terminal?: OwnedUiTerminalPort;
-    readonly startup?: OwnedUiStartupOptions;
-    /** Live profile-local settings, supplied only to the bare-A1 composition. */
-    readonly viewportSettings?: OwnedUiViewportSettingsPort;
-    /** Live fullscreen canvas choice, supplied only to the bare-A1 composition. */
-    readonly backgroundSettings?: OwnedUiBackgroundSettingsPort;
-    /** Deterministic scheduling seam for presentation-cadence tests. */
-    readonly stream?: {
-        readonly intervalMs?: number;
-        readonly scheduler?: StreamPresentationScheduler;
-    };
-    /**
-     * Minimum time the reload box stays visible so a fast reload still reads as one.
-     * Production uses the default hold; tests inject `now`/`sleep` for determinism.
-     */
-    readonly reload?: {
-        readonly minVisibleMs?: number;
-        readonly now?: () => number;
-        readonly sleep?: (ms: number) => Promise<void>;
-    };
-    /**
-     * Quit outro settings and seams, supplied only to the bare-A1 composition.
-     * `interactive` states whether the terminal can show the animation; production
-     * passes stdout's TTY state, tests opt in explicitly.
-     */
-    readonly quitOutro?: OwnedUiQuitOutroSettingsPort & {
-        readonly interactive: boolean;
-        readonly now?: () => number;
-        readonly sleep?: (ms: number) => Promise<void>;
-        readonly seed?: number;
-    };
-    readonly input?: {
-        readonly scheduler?: TerminalInputCoordinationScheduler;
-        readonly onEvent?: (event: TerminalInputDiagnosticsEvent) => void;
-        readonly now?: () => number;
-        /** Evidence-only baseline seam; production leaves coordination enabled. */
-        readonly coordination?: boolean;
-        /** Evidence-only baseline seam; production leaves dock reuse enabled. */
-        readonly viewportReuse?: boolean;
-    };
-}
+import type { OwnedUiShellEngineOptions, OwnedUiShellPresentationOptions } from "./shell-options.js";
+export type { OwnedUiShellEngineOptions, OwnedUiShellPresentationOptions } from "./shell-options.js";
 /** Persistent prompt history: its store, its bound, the editor that recalls it, and the image sidecar. */
 export interface OwnedUiShellHistoryOptions {
     readonly store: import("../../contracts/owned-ui/index.js").PromptHistoryPort;
@@ -286,4 +223,3 @@ export type PinnedLayoutParts = Readonly<Record<PinnedLayoutPart, TerminalCompon
  * so its single `transcript` scroll view is shared by whichever session the parts currently resolve to.
  */
 export declare function pinnedLayoutRoot(parts: PinnedLayoutParts, theme: ThemeSource): TerminalLayoutNode;
-export {};

package/dist/app/session-shell/session-shell-root.js

@@ -357,10 +357,14 @@ export class OwnedUiSessionShellRoot {
         const messageStart = queued.length;
         const copyableMessageRows = Array.from({ length: statusRows.length + noticeRows.length }, (_value, index) => ({ row: messageStart + index }));
         const aboveWidgets = this.#extensions.renderWidgets("aboveEditor", width);
-        const input = this.#input.surface.render(width);
-        const body = this.usesDefaultInputSurface() ? this.editor.bodyGeometry?.() : undefined;
         const belowWidgets = this.#extensions.renderWidgets("belowEditor", width);
         const footer = this.#renderFooter(width);
+        // Invariant: reserve transcript context above scrollable routes.
+        const available = Math.max(1, this.#componentRuntime.getRows() - transientRows.length - aboveWidgets.length - belowWidgets.length - footer.length - 3);
+        const surface = this.#input.surface;
+        const input = this.#customViewport && surface.renderInDock !== undefined
+            ? surface.renderInDock(width, available) : surface.render(width);
+        const body = this.usesDefaultInputSurface() ? this.editor.bodyGeometry?.() : undefined;
         const rowsWithoutTransient = [...aboveWidgets, ...input, ...belowWidgets, ...footer];
         const inputOffset = transientRows.length + aboveWidgets.length;
         return {

package/dist/app/session-shell/session-shell.js

@@ -7,7 +7,7 @@ import { LoginInteraction } from "./login-interaction.js";
 import { PromptSubmission } from "./prompt-submission.js";
 import { SessionConcerns } from "./session-concern.js";
 import { composeExitText, SessionStopLatch } from "./session-lifecycle.js";
-import { openWorkflowSelector } from "./workflow-router.js";
+import { openWorkflowSelector, selectSessionCwdRecovery } from "./workflow-router.js";
 import { SessionSelectors } from "./session-selectors.js";
 import { bindSessionSettings, bindShellSettings } from "./settings-bindings.js";
 import { promptSuggestionSurface, suggestionPresentationBlockReason, } from "./suggestion-surface.js";
@@ -181,7 +181,7 @@ export class OwnedUiSessionPresenter {
             this.#dialogs = new SessionDialogCoordinator({
                 terminal: this.#terminal,
                 root: this.root,
-                routeHost: routeHost ?? null, dialogs: options.presenters.components.dialogs,
+                routeHost: routeHost ?? null, dialogs: options.presenters.components.dialogs, inPlaceSession: this.#customViewport,
                 presentation: options.presenters, viewport: () => this.#terminal.viewport(),
                 disposed: () => this.#disposed,
                 exit: () => { void this.shutdown(); },
@@ -315,6 +315,8 @@ export class OwnedUiSessionPresenter {
         }
         // Compatibility: route modal paging and boundary keys before Pi's fullscreen handlers.
         const isDefault = this.root.usesDefaultInputSurface();
+        if (this.#dialogs.handleInputRouteInterrupt(data))
+            return { consume: true };
         if (!this.#terminal.hasOverlay() && !isDefault
             && (this.root.editor.matchesTerminalKey(data, "pageUp")
                 || this.root.editor.matchesTerminalKey(data, "pageDown"))) {
@@ -604,18 +606,12 @@ export class OwnedUiSessionPresenter {
             this.selectors.showModelSelector((result.detail ?? request.argument.trim()) || undefined);
             return { outcome: "completed", diagnostic: null };
         }
-        if (result.outcome === "requires-confirmation" && request.command === "resume") {
-            const confirmed = await this.#extensionBridge.context.confirm("Session cwd not found", result.message);
-            return this.runWorkflow({ ...request, confirmed: confirmed === true });
+        if (result.outcome === "requires-selection" && result.cwdRecovery !== undefined && (request.command === "resume" || request.command === "import")) {
+            return this.runWorkflow(await selectSessionCwdRecovery(request, result, this.#extensionBridge.context));
         }
         if (result.outcome === "requires-confirmation" && request.command === "import") {
-            const recoveringCwd = result.detail !== undefined;
-            const confirmed = await this.#extensionBridge.context.confirm(recoveringCwd ? "Session cwd not found" : "Import session", result.message);
-            return this.runWorkflow({
-                ...request,
-                confirmed: confirmed === true,
-                ...(confirmed === true && result.detail ? { cwdOverride: result.detail } : {}),
-            });
+            const confirmed = await this.#extensionBridge.context.confirm("Import session", result.message);
+            return this.runWorkflow({ ...request, confirmed: confirmed === true });
         }
         if (result.outcome === "requires-selection" || result.outcome === "requires-confirmation") {
             this.root.workflow.appendResult({ command: request.command, outcome: "failed", message: `Owned controller missing for ${request.command}` });
@@ -921,7 +917,7 @@ export class OwnedUiSessionPresenter {
         const skills = this.#skillSummaries();
         const trimmed = argument.trim();
         if (trimmed.length === 0) {
-            this.selectors.showSkillsSelector(skills);
+            await this.selectors.showSkillsSelector(skills);
             return { outcome: "completed", diagnostic: null };
         }
         const separator = trimmed.search(/\s/u);

package/dist/app/session-shell/shell-host.js

@@ -270,8 +270,8 @@ export class OwnedUiTerminalHost {
             requestHyperlinkCleanup: rows => { if (attached())
                 this.#damageTerminal?.requestHyperlinkCleanup(rows); },
             openRoute: (surface, callbacks) => this.#openRoute(presenter, surface, callbacks),
-            // Invariant: an inactive presenter must never hold the active presenter's frames.
-            beginPresentationHold: () => attached() ? runtime.beginPresentationHold() : () => { },
+            // Invariant: only an attached presenter on a running runtime can hold frames.
+            beginPresentationHold: () => attached() && runtime.active ? runtime.beginPresentationHold() : () => { },
             switchMode: mode => runtime.switchMode(mode),
             setTitle: title => { if (attached())
                 runtime.setTitle(title); },

package/dist/app/session-shell/shell-options.d.ts

@@ -0,0 +1,65 @@
+import type { OwnedUiBackgroundSettingsPort, OwnedUiSessionBackend, OwnedUiShellHeaderOptions, OwnedUiViewportSettingsPort, OwnedUiQuitOutroSettingsPort } from "../../contracts/owned-ui/index.js";
+import type { TerminalInputCoordinationScheduler, TerminalInputDiagnosticsEvent, TerminalPort } from "../../contracts/presentation/index.js";
+import type { StreamPresentationScheduler } from "./stream-presentation-coalescer.js";
+import type { UiRouteHost, UiRouteInput } from "../../ui/apps/index.js";
+/** The engine session the shell presents and the composition's decisions about it. */
+export interface OwnedUiShellEngineOptions {
+    readonly backend: OwnedUiSessionBackend;
+    readonly cwd: string;
+    /**
+     * Declared A1-owned routes. A route this host claims resolves to its app;
+     * every other route continues to the pinned workflow table unchanged.
+     */
+    readonly routeHost?: UiRouteHost;
+    /** One product-owned route presented after the first usable frame and any startup modal. */
+    readonly startupRoute?: {
+        readonly route: string;
+        readonly input?: UiRouteInput;
+        readonly onClosed?: () => void | Promise<void>;
+    };
+    /** Bare A1 selects the owned bounded viewport; comparison profiles stay pinned. */
+    readonly sessionLayout?: "pinned" | "custom-viewport";
+}
+/** Terminal, startup, viewport, and presentation-cadence seams; production leaves most at their defaults. */
+export interface OwnedUiShellPresentationOptions {
+    readonly terminal?: TerminalPort;
+    readonly startup?: OwnedUiShellHeaderOptions;
+    /** Live profile-local settings, supplied only to the bare-A1 composition. */
+    readonly viewportSettings?: OwnedUiViewportSettingsPort;
+    /** Live fullscreen canvas choice, supplied only to the bare-A1 composition. */
+    readonly backgroundSettings?: OwnedUiBackgroundSettingsPort;
+    /** Deterministic scheduling seam for presentation-cadence tests. */
+    readonly stream?: {
+        readonly intervalMs?: number;
+        readonly scheduler?: StreamPresentationScheduler;
+    };
+    /**
+     * Minimum time the reload box stays visible so a fast reload still reads as one.
+     * Production uses the default hold; tests inject `now`/`sleep` for determinism.
+     */
+    readonly reload?: {
+        readonly minVisibleMs?: number;
+        readonly now?: () => number;
+        readonly sleep?: (ms: number) => Promise<void>;
+    };
+    /**
+     * Quit outro settings and seams, supplied only to the bare-A1 composition.
+     * `interactive` states whether the terminal can show the animation; production
+     * passes stdout's TTY state, tests opt in explicitly.
+     */
+    readonly quitOutro?: OwnedUiQuitOutroSettingsPort & {
+        readonly interactive: boolean;
+        readonly now?: () => number;
+        readonly sleep?: (ms: number) => Promise<void>;
+        readonly seed?: number;
+    };
+    readonly input?: {
+        readonly scheduler?: TerminalInputCoordinationScheduler;
+        readonly onEvent?: (event: TerminalInputDiagnosticsEvent) => void;
+        readonly now?: () => number;
+        /** Evidence-only baseline seam; production leaves coordination enabled. */
+        readonly coordination?: boolean;
+        /** Evidence-only baseline seam; production leaves dock reuse enabled. */
+        readonly viewportReuse?: boolean;
+    };
+}

package/dist/app/session-shell/shell-options.js

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

package/dist/app/session-shell/viewport-pointer.js

@@ -110,7 +110,11 @@ export class ViewportPointerGestures {
             viewport.setRailHovered(false);
             viewport.setStickyHovered(false);
             this.#position = undefined;
-            owner.component.handleInput?.(report);
+            if (owner.component.handleLocalMouse !== undefined) {
+                owner.component.handleLocalMouse({ ...event, column: event.column - owner.columnStart + 1, row: event.row - owner.rowStart + 1 });
+            }
+            else
+                owner.component.handleInput?.(report);
             outcome.repaint = true;
             return true;
         }

package/dist/app/session-shell/workflow-router.d.ts

@@ -1,4 +1,4 @@
-import type { OwnedUiCommandResult, OwnedUiWorkflowRequest } from "../../contracts/owned-ui/index.js";
+import type { OwnedUiCommandResult, OwnedUiExtensionUiPort, OwnedUiWorkflowRequest, OwnedUiWorkflowResult } from "../../contracts/owned-ui/index.js";
 /** The owned selectors a workflow can open in place of asking the engine to choose. */
 export interface WorkflowSelectors {
     showScopedModelsSelector(): void;
@@ -6,7 +6,7 @@ export interface WorkflowSelectors {
     showModelSelector(initialSearchInput?: string): void;
     showForkSelector(): void;
     showThinkingSelector(): Promise<void>;
-    showTrustSelector(): void;
+    showTrustSelector(): void | Promise<void>;
     showSettingsSelector(): void;
     showSessionSelector(): Promise<void>;
     showLoginAuthTypeSelector(): void;
@@ -14,6 +14,8 @@ export interface WorkflowSelectors {
     showLogoutSelector(): Promise<void>;
     showTreeSelector(): Promise<void>;
 }
+/** Maps the pinned recovery labels back to explicit choices, including Escape as cancellation. */
+export declare function selectSessionCwdRecovery(request: OwnedUiWorkflowRequest, result: OwnedUiWorkflowResult, ui: Pick<OwnedUiExtensionUiPort, "select">): Promise<OwnedUiWorkflowRequest>;
 /**
  * Opens the owned selector a workflow request asks for when the user has not chosen yet. Returns
  * the command result when a selector handled the request, settling once an asynchronous selector

package/dist/app/session-shell/workflow-router.js

@@ -1,3 +1,15 @@
+/** Maps the pinned recovery labels back to explicit choices, including Escape as cancellation. */
+export async function selectSessionCwdRecovery(request, result, ui) {
+    const options = result.options ?? [];
+    const selected = await ui.select(result.message, options.map(option => option.label));
+    const choice = options.find(option => option.label === selected)?.id;
+    const cwdRecoveryChoice = choice === "continue" || choice === "fork" ? choice : "cancel";
+    return {
+        ...request,
+        cwdRecoveryChoice,
+        ...(cwdRecoveryChoice === "continue" ? { cwdOverride: result.cwdRecovery.fallbackCwd } : {}),
+    };
+}
 const unchosen = (request) => request.selection === undefined && request.confirmed === undefined;
 const unchosenBare = (request) => unchosen(request) && request.argument.trim().length === 0;
 // Invariant: the routes are checked in this order, matching the order the workflows were introduced.