@timurproko/a1 0.1.8-dev.368 → 0.1.8-dev.402

package/dist/integrations/pi/session-ui/response-copy-coordinator.js

@@ -0,0 +1,189 @@
+import { MAX_COPY_SOURCE_UNITS } from "../../../ui/components/index.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;
+    #pending;
+    #latest = Promise.resolve({ outcome: "delivered" });
+    #latestPending = false;
+    #disposed = false;
+    #quarantined = false;
+    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. */
+    submitText(text) {
+        return this.submit(Object.freeze({
+            literal: true, revision: 0, sourceUnits: text.length,
+            selection: Object.freeze({ start: Object.freeze({ line: 0, column: 0 }), end: Object.freeze({ line: 0, column: Number.MAX_SAFE_INTEGER }) }),
+            rows: Object.freeze(text.length > MAX_COPY_SOURCE_UNITS ? [] : [Object.freeze({ text })]),
+            ...(text.length > MAX_COPY_SOURCE_UNITS ? { rejected: "size" } : {}),
+        }));
+    }
+    /** Admission is synchronous, but preparation/startup never runs in the input handler's stack. */
+    submit(snapshot, before = Promise.resolve()) {
+        const id = ++this.#sequence;
+        const admitted = this.#now() - (snapshot.captureMs ?? 0);
+        let resolve;
+        const result = new Promise(done => { resolve = done; });
+        this.#latest = result;
+        this.#latestPending = true;
+        const request = {
+            id, epoch: this.#epoch, admitted, sourceUnits: snapshot.sourceUnits, snapshot, before, resolve, done: false, submitting: false,
+            timer: setTimeout(() => this.#cancel(request, { outcome: "timed-out" }), Math.max(0, COPY_DEADLINE_MS - (snapshot.captureMs ?? 0))),
+        };
+        request.timer.unref?.();
+        this.#trace(request, "capture", { elapsedMs: snapshot.captureMs ?? 0 });
+        if (snapshot.literal !== true)
+            this.#trace(request, "selection-clear");
+        if (this.#disposed || this.#quarantined || snapshot.rejected) {
+            this.#settle(request, { outcome: this.#disposed ? "canceled" : "failed", failure: snapshot.rejected ? "size" : "unsafe" });
+            return result;
+        }
+        if (this.#pending)
+            this.#cancel(this.#pending, { outcome: "superseded" });
+        this.#pending = request;
+        if (this.#active && !this.#active.submitting)
+            this.#cancel(this.#active, { outcome: "superseded" });
+        this.#trace(request, "queued");
+        this.#drain();
+        return result;
+    }
+    /** Capture the current copy barrier, without making later copies retroactively delay this paste. */
+    canPaste(signal) { return this.capturePasteBarrier()(signal); }
+    /** Only a pending write is a prerequisite; a completed failure cannot poison independent future reads. */
+    capturePasteBarrier() {
+        const latest = this.#latestPending ? this.#latest : undefined;
+        return async (signal) => {
+            if (signal.aborted)
+                return false;
+            if (latest === undefined)
+                return true;
+            return new Promise(resolve => {
+                const abort = () => resolve(false);
+                signal.addEventListener("abort", abort, { once: true });
+                void latest.then(result => {
+                    signal.removeEventListener("abort", abort);
+                    resolve(!signal.aborted && (result.outcome === "delivered" || result.outcome === "submitted-unverified"));
+                });
+            });
+        };
+    }
+    /** Session replacement fences the old executor rather than discarding its live side effects. */
+    reset() {
+        this.#epoch++;
+        if (this.#pending)
+            this.#cancel(this.#pending, { outcome: "canceled" });
+        if (this.#active)
+            this.#cancel(this.#active, { outcome: "canceled" });
+        this.#latestPending = false;
+        this.#latest = Promise.resolve({ outcome: "delivered" });
+    }
+    dispose() { this.#disposed = true; this.reset(); }
+    #drain() {
+        if (this.#active || this.#disposed || this.#quarantined)
+            return;
+        const request = this.#pending;
+        this.#pending = undefined;
+        if (!request || request.done)
+            return;
+        this.#active = request;
+        // Concurrency: render and input get an event-loop turn before child startup or source transfer.
+        setImmediate(() => {
+            if (request.done) {
+                this.#release(request);
+                return;
+            }
+            let canceled = false;
+            let executor;
+            const run = request.before.then(async () => {
+                if (canceled || request.done || request.snapshot === undefined)
+                    return { outcome: "canceled" };
+                this.#trace(request, "preparing");
+                executor = this.options.execute(request.snapshot, (phase, bytes, transport) => {
+                    if (request.done)
+                        return;
+                    if (phase === "submitting")
+                        request.submitting = true;
+                    this.#trace(request, phase, { bytes, transport });
+                });
+                return executor.result;
+            }).catch(() => ({ outcome: "failed", failure: "transport" }));
+            // Concurrency: a canceled gate has not started any side effect. Do not wait for an unrelated prior prompt indefinitely.
+            let cancelGate;
+            const gateStopped = new Promise(resolve => { cancelGate = resolve; });
+            const stopped = Promise.race([
+                run.then(async () => { await executor?.stopped; }), gateStopped,
+            ]);
+            request.job = { result: run, stopped, cancel: () => {
+                    canceled = true;
+                    if (executor)
+                        executor.cancel();
+                    else
+                        cancelGate();
+                } };
+            void run.then(result => this.#settle(request, result));
+            void stopped.then(() => this.#release(request));
+        });
+    }
+    #cancel(request, result) {
+        if (request.done)
+            return;
+        this.#settle(request, result);
+        request.job?.cancel();
+        if (this.#pending === request)
+            this.#pending = undefined;
+        if (this.#active === request && request.job) {
+            const cleanup = setTimeout(() => {
+                if (this.#active !== request)
+                    return;
+                this.#quarantined = true;
+                this.#trace(request, "cleanup");
+                if (this.#pending)
+                    this.#cancel(this.#pending, { outcome: "failed", failure: "unsafe" });
+            }, COPY_CLEANUP_MS);
+            cleanup.unref?.();
+            void request.job.stopped.then(() => clearTimeout(cleanup));
+        }
+    }
+    #settle(request, result) {
+        if (request.done)
+            return;
+        request.done = true;
+        if (request.id === this.#sequence)
+            this.#latestPending = false;
+        request.snapshot = undefined;
+        clearTimeout(request.timer);
+        this.#trace(request, "settled", { outcome: result.outcome });
+        request.resolve(result);
+        if (!this.#disposed && request.epoch === this.#epoch && request.id === this.#sequence
+            && (result.outcome === "failed" || result.outcome === "timed-out")) {
+            this.options.onFailure?.(result);
+        }
+    }
+    #release(request) {
+        if (this.#active !== request)
+            return;
+        this.#active = undefined;
+        this.#quarantined = false;
+        this.#trace(request, "cleanup");
+        this.#drain();
+    }
+    #now() { return this.options.now?.() ?? performance.now(); }
+    #trace(request, phase, extra = {}) {
+        if (this.options.onEvent === undefined)
+            return;
+        const atMs = this.#now();
+        // Security: observations contain only bounded scalar metadata, never copied source or encoded content.
+        try {
+            this.options.onEvent({ request: request.id, phase, atMs, elapsedMs: atMs - request.admitted,
+                sourceUnits: request.sourceUnits, pending: Number(this.#active !== undefined) + Number(this.#pending !== undefined), ...extra });
+        }
+        catch { /* Invariant: diagnostics must not alter copy semantics. */ }
+    }
+}

package/dist/integrations/pi/session-ui/response-copy-helper.d.ts

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

package/dist/integrations/pi/session-ui/response-copy-helper.js

@@ -0,0 +1,122 @@
+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;
+let fragments = [];
+let parts = [];
+let rowIndex = 0, sourceUnits = 0, bytes = 0;
+let finished = false;
+let output;
+let outputOffset = 0;
+function nextOutput() {
+    if (output === undefined)
+        throw new Error("protocol");
+    if (outputOffset === output.length) {
+        output = undefined;
+        finish({ outcome: "delivered" });
+        return;
+    }
+    let end = Math.min(output.length, outputOffset + COPY_CHUNK_UNITS);
+    if (end < output.length && /[\uD800-\uDBFF]/u.test(output[end - 1]) && /[\uDC00-\uDFFF]/u.test(output[end]))
+        end--;
+    const text = output.slice(outputOffset, end);
+    outputOffset = end;
+    send({ kind: "data", text });
+}
+function send(message) { process.send?.(message); }
+function finish(result, control) {
+    if (finished)
+        return;
+    finished = true;
+    fragments = [];
+    parts = [];
+    process.send?.({ kind: "result", result, ...(control === undefined ? {} : { control }) }, () => process.exit(0));
+}
+async function receive(message) {
+    if (finished)
+        return;
+    if (message?.kind === "next" && header?.mode === "prepare") {
+        nextOutput();
+        return;
+    }
+    if (message?.kind === "begin" && header === undefined) {
+        if (!Number.isSafeInteger(message.rows) || message.rows < 1 || message.rows > MAX_COPY_ROWS
+            || !["native", "terminal", "prepare"].includes(message.mode))
+            throw new Error("protocol");
+        header = message;
+    }
+    else if (message?.kind === "row" && header !== undefined) {
+        if (typeof message.text !== "string" || message.text.length > COPY_CHUNK_UNITS || rowIndex >= header.rows)
+            throw new Error("protocol");
+        sourceUnits += message.text.length;
+        if (sourceUnits > MAX_COPY_SOURCE_UNITS) {
+            finish({ outcome: "failed", failure: "size" });
+            return;
+        }
+        fragments.push(message.text);
+        if (message.end) {
+            const text = selectionCopyRowText(header, { text: fragments.join(""), ...(message.prompt === undefined ? {} : { prompt: message.prompt }) }, rowIndex);
+            fragments = [];
+            bytes += Buffer.byteLength(text, "utf8") + (rowIndex === 0 ? 0 : 1);
+            if (bytes > MAX_COPY_BYTES) {
+                finish({ outcome: "failed", failure: "size" });
+                return;
+            }
+            parts.push(text);
+            rowIndex++;
+        }
+    }
+    else if (message?.kind === "finish" && header !== undefined && rowIndex === header.rows && fragments.length === 0) {
+        send({ kind: "phase", phase: "extracted", bytes });
+        const text = parts.join("\n");
+        parts = [];
+        if (text.length === 0) {
+            finish({ outcome: "failed", failure: "size" });
+            return;
+        }
+        if (header.mode === "prepare") {
+            // Protocol: this success acknowledges prepared IPC only; the owner must still await its injected writer.
+            output = text;
+            nextOutput();
+            return;
+        }
+        if (header.mode === "terminal") {
+            const limit = Math.min(MAX_COPY_CONTROL_BYTES, header.controlLimit);
+            if (!Number.isSafeInteger(limit) || limit < 8 || 8 + 4 * Math.ceil(bytes / 3) > limit) {
+                finish({ outcome: "failed", failure: "size" });
+                return;
+            }
+            const control = `\u001b]52;c;${Buffer.from(text, "utf8").toString("base64")}\u0007`;
+            send({ kind: "phase", phase: "encoded", bytes });
+            finish({ outcome: "submitted-unverified" }, control);
+            return;
+        }
+        // Platform: even an async native binding may block internally; the parent can terminate this process.
+        let native;
+        try {
+            native = await import("@mariozechner/clipboard");
+        }
+        catch {
+            finish({ outcome: "failed", failure: "unavailable" });
+            return;
+        }
+        send({ kind: "phase", phase: "submitting", bytes });
+        try {
+            await native.setText(text);
+            finish({ outcome: "delivered" });
+        }
+        catch {
+            finish({ outcome: "failed", failure: "denied" });
+        }
+        return;
+    }
+    else
+        throw new Error("protocol");
+    send({ kind: "ready" });
+}
+process.on("message", message => {
+    void receive(message).catch(() => finish({ outcome: "failed", failure: "transport" }));
+});
+// Concurrency: a vanished owner must never leave a clipboard worker alive.
+process.on("disconnect", () => process.exit(0));
+send({ kind: "ready" });

package/dist/integrations/pi/session-ui/response-copy-protocol.d.ts

@@ -0,0 +1,56 @@
+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;
+export declare const MAX_COPY_CONTROL_BYTES: number;
+export declare const COPY_CHUNK_UNITS = 16384;
+export type CopyOutcome = "delivered" | "submitted-unverified" | "failed" | "timed-out" | "superseded" | "canceled";
+export type CopyFailure = "size" | "unavailable" | "denied" | "transport" | "unsafe";
+export interface CopyResult {
+    readonly outcome: CopyOutcome;
+    readonly failure?: CopyFailure;
+}
+/** Payload-free observations; callers must not attach transcript/clipboard content. */
+export interface ResponseCopyEvent {
+    readonly request: number;
+    readonly phase: "capture" | "selection-clear" | "queued" | "preparing" | "extracted" | "encoded" | "submitting" | "settled" | "cleanup";
+    readonly atMs: number;
+    readonly elapsedMs: number;
+    readonly pending: number;
+    readonly sourceUnits: number;
+    readonly bytes?: number;
+    readonly transport?: "native" | "terminal" | "injected";
+    readonly outcome?: CopyOutcome;
+}
+/** One request per helper lifetime. Each source fragment is acknowledged before the next is sent. */
+export type CopyHelperInput = {
+    readonly kind: "begin";
+    readonly selection: OrderedTextSelection;
+    readonly rows: number;
+    readonly mode: "native" | "terminal" | "prepare";
+    readonly literal?: boolean;
+    readonly controlLimit: number;
+} | {
+    readonly kind: "row";
+    readonly text: string;
+    readonly end: boolean;
+    readonly prompt?: Exclude<SelectionCopyPrompt, undefined>;
+} | {
+    readonly kind: "finish";
+} | {
+    readonly kind: "next";
+};
+export type CopyHelperOutput = {
+    readonly kind: "ready";
+} | {
+    readonly kind: "data";
+    readonly text: string;
+} | {
+    readonly kind: "phase";
+    readonly phase: "extracted" | "encoded" | "submitting";
+    readonly bytes: number;
+} | {
+    readonly kind: "result";
+    readonly result: CopyResult;
+    readonly control?: string;
+};

package/dist/integrations/pi/session-ui/response-copy-protocol.js

@@ -0,0 +1,5 @@
+export const COPY_DEADLINE_MS = 5_000;
+export const COPY_CLEANUP_MS = 250;
+export const MAX_COPY_BYTES = 16 * 1024 * 1024;
+export const MAX_COPY_CONTROL_BYTES = 64 * 1024;
+export const COPY_CHUNK_UNITS = 16_384;

package/dist/integrations/pi/session-ui/response-copy-transport.d.ts

@@ -0,0 +1,31 @@
+import type { SelectionCopySnapshot } from "../../../ui/components/index.js";
+import { type CopyResult } from "./response-copy-protocol.js";
+export interface ResponseCopyJob {
+    readonly result: Promise<CopyResult>;
+    /** Resolves only after the executor can no longer produce clipboard side effects. */
+    readonly stopped: Promise<void>;
+    cancel(): void;
+}
+export type CopyPhaseObserver = (phase: "extracted" | "encoded" | "submitting", bytes: number, transport: "native" | "terminal" | "injected") => void;
+export type ResponseCopyExecutor = (snapshot: SelectionCopySnapshot, phase: CopyPhaseObserver) => ResponseCopyJob;
+export interface ResponseCopyTerminal {
+    readonly maxBytes?: number;
+    /** A supported non-blocking submission boundary, not clipboard acknowledgment. */
+    submit(control: string, signal: AbortSignal): Promise<void>;
+}
+/** 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;
+/** 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>;
+    /** Package/fault-test seam: the production helper is always an emitted sibling. */
+    readonly helper?: URL;
+}): ResponseCopyExecutor;

package/dist/integrations/pi/session-ui/response-copy-transport.js

@@ -0,0 +1,187 @@
+import { fork } from "node:child_process";
+import { fstatSync } from "node:fs";
+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) {
+    return 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;
+    }
+}
+/** Isolates preparation and native clipboard access; only the owner may submit terminal controls. */
+export function createResponseCopyExecutor(options = {}) {
+    return (snapshot, phase) => {
+        const controller = new AbortController();
+        let active;
+        const run = async () => {
+            const destination = options.writeText === undefined ? options.destination ?? responseCopyDestination(process.env) : "prepare";
+            const execute = async (mode) => {
+                if (controller.signal.aborted)
+                    return { kind: "result", result: { outcome: "canceled" } };
+                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);
+                if (controller.signal.aborted)
+                    active.cancel();
+                return active.result;
+            };
+            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)
+                return { outcome: "canceled" };
+            if (destination === "prepare" && outcome.result.outcome === "delivered") {
+                if (outcome.text === undefined)
+                    return { outcome: "failed", failure: "transport" };
+                phase("submitting", outcome.bytes ?? 0, "injected");
+                await options.writeText(outcome.text, controller.signal);
+            }
+            if (outcome.result.outcome === "submitted-unverified") {
+                const control = "control" in outcome ? outcome.control : undefined;
+                if (typeof control !== "string" || !/^\u001b\]52;c;[A-Za-z0-9+/]*={0,2}\u0007$/u.test(control)
+                    || Buffer.byteLength(control) > Math.min(MAX_COPY_CONTROL_BYTES, options.terminal === undefined ? 0 : options.terminal.maxBytes ?? MAX_COPY_CONTROL_BYTES)) {
+                    return { outcome: "failed", failure: "transport" };
+                }
+                phase("submitting", control.length, "terminal");
+                await options.terminal.submit(control, controller.signal);
+            }
+            return controller.signal.aborted ? { outcome: "canceled" } : outcome.result;
+        };
+        const result = run().catch(() => ({ outcome: controller.signal.aborted ? "canceled" : "failed", failure: "transport" }));
+        return { result, stopped: result.then(() => { }), cancel: () => { controller.abort(); active?.cancel(); } };
+    };
+}
+function* sourceMessages(snapshot, mode, controlLimit) {
+    yield { kind: "begin", selection: snapshot.selection, rows: snapshot.rows.length, mode, controlLimit,
+        ...(snapshot.literal === undefined ? {} : { literal: snapshot.literal }) };
+    for (const row of snapshot.rows) {
+        for (let offset = 0; offset < Math.max(1, row.text.length); offset += COPY_CHUNK_UNITS) {
+            yield { kind: "row", text: row.text.slice(offset, offset + COPY_CHUNK_UNITS), end: offset + COPY_CHUNK_UNITS >= row.text.length,
+                ...(row.prompt === undefined ? {} : { prompt: row.prompt }) };
+        }
+    }
+    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);
+    let iterator = sourceMessages(snapshot, mode, controlLimit);
+    let outcome;
+    let stopping = false;
+    let prepared = [], preparedBytes = 0, expectedBytes;
+    const observedPhases = new Set();
+    let cleanup;
+    const cancel = () => {
+        if (stopping)
+            return;
+        stopping = true;
+        prepared = [];
+        iterator = undefined;
+        child.kill("SIGKILL");
+        // Concurrency: a kernel-stuck child is quarantined by the coordinator, not allowed to pin UI shutdown.
+        cleanup = setTimeout(() => { child.unref(); child.channel?.unref(); }, COPY_CLEANUP_MS);
+        cleanup.unref();
+    };
+    const result = new Promise(resolve => {
+        let settled = false;
+        const settle = () => {
+            if (settled)
+                return;
+            settled = true;
+            const value = outcome ?? { kind: "result", result: { outcome: "failed", failure: "transport" } };
+            if (mode === "prepare" && value.result.outcome === "delivered") {
+                resolve(expectedBytes === preparedBytes ? { ...value, text: prepared.join(""), bytes: preparedBytes }
+                    : { kind: "result", result: { outcome: "failed", failure: "transport" } });
+            }
+            else
+                resolve(value);
+            prepared = [];
+        };
+        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(); });
+            }
+            else if (message?.kind === "data") {
+                if (mode !== "prepare" || expectedBytes === undefined || typeof message.text !== "string" || message.text.length > COPY_CHUNK_UNITS) {
+                    cancel();
+                    return;
+                }
+                preparedBytes += Buffer.byteLength(message.text);
+                if (preparedBytes > MAX_COPY_BYTES) {
+                    cancel();
+                    return;
+                }
+                prepared.push(message.text);
+                child.send({ kind: "next" }, error => { if (error)
+                    cancel(); });
+            }
+            else if (message?.kind === "phase" && ["extracted", "encoded", "submitting"].includes(message.phase)
+                && Number.isSafeInteger(message.bytes) && message.bytes >= 0) {
+                if (observedPhases.has(message.phase)) {
+                    cancel();
+                    return;
+                }
+                observedPhases.add(message.phase);
+                if (message.phase === "extracted")
+                    expectedBytes = message.bytes;
+                phase(message.phase, message.bytes, mode === "prepare" ? "injected" : mode);
+            }
+            else if (message?.kind === "result" && ["delivered", "submitted-unverified", "failed"].includes(message.result?.outcome)) {
+                outcome = message;
+                iterator = undefined;
+                // Concurrency: a result is not an exit fence. Bound a malformed helper that sends a result but never exits.
+                cleanup = setTimeout(cancel, COPY_CLEANUP_MS);
+                cleanup.unref();
+            }
+            else
+                cancel();
+        });
+        child.once("error", cancel);
+        child.once("exit", () => {
+            iterator = undefined;
+            if (cleanup !== undefined)
+                clearTimeout(cleanup);
+            child.removeAllListeners("message");
+            settle();
+        });
+        // Platform: spawn failure has no exit event, but has a close event and no live executor to fence.
+        child.once("close", () => {
+            iterator = undefined;
+            if (cleanup !== undefined)
+                clearTimeout(cleanup);
+            settle();
+        });
+    });
+    return { result, cancel };
+}

package/dist/integrations/pi/session-ui/session-shell-root.d.ts

@@ -6,6 +6,10 @@ import { type PiEngineAdapter, type PiWorkflowMessage, type PiWorkflowResult } f
 import { type PiShellClipboardContent, type PiShellComponentPort, type PiShellEditorPort, type PiShellExtensionRendererResolver, type PiShellHeaderOptions, type PiShellHeaderPort, type PiShellImageAssetResolver, type PiShellLoadedResourcesPort, type PiShellResourceEntry, type PiShellTranscriptComponentPort } from "../components/index.js";
 import { type PiTuiComponentPort, type PiTuiInputSurfaceKind, type PiTuiInputCoordinationScheduler, type PiTuiInputDiagnosticsEvent, type PiTuiLayoutNode, type PiTuiTerminalPort } from "../tui-runtime/index.js";
 import { type PreparedPrompt } from "./prompt-chips.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";
+import type { PasteEvent, PasteSource } from "./paste-protocol.js";
 import type { StreamPresentationScheduler } from "./stream-presentation-coalescer.js";
 export type OwnedUiBackendPort = PiEngineAdapter;
 export type OwnedUiTerminalPort = PiTuiTerminalPort;
@@ -16,7 +20,7 @@ export interface OwnedUiClipboardPort {
         readonly data: string;
         readonly mimeType: string;
     } | null>;
-    writeText?(text: string): Promise<void>;
+    writeText?(text: string, signal?: AbortSignal): Promise<void>;
 }
 export interface OwnedUiSessionShellOptions {
     readonly promptHistory?: {
@@ -43,6 +47,13 @@ export interface OwnedUiSessionShellOptions {
     readonly viewportSettings?: OwnedUiViewportSettingsPort;
     /** 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 intervalMs?: number;
@@ -97,6 +108,8 @@ export declare class OwnedUiSessionShellRoot implements PiTuiComponentPort {
         readonly onInputSurfaceChanged?: () => void;
         readonly onCopyText?: (text: string) => void;
         readonly readClipboardContent?: (signal?: AbortSignal) => Promise<PiShellClipboardContent | null>;
+        readonly captureClipboardPaste?: () => PasteSource;
+        readonly pasteDiagnostics?: (event: PasteEvent) => void;
     }, startup?: PiShellHeaderOptions, agentDir?: string, extensionRenderers?: PiShellExtensionRendererResolver, sessionLayout?: "pinned" | "custom-viewport", imageAssets?: PiShellImageAssetResolver);
     setEditorPaddingX(padding: number): void;
     setAutocompleteMaxVisible(maxVisible: number): void;
@@ -171,11 +184,7 @@ export declare class OwnedUiSessionShellRoot implements PiTuiComponentPort {
     clearViewportPointerState(): void;
     setViewportOverlaySurfaces(surfaces: readonly PiTuiPointerSurface[] | null): void;
     viewportInputGeometryReady(width: number, height: number): boolean;
-    handleViewportPreInput(data: string, allowWheel?: boolean, now?: number, editorActive?: boolean): {
-        readonly data: string;
-        readonly consumed: boolean;
-        readonly copyText?: string;
-    };
+    handleViewportPreInput(data: string, allowWheel?: boolean, now?: number, editorActive?: boolean): SessionViewportInputResult;
     layoutRoot(): PiTuiLayoutNode;
     transcriptComponent(id: string): PiShellTranscriptComponentPort | undefined;
     exitTranscript(width: number): string;