@timurproko/a1 0.1.8-dev.de7821a → 0.2.0

package/bin/update-recovery.js

@@ -0,0 +1,365 @@
+#!/usr/bin/env node
+
+// Security: this file intentionally depends only on Node built-ins: the updater copies it into a
+// transaction capsule before npm is allowed to rename or remove the installed package.
+import { spawn } from "node:child_process";
+import { createHash, randomUUID } from "node:crypto";
+import { chmod, lstat, mkdir, open, readFile, realpath, rename, rm, writeFile } from "node:fs/promises";
+import { basename, 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");
+}
+
+/** @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, {
+    schema: SCHEMA,
+    transactionId: value.transactionId,
+    pid: process.pid,
+    startIdentity: `${process.pid}:${Math.floor(Date.now() - process.uptime() * 1000)}`,
+    startedAt: new Date().toISOString(),
+  });
+  const heartbeat = setInterval(() => {
+    void writeJson(value.ownerPath, {
+      schema: SCHEMA,
+      transactionId: value.transactionId,
+      pid: process.pid,
+      startIdentity: `${process.pid}:${Math.floor(Date.now() - process.uptime() * 1000)}`,
+      heartbeatAt: new Date().toISOString(),
+    });
+  }, 500);
+  heartbeat.unref?.();
+  const child = spawn(process.execPath, [value.npmCli, ...value.npmArguments], {
+    detached: false,
+    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;
+    cancelled = true;
+    child.kill("SIGTERM");
+    forceTimer = setTimeout(() => { forced = true; child.kill("SIGKILL"); }, 2_000);
+    forceTimer.unref?.();
+  }, 50);
+  cancellationPoll.unref?.();
+
+  let npmExitCode = null;
+  let spawnError = null;
+  try {
+    npmExitCode = await new Promise((resolvePromise, rejectPromise) => {
+      child.once("error", rejectPromise);
+      child.once("close", code => resolvePromise(code));
+    });
+  } catch (error) {
+    spawnError = error;
+  } finally {
+    clearInterval(cancellationPoll);
+    clearInterval(heartbeat);
+    if (forceTimer) clearTimeout(forceTimer);
+  }
+
+  const targetReady = await installedTargetIsCallable(value);
+  let launcherDisposition = "unavailable";
+  let outcome = "failed";
+  if (targetReady) {
+    launcherDisposition = "target";
+    outcome = "installed";
+  } else {
+    await writeRecoveryLaunchers(value);
+    if (await recoveryLaunchersAreCallable(value)) {
+      launcherDisposition = "recovery";
+      outcome = "recovery-launcher";
+    }
+  }
+  await writeJson(value.resultPath, {
+    schema: SCHEMA,
+    transactionId: value.transactionId,
+    outcome,
+    npmExitCode,
+    cancelled,
+    launcherDisposition,
+    stdout: bounded(Buffer.concat(stdout).toString("utf8")),
+    stderr: bounded(`${Buffer.concat(stderr).toString("utf8")}${spawnError ? `\n${String(spawnError)}` : ""}${forced ? "\nforced npm termination after cancellation" : ""}`.trim()),
+    completedAt: new Date().toISOString(),
+  });
+  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", capsuleManifestPath], {
+      detached: true,
+      windowsHide: true,
+      stdio: "ignore",
+    });
+    worker.unref();
+    const deadline = Date.now() + 15 * 60 * 1000;
+    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);
+    process.on("SIGTERM", onSigterm);
+    try {
+      while (Date.now() < deadline && !await exists(value.resultPath)) await sleep(50);
+    } finally {
+      process.off("SIGINT", onSigint);
+      process.off("SIGTERM", onSigterm);
+    }
+    entry = await installedTargetEntry(value);
+  }
+  entry ??= resolve(value.priorReleaseRoot, "bin", "cli.js");
+  const child = spawn(process.execPath, [entry, ...arguments_], { stdio: "inherit", windowsHide: false });
+  return await new Promise(resolvePromise => {
+    child.once("error", error => { console.error(error instanceof Error ? error.message : String(error)); resolvePromise(1); });
+    child.once("close", code => resolvePromise(code ?? 1));
+  });
+}
+
+/**
+ * @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.");
+  if (value.schema !== SCHEMA || typeof value.transactionId !== "string" || typeof value.packageName !== "string"
+    || typeof value.packageName !== "string" || !value.packageName.includes("/") || typeof value.targetVersion !== "string" || typeof value.packageRoot !== "string" || typeof value.globalRoot !== "string"
+    || typeof value.launcherRoot !== "string" || !Array.isArray(value.launchers) || typeof value.priorReleaseId !== "string" || typeof value.priorReleaseRoot !== "string"
+    || !/^[a-f0-9]{64}$/.test(value.priorContentDigest) || typeof value.releaseManifestName !== "string"
+    || typeof value.recoveryEntry !== "string" || typeof value.recoveryEntryDigest !== "string" || value.nodeExecutable !== process.execPath || typeof value.npmCli !== "string"
+    || !Array.isArray(value.npmArguments) || typeof value.resultPath !== "string" || typeof value.cancellationPath !== "string") {
+    throw new Error("invalid A1 update recovery capsule");
+  }
+  const lexicalCapsuleRoot = dirname(resolve(path));
+  if (lexicalCapsuleRoot.split(sep).at(-1) !== value.transactionId) throw new Error("A1 update recovery transaction path is invalid");
+  const capsuleRoot = await realpath(lexicalCapsuleRoot);
+  const entry = await realpath(value.recoveryEntry);
+  assertDirectChild(capsuleRoot, entry);
+  if (!samePath(entry, resolve(capsuleRoot, "recovery.js"))) throw new Error("A1 update recovery entry path is invalid");
+  const digest = createHash("sha256").update(await readFile(entry)).digest("hex");
+  if (digest !== value.recoveryEntryDigest) throw new Error("A1 update recovery payload digest mismatch");
+  const globalRoot = await realpath(value.globalRoot);
+  const packageRoot = await realpath(value.packageRoot).catch(() => resolve(value.packageRoot));
+  const expectedPackage = resolve(globalRoot, ...value.packageName.split("/"));
+  if (!samePath(packageRoot, expectedPackage) || !containedBy(globalRoot, packageRoot)) throw new Error("A1 update recovery package root escapes npm global root");
+  const prefix = npmPrefixForGlobalRoot(globalRoot);
+  const expectedNpmArguments = ["install", "--global", "--prefix", prefix, "--loglevel=error", "--no-fund", "--no-audit", `${value.packageName}@${value.targetVersion}`];
+  const legacyNpmArguments = ["install", "--global", "--loglevel=error", "--no-fund", "--no-audit", `${value.packageName}@${value.targetVersion}`];
+  if (![expectedNpmArguments, legacyNpmArguments].some(arguments_ => sameArguments(value.npmArguments, arguments_))) {
+    throw new Error("A1 update recovery npm arguments are invalid");
+  }
+  const launcherRoot = resolve(value.launcherRoot);
+  const expectedLauncherRoot = process.platform === "win32" ? prefix : resolve(prefix, "bin");
+  if (!samePath(launcherRoot, expectedLauncherRoot)) throw new Error("A1 update recovery launcher root is invalid");
+  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((/** @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] ?? ""))) {
+    throw new Error("A1 update recovery sidecar paths are invalid");
+  }
+  const dataDir = dirname(dirname(capsuleRoot));
+  const releasesRoot = await realpath(resolve(dataDir, "releases"));
+  const priorReleaseRoot = await realpath(value.priorReleaseRoot);
+  assertDirectChild(releasesRoot, priorReleaseRoot);
+  if (priorReleaseRoot.split(sep).at(-1) !== value.priorReleaseId) throw new Error("A1 update recovery prior release identity is invalid");
+  const priorManifest = JSON.parse(await readFile(resolve(priorReleaseRoot, value.releaseManifestName), "utf8"));
+  if (priorManifest.launchContract !== "neutral-launch-v1") throw new Error("Unsupported prior private launch contract; manual cutover is required.");
+  if (priorManifest.releaseId !== value.priorReleaseId || priorManifest.contentDigest !== value.priorContentDigest) {
+    throw new Error("A1 update recovery prior release manifest is invalid");
+  }
+  const npmMetadata = await lstat(value.npmCli);
+  if (!npmMetadata.isFile() || npmMetadata.isSymbolicLink()) throw new Error("A1 update recovery npm entry is invalid");
+  return value;
+}
+
+/** @param {Capsule} value */
+async function installedTargetEntry(value) {
+  try {
+    const manifest = JSON.parse(await readFile(resolve(value.packageRoot, "package.json"), "utf8"));
+    const entry = resolve(value.packageRoot, "bin", "cli.js");
+    if (manifest.privateLaunchContract !== "neutral-launch-v1" || manifest.name !== value.packageName || manifest.version !== value.targetVersion || !(await lstat(entry)).isFile()) return null;
+    return entry;
+  } 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`;
+  for (const path of value.launchers) {
+    try {
+      const metadata = await lstat(path);
+      if (!metadata.isFile() || metadata.isSymbolicLink()) return false;
+      if (process.platform !== "win32" && (metadata.mode & 0o111) === 0) return false;
+      const normalized = (await readFile(path, "utf8")).replaceAll("\\", "/");
+      if (!normalized.includes(token)) return false;
+    } catch { return false; }
+  }
+  return true;
+}
+
+/** @param {Capsule} value */
+async function writeRecoveryLaunchers(value) {
+  const node = value.nodeExecutable ?? process.execPath;
+  const entry = value.recoveryEntry;
+  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);
+}
+
+/** @param {Capsule} value */
+async function recoveryLaunchersAreCallable(value) {
+  for (const path of value.launchers) {
+    try {
+      const metadata = await lstat(path);
+      if (!metadata.isFile() || metadata.isSymbolicLink()) return false;
+      if (process.platform !== "win32" && (metadata.mode & 0o111) === 0) return false;
+      if (!(await readFile(path, "utf8")).includes(value.recoveryEntry)) return false;
+    } catch { return false; }
+  }
+  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 });
+  await chmod(temporary, mode);
+  await rm(path, { force: true });
+  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`;
+  const file = await open(temporary, "wx", 0o600);
+  try { await file.writeFile(JSON.stringify(value, null, 2)); await file.sync(); }
+  finally { await file.close(); }
+  await rm(path, { force: true });
+  await rename(temporary, path);
+}
+
+/** @param {string} globalRoot */
+function npmPrefixForGlobalRoot(globalRoot) {
+  const root = resolve(globalRoot);
+  const nodeModules = process.platform === "win32" ? basename(root).toLowerCase() === "node_modules" : basename(root) === "node_modules";
+  if (!nodeModules) throw new Error("A1 update recovery npm global root layout is invalid");
+  if (process.platform === "win32") return dirname(root);
+  const libraryRoot = dirname(root);
+  if (basename(libraryRoot) !== "lib") throw new Error("A1 update recovery npm global root layout is invalid");
+  return dirname(libraryRoot);
+}
+
+/** @param {string[]} left @param {string[]} right */
+function sameArguments(left, right) {
+  return left.length === right.length && left.every((value, index) => value === right[index]);
+}
+
+/**
+ * @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

@@ -0,0 +1,28 @@
+#!/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);
+const [{ fileURLToPath }, identity, descriptor] = await Promise.all([
+  import("node:url"),
+  import("./module-identity.js"),
+  import("../dist/foundation/startup/startup-descriptor.js"),
+]);
+identity.configurePinnedPiPublicPackage(fileURLToPath(new URL("..", import.meta.url)));
+
+// Security: this entry imports the exact interactive graph but never composes it, so it
+// creates no terminal, profile/session path, trust callback, executable resource loader,
+// extension runner, or network client.
+const [launch, selection, trustPrompt, forkPrompt, run, composition] = await descriptor.loadDeclaredStartupGraph();
+if (typeof identity.assertSinglePiTuiModuleAtLaunch !== "function"
+  || typeof launch.runSelectedInteractiveRuntime !== "function"
+  || typeof selection.parseSessionSelection !== "function"
+  || typeof trustPrompt.createConsoleProjectTrustPrompt !== "function"
+  || typeof forkPrompt.createConsoleSessionForkPrompt !== "function"
+  || typeof run.runOwnedUi !== "function"
+  || typeof composition.composeOwnedUi !== "function") {
+  throw new Error("immutable startup graph is incomplete");
+}

package/dist/app/session-shell/clipboard-diagnostics.d.ts

@@ -0,0 +1,16 @@
+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. */
+export declare class ClipboardDiagnosticCapture {
+    #private;
+    private readonly destination;
+    private readonly write;
+    constructor(destination: string, write?: (file: string, data: string) => Promise<void>);
+    copy(event: ResponseCopyEvent): void;
+    paste(event: PasteEvent): void;
+    runtime(event: PiTuiInputDiagnosticsEvent): void;
+    /** Explicit test/evidence boundary; the interactive UI never waits for disk diagnostics. */
+    flush(): Promise<void>;
+    dispose(): void;
+}

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

@@ -0,0 +1,65 @@
+import { writeFile } from "node:fs/promises";
+const PHASES = new Set(["capture", "selection-clear", "queued", "preparing", "extracted", "encoded", "submitting", "settled", "cleanup",
+    "shortcut-received", "shortcut-matched", "shortcut-admitted", "pointer-admitted", "framing", "admitted", "predecessor", "acquiring", "acquired-text", "acquired-image", "classifying", "path-fallback", "prepared", "inserting",
+    "receipt", "semantic-start", "semantic-end", "composition-start", "composition-end", "write-start", "write-end", "heartbeat"]);
+/** Opt-in scalar-only snapshots, bounded to 128 rows and one pending asynchronous write. */
+export class ClipboardDiagnosticCapture {
+    #records = [];
+    #payloads = new Map();
+    #pending;
+    #writing;
+    #disposed = false;
+    #heartbeat;
+    destination;
+    write;
+    constructor(destination, write = (file, data) => writeFile(file, data, { encoding: "utf8", mode: 0o600 })) {
+        this.destination = destination;
+        this.write = write;
+        this.#heartbeat = setInterval(() => this.#record("heartbeat", { phase: "heartbeat", atMs: performance.now() }), 100);
+        this.#heartbeat.unref();
+    }
+    copy(event) { this.#record("copy", event); }
+    paste(event) { this.#record("paste", event); }
+    runtime(event) {
+        this.#record("runtime", { phase: event.phase, atMs: event.atMs, request: event.revision, pending: event.pendingDepth });
+    }
+    #record(source, event) {
+        if (this.#disposed || !PHASES.has(event.phase))
+            return;
+        const key = `${source}:${event.request ?? 0}`;
+        // Concurrency: eight pastes plus active/pending copy and the incoming superseding capture can overlap briefly.
+        if (["capture", "admitted"].includes(event.phase) && this.#payloads.size < 11)
+            this.#payloads.set(key, scalar(event.sourceUnits) * 2);
+        if (this.#payloads.has(key) && event.bytes !== undefined)
+            this.#payloads.set(key, Math.max(this.#payloads.get(key), scalar(event.bytes)));
+        if (event.phase === "settled" || event.phase === "cleanup")
+            this.#payloads.delete(key);
+        // Rationale: observed payload/source bytes, not an assertion about opaque native allocator overhead.
+        const pendingBytes = scalar([...this.#payloads.values()].reduce((sum, bytes) => sum + bytes, 0));
+        // Security: project only declared scalar fields. Never serialize the supplied event object or raw errors.
+        this.#records.push({ source, phase: event.phase, atMs: scalar(event.atMs), request: event.request !== undefined && event.request < 0 ? -scalar(-event.request) : scalar(event.request), pending: scalar(event.pending), bytes: scalar(event.bytes), elapsedMs: scalar(event.elapsedMs),
+            sourceUnits: scalar(event.sourceUnits), pendingBytes,
+            transport: ["native", "terminal", "provided", "injected"].includes(event.transport ?? "") ? event.transport : "none",
+            outcome: ["ready", "failed", "canceled", "delivered", "submitted-unverified", "timed-out", "superseded"].includes(event.outcome ?? "") ? event.outcome : "none" });
+        if (this.#records.length > 128)
+            this.#records.shift();
+        this.#pending = JSON.stringify({ schema: "clipboard-diagnostics-v1", records: this.#records });
+        this.#pump();
+    }
+    #pump() {
+        if (this.#disposed || this.#writing || this.#pending === undefined)
+            return;
+        const snapshot = this.#pending;
+        this.#pending = undefined;
+        this.#writing = Promise.resolve().then(() => this.write(this.destination, snapshot)).catch(() => {
+            // Security: diagnostics failure must not enter the normal terminal or block clipboard work.
+        }).finally(() => { this.#writing = undefined; this.#pump(); });
+    }
+    /** Explicit test/evidence boundary; the interactive UI never waits for disk diagnostics. */
+    async flush() { while (this.#writing)
+        await this.#writing; }
+    dispose() { this.#disposed = true; clearInterval(this.#heartbeat); this.#pending = undefined; this.#records = []; this.#payloads.clear(); }
+}
+function scalar(value) {
+    return value !== undefined && Number.isFinite(value) ? Math.max(0, Math.min(Number.MAX_SAFE_INTEGER, value)) : 0;
+}

package/dist/app/session-shell/clipboard-image.d.ts

@@ -0,0 +1,11 @@
+export interface ClipboardImageData {
+    readonly data: string;
+    readonly mimeType: string;
+}
+/**
+ * Converts valid padded or unpadded standard base64 into its unique padded form.
+ * Clipboard adapters are untrusted at this boundary, so reject representations
+ * that Node's permissive base64 decoder would otherwise partially accept.
+ */
+export declare function canonicalizeClipboardImage(image: ClipboardImageData, source?: boolean): ClipboardImageData | null;
+export declare function canonicalizeStandardBase64(value: string, source?: boolean): string | null;

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

@@ -0,0 +1,38 @@
+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;
+/**
+ * Converts valid padded or unpadded standard base64 into its unique padded form.
+ * Clipboard adapters are untrusted at this boundary, so reject representations
+ * that Node's permissive base64 decoder would otherwise partially accept.
+ */
+export function canonicalizeClipboardImage(image, source = false) {
+    const data = canonicalizeStandardBase64(image.data, source);
+    return data === null ? null : { data, mimeType: image.mimeType };
+}
+export function canonicalizeStandardBase64(value, source = false) {
+    if (typeof value !== "string" || value.length === 0)
+        return null;
+    const maximum = source ? Math.ceil(MAX_SOURCE_IMAGE_BYTES / 3) * 4 : MAX_IMAGE_DATA_BYTES;
+    if (Math.ceil(value.length / 4) * 4 > maximum)
+        throw new ImageAttachmentError(source ? "image-source-size" : "image-size");
+    if (!STANDARD_BASE64.test(value))
+        return null;
+    const paddingStart = value.indexOf("=");
+    const core = paddingStart < 0 ? value : value.slice(0, paddingStart);
+    const suppliedPadding = value.length - core.length;
+    const remainder = core.length % 4;
+    if (remainder === 1)
+        return null;
+    const requiredPadding = remainder === 0 ? 0 : 4 - remainder;
+    if (suppliedPadding !== 0 && suppliedPadding !== requiredPadding)
+        return null;
+    const padded = `${core}${"=".repeat(requiredPadding)}`;
+    const decoded = Buffer.from(padded, "base64");
+    if (source && decoded.length > MAX_SOURCE_IMAGE_BYTES)
+        throw new ImageAttachmentError("image-source-size");
+    if (decoded.length === 0)
+        return null;
+    const canonical = decoded.toString("base64");
+    return canonical === padded ? canonical : null;
+}

package/dist/app/session-shell/editor-hyperlink-budget.d.ts

@@ -0,0 +1,9 @@
+/** Aggregate explicit URL-chip metadata allowance for one owned editor decoration pass. */
+export declare const EDITOR_HYPERLINK_METADATA_BYTES: number;
+/** Accounts complete OSC 8 controls before construction, without scanning oversized backing URLs. */
+export declare class EditorHyperlinkBudget {
+    #private;
+    reset(): void;
+    takeCleanup(): boolean;
+    take(target: string): boolean;
+}

package/dist/app/session-shell/editor-hyperlink-budget.js

@@ -0,0 +1,23 @@
+/** Aggregate explicit URL-chip metadata allowance for one owned editor decoration pass. */
+export const EDITOR_HYPERLINK_METADATA_BYTES = 64 * 1024;
+const CLOSE_BYTES = 7;
+const PAIR_BYTES = CLOSE_BYTES * 2;
+/** Accounts complete OSC 8 controls before construction, without scanning oversized backing URLs. */
+export class EditorHyperlinkBudget {
+    #remaining = EDITOR_HYPERLINK_METADATA_BYTES;
+    reset() { this.#remaining = EDITOR_HYPERLINK_METADATA_BYTES; }
+    takeCleanup() { return this.#reserve(CLOSE_BYTES); }
+    take(target) {
+        // Performance: UTF-16 length is a lower bound on UTF-8 bytes, including replacement surrogates.
+        // Reject large backing values before byte counting, flattening, interpolation, or signatures.
+        if (target.length > this.#remaining - PAIR_BYTES)
+            return false;
+        return this.#reserve(PAIR_BYTES + Buffer.byteLength(target, "utf8"));
+    }
+    #reserve(bytes) {
+        if (bytes > this.#remaining)
+            return false;
+        this.#remaining -= bytes;
+        return true;
+    }
+}

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;
+}