@polderlabs/bizar 10.5.0 → 10.7.0

package/bizar-dash/src/server/routes/loops.mjs

@@ -0,0 +1,138 @@
+/**
+ * src/server/routes/loops.mjs
+ *
+ * G-autoloop Phase 5 — HTTP surface for the loop runtime.
+ *
+ * Endpoints (mounted under `/api/loops`):
+ *   GET    /api/loops                  — snapshot of all known loops
+ *   GET    /api/loops/:id              — single loop state
+ *   POST   /api/loops                  — create a new pending loop
+ *   PATCH  /api/loops/:id              — patch fields (intervalMs, maxIterations, etc.)
+ *   POST   /api/loops/:id/start        — flip status to 'running' (idempotent)
+ *   POST   /api/loops/:id/stop         — flip status to 'stopped' (idempotent)
+ *   DELETE /api/loops/:id              — delete the state file
+ *
+ * The actual scheduling (in-process setInterval) happens in
+ * `loop-runtime.mjs`. This router owns only the HTTP wiring — keeps
+ * the runtime pure + testable.
+ *
+ * Phase 5 deliberately stops short of dispatching real tasks here.
+ * That's wired in a follow-up so we can ship the loop infrastructure
+ * (CRUD + scheduler) and let a dedicated route pair it with the real
+ * `taskDelegator` + project-store integration.
+ */
+
+import { Router } from 'express';
+import {
+  createLoop,
+  readLoop,
+  patchLoop,
+  deleteLoop,
+  listLoops,
+  snapshotLoops,
+  startLoop,
+  stopLoop,
+} from '../loop-runtime.mjs';
+import { wrap } from './_shared.mjs';
+
+const VALID_PATCH_FIELDS = new Set([
+  'name',
+  'intervalMs',
+  'maxIterations',
+  'projectId',
+]);
+
+/**
+ * @param {Object} deps
+ * @param {Function} [deps.broadcast]
+ */
+export function createLoopsRouter({ broadcast = () => {} } = {}) {
+  const router = Router();
+
+  router.get('/loops', wrap(async (req, res) => {
+    const snap = snapshotLoops();
+    res.json({ loops: Object.values(snap), count: Object.keys(snap).length });
+  }));
+
+  router.get('/loops/:id', wrap(async (req, res) => {
+    const s = readLoop(req.params.id);
+    if (!s) {
+      res.status(404).json({ error: 'not_found' });
+      return;
+    }
+    res.json(s);
+  }));
+
+  router.post('/loops', wrap(async (req, res) => {
+    const body = req.body || {};
+    if (!body.projectId) {
+      res.status(400).json({ error: 'bad_request', message: 'projectId required' });
+      return;
+    }
+    const s = createLoop({
+      projectId: body.projectId,
+      name: body.name,
+      intervalMs: body.intervalMs,
+      maxIterations: body.maxIterations,
+    });
+    broadcast({ type: 'loops:change', loop: s });
+    res.status(201).json(s);
+  }));
+
+  router.patch('/loops/:id', wrap(async (req, res) => {
+    const patch = {};
+    for (const [k, v] of Object.entries(req.body || {})) {
+      if (VALID_PATCH_FIELDS.has(k)) patch[k] = v;
+    }
+    const next = patchLoop(req.params.id, patch);
+    if (!next) {
+      res.status(404).json({ error: 'not_found' });
+      return;
+    }
+    broadcast({ type: 'loops:change', loop: next });
+    res.json(next);
+  }));
+
+  // Start a loop. The runtime owns the timer; this just flips state.
+  // We re-use `startLoop` from the runtime so the in-process scheduler
+  // is the single source of truth. If the caller passed a `dry` flag,
+  // we only flip the state without engaging the timer — useful for
+  // the dashboard's "arm only" toggle.
+  router.post('/loops/:id/start', wrap(async (req, res) => {
+    const dry = req.body && req.body.dry === true;
+    let next;
+    try {
+      next = dry ? patchLoop(req.params.id, { status: 'running' }) : startLoop(req.params.id, {});
+    } catch (err) {
+      res.status(404).json({ error: 'not_found', message: err.message });
+      return;
+    }
+    if (!next) {
+      res.status(404).json({ error: 'not_found' });
+      return;
+    }
+    broadcast({ type: 'loops:change', loop: next });
+    res.json(next);
+  }));
+
+  router.post('/loops/:id/stop', wrap(async (req, res) => {
+    const next = stopLoop(req.params.id);
+    if (!next) {
+      res.status(404).json({ error: 'not_found' });
+      return;
+    }
+    broadcast({ type: 'loops:change', loop: next });
+    res.json(next);
+  }));
+
+  router.delete('/loops/:id', wrap(async (req, res) => {
+    // Stop the in-process timer first so it doesn't keep firing on a
+    // deleted state.json.
+    stopLoop(req.params.id);
+    deleteLoop(req.params.id);
+    broadcast({ type: 'loops:deleted', loopId: req.params.id });
+    res.status(204).end();
+  }));
+
+  return router;
+}

package/bizar-dash/src/server/task-splitter.mjs

@@ -0,0 +1,241 @@
+/**
+ * src/server/task-splitter.mjs
+ *
+ * v10.6.0 — G-autoloop Phase 3. Task ordering + auto-splitting.
+ *
+ * The "best order" problem the user cares about has three pieces:
+ *
+ *   1. Order.    Which ready task should the loop pick next? Already
+ *                solved in `loop-runtime.mjs:pickReadyTasks` (priority
+ *                then age, dependencies gated on `done` status).
+ *
+ *   2. Size.     How big is each task? Operators want to know
+ *                "`tsk_abc` is L-sized" before they let the loop loose
+ *                on it. Size is a heuristic over title/description
+ *                length, presence of linked goal/KR, and historical
+ *                completion times.
+ *
+ *   3. Split.    Tasks tagged `size ∈ { L, XL }` get routed to the
+ *                `task-decomposer` agent, which returns 2-N smaller
+ *                tasks. The new tasks link back via `parentTaskId`
+ *                so progress aggregates up. The parent stays open
+ *                until all children are `done`.
+ *
+ * This module implements pure functions for (2) and (3). Splitting
+ * itself delegates to a caller-supplied `decompose` function so we
+ * don't bake an LLM call into the harness — that's the agent's job
+ * (per our architecture boundary: skills/MCP define agent behaviour,
+ * not the dash server).
+ */
+
+const SIZE_ORDER = ['S', 'M', 'L', 'XL'];
+
+/**
+ * Estimate a task's size bucket from its title, description, linked
+ * goals, and history. Heuristic, no LLM. Buckets: S, M, L, XL.
+ *
+ * Signals:
+ *   - title word count        : +0.2 per word over 6
+ *   - description char count  : +0.001 per char over 200
+ *   - linked goal/KR          : +1 size point each
+ *   - avg historical duration : +1 if > 2h, +2 if > 6h
+ *
+ * @param {Object} task
+ * @param {string} task.title
+ * @param {string} [task.description]
+ * @param {Object} [task.metadata]      may carry goalId/krId
+ * @param {Array}  [history]            prior tasks from this assignee;
+ *                                      we use title-length buckets and
+ *                                      avg `timeSpent` minutes as a
+ *                                      proxy for difficulty.
+ * @returns {'S'|'M'|'L'|'XL'}
+ */
+export function estimateSize(task, history = []) {
+  if (!task || typeof task !== 'object') return 'M';
+  const title = String(task.title || '');
+  const desc = String(task.description || '');
+  const meta = task.metadata || {};
+
+  let score = 0;
+  // Title length signal — every word over 6 adds 0.2 to the score.
+  const words = title.trim().split(/\s+/).filter(Boolean);
+  if (words.length > 6) score += (words.length - 6) * 0.2;
+
+  // Description length signal — chars over 200 add 0.001 each.
+  if (desc.length > 200) score += (desc.length - 200) * 0.001;
+
+  // Linked goal / KR — both count.
+  if (meta.goalId) score += 1;
+  if (meta.krId) score += 1;
+
+  // Historical signal — if prior similar-sized tasks took > 2h, push up.
+  const historicalMinutes = avgHistoricalMinutes(task, history);
+  if (historicalMinutes > 360) score += 2;      // > 6h
+  else if (historicalMinutes > 120) score += 1; // > 2h
+
+  return scoreToBucket(score);
+}
+
+function scoreToBucket(score) {
+  if (score < 0.5) return 'S';
+  if (score < 1.5) return 'M';
+  if (score < 3.0) return 'L';
+  return 'XL';
+}
+
+/**
+ * Average minutes spent on historical tasks that share at least 2
+ * title-words with the candidate. We treat very short histories
+ * (< 2 items) as unreliable and return 0.
+ *
+ * @param {Object} task
+ * @param {Array}  history
+ * @returns {number}
+ */
+export function avgHistoricalMinutes(task, history) {
+  if (!task || !Array.isArray(history) || history.length < 2) return 0;
+  const titleWords = new Set(
+    String(task.title || '').toLowerCase().split(/\s+/).filter((w) => w.length > 3),
+  );
+  if (titleWords.size === 0) return 0;
+  const similar = history.filter((h) => {
+    if (!h || !h.title) return false;
+    const hw = new Set(String(h.title).toLowerCase().split(/\s+/).filter((w) => w.length > 3));
+    let overlap = 0;
+    for (const w of titleWords) if (hw.has(w)) overlap++;
+    return overlap >= 2;
+  });
+  if (similar.length === 0) return 0;
+  let total = 0;
+  let count = 0;
+  for (const h of similar) {
+    const mins = Number(h.timeSpent) || 0;
+    if (mins > 0) {
+      total += mins;
+      count++;
+    }
+  }
+  return count > 0 ? total / count : 0;
+}
+
+/**
+ * Decide whether a task should be split. Threshold: `size ∈ { L, XL }`
+ * OR explicit `metadata.autoSplit === true`.
+ *
+ * @param {Object} task
+ * @param {Array}  [history]
+ * @returns {boolean}
+ */
+export function shouldSplit(task, history = []) {
+  if (!task) return false;
+  if (task.metadata && task.metadata.autoSplit === true) return true;
+  if (task.metadata && task.metadata.autoSplit === false) return false;
+  const size = estimateSize(task, history);
+  return size === 'L' || size === 'XL';
+}
+
+/**
+ * Plan a split. Returns the **call shape** the caller dispatches to a
+ * `task-decomposer` agent (LLM-step), plus the metadata that should
+ * be patched back onto the parent. The agent must return:
+ *
+ *   [{ title, description?, size?, priority? }, ...]      // 2..N tasks
+ *
+ * @param {Object} parent
+ * @returns {Object} plan
+ *   - kind: 'task-decompose'
+ *   - parentTaskId
+ *   - prompt: natural-language instruction for the agent
+ *   - constraints: { min: 2, max: 5 } — the agent may not exceed this
+ */
+export function planSplit(parent) {
+  if (!parent || !parent.id) throw new TypeError('planSplit: task id required');
+  const p = parent;
+  return {
+    kind: 'task-decompose',
+    parentTaskId: p.id,
+    prompt: [
+      `Break the following task into 2-5 smaller, independently-completable subtasks.`,
+      `Each subtask should be completable in under 30 minutes by a single subagent.`,
+      ``,
+      `Title: ${p.title || '(no title)'}`,
+      `Description: ${p.description || '(no description)'}`,
+      p.assignee ? `Original assignee: ${p.assignee}` : null,
+      p.metadata && p.metadata.goalId ? `Linked goal: ${p.metadata.goalId}` : null,
+    ].filter(Boolean).join('\n'),
+    constraints: { min: 2, max: 5 },
+  };
+}
+
+/**
+ * Validate a `task-decompose` response. Returns an array of task
+ * seeds (without ids — those are minted by the task store on create).
+ *
+ * @param {Array}  candidates
+ * @param {Object} [opts]
+ * @param {number} [opts.min=2]
+ * @param {number} [opts.max=5]
+ * @returns {Array} cleaned seeds, ready to be passed to `tasksStore.create`
+ */
+export function acceptSplit(candidates, { min = 2, max = 5 } = {}) {
+  if (!Array.isArray(candidates)) return [];
+  const out = [];
+  for (const c of candidates) {
+    if (!c || typeof c !== 'object') continue;
+    if (!c.title || typeof c.title !== 'string') continue;
+    out.push({
+      title: String(c.title).slice(0, 200),
+      description: c.description ? String(c.description).slice(0, 4000) : '',
+      priority: Number.isFinite(c.priority) ? c.priority : 5,
+      tags: Array.isArray(c.tags) ? c.tags.filter((t) => typeof t === 'string') : ['autosplit'],
+    });
+    if (out.length >= max) break;
+  }
+  if (out.length < min) return [];
+  return out;
+}
+
+/**
+ * Roll up child task progress into the parent's `metadata.progress`
+ * (0..1) and auto-complete the parent when all children are `done`.
+ *
+ * Pure function — the caller is responsible for writing back to the
+ * task store. Returns `{ ratio, allDone }`. If `parent` has no
+ * children array, returns `{ ratio: 0, allDone: false }`.
+ *
+ * @param {Object} parent
+ * @returns {Object}
+ */
+export function rollupProgress(parent) {
+  if (!parent) return { ratio: 0, allDone: false };
+  const children = Array.isArray(parent.subtasks) ? parent.subtasks : [];
+  if (children.length === 0) return { ratio: 0, allDone: false };
+  let done = 0;
+  for (const c of children) {
+    if (c && c.status === 'done') done++;
+  }
+  const ratio = done / children.length;
+  return { ratio, allDone: done === children.length };
+}
+
+/**
+ * Suggest a goal-aware priority bump. If a task links to a goal whose
+ * status is `at-risk` or `blocked`, bump its priority by 1; if `done`,
+ * drop the task to backlog. Pure helper; caller decides what to do
+ * with the result.
+ *
+ * @param {Object} task
+ * @param {Object} [goal]   parsed goal object (from progress-parser)
+ * @returns {{ priority: number, action: 'bump'|'drop'|'none' }}
+ */
+export function goalAwarePriority(task, goal) {
+  if (!task || !goal) return { priority: Number.isFinite(task && task.priority) ? task.priority : 5, action: 'none' };
+  const base = Number.isFinite(task.priority) ? task.priority : 5;
+  if (goal.status === 'at-risk') return { priority: Math.max(1, base - 1), action: 'bump' };
+  if (goal.status === 'blocked') return { priority: base, action: 'none' };
+  if (goal.status === 'done') return { priority: 9, action: 'drop' };
+  return { priority: base, action: 'none' };
+}
+
+/** Exported for tests + UI. */
+export const __sizeBuckets = SIZE_ORDER;

package/bizar-dash/tests/agent-bus.test.mjs

@@ -0,0 +1,289 @@
+/**
+ * tests/agent-bus.test.mjs
+ *
+ * Self-check for agent-bus.mjs (G-autoloop Phase 4).
+ * Uses node:test + node:assert/strict, mirroring the convention in
+ * tests/background-steer.test.mjs. Isolates state by pointing the
+ * module at a fresh temp directory and resetting presence on exit.
+ */
+
+import { test, before, after, beforeEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, rmSync, existsSync, readFileSync, mkdirSync, appendFileSync, writeFileSync, renameSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+const TMP = mkdtempSync(join(tmpdir(), 'bizar-agent-bus-'));
+
+// Point the module at the temp dir BEFORE importing it.
+process.env.BIZAR_AGENT_BUS_ROOT = TMP;
+
+const {
+  AGENT_BUS_LOG_DIR,
+  AGENT_BUS_PRESENCE_FILE,
+  DEFAULT_CHANNEL,
+  isValidAddress,
+  resolveAddress,
+  publish,
+  steer,
+  correct,
+  handoff,
+  request,
+  respond,
+  subscribe,
+  subscribeChannel,
+  readChannel,
+  announce,
+  leave,
+  heartbeat,
+  getPresence,
+  _resetForTests,
+} = await import('../src/server/agent-bus.mjs');
+
+beforeEach(() => _resetForTests());
+
+after(() => {
+  try { rmSync(TMP, { recursive: true, force: true }); } catch { /* */ }
+});
+
+test('isValidAddress: accepts loose and targeted and broadcast', () => {
+  assert.equal(isValidAddress('agent://odin'), true);
+  assert.equal(isValidAddress('agent://odin/session-abc123'), true);
+  assert.equal(isValidAddress('agent://*'), true);
+  assert.equal(isValidAddress('odin'), false);
+  assert.equal(isValidAddress('agent:/odin'), false);
+  assert.equal(isValidAddress(''), false);
+  assert.equal(isValidAddress(null), false);
+  assert.equal(isValidAddress(undefined), false);
+});
+
+test('publish: rejects bad input with TypeError', () => {
+  assert.throws(() => publish(null), TypeError);
+  assert.throws(() => publish({}), TypeError);
+  assert.throws(() => publish({ from: 'odin', to: 'agent://thor', kind: 'request' }), TypeError);
+  assert.throws(() => publish({ from: 'agent://odin', to: 'agent://thor', kind: 'bogus' }), TypeError);
+});
+
+test('publish: appends to JSONL log and emits live', () => {
+  const seen = [];
+  const unsub = subscribe((m) => seen.push(m));
+  const id = publish({ from: 'agent://odin', to: 'agent://thor', kind: 'request', payload: { q: 'hello' } });
+  unsub();
+  assert.ok(id.length > 0);
+  assert.equal(seen.length, 1);
+  assert.equal(seen[0].kind, 'request');
+  assert.equal(seen[0].channel, DEFAULT_CHANNEL);
+  const logFile = join(AGENT_BUS_LOG_DIR, `${DEFAULT_CHANNEL}.jsonl`);
+  assert.ok(existsSync(logFile));
+  const text = readFileSync(logFile, 'utf8');
+  assert.equal(text.trim().split('\n').length, 1);
+});
+
+test('publish: per-task channels are auto-created on first publish', () => {
+  const id = publish({
+    from: 'agent://odin',
+    to: 'agent://thor',
+    channel: 'task-tsk_abc',
+    taskId: 'tsk_abc',
+    kind: 'request',
+    payload: { x: 1 },
+  });
+  assert.ok(id);
+  assert.ok(existsSync(join(AGENT_BUS_LOG_DIR, 'task-tsk_abc.jsonl')));
+});
+
+test('steer + correct + handoff: convenience wrappers set kind and payload', () => {
+  const seen = [];
+  const unsub = subscribe((m) => seen.push(m));
+  steer('agent://odin', 'agent://thor', 'focus on tests', { channel: 'task-tsk_x', taskId: 'tsk_x' });
+  correct('agent://odin', 'agent://thor', 'use new endpoint', { before: 'a()', after: 'b()', reason: 'simpler' }, { taskId: 'tsk_x' });
+  handoff('agent://odin', 'agent://thor', 'tsk_x', 'better fit', { channel: 'task-tsk_x' });
+  unsub();
+  assert.equal(seen.length, 3);
+  assert.equal(seen[0].kind, 'steer');
+  assert.equal(seen[0].payload.note, 'focus on tests');
+  assert.equal(seen[1].kind, 'correct');
+  assert.equal(seen[1].payload.before, 'a()');
+  assert.equal(seen[1].payload.after, 'b()');
+  assert.equal(seen[2].kind, 'handoff');
+  assert.equal(seen[2].payload.taskId, 'tsk_x');
+});
+
+test('request/respond: correlation roundtrip resolves the Promise', async () => {
+  const unsub = subscribe((msg) => {
+    if (msg.kind === 'request') {
+      respond(msg, 'agent://thor', { ok: true, value: 42 });
+    }
+  });
+  const reply = await request('agent://odin', 'agent://thor', { ask: 'meaning' }, { timeoutMs: 2000 });
+  unsub();
+  assert.equal(reply.kind, 'response');
+  assert.equal(reply.from, 'agent://thor');
+  assert.equal(reply.payload.value, 42);
+  assert.equal(reply.correlationId.length > 0, true);
+});
+
+test('request: timeout rejects with TIMEOUT code', async () => {
+  await assert.rejects(
+    request('agent://odin', 'agent://nobody', { ask: 'nothing' }, { timeoutMs: 50 }),
+    (err) => err.code === 'TIMEOUT',
+  );
+});
+
+test('subscribeChannel: only fires for the named channel', () => {
+  const target = [];
+  const other = [];
+  const u1 = subscribeChannel('task-tsk_y', (m) => target.push(m));
+  const u2 = subscribeChannel('task-tsk_z', (m) => other.push(m));
+  publish({ from: 'agent://odin', to: 'agent://thor', channel: 'task-tsk_y', kind: 'request', payload: {} });
+  publish({ from: 'agent://odin', to: 'agent://thor', channel: 'task-tsk_z', kind: 'request', payload: {} });
+  u1(); u2();
+  assert.equal(target.length, 1);
+  assert.equal(other.length, 1);
+});
+
+test('readChannel: skips corrupt JSONL lines and respects limit', () => {
+  const logFile = join(AGENT_BUS_LOG_DIR, 'corrupt.jsonl');
+  mkdirSync(AGENT_BUS_LOG_DIR, { recursive: true });
+  const good = { id: 'a', from: 'agent://odin', to: 'agent://thor', channel: 'corrupt', kind: 'request', payload: {}, ts: new Date().toISOString() };
+  appendFileSync(logFile, JSON.stringify(good) + '\n');
+  appendFileSync(logFile, 'this is not json\n');
+  appendFileSync(logFile, JSON.stringify({ ...good, id: 'b' }) + '\n');
+  const out = readChannel('corrupt');
+  assert.equal(out.length, 2);
+  assert.equal(out[0].id, 'a');
+  assert.equal(out[1].id, 'b');
+});
+
+test('readChannel: limit truncates to the last N', () => {
+  for (let i = 0; i < 5; i++) {
+    publish({ from: 'agent://odin', to: 'agent://thor', channel: 'limit', kind: 'request', payload: { i } });
+  }
+  const out = readChannel('limit', { limit: 2 });
+  assert.equal(out.length, 2);
+  assert.equal(out[0].payload.i, 3);
+  assert.equal(out[1].payload.i, 4);
+});
+
+test('readChannel: since filters out messages at or before the cutoff', async () => {
+  publish({ from: 'agent://odin', to: 'agent://thor', channel: 'since', kind: 'request', payload: { i: 1 } });
+  // Guarantee a strictly-monotonic clock between msg 1 and the cutoff.
+  await new Promise((r) => setTimeout(r, 5));
+  const cutoff = new Date().toISOString();
+  await new Promise((r) => setTimeout(r, 5));
+  publish({ from: 'agent://odin', to: 'agent://thor', channel: 'since', kind: 'request', payload: { i: 2 } });
+  const out = readChannel('since', { since: cutoff });
+  assert.equal(out.length, 1);
+  assert.equal(out[0].payload.i, 2);
+});
+
+test('presence: announce + heartbeat + getPresence roundtrip', () => {
+  announce({ name: 'odin', sessionId: 'sess_1', capabilities: ['plan'], model: 'opus' });
+  announce({ name: 'thor', sessionId: 'sess_2', currentTask: 'tsk_1' });
+  const p = getPresence();
+  assert.ok(p.odin);
+  assert.equal(p.odin.sessionId, 'sess_1');
+  assert.deepEqual(p.odin.capabilities, ['plan']);
+  assert.ok(p.thor);
+  heartbeat('odin', 'sess_1');
+  heartbeat('thor', 'sess_1'); // wrong sessionId — no-op
+  assert.equal(getPresence().odin.sessionId, 'sess_1');
+});
+
+test('presence: leave removes and persists', () => {
+  announce({ name: 'odin', sessionId: 'sess_1' });
+  assert.ok(getPresence().odin);
+  leave('odin');
+  assert.equal(getPresence().odin, undefined);
+  // Persistence: presence.json on disk reflects the leave.
+  const persisted = JSON.parse(readFileSync(AGENT_BUS_PRESENCE_FILE, 'utf8'));
+  assert.equal(persisted.odin, undefined);
+});
+
+test('presence: announce with same name+sessionId updates lastSeenAt in-place', () => {
+  announce({ name: 'odin', sessionId: 'sess_1', capabilities: ['plan'] });
+  const first = getPresence().odin.lastSeenAt;
+  // Wait 5ms so the timestamp moves.
+  const wait = Date.now() + 5;
+  while (Date.now() < wait) { /* spin */ }
+  announce({ name: 'odin', sessionId: 'sess_1', capabilities: ['plan', 'impl'] });
+  const second = getPresence().odin;
+  assert.equal(second.sessionId, 'sess_1');
+  assert.notEqual(second.lastSeenAt, first);
+});
+
+test('presence: getPresence filters stale entries older than 5 minutes', () => {
+  announce({ name: 'fresh', sessionId: 's' });
+  announce({ name: 'stale', sessionId: 's' });
+  // Backdate stale manually via the in-memory map.
+  // We don't have a handle to it, so we use leave+reannounce with a
+  // forged timestamp persisted through read-modify-write.
+  const persisted = JSON.parse(readFileSync(AGENT_BUS_PRESENCE_FILE, 'utf8'));
+  persisted.stale.lastSeenAt = new Date(Date.now() - 6 * 60 * 1000).toISOString();
+  // _resetForTests wipes the in-memory map; we leave the file as-is
+  // and call announce again so in-memory state matches.
+  writeFileSync(AGENT_BUS_PRESENCE_FILE + '.tmp', JSON.stringify(persisted));
+  renameSync(AGENT_BUS_PRESENCE_FILE + '.tmp', AGENT_BUS_PRESENCE_FILE);
+  _resetForTests();
+  announce({ name: 'fresh', sessionId: 's' });
+  // `stale` is no longer in-memory, so getPresence won't see it —
+  // this is correct. The persistence-level staleness check would
+  // only matter on cold start. We assert the in-memory filter:
+  const p = getPresence();
+  assert.ok(p.fresh);
+  assert.equal(p.stale, undefined);
+});
+
+test('resolveAddress: loose address returns live sessions; targeted requires matching sid', () => {
+  announce({ name: 'odin', sessionId: 'sess_a' });
+  announce({ name: 'thor', sessionId: 'sess_b' });
+  assert.equal(resolveAddress('agent://odin').length, 1);
+  assert.equal(resolveAddress('agent://odin')[0].sessionId, 'sess_a');
+  assert.equal(resolveAddress('agent://odin/sess_a').length, 1);
+  assert.equal(resolveAddress('agent://odin/wrong-sid').length, 0);
+  assert.equal(resolveAddress('agent://nobody').length, 0);
+  assert.equal(resolveAddress('not-an-address').length, 0);
+});
+
+test('publish: empty payload becomes {}', () => {
+  const id = publish({ from: 'agent://odin', to: 'agent://thor', kind: 'ack' });
+  const log = readChannel(DEFAULT_CHANNEL);
+  const found = log.find((m) => m.id === id);
+  assert.ok(found);
+  assert.deepEqual(found.payload, {});
+});
+
+test('publish: correlationId and taskId survive the roundtrip', () => {
+  publish({
+    from: 'agent://odin',
+    to: 'agent://thor',
+    channel: 'task-tsk_q',
+    taskId: 'tsk_q',
+    kind: 'request',
+    payload: {},
+  });
+  const log = readChannel('task-tsk_q');
+  assert.equal(log[0].taskId, 'tsk_q');
+  assert.equal(log[0].correlationId, null);
+});
+
+test('subscribe: returns an unsubscribe function that detaches the listener', () => {
+  let count = 0;
+  const unsub = subscribe(() => count++);
+  publish({ from: 'agent://odin', to: 'agent://thor', kind: 'ack' });
+  publish({ from: 'agent://odin', to: 'agent://thor', kind: 'ack' });
+  assert.equal(count, 2);
+  unsub();
+  publish({ from: 'agent://odin', to: 'agent://thor', kind: 'ack' });
+  assert.equal(count, 2);
+});
+
+test('subscribe: rejects non-function listener', () => {
+  assert.throws(() => subscribe('not a fn'), TypeError);
+  assert.throws(() => subscribe(null), TypeError);
+});
+
+test('announce: rejects missing name or sessionId', () => {
+  assert.throws(() => announce({ sessionId: 's' }), TypeError);
+  assert.throws(() => announce({ name: 'x' }), TypeError);
+});