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

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

@@ -0,0 +1,8 @@
+import type { CliOutput } from '../output.js';
+export declare const collaborationPlanUsage: string;
+export interface CollaborationPlanOptions {
+    readonly taskRoot: string | null;
+    readonly planFile: string | null;
+    readonly json: boolean;
+}
+export declare function runCollaborationPlanCommand(options: CollaborationPlanOptions, output: CliOutput): Promise<number>;

package/dist/cli/commands/collaboration-plan.js

@@ -0,0 +1,108 @@
+import path from 'node:path';
+import { COLLAB_WORK_PLAN_REPORT_SCHEMA, inspectWorkPlan, } from '../../app/collab-work-plan.js';
+export const collaborationPlanUsage = 'pappra collab plan --task-root <abs> --config <abs plan.json> [--json]\n\n' +
+    'Read-only role and dependency evaluation of one persisted work-plan document\n' +
+    'against the authoritative task record. Nothing is claimed, dispatched, launched,\n' +
+    'refreshed or written, and no prompt, network call or model call is made.\n\n' +
+    'Plan nodes correlate to the existing task protocol by\n' +
+    'node.assignment_id == attempt.subtask_id; there is no second assignment registry.\n' +
+    'A ready node is not authorization to run it.\n\n' +
+    'Exit 0 evaluated snapshot (normal waiting and blocked nodes included),\n' +
+    '1 incomplete or unavailable authoritative evidence, 2 invalid request/plan.';
+function invalid(output, options, errors) {
+    if (options.json) {
+        output.stdout(`${JSON.stringify({
+            schema: COLLAB_WORK_PLAN_REPORT_SCHEMA,
+            ok: false,
+            status: 'invalid',
+            task_root: options.taskRoot,
+            task_id: null,
+            plan: {
+                ref: options.planFile,
+                digest: null,
+                plan_id: null,
+                owner_epoch: null,
+                node_count: null,
+            },
+            stale: false,
+            summary: null,
+            nodes: [],
+            core: null,
+            evidence: {
+                registered_decisions: 0,
+                supplied: 0,
+                envelope_bytes: 0,
+                unreadable: [],
+                truncated: false,
+            },
+            diagnostics: errors.map((error) => ({
+                code: 'invalid_arguments',
+                detail: error,
+                next_action: collaborationPlanUsage,
+            })),
+            identity_mapping: 'plan.nodes[].assignment_id corresponds to the existing task subtask identity (record.attempts[].subtask_id); no separate assignment registry exists.',
+            limits: ['persisted_snapshot_only', 'not_an_authorization'],
+        })}\n`);
+    }
+    else {
+        output.stdout('Plan request invalid.\n');
+        for (const error of errors)
+            output.stdout(`  - ${error}\n`);
+        output.stdout(`\n${collaborationPlanUsage}\n`);
+    }
+    return 2;
+}
+function emitHuman(report, output) {
+    const planLabel = report.plan.plan_id ?? '<unparsed plan>';
+    const taskLabel = report.task_id ?? '<unknown task>';
+    output.stdout(`Plan ${planLabel} on task ${taskLabel}: ${report.status}.\n`);
+    if (report.status === 'invalid') {
+        for (const entry of report.diagnostics)
+            output.stdout(`  invalid: ${entry.code}: ${entry.detail}\n`);
+        return;
+    }
+    if (report.status === 'incomplete') {
+        for (const entry of report.diagnostics)
+            output.stdout(`  incomplete: ${entry.code}: ${entry.detail}\n`);
+    }
+    if (report.stale) {
+        output.stdout('  note: the plan owner epoch is not the current epoch; every node is stale until it is rebuilt.\n');
+    }
+    const summary = report.summary;
+    if (summary !== null) {
+        output.stdout(`  ready ${summary.ready}, running ${summary.running}, awaiting acceptance ${summary.awaiting_acceptance}, accepted ${summary.accepted}, blocked ${summary.blocked}\n`);
+    }
+    for (const node of report.nodes) {
+        output.stdout(`  ${node.role} ${node.node_id} (assignment ${node.assignment_id}#${node.attempt}): ${node.status}\n`);
+        for (const blocker of node.blockers)
+            output.stdout(`      blocked by ${blocker.code}: ${blocker.detail}\n`);
+        if (node.next_action !== null)
+            output.stdout(`      next: ${node.next_action}\n`);
+    }
+    output.stdout(`  evidence: ${report.evidence.supplied}/${report.evidence.registered_decisions} relevant decision envelope(s) read from ${report.evidence.relevant_reports} planned report(s), ${report.evidence.raw_bytes} raw bytes\n`);
+    output.stdout('  read-only: this evaluation is a persisted snapshot and grants no authority to run anything.\n');
+}
+export async function runCollaborationPlanCommand(options, output) {
+    const errors = [];
+    if (options.taskRoot === null)
+        errors.push('--task-root is required.');
+    else if (!path.isAbsolute(options.taskRoot))
+        errors.push('--task-root must be absolute.');
+    if (options.planFile === null)
+        errors.push('--config is required.');
+    else if (!path.isAbsolute(options.planFile))
+        errors.push('--config must be an absolute path to the plan document.');
+    if (errors.length > 0)
+        return invalid(output, options, errors);
+    const report = await inspectWorkPlan({
+        taskRoot: options.taskRoot,
+        planFile: options.planFile,
+    });
+    if (options.json)
+        output.stdout(`${JSON.stringify(report)}\n`);
+    else
+        emitHuman(report, output);
+    if (report.status === 'evaluated')
+        return 0;
+    return report.status === 'invalid' ? 2 : 1;
+}

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

@@ -0,0 +1,10 @@
+import type { CliOutput } from '../output.js';
+export declare const collaborationPreflightUsage: string;
+export interface CollaborationPreflightOptions {
+    readonly cwd: string;
+    readonly assignmentFile: string | null;
+    readonly capabilitiesFile: string | null;
+    readonly maxAgeMinutes: string | null;
+    readonly json: boolean;
+}
+export declare function runCollaborationPreflightCommand(options: CollaborationPreflightOptions, output: CliOutput): number;

package/dist/cli/commands/collaboration-preflight.js

@@ -0,0 +1,167 @@
+import { runCollaborationPreflight, } from '../../app/collab-preflight.js';
+export const collaborationPreflightUsage = 'pappra collab preflight --assignment <abs assignment.json> --capabilities <abs card.json> [--max-age-minutes <n>] [--json]\n\n' +
+    'Read-only readiness check over the existing collaboration preflight. It reads the\n' +
+    'two files and verifies pinned inputs/evidence; it never launches, claims, mutates\n' +
+    'a task record or refreshes evidence. Exit 0 ready, 1 needs_input, 2 invalid.\n' +
+    'Needs-input output groups recovery guidance for known blockers; JSON output is unchanged.';
+function usageFailure(output, options, code, message) {
+    if (options.json) {
+        output.stdout(`${JSON.stringify({
+            schema: 'pappra/collaboration-preflight/1',
+            ok: false,
+            status: 'invalid',
+            errors: [message],
+            blockers: [],
+            warnings: [],
+            limits: [],
+            code,
+        })}\n`);
+    }
+    else {
+        output.stderr(`pappra collab preflight: ${message}\n`);
+    }
+    return 2;
+}
+function describeChecks(checks) {
+    return checks.map((check) => `  - ${check.code}${check.capability === undefined ? '' : ` (${check.capability})`}`);
+}
+const FRESHNESS_RECOVERY = 'Obtain fresh runtime evidence from the current receiving session and rerun preflight. Never retimestamp older evidence, and never revert a user-selected model or provider to recreate an earlier observation.';
+const IDENTITY_RECOVERY = 'Supply evidence for the exact assignee identity, session, cwd and configuration. A model or provider difference alone is not an identity difference, and identity fields are not relabeled to match.';
+const CAPABILITY_RECOVERY = 'Required capability readiness is not confirmed by this card: inspect the current runtime exposure and obtain actual current evidence for the required tool or skill, restoring or enabling it when it is in fact absent. Changing the requirement is an explicit scope decision for the coordinator, not a worker recovery step. Earlier successful tool use does not prove the current runtime still exposes it.';
+/** Exact identity blockers emitted by the preflight core; unknown future codes get no remedy. */
+const IDENTITY_BLOCKERS = new Set([
+    'assignee_agent_id_mismatch',
+    'assignee_session_id_mismatch',
+    'assignee_harness_mismatch',
+    'assignee_surface_mismatch',
+    'assignee_configuration_id_mismatch',
+    'assignee_cwd_mismatch',
+]);
+/** Recovery guidance for concrete, known blockers. Unknown codes keep their code only. */
+function recoveryFor(code) {
+    if (code === 'capabilities_stale')
+        return { group: 'freshness', action: FRESHNESS_RECOVERY };
+    if (code === 'capabilities_from_future')
+        return {
+            group: 'clock',
+            action: 'The evidence clock is ahead of this host clock: compare host and native timestamps and correct the clock or the evidence source. Do not edit timestamps to make evidence pass.',
+        };
+    if (code === 'runtime_capabilities_unconfirmed')
+        return {
+            group: 'evidence-level',
+            action: 'Derive a runtime card from actual native evidence for this session (pappra collab capabilities derive); a declared template is not runtime proof.',
+        };
+    if (code === 'required_capability_omitted_by_runner')
+        return { group: 'capabilities', action: CAPABILITY_RECOVERY };
+    if (code === 'native_evidence_changed' ||
+        code === 'native_evidence_unavailable')
+        return {
+            group: 'evidence-files',
+            action: 'The referenced native evidence changed or is unavailable: re-derive from the current native file instead of editing digests.',
+        };
+    if (code === 'input_changed' || code === 'input_unavailable')
+        return {
+            group: 'pinned-input',
+            action: 'A pinned input changed or is missing: obtain the current pinned input and update the assignment revision deliberately rather than rewriting a digest.',
+        };
+    if (code === 'tools_unavailable' || code === 'skills_unavailable')
+        return { group: 'capabilities', action: CAPABILITY_RECOVERY };
+    if (code === 'tools_evidence_unavailable' ||
+        code === 'skills_evidence_unavailable')
+        return {
+            group: 'capability-evidence',
+            action: 'A claimed capability has no usable evidence: re-derive the card so each capability references existing evidence.',
+        };
+    if (code === 'skill_version_mismatch' ||
+        code === 'skill_files_changed' ||
+        code === 'skill_files_unavailable')
+        return {
+            group: 'skill-bundle',
+            action: 'The required skill bundle differs from the pinned fingerprint or is unreadable: restore the pinned bundle or update the requirement deliberately.',
+        };
+    if (code === 'assignee_cwd_unavailable')
+        return {
+            group: 'identity',
+            action: 'The assigned cwd is unreadable from here: run readiness from a process that can read it. cwd is part of the identity.',
+        };
+    if (IDENTITY_BLOCKERS.has(code))
+        return { group: 'identity', action: IDENTITY_RECOVERY };
+    return null;
+}
+function recoveryLines(checks) {
+    const groups = new Map();
+    for (const check of checks) {
+        const guidance = recoveryFor(check.code);
+        if (guidance === null)
+            continue;
+        const existing = groups.get(guidance.group);
+        if (existing === undefined) {
+            groups.set(guidance.group, {
+                action: guidance.action,
+                codes: new Set([check.code]),
+            });
+            continue;
+        }
+        existing.codes.add(check.code);
+    }
+    return [...groups.entries()].map(([group, entry]) => `  ${group}: ${entry.action} (${[...entry.codes].join(', ')})`);
+}
+function emitHuman(report, output) {
+    if (report.status === 'ready') {
+        output.stdout(`Preflight ready${report.checked_at === undefined ? '' : ` at ${report.checked_at}`}.\n`);
+    }
+    else if (report.status === 'needs_input') {
+        output.stdout(`Preflight needs input: ${report.blockers.length} blocker(s).\n`);
+        for (const line of describeChecks(report.blockers))
+            output.stdout(`${line}\n`);
+        const recovery = recoveryLines(report.blockers);
+        if (recovery.length > 0) {
+            output.stdout('Recovery:\n');
+            for (const line of recovery)
+                output.stdout(`${line}\n`);
+        }
+    }
+    else {
+        output.stdout(`Preflight invalid: ${report.errors[0] ?? 'invalid input'}.\n`);
+        for (const error of report.errors.slice(1))
+            output.stdout(`  - ${error}\n`);
+    }
+    if (report.warnings.length > 0) {
+        output.stdout(`Warnings: ${report.warnings.length}.\n`);
+        for (const line of describeChecks(report.warnings))
+            output.stdout(`${line}\n`);
+    }
+    if (report.limits.length > 0) {
+        output.stdout(`Limits: ${report.limits.join(', ')}.\n`);
+    }
+}
+export function runCollaborationPreflightCommand(options, output) {
+    if (options.assignmentFile === null) {
+        return usageFailure(output, options, 'assignment_required', 'preflight requires --assignment <abs assignment.json>.');
+    }
+    if (options.capabilitiesFile === null) {
+        return usageFailure(output, options, 'capabilities_required', 'preflight requires --capabilities <abs card.json>.');
+    }
+    let maxAgeMinutes;
+    if (options.maxAgeMinutes !== null) {
+        const parsed = Number(options.maxAgeMinutes.trim());
+        if (!Number.isFinite(parsed) || parsed <= 0) {
+            return usageFailure(output, options, 'max_age_invalid', '--max-age-minutes must be a positive finite number.');
+        }
+        maxAgeMinutes = parsed;
+    }
+    const report = runCollaborationPreflight({
+        assignmentFile: options.assignmentFile,
+        capabilitiesFile: options.capabilitiesFile,
+        ...(maxAgeMinutes === undefined ? {} : { maxAgeMinutes }),
+    });
+    if (options.json) {
+        output.stdout(`${JSON.stringify(report)}\n`);
+    }
+    else {
+        emitHuman(report, output);
+    }
+    if (report.status === 'ready')
+        return 0;
+    return report.status === 'needs_input' ? 1 : 2;
+}

package/dist/cli/commands/collaboration-recovery-run.d.ts

@@ -0,0 +1,46 @@
+import { type RecoveryController } from '../../app/collab-recovery-executor.js';
+import type { RecoveryPolicy } from '../../app/collab-recovery-projection.js';
+import type { Identity } from '../../collab/types.js';
+import type { CliOutput } from '../output.js';
+export declare const COLLAB_RECOVERY_RUN_SCHEMA: 'pappra/collab-recovery-run/1';
+export declare const collaborationRecoveryRunUsage: string;
+/** Typed options for the handler; a parser rejects duplicate and unknown flags at the boundary. */
+export interface CollaborationRecoveryRunOptions {
+    readonly requestFile: string | null;
+    readonly apply: boolean;
+    readonly json: boolean;
+}
+export interface CollaborationRecoveryRunParse {
+    readonly options: CollaborationRecoveryRunOptions;
+    readonly errors: readonly string[];
+}
+/** The request file supplied to the handler; mode is derived from the --apply flag, not the file. */
+export interface RecoveryRunRequestFile {
+    readonly schema: 'pappra/collab-recovery-run-request/1';
+    readonly taskRoot: string;
+    readonly planFile: string;
+    readonly self: Identity;
+    readonly policy: RecoveryPolicy;
+    readonly expected?: {
+        readonly session_id: string;
+        readonly cwd?: string | null;
+        readonly binding_ref?: string | null;
+        readonly binding_digest?: string | null;
+        readonly pane_id?: string | null;
+        readonly harness?: string | null;
+    } | null;
+    readonly requestId: string;
+    readonly target?: {
+        readonly agent: string;
+    } | null;
+}
+/** Parse argv for the recovery-run command, rejecting duplicate and unknown options. */
+export declare function parseCollaborationRecoveryRunArgs(argv: readonly string[]): CollaborationRecoveryRunParse;
+/**
+ * Durable recovery execution handler, exported for the integration router. It builds a Herdr-backed
+ * controller only for an `--apply` request that names a target agent; a dry plan needs no controller
+ * and issues no effect.
+ */
+export declare function runCollaborationRecoveryRunCommand(options: CollaborationRecoveryRunOptions, output: CliOutput, deps?: {
+    readonly controller?: RecoveryController;
+}): Promise<number>;

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

@@ -0,0 +1,224 @@
+import path from 'node:path';
+import { readBoundedFile } from '../../app/bounded-file.js';
+import { createHerdrRecoveryController, executeRecovery, } from '../../app/collab-recovery-executor.js';
+export const COLLAB_RECOVERY_RUN_SCHEMA = 'pappra/collab-recovery-run/1';
+const MAX_REQUEST_BYTES = 64 * 1024;
+export const collaborationRecoveryRunUsage = 'pappra collab recovery-run --request <abs recovery-run.json> [--apply] [--json]\n\n' +
+    'Durable recovery execution for a single task. Without --apply this is a strict dry\n' +
+    'plan: it reads the current task and recommendation and writes nothing. With --apply,\n' +
+    'the request must pin the exact session, cwd, harness, pane and bounded task-local\n' +
+    'binding path/digest for the admitted current task participant; no identity or\n' +
+    'participant fallback is accepted. The live target and current authority are rechecked\n' +
+    'before prompting. It never spawns a session, overrides a model, installs anything or\n' +
+    'auto-approves.';
+/** Parse argv for the recovery-run command, rejecting duplicate and unknown options. */
+export function parseCollaborationRecoveryRunArgs(argv) {
+    const errors = [];
+    let requestFile = null;
+    let apply = false;
+    let json = false;
+    let sawApply = false;
+    let sawJson = false;
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === '--request') {
+            if (requestFile !== null)
+                errors.push('--request may be given only once.');
+            const value = argv[i + 1];
+            if (value === undefined || value.startsWith('--'))
+                errors.push('--request requires a value.');
+            else {
+                requestFile = value;
+                i += 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 isIdentity(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        typeof value.agent_id === 'string' &&
+        typeof value.session_id === 'string' &&
+        (typeof value.harness === 'string' ||
+            value.harness === null));
+}
+function isPinnedExpected(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return false;
+    const expected = value;
+    const keys = Object.keys(expected).sort();
+    return (keys.join('|') ===
+        'binding_digest|binding_ref|cwd|harness|pane_id|session_id' &&
+        typeof expected.session_id === 'string' &&
+        expected.session_id.length > 0 &&
+        typeof expected.cwd === 'string' &&
+        path.isAbsolute(expected.cwd) &&
+        typeof expected.binding_ref === 'string' &&
+        path.isAbsolute(expected.binding_ref) &&
+        typeof expected.binding_digest === 'string' &&
+        /^sha256:[0-9a-f]{64}$/.test(expected.binding_digest) &&
+        typeof expected.pane_id === 'string' &&
+        /^[A-Za-z0-9]+:p[A-Za-z0-9]+$/.test(expected.pane_id) &&
+        typeof expected.harness === 'string' &&
+        expected.harness.length > 0);
+}
+function loadRequestFile(file) {
+    const read = readBoundedFile(file, MAX_REQUEST_BYTES);
+    if (!read.ok)
+        return { ok: false, error: `request file unreadable (${read.code}).` };
+    let parsed;
+    try {
+        parsed = JSON.parse(read.text);
+    }
+    catch {
+        return { ok: false, error: 'request file is not valid JSON.' };
+    }
+    if (typeof parsed !== 'object' || parsed === null)
+        return { ok: false, error: 'request must be an object.' };
+    const raw = parsed;
+    if (raw.schema !== 'pappra/collab-recovery-run-request/1')
+        return { ok: false, error: 'unsupported request schema.' };
+    if (typeof raw.taskRoot !== 'string' || !path.isAbsolute(raw.taskRoot))
+        return { ok: false, error: 'taskRoot must be an absolute path.' };
+    if (typeof raw.planFile !== 'string' || !path.isAbsolute(raw.planFile))
+        return { ok: false, error: 'planFile must be an absolute path.' };
+    if (!isIdentity(raw.self))
+        return { ok: false, error: 'self must be a valid identity.' };
+    const policy = raw.policy;
+    if (typeof policy !== 'object' ||
+        policy === null ||
+        (policy.role !== 'writer' &&
+            policy.role !== 'coordinator' &&
+            policy.role !== 'reviewer'))
+        return {
+            ok: false,
+            error: 'policy.role must be writer, coordinator or reviewer.',
+        };
+    if (typeof raw.requestId !== 'string' || raw.requestId.length === 0)
+        return { ok: false, error: 'requestId must be a non-empty string.' };
+    if (raw.expected !== undefined &&
+        raw.expected !== null &&
+        !isPinnedExpected(raw.expected))
+        return {
+            ok: false,
+            error: 'expected must pin session, cwd, harness, pane, binding_ref and binding_digest exactly.',
+        };
+    if (raw.target !== undefined &&
+        raw.target !== null &&
+        (typeof raw.target !== 'object' ||
+            Array.isArray(raw.target) ||
+            typeof raw.target.agent !== 'string' ||
+            !raw.target.agent))
+        return {
+            ok: false,
+            error: 'target.agent must be a non-empty Herdr agent name.',
+        };
+    return { ok: true, value: raw };
+}
+function invalid(output, options, errors) {
+    if (options.json)
+        output.stdout(`${JSON.stringify({ schema: COLLAB_RECOVERY_RUN_SCHEMA, ok: false, status: 'invalid', errors })}\n`);
+    else {
+        output.stdout('Recovery run request invalid.\n');
+        for (const error of errors)
+            output.stdout(`  - ${error}\n`);
+    }
+    return 2;
+}
+/**
+ * Durable recovery execution handler, exported for the integration router. It builds a Herdr-backed
+ * controller only for an `--apply` request that names a target agent; a dry plan needs no controller
+ * and issues no effect.
+ */
+export async function runCollaborationRecoveryRunCommand(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 loaded = loadRequestFile(options.requestFile);
+    if (!loaded.ok)
+        return invalid(output, options, [loaded.error]);
+    const request = loaded.value;
+    const mode = options.apply ? 'apply' : 'plan';
+    if (mode === 'apply' &&
+        (!isPinnedExpected(request.expected) ||
+            typeof request.target?.agent !== 'string' ||
+            request.target.agent.length === 0))
+        return invalid(output, options, [
+            'apply requires a complete expected session/cwd/harness/pane plus a task-local binding_ref and binding_digest, and request.target.agent.',
+        ]);
+    let controller;
+    if (deps.controller)
+        controller = deps.controller;
+    else if (mode === 'apply') {
+        if (!request.target || typeof request.target.agent !== 'string')
+            return invalid(output, options, [
+                'apply requires request.target.agent for the continuation wake.',
+            ]);
+        controller = createHerdrRecoveryController({ env: process.env }, { agent: request.target.agent });
+    }
+    else {
+        controller = {
+            id: 'recovery-plan-noop',
+            perform: async () => ({
+                disposition: 'unknown',
+                detail: 'plan mode issues no effect',
+                observation: 'none',
+            }),
+        };
+    }
+    const executorRequest = {
+        taskRoot: request.taskRoot,
+        planFile: request.planFile,
+        self: request.self,
+        policy: request.policy,
+        requestId: request.requestId,
+        mode,
+        ...(isPinnedExpected(request.expected)
+            ? {
+                expectedSession: {
+                    session_id: request.expected.session_id,
+                    cwd: request.expected.cwd,
+                    binding_digest: request.expected.binding_digest,
+                    binding_ref: request.expected.binding_ref,
+                    target_agent: request.target?.agent ?? null,
+                    pane_id: request.expected.pane_id,
+                    harness: request.expected.harness,
+                },
+            }
+            : {}),
+    };
+    const result = await executeRecovery(executorRequest, { controller });
+    if (options.json) {
+        output.stdout(`${JSON.stringify({ schema: COLLAB_RECOVERY_RUN_SCHEMA, ok: result.ok, executor: result })}\n`);
+    }
+    else {
+        output.stdout(`Recovery ${mode}: ${result.status}${result.action ? ` (${result.action.kind} ${result.action.subtask_id ?? '-'})` : ''}.\n`);
+        for (const note of result.notes)
+            output.stdout(`  - ${note}\n`);
+        if (result.reservation)
+            output.stdout(`  reservation: ${result.reservation.created ? 'created' : 'existing'} ${result.reservation.key.slice(0, 12)} outcome=${result.reservation.outcome ?? 'none'}\n`);
+    }
+    // Exit success for a clean plan or a positively issued/deferred apply; block otherwise.
+    const good = result.status === 'planned' ||
+        result.status === 'applied' ||
+        result.status === 'deferred' ||
+        result.status === 'noop';
+    return good ? 0 : 1;
+}

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

@@ -0,0 +1,11 @@
+import { type RecoveryAction } from '../../app/collab-recovery.js';
+import type { CliOutput } from '../output.js';
+export declare const collaborationRecoveryUsage: string;
+export interface CollaborationRecoveryOptions {
+    readonly action: RecoveryAction | null;
+    readonly taskRoot: string | null;
+    readonly requestFile: string | null;
+    readonly apply: boolean;
+    readonly json: boolean;
+}
+export declare function runCollaborationRecoveryCommand(options: CollaborationRecoveryOptions, output: CliOutput): Promise<number>;