@fitlab-ai/agent-infra 0.9.10 → 0.9.12

package/lib/sandbox/recovery.ts

@@ -28,11 +28,12 @@ import {
   sandboxControlPaths,
   sandboxWorkspaceViewPaths
 } from './workspace-view.ts';
+import { resolveTaskWorkspace } from './task-resolver.ts';
 import {
   parseSandboxWorkspaceIdentity,
   sameSandboxWorkspaceIdentity,
   type SandboxContainerWorkspaceIdentity,
-  type SandboxWorkspaceIdentity
+  type SandboxWorkspaceReference
 } from './workspace-identity.ts';
 import { inspectWorktree, type WorktreeSnapshot } from './worktree-safety.ts';
 import { commandForEngine, runEngine, runOkEngine, runProbe, runVerboseEngine } from './shell.ts';
@@ -91,7 +92,7 @@ export type SandboxRecoverySnapshot = {
   containerIdValid: boolean;
   expectedBranch: string;
   actualBranch: string | null;
-  expectedWorkspace: SandboxWorkspaceIdentity;
+  expectedWorkspace: SandboxWorkspaceReference;
   actualWorkspace: SandboxContainerWorkspaceIdentity;
   workspaceTopology?: 'legacy-parent' | 'per-state' | 'unknown';
   taskView?: { path: string; readable: boolean };
@@ -174,7 +175,8 @@ type EnsureSandboxReadyParams = {
   config: SandboxConfig;
   engine: string;
   branch: string;
-  workspace?: SandboxWorkspaceIdentity;
+  workspace?: SandboxWorkspaceReference;
+  reentry?: 'standard' | 'completed';
   row: SandboxRow;
   allowRecreate?: boolean;
   forceRecreate?: boolean;
@@ -187,6 +189,7 @@ type ExpectedMount = {
   path: string;
   expectedType: 'bind' | 'tmpfs';
   hostPaths: string[];
+  sourceAccessiblePaths?: string[];
   expectedRW: boolean;
 };
 
@@ -324,7 +327,7 @@ export async function startSandboxControlBroker(repoRoot: string, manifestPath:
 async function ensureSandboxControlBroker(params: {
   config: SandboxConfig;
   container: string;
-  workspace: SandboxWorkspaceIdentity;
+  workspace: SandboxWorkspaceReference;
 }): Promise<void> {
   const control = sandboxControlPaths({
     base: params.config.controlBase ?? path.join(params.config.home, '.agent-infra', 'sandbox-control'),
@@ -603,6 +606,93 @@ function sourceCandidates(engine: string, hostPath: string): string[] {
   return [...new Set(candidates.map((candidate) => normalizeMountSource(engine, candidate)))];
 }
 
+function recoveryTaskSources(repoRoot: string, taskId: string): {
+  mountPaths: string[];
+  accessiblePaths: string[];
+} {
+  const activePath = path.join(repoRoot, '.agents', 'workspace', 'active', taskId);
+  const completedPath = path.join(repoRoot, '.agents', 'workspace', 'completed', taskId);
+  if (fs.existsSync(activePath) && !fs.existsSync(completedPath)) {
+    const source = assertSandboxTaskSource(repoRoot, taskId);
+    return { mountPaths: [source], accessiblePaths: [source] };
+  }
+
+  const task = resolveTaskWorkspace(taskId, repoRoot);
+  if (task.state === 'active') {
+    const source = assertSandboxTaskSource(repoRoot, taskId);
+    return { mountPaths: [source], accessiblePaths: [source] };
+  }
+  if (task.state !== 'completed') {
+    throw new Error(`SANDBOX_TASK_SOURCE_STATE_UNSUPPORTED: task ${taskId} is ${task.state}`);
+  }
+
+  const completedRoot = fs.realpathSync.native(
+    path.join(repoRoot, '.agents', 'workspace', 'completed')
+  );
+  const completedSource = fs.realpathSync.native(path.dirname(task.taskMd));
+  if (path.dirname(completedSource) !== completedRoot) {
+    throw new Error(`SANDBOX_TASK_SOURCE_INVALID: ${completedSource} is not under completed workspace`);
+  }
+
+  const historicalActivePath = path.join(
+    repoRoot,
+    '.agents',
+    'workspace',
+    'active',
+    taskId
+  );
+  const mountPaths = [completedSource, historicalActivePath];
+  if (fs.existsSync(historicalActivePath)) {
+    try {
+      mountPaths[1] = fs.realpathSync.native(historicalActivePath);
+    } catch {
+      // Keep the exact historical path as a candidate; the current completed
+      // source remains the only source that must still be accessible.
+    }
+  }
+  return { mountPaths, accessiblePaths: [completedSource] };
+}
+
+function startCompletedSandboxContainer(params: {
+  config: SandboxConfig;
+  engine: string;
+  container: string;
+  taskId: string;
+  start: typeof startSandboxContainer;
+}): void {
+  const taskSources = recoveryTaskSources(params.config.repoRoot, params.taskId);
+  const completedSource = taskSources.accessiblePaths[0]!;
+  const activeRoot = path.join(params.config.repoRoot, '.agents', 'workspace', 'active');
+  const historicalSource = path.join(activeRoot, params.taskId);
+  fs.mkdirSync(activeRoot, { recursive: true });
+  try {
+    fs.lstatSync(historicalSource);
+    throw new Error(
+      `SANDBOX_COMPLETED_SOURCE_CONFLICT: historical task source already exists at ${historicalSource}`
+    );
+  } catch (error) {
+    if (!(error instanceof Error && 'code' in error && error.code === 'ENOENT')) throw error;
+  }
+
+  fs.symlinkSync(
+    completedSource,
+    historicalSource,
+    process.platform === 'win32' ? 'junction' : 'dir'
+  );
+  try {
+    params.start(params.engine, params.container);
+  } finally {
+    const temporarySource = fs.lstatSync(historicalSource);
+    const resolvedSource = fs.realpathSync.native(historicalSource);
+    if (!temporarySource.isSymbolicLink() || resolvedSource !== completedSource) {
+      throw new Error(
+        `SANDBOX_COMPLETED_SOURCE_CHANGED: refusing to remove unexpected path at ${historicalSource}`
+      );
+    }
+    fs.unlinkSync(historicalSource);
+  }
+}
+
 function sameHostSource(left: string, right: string): boolean {
   try {
     const leftStat = fs.statSync(left, { bigint: true });
@@ -629,7 +719,7 @@ function expectedMounts(params: {
   config: SandboxConfig;
   branch: string;
   container: string;
-  workspace: SandboxWorkspaceIdentity;
+  workspace: SandboxWorkspaceReference;
   tools: readonly SandboxTool[];
   actualMounts: Map<string, DockerMount>;
 }): ExpectedMount[] {
@@ -646,21 +736,29 @@ function expectedMounts(params: {
     container: params.container,
     identity: params.workspace
   });
+  const taskSources = params.workspace.mode === 'task-bound'
+    ? recoveryTaskSources(config.repoRoot, params.workspace.taskId)
+    : null;
+  const taskId = params.workspace.mode === 'task-bound' ? params.workspace.taskId : null;
   const core = sandboxCoreBindMounts(config, branch, {
     workspaceViewRoot: view.root,
     controlDir: control.channelDir,
     controlStatusDir: control.statusDir,
-    ...(params.workspace.mode === 'task-bound'
-      ? {
+    ...(taskSources === null
+      ? {}
+      : {
         runtimeDir: control.runtimeDir,
-        taskSource: assertSandboxTaskSource(config.repoRoot, params.workspace.taskId),
-        taskId: params.workspace.taskId
-      }
-      : {})
+        taskSources: taskSources.mountPaths,
+        taskId: taskId!
+      })
   }).map((mount) => ({
     path: mount.containerPath,
     expectedType: 'bind' as const,
     hostPaths: mount.hostPaths,
+    ...(taskSources !== null && taskId !== null
+      && mount.containerPath === `/workspace/.agents/workspace/active/${taskId}`
+      ? { sourceAccessiblePaths: taskSources.accessiblePaths }
+      : {}),
     expectedRW: !mount.readOnly
   }));
   const live = tools.flatMap((tool) =>
@@ -676,13 +774,7 @@ function expectedMounts(params: {
     })
   );
   const persistentTools = tools
-    .filter((tool) =>
-      !tool.tmpfs
-      && (
-        config.agentClientSource === 'canonical'
-        || actualMounts.has(tool.containerMount)
-      )
-    )
+    .filter((tool) => !tool.tmpfs)
     .map((tool) => ({
       path: tool.containerMount,
       expectedType: 'bind' as const,
@@ -755,7 +847,7 @@ export function collectSandboxRecoverySnapshot(params: {
   config: SandboxConfig;
   engine: string;
   branch: string;
-  workspace?: SandboxWorkspaceIdentity;
+  workspace?: SandboxWorkspaceReference;
   container: string;
   deps?: RecoveryCommandDeps;
 }): SandboxRecoverySnapshot {
@@ -836,13 +928,10 @@ export function collectSandboxRecoverySnapshot(params: {
     taskId: sandboxTaskIdLabel(params.config)
   });
   const selectedToolIds = new Set(tools.map((tool) => tool.id));
-  const enforceCanonicalPlan = params.config.agentClientSource === 'canonical';
-  const unexpectedCapabilityMounts = enforceCanonicalPlan
-    ? capabilityPlan.cleanupInventory
-      .filter((tool) => isAgentClientId(tool.id) && !selectedToolIds.has(tool.id))
-      .map((tool) => tool.containerMount)
-      .filter((mountPath) => mountsByDestination.has(mountPath))
-    : [];
+  const unexpectedCapabilityMounts = capabilityPlan.cleanupInventory
+    .filter((tool) => isAgentClientId(tool.id) && !selectedToolIds.has(tool.id))
+    .map((tool) => tool.containerMount)
+    .filter((mountPath) => mountsByDestination.has(mountPath));
   const mountSnapshots = expectedMounts({
     config: params.config,
     branch: params.branch,
@@ -880,7 +969,9 @@ export function collectSandboxRecoverySnapshot(params: {
       sourceAccessible: expected.expectedType === 'tmpfs'
         ? true
         : matchedHostPath !== undefined
-          && hostSourceAccessible(matchedHostPath, expected.expectedRW)
+          && (expected.sourceAccessiblePaths ?? [matchedHostPath]).some((hostPath) =>
+            hostSourceAccessible(hostPath, expected.expectedRW)
+          )
     };
   });
 
@@ -907,9 +998,7 @@ export function collectSandboxRecoverySnapshot(params: {
     identityOk: typeof inspection.Id === 'string' && inspection.Id.length > 0
       && branchLabel === params.branch
       && sameSandboxWorkspaceIdentity(containerWorkspace, workspace),
-    runtimeCapabilityOk: enforceCanonicalPlan
-      ? labels[sandboxRuntimeCapabilityLabel(params.config)] === capabilityPlan.runtimeSignature
-      : undefined,
+    runtimeCapabilityOk: labels[sandboxRuntimeCapabilityLabel(params.config)] === capabilityPlan.runtimeSignature,
     unexpectedCapabilityMounts,
     mounts: mountSnapshots,
     tmpfs,
@@ -1069,7 +1158,7 @@ function assess(params: {
   config: SandboxConfig;
   engine: string;
   branch: string;
-  workspace?: SandboxWorkspaceIdentity;
+  workspace?: SandboxWorkspaceReference;
   container: string;
   deps?: RecoveryCommandDeps;
 }): { snapshot: SandboxRecoverySnapshot; findings: SandboxRecoveryFinding[] } {
@@ -1095,7 +1184,7 @@ export async function assertFreshSandboxReady(params: {
   config: SandboxConfig;
   engine: string;
   branch: string;
-  workspace?: SandboxWorkspaceIdentity;
+  workspace?: SandboxWorkspaceReference;
   container: string;
   copiedEntries: TmpfsSeedEntry[];
   deps?: RecoveryCommandDeps;
@@ -1157,11 +1246,21 @@ export async function ensureSandboxReady(params: EnsureSandboxReadyParams): Prom
         workspace: params.workspace ?? { mode: 'branch-only' }
       });
     }
-    if (params.forceRecreate) {
+    if (params.forceRecreate || (params.reentry === 'completed' && params.allowRecreate)) {
       throw new Error('Explicit container recreation requested.');
     }
     if (!params.row.running) {
-      startFn(params.engine, params.row.name);
+      if (params.reentry === 'completed' && params.workspace?.mode === 'task-bound') {
+        startCompletedSandboxContainer({
+          config: params.config,
+          engine: params.engine,
+          container: params.row.name,
+          taskId: params.workspace.taskId,
+          start: startFn
+        });
+      } else {
+        startFn(params.engine, params.row.name);
+      }
       const initial = assess({
         config: params.config,
         engine: params.engine,
@@ -1281,6 +1380,35 @@ export async function ensureSandboxReady(params: EnsureSandboxReadyParams): Prom
     failure = error instanceof Error ? error : new Error(String(error));
   }
 
+  if (params.reentry === 'completed') {
+    if (params.workspace?.mode !== 'task-bound') {
+      throw new Error('SANDBOX_COMPLETED_REENTRY_INVALID: completed re-entry requires a task-bound workspace');
+    }
+    const taskId = params.workspace.taskId;
+    const commandChain = [
+      `docker exec -it ${params.row.name} bash /usr/local/bin/sandbox-tmux-entry`,
+      `ai sandbox rm ${taskId}`,
+      `ai sandbox create ${params.branch}`
+    ];
+    const code = params.allowRecreate || params.forceRecreate
+      ? 'SANDBOX_COMPLETED_RECREATE_UNSUPPORTED'
+      : 'SANDBOX_COMPLETED_REENTRY_FAILED';
+    const lead = code === 'SANDBOX_COMPLETED_RECREATE_UNSUPPORTED'
+      ? 'Completed sandbox replacement is unsupported; the existing container was not replaced.'
+      : 'Completed sandbox recovery failed; the existing container was not replaced.';
+    throw new Error([
+      `${code}: ${lead}`,
+      `Task: ${taskId}; container: ${params.row.name}; branch: ${params.branch}.`,
+      'To preserve the current container state, enter it manually with:',
+      `  ${commandChain[0]}`,
+      'If you intentionally want a replacement, the following is the full interactive sandbox cleanup, not a container-only delete.',
+      'It may remove the worktree, local branch, tool/shell state, and branch share:',
+      `  ${commandChain[1]}`,
+      `  ${commandChain[2]}`,
+      `Details: ${failure.message}`
+    ].join('\n'));
+  }
+
   const dataBoundary =
     'The existing container writable layer, ordinary /tmp data, processes, tmux sessions, and RAM state may be lost by replacement; worktree and host-managed sandbox data are preserved.';
   const recoveryTarget = params.workspace?.mode === 'task-bound'

package/lib/sandbox/tools.ts

@@ -41,7 +41,7 @@ type ToolsConfig = {
   project: string;
   tools: string[];
   customTools?: SandboxTool[];
-  agentClientState?: import('../agent-clients/types.ts').AgentClientState;
+  agentClientState: import('../agent-clients/types.ts').AgentClientState;
 };
 
 const TOOL_ID_PATTERN = /^[a-z0-9][a-z0-9-]*$/;

package/lib/sandbox/workspace-identity.ts

@@ -17,6 +17,8 @@ export type SandboxWorkspaceKey =
   | Readonly<{ mode: 'task-bound'; taskId: string }>
   | Readonly<{ mode: 'branch-only' }>;
 
+export type SandboxWorkspaceReference = SandboxWorkspaceIdentity | SandboxWorkspaceKey;
+
 export type SandboxCleanupTarget = Readonly<{
   requestedRef: string;
   branch: string;
@@ -35,6 +37,11 @@ export type SandboxTarget = Readonly<{
   workspace: SandboxWorkspaceIdentity;
 }>;
 
+export type SandboxReentryContext = Readonly<{
+  workspace: SandboxWorkspaceReference;
+  reentry: 'standard' | 'completed';
+}>;
+
 function stripQuotes(value: string): string {
   return value.replace(/^(?:"([^"]*)"|'([^']*)')$/, '$1$2');
 }
@@ -116,6 +123,27 @@ export function resolveSandboxTarget(requestedRef: string, repoRoot: string): Sa
   return { requestedRef, branch: requestedRef, workspace: { mode: 'branch-only' } };
 }
 
+export function resolveSandboxReentryContext(params: Readonly<{
+  target: SandboxTarget;
+  containerWorkspace: SandboxContainerWorkspaceIdentity;
+  repoRoot: string;
+}>): SandboxReentryContext {
+  if (params.target.workspace.mode !== 'branch-only'
+    || params.containerWorkspace.mode !== 'task-bound') {
+    return { workspace: params.target.workspace, reentry: 'standard' };
+  }
+
+  const task = resolveTaskWorkspace(params.containerWorkspace.taskId, params.repoRoot);
+  if (task.state !== 'completed' || task.branch !== params.target.branch) {
+    return { workspace: params.target.workspace, reentry: 'standard' };
+  }
+
+  return {
+    workspace: { mode: 'task-bound', taskId: task.taskId },
+    reentry: 'completed'
+  };
+}
+
 export function resolveSandboxCleanupTarget(
   requestedRef: string,
   repoRoot: string,

package/lib/sandbox/workspace-view.ts

@@ -52,10 +52,15 @@ export type SandboxControlSetup = Readonly<{
   statusDir: string;
   runtimeDir: string;
   manifestPath: string;
+  manifestDraft: SandboxControlManifestDraft;
   token: string;
   generation: string;
 }>;
 
+export type SandboxControlManifestDraft = Readonly<Omit<SandboxControlManifest, 'containerIdentity' | 'engine'> & {
+  engine: string;
+}>;
+
 export function sandboxControlPaths(params: Readonly<{
   base: string;
   project: string;
@@ -230,14 +235,12 @@ export function materializeSandboxControl(params: Readonly<{
   const token = randomBytes(32).toString('hex');
   const generation = randomBytes(16).toString('hex');
   const repoRoot = fs.realpathSync.native(params.repoRoot);
-  const manifest: SandboxControlManifest = {
-    version: 5,
+  const manifestDraft: SandboxControlManifestDraft = {
     engine: params.engine ?? 'docker',
     repoRoot,
     worktreeRoot: fs.realpathSync.native(params.worktreeRoot),
     project: params.project,
     container: params.container,
-    containerIdentity: { id: '', labels: {} },
     branch: params.branch,
     mode: params.identity.mode,
     taskId: params.identity.mode === 'task-bound' ? params.identity.taskId : null,
@@ -248,19 +251,19 @@ export function materializeSandboxControl(params: Readonly<{
     processingDir,
     runtimeDir
   };
-  fs.writeFileSync(manifestPath, `${JSON.stringify(manifest)}\n`, { mode: 0o600 });
-  return { root, channelDir, statusDir, runtimeDir, manifestPath, token, generation };
+  return { root, channelDir, statusDir, runtimeDir, manifestPath, manifestDraft, token, generation };
 }
 
 export function finalizeSandboxControlManifest(
   setup: SandboxControlSetup,
   identity: Readonly<{ engine: string; id: string; labels: Readonly<Record<string, string>> }>
-): void {
+): SandboxControlManifest {
   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 = 5;
-  manifest.engine = identity.engine;
-  manifest.containerIdentity = { id: identity.id, labels: { ...identity.labels } };
+  const manifest: SandboxControlManifest = {
+    ...setup.manifestDraft,
+    engine: identity.engine,
+    containerIdentity: { id: identity.id, labels: { ...identity.labels } }
+  };
   const temporary = `${setup.manifestPath}.${process.pid}.${randomBytes(8).toString('hex')}.tmp`;
   try {
     fs.writeFileSync(temporary, `${JSON.stringify(manifest)}\n`, { mode: 0o600, flag: 'wx' });
@@ -268,4 +271,5 @@ export function finalizeSandboxControlManifest(
   } finally {
     fs.rmSync(temporary, { force: true });
   }
+  return manifest;
 }