沙箱与进程树

135  resolve(request: SandboxPolicyRequest = {}): SandboxExecutionPolicy {136    const { session } = request137    return {138      mode: request.mode ?? (session === undefined ? undefined : this.overrideOf(session)) ?? this.defaultMode,139      workspaceRoot: resolveWorkspaceRoot(session?.header.cwd ?? this.workspaceRoot),⋯      ...session === undefined ? {} : { sessionId: session.id },141    }142  }

29export type SandboxMode = 'read-only' | 'workspace-write' | 'danger-full-access'

23Only the first two modes can be sent to a provider. A `danger-full-access` consumer spawns its original argv and does not call `ctx.sandbox`.

30Enforcement is a reported fact. `full` means the backend governs every file effect promised by the mode; `partial` means an active backend or older kernel ABI governs only a subset, so consumers that require the absolute promise must reject or surface that distinction. Older Landlock ABIs and the Windows ACL runner's Everyone/hard-link boundaries are current partial cases.

152/**153 * Abstract process-sandbox service. {@link confine} must return enforcing argv154 * or fail closed at wrap or runner-execution time; silent unconfined passthrough155 * is forbidden. Functional probes arbitrate multi-runner chains and may be156 * skipped for a sole candidate, whose own refusal remains the fail-closed end.157 */158export abstract class SandboxProvider extends Service {159  /* v8 ignore next -- abstract service construction is covered through concrete provider packages. */160  constructor(ctx: Context) {161    super(ctx, 'sandbox')162  }163164  /**165   * Wrap `argv` so it executes confined under `policy` on this host; the166   * caller spawns the returned argv in place of its own.167   * @param argv - the exact argv the caller is about to spawn (program plus168   *   arguments), NOT a shell string — a shell-shaped consumer passes169   *   `['bash', '-c', command]`.170   * @param policy - the file-effect policy this execution runs under,171   *   carried per call (see {@link SandboxPolicy}).172   * @returns the argv to spawn instead, plus the enforcement completeness173   *   the selected backend achieves for it.174   */175  abstract confine(argv: readonly string[], policy: SandboxPolicy): ConfinedArgv176}

159const PLATFORM_CHAINS: Record<string, readonly SelectedRunner['runner'][]> = {160  linux: ['bwrap', 'landlock'],161  darwin: ['seatbelt'],162  // The Windows restricted-token runner (@deepseek-ai/dsh-sandbox-windows-acl):163  // a sole candidate, selected without a probe — its execution-time refusal164  // fails closed through its stderr signature (windows-acl-run:) and exit 127.165  win32: ['windows-acl'],166}

492  private selectRunner(mode: ConfinedSandboxMode): SelectedRunner {493    this.selectedRunner ??= this.chainVerdict()494    if (this.selectedRunner === 'unavailable') throw new SandboxUnavailableError(mode)495    return this.selectedRunner496  }497498  /** Walk this platform's chain: sole candidate unprobed, several probed in order, none usable → unavailable. */499  private chainVerdict(): SelectedRunner | 'unavailable' {500    const chain = this.internals.chain ?? PLATFORM_CHAINS[this.internals.platform ?? process.platform] ?? []501    const [first, ...rest] = chain502    if (first === undefined) return 'unavailable'503    // A sole candidate needs no arbitration; its execution-time refusal still fails closed.504    if (rest.length === 0) return { runner: first, enforcement: STATIC_ENFORCEMENT[first] }505    for (const runner of chain) {506      const enforcement = this.probeRunner(runner)507      if (enforcement !== 'unusable') return { runner, enforcement }508    }509    return 'unavailable'510  }

131export class SandboxUnavailableError extends HarnessError {132  constructor(mode: ConfinedSandboxMode, detail?: string) {133    super(134      `sandbox mode "${mode}" is requested but no sandbox backend is usable on this host; `135      + 'refusing to run the command unconfined. Install bubblewrap or run a Landlock-enforcing '136      + 'kernel (Linux), ensure sandbox-exec is usable (macOS), or ensure the ACL '137      + 'restricted-token runner can start (Windows) — otherwise switch the consumer to '138      + 'danger-full-access.'139      + (detail === undefined ? '' : ` Runner failure: ${detail}`),140      SANDBOX_UNAVAILABLE,141    )142    this.name = 'SandboxUnavailableError'143  }144}

16export function bwrapProfileArgs(policy: SandboxPolicy): string[] {17  const args = ['--ro-bind', '/', '/', '--dev', '/dev', '--unshare-pid', '--proc', '/proc', '--die-with-parent']18  if (policy.mode === 'workspace-write') {19    args.push('--tmpfs', '/tmp')20    args.push('--bind', policy.workspaceRoot, policy.workspaceRoot)21  }22  return args23}

230static int restrict_self(const struct cli *cli, int *partial) {231  long abi = syscall(__NR_landlock_create_ruleset, NULL, 0, LANDLOCK_CREATE_RULESET_VERSION);232  if (abi < 0) {233    /* ENOSYS: kernel built without Landlock; EOPNOTSUPP: built but disabled.234     * Either way: not enforceable — fail CLOSED, never exec unconfined. */235    return fail(NOT_ENFORCED_MESSAGE, NULL);236  }237  *partial = abi < MAX_ABI;238  uint64_t handled = fs_mask_for_abi(abi < MAX_ABI ? abi : MAX_ABI);239240  struct landlock_ruleset_attr attr = { .handled_access_fs = handled };241  int ruleset_fd = (int)syscall(__NR_landlock_create_ruleset, &attr, sizeof attr, 0);242  if (ruleset_fd < 0) return fail("landlock ruleset error", strerror(errno));243244  const uint64_t read_side = LL_FS_EXECUTE | LL_FS_READ_FILE | LL_FS_READ_DIR;245  for (size_t i = 0; i < cli->ro_count; i++) {246    int code = add_rule(ruleset_fd, cli->ro[i], read_side & handled);247    if (code != 0) return code;248  }249  for (size_t i = 0; i < cli->rw_count; i++) {250    int code = add_rule(ruleset_fd, cli->rw[i], handled);251    if (code != 0) return code;252  }253254  if (prctl(PR_SET_NO_NEW_PRIVS, 1, 0, 0, 0) != 0) {255    return fail("landlock ruleset error", strerror(errno));256  }257  if (syscall(__NR_landlock_restrict_self, ruleset_fd, 0) != 0) {258    return fail("landlock ruleset error", strerror(errno));259  }260  close(ruleset_fd);261  return 0;262}

30 * Plain C11 over the raw Landlock UAPI — no libraries beyond libc (musl,31 * linked statically), so the whole audit surface is this file plus the32 * kernel's stable syscall contract. Built natively per architecture by33 * `scripts/build.ts` into the per-platform npm packages34 * (`@deepseek-ai/node-addon-landlock-run-linux-{x64,arm64}`); the argv grammar,35 * exit codes, and report lines are pinned in `docs/cli-contract.md`.36 */

264int main(int argc, char **argv) {265  struct cli cli = { 0 };266  int code = parse(argc, argv, &cli);267  if (code != 0) return code;268269  if (cli.probe) {270    /* The functional probe: build and enforce a maximal ruleset in THIS271     * short-lived process (the probe run exits right after). `--version`272     * style checks would miss a kernel that has the syscalls but refuses273     * enforcement; actually restricting is the only honest signal. The one274     * report line is part of the launcher CLI contract — the executor reads275     * enforcement completeness from it. */276    static const char *probe_root = "/";277    struct cli probe = { .ro = &probe_root, .ro_count = 1 };278    int partial = 0;279    code = restrict_self(&probe, &partial);280    if (code != 0) return code;281    printf("landlock: %s\n", partial ? "partially enforced (older ABI)" : "fully enforced");282    return 0;283  }284285  int partial = 0;286  code = restrict_self(&cli, &partial);287  if (code != 0) return code;288  if (partial) {289    /* Older ABI: some handled accesses are not governed (e.g. truncate290     * before ABI 3). Still confined for everything the kernel supports —291     * report, do not refuse. */292    fprintf(stderr, "landlock-run: partial enforcement (older Landlock ABI)\n");293  }294295  execvp(cli.command[0], cli.command);296  /* exec only returns on failure. */297  return fail("exec failed", strerror(errno));298}

94export function grantArgs(grants: LauncherGrants): string[] {95  return [⋯    ...(grants.readOnly ?? []).flatMap(root => ['--ro', root]),⋯    ...(grants.readWrite ?? []).flatMap(root => ['--rw', root]),98  ]99}

167export interface SubprocessHandle {168  /** Process id (tree root); -1 when the spawn itself failed. */169  readonly pid: number170  /** The child's stdin, present iff spawned with `stdin: 'pipe'`. */171  readonly stdin: Writable | undefined172  /** The child's raw stdout, present iff spawned with `stdout: 'pipe'`. */173  readonly stdout: Readable | undefined174  /** The child's raw stderr, present iff spawned with `stderr: 'pipe'`. */175  readonly stderr: Readable | undefined176  /** Offset-based readers for collect-mode streams (also readable after exit). */177  readonly collected: SubprocessCollectedOutputs178  /** Resolves at process close with exit facts; rejects only for spawn-level failures. */179  readonly done: Promise<SubprocessOutcome>180  /**181   * Begin the SIGTERM → `graceMs` → SIGKILL escalation on the process tree182   * (Windows force-terminates immediately) — the seam's only termination183   * verb. Idempotent, a no-op once the tree is gone (the pid may be reused),184   * and also triggered by the spec's abort signal.185   */186  terminate(): void187  /**188   * Wait until the process tree has exited — the tree, not just the direct189   * child, so a still-running helper is observable before teardown returns.190   * @param signal - optional bound for the wait.191   * @returns `true` when the tree exited, `false` when the signal aborted first.192   */193  waitForExit(signal?: AbortSignal): Promise<boolean>194}

439  const terminate = (): void => {440    if (treeExitObserved || graceTimer !== undefined) return441    // Observe from the first termination tier onward, even when inherited442    // pipes delay `done` and no consumer has begun its own teardown wait.443    void observeTreeExit()444    // oxlint-disable-next-line typescript/no-unnecessary-condition -- observer can record absence before its first await.445    if (treeExitObserved) return446    kill('SIGTERM')447    // The escalation must survive direct-child settlement — the leader dying448    // does not mean the tree died — so settle does not clear this timer, and449    // kill() re-probes tree liveness before force-killing. It stays ref'd:450    // the pending SIGKILL is a commitment, and a parent exiting before it451    // fires would orphan a trapped survivor. Self-bounds at graceMs.452    graceTimer = setTimeout(() => { kill('SIGKILL') }, spec.graceMs)453  }

99export function linuxProcessGroupHasLiveMembers(100  processGroupId: number,101  internals: ProcessInspectorInternals = DEFAULT_INTERNALS,102): boolean | undefined {103  let entries: string[]104  try {105    entries = internals.readDir('/proc')106  } catch (_unreadableProcDirectory) {107    return undefined108  }109  let matched = false110  for (const entry of entries) {111    if (!/^\d+$/.test(entry)) continue112    const stat = readLinuxStat(internals, Number(entry))113    if (stat?.pgrp !== processGroupId) continue114    matched = true115    if (!/^[ZXx]$/.test(stat.state)) return true116  }117  return matched ? false : undefined118}

79  private async disposeManagedProcesses(): Promise<void> {80    // Terminate (escalating), then await WHOLE-TREE exit — not just the81    // direct child's settlement — so even a TERM-trapping descendant cannot82    // outlive the fiber. Keep both sets authoritative while these waits are83    // pending so a shorter process-level exit bound can still force-kill them.84    const pending: Promise<unknown>[] = []85    for (const handle of this.live) {86      handle.terminate()87      // Spawn-failure rejections already settled and left the live set.88      pending.push(handle.done.catch(() => {}).then(() => handle.waitForExit()))89    }90    for (const terminal of this.terminals) {91      pending.push(terminal.terminate())92    }93    const outcomes = await Promise.allSettled(pending)94    const failures = outcomes.flatMap<unknown>(outcome => outcome.status === 'rejected'95      ? [outcome.reason as unknown]96      : [])97    if (failures.length > 0) this.terminateForHostExit()98    this.live.clear()99    this.terminals.clear()100    if (failures.length === 1) throw failures[0]101    if (failures.length > 1) throw new AggregateError(failures, 'local subprocess teardown failed')102  }

108    ctx.effect(() => async () => {109      this.disposed = true110      let sandbox: Sandbox111      try {112        sandbox = await this.ready113      } catch (_sandboxSetupFailure) {114        // open() either acquired no sandbox or already made the POC's one rollback attempt.115        return116      }117      try {118        await sandbox.kill()119      } catch (error: unknown) {120        if (!(error instanceof SandboxNotFoundError)) throw error121      }122    }, 'e2b sandbox teardown')123  }

81export async function signalRemoteGroups(82  sandbox: Sandbox,83  envs: Record<string, string>,84  groups: readonly number[],85  signal: 'TERM' | 'KILL',86): Promise<void> {87  // TODO(e2b-pgid-identity): Prefer an atomic identity-bound group signal if E2B adds one;88  // a userspace identity precheck cannot close the numeric-PGID reuse race.89  try {90    await sandbox.commands.run(91      `kill -${signal} -- ${groups.map(group => `-${group}`).join(' ')}`,92      commandOpts(envs),93    )94  } catch (error: unknown) {95    if (!(error instanceof CommandExitError) && !(error instanceof SandboxNotFoundError)) throw error96  }97}

15This boundary does not move the harness process, Cordis objects, model calls, agent/session state, session persistence, skills, higher-level protocol state, or E2B SDK buffers. The [portable execution-world decision](../../.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md) owns both the generic composition and this POC boundary.

48- Fixed the Linux sandbox making a nonexistent `.git/config.worktree` unreadable, which broke every sandboxed git command in repos with `extensions.worktreeConfig` set

124- Sandbox: on macOS, wildcard read-deny rules (e.g. `**/.env`) now take precedence inside allowed read regions, cover matched directories' contents, and can't be bypassed by renaming the denied file

1{2  "allowManagedPermissionRulesOnly": true,3  "sandbox": {4    "enabled": true,5    "autoAllowBashIfSandboxed": false,6    "allowUnsandboxedCommands": false,7    "excludedCommands": [],8    "network": {9      "allowUnixSockets": [],10      "allowAllUnixSockets": false,11      "allowLocalBinding": false,12      "allowedDomains": [],13      "httpProxyPort": null,14      "socksProxyPort": null15    },16    "enableWeakerNestedSandbox": false17  }18}

27- The `sandbox` property only applies to the `Bash` tool; it does not apply to other tools (like Read, Write, WebSearch, WebFetch, MCPs), hooks, or internal commands