@fitlab-ai/agent-infra 0.9.6 → 0.9.8

package/lib/sandbox/control/protocol.ts

@@ -1,4 +1,5 @@
 import { validateTaskCreateCandidate, type TaskCreateCandidateV1 } from '../../task/create.ts';
+import type { ProcessIdentity } from '../../server/process-state.ts';
 
 export const SANDBOX_CONTROL_MAX_BYTES = 64 * 1024;
 export const SANDBOX_CONTROL_ADMISSION_WINDOW_MS = 2_000;
@@ -6,13 +7,41 @@ export const SANDBOX_CONTROL_STATUS_INTERVAL_MS = 250;
 export const SANDBOX_CONTROL_STATUS_STALE_MS = 1_500;
 export const SANDBOX_CONTROL_FUTURE_SKEW_MS = 1_000;
 export const SANDBOX_CONTROL_FAMILIES = ['task-lifecycle', 'task-orchestration', 'task-create'] as const;
+export type SandboxControlTimingPolicy = Readonly<{
+  controlTickMs: number;
+  parkedBindingInitialMs: number;
+  slowCheckMs: number;
+  containerHeartbeatMs: number;
+  quiesceDeadlineMs: number;
+}>;
+export const DEFAULT_SANDBOX_CONTROL_TIMING: SandboxControlTimingPolicy = Object.freeze({
+  controlTickMs: 250,
+  parkedBindingInitialMs: 1_000,
+  slowCheckMs: 5_000,
+  containerHeartbeatMs: 5_000,
+  quiesceDeadlineMs: 7_000
+} as const);
 
 export type SandboxControlFamily = typeof SANDBOX_CONTROL_FAMILIES[number];
-export type SandboxControlManifest = Readonly<{
-  version: 3; repoRoot: string; worktreeRoot: string; project: string; container: string;
+export type SandboxControlContainerIdentity = Readonly<{
+  id: string;
+  labels: Readonly<Record<string, string>>;
+}>;
+export type SandboxControlManifestBase = Readonly<{
+  engine: string; repoRoot: string; worktreeRoot: string; project: string; container: string;
+  containerIdentity: SandboxControlContainerIdentity;
   branch: string; mode: 'task-bound' | 'branch-only'; taskId: string | null; token: string;
   generation: string; channelDir: string; publicStatusDir: string; processingDir: string;
 }>;
+export type SandboxControlLegacyManifest = SandboxControlManifestBase & Readonly<{ version: 4 }>;
+export type SandboxControlManifest = SandboxControlManifestBase & Readonly<{ version: 5; runtimeDir: string }>;
+export type SandboxControlManifestLike = SandboxControlLegacyManifest | SandboxControlManifest;
+export type SandboxControlBrokerOwner = ProcessIdentity & Readonly<{
+  version: 3;
+  brokerId: string;
+  token: string;
+  generation: string;
+}>;
 type RequestBase = Readonly<{
   version: 2; id: string; token: string; generation: string; issuedAt: number; expiresAt: number;
 }>;
@@ -29,17 +58,17 @@ export type SandboxControlResponse = Readonly<{
   stdout: string; stderr: string; error: SandboxControlError | null;
 }>;
 export type SandboxControlStatus = Readonly<{
-  version: 1; generation: string; broker: { pid: number; startTime: string };
+  version: 2; generation: string; broker: ProcessIdentity & { brokerId: string };
   state: 'starting' | 'healthy' | 'busy' | 'parked'; reasonCode: string | null;
   activeRequestId: string | null; updatedAt: number;
 }>;
 export type SandboxControlLease = Readonly<{
-  version: 1; generation: string; nonce: string; owner: { pid: number; startTime: string };
+  version: 2; generation: string; nonce: string; owner: ProcessIdentity;
   issuedAt: number; expiresAt: number; taskId: string | null; branch: string; reason: string;
 }>;
 export type SandboxControlExecution = Readonly<{
-  version: 1; generation: string; requestId: string; nonce: string;
-  child: { pid: number; startTime: string; processGroupId: number | null };
+  version: 2; generation: string; requestId: string; nonce: string;
+  child: ProcessIdentity & { processGroupId: number | null };
   phase: 'prepared' | 'running' | 'terminating'; updatedAt: number;
 }>;
 

package/lib/sandbox/control/server.ts

@@ -1,13 +1,15 @@
 import fs from 'node:fs';
 import path from 'node:path';
+import { randomUUID } from 'node:crypto';
 import { getProcessStartTime } from '../../server/process-state.ts';
 import { assertGitWorktreeBinding } from '../../git/worktree-identity.ts';
 import {
   controlError,
-  SANDBOX_CONTROL_STATUS_INTERVAL_MS,
+  DEFAULT_SANDBOX_CONTROL_TIMING,
   type SandboxControlManifest,
   type SandboxControlRequest,
-  type SandboxControlResponse
+  type SandboxControlResponse,
+  type SandboxControlTimingPolicy
 } from './protocol.ts';
 import { prepareSandboxControlExecution, type PreparedSandboxControlExecution, type SandboxControlExecutionResult } from './executor.ts';
 import {
@@ -21,11 +23,15 @@ import {
   writeSandboxControlStatus
 } from './state.ts';
 import { validateSandboxControlRequest } from './protocol.ts';
+import { inspectSandboxControlContainer, type ContainerObservation } from './container-identity.ts';
 import {
   acquireSandboxControlBrokerStartup,
+  garbageCollectSandboxControlRoot,
   isSandboxControlRootQuiescing,
   readSandboxControlManifest
 } from './lifecycle.ts';
+import type { BrokerOwner } from './lifecycle.ts';
+import { nextSandboxControlBackoff } from './timing.ts';
 
 type ActiveExecution = {
   request: SandboxControlRequest;
@@ -105,9 +111,10 @@ function bindingReason(manifest: SandboxControlManifest): string | null {
   }
 }
 
-function recoverProcessing(manifest: SandboxControlManifest): void {
+function recoverProcessing(manifest: SandboxControlManifest, brokerOwns: () => boolean): boolean {
   for (const entry of fs.readdirSync(manifest.processingDir, { withFileTypes: true })) {
     if (!entry.isDirectory() || !/^[a-f0-9-]{16,64}$/.test(entry.name)) continue;
+    if (!brokerOwns()) return false;
     const descriptor = executionPath(manifest, entry.name);
     const existingResponse = responsePath(manifest, entry.name);
     if (fs.existsSync(descriptor)) {
@@ -115,6 +122,7 @@ function recoverProcessing(manifest: SandboxControlManifest): void {
       if (!terminateSandboxControlExecution(execution)) {
         throw new Error(`SANDBOX_CONTROL_EXECUTION_STILL_RUNNING: ${entry.name}`);
       }
+      if (!brokerOwns()) return false;
       appendSandboxControlAudit(manifest, 'orphan-tree-terminated', { requestId: entry.name });
       let terminal = false;
       if (fs.existsSync(existingResponse)) {
@@ -126,12 +134,18 @@ function recoverProcessing(manifest: SandboxControlManifest): void {
           terminal = false;
         }
       }
-      if (!terminal) writeResponse(manifest, unknown(entry.name));
+      if (!terminal) {
+        if (!brokerOwns()) return false;
+        writeResponse(manifest, unknown(entry.name));
+      }
     } else {
+      if (!brokerOwns()) return false;
       writeResponse(manifest, notExecuted(entry.name));
     }
+    if (!brokerOwns()) return false;
     fs.rmSync(path.join(manifest.processingDir, entry.name), { recursive: true, force: true });
   }
+  return true;
 }
 
 function delay(ms: number): Promise<void> {
@@ -144,19 +158,42 @@ export function sandboxControlSafeEnv(env: NodeJS.ProcessEnv = process.env): Nod
 
 export async function serveSandboxControl(
   manifestPath: string,
-  signal: AbortSignal = new AbortController().signal
+  signal: AbortSignal = new AbortController().signal,
+  options: {
+    timing?: SandboxControlTimingPolicy;
+    inspectContainer?: (manifest: SandboxControlManifest) => Promise<ContainerObservation>;
+    bindingCheck?: (manifest: SandboxControlManifest) => string | null;
+  } = {}
 ): Promise<void> {
+  const timing = options.timing ?? DEFAULT_SANDBOX_CONTROL_TIMING;
+  const inspectContainer = options.inspectContainer ?? ((value: SandboxControlManifest) => inspectSandboxControlContainer(value));
+  const bindingCheck = options.bindingCheck ?? bindingReason;
   const manifest = readSandboxControlManifest(manifestPath);
   const root = path.dirname(manifestPath);
   const startTime = getProcessStartTime(process.pid);
   if (!startTime) throw new Error('SANDBOX_CONTROL_BROKER_IDENTITY_UNAVAILABLE');
-  const releaseStartup = await acquireSandboxControlBrokerStartup(root, { pid: process.pid, startTime });
+  const brokerId = randomUUID();
+  const releaseStartup = await acquireSandboxControlBrokerStartup(root, { pid: process.pid, startTime, brokerId });
   const requestsDir = path.join(manifest.channelDir, 'requests');
   const responsesDir = path.join(manifest.channelDir, 'responses');
   const consumedDir = path.join(root, 'consumed');
-  const broker = { pid: process.pid, startTime };
+  const broker: BrokerOwner = {
+    version: 3,
+    pid: process.pid,
+    startTime,
+    brokerId,
+    token: manifest.token,
+    generation: manifest.generation
+  };
   const brokerPath = path.join(root, 'broker.json');
-  const brokerRecord = `${JSON.stringify({ version: 2, ...broker, token: manifest.token, generation: manifest.generation })}\n`;
+  const brokerRecord = `${JSON.stringify(broker)}\n`;
+  const brokerOwns = (): boolean => {
+    try {
+      return fs.readFileSync(brokerPath, 'utf8') === brokerRecord;
+    } catch {
+      return false;
+    }
+  };
   try {
     for (const directory of [manifest.channelDir, requestsDir, responsesDir, consumedDir, manifest.publicStatusDir, manifest.processingDir]) {
       fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
@@ -178,11 +215,20 @@ export async function serveSandboxControl(
   let active: ActiveExecution | null = null;
   let lastState = '';
   let lastStatusAt = 0;
+  let nextBindingCheckAt = 0;
+  let nextContainerHeartbeatAt = Date.now() + timing.containerHeartbeatMs;
+  let containerReasonCode: string | null = null;
+  let containerBackoffMs = timing.parkedBindingInitialMs;
+  let bindingReasonCode: string | null = null;
+  let bindingBackoffMs: number = timing.parkedBindingInitialMs;
   try {
+    if (!brokerOwns()) return;
     writeSandboxControlStatus(manifest, broker, 'starting', null, null);
+    if (!brokerOwns()) return;
     appendSandboxControlAudit(manifest, 'broker-start', { pid: broker.pid });
-    recoverProcessing(manifest);
+    if (!recoverProcessing(manifest, brokerOwns)) return;
     while (!signal.aborted) {
+      if (!brokerOwns()) break;
       let current: SandboxControlManifest;
       try {
         current = readSandboxControlManifest(manifestPath);
@@ -190,54 +236,123 @@ export async function serveSandboxControl(
         break;
       }
       if (current.token !== manifest.token || current.generation !== manifest.generation) break;
+      const heartbeatNow = Date.now();
+      if (heartbeatNow >= nextContainerHeartbeatAt) {
+        let observation: ContainerObservation;
+        try {
+          observation = await inspectContainer(manifest);
+        } catch (error) {
+          observation = { state: 'unknown', reason: controlError(error).code };
+        }
+        if (!brokerOwns()) break;
+        if (observation.state === 'found') {
+          containerReasonCode = null;
+          containerBackoffMs = timing.parkedBindingInitialMs;
+          nextContainerHeartbeatAt = Date.now() + timing.containerHeartbeatMs;
+        } else if (observation.state === 'unknown') {
+          containerReasonCode = 'SANDBOX_CONTROL_CONTAINER_UNKNOWN';
+          appendSandboxControlAudit(manifest, 'container-heartbeat-unknown', { reason: observation.reason });
+          const backoff = nextSandboxControlBackoff(containerBackoffMs, timing.slowCheckMs);
+          nextContainerHeartbeatAt = Date.now() + backoff.delayMs;
+          containerBackoffMs = backoff.nextDelayMs;
+        } else {
+          try {
+            await garbageCollectSandboxControlRoot(root, {
+              timeoutMs: timing.quiesceDeadlineMs,
+              inspectContainer: (timeoutMs) => inspectContainer(manifest),
+              selfOwner: broker
+            });
+            active = null;
+            return;
+          } catch (error) {
+            if (!brokerOwns()) break;
+            containerReasonCode = 'SANDBOX_CONTROL_CONTAINER_ABSENT_GC_FAILED';
+            appendSandboxControlAudit(manifest, 'container-gc-failed', { reason: controlError(error).code });
+            const backoff = nextSandboxControlBackoff(containerBackoffMs, timing.slowCheckMs);
+            nextContainerHeartbeatAt = Date.now() + backoff.delayMs;
+            containerBackoffMs = backoff.nextDelayMs;
+          }
+        }
+      }
 
       if (active?.settled) {
+        if (!brokerOwns()) break;
         if (active.result) {
+          if (!brokerOwns()) break;
           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 {
+          if (!brokerOwns()) break;
           writeResponse(manifest, unknown(active.request.id));
         }
+        if (!brokerOwns()) break;
         fs.rmSync(path.join(manifest.processingDir, active.request.id), { recursive: true, force: true });
         active = null;
       }
 
       let reasonCode: string | null = null;
       try {
+        if (!brokerOwns()) break;
         if (cleanupStaleSandboxControlLease(manifest)) {
+          if (!brokerOwns()) break;
           appendSandboxControlAudit(manifest, 'lease-stale-cleanup');
         }
         if (readActiveLease(manifest)) reasonCode = 'SANDBOX_CONTROL_HANDOFF_ACTIVE';
       } catch {
         reasonCode = 'SANDBOX_CONTROL_HANDOFF_ACTIVE';
       }
-      reasonCode ??= bindingReason(manifest);
+      const now = Date.now();
+      if (now >= nextBindingCheckAt) {
+        bindingReasonCode = bindingCheck(manifest);
+        if (bindingReasonCode) {
+          const backoff = nextSandboxControlBackoff(bindingBackoffMs, timing.slowCheckMs);
+          nextBindingCheckAt = now + backoff.delayMs;
+          bindingBackoffMs = backoff.nextDelayMs;
+        } else {
+          nextBindingCheckAt = now + timing.slowCheckMs;
+          bindingBackoffMs = timing.parkedBindingInitialMs;
+        }
+      }
+      reasonCode ??= containerReasonCode;
+      reasonCode ??= bindingReasonCode;
       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) {
+      if (brokerOwns() && (stateKey !== lastState || now - lastStatusAt >= timing.controlTickMs)) {
         writeSandboxControlStatus(manifest, broker, state, reasonCode, active?.request.id ?? null, now);
         lastStatusAt = now;
       }
-      if (stateKey !== lastState) {
+      if (brokerOwns() && stateKey !== lastState) {
         appendSandboxControlAudit(manifest, 'broker-state', { state, reasonCode, requestId: active?.request.id ?? null });
         lastState = stateKey;
       }
 
+      let retiring = false;
       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 {
+          if (!brokerOwns()) {
+            retiring = true;
+            break;
+          }
           claimed = claimRequest(manifest, source, id);
+          if (!brokerOwns()) {
+            retiring = true;
+            break;
+          }
           consumeRequest(consumedDir, id);
+          if (!brokerOwns()) {
+            retiring = true;
+            break;
+          }
           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 (bindingCheck(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]!
@@ -248,37 +363,82 @@ export async function serveSandboxControl(
             (result) => { execution.result = result; execution.settled = true; },
             (error) => { execution.failure = error; execution.settled = true; }
           );
+          if (!brokerOwns()) {
+            prepared.terminate(false);
+            active = null;
+            retiring = true;
+            continue;
+          }
+          if (!brokerOwns()) {
+            prepared.terminate(false);
+            active = null;
+            retiring = true;
+            continue;
+          }
           writeResponse(manifest, {
             version: 2, id, phase: 'accepted', exitCode: null, stdout: '', stderr: '', error: null
           });
+          if (!brokerOwns()) {
+            prepared.terminate(false);
+            active = null;
+            retiring = true;
+            break;
+          }
           try {
-            prepared.start();
+            prepared.start(brokerOwns);
           } catch (error) {
-            prepared.terminate();
+            const owned = brokerOwns();
+            prepared.terminate(owned);
+            if (!owned || !brokerOwns()) {
+              active = null;
+              retiring = true;
+              break;
+            }
             writeResponse(manifest, unknown(id));
+            if (!brokerOwns()) {
+              active = null;
+              retiring = true;
+              break;
+            }
             fs.rmSync(path.join(manifest.processingDir, id), { recursive: true, force: true });
             active = null;
             claimed = null;
+            if (!brokerOwns()) {
+              retiring = true;
+              break;
+            }
             appendSandboxControlAudit(manifest, 'executor-gate-failed', { requestId: id });
             continue;
           }
         } catch (error) {
+          if (!brokerOwns()) {
+            retiring = true;
+            break;
+          }
           writeResponse(manifest, rejected(id, error));
+          if (!brokerOwns()) {
+            retiring = true;
+            break;
+          }
           if (claimed) fs.rmSync(path.dirname(claimed), { recursive: true, force: true });
         }
       }
-      await delay(25);
+      if (retiring || !brokerOwns()) break;
+      await delay(timing.controlTickMs);
     }
   } finally {
     if (active) {
-      active.prepared.terminate();
-      writeResponse(manifest, unknown(active.request.id));
+      const owned = brokerOwns();
+      active.prepared.terminate(owned);
+      if (owned && brokerOwns()) 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.
+    if (brokerOwns()) {
+      appendSandboxControlAudit(manifest, 'broker-stop', { pid: broker.pid, brokerId: broker.brokerId });
+      try {
+        if (fs.readFileSync(brokerPath, 'utf8') === brokerRecord) fs.unlinkSync(brokerPath);
+      } catch {
+        // A newer owner or recovery path owns the record.
+      }
     }
   }
 }

package/lib/sandbox/control/state.ts

@@ -3,11 +3,12 @@ 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 { getProcessIdentityState } from '../../server/process-state.ts';
+import type { ProcessIdentity, ProcessIdentityProbe } from '../../server/process-state.ts';
 import type {
   SandboxControlExecution,
   SandboxControlLease,
-  SandboxControlManifest,
+  SandboxControlManifestLike,
   SandboxControlStatus
 } from './protocol.ts';
 
@@ -35,20 +36,20 @@ export function readJsonFile(filePath: string): unknown {
   return JSON.parse(fs.readFileSync(filePath, 'utf8'));
 }
 
-export function statusPath(manifest: SandboxControlManifest): string {
+export function statusPath(manifest: SandboxControlManifestLike): string {
   return path.join(manifest.publicStatusDir, 'status.json');
 }
 
 export function writeSandboxControlStatus(
-  manifest: SandboxControlManifest,
-  broker: { pid: number; startTime: string },
+  manifest: SandboxControlManifestLike,
+  broker: ProcessIdentity & { brokerId: 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
+    version: 2, generation: manifest.generation, broker, state, reasonCode, activeRequestId, updatedAt: now
   };
   atomicWriteJson(statusPath(manifest), status, 0o600, false);
   return status;
@@ -56,8 +57,10 @@ export function writeSandboxControlStatus(
 
 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'
+  if (!status || status.version !== 2 || typeof status.generation !== 'string'
+    || !status.broker || !Number.isSafeInteger(status.broker.pid) || typeof status.broker.startTime !== 'number'
+    || !Number.isSafeInteger(status.broker.startTime) || typeof status.broker.brokerId !== 'string'
+    || status.broker.brokerId.length === 0
     || !['starting', 'healthy', 'busy', 'parked'].includes(status.state ?? '')
     || (status.reasonCode !== null && typeof status.reasonCode !== 'string')
     || (status.activeRequestId !== null && typeof status.activeRequestId !== 'string')
@@ -69,13 +72,14 @@ export function readSandboxControlStatus(directory: string): SandboxControlStatu
   return parseSandboxControlStatus(readJsonFile(path.join(directory, 'status.json')));
 }
 
-export function readActiveLease(manifest: SandboxControlManifest, now = Date.now()): SandboxControlLease | null {
+export function readActiveLease(manifest: SandboxControlManifestLike, 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
+  if (!lease || lease.version !== 2
     || typeof lease.nonce !== 'string' || !lease.owner || !Number.isSafeInteger(lease.owner.pid)
-    || typeof lease.owner.startTime !== 'string' || !Number.isSafeInteger(lease.issuedAt)
+    || typeof lease.owner.startTime !== 'number' || !Number.isSafeInteger(lease.owner.startTime)
+    || !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') {
@@ -86,23 +90,30 @@ export function readActiveLease(manifest: SandboxControlManifest, now = Date.now
   return lease as SandboxControlLease;
 }
 
-export function cleanupStaleSandboxControlLease(manifest: SandboxControlManifest, now = Date.now()): boolean {
+export function cleanupStaleSandboxControlLease(
+  manifest: SandboxControlManifestLike,
+  now = Date.now(),
+  options: Readonly<{ identityProbe?: ProcessIdentityProbe }> = {}
+): 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
+  if (!lease || lease.version !== 2
     || typeof lease.nonce !== 'string' || !lease.owner || !Number.isSafeInteger(lease.owner.pid)
-    || typeof lease.owner.startTime !== 'string' || !Number.isSafeInteger(lease.issuedAt)
+    || typeof lease.owner.startTime !== 'number' || !Number.isSafeInteger(lease.owner.startTime)
+    || !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!
+  const ownerState = (options.identityProbe ?? getProcessIdentityState)({
+    pid: lease.owner.pid!, startTime: lease.owner.startTime!
   });
+  if (ownerState === 'unknown') throw new Error('SANDBOX_CONTROL_LEASE_OWNER_UNAVAILABLE');
+  const stale = lease.generation !== manifest.generation || lease.taskId !== manifest.taskId
+    || lease.branch !== manifest.branch || lease.expiresAt! <= now || ownerState === 'dead';
   if (!stale) return false;
   if (fs.readFileSync(filePath, 'utf8') !== raw) throw new Error('SANDBOX_CONTROL_LEASE_OWNERSHIP_LOST');
   fs.unlinkSync(filePath);
@@ -110,7 +121,7 @@ export function cleanupStaleSandboxControlLease(manifest: SandboxControlManifest
 }
 
 export function appendSandboxControlAudit(
-  manifest: SandboxControlManifest,
+  manifest: SandboxControlManifestLike,
   event: string,
   fields: Record<string, string | number | boolean | null> = {},
   now = Date.now()
@@ -125,15 +136,16 @@ export function appendSandboxControlAudit(
   });
 }
 
-export function executionPath(manifest: SandboxControlManifest, requestId: string): string {
+export function executionPath(manifest: SandboxControlManifestLike, 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'
+  if (!execution || execution.version !== 2 || typeof execution.generation !== 'string'
     || typeof execution.requestId !== 'string' || typeof execution.nonce !== 'string'
-    || !execution.child || !Number.isSafeInteger(execution.child.pid) || typeof execution.child.startTime !== 'string'
+    || !execution.child || !Number.isSafeInteger(execution.child.pid) || typeof execution.child.startTime !== 'number'
+    || !Number.isSafeInteger(execution.child.startTime)
     || !['prepared', 'running', 'terminating'].includes(execution.phase ?? '')
     || !Number.isSafeInteger(execution.updatedAt)) throw new Error('SANDBOX_CONTROL_EXECUTION_INVALID');
   return execution as SandboxControlExecution;
@@ -141,31 +153,48 @@ export function readExecution(filePath: string): SandboxControlExecution {
 
 export function terminateSandboxControlExecution(
   execution: SandboxControlExecution,
-  options: { platform?: NodeJS.Platform; timeoutMs?: number } = {}
+  options: {
+    platform?: NodeJS.Platform;
+    timeoutMs?: number;
+    deadlineAt?: number;
+    forceAt?: number;
+    allowForce?: boolean;
+    identityProbe?: ProcessIdentityProbe;
+  } = {}
 ): boolean {
   const platform = options.platform ?? process.platform;
   const processGroupId = execution.child.processGroupId;
-  const processGroupAlive = (groupId: number): boolean => {
+  const processGroupState = (groupId: number): 'alive' | 'dead' | 'unknown' => {
     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');
-      });
+      }) ? 'alive' : 'dead';
     } catch {
       try {
         process.kill(-groupId, 0);
-        return true;
+        return 'alive';
       } catch (error) {
-        return (error as NodeJS.ErrnoException).code === 'EPERM';
+        const code = (error as NodeJS.ErrnoException).code;
+        if (code === 'ESRCH') return 'dead';
+        if (code === 'EPERM') return 'alive';
+        return 'unknown';
       }
     }
   };
-  const treeAlive = (): boolean => {
+  const treeState = (): 'alive' | 'dead' | 'unknown' => {
     if (platform === 'win32' || !processGroupId) {
-      return processIdentityMatches({ version: 1, pid: execution.child.pid, startTime: execution.child.startTime });
+      return (options.identityProbe ?? getProcessIdentityState)({
+        pid: execution.child.pid, startTime: execution.child.startTime
+      });
     }
-    return processGroupAlive(processGroupId);
+    return processGroupState(processGroupId);
+  };
+  const treeAlive = (): boolean => {
+    const state = treeState();
+    if (state === 'unknown') throw new Error('SANDBOX_CONTROL_EXECUTION_OWNER_UNAVAILABLE');
+    return state === 'alive';
   };
   if (!treeAlive()) return true;
   const command = buildProcessTreeStopCommand(processGroupId ?? execution.child.pid, platform);
@@ -175,18 +204,23 @@ export function terminateSandboxControlExecution(
   } 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) {
+  const deadline = options.deadlineAt ?? (Date.now() + (options.timeoutMs ?? SANDBOX_CONTROL_EXECUTION_STOP_MS));
+  const forceAt = options.forceAt ?? (options.deadlineAt === undefined
+    ? deadline
+    : Math.min(deadline, Date.now() + Math.floor(Math.max(0, deadline - Date.now()) / 2)));
+  while (Date.now() < forceAt) {
     if (!treeAlive()) return true;
     Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 25);
   }
-  if (platform !== 'win32') {
+  if (platform !== 'win32' && options.allowForce !== false
+    && (options.deadlineAt === undefined || Date.now() < deadline)) {
     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);
+    const killDeadline = options.deadlineAt
+      ?? (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);

package/lib/sandbox/control/timing.ts

@@ -0,0 +1,12 @@
+export type SandboxControlBackoffStep = Readonly<{
+  delayMs: number;
+  nextDelayMs: number;
+}>;
+
+export function nextSandboxControlBackoff(currentDelayMs: number, capMs: number): SandboxControlBackoffStep {
+  const delayMs = Math.min(currentDelayMs, capMs);
+  return {
+    delayMs,
+    nextDelayMs: Math.min(capMs, delayMs * 2)
+  };
+}