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

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

@@ -0,0 +1,84 @@
+import path from 'node:path';
+import { applyVisibleBootstrap, loadVisibleBootstrapRequest, planVisibleBootstrap, } from '../../app/collab-bootstrap.js';
+export const collaborationBootstrapUsage = 'pappra collab bootstrap <plan|apply> --task-root <abs> --request <abs request.json> [--json]\n\n' +
+    'Plan is read-only. Apply performs one durable, visible Pi sibling launch or an\n' +
+    'explicitly verified task-bound reuse. Readiness is not authorization, and a\n' +
+    'submitted message is not receiver acceptance. Unknown outcomes are reconciled,\n' +
+    'never retried automatically.';
+function emitHuman(report, output) {
+    output.stdout(`Bootstrap ${report.action}: ${report.status}${report.code === null ? '' : ` (${report.code})`}.\n`);
+    if (report.message !== null)
+        output.stdout(`  ${report.message}\n`);
+    if (report.request_id !== null)
+        output.stdout(`  request: ${report.request_id}\n`);
+    if (report.task_id !== null)
+        output.stdout(`  task: ${report.task_id}\n`);
+    if (report.target !== null && typeof report.target['choice'] === 'string')
+        output.stdout(`  target: ${report.target['choice']}${typeof report.target['pane_id'] === 'string' ? ` ${report.target['pane_id']}` : ''}\n`);
+    if (report.next_action !== null)
+        output.stdout(`  next: ${report.next_action}\n`);
+    if (report.effects.length > 0) {
+        output.stdout('  effects:\n');
+        for (const effect of report.effects)
+            output.stdout(`    ${effect.step}: ${effect.status}${effect.detail === null ? '' : ` — ${effect.detail}`}\n`);
+    }
+    if (report.limits.length > 0)
+        output.stdout(`  limits: ${report.limits.join(', ')}\n`);
+}
+function exitCode(report) {
+    if (report.status === 'planned' ||
+        report.status === 'applied' ||
+        report.status === 'already_recorded')
+        return 0;
+    if (report.status === 'invalid')
+        return 2;
+    return 1;
+}
+export async function runCollaborationBootstrapCommand(options, output, dependencies = {}) {
+    if (options.action === null) {
+        output.stderr(`pappra collab bootstrap requires plan or apply.\n${collaborationBootstrapUsage}\n`);
+        return 2;
+    }
+    if (options.taskRoot === null || options.requestFile === null) {
+        const message = 'collab bootstrap requires --task-root <absolute> and --request <absolute request.json>.';
+        if (options.json)
+            output.stdout(`${JSON.stringify({ ok: false, status: 'invalid', code: 'required_option_missing', message })}\n`);
+        else
+            output.stderr(`${message}\n${collaborationBootstrapUsage}\n`);
+        return 2;
+    }
+    if (!path.isAbsolute(options.taskRoot) ||
+        !path.isAbsolute(options.requestFile)) {
+        const message = '--task-root and --request must be absolute paths.';
+        if (options.json)
+            output.stdout(`${JSON.stringify({ ok: false, status: 'invalid', code: 'absolute_path_required', message })}\n`);
+        else
+            output.stderr(`${message}\n`);
+        return 2;
+    }
+    const loaded = loadVisibleBootstrapRequest(options.requestFile);
+    if (!loaded.ok) {
+        if (options.json)
+            output.stdout(`${JSON.stringify({ ok: false, status: 'invalid', code: loaded.code, message: loaded.message })}\n`);
+        else
+            output.stderr(`${loaded.code}: ${loaded.message}\n`);
+        return 2;
+    }
+    if (path.resolve(options.taskRoot) !==
+        path.resolve(loaded.value.request.task_root)) {
+        const message = '--task-root does not match request.task_root.';
+        if (options.json)
+            output.stdout(`${JSON.stringify({ ok: false, status: 'invalid', code: 'task_root_mismatch', message })}\n`);
+        else
+            output.stderr(`${message}\n`);
+        return 2;
+    }
+    const report = options.action === 'plan'
+        ? await planVisibleBootstrap(loaded.value, dependencies)
+        : await applyVisibleBootstrap(loaded.value, dependencies);
+    if (options.json)
+        output.stdout(`${JSON.stringify(report)}\n`);
+    else
+        emitHuman(report, output);
+    return exitCode(report);
+}

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

@@ -0,0 +1,13 @@
+import type { CliOutput } from '../output.js';
+export declare const collaborationCapabilitiesUsage: string;
+export interface CollaborationCapabilitiesOptions {
+    readonly harness: string | null;
+    readonly assignmentFile: string | null;
+    readonly templateFile: string | null;
+    readonly executionFile: string | null;
+    readonly sessionFile: string | null;
+    readonly eventsFile: string | null;
+    readonly json: boolean;
+    readonly live?: boolean;
+}
+export declare function runCollaborationCapabilitiesCommand(options: CollaborationCapabilitiesOptions, output: CliOutput): number;

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

@@ -0,0 +1,127 @@
+import path from 'node:path';
+import { CAPABILITIES_SCHEMA, CAPABILITY_LIMITS, deriveCapabilityCard, } from '../../app/capability-evidence/index.js';
+export const collaborationCapabilitiesUsage = 'pappra collab capabilities derive --harness <pi|codex|claude> --assignment <abs assignment.json> --template <abs card.declared.json> [--execution <abs execution.json> | --live] [--session <abs pi-session.jsonl> | --events <abs events.jsonl>] [--json]\n\n' +
+    'Read-only native capability evidence: Pi requires --session, Codex and Claude\n' +
+    'require --events. Pi --live derives a settled saved-session snapshot without\n' +
+    'an execution receipt; it does not prove live ownership, queue or approvals.\n' +
+    'A derived card is a claim derived from the supplied evidence;\n' +
+    'nothing is written, launched, authenticated or dispatched. Exit 0 derived,\n' +
+    '1 needs_input, 2 invalid.';
+function invalid(harness, errors) {
+    return {
+        schema: CAPABILITIES_SCHEMA,
+        ok: false,
+        status: 'invalid',
+        harness,
+        errors,
+        limits: CAPABILITY_LIMITS,
+    };
+}
+function emitInvalid(output, options, result) {
+    if (options.json)
+        output.stdout(`${JSON.stringify(result)}\n`);
+    else {
+        output.stdout(`Capabilities invalid.\n`);
+        for (const error of result.errors ?? [])
+            output.stdout(`  - ${error}\n`);
+    }
+    return 2;
+}
+function emitHuman(result, output) {
+    if (result.status === 'derived') {
+        const card = result.card;
+        const tools = card.tools.map((tool) => `${tool.id}:${tool.state}`);
+        const skills = card.skills.map((skill) => `${skill.id}:${skill.state}`);
+        output.stdout(`Capabilities derived (${result.harness}) at ${card.observed_at}.\n`);
+        output.stdout(`  tools: ${tools.length ? tools.join(', ') : 'none'}\n`);
+        output.stdout(`  skills: ${skills.length ? skills.join(', ') : 'none'}\n`);
+        output.stdout(`  evidence: ${String(card.evidence_records?.length ?? 0)} record(s)\n`);
+        if (result.limitations?.length) {
+            output.stdout(`  limitations: ${result.limitations.join(', ')}\n`);
+        }
+    }
+    else if (result.status === 'needs_input') {
+        output.stdout(`Capabilities need input: ${(result.blockers ?? []).join(', ') || 'none'}.\n`);
+    }
+    else {
+        output.stdout(`Capabilities invalid.\n`);
+        for (const error of result.errors ?? [])
+            output.stdout(`  - ${error}\n`);
+        for (const blocker of result.blockers ?? [])
+            output.stdout(`  - ${blocker}\n`);
+    }
+    output.stdout(`  limits: ${result.limits.join(', ')}\n`);
+}
+export function runCollaborationCapabilitiesCommand(options, output) {
+    const harness = options.harness === 'pi' ||
+        options.harness === 'codex' ||
+        options.harness === 'claude'
+        ? options.harness
+        : null;
+    if (harness === null) {
+        return emitInvalid(output, options, invalid('unknown', ['--harness must be pi, codex or claude.']));
+    }
+    const missing = [
+        ['--assignment', options.assignmentFile],
+        ['--template', options.templateFile],
+        ...(!options.live ? [['--execution', options.executionFile]] : []),
+    ]
+        .filter(([, value]) => value === null)
+        .map(([flag]) => flag);
+    if (missing.length) {
+        return emitInvalid(output, options, invalid(harness, [`missing required option(s): ${missing.join(', ')}.`]));
+    }
+    if (options.live && (harness !== 'pi' || options.executionFile !== null)) {
+        return emitInvalid(output, options, invalid(harness, ['--live requires Pi and excludes --execution.']));
+    }
+    if (harness === 'pi') {
+        if (options.sessionFile === null) {
+            return emitInvalid(output, options, invalid(harness, ['--session is required for pi.']));
+        }
+        if (options.eventsFile !== null) {
+            return emitInvalid(output, options, invalid(harness, ['--events is only valid for codex or claude.']));
+        }
+    }
+    else {
+        if (options.eventsFile === null) {
+            return emitInvalid(output, options, invalid(harness, [`--events is required for ${harness}.`]));
+        }
+        if (options.sessionFile !== null) {
+            return emitInvalid(output, options, invalid(harness, ['--session is only valid for pi.']));
+        }
+    }
+    const files = [
+        ['--assignment', options.assignmentFile],
+        ['--template', options.templateFile],
+        ['--execution', options.executionFile],
+        ['--session', options.sessionFile],
+        ['--events', options.eventsFile],
+    ];
+    const nonAbsolute = files
+        .filter(([, value]) => value !== null && !path.isAbsolute(value))
+        .map(([flag]) => flag);
+    if (nonAbsolute.length) {
+        return emitInvalid(output, options, invalid(harness, [
+            `option(s) must be absolute: ${nonAbsolute.join(', ')}.`,
+        ]));
+    }
+    const deriveOptions = {
+        harness,
+        assignmentFile: options.assignmentFile,
+        templateFile: options.templateFile,
+        executionFile: options.executionFile,
+        sessionFile: options.sessionFile,
+        eventsFile: options.eventsFile,
+        live: options.live ?? false,
+    };
+    const result = deriveCapabilityCard(deriveOptions);
+    if (options.json) {
+        output.stdout(`${JSON.stringify(result)}\n`);
+    }
+    else {
+        emitHuman(result, output);
+    }
+    if (result.status === 'derived')
+        return 0;
+    return result.status === 'needs_input' ? 1 : 2;
+}

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

@@ -0,0 +1,13 @@
+import { type HandoffAction } from '../../app/collab-handoff.js';
+import type { CliOutput } from '../output.js';
+export declare const collaborationHandoffUsage: string;
+export interface CollaborationHandoffOptions {
+    readonly action: HandoffAction | 'inventory' | null;
+    readonly taskRoot: string | null;
+    readonly requestFile: string | null;
+    readonly subtaskId: string | null;
+    readonly attempt: string | null;
+    readonly apply: boolean;
+    readonly json: boolean;
+}
+export declare function runCollaborationHandoffCommand(options: CollaborationHandoffOptions, output: CliOutput): Promise<number>;

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

@@ -0,0 +1,102 @@
+import path from 'node:path';
+import { COLLAB_HANDOFF_SCHEMA, applyHandoffRequest, loadHandoffRequest, planHandoffRequest, readHandoffInventory, } from '../../app/collab-handoff.js';
+export const collaborationHandoffUsage = 'pappra collab handoff inventory --task-root <abs> [--subtask-id <id>] [--attempt <positive integer>] [--json]\n' +
+    'pappra collab handoff <begin|stopped|rebind|transfer|confirm|complete|abort|release-dispatch> --task-root <abs> --request <abs request.json> [--apply] [--json]\n\n' +
+    'Recorded ownership handoff over the existing store/lifecycle primitives. Plan is\n' +
+    'namespace/request validation only; --apply performs a cooperative record\n' +
+    'mutation and never stops, launches, adopts or resumes an execution. Confirmation\n' +
+    'requires an accepted/recorded, explicitly correlated receiver message.';
+function invalid(output, options, errors) {
+    if (options.json) {
+        output.stdout(`${JSON.stringify({
+            schema: COLLAB_HANDOFF_SCHEMA,
+            ok: false,
+            status: 'invalid',
+            action: options.action,
+            errors,
+        })}\n`);
+    }
+    else {
+        output.stdout(`Handoff 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_HANDOFF_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(`Handoff needs input: ${value.message}\n`);
+        if (value.nextAction)
+            output.stdout(`  ${value.nextAction}\n`);
+    }
+    return exitCode;
+}
+function emitInventory(value, output) {
+    const counts = value.counts;
+    output.stdout(`Handoff inventory: ${String(counts.handoffs)} handoff(s), ${String(counts.inflight)} inflight, ${String(counts.uncertainty)} uncertainty.\n`);
+    if (value.truncated === true)
+        output.stdout('  Some inventory rows are omitted (bounded summary).\n');
+}
+function emitHuman(value, action, output) {
+    if (value.applied === false) {
+        output.stdout(`Handoff ${action} plan validated; nothing was persisted.\n`);
+    }
+    else {
+        output.stdout(`Handoff ${action} ${value.ok === true ? 'applied' : 'refused'}: ${String(value.reason ?? 'completed')}.\n`);
+    }
+}
+export async function runCollaborationHandoffCommand(options, output) {
+    if (options.action === null)
+        return invalid(output, options, ['handoff 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 === 'inventory') {
+        let attempt = null;
+        if (options.attempt !== null) {
+            const parsed = Number(options.attempt.trim());
+            if (!Number.isSafeInteger(parsed) || parsed <= 0)
+                return invalid(output, options, [
+                    '--attempt must be a positive integer.',
+                ]);
+            attempt = parsed;
+        }
+        const result = await readHandoffInventory(options.taskRoot, options.subtaskId, attempt);
+        if (!result.ok)
+            return failure(output, options, result, 1);
+        if (options.json)
+            output.stdout(`${JSON.stringify(result.value)}\n`);
+        else
+            emitInventory(result.value, output);
+        return 0;
+    }
+    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 = loadHandoffRequest(options.requestFile, options.action);
+    if (!loaded.ok)
+        return failure(output, options, loaded, 2);
+    const result = options.apply
+        ? await applyHandoffRequest(options.taskRoot, loaded.value.request)
+        : await planHandoffRequest(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-message.d.ts

@@ -0,0 +1,17 @@
+import type { CliOutput } from '../output.js';
+export declare const collaborationMessageUsage: string;
+export type CollaborationMessageAction = 'send' | 'list' | 'read' | 'notify';
+export interface CollaborationMessageOptions {
+    readonly cwd: string;
+    readonly action: CollaborationMessageAction | null;
+    readonly taskRoot: string | null;
+    readonly messageFile: string | null;
+    readonly messageId: string | null;
+    readonly bindingFile: string | null;
+    readonly apply: boolean;
+    readonly retry: boolean;
+    readonly limit: string | null;
+    readonly callerPane: string | null;
+    readonly json: boolean;
+}
+export declare function runCollaborationMessageCommand(options: CollaborationMessageOptions, output: CliOutput): Promise<number>;

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

@@ -0,0 +1,177 @@
+import { listMessagesForTaskRoot, readMessageFromTaskRoot, sendMessageFromFile, } from '../../app/collab-messages.js';
+import { notifyRegisteredMessage } from '../../app/collab-notify.js';
+export const collaborationMessageUsage = 'pappra collab message <send|list|read|notify> --task-root <dir> [options]\n' +
+    '  send   --message <abs envelope.json> [--apply]\n' +
+    '  list   [--limit <1-100>]\n' +
+    '  read   --message-id <id>\n' +
+    '  notify --message-id <id> --binding <abs binding.json> [--caller-pane <id>] [--apply] [--retry]\n\n' +
+    'send plans by default and persists only with --apply; it never notifies.\n' +
+    'notify forwards one registered pointer through the Herdr CLI without --wait and\n' +
+    'requires a task-local binding that matches the recipient and live agent metadata.';
+const CALLER_PANE_PATTERN = /^[A-Za-z0-9]+:p[A-Za-z0-9]+$/;
+const SUCCESS_STATUSES = new Set([
+    'planned',
+    'accepted',
+    'duplicate',
+    'submitted',
+    'already_recorded',
+]);
+function emit(output, json, payload, lines, exitCode) {
+    if (json) {
+        output.stdout(`${JSON.stringify(payload)}\n`);
+    }
+    else {
+        for (const line of lines)
+            output.stdout(`${line}\n`);
+    }
+    return exitCode;
+}
+function usageFailure(output, options, code, message) {
+    return emit(output, options.json, { schema: 'pappra/collaboration-message/1', ok: false, code, message }, [`pappra collab message: ${message}`], 2);
+}
+function serviceFailure(output, options, failure) {
+    if (options.json) {
+        output.stdout(`${JSON.stringify({
+            schema: 'pappra/collaboration-message/1',
+            ok: false,
+            action: options.action,
+            code: failure.code,
+            message: failure.message,
+            nextAction: failure.nextAction,
+        })}\n`);
+    }
+    else {
+        output.stderr(`pappra collab message: ${failure.message}\n`);
+        if (failure.nextAction !== null) {
+            output.stderr(`  next: ${failure.nextAction}\n`);
+        }
+    }
+    return 1;
+}
+export async function runCollaborationMessageCommand(options, output) {
+    if (options.action === null) {
+        return usageFailure(output, options, 'action_required', 'collab message requires send, list, read, or notify.');
+    }
+    const taskRoot = options.taskRoot;
+    if (taskRoot === null) {
+        return usageFailure(output, options, 'task_root_required', 'collab message requires an absolute --task-root.');
+    }
+    if (options.action === 'send') {
+        if (options.messageFile === null) {
+            return usageFailure(output, options, 'message_required', 'collab message send requires --message <abs envelope.json>.');
+        }
+        const result = await sendMessageFromFile(taskRoot, options.messageFile, {
+            apply: options.apply,
+        });
+        if (!result.ok)
+            return serviceFailure(output, options, result);
+        const value = result.value;
+        const payload = {
+            schema: 'pappra/collaboration-message/1',
+            ok: value.status !== 'conflict' && value.status !== 'rejected',
+            action: 'send',
+            applied: options.apply,
+            status: value.status,
+            message: value.message,
+            registrationStatus: value.registrationStatus,
+            stateRevision: value.stateRevision,
+            messagePath: value.messagePath,
+            digest: value.digest,
+            detail: value.detail,
+            delivery: value.delivery,
+            notified: value.notified,
+            taskAccepted: value.taskAccepted,
+        };
+        const ok = payload.ok;
+        return emit(output, options.json, payload, ok
+            ? [
+                `Message ${value.message.message_id} ${value.status}; delivery ${value.delivery}.`,
+                ...(value.messagePath === null
+                    ? []
+                    : [`  file: ${value.messagePath}`]),
+                ...(value.digest === null ? [] : [`  digest: ${value.digest}`]),
+            ]
+            : [
+                `Message ${value.message.message_id} ${value.status}: ${String(value.detail)}`,
+            ], ok ? 0 : 1);
+    }
+    if (options.action === 'list') {
+        const parsedLimit = (() => {
+            if (options.limit === null)
+                return 20;
+            const value = Number(options.limit);
+            return Number.isSafeInteger(value) ? value : Number.NaN;
+        })();
+        if (Number.isNaN(parsedLimit)) {
+            return usageFailure(output, options, 'limit_invalid', '--limit must be a positive integer.');
+        }
+        const result = await listMessagesForTaskRoot(taskRoot, {
+            limit: parsedLimit,
+        });
+        if (!result.ok)
+            return serviceFailure(output, options, result);
+        const value = result.value;
+        return emit(output, options.json, {
+            schema: 'pappra/collaboration-message/1',
+            ok: true,
+            action: 'list',
+            ...value,
+        }, [
+            `Messages ${value.returned}/${value.total}${value.truncated ? ' (truncated)' : ''}`,
+            ...value.messages.map((entry) => `  ${entry.message_id} ${entry.type} ${entry.state}${entry.reply_to === null ? '' : ` reply_to=${entry.reply_to}`}${entry.delivery === null ? '' : ` notification=${entry.delivery.status}`}`),
+        ], 0);
+    }
+    if (options.action === 'read') {
+        if (options.messageId === null) {
+            return usageFailure(output, options, 'message_id_required', 'collab message read requires --message-id.');
+        }
+        const result = await readMessageFromTaskRoot(taskRoot, options.messageId);
+        if (!result.ok)
+            return serviceFailure(output, options, result);
+        const value = result.value;
+        return emit(output, options.json, {
+            schema: 'pappra/collaboration-message/1',
+            ok: true,
+            action: 'read',
+            ...value,
+        }, [
+            `${value.message.message_id} ${value.message.type} ${value.entry?.state ?? 'not-applied'}`,
+            `  file: ${value.messagePath}`,
+            `  digest: ${value.digest}`,
+            `  notification: ${value.delivery?.status ?? 'not-notified'}`,
+        ], 0);
+    }
+    if (options.callerPane !== null &&
+        !CALLER_PANE_PATTERN.test(options.callerPane)) {
+        return usageFailure(output, options, 'caller_pane_invalid', '--caller-pane must be a Herdr pane id such as w3:p1.');
+    }
+    if (options.bindingFile === null || options.messageId === null) {
+        return usageFailure(output, options, 'notify_arguments_required', 'collab message notify requires --message-id and --binding.');
+    }
+    const result = await notifyRegisteredMessage({
+        taskRoot,
+        messageId: options.messageId,
+        bindingFile: options.bindingFile,
+        apply: options.apply,
+        retry: options.retry,
+        callerPane: options.callerPane,
+    });
+    if (!result.ok)
+        return serviceFailure(output, options, result);
+    const value = result.value;
+    const ok = SUCCESS_STATUSES.has(value.status);
+    return emit(output, options.json, {
+        schema: 'pappra/collaboration-message/1',
+        ok,
+        action: 'notify',
+        applied: options.apply,
+        ...value,
+    }, ok
+        ? [
+            `Notification ${value.status}; consumed=false, taskAccepted=false.`,
+            ...(value.deliveryPath === null
+                ? []
+                : [`  delivery: ${value.deliveryPath}`]),
+        ]
+        : [`Notification ${value.status}: ${String(value.detail)}`], ok ? 0 : 1);
+}

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;