@cohortapp/agent-sdk 2.3.0

package/lib/collective/presence.mjs

@@ -0,0 +1,201 @@
+/**
+ * lib/collective/presence.mjs — concurrent-session presence registry.
+ *
+ * Gives every running Claude Code session situational awareness of the OTHER
+ * sessions active on the machine right now. Each session is one JSON file under
+ * `state/collective/presence/<sessionId>.json`, written with the same atomic-`wx`
+ * + fail-open idiom as scripts/daemon/session-lock.mjs. Stale entries (no
+ * heartbeat past `staleSec`, or a dead PID) are reaped on read.
+ *
+ * Anti-bloat: presence surfaces as ONE summary line in the SessionStart digest,
+ * never a full dump. Everything is fail-open — presence never blocks a session.
+ *
+ * Record shape:
+ *   { sessionId, pid, cwd, repo, agentName, startedAt, lastBeat,
+ *     intent, model, status, kind }
+ *
+ * @module lib/collective/presence
+ */
+
+"use strict";
+
+import {
+  writeFileSync, readFileSync, unlinkSync, readdirSync, mkdirSync, existsSync,
+} from "node:fs";
+import { join, basename } from "node:path";
+
+const PRESENCE_REL = "state/collective/presence";
+const DEFAULT_STALE_SEC = 300;
+
+function presenceDir(agentRoot) {
+  return join(agentRoot, PRESENCE_REL);
+}
+
+function safeId(sessionId) {
+  return String(sessionId || "unknown").replace(/[^a-zA-Z0-9_-]/g, "-").slice(0, 120);
+}
+
+/** Liveness probe — signal 0 checks existence without sending a signal. */
+function isProcessRunning(pid) {
+  if (!pid || !Number.isFinite(pid)) return true; // unknown pid → don't reap on this basis
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return err.code === "EPERM"; // exists but not ours
+  }
+}
+
+function nowIso(nowMs) {
+  return new Date(Number.isFinite(nowMs) ? nowMs : Date.now()).toISOString();
+}
+
+/**
+ * Register (or refresh) a session in the presence registry. Idempotent: a
+ * second call for the same sessionId overwrites, preserving startedAt.
+ *
+ * @param {string} agentRoot
+ * @param {object} info - { sessionId, pid?, cwd?, repo?, agentName?, intent?, model?, status?, kind?, nowMs? }
+ * @returns {boolean} success
+ */
+export function register(agentRoot, info = {}) {
+  if (!agentRoot || !info.sessionId) return false;
+  const dir = presenceDir(agentRoot);
+  const path = join(dir, `${safeId(info.sessionId)}.json`);
+  try {
+    mkdirSync(dir, { recursive: true });
+    let startedAt = nowIso(info.nowMs);
+    try {
+      if (existsSync(path)) {
+        const prev = JSON.parse(readFileSync(path, "utf8"));
+        if (prev && prev.startedAt) startedAt = prev.startedAt;
+      }
+    } catch { /* ignore prior */ }
+    const rec = {
+      sessionId: String(info.sessionId),
+      pid: Number.isFinite(info.pid) ? info.pid : process.pid,
+      cwd: info.cwd || "",
+      repo: info.repo || (info.cwd ? basename(info.cwd) : ""),
+      agentName: info.agentName || "",
+      startedAt,
+      lastBeat: nowIso(info.nowMs),
+      intent: String(info.intent || "").slice(0, 200),
+      model: info.model || "",
+      status: info.status || "active",
+      kind: info.kind || "interactive",
+    };
+    writeFileSync(path, JSON.stringify(rec, null, 2));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Refresh a session's heartbeat (and optionally intent/status). No-op if the
+ * record is gone. Fail-open.
+ * @param {string} agentRoot @param {string} sessionId @param {object} [updates]
+ */
+export function heartbeat(agentRoot, sessionId, updates = {}) {
+  if (!agentRoot || !sessionId) return false;
+  const path = join(presenceDir(agentRoot), `${safeId(sessionId)}.json`);
+  try {
+    const rec = JSON.parse(readFileSync(path, "utf8"));
+    rec.lastBeat = nowIso(updates.nowMs);
+    if (updates.intent !== undefined) rec.intent = String(updates.intent).slice(0, 200);
+    if (updates.status !== undefined) rec.status = updates.status;
+    writeFileSync(path, JSON.stringify(rec, null, 2));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Remove a session from the registry (called on Stop / SessionEnd). */
+export function deregister(agentRoot, sessionId) {
+  if (!agentRoot || !sessionId) return;
+  try {
+    unlinkSync(join(presenceDir(agentRoot), `${safeId(sessionId)}.json`));
+  } catch { /* already gone — fine */ }
+}
+
+/**
+ * List live sessions, reaping stale (no heartbeat past staleSec) or dead-PID
+ * entries as a side effect. Newest-heartbeat first.
+ *
+ * @param {string} agentRoot
+ * @param {object} [opts] - { staleSec, nowMs, reap=true }
+ * @returns {object[]}
+ */
+export function list(agentRoot, opts = {}) {
+  if (!agentRoot) return [];
+  const dir = presenceDir(agentRoot);
+  if (!existsSync(dir)) return [];
+  const staleMs = (Number.isFinite(opts.staleSec) ? opts.staleSec : DEFAULT_STALE_SEC) * 1000;
+  const nowMs = Number.isFinite(opts.nowMs) ? opts.nowMs : Date.now();
+  const reap = opts.reap !== false;
+  let files;
+  try {
+    files = readdirSync(dir).filter((f) => f.endsWith(".json"));
+  } catch {
+    return [];
+  }
+  const live = [];
+  for (const f of files) {
+    const path = join(dir, f);
+    let rec;
+    try {
+      rec = JSON.parse(readFileSync(path, "utf8"));
+    } catch {
+      if (reap) { try { unlinkSync(path); } catch { /* */ } }
+      continue;
+    }
+    const age = nowMs - Date.parse(rec.lastBeat || rec.startedAt || 0);
+    const stale = !Number.isFinite(age) || age > staleMs;
+    const dead = !isProcessRunning(rec.pid);
+    if (stale || dead) {
+      if (reap) { try { unlinkSync(path); } catch { /* */ } }
+      continue;
+    }
+    live.push(rec);
+  }
+  live.sort((a, b) => Date.parse(b.lastBeat || 0) - Date.parse(a.lastBeat || 0));
+  return live;
+}
+
+/** Human "Xm"/"Xs"/"Xh" age from a lastBeat ISO, relative to nowMs. */
+function ageLabel(iso, nowMs) {
+  const ms = nowMs - Date.parse(iso);
+  if (!Number.isFinite(ms) || ms < 0) return "now";
+  const s = Math.round(ms / 1000);
+  if (s < 45) return "just now";
+  const m = Math.round(s / 60);
+  if (m < 60) return `${m}m`;
+  const h = Math.round(m / 60);
+  return `${h}h`;
+}
+
+/**
+ * Build the one-line presence summary for the SessionStart digest. Excludes the
+ * current session. Returns "" when no other sessions are active (so the digest
+ * can omit the line entirely).
+ *
+ * @param {string} agentRoot
+ * @param {object} [opts] - { excludeSessionId, staleSec, nowMs, max=5 }
+ * @returns {string}
+ */
+export function summarize(agentRoot, opts = {}) {
+  const nowMs = Number.isFinite(opts.nowMs) ? opts.nowMs : Date.now();
+  const max = Number.isFinite(opts.max) ? opts.max : 5;
+  const others = list(agentRoot, { staleSec: opts.staleSec, nowMs, reap: opts.reap })
+    .filter((r) => r.sessionId !== opts.excludeSessionId);
+  if (others.length === 0) return "";
+  const parts = others.slice(0, max).map((r) => {
+    const where = r.kind === "daemon" ? "daemon" : (r.repo || "session");
+    const what = r.intent ? `: ${r.intent}` : "";
+    return `${where}${what} (${ageLabel(r.lastBeat, nowMs)})`;
+  });
+  const extra = others.length > max ? ` +${others.length - max} more` : "";
+  const noun = others.length === 1 ? "session" : "sessions";
+  return `${others.length} other ${noun} active — ${parts.join("; ")}${extra}`;
+}

package/lib/collective/presence.test.mjs

@@ -0,0 +1,95 @@
+/**
+ * presence.test.mjs — tests for the concurrent-session presence registry.
+ * Run: node --test lib/collective/presence.test.mjs
+ */
+"use strict";
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { register, heartbeat, deregister, list, summarize } from "./presence.mjs";
+
+function tmp() {
+  return mkdtempSync(join(tmpdir(), "collective-presence-"));
+}
+const T0 = Date.parse("2026-06-03T12:00:00Z");
+
+test("register + list: round-trips a live session", () => {
+  const root = tmp();
+  try {
+    assert.equal(register(root, { sessionId: "s1", cwd: "/Users/x/maestro", intent: "triage inbox", nowMs: T0 }), true);
+    const live = list(root, { nowMs: T0 + 1000, staleSec: 300 });
+    assert.equal(live.length, 1);
+    assert.equal(live[0].sessionId, "s1");
+    assert.equal(live[0].repo, "maestro", "repo derived from cwd basename");
+    assert.equal(live[0].intent, "triage inbox");
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("heartbeat: refreshes lastBeat and intent", () => {
+  const root = tmp();
+  try {
+    register(root, { sessionId: "s1", nowMs: T0 });
+    heartbeat(root, "s1", { nowMs: T0 + 60_000, intent: "drafting reply" });
+    const live = list(root, { nowMs: T0 + 61_000, staleSec: 300 });
+    assert.equal(live[0].intent, "drafting reply");
+    assert.equal(Date.parse(live[0].lastBeat), T0 + 60_000);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("deregister: removes the session", () => {
+  const root = tmp();
+  try {
+    register(root, { sessionId: "s1", nowMs: T0 });
+    deregister(root, "s1");
+    assert.equal(list(root, { nowMs: T0 + 1000 }).length, 0);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("list: reaps stale sessions (no heartbeat past staleSec)", () => {
+  const root = tmp();
+  try {
+    register(root, { sessionId: "stale", nowMs: T0 });
+    // 10 min later with a 5-min stale window → reaped.
+    const live = list(root, { nowMs: T0 + 10 * 60_000, staleSec: 300 });
+    assert.equal(live.length, 0);
+    // Confirm it was actually deleted, not just filtered.
+    assert.equal(list(root, { nowMs: T0 + 10 * 60_000 + 1, staleSec: 999999 }).length, 0);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("list: reaps dead-PID sessions", () => {
+  const root = tmp();
+  try {
+    register(root, { sessionId: "dead", pid: 2_000_000_000, nowMs: T0 });
+    const live = list(root, { nowMs: T0 + 1000, staleSec: 300 });
+    assert.equal(live.length, 0, "a session whose PID is not running is reaped");
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("summarize: excludes self; empty when alone; formats others", () => {
+  const root = tmp();
+  try {
+    register(root, { sessionId: "me", cwd: "/x/maestro", nowMs: T0 });
+    assert.equal(summarize(root, { excludeSessionId: "me", nowMs: T0 + 1000 }), "", "alone → empty");
+    register(root, { sessionId: "other", cwd: "/x/openclaw", intent: "research", kind: "interactive", nowMs: T0 });
+    const line = summarize(root, { excludeSessionId: "me", nowMs: T0 + 1000, staleSec: 300 });
+    assert.match(line, /1 other session active/);
+    assert.match(line, /openclaw: research/);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});

package/lib/collective/recall.mjs

@@ -0,0 +1,215 @@
+/**
+ * lib/collective/recall.mjs — budgeted recall for the SessionStart digest.
+ *
+ * THE anti-bloat module. Turns the agent's memory cards (+ live presence) into a
+ * small, hard-token-budgeted context block injected at session start. Ranking is
+ * relevance × recency-decay × salience; near-duplicates are removed with MMR;
+ * the result is cut to `budgetTokens`.
+ *
+ * The ranking/budget/MMR core is pure and unit-tested. `buildDigest()` wires it
+ * to the card store + presence; `recallForQuery()` wraps the existing lib/rag
+ * search for on-demand, query-driven recall (the `collective recall` CLI).
+ *
+ * @module lib/collective/recall
+ */
+
+"use strict";
+
+import { readRecentCards, cardToText } from "./cards.mjs";
+import { summarize as summarizePresence } from "./presence.mjs";
+
+const DAY_MS = 86400_000;
+
+/** ~4 chars/token heuristic; good enough for a budget guard. */
+export function estimateTokens(text) {
+  if (!text) return 0;
+  return Math.ceil(String(text).length / 4);
+}
+
+/** Exponential recency decay: 1.0 now → 0.5 at one half-life → … */
+export function decayWeight(ageMs, halfLifeDays) {
+  const hl = (Number.isFinite(halfLifeDays) && halfLifeDays > 0 ? halfLifeDays : 30) * DAY_MS;
+  const age = Number.isFinite(ageMs) && ageMs > 0 ? ageMs : 0;
+  return Math.pow(2, -age / hl);
+}
+
+/** Salience boost in [0.4, 1.0] so low-salience cards rank lower but never vanish. */
+function salienceBoost(salience) {
+  const s = Number.isFinite(salience) ? Math.max(0, Math.min(1, salience)) : 0.5;
+  return 0.4 + 0.6 * s;
+}
+
+/**
+ * Score + sort cards by relevance × recency-decay × salience. Pure.
+ *
+ * @param {object[]} cards
+ * @param {object} [opts] - { relevanceById?, nowMs, halfLifeDays }
+ *   relevanceById: optional map cardId → relevance (0..1); defaults to 1 (i.e.
+ *   pure recency×salience, the cold-start case).
+ * @returns {Array<{card, score}>}
+ */
+export function rankCards(cards, opts = {}) {
+  const nowMs = Number.isFinite(opts.nowMs) ? opts.nowMs : Date.now();
+  const rel = opts.relevanceById || null;
+  const scored = (Array.isArray(cards) ? cards : []).map((card) => {
+    const ageMs = nowMs - Date.parse(card.ts || 0);
+    const relevance = rel && rel[card.id] != null ? rel[card.id] : 1;
+    const score = relevance * decayWeight(ageMs, opts.halfLifeDays) * salienceBoost(card.salience);
+    return { card, score };
+  });
+  scored.sort((a, b) => b.score - a.score);
+  return scored;
+}
+
+/**
+ * Lowercase token set for similarity (drops sub-3-char tokens + punctuation).
+ * Exported so the learning loop (lib/learning/reflect) reuses the SAME tokenizer
+ * the digest's MMR uses — one definition of "similar".
+ */
+export function tokenSet(text) {
+  return new Set(
+    String(text || "").toLowerCase().replace(/[^a-z0-9 ]/g, " ").split(/\s+/).filter((t) => t.length > 2),
+  );
+}
+
+/**
+ * Jaccard similarity of two token sets. Exported for reuse by the learning loop
+ * (procedure-recurrence detection) — see lib/learning/reflect.
+ */
+export function jaccard(a, b) {
+  if (a.size === 0 || b.size === 0) return 0;
+  let inter = 0;
+  for (const t of a) if (b.has(t)) inter++;
+  return inter / (a.size + b.size - inter);
+}
+
+/**
+ * Maximal Marginal Relevance selection — greedily pick high-score items while
+ * penalizing similarity to already-selected items, so the digest is diverse
+ * rather than five near-duplicate cards. Pure.
+ *
+ * @param {Array<{card, score}>} scored - sorted desc by score
+ * @param {object} [opts] - { limit=12, lambda=0.7 }
+ * @returns {Array<{card, score}>}
+ */
+export function mmrSelect(scored, opts = {}) {
+  const limit = Number.isFinite(opts.limit) ? opts.limit : 12;
+  const lambda = Number.isFinite(opts.lambda) ? opts.lambda : 0.7;
+  const pool = scored.slice();
+  const selected = [];
+  const selSets = [];
+  while (pool.length && selected.length < limit) {
+    let bestIdx = 0;
+    let bestVal = -Infinity;
+    for (let i = 0; i < pool.length; i++) {
+      const set = tokenSet(cardToText(pool[i].card));
+      let maxSim = 0;
+      for (const s of selSets) maxSim = Math.max(maxSim, jaccard(set, s));
+      const mmr = lambda * pool[i].score - (1 - lambda) * maxSim;
+      if (mmr > bestVal) { bestVal = mmr; bestIdx = i; }
+    }
+    const [chosen] = pool.splice(bestIdx, 1);
+    selected.push(chosen);
+    selSets.push(tokenSet(cardToText(chosen.card)));
+  }
+  return selected;
+}
+
+/**
+ * Take items (in order) until the cumulative token cost of their rendered lines
+ * would exceed `budgetTokens` (after reserving `reservedTokens` for the header /
+ * presence line). Pure.
+ *
+ * @param {Array<{card, score}>} items
+ * @param {object} [opts] - { budgetTokens=1500, reservedTokens=0 }
+ * @returns {Array<{card, score}>}
+ */
+export function selectWithinBudget(items, opts = {}) {
+  const budget = Number.isFinite(opts.budgetTokens) ? opts.budgetTokens : 1500;
+  let used = Number.isFinite(opts.reservedTokens) ? opts.reservedTokens : 0;
+  const out = [];
+  for (const it of items) {
+    const cost = estimateTokens("- " + cardToText(it.card)) + 1;
+    if (used + cost > budget) break;
+    used += cost;
+    out.push(it);
+  }
+  return out;
+}
+
+/**
+ * Render the digest block. Returns "" when there is nothing to say (no presence,
+ * no cards) so the hook can stay silent.
+ */
+export function formatDigest({ presenceLine = "", cards = [], totalCards = 0 } = {}) {
+  if (!presenceLine && cards.length === 0) return "";
+  const lines = ["<!-- maestro:collective-digest -->"];
+  if (presenceLine) lines.push(`**Active now:** ${presenceLine}`);
+  if (cards.length) {
+    const more = totalCards > cards.length ? ` of ${totalCards}; \`rag_search\` or \`collective recall\` for more` : "";
+    lines.push(`**Recent collective memory** (${cards.length}${more}):`);
+    for (const c of cards) lines.push(`- ${cardToText(c)}`);
+  }
+  return lines.join("\n");
+}
+
+/**
+ * Build the full SessionStart digest for an agent root. Pulls recent cards +
+ * live presence, ranks, MMR-dedupes, and cuts to budget. Fail-open → "".
+ *
+ * @param {string} agentRoot
+ * @param {object} [opts] - {
+ *   budgetTokens, halfLifeDays, nowMs, excludeSessionId, staleSec, maxCards,
+ *   relevanceById, presenceLineOverride, cardsOverride
+ * }
+ * @returns {string}
+ */
+export function buildDigest(agentRoot, opts = {}) {
+  try {
+    const nowMs = Number.isFinite(opts.nowMs) ? opts.nowMs : Date.now();
+    const budgetTokens = Number.isFinite(opts.budgetTokens) ? opts.budgetTokens : 1500;
+    const presenceLine = opts.presenceLineOverride != null
+      ? opts.presenceLineOverride
+      : summarizePresence(agentRoot, { excludeSessionId: opts.excludeSessionId, staleSec: opts.staleSec, nowMs });
+    const cards = opts.cardsOverride != null
+      ? opts.cardsOverride
+      : readRecentCards(agentRoot, { nowMs, days: Math.max(45, (opts.halfLifeDays || 30) * 2) });
+    const scored = rankCards(cards, { relevanceById: opts.relevanceById, nowMs, halfLifeDays: opts.halfLifeDays });
+    const diversified = mmrSelect(scored, { limit: Number.isFinite(opts.maxCards) ? opts.maxCards : 12 });
+    const reserved = estimateTokens(presenceLine) + 24; // header + presence
+    const selected = selectWithinBudget(diversified, { budgetTokens, reservedTokens: reserved });
+    return formatDigest({
+      presenceLine,
+      cards: selected.map((s) => s.card),
+      totalCards: cards.length,
+    });
+  } catch {
+    return "";
+  }
+}
+
+/**
+ * On-demand, query-driven recall over the full indexed corpus (incl. collective
+ * cards). Thin wrapper over lib/rag search; `searchFn` is injectable for tests.
+ *
+ * @param {object} opts - { agentRoot, query, topN=8, searchFn? }
+ * @returns {Promise<Array>}
+ */
+export async function recallForQuery(opts = {}) {
+  const { agentRoot, query, topN = 8 } = opts;
+  if (!agentRoot || !query) return [];
+  let searchFn = opts.searchFn;
+  if (!searchFn) {
+    try {
+      const mod = await import("../rag/search.mjs");
+      searchFn = mod.search;
+    } catch {
+      return [];
+    }
+  }
+  try {
+    return await searchFn({ query, topN, agentRoot });
+  } catch {
+    return [];
+  }
+}

package/lib/collective/recall.test.mjs

@@ -0,0 +1,116 @@
+/**
+ * recall.test.mjs — tests for the budgeted recall core.
+ * Run: node --test lib/collective/recall.test.mjs
+ */
+"use strict";
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+
+import {
+  estimateTokens,
+  decayWeight,
+  rankCards,
+  mmrSelect,
+  selectWithinBudget,
+  formatDigest,
+  buildDigest,
+  recallForQuery,
+} from "./recall.mjs";
+
+const T = Date.parse("2026-06-03T12:00:00Z");
+const card = (over) => ({
+  id: over.id || over.title, ts: over.ts, kind: over.kind || "fact",
+  title: over.title, body: over.body || "", tags: over.tags || [],
+  salience: over.salience ?? 0.5, sessionId: "s", repo: "r", sourceRefs: [],
+});
+
+test("estimateTokens: ~chars/4", () => {
+  assert.equal(estimateTokens(""), 0);
+  assert.equal(estimateTokens("abcd"), 1);
+  assert.equal(estimateTokens("a".repeat(40)), 10);
+});
+
+test("decayWeight: 1.0 at age 0, ~0.5 at one half-life", () => {
+  assert.equal(decayWeight(0, 30), 1);
+  assert.ok(Math.abs(decayWeight(30 * 86400_000, 30) - 0.5) < 1e-9);
+  assert.ok(decayWeight(60 * 86400_000, 30) < 0.26);
+});
+
+test("rankCards: recency + salience order; relevanceById applies", () => {
+  const cards = [
+    card({ title: "old-hi-sal", ts: "2026-05-01T00:00:00Z", salience: 0.9 }),
+    card({ title: "new-lo-sal", ts: "2026-06-03T00:00:00Z", salience: 0.2 }),
+  ];
+  const ranked = rankCards(cards, { nowMs: T, halfLifeDays: 30 });
+  assert.equal(ranked[0].card.title, "new-lo-sal", "recent beats month-old even at lower salience");
+  // Relevance map can flip it.
+  const ranked2 = rankCards(cards, {
+    nowMs: T, halfLifeDays: 30,
+    relevanceById: { "old-hi-sal": 1, "new-lo-sal": 0.05 },
+  });
+  assert.equal(ranked2[0].card.title, "old-hi-sal", "strong relevance dominates");
+});
+
+test("mmrSelect: dedupes near-duplicates and respects limit", () => {
+  const scored = [
+    { card: card({ title: "Shipped the billing migration to prod" }), score: 1.0 },
+    { card: card({ title: "Shipped the billing migration to production" }), score: 0.99 },
+    { card: card({ title: "Hired a new compliance analyst" }), score: 0.8 },
+  ];
+  const picked = mmrSelect(scored, { limit: 2, lambda: 0.7 });
+  assert.equal(picked.length, 2);
+  const titles = picked.map((p) => p.card.title);
+  assert.ok(titles.includes("Shipped the billing migration to prod"));
+  assert.ok(
+    titles.includes("Hired a new compliance analyst"),
+    "MMR should prefer the diverse card over the near-duplicate",
+  );
+});
+
+test("selectWithinBudget: stops before exceeding the budget", () => {
+  const items = Array.from({ length: 50 }, (_, i) => ({ card: card({ title: `card number ${i} with some words` }), score: 1 - i / 100 }));
+  const tiny = selectWithinBudget(items, { budgetTokens: 20 });
+  const big = selectWithinBudget(items, { budgetTokens: 100000 });
+  assert.ok(tiny.length < big.length, "tighter budget selects fewer");
+  assert.ok(tiny.length >= 1);
+});
+
+test("formatDigest: empty when nothing; includes presence + cards", () => {
+  assert.equal(formatDigest({ presenceLine: "", cards: [] }), "");
+  const out = formatDigest({
+    presenceLine: "1 other session active — maestro: triage (2m)",
+    cards: [card({ title: "Decided to ship v2", kind: "decision" })],
+    totalCards: 3,
+  });
+  assert.match(out, /maestro:collective-digest/);
+  assert.match(out, /Active now:/);
+  assert.match(out, /Decided to ship v2/);
+  assert.match(out, /of 3/, "indicates more available");
+});
+
+test("buildDigest: budgeted, uses overrides, fail-open", () => {
+  const cards = Array.from({ length: 30 }, (_, i) =>
+    card({ title: `Event ${i} happened in the system today`, ts: "2026-06-03T00:00:00Z", salience: 0.5 }));
+  const full = buildDigest("/nonexistent", {
+    nowMs: T, budgetTokens: 100000, presenceLineOverride: "2 sessions active", cardsOverride: cards,
+  });
+  assert.match(full, /Active now:/);
+  const tight = buildDigest("/nonexistent", {
+    nowMs: T, budgetTokens: 60, presenceLineOverride: "2 sessions active", cardsOverride: cards,
+  });
+  // Tight budget yields a much shorter block.
+  assert.ok(tight.length < full.length);
+  // Fail-open: bad input never throws.
+  assert.equal(typeof buildDigest(null, { cardsOverride: null, presenceLineOverride: "" }), "string");
+});
+
+test("recallForQuery: injected search; empty without query", async () => {
+  assert.deepEqual(await recallForQuery({ agentRoot: "/x" }), []);
+  const hits = await recallForQuery({
+    agentRoot: "/x", query: "billing",
+    searchFn: async ({ query }) => [{ source_path: "memory/collective/cards/x.jsonl", relevance: 1, snippet: query }],
+  });
+  assert.equal(hits.length, 1);
+  assert.equal(hits[0].relevance, 1);
+});