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

package/dist/cli/commands/collaboration-work-run.js

@@ -0,0 +1,178 @@
+import path from 'node:path';
+import { readBoundedFile } from '../../app/bounded-file.js';
+import { COLLAB_WORK_EXECUTION_SCHEMA, runWorkExecution, } from '../../app/collab-work-execution.js';
+const MAX_REQUEST_BYTES = 64 * 1024;
+export const collaborationWorkRunUsage = 'pappra collab work-run --request <abs work-execution.json> [--apply] [--json]\n\n' +
+    'Without --apply this is a zero-write, zero-notification plan. Apply revalidates the\n' +
+    'pinned work plan, current assignments, capability cards, coordinator epoch, resource\n' +
+    'claims and visible participant binding; it records a durable per-node intent before\n' +
+    'one bounded concurrent notification batch. Existing/unknown intents are reconciliation\n' +
+    'only and are never automatically replayed. This command never launches sessions, merges\n' +
+    'code or accepts a report.';
+export function parseCollaborationWorkRunArgs(argv) {
+    const errors = [];
+    let requestFile = null;
+    let apply = false;
+    let json = false;
+    let sawApply = false;
+    let sawJson = false;
+    for (let index = 0; index < argv.length; index += 1) {
+        const arg = argv[index];
+        if (arg === '--request') {
+            if (requestFile !== null)
+                errors.push('--request may be given only once.');
+            const value = argv[index + 1];
+            if (value === undefined || value.startsWith('--'))
+                errors.push('--request requires a value.');
+            else {
+                requestFile = value;
+                index += 1;
+            }
+        }
+        else if (arg === '--apply') {
+            if (sawApply)
+                errors.push('--apply may be given only once.');
+            sawApply = true;
+            apply = true;
+        }
+        else if (arg === '--json') {
+            if (sawJson)
+                errors.push('--json may be given only once.');
+            sawJson = true;
+            json = true;
+        }
+        else
+            errors.push(`unknown option: ${String(arg)}`);
+    }
+    return { options: { requestFile, apply, json }, errors };
+}
+function isObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function isAbsolute(value) {
+    return typeof value === 'string' && path.isAbsolute(value);
+}
+function loadRequest(file) {
+    const read = readBoundedFile(file, MAX_REQUEST_BYTES);
+    if (!read.ok)
+        return { ok: false, error: `request_file_${read.code}` };
+    let parsed;
+    try {
+        parsed = JSON.parse(read.text);
+    }
+    catch {
+        return { ok: false, error: 'request_file_invalid_json' };
+    }
+    if (!isObject(parsed) ||
+        parsed.schema !== 'pappra/collab-work-execution-request/1')
+        return { ok: false, error: 'request_schema_invalid' };
+    const keys = Object.keys(parsed).sort();
+    const expected = [
+        'binding_file',
+        'caller',
+        'caller_pane',
+        'capability_cards',
+        'plan_file',
+        'schema',
+        'task_root',
+    ];
+    const expectedOptional = [...expected, 'max_concurrency'].sort();
+    if (keys.join('|') !== expected.sort().join('|') &&
+        keys.join('|') !== expectedOptional.join('|'))
+        return { ok: false, error: 'request_fields_invalid' };
+    if (!isAbsolute(parsed.task_root) ||
+        !isAbsolute(parsed.plan_file) ||
+        !isAbsolute(parsed.binding_file))
+        return { ok: false, error: 'request_paths_must_be_absolute' };
+    if (typeof parsed.caller_pane !== 'string' ||
+        !/^[A-Za-z0-9]+:p[A-Za-z0-9]+$/.test(parsed.caller_pane))
+        return { ok: false, error: 'caller_pane_invalid' };
+    if (!isObject(parsed.caller) ||
+        Object.keys(parsed.caller).sort().join('|') !==
+            'agent_id|cwd|harness|session_id' ||
+        typeof parsed.caller.agent_id !== 'string' ||
+        typeof parsed.caller.session_id !== 'string' ||
+        typeof parsed.caller.harness !== 'string' ||
+        !isAbsolute(parsed.caller.cwd))
+        return { ok: false, error: 'caller_identity_invalid' };
+    if (!Array.isArray(parsed.capability_cards) ||
+        parsed.capability_cards.length > 64)
+        return { ok: false, error: 'capability_cards_invalid' };
+    const assignmentIds = new Set();
+    const cards = [];
+    for (const item of parsed.capability_cards) {
+        if (!isObject(item) ||
+            Object.keys(item).sort().join('|') !==
+                'assignment_id|capabilities_file' ||
+            typeof item.assignment_id !== 'string' ||
+            !isAbsolute(item.capabilities_file) ||
+            assignmentIds.has(item.assignment_id))
+            return { ok: false, error: 'capability_cards_invalid' };
+        assignmentIds.add(item.assignment_id);
+        cards.push({
+            assignment_id: item.assignment_id,
+            capabilities_file: item.capabilities_file,
+        });
+    }
+    const maxConcurrency = parsed.max_concurrency;
+    if (maxConcurrency !== undefined &&
+        (typeof maxConcurrency !== 'number' ||
+            !Number.isSafeInteger(maxConcurrency) ||
+            maxConcurrency < 1 ||
+            maxConcurrency > 8))
+        return { ok: false, error: 'max_concurrency_invalid' };
+    return {
+        ok: true,
+        value: {
+            task_root: parsed.task_root,
+            plan_file: parsed.plan_file,
+            binding_file: parsed.binding_file,
+            caller: parsed.caller,
+            caller_pane: parsed.caller_pane,
+            capability_cards: cards,
+            ...(maxConcurrency === undefined
+                ? {}
+                : { max_concurrency: maxConcurrency }),
+        },
+    };
+}
+function invalid(output, options, errors) {
+    if (options.json)
+        output.stdout(`${JSON.stringify({ schema: COLLAB_WORK_EXECUTION_SCHEMA, ok: false, status: 'invalid', errors })}\n`);
+    else {
+        output.stdout('Work execution request invalid.\n');
+        for (const error of errors)
+            output.stdout(`  - ${error}\n`);
+        output.stdout(`\n${collaborationWorkRunUsage}\n`);
+    }
+    return 2;
+}
+function emitHuman(report, output) {
+    output.stdout(`Work execution ${report.apply ? 'apply' : 'plan'}: ${report.status}${report.task_id ? ` (${report.task_id})` : ''}.\n`);
+    output.stdout(`  nodes ${report.nodes.length}, concurrent limit ${report.concurrency.limit}, actual overlap ${report.concurrency.actual_overlap ? 'yes' : 'no'}\n`);
+    for (const node of report.nodes) {
+        output.stdout(`  ${node.role} ${node.node_id} (${node.assignment_id}#${node.attempt}): ${node.execution_status}; acceptance ${node.acceptance}\n`);
+        for (const blocker of node.blockers)
+            output.stdout(`    - ${blocker}\n`);
+        if (node.intent_message_id)
+            output.stdout(`    intent: ${node.intent_message_id}\n`);
+    }
+    output.stdout(`  immutable report pointers: ${report.reports.length}; no merge or acceptance performed\n`);
+}
+export async function runCollaborationWorkRunCommand(options, output, deps = {}) {
+    if (options.requestFile === null)
+        return invalid(output, options, ['--request is required.']);
+    if (!path.isAbsolute(options.requestFile))
+        return invalid(output, options, ['--request must be absolute.']);
+    const request = loadRequest(options.requestFile);
+    if (!request.ok)
+        return invalid(output, options, [request.error]);
+    const report = await runWorkExecution({ request: request.value, apply: options.apply }, deps);
+    if (options.json)
+        output.stdout(`${JSON.stringify(report)}\n`);
+    else
+        emitHuman(report, output);
+    if (report.status === 'planned' || report.status === 'applied')
+        return 0;
+    return report.status === 'invalid' ? 2 : 1;
+}

package/dist/cli/commands/collaboration.d.ts

@@ -1,4 +1,6 @@
 import type { CliOutput } from '../output.js';
+/** One source of truth for the full collaboration command family in help output. */
+export declare const collaborationCommandLine = "pappra collab <prepare|run|work-run|role-run|query|preflight|plan|role-plan|bootstrap|rollover|transition|message|capabilities|state|resource|handoff|recovery|recovery-run|binding> [options]";
 export declare const collaborationUsage: string;
 export interface CollaborationCommandOptions {
     readonly cwd: string;
@@ -9,5 +11,7 @@ export interface CollaborationCommandOptions {
     readonly capabilitiesFile: string | null;
     readonly controller: string | null;
     readonly domainRoot: string | null;
+    readonly rpcRequestTimeoutMs?: number;
+    readonly rpcOperationTimeoutMs?: number;
 }
 export declare function runCollaborationCommand(options: CollaborationCommandOptions, output: CliOutput, input?: NodeJS.ReadableStream): Promise<number>;

package/dist/cli/commands/collaboration.js

@@ -1,10 +1,38 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { FixtureController, PiRpcController, driveRun, inspectPreparedHistory, prepareCollaboration, startPrepared, } from '../../app/collaboration.js';
-export const collaborationUsage = 'pappra collab <prepare|run|query> [options]\n' +
+/** One source of truth for the full collaboration command family in help output. */
+export const collaborationCommandLine = 'pappra collab <prepare|run|work-run|role-run|query|preflight|plan|role-plan|bootstrap|rollover|transition|message|capabilities|state|resource|handoff|recovery|recovery-run|binding> [options]';
+export const collaborationUsage = `${collaborationCommandLine}\n` +
     '  prepare --goal <file> --domain-root <dir> [--json]\n' +
     '  run --prepared <file> --capabilities <card> --controller <fixture|pi-rpc>\n' +
+    '    [--rpc-request-timeout-ms <1..60000>] [--rpc-operation-timeout-ms <1..86400000>]\n' +
+    '  work-run --request <abs work-execution.json> [--apply] [--json]\n' +
+    '  role-run --request <abs role-orchestration.json> [--apply] [--json]\n' +
+    '    Apply records bounded notification intents; plans write and notify nothing.\n' +
     '  query --prepared <file> [--json]\n' +
+    '  preflight --assignment <file> --capabilities <card> [--max-age-minutes <n>] [--json]\n' +
+    '  plan --task-root <dir> --config <plan.json> [--json]\n' +
+    '  role-plan expand --request <abs role-plan.json> [--json]\n' +
+    '  role-plan aggregate --request <abs role-plan.json> --task-root <abs> --config <abs expanded-plan.json> [--json]\n' +
+    '  rollover <inspect|plan> --task-root <dir> --request <request.json> [--json]\n' +
+    '  bootstrap <plan|apply> --task-root <abs> --request <abs request.json> [--json]\n' +
+    '    Plan is read-only; apply launches only a visible Pi sibling or verified task-bound reuse.\n' +
+    '    Unknown effects are reconciled, not retried; submission is not acceptance.\n' +
+    '    Rollover remains read-only: no apply, native stop proof, route removal or session archive.\n' +
+    '  transition <plan|apply> --task-root <abs> --request <abs request.json> [--json]\n' +
+    '    Pre-transfer apply requires the opt-in Pi host; first-work and retirement resume from CLI.\n' +
+    '    Unsupported native-quiescence proof blocks before successor launch or claim transfer.\n' +
+    '    Applied ACK and REPORT pointers are required; retirement retains the original transcript.\n' +
+    '  message <send|list|read|notify> --task-root <dir> [options]\n' +
+    '  capabilities derive --harness <pi|codex|claude> --assignment <file> --template <file> [--execution <file> | --live] [--session <file> | --events <file>] [--json]\n' +
+    '  state <show|doctor|epoch-check> --task-root <dir> [options]\n' +
+    '  resource <list|claim|release> --task-root <dir> [options]\n' +
+    '  handoff <inventory|begin|stopped|rebind|transfer|confirm|complete|abort|release-dispatch> --task-root <dir> [options]\n' +
+    '  recovery <inspect|reconcile|lock-break> --task-root <dir> [options]\n' +
+    '  recovery-run --request <abs recovery-run.json> [--apply] [--json]\n' +
+    '    Apply requires exact session/cwd/harness/pane and a task-local digest-pinned binding.\n' +
+    '  binding <list|resolve|bind|unbind> [--root <dir>] [options]\n' +
     '  run reads pappra/collaboration-command/1 JSONL from stdin and writes\n' +
     '  pappra/collaboration-event/1 JSONL to stdout.';
 function failure(code, message) {
@@ -17,11 +45,18 @@ function readGoal(file) {
     }
     return JSON.parse(fs.readFileSync(file, 'utf8'));
 }
-function controllerFor(name) {
+function controllerFor(name, options) {
     if (name === 'fixture')
         return new FixtureController();
     if (name === 'pi-rpc')
-        return new PiRpcController();
+        return new PiRpcController({
+            ...(options.rpcRequestTimeoutMs === undefined
+                ? {}
+                : { requestTimeoutMs: options.rpcRequestTimeoutMs }),
+            ...(options.rpcOperationTimeoutMs === undefined
+                ? {}
+                : { operationTimeoutMs: options.rpcOperationTimeoutMs }),
+        });
     return null;
 }
 const MAX_COMMAND_LINE_BYTES = 256 * 1024;
@@ -145,7 +180,7 @@ export async function runCollaborationCommand(options, output, input = process.s
             output.stderr('pappra: collab run requires --prepared <file> and --capabilities <card>\n');
             return 2;
         }
-        const controller = controllerFor(options.controller);
+        const controller = controllerFor(options.controller, options);
         if (controller === null) {
             output.stderr('pappra: collab run requires --controller <fixture|pi-rpc>\n');
             return 2;

package/dist/cli/commands/continuity.js

@@ -124,10 +124,6 @@ export async function runResumeCommand(options, output) {
     else {
         printDiagnostics(output, result.diagnostics);
     }
-    return result.ok &&
-        result.packet !== null &&
-        result.packet.executionAllowed &&
-        result.packet.verificationStatus === 'current'
-        ? 0
-        : 1;
+    // Reading advisory handoff context does not acquire execution authority.
+    return result.ok && result.packet?.verificationStatus === 'current' ? 0 : 1;
 }

package/dist/cli/commands/docs.d.ts

@@ -4,6 +4,8 @@ export interface DocsCommandOptions {
     readonly cwd: string;
     readonly action: string | null;
     readonly argument: string | null;
+    readonly targetPath?: string | null;
+    readonly scope?: string | null;
     readonly json: boolean;
     readonly includePrivate: boolean;
     readonly includeArchived: boolean;

package/dist/cli/commands/docs.js

@@ -1,15 +1,18 @@
 import { resolveWorkspaceRoot } from '../../workspace/resolve.js';
 import { scanDiscoveredDocuments } from '../../knowledge/scan.js';
 import { formatDiagnostic } from '../../schemas/diagnostics.js';
-import { docsArchiveReportSchema, docsCheckReportSchema, docsListReportSchema, } from '../../schemas/document.js';
+import { docsArchiveReportSchema, docsCheckReportSchema, docsListReportSchema, documentLocationSchema, } from '../../schemas/document.js';
 import { KnowledgeService, } from '../../knowledge/index.js';
-export const docsUsage = 'pappra docs <list|check|archive|scan> [options]\n' +
+export const docsUsage = 'pappra docs <list|check|archive|scan|relocate|forget> [options]\n' +
     '  list   [--include-private] [--include-archived] [--json]\n' +
     '  check  [--include-private] [--json]\n' +
     '  archive <documentId> [--json]\n' +
     '  scan   [--apply] [--json]\n\n' +
-    'scan registers documents discovered under the configured knowledge sources; without\n' +
-    '--apply it only reports the candidates.';
+    '  relocate <documentId> <workspace-relative-path> [--apply] [--json]\n' +
+    '  forget <documentId> [--scope private|shared] [--apply] [--json]\n\n' +
+    'scan registers existing documents discovered under knowledge.sources; newDocuments is\n' +
+    'only the destination for future authored documents. Without --apply scan only reports\n' +
+    'candidates.';
 async function runDocsScan(options, output, root) {
     const result = await scanDiscoveredDocuments(root, { apply: options.apply });
     if ('message' in result) {
@@ -20,20 +23,37 @@ async function runDocsScan(options, output, root) {
             output.stdout(`${JSON.stringify(result)}\n`);
         }
         else {
-            output.stdout(`Scan candidates: ${result.candidates.length}\n`);
-            for (const candidate of result.candidates) {
-                output.stdout(`  ${candidate.kind}  ${candidate.path}\n`);
+            if (result.candidates.length === 0) {
+                output.stdout('No new documents found.\n');
             }
-            output.stdout('Plan only; rerun with --apply to register them.\n');
+            else {
+                output.stdout(`Scan candidates: ${result.candidates.length}\n`);
+                for (const candidate of result.candidates) {
+                    output.stdout(`  ${candidate.kind}  ${candidate.path}\n`);
+                }
+            }
+            printDiagnostics(output, result.diagnostics);
+            for (const action of result.nextActions) {
+                output.stdout(`${action}\n`);
+            }
+            output.stdout(result.ok
+                ? 'Plan only; rerun with --apply to register them.\n'
+                : 'Scan coverage is incomplete; no complete result is claimed.\n');
         }
-        return 0;
+        return result.ok ? 0 : 1;
     }
     if (options.json) {
         output.stdout(`${JSON.stringify(result)}\n`);
     }
     else {
         output.stdout(`Registered ${result.registered.length} document(s).\n`);
+        if (!result.ok) {
+            output.stdout('Scan coverage is incomplete; the registration result is not a complete scan.\n');
+        }
         printDiagnostics(output, result.diagnostics);
+        for (const action of result.nextActions) {
+            output.stdout(`${action}\n`);
+        }
     }
     return result.ok ? 0 : 1;
 }
@@ -75,7 +95,7 @@ export async function runDocsCommand(options, output) {
     if (options.action === null || options.action === 'help') {
         if (options.json) {
             output.stdout(`${JSON.stringify({
-                commands: ['list', 'check', 'archive'],
+                commands: ['list', 'check', 'archive', 'scan', 'relocate', 'forget'],
                 usage: docsUsage,
             })}\n`);
         }
@@ -84,22 +104,67 @@ export async function runDocsCommand(options, output) {
         }
         return 0;
     }
+    if (options.scope !== undefined &&
+        options.scope !== null &&
+        (options.action !== 'forget' ||
+            !['private', 'shared'].includes(options.scope)))
+        return invalidArguments(output, options.json, 'Only docs forget accepts --scope private|shared.');
     const resolution = await resolveWorkspaceRoot({ startPath: options.cwd });
     const serviceRoot = resolution.root ?? options.cwd;
-    if (!['list', 'check', 'archive', 'scan'].includes(options.action)) {
+    if (!['list', 'check', 'archive', 'scan', 'relocate', 'forget'].includes(options.action)) {
         return invalidArguments(output, options.json, `unknown docs action: ${options.action}`);
     }
-    if (options.action === 'archive' && options.argument === null) {
-        return invalidArguments(output, options.json, 'docs archive requires a documentId');
+    if (['archive', 'relocate', 'forget'].includes(options.action) &&
+        options.argument === null) {
+        return invalidArguments(output, options.json, `docs ${options.action} requires a documentId`);
     }
-    if (options.action !== 'archive' && options.argument !== null) {
+    if (!['archive', 'relocate', 'forget'].includes(options.action) &&
+        options.argument !== null) {
         return invalidArguments(output, options.json, `docs ${options.action} does not accept an argument`);
     }
     if (options.action === 'scan') {
         return runDocsScan(options, output, serviceRoot);
     }
+    if ((options.action === 'relocate' || options.action === 'forget') &&
+        options.argument !== null) {
+        const location = options.action === 'relocate'
+            ? documentLocationSchema.safeParse({
+                kind: 'workspace',
+                path: options.targetPath,
+            })
+            : null;
+        if (location && !location.success)
+            return invalidArguments(output, options.json, 'docs relocate requires a normalized workspace-relative target path.');
+        if (!options.apply) {
+            const plan = {
+                schema: 'pappra/docs-metadata-plan/1',
+                ok: true,
+                action: options.action,
+                documentId: options.argument,
+                scope: options.scope ?? null,
+                location: location?.success ? location.data : null,
+                applied: false,
+            };
+            output.stdout(options.json
+                ? `${JSON.stringify(plan)}\n`
+                : `Plan only: ${options.action} ${options.argument}; document content is preserved. Rerun with --apply.\n`);
+            return 0;
+        }
+        const service = new KnowledgeService(serviceRoot);
+        const result = location?.success
+            ? await service.relocate(options.argument, location.data)
+            : await service.forget(options.argument, options.scope === 'private' || options.scope === 'shared'
+                ? options.scope
+                : undefined);
+        output.stdout(options.json
+            ? `${JSON.stringify({ schema: 'pappra/docs-metadata-result/1', action: options.action, ...result })}\n`
+            : `${options.action}: ${result.ok ? 'applied' : result.status}\n`);
+        if (!options.json)
+            printDiagnostics(output, result.diagnostics);
+        return result.ok ? 0 : 1;
+    }
     if (options.apply) {
-        return invalidArguments(output, options.json, 'only docs scan accepts --apply');
+        return invalidArguments(output, options.json, 'only docs scan, relocate and forget accept --apply');
     }
     if (options.action === 'archive' && options.argument !== null) {
         const service = new KnowledgeService(serviceRoot);
@@ -142,6 +207,15 @@ export async function runDocsCommand(options, output) {
         else {
             for (const record of result.records)
                 printDocument(output, record);
+            if (result.records.length === 0 && !options.includePrivate && result.ok) {
+                const command = options.includeArchived
+                    ? 'pappra docs list --include-private --include-archived'
+                    : 'pappra docs list --include-private';
+                output.stdout(`No documents in the default view. Private documents are hidden; run: ${command}\n`);
+                if (!options.includeArchived) {
+                    output.stdout('Archived documents also remain hidden; add --include-archived to include them.\n');
+                }
+            }
             printDiagnostics(output, result.diagnostics);
         }
         return result.ok ? 0 : 1;

package/dist/cli/commands/host.d.ts

@@ -4,7 +4,7 @@ export declare const hostUsage: string;
 export interface HostCommandOptions {
     readonly cwd: string;
     readonly json: boolean;
-    readonly action: 'detect' | 'describe' | 'plan' | 'install' | 'verify' | 'bundle' | 'mcp' | 'probe' | null;
+    readonly action: 'detect' | 'describe' | 'plan' | 'install' | 'uninstall' | 'verify' | 'bundle' | 'mcp' | 'probe' | null;
     readonly host: HostName | null;
     readonly hostRoot: string | null;
     readonly hostVersion: string | null;
@@ -13,6 +13,12 @@ export interface HostCommandOptions {
     readonly subAction: string | null;
     readonly out: string | null;
     readonly mode: 'project-settings' | 'plugin' | null;
+    /** Explicit private bootstrap binding; Pi bundle exports only. */
+    readonly bootstrapConfig: string | null;
+    /** Explicit validated task/session binding; recovery exports are Pi-only. */
+    readonly recoveryConfig: string | null;
+    /** Opt-in Pi session-transition command extension; it is not native takeover. */
+    readonly transitionExtension: boolean;
     readonly marketplace: boolean;
     readonly scope: 'project' | 'user' | null;
 }

package/dist/cli/commands/host.js

@@ -1,17 +1,28 @@
 import { homedir } from 'node:os';
-import { join, resolve } from 'node:path';
+import { isAbsolute, join, resolve } from 'node:path';
 import { HostIntegrationService } from '../../hosts/integration/service.js';
-import { exportHostPluginBundle } from '../../hosts/integration/bundle-export.js';
+import { exportHostPluginBundle, } from '../../hosts/integration/bundle-export.js';
+import { readPiBootstrapConfig } from '../../hosts/integration/bootstrap-config.js';
+import { readPiRecoveryConfig } from '../../hosts/integration/recovery-config.js';
 import { applyHostMcp, planHostMcp, verifyHostMcp, } from '../../app/host-mcp.js';
 import { probeHost } from '../../app/host-probe.js';
 import { HOST_SUPPORT, isSupportedVersion, } from '../../hosts/integration/support.js';
-import { getPackageInfo } from '../../package-info.js';
-export const hostUsage = 'pappra host <detect|describe|plan|install|verify|bundle|mcp> --host <pi|codex|claude>\n' +
+import { getPackageInfo, getPackageRoot } from '../../package-info.js';
+export const hostUsage = 'pappra host <detect|describe|probe|plan|install|uninstall|verify|bundle|mcp> --host <pi|codex|claude>\n' +
     '  [--host-root <dir>] [--host-version <version>] [--out <dir>]\n' +
-    '  [--mode project-settings|plugin] [--apply] [--json]\n' +
+    '  [--mode project-settings|plugin] [--scope project|user] [--marketplace] [--apply] [--json]\n' +
+    '  probe --host <name> [--host-root <dir>] [--json]\n' +
+    '  uninstall --host <name> [--host-root <dir> | --scope user] [--apply] [--force]\n' +
+    '    --force asserts all host writers are stopped and archives unknown locks; edited assets remain preserved.\n' +
+    '  mcp <plan|install|verify> --host <name> [--host-root <dir>] [--apply] [--json]\n' +
+    '  bundle --host pi --out <new-private-dir> [--bootstrap-config <abs-file> |\n' +
+    '    --recovery-config <abs-file>] [--transition-extension]\n' +
     '\n' +
     'bundle exports a host-native plugin/package directory and never registers it or\n' +
-    'claims host callability.';
+    'claims host callability. Recovery and transition extensions are opt-in Pi bundle\n' +
+    'artifacts; --recovery-config must pin an exact task-local session and binding.\n' +
+    'Exports do not install, trust, load, launch or transfer; native quiescence and\n' +
+    'interactive session takeover remain unsupported.';
 /** Codex only loads lifecycle hooks from its user configuration directory. */
 function codexHome() {
     const configured = process.env['CODEX_HOME'];
@@ -66,8 +77,9 @@ export async function runHostCommand(options, output) {
         }
         if (options.action !== 'plan' &&
             options.action !== 'install' &&
+            options.action !== 'uninstall' &&
             options.action !== 'verify') {
-            output.stderr('pappra host: --scope user is only valid for plan, install, or verify.\n');
+            output.stderr('pappra host: --scope user is only valid for plan, install, uninstall, or verify.\n');
             return 2;
         }
     }
@@ -197,15 +209,109 @@ export async function runHostCommand(options, output) {
         }
         return diagnosticStatus(result.status);
     }
+    if (options.action === 'uninstall') {
+        const result = await service.uninstall(options.host, {
+            ...target,
+            apply: options.apply,
+            force: options.force,
+        });
+        if (options.json)
+            output.stdout(`${JSON.stringify(result)}\n`);
+        else {
+            output.stdout(`Status: ${result.status}\n`);
+            for (const file of result.removedFiles)
+                output.stdout(`  removed ${file}\n`);
+            for (const file of result.retainedPaths)
+                output.stdout(`  preserved ${file}\n`);
+            for (const file of result.quarantinedLocks)
+                output.stdout(`  archived lock ${file}\n`);
+            if (!options.apply)
+                output.stdout('  plan only; rerun with --apply to remove managed wiring.\n');
+            printDiagnostics(output, result.diagnostics);
+        }
+        return result.ok ? 0 : 1;
+    }
     if (options.action === 'bundle') {
         if (options.out === null) {
             output.stderr('pappra host bundle requires --out <dir>.\n');
             return 2;
         }
+        if (options.bootstrapConfig !== null) {
+            if (options.host !== 'pi') {
+                output.stderr('pappra host bundle: --bootstrap-config requires --host pi.\n');
+                return 2;
+            }
+            if (!isAbsolute(options.bootstrapConfig)) {
+                output.stderr('pappra host bundle: --bootstrap-config must be an absolute path.\n');
+                return 2;
+            }
+            if (options.marketplace || options.mode !== null || options.apply) {
+                output.stderr('pappra host bundle: --bootstrap-config cannot be combined with --marketplace, --mode or --apply.\n');
+                return 2;
+            }
+        }
         if (!isSupportedVersion(options.host, options.hostVersion)) {
             output.stderr(`Host ${options.host} version ${options.hostVersion ?? '(unknown)'} is outside the pinned ${HOST_SUPPORT[options.host].version} support matrix.\n`);
             return 1;
         }
+        let bootstrap;
+        if (options.bootstrapConfig !== null) {
+            const loaded = readPiBootstrapConfig(options.bootstrapConfig);
+            if (loaded.ok === false) {
+                if (options.json) {
+                    output.stdout(`${JSON.stringify({
+                        ok: false,
+                        command: 'host',
+                        action: 'bundle',
+                        code: loaded.code,
+                        message: loaded.message,
+                    })}\n`);
+                }
+                else {
+                    output.stderr(`pappra host bundle: ${loaded.message}\n`);
+                }
+                return 1;
+            }
+            bootstrap = {
+                config: loaded.config,
+                configBytes: loaded.bytes,
+                configDigest: loaded.digest,
+                artifactPath: join(getPackageRoot(), 'dist/hosts/integration/pappra-bootstrap-extension.mjs'),
+            };
+        }
+        let recovery;
+        if (options.recoveryConfig !== null) {
+            if (options.host !== 'pi') {
+                output.stderr('pappra host bundle: --recovery-config requires --host pi.\n');
+                return 2;
+            }
+            if (!isAbsolute(options.recoveryConfig) ||
+                options.bootstrapConfig !== null ||
+                options.marketplace ||
+                options.mode !== null ||
+                options.apply) {
+                output.stderr('pappra host bundle: --recovery-config requires an absolute path and cannot be combined with --bootstrap-config, --marketplace, --mode or --apply.\n');
+                return 2;
+            }
+            const loaded = readPiRecoveryConfig(options.recoveryConfig);
+            if (loaded.ok === false) {
+                output.stderr(`pappra host bundle: recovery config validation failed (${loaded.code}).\n`);
+                return 1;
+            }
+            recovery = {
+                configFile: options.recoveryConfig,
+                artifactPath: join(getPackageRoot(), 'dist/hosts/integration/pappra-recovery-extension.mjs'),
+            };
+        }
+        if (options.transitionExtension &&
+            (options.host !== 'pi' ||
+                options.bootstrapConfig !== null ||
+                options.marketplace ||
+                options.mode !== null ||
+                options.apply)) {
+            output.stderr('pappra host bundle: --transition-extension requires a plain Pi bundle and cannot be combined with --bootstrap-config, --marketplace, --mode or --apply.\n');
+            return 2;
+        }
         try {
             const exported = await exportHostPluginBundle({
                 host: options.host,
@@ -213,6 +319,15 @@ export async function runHostCommand(options, output) {
                 outDir: options.out,
                 packageVersion: getPackageInfo().version,
                 marketplace: options.marketplace,
+                ...(bootstrap === undefined ? {} : { bootstrap }),
+                ...(recovery === undefined ? {} : { recovery }),
+                ...(options.transitionExtension
+                    ? {
+                        transition: {
+                            artifactPath: join(getPackageRoot(), 'dist/hosts/integration/pappra-session-transition-extension.mjs'),
+                        },
+                    }
+                    : {}),
             });
             if (options.json) {
                 output.stdout(`${JSON.stringify({ ok: true, command: 'host', action: 'bundle', ...exported })}\n`);