kodelyth-ecc 1.5.10 → 1.7.1

package/tests/mcp/client.test.js

@@ -0,0 +1,113 @@
+// Tests for scripts/mcp/client.js — registry + connect helpers.
+// Uses the LOCAL Kodelyth MCP server itself as a real test target so we
+// exercise the full stdio handshake without needing external dependencies.
+'use strict';
+
+const test   = require('node:test');
+const assert = require('node:assert/strict');
+const fs     = require('fs');
+const os     = require('os');
+const path   = require('path');
+
+// Isolate the registry to a tmp dir so we don't pollute ~/.kodelyth.
+const TMP = fs.mkdtempSync(path.join(os.tmpdir(), 'kodelyth-mcp-client-'));
+process.env.KODELYTH_MCP_CLIENT_DIR = TMP;
+
+const C = require('../../scripts/mcp/client.js');
+
+const ROOT = path.join(__dirname, '..', '..');
+const LOCAL_SERVER = path.join(ROOT, 'scripts', 'mcp', 'server.js');
+
+// ── Registry tests (no SDK required) ─────────────────────────────────────────
+
+test('registry: starts empty', () => {
+  const reg = C.loadRegistry();
+  assert.deepEqual(reg.servers, {});
+  assert.deepEqual(C.listServers(), []);
+});
+
+test('registry: addServer persists with sane defaults', () => {
+  const spec = C.addServer({
+    name: 'self',
+    command: process.execPath,
+    args: [LOCAL_SERVER],
+    env: { TEST_VAR: '1' },
+    description: 'local self-test target',
+  });
+  assert.equal(spec.name, 'self');
+  assert.equal(spec.command, process.execPath);
+  assert.deepEqual(spec.args, [LOCAL_SERVER]);
+  assert.equal(spec.env.TEST_VAR, '1');
+  assert.ok(spec.added_at);
+
+  // Persisted to disk:
+  assert.ok(fs.existsSync(C.REGISTRY_FILE));
+  const onDisk = JSON.parse(fs.readFileSync(C.REGISTRY_FILE, 'utf8'));
+  assert.equal(onDisk.servers.self.name, 'self');
+});
+
+test('registry: rejects bad names', () => {
+  assert.throws(() => C.addServer({ name: '',         command: 'x' }));
+  assert.throws(() => C.addServer({ name: 'has space',command: 'x' }));
+  assert.throws(() => C.addServer({ name: 'self',     command: ''  }));
+});
+
+test('registry: getServer / listServers reflect adds + removes', () => {
+  C.addServer({ name: 'second', command: '/usr/bin/true', args: [] });
+  const list = C.listServers();
+  assert.equal(list.length, 2, `expected 2, got ${list.length}`);
+  const names = list.map(s => s.name).sort();
+  assert.deepEqual(names, ['second', 'self']);
+
+  assert.ok(C.getServer('self'));
+  assert.equal(C.getServer('not-real'), null);
+
+  assert.equal(C.removeServer('second'), true);
+  assert.equal(C.removeServer('second'), false); // already gone
+  assert.equal(C.listServers().length, 1);
+});
+
+// ── End-to-end: connect to local kodelyth MCP server and call tools ──────────
+// These tests require @modelcontextprotocol/sdk (optionalDependency).
+// Skip gracefully when it isn't installed (e.g. CI without optional deps).
+let hasSdk = false;
+try { require('@modelcontextprotocol/sdk/client/index.js'); hasSdk = true; } catch (_) {}
+
+test('client: connects to local kodelyth MCP server and lists tools', { skip: !hasSdk }, async () => {
+  // self is already registered from the earlier test (running in same file).
+  const out = await C.listTools('self');
+  assert.ok(out.tools.length > 0, 'expected at least one tool from local kodelyth server');
+  const names = new Set(out.tools.map(t => t.name));
+  assert.ok(names.has('catalog_stats'), 'catalog_stats tool must be exposed');
+  assert.ok(names.has('list_agents'),   'list_agents tool must be exposed');
+});
+
+test('client: callTool on local server returns a real result', { skip: !hasSdk }, async () => {
+  const out = await C.callTool('self', 'catalog_stats', {});
+  assert.ok(Array.isArray(out.content));
+  assert.equal(out.content[0].type, 'text');
+  const data = JSON.parse(out.content[0].text);
+  assert.ok(data.agents > 0);
+  assert.ok(data.skills > 0);
+  assert.ok(data.commands > 0);
+});
+
+test('client: listResources surfaces kodelyth:// URIs', { skip: !hasSdk }, async () => {
+  const out = await C.listResources('self');
+  assert.ok(out.resources.length > 0);
+  assert.ok(out.resources.every(r => r.uri.startsWith('kodelyth://')),
+    'every resource uri should start with kodelyth://');
+});
+
+test('client: listPrompts surfaces routing-rule', { skip: !hasSdk }, async () => {
+  const out = await C.listPrompts('self');
+  const names = new Set(out.prompts.map(p => p.name));
+  assert.ok(names.has('routing-rule'));
+});
+
+test('client: connect fails clearly for unregistered server', async () => {
+  await assert.rejects(
+    () => C.connect('this-was-never-registered'),
+    err => err.code === 'MCP_SERVER_NOT_REGISTERED'
+  );
+});

package/tests/mcp/resources-prompts.test.js

@@ -0,0 +1,70 @@
+// Tests for scripts/mcp/resources.js and scripts/mcp/prompts.js
+'use strict';
+
+const test   = require('node:test');
+const assert = require('node:assert/strict');
+
+const RES     = require('../../scripts/mcp/resources');
+const PROMPTS = require('../../scripts/mcp/prompts');
+
+test('resources.buildList returns agents/skills/commands/rules/bundles', () => {
+  const list = RES.buildList();
+  assert.ok(list.length > 200, `expected >200 resources, got ${list.length}`);
+  const schemes = new Set(list.map(r => r.uri.split('://')[1].split('/')[0]));
+  for (const expected of ['agents', 'skills', 'commands', 'rules', 'bundles']) {
+    assert.ok(schemes.has(expected), `missing resource bucket: ${expected}`);
+  }
+  for (const r of list.slice(0, 5)) {
+    assert.match(r.uri, /^kodelyth:\/\//);
+    assert.equal(r.mimeType, 'text/markdown');
+  }
+});
+
+test('resources.readResource returns body for a known agent', () => {
+  const out = RES.readResource('kodelyth://agents/debug-detective');
+  assert.ok(out.contents.length === 1);
+  assert.equal(out.contents[0].mimeType, 'text/markdown');
+  assert.match(out.contents[0].text, /debug-detective/);
+});
+
+test('resources.readResource rejects unknown URI scheme', () => {
+  assert.throws(() => RES.readResource('weird://foo/bar'));
+});
+
+test('resources.readResource rejects unknown name', () => {
+  assert.throws(() => RES.readResource('kodelyth://agents/no-such-agent'));
+});
+
+test('PROMPT_DEFINITIONS exposes routing-rule and overviews', () => {
+  const names = PROMPTS.PROMPT_DEFINITIONS.map(p => p.name);
+  for (const expected of [
+    'routing-rule',
+    'agents-overview',
+    'skills-overview',
+    'commands-overview',
+    'handoff-chains',
+    'devil-mode',
+  ]) {
+    assert.ok(names.includes(expected), `missing prompt: ${expected}`);
+  }
+});
+
+test('routing-rule prompt returns the full intent routing rule body', () => {
+  const out = PROMPTS.PROMPT_HANDLERS['routing-rule']();
+  assert.ok(out.messages.length === 1);
+  assert.equal(out.messages[0].role, 'user');
+  assert.match(out.messages[0].content.text, /Agent Intent Routing/);
+});
+
+test('agents-overview returns a summary of all agents', () => {
+  const out = PROMPTS.PROMPT_HANDLERS['agents-overview']();
+  const text = out.messages[0].content.text;
+  assert.match(text, /Kodelyth ECC — Agents/);
+  assert.match(text, /debug-detective/);
+});
+
+test('devil-mode prompt returns the parallel command body', () => {
+  const out = PROMPTS.PROMPT_HANDLERS['devil-mode']();
+  const text = out.messages[0].content.text;
+  assert.match(text, /devil-mode/i);
+});

package/tests/mcp/tools.test.js

@@ -0,0 +1,159 @@
+// Tests for scripts/mcp/tools.js — pure-function MCP tool handlers.
+'use strict';
+
+const test   = require('node:test');
+const assert = require('node:assert/strict');
+const fs     = require('fs');
+const os     = require('os');
+const path   = require('path');
+
+// Isolate the memory store to a tmp dir so capture/recall don't pollute
+// the user's real ~/.kodelyth/memory.
+const TMP = fs.mkdtempSync(path.join(os.tmpdir(), 'kodelyth-mcp-'));
+process.env.KODELYTH_MEMORY_DIR = TMP;
+
+// Load AFTER setting env so the memory store picks up the tmp dir.
+const T = require('../../scripts/mcp/tools');
+
+function parseJSON(toolResult) {
+  const text = toolResult.content[0].text;
+  return JSON.parse(text);
+}
+
+test('TOOL_DEFINITIONS exposes the expected tool surface', () => {
+  const names = T.TOOL_DEFINITIONS.map(t => t.name);
+  for (const expected of [
+    'route_intent',
+    'list_agents',
+    'list_skills',
+    'list_commands',
+    'list_rules',
+    'list_bundles',
+    'get_agent',
+    'get_skill',
+    'get_command',
+    'get_rule',
+    'get_bundle',
+    'recall_memory',
+    'capture_memory',
+    'memory_stats',
+    'catalog_stats',
+    'audit_skill_match',
+  ]) {
+    assert.ok(names.includes(expected), `missing tool: ${expected}`);
+  }
+  // Every tool has a handler entry.
+  for (const t of T.TOOL_DEFINITIONS) {
+    assert.equal(typeof T.TOOL_HANDLERS[t.name], 'function', `${t.name} handler missing`);
+    assert.ok(t.description && t.description.length > 5, `${t.name} description too short`);
+    assert.ok(t.inputSchema && t.inputSchema.type === 'object', `${t.name} inputSchema malformed`);
+  }
+});
+
+test('route_intent rejects empty message', () => {
+  const r = T.tool_route_intent({});
+  assert.ok(r.isError, 'must error on missing message');
+});
+
+test('route_intent surfaces a relevant agent for a debug task', () => {
+  const r = T.tool_route_intent({ message: 'i have a hard intermittent bug in production' });
+  const data = parseJSON(r);
+  assert.ok(Array.isArray(data.suggestions));
+  assert.ok(data.suggestions.length > 0, 'should produce at least one suggestion');
+});
+
+test('route_intent honours top_k', () => {
+  const r = T.tool_route_intent({ message: 'review this code for security and quality issues', top_k: 2 });
+  const data = parseJSON(r);
+  assert.ok(data.suggestions.length <= 2);
+});
+
+test('list_agents returns the full catalog', () => {
+  const r = T.tool_list_agents();
+  const data = parseJSON(r);
+  assert.ok(data.count >= 60);
+  assert.ok(Array.isArray(data.agents) && data.agents.length === data.count);
+});
+
+test('get_agent returns body for known agent', () => {
+  const r = T.tool_get_agent({ name: 'debug-detective' });
+  assert.ok(!r.isError);
+  assert.match(r.content[0].text, /^# Agent: debug-detective/);
+});
+
+test('get_agent errors on unknown agent', () => {
+  const r = T.tool_get_agent({ name: 'no-such-agent' });
+  assert.ok(r.isError);
+});
+
+test('get_command tolerates leading slash', () => {
+  const r = T.tool_get_command({ name: '/code-review' });
+  assert.ok(!r.isError);
+  assert.match(r.content[0].text, /^# Command: \/code-review/);
+});
+
+test('get_rule returns the intent routing rule', () => {
+  const r = T.tool_get_rule({ name: 'agent-intent-routing' });
+  assert.ok(!r.isError);
+  assert.match(r.content[0].text, /Agent Intent Routing/);
+});
+
+test('get_bundle returns red-team cheat sheet', () => {
+  const r = T.tool_get_bundle({ name: 'red-team' });
+  assert.ok(!r.isError);
+  assert.ok(r.content[0].text.length > 100);
+});
+
+test('catalog_stats returns counts', () => {
+  const r = T.tool_catalog_stats();
+  const s = parseJSON(r);
+  assert.ok(s.agents > 0 && s.skills > 0 && s.commands > 0);
+});
+
+test('audit_skill_match suggests at least one skill for an observability task', () => {
+  const r = T.tool_audit_skill_match({ task: 'add structured logging and tracing to a fastapi service' });
+  const data = parseJSON(r);
+  assert.ok(Array.isArray(data.suggestions));
+  assert.ok(data.suggestions.length > 0, 'expected at least one skill suggestion');
+});
+
+test('capture_memory + recall_memory roundtrip in isolated tmp store', () => {
+  // Pre-seed a few unrelated memories so BM25 IDF can rise above the store's
+  // default minScore floor (with N=1 IDF stays ~0.29 which is filtered out).
+  for (const seed of [
+    { problem: 'fix a flaky CI build on github actions',  approach: 'set timeout to 60s and retry once' },
+    { problem: 'wire up redis caching for product list',  approach: 'use 60s ttl plus stale-while-revalidate' },
+    { problem: 'migrate postgres timestamps to utc',       approach: 'add at::timestamptz coercion in alembic migration' },
+  ]) {
+    T.tool_capture_memory({ ...seed, tags: ['seed'], language: 'misc' });
+  }
+
+  const cap = T.tool_capture_memory({
+    problem:  'mcp test problem keyword splatzilla',
+    approach: 'documenting that capture_memory works end-to-end',
+    tags:     ['mcp', 'test'],
+    language: 'javascript',
+  });
+  assert.ok(!cap.isError, 'capture must succeed');
+  const capData = parseJSON(cap);
+  assert.ok(capData.id && typeof capData.id === 'string');
+  assert.ok(capData.captured_at);
+
+  const rec = T.tool_recall_memory({ query: 'splatzilla', limit: 3 });
+  assert.ok(!rec.isError);
+  const recData = parseJSON(rec);
+  assert.ok(recData.count >= 1, 'should recall the memory we just captured');
+  assert.equal(recData.memories[0].problem, 'mcp test problem keyword splatzilla');
+});
+
+test('capture_memory rejects missing required fields', () => {
+  const r = T.tool_capture_memory({ problem: 'only problem, no approach' });
+  assert.ok(r.isError);
+});
+
+test('memory_stats reflects at least one stored memory', () => {
+  const r = T.tool_memory_stats();
+  assert.ok(!r.isError);
+  const s = parseJSON(r);
+  assert.ok(typeof s === 'object');
+});

package/tests/replay/bundle.test.js

@@ -0,0 +1,181 @@
+// Tests for scripts/replay/bundle.js — pure read/write of session bundles.
+'use strict';
+
+const test   = require('node:test');
+const assert = require('node:assert/strict');
+const fs     = require('fs');
+const os     = require('os');
+const path   = require('path');
+
+const B = require('../../scripts/replay/bundle.js');
+
+function tmp() {
+  return fs.mkdtempSync(path.join(os.tmpdir(), 'kodelyth-bundle-'));
+}
+
+function seedSession(root, sessionName, workers) {
+  const sessionDir = path.join(root, sessionName);
+  fs.mkdirSync(sessionDir, { recursive: true });
+  for (const w of workers) {
+    const wdir = path.join(sessionDir, w.slug);
+    fs.mkdirSync(wdir);
+    fs.writeFileSync(path.join(wdir, 'task.md'),    w.task    || `# task for ${w.slug}`);
+    fs.writeFileSync(path.join(wdir, 'handoff.md'), w.handoff || `# handoff for ${w.slug}`);
+    fs.writeFileSync(path.join(wdir, 'status.md'),  w.status  || `# status for ${w.slug}\n- State: completed`);
+  }
+  return sessionDir;
+}
+
+// ── exportBundle ─────────────────────────────────────────────────────────────
+
+test('exportBundle: rejects missing session dir', () => {
+  assert.throws(() => B.exportBundle({ sessionDir: '/no/such/path' }), /not found/);
+});
+
+test('exportBundle: gathers task/handoff/status per worker', () => {
+  const root = tmp();
+  const dir = seedSession(root, 'swarm-test', [
+    { slug: 'security-reviewer', task: 'audit', handoff: 'found 3 issues', status: 'completed' },
+    { slug: 'code-reviewer',     task: 'review', handoff: 'all good',       status: 'completed' },
+  ]);
+  const bundle = B.exportBundle({ sessionDir: dir, sessionName: 'swarm-test', meta: { task: 'audit oauth', harness: 'claude' } });
+  assert.equal(bundle.schema, B.BUNDLE_SCHEMA);
+  assert.equal(bundle.session, 'swarm-test');
+  assert.equal(bundle.workers.length, 2);
+  assert.equal(bundle.meta.task, 'audit oauth');
+  // Sorted by slug:
+  assert.deepEqual(bundle.workers.map(w => w.slug), ['code-reviewer', 'security-reviewer']);
+  // Content preserved:
+  const sec = bundle.workers.find(w => w.slug === 'security-reviewer');
+  assert.equal(sec.task, 'audit');
+  assert.equal(sec.handoff, 'found 3 issues');
+});
+
+test('exportBundle: handles empty session dir gracefully', () => {
+  const root = tmp();
+  const empty = path.join(root, 'empty');
+  fs.mkdirSync(empty);
+  const bundle = B.exportBundle({ sessionDir: empty });
+  assert.equal(bundle.workers.length, 0);
+});
+
+// ── writeBundle / readBundle round-trip ──────────────────────────────────────
+
+test('writeBundle + readBundle: round-trips losslessly', () => {
+  const root = tmp();
+  const dir = seedSession(root, 's1', [{ slug: 'a' }, { slug: 'b' }]);
+  const bundle = B.exportBundle({ sessionDir: dir, meta: { task: 'foo' } });
+  const out = path.join(root, 'out.json');
+  B.writeBundle(bundle, out);
+
+  const reread = B.readBundle(out);
+  assert.equal(reread.session, bundle.session);
+  assert.equal(reread.workers.length, 2);
+  assert.equal(reread.meta.task, 'foo');
+});
+
+test('writeBundle: rejects bad schema', () => {
+  assert.throws(() => B.writeBundle({ schema: 'bogus' }, '/tmp/x.json'), /invalid schema/);
+});
+
+test('readBundle: rejects unknown schema', () => {
+  const root = tmp();
+  const out = path.join(root, 'bad.json');
+  fs.writeFileSync(out, JSON.stringify({ schema: 'not.kodelyth/v0', session: 'x', workers: [] }));
+  assert.throws(() => B.readBundle(out), /unsupported schema/);
+});
+
+test('readBundle: rejects empty workers', () => {
+  const root = tmp();
+  const out = path.join(root, 'empty.json');
+  fs.writeFileSync(out, JSON.stringify({ schema: B.BUNDLE_SCHEMA, session: 'x', workers: [] }));
+  assert.throws(() => B.readBundle(out), /non-empty array/);
+});
+
+// ── importBundle ─────────────────────────────────────────────────────────────
+
+test('importBundle: restores worker files into target dir', () => {
+  const root = tmp();
+  const dir = seedSession(root, 'src', [
+    { slug: 'a', task: 'task-a', handoff: 'handoff-a', status: 'status-a' },
+  ]);
+  const bundle = B.exportBundle({ sessionDir: dir });
+
+  const target = path.join(root, 'restored');
+  const out = B.importBundle(bundle, { targetDir: target });
+  assert.equal(out.targetDir, target);
+  assert.deepEqual(out.workers, ['a']);
+
+  assert.equal(fs.readFileSync(path.join(target, 'a', 'task.md'),    'utf8'), 'task-a');
+  assert.equal(fs.readFileSync(path.join(target, 'a', 'handoff.md'), 'utf8'), 'handoff-a');
+  assert.equal(fs.readFileSync(path.join(target, 'a', 'status.md'),  'utf8'), 'status-a');
+});
+
+test('importBundle: refuses to overwrite without flag', () => {
+  const root = tmp();
+  const dir = seedSession(root, 'src', [{ slug: 'a' }]);
+  const bundle = B.exportBundle({ sessionDir: dir });
+  const target = path.join(root, 'exists');
+  fs.mkdirSync(target);
+  assert.throws(() => B.importBundle(bundle, { targetDir: target }), /already exists/);
+});
+
+test('importBundle: overwrite=true replaces existing dir', () => {
+  const root = tmp();
+  const dir = seedSession(root, 'src', [{ slug: 'a', task: 'fresh' }]);
+  const bundle = B.exportBundle({ sessionDir: dir });
+  const target = path.join(root, 'exists');
+  fs.mkdirSync(target);
+  fs.writeFileSync(path.join(target, 'stale.txt'), 'leftover');
+
+  B.importBundle(bundle, { targetDir: target, overwrite: true });
+  assert.equal(fs.existsSync(path.join(target, 'stale.txt')), false);
+  assert.equal(fs.readFileSync(path.join(target, 'a', 'task.md'), 'utf8'), 'fresh');
+});
+
+// ── diffBundles ──────────────────────────────────────────────────────────────
+
+test('diffBundles: detects handoff changes', () => {
+  const root = tmp();
+  const a = B.exportBundle({ sessionDir: seedSession(root, 'a', [
+    { slug: 'x', handoff: 'aaa' }, { slug: 'y', handoff: 'shared' },
+  ]) });
+  const b = B.exportBundle({ sessionDir: seedSession(root, 'b', [
+    { slug: 'x', handoff: 'bbb' }, { slug: 'y', handoff: 'shared' },
+  ]) });
+  const d = B.diffBundles(a, b);
+  const x = d.find(r => r.slug === 'x');
+  const y = d.find(r => r.slug === 'y');
+  assert.equal(x.handoff_changed, true);
+  assert.equal(y.handoff_changed, false);
+});
+
+test('diffBundles: surfaces workers that exist on only one side', () => {
+  const root = tmp();
+  const a = B.exportBundle({ sessionDir: seedSession(root, 'a', [
+    { slug: 'only-a' }, { slug: 'shared' },
+  ]) });
+  const b = B.exportBundle({ sessionDir: seedSession(root, 'b', [
+    { slug: 'shared' }, { slug: 'only-b' },
+  ]) });
+  const d = B.diffBundles(a, b);
+  assert.equal(d.find(r => r.slug === 'only-a').in_a, true);
+  assert.equal(d.find(r => r.slug === 'only-a').in_b, false);
+  assert.equal(d.find(r => r.slug === 'only-b').in_b, true);
+  assert.equal(d.find(r => r.slug === 'only-b').in_a, false);
+});
+
+// ── nextReplayName ───────────────────────────────────────────────────────────
+
+test('nextReplayName: generates -replay-1 for fresh origin', () => {
+  assert.equal(B.nextReplayName('swarm-2026-05-10-4a'), 'swarm-2026-05-10-4a-replay-1');
+});
+
+test('nextReplayName: skips taken numbers', () => {
+  const taken = new Set(['swarm-x-replay-1', 'swarm-x-replay-2']);
+  assert.equal(B.nextReplayName('swarm-x', taken), 'swarm-x-replay-3');
+});
+
+test('nextReplayName: strips existing -replay-N suffix to find canonical base', () => {
+  assert.equal(B.nextReplayName('swarm-x-replay-3'), 'swarm-x-replay-1');
+});

package/tests/replay/replay.test.js

@@ -0,0 +1,131 @@
+// Tests for scripts/replay/replay.js — replay engine.
+'use strict';
+
+const test   = require('node:test');
+const assert = require('node:assert/strict');
+const path   = require('path');
+
+const R = require('../../scripts/replay/replay.js');
+const B = require('../../scripts/replay/bundle.js');
+const O = require('../../scripts/lib/tmux-worktree-orchestrator.js');
+
+const FAKE_BUNDLE = {
+  schema: B.BUNDLE_SCHEMA,
+  session: 'swarm-2026-05-10-4a',
+  exported_at: '2026-05-10T17:00:00Z',
+  exported_by: 'kodelyth-ecc@1.7.0',
+  meta: {
+    task: 'audit oauth flow for security regressions',
+    agents: ['security-reviewer', 'code-reviewer'],
+    harness: 'echo',
+    base_ref: 'HEAD',
+  },
+  workers: [
+    { slug: 'security-reviewer', task: '# task', handoff: '# handoff', status: '# status' },
+    { slug: 'code-reviewer',     task: '# task', handoff: '# handoff', status: '# status' },
+  ],
+};
+
+// ── extractTaskFromBundle ────────────────────────────────────────────────────
+
+test('extractTaskFromBundle: prefers meta.task when present', () => {
+  const t = R.extractTaskFromBundle(FAKE_BUNDLE);
+  assert.equal(t, 'audit oauth flow for security regressions');
+});
+
+test('extractTaskFromBundle: falls back to parsing first worker task.md (Shared Task)', () => {
+  const bundle = {
+    schema: B.BUNDLE_SCHEMA,
+    session: 's',
+    workers: [{
+      slug: 'a',
+      task: '# a — swarm task\n\nblah\n\n## Shared Task\n\nrefactor payments\n\n## Required handoff sections\n1. Summary',
+    }],
+    meta: {},
+  };
+  assert.equal(R.extractTaskFromBundle(bundle), 'refactor payments');
+});
+
+test('extractTaskFromBundle: falls back to orchestrator Objective block', () => {
+  const bundle = {
+    schema: B.BUNDLE_SCHEMA,
+    session: 's',
+    workers: [{
+      slug: 'a',
+      task: '# Worker Task\n\n## Objective\nfix the bug\n\n## Completion\nDo not spawn',
+    }],
+    meta: {},
+  };
+  assert.equal(R.extractTaskFromBundle(bundle), 'fix the bug');
+});
+
+test('extractTaskFromBundle: throws if no task can be recovered', () => {
+  const bundle = { schema: B.BUNDLE_SCHEMA, session: 's', workers: [], meta: {} };
+  assert.throws(() => R.extractTaskFromBundle(bundle), /cannot extract task/);
+});
+
+// ── buildReplayPlanConfig ────────────────────────────────────────────────────
+
+test('buildReplayPlanConfig: defaults to bundle.meta values', () => {
+  const cfg = R.buildReplayPlanConfig(FAKE_BUNDLE, { repoRoot: process.cwd() });
+  assert.equal(cfg._meta.task, 'audit oauth flow for security regressions');
+  assert.deepEqual(cfg._meta.pickedAgents, ['security-reviewer', 'code-reviewer']);
+  assert.match(cfg.sessionName, /^swarm-2026-05-10-4a-replay-1$/);
+  assert.equal(cfg.baseRef, 'HEAD');
+});
+
+test('buildReplayPlanConfig: --harness override flows to plan', () => {
+  const cfg = R.buildReplayPlanConfig(FAKE_BUNDLE, { repoRoot: process.cwd(), harness: 'echo' });
+  // Harness override is preserved in the planConfig._meta.
+  assert.equal(cfg._meta.harness, 'echo');
+});
+
+test('buildReplayPlanConfig: --agents override replaces bundle.meta.agents', () => {
+  const cfg = R.buildReplayPlanConfig(FAKE_BUNDLE, {
+    repoRoot: process.cwd(),
+    agents: ['supply-chain-auditor', 'prompt-injection-hunter'],
+  });
+  assert.deepEqual(cfg._meta.pickedAgents, ['supply-chain-auditor', 'prompt-injection-hunter']);
+});
+
+test('buildReplayPlanConfig: --base-ref override flows to plan', () => {
+  const cfg = R.buildReplayPlanConfig(FAKE_BUNDLE, { repoRoot: process.cwd(), baseRef: 'main' });
+  assert.equal(cfg.baseRef, 'main');
+});
+
+test('buildReplayPlanConfig: --session override wins over auto-naming', () => {
+  const cfg = R.buildReplayPlanConfig(FAKE_BUNDLE, {
+    repoRoot: process.cwd(),
+    sessionName: 'my-replay',
+  });
+  assert.equal(cfg.sessionName, 'my-replay');
+});
+
+test('buildReplayPlanConfig: takenSessions skips conflicting names', () => {
+  const taken = new Set(['swarm-2026-05-10-4a-replay-1', 'swarm-2026-05-10-4a-replay-2']);
+  const cfg = R.buildReplayPlanConfig(FAKE_BUNDLE, { repoRoot: process.cwd(), takenSessions: taken });
+  assert.equal(cfg.sessionName, 'swarm-2026-05-10-4a-replay-3');
+});
+
+test('buildReplayPlanConfig: produces a plan-config the orchestrator accepts', () => {
+  const cfg = R.buildReplayPlanConfig(FAKE_BUNDLE, { repoRoot: process.cwd() });
+  // Verify orchestrator can build a real plan from it.
+  const plan = O.buildOrchestrationPlan(cfg);
+  assert.equal(plan.workerPlans.length, 2);
+  assert.ok(plan.workerPlans.every(w => w.task.includes('audit oauth flow')));
+  assert.match(plan.sessionName, /-replay-/);
+});
+
+test('buildReplayPlanConfig: falls back to worker slugs when no meta.agents AND no override', () => {
+  const minimalBundle = {
+    schema: B.BUNDLE_SCHEMA,
+    session: 'minimal',
+    workers: [
+      { slug: 'a', task: '## Shared Task\n\ndo X\n\n## Required handoff sections\n' },
+      { slug: 'b', task: '## Shared Task\n\ndo X\n\n## Required handoff sections\n' },
+    ],
+    meta: {},
+  };
+  const cfg = R.buildReplayPlanConfig(minimalBundle, { repoRoot: process.cwd(), harness: 'echo' });
+  assert.deepEqual(cfg._meta.pickedAgents, ['a', 'b']);
+});