@phyzess/pappra 0.1.0-beta.18 → 0.1.0-beta.19

package/dist/cli/run.js

@@ -8,320 +8,16 @@ import { doctorUsage, runDoctorCommand } from './commands/doctor.js';
 import { docsUsage, runDocsCommand } from './commands/docs.js';
 import { checkpointUsage, resumeUsage, runCheckpointCommand, runResumeCommand, } from './commands/continuity.js';
 import { codeUsage, runCodeCommand } from './commands/code.js';
-import { collaborationCommandLine, collaborationUsage, runCollaborationCommand, } from './commands/collaboration.js';
-import { collaborationMessageUsage, runCollaborationMessageCommand, } from './commands/collaboration-message.js';
-import { collaborationPreflightUsage, runCollaborationPreflightCommand, } from './commands/collaboration-preflight.js';
-import { collaborationCapabilitiesUsage, runCollaborationCapabilitiesCommand, } from './commands/collaboration-capabilities.js';
-import { collaborationStateUsage, runCollaborationStateCommand, } from './commands/collaboration-state.js';
-import { collaborationResourcesUsage, runCollaborationResourcesCommand, } from './commands/collaboration-resources.js';
-import { collaborationHandoffUsage, runCollaborationHandoffCommand, } from './commands/collaboration-handoff.js';
-import { collaborationRecoveryUsage, runCollaborationRecoveryCommand, } from './commands/collaboration-recovery.js';
-import { collaborationRecoveryRunUsage, parseCollaborationRecoveryRunArgs, runCollaborationRecoveryRunCommand, } from './commands/collaboration-recovery-run.js';
-import { collaborationWorkRunUsage, parseCollaborationWorkRunArgs, runCollaborationWorkRunCommand, } from './commands/collaboration-work-run.js';
-import { collaborationBindingUsage, runCollaborationBindingCommand, } from './commands/collaboration-binding.js';
-import { collaborationPlanUsage, runCollaborationPlanCommand, } from './commands/collaboration-plan.js';
-import { collaborationRolloverUsage, runCollaborationRolloverCommand, } from './commands/collaboration-rollover.js';
-import { collaborationBootstrapUsage, runCollaborationBootstrapCommand, } from './commands/collaboration-bootstrap.js';
-import { collaborationTransitionUsage, runCollaborationTransitionCommand, } from './commands/collaboration-transition.js';
 import { hostUsage, runHostCommand } from './commands/host.js';
 import { sessionUsage, runSessionCommand } from './commands/session.js';
+import { collaborationCommandLine } from './commands/collaboration.js';
 import { collaborationRoleRunUsage, runCollaborationRoleRunCommand, } from './commands/collaboration-role-run.js';
 import { collaborationRolePlanUsage, runCollaborationRolePlanCommand, } from './commands/collaboration-role-plan.js';
 import { runtimeUsage, runRuntimeCommand } from './commands/runtime.js';
 import { repairUsage, runRepairCommand } from './commands/repair.js';
 import { hostNameSchema } from '../schemas/host.js';
-function parseOptions(args) {
-    const { values, positionals } = parseArgs({
-        args: [...args],
-        options: {
-            help: { type: 'boolean', short: 'h' },
-            version: { type: 'boolean', short: 'v' },
-            json: { type: 'boolean' },
-            live: { type: 'boolean' },
-            config: { type: 'string' },
-            apply: { type: 'boolean' },
-            watch: { type: 'boolean' },
-            yes: { type: 'boolean', short: 'y' },
-            'no-runtime': { type: 'boolean' },
-            'allow-workspace-writes': { type: 'boolean' },
-            reconfigure: { type: 'boolean' },
-            hosts: { type: 'string' },
-            'apply-host': { type: 'boolean' },
-            'dry-run': { type: 'boolean' },
-            'print-handoff': { type: 'boolean' },
-            'auto-resume': { type: 'boolean' },
-            from: { type: 'string' },
-            tarball: { type: 'string' },
-            out: { type: 'string' },
-            'bootstrap-config': { type: 'string' },
-            'recovery-config': { type: 'string' },
-            'transition-extension': { type: 'boolean' },
-            mode: { type: 'string' },
-            marketplace: { type: 'boolean' },
-            scope: { type: 'string' },
-            bind: { type: 'boolean' },
-            force: { type: 'boolean' },
-            'no-interactive': { type: 'boolean' },
-            'print-choices': { type: 'boolean' },
-            'install-runtime': { type: 'boolean' },
-            'runtime-tarball': { type: 'string' },
-            'runtime-version': { type: 'string' },
-            root: { type: 'string' },
-            'task-id': { type: 'string' },
-            record: { type: 'string' },
-            roots: { type: 'string' },
-            'include-private': { type: 'boolean' },
-            'include-archived': { type: 'boolean' },
-            task: { type: 'string' },
-            objective: { type: 'string' },
-            acceptance: { type: 'string', multiple: true },
-            constraint: { type: 'string', multiple: true },
-            decision: { type: 'string', multiple: true },
-            attempted: { type: 'string', multiple: true },
-            'next-action': { type: 'string', multiple: true },
-            limitation: { type: 'string', multiple: true },
-            artifact: { type: 'string', multiple: true },
-            'collaboration-record': { type: 'string' },
-            'context-completeness': { type: 'string' },
-            'author-session': { type: 'string' },
-            'native-harness': { type: 'string' },
-            'native-session': { type: 'string' },
-            session: { type: 'string' },
-            repo: { type: 'string' },
-            kind: { type: 'string' },
-            query: { type: 'string' },
-            limit: { type: 'string' },
-            'max-bytes': { type: 'string' },
-            rebuild: { type: 'boolean' },
-            host: { type: 'string' },
-            'host-root': { type: 'string' },
-            'host-version': { type: 'string' },
-            goal: { type: 'string' },
-            prepared: { type: 'string' },
-            capabilities: { type: 'string' },
-            controller: { type: 'string' },
-            'rpc-request-timeout-ms': { type: 'string' },
-            'rpc-operation-timeout-ms': { type: 'string' },
-            'domain-root': { type: 'string' },
-            'task-root': { type: 'string' },
-            message: { type: 'string' },
-            'message-id': { type: 'string' },
-            binding: { type: 'string' },
-            retry: { type: 'boolean' },
-            'caller-pane': { type: 'string' },
-            assignment: { type: 'string' },
-            'max-age-minutes': { type: 'string' },
-            harness: { type: 'string' },
-            template: { type: 'string' },
-            execution: { type: 'string' },
-            events: { type: 'string' },
-            request: { type: 'string' },
-            'owner-epoch': { type: 'string' },
-            'subtask-id': { type: 'string' },
-            attempt: { type: 'string' },
-        },
-        allowPositionals: true,
-        strict: true,
-    });
-    if (values.help && values.version) {
-        throw new Error('Use either --help or --version, not both.');
-    }
-    const command = positionals[0] ?? null;
-    if (command === 'task') {
-        if (positionals.length > 3) {
-            throw new Error('task accepts one action and an optional task id.');
-        }
-        return {
-            values,
-            command,
-            docsAction: null,
-            docsArgument: null,
-            codeAction: null,
-            hostAction: null,
-            hostSubAction: null,
-            collaborationAction: null,
-            resumeTaskId: null,
-            runtimeAction: null,
-            taskAction: positionals[1] ?? null,
-            taskArgument: positionals[2] ?? null,
-        };
-    }
-    if (command === 'docs') {
-        if (positionals.length > (positionals[1] === 'relocate' ? 4 : 3)) {
-            throw new Error('Unknown command; docs accepts one action and one argument.');
-        }
-        return {
-            values,
-            codeAction: null,
-            command,
-            docsAction: positionals[1] ?? null,
-            docsArgument: positionals[2] ?? null,
-            docsTarget: positionals[3] ?? null,
-            hostAction: null,
-            hostSubAction: null,
-            collaborationAction: null,
-            resumeTaskId: null,
-            runtimeAction: null,
-            taskAction: null,
-            taskArgument: null,
-        };
-    }
-    if (command === 'resume') {
-        if (positionals.length > 2) {
-            throw new Error('resume accepts exactly one task id.');
-        }
-        return {
-            values,
-            command,
-            docsAction: null,
-            docsArgument: null,
-            codeAction: null,
-            hostAction: null,
-            hostSubAction: null,
-            collaborationAction: null,
-            resumeTaskId: positionals[1] ?? null,
-            runtimeAction: null,
-            taskAction: null,
-            taskArgument: null,
-        };
-    }
-    if (command === 'code') {
-        if (positionals.length > 2) {
-            throw new Error('code accepts one action: status, prepare, or query.');
-        }
-        return {
-            values,
-            command,
-            docsAction: null,
-            docsArgument: null,
-            codeAction: positionals[1] ?? null,
-            hostAction: null,
-            hostSubAction: null,
-            collaborationAction: null,
-            resumeTaskId: null,
-            runtimeAction: null,
-            taskAction: null,
-            taskArgument: null,
-        };
-    }
-    if (command === 'host') {
-        if (positionals.length > 3) {
-            throw new Error('host accepts one action and an optional mcp sub-action.');
-        }
-        return {
-            values,
-            command,
-            docsAction: null,
-            docsArgument: null,
-            codeAction: null,
-            hostAction: positionals[1] ?? null,
-            hostSubAction: positionals[2] ?? null,
-            collaborationAction: null,
-            resumeTaskId: null,
-            runtimeAction: null,
-            taskAction: null,
-            taskArgument: null,
-        };
-    }
-    if (command === 'runtime') {
-        if (positionals.length > 2) {
-            throw new Error('runtime accepts one action: install, status, verify, or remove.');
-        }
-        return {
-            values,
-            command,
-            docsAction: null,
-            docsArgument: null,
-            codeAction: null,
-            hostAction: null,
-            hostSubAction: null,
-            collaborationAction: null,
-            resumeTaskId: null,
-            runtimeAction: positionals[1] ?? null,
-            taskAction: null,
-            taskArgument: null,
-        };
-    }
-    if (command === 'collab') {
-        // `collab message <action>` is the only two-level form; the action string carries
-        // both segments so callers keep one parsed field.
-        if (positionals.length > 3 ||
-            (positionals.length === 3 &&
-                positionals[1] !== 'transition' &&
-                positionals[1] !== 'bootstrap' &&
-                positionals[1] !== 'plan' &&
-                positionals[1] !== 'role-plan' &&
-                positionals[1] !== 'message' &&
-                !(positionals[1] === 'capabilities' && positionals[2] === 'derive') &&
-                !((positionals[1] === 'state' ||
-                    positionals[1] === 'resource' ||
-                    positionals[1] === 'handoff' ||
-                    positionals[1] === 'recovery' ||
-                    positionals[1] === 'binding' ||
-                    positionals[1] === 'rollover') &&
-                    positionals[2] !== undefined))) {
-            throw new Error('collab accepts prepare, run, work-run, query, preflight, plan, bootstrap, rollover <inspect|plan>, transition <plan|apply>, message <send|list|read|notify>, capabilities derive, state <show|doctor|epoch-check>, resource <list|claim|release>, handoff <inventory|begin|stopped|rebind|transfer|confirm|complete|abort|release-dispatch>, recovery <inspect|reconcile|lock-break>, recovery-run, or binding <list|resolve|bind|unbind>.');
-        }
-        return {
-            values,
-            command,
-            docsAction: null,
-            docsArgument: null,
-            codeAction: null,
-            hostAction: null,
-            hostSubAction: null,
-            collaborationAction: positionals[1] === undefined ? null : positionals.slice(1).join(':'),
-            resumeTaskId: null,
-            runtimeAction: null,
-            taskAction: null,
-            taskArgument: null,
-        };
-    }
-    if (positionals.length > 1) {
-        throw new Error('Only one command may be specified.');
-    }
-    return {
-        values,
-        command,
-        docsAction: null,
-        docsArgument: null,
-        codeAction: null,
-        hostAction: null,
-        collaborationAction: null,
-        resumeTaskId: null,
-        runtimeAction: null,
-    };
-}
-function failure(output, json, code, error) {
-    const message = typeof error === 'string'
-        ? error
-        : error instanceof Error
-            ? error.message
-            : 'Operation failed.';
-    if (json) {
-        output.stdout(`${JSON.stringify({ ok: false, code, message })}\n`);
-    }
-    else {
-        output.stderr(`pappra: ${message}\n`);
-    }
-}
-function hasContinuityOptions(values, includeSession = true) {
-    return (values.task !== undefined ||
-        values.objective !== undefined ||
-        values.acceptance !== undefined ||
-        values.constraint !== undefined ||
-        values.decision !== undefined ||
-        values.attempted !== undefined ||
-        values['next-action'] !== undefined ||
-        values.limitation !== undefined ||
-        values.artifact !== undefined ||
-        values['collaboration-record'] !== undefined ||
-        values['context-completeness'] !== undefined ||
-        values['author-session'] !== undefined ||
-        values['native-harness'] !== undefined ||
-        values['native-session'] !== undefined ||
-        (includeSession && values.session !== undefined));
-}
+import { parseOptions, failure, hasContinuityOptions } from './options.js';
+import { routeCollaboration } from './collaboration-router.js';
 const globalUsage = 'pappra [--help | --version] [--json]\n' +
     'pappra task <pin|unpin|show> [taskId] [--auto-resume] [--json]\n' +
     'pappra mcp [--root <dir>] [--allow-workspace-writes] [--help]\n' +
@@ -522,15 +218,25 @@ export async function runCli(args, output) {
         failure(output, json, 'invalid_arguments', '--out is only valid for host.');
         return 2;
     }
-    if (values.scope !== undefined &&
-        values.scope !== 'project' &&
-        values.scope !== 'user') {
-        failure(output, json, 'invalid_arguments', '--scope accepts project or user.');
-        return 2;
-    }
-    if (command !== 'host' && values.scope !== undefined) {
-        failure(output, json, 'invalid_arguments', '--scope is only valid for host.');
-        return 2;
+    if (values.scope !== undefined) {
+        // `--scope` is command-family scoped: host wiring uses project|user, knowledge
+        // documents use private|shared, and docs itself still restricts it to forget.
+        if (command === 'host') {
+            if (values.scope !== 'project' && values.scope !== 'user') {
+                failure(output, json, 'invalid_arguments', '--scope accepts project or user.');
+                return 2;
+            }
+        }
+        else if (command === 'docs') {
+            if (values.scope !== 'private' && values.scope !== 'shared') {
+                failure(output, json, 'invalid_arguments', '--scope accepts private or shared for docs.');
+                return 2;
+            }
+        }
+        else {
+            failure(output, json, 'invalid_arguments', '--scope is only valid for host or docs.');
+            return 2;
+        }
     }
     if (command !== 'host' && values.marketplace === true) {
         failure(output, json, 'invalid_arguments', '--marketplace is only valid for host bundle.');
@@ -616,594 +322,16 @@ export async function runCli(args, output) {
         return 2;
     }
     if (command === 'collab') {
-        if (values.help) {
-            const usage = collaborationAction === 'recovery-run'
-                ? collaborationRecoveryRunUsage
-                : collaborationAction === 'work-run'
-                    ? collaborationWorkRunUsage
-                    : collaborationAction === 'transition' ||
-                        collaborationAction?.startsWith('transition:') === true
-                        ? collaborationTransitionUsage
-                        : collaborationAction === 'bootstrap' ||
-                            collaborationAction?.startsWith('bootstrap:') === true
-                            ? collaborationBootstrapUsage
-                            : collaborationAction === 'message' ||
-                                collaborationAction?.startsWith('message:') === true
-                                ? collaborationMessageUsage
-                                : collaborationAction?.startsWith('capabilities:') === true
-                                    ? collaborationCapabilitiesUsage
-                                    : collaborationAction?.startsWith('state:') === true
-                                        ? collaborationStateUsage
-                                        : collaborationAction?.startsWith('resource:') === true
-                                            ? collaborationResourcesUsage
-                                            : collaborationAction?.startsWith('handoff:') === true
-                                                ? collaborationHandoffUsage
-                                                : collaborationAction?.startsWith('recovery:') ===
-                                                    true
-                                                    ? collaborationRecoveryUsage
-                                                    : collaborationAction?.startsWith('binding:') ===
-                                                        true
-                                                        ? collaborationBindingUsage
-                                                        : collaborationAction === 'plan'
-                                                            ? collaborationPlanUsage
-                                                            : collaborationAction?.startsWith('rollover:') === true ||
-                                                                collaborationAction === 'rollover'
-                                                                ? collaborationRolloverUsage
-                                                                : collaborationAction === 'preflight'
-                                                                    ? collaborationPreflightUsage
-                                                                    : collaborationUsage;
-            if (json) {
-                output.stdout(`${JSON.stringify({ ...info, commands: ['collab'], usage })}\n`);
-            }
-            else {
-                output.stdout(usage);
-            }
-            return 0;
-        }
-        if (collaborationAction === 'work-run') {
-            const allowed = new Set(['request', 'apply', 'json']);
-            const extra = Object.entries(values)
-                .filter(([, value]) => value !== undefined)
-                .map(([key]) => key)
-                .filter((key) => !allowed.has(key));
-            const parsedWork = parseCollaborationWorkRunArgs(args.slice(2));
-            if (extra.length || parsedWork.errors.length) {
-                failure(output, json, 'invalid_arguments', `collab work-run accepts only --request, --apply and --json.${extra.length ? ` Unexpected: ${extra.join(', ')}.` : ''}${parsedWork.errors.length ? ` ${parsedWork.errors.join(' ')}` : ''}\n${collaborationWorkRunUsage}`);
-                return 2;
-            }
-            return runCollaborationWorkRunCommand({ ...parsedWork.options, json }, output);
-        }
-        if (collaborationAction === 'recovery-run') {
-            const allowed = new Set(['request', 'apply', 'json']);
-            const extra = Object.entries(values)
-                .filter(([, value]) => value !== undefined)
-                .map(([key]) => key)
-                .filter((key) => !allowed.has(key));
-            const parsedRecovery = parseCollaborationRecoveryRunArgs(args.slice(2));
-            if (extra.length || parsedRecovery.errors.length) {
-                failure(output, json, 'invalid_arguments', `collab recovery-run accepts only --request, --apply and --json.${extra.length ? ` Unexpected: ${extra.join(', ')}.` : ''}${parsedRecovery.errors.length ? ` ${parsedRecovery.errors.join(' ')}` : ''}\n${collaborationRecoveryRunUsage}`);
-                return 2;
-            }
-            return runCollaborationRecoveryRunCommand({ ...parsedRecovery.options, json }, output);
-        }
-        if (collaborationAction === 'capabilities:derive') {
-            const duplicate = [
-                '--live',
-                '--harness',
-                '--assignment',
-                '--template',
-                '--execution',
-                '--session',
-                '--events',
-            ].filter((flag) => args.filter((arg) => arg === flag || arg.startsWith(`${flag}=`))
-                .length > 1);
-            if (duplicate.length) {
-                failure(output, json, 'invalid_arguments', `collab capabilities derive rejects duplicate option(s): ${duplicate.join(', ')}.\n${collaborationCapabilitiesUsage}`);
-                return 2;
-            }
-            const allowed = new Set([
-                'live',
-                'assignment',
-                'harness',
-                'template',
-                'execution',
-                'session',
-                'events',
-                'json',
-            ]);
-            const extra = Object.entries(values)
-                .filter(([, value]) => value !== undefined)
-                .map(([key]) => key)
-                .filter((key) => !allowed.has(key));
-            if (extra.length) {
-                failure(output, json, 'invalid_arguments', `collab capabilities derive accepts only its own options: ${extra.join(', ')}.\n${collaborationCapabilitiesUsage}`);
-                return 2;
-            }
-            return runCollaborationCapabilitiesCommand({
-                harness: values.harness ?? null,
-                assignmentFile: values.assignment ?? null,
-                templateFile: values.template ?? null,
-                executionFile: values.execution ?? null,
-                sessionFile: values.session ?? null,
-                eventsFile: values.events ?? null,
-                live: values.live ?? false,
-                json,
-            }, output);
-        }
-        if (collaborationAction?.startsWith('state:')) {
-            const selected = collaborationAction.slice('state:'.length);
-            const stateAction = selected === 'show' ||
-                selected === 'doctor' ||
-                selected === 'epoch-check'
-                ? selected
-                : null;
-            const stateFlags = stateAction === 'epoch-check'
-                ? ['--task-root', '--owner-epoch']
-                : ['--task-root'];
-            const duplicate = stateFlags.filter((flag) => args.filter((arg) => arg === flag || arg.startsWith(`${flag}=`))
-                .length > 1);
-            const allowed = new Set([
-                'task-root',
-                'json',
-                ...(stateAction === 'epoch-check' ? ['owner-epoch'] : []),
-            ]);
-            const extra = Object.entries(values)
-                .filter(([, value]) => value !== undefined)
-                .map(([key]) => key)
-                .filter((key) => !allowed.has(key));
-            if (stateAction === null || duplicate.length || extra.length) {
-                failure(output, json, 'invalid_arguments', `collab state accepts only show/doctor/epoch-check and their own options.${duplicate.length ? ` Duplicate: ${duplicate.join(', ')}.` : ''}${extra.length ? ` Unexpected: ${extra.join(', ')}.` : ''}\n${collaborationStateUsage}`);
-                return 2;
-            }
-            return runCollaborationStateCommand({
-                action: stateAction,
-                taskRoot: values['task-root'] ?? null,
-                ownerEpoch: values['owner-epoch'] ?? null,
-                json,
-            }, output);
-        }
-        if (collaborationAction?.startsWith('resource:')) {
-            const selected = collaborationAction.slice('resource:'.length);
-            const resourceAction = selected === 'list' || selected === 'claim' || selected === 'release'
-                ? selected
-                : null;
-            const resourceFlags = resourceAction === 'list'
-                ? ['--task-root']
-                : ['--task-root', '--request'];
-            const duplicate = resourceFlags.filter((flag) => args.filter((arg) => arg === flag || arg.startsWith(`${flag}=`))
-                .length > 1);
-            const allowed = new Set([
-                'task-root',
-                'json',
-                ...(resourceAction === 'list' ? [] : ['request', 'apply']),
-            ]);
-            const extra = Object.entries(values)
-                .filter(([, value]) => value !== undefined)
-                .map(([key]) => key)
-                .filter((key) => !allowed.has(key));
-            if (resourceAction === null || duplicate.length || extra.length) {
-                failure(output, json, 'invalid_arguments', `collab resource accepts only list/claim/release and their own options.${duplicate.length ? ` Duplicate: ${duplicate.join(', ')}.` : ''}${extra.length ? ` Unexpected: ${extra.join(', ')}.` : ''}\n${collaborationResourcesUsage}`);
-                return 2;
-            }
-            return runCollaborationResourcesCommand({
-                action: resourceAction,
-                taskRoot: values['task-root'] ?? null,
-                requestFile: values.request ?? null,
-                apply: values.apply === true,
-                json,
-            }, output);
-        }
-        if (collaborationAction?.startsWith('handoff:')) {
-            const selected = collaborationAction.slice('handoff:'.length);
-            const handoffAction = selected === 'inventory' ||
-                selected === 'begin' ||
-                selected === 'stopped' ||
-                selected === 'rebind' ||
-                selected === 'transfer' ||
-                selected === 'confirm' ||
-                selected === 'complete' ||
-                selected === 'abort' ||
-                selected === 'release-dispatch'
-                ? selected
-                : null;
-            const duplicateFlags = handoffAction === 'inventory'
-                ? ['--task-root', '--subtask-id', '--attempt']
-                : ['--task-root', '--request'];
-            const duplicate = duplicateFlags.filter((flag) => args.filter((arg) => arg === flag || arg.startsWith(`${flag}=`))
-                .length > 1);
-            const allowed = new Set([
-                'task-root',
-                'json',
-                ...(handoffAction === 'inventory'
-                    ? ['subtask-id', 'attempt']
-                    : ['request', 'apply']),
-            ]);
-            const extra = Object.entries(values)
-                .filter(([, value]) => value !== undefined)
-                .map(([key]) => key)
-                .filter((key) => !allowed.has(key));
-            if (handoffAction === null || duplicate.length || extra.length) {
-                failure(output, json, 'invalid_arguments', `collab handoff accepts only inventory or a handoff mutation action and their own options.${duplicate.length ? ` Duplicate: ${duplicate.join(', ')}.` : ''}${extra.length ? ` Unexpected: ${extra.join(', ')}.` : ''}\n${collaborationHandoffUsage}`);
-                return 2;
-            }
-            return runCollaborationHandoffCommand({
-                action: handoffAction,
-                taskRoot: values['task-root'] ?? null,
-                requestFile: values.request ?? null,
-                subtaskId: values['subtask-id'] ?? null,
-                attempt: values.attempt ?? null,
-                apply: values.apply === true,
-                json,
-            }, output);
-        }
-        if (collaborationAction?.startsWith('recovery:')) {
-            const selected = collaborationAction.slice('recovery:'.length);
-            const recoveryAction = selected === 'inspect' ||
-                selected === 'reconcile' ||
-                selected === 'lock-break'
-                ? selected
-                : null;
-            const duplicateFlags = recoveryAction === 'inspect'
-                ? ['--task-root']
-                : ['--task-root', '--request'];
-            const duplicate = duplicateFlags.filter((flag) => args.filter((arg) => arg === flag || arg.startsWith(`${flag}=`))
-                .length > 1);
-            const allowed = new Set([
-                'task-root',
-                'json',
-                ...(recoveryAction === 'inspect' ? [] : ['request', 'apply']),
-            ]);
-            const extra = Object.entries(values)
-                .filter(([, value]) => value !== undefined)
-                .map(([key]) => key)
-                .filter((key) => !allowed.has(key));
-            if (recoveryAction === null || duplicate.length || extra.length) {
-                failure(output, json, 'invalid_arguments', `collab recovery accepts only inspect/reconcile/lock-break and their own options.${duplicate.length ? ` Duplicate: ${duplicate.join(', ')}.` : ''}${extra.length ? ` Unexpected: ${extra.join(', ')}.` : ''}\n${collaborationRecoveryUsage}`);
-                return 2;
-            }
-            return runCollaborationRecoveryCommand({
-                action: recoveryAction,
-                taskRoot: values['task-root'] ?? null,
-                requestFile: values.request ?? null,
-                apply: values.apply === true,
-                json,
-            }, output);
-        }
-        if (collaborationAction?.startsWith('binding:')) {
-            const selected = collaborationAction.slice('binding:'.length);
-            const bindingAction = selected === 'list' ||
-                selected === 'resolve' ||
-                selected === 'bind' ||
-                selected === 'unbind'
-                ? selected
-                : null;
-            const allowedFlags = bindingAction === 'list'
-                ? ['root']
-                : bindingAction === 'resolve'
-                    ? ['task-id', 'root', 'roots']
-                    : bindingAction === 'bind'
-                        ? ['task-id', 'record', 'root', 'apply']
-                        : bindingAction === 'unbind'
-                            ? ['task-id', 'root', 'apply']
-                            : [];
-            const duplicate = allowedFlags.filter((flag) => args.filter((arg) => arg === `--${flag}` || arg.startsWith(`--${flag}=`)).length > 1);
-            const allowed = new Set([...allowedFlags, 'json']);
-            const extra = Object.entries(values)
-                .filter(([, value]) => value !== undefined)
-                .map(([key]) => key)
-                .filter((key) => !allowed.has(key));
-            const missing = bindingAction === null
-                ? []
-                : [
-                    ...(bindingAction === 'resolve' ||
-                        bindingAction === 'bind' ||
-                        bindingAction === 'unbind'
-                        ? ['task-id']
-                        : []),
-                    ...(bindingAction === 'bind' ? ['record'] : []),
-                ].filter((flag) => values[flag] === undefined ||
-                    values[flag] === null);
-            if (bindingAction === null ||
-                duplicate.length ||
-                extra.length ||
-                missing.length) {
-                failure(output, json, 'invalid_arguments', `collab binding accepts only list/resolve/bind/unbind and their own options.${duplicate.length ? ` Duplicate: ${duplicate.join(', ')}.` : ''}${extra.length ? ` Unexpected: ${extra.join(', ')}.` : ''}${missing.length ? ` Missing: ${missing.join(', ')}.` : ''}\n${collaborationBindingUsage}`);
-                return 2;
-            }
-            return runCollaborationBindingCommand({
-                action: bindingAction,
-                root: values.root ?? null,
-                taskId: values['task-id'] ?? null,
-                record: values.record ?? null,
-                roots: values.roots ?? null,
-                apply: values.apply === true,
-                json,
-            }, output);
-        }
-        if (collaborationAction === 'transition' ||
-            collaborationAction?.startsWith('transition:') === true) {
-            const selected = collaborationAction === 'transition'
-                ? null
-                : collaborationAction.slice('transition:'.length);
-            const transitionAction = selected === 'plan' || selected === 'apply' ? selected : null;
-            const duplicate = ['--task-root', '--request'].filter((flag) => args.filter((arg) => arg === flag || arg.startsWith(`${flag}=`))
-                .length > 1);
-            const allowed = new Set(['task-root', 'request', 'json']);
-            const extra = Object.entries(values)
-                .filter(([, value]) => value !== undefined)
-                .map(([key]) => key)
-                .filter((key) => !allowed.has(key));
-            if (transitionAction === null || duplicate.length || extra.length) {
-                failure(output, json, 'invalid_arguments', `collab transition accepts only plan|apply with --task-root, --request and --json.${duplicate.length ? ` Duplicate: ${duplicate.join(', ')}.` : ''}${extra.length ? ` Unexpected: ${extra.join(', ')}.` : ''}${transitionAction === null ? ' Missing: plan or apply.' : ''}\n${collaborationTransitionUsage}`);
-                return 2;
-            }
-            return runCollaborationTransitionCommand({
-                action: transitionAction,
-                taskRoot: values['task-root'] ?? null,
-                requestFile: values.request ?? null,
-                json,
-            }, output);
-        }
-        if (collaborationAction?.startsWith('rollover:') ||
-            collaborationAction === 'rollover') {
-            const selected = collaborationAction === 'rollover'
-                ? null
-                : collaborationAction.slice('rollover:'.length);
-            const rolloverAction = selected === 'inspect' || selected === 'plan' ? selected : null;
-            const duplicate = ['--task-root', '--request'].filter((flag) => args.filter((arg) => arg === flag || arg.startsWith(`${flag}=`))
-                .length > 1);
-            const allowed = new Set(['task-root', 'request', 'json']);
-            const extra = Object.entries(values)
-                .filter(([, value]) => value !== undefined)
-                .map(([key]) => key)
-                .filter((key) => !allowed.has(key));
-            if (rolloverAction === null || duplicate.length || extra.length) {
-                failure(output, json, 'invalid_arguments', `collab rollover accepts only inspect or plan with --task-root, --request and --json.${duplicate.length ? ` Duplicate: ${duplicate.join(', ')}.` : ''}${extra.length ? ` Unexpected: ${extra.join(', ')}.` : ''}${rolloverAction === null ? ' Missing: inspect or plan.' : ''}\n${collaborationRolloverUsage}`);
-                return 2;
-            }
-            return runCollaborationRolloverCommand({
-                action: rolloverAction,
-                taskRoot: values['task-root'] ?? null,
-                requestFile: values.request ?? null,
-                json,
-            }, output);
-        }
-        if (collaborationAction === 'plan') {
-            // `plan` is the only collab action that reads --config: the plan document is an
-            // explicit bounded file, not a global flag other commands silently accept.
-            const duplicate = ['--task-root', '--config'].filter((flag) => args.filter((arg) => arg === flag || arg.startsWith(`${flag}=`))
-                .length > 1);
-            const allowed = new Set(['task-root', 'config', 'json']);
-            const extra = Object.entries(values)
-                .filter(([, value]) => value !== undefined)
-                .map(([key]) => key)
-                .filter((key) => !allowed.has(key));
-            if (duplicate.length || extra.length) {
-                failure(output, json, 'invalid_arguments', `collab plan accepts only --task-root, --config and --json.${duplicate.length ? ` Duplicate: ${duplicate.join(', ')}.` : ''}${extra.length ? ` Unexpected: ${extra.join(', ')}.` : ''}\n${collaborationPlanUsage}`);
-                return 2;
-            }
-            return runCollaborationPlanCommand({
-                taskRoot: values['task-root'] ?? null,
-                planFile: values.config ?? null,
-                json,
-            }, output);
-        }
-        if (collaborationAction === 'bootstrap' ||
-            collaborationAction?.startsWith('bootstrap:') === true) {
-            const selected = collaborationAction === 'bootstrap'
-                ? null
-                : collaborationAction.slice('bootstrap:'.length);
-            const action = selected === 'plan' || selected === 'apply' ? selected : null;
-            const duplicate = ['--task-root', '--request'].filter((flag) => args.filter((arg) => arg === flag || arg.startsWith(`${flag}=`))
-                .length > 1);
-            const allowed = new Set(['task-root', 'request', 'json']);
-            const extra = Object.entries(values)
-                .filter(([, value]) => value !== undefined)
-                .map(([key]) => key)
-                .filter((key) => !allowed.has(key));
-            if (action === null || duplicate.length || extra.length) {
-                failure(output, json, 'invalid_arguments', `collab bootstrap requires plan|apply and only --task-root, --request and --json.${duplicate.length ? ` Duplicate: ${duplicate.join(', ')}.` : ''}${extra.length ? ` Unexpected: ${extra.join(', ')}.` : ''}\n${collaborationBootstrapUsage}`);
-                return 2;
-            }
-            return runCollaborationBootstrapCommand({
-                action,
-                taskRoot: values['task-root'] ?? null,
-                requestFile: values.request ?? null,
-                json,
-            }, output);
-        }
-        if (collaborationAction === 'preflight') {
-            if (values.version ||
-                values.config !== undefined ||
-                values['install-runtime'] === true ||
-                values['runtime-tarball'] !== undefined ||
-                values['runtime-version'] !== undefined ||
-                values.root !== undefined ||
-                values.goal !== undefined ||
-                values.prepared !== undefined ||
-                values.controller !== undefined ||
-                values['domain-root'] !== undefined ||
-                values['task-root'] !== undefined ||
-                values.message !== undefined ||
-                values['message-id'] !== undefined ||
-                values.binding !== undefined ||
-                values.retry === true ||
-                values['caller-pane'] !== undefined ||
-                values.session !== undefined ||
-                values.harness !== undefined ||
-                values.template !== undefined ||
-                values.execution !== undefined ||
-                values.events !== undefined ||
-                values.request !== undefined ||
-                values['owner-epoch'] !== undefined ||
-                values['subtask-id'] !== undefined ||
-                values.attempt !== undefined ||
-                values['task-id'] !== undefined ||
-                values.record !== undefined ||
-                values.roots !== undefined ||
-                values.apply === true ||
-                values['include-private'] === true ||
-                values['include-archived'] === true ||
-                hasContinuityOptions(values)) {
-                failure(output, json, 'invalid_arguments', `collab preflight accepts only its own options.\n${collaborationPreflightUsage}`);
-                return 2;
-            }
-            return runCollaborationPreflightCommand({
-                cwd: process.cwd(),
-                assignmentFile: values.assignment ?? null,
-                capabilitiesFile: values.capabilities ?? null,
-                maxAgeMinutes: values['max-age-minutes'] ?? null,
-                json,
-            }, output);
-        }
-        const separator = collaborationAction?.indexOf(':') ?? -1;
-        if (separator >= 0) {
-            const group = collaborationAction?.slice(0, separator) ?? '';
-            const selected = collaborationAction?.slice(separator + 1) ?? '';
-            const messageAction = group === 'message' &&
-                (selected === 'send' ||
-                    selected === 'list' ||
-                    selected === 'read' ||
-                    selected === 'notify')
-                ? selected
-                : null;
-            const provided = new Set();
-            if (values.message !== undefined)
-                provided.add('message');
-            if (values['message-id'] !== undefined)
-                provided.add('message-id');
-            if (values.binding !== undefined)
-                provided.add('binding');
-            if (values.limit !== undefined)
-                provided.add('limit');
-            if (values.apply === true)
-                provided.add('apply');
-            if (values.retry === true)
-                provided.add('retry');
-            if (values['caller-pane'] !== undefined)
-                provided.add('caller-pane');
-            const allowedByAction = {
-                send: new Set(['message', 'apply']),
-                list: new Set(['limit']),
-                read: new Set(['message-id']),
-                notify: new Set([
-                    'message-id',
-                    'binding',
-                    'apply',
-                    'retry',
-                    'caller-pane',
-                ]),
-            };
-            const requiredByAction = {
-                send: ['message'],
-                list: [],
-                read: ['message-id'],
-                notify: ['message-id', 'binding'],
-            };
-            const actionFlagsValid = messageAction !== null &&
-                [...provided].every((flag) => allowedByAction[messageAction].has(flag)) &&
-                requiredByAction[messageAction].every((flag) => provided.has(flag));
-            if (messageAction === null ||
-                !actionFlagsValid ||
-                values.version ||
-                values.config !== undefined ||
-                values['install-runtime'] === true ||
-                values['runtime-tarball'] !== undefined ||
-                values['runtime-version'] !== undefined ||
-                values.root !== undefined ||
-                values.goal !== undefined ||
-                values.prepared !== undefined ||
-                values.capabilities !== undefined ||
-                values.controller !== undefined ||
-                values['domain-root'] !== undefined ||
-                values.assignment !== undefined ||
-                values['max-age-minutes'] !== undefined ||
-                values.session !== undefined ||
-                values.harness !== undefined ||
-                values.template !== undefined ||
-                values.execution !== undefined ||
-                values.events !== undefined ||
-                values.request !== undefined ||
-                values['owner-epoch'] !== undefined ||
-                values['subtask-id'] !== undefined ||
-                values.attempt !== undefined ||
-                values['task-id'] !== undefined ||
-                values.record !== undefined ||
-                values.roots !== undefined ||
-                values['include-private'] === true ||
-                values['include-archived'] === true ||
-                hasContinuityOptions(values)) {
-                failure(output, json, 'invalid_arguments', `collab message requires send/list/read/notify with only its own options.\n${collaborationMessageUsage}`);
-                return 2;
-            }
-            return runCollaborationMessageCommand({
-                cwd: process.cwd(),
-                action: messageAction,
-                json,
-                taskRoot: values['task-root'] ?? null,
-                messageFile: values.message ?? null,
-                messageId: values['message-id'] ?? null,
-                bindingFile: values.binding ?? null,
-                apply: values.apply === true,
-                retry: values.retry === true,
-                limit: values.limit ?? null,
-                callerPane: values['caller-pane'] ?? null,
-            }, output);
-        }
-        const action = collaborationAction === 'prepare' ||
-            collaborationAction === 'run' ||
-            collaborationAction === 'query'
-            ? collaborationAction
-            : null;
-        if (action === null ||
-            values.version ||
-            values.config !== undefined ||
-            values['install-runtime'] === true ||
-            values['runtime-tarball'] !== undefined ||
-            values['runtime-version'] !== undefined ||
-            values.root !== undefined ||
-            values['include-private'] === true ||
-            values['task-root'] !== undefined ||
-            values.message !== undefined ||
-            values['message-id'] !== undefined ||
-            values.binding !== undefined ||
-            values.retry === true ||
-            values['caller-pane'] !== undefined ||
-            values.assignment !== undefined ||
-            values['max-age-minutes'] !== undefined ||
-            values.session !== undefined ||
-            values.harness !== undefined ||
-            values.template !== undefined ||
-            values.execution !== undefined ||
-            values.events !== undefined ||
-            values.request !== undefined ||
-            values['owner-epoch'] !== undefined ||
-            values['subtask-id'] !== undefined ||
-            values.attempt !== undefined ||
-            values['task-id'] !== undefined ||
-            values.record !== undefined ||
-            values.roots !== undefined ||
-            values['include-archived'] === true ||
-            hasContinuityOptions(values)) {
-            failure(output, json, 'invalid_arguments', 'collab requires prepare/run/query and only collab options.');
-            return 2;
-        }
-        return runCollaborationCommand({
-            cwd: process.cwd(),
-            action,
+        return routeCollaboration({
+            values,
+            action: collaborationAction,
+            args,
+            info,
+            rpcRequestTimeout,
+            rpcOperationTimeout,
+            output,
             json,
-            goalFile: values.goal ?? null,
-            preparedFile: values.prepared ?? null,
-            capabilitiesFile: values.capabilities ?? null,
-            controller: values.controller ?? null,
-            domainRoot: values['domain-root'] ?? null,
-            ...(rpcRequestTimeout === undefined
-                ? {}
-                : { rpcRequestTimeoutMs: Number(rpcRequestTimeout) }),
-            ...(rpcOperationTimeout === undefined
-                ? {}
-                : { rpcOperationTimeoutMs: Number(rpcOperationTimeout) }),
-        }, output);
+        });
     }
     if (command === 'docs') {
         if (values.version ||