@fitlab-ai/agent-infra 0.9.7 → 0.9.8

package/lib/internal/task-override.ts

@@ -0,0 +1,138 @@
+import {
+  consumeHumanOverride,
+  diagnoseHumanOverrideForTask,
+  issueHumanOverride
+} from '../task/human-override.ts';
+import type { ConsumeHumanOverrideRequest, HumanOverrideRequest } from '../task/human-override.ts';
+import { resolveTaskRef } from '../task/resolve-ref.ts';
+import { TaskExecutionLockError, withTaskExecutionLock } from '../task/task-execution-lock.ts';
+
+const USAGE = `Usage: agent-infra-internal task-override <task-ref> <diagnose|issue|consume> [options]
+
+Options: --failure-id <id> --target <target> --operator <operator> --reason <reason> --scope <scope>
+         --intent <lifecycle-intent> --alert-number <N> --issue-number <N> --staging-dir <path>
+         --expires-at <timestamp> --ticket <ticket-id> --pr-number <N>
+`;
+
+const FLAGS: Record<string, string> = {
+  '--failure-id': 'failureId',
+  '--target': 'target',
+  '--operator': 'operator',
+  '--reason': 'reason',
+  '--scope': 'scope',
+  '--intent': 'intent',
+  '--failure-digest': 'failureDigest',
+  '--expires-at': 'expiresAt',
+  '--ticket': 'ticketId',
+  '--facts': 'observedFacts',
+  '--alert-number': 'alertNumber',
+  '--issue-number': 'issueNumber',
+  '--pr-number': 'pullRequestNumber',
+  '--staging-dir': 'stagingDir'
+};
+
+function usageFailure(message: string): void {
+  process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, error: { code: 'OVERRIDE_PAYLOAD_INVALID', message } })}\n`);
+  process.stderr.write(USAGE);
+  process.exitCode = 1;
+}
+
+function taskOverride(args: string[] = []): void {
+  if (args[0] === '--help' || args[0] === '-h') { process.stdout.write(USAGE); return; }
+  const [taskRef, operation] = args;
+  if (!taskRef || !operation || !['diagnose', 'issue', 'consume'].includes(operation)) {
+    usageFailure('task ref and a valid operation are required');
+    return;
+  }
+  const values: Record<string, unknown> = { taskRef };
+  const seen = new Set<string>();
+  for (let index = 2; index < args.length; index += 1) {
+    const flag = args[index]!;
+    const key = FLAGS[flag];
+    if (!key) { usageFailure(`unknown option '${flag}'`); return; }
+    if (seen.has(flag)) { usageFailure(`duplicate option '${flag}'`); return; }
+    const value = args[++index];
+    if (value === undefined || value.startsWith('--')) { usageFailure(`option '${flag}' requires a value`); return; }
+    seen.add(flag);
+    values[key] = key === 'observedFacts' ? value.split(',').map((fact) => fact.trim()).filter(Boolean)
+      : key === 'alertNumber' || key === 'issueNumber' || key === 'pullRequestNumber' ? Number(value) : value;
+  }
+
+  const required: Record<string, string[]> = {
+    diagnose: [],
+    issue: ['failureId', 'target', 'operator', 'reason', 'scope', 'expiresAt'],
+    consume: ['failureId', 'target', 'scope', 'ticketId']
+  };
+  const missing = required[operation]!.find((key) => values[key] === undefined);
+  if (missing) { usageFailure(`${operation} requires '--${missing.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`)}'`); return; }
+
+  const resolved = resolveTaskRef(taskRef);
+  if (!resolved.ok) {
+    process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, error: { code: resolved.code, message: resolved.message } })}\n`);
+    process.exitCode = 1;
+    return;
+  }
+
+  let result;
+  try {
+    if (operation === 'diagnose') {
+      result = diagnoseHumanOverrideForTask(
+        taskRef,
+        values.failureId ? String(values.failureId) : undefined,
+        values.target ? String(values.target) : undefined
+      );
+    } else if (operation === 'issue') {
+      result = withTaskExecutionLock(
+        resolved.repoRoot,
+        resolved.taskId,
+        'task-override.issue',
+        () => issueHumanOverride({
+          taskRef,
+          failureId: String(values.failureId),
+          target: String(values.target),
+          operator: String(values.operator),
+          reason: String(values.reason),
+          scope: String(values.scope),
+          expiresAt: String(values.expiresAt),
+          ...(values.intent ? { intent: String(values.intent) as HumanOverrideRequest['intent'] } : {}),
+          ...(values.alertNumber !== undefined ? { alertNumber: Number(values.alertNumber) } : {}),
+          ...(values.issueNumber !== undefined ? { issueNumber: Number(values.issueNumber) } : {}),
+          ...(values.pullRequestNumber !== undefined ? { pullRequestNumber: Number(values.pullRequestNumber) } : {}),
+          ...(values.stagingDir ? { stagingDir: String(values.stagingDir) } : {}),
+          ...(values.failureDigest ? { failureDigest: String(values.failureDigest) } : {})
+        } satisfies HumanOverrideRequest)
+      );
+    } else {
+        result = withTaskExecutionLock(
+        resolved.repoRoot,
+        resolved.taskId,
+        'task-override.consume',
+        () => consumeHumanOverride({
+          taskRef,
+          ticketId: String(values.ticketId),
+          failureId: String(values.failureId),
+          target: String(values.target),
+          scope: String(values.scope),
+          ...(values.intent ? { intent: String(values.intent) as ConsumeHumanOverrideRequest['intent'] } : {}),
+          ...(values.alertNumber !== undefined ? { alertNumber: Number(values.alertNumber) } : {}),
+          ...(values.issueNumber !== undefined ? { issueNumber: Number(values.issueNumber) } : {}),
+          ...(values.pullRequestNumber !== undefined ? { pullRequestNumber: Number(values.pullRequestNumber) } : {}),
+          ...(values.stagingDir ? { stagingDir: String(values.stagingDir) } : {}),
+          ...(values.failureDigest ? { failureDigest: String(values.failureDigest) } : {}),
+          ...(values.observedFacts ? { observedFacts: values.observedFacts as string[] } : {})
+        } satisfies ConsumeHumanOverrideRequest)
+      );
+    }
+  } catch (cause) {
+    if (cause instanceof TaskExecutionLockError) {
+      process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, error: { code: cause.code, message: cause.message } })}\n`);
+      process.exitCode = 1;
+      return;
+    }
+    throw cause;
+  }
+  process.stdout.write(`${JSON.stringify(result)}\n`);
+  if (result.status === 'failed') process.exitCode = 1;
+}
+
+export { taskOverride };

package/lib/internal/task-review.ts

@@ -1,6 +1,9 @@
 import { finalizeReviewSummary } from '../task/review-finalization.ts';
+import { consumeHumanOverride, failureId, overrideDryRunConflict } from '../task/human-override.ts';
+import { resolveTaskRef } from '../task/resolve-ref.ts';
+import { TaskExecutionLockError, withTaskExecutionLock } from '../task/task-execution-lock.ts';
 
-const USAGE = 'Usage: agent-infra-internal task-review <task-ref> finalize-summary --stage <analysis|plan|code> --artifact <review-*.md> [--orchestrated] [--dry-run]\n';
+const USAGE = 'Usage: agent-infra-internal task-review <task-ref> finalize-summary --stage <analysis|plan|code> --artifact <review-*.md> [--orchestrated] [--dry-run] [--override-ticket <ticket> --override-target <target> --override-scope <scope>]\n';
 
 function failUsage(message: string): void {
   process.stdout.write(`${JSON.stringify({
@@ -30,10 +33,13 @@ function taskReview(args: string[] = []): void {
   let artifact = '';
   let dryRun = false;
   let orchestrated = false;
+  let overrideTicket = '';
+  let overrideTarget = '';
+  let overrideScope = '';
   const seen = new Set<string>();
   for (let index = 2; index < args.length; index += 1) {
     const flag = args[index]!;
-    if (!['--stage', '--artifact', '--orchestrated', '--dry-run'].includes(flag)) {
+    if (!['--stage', '--artifact', '--orchestrated', '--dry-run', '--override-ticket', '--override-target', '--override-scope'].includes(flag)) {
       failUsage(`unknown option '${flag}'`);
       return;
     }
@@ -56,15 +62,54 @@ function taskReview(args: string[] = []): void {
       return;
     }
     if (flag === '--stage') stage = value;
-    else artifact = value;
+    else if (flag === '--artifact') artifact = value;
+    else if (flag === '--override-ticket') overrideTicket = value;
+    else if (flag === '--override-target') overrideTarget = value;
+    else if (flag === '--override-scope') overrideScope = value;
   }
   if (!stage || !artifact) {
     failUsage("options '--stage' and '--artifact' are required");
     return;
   }
-  const result = finalizeReviewSummary({ taskRef: args[0]!, stage, artifact, orchestrated, dryRun });
-  process.stdout.write(`${JSON.stringify(result)}\n`);
-  if (result.status === 'failed') process.exitCode = 1;
+  const dryRunConflict = overrideDryRunConflict({ dryRun, overrideTicket, overrideTarget, overrideScope });
+  if (dryRunConflict) { failUsage(dryRunConflict.message); return; }
+  const resolved = resolveTaskRef(args[0]!);
+  if (!resolved.ok) { failUsage(resolved.message); return; }
+  let result;
+  let humanOverride: unknown = null;
+  try {
+    result = withTaskExecutionLock(resolved.repoRoot, resolved.taskId, 'task-review.finalize-summary', () => {
+      let current = finalizeReviewSummary({ taskRef: args[0]!, stage, artifact, orchestrated, dryRun }, { lockAlreadyHeld: true });
+      if (current.status !== 'failed' || !overrideTicket) return current;
+      if (!overrideTarget || !overrideScope) { failUsage('override ticket requires target and scope'); return current; }
+      const consumed = consumeHumanOverride({
+        taskRef: args[0]!, ticketId: overrideTicket,
+        failureId: failureId('review-finalization', current.error?.code ?? 'TASK_STATE_MISMATCH'),
+        target: overrideTarget, scope: overrideScope
+      }, {
+        effectExecutor: (capability) => {
+          const retried = finalizeReviewSummary({ taskRef: args[0]!, stage, artifact, orchestrated, dryRun }, { lockAlreadyHeld: true, manualOverride: capability });
+          current = retried;
+          return retried.status === 'failed' || retried.status === 'planned'
+            ? { code: 'OVERRIDE_EFFECT_FAILED', message: retried.status === 'planned' ? 'producer returned planned; no review effect was committed' : `${retried.error?.code ?? 'REVIEW_FAILED'}: ${retried.error?.message ?? 'manual review effect failed'}` }
+            : null;
+        }
+      });
+      humanOverride = consumed;
+      return current;
+    });
+  } catch (error) {
+    if (!(error instanceof TaskExecutionLockError)) throw error;
+    process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, error: { code: error.code, message: error.message } })}\n`);
+    process.exitCode = 1;
+    return;
+  }
+  process.stdout.write(`${JSON.stringify(humanOverride ? { ...result, humanOverride } : result)}\n`);
+  const overrideFailed = Boolean(
+    humanOverride && typeof humanOverride === 'object' &&
+    (humanOverride as { status?: unknown }).status === 'failed'
+  );
+  if (result.status === 'failed' || overrideFailed) process.exitCode = 1;
 }
 
 export { taskReview };

package/lib/internal/task-verify.ts

@@ -1,6 +1,9 @@
 import { renderTaskVerification, verifyTaskEvent } from '../task/verification.ts';
+import { consumeHumanOverride, failureId } from '../task/human-override.ts';
+import { resolveTaskRef } from '../task/resolve-ref.ts';
+import { TaskExecutionLockError, withTaskExecutionLock } from '../task/task-execution-lock.ts';
 
-const USAGE = 'Usage: agent-infra-internal task-verify <N | TASK-id> <verification-event> [--artifact <canonical.md>] [--format json|text]\n';
+const USAGE = 'Usage: agent-infra-internal task-verify <N | TASK-id> <verification-event> [--artifact <canonical.md>] [--format json|text] [--override-ticket <ticket> --override-target <target> --override-scope <scope>]\n';
 
 function fail(message: string): void {
   process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, error: { code: 'VERIFY_PAYLOAD_INVALID', message } })}\n`);
@@ -11,21 +14,67 @@ function fail(message: string): void {
 function taskVerify(args: string[] = []): void {
   if (args[0] === '--help' || args[0] === '-h') { process.stdout.write(USAGE); return; }
   if (!args[0] || !args[1] || args[0].startsWith('--') || args[1].startsWith('--')) { fail('task ref and verification event are required'); return; }
+  const taskRef = args[0];
+  const event = args[1];
   let artifact: string | undefined;
   let format: 'json' | 'text' = 'json';
+  let overrideTicket: string | undefined;
+  let overrideTarget: string | undefined;
+  let overrideScope: string | undefined;
   const seen = new Set<string>();
   for (let index = 2; index < args.length; index += 1) {
     const flag = args[index]!;
-    if (flag !== '--artifact' && flag !== '--format') { fail(`unknown option '${flag}'`); return; }
+    if (!['--artifact', '--format', '--override-ticket', '--override-target', '--override-scope'].includes(flag)) { fail(`unknown option '${flag}'`); return; }
     if (seen.has(flag)) { fail(`duplicate option '${flag}'`); return; }
     const value = args[++index];
     if (!value || value.startsWith('--')) { fail(`option '${flag}' requires a value`); return; }
     seen.add(flag);
     if (flag === '--artifact') artifact = value;
+    else if (flag === '--override-ticket') overrideTicket = value;
+    else if (flag === '--override-target') overrideTarget = value;
+    else if (flag === '--override-scope') overrideScope = value;
     else if (value === 'json' || value === 'text') format = value;
     else { fail("option '--format' requires 'json' or 'text'"); return; }
   }
-  const result = verifyTaskEvent({ taskRef: args[0], event: args[1], ...(artifact ? { artifact } : {}) });
+  const resolved = resolveTaskRef(taskRef);
+  if (!resolved.ok) { fail(resolved.message); return; }
+  let result;
+  let humanOverride: unknown = null;
+  try {
+    result = withTaskExecutionLock(resolved.repoRoot, resolved.taskId, `task-verify.${event}`, () => {
+      let current = verifyTaskEvent({ taskRef, event, ...(artifact ? { artifact } : {}) });
+      if (current.status === 'pass' || !overrideTicket) return current;
+      if (!overrideTarget || !overrideScope) { fail('override ticket requires target and scope'); return current; }
+      const failureProducer = current.status === 'blocked' || current.status === 'fail'
+        ? 'verification-engine'
+        : 'task-verify';
+      const failureCode = current.status === 'blocked'
+        ? 'CHECK_BLOCKED'
+        : current.status === 'fail'
+          ? 'CHECK_FAILED'
+          : current.error?.code ?? 'VERIFY_TASK_STATE_MISMATCH';
+      const consumed = consumeHumanOverride({
+        taskRef, ticketId: overrideTicket,
+        failureId: failureId(failureProducer, failureCode),
+        target: overrideTarget, scope: overrideScope
+      }, {
+        effectExecutor: (capability) => {
+          const retried = verifyTaskEvent({ taskRef, event, ...(artifact ? { artifact } : {}) }, { manualOverride: capability });
+          current = retried;
+          return retried.status !== 'pass'
+            ? { code: 'OVERRIDE_EFFECT_FAILED', message: `${retried.error?.code ?? 'VERIFY_FAILED'}: ${retried.error?.message ?? 'manual verification effect failed'}` }
+            : null;
+        }
+      });
+      humanOverride = consumed;
+      return current;
+    });
+  } catch (error) {
+    if (!(error instanceof TaskExecutionLockError)) throw error;
+    fail(`${error.code}: ${error.message}`);
+    return;
+  }
+  if (humanOverride) result = { ...result, humanOverride } as typeof result;
   process.stdout.write(format === 'text' ? renderTaskVerification(result) : `${JSON.stringify(result)}\n`);
   process.exitCode = result.status === 'pass' ? 0 : result.status === 'blocked' ? 2 : 1;
 }

package/lib/internal/task-warning.ts

@@ -1,10 +1,14 @@
 import { applyWorkflowWarningIntent } from '../task/workflow-warning-intents.ts';
 import type { WorkflowWarningIntent } from '../task/workflow-warning-intents.ts';
+import { consumeHumanOverride, failureId, overrideDryRunConflict } from '../task/human-override.ts';
+import { resolveTaskRef } from '../task/resolve-ref.ts';
+import { TaskExecutionLockError, withTaskExecutionLock } from '../task/task-execution-lock.ts';
 
 const USAGE = `Usage: agent-infra-internal task-warning <task-ref> <add|set-status|list> [intent flags] [--dry-run]\n`;
 const FLAGS: Record<string, string> = {
   '--step': 'step', '--severity': 'severity', '--code': 'code', '--target': 'target',
   '--message': 'message', '--action': 'action', '--id': 'id', '--status': 'status', '--resolution': 'resolution'
+  , '--override-ticket': 'overrideTicket', '--override-target': 'overrideTarget', '--override-scope': 'overrideScope'
 };
 
 function usageFailure(message: string): void {
@@ -38,13 +42,50 @@ function taskWarning(args: string[] = []): void {
   };
   const optional = kind === 'list' ? ['status'] : [];
   const allowed = new Set(['kind', 'taskRef', 'dryRun', ...required[kind]!, ...optional]);
+  allowed.add('overrideTicket'); allowed.add('overrideTarget'); allowed.add('overrideScope');
   const unexpected = Object.keys(values).find((key) => !allowed.has(key));
   const missing = required[kind]!.find((key) => values[key] === undefined);
   if (unexpected) { usageFailure(`${kind} does not accept '${unexpected}'`); return; }
   if (missing) { usageFailure(`${kind} requires '${missing}'`); return; }
-  const result = applyWorkflowWarningIntent(values as WorkflowWarningIntent);
-  process.stdout.write(`${JSON.stringify(result)}\n`);
-  if (result.status === 'failed') process.exitCode = 1;
+  const dryRunConflict = overrideDryRunConflict(values);
+  if (dryRunConflict) { usageFailure(dryRunConflict.message); return; }
+  const resolved = resolveTaskRef(taskRef);
+  if (!resolved.ok) { usageFailure(resolved.message); return; }
+  let result;
+  let humanOverride: unknown = null;
+  try {
+    result = withTaskExecutionLock(resolved.repoRoot, resolved.taskId, `task-warning.${kind}`, () => {
+      let current = applyWorkflowWarningIntent(values as WorkflowWarningIntent);
+      if (current.status !== 'failed' || !values.overrideTicket) return current;
+      if (!values.overrideTarget || !values.overrideScope) { usageFailure('override ticket requires target and scope'); return current; }
+      const consumed = consumeHumanOverride({
+        taskRef, ticketId: String(values.overrideTicket),
+        failureId: failureId('workflow-warning', current.error?.code ?? 'TASK_STATE_MISMATCH'),
+        target: String(values.overrideTarget), scope: String(values.overrideScope)
+      }, {
+        effectExecutor: (capability) => {
+          const retried = applyWorkflowWarningIntent(values as WorkflowWarningIntent, { manualOverride: capability });
+          current = retried;
+          return retried.status === 'failed' || retried.status === 'planned'
+            ? { code: 'OVERRIDE_EFFECT_FAILED', message: retried.status === 'planned' ? 'producer returned planned; no workflow warning effect was committed' : `${retried.error?.code ?? 'WARNING_FAILED'}: ${retried.error?.message ?? 'manual warning effect failed'}` }
+            : null;
+        }
+      });
+      humanOverride = consumed;
+      return current;
+    });
+  } catch (error) {
+    if (!(error instanceof TaskExecutionLockError)) throw error;
+    process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, error: { code: error.code, message: error.message } })}\n`);
+    process.exitCode = 1;
+    return;
+  }
+  process.stdout.write(`${JSON.stringify(humanOverride ? { ...result, humanOverride } : result)}\n`);
+  const overrideFailed = Boolean(
+    humanOverride && typeof humanOverride === 'object' &&
+    (humanOverride as { status?: unknown }).status === 'failed'
+  );
+  if (result.status === 'failed' || overrideFailed) process.exitCode = 1;
 }
 
 export { taskWarning };

package/lib/platform/pr-summary.ts

@@ -3,6 +3,7 @@ import { execFileSync } from 'node:child_process';
 
 import { enumerateArtifacts } from '../task/artifacts.ts';
 import { parseTaskFrontmatter } from '../task/frontmatter.ts';
+import { renderHumanOverrideAudit } from '../task/human-override.ts';
 import { resolveTaskRef } from '../task/resolve-ref.ts';
 import { resolvePlatformContext } from './context.ts';
 import { createGitHubClient } from './github-client.ts';
@@ -21,8 +22,9 @@ function summaryMarker(taskId: string): string {
   return `<!-- sync-pr:${taskId}:summary -->`;
 }
 
-function buildPullRequestSummary(taskId: string, body: string, headSha: string): string {
-  return normalizeCommentContent(`${summaryMarker(taskId)}\n<!-- last-commit: ${headSha} -->\n\n${body.replace(/\s+$/, '')}\n`);
+function buildPullRequestSummary(taskId: string, body: string, headSha: string, humanOverrideAudit = ''): string {
+  const sections = [body.replace(/\s+$/, ''), humanOverrideAudit.trim()].filter(Boolean).join('\n\n');
+  return normalizeCommentContent(`${summaryMarker(taskId)}\n<!-- last-commit: ${headSha} -->\n\n${sections}\n`);
 }
 
 function reconcileSummaryComment(comments: SummaryComment[], taskId: string, desired: string):
@@ -74,7 +76,12 @@ function syncPullRequestSummary(taskRef: string, options: { agent: string; body:
   } catch (error) {
     return platformResult('failed', { platform: context.platform, capabilities: context.capabilities, error: { code: 'GIT_HEAD_UNRESOLVED', message: error instanceof Error ? error.message : String(error), retryable: false } });
   }
-  const desired = buildPullRequestSummary(resolved.taskId, options.body, headSha);
+  const desired = buildPullRequestSummary(
+    resolved.taskId,
+    options.body,
+    headSha,
+    renderHumanOverrideAudit(fs.readFileSync(resolved.taskMdPath, 'utf8'))
+  );
   const listed = listRemoteComments(client, context.platform.repository, prNumber, resolved.repoRoot);
   if (!listed.ok) return platformResult(listed.error.retryable ? 'blocked' : 'failed', { platform: context.platform, capabilities: context.capabilities, resource: { kind: 'pull-request', number: prNumber }, error: listed.error });
   const reconciliation = reconcileSummaryComment(listed.value, resolved.taskId, desired);

package/lib/runtime/agent-runtime.ts

@@ -0,0 +1,76 @@
+import path from 'node:path';
+
+export type AgentRuntimeStore = 'capabilities' | 'lifecycle';
+
+type RuntimeResolutionOptions = Readonly<{
+  repoRoot?: string;
+  env?: NodeJS.ProcessEnv;
+  explicitRoot?: string;
+  client?: string;
+  store?: AgentRuntimeStore;
+}>;
+
+const CLIENT_NAMESPACE = /^[a-z][a-z0-9-]{0,31}$/u;
+
+function runtimeError(code: string, message: string): Error {
+  const error = new Error(`${code}: ${message}`);
+  error.name = code;
+  return error;
+}
+
+function boundControlContext(env: NodeJS.ProcessEnv): boolean {
+  return [
+    'AGENT_INFRA_CONTROL_TOKEN',
+    'AGENT_INFRA_CONTROL_GENERATION',
+    'AGENT_INFRA_EXECUTOR_MANIFEST',
+    'AGENT_INFRA_CODEX_CONTROLLER_CONTEXT'
+  ].some((key) => typeof env[key] === 'string' && env[key]!.length > 0);
+}
+
+function clientNamespace(client: string): string {
+  if (!CLIENT_NAMESPACE.test(client)) {
+    throw runtimeError('AGENT_INFRA_RUNTIME_CLIENT_INVALID', `invalid runtime client namespace '${client}'`);
+  }
+  return client;
+}
+
+export function resolveAgentRuntimeRoot(options: Readonly<{
+  repoRoot?: string;
+  env?: NodeJS.ProcessEnv;
+}> = {}): string {
+  const env = options.env ?? process.env;
+  const configured = env.AGENT_INFRA_RUNTIME_DIR;
+  if (configured !== undefined && configured.length > 0) {
+    if (!path.isAbsolute(configured)) {
+      throw runtimeError('AGENT_INFRA_RUNTIME_DIR_INVALID', 'runtime directory must be absolute');
+    }
+    return path.resolve(configured);
+  }
+  if (boundControlContext(env)) {
+    throw runtimeError(
+      'AGENT_INFRA_RUNTIME_DIR_REQUIRED',
+      'task-bound control context requires AGENT_INFRA_RUNTIME_DIR'
+    );
+  }
+  return path.join(path.resolve(options.repoRoot ?? process.cwd()), '.agents', 'workspace', '.runtime');
+}
+
+export function resolveAgentRuntimeStoreRoot(options: RuntimeResolutionOptions = {}): string {
+  const client = clientNamespace(options.client ?? 'codex');
+  if (options.explicitRoot) return path.resolve(options.explicitRoot);
+  const env = options.env ?? process.env;
+  const runtimeRoot = resolveAgentRuntimeRoot({ repoRoot: options.repoRoot, env });
+  if (env.AGENT_INFRA_RUNTIME_DIR) {
+    if (!options.store) {
+      throw runtimeError('AGENT_INFRA_RUNTIME_STORE_INVALID', 'store kind is required for task-bound runtime');
+    }
+    return path.join(runtimeRoot, 'clients', client, options.store);
+  }
+  if (client === 'codex' && options.store) {
+    return path.join(runtimeRoot, `codex-${options.store}`);
+  }
+  if (!options.store) {
+    throw runtimeError('AGENT_INFRA_RUNTIME_STORE_INVALID', 'store kind is required');
+  }
+  return path.join(runtimeRoot, 'clients', client, options.store);
+}

package/lib/sandbox/commands/create.ts

@@ -69,6 +69,17 @@ import {
   prepareTmpfsMounts,
   startSandboxControlBroker
 } from '../recovery.ts';
+import {
+  acquireSandboxControlReplacement,
+  assertSandboxControlCutoverSnapshot,
+  beginSandboxControlReplacement,
+  captureSandboxControlCutoverSnapshot,
+  commitSandboxControlReplacement,
+  quiesceSandboxControlRoot,
+  recoverSandboxControlReplacement,
+  readSandboxControlManifestForTransition
+} from '../control/lifecycle.ts';
+import { inspectSandboxControlContainer } from '../control/container-identity.ts';
 import { hostJoin, toEnginePath, volumeArg } from '../engines/wsl2-paths.ts';
 import { sandboxCoreBindMounts } from '../mounts.ts';
 import {
@@ -76,7 +87,8 @@ import {
   finalizeSandboxControlManifest,
   materializeSandboxControl,
   materializeSandboxWorkspaceView,
-  prepareSandboxWorkspaceMountTarget,
+  prepareSandboxWorkspaceMountTargets,
+  sandboxControlPaths,
 } from '../workspace-view.ts';
 import { clipboardHostDir, CONTAINER_CLIPBOARD_MOUNT } from '../clipboard/paths.ts';
 import { validateSelinuxDisableEnv } from '../engines/selinux.ts';
@@ -1036,6 +1048,12 @@ export async function create(args: string[]): Promise<void> {
   }
   const effectiveResolvedTools = resolvedTools;
   const container = containerName(effectiveConfig, branch);
+  const controlPaths = sandboxControlPaths({
+    base: effectiveConfig.controlBase,
+    project: effectiveConfig.project,
+    container,
+    identity: target.workspace
+  });
   const worktree = worktreeCandidates.find((candidate) => fs.existsSync(candidate)) ?? worktreeCandidates[0] ?? '';
   const shareCommon = shareCommonDir(effectiveConfig);
   const shareBranch = shareBranchDir(effectiveConfig, branch);
@@ -1224,6 +1242,22 @@ export async function create(args: string[]): Promise<void> {
       {
         title: `Starting container '${container}'`,
         task: async (message: (text: string) => void) => {
+          const hadControlRootBeforeAcquire = fs.existsSync(controlPaths.root);
+          const replacementLease = acquireSandboxControlReplacement(controlPaths.root);
+          let replacementLeaseHeld = true;
+          let replacementCutover: ReturnType<typeof beginSandboxControlReplacement> | null = null;
+          try {
+            const recoveryResult = await recoverSandboxControlReplacement(controlPaths.root, replacementLease);
+            const hadExistingControlRoot = hadControlRootBeforeAcquire || recoveryResult === 'restored';
+            const previousManifest = fs.existsSync(controlPaths.manifestPath)
+              ? readSandboxControlManifestForTransition(controlPaths.manifestPath)
+              : null;
+            if (hadExistingControlRoot) {
+              await quiesceSandboxControlRoot(controlPaths.root);
+            }
+            const previousCutoverSnapshot = hadExistingControlRoot
+              ? captureSandboxControlCutoverSnapshot(controlPaths.root)
+              : null;
           const existing = runSafeEngine(engine, 'docker', ['ps', '-a', '--format', '{{.Names}}']).split('\n').filter(Boolean);
           const matchedContainers = containerNameCandidates(effectiveConfig, branch)
             .filter((name) => existing.includes(name));
@@ -1266,6 +1300,14 @@ export async function create(args: string[]): Promise<void> {
               runSafeEngine(engine, 'docker', ['rm', name]);
             }
           }
+          if (previousManifest) {
+            const oldContainer = await inspectSandboxControlContainer(previousManifest);
+            if (oldContainer.state !== 'absent') {
+              throw new Error(oldContainer.state === 'unknown'
+                ? `SANDBOX_CONTROL_CONTAINER_UNKNOWN: ${oldContainer.reason}`
+                : 'SANDBOX_CONTROL_CONTAINER_STILL_EXISTS');
+            }
+          }
 
           const aliasesFile = ensureSandboxAliasesFile(
             effectiveConfig.home,
@@ -1342,7 +1384,19 @@ export async function create(args: string[]): Promise<void> {
               container,
               identity: target.workspace
             });
-            prepareSandboxWorkspaceMountTarget(worktree);
+            prepareSandboxWorkspaceMountTargets(worktree);
+            if (previousCutoverSnapshot) {
+              assertSandboxControlCutoverSnapshot(previousCutoverSnapshot);
+              if (previousManifest) {
+                const finalOldContainer = await inspectSandboxControlContainer(previousManifest);
+                if (finalOldContainer.state !== 'absent') {
+                  throw new Error(finalOldContainer.state === 'unknown'
+                    ? `SANDBOX_CONTROL_CONTAINER_UNKNOWN: ${finalOldContainer.reason}`
+                    : 'SANDBOX_CONTROL_CONTAINER_REAPPEARED');
+                }
+              }
+              replacementCutover = beginSandboxControlReplacement(controlPaths.root, replacementLease);
+            }
             const control = materializeSandboxControl({
               base: effectiveConfig.controlBase,
               repoRoot: effectiveConfig.repoRoot,
@@ -1351,7 +1405,8 @@ export async function create(args: string[]): Promise<void> {
               container,
               branch,
               identity: target.workspace,
-              engine
+              engine,
+              replacementLease
             });
             hostShellConfig = prepareHostShellConfig({
               home: effectiveConfig.home,
@@ -1365,6 +1420,7 @@ export async function create(args: string[]): Promise<void> {
               workspaceViewRoot: workspaceView.root,
               controlDir: control.channelDir,
               controlStatusDir: control.statusDir,
+              ...(target.workspace.mode === 'task-bound' ? { runtimeDir: control.runtimeDir } : {}),
               ...(target.workspace.mode === 'task-bound'
                 ? {
                   taskSource: assertSandboxTaskSource(
@@ -1456,6 +1512,9 @@ export async function create(args: string[]): Promise<void> {
               'AGENT_INFRA_CONTROL_DIR=/run/agent-infra/control',
               '-e',
               'AGENT_INFRA_CONTROL_STATUS_DIR=/run/agent-infra/control-status',
+              ...(target.workspace.mode === 'task-bound'
+                ? ['-e', 'AGENT_INFRA_RUNTIME_DIR=/run/agent-infra/runtime']
+                : []),
               '--label',
               `${sandboxRuntimeCapabilityLabel(effectiveConfig)}=${capabilityPlan.runtimeSignature}`,
               ...coreVolumes,
@@ -1512,14 +1571,27 @@ export async function create(args: string[]): Promise<void> {
                 id: containerId,
                 labels: expectedLabels
               });
+              replacementLease.clearQuiescing();
               await startSandboxControlBroker(effectiveConfig.repoRoot, control.manifestPath);
+              if (replacementCutover) {
+                commitSandboxControlReplacement(control.root, replacementLease);
+                replacementCutover = null;
+              }
               createdTmpfsSeedPlan = tmpfsSeedPlan;
             } catch (error) {
               if (createdContainerRef) {
                 runSafeEngine(engine, 'docker', ['stop', createdContainerRef]);
                 runSafeEngine(engine, 'docker', ['rm', createdContainerRef]);
               }
-              removeDirRecursive(control.root);
+              if (!hadExistingControlRoot) removeDirRecursive(control.root);
+              if (replacementCutover) {
+                try {
+                  await recoverSandboxControlReplacement(control.root, replacementLease);
+                  replacementCutover = null;
+                } catch {
+                  // Preserve the cutover state for the next explicit recreate to recover.
+                }
+              }
               removeDirRecursive(workspaceView.root);
               throw error;
             }
@@ -1615,7 +1687,19 @@ export async function create(args: string[]): Promise<void> {
             );
           }
 
+          replacementLease.release();
+          replacementLeaseHeld = false;
           return 'Container started';
+          } catch (error) {
+            if (replacementLeaseHeld) {
+              try {
+                replacementLease.release();
+              } catch {
+                // Preserve the original cutover failure and its evidence.
+              }
+            }
+            throw error;
+          }
         }
       }
     ]);