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

package/bin/update-recovery.js

@@ -9,19 +9,46 @@ import { dirname, isAbsolute, relative, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 
 const SCHEMA = "a1-update-recovery-v1";
+
+/**
+ * @typedef {object} Capsule
+ * @property {string} transactionId
+ * @property {string} packageName
+ * @property {string} targetVersion
+ * @property {string} packageRoot
+ * @property {string} globalRoot
+ * @property {string} launcherRoot
+ * @property {string[]} launchers
+ * @property {string} priorReleaseId
+ * @property {string} priorReleaseRoot
+ * @property {string} priorContentDigest
+ * @property {string} releaseManifestName
+ * @property {string} recoveryEntry
+ * @property {string} recoveryEntryDigest
+ * @property {string} nodeExecutable
+ * @property {string} npmCli
+ * @property {string[]} npmArguments
+ * @property {string} resultPath
+ * @property {string} cancellationPath
+ * @property {string} ownerPath
+ */
+
 const [, , mode, manifestPath, separator, ...forwarded] = process.argv;
 
 if ((mode !== "--worker" && mode !== "--launch") || !manifestPath || (mode === "--launch" && separator !== "--")) {
   throw new Error("invalid A1 update recovery invocation");
 }
 
-const capsule = await readCapsule(manifestPath);
+/** @type {string} */
+const capsuleManifestPath = manifestPath;
+const capsule = await readCapsule(capsuleManifestPath);
 if (mode === "--worker") {
   await runWorker(capsule);
 } else {
   process.exitCode = await runRecoveredCommand(capsule, forwarded);
 }
 
+/** @param {Capsule} value */
 async function runWorker(value) {
   await rm(value.resultPath, { force: true });
   await writeJson(value.ownerPath, {
@@ -46,12 +73,15 @@ async function runWorker(value) {
     windowsHide: true,
     stdio: ["ignore", "pipe", "pipe"],
   });
+  /** @type {Buffer[]} */
   const stdout = [];
+  /** @type {Buffer[]} */
   const stderr = [];
   child.stdout?.on("data", chunk => stdout.push(Buffer.from(chunk)));
   child.stderr?.on("data", chunk => stderr.push(Buffer.from(chunk)));
   let cancelled = false;
   let forced = false;
+  /** @type {ReturnType<typeof setTimeout> | null} */
   let forceTimer = null;
   const cancellationPoll = setInterval(async () => {
     if (cancelled || !await exists(value.cancellationPath)) return;
@@ -104,20 +134,25 @@ async function runWorker(value) {
   if (launcherDisposition === "unavailable") process.exitCode = 1;
 }
 
+/**
+ * @param {Capsule} value
+ * @param {string[]} arguments_
+ * @returns {Promise<number>}
+ */
 async function runRecoveredCommand(value, arguments_) {
   let entry = await installedTargetEntry(value);
   if (entry === null && arguments_[0] === "update") {
     await rm(value.cancellationPath, { force: true });
     await rm(value.resultPath, { force: true });
     await rm(value.ownerPath, { force: true });
-    const worker = spawn(process.execPath, [fileURLToPath(import.meta.url), "--worker", manifestPath], {
+    const worker = spawn(process.execPath, [fileURLToPath(import.meta.url), "--worker", capsuleManifestPath], {
       detached: true,
       windowsHide: true,
       stdio: "ignore",
     });
     worker.unref();
     const deadline = Date.now() + 15 * 60 * 1000;
-    const requestCancellation = signal => { void writeJson(value.cancellationPath, { schema: SCHEMA, transactionId: value.transactionId, signal, requestedAt: new Date().toISOString() }); };
+    const requestCancellation = (/** @type {string} */ signal) => { void writeJson(value.cancellationPath, { schema: SCHEMA, transactionId: value.transactionId, signal, requestedAt: new Date().toISOString() }); };
     const onSigint = () => requestCancellation("SIGINT");
     const onSigterm = () => requestCancellation("SIGTERM");
     process.on("SIGINT", onSigint);
@@ -138,6 +173,10 @@ async function runRecoveredCommand(value, arguments_) {
   });
 }
 
+/**
+ * @param {string} path
+ * @returns {Promise<Capsule>}
+ */
 async function readCapsule(path) {
   const value = JSON.parse(await readFile(path, "utf8"));
   if (value.launchContract !== "neutral-launch-v1") throw new Error("Unsupported private recovery contract; stop existing processes and install directly with npm. Preserve settings, sessions, and history.");
@@ -167,10 +206,10 @@ async function readCapsule(path) {
   const expectedLaunchers = process.platform === "win32"
     ? [resolve(launcherRoot, "a1"), resolve(launcherRoot, "a1.cmd"), resolve(launcherRoot, "a1.ps1")]
     : [resolve(launcherRoot, "a1")];
-  if (JSON.stringify(value.launchers.map(path => resolve(path))) !== JSON.stringify(expectedLaunchers)) throw new Error("A1 update recovery launcher set is invalid");
+  if (JSON.stringify(value.launchers.map((/** @type {string} */ path) => resolve(path))) !== JSON.stringify(expectedLaunchers)) throw new Error("A1 update recovery launcher set is invalid");
   for (const launcher of value.launchers) assertDirectChild(launcherRoot, resolve(launcher));
   const expectedSidecars = [resolve(lexicalCapsuleRoot, "cancel.json"), resolve(lexicalCapsuleRoot, "result.json"), resolve(lexicalCapsuleRoot, "owner.json")];
-  if (![value.cancellationPath, value.resultPath, value.ownerPath].every((candidate, index) => samePath(candidate, expectedSidecars[index]))) {
+  if (![value.cancellationPath, value.resultPath, value.ownerPath].every((candidate, index) => samePath(candidate, expectedSidecars[index] ?? ""))) {
     throw new Error("A1 update recovery sidecar paths are invalid");
   }
   const dataDir = dirname(dirname(capsuleRoot));
@@ -188,6 +227,7 @@ async function readCapsule(path) {
   return value;
 }
 
+/** @param {Capsule} value */
 async function installedTargetEntry(value) {
   try {
     const manifest = JSON.parse(await readFile(resolve(value.packageRoot, "package.json"), "utf8"));
@@ -197,6 +237,7 @@ async function installedTargetEntry(value) {
   } catch { return null; }
 }
 
+/** @param {Capsule} value */
 async function installedTargetIsCallable(value) {
   if (await installedTargetEntry(value) === null) return false;
   const token = `node_modules/${value.packageName}/bin/cli.js`;
@@ -212,18 +253,20 @@ async function installedTargetIsCallable(value) {
   return true;
 }
 
+/** @param {Capsule} value */
 async function writeRecoveryLaunchers(value) {
   const node = value.nodeExecutable ?? process.execPath;
   const entry = value.recoveryEntry;
-  const manifest = manifestPath;
+  const manifest = capsuleManifestPath;
   const shell = `#!/bin/sh\nexec ${shellQuote(node)} ${shellQuote(entry)} --launch ${shellQuote(manifest)} -- "$@"\n`;
   const command = `@ECHO off\r\n"${node}" "${entry}" --launch "${manifest}" -- %*\r\n`;
   const powershell = `& '${psQuote(node)}' '${psQuote(entry)}' --launch '${psQuote(manifest)}' -- $args\nexit $LASTEXITCODE\n`;
   const content = process.platform === "win32" ? [shell, command, powershell] : [shell];
   await mkdir(value.launcherRoot, { recursive: true });
-  for (let index = 0; index < value.launchers.length; index += 1) await atomicWrite(value.launchers[index], content[index], 0o755);
+  for (let index = 0; index < value.launchers.length; index += 1) await atomicWrite(value.launchers[index] ?? "", content[index] ?? "", 0o755);
 }
 
+/** @param {Capsule} value */
 async function recoveryLaunchersAreCallable(value) {
   for (const path of value.launchers) {
     try {
@@ -236,6 +279,11 @@ async function recoveryLaunchersAreCallable(value) {
   return true;
 }
 
+/**
+ * @param {string} path
+ * @param {string} content
+ * @param {number} mode
+ */
 async function atomicWrite(path, content, mode) {
   const temporary = `${path}.${process.pid}.${randomUUID()}.tmp`;
   await writeFile(temporary, content, { mode });
@@ -244,6 +292,10 @@ async function atomicWrite(path, content, mode) {
   await rename(temporary, path);
 }
 
+/**
+ * @param {string} path
+ * @param {unknown} value
+ */
 async function writeJson(path, value) {
   await mkdir(dirname(path), { recursive: true, mode: 0o700 });
   const temporary = `${path}.${process.pid}.${randomUUID()}.tmp`;
@@ -254,21 +306,38 @@ async function writeJson(path, value) {
   await rename(temporary, path);
 }
 
+/**
+ * @param {string} left
+ * @param {string} right
+ */
 function samePath(left, right) {
   return process.platform === "win32" ? resolve(left).toLowerCase() === resolve(right).toLowerCase() : resolve(left) === resolve(right);
 }
+/**
+ * @param {string} parent
+ * @param {string} child
+ */
 function containedBy(parent, child) {
   const fromParent = relative(parent, child);
   return fromParent.length > 0 && fromParent !== ".." && !fromParent.startsWith(`..${sep}`) && !isAbsolute(fromParent);
 }
+/**
+ * @param {string} parent
+ * @param {string} child
+ */
 function assertDirectChild(parent, child) {
   const expectedParent = resolve(parent);
   const actualParent = dirname(resolve(child));
   const matches = process.platform === "win32" ? actualParent.toLowerCase() === expectedParent.toLowerCase() : actualParent === expectedParent;
   if (!matches) throw new Error(`A1 update recovery path escapes its managed root: ${child}`);
 }
+/** @param {string} value */
 function shellQuote(value) { return `'${String(value).replaceAll("'", `'"'"'`)}'`; }
+/** @param {string} value */
 function psQuote(value) { return String(value).replaceAll("'", "''"); }
+/** @param {string} value */
 function bounded(value) { return value.length <= 64 * 1024 ? value : value.slice(-64 * 1024); }
+/** @param {string} path */
 async function exists(path) { return await lstat(path).then(() => true).catch(() => false); }
+/** @param {number} ms */
 async function sleep(ms) { await new Promise(resolvePromise => setTimeout(resolvePromise, ms)); }

package/bin/warmup.js

@@ -1,5 +1,8 @@
 #!/usr/bin/env node
 
+// Invariant: one terminal module identity per process, decided before any A1 or Pi module loads.
+const [{ installPinnedPiTuiResolver }, { fileURLToPath: toPath }] = await Promise.all([import("./module-resolver.js"), import("node:url")]);
+installPinnedPiTuiResolver(toPath(new URL("..", import.meta.url)));
 const startup = await import("../dist/foundation/startup/startup-runtime.js");
 startup.assertImmutableWarmupEnvironment(process.env);
 startup.enableEnvironmentCompileCache(process.env);

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

@@ -1,4 +1,4 @@
-import type { PiTuiInputDiagnosticsEvent } from "../tui-runtime/contracts.js";
+import type { PiTuiInputDiagnosticsEvent } from "../../integrations/pi/tui-runtime/contracts.js";
 import type { ResponseCopyEvent } from "./response-copy-protocol.js";
 import type { PasteEvent } from "./paste-protocol.js";
 /** Opt-in scalar-only snapshots, bounded to 128 rows and one pending asynchronous write. */

package/dist/{integrations/pi/session-ui → app/session-shell}/clipboard-image.js

@@ -1,4 +1,4 @@
-import { ImageAttachmentError, MAX_IMAGE_DATA_BYTES } from "../../../contracts/owned-ui/index.js";
+import { ImageAttachmentError, MAX_IMAGE_DATA_BYTES } from "../../contracts/owned-ui/index.js";
 import { MAX_SOURCE_IMAGE_BYTES } from "./image-source.js";
 const STANDARD_BASE64 = /^[A-Za-z0-9+/]*={0,2}$/u;
 /**

package/dist/app/session-shell/helper-pool.d.ts

@@ -0,0 +1,33 @@
+import type { ChildProcess } from "node:child_process";
+/** How long an unused spare helper may idle before it is stopped so a background session holds no extra process. */
+export declare const HELPER_SPARE_IDLE_MS: number;
+export interface SpareHelper {
+    readonly child: ChildProcess;
+    /** Whether the helper already announced itself; the taker must then send the first request itself. */
+    readonly ready: boolean;
+}
+export interface HelperPoolOptions {
+    readonly fork: () => ChildProcess;
+    /** Stops a spare that is no longer wanted; the paste helper needs its process group killed on POSIX. */
+    readonly stop: (child: ChildProcess) => void;
+    readonly idleMs?: number;
+}
+/**
+ * Keeps one forked IPC helper ready so a request takes a live child instead of paying fork and module
+ * load on its own critical path. The spare stays idle on its channel until it is taken; a spare that
+ * exits or idles too long is dropped, and the next request forks cold and warms a replacement afterwards.
+ */
+export declare class HelperPool {
+    #private;
+    constructor(options: HelperPoolOptions);
+    /** Whether a spare is currently held (ready or still starting). */
+    get warmed(): boolean;
+    /** Opts the pool in and forks the first spare; from here on `replenish` keeps one ready after each request. */
+    warm(): void;
+    /** Forks the next spare after a request released its child; a no-op until the owner warmed the pool. A fork failure leaves the pool empty. */
+    replenish(): void;
+    /** Hands the spare to a request, with the pool's listeners removed; returns nothing when no live spare is held. */
+    take(): SpareHelper | undefined;
+    /** Stops the held spare and refuses further warming. */
+    dispose(): void;
+}

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

@@ -0,0 +1,98 @@
+/** How long an unused spare helper may idle before it is stopped so a background session holds no extra process. */
+export const HELPER_SPARE_IDLE_MS = 5 * 60_000;
+/**
+ * Keeps one forked IPC helper ready so a request takes a live child instead of paying fork and module
+ * load on its own critical path. The spare stays idle on its channel until it is taken; a spare that
+ * exits or idles too long is dropped, and the next request forks cold and warms a replacement afterwards.
+ */
+export class HelperPool {
+    #fork;
+    #stop;
+    #idleMs;
+    #spare;
+    #enabled = false;
+    #disposed = false;
+    constructor(options) {
+        this.#fork = options.fork;
+        this.#stop = options.stop;
+        this.#idleMs = options.idleMs ?? HELPER_SPARE_IDLE_MS;
+    }
+    /** Whether a spare is currently held (ready or still starting). */
+    get warmed() { return this.#spare !== undefined; }
+    /** Opts the pool in and forks the first spare; from here on `replenish` keeps one ready after each request. */
+    warm() {
+        if (this.#disposed)
+            return;
+        this.#enabled = true;
+        this.replenish();
+    }
+    /** Forks the next spare after a request released its child; a no-op until the owner warmed the pool. A fork failure leaves the pool empty. */
+    replenish() {
+        if (!this.#enabled || this.#disposed || this.#spare !== undefined)
+            return;
+        let child;
+        try {
+            child = this.#fork();
+        }
+        catch {
+            return;
+        }
+        const onMessage = (value) => {
+            if (this.#spare?.child === child && value?.kind === "ready")
+                this.#spare.ready = true;
+        };
+        const onExit = () => { if (this.#spare?.child === child) {
+            this.#drop();
+        } };
+        const detach = () => {
+            child.off("message", onMessage);
+            child.off("exit", onExit);
+            child.off("close", onExit);
+            child.off("error", onExit);
+        };
+        // Performance: an idle spare must not keep a background session alive or hold a process forever.
+        const timer = setTimeout(() => { if (this.#spare?.child === child)
+            this.#discard(); }, this.#idleMs);
+        timer.unref();
+        child.on("message", onMessage);
+        child.once("exit", onExit);
+        child.once("close", onExit);
+        child.once("error", onExit);
+        // Invariant: an idle spare never keeps the owner's process alive; taking it refs it again.
+        child.unref();
+        child.channel?.unref();
+        this.#spare = { child, ready: false, timer, detach };
+    }
+    /** Hands the spare to a request, with the pool's listeners removed; returns nothing when no live spare is held. */
+    take() {
+        const spare = this.#spare;
+        if (spare === undefined)
+            return undefined;
+        this.#drop();
+        if (spare.child.exitCode !== null || spare.child.signalCode !== null || !spare.child.connected)
+            return undefined;
+        spare.child.ref();
+        spare.child.channel?.ref();
+        return { child: spare.child, ready: spare.ready };
+    }
+    /** Stops the held spare and refuses further warming. */
+    dispose() {
+        this.#disposed = true;
+        this.#discard();
+    }
+    #drop() {
+        const spare = this.#spare;
+        if (spare === undefined)
+            return;
+        this.#spare = undefined;
+        clearTimeout(spare.timer);
+        spare.detach();
+    }
+    #discard() {
+        const spare = this.#spare;
+        if (spare === undefined)
+            return;
+        this.#drop();
+        this.#stop(spare.child);
+    }
+}

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

@@ -1,4 +1,4 @@
-import type { PiShellClipboardContent } from "../components/index.js";
+import type { PiShellClipboardContent } from "../../integrations/pi/components/index.js";
 import type { ImagePreparationLimits, PreparedImage } from "./image-preparation.js";
 import type { ImageWorkerRequest } from "./image-worker.js";
 export type PreparedClipboardContent = {

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

@@ -1,5 +1,5 @@
 import { Worker } from "node:worker_threads";
-import { ImageAttachmentError } from "../../../contracts/owned-ui/index.js";
+import { ImageAttachmentError } from "../../contracts/owned-ui/index.js";
 import { IMAGE_PREPARATION_MS, MAX_SOURCE_IMAGE_BYTES } from "./image-source.js";
 /** Owns bounded paste acquisition and one off-thread conversion, canceled on session disposal. */
 export class ImagePreparationClient {

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

@@ -1,5 +1,5 @@
 import { isMainThread } from "node:worker_threads";
-import { ImageAttachmentError } from "../../../contracts/owned-ui/index.js";
+import { ImageAttachmentError } from "../../contracts/owned-ui/index.js";
 import { canonicalizeClipboardImage } from "./clipboard-image.js";
 import { sourceImageInfo } from "./image-source.js";
 export const IMAGE_TARGET_BASE64_BYTES = 4.5 * 1024 * 1024;

package/dist/{integrations/pi/session-ui → app/session-shell}/image-source.js

@@ -1,4 +1,4 @@
-import { ImageAttachmentError } from "../../../contracts/owned-ui/index.js";
+import { ImageAttachmentError } from "../../contracts/owned-ui/index.js";
 export const MAX_SOURCE_IMAGE_BYTES = 20 * 1024 * 1024;
 export const MAX_SOURCE_PIXELS = 40_000_000;
 export const MAX_SOURCE_DIMENSION = 32_768;

package/dist/{integrations/pi/session-ui → app/session-shell}/image-worker.js

@@ -1,5 +1,5 @@
 import { parentPort, workerData } from "node:worker_threads";
-import { ImageAttachmentError } from "../../../contracts/owned-ui/index.js";
+import { ImageAttachmentError } from "../../contracts/owned-ui/index.js";
 import { prepareImage } from "./image-preparation.js";
 import { canonicalizeClipboardImage } from "./clipboard-image.js";
 import { readSystemClipboardContent } from "./system-clipboard.js";

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

@@ -0,0 +1,7 @@
+export { ClipboardDiagnosticCapture } from "./clipboard-diagnostics.js";
+export { ContextualPromptSuggestionController, samePromptSuggestionIdentity } from "./prompt-suggestion-controller.js";
+export type { ContextualPromptSuggestionControllerOptions, ContextualPromptSuggestionSurface } from "./prompt-suggestion-controller.js";
+export { OwnedUiSessionShell, OwnedUiSessionShellRoot, formatSessionResumeCommand, quoteCommandArgument } from "./session-shell.js";
+export type { OwnedUiSessionShellOptions, OwnedUiShellDiagnosticOptions, OwnedUiShellEngineOptions, OwnedUiShellHistoryOptions, OwnedUiShellPresentationOptions, OwnedUiShellSuggestionOptions, SessionResumeCommandMetadata, } from "./session-shell.js";
+export { STREAM_PRESENTATION_INTERVAL_MS, StreamPresentationCoalescer } from "./stream-presentation-coalescer.js";
+export type { StreamPresentationScheduler } from "./stream-presentation-coalescer.js";

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

@@ -0,0 +1,4 @@
+export { ClipboardDiagnosticCapture } from "./clipboard-diagnostics.js";
+export { ContextualPromptSuggestionController, samePromptSuggestionIdentity } from "./prompt-suggestion-controller.js";
+export { OwnedUiSessionShell, OwnedUiSessionShellRoot, formatSessionResumeCommand, quoteCommandArgument } from "./session-shell.js";
+export { STREAM_PRESENTATION_INTERVAL_MS, StreamPresentationCoalescer } from "./stream-presentation-coalescer.js";

package/dist/app/session-shell/paste-executor.d.ts

@@ -0,0 +1,18 @@
+import { type ChildProcess } from "node:child_process";
+import type { PiShellClipboardContent } from "../../integrations/pi/components/shell-shared-facade.js";
+import { type PreparedPaste, type PasteEvent } from "./paste-protocol.js";
+import { HelperPool } from "./helper-pool.js";
+export interface PasteExecutorJob {
+    readonly result: Promise<PreparedPaste>;
+    readonly stopped: Promise<void>;
+    cancel(): void;
+}
+export type PastePhase = (phase: PasteEvent["phase"], bytes?: number) => void;
+/** Forks one paste helper: no inherited descriptors, JSON IPC only, and its own process group on POSIX. */
+export declare function forkPasteHelper(helper?: URL): ChildProcess;
+/** Kills a paste helper and everything it spawned, then lets the parent exit without waiting for it. */
+export declare function stopPasteHelper(child: ChildProcess): void;
+/** A spare-of-one pool of paste helpers; `startPasteExecutor` takes its child and warms the next one after each paste. */
+export declare function createPasteHelperPool(helper?: URL, idleMs?: number): HelperPool;
+/** Streams bounded fragments through a killable child; native/codec/filesystem work never runs on the UI thread. */
+export declare function startPasteExecutor(content: PiShellClipboardContent | undefined, signal: AbortSignal, phase?: PastePhase, helper?: URL, pool?: HelperPool): PasteExecutorJob;

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

@@ -1,7 +1,8 @@
 import { fork } from "node:child_process";
-import { ImageAttachmentError } from "../../../contracts/owned-ui/image-attachments.js";
+import { ImageAttachmentError } from "../../contracts/owned-ui/index.js";
 import { MAX_SOURCE_IMAGE_BYTES } from "./image-source.js";
 import { PASTE_CHUNK_UNITS, PASTE_REQUESTS, PASTE_STOP_MS, PASTE_TEXT_BYTES, pasteFragments } from "./paste-protocol.js";
+import { HelperPool } from "./helper-pool.js";
 const live = new Set();
 const conversionQueue = [];
 let converting;
@@ -18,14 +19,8 @@ function permitConversion() {
     converting = child;
     child.send({ kind: "convert" }, () => { });
 }
-/** Streams bounded fragments through a killable child; native/codec/filesystem work never runs on the UI thread. */
-export function startPasteExecutor(content, signal, phase = () => { }, helper) {
-    const tooLarge = content?.kind === "text" && content.text.length > PASTE_TEXT_BYTES;
-    if (signal.aborted || live.size >= PASTE_REQUESTS || tooLarge) {
-        const result = Promise.reject(new ImageAttachmentError(signal.aborted ? "image-canceled" : tooLarge ? "paste-size" : "paste-busy"));
-        void result.catch(() => { });
-        return { result, stopped: Promise.resolve(), cancel() { } };
-    }
+/** Forks one paste helper: no inherited descriptors, JSON IPC only, and its own process group on POSIX. */
+export function forkPasteHelper(helper) {
     const source = new URL(import.meta.url).pathname.endsWith(".ts");
     const entry = helper ?? new URL(source ? "./paste-helper.ts" : "./paste-helper.js", import.meta.url);
     const options = {
@@ -33,22 +28,40 @@ export function startPasteExecutor(content, signal, phase = () => { }, helper) {
         stdio: ["ignore", "ignore", "ignore", "ipc"], serialization: "json", windowsHide: true,
         detached: process.platform !== "win32",
     };
-    const child = fork(entry, [], options);
-    const forceStop = () => {
-        // Concurrency: POSIX command fallbacks share this isolated process group; kill descendants too.
-        if (process.platform !== "win32" && child.pid !== undefined) {
-            try {
-                process.kill(-child.pid, "SIGKILL");
-            }
-            catch {
-                child.kill("SIGKILL");
-            }
+    return fork(entry, [], options);
+}
+/** Kills a paste helper and everything it spawned, then lets the parent exit without waiting for it. */
+export function stopPasteHelper(child) {
+    // Concurrency: POSIX command fallbacks share this isolated process group; kill descendants too.
+    if (process.platform !== "win32" && child.pid !== undefined) {
+        try {
+            process.kill(-child.pid, "SIGKILL");
         }
-        else
+        catch {
             child.kill("SIGKILL");
-        child.unref();
-        child.channel?.unref();
-    };
+        }
+    }
+    else
+        child.kill("SIGKILL");
+    child.unref();
+    child.channel?.unref();
+}
+/** A spare-of-one pool of paste helpers; `startPasteExecutor` takes its child and warms the next one after each paste. */
+export function createPasteHelperPool(helper, idleMs) {
+    return new HelperPool({ fork: () => forkPasteHelper(helper), stop: stopPasteHelper, ...(idleMs === undefined ? {} : { idleMs }) });
+}
+/** Streams bounded fragments through a killable child; native/codec/filesystem work never runs on the UI thread. */
+export function startPasteExecutor(content, signal, phase = () => { }, helper, pool) {
+    const tooLarge = content?.kind === "text" && content.text.length > PASTE_TEXT_BYTES;
+    if (signal.aborted || live.size >= PASTE_REQUESTS || tooLarge) {
+        const result = Promise.reject(new ImageAttachmentError(signal.aborted ? "image-canceled" : tooLarge ? "paste-size" : "paste-busy"));
+        void result.catch(() => { });
+        return { result, stopped: Promise.resolve(), cancel() { } };
+    }
+    // Performance: a warm spare skips fork and module load on the paste's own critical path.
+    const spare = pool?.take();
+    const child = spare?.child ?? forkPasteHelper(helper);
+    const forceStop = () => stopPasteHelper(child);
     live.add(child);
     let input = sourceMessages(content);
     let canceled = false, done = false;
@@ -84,6 +97,14 @@ export function startPasteExecutor(content, signal, phase = () => { }, helper) {
         stopTimer.unref();
     };
     const fail = (code = "paste-unavailable") => { failure = new ImageAttachmentError(code); cancel(); };
+    const advance = () => {
+        const next = input?.next();
+        if (!next || next.done) {
+            fail();
+            return;
+        }
+        send(next.value);
+    };
     signal.addEventListener("abort", cancel, { once: true });
     child.on("message", value => {
         if (canceled)
@@ -91,12 +112,7 @@ export function startPasteExecutor(content, signal, phase = () => { }, helper) {
         const message = value;
         try {
             if (message?.kind === "ready") {
-                const next = input?.next();
-                if (!next || next.done) {
-                    fail();
-                    return;
-                }
-                send(next.value);
+                advance();
             }
             else if (message?.kind === "phase") {
                 if (!["acquired-text", "acquired-image", "classifying", "path-fallback", "prepared"].includes(message.phase) || phases.has(message.phase)) {
@@ -210,9 +226,14 @@ export function startPasteExecutor(content, signal, phase = () => { }, helper) {
             phase("cleanup");
         }
         catch { /* Invariant: cleanup observation cannot retain an exited executor. */ }
+        // Performance: the next paste finds a spare that was forked while nothing waited on it.
+        pool?.replenish();
     };
     child.once("exit", cleanup);
     child.once("close", cleanup);
+    // Protocol: a spare already announced itself while pooled, so its first request is sent now rather than on "ready".
+    if (spare?.ready)
+        advance();
     void result.catch(() => { });
     return { result, stopped: exit, cancel };
 }

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

@@ -1,5 +1,5 @@
 import { Worker } from "node:worker_threads";
-import { ImageAttachmentError } from "../../../contracts/owned-ui/index.js";
+import { ImageAttachmentError } from "../../contracts/owned-ui/index.js";
 import { readSystemClipboardContent } from "./system-clipboard.js";
 import { MAX_SOURCE_IMAGE_BYTES } from "./image-source.js";
 import { preparePasteText } from "./paste-text-preparation.js";

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

@@ -0,0 +1,31 @@
+import { startPasteExecutor } from "./paste-executor.js";
+import { type PasteEvent, type PasteSource, type PreparedPaste } from "./paste-protocol.js";
+export interface PreparedPasteJob<T> {
+    readonly result: Promise<T>;
+    cancel(): void;
+    complete(): void;
+    isCurrent(): boolean;
+}
+/** Starts one isolated preparation; the production starter forks the paste helper, tests may prepare in process. */
+export type PasteExecutorStarter = typeof startPasteExecutor;
+export interface PastePreparationClientOptions {
+    readonly onEvent?: (event: PasteEvent) => void;
+    /** Test seam: replaces the forked helper entirely; no spare is kept when it is set. */
+    readonly execute?: PasteExecutorStarter;
+    /** Package/fault-test seam for the forked helper's entry. */
+    readonly helper?: URL;
+    /** Idle bound for the spare helper; production keeps the default. */
+    readonly spareIdleMs?: number;
+}
+/** Keeps eight distinct paste transactions alive through insertion; canceled executors retain capacity until fenced. */
+export declare class PastePreparationClient {
+    #private;
+    constructor(options?: PastePreparationClientOptions);
+    /** Forks the spare helper now so the first paste takes a live child; later pastes rewarm it themselves. */
+    warm(): void;
+    /** Whether a spare helper is held; diagnostics and tests only. */
+    get warmed(): boolean;
+    start<T>(source: PasteSource, adopt: (value: PreparedPaste, signal: AbortSignal) => Promise<T> | T, onImage: () => void, onText?: () => void): PreparedPasteJob<T>;
+    reset(): void;
+    dispose(): Promise<void>;
+}