@fitlab-ai/agent-infra 0.9.5 → 0.9.7

package/lib/task/codex-orchestration.ts

@@ -0,0 +1,319 @@
+import fs from 'node:fs';
+
+import {
+  preflightCodexLifecycleEvidence,
+  resolveCodexSpawnedChild,
+  resolveCodexTerminal,
+  resolveCodexThread
+} from '../agent-clients/adapters/codex-lifecycle/app-server.ts';
+import { createCodexLifecycleStore } from '../agent-clients/adapters/codex-lifecycle/store.ts';
+import { createCodexCapabilityStore } from '../agent-clients/adapters/codex-lifecycle/capability-store.ts';
+import { computeLifecycleBuildIdentity } from '../agent-clients/adapters/codex-lifecycle/build-identity.ts';
+import type { LifecycleBuildIdentity } from '../agent-clients/adapters/codex-lifecycle/build-identity.ts';
+import { verifyCodexSandboxControllerContext } from '../agent-clients/adapters/codex-lifecycle/sandbox-controller.ts';
+import type { AgentClientId } from '../agent-clients/types.ts';
+import { resolveTaskRef } from './resolve-ref.ts';
+import {
+  activateMatchingOrchestrationDelegation,
+  hasActivatableOrchestrationDelegation,
+  hasSealableOrchestrationDelegation,
+  pauseMatchingOrchestrationDelegation,
+  prepareOrchestrationDelegation,
+  reconcileMatchingOrchestrationDelegation,
+  sealMatchingOrchestrationDelegationWithHostEvidence
+} from './orchestration.ts';
+import type { OrchestrationOptions, OrchestrationResult } from './orchestration.ts';
+
+type LifecycleStore = ReturnType<typeof createCodexLifecycleStore>;
+type CapabilityStore = ReturnType<typeof createCodexCapabilityStore>;
+type CodexBridgeOptions = Readonly<{
+  repoRoot?: string;
+  store?: LifecycleStore;
+  preflight?: typeof preflightCodexLifecycleEvidence;
+  resolveThread?: typeof resolveCodexThread;
+  resolveTerminal?: typeof resolveCodexTerminal;
+  capabilityStore?: CapabilityStore;
+  buildIdentity?: LifecycleBuildIdentity;
+  orchestrationOptions?: OrchestrationOptions;
+}>;
+
+type CodexSpawnIdentity = Readonly<{
+  sessionId: string;
+  turnId: string;
+  toolUseId: string;
+  transcriptPath: string;
+  nativeAgent: string;
+  taskName: string;
+  requestedModel?: string;
+  requestedReasoningEffort?: string;
+}>;
+
+function coreOptions(options: CodexBridgeOptions): OrchestrationOptions {
+  return { ...options.orchestrationOptions, repoRoot: options.repoRoot ?? options.orchestrationOptions?.repoRoot };
+}
+
+function bridgeFailure(code: string, message: string): OrchestrationResult {
+  return {
+    status: 'failed', changed: false, taskId: null, run: null, next: null,
+    error: { code, message }
+  };
+}
+
+function pauseBridge(code: string, message: string, options: CodexBridgeOptions): OrchestrationResult {
+  const paused = pauseMatchingOrchestrationDelegation('codex', code, message, coreOptions(options));
+  return paused.error?.code === 'ORCHESTRATION_DELEGATION_MISSING'
+    ? bridgeFailure(code, message)
+    : paused;
+}
+
+function requiredStore(options: CodexBridgeOptions): LifecycleStore {
+  if (!options.store) throw new Error('Codex lifecycle store is required for orchestration bridge events');
+  return options.store;
+}
+
+function controllerContext(taskId: string, repoRoot: string) {
+  const contextPath = process.env.AGENT_INFRA_CODEX_CONTROLLER_CONTEXT;
+  return contextPath
+    ? verifyCodexSandboxControllerContext(contextPath, taskId, { repoRoot })
+    : null;
+}
+
+async function prepareCodexOrchestrationDelegation(
+  taskRef: string,
+  input: Readonly<{
+    client: AgentClientId;
+    requestedModel?: string;
+    requestedReasoningEffort?: string;
+    capabilityToken?: string;
+  }>,
+  options: CodexBridgeOptions = {}
+): Promise<OrchestrationResult> {
+  if (input.client !== 'codex') return prepareOrchestrationDelegation(taskRef, input, coreOptions(options));
+  try {
+    const repoRoot = options.repoRoot ?? process.cwd();
+    const resolved = resolveTaskRef(taskRef, { repoRoot });
+    if (!resolved.ok) return bridgeFailure(resolved.code, resolved.message);
+    const preflight = await (options.preflight ?? preflightCodexLifecycleEvidence)(repoRoot);
+    if (!input.capabilityToken) {
+      return bridgeFailure(
+        'ORCHESTRATION_CODEX_CAPABILITY_REQUIRED',
+        'Codex prepare requires a current-session capability token'
+      );
+    }
+    const buildIdentity = options.buildIdentity ?? computeLifecycleBuildIdentity(repoRoot);
+    const controller = controllerContext(resolved.taskId, repoRoot);
+    const capabilityStore = options.capabilityStore ?? createCodexCapabilityStore();
+    const consumed = capabilityStore.consume(input.capabilityToken, {
+      taskId: resolved.taskId,
+      hookDefinitionHash: preflight.hookDefinitionHash,
+      buildIdentity,
+      ...(controller ? { controller: {
+        instanceDigest: controller.controllerInstanceDigest,
+        controlGeneration: controller.controlGeneration
+      } } : {})
+    });
+    return prepareOrchestrationDelegation(taskRef, {
+      ...input,
+      lifecycleProvenance: {
+        ...consumed.buildIdentity,
+        hookDefinitionHash: preflight.hookDefinitionHash,
+        ...preflight.hookProvenance,
+        capabilitySessionId: consumed.sessionId!,
+        capabilityTurnId: consumed.turnId!,
+        capabilityToolUseId: consumed.toolUseId!,
+        controllerInstanceDigest: controller?.controllerInstanceDigest ?? null,
+        controlGeneration: controller?.controlGeneration ?? null
+      }
+    }, coreOptions(options));
+  } catch (error) {
+    return bridgeFailure(
+      error instanceof Error && error.name.startsWith('CODEX_CAPABILITY_')
+        ? error.name
+        : 'ORCHESTRATION_CLIENT_PREFLIGHT_FAILED',
+      error instanceof Error ? error.message : String(error)
+    );
+  }
+}
+
+async function activateCodexOrchestrationDelegation(
+  childThreadId: string,
+  options: CodexBridgeOptions = {}
+): Promise<OrchestrationResult> {
+  try {
+    if (!hasActivatableOrchestrationDelegation('codex', childThreadId, coreOptions(options))) {
+      return bridgeFailure('ORCHESTRATION_DELEGATION_MISSING', 'No matching Codex delegation is active');
+    }
+    const store = requiredStore(options);
+    const resolved = await (options.resolveThread ?? resolveCodexThread)(childThreadId);
+    store.apply(resolved.resolution.thread);
+    for (const reroute of resolved.reroutes) store.apply(reroute);
+    store.apply(resolved.resolution.settings);
+    const record = store.read(childThreadId);
+    const evidence = record.state.startEvidence;
+    if (record.state.status !== 'start-ready' || !evidence) {
+      return pauseBridge('ORCHESTRATION_CODEX_START_EVIDENCE_INVALID', 'Codex lifecycle start evidence is not ready', options);
+    }
+    const repoRoot = options.repoRoot ?? process.cwd();
+    const preflight = await (options.preflight ?? preflightCodexLifecycleEvidence)(repoRoot, {
+      sessionId: evidence.parentThreadId,
+      turnId: evidence.parentTurnId,
+      toolUseId: evidence.spawnToolUseId
+    });
+    const buildIdentity = options.buildIdentity ?? computeLifecycleBuildIdentity(repoRoot);
+    const contextPath = process.env.AGENT_INFRA_CODEX_CONTROLLER_CONTEXT;
+    const contextTaskId = contextPath
+      ? (JSON.parse(fs.readFileSync(contextPath, 'utf8')) as { taskId?: unknown }).taskId
+      : null;
+    if (contextPath && typeof contextTaskId !== 'string') {
+      throw new Error('CODEX_SANDBOX_CONTROLLER_CONTEXT_INVALID');
+    }
+    const controller = contextPath
+      ? verifyCodexSandboxControllerContext(contextPath, contextTaskId as string, { repoRoot })
+      : null;
+    return activateMatchingOrchestrationDelegation('codex', {
+      nativeAgent: evidence.nativeAgent,
+      childId: evidence.childThreadId,
+      parentId: evidence.parentThreadId,
+      spawnMode: evidence.spawnMode,
+      actualModel: evidence.actualModel.value,
+      actualReasoningEffort: evidence.actualReasoningEffort.value,
+      ...(evidence.modelFallbackReason ? { modelFallbackReason: evidence.modelFallbackReason } : {}),
+      ...(evidence.reasoningEffortFallbackReason
+        ? { reasoningEffortFallbackReason: evidence.reasoningEffortFallbackReason }
+        : {}),
+      hostEvidence: {
+        kind: 'codex-lifecycle-v2',
+        hookDefinitionHash: evidence.hookDefinitionHash,
+        startRevision: record.revision,
+        ...buildIdentity,
+        ...preflight.hookProvenance,
+        capabilitySessionId: evidence.parentThreadId,
+        capabilityTurnId: evidence.parentTurnId,
+        spawnToolUseId: evidence.spawnToolUseId,
+        spawnObservedAt: record.spawnObservedAt ?? undefined,
+        controllerInstanceDigest: controller?.controllerInstanceDigest ?? null,
+        controlGeneration: controller?.controlGeneration ?? null
+      }
+    }, coreOptions(options));
+  } catch (error) {
+    return pauseBridge('ORCHESTRATION_CODEX_START_FAILED', error instanceof Error ? error.message : String(error), options);
+  }
+}
+
+async function activateCodexSpawnDelegation(
+  spawn: CodexSpawnIdentity,
+  options: CodexBridgeOptions = {}
+): Promise<OrchestrationResult> {
+  try {
+    const store = requiredStore(options);
+    const childThreadId = resolveCodexSpawnedChild(spawn.transcriptPath, spawn);
+    const resolved = await (options.resolveThread ?? resolveCodexThread)(childThreadId);
+    store.applyToSpawn(spawn, {
+      type: 'hook-child',
+      sessionId: spawn.sessionId,
+      turnId: spawn.turnId,
+      childThreadId,
+      parentThreadId: resolved.resolution.thread.parentThreadId,
+      nativeAgent: spawn.nativeAgent,
+      source: 'parent-rollout'
+    });
+    return activateCodexOrchestrationDelegation(childThreadId, {
+      ...options,
+      store,
+      resolveThread: async () => resolved
+    });
+  } catch (error) {
+    return pauseBridge('ORCHESTRATION_CODEX_START_FAILED', error instanceof Error ? error.message : String(error), options);
+  }
+}
+
+async function sealCodexOrchestrationDelegation(
+  childThreadId: string,
+  options: CodexBridgeOptions = {}
+): Promise<OrchestrationResult> {
+  try {
+    if (!hasSealableOrchestrationDelegation('codex', childThreadId, coreOptions(options))) {
+      return bridgeFailure('ORCHESTRATION_DELEGATION_MISSING', 'No matching Codex delegation is active');
+    }
+    const store = requiredStore(options);
+    const existing = store.read(childThreadId);
+    if (!existing.consumer) {
+      store.apply(await (options.resolveTerminal ?? resolveCodexTerminal)(childThreadId));
+    }
+    const record = store.read(childThreadId);
+    const evidence = record.state.stopEvidence;
+    if (record.state.status !== 'stop-ready' || !evidence || !record.state.startEvidence) {
+      return pauseBridge('ORCHESTRATION_CODEX_STOP_EVIDENCE_INVALID', 'Codex lifecycle stop evidence is not ready', options);
+    }
+    return sealMatchingOrchestrationDelegationWithHostEvidence(
+      'codex',
+      { nativeAgent: record.state.startEvidence.nativeAgent, childId: childThreadId },
+      (receipt) => {
+        const consumed = store.consume(childThreadId, receipt.id, receipt.hostEvidence?.hookDefinitionHash);
+        return {
+          stopRevision: consumed.revision,
+          consumer: consumed.consumer!,
+          consumedAt: consumed.consumedAt!
+        };
+      },
+      coreOptions(options)
+    );
+  } catch (error) {
+    return pauseBridge('ORCHESTRATION_CODEX_STOP_FAILED', error instanceof Error ? error.message : String(error), options);
+  }
+}
+
+async function sealCodexParentDelegation(
+  parentThreadId: string,
+  options: CodexBridgeOptions = {}
+): Promise<OrchestrationResult> {
+  try {
+    const store = requiredStore(options);
+    const candidates = store.findByParent(parentThreadId);
+    if (!candidates.length) return bridgeFailure('ORCHESTRATION_DELEGATION_MISSING', 'No matching Codex delegation is active');
+    for (const consumed of candidates.filter((record) => record.consumer)) {
+      const replayed = await sealCodexOrchestrationDelegation(consumed.state.startEvidence!.childThreadId, options);
+      if (replayed.error?.code !== 'ORCHESTRATION_DELEGATION_MISSING') return replayed;
+    }
+    const active = candidates.find((record) => !record.consumer);
+    if (!active) return bridgeFailure('ORCHESTRATION_DELEGATION_MISSING', 'No matching Codex delegation is active');
+    const start = active.state.startEvidence!;
+    const child = active.state.child!;
+    if (!active.state.terminal) {
+      store.apply(await (options.resolveTerminal ?? resolveCodexTerminal)(start.childThreadId));
+    }
+    if (!store.read(start.childThreadId).state.stop) {
+      store.apply({
+        type: 'hook-stop',
+        sessionId: parentThreadId,
+        turnId: child.turnId,
+        childThreadId: start.childThreadId,
+        nativeAgent: start.nativeAgent,
+        source: 'parent-rollout'
+      });
+    }
+    return sealCodexOrchestrationDelegation(start.childThreadId, options);
+  } catch (error) {
+    if (error instanceof Error && error.message === 'CODEX_TURN_NOT_TERMINAL') {
+      return bridgeFailure('ORCHESTRATION_DELEGATION_MISSING', 'The matching Codex child has not completed');
+    }
+    return pauseBridge('ORCHESTRATION_CODEX_STOP_FAILED', error instanceof Error ? error.message : String(error), options);
+  }
+}
+
+function reconcileCodexOrchestrationDelegation(
+  childThreadId: string,
+  options: CodexBridgeOptions = {}
+): OrchestrationResult {
+  return reconcileMatchingOrchestrationDelegation('codex', childThreadId, coreOptions(options));
+}
+
+export {
+  activateCodexOrchestrationDelegation,
+  activateCodexSpawnDelegation,
+  prepareCodexOrchestrationDelegation,
+  reconcileCodexOrchestrationDelegation,
+  sealCodexParentDelegation,
+  sealCodexOrchestrationDelegation
+};
+export type { CodexBridgeOptions };

package/lib/task/commands/status.ts

@@ -71,6 +71,7 @@ const STAGE_ORDER = [
   'review-plan',
   'code',
   'review-code',
+  'validation-run',
   'task',
   'other'
 ] as const;
@@ -81,6 +82,7 @@ function stageOf(name: string): string {
   if (stem.startsWith('review-analysis')) return 'review-analysis';
   if (stem.startsWith('review-plan')) return 'review-plan';
   if (stem.startsWith('review-code')) return 'review-code';
+  if (stem.startsWith('validation-run')) return 'validation-run';
   if (stem.startsWith('analysis')) return 'analysis';
   if (stem.startsWith('plan')) return 'plan';
   if (stem.startsWith('code')) return 'code';

package/lib/task/commands/validate.ts

@@ -0,0 +1,282 @@
+import { execFileSync, spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { loadConfig } from '../../sandbox/config.ts';
+import { detectEngine } from '../../sandbox/engine.ts';
+import { runEngine } from '../../sandbox/shell.ts';
+import { sandboxBranchLabel, sandboxLabel } from '../../sandbox/constants.ts';
+import { fetchSandboxRows, selectSandboxContainer } from '../../sandbox/commands/list-running.ts';
+import { containerNameCandidates } from '../../sandbox/constants.ts';
+import { resolveSandboxTarget } from '../../sandbox/workspace-identity.ts';
+import { sandboxControlPaths } from '../../sandbox/workspace-view.ts';
+import {
+  appendSandboxControlAudit,
+  readActiveLease,
+  readSandboxControlStatus
+} from '../../sandbox/control/state.ts';
+import type { SandboxControlLease, SandboxControlManifest } from '../../sandbox/control/protocol.ts';
+import {
+  SANDBOX_CONTROL_FUTURE_SKEW_MS,
+  SANDBOX_CONTROL_STATUS_STALE_MS
+} from '../../sandbox/control/protocol.ts';
+import { getProcessStartTime } from '../../server/process-state.ts';
+import { assertGitWorktreeBinding } from '../../git/worktree-identity.ts';
+
+const USAGE = `Usage: ai task validate <branch | TASK-id | N> [--scope snapshot|inplace] [--timeout <ms>] [--format text|json] -- <command> [args...]`;
+const MAX_TIMEOUT_MS = 60 * 60 * 1000;
+const RECOVERY_GRACE_MS = 30_000;
+
+type ValidateOptions = {
+  target: string;
+  scope: 'snapshot' | 'inplace';
+  timeoutMs: number;
+  format: 'text' | 'json';
+  command: string[];
+  help: boolean;
+};
+
+export function parseValidateArgs(args: string[]): ValidateOptions {
+  if (args.includes('--help') || args.includes('-h')) {
+    return { target: '', scope: 'snapshot', timeoutMs: 300_000, format: 'text', command: [], help: true };
+  }
+  const separator = args.indexOf('--');
+  if (separator < 0) throw new Error(`${USAGE}\nA literal -- must separate validation options from the command.`);
+  const optionArgs = args.slice(0, separator);
+  const command = args.slice(separator + 1);
+  let scope: ValidateOptions['scope'] = 'snapshot';
+  let timeoutMs = 300_000;
+  let format: ValidateOptions['format'] = 'text';
+  const positionals: string[] = [];
+  for (let index = 0; index < optionArgs.length; index += 1) {
+    const arg = optionArgs[index]!;
+    if (arg === '--scope') {
+      const value = optionArgs[++index];
+      if (value !== 'snapshot' && value !== 'inplace') throw new Error('validate --scope must be snapshot or inplace');
+      scope = value;
+    } else if (arg === '--timeout') {
+      const value = Number(optionArgs[++index]);
+      if (!Number.isSafeInteger(value) || value <= 0 || value > MAX_TIMEOUT_MS) throw new Error(`validate --timeout must be 1..${MAX_TIMEOUT_MS}`);
+      timeoutMs = value;
+    } else if (arg === '--format') {
+      const value = optionArgs[++index];
+      if (value !== 'text' && value !== 'json') throw new Error('validate --format must be text or json');
+      format = value;
+    } else if (arg.startsWith('-')) {
+      throw new Error(`Unknown option: ${arg}`);
+    } else {
+      positionals.push(arg);
+    }
+  }
+  if (positionals.length !== 1 || command.length === 0) throw new Error(USAGE);
+  return { target: positionals[0]!, scope, timeoutMs, format, command, help: false };
+}
+
+function runValidationCommand(command: string[], cwd: string, scope: string, timeoutMs: number, json: boolean) {
+  const [file, ...args] = command;
+  const result = spawnSync(file!, args, {
+    cwd,
+    env: { ...process.env, AGENT_INFRA_VALIDATION_SCOPE: scope },
+    encoding: 'utf8',
+    timeout: timeoutMs,
+    stdio: ['inherit', 'pipe', 'pipe'],
+    shell: process.platform === 'win32' && /\.(?:bat|cmd)$/i.test(file!)
+  });
+  if (json) {
+    if (result.stdout) process.stderr.write(result.stdout);
+    if (result.stderr) process.stderr.write(result.stderr);
+  } else {
+    if (result.stdout) process.stdout.write(result.stdout);
+    if (result.stderr) process.stderr.write(result.stderr);
+  }
+  return { exitCode: result.status ?? 1, signal: result.signal ?? null };
+}
+
+function git(root: string, args: string[]): string {
+  return execFileSync('git', args, { cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim();
+}
+
+function waitForState(statusDir: string, predicate: (state: ReturnType<typeof readSandboxControlStatus>) => boolean, timeoutMs = 5_000): void {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    try {
+      const status = readSandboxControlStatus(statusDir);
+      if (predicate(status)) return;
+    } catch {
+      // Atomic status publication may be between renames.
+    }
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 25);
+  }
+  throw new Error('SANDBOX_VALIDATION_BROKER_STATE_TIMEOUT');
+}
+
+function snapshotValidation(repoRoot: string, commit: string, options: ValidateOptions) {
+  const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-infra-validation-'));
+  const worktree = path.join(tempRoot, 'worktree');
+  let cleanup = 'not-created';
+  try {
+    git(repoRoot, ['worktree', 'add', '--detach', worktree, commit]);
+    cleanup = 'pending';
+    return { ...runValidationCommand(options.command, worktree, 'snapshot', options.timeoutMs, options.format === 'json'), cleanup: () => cleanup };
+  } finally {
+    let cleanupError: unknown = null;
+    if (fs.existsSync(worktree)) {
+      try {
+        git(repoRoot, ['worktree', 'remove', '--force', worktree]);
+        cleanup = 'completed';
+      } catch (error) {
+        cleanupError = error;
+      }
+    }
+    try {
+      git(repoRoot, ['worktree', 'prune']);
+    } catch (error) {
+      cleanupError ??= error;
+    }
+    try {
+      fs.rmSync(tempRoot, { recursive: true, force: true });
+    } catch (error) {
+      cleanupError ??= error;
+    }
+    if (cleanupError) throw cleanupError;
+  }
+}
+
+function inplaceValidation(config: ReturnType<typeof loadConfig>, target: ReturnType<typeof resolveSandboxTarget>, options: ValidateOptions) {
+  const engine = detectEngine(config);
+  const { running, nonRunning } = fetchSandboxRows(engine, sandboxLabel(config), sandboxBranchLabel(config));
+  const row = selectSandboxContainer([...running, ...nonRunning], containerNameCandidates(config, target.branch));
+  if (!row) throw new Error('SANDBOX_VALIDATION_CONTAINER_NOT_FOUND');
+  const control = sandboxControlPaths({
+    base: config.controlBase, project: config.project,
+    container: row.name, identity: target.workspace
+  });
+  const manifest = JSON.parse(fs.readFileSync(control.manifestPath, 'utf8')) as SandboxControlManifest;
+  const initial = readSandboxControlStatus(control.statusDir);
+  const now = Date.now();
+  if (initial.generation !== manifest.generation
+    || now - initial.updatedAt > SANDBOX_CONTROL_STATUS_STALE_MS
+    || initial.updatedAt > now + SANDBOX_CONTROL_FUTURE_SKEW_MS) {
+    throw new Error('SANDBOX_VALIDATION_BROKER_STATUS_STALE');
+  }
+  if (initial.state !== 'healthy' || initial.activeRequestId !== null) {
+    throw new Error('SANDBOX_VALIDATION_BROKER_NOT_IDLE');
+  }
+  const startTime = getProcessStartTime(process.pid);
+  if (!startTime) throw new Error('SANDBOX_VALIDATION_OWNER_IDENTITY_UNAVAILABLE');
+  const leasePath = path.join(control.root, 'lease.json');
+  const nonce = randomUUID();
+  const issuedAt = Date.now();
+  const lease: SandboxControlLease = {
+    version: 2, generation: manifest.generation, nonce,
+    owner: { pid: process.pid, startTime }, issuedAt,
+    expiresAt: issuedAt + Math.min(options.timeoutMs + RECOVERY_GRACE_MS, MAX_TIMEOUT_MS + RECOVERY_GRACE_MS),
+    taskId: target.workspace.mode === 'task-bound' ? target.workspace.taskId : null,
+    branch: target.branch, reason: 'manual-validation'
+  };
+  const originalBranch = git(manifest.worktreeRoot, ['symbolic-ref', '--quiet', '--short', 'HEAD']);
+  const originalHead = git(manifest.worktreeRoot, ['rev-parse', 'HEAD']);
+  fs.writeFileSync(leasePath, `${JSON.stringify(lease)}\n`, { flag: 'wx', mode: 0o600 });
+  let stopped = false;
+  let restored = false;
+  try {
+    appendSandboxControlAudit(manifest, 'lease-acquire', { ownerPid: process.pid });
+    waitForState(control.statusDir, (status) => status.state === 'parked' && status.reasonCode === 'SANDBOX_CONTROL_HANDOFF_ACTIVE');
+    if (row.running) {
+      runEngine(engine, 'docker', ['stop', row.name]);
+      stopped = true;
+    }
+    const refreshedRows = fetchSandboxRows(engine, sandboxLabel(config), sandboxBranchLabel(config));
+    const refreshed = selectSandboxContainer(
+      [...refreshedRows.running, ...refreshedRows.nonRunning],
+      containerNameCandidates(config, target.branch)
+    );
+    if (!refreshed || refreshed.running) throw new Error('SANDBOX_VALIDATION_CONTAINER_STILL_RUNNING');
+    const activeLease = readActiveLease(manifest);
+    if (!activeLease || activeLease.nonce !== nonce) throw new Error('SANDBOX_VALIDATION_LEASE_OWNERSHIP_LOST');
+    assertGitWorktreeBinding(config.repoRoot, manifest.worktreeRoot, target.branch);
+    const result = runValidationCommand(options.command, manifest.worktreeRoot, 'inplace', options.timeoutMs, options.format === 'json');
+    return { ...result, cleanup: () => restored ? 'completed' : 'pending' };
+  } finally {
+    const recoveryErrors: string[] = [];
+    try {
+      const currentBranch = git(manifest.worktreeRoot, ['symbolic-ref', '--quiet', '--short', 'HEAD']);
+      if (currentBranch !== originalBranch) git(manifest.worktreeRoot, ['switch', originalBranch]);
+    } catch {
+      try {
+        git(manifest.worktreeRoot, ['checkout', '--detach', originalHead]);
+        git(manifest.worktreeRoot, ['switch', originalBranch]);
+      } catch (fallbackError) {
+        recoveryErrors.push(`git binding restore failed: ${fallbackError instanceof Error ? fallbackError.message : String(fallbackError)}`);
+      }
+    }
+    if (stopped) {
+      try {
+        runEngine(engine, 'docker', ['start', row.name]);
+      } catch (error) {
+        recoveryErrors.push(`container start failed: ${error instanceof Error ? error.message : String(error)}`);
+      }
+    }
+    try {
+      const currentLease = JSON.parse(fs.readFileSync(leasePath, 'utf8')) as { nonce?: unknown };
+      if (currentLease.nonce !== nonce) throw new Error('SANDBOX_VALIDATION_LEASE_OWNERSHIP_LOST');
+    } catch (error) {
+      recoveryErrors.push(error instanceof Error ? error.message : String(error));
+    }
+    if (recoveryErrors.length === 0) {
+      try {
+        fs.unlinkSync(leasePath);
+        appendSandboxControlAudit(manifest, 'lease-release', { ownerPid: process.pid });
+        waitForState(control.statusDir, (status) => status.state === 'healthy');
+        restored = true;
+      } catch (error) {
+        try {
+          if (!fs.existsSync(leasePath)) {
+            fs.writeFileSync(leasePath, `${JSON.stringify(lease)}\n`, { flag: 'wx', mode: 0o600 });
+          }
+          appendSandboxControlAudit(manifest, 'lease-release-failed', { ownerPid: process.pid });
+        } catch (leaseError) {
+          recoveryErrors.push(`lease preservation failed: ${leaseError instanceof Error ? leaseError.message : String(leaseError)}`);
+        }
+        recoveryErrors.push(error instanceof Error ? error.message : String(error));
+      }
+    }
+    if (recoveryErrors.length > 0) {
+      throw new Error(
+        `SANDBOX_VALIDATION_RECOVERY_INCOMPLETE: ${recoveryErrors.join('; ')}; run 'ai sandbox start ${target.branch}'`
+      );
+    }
+  }
+}
+
+export async function validate(args: string[]): Promise<number> {
+  const options = parseValidateArgs(args);
+  if (options.help) {
+    process.stdout.write(`${USAGE}\n`);
+    return 0;
+  }
+  const config = loadConfig();
+  const target = resolveSandboxTarget(options.target, config.repoRoot);
+  const commit = git(config.repoRoot, ['rev-parse', target.branch]);
+  const startedAt = new Date().toISOString();
+  const result = options.scope === 'snapshot'
+    ? snapshotValidation(config.repoRoot, commit, options)
+    : inplaceValidation(config, target, options);
+  const evidence = {
+    version: 1,
+    taskId: target.workspace.mode === 'task-bound' ? target.workspace.taskId : null,
+    branch: target.branch,
+    scope: options.scope,
+    commit,
+    command: path.basename(options.command[0]!),
+    startedAt,
+    completedAt: new Date().toISOString(),
+    exitCode: result.exitCode,
+    signal: result.signal,
+    cleanup: result.cleanup()
+  };
+  if (options.format === 'json') process.stdout.write(`${JSON.stringify(evidence)}\n`);
+  else process.stdout.write(`Validation ${result.exitCode === 0 ? 'passed' : 'failed'} (${options.scope}, ${evidence.command}, cleanup=${evidence.cleanup}).\n`);
+  return result.exitCode;
+}