chati-dev 4.5.15 → 4.5.27

package/src/terminal/spawner.js

@@ -7,11 +7,31 @@
  * (spawnTerminal) that actually calls child_process.spawn.
  */
 
-import { spawn } from 'child_process';
+import { spawn, spawnSync } from 'child_process';
+import { createHash } from 'node:crypto';
+import { EventEmitter } from 'node:events';
+import {
+  closeSync, constants, fstatSync, fsyncSync, lstatSync, mkdirSync, mkdtempSync, openSync,
+  readFileSync, readSync, realpathSync, rmSync, writeSync,
+} from 'node:fs';
+import { homedir, hostname, tmpdir } from 'node:os';
+import { basename, delimiter, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { canonicalize, sha256 } from '@chati/core';
 import { validateWriteScopes, buildIsolationEnv } from './isolation.js';
 import { getProvider } from './cli-registry.js';
 import { getRateLimiter } from './rate-limiter.js';
 import { recordModelSelection } from '../orchestrator/session-manager.js';
+import {
+  digestProviderExecutable, openPinnedProviderExecutable, openPinnedProviderSupportingExecutables,
+} from '../installer-v2/provider-executable.js';
+import {
+  installationAuthorityStateDirectory, signHostAuthorityPayload, verifyHostAuthorityPayload,
+} from '../installer-v2/installation-authority.js';
+import {
+  assertRailExecutionWorktreeBaselineUnchanged,
+  captureRailExecutionWorktree,
+  verifyRailExecutionWorktreeResult,
+} from './rail-execution-worktree.js';
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -38,6 +58,768 @@ const OVERLOAD_PATTERNS = [/529/, /overloaded/i, /capacity/i, /too many requests
 // ---------------------------------------------------------------------------
 
 let _counter = 0;
+const TERMINAL_AUTHORITY_STATE = new WeakMap();
+const TERMINAL_AUTHORITY_DOMAIN = 'chati-terminal-receipt-v1';
+const TERMINAL_SECURITY_TEST_HOOKS = Symbol.for('chati.terminal.security-test-hooks');
+const READ_ONLY_PROVIDERS = new Set(['claude', 'codex', 'grok']);
+const BUBBLEWRAP_PATH = '/usr/bin/bwrap';
+const PROVIDER_CONTROL_PLANE_DIRECTORIES = Object.freeze([
+  '.chati', '.chati.dev', '.claude', '.codex', '.grok', '.agents',
+]);
+const PROCESS_TREE_SETTLE_WAIT = new Int32Array(new SharedArrayBuffer(4));
+const PRIVATE_PROMPT_MARKER = '<chati-private-prompt-file>';
+const CONTAINED_PROMPT_PATH = '/run/user/chati-private-prompt';
+const CONTAINED_PROVIDER_EXECUTABLE_PATH = '/run/user/chati-provider-executable';
+const AUTHORITY_SYSTEM_PATH = '/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin';
+const TEAM_CONTEXT_ENV_KEYS = Object.freeze([
+  'CHATI_TEAM_ID', 'CHATI_TEAM_MEMBER', 'CHATI_TEAM_TASK_LIST', 'CHATI_TEAM_MAILBOX',
+]);
+
+function runTerminalSecurityTestHook(name, payload) {
+  const hooks = globalThis[TERMINAL_SECURITY_TEST_HOOKS];
+  if (hooks && typeof hooks[name] === 'function') hooks[name](payload);
+}
+
+function openPrivatePromptFile(prompt) {
+  const directory = mkdtempSync(join(tmpdir(), 'chati-terminal-prompt-'));
+  const path = join(directory, 'prompt');
+  const bytes = Buffer.from(String(prompt), 'utf8');
+  let writer;
+  let descriptor;
+  try {
+    writer = openSync(path, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | (constants.O_NOFOLLOW || 0), 0o600);
+    let offset = 0;
+    while (offset < bytes.length) offset += writeSync(writer, bytes, offset, bytes.length - offset, null);
+    fsyncSync(writer);
+    const written = fstatSync(writer);
+    closeSync(writer);
+    writer = undefined;
+    descriptor = openSync(path, constants.O_RDONLY | (constants.O_NOFOLLOW || 0));
+    const pinned = fstatSync(descriptor);
+    if (!pinned.isFile() || pinned.dev !== written.dev || pinned.ino !== written.ino
+      || pinned.nlink !== 1 || pinned.size !== bytes.length || (pinned.mode & 0o777) !== 0o600) {
+      return failContainment('private provider prompt file could not be descriptor-pinned');
+    }
+    const record = Object.freeze({ descriptor, directory, path, size: bytes.length });
+    runTerminalSecurityTestHook('afterPrivatePromptFileOpen', { path, directory, size: bytes.length });
+    return record;
+  } catch (error) {
+    if (writer !== undefined) try { closeSync(writer); } catch { /* preserve primary error */ }
+    if (descriptor !== undefined) try { closeSync(descriptor); } catch { /* preserve primary error */ }
+    rmSync(directory, { recursive: true, force: true });
+    throw error;
+  }
+}
+
+function cleanupPrivatePromptFile(record) {
+  if (record?.directory) rmSync(record.directory, { recursive: true, force: true });
+}
+
+function materializePrivatePromptArgs(args, promptPath) {
+  const matches = args.filter((argument) => argument === PRIVATE_PROMPT_MARKER).length;
+  if (matches !== 1) return failContainment('private provider prompt marker is missing or ambiguous');
+  return args.map((argument) => argument === PRIVATE_PROMPT_MARKER ? promptPath : argument);
+}
+
+function failContainment(message) {
+  throw Object.assign(new Error(message), { code: 'TERMINAL_CONTAINMENT_UNAVAILABLE' });
+}
+
+function hostRootIsUnmapped(uidMap) {
+  return String(uidMap).trim().split(/\n+/).some((line) => {
+    const [inside, outside, length] = line.trim().split(/\s+/).map(Number);
+    return inside === 0 && outside === 0 && Number.isInteger(length) && length > 0;
+  });
+}
+
+export function _validateBubblewrapTrust({
+  trustedDirectories, pathStat, descriptorStat, uidMap, effectiveUid,
+} = {}) {
+  if (!Array.isArray(trustedDirectories) || trustedDirectories.length !== 3
+    || !Number.isInteger(effectiveUid) || effectiveUid < 0
+    || !hostRootIsUnmapped(uidMap)) {
+    return failContainment('Bubblewrap trust requires an unmapped host-root identity');
+  }
+  if (trustedDirectories.some(({ stat }) => !stat || stat.isSymbolicLink() || !stat.isDirectory()
+    || stat.uid !== 0 || (stat.mode & 0o022) !== 0)) {
+    return failContainment('Bubblewrap containment ancestors must be host-root-owned, non-writable real directories');
+  }
+  if (!pathStat || !descriptorStat
+    || pathStat.isSymbolicLink() || !pathStat.isFile() || !descriptorStat.isFile()
+    || pathStat.dev !== descriptorStat.dev || pathStat.ino !== descriptorStat.ino
+    || descriptorStat.uid !== 0 || (descriptorStat.mode & 0o022) !== 0
+    || descriptorStat.nlink < 1) {
+    return failContainment('Bubblewrap containment binary must be host-root-owned, non-writable and descriptor-pinned');
+  }
+  return true;
+}
+
+function executableSnapshot(stat) {
+  return Object.freeze({
+    dev: stat.dev, ino: stat.ino, mode: stat.mode, uid: stat.uid,
+    gid: stat.gid, nlink: stat.nlink, size: stat.size,
+    mtimeMs: stat.mtimeMs, ctimeMs: stat.ctimeMs,
+  });
+}
+
+function sameExecutableSnapshot(left, right) {
+  return Object.keys(left).every((key) => left[key] === right[key]);
+}
+
+function digestPinnedExecutable(descriptor, expected = null) {
+  const before = executableSnapshot(fstatSync(descriptor));
+  if (before.size < 1 || before.size > 16 * 1024 * 1024) {
+    return failContainment('Bubblewrap containment binary has an invalid bounded size');
+  }
+  const hash = createHash('sha256');
+  const buffer = Buffer.allocUnsafe(64 * 1024);
+  let position = 0;
+  while (position < before.size) {
+    const bytesRead = readSync(descriptor, buffer, 0, Math.min(buffer.length, before.size - position), position);
+    if (bytesRead === 0) return failContainment('Bubblewrap containment binary changed during hashing');
+    hash.update(buffer.subarray(0, bytesRead));
+    position += bytesRead;
+  }
+  const after = executableSnapshot(fstatSync(descriptor));
+  const digest = hash.digest('hex');
+  if (!sameExecutableSnapshot(before, after)
+    || (expected && (!sameExecutableSnapshot(after, expected.snapshot) || digest !== expected.digest))) {
+    return failContainment('Bubblewrap containment binary changed after trust validation');
+  }
+  return Object.freeze({ digest, snapshot: after });
+}
+
+function currentBubblewrapTrust(descriptor) {
+  const trustedDirectories = ['/', '/usr', '/usr/bin'].map((path) => ({ path, stat: lstatSync(path) }));
+  const pathStat = lstatSync(BUBBLEWRAP_PATH);
+  const descriptorStat = fstatSync(descriptor);
+  _validateBubblewrapTrust({
+    trustedDirectories, pathStat, descriptorStat,
+    uidMap: readFileSync('/proc/self/uid_map', 'utf8'),
+    effectiveUid: process.geteuid?.() ?? process.getuid?.() ?? -1,
+  });
+}
+
+function requireBubblewrapContainment() {
+  if (process.platform !== 'linux') {
+    throw Object.assign(new Error('authority-bearing RAIL processes require Linux PID-namespace containment'), { code: 'TERMINAL_CONTAINMENT_UNAVAILABLE' });
+  }
+  let descriptor;
+  try { descriptor = openSync(BUBBLEWRAP_PATH, constants.O_RDONLY | (constants.O_NOFOLLOW || 0)); }
+  catch (error) {
+    throw Object.assign(new Error(`authority-bearing RAIL processes require ${BUBBLEWRAP_PATH}: ${error.message}`), { code: 'TERMINAL_CONTAINMENT_UNAVAILABLE' });
+  }
+  let probeDirectoryDescriptor;
+  try {
+    currentBubblewrapTrust(descriptor);
+    const executable = digestPinnedExecutable(descriptor);
+    probeDirectoryDescriptor = openSync('/', constants.O_RDONLY | (constants.O_DIRECTORY || 0) | (constants.O_NOFOLLOW || 0));
+    const probe = spawnSync('/proc/self/fd/3', [
+      '--die-with-parent', '--unshare-pid', '--unshare-ipc', '--unshare-cgroup-try',
+      '--ro-bind', '/', '/', '--dev', '/dev', '--proc', '/proc', '--tmpfs', '/run/user',
+      '--ro-bind-fd', '4', '/mnt', '--', '/bin/sh', '-c',
+      'test ! -e /proc/self/fd/4 && test -r /mnt/usr/bin/true',
+    ], { encoding: 'utf8', timeout: 10_000, stdio: ['ignore', 'pipe', 'pipe', descriptor, probeDirectoryDescriptor] });
+    closeSync(probeDirectoryDescriptor);
+    probeDirectoryDescriptor = undefined;
+    if (probe.status !== 0 || probe.error) {
+      throw Object.assign(new Error(`Bubblewrap descriptor-consuming PID-namespace containment is unavailable: ${probe.error?.message || probe.stderr || `status ${probe.status}`}`), { code: 'TERMINAL_CONTAINMENT_UNAVAILABLE' });
+    }
+    currentBubblewrapTrust(descriptor);
+    digestPinnedExecutable(descriptor, executable);
+    return Object.freeze({ descriptor, binaryDigest: executable.digest, executable });
+  } catch (error) {
+    if (probeDirectoryDescriptor !== undefined) closeSync(probeDirectoryDescriptor);
+    closeSync(descriptor);
+    throw error;
+  }
+}
+
+function pathContains(root, candidate) {
+  const pathFromRoot = relative(resolve(root), resolve(candidate));
+  return pathFromRoot === '' || (pathFromRoot !== '..' && !pathFromRoot.startsWith(`..${sep}`) && !isAbsolute(pathFromRoot));
+}
+
+function directorySnapshot(stat) {
+  return Object.freeze({
+    dev: stat.dev, ino: stat.ino, mode: stat.mode, uid: stat.uid,
+    gid: stat.gid,
+  });
+}
+
+function sameDirectorySnapshot(left, right) {
+  return Object.keys(left).every((key) => left[key] === right[key]);
+}
+
+function closeDirectoryChain(chain) {
+  for (const descriptor of [...(chain?.descriptors ?? [])].reverse()) {
+    try { closeSync(descriptor); } catch { /* preserve the primary containment result */ }
+  }
+}
+
+function openPinnedDirectoryChain(path) {
+  if (process.platform !== 'linux') {
+    return failContainment('authority-bearing RAIL processes require Linux descriptor-pinned project storage');
+  }
+  const absolute = resolve(path);
+  const descriptors = [];
+  const snapshots = [];
+  let descriptor;
+  try {
+    descriptor = openSync('/', constants.O_RDONLY | (constants.O_DIRECTORY || 0) | (constants.O_NOFOLLOW || 0));
+    descriptors.push(descriptor);
+    snapshots.push(directorySnapshot(fstatSync(descriptor)));
+    for (const segment of absolute.slice(1).split(sep).filter(Boolean)) {
+      descriptor = openSync(
+        join(`/proc/self/fd/${descriptor}`, segment),
+        constants.O_RDONLY | (constants.O_DIRECTORY || 0) | (constants.O_NOFOLLOW || 0),
+      );
+      const stat = fstatSync(descriptor);
+      if (!stat.isDirectory()) return failContainment('authority project chain must contain only real directories');
+      descriptors.push(descriptor);
+      snapshots.push(directorySnapshot(stat));
+    }
+    return Object.freeze({
+      path: absolute,
+      reference: `/proc/self/fd/${descriptors.at(-1)}`,
+      descriptors: Object.freeze(descriptors),
+      snapshots: Object.freeze(snapshots),
+      identity_digest: sha256({ path: absolute, snapshots }),
+    });
+  } catch (error) {
+    closeDirectoryChain({ descriptors });
+    if (error?.code === 'TERMINAL_CONTAINMENT_UNAVAILABLE') throw error;
+    return failContainment(`authority project chain cannot be pinned: ${error.message}`);
+  }
+}
+
+function assertPinnedDirectoryChain(chain) {
+  const current = openPinnedDirectoryChain(chain.path);
+  try {
+    if (current.snapshots.length !== chain.snapshots.length
+      || current.snapshots.some((snapshot, index) => !sameDirectorySnapshot(snapshot, chain.snapshots[index]))) {
+      return failContainment('authority project chain changed before provider launch');
+    }
+    for (const [index, descriptor] of chain.descriptors.entries()) {
+      if (!sameDirectorySnapshot(directorySnapshot(fstatSync(descriptor)), chain.snapshots[index])) {
+        return failContainment('pinned authority project directory changed before provider launch');
+      }
+    }
+    return true;
+  } finally { closeDirectoryChain(current); }
+}
+
+function ensureScopedDirectory(projectChain, relativeDirectory) {
+  const descriptors = [];
+  const snapshots = [];
+  let reference = projectChain.reference;
+  try {
+    for (const segment of relativeDirectory.split(sep).filter(Boolean)) {
+      const target = join(reference, segment);
+      try { mkdirSync(target, { mode: 0o700 }); }
+      catch (error) { if (error?.code !== 'EEXIST') throw error; }
+      const pathStat = lstatSync(target);
+      if (pathStat.isSymbolicLink() || !pathStat.isDirectory()) {
+        return failContainment('Planning write scope ancestors must be real directories');
+      }
+      const descriptor = openSync(
+        target,
+        constants.O_RDONLY | (constants.O_DIRECTORY || 0) | (constants.O_NOFOLLOW || 0),
+      );
+      const pinned = fstatSync(descriptor);
+      if (pathStat.dev !== pinned.dev || pathStat.ino !== pinned.ino) {
+        closeSync(descriptor);
+        return failContainment('Planning write scope changed while it was pinned');
+      }
+      descriptors.push(descriptor);
+      snapshots.push(directorySnapshot(pinned));
+      reference = `/proc/self/fd/${descriptor}`;
+    }
+    return Object.freeze({ descriptors, snapshots, reference });
+  } catch (error) {
+    descriptors.reverse().forEach((descriptor) => { try { closeSync(descriptor); } catch { /* already closed */ } });
+    if (error?.code === 'TERMINAL_CONTAINMENT_UNAVAILABLE') throw error;
+    return failContainment(`Planning write scope cannot be pinned: ${error.message}`);
+  }
+}
+
+function preparePinnedWriteScopes(projectChain, writeScope = []) {
+  if (!Array.isArray(writeScope)) return failContainment('terminal write scope must be an array');
+  const normalized = [...new Set(writeScope.map((scope) => String(scope || '').trim()).filter(Boolean))];
+  const fullProject = normalized.some((scope) => ['.', './'].includes(scope));
+  if (fullProject && normalized.length !== 1) return failContainment('full-project write scope cannot be combined with narrower scopes');
+  if (fullProject) return Object.freeze({ fullProject: true, entries: Object.freeze([]), descriptors: Object.freeze([]) });
+
+  const entries = [];
+  const descriptors = [];
+  try {
+    for (const scope of normalized) {
+      if (isAbsolute(scope)) return failContainment('terminal write scopes must be project-relative');
+      const directoryScope = scope.endsWith('/') || scope.endsWith(sep);
+      const absolute = resolve(projectChain.path, scope);
+      if (!pathContains(projectChain.path, absolute)) return failContainment('terminal write scope escapes the project');
+      for (const protectedPath of ['.chati', '.chati.dev']) {
+        const protectedAbsolute = resolve(projectChain.path, protectedPath);
+        if (pathContains(protectedAbsolute, absolute) || pathContains(absolute, protectedAbsolute)) {
+          return failContainment('terminal write scope overlaps the CHATI control plane');
+        }
+      }
+      const rel = relative(projectChain.path, absolute);
+      if (!rel) return failContainment('full-project write authority must use the explicit dot scope');
+      const parentRel = directoryScope ? rel : dirname(rel);
+      const parent = ensureScopedDirectory(projectChain, parentRel === '.' ? '' : parentRel);
+      descriptors.push(...parent.descriptors);
+      let targetDescriptor;
+      let targetSnapshot;
+      if (directoryScope) {
+        targetDescriptor = parent.descriptors.at(-1);
+        targetSnapshot = parent.snapshots.at(-1);
+      } else {
+        const name = rel.split(sep).at(-1);
+        const target = join(parent.reference, name);
+        const pathFlags = constants.O_RDWR | constants.O_CREAT | (constants.O_NOFOLLOW || 0);
+        targetDescriptor = openSync(target, pathFlags, 0o600);
+        const stat = fstatSync(targetDescriptor);
+        if (!stat.isFile() || stat.nlink !== 1) {
+          closeSync(targetDescriptor);
+          return failContainment('Planning file write scope must be a regular single-link file');
+        }
+        descriptors.push(targetDescriptor);
+        targetSnapshot = executableSnapshot(stat);
+      }
+      entries.push(Object.freeze({
+        target: absolute,
+        descriptor: targetDescriptor,
+        snapshot: targetSnapshot,
+        kind: directoryScope ? 'directory' : 'file',
+      }));
+    }
+    return Object.freeze({
+      fullProject: false,
+      entries: Object.freeze(entries),
+      descriptors: Object.freeze([...new Set(descriptors)]),
+    });
+  } catch (error) {
+    [...new Set(descriptors)].reverse().forEach((descriptor) => { try { closeSync(descriptor); } catch { /* already closed */ } });
+    if (error?.code === 'TERMINAL_CONTAINMENT_UNAVAILABLE') throw error;
+    return failContainment(`Planning write scope cannot be prepared: ${error.message}`);
+  }
+}
+
+function assertPinnedWriteScopes(scopes) {
+  for (const entry of scopes?.entries ?? []) {
+    const current = entry.kind === 'directory'
+      ? directorySnapshot(fstatSync(entry.descriptor))
+      : executableSnapshot(fstatSync(entry.descriptor));
+    const matches = entry.kind === 'directory'
+      ? sameDirectorySnapshot(current, entry.snapshot)
+      : sameExecutableSnapshot(current, entry.snapshot);
+    if (!matches) return failContainment('Planning write scope changed before provider launch');
+  }
+  return true;
+}
+
+function readOnlyTmpPathEntries() {
+  const entries = [...new Set(String(process.env.PATH || '').split(delimiter).filter(Boolean).map((entry) => resolve(entry)))];
+  return entries.filter((entry) => pathContains('/tmp', entry)).flatMap((entry) => {
+    try {
+      const stat = lstatSync(entry);
+      return !stat.isSymbolicLink() && stat.isDirectory() ? ['--ro-bind', entry, entry] : [];
+    } catch { return []; }
+  });
+}
+
+function hiddenInstallationAuthorityArgs() {
+  const directory = installationAuthorityStateDirectory();
+  try {
+    const stat = lstatSync(directory);
+    if (stat.isSymbolicLink() || !stat.isDirectory()) {
+      return failContainment('installation authority state must be a real directory');
+    }
+    return ['--tmpfs', directory];
+  } catch (error) {
+    if (error?.code === 'ENOENT') return [];
+    if (error?.code === 'TERMINAL_CONTAINMENT_UNAVAILABLE') throw error;
+    return failContainment(`installation authority state cannot be isolated: ${error.message}`);
+  }
+}
+
+function buildAuthorityContainment({
+  args, cwd, readOnly, writeScope, terminalId, provider, providerExecutableBinding,
+  promptRecord = null, maskedReadPaths = [],
+}) {
+  const trustedBubblewrap = requireBubblewrapContainment();
+  if (providerExecutableBinding === undefined) {
+    closeSync(trustedBubblewrap.descriptor);
+    throw Object.assign(new Error('authority-bearing provider launch requires an executable binding sealed by the installation'), { code: 'PROVIDER_EXECUTABLE_BINDING_REQUIRED' });
+  }
+  let projectChain;
+  const maskedChains = [];
+  let trustedProvider;
+  let trustedSupportingProviders = [];
+  let pinnedWriteScopes;
+  const stateDirectory = join(homedir(), provider === 'claude' ? '.claude' : provider === 'codex' ? '.codex' : '.grok');
+  let stateDirectoryArgs;
+  let stateDirectoryDescriptor;
+  const controlPlaneDescriptors = [];
+  const controlPlaneArgs = [];
+  try {
+    trustedProvider = openPinnedProviderExecutable(providerExecutableBinding, { harnessId: provider, projectDir: cwd });
+    trustedSupportingProviders = openPinnedProviderSupportingExecutables(
+      providerExecutableBinding, { harnessId: provider, projectDir: cwd },
+    );
+    projectChain = openPinnedDirectoryChain(cwd);
+    if (!Array.isArray(maskedReadPaths)) return failContainment('masked read paths must be an array');
+    for (const requested of [...new Set(maskedReadPaths.map((entry) => resolve(String(entry))))]) {
+      const physical = realpathSync(requested);
+      if (pathContains(physical, cwd) || pathContains(cwd, physical)) {
+        return failContainment('masked read path must not overlap the authority working directory');
+      }
+      maskedChains.push(openPinnedDirectoryChain(physical));
+    }
+    pinnedWriteScopes = preparePinnedWriteScopes(projectChain, readOnly ? [] : writeScope);
+    let stateStat;
+    try { stateStat = lstatSync(stateDirectory); }
+    catch (error) {
+      if (error?.code !== 'ENOENT') throw error;
+      mkdirSync(stateDirectory, { mode: 0o700 });
+      stateStat = lstatSync(stateDirectory);
+    }
+    if (!stateStat.isDirectory()) {
+      throw Object.assign(new Error('provider state path must be a real directory'), { code: 'TERMINAL_CONTAINMENT_UNAVAILABLE' });
+    }
+    stateDirectoryDescriptor = openSync(stateDirectory, constants.O_RDONLY | (constants.O_DIRECTORY || 0) | (constants.O_NOFOLLOW || 0));
+    const descriptorStat = fstatSync(stateDirectoryDescriptor);
+    if (descriptorStat.dev !== stateStat.dev || descriptorStat.ino !== stateStat.ino) {
+      throw Object.assign(new Error('provider state directory changed before containment'), { code: 'TERMINAL_CONTAINMENT_UNAVAILABLE' });
+    }
+    const physicalProject = realpathSync(projectChain.reference);
+    const physicalState = realpathSync(stateDirectory);
+    if (pathContains(physicalProject, physicalState) || pathContains(physicalState, physicalProject)) {
+      throw Object.assign(new Error('provider state and project directories must not physically overlap inside authority containment'), { code: 'TERMINAL_CONTAINMENT_UNAVAILABLE' });
+    }
+    // The project bind is applied after the authority key mask. Rejecting an
+    // overlap prevents that later bind from remounting the private key into
+    // the provider namespace through a caller-selected project path.
+    try {
+      const physicalAuthority = realpathSync(installationAuthorityStateDirectory());
+      if (pathContains(physicalProject, physicalAuthority) || pathContains(physicalAuthority, physicalProject)) {
+        throw Object.assign(new Error('installation authority and project directories must not physically overlap inside authority containment'), { code: 'TERMINAL_CONTAINMENT_UNAVAILABLE' });
+      }
+    } catch (error) {
+      if (error?.code !== 'ENOENT') throw error;
+    }
+    for (const masked of maskedChains) {
+      if (pathContains(masked.path, physicalState) || pathContains(physicalState, masked.path)
+        || pathContains(masked.path, trustedProvider.binding.executable_path)) {
+        throw Object.assign(new Error('masked read path overlaps provider state or executable authority'), { code: 'TERMINAL_CONTAINMENT_UNAVAILABLE' });
+      }
+    }
+    stateDirectoryArgs = ['--bind-fd', '4', stateDirectory];
+    // Provider-specific configuration is control-plane material too. A RAIL
+    // execution may write its scoped product files, but cannot rewrite a
+    // harness hook, skill, rule or config and then rely on that change in the
+    // same contained process.
+    for (const name of PROVIDER_CONTROL_PLANE_DIRECTORIES) {
+      const target = join(projectChain.reference, name);
+      let targetStat;
+      try { targetStat = lstatSync(target); }
+      catch (error) { if (error?.code === 'ENOENT') continue; throw error; }
+      if (targetStat.isSymbolicLink() || !targetStat.isDirectory()) {
+        throw Object.assign(new Error(`${name} control plane must be a real directory`), { code: 'TERMINAL_CONTAINMENT_UNAVAILABLE' });
+      }
+      const descriptor = openSync(target, constants.O_RDONLY | (constants.O_DIRECTORY || 0) | (constants.O_NOFOLLOW || 0));
+      const pinned = fstatSync(descriptor);
+      if (pinned.dev !== targetStat.dev || pinned.ino !== targetStat.ino
+        || !pathContains(physicalProject, realpathSync(target))) {
+        closeSync(descriptor);
+        throw Object.assign(new Error(`${name} control plane changed before containment`), { code: 'TERMINAL_CONTAINMENT_UNAVAILABLE' });
+      }
+      const descriptorNumber = 6 + controlPlaneDescriptors.length;
+      controlPlaneDescriptors.push(descriptor);
+      controlPlaneArgs.push('--ro-bind-fd', String(descriptorNumber), join(cwd, name));
+    }
+  } catch (error) {
+    controlPlaneDescriptors.forEach((descriptor) => closeSync(descriptor));
+    if (stateDirectoryDescriptor !== undefined) closeSync(stateDirectoryDescriptor);
+    if (trustedProvider?.descriptor !== undefined) closeSync(trustedProvider.descriptor);
+    trustedSupportingProviders.forEach((support) => closeSync(support.descriptor));
+    for (const descriptor of pinnedWriteScopes?.descriptors ?? []) try { closeSync(descriptor); } catch { /* already closed */ }
+    for (const chain of maskedChains) closeDirectoryChain(chain);
+    closeDirectoryChain(projectChain);
+    closeSync(trustedBubblewrap.descriptor);
+    if (error?.code === 'TERMINAL_CONTAINMENT_UNAVAILABLE' || error?.code?.startsWith('PROVIDER_EXECUTABLE_')) throw error;
+    throw Object.assign(new Error(`cannot prepare provider state directory: ${error.message}`), { code: 'TERMINAL_CONTAINMENT_UNAVAILABLE' });
+  }
+  const writableScopeDescriptors = pinnedWriteScopes.entries.map((entry) => entry.descriptor);
+  const writableScopeArgs = pinnedWriteScopes.entries.flatMap((entry, index) => [
+    '--bind-fd', String(6 + controlPlaneDescriptors.length + index), entry.target,
+  ]);
+  const promptDescriptorNumber = 6 + controlPlaneDescriptors.length + writableScopeDescriptors.length;
+  const providerDescriptorNumber = promptDescriptorNumber + (promptRecord ? 1 : 0);
+  const supportingProviderDescriptorNumber = providerDescriptorNumber + 1;
+  const supportingProviderArgs = trustedSupportingProviders.flatMap((support, index) => [
+    '--ro-bind-fd', String(supportingProviderDescriptorNumber + index),
+    join(dirname(CONTAINED_PROVIDER_EXECUTABLE_PATH), basename(support.binding.executable_path)),
+  ]);
+  const maskedPathArgs = maskedChains
+    .filter((chain) => !pathContains('/tmp', chain.path))
+    .flatMap((chain) => ['--tmpfs', chain.path]);
+  const containmentArgs = [
+    '--die-with-parent', '--unshare-pid', '--unshare-ipc', '--unshare-cgroup-try',
+    '--ro-bind', '/', '/',
+    '--dev', '/dev', '--proc', '/proc',
+    '--tmpfs', '/run/user',
+    '--tmpfs', '/tmp',
+    ...readOnlyTmpPathEntries(),
+    ...maskedPathArgs,
+    ...hiddenInstallationAuthorityArgs(),
+    ...stateDirectoryArgs,
+    pinnedWriteScopes.fullProject ? '--bind-fd' : '--ro-bind-fd', '5', cwd,
+    ...controlPlaneArgs,
+    ...writableScopeArgs,
+    ...(promptRecord ? ['--ro-bind-fd', String(promptDescriptorNumber), CONTAINED_PROMPT_PATH] : []),
+    '--ro-bind-fd', String(providerDescriptorNumber), CONTAINED_PROVIDER_EXECUTABLE_PATH,
+    ...supportingProviderArgs,
+    '--chdir', cwd,
+    '--', CONTAINED_PROVIDER_EXECUTABLE_PATH, ...args,
+  ];
+  return Object.freeze({
+    kind: 'bubblewrap_pid_namespace_v1',
+    id: `bwrap:${terminalId}`,
+    command: '/proc/self/fd/3',
+    args: Object.freeze(containmentArgs),
+    inheritedDescriptors: Object.freeze([
+      trustedBubblewrap.descriptor, stateDirectoryDescriptor, projectChain.descriptors.at(-1),
+      ...controlPlaneDescriptors,
+      ...writableScopeDescriptors,
+      ...(promptRecord ? [promptRecord.descriptor] : []),
+      trustedProvider.descriptor,
+      ...trustedSupportingProviders.map((support) => support.descriptor),
+    ]),
+    pinnedProjectChain: projectChain,
+    maskedReadChains: Object.freeze(maskedChains),
+    pinnedWriteScopes,
+    projectReference: projectChain.reference,
+    projectIdentityDigest: projectChain.identity_digest,
+    trustedExecutable: trustedBubblewrap.executable,
+    trustedProviderExecutable: trustedProvider.executable,
+    trustedSupportingProviderExecutables: Object.freeze(trustedSupportingProviders.map((support) => support.executable)),
+    providerExecutableBinding: trustedProvider.binding,
+    providerExecutableDescriptor: trustedProvider.descriptor,
+    supportingProviderExecutableBindings: Object.freeze(trustedSupportingProviders.map((support) => support.binding)),
+    supportingProviderExecutableDescriptors: Object.freeze(trustedSupportingProviders.map((support) => support.descriptor)),
+    digest: sha256({
+      binary: BUBBLEWRAP_PATH,
+      binary_sha256: trustedBubblewrap.binaryDigest,
+      provider_executable: trustedProvider.binding,
+      supporting_provider_executables: trustedSupportingProviders.map((support) => support.binding),
+      args: containmentArgs.slice(0, -args.length - 1),
+    }),
+  });
+}
+
+function closeAuthorityContainment(containment) {
+  const descriptors = new Set([
+    ...(containment?.inheritedDescriptors ?? []),
+    ...(containment?.pinnedProjectChain?.descriptors ?? []),
+    ...(containment?.pinnedWriteScopes?.descriptors ?? []),
+  ]);
+  for (const descriptor of descriptors) {
+    try { closeSync(descriptor); } catch { /* preserve the primary spawn result */ }
+  }
+  for (const chain of containment?.maskedReadChains ?? []) closeDirectoryChain(chain);
+}
+
+function signalProcessTree(child, processGroupId, signal) {
+  if (Number.isInteger(processGroupId) && processGroupId > 0 && process.platform !== 'win32') {
+    try { process.kill(-processGroupId, signal); return true; }
+    catch (error) { if (error?.code !== 'ESRCH') throw error; return false; }
+  }
+  return child.kill(signal);
+}
+
+function processTreeIsRunning(childPid, processGroupId) {
+  const target = Number.isInteger(processGroupId) && processGroupId > 0 && process.platform !== 'win32'
+    ? -processGroupId
+    : childPid;
+  try { process.kill(target, 0); return true; }
+  catch (error) { if (error?.code === 'ESRCH') return false; throw error; }
+}
+
+function processTreeStopsAfterClose(childPid, processGroupId) {
+  for (let attempt = 0; attempt < 100; attempt += 1) {
+    if (!processTreeIsRunning(childPid, processGroupId)) return true;
+    Atomics.wait(PROCESS_TREE_SETTLE_WAIT, 0, 0, 5);
+  }
+  return false;
+}
+
+function terminalAuthorityReceipt(material) {
+  const signed = signHostAuthorityPayload(canonicalize(material), {
+    domain: TERMINAL_AUTHORITY_DOMAIN,
+  });
+  return Object.freeze(canonicalize({
+    ...material,
+    authority_id: signed.authority_id,
+    authority_signature: signed.signature,
+  }));
+}
+
+function parseRailExecutionAuthorityResult(stdout, launchNonce) {
+  const matches = [...stdout.matchAll(/<CHATI_RAIL_EXECUTION>\s*([\s\S]*?)\s*<\/CHATI_RAIL_EXECUTION>/g)];
+  if (matches.length !== 1) {
+    throw Object.assign(new Error('successful RAIL execution must return exactly one result envelope on stdout'), { code: 'RAIL_EXECUTION_OUTPUT_INVALID' });
+  }
+  let payload;
+  try { payload = JSON.parse(matches[0][1]); }
+  catch {
+    throw Object.assign(new Error('successful RAIL execution returned malformed result JSON'), { code: 'RAIL_EXECUTION_OUTPUT_INVALID' });
+  }
+  if (!payload || typeof payload !== 'object' || Array.isArray(payload)
+    || Object.keys(payload).sort().join(',') !== 'launch_nonce,result_commit_ref'
+    || !/^[a-f0-9]{40,64}$/.test(payload.result_commit_ref || '')
+    || !/^[A-Za-z0-9._-]{16,128}$/.test(payload.launch_nonce || '')) {
+    throw Object.assign(new Error('RAIL execution result must bind one full commit id to the exact launch nonce'), { code: 'RAIL_EXECUTION_OUTPUT_INVALID' });
+  }
+  if (payload.launch_nonce !== launchNonce) {
+    throw Object.assign(new Error('RAIL execution output does not echo the canonical launch nonce'), { code: 'RAIL_EXECUTION_LAUNCH_NONCE_MISMATCH' });
+  }
+  return Object.freeze({ result_commit_ref: payload.result_commit_ref });
+}
+
+/**
+ * Verifies a receipt minted by the persistent host terminal authority. The
+ * private key remains outside provider containment, while persisted receipts
+ * remain verifiable after a supervisor restart.
+ */
+export function verifyTerminalAuthorityReceipt(receipt, expected = {}) {
+  if (!receipt || typeof receipt !== 'object' || Array.isArray(receipt)
+    || typeof receipt.authority_id !== 'string'
+    || typeof receipt.authority_signature !== 'string') return false;
+  const { authority_signature, authority_id, ...material } = receipt;
+  if (!verifyHostAuthorityPayload(material, {
+    domain: TERMINAL_AUTHORITY_DOMAIN,
+    authorityId: authority_id,
+    signature: authority_signature,
+  })) return false;
+  return Object.entries(expected).every(([key, value]) => Object.hasOwn(material, key)
+    && sha256(material[key]) === sha256(value));
+}
+
+export function getTerminalLaunchAuthorityReceipt(handle) {
+  const state = TERMINAL_AUTHORITY_STATE.get(handle);
+  if (!state) throw Object.assign(new Error('terminal handle was not minted by spawnTerminal'), { code: 'UNTRUSTED_TERMINAL_HANDLE' });
+  return state.launchReceipt;
+}
+
+export function getTerminalCompletionAuthorityReceipt(handle) {
+  const state = TERMINAL_AUTHORITY_STATE.get(handle);
+  if (!state) throw Object.assign(new Error('terminal handle was not minted by spawnTerminal'), { code: 'UNTRUSTED_TERMINAL_HANDLE' });
+  const { runtime, identity } = state;
+  if (runtime.timeoutCleanupFailure) throw runtime.timeoutCleanupFailure;
+  if (runtime.timeoutCleanupPromise && !runtime.timeoutCleanupSettled) {
+    throw Object.assign(new Error('terminal timeout cleanup proof is still pending'), { code: 'TERMINAL_CLEANUP_PENDING' });
+  }
+  if (runtime.status === 'running' || !Number.isInteger(runtime.exitCode)) {
+    throw Object.assign(new Error('terminal completion receipt requires an exited process'), { code: 'TERMINAL_STILL_RUNNING' });
+  }
+  if (runtime.outputOverflow) {
+    throw Object.assign(new Error('terminal output exceeded the authority capture limit'), { code: 'TERMINAL_OUTPUT_OVERFLOW' });
+  }
+  if (!processTreeStopsAfterClose(runtime.child.pid, runtime.processGroupId)) {
+    try { signalProcessTree(runtime.child, runtime.processGroupId, 'SIGKILL'); } catch { /* fail closed below */ }
+    throw Object.assign(new Error('terminal process group remained active after the provider CLI exited'), { code: 'TERMINAL_PROCESS_GROUP_STILL_RUNNING' });
+  }
+  if (!state.completionReceipt) {
+    const stdout = runtime.stdout.join('');
+    let railResult = null;
+    let executionWorktreeProof = null;
+    let executionResultStatus = null;
+    let executionResultErrorCode = null;
+    if (state.context.authority_kind === 'rail_execution') {
+      if (runtime.exitCode === 0) {
+        try {
+          railResult = parseRailExecutionAuthorityResult(stdout, state.context.launch_nonce);
+          if (state.executionWorktreeBaseline) {
+            executionWorktreeProof = verifyRailExecutionWorktreeResult({
+              baseline: state.executionWorktreeBaseline,
+              resultCommitRef: railResult.result_commit_ref,
+            });
+          }
+          executionResultStatus = 'valid';
+        } catch (error) {
+          railResult = null;
+          executionWorktreeProof = null;
+          executionResultStatus = 'invalid_output';
+          executionResultErrorCode = error.code || 'RAIL_EXECUTION_OUTPUT_INVALID';
+        }
+      } else {
+        executionResultStatus = 'process_failed';
+      }
+    }
+    state.completionReceipt = terminalAuthorityReceipt({
+      schema_version: 1,
+      purpose: 'terminal_completion',
+      launch_receipt_digest: sha256(state.launchReceipt),
+      terminal_id: identity.terminal_id,
+      invocation_id: state.context.invocation_id,
+      launch_nonce: state.context.launch_nonce,
+      authority_kind: state.context.authority_kind,
+      provider_id: state.context.provider_id,
+      harness_id: identity.harness_id,
+      model_id: identity.model_id,
+      reasoning_configuration: identity.reasoning_configuration,
+      provider_executable_path: identity.provider_executable_path,
+      provider_executable_sha256: identity.provider_executable_sha256,
+      exit_status: runtime.exitCode,
+      stdout_digest: sha256(stdout),
+      stderr_digest: sha256(runtime.stderr.join('')),
+      ...(executionResultStatus ? { execution_result_status: executionResultStatus } : {}),
+      ...(executionResultErrorCode ? { execution_result_error_code: executionResultErrorCode } : {}),
+      ...(state.executionWorktreeBaseline ? {
+        execution_base_commit_ref: state.executionWorktreeBaseline.base_commit_ref,
+        execution_launch_head_ref: state.executionWorktreeBaseline.launch_head_ref,
+        execution_repository_identity_digest: state.executionWorktreeBaseline.repository_identity_digest,
+        execution_preexisting_commits_digest: state.executionWorktreeBaseline.preexisting_commits_digest,
+      } : {}),
+      ...(executionWorktreeProof ? {
+        execution_result_head_ref: executionWorktreeProof.result_head_ref,
+        execution_result_preexisted: executionWorktreeProof.result_preexisted,
+        execution_worktree_clean: executionWorktreeProof.worktree_clean,
+      } : {}),
+      ...(railResult || {}),
+      completed_at: runtime.completedAt,
+    });
+  }
+  return state.completionReceipt;
+}
+
+/** Wait for an authority terminal and propagate timeout cleanup proof failures. */
+export async function waitForTerminal(handle) {
+  const state = TERMINAL_AUTHORITY_STATE.get(handle);
+  if (!state) {
+    if (!handle?.process || handle.status !== 'running') return handle;
+    await new Promise((done) => {
+      handle.process.once('exit', done);
+      handle.process.once('error', done);
+    });
+    if (handle.timeoutCleanupFailure) throw handle.timeoutCleanupFailure;
+    return handle;
+  }
+  const { runtime } = state;
+  const outcome = await Promise.race([
+    runtime.exitPromise.then(() => Object.freeze({ kind: 'exit' })),
+    runtime.cleanupFailureSignal.then((error) => Object.freeze({ kind: 'cleanup_failure', error })),
+  ]);
+  if (outcome.kind === 'cleanup_failure') throw outcome.error;
+  if (runtime.timeoutCleanupPromise) {
+    const cleanup = await runtime.timeoutCleanupPromise;
+    if (!cleanup.ok) throw cleanup.error;
+  }
+  if (runtime.timeoutCleanupFailure) throw runtime.timeoutCleanupFailure;
+  return handle;
+}
 
 /**
  * Generate a unique terminal identifier.
@@ -99,6 +881,24 @@ export function cleanParentEnv(env) {
   return cleaned;
 }
 
+const AUTHORITY_PROVIDER_SECRET_PREFIXES = Object.freeze({
+  claude: Object.freeze(['ANTHROPIC_', 'CLAUDE_']),
+  codex: Object.freeze(['OPENAI_', 'CODEX_']),
+  grok: Object.freeze(['XAI_', 'GROK_']),
+});
+const AUTHORITY_SECRET_NAME = /(API[_-]?KEY|ACCESS[_-]?KEY|PRIVATE[_-]?KEY|PASSWORD|SECRET|TOKEN|CREDENTIAL|AUTH[_-]?SOCK)/i;
+
+export function cleanAuthorityEnv(env, provider) {
+  const allowedPrefixes = AUTHORITY_PROVIDER_SECRET_PREFIXES[provider] || [];
+  const cleaned = {};
+  for (const [key, value] of Object.entries(cleanParentEnv(env))) {
+    if (AUTHORITY_SECRET_NAME.test(key) && !allowedPrefixes.some((prefix) => key.startsWith(prefix))) continue;
+    cleaned[key] = value;
+  }
+  cleaned.PATH = AUTHORITY_SYSTEM_PATH;
+  return cleaned;
+}
+
 // ---------------------------------------------------------------------------
 // Public API
 // ---------------------------------------------------------------------------
@@ -112,11 +912,16 @@ export function cleanParentEnv(env) {
  * @property {string} [providerId]    - Vendor provider identifier (anthropic, openai, xai)
  * @property {string} [reasoningConfiguration] - Requested reasoning effort
  * @property {string} [catalogSnapshotRef] - Capability catalog snapshot used for routing
- * @property {string} [prompt]        - Full prompt string (from prompt-builder, piped via stdin)
+ * @property {{executable_path:string,executable_sha256:string}} [providerExecutableBinding] - Sealed native provider executable
+ * @property {string} [prompt]        - Full prompt string transported outside argv by the provider adapter
  * @property {object} [contextPayload] - Context to inject via env var
  * @property {string[]} [writeScope]   - Override write scope
  * @property {string} [workingDir]     - Working directory for the process
  * @property {number} [timeout]        - Max execution time in ms
+ * @property {function} [beforeProcessSpawn] - Read-only preparation after containment is pinned
+ * @property {function} [beforeAuthoritySpawn] - Final synchronous authority reservation before spawn
+ * @property {string[]} [maskedReadPaths] - Canonical host paths hidden from an authority provider
+ * @property {string} [auditProjectDir] - Canonical CHATI project used only for the host-side model audit
  */
 
 /**
@@ -140,7 +945,7 @@ export function cleanParentEnv(env) {
  * perform any I/O and is therefore fully testable in isolation.
  *
  * @param {SpawnConfig} config
- * @returns {{ command: string, args: string[], env: Record<string, string>, terminalId: string, prompt: string|null }}
+ * @returns {{ command: string, args: string[], env: Record<string, string>, terminalId: string, prompt: string|null, promptFile: string|null }}
  */
 export function buildSpawnCommand(config) {
   if (!config || typeof config !== 'object') {
@@ -157,9 +962,17 @@ export function buildSpawnCommand(config) {
     failure.code = 'PROVIDER_REQUIRED';
     throw failure;
   }
+  const readOnly = Array.isArray(config.writeScope) && config.writeScope.length === 0;
+  if (readOnly && !READ_ONLY_PROVIDERS.has(config.provider)) {
+    const failure = new Error(`Selected provider "${config.provider}" has no enforced read-only terminal mode`);
+    failure.code = 'READ_ONLY_PROVIDER_UNSUPPORTED';
+    throw failure;
+  }
 
   const terminalId = generateTerminalId(config.agent);
-  const isolationEnv = buildIsolationEnv(config.agent);
+  const isolationEnv = Array.isArray(config.writeScope)
+    ? { CHATI_WRITE_SCOPE: config.writeScope.join(','), CHATI_READ_SCOPE: '*' }
+    : buildIsolationEnv(config.agent);
 
   const env = {
     ...isolationEnv,
@@ -167,6 +980,7 @@ export function buildSpawnCommand(config) {
     CHATI_AGENT: config.agent,
     CHATI_TASK_ID: config.taskId,
     CHATI_SPAWNED: 'true',
+    ...(readOnly ? { CHATI_EXECUTION_MODE: 'read-only' } : {}),
     ...(config.reasoningConfiguration ? { CHATI_REASONING_CONFIGURATION: config.reasoningConfiguration } : {}),
   };
 
@@ -177,12 +991,16 @@ export function buildSpawnCommand(config) {
       process.stderr.write(`[chati] spawner context-serialize: ${err.message}\n`);
       env.CHATI_CONTEXT = '{}';
     }
+    for (const key of TEAM_CONTEXT_ENV_KEYS) {
+      const value = config.contextPayload[key];
+      if (typeof value === 'string' && value.trim() !== '') env[key] = value;
+    }
   }
 
   // Resolve the exact provider selected by the router. Never substitute a
   // different vendor when credentials, catalog data, or a CLI are missing.
   const providerName = config.provider;
-  let command, args, prompt;
+  let command, args, prompt, promptFile;
   const providerFallback = null;
   const actualProvider = providerName;
   let actualModel;
@@ -196,6 +1014,7 @@ export function buildSpawnCommand(config) {
     command = adapterResult.command;
     args = adapterResult.args;
     prompt = adapterResult.stdinPrompt;
+    promptFile = adapterResult.promptFile ?? null;
     actualModel = adapterResult.effectiveModel;
     actualReasoningConfiguration = adapterResult.effectiveReasoningConfiguration;
   } catch (err) {
@@ -205,7 +1024,7 @@ export function buildSpawnCommand(config) {
   }
 
   return {
-    command, args, env, terminalId, prompt, providerFallback,
+    command, args, env, terminalId, prompt, promptFile, providerFallback,
     actualProvider, actualModel, actualReasoningConfiguration,
   };
 }
@@ -218,100 +1037,394 @@ export function buildSpawnCommand(config) {
  */
 export function spawnTerminal(config) {
   const {
-    command, args, env, terminalId, prompt, providerFallback,
+    command, args, env, terminalId, prompt, promptFile, providerFallback,
     actualProvider, actualModel, actualReasoningConfiguration,
   } = buildSpawnCommand(config);
 
   const cwd = config.workingDir || process.cwd();
   const timeout = config.timeout || 300_000; // default 5 minutes
+  const authorityContext = config.authorityContext;
+  if (authorityContext !== undefined) {
+    for (const field of ['authority_kind', 'invocation_id', 'launch_nonce', 'provider_id']) {
+      if (typeof authorityContext?.[field] !== 'string' || authorityContext[field].trim() === '') {
+        throw Object.assign(new Error(`authorityContext.${field} is required`), { code: 'INVALID_TERMINAL_AUTHORITY_CONTEXT' });
+      }
+    }
+  }
 
-  const selectionRecord = recordModelSelection(cwd, {
-    agent: config.agent,
-    taskId: config.taskId,
-    provider: actualProvider,
-    providerId: config.providerId || null,
-    model: actualModel,
-    reasoningConfiguration: actualReasoningConfiguration,
-    catalogSnapshotRef: config.catalogSnapshotRef || null,
-  });
-  if (!selectionRecord.saved) {
-    const auditError = new Error(selectionRecord.error || 'Failed to persist model selection audit');
-    auditError.code = 'MODEL_SELECTION_AUDIT_FAILED';
-    throw auditError;
+  const readOnly = Array.isArray(config.writeScope) && config.writeScope.length === 0;
+  if (config.beforeProcessSpawn !== undefined && typeof config.beforeProcessSpawn !== 'function') {
+    throw Object.assign(new Error('beforeProcessSpawn must be a function'), { code: 'INVALID_TERMINAL_PRESPAWN_HOOK' });
+  }
+  if (config.beforeAuthoritySpawn !== undefined
+    && (authorityContext === undefined || typeof config.beforeAuthoritySpawn !== 'function')) {
+    throw Object.assign(new Error('beforeAuthoritySpawn requires an authority context and callback'), { code: 'INVALID_TERMINAL_PRESPAWN_HOOK' });
   }
 
-  const child = spawn(command, args, {
-    cwd,
-    env: { ...cleanParentEnv(process.env), ...env },
-    stdio: ['pipe', 'pipe', 'pipe'],
-  });
+  const detachedProcessGroup = authorityContext !== undefined && process.platform !== 'win32';
+  let promptRecord;
+  let containment;
+  let sealedProvider;
+  let executionWorktreeBaseline;
+  let spawnArgs = args;
+  let child;
+  try {
+    if (promptFile !== null) {
+      promptRecord = openPrivatePromptFile(promptFile);
+      spawnArgs = materializePrivatePromptArgs(args, authorityContext === undefined
+        ? '/proc/self/fd/3'
+        : CONTAINED_PROMPT_PATH);
+    }
+    containment = authorityContext === undefined ? null : buildAuthorityContainment({
+      args: spawnArgs, cwd: resolve(cwd), readOnly, terminalId, provider: actualProvider,
+      writeScope: config.writeScope, providerExecutableBinding: config.providerExecutableBinding, promptRecord,
+      maskedReadPaths: config.maskedReadPaths,
+    });
+    if (!containment && config.providerExecutableBinding !== undefined) {
+      if (process.platform !== 'linux') {
+        throw Object.assign(
+          new Error('sealed Planning provider execution requires Linux descriptor execution'),
+          { code: 'PROVIDER_EXECUTABLE_UNSUPPORTED' },
+        );
+      }
+      sealedProvider = openPinnedProviderExecutable(config.providerExecutableBinding, {
+        harnessId: actualProvider,
+        projectDir: cwd,
+      });
+    }
+    const auditProjectDir = config.auditProjectDir ? resolve(config.auditProjectDir) : null;
+    if (containment && auditProjectDir && auditProjectDir !== resolve(cwd)
+      && !(config.maskedReadPaths || []).map((entry) => realpathSync(resolve(entry))).includes(realpathSync(auditProjectDir))) {
+      throw Object.assign(new Error('external model audit project must be hidden from the authority provider'), { code: 'TERMINAL_CONTAINMENT_UNAVAILABLE' });
+    }
+    const selectionRecord = recordModelSelection(auditProjectDir ?? containment?.projectReference ?? cwd, {
+      agent: config.agent,
+      taskId: config.taskId,
+      provider: actualProvider,
+      providerId: config.providerId || null,
+      model: actualModel,
+      reasoningConfiguration: actualReasoningConfiguration,
+      catalogSnapshotRef: config.catalogSnapshotRef || null,
+    });
+    if (!selectionRecord.saved) {
+      const auditError = new Error(selectionRecord.error || 'Failed to persist model selection audit');
+      auditError.code = 'MODEL_SELECTION_AUDIT_FAILED';
+      throw auditError;
+    }
 
-  // Pipe prompt via stdin (avoids shell argument length limits)
+    if (authorityContext?.authority_kind === 'rail_execution'
+      && config.executionBaseCommitRef !== undefined) {
+      executionWorktreeBaseline = captureRailExecutionWorktree({
+        projectDir: cwd,
+        baseCommitRef: config.executionBaseCommitRef,
+      });
+    }
+
+    if (config.beforeProcessSpawn) config.beforeProcessSpawn();
+    if (containment) {
+      runTerminalSecurityTestHook('beforeAuthorityExecutableRevalidation', { containment });
+      currentBubblewrapTrust(containment.inheritedDescriptors[0]);
+      digestPinnedExecutable(containment.inheritedDescriptors[0], containment.trustedExecutable);
+      const providerExecutable = digestProviderExecutable(
+        containment.providerExecutableDescriptor,
+        containment.trustedProviderExecutable.snapshot,
+      );
+      if (providerExecutable.sha256 !== containment.providerExecutableBinding.executable_sha256) {
+        throw Object.assign(new Error('provider executable changed after installation binding validation'), { code: 'PROVIDER_EXECUTABLE_DRIFT' });
+      }
+      containment.supportingProviderExecutableDescriptors.forEach((descriptor, index) => {
+        const supportingExecutable = digestProviderExecutable(
+          descriptor, containment.trustedSupportingProviderExecutables[index].snapshot,
+        );
+        if (supportingExecutable.sha256 !== containment.supportingProviderExecutableBindings[index].executable_sha256) {
+          throw Object.assign(new Error('provider supporting executable changed after installation binding validation'), { code: 'PROVIDER_EXECUTABLE_DRIFT' });
+        }
+      });
+      assertPinnedDirectoryChain(containment.pinnedProjectChain);
+      for (const chain of containment.maskedReadChains) assertPinnedDirectoryChain(chain);
+      assertPinnedWriteScopes(containment.pinnedWriteScopes);
+    } else if (sealedProvider) {
+      const providerExecutable = digestProviderExecutable(
+        sealedProvider.descriptor,
+        sealedProvider.executable.snapshot,
+      );
+      if (providerExecutable.sha256 !== sealedProvider.binding.executable_sha256) {
+        throw Object.assign(new Error('provider executable changed after installation binding validation'), { code: 'PROVIDER_EXECUTABLE_DRIFT' });
+      }
+    }
+    if (executionWorktreeBaseline) {
+      executionWorktreeBaseline = assertRailExecutionWorktreeBaselineUnchanged(executionWorktreeBaseline);
+    }
+    if (config.beforeAuthoritySpawn) {
+      config.beforeAuthoritySpawn(Object.freeze({
+        working_dir: resolve(cwd),
+        project_identity_digest: containment.projectIdentityDigest,
+      }));
+    }
+    if (executionWorktreeBaseline) {
+      executionWorktreeBaseline = assertRailExecutionWorktreeBaselineUnchanged(executionWorktreeBaseline);
+    }
+    const sealedProviderDescriptorNumber = 3 + (promptRecord ? 1 : 0);
+    const spawnCommand = containment?.command
+      ?? (sealedProvider ? `/proc/self/fd/${sealedProviderDescriptorNumber}` : command);
+    child = spawn(spawnCommand, containment?.args ?? spawnArgs, {
+      cwd: containment ? '/' : cwd,
+      env: {
+        ...(containment ? cleanAuthorityEnv(process.env, actualProvider) : cleanParentEnv(process.env)), ...env,
+        ...(containment ? { TMPDIR: '/tmp', TMP: '/tmp', TEMP: '/tmp' } : {}),
+      },
+      stdio: containment
+        ? ['pipe', 'pipe', 'pipe', ...containment.inheritedDescriptors]
+        : [
+            'pipe', 'pipe', 'pipe',
+            ...(promptRecord ? [promptRecord.descriptor] : []),
+            ...(sealedProvider ? [sealedProvider.descriptor] : []),
+          ],
+      detached: detachedProcessGroup,
+    });
+    if (promptRecord) {
+      child.once('exit', () => cleanupPrivatePromptFile(promptRecord));
+      child.once('error', () => cleanupPrivatePromptFile(promptRecord));
+    }
+    if (containment) {
+      assertPinnedDirectoryChain(containment.pinnedProjectChain);
+    }
+  } catch (error) {
+    if (child?.pid) {
+      try { signalProcessTree(child, detachedProcessGroup ? child.pid : null, 'SIGKILL'); } catch { /* reservation remains fail-closed */ }
+    }
+    throw error;
+  } finally {
+    if (containment) closeAuthorityContainment(containment);
+    if (sealedProvider?.descriptor !== undefined) try { closeSync(sealedProvider.descriptor); } catch { /* child inherited its own descriptor */ }
+    if (promptRecord) try { closeSync(promptRecord.descriptor); } catch { /* containment already closed it */ }
+    if (promptRecord && !child) cleanupPrivatePromptFile(promptRecord);
+  }
+  const processGroupId = detachedProcessGroup ? child.pid : null;
+
+  // Stdin-capable adapters transport prompts here. File-capable adapters use
+  // the private descriptor prepared before spawn and leave stdin empty.
   if (prompt) {
     child.stdin.write(prompt);
   }
   child.stdin.end();
 
+  let resolveAuthorityExit;
+  let signalAuthorityCleanupFailure;
+  const runtime = authorityContext === undefined ? null : {
+    child,
+    processGroupId,
+    status: 'running',
+    exitCode: null,
+    stdout: [],
+    stderr: [],
+    stdoutBytes: 0,
+    stderrBytes: 0,
+    outputOverflow: false,
+    completedAt: null,
+    killRequested: false,
+    finalized: false,
+    exitPromise: new Promise((resolveExit) => { resolveAuthorityExit = resolveExit; }),
+    cleanupFailureSignal: new Promise((resolveFailure) => { signalAuthorityCleanupFailure = resolveFailure; }),
+    timeoutCleanupPromise: null,
+    timeoutCleanupSettled: false,
+    timeoutCleanupFailure: null,
+  };
+  const processFacade = runtime ? new EventEmitter() : child;
+  if (runtime) {
+    Object.defineProperties(processFacade, {
+      pid: { enumerable: true, get: () => child.pid },
+      killed: { enumerable: true, get: () => child.killed },
+    });
+    Object.defineProperty(processFacade, 'kill', {
+      enumerable: true,
+      value: (signal) => signalProcessTree(child, processGroupId, signal),
+    });
+  }
+
   /** @type {TerminalHandle} */
   const handle = {
     id: terminalId,
-    process: child,
+    process: processFacade,
     agent: config.agent,
     taskId: config.taskId,
     model: actualModel || config.model || 'provider-default',
     provider: actualProvider,
-    reasoningConfiguration: config.reasoningConfiguration || null,
+    reasoningConfiguration: actualReasoningConfiguration || null,
     providerFallback,
     startedAt: new Date().toISOString(),
-    status: 'running',
-    exitCode: null,
-    stdout: [],
-    stderr: [],
     timeout,
   };
 
+  if (runtime) {
+    Object.defineProperties(handle, {
+      status: { enumerable: true, configurable: false, get: () => runtime.status },
+      exitCode: { enumerable: true, configurable: false, get: () => runtime.exitCode },
+      stdout: { enumerable: true, configurable: false, get: () => Object.freeze([...runtime.stdout]) },
+      stderr: { enumerable: true, configurable: false, get: () => Object.freeze([...runtime.stderr]) },
+    });
+  } else {
+    Object.assign(handle, { status: 'running', exitCode: null, stdout: [], stderr: [] });
+  }
+
+  if (authorityContext !== undefined) {
+    const context = authorityContext;
+    const identity = Object.freeze({
+      terminal_id: terminalId,
+      harness_id: actualProvider,
+      model_id: actualModel,
+      reasoning_configuration: actualReasoningConfiguration,
+      provider_executable_path: containment.providerExecutableBinding.executable_path,
+      provider_executable_sha256: containment.providerExecutableBinding.executable_sha256,
+    });
+    const launchReceipt = terminalAuthorityReceipt({
+      schema_version: 1,
+      purpose: 'terminal_launch',
+      authority_kind: context.authority_kind,
+      invocation_id: context.invocation_id,
+      launch_nonce: context.launch_nonce,
+      terminal_id: terminalId,
+      process_pid: child.pid,
+      process_group_id: processGroupId,
+      process_hostname: hostname(),
+      process_containment_kind: containment.kind,
+      process_containment_id: containment.id,
+      process_containment_digest: containment.digest,
+      project_identity_digest: containment.projectIdentityDigest,
+      agent: config.agent,
+      task_id: config.taskId,
+      working_dir: resolve(cwd),
+      prompt_digest: sha256(config.prompt ?? ''),
+      provider_id: context.provider_id,
+      harness_id: actualProvider,
+      model_id: actualModel,
+      reasoning_configuration: actualReasoningConfiguration,
+      provider_executable_path: containment.providerExecutableBinding.executable_path,
+      provider_executable_sha256: containment.providerExecutableBinding.executable_sha256,
+      command_digest: sha256({
+        command: containment.providerExecutableBinding.executable_path,
+        command_sha256: containment.providerExecutableBinding.executable_sha256,
+        args,
+      }),
+      ...(executionWorktreeBaseline ? {
+        execution_base_commit_ref: executionWorktreeBaseline.base_commit_ref,
+        execution_launch_head_ref: executionWorktreeBaseline.launch_head_ref,
+        execution_repository_identity_digest: executionWorktreeBaseline.repository_identity_digest,
+        execution_preexisting_commits_digest: executionWorktreeBaseline.preexisting_commits_digest,
+        execution_worktree_clean: true,
+      } : {}),
+      started_at: handle.startedAt,
+    });
+    TERMINAL_AUTHORITY_STATE.set(handle, {
+      context: Object.freeze({ ...context }),
+      identity,
+      runtime,
+      executionWorktreeBaseline,
+      launchReceipt,
+      completionReceipt: null,
+    });
+  }
+
   // Record spawn in rate limiter for throttling
   const providerForRate = actualProvider;
   getRateLimiter(providerForRate).recordSpawn();
 
   // Capture output (capped at ~10MB to prevent unbounded memory growth)
   const MAX_BUFFER_CHUNKS = 10_000;
+  const MAX_AUTHORITY_OUTPUT_BYTES = 10 * 1024 * 1024;
+  const captureAuthorityOutput = (stream, chunk) => {
+    const key = stream === 'stdout' ? 'stdoutBytes' : 'stderrBytes';
+    const bytes = Buffer.byteLength(chunk);
+    if (runtime[key] + bytes > MAX_AUTHORITY_OUTPUT_BYTES) {
+      if (!runtime.outputOverflow) {
+        runtime.outputOverflow = true;
+        runtime.stderr.push(`terminal output exceeded ${MAX_AUTHORITY_OUTPUT_BYTES} byte authority limit`);
+        runtime.killRequested = true;
+        try { signalProcessTree(child, processGroupId, 'SIGKILL'); } catch { /* process already exited */ }
+      }
+      return;
+    }
+    runtime[key] += bytes;
+    runtime[stream].push(chunk);
+  };
   if (child.stdout) {
     child.stdout.on('data', (chunk) => {
-      if (handle.stdout.length < MAX_BUFFER_CHUNKS) {
-        handle.stdout.push(chunk.toString());
+      const text = chunk.toString();
+      if (runtime) { captureAuthorityOutput('stdout', text); return; }
+      const output = handle.stdout;
+      if (output.length < MAX_BUFFER_CHUNKS) {
+        output.push(text);
       }
     });
   }
   if (child.stderr) {
     child.stderr.on('data', (chunk) => {
-      if (handle.stderr.length < MAX_BUFFER_CHUNKS) {
-        handle.stderr.push(chunk.toString());
+      const text = chunk.toString();
+      if (runtime) { captureAuthorityOutput('stderr', text); return; }
+      const output = handle.stderr;
+      if (output.length < MAX_BUFFER_CHUNKS) {
+        output.push(text);
       }
     });
   }
 
-  child.on('exit', (code) => {
-    handle.status = 'exited';
-    handle.exitCode = code;
-  });
+  if (runtime) {
+    const finalize = (code, error = null) => {
+      if (runtime.finalized) return;
+      runtime.finalized = true;
+      runtime.status = runtime.killRequested ? 'killed' : 'exited';
+      runtime.exitCode = Number.isInteger(code) ? code : -1;
+      runtime.completedAt = new Date().toISOString();
+      if (error) runtime.stderr.push(`spawn error: ${error.message}`);
+      if (error && processFacade.listenerCount('error') > 0) processFacade.emit('error', error);
+      processFacade.emit('exit', runtime.exitCode);
+      processFacade.emit('close', runtime.exitCode);
+      resolveAuthorityExit(handle);
+    };
+    // `close` fires only after stdio has drained, so an authority receipt can
+    // never omit output that arrived after the OS process exited.
+    child.once('close', (code) => finalize(code));
+    child.once('error', (error) => finalize(-1, error));
+  } else {
+    child.on('exit', (code) => {
+      handle.status = 'exited';
+      handle.exitCode = code;
+    });
 
-  child.on('error', (err) => {
-    handle.status = 'exited';
-    handle.exitCode = -1;
-    handle.stderr.push(`spawn error: ${err.message}`);
-  });
+    child.on('error', (err) => {
+      handle.status = 'exited';
+      handle.exitCode = -1;
+      handle.stderr.push(`spawn error: ${err.message}`);
+    });
+  }
 
   // Enforce timeout — kill process if it exceeds max execution time
   const timeoutTimer = setTimeout(() => {
     if (handle.status === 'running') {
-      handle.stderr.push(`timeout: process exceeded ${timeout}ms limit`);
-      killTerminal(handle);
+      (runtime?.stderr ?? handle.stderr).push(`timeout: process exceeded ${timeout}ms limit`);
+      if (runtime) {
+        runtime.timeoutCleanupPromise = killTerminal(handle).then(
+          (result) => {
+            runtime.timeoutCleanupSettled = true;
+            return Object.freeze({ ok: true, result });
+          },
+          (error) => {
+            runtime.timeoutCleanupSettled = true;
+            runtime.timeoutCleanupFailure = error;
+            signalAuthorityCleanupFailure(error);
+            return Object.freeze({ ok: false, error });
+          },
+        );
+      } else {
+        void killTerminal(handle).catch((error) => {
+          handle.timeoutCleanupFailure = error;
+        });
+      }
     }
   }, timeout);
 
   // Clear timer when process exits normally
-  child.on('exit', () => clearTimeout(timeoutTimer));
+  child.on('close', () => clearTimeout(timeoutTimer));
 
   return handle;
 }
@@ -411,16 +1524,7 @@ export async function spawnParallelGroupAsync(configs, options = {}) {
    * when the terminal's process emits 'exit'.
    */
   function waitForExit(handle) {
-    if (handle.status !== 'running') {
-      return Promise.resolve();
-    }
-    return new Promise(resolve => {
-      if (!handle.process) {
-        resolve();
-        return;
-      }
-      handle.process.once('exit', () => resolve());
-    });
+    return waitForTerminal(handle).then(() => undefined);
   }
 
   // Fill initial pool
@@ -468,14 +1572,58 @@ export function killTerminal(handle) {
     return Promise.resolve({ killed: false, exitCode: handle?.exitCode ?? null });
   }
 
-  if (handle.status === 'exited') {
+  const authorityState = TERMINAL_AUTHORITY_STATE.get(handle);
+  const rawProcess = authorityState?.runtime?.child ?? handle.process;
+  const processGroupId = authorityState?.runtime?.processGroupId ?? null;
+  if (authorityState) {
+    authorityState.runtime.killRequested = true;
+    return (async () => {
+      runTerminalSecurityTestHook('beforeAuthorityProcessTreeObservation', { handle });
+      let active;
+      try { active = processTreeIsRunning(rawProcess.pid, processGroupId); }
+      catch (error) {
+        throw Object.assign(new Error(`cannot observe the contained provider process tree: ${error.message}`), { code: 'TERMINAL_PROCESS_TREE_UNRESOLVED' });
+      }
+      if (!active) return { killed: false, exitCode: handle.exitCode };
+      try { signalProcessTree(rawProcess, processGroupId, 'SIGTERM'); }
+      catch { /* the containment may have exited between observation and signal */ }
+      const waitForStop = async (attempts) => {
+        for (let attempt = 0; attempt < attempts; attempt += 1) {
+          try { if (!processTreeIsRunning(rawProcess.pid, processGroupId)) return true; }
+          catch (error) {
+            throw Object.assign(new Error(`cannot observe the contained provider process tree: ${error.message}`), { code: 'TERMINAL_PROCESS_TREE_UNRESOLVED' });
+          }
+          await new Promise((done) => setTimeout(done, 25));
+        }
+        return false;
+      };
+      if (!(await waitForStop(200))) {
+        try { signalProcessTree(rawProcess, processGroupId, 'SIGKILL'); }
+        catch { /* the containment may have exited between observation and signal */ }
+        if (!(await waitForStop(200))) {
+          throw Object.assign(new Error('contained provider process tree survived SIGKILL'), { code: 'TERMINAL_PROCESS_TREE_STILL_RUNNING' });
+        }
+      }
+      for (let attempt = 0; attempt < 80 && handle.status === 'running'; attempt += 1) {
+        await new Promise((done) => setTimeout(done, 25));
+      }
+      return { killed: true, exitCode: handle.exitCode };
+    })();
+  }
+  if (handle.status === 'exited' || handle.status === 'killed') {
     return Promise.resolve({ killed: false, exitCode: handle.exitCode });
   }
 
   return new Promise((resolve) => {
+    let settled = false;
+    const settle = (result) => {
+      if (settled) return;
+      settled = true;
+      resolve(result);
+    };
     const forceKillTimer = setTimeout(() => {
       try {
-        handle.process.kill('SIGKILL');
+        signalProcessTree(rawProcess, processGroupId, 'SIGKILL');
       } catch { /* expected: process may already be dead */
         // already dead -- ignore
       }
@@ -483,17 +1631,24 @@ export function killTerminal(handle) {
 
     handle.process.once('exit', (code) => {
       clearTimeout(forceKillTimer);
-      handle.status = 'killed';
-      handle.exitCode = code;
-      resolve({ killed: true, exitCode: code });
+      if (!authorityState) {
+        handle.status = 'killed';
+        handle.exitCode = code;
+      }
+      try {
+        if (processTreeIsRunning(rawProcess.pid, processGroupId)) {
+          signalProcessTree(rawProcess, processGroupId, 'SIGKILL');
+        }
+      } catch { /* completion authority remains fail-closed if the tree cannot be observed */ }
+      settle({ killed: true, exitCode: code });
     });
 
     try {
-      handle.process.kill('SIGTERM');
+      signalProcessTree(rawProcess, processGroupId, 'SIGTERM');
     } catch { /* expected: process may already be dead */
       clearTimeout(forceKillTimer);
-      handle.status = 'killed';
-      resolve({ killed: false, exitCode: handle.exitCode });
+      if (!authorityState) handle.status = 'killed';
+      settle({ killed: false, exitCode: handle.exitCode });
     }
   });
 }
@@ -554,7 +1709,8 @@ export async function spawnTerminalWithRetry(config, retryOptions = {}) {
   const maxRetries = retryOptions.maxRetries ?? 2;
   const baseDelay = retryOptions.baseDelay ?? 2000;
   const shouldRetry = retryOptions.shouldRetry || isTransientFailure;
-  const enableModelFallback = retryOptions.enableModelFallback ?? true;
+  // Model substitution is authority-sensitive and therefore opt-in only.
+  const enableModelFallback = retryOptions.enableModelFallback === true;
 
   let lastHandle = null;
 
@@ -563,11 +1719,7 @@ export async function spawnTerminalWithRetry(config, retryOptions = {}) {
     lastHandle = handle;
 
     // Wait for process to exit
-    await new Promise((resolve) => {
-      if (!handle.process) { resolve(); return; }
-      if (handle.status !== 'running') { resolve(); return; }
-      handle.process.once('exit', () => resolve());
-    });
+    await waitForTerminal(handle);
 
     // Success — return immediately
     if (handle.exitCode === 0) {
@@ -597,11 +1749,7 @@ export async function spawnTerminalWithRetry(config, retryOptions = {}) {
       const fallbackConfig = { ...config, model: fallbackModel };
       const fallbackHandle = spawnTerminal(fallbackConfig);
 
-      await new Promise((resolve) => {
-        if (!fallbackHandle.process) { resolve(); return; }
-        if (fallbackHandle.status !== 'running') { resolve(); return; }
-        fallbackHandle.process.once('exit', () => resolve());
-      });
+      await waitForTerminal(fallbackHandle);
 
       // Record fallback metadata
       fallbackHandle.modelFallback = {