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

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

@@ -0,0 +1,118 @@
+import { COLLAB_BINDING_RESULT_SCHEMA, bindAlias, listBindings, resolveBinding, unbindAlias, } from '../../app/collab-bindings.js';
+export const collaborationBindingUsage = 'pappra collab binding list [--root <abs workspace>] [--json]\n' +
+    'pappra collab binding resolve --task-id <alias> [--root <abs>] [--roots <abs roots.json>] [--json]\n' +
+    'pappra collab binding bind --task-id <alias> --record <abs task.json> [--root <abs>] [--apply] [--json]\n' +
+    'pappra collab binding unbind --task-id <alias> [--root <abs>] [--apply] [--json]\n\n' +
+    'Workspace-local alias pointers to authoritative collaboration records. The index\n' +
+    'contains pointer metadata only; it never copies protocol content,\n' +
+    'starts/adopts an execution or treats a target as live. Mutations plan by default.';
+function outputFailure(output, options, value, exitCode) {
+    const body = {
+        schema: COLLAB_BINDING_RESULT_SCHEMA,
+        ok: false,
+        status: exitCode === 2 ? 'invalid' : 'needs_input',
+        action: options.action,
+        code: value.code,
+        message: value.message,
+        nextAction: value.nextAction,
+        ...(value.details === undefined ? {} : { details: value.details }),
+    };
+    if (options.json)
+        output.stdout(`${JSON.stringify(body)}\n`);
+    else {
+        output.stdout(`Binding ${exitCode === 2 ? 'invalid' : 'needs input'}: ${value.message}\n`);
+        if (value.nextAction)
+            output.stdout(`  ${value.nextAction}\n`);
+        for (const detail of value.details ?? [])
+            output.stdout(`  - ${detail}\n`);
+    }
+    return exitCode;
+}
+function invalid(output, options, message) {
+    return outputFailure(output, options, {
+        ok: false,
+        code: 'invalid_options',
+        message,
+        nextAction: `Use ${collaborationBindingUsage.split('\n')[0]}.`,
+    }, 2);
+}
+function emitList(value, output) {
+    const counts = value.counts;
+    output.stdout(`Bindings: ${String(counts.bindings)} binding(s), ${String(counts.unbound)} tombstone(s).\n`);
+    for (const entry of value.bindings) {
+        output.stdout(`  ${String(entry.alias)} -> ${String(entry.record)} [${String(entry.status)}]\n`);
+    }
+    if (value.truncated === true) {
+        const omitted = value.omitted;
+        output.stdout(`  omitted: ${String(omitted.bindings)} binding(s), ${String(omitted.unbound)} tombstone(s)\n`);
+    }
+}
+function emitResolve(value, output) {
+    output.stdout(`Alias ${String(value.alias)}: ${String(value.status)} (usable ${String(value.usable)}).\n`);
+    const target = value.target;
+    if (target) {
+        output.stdout(`  record: ${String(target.record)} revision ${String(target.state_revision)}; coordinator epoch ${String(target.coordinator_epoch)}; frozen ${String(target.dispatch_frozen)}\n`);
+        output.stdout(`  attempts: ${String(target.attempt_count)}; scope: ${String(value.scope)}; live status: ${String(value.liveStatus)}\n`);
+    }
+    for (const candidate of value.candidates)
+        output.stdout(`  candidate: ${candidate}\n`);
+    for (const error of value.errors)
+        output.stdout(`  ! ${error}\n`);
+}
+function emitMutation(value, action, output) {
+    if (value.status === 'planned') {
+        output.stdout(action === 'bind'
+            ? 'Bind plan validates the alias, target and index; nothing was written.\n'
+            : 'Unbind plan validates the alias and index; nothing was written.\n');
+        return;
+    }
+    output.stdout(`${action === 'bind' ? 'Bind' : 'Unbind'} ${String(value.status)}; applied ${String(value.applied)}.\n`);
+    const target = value.target;
+    if (target)
+        output.stdout(`  target: ${String(target.record)}\n`);
+}
+export async function runCollaborationBindingCommand(options, output) {
+    if (options.action === null)
+        return invalid(output, options, 'binding requires list/resolve/bind/unbind.');
+    const serviceOptions = {
+        root: options.root,
+        taskId: options.taskId,
+        record: options.record,
+        roots: options.roots,
+        apply: options.apply,
+    };
+    const result = options.action === 'list'
+        ? await listBindings(serviceOptions)
+        : options.action === 'resolve'
+            ? await resolveBinding(serviceOptions)
+            : options.action === 'bind'
+                ? await bindAlias(serviceOptions)
+                : await unbindAlias(serviceOptions);
+    if (!result.ok) {
+        const exitCode = result.code === 'invalid_options' ||
+            result.code === 'workspace_unavailable' ||
+            result.code === 'bindings_invalid' ||
+            result.code === 'roots_invalid'
+            ? 2
+            : 1;
+        return outputFailure(output, options, result, exitCode);
+    }
+    if (options.json)
+        output.stdout(`${JSON.stringify(result.value)}\n`);
+    else if (options.action === 'list')
+        emitList(result.value, output);
+    else if (options.action === 'resolve')
+        emitResolve(result.value, output);
+    else
+        emitMutation(result.value, options.action, output);
+    if (options.action === 'resolve') {
+        const status = result.value.status;
+        return status === 'binding' ||
+            status === 'discovery-unique' ||
+            status === 'unbound' ||
+            status === 'none'
+            ? 0
+            : 1;
+    }
+    return 0;
+}

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

@@ -0,0 +1,10 @@
+import { type BootstrapAction, type VisibleBootstrapDependencies } from '../../app/collab-bootstrap.js';
+import type { CliOutput } from '../output.js';
+export declare const collaborationBootstrapUsage: string;
+export interface CollaborationBootstrapOptions {
+    readonly action: BootstrapAction | null;
+    readonly taskRoot: string | null;
+    readonly requestFile: string | null;
+    readonly json: boolean;
+}
+export declare function runCollaborationBootstrapCommand(options: CollaborationBootstrapOptions, output: CliOutput, dependencies?: VisibleBootstrapDependencies): Promise<number>;

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);
+}