@fitlab-ai/agent-infra 0.9.12 → 0.9.14

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

@@ -0,0 +1,140 @@
+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'],
+  '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']
+} 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() });
@@ -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');
@@ -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');

package/lib/internal/git-workflow.ts

@@ -3,40 +3,43 @@ import { inspectGitWorkflow, previewCommitTree, pushRebasedBranch } from '../git
 import { compareReviewTrees, snapshotReview } from '../git/review-snapshot.ts';
 import { resolvePostReviewGlobs } from '../task/review-fingerprint.ts';
 import { executeCommitOperation } from '../task/commit-operation.ts';
+import { ensureInternalHandlerRoute, internalHandlerRoute } from './cli-route-inventory.ts';
 
 function output(value: unknown): void { process.stdout.write(`${JSON.stringify(value)}\n`); }
 
 function gitWorkflow(args: string[] = []): void {
+  if (!ensureInternalHandlerRoute('git-workflow', args)) return;
   const [action, ...rest] = args;
   const cwdIndex = rest.indexOf('--cwd');
   const cwd = cwdIndex >= 0 ? rest[cwdIndex + 1] : process.cwd();
   let result;
-  if (action === 'inspect') {
+  if (internalHandlerRoute('git-workflow', 'inspect', action ?? '')) {
     const inputIndex = rest.indexOf('--input');
     const input = inputIndex >= 0 && rest[inputIndex + 1] ? JSON.parse(fs.readFileSync(rest[inputIndex + 1]!, 'utf8')) as { remote?: string; refs?: string[] } : null;
     result = inspectGitWorkflow(cwd ?? process.cwd(), undefined, input?.remote && input.refs ? { remote: input.remote, refs: input.refs } : undefined);
   }
-  else if (action === 'commit') {
+  else if (internalHandlerRoute('git-workflow', 'commit', action ?? '')) {
     const inputIndex = rest.indexOf('--input');
     const input = inputIndex >= 0 && rest[inputIndex + 1] ? JSON.parse(fs.readFileSync(rest[inputIndex + 1]!, 'utf8')) : null;
     result = input
       ? executeCommitOperation({ cwd: cwd ?? process.cwd(), ...input })
       : { status: 'failed', changed: false, error: { code: 'GIT_INPUT_REQUIRED', message: '--input JSON file is required' } };
-  } else if (action === 'push-rebased') {
+  } else if (internalHandlerRoute('git-workflow', 'push-rebased', action ?? '')) {
     const inputIndex = rest.indexOf('--input');
     const input = inputIndex >= 0 && rest[inputIndex + 1] ? JSON.parse(fs.readFileSync(rest[inputIndex + 1]!, 'utf8')) : null;
     result = input ? pushRebasedBranch({ cwd: cwd ?? process.cwd(), ...input }) : { status: 'failed', changed: false, error: { code: 'GIT_INPUT_REQUIRED', message: '--input JSON file is required' } };
-  } else if (action === 'preview-tree') {
+  } else if (internalHandlerRoute('git-workflow', 'preview-tree', action ?? '')) {
     const inputIndex = rest.indexOf('--input');
     const input = inputIndex >= 0 && rest[inputIndex + 1] ? JSON.parse(fs.readFileSync(rest[inputIndex + 1]!, 'utf8')) : null;
     result = input
       ? previewCommitTree({ cwd: cwd ?? process.cwd(), paths: input.paths, expectedHead: input.expectedHead })
       : { status: 'failed', changed: false, error: { code: 'GIT_INPUT_REQUIRED', message: '--input JSON file is required' } };
-  } else if (action === 'snapshot' || action === 'compare-trees') {
+  } else if (internalHandlerRoute('git-workflow', 'snapshot', action ?? '')
+    || internalHandlerRoute('git-workflow', 'compare-trees', action ?? '')) {
     const inputIndex = rest.indexOf('--input');
     const input = inputIndex >= 0 && rest[inputIndex + 1] ? JSON.parse(fs.readFileSync(rest[inputIndex + 1]!, 'utf8')) : null;
     if (!input) result = { status: 'failed', changed: false, error: { code: 'GIT_INPUT_REQUIRED', message: '--input JSON file is required' } };
-    else if (action === 'snapshot') result = { status: 'no-op', changed: false, snapshot: snapshotReview({ cwd: cwd ?? process.cwd(), mode: input.mode, baseline: input.baseline, diffBase: input.diffBase, globs: input.globs ?? resolvePostReviewGlobs({}, {}) }), error: null };
+    else if (internalHandlerRoute('git-workflow', 'snapshot', action ?? '')) result = { status: 'no-op', changed: false, snapshot: snapshotReview({ cwd: cwd ?? process.cwd(), mode: input.mode, baseline: input.baseline, diffBase: input.diffBase, globs: input.globs ?? resolvePostReviewGlobs({}, {}) }), error: null };
     else result = { status: 'no-op', changed: false, comparison: compareReviewTrees({ cwd: cwd ?? process.cwd(), expected: input.expected, actual: input.actual }), error: null };
   } else result = { status: 'failed', changed: false, error: { code: 'GIT_ACTION_INVALID', message: `Unknown git-workflow action '${action ?? ''}'` } };
   output(result);

package/lib/internal/platform-checks.ts

@@ -7,6 +7,7 @@ import {
   watchPullRequestReadiness
 } from '../platform/pr-checks.ts';
 import type { ChecksResult } from '../platform/pr-checks.ts';
+import { ensureInternalHandlerRoute, internalHandlerRoute } from './cli-route-inventory.ts';
 
 const USAGE = `Usage: agent-infra-internal platform-checks inspect <task-ref> [--cwd <path>]
        agent-infra-internal platform-checks watch <task-ref> --interval-seconds <N> --deadline-seconds <N> [--cwd <path>]
@@ -53,9 +54,15 @@ function positive(value: string | undefined): number | null {
 }
 
 async function platformChecks(args: string[] = []): Promise<void> {
+  if (!ensureInternalHandlerRoute('platform-checks', args)) return;
   if (args[0] === '--help' || args[0] === '-h') { process.stdout.write(USAGE); return; }
   const operation = args[0];
-  if (!operation || !['inspect', 'watch', 'resolve-run', 'logs'].includes(operation)) { fail('a valid operation is required'); return; }
+  if (!operation || ![
+    internalHandlerRoute('platform-checks', 'inspect', operation),
+    internalHandlerRoute('platform-checks', 'watch', operation),
+    internalHandlerRoute('platform-checks', 'resolve-run', operation),
+    internalHandlerRoute('platform-checks', 'logs', operation)
+  ].some(Boolean)) { fail('a valid operation is required'); return; }
   const taskRef = args[1];
   if (!taskRef || taskRef.startsWith('--')) { fail(`${operation} requires a task ref`); return; }
   const parsed = parse(args, 2);
@@ -70,19 +77,20 @@ async function platformChecks(args: string[] = []): Promise<void> {
   };
   const unexpected = Object.keys(values).find((name) => !allowed[operation]!.includes(name));
   if (unexpected) { fail(`${operation} does not accept --${unexpected}`); return; }
-  if (operation === 'inspect') { finish(inspectPullRequestReadiness(taskRef, { cwd })); return; }
-  if (operation === 'resolve-run') {
+  if (internalHandlerRoute('platform-checks', 'inspect', operation)) { finish(await inspectPullRequestReadiness(taskRef, { cwd })); return; }
+  if (internalHandlerRoute('platform-checks', 'resolve-run', operation)) {
     if (!values.checkName) { fail('resolve-run requires --check-name'); return; }
-    finish(resolvePlatformCheckRun(taskRef, { cwd, checkName: values.checkName, detailsUrl: values.detailsUrl }));
+    finish(await resolvePlatformCheckRun(taskRef, { cwd, checkName: values.checkName, detailsUrl: values.detailsUrl }));
     return;
   }
-  if (operation === 'logs') {
+  if (internalHandlerRoute('platform-checks', 'logs', operation)) {
     const run = positive(values.run);
     const job = values.job === undefined ? undefined : positive(values.job);
     if (!run || values.job !== undefined && !job) { fail('logs requires a positive --run and optional positive --job'); return; }
-    finish(fetchPlatformCheckLogs(taskRef, { cwd, run, job: job || undefined }));
+    finish(await fetchPlatformCheckLogs(taskRef, { cwd, run, job: job || undefined }));
     return;
   }
+  if (!internalHandlerRoute('platform-checks', 'watch', operation)) { fail('operation is not registered'); return; }
   const intervalSeconds = positive(values.intervalSeconds);
   const deadlineSeconds = positive(values.deadlineSeconds);
   if (!intervalSeconds || !deadlineSeconds) { fail('watch requires positive --interval-seconds and --deadline-seconds'); return; }

package/lib/internal/platform-comment.ts

@@ -10,8 +10,9 @@ import {
 import type { CommentKind } from '../platform/issue-comments.ts';
 import type { PlatformResult } from '../platform/types.ts';
 import { backfillCompletionComments } from '../platform/completion-backfill.ts';
+import { ensureInternalHandlerRoute, internalHandlerRoute } from './cli-route-inventory.ts';
 
-const USAGE = `Usage: agent-infra-internal platform-comment list --issue <N> [--cwd <path>]
+const USAGE = `Usage: agent-infra-internal platform-comment list --issue <token> [--cwd <path>]
        agent-infra-internal platform-comment owner <task-ref> [--cwd <path>]
        agent-infra-internal platform-comment backfill <task-ref> --agent <agent> [--cwd <path>]
        agent-infra-internal platform-comment sync <task-ref> --kind <kind> --agent <agent> [--artifact <file>] [--body-file <path|->] [--status-label <label>] [--backfill] [--cwd <path>]
@@ -52,40 +53,47 @@ function readBodyFile(value: string, cwd: string): string {
   return fs.readFileSync(path.resolve(cwd, value), 'utf8');
 }
 
-function platformComment(args: string[] = []): void {
+async function platformComment(args: string[] = []): Promise<void> {
+  if (!ensureInternalHandlerRoute('platform-comment', args)) return;
   if (args[0] === '--help' || args[0] === '-h') { process.stdout.write(USAGE); return; }
   const operation = args[0];
-  if (!operation || !['list', 'owner', 'backfill', 'sync'].includes(operation)) { fail('a valid operation is required'); return; }
+  if (!operation || ![
+    internalHandlerRoute('platform-comment', 'list', operation),
+    internalHandlerRoute('platform-comment', 'owner', operation),
+    internalHandlerRoute('platform-comment', 'backfill', operation),
+    internalHandlerRoute('platform-comment', 'sync', operation)
+  ].some(Boolean)) { fail('a valid operation is required'); return; }
   const hasTaskRef = operation !== 'list';
   const taskRef = hasTaskRef ? args[1] : undefined;
   if (hasTaskRef && (!taskRef || taskRef.startsWith('--'))) { fail(`${operation} requires a task ref`); return; }
   const parsed = parseFlags(args, hasTaskRef ? 2 : 1);
   if (parsed.error) { fail(parsed.error); return; }
   const cwd = path.resolve(typeof parsed.values.cwd === 'string' ? parsed.values.cwd : process.cwd());
-  if (operation === 'list') {
-    const issue = Number(parsed.values.issue);
-    if (!Number.isInteger(issue) || issue <= 0) { fail('list requires a positive --issue'); return; }
+  if (internalHandlerRoute('platform-comment', 'list', operation)) {
+    const issue = parsed.values.issue;
+    if (typeof issue !== 'string' || !issue) { fail('list requires --issue <token>'); return; }
     const unexpected = Object.keys(parsed.values).find((key) => !['issue', 'cwd'].includes(key));
     if (unexpected) { fail(`list does not accept '--${unexpected}'`); return; }
-    finish(listPlatformComments(issue, cwd));
+    finish(await listPlatformComments(issue, cwd));
     return;
   }
-  if (operation === 'owner') {
+  if (internalHandlerRoute('platform-comment', 'owner', operation)) {
     const unexpected = Object.keys(parsed.values).find((key) => key !== 'cwd');
     if (unexpected) { fail(`owner does not accept '--${unexpected}'`); return; }
-    finish(checkPlatformCommentOwner(taskRef!, { cwd }));
+    finish(await checkPlatformCommentOwner(taskRef!, { cwd }));
     return;
   }
-  if (operation === 'backfill') {
+  if (internalHandlerRoute('platform-comment', 'backfill', operation)) {
     const unexpected = Object.keys(parsed.values).find((key) => !['cwd', 'agent'].includes(key));
     if (unexpected) { fail(`backfill does not accept '--${unexpected}'`); return; }
     const agent = parsed.values.agent;
     if (typeof agent !== 'string' || !agent) { fail('backfill requires --agent'); return; }
     const normalizedAgent = normalizeAgentToken(agent);
     if (!normalizedAgent) { fail(`invalid --agent '${agent}': ${AGENT_USAGE_HINT}`); return; }
-    finish(backfillCompletionComments(taskRef!, { cwd, agent: normalizedAgent }));
+    finish(await backfillCompletionComments(taskRef!, { cwd, agent: normalizedAgent }));
     return;
   }
+  if (!internalHandlerRoute('platform-comment', 'sync', operation)) { fail('operation is not registered'); return; }
   const kind = parsed.values.kind;
   const agent = parsed.values.agent;
   if (!['task', 'artifact', 'summary', 'cancel'].includes(String(kind))) { fail('sync requires a valid --kind'); return; }
@@ -101,7 +109,7 @@ function platformComment(args: string[] = []): void {
     fail(`unable to read body file: ${error instanceof Error ? error.message : String(error)}`);
     return;
   }
-  finish(syncPlatformComment(taskRef!, {
+  finish(await syncPlatformComment(taskRef!, {
     kind: kind as CommentKind,
     agent: normalizedAgent,
     artifact: typeof parsed.values.artifact === 'string' ? parsed.values.artifact : undefined,

package/lib/internal/platform-context.ts

@@ -1,6 +1,7 @@
 import path from 'node:path';
 
 import { resolvePlatformContext } from '../platform/context.ts';
+import { ensureInternalHandlerRoute, internalHandlerRoute } from './cli-route-inventory.ts';
 
 const USAGE = 'Usage: agent-infra-internal platform-context resolve [--cwd <path>]\n';
 
@@ -10,9 +11,10 @@ function fail(message: string): void {
   process.exitCode = 1;
 }
 
-function platformContext(args: string[] = []): void {
+async function platformContext(args: string[] = []): Promise<void> {
+  if (!ensureInternalHandlerRoute('platform-context', args)) return;
   if (args[0] === '--help' || args[0] === '-h') { process.stdout.write(USAGE); return; }
-  if (args[0] !== 'resolve') { fail("operation must be 'resolve'"); return; }
+  if (!internalHandlerRoute('platform-context', 'resolve', args[0] ?? '')) { fail("operation must be 'resolve'"); return; }
   let cwd = process.cwd();
   const seen = new Set<string>();
   for (let index = 1; index < args.length; index += 1) {
@@ -24,7 +26,7 @@ function platformContext(args: string[] = []): void {
     seen.add(flag);
     cwd = path.resolve(value);
   }
-  const result = resolvePlatformContext({ cwd });
+  const result = await resolvePlatformContext({ cwd });
   process.stdout.write(`${JSON.stringify(result)}\n`);
   if (result.status === 'failed') process.exitCode = 1;
   if (result.status === 'blocked') process.exitCode = 2;

package/lib/internal/platform-issue.ts

@@ -8,10 +8,11 @@ import {
   syncPlatformIssue
 } from '../platform/issues.ts';
 import type { IssueResult } from '../platform/issues.ts';
+import { ensureInternalHandlerRoute, internalHandlerRoute } from './cli-route-inventory.ts';
 
 const USAGE = `Usage: agent-infra-internal platform-issue inspect <task-ref> [--cwd <path>]
        agent-infra-internal platform-issue create <task-ref> --agent <agent> [--dry-run] [--cwd <path>]
-       agent-infra-internal platform-issue bind <task-ref> --issue <N> --agent <agent> [--dry-run] [--cwd <path>]
+       agent-infra-internal platform-issue bind <task-ref> --issue <token> --agent <agent> [--dry-run] [--cwd <path>]
        agent-infra-internal platform-issue sync <task-ref> --agent <agent> [--status <suffix|none>] [--assignees current|none] [--milestone initial|specific|none] [--issue-type] [--fields] [--requirements] [--in-labels from-diff|none] [--base <branch>] [--state open|closed] [--close-reason completed|not_planned] [--dry-run] [--cwd <path>]
 `;
 
@@ -59,10 +60,16 @@ function oneOf(values: Record<string, string | boolean>, name: string, allowed:
   return value;
 }
 
-function platformIssue(args: string[] = []): void {
+async function platformIssue(args: string[] = []): Promise<void> {
+  if (!ensureInternalHandlerRoute('platform-issue', args)) return;
   if (args[0] === '--help' || args[0] === '-h') { process.stdout.write(USAGE); return; }
   const operation = args[0];
-  if (!operation || !['inspect', 'create', 'bind', 'sync'].includes(operation)) { fail('a valid operation is required'); return; }
+  if (!operation || ![
+    internalHandlerRoute('platform-issue', 'inspect', operation),
+    internalHandlerRoute('platform-issue', 'create', operation),
+    internalHandlerRoute('platform-issue', 'bind', operation),
+    internalHandlerRoute('platform-issue', 'sync', operation)
+  ].some(Boolean)) { fail('a valid operation is required'); return; }
   const taskRef = args[1];
   if (!taskRef || taskRef.startsWith('--')) { fail(`${operation} requires a task ref`); return; }
   const parsed = parse(args, 2);
@@ -75,18 +82,17 @@ function platformIssue(args: string[] = []): void {
   };
   const unexpected = Object.keys(values).find((name) => !allowed[operation]!.includes(name));
   if (unexpected) { fail(`${operation} does not accept --${unexpected}`); return; }
-  if (operation === 'inspect') { finish(inspectPlatformIssue(taskRef, { cwd })); return; }
+  if (internalHandlerRoute('platform-issue', 'inspect', operation)) { finish(await inspectPlatformIssue(taskRef, { cwd })); return; }
   if (typeof values.agent !== 'string' || !values.agent) { fail(`${operation} requires --agent`); return; }
   const agent = normalizeAgentToken(values.agent);
   if (!agent) { fail(`invalid --agent '${values.agent}': ${AGENT_USAGE_HINT}`); return; }
   values.agent = agent;
-  if (operation === 'create') {
-    finish(createPlatformIssue(taskRef, { cwd, agent: values.agent, dryRun: values.dryRun === true })); return;
+  if (internalHandlerRoute('platform-issue', 'create', operation)) {
+    finish(await createPlatformIssue(taskRef, { cwd, agent: values.agent, dryRun: values.dryRun === true })); return;
   }
-  if (operation === 'bind') {
-    const issue = Number(values.issue);
-    if (!Number.isInteger(issue) || issue <= 0) { fail('bind requires a positive --issue'); return; }
-    finish(bindPlatformIssue(taskRef, { cwd, agent: values.agent, issue, dryRun: values.dryRun === true })); return;
+  if (internalHandlerRoute('platform-issue', 'bind', operation)) {
+    if (typeof values.issue !== 'string' || !values.issue) { fail('bind requires --issue <token>'); return; }
+    finish(await bindPlatformIssue(taskRef, { cwd, agent: values.agent, issue: values.issue, dryRun: values.dryRun === true })); return;
   }
   try {
     const assignees = oneOf(values, 'assignees', ['current', 'none']);
@@ -99,7 +105,7 @@ function platformIssue(args: string[] = []): void {
     if (closeReason && state !== 'closed') throw new Error('--close-reason requires --state closed');
     const desiredKeys = ['status', 'assignees', 'milestone', 'issueType', 'fields', 'requirements', 'inLabels', 'state'];
     if (!desiredKeys.some((name) => values[name] !== undefined)) throw new Error('sync requires at least one desired-state option');
-    finish(syncPlatformIssue(taskRef, {
+    finish(await syncPlatformIssue(taskRef, {
       cwd, agent: values.agent, dryRun: values.dryRun === true,
       status: typeof values.status === 'string' ? values.status : undefined,
       assignees: assignees as 'current' | 'none' | undefined,

package/lib/internal/platform-metadata.ts

@@ -0,0 +1,70 @@
+import path from 'node:path';
+
+import { initializeLabels, initializeMilestones } from '../platform/repository-metadata.ts';
+import { ensureInternalHandlerRoute, internalHandlerRoute } from './cli-route-inventory.ts';
+
+const USAGE = `Usage: agent-infra-internal platform-metadata init-labels [--cleanup-stale-in] [--cwd <path>]
+       agent-infra-internal platform-metadata init-milestones [--history] [--cwd <path>]
+`;
+
+function fail(message: string): void {
+  process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, error: { code: 'METADATA_INPUT_INVALID', message, retryable: false } })}\n`);
+  process.stderr.write(USAGE);
+  process.exitCode = 1;
+}
+
+function finish(result: { status: string; [key: string]: unknown }, preserveMilestoneFallback = false): void {
+  if (preserveMilestoneFallback && result.error && typeof result.error === 'object'
+    && (result.error as { code?: string }).code === 'PLATFORM_CAPABILITY_UNSUPPORTED') {
+    process.stderr.write('Milestone initialization skipped for unsupported platform.\n');
+    process.exitCode = 0;
+    return;
+  }
+  process.stdout.write(`${JSON.stringify(result)}\n`);
+  process.exitCode = result.status === 'blocked' ? 2 : result.status === 'failed' ? 1 : 0;
+}
+
+function parseOptions(args: string[]): { cwd: string; cleanup: boolean; history: boolean } | null {
+  let cwd = process.cwd();
+  let cleanup = false;
+  let history = false;
+  const seen = new Set<string>();
+  for (let index = 0; index < args.length; index += 1) {
+    const flag = args[index]!;
+    if (seen.has(flag)) return null;
+    seen.add(flag);
+    if (flag === '--cleanup-stale-in') { cleanup = true; continue; }
+    if (flag === '--history') { history = true; continue; }
+    if (flag === '--cwd') {
+      const value = args[++index];
+      if (!value || value.startsWith('--')) return null;
+      cwd = path.resolve(value);
+      continue;
+    }
+    return null;
+  }
+  return { cwd: path.resolve(cwd), cleanup, history };
+}
+
+async function platformMetadata(args: string[] = []): Promise<void> {
+  if (!ensureInternalHandlerRoute('platform-metadata', args)) return;
+  if (args[0] === '--help' || args[0] === '-h') { process.stdout.write(USAGE); return; }
+  const action = args[0];
+  if (!internalHandlerRoute('platform-metadata', 'init-labels', action ?? '')
+    && !internalHandlerRoute('platform-metadata', 'init-milestones', action ?? '')) {
+    fail('a valid operation is required');
+    return;
+  }
+  if (action !== 'init-labels' && action !== 'init-milestones') { fail('a valid operation is required'); return; }
+  const parsed = parseOptions(args.slice(1));
+  if (!parsed) { fail('invalid metadata options'); return; }
+  if (action === 'init-labels' && parsed.history) { fail('init-labels does not accept --history'); return; }
+  if (action === 'init-milestones' && parsed.cleanup) { fail('init-milestones does not accept --cleanup-stale-in'); return; }
+  if (action === 'init-labels') {
+    finish(await initializeLabels({ cleanupStaleIn: parsed.cleanup }, { cwd: parsed.cwd }));
+    return;
+  }
+  finish(await initializeMilestones({ history: parsed.history }, { cwd: parsed.cwd }), true);
+}
+
+export { platformMetadata };