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 advisory rail is the only mechanism that emits a forward pointer
* (no-dead-ends, phase 3, item 2).
*
* `advisory-rail.ts` opens by stating that every forward-pointer line the
* CLI prints passes "through this module, and through nothing else".
* That was an aspiration, not a fact: hand-written pointers survived in
* five stdout call sites, one of them in the same file as a migrated one,
* so `clusters list` printed `- run: ...` while `clusters run` printed
* `next: ...`. The census in `terminal-state-census.test.ts` classifies
* which STATES have an exit; nothing stopped a second MECHANISM from
* reappearing beside the rail. This file is that ratchet.
*
* ## How a pointer is detected, structurally
*
* A forward pointer is a literal naming THIS TOOL'S OWN INVOCATION that
* reaches stdout on a success path. Both halves are structural facts
* about the source, not words in any language:
*
* - the invocation is the binary name `o2b` followed by verb tokens;
* - "reaches stdout" is the callee: `ok`, `info` and
* `process.stdout.write` are the CLI's stdout writers, while every
* refusal goes to stderr through `fail`, `failWith`, `usageError` or
* `process.stderr.write`. The refusal family is therefore outside the
* population BY CONSTRUCTION - it is never filtered out by matching
* on what the message says.
*
* Two SHAPES inside that population are not pointers, and each is
* subtracted by a rule rather than by an entry per instance, because both
* recur every time a verb is added:
*
* - a **usage grammar**: the text after the invocation carries this
* CLI's optional-group bracket or its alternation bar. A next command
* never can - it is one exact invocation, and a test below pins that
* against the whole registry.
* - a **self-label**: the literal opens with the invocation followed
* immediately by a colon, which is a command naming its own output
* line, not naming somewhere to go.
*
* ## The limit, stated rather than discovered
*
* The scan reads the arguments of a writer CALL. A literal that reaches
* stdout indirectly - returned by a renderer the caller writes, or pushed
* into an array joined later - is outside what a per-call-site scan can
* see. `o2b search status` was such a site and is migrated here; the
* `install` plan renderers legitimately name per-target commands the
* registry cannot hold and are out of reach of both this ratchet and the
* rail.
*/
import { afterEach, beforeEach, describe, expect, setDefaultTimeout, test } from "bun:test";
import { mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { join, relative } from "node:path";
import { DIAGNOSTIC_SIGNALS } from "../../src/core/brain/diagnostics.ts";
import { resolveNextStep } from "../../src/core/brain/next-step.ts";
import { bootstrapBrain } from "../../src/core/brain/init.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);
const REPO_ROOT = join(import.meta.dir, "..", "..");
const CLI_ROOT = join(REPO_ROOT, "src", "cli");
/**
* The CLI's stdout writers. `okJson` and `writeJson` are deliberately
* absent: they serialise a payload, and a next command belongs in that
* payload as a field, which is a different mechanism with its own test.
*/
const STDOUT_WRITER_RE = /(?:\bok|\binfo|process\.stdout\.write)\(/g;
/** This tool's own invocation: the binary name plus its verb tokens. */
const INVOCATION_RE = /\bo2b(?:\s+[a-z][a-z0-9-]*)+/g;
/**
* This CLI's usage notation: an optional group or an alternation. A
* `nextCommand` is one exact invocation and carries neither - pinned
* against the whole registry by a test below.
*/
const USAGE_NOTATION_RE = /[[|]/;
/** A source-level string delimiter. */
const QUOTE_RE = /['"`]$/;
/**
* Sites where a literal invocation reaches stdout and the rail genuinely
* cannot carry it. `count` pins how many such literals the site holds, so
* a NEW hand-written pointer in an already-sanctioned file fails here
* instead of hiding behind its neighbour's reason.
*/
interface SanctionedPointer {
readonly count: number;
readonly reason: string;
}
const SANCTIONED: Readonly<Record<string, SanctionedPointer>> = Object.freeze({
"src/cli/brain/verbs/protect.ts :: o2b brain protect": {
count: 1,
reason:
"provenance header of a generated artifact, not a pointer: the preview writes the deny-rule " +
"file to stdout for redirection and names, in a comment line, the command that produced it. " +
"The operator has already run it; there is nothing forward about it.",
},
"src/cli/brain/verbs/protect.ts :: o2b brain unprotect": {
count: 1,
reason:
"provenance header of the preview report, not a pointer: the read-only print mode stamps, " +
"in a comment line, the command that produced the diff below it - the same header its " +
"protect sibling stamps on the redirected artifact. The operator has already run it; the " +
"only forward guidance on the page is the `re-run with --apply` line, which carries no " +
"invocation literal.",
},
"src/cli/main.ts :: o2b search check": {
count: 1,
reason:
"part of the semantic-search configuration template, whose two commands are the verification " +
"sequence AFTER the operator edits the keys printed immediately above them. Neither is " +
"runnable until that edit happens, and the rail resolves one structural command per code - it " +
"cannot express an ordered pair conditioned on a manual step.",
},
"src/cli/main.ts :: o2b search index": {
count: 1,
reason:
"the second half of that same configuration template (`o2b search index --embeddings`). It is " +
"listed for the identical reason and is counted separately so a new hand-written pointer " +
"naming this verb in this module cannot hide behind the template's entry.",
},
"src/cli/main.ts :: o2b install-cli": {
count: 1,
reason:
"`o2b uninstall --help` prose describing what `--remove-cli` removes, by naming the command " +
"that created those symlinks in the past. It is a mention of a command already run, not a " +
"command to run next, and routing it through the rail would advise the operator to reinstall " +
"the very symlinks the paragraph is about removing.",
},
"src/cli/state.ts :: o2b state rollback": {
count: 1,
reason:
"the undo line on a completed `state migrate --apply` receipt, which must name the " +
"destination the operator chose seconds earlier: `o2b state rollback --from <that dir>`. " +
"The rail resolves ONE structural command per diagnostic code and has no parameter through " +
"which a runtime path can enter, by design - so a registered signal here could only name a " +
"command that does not run. It sits beside the manifest path in the same receipt for the " +
"same reason: both are facts about the move that just happened.",
},
"src/cli/bootstrap/run.ts :: o2b bootstrap": {
count: 1,
reason:
"the failed-registration receipt beside a mint that already landed: `re-run o2b bootstrap " +
"--target <the target this run provisioned>`. The target is runtime state, the rail resolves " +
"one structural command per code with no parameter channel, so a registered signal could " +
"only advise bootstrapping a target other than the one that just failed.",
},
"src/cli/bootstrap/run.ts :: o2b mcp token revoke": {
count: 1,
reason:
"the cleanup half of that same failed-registration receipt: `o2b mcp token revoke --name " +
"<the token minted seconds ago>`. The name exists only in this run and is printed once, in " +
"the line above; the rail's structural registry cannot carry it, and an unparameterized " +
"revoke could only name the wrong credential.",
},
"src/cli/bootstrap/run.ts :: o2b install is removed with": {
count: 1,
reason:
"prose on the nothing-to-remove receipt: `a registration written by o2b install is removed " +
"with: o2b uninstall --target <target> --apply`. The detector reads the sentence's first `o2b` " +
"token run as the invocation; the pointer it frames is the runtime-parameterized uninstall " +
"named in the sibling entry, which the rail cannot carry.",
},
"src/cli/bootstrap/run.ts :: o2b uninstall": {
count: 1,
reason:
"the command half of that same nothing-to-remove receipt line: `o2b uninstall --target " +
"<target> --apply`. Runtime-parameterized like its prose sibling and counted separately, so " +
"a new hand-written pointer naming this verb in this module cannot hide behind the prose " +
"entry.",
},
});
/** A reason has to say something; a placeholder cannot reach this. */
const MIN_REASON_LENGTH = 80;
const readSource = (path: string): string => readFileSync(path, "utf8");
function cliFiles(dir: string = CLI_ROOT): string[] {
const out: string[] = [];
for (const entry of readdirSync(dir, { withFileTypes: true })) {
const abs = join(dir, entry.name);
if (entry.isDirectory()) out.push(...cliFiles(abs));
else if (entry.name.endsWith(".ts")) out.push(abs);
}
return out;
}
/**
* The argument text of a call whose opening paren sits at `start`.
* Quote-aware, so a paren inside a string literal cannot unbalance the
* scan and a multi-line argument (an array joined into one write) is
* read whole.
*/
function argumentText(text: string, start: number): string {
let depth = 1;
let quote: string | null = null;
let i = start;
while (i < text.length && depth > 0) {
const ch = text[i]!;
if (quote !== null) {
if (ch === "\\") i += 1;
else if (ch === quote) quote = null;
} else if (ch === '"' || ch === "'" || ch === "`") {
quote = ch;
} else if (ch === "(") {
depth += 1;
} else if (ch === ")") {
depth -= 1;
}
i += 1;
}
return text.slice(start, i - 1);
}
/**
* True when the invocation at `at` inside `args` is one of the two
* non-pointer shapes: a usage grammar, or the command labelling its own
* output line. Both are read from the source text around the match, not
* from what the sentence says.
*/
function isNotAPointer(args: string, at: number, invocation: string): boolean {
const before = args.slice(0, at);
const after = args.slice(at + invocation.length);
// Usage grammar: bounded to the invocation's own line, so a bracket
// somewhere else in a multi-line argument cannot excuse it.
const restOfLine = after.split("\n", 1)[0]!;
if (USAGE_NOTATION_RE.test(restOfLine)) return true;
// Self-label: the literal opens with the invocation, and a colon
// follows it immediately.
return QUOTE_RE.test(before) && after.startsWith(":");
}
/** Every invocation literal written to stdout from `text`. */
function pointersIn(text: string): ReadonlyArray<string> {
const found: string[] = [];
for (const match of text.matchAll(STDOUT_WRITER_RE)) {
const args = argumentText(text, match.index! + match[0].length);
for (const invocation of args.matchAll(INVOCATION_RE)) {
if (isNotAPointer(args, invocation.index!, invocation[0])) continue;
found.push(invocation[0]);
}
}
return found;
}
/** `<relative path> :: <invocation>` -> how many times it was measured. */
function census(): ReadonlyMap<string, number> {
const counts = new Map<string, number>();
for (const path of cliFiles()) {
const rel = relative(REPO_ROOT, path).split("\\").join("/");
for (const invocation of pointersIn(readSource(path))) {
const key = `${rel} :: ${invocation}`;
counts.set(key, (counts.get(key) ?? 0) + 1);
}
}
return counts;
}
describe("the rail is the only forward-pointer mechanism", () => {
test("no unsanctioned invocation literal reaches stdout", () => {
const unsanctioned = [...census().keys()]
.filter((key) => SANCTIONED[key] === undefined)
.toSorted();
// Named, not counted: the failure message is the work to be done.
expect(unsanctioned.join("\n")).toBe("");
});
test("every sanctioned site still exists and holds exactly what it declares", () => {
const measured = census();
for (const [key, entry] of Object.entries(SANCTIONED)) {
expect(`${key} measured: ${measured.get(key) ?? 0}`).toBe(`${key} measured: ${entry.count}`);
}
});
test("every sanctioned reason is specific", () => {
for (const [key, entry] of Object.entries(SANCTIONED)) {
expect(`${key} reason is specific: ${entry.reason.trim().length >= MIN_REASON_LENGTH}`).toBe(
`${key} reason is specific: true`,
);
}
});
test("the detector is not vacuous - it still matches the shapes it removed", () => {
// The exact literals this change migrated. A regex that stopped
// matching would otherwise sweep the whole tree clean.
const removed = [
'ok("no dream bundles - run: o2b brain dream stage");',
'else ok("no cluster notes yet - run: o2b brain clusters run");',
'ok("tune: no valid tuned parameters persisted - run: o2b brain tune run --dataset <path>");',
'ok("resolve with: o2b brain tiers restore <path> --apply (or accept <path>)");',
'process.stdout.write(" next: o2b search index # build the vault search index\\n");',
];
for (const line of removed) {
expect(`${line} detected: ${pointersIn(line).length}`).toBe(`${line} detected: 1`);
}
// And a refusal naming a command is NOT a forward pointer.
expect(pointersIn('return fail("run o2b brain init first");')).toEqual([]);
expect(pointersIn('process.stderr.write("usage: o2b brain dream\\n");')).toEqual([]);
});
test("the two subtracted shapes are subtracted, and only those", () => {
// A usage grammar carries this CLI's optional-group bracket or its
// alternation bar.
expect(
pointersIn('process.stdout.write("usage: o2b secrets list|status [args...]\\n");'),
).toEqual([]);
expect(
pointersIn('process.stdout.write("usage: o2b brain snapshot <verb> [args...]\\n");'),
).toEqual([]);
// A self-label opens the line with the invocation and a colon.
expect(pointersIn("process.stdout.write(`o2b discipline: job created\\n`);")).toEqual([]);
// Neither rule excuses a bare pointer that merely starts the line...
expect(pointersIn('ok("o2b brain clusters run");')).toEqual(["o2b brain clusters run"]);
// ...nor one whose own arguments use the angle-bracket placeholder
// shape a real next command does use.
expect(pointersIn('ok("run: o2b brain tune run --dataset <path>");')).toEqual([
"o2b brain tune run",
]);
});
test("no registered next command could be mistaken for a usage grammar", () => {
// The usage-notation rule is only sound while this holds.
const offenders = [...DIAGNOSTIC_SIGNALS.values()]
.filter((signal) => USAGE_NOTATION_RE.test(signal.nextCommand))
.map((signal) => `${signal.code}: ${signal.nextCommand}`);
expect(offenders.toSorted().join("\n")).toBe("");
});
test("the sanctioned table stays an exception", () => {
// Every measured site is sanctioned (test one), so the table's size
// IS the number of unmigrated sites. Five was the ceiling this change
// inherited; 6-9 are the bootstrap receipt's four measured literals,
// each interpolating runtime state (`--target`, `--name`) the rail
// structurally cannot carry because it resolves one structural
// command per code with no parameter channel - the same argument the
// `state migrate` undo line makes. 10 is the unprotect preview's
// provenance header, the same not-a-pointer shape as its protect
// sibling one entry above. An eleventh needs its own argument.
expect(Object.keys(SANCTIONED).length).toBeLessThanOrEqual(10);
});
});
describe("the migrated codes resolve to a structural command", () => {
test("each new registry code names its exit", () => {
const expected: ReadonlyArray<readonly [string, string]> = [
["dream-bundles-absent", "o2b brain dream stage"],
["cluster-notes-absent", "o2b brain clusters run"],
["recall-tuning-absent", "o2b brain tune run --dataset <path>"],
["tier-drift-restore", "o2b brain tiers restore <path> --apply"],
["tier-drift-accept", "o2b brain tiers accept <path>"],
];
for (const [code, command] of expected) {
expect(`${code} -> ${resolveNextStep(code)?.nextCommand ?? "(unregistered)"}`).toBe(
`${code} -> ${command}`,
);
}
});
});
describe("the migrated verbs emit through the rail", () => {
let tmp: string;
let vault: string;
let configPath: string;
const savedEnv: Record<string, string | undefined> = {};
beforeEach(() => {
tmp = mkdtempSync(join(tmpdir(), "o2b-pointer-rail-"));
vault = join(tmp, "vault");
configPath = join(tmp, "config.yaml");
for (const key of ["VAULT_DIR", "OPEN_SECOND_BRAIN_CONFIG", "VAULT_AGENT_NAME"]) {
savedEnv[key] = process.env[key];
delete process.env[key];
}
writeFileSync(configPath, `vault: ${vault}\nagent_name: claude\n`);
bootstrapBrain(vault, { configPath });
});
afterEach(() => {
rmSync(tmp, { recursive: true, force: true });
for (const [key, value] of Object.entries(savedEnv)) {
if (value === undefined) delete process.env[key];
else process.env[key] = value;
}
});
test("brain dream list with no bundles names the stage command", async () => {
const r = await runCli(["brain", "dream", "list", "--vault", vault]);
expect(r.returncode).toBe(0);
expect(r.stdout).toContain("next: o2b brain dream stage\n");
expect(r.stdout).not.toContain("- run:");
});
test("brain clusters list names the same exit whether the directory is missing or empty", async () => {
const missing = await runCli(["brain", "clusters", "list", "--vault", vault]);
expect(missing.returncode).toBe(0);
expect(missing.stdout).toContain("next: o2b brain clusters run\n");
// The empty-directory branch reached the SAME state and previously
// said nothing forward at all.
mkdirSync(join(vault, "Brain", "clusters"), { recursive: true });
const empty = await runCli(["brain", "clusters", "list", "--vault", vault]);
expect(empty.returncode).toBe(0);
expect(empty.stdout).toContain("next: o2b brain clusters run\n");
});
test("brain tune status with nothing persisted names the tuning run", async () => {
const r = await runCli(["brain", "tune", "status", "--vault", vault]);
expect(r.returncode).toBe(0);
expect(r.stdout).toContain("next: o2b brain tune run --dataset <path>\n");
});
test("the rail line stays off the machine stream", async () => {
for (const argv of [
["brain", "dream", "list", "--vault", vault, "--json"],
["brain", "clusters", "list", "--vault", vault, "--json"],
["brain", "tune", "status", "--vault", vault, "--json"],
]) {
// oxlint-disable-next-line no-await-in-loop -- runCli patches process.stdout in-process, so concurrent invocations would interleave each other's captured output
const r = await runCli(argv);
expect(`${argv[1]} exit: ${r.returncode}`).toBe(`${argv[1]} exit: 0`);
expect(`${argv[1]} clean: ${!r.stdout.includes("next: ")}`).toBe(`${argv[1]} clean: true`);
expect(() => JSON.parse(r.stdout)).not.toThrow();
}
});
test("search status with no index names the indexer through the rail", async () => {
const r = await runCli(["search", "status", "--vault", vault, "--db", join(tmp, "none.db")]);
expect(r.returncode).toBe(0);
expect(r.stdout).toContain("next: o2b search index\n");
expect(r.stdout).not.toContain("Run: o2b search index");
});
});