@fitlab-ai/agent-infra 0.9.9 → 0.9.11

package/lib/self-update.ts

@@ -0,0 +1,341 @@
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { err, info, ok } from './log.ts';
+import { needsShell, resolveCommandFromAbsolutePath } from './run/host.ts';
+
+type CommandResult = {
+  status: number | null;
+  signal?: NodeJS.Signals | null;
+  stdout?: string;
+  stderr?: string;
+  error?: Error;
+};
+
+export type SelfUpdateOptions = Readonly<{
+  platform?: NodeJS.Platform;
+  env?: NodeJS.ProcessEnv;
+  argv?: readonly string[];
+  run?: (command: readonly string[]) => CommandResult;
+}>;
+
+export type UpdateSource = Readonly<{
+  kind: 'npm' | 'brew';
+  managerPath: string;
+  packageRoot: string;
+  updateArgs: readonly string[];
+}>;
+
+export type UpdateSourceResult = Readonly<{
+  source: UpdateSource | null;
+  error?: string;
+}>;
+
+type PackageInfo = Readonly<{
+  root: string;
+  name: string;
+}>;
+
+function canonicalPath(target: string): string | null {
+  try {
+    return fs.realpathSync.native(target);
+  } catch {
+    return null;
+  }
+}
+
+function comparable(target: string, platform: NodeJS.Platform): string {
+  const resolved = path.resolve(target).replaceAll('\\', '/');
+  return platform === 'win32' ? resolved.toLowerCase() : resolved;
+}
+
+function samePath(left: string, right: string, platform: NodeJS.Platform): boolean {
+  return comparable(left, platform) === comparable(right, platform);
+}
+
+function isWithin(root: string, target: string, platform: NodeJS.Platform): boolean {
+  const normalizedRoot = comparable(root, platform).replace(/\/$/, '');
+  const normalizedTarget = comparable(target, platform).replace(/\/$/, '');
+  return normalizedTarget === normalizedRoot
+    || normalizedTarget.startsWith(`${normalizedRoot}/`);
+}
+
+function packageInfoFromRoot(root: string): PackageInfo | null {
+  try {
+    const packageJson = JSON.parse(
+      fs.readFileSync(path.join(root, 'package.json'), 'utf8')
+    ) as { name?: unknown };
+    return typeof packageJson.name === 'string'
+      ? { root, name: packageJson.name }
+      : null;
+  } catch {
+    return null;
+  }
+}
+
+function findPackageInfo(entry: string, platform: NodeJS.Platform): PackageInfo | null {
+  const canonicalEntry = canonicalPath(entry);
+  if (!canonicalEntry) return null;
+
+  let current = path.dirname(canonicalEntry);
+  while (true) {
+    const canonicalRoot = canonicalPath(current);
+    const info = canonicalRoot ? packageInfoFromRoot(canonicalRoot) : null;
+    if (info && isWithin(info.root, canonicalEntry, platform)) return info;
+    const parent = path.dirname(current);
+    if (parent === current) return null;
+    current = parent;
+  }
+}
+
+function packageInfoFromCommand(commandPath: string, platform: NodeJS.Platform): PackageInfo | null {
+  const direct = findPackageInfo(commandPath, platform);
+  if (direct) return direct;
+  if (!/\.(?:cmd|bat)$/i.test(commandPath)) return null;
+
+  const globalPackageRoot = canonicalPath(path.join(
+    path.dirname(commandPath),
+    'node_modules',
+    '@fitlab-ai',
+    'agent-infra'
+  ));
+  return globalPackageRoot ? packageInfoFromRoot(globalPackageRoot) : null;
+}
+
+function visibleAliasError(
+  packageRoot: string,
+  platform: NodeJS.Platform,
+  env: NodeJS.ProcessEnv
+): string | null {
+  for (const alias of ['ai', 'agent-infra']) {
+    const absolute = resolveCommandFromAbsolutePath(alias, platform, env);
+    if (!absolute) continue;
+    if (!canonicalPath(absolute)) continue;
+    const info = packageInfoFromCommand(absolute, platform);
+    if (info && !samePath(info.root, packageRoot, platform)) {
+      return `PATH shadowing detected: ${alias} resolves to ${info.root}, not ${packageRoot}.`;
+    }
+  }
+  return null;
+}
+
+function resolveManager(
+  name: string,
+  expectedBasenames: readonly string[],
+  platform: NodeJS.Platform,
+  env: NodeJS.ProcessEnv
+): { path: string } | { error: string } | null {
+  const absolute = resolveCommandFromAbsolutePath(name, platform, env);
+  if (!absolute) {
+    return { error: `${name} manager was not found on PATH.` };
+  }
+  let stat: fs.Stats;
+  try {
+    stat = fs.statSync(absolute);
+  } catch {
+    return { error: `Cannot inspect manager executable: ${absolute}.` };
+  }
+  if (!stat.isFile()) return { error: `Manager executable is not a regular file: ${absolute}.` };
+  if (!expectedBasenames.includes(path.basename(absolute).toLowerCase())) {
+    return { error: `Unexpected manager executable: ${absolute}.` };
+  }
+  const canonical = canonicalPath(absolute);
+  return canonical ? { path: canonical } : null;
+}
+
+function defaultRun(command: readonly string[], platform: NodeJS.Platform): CommandResult {
+  const [file, ...args] = command;
+  if (!file) return { status: null, error: new Error('run: missing command') };
+  const result = spawnSync(file, args, {
+    encoding: 'utf8',
+    shell: needsShell(file, platform),
+    stdio: ['ignore', 'pipe', 'pipe']
+  });
+  return {
+    status: result.status,
+    signal: result.signal,
+    stdout: result.stdout || '',
+    stderr: result.stderr || '',
+    error: result.error
+  };
+}
+
+function runCommand(
+  command: readonly string[],
+  options: SelfUpdateOptions,
+  platform: NodeJS.Platform
+): CommandResult {
+  return options.run ? options.run(command) : defaultRun(command, platform);
+}
+
+function probe(
+  command: readonly string[],
+  options: SelfUpdateOptions,
+  platform: NodeJS.Platform,
+  label: string
+): string | { error: string } {
+  const result = runCommand(command, options, platform);
+  if (result.error) return { error: `${label} failed: ${result.error.message}` };
+  if (result.signal) return { error: `${label} terminated by ${result.signal}.` };
+  if (result.status !== 0) {
+    const detail = result.stderr?.trim();
+    return { error: `${label} exited with ${result.status ?? 1}${detail ? `: ${detail}` : '.'}` };
+  }
+  const output = result.stdout?.trim() || '';
+  return output ? output : { error: `${label} returned no path.` };
+}
+
+function npmSource(
+  packageInfo: PackageInfo,
+  options: SelfUpdateOptions,
+  platform: NodeJS.Platform,
+  env: NodeJS.ProcessEnv
+): UpdateSource | { error: string } | null {
+  const manager = resolveManager(
+    'npm',
+    platform === 'win32' ? ['npm.cmd', 'npm.bat'] : ['npm'],
+    platform,
+    env
+  );
+  if (!manager) return null;
+  if ('error' in manager) return manager;
+
+  const prefixOutput = probe([manager.path, 'prefix', '--global'], options, platform, 'npm prefix --global');
+  if (typeof prefixOutput !== 'string') return prefixOutput;
+  const rootOutput = probe([manager.path, 'root', '--global'], options, platform, 'npm root --global');
+  if (typeof rootOutput !== 'string') return rootOutput;
+  const prefix = canonicalPath(prefixOutput);
+  const globalRoot = canonicalPath(rootOutput);
+  if (!prefix || !globalRoot) return { error: 'npm global prefix or root is not an existing directory.' };
+  if (!isWithin(prefix, globalRoot, platform)) {
+    return { error: `npm global root ${globalRoot} is outside prefix ${prefix}.` };
+  }
+  const expectedPackageRoot = canonicalPath(path.join(globalRoot, '@fitlab-ai', 'agent-infra'));
+  if (!expectedPackageRoot || !samePath(expectedPackageRoot, packageInfo.root, platform)) {
+    return { error: `Current CLI package is not owned by npm global root ${globalRoot}.` };
+  }
+  if (packageInfo.name !== '@fitlab-ai/agent-infra') {
+    return { error: `Unexpected package name at ${packageInfo.root}: ${packageInfo.name}.` };
+  }
+  if (platform !== 'win32' && !isWithin(prefix, manager.path, platform)) {
+    return { error: `npm manager ${manager.path} is outside global prefix ${prefix}.` };
+  }
+  return {
+    kind: 'npm',
+    managerPath: manager.path,
+    packageRoot: packageInfo.root,
+    updateArgs: ['update', '--global', '@fitlab-ai/agent-infra']
+  };
+}
+
+function brewSource(
+  packageInfo: PackageInfo,
+  options: SelfUpdateOptions,
+  platform: NodeJS.Platform,
+  env: NodeJS.ProcessEnv
+): UpdateSource | { error: string } | null {
+  const manager = resolveManager('brew', ['brew', 'brew.exe', 'brew.cmd'], platform, env);
+  if (!manager) return null;
+  if ('error' in manager) return manager;
+
+  const homebrewOutput = probe([manager.path, '--prefix'], options, platform, 'brew --prefix');
+  if (typeof homebrewOutput !== 'string') return homebrewOutput;
+  const formulaOutput = probe([manager.path, '--prefix', 'agent-infra'], options, platform, 'brew --prefix agent-infra');
+  if (typeof formulaOutput !== 'string') return formulaOutput;
+  const homebrewRoot = canonicalPath(homebrewOutput);
+  const formulaRoot = canonicalPath(formulaOutput);
+  if (!homebrewRoot || !formulaRoot) return { error: 'Homebrew prefix is not an existing directory.' };
+  if (!isWithin(homebrewRoot, manager.path, platform)) {
+    return { error: `brew manager ${manager.path} is outside Homebrew prefix ${homebrewRoot}.` };
+  }
+  if (!isWithin(homebrewRoot, formulaRoot, platform)) {
+    return { error: `agent-infra formula prefix ${formulaRoot} is outside Homebrew prefix ${homebrewRoot}.` };
+  }
+  if (!isWithin(formulaRoot, packageInfo.root, platform)) {
+    return { error: `Current CLI package is outside agent-infra formula prefix ${formulaRoot}.` };
+  }
+  if (packageInfo.name !== '@fitlab-ai/agent-infra') {
+    return { error: `Unexpected package name at ${packageInfo.root}: ${packageInfo.name}.` };
+  }
+  return {
+    kind: 'brew',
+    managerPath: manager.path,
+    packageRoot: packageInfo.root,
+    updateArgs: ['upgrade', 'agent-infra']
+  };
+}
+
+export function detectUpdateSource(options: SelfUpdateOptions = {}): UpdateSourceResult {
+  const platform = options.platform ?? process.platform;
+  const env = options.env ?? process.env;
+  const entry = options.argv?.[1] ?? process.argv[1];
+  if (!entry) return { source: null, error: 'Cannot determine the running CLI entry.' };
+  const packageInfo = findPackageInfo(entry, platform);
+  if (!packageInfo || packageInfo.name !== '@fitlab-ai/agent-infra') {
+    return { source: null, error: 'Running CLI is not a persistent @fitlab-ai/agent-infra package installation.' };
+  }
+  const aliasError = visibleAliasError(packageInfo.root, platform, env);
+  if (aliasError) return { source: null, error: aliasError };
+
+  const candidates: UpdateSource[] = [];
+  const errors: string[] = [];
+  for (const candidate of [
+    npmSource(packageInfo, options, platform, env),
+    brewSource(packageInfo, options, platform, env)
+  ]) {
+    if (!candidate) continue;
+    if ('error' in candidate) errors.push(candidate.error);
+    else candidates.push(candidate);
+  }
+  if (candidates.length === 1) {
+    const [source] = candidates;
+    if (source) return { source };
+  }
+  if (candidates.length > 1) return { source: null, error: 'Multiple package managers claim the running CLI; refusing to choose.' };
+  return {
+    source: null,
+    error: errors.length > 0
+      ? errors.join(' ')
+      : 'No supported persistent npm or Homebrew installation owns the running CLI.'
+  };
+}
+
+function managerStable(source: UpdateSource, platform: NodeJS.Platform): boolean {
+  const current = canonicalPath(source.managerPath);
+  return current !== null && samePath(current, source.managerPath, platform);
+}
+
+export async function cmdUpdate(options: SelfUpdateOptions = {}): Promise<number> {
+  const platform = options.platform ?? process.platform;
+  const detected = detectUpdateSource(options);
+  if (!detected.source) {
+    err(`Cannot update agent-infra CLI: ${detected.error ?? 'unknown source'}`);
+    err('Install persistently with "npm install -g @fitlab-ai/agent-infra" or "brew install fitlab-ai/tap/agent-infra".');
+    return 1;
+  }
+
+  const source = detected.source;
+  if (!managerStable(source, platform)) {
+    err(`Cannot update agent-infra CLI: manager path changed: ${source.managerPath}.`);
+    return 1;
+  }
+  info(`Updating agent-infra CLI via ${source.kind}.`);
+  const result = runCommand([source.managerPath, ...source.updateArgs], options, platform);
+  if (result.error) {
+    err(`agent-infra CLI update failed: ${result.error.message}`);
+    return 1;
+  }
+  if (result.signal) {
+    err(`agent-infra CLI update terminated by ${result.signal}.`);
+    return 1;
+  }
+  if (result.status !== 0) {
+    err(`agent-infra CLI update failed with exit code ${result.status ?? 1}.`);
+    const detail = result.stderr?.trim();
+    if (detail) err(detail);
+    return result.status && result.status > 0 ? result.status : 1;
+  }
+  ok('agent-infra CLI updated successfully!');
+  return 0;
+}

package/lib/server/protocol.ts

@@ -31,16 +31,16 @@ export function commandHelp(): string {
     '/sandbox ls',
     '/sandbox show {ref}',
     '/sandbox vm status',
-    '/task decisions [--task {ref}] [--item {selector}]',
-    '/task log [--task {ref}]',
+    '/task decisions [--task {ref} | -t {ref}] [--item {selector} | -i {selector}]',
+    '/task log [--task {ref} | -t {ref}]',
     '/task ls',
-    '/task show [--task {ref}]',
-    '/task status [--task {ref}]',
+    '/task show [--task {ref} | -t {ref}]',
+    '/task status [--task {ref} | -t {ref}]',
     'Write:',
     '/sandbox create {ref}',
     '/sandbox start {ref}',
     'Exec:',
-    '/decide [--task {ref}] --item {ordinal|ledger-id} [--needs-implementation true|false] {decision}',
+    '/decide [--task {ref} | -t {ref}] (--item {ordinal|ledger-id} | -i {ordinal|ledger-id}) [--needs-implementation true|false] {decision}',
     '/run create-task {description}',
     '/run {skill} {task-ref}'
   ].join('\n');

package/lib/task/activity-log.ts

@@ -89,6 +89,10 @@ function pairEntries(entries: LogEntry[]): StepRow[] {
   return rows;
 }
 
+function startedBackedRows(rows: StepRow[]): StepRow[] {
+  return rows.filter((row) => row.started !== '');
+}
+
 export {
   activityAttempt,
   appendActivityEntry,
@@ -96,6 +100,7 @@ export {
   locateActivityLog,
   pairEntries,
   parseActivityLog,
-  parseCommitAttemptStarted
+  parseCommitAttemptStarted,
+  startedBackedRows
 };
 export type { ActivityLogSection, CommitAttempt, LogEntry, StepRow };

package/lib/task/artifact-lifecycle.ts

@@ -46,7 +46,8 @@ type ArtifactErrorCode =
   | 'ARTIFACT_TOPOLOGY_CONFLICT' | 'ARTIFACT_INPUT_MISSING'
   | 'ARTIFACT_REFERENCE_INVALID' | 'ARTIFACT_PATH_INVALID'
   | 'ARTIFACT_IDENTITY_INVALID' | 'ARTIFACT_NOT_FOUND'
-  | 'ARTIFACT_NOT_REGULAR' | 'ARTIFACT_NOT_READABLE' | 'ARTIFACT_MODE_REFUSED';
+  | 'ARTIFACT_NOT_REGULAR' | 'ARTIFACT_NOT_READABLE' | 'ARTIFACT_VERDICT_INVALID'
+  | 'ARTIFACT_MODE_REFUSED';
 type ArtifactError = { code: ArtifactErrorCode; message: string };
 type ArtifactInventoryResult = {
   status: 'ready' | 'failed';
@@ -357,7 +358,7 @@ function resolveCodeContext(inventory: ArtifactInventoryResult, options: Inspect
       return contextFailure(inventory, 'ARTIFACT_INPUT_MISSING', `latest plan '${plan.latest.name}' requires a matching approved review-plan`);
     }
     const verdict = parseVerdict(reviewPlan.latest.path);
-    if (!verdict.ok) return contextFailure(inventory, 'ARTIFACT_REFERENCE_INVALID', verdict.message, reviewPlan.latest.name);
+    if (!verdict.ok) return contextFailure(inventory, 'ARTIFACT_VERDICT_INVALID', `${verdict.code}: ${verdict.message}`, reviewPlan.latest.name);
     if (verdict.verdict !== 'Approved') {
       return contextFailure(inventory, 'ARTIFACT_REFERENCE_INVALID', `latest ${reviewPlan.latest.name} is not approved`, reviewPlan.latest.name);
     }
@@ -373,6 +374,7 @@ function resolveCodeContext(inventory: ArtifactInventoryResult, options: Inspect
   }
   if (reviewPlan.latest && reviewPlan.reviewedInput?.name === plan.latest.name) {
     const verdict = parseVerdict(reviewPlan.latest.path);
+    if (!verdict.ok) return contextFailure(inventory, 'ARTIFACT_VERDICT_INVALID', `${verdict.code}: ${verdict.message}`, reviewPlan.latest.name);
     const reviewedPlanSha256 = sha256File(reviewPlan.reviewedInput.path);
     if (verdict.ok && verdict.verdict === 'Approved' && (
       codePlanInput.input.name !== plan.latest.name || codePlanInput.inputSha256 !== reviewedPlanSha256
@@ -388,7 +390,7 @@ function resolveCodeContext(inventory: ArtifactInventoryResult, options: Inspect
   const review = reviewCode.latest;
   if (!review) return contextFailure(inventory, 'ARTIFACT_INPUT_MISSING', 'latest review-code artifact is required');
   const verdict = parseVerdict(review.path);
-  if (!verdict.ok) return contextFailure(inventory, 'ARTIFACT_REFERENCE_INVALID', verdict.message);
+  if (!verdict.ok) return contextFailure(inventory, 'ARTIFACT_VERDICT_INVALID', `${verdict.code}: ${verdict.message}`, review.name);
   if (verdict.verdict === 'Approved') {
     const decision = resolveDecisionImplementationInput(inventory, review);
     if ('error' in decision) return contextFailure(inventory, 'ARTIFACT_REFERENCE_INVALID', decision.error, review.name);

package/lib/task/codex-orchestration.ts

@@ -10,10 +10,16 @@ import {
   isCodexCapabilityProvenanceDetail
 } from '../agent-clients/adapters/codex-lifecycle/capability-store.ts';
 import type { CodexCapabilityProvenanceDetail } from '../agent-clients/adapters/codex-lifecycle/capability-store.ts';
-import { computeLifecycleBuildIdentity } from '../agent-clients/adapters/codex-lifecycle/build-identity.ts';
-import type { LifecycleBuildIdentity } from '../agent-clients/adapters/codex-lifecycle/build-identity.ts';
-import { verifyCodexSandboxControllerContext } from '../agent-clients/adapters/codex-lifecycle/sandbox-controller.ts';
-import { verifyCodexSandboxControllerContext as verifyControllerContextFile } from '../agent-clients/adapters/codex-lifecycle/controller-context.ts';
+import {
+  computeLifecycleBuildIdentity,
+  verifyLifecycleBuildIdentity,
+  type LifecycleBuildIdentity,
+  type LifecycleIdentityWarning
+} from '../agent-clients/adapters/codex-lifecycle/build-identity.ts';
+import { verifyCodexSandboxControllerContextWithWarnings as verifySandboxControllerWithWarnings } from '../agent-clients/adapters/codex-lifecycle/sandbox-controller.ts';
+import {
+  verifyCodexSandboxControllerContextWithWarnings as verifyControllerContextFileWithWarnings
+} from '../agent-clients/adapters/codex-lifecycle/controller-context.ts';
 import type { AgentClientId } from '../agent-clients/types.ts';
 import { resolveTaskRef } from './resolve-ref.ts';
 import {
@@ -39,6 +45,7 @@ type CodexBridgeOptions = Readonly<{
   capabilityStore?: CapabilityStore;
   buildIdentity?: LifecycleBuildIdentity;
   orchestrationOptions?: OrchestrationOptions;
+  controllerBinding?: Readonly<{ instanceDigest: string; controlGeneration: string }>;
 }>;
 
 type CodexSpawnIdentity = Readonly<{
@@ -92,35 +99,6 @@ function requiredStore(options: CodexBridgeOptions): LifecycleStore {
   return options.store;
 }
 
-function controllerContext(
-  repoRoot: string,
-  brokerController: Readonly<{ instanceDigest: string; controlGeneration: string }> | null
-) {
-  const contextPath = process.env.AGENT_INFRA_CODEX_CONTROLLER_CONTEXT;
-  if (!contextPath) return null;
-  if (brokerController) {
-    return verifyControllerContextFile(contextPath, {
-      repoRoot,
-      generation: process.env.AGENT_INFRA_CONTROL_GENERATION ?? brokerController.controlGeneration
-    });
-  }
-  return verifyCodexSandboxControllerContext(contextPath, { repoRoot });
-}
-
-function brokerBindingConflictsWithContext(
-  repoRoot: string,
-  brokerController: Readonly<{ instanceDigest: string; controlGeneration: string }> | null
-): boolean {
-  const contextPath = process.env.AGENT_INFRA_CODEX_CONTROLLER_CONTEXT;
-  if (!contextPath || !brokerController) return false;
-  const context = verifyControllerContextFile(contextPath, {
-    repoRoot,
-    generation: process.env.AGENT_INFRA_CONTROL_GENERATION ?? brokerController.controlGeneration
-  });
-  return context.controllerInstanceDigest !== brokerController.instanceDigest
-    || context.controlGeneration !== brokerController.controlGeneration;
-}
-
 function brokerControllerBinding(): Readonly<{ instanceDigest: string; controlGeneration: string }> | null {
   const raw = process.env.AGENT_INFRA_CONTROL_CONTROLLER_BINDING;
   if (!raw) return null;
@@ -165,14 +143,18 @@ async function prepareCodexOrchestrationDelegation(
       );
     }
     const buildIdentity = options.buildIdentity ?? computeLifecycleBuildIdentity(repoRoot);
-    const brokerController = brokerControllerBinding();
-    if (brokerBindingConflictsWithContext(repoRoot, brokerController)) {
-      return bridgeFailure(
-        'CODEX_SANDBOX_CONTROLLER_BINDING_MISMATCH',
-        'broker and local controller bindings do not match'
-      );
-    }
-    const localController = controllerContext(repoRoot, brokerController);
+    const brokerController = options.controllerBinding ?? brokerControllerBinding();
+    const contextPath = process.env.AGENT_INFRA_CODEX_CONTROLLER_CONTEXT;
+    const contextVerification = contextPath
+      ? (brokerController
+        ? verifyControllerContextFileWithWarnings(contextPath, {
+            repoRoot,
+            generation: process.env.AGENT_INFRA_CONTROL_GENERATION ?? brokerController.controlGeneration
+          })
+        : verifySandboxControllerWithWarnings(contextPath, { repoRoot }))
+      : null;
+    const identityWarnings: LifecycleIdentityWarning[] = [...(contextVerification?.warnings ?? [])];
+    const localController = contextVerification?.context ?? null;
     if (localController && brokerController
       && (localController.controllerInstanceDigest !== brokerController.instanceDigest
         || localController.controlGeneration !== brokerController.controlGeneration)) {
@@ -187,6 +169,11 @@ async function prepareCodexOrchestrationDelegation(
     } : null);
     const capabilityStore = options.capabilityStore ?? createCodexCapabilityStore();
     const attested = capabilityStore.inspect(input.capabilityToken);
+    const capabilityIdentity = verifyLifecycleBuildIdentity(attested.buildIdentity, buildIdentity);
+    if (!capabilityIdentity.ok) {
+      return bridgeFailure(capabilityIdentity.code!, capabilityIdentity.message!);
+    }
+    identityWarnings.push(...capabilityIdentity.warnings);
     const lifecycleProvenance = {
       ...attested.buildIdentity,
       hookDefinitionHash: preflight.hookDefinitionHash,
@@ -206,7 +193,7 @@ async function prepareCodexOrchestrationDelegation(
         controlGeneration: controller.controlGeneration
       } } : {})
     };
-    return prepareOrchestrationDelegation(taskRef, {
+    const prepared = prepareOrchestrationDelegation(taskRef, {
       ...input,
       lifecycleProvenance
     }, {
@@ -244,6 +231,9 @@ async function prepareCodexOrchestrationDelegation(
         }
       }
     });
+    return identityWarnings.length > 0 && prepared.status !== 'failed'
+      ? { ...prepared, warnings: Object.freeze(identityWarnings) }
+      : prepared;
   } catch (error) {
     if (error instanceof OrchestrationStateError) return bridgeFailure(error.code, error.message);
     const detailValue = error instanceof Error
@@ -290,10 +280,11 @@ async function activateCodexOrchestrationDelegation(
     });
     const buildIdentity = options.buildIdentity ?? computeLifecycleBuildIdentity(repoRoot);
     const contextPath = process.env.AGENT_INFRA_CODEX_CONTROLLER_CONTEXT;
-    const controller = contextPath
-      ? verifyCodexSandboxControllerContext(contextPath, { repoRoot })
+    const contextVerification = contextPath
+      ? verifySandboxControllerWithWarnings(contextPath, { repoRoot })
       : null;
-    return activateMatchingOrchestrationDelegation('codex', {
+    const controller = contextVerification?.context ?? null;
+    const activated = activateMatchingOrchestrationDelegation('codex', {
       nativeAgent: evidence.nativeAgent,
       childId: evidence.childThreadId,
       parentId: evidence.parentThreadId,
@@ -318,6 +309,10 @@ async function activateCodexOrchestrationDelegation(
         controlGeneration: controller?.controlGeneration ?? null
       }
     }, coreOptions(options));
+    const warnings = contextVerification?.warnings ?? [];
+    return warnings.length > 0 && activated.status !== 'failed'
+      ? { ...activated, warnings: Object.freeze(warnings) }
+      : activated;
   } catch (error) {
     if (error instanceof OrchestrationStateError) return bridgeFailure(error.code, error.message);
     return pauseBridge('ORCHESTRATION_CODEX_START_FAILED', error instanceof Error ? error.message : String(error), options);

package/lib/task/command-options.ts

@@ -15,8 +15,7 @@ function parseTaskScope(args: string[]): TaskScope {
       value = args[++index];
       if (value === undefined || value === '' || value.startsWith('-')) throw new Error(`${arg} requires a value`);
     } else if (arg.startsWith('--task=')) {
-      value = arg.slice('--task='.length);
-      if (value === '') throw new Error('--task requires a value');
+      throw new Error("--task=... is not supported; use --task <ref> or -t <ref>");
     } else {
       positionals.push(arg);
       continue;

package/lib/task/commands/cat.ts

@@ -5,11 +5,9 @@ import { resolveArtifact } from '../artifacts.ts';
 
 const USAGE = `Usage: ai task cat <artifact | N>
        ai task cat (--task <ref> | -t <ref>) <artifact | N>
-       ai task cat <ref> <artifact | N>
 
 Prints a task artifact's raw content to stdout.
   One positional    Uses current task context and treats the operand as the artifact.
-  <ref>            Bare numeric short id, or a full TASK-YYYYMMDD-HHMMSS id.
   <artifact | N>   Artifact filename (with or without '.md'), or the number from 'ai task files'.
 `;
 
@@ -29,8 +27,6 @@ function cat(args: string[] = []): void {
     taskRef = scope.taskRef; artifact = scope.positionals[0];
   } else if (scope.positionals.length === 1) {
     artifact = scope.positionals[0];
-  } else if (scope.positionals.length === 2) {
-    [taskRef, artifact] = scope.positionals;
   } else { process.stdout.write(USAGE); process.exitCode = 1; return; }
   const resolved = resolveTaskContext(taskRef);
   if (!resolved.ok) {