@fitlab-ai/agent-infra 0.9.3 → 0.9.4

package/lib/process-data/store.ts

@@ -0,0 +1,315 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+
+import type {
+  JsonValue,
+  NormalizedRecord,
+  QualityFinding,
+  RepairAction,
+  RestCollectionEvidence,
+  SnapshotManifest,
+  StoredObjectEvidence
+} from './types.ts';
+
+type ObjectWrite = { sha256: string; path: string; created: boolean };
+type ObjectStore = { put(bytes: Buffer): ObjectWrite; pathFor(sha256: string): string };
+
+type PublishInput = {
+  scope: 'all' | 'local' | 'github';
+  repository: string;
+  observedFrom: string;
+  observedTo: string;
+  objects: StoredObjectEvidence[];
+  endpoints: RestCollectionEvidence[];
+  excerptsEnabled: boolean;
+  records: NormalizedRecord[];
+  quality: QualityFinding[];
+  repairs: RepairAction[];
+};
+
+type VerificationResult = {
+  ok: boolean;
+  snapshotId: string;
+  snapshotPath: string | null;
+  errors: string[];
+  manifest?: SnapshotManifest;
+};
+
+function sha256(bytes: Buffer | string): string {
+  return crypto.createHash('sha256').update(bytes).digest('hex');
+}
+
+function compareCodePoints(left: string, right: string): number {
+  const a = Array.from(left, (char) => char.codePointAt(0)!);
+  const b = Array.from(right, (char) => char.codePointAt(0)!);
+  for (let index = 0; index < Math.min(a.length, b.length); index += 1) {
+    if (a[index] !== b[index]) return a[index]! - b[index]!;
+  }
+  return a.length - b.length;
+}
+
+function canonicalString(value: unknown, seen: Set<object>): string {
+  if (value === null || typeof value === 'boolean' || typeof value === 'string') {
+    return JSON.stringify(value);
+  }
+  if (typeof value === 'number') {
+    if (!Number.isFinite(value)) throw new Error('canonical JSON accepts only finite JSON values');
+    return JSON.stringify(value);
+  }
+  if (Array.isArray(value)) {
+    if (seen.has(value)) throw new Error('canonical JSON accepts only acyclic JSON values');
+    seen.add(value);
+    const output = `[${value.map((entry) => canonicalString(entry, seen)).join(',')}]`;
+    seen.delete(value);
+    return output;
+  }
+  if (typeof value === 'object') {
+    if (seen.has(value)) throw new Error('canonical JSON accepts only acyclic JSON values');
+    seen.add(value);
+    const record = value as Record<string, unknown>;
+    const fields = Object.keys(record)
+      .sort(compareCodePoints)
+      .map((key) => `${JSON.stringify(key)}:${canonicalString(record[key], seen)}`);
+    seen.delete(value);
+    return `{${fields.join(',')}}`;
+  }
+  throw new Error('canonical JSON accepts only JSON values');
+}
+
+function canonicalJsonBytes(value: JsonValue | unknown): Buffer {
+  return Buffer.from(canonicalString(value, new Set()), 'utf8');
+}
+
+function ensurePrivateDirectory(directory: string): void {
+  fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
+  if (process.platform !== 'win32') fs.chmodSync(directory, 0o700);
+}
+
+function writeExclusive(filePath: string, bytes: Buffer): boolean {
+  ensurePrivateDirectory(path.dirname(filePath));
+  try {
+    const fd = fs.openSync(filePath, 'wx', 0o600);
+    try {
+      fs.writeFileSync(fd, bytes);
+      fs.fsyncSync(fd);
+    } finally {
+      fs.closeSync(fd);
+    }
+    return true;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw error;
+    return false;
+  }
+}
+
+function createObjectStore(root: string): ObjectStore {
+  const objectRoot = path.join(root, 'objects', 'sha256');
+  ensurePrivateDirectory(objectRoot);
+  return {
+    pathFor(digest: string) {
+      if (!/^[a-f0-9]{64}$/.test(digest)) throw new Error(`invalid SHA-256: ${digest}`);
+      return path.join(objectRoot, digest.slice(0, 2), digest);
+    },
+    put(bytes: Buffer) {
+      const digest = sha256(bytes);
+      const objectPath = path.join(objectRoot, digest.slice(0, 2), digest);
+      const created = writeExclusive(objectPath, bytes);
+      const stored = fs.readFileSync(objectPath);
+      if (sha256(stored) !== digest) throw new Error(`CAS hash mismatch for ${digest}`);
+      return { sha256: digest, path: objectPath, created };
+    }
+  };
+}
+
+function dispositionCounts(objects: StoredObjectEvidence[]): SnapshotManifest['dispositionCounts'] {
+  const counts: SnapshotManifest['dispositionCounts'] = { included: 0, 'excluded-sensitive': 0, unavailable: 0 };
+  for (const object of objects) counts[object.disposition?.state ?? 'included'] += 1;
+  return counts;
+}
+
+function jsonLine(value: JsonValue | unknown): string {
+  return `${canonicalJsonBytes(value).toString('utf8')}\n`;
+}
+
+function writePrivateFile(filePath: string, content: string | Buffer): void {
+  fs.writeFileSync(filePath, content, { mode: 0o600, flag: 'wx' });
+  if (process.platform !== 'win32') fs.chmodSync(filePath, 0o600);
+}
+
+function manifestDigest(manifest: Omit<SnapshotManifest, 'manifestSha256'>): string {
+  return sha256(canonicalJsonBytes(manifest));
+}
+
+function publishSnapshot(root: string, input: PublishInput): { snapshotId: string; path: string; created: boolean } {
+  ensurePrivateDirectory(root);
+  ensurePrivateDirectory(path.join(root, 'repairs'));
+  const date = new Date(input.observedTo);
+  if (!Number.isFinite(date.getTime())) throw new Error('observedTo must be an ISO timestamp');
+
+  const identity = {
+    scope: input.scope,
+    repository: input.repository,
+    observedFrom: input.observedFrom,
+    observedTo: input.observedTo,
+    objects: input.objects,
+    endpoints: input.endpoints,
+    excerptsEnabled: input.excerptsEnabled,
+    dispositionCounts: dispositionCounts(input.objects),
+    recordCount: input.records.length,
+    findingCount: input.quality.length,
+    repairCount: input.repairs.length
+  };
+  const identityDigest = sha256(canonicalJsonBytes(identity));
+  const stamp = input.observedTo.replace(/[-:]/g, '').replace(/\.\d{3}Z$/, 'Z');
+  const snapshotId = `${stamp}-${identityDigest.slice(0, 12)}`;
+  const partialManifest: Omit<SnapshotManifest, 'manifestSha256'> = {
+    schema: 'raw-manifest/v1',
+    snapshotId,
+    ...identity,
+    privacyPolicyVersion: 'process-data-privacy/v1'
+  };
+  const manifest: SnapshotManifest = { ...partialManifest, manifestSha256: manifestDigest(partialManifest) };
+
+  const stagingRoot = path.join(root, '.staging');
+  ensurePrivateDirectory(stagingRoot);
+  const staging = fs.mkdtempSync(path.join(stagingRoot, `${snapshotId}-`));
+  if (process.platform !== 'win32') fs.chmodSync(staging, 0o700);
+  try {
+    writePrivateFile(path.join(staging, 'manifest.json'), jsonLine(manifest));
+    writePrivateFile(
+      path.join(staging, 'normalized.jsonl'),
+      input.records.map((record) => jsonLine({ schema: 'normalized/v1', ...record })).join('')
+    );
+    writePrivateFile(path.join(staging, 'quality.json'), jsonLine({ schema: 'quality/v1', findings: input.quality }));
+    writePrivateFile(
+      path.join(staging, 'repair-manifest.jsonl'),
+      input.repairs.map((repair) => jsonLine({ schema: 'repair/v1', ...repair })).join('')
+    );
+
+    const destination = path.join(
+      root,
+      'snapshots',
+      String(date.getUTCFullYear()),
+      String(date.getUTCMonth() + 1).padStart(2, '0'),
+      String(date.getUTCDate()).padStart(2, '0'),
+      snapshotId
+    );
+    ensurePrivateDirectory(path.dirname(destination));
+    if (fs.existsSync(destination)) {
+      const existing = fs.readFileSync(path.join(destination, 'manifest.json'), 'utf8');
+      if (existing !== jsonLine(manifest)) throw new Error(`snapshot collision: ${snapshotId}`);
+      fs.rmSync(staging, { recursive: true, force: true });
+      return { snapshotId, path: destination, created: false };
+    }
+    fs.renameSync(staging, destination);
+    return { snapshotId, path: destination, created: true };
+  } catch (error) {
+    fs.rmSync(staging, { recursive: true, force: true });
+    throw error;
+  }
+}
+
+function findSnapshot(root: string, snapshotId: string): string | null {
+  const snapshotRoot = path.join(root, 'snapshots');
+  if (!fs.existsSync(snapshotRoot)) return null;
+  const stack = [snapshotRoot];
+  while (stack.length > 0) {
+    const current = stack.pop()!;
+    for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
+      if (!entry.isDirectory()) continue;
+      const candidate = path.join(current, entry.name);
+      if (entry.name === snapshotId && fs.existsSync(path.join(candidate, 'manifest.json'))) return candidate;
+      stack.push(candidate);
+    }
+  }
+  return null;
+}
+
+function verifySnapshot(root: string, snapshotId: string): VerificationResult {
+  const snapshotPath = findSnapshot(root, snapshotId);
+  if (!snapshotPath) return { ok: false, snapshotId, snapshotPath: null, errors: ['snapshot not found'] };
+  const errors: string[] = [];
+  const checkMode = (target: string, expected: number, label: string) => {
+    if (process.platform === 'win32' || !fs.existsSync(target)) return;
+    const actual = fs.statSync(target).mode & 0o777;
+    if (actual !== expected) errors.push(`${label} permission mismatch: expected ${expected.toString(8)}, got ${actual.toString(8)}`);
+  };
+  checkMode(snapshotPath, 0o700, 'snapshot directory');
+  for (const file of ['manifest.json', 'normalized.jsonl', 'quality.json', 'repair-manifest.jsonl']) {
+    checkMode(path.join(snapshotPath, file), 0o600, file);
+  }
+  let manifest: SnapshotManifest;
+  try {
+    manifest = JSON.parse(fs.readFileSync(path.join(snapshotPath, 'manifest.json'), 'utf8')) as SnapshotManifest;
+  } catch {
+    return { ok: false, snapshotId, snapshotPath, errors: ['manifest is invalid JSON'] };
+  }
+  if (manifest.schema !== 'raw-manifest/v1') errors.push(`unsupported manifest schema: ${manifest.schema}`);
+  if (manifest.snapshotId !== snapshotId) errors.push('snapshot identity mismatch');
+  if (typeof manifest.excerptsEnabled !== 'boolean') errors.push('manifest excerpts opt-in is invalid');
+  if (!manifest.dispositionCounts || canonicalJsonBytes(manifest.dispositionCounts).toString('utf8') !== canonicalJsonBytes(dispositionCounts(manifest.objects)).toString('utf8')) {
+    errors.push('manifest disposition counts mismatch');
+  }
+  const { manifestSha256, ...partial } = manifest;
+  if (manifestDigest(partial) !== manifestSha256) errors.push('manifest hash mismatch');
+  const store = createObjectStore(root);
+  try {
+    const lines = fs.readFileSync(path.join(snapshotPath, 'normalized.jsonl'), 'utf8').split('\n').filter(Boolean);
+    const ids = new Set<string>();
+    for (const line of lines) {
+      const record = JSON.parse(line) as { schema?: string; recordId?: string };
+      if (record.schema !== 'normalized/v1' || typeof record.recordId !== 'string') {
+        errors.push('normalized record schema is invalid');
+        continue;
+      }
+      if (ids.has(record.recordId)) errors.push(`duplicate normalized record: ${record.recordId}`);
+      ids.add(record.recordId);
+    }
+    if (lines.length !== manifest.recordCount) errors.push('normalized record count mismatch');
+    const quality = JSON.parse(fs.readFileSync(path.join(snapshotPath, 'quality.json'), 'utf8')) as { schema?: string; findings?: unknown[] };
+    if (quality.schema !== 'quality/v1' || !Array.isArray(quality.findings)) errors.push('quality schema is invalid');
+    else if (quality.findings.length !== manifest.findingCount) errors.push('quality finding count mismatch');
+    const repairLines = fs.readFileSync(path.join(snapshotPath, 'repair-manifest.jsonl'), 'utf8').split('\n').filter(Boolean);
+    for (const line of repairLines) {
+      const repair = JSON.parse(line) as { schema?: string; repairId?: string };
+      if (repair.schema !== 'repair/v1' || typeof repair.repairId !== 'string') errors.push('repair manifest schema is invalid');
+    }
+    if (repairLines.length !== manifest.repairCount) errors.push('repair manifest count mismatch');
+  } catch {
+    errors.push('snapshot derived files are missing or invalid');
+  }
+  for (const object of manifest.objects) {
+    if (object.disposition?.state && object.disposition.state !== 'included') continue;
+    try {
+      const objectPath = store.pathFor(object.sha256);
+      checkMode(path.dirname(objectPath), 0o700, `object directory ${object.sha256.slice(0, 2)}`);
+      checkMode(objectPath, 0o600, `object ${object.sourceIdentity}`);
+      const bytes = fs.readFileSync(objectPath);
+      if (sha256(bytes) !== object.sha256) errors.push(`object hash mismatch: ${object.sourceIdentity}`);
+      if (bytes.length !== object.bytes) errors.push(`object byte count mismatch: ${object.sourceIdentity}`);
+    } catch {
+      errors.push(`object missing: ${object.sourceIdentity}`);
+    }
+  }
+  for (const page of manifest.endpoints.flatMap((endpoint) => endpoint.pages)) {
+    try {
+      if (sha256(fs.readFileSync(store.pathFor(page.canonicalSha256))) !== page.canonicalSha256) {
+        errors.push(`page hash mismatch: ${page.index}`);
+      }
+    } catch {
+      errors.push(`page object missing: ${page.canonicalSha256}`);
+    }
+  }
+  return { ok: errors.length === 0, snapshotId, snapshotPath, errors, manifest };
+}
+
+export {
+  canonicalJsonBytes,
+  createObjectStore,
+  findSnapshot,
+  publishSnapshot,
+  sha256,
+  verifySnapshot
+};
+export type { ObjectStore, ObjectWrite, PublishInput, VerificationResult };

package/lib/process-data/types.ts

@@ -0,0 +1,135 @@
+type JsonPrimitive = null | boolean | number | string;
+type JsonValue = JsonPrimitive | JsonValue[] | { [key: string]: JsonValue };
+
+type Availability<T> =
+  | { state: 'known'; value: T }
+  | { state: 'unknown' | 'unavailable'; reason: string };
+
+type SourceKind = 'local-file' | 'github-rest' | 'operational-report' | 'structured-telemetry';
+
+type PrivacyDisposition =
+  | { state: 'included' }
+  | { state: 'excluded-sensitive'; ruleId: string }
+  | { state: 'unavailable'; reason: string };
+
+type CapturedObject = {
+  sourceKind: SourceKind;
+  sourceIdentity: string;
+  sha256: string;
+  bytes: number;
+  content?: string;
+  disposition?: PrivacyDisposition;
+};
+
+type StoredObjectEvidence = Omit<CapturedObject, 'content'>;
+
+type RestPageEvidence = {
+  index: number;
+  itemCount: number;
+  canonicalSha256: string;
+};
+
+type RestCollectionEvidence = {
+  endpoint: string;
+  requestCount: number;
+  dataPageCount: number;
+  itemCount: number;
+  termination: 'short-page';
+  pages: RestPageEvidence[];
+};
+
+type NormalizedKind =
+  | 'task'
+  | 'artifact'
+  | 'platform-resource'
+  | 'lifecycle-event'
+  | 'review-finding'
+  | 'human-ruling'
+  | 'telemetry'
+  | 'operational-report'
+  | 'missing'
+  | 'conflict';
+
+type NormalizedRecord = {
+  recordId: string;
+  kind: NormalizedKind;
+  sourceIdentity: string;
+  sourceSha256: string;
+  binding?: string;
+  observedAt?: Availability<string>;
+  data?: JsonValue;
+};
+
+type QualityCategory =
+  | 'missing-local'
+  | 'missing-remote'
+  | 'duplicate-identity'
+  | 'binding-conflict'
+  | 'content-mismatch'
+  | 'schema-difference'
+  | 'mutable-remote'
+  | 'unrecoverable'
+  | 'privacy-excluded';
+
+type QualityFinding = {
+  findingId: string;
+  category: QualityCategory;
+  severity: 'info' | 'warning' | 'error';
+  identities: string[];
+  repairable: boolean;
+  reason: string;
+};
+
+type RepairAction = {
+  repairId: string;
+  operation: 'add' | 'supersede' | 'link';
+  sourceRecordId: string;
+  targetRecordId: string;
+  preconditionSha256: string;
+};
+
+type SnapshotManifest = {
+  schema: 'raw-manifest/v1';
+  snapshotId: string;
+  scope: 'all' | 'local' | 'github';
+  repository: string;
+  observedFrom: string;
+  observedTo: string;
+  objects: StoredObjectEvidence[];
+  endpoints: RestCollectionEvidence[];
+  recordCount: number;
+  findingCount: number;
+  repairCount: number;
+  privacyPolicyVersion: 'process-data-privacy/v1';
+  excerptsEnabled: boolean;
+  dispositionCounts: Record<'included' | 'excluded-sensitive' | 'unavailable', number>;
+  manifestSha256: string;
+};
+
+type ProcessDataError = {
+  code: string;
+  message: string;
+  retryable?: boolean;
+};
+
+type ProcessResult<T> = { ok: true; value: T } | { ok: false; error: ProcessDataError };
+
+export type {
+  Availability,
+  CapturedObject,
+  JsonPrimitive,
+  JsonValue,
+  NormalizedKind,
+  NormalizedRecord,
+  PrivacyDisposition,
+  ProcessDataError,
+  ProcessResult,
+  QualityCategory,
+  QualityFinding,
+  RepairAction,
+  RestCollectionEvidence,
+  RestPageEvidence,
+  SnapshotManifest,
+  SourceKind,
+  StoredObjectEvidence
+};

package/lib/run/index.ts

@@ -1,7 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { loadServerConfig } from '../server/config.ts';
-import { resolveTaskBranch } from '../sandbox/task-resolver.ts';
+import { resolveSandboxTarget, type SandboxWorkspaceIdentity } from '../sandbox/workspace-identity.ts';
 import { createRunId, runInSandbox, type SandboxRunMetadata } from '../sandbox/capture.ts';
 import { loadShortIdByTaskId, normalizeShortIdInput } from '../task/short-id.ts';
 import { buildTuiCommand, renderPrompt, selectTui } from './tui.ts';
@@ -19,6 +19,7 @@ export type ParsedRunArgs = {
 export type SandboxRunRequest = {
   taskRef: string;
   branch: string;
+  workspace?: SandboxWorkspaceIdentity;
   command: string[];
   runId?: string;
   recreate?: boolean;
@@ -136,7 +137,6 @@ function resolveActiveTaskIdentity(taskRef: string, repoRoot: string): ActiveTas
 
   if (TASK_ID_RE.test(taskRef)) {
     taskId = taskRef;
-    resolvedTaskRef = loadShortIdByTaskId(repoRoot).get(taskId) ?? taskRef;
   } else {
     const normalized = normalizeShortIdInput(taskRef, { shortIdLength: readShortIdLength(repoRoot) });
     if (normalized.kind !== 'shortId') return null;
@@ -211,7 +211,8 @@ export async function runSkill(args: string[], options: RunSkillOptions = {}): P
   }
 
   const repoRoot = options.repoRoot ?? config?.repoRoot ?? process.cwd();
-  const branch = resolveTaskBranch(parsed.taskRef, repoRoot);
+  const target = resolveSandboxTarget(parsed.taskRef, repoRoot);
+  const branch = target.branch;
   const identity = resolveActiveTaskIdentity(parsed.taskRef, repoRoot);
   const runId = identity ? createRunId() : undefined;
   const writeStdout = options.writeStdout ?? ((chunk: string) => process.stdout.write(chunk));
@@ -222,6 +223,7 @@ export async function runSkill(args: string[], options: RunSkillOptions = {}): P
   const result = await runSandbox({
     taskRef: parsed.taskRef,
     branch,
+    workspace: target.workspace,
     command,
     runId,
     recreate: parsed.recreate

package/lib/run/tui.ts

@@ -1,9 +1,16 @@
 import { renderAgentClientInvocation } from '../agent-clients/invocation.ts';
 import { getAgentClientAdapter } from '../agent-clients/registry.ts';
+import type { AgentClientId } from '../agent-clients/types.ts';
 
 export type TuiName = 'claude' | 'codex' | 'antigravity' | 'opencode';
 
 const TUI_NAMES = new Set(['claude', 'codex', 'antigravity', 'opencode']);
+const TUI_AGENT_CLIENT_IDS: Readonly<Record<TuiName, AgentClientId>> = Object.freeze({
+  claude: 'claude-code',
+  codex: 'codex',
+  antigravity: 'antigravity-cli',
+  opencode: 'opencode'
+});
 
 export type CommandConfig = {
   defaultTui?: unknown;
@@ -29,14 +36,10 @@ export function selectTui(
 }
 
 export function renderPrompt(params: { tui: TuiName; skill: string; args: string[] }): string {
-  const suffix = [params.skill, ...params.args].join(' ').trim();
-  if (params.tui === 'codex') {
-    return renderAgentClientInvocation(getAgentClientAdapter('codex').invocation, {
-      skillName: params.skill,
-      args: params.args
-    });
-  }
-  return `/${suffix}`;
+  return renderAgentClientInvocation(
+    getAgentClientAdapter(TUI_AGENT_CLIENT_IDS[params.tui]).invocation,
+    { skillName: params.skill, args: params.args }
+  );
 }
 
 export function buildTuiCommand(tui: TuiName, prompt: string): [string, string[]] {

package/lib/sandbox/agent-client-reconciler.ts

@@ -51,6 +51,12 @@ type SandboxRuntimeCapabilityProjection = Readonly<{
     }>;
     repair?: AgentClientSandboxRecoveryCheck['repair'];
   }>[];
+  image: SandboxImageContribution;
+}>;
+
+type SandboxImageContribution = Readonly<{
+  dockerfileFragments: readonly string[];
+  dotfilesExclusions: readonly string[];
 }>;
 
 type PlannedAgentClientRecoveryCheck = Readonly<{
@@ -64,6 +70,7 @@ type SandboxCapabilityPlan = Readonly<{
   hooksByPhase: Readonly<Record<SandboxHookPhase, readonly AgentClientSandboxHook[]>>;
   recoveryChecks: readonly PlannedAgentClientRecoveryCheck[];
   aliases: readonly SandboxAlias[];
+  image: SandboxImageContribution;
   imageSignature: string;
   runtimeSignature: string;
   runtimeProjection: SandboxRuntimeCapabilityProjection;
@@ -147,6 +154,36 @@ function assertUniqueTools(tools: readonly SandboxTool[]): void {
   }
 }
 
+function unique(values: readonly string[]): readonly string[] {
+  return Object.freeze([...new Set(values)]);
+}
+
+function sandboxImageContribution(
+  adapters: readonly AgentClientAdapter[],
+  tools: readonly SandboxTool[]
+): SandboxImageContribution {
+  const homePrefix = '/home/devuser/';
+  const derivedExclusions = tools.map((tool) => {
+    if (!tool.containerMount.startsWith(homePrefix)) {
+      throw new Error(
+        `Agent Client '${tool.id}' container mount must be below ${homePrefix.slice(0, -1)}`
+      );
+    }
+    return tool.containerMount.slice(homePrefix.length);
+  });
+  return Object.freeze({
+    dockerfileFragments: unique(adapters.flatMap((adapter) =>
+      adapter.sandbox.image?.dockerfileFragment
+        ? [adapter.sandbox.image.dockerfileFragment]
+        : []
+    )),
+    dotfilesExclusions: unique([
+      ...derivedExclusions,
+      ...adapters.flatMap((adapter) => adapter.sandbox.image?.dotfilesExclusions ?? [])
+    ])
+  });
+}
+
 function hooksByPhase(
   adapters: readonly AgentClientAdapter[]
 ): SandboxCapabilityPlan['hooksByPhase'] {
@@ -207,6 +244,7 @@ function createSandboxCapabilityPlan(
 
   const tools = Object.freeze([...nonClientTools, ...selectedTools, ...selectedCustomTools]);
   assertUniqueTools(tools);
+  const image = sandboxImageContribution(selectedAgentClients, selectedTools);
   const phaseHooks = hooksByPhase(selectedAgentClients);
   const hookProjection = selectedAgentClients.flatMap((adapter) =>
     adapter.sandbox.hooks.map((hook) => ({
@@ -239,7 +277,8 @@ function createSandboxCapabilityPlan(
     tools: Object.freeze(tools.map(runtimeToolProjection)),
     selectedAgentClients: Object.freeze(selectedAgentClients.map((adapter) => adapter.id)),
     hooks: Object.freeze(hookProjection),
-    recoveryChecks: recoveryCheckProjection
+    recoveryChecks: recoveryCheckProjection,
+    image
   });
   const cleanupInventory = Object.freeze([
     agentInfraTool(config.home),
@@ -256,6 +295,7 @@ function createSandboxCapabilityPlan(
     aliases: Object.freeze(
       listAgentClientAdapters().flatMap((adapter) => adapter.sandbox.aliases)
     ),
+    image,
     imageSignature: hash(tools.map(({ id, install }) => ({ id, install }))),
     runtimeSignature: hash(runtimeProjection),
     runtimeProjection,
@@ -367,12 +407,14 @@ export {
   DEFAULT_SANDBOX_HOOK_TIMEOUT_MS,
   createSandboxCapabilityPlan,
   runBoundedSandboxHookCommand,
-  runSandboxHooks
+  runSandboxHooks,
+  sandboxImageContribution
 };
 export type {
   HookExecutionResult,
   SandboxCapabilityConfig,
   SandboxCapabilityPlan,
+  SandboxImageContribution,
   PlannedAgentClientRecoveryCheck,
   SandboxRuntimeCapabilityProjection
 };

package/lib/sandbox/capture.ts

@@ -11,10 +11,12 @@ import {
   startSandboxContainer,
   type SandboxRow
 } from './commands/list-running.ts';
+import { resolveSandboxTarget, type SandboxWorkspaceIdentity } from './workspace-identity.ts';
 
 export type SandboxCaptureRequest = {
   taskRef: string;
   branch: string;
+  workspace?: SandboxWorkspaceIdentity;
   command: string[];
   timeoutMs?: number;
   recreate?: boolean;
@@ -44,6 +46,7 @@ export type SandboxCaptureOptions = {
   startContainer?: (name: string) => void;
   ensureReady?: (params: {
     branch: string;
+    workspace?: SandboxWorkspaceIdentity;
     row: SandboxRow;
     allowRecreate: boolean;
   }) => Promise<SandboxReadyResult>;
@@ -183,6 +186,8 @@ export async function runInSandbox(
 ): Promise<SandboxCaptureResult> {
   const config = options.engine ? null : loadConfig();
   const engine = options.engine ?? detectEngine(config!);
+  const workspace = request.workspace
+    ?? (config ? resolveSandboxTarget(request.taskRef, config.repoRoot).workspace : undefined);
   const rows =
     options.rows ??
     (() => {
@@ -200,6 +205,7 @@ export async function runInSandbox(
   if (options.ensureReady) {
     container = (await options.ensureReady({
       branch: request.branch,
+      workspace,
       row: found,
       allowRecreate: request.recreate ?? false
     })).container;
@@ -208,11 +214,12 @@ export async function runInSandbox(
       config,
       engine,
       branch: request.branch,
+      workspace,
       row: found,
       allowRecreate: request.recreate,
-      recreate: async (targetBranch) => {
+      recreate: async () => {
         const { create } = await import('./commands/create.ts');
-        await create([targetBranch, '--no-refresh']);
+        await create([request.taskRef, '--no-refresh']);
       }
     })).container;
   } else if (!found.running) {