@fitlab-ai/agent-infra 0.11.12 → 0.11.14

package/lib/internal/sandbox-control.ts

@@ -1,33 +1,12 @@
 import {
   recoverSandboxControl,
   requestSandboxControl,
-  requestSandboxTaskFinalization,
   SandboxControlClientError
 } from '../sandbox/control/client.ts';
-import { normalizeAgentToken, AGENT_USAGE_HINT } from '../agent-clients/tokens.ts';
 import { serveSandboxControl } from '../sandbox/control/server.ts';
 import { runSandboxControlExecutor } from '../sandbox/control/executor.ts';
 import { ensureInternalHandlerRoute, internalHandlerRoute } from './cli-route-inventory.ts';
 import { parseTaskCreateResult, taskCreateExitCode } from '../task/create-service.ts';
-import { serializeTaskFinalizationEnvelope, type TaskFinalizationEnvelope } from '../task/finalization-envelope.ts';
-
-type FinalizationStatus = 'completed' | 'failed' | 'blocked' | 'unknown';
-
-function writeFinalizationEnvelope(
-  status: FinalizationStatus,
-  accepted: boolean,
-  error: { code: string; message: string; retryable: boolean },
-  changed: boolean | null = false,
-  result: unknown = null,
-  requestId: string | null = null
-): void {
-  process.stdout.write(serializeTaskFinalizationEnvelope({ status, changed, accepted, requestId, result, error }));
-}
-
-function finalizationErrorStatus(error: { retryable: boolean; code: string }): FinalizationStatus {
-  if (error.code === 'SANDBOX_CONTROL_RESULT_UNKNOWN') return 'unknown';
-  return error.retryable ? 'blocked' : 'failed';
-}
 
 function writeClientError(error: SandboxControlClientError): void {
   process.stderr.write(`${error.detail.message}\n`);
@@ -45,78 +24,6 @@ function recoveredExitCode(response: Awaited<ReturnType<typeof recoverSandboxCon
   return response.exitCode ?? 1;
 }
 
-function finalizationResponseOutput(response: Awaited<ReturnType<typeof requestSandboxTaskFinalization>>): string {
-  try {
-    const value = JSON.parse(response.stdout) as Partial<TaskFinalizationEnvelope>;
-    if (value.version === 2
-      && value.status
-      && ['completed', 'failed', 'blocked', 'unknown'].includes(value.status)
-      && (typeof value.changed === 'boolean' || value.changed === null)) {
-      return serializeTaskFinalizationEnvelope({
-        status: value.status,
-        changed: value.changed,
-        accepted: true,
-        requestId: response.id,
-        result: value.result ?? null,
-        error: value.error ?? null
-      });
-    }
-  } catch {
-    // Preserve non-envelope output for diagnostics from the executor.
-  }
-  return response.stdout;
-}
-
-function sandboxFinalizationClient(args: string[]): void {
-  if (args.length !== 4 || !args[0] || args[1] !== 'complete' || args[2] !== '--agent' || !args[3]) {
-    const error = { code: 'TASK_FINALIZATION_PAYLOAD_INVALID', message: 'task ref, complete intent, and --agent are required', retryable: false };
-    writeFinalizationEnvelope('failed', false, error);
-    process.stderr.write('Usage: agent-infra-internal task-finalization <N | TASK-id> complete --agent <agent>\n');
-    process.exitCode = 1;
-    return;
-  }
-  const agent = normalizeAgentToken(args[3]);
-  if (!agent) {
-    const error = { code: 'TASK_FINALIZATION_PAYLOAD_INVALID', message: `invalid --agent: ${AGENT_USAGE_HINT}`, retryable: false };
-    writeFinalizationEnvelope('failed', false, error);
-    process.exitCode = 1;
-    return;
-  }
-  let response;
-  try {
-    response = requestSandboxTaskFinalization({ agent });
-  } catch (error) {
-    if (!(error instanceof SandboxControlClientError)) throw error;
-    const status = finalizationErrorStatus(error.detail);
-    writeFinalizationEnvelope(status, error.accepted, error.detail, status === 'unknown' ? null : false, null, error.requestId);
-    writeClientError(error);
-    process.exitCode = error.detail.code === 'SANDBOX_CONTROL_RESULT_UNKNOWN' ? 1 : error.detail.retryable ? 2 : 1;
-    return;
-  }
-  if (response.phase === 'rejected') {
-    const error = response.error ?? {
-      code: 'SANDBOX_CONTROL_REJECTED',
-      message: 'sandbox control rejected the finalization request',
-      retryable: false
-    };
-    const status = finalizationErrorStatus(error);
-    writeFinalizationEnvelope(
-      status,
-      error.code === 'SANDBOX_CONTROL_RESULT_UNKNOWN',
-      error,
-      status === 'unknown' ? null : false,
-      null,
-      response.id
-    );
-    process.stderr.write(`${error.message}\n`);
-    process.exitCode = error.code === 'SANDBOX_CONTROL_RESULT_UNKNOWN' ? 1 : error.retryable ? 2 : 1;
-    return;
-  }
-  process.stdout.write(finalizationResponseOutput(response));
-  process.stderr.write(response.stderr);
-  process.exitCode = response.exitCode ?? 1;
-}
-
 async function sandboxControl(args: string[]): Promise<void> {
   if (!ensureInternalHandlerRoute('sandbox-control', args)) return;
   const [operation, ...rest] = args;
@@ -165,10 +72,6 @@ async function sandboxControl(args: string[]): Promise<void> {
   }
   if (internalHandlerRoute('sandbox-control', 'client', operation ?? '')) {
     const [family = '', ...commandArgs] = rest;
-    if (family === 'task-finalization') {
-      sandboxFinalizationClient(commandArgs);
-      return;
-    }
     let response;
     try {
       response = requestSandboxControl({ family, args: commandArgs });

package/lib/internal/task-finalization.ts

@@ -1,3 +1,4 @@
+import path from 'node:path';
 import {
   createDirectHostExecutionContext,
   dispatchTaskControlOperation,
@@ -6,8 +7,10 @@ import {
 import { applyTaskFinalization } from '../task/finalization.ts';
 import { detectRepoRoot, resolveTaskRef } from '../task/resolve-ref.ts';
 import { resolveSandboxControlTransport } from './task-operation-registry.ts';
-import { requestSandboxTaskFinalization, SandboxControlClientError } from '../sandbox/control/client.ts';
+import { quiesceSandboxControlForTaskCompletion } from '../sandbox/control/lifecycle.ts';
+import { loadSandboxControlLocation } from '../sandbox/config.ts';
 import { serializeTaskFinalizationEnvelope } from '../task/finalization-envelope.ts';
+import { verifyTaskEvent } from '../task/verification.ts';
 import { ensureInternalHandlerRoute, internalHandlerRoute } from './cli-route-inventory.ts';
 
 const USAGE = 'Usage: agent-infra-internal task-finalization <N | TASK-id> complete --agent <agent>\n';
@@ -79,28 +82,39 @@ async function taskFinalization(args: string[] = []): Promise<void> {
   };
   const transport = resolveSandboxControlTransport(process.env, { localWorkflow: true });
   if (transport.kind === 'sandbox-local') {
-    try {
-      const response = requestSandboxTaskFinalization({ agent: boundOperation.request.agent });
-      process.stdout.write(response.stdout);
-      process.stderr.write(response.stderr);
-      process.exitCode = response.exitCode ?? 1;
-      return;
-    } catch (error) {
-      const clientError = error instanceof SandboxControlClientError ? error : null;
-      const detail = clientError
-        ? clientError.detail
-        : { code: 'SANDBOX_CONTROL_CLIENT_FAILED', message: error instanceof Error ? error.message : String(error), retryable: false };
-      const status = detail.code === 'SANDBOX_CONTROL_RESULT_UNKNOWN'
-        ? 'unknown'
-        : detail.retryable ? 'blocked' : 'failed';
-      const changed = status === 'unknown' ? null : false;
-      process.stdout.write(envelope(status, changed, clientError?.accepted ?? false, null, detail, clientError?.requestId ?? null));
-      process.exitCode = exitCode(status);
+    const statusDir = process.env.AGENT_INFRA_CONTROL_STATUS_DIR;
+    const taskId = process.env.AGENT_INFRA_TASK_ID;
+    const generation = process.env.AGENT_INFRA_CONTROL_GENERATION;
+    const controlRootId = process.env.AGENT_INFRA_CONTROL_ROOT_ID;
+    const controlRoot = process.env.AGENT_INFRA_CONTROL_ROOT_DIR;
+    if (!statusDir || !taskId || !generation || !controlRootId || !controlRoot || taskId !== resolved.taskId) {
+      const detail = { code: 'TASK_CONTROL_TRANSPORT_INVALID', message: 'sandbox task control identity is incomplete', retryable: false };
+      process.stdout.write(envelope('failed', false, true, null, detail));
+      process.exitCode = 1;
       return;
     }
+    const result = await applyTaskFinalization(boundOperation.request, {
+      repoRoot,
+      beforeLifecycle: async (currentTaskId) => {
+        if (currentTaskId !== taskId) throw new Error('SANDBOX_CONTROL_IDENTITY_MISMATCH');
+        await quiesceSandboxControlForTaskCompletion(
+          controlRoot,
+          { taskId, generation, controlRootId, statusDir }
+        );
+      },
+      preflight: (request, options) => verifyTaskEvent(
+        { ...request, event: 'complete-task.hard-preflight' }, options
+      )
+    });
+    const status = result.status === 'prepared' ? 'failed' : result.status;
+    process.stdout.write(envelope(status, result.changed, true, result, result.error
+      ?? (result.status === 'prepared' ? { code: 'TASK_FINALIZATION_PREPARATION_INCOMPLETE', message: 'finalization did not commit', retryable: true } : null)));
+    process.exitCode = exitCode(status);
+    return;
   }
+  const controlLocation = loadSandboxControlLocation(repoRoot);
   const result = await dispatchTaskControlOperation(
-    createDirectHostExecutionContext({ repoRoot }),
+    createDirectHostExecutionContext({ repoRoot, ...(controlLocation ?? {}) }),
     boundOperation
   );
   if (result.status === 'prepared') {

package/lib/internal/task-lifecycle.ts

@@ -9,8 +9,9 @@ import { detectRepoRoot, resolveTaskRef } from '../task/resolve-ref.ts';
 import type { TaskLifecycleResult } from '../task/lifecycle.ts';
 import type { AgentClientLifecycleRecoveryResult as LifecycleRecoveryResult } from '../agent-clients/adapter.ts';
 import { ensureInternalHandlerRoute, internalHandlerRoute } from './cli-route-inventory.ts';
+import { loadSandboxControlLocation } from '../sandbox/config.ts';
 
-const USAGE = `Usage: agent-infra-internal task-lifecycle <N | TASK-id> <intent> --agent <agent> [intent flags] [--dry-run]\n\nIntents: ${lifecycleIntentCatalog.join(', ')}\nrecover-started: --auto\n`;
+const USAGE = `Usage: agent-infra-internal task-lifecycle <N | TASK-id> <intent> --agent <agent> [intent flags] [--dry-run]\n\nIntents: ${lifecycleIntentCatalog.filter((intent) => intent !== 'complete').join(', ')}\nrecover-started: --auto\n`;
 
 function usageFailure(message: string): void {
   process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, error: { code: 'LIFECYCLE_PAYLOAD_INVALID', message } })}\n`);
@@ -59,8 +60,9 @@ async function taskLifecycle(args: string[] = []): Promise<void> {
     repoRoot = resolved.repoRoot;
   }
 
+  const controlLocation = loadSandboxControlLocation(repoRoot);
   const result = await dispatchTaskControlOperation(
-    createDirectHostExecutionContext({ repoRoot }),
+    createDirectHostExecutionContext({ repoRoot, ...(controlLocation ?? {}) }),
     operation
   ) as TaskLifecycleResult | LifecycleRecoveryResult;
   process.stdout.write(`${JSON.stringify(result)}\n`);

package/lib/internal/task-operation-registry.ts

@@ -60,8 +60,6 @@ function internalTaskRoutes(): TaskOperationDescriptor[] {
     descriptor('internal', 'codex-lifecycle', 'resolve-start', 'conditional', 'progress'),
     descriptor('internal', 'codex-lifecycle', 'resolve-stop', 'conditional', 'progress'),
     descriptor('internal', 'codex-lifecycle', 'consume', 'conditional', 'progress'),
-    descriptor('internal', 'codex-sandbox-controller', 'verify-context', 'task-bound', 'diagnostic'),
-    descriptor('internal', 'codex-sandbox-controller', 'run', 'task-bound', 'progress'),
     descriptor('internal', 'git-workflow', 'inspect', 'conditional', 'diagnostic'),
     descriptor('internal', 'git-workflow', 'preview-tree', 'conditional', 'diagnostic'),
     descriptor('internal', 'git-workflow', 'snapshot', 'conditional', 'diagnostic'),
@@ -213,7 +211,7 @@ export const TASK_OPERATION_DESCRIPTORS = Object.freeze([
 ]);
 
 export const INTERNAL_DISPATCHER_ROUTES = Object.freeze([
-  'task-create', 'task-qualification', 'sandbox-control', 'agent-client', 'codex-lifecycle', 'codex-sandbox-controller',
+  'task-create', 'task-qualification', 'sandbox-control', 'agent-client', 'codex-lifecycle',
   'git-workflow', 'task-delivery', 'release-workflow', 'platform-release-notes', 'platform-security', 'platform-metadata', 'platform-context',
   'platform-comment', 'platform-issue', 'platform-pr', 'platform-pr-review', 'pr-review-grade',
   'platform-checks', 'task-context', 'task-ledger', 'task-warning', 'task-activity', 'task-artifact',

package/lib/internal/task-validate.ts

@@ -2,27 +2,9 @@ import { execFileSync, spawnSync } from 'node:child_process';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
-import { randomUUID } from 'node:crypto';
 import { loadConfig } from '../sandbox/config.ts';
-import { detectEngine } from '../sandbox/engine.ts';
-import { runEngine } from '../sandbox/shell.ts';
-import { sandboxBranchLabel, sandboxLabel } from '../sandbox/constants.ts';
-import { fetchSandboxRows, selectSandboxContainer } from '../sandbox/commands/list-running.ts';
-import { containerNameCandidates } from '../sandbox/constants.ts';
 import { resolveSandboxTarget } from '../sandbox/workspace-identity.ts';
-import { sandboxControlPaths } from '../sandbox/workspace-view.ts';
-import {
-  appendSandboxControlAudit,
-  readActiveLease,
-  readSandboxControlStatus
-} from '../sandbox/control/state.ts';
-import type { SandboxControlLease } from '../sandbox/control/protocol.ts';
-import { readSandboxControlManifest } from '../sandbox/control/lifecycle.ts';
-import {
-  SANDBOX_CONTROL_FUTURE_SKEW_MS,
-  SANDBOX_CONTROL_STATUS_STALE_MS
-} from '../sandbox/control/protocol.ts';
-import { getProcessStartTime } from '../server/process-state.ts';
+import { resolveBranchWorktree } from '../git/branch-worktree.ts';
 import { assertGitWorktreeBinding } from '../git/worktree-identity.ts';
 import { createManualValidationEvidence, manualValidationEvidenceSummary } from '../task/manual-validation-evidence.ts';
 import type { ManualValidationCleanup } from '../task/manual-validation-evidence.ts';
@@ -31,7 +13,6 @@ import { ensureInternalHandlerRoute, internalHandlerRoute } from './cli-route-in
 
 const USAGE = `Usage: agent-infra-internal task-validate <branch | TASK-id | N> [--scope snapshot|inplace] [--timeout <ms>] [--format text|json] [--evidence-file <path>] -- <command> [args...]`;
 const MAX_TIMEOUT_MS = 60 * 60 * 1000;
-const RECOVERY_GRACE_MS = 30_000;
 
 type ValidateOptions = {
   target: string;
@@ -108,20 +89,6 @@ function git(root: string, args: string[]): string {
   return execFileSync('git', args, { cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim();
 }
 
-function waitForState(statusDir: string, predicate: (state: ReturnType<typeof readSandboxControlStatus>) => boolean, timeoutMs = 5_000): void {
-  const deadline = Date.now() + timeoutMs;
-  while (Date.now() < deadline) {
-    try {
-      const status = readSandboxControlStatus(statusDir);
-      if (predicate(status)) return;
-    } catch {
-      // Atomic status publication may be between renames.
-    }
-    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 25);
-  }
-  throw new Error('SANDBOX_VALIDATION_BROKER_STATE_TIMEOUT');
-}
-
 function snapshotValidation(repoRoot: string, commit: string, options: ValidateOptions) {
   const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-infra-validation-'));
   const worktree = path.join(tempRoot, 'worktree');
@@ -150,109 +117,28 @@ function snapshotValidation(repoRoot: string, commit: string, options: ValidateO
 }
 
 function inplaceValidation(config: ReturnType<typeof loadConfig>, target: ReturnType<typeof resolveSandboxTarget>, options: ValidateOptions) {
-  const engine = detectEngine(config);
-  const { running, nonRunning } = fetchSandboxRows(engine, sandboxLabel(config), sandboxBranchLabel(config));
-  const row = selectSandboxContainer([...running, ...nonRunning], containerNameCandidates(config, target.branch));
-  if (!row) throw new Error('SANDBOX_VALIDATION_CONTAINER_NOT_FOUND');
-  const control = sandboxControlPaths({
-    base: config.controlBase, repoRoot: config.repoRoot, project: config.project,
-    container: row.name, identity: target.workspace
-  });
-  const manifest = readSandboxControlManifest(control.manifestPath);
-  const initial = readSandboxControlStatus(control.statusDir);
-  const now = Date.now();
-  if (initial.generation !== manifest.generation
-    || now - initial.updatedAt > SANDBOX_CONTROL_STATUS_STALE_MS
-    || initial.updatedAt > now + SANDBOX_CONTROL_FUTURE_SKEW_MS) {
-    throw new Error('SANDBOX_VALIDATION_BROKER_STATUS_STALE');
-  }
-  if (initial.state !== 'healthy' || initial.activeRequestId !== null) {
-    throw new Error('SANDBOX_VALIDATION_BROKER_NOT_IDLE');
-  }
-  const startTime = getProcessStartTime(process.pid);
-  if (!startTime) throw new Error('SANDBOX_VALIDATION_OWNER_IDENTITY_UNAVAILABLE');
-  const leasePath = path.join(control.root, 'lease.json');
-  const nonce = randomUUID();
-  const issuedAt = Date.now();
-  const lease: SandboxControlLease = {
-    version: 2, generation: manifest.generation, nonce,
-    owner: { pid: process.pid, startTime }, issuedAt,
-    expiresAt: issuedAt + Math.min(options.timeoutMs + RECOVERY_GRACE_MS, MAX_TIMEOUT_MS + RECOVERY_GRACE_MS),
-    taskId: target.workspace.mode === 'task-bound' ? target.workspace.taskId : null,
-    branch: target.branch, reason: 'manual-validation'
-  };
-  const originalBranch = git(manifest.worktreeRoot, ['symbolic-ref', '--quiet', '--short', 'HEAD']);
-  const originalHead = git(manifest.worktreeRoot, ['rev-parse', 'HEAD']);
-  fs.writeFileSync(leasePath, `${JSON.stringify(lease)}\n`, { flag: 'wx', mode: 0o600 });
-  let stopped = false;
+  const targetRoot = resolveBranchWorktree(config.repoRoot, target.branch);
+  if (!targetRoot) throw new Error(`TASK_VALIDATION_WORKTREE_NOT_FOUND: ${target.branch}`);
+  const worktree = assertGitWorktreeBinding(config.repoRoot, targetRoot, target.branch);
+  const originalBranch = git(worktree.worktreeRoot, ['symbolic-ref', '--quiet', '--short', 'HEAD']);
+  const originalHead = git(worktree.worktreeRoot, ['rev-parse', 'HEAD']);
   let restored = false;
   try {
-    appendSandboxControlAudit(manifest, 'lease-acquire', { ownerPid: process.pid });
-    waitForState(control.statusDir, (status) => status.state === 'parked' && status.reasonCode === 'SANDBOX_CONTROL_HANDOFF_ACTIVE');
-    if (row.running) {
-      runEngine(engine, 'docker', ['stop', row.name]);
-      stopped = true;
-    }
-    const refreshedRows = fetchSandboxRows(engine, sandboxLabel(config), sandboxBranchLabel(config));
-    const refreshed = selectSandboxContainer(
-      [...refreshedRows.running, ...refreshedRows.nonRunning],
-      containerNameCandidates(config, target.branch)
-    );
-    if (!refreshed || refreshed.running) throw new Error('SANDBOX_VALIDATION_CONTAINER_STILL_RUNNING');
-    const activeLease = readActiveLease(manifest);
-    if (!activeLease || activeLease.nonce !== nonce) throw new Error('SANDBOX_VALIDATION_LEASE_OWNERSHIP_LOST');
-    assertGitWorktreeBinding(config.repoRoot, manifest.worktreeRoot, target.branch);
-    const result = runValidationCommand(options.command, manifest.worktreeRoot, 'inplace', options.timeoutMs, options.format === 'json');
+    const result = runValidationCommand(options.command, worktree.worktreeRoot, 'inplace', options.timeoutMs, options.format === 'json');
     return { ...result, cleanup: () => restored ? 'completed' : 'pending' };
   } finally {
-    const recoveryErrors: string[] = [];
     try {
-      const currentBranch = git(manifest.worktreeRoot, ['symbolic-ref', '--quiet', '--short', 'HEAD']);
-      if (currentBranch !== originalBranch) git(manifest.worktreeRoot, ['switch', originalBranch]);
+      const currentBranch = git(worktree.worktreeRoot, ['symbolic-ref', '--quiet', '--short', 'HEAD']);
+      if (currentBranch !== originalBranch) git(worktree.worktreeRoot, ['switch', originalBranch]);
     } catch {
       try {
-        git(manifest.worktreeRoot, ['checkout', '--detach', originalHead]);
-        git(manifest.worktreeRoot, ['switch', originalBranch]);
-      } catch (fallbackError) {
-        recoveryErrors.push(`git binding restore failed: ${fallbackError instanceof Error ? fallbackError.message : String(fallbackError)}`);
-      }
-    }
-    if (stopped) {
-      try {
-        runEngine(engine, 'docker', ['start', row.name]);
-      } catch (error) {
-        recoveryErrors.push(`container start failed: ${error instanceof Error ? error.message : String(error)}`);
-      }
-    }
-    try {
-      const currentLease = JSON.parse(fs.readFileSync(leasePath, 'utf8')) as { nonce?: unknown };
-      if (currentLease.nonce !== nonce) throw new Error('SANDBOX_VALIDATION_LEASE_OWNERSHIP_LOST');
-    } catch (error) {
-      recoveryErrors.push(error instanceof Error ? error.message : String(error));
-    }
-    if (recoveryErrors.length === 0) {
-      try {
-        fs.unlinkSync(leasePath);
-        appendSandboxControlAudit(manifest, 'lease-release', { ownerPid: process.pid });
-        waitForState(control.statusDir, (status) => status.state === 'healthy');
-        restored = true;
+        git(worktree.worktreeRoot, ['checkout', '--detach', originalHead]);
+        git(worktree.worktreeRoot, ['switch', originalBranch]);
       } catch (error) {
-        try {
-          if (!fs.existsSync(leasePath)) {
-            fs.writeFileSync(leasePath, `${JSON.stringify(lease)}\n`, { flag: 'wx', mode: 0o600 });
-          }
-          appendSandboxControlAudit(manifest, 'lease-release-failed', { ownerPid: process.pid });
-        } catch (leaseError) {
-          recoveryErrors.push(`lease preservation failed: ${leaseError instanceof Error ? leaseError.message : String(leaseError)}`);
-        }
-        recoveryErrors.push(error instanceof Error ? error.message : String(error));
+        throw new Error(`TASK_VALIDATION_WORKTREE_RESTORE_FAILED: ${error instanceof Error ? error.message : String(error)}`);
       }
     }
-    if (recoveryErrors.length > 0) {
-      throw new Error(
-        `SANDBOX_VALIDATION_RECOVERY_INCOMPLETE: ${recoveryErrors.join('; ')}; run 'ai sandbox start ${target.branch}'`
-      );
-    }
+    restored = true;
   }
 }
 

package/lib/platform/github-client.ts

@@ -51,6 +51,33 @@ function boundedFailureDetail(result: RunResult): string {
     : `${diagnostic.slice(0, ERROR_DETAIL_LIMIT)}… [truncated]`;
 }
 
+function requestDiagnostics(args: string[], request: RequestOptions, attempt: number, errorMessage: string): string {
+  if (process.env.AGENT_INFRA_GH_DIAGNOSTICS !== '1' && !/rate.?limit/iu.test(errorMessage)) return '';
+
+  const apiIndex = args.indexOf('api');
+  const endpoint = apiIndex < 0
+    ? args.slice(0, 2).filter((arg) => !arg.startsWith('-')).join(' ')
+    : args.slice(apiIndex + 1).find((arg) => !arg.startsWith('-') && !arg.includes('=')) || 'unknown';
+  const safeEndpoint = endpoint.startsWith('http')
+    ? (() => {
+      try {
+        const url = new URL(endpoint);
+        return `${url.host}${url.pathname}`;
+      } catch {
+        return 'unknown';
+      }
+    })()
+    : endpoint.split('?')[0] || 'unknown';
+  const methodIndex = args.findIndex((arg) => arg === '-X' || arg === '--method');
+  const methodFromArgs = methodIndex >= 0 ? args[methodIndex + 1] : undefined;
+  const method = methodFromArgs || request.method || (safeEndpoint === 'graphql' ? 'POST' : 'GET');
+  const tokenEnvironment = ['GH_TOKEN', 'GITHUB_TOKEN', 'GH_ENTERPRISE_TOKEN', 'GITHUB_ENTERPRISE_TOKEN']
+    .filter((name) => Boolean(process.env[name]));
+  const configDirOverride = Boolean(process.env.GH_CONFIG_DIR);
+
+  return ` [gh-diagnostic endpoint=${safeEndpoint} method=${method} attempt=${attempt} tokenEnv=${tokenEnvironment.join(',') || 'none'} ghConfigDirOverride=${configDirOverride}]`;
+}
+
 function defaultRunner(args: string[], options: RunOptions): RunResult {
   const command = process.env.AGENT_INFRA_GH_BIN || 'gh';
   let prefix: string[] = [];
@@ -168,13 +195,17 @@ function createGitHubClient(options: ClientOptions = {}): GitHubClient {
       const result = runner(args, request);
       if (result.status === 0) return { ok: true, value: result.stdout };
       const error = classifyGitHubFailure(result);
-      if (!retryableMethod || !error.requestRetryable) return { ok: false, error: clientError(error) };
+      const requestDetail = requestDiagnostics(args, request, attempt + 1, error.message);
+      const contextualError = requestDetail
+        ? { ...error, message: `${error.message}${requestDetail}` }
+        : error;
+      if (!retryableMethod || !error.requestRetryable) return { ok: false, error: clientError(contextualError) };
       if (attempt >= delays.length) {
         return {
           ok: false,
           error: error.code === 'NETWORK_TRANSIENT'
-            ? { ...clientError(error), code: 'NETWORK_RETRY_EXHAUSTED', message: `${error.message} (retry exhausted)` }
-            : clientError(error)
+            ? { ...clientError(contextualError), code: 'NETWORK_RETRY_EXHAUSTED', message: `${contextualError.message} (retry exhausted)` }
+            : clientError(contextualError)
         };
       }
       sleep(delays[attempt]!);

package/lib/platform/release-notes.ts

@@ -136,8 +136,8 @@ async function releaseNoteContext(
   options: ReleaseNoteOptions = {}
 ) {
   const historyLimit = input.historyLimit ?? 3;
-  if (!input.fromTag || !input.toTag || !input.branch || !Number.isInteger(historyLimit) || historyLimit < 1 || historyLimit > 20) {
-    return { ...baseResult('failed'), error: { code: 'RELEASE_NOTES_INPUT_INVALID', message: 'from-tag, to-tag, branch, and a history limit from 1 to 20 are required', retryable: false } };
+  if (!input.fromTag || !input.toTag || !input.branch || !Number.isInteger(historyLimit) || historyLimit < 1 || historyLimit > 100) {
+    return { ...baseResult('failed'), error: { code: 'RELEASE_NOTES_INPUT_INVALID', message: 'from-tag, to-tag, branch, and a history limit from 1 to 100 are required', retryable: false } };
   }
   const cwd = path.resolve(options.cwd || process.cwd());
   const platformType = options.platformType ?? configuredPlatform(cwd);

package/lib/sandbox/commands/control-status.ts

@@ -14,7 +14,6 @@ export function readSandboxControlStatusForRow(
     : { mode: 'branch-only' as const };
   const control = sandboxControlPaths({
     base: config.controlBase,
-    repoRoot: config.repoRoot,
     project: config.project,
     container: row.name,
     identity

package/lib/sandbox/commands/create.ts

@@ -91,6 +91,7 @@ import {
   materializeSandboxControl,
   materializeSandboxWorkspaceView,
   prepareSandboxWorkspaceMountTargets,
+  prepareSandboxCompletedTaskMountSource,
   sandboxControlPaths,
 } from '../workspace-view.ts';
 import { clipboardHostDir, CONTAINER_CLIPBOARD_MOUNT } from '../clipboard/paths.ts';
@@ -1107,7 +1108,6 @@ export async function create(
   const container = containerName(effectiveConfig, branch);
   const controlPaths = sandboxControlPaths({
     base: effectiveConfig.controlBase,
-    repoRoot: effectiveConfig.repoRoot,
     project: effectiveConfig.project,
     container,
     identity: target.workspace
@@ -1451,7 +1451,10 @@ export async function create(
             const taskSource = target.workspace.mode === 'task-bound'
               ? assertSandboxTaskSource(effectiveConfig.repoRoot, target.workspace.taskId)
               : null;
-            prepareSandboxWorkspaceMountTargets(worktree);
+            const completedTaskSource = target.workspace.mode === 'task-bound'
+              ? prepareSandboxCompletedTaskMountSource(effectiveConfig.repoRoot, target.workspace.taskId)
+              : null;
+            prepareSandboxWorkspaceMountTargets(worktree, target.workspace.mode === 'task-bound' ? target.workspace.taskId : undefined);
             if (previousCutoverSnapshot) {
               assertSandboxControlCutoverSnapshot(previousCutoverSnapshot);
               if (previousManifest) {
@@ -1489,11 +1492,13 @@ export async function create(
               shellConfigHostDir: hostShellConfig.hostDir,
               workspaceViewRoot: workspaceView.root,
               controlDir: control.channelDir,
+              ...(target.workspace.mode === 'task-bound' ? { controlRootDir: control.root } : {}),
               controlStatusDir: control.statusDir,
               ...(target.workspace.mode === 'task-bound' ? { runtimeDir: control.runtimeDir } : {}),
               ...(target.workspace.mode === 'task-bound'
                 ? {
                   taskSources: [taskSource!],
+                  completedTaskSource: completedTaskSource!,
                   taskId: target.workspace.taskId
                 }
                 : {})
@@ -1583,8 +1588,6 @@ export async function create(
                 ]
                 : []),
               '-e',
-              `AGENT_INFRA_CONTROL_TOKEN=${control.token}`,
-              '-e',
               `AGENT_INFRA_CONTROL_GENERATION=${control.generation}`,
               '-e',
               'AGENT_INFRA_CONTROL_DIR=/run/agent-infra/control',
@@ -1593,7 +1596,10 @@ export async function create(
               '-e',
               `AGENT_INFRA_CONTROL_ROOT_ID=${control.controlRootId}`,
               ...(target.workspace.mode === 'task-bound'
-                ? ['-e', 'AGENT_INFRA_RUNTIME_DIR=/run/agent-infra/runtime']
+                ? [
+                  '-e', 'AGENT_INFRA_CONTROL_ROOT_DIR=/run/agent-infra/control-root',
+                  '-e', 'AGENT_INFRA_RUNTIME_DIR=/run/agent-infra/runtime'
+                ]
                 : []),
               '--label',
               `${sandboxRuntimeCapabilityLabel(effectiveConfig)}=${capabilityPlan.runtimeSignature}`,

package/lib/sandbox/commands/ls.ts

@@ -18,11 +18,10 @@ export { containerListFormat, parseLabels } from './list-running.ts';
 const USAGE = `Usage: ai sandbox ls
 
 Lists all containers for the current project. The '#' column is a
-display-only row number; the 'SHORT' column shows the active task short
-id bound to each container's branch (via
-.agents/workspace/active/.short-ids.json), or '-' if no active task is
-bound. Pass the SHORT value to "ai sandbox exec" (e.g. 'ai sandbox exec 11').
-A SHORT value of '-' means this container has no active task short id and may
+display-only row number; the 'SHORT' column shows the task short id bound to
+each task-bound container, or '-' if no short id is registered. Pass the
+SHORT value to "ai sandbox exec" (e.g. 'ai sandbox exec 11').
+A SHORT value of '-' means this container has no task short id and may
 be eligible for "ai sandbox rm --unbound" cleanup. Use a full TASK-id to
 remove a specific task-bound sandbox.
 

package/lib/sandbox/commands/rm.ts

@@ -13,7 +13,7 @@ import { fetchSandboxRows } from './list-running.ts';
 import { rmOne, rmPurge, rmUnbound } from '../removal.ts';
 
 const USAGE = `Usage:
-  ai sandbox rm <branch | TASK-id | short id> Remove one sandbox; use a full TASK-id for a task-bound sandbox and a branch for branch-only sandboxes
+  ai sandbox rm <branch | TASK-id | short id> Remove one sandbox; use a retained short id or full TASK-id for a task-bound sandbox and a branch for branch-only sandboxes
   ai sandbox rm --unbound [--dry-run] [--yes] Remove sandboxes not bound to an active task short id
   ai sandbox rm --purge                     Tear down ALL sandboxes for the project (containers, worktrees, image, VM)`;
 

package/lib/sandbox/config.ts

@@ -237,3 +237,16 @@ export function loadConfig({
     }
   };
 }
+
+export function loadSandboxControlLocation(repoRoot = detectRepoRoot()): Readonly<{
+  controlBase: string;
+  project: string;
+}> | null {
+  const configPath = path.join(repoRoot, '.agents', '.airc.json');
+  if (!fs.existsSync(configPath)) return null;
+  const airc = JSON.parse(fs.readFileSync(configPath, 'utf8')) as AircConfig;
+  if (typeof airc.project !== 'string' || !airc.project) return null;
+  const home = homedir();
+  if (!home) throw new Error('sandbox: home directory is required');
+  return { controlBase: hostJoin(home, '.agent-infra', 'sandbox-control'), project: airc.project };
+}

package/lib/sandbox/control/audit.ts

@@ -41,8 +41,7 @@ const AUDIT_MAX_BYTES = 1024 * 1024;
 
 export function requestAuditFields(manifest: SandboxControlManifest, request: SandboxControlRequest) {
   return {
-    requestId: request.id, requestFamily: request.family, sandboxTaskId: manifest.taskId,
-    requestGeneration: request.generation, requestIssuedAt: request.issuedAt, requestExpiresAt: request.expiresAt
+    requestId: request.id, requestFamily: request.family, sandboxTaskId: manifest.taskId
   };
 }