@fitlab-ai/agent-infra 0.9.13 → 0.9.14

package/dist/lib/internal/task-operation-registry.js

@@ -0,0 +1,421 @@
+import fs from 'node:fs';
+import { accessSandboxTaskView, parseSandboxTaskView, taskViewFromStatus } from '../sandbox/control/task-view.js';
+import { resolveTaskRef } from '../task/resolve-ref.js';
+import { PUBLIC_CLI_COMMAND_ALIASES, PUBLIC_CLI_SELECTOR_ALIASES, internalRouteSelector } from './cli-route-inventory.js';
+const descriptor = (dispatcher, command, selector, scope, effect, taskRefSource = scope === 'non-task' ? 'none' : 'argv') => ({ dispatcher, command, selector, scope, effect, taskRefSource, guardBeforeImport: true });
+function internalTaskRoutes() {
+    return [
+        descriptor('internal', 'task-create', 'input', 'conditional', 'progress'),
+        descriptor('internal', 'task-qualification', 'proposal', 'task-bound', 'progress'),
+        descriptor('internal', 'task-qualification', 'confirm', 'task-bound', 'progress'),
+        descriptor('internal', 'task-qualification', 'supersede', 'task-bound', 'progress'),
+        descriptor('internal', 'task-qualification', 'revoke', 'task-bound', 'progress'),
+        descriptor('internal', 'sandbox-control', 'serve', 'non-task', 'progress', 'none'),
+        descriptor('internal', 'sandbox-control', 'execute', 'non-task', 'progress', 'none'),
+        descriptor('internal', 'sandbox-control', 'recover', 'conditional', 'recovery', 'delegated'),
+        descriptor('internal', 'sandbox-control', 'client', 'conditional', 'progress', 'delegated'),
+        descriptor('internal', 'agent-client', 'next-steps', 'non-task', 'diagnostic', 'none'),
+        descriptor('internal', 'agent-client', 'model-selection', 'non-task', 'diagnostic', 'none'),
+        descriptor('internal', 'codex-lifecycle', 'preflight', 'non-task', 'diagnostic', 'none'),
+        descriptor('internal', 'codex-lifecycle', 'capability-arm', 'conditional', 'progress'),
+        descriptor('internal', 'codex-lifecycle', 'hook-event', 'conditional', 'progress'),
+        descriptor('internal', 'codex-lifecycle', 'resolve-start', 'conditional', 'progress'),
+        descriptor('internal', 'codex-lifecycle', 'resolve-stop', 'conditional', 'progress'),
+        descriptor('internal', 'codex-lifecycle', 'consume', 'conditional', 'progress'),
+        descriptor('internal', 'codex-sandbox-controller', 'verify-context', 'task-bound', 'diagnostic'),
+        descriptor('internal', 'codex-sandbox-controller', 'run', 'task-bound', 'progress'),
+        descriptor('internal', 'git-workflow', 'inspect', 'conditional', 'diagnostic'),
+        descriptor('internal', 'git-workflow', 'preview-tree', 'conditional', 'diagnostic'),
+        descriptor('internal', 'git-workflow', 'snapshot', 'conditional', 'diagnostic'),
+        descriptor('internal', 'git-workflow', 'compare-trees', 'conditional', 'diagnostic'),
+        descriptor('internal', 'git-workflow', 'commit', 'task-bound', 'progress', 'input'),
+        descriptor('internal', 'git-workflow', 'push-rebased', 'task-bound', 'remote-write'),
+        descriptor('internal', 'task-delivery', 'deliver', 'task-bound', 'remote-write'),
+        descriptor('internal', 'release-workflow', 'inspect', 'non-task', 'diagnostic', 'none'),
+        descriptor('internal', 'release-workflow', 'prepare', 'non-task', 'progress', 'none'),
+        descriptor('internal', 'release-workflow', 'publish', 'non-task', 'remote-write', 'none'),
+        descriptor('internal', 'release-workflow', 'post-prepare', 'non-task', 'progress', 'none'),
+        descriptor('internal', 'release-workflow', 'post-publish', 'non-task', 'remote-write', 'none'),
+        descriptor('internal', 'platform-release-notes', 'context', 'non-task', 'diagnostic', 'none'),
+        descriptor('internal', 'platform-release-notes', 'stage', 'non-task', 'artifact-write', 'none'),
+        descriptor('internal', 'platform-release-notes', 'publish', 'non-task', 'remote-write', 'none'),
+        descriptor('internal', 'platform-security', 'read', 'non-task', 'diagnostic', 'none'),
+        descriptor('internal', 'platform-security', 'dismiss', 'non-task', 'remote-write', 'none'),
+        descriptor('internal', 'platform-metadata', 'init-labels', 'non-task', 'remote-write', 'none'),
+        descriptor('internal', 'platform-metadata', 'init-milestones', 'non-task', 'remote-write', 'none'),
+        descriptor('internal', 'platform-context', 'resolve', 'non-task', 'diagnostic', 'none'),
+        descriptor('internal', 'platform-comment', 'list', 'non-task', 'diagnostic', 'none'),
+        descriptor('internal', 'platform-comment', 'owner', 'task-bound', 'diagnostic'),
+        descriptor('internal', 'platform-comment', 'backfill', 'task-bound', 'remote-write'),
+        descriptor('internal', 'platform-comment', 'sync', 'task-bound', 'remote-write'),
+        descriptor('internal', 'platform-issue', 'inspect', 'task-bound', 'diagnostic'),
+        descriptor('internal', 'platform-issue', 'create', 'task-bound', 'remote-write'),
+        descriptor('internal', 'platform-issue', 'bind', 'task-bound', 'remote-write'),
+        descriptor('internal', 'platform-issue', 'sync', 'task-bound', 'remote-write'),
+        descriptor('internal', 'platform-pr', 'inspect', 'task-bound', 'diagnostic'),
+        descriptor('internal', 'platform-pr', 'summary-context', 'task-bound', 'diagnostic'),
+        descriptor('internal', 'platform-pr', 'resolve-external', 'task-bound', 'remote-write'),
+        descriptor('internal', 'platform-pr', 'create', 'task-bound', 'remote-write'),
+        descriptor('internal', 'platform-pr', 'bind', 'task-bound', 'remote-write'),
+        descriptor('internal', 'platform-pr', 'skip', 'task-bound', 'progress'),
+        descriptor('internal', 'platform-pr', 'sync', 'task-bound', 'remote-write'),
+        descriptor('internal', 'platform-pr', 'change-report', 'task-bound', 'remote-write'),
+        descriptor('internal', 'platform-pr', 'summary-sync', 'task-bound', 'remote-write'),
+        descriptor('internal', 'platform-pr', 'sync-in-labels', 'non-task', 'remote-write', 'none'),
+        descriptor('internal', 'platform-pr-review', 'inspect', 'non-task', 'diagnostic', 'none'),
+        descriptor('internal', 'platform-pr-review', 'list', 'non-task', 'diagnostic', 'none'),
+        descriptor('internal', 'platform-pr-review', 'publish-pr', 'non-task', 'remote-write', 'none'),
+        descriptor('internal', 'platform-pr-review', 'publish-task', 'task-bound', 'remote-write'),
+        descriptor('internal', 'pr-review-grade', 'decide', 'non-task', 'diagnostic', 'none'),
+        descriptor('internal', 'pr-review-grade', 'resolve-host', 'non-task', 'diagnostic', 'none'),
+        descriptor('internal', 'pr-review-grade', 'verify-artifact', 'non-task', 'diagnostic', 'none'),
+        descriptor('internal', 'platform-checks', 'inspect', 'conditional', 'diagnostic'),
+        descriptor('internal', 'platform-checks', 'watch', 'conditional', 'diagnostic'),
+        descriptor('internal', 'platform-checks', 'resolve-run', 'conditional', 'diagnostic'),
+        descriptor('internal', 'platform-checks', 'logs', 'conditional', 'diagnostic'),
+        descriptor('internal', 'task-context', 'resolve', 'task-bound', 'diagnostic'),
+        descriptor('internal', 'task-ledger', 'decision-next-id', 'task-bound', 'diagnostic'),
+        descriptor('internal', 'task-ledger', 'stage-status', 'task-bound', 'diagnostic'),
+        descriptor('internal', 'task-ledger', 'finding-upsert', 'task-bound', 'progress'),
+        descriptor('internal', 'task-ledger', 'finding-respond', 'task-bound', 'progress'),
+        descriptor('internal', 'task-ledger', 'finding-review', 'task-bound', 'progress'),
+        descriptor('internal', 'task-ledger', 'decision-upsert', 'task-bound', 'progress'),
+        descriptor('internal', 'task-ledger', 'rework-intent-upsert', 'task-bound', 'progress'),
+        descriptor('internal', 'task-warning', 'list', 'task-bound', 'diagnostic'),
+        descriptor('internal', 'task-warning', 'add', 'task-bound', 'progress'),
+        descriptor('internal', 'task-warning', 'set-status', 'task-bound', 'progress'),
+        descriptor('internal', 'task-activity', 'pr-review-inspect', 'task-bound', 'diagnostic'),
+        descriptor('internal', 'task-activity', 'pr-review-start', 'task-bound', 'progress'),
+        descriptor('internal', 'task-activity', 'pr-review-complete', 'task-bound', 'progress'),
+        descriptor('internal', 'task-activity', 'pr-review-terminate', 'task-bound', 'progress'),
+        descriptor('internal', 'task-artifact', 'inspect', 'task-bound', 'diagnostic'),
+        descriptor('internal', 'task-artifact', 'init', 'task-bound', 'artifact-write'),
+        descriptor('internal', 'task-artifact', 'repair', 'task-bound', 'artifact-write'),
+        descriptor('internal', 'task-artifact', 'finalize-local', 'task-bound', 'artifact-write'),
+        descriptor('internal', 'task-orchestration', 'status', 'task-bound', 'diagnostic'),
+        descriptor('internal', 'task-orchestration', 'progress', 'task-bound', 'progress'),
+        descriptor('internal', 'task-review', 'finalize-summary', 'task-bound', 'progress'),
+        descriptor('internal', 'task-event', 'event', 'task-bound', 'progress'),
+        descriptor('internal', 'task-invalidation', 'reconcile', 'task-bound', 'progress'),
+        descriptor('internal', 'task-override', 'diagnose', 'task-bound', 'diagnostic'),
+        descriptor('internal', 'task-override', 'issue', 'task-bound', 'progress'),
+        descriptor('internal', 'task-override', 'consume', 'task-bound', 'progress'),
+        descriptor('internal', 'task-lifecycle', 'intent', 'task-bound', 'progress'),
+        descriptor('internal', 'task-finalization', 'complete', 'task-bound', 'progress'),
+        descriptor('internal', 'task-short-id', 'list', 'conditional', 'diagnostic'),
+        descriptor('internal', 'task-short-id', 'list-verify', 'conditional', 'diagnostic'),
+        descriptor('internal', 'task-short-id', 'alloc', 'task-bound', 'progress'),
+        descriptor('internal', 'task-short-id', 'release', 'task-bound', 'progress'),
+        descriptor('internal', 'task-short-id', 'resolve', 'task-bound', 'progress'),
+        descriptor('internal', 'task-snapshot', 'snapshot', 'conditional', 'diagnostic'),
+        descriptor('internal', 'task-verify', 'event', 'task-bound', 'terminal-verdict'),
+        descriptor('internal', 'task-validate', 'snapshot', 'conditional', 'diagnostic'),
+        descriptor('internal', 'task-validate', 'inplace', 'task-bound', 'progress')
+    ];
+}
+function publicTaskRoutes() {
+    return [
+        descriptor('public', 'agent-client', 'list', 'non-task', 'diagnostic', 'none'),
+        descriptor('public', 'agent-client', 'status', 'non-task', 'diagnostic', 'none'),
+        descriptor('public', 'agent-client', 'enable', 'non-task', 'progress', 'none'),
+        descriptor('public', 'agent-client', 'disable', 'non-task', 'progress', 'none'),
+        descriptor('public', 'agent-client', 'configure', 'non-task', 'progress', 'none'),
+        descriptor('public', 'cp', 'cp', 'non-task', 'remote-write', 'none'),
+        descriptor('public', 'data', 'capture', 'non-task', 'diagnostic', 'none'),
+        descriptor('public', 'data', 'verify', 'non-task', 'diagnostic', 'none'),
+        descriptor('public', 'data', 'audit', 'non-task', 'diagnostic', 'none'),
+        descriptor('public', 'data', 'repair', 'non-task', 'progress', 'none'),
+        descriptor('public', 'data', 'export', 'non-task', 'diagnostic', 'none'),
+        descriptor('public', 'decide', 'decide', 'task-bound', 'progress'),
+        descriptor('public', 'help', 'help', 'non-task', 'diagnostic', 'none'),
+        descriptor('public', 'version', 'version', 'non-task', 'diagnostic', 'none'),
+        descriptor('public', 'init', 'init', 'non-task', 'progress', 'none'),
+        descriptor('public', 'merge', 'merge', 'conditional', 'progress'),
+        descriptor('public', 'run', 'create-task', 'conditional', 'progress'),
+        descriptor('public', 'run', 'task-skill', 'task-bound', 'progress'),
+        descriptor('public', 'run', 'recreate', 'task-bound', 'recovery'),
+        descriptor('public', 'sandbox', 'ls', 'conditional', 'diagnostic'),
+        descriptor('public', 'sandbox', 'show', 'conditional', 'diagnostic'),
+        descriptor('public', 'sandbox', 'create', 'conditional', 'recovery'),
+        descriptor('public', 'sandbox', 'exec', 'conditional', 'recovery'),
+        descriptor('public', 'sandbox', 'start', 'conditional', 'recovery'),
+        descriptor('public', 'sandbox', 'rm', 'conditional', 'cleanup'),
+        descriptor('public', 'sandbox', 'prune', 'non-task', 'cleanup', 'none'),
+        descriptor('public', 'sandbox', 'rebuild', 'non-task', 'progress', 'none'),
+        descriptor('public', 'sandbox', 'refresh', 'non-task', 'progress', 'none'),
+        descriptor('public', 'sandbox', 'vm', 'non-task', 'progress', 'none'),
+        descriptor('public', 'server', 'start', 'non-task', 'progress', 'none'),
+        descriptor('public', 'server', 'stop', 'non-task', 'progress', 'none'),
+        descriptor('public', 'server', 'status', 'non-task', 'diagnostic', 'none'),
+        descriptor('public', 'server', 'logs', 'non-task', 'diagnostic', 'none'),
+        descriptor('public', 'server', '__daemon', 'non-task', 'progress', 'none'),
+        descriptor('public', 'task', 'cat', 'task-bound', 'diagnostic'),
+        descriptor('public', 'task', 'decisions', 'task-bound', 'diagnostic'),
+        descriptor('public', 'task', 'files', 'task-bound', 'diagnostic'),
+        descriptor('public', 'task', 'grep', 'task-bound', 'diagnostic'),
+        descriptor('public', 'task', 'issue-body', 'task-bound', 'diagnostic'),
+        descriptor('public', 'task', 'log', 'task-bound', 'diagnostic'),
+        descriptor('public', 'task', 'ls', 'task-bound', 'diagnostic'),
+        descriptor('public', 'task', 'show', 'task-bound', 'diagnostic'),
+        descriptor('public', 'task', 'status', 'task-bound', 'diagnostic'),
+        descriptor('public', 'sync', 'sync', 'non-task', 'progress', 'none'),
+        descriptor('public', 'update', 'update', 'non-task', 'progress', 'none')
+    ];
+}
+export const INTERNAL_OPERATION_DESCRIPTORS = Object.freeze(internalTaskRoutes());
+export const PUBLIC_OPERATION_DESCRIPTORS = Object.freeze(publicTaskRoutes());
+export const TASK_OPERATION_DESCRIPTORS = Object.freeze([
+    ...INTERNAL_OPERATION_DESCRIPTORS,
+    ...PUBLIC_OPERATION_DESCRIPTORS
+]);
+export const INTERNAL_DISPATCHER_ROUTES = Object.freeze([
+    'task-create', 'task-qualification', 'sandbox-control', 'agent-client', 'codex-lifecycle', 'codex-sandbox-controller',
+    'git-workflow', 'task-delivery', 'release-workflow', 'platform-release-notes', 'platform-security', 'platform-metadata', 'platform-context',
+    'platform-comment', 'platform-issue', 'platform-pr', 'platform-pr-review', 'pr-review-grade',
+    'platform-checks', 'task-context', 'task-ledger', 'task-warning', 'task-activity', 'task-artifact',
+    'task-orchestration', 'task-review', 'task-event', 'task-invalidation', 'task-lifecycle',
+    'task-finalization', 'task-override', 'task-short-id', 'task-snapshot', 'task-verify', 'task-validate'
+]);
+export const PUBLIC_DISPATCHER_ROUTES = Object.freeze([
+    'agent-client', 'cp', 'data', 'decide', 'help', 'init', 'merge', 'run', 'sandbox', 'server', 'task', 'sync', 'update', 'version'
+]);
+function first(args) {
+    return args[0] ?? '';
+}
+function optionValue(args, name) {
+    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);
+}
+function publicSelector(command, args) {
+    if (command === 'agent-client' || command === 'data' || command === 'server' || command === 'sandbox' || command === 'task') {
+        const selector = first(args);
+        if (command === 'task') {
+            return PUBLIC_CLI_SELECTOR_ALIASES.task[selector] ?? selector;
+        }
+        return selector;
+    }
+    if (command === 'run') {
+        const skill = optionValue(args, '--skill');
+        if (skill === 'create-task')
+            return 'create-task';
+        if (args.includes('--recreate'))
+            return 'recreate';
+        return skill ? 'task-skill' : '';
+    }
+    return command;
+}
+function descriptorsFor(dispatcher) {
+    return dispatcher === 'internal' ? INTERNAL_OPERATION_DESCRIPTORS : PUBLIC_OPERATION_DESCRIPTORS;
+}
+export function resolveTaskOperation(dispatcher, command, args = []) {
+    const normalizedCommand = dispatcher === 'public'
+        ? PUBLIC_CLI_COMMAND_ALIASES[command] ?? command
+        : command;
+    const selector = dispatcher === 'internal' ? internalRouteSelector(normalizedCommand, args) : publicSelector(normalizedCommand, args);
+    if (!selector)
+        return null;
+    return descriptorsFor(dispatcher).find((item) => item.command === normalizedCommand && item.selector === selector) ?? null;
+}
+export function resolveDelegatedTaskOperation(args) {
+    const [operation, ...rest] = args;
+    if (operation !== 'client' || !rest[0])
+        return null;
+    return resolveTaskOperation('internal', rest[0], rest.slice(1));
+}
+const TASK_MARKER_KEYS = [
+    'AGENT_INFRA_TASK_ID',
+    'AGENT_INFRA_CONTROL_TOKEN',
+    'AGENT_INFRA_CONTROL_GENERATION',
+    'AGENT_INFRA_CONTROL_DIR',
+    'AGENT_INFRA_CONTROL_STATUS_DIR',
+    'AGENT_INFRA_RUNTIME_DIR'
+];
+const TASK_CONTROL_MARKER_KEYS = [
+    'AGENT_INFRA_CONTROL_TOKEN',
+    'AGENT_INFRA_CONTROL_GENERATION',
+    'AGENT_INFRA_CONTROL_DIR',
+    'AGENT_INFRA_CONTROL_STATUS_DIR'
+];
+function taskMarkerState(env) {
+    const present = (key) => Boolean(env[key]);
+    const taskId = present('AGENT_INFRA_TASK_ID');
+    const controls = TASK_CONTROL_MARKER_KEYS.every(present);
+    const runtime = present('AGENT_INFRA_RUNTIME_DIR');
+    const any = TASK_MARKER_KEYS.some(present);
+    if (!any)
+        return 'none';
+    if (taskId && controls && runtime)
+        return 'task-bound';
+    if (!taskId && controls && !runtime)
+        return 'branch-only';
+    return 'incomplete';
+}
+export function hasTaskBoundMarker(env = process.env) {
+    return taskMarkerState(env) === 'task-bound';
+}
+function explicitTaskRefForOperation(dispatcher, command, args, selected) {
+    if (selected.taskRefSource === 'none' || selected.taskRefSource === 'environment')
+        return null;
+    if (selected.taskRefSource === 'input')
+        return inputTaskRefForOperation(args);
+    if (command === 'sandbox-control' && args[0] === 'client') {
+        return explicitTaskRefForOperation('internal', args[1] ?? '', args.slice(2), selected);
+    }
+    if (dispatcher === 'public') {
+        if (command === 'decide' || command === 'run' || command === 'task') {
+            return optionValue(args, '--task') ?? optionValue(args, '-t') ?? null;
+        }
+        if (command === 'sandbox') {
+            const subcommand = first(args);
+            if (!['create', 'exec', 'show', 'rm', 'start'].includes(subcommand))
+                return null;
+            const targetIndex = (subcommand === 'exec' || subcommand === 'start') && args[1] === '--recreate' ? 2 : 1;
+            return args[targetIndex] ?? null;
+        }
+        return command === 'merge' ? null : first(args) || null;
+    }
+    if (command === 'codex-lifecycle')
+        return optionValue(args, '--task-id') ?? null;
+    if (command === 'platform-comment' || command === 'platform-issue') {
+        return first(args) === 'list' ? null : args[1] ?? null;
+    }
+    if (command === 'platform-pr')
+        return first(args) === 'sync-in-labels' ? null : args[1] ?? null;
+    if (command === 'platform-pr-review')
+        return optionValue(args, '--scope') ?? null;
+    if (command === 'platform-checks')
+        return args[1] ?? null;
+    if (command === 'task-context') {
+        const taskArgs = args.slice(1);
+        return optionValue(taskArgs, '--task')
+            ?? optionValue(taskArgs, '-t')
+            ?? taskArgs.find((arg) => !arg.startsWith('--'))
+            ?? null;
+    }
+    if (command === 'task-create' || command === 'task-short-id' && first(args) === 'list')
+        return null;
+    if (command === 'task-short-id')
+        return args[1] ?? null;
+    return first(args) || null;
+}
+function inputTaskRefForOperation(args) {
+    const inputPath = optionValue(args, '--input');
+    if (!inputPath)
+        return null;
+    try {
+        const input = JSON.parse(fs.readFileSync(inputPath, 'utf8'));
+        return typeof input.taskRef === 'string' && input.taskRef.trim() ? input.taskRef.trim() : null;
+    }
+    catch {
+        return null;
+    }
+}
+function isTaskInputRef(taskRef) {
+    return /^TASK-\d{8}-\d{6}$/u.test(taskRef) || /^\d+$/u.test(taskRef);
+}
+function taskRefMatchesEnvironment(taskRef, taskId) {
+    if (/^TASK-\d{8}-\d{6}$/u.test(taskRef))
+        return taskRef === taskId;
+    if (!/^\d+$/u.test(taskRef))
+        return true;
+    try {
+        const resolved = resolveTaskRef(taskRef);
+        return resolved.ok && resolved.taskId === taskId;
+    }
+    catch {
+        return false;
+    }
+}
+function isSandboxExecutorRoute(dispatcher, command, args, env) {
+    return dispatcher === 'internal'
+        && command === 'sandbox-control'
+        && first(args) === 'execute'
+        && Boolean(env.AGENT_INFRA_EXECUTOR_MANIFEST)
+        && Boolean(env.AGENT_INFRA_RUNTIME_DIR)
+        && !TASK_CONTROL_MARKER_KEYS.some((key) => Boolean(env[key]));
+}
+function viewFromEnvironment(env) {
+    const statusDir = env.AGENT_INFRA_CONTROL_STATUS_DIR;
+    if (!statusDir) {
+        return { state: 'unknown', taskId: env.AGENT_INFRA_TASK_ID ?? null, observedSource: 'unknown', receipt: null, reasonCode: 'SANDBOX_TASK_VIEW_STATUS_MISSING' };
+    }
+    try {
+        const view = taskViewFromStatus(JSON.parse(fs.readFileSync(`${statusDir}/status.json`, 'utf8')));
+        if (view.taskId !== env.AGENT_INFRA_TASK_ID) {
+            return {
+                state: 'unknown', taskId: env.AGENT_INFRA_TASK_ID ?? null, observedSource: 'unknown', receipt: null,
+                reasonCode: 'SANDBOX_TASK_VIEW_TASK_ID_MISMATCH'
+            };
+        }
+        return view;
+    }
+    catch {
+        return { state: 'unknown', taskId: env.AGENT_INFRA_TASK_ID ?? null, observedSource: 'unknown', receipt: null, reasonCode: 'SANDBOX_TASK_VIEW_STATUS_INVALID' };
+    }
+}
+export function formatTaskViewDiagnostic(view) {
+    const task = view.taskId ?? '-';
+    const source = view.observedSource ?? '-';
+    const reason = view.reasonCode ? ` reason=${view.reasonCode}` : '';
+    return `Task view: ${view.state} task=${task} source=${source}${reason}\n`;
+}
+export class TaskViewOperationError extends Error {
+    code;
+    exitCode;
+    constructor(code, message, exitCode = 1) {
+        super(`${code}: ${message}`);
+        this.name = 'TaskViewOperationError';
+        this.code = code;
+        this.exitCode = exitCode;
+    }
+}
+export function guardTaskOperation(dispatcher, command, args = [], options = {}) {
+    const env = options.env ?? process.env;
+    if (args[0] === '--help' || args[0] === '-h' || args[0] === 'help') {
+        return {
+            descriptor: resolveTaskOperation(dispatcher, command, args)
+                ?? descriptor(dispatcher, command, 'help', 'non-task', 'diagnostic', 'none'),
+            taskView: null
+        };
+    }
+    const markerState = taskMarkerState(env);
+    if (markerState === 'incomplete' && !isSandboxExecutorRoute(dispatcher, command, args, env)) {
+        throw new TaskViewOperationError('SANDBOX_TASK_VIEW_MARKER_INVALID', 'sandbox task markers are incomplete; refusing to infer host-direct authority');
+    }
+    const selected = command === 'sandbox-control'
+        ? first(args) === 'client'
+            ? resolveDelegatedTaskOperation(args)
+            : resolveTaskOperation(dispatcher, command, args)
+        : resolveTaskOperation(dispatcher, command, args);
+    if (!selected) {
+        if (markerState === 'task-bound') {
+            throw new TaskViewOperationError('TASK_VIEW_OPERATION_UNREGISTERED', `operation '${command} ${first(args)}' is not registered for a task-bound workspace`);
+        }
+        return { descriptor: descriptor(dispatcher, command, 'unregistered', 'non-task', 'diagnostic', 'none'), taskView: null };
+    }
+    if (selected.scope === 'non-task' || markerState !== 'task-bound')
+        return { descriptor: selected, taskView: null };
+    const taskId = env.AGENT_INFRA_TASK_ID;
+    const taskView = options.taskView ?? viewFromEnvironment(env);
+    if (taskView.state === 'not-applicable' && selected.effect !== 'cleanup') {
+        throw new TaskViewOperationError('SANDBOX_TASK_VIEW_INVALID', 'task-bound operation has no applicable task view');
+    }
+    const access = accessSandboxTaskView(taskView, selected.effect);
+    if (!access.allowed)
+        throw new TaskViewOperationError(access.reasonCode ?? 'SANDBOX_TASK_VIEW_DENIED', access.message ?? 'task view denied');
+    const taskRef = explicitTaskRefForOperation(dispatcher, command, args, selected);
+    if (selected.taskRefSource === 'input' && (!taskRef || !isTaskInputRef(taskRef))) {
+        throw new TaskViewOperationError('SANDBOX_TASK_REF_INVALID', 'task-bound input must contain a valid taskRef');
+    }
+    if (taskRef && !taskRefMatchesEnvironment(taskRef, taskId)) {
+        throw new TaskViewOperationError('SANDBOX_TASK_REF_MISMATCH', `task-bound operation targets '${taskRef}', but the sandbox is bound to '${taskId}'`);
+    }
+    return { descriptor: selected, taskView };
+}
+export function assertTaskViewStatus(value) {
+    return parseSandboxTaskView(value);
+}
+//# sourceMappingURL=task-operation-registry.js.map

package/dist/lib/internal/task-orchestration.js

@@ -1,6 +1,7 @@
 import { createDirectHostExecutionContext, dispatchTaskControlOperation, parseTaskControlOperation } from '../task/control-authority.js';
 import { OrchestrationStateError } from '../task/orchestration.js';
 import { detectRepoRoot } from '../task/resolve-ref.js';
+import { ensureInternalHandlerRoute, internalHandlerRoute } from './cli-route-inventory.js';
 const USAGE = 'Usage: agent-infra-internal task-orchestration <task-ref|auto> <begin-or-resume|route|prepare|dispatch|await-activation|recover-prepared|hook-start|hook-stop|advance|pause|status> [options]\n';
 function usageFailure(message) {
     process.stdout.write(`${JSON.stringify({
@@ -15,10 +16,21 @@ function parseFailure(error) {
     return message.replace(/^TASK_CONTROL_OPERATION_INVALID: /u, '');
 }
 async function taskOrchestration(args = []) {
+    if (!ensureInternalHandlerRoute('task-orchestration', args))
+        return;
     if (args[0] === '--help' || args[0] === '-h') {
         process.stdout.write(USAGE);
         return;
     }
+    const route = internalHandlerRoute('task-orchestration', 'status', args[1] ?? '')
+        ? 'status'
+        : internalHandlerRoute('task-orchestration', 'progress', args[1] ? 'progress' : '')
+            ? 'progress'
+            : '';
+    if (!route) {
+        usageFailure('orchestration operation is required');
+        return;
+    }
     let operation;
     try {
         operation = parseTaskControlOperation('task-orchestration', args);

package/dist/lib/internal/task-override.js

@@ -1,6 +1,7 @@
 import { consumeHumanOverride, diagnoseHumanOverrideForTask, issueHumanOverride } from '../task/human-override.js';
 import { resolveTaskRef } from '../task/resolve-ref.js';
 import { TaskExecutionLockError, withTaskExecutionLock } from '../task/task-execution-lock.js';
+import { ensureInternalHandlerRoute, internalHandlerRoute } from './cli-route-inventory.js';
 const USAGE = `Usage: agent-infra-internal task-override <task-ref> <diagnose|issue|consume> [options]
 
 Options: --failure-id <id> --target <target> --operator <operator> --reason <reason> --scope <scope>
@@ -29,12 +30,18 @@ function usageFailure(message) {
     process.exitCode = 1;
 }
 async function taskOverride(args = []) {
+    if (!ensureInternalHandlerRoute('task-override', args))
+        return;
     if (args[0] === '--help' || args[0] === '-h') {
         process.stdout.write(USAGE);
         return;
     }
     const [taskRef, operation] = args;
-    if (!taskRef || !operation || !['diagnose', 'issue', 'consume'].includes(operation)) {
+    if (!taskRef || !operation || ![
+        internalHandlerRoute('task-override', 'diagnose', operation ?? ''),
+        internalHandlerRoute('task-override', 'issue', operation ?? ''),
+        internalHandlerRoute('task-override', 'consume', operation ?? '')
+    ].some(Boolean)) {
         usageFailure('task ref and a valid operation are required');
         return;
     }
@@ -78,10 +85,10 @@ async function taskOverride(args = []) {
     }
     let result;
     try {
-        if (operation === 'diagnose') {
+        if (internalHandlerRoute('task-override', 'diagnose', operation)) {
             result = await diagnoseHumanOverrideForTask(taskRef, values.failureId ? String(values.failureId) : undefined, values.target ? String(values.target) : undefined);
         }
-        else if (operation === 'issue') {
+        else if (internalHandlerRoute('task-override', 'issue', operation)) {
             result = await withTaskExecutionLock(resolved.repoRoot, resolved.taskId, 'task-override.issue', async () => issueHumanOverride({
                 taskRef,
                 failureId: String(values.failureId),

package/dist/lib/internal/task-qualification.js

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

package/dist/lib/internal/task-review.js

@@ -2,6 +2,7 @@ import { finalizeReviewSummary } from '../task/review-finalization.js';
 import { consumeHumanOverride, failureId, overrideDryRunConflict } from '../task/human-override.js';
 import { resolveTaskRef } from '../task/resolve-ref.js';
 import { TaskExecutionLockError, withTaskExecutionLock } from '../task/task-execution-lock.js';
+import { ensureInternalHandlerRoute, internalHandlerRoute } from './cli-route-inventory.js';
 const USAGE = 'Usage: agent-infra-internal task-review <task-ref> finalize-summary --stage <analysis|plan|code> --artifact <review-*.md> [--orchestrated] [--dry-run] [--override-ticket <ticket> --override-target <target> --override-scope <scope>]\n';
 function failUsage(message) {
     process.stdout.write(`${JSON.stringify({
@@ -14,6 +15,8 @@ function failUsage(message) {
     process.exitCode = 2;
 }
 async function taskReview(args = []) {
+    if (!ensureInternalHandlerRoute('task-review', args))
+        return;
     if (args[0] === '--help' || args[0] === '-h') {
         process.stdout.write(USAGE);
         return;
@@ -22,7 +25,7 @@ async function taskReview(args = []) {
         failUsage('task ref and intent are required');
         return;
     }
-    if (args[1] !== 'finalize-summary') {
+    if (!internalHandlerRoute('task-review', 'finalize-summary', args[1] ?? '')) {
         failUsage(`unknown intent '${args[1]}'`);
         return;
     }