@fitlab-ai/agent-infra 0.9.13 → 0.9.15

package/lib/host-control/server.ts

@@ -0,0 +1,180 @@
+import fs from 'node:fs';
+import net from 'node:net';
+import { createHash } from 'node:crypto';
+
+import {
+  HOST_CONTROL_DIRECTORY_MODE,
+  HOST_CONTROL_SOCKET_MODE,
+  ensureHostControlWorkerToken,
+  inspectHostControlEndpoint,
+  prepareHostControlDirectory,
+  removeHostControlWorkerToken,
+  resolveHostControlEndpoint
+} from './path.ts';
+import {
+  HOST_CONTROL_MAX_REQUEST_BYTES,
+  validateHostControlRequest,
+  type HostControlRequest,
+  type HostControlResponse
+} from './client.ts';
+import { acquireFileLock } from '../fs/file-lock.ts';
+import { appendHostControlAudit } from './audit.ts';
+
+export type HostControlDispatch = (request: HostControlRequest) => Promise<{ stdout: string; stderr: string; exitCode: number }>;
+
+export type HostControlAudit = Readonly<{
+  requestId: string;
+  taskId: string | null;
+  operation: string;
+  scope: string;
+  phase: 'accepted' | 'completed' | 'rejected';
+  outcome: string;
+  authorityKind: 'host-broker';
+  transportKind: 'host-fixed-transport';
+  identityDigest: string;
+}>;
+
+export type HostControlServerOptions = Readonly<{
+  endpoint?: string;
+  dispatch: HostControlDispatch;
+  audit?: (entry: HostControlAudit) => void;
+}>;
+
+function auditFor(request: HostControlRequest, phase: HostControlAudit['phase'], outcome: string): HostControlAudit {
+  return {
+    requestId: request.id,
+    taskId: request.taskId,
+    operation: request.operation,
+    scope: request.scope,
+    phase,
+    outcome,
+    authorityKind: 'host-broker',
+    transportKind: 'host-fixed-transport',
+    identityDigest: createHash('sha256').update(`${request.taskId ?? '-'}\0${request.generation ?? '-'}`, 'utf8').digest('hex')
+  };
+}
+
+function failedResponse(id: string, status: 'rejected' | 'unknown', code: string, message: string): HostControlResponse {
+  const error = { code, message };
+  const stdout = `${JSON.stringify({ status: 'failed', changed: status === 'rejected' ? false : null, error })}\n`;
+  return { version: 1, id, status, exitCode: 1, stdout, stderr: '', error };
+}
+
+async function handleConnection(socket: net.Socket, options: HostControlServerOptions): Promise<void> {
+  await new Promise<void>((resolve) => {
+    let input = '';
+    let completed = false;
+    let processing = false;
+    socket.setEncoding('utf8');
+    // A disconnected caller does not cancel an already dispatched domain operation.
+    socket.on('error', () => socket.destroy());
+    socket.on('close', () => { if (!processing) resolve(); });
+    socket.on('end', () => { if (!processing) socket.end(); });
+    const finish = (value: HostControlResponse): void => {
+      if (completed || socket.destroyed) return;
+      completed = true;
+      socket.end(`${JSON.stringify(value)}\n`);
+    };
+    socket.on('data', async (chunk: string) => {
+      if (completed || processing) return;
+      input += chunk;
+      if (Buffer.byteLength(input, 'utf8') > HOST_CONTROL_MAX_REQUEST_BYTES) {
+        finish(failedResponse('invalid', 'rejected', 'HOST_CONTROL_REQUEST_TOO_LARGE', 'request exceeds the control limit'));
+        return;
+      }
+      const newline = input.indexOf('\n');
+      if (newline < 0) return;
+      const raw = input.slice(0, newline);
+      let request: HostControlRequest;
+      try { request = validateHostControlRequest(JSON.parse(raw)); }
+      catch (error) {
+        finish(failedResponse('invalid', 'rejected', 'HOST_CONTROL_REQUEST_INVALID', error instanceof Error ? error.message : String(error)));
+        return;
+      }
+      processing = true;
+      let started = false;
+      try {
+        options.audit?.(auditFor(request, 'accepted', 'in-progress'));
+        started = true;
+        const result = await options.dispatch(request);
+        options.audit?.(auditFor(request, 'completed', result.exitCode === 0 ? 'success' : 'failure'));
+        finish({ version: 1, id: request.id, status: 'completed', ...result, error: null });
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        const code = /^([A-Z][A-Z0-9_]+)/u.exec(message)?.[1] ?? 'HOST_CONTROL_DISPATCH_FAILED';
+        const status = started ? 'unknown' : 'rejected';
+        try { options.audit?.(auditFor(request, started ? 'completed' : 'rejected', status)); }
+        catch { /* Return the uncertainty even when the audit sink is unavailable. */ }
+        finish(failedResponse(request.id, status, code, message));
+      } finally {
+        resolve();
+      }
+    });
+  });
+}
+
+export type RunningHostControlServer = Readonly<{
+  endpoint: string;
+  server: net.Server;
+  close: () => Promise<void>;
+}>;
+
+export async function startHostControlServer(options: HostControlServerOptions): Promise<RunningHostControlServer> {
+  const endpoint = options.endpoint ?? resolveHostControlEndpoint();
+  const audit = options.audit ?? ((entry: HostControlAudit) => appendHostControlAudit(endpoint, entry));
+  prepareHostControlDirectory(endpoint);
+  const lock = acquireFileLock(`${endpoint}.lock`);
+  let server: net.Server | undefined;
+  try {
+    ensureHostControlWorkerToken(endpoint);
+    try {
+      const existing = fs.lstatSync(endpoint);
+      if (existing.isSymbolicLink() || !existing.isSocket()) throw new Error('HOST_CONTROL_ENDPOINT_INVALID');
+      fs.unlinkSync(endpoint);
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error;
+    }
+    const connections = new Set<Promise<void>>();
+    server = net.createServer({ allowHalfOpen: true }, (socket) => {
+      const connection = handleConnection(socket, { ...options, audit });
+      connections.add(connection);
+      void connection.finally(() => connections.delete(connection));
+    });
+    const listeningServer = server;
+    await new Promise<void>((resolve, reject) => {
+      listeningServer.once('error', reject);
+      listeningServer.listen(endpoint, () => { listeningServer.off('error', reject); resolve(); });
+    });
+    fs.chmodSync(endpoint, HOST_CONTROL_SOCKET_MODE);
+    const inspection = inspectHostControlEndpoint(endpoint, { uid: process.getuid?.() });
+    if (!inspection.ok) {
+      await new Promise<void>((resolve) => listeningServer.close(() => resolve()));
+      removeHostControlWorkerToken(endpoint);
+      throw new Error(inspection.code ?? 'HOST_CONTROL_ENDPOINT_INVALID');
+    }
+    let closing: Promise<void> | undefined;
+    return {
+      endpoint,
+      server,
+      close: () => closing ??= (async () => {
+        try {
+          await new Promise<void>((resolve) => listeningServer.close(() => resolve()));
+          await Promise.all(connections);
+          await fs.promises.rm(endpoint, { force: true });
+          removeHostControlWorkerToken(endpoint);
+        } finally { lock.release(); }
+      })()
+    };
+  } catch (error) {
+    if (server?.listening) await new Promise<void>((resolve) => server!.close(() => resolve()));
+    lock.release();
+    throw error;
+  }
+}
+
+export async function serveHostControl(options: HostControlServerOptions, signal?: AbortSignal): Promise<void> {
+  const running = await startHostControlServer(options);
+  if (!signal) return;
+  if (signal.aborted) { await running.close(); return; }
+  await new Promise<void>((resolve) => signal.addEventListener('abort', () => { void running.close().then(resolve); }, { once: true }));
+}

package/lib/host-control/service.ts

@@ -0,0 +1,133 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import {
+  inspectHostControlEndpoint,
+  resolveHostControlEndpoint,
+  type HostControlPlatform
+} from './path.ts';
+import { serveHostControl, startHostControlServer, type HostControlDispatch, type RunningHostControlServer } from './server.ts';
+
+export type HostControlServiceOptions = Readonly<{
+  platform?: HostControlPlatform;
+  uid?: number;
+  username?: string;
+  endpoint?: string;
+  dispatch: HostControlDispatch;
+  audit?: Parameters<typeof startHostControlServer>[0]['audit'];
+}>;
+
+export type HostControlServicePlatform = 'linux' | 'darwin' | 'unsupported';
+
+function servicePlatform(): HostControlServicePlatform {
+  if (process.platform === 'linux' || process.platform === 'darwin') return process.platform;
+  return 'unsupported';
+}
+
+function serviceEntryPoint(): string {
+  const compiled = fileURLToPath(new URL('../../bin/internal-cli.js', import.meta.url));
+  if (fs.existsSync(compiled)) return fs.realpathSync.native(compiled);
+  const candidate = process.argv[1];
+  if (candidate && fs.existsSync(candidate)) return fs.realpathSync.native(candidate);
+  return fs.realpathSync.native(fileURLToPath(new URL('../../bin/internal-cli.ts', import.meta.url)));
+}
+
+function xml(value: string): string {
+  return value.replaceAll('&', '&amp;').replaceAll('<', '&lt;').replaceAll('>', '&gt;').replaceAll('"', '&quot;');
+}
+
+function systemdArgument(value: string): string {
+  const escaped = value.replace(/[\\"]/g, '\\$&')
+    .replace(/[\x00-\x1f\x7f]/g, (character) => `\\x${character.charCodeAt(0).toString(16).padStart(2, '0')}`)
+    .replaceAll('%', '%%');
+  return `"${escaped}"`;
+}
+
+function servicePaths(platform: HostControlServicePlatform = servicePlatform()): Readonly<{ unit?: string; plist?: string }> {
+  if (platform === 'linux') return { unit: path.join(os.homedir(), '.config', 'systemd', 'user', 'agent-infra-host-control.service') };
+  if (platform === 'darwin') return { plist: path.join(os.homedir(), 'Library', 'LaunchAgents', 'com.fitlab-ai.agent-infra.host-control.plist') };
+  throw new Error('HOST_CONTROL_UNSUPPORTED_PLATFORM');
+}
+
+export function installHostControlService(platform: HostControlServicePlatform = servicePlatform()): string {
+  const paths = servicePaths(platform);
+  const entry = serviceEntryPoint();
+  if (paths.unit) {
+    // mkdir only applies mode to directories it creates, and this one usually
+    // already exists, so restate the intended mode explicitly.
+    fs.mkdirSync(path.dirname(paths.unit), { recursive: true, mode: 0o700 });
+    fs.chmodSync(path.dirname(paths.unit), 0o700);
+    fs.writeFileSync(paths.unit, [
+      '[Unit]',
+      'Description=agent-infra host-control service',
+      '',
+      '[Service]',
+      // The ':' executable prefix disables environment expansion for literal paths.
+      `ExecStart=${systemdArgument(`:${process.execPath}`)} ${systemdArgument(entry)} host-control serve`,
+      'Restart=on-failure',
+      'NoNewPrivileges=true',
+      // Workers receive host paths, including working directories and inputs under /tmp.
+      'PrivateTmp=false',
+      '',
+      '[Install]',
+      'WantedBy=default.target',
+      ''
+    ].join('\n'), { mode: 0o600 });
+    fs.chmodSync(paths.unit, 0o600);
+    return paths.unit;
+  }
+  const plist = paths.plist!;
+  fs.mkdirSync(path.dirname(plist), { recursive: true, mode: 0o700 });
+  fs.chmodSync(path.dirname(plist), 0o700);
+  const argumentsXml = [process.execPath, entry, 'host-control', 'serve']
+    .map((argument) => `    <string>${xml(argument)}</string>`)
+    .join('\n');
+  fs.writeFileSync(plist, [
+    '<?xml version="1.0" encoding="UTF-8"?>',
+    '<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">',
+    '<plist version="1.0">',
+    '<dict>',
+    '  <key>Label</key>',
+    '  <string>com.fitlab-ai.agent-infra.host-control</string>',
+    '  <key>ProgramArguments</key>',
+    '  <array>',
+    argumentsXml,
+    '  </array>',
+    '  <key>RunAtLoad</key>',
+    '  <true/>',
+    '  <key>KeepAlive</key>',
+    '  <true/>',
+    '</dict>',
+    '</plist>',
+    ''
+  ].join('\n'), { mode: 0o600 });
+  fs.chmodSync(plist, 0o600);
+  return plist;
+}
+
+export function uninstallHostControlService(platform: HostControlServicePlatform = servicePlatform()): string {
+  const paths = servicePaths(platform);
+  const target = paths.unit ?? paths.plist!;
+  fs.rmSync(target, { force: true });
+  return target;
+}
+
+export function hostControlServiceEndpoint(options: Pick<HostControlServiceOptions, 'platform' | 'uid' | 'username' | 'endpoint'> = {}): string {
+  return options.endpoint ?? resolveHostControlEndpoint(options);
+}
+
+export async function startHostControlService(options: HostControlServiceOptions): Promise<RunningHostControlServer> {
+  return startHostControlServer({ endpoint: hostControlServiceEndpoint(options), dispatch: options.dispatch, ...(options.audit ? { audit: options.audit } : {}) });
+}
+
+export async function serveHostControlService(options: HostControlServiceOptions, signal?: AbortSignal): Promise<void> {
+  await serveHostControl({ endpoint: hostControlServiceEndpoint(options), dispatch: options.dispatch, ...(options.audit ? { audit: options.audit } : {}) }, signal);
+}
+
+export function hostControlServiceStatus(options: Pick<HostControlServiceOptions, 'platform' | 'uid' | 'username' | 'endpoint'> = {}): Readonly<{ endpoint: string; available: boolean; code: string | null }> {
+  const endpoint = hostControlServiceEndpoint(options);
+  const result = inspectHostControlEndpoint(endpoint, { uid: options.uid ?? process.getuid?.() });
+  return { endpoint, available: result.ok, code: result.code };
+}

package/lib/init.ts

@@ -61,6 +61,7 @@ const PLATFORM_DEFAULT_ENGINES = Object.freeze({
   darwin: 'colima',
   win32: 'wsl2'
 });
+const DEMO_PLATFORM_ENV = 'AGENT_INFRA_DEMO_PLATFORM';
 
 function detectProjectName(): string {
   try {
@@ -88,6 +89,12 @@ function detectOrgName(): string {
   return '';
 }
 
+function resolveInitPlatform(): NodeJS.Platform {
+  const override = process.env[DEMO_PLATFORM_ENV];
+  if (override === 'linux' || override === 'darwin' || override === 'win32') return override;
+  return platform();
+}
+
 const VALID_NAME_RE = /^[a-zA-Z0-9_.@-]+$/;
 
 function parseLocalSources(input: string): SourceEntry[] {
@@ -160,7 +167,7 @@ async function cmdInit(): Promise<void> {
     return;
   }
 
-  const currentPlatform = platform();
+  const currentPlatform = resolveInitPlatform();
   const defaultEngine = PLATFORM_DEFAULT_ENGINES[currentPlatform as keyof typeof PLATFORM_DEFAULT_ENGINES];
   const engineChoices = enginesForPlatform(currentPlatform).sort((left, right) => {
     if (left === defaultEngine) return -1;
@@ -288,6 +295,12 @@ async function cmdInit(): Promise<void> {
     replacements
   );
   ok('Installed .agents/scripts/lib/agent-infra-package.js');
+  renderFile(
+    path.join(templateDir, '.agents', 'scripts', 'package.json'),
+    path.join('.agents', 'scripts', 'package.json'),
+    replacements
+  );
+  ok('Installed .agents/scripts/package.json');
 
   const reconcileResult = applyAgentClientReconciliation(workflowPlan);
   for (const target of reconcileResult.applied) ok(`Installed ${target}`);
@@ -317,4 +330,4 @@ async function cmdInit(): Promise<void> {
   }
 }
 
-export { cmdInit };
+export { cmdInit, resolveInitPlatform };

package/lib/internal/agent-client.ts

@@ -9,6 +9,7 @@ import { normalizeCustomTUIs } from '../agent-clients/custom-tuis.ts';
 import { renderNextStepCommands } from '../agent-clients/next-steps.ts';
 import { getAgentClientModelSelection } from '../agent-clients/registry.ts';
 import { isAgentClientId } from '../agent-clients/types.ts';
+import { ensureInternalHandlerRoute, internalHandlerRoute } from './cli-route-inventory.ts';
 
 const USAGE = 'Usage: agent-infra-internal agent-client <next-steps|model-selection> [options]\n';
 
@@ -35,7 +36,7 @@ function parseArgs(args: string[]): ParsedArgs | null {
     process.stdout.write(USAGE);
     return null;
   }
-  if (args[0] !== 'next-steps') {
+  if (!internalHandlerRoute('agent-client', 'next-steps', args[0] ?? '')) {
     failure('AGENT_CLIENT_PAYLOAD_INVALID', "operation must be 'next-steps'");
     return null;
   }
@@ -84,7 +85,8 @@ function parseArgs(args: string[]): ParsedArgs | null {
 }
 
 function agentClient(args: string[] = []): void {
-  if (args[0] === 'model-selection') {
+  if (!ensureInternalHandlerRoute('agent-client', args)) return;
+  if (internalHandlerRoute('agent-client', 'model-selection', args[0] ?? '')) {
     const values: Record<string, string> = {};
     const seen = new Set<string>();
     for (let index = 1; index < args.length; index += 1) {

package/lib/internal/cli-route-inventory.ts

@@ -0,0 +1,142 @@
+export const PUBLIC_CLI_COMMAND_ALIASES = Object.freeze({
+  '': 'help',
+  s: 'sandbox',
+  t: 'task',
+  '--version': 'version',
+  '-v': 'version'
+} as const);
+
+export const PUBLIC_CLI_SELECTOR_ALIASES = Object.freeze({
+  task: Object.freeze({ d: 'decisions' })
+} as const);
+
+export const PUBLIC_CLI_ROUTE_SELECTORS = Object.freeze({
+  'agent-client': ['list', 'status', 'enable', 'disable', 'configure'],
+  cp: ['cp'],
+  data: ['capture', 'verify', 'audit', 'repair', 'export'],
+  decide: ['decide'],
+  help: ['help'],
+  init: ['init'],
+  merge: ['merge'],
+  run: ['create-task', 'task-skill', 'recreate'],
+  sandbox: ['create', 'exec', 'ls', 'show', 'prune', 'rebuild', 'refresh', 'rm', 'start', 'vm'],
+  server: ['start', 'stop', 'status', 'logs', '__daemon'],
+  task: ['cat', 'decisions', 'files', 'grep', 'issue-body', 'log', 'ls', 'show', 'status'],
+  sync: ['sync'],
+  update: ['update'],
+  version: ['version']
+} as const);
+
+/**
+ * The selector definitions consumed by every internal handler. Keep this
+ * module free of handler imports so the pre-import task-view guard remains
+ * effective.
+ */
+export const INTERNAL_HANDLER_ROUTE_SELECTORS = Object.freeze({
+  'task-create': ['input'],
+  'task-qualification': ['proposal', 'confirm', 'supersede', 'revoke'],
+  'sandbox-control': ['serve', 'execute', 'recover', 'client'],
+  'host-control': ['serve', 'status', 'install', 'uninstall'],
+  'agent-client': ['next-steps', 'model-selection'],
+  'codex-lifecycle': ['preflight', 'capability-arm', 'hook-event', 'resolve-start', 'resolve-stop', 'consume'],
+  'codex-sandbox-controller': ['verify-context', 'run'],
+  'git-workflow': ['inspect', 'preview-tree', 'snapshot', 'compare-trees', 'commit', 'push-rebased'],
+  'task-delivery': ['deliver'],
+  'release-workflow': ['inspect', 'prepare', 'publish', 'post-prepare', 'post-publish'],
+  'platform-release-notes': ['context', 'stage', 'publish'],
+  'platform-security': ['read', 'dismiss'],
+  'platform-metadata': ['init-labels', 'init-milestones'],
+  'platform-context': ['resolve'],
+  'platform-comment': ['list', 'owner', 'backfill', 'sync'],
+  'platform-issue': ['inspect', 'create', 'bind', 'sync'],
+  'platform-pr': ['inspect', 'summary-context', 'resolve-external', 'create', 'bind', 'skip', 'sync', 'change-report', 'summary-sync', 'sync-in-labels'],
+  'platform-pr-review': ['inspect', 'list', 'publish-pr', 'publish-task'],
+  'pr-review-grade': ['decide', 'resolve-host', 'verify-artifact'],
+  'platform-checks': ['inspect', 'watch', 'resolve-run', 'logs'],
+  'task-context': ['resolve'],
+  'task-ledger': ['decision-next-id', 'stage-status', 'finding-upsert', 'finding-respond', 'finding-review', 'decision-upsert', 'rework-intent-upsert'],
+  'task-warning': ['list', 'add', 'set-status'],
+  'task-activity': ['pr-review-inspect', 'pr-review-start', 'pr-review-complete', 'pr-review-terminate'],
+  'task-artifact': ['inspect', 'init', 'repair', 'finalize-local'],
+  'task-orchestration': ['status', 'progress'],
+  'task-review': ['finalize-summary'],
+  'task-event': ['event'],
+  'task-invalidation': ['reconcile'],
+  'task-override': ['diagnose', 'issue', 'consume'],
+  'task-lifecycle': ['intent'],
+  'task-finalization': ['complete'],
+  'task-short-id': ['list', 'list-verify', 'alloc', 'release', 'resolve'],
+  'task-snapshot': ['snapshot'],
+  'task-verify': ['event'],
+  'task-validate': ['snapshot', 'inplace'],
+  'manual-validation': ['transaction']
+} as const);
+
+export const INTERNAL_CLI_ROUTE_SELECTORS = INTERNAL_HANDLER_ROUTE_SELECTORS;
+
+function first(args: readonly string[]): string {
+  return args[0] ?? '';
+}
+
+function optionValue(args: readonly string[], name: string): string | undefined {
+  const index = args.indexOf(name);
+  if (index >= 0) return args[index + 1];
+  const prefix = `${name}=`;
+  return args.find((arg) => arg.startsWith(prefix))?.slice(prefix.length);
+}
+
+export function internalRouteSelector(command: string, args: readonly string[]): string {
+  if (command === 'sandbox-control') return first(args);
+  if (command === 'task-create') return 'input';
+  if (command === 'task-qualification') return args[1] ?? '';
+  if (command === 'task-lifecycle') return args[1] ? 'intent' : '';
+  if (command === 'task-finalization') return args[1] === 'complete' ? 'complete' : '';
+  if (command === 'task-event') return args[1] ? 'event' : '';
+  if (command === 'task-verify') return args[0] && args[1] ? 'event' : '';
+  if (command === 'task-snapshot') return 'snapshot';
+  if (command === 'task-validate') return optionValue(args, '--scope') ?? 'snapshot';
+  if (command === 'task-short-id') return first(args) === 'list' && args.includes('--verify') ? 'list-verify' : first(args);
+  if (command === 'task-orchestration') return args[1] === 'status' ? 'status' : args[1] ? 'progress' : '';
+  if (command === 'task-review') return args[1] ?? '';
+  if (command === 'task-invalidation') return args[1] ?? '';
+  if (command === 'task-override') return args[1] ?? '';
+  if (command === 'task-artifact') return args[1] ?? '';
+  if (command === 'platform-pr-review' && first(args) === 'publish') {
+    const scope = optionValue(args, '--scope') ?? '';
+    return /^TASK-\d{8}-\d{6}$/u.test(scope) ? 'publish-task' : /^pr\d+$/u.test(scope) ? 'publish-pr' : '';
+  }
+  if (['task-ledger', 'task-warning', 'task-activity'].includes(command)) return args[1] ?? '';
+  if (command === 'task-delivery') return args[1] ?? '';
+  if (command === 'task-context') return first(args);
+  return first(args);
+}
+
+export function isInternalHandlerRoute(command: string, args: readonly string[]): boolean {
+  if (args[0] === '--help' || args[0] === '-h') return true;
+  const selector = internalRouteSelector(command, args);
+  const selectors = INTERNAL_HANDLER_ROUTE_SELECTORS[command as keyof typeof INTERNAL_HANDLER_ROUTE_SELECTORS];
+  return Boolean(selector && selectors?.some((candidate) => candidate === selector));
+}
+
+/**
+ * Marks a selector at the handler's actual dispatch branch.
+ *
+ * The call is intentionally side-effect free so the top-level task-view guard
+ * can still run before a handler module is imported. Route coverage tests read
+ * these branch markers independently from the pre-import inventory.
+ */
+export function internalHandlerRoute(command: string, selector: string, actualSelector: string): boolean {
+  return command.length > 0 && selector === actualSelector;
+}
+
+export function ensureInternalHandlerRoute(command: string, args: readonly string[]): boolean {
+  if (isInternalHandlerRoute(command, args)) return true;
+  const selector = internalRouteSelector(command, args);
+  process.stdout.write(`${JSON.stringify({
+    status: 'failed',
+    changed: false,
+    error: { code: 'INTERNAL_ROUTE_UNREGISTERED', message: `operation '${command} ${selector || first(args)}' is not registered` }
+  })}\n`);
+  process.exitCode = 1;
+  return false;
+}

package/lib/internal/codex-lifecycle.ts

@@ -22,6 +22,7 @@ import {
   sealCodexOrchestrationDelegation,
   sealCodexParentDelegation
 } from '../task/codex-orchestration.ts';
+import { ensureInternalHandlerRoute, internalHandlerRoute } from './cli-route-inventory.ts';
 
 const USAGE = 'Usage: agent-infra-internal codex-lifecycle <capability-arm|hook-event|resolve-start|resolve-stop|preflight|consume> [options]\n';
 const MANAGED_AGENT = /^agent-infra-lifecycle-(executor|reviewer)$/;
@@ -162,10 +163,11 @@ function payloadText(payload: unknown, key: string): string {
 }
 
 async function codexLifecycle(args: string[] = []): Promise<void> {
+  if (!ensureInternalHandlerRoute('codex-lifecycle', args)) return;
   const parsed = parse(args);
   if (!parsed || process.exitCode) return;
   try {
-    if (parsed.operation === 'preflight') {
+    if (internalHandlerRoute('codex-lifecycle', 'preflight', parsed.operation)) {
       const format = parsed.values['--format'] ?? 'json';
       if (!['text', 'json'].includes(format)) throw new Error("format must be 'text' or 'json'");
       const runtimeFields = [
@@ -188,7 +190,7 @@ async function codexLifecycle(args: string[] = []): Promise<void> {
       return;
     }
 
-    if (parsed.operation === 'capability-arm') {
+    if (internalHandlerRoute('codex-lifecycle', 'capability-arm', parsed.operation)) {
       const taskId = parsed.values['--task-id'];
       if (!taskId) throw new Error('capability-arm requires --task-id');
       const resolved = resolveTaskRef(taskId, { repoRoot: process.cwd() });
@@ -201,7 +203,7 @@ async function codexLifecycle(args: string[] = []): Promise<void> {
       output({
         status: 'armed',
         changed: true,
-        capabilityToken: armed.token,
+        capabilityRef: armed.capabilityRef,
         marker: armed.marker,
         expiresAt: armed.expiresAt,
         buildIdentity: armed.buildIdentity,
@@ -211,7 +213,7 @@ async function codexLifecycle(args: string[] = []): Promise<void> {
     }
 
     const store = createCodexLifecycleStore({ cliVersion: cliVersion() });
-    if (parsed.operation === 'hook-event') {
+    if (internalHandlerRoute('codex-lifecycle', 'hook-event', parsed.operation)) {
       const phase = parsed.values['--event'];
       if (!phase || !['pre-tool', 'subagent-start', 'post-tool', 'subagent-stop'].includes(phase)) {
         throw new Error('hook-event requires a known --event');
@@ -221,12 +223,12 @@ async function codexLifecycle(args: string[] = []): Promise<void> {
       }
       const payload = await readStdin();
       if (phase === 'post-tool') {
-        const capabilityToken = payloadText(payload, 'capabilityToken');
-        if (capabilityToken) {
+        const capabilityRef = payloadText(payload, 'capabilityRef');
+        if (capabilityRef) {
           const capabilityStore = createCodexCapabilityStore();
-          const armed = capabilityStore.inspect(capabilityToken);
-          const capability = createCodexCapabilityStore().attest({
-            token: capabilityToken,
+          const armed = capabilityStore.inspectReference(capabilityRef);
+          const capability = capabilityStore.attestByReference({
+            capabilityRef,
             sessionId: payloadText(payload, 'sessionId'),
             turnId: payloadText(payload, 'turnId'),
             toolUseId: payloadText(payload, 'toolUseId'),
@@ -348,7 +350,7 @@ async function codexLifecycle(args: string[] = []): Promise<void> {
 
     const childThreadId = parsed.values['--child-id'];
     if (!childThreadId) throw new Error(`operation '${parsed.operation}' requires --child-id`);
-    if (parsed.operation === 'resolve-start') {
+    if (internalHandlerRoute('codex-lifecycle', 'resolve-start', parsed.operation)) {
       if (store.read(childThreadId).state.spawn?.hookDefinitionHash !== hookDefinitionHash()) {
         throw new Error('Codex lifecycle hook definition hash is stale');
       }
@@ -360,7 +362,7 @@ async function codexLifecycle(args: string[] = []): Promise<void> {
       if (latest.state.status !== 'start-ready') process.exitCode = 1;
       return;
     }
-    if (parsed.operation === 'resolve-stop') {
+    if (internalHandlerRoute('codex-lifecycle', 'resolve-stop', parsed.operation)) {
       const stopTurnId = store.read(childThreadId).state.stop?.turnId;
       if (!stopTurnId) throw new Error('Codex lifecycle stop hook is not available');
       const terminal = await resolveCodexTerminal(childThreadId, stopTurnId);
@@ -371,7 +373,7 @@ async function codexLifecycle(args: string[] = []): Promise<void> {
       output({ status: latest.state.status, changed: true, evidence: latest.state.stopEvidence, diagnostics: [], error: latest.state.error });
       return;
     }
-    if (parsed.operation === 'consume') {
+    if (internalHandlerRoute('codex-lifecycle', 'consume', parsed.operation)) {
       const consumer = parsed.values['--consumer'];
       if (!consumer) throw new Error('consume requires --consumer');
       const consumed = store.consume(childThreadId, consumer, hookDefinitionHash());

package/lib/internal/codex-sandbox-controller.ts

@@ -2,6 +2,7 @@ import {
   runCodexSandboxController,
   verifyCodexSandboxControllerContextWithWarnings
 } from '../agent-clients/adapters/codex-lifecycle/sandbox-controller.ts';
+import { ensureInternalHandlerRoute, internalHandlerRoute } from './cli-route-inventory.ts';
 
 const USAGE = 'Usage: agent-infra-internal codex-sandbox-controller <run|verify-context> [options]\n';
 
@@ -20,7 +21,10 @@ function parse(args: string[]): Readonly<{ operation: string; values: Readonly<R
     return null;
   }
   const operation = args[0];
-  if (!operation || !['run', 'verify-context'].includes(operation)) {
+  if (!operation || ![
+    internalHandlerRoute('codex-sandbox-controller', 'run', operation),
+    internalHandlerRoute('codex-sandbox-controller', 'verify-context', operation)
+  ].some(Boolean)) {
     process.stderr.write(USAGE);
     fail('CODEX_SANDBOX_CONTROLLER_PAYLOAD_INVALID', 'operation must be run or verify-context', 2);
     return null;
@@ -51,10 +55,11 @@ function parse(args: string[]): Readonly<{ operation: string; values: Readonly<R
 }
 
 async function codexSandboxController(args: string[] = []): Promise<void> {
+  if (!ensureInternalHandlerRoute('codex-sandbox-controller', args)) return;
   const parsed = parse(args);
   if (!parsed || process.exitCode) return;
   try {
-    if (parsed.operation === 'verify-context') {
+    if (internalHandlerRoute('codex-sandbox-controller', 'verify-context', parsed.operation)) {
       const contextPath = parsed.values['--context']
         ?? process.env.AGENT_INFRA_CODEX_CONTROLLER_CONTEXT;
       if (!contextPath) throw new Error('CODEX_SANDBOX_CONTROLLER_CONTEXT_MISSING');