@timurproko/a1 0.2.6 → 0.2.7-dev.1222

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

@@ -0,0 +1,276 @@
+import { assertOwnedUiCommand, assertPromptImages, ImageAttachmentError, } from "../../contracts/owned-ui/index.js";
+import { renderPiShellStatusText } from "../../integrations/pi/components/shell-presenters-info.js";
+const rejected = (diagnostic) => ({ outcome: "rejected", diagnostic });
+/**
+ * Turns editor input into engine commands: prompts, steering, follow-ups, and bash, each recorded
+ * in history first. It holds a submission whose image pastes are still preparing, journals prompts
+ * for resident tabs, and recovers the draft when a submission is rejected.
+ */
+export class PromptSubmission {
+    #ports;
+    #waiting = new Map();
+    #editorRevision = 0;
+    constructor(ports) {
+        this.#ports = ports;
+    }
+    /** True while a submission waits for its image pastes. */
+    get waiting() {
+        return this.#waiting.size > 0;
+    }
+    /** The editor changed; a later recovery never overwrites input typed after its submission. */
+    noteEditorChange() {
+        this.#editorRevision++;
+    }
+    submit(text) {
+        return this.#whenReady(text, () => this.#submit(text));
+    }
+    queueFollowUp(draft) {
+        return this.#whenReady(draft, () => this.#queueFollowUp(draft));
+    }
+    cancelWaiting() {
+        for (const item of this.#waiting.values())
+            item.controller.abort();
+    }
+    /** Puts waiting submissions and the engine's queued input back into the editor. */
+    restoreQueued() {
+        const queued = [...this.#waiting.keys(), ...this.#ports.backend.workflows.clearQueuedWorkflows()];
+        this.cancelWaiting();
+        if (queued.length === 0)
+            return;
+        this.#ports.root.editor.setText(queued.join("\n"));
+        this.#ports.terminal.requestRender();
+    }
+    /** Sends slash text the shell does not own as engine prompt input; history keeps what was typed. */
+    sendSlashPrompt(text, typed = text) {
+        this.#rememberInput(typed, "slash");
+        this.#ports.root.resumeViewportFollowing();
+        return this.execute({
+            type: this.#ports.lifecycle() === "busy" ? "steer" : "prompt",
+            correlationId: this.#ports.correlation("prompt-command"),
+            sessionId: this.#ports.backend.identity.sessionId,
+            text,
+        });
+    }
+    /** Executes a command; with a draft, a rejected or failed submission puts the draft back for recovery. */
+    async execute(command, draft) {
+        const { backend } = this.#ports;
+        if (draft === undefined)
+            return backend.session.execute(command);
+        const revision = this.#editorRevision;
+        try {
+            assertOwnedUiCommand(command);
+        }
+        catch (error) {
+            return this.#recover(draft, revision, error);
+        }
+        try {
+            const result = await backend.session.execute(command);
+            if (result.outcome === "rejected")
+                return this.#recover(draft, revision);
+            return result;
+        }
+        catch {
+            // Security: dispatch might already have reached the provider. Never retry automatically.
+            this.#ports.root.editor.addToHistory(draft);
+            this.#ports.promptHistory()?.rememberRecovery(draft);
+            this.reportError(undefined, "Submission failed; delivery is uncertain. Check the conversation before retrying. Press Up to recover the draft.");
+            return { outcome: "failed", diagnostic: "submission delivery is uncertain" };
+        }
+    }
+    reportError(error, message) {
+        // Security: arbitrary provider/extension error messages can contain the entire request.
+        try {
+            this.#ports.root.appendWorkflowResult({ command: "debug", outcome: "failed", message: message
+                    ?? (error instanceof ImageAttachmentError ? error.message : "Submission failed. Check the prompt and try again.") }, error instanceof ImageAttachmentError ? error.code : undefined);
+            this.#ports.terminal.requestRender();
+        }
+        catch { /* Security: error presentation cannot create another rejected submission callback. */ }
+    }
+    onSessionReplaced() {
+        this.cancelWaiting();
+    }
+    dispose() {
+        this.cancelWaiting();
+    }
+    #whenReady(draft, action) {
+        const { root, backend } = this.#ports;
+        const previous = this.#waiting.get(draft);
+        if (previous !== undefined)
+            return previous.result;
+        if (!root.hasPendingPastes(draft))
+            return this.#guard(draft, action);
+        const controller = new AbortController();
+        const generation = backend.identity.sessionGeneration;
+        const result = this.#guard(draft, async () => {
+            await root.waitForPromptPastes(draft, controller.signal);
+            if (controller.signal.aborted || this.#ports.disposed() || backend.identity.sessionGeneration !== generation)
+                return rejected("image submission canceled");
+            return action();
+        }).finally(() => {
+            this.#waiting.delete(draft);
+            if (!this.#ports.disposed())
+                this.#showWaiting();
+        });
+        this.#waiting.set(draft, { controller, result });
+        if (root.editor.getText() === draft)
+            root.editor.setText("");
+        this.#showWaiting();
+        return result;
+    }
+    #showWaiting() {
+        const count = this.#waiting.size;
+        this.#ports.root.setExtensionWidget("owned-image-preparation", count === 0 ? null : {
+            render: width => [...renderPiShellStatusText(`Waiting for images (${count} submission${count === 1 ? "" : "s"}) — Esc cancels; dequeue restores`, width)],
+            invalidate: () => { },
+        }, "aboveEditor");
+        this.#ports.terminal.requestRender();
+    }
+    async #guard(draft, action) {
+        const revision = this.#editorRevision;
+        try {
+            return await action();
+        }
+        catch (error) {
+            if (error instanceof ImageAttachmentError && error.code === "image-canceled")
+                return rejected("image submission canceled");
+            return this.#recover(draft, revision, error);
+        }
+    }
+    #recover(draft, revision, error) {
+        const { root } = this.#ports;
+        root.editor.addToHistory(draft);
+        this.#ports.promptHistory()?.rememberRecovery(draft);
+        // Concurrency: never overwrite input typed (even typed and cleared) after this submission.
+        if (revision === this.#editorRevision && root.editor.getText().length === 0)
+            root.editor.setText(draft);
+        const message = error instanceof ImageAttachmentError ? error.message : "Submission rejected. Check the prompt and attachments.";
+        this.reportError(error, error instanceof ImageAttachmentError && error.code === "image-count"
+            ? message
+            : `${message} Press Up to recover the draft.`);
+        return rejected(message);
+    }
+    #rememberInput(text, kind) {
+        const { root } = this.#ports;
+        root.editor.addToHistory(text);
+        const history = this.#ports.promptHistory();
+        if (history === null)
+            return;
+        const reusable = root.prepareHistoryText(text);
+        if (reusable.length === 0) {
+            history.rememberRecovery(text);
+            return;
+        }
+        // Rationale: write the image chip payloads referenced by an editor draft to the sidecar
+        // directory before their history row commits. Missing sidecar dependency = silent skip; the
+        // recall path treats an absent sidecar the same as a corrupt one.
+        const sidecar = this.#ports.imageSidecar();
+        if (sidecar !== undefined) {
+            for (const record of root.imageChipAttachmentsFromEditor(text)) {
+                sidecar.write(record.id, { tag: record.tag, data: record.image.data, mimeType: record.image.mimeType, savedAt: new Date().toISOString() });
+            }
+        }
+        history.capture(reusable, kind, this.#ports.cwd, this.#ports.backend.identity.sessionId);
+    }
+    async #submit(text) {
+        this.#ports.invalidateSuggestions();
+        const displayInput = text.trim();
+        if (!displayInput)
+            return { outcome: "completed", diagnostic: null };
+        if (displayInput.startsWith("/"))
+            return this.#ports.slashCommand(displayInput);
+        const { root, backend } = this.#ports;
+        const prepared = root.preparePromptSubmission(displayInput);
+        assertPromptImages(prepared.images);
+        const input = prepared.text.trim();
+        if (input.startsWith("!")) {
+            const bash = await this.#bash(input, displayInput);
+            if (bash !== undefined)
+                return bash;
+        }
+        // Compatibility: match interactive Pi: input during compaction is queued steering; the engine
+        // shows it in the pending rows and delivers it when compaction ends.
+        const type = this.#ports.lifecycle() === "busy" ? "steer" : "prompt";
+        this.#rememberInput(root.omitUnsentPromptImages(displayInput).trim(), type);
+        root.resumeViewportFollowing();
+        const command = {
+            type,
+            correlationId: this.#ports.correlation(type),
+            sessionId: backend.identity.sessionId,
+            text: input,
+            ...(prepared.images.length === 0 ? {} : { images: prepared.images }),
+        };
+        let submission;
+        try {
+            submission = await this.#ports.residentTab.admit({
+                sessionId: command.sessionId,
+                sessionFile: this.#ports.currentSessionFile(),
+                kind: type,
+                text: input,
+            });
+        }
+        catch {
+            if (root.editor.getText().length === 0)
+                root.editor.setText(displayInput);
+            const message = "Prompt was not sent because its recovery journal could not be synchronized.";
+            this.reportError(undefined, message);
+            return rejected(message);
+        }
+        const finishSending = prepared.images.length === 0 ? () => { } : root.beginImageSubmissionStatus();
+        try {
+            const result = await this.execute(command, displayInput);
+            if (submission !== undefined && result.outcome !== "rejected") {
+                await this.#ports.residentTab.dispatched(submission.id, command.correlationId);
+            }
+            return result;
+        }
+        finally {
+            finishSending();
+        }
+    }
+    // Protocol: `!command` runs bash with its output in context, `!!command` keeps it out; an empty command is prompt text.
+    async #bash(input, displayInput) {
+        const excludeFromContext = input.startsWith("!!");
+        const command = input.slice(excludeFromContext ? 2 : 1).trim();
+        if (!command)
+            return undefined;
+        this.#rememberInput(displayInput, "bash");
+        try {
+            const result = await this.#ports.backend.workflows.executeBashWorkflow(command, excludeFromContext);
+            const workflow = {
+                command: "debug",
+                outcome: result.cancelled ? "cancelled" : result.exitCode === 0 || result.exitCode === undefined ? "completed" : "failed",
+                message: result.cancelled ? "Bash command cancelled" : `Bash exited ${result.exitCode ?? 0}: ${command}`,
+                ...(result.output ? { detail: result.output } : {}),
+            };
+            this.#ports.root.appendWorkflowResult(workflow);
+            this.#ports.terminal.requestRender();
+            return workflow.outcome === "failed" ? rejected(workflow.message) : { outcome: "completed", diagnostic: null };
+        }
+        catch (error) {
+            const message = `Bash command failed: ${error instanceof Error ? error.message : String(error)}`;
+            this.#ports.root.appendWorkflowResult({ command: "debug", outcome: "failed", message });
+            this.#ports.terminal.requestRender();
+            return rejected(message);
+        }
+    }
+    async #queueFollowUp(draft) {
+        const { root, backend } = this.#ports;
+        const displayInput = draft.trim();
+        if (!displayInput)
+            return rejected("nothing to queue");
+        const prepared = root.preparePromptSubmission(displayInput);
+        assertPromptImages(prepared.images);
+        const text = prepared.text.trim();
+        this.#rememberInput(displayInput, "follow-up");
+        if (root.editor.getText() === draft)
+            root.editor.setText("");
+        root.resumeViewportFollowing();
+        return this.execute({
+            type: "follow-up",
+            correlationId: this.#ports.correlation("follow-up"),
+            sessionId: backend.identity.sessionId,
+            text,
+            ...(prepared.images.length === 0 ? {} : { images: prepared.images }),
+        }, displayInput);
+    }
+}

package/dist/app/session-shell/resident-tab-coordinator.d.ts

@@ -0,0 +1,38 @@
+import type { OwnedUiEvent, PromptHistoryImageSidecarPort } from "../../contracts/owned-ui/index.js";
+import type { SessionConcern } from "./session-concern.js";
+import type { OwnedUiShellEngineOptions, OwnedUiSessionShellRoot } from "./session-shell-root.js";
+export type ResidentTabOptions = NonNullable<OwnedUiShellEngineOptions["residentTab"]>;
+export interface ResidentTabCoordinatorPorts {
+    readonly root: Pick<OwnedUiSessionShellRoot, "appendWorkflowStatus" | "rehydrateHistoryText" | "editor">;
+}
+/**
+ * The session presenter's side of a resident tab: recovered input, the idle status it reports to
+ * the strip, prompt admission and correlation through the recovery journal, draft checkpoints,
+ * detach on quit, and the graceful stop when the presenter is released. Outside a resident tab
+ * every operation is a no-op.
+ */
+export declare class ResidentTabCoordinator implements SessionConcern {
+    #private;
+    constructor(options: ResidentTabOptions | undefined, ports: ResidentTabCoordinatorPorts);
+    /** True inside a resident tab, where Settings and the session name live in the global strip. */
+    get active(): boolean;
+    checkpoint(text: string): void;
+    closeOwnedRoute(route: string): void;
+    /** Puts the prompts and draft a previous tab process left unfinished back into the editor. */
+    restoreInput(imageSidecar?: PromptHistoryImageSidecarPort): void;
+    /** Reports idle to the strip whenever the session leaves its busy lifecycle. */
+    observeLifecycle(event: OwnedUiEvent): void;
+    /** Journals a prompt before it is sent; undefined outside a resident tab. Rejects when the journal cannot sync. */
+    admit(input: Parameters<NonNullable<ResidentTabOptions["admit"]>>[0]): Promise<{
+        readonly id: string;
+    } | undefined>;
+    /** The admitted prompt reached the engine; its journal entry is correlated with the engine's entry. */
+    dispatched(submissionId: string, entryId: string): Promise<void>;
+    /**
+     * Leaves the tab without stopping its engine. Returns undefined outside a resident tab, true when
+     * the client detached, or the notice to show when detaching is unavailable.
+     */
+    detach(): Promise<true | string | undefined>;
+    gracefulStop(sessionFile: string | null): Promise<void>;
+    dispose(): void;
+}

package/dist/app/session-shell/resident-tab-coordinator.js

@@ -0,0 +1,77 @@
+/**
+ * The session presenter's side of a resident tab: recovered input, the idle status it reports to
+ * the strip, prompt admission and correlation through the recovery journal, draft checkpoints,
+ * detach on quit, and the graceful stop when the presenter is released. Outside a resident tab
+ * every operation is a no-op.
+ */
+export class ResidentTabCoordinator {
+    #options;
+    #ports;
+    constructor(options, ports) {
+        this.#options = options;
+        this.#ports = ports;
+    }
+    /** True inside a resident tab, where Settings and the session name live in the global strip. */
+    get active() {
+        return this.#options !== undefined;
+    }
+    checkpoint(text) {
+        this.#options?.checkpoint?.(text);
+    }
+    closeOwnedRoute(route) {
+        this.#options?.closeOwnedRoute?.(route);
+    }
+    /** Puts the prompts and draft a previous tab process left unfinished back into the editor. */
+    restoreInput(imageSidecar) {
+        const recovered = this.#options?.recovered;
+        if (recovered === undefined)
+            return;
+        const { root } = this.#ports;
+        const prompts = recovered.prompts
+            .map(prompt => root.rehydrateHistoryText(prompt.text, id => imageSidecar?.readAttachment(id) ?? null))
+            .filter(Boolean);
+        if (prompts.length > 0) {
+            root.editor.setText(prompts[0]);
+            if (recovered.draft)
+                root.editor.addToHistory(recovered.draft);
+            for (const additional of prompts.slice(1))
+                root.editor.addToHistory(additional);
+            root.appendWorkflowStatus(recovered.draft
+                ? `Recovered an unfinished prompt; the prior draft and ${Math.max(0, prompts.length - 1)} additional prompt${prompts.length === 2 ? "" : "s"} are in editor history.`
+                : `Recovered an unfinished prompt${prompts.length > 1 ? `; ${prompts.length - 1} additional prompts are in editor history` : ""}.`);
+        }
+        else if (recovered.draft) {
+            root.editor.setText(recovered.draft);
+            root.appendWorkflowStatus("Recovered the editor draft from the previous tab process.");
+        }
+    }
+    /** Reports idle to the strip whenever the session leaves its busy lifecycle. */
+    observeLifecycle(event) {
+        if (event.type === "session-lifecycle" && event.lifecycle !== "busy")
+            this.#options?.reportStatus?.("idle");
+    }
+    /** Journals a prompt before it is sent; undefined outside a resident tab. Rejects when the journal cannot sync. */
+    admit(input) {
+        return this.#options?.admit?.(input) ?? Promise.resolve(undefined);
+    }
+    /** The admitted prompt reached the engine; its journal entry is correlated with the engine's entry. */
+    async dispatched(submissionId, entryId) {
+        this.#options?.dispatched?.();
+        await this.#options?.correlated?.(submissionId, entryId).catch(() => undefined);
+    }
+    /**
+     * Leaves the tab without stopping its engine. Returns undefined outside a resident tab, true when
+     * the client detached, or the notice to show when detaching is unavailable.
+     */
+    async detach() {
+        const resident = this.#options;
+        if (resident === undefined)
+            return undefined;
+        const detached = await resident.requestDetach().catch(() => false);
+        return detached ? true : resident.unavailableNotice ?? "Press Ctrl+C twice to leave; this agent keeps running.";
+    }
+    gracefulStop(sessionFile) {
+        return this.#options?.gracefulStop?.(sessionFile) ?? Promise.resolve();
+    }
+    dispose() { }
+}

package/dist/app/session-shell/response-copy-helper.js

@@ -1,5 +1,6 @@
 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";
+const NATIVE_RETRY_DELAYS_MS = [20, 60];
 // Security: this isolated executor never inherits the UI terminal and never logs clipboard contents.
 let header;
 let fragments = [];
@@ -24,6 +25,14 @@ function nextOutput() {
     send({ kind: "data", text });
 }
 function send(message) { process.send?.(message); }
+function transientClipboardError(error) {
+    const code = typeof error === "object" && error !== null && "code" in error ? String(error.code) : "";
+    const message = error instanceof Error ? error.message : String(error);
+    return /^(?:EAGAIN|EBUSY)$/iu.test(code) || /(?:busy|locked|contention|temporar|try again)/iu.test(message);
+}
+function delay(milliseconds) {
+    return new Promise(resolve => setTimeout(resolve, milliseconds));
+}
 function finish(result, control) {
     if (finished)
         return;
@@ -97,13 +106,19 @@ async function receive(message) {
             return;
         }
         send({ kind: "phase", phase: "submitting", bytes });
-        try {
-            await native.setText(text);
-            finish({ outcome: "delivered" });
-        }
-        catch {
-            finish({ outcome: "failed", failure: "denied" });
+        for (let attempt = 0; attempt <= NATIVE_RETRY_DELAYS_MS.length; attempt++) {
+            try {
+                await native.setText(text);
+                finish({ outcome: "delivered" });
+                return;
+            }
+            catch (error) {
+                if (!transientClipboardError(error) || attempt === NATIVE_RETRY_DELAYS_MS.length)
+                    break;
+                await delay(NATIVE_RETRY_DELAYS_MS[attempt]);
+            }
         }
+        finish({ outcome: "failed", failure: "denied" });
         return;
     }
     else

package/dist/app/session-shell/response-copy-protocol.d.ts

@@ -19,7 +19,7 @@ export interface ResponseCopyEvent {
     readonly pending: number;
     readonly sourceUnits: number;
     readonly bytes?: number;
-    readonly transport?: "native" | "terminal" | "injected";
+    readonly transport?: "native" | "terminal" | "platform" | "injected";
     readonly outcome?: CopyOutcome;
 }
 /** One request per helper lifetime. Each source fragment is acknowledged before the next is sent. */

package/dist/app/session-shell/response-copy-transport.d.ts

@@ -7,7 +7,7 @@ export interface ResponseCopyJob {
     readonly stopped: Promise<void>;
     cancel(): void;
 }
-export type CopyPhaseObserver = (phase: "extracted" | "encoded" | "submitting", bytes: number, transport: "native" | "terminal" | "injected") => void;
+export type CopyPhaseObserver = (phase: "extracted" | "encoded" | "submitting", bytes: number, transport: "native" | "terminal" | "platform" | "injected") => void;
 export type ResponseCopyExecutor = (snapshot: SelectionCopySnapshot, phase: CopyPhaseObserver) => ResponseCopyJob;
 /** The production executor also holds a spare helper; the owner warms it at start and disposes it at shutdown unless the pool is shared. */
 export interface OwnedResponseCopyExecutor extends ResponseCopyExecutor {
@@ -22,17 +22,27 @@ export interface ResponseCopyTerminal {
 }
 /** Never substitute a remote host's native clipboard for the terminal user's clipboard. */
 export declare function responseCopyDestination(env: NodeJS.ProcessEnv): "native" | "terminal";
-/** Node documents synchronous POSIX TTY and Windows pipe writes; do not put clipboard traffic there. */
-export declare function hasAsyncClipboardOutput(platform?: NodeJS.Platform, stdout?: {
-    readonly isTTY?: boolean | undefined;
-    readonly fd?: number | undefined;
-}): boolean;
+/**
+ * Spawn options for one operating-system clipboard writer.
+ * Platform: on POSIX the writer is detached into its own process group, as pinned Pi 1.4 does, so a writer
+ * that daemonizes to keep serving the clipboard is not stopped when Ctrl+Z sends SIGTSTP to the shell's group.
+ */
+export declare function platformClipboardWriteOptions(signal: AbortSignal, platform?: NodeJS.Platform): {
+    signal: AbortSignal;
+    windowsHide: boolean;
+    timeout: number;
+    killSignal: "SIGKILL";
+    maxBuffer: number;
+    detached: boolean;
+};
 /** Isolates preparation and native clipboard access; only the owner may submit terminal controls. */
 export declare function createResponseCopyExecutor(options?: {
     readonly terminal?: ResponseCopyTerminal;
     readonly destination?: "native" | "terminal";
     /** Explicit host seam: must be non-blocking and honor cancellation, or its unresolved lifetime is quarantined. */
     readonly writeText?: (text: string, signal: AbortSignal) => Promise<void>;
+    /** Platform/fault-test seam; production writes through the supported operating-system command. */
+    readonly platformWriteText?: (text: string, signal: AbortSignal) => Promise<boolean>;
     /** Package/fault-test seam: the production helper is always an emitted sibling. */
     readonly helper?: URL;
     /** Idle bound for the spare helper; production keeps the default. */

package/dist/app/session-shell/response-copy-transport.js

@@ -1,25 +1,67 @@
-import { fork } from "node:child_process";
-import { fstatSync } from "node:fs";
+import { execFile, fork } from "node:child_process";
 import { HelperPool } from "./helper-pool.js";
+import { PRODUCT_IDENTITY } from "../../product-identity.js";
 import { COPY_CHUNK_UNITS, COPY_CLEANUP_MS, MAX_COPY_BYTES, MAX_COPY_CONTROL_BYTES } from "./response-copy-protocol.js";
+const PLATFORM_WRITE_TIMEOUT_MS = 1_500;
 /** Never substitute a remote host's native clipboard for the terminal user's clipboard. */
 export function responseCopyDestination(env) {
-    return env.SSH_CONNECTION || env.SSH_CLIENT || env.SSH_TTY || env.TMUX || env.STY || env.WSL_DISTRO_NAME
+    return env[PRODUCT_IDENTITY.environment.tabId] || env.SSH_CONNECTION || env.SSH_CLIENT || env.SSH_TTY || env.TMUX || env.STY || env.WSL_DISTRO_NAME
         ? "terminal" : "native";
 }
-/** Node documents synchronous POSIX TTY and Windows pipe writes; do not put clipboard traffic there. */
-export function hasAsyncClipboardOutput(platform = process.platform, stdout = process.stdout) {
-    if (stdout.isTTY)
-        return platform === "win32";
-    if (platform === "win32")
-        return false;
-    try {
-        const stat = fstatSync(stdout.fd ?? -1);
-        return stat.isFIFO() || stat.isSocket();
-    }
-    catch {
-        return false;
+function platformClipboardCommands() {
+    if (process.platform === "win32")
+        return [{
+                command: "powershell.exe",
+                args: ["-NoLogo", "-NoProfile", "-NonInteractive", "-Command", "$value=[Console]::In.ReadToEnd(); Set-Clipboard -Value $value"],
+            }];
+    if (process.platform === "darwin")
+        return [{ command: "pbcopy", args: [] }];
+    return [
+        { command: "wl-copy", args: ["--type", "text/plain;charset=utf-8"] },
+        { command: "xclip", args: ["-selection", "clipboard", "-in"] },
+    ];
+}
+/**
+ * Spawn options for one operating-system clipboard writer.
+ * Platform: on POSIX the writer is detached into its own process group, as pinned Pi 1.4 does, so a writer
+ * that daemonizes to keep serving the clipboard is not stopped when Ctrl+Z sends SIGTSTP to the shell's group.
+ */
+export function platformClipboardWriteOptions(signal, platform = process.platform) {
+    return {
+        signal,
+        windowsHide: true,
+        timeout: PLATFORM_WRITE_TIMEOUT_MS,
+        killSignal: "SIGKILL",
+        maxBuffer: 1_024,
+        detached: platform !== "win32",
+    };
+}
+async function writePlatformClipboardText(text, signal) {
+    for (const route of platformClipboardCommands()) {
+        if (signal.aborted)
+            return false;
+        const delivered = await new Promise(resolve => {
+            let settled = false;
+            const done = (value) => {
+                if (settled)
+                    return;
+                settled = true;
+                resolve(value);
+            };
+            const child = execFile(route.command, [...route.args], platformClipboardWriteOptions(signal), error => done(error === null));
+            child.once("error", () => done(false));
+            if (child.stdin === null) {
+                child.kill("SIGKILL");
+                done(false);
+                return;
+            }
+            child.stdin.once("error", () => { child.kill("SIGKILL"); done(false); });
+            child.stdin.end(text);
+        });
+        if (delivered)
+            return true;
     }
+    return false;
 }
 /** Isolates preparation and native clipboard access; only the owner may submit terminal controls. */
 export function createResponseCopyExecutor(options = {}) {
@@ -43,8 +85,18 @@ export function createResponseCopyExecutor(options = {}) {
             };
             let outcome = await execute(destination);
             // Concurrency: helper results settle only after exit; fallback cannot race an older native write.
-            if (!controller.signal.aborted && destination === "native" && outcome.result.failure === "unavailable" && options.terminal !== undefined) {
-                outcome = await execute("terminal");
+            if (!controller.signal.aborted && destination === "native" && outcome.result.outcome === "failed") {
+                const prepared = await execute("prepare");
+                if (prepared.result.outcome === "delivered" && prepared.text !== undefined) {
+                    phase("submitting", prepared.bytes ?? 0, "platform");
+                    const delivered = await (options.platformWriteText ?? writePlatformClipboardText)(prepared.text, controller.signal);
+                    outcome = { kind: "result", result: delivered ? { outcome: "delivered" } : { outcome: "failed", failure: "unavailable" } };
+                }
+                else
+                    outcome = { kind: "result", result: { outcome: "failed", failure: "transport" } };
+                if (!controller.signal.aborted && outcome.result.outcome === "failed" && options.terminal !== undefined) {
+                    outcome = await execute("terminal");
+                }
             }
             if (controller.signal.aborted)
                 return { outcome: "canceled" };

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

@@ -0,0 +1,22 @@
+/**
+ * One piece of a session presenter's state that resets itself when the backend replaces the
+ * session and releases itself when the presenter is released.
+ */
+export interface SessionConcern {
+    /** The backend replaced the session: drop the pending work, timers, and surfaces that belonged to it. */
+    onSessionReplaced?(): void;
+    /** Release everything this concern holds; called at most once. */
+    dispose?(): void;
+}
+/**
+ * The presenter's concerns in their declared order. Session replacement and disposal fan out in
+ * that order, because later resets depend on earlier ones (copy intent before pastes before the
+ * input surface), and disposal is idempotent.
+ */
+export declare class SessionConcerns {
+    #private;
+    constructor(concerns: readonly SessionConcern[]);
+    replaceSession(): void;
+    /** Disposes each concern once, through `attempt` so one failure does not skip the rest. */
+    dispose(attempt?: (action: () => void) => void): void;
+}

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

@@ -0,0 +1,29 @@
+/**
+ * The presenter's concerns in their declared order. Session replacement and disposal fan out in
+ * that order, because later resets depend on earlier ones (copy intent before pastes before the
+ * input surface), and disposal is idempotent.
+ */
+export class SessionConcerns {
+    #concerns;
+    #disposed = false;
+    constructor(concerns) {
+        this.#concerns = concerns;
+    }
+    replaceSession() {
+        if (this.#disposed)
+            return;
+        for (const concern of this.#concerns)
+            concern.onSessionReplaced?.();
+    }
+    /** Disposes each concern once, through `attempt` so one failure does not skip the rest. */
+    dispose(attempt = action => action()) {
+        if (this.#disposed)
+            return;
+        this.#disposed = true;
+        for (const concern of this.#concerns) {
+            const dispose = concern.dispose;
+            if (dispose !== undefined)
+                attempt(() => dispose.call(concern));
+        }
+    }
+}