@fitlab-ai/agent-infra 0.9.13 → 0.9.15

package/dist/lib/internal/manual-validation.js

@@ -0,0 +1,322 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { locateActivityLog, pairEntries } from '../task/activity-log.js';
+import { resolveTaskRef } from '../task/resolve-ref.js';
+import { applyTaskEvent } from '../task/events.js';
+import { TaskExecutionLockError, withTaskExecutionLock } from '../task/task-execution-lock.js';
+import { normalizeAgentToken } from '../agent-clients/tokens.js';
+import { createManualValidationReceipt, manualValidationFinalSummaryDigest, manualValidationFinalSummaryProjectionMatches, readManualValidationReceipt, writeManualValidationReceiptAtomic } from '../task/manual-validation-receipt.js';
+import { archiveManualValidationGeneration, createManualValidationTransaction, readManualValidationTransaction, retryManualValidationTransaction, summaryPreimageDigest, transitionManualValidationTransaction, validateManualValidationGenerationArchive, writeManualValidationTransactionAtomic } from '../task/manual-validation-transaction.js';
+import { sha256File } from '../task/artifact-receipts.js';
+import { summaryCommentState, syncPullRequestSummary } from '../platform/pr-summary.js';
+import { ensureInternalHandlerRoute, internalHandlerRoute } from './cli-route-inventory.js';
+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>]`;
+function result(status, error = null, extra = {}) {
+    return { status, changed: false, error, ...extra };
+}
+function printFailure(format, error) {
+    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, phase, transactionId, receiptDigest = '', evidenceDigest = '', prHeadSha = '') {
+    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) {
+    let content;
+    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, values, cwd, options = {}) {
+    const prepareOnly = values.prepare === 'true';
+    const required = prepareOnly
+        ? ['artifact', 'summaryFile', 'agent']
+        : ['artifact', 'summaryFile', 'changeReportFile', 'agent'];
+    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, prepareOnly, options));
+    }
+    catch (error) {
+        if (error instanceof TaskExecutionLockError)
+            return result('failed', { code: error.code, message: error.message });
+        throw error;
+    }
+}
+async function executeManualValidationTransactionLocked(taskRef, values, cwd, resolved, agent, primaryResult, prepareOnly, options) {
+    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 = 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 = () => 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;
+    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) => {
+        throw new Error(`${failure.code}: ${failure.message}`);
+    };
+    const transitionAndPersist = (phase, patch = {}) => {
+        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, 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;
+        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, 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, start) {
+    const values = {};
+    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) => letter.toUpperCase());
+        if (values[key])
+            return { values, error: `duplicate option '${flag}'` };
+        values[key] = value;
+    }
+    return { values };
+}
+async function manualValidation(args = []) {
+    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 };
+//# sourceMappingURL=manual-validation.js.map

package/dist/lib/internal/platform-checks.js

@@ -1,5 +1,6 @@
 import path from 'node:path';
 import { fetchPlatformCheckLogs, inspectPullRequestReadiness, resolvePlatformCheckRun, watchPullRequestReadiness } from '../platform/pr-checks.js';
+import { ensureInternalHandlerRoute, internalHandlerRoute } from './cli-route-inventory.js';
 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>]
        agent-infra-internal platform-checks resolve-run <task-ref> --check-name <name> [--details-url <url>] [--cwd <path>]
@@ -43,12 +44,19 @@ function positive(value) {
     return Number.isFinite(number) && number > 0 ? number : null;
 }
 async function platformChecks(args = []) {
+    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)) {
+    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;
     }
@@ -75,11 +83,11 @@ async function platformChecks(args = []) {
         fail(`${operation} does not accept --${unexpected}`);
         return;
     }
-    if (operation === 'inspect') {
+    if (internalHandlerRoute('platform-checks', 'inspect', operation)) {
         finish(await inspectPullRequestReadiness(taskRef, { cwd }));
         return;
     }
-    if (operation === 'resolve-run') {
+    if (internalHandlerRoute('platform-checks', 'resolve-run', operation)) {
         if (!values.checkName) {
             fail('resolve-run requires --check-name');
             return;
@@ -87,7 +95,7 @@ async function platformChecks(args = []) {
         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) {
@@ -97,6 +105,10 @@ async function platformChecks(args = []) {
         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) {

package/dist/lib/internal/platform-comment.js

@@ -3,6 +3,7 @@ import path from 'node:path';
 import { normalizeAgentToken, AGENT_USAGE_HINT } from '../agent-clients/tokens.js';
 import { checkPlatformCommentOwner, listPlatformComments, syncPlatformComment } from '../platform/issue-comments.js';
 import { backfillCompletionComments } from '../platform/completion-backfill.js';
+import { ensureInternalHandlerRoute, internalHandlerRoute } from './cli-route-inventory.js';
 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>]
@@ -48,12 +49,19 @@ function readBodyFile(value, cwd) {
     return fs.readFileSync(path.resolve(cwd, value), 'utf8');
 }
 async function platformComment(args = []) {
+    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)) {
+    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;
     }
@@ -69,7 +77,7 @@ async function platformComment(args = []) {
         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>');
@@ -83,7 +91,7 @@ async function platformComment(args = []) {
         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}'`);
@@ -92,7 +100,7 @@ async function platformComment(args = []) {
         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}'`);
@@ -111,6 +119,10 @@ async function platformComment(args = []) {
         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))) {

package/dist/lib/internal/platform-context.js

@@ -1,5 +1,6 @@
 import path from 'node:path';
 import { resolvePlatformContext } from '../platform/context.js';
+import { ensureInternalHandlerRoute, internalHandlerRoute } from './cli-route-inventory.js';
 const USAGE = 'Usage: agent-infra-internal platform-context resolve [--cwd <path>]\n';
 function fail(message) {
     process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, error: { code: 'PLATFORM_PAYLOAD_INVALID', message } })}\n`);
@@ -7,11 +8,13 @@ function fail(message) {
     process.exitCode = 1;
 }
 async function platformContext(args = []) {
+    if (!ensureInternalHandlerRoute('platform-context', args))
+        return;
     if (args[0] === '--help' || args[0] === '-h') {
         process.stdout.write(USAGE);
         return;
     }
-    if (args[0] !== 'resolve') {
+    if (!internalHandlerRoute('platform-context', 'resolve', args[0] ?? '')) {
         fail("operation must be 'resolve'");
         return;
     }

package/dist/lib/internal/platform-issue.js

@@ -1,6 +1,7 @@
 import path from 'node:path';
 import { normalizeAgentToken, AGENT_USAGE_HINT } from '../agent-clients/tokens.js';
 import { bindPlatformIssue, createPlatformIssue, inspectPlatformIssue, syncPlatformIssue } from '../platform/issues.js';
+import { ensureInternalHandlerRoute, internalHandlerRoute } from './cli-route-inventory.js';
 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 <token> --agent <agent> [--dry-run] [--cwd <path>]
@@ -55,12 +56,19 @@ function oneOf(values, name, allowed) {
     return value;
 }
 async function platformIssue(args = []) {
+    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)) {
+    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;
     }
@@ -85,7 +93,7 @@ async function platformIssue(args = []) {
         fail(`${operation} does not accept --${unexpected}`);
         return;
     }
-    if (operation === 'inspect') {
+    if (internalHandlerRoute('platform-issue', 'inspect', operation)) {
         finish(await inspectPlatformIssue(taskRef, { cwd }));
         return;
     }
@@ -99,11 +107,11 @@ async function platformIssue(args = []) {
         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;

package/dist/lib/internal/platform-metadata.js

@@ -0,0 +1,88 @@
+import path from 'node:path';
+import { initializeLabels, initializeMilestones } from '../platform/repository-metadata.js';
+import { ensureInternalHandlerRoute, internalHandlerRoute } from './cli-route-inventory.js';
+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) {
+    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, preserveMilestoneFallback = false) {
+    if (preserveMilestoneFallback && result.error && typeof result.error === 'object'
+        && result.error.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) {
+    let cwd = process.cwd();
+    let cleanup = false;
+    let history = false;
+    const seen = new Set();
+    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 = []) {
+    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 };
+//# sourceMappingURL=platform-metadata.js.map