cool-workflow 0.1.80 → 0.1.82

package/dist/gates.js

@@ -0,0 +1,48 @@
+"use strict";
+// Shared, drift-proof gate primitives (F4). These two helpers were previously
+// duplicated "in sync by comment" in commit.ts and candidate-scoring.ts — the
+// no-false-green gate and the sandbox-profile lookup. A by-comment sync is a
+// structural drift hazard: nothing prevents one copy from changing without the
+// other, and the two gates MUST agree (selection + commit must reach the same
+// empty-capture verdict). Extracting ONE implementation each, imported by both
+// call sites, makes that drift impossible.
+//
+// Pure functions over PERSISTED state only — no clock, no randomness, no fs —
+// so both selection and commit replays reach the same gate decision. Keep them
+// fail-closed: when in doubt the caller must BLOCK, never silently pass.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.emptyCaptureWarning = emptyCaptureWarning;
+exports.sandboxProfileForCandidate = sandboxProfileForCandidate;
+/** The HARD no-false-green gate (DIRECTION.md "ambiguity is a visible state").
+ *  A verifier node is built FROM a result node; when that result captured no
+ *  structured signal at all the result node carries a `metadata.captureWarning`
+ *  marker (set in worker-isolation / lifecycle ingest via isEmptyCapture). The
+ *  worker output is still ACCEPTED (a recorded warning, never a silent pass), but
+ *  a verifier-GATED commit — and candidate SELECTION — must NOT be able to
+ *  present that zero-evidence result as clean/green. We detect it here, reading
+ *  ONLY persisted state (the source result node's metadata) — purely functional,
+ *  no clock/ordering — so snapshot replay reaches the same gate decision.
+ *  Returns the marker string, or undefined.
+ *
+ *  Resolution trail: verifier node -> its input/parent result node. We look at
+ *  `inputs.inputNodeId` (set by runPipelineStage) first, then fall back to the
+ *  first parent, so it works regardless of which ingest path produced the node. */
+function emptyCaptureWarning(run, verifierNode) {
+    const resultNodeId = (typeof verifierNode.inputs?.inputNodeId === "string" ? verifierNode.inputs.inputNodeId : undefined) ||
+        verifierNode.parents[0];
+    const resultNode = resultNodeId ? (run.nodes || []).find((node) => node.id === resultNodeId) : undefined;
+    const warning = resultNode?.metadata?.captureWarning;
+    return typeof warning === "string" && warning ? warning : undefined;
+}
+/** Resolve the sandbox profile that backed a candidate's acceptance: the
+ *  worker's profile if the candidate has a worker, else the originating task's.
+ *  Read by both the commit gate's acceptance rationale and selection. Accepts an
+ *  optional candidate so the commit-side caller (which may not have resolved a
+ *  candidate) can share the same lookup. Pure over persisted run state. */
+function sandboxProfileForCandidate(run, candidate) {
+    const worker = candidate?.workerId ? (run.workers || []).find((entry) => entry.id === candidate.workerId) : undefined;
+    if (worker?.sandboxProfileId)
+        return worker.sandboxProfileId;
+    const task = candidate?.taskId ? (run.tasks || []).find((entry) => entry.id === candidate.taskId) : undefined;
+    return task?.sandboxProfileId;
+}

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,7 +401,7 @@ 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":
@@ -397,6 +412,8 @@ function callTool(name, args) {
                 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":
@@ -442,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 {
@@ -484,161 +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" || name === "cw_run_export" || name === "cw_run_verify_import")
-        return ["runId"];
-    if (name === "cw_run_import")
-        return ["archive|path|file"];
-    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 [
@@ -1036,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(),
@@ -1466,6 +1320,12 @@ function toolDefinitions() {
             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")
@@ -1561,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"),

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,141 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createId = 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.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 — single source of truth in ./ids. Re-exported here so
+// multi-agent.ts importers stay byte-unchanged (F10 dedup: the coordinator layer
+// shares the exact same helper).
+var ids_1 = require("./ids");
+Object.defineProperty(exports, "createId", { enumerable: true, get: function () { return ids_1.createId; } });
+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/ids.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createId = createId;
+// Single source of truth for the deterministic record id scheme shared by the
+// multi-agent kernel (multi-agent/helpers.ts) and the coordinator/blackboard
+// layer (coordinator/util.ts). Both previously copy-pasted byte-identical
+// zero-padded-seq logic; this dedup (F10) collapses them onto one helper.
+//
+// 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 / coordination 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.
+//
+// REPLAY DETERMINISM: pure function of its arguments — no Date, no random.
+// The output MUST stay byte-identical: `${prefix}-${4-digit-zero-padded-seq}`.
+function createId(prefix, seq) {
+    return `${prefix}-${String(seq).padStart(4, "0")}`;
+}

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