@fitlab-ai/agent-infra 0.9.14 → 0.9.15

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

@@ -1,4 +1,5 @@
 import fs from 'node:fs';
+import path from 'node:path';
 
 import {
   accessSandboxTaskView,
@@ -13,12 +14,18 @@ import {
   PUBLIC_CLI_SELECTOR_ALIASES,
   internalRouteSelector
 } from './cli-route-inventory.ts';
+import { readSandboxControlIdentitySentinel } from '../sandbox/control/identity-sentinel.ts';
 
 export type TaskOperationDispatcher = 'public' | 'internal';
 export type TaskOperationScope = 'task-bound' | 'non-task' | 'conditional';
 export type TaskOperationEffect = TaskViewAccessEffect;
 export type TaskRefSource = 'argv' | 'environment' | 'none' | 'delegated' | 'input';
 
+export type SandboxControlTransportDecision = Readonly<{
+  kind: 'direct-host' | 'broker-client' | 'fail-closed';
+  reasonCode: string | null;
+}>;
+
 export type TaskOperationDescriptor = Readonly<{
   dispatcher: TaskOperationDispatcher;
   command: string;
@@ -49,6 +56,10 @@ function internalTaskRoutes(): TaskOperationDescriptor[] {
     descriptor('internal', 'sandbox-control', 'execute', 'non-task', 'progress', 'none'),
     descriptor('internal', 'sandbox-control', 'recover', 'conditional', 'recovery', 'delegated'),
     descriptor('internal', 'sandbox-control', 'client', 'conditional', 'progress', 'delegated'),
+    descriptor('internal', 'host-control', 'serve', 'non-task', 'progress', 'none'),
+    descriptor('internal', 'host-control', 'status', 'non-task', 'diagnostic', 'none'),
+    descriptor('internal', 'host-control', 'install', 'non-task', 'progress', 'none'),
+    descriptor('internal', 'host-control', 'uninstall', 'non-task', 'progress', 'none'),
     descriptor('internal', 'agent-client', 'next-steps', 'non-task', 'diagnostic', 'none'),
     descriptor('internal', 'agent-client', 'model-selection', 'non-task', 'diagnostic', 'none'),
     descriptor('internal', 'codex-lifecycle', 'preflight', 'non-task', 'diagnostic', 'none'),
@@ -145,7 +156,8 @@ function internalTaskRoutes(): TaskOperationDescriptor[] {
     descriptor('internal', 'task-snapshot', 'snapshot', 'conditional', 'diagnostic'),
     descriptor('internal', 'task-verify', 'event', 'task-bound', 'terminal-verdict'),
     descriptor('internal', 'task-validate', 'snapshot', 'conditional', 'diagnostic'),
-    descriptor('internal', 'task-validate', 'inplace', 'task-bound', 'progress')
+    descriptor('internal', 'task-validate', 'inplace', 'task-bound', 'progress'),
+    descriptor('internal', 'manual-validation', 'transaction', 'task-bound', 'remote-write')
   ];
 }
 
@@ -207,12 +219,12 @@ 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', 'host-control', 'agent-client', 'codex-lifecycle', 'codex-sandbox-controller',
   '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',
   'task-orchestration', 'task-review', 'task-event', 'task-invalidation', 'task-lifecycle',
-  'task-finalization', 'task-override', 'task-short-id', 'task-snapshot', 'task-verify', 'task-validate'
+  'task-finalization', 'task-override', 'task-short-id', 'task-snapshot', 'task-verify', 'task-validate', 'manual-validation'
 ]);
 export const PUBLIC_DISPATCHER_ROUTES = Object.freeze([
   'agent-client', 'cp', 'data', 'decide', 'help', 'init', 'merge', 'run', 'sandbox', 'server', 'task', 'sync', 'update', 'version'
@@ -284,6 +296,35 @@ const TASK_CONTROL_MARKER_KEYS = [
   'AGENT_INFRA_CONTROL_STATUS_DIR'
 ] as const;
 
+const TASK_CONTROL_CONFIG_KEYS = [
+  'AGENT_INFRA_CONTROL_TOKEN',
+  'AGENT_INFRA_CONTROL_GENERATION',
+  'AGENT_INFRA_CONTROL_ROOT_ID',
+  'AGENT_INFRA_CONTROL_DIR',
+  'AGENT_INFRA_CONTROL_STATUS_DIR'
+] as const;
+export const SANDBOX_CONTROL_STATUS_MOUNT = '/run/agent-infra/control-status';
+
+type NativeDirectoryProbe = 'present' | 'absent' | 'unknown';
+
+function nativeDirectoryProbe(candidate: string): NativeDirectoryProbe {
+  try {
+    // The fixed mount is a trust anchor. Do not use a mutable node:fs export:
+    // a preload must not turn a mounted sandbox into the direct-host path by
+    // replacing the ordinary filesystem probe.
+    const binding = (process as unknown as {
+      binding(name: string): { internalModuleStat(filePath: string): number }
+    }).binding('fs');
+    if (!Function.prototype.toString.call(binding.internalModuleStat).includes('[native code]')) return 'unknown';
+    const result = binding.internalModuleStat(candidate);
+    if (result === 1) return 'present';
+    if (result === -2) return 'absent';
+    return 'unknown';
+  } catch {
+    return 'unknown';
+  }
+}
+
 type TaskMarkerState = 'none' | 'branch-only' | 'task-bound' | 'incomplete';
 
 function taskMarkerState(env: NodeJS.ProcessEnv): TaskMarkerState {
@@ -298,6 +339,73 @@ function taskMarkerState(env: NodeJS.ProcessEnv): TaskMarkerState {
   return 'incomplete';
 }
 
+export function resolveSandboxControlTransport(
+  env: NodeJS.ProcessEnv = process.env,
+  options: Readonly<{ statusMountPath?: string }> = {}
+): SandboxControlTransportDecision {
+  const configuredStatusDir = env.AGENT_INFRA_CONTROL_STATUS_DIR;
+  const fixedStatusDir = options.statusMountPath
+    ?? SANDBOX_CONTROL_STATUS_MOUNT;
+  const hasAnyMarker = TASK_MARKER_KEYS.some((key) => Boolean(env[key]))
+    || Boolean(env.AGENT_INFRA_CONTROL_CONTROLLER_BINDING)
+    || Boolean(env.AGENT_INFRA_EXECUTOR_MANIFEST);
+  const fixedStatusProbe = !env.AGENT_INFRA_TEST_HOST_CONTROL_ENDPOINT && path.isAbsolute(fixedStatusDir)
+    ? nativeDirectoryProbe(fixedStatusDir) : 'absent';
+  if (fixedStatusProbe === 'unknown') {
+    return { kind: 'fail-closed', reasonCode: 'SANDBOX_CONTROL_IDENTITY_UNAVAILABLE' };
+  }
+  const fixedStatusMounted = fixedStatusProbe === 'present';
+  const configuredStatusProbe = configuredStatusDir && path.isAbsolute(configuredStatusDir)
+    ? nativeDirectoryProbe(configuredStatusDir) : 'absent';
+  if (configuredStatusProbe === 'unknown') {
+    return { kind: 'fail-closed', reasonCode: 'SANDBOX_CONTROL_IDENTITY_UNAVAILABLE' };
+  }
+  const statusDir = configuredStatusDir && path.isAbsolute(configuredStatusDir) && configuredStatusProbe === 'present'
+    ? configuredStatusDir
+    : fixedStatusMounted ? fixedStatusDir : null;
+  const statusMounted = statusDir !== null;
+  const hasCompleteConfig = TASK_CONTROL_CONFIG_KEYS.every((key) => Boolean(env[key]));
+  if (env.AGENT_INFRA_EXECUTOR_MANIFEST || env.AGENT_INFRA_CONTROL_CONTROLLER_BINDING) {
+    return { kind: 'fail-closed', reasonCode: 'TASK_CONTROL_TRANSPORT_INVALID' };
+  }
+  const taskBound = Boolean(env.AGENT_INFRA_TASK_ID);
+  const runtime = Boolean(env.AGENT_INFRA_RUNTIME_DIR);
+
+  if (statusMounted) {
+    let sentinel;
+    try {
+      sentinel = readSandboxControlIdentitySentinel(statusDir);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : '';
+      return { kind: 'fail-closed', reasonCode: message.endsWith('MISSING')
+        ? 'SANDBOX_CONTROL_IDENTITY_MISSING'
+        : 'SANDBOX_CONTROL_IDENTITY_MALFORMED' };
+    }
+    if (sentinel.generation !== env.AGENT_INFRA_CONTROL_GENERATION) {
+      return { kind: 'fail-closed', reasonCode: 'SANDBOX_CONTROL_IDENTITY_GENERATION_MISMATCH' };
+    }
+    if (env.AGENT_INFRA_CONTROL_ROOT_ID && sentinel.controlRootId !== env.AGENT_INFRA_CONTROL_ROOT_ID) {
+      return { kind: 'fail-closed', reasonCode: 'SANDBOX_CONTROL_IDENTITY_ROOT_ID_MISMATCH' };
+    }
+    if (sentinel.mode === 'task-bound'
+      && (sentinel.taskId !== env.AGENT_INFRA_TASK_ID || !runtime)) {
+      return { kind: 'fail-closed', reasonCode: 'SANDBOX_CONTROL_IDENTITY_TOPOLOGY_MISMATCH' };
+    }
+    if (sentinel.mode === 'branch-only' && (taskBound || runtime)) {
+      return { kind: 'fail-closed', reasonCode: 'SANDBOX_CONTROL_IDENTITY_TOPOLOGY_MISMATCH' };
+    }
+    if (!hasCompleteConfig) {
+      return { kind: 'fail-closed', reasonCode: 'SANDBOX_CONTROL_CONFIGURATION_INCOMPLETE' };
+    }
+    return { kind: 'broker-client', reasonCode: null };
+  }
+  if (!hasAnyMarker) return { kind: 'direct-host', reasonCode: null };
+  if (!hasCompleteConfig || (taskBound && !runtime) || (!taskBound && runtime)) {
+    return { kind: 'fail-closed', reasonCode: 'SANDBOX_CONTROL_CONFIGURATION_INCOMPLETE' };
+  }
+  return { kind: 'broker-client', reasonCode: null };
+}
+
 export function hasTaskBoundMarker(env: NodeJS.ProcessEnv = process.env): boolean {
   return taskMarkerState(env) === 'task-bound';
 }

package/lib/internal/task-review.ts

@@ -1,8 +1,9 @@
+import { parseReviewCommand } from '../task/review-command.ts';
 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';
-import { ensureInternalHandlerRoute, internalHandlerRoute } from './cli-route-inventory.ts';
+import { ensureInternalHandlerRoute } from './cli-route-inventory.ts';
 
 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';
 
@@ -23,56 +24,10 @@ async function taskReview(args: string[] = []): Promise<void> {
     process.stdout.write(USAGE);
     return;
   }
-  if (args.length < 2) {
-    failUsage('task ref and intent are required');
-    return;
-  }
-  if (!internalHandlerRoute('task-review', 'finalize-summary', args[1] ?? '')) {
-    failUsage(`unknown intent '${args[1]}'`);
-    return;
-  }
-  let stage = '';
-  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', '--override-ticket', '--override-target', '--override-scope'].includes(flag)) {
-      failUsage(`unknown option '${flag}'`);
-      return;
-    }
-    if (seen.has(flag)) {
-      failUsage(`duplicate option '${flag}'`);
-      return;
-    }
-    seen.add(flag);
-    if (flag === '--dry-run') {
-      dryRun = true;
-      continue;
-    }
-    if (flag === '--orchestrated') {
-      orchestrated = true;
-      continue;
-    }
-    const value = args[++index];
-    if (!value || value.startsWith('--')) {
-      failUsage(`option '${flag}' requires a value`);
-      return;
-    }
-    if (flag === '--stage') stage = 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;
-  }
+  let request;
+  try { request = parseReviewCommand(args); }
+  catch (error) { failUsage(error instanceof Error ? error.message : String(error)); return; }
+  const { stage, artifact, dryRun, orchestrated, overrideTicket, overrideTarget, overrideScope } = request;
   const dryRunConflict = overrideDryRunConflict({ dryRun, overrideTicket, overrideTarget, overrideScope });
   if (dryRunConflict) { failUsage(dryRunConflict.message); return; }
   const resolved = resolveTaskRef(args[0]!);

package/lib/internal/task-validate.ts

@@ -24,9 +24,12 @@ import {
 } from '../sandbox/control/protocol.ts';
 import { getProcessStartTime } from '../server/process-state.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';
+import { writeJsonAtomic } from '../task/manual-validation-shared.ts';
 import { ensureInternalHandlerRoute, internalHandlerRoute } from './cli-route-inventory.ts';
 
-const USAGE = `Usage: agent-infra-internal task-validate <branch | TASK-id | N> [--scope snapshot|inplace] [--timeout <ms>] [--format text|json] -- <command> [args...]`;
+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;
 
@@ -35,13 +38,14 @@ type ValidateOptions = {
   scope: 'snapshot' | 'inplace';
   timeoutMs: number;
   format: 'text' | 'json';
+  evidenceFile: string | null;
   command: string[];
   help: boolean;
 };
 
 export function parseValidateArgs(args: string[]): ValidateOptions {
   if (args.includes('--help') || args.includes('-h')) {
-    return { target: '', scope: 'snapshot', timeoutMs: 300_000, format: 'text', command: [], help: true };
+    return { target: '', scope: 'snapshot', timeoutMs: 300_000, format: 'text', evidenceFile: null, command: [], help: true };
   }
   const separator = args.indexOf('--');
   if (separator < 0) throw new Error(`${USAGE}\nA literal -- must separate validation options from the command.`);
@@ -50,6 +54,7 @@ export function parseValidateArgs(args: string[]): ValidateOptions {
   let scope: ValidateOptions['scope'] = 'snapshot';
   let timeoutMs = 300_000;
   let format: ValidateOptions['format'] = 'text';
+  let evidenceFile: string | null = null;
   const positionals: string[] = [];
   for (let index = 0; index < optionArgs.length; index += 1) {
     const arg = optionArgs[index]!;
@@ -65,6 +70,10 @@ export function parseValidateArgs(args: string[]): ValidateOptions {
       const value = optionArgs[++index];
       if (value !== 'text' && value !== 'json') throw new Error('validate --format must be text or json');
       format = value;
+    } else if (arg === '--evidence-file') {
+      const value = optionArgs[++index];
+      if (!value || value.startsWith('-')) throw new Error('validate --evidence-file requires a path');
+      evidenceFile = value;
     } else if (arg.startsWith('-')) {
       throw new Error(`Unknown option: ${arg}`);
     } else {
@@ -72,7 +81,7 @@ export function parseValidateArgs(args: string[]): ValidateOptions {
     }
   }
   if (positionals.length !== 1 || command.length === 0) throw new Error(USAGE);
-  return { target: positionals[0]!, scope, timeoutMs, format, command, help: false };
+  return { target: positionals[0]!, scope, timeoutMs, format, evidenceFile, command, help: false };
 }
 
 function runValidationCommand(command: string[], cwd: string, scope: string, timeoutMs: number, json: boolean) {
@@ -294,23 +303,30 @@ function taskValidate(args: string[]): void {
       : internalHandlerRoute('task-validate', 'inplace', options.scope)
         ? inplaceValidation(config, target, options)
         : (() => { throw new Error('TASK_VALIDATE_SCOPE_UNREGISTERED'); })();
-    const evidence = {
-      version: 1,
+    const cleanup = result.cleanup() as ManualValidationCleanup;
+    const evidence = createManualValidationEvidence({
+      mode: target.workspace.mode,
       taskId: target.workspace.mode === 'task-bound' ? target.workspace.taskId : null,
       branch: target.branch,
-      scope: options.scope,
       commit,
+      recoverable: target.workspace.mode === 'task-bound',
+      scope: options.scope,
       command: path.basename(options.command[0]!),
       startedAt,
       completedAt: new Date().toISOString(),
       exitCode: result.exitCode,
       signal: result.signal,
-      cleanup: result.cleanup()
-    };
+      cleanup
+    });
+    if (options.evidenceFile) {
+      try { writeJsonAtomic(path.resolve(options.evidenceFile), evidence); }
+      catch (error) { throw new Error(`MANUAL_VALIDATION_EVIDENCE_WRITE_FAILED: ${error instanceof Error ? error.message : String(error)}`); }
+    }
+    const evidenceSummary = manualValidationEvidenceSummary(evidence);
     if (options.format === 'json') {
-      process.stdout.write(`${JSON.stringify({ status: 'applied', changed: false, evidence, error: null })}\n`);
+      process.stdout.write(`${JSON.stringify({ status: 'applied', changed: false, evidence: evidenceSummary, evidenceFile: options.evidenceFile, error: null })}\n`);
     } else {
-      process.stdout.write(`Validation ${result.exitCode === 0 ? 'passed' : 'failed'} (${options.scope}, ${evidence.command}, cleanup=${evidence.cleanup}).\n`);
+      process.stdout.write(`Validation ${result.exitCode === 0 ? 'passed' : 'failed'} (${options.scope}, ${evidenceSummary.command}, cleanup=${evidenceSummary.cleanup}).\n`);
     }
     process.exitCode = result.exitCode;
   } catch (error) {

package/lib/owned-path.ts

@@ -0,0 +1,26 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+// Inspect descendants without following symlinks. The caller supplies the trusted root.
+export function inspectOwnedPath(rootInput: string, targetInput: string, expect: 'file' | 'directory'): fs.Stats | null {
+  const root = path.resolve(rootInput);
+  const target = path.resolve(targetInput);
+  const relative = path.relative(root, target);
+  if (!relative || relative.startsWith('..') || path.isAbsolute(relative)) return null;
+  try {
+    const rootStat = fs.lstatSync(root);
+    if (rootStat.isSymbolicLink() || !rootStat.isDirectory()) return null;
+    let current = root;
+    for (const segment of relative.split(path.sep)) {
+      current = path.join(current, segment);
+      const stat = fs.lstatSync(current);
+      if (stat.isSymbolicLink()) return null;
+      if (process.platform !== 'win32' && typeof process.getuid === 'function' && stat.uid !== process.getuid()) return null;
+      if (current === target) return (expect === 'file' ? stat.isFile() : stat.isDirectory()) ? stat : null;
+      if (!stat.isDirectory()) return null;
+    }
+  } catch {
+    return null;
+  }
+  return null;
+}

package/lib/platform/check-status.ts

@@ -0,0 +1,9 @@
+import type { PlatformCheckSnapshot } from './snapshots.ts';
+
+export function checkStatusBucket(status: string): PlatformCheckSnapshot['bucket'] {
+  const value = status.toLowerCase();
+  if (['pass', 'success', 'successful', 'neutral'].includes(value)) return 'pass';
+  if (['fail', 'failure', 'failed', 'error', 'timed_out', 'action_required'].includes(value)) return 'fail';
+  if (['cancel', 'cancelled', 'canceled', 'skipped', 'stale'].includes(value)) return 'cancel';
+  return 'pending';
+}

package/lib/platform/comment-safety.ts

@@ -185,6 +185,10 @@ function sanitizeMarkdownDocument(value: string, options: SanitizationOptions =
   return ok(result + tail.value);
 }
 
+function canonicalizeCommentBody(value: string): SanitizationResult<string> {
+  return sanitizeMarkdownDocument(value, { reservedMarkers: [CONTROL_MARKER_PATTERN] });
+}
+
 function renderSafeCodeFence(value: string, language = '', reservedMarkers: readonly RegExp[] = [CONTROL_MARKER_PATTERN]): string {
   const content = markerSafe(normalized(value), reservedMarkers);
   const longestRun = Math.max(0, ...(content.match(/`+/g) || []).map((run) => run.length));
@@ -244,6 +248,7 @@ export {
   escapeMarkdownLiteral,
   fenceRanges,
   renderSafeCodeFence,
+  canonicalizeCommentBody,
   sanitizeMarkdownDocument,
   splitDocumentPlaceholder
 };

package/lib/platform/completion-backfill.ts

@@ -2,7 +2,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 
 import { COMPLETION_BACKFILL_FAMILIES, inspectCompletionArtifacts } from '../task/finalization-artifacts.ts';
-import { parseArtifactName } from '../task/artifact-lifecycle.ts';
+import { parseArtifactName } from '../task/artifact-name.ts';
 import { parseTaskFrontmatter } from '../task/frontmatter.ts';
 import { resolveTaskRef } from '../task/resolve-ref.ts';
 import { getOpenWorkflowWarnings } from '../task/workflow-warnings.ts';