@fitlab-ai/agent-infra 0.9.6 → 0.9.7

package/lib/agent-clients/adapters/codex-lifecycle/sandbox-controller.ts

@@ -0,0 +1,453 @@
+import crypto from 'node:crypto';
+import { spawn, spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import semver from 'semver';
+import * as toml from 'smol-toml';
+
+import { requestSandboxControl } from '../../../sandbox/control/client.ts';
+import { readSandboxControlStatus } from '../../../sandbox/control/state.ts';
+import { getProcessStartTime, isProcessAlive } from '../../../server/process-state.ts';
+import { computeLifecycleBuildIdentity } from './build-identity.ts';
+import type { LifecycleBuildIdentity } from './build-identity.ts';
+
+type ControllerControl = Readonly<{
+  token: string;
+  generation: string;
+  channelDir: string;
+  statusDir: string;
+}>;
+
+type CodexSandboxControllerContext = Readonly<{
+  version: 1;
+  taskId: string;
+  controlGeneration: string;
+  controllerInstanceDigest: string;
+  parentPid: number;
+  parentStartTime: number;
+  issuedAt: number;
+  expiresAt: number;
+  buildIdentity: LifecycleBuildIdentity;
+  hookDefinitionHash: string;
+  lifecycleProfilesHash: string;
+}>;
+
+type ControllerInput = Readonly<{
+  taskId: string;
+  taskRef: string;
+  executorModel?: string;
+  executorReasoningEffort?: string;
+  reviewerModel?: string;
+  reviewerReasoningEffort?: string;
+}>;
+
+type ControllerOptions = Readonly<{
+  repoRoot?: string;
+  codexHome?: string;
+  temporaryRoot?: string;
+  control?: ControllerControl;
+  now?: () => number;
+  codexVersion?: () => string;
+  verifyTaskBinding?: (taskId: string, control: ControllerControl) => void;
+  environment?: NodeJS.ProcessEnv;
+}>;
+
+type PreparedCodexSandboxController = Readonly<{
+  command: 'codex';
+  args: readonly string[];
+  env: NodeJS.ProcessEnv;
+  home: string;
+  contextPath: string;
+  context: CodexSandboxControllerContext;
+  cleanup: () => void;
+}>;
+
+const CONTEXT_TTL_MS = 4 * 60 * 60 * 1_000;
+
+function digestFiles(files: readonly string[]): string {
+  const hash = crypto.createHash('sha256');
+  for (const file of [...files].sort()) {
+    const stat = fs.lstatSync(file);
+    if (!stat.isFile() || stat.isSymbolicLink()) {
+      throw new Error('CODEX_SANDBOX_CONTROLLER_BUNDLE_MISMATCH');
+    }
+    hash.update(path.basename(file));
+    hash.update('\0');
+    hash.update(fs.readFileSync(file));
+    hash.update('\0');
+  }
+  return hash.digest('hex');
+}
+
+function copyRegular(source: string, destination: string, mode: number): void {
+  const stat = fs.lstatSync(source);
+  if (!stat.isFile() || stat.isSymbolicLink()) {
+    throw new Error('CODEX_SANDBOX_CONTROLLER_INPUT_INVALID');
+  }
+  fs.mkdirSync(path.dirname(destination), { recursive: true, mode: 0o700 });
+  fs.copyFileSync(source, destination);
+  fs.chmodSync(destination, mode);
+}
+
+function controlFromEnvironment(): ControllerControl {
+  const token = process.env.AGENT_INFRA_CONTROL_TOKEN;
+  const generation = process.env.AGENT_INFRA_CONTROL_GENERATION;
+  const channelDir = process.env.AGENT_INFRA_CONTROL_DIR;
+  const statusDir = process.env.AGENT_INFRA_CONTROL_STATUS_DIR;
+  if (!token || !generation || !channelDir || !statusDir) {
+    throw new Error('CODEX_SANDBOX_CONTROLLER_CONTROL_MISSING');
+  }
+  return { token, generation, channelDir, statusDir };
+}
+
+function verifyControl(taskId: string, control: ControllerControl): void {
+  let status: ReturnType<typeof readSandboxControlStatus> | null = null;
+  let lastError: unknown = null;
+  for (let attempt = 0; attempt < 5; attempt += 1) {
+    try {
+      status = readSandboxControlStatus(control.statusDir);
+      break;
+    } catch (error) {
+      lastError = error;
+      if (attempt < 4) Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 25);
+    }
+  }
+  if (!status) {
+    throw new Error(`CODEX_SANDBOX_CONTROLLER_CONTROL_UNAVAILABLE: ${String(lastError)}`);
+  }
+  if (status.generation !== control.generation
+    || status.state !== 'healthy'
+    || Date.now() - status.updatedAt > 1_500) {
+    throw new Error('CODEX_SANDBOX_CONTROLLER_CONTROL_UNAVAILABLE');
+  }
+  const response = requestSandboxControl({
+    family: 'task-orchestration',
+    args: [taskId, 'status'],
+    ...control,
+    timeoutMs: 30_000
+  });
+  let payload: { taskId?: unknown } = {};
+  try {
+    payload = JSON.parse(response.stdout) as { taskId?: unknown };
+  } catch {
+    throw new Error('CODEX_SANDBOX_CONTROLLER_TASK_BINDING_INVALID');
+  }
+  if (payload.taskId !== taskId) throw new Error('CODEX_SANDBOX_CONTROLLER_TASK_BINDING_INVALID');
+}
+
+function detectedCodexVersion(): string {
+  const result = spawnSync('codex', ['--version'], { encoding: 'utf8' });
+  const version = /codex-cli\s+(\d+\.\d+\.\d+)/u.exec(result.stdout ?? '')?.[1];
+  if (result.status !== 0 || !version) throw new Error('CODEX_SANDBOX_CONTROLLER_CODEX_UNAVAILABLE');
+  return version;
+}
+
+function sanitizedConfig(source: string, destination: string, sourceHome: string, targetHome: string): readonly string[] {
+  if (!fs.existsSync(source)) return [];
+  const parsed = toml.parse(fs.readFileSync(source, 'utf8')) as Record<string, unknown>;
+  const allowed = new Set([
+    'model',
+    'model_provider',
+    'model_providers',
+    'model_reasoning_effort',
+    'model_auto_compact_token_limit',
+    'preferred_auth_method'
+  ]);
+  const output = Object.fromEntries(Object.entries(parsed).filter(([key]) => allowed.has(key)));
+  const catalog = parsed.model_catalog_json;
+  if (typeof catalog === 'string' && catalog.trim()) {
+    const resolved = path.resolve(sourceHome, catalog.replace(/^~[/\\]/u, ''));
+    const relative = path.relative(sourceHome, resolved);
+    if (relative.startsWith('..') || path.isAbsolute(relative)) {
+      throw new Error('CODEX_SANDBOX_CONTROLLER_CONFIG_PATH_INVALID');
+    }
+    const target = path.join(targetHome, 'model-catalogs', path.basename(resolved));
+    copyRegular(resolved, target, 0o600);
+    output.model_catalog_json = target;
+  }
+  fs.writeFileSync(destination, `${toml.stringify(output)}\n`, { mode: 0o600 });
+  const providerEnvironment = new Set<string>();
+  const providers = output.model_providers;
+  if (providers && typeof providers === 'object' && !Array.isArray(providers)) {
+    for (const provider of Object.values(providers)) {
+      if (!provider || typeof provider !== 'object' || Array.isArray(provider)) continue;
+      for (const key of ['env_key', 'envKey']) {
+        const name = (provider as Record<string, unknown>)[key];
+        if (typeof name === 'string' && /^[A-Z][A-Z0-9_]{1,127}$/u.test(name)) {
+          providerEnvironment.add(name);
+        }
+      }
+    }
+  }
+  return Object.freeze([...providerEnvironment]);
+}
+
+function isolatedEnvironment(
+  home: string,
+  shimDir: string,
+  contextPath: string,
+  taskId: string,
+  control: ControllerControl,
+  providerEnvironment: readonly string[],
+  sourceEnvironment: NodeJS.ProcessEnv
+): NodeJS.ProcessEnv {
+  const inherited = new Set([
+    'LANG', 'LC_ALL', 'TERM', 'COLORTERM',
+    'HTTP_PROXY', 'HTTPS_PROXY', 'NO_PROXY',
+    'http_proxy', 'https_proxy', 'no_proxy',
+    'SSL_CERT_FILE', 'SSL_CERT_DIR', 'NODE_EXTRA_CA_CERTS',
+    'CODEX_CI',
+    ...providerEnvironment
+  ]);
+  const env: NodeJS.ProcessEnv = {};
+  for (const key of inherited) {
+    if (sourceEnvironment[key] !== undefined) env[key] = sourceEnvironment[key];
+  }
+  return {
+    ...env,
+    HOME: home,
+    CODEX_HOME: home,
+    PATH: `${shimDir}${path.delimiter}${sourceEnvironment.PATH ?? ''}`,
+    AGENT_INFRA_TASK_ID: taskId,
+    AGENT_INFRA_CONTROL_TOKEN: control.token,
+    AGENT_INFRA_CONTROL_GENERATION: control.generation,
+    AGENT_INFRA_CONTROL_DIR: control.channelDir,
+    AGENT_INFRA_CONTROL_STATUS_DIR: control.statusDir,
+    AGENT_INFRA_CODEX_CONTROLLER_CONTEXT: contextPath
+  };
+}
+
+function shellQuote(value: string): string {
+  return `'${value.replaceAll("'", "'\\''")}'`;
+}
+
+function prepareCodexSandboxController(
+  input: ControllerInput,
+  options: ControllerOptions = {}
+): PreparedCodexSandboxController {
+  const repoRoot = path.resolve(options.repoRoot ?? process.cwd());
+  const sourceHome = path.resolve(options.codexHome ?? process.env.CODEX_HOME ?? path.join(os.homedir(), '.codex'));
+  const control = options.control ?? controlFromEnvironment();
+  (options.verifyTaskBinding ?? verifyControl)(input.taskId, control);
+  const version = (options.codexVersion ?? detectedCodexVersion)();
+  if (!semver.gte(version, '0.147.0')) throw new Error('CODEX_SANDBOX_CONTROLLER_CODEX_UNSUPPORTED');
+
+  const runtimeRoot = path.resolve(options.temporaryRoot
+    ?? path.join(os.tmpdir(), 'agent-infra-codex-controllers'));
+  fs.mkdirSync(runtimeRoot, { recursive: true, mode: 0o700 });
+  fs.chmodSync(runtimeRoot, 0o700);
+  const key = crypto.createHash('sha256')
+    .update(`${input.taskId}\0${control.generation}`)
+    .digest('hex');
+  const leasePath = path.join(runtimeRoot, `${key}.lease.json`);
+  if (fs.existsSync(leasePath)) {
+    const lease = JSON.parse(fs.readFileSync(leasePath, 'utf8')) as { pid?: number; startTime?: number };
+    if (Number.isSafeInteger(lease.pid) && typeof lease.startTime === 'number'
+      && getProcessStartTime(lease.pid!) === lease.startTime) {
+      throw new Error('CODEX_SANDBOX_CONTROLLER_BUSY');
+    }
+    fs.unlinkSync(leasePath);
+  }
+
+  const parentStartTime = getProcessStartTime(process.pid);
+  if (!parentStartTime) throw new Error('CODEX_SANDBOX_CONTROLLER_PROCESS_IDENTITY_INVALID');
+  const instanceDigest = crypto.randomBytes(32).toString('hex');
+  fs.writeFileSync(leasePath, `${JSON.stringify({
+    version: 1,
+    pid: process.pid,
+    startTime: parentStartTime,
+    taskId: input.taskId,
+    generation: control.generation,
+    instanceDigest
+  })}\n`, { mode: 0o600, flag: 'wx' });
+
+  const home = fs.mkdtempSync(path.join(runtimeRoot, `${key}-`));
+  fs.chmodSync(home, 0o700);
+  let cleaned = false;
+  const cleanup = () => {
+    if (cleaned) return;
+    cleaned = true;
+    const relative = path.relative(runtimeRoot, home);
+    if (!relative.startsWith('..') && !path.isAbsolute(relative)) {
+      fs.rmSync(home, { recursive: true, force: true });
+    }
+    try {
+      const lease = JSON.parse(fs.readFileSync(leasePath, 'utf8')) as { instanceDigest?: string };
+      if (lease.instanceDigest === instanceDigest) fs.unlinkSync(leasePath);
+    } catch {
+      // A missing or replaced lease is owned by another cleanup path.
+    }
+  };
+
+  try {
+    const auth = path.join(sourceHome, 'auth.json');
+    if (fs.existsSync(auth)) copyRegular(auth, path.join(home, 'auth.json'), 0o600);
+    const providerEnvironment = sanitizedConfig(
+      path.join(sourceHome, 'config.toml'),
+      path.join(home, 'config.toml'),
+      sourceHome,
+      home
+    );
+
+    const hooks = path.join(repoRoot, '.codex', 'hooks.json');
+    const executor = path.join(repoRoot, '.codex', 'agents', 'agent-infra-lifecycle-executor.toml');
+    const reviewer = path.join(repoRoot, '.codex', 'agents', 'agent-infra-lifecycle-reviewer.toml');
+    copyRegular(hooks, path.join(home, 'hooks.json'), 0o600);
+    copyRegular(executor, path.join(home, 'agents', path.basename(executor)), 0o600);
+    copyRegular(reviewer, path.join(home, 'agents', path.basename(reviewer)), 0o600);
+    if (crypto.createHash('sha256').update(fs.readFileSync(path.join(home, 'hooks.json'))).digest('hex')
+      !== crypto.createHash('sha256').update(fs.readFileSync(hooks)).digest('hex')
+      || digestFiles([
+        path.join(home, 'agents', path.basename(executor)),
+        path.join(home, 'agents', path.basename(reviewer))
+      ]) !== digestFiles([executor, reviewer])) {
+      throw new Error('CODEX_SANDBOX_CONTROLLER_BUNDLE_MISMATCH');
+    }
+
+    const buildIdentity = computeLifecycleBuildIdentity(repoRoot);
+    const now = (options.now ?? Date.now)();
+    const context: CodexSandboxControllerContext = Object.freeze({
+      version: 1,
+      taskId: input.taskId,
+      controlGeneration: control.generation,
+      controllerInstanceDigest: instanceDigest,
+      parentPid: process.pid,
+      parentStartTime,
+      issuedAt: now,
+      expiresAt: now + CONTEXT_TTL_MS,
+      buildIdentity,
+      hookDefinitionHash: crypto.createHash('sha256').update(fs.readFileSync(hooks)).digest('hex'),
+      lifecycleProfilesHash: digestFiles([executor, reviewer])
+    });
+    const contextPath = path.join(home, 'controller-context.json');
+    fs.writeFileSync(contextPath, `${JSON.stringify(context, null, 2)}\n`, { mode: 0o600 });
+
+    const shimDir = path.join(home, 'bin');
+    fs.mkdirSync(shimDir, { mode: 0o700 });
+    const internalCli = path.resolve(process.argv[1] ?? path.join(repoRoot, 'bin', 'internal-cli.ts'));
+    const source = internalCli.endsWith('.ts')
+      ? `#!/bin/sh\nexec ${shellQuote(process.execPath)} --experimental-strip-types ${shellQuote(internalCli)} "$@"\n`
+      : `#!/bin/sh\nexec ${shellQuote(process.execPath)} ${shellQuote(internalCli)} "$@"\n`;
+    fs.writeFileSync(path.join(shimDir, 'agent-infra-internal'), source, { mode: 0o700 });
+
+    const policy = [
+      input.executorModel ? `--executor-model ${input.executorModel}` : '',
+      input.executorReasoningEffort ? `--executor-reasoning-effort ${input.executorReasoningEffort}` : '',
+      input.reviewerModel ? `--reviewer-model ${input.reviewerModel}` : '',
+      input.reviewerReasoningEffort ? `--reviewer-reasoning-effort ${input.reviewerReasoningEffort}` : ''
+    ].filter(Boolean).join(' ');
+    const prompt = `$run-task ${input.taskRef}${policy ? ` ${policy}` : ''}`;
+    const args = Object.freeze([
+      'exec',
+      '--enable', 'hooks',
+      '--enable', 'multi_agent',
+      '--dangerously-bypass-hook-trust',
+      '--dangerously-bypass-approvals-and-sandbox',
+      '--json',
+      '-C', repoRoot,
+      prompt
+    ]);
+    const env = isolatedEnvironment(
+      home,
+      shimDir,
+      contextPath,
+      input.taskId,
+      control,
+      providerEnvironment,
+      options.environment ?? process.env
+    );
+    return Object.freeze({
+      command: 'codex' as const,
+      args,
+      env,
+      home,
+      contextPath,
+      context,
+      cleanup
+    });
+  } catch (error) {
+    cleanup();
+    throw error;
+  }
+}
+
+function verifyCodexSandboxControllerContext(
+  contextPath: string,
+  taskId: string,
+  options: Readonly<{ repoRoot?: string; now?: number; generation?: string }> = {}
+): CodexSandboxControllerContext {
+  const stat = fs.lstatSync(contextPath);
+  if (!stat.isFile() || stat.isSymbolicLink() || (stat.mode & 0o077) !== 0) {
+    throw new Error('CODEX_SANDBOX_CONTROLLER_CONTEXT_INVALID');
+  }
+  const context = JSON.parse(fs.readFileSync(contextPath, 'utf8')) as CodexSandboxControllerContext;
+  const generation = options.generation ?? process.env.AGENT_INFRA_CONTROL_GENERATION;
+  if (context.version !== 1
+    || context.taskId !== taskId
+    || context.controlGeneration !== generation
+    || context.expiresAt < (options.now ?? Date.now())
+    || getProcessStartTime(context.parentPid) !== context.parentStartTime
+    || !isProcessAlive(context.parentPid)) {
+    throw new Error('CODEX_SANDBOX_CONTROLLER_CONTEXT_INVALID');
+  }
+  const current = computeLifecycleBuildIdentity(options.repoRoot ?? process.cwd());
+  if (JSON.stringify(current) !== JSON.stringify(context.buildIdentity)) {
+    throw new Error('CODEX_SANDBOX_CONTROLLER_BUNDLE_MISMATCH');
+  }
+  return Object.freeze(context);
+}
+
+async function runCodexSandboxController(
+  input: ControllerInput,
+  options: ControllerOptions = {}
+): Promise<number> {
+  const prepared = prepareCodexSandboxController(input, options);
+  try {
+    const child = spawn(prepared.command, [...prepared.args], {
+      cwd: options.repoRoot ?? process.cwd(),
+      env: prepared.env,
+      stdio: 'inherit',
+      detached: process.platform !== 'win32'
+    });
+    let forceKill: NodeJS.Timeout | undefined;
+    const terminate = () => {
+      if (child.pid && process.platform !== 'win32') {
+        try { process.kill(-child.pid, 'SIGTERM'); } catch { child.kill('SIGTERM'); }
+      } else child.kill('SIGTERM');
+      forceKill = setTimeout(() => {
+        if (child.pid && process.platform !== 'win32') {
+          try { process.kill(-child.pid, 'SIGKILL'); } catch { child.kill('SIGKILL'); }
+        } else child.kill('SIGKILL');
+      }, 5_000);
+      forceKill.unref();
+    };
+    process.once('SIGINT', terminate);
+    process.once('SIGTERM', terminate);
+    try {
+      return await new Promise<number>((resolve, reject) => {
+        child.once('error', reject);
+        child.once('exit', (code, signal) => resolve(code ?? (signal ? 1 : 0)));
+      });
+    } finally {
+      if (forceKill) clearTimeout(forceKill);
+      process.off('SIGINT', terminate);
+      process.off('SIGTERM', terminate);
+    }
+  } finally {
+    prepared.cleanup();
+  }
+}
+
+export {
+  prepareCodexSandboxController,
+  runCodexSandboxController,
+  verifyCodexSandboxControllerContext
+};
+export type {
+  CodexSandboxControllerContext,
+  ControllerControl,
+  ControllerInput,
+  ControllerOptions,
+  PreparedCodexSandboxController
+};

package/lib/agent-clients/adapters/codex-lifecycle/store.ts

@@ -18,6 +18,7 @@ type StoredCodexLifecycle = Readonly<{
   state: CodexLifecycleState;
   consumer: string | null;
   consumedAt: string | null;
+  spawnObservedAt: string | null;
   updatedAt: string;
 }>;
 
@@ -33,6 +34,11 @@ type CodexLifecycleStoreResult = Readonly<{
   state: CodexLifecycleState;
 }>;
 
+type ActiveCodexLifecycleEvidenceQuery = Readonly<{
+  nativeAgent: string;
+  hookDefinitionHash: string;
+}>;
+
 const LOCK_RETRY_MS = 10;
 const LOCK_TIMEOUT_MS = 1_000;
 const LOCK_STALE_MS = 30_000;
@@ -49,10 +55,14 @@ function readRecord(file: string): StoredCodexLifecycle {
     || value.revision < 1
     || !value.state
     || value.state.schemaVersion !== 1
+    || (value.spawnObservedAt != null && (
+      typeof value.spawnObservedAt !== 'string'
+      || !Number.isFinite(Date.parse(value.spawnObservedAt))
+    ))
   ) {
     throw new Error(`Codex lifecycle record '${path.basename(file)}' is invalid`);
   }
-  return value;
+  return Object.freeze({ ...value, spawnObservedAt: value.spawnObservedAt ?? null });
 }
 
 function recordFiles(root: string): string[] {
@@ -62,6 +72,19 @@ function recordFiles(root: string): string[] {
     .map((name) => path.join(root, name));
 }
 
+function hasActiveCodexLifecycleEvidence(
+  root: string,
+  query: ActiveCodexLifecycleEvidenceQuery
+): boolean {
+  return recordFiles(root).map(readRecord).some((record) => {
+    const evidence = record.state.startEvidence;
+    return record.consumer === null
+      && ['start-ready', 'observed-terminal', 'stop-ready'].includes(record.state.status)
+      && evidence?.nativeAgent === query.nativeAgent
+      && evidence.hookDefinitionHash === query.hookDefinitionHash;
+  });
+}
+
 function writeRecord(file: string, record: StoredCodexLifecycle, expectedRevision: number): void {
   const temp = `${file}.${process.pid}.${crypto.randomUUID()}.tmp`;
   fs.writeFileSync(temp, `${JSON.stringify(record, null, 2)}\n`, {
@@ -154,6 +177,7 @@ function createCodexLifecycleStore(options: CodexLifecycleStoreOptions) {
   function apply(event: CodexLifecycleEvent): CodexLifecycleStoreResult {
     return withWriteLock(() => {
       const file = locate(event);
+      const observedAt = now();
       const current = fs.existsSync(file)
         ? readRecord(file)
         : Object.freeze({
@@ -162,7 +186,8 @@ function createCodexLifecycleStore(options: CodexLifecycleStoreOptions) {
             state: createCodexLifecycleState(options.cliVersion),
             consumer: null,
             consumedAt: null,
-            updatedAt: now()
+            spawnObservedAt: null,
+            updatedAt: observedAt
           });
       if (current.consumer) throw new Error(`Codex lifecycle evidence was already consumed by '${current.consumer}'`);
       const nextState = reduceCodexLifecycleEvent(current.state, event);
@@ -172,7 +197,10 @@ function createCodexLifecycleStore(options: CodexLifecycleStoreOptions) {
         state: nextState,
         consumer: null,
         consumedAt: null,
-        updatedAt: now()
+        spawnObservedAt: event.type === 'hook-spawn' && current.revision === 0
+          ? observedAt
+          : current.spawnObservedAt,
+        updatedAt: observedAt
       });
       writeRecord(file, next, current.revision);
       return Object.freeze({ path: file, revision: next.revision, state: next.state });
@@ -290,8 +318,9 @@ function createCodexLifecycleStore(options: CodexLifecycleStoreOptions) {
   return Object.freeze({ root, apply, applyToSpawn, consume, expireBefore, findByParent, read });
 }
 
-export { createCodexLifecycleStore };
+export { createCodexLifecycleStore, hasActiveCodexLifecycleEvidence };
 export type {
+  ActiveCodexLifecycleEvidenceQuery,
   CodexLifecycleStoreOptions,
   CodexLifecycleStoreResult,
   StoredCodexLifecycle

package/lib/defaults.json

@@ -56,7 +56,6 @@
       ".agents/skills/",
       ".agents/templates/",
       ".agents/workflows/",
-      ".agents/workspace/README.md",
       ".git-hooks/check-large-files.cjs",
       ".git-hooks/check-version-format.sh",
       ".github/scripts/",
@@ -84,6 +83,15 @@
       ".git-hooks/pre-commit",
       ".gitignore"
     ],
-    "ejected": []
+    "ejected": [],
+    "retiredManaged": [
+      {
+        "path": ".agents/workspace/README.md",
+        "templateHashes": [
+          "sha256:967b27ca4008154c5abf99a1df728242f80ed3ace9bd98eb2828bc1c76af826c",
+          "sha256:15aa21942cf2a1396d27834f1d3d723b61a46f8d14600b706f39f3bebc21aea3"
+        ]
+      }
+    ]
   }
 }

package/lib/git/workflow.ts

@@ -20,6 +20,10 @@ function value(runner: GitRunner, cwd: string, args: readonly string[], trim = t
   return result.status === 0 ? (trim ? result.stdout.trim() : result.stdout.replace(/\n$/, '')) : null;
 }
 
+function nulPaths(output: string): string[] {
+  return output.split('\0').filter(Boolean);
+}
+
 function cleanMessage(message: string): string {
   return message.replace(/(https?:\/\/)[^\s/@:]+(?::[^\s/@]*)?@/gi, '$1***@').trim();
 }
@@ -68,8 +72,27 @@ function commitExplicitPaths(input: { cwd: string; paths: readonly string[]; mes
   const selected = new Set(input.paths);
   const unrelatedStaged = before.snapshot.staged.filter((candidate) => !selected.has(candidate));
   if (unrelatedStaged.length > 0) return { status: 'failed' as const, changed: false, snapshot: before.snapshot, operations: [], error: { code: 'GIT_STAGED_SCOPE_MISMATCH', message: `Unrelated staged paths: ${unrelatedStaged.join(', ')}` } };
-  const add = run(runner, input.cwd, ['add', '--', ...input.paths]);
-  if (add.status !== 0) return { status: 'failed' as const, changed: false, snapshot: inspectGitWorkflow(input.cwd, runner).snapshot, operations: [{ name: 'stage', status: 'failed' as const, message: add.stderr.trim() }], error: { code: 'GIT_STAGE_FAILED', message: add.stderr.trim() } };
+  const stageFailure = (message: string) => ({ status: 'failed' as const, changed: false, snapshot: inspectGitWorkflow(input.cwd, runner).snapshot, operations: [{ name: 'stage', status: 'failed' as const, message }], error: { code: 'GIT_STAGE_FAILED', message } });
+  const indexed = run(runner, input.cwd, ['ls-files', '-z', '--', ...input.paths]);
+  if (indexed.status !== 0) return stageFailure(indexed.stderr.trim());
+  const headed = run(runner, input.cwd, ['ls-tree', '-r', '--name-only', '-z', 'HEAD', '--', ...input.paths]);
+  if (headed.status !== 0) return stageFailure(headed.stderr.trim());
+  const indexedPaths = new Set(nulPaths(indexed.stdout));
+  const headPaths = new Set(nulPaths(headed.stdout));
+  const trackedPaths: string[] = [];
+  const addPaths: string[] = [];
+  for (const candidate of input.paths) {
+    if (indexedPaths.has(candidate)) trackedPaths.push(candidate);
+    else if (!headPaths.has(candidate) || fs.existsSync(path.join(input.cwd, candidate))) addPaths.push(candidate);
+  }
+  if (trackedPaths.length > 0) {
+    const update = run(runner, input.cwd, ['add', '-u', '--', ...trackedPaths]);
+    if (update.status !== 0) return stageFailure(update.stderr.trim());
+  }
+  if (addPaths.length > 0) {
+    const add = run(runner, input.cwd, ['add', '--', ...addPaths]);
+    if (add.status !== 0) return stageFailure(add.stderr.trim());
+  }
   const staged = run(runner, input.cwd, ['diff', '--cached', '--quiet', '--']);
   if (staged.status === 0) return { status: 'no-op' as const, changed: false, snapshot: inspectGitWorkflow(input.cwd, runner).snapshot, operations: [{ name: 'stage', status: 'no-op' as const }], error: null };
   if (input.expectedTree) {