cool-workflow 0.1.79 → 0.1.81

package/dist/mcp-server.js

@@ -65,6 +65,19 @@ function handleLine(line) {
         sendError(message.id, -32000, messageOf(error));
     }
 }
+// This is an EXPLICIT switch by design, NOT a descriptor-driven generic dispatcher
+// (FreeBSD-audit R1, assessed & closed as won't-do). A data-routing rewrite is
+// ACTIVELY DANGEROUS here, not just risky: (1) `descriptor.entry` does NOT reliably
+// name the function an arm calls (e.g. cw_app_run entry="validateApp" actually calls
+// appRun; cw_commit entry="commit" calls commitEnvelope), so `runner[entry](args)`
+// would silently call the WRONG method; (2) the parity gate is token-set-only +
+// payload-probes ~30 read-only runId caps, so ~150 multi-positional/write arms are
+// UNPROBED — a mis-marshalling generic dispatcher would pass BOTH gates green = the
+// existential public false-green (a CW red line — see DIRECTION.md). The arms
+// work and parity guards the surface; the real defect the audit flagged (a DEAD
+// dispatcher) was already removed (#131). Cheap safe hardening, if ever wanted:
+// broaden parity-check payload probes to cover multi-positional/write arms, and
+// correct the wrong `entry` metadata — NOT a dispatch rewrite.
 function callTool(name, args) {
     const previousCwd = process.cwd();
     if (args.cwd)
@@ -237,6 +250,8 @@ function callTool(name, args) {
                 return runner.recordCoordinatorDecision(String(args.runId || ""), args);
             case "cw_audit_summary":
                 return runner.auditSummary(String(args.runId || ""));
+            case "cw_audit_verify":
+                return (0, capability_core_1.auditVerify)(runner, args);
             case "cw_audit_worker":
                 return runner.workerAudit(String(args.runId || ""), String(args.workerId || ""));
             case "cw_audit_provenance":
@@ -386,11 +401,19 @@ function callTool(name, args) {
             case "cw_run_show":
                 return (0, capability_core_1.runShow)((0, capability_core_1.runRegistryFor)(args, runner), String(args.runId || ""), args);
             case "cw_run_resume":
-                return (0, capability_core_1.runResume)((0, capability_core_1.runRegistryFor)(args, runner), String(args.runId || ""), args);
+                return (0, capability_core_1.runResume)((0, capability_core_1.runRegistryFor)(args, runner), runner, String(args.runId || ""), args);
             case "cw_run_archive":
                 return (0, capability_core_1.runArchive)((0, capability_core_1.runRegistryFor)(args, runner), (0, capability_core_1.optionalString)(args.runId), args);
             case "cw_run_rerun":
                 return (0, capability_core_1.runRerun)((0, capability_core_1.runRegistryFor)(args, runner), String(args.runId || ""), args);
+            case "cw_run_export":
+                return (0, capability_core_1.runExportArchive)(runner, String(args.runId || ""), args);
+            case "cw_run_import":
+                return (0, capability_core_1.runImportArchive)(runner, args);
+            case "cw_run_verify_import":
+                return (0, capability_core_1.runVerifyImport)(runner, String(args.runId || ""), args);
+            case "cw_run_inspect_archive":
+                return (0, capability_core_1.runInspectArchive)(runner, args);
             case "cw_run_drive":
                 return (0, capability_core_1.runDrivePreview)(runner, args);
             case "cw_run_drive_step":
@@ -436,22 +459,8 @@ function callTool(name, args) {
                 // (identical to `cw workbench serve --json`). The CLI default additionally
                 // starts the localhost host — declared divergence (see capability-registry).
                 return (0, workbench_1.buildWorkbenchServeDescriptor)(runner, { ...args, once: true });
-            default: {
-                // ---- Dynamic capability dispatch fallback (v0.1.53) ---------------
-                // Mechanism: try the capability registry before failing. Policy: which
-                // tools exist is declared via registerCapabilityHandler at load time.
-                const capabilityId = (0, capability_registry_1.resolveMcpTool)(name);
-                if (capabilityId) {
-                    const handler = (0, capability_registry_1.getCapabilityHandler)(capabilityId);
-                    if (handler) {
-                        return (0, capability_registry_1.dispatchCapability)(capabilityId, args, {
-                            runner,
-                            cwd: process.cwd()
-                        });
-                    }
-                }
+            default:
                 throw new Error(`Unknown tool: ${name}`);
-            }
         }
     }
     finally {
@@ -478,159 +487,11 @@ function requiredToolArguments(name, value) {
     return args;
 }
 function requiredArgsForTool(name) {
-    if (name === "cw_plan" || name === "cw_init")
-        return ["workflowId"];
-    if (name === "cw_app_run")
-        return ["appId"];
-    if (name === "cw_node_show")
-        return ["runId", "nodeId"];
-    if (name === "cw_eval_replay")
-        return ["snapshot|snapshotId|path"];
-    if (name === "cw_eval_compare")
-        return ["baseline|baselinePath", "replay|replayPath"];
-    if (name === "cw_eval_score" || name === "cw_eval_report")
-        return ["replay|replayPath|path"];
-    if (name === "cw_eval_gate")
-        return ["suite|suiteId|path"];
-    if (name === "cw_topology_show" || name === "cw_topology_validate")
-        return ["topologyId|id"];
-    if (name === "cw_topology_apply")
-        return ["runId", "topologyId|id"];
-    if (name === "cw_sandbox_show")
-        return ["profileId"];
-    if (name === "cw_sandbox_validate")
-        return ["profileFile"];
-    if (name === "cw_schedule_delete" || name === "cw_schedule_complete" || name === "cw_schedule_pause" || name === "cw_schedule_resume" || name === "cw_schedule_run_now")
-        return ["id"];
-    if (name === "cw_routine_delete")
-        return ["id"];
-    if (name === "cw_routine_fire")
-        return ["kind"];
-    if (name === "cw_approve" || name === "cw_reject")
-        return ["runId", "targetKind|kind", "targetId|target"];
-    if (name === "cw_comment_add")
-        return ["runId", "targetKind|kind", "targetId|target", "body|message|text"];
-    if (name === "cw_handoff")
-        return ["runId", "targetKind|kind", "targetId|target", "to|toActor"];
-    if (name === "cw_run_show" || name === "cw_run_resume" || name === "cw_run_rerun")
-        return ["runId"];
-    if (name === "cw_run_archive")
-        return ["runId|olderThanDays"];
-    if (name === "cw_gc_verify")
-        return ["runId"];
-    if (name === "cw_telemetry_verify")
-        return ["runId"];
-    if (name === "cw_queue_show")
-        return ["id"];
-    if (name.endsWith("_show")) {
-        if (name.includes("_role_"))
-            return ["runId", "roleId"];
-        if (name.includes("_group_"))
-            return ["runId", "groupId"];
-        if (name.includes("_membership_"))
-            return ["runId", "membershipId"];
-        if (name.includes("_fanout_"))
-            return ["runId", "fanoutId"];
-        if (name.includes("_fanin_"))
-            return ["runId", "faninId"];
-        if (name.includes("_candidate_"))
-            return ["runId", "candidateId"];
-        if (name.includes("_feedback_"))
-            return ["runId", "feedbackId"];
-        if (name.includes("_worker_"))
-            return ["runId", "workerId"];
-    }
-    if (name.startsWith("cw_") && [
-        "cw_status",
-        "cw_next",
-        "cw_state_check",
-        "cw_contract_show",
-        "cw_node_list",
-        "cw_node_graph",
-        "cw_operator_status",
-        "cw_operator_graph",
-        "cw_operator_report",
-        "cw_worker_summary",
-        "cw_workbench_view",
-        "cw_candidate_summary",
-        "cw_feedback_summary",
-        "cw_commit_summary",
-        "cw_multi_agent_summary",
-        "cw_multi_agent_graph",
-        "cw_multi_agent_dependencies",
-        "cw_multi_agent_failures",
-        "cw_multi_agent_evidence",
-        "cw_evidence_reasoning",
-        "cw_evidence_reasoning_refresh",
-        "cw_summary_refresh",
-        "cw_summary_show",
-        "cw_metrics_show",
-        "cw_blackboard_summarize",
-        "cw_multi_agent_summarize",
-        "cw_multi_agent_graph_compact",
-        "cw_multi_agent_status",
-        "cw_multi_agent_step",
-        "cw_multi_agent_blackboard",
-        "cw_multi_agent_score",
-        "cw_multi_agent_select",
-        "cw_eval_snapshot",
-        "cw_multi_agent_run_create",
-        "cw_multi_agent_run_transition",
-        "cw_multi_agent_run_show",
-        "cw_multi_agent_role_create",
-        "cw_multi_agent_group_create",
-        "cw_multi_agent_membership_create",
-        "cw_multi_agent_fanout_create",
-        "cw_multi_agent_fanin_collect",
-        "cw_topology_summary",
-        "cw_topology_graph",
-        "cw_blackboard_summary",
-        "cw_blackboard_graph",
-        "cw_blackboard_resolve",
-        "cw_blackboard_topic_create",
-        "cw_blackboard_message_post",
-        "cw_blackboard_message_list",
-        "cw_blackboard_context_put",
-        "cw_blackboard_artifact_add",
-        "cw_blackboard_artifact_list",
-        "cw_blackboard_snapshot",
-        "cw_coordinator_summary",
-        "cw_coordinator_decision",
-        "cw_audit_summary",
-        "cw_audit_worker",
-        "cw_audit_provenance",
-        "cw_audit_multi_agent",
-        "cw_audit_policy",
-        "cw_audit_role",
-        "cw_audit_blackboard",
-        "cw_audit_judge",
-        "cw_audit_attest",
-        "cw_audit_decision",
-        "cw_dispatch",
-        "cw_result",
-        "cw_commit",
-        "cw_report",
-        "cw_worker_list",
-        "cw_worker_manifest",
-        "cw_worker_output",
-        "cw_worker_fail",
-        "cw_worker_validate",
-        "cw_candidate_list",
-        "cw_candidate_register",
-        "cw_candidate_score",
-        "cw_candidate_rank",
-        "cw_candidate_select",
-        "cw_candidate_reject",
-        "cw_review_status",
-        "cw_review_policy",
-        "cw_comment_list",
-        "cw_feedback_list",
-        "cw_feedback_collect",
-        "cw_feedback_task",
-        "cw_feedback_resolve"
-    ].includes(name))
-        return ["runId"];
-    return [];
+    // Required args are declared once per capability as data on the mcp binding
+    // (McpBinding.requiredArgs). This is a pure data read of the parity-gated
+    // registry — no string-pattern ladder.
+    const descriptor = capability_registry_1.CAPABILITY_REGISTRY.find((capability) => capability.mcp?.tool === name);
+    return descriptor?.mcp?.requiredArgs ?? [];
 }
 function toolDefinitions() {
     return [
@@ -704,24 +565,23 @@ function toolDefinitions() {
             contract: stringSchema("run-state | workflow-app (default run-state)"),
             cwd: stringSchema("Run workspace")
         }),
-        tool("cw_operator_status", "Read the structured Operator UX run status.", runIdSchema()),
-        tool("cw_operator_graph", "Read the structured Operator UX run graph.", runIdSchema()),
-        tool("cw_operator_report", "Refresh and read the structured Operator UX report summary.", runIdSchema()),
-        tool("cw_worker_summary", "Read the structured worker summary for a run.", runIdSchema()),
+        ...runIdCapabilityTools(["operator.status", "graph", "operator.report", "worker.summary"]),
         tool("cw_workbench_view", "Read the read-only five-panel Workbench view (graph, blackboard, worker, candidate, audit) for one run. Each panel embeds the verbatim `cw <cmd> --json` payload of one existing capability; absent panels are surfaced honestly. Peer of `cw workbench view`.", runIdSchema()),
         tool("cw_workbench_serve", "Describe the optional localhost-only, read-only Workbench host (bind, scope, routes). Returns the serve descriptor identical to `cw workbench serve --json`; MCP never starts the blocking server.", {
             cwd: stringSchema("Run workspace"),
             port: numberSchema("Optional loopback port, defaults to 7717"),
             scope: stringSchema("Registry scope: repo|home")
         }),
-        tool("cw_candidate_summary", "Read the structured candidate summary for a run.", runIdSchema()),
-        tool("cw_feedback_summary", "Read the structured feedback summary for a run.", runIdSchema()),
-        tool("cw_commit_summary", "Read the structured commit summary for a run.", runIdSchema()),
-        tool("cw_multi_agent_summary", "Read the structured multi-agent runtime summary for a run.", runIdSchema()),
-        tool("cw_multi_agent_graph", "Read the structured multi-agent operator graph for a run.", runIdSchema()),
-        tool("cw_multi_agent_dependencies", "Read derived multi-agent dependency edges for operator inspection.", runIdSchema()),
-        tool("cw_multi_agent_failures", "Read failed, blocked, rejected, and ambiguous multi-agent records.", runIdSchema()),
-        tool("cw_multi_agent_evidence", "Read evidence adoption status from worker output through selection and commit. Each row carries a derived rationaleStatus (explained|unexplained|not-applicable).", runIdSchema()),
+        ...runIdCapabilityTools([
+            "candidate.summary",
+            "feedback.summary",
+            "commit.summary",
+            "multi-agent.summary",
+            "multi-agent.graph",
+            "multi-agent.dependencies",
+            "multi-agent.failures",
+            "multi-agent.evidence"
+        ]),
         tool("cw_evidence_reasoning", "Explain WHY each evidence item was adopted/rejected/superseded/conflicting: a derived, fingerprinted reasoning chain with decision, basis, authority, rationale, and counterfactual per gate (fanin, candidate-score, selection, verifier, commit). Fails closed to `unexplained` when a rationale cannot be traced. Reads valid|stale|absent freshness against current source state.", {
             ...runIdSchema(),
             evidence: stringSchema("Optional evidence id/ref to explain a single adoption"),
@@ -1029,6 +889,7 @@ function toolDefinitions() {
             message: arraySchema("Blackboard message ids")
         }),
         tool("cw_audit_summary", "Read durable trust/audit summary for a run.", runIdSchema()),
+        tool("cw_audit_verify", "Re-prove a run's trust-audit hash chain offline: recompute every event hash from genesis + check chain linkage; a forged, edited, truncated, or unchained-injected event fails it. Peer of `cw audit verify`; fail-closed.", runIdSchema()),
         tool("cw_audit_worker", "Read trust/audit events for one worker.", workerIdSchema()),
         tool("cw_audit_provenance", "Inspect evidence provenance for a run, worker, candidate, or commit.", {
             ...runIdSchema(),
@@ -1440,6 +1301,31 @@ function toolDefinitions() {
             scope: stringSchema("home (default, cross-repo) or repo"),
             reason: stringSchema("Rerun reason")
         }),
+        tool("cw_run_export", "Export a run to a portable, digest-checked archive containing run-local artifacts, audit overlays, telemetry, reports, workers, and commit snapshots.", {
+            runId: stringSchema("Run id to export"),
+            cwd: stringSchema("Repo workspace containing .cw/runs/<run-id>"),
+            output: stringSchema("Archive output path"),
+            path: stringSchema("Alias for output"),
+            archive: stringSchema("Alias for output")
+        }),
+        tool("cw_run_import", "Restore a portable run archive into a target repo and immediately verify restored file digests.", {
+            archive: stringSchema("Archive path"),
+            path: stringSchema("Alias for archive"),
+            file: stringSchema("Alias for archive"),
+            target: stringSchema("Restore target repo directory"),
+            repo: stringSchema("Alias for target"),
+            cwd: stringSchema("Invocation workspace")
+        }),
+        tool("cw_run_verify_import", "Verify an imported run against its restore manifest and telemetry chain; detects missing or tampered restored files.", {
+            runId: stringSchema("Imported run id to verify"),
+            cwd: stringSchema("Restored repo workspace")
+        }),
+        tool("cw_run_inspect_archive", "Read-only integrity inspection of a portable run archive without importing it: re-proves every file digest/size, the manifest digest + file count, and the whole-archive sha256, naming any offending file. Writes nothing.", {
+            archive: stringSchema("Archive path"),
+            path: stringSchema("Alias for archive"),
+            file: stringSchema("Alias for archive"),
+            cwd: stringSchema("Invocation workspace")
+        }),
         tool("cw_run_drive", "Preview the next agent-delegation drive step for a run (read-only, deterministic). Counts come from state; no spawn, no mutation.", {
             runId: stringSchema("Run id to preview"),
             cwd: stringSchema("Run workspace")
@@ -1535,9 +1421,10 @@ function toolDefinitions() {
             scope: stringSchema("home (default, cross-repo) or repo"),
             runId: stringSchema("Run id to verify")
         }),
-        tool("cw_telemetry_verify", "Re-prove a run's telemetry attestation ledger offline: prevHash chain linkage + independent per-record hash recompute (never trusts the stored hash). A forged or edited record fails it. Peer of `cw telemetry verify`.", {
+        tool("cw_telemetry_verify", "Re-prove a run's telemetry attestation ledger offline: prevHash chain linkage + independent per-record hash recompute (never trusts the stored hash), and optionally re-run ed25519 checks with a public key. A forged or edited record fails it. Peer of `cw telemetry verify`.", {
             cwd: stringSchema("Repo workspace"),
-            runId: stringSchema("Run id to verify")
+            runId: stringSchema("Run id to verify"),
+            pubkey: stringSchema("Optional inline PEM or path to a public key for re-checking attested signatures")
         }),
         tool("cw_history", "Read a cross-repo unified run timeline (newest first), deterministic and paginated, with provenance links.", {
             cwd: stringSchema("Repo workspace"),
@@ -1560,6 +1447,15 @@ function tool(name, description, properties) {
         }
     };
 }
+function runIdCapabilityTools(capabilityIds) {
+    return capabilityIds.map((capabilityId) => capabilityTool(capabilityId, runIdSchema()));
+}
+function capabilityTool(capabilityId, properties) {
+    const descriptor = capability_registry_1.CAPABILITY_REGISTRY.find((capability) => capability.capability === capabilityId);
+    if (!descriptor?.mcp)
+        throw new Error(`MCP capability not declared: ${capabilityId}`);
+    return tool(descriptor.mcp.tool, descriptor.summary, properties);
+}
 function stringSchema(description) {
     return { type: "string", description };
 }

package/dist/multi-agent/graph.js

@@ -0,0 +1,84 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildMultiAgentGraphFromState = buildMultiAgentGraphFromState;
+// Multi-agent provenance-graph builder (god-module carve, FreeBSD router pattern
+// — cf. orchestrator/topology-operations.ts and run-registry/derive.ts). This is
+// the largest cohesive renderer in the module: it walks the resolved
+// MultiAgentState and emits the nodes/edges that the operator-UX and orchestrator
+// graph surfaces consume. BEHAVIOR-PRESERVING — pure code movement, zero logic
+// change. multi-agent.ts keeps the public buildMultiAgentGraph(run) entry point
+// as a thin delegator (it resolves the state via ensureMultiAgentState, then
+// calls buildMultiAgentGraphFromState) so the state is still ensured exactly
+// once, in the same order, with the same side effects.
+const node_fs_1 = __importDefault(require("node:fs"));
+const paths_1 = require("./paths");
+const helpers_1 = require("./helpers");
+function buildMultiAgentGraphFromState(run, state) {
+    const root = (0, paths_1.multiAgentRoot)(run);
+    const nodes = [];
+    const edges = [];
+    for (const record of state.runs) {
+        nodes.push({ id: `${run.id}:multi-agent:${record.id}`, kind: "multi-agent-run", status: record.status, label: record.title || record.id, path: (0, paths_1.recordPath)(run, "runs", record.id) });
+        edges.push({ from: `${run.id}:run`, to: `${run.id}:multi-agent:${record.id}` });
+        if (record.blackboardId)
+            edges.push({ from: `${run.id}:multi-agent:${record.id}`, to: `${run.id}:blackboard:${record.blackboardId}`, label: "blackboard" });
+        if (record.parentMultiAgentRunId)
+            edges.push({ from: `${run.id}:multi-agent:${record.parentMultiAgentRunId}`, to: `${run.id}:multi-agent:${record.id}`, label: "child" });
+    }
+    for (const record of state.roles) {
+        nodes.push({ id: `${run.id}:multi-agent:role:${record.id}`, kind: "agent-role", status: record.status, label: record.title, path: (0, paths_1.recordPath)(run, "roles", record.id) });
+        edges.push({ from: `${run.id}:multi-agent:${record.multiAgentRunId}`, to: `${run.id}:multi-agent:role:${record.id}` });
+        if (record.blackboardId)
+            edges.push({ from: `${run.id}:multi-agent:role:${record.id}`, to: `${run.id}:blackboard:${record.blackboardId}`, label: "blackboard" });
+    }
+    for (const record of state.groups) {
+        nodes.push({ id: `${run.id}:multi-agent:group:${record.id}`, kind: "agent-group", status: record.status, label: record.title || record.id, path: (0, paths_1.recordPath)(run, "groups", record.id) });
+        edges.push({ from: `${run.id}:multi-agent:${record.multiAgentRunId}`, to: `${run.id}:multi-agent:group:${record.id}` });
+        if (record.blackboardId)
+            edges.push({ from: `${run.id}:multi-agent:group:${record.id}`, to: `${run.id}:blackboard:${record.blackboardId}`, label: "blackboard" });
+        for (const taskId of record.taskIds)
+            edges.push({ from: `${run.id}:multi-agent:group:${record.id}`, to: `${run.id}:task:${taskId}`, label: "task" });
+    }
+    for (const record of state.fanouts) {
+        nodes.push({ id: `${run.id}:multi-agent:fanout:${record.id}`, kind: "agent-fanout", status: record.status, label: record.reason, path: (0, paths_1.recordPath)(run, "fanouts", record.id) });
+        edges.push({ from: `${run.id}:multi-agent:group:${record.groupId}`, to: `${run.id}:multi-agent:fanout:${record.id}` });
+        for (const dispatchId of record.dispatchIds)
+            edges.push({ from: `${run.id}:multi-agent:fanout:${record.id}`, to: `${run.id}:dispatch:${dispatchId}`, label: "dispatch" });
+    }
+    for (const record of state.memberships) {
+        nodes.push({ id: `${run.id}:multi-agent:membership:${record.id}`, kind: "agent-membership", status: record.status, label: `${record.roleId}/${record.taskId}`, path: (0, paths_1.recordPath)(run, "memberships", record.id) });
+        edges.push({ from: `${run.id}:multi-agent:group:${record.groupId}`, to: `${run.id}:multi-agent:membership:${record.id}` });
+        edges.push({ from: `${run.id}:multi-agent:role:${record.roleId}`, to: `${run.id}:multi-agent:membership:${record.id}` });
+        edges.push({ from: `${run.id}:multi-agent:membership:${record.id}`, to: `${run.id}:task:${record.taskId}`, label: "task" });
+        if (record.workerId)
+            edges.push({ from: `${run.id}:multi-agent:membership:${record.id}`, to: `${run.id}:worker:${record.workerId}`, label: "worker" });
+        if (record.resultNodeId)
+            edges.push({ from: `${run.id}:multi-agent:membership:${record.id}`, to: record.resultNodeId, label: "result" });
+        if (record.verifierNodeId)
+            edges.push({ from: `${run.id}:multi-agent:membership:${record.id}`, to: record.verifierNodeId, label: "verifier" });
+        if (record.blackboardId)
+            edges.push({ from: `${run.id}:multi-agent:membership:${record.id}`, to: `${run.id}:blackboard:${record.blackboardId}`, label: "blackboard" });
+        for (const artifactId of record.blackboardArtifactRefIds || [])
+            edges.push({ from: `${run.id}:multi-agent:membership:${record.id}`, to: `${run.id}:blackboard:artifact:${artifactId}`, label: "evidence" });
+        for (const messageId of record.blackboardMessageIds || [])
+            edges.push({ from: `${run.id}:multi-agent:membership:${record.id}`, to: `${run.id}:blackboard:message:${messageId}`, label: "message" });
+    }
+    for (const record of state.fanins) {
+        nodes.push({ id: `${run.id}:multi-agent:fanin:${record.id}`, kind: "agent-fanin", status: record.status, label: record.strategy, path: (0, paths_1.recordPath)(run, "fanins", record.id) });
+        edges.push({ from: `${run.id}:multi-agent:group:${record.groupId}`, to: `${run.id}:multi-agent:fanin:${record.id}` });
+        if (record.fanoutId)
+            edges.push({ from: `${run.id}:multi-agent:fanout:${record.fanoutId}`, to: `${run.id}:multi-agent:fanin:${record.id}` });
+        for (const membershipId of record.reportedMembershipIds)
+            edges.push({ from: `${run.id}:multi-agent:membership:${membershipId}`, to: `${run.id}:multi-agent:fanin:${record.id}`, label: "reported" });
+        for (const membershipId of record.missingMembershipIds)
+            edges.push({ from: `${run.id}:multi-agent:membership:${membershipId}`, to: `${run.id}:multi-agent:fanin:${record.id}`, label: "missing" });
+        if (record.blackboardId)
+            edges.push({ from: `${run.id}:multi-agent:fanin:${record.id}`, to: `${run.id}:blackboard:${record.blackboardId}`, label: "blackboard" });
+    }
+    if (!node_fs_1.default.existsSync(root))
+        node_fs_1.default.mkdirSync(root, { recursive: true });
+    return { nodes, edges: (0, helpers_1.uniqueEdges)(edges) };
+}

package/dist/multi-agent/helpers.js

@@ -0,0 +1,145 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MULTI_AGENT_SCHEMA_VERSION = void 0;
+exports.indexRow = indexRow;
+exports.assertNoRecordPathCollisions = assertNoRecordPathCollisions;
+exports.pluralKind = pluralKind;
+exports.statusToNodeStatus = statusToNodeStatus;
+exports.assertLifecycleTransition = assertLifecycleTransition;
+exports.lifecycleEvent = lifecycleEvent;
+exports.isMembershipReported = isMembershipReported;
+exports.touch = touch;
+exports.createId = createId;
+exports.compact = compact;
+exports.unique = unique;
+exports.countBy = countBy;
+exports.uniqueEdges = uniqueEdges;
+const state_1 = require("../state");
+exports.MULTI_AGENT_SCHEMA_VERSION = 1;
+function indexRow(record) {
+    return { id: record.id, status: record.status, updatedAt: record.updatedAt };
+}
+function assertNoRecordPathCollisions(label, records) {
+    const seen = new Map();
+    for (const record of records) {
+        const safe = (0, state_1.safeFileName)(record.id);
+        const existing = seen.get(safe);
+        if (existing && existing !== record.id) {
+            throw new Error(`${label} ids ${existing} and ${record.id} collide on safe file name ${safe}`);
+        }
+        seen.set(safe, record.id);
+    }
+}
+function pluralKind(kind) {
+    switch (kind) {
+        case "multi-agent-run":
+            return "runs";
+        case "agent-role":
+            return "roles";
+        case "agent-group":
+            return "groups";
+        case "agent-membership":
+            return "memberships";
+        case "agent-fanout":
+            return "fanouts";
+        case "agent-fanin":
+            return "fanins";
+        default:
+            return `${kind}s`;
+    }
+}
+function statusToNodeStatus(status) {
+    switch (status) {
+        case "completed":
+        case "reported":
+        case "ready":
+            return "completed";
+        case "running":
+        case "forming":
+        case "collecting":
+        case "verifying":
+        case "assigned":
+        case "active":
+        case "dispatched":
+            return "running";
+        case "blocked":
+            return "blocked";
+        case "failed":
+            return "failed";
+        case "cancelled":
+        case "rejected":
+            return "rejected";
+        default:
+            return "pending";
+    }
+}
+function assertLifecycleTransition(from, to) {
+    const allowed = {
+        planned: ["forming", "running", "failed", "cancelled"],
+        forming: ["running", "failed", "cancelled"],
+        running: ["collecting", "completed", "failed", "cancelled"],
+        collecting: ["verifying", "completed", "failed", "cancelled"],
+        verifying: ["completed", "failed", "cancelled"],
+        completed: [],
+        failed: [],
+        cancelled: []
+    };
+    if (from === to)
+        return;
+    if (!allowed[from].includes(to))
+        throw new Error(`Invalid MultiAgentRun lifecycle transition: ${from} -> ${to}`);
+}
+function lifecycleEvent(from, to, reason, actor = "cw", metadata) {
+    return {
+        at: new Date().toISOString(),
+        from,
+        to,
+        actor,
+        reason,
+        metadata: compact(metadata)
+    };
+}
+function isMembershipReported(membership) {
+    return (membership.status === "reported" || membership.status === "verified") && membership.evidenceRefs.length > 0;
+}
+function touch(record) {
+    record.updatedAt = new Date().toISOString();
+    return record;
+}
+// Deterministic record id (FreeBSD-audit L12/L13): the record's POSITION in its
+// per-run collection, threaded from the call site. No wall-clock stamp, no PRNG
+// suffix — re-running the same multi-agent topology mints byte-identical ids, so
+// snapshot/replay digests match. Each call site already asserts the minted id is
+// unique within its collection, and these collections only ever append.
+function createId(prefix, seq) {
+    return `${prefix}-${String(seq).padStart(4, "0")}`;
+}
+function compact(value) {
+    if (!value)
+        return undefined;
+    const entries = Object.entries(value).filter(([, entry]) => entry !== undefined);
+    return entries.length ? Object.fromEntries(entries) : undefined;
+}
+function unique(values) {
+    return Array.from(new Set(values.filter(Boolean))).sort();
+}
+function countBy(items, key) {
+    const counts = {};
+    for (const item of items) {
+        const value = key(item);
+        counts[value] = (counts[value] || 0) + 1;
+    }
+    return counts;
+}
+function uniqueEdges(edges) {
+    const seen = new Set();
+    const result = [];
+    for (const edge of edges) {
+        const key = `${edge.from}\0${edge.to}\0${edge.label || ""}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        result.push(edge);
+    }
+    return result;
+}

package/dist/multi-agent/paths.js

@@ -0,0 +1,22 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.multiAgentRoot = multiAgentRoot;
+exports.recordPath = recordPath;
+// Filesystem path resolution for multi-agent records (god-module carve, FreeBSD
+// router pattern). BEHAVIOR-PRESERVING — pure code movement, zero logic change.
+// These two free functions derive paths from run.paths only; they are shared by
+// the persistence, node-append, and graph clusters, so they live in their own
+// leaf module to keep those clusters free of a circular import back to
+// multi-agent.ts. Re-exported there is unnecessary (both are private), but the
+// derivation is byte-identical to the originals.
+const node_path_1 = __importDefault(require("node:path"));
+const state_1 = require("../state");
+function multiAgentRoot(run) {
+    return run.paths.multiAgentDir || node_path_1.default.join(run.paths.runDir, "multi-agent");
+}
+function recordPath(run, kind, id) {
+    return node_path_1.default.join(multiAgentRoot(run), kind, `${(0, state_1.safeFileName)(id)}.json`);
+}