Local-first 🧠memory for Hermes Agent that lives in your Obsidian vault and remembers project context. Nightly 😴 dream passes turn repeat corrections into confirmed preferences with measurable confidence. Adapters ship for Claude Code, Codex, and OpenClaw, with an MCP server for anything else.
TypeScript
/**
* The SessionStart cross-agent log catch-up lane (t_3b44cd9a).
*
* Opt-in, read-only: when `log_catchup_enabled` resolves on, the hook
* hands the agent the `Brain/log` lines OTHER agents appended since the
* lane's last look - newest first under the per-lane cap, with a count of
* older ones - under the shared untrusted-content fence. The cursor is an
* un-synced `(date, shardId, line)` watermark in the derived store, never
* a row in `Brain/log`: the lane is a pure read, and `Brain/log` is
* byte-identical after every run.
*/
import { afterEach, beforeEach, describe, expect, setDefaultTimeout, test } from "bun:test";
import {
existsSync,
mkdtempSync,
readFileSync,
readdirSync,
rmSync,
statSync,
writeFileSync,
} from "node:fs";
import { tmpdir } from "node:os";
import { dirname, join, resolve } from "node:path";
import { fileURLToPath } from "node:url";
import { bootstrapBrain } from "../../src/core/brain/init.ts";
import { appendLogEvent } from "../../src/core/brain/log.ts";
import { BRAIN_LOG_EVENT_KIND } from "../../src/core/brain/types.ts";
import { DERIVED_STORE_DIR } from "../../src/core/brain/path-constants.ts";
import {
firstRunScanCutoffDate,
logCatchupCursorFilename,
logCatchupCursorPath,
LOG_CATCHUP_FIRST_RUN_WINDOW_DATES,
LOG_CATCHUP_WINDOW_DATES,
} from "../../hooks/lib/log-cursor-state.ts";
import { homeEnv } from "../helpers/platform.ts";
import { CLI_SPAWN_BUDGET_MS } from "../helpers/cli-timeout.ts";
// Tests here spawn processes; see tests/helpers/cli-timeout.ts.
setDefaultTimeout(CLI_SPAWN_BUDGET_MS);
const HOOK = resolve(
dirname(fileURLToPath(import.meta.url)),
"..",
"..",
"hooks",
"log-catchup.ts",
);
const NOW = "2026-10-17T10:00:00Z";
let vault: string;
let configHome: string;
beforeEach(() => {
vault = mkdtempSync(join(tmpdir(), "o2b-catchup-vault-"));
configHome = mkdtempSync(join(tmpdir(), "o2b-catchup-cfg-"));
bootstrapBrain(vault);
});
afterEach(() => {
rmSync(vault, { recursive: true, force: true });
rmSync(configHome, { recursive: true, force: true });
});
interface RunResult {
readonly stdout: string;
readonly stderr: string;
readonly exit: number;
}
async function runHook(payload: unknown, env: Record<string, string> = {}): Promise<RunResult> {
const inherited: Record<string, string> = {
PATH: process.env["PATH"] ?? "",
...homeEnv(configHome),
};
const proc = Bun.spawn(["bun", "run", HOOK], {
stdin: "pipe",
stdout: "pipe",
stderr: "pipe",
env: { ...inherited, ...env },
});
proc.stdin.write(JSON.stringify(payload));
await proc.stdin.end();
const stdout = await new Response(proc.stdout).text();
const stderr = await new Response(proc.stderr).text();
const exit = await proc.exited;
return { stdout, stderr, exit };
}
/** The flag-on environment for the agent the lane runs as. */
function flagOn(self: string | null): Record<string, string> {
const env: Record<string, string> = {
OPEN_SECOND_BRAIN_LOG_CATCHUP_ENABLED: "true",
VAULT_DIR: vault,
};
if (self !== null) env["VAULT_AGENT_NAME"] = self;
return env;
}
const SESSION_START = { hook_event_name: "SessionStart" };
interface InjectedPayload {
readonly hookSpecificOutput?: {
readonly hookEventName?: string;
readonly additionalContext?: string;
};
}
/** The additionalContext of a run that emitted, or null when silent. */
function emitted(run: RunResult): string | null {
if (run.stdout.trim().length === 0) return null;
const payload = JSON.parse(run.stdout) as InjectedPayload;
return payload.hookSpecificOutput?.additionalContext ?? null;
}
/** Append one note-kind event for `agent`, pinned to the legacy un-sharded pair by default. */
function seed(
agent: string,
text: string,
opts: { timestamp?: string; deviceId?: string } = {},
): void {
appendLogEvent(
vault,
{
timestamp: opts.timestamp ?? NOW,
eventType: BRAIN_LOG_EVENT_KIND.note,
agent,
body: { text },
},
{ deviceId: opts.deviceId ?? "" },
);
}
/** Byte fingerprint of every file under `Brain/log`, for the pure-read pin. */
function logFingerprint(): string {
const root = join(vault, "Brain", "log");
const parts: string[] = [];
const walk = (dir: string): void => {
for (const entry of readdirSync(dir, { withFileTypes: true }).toSorted((a, b) =>
a.name.localeCompare(b.name),
)) {
const abs = join(dir, entry.name);
if (entry.isDirectory()) walk(abs);
else parts.push(`${abs}:${statSync(abs).size}:${readFileSync(abs, "utf8")}`);
}
};
if (existsSync(root)) walk(root);
return parts.join("\u0000");
}
/** The cursor file for one identity on this vault (the hook's own path rule). */
function cursorPath(identity = "agent-b"): string {
return logCatchupCursorPath(vault, identity);
}
describe("log-catchup hook (SessionStart)", () => {
test("flag off is an immediate no-op with zero output and no cursor", async () => {
seed("agent-a", "did the thing");
const r = await runHook(SESSION_START, { VAULT_DIR: vault });
expect(r.exit).toBe(0);
expect(r.stdout).toBe("");
expect(existsSync(cursorPath())).toBe(false);
});
test("hands agent B exactly agent A's lines since B's cursor, self lines filtered", async () => {
seed("agent-a", "agent a did the first thing");
seed("agent-b", "agent b wrote this one itself");
seed("agent-a", "agent a did the second thing");
const r = await runHook(SESSION_START, flagOn("agent-b"));
expect(r.exit).toBe(0);
expect(r.stderr).toBe("");
const context = emitted(r);
expect(context).not.toBeNull();
// Only the other agent's lines, framed as untrusted content.
expect(context).toContain("untrusted_source");
expect(context).toContain("agent a did the first thing");
expect(context).toContain("agent a did the second thing");
expect(context).not.toContain("agent b wrote this one itself");
expect(context).toContain("agent-a");
});
test("the log is byte-identical after every run - the lane is a pure read", async () => {
seed("agent-a", "before the run");
const before = logFingerprint();
await runHook(SESSION_START, flagOn("agent-b"));
expect(logFingerprint()).toBe(before);
const second = await runHook(SESSION_START, flagOn("agent-b"));
expect(logFingerprint()).toBe(before);
expect(emitted(second)).toBeNull();
});
test("a second run with no new lines emits nothing", async () => {
seed("agent-a", "once");
expect(emitted(await runHook(SESSION_START, flagOn("agent-b")))).not.toBeNull();
const again = await runHook(SESSION_START, flagOn("agent-b"));
expect(again.exit).toBe(0);
expect(again.stdout).toBe("");
});
test("the cursor survives as a (date, shardId, line) watermark in the derived store", async () => {
seed("agent-a", "watermark me");
await runHook(SESSION_START, flagOn("agent-b"));
const raw = readFileSync(cursorPath(), "utf8");
const cursor = JSON.parse(raw) as {
date: string;
shardId: string;
line: number;
shards: Record<string, number>;
};
expect(cursor.date).toBe(NOW.slice(0, 10));
expect(cursor.shardId).toBe("");
expect(cursor.line).toBe(0);
expect(cursor.shards[""]).toBe(0);
});
test("an over-long foreign line renders truncated and shorter lines still show", async () => {
// neutralizeSingleLine does not bound length, so one untrusted
// 10k-char line would blow the whole block budget; the char-cap trim
// loop peels oldest-first, drops every shorter line, then cannot fit
// the long one either - the lane goes silent forever and the frozen
// cursor rescans the same history every session. A per-line cap must
// keep every rendered line fittable.
seed("agent-a", "a short line that must survive");
const hugeText = `huge ${"x".repeat(10000)}`;
seed("agent-a", hugeText, { timestamp: "2026-10-17T10:01:00Z" });
const r = await runHook(SESSION_START, flagOn("agent-b"));
expect(r.exit).toBe(0);
const context = emitted(r);
expect(context).not.toBeNull();
expect(context).toContain("a short line that must survive");
// The long line shows its head, truncated under the per-line cap -
// never the full 10k characters.
expect(context).toContain("huge xxxxxxxxxxxxxxxxxxxx");
expect(context).not.toContain(hugeText);
expect(context).not.toContain("x".repeat(600));
// The watermark still covers both scanned lines.
const cursor = JSON.parse(readFileSync(cursorPath(), "utf8")) as {
shards: Record<string, number>;
};
expect(cursor.shards[""]).toBe(1);
});
test("a solo agent's silent run still advances the cursor", async () => {
// Every scanned line is self-authored, so nothing is collected and
// nothing may be emitted - but the scan DID advance past lines. If
// the watermark is not parked, every SessionStart rescans the whole
// history from the beginning, forever.
seed("agent-b", "my own first line");
seed("agent-b", "my own second line");
const first = await runHook(SESSION_START, flagOn("agent-b"));
expect(first.exit).toBe(0);
expect(first.stdout).toBe("");
const cursor = JSON.parse(readFileSync(cursorPath(), "utf8")) as {
date: string;
shards: Record<string, number>;
};
expect(cursor.date).toBe(NOW.slice(0, 10));
expect(cursor.shards[""]).toBe(1);
// The second run then scans nothing new and stays silent.
const second = await runHook(SESSION_START, flagOn("agent-b"));
expect(second.exit).toBe(0);
expect(second.stdout).toBe("");
});
test("a shard named like an Object.prototype member still gets a cursor", async () => {
// DEVICE_ID_RE admits lowercase names such as "constructor" and
// "valueOf"; shard-keyed plain objects inherit those members, so the
// mark for such a shard silently becomes a function and the cursor
// write fails validation - the lane goes silent and rescans forever.
seed("agent-a", "a line from the constructor shard", { deviceId: "constructor" });
const first = await runHook(SESSION_START, flagOn("agent-b"));
expect(emitted(first)).not.toBeNull();
const cursor = JSON.parse(readFileSync(cursorPath(), "utf8")) as {
shards: Record<string, number>;
};
expect(cursor.shards["constructor"]).toBe(0);
const second = await runHook(SESSION_START, flagOn("agent-b"));
expect(second.exit).toBe(0);
expect(emitted(second)).toBeNull();
});
test("a backfilled line with an earlier timestamp still surfaces and marks its true file index", async () => {
// A shard whose timestamps go backwards (backfill, clock skew) does
// not merge in file order, so an index COUNTED in merge order does
// not name the entry's position in the file. The watermark must ride
// the true per-shard file index, or this backfill - file line 1 but
// merge-first at 10:03 - reads as "line 0, already seen" and is lost.
seed("agent-a", "the on-time line", { timestamp: "2026-10-17T10:05:00Z" });
const first = await runHook(SESSION_START, flagOn("agent-b"));
expect(emitted(first)).not.toBeNull();
seed("agent-a", "the backfilled line", { timestamp: "2026-10-17T10:03:00Z" });
const second = await runHook(SESSION_START, flagOn("agent-b"));
expect(second.exit).toBe(0);
const context = emitted(second);
expect(context).not.toBeNull();
expect(context).toContain("the backfilled line");
// The mark carries the true file index of the backfill, not the
// merge-order count.
const cursor = JSON.parse(readFileSync(cursorPath(), "utf8")) as {
shards: Record<string, number>;
};
expect(cursor.shards[""]).toBe(1);
});
test("each identity on one vault keeps its own cursor", async () => {
// Several runtimes share a device and a vault but carry different
// VAULT_AGENT_NAMEs; a vault-wide cursor would let whichever runs
// first advance the watermark past lines the others never saw.
seed("agent-a", "a line meant for agent b");
seed("agent-c", "a line meant for agent a");
expect(emitted(await runHook(SESSION_START, flagOn("agent-b")))).not.toBeNull();
expect(existsSync(cursorPath("agent-b"))).toBe(true);
// Agent b's cursor must not speak for agent a: no file yet, and the
// line addressed to a is still there when a's turn comes.
expect(existsSync(cursorPath("agent-a"))).toBe(false);
const asA = await runHook(SESSION_START, flagOn("agent-a"));
const contextA = emitted(asA);
expect(contextA).not.toBeNull();
expect(contextA).toContain("a line meant for agent a");
expect(existsSync(cursorPath("agent-a"))).toBe(true);
});
test("a legacy vault-wide cursor file is ignored, and the identity file replaces it", async () => {
// Lenient migration: the pre-identity file named what SOME identity
// on this device last saw, so reading it could hide lines from the
// identity now asking. A fresh start replays history under the
// lane's caps instead of risking that silence.
const { mkdirSync } = await import("node:fs");
mkdirSync(dirname(cursorPath()), { recursive: true });
writeFileSync(
cursorPath().replace(/log-catchup\.[^/]*\.cursor\.json$/, "log-catchup.cursor.json"),
JSON.stringify({
date: NOW.slice(0, 10),
shardId: "",
line: 99,
shards: { "": 99 },
}),
"utf8",
);
seed("agent-a", "buried by the legacy watermark if it were read");
const r = await runHook(SESSION_START, flagOn("agent-b"));
expect(r.exit).toBe(0);
const context = emitted(r);
expect(context).not.toBeNull();
expect(context).toContain("buried by the legacy watermark if it were read");
expect(existsSync(cursorPath("agent-b"))).toBe(true);
});
test("two identities the sanitizer collides get distinct cursor files", () => {
// The `[^A-Za-z0-9._-] -> _` rule alone is not one-to-one: "agent b",
// "agent/b" and "agent_b" all sanitize to "agent_b", and one would
// read the other's watermark. The file name therefore carries a short
// digest of the RAW identity beside the sanitized form.
const a = logCatchupCursorFilename("agent b");
const b = logCatchupCursorFilename("agent/b");
const c = logCatchupCursorFilename("agent_b");
for (const name of [a, b, c]) {
expect(name).toMatch(/^log-catchup\.agent_b-[0-9a-f]{8}\.cursor\.json$/);
}
expect(new Set([a, b, c]).size).toBe(3);
});
test("an identity name that could traverse is sanitized in the cursor file name", async () => {
seed("agent-a", "a line under a hostile identity");
const hostile = await runHook(SESSION_START, flagOn("../../evil"));
expect(hostile.exit).toBe(0);
expect(emitted(hostile)).not.toBeNull();
// The written cursor stays inside the derived store under the
// sanitized name; nothing escaped the vault directory.
expect(existsSync(cursorPath("../../evil"))).toBe(true);
const escaped = readdirSync(join(vault, DERIVED_STORE_DIR)).filter((name) =>
name.endsWith(".json"),
);
expect(escaped).toEqual([logCatchupCursorFilename("../../evil")]);
});
test("a shard that syncs in late for an earlier date still surfaces", async () => {
// Cross-device sync delay is the NORMAL case: yesterday's shard can
// land after the cursor already moved to today. A date-level skip
// would drop it forever; the skip decision must be per (date, shard)
// against the windowed marks.
seed("agent-a", "yesterdays early line", {
timestamp: "2026-10-16T09:00:00Z",
deviceId: "dev-a",
});
seed("agent-a", "todays line", { timestamp: "2026-10-17T09:00:00Z", deviceId: "dev-a" });
expect(emitted(await runHook(SESSION_START, flagOn("agent-b")))).not.toBeNull();
seed("agent-a", "yesterdays late-synced line", {
timestamp: "2026-10-16T10:00:00Z",
deviceId: "dev-c",
});
const r = await runHook(SESSION_START, flagOn("agent-b"));
expect(r.exit).toBe(0);
const context = emitted(r);
expect(context).not.toBeNull();
expect(context).toContain("yesterdays late-synced line");
expect(context).not.toContain("yesterdays early line");
});
test("a shard that syncs in late for a date with no local file still surfaces", async () => {
// The windowed marks only cover dates that HAD files when the cursor
// last parked, but the window itself is a range of calendar dates:
// one device can own a whole day whose shard reaches this device
// only after the cursor already moved past it. Keying the date skip
// on the recorded `days` marks (instead of the calendar window)
// would drop that day's lines forever - the normal cross-device
// case the lane exists for.
seed("agent-a", "todays line", { timestamp: "2026-10-17T09:00:00Z", deviceId: "dev-a" });
expect(emitted(await runHook(SESSION_START, flagOn("agent-b")))).not.toBeNull();
seed("agent-a", "late shard for a day that had no local file", {
timestamp: "2026-10-16T09:00:00Z",
deviceId: "dev-c",
});
const r = await runHook(SESSION_START, flagOn("agent-b"));
expect(r.exit).toBe(0);
const context = emitted(r);
expect(context).not.toBeNull();
expect(context).toContain("late shard for a day that had no local file");
expect(context).not.toContain("todays line");
});
test("a future-dated foreign line does not park the cursor past today", async () => {
// A foreign writer can stamp a log file with a future date. The scan
// must still read and surface it, but the watermark must never park
// on a date beyond today: parked at the skew, every real date under
// it reads as already-seen and the lane goes silent for exactly the
// days it exists for, until the clock catches up. The skew rides the
// clock, not a constant, so the test cannot age into a real date.
const skew = new Date(Date.now() + 45 * 86_400_000).toISOString().slice(0, 10);
seed("agent-a", "a line stamped in the future", { timestamp: `${skew}T09:00:00Z` });
seed("agent-a", "todays real line");
const first = await runHook(SESSION_START, flagOn("agent-b"));
expect(first.exit).toBe(0);
// The scan still reads the future-dated file: the line surfaces.
expect(emitted(first)).toContain("a line stamped in the future");
// The watermark parked on a real date - the newest one the log
// actually carries - never on the skew.
const cursor = JSON.parse(readFileSync(cursorPath(), "utf8")) as { date: string };
expect(cursor.date <= new Date().toISOString().slice(0, 10)).toBe(true);
// A line landing later on a real date between today and the skew
// must still surface instead of reading as covered by the parked
// cursor.
const tomorrow = new Date(Date.now() + 86_400_000).toISOString().slice(0, 10);
seed("agent-a", "tomorrows real line", { timestamp: `${tomorrow}T09:00:00Z` });
const second = await runHook(SESSION_START, flagOn("agent-b"));
expect(second.exit).toBe(0);
expect(emitted(second)).toContain("tomorrows real line");
});
test("a future-skewed foreign line shows once, not again before the clock reaches its date", async () => {
// The clamp parks the cursor on a date of today or earlier, so a
// foreign line stamped with a future date stays newest in merge order
// and past the cursor for the whole skew period - without marks for
// the future dates, every SessionStart re-renders the skew line and
// it eats the block budget every run. The cursor must record the
// per-(date, shard) marks of the future dates it scanned, so a skewed
// line is shown once; a line appended later to the still-future date
// is past that shard's mark and surfaces normally.
const skew = new Date(Date.now() + 45 * 86_400_000).toISOString().slice(0, 10);
seed("agent-a", "todays real line");
seed("agent-a", "a line stamped in the future", { timestamp: `${skew}T09:00:00Z` });
const first = await runHook(SESSION_START, flagOn("agent-b"));
expect(first.exit).toBe(0);
expect(emitted(first)).toContain("a line stamped in the future");
// The clock is still short of the skew: the line must not reshow.
const second = await runHook(SESSION_START, flagOn("agent-b"));
expect(second.exit).toBe(0);
expect(emitted(second)).toBeNull();
// A second line on the still-future date is past the shard's mark.
seed("agent-a", "a second line in the future", { timestamp: `${skew}T10:00:00Z` });
const third = await runHook(SESSION_START, flagOn("agent-b"));
expect(third.exit).toBe(0);
expect(emitted(third)).toContain("a second line in the future");
expect(emitted(third)).not.toContain("a line stamped in the future");
});
test("a first run with no cursor scans only the recent window and counts the older days honestly", async () => {
// The one unbounded scan left: with no cursor yet, the lane used to
// walk the WHOLE history - on a vault with years of daily log, the
// first SessionStart parsed every day only to render the newest 50
// lines. A first run now scans a bounded recent window and reports
// the rest as an honest count, instead of quietly parsing history
// no one will read or, worse, re-listing every shard per date.
for (const d of ["2026-09-11", "2026-09-12", "2026-09-13", "2026-09-14", "2026-09-15"]) {
seed("agent-a", `old history line from ${d}`, { timestamp: `${d}T09:00:00Z` });
}
seed("agent-a", "a recent line the window still reaches", {
timestamp: "2026-10-17T09:00:00Z",
});
const r = await runHook(SESSION_START, flagOn("agent-b"));
expect(r.exit).toBe(0);
const context = emitted(r);
expect(context).not.toBeNull();
// The recent tail surfaces; the unscanned history does not ride
// along (under the line cap it would, on a vault whose whole
// history fits the block).
expect(context).toContain("a recent line the window still reaches");
expect(context).not.toContain("old history line");
// The unscanned days are reported, not silently dropped.
expect(context).toContain("5 older day(s) not scanned");
// The run still parks the cursor, so the lane starts where it left
// off next time instead of re-deciding the window.
const cursor = JSON.parse(readFileSync(cursorPath(), "utf8")) as {
date: string;
shards: Record<string, number>;
};
expect(cursor.date).toBe("2026-10-17");
expect(cursor.shards[""]).toBe(0);
// And a second run stays silent: nothing new since the park.
const second = await runHook(SESSION_START, flagOn("agent-b"));
expect(second.exit).toBe(0);
expect(emitted(second)).toBeNull();
});
test("a first run with nothing foreign to show still reports the unscanned days", async () => {
// The unscanned-day count used to surface only inside a rendered
// block: a first run whose every window line is the reader's own
// collected nothing, emitted nothing, parked the cursor - and the
// older days were dropped forever, never reported. A header-only
// block carries the count instead, exactly once: the park below is
// what keeps the next session silent.
for (const d of ["2026-09-11", "2026-09-12", "2026-09-13", "2026-09-14", "2026-09-15"]) {
seed("agent-b", `self-authored old history from ${d}`, { timestamp: `${d}T09:00:00Z` });
}
seed("agent-b", "my own recent line", { timestamp: "2026-10-17T09:00:00Z" });
const r = await runHook(SESSION_START, flagOn("agent-b"));
expect(r.exit).toBe(0);
const context = emitted(r);
expect(context).not.toBeNull();
expect(context).toContain("5 older day(s) not scanned");
expect(context).toContain("0 log line(s)");
expect(context).not.toContain("self-authored old history");
// One honest report, not a per-session nag: the cursor parked.
const second = await runHook(SESSION_START, flagOn("agent-b"));
expect(second.exit).toBe(0);
expect(emitted(second)).toBeNull();
});
test("a first run whose window holds nothing parseable stays silent", async () => {
// The header-only report rode on the park that follows it - but a
// window whose newest shard parses to zero entries parks nothing:
// lastSeen never moves, the cursor is never written, and every
// SessionStart repeated the block over the same unscanned days. The
// report fires only when the cursor will actually be written, so a
// vault whose readable history all sits outside the window stays
// silent instead of nagging, and reports once the moment a scan
// actually advances the watermark.
for (const d of ["2026-09-11", "2026-09-12", "2026-09-13", "2026-09-14", "2026-09-15"]) {
seed("agent-a", `foreign history from ${d}`, { timestamp: `${d}T09:00:00Z` });
}
// The newest date in the log is real but unreadable: the shard the
// first-run window scans holds no parseable line at all.
writeFileSync(join(vault, "Brain", "log", "2026-10-17.jsonl"), "not json at all\n", "utf8");
const first = await runHook(SESSION_START, flagOn("agent-b"));
expect(first.exit).toBe(0);
expect(emitted(first)).toBeNull();
expect(existsSync(cursorPath())).toBe(false);
// The silence holds: the second run sees the same vault, and the
// block does not come back.
const second = await runHook(SESSION_START, flagOn("agent-b"));
expect(second.exit).toBe(0);
expect(emitted(second)).toBeNull();
expect(existsSync(cursorPath())).toBe(false);
});
test("the header names the recent window on a first run, the last read after it", async () => {
// "Since your last read" names a read that never happened on a first
// run: with no cursor there is no last look, and the lower bound is
// the first-run window, not a watermark.
seed("agent-a", "a line for the first run");
const first = await runHook(SESSION_START, flagOn("agent-b"));
expect(first.exit).toBe(0);
const firstContext = emitted(first);
expect(firstContext).not.toBeNull();
expect(firstContext).toContain("in the recent window");
expect(firstContext).not.toContain("since your last read");
// Once the cursor exists the bound really is the last read.
seed("agent-a", "a line for the second run");
const second = await runHook(SESSION_START, flagOn("agent-b"));
expect(second.exit).toBe(0);
const secondContext = emitted(second);
expect(secondContext).not.toBeNull();
expect(secondContext).toContain("since your last read");
expect(secondContext).not.toContain("in the recent window");
});
test("a date evicted from the window is still skipped whole", async () => {
// Six dates: the cursor keeps per-shard marks for the newest three
// before its date, so 10-10 and 10-13 are evicted - and a brand-new
// line on an evicted date is not chased, which bounds how far back a
// delayed sync can resurface.
const dates = [
"2026-10-10",
"2026-10-13",
"2026-10-14",
"2026-10-15",
"2026-10-16",
"2026-10-17",
];
for (const d of dates) {
seed("agent-a", `line on ${d}`, { timestamp: `${d}T09:00:00Z` });
}
expect(emitted(await runHook(SESSION_START, flagOn("agent-b")))).not.toBeNull();
const cursor = JSON.parse(readFileSync(cursorPath(), "utf8")) as {
days: Record<string, Record<string, number>>;
};
expect(Object.keys(cursor.days).toSorted()).toEqual(["2026-10-14", "2026-10-15", "2026-10-16"]);
seed("agent-a", "a line on the evicted date", { timestamp: "2026-10-10T10:00:00Z" });
const r = await runHook(SESSION_START, flagOn("agent-b"));
expect(r.exit).toBe(0);
expect(emitted(r)).toBeNull();
});
test("the cursor keeps per-shard marks for at most the previous three dates", async () => {
for (let d = 10; d <= 17; d++) {
seed("agent-a", `day ${d} line`, { timestamp: `2026-10-${d}T09:00:00Z` });
}
expect(emitted(await runHook(SESSION_START, flagOn("agent-b")))).not.toBeNull();
const cursor = JSON.parse(readFileSync(cursorPath(), "utf8")) as {
date: string;
days: Record<string, Record<string, number>>;
};
expect(cursor.date).toBe("2026-10-17");
const window = Object.keys(cursor.days).toSorted();
expect(window.length).toBeLessThanOrEqual(3);
for (const d of window) expect(d < cursor.date).toBe(true);
// The newest three older dates are exactly the ones kept.
expect(window).toEqual(["2026-10-14", "2026-10-15", "2026-10-16"]);
});
test("a same-second line in a different shard is not skipped", async () => {
// Run 1's cursor must sit on the HIGHER-sorting shard for this test
// to exercise the interleaving: the dev-z line parks the cursor at
// shard "dev-z", then run 2's dev-a line lands at the same second,
// so the merge order places it BEFORE the cursor tuple. A bare
// (date, shardId, line) comparison would call it already seen and
// skip it; only the per-shard marks - "dev-a" has no mark yet -
// admit it.
seed("agent-a", "first device line", { deviceId: "dev-z" });
expect(emitted(await runHook(SESSION_START, flagOn("agent-b")))).not.toBeNull();
seed("agent-a", "same-second line from another shard", { deviceId: "dev-a" });
const r = await runHook(SESSION_START, flagOn("agent-b"));
expect(r.exit).toBe(0);
const context = emitted(r);
expect(context).not.toBeNull();
expect(context).toContain("same-second line from another shard");
});
test("more than the per-lane cap shows the newest lines plus an older count", async () => {
for (let i = 0; i < 55; i++) {
seed("agent-a", `catch-up line number ${String(i).padStart(2, "0")}`, {
timestamp: `2026-10-17T10:${String(i).padStart(2, "0")}:00Z`,
});
}
const r = await runHook(SESSION_START, flagOn("agent-b"));
expect(r.exit).toBe(0);
const context = emitted(r);
expect(context).not.toBeNull();
// The newest 50 survive; the 5 oldest are counted, not rendered.
expect(context).toContain("catch-up line number 54");
expect(context).toContain("catch-up line number 05");
expect(context).not.toContain("catch-up line number 04");
expect(context).toContain("5 older");
});
test("the char cap drops the oldest lines first and the cursor still covers every scanned line", async () => {
// Fourteen long lines whose rendered block (each truncated to the
// per-line cap) still blows past LOG_CATCHUP_MAX_CHARS: the trim
// loop must peel the oldest lines off the front, count each as
// older, and still advance the watermark past every line it
// scanned - trimming the render must not freeze the cursor, or the
// dropped lines would resurface next session.
for (let i = 0; i < 14; i++) {
seed("agent-a", `charcap line ${i} ${"x".repeat(1500)}`, {
timestamp: `2026-10-17T10:${String(i).padStart(2, "0")}:00Z`,
});
}
const r = await runHook(SESSION_START, flagOn("agent-b"));
expect(r.exit).toBe(0);
const context = emitted(r);
expect(context).not.toBeNull();
// Oldest dropped first: the front of the scan is gone, the newest
// line survives. (Pin the dropped lines with their first x so the
// substring cannot match the two-digit line numbers.)
expect(context).not.toContain("charcap line 0 x");
expect(context).not.toContain("charcap line 1 x");
expect(context).toContain("charcap line 13");
// Any "older" count in the header is the char-trim loop's own work
// (the line cap alone would have shown all 14).
const older = context?.match(/\((\d+) older not shown/);
expect(older).not.toBeNull();
expect(Number(older![1])).toBeGreaterThanOrEqual(1);
// The cut line names the surface that carries the rest (task 4.4).
expect(context).toContain("the log pages carry the rest");
// The watermark advanced past ALL scanned lines despite the trim.
const cursor = JSON.parse(readFileSync(cursorPath(), "utf8")) as {
line: number;
shards: Record<string, number>;
};
expect(cursor.line).toBe(13);
expect(cursor.shards[""]).toBe(13);
});
test("a missing or corrupt cursor fails soft and the lane still exits 0", async () => {
seed("agent-a", "read me despite the broken cursor");
const { mkdirSync } = await import("node:fs");
mkdirSync(dirname(cursorPath()), { recursive: true });
writeFileSync(cursorPath(), "{ not json", "utf8");
const r = await runHook(SESSION_START, flagOn("agent-b"));
expect(r.exit).toBe(0);
expect(r.stderr).toBe("");
const context = emitted(r);
expect(context).not.toBeNull();
expect(context).toContain("read me despite the broken cursor");
});
test("self identity falls back to the device id when no agent name is configured", async () => {
seed("dev-b", "the device's own line");
seed("agent-a", "someone else's line");
const r = await runHook(SESSION_START, {
OPEN_SECOND_BRAIN_LOG_CATCHUP_ENABLED: "true",
VAULT_DIR: vault,
O2B_DEVICE_ID: "dev-b",
});
expect(r.exit).toBe(0);
const context = emitted(r);
expect(context).not.toBeNull();
expect(context).toContain("someone else's line");
expect(context).not.toContain("the device's own line");
});
test("device fallback filters own lines by shard when the writer stamped the placeholder agent", async () => {
// The writer-realistic shape: an unconfigured install stamps the
// payload `agent` with the `resolveAgentName` placeholder ("agent")
// and puts its device id in the shard name - the payload never
// carries the device id. Fallback authorship must therefore be read
// off the shard (the shard id IS the device id), or the install
// replays its own lines back as cross-agent catch-up.
seed("agent", "the device's own writer-realistic line", { deviceId: "dev-b" });
seed("agent-a", "a genuinely other agent's line", { deviceId: "dev-c" });
const r = await runHook(SESSION_START, {
OPEN_SECOND_BRAIN_LOG_CATCHUP_ENABLED: "true",
VAULT_DIR: vault,
O2B_DEVICE_ID: "dev-b",
});
expect(r.exit).toBe(0);
const context = emitted(r);
expect(context).not.toBeNull();
expect(context).toContain("a genuinely other agent's line");
expect(context).not.toContain("the device's own writer-realistic line");
});
test("a configured agent name stays the identity even across device shards", async () => {
// When an agent name is configured it is the identity: a same-name
// line from another device's shard is still self, and the shard id
// is not consulted at all.
seed("agent-b", "my own line from another device", { deviceId: "dev-other" });
seed("agent-a", "another agent's cross-device line", { deviceId: "dev-other" });
const r = await runHook(SESSION_START, flagOn("agent-b"));
expect(r.exit).toBe(0);
const context = emitted(r);
expect(context).not.toBeNull();
expect(context).toContain("another agent's cross-device line");
expect(context).not.toContain("my own line from another device");
});
test("agent identity compares trimmed on both sides", async () => {
// The configured name can arrive padded through the env and the
// entry attribution padded through the log; both sides must
// normalize before the comparison or the agent's own line reads as
// foreign.
seed(" agent-b ", "my paddedly attributed line");
seed("agent-a", "someone else's plainly attributed line");
const r = await runHook(SESSION_START, flagOn(" agent-b "));
expect(r.exit).toBe(0);
const context = emitted(r);
expect(context).not.toBeNull();
expect(context).toContain("someone else's plainly attributed line");
expect(context).not.toContain("my paddedly attributed line");
});
test("an event that cannot carry additionalContext gets nothing", async () => {
seed("agent-a", "quiet on this event");
const r = await runHook({ hook_event_name: "PostToolUse" }, flagOn("agent-b"));
expect(r.exit).toBe(0);
expect(r.stdout).toBe("");
expect(existsSync(cursorPath())).toBe(false);
});
test("no vault resolves to silence", async () => {
const r = await runHook(SESSION_START, { OPEN_SECOND_BRAIN_LOG_CATCHUP_ENABLED: "true" });
expect(r.exit).toBe(0);
expect(r.stdout).toBe("");
});
});
describe("first-run scan window", () => {
test("a no-cursor run scans only the first-run window behind the newest real date", () => {
// The window rides the NEWEST date in the log that is today or
// earlier, not today itself: a vault whose newest entry is months
// old still catches up on its own recent tail instead of reporting
// its whole history unscanned. The +2 slack over the cursor window
// keeps the first run's reach a superset of what a parked cursor
// would still rescan.
expect(LOG_CATCHUP_FIRST_RUN_WINDOW_DATES).toBe(LOG_CATCHUP_WINDOW_DATES + 2);
const dates = [
"2026-01-05",
"2026-09-11",
"2026-09-12",
"2026-09-13",
"2026-09-14",
"2026-09-15",
"2026-10-17",
];
expect(firstRunScanCutoffDate(dates, "2026-10-18")).toBe("2026-10-12");
// The boundary is inclusive: a date exactly on the cutoff scans.
expect(firstRunScanCutoffDate(["2026-10-12"], "2026-10-18")).toBe("2026-10-07");
// A future-skewed newest date must not widen the window past every
// real day - the reference clamps to the newest date of today or
// earlier, the watermark parking clamp again.
expect(firstRunScanCutoffDate([...dates, "2026-12-02"], "2026-10-18")).toBe("2026-10-12");
// Every date future: the reference falls back to today, so the skew
// lines still surface instead of reading as unscanned history.
expect(firstRunScanCutoffDate(["2026-12-02"], "2026-10-18")).toBe("2026-10-13");
// An empty log has no window and no cutoff.
expect(firstRunScanCutoffDate([], "2026-10-18")).toBeNull();
});
});