@fitlab-ai/agent-infra 0.9.13 → 0.9.15

package/lib/internal/task-override.ts

@@ -6,6 +6,7 @@ import {
 import type { ConsumeHumanOverrideRequest, HumanOverrideRequest } from '../task/human-override.ts';
 import { resolveTaskRef } from '../task/resolve-ref.ts';
 import { TaskExecutionLockError, withTaskExecutionLock } from '../task/task-execution-lock.ts';
+import { ensureInternalHandlerRoute, internalHandlerRoute } from './cli-route-inventory.ts';
 
 const USAGE = `Usage: agent-infra-internal task-override <task-ref> <diagnose|issue|consume> [options]
 
@@ -38,9 +39,14 @@ function usageFailure(message: string): void {
 }
 
 async function taskOverride(args: string[] = []): Promise<void> {
+  if (!ensureInternalHandlerRoute('task-override', args)) return;
   if (args[0] === '--help' || args[0] === '-h') { process.stdout.write(USAGE); return; }
   const [taskRef, operation] = args;
-  if (!taskRef || !operation || !['diagnose', 'issue', 'consume'].includes(operation)) {
+  if (!taskRef || !operation || ![
+    internalHandlerRoute('task-override', 'diagnose', operation ?? ''),
+    internalHandlerRoute('task-override', 'issue', operation ?? ''),
+    internalHandlerRoute('task-override', 'consume', operation ?? '')
+  ].some(Boolean)) {
     usageFailure('task ref and a valid operation are required');
     return;
   }
@@ -75,13 +81,13 @@ async function taskOverride(args: string[] = []): Promise<void> {
 
   let result;
   try {
-    if (operation === 'diagnose') {
+    if (internalHandlerRoute('task-override', 'diagnose', operation)) {
       result = await diagnoseHumanOverrideForTask(
         taskRef,
         values.failureId ? String(values.failureId) : undefined,
         values.target ? String(values.target) : undefined
       );
-    } else if (operation === 'issue') {
+    } else if (internalHandlerRoute('task-override', 'issue', operation)) {
       result = await withTaskExecutionLock(
         resolved.repoRoot,
         resolved.taskId,

package/lib/internal/task-qualification.ts

@@ -0,0 +1,61 @@
+import fs from 'node:fs';
+
+import { applyQualificationConfirmation } from '../task/qualification-confirmation.ts';
+import type { QualificationConfirmationRequest } from '../task/qualification-confirmation.ts';
+import { applyQualificationProposal } from '../task/qualification-intents.ts';
+import type { QualificationProposalRequest } from '../task/qualification-intents.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';
+
+const USAGE = `Usage: agent-infra-internal task-qualification <task-ref> <proposal|confirm|supersede|revoke> --input <json-file> [--dry-run]\n`;
+
+function fail(message: string, code = 'QUALIFICATION_PROPOSAL_INVALID'): void {
+  process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, error: { code, message } })}\n`);
+  process.stderr.write(USAGE);
+  process.exitCode = 1;
+}
+
+async function taskQualification(args: string[] = []): Promise<void> {
+  const [taskRef, operation] = args;
+  const registered = [
+    internalHandlerRoute('task-qualification', 'proposal', operation ?? ''),
+    internalHandlerRoute('task-qualification', 'confirm', operation ?? ''),
+    internalHandlerRoute('task-qualification', 'supersede', operation ?? ''),
+    internalHandlerRoute('task-qualification', 'revoke', operation ?? '')
+  ].some(Boolean);
+  if (!registered) {
+    fail('task ref and a valid qualification operation are required');
+    return;
+  }
+  if (!ensureInternalHandlerRoute('task-qualification', args)) return;
+  if (!taskRef || !['proposal', 'confirm', 'supersede', 'revoke'].includes(operation ?? '')) { fail('task ref and a valid qualification operation are required'); return; }
+  let inputPath = '';
+  let dryRun = false;
+  for (let index = 2; index < args.length; index += 1) {
+    const arg = args[index]!;
+    if (arg === '--dry-run') { if (dryRun) { fail('duplicate option --dry-run'); return; } dryRun = true; continue; }
+    if (arg !== '--input' || inputPath) { fail(`unknown or duplicate option '${arg}'`); return; }
+    inputPath = args[++index] ?? '';
+    if (!inputPath || inputPath.startsWith('--')) { fail("option '--input' requires a value"); return; }
+  }
+  if (!inputPath) { fail("option '--input' is required"); return; }
+  let payload: unknown;
+  try { payload = JSON.parse(fs.readFileSync(inputPath, 'utf8')); }
+  catch (error) { fail(`cannot read qualification input: ${error instanceof Error ? error.message : String(error)}`); return; }
+  if (!payload || typeof payload !== 'object' || Array.isArray(payload)) { fail('qualification input must be an object'); return; }
+  const resolved = resolveTaskRef(taskRef);
+  if (!resolved.ok) { fail(resolved.message, resolved.code); return; }
+  try {
+    const result = await withTaskExecutionLock(resolved.repoRoot, resolved.taskId, `task-qualification.${operation}`, () => operation === 'proposal'
+      ? applyQualificationProposal({ ...(payload as Record<string, unknown>), taskRef: resolved.taskId, dryRun } as QualificationProposalRequest, { repoRoot: resolved.repoRoot })
+      : applyQualificationConfirmation({ ...(payload as Record<string, unknown>), taskRef: resolved.taskId, operation, dryRun } as QualificationConfirmationRequest, { repoRoot: resolved.repoRoot }));
+    process.stdout.write(`${JSON.stringify(result)}\n`);
+    if (result.status === 'failed') process.exitCode = 1;
+  } catch (error) {
+    if (error instanceof TaskExecutionLockError) fail(`${error.code}: ${error.message}`, error.code);
+    else throw error;
+  }
+}
+
+export { taskQualification };

package/lib/internal/task-review.ts

@@ -1,7 +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 } 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';
 
@@ -17,60 +19,15 @@ function failUsage(message: string): void {
 }
 
 async function taskReview(args: string[] = []): Promise<void> {
+  if (!ensureInternalHandlerRoute('task-review', args)) return;
   if (args[0] === '--help' || args[0] === '-h') {
     process.stdout.write(USAGE);
     return;
   }
-  if (args.length < 2) {
-    failUsage('task ref and intent are required');
-    return;
-  }
-  if (args[1] !== 'finalize-summary') {
-    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-short-id.ts

@@ -2,6 +2,7 @@ import path from 'node:path';
 
 import { detectRepoRoot } from '../task/resolve-ref.ts';
 import { configuredShortIdLength, executeShortIdCommand } from '../task/short-id.ts';
+import { ensureInternalHandlerRoute, internalHandlerRoute } from './cli-route-inventory.ts';
 
 const USAGE = `Usage: agent-infra-internal task-short-id <alloc|release|resolve|list> [argument] [--active-dir <path>] [--short-id-length <N>] [--verify]\n`;
 
@@ -12,9 +13,17 @@ function failure(message: string): void {
 }
 
 function taskShortId(args: string[] = []): void {
+  if (!ensureInternalHandlerRoute('task-short-id', args)) return;
   if (args[0] === '--help' || args[0] === '-h') { process.stdout.write(USAGE); return; }
   const operation = args[0];
-  if (!operation || !['alloc', 'release', 'resolve', 'list'].includes(operation)) { failure('a valid short-id operation is required'); return; }
+  const route = operation === 'list' && args.includes('--verify') ? 'list-verify' : operation ?? '';
+  if (!operation || ![
+    internalHandlerRoute('task-short-id', 'alloc', route),
+    internalHandlerRoute('task-short-id', 'release', route),
+    internalHandlerRoute('task-short-id', 'resolve', route),
+    internalHandlerRoute('task-short-id', 'list', route),
+    internalHandlerRoute('task-short-id', 'list-verify', route)
+  ].some(Boolean)) { failure('a valid short-id operation is required'); return; }
   const positional: string[] = [];
   let activeDir: string | null = null;
   let shortIdLength: number | null = null;

package/lib/internal/task-snapshot.ts

@@ -1,4 +1,5 @@
 import { collectTaskSnapshot } from '../task/snapshot.ts';
+import { ensureInternalHandlerRoute, internalHandlerRoute } from './cli-route-inventory.ts';
 
 const USAGE = 'Usage: agent-infra-internal task-snapshot <N | TASK-id> [--format json|text]\n';
 
@@ -9,8 +10,9 @@ function fail(message: string): void {
 }
 
 function taskSnapshot(args: string[] = []): void {
+  if (!ensureInternalHandlerRoute('task-snapshot', args)) return;
   if (args[0] === '--help' || args[0] === '-h') { process.stdout.write(USAGE); return; }
-  if (!args[0] || args[0].startsWith('--')) { fail('task ref is required'); return; }
+  if (!args[0] || args[0].startsWith('--') || !internalHandlerRoute('task-snapshot', 'snapshot', 'snapshot')) { fail('task ref is required'); return; }
   let format: 'json' | 'text' = 'json';
   let seenFormat = false;
   for (let index = 1; index < args.length; index += 1) {

package/lib/internal/task-validate.ts

@@ -24,8 +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;
 
@@ -34,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.`);
@@ -49,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]!;
@@ -64,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 {
@@ -71,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) {
@@ -271,6 +281,7 @@ function sniffFormat(args: string[]): 'text' | 'json' {
 }
 
 function taskValidate(args: string[]): void {
+  if (!ensureInternalHandlerRoute('task-validate', args)) return;
   let options: ValidateOptions;
   try {
     options = parseValidateArgs(args);
@@ -287,26 +298,35 @@ function taskValidate(args: string[]): void {
     const target = resolveSandboxTarget(options.target, config.repoRoot);
     const commit = git(config.repoRoot, ['rev-parse', target.branch]);
     const startedAt = new Date().toISOString();
-    const result = options.scope === 'snapshot'
+    const result = internalHandlerRoute('task-validate', 'snapshot', options.scope)
       ? snapshotValidation(config.repoRoot, commit, options)
-      : inplaceValidation(config, target, options);
-    const evidence = {
-      version: 1,
+      : internalHandlerRoute('task-validate', 'inplace', options.scope)
+        ? inplaceValidation(config, target, options)
+        : (() => { throw new Error('TASK_VALIDATE_SCOPE_UNREGISTERED'); })();
+    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/internal/task-verify.ts

@@ -2,6 +2,7 @@ import { renderTaskVerification, verifyTaskEvent } from '../task/verification.ts
 import { consumeHumanOverride, failureId } from '../task/human-override.ts';
 import { resolveTaskRef } from '../task/resolve-ref.ts';
 import { TaskExecutionLockError, withTaskExecutionLock } from '../task/task-execution-lock.ts';
+import { ensureInternalHandlerRoute, internalHandlerRoute } from './cli-route-inventory.ts';
 
 const USAGE = 'Usage: agent-infra-internal task-verify <N | TASK-id> <verification-event> [--artifact <canonical.md>] [--format json|text] [--override-ticket <ticket> --override-target <target> --override-scope <scope>]\n';
 
@@ -12,8 +13,10 @@ function fail(message: string): void {
 }
 
 async function taskVerify(args: string[] = []): Promise<void> {
+  if (!ensureInternalHandlerRoute('task-verify', args)) return;
   if (args[0] === '--help' || args[0] === '-h') { process.stdout.write(USAGE); return; }
-  if (!args[0] || !args[1] || args[0].startsWith('--') || args[1].startsWith('--')) { fail('task ref and verification event are required'); return; }
+  if (!args[0] || !args[1] || args[0].startsWith('--') || args[1].startsWith('--')
+    || !internalHandlerRoute('task-verify', 'event', args[1] ? 'event' : '')) { fail('task ref and verification event are required'); return; }
   const taskRef = args[0];
   const event = args[1];
   let artifact: string | undefined;

package/lib/internal/task-warning.ts

@@ -3,6 +3,7 @@ import type { WorkflowWarningIntent } from '../task/workflow-warning-intents.ts'
 import { consumeHumanOverride, failureId, overrideDryRunConflict } from '../task/human-override.ts';
 import { resolveTaskRef } from '../task/resolve-ref.ts';
 import { TaskExecutionLockError, withTaskExecutionLock } from '../task/task-execution-lock.ts';
+import { ensureInternalHandlerRoute, internalHandlerRoute } from './cli-route-inventory.ts';
 
 const USAGE = `Usage: agent-infra-internal task-warning <task-ref> <add|set-status|list> [intent flags] [--dry-run]\n`;
 const FLAGS: Record<string, string> = {
@@ -18,9 +19,14 @@ function usageFailure(message: string): void {
 }
 
 async function taskWarning(args: string[] = []): Promise<void> {
+  if (!ensureInternalHandlerRoute('task-warning', args)) return;
   if (args[0] === '--help' || args[0] === '-h') { process.stdout.write(USAGE); return; }
   const [taskRef, kind] = args;
-  if (!taskRef || !kind || !['add', 'set-status', 'list'].includes(kind)) { usageFailure('task ref and a valid intent are required'); return; }
+  if (!taskRef || !kind || ![
+    internalHandlerRoute('task-warning', 'add', kind ?? ''),
+    internalHandlerRoute('task-warning', 'set-status', kind ?? ''),
+    internalHandlerRoute('task-warning', 'list', kind ?? '')
+  ].some(Boolean)) { usageFailure('task ref and a valid intent are required'); return; }
   const values: Record<string, unknown> = { kind, taskRef };
   const seen = new Set<string>();
   for (let index = 2; index < args.length; index += 1) {

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';
+}