@fitlab-ai/agent-infra 0.9.5 → 0.9.6

package/lib/sandbox/control/server.ts

@@ -1,34 +1,39 @@
-import { spawnSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
 import { getProcessStartTime } from '../../server/process-state.ts';
-import { createTask } from '../../task/create-service.ts';
 import { assertGitWorktreeBinding } from '../../git/worktree-identity.ts';
 import {
-  bindSandboxControlTask,
-  validateSandboxControlRequest,
+  controlError,
+  SANDBOX_CONTROL_STATUS_INTERVAL_MS,
   type SandboxControlManifest,
+  type SandboxControlRequest,
   type SandboxControlResponse
 } from './protocol.ts';
+import { prepareSandboxControlExecution, type PreparedSandboxControlExecution, type SandboxControlExecutionResult } from './executor.ts';
+import {
+  appendSandboxControlAudit,
+  atomicWriteJson,
+  cleanupStaleSandboxControlLease,
+  executionPath,
+  readActiveLease,
+  readExecution,
+  terminateSandboxControlExecution,
+  writeSandboxControlStatus
+} from './state.ts';
+import { validateSandboxControlRequest } from './protocol.ts';
+import {
+  acquireSandboxControlBrokerStartup,
+  isSandboxControlRootQuiescing,
+  readSandboxControlManifest
+} from './lifecycle.ts';
 
-function readManifest(manifestPath: string): SandboxControlManifest {
-  const stat = fs.lstatSync(manifestPath);
-  if (!stat.isFile() || stat.isSymbolicLink()) throw new Error('SANDBOX_CONTROL_MANIFEST_INVALID');
-  const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8')) as SandboxControlManifest;
-  if (manifest.version !== 2) {
-    throw new Error('SANDBOX_CONTROL_MANIFEST_VERSION_INVALID: expected version 2; recreate the sandbox');
-  }
-  if (
-    typeof manifest.repoRoot !== 'string'
-    || typeof manifest.worktreeRoot !== 'string'
-    || typeof manifest.channelDir !== 'string'
-    || typeof manifest.token !== 'string'
-  ) throw new Error('SANDBOX_CONTROL_MANIFEST_INVALID');
-  if (path.resolve(manifest.channelDir) !== path.join(path.dirname(path.resolve(manifestPath)), 'channel')) {
-    throw new Error('SANDBOX_CONTROL_MANIFEST_INVALID');
-  }
-  return manifest;
-}
+type ActiveExecution = {
+  request: SandboxControlRequest;
+  prepared: PreparedSandboxControlExecution;
+  result: SandboxControlExecutionResult | null;
+  failure: unknown;
+  settled: boolean;
+};
 
 function assertRealDirectory(directory: string, parent?: string): void {
   const stat = fs.lstatSync(directory);
@@ -38,118 +43,242 @@ function assertRealDirectory(directory: string, parent?: string): void {
   }
 }
 
-function writeResponse(directory: string, response: SandboxControlResponse): void {
-  const temporary = path.join(directory, `.${response.id}.tmp`);
-  fs.writeFileSync(temporary, `${JSON.stringify(response)}\n`, { mode: 0o600, flag: 'wx' });
-  fs.renameSync(temporary, path.join(directory, `${response.id}.json`));
+function responsePath(manifest: SandboxControlManifest, id: string): string {
+  return path.join(manifest.channelDir, 'responses', `${id}.json`);
 }
 
-export function sandboxControlSafeEnv(env: NodeJS.ProcessEnv = process.env): NodeJS.ProcessEnv {
-  return Object.fromEntries(
-    Object.entries(env).filter(
-      ([key]) => !key.toUpperCase().startsWith('AGENT_INFRA_CONTROL_')
-    )
-  );
+function writeResponse(manifest: SandboxControlManifest, response: SandboxControlResponse): void {
+  atomicWriteJson(responsePath(manifest, response.id), response);
+}
+
+function rejected(id: string, error: unknown): SandboxControlResponse {
+  const detail = controlError(error);
+  return { version: 2, id, phase: 'rejected', exitCode: null, stdout: '', stderr: `${detail.message}\n`, error: detail };
+}
+
+function unknown(id: string): SandboxControlResponse {
+  const error = {
+    code: 'SANDBOX_CONTROL_RESULT_UNKNOWN',
+    message: 'SANDBOX_CONTROL_RESULT_UNKNOWN: accepted execution ended without a provable result; inspect domain state before retrying',
+    retryable: false
+  };
+  return { version: 2, id, phase: 'rejected', exitCode: null, stdout: '', stderr: `${error.message}\n`, error };
+}
+
+function notExecuted(id: string): SandboxControlResponse {
+  const error = {
+    code: 'SANDBOX_CONTROL_NOT_EXECUTED',
+    message: 'SANDBOX_CONTROL_NOT_EXECUTED: request was claimed but never accepted; retry with a new request id',
+    retryable: true
+  };
+  return { version: 2, id, phase: 'rejected', exitCode: null, stdout: '', stderr: `${error.message}\n`, error };
 }
 
 function consumeRequest(directory: string, id: string): void {
   try {
     fs.writeFileSync(path.join(directory, id), '', { flag: 'wx', mode: 0o600 });
   } catch (error) {
-    if ((error as NodeJS.ErrnoException).code === 'EEXIST') {
-      throw new Error('SANDBOX_CONTROL_REQUEST_REPLAYED');
-    }
+    if ((error as NodeJS.ErrnoException).code === 'EEXIST') throw new Error('SANDBOX_CONTROL_REQUEST_REPLAYED');
+    throw error;
+  }
+}
+
+function claimRequest(manifest: SandboxControlManifest, requestPath: string, id: string): string {
+  const directory = path.join(manifest.processingDir, id);
+  fs.mkdirSync(directory, { mode: 0o700 });
+  const claimed = path.join(directory, 'request.json');
+  try {
+    fs.renameSync(requestPath, claimed);
+    return claimed;
+  } catch (error) {
+    fs.rmSync(directory, { recursive: true, force: true });
     throw error;
   }
 }
 
-export function serveSandboxControl(manifestPath: string, signal: AbortSignal = new AbortController().signal): void {
-  const manifest = readManifest(manifestPath);
-  assertGitWorktreeBinding(manifest.repoRoot, manifest.worktreeRoot, manifest.branch);
-  const brokerPath = path.join(path.dirname(manifestPath), 'broker.json');
+function bindingReason(manifest: SandboxControlManifest): string | null {
+  try {
+    assertGitWorktreeBinding(manifest.repoRoot, manifest.worktreeRoot, manifest.branch);
+    return null;
+  } catch {
+    return 'SANDBOX_WORKTREE_BINDING_LOST';
+  }
+}
+
+function recoverProcessing(manifest: SandboxControlManifest): void {
+  for (const entry of fs.readdirSync(manifest.processingDir, { withFileTypes: true })) {
+    if (!entry.isDirectory() || !/^[a-f0-9-]{16,64}$/.test(entry.name)) continue;
+    const descriptor = executionPath(manifest, entry.name);
+    const existingResponse = responsePath(manifest, entry.name);
+    if (fs.existsSync(descriptor)) {
+      const execution = readExecution(descriptor);
+      if (!terminateSandboxControlExecution(execution)) {
+        throw new Error(`SANDBOX_CONTROL_EXECUTION_STILL_RUNNING: ${entry.name}`);
+      }
+      appendSandboxControlAudit(manifest, 'orphan-tree-terminated', { requestId: entry.name });
+      let terminal = false;
+      if (fs.existsSync(existingResponse)) {
+        try {
+          const response = JSON.parse(fs.readFileSync(existingResponse, 'utf8')) as SandboxControlResponse;
+          terminal = response.version === 2 && response.id === entry.name
+            && (response.phase === 'completed' || response.phase === 'rejected');
+        } catch {
+          terminal = false;
+        }
+      }
+      if (!terminal) writeResponse(manifest, unknown(entry.name));
+    } else {
+      writeResponse(manifest, notExecuted(entry.name));
+    }
+    fs.rmSync(path.join(manifest.processingDir, entry.name), { recursive: true, force: true });
+  }
+}
+
+function delay(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+export function sandboxControlSafeEnv(env: NodeJS.ProcessEnv = process.env): NodeJS.ProcessEnv {
+  return Object.fromEntries(Object.entries(env).filter(([key]) => !key.toUpperCase().startsWith('AGENT_INFRA_CONTROL_')));
+}
+
+export async function serveSandboxControl(
+  manifestPath: string,
+  signal: AbortSignal = new AbortController().signal
+): Promise<void> {
+  const manifest = readSandboxControlManifest(manifestPath);
+  const root = path.dirname(manifestPath);
   const startTime = getProcessStartTime(process.pid);
   if (!startTime) throw new Error('SANDBOX_CONTROL_BROKER_IDENTITY_UNAVAILABLE');
-  fs.writeFileSync(brokerPath, `${JSON.stringify({
-    version: 1,
-    pid: process.pid,
-    startTime,
-    token: manifest.token
-  })}\n`, { mode: 0o600, flag: 'wx' });
+  const releaseStartup = await acquireSandboxControlBrokerStartup(root, { pid: process.pid, startTime });
   const requestsDir = path.join(manifest.channelDir, 'requests');
   const responsesDir = path.join(manifest.channelDir, 'responses');
-  const consumedDir = path.join(path.dirname(manifestPath), 'consumed');
-  assertRealDirectory(manifest.channelDir);
-  fs.mkdirSync(requestsDir, { recursive: true, mode: 0o700 });
-  fs.mkdirSync(responsesDir, { recursive: true, mode: 0o700 });
-  fs.mkdirSync(consumedDir, { recursive: true, mode: 0o700 });
-  assertRealDirectory(requestsDir, manifest.channelDir);
-  assertRealDirectory(responsesDir, manifest.channelDir);
-  assertRealDirectory(consumedDir, path.dirname(manifestPath));
-  while (!signal.aborted) {
-    const current = readManifest(manifestPath);
-    if (current.token !== manifest.token) return;
-    assertGitWorktreeBinding(current.repoRoot, current.worktreeRoot, current.branch);
+  const consumedDir = path.join(root, 'consumed');
+  const broker = { pid: process.pid, startTime };
+  const brokerPath = path.join(root, 'broker.json');
+  const brokerRecord = `${JSON.stringify({ version: 2, ...broker, token: manifest.token, generation: manifest.generation })}\n`;
+  try {
+    for (const directory of [manifest.channelDir, requestsDir, responsesDir, consumedDir, manifest.publicStatusDir, manifest.processingDir]) {
+      fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
+    }
+    assertRealDirectory(manifest.channelDir);
     assertRealDirectory(requestsDir, manifest.channelDir);
     assertRealDirectory(responsesDir, manifest.channelDir);
-    for (const name of fs.readdirSync(requestsDir).sort()) {
-      if (!/^[a-f0-9-]{16,64}\.json$/.test(name)) continue;
-      const requestPath = path.join(requestsDir, name);
-      let id = name.slice(0, -5);
-      let response: SandboxControlResponse;
+    assertRealDirectory(consumedDir, root);
+    assertRealDirectory(manifest.publicStatusDir, root);
+    assertRealDirectory(manifest.processingDir, root);
+    fs.writeFileSync(brokerPath, brokerRecord, { mode: 0o600, flag: 'wx' });
+    if (isSandboxControlRootQuiescing(root)) {
+      if (fs.readFileSync(brokerPath, 'utf8') === brokerRecord) fs.unlinkSync(brokerPath);
+      return;
+    }
+  } finally {
+    releaseStartup();
+  }
+  let active: ActiveExecution | null = null;
+  let lastState = '';
+  let lastStatusAt = 0;
+  try {
+    writeSandboxControlStatus(manifest, broker, 'starting', null, null);
+    appendSandboxControlAudit(manifest, 'broker-start', { pid: broker.pid });
+    recoverProcessing(manifest);
+    while (!signal.aborted) {
+      let current: SandboxControlManifest;
       try {
-        const stat = fs.lstatSync(requestPath);
-        if (!stat.isFile() || stat.isSymbolicLink()) throw new Error('SANDBOX_CONTROL_REQUEST_INVALID');
-        const request = validateSandboxControlRequest(
-          JSON.parse(fs.readFileSync(requestPath, 'utf8')),
-          manifest
-        );
-        id = request.id;
-        consumeRequest(consumedDir, id);
-        if (request.family === 'task-create') {
-          const result = createTask(request.candidate, { repoRoot: manifest.repoRoot });
-          response = {
-            version: 1, id,
-            exitCode: result.status === 'blocked' ? 2 : result.status === 'failed' ? 1 : 0,
-            stdout: `${JSON.stringify(result)}\n`, stderr: ''
-          };
+        current = readSandboxControlManifest(manifestPath);
+      } catch {
+        break;
+      }
+      if (current.token !== manifest.token || current.generation !== manifest.generation) break;
+
+      if (active?.settled) {
+        if (active.result) {
+          writeResponse(manifest, {
+            version: 2, id: active.request.id, phase: 'completed', exitCode: active.result.exitCode,
+            stdout: active.result.stdout, stderr: active.result.stderr, error: null
+          });
         } else {
-          const boundArgs = bindSandboxControlTask(request, manifest.taskId!);
-          if (request.family === 'task-orchestration') {
-            boundArgs.push('--git-worktree-root', manifest.worktreeRoot);
-          }
-          const result = spawnSync(
-            process.execPath,
-            ['--experimental-strip-types', '--no-warnings', process.argv[1]!, request.family, ...boundArgs],
-            {
-              cwd: manifest.repoRoot,
-              encoding: 'utf8',
-              env: sandboxControlSafeEnv()
-            }
-          );
-          response = {
-            version: 1,
-            id,
-            exitCode: result.status ?? 1,
-            stdout: result.stdout ?? '',
-            stderr: result.stderr ?? ''
-          };
+          writeResponse(manifest, unknown(active.request.id));
         }
-      } catch (error) {
-        response = {
-          version: 1,
-          id,
-          exitCode: 1,
-          stdout: '',
-          stderr: `${error instanceof Error ? error.message : String(error)}\n`
-        };
+        fs.rmSync(path.join(manifest.processingDir, active.request.id), { recursive: true, force: true });
+        active = null;
       }
+
+      let reasonCode: string | null = null;
       try {
-        fs.unlinkSync(requestPath);
-        writeResponse(responsesDir, response);
-      } catch (error) {
-        if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error;
+        if (cleanupStaleSandboxControlLease(manifest)) {
+          appendSandboxControlAudit(manifest, 'lease-stale-cleanup');
+        }
+        if (readActiveLease(manifest)) reasonCode = 'SANDBOX_CONTROL_HANDOFF_ACTIVE';
+      } catch {
+        reasonCode = 'SANDBOX_CONTROL_HANDOFF_ACTIVE';
       }
+      reasonCode ??= bindingReason(manifest);
+      const state = reasonCode ? 'parked' : active ? 'busy' : 'healthy';
+      const stateKey = `${state}:${reasonCode ?? ''}:${active?.request.id ?? ''}`;
+      const now = Date.now();
+      if (stateKey !== lastState || now - lastStatusAt >= SANDBOX_CONTROL_STATUS_INTERVAL_MS) {
+        writeSandboxControlStatus(manifest, broker, state, reasonCode, active?.request.id ?? null, now);
+        lastStatusAt = now;
+      }
+      if (stateKey !== lastState) {
+        appendSandboxControlAudit(manifest, 'broker-state', { state, reasonCode, requestId: active?.request.id ?? null });
+        lastState = stateKey;
+      }
+
+      for (const name of fs.readdirSync(requestsDir).sort()) {
+        if (!/^[a-f0-9-]{16,64}\.json$/.test(name)) continue;
+        const id = name.slice(0, -5);
+        const source = path.join(requestsDir, name);
+        let claimed: string | null = null;
+        try {
+          claimed = claimRequest(manifest, source, id);
+          consumeRequest(consumedDir, id);
+          if (reasonCode) throw new Error(reasonCode);
+          if (active) throw new Error('SANDBOX_CONTROL_BUSY');
+          const request = validateSandboxControlRequest(JSON.parse(fs.readFileSync(claimed, 'utf8')), manifest);
+          if (bindingReason(manifest)) throw new Error('SANDBOX_WORKTREE_BINDING_LOST');
+          if (readActiveLease(manifest)) throw new Error('SANDBOX_CONTROL_HANDOFF_ACTIVE');
+          const prepared = await prepareSandboxControlExecution({
+            manifest, manifestPath, request, requestPath: claimed, internalCliPath: process.argv[1]!
+          });
+          const execution: ActiveExecution = { request, prepared, result: null, failure: null, settled: false };
+          active = execution;
+          prepared.completion.then(
+            (result) => { execution.result = result; execution.settled = true; },
+            (error) => { execution.failure = error; execution.settled = true; }
+          );
+          writeResponse(manifest, {
+            version: 2, id, phase: 'accepted', exitCode: null, stdout: '', stderr: '', error: null
+          });
+          try {
+            prepared.start();
+          } catch (error) {
+            prepared.terminate();
+            writeResponse(manifest, unknown(id));
+            fs.rmSync(path.join(manifest.processingDir, id), { recursive: true, force: true });
+            active = null;
+            claimed = null;
+            appendSandboxControlAudit(manifest, 'executor-gate-failed', { requestId: id });
+            continue;
+          }
+        } catch (error) {
+          writeResponse(manifest, rejected(id, error));
+          if (claimed) fs.rmSync(path.dirname(claimed), { recursive: true, force: true });
+        }
+      }
+      await delay(25);
+    }
+  } finally {
+    if (active) {
+      active.prepared.terminate();
+      writeResponse(manifest, unknown(active.request.id));
+    }
+    appendSandboxControlAudit(manifest, 'broker-stop', { pid: broker.pid });
+    try {
+      if (fs.readFileSync(brokerPath, 'utf8') === brokerRecord) fs.unlinkSync(brokerPath);
+    } catch {
+      // A newer owner or recovery path owns the record.
     }
-    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 25);
   }
 }

package/lib/sandbox/control/state.ts

@@ -0,0 +1,196 @@
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { buildProcessTreeStopCommand } from '../../server/process-control.ts';
+import { processIdentityMatches } from '../../server/process-state.ts';
+import type {
+  SandboxControlExecution,
+  SandboxControlLease,
+  SandboxControlManifest,
+  SandboxControlStatus
+} from './protocol.ts';
+
+export const SANDBOX_CONTROL_AUDIT_MAX_BYTES = 1024 * 1024;
+export const SANDBOX_CONTROL_EXECUTION_STOP_MS = 2_000;
+
+function assertRegularFile(filePath: string): void {
+  const stat = fs.lstatSync(filePath);
+  if (!stat.isFile() || stat.isSymbolicLink()) throw new Error('SANDBOX_CONTROL_STATE_INVALID');
+}
+
+export function atomicWriteJson(filePath: string, value: unknown, mode = 0o600, createParent = true): void {
+  if (createParent) fs.mkdirSync(path.dirname(filePath), { recursive: true, mode: 0o700 });
+  const temporary = path.join(path.dirname(filePath), `.${path.basename(filePath)}.${process.pid}.${randomUUID()}.tmp`);
+  try {
+    fs.writeFileSync(temporary, `${JSON.stringify(value)}\n`, { mode, flag: 'wx' });
+    fs.renameSync(temporary, filePath);
+  } finally {
+    fs.rmSync(temporary, { force: true });
+  }
+}
+
+export function readJsonFile(filePath: string): unknown {
+  assertRegularFile(filePath);
+  return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+}
+
+export function statusPath(manifest: SandboxControlManifest): string {
+  return path.join(manifest.publicStatusDir, 'status.json');
+}
+
+export function writeSandboxControlStatus(
+  manifest: SandboxControlManifest,
+  broker: { pid: number; startTime: string },
+  state: SandboxControlStatus['state'],
+  reasonCode: string | null,
+  activeRequestId: string | null,
+  now = Date.now()
+): SandboxControlStatus {
+  const status: SandboxControlStatus = {
+    version: 1, generation: manifest.generation, broker, state, reasonCode, activeRequestId, updatedAt: now
+  };
+  atomicWriteJson(statusPath(manifest), status, 0o600, false);
+  return status;
+}
+
+export function parseSandboxControlStatus(value: unknown): SandboxControlStatus {
+  const status = value as Partial<SandboxControlStatus> | null;
+  if (!status || status.version !== 1 || typeof status.generation !== 'string'
+    || !status.broker || !Number.isSafeInteger(status.broker.pid) || typeof status.broker.startTime !== 'string'
+    || !['starting', 'healthy', 'busy', 'parked'].includes(status.state ?? '')
+    || (status.reasonCode !== null && typeof status.reasonCode !== 'string')
+    || (status.activeRequestId !== null && typeof status.activeRequestId !== 'string')
+    || !Number.isSafeInteger(status.updatedAt)) throw new Error('SANDBOX_CONTROL_STATUS_INVALID');
+  return status as SandboxControlStatus;
+}
+
+export function readSandboxControlStatus(directory: string): SandboxControlStatus {
+  return parseSandboxControlStatus(readJsonFile(path.join(directory, 'status.json')));
+}
+
+export function readActiveLease(manifest: SandboxControlManifest, now = Date.now()): SandboxControlLease | null {
+  const filePath = path.join(path.dirname(manifest.publicStatusDir), 'lease.json');
+  if (!fs.existsSync(filePath)) return null;
+  const lease = readJsonFile(filePath) as Partial<SandboxControlLease> | null;
+  if (!lease || lease.version !== 1
+    || typeof lease.nonce !== 'string' || !lease.owner || !Number.isSafeInteger(lease.owner.pid)
+    || typeof lease.owner.startTime !== 'string' || !Number.isSafeInteger(lease.issuedAt)
+    || !Number.isSafeInteger(lease.expiresAt) || typeof lease.generation !== 'string'
+    || (lease.taskId !== null && typeof lease.taskId !== 'string')
+    || typeof lease.branch !== 'string' || typeof lease.reason !== 'string') {
+    throw new Error('SANDBOX_CONTROL_LEASE_INVALID');
+  }
+  if (lease.generation !== manifest.generation || lease.expiresAt! <= now
+    || lease.taskId !== manifest.taskId || lease.branch !== manifest.branch) return null;
+  return lease as SandboxControlLease;
+}
+
+export function cleanupStaleSandboxControlLease(manifest: SandboxControlManifest, now = Date.now()): boolean {
+  const filePath = path.join(path.dirname(manifest.publicStatusDir), 'lease.json');
+  if (!fs.existsSync(filePath)) return false;
+  const raw = fs.readFileSync(filePath, 'utf8');
+  const lease = JSON.parse(raw) as Partial<SandboxControlLease> | null;
+  if (!lease || lease.version !== 1
+    || typeof lease.nonce !== 'string' || !lease.owner || !Number.isSafeInteger(lease.owner.pid)
+    || typeof lease.owner.startTime !== 'string' || !Number.isSafeInteger(lease.issuedAt)
+    || !Number.isSafeInteger(lease.expiresAt) || typeof lease.generation !== 'string'
+    || (lease.taskId !== null && typeof lease.taskId !== 'string')
+    || typeof lease.branch !== 'string' || typeof lease.reason !== 'string') {
+    throw new Error('SANDBOX_CONTROL_LEASE_INVALID');
+  }
+  const stale = lease.generation !== manifest.generation || lease.taskId !== manifest.taskId
+    || lease.branch !== manifest.branch || lease.expiresAt! <= now || !processIdentityMatches({
+    version: 1, pid: lease.owner.pid!, startTime: lease.owner.startTime!
+  });
+  if (!stale) return false;
+  if (fs.readFileSync(filePath, 'utf8') !== raw) throw new Error('SANDBOX_CONTROL_LEASE_OWNERSHIP_LOST');
+  fs.unlinkSync(filePath);
+  return true;
+}
+
+export function appendSandboxControlAudit(
+  manifest: SandboxControlManifest,
+  event: string,
+  fields: Record<string, string | number | boolean | null> = {},
+  now = Date.now()
+): void {
+  const auditPath = path.join(path.dirname(manifest.publicStatusDir), 'audit.ndjson');
+  if (fs.existsSync(auditPath) && fs.statSync(auditPath).size >= SANDBOX_CONTROL_AUDIT_MAX_BYTES) {
+    fs.rmSync(`${auditPath}.1`, { force: true });
+    fs.renameSync(auditPath, `${auditPath}.1`);
+  }
+  fs.appendFileSync(auditPath, `${JSON.stringify({ version: 1, event, generation: manifest.generation, at: now, ...fields })}\n`, {
+    encoding: 'utf8', mode: 0o600
+  });
+}
+
+export function executionPath(manifest: SandboxControlManifest, requestId: string): string {
+  return path.join(manifest.processingDir, requestId, 'execution.json');
+}
+
+export function readExecution(filePath: string): SandboxControlExecution {
+  const execution = readJsonFile(filePath) as Partial<SandboxControlExecution> | null;
+  if (!execution || execution.version !== 1 || typeof execution.generation !== 'string'
+    || typeof execution.requestId !== 'string' || typeof execution.nonce !== 'string'
+    || !execution.child || !Number.isSafeInteger(execution.child.pid) || typeof execution.child.startTime !== 'string'
+    || !['prepared', 'running', 'terminating'].includes(execution.phase ?? '')
+    || !Number.isSafeInteger(execution.updatedAt)) throw new Error('SANDBOX_CONTROL_EXECUTION_INVALID');
+  return execution as SandboxControlExecution;
+}
+
+export function terminateSandboxControlExecution(
+  execution: SandboxControlExecution,
+  options: { platform?: NodeJS.Platform; timeoutMs?: number } = {}
+): boolean {
+  const platform = options.platform ?? process.platform;
+  const processGroupId = execution.child.processGroupId;
+  const processGroupAlive = (groupId: number): boolean => {
+    try {
+      const rows = execFileSync('ps', ['-axo', 'pgid=,stat='], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+      return rows.split('\n').some((row) => {
+        const match = row.trim().match(/^(\d+)\s+(\S+)/);
+        return Number(match?.[1]) === groupId && !match?.[2]?.startsWith('Z');
+      });
+    } catch {
+      try {
+        process.kill(-groupId, 0);
+        return true;
+      } catch (error) {
+        return (error as NodeJS.ErrnoException).code === 'EPERM';
+      }
+    }
+  };
+  const treeAlive = (): boolean => {
+    if (platform === 'win32' || !processGroupId) {
+      return processIdentityMatches({ version: 1, pid: execution.child.pid, startTime: execution.child.startTime });
+    }
+    return processGroupAlive(processGroupId);
+  };
+  if (!treeAlive()) return true;
+  const command = buildProcessTreeStopCommand(processGroupId ?? execution.child.pid, platform);
+  try {
+    if (command.kind === 'exec') execFileSync(command.command, command.args, { stdio: 'ignore' });
+    else process.kill(command.pid, command.signal);
+  } catch {
+    // The identity check below distinguishes an already-exited tree from a failed termination.
+  }
+  const deadline = Date.now() + (options.timeoutMs ?? SANDBOX_CONTROL_EXECUTION_STOP_MS);
+  while (Date.now() < deadline) {
+    if (!treeAlive()) return true;
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 25);
+  }
+  if (platform !== 'win32') {
+    try {
+      process.kill(processGroupId ? -processGroupId : execution.child.pid, 'SIGKILL');
+    } catch {
+      // The final identity check handles an already-exited tree.
+    }
+    const killDeadline = Date.now() + (options.timeoutMs ?? SANDBOX_CONTROL_EXECUTION_STOP_MS);
+    while (Date.now() < killDeadline) {
+      if (!treeAlive()) return true;
+      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 25);
+    }
+  }
+  return !treeAlive();
+}

package/lib/sandbox/index.ts

@@ -15,9 +15,9 @@ Commands:
   rebuild [--quiet] [--refresh]
                                Rebuild the sandbox image (--refresh pulls base + tools)
   refresh                      Sync host Claude Code credentials to all sandbox copies
-  rm <branch> | --all | --purge
+  rm <branch> | --unbound | --purge
                                Remove one sandbox, all sandboxes not bound to an
-                               active task (--all), or tear down everything (--purge)
+                               active task (--unbound), or tear down everything (--purge)
   start [--recreate] <branch | TASK-id | N>
                                Verify or recover an existing sandbox container;
                                optionally replace only the container on failure

package/lib/sandbox/managed-fs.ts

@@ -1,6 +1,8 @@
 import path from 'node:path';
 import { run, runSafe } from './shell.ts';
 import { removeDirRecursive } from '../remove-dir.ts';
+import { verifyWorktreePermit } from './worktree-safety.ts';
+import type { WorktreeRemovalPermit } from './worktree-safety.ts';
 
 export function assertManagedPath(root: string, target: string): void {
   const resolvedRoot = path.resolve(root);
@@ -22,18 +24,31 @@ export function removeWorktreeDir(
   repoRoot: string,
   worktreeBase: string,
   dir: string,
-  { runFn = run, runSafeFn = runSafe }: {
+  permit: WorktreeRemovalPermit,
+  { runFn = run, runSafeFn = runSafe, allowRegisteredPathFallback = false }: {
     runFn?: typeof run;
     runSafeFn?: typeof runSafe;
+    allowRegisteredPathFallback?: boolean;
   } = {}
 ): void {
+  assertManagedPath(worktreeBase, dir);
+  if (path.resolve(permit.snapshot.worktree) !== path.resolve(dir)) {
+    throw new Error(`Worktree permit target mismatch: ${dir}`);
+  }
+  verifyWorktreePermit(permit);
   try {
     runFn('git', ['-C', repoRoot, 'worktree', 'remove', dir, '--force']);
-  } catch {
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const registeredPathMismatch = /(?:is not|not a valid) working tree|not a working tree/i.test(message);
+    if (!allowRegisteredPathFallback || !registeredPathMismatch) {
+      throw error;
+    }
     // On WSL2 the worktree is registered under its `/mnt/<drive>/...` path, so
     // `git worktree remove <windows-path>` cannot match it. Delete the managed
     // directory directly, then prune the now-dangling worktree metadata so the
     // branch is no longer reported as checked out.
+    verifyWorktreePermit(permit);
     removeManagedDir(worktreeBase, dir);
     runSafeFn('git', ['-C', repoRoot, 'worktree', 'prune']);
   }