@fitlab-ai/agent-infra 0.9.7 → 0.9.9

package/lib/sandbox/task-resolver.ts

@@ -5,7 +5,14 @@ import { isRemovedHashShortIdInput } from '../task/short-id.ts';
 
 const TASK_ID_RE = /^TASK-\d{8}-\d{6}$/;
 const SHORT_ID_RE = /^\d+$/;
-const WORKSPACE_DIRS = ['active', 'completed', 'blocked', 'archive'];
+export const TASK_WORKSPACE_STATES = ['active', 'completed', 'blocked', 'archive'] as const;
+export type TaskWorkspaceState = typeof TASK_WORKSPACE_STATES[number];
+export type TaskWorkspace = Readonly<{
+  taskId: string;
+  branch: string;
+  state: TaskWorkspaceState;
+  taskMd: string;
+}>;
 
 function resolveShortIdStrict(arg: string, repoRoot: string): string {
   const scriptPath = path.join(repoRoot, '.agents', 'scripts', 'task-short-id.js');
@@ -27,16 +34,30 @@ function stripQuotes(value: string): string {
   return value.replace(/^(["'])(.*)\1$/, '$2');
 }
 
-function readTaskContent(repoRoot: string, taskId: string): string {
-  for (const dir of WORKSPACE_DIRS) {
-    const taskPath = path.join(repoRoot, '.agents', 'workspace', dir, taskId, 'task.md');
+function readTaskContent(repoRoot: string, taskId: string): { content: string; state: TaskWorkspaceState; taskMd: string } {
+  for (const state of TASK_WORKSPACE_STATES) {
+    const taskPath = path.join(repoRoot, '.agents', 'workspace', state, taskId, 'task.md');
     if (fs.existsSync(taskPath)) {
-      return fs.readFileSync(taskPath, 'utf8');
+      return { content: fs.readFileSync(taskPath, 'utf8'), state, taskMd: taskPath };
     }
   }
   throw new Error(`Task not found: ${taskId}`);
 }
 
+function taskWorkspaceCandidates(repoRoot: string, taskId: string): TaskWorkspace[] {
+  return TASK_WORKSPACE_STATES.flatMap((state) => {
+    const taskMd = path.join(repoRoot, '.agents', 'workspace', state, taskId, 'task.md');
+    if (!fs.existsSync(taskMd)) return [];
+    const content = fs.readFileSync(taskMd, 'utf8');
+    return [{
+      taskId,
+      branch: resolveBranchFromTaskContent(content, taskId),
+      state,
+      taskMd
+    }];
+  });
+}
+
 function resolveBranchFromTaskContent(content: string, taskId: string): string {
   const frontmatterBranch = content.match(/^branch:\s*(.+)$/m);
   if (frontmatterBranch?.[1]?.trim()) {
@@ -57,12 +78,42 @@ export function resolveTaskBranch(arg: string, repoRoot: string): string {
   }
   if (SHORT_ID_RE.test(arg)) {
     const taskId = resolveShortIdStrict(arg, repoRoot);
-    const content = readTaskContent(repoRoot, taskId);
+    const { content } = readTaskContent(repoRoot, taskId);
     return resolveBranchFromTaskContent(content, taskId);
   }
   if (!TASK_ID_RE.test(arg)) {
     return arg;
   }
-  const content = readTaskContent(repoRoot, arg);
+  const { content } = readTaskContent(repoRoot, arg);
   return resolveBranchFromTaskContent(content, arg);
 }
+
+export function resolveTaskWorkspace(taskId: string, repoRoot: string): TaskWorkspace {
+  if (!TASK_ID_RE.test(taskId)) throw new Error(`Invalid task id: ${taskId}`);
+  const matches = taskWorkspaceCandidates(repoRoot, taskId);
+  if (matches.length === 0) throw new Error(`Task not found: ${taskId}`);
+  if (matches.length !== 1) {
+    throw new Error(
+      `SANDBOX_TASK_STATE_AMBIGUOUS: task ${taskId} exists in ${matches.map((match) => match.state).join(', ')}`
+    );
+  }
+  return matches[0]!;
+}
+
+export function listTaskWorkspaces(repoRoot: string, state: TaskWorkspaceState): TaskWorkspace[] {
+  const stateRoot = path.join(repoRoot, '.agents', 'workspace', state);
+  if (!fs.existsSync(stateRoot)) return [];
+  return fs.readdirSync(stateRoot, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory() && TASK_ID_RE.test(entry.name))
+    .flatMap((entry) => {
+      const taskMd = path.join(stateRoot, entry.name, 'task.md');
+      if (!fs.existsSync(taskMd)) return [];
+      const content = fs.readFileSync(taskMd, 'utf8');
+      return [{
+        taskId: entry.name,
+        branch: resolveBranchFromTaskContent(content, entry.name),
+        state,
+        taskMd
+      }];
+    });
+}

package/lib/sandbox/workspace-identity.ts

@@ -1,6 +1,10 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { isRemovedHashShortIdInput } from '../task/short-id.ts';
+import {
+  resolveTaskWorkspace,
+  type TaskWorkspaceState
+} from './task-resolver.ts';
 
 const TASK_ID_RE = /^TASK-\d{8}-\d{6}$/;
 const SHORT_ID_RE = /^\d+$/;
@@ -9,6 +13,17 @@ export type SandboxWorkspaceIdentity =
   | Readonly<{ mode: 'task-bound'; taskId: string; shortId: string }>
   | Readonly<{ mode: 'branch-only' }>;
 
+export type SandboxWorkspaceKey =
+  | Readonly<{ mode: 'task-bound'; taskId: string }>
+  | Readonly<{ mode: 'branch-only' }>;
+
+export type SandboxCleanupTarget = Readonly<{
+  requestedRef: string;
+  branch: string;
+  workspace: SandboxWorkspaceKey;
+  taskState: TaskWorkspaceState | 'branch-only';
+}>;
+
 export type SandboxContainerWorkspaceIdentity =
   | Readonly<{ mode: 'task-bound'; taskId: string }>
   | Readonly<{ mode: 'branch-only' }>
@@ -101,6 +116,39 @@ export function resolveSandboxTarget(requestedRef: string, repoRoot: string): Sa
   return { requestedRef, branch: requestedRef, workspace: { mode: 'branch-only' } };
 }
 
+export function resolveSandboxCleanupTarget(
+  requestedRef: string,
+  repoRoot: string,
+  options: Readonly<{ allowProtected?: boolean }> = {}
+): SandboxCleanupTarget {
+  if (isRemovedHashShortIdInput(requestedRef)) {
+    throw new Error(`Invalid task short id '${requestedRef}': task short ids must use bare digits`);
+  }
+
+  if (TASK_ID_RE.test(requestedRef)) {
+    const task = resolveTaskWorkspace(requestedRef, repoRoot);
+    if (!options.allowProtected && (task.state === 'blocked' || task.state === 'archive')) {
+      throw new Error(`SANDBOX_CLEANUP_STATE_UNSUPPORTED: task ${requestedRef} is ${task.state}`);
+    }
+    return {
+      requestedRef,
+      branch: task.branch,
+      workspace: { mode: 'task-bound', taskId: task.taskId },
+      taskState: task.state
+    };
+  }
+
+  const target = resolveSandboxTarget(requestedRef, repoRoot);
+  return {
+    requestedRef,
+    branch: target.branch,
+    workspace: target.workspace.mode === 'task-bound'
+      ? { mode: 'task-bound', taskId: target.workspace.taskId }
+      : { mode: 'branch-only' },
+    taskState: target.workspace.mode === 'task-bound' ? 'active' : 'branch-only'
+  };
+}
+
 export function parseSandboxWorkspaceIdentity(
   labels: Readonly<Record<string, string>>,
   keys: Readonly<{ mode: string; taskId: string }>
@@ -115,8 +163,8 @@ export function parseSandboxWorkspaceIdentity(
 }
 
 export function sameSandboxWorkspaceIdentity(
-  left: SandboxWorkspaceIdentity | SandboxContainerWorkspaceIdentity,
-  right: SandboxWorkspaceIdentity | SandboxContainerWorkspaceIdentity
+  left: SandboxWorkspaceIdentity | SandboxWorkspaceKey | SandboxContainerWorkspaceIdentity,
+  right: SandboxWorkspaceIdentity | SandboxWorkspaceKey | SandboxContainerWorkspaceIdentity
 ): boolean {
   return left.mode === right.mode
     && (left.mode !== 'task-bound' || (right.mode === 'task-bound' && left.taskId === right.taskId));

package/lib/sandbox/workspace-view.ts

@@ -1,7 +1,7 @@
 import { createHash, randomBytes } from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
-import type { SandboxWorkspaceIdentity } from './workspace-identity.ts';
+import type { SandboxWorkspaceIdentity, SandboxWorkspaceKey } from './workspace-identity.ts';
 import type { SandboxControlManifest } from './control/protocol.ts';
 
 export type SandboxWorkspaceView = Readonly<{
@@ -30,7 +30,7 @@ export function sandboxWorkspaceViewPaths(params: Readonly<{
   base: string;
   project: string;
   container: string;
-  identity: SandboxWorkspaceIdentity;
+  identity: SandboxWorkspaceIdentity | SandboxWorkspaceKey;
 }>): SandboxWorkspaceView {
   const identityKey = params.identity.mode === 'task-bound'
     ? `task-bound:${params.identity.taskId}`
@@ -50,6 +50,7 @@ export type SandboxControlSetup = Readonly<{
   root: string;
   channelDir: string;
   statusDir: string;
+  runtimeDir: string;
   manifestPath: string;
   token: string;
   generation: string;
@@ -59,8 +60,8 @@ export function sandboxControlPaths(params: Readonly<{
   base: string;
   project: string;
   container: string;
-  identity: SandboxWorkspaceIdentity;
-}>): Readonly<{ root: string; channelDir: string; statusDir: string; processingDir: string; manifestPath: string }> {
+  identity: SandboxWorkspaceIdentity | SandboxWorkspaceKey;
+}>): Readonly<{ root: string; channelDir: string; statusDir: string; processingDir: string; runtimeDir: string; manifestPath: string }> {
   const identityKey = params.identity.mode === 'task-bound'
     ? `task-bound:${params.identity.taskId}`
     : 'branch-only';
@@ -71,6 +72,7 @@ export function sandboxControlPaths(params: Readonly<{
     channelDir: path.join(root, 'channel'),
     statusDir: path.join(root, 'public'),
     processingDir: path.join(root, 'processing'),
+    runtimeDir: path.join(root, 'runtime'),
     manifestPath: path.join(root, 'manifest.json')
   };
 }
@@ -85,6 +87,32 @@ function assertSafeDirectory(directory: string, expectedBase: string): void {
   }
 }
 
+function assertSafeMountTargetPath(
+  target: string,
+  worktreeRoot: string,
+  canonicalWorktreeRoot: string
+): void {
+  const relative = path.relative(worktreeRoot, target);
+  if (relative.startsWith('..') || path.isAbsolute(relative)) {
+    throw new Error(`Sandbox workspace mount target escapes its worktree: ${target}`);
+  }
+  let current = worktreeRoot;
+  for (const segment of ['', ...relative.split(path.sep).filter(Boolean)]) {
+    current = segment ? path.join(current, segment) : current;
+    try {
+      if (fs.lstatSync(current).isSymbolicLink()) {
+        throw new Error(`Sandbox workspace mount target must not contain a symbolic link: ${current}`);
+      }
+      const canonicalRelative = path.relative(canonicalWorktreeRoot, fs.realpathSync.native(current));
+      if (canonicalRelative.startsWith('..') || path.isAbsolute(canonicalRelative)) {
+        throw new Error(`Sandbox workspace mount target escapes its real worktree: ${current}`);
+      }
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error;
+    }
+  }
+}
+
 export function assertSandboxTaskSource(repoRoot: string, taskId: string): string {
   if (!/^TASK-\d{8}-\d{6}$/.test(taskId)) throw new Error('SANDBOX_TASK_SOURCE_INVALID');
   const activeRoot = fs.realpathSync.native(path.join(repoRoot, '.agents', 'workspace', 'active'));
@@ -100,41 +128,22 @@ export function assertSandboxTaskSource(repoRoot: string, taskId: string): strin
   return canonical;
 }
 
-export function prepareSandboxWorkspaceMountTarget(worktreeRoot: string): string {
-  const worktree = path.resolve(worktreeRoot);
-  const canonicalWorktree = fs.realpathSync.native(worktree);
-  const agentsRoot = path.join(worktree, '.agents');
-  if (fs.existsSync(agentsRoot)) {
-    const agentsStat = fs.lstatSync(agentsRoot);
-    if (!agentsStat.isDirectory() || agentsStat.isSymbolicLink()) {
-      throw new Error(`Sandbox workspace mount ancestor must be a real directory: ${agentsRoot}`);
-    }
-  } else {
-    fs.mkdirSync(agentsRoot, { mode: 0o700 });
+export function prepareSandboxWorkspaceMountTargets(worktreeRoot: string): void {
+  const resolvedWorktreeRoot = path.resolve(worktreeRoot);
+  const canonicalWorktreeRoot = fs.realpathSync.native(resolvedWorktreeRoot);
+  const workspaceRoot = path.resolve(resolvedWorktreeRoot, '.agents', 'workspace');
+  const statePaths = sandboxWorkspaceViewStatePaths(workspaceRoot);
+  const registryTarget = path.join(workspaceRoot, 'active', '.short-ids.json');
+  for (const target of [workspaceRoot, ...statePaths.map(({ hostPath }) => hostPath), registryTarget]) {
+    assertSafeMountTargetPath(target, resolvedWorktreeRoot, canonicalWorktreeRoot);
   }
-  const canonicalAgents = fs.realpathSync.native(agentsRoot);
-  if (path.dirname(canonicalAgents) !== canonicalWorktree) {
-    throw new Error(`Sandbox workspace mount ancestor escapes the worktree: ${agentsRoot}`);
-  }
-
-  const target = path.join(agentsRoot, 'workspace');
-  if (fs.existsSync(target)) {
-    const stat = fs.lstatSync(target);
-    if (stat.isSymbolicLink()) {
-      throw new Error(`Sandbox workspace mount target must not be a symbolic link: ${target}`);
-    }
-    if (!stat.isDirectory()) {
-      throw new Error(`Sandbox workspace mount target must be a directory: ${target}`);
-    }
-    if (path.dirname(fs.realpathSync.native(target)) !== canonicalAgents) {
-      throw new Error(`Sandbox workspace mount target escapes the worktree: ${target}`);
-    }
-  } else {
-    fs.mkdirSync(target, { mode: 0o700 });
+  fs.mkdirSync(workspaceRoot, { recursive: true, mode: 0o700 });
+  for (const { hostPath } of statePaths) {
+    fs.mkdirSync(hostPath, { recursive: true, mode: 0o700 });
+    fs.chmodSync(hostPath, 0o700);
   }
-  fs.chmodSync(target, 0o700);
-  fs.accessSync(target, fs.constants.W_OK);
-  return target;
+  fs.chmodSync(workspaceRoot, 0o700);
+  fs.closeSync(fs.openSync(registryTarget, 'a', 0o600));
 }
 
 export function materializeSandboxWorkspaceView(params: Readonly<{
@@ -181,16 +190,36 @@ export function materializeSandboxControl(params: Readonly<{
   branch: string;
   identity: SandboxWorkspaceIdentity;
   engine?: string;
+  replacementLease?: Readonly<{
+    root: string;
+    assertOwned(): void;
+  }>;
 }>): SandboxControlSetup {
-  const { root, channelDir, statusDir, processingDir, manifestPath } = sandboxControlPaths(params);
+  const { root, channelDir, statusDir, processingDir, runtimeDir, manifestPath } = sandboxControlPaths(params);
   assertSafeDirectory(root, path.resolve(params.base));
+  if (fs.existsSync(root)) {
+    if (!params.replacementLease || path.resolve(params.replacementLease.root) !== root) {
+      throw new Error('SANDBOX_CONTROL_REPLACEMENT_REQUIRED');
+    }
+    params.replacementLease.assertOwned();
+  }
   const consumedDir = path.join(root, 'consumed');
   assertSafeDirectory(consumedDir, root);
   fs.rmSync(consumedDir, { recursive: true, force: true });
   fs.mkdirSync(consumedDir, { recursive: true, mode: 0o700 });
-  for (const directory of [statusDir, processingDir]) {
+  for (const directory of [statusDir, processingDir, runtimeDir]) {
     assertSafeDirectory(directory, root);
+    if (directory === runtimeDir) fs.rmSync(directory, { recursive: true, force: true });
+    fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
+  }
+  for (const directory of [
+    path.join(runtimeDir, 'clients'),
+    path.join(runtimeDir, 'clients', 'codex', 'capabilities'),
+    path.join(runtimeDir, 'clients', 'codex', 'lifecycle')
+  ]) {
+    assertSafeDirectory(directory, runtimeDir);
     fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
+    fs.chmodSync(directory, 0o700);
   }
   for (const queue of ['requests', 'responses']) {
     const directory = path.join(channelDir, queue);
@@ -202,7 +231,7 @@ export function materializeSandboxControl(params: Readonly<{
   const generation = randomBytes(16).toString('hex');
   const repoRoot = fs.realpathSync.native(params.repoRoot);
   const manifest: SandboxControlManifest = {
-    version: 4,
+    version: 5,
     engine: params.engine ?? 'docker',
     repoRoot,
     worktreeRoot: fs.realpathSync.native(params.worktreeRoot),
@@ -216,10 +245,11 @@ export function materializeSandboxControl(params: Readonly<{
     generation,
     channelDir,
     publicStatusDir: statusDir,
-    processingDir
+    processingDir,
+    runtimeDir
   };
   fs.writeFileSync(manifestPath, `${JSON.stringify(manifest)}\n`, { mode: 0o600 });
-  return { root, channelDir, statusDir, manifestPath, token, generation };
+  return { root, channelDir, statusDir, runtimeDir, manifestPath, token, generation };
 }
 
 export function finalizeSandboxControlManifest(
@@ -228,7 +258,7 @@ export function finalizeSandboxControlManifest(
 ): void {
   if (!identity.engine || !identity.id) throw new Error('SANDBOX_CONTROL_CONTAINER_ID_INVALID');
   const manifest = JSON.parse(fs.readFileSync(setup.manifestPath, 'utf8')) as Record<string, unknown>;
-  manifest.version = 4;
+  manifest.version = 5;
   manifest.engine = identity.engine;
   manifest.containerIdentity = { id: identity.id, labels: { ...identity.labels } };
   const temporary = `${setup.manifestPath}.${process.pid}.${randomBytes(8).toString('hex')}.tmp`;

package/lib/sandbox/worktree-safety.ts

@@ -1,7 +1,9 @@
 import { createHash } from 'node:crypto';
 import fs from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
 import { runProbe } from './shell.ts';
+import { resolveSandboxTarget } from './workspace-identity.ts';
 
 type WorktreeChange = {
   indexStatus: string;
@@ -16,6 +18,8 @@ type WorktreeSnapshot = {
   head: string;
   changes: readonly WorktreeChange[];
   identity: string;
+  source?: 'registered' | 'recovered';
+  recovery?: WorktreeRecoveryContext;
 };
 
 type WorktreeInspection =
@@ -28,6 +32,14 @@ type WorktreeRemovalPermit = {
   snapshot: WorktreeSnapshot;
 };
 
+type WorktreeRecoveryContext = Readonly<{
+  repoRoot: string;
+  worktreeBase: string;
+  branch: string;
+  identitySource: 'branch-only' | 'task-bound';
+  taskId: string | null;
+}>;
+
 type Probe = typeof runProbe;
 
 function probeText(probe: Probe, cwd: string, args: string[]): string {
@@ -164,6 +176,203 @@ function captureOnce(worktree: string, probe: Probe): WorktreeSnapshot {
   return { worktree: resolvedWorktree, branch, head, changes, identity: hash.digest('hex') };
 }
 
+function probeTextWithEnv(
+  probe: Probe,
+  repoRoot: string,
+  args: string[],
+  env: NodeJS.ProcessEnv
+): string {
+  const result = probe('git', args, { cwd: repoRoot, encoding: 'utf8', env });
+  if (result.error) throw result.error;
+  if (result.status !== 0) {
+    const stderr = typeof result.stderr === 'string' ? result.stderr.trim() : result.stderr.toString('utf8').trim();
+    throw new Error(stderr || `git ${args[0] ?? 'command'} failed with exit code ${result.status ?? 'unknown'}`);
+  }
+  return typeof result.stdout === 'string' ? result.stdout : result.stdout.toString('utf8');
+}
+
+function probeMetadataCommand(
+  probe: Probe,
+  repoRoot: string,
+  args: string[],
+  env: NodeJS.ProcessEnv
+): boolean {
+  const result = probe('git', args, { cwd: repoRoot, encoding: 'utf8', env });
+  if (result.error) throw result.error;
+  return result.status === 0;
+}
+
+function hasValidHeadContent(content: string): boolean {
+  return /^(?:ref:\s+refs\/\S+|[0-9a-f]{40}|[0-9a-f]{64})$/i.test(content.trim());
+}
+
+function assertRecoverableMetadata(worktree: string, repoRoot: string, probe: Probe): void {
+  const dotGit = path.join(worktree, '.git');
+  let dotGitStat: fs.Stats;
+  try {
+    dotGitStat = fs.lstatSync(dotGit);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return;
+    throw error;
+  }
+  if (dotGitStat.isSymbolicLink() || dotGitStat.isDirectory()) {
+    throw new Error('WORKTREE_RECOVERY_METADATA_NOT_ELIGIBLE');
+  }
+  if (!dotGitStat.isFile()) throw new Error('WORKTREE_RECOVERY_METADATA_INVALID');
+
+  const content = fs.readFileSync(dotGit, 'utf8').trim();
+  const match = /^gitdir:\s*(.+)$/i.exec(content);
+  if (!match) throw new Error('WORKTREE_RECOVERY_METADATA_INVALID');
+
+  const commonDir = fs.realpathSync.native(path.resolve(repoRoot, probeText(probe, repoRoot, [
+    'rev-parse', '--git-common-dir'
+  ]).trim()));
+  const adminRoot = path.join(commonDir, 'worktrees');
+  const adminPath = path.resolve(path.dirname(dotGit), match[1]!);
+  const relative = path.relative(adminRoot, adminPath);
+  if (!relative || relative.startsWith('..') || path.isAbsolute(relative) || relative.includes(path.sep)) {
+    throw new Error('WORKTREE_RECOVERY_METADATA_INVALID');
+  }
+
+  if (!fs.existsSync(adminPath)) return;
+  const adminStat = fs.lstatSync(adminPath);
+  if (adminStat.isSymbolicLink()) throw new Error('WORKTREE_RECOVERY_METADATA_INVALID');
+  if (!adminStat.isDirectory()) return;
+
+  const requiredFiles = ['HEAD', 'gitdir', 'commondir', 'index'];
+  if (requiredFiles.some((name) => !fs.existsSync(path.join(adminPath, name)))) return;
+  for (const name of requiredFiles) {
+    const filePath = path.join(adminPath, name);
+    const stat = fs.lstatSync(filePath);
+    if (stat.isSymbolicLink() || !stat.isFile()) throw new Error('WORKTREE_RECOVERY_METADATA_INVALID');
+  }
+
+  const adminGitdir = fs.readFileSync(path.join(adminPath, 'gitdir'), 'utf8').trim();
+  const adminCommonDir = fs.readFileSync(path.join(adminPath, 'commondir'), 'utf8').trim();
+  const adminGitdirPath = adminGitdir
+    ? fs.realpathSync.native(path.resolve(adminPath, adminGitdir))
+    : '';
+  const canonicalDotGit = fs.realpathSync.native(dotGit);
+  const adminCommonDirPath = adminCommonDir
+    ? fs.realpathSync.native(path.resolve(adminPath, adminCommonDir))
+    : '';
+  if (!adminGitdir || adminGitdirPath !== canonicalDotGit
+    || !adminCommonDir || adminCommonDirPath !== commonDir) {
+    throw new Error('WORKTREE_RECOVERY_METADATA_INVALID');
+  }
+
+  const headContent = fs.readFileSync(path.join(adminPath, 'HEAD'), 'utf8');
+  const indexContent = fs.readFileSync(path.join(adminPath, 'index'));
+  if (!hasValidHeadContent(headContent) || indexContent.subarray(0, 4).toString('ascii') !== 'DIRC') return;
+
+  const validationEnv: NodeJS.ProcessEnv = { ...process.env };
+  for (const key of ['GIT_DIR', 'GIT_COMMON_DIR', 'GIT_INDEX_FILE', 'GIT_WORK_TREE', 'GIT_PREFIX']) {
+    delete validationEnv[key];
+  }
+  validationEnv.GIT_DIR = adminPath;
+  validationEnv.GIT_WORK_TREE = path.resolve(worktree);
+  if (!probeMetadataCommand(probe, repoRoot, ['rev-parse', '--verify', 'HEAD^{commit}'], validationEnv)) return;
+  if (!probeMetadataCommand(probe, repoRoot, ['ls-files', '--stage', '-z'], validationEnv)) return;
+  throw new Error('WORKTREE_RECOVERY_METADATA_REGISTERED');
+}
+
+function parseRecoveredStatus(raw: string): WorktreeChange[] {
+  const records = raw.split('\0');
+  const changes: WorktreeChange[] = [];
+  for (let index = 0; index < records.length;) {
+    const status = records[index++] ?? '';
+    if (!status) continue;
+    const code = status[0] ?? '';
+    if (code === 'R' || code === 'C') {
+      const originalPath = records[index++];
+      const nextPath = records[index++];
+      if (!originalPath || !nextPath) throw new Error('Unable to parse recovered Git rename record');
+      changes.push({ indexStatus: code, worktreeStatus: ' ', path: nextPath, originalPath });
+      continue;
+    }
+    const filePath = records[index++];
+    if (!filePath) throw new Error('Unable to parse recovered Git status record');
+    changes.push({
+      indexStatus: code === 'D' ? ' ' : code,
+      worktreeStatus: code === 'D' ? 'D' : ' ',
+      path: filePath
+    });
+  }
+  return changes;
+}
+
+function captureRecoveredOnce(
+  worktree: string,
+  recovery: WorktreeRecoveryContext,
+  probe: Probe
+): WorktreeSnapshot {
+  const resolvedWorktree = path.resolve(worktree);
+  const resolvedBase = path.resolve(recovery.worktreeBase);
+  const relative = path.relative(resolvedBase, resolvedWorktree);
+  if (!relative || relative.startsWith('..') || path.isAbsolute(relative)) {
+    throw new Error(`WORKTREE_RECOVERY_PATH_INVALID: ${resolvedWorktree}`);
+  }
+  const stat = fs.lstatSync(resolvedWorktree);
+  if (!stat.isDirectory() || stat.isSymbolicLink()) throw new Error('WORKTREE_RECOVERY_PATH_INVALID');
+  const canonicalBase = fs.realpathSync.native(resolvedBase);
+  const canonicalWorktree = fs.realpathSync.native(resolvedWorktree);
+  const canonicalRelative = path.relative(canonicalBase, canonicalWorktree);
+  if (!canonicalRelative || canonicalRelative.startsWith('..') || path.isAbsolute(canonicalRelative)) {
+    throw new Error('WORKTREE_RECOVERY_PATH_INVALID');
+  }
+  const resolvedWorkspace = resolveSandboxTarget(recovery.branch, recovery.repoRoot).workspace;
+  if (recovery.identitySource === 'branch-only' && resolvedWorkspace.mode !== 'branch-only') {
+    throw new Error('WORKTREE_RECOVERY_IDENTITY_CHANGED');
+  }
+  if (recovery.identitySource === 'task-bound'
+    && (resolvedWorkspace.mode !== 'task-bound' || resolvedWorkspace.taskId !== recovery.taskId)) {
+    throw new Error('WORKTREE_RECOVERY_IDENTITY_CHANGED');
+  }
+  assertRecoverableMetadata(resolvedWorktree, recovery.repoRoot, probe);
+
+  const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-infra-recovered-index-'));
+  const env: NodeJS.ProcessEnv = { ...process.env };
+  for (const key of ['GIT_DIR', 'GIT_COMMON_DIR', 'GIT_PREFIX']) delete env[key];
+  env.GIT_INDEX_FILE = path.join(tempDir, 'index');
+  env.GIT_WORK_TREE = resolvedWorktree;
+  try {
+    const baseline = probeTextWithEnv(probe, recovery.repoRoot, [
+      'rev-parse', '--verify', `refs/heads/${recovery.branch}^{commit}`
+    ], env).trim();
+    if (!baseline) throw new Error(`WORKTREE_RECOVERY_BRANCH_INVALID: ${recovery.branch}`);
+    probeTextWithEnv(probe, recovery.repoRoot, ['read-tree', baseline], env);
+    probeTextWithEnv(probe, recovery.repoRoot, ['add', '-A', '--', '.'], env);
+    const status = probeTextWithEnv(probe, recovery.repoRoot, [
+      'diff', '--cached', '--name-status', '--find-renames', '-z', '--', '.'
+    ], env);
+    const changes = parseRecoveredStatus(status);
+    const hash = createHash('sha256');
+    updatePart(hash, 'source', 'recovered');
+    updatePart(hash, 'worktree', resolvedWorktree);
+    updatePart(hash, 'repo-root', path.resolve(recovery.repoRoot));
+    updatePart(hash, 'branch', recovery.branch);
+    updatePart(hash, 'baseline', baseline);
+    updatePart(hash, 'identity-source', recovery.identitySource);
+    updatePart(hash, 'task-id', recovery.taskId ?? '');
+    updatePart(hash, 'status', status);
+    for (const change of changes) {
+      hashPath(hash, resolvedWorktree, change.path, probe);
+      if (change.originalPath) hashPath(hash, resolvedWorktree, change.originalPath, probe);
+    }
+    return {
+      worktree: resolvedWorktree,
+      branch: recovery.branch,
+      head: baseline,
+      changes,
+      identity: hash.digest('hex'),
+      source: 'recovered',
+      recovery: { ...recovery }
+    };
+  } finally {
+    fs.rmSync(tempDir, { recursive: true, force: true });
+  }
+}
+
 function inspectWorktree(worktree: string, { probe = runProbe }: { probe?: Probe } = {}): WorktreeInspection {
   const resolvedWorktree = path.resolve(worktree);
   try {
@@ -182,6 +391,28 @@ function inspectWorktree(worktree: string, { probe = runProbe }: { probe?: Probe
   }
 }
 
+function inspectRecoveredWorktree(
+  worktree: string,
+  recovery: WorktreeRecoveryContext,
+  { probe = runProbe }: { probe?: Probe } = {}
+): WorktreeInspection {
+  const resolvedWorktree = path.resolve(worktree);
+  try {
+    const first = captureRecoveredOnce(resolvedWorktree, recovery, probe);
+    const second = captureRecoveredOnce(resolvedWorktree, recovery, probe);
+    if (first.identity !== second.identity) {
+      return { status: 'failed', worktree: resolvedWorktree, message: 'Snapshot changed while recovering worktree' };
+    }
+    return { status: second.changes.length === 0 ? 'clean' : 'dirty', snapshot: second };
+  } catch (error) {
+    return {
+      status: 'failed',
+      worktree: resolvedWorktree,
+      message: error instanceof Error ? error.message : String(error)
+    };
+  }
+}
+
 function inspectWorktrees(worktrees: readonly string[]): WorktreeInspection[] {
   return [...new Set(worktrees.map((worktree) => path.resolve(worktree)))].sort()
     .map((worktree) => inspectWorktree(worktree));
@@ -201,7 +432,9 @@ function verifyWorktreePermit(
   permit: WorktreeRemovalPermit,
   options: { probe?: Probe } = {}
 ): WorktreeSnapshot {
-  const current = inspectWorktree(permit.snapshot.worktree, options);
+  const current = permit.snapshot.source === 'recovered' && permit.snapshot.recovery
+    ? inspectRecoveredWorktree(permit.snapshot.worktree, permit.snapshot.recovery, options)
+    : inspectWorktree(permit.snapshot.worktree, options);
   if (current.status === 'failed') throw new Error(`Unable to verify worktree permit: ${current.message}`);
   if (current.snapshot.identity !== permit.snapshot.identity || (permit.mode === 'clean' && current.status !== 'clean')) {
     throw new Error(`Worktree changed after authorization: ${permit.snapshot.worktree}`);
@@ -227,8 +460,9 @@ export {
   createCleanPermit,
   createDiscardPermit,
   formatWorktreeSnapshot,
+  inspectRecoveredWorktree,
   inspectWorktree,
   inspectWorktrees,
   verifyWorktreePermit
 };
-export type { WorktreeChange, WorktreeInspection, WorktreeRemovalPermit, WorktreeSnapshot };
+export type { WorktreeChange, WorktreeInspection, WorktreeRecoveryContext, WorktreeRemovalPermit, WorktreeSnapshot };