@fitlab-ai/agent-infra 0.9.13 → 0.9.15

package/lib/internal/manual-validation.ts

@@ -0,0 +1,306 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { locateActivityLog, pairEntries } from '../task/activity-log.ts';
+import { resolveTaskRef } from '../task/resolve-ref.ts';
+import { applyTaskEvent } from '../task/events.ts';
+import { TaskExecutionLockError, withTaskExecutionLock } from '../task/task-execution-lock.ts';
+import { normalizeAgentToken } from '../agent-clients/tokens.ts';
+import { createManualValidationReceipt, manualValidationFinalSummaryDigest, manualValidationFinalSummaryProjectionMatches, readManualValidationReceipt, writeManualValidationReceiptAtomic } from '../task/manual-validation-receipt.ts';
+import { archiveManualValidationGeneration, createManualValidationTransaction, readManualValidationTransaction, retryManualValidationTransaction, summaryPreimageDigest, transitionManualValidationTransaction, validateManualValidationGenerationArchive, writeManualValidationTransactionAtomic } from '../task/manual-validation-transaction.ts';
+import type { ManualValidationTransaction } from '../task/manual-validation-transaction.ts';
+import type { ManualValidationReceipt } from '../task/manual-validation-receipt.ts';
+import { sha256File } from '../task/artifact-receipts.ts';
+import { summaryCommentState, syncPullRequestSummary } from '../platform/pr-summary.ts';
+import type { PlatformClient } from '../platform/context.ts';
+import { ensureInternalHandlerRoute, internalHandlerRoute } from './cli-route-inventory.ts';
+
+const USAGE = `Usage: agent-infra-internal manual-validation transaction <task-ref> --prepare --artifact <artifact> --summary-file <path> --agent <agent> [--cwd <path>]
+       agent-infra-internal manual-validation transaction <task-ref> --artifact <artifact> --summary-file <path> --change-report-file <path> --agent <agent> [--result pr_created|pr_reused|no_op] [--cwd <path>]`;
+
+type OutputFormat = 'json' | 'text';
+type ManualValidationCoordinatorOptions = {
+  client?: PlatformClient;
+  archiveGeneration?: typeof archiveManualValidationGeneration;
+};
+type ManualValidationResult = {
+  status: 'applied' | 'failed';
+  changed: false;
+  error: { code: string; message: string } | null;
+  transaction?: ManualValidationTransaction;
+  receipt?: ManualValidationReceipt;
+  prepared?: boolean;
+  idempotent?: boolean;
+  [key: string]: unknown;
+};
+function result(status: 'applied' | 'failed', error: { code: string; message: string } | null = null, extra: Record<string, unknown> = {}): ManualValidationResult {
+  return { status, changed: false, error, ...extra };
+}
+
+function printFailure(format: OutputFormat, error: { code: string; message: string }): void {
+  if (format === 'json') process.stdout.write(`${JSON.stringify(result('failed', error))}\n`);
+  else process.stderr.write(`${error.code}: ${error.message}\n`);
+  process.exitCode = 1;
+}
+
+function manualSummaryBody(body: string, phase: 'pending' | 'final', transactionId: string, receiptDigest = '', evidenceDigest = '', prHeadSha = ''): string {
+  const withoutPrevious = body
+    .replace(/^###\s+✅\s+(?:Manual Validation Passed|人工验证已通过)\s*$/gmu, '')
+    .replace(/^###\s+⏳\s+(?:Manual Validation Pending|人工验证待收尾)\s*$/gmu, '')
+    .replace(/Manual validation passed(?:\s+→)?/giu, 'Manual validation pending');
+  const section = phase === 'pending'
+    ? `### ⏳ Manual Validation Pending\n\nManual validation evidence is staged; transaction ${transactionId} is awaiting final promotion.`
+    : `### ✅ Manual Validation Passed\n\nManual validation passed; transaction=${transactionId}; receipt=${receiptDigest}; evidence=${evidenceDigest}; head=${prHeadSha}.`;
+  return `${withoutPrevious.replace(/\s+$/u, '')}\n\n${section}\n`;
+}
+
+function openManualValidationStarted(taskMdPath: string): { present: boolean; transactionId: string | null } {
+  let content: string;
+  try { content = fs.readFileSync(taskMdPath, 'utf8'); }
+  catch { return { present: false, transactionId: null }; }
+  const section = locateActivityLog(content);
+  if (!section) return { present: false, transactionId: null };
+  const row = pairEntries(section.entries)
+    .filter((item) => item.step === 'Complete Manual Validation' && item.started && !item.done)
+    .at(-1);
+  if (!row) return { present: false, transactionId: null };
+  return {
+    present: true,
+    transactionId: /(?:^|;\s*)transaction=([A-Za-z0-9][A-Za-z0-9._-]{0,127})(?:;|$)/u.exec(row.note)?.[1] ?? null
+  };
+}
+
+async function executeManualValidationTransaction(taskRef: string, values: Record<string, string>, cwd: string, options: ManualValidationCoordinatorOptions = {}) {
+  const prepareOnly = values.prepare === 'true';
+  const required = prepareOnly
+    ? ['artifact', 'summaryFile', 'agent'] as const
+    : ['artifact', 'summaryFile', 'changeReportFile', 'agent'] as const;
+  const missing = required.find((key) => !values[key]);
+  if (missing) return result('failed', { code: 'MANUAL_VALIDATION_TRANSACTION_ARGS_INVALID', message: `transaction requires --${missing.replace(/[A-Z]/gu, (letter) => `-${letter.toLowerCase()}`)}` });
+  const agent = normalizeAgentToken(values.agent!);
+  if (!agent) return result('failed', { code: 'MANUAL_VALIDATION_TRANSACTION_ARGS_INVALID', message: 'transaction agent is invalid' });
+  const primaryResult = values.result ?? 'no_op';
+  if (!['pr_created', 'pr_reused', 'no_op'].includes(primaryResult)) return result('failed', { code: 'MANUAL_VALIDATION_TRANSACTION_ARGS_INVALID', message: '--result must be pr_created, pr_reused, or no_op' });
+  const resolved = resolveTaskRef(taskRef, { repoRoot: cwd });
+  if (!resolved.ok) return result('failed', { code: resolved.code, message: resolved.message });
+  try {
+    return await withTaskExecutionLock(
+      resolved.repoRoot,
+      resolved.taskId,
+      `manual-validation:${taskRef}`,
+      () => executeManualValidationTransactionLocked(taskRef, values, cwd, resolved, agent, primaryResult as 'pr_created' | 'pr_reused' | 'no_op', prepareOnly, options)
+    );
+  } catch (error) {
+    if (error instanceof TaskExecutionLockError) return result('failed', { code: error.code, message: error.message });
+    throw error;
+  }
+}
+
+async function executeManualValidationTransactionLocked(
+  taskRef: string,
+  values: Record<string, string>,
+  cwd: string,
+  resolved: Extract<ReturnType<typeof resolveTaskRef>, { ok: true }>,
+  agent: string,
+  primaryResult: 'pr_created' | 'pr_reused' | 'no_op',
+  prepareOnly: boolean,
+  options: ManualValidationCoordinatorOptions
+) {
+  const artifactPath = path.resolve(resolved.taskDir, values.artifact!);
+  if (!prepareOnly && !fs.existsSync(artifactPath)) return result('failed', { code: 'MANUAL_VALIDATION_ARTIFACT_MISSING', message: `manual-validation artifact is missing: ${values.artifact}` });
+  const currentState = await summaryCommentState(taskRef, { cwd, client: options.client });
+  if (!currentState.pullRequest) return result('failed', { code: 'MANUAL_VALIDATION_PR_REQUIRED', message: 'canonical pull-request head is unavailable' });
+  const pullRequest = currentState.pullRequest;
+  const preimageBody = currentState.comment?.body ?? '';
+  const preimage = { commentId: currentState.comment?.id ?? null, body: preimageBody, digest: summaryPreimageDigest(preimageBody) };
+  const evidenceDigest = sha256File(path.resolve(cwd, values.summaryFile!));
+  const archiveGeneration = options.archiveGeneration ?? archiveManualValidationGeneration;
+  let transactionResult = readManualValidationTransaction(resolved.taskDir, { taskId: resolved.taskId, prNumber: pullRequest.number, prHeadSha: pullRequest.head.sha, evidenceDigest, artifact: values.artifact! });
+  let previousTransaction: ManualValidationTransaction | null = null;
+  if (!transactionResult.ok && transactionResult.error.code === 'MANUAL_VALIDATION_TRANSACTION_IDENTITY_MISMATCH') {
+    const existing = readManualValidationTransaction(resolved.taskDir);
+    if (!existing.ok) return result('failed', existing.error);
+    if (!['aborted', 'recovery-required', 'committed'].includes(existing.value.phase)) return result('failed', transactionResult.error);
+    try { validateManualValidationGenerationArchive(resolved.taskDir, existing.value, existing.value.phase === 'committed'); }
+    catch (error) { return result('failed', { code: 'MANUAL_VALIDATION_TRANSACTION_RECOVERY_REQUIRED', message: error instanceof Error ? error.message : String(error) }); }
+    previousTransaction = existing.value;
+    transactionResult = { ok: false, error: { code: 'MANUAL_VALIDATION_TRANSACTION_MISSING', message: 'previous failed transaction was archived for a new pull-request head' } };
+  }
+  if (!transactionResult.ok && transactionResult.error.code !== 'MANUAL_VALIDATION_TRANSACTION_MISSING') return result('failed', transactionResult.error);
+  if (transactionResult.ok && transactionResult.value.phase === 'committed') return result('applied', null, { transaction: transactionResult.value, receipt: transactionResult.value.committedReceipt, idempotent: true });
+  const openStarted = transactionResult.ok ? { present: false, transactionId: null } : openManualValidationStarted(resolved.taskMdPath);
+  if (openStarted.present && !openStarted.transactionId) {
+    return result('failed', { code: 'MANUAL_VALIDATION_TRANSACTION_RECOVERY_REQUIRED', message: 'open manual-validation started event has no recoverable transactionId' });
+  }
+  if (previousTransaction && openStarted.transactionId === previousTransaction.transactionId) {
+    return result('failed', { code: 'MANUAL_VALIDATION_TRANSACTION_RECOVERY_REQUIRED', message: 'previous manual-validation generation is still open; retry the existing transaction before starting a new generation' });
+  }
+  const transactionId = transactionResult.ok
+    ? transactionResult.value.transactionId
+    : (openStarted.transactionId ?? values.transactionId ?? `mv-${Date.now()}`);
+  const finalBodyWithoutReceipt = fs.readFileSync(path.resolve(cwd, values.summaryFile!), 'utf8');
+  const pendingBody = manualSummaryBody(finalBodyWithoutReceipt, 'pending', transactionId);
+  const createTransaction = (): ManualValidationTransaction => createManualValidationTransaction({
+    transactionId,
+    taskId: resolved.taskId,
+    prNumber: pullRequest.number,
+    prHeadSha: pullRequest.head.sha,
+    evidenceDigest,
+    summaryPreimage: preimage,
+    pendingSummaryDigest: summaryPreimageDigest(pendingBody),
+    finalSummaryDigest: manualValidationFinalSummaryDigest(manualSummaryBody(finalBodyWithoutReceipt, 'final', transactionId, '<receipt>', evidenceDigest, pullRequest.head.sha)),
+    artifact: values.artifact!,
+    attempt: 1,
+    createdAt: new Date().toISOString(),
+    updatedAt: new Date().toISOString()
+  });
+  let transaction: ManualValidationTransaction;
+  const idempotent = transactionResult.ok;
+  let startedEventApplied = false;
+  if (!transactionResult.ok) {
+    transaction = createTransaction();
+    const started = applyTaskEvent({ taskRef, event: 'manual-validation.started', agent, initiator: 'model', requestId: transactionId, reasonCode: 'user-request', transactionId }, { lockAlreadyHeld: true, repoRoot: cwd });
+    if (started.status === 'failed') return result('failed', started.error ?? { code: 'MANUAL_VALIDATION_TRANSACTION_FAILED', message: 'manual-validation started event failed' });
+    startedEventApplied = true;
+    if (previousTransaction) {
+      try { archiveGeneration(resolved.taskDir, previousTransaction, previousTransaction.phase === 'committed'); }
+      catch (error) { return result('failed', { code: 'MANUAL_VALIDATION_TRANSACTION_RECOVERY_REQUIRED', message: error instanceof Error ? error.message : String(error) }); }
+    }
+    writeManualValidationTransactionAtomic(resolved.taskDir, transaction);
+  } else {
+    transaction = transactionResult.value;
+    if (['aborted', 'recovery-required'].includes(transaction.phase)) {
+      const retried = retryManualValidationTransaction(transaction);
+      if (!retried.ok) return result('failed', retried.error);
+      transaction = retried.value;
+      writeManualValidationTransactionAtomic(resolved.taskDir, transaction);
+    }
+  }
+  if (transaction.phase === 'prepared' && !startedEventApplied) {
+    const started = applyTaskEvent({ taskRef, event: 'manual-validation.started', agent, initiator: 'model', requestId: transaction.transactionId, reasonCode: 'user-request', transactionId: transaction.transactionId }, { lockAlreadyHeld: true, repoRoot: cwd });
+    if (started.status === 'failed') return result('failed', started.error ?? { code: 'MANUAL_VALIDATION_TRANSACTION_FAILED', message: 'manual-validation started event failed' });
+  }
+  if (prepareOnly) return result('applied', null, { transaction, prepared: true, idempotent });
+  const transactionFailure = (failure: { code: string; message: string }): never => {
+    throw new Error(`${failure.code}: ${failure.message}`);
+  };
+  const transitionAndPersist = (
+    phase: Parameters<typeof transitionManualValidationTransaction>[1],
+    patch: Parameters<typeof transitionManualValidationTransaction>[2] = {}
+  ): void => {
+    const next = transitionManualValidationTransaction(transaction, phase, patch);
+    if (!next.ok) throw new Error(`${next.error.code}: ${next.error.message}`);
+    transaction = next.value;
+    writeManualValidationTransactionAtomic(resolved.taskDir, transaction);
+  };
+  try {
+    if (transaction.phase === 'prepared') {
+      const staged = await syncPullRequestSummary(taskRef, {
+        cwd, client: options.client, agent, body: pendingBody, changeReportFile: path.resolve(cwd, values.changeReportFile!), primaryResult: primaryResult as 'pr_created' | 'pr_reused' | 'no_op', strict: true,
+        manualValidation: { phase: 'pending' }, lockAlreadyHeld: true
+      });
+      if (!['applied', 'no-op'].includes(staged.status)) transactionFailure(staged.error ?? { code: 'MANUAL_VALIDATION_TRANSACTION_FAILED', message: 'pending summary staging failed' });
+      transitionAndPersist('summary-staged');
+    }
+    let receiptResult = readManualValidationReceipt(resolved.taskDir, {
+      transactionId: transaction.transactionId,
+      taskId: resolved.taskId,
+      prNumber: pullRequest.number,
+      prHeadSha: pullRequest.head.sha,
+      evidenceDigest: transaction.evidenceDigest,
+      artifact: values.artifact!
+    });
+    if (!receiptResult.ok && receiptResult.error.code !== 'MANUAL_VALIDATION_RECEIPT_MISSING') transactionFailure(receiptResult.error);
+    let receipt: ManualValidationReceipt;
+    if (receiptResult.ok) {
+      receipt = receiptResult.value;
+    } else {
+      receipt = createManualValidationReceipt({
+      transactionId: transaction.transactionId,
+      taskId: resolved.taskId,
+      prNumber: pullRequest.number,
+      prHeadSha: pullRequest.head.sha,
+      evidenceDigest: transaction.evidenceDigest,
+      artifact: values.artifact!,
+      artifactSha256: sha256File(artifactPath),
+      pendingSummaryDigest: transaction.pendingSummaryDigest,
+      finalSummaryDigest: transaction.finalSummaryDigest,
+      committedAt: new Date().toISOString()
+      });
+      writeManualValidationReceiptAtomic(resolved.taskDir, receipt);
+    }
+    if (transaction.phase === 'summary-staged') {
+      transitionAndPersist('receipt-committed', { committedReceipt: receipt.receiptDigest });
+    }
+    if (transaction.phase === 'receipt-committed' && !transaction.eventAppended) {
+      const completed = applyTaskEvent({ taskRef, event: 'manual-validation.completed', agent, initiator: 'model', requestId: transaction.transactionId, reasonCode: 'user-request', artifact: values.artifact, summaryResult: 'human-confirmed validation and committed receipt', transactionId: transaction.transactionId, receiptDigest: receipt.receiptDigest, prHeadSha: receipt.prHeadSha }, { lockAlreadyHeld: true, repoRoot: cwd });
+      if (completed.status === 'failed') transactionFailure(completed.error ?? { code: 'MANUAL_VALIDATION_TRANSACTION_FAILED', message: 'manual-validation completion event failed' });
+      transitionAndPersist('receipt-committed', { eventAppended: true });
+    }
+    if (transaction.phase === 'receipt-committed') {
+      transitionAndPersist('final-promotion-in-progress');
+    }
+    const promoted = await syncPullRequestSummary(taskRef, {
+      cwd, client: options.client, agent, body: manualSummaryBody(finalBodyWithoutReceipt, 'final', transaction.transactionId, receipt.receiptDigest, receipt.evidenceDigest, receipt.prHeadSha), changeReportFile: path.resolve(cwd, values.changeReportFile!), primaryResult, strict: true,
+      manualValidation: { phase: 'final', transactionId: transaction.transactionId, receiptDigest: receipt.receiptDigest, prHeadSha: receipt.prHeadSha, authority: 'coordinator' }, lockAlreadyHeld: true
+    });
+    if (!['applied', 'no-op'].includes(promoted.status)) transactionFailure(promoted.error ?? { code: 'MANUAL_VALIDATION_TRANSACTION_RECOVERY_REQUIRED', message: 'final summary promotion failed' });
+    const postWrite = await summaryCommentState(taskRef, { cwd, client: options.client });
+    if (!postWrite.comment?.body.includes('### ✅ Manual Validation Passed') || postWrite.pullRequest?.head.sha !== receipt.prHeadSha || !manualValidationFinalSummaryProjectionMatches(postWrite.comment.body, receipt)) transactionFailure({ code: 'MANUAL_VALIDATION_TRANSACTION_RECOVERY_REQUIRED', message: 'final summary post-write verification failed' });
+    transitionAndPersist('committed', { postWriteVerified: true });
+    return result('applied', null, { transaction, receipt, idempotent: false });
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (transaction.phase === 'final-promotion-in-progress') {
+      try {
+        await syncPullRequestSummary(taskRef, {
+          cwd, client: options.client, agent, body: pendingBody, changeReportFile: path.resolve(cwd, values.changeReportFile!), primaryResult: primaryResult as 'pr_created' | 'pr_reused' | 'no_op', strict: true,
+          manualValidation: { phase: 'pending' }, lockAlreadyHeld: true
+        });
+      } catch {
+        // Preserve recovery-required when pending compensation cannot be confirmed.
+      }
+    }
+    const failedTransaction = transitionManualValidationTransaction(transaction, 'recovery-required', { error: message.slice(0, 400) });
+    if (failedTransaction.ok) writeManualValidationTransactionAtomic(resolved.taskDir, failedTransaction.value);
+    return result('failed', { code: 'MANUAL_VALIDATION_TRANSACTION_RECOVERY_REQUIRED', message });
+  }
+}
+
+function parse(args: string[], start: number): { values: Record<string, string>; error?: string } {
+  const values: Record<string, string> = {};
+  for (let index = start; index < args.length; index += 1) {
+    const flag = args[index]!;
+    if (flag === '--prepare') {
+      if (values.prepare) return { values, error: `duplicate option '${flag}'` };
+      values.prepare = 'true';
+      continue;
+    }
+    if (!['--format', '--cwd', '--artifact', '--summary-file', '--change-report-file', '--agent', '--result'].includes(flag)) return { values, error: `unknown option '${flag}'` };
+    const value = args[++index];
+    if (!value || value.startsWith('--')) return { values, error: `option '${flag}' requires a value` };
+    const key = flag.slice(2).replace(/-([a-z])/gu, (_, letter: string) => letter.toUpperCase());
+    if (values[key]) return { values, error: `duplicate option '${flag}'` };
+    values[key] = value;
+  }
+  return { values };
+}
+
+async function manualValidation(args: string[] = []): Promise<void> {
+  if (!ensureInternalHandlerRoute('manual-validation', args)) return;
+  if (args[0] === '--help' || args[0] === '-h') { process.stdout.write(`${USAGE}\n`); return; }
+  const operation = args[0];
+  const isTransaction = operation === 'transaction' && internalHandlerRoute('manual-validation', 'transaction', operation);
+  if (!isTransaction) { printFailure('json', { code: 'MANUAL_VALIDATION_ARGS_INVALID', message: 'transaction operation is required' }); return; }
+  const taskRef = args[1];
+  if (!taskRef || taskRef.startsWith('--')) { printFailure('json', { code: 'MANUAL_VALIDATION_ARGS_INVALID', message: 'task ref is required' }); return; }
+  const parsed = parse(args, 2);
+  if (parsed.error) { printFailure('json', { code: 'MANUAL_VALIDATION_ARGS_INVALID', message: parsed.error }); return; }
+  const values = parsed.values;
+  const format = values.format === 'text' ? 'text' : 'json';
+  const output = await executeManualValidationTransaction(taskRef, values, path.resolve(values.cwd ?? process.cwd()));
+  process.stdout.write(format === 'json' ? `${JSON.stringify(output)}\n` : `${output.status === 'applied' ? 'Manual validation transaction committed.' : `${output.error?.code}: ${output.error?.message}`}\n`);
+  if (output.status === 'failed') process.exitCode = 1;
+}
+
+export { executeManualValidationTransaction, manualValidation };

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(await 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(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(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,6 +10,7 @@ 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 <token> [--cwd <path>]
        agent-infra-internal platform-comment owner <task-ref> [--cwd <path>]
@@ -53,16 +54,22 @@ function readBodyFile(value: string, cwd: string): string {
 }
 
 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') {
+  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));
@@ -70,13 +77,13 @@ async function platformComment(args: string[] = []): Promise<void> {
     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(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;
@@ -86,6 +93,7 @@ async function platformComment(args: string[] = []): Promise<void> {
     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; }

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';
 
@@ -11,8 +12,9 @@ function fail(message: 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) {

package/lib/internal/platform-issue.ts

@@ -8,6 +8,7 @@ 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>]
@@ -60,9 +61,15 @@ function oneOf(values: Record<string, string | boolean>, name: string, allowed:
 }
 
 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,15 +82,15 @@ async function platformIssue(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(await 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') {
+  if (internalHandlerRoute('platform-issue', 'create', operation)) {
     finish(await createPlatformIssue(taskRef, { cwd, agent: values.agent, dryRun: values.dryRun === true })); return;
   }
-  if (operation === 'bind') {
+  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;
   }

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

package/lib/internal/platform-pr-review.ts

@@ -5,6 +5,7 @@ import { inspectPlatformPullRequestByNumber } from '../platform/pull-requests.ts
 import { listPrReviews, publishPrReview } from '../platform/pr-review.ts';
 import type { PrReviewEvent } from '../platform/pr-review.ts';
 import type { PlatformResult } from '../platform/types.ts';
+import { ensureInternalHandlerRoute, internalHandlerRoute } from './cli-route-inventory.ts';
 
 const USAGE = `Usage: agent-infra-internal platform-pr-review inspect --pr <token> [--cwd <path>]
        agent-infra-internal platform-pr-review list --pr <token> [--cwd <path>]
@@ -51,9 +52,14 @@ function readBodyFile(value: string, cwd: string): string {
 }
 
 async function platformPrReview(args: string[] = []): Promise<void> {
+  if (!ensureInternalHandlerRoute('platform-pr-review', args)) return;
   if (args[0] === '--help' || args[0] === '-h') { process.stdout.write(USAGE); return; }
   const operation = args[0];
-  if (!operation || !['inspect', 'list', 'publish'].includes(operation)) { fail('a valid operation is required'); return; }
+  if (!operation || ![
+    internalHandlerRoute('platform-pr-review', 'inspect', operation),
+    internalHandlerRoute('platform-pr-review', 'list', operation),
+    operation === 'publish'
+  ].some(Boolean)) { fail('a valid operation is required'); return; }
   const parsed = parse(args, 1);
   if (parsed.error) { fail(parsed.error); return; }
   const values = parsed.values;
@@ -67,19 +73,24 @@ async function platformPrReview(args: string[] = []): Promise<void> {
   if (unexpected) { fail(`${operation} does not accept --${unexpected}`); return; }
   const pr = values.pr;
   if (typeof pr !== 'string' || !pr) { fail(`${operation} requires --pr <token>`); return; }
-  if (operation === 'inspect') {
+  if (internalHandlerRoute('platform-pr-review', 'inspect', operation)) {
     finish(await inspectPlatformPullRequestByNumber(pr, { cwd }));
     return;
   }
-  if (operation === 'list') {
+  if (internalHandlerRoute('platform-pr-review', 'list', operation)) {
     finish(await listPrReviews(pr, { cwd }));
     return;
   }
   const scope = typeof values.scope === 'string' ? values.scope : '';
+  const publishSelector = /^TASK-\d{8}-\d{6}$/u.test(scope) ? 'publish-task' : /^pr\d+$/u.test(scope) ? 'publish-pr' : '';
   const round = Number(values.round);
   const commit = typeof values.commit === 'string' ? values.commit : '';
   const event = values.event as string;
   if (!scope || !/^(?:pr\d+|TASK-\d{8}-\d{6})$/.test(scope)) { fail('publish requires --scope <taskId|pr{N}>'); return; }
+  if (!internalHandlerRoute('platform-pr-review', 'publish-task', publishSelector)
+    && !internalHandlerRoute('platform-pr-review', 'publish-pr', publishSelector)) {
+    fail('publish scope is not registered'); return;
+  }
   if (!Number.isInteger(round) || round <= 0) { fail('publish requires a positive --round'); return; }
   if (!/^[0-9a-f]{7,40}$/i.test(commit)) { fail('publish requires --commit <sha>'); return; }
   if (!['COMMENT', 'APPROVE', 'REQUEST_CHANGES'].includes(event)) { fail('publish requires --event <COMMENT|APPROVE|REQUEST_CHANGES>'); return; }