@timurproko/a1 0.1.8-dev.472 → 0.1.8-dev.508

package/dist/{integrations/pi/session-ui → app/session-shell}/paste-preparation-client.js

@@ -1,15 +1,25 @@
-import { ImageAttachmentError } from "../../../contracts/owned-ui/index.js";
-import { startPasteExecutor } from "./paste-executor.js";
+import { ImageAttachmentError } from "../../contracts/owned-ui/index.js";
+import { createPasteHelperPool, startPasteExecutor } from "./paste-executor.js";
 import { PASTE_READ_MS, PASTE_REQUESTS, PASTE_STOP_MS, PASTE_TOTAL_MS } from "./paste-protocol.js";
 /** Keeps eight distinct paste transactions alive through insertion; canceled executors retain capacity until fenced. */
 export class PastePreparationClient {
-    onEvent;
     #active = new Set();
+    #onEvent;
+    #execute;
+    #helper;
+    #pool;
     #sequence = 0;
     #disposed = false;
-    constructor(onEvent) {
-        this.onEvent = onEvent;
+    constructor(options = {}) {
+        this.#onEvent = options.onEvent;
+        this.#execute = options.execute ?? startPasteExecutor;
+        this.#helper = options.helper;
+        this.#pool = options.execute === undefined ? createPasteHelperPool(options.helper, options.spareIdleMs) : undefined;
     }
+    /** Forks the spare helper now so the first paste takes a live child; later pastes rewarm it themselves. */
+    warm() { this.#pool?.warm(); }
+    /** Whether a spare helper is held; diagnostics and tests only. */
+    get warmed() { return this.#pool?.warmed ?? false; }
     start(source, adopt, onImage, onText = () => { }) {
         const controller = new AbortController();
         const id = ++this.#sequence;
@@ -22,7 +32,7 @@ export class PastePreparationClient {
         const emit = (phase, bytes, outcome) => {
             const atMs = performance.now();
             try {
-                this.onEvent?.({ request: id, phase, atMs, elapsedMs: atMs - admitted, pending: this.#active.size, transport: source.kind === "text" ? "terminal" : source.kind,
+                this.#onEvent?.({ request: id, phase, atMs, elapsedMs: atMs - admitted, pending: this.#active.size, transport: source.kind === "text" ? "terminal" : source.kind,
                     ...(bytes === undefined ? {} : { bytes }), ...(outcome === undefined ? {} : { outcome }) });
             }
             catch { /* Invariant: observations never affect input. */ }
@@ -100,7 +110,7 @@ export class PastePreparationClient {
                         }
                         content = read;
                     }
-                    executor = startPasteExecutor(content, controller.signal, (phase, bytes) => {
+                    executor = this.#execute(content, controller.signal, (phase, bytes) => {
                         // Protocol: helper exit precedes adoption; only the request's finally block reports complete cleanup.
                         if (phase === "cleanup")
                             return;
@@ -113,7 +123,7 @@ export class PastePreparationClient {
                         if (phase === "acquired-text")
                             onText();
                         emit(phase, bytes);
-                    });
+                    }, this.#helper, this.#pool);
                     const value = await executor.result;
                     if (controller.signal.aborted)
                         return;
@@ -150,6 +160,7 @@ export class PastePreparationClient {
     async dispose() {
         this.#disposed = true;
         this.reset();
+        this.#pool?.dispose();
         let timer;
         await Promise.race([Promise.all([...this.#active].map(active => active.stopped)),
             new Promise(resolve => { timer = setTimeout(resolve, PASTE_STOP_MS); timer.unref(); })]);

package/dist/{integrations/pi/session-ui → app/session-shell}/paste-protocol.d.ts

@@ -1,4 +1,4 @@
-import type { PiShellClipboardContent } from "../components/index.js";
+import type { PiShellClipboardContent } from "../../integrations/pi/components/index.js";
 import type { PreparedPasteText, ClipboardPath } from "./paste-text-preparation.js";
 import type { PreparedImage } from "./image-preparation.js";
 export declare const PASTE_READ_MS = 5000;

package/dist/{integrations/pi/session-ui → app/session-shell}/paste-protocol.js

@@ -1,4 +1,4 @@
-import { MAX_CLIPBOARD_TEXT_BYTES } from "../../../contracts/owned-ui/index.js";
+import { MAX_CLIPBOARD_TEXT_BYTES } from "../../contracts/owned-ui/index.js";
 export const PASTE_READ_MS = 5_000;
 export const PASTE_TOTAL_MS = 15_000;
 export const PASTE_STOP_MS = 250;

package/dist/app/session-shell/paste-text-preparation.d.ts

@@ -0,0 +1,6 @@
+import type { PreparedPasteText } from "./paste-types.js";
+export type { ClipboardPath, PreparedPasteText } from "./paste-types.js";
+/** Small non-path text has a fixed CPU bound and cannot enter filesystem probing. */
+export declare function canPreparePasteInline(text: string): boolean;
+/** The shared chip classifier; interactive callers run path/filesystem probing in an isolated executor. */
+export declare function preparePasteText(text: string, skipPaths?: boolean, compactPaths?: boolean): PreparedPasteText;

package/dist/{integrations/pi/session-ui/paste-text-preparation.d.ts → app/session-shell/paste-types.d.ts}

@@ -1,3 +1,4 @@
+/** Paste classification results shared by text preparation and path chip presentation. */
 export interface ClipboardPath {
     readonly fullPath: string;
     readonly kind: "folder" | "file";
@@ -14,7 +15,3 @@ export type PreparedPasteText = {
     readonly kind: "paths";
     readonly paths: readonly ClipboardPath[];
 };
-/** Small non-path text has a fixed CPU bound and cannot enter filesystem probing. */
-export declare function canPreparePasteInline(text: string): boolean;
-/** The shared chip classifier; interactive callers run path/filesystem probing in an isolated executor. */
-export declare function preparePasteText(text: string, skipPaths?: boolean, compactPaths?: boolean): PreparedPasteText;

package/dist/{integrations/pi/session-ui → app/session-shell}/path-chip-presentation.d.ts

@@ -1,4 +1,4 @@
-import type { ClipboardPath, PreparedPasteText } from "./paste-text-preparation.js";
+import type { ClipboardPath, PreparedPasteText } from "./paste-types.js";
 export declare const PATH_CHIP_PRESENTATION_UNITS = 4096;
 export declare const PATH_CHIP_SUFFIX_UNITS = 20;
 /** Shared base tag for presentation budgeting and actual chip adoption, including image-file spacing. */

package/dist/{integrations/pi/session-ui → app/session-shell}/prompt-chips.d.ts

@@ -1,4 +1,5 @@
-import type { PiShellClipboardContent, PiShellEditorTextRange } from "../components/shell-shared-facade.js";
+import type { PiShellClipboardContent, PiShellEditorTextRange } from "../../integrations/pi/components/shell-shared-facade.js";
+import { type PastePreparationClientOptions } from "./paste-preparation-client.js";
 import type { PasteEvent, PasteSource } from "./paste-protocol.js";
 export interface PromptImageAttachment {
     readonly type: "image";
@@ -15,7 +16,10 @@ export declare class PromptChipStore {
     constructor(options?: {
         readonly isolated?: boolean;
         readonly onEvent?: (event: PasteEvent) => void;
+        readonly preparation?: Omit<PastePreparationClientOptions, "onEvent">;
     });
+    /** Forks the spare paste helper so the session's first paste does not pay for helper startup. */
+    warm(): void;
     beginPaste(currentText: string, read: ((signal: AbortSignal) => Promise<PiShellClipboardContent | null>) | PasteSource, onError: (error: unknown) => void, onImage?: () => void): {
         marker: string;
         result: Promise<string>;

package/dist/{integrations/pi/session-ui → app/session-shell}/prompt-chips.js

@@ -1,7 +1,7 @@
 import { randomBytes } from "node:crypto";
 import path from "node:path";
 import { canonicalizeClipboardImage } from "./clipboard-image.js";
-import { assertImageEncodedSize, assertPromptImages, ImageAttachmentError } from "../../../contracts/owned-ui/image-attachments.js";
+import { assertImageEncodedSize, assertPromptImages, ImageAttachmentError } from "../../contracts/owned-ui/index.js";
 import { ImagePreparationClient } from "./image-preparation-client.js";
 import { preparePasteText } from "./paste-text-preparation.js";
 import { pathChipTag } from "./path-chip-presentation.js";
@@ -26,8 +26,12 @@ export class PromptChipStore {
     #provisionalOwners = new Map();
     #ownedChipTags = new Map();
     constructor(options = {}) {
-        this.#isolated = options.isolated ? new PastePreparationClient(options.onEvent) : undefined;
+        this.#isolated = options.isolated
+            ? new PastePreparationClient({ ...options.preparation, ...(options.onEvent === undefined ? {} : { onEvent: options.onEvent }) })
+            : undefined;
     }
+    /** Forks the spare paste helper so the session's first paste does not pay for helper startup. */
+    warm() { this.#isolated?.warm(); }
     beginPaste(currentText, read, onError, onImage = () => { }) {
         if (this.#isolated)
             return this.#beginIsolatedPaste(currentText, typeof read === "function" ? { kind: "provided", read } : read, onError, onImage);

package/dist/{integrations/pi/session-ui → app/session-shell}/prompt-history-controller.d.ts

@@ -1,5 +1,5 @@
-import { type PromptHistoryKind, type PromptHistoryPort } from "../../../contracts/owned-ui/index.js";
-import type { PiShellEditorPort } from "../components/index.js";
+import { type PromptHistoryKind, type PromptHistoryPort } from "../../contracts/owned-ui/index.js";
+import type { PiShellEditorPort } from "../../integrations/pi/components/index.js";
 /** Merges bounded recall snapshots; the editor alone owns browsing, draft, cursor, and undo state. */
 export declare class PromptHistoryController {
     #private;

package/dist/{integrations/pi/session-ui → app/session-shell}/prompt-history-controller.js

@@ -1,8 +1,7 @@
 import { randomUUID } from "node:crypto";
-import { PROMPT_HISTORY_MAX_TEXT_BYTES } from "../../../contracts/owned-ui/index.js";
+import { PROMPT_HISTORY_MAX_TEXT_BYTES } from "../../contracts/owned-ui/index.js";
 /** Merges bounded recall snapshots; the editor alone owns browsing, draft, cursor, and undo state. */
 export class PromptHistoryController {
-    options;
     #local = new Map();
     #unsubscribe;
     #snapshot;
@@ -14,6 +13,7 @@ export class PromptHistoryController {
     #unsubscribeFailure;
     #closeFailed = false;
     #closePromise;
+    options;
     constructor(options) {
         this.options = options;
         if (options.editor.recall === undefined)

package/dist/{integrations/pi/session-ui → app/session-shell}/prompt-suggestion-controller.d.ts

@@ -1,4 +1,4 @@
-import { type OwnedUiPromptSuggestionGeneratorPort, type OwnedUiPromptSuggestionIdentity, type OwnedUiPromptSuggestionState, type SuggestionDecision, type SuggestionDecisionReason, type SuggestionDiagnosticObserver } from "../../../contracts/owned-ui/index.js";
+import { type OwnedUiPromptSuggestionGeneratorPort, type OwnedUiPromptSuggestionIdentity, type OwnedUiPromptSuggestionState, type SuggestionDecision, type SuggestionDecisionReason, type SuggestionDiagnosticObserver } from "../../contracts/owned-ui/index.js";
 export interface ContextualPromptSuggestionSurface {
     canPresent(identity: OwnedUiPromptSuggestionIdentity): boolean;
     presentationBlockReason?(identity: OwnedUiPromptSuggestionIdentity): SuggestionDecision;

package/dist/{integrations/pi/session-ui → app/session-shell}/prompt-suggestion-controller.js

@@ -1,7 +1,6 @@
-import { assertOwnedUiPromptSuggestionResult, normalizePromptSuggestionCandidate, } from "../../../contracts/owned-ui/index.js";
+import { assertOwnedUiPromptSuggestionResult, normalizePromptSuggestionCandidate, } from "../../contracts/owned-ui/index.js";
 /** Prefetches one inert candidate; owns retirement even when a provider ignores abort. */
 export class ContextualPromptSuggestionController {
-    options;
     #state = { status: "idle" };
     #request = null;
     #lastConsidered = "";
@@ -12,6 +11,7 @@ export class ContextualPromptSuggestionController {
     #requestSequence = 0;
     #timeoutMs;
     #now;
+    options;
     constructor(options) {
         this.options = options;
         this.#enabled = options.enabled;

package/dist/{integrations/pi/session-ui → app/session-shell}/quit-outro.js

@@ -5,7 +5,7 @@
  * terminal never shows a half-painted step, and playback is bounded so a slow
  * terminal cannot delay restoration past the configured clamp.
  */
-import { displayWidth, truncateToWidth } from "../../../ui/components/index.js";
+import { displayWidth, truncateToWidth } from "../../ui/components/index.js";
 import { createQuitOutroPlan } from "./quit-outro-effects.js";
 export const QUIT_OUTRO_MIN_MS = 300;
 export const QUIT_OUTRO_MAX_MS = 2000;

package/dist/{integrations/pi/session-ui → app/session-shell}/response-copy-coordinator.d.ts

@@ -1,4 +1,4 @@
-import { type SelectionCopySnapshot } from "../../../ui/components/selection-copy.js";
+import { type SelectionCopySnapshot } from "../../ui/components/selection-copy.js";
 import { type CopyResult, type ResponseCopyEvent } from "./response-copy-protocol.js";
 import type { ResponseCopyExecutor } from "./response-copy-transport.js";
 /** Owns one delivery and one newest pending copy, including expiry and side-effect fencing. */

package/dist/{integrations/pi/session-ui → app/session-shell}/response-copy-coordinator.js

@@ -1,8 +1,7 @@
-import { MAX_COPY_SOURCE_UNITS } from "../../../ui/components/selection-copy.js";
+import { MAX_COPY_SOURCE_UNITS } from "../../ui/components/selection-copy.js";
 import { COPY_CLEANUP_MS, COPY_DEADLINE_MS } from "./response-copy-protocol.js";
 /** Owns one delivery and one newest pending copy, including expiry and side-effect fencing. */
 export class ResponseCopyCoordinator {
-    options;
     #sequence = 0;
     #epoch = 0;
     #active;
@@ -11,9 +10,8 @@ export class ResponseCopyCoordinator {
     #latestPending = false;
     #disposed = false;
     #quarantined = false;
-    constructor(options) {
-        this.options = options;
-    }
+    options;
+    constructor(options) { this.options = options; }
     get busy() { return this.#active !== undefined || this.#pending !== undefined; }
     get latest() { return this.#latest; }
     /** Exact prompt copy/cut shares the write lifetime without transcript text transformations. */

package/dist/{integrations/pi/session-ui → app/session-shell}/response-copy-helper.js

@@ -1,4 +1,4 @@
-import { MAX_COPY_ROWS, MAX_COPY_SOURCE_UNITS, selectionCopyRowText } from "../../../ui/components/index.js";
+import { MAX_COPY_ROWS, MAX_COPY_SOURCE_UNITS, selectionCopyRowText } from "../../ui/components/index.js";
 import { COPY_CHUNK_UNITS, MAX_COPY_BYTES, MAX_COPY_CONTROL_BYTES } from "./response-copy-protocol.js";
 // Security: this isolated executor never inherits the UI terminal and never logs clipboard contents.
 let header;

package/dist/{integrations/pi/session-ui → app/session-shell}/response-copy-protocol.d.ts

@@ -1,4 +1,4 @@
-import type { OrderedTextSelection, SelectionCopyPrompt } from "../../../ui/components/index.js";
+import type { OrderedTextSelection, SelectionCopyPrompt } from "../../ui/components/index.js";
 export declare const COPY_DEADLINE_MS = 5000;
 export declare const COPY_CLEANUP_MS = 250;
 export declare const MAX_COPY_BYTES: number;

package/dist/{integrations/pi/session-ui → app/session-shell}/response-copy-transport.d.ts

@@ -1,4 +1,4 @@
-import type { SelectionCopySnapshot } from "../../../ui/components/selection-copy.js";
+import type { SelectionCopySnapshot } from "../../ui/components/selection-copy.js";
 import { type CopyResult } from "./response-copy-protocol.js";
 export interface ResponseCopyJob {
     readonly result: Promise<CopyResult>;
@@ -8,6 +8,12 @@ export interface ResponseCopyJob {
 }
 export type CopyPhaseObserver = (phase: "extracted" | "encoded" | "submitting", bytes: number, transport: "native" | "terminal" | "injected") => void;
 export type ResponseCopyExecutor = (snapshot: SelectionCopySnapshot, phase: CopyPhaseObserver) => ResponseCopyJob;
+/** The production executor also owns a spare helper; the owner warms it at start and disposes it at shutdown. */
+export interface OwnedResponseCopyExecutor extends ResponseCopyExecutor {
+    warm(): void;
+    dispose(): void;
+    readonly warmed: boolean;
+}
 export interface ResponseCopyTerminal {
     readonly maxBytes?: number;
     /** A supported non-blocking submission boundary, not clipboard acknowledgment. */
@@ -28,4 +34,6 @@ export declare function createResponseCopyExecutor(options?: {
     readonly writeText?: (text: string, signal: AbortSignal) => Promise<void>;
     /** Package/fault-test seam: the production helper is always an emitted sibling. */
     readonly helper?: URL;
-}): ResponseCopyExecutor;
+    /** Idle bound for the spare helper; production keeps the default. */
+    readonly spareIdleMs?: number;
+}): OwnedResponseCopyExecutor;

package/dist/{integrations/pi/session-ui → app/session-shell}/response-copy-transport.js

@@ -1,5 +1,6 @@
 import { fork } from "node:child_process";
 import { fstatSync } from "node:fs";
+import { HelperPool } from "./helper-pool.js";
 import { COPY_CHUNK_UNITS, COPY_CLEANUP_MS, MAX_COPY_BYTES, MAX_COPY_CONTROL_BYTES } from "./response-copy-protocol.js";
 /** Never substitute a remote host's native clipboard for the terminal user's clipboard. */
 export function responseCopyDestination(env) {
@@ -22,7 +23,8 @@ export function hasAsyncClipboardOutput(platform = process.platform, stdout = pr
 }
 /** Isolates preparation and native clipboard access; only the owner may submit terminal controls. */
 export function createResponseCopyExecutor(options = {}) {
-    return (snapshot, phase) => {
+    const pool = new HelperPool({ fork: () => forkCopyHelper(options.helper), stop: stopCopyHelper, ...(options.spareIdleMs === undefined ? {} : { idleMs: options.spareIdleMs }) });
+    const execute = (snapshot, phase) => {
         const controller = new AbortController();
         let active;
         const run = async () => {
@@ -33,7 +35,7 @@ export function createResponseCopyExecutor(options = {}) {
                 if (mode === "terminal" && options.terminal === undefined) {
                     return { kind: "result", result: { outcome: "failed", failure: "unsafe" } };
                 }
-                active = startHelper(snapshot, mode, options.terminal?.maxBytes ?? MAX_COPY_CONTROL_BYTES, phase, options.helper);
+                active = startHelper(snapshot, mode, options.terminal?.maxBytes ?? MAX_COPY_CONTROL_BYTES, phase, options.helper, pool);
                 if (controller.signal.aborted)
                     active.cancel();
                 return active.result;
@@ -65,6 +67,28 @@ export function createResponseCopyExecutor(options = {}) {
         const result = run().catch(() => ({ outcome: controller.signal.aborted ? "canceled" : "failed", failure: "transport" }));
         return { result, stopped: result.then(() => { }), cancel: () => { controller.abort(); active?.cancel(); } };
     };
+    // Rationale: `Object.assign` would copy the getter's value once; the accessor must read the pool each time.
+    return Object.defineProperties(execute, {
+        warm: { value: () => pool.warm() },
+        dispose: { value: () => pool.dispose() },
+        warmed: { get: () => pool.warmed },
+    });
+}
+/** Forks one copy helper: bounded IPC only, no clipboard payload in argv or temp files, no inherited terminal descriptors. */
+function forkCopyHelper(helper) {
+    const source = new URL(import.meta.url).pathname.endsWith(".ts");
+    const entry = helper ?? new URL(source ? "./response-copy-helper.ts" : "./response-copy-helper.js", import.meta.url);
+    const forkOptions = {
+        execArgv: entry.pathname.endsWith(".ts") ? ["--import", "tsx"] : [],
+        stdio: ["ignore", "ignore", "ignore", "ipc"], windowsHide: true,
+        serialization: "json",
+    };
+    return fork(entry, [], forkOptions);
+}
+function stopCopyHelper(child) {
+    child.kill("SIGKILL");
+    child.unref();
+    child.channel?.unref();
 }
 function* sourceMessages(snapshot, mode, controlLimit) {
     yield { kind: "begin", selection: snapshot.selection, rows: snapshot.rows.length, mode, controlLimit,
@@ -77,16 +101,10 @@ function* sourceMessages(snapshot, mode, controlLimit) {
     }
     yield { kind: "finish" };
 }
-function startHelper(snapshot, mode, controlLimit, phase, helper) {
-    const source = new URL(import.meta.url).pathname.endsWith(".ts");
-    const entry = helper ?? new URL(source ? "./response-copy-helper.ts" : "./response-copy-helper.js", import.meta.url);
-    // Security: bounded IPC only, no clipboard payload in argv/temp files, and no inherited terminal descriptors.
-    const forkOptions = {
-        execArgv: entry.pathname.endsWith(".ts") ? ["--import", "tsx"] : [],
-        stdio: ["ignore", "ignore", "ignore", "ipc"], windowsHide: true,
-        serialization: "json",
-    };
-    const child = fork(entry, [], forkOptions);
+function startHelper(snapshot, mode, controlLimit, phase, helper, pool) {
+    // Performance: a warm spare skips fork and module load on the copy's own critical path.
+    const spare = pool.take();
+    const child = spare?.child ?? forkCopyHelper(helper);
     let iterator = sourceMessages(snapshot, mode, controlLimit);
     let outcome;
     let stopping = false;
@@ -123,18 +141,21 @@ function startHelper(snapshot, mode, controlLimit, phase, helper) {
                 resolve(value);
             prepared = [];
         };
+        const advance = () => {
+            const next = iterator?.next();
+            if (next === undefined || next.done) {
+                cancel();
+                return;
+            }
+            child.send(next.value, error => { if (error)
+                cancel(); });
+        };
         child.on("message", value => {
             const message = value;
             if (stopping)
                 return;
             if (message?.kind === "ready") {
-                const next = iterator?.next();
-                if (next === undefined || next.done) {
-                    cancel();
-                    return;
-                }
-                child.send(next.value, error => { if (error)
-                    cancel(); });
+                advance();
             }
             else if (message?.kind === "data") {
                 if (mode !== "prepare" || expectedBytes === undefined || typeof message.text !== "string" || message.text.length > COPY_CHUNK_UNITS) {
@@ -178,6 +199,8 @@ function startHelper(snapshot, mode, controlLimit, phase, helper) {
                 clearTimeout(cleanup);
             child.removeAllListeners("message");
             settle();
+            // Performance: the next copy finds a spare that was forked while nothing waited on it.
+            pool.replenish();
         });
         // Platform: spawn failure has no exit event, but has a close event and no live executor to fence.
         child.once("close", () => {
@@ -186,6 +209,9 @@ function startHelper(snapshot, mode, controlLimit, phase, helper) {
                 clearTimeout(cleanup);
             settle();
         });
+        // Protocol: a spare already announced itself while pooled, so its first request is sent now rather than on "ready".
+        if (spare?.ready)
+            advance();
     });
     return { result, cancel };
 }

package/dist/{integrations/pi/session-ui → app/session-shell}/session-shell-root.d.ts

@@ -1,13 +1,14 @@
-import type { OwnedUiPromptSuggestionGeneratorPort, OwnedUiSessionViewModel, OwnedUiViewportSettings, OwnedUiViewportSettingsPort, OwnedUiQuitOutroSettingsPort, SuggestionDecision, SuggestionDiagnosticObserver } from "../../../contracts/owned-ui/index.js";
-import type { PiTuiPointerSurface } from "../tui-runtime/contracts.js";
-import type { UiRouteHost } from "../../../ui/apps/contracts.js";
-import type { TranscriptViewportFrame, TranscriptViewportFrameDescriptor } from "../../../ui/components/transcript-viewport.js";
-import type { PiEngineAdapter } from "../engine/adapter.js";
-import type { PiWorkflowMessage, PiWorkflowResult } from "../engine/workflows.js";
-import { type PiShellClipboardContent, type PiShellComponentPort, type PiShellEditorPort, type PiShellExtensionRendererResolver, type PiShellHeaderOptions, type PiShellHeaderPort, type PiShellImageAssetResolver, type PiShellLoadedResourcesPort, type PiShellResourceEntry, type PiShellTranscriptComponentPort } from "../components/shell-shared-facade.js";
-import { type PiTuiInputCoordinationScheduler, type PiTuiInputSurfaceKind } from "../tui-runtime/input-presentation-coordinator.js";
-import type { PiTuiComponentPort, PiTuiInputDiagnosticsEvent, PiTuiLayoutNode, PiTuiTerminalPort } from "../tui-runtime/contracts.js";
+import type { OwnedUiPromptSuggestionGeneratorPort, OwnedUiSessionViewModel, OwnedUiViewportSettings, OwnedUiViewportSettingsPort, OwnedUiQuitOutroSettingsPort, SuggestionDecision, SuggestionDiagnosticObserver } from "../../contracts/owned-ui/index.js";
+import type { PiTuiPointerSurface } from "../../integrations/pi/tui-runtime/contracts.js";
+import type { UiRouteHost } from "../../ui/apps/contracts.js";
+import type { TranscriptViewportFrame, TranscriptViewportFrameDescriptor } from "../../ui/components/transcript-viewport.js";
+import type { PiEngineAdapter } from "../../integrations/pi/engine/adapter.js";
+import type { PiWorkflowMessage, PiWorkflowResult } from "../../integrations/pi/engine/workflows.js";
+import { type PiShellClipboardContent, type PiShellComponentPort, type PiShellEditorPort, type PiShellExtensionRendererResolver, type PiShellHeaderOptions, type PiShellHeaderPort, type PiShellImageAssetResolver, type PiShellLoadedResourcesPort, type PiShellResourceEntry, type PiShellTranscriptComponentPort } from "../../integrations/pi/components/shell-shared-facade.js";
+import { type PiTuiInputCoordinationScheduler, type PiTuiInputSurfaceKind } from "../../integrations/pi/tui-runtime/input-presentation-coordinator.js";
+import type { PiTuiComponentPort, PiTuiInputDiagnosticsEvent, PiTuiLayoutNode, PiTuiTerminalPort } from "../../integrations/pi/tui-runtime/contracts.js";
 import { type PreparedPrompt } from "./prompt-chips.js";
+import type { PastePreparationClientOptions } from "./paste-preparation-client.js";
 import { type SessionViewportInputResult } from "./session-viewport-controller.js";
 import type { ResponseCopyExecutor } from "./response-copy-transport.js";
 import type { ResponseCopyEvent } from "./response-copy-protocol.js";
@@ -24,20 +25,10 @@ export interface OwnedUiClipboardPort {
     } | null>;
     writeText?(text: string, signal?: AbortSignal): Promise<void>;
 }
-export interface OwnedUiSessionShellOptions {
-    readonly promptHistory?: {
-        readonly store: import("../../../contracts/owned-ui/index.js").PromptHistoryPort;
-        readonly limit: number;
-        readonly editor: import("../components/index.js").HistoryEditorConstructor;
-        /** Optional per-profile filesystem sidecar for image chip payloads. When present, submit
-         * writes each referenced attachment and recall reads them back to rehydrate live chips.
-         * When absent, image chips silently strip on recall, matching the missing-sidecar path. */
-        readonly imageSidecar?: import("../../../contracts/owned-ui/index.js").PromptHistoryImageSidecarPort;
-    };
+/** The engine session the shell presents and the composition's decisions about it. */
+export interface OwnedUiShellEngineOptions {
     readonly backend: OwnedUiBackendPort;
     readonly cwd: string;
-    readonly terminal?: OwnedUiTerminalPort;
-    readonly startup?: OwnedUiStartupOptions;
     /**
      * Declared A1-owned routes. A route this host claims resolves to its app;
      * every other route continues to the pinned workflow table unchanged.
@@ -45,30 +36,15 @@ export interface OwnedUiSessionShellOptions {
     readonly routeHost?: UiRouteHost;
     /** 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;
-    /**
-     * 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;
-    };
-    /** Optional platform seam; production uses A1's system clipboard adapter. */
-    readonly clipboard?: OwnedUiClipboardPort;
-    /** Owned response-copy transport and payload-free diagnostic seams. Comparison profiles ignore them. */
-    readonly responseCopy?: {
-        readonly execute?: ResponseCopyExecutor;
-        readonly onEvent?: (event: ResponseCopyEvent) => void;
-    };
-    /** Bounded, payload-free clipboard acquisition/preparation observations. */
-    readonly pasteDiagnostics?: (event: PasteEvent) => void;
     /** Deterministic scheduling seam for presentation-cadence tests. */
-    readonly streamPresentation?: {
+    readonly stream?: {
         readonly intervalMs?: number;
         readonly scheduler?: StreamPresentationScheduler;
     };
@@ -76,19 +52,23 @@ export interface OwnedUiSessionShellOptions {
      * 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 reloadPresentation?: {
+    readonly reload?: {
         readonly minVisibleMs?: number;
         readonly now?: () => number;
         readonly sleep?: (ms: number) => Promise<void>;
     };
-    /** Optional deterministic seam for keyboard scheduling and phase evidence. */
-    readonly promptSuggestions?: {
-        readonly diagnostics?: SuggestionDiagnosticObserver;
-        readonly generator: OwnedUiPromptSuggestionGeneratorPort;
-        readonly enabled: () => boolean;
-        readonly onChange: (listener: (enabled: boolean) => void) => () => 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 inputPresentation?: {
+    readonly input?: {
         readonly scheduler?: PiTuiInputCoordinationScheduler;
         readonly onEvent?: (event: PiTuiInputDiagnosticsEvent) => void;
         readonly now?: () => number;
@@ -98,6 +78,45 @@ export interface OwnedUiSessionShellOptions {
         readonly viewportReuse?: boolean;
     };
 }
+/** 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;
+    readonly limit: number;
+    readonly editor: import("../../integrations/pi/components/index.js").HistoryEditorConstructor;
+    /** Optional per-profile filesystem sidecar for image chip payloads. When present, submit
+     * writes each referenced attachment and recall reads them back to rehydrate live chips.
+     * When absent, image chips silently strip on recall, matching the missing-sidecar path. */
+    readonly imageSidecar?: import("../../contracts/owned-ui/index.js").PromptHistoryImageSidecarPort;
+}
+/** Contextual prompt suggestions: the generator, the enablement setting, and an optional evidence seam. */
+export interface OwnedUiShellSuggestionOptions {
+    readonly diagnostics?: SuggestionDiagnosticObserver;
+    readonly generator: OwnedUiPromptSuggestionGeneratorPort;
+    readonly enabled: () => boolean;
+    readonly onChange: (listener: (enabled: boolean) => void) => () => void;
+}
+/** Clipboard seams and payload-free diagnostics; comparison profiles ignore the diagnostics. */
+export interface OwnedUiShellDiagnosticOptions {
+    /** Optional platform seam; production uses A1's system clipboard adapter. */
+    readonly clipboard?: OwnedUiClipboardPort;
+    /** Owned response-copy transport and payload-free diagnostic seams. */
+    readonly responseCopy?: {
+        readonly execute?: ResponseCopyExecutor;
+        readonly onEvent?: (event: ResponseCopyEvent) => void;
+    };
+    /** Bounded, payload-free clipboard acquisition/preparation observations. */
+    readonly paste?: (event: PasteEvent) => void;
+    /** Test seams for isolated paste preparation: an in-process starter, or the forked helper's entry. */
+    readonly pastePreparation?: Omit<PastePreparationClientOptions, "onEvent" | "spareIdleMs">;
+}
+/** What composes an owned session shell, grouped by the collaborator that provides each part. */
+export interface OwnedUiSessionShellOptions {
+    readonly engine: OwnedUiShellEngineOptions;
+    readonly presentation?: OwnedUiShellPresentationOptions;
+    readonly history?: OwnedUiShellHistoryOptions;
+    readonly suggestions?: OwnedUiShellSuggestionOptions;
+    readonly diagnostics?: OwnedUiShellDiagnosticOptions;
+}
 /** Composes backend session state into the owned transcript, viewport, editor, and dock presentation. */
 export declare class OwnedUiSessionShellRoot implements PiTuiComponentPort {
     #private;
@@ -112,7 +131,7 @@ export declare class OwnedUiSessionShellRoot implements PiTuiComponentPort {
         readonly requestHyperlinkCleanup?: (rows?: readonly number[]) => void;
         readonly enableDockInputReuse?: boolean;
         readonly persistentHistory?: boolean;
-        readonly historyEditor?: import("../components/index.js").HistoryEditorConstructor;
+        readonly historyEditor?: import("../../integrations/pi/components/index.js").HistoryEditorConstructor;
         readonly onSubmit: (text: string) => void;
         readonly onPasteRejected?: (error: unknown) => void;
         readonly onInterrupt: () => void;
@@ -132,6 +151,7 @@ export declare class OwnedUiSessionShellRoot implements PiTuiComponentPort {
         readonly readClipboardContent?: (signal?: AbortSignal) => Promise<PiShellClipboardContent | null>;
         readonly captureClipboardPaste?: () => PasteSource;
         readonly pasteDiagnostics?: (event: PasteEvent) => void;
+        readonly pastePreparation?: Omit<PastePreparationClientOptions, "onEvent">;
     }, startup?: PiShellHeaderOptions, agentDir?: string, extensionRenderers?: PiShellExtensionRendererResolver, sessionLayout?: "pinned" | "custom-viewport", imageAssets?: PiShellImageAssetResolver);
     setEditorPaddingX(padding: number): void;
     setAutocompleteMaxVisible(maxVisible: number): void;
@@ -140,7 +160,7 @@ export declare class OwnedUiSessionShellRoot implements PiTuiComponentPort {
     setMermaidRenderingMode(mode: "off" | "final" | "streaming"): void;
     setImagePresentation(showImages: boolean, imageWidthCells: number): void;
     prepareHistoryText(text: string): string;
-    rehydrateHistoryText(text: string, resolveImage: (id: string) => import("../../../contracts/owned-ui/index.js").PromptHistoryImageSidecarAttachment | null): string;
+    rehydrateHistoryText(text: string, resolveImage: (id: string) => import("../../contracts/owned-ui/index.js").PromptHistoryImageSidecarAttachment | null): string;
     imageChipAttachmentsFromEditor(text: string): {
         readonly id: string;
         readonly tag: string;
@@ -154,6 +174,8 @@ export declare class OwnedUiSessionShellRoot implements PiTuiComponentPort {
     hasPendingPastes(text: string): boolean;
     waitForPromptPastes(text: string, signal: AbortSignal): Promise<PreparedPrompt>;
     resetPendingPastes(): void;
+    /** Forks the spare paste helper so the first paste of the session takes a live child. */
+    warmPastePreparation(): void;
     disposePendingPastes(): Promise<void>;
     promptSuggestionPrepareBlockReason(): SuggestionDecision;
     canPreparePromptSuggestion(): boolean;
@@ -192,7 +214,7 @@ export declare class OwnedUiSessionShellRoot implements PiTuiComponentPort {
         followingEnd: boolean;
         scrollTop: number;
         maxScroll: number;
-        cause: "detached" | "initial" | "steady" | "dock-input" | "follow-shift" | "geometry-change" | null;
+        cause: "initial" | "steady" | "dock-input" | "follow-shift" | "detached" | "geometry-change" | null;
     };
     /** Visible non-selectable Steering, alignment, and Working rows, for rendering evidence. */
     viewportTransientTailRowCount(): number;