@cohortapp/agent-sdk 2.3.0

package/lib/collective/capture.mjs

@@ -0,0 +1,185 @@
+/**
+ * lib/collective/capture.mjs — distil a finished session into memory cards.
+ *
+ * The write path of collective memory. A global Stop/PreCompact hook hands the
+ * session transcript here; we run a CHEAP model to distil it into a handful of
+ * durable memory cards (decisions/facts/artifacts/open-loops/entities) and append
+ * them to the card store. NEVER stores raw transcripts.
+ *
+ * Hard guarantees (this runs on every session machine-wide):
+ *   - FAIL-OPEN: any error → 0 cards written, never throws, never blocks.
+ *   - SCOPED: honors the repo denylist + the `enabled` flag.
+ *   - BOUNDED: skips trivial sessions, caps cards/session, time-boxes the model.
+ *
+ * The distiller is injectable (`distillFn`) so tests never spawn a model; the
+ * default shells a `claude --print --model <cheap>` via lib/claude-bin.
+ *
+ * @module lib/collective/capture
+ */
+
+"use strict";
+
+import { spawnSync } from "node:child_process";
+import { normalizeCard, appendCards, repoLabel } from "./cards.mjs";
+import { isRepoDenied } from "./config.mjs";
+import { resolveClaudeBin, daemonClaudeArgs, augmentedPath } from "../claude-bin.mjs";
+
+const DISTILL_TIMEOUT_MS = 60_000;
+const MAX_TRANSCRIPT_CHARS = 16_000;
+
+/** Keep the last `n` chars of a string (the tail is the most relevant). */
+function tail(s, n) {
+  return s.length <= n ? s : s.slice(s.length - n);
+}
+
+function extractContent(obj) {
+  const c = obj.content ?? (obj.message && obj.message.content);
+  if (typeof c === "string") return c;
+  if (Array.isArray(c)) {
+    return c.map((part) => (typeof part === "string" ? part : part && part.text ? part.text : "")).filter(Boolean).join(" ");
+  }
+  if (typeof obj.text === "string") return obj.text;
+  return "";
+}
+
+/**
+ * Flatten a Claude Code transcript (JSONL of message objects) into role-tagged
+ * text, tail-capped. Plain (non-JSONL) input is passed through tail-capped.
+ * @param {string} jsonl
+ * @returns {string}
+ */
+export function transcriptToText(jsonl) {
+  if (!jsonl) return "";
+  const lines = String(jsonl).split("\n").map((s) => s.trim()).filter(Boolean);
+  const out = [];
+  let looksJsonl = false;
+  for (const line of lines) {
+    if (!line.startsWith("{")) continue;
+    looksJsonl = true;
+    try {
+      const obj = JSON.parse(line);
+      const role = obj.role || (obj.message && obj.message.role) || obj.type || "";
+      const content = extractContent(obj);
+      if (content) out.push(`${role ? role + ": " : ""}${content}`);
+    } catch { /* skip bad line */ }
+  }
+  if (!looksJsonl) return tail(String(jsonl), MAX_TRANSCRIPT_CHARS);
+  return tail(out.join("\n"), MAX_TRANSCRIPT_CHARS);
+}
+
+/** Count user turns in role-tagged transcript text. */
+export function countUserTurns(text) {
+  if (!text) return 0;
+  const m = String(text).match(/(^|\n)\s*(user|human)\s*:/gi);
+  return m ? m.length : 0;
+}
+
+/** The distillation instruction handed to the cheap model. */
+export function buildDistillPrompt(transcriptText, maxCards = 12) {
+  return [
+    "You distil a finished work session into durable MEMORY CARDS for an AI agent's",
+    "long-term memory. Output ONLY a JSON array (no prose, no code fence).",
+    "",
+    "Each card: {\"kind\",\"title\",\"body\",\"tags\",\"salience\",\"sourceRefs\"}.",
+    "  kind: one of decision|fact|artifact|openloop|entity|procedure",
+    "    procedure: a repeatable multi-step method a future session could re-run",
+    "    (a named how-to with concrete steps) — NOT a one-off action.",
+    "  title: <=160 chars, the durable takeaway (not a play-by-play)",
+    "  body: <=600 chars of supporting detail",
+    "  tags: 0-6 short topic tags",
+    "  salience: 0..1 — how useful this will be to a FUTURE session (be selective)",
+    "  sourceRefs: file paths / urls / ids touched (optional)",
+    "",
+    "Rules: capture only what a future session would genuinely benefit from —",
+    "decisions made, facts learned, artifacts produced, open loops left, key",
+    `entities. Skip chit-chat, transient debugging, and secrets. At most ${maxCards} cards.`,
+    "If nothing is worth remembering, output [].",
+    "",
+    "=== SESSION TRANSCRIPT (tail) ===",
+    transcriptText,
+    "=== END ===",
+  ].join("\n");
+}
+
+/** Extract a JSON array of raw cards from model output. Tolerant; [] on failure. */
+export function extractCardsFromModelOutput(text) {
+  if (!text || typeof text !== "string") return [];
+  const start = text.indexOf("[");
+  const end = text.lastIndexOf("]");
+  if (start === -1 || end === -1 || end <= start) return [];
+  try {
+    const arr = JSON.parse(text.slice(start, end + 1));
+    return Array.isArray(arr) ? arr : [];
+  } catch {
+    return [];
+  }
+}
+
+/** Default distiller: spawn a cheap `claude --print` pass. Fail-open → "". */
+export function defaultDistiller(prompt, opts = {}) {
+  try {
+    const model = opts.model || "haiku";
+    const args = ["--print", "--model", model, ...daemonClaudeArgs()];
+    const res = spawnSync(resolveClaudeBin(), args, {
+      input: prompt,
+      encoding: "utf8",
+      timeout: DISTILL_TIMEOUT_MS,
+      env: { ...process.env, PATH: augmentedPath() },
+      maxBuffer: 8 * 1024 * 1024,
+    });
+    if (res.status === 0 && res.stdout) return res.stdout;
+    return "";
+  } catch {
+    return "";
+  }
+}
+
+/**
+ * Capture one finished session into cards. Orchestrates the guards, distillation,
+ * normalization, and append. Always resolves (never rejects).
+ *
+ * @param {object} o - {
+ *   agentRoot, sessionId, cwd, transcriptText, cfg,
+ *   distillFn?, nowMs?, model?, maxCards?, minTurns?
+ * }
+ * @returns {Promise<{written:number, skipped:boolean, reason:string}>}
+ */
+export async function captureSession(o = {}) {
+  const { agentRoot, sessionId, cwd, transcriptText = "", cfg = {} } = o;
+  if (!agentRoot) return { written: 0, skipped: true, reason: "no-agent-root" };
+  if (cfg.enabled === false) return { written: 0, skipped: true, reason: "disabled" };
+  if (isRepoDenied(cwd, cfg)) return { written: 0, skipped: true, reason: "denylisted" };
+
+  const minTurns = Number.isFinite(o.minTurns) ? o.minTurns : (Number.isFinite(cfg.minTurnsToCapture) ? cfg.minTurnsToCapture : 2);
+  if (countUserTurns(transcriptText) < minTurns) {
+    return { written: 0, skipped: true, reason: "too-short" };
+  }
+
+  const maxCards = Number.isFinite(o.maxCards) ? o.maxCards : (Number.isFinite(cfg.maxCardsPerSession) ? cfg.maxCardsPerSession : 12);
+  const model = o.model || cfg.captureModel || "haiku";
+  const distill = o.distillFn || defaultDistiller;
+
+  let raw;
+  try {
+    raw = await distill(buildDistillPrompt(transcriptText, maxCards), { model, agentRoot });
+  } catch {
+    return { written: 0, skipped: true, reason: "distill-failed" };
+  }
+
+  const rawCards = extractCardsFromModelOutput(raw).slice(0, maxCards);
+  if (rawCards.length === 0) return { written: 0, skipped: false, reason: "no-cards" };
+
+  const ctx = {
+    sessionId: sessionId || "unknown",
+    repo: repoLabel(cwd),
+    ts: Number.isFinite(o.nowMs) ? new Date(o.nowMs).toISOString() : undefined,
+  };
+  // Pre-normalize so a single bad card doesn't poison the batch.
+  const cards = rawCards.map((c) => normalizeCard(c, ctx)).filter(Boolean);
+  const written = appendCards(agentRoot, cards, ctx);
+  // Surface the normalized cards (additive) so a second pass — e.g. the WS3
+  // skill-promoter — can inspect what was just distilled without re-reading the
+  // store. Optional `_onCards` callback mirrors it for streaming callers.
+  if (typeof o._onCards === "function") { try { o._onCards(cards); } catch { /* */ } }
+  return { written, skipped: false, reason: written ? "ok" : "no-cards", cards };
+}

package/lib/collective/capture.test.mjs

@@ -0,0 +1,121 @@
+/**
+ * capture.test.mjs — tests for session → memory-card distillation.
+ * Run: node --test lib/collective/capture.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 {
+  transcriptToText,
+  countUserTurns,
+  buildDistillPrompt,
+  extractCardsFromModelOutput,
+  captureSession,
+} from "./capture.mjs";
+import { readRecentCards } from "./cards.mjs";
+
+function tmp() {
+  return mkdtempSync(join(tmpdir(), "collective-capture-"));
+}
+
+test("transcriptToText: flattens JSONL; passes plain text through", () => {
+  const jsonl = [
+    JSON.stringify({ role: "user", content: "do the thing" }),
+    JSON.stringify({ role: "assistant", content: [{ type: "text", text: "done" }] }),
+  ].join("\n");
+  const out = transcriptToText(jsonl);
+  assert.match(out, /user: do the thing/);
+  assert.match(out, /assistant: done/);
+  assert.equal(transcriptToText("just plain text"), "just plain text");
+});
+
+test("countUserTurns: counts user/human turns", () => {
+  assert.equal(countUserTurns("user: a\nassistant: b\nuser: c"), 2);
+  assert.equal(countUserTurns("human: hi\nassistant: yo"), 1);
+  assert.equal(countUserTurns(""), 0);
+});
+
+test("buildDistillPrompt: instructs JSON-only output", () => {
+  const p = buildDistillPrompt("user: x", 5);
+  assert.match(p, /ONLY a JSON array/);
+  assert.match(p, /at most 5 cards/i);
+  assert.match(p, /SESSION TRANSCRIPT/);
+});
+
+test("extractCardsFromModelOutput: fenced, plain, and garbage", () => {
+  assert.equal(extractCardsFromModelOutput("```json\n[{\"title\":\"a\"}]\n```").length, 1);
+  assert.equal(extractCardsFromModelOutput('prose [{"title":"a"},{"title":"b"}] more').length, 2);
+  assert.deepEqual(extractCardsFromModelOutput("no json here"), []);
+  assert.deepEqual(extractCardsFromModelOutput(""), []);
+});
+
+const longTranscript = "user: please ship billing\nassistant: shipping\nuser: confirm done\nassistant: done";
+
+test("captureSession: writes distilled cards (injected distiller)", async () => {
+  const root = tmp();
+  try {
+    const distillFn = async () => JSON.stringify([
+      { kind: "decision", title: "Shipped billing migration", salience: 0.9, tags: ["billing"] },
+      { kind: "openloop", title: "Verify invoices next run", salience: 0.6 },
+    ]);
+    const res = await captureSession({
+      agentRoot: root, sessionId: "s1", cwd: "/x/maestro",
+      transcriptText: longTranscript, cfg: { enabled: true }, distillFn,
+      nowMs: Date.parse("2026-06-03T12:00:00Z"),
+    });
+    assert.equal(res.written, 2);
+    assert.equal(res.reason, "ok");
+    const cards = readRecentCards(root, { nowMs: Date.parse("2026-06-03T13:00:00Z") });
+    assert.equal(cards.length, 2);
+    assert.equal(cards.find((c) => c.kind === "decision").repo, "maestro");
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("captureSession: skips when disabled / denylisted / too short", async () => {
+  const root = tmp();
+  const distillFn = async () => "[{\"title\":\"x\"}]";
+  try {
+    assert.equal((await captureSession({ agentRoot: root, transcriptText: longTranscript, cfg: { enabled: false }, distillFn })).reason, "disabled");
+    assert.equal((await captureSession({ agentRoot: root, cwd: "/x/secret", transcriptText: longTranscript, cfg: { repoDenylist: ["secret"] }, distillFn })).reason, "denylisted");
+    assert.equal((await captureSession({ agentRoot: root, transcriptText: "user: hi", cfg: {}, distillFn })).reason, "too-short");
+    assert.equal((await captureSession({ transcriptText: longTranscript, cfg: {}, distillFn })).reason, "no-agent-root");
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("captureSession: fail-open on bad distiller output / throw", async () => {
+  const root = tmp();
+  try {
+    const garbage = await captureSession({ agentRoot: root, transcriptText: longTranscript, cfg: {}, distillFn: async () => "not json" });
+    assert.equal(garbage.written, 0);
+    assert.equal(garbage.reason, "no-cards");
+    const thrower = await captureSession({ agentRoot: root, transcriptText: longTranscript, cfg: {}, distillFn: async () => { throw new Error("boom"); } });
+    assert.equal(thrower.written, 0);
+    assert.equal(thrower.skipped, true);
+    assert.equal(thrower.reason, "distill-failed");
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("captureSession: caps cards per session", async () => {
+  const root = tmp();
+  try {
+    const many = Array.from({ length: 20 }, (_, i) => ({ kind: "fact", title: `fact ${i}`, salience: 0.5 }));
+    const res = await captureSession({
+      agentRoot: root, transcriptText: longTranscript, cfg: {}, maxCards: 5,
+      distillFn: async () => JSON.stringify(many), nowMs: Date.parse("2026-06-03T12:00:00Z"),
+    });
+    assert.equal(res.written, 5);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});

package/lib/collective/cards.mjs

@@ -0,0 +1,201 @@
+/**
+ * lib/collective/cards.mjs — the memory-card store.
+ *
+ * A "memory card" is a small, structured, durable unit of cross-session memory
+ * distilled from a finished Claude Code session — NEVER a raw transcript. Cards
+ * are append-only JSONL under `memory/collective/cards/<YYYY-MM-DD>.jsonl`, which
+ * the existing lib/rag indexer picks up as a normal source (so recall reuses the
+ * FTS5 + embedding index — no separate store).
+ *
+ * Card shape:
+ *   {
+ *     id,            // stable hash of (sessionId|kind|title)
+ *     ts,            // ISO 8601 creation time
+ *     sessionId,     // originating Claude Code session
+ *     repo,          // basename of the originating cwd (provenance, not a path)
+ *     kind,          // decision | fact | artifact | openloop | entity
+ *     title,         // one-line summary
+ *     body,          // <= BODY_MAX chars of detail
+ *     tags,          // string[]
+ *     salience,      // 0..1 importance (drives recall ranking + retention)
+ *     sourceRefs     // string[] — file paths / urls / ids touched (optional)
+ *   }
+ *
+ * Pure + fail-open: append/read never throw on a bad card or unreadable file.
+ *
+ * @module lib/collective/cards
+ */
+
+"use strict";
+
+import { existsSync, readFileSync, appendFileSync, mkdirSync, readdirSync } from "node:fs";
+import { join, basename } from "node:path";
+import { createHash } from "node:crypto";
+
+export const KINDS = Object.freeze(["decision", "fact", "artifact", "openloop", "entity", "procedure"]);
+const BODY_MAX = 600;
+const TITLE_MAX = 160;
+const CARDS_REL = "memory/collective/cards";
+
+/** Directory holding the per-day card JSONL files for an agent root. */
+export function cardsDir(agentRoot) {
+  return join(agentRoot, CARDS_REL);
+}
+
+function clamp01(n) {
+  const x = typeof n === "number" && Number.isFinite(n) ? n : 0.5;
+  return x < 0 ? 0 : x > 1 ? 1 : x;
+}
+
+function shortHash(s) {
+  return createHash("sha1").update(String(s)).digest("hex").slice(0, 12);
+}
+
+/** UTC date stamp (YYYY-MM-DD) for an ISO timestamp. */
+function dayStamp(iso) {
+  // Slice is safe for ISO strings; fall back to the raw first 10 chars.
+  return String(iso).slice(0, 10);
+}
+
+/**
+ * Validate + normalize a raw distilled card into the canonical shape. Returns
+ * null if the card has no usable title (the one hard requirement).
+ *
+ * @param {object} raw
+ * @param {object} [ctx] - { sessionId, repo, ts } defaults applied when absent
+ * @returns {object|null}
+ */
+export function normalizeCard(raw, ctx = {}) {
+  if (!raw || typeof raw !== "object") return null;
+  const title = String(raw.title || "").trim().slice(0, TITLE_MAX);
+  if (!title) return null;
+  const kind = KINDS.includes(raw.kind) ? raw.kind : "fact";
+  const ts = String(raw.ts || ctx.ts || "").trim() || isoNow(ctx);
+  const sessionId = String(raw.sessionId || ctx.sessionId || "unknown");
+  const repo = String(raw.repo || ctx.repo || "").trim();
+  const body = String(raw.body || "").trim().slice(0, BODY_MAX);
+  const tags = Array.isArray(raw.tags)
+    ? raw.tags.map((t) => String(t).trim()).filter(Boolean).slice(0, 12)
+    : [];
+  const sourceRefs = Array.isArray(raw.sourceRefs)
+    ? raw.sourceRefs.map((r) => String(r).trim()).filter(Boolean).slice(0, 20)
+    : [];
+  const salience = clamp01(raw.salience);
+  const id = String(raw.id || `card-${shortHash(`${sessionId}|${kind}|${title}`)}`);
+  return { id, ts, sessionId, repo, kind, title, body, tags, salience, sourceRefs };
+}
+
+// `ctx.ts` may be injected for deterministic tests; otherwise use wall clock.
+function isoNow(ctx) {
+  if (ctx && ctx.ts) return ctx.ts;
+  return new Date().toISOString();
+}
+
+/**
+ * Append normalized cards to today's (or each card's own date's) JSONL file.
+ * De-duplicates within the call by id. Fail-open: returns the count written, 0
+ * on any error.
+ *
+ * @param {string} agentRoot
+ * @param {object[]} cards - raw or normalized cards
+ * @param {object} [ctx] - normalization context (sessionId, repo, ts)
+ * @returns {number} number of cards written
+ */
+export function appendCards(agentRoot, cards, ctx = {}) {
+  if (!agentRoot || !Array.isArray(cards) || cards.length === 0) return 0;
+  const dir = cardsDir(agentRoot);
+  let written = 0;
+  try {
+    mkdirSync(dir, { recursive: true });
+    const seen = new Set();
+    // Group lines by day file so a batch spanning midnight lands correctly.
+    const byDay = new Map();
+    for (const raw of cards) {
+      const card = normalizeCard(raw, ctx);
+      if (!card) continue;
+      if (seen.has(card.id)) continue;
+      seen.add(card.id);
+      const day = dayStamp(card.ts);
+      if (!byDay.has(day)) byDay.set(day, []);
+      byDay.get(day).push(JSON.stringify(card));
+    }
+    for (const [day, lines] of byDay) {
+      appendFileSync(join(dir, `${day}.jsonl`), lines.join("\n") + "\n");
+      written += lines.length;
+    }
+  } catch {
+    return written;
+  }
+  return written;
+}
+
+/** Parse a JSONL file into card objects, skipping bad lines. Fail-open. */
+function readJsonl(path) {
+  try {
+    const raw = readFileSync(path, "utf8");
+    const out = [];
+    for (const line of raw.split("\n")) {
+      const t = line.trim();
+      if (!t) continue;
+      try {
+        const obj = JSON.parse(t);
+        if (obj && obj.title) out.push(obj);
+      } catch { /* skip bad line */ }
+    }
+    return out;
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Read recent cards across the last `days` day-files, newest first.
+ * Bounded by filename-date filtering first (no full-corpus scan), then `limit`.
+ *
+ * @param {string} agentRoot
+ * @param {object} [opts] - { days=45, limit=500, nowMs }
+ * @returns {object[]}
+ */
+export function readRecentCards(agentRoot, opts = {}) {
+  if (!agentRoot) return [];
+  const days = Number.isFinite(opts.days) ? opts.days : 45;
+  const limit = Number.isFinite(opts.limit) ? opts.limit : 500;
+  const nowMs = Number.isFinite(opts.nowMs) ? opts.nowMs : Date.now();
+  const cutoffMs = nowMs - days * 86400_000;
+  const dir = cardsDir(agentRoot);
+  if (!existsSync(dir)) return [];
+  let files;
+  try {
+    files = readdirSync(dir).filter((f) => /^\d{4}-\d{2}-\d{2}\.jsonl$/.test(f));
+  } catch {
+    return [];
+  }
+  // Keep only day-files within the window (by filename date), newest first.
+  files = files
+    .filter((f) => {
+      const d = Date.parse(f.slice(0, 10) + "T23:59:59Z");
+      return Number.isFinite(d) ? d >= cutoffMs : true;
+    })
+    .sort()
+    .reverse();
+  const all = [];
+  for (const f of files) {
+    for (const c of readJsonl(join(dir, f))) all.push(c);
+    if (all.length >= limit * 2) break; // soft cap before sort
+  }
+  all.sort((a, b) => String(b.ts).localeCompare(String(a.ts)));
+  return all.slice(0, limit);
+}
+
+/** Compact one-line-ish text form of a card (for digests + embedding). */
+export function cardToText(card) {
+  const tags = card.tags && card.tags.length ? ` [${card.tags.join(", ")}]` : "";
+  const body = card.body ? ` — ${card.body}` : "";
+  return `(${card.kind}) ${card.title}${body}${tags}`;
+}
+
+/** Provenance-safe repo label from a cwd (basename only, never a full path). */
+export function repoLabel(cwd) {
+  if (!cwd) return "";
+  try { return basename(cwd); } catch { return ""; }
+}

package/lib/collective/cards.test.mjs

@@ -0,0 +1,114 @@
+/**
+ * cards.test.mjs — tests for the memory-card store.
+ * Run: node --test lib/collective/cards.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 {
+  KINDS,
+  normalizeCard,
+  appendCards,
+  readRecentCards,
+  cardToText,
+  repoLabel,
+} from "./cards.mjs";
+
+function tmp() {
+  return mkdtempSync(join(tmpdir(), "collective-cards-"));
+}
+
+test("normalizeCard: requires a title", () => {
+  assert.equal(normalizeCard({ kind: "fact" }), null);
+  assert.equal(normalizeCard(null), null);
+  assert.ok(normalizeCard({ title: "x" }));
+});
+
+test("normalizeCard: kind fallback, salience clamp, stable id, ctx defaults", () => {
+  const c = normalizeCard(
+    { title: "Decided to ship", kind: "bogus", salience: 5 },
+    { sessionId: "s1", repo: "maestro", ts: "2026-06-01T00:00:00Z" },
+  );
+  assert.equal(c.kind, "fact", "unknown kind falls back to fact");
+  assert.equal(c.salience, 1, "salience clamped to [0,1]");
+  assert.equal(c.sessionId, "s1");
+  assert.equal(c.repo, "maestro");
+  assert.equal(c.ts, "2026-06-01T00:00:00Z");
+  // id is a stable hash of sessionId|kind|title
+  const c2 = normalizeCard({ title: "Decided to ship", kind: "bogus" }, { sessionId: "s1" });
+  assert.equal(c.id, c2.id, "same (session,kind,title) → same id");
+});
+
+test("normalizeCard: all KINDS preserved; body/tags truncated/cleaned", () => {
+  for (const k of KINDS) {
+    assert.equal(normalizeCard({ title: "t", kind: k }).kind, k);
+  }
+  const c = normalizeCard({
+    title: "t",
+    body: "x".repeat(5000),
+    tags: ["  a ", "", "b", 3, "c", "d", "e", "f", "g", "h", "i", "j", "k", "l"],
+  });
+  assert.ok(c.body.length <= 600);
+  assert.ok(c.tags.length <= 12);
+  assert.deepEqual(c.tags.slice(0, 4), ["a", "b", "3", "c"], "trimmed, empties dropped, non-strings coerced");
+});
+
+test("appendCards + readRecentCards: round-trip, dedup, newest-first", () => {
+  const root = tmp();
+  try {
+    const n = appendCards(
+      root,
+      [
+        { title: "older", kind: "fact", ts: "2026-06-01T10:00:00Z" },
+        { title: "newer", kind: "decision", ts: "2026-06-02T10:00:00Z" },
+        { title: "older", kind: "fact", ts: "2026-06-01T10:00:00Z" }, // dup id
+      ],
+      { sessionId: "s1", repo: "r" },
+    );
+    assert.equal(n, 2, "duplicate id collapsed");
+    const cards = readRecentCards(root, { nowMs: Date.parse("2026-06-02T12:00:00Z") });
+    assert.equal(cards.length, 2);
+    assert.equal(cards[0].title, "newer", "newest first");
+    assert.equal(cards[1].title, "older");
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("readRecentCards: day-window filtering + limit", () => {
+  const root = tmp();
+  try {
+    appendCards(root, [{ title: "ancient", ts: "2026-01-01T00:00:00Z" }], { sessionId: "s" });
+    appendCards(root, [{ title: "recent", ts: "2026-06-02T00:00:00Z" }], { sessionId: "s" });
+    const recent = readRecentCards(root, { days: 30, nowMs: Date.parse("2026-06-03T00:00:00Z") });
+    assert.equal(recent.length, 1, "ancient card outside 30-day window excluded");
+    assert.equal(recent[0].title, "recent");
+    const limited = readRecentCards(root, { days: 9999, limit: 1, nowMs: Date.parse("2026-06-03T00:00:00Z") });
+    assert.equal(limited.length, 1, "limit honored");
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("appendCards: empty/!agentRoot is a safe no-op", () => {
+  assert.equal(appendCards(null, [{ title: "x" }]), 0);
+  assert.equal(appendCards(tmp(), []), 0);
+});
+
+test("cardToText: includes kind, title, body, tags", () => {
+  const txt = cardToText({ kind: "decision", title: "Ship v2", body: "after review", tags: ["release"] });
+  assert.match(txt, /decision/);
+  assert.match(txt, /Ship v2/);
+  assert.match(txt, /after review/);
+  assert.match(txt, /release/);
+});
+
+test("repoLabel: basename only, never a full path", () => {
+  assert.equal(repoLabel("/Users/x/maestro"), "maestro");
+  assert.equal(repoLabel(""), "");
+});