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

package/dist/cli/run.js

@@ -8,275 +8,111 @@ 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 { collaborationUsage, runCollaborationCommand, } from './commands/collaboration.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' },
-            config: { type: 'string' },
-            apply: { type: 'boolean' },
-            yes: { type: 'boolean', short: 'y' },
-            'no-runtime': { 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' },
-            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' },
-            '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' },
-            'domain-root': { 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 > 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,
-            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') {
-        if (positionals.length > 2) {
-            throw new Error('collab accepts one action: prepare, run, or query.');
-        }
-        return {
-            values,
-            command,
-            docsAction: null,
-            docsArgument: null,
-            codeAction: null,
-            hostAction: null,
-            hostSubAction: null,
-            collaborationAction: positionals[1] ?? null,
-            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>] [--help]\n' +
+    'pappra mcp [--root <dir>] [--allow-workspace-writes] [--help]\n' +
     'pappra onboard [--root <dir>] [--config <file>] [--hosts <list>] [--yes]\n' +
     '               [--apply-host] [--dry-run] [--print-handoff] [--json]\n' +
     'pappra init [--config <file> | --yes] [--apply] [--json] [--print-choices]\n' +
     '              [--install-runtime (--runtime-tarball <file> | --runtime-version <version>)]\n' +
     'pappra doctor [--root <path>] [--json]\n' +
-    'pappra docs <list|check|archive> [options]\n' +
+    'pappra repair [--root <path>] [--runtime-version <v>] [--install-id <uuid>] [--apply] [--json]\n' +
+    'pappra docs <list|check|archive|scan|relocate|forget> [options]\n' +
     'pappra checkpoint --task <id> [options] [--json]\n' +
     'pappra resume <taskId> [--session <id>] [--json]\n' +
     'pappra code <status|prepare|query> --repo <id> [options] [--json]\n' +
-    'pappra host <detect|describe|plan|install|verify> --host <name> [options] [--json]\n' +
-    'pappra runtime <install|status|verify|remove> [options] [--json]\n' +
-    'pappra collab <prepare|run|query> [options]';
+    'pappra host <detect|describe|probe|plan|install|verify|uninstall|bundle|mcp> --host <name> [options] [--json]\n' +
+    'pappra runtime <install|status|verify|remove|gc> [options] [--json]\n' +
+    'pappra session <plan|start|status|fence|stop> --config <abs managed-pi.json> [--json]\n' +
+    `${collaborationCommandLine}`;
 export async function runCli(args, output) {
     const jsonRequested = args.includes('--json');
+    if (args[0] === 'repair') {
+        try {
+            const parsedRepair = parseArgs({
+                args: [...args.slice(1)],
+                options: {
+                    root: { type: 'string' },
+                    'runtime-version': { type: 'string' },
+                    'install-id': { type: 'string' },
+                    apply: { type: 'boolean' },
+                    'quarantine-unowned-locks': { type: 'boolean' },
+                    'reset-local': { type: 'boolean' },
+                    'all-writers-stopped': { type: 'boolean' },
+                    json: { type: 'boolean' },
+                    help: { type: 'boolean', short: 'h' },
+                },
+                allowPositionals: false,
+                strict: true,
+            });
+            if (['--root', '--runtime-version', '--install-id'].some((flag) => args.filter((arg) => arg === flag || arg.startsWith(`${flag}=`))
+                .length > 1))
+                throw new Error('Repair options must not be repeated.');
+            if (parsedRepair.values.help) {
+                output.stdout(repairUsage);
+                return 0;
+            }
+            return runRepairCommand({
+                root: parsedRepair.values.root ?? process.cwd(),
+                ...(parsedRepair.values['runtime-version'] === undefined
+                    ? {}
+                    : { runtimeVersion: parsedRepair.values['runtime-version'] }),
+                ...(parsedRepair.values['install-id'] === undefined
+                    ? {}
+                    : { installId: parsedRepair.values['install-id'] }),
+                apply: parsedRepair.values.apply === true,
+                quarantineUnownedLocks: parsedRepair.values['quarantine-unowned-locks'] === true,
+                resetLocal: parsedRepair.values['reset-local'] === true,
+                allWritersStopped: parsedRepair.values['all-writers-stopped'] === true,
+                json: parsedRepair.values.json === true,
+            }, output);
+        }
+        catch (error) {
+            failure(output, jsonRequested, 'invalid_arguments', error);
+            return 2;
+        }
+    }
+    if (args[0] === 'session') {
+        try {
+            const parsedSession = parseArgs({
+                args: [...args.slice(1)],
+                options: {
+                    config: { type: 'string' },
+                    json: { type: 'boolean' },
+                    help: { type: 'boolean', short: 'h' },
+                },
+                allowPositionals: true,
+                strict: true,
+            });
+            if (parsedSession.values.help) {
+                output.stdout(`${sessionUsage}\n`);
+                return 0;
+            }
+            if (parsedSession.positionals.length !== 1 ||
+                args.filter((arg) => arg === '--config' || arg.startsWith('--config='))
+                    .length > 1)
+                throw new Error(sessionUsage);
+            return runSessionCommand({
+                action: parsedSession.positionals[0],
+                config: parsedSession.values.config ?? null,
+                json: parsedSession.values.json ?? false,
+            }, output);
+        }
+        catch (error) {
+            failure(output, jsonRequested, 'invalid_arguments', error);
+            return 2;
+        }
+    }
     let parsed;
     try {
         parsed = parseOptions(args);
@@ -287,7 +123,61 @@ export async function runCli(args, output) {
     }
     const { values, command, docsAction, docsArgument, codeAction, hostAction, collaborationAction, resumeTaskId, runtimeAction, hostSubAction, taskAction, taskArgument, } = parsed;
     const json = values.json === true;
+    if (values['allow-workspace-writes'] === true && command !== 'mcp') {
+        failure(output, json, 'invalid_arguments', '--allow-workspace-writes is a trusted MCP server startup option only.');
+        return 2;
+    }
     const applyRequested = values.apply === true;
+    if (command === 'collab' && collaborationAction === 'role-run') {
+        const allowed = new Set(['request', 'apply', 'watch', 'json', 'help']);
+        const invalid = Object.entries(values).some(([key, value]) => value !== undefined && !allowed.has(key));
+        const duplicates = args.filter((arg) => arg === '--request' || arg.startsWith('--request='))
+            .length > 1;
+        if (invalid || duplicates) {
+            failure(output, json, 'invalid_arguments', collaborationRoleRunUsage);
+            return 2;
+        }
+        if (values.help) {
+            output.stdout(`${collaborationRoleRunUsage}\n`);
+            return 0;
+        }
+        return runCollaborationRoleRunCommand({
+            requestFile: values.request ?? null,
+            apply: applyRequested,
+            watch: values.watch === true,
+            json,
+        }, output);
+    }
+    if (values.watch !== undefined) {
+        failure(output, json, 'invalid_arguments', '--watch is supported only by collab role-run.');
+        return 2;
+    }
+    if (command === 'collab' && collaborationAction?.startsWith('role-plan')) {
+        const allowed = new Set(['request', 'task-root', 'config', 'json', 'help']);
+        const extra = Object.entries(values).filter(([key, value]) => value !== undefined && !allowed.has(key));
+        const duplicate = ['--request', '--task-root', '--config'].some((flag) => args.filter((arg) => arg === flag || arg.startsWith(`${flag}=`))
+            .length > 1);
+        if (extra.length || duplicate) {
+            failure(output, json, 'invalid_arguments', collaborationRolePlanUsage);
+            return 2;
+        }
+        if (values.help) {
+            output.stdout(`${collaborationRolePlanUsage}\n`);
+            return 0;
+        }
+        return runCollaborationRolePlanCommand({
+            action: collaborationAction.slice('role-plan:'.length),
+            requestFile: values.request ?? null,
+            taskRoot: values['task-root'] ?? null,
+            planFile: values.config ?? null,
+            json,
+        }, output);
+    }
+    if (values.live === true &&
+        !(command === 'collab' && collaborationAction === 'capabilities:derive')) {
+        failure(output, json, 'invalid_arguments', '--live is only valid for collab capabilities derive.');
+        return 2;
+    }
     if (command !== 'init' &&
         (values['no-interactive'] === true ||
             values['print-choices'] === true ||
@@ -312,20 +202,42 @@ export async function runCli(args, output) {
         failure(output, json, 'invalid_arguments', '--hosts, --apply-host, --dry-run and --print-handoff are only valid for onboard.');
         return 2;
     }
-    if (command !== 'host' && values.out !== undefined) {
-        failure(output, json, 'invalid_arguments', '--out is only valid for host.');
+    if (command !== 'host' && values['bootstrap-config'] !== undefined) {
+        failure(output, json, 'invalid_arguments', '--bootstrap-config is only valid for host bundle.');
         return 2;
     }
-    if (values.scope !== undefined &&
-        values.scope !== 'project' &&
-        values.scope !== 'user') {
-        failure(output, json, 'invalid_arguments', '--scope accepts project or user.');
+    if (command !== 'host' && values['recovery-config'] !== undefined) {
+        failure(output, json, 'invalid_arguments', '--recovery-config is only valid for host bundle.');
         return 2;
     }
-    if (command !== 'host' && values.scope !== undefined) {
-        failure(output, json, 'invalid_arguments', '--scope is only valid for host.');
+    if (command !== 'host' && values['transition-extension'] === true) {
+        failure(output, json, 'invalid_arguments', '--transition-extension is only valid for host bundle.');
         return 2;
     }
+    if (command !== 'host' && values.out !== undefined) {
+        failure(output, json, 'invalid_arguments', '--out 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.');
         return 2;
@@ -351,6 +263,25 @@ export async function runCli(args, output) {
         failure(output, json, 'invalid_arguments', '--from, --tarball, --bind and --force are only valid for runtime.');
         return 2;
     }
+    const rpcRequestTimeout = values['rpc-request-timeout-ms'];
+    const rpcOperationTimeout = values['rpc-operation-timeout-ms'];
+    for (const [name, value, maximum] of [
+        ['rpc-request-timeout-ms', rpcRequestTimeout, 60_000],
+        ['rpc-operation-timeout-ms', rpcOperationTimeout, 86_400_000],
+    ]) {
+        if (value === undefined)
+            continue;
+        if (command !== 'collab' ||
+            collaborationAction !== 'run' ||
+            values.controller !== 'pi-rpc' ||
+            !/^[0-9]+$/.test(value) ||
+            !Number.isSafeInteger(Number(value)) ||
+            Number(value) < 1 ||
+            Number(value) > maximum) {
+            failure(output, json, 'invalid_arguments', `--${name} requires collab run --controller pi-rpc and an integer from 1 to ${maximum}.`);
+            return 2;
+        }
+    }
     let info;
     try {
         info = getPackageInfo();
@@ -367,44 +298,40 @@ export async function runCli(args, output) {
         output.stdout(json ? `${JSON.stringify(info)}\n` : `${info.version}\n`);
         return 0;
     }
+    if (command !== 'collab' &&
+        (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.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)) {
+        failure(output, json, 'invalid_arguments', '--task-root, --message, --message-id, --binding, --retry, --caller-pane, --assignment, --max-age-minutes, --harness, --template, --execution, --events, --request, --owner-epoch, --subtask-id, --attempt, --task-id, --record and --roots are only valid for collab.');
+        return 2;
+    }
     if (command === 'collab') {
-        if (values.help) {
-            if (json) {
-                output.stdout(`${JSON.stringify({ ...info, commands: ['collab'], usage: collaborationUsage })}\n`);
-            }
-            else {
-                output.stdout(collaborationUsage);
-            }
-            return 0;
-        }
-        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['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,
-        }, output);
+        });
     }
     if (command === 'docs') {
         if (values.version ||
@@ -414,7 +341,7 @@ export async function runCli(args, output) {
             values['runtime-version'] !== undefined ||
             values.root !== undefined ||
             hasContinuityOptions(values)) {
-            failure(output, json, 'invalid_arguments', 'docs only accepts list/check/archive/scan, --include-private, --include-archived, --apply (scan only), --help, and --json.');
+            failure(output, json, 'invalid_arguments', 'docs accepts list/check/archive/scan/relocate/forget, --include-private, --include-archived, --apply, --help, and --json.');
             return 2;
         }
         if (values.help) {
@@ -430,6 +357,8 @@ export async function runCli(args, output) {
             cwd: process.cwd(),
             action: docsAction,
             argument: docsArgument,
+            targetPath: 'docsTarget' in parsed ? parsed.docsTarget : null,
+            scope: values.scope ?? null,
             json,
             includePrivate: values['include-private'] === true,
             includeArchived: values['include-archived'] === true,
@@ -524,7 +453,7 @@ export async function runCli(args, output) {
             values.rebuild === true ||
             values.host !== undefined ||
             hasContinuityOptions(values)) {
-            failure(output, json, 'invalid_arguments', 'mcp accepts only --root, --help, and --json.');
+            failure(output, json, 'invalid_arguments', 'mcp accepts --root, --allow-workspace-writes, --help, and --json.');
             return 2;
         }
         if (values.help) {
@@ -540,7 +469,12 @@ export async function runCli(args, output) {
             failure(output, json, 'invalid_arguments', '--version cannot be combined with mcp.');
             return 2;
         }
-        return runMcpCommand({ cwd: process.cwd(), root: values.root ?? null, json }, output);
+        return runMcpCommand({
+            cwd: process.cwd(),
+            root: values.root ?? null,
+            json,
+            allowWorkspaceWrites: values['allow-workspace-writes'] === true,
+        }, output);
     }
     if (command === 'onboard') {
         if (values.apply === true ||
@@ -648,13 +582,14 @@ export async function runCli(args, output) {
             values.query !== undefined ||
             values.kind !== undefined ||
             hasContinuityOptions(values)) {
-            failure(output, json, 'invalid_arguments', 'runtime accepts only --from, --tarball, --version, --apply, --bind, --force, --help, and --json.');
+            failure(output, json, 'invalid_arguments', 'runtime accepts only --from, --tarball, --runtime-version, --apply, --bind, --force, --help, and --json.');
             return 2;
         }
         const action = runtimeAction === 'install' ||
             runtimeAction === 'status' ||
             runtimeAction === 'verify' ||
-            runtimeAction === 'remove'
+            runtimeAction === 'remove' ||
+            runtimeAction === 'gc'
             ? runtimeAction
             : null;
         return runRuntimeCommand({
@@ -847,6 +782,7 @@ export async function runCli(args, output) {
             'describe',
             'plan',
             'install',
+            'uninstall',
             'verify',
             'bundle',
             'mcp',
@@ -855,6 +791,10 @@ export async function runCli(args, output) {
         const action = allowedActions.find((item) => item === hostAction) ?? null;
         const parsedHost = hostNameSchema.safeParse(values.host);
         const host = parsedHost.success ? parsedHost.data : null;
+        const duplicatedBootstrapConfig = args.filter((arg) => arg === '--bootstrap-config' || arg.startsWith('--bootstrap-config=')).length > 1;
+        const duplicatedRecoveryConfig = args.filter((arg) => arg === '--recovery-config' || arg.startsWith('--recovery-config=')).length > 1;
+        const duplicatedTransitionExtension = args.filter((arg) => arg === '--transition-extension' ||
+            arg.startsWith('--transition-extension=')).length > 1;
         const invalid = values.version ||
             values.config !== undefined ||
             values['install-runtime'] === true ||
@@ -870,15 +810,42 @@ export async function runCli(args, output) {
             values['max-bytes'] !== undefined ||
             values.rebuild === true ||
             hasContinuityOptions(values) ||
-            (values.apply === true && action !== 'install' && action !== 'mcp') ||
+            (values.apply === true &&
+                action !== 'install' &&
+                action !== 'uninstall' &&
+                action !== 'mcp') ||
             (values.mode !== undefined && action !== 'install') ||
             (values.marketplace === true && action !== 'bundle') ||
+            (values['bootstrap-config'] !== undefined &&
+                (action !== 'bundle' ||
+                    values.marketplace === true ||
+                    values.mode !== undefined ||
+                    values.apply === true ||
+                    values['recovery-config'] !== undefined ||
+                    values['transition-extension'] === true)) ||
+            (values['recovery-config'] !== undefined &&
+                (action !== 'bundle' ||
+                    host !== 'pi' ||
+                    values.marketplace === true ||
+                    values.mode !== undefined ||
+                    values.apply === true)) ||
+            (values['transition-extension'] === true &&
+                (action !== 'bundle' ||
+                    host !== 'pi' ||
+                    values.marketplace === true ||
+                    values.mode !== undefined ||
+                    values.apply === true ||
+                    values['bootstrap-config'] !== undefined)) ||
             (values.scope !== undefined &&
                 action !== 'plan' &&
                 action !== 'install' &&
+                action !== 'uninstall' &&
                 action !== 'verify') ||
             (values['host-root'] !== undefined && action === null) ||
-            (values['host-version'] !== undefined && action === null);
+            (values['host-version'] !== undefined && action === null) ||
+            duplicatedBootstrapConfig ||
+            duplicatedRecoveryConfig ||
+            duplicatedTransitionExtension;
         if (values.help) {
             if (json) {
                 output.stdout(`${JSON.stringify({ ...info, commands: ['host'], usage: hostUsage })}\n`);
@@ -889,7 +856,7 @@ export async function runCli(args, output) {
             return 0;
         }
         if (action === null || host === null || invalid) {
-            failure(output, json, 'invalid_arguments', 'host requires detect/describe/plan/install/verify/bundle, --host, and action-compatible options.');
+            failure(output, json, 'invalid_arguments', 'host requires detect/describe/probe/plan/install/verify/uninstall/bundle/mcp, --host, and action-compatible options.');
             return 2;
         }
         return runHostCommand({
@@ -906,6 +873,9 @@ export async function runCli(args, output) {
             mode: values.mode === 'project-settings' || values.mode === 'plugin'
                 ? values.mode
                 : null,
+            bootstrapConfig: values['bootstrap-config'] ?? null,
+            recoveryConfig: values['recovery-config'] ?? null,
+            transitionExtension: values['transition-extension'] === true,
             marketplace: values.marketplace === true,
             scope: values.scope === 'project' || values.scope === 'user'
                 ? values.scope
@@ -930,16 +900,16 @@ export async function runCli(args, output) {
     }
     if (values.help) {
         if (json) {
-            output.stdout(`${JSON.stringify({ ...info, usage: globalUsage, commands: ['init', 'doctor', 'docs', 'checkpoint', 'resume', 'code', 'host', 'collab'] })}\n`);
+            output.stdout(`${JSON.stringify({ ...info, usage: globalUsage, commands: ['init', 'onboard', 'doctor', 'repair', 'docs', 'checkpoint', 'resume', 'code', 'host', 'runtime', 'task', 'mcp', 'collab', 'session'] })}\n`);
         }
         else {
-            output.stdout(`${info.name} ${info.version}\n${info.description}\n\nUsage:\n  ${globalUsage.replaceAll('\n', '\n  ')}\n\nOptions:\n  -h, --help     Show help\n  -v, --version  Show version\n      --json     Output JSON\n\nCommands:\n  init           Plan workspace initialization\n  doctor         Read-only workspace and installation diagnostics\n  docs           List, check, and archive registered documents\n`);
-            output.stdout('  checkpoint     Save a private task checkpoint\n  resume         Read a bounded recovery packet without starting an agent\n  code           Inspect or prepare selected code intelligence\n  host           Detect, plan, install, or verify a selected host integration\n  collab         Prepare, run, or query a bounded collaboration goal\n');
+            output.stdout(`${info.name} ${info.version}\n${info.description}\n\nUsage:\n  ${globalUsage.replaceAll('\n', '\n  ')}\n\nOptions:\n  -h, --help     Show help\n  -v, --version  Show version\n      --json     Output JSON\n\nCommands:\n  init           Plan workspace initialization\n  onboard        Discover and connect supported hosts\n  doctor         Read-only workspace and installation diagnostics\n  repair         Inspect and repair interrupted state\n  docs           Scan, relocate, forget and inspect knowledge\n  runtime        Install, verify and remove durable runtimes\n  task           Select a private task and auto-resume preference\n  mcp            Serve workspace tools over stdio\n`);
+            output.stdout('  checkpoint     Save a private task checkpoint\n  resume         Read a bounded recovery packet without starting an agent\n  code           Inspect or prepare selected code intelligence\n  host           Detect, plan, install, or verify a selected host integration\n  collab         Prepare, run, query, message, preflight, state, recovery and bindings\n  session        Launch and control an owned visible native Pi session\n');
         }
         return 0;
     }
     if (json) {
-        output.stdout(`${JSON.stringify({ ...info, usage: globalUsage, commands: ['init', 'doctor', 'docs', 'checkpoint', 'resume', 'code', 'host', 'collab'] })}\n`);
+        output.stdout(`${JSON.stringify({ ...info, usage: globalUsage, commands: ['init', 'onboard', 'doctor', 'repair', 'docs', 'checkpoint', 'resume', 'code', 'host', 'runtime', 'task', 'mcp', 'collab', 'session'] })}\n`);
     }
     else {
         output.stdout(`${info.name} ${info.version}\n${info.description}\n\nUsage:\n  ${globalUsage}\n\nRun pappra --help for all options.\n`);