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

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>;

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>;