@ckanner/flywheel 0.32.1 → 0.33.1

package/dist/machine-worker.mjs

@@ -0,0 +1,241 @@
+import { isAbsolute } from 'node:path';
+
+const LIFECYCLE_EVENTS = new Set(['thread-ready', 'dispatch-intent', 'dispatch-possible', 'turn-accepted', 'terminal', 'cleanup-confirmed']);
+const ACK_BYTES = 4096;
+const MAX_LIFECYCLE_EVENTS = 64;
+
+function identifier(value) {
+  return typeof value === 'string' && value.trim() !== '' && value.length <= 256 && !value.includes('\0');
+}
+
+/** Recovery carries only the old non-secret binding, never a prompt. */
+export function recoveryRequest(value, WorkerError) {
+  const keys = new Set(['type', 'protocol', 'requestId', 'runId', 'recoveryDirectory', 'original']);
+  const originalKeys = new Set(['cwd', 'model', 'reasoningEffort', 'permissionMode', 'threadMode', 'threadId']);
+  const o = value?.original;
+  if (!value || typeof value !== 'object' || Array.isArray(value) || value.type !== 'recover' || value.protocol !== 3 ||
+      Object.keys(value).some(key => !keys.has(key)) || !identifier(value.requestId) || !identifier(value.runId) ||
+      typeof value.recoveryDirectory !== 'string' || !isAbsolute(value.recoveryDirectory) || value.recoveryDirectory.includes('\0') || value.recoveryDirectory.length > 4096 ||
+      !o || typeof o !== 'object' || Array.isArray(o) || Object.keys(o).some(key => !originalKeys.has(key)) ||
+      typeof o.cwd !== 'string' || !isAbsolute(o.cwd) || o.cwd.includes('\0') || !identifier(o.model) ||
+      typeof o.reasoningEffort !== 'string' || !['read-only', 'workspace-write', 'danger-full-access'].includes(o.permissionMode) ||
+      !['ephemeral', 'persistent'].includes(o.threadMode) ||
+      (o.threadId !== undefined && (o.threadMode !== 'persistent' || !identifier(o.threadId)))) {
+    throw new WorkerError('INVALID_REQUEST', 'Expected a protocol 3 read-only recovery request with the original non-secret binding');
+  }
+  // No cwd resolution, login, runMachine, thread/resume or model request here.
+  return { protocol: 1, requestId: value.requestId, runId: value.runId, recoveryDirectory: value.recoveryDirectory };
+}
+
+// Parent lifeline and bounded transport; adapters own backend semantics.
+export async function runMachineWorker({ ADAPTER, LIMITS, WorkerError, loadAdapter, machineRequest, doctorResult,
+  label, commandName, attestAdmission = false, runtimeOptions = () => ({}) }) {
+  const controller = new AbortController();
+  let cancelledBy, inputFailure, outputFailure, requestId = 'invalid-request', protocol = 1, finished = false, adapterInvoked = false;
+  let recovery = false, pendingAck, lifecycleSequence = 0, lifecycleRunId, lifecycleBytes = 0;
+  const cancel = signal => { cancelledBy ??= signal; controller.abort(); };
+  const handlers = new Map(['SIGTERM', 'SIGINT', 'SIGHUP'].map(signal => [signal, () => cancel(signal)]));
+  for (const [signal, handler] of handlers) process.on(signal, handler);
+  process.stdout.on('error', () => {
+    outputFailure ??= new WorkerError('OUTPUT_ERROR', 'The result consumer closed or failed');
+    process.exitCode = 1;
+    controller.abort();
+  });
+
+  function write(frame) {
+    if (outputFailure) return false;
+    const line = JSON.stringify(frame) + '\n';
+    if (Buffer.byteLength(line) > LIMITS.receiptFrameBytes) throw new WorkerError('OUTPUT_LIMIT', label + ' result exceeded the complete receipt frame limit');
+    process.stdout.write(line);
+    return true;
+  }
+
+  function settleAck(error) {
+    if (!pendingAck) return;
+    const pending = pendingAck;
+    pendingAck = undefined;
+    clearTimeout(pending.timer);
+    if (error) pending.reject(error); else pending.resolve();
+  }
+
+  function acceptAck(value) {
+    const keys = new Set(['type', 'protocol', 'requestId', 'runId', 'sequence']);
+    if (protocol !== 3 || !pendingAck || !value || typeof value !== 'object' || Array.isArray(value) ||
+        Object.keys(value).some(key => !keys.has(key)) || value.type !== 'ack' || value.protocol !== 3 ||
+        value.requestId !== requestId || value.runId !== lifecycleRunId || value.sequence !== lifecycleSequence) {
+      throw new WorkerError('INVALID_ACK', 'A lifecycle acknowledgment must match the pending request, run and sequence');
+    }
+    settleAck();
+  }
+
+  /** Keep stdin open: protocol 3 uses durable ACKs, all versions use EOF as a lifeline. */
+  function input() {
+    let buffer = Buffer.alloc(0), admitted = false, inputProtocol = 1, ackBytes = 0, resolveInput, rejectInput;
+    const promise = new Promise((resolve, reject) => { resolveInput = resolve; rejectInput = reject; });
+    const fail = (code, message) => {
+      if (finished) return;
+      inputFailure ??= new WorkerError(code, message);
+      clearTimeout(timer);
+      rejectInput(inputFailure);
+      settleAck(inputFailure);
+      controller.abort();
+    };
+    const timer = setTimeout(() => fail('INPUT_TIMEOUT', 'No complete start request arrived within 10 seconds'), LIMITS.admissionMs);
+    const onData = chunk => {
+      if (finished || inputFailure) return;
+      buffer = Buffer.concat([buffer, chunk]);
+      while (buffer.length) {
+        if (admitted && buffer.toString('utf8').trim() !== '' && (inputProtocol !== 3 || !pendingAck)) {
+          fail(inputProtocol === 3 ? 'INVALID_ACK' : 'INVALID_REQUEST', 'Only the pending lifecycle checkpoint may be acknowledged');
+          return;
+        }
+        const newline = buffer.indexOf(10);
+        const limit = admitted ? ACK_BYTES : LIMITS.requestBytes;
+        if ((newline < 0 ? buffer.length : newline + 1) > limit) { fail('INPUT_LIMIT', 'A request or acknowledgment exceeded its frame limit'); return; }
+        if (newline < 0) return;
+        const bytes = buffer.subarray(0, newline);
+        buffer = buffer.subarray(newline + 1);
+        try {
+          const line = new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+          if (admitted) {
+            ackBytes += bytes.length + 1;
+            if (ackBytes > MAX_LIFECYCLE_EVENTS * ACK_BYTES) throw new WorkerError('INPUT_LIMIT', 'Lifecycle acknowledgments exceeded their total limit');
+            if (line.trim() === '') continue;
+          }
+          const value = JSON.parse(line);
+          if (!admitted) {
+            admitted = true;
+            inputProtocol = value?.protocol;
+            clearTimeout(timer);
+            resolveInput(value);
+          } else {
+            acceptAck(value);
+          }
+        } catch (error) {
+          fail(error instanceof WorkerError ? error.code : 'INVALID_REQUEST',
+            error instanceof WorkerError ? error.message : 'Every frame must be one valid UTF-8 JSON document');
+          return;
+        }
+      }
+    };
+    const onEnd = () => fail('PARENT_DISCONNECTED', 'The parent stdin lifeline closed before completion');
+    const onError = () => fail('INPUT_ERROR', 'The parent stdin lifeline failed');
+    const onAbort = () => {
+      clearTimeout(timer);
+      const error = inputFailure || outputFailure || new WorkerError('CANCELLED', label + ' worker was cancelled');
+      rejectInput(error);
+      settleAck(error);
+    };
+    process.stdin.on('data', onData);
+    process.stdin.once('end', onEnd);
+    process.stdin.once('error', onError);
+    controller.signal.addEventListener('abort', onAbort, { once: true });
+    if (controller.signal.aborted) onAbort();
+    return { promise, stop() {
+      clearTimeout(timer);
+      settleAck(new WorkerError('CANCELLED', 'The worker has settled'));
+      process.stdin.off('data', onData); process.stdin.off('end', onEnd); process.stdin.off('error', onError);
+      controller.signal.removeEventListener('abort', onAbort);
+      process.stdin.pause();
+      process.stdin.destroy();
+    } };
+  }
+
+  async function onLifecycle(event) {
+    if (controller.signal.aborted) throw inputFailure || outputFailure || new WorkerError('CANCELLED', 'Lifecycle consumer was cancelled');
+    if (pendingAck || !event || typeof event !== 'object' || event.type !== 'lifecycle' || event.lifecycleVersion !== 1 ||
+        event.requestId !== requestId || !identifier(event.runId) || (lifecycleRunId && lifecycleRunId !== event.runId) ||
+        !Number.isSafeInteger(event.sequence) || event.sequence !== lifecycleSequence + 1 || event.sequence > MAX_LIFECYCLE_EVENTS ||
+        !LIFECYCLE_EVENTS.has(event.event)) {
+      throw new WorkerError('INVALID_LIFECYCLE', 'The adapter emitted an uncorrelated or out-of-order lifecycle event');
+    }
+    lifecycleRunId = event.runId;
+    lifecycleSequence = event.sequence;
+    const frame = { protocol: 3, type: 'lifecycle', requestId, adapter: ADAPTER, lifecycle: event };
+    lifecycleBytes += Buffer.byteLength(JSON.stringify(frame) + '\n');
+    if (lifecycleBytes > LIMITS.progressBytes) throw new WorkerError('OUTPUT_LIMIT', 'Lifecycle evidence exceeded its stream limit');
+    // Install the waiter before writing so a fast durable consumer cannot race it.
+    await new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        inputFailure ??= new WorkerError('ACK_TIMEOUT', 'The parent did not durably acknowledge the lifecycle checkpoint in time');
+        settleAck(inputFailure);
+        controller.abort();
+      }, LIMITS.lifecycleAckMs ?? 10000);
+      pendingAck = { resolve, reject, timer };
+      try {
+        if (!write(frame)) settleAck(outputFailure);
+      } catch (error) { settleAck(error); controller.abort(); }
+    });
+  }
+
+  let lifeline;
+  try {
+    const args = process.argv.slice(2);
+    if (args.length > 1 || (args.length === 1 && args[0] !== '--doctor')) throw new WorkerError('INVALID_REQUEST', 'Use ' + commandName + ' [--doctor]');
+    if (args[0] === '--doctor') {
+      await loadAdapter();
+      write(doctorResult());
+      process.exitCode = 0;
+    } else {
+      lifeline = input();
+      const value = await lifeline.promise;
+      protocol = [2, 3].includes(value?.protocol) ? value.protocol : 1;
+      recovery = protocol === 3 && value?.type === 'recover';
+      if (identifier(value?.requestId)) requestId = value.requestId;
+      const api = await loadAdapter();
+      if (controller.signal.aborted) throw inputFailure || new WorkerError('CANCELLED', label + ' worker was cancelled before the run');
+      if (protocol === 3 && (api.MACHINE_LIFECYCLE_VERSION !== 1 || typeof api.recoverMachine !== 'function' ||
+          api.MACHINE_LIFECYCLE_CAPABILITIES?.durableJournal !== true || api.MACHINE_LIFECYCLE_CAPABILITIES?.readOnlyRecovery !== true)) {
+        throw new WorkerError('ADAPTER_MISMATCH', 'The selected adapter does not expose lifecycle 1 and read-only durable recovery');
+      }
+      if (recovery) {
+        const query = recoveryRequest(value, WorkerError);
+        const evidence = await api.recoverMachine(query);
+        finished = true;
+        lifeline.stop();
+        const error = inputFailure || outputFailure;
+        write({ protocol: 3, type: 'recovery', requestId, adapter: ADAPTER, recovery: evidence,
+          error: error ? { code: error.code, message: error.message } : null });
+        process.exitCode = error || controller.signal.aborted ? 1 : 0;
+      } else {
+        const request = machineRequest(value, api, process.env);
+        requestId = request.requestId;
+        let progressBytes = 0;
+        const options = { signal: controller.signal, env: process.env, ...runtimeOptions(process.env),
+          ...(protocol === 3 ? { recoveryDirectory: value.recoveryDirectory, onLifecycle } : {}),
+          onProgress(text) {
+            if (controller.signal.aborted) return;
+            const frame = { protocol, type: 'progress', requestId, text };
+            progressBytes += Buffer.byteLength(JSON.stringify(frame) + '\n');
+            if (progressBytes > LIMITS.progressBytes) {
+              outputFailure ??= new WorkerError('OUTPUT_LIMIT', label + ' progress exceeded the 1 MiB stream limit');
+              controller.abort();
+            } else write(frame);
+          } };
+        adapterInvoked = true;
+        const receipt = await api.runMachine(request, options);
+        finished = true;
+        lifeline.stop();
+        const error = inputFailure || outputFailure;
+        if (outputFailure?.code === 'OUTPUT_LIMIT') outputFailure = undefined;
+        write({ protocol, type: 'result', requestId, adapter: ADAPTER, receipt,
+          error: error ? { code: error.code, message: error.message } : null });
+        process.exitCode = receipt.ok && !error && !controller.signal.aborted ? 0 : 1;
+      }
+    }
+  } catch (error) {
+    finished = true;
+    lifeline?.stop();
+    const known = error instanceof WorkerError ? error : new WorkerError('WORKER_ERROR', label + ' worker failed before a complete receipt was available');
+    write({ protocol, type: recovery ? 'recovery' : 'result', requestId, adapter: ADAPTER,
+      ...(recovery ? { recovery: null } : { receipt: null }),
+      ...(attestAdmission && !adapterInvoked && !recovery ? { admission: { dispatched: false, cleanupConfirmed: true } } : {}),
+      error: { code: known.code, message: known.message } });
+    process.exitCode = 1;
+  } finally {
+    finished = true;
+    lifeline?.stop();
+    if (cancelledBy) process.exitCode = { SIGINT: 130, SIGTERM: 143, SIGHUP: 129 }[cancelledBy];
+    for (const [signal, handler] of handlers) process.off(signal, handler);
+  }
+}

package/dist/policy.mjs

@@ -0,0 +1,91 @@
+// Loaded only in the independently owned SDK process, never in the desktop host.
+// Public rc.5/rc.1 Cordis services; the worker verifies this acknowledgement before prompt().
+import { link, realpath, stat, unlink, writeFile } from 'node:fs/promises';
+import { dirname, isAbsolute } from 'node:path';
+import { readPolicyReceipt, nonempty } from './protocol.mjs';
+
+export const inject = ['sandboxPolicy', 'approval', 'shell', 'workingDirectory'];
+
+export async function apply(ctx, config) {
+  const { permissionMode, cwd, workspaceCwd, receiptPath, requestId, nonce, deferredAdmissionPath } = config;
+  let { sessionTitle, sessionId } = config;
+  const fullAccess = permissionMode === 'danger-full-access';
+  if (!['read-only', 'workspace-write', 'danger-full-access'].includes(permissionMode) || typeof cwd !== 'string' ||
+      ctx.shell.sandboxMode === undefined) {
+    throw new Error('Flywheel requires a sandbox-capable DSH shell and explicit permission policy');
+  }
+  if (typeof receiptPath !== 'string' || !isAbsolute(receiptPath) ||
+      [requestId, ...(deferredAdmissionPath === undefined ? [sessionId] : []), nonce].some(value => typeof value !== 'string' || value.trim() === '' || value.includes('\0'))) {
+    throw new Error('Flywheel policy requires an owned, correlated admission receipt');
+  }
+  if (deferredAdmissionPath !== undefined && (typeof deferredAdmissionPath !== 'string' || !isAbsolute(deferredAdmissionPath) ||
+      dirname(deferredAdmissionPath) !== dirname(receiptPath) || sessionId !== undefined)) {
+    throw new Error('Flywheel deferred admission requires the same owned receipt directory');
+  }
+  const parent = dirname(receiptPath);
+  const owner = await stat(parent);
+  if (await realpath(parent) !== parent || !owner.isDirectory() || (owner.mode & 0o077) !== 0) {
+    throw new Error('Flywheel policy receipt must be inside its private physical directory');
+  }
+  // Probe the official runner. Restricted modes must prove full enforcement;
+  // full access must truthfully report that no confinement was applied.
+  const probe = await ctx.shell.execute(ctx.shell.resolve({
+    command: ':', workdir: cwd, timeoutMs: 5000,
+    sandboxPolicy: { mode: permissionMode, workspaceRoot: cwd },
+  }));
+  const result = await probe.result();
+  if (result.exitCode !== 0 || result.timedOut || result.aborted ||
+      result.sandbox?.mode !== permissionMode ||
+      (fullAccess ? result.sandbox.denied !== false || result.sandbox.enforcement !== undefined : result.sandbox.enforcement !== 'full')) {
+    throw new Error(fullAccess ? 'Flywheel readiness probe did not confirm explicit full access' : 'Flywheel sandbox readiness probe did not prove full enforcement');
+  }
+  // Session creation is read-only in rc.1. Agent creation is awaited after
+  // that announcement and before the factory admits any model work in both hosts.
+  ctx.on('agent/created', async ({ agent }) => {
+    const session = agent.session;
+    if (deferredAdmissionPath !== undefined) {
+      const identity = await readPolicyReceipt(deferredAdmissionPath, { requestId, nonce });
+      if (Object.keys(identity).some(key => !['requestId', 'nonce', 'sessionId', 'sessionTitle'].includes(key))) {
+        throw new Error('Flywheel deferred admission has unsupported fields');
+      }
+      sessionId = nonempty(identity.sessionId, 'sessionId', 512);
+      sessionTitle = identity.sessionTitle === undefined ? undefined : nonempty(identity.sessionTitle, 'sessionTitle', 512);
+    }
+    if (String(session.id) !== sessionId) throw new Error('Flywheel policy refuses an unrelated SDK session');
+    if (workspaceCwd !== undefined && session.header.cwd !== workspaceCwd) {
+      throw new Error('Flywheel refuses to relabel a session from a different project workspace');
+    }
+    if (workspaceCwd !== undefined) {
+      // Public service accepts an unpublished Agent. Switch before attesting
+      // readiness. The native sandbox root remains the immutable project;
+      // unsupported split workspace-write requests are rejected at admission.
+      await ctx.workingDirectory.set(agent, cwd);
+    }
+    if (sessionTitle && ctx.get('sessionTitle')) {
+      ctx.get('sessionTitle').rename(session, [...sessionTitle].slice(0, 35).join(''));
+    }
+    // Official events remain readable by a later SDK. An ad-hoc Session event
+    // would make rc.1 reject the entire persisted log on resume.
+    session.append('sandbox/mode', { mode: permissionMode });
+    session.append('approval/policy', { policy: 'never' });
+    const policy = ctx.sandboxPolicy.resolve({ session });
+    const receipt = {
+      protocol: 1,
+      requestId, sessionId, nonce,
+      ...(workspaceCwd === undefined ? {} : { workspaceCwd: session.header.cwd }),
+      cwd: policy.workspaceRoot,
+      permissionMode: policy.mode,
+      // Read the explicit logged override through the public API.
+      approvalPolicy: ctx.approval.overrideOf(session),
+      confinedShell: !fullAccess,
+      ...(fullAccess ? {} : { enforcement: result.sandbox.enforcement }),
+    };
+    // The awaited creation hook publishes once into an owned 0700 directory.
+    // Exclusive creation + atomic link rejects existing files/symlinks. This
+    // transient control receipt is read before model dispatch, never on replay.
+    const pending = receiptPath + '.pending';
+    await writeFile(pending, JSON.stringify(receipt), { mode: 0o600, flag: 'wx' });
+    await link(pending, receiptPath);
+    await unlink(pending);
+  });
+}

package/dist/prewarm.mjs

@@ -0,0 +1,136 @@
+// One-use, no-prompt SDK startup. No model Session exists until the owned start.
+import { open, realpath, stat, link, unlink, readdir } from 'node:fs/promises';
+import { join, isAbsolute } from 'node:path';
+import { BridgeError, MAX_FRAME_BYTES, directory, nonempty, record } from './protocol.mjs';
+
+export const PREWARM_MS = 60000;
+const MAX_RECEIPT_BYTES = 8192;
+const TRUNCATED_DIAGNOSTIC = ' [truncated]';
+const BINDING_FIELDS = ['cwd', 'workspaceCwd', 'provider', 'model', 'reasoningEffort', 'permissionMode'];
+
+export async function validatePrepare(value) {
+  const keys = new Set(['type', 'protocol', 'warmId', 'binding', 'receiptDirectory', 'ttlMs', ...BINDING_FIELDS]);
+  if (!record(value) || value.type !== 'prepare' || value.protocol !== 1 ||
+      Object.keys(value).some(key => !keys.has(key)) || typeof value.warmId !== 'string' || typeof value.binding !== 'string' ||
+      !/^[a-zA-Z0-9_-]{8,128}$/.test(value.warmId) ||
+      !/^[a-f0-9]{64}$/.test(value.binding ?? '') || !Number.isSafeInteger(value.ttlMs) || value.ttlMs < 1 || value.ttlMs > PREWARM_MS ||
+      !['read-only', 'workspace-write', 'danger-full-access'].includes(value.permissionMode)) {
+    throw new BridgeError('INVALID_REQUEST', 'expected a bounded, identified SDK prepare request without a prompt');
+  }
+  const request = { ...value, cwd: await directory(value.cwd, 'cwd'),
+    ...(value.workspaceCwd === undefined ? {} : { workspaceCwd: await directory(value.workspaceCwd, 'workspaceCwd') }) };
+  for (const key of ['provider', 'model', 'reasoningEffort']) nonempty(value[key], key);
+  if (request.workspaceCwd && request.workspaceCwd !== request.cwd && request.permissionMode === 'workspace-write') {
+    throw new BridgeError('INVALID_REQUEST', 'separate execution roots require an explicitly compatible permission mode');
+  }
+  const path = value.receiptDirectory;
+  if (typeof path !== 'string' || !isAbsolute(path) || await realpath(path) !== path) {
+    throw new BridgeError('INVALID_REQUEST', 'prewarm receipt directory must be physical and absolute');
+  }
+  const owner = await stat(path);
+  if (!owner.isDirectory() || (owner.mode & 0o077) !== 0) throw new BridgeError('INVALID_REQUEST', 'prewarm receipt directory must be private');
+  if ((await readdir(path)).length) throw new BridgeError('INVALID_REQUEST', 'prewarm receipt directory must be new and empty');
+  return request;
+}
+
+export function matchWarmStart(prepared, request) {
+  if (request.maxTokens !== undefined) throw new BridgeError('INVALID_REQUEST', 'maxTokens cannot be introduced after SDK initialization');
+  if (BINDING_FIELDS.some(key => (prepared[key] ?? '') !== (request[key] ?? ''))) {
+    throw new BridgeError('INVALID_REQUEST', 'formal request differs from the initialized SDK binding');
+  }
+}
+
+export async function writeWarmReceipt(prepared, settled, error) {
+  // A parent may recover this receipt only after proving this worker has exited.
+  // Exclusive publication prevents overwriting evidence from another lifetime.
+  const pending = join(prepared.receiptDirectory, 'terminal.pending');
+  const diagnostic = typeof error?.message === 'string' ? error.message : undefined;
+  const receipt = { protocol: 1, warmId: prepared.warmId, binding: prepared.binding,
+    workerPid: process.pid, dispatched: false, cleanupConfirmed: settled,
+    ...(diagnostic === undefined ? {} : { error: '' }) };
+  let bytes = Buffer.byteLength(JSON.stringify(receipt) + '\n');
+  // Only diagnostic text is expendable. Never publish oversized or shortened
+  // proof fields; a validated prepare leaves ample room for the marker.
+  if (bytes > MAX_RECEIPT_BYTES || (diagnostic !== undefined && bytes + TRUNCATED_DIAGNOSTIC.length > MAX_RECEIPT_BYTES)) {
+    throw new BridgeError('INVALID_REQUEST', 'prewarm cleanup identity exceeds the private receipt limit');
+  }
+  if (diagnostic !== undefined) {
+    const parts = [], sizes = [];
+    // Read only the prefix that can fit. Per-code-point JSON size accounts for
+    // UTF-8, escapes and lone surrogates without splitting a surrogate pair.
+    for (const character of diagnostic) {
+      const size = Buffer.byteLength(JSON.stringify(character)) - 2;
+      if (bytes + size > MAX_RECEIPT_BYTES) {
+        while (bytes + TRUNCATED_DIAGNOSTIC.length > MAX_RECEIPT_BYTES) {
+          bytes -= sizes.pop(); parts.pop();
+        }
+        parts.push(TRUNCATED_DIAGNOSTIC);
+        break;
+      }
+      parts.push(character); sizes.push(size); bytes += size;
+    }
+    receipt.error = parts.join('');
+  }
+  const file = await open(pending, 'wx', 0o600);
+  try { await file.writeFile(JSON.stringify(receipt) + '\n'); await file.sync(); }
+  finally { await file.close(); }
+  await link(pending, join(prepared.receiptDirectory, 'terminal.json'));
+  await unlink(pending);
+  const directory = await open(prepared.receiptDirectory, 'r');
+  try { await directory.sync(); } finally { await directory.close(); }
+}
+
+/** Both phases keep stdin as the parent lifeline; EOF is never a start signal. */
+export function prewarmInput(controller, input = process.stdin) {
+  let buffer = Buffer.alloc(0), first, phase = 0, ready = false, finished = false;
+  let admit, rejectAdmission, next, rejectNext;
+  const admission = new Promise((resolve, reject) => { admit = resolve; rejectAdmission = reject; });
+  const dispatch = new Promise((resolve, reject) => { next = resolve; rejectNext = reject; });
+  dispatch.catch(() => {}); // Initialization may fail before a dispatch is awaited.
+  const fail = error => {
+    if (finished) return;
+    clearTimeout(timer);
+    rejectAdmission(error); rejectNext(error); controller.abort(error);
+  };
+  const timer = setTimeout(() => fail(new BridgeError('TIMEOUT', 'no complete prepare request within 10 seconds')), 10000);
+  const onData = chunk => {
+    if (finished || controller.signal.aborted) return;
+    buffer = Buffer.concat([buffer, chunk]);
+    while (buffer.length) {
+      const newline = buffer.indexOf(10);
+      if ((newline < 0 ? buffer.length : newline + 1) > MAX_FRAME_BYTES) {
+        fail(new BridgeError('INVALID_REQUEST', 'prewarm frame exceeds 8 MiB')); return;
+      }
+      if (newline < 0) return;
+      const bytes = buffer.subarray(0, newline); buffer = buffer.subarray(newline + 1);
+      try {
+        const value = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes));
+        if (phase === 0) { first = value; phase = 1; clearTimeout(timer); admit(value); }
+        else {
+          const close = value?.type === 'close';
+          if (phase !== 1 || !record(value) || value.protocol !== 1 || value.warmId !== first?.warmId ||
+              Object.keys(value).some(key => !['type', 'protocol', 'warmId', ...(close ? [] : ['request'])].includes(key)) ||
+              (!close && (value.type !== 'start' || !ready || !record(value.request)))) {
+            throw new BridgeError('INVALID_REQUEST', 'expected one matching ready start or close frame');
+          }
+          phase = 2;
+          next(close ? null : value.request);
+          if (close && !ready) controller.abort(new BridgeError('TRANSPORT', 'prewarm closed before readiness'));
+        }
+      } catch (error) {
+        fail(error instanceof BridgeError ? error : new BridgeError('INVALID_REQUEST', 'prewarm frames must be complete UTF-8 JSON'));
+        return;
+      }
+    }
+  };
+  const onEnd = () => fail(new BridgeError('TRANSPORT', 'prewarm parent lifeline closed'));
+  const onError = () => fail(new BridgeError('TRANSPORT', 'prewarm parent lifeline failed'));
+  const onAbort = () => { clearTimeout(timer); rejectAdmission(controller.signal.reason); rejectNext(controller.signal.reason); };
+  controller.signal.addEventListener('abort', onAbort, { once: true });
+  if (controller.signal.aborted) onAbort();
+  input.on('data', onData); input.once('end', onEnd); input.once('error', onError);
+  return { admission, dispatch, ready() { ready = true; }, stop() {
+    finished = true; clearTimeout(timer); controller.signal.removeEventListener('abort', onAbort);
+    input.off('data', onData); input.off('end', onEnd); input.off('error', onError); input.pause();
+  } };
+}