brane 0.0.2 → 0.3.0

package/dist/test/model-resolution.test.js

@@ -0,0 +1,166 @@
+import { after, before, describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { createTestDb } from "./helpers.js";
+import { appendEvent } from "../db/events.js";
+import { getAgentAdapter } from "../agents.js";
+import { resolvePendingTraces } from "../memory/index.js";
+// meta.session / meta.model per-message provenance resolution (claude).
+//
+// claude's resolveTrace and the runIndex resolver read the agent's own
+// session JSONL under ~/.claude/projects/<cwd-encoded>/<id>.jsonl. We sandbox
+// HOME to a temp dir, fabricate a session log with two assistant turns on
+// *different* models (proving per-message granularity), and assert both the
+// adapter and the DB-level backfill resolve correctly.
+const SESSION = "11111111-2222-3333-4444-555555555555";
+const FOLD = "/work/proj"; // absolute fold path (stored verbatim in narratives)
+const UUID_A = "aaaaaaaa-0000-0000-0000-000000000001";
+const UUID_B = "bbbbbbbb-0000-0000-0000-000000000002";
+const SAY_A = "First narration, on the older model.";
+const SAY_B = "Second narration, after a /model switch.";
+let origHome;
+let homeDir;
+function assistantLine(uuid, model, say) {
+    return JSON.stringify({
+        type: "assistant",
+        uuid,
+        message: {
+            model,
+            role: "assistant",
+            content: [{ type: "tool_use", name: "mcp__brane__narrate", input: { say } }],
+        },
+    });
+}
+before(() => {
+    origHome = process.env.HOME;
+    homeDir = mkdtempSync(join(tmpdir(), "brane-home-"));
+    process.env.HOME = homeDir;
+    const projectDir = join(homeDir, ".claude", "projects", FOLD.replace(/\//g, "-"));
+    mkdirSync(projectDir, { recursive: true });
+    const lines = [
+        JSON.stringify({ type: "user", uuid: "user-0", message: { role: "user", content: "hi" } }),
+        assistantLine(UUID_A, "claude-opus-4-7", SAY_A),
+        assistantLine(UUID_B, "claude-opus-4-8", SAY_B),
+    ];
+    writeFileSync(join(projectDir, `${SESSION}.jsonl`), lines.join("\n") + "\n");
+});
+after(() => {
+    if (origHome === undefined)
+        delete process.env.HOME;
+    else
+        process.env.HOME = origHome;
+});
+describe("claude resolveTrace", () => {
+    const claude = getAgentAdapter("claude");
+    it("declares per-message granularity", () => {
+        assert.equal(claude.modelGranularity, "per-message");
+    });
+    it("resolves offset (uuid) + model by exact say match, per message", () => {
+        const a = claude.resolveTrace({ sessionId: SESSION, foldPath: FOLD, content: SAY_A });
+        assert.deepEqual(a, { offset: UUID_A, model: "claude-opus-4-7" });
+        const b = claude.resolveTrace({ sessionId: SESSION, foldPath: FOLD, content: SAY_B });
+        assert.deepEqual(b, { offset: UUID_B, model: "claude-opus-4-8" });
+    });
+    it("returns null on no content match and on a missing session file", () => {
+        assert.equal(claude.resolveTrace({ sessionId: SESSION, foldPath: FOLD, content: "never said" }), null);
+        assert.equal(claude.resolveTrace({ sessionId: "no-such-session", foldPath: FOLD, content: SAY_A }), null);
+    });
+});
+describe("resolvePendingTraces (runIndex backfill)", () => {
+    function seedNarrative(db, id, opts = {}) {
+        db.prepare(`INSERT INTO narratives (id, brane_id, fold_path, agent_type, role, created_at, status, agent_session_id)
+       VALUES (?, 'brane-test', ?, ?, 'worker', ?, 'active', ?)`).run(id, FOLD, opts.agent_type ?? "claude", Date.now(), opts.agent_session_id ?? null);
+    }
+    it("stamps meta.session + meta.model on self narrations, idempotently", async () => {
+        const db = createTestDb();
+        seedNarrative(db, "claude-A", { agent_session_id: SESSION });
+        appendEvent(db, "claude-A", "narration", { content: SAY_B, source: "claude-A" });
+        const n = await resolvePendingTraces(db);
+        assert.equal(n, 1);
+        const row = db.prepare("SELECT meta FROM events WHERE narrative_id = 'claude-A' AND seq = 1").get();
+        const meta = JSON.parse(row.meta);
+        assert.equal(meta.model, "claude-opus-4-8");
+        assert.deepEqual(meta.session, { id: SESSION, offset: UUID_B });
+        // Second pass resolves nothing (gated on absence of meta.model).
+        assert.equal(await resolvePendingTraces(db), 0);
+    });
+    it("attributes a FOREIGN narration to its author's session (via source)", async () => {
+        const db = createTestDb();
+        // Author A (claude, has the session) narrates into host B (any agent).
+        seedNarrative(db, "claude-A", { agent_session_id: SESSION });
+        seedNarrative(db, "goose-B", { agent_type: "goose" });
+        appendEvent(db, "goose-B", "agent_signal", { content: SAY_A, source: "claude-A" });
+        assert.equal(await resolvePendingTraces(db), 1);
+        const row = db.prepare("SELECT meta FROM events WHERE narrative_id = 'goose-B' AND seq = 1").get();
+        const meta = JSON.parse(row.meta);
+        assert.equal(meta.model, "claude-opus-4-7"); // author's model, not host's
+        assert.equal(meta.session.id, SESSION);
+    });
+    it("uses live-stamped meta.session.id when present (no agent_session_id needed)", async () => {
+        const db = createTestDb();
+        seedNarrative(db, "claude-A", { agent_session_id: null });
+        appendEvent(db, "claude-A", "narration", {
+            content: SAY_A,
+            source: "claude-A",
+            meta: { session: { id: SESSION } },
+        });
+        assert.equal(await resolvePendingTraces(db), 1);
+        const row = db.prepare("SELECT meta FROM events WHERE narrative_id = 'claude-A' AND seq = 1").get();
+        assert.equal(JSON.parse(row.meta).model, "claude-opus-4-7");
+    });
+    it("skips unsupported agents and unresolvable sessions, leaving meta unset", async () => {
+        const db = createTestDb();
+        // goose has no resolveTrace → skipped.
+        seedNarrative(db, "goose-C", { agent_type: "goose", agent_session_id: "x" });
+        appendEvent(db, "goose-C", "narration", { content: SAY_A, source: "goose-C" });
+        // claude but no session id discoverable → skipped.
+        seedNarrative(db, "claude-D", { agent_session_id: null });
+        appendEvent(db, "claude-D", "narration", { content: SAY_A, source: "claude-D" });
+        assert.equal(await resolvePendingTraces(db), 0);
+        const g = db.prepare("SELECT meta FROM events WHERE narrative_id = 'goose-C' AND seq = 1").get();
+        assert.equal(g.meta, null);
+    });
+    it("parses each session transcript once for many same-session events (memoized)", async () => {
+        const db = createTestDb();
+        seedNarrative(db, "claude-A", { agent_session_id: SESSION });
+        // Two pending events, both authored in the same session transcript.
+        appendEvent(db, "claude-A", "narration", { content: SAY_A, source: "claude-A" });
+        appendEvent(db, "claude-A", "narration", { content: SAY_B, source: "claude-A" });
+        // Spy on the claude adapter's transcript parse to count file reads.
+        const claude = getAgentAdapter("claude");
+        const orig = claude.buildTraceIndex.bind(claude);
+        let parses = 0;
+        claude.buildTraceIndex = (opts) => {
+            parses++;
+            return orig(opts);
+        };
+        try {
+            assert.equal(await resolvePendingTraces(db), 2); // both resolved
+            assert.equal(parses, 1); // …from a single transcript parse
+        }
+        finally {
+            claude.buildTraceIndex = orig;
+        }
+        const a = JSON.parse(db.prepare("SELECT meta FROM events WHERE narrative_id='claude-A' AND seq=1").get().meta);
+        const b = JSON.parse(db.prepare("SELECT meta FROM events WHERE narrative_id='claude-A' AND seq=2").get().meta);
+        assert.equal(a.model, "claude-opus-4-7");
+        assert.equal(b.model, "claude-opus-4-8");
+    });
+    it("skips a corrupt-meta row without aborting the pass (json_valid gate)", async () => {
+        const db = createTestDb();
+        seedNarrative(db, "claude-A", { agent_session_id: SESSION });
+        // A resolvable event (seq 1) plus one with corrupt meta written directly
+        // (seq 2). Without the json_valid CASE guard, json_extract on the corrupt
+        // blob would throw and abort the whole SELECT.
+        appendEvent(db, "claude-A", "narration", { content: SAY_B, source: "claude-A" });
+        appendEvent(db, "claude-A", "narration", { content: SAY_A, source: "claude-A" });
+        db.prepare("UPDATE events SET meta = '{bad json' WHERE narrative_id = 'claude-A' AND seq = 2").run();
+        // The pass completes; the corrupt row is excluded, the valid one resolves.
+        assert.equal(await resolvePendingTraces(db), 1);
+        const ok = db.prepare("SELECT meta FROM events WHERE narrative_id = 'claude-A' AND seq = 1").get();
+        assert.equal(JSON.parse(ok.meta).model, "claude-opus-4-8");
+    });
+});
+//# sourceMappingURL=model-resolution.test.js.map

package/dist/test/narrate-validate.test.js

@@ -0,0 +1,77 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { createTestDb } from "./helpers.js";
+import { handleMcpNarrate, toolFlag } from "../daemon/server.js";
+// A narrate that is going to refuse must refuse before it writes anything.
+// The failure this pins is the one an agent can't recover from gracefully: an
+// error returned for words that were in fact posted, which it will reasonably
+// post again.
+const SELF = "claude-aaaaaaaa";
+const OTHER = "claude-bbbbbbbb";
+function db() {
+    const d = createTestDb();
+    const ins = d.prepare("INSERT INTO narratives (id, brane_id, created_at, status) VALUES (?, 'brane-home', 0, 'active')");
+    ins.run(SELF);
+    ins.run(OTHER);
+    return d;
+}
+const count = (d) => d.prepare("SELECT COUNT(*) AS c FROM events").get().c;
+const summary = (d) => d.prepare("SELECT summary FROM narratives WHERE id = ?").get(SELF).summary;
+describe("narrate refuses before the first write", () => {
+    for (const [name, bad] of [
+        ["tail", { tail: "abc" }],
+        ["before", { before: { self: "nope" } }],
+        ["after", { after: [1, 2] }],
+    ]) {
+        for (const wait of [false, true]) {
+            it(`a malformed \`${name}\`${wait ? " with wait" : ""} throws and posts nothing`, () => {
+                const d = db();
+                assert.throws(() => handleMcpNarrate({ say: "hello", meta: { summary: "changed" }, wait, ...bad }, d, SELF, () => { }), /Invalid|cursor/);
+                assert.equal(count(d), 0, "no narration was appended");
+                assert.equal(summary(d), null, "no summary was written");
+            });
+        }
+    }
+    it("an unknown foreign target refuses before the summary is touched", () => {
+        const d = db();
+        const r = handleMcpNarrate({ say: "hi", nid: "claude-zzzzzzzz", meta: { summary: "changed" } }, d, SELF, () => { });
+        assert.match(r.error ?? "", /Unknown narrative/);
+        assert.equal(count(d), 0);
+        assert.equal(summary(d), null);
+    });
+    it("a well-formed call still posts", () => {
+        const d = db();
+        const r = handleMcpNarrate({ say: "hello", tail: "3" }, d, SELF, () => { });
+        assert.equal(r.seq, 1);
+        assert.equal(count(d), 1);
+    });
+});
+describe("toolFlag", () => {
+    it("reads booleans and their string spellings", () => {
+        assert.equal(toolFlag(true, false), true);
+        assert.equal(toolFlag("true", false), true);
+        assert.equal(toolFlag(false, true), false);
+        assert.equal(toolFlag("false", true), false, "a string \"false\" must not read as truthy");
+    });
+    it("falls back on anything else", () => {
+        for (const raw of [undefined, null, 1, 0, "yes", "", {}]) {
+            assert.equal(toolFlag(raw, true), true);
+            assert.equal(toolFlag(raw, false), false);
+        }
+    });
+    it("`strict: \"true\"` refuses what `strict: true` refuses", () => {
+        // A narration that won't render as written, so `strict` has something to refuse.
+        for (const strict of [true, "true"]) {
+            const d = db();
+            const r = handleMcpNarrate({ say: "$\\bogusmacro{x}$", strict }, d, SELF, () => { });
+            assert.ok(r.error, `strict: ${JSON.stringify(strict)} refuses`);
+            assert.equal(count(d), 0, "and posts nothing");
+        }
+    });
+    it("`wait: \"true\"` parks a narrate instead of quietly not waiting", () => {
+        const d = db();
+        const r = handleMcpNarrate({ say: "hello", after: 0, wait: "true" }, d, SELF, () => { });
+        assert.ok(r.park, "the plan comes back, as it does for `wait: true`");
+    });
+});
+//# sourceMappingURL=narrate-validate.test.js.map

package/dist/test/narrate-wait.test.js

@@ -0,0 +1,160 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { createTestDb } from "./helpers.js";
+import { handleMcpNarrate, narrateWaitCursor, startMcpListen, } from "../daemon/server.js";
+import { appendEvent, readEvents } from "../db/events.js";
+// `narrate({ wait: true })` is a narrate followed by a listen, in one call:
+// one re-read of the agent's context per exchange instead of two. The daemon
+// splits it the same way — `handleMcpNarrate` writes and returns a plan, and
+// the dispatcher hands the plan to `startMcpListen` — so these drive the two
+// halves exactly as the dispatcher does.
+const SELF = "claude-aaaaaaaa";
+const OTHER = "claude-bbbbbbbb";
+const BRANE = "brane-home";
+function fakeClient() {
+    const sent = [];
+    const ws = {
+        readyState: 1, // WebSocket.OPEN
+        send: (raw) => {
+            const msg = JSON.parse(raw);
+            if (msg.type === "tool_result")
+                sent.push({ callId: msg.id, result: msg.result });
+        },
+    };
+    return {
+        client: { ws: ws, narrativeId: SELF, agentType: "claude", pendingListens: new Map() },
+        sent,
+    };
+}
+function db() {
+    const d = createTestDb();
+    const ins = d.prepare("INSERT INTO narratives (id, brane_id, created_at, status) VALUES (?, ?, 0, 'active')");
+    ins.run(SELF, BRANE);
+    ins.run(OTHER, BRANE);
+    return d;
+}
+/** What the dispatcher does with a `narrate` call. */
+function narrateWait(d, c, callId, args, waiters = new Map(), settle = () => { }) {
+    const result = handleMcpNarrate({ ...args, wait: true }, d, SELF, () => { });
+    if (result.park) {
+        const { park, ...extra } = result;
+        startMcpListen(c, d, callId, { after: park.after }, waiters, settle, BRANE, {
+            omit: park.omit,
+            extra,
+        });
+    }
+    return result;
+}
+describe("narrate({ wait: true })", () => {
+    it("posts, then parks without handing back its own narration", () => {
+        const d = db();
+        const { client, sent } = fakeClient();
+        appendEvent(d, SELF, "human_signal", { content: "question?", source: "web" });
+        narrateWait(d, client, "1", { say: "answer", after: 1 });
+        assert.equal(readEvents(d, SELF, { after: 0 }).length, 2, "the narration was written");
+        assert.equal(sent.length, 0, "its own narration is not what it was waiting for");
+        assert.equal(client.pendingListens.size, 1);
+    });
+    it("wakes on the next signal, with the narration's nid and seq on the result", () => {
+        const d = db();
+        const { client, sent } = fakeClient();
+        const waiters = new Map();
+        const settled = [];
+        narrateWait(d, client, "1", { say: "done — anything else?" }, waiters, (_nid, name) => settled.push(name));
+        appendEvent(d, SELF, "human_signal", { content: "thanks", source: "web" });
+        for (const wake of waiters.get(SELF) ?? [])
+            wake();
+        assert.equal(sent.length, 1);
+        const r = sent[0].result;
+        assert.equal(r.nid, SELF);
+        assert.equal(r.seq, 1);
+        assert.equal(r.timed_out, false);
+        assert.deepEqual(r.events.self.map((e) => e.content), ["thanks"]);
+        // The row is the narrate's, so it is the narrate's row that settles.
+        assert.deepEqual(settled, ["mcp__brane__narrate"]);
+    });
+    it("returns at once when a signal landed between the cursor and the narration", () => {
+        const d = db();
+        const { client, sent } = fakeClient();
+        appendEvent(d, SELF, "human_signal", { content: "first", source: "web" });
+        appendEvent(d, SELF, "human_signal", { content: "actually, wait", source: "web" });
+        // The agent had read seq 1 and answered it; seq 2 crossed with the answer.
+        narrateWait(d, client, "1", { say: "on it", after: 1 });
+        assert.equal(sent.length, 1, "a crossed signal is not something to sleep through");
+        assert.equal(sent[0].result.waited_ms, 0);
+        assert.deepEqual(sent[0].result.events.self.map((e) => e.content), ["actually, wait"]);
+        assert.equal(sent[0].result.seq, 3);
+    });
+    it("carries rendering warnings through to the woken result", () => {
+        const d = db();
+        const { client, sent } = fakeClient();
+        const waiters = new Map();
+        narrateWait(d, client, "1", { say: "The identity $\\bogusmacro{x}$ holds." }, waiters);
+        appendEvent(d, SELF, "human_signal", { content: "ok", source: "web" });
+        for (const wake of waiters.get(SELF) ?? [])
+            wake();
+        assert.equal(sent[0].result.warnings?.[0].kind, "math_parse_error");
+    });
+    it("watches every narrative in a multi-narrative cursor", () => {
+        const d = db();
+        const { client, sent } = fakeClient();
+        const waiters = new Map();
+        narrateWait(d, client, "1", { say: "waiting on you both", after: { self: 0, [OTHER]: 0 } }, waiters);
+        assert.equal(sent.length, 0, "our own narration does not end the wait");
+        appendEvent(d, OTHER, "narration", { content: "worker done", source: OTHER });
+        for (const wake of waiters.get(OTHER) ?? [])
+            wake();
+        assert.equal(sent.length, 1);
+        assert.deepEqual(sent[0].result.events[OTHER].map((e) => e.content), ["worker done"]);
+        assert.deepEqual(sent[0].result.events.self, []);
+    });
+    it("narrates into another narrative and waits on both sides of the exchange", () => {
+        const d = db();
+        const { client, sent } = fakeClient();
+        const waiters = new Map();
+        appendEvent(d, OTHER, "narration", { content: "earlier", source: OTHER });
+        const plan = narrateWait(d, client, "1", { say: "can you take this?", nid: OTHER }, waiters);
+        assert.equal(plan.nid, OTHER);
+        assert.equal(plan.seq, 2);
+        // No `after`: both narratives from their current heads, so neither the
+        // history nor our own agent_signal comes back.
+        assert.deepEqual(plan.park.after, { self: 0, [OTHER]: 2 });
+        assert.equal(sent.length, 0);
+        appendEvent(d, OTHER, "narration", { content: "on it", source: OTHER });
+        for (const wake of waiters.get(OTHER) ?? [])
+            wake();
+        assert.deepEqual(sent[0].result.events[OTHER].map((e) => e.content), ["on it"]);
+    });
+    it("leaves a foreign narration out even when the cursor would include it", () => {
+        const d = db();
+        const { client, sent } = fakeClient();
+        narrateWait(d, client, "1", { say: "ping", nid: OTHER, after: { self: 0, [OTHER]: 0 } });
+        assert.equal(sent.length, 0, "our agent_signal in OTHER is not a reply");
+        assert.equal(client.pendingListens.size, 1);
+    });
+    it("with `before` or `tail`, posts as a plain narrate and says it did not wait", () => {
+        const d = db();
+        for (const extra of [{ tail: 5 }, { before: 3, after: 0 }]) {
+            const r = handleMcpNarrate({ say: "hi", wait: true, ...extra }, d, SELF, () => { });
+            assert.ok(!("park" in r));
+            assert.ok("events" in r, "a receipt, as without wait");
+            assert.match(String(r.wait_ignored), /call `listen` next/);
+        }
+        assert.equal(readEvents(d, SELF, { after: 0 }).length, 2, "both narrations were posted");
+    });
+    it("accepts any cursor listen accepts, and fills omitted heads", () => {
+        assert.deepEqual(narrateWaitCursor({ after: 4 }, SELF), { after: { self: 4 } });
+        assert.deepEqual(narrateWaitCursor({ after: { [SELF]: 4, [OTHER]: 1 } }, SELF), { after: { [SELF]: 4, [OTHER]: 1 } });
+        assert.deepEqual(narrateWaitCursor({}, SELF), { after: { self: undefined } });
+        assert.deepEqual(narrateWaitCursor({ nid: SELF }, SELF), { after: { self: undefined } });
+        assert.deepEqual(narrateWaitCursor({ nid: OTHER }, SELF), { after: { self: undefined, [OTHER]: undefined } });
+    });
+    it("without wait, narrate still answers with a receipt and parks nothing", () => {
+        const d = db();
+        const r = handleMcpNarrate({ say: "hello", after: 0 }, d, SELF, () => { });
+        assert.ok(!("park" in r));
+        assert.ok("events" in r);
+        assert.ok(!("wait_ignored" in r), "a receipt reads exactly as it always has");
+    });
+});
+//# sourceMappingURL=narrate-wait.test.js.map

package/dist/test/narrative-format.test.js

@@ -0,0 +1,219 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { agentTypeOf, formatActivitySpan, formatCost, formatCostTotals, formatInvocation, formatSystemContent, isSystemEvent, relPart, systemLine, restartedContent, revivedContent, runningContent, spawnedContent, } from "../shared/narrative-format.js";
+// Every case pins `now` explicitly. These functions feed four surfaces (the
+// list card, the page header, the switcher, and the HTML export), so a change
+// in wording here is a change in all four — which is the point of them living
+// in one module, and the reason they're worth pinning.
+// Local-clock fixtures, deliberately: `relPart` formats absolute dates with
+// local getters (`d.getMonth()`, `d.getFullYear()`), so a `Date.UTC` fixture
+// would be constructed on one clock and read on another. Noon hides that
+// almost everywhere — but at UTC+13/+14 the date rolls and the assertions
+// shift by a day, which is how a green CI ships a test that fails in Auckland.
+const NOW = new Date(2026, 6, 28, 12, 0, 0).getTime(); // 2026-07-28T12:00 local
+const SEC = 1000;
+const MIN = 60 * SEC;
+const HOUR = 60 * MIN;
+const DAY = 24 * HOUR;
+describe("relPart", () => {
+    it("floors sub-minute to seconds, never to zero", () => {
+        assert.deepEqual(relPart(NOW - 30 * SEC, NOW), { val: "30s", ago: true });
+        // A just-written event is "1s ago", not "0s ago".
+        assert.deepEqual(relPart(NOW, NOW), { val: "1s", ago: true });
+    });
+    it("steps up through minutes, hours, and days", () => {
+        assert.deepEqual(relPart(NOW - 5 * MIN, NOW), { val: "5m", ago: true });
+        assert.deepEqual(relPart(NOW - 3 * HOUR, NOW), { val: "3h", ago: true });
+        assert.deepEqual(relPart(NOW - 3 * DAY, NOW), { val: "3d", ago: true });
+    });
+    it("switches to an absolute date past a week, dropping the 'ago' suffix", () => {
+        const p = relPart(NOW - 10 * DAY, NOW);
+        assert.equal(p.ago, false);
+        assert.match(p.val, /^Jul \d+$/);
+    });
+    it("includes the year only when it differs from the reference year", () => {
+        const sameYear = relPart(new Date(2026, 0, 15, 12).getTime(), NOW);
+        assert.equal(sameYear.val, "Jan 15");
+        const priorYear = relPart(new Date(2025, 0, 15, 12).getTime(), NOW);
+        assert.equal(priorYear.val, "Jan 15, 2025");
+    });
+});
+describe("formatActivitySpan", () => {
+    it("collapses to one value when there is no distinct last activity", () => {
+        assert.equal(formatActivitySpan(NOW - 3 * HOUR, null, NOW), "3h ago");
+        assert.equal(formatActivitySpan(NOW - 3 * HOUR, undefined, NOW), "3h ago");
+    });
+    it("treats activity within a minute of creation as no span at all", () => {
+        const created = NOW - 3 * HOUR;
+        assert.equal(formatActivitySpan(created, created + 30 * SEC, NOW), "3h ago");
+    });
+    it("shares one 'ago' when both ends are relative", () => {
+        assert.equal(formatActivitySpan(NOW - 3 * DAY, NOW - 4 * HOUR, NOW), "3d to 4h ago");
+    });
+    it("collapses a span whose ends round to the same value", () => {
+        assert.equal(formatActivitySpan(NOW - 3 * DAY, NOW - 3 * DAY - 2 * MIN, NOW), "3d ago");
+    });
+    it("spells out each end when one is an absolute date", () => {
+        const span = formatActivitySpan(NOW - 10 * DAY, NOW - 4 * HOUR, NOW);
+        assert.match(span, /^Jul \d+ to 4h ago$/);
+    });
+    it("is anchored to the passed instant, not wall-clock time", () => {
+        // The export pins `now` to its snapshot instant; the same inputs must give
+        // the same string tomorrow.
+        const created = NOW - 3 * DAY;
+        assert.equal(formatActivitySpan(created, null, NOW), "3d ago");
+        // Four days later the same event is past the week boundary, so it becomes
+        // an absolute date and loses the "ago" suffix.
+        assert.equal(formatActivitySpan(created, null, NOW + 4 * DAY), "Jul 25");
+    });
+});
+describe("formatCostTotals", () => {
+    it("lists units side by side, never adding them", () => {
+        assert.equal(formatCostTotals([{ unit: "USD", amount: 2433.74 }, { unit: "AIC", amount: 100.2 }]), "$2433.74 · 100.2 AIC");
+    });
+    it("is null with nothing metered", () => {
+        assert.equal(formatCostTotals([]), null);
+        assert.equal(formatCostTotals(undefined), null);
+    });
+});
+describe("formatCost", () => {
+    it("renders USD to two decimals with a leading $", () => {
+        assert.equal(formatCost(26.34, "USD"), "$26.34");
+        assert.equal(formatCost(6.8, "USD"), "$6.80");
+    });
+    // Non-USD units group per the *runtime's* locale — `toLocaleString()` is
+    // called without one, so a German viewer sees "1.200 AIC". That's deliberate
+    // (the app renders for whoever is looking), which makes hardcoding "1,200
+    // AIC" a test that fails on a German developer's laptop and passes in CI.
+    // Assert the shape — grouped number, space, unit — not one locale's commas.
+    it("renders any other unit as a grouped number plus the unit", () => {
+        assert.equal(formatCost(1200, "AIC"), `${(1200).toLocaleString()} AIC`);
+        assert.ok(/^1\D?200 AIC$/.test(formatCost(1200, "AIC")), "thousands are grouped");
+    });
+    it("clamps a fractional non-USD amount to two decimals", () => {
+        assert.equal(formatCost(1200.567, "AIC"), `${(1200.567).toLocaleString(undefined, { maximumFractionDigits: 2 })} AIC`);
+        // Whatever the separators, the fraction is two digits, not three.
+        assert.match(formatCost(1200.567, "AIC"), /^1\D?200\D57 AIC$/);
+    });
+    it("returns null when there is nothing to show", () => {
+        assert.equal(formatCost(null, "USD"), null);
+        assert.equal(formatCost(undefined, "USD"), null);
+        assert.equal(formatCost(26.34, null), null);
+        assert.equal(formatCost(26.34, ""), null);
+    });
+    it("keeps a genuine zero rather than treating it as absent", () => {
+        assert.equal(formatCost(0, "USD"), "$0.00");
+    });
+});
+describe("isSystemEvent", () => {
+    it("is false for everything anyone actually said", () => {
+        for (const t of ["narration", "human_signal", "agent_signal"]) {
+            assert.equal(isSystemEvent(t), false, t);
+        }
+    });
+    it("is true for the daemon's own lifecycle events", () => {
+        for (const t of ["started", "restarted", "binding_rejected"]) {
+            assert.equal(isSystemEvent(t), true, t);
+        }
+    });
+    it("treats an unknown type as system — the safe default", () => {
+        // A new lifecycle type should render as a system row on day one, not as
+        // something an agent said.
+        assert.equal(isSystemEvent("some_future_type"), true);
+    });
+});
+describe("lifecycle lines", () => {
+    // The line every narrative opens with, in the shape every writer shares:
+    // verb, invocation as a code span, role as a /protocol.
+    it("spawn: the operator's invocation and the role", () => {
+        assert.equal(spawnedContent("claude", "worker"), "Spawned `claude` /worker");
+        assert.equal(spawnedContent("claude", "worker", { args: ["--model", "opus-5", "--dangerously-skip-permissions"] }), "Spawned `claude --model opus-5 --dangerously-skip-permissions` /worker");
+    });
+    it("twin: the predecessor stays a bare nid:seq so it linkifies", () => {
+        assert.equal(spawnedContent("claude", "twin", { from: "claude-aaaaaaaa:42" }), "Spawned `claude` /twin from claude-aaaaaaaa:42");
+    });
+    it("revive: same shape, flagged when the resume forked a live original", () => {
+        assert.equal(revivedContent("claude", "worker"), "Revived `claude` /worker");
+        assert.equal(revivedContent("claude", "keeper", ["--dangerously-skip-permissions"], true), "Revived `claude --dangerously-skip-permissions` /keeper (forked — original still live)");
+    });
+    it("utility: the command is the whole line", () => {
+        assert.equal(runningContent(["lazygit"]), "Running `lazygit`");
+        assert.equal(restartedContent(["htop", "-d", "5"]), "Restarted `htop -d 5`");
+    });
+    it("quotes an argument the way a shell would want it typed", () => {
+        assert.equal(formatInvocation(["codex", "-c", 'project_root_markers=[".git"]']), "`codex -c 'project_root_markers=[\".git\"]'`");
+        assert.equal(formatInvocation(["sh", "-c", "echo it's"]), "`sh -c 'echo it'\\''s'`");
+    });
+    it("widens the code fence around a backtick instead of breaking it", () => {
+        assert.equal(formatInvocation(["echo", "a`b"]), "`` echo 'a`b' ``");
+    });
+});
+describe("formatSystemContent", () => {
+    // Rows written before the invocation shape existed, brought up to it at
+    // render time. Each is anchored to the whole line.
+    it("rewrites a legacy spawn line: code-span the agent, slash the role", () => {
+        assert.equal(formatSystemContent("Spawned claude (worker)"), "Spawned `claude` /worker");
+    });
+    it("accepts any role, not just the ones brane ships", () => {
+        assert.equal(formatSystemContent("Spawned claude (haruspex)"), "Spawned `claude` /haruspex");
+        assert.equal(formatSystemContent("Spawned claude (twin-2)"), "Spawned `claude` /twin-2");
+    });
+    it("rewrites the old twin back-pointer into a full spawn line, given the agent", () => {
+        assert.equal(formatSystemContent("Twinned from claude-aaaaaaaa:42", "goose"), "Spawned `goose` /twin from claude-aaaaaaaa:42");
+        // The old line never recorded the agent; without one, the protocol alone.
+        assert.equal(formatSystemContent("Twinned from claude-aaaaaaaa:42"), "/twin from claude-aaaaaaaa:42");
+    });
+    it("reads the agent off a spawned narrative id", () => {
+        assert.equal(agentTypeOf("claude-rfhbth2v"), "claude");
+        assert.equal(agentTypeOf("my-agent-0a1b2c3d"), "my-agent");
+    });
+    it("rewrites a legacy revive, keeping its parenthesised prose", () => {
+        assert.equal(formatSystemContent("Revived claude session"), "Revived `claude`");
+        assert.equal(formatSystemContent("Revived claude session (forked — original still live)"), "Revived `claude` (forked — original still live)");
+    });
+    it("rewrites a legacy utility line", () => {
+        assert.equal(formatSystemContent("Running lazygit"), "Running `lazygit`");
+        assert.equal(formatSystemContent("Restarted htop -d 5"), "Restarted `htop -d 5`");
+    });
+    it("is idempotent: a line already in the new shape passes through", () => {
+        for (const s of [
+            spawnedContent("claude", "worker", { args: ["--model", "opus-5"] }),
+            spawnedContent("claude", "twin", { from: "claude-aaaaaaaa:42" }),
+            revivedContent("claude", "worker", [], true),
+            runningContent(["lazygit"]),
+        ]) {
+            assert.equal(formatSystemContent(s, "goose"), s);
+        }
+    });
+    it("only rewrites a whole line — prose that starts with a verb is left alone", () => {
+        const s = "Spawned claude (worker) after a restart";
+        assert.equal(formatSystemContent(s), s);
+    });
+    it("passes through content with no legacy shape", () => {
+        assert.equal(formatSystemContent("Connected external MCP client"), "Connected external MCP client");
+    });
+    it("tolerates trailing whitespace", () => {
+        assert.equal(formatSystemContent("Spawned claude (worker)  "), "Spawned `claude` /worker");
+    });
+});
+describe("systemLine", () => {
+    // The fold is a column on the narrative row and whether to show it is the
+    // event type — neither is read out of the text.
+    it("appends the row's fold to a started line as a brane://fold link", () => {
+        assert.equal(systemLine({ type: "started", content: "Spawned `claude` /worker" }, { fold: "~/dev/brane" }), "Spawned `claude` /worker in [~/dev/brane](brane://fold/~/dev/brane)");
+        assert.equal(systemLine({ type: "started", content: "Running `lazygit`" }, { fold: "~/dev/brane" }), "Running `lazygit` in [~/dev/brane](brane://fold/~/dev/brane)");
+    });
+    it("leaves a restarted line and a narrative without a fold alone", () => {
+        assert.equal(systemLine({ type: "restarted", content: "Revived `claude` /worker" }, { fold: "~/dev/brane" }), "Revived `claude` /worker");
+        assert.equal(systemLine({ type: "started", content: "Connected external MCP client" }, {}), "Connected external MCP client");
+    });
+    it("normalizes a legacy line first, then appends the fold", () => {
+        assert.equal(systemLine({ type: "started", content: "Twinned from claude-aaaaaaaa:42" }, { agent: "claude", fold: "~/dev/brane" }), "Spawned `claude` /twin from claude-aaaaaaaa:42 in [~/dev/brane](brane://fold/~/dev/brane)");
+    });
+    it("drops a fold the interim writers baked in, by equality with the row's own", () => {
+        assert.equal(systemLine({ type: "started", content: "Spawned `claude` /worker in ~/dev/brane" }, { fold: "~/dev/brane" }), "Spawned `claude` /worker in [~/dev/brane](brane://fold/~/dev/brane)");
+        // A different trailing path is content, not the baked fold.
+        assert.equal(systemLine({ type: "started", content: "Spawned `claude` /worker in ~/dev/other" }, { fold: "~/dev/brane" }), "Spawned `claude` /worker in ~/dev/other in [~/dev/brane](brane://fold/~/dev/brane)");
+    });
+});
+//# sourceMappingURL=narrative-format.test.js.map