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
/**
* Tests for src/cli/advisory-rail.ts - the single emission point for
* forward-pointer lines (no-dead-ends, task 2).
*
* The rail owns two decisions and both are pinned here: WHAT to say (a
* payload resolved by code from the diagnostics registry, never a
* caller-supplied sentence) and WHETHER it is legal to say it on the
* current stream (a command that renders its own JSON must not receive
* advisory chrome on stdout; an envelope-wrapped command may, because the
* envelope buffers).
*
* `wantsJsonFlag` is tested alongside because the rail's legality question
* is the reason its raw-argv scan had to become grammar-faithful.
*/
import { afterEach, beforeEach, describe, expect, setDefaultTimeout, test } from "bun:test";
import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import {
ADVISORY_OUTCOME,
advisoryIsLegal,
type AdvisoryEmission,
emitNextStep,
emitNextSteps,
renderNextStepLine,
} from "../../src/cli/advisory-rail.ts";
import {
COMMANDS_WITH_INTERNAL_JSON,
ownsInternalJson,
wantsJsonFlag,
withJsonFallback,
} from "../../src/cli/json-helpers.ts";
import { parseFlags } from "../../src/cli/argparse.ts";
import { writeJson } from "../../src/cli/output.ts";
import { bootstrapBrain } from "../../src/core/brain/init.ts";
import { DIAGNOSTIC_SIGNALS } from "../../src/core/brain/diagnostics.ts";
import { runCli } from "../helpers/run-cli.ts";
import { useUnshardedLegacyLog } from "../helpers/device-id.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);
// The legacy day log and ledgers are read under their un-sharded names.
useUnshardedLegacyLog();
/** A code the registry carries, with a multi-flag structural command. */
const REGISTERED_CODE = "wal-gap";
const REGISTERED_COMMAND = DIAGNOSTIC_SIGNALS.get(REGISTERED_CODE)!.nextCommand;
/** Capture everything written to stdout while `run` executes. */
async function captureStdout(run: () => Promise<void> | void): Promise<string> {
let captured = "";
const real = process.stdout.write;
process.stdout.write = ((chunk: unknown, ...rest: unknown[]) => {
captured += typeof chunk === "string" ? chunk : Buffer.from(chunk as Uint8Array).toString();
const cb = rest[rest.length - 1];
if (typeof cb === "function") (cb as () => void)();
return true;
}) as typeof process.stdout.write;
try {
await run();
} finally {
process.stdout.write = real;
}
return captured;
}
describe("advisory rail - what to say", () => {
test("a human-path emission renders the structural command", async () => {
let result: AdvisoryEmission | undefined;
const out = await captureStdout(() => {
result = emitNextStep(REGISTERED_CODE, {
command: "brain",
argv: ["doctor"],
jsonRequested: false,
});
});
expect(out).toBe(`next: ${REGISTERED_COMMAND}\n`);
expect(result).toEqual({
code: REGISTERED_CODE,
outcome: ADVISORY_OUTCOME.emitted,
nextStep: {
code: REGISTERED_CODE,
issueClass: DIAGNOSTIC_SIGNALS.get(REGISTERED_CODE)!.issueClass,
nextCommand: REGISTERED_COMMAND,
},
line: `next: ${REGISTERED_COMMAND}`,
});
});
test("the rendered line is the label plus the registered command, nothing else", () => {
for (const signal of DIAGNOSTIC_SIGNALS.values()) {
expect(
renderNextStepLine({
code: signal.code,
issueClass: signal.issueClass,
nextCommand: signal.nextCommand,
}),
).toBe(`next: ${signal.nextCommand}`);
}
});
test("an unregistered code emits nothing and reports the absence by name", async () => {
let result: AdvisoryEmission | undefined;
const out = await captureStdout(() => {
result = emitNextStep("no-such-diagnostic-code", {
command: "brain",
argv: ["doctor"],
jsonRequested: false,
});
});
expect(out).toBe("");
expect(result).toEqual({
code: "no-such-diagnostic-code",
outcome: ADVISORY_OUTCOME.unregisteredCode,
nextStep: null,
line: null,
});
});
test("a sentence passed where a code belongs resolves to nothing, never to itself", async () => {
let result: AdvisoryEmission | undefined;
const out = await captureStdout(() => {
result = emitNextStep("Run o2b brain doctor to repair this.", {
command: "brain",
argv: [],
jsonRequested: false,
});
});
expect(out).toBe("");
expect(result!.outcome).toBe(ADVISORY_OUTCOME.unregisteredCode);
expect(result!.line).toBeNull();
});
});
describe("advisory rail - whether it is legal here", () => {
test("a command that renders its own JSON gets no stdout contamination", async () => {
let result: AdvisoryEmission | undefined;
const out = await captureStdout(() => {
writeJson({ ok: true, issues: [] });
result = emitNextStep(REGISTERED_CODE, {
command: "brain",
argv: ["doctor", "--json"],
jsonRequested: true,
});
});
expect(out).toBe(`${JSON.stringify({ ok: true, issues: [] }, undefined, 2)}\n`);
expect(() => JSON.parse(out)).not.toThrow();
expect(result!.outcome).toBe(ADVISORY_OUTCOME.suppressedMachineStream);
expect(result!.line).toBeNull();
// The payload is still resolved, so the verb can carry it as a field.
expect(result!.nextStep!.nextCommand).toBe(REGISTERED_COMMAND);
});
test("the same command on the human path is not suppressed", () => {
expect(advisoryIsLegal({ command: "brain", argv: ["doctor"], jsonRequested: false })).toBe(
true,
);
expect(
advisoryIsLegal({ command: "brain", argv: ["doctor", "--json"], jsonRequested: true }),
).toBe(false);
});
test("an envelope-wrapped command may emit: the envelope buffers the line", async () => {
const stream = { command: "completions", argv: ["bash", "--json"], jsonRequested: true };
expect(advisoryIsLegal(stream)).toBe(true);
const out = await captureStdout(async () => {
await withJsonFallback("completions", async () => {
writeJson({ shell: "bash" });
emitNextStep(REGISTERED_CODE, stream);
return 0;
});
});
const envelope = JSON.parse(out) as { ok: boolean; command: string; stdout: string };
expect(envelope.ok).toBe(true);
expect(envelope.command).toBe("completions");
expect(envelope.stdout).toContain(`next: ${REGISTERED_COMMAND}\n`);
});
test("mcp --probe and help are internal-JSON even though the set omits them", () => {
expect(COMMANDS_WITH_INTERNAL_JSON.has("mcp")).toBe(false);
expect(COMMANDS_WITH_INTERNAL_JSON.has("help")).toBe(false);
expect(ownsInternalJson("mcp", ["--probe", "--json"])).toBe(true);
expect(ownsInternalJson("mcp", ["--json"])).toBe(false);
expect(ownsInternalJson("help", ["--json"])).toBe(true);
expect(advisoryIsLegal({ command: "mcp", argv: ["--probe"], jsonRequested: true })).toBe(false);
});
test("every command owning an internal JSON branch is refused advisory chrome", () => {
for (const command of COMMANDS_WITH_INTERNAL_JSON) {
expect(`${command}: ${ownsInternalJson(command, ["--json"])}`).toBe(`${command}: true`);
expect(`${command}: ${advisoryIsLegal({ command, argv: [], jsonRequested: true })}`).toBe(
`${command}: false`,
);
expect(`${command}: ${advisoryIsLegal({ command, argv: [], jsonRequested: false })}`).toBe(
`${command}: true`,
);
}
});
});
describe("advisory rail - the batch form (no-dead-ends, task 4)", () => {
const HUMAN = { command: "brain", argv: ["doctor"], jsonRequested: false };
test("codes sharing one command print that command once", async () => {
// `broken-wikilink` and `dangling-workrun` are distinct issue
// classes with one repair verb between them.
const shared = DIAGNOSTIC_SIGNALS.get("broken-wikilink")!.nextCommand;
expect(DIAGNOSTIC_SIGNALS.get("dangling-workrun")!.nextCommand).toBe(shared);
let emissions: ReadonlyArray<AdvisoryEmission> = [];
const out = await captureStdout(() => {
emissions = emitNextSteps(
["broken-wikilink", "dangling-workrun", "broken-wikilink", "broken-backlinks"],
HUMAN,
);
});
const backlinks = DIAGNOSTIC_SIGNALS.get("broken-backlinks")!.nextCommand;
expect(out).toBe(`next: ${shared}\nnext: ${backlinks}\n`);
expect(emissions.map((e) => e.outcome)).toEqual([
ADVISORY_OUTCOME.emitted,
ADVISORY_OUTCOME.emitted,
]);
});
test("an unregistered code is reported once by name and never printed", async () => {
let emissions: ReadonlyArray<AdvisoryEmission> = [];
const out = await captureStdout(() => {
emissions = emitNextSteps(
["no-such-diagnostic-code", "no-such-diagnostic-code", REGISTERED_CODE],
HUMAN,
);
});
expect(out).toBe(`next: ${REGISTERED_COMMAND}\n`);
expect(emissions.map((e) => e.outcome)).toEqual([
ADVISORY_OUTCOME.unregisteredCode,
ADVISORY_OUTCOME.emitted,
]);
// "by name" is the whole point of returning an unregistered code at
// all: a caller batching codes must be able to say WHICH of its
// issues has no exit. Asserting only the outcome would let the
// record stop carrying the name without any test noticing.
expect(emissions.map((e) => e.code)).toEqual(["no-such-diagnostic-code", REGISTERED_CODE]);
});
test("no codes means no lines and no emissions", async () => {
let emissions: ReadonlyArray<AdvisoryEmission> = [];
const out = await captureStdout(() => {
emissions = emitNextSteps([], HUMAN);
});
expect(out).toBe("");
expect(emissions).toEqual([]);
});
test("a machine stream still resolves every distinct step, silently", async () => {
let emissions: ReadonlyArray<AdvisoryEmission> = [];
const out = await captureStdout(() => {
emissions = emitNextSteps([REGISTERED_CODE, REGISTERED_CODE], {
command: "brain",
argv: ["doctor", "--json"],
jsonRequested: true,
});
});
expect(out).toBe("");
expect(emissions).toHaveLength(1);
expect(emissions[0]!.outcome).toBe(ADVISORY_OUTCOME.suppressedMachineStream);
expect(emissions[0]!.nextStep!.nextCommand).toBe(REGISTERED_COMMAND);
});
});
describe("wantsJsonFlag - a flag, not a positional value", () => {
test("the flag in its own token is still a JSON request", () => {
expect(wantsJsonFlag(["note", "hello", "--json"])).toBe(true);
expect(wantsJsonFlag(["--json"])).toBe(true);
expect(wantsJsonFlag(["list", "--json=pretty"])).toBe(true);
});
test("no flag at all is not a JSON request", () => {
expect(wantsJsonFlag([])).toBe(false);
expect(wantsJsonFlag(["note", "hello"])).toBe(false);
expect(wantsJsonFlag(["note", "--jsonx"])).toBe(false);
});
test("a note whose text merely mentions the flag is not a JSON request", () => {
expect(wantsJsonFlag(["note", "see --json for details"])).toBe(false);
});
test("after the argv terminator the flag is literal content", () => {
expect(wantsJsonFlag(["note", "--", "--json"])).toBe(false);
expect(wantsJsonFlag(["note", "--", "--json=pretty"])).toBe(false);
expect(wantsJsonFlag(["note", "--json", "--", "--json"])).toBe(true);
});
test("a value-position flag stays a JSON request, and that is deliberate", () => {
// `--principle --json` is the value of a string flag, but which flags
// take a value is per-verb schema the two `main.ts` call sites do not
// have. The scan errs toward the envelope (a buffered extra wrapper)
// rather than toward silencing a human-path advisory, and `--` is the
// documented way to make the token literal. Pinned so the limitation is
// visible rather than discovered.
expect(wantsJsonFlag(["feedback", "--principle", "--json"])).toBe(true);
expect(wantsJsonFlag(["feedback", "--principle", "--", "--json"])).toBe(false);
});
test("the scan agrees with the parser it guards", () => {
const shapes: ReadonlyArray<ReadonlyArray<string>> = [
[],
["--json"],
["hello", "--json"],
["--", "--json"],
["note", "--", "--json"],
["see --json for details"],
];
for (const argv of shapes) {
const parsed = parseFlags(argv, {});
expect(`${argv.join(" ")}: ${wantsJsonFlag(argv)}`).toBe(
`${argv.join(" ")}: ${parsed.flags["json"] === true}`,
);
}
});
});
describe("byte-identical when the rail is not called", () => {
let tmp: string;
let vault: string;
let configPath: string;
beforeEach(() => {
tmp = mkdtempSync(join(tmpdir(), "o2b-advisory-rail-"));
vault = join(tmp, "vault");
configPath = join(tmp, "config.yaml");
writeFileSync(configPath, `vault: ${vault}\nagent_name: test-agent\n`);
bootstrapBrain(vault, { configPath });
});
afterEach(() => {
rmSync(tmp, { recursive: true, force: true });
});
test("a note mentioning the flag stays on the human path and prints its own line", async () => {
const res = await runCli(["brain", "note", "see --json for details"], {
env: { OPEN_SECOND_BRAIN_CONFIG: configPath },
});
expect(res.returncode).toBe(0);
expect(res.stdout).toMatch(/^logged note at Brain\/log\/\d{4}-\d{2}-\d{2}\.md\n$/);
expect(res.stdout).not.toContain("next:");
});
test("the JSON envelope still wraps a command that does not own a JSON branch", async () => {
const plain = await runCli(["completions", "bash"]);
const wrapped = await runCli(["completions", "bash", "--json"]);
expect(plain.returncode).toBe(0);
expect(wrapped.returncode).toBe(0);
expect(JSON.parse(wrapped.stdout)).toEqual({
ok: true,
command: "completions",
code: 0,
stdout: plain.stdout,
stderr: "",
});
expect(plain.stdout).not.toContain("next:");
});
test("a command that owns its JSON branch is untouched", async () => {
const res = await runCli(["help", "--json"]);
expect(res.returncode).toBe(0);
expect(() => JSON.parse(res.stdout)).not.toThrow();
expect(res.stdout).not.toContain("next:");
});
});