chainlesschain 0.162.184 → 0.162.185

package/src/lib/process-execution-broker/linux-generic-bwrap-runtime.js

@@ -14,6 +14,7 @@ import { spawnSync as nativeSpawnSync } from "node:child_process";
 import {
   LINUX_GENERIC_BWRAP_BACKEND,
   LINUX_GENERIC_CONTRACT_KIND,
+  LINUX_GENERIC_PTY_LAUNCHER_PATH,
   planLinuxGenericBubblewrap,
 } from "./linux-generic-bwrap.js";
 
@@ -345,8 +346,12 @@ function parseMountInfo(runtime) {
     }
     const root = decodeMountInfoPath(fields[3]);
     const mountPoint = decodeMountInfoPath(fields[4]);
+    const optionalFields = fields.slice(6, separator);
     const fsType = fields[separator + 1];
     if (
+      !fields[5] ||
+      fields[5].includes("\0") ||
+      optionalFields.some((field) => !field || field.includes("\0")) ||
       !fsType ||
       fsType.includes("\0") ||
       fields.slice(separator + 1).some((field) => !field)
@@ -361,6 +366,7 @@ function parseMountInfo(runtime) {
         root,
         mountPoint,
         fsType,
+        optionalFields: Object.freeze(optionalFields),
         lineDigest: sha256(line),
       }),
     );
@@ -399,7 +405,75 @@ function sameDirectoryIdentity(left, right) {
   );
 }
 
-function workspaceMountTopology(runtime, workspaceRoot, workspaceIdentity) {
+function bindSourceMountTopology(entries, bindSources) {
+  const normalizedSources = bindSources
+    .map((source) => ({
+      kind: source.kind,
+      source: source.source,
+      recursive: source.recursive === true,
+    }))
+    .sort(
+      (left, right) =>
+        left.source.localeCompare(right.source) ||
+        left.kind.localeCompare(right.kind),
+    );
+  const sourceKeys = new Set();
+  for (const source of normalizedSources) {
+    if (
+      typeof source.kind !== "string" ||
+      !source.kind ||
+      typeof source.source !== "string" ||
+      !path.posix.isAbsolute(source.source) ||
+      path.posix.normalize(source.source) !== source.source
+    ) {
+      throw new Error("bind_source_mount_topology_invalid");
+    }
+    const key = `${source.kind}\0${source.source}`;
+    if (sourceKeys.has(key)) {
+      throw new Error("bind_source_mount_topology_duplicate");
+    }
+    sourceKeys.add(key);
+  }
+
+  let importedMountEntryCount = 0;
+  const sourceMountBindings = normalizedSources.map((source) => {
+    const mountedBy = containingMount(entries, source.source);
+    const importedMounts = new Map([[mountedBy.mountId, mountedBy]]);
+    if (source.recursive) {
+      for (const entry of entries) {
+        if (isWithin(source.source, entry.mountPoint)) {
+          importedMounts.set(entry.mountId, entry);
+        }
+      }
+    }
+    const imported = [...importedMounts.values()];
+    if (imported.some((entry) => entry.optionalFields.length !== 0)) {
+      throw new Error("bind_source_mount_propagation_not_private");
+    }
+    importedMountEntryCount += imported.length;
+    return {
+      ...source,
+      containingMount: mountedBy.lineDigest,
+      importedMountEntryDigests: imported
+        .map((entry) => entry.lineDigest)
+        .sort(),
+    };
+  });
+  return {
+    sourceMountSetDigest: sha256(stableJson(normalizedSources)),
+    sourceMountCount: normalizedSources.length,
+    importedMountEntryCount,
+    sourceMountBindings,
+    sourceMountPropagationPrivateAtAttestation: true,
+  };
+}
+
+function workspaceMountTopology(
+  runtime,
+  workspaceRoot,
+  workspaceIdentity,
+  bindSources,
+) {
   const entries = parseMountInfo(runtime);
   const descendants = entries.filter(
     (entry) =>
@@ -498,6 +572,7 @@ function workspaceMountTopology(runtime, workspaceRoot, workspaceIdentity) {
   const lineage = entries.filter((entry) =>
     isWithin(entry.mountPoint, workspaceRoot),
   );
+  const bindSourceTopology = bindSourceMountTopology(entries, bindSources);
   const binding = {
     version: MOUNT_TOPOLOGY_VERSION,
     source: "proc-self-mountinfo",
@@ -512,6 +587,7 @@ function workspaceMountTopology(runtime, workspaceRoot, workspaceIdentity) {
     forbiddenIdentityDigests: forbiddenIdentities
       .map((entry) => sha256(stableJson(entry)))
       .sort(),
+    ...bindSourceTopology,
     strictDescendantMountsAtAttestation: 0,
     recursiveBind: true,
     mountTopologyAtomic: false,
@@ -525,6 +601,11 @@ function workspaceMountTopology(runtime, workspaceRoot, workspaceIdentity) {
     filesystemEntryCount: binding.filesystemEntryDigests.length,
     aliasCount: binding.aliasDigests.length,
     forbiddenIdentityCount: binding.forbiddenIdentityDigests.length,
+    sourceMountSetDigest: binding.sourceMountSetDigest,
+    sourceMountCount: binding.sourceMountCount,
+    importedMountEntryCount: binding.importedMountEntryCount,
+    sourceMountPropagationPrivateAtAttestation:
+      binding.sourceMountPropagationPrivateAtAttestation,
     strictDescendantMountsAtAttestation:
       binding.strictDescendantMountsAtAttestation,
     rootAliasAttested: true,
@@ -697,10 +778,20 @@ function createTrustedResources(
     const cwdPins = openPair(contract.workingDirectory, {
       directory: true,
     });
-    const initialWorkspaceMountTopology = workspaceMountTopology(
+    // Fail before executing any helper when the writable recursive source is
+    // already propagation-capable. The complete exact source set is attested
+    // after the actual system and /etc descriptors have been acquired.
+    workspaceMountTopology(
       runtime,
       contract.workspaceRoot,
       workspace.identity,
+      [
+        {
+          kind: "workspace",
+          source: contract.workspaceRoot,
+          recursive: true,
+        },
+      ],
     );
 
     const supervisor = openPair(BWRAP_PATH, {
@@ -771,6 +862,76 @@ function createTrustedResources(
       throw error;
     }
 
+    let ptyLauncher = null;
+    let ptyLauncherBytes = 0;
+    let ptyLauncherDigest = null;
+    if (sandboxOpts?.pty === true) {
+      ptyLauncher = openPair(LINUX_GENERIC_PTY_LAUNCHER_PATH, {
+        directory: false,
+        rootRequired: true,
+        executable: true,
+      });
+      ptyLauncherBytes = Number(runtime.fs.fstatSync(ptyLauncher.probeFd).size);
+      const probeDigest = hashOpenFile(
+        runtime,
+        ptyLauncher.probeFd,
+        ptyLauncherBytes,
+      );
+      ptyLauncherDigest = hashOpenFile(
+        runtime,
+        ptyLauncher.finalFd,
+        ptyLauncherBytes,
+      );
+      if (probeDigest !== ptyLauncherDigest) {
+        throw new Error("pty_launcher_digest_mismatch");
+      }
+      ptyLauncher.identity = Object.freeze({
+        ...ptyLauncher.identity,
+        sha256: ptyLauncherDigest,
+        bytes: ptyLauncherBytes,
+      });
+
+      const launcherCapabilityFd = runtime.fs.openSync(
+        LINUX_GENERIC_PTY_LAUNCHER_PATH,
+        openFlags({ directory: false }),
+      );
+      ownedFds.add(launcherCapabilityFd);
+      const launcherCapabilityStat = runtime.fs.fstatSync(launcherCapabilityFd);
+      if (
+        !statMatchesIdentity(launcherCapabilityStat, ptyLauncher.identity, {
+          directory: false,
+        }) ||
+        hashOpenFile(runtime, launcherCapabilityFd, ptyLauncherBytes) !==
+          ptyLauncherDigest
+      ) {
+        throw new Error("pty_launcher_capability_reader_unattested");
+      }
+      const launcherCapabilityResult = runtime.spawnSync(
+        "/proc/self/fd/3",
+        ["--help"],
+        {
+          shell: false,
+          encoding: "utf8",
+          stdio: ["ignore", "pipe", "pipe", launcherCapabilityFd],
+          timeout: 10_000,
+          env: { PATH: "/usr/bin:/bin", LANG: "C", LC_ALL: "C" },
+        },
+      );
+      closeFd(launcherCapabilityFd);
+      const launcherHelp =
+        `${String(launcherCapabilityResult?.stdout || "")}\n` +
+        String(launcherCapabilityResult?.stderr || "");
+      if (
+        launcherCapabilityResult?.error ||
+        launcherCapabilityResult?.status !== 0 ||
+        !launcherHelp.split(/\s+/).includes("--ctty")
+      ) {
+        const error = new Error("pty_launcher_capability_probe_failed");
+        error.code = "LINUX_GENERIC_BWRAP_UNAVAILABLE";
+        throw error;
+      }
+    }
+
     const system = [];
     const systemSymlinks = [];
     for (const destination of SYSTEM_DESTINATIONS) {
@@ -824,6 +985,33 @@ function createTrustedResources(
         identity: pair.identity,
       });
     }
+    const sourceMountSources = Object.freeze([
+      Object.freeze({
+        kind: "workspace",
+        source: contract.workspaceRoot,
+        recursive: true,
+      }),
+      ...system.map((entry) =>
+        Object.freeze({
+          kind: "system",
+          source: entry.destination,
+          recursive: true,
+        }),
+      ),
+      ...etc.map((entry) =>
+        Object.freeze({
+          kind: "etc",
+          source: entry.destination,
+          recursive: false,
+        }),
+      ),
+    ]);
+    const initialWorkspaceMountTopology = workspaceMountTopology(
+      runtime,
+      contract.workspaceRoot,
+      workspace.identity,
+      sourceMountSources,
+    );
 
     const filter = buildNetworkSeccompFilter(runtime.arch);
     const openSeccomp = (phase) => {
@@ -969,6 +1157,7 @@ function createTrustedResources(
         issued.origin === (spawnOpts?.origin || "unknown") &&
         issued.command === command &&
         issued.sync === (sandboxOpts?.sync === true) &&
+        issued.pty === (sandboxOpts?.pty === true) &&
         issued.shell === false &&
         Array.isArray(stdio) &&
         issued.stdio.length === stdio.length &&
@@ -986,6 +1175,7 @@ function createTrustedResources(
           runtime,
           contract.workspaceRoot,
           workspace.identity,
+          sourceMountSources,
         );
       } catch {
         return false;
@@ -1001,6 +1191,14 @@ function createTrustedResources(
         !descriptorAttested(supervisor.finalFd, supervisor.identity, false) ||
         hashOpenFile(runtime, supervisor.finalFd, supervisorBytes) !==
           supervisorFinalDigest ||
+        (sandboxOpts?.pty === true &&
+          (!descriptorAttested(
+            ptyLauncher?.finalFd,
+            ptyLauncher?.identity,
+            false,
+          ) ||
+            hashOpenFile(runtime, ptyLauncher.finalFd, ptyLauncherBytes) !==
+              ptyLauncherDigest)) ||
         hashOpenFile(runtime, seccomp.finalFd, filter.buffer.length) !==
           filter.sha256
       ) {
@@ -1249,6 +1447,17 @@ function createTrustedResources(
         sha256: supervisorFinalDigest,
         bytes: supervisorBytes,
       },
+      ...(ptyLauncher
+        ? {
+            ptyLauncher: {
+              probeFd: ptyLauncher.probeFd,
+              finalFd: ptyLauncher.finalFd,
+              identity: ptyLauncher.identity,
+              sha256: ptyLauncherDigest,
+              bytes: ptyLauncherBytes,
+            },
+          }
+        : {}),
       workspace: {
         probeFd: workspace.probeFd,
         finalFd: workspace.finalFd,
@@ -1291,6 +1500,7 @@ export function applyLinuxGenericWorkspaceSandbox(
     cwd: spawnOpts?.cwd || process.cwd(),
     shell: spawnOpts?.shell,
     sync: sandboxOpts?.sync === true,
+    pty: sandboxOpts?.pty === true,
     stdio: spawnOpts?.stdio,
     requiredBoundaries,
   };

package/src/lib/process-execution-broker/linux-generic-bwrap.js

@@ -24,6 +24,7 @@ import path from "node:path";
 
 export const LINUX_GENERIC_BWRAP_BACKEND = "linux-bwrap-workspace";
 export const LINUX_GENERIC_CONTRACT_KIND = "strict-workspace-command";
+export const LINUX_GENERIC_PTY_LAUNCHER_PATH = "/usr/bin/setsid";
 
 const SUPPORTED_BOUNDARIES = new Set(["filesystem", "network"]);
 const SYSTEM_RUNTIME_DESTINATIONS = new Set([
@@ -97,6 +98,7 @@ const CONTRACT_VERSION = 1;
 const PLAN_VERSION = 1;
 const SANDBOX_HOME = "/home/sandbox";
 const SUPERVISOR_STAGING_PATH = "/run/.chainless-bwrap-supervisor";
+const PTY_LAUNCHER_STAGING_PATH = "/run/.chainless-pty-launcher";
 const SCRATCH_MOUNTS = ["/tmp", "/run", "/var/tmp", SANDBOX_HOME];
 
 const issuedContracts = new WeakMap();
@@ -194,6 +196,12 @@ function normalizeShell(shell) {
   throw new TypeError("strong Linux workspace sandbox requires shell:false");
 }
 
+function normalizePty(pty) {
+  if (pty === undefined || pty === null || pty === false) return false;
+  if (pty === true) return true;
+  throw new TypeError("strong Linux workspace sandbox requires pty:boolean");
+}
+
 function normalizeStdio(stdio) {
   let entries;
   if (stdio === undefined || stdio === null || stdio === "pipe") {
@@ -324,6 +332,10 @@ export function issueLinuxGenericSandboxExecutionContract(
   const args = normalizeArgs(spec?.args || []);
   const shell = normalizeShell(spec?.shell);
   const sync = spec?.sync === true;
+  const pty = normalizePty(spec?.pty);
+  if (pty && sync) {
+    throw new TypeError("strong Linux workspace PTY cannot be synchronous");
+  }
   const stdio = normalizeStdio(spec?.stdio);
   const requiredBoundaries = normalizeBoundaries(spec?.requiredBoundaries);
   if (
@@ -355,6 +367,7 @@ export function issueLinuxGenericSandboxExecutionContract(
     args,
     shell,
     sync,
+    pty,
     stdio,
     requiredBoundaries,
   };
@@ -383,11 +396,13 @@ function issuedBindingMatches(issued, provenance = {}) {
   let args;
   let boundaries;
   let shell;
+  let pty;
   let stdio;
   try {
     args = normalizeArgs(provenance.args || []);
     boundaries = normalizeBoundaries(provenance.requiredBoundaries);
     shell = normalizeShell(provenance.shell);
+    pty = normalizePty(provenance.pty);
     stdio = normalizeStdio(provenance.stdio);
   } catch {
     return false;
@@ -397,6 +412,7 @@ function issuedBindingMatches(issued, provenance = {}) {
     provenance.command === issued.command &&
     provenance.cwd === issued.workingDirectory &&
     provenance.sync === issued.sync &&
+    pty === issued.pty &&
     shell === issued.shell &&
     args.length === issued.args.length &&
     args.every((value, index) => value === issued.args[index]) &&
@@ -514,12 +530,23 @@ function validateWorkspaceMountTopology(value, issued) {
     !/^[a-f0-9]{64}$/.test(value.digest || "") ||
     !Number.isSafeInteger(value.lineageEntryCount) ||
     value.lineageEntryCount < 1 ||
+    value.lineageEntryCount > 4096 ||
     !Number.isSafeInteger(value.filesystemEntryCount) ||
     value.filesystemEntryCount < 1 ||
+    value.filesystemEntryCount > 16384 ||
     !Number.isSafeInteger(value.aliasCount) ||
-    value.aliasCount < 1 ||
+    value.aliasCount !== 1 ||
     !Number.isSafeInteger(value.forbiddenIdentityCount) ||
     value.forbiddenIdentityCount < 1 ||
+    value.forbiddenIdentityCount > 64 ||
+    !/^[a-f0-9]{64}$/.test(value.sourceMountSetDigest || "") ||
+    !Number.isSafeInteger(value.sourceMountCount) ||
+    value.sourceMountCount < 2 ||
+    value.sourceMountCount > 64 ||
+    !Number.isSafeInteger(value.importedMountEntryCount) ||
+    value.importedMountEntryCount < value.sourceMountCount ||
+    value.importedMountEntryCount > 65536 ||
+    value.sourceMountPropagationPrivateAtAttestation !== true ||
     value.strictDescendantMountsAtAttestation !== 0 ||
     value.rootAliasAttested !== true ||
     value.recursiveBind !== true ||
@@ -538,6 +565,11 @@ function validateWorkspaceMountTopology(value, issued) {
     filesystemEntryCount: value.filesystemEntryCount,
     aliasCount: value.aliasCount,
     forbiddenIdentityCount: value.forbiddenIdentityCount,
+    sourceMountSetDigest: value.sourceMountSetDigest,
+    sourceMountCount: value.sourceMountCount,
+    importedMountEntryCount: value.importedMountEntryCount,
+    sourceMountPropagationPrivateAtAttestation:
+      value.sourceMountPropagationPrivateAtAttestation,
     strictDescendantMountsAtAttestation:
       value.strictDescendantMountsAtAttestation,
     rootAliasAttested: value.rootAliasAttested,
@@ -579,6 +611,30 @@ function validateResourceContract(resources, issued) {
   ) {
     throw new Error("bubblewrap supervisor is not root-owned and pinned");
   }
+  let ptyLauncher = null;
+  if (issued.pty) {
+    if (
+      resources.ptyLauncher?.identity?.realPath !==
+        LINUX_GENERIC_PTY_LAUNCHER_PATH ||
+      !validateRootOwnedIdentity(resources.ptyLauncher?.identity, {
+        directory: false,
+      }) ||
+      !/^[a-f0-9]{64}$/.test(resources.ptyLauncher?.sha256 || "") ||
+      !Number.isSafeInteger(resources.ptyLauncher?.bytes) ||
+      resources.ptyLauncher.bytes <= 0 ||
+      !Number.isInteger(resources.ptyLauncher?.probeFd) ||
+      !Number.isInteger(resources.ptyLauncher?.finalFd)
+    ) {
+      throw new Error("PTY session launcher is not root-owned and pinned");
+    }
+    ptyLauncher = {
+      identity: resources.ptyLauncher.identity,
+      sha256: resources.ptyLauncher.sha256,
+      bytes: resources.ptyLauncher.bytes,
+    };
+  } else if (resources.ptyLauncher !== undefined) {
+    throw new Error("non-PTY launch supplied a PTY session launcher");
+  }
   const system = Array.isArray(resources.system) ? resources.system : [];
   if (!system.some((entry) => entry.destination === "/usr")) {
     throw new Error("root-owned /usr runtime mount is required");
@@ -657,6 +713,7 @@ function validateResourceContract(resources, issued) {
       sha256: resources.supervisor.sha256,
       bytes: resources.supervisor.bytes,
     },
+    ptyLauncher,
     system,
     symlinks,
     etc,
@@ -749,6 +806,15 @@ function directoryArguments(directoryDestinations, fileDestinations) {
 
 function descriptorLayout(stdio, resources, validated, workspaceRoot, phase) {
   const descriptors = [
+    ...(validated.ptyLauncher
+      ? [
+          {
+            kind: "ptyLauncher",
+            fd: resources.ptyLauncher[`${phase}Fd`],
+            destination: PTY_LAUNCHER_STAGING_PATH,
+          },
+        ]
+      : []),
     {
       kind: "supervisor",
       fd: resources.supervisor[`${phase}Fd`],
@@ -791,6 +857,7 @@ function descriptorLayout(stdio, resources, validated, workspaceRoot, phase) {
 function buildPolicyArgs({ issued, validated, descriptors, environment }) {
   const byKind = (kind) =>
     descriptors.filter((descriptor) => descriptor.kind === kind);
+  const ptyLauncher = byKind("ptyLauncher")[0] || null;
   const supervisor = byKind("supervisor")[0];
   const workspace = byKind("workspace")[0];
   const seccomp = byKind("seccomp")[0];
@@ -805,7 +872,7 @@ function buildPolicyArgs({ issued, validated, descriptors, environment }) {
   );
   const args = [
     "--die-with-parent",
-    "--new-session",
+    ...(issued.pty ? [] : ["--new-session"]),
     "--unshare-user",
     "--disable-userns",
     "--assert-userns-disabled",
@@ -824,6 +891,15 @@ function buildPolicyArgs({ issued, validated, descriptors, environment }) {
     args.push("--dir", directory);
   }
   args.push(
+    ...(ptyLauncher
+      ? [
+          "--perms",
+          "0000",
+          "--file",
+          String(ptyLauncher.childFd),
+          PTY_LAUNCHER_STAGING_PATH,
+        ]
+      : []),
     "--perms",
     "0000",
     "--file",
@@ -951,6 +1027,15 @@ function policyBinding({
         ? { identity: validated.target.identity }
         : {}),
     },
+    pty: issued.pty
+      ? {
+          mode: "dedicated-controlling-terminal",
+          launcher: validated.ptyLauncher,
+          launcherDescriptorBound: true,
+          launcherDescriptorConsumedBeforeTarget: true,
+          bwrapNewSession: false,
+        }
+      : { mode: "none" },
     requiredBoundaries: [...requiredBoundaries].sort(),
     environmentDigest: sha256(stableJson(environment)),
     policyArgs,
@@ -1067,6 +1152,7 @@ export function planLinuxGenericBubblewrap(
     cwd: "/",
     shell: false,
     encoding: "utf8",
+    timeout: 10_000,
     stdio: [
       ...issued.stdio.map((_, index) =>
         index === 1 || index === 2 ? "pipe" : "ignore",
@@ -1138,13 +1224,22 @@ export function planLinuxGenericBubblewrap(
   const supervisor = finalDescriptors.find(
     (entry) => entry.kind === "supervisor",
   );
-  const command = `/proc/self/fd/${supervisor.childFd}`;
-  const args = Object.freeze([
+  const ptyLauncher = finalDescriptors.find(
+    (entry) => entry.kind === "ptyLauncher",
+  );
+  const supervisorCommand = `/proc/self/fd/${supervisor.childFd}`;
+  const command = issued.pty
+    ? `/proc/self/fd/${ptyLauncher.childFd}`
+    : supervisorCommand;
+  const bwrapArgs = [
     ...policyArgs,
     "--",
     validated.target.resolvedCommand,
     ...validated.target.args,
-  ]);
+  ];
+  const args = Object.freeze(
+    issued.pty ? ["--ctty", supervisorCommand, ...bwrapArgs] : bwrapArgs,
+  );
   const options = Object.freeze({
     ...passthroughSpawnOptions(spawnOptions),
     cwd: "/",
@@ -1187,10 +1282,16 @@ export function planLinuxGenericBubblewrap(
       targetRuntime: "generic-command",
       contentSnapshot: false,
       handleAtomic: false,
+      // Every descriptor bind source is private at both attestations, which
+      // prevents ongoing host propagation after bwrap clones that topology.
+      // The final check is still not atomic with the subsequent native spawn.
       mountTopologyAtomic: false,
       contractDigest: issued.contractDigest,
       policyDigest,
       mountTopologyDigest: validated.workspaceMountTopology.digest,
+      sourceMountSetDigest:
+        validated.workspaceMountTopology.sourceMountSetDigest,
+      sourceMountPropagationPrivateAtAttestation: true,
       emptyRoot: true,
       undeclaredRootReadOnly: true,
       workspaceReadWrite: true,
@@ -1228,6 +1329,9 @@ export function planLinuxGenericBubblewrap(
         "no-strict-descendants-or-forbidden-root-aliases-at-attestation",
       mountTopologySource: validated.workspaceMountTopology.source,
       mountTopologyDigest: validated.workspaceMountTopology.digest,
+      sourceMountSetDigest:
+        validated.workspaceMountTopology.sourceMountSetDigest,
+      sourceMountPropagationPrivateAtAttestation: true,
       mountTopologyAtomic: false,
     }),
     networkPolicy: Object.freeze({
@@ -1235,6 +1339,19 @@ export function planLinuxGenericBubblewrap(
       namespaceIdentityChanged: true,
       seccomp: "deny-network-creation",
     }),
+    ptyPolicy: issued.pty
+      ? Object.freeze({
+          mode: "dedicated-controlling-terminal",
+          launcherPath: validated.ptyLauncher.identity.realPath,
+          launcherSha256: validated.ptyLauncher.sha256,
+          launcherBytes: validated.ptyLauncher.bytes,
+          launcherDescriptorBound: true,
+          launcherExecutablePinned: true,
+          launcherDescriptorConsumedBeforeTarget: true,
+          launcherStagingPathHidden: true,
+          bwrapNewSession: false,
+        })
+      : null,
     postSpawn: Object.freeze({ required: false, mode: "none" }),
     cleanup: finalCleanup,
   });
@@ -1248,7 +1365,8 @@ export function verifyLinuxGenericBubblewrapPlan(plan) {
     Object.isFrozen(plan) &&
     Object.isFrozen(plan.args) &&
     Object.isFrozen(plan.options) &&
-    Object.isFrozen(plan.options.stdio)
+    Object.isFrozen(plan.options.stdio) &&
+    (plan.ptyPolicy === null || Object.isFrozen(plan.ptyPolicy))
   );
 }
 

package/src/lib/process-execution-broker/platform-sandbox.js

@@ -321,6 +321,7 @@ function normalizeSandboxRequest(profileOrRequest, explicitRequest) {
     profile,
     requiredBoundaries,
     sync: request.sync === true,
+    pty: request.pty === true,
     executionContract:
       request.executionContract &&
       typeof request.executionContract === "object" &&
@@ -3040,7 +3041,7 @@ function validateLinuxPluginContract(
     return { ok: false, reason: "execution_contract_missing" };
   }
   if (
-    sync !== true ||
+    (sync !== true && sync !== false) ||
     spawnOpts?.shell !== false ||
     spawnOpts?.detached === true ||
     !linuxStdioIsNarrow(spawnOpts?.stdio) ||
@@ -4553,7 +4554,8 @@ function buildLinuxNetworkSeccompFilter(arch) {
     instructions.push([0x54, 0, 0, ~architecture.x32SyscallBit]);
   }
   instructions.push(
-    // No socket family is needed by this direct foreground Plugin Node route.
+    // No socket family is needed by this direct one-shot Plugin bin route,
+    // whether the Broker call is synchronous or asynchronously supervised.
     // Blocking creation rather than relying only on CLONE_NEWNET also closes
     // non-network-namespaced transports such as AF_VSOCK.
     [0x15, 0, 1, architecture.socketSyscall],
@@ -6179,6 +6181,7 @@ export function applyLinuxSandbox(
  *   profile?: string,
  *   requiredBoundaries?: string[],
  *   sync?: boolean,
+ *   pty?: boolean,
  *   executionContract?: Readonly<Object>|null
  * }|null} explicitRequest
  * @returns {ReturnType<typeof createSandboxPlan>}
@@ -6239,6 +6242,7 @@ export function applySandbox(
     profileName: profiles[profileName] ? profileName : "default",
     requiredBoundaries: sandboxRequest.requiredBoundaries,
     sync: sandboxRequest.sync,
+    pty: sandboxRequest.pty,
     executionContract: sandboxRequest.executionContract,
   };
 

package/src/repl/agent-repl.js

@@ -121,6 +121,7 @@ import {
   questionWithIdleTimeout,
 } from "./permission-prompt.js";
 import { describeAskContext, raceLocalAndRemote } from "./remote-approval.js";
+import { runWithHostHooksV2Workspace } from "../lib/hooks-v2-workspace-context.js";
 import {
   parsePermissionTier,
   parsePermissionModeArg,
@@ -477,6 +478,13 @@ export async function agentLoop(messages, options) {
  * Start the agentic REPL
  */
 export async function startAgentRepl(options = {}) {
+  const trustedWorkspaceRoot = process.cwd();
+  return runWithHostHooksV2Workspace(trustedWorkspaceRoot, () =>
+    startAgentReplInWorkspace(options),
+  );
+}
+
+async function startAgentReplInWorkspace(options = {}) {
   // EPIPE guard: if the REPL's stdout is piped and the consumer closes (e.g.
   // `cc agent | head`), the async stream `error` would otherwise crash the
   // process. Route a broken pipe into the REPL's own graceful shutdown (the