@limina-labs/momentum 0.30.2

package/core/swarm/schema/dispatch-run.schema.json

@@ -0,0 +1,70 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/LiminaLabsAI/momentum/schemas/swarm-dispatch-run-v1.json",
+  "title": "Momentum Swarm Dispatch-Run (Per-Supervisor Saga Step)",
+  "description": "Extension of the existing Phase 11 dispatch-run-NNN artifact for swarm-aware supervisors. Lives at <repo>/.momentum/runs/dispatch-run-NNN.json (one per supervisor per wave). The conductor never reads this directly — it watches HEAD SHAs + reads materialized board.json. This schema is the durable per-step saga record that makes /swarm resume possible.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["run_id", "primitive", "swarm_id", "saga_id", "wave", "repo", "phase_slug", "started", "step_n", "done"],
+  "properties": {
+    "run_id": {
+      "type": "string",
+      "pattern": "^[0-9]{3,6}$",
+      "description": "Zero-padded counter per repo per primitive. Matches the filename suffix."
+    },
+    "primitive": {
+      "type": "string",
+      "const": "swarm-supervise",
+      "description": "Marks this as a swarm supervisor run (distinct from scout/dispatch/handoff dispatch-runs that share the same .momentum/runs/ directory)."
+    },
+    "swarm_id": {"type": "string", "pattern": "^[0-9]{4}-[a-z][a-z0-9-]*$"},
+    "saga_id": {"type": "string", "pattern": "^sg_[a-z0-9]{4,16}$"},
+    "wave": {"type": "integer", "minimum": 1},
+    "repo": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9-]*$",
+      "description": "Ecosystem member id this supervisor is pinned to."
+    },
+    "phase_slug": {
+      "type": "string",
+      "pattern": "^phase-[0-9]+(?:[a-z])?-[a-z][a-z0-9-]*$"
+    },
+    "branch": {"type": "string", "minLength": 1},
+    "started": {"type": "string", "format": "date-time"},
+    "step_n": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Monotonic step counter inside this wave. Each supervisor /start-phase iteration bumps step_n."
+    },
+    "done": {
+      "type": "boolean",
+      "description": "True once /complete-phase succeeded in this supervisor's repo for this wave."
+    },
+    "ended": {"type": "string", "format": "date-time"},
+    "exit_status": {
+      "type": "string",
+      "enum": ["success", "failed", "cancelled", "in-progress"]
+    },
+    "tasks_done": {"type": "integer", "minimum": 0},
+    "tasks_total": {"type": "integer", "minimum": 0},
+    "tokens_used": {"type": "integer", "minimum": 0},
+    "head_sha": {"type": "string", "pattern": "^[0-9a-f]{7,40}$"},
+    "last_commit": {"type": "string", "description": "Last commit subject the supervisor wrote."},
+    "current_file": {"type": "string", "description": "Free-form: what file the supervisor is editing right now."},
+    "inbox_items": {
+      "type": "array",
+      "items": {"type": "string"},
+      "description": "Slugs of inbox items this supervisor has written. Empty when none pending."
+    },
+    "history_tail_offset": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Byte offset into <repo>/specs/phases/<slug>/history.md where the supervisor was last seen. Lets /swarm resume seek to new entries without re-reading the full file."
+    },
+    "claimed_by_session": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Session UUID that wrote this step. Portability hook."
+    }
+  }
+}

package/core/swarm/schema/manifest.schema.json

@@ -0,0 +1,234 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/LiminaLabsAI/momentum/schemas/swarm-manifest-v1.json",
+  "title": "Momentum Swarm Manifest",
+  "description": "Declares a cross-repo work unit driven from one user (conductor) session. Lives at <ecosystem-root>/swarms/<id>/manifest.json. The saga record — repos, waves, owner/lease, contract pins, token budgets, audit. All conductor + supervisor writes go through mkdir-locked CRUD in core/swarm/lib/manifest.js.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["swarm_id", "version", "saga_id", "mode", "initiative", "created", "ecosystem", "repos", "waves"],
+  "properties": {
+    "swarm_id": {
+      "type": "string",
+      "pattern": "^[0-9]{4}-[a-z][a-z0-9-]*$",
+      "description": "Zero-padded NNNN- prefix plus kebab slug, e.g. 0007-user-auth. Matches the on-disk directory name."
+    },
+    "version": {
+      "type": "integer",
+      "const": 1,
+      "description": "Manifest schema version. Locked to 1."
+    },
+    "saga_id": {
+      "type": "string",
+      "pattern": "^sg_[a-z0-9]{4,16}$",
+      "description": "Opaque short identifier (sg_<hex>) — used in dispatch-run records to associate per-repo saga steps with this swarm."
+    },
+    "mode": {
+      "type": "string",
+      "enum": ["autopilot", "checkpoint", "interactive"],
+      "description": "Conductor intervention mode. v0.20.0 ships autopilot + checkpoint; interactive reserved for v0.20.x."
+    },
+    "initiative": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9-]*$",
+      "description": "Slug of the cross-repo initiative this swarm advances. Must reference a real <eco>/initiatives/NNNN-<slug>.md."
+    },
+    "created": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO-8601 timestamp the swarm was started."
+    },
+    "ecosystem": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9-]*$",
+      "description": "Ecosystem name (mirrors ecosystem.json name). Defensive copy — lets a swarm survive an ecosystem rename without losing context."
+    },
+    "repos": {
+      "type": "object",
+      "minProperties": 1,
+      "description": "Per-repo swarm state, keyed by ecosystem member id.",
+      "patternProperties": {
+        "^[a-z][a-z0-9-]*$": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["wave", "status", "phase_slug", "branch", "owner"],
+          "properties": {
+            "wave": {
+              "type": "integer",
+              "minimum": 1,
+              "description": "Wave index this repo is assigned to. Computed from ecosystem.json dependency edges at start; immutable per swarm."
+            },
+            "status": {
+              "type": "string",
+              "enum": ["queued", "running", "blocked", "complete", "failed", "cancelled"],
+              "description": "Current execution status. Materialized into board.json."
+            },
+            "phase_slug": {
+              "type": "string",
+              "pattern": "^phase-[0-9]+(?:[a-z])?-[a-z][a-z0-9-]*$",
+              "description": "The phase directory slug inside this repo (e.g. phase-3-user-auth). The supervisor's /start-phase loop drives this phase."
+            },
+            "branch": {
+              "type": "string",
+              "minLength": 1,
+              "description": "Git branch the supervisor commits to in this repo. Defaults to phase-N-<slug>."
+            },
+            "owner": {
+              "type": "string",
+              "minLength": 1,
+              "description": "Session id (UUID-like) currently authoritative for this repo. Portability hook — Phase 17.5 lights up lease enforcement."
+            },
+            "lease_expires_at": {
+              "type": "string",
+              "format": "date-time",
+              "description": "When the current owner's lease expires. Conductor renews each turn. Phase 17.5 enforces; v0.20.0 audits only."
+            },
+            "lease_renewed_at": {
+              "type": "string",
+              "format": "date-time",
+              "description": "Last time the owner refreshed the lease. Conductor writes each conductor turn for repos it owns."
+            },
+            "claimed_by_session": {
+              "type": "string",
+              "minLength": 1,
+              "description": "Session UUID that holds the active claim. Mirrors brief frontmatter claimed_by_session."
+            },
+            "last_seen_sha": {
+              "type": "string",
+              "pattern": "^[0-9a-f]{7,40}$",
+              "description": "Last HEAD SHA the conductor observed for this repo. Cheap revalidation: if rev-parse HEAD matches, cache is fresh."
+            },
+            "tasks_done": {
+              "type": "integer",
+              "minimum": 0,
+              "description": "Number of supervisor checklist items completed."
+            },
+            "tasks_total": {
+              "type": "integer",
+              "minimum": 0,
+              "description": "Total checklist size at supervisor spawn time."
+            },
+            "tokens_used": {
+              "type": "integer",
+              "minimum": 0,
+              "description": "Output tokens spent by this supervisor (approximate, supervisor-reported)."
+            },
+            "tokens_budget": {
+              "type": "integer",
+              "minimum": 1,
+              "description": "Hard cap on supervisor output tokens. /swarm budget extends. Default 300000."
+            },
+            "inbox_count": {
+              "type": "integer",
+              "minimum": 0,
+              "description": "Count of unresolved inbox items written by this supervisor."
+            },
+            "commits": {
+              "type": "integer",
+              "minimum": 0,
+              "description": "Number of git commits the supervisor has pushed on its branch."
+            },
+            "current_task": {
+              "type": "string",
+              "description": "Free-form label of what the supervisor is working on right now."
+            },
+            "waiting_on": {
+              "type": "array",
+              "items": {"type": "string", "pattern": "^[a-z][a-z0-9-]*$"},
+              "description": "Member ids this repo's supervisor is blocked on. Used in board.json rendering for queued repos."
+            },
+            "contract_refs": {
+              "type": "array",
+              "items": {"type": "string"},
+              "description": "Contract surfaces this repo produces or consumes — slugs that resolve to contracts/<slug>.contract.json."
+            }
+          }
+        }
+      },
+      "additionalProperties": false
+    },
+    "waves": {
+      "type": "array",
+      "minItems": 1,
+      "description": "Ordered wave plan. Each entry lists the member ids in that wave. Waves execute sequentially; repos within a wave run in parallel.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["index", "repos"],
+        "properties": {
+          "index": {"type": "integer", "minimum": 1},
+          "repos": {
+            "type": "array",
+            "minItems": 1,
+            "items": {"type": "string", "pattern": "^[a-z][a-z0-9-]*$"}
+          },
+          "status": {
+            "type": "string",
+            "enum": ["queued", "running", "complete", "cancelled"]
+          },
+          "checkpoint_resolved_at": {
+            "type": "string",
+            "format": "date-time",
+            "description": "When the user approved the wave checkpoint (checkpoint mode). Null/missing in autopilot."
+          }
+        }
+      }
+    },
+    "sessions": {
+      "type": "array",
+      "description": "Registry of every conductor session that has touched this swarm. Portability hook — Phase 17.5 uses for join/absorb.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["session_id", "first_seen"],
+        "properties": {
+          "session_id": {"type": "string", "minLength": 1},
+          "first_seen": {"type": "string", "format": "date-time"},
+          "last_seen": {"type": "string", "format": "date-time"}
+        }
+      }
+    },
+    "contracts": {
+      "type": "array",
+      "description": "Cross-repo contract surfaces pinned at start. Each references contracts/<surface>.contract.json. Mismatches at wave boundaries block the next wave.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["surface", "owner", "consumers", "version"],
+        "properties": {
+          "surface": {"type": "string", "pattern": "^[a-z][a-z0-9-]*$"},
+          "owner": {"type": "string", "pattern": "^[a-z][a-z0-9-]*$"},
+          "consumers": {
+            "type": "array",
+            "items": {"type": "string", "pattern": "^[a-z][a-z0-9-]*$"}
+          },
+          "version": {"type": "integer", "minimum": 1},
+          "content_hash": {"type": "string", "pattern": "^[0-9a-f]{8,64}$"}
+        }
+      }
+    },
+    "audit": {
+      "type": "array",
+      "description": "Append-only audit log: /swarm tell, /swarm broadcast, /swarm budget, /swarm cancel, /swarm verify events. Materialized into board.json as recent_activity.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["ts", "actor", "event"],
+        "properties": {
+          "ts": {"type": "string", "format": "date-time"},
+          "actor": {"type": "string", "minLength": 1},
+          "event": {
+            "type": "string",
+            "enum": ["start", "tell", "broadcast", "budget", "cancel", "verify", "checkpoint", "complete", "resume", "wave-transition", "inbox-resolved", "contract-bump", "claim", "release", "focus", "join", "absorb", "lease-takeover"]
+          },
+          "repo": {"type": "string", "pattern": "^[a-z][a-z0-9-]*$"},
+          "detail": {"type": "string"}
+        }
+      }
+    },
+    "status": {
+      "type": "string",
+      "enum": ["running", "paused", "complete", "cancelled", "failed"],
+      "description": "Overall swarm state. Derived from per-repo + wave statuses; materialized into board.json."
+    }
+  }
+}

package/core/swarm/schema/signal.schema.json

@@ -0,0 +1,61 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/LiminaLabsAI/momentum/schemas/swarm-signal-v1.json",
+  "title": "Momentum Swarm Signal",
+  "description": "Typed cross-session message in a swarm's signals/ directory. One file per signal at <eco>/swarms/<id>/signals/NNNN-<type>-<slug>.json. Writes are mkdir-locked. Read once and archived to signals/processed/. Phase 17.5 portability protocol.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["signal_id", "version", "type", "ts", "from_session"],
+  "properties": {
+    "signal_id": {
+      "type": "string",
+      "pattern": "^[0-9]{4}-(focus-request|claim-request|absorb-proposed|lease-expired)-[a-z0-9][a-z0-9-]*$",
+      "description": "Zero-padded NNNN-<type>-<slug>. Matches the on-disk filename minus extension."
+    },
+    "version": {
+      "type": "integer",
+      "const": 1,
+      "description": "Schema version. Locked to 1."
+    },
+    "type": {
+      "type": "string",
+      "enum": ["focus-request", "claim-request", "absorb-proposed", "lease-expired"],
+      "description": "Signal kind. Drives conductor poller branching."
+    },
+    "ts": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO-8601 timestamp the signal was written."
+    },
+    "from_session": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Session id that wrote the signal."
+    },
+    "to_session": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Optional target session id. Null/missing = broadcast to all conductors that poll."
+    },
+    "repo": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9-]*$",
+      "description": "Ecosystem member id this signal concerns. Required for focus-request / claim-request / lease-expired."
+    },
+    "token": {
+      "type": "string",
+      "pattern": "^[0-9a-f]{16}$",
+      "description": "Transfer token id (16-hex). Set on focus-request when a token has been issued for the receiver to consume."
+    },
+    "source_swarm": {
+      "type": "string",
+      "pattern": "^[0-9]{4}-[a-z][a-z0-9-]*$",
+      "description": "Other swarm id being proposed for absorb. Required for absorb-proposed."
+    },
+    "detail": {
+      "type": "string",
+      "maxLength": 2000,
+      "description": "Optional human-readable note. Surfaced in conductor's poll output."
+    }
+  }
+}

package/core/swarm/signals.js

@@ -0,0 +1,296 @@
+'use strict';
+
+/**
+ * Swarm signal protocol — typed cross-session messages.
+ *
+ * Phase 17.5 lights up the `signals/` directory reserved in v0.20.0.
+ * Each signal is one file at `<eco>/swarms/<id>/signals/NNNN-<type>-<slug>.json`.
+ * The conductor polls the directory each turn, surfaces unprocessed
+ * signals, and on processing moves the file to `signals/processed/`.
+ *
+ * Types:
+ *   - focus-request    issued by `/swarm focus <repo>`; receiver consumes the token via `/swarm join --token`
+ *   - claim-request    issued by `/swarm claim <repo>` when the requester doesn't yet hold the lease
+ *   - absorb-proposed  issued by `/swarm absorb` before performing the merge — gives the other conductor a chance to see it
+ *   - lease-expired    issued by enforcement when a write was rejected against an expired lease
+ *
+ * Concurrency: writes use the same mkdir-lock pattern as manifest.js +
+ * inbox.js. Filenames embed the signal type so the poller can branch
+ * without reading bodies.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const manifestLib = require('./lib/manifest');
+
+const SIGNALS_DIR = 'signals';
+const PROCESSED_DIR = 'processed';
+const INDEX_FILENAME = 'INDEX.md';
+
+const VALID_TYPES = Object.freeze([
+  'focus-request',
+  'claim-request',
+  'absorb-proposed',
+  'lease-expired',
+]);
+
+const SLUG = /^[a-z0-9][a-z0-9-]*$/;
+const TYPE_ALT = VALID_TYPES.join('|');
+const FILENAME = new RegExp(`^(\\d{4})-(${TYPE_ALT})-([a-z0-9][a-z0-9-]*)\\.json$`);
+const SIGNAL_ID = new RegExp(`^[0-9]{4}-(?:${TYPE_ALT})-[a-z0-9][a-z0-9-]*$`);
+const TOKEN_HEX = /^[0-9a-f]{16}$/;
+const SWARM_ID = /^[0-9]{4}-[a-z][a-z0-9-]*$/;
+const ISO_DATETIME = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:?\d{2})$/;
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Path helpers
+// ─────────────────────────────────────────────────────────────────────────────
+
+function signalsDir(ecosystemRoot, swarmId) {
+  return path.join(manifestLib.swarmDir(ecosystemRoot, swarmId), SIGNALS_DIR);
+}
+
+function processedDir(ecosystemRoot, swarmId) {
+  return path.join(signalsDir(ecosystemRoot, swarmId), PROCESSED_DIR);
+}
+
+function indexPath(ecosystemRoot, swarmId) {
+  return path.join(signalsDir(ecosystemRoot, swarmId), INDEX_FILENAME);
+}
+
+function ensureLayout(ecosystemRoot, swarmId) {
+  manifestLib.ensureSwarmLayout(ecosystemRoot, swarmId);
+  fs.mkdirSync(processedDir(ecosystemRoot, swarmId), { recursive: true });
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Validation
+// ─────────────────────────────────────────────────────────────────────────────
+
+function validateSignal(obj) {
+  const errors = [];
+  const push = (p, m) => errors.push({ path: p, message: m });
+
+  if (obj === null || typeof obj !== 'object' || Array.isArray(obj)) {
+    return { ok: false, errors: [{ path: '$', message: 'signal must be a JSON object' }] };
+  }
+
+  if (typeof obj.signal_id !== 'string' || !SIGNAL_ID.test(obj.signal_id)) {
+    push('$.signal_id', 'must match /^[0-9]{4}-<type>-[a-z0-9][a-z0-9-]*$/');
+  }
+  if (obj.version !== 1) push('$.version', 'must be the integer 1');
+  if (!VALID_TYPES.includes(obj.type)) {
+    push('$.type', `must be one of: ${VALID_TYPES.join(', ')}`);
+  }
+  if (typeof obj.ts !== 'string' || !ISO_DATETIME.test(obj.ts)) {
+    push('$.ts', 'must be ISO-8601 date-time');
+  }
+  if (typeof obj.from_session !== 'string' || obj.from_session.length === 0) {
+    push('$.from_session', 'required non-empty string');
+  }
+  if (obj.to_session !== undefined && (typeof obj.to_session !== 'string' || obj.to_session.length === 0)) {
+    push('$.to_session', 'must be non-empty string when present');
+  }
+  if (obj.repo !== undefined && (typeof obj.repo !== 'string' || !SLUG.test(obj.repo))) {
+    push('$.repo', 'must match /^[a-z0-9][a-z0-9-]*$/ when present');
+  }
+  if (obj.token !== undefined && (typeof obj.token !== 'string' || !TOKEN_HEX.test(obj.token))) {
+    push('$.token', 'must be 16-hex when present');
+  }
+  if (obj.source_swarm !== undefined && (typeof obj.source_swarm !== 'string' || !SWARM_ID.test(obj.source_swarm))) {
+    push('$.source_swarm', 'must match swarm-id pattern when present');
+  }
+  if (obj.detail !== undefined && typeof obj.detail !== 'string') {
+    push('$.detail', 'must be string when present');
+  }
+
+  // Per-type required fields
+  if (obj.type === 'focus-request' || obj.type === 'claim-request' || obj.type === 'lease-expired') {
+    if (typeof obj.repo !== 'string') push('$.repo', `required for ${obj.type}`);
+  }
+  if (obj.type === 'absorb-proposed') {
+    if (typeof obj.source_swarm !== 'string') push('$.source_swarm', 'required for absorb-proposed');
+  }
+
+  return errors.length === 0 ? { ok: true } : { ok: false, errors };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// ID generation
+// ─────────────────────────────────────────────────────────────────────────────
+
+function nextSignalId(ecosystemRoot, swarmId) {
+  ensureLayout(ecosystemRoot, swarmId);
+  let max = 0;
+  const scan = (dir) => {
+    if (!fs.existsSync(dir)) return;
+    for (const name of fs.readdirSync(dir)) {
+      const m = name.match(FILENAME);
+      if (m) {
+        const n = parseInt(m[1], 10);
+        if (n > max) max = n;
+      }
+    }
+  };
+  scan(signalsDir(ecosystemRoot, swarmId));
+  scan(processedDir(ecosystemRoot, swarmId));
+  return String(max + 1).padStart(4, '0');
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Write
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Write a typed signal. Returns { signal_id, filePath }.
+ *
+ * @param {object} args
+ * @param {string} args.ecosystemRoot
+ * @param {string} args.swarmId
+ * @param {string} args.type            one of VALID_TYPES
+ * @param {string} args.slug            kebab slug (used in filename + signal_id)
+ * @param {string} args.fromSession     issuing session id
+ * @param {string} args.nowIso          ISO timestamp
+ * @param {string} [args.toSession]
+ * @param {string} [args.repo]
+ * @param {string} [args.token]
+ * @param {string} [args.sourceSwarm]
+ * @param {string} [args.detail]
+ */
+function writeSignal(args) {
+  const {
+    ecosystemRoot, swarmId, type, slug, fromSession, nowIso,
+    toSession, repo, token, sourceSwarm, detail,
+  } = args;
+  if (!VALID_TYPES.includes(type)) {
+    throw new TypeError(`writeSignal: invalid type ${JSON.stringify(type)}`);
+  }
+  if (typeof slug !== 'string' || !SLUG.test(slug)) {
+    throw new TypeError(`writeSignal: invalid slug ${JSON.stringify(slug)}`);
+  }
+  ensureLayout(ecosystemRoot, swarmId);
+  const id = nextSignalId(ecosystemRoot, swarmId);
+  const signalId = `${id}-${type}-${slug}`;
+  const filePath = path.join(signalsDir(ecosystemRoot, swarmId), `${signalId}.json`);
+
+  const payload = {
+    signal_id: signalId,
+    version: 1,
+    type,
+    ts: nowIso,
+    from_session: fromSession,
+  };
+  if (toSession) payload.to_session = toSession;
+  if (repo) payload.repo = repo;
+  if (token) payload.token = token;
+  if (sourceSwarm) payload.source_swarm = sourceSwarm;
+  if (detail) payload.detail = detail;
+
+  const v = validateSignal(payload);
+  if (!v.ok) {
+    const summary = v.errors.map((e) => `  ${e.path}: ${e.message}`).join('\n');
+    throw new Error(`writeSignal: validation failed:\n${summary}`);
+  }
+
+  manifestLib.withLock(filePath, () => {
+    fs.writeFileSync(filePath, JSON.stringify(payload, null, 2) + '\n', 'utf8');
+  });
+  rebuildIndex(ecosystemRoot, swarmId);
+  return { signal_id: signalId, filePath };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Read / poll
+// ─────────────────────────────────────────────────────────────────────────────
+
+function readSignal(filePath) {
+  const raw = fs.readFileSync(filePath, 'utf8');
+  return JSON.parse(raw);
+}
+
+/**
+ * List unprocessed signals (excluding processed/). Optionally filter by
+ * `type` and/or `toSession` (broadcast signals — those without
+ * `to_session` — always match).
+ */
+function listPendingSignals(ecosystemRoot, swarmId, opts = {}) {
+  const dir = signalsDir(ecosystemRoot, swarmId);
+  if (!fs.existsSync(dir)) return [];
+  const wantType = opts.type;
+  const wantSession = opts.toSession;
+  const out = [];
+  for (const name of fs.readdirSync(dir)) {
+    const m = name.match(FILENAME);
+    if (!m) continue;
+    const filePath = path.join(dir, name);
+    let body;
+    try { body = readSignal(filePath); } catch (_e) { continue; }
+    if (wantType && body.type !== wantType) continue;
+    if (wantSession && body.to_session && body.to_session !== wantSession) continue;
+    out.push({ ...body, filePath });
+  }
+  out.sort((a, b) => a.signal_id.localeCompare(b.signal_id));
+  return out;
+}
+
+/**
+ * Move a signal file to processed/. Idempotent — if already in
+ * processed/, returns silently.
+ */
+function markProcessed(ecosystemRoot, swarmId, signalId) {
+  ensureLayout(ecosystemRoot, swarmId);
+  const dir = signalsDir(ecosystemRoot, swarmId);
+  const fromPath = path.join(dir, `${signalId}.json`);
+  const toPath = path.join(processedDir(ecosystemRoot, swarmId), `${signalId}.json`);
+  if (!fs.existsSync(fromPath)) {
+    if (fs.existsSync(toPath)) return { signalId, processedPath: toPath };
+    throw new Error(`markProcessed: signal ${signalId} not found`);
+  }
+  manifestLib.withLock(fromPath, () => {
+    fs.renameSync(fromPath, toPath);
+  });
+  rebuildIndex(ecosystemRoot, swarmId);
+  return { signalId, processedPath: toPath };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// INDEX
+// ─────────────────────────────────────────────────────────────────────────────
+
+function rebuildIndex(ecosystemRoot, swarmId) {
+  ensureLayout(ecosystemRoot, swarmId);
+  const items = listPendingSignals(ecosystemRoot, swarmId);
+  const lines = ['# Signals — pending', ''];
+  if (items.length === 0) {
+    lines.push('_(no pending signals)_');
+  } else {
+    lines.push('| ID | Type | Repo | From | To | Token |');
+    lines.push('|----|------|------|------|----|-------|');
+    for (const it of items) {
+      lines.push(
+        `| ${it.signal_id} | ${it.type} | ${it.repo || '—'} | ${it.from_session} | ${it.to_session || '*'} | ${it.token || '—'} |`
+      );
+    }
+  }
+  lines.push('');
+  fs.writeFileSync(indexPath(ecosystemRoot, swarmId), lines.join('\n'), 'utf8');
+}
+
+module.exports = {
+  SIGNALS_DIR,
+  PROCESSED_DIR,
+  INDEX_FILENAME,
+  VALID_TYPES,
+  signalsDir,
+  processedDir,
+  indexPath,
+  ensureLayout,
+  validateSignal,
+  nextSignalId,
+  writeSignal,
+  readSignal,
+  listPendingSignals,
+  markProcessed,
+  rebuildIndex,
+};