@limina-labs/momentum 0.30.2

package/core/swarm/inbox.js

@@ -0,0 +1,222 @@
+'use strict';
+
+/**
+ * Swarm inbox protocol.
+ *
+ * Supervisors write `<eco>/swarms/<id>/inbox/NNNN-<slug>.md` when they
+ * need a user decision they can't make alone. The conductor surfaces
+ * these per turn and resolves them interactively. After resolution the
+ * item is moved to `inbox/resolved/` (preserved for audit) and the
+ * INDEX is regenerated.
+ *
+ * Numbering: monotonic across the swarm's lifetime, including
+ * resolved. Filename: `NNNN-<slug>.md` matching the regex
+ * `/^\d{4}-[a-z][a-z0-9-]*\.md$/`.
+ *
+ * Concurrency: writes use the same mkdir-lock as manifest.js.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const manifestLib = require('./lib/manifest');
+
+const INBOX_DIR = 'inbox';
+const RESOLVED_DIR = 'resolved';
+const INDEX_FILENAME = 'INDEX.md';
+
+const FILENAME = /^(\d{4})-([a-z][a-z0-9-]*)\.md$/;
+
+function inboxDir(ecosystemRoot, swarmId) {
+  return path.join(manifestLib.swarmDir(ecosystemRoot, swarmId), INBOX_DIR);
+}
+
+function resolvedDir(ecosystemRoot, swarmId) {
+  return path.join(inboxDir(ecosystemRoot, swarmId), RESOLVED_DIR);
+}
+
+function indexPath(ecosystemRoot, swarmId) {
+  return path.join(inboxDir(ecosystemRoot, swarmId), INDEX_FILENAME);
+}
+
+function ensureLayout(ecosystemRoot, swarmId) {
+  manifestLib.ensureSwarmLayout(ecosystemRoot, swarmId);
+  fs.mkdirSync(resolvedDir(ecosystemRoot, swarmId), { recursive: true });
+}
+
+function nextInboxId(ecosystemRoot, swarmId) {
+  ensureLayout(ecosystemRoot, swarmId);
+  let max = 0;
+  for (const name of fs.readdirSync(inboxDir(ecosystemRoot, swarmId))) {
+    const m = name.match(FILENAME);
+    if (m) {
+      const n = parseInt(m[1], 10);
+      if (n > max) max = n;
+    }
+  }
+  for (const name of fs.readdirSync(resolvedDir(ecosystemRoot, swarmId))) {
+    const m = name.match(FILENAME);
+    if (m) {
+      const n = parseInt(m[1], 10);
+      if (n > max) max = n;
+    }
+  }
+  return String(max + 1).padStart(4, '0');
+}
+
+/**
+ * Supervisor-side write. Returns { id, slug, filePath }.
+ *
+ * @param {object} args
+ * @param {string} args.ecosystemRoot
+ * @param {string} args.swarmId
+ * @param {string} args.repo            ecosystem member id
+ * @param {string} args.slug            kebab slug summarizing the question
+ * @param {string} args.question        markdown body (full question)
+ * @param {string[]} [args.options]     optional structured choices (each one line)
+ * @param {string} args.nowIso
+ */
+function writeInboxItem(args) {
+  const { ecosystemRoot, swarmId, repo, slug, question, options = [], nowIso } = args;
+  if (typeof slug !== 'string' || !/^[a-z][a-z0-9-]*$/.test(slug)) {
+    throw new TypeError(`writeInboxItem: invalid slug ${JSON.stringify(slug)}`);
+  }
+  if (typeof question !== 'string' || question.length === 0) {
+    throw new TypeError('writeInboxItem: question required');
+  }
+  if (typeof repo !== 'string' || !/^[a-z][a-z0-9-]*$/.test(repo)) {
+    throw new TypeError(`writeInboxItem: invalid repo ${JSON.stringify(repo)}`);
+  }
+  ensureLayout(ecosystemRoot, swarmId);
+  const id = nextInboxId(ecosystemRoot, swarmId);
+  const filePath = path.join(inboxDir(ecosystemRoot, swarmId), `${id}-${slug}.md`);
+  const lines = [
+    `# ${id} — ${slug}`,
+    '',
+    `- Repo: \`${repo}\``,
+    `- Asked at: ${nowIso}`,
+    `- Status: pending`,
+    '',
+    '## Question',
+    '',
+    question.trim(),
+    '',
+  ];
+  if (options.length) {
+    lines.push('## Options');
+    lines.push('');
+    for (const o of options) lines.push(`- ${o}`);
+    lines.push('');
+  }
+  manifestLib.withLock(filePath, () => {
+    fs.writeFileSync(filePath, lines.join('\n'), 'utf8');
+  });
+
+  rebuildIndex(ecosystemRoot, swarmId);
+  return { id, slug, filePath };
+}
+
+/**
+ * Conductor-side: list pending items (excluding resolved/).
+ */
+function listPendingInboxItems(ecosystemRoot, swarmId) {
+  const dir = inboxDir(ecosystemRoot, swarmId);
+  if (!fs.existsSync(dir)) return [];
+  const items = [];
+  for (const name of fs.readdirSync(dir)) {
+    const m = name.match(FILENAME);
+    if (!m) continue;
+    const filePath = path.join(dir, name);
+    items.push(parseItemHeader(filePath, m[1], m[2]));
+  }
+  items.sort((a, b) => a.id.localeCompare(b.id));
+  return items;
+}
+
+function parseItemHeader(filePath, id, slug) {
+  const raw = fs.readFileSync(filePath, 'utf8');
+  const lines = raw.split('\n');
+  let repo = '';
+  let asked = '';
+  let status = 'pending';
+  for (const line of lines) {
+    let m;
+    if ((m = line.match(/^- Repo:\s*`([^`]+)`/))) repo = m[1];
+    else if ((m = line.match(/^- Asked at:\s*(.+)$/))) asked = m[1].trim();
+    else if ((m = line.match(/^- Status:\s*(.+)$/))) status = m[1].trim();
+  }
+  return { id, slug, repo, asked, status, filePath };
+}
+
+/**
+ * Conductor-side: resolve an item with the user's answer. Moves the
+ * file into resolved/ with the answer + ts appended.
+ */
+function resolveInboxItem(args) {
+  const { ecosystemRoot, swarmId, id, answer, nowIso } = args;
+  if (typeof id !== 'string' || !/^\d{4}$/.test(id)) {
+    throw new TypeError(`resolveInboxItem: invalid id ${JSON.stringify(id)}`);
+  }
+  if (typeof answer !== 'string' || answer.length === 0) {
+    throw new TypeError('resolveInboxItem: answer required');
+  }
+  ensureLayout(ecosystemRoot, swarmId);
+  const dir = inboxDir(ecosystemRoot, swarmId);
+  const match = fs.readdirSync(dir).find((n) => n.startsWith(`${id}-`) && n.endsWith('.md'));
+  if (!match) throw new Error(`resolveInboxItem: no pending inbox item ${id}`);
+  const fromPath = path.join(dir, match);
+  const toPath = path.join(resolvedDir(ecosystemRoot, swarmId), match);
+
+  const raw = fs.readFileSync(fromPath, 'utf8');
+  const updated =
+    raw.replace(/^- Status: pending\b/m, '- Status: resolved') +
+    `\n## Answer (resolved at ${nowIso})\n\n${answer.trim()}\n`;
+
+  manifestLib.withLock(fromPath, () => {
+    fs.writeFileSync(toPath, updated, 'utf8');
+    fs.unlinkSync(fromPath);
+  });
+  rebuildIndex(ecosystemRoot, swarmId);
+
+  manifestLib.appendAudit(ecosystemRoot, swarmId, {
+    ts: nowIso, actor: 'conductor', event: 'inbox-resolved',
+    detail: `${id} — ${answer.slice(0, 200)}`,
+  });
+  return { id, resolvedPath: toPath };
+}
+
+/**
+ * Regenerate inbox/INDEX.md from pending items. Cheap — runs on every
+ * write/resolve.
+ */
+function rebuildIndex(ecosystemRoot, swarmId) {
+  ensureLayout(ecosystemRoot, swarmId);
+  const items = listPendingInboxItems(ecosystemRoot, swarmId);
+  const lines = ['# Inbox — pending items', ''];
+  if (items.length === 0) {
+    lines.push('_(no pending items)_');
+  } else {
+    lines.push('| ID | Repo | Slug | Asked at |');
+    lines.push('|----|------|------|----------|');
+    for (const it of items) {
+      lines.push(`| ${it.id} | ${it.repo} | ${it.slug} | ${it.asked} |`);
+    }
+  }
+  lines.push('');
+  fs.writeFileSync(indexPath(ecosystemRoot, swarmId), lines.join('\n'), 'utf8');
+}
+
+module.exports = {
+  INBOX_DIR,
+  RESOLVED_DIR,
+  INDEX_FILENAME,
+  inboxDir,
+  resolvedDir,
+  indexPath,
+  ensureLayout,
+  nextInboxId,
+  writeInboxItem,
+  listPendingInboxItems,
+  resolveInboxItem,
+  rebuildIndex,
+};

package/core/swarm/join.js

@@ -0,0 +1,138 @@
+'use strict';
+
+/**
+ * /swarm join <swarm-id> — register a session with an existing swarm.
+ *
+ * Phase 17.5 portability primitive. Three call shapes:
+ *
+ *   join(swarmId, sessionId)
+ *     Registration only. Adds to sessions[] (idempotent — touch on
+ *     re-join), auto-renews any repos this session already owns.
+ *
+ *   join(swarmId, sessionId, { token })
+ *     Consume an opaque transfer token. If kind=focus, claim ONLY the
+ *     token's target_repo (FOCUSING sentinel allows takeover). If
+ *     kind=join, no automatic claim — equivalent to plain registration.
+ *
+ *   join(swarmId, sessionId, { claim: <repo> })
+ *     Explicit claim shortcut. Composes `manifestLib.updateManifestAsOwner`
+ *     on the named repo — bound by the same lease rules as `/swarm claim`.
+ *
+ * Returns: {
+ *   swarmId,
+ *   sessionId,
+ *   sessions: <new sessions[] array>,
+ *   claimed?: { repo, owner, lease_expires_at },
+ *   token?: <consumed token record>,
+ * }
+ *
+ * Throws on:
+ *   - swarm missing
+ *   - token missing / expired
+ *   - claim rejected (EOWNERSHIP propagates)
+ */
+
+const manifestLib = require('./lib/manifest');
+const tokensLib = require('./lib/tokens');
+const sessionsLib = require('./lib/sessions');
+const boardLib = require('./lib/board');
+
+const DEFAULT_LEASE_MS = 24 * 60 * 60 * 1000;
+
+function join(args) {
+  const {
+    ecosystemRoot, swarmId, sessionId, nowIso,
+    token: tokenStr, claim: claimRepo,
+    leaseMs = DEFAULT_LEASE_MS,
+  } = args;
+
+  if (typeof sessionId !== 'string' || sessionId.length === 0) {
+    throw new TypeError('join: sessionId required');
+  }
+  if (typeof nowIso !== 'string' || nowIso.length === 0) {
+    throw new TypeError('join: nowIso required');
+  }
+
+  const manifest = manifestLib.loadManifest(ecosystemRoot, swarmId);
+  if (!manifest) throw new Error(`join: swarm ${swarmId} not found at ${ecosystemRoot}`);
+
+  // 1. Register / touch session
+  sessionsLib.touchSession(ecosystemRoot, swarmId, sessionId, nowIso);
+
+  let claimed = null;
+  let consumedToken = null;
+  let claimTargetRepo = claimRepo || null;
+
+  // 2. Optional token consumption — may set claimTargetRepo
+  if (tokenStr) {
+    consumedToken = tokensLib.consumeToken(ecosystemRoot, swarmId, tokenStr, nowIso);
+    if (consumedToken.kind === 'focus') {
+      // Focus token narrows the claim to its target_repo
+      claimTargetRepo = consumedToken.target_repo;
+    }
+    // kind=join: no implicit claim, registration is enough
+  }
+
+  // 3. Optional / token-implied repo claim
+  if (claimTargetRepo) {
+    const expiresAt = isoFromMs(Date.parse(nowIso) + leaseMs);
+    manifestLib.updateManifestAsOwner({
+      ecosystemRoot, swarmId, sessionId, repo: claimTargetRepo, nowIso,
+      mutate: (m, decision) => {
+        const previousOwner = m.repos[claimTargetRepo].owner;
+        m.repos[claimTargetRepo].owner = sessionId;
+        m.repos[claimTargetRepo].claimed_by_session = sessionId;
+        m.repos[claimTargetRepo].lease_renewed_at = nowIso;
+        m.repos[claimTargetRepo].lease_expires_at = expiresAt;
+        if (!Array.isArray(m.audit)) m.audit = [];
+        m.audit.push({
+          ts: nowIso, actor: sessionId, event: 'claim', repo: claimTargetRepo,
+          detail: `${previousOwner} → ${sessionId} (via join${consumedToken ? ` --token kind=${consumedToken.kind}` : ''})`,
+        });
+        if (decision.expired) {
+          m.audit.push({
+            ts: nowIso, actor: sessionId, event: 'lease-takeover', repo: claimTargetRepo,
+            detail: `previous owner ${previousOwner} lease expired`,
+          });
+        }
+      },
+    });
+    claimed = { repo: claimTargetRepo, owner: sessionId, lease_expires_at: expiresAt };
+  }
+
+  // 4. Audit-log the join itself
+  manifestLib.appendAudit(ecosystemRoot, swarmId, {
+    ts: nowIso, actor: sessionId, event: 'join',
+    detail: tokenStr
+      ? `via token kind=${consumedToken.kind}${claimTargetRepo ? ` (claimed ${claimTargetRepo})` : ''}`
+      : (claimRepo ? `with --claim ${claimRepo}` : 'registration only'),
+  });
+
+  // 5. Auto-renew owned-repo leases. Pulls conductor.renewLeases without
+  //    requiring it as a hard dep — the conductor module does require
+  //    this file's siblings, so we lazy-require here to avoid cycles.
+  const conductor = require('./conductor');
+  conductor.renewLeases(ecosystemRoot, swarmId, sessionId, nowIso);
+
+  // 6. Refresh board
+  boardLib.refreshBoard(ecosystemRoot, swarmId, nowIso);
+
+  return {
+    swarmId,
+    sessionId,
+    sessions: sessionsLib.listSessions(ecosystemRoot, swarmId),
+    claimed,
+    token: consumedToken,
+  };
+}
+
+function isoFromMs(ms) {
+  // Match the same no-millis format `bin/swarm.js::nowIso()` produces so
+  // joined manifest timestamps look consistent across writers.
+  return new Date(ms).toISOString().replace(/\.\d+Z$/, 'Z');
+}
+
+module.exports = {
+  join,
+  DEFAULT_LEASE_MS,
+};

package/core/swarm/lib/board.js

@@ -0,0 +1,178 @@
+'use strict';
+
+/**
+ * Materialized board cache for swarms.
+ *
+ * Strategy A from the indexing design: the conductor reads ONLY
+ * board.json on most turns. Inputs: manifest.json + per-repo
+ * dispatch-run-NNN.json records. Output: board.json (≈1–3KB).
+ *
+ * Pre-rendered display strings keep the conductor stateless — no
+ * computation per turn. The materializer is invoked from any code path
+ * that mutates manifest or supervisor saga records.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const manifestLib = require('./manifest');
+
+const BOARD_FILENAME = 'board.json';
+
+function boardPath(ecosystemRoot, swarmId) {
+  return path.join(manifestLib.swarmDir(ecosystemRoot, swarmId), BOARD_FILENAME);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Render helpers
+// ─────────────────────────────────────────────────────────────────────────────
+
+function tasksDisplay(done, total) {
+  if (done == null && total == null) return '';
+  return `${done || 0}/${total || 0}`;
+}
+
+function tokensDisplay(used, budget) {
+  const k = (n) => `${Math.round((n || 0) / 1000)}k`;
+  if (used == null && budget == null) return '';
+  return `${k(used)}/${k(budget)}`;
+}
+
+function shortTs(iso) {
+  // "2026-06-12T17:42:11Z" → "17:42"
+  if (typeof iso !== 'string') return '';
+  const m = iso.match(/T(\d{2}):(\d{2})/);
+  return m ? `${m[1]}:${m[2]}` : '';
+}
+
+function deriveOverallStatus(manifest) {
+  const repos = Object.values(manifest.repos || {});
+  if (repos.length === 0) return 'running';
+  if (repos.every((r) => r.status === 'complete')) return 'complete';
+  if (repos.some((r) => r.status === 'failed')) return 'failed';
+  if (repos.every((r) => r.status === 'cancelled' || r.status === 'complete')
+      && repos.some((r) => r.status === 'cancelled')) {
+    return 'cancelled';
+  }
+  return manifest.status || 'running';
+}
+
+function activeWave(manifest) {
+  const waves = manifest.waves || [];
+  for (const w of waves) {
+    if (w.status === 'running') return w.index;
+  }
+  for (const w of waves) {
+    if (w.status === 'queued' || w.status === undefined) return w.index;
+  }
+  // All complete — return last wave's index
+  return waves.length ? waves[waves.length - 1].index : 1;
+}
+
+function inboxCount(ecosystemRoot, swarmId) {
+  const inboxDir = path.join(manifestLib.swarmDir(ecosystemRoot, swarmId), 'inbox');
+  if (!fs.existsSync(inboxDir)) return 0;
+  return fs.readdirSync(inboxDir)
+    .filter((n) => /^\d{4}-[a-z][a-z0-9-]*\.md$/.test(n))
+    .length;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Materialization
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Derive a board cache from manifest state. Pure function over manifest
+ * — disk reads are limited to the inbox dir for the count. `nowIso` is
+ * injected for determinism (the conductor passes current time; tests
+ * pass a fixed value).
+ */
+function materializeBoard(ecosystemRoot, swarmId, manifest, nowIso) {
+  if (!manifest || typeof manifest !== 'object') {
+    throw new TypeError('materializeBoard: manifest must be an object');
+  }
+  const board = {
+    swarm_id: manifest.swarm_id,
+    version: 1,
+    saga_id: manifest.saga_id,
+    mode: manifest.mode,
+    rendered_at: nowIso,
+    status: deriveOverallStatus(manifest),
+    active_wave: activeWave(manifest),
+    repos: [],
+    inbox_count: inboxCount(ecosystemRoot, swarmId),
+    recent_activity: [],
+  };
+
+  for (const [name, r] of Object.entries(manifest.repos || {})) {
+    const row = {
+      name,
+      wave: r.wave,
+      status: r.status,
+    };
+    if (r.tasks_done != null || r.tasks_total != null) {
+      row.tasks = tasksDisplay(r.tasks_done, r.tasks_total);
+    }
+    if (r.tokens_used != null || r.tokens_budget != null) {
+      row.tokens = tokensDisplay(r.tokens_used, r.tokens_budget);
+    }
+    if (r.commits != null) row.commits = r.commits;
+    if (r.current_task) row.current = r.current_task;
+    if (r.inbox_count != null) row.inbox_count = r.inbox_count;
+    if (Array.isArray(r.waiting_on) && r.waiting_on.length) {
+      row.waiting_on = r.waiting_on.join(', ');
+    }
+    board.repos.push(row);
+  }
+
+  if (Array.isArray(manifest.audit)) {
+    const tail = manifest.audit.slice(-10).reverse();
+    for (const a of tail) {
+      const msg = a.detail || a.event;
+      const entry = { ts: shortTs(a.ts), msg };
+      if (a.repo) entry.repo = a.repo;
+      board.recent_activity.push(entry);
+    }
+  }
+
+  return board;
+}
+
+function writeBoard(ecosystemRoot, swarmId, board) {
+  const file = boardPath(ecosystemRoot, swarmId);
+  manifestLib.ensureSwarmLayout(ecosystemRoot, swarmId);
+  return manifestLib.withLock(file, () => {
+    fs.writeFileSync(file, JSON.stringify(board, null, 2) + '\n', 'utf8');
+    return file;
+  });
+}
+
+function loadBoard(ecosystemRoot, swarmId) {
+  const file = boardPath(ecosystemRoot, swarmId);
+  if (!fs.existsSync(file)) return null;
+  return JSON.parse(fs.readFileSync(file, 'utf8'));
+}
+
+/**
+ * Convenience: materialize from current manifest + write atomically.
+ */
+function refreshBoard(ecosystemRoot, swarmId, nowIso) {
+  const manifest = manifestLib.loadManifest(ecosystemRoot, swarmId);
+  if (!manifest) throw new Error(`refreshBoard: no manifest for swarm ${swarmId}`);
+  const board = materializeBoard(ecosystemRoot, swarmId, manifest, nowIso);
+  writeBoard(ecosystemRoot, swarmId, board);
+  return board;
+}
+
+module.exports = {
+  BOARD_FILENAME,
+  boardPath,
+  materializeBoard,
+  writeBoard,
+  loadBoard,
+  refreshBoard,
+  deriveOverallStatus,
+  activeWave,
+  tasksDisplay,
+  tokensDisplay,
+};

package/core/swarm/lib/brief.js

@@ -0,0 +1,157 @@
+'use strict';
+
+/**
+ * Phase-brief frontmatter — swarm-context extension.
+ *
+ * A solo (non-swarm) phase brief has NO frontmatter — it's plain
+ * markdown beginning with `# Phase N — ...`. A swarm-member phase
+ * brief MAY have an optional YAML frontmatter block declaring its
+ * swarm context. The fields are:
+ *
+ *   swarm: NNNN-<slug>            # swarm directory name
+ *   wave: <integer>               # 1-based wave index
+ *   initiative: <slug>            # /eco/initiatives/<NNNN>-<slug>.md
+ *   claimed_by_session: <uuid>    # current owning session
+ *
+ * All four are optional individually — a brief with `swarm:` but no
+ * `wave:` is malformed and validation fails. Solo briefs (no
+ * frontmatter at all) are byte-shape-compatible with v0.19.0.
+ *
+ * This module is intentionally narrow: parseSwarmFrontmatter,
+ * serializeSwarmFrontmatter, validateSwarmFrontmatter,
+ * injectSwarmFrontmatter (rewrites an existing brief atomically). It
+ * does NOT duplicate the broader markdown parsing already in
+ * ecosystem/lib/initiative.js — it's a focused helper for the
+ * supervisor recipe + /validate.
+ */
+
+const fs = require('fs');
+
+const FENCE = '---';
+
+const SLUG = /^[a-z][a-z0-9-]*$/;
+const SWARM_ID = /^[0-9]{4}-[a-z][a-z0-9-]*$/;
+
+const SWARM_FIELDS = Object.freeze([
+  'swarm',
+  'wave',
+  'initiative',
+  'claimed_by_session',
+]);
+
+function parseSwarmFrontmatter(content) {
+  if (typeof content !== 'string') {
+    return { frontmatter: null, body: content == null ? '' : String(content) };
+  }
+  const trimmed = content.replace(/^/, '');
+  if (!trimmed.startsWith(FENCE)) {
+    return { frontmatter: null, body: content };
+  }
+  const lines = trimmed.split('\n');
+  let end = -1;
+  for (let i = 1; i < lines.length; i++) {
+    if (lines[i].trim() === FENCE) { end = i; break; }
+  }
+  if (end === -1) return { frontmatter: null, body: content };
+  const fm = {};
+  for (const raw of lines.slice(1, end)) {
+    const line = raw.trim();
+    if (!line || line.startsWith('#')) continue;
+    const colon = line.indexOf(':');
+    if (colon === -1) continue;
+    const key = line.slice(0, colon).trim();
+    let value = line.slice(colon + 1).trim();
+    if (value.startsWith('"') && value.endsWith('"')) {
+      value = value.slice(1, -1);
+    } else if (/^-?\d+$/.test(value)) {
+      value = parseInt(value, 10);
+    }
+    fm[key] = value;
+  }
+  const body = lines.slice(end + 1).join('\n').replace(/^\n+/, '');
+  return { frontmatter: fm, body };
+}
+
+function serializeSwarmFrontmatter(fm) {
+  const lines = [FENCE];
+  for (const key of SWARM_FIELDS) {
+    if (fm[key] === undefined || fm[key] === null) continue;
+    const v = fm[key];
+    if (typeof v === 'number') {
+      lines.push(`${key}: ${v}`);
+    } else {
+      const s = String(v);
+      lines.push(`${key}: ${s}`);
+    }
+  }
+  lines.push(FENCE);
+  return lines.join('\n') + '\n';
+}
+
+function validateSwarmFrontmatter(fm) {
+  const errors = [];
+  if (fm == null) return { ok: true }; // solo brief — no frontmatter required
+  if (typeof fm !== 'object' || Array.isArray(fm)) {
+    return { ok: false, errors: [{ path: '$', message: 'frontmatter must be an object' }] };
+  }
+
+  // If ANY swarm field is present, swarm + wave are both required (the
+  // pair locks the brief into a swarm context).
+  const present = SWARM_FIELDS.filter((k) => fm[k] !== undefined);
+  const anyPresent = present.length > 0;
+  if (anyPresent) {
+    if (typeof fm.swarm !== 'string' || !SWARM_ID.test(fm.swarm)) {
+      errors.push({ path: '$.swarm', message: 'required when any swarm field is set; must match NNNN-<slug>' });
+    }
+    if (!Number.isInteger(fm.wave) || fm.wave < 1) {
+      errors.push({ path: '$.wave', message: 'required when any swarm field is set; positive integer' });
+    }
+  }
+
+  if (fm.initiative !== undefined) {
+    if (typeof fm.initiative !== 'string' || !SLUG.test(fm.initiative)) {
+      errors.push({ path: '$.initiative', message: 'must be a slug' });
+    }
+  }
+  if (fm.claimed_by_session !== undefined) {
+    if (typeof fm.claimed_by_session !== 'string' || fm.claimed_by_session.length === 0) {
+      errors.push({ path: '$.claimed_by_session', message: 'must be a non-empty string' });
+    }
+  }
+
+  return errors.length === 0 ? { ok: true } : { ok: false, errors };
+}
+
+/**
+ * Atomically inject (or update) swarm frontmatter in an existing brief
+ * file. Preserves the body verbatim. Validates the merged frontmatter
+ * before writing.
+ *
+ * If the brief has no frontmatter, prepends a new block. If it already
+ * has frontmatter, merges (new keys override existing).
+ */
+function injectSwarmFrontmatter(filePath, swarmFields) {
+  if (typeof filePath !== 'string' || filePath.length === 0) {
+    throw new TypeError('injectSwarmFrontmatter: filePath required');
+  }
+  const exists = fs.existsSync(filePath);
+  const raw = exists ? fs.readFileSync(filePath, 'utf8') : '';
+  const { frontmatter, body } = parseSwarmFrontmatter(raw);
+  const merged = Object.assign({}, frontmatter || {}, swarmFields);
+  const v = validateSwarmFrontmatter(merged);
+  if (!v.ok) {
+    const summary = v.errors.map((e) => `  ${e.path}: ${e.message}`).join('\n');
+    throw new Error(`injectSwarmFrontmatter: validation failed:\n${summary}`);
+  }
+  const fmBlock = serializeSwarmFrontmatter(merged);
+  fs.writeFileSync(filePath, fmBlock + body, 'utf8');
+  return merged;
+}
+
+module.exports = {
+  SWARM_FIELDS,
+  parseSwarmFrontmatter,
+  serializeSwarmFrontmatter,
+  validateSwarmFrontmatter,
+  injectSwarmFrontmatter,
+};