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 vault `.gitignore` guard seeder (t_206562ae, task B1).
*
* `bootstrapBrain` seeds a managed block into `<vault>/.gitignore` whose
* entry list starts as exactly one vault-root-anchored line,
* `/.open-second-brain/` - one entry covering every Tier A derived-state
* writer (brain.sqlite, hook-audit, secrets, maintenance sqlite and
* journals, ingest checkpoints, dead-letters, session ledgers, watchdog
* fallback, self-heal state, locks, bench runs). The seeder never shells
* out to git and never touches bytes outside the block.
*
* The census at the bottom is the source-reading half (same discipline as
* `tests/hooks/audit-root.test.ts` and the sync-lockfile lock-site
* census): the entry covers the directory only while every derived-state
* writer actually resolves under it, so the sweep pins the population.
*/
import { describe, expect, test } from "bun:test";
import {
existsSync,
lstatSync,
mkdirSync,
mkdtempSync,
readFileSync,
readdirSync,
rmSync,
symlinkSync,
writeFileSync,
} from "node:fs";
import { tmpdir } from "node:os";
import { dirname, join, resolve } from "node:path";
import { fileURLToPath } from "node:url";
import {
DEFAULT_BEGIN_MARKER,
DEFAULT_END_MARKER,
} from "../../../src/core/install/managed-block.ts";
import {
ensureVaultGitignoreEntries,
GITIGNORE_GUARD_ENTRIES,
GITIGNORE_GUARD_FILE,
} from "../../../src/core/brain/gitignore-guard.ts";
import { BENCH_RUNS_REL, DERIVED_STORE_DIR } from "../../../src/core/brain/path-constants.ts";
let vault: string;
function freshVault(): string {
const dir = mkdtempSync(join(tmpdir(), "o2b-gitignore-guard-"));
// A legacy vault: it keeps machine state, so it wants the ignore block.
// A vault with no `Brain/` is store-only and keeps none.
mkdirSync(join(dir, "Brain"));
return dir;
}
function gitignorePath(): string {
return join(vault, GITIGNORE_GUARD_FILE);
}
function seededBlock(): string {
return `${DEFAULT_BEGIN_MARKER}\n${GITIGNORE_GUARD_ENTRIES.join("\n")}\n${DEFAULT_END_MARKER}\n`;
}
/**
* The git-valid spellings of a negating line the matcher must catch.
* Beyond the two plain forms: a trailing slash, git's ignored unescaped
* trailing whitespace, and the double-star-slash prefix that matches
* zero or more directories (so it covers the vault root too). Spellings
* OUTSIDE this list - escaped-dot spellings, character-class and
* bracket-expression tricks - stay out of scope on purpose: the doctor's
* git-tracked-state row measures what git actually did, and is the
* authority for everything this matcher cannot name.
*/
const NEGATION_LINE_VARIANTS: ReadonlyArray<string> = [
"!.open-second-brain",
"!/.open-second-brain",
"!.open-second-brain/",
"!/.open-second-brain/",
"!.open-second-brain ",
"!**/.open-second-brain",
"!**/.open-second-brain/",
];
describe("ensureVaultGitignoreEntries", () => {
test("creates a .gitignore containing only the block when none exists", () => {
vault = freshVault();
try {
const result = ensureVaultGitignoreEntries(vault);
expect(result.status).toBe("created");
expect(result.file).toBe(GITIGNORE_GUARD_FILE);
expect(existsSync(gitignorePath())).toBe(true);
expect(readFileSync(gitignorePath(), "utf8")).toBe(seededBlock());
} finally {
rmSync(vault, { recursive: true, force: true });
}
});
test("appends the block to an existing user .gitignore, byte-preserving user content", () => {
vault = freshVault();
try {
const user = "# my patterns\n*.tmp\n.obsidian/workspace.json\n";
writeFileSync(gitignorePath(), user, "utf8");
const result = ensureVaultGitignoreEntries(vault);
expect(result.status).toBe("updated");
const next = readFileSync(gitignorePath(), "utf8");
expect(next.startsWith(user)).toBe(true);
expect(next).toContain(DEFAULT_BEGIN_MARKER);
expect(next).toContain(`/${DERIVED_STORE_DIR}/`);
expect(next).toContain(DEFAULT_END_MARKER);
} finally {
rmSync(vault, { recursive: true, force: true });
}
});
test("a second run is a no-op: byte-equal file, skipped", () => {
vault = freshVault();
try {
ensureVaultGitignoreEntries(vault);
const before = readFileSync(gitignorePath(), "utf8");
const second = ensureVaultGitignoreEntries(vault);
expect(second.status).toBe("skipped");
expect(readFileSync(gitignorePath(), "utf8")).toBe(before);
} finally {
rmSync(vault, { recursive: true, force: true });
}
});
test("a user line that already ignores the path yields a skip, not a duplicate", () => {
vault = freshVault();
try {
const user = "*.tmp\n/.open-second-brain/\n";
writeFileSync(gitignorePath(), user, "utf8");
const result = ensureVaultGitignoreEntries(vault);
expect(result.status).toBe("skipped");
expect(readFileSync(gitignorePath(), "utf8")).toBe(user);
} finally {
rmSync(vault, { recursive: true, force: true });
}
});
test("CRLF files keep their line endings in both the user content and the block", () => {
vault = freshVault();
try {
writeFileSync(gitignorePath(), "# my patterns\r\n*.tmp\r\n", "utf8");
const result = ensureVaultGitignoreEntries(vault);
expect(result.status).toBe("updated");
const next = readFileSync(gitignorePath(), "utf8");
expect(next.startsWith("# my patterns\r\n*.tmp\r\n")).toBe(true);
expect(next).toContain(`${DEFAULT_BEGIN_MARKER}\r\n`);
expect(next).toContain(`/${DERIVED_STORE_DIR}/\r\n`);
expect(next).toContain(`${DEFAULT_END_MARKER}\r\n`);
} finally {
rmSync(vault, { recursive: true, force: true });
}
});
test("an existing conforming block with extra entries merges without losing them", () => {
vault = freshVault();
try {
const prior = `${DEFAULT_BEGIN_MARKER}\n*.log\n${DEFAULT_END_MARKER}\n`;
writeFileSync(gitignorePath(), prior, "utf8");
const result = ensureVaultGitignoreEntries(vault);
expect(result.status).toBe("updated");
const next = readFileSync(gitignorePath(), "utf8");
// The block survives as ONE block, its prior entries kept, ours added.
expect(next.match(new RegExp(DEFAULT_BEGIN_MARKER, "g"))).toHaveLength(1);
expect(next).toContain("*.log");
expect(next).toContain(`/${DERIVED_STORE_DIR}/`);
} finally {
rmSync(vault, { recursive: true, force: true });
}
});
test("malformed existing markers surface the named conflict without writing", () => {
vault = freshVault();
try {
const broken = "# mine\n# >>> open-second-brain managed >>>\n*.tmp\n";
writeFileSync(gitignorePath(), broken, "utf8");
const result = ensureVaultGitignoreEntries(vault);
expect(result.status).toBe("conflict");
expect(result.detail).toBeTruthy();
// Warn-and-continue: the file is exactly as the user left it.
expect(readFileSync(gitignorePath(), "utf8")).toBe(broken);
} finally {
rmSync(vault, { recursive: true, force: true });
}
});
test("two begin markers are a conflict too", () => {
vault = freshVault();
try {
const broken = `${DEFAULT_BEGIN_MARKER}\n${DEFAULT_END_MARKER}\n${DEFAULT_BEGIN_MARKER}\n`;
writeFileSync(gitignorePath(), broken, "utf8");
const result = ensureVaultGitignoreEntries(vault);
expect(result.status).toBe("conflict");
expect(readFileSync(gitignorePath(), "utf8")).toBe(broken);
} finally {
rmSync(vault, { recursive: true, force: true });
}
});
test("a later negating line turns the exact-line skip into a named conflict", () => {
// git evaluates .gitignore patterns in order and the LAST match
// wins: with `!.open-second-brain` after the entry the store is NOT
// ignored, so reporting a clean skip here would be optimistic. The
// doctor row catches it later; the init report itself must not lie.
for (const negation of NEGATION_LINE_VARIANTS) {
vault = freshVault();
try {
const hostile = `/.open-second-brain/\n*.tmp\n${negation}\n`;
writeFileSync(gitignorePath(), hostile, "utf8");
let result!: ReturnType<typeof ensureVaultGitignoreEntries>;
const { stderr } = captureStderr(() => {
result = ensureVaultGitignoreEntries(vault);
});
expect(result.status).toBe("conflict");
expect(result.detail).toContain(negation.trim());
// Warn-and-continue: the file is exactly as the user left it.
expect(readFileSync(gitignorePath(), "utf8")).toBe(hostile);
expect(stderr).toMatch(/warning:/);
expect(stderr).toContain("derived-brain-state");
} finally {
rmSync(vault, { recursive: true, force: true });
}
}
});
test("a conforming block that a later negation defeats is a conflict, not a clean update", () => {
// The merge would land the entry INSIDE the earlier block, so the
// negation after the block still wins under git's last-match rule:
// a clean `updated` here would seed nothing effective while the
// report claimed the guard moved.
vault = freshVault();
try {
const hostile = `${DEFAULT_BEGIN_MARKER}\n*.log\n${DEFAULT_END_MARKER}\n!.open-second-brain\n`;
writeFileSync(gitignorePath(), hostile, "utf8");
let result!: ReturnType<typeof ensureVaultGitignoreEntries>;
const { stderr } = captureStderr(() => {
result = ensureVaultGitignoreEntries(vault);
});
expect(result.status).toBe("conflict");
expect(result.detail).toContain("!.open-second-brain");
// Warn-and-continue: the file is exactly as the user left it, and
// the store stays unprotected - reported, never claimed as seeded.
expect(readFileSync(gitignorePath(), "utf8")).toBe(hostile);
expect(stderr).toMatch(/warning:/);
expect(stderr).toContain("derived-brain-state");
} finally {
rmSync(vault, { recursive: true, force: true });
}
});
test("a negation BEFORE the block is overridden by the merged entry - a clean update", () => {
// Last-match-wins favors the entry the merge adds, because it lands
// after the negation inside the block.
vault = freshVault();
try {
const user = `!.open-second-brain\n${DEFAULT_BEGIN_MARKER}\n*.log\n${DEFAULT_END_MARKER}\n`;
writeFileSync(gitignorePath(), user, "utf8");
const result = ensureVaultGitignoreEntries(vault);
expect(result.status).toBe("updated");
const next = readFileSync(gitignorePath(), "utf8");
expect(next).toContain(`/${DERIVED_STORE_DIR}/`);
expect(next).toContain("*.log");
} finally {
rmSync(vault, { recursive: true, force: true });
}
});
test("an existing empty block gains the entry without a stray blank line", () => {
// Begin marker directly followed by end marker: the block body is
// the empty string, and `"".split("\n")` yields [""], which used to
// open the merged block with a blank line.
vault = freshVault();
try {
writeFileSync(gitignorePath(), `${DEFAULT_BEGIN_MARKER}\n${DEFAULT_END_MARKER}\n`, "utf8");
const result = ensureVaultGitignoreEntries(vault);
expect(result.status).toBe("updated");
expect(readFileSync(gitignorePath(), "utf8")).toBe(
`${DEFAULT_BEGIN_MARKER}\n/${DERIVED_STORE_DIR}/\n${DEFAULT_END_MARKER}\n`,
);
} finally {
rmSync(vault, { recursive: true, force: true });
}
});
test("a negation BEFORE the entry is a clean skip - last-match-wins favors the entry", () => {
vault = freshVault();
try {
const harmless = "!.open-second-brain\n/.open-second-brain/\n";
writeFileSync(gitignorePath(), harmless, "utf8");
const result = ensureVaultGitignoreEntries(vault);
expect(result.status).toBe("skipped");
expect(readFileSync(gitignorePath(), "utf8")).toBe(harmless);
} finally {
rmSync(vault, { recursive: true, force: true });
}
});
test("a symlinked .gitignore is a conflict: the link is kept, the target untouched", () => {
// An operator who manages the vault .gitignore as a link into their
// dotfiles loses the link silently if the seeder writes: the atomic
// write renames a regular file over the LINK path, and init would
// report a clean `updated`. The seeder must refuse like every other
// writer in this tree, naming the link target, and the doctor row
// then reports the still-unprotected store.
vault = freshVault();
try {
const target = join(vault, "dotfiles.gitignore");
const user = "# my patterns\n";
writeFileSync(target, user, "utf8");
symlinkSync("dotfiles.gitignore", gitignorePath());
let result!: ReturnType<typeof ensureVaultGitignoreEntries>;
const { stderr } = captureStderr(() => {
result = ensureVaultGitignoreEntries(vault);
});
expect(result.status).toBe("conflict");
expect(result.detail).toContain("dotfiles.gitignore");
expect(result.detail!.length).toBeGreaterThan(0);
// The link is still a link, and the target holds exactly the
// user's bytes - nothing was written anywhere.
expect(lstatSync(gitignorePath()).isSymbolicLink()).toBe(true);
expect(readFileSync(target, "utf8")).toBe(user);
expect(stderr).toMatch(/warning:/);
expect(stderr).toContain("derived-brain-state");
} finally {
rmSync(vault, { recursive: true, force: true });
}
});
test("a dangling .gitignore link is a conflict too, never replaced by a created file", () => {
// existsSync is false through a dangling link, which used to route
// the seeder into the created branch - renaming a regular file over
// the link. The refusal must see the link itself, so the same
// conflict applies and the (broken, but the operator's) link stays.
vault = freshVault();
try {
symlinkSync("gone-target.gitignore", gitignorePath());
let result!: ReturnType<typeof ensureVaultGitignoreEntries>;
const { stderr } = captureStderr(() => {
result = ensureVaultGitignoreEntries(vault);
});
expect(result.status).toBe("conflict");
expect(result.detail).toContain("gone-target.gitignore");
expect(lstatSync(gitignorePath()).isSymbolicLink()).toBe(true);
expect(existsSync(gitignorePath())).toBe(false);
expect(existsSync(join(vault, "gone-target.gitignore"))).toBe(false);
expect(stderr).toMatch(/warning:/);
} finally {
rmSync(vault, { recursive: true, force: true });
}
});
});
/** Run `fn`, capturing everything it writes to stderr; restore afterwards. */
function captureStderr(fn: () => unknown): { stderr: string } {
const original = process.stderr.write.bind(process.stderr);
let captured = "";
process.stderr.write = ((chunk: string | Uint8Array): boolean => {
captured += typeof chunk === "string" ? chunk : Buffer.from(chunk).toString("utf8");
return true;
}) as typeof process.stderr.write;
try {
fn();
} finally {
process.stderr.write = original;
}
return { stderr: captured };
}
// ----- Source-reading census ------------------------------------------------
/**
* Every `src/` file that references the derived store, by constant or by
* the directory's literal name (as a quoted path segment or a
* slash-anchored pattern in a message). This is the population the
* `/.open-second-brain/` entry has to cover.
*/
const SRC = resolve(dirname(fileURLToPath(import.meta.url)), "..", "..", "..", "src");
const DERIVED_STORE_REFERENCE_RE =
/DERIVED_STORE_DIR|DERIVED_STORE_FILE|BENCH_RUNS_REL|"\.open-second-brain"|\/\.open-second-brain/;
function derivedStoreSites(): string[] {
const out: string[] = [];
const walk = (dir: string): void => {
for (const entry of readdirSync(dir, { withFileTypes: true })) {
const full = join(dir, entry.name);
if (entry.isDirectory()) {
walk(full);
continue;
}
if (!entry.name.endsWith(".ts")) continue;
if (DERIVED_STORE_REFERENCE_RE.test(readFileSync(full, "utf8"))) {
out.push(full.slice(SRC.length + 1).replaceAll("\\", "/"));
}
}
};
walk(SRC);
return out.toSorted();
}
/**
* Declared derived-state sites, each with what its reference IS. A new
* site fails the census until its author states what the reference is
* here; a declared site whose reference disappears (a writer moved its
* paths outside the covered directory) fails the membership assertion.
*/
const DECLARED_SITES: ReadonlyMap<string, string> = new Map([
[
"core/search/brain-store/location.ts",
"names the legacy derived-store file to place the store-aware index outside the vault",
],
["cli/bootstrap/receipt.ts", "bootstraps the bootstrap lockfile under the store"],
[
"core/state/machine-state.ts",
"names the derived-store tree the machine-state resolver maps into device-local state",
],
["cli/bootstrap/run.ts", "CLI bootstrap reporting that names the store"],
["cli/brain/help-text.ts", "help prose naming the store directory"],
["cli/brain/verbs/bench.ts", "bench runs default dir, composed from BENCH_RUNS_REL"],
["cli/brain/verbs/dead-letters.ts", "dead-letter listing prose naming the store"],
[
"core/brain/attestation/record.ts",
"signed attestation shards under the store, spelled as the ATTESTATIONS_REL join",
],
[
"core/brain/attestation/signing.ts",
"the operator attestation key directory under the store, spelled as a segment join",
],
[
"core/brain/checkpoint-store.ts",
"the shared checkpoint substrate under the store (ingest and session-import lanes)",
],
["core/brain/dead-letter.ts", "dead letters under the store"],
["core/brain/gitignore-guard.ts", "composes the seeded guard entry from the constant"],
["core/brain/init.ts", "bootstraps the seed; names the entry in its step 1c docblock"],
[
"core/brain/doctor/git-tracked-state-check.ts",
"composes the ls-files pathspec and the guard ignore line from the constant",
],
["core/brain/ingest/checkpoint.ts", "ingest checkpoints under the store"],
[
"core/brain/ingest/content-manifest.ts",
"ingest content manifest under the store, spelled as the private MACHINE_ARTIFACT_DIR beside its join",
],
[
"core/brain/inject-failopen.ts",
"inject cache under the store, spelled as the private INJECT_CACHE_DIR beside its join",
],
[
"core/brain/lessons-promotion.ts",
"lesson-approval ledger under the store (t_1e952e43), the decisions-in-force table",
],
["core/brain/maintenance/journal.ts", "maintenance journals under the store"],
["core/brain/maintenance/lease.ts", "maintenance lease sqlite under the store"],
["core/brain/path-constants.ts", "owns the directory name itself"],
["core/brain/paths.ts", "composes the hook-audit root under the store from the constant"],
[
"core/brain/protect.ts",
"protect manifest under the store, spelled as the private MANIFEST_DIR beside its join",
],
["core/brain/recall-inject.ts", "recall injection reporting that names the store"],
["core/brain/secrets/store.ts", "secrets directory under the store, spelled as a join literal"],
["core/brain/secrets/token-store.ts", "token-store reporting that names the store"],
["core/brain/session-mining-ledger.ts", "session mining ledger under the store"],
["core/brain/session-mining-surveys.ts", "session mining surveys under the store"],
["core/brain/sessions/discover.ts", "session import ledger under the store"],
["core/brain/snapshot.ts", "snapshot recovery reaching the brain.sqlite file"],
["core/brain/storage/usage.ts", "storage census over the store"],
["core/brain/sync-lockfile.ts", "lock files under the store"],
[
"core/brain/temporal/weekly-brief.ts",
"weekly brief EXCLUDES the store by directory name, it writes nothing there",
],
["core/brain/watchdog.ts", "watchdog audit fallback under the store"],
["core/derived-store-guard.ts", "the symlink guard over the store directory itself"],
["core/doctor-selftest.ts", "doctor self-test writing probe state under the store"],
[
"core/graph/mcp-config.ts",
"MCP config SKIP_DIRS excludes the store by name, it writes nothing there",
],
["core/install/adapters/aider.ts", "aider adapter reporting that names the store"],
[
"core/install/adapters/aider-wrapper.ts",
"aider context artifact under the store, spelled as a join literal",
],
[
"core/install/instruction-block.ts",
"instruction-block ownership lockfile under the store (t_ba41a78a)",
],
["core/install/manifest.ts", "install lockfile under the store, spelled as a join literal"],
["core/maintenance/self-heal-upgrade-state.ts", "self-heal upgrade state under the store"],
["core/search/paths.ts", "composes the brain.sqlite path under the store from the constants"],
["core/state/surfaces.ts", "state surfaces census over the store"],
[
"core/vault-scope/defaults.ts",
"DEFAULT_VAULT_IGNORE_PATHS excludes the store by name, it writes nothing there",
],
]);
describe("every derived-state site sits under the covered directory", () => {
test("the sweep actually found the sites", () => {
// A census over an empty set passes for the wrong reason.
expect(derivedStoreSites().length).toBeGreaterThan(20);
});
test("no derived-state site is missing from the declared set", () => {
const undeclared = derivedStoreSites().filter((rel) => !DECLARED_SITES.has(rel));
expect(undeclared).toEqual([]);
});
test("every declared site still exists and still references the store", () => {
const vanished = [...DECLARED_SITES.keys()].filter((rel) => {
const path = join(SRC, rel);
if (!existsSync(path)) return true;
return !DERIVED_STORE_REFERENCE_RE.test(readFileSync(path, "utf8"));
});
expect(vanished).toEqual([]);
});
test("the bench runs dir is hoisted, not locally spelled", () => {
// The default runs dir is named beside DERIVED_STORE_DIR so the
// guard's single entry provably covers it (task B1).
expect(BENCH_RUNS_REL).toBe(`${DERIVED_STORE_DIR}/bench-runs`);
const bench = readFileSync(join(SRC, "cli", "brain", "verbs", "bench.ts"), "utf8");
expect(bench).not.toContain('".open-second-brain"');
expect(bench).toContain("BENCH_RUNS_REL");
});
});
describe("the guard's entry list", () => {
test("starts as exactly one vault-root-anchored entry naming the store", () => {
expect([...GITIGNORE_GUARD_ENTRIES]).toEqual([`/${DERIVED_STORE_DIR}/`]);
});
test("seeding a fresh vault covers the derived store root", () => {
vault = freshVault();
try {
mkdirSync(vault, { recursive: true });
ensureVaultGitignoreEntries(vault);
const content = readFileSync(gitignorePath(), "utf8");
expect(content).toContain(`/${DERIVED_STORE_DIR}/`);
} finally {
rmSync(vault, { recursive: true, force: true });
}
});
});