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
/**
* `o2b brain permissions` (write-side-trust, Task 4).
*
* The operator surface over the permissions document and the decision
* ledger. `show` exists so the foot-gun a default-deny document is stays
* visible BEFORE the first refusal: it renders the dry-run decision table
* over the declared agents. `ledger` is the query half of the
* accountability trail. A document that cannot be read is never smoothed
* over: `show` fails naming the field, and the doctor reports the same
* fault under `permissions-unreadable` - exactly once.
*/
import { afterEach, beforeEach, describe, expect, setDefaultTimeout, test } from "bun:test";
import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { appendDecisionLedger } from "../../src/core/brain/permissions/ledger.ts";
import { runCli } from "../helpers/run-cli.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);
let tmp: string;
let vault: string;
let docPath: string;
beforeEach(() => {
tmp = mkdtempSync(join(tmpdir(), "o2b-cli-permissions-"));
vault = join(tmp, "vault");
mkdirSync(join(vault, "Brain"), { recursive: true });
docPath = join(vault, "Brain", "_permissions.yaml");
});
afterEach(() => {
rmSync(tmp, { recursive: true, force: true });
});
function writeDoc(text: string): void {
writeFileSync(docPath, text, "utf8");
}
const DOCUMENT = [
"version: 1",
"default_action: deny",
"roles:",
" reviewer:",
" write: ask",
" ingest: deny",
"agents:",
" codex:",
" role: reviewer",
" write: allow",
"entries:",
" - id: freeze-notes",
" agent: codex",
" action: write",
" target: notes/foo.md",
" verdict: deny",
].join("\n");
describe("brain permissions show", () => {
test("with no document it says so and prints no decision table", async () => {
const result = await runCli(["brain", "permissions", "show", "--vault", vault]);
expect(result.returncode).toBe(0);
expect(result.stdout).toContain("no permissions document");
expect(result.stdout).toContain("_permissions.yaml");
// The decision table's header never appears when there is nothing to resolve.
expect(result.stdout).not.toContain("decision");
});
test("with a document it renders the resolved decision for each declared agent", async () => {
writeDoc(`${DOCUMENT}\n`);
const result = await runCli(["brain", "permissions", "show", "--vault", vault]);
expect(result.returncode).toBe(0);
expect(result.stdout).toContain("deny"); // the explicit default
expect(result.stdout).toContain("reviewer");
expect(result.stdout).toContain("codex");
// Sources name the deciding rule: the target-scoped entry beats the
// agent override on its target, the override wins elsewhere.
expect(result.stdout).toContain("entry:freeze-notes");
expect(result.stdout).toContain("agent:codex");
expect(result.stdout).toContain("role:reviewer");
});
test("--json carries the document and one resolved row per agent per action", async () => {
writeDoc(`${DOCUMENT}\n`);
const result = await runCli(["brain", "permissions", "show", "--vault", vault, "--json"]);
expect(result.returncode).toBe(0);
const payload = JSON.parse(result.stdout) as {
document: { default_action: string } | null;
decisions: Array<{
agent: string;
action: string;
target: string;
verdict: string;
source: string;
}>;
};
expect(payload.document).not.toBeNull();
expect(payload.document!.default_action).toBe("deny");
// One agent: three blanket actions plus the one declared target.
expect(payload.decisions).toHaveLength(4);
const write = payload.decisions.find((d) => d.action === "write" && d.target === "")!;
expect(write.verdict).toBe("allow");
expect(write.source).toBe("agent:codex");
const scoped = payload.decisions.find((d) => d.target === "notes/foo.md")!;
expect(scoped.source).toBe("entry:freeze-notes");
expect(scoped.verdict).toBe("deny");
});
test("a corrupt document fails with the field-named error", async () => {
writeDoc("version: 1\n");
const result = await runCli(["brain", "permissions", "show", "--vault", vault]);
expect(result.returncode).not.toBe(0);
const said = `${result.stdout}${result.stderr}`;
expect(said).toContain("default_action");
expect(said).toContain("_permissions.yaml");
});
});
describe("brain permissions ledger", () => {
test("an empty vault reports no rows", async () => {
const result = await runCli(["brain", "permissions", "ledger", "--vault", vault]);
expect(result.returncode).toBe(0);
expect(result.stdout.toLowerCase()).toContain("no decision ledger rows");
});
test("rows list in deterministic order and filters narrow them", async () => {
appendDecisionLedger(vault, {
ts: "2026-10-10T10:00:00Z",
actor: "codex",
via: "token",
action: "write",
target: "notes/foo.md",
verdict: "deny",
source: "entry:freeze-notes",
reason: "target-scoped entry freeze-notes",
});
appendDecisionLedger(vault, {
ts: "2026-10-10T11:00:00Z",
actor: "gemini",
via: "token",
action: "ingest",
target: "sources/x.pdf",
verdict: "ask",
source: "role:reviewer",
reason: "role mapping",
});
const all = await runCli(["brain", "permissions", "ledger", "--vault", vault]);
expect(all.returncode).toBe(0);
const codexAt = all.stdout.indexOf("codex");
const geminiAt = all.stdout.indexOf("gemini");
expect(codexAt).toBeGreaterThanOrEqual(0);
expect(geminiAt).toBeGreaterThan(codexAt);
const filtered = await runCli([
"brain",
"permissions",
"ledger",
"--vault",
vault,
"--actor",
"gemini",
]);
expect(filtered.stdout).toContain("gemini");
expect(filtered.stdout).not.toContain("codex");
const json = await runCli(["brain", "permissions", "ledger", "--vault", vault, "--json"]);
const payload = JSON.parse(json.stdout) as {
rows: Array<{ actor: string; verdict: string; source: string }>;
};
expect(payload.rows.map((r) => r.actor)).toEqual(["codex", "gemini"]);
expect(payload.rows[0]!.source).toBe("entry:freeze-notes");
});
});
describe("the doctor finding", () => {
test("a corrupt document yields exactly one permissions-unreadable error", async () => {
writeDoc("version: 1\ndefault_action: maybe\n");
const result = await runCli(["brain", "doctor", "--vault", vault, "--json"]);
expect(result.returncode).not.toBe(0);
const payload = JSON.parse(result.stdout) as {
errors: Array<{ code: string; message: string }>;
};
const findings = payload.errors.filter((e) => e.code === "permissions-unreadable");
expect(findings).toHaveLength(1);
expect(findings[0]!.message).toContain("default_action");
});
test("a healthy or absent document raises no permissions finding", async () => {
const absent = await runCli(["brain", "doctor", "--vault", vault, "--json"]);
const absentPayload = JSON.parse(absent.stdout) as {
errors: Array<{ code: string }>;
warnings: Array<{ code: string }>;
};
expect(
[...absentPayload.errors, ...absentPayload.warnings].filter(
(e) => e.code === "permissions-unreadable",
),
).toEqual([]);
writeDoc(`${DOCUMENT}\n`);
const healthy = await runCli(["brain", "doctor", "--vault", vault, "--json"]);
const healthyPayload = JSON.parse(healthy.stdout) as {
errors: Array<{ code: string }>;
warnings: Array<{ code: string }>;
};
expect(
[...healthyPayload.errors, ...healthyPayload.warnings].filter(
(e) => e.code === "permissions-unreadable",
),
).toEqual([]);
});
test("the finding names its exit: o2b brain permissions show", async () => {
writeDoc("version: 2\ndefault_action: ask\n");
const result = await runCli(["brain", "doctor", "--vault", vault]);
expect(result.returncode).not.toBe(0);
expect(`${result.stdout}${result.stderr}`).toContain("o2b brain permissions show");
});
});
describe("the permissions-agent-denied finding", () => {
test("a document that denies the locally configured agent's write fires by name", async () => {
writeDoc("version: 1\ndefault_action: deny\n");
const result = await runCli(["brain", "doctor", "--vault", vault, "--json"], {
env: { VAULT_AGENT_NAME: "codex" },
});
const payload = JSON.parse(result.stdout) as {
warnings: Array<{ code: string; message: string; next_command?: string }>;
errors: Array<{ code: string }>;
};
const findings = payload.warnings.filter((w) => w.code === "permissions-agent-denied");
expect(findings).toHaveLength(1);
// By name: the finding names the agent the document denies.
expect(findings[0]!.message).toContain('"codex"');
expect(findings[0]!.message).toContain("o2b brain permissions show");
expect(findings[0]!.next_command).toBe("o2b brain permissions show");
expect(payload.errors.map((e) => e.code)).not.toContain("permissions-agent-denied");
});
test("an agent override out of the deny keeps the finding silent", async () => {
writeDoc("version: 1\ndefault_action: deny\nagents:\n codex:\n write: allow\n");
const result = await runCli(["brain", "doctor", "--vault", vault, "--json"], {
env: { VAULT_AGENT_NAME: "codex" },
});
const payload = JSON.parse(result.stdout) as {
warnings: Array<{ code: string }>;
errors: Array<{ code: string }>;
};
expect(
[...payload.errors, ...payload.warnings].filter((e) => e.code === "permissions-agent-denied"),
).toEqual([]);
});
test("an ask verdict is not a denial", async () => {
writeDoc("version: 1\ndefault_action: ask\n");
const result = await runCli(["brain", "doctor", "--vault", vault, "--json"], {
env: { VAULT_AGENT_NAME: "codex" },
});
const payload = JSON.parse(result.stdout) as {
warnings: Array<{ code: string }>;
errors: Array<{ code: string }>;
};
expect(
[...payload.errors, ...payload.warnings].filter((e) => e.code === "permissions-agent-denied"),
).toEqual([]);
});
});