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

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

@@ -0,0 +1,104 @@
+import path from 'node:path';
+import { COLLAB_RECOVERY_SCHEMA, applyRecovery, inspectRecovery, loadRecoveryRequest, planRecovery, } from '../../app/collab-recovery.js';
+export const collaborationRecoveryUsage = 'pappra collab recovery inspect --task-root <abs> [--json]\n' +
+    'pappra collab recovery <reconcile|lock-break> --task-root <abs> --request <abs request.json> [--apply] [--json]\n\n' +
+    'Read-only recovery inspection or explicit recorded recovery. Reconcile resolves\n' +
+    'one uncertainty (and optionally applies an existing state transition) atomically.\n' +
+    'Lock-break archives one task write lock only after an operator stop assertion and\n' +
+    'an exact inspected fingerprint. No native execution is queried or controlled.';
+function invalid(output, options, errors) {
+    if (options.json) {
+        output.stdout(`${JSON.stringify({
+            schema: COLLAB_RECOVERY_SCHEMA,
+            ok: false,
+            status: 'invalid',
+            action: options.action,
+            errors,
+        })}\n`);
+    }
+    else {
+        output.stdout(`Recovery request invalid.\n`);
+        for (const error of errors)
+            output.stdout(`  - ${error}\n`);
+    }
+    return 2;
+}
+function failure(output, options, value, exitCode) {
+    if (options.json) {
+        output.stdout(`${JSON.stringify({
+            schema: COLLAB_RECOVERY_SCHEMA,
+            ok: false,
+            status: exitCode === 2 ? 'invalid' : 'needs_input',
+            action: options.action,
+            code: value.code,
+            message: value.message,
+            nextAction: value.nextAction,
+        })}\n`);
+    }
+    else {
+        output.stdout(`Recovery needs input: ${value.message}\n`);
+        if (value.nextAction)
+            output.stdout(`  ${value.nextAction}\n`);
+    }
+    return exitCode;
+}
+function emitInspect(value, output) {
+    const uncertainty = value.uncertainty;
+    const lock = value.lock;
+    output.stdout(`Recovery ${value.ok === true ? 'ready' : 'needs input'}: ${String(uncertainty.counts.open)} open uncertainty, ${String(uncertainty.counts.resolved)} resolved.\n`);
+    output.stdout(`  lock: ${lock.held ? (lock.holder_process_alive ? 'held (holder alive)' : 'held (holder liveness unconfirmed)') : 'not held'}; transactions: ${String(lock.transaction_count)}; fingerprint: ${lock.fingerprint_status}\n`);
+}
+function emitHuman(value, action, output) {
+    if (value.status === 'planned' && value.applied === false) {
+        output.stdout(action === 'reconcile'
+            ? 'Reconcile plan validates the request and task namespace; nothing was written.\n'
+            : 'Lock-break plan validates the request and task namespace; nothing was archived.\n');
+        return;
+    }
+    if (action === 'reconcile') {
+        output.stdout(value.ok === true
+            ? `Reconcile applied: resolution recorded; state transition ${String(value.result?.state_transition ?? 'none')}.\n`
+            : `Reconcile refused: ${String(value.reason ?? 'unknown')}.\n`);
+    }
+    else if (value.ok === true) {
+        output.stdout(`Lock-break archived ${String(value.archived_lock ?? 'the task lock')}.\n`);
+    }
+    else {
+        output.stdout(`Lock-break refused: ${String(value.reason ?? 'unknown')}.\n`);
+    }
+}
+export async function runCollaborationRecoveryCommand(options, output) {
+    if (options.action === null)
+        return invalid(output, options, ['recovery requires an action.']);
+    if (options.taskRoot === null)
+        return invalid(output, options, ['--task-root is required.']);
+    if (!path.isAbsolute(options.taskRoot))
+        return invalid(output, options, ['--task-root must be absolute.']);
+    if (options.action === 'inspect') {
+        const result = await inspectRecovery(options.taskRoot);
+        if (!result.ok)
+            return failure(output, options, result, 1);
+        if (options.json)
+            output.stdout(`${JSON.stringify(result.value)}\n`);
+        else
+            emitInspect(result.value, output);
+        return result.value.ok === true ? 0 : 1;
+    }
+    if (options.requestFile === null)
+        return invalid(output, options, [`${options.action} requires --request.`]);
+    if (!path.isAbsolute(options.requestFile))
+        return invalid(output, options, ['--request must be absolute.']);
+    const loaded = loadRecoveryRequest(options.requestFile, options.action);
+    if (!loaded.ok)
+        return failure(output, options, loaded, 2);
+    const result = options.apply
+        ? await applyRecovery(options.taskRoot, loaded.value.request)
+        : await planRecovery(options.taskRoot, loaded.value.request);
+    if (!result.ok)
+        return failure(output, options, result, 1);
+    if (options.json)
+        output.stdout(`${JSON.stringify(result.value)}\n`);
+    else
+        emitHuman(result.value, options.action, output);
+    return result.value.ok === true ? 0 : 1;
+}

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

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

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

@@ -0,0 +1,96 @@
+import path from 'node:path';
+import { COLLAB_RESOURCES_SCHEMA, applyResourceRequest, listTaskResources, loadResourceRequest, planResourceRequest, } from '../../app/collab-resources.js';
+export const collaborationResourcesUsage = 'pappra collab resource <list|claim|release> --task-root <abs> [options]\n' +
+    '  list     --task-root <abs> [--json]\n' +
+    '  claim    --task-root <abs> --request <abs request.json> [--apply] [--json]\n' +
+    '  release  --task-root <abs> --request <abs request.json> [--apply] [--json]\n\n' +
+    'Read/plan is non-mutating. --apply invokes the existing cooperative claim or\n' +
+    'release primitive and never fences OS side effects. Exit 0 success,\n' +
+    '1 conflict/uncertainty/core refusal, 2 invalid request/options.';
+function invalid(output, options, errors) {
+    if (options.json) {
+        output.stdout(`${JSON.stringify({
+            schema: COLLAB_RESOURCES_SCHEMA,
+            ok: false,
+            status: 'invalid',
+            action: options.action,
+            errors,
+        })}\n`);
+    }
+    else {
+        output.stdout(`Resource request invalid.\n`);
+        for (const error of errors)
+            output.stdout(`  - ${error}\n`);
+    }
+    return 2;
+}
+function failure(output, options, value, exitCode) {
+    if (options.json) {
+        output.stdout(`${JSON.stringify({
+            schema: COLLAB_RESOURCES_SCHEMA,
+            ok: false,
+            status: exitCode === 2 ? 'invalid' : 'needs_input',
+            action: options.action,
+            code: value.code,
+            message: value.message,
+            nextAction: value.nextAction,
+        })}\n`);
+    }
+    else {
+        output.stdout(`Resource operation needs input: ${value.message}\n`);
+        if (value.nextAction)
+            output.stdout(`  ${value.nextAction}\n`);
+    }
+    return exitCode;
+}
+function emitHuman(value, action, output) {
+    if (action === 'list') {
+        const counts = value.counts;
+        output.stdout(`Domain resources: ${String(counts.tasks)} task(s), ${String(counts.claims)} claim(s), state ${String(value.state)}.\n`);
+        if (value.unreadable_tasks.length)
+            output.stdout(`  unreadable tasks: ${String(value.unreadable_tasks.length)}\n`);
+    }
+    else if (value.applied === false) {
+        output.stdout(`Resource ${action} plan validated; nothing was persisted.\n`);
+    }
+    else {
+        output.stdout(`Resource ${action} ${value.ok === true ? 'applied' : 'refused'}: ${String(value.reason ?? 'completed')}.\n`);
+    }
+}
+export async function runCollaborationResourcesCommand(options, output) {
+    if (options.action === null)
+        return invalid(output, options, [
+            'resource requires list, claim or release.',
+        ]);
+    if (options.taskRoot === null)
+        return invalid(output, options, ['--task-root is required.']);
+    if (!path.isAbsolute(options.taskRoot))
+        return invalid(output, options, ['--task-root must be absolute.']);
+    if (options.action === 'list') {
+        const result = await listTaskResources(options.taskRoot);
+        if (!result.ok)
+            return failure(output, options, result, 1);
+        if (options.json)
+            output.stdout(`${JSON.stringify(result.value)}\n`);
+        else
+            emitHuman(result.value, options.action, output);
+        return result.value.ok === true ? 0 : 1;
+    }
+    if (options.requestFile === null)
+        return invalid(output, options, [`${options.action} requires --request.`]);
+    if (!path.isAbsolute(options.requestFile))
+        return invalid(output, options, ['--request must be absolute.']);
+    const loaded = loadResourceRequest(options.requestFile, options.action);
+    if (!loaded.ok)
+        return failure(output, options, loaded, 2);
+    const result = options.apply
+        ? await applyResourceRequest(options.taskRoot, loaded.value.request)
+        : await planResourceRequest(options.taskRoot, loaded.value.request);
+    if (!result.ok)
+        return failure(output, options, result, 1);
+    if (options.json)
+        output.stdout(`${JSON.stringify(result.value)}\n`);
+    else
+        emitHuman(result.value, options.action, output);
+    return result.value.ok === true ? 0 : 1;
+}

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

@@ -0,0 +1,9 @@
+import type { CliOutput } from '../output.js';
+export declare const collaborationRolePlanUsage: string;
+export declare function runCollaborationRolePlanCommand(options: {
+    readonly action: string;
+    readonly requestFile: string | null;
+    readonly taskRoot: string | null;
+    readonly planFile: string | null;
+    readonly json: boolean;
+}, output: CliOutput): Promise<number>;

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

@@ -0,0 +1,69 @@
+import { readBoundedFile } from '../../app/bounded-file.js';
+import { expandRolePlan, aggregateRolePlan, } from '../../app/collab-role-plan.js';
+import { inspectWorkPlan } from '../../app/collab-work-plan.js';
+import { canonicalJson } from '../../collab/envelope.js';
+export const collaborationRolePlanUsage = 'pappra collab role-plan expand --request <abs role-plan.json> [--json]\n' +
+    'pappra collab role-plan aggregate --request <abs role-plan.json> --task-root <abs> --config <abs expanded-plan.json> [--json]\n\n' +
+    'Read-only writer/reviewer expansion and authoritative task-result aggregation.\n' +
+    'Save the returned plan, then use collab plan/work-run for existing admission and dispatch.\n' +
+    'Roles never grant authority; delivery never implies acceptance.';
+function loadJson(file) {
+    if (file === null)
+        throw new Error('An absolute input file is required.');
+    const loaded = readBoundedFile(file, 512 * 1024);
+    if (!loaded.ok)
+        throw new Error(`Input refused: ${loaded.code}.`);
+    try {
+        return JSON.parse(loaded.text);
+    }
+    catch {
+        throw new Error('Input must be JSON.');
+    }
+}
+export async function runCollaborationRolePlanCommand(options, output) {
+    const emit = (value) => {
+        output.stdout(`${JSON.stringify(value, null, options.json ? undefined : 2)}\n`);
+    };
+    try {
+        if (options.action !== 'expand' && options.action !== 'aggregate')
+            throw new Error('role-plan accepts expand or aggregate.');
+        if (options.action === 'expand' &&
+            (options.taskRoot !== null || options.planFile !== null))
+            throw new Error('expand accepts only --request and --json.');
+        const expanded = expandRolePlan(loadJson(options.requestFile));
+        if (!expanded.ok) {
+            emit(expanded);
+            return 2;
+        }
+        if (options.action === 'expand') {
+            emit(expanded);
+            return 0;
+        }
+        if (options.taskRoot === null || options.planFile === null)
+            throw new Error('aggregate requires --task-root and --config.');
+        if (canonicalJson(loadJson(options.planFile)) !== canonicalJson(expanded.plan))
+            throw new Error('Persisted plan differs from the expanded role request.');
+        const report = await inspectWorkPlan({
+            taskRoot: options.taskRoot,
+            planFile: options.planFile,
+        });
+        const result = aggregateRolePlan(expanded, report.core ?? {
+            ok: false,
+            diagnostics: report.diagnostics.map((entry) => ({
+                ...entry,
+                node_id: null,
+            })),
+        });
+        emit(result);
+        return result.outcome === 'unknown' || result.outcome === 'missing' ? 1 : 0;
+    }
+    catch (error) {
+        emit({
+            ok: false,
+            status: 'invalid',
+            code: 'invalid_role_plan_request',
+            message: error instanceof Error ? error.message : 'Role plan request failed.',
+        });
+        return 2;
+    }
+}

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

@@ -0,0 +1,11 @@
+import { watchRoleOrchestration } from '../../app/collab-role-events.js';
+import type { CliOutput } from '../output.js';
+export declare const collaborationRoleRunUsage: string;
+export declare function runCollaborationRoleRunCommand(options: {
+    readonly requestFile: string | null;
+    readonly apply: boolean;
+    readonly watch?: boolean;
+    readonly json: boolean;
+}, output: CliOutput, deps?: {
+    readonly watch?: typeof watchRoleOrchestration;
+}): Promise<number>;

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

@@ -0,0 +1,128 @@
+import { loadRoleRunRequest, watchRoleOrchestration, } from '../../app/collab-role-events.js';
+import { tickRoleOrchestration } from '../../app/collab-role-orchestration.js';
+import { expandRolePlan } from '../../app/collab-role-plan.js';
+import { inspectWorkPlan } from '../../app/collab-work-plan.js';
+import { readBoundedFile } from '../../app/bounded-file.js';
+import { canonicalJson } from '../../collab/envelope.js';
+import { managedPiRepairDependencies } from '../../app/managed-pi-repair-stop.js';
+export const collaborationRoleRunUsage = 'pappra collab role-run --request <abs role-orchestration.json> [--apply] [--watch] [--json]\n\n' +
+    'Plan reads authoritative role/dependency state without effects. Apply handles one\n' +
+    'bounded event tick, reserves before dispatch and never infers acceptance.\n' +
+    '--watch requires --apply and re-evaluates on relevant task/request/capability events.\n' +
+    'Repeated or ambiguous effects are reconciled; rejected work requires an authorized repair attempt.';
+const PUBLIC_ERRORS = new Set([
+    'role_request_required',
+    'role_request_invalid',
+    'role_request_invalid_json',
+    'role_request_path_not_absolute',
+    'role_request_symlink',
+    'role_request_not_regular',
+    'role_request_too_large',
+    'role_request_unreadable',
+    'role_plan_file_mismatch',
+    'watch_requires_apply',
+    'role_event_request_path_not_absolute',
+    'role_event_task_unavailable',
+    'role_event_task_root_mismatch',
+    'role_event_watch_initialization_failed',
+]);
+function safeErrorCode(error) {
+    if (!(error instanceof Error))
+        return 'role_run_failed';
+    return PUBLIC_ERRORS.has(error.message) ? error.message : 'role_run_failed';
+}
+export async function runCollaborationRoleRunCommand(options, output, deps = {}) {
+    const emit = (value) => output.stdout(`${JSON.stringify(value, null, options.json ? undefined : 2)}\n`);
+    try {
+        if (options.watch && !options.apply)
+            throw new Error('watch_requires_apply');
+        if (!options.requestFile)
+            throw new Error('role_request_required');
+        if (options.watch) {
+            return await runWatch(options.requestFile, emit, deps.watch ?? watchRoleOrchestration);
+        }
+        const request = loadRoleRunRequest(options.requestFile);
+        if (!options.apply) {
+            const expanded = expandRolePlan(request.role_plan);
+            if (!expanded.ok) {
+                emit(expanded);
+                return 2;
+            }
+            const plan = readBoundedFile(request.execution.plan_file, 512 * 1024);
+            if (!plan.ok ||
+                canonicalJson(JSON.parse(plan.text)) !== canonicalJson(expanded.plan))
+                throw new Error('role_plan_file_mismatch');
+            const report = await inspectWorkPlan({
+                taskRoot: request.execution.task_root,
+                planFile: request.execution.plan_file,
+            });
+            emit({
+                schema: 'pappra/collab-role-orchestration-plan/1',
+                status: report.ok ? 'planned' : 'blocked',
+                effect: 'none',
+                inspection: report,
+            });
+            return report.ok ? 0 : 1;
+        }
+        const repair = managedPiRepairDependencies(request);
+        const report = await tickRoleOrchestration(request, repair ? { repair } : {});
+        emit(report);
+        return [
+            'blocked',
+            'reconciliation-required',
+            'repair-required',
+            'repair-exhausted',
+            'budget-exhausted',
+        ].includes(report.status)
+            ? 1
+            : 0;
+    }
+    catch (error) {
+        emit({ ok: false, status: 'invalid', code: safeErrorCode(error) });
+        return 2;
+    }
+}
+async function runWatch(requestFile, emit, watch) {
+    emit({
+        schema: 'pappra/collab-role-orchestration-watch/1',
+        status: 'watching',
+    });
+    let resolveStop = null;
+    let stopped = false;
+    const stop = new Promise((resolve) => {
+        resolveStop = resolve;
+    });
+    const onSignal = (code) => () => {
+        if (stopped)
+            return;
+        stopped = true;
+        resolveStop?.(code);
+    };
+    const onInterrupt = onSignal(130);
+    const onTerminate = onSignal(143);
+    process.once('SIGINT', onInterrupt);
+    process.once('SIGTERM', onTerminate);
+    let watcher = null;
+    try {
+        watcher = await watch(requestFile, (result) => emit(result));
+        const signalCode = await stop;
+        const status = watcher.status();
+        emit({
+            schema: 'pappra/collab-role-orchestration-watch/1',
+            status: 'stopped',
+            result: status.result,
+            error: status.error,
+        });
+        return signalCode;
+    }
+    finally {
+        try {
+            if (watcher)
+                await watcher.close();
+        }
+        finally {
+            process.removeListener('SIGINT', onInterrupt);
+            process.removeListener('SIGTERM', onTerminate);
+        }
+    }
+}

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

@@ -0,0 +1,10 @@
+import { type RolloverAction } from '../../app/collab-rollover.js';
+import type { CliOutput } from '../output.js';
+export declare const collaborationRolloverUsage: string;
+export interface CollaborationRolloverOptions {
+    readonly action: RolloverAction;
+    readonly taskRoot: string | null;
+    readonly requestFile: string | null;
+    readonly json: boolean;
+}
+export declare function runCollaborationRolloverCommand(options: CollaborationRolloverOptions, output: CliOutput): Promise<number>;

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

@@ -0,0 +1,103 @@
+import path from 'node:path';
+import { COLLAB_ROLLOVER_REPORT_SCHEMA, inspectOrPlanRollover, loadRolloverRequest, } from '../../app/collab-rollover.js';
+export const collaborationRolloverUsage = 'pappra collab rollover <inspect|plan> --task-root <abs> --request <abs request.json> [--json]\n\n' +
+    'Read-only rollover inspection and planning against the authoritative task record\n' +
+    'and one exact linked continuity handoff bundle. Nothing is claimed, transferred,\n' +
+    'launched, archived, routed, notified or written, and no native query is made.\n\n' +
+    'The request document is bounded (64 KiB) and separately versioned\n' +
+    '(schema pappra/collaboration-rollover-request/1). It names the absolute task root,\n' +
+    'the exact bundle reference and digest, and either a recorded intent id or a\n' +
+    'proposed intent. --task-root must equal the request task_root.\n\n' +
+    'There is no apply action. A caller-supplied stop observation, exit code or\n' +
+    'producer label is never authenticated native proof, so prepare-transfer stays\n' +
+    'unavailable until an accepted host adapter produces quiescence evidence.\n\n' +
+    'Exit 0 inspected (blocked steps included, plan_complete reports completion),\n' +
+    '1 the exact record or bundle cannot support the inspection, 2 invalid request.';
+function emitFailure(output, options, kind, code, message, nextAction, details) {
+    if (options.json) {
+        output.stdout(`${JSON.stringify({
+            schema: COLLAB_ROLLOVER_REPORT_SCHEMA,
+            action: options.action,
+            ok: false,
+            kind,
+            code,
+            message,
+            next_action: nextAction,
+            task_root: options.taskRoot,
+            request: options.requestFile,
+            details,
+            limits: [
+                'read_only_inspection',
+                'no_apply_or_mutation',
+                'host_stop_proof_unavailable',
+                'native_launch_unavailable',
+                'native_session_archive_unavailable',
+                'routing_removal_pending',
+            ],
+        })}\n`);
+    }
+    else {
+        output.stdout(`Rollover ${options.action} rejected (${code}).\n`);
+        output.stdout(`  ${message}\n`);
+        for (const detail of details)
+            output.stdout(`  - ${detail}\n`);
+        if (nextAction !== null)
+            output.stdout(`  next: ${nextAction}\n`);
+    }
+    return kind === 'invalid' ? 2 : 1;
+}
+function emitHuman(report, output) {
+    const intentLabel = report.intent.intent_id ?? '<unrecorded intent>';
+    output.stdout(`Rollover ${report.action} on task ${report.task_id} (revision ${report.state_revision}, epoch ${String(report.owner_epoch)}): intent ${intentLabel}.\n`);
+    output.stdout(`  record: ${report.intent.found ? 'recorded intent' : 'proposed intent'}, handoff ${report.handoff.state ?? '<none>'}, attempt ${report.attempt?.state ?? '<none>'}\n`);
+    for (const claim of report.claims) {
+        output.stdout(`  claim ${claim.claim_id}: holder ${claim.holder?.agent_id ?? '<none>'}, epoch ${String(claim.resource_epoch)} (expected ${claim.expected_resource_epoch})${claim.released_at === null ? '' : ', released'}\n`);
+    }
+    output.stdout(`  bundle ${report.bundle.ref}: verified, context ${report.bundle.context_integrity}, association ${report.bundle.collaboration.matches_plan ? 'matches' : 'differs'}, execution ${String(report.bundle.execution_allowed)}\n`);
+    for (const step of report.steps) {
+        output.stdout(`  ${step.step}: ${step.status}\n`);
+        for (const blocker of step.blockers)
+            output.stdout(`      blocked by ${blocker.code}: ${blocker.detail}\n`);
+    }
+    if (report.drift.length > 0) {
+        output.stdout('  current-record drift:\n');
+        for (const blocker of report.drift)
+            output.stdout(`      ${blocker.code}: ${blocker.detail}\n`);
+    }
+    output.stdout(`  notify exclusion for the planned identities: ${report.notify_exclusion.effective}\n`);
+    if (report.evidence.requested.length > 0)
+        output.stdout(`  evidence: ${report.evidence.supplied}/${report.evidence.requested.length} correlated envelope(s), ${report.evidence.raw_bytes} raw bytes\n`);
+    for (const entry of report.evidence.unreadable)
+        output.stdout(`      unreadable ${entry.message_id}: ${entry.code}\n`);
+    output.stdout(`  plan complete: ${String(report.plan_complete)} (host stop proof ${report.capabilities.host_stop_proof}, native launch ${report.capabilities.native_launch}, routing removal ${report.capabilities.routing_removal})\n`);
+    output.stdout('  read-only: no intent, claim, handoff, bundle, binding, notification or delivery file was written and nothing was applied.\n');
+}
+export async function runCollaborationRolloverCommand(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.requestFile === null)
+        errors.push('--request is required.');
+    else if (!path.isAbsolute(options.requestFile))
+        errors.push('--request must be an absolute path to the request document.');
+    if (errors.length > 0)
+        return emitFailure(output, options, 'invalid', 'invalid_arguments', 'The rollover request is incomplete.', collaborationRolloverUsage, errors);
+    const loaded = loadRolloverRequest(options.requestFile);
+    if (loaded.ok === false)
+        return emitFailure(output, options, loaded.kind, loaded.code, loaded.message, loaded.nextAction, []);
+    const request = loaded.value;
+    if (options.action !== request.action)
+        return emitFailure(output, options, 'invalid', 'request_action_mismatch', `The command asks for ${options.action} but the request document declares ${request.action}.`, 'Use one action in both the command and the request document.', []);
+    if (path.resolve(request.task_root) !== path.resolve(options.taskRoot))
+        return emitFailure(output, options, 'invalid', 'task_root_mismatch', 'The request task_root is not the --task-root passed on the command line.', 'Use one absolute task root; the cwd is never used to infer it.', []);
+    const report = await inspectOrPlanRollover(request);
+    if (report.ok === false)
+        return emitFailure(output, options, report.kind, report.code, report.message, report.nextAction, []);
+    if (options.json)
+        output.stdout(`${JSON.stringify(report.value)}\n`);
+    else
+        emitHuman(report.value, output);
+    return 0;
+}

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

@@ -0,0 +1,10 @@
+import { type StateAction } from '../../app/collab-state.js';
+import type { CliOutput } from '../output.js';
+export declare const collaborationStateUsage: string;
+export interface CollaborationStateOptions {
+    readonly action: StateAction | null;
+    readonly taskRoot: string | null;
+    readonly ownerEpoch: string | null;
+    readonly json: boolean;
+}
+export declare function runCollaborationStateCommand(options: CollaborationStateOptions, output: CliOutput): Promise<number>;

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

@@ -0,0 +1,96 @@
+import path from 'node:path';
+import { COLLAB_STATE_SCHEMA, checkTaskEpoch, doctorTaskState, showTaskState, } from '../../app/collab-state.js';
+export const collaborationStateUsage = 'pappra collab state <show|doctor|epoch-check> --task-root <abs> [options]\n' +
+    '  show         --task-root <abs> [--json]\n' +
+    '  doctor       --task-root <abs> [--json]\n' +
+    '  epoch-check  --task-root <abs> --owner-epoch <positive integer> [--json]\n\n' +
+    'Read-only task-state projections over the existing record/lock/transaction\n' +
+    'primitives. Nothing is repaired, released, restarted or launched. Exit 0 ready,\n' +
+    '1 needs_input/uncertainty, 2 invalid request/options.';
+function invalid(output, options, errors) {
+    if (options.json) {
+        output.stdout(`${JSON.stringify({
+            schema: COLLAB_STATE_SCHEMA,
+            ok: false,
+            status: 'invalid',
+            action: options.action,
+            errors,
+        })}\n`);
+    }
+    else {
+        output.stdout(`State request invalid.\n`);
+        for (const error of errors)
+            output.stdout(`  - ${error}\n`);
+    }
+    return 2;
+}
+function failure(output, options, value) {
+    if (options.json) {
+        output.stdout(`${JSON.stringify({
+            schema: COLLAB_STATE_SCHEMA,
+            ok: false,
+            status: 'needs_input',
+            action: options.action,
+            code: value.code,
+            message: value.message,
+            nextAction: value.nextAction,
+        })}\n`);
+    }
+    else {
+        output.stdout(`State needs input: ${value.message}\n`);
+        if (value.nextAction)
+            output.stdout(`  ${value.nextAction}\n`);
+    }
+    return 1;
+}
+function emitHuman(value, action, output) {
+    if (action === 'show') {
+        output.stdout(`Task ${String(value.task_id)} revision ${String(value.state_revision)}.\n`);
+        output.stdout(`  attempts: ${String(value.counts.attempts)}; claims: ${String(value.counts.claims)}; messages: ${String(value.messages)}\n`);
+        const lock = value.lock;
+        output.stdout(`  lock: ${lock.held === true ? 'held' : 'not held'}; transactions: ${String(lock.transaction_count)}\n`);
+    }
+    else if (action === 'doctor') {
+        const findings = value.findings;
+        const counts = value.counts;
+        output.stdout(`Doctor ${value.ok === true ? 'ready' : 'needs input'}: ${String(counts.findings)} finding(s), ${String(counts.blocking)} blocking, ${String(counts.uncertain)} uncertain, ${String(counts.active)} active lock observation(s).\n`);
+        for (const finding of findings)
+            output.stdout(`  - ${finding.severity}: ${finding.code}\n`);
+    }
+    else {
+        output.stdout(`Owner epoch ${value.ok === true ? 'matches' : 'does not match'}: expected ${String(value.expected)}, actual ${String(value.actual)}.\n`);
+    }
+}
+export async function runCollaborationStateCommand(options, output) {
+    if (options.action === null)
+        return invalid(output, options, [
+            'state requires show, doctor or epoch-check.',
+        ]);
+    if (options.taskRoot === null)
+        return invalid(output, options, ['--task-root is required.']);
+    if (!path.isAbsolute(options.taskRoot))
+        return invalid(output, options, ['--task-root must be absolute.']);
+    let ownerEpoch = null;
+    if (options.action === 'epoch-check') {
+        if (options.ownerEpoch === null)
+            return invalid(output, options, ['epoch-check requires --owner-epoch.']);
+        const parsed = Number(options.ownerEpoch.trim());
+        if (!Number.isSafeInteger(parsed) || parsed <= 0)
+            return invalid(output, options, [
+                '--owner-epoch must be a positive integer.',
+            ]);
+        ownerEpoch = parsed;
+    }
+    const result = options.action === 'show'
+        ? await showTaskState(options.taskRoot)
+        : options.action === 'doctor'
+            ? await doctorTaskState(options.taskRoot)
+            : await checkTaskEpoch(options.taskRoot, ownerEpoch);
+    if (!result.ok)
+        return failure(output, options, result);
+    if (options.json)
+        output.stdout(`${JSON.stringify(result.value)}\n`);
+    else
+        emitHuman(result.value, options.action, output);
+    return result.value.ok === true ? 0 : 1;
+}

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

@@ -0,0 +1,10 @@
+import { type SessionTransitionAction, type SessionTransitionDependencies } from '../../app/collab-session-transition.js';
+import type { CliOutput } from '../output.js';
+export declare const collaborationTransitionUsage: string;
+export interface CollaborationTransitionOptions {
+    readonly action: SessionTransitionAction | null;
+    readonly taskRoot: string | null;
+    readonly requestFile: string | null;
+    readonly json: boolean;
+}
+export declare function runCollaborationTransitionCommand(options: CollaborationTransitionOptions, output: CliOutput, dependencies?: SessionTransitionDependencies): Promise<number>;