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
/**
* Test helper: run the `o2b` CLI as a subprocess and capture stdout/stderr/code.
*
* Each invocation gets an isolated `OPEN_SECOND_BRAIN_CONFIG` so init-tests
* never clobber the developer's `~/.config/open-second-brain/config.yaml`.
* Tests that explicitly want to verify default-config behavior can pass their
* own value in `env`.
*/
import { mkdtempSync, rmSync } from "node:fs";
import { tmpdir } from "node:os";
import { join, dirname, resolve } from "node:path";
import { fileURLToPath } from "node:url";
import { main } from "../../src/cli/main.ts";
import { PARTNER_CODEGRAPH_DISABLED_ENV } from "../../src/core/config.ts";
import { STORE_ROOT_ENV } from "../../src/core/store/constants.ts";
import { CLI_CHILD_LIMIT_MS, EXIT_DRAIN_GRACE_MS, KILL_REAP_MS } from "./cli-timeout.ts";
import { DEFAULT_STORE_ROOT_ENV } from "./test-store.ts";
import { windowsProcessAfterKill, windowsProcessState } from "./windows-process-probe.ts";
export interface RunResult {
readonly stdout: string;
readonly stderr: string;
readonly returncode: number;
/**
* Set only when the child exited but its output pipes stayed open past a
* short grace period (a process it started holds them); says which and
* for how long. The same line goes to this process's stderr.
*/
readonly warning?: string;
}
const HERE = dirname(fileURLToPath(import.meta.url));
const ROOT = resolve(HERE, "..", "..");
const CLI_ENTRY = join(ROOT, "src", "cli", "main.ts");
/**
* Env vars that the CLI reads for vault / identity / timezone resolution
* AND `OPEN_SECOND_BRAIN_CONFIG` itself. Each one MUST start unset in tests
* unless the caller passes it explicitly — the developer's shell almost
* certainly has `VAULT_AGENT_NAME`, `OPEN_SECOND_BRAIN_CONFIG`, etc. pointing
* at their real vault / persisted config; if we let those leak into the
* child process, init-tests can write to the real `~/.config/open-second-brain/`
* instead of a per-test sandbox.
*/
const RUNTIME_OVERRIDABLE_ENV = [
"VAULT_DIR",
"VAULT_AGENT_NAME",
"VAULT_TIMEZONE",
"OPEN_SECOND_BRAIN_CONFIG",
"OPEN_SECOND_BRAIN_TRIGGER_COOLDOWN_DAYS",
"OPEN_SECOND_BRAIN_WIKI_LINK_FORMAT",
"OPEN_SECOND_BRAIN_RECALL_GATE_TELEMETRY",
"OPEN_SECOND_BRAIN_BENCH_JUDGE_CMD",
"OPEN_SECOND_BRAIN_POST_COMPACT_SURVIVAL_AUDIT",
// Search-lane selection. `resolveSearchConfig` reads these straight off
// `process.env`, so a developer with semantic search configured ran a
// DIFFERENT pipeline than CI - against a remote embedding provider -
// and every "deterministic and network-free" claim in the tree was a
// property of an unset shell rather than of the code.
"OPEN_SECOND_BRAIN_SEARCH_SEMANTIC",
"OPEN_SECOND_BRAIN_EMBEDDING_PROVIDER",
// The optional decision model: a developer who enabled it in the shell
// must not turn a network-free test into one that calls an endpoint.
"OPEN_SECOND_BRAIN_DECISION_MODEL_ENABLED",
"OPEN_SECOND_BRAIN_DECISION_MODEL_PROVIDER",
"OPEN_SECOND_BRAIN_DECISION_MODEL_BASE_URL",
"OPEN_SECOND_BRAIN_DECISION_MODEL_ID",
"OPEN_SECOND_BRAIN_DECISION_MODEL_ENV_KEY",
"OPEN_SECOND_BRAIN_DECISION_MODEL_ALLOW_INSECURE_HTTP",
"OPEN_SECOND_BRAIN_DECISION_MODEL_TIMEOUT_MS",
"OPEN_SECOND_BRAIN_DECISION_MODEL_HOOK_BUDGET_MS",
"OPEN_SECOND_BRAIN_DECISION_MODEL_MAX_STATE_TOKENS",
"OPEN_SECOND_BRAIN_DECISION_MODEL_USES",
"OPEN_SECOND_BRAIN_DECISION_MODEL_COST_GATE_USD",
"OPEN_SECOND_BRAIN_DECISION_MODEL_INPUT_PRICE_USD_PER_MTOK",
"OPEN_SECOND_BRAIN_DECISION_MODEL_ALLOW_UNCALIBRATED",
// The codegraph partner switch, for the same reason and with a default
// of its own below.
PARTNER_CODEGRAPH_DISABLED_ENV,
// The secret store's environment unlock is consumed-once; a developer
// shell that happens to carry it must not turn a locked-store test into
// an unlocked one (or steal the value mid-run).
"OPEN_SECOND_BRAIN_SECRETS_PASSPHRASE",
// Lesson-promotion scope selection (t_1e952e43). A developer shell
// carrying an enabled scope must not silently flip the promotion gate
// in every lessons CLI test.
"OPEN_SECOND_BRAIN_LESSONS_PROMOTION_SCOPES",
] as const;
export interface RunCliOptions {
readonly env?: Record<string, string>;
readonly stdin?: string;
readonly cwd?: string;
/**
* Force a fresh child process instead of the in-process fast path. The
* in-process path imports `main()` once and calls it directly - two orders of
* magnitude cheaper than spawning `bun run src/cli/main.ts` per call (that
* re-parses and re-evaluates the whole CLI import graph every time). Set this
* only when a test genuinely needs OS-level process isolation (real stdin, a
* long-running server command, signal handling). Passing `stdin` implies it.
*/
readonly subprocess?: boolean;
/**
* The longest a spawned child may run (default {@link CLI_CHILD_LIMIT_MS}).
* Only the subprocess path has one; a caller whose test timeout is
* shorter than `CLI_SPAWN_BUDGET_MS` passes
* `cliChildLimitFor(<its timeout>)` (`cli-timeout.ts`).
*/
readonly limitMs?: number;
}
/**
* The real `process.env` on Windows is case-insensitive: the variable the
* OS calls `Path` answers to `process.env.PATH`, which is how the product
* reads it. The in-process runner swaps in a plain object copy, which is
* case-SENSITIVE, so without this fold every `process.env["PATH"]` read in
* the CLI saw `undefined` (snapshot tooling then reported `tar` missing),
* and a caller's `PATH` override sat beside the inherited `Path` instead of
* replacing it. Rename inherited `Path` to `PATH`, and drop any inherited
* key that differs from a caller key only by case.
*/
function foldWindowsEnvCase(env: Record<string, string>, callerEnv: Record<string, string>): void {
for (const key of Object.keys(env)) {
if (key !== "PATH" && key.toUpperCase() === "PATH") {
if (!("PATH" in env)) env["PATH"] = env[key] as string;
delete env[key];
}
}
const callerUpper = new Set(Object.keys(callerEnv).map((k) => k.toUpperCase()));
for (const key of Object.keys(env)) {
if (callerUpper.has(key.toUpperCase()) && !(key in callerEnv)) delete env[key];
}
}
/**
* Compute the child environment the caller's overrides produce, mirroring the
* process-level resolution the CLI performs from `process.env`.
*/
function resolveEnv(callerEnv: Record<string, string>): {
env: Record<string, string>;
cleanupDir: string | null;
} {
const env: Record<string, string> = { ...process.env } as Record<string, string>;
for (const key of RUNTIME_OVERRIDABLE_ENV) {
if (!(key in callerEnv)) delete env[key];
}
if (process.platform === "win32") foldWindowsEnvCase(env, callerEnv);
Object.assign(env, callerEnv);
// A caller that sandboxes HOME means "the user's home directory". On
// Windows `os.homedir()` answers from USERPROFILE and ignores HOME, so
// without this mirror an install test wrote the operator's real
// `%USERPROFILE%\.cursor\mcp.json` instead of the temp home it named.
if (process.platform === "win32" && "HOME" in callerEnv && !("USERPROFILE" in callerEnv)) {
env["USERPROFILE"] = callerEnv["HOME"] as string;
}
// `o2b doctor` consults the codegraph partner by spawning a third-party
// CLI once per discovered project whenever that binary is on PATH. The
// suite runs from this repo, which IS such a project, so the check ran
// for real on any developer machine with codegraph installed and did not
// run at all on CI, where the binary is absent - the suite's cost and its
// dependency on a foreign tool were both properties of the machine. On
// this workstation that was 96.0 s for `tests/cli/cli.test.ts` against
// 1.1 s with the partner left alone. Tests keep the switch ON by default
// and the partner check has its own coverage that calls `doctor()`
// directly; a caller that wants the real consultation passes the key.
if (!(PARTNER_CODEGRAPH_DISABLED_ENV in env)) env[PARTNER_CODEGRAPH_DISABLED_ENV] = "true";
let cleanupDir: string | null = null;
if (!("OPEN_SECOND_BRAIN_CONFIG" in env)) {
cleanupDir = mkdtempSync(join(tmpdir(), "o2b-test-"));
env["OPEN_SECOND_BRAIN_CONFIG"] = join(cleanupDir, "isolated-config.yaml");
}
// `o2b init` creates the brain store (design D14 item 1). A run that
// still names the preload's shared default root gets a root of its own,
// removed with the run, so one test's store never leaks into another.
// A caller (or a test that set the variable itself) keeps its root.
const sharedRoot = env[DEFAULT_STORE_ROOT_ENV];
if (
!(STORE_ROOT_ENV in callerEnv) &&
sharedRoot !== undefined &&
env[STORE_ROOT_ENV] === sharedRoot
) {
cleanupDir ??= mkdtempSync(join(tmpdir(), "o2b-test-"));
env[STORE_ROOT_ENV] = join(cleanupDir, "store");
}
return { env, cleanupDir };
}
/**
* The current directory, or null when the process no longer has one.
*
* `process.cwd()` throws ENOENT once the directory it names is deleted,
* which happens routinely in a suite that chdirs into temp vaults and
* removes them. A run does not need to know where it started to work; only
* the restore does, and it can honestly do nothing when there is nowhere
* to return to.
*/
function currentDirectoryOrNull(): string | null {
try {
return process.cwd();
} catch {
return null;
}
}
/** A `process.stdout.write`-shaped sink that appends decoded chunks to `sink`. */
function captureWrite(sink: (s: string) => void) {
return (chunk: unknown, ...rest: unknown[]): boolean => {
sink(typeof chunk === "string" ? chunk : Buffer.from(chunk as Uint8Array).toString("utf8"));
const cb = rest[rest.length - 1];
if (typeof cb === "function") (cb as () => void)();
return true;
};
}
/** A stream being read into a sink, and the way to stop reading it. */
interface Drain {
readonly done: Promise<void>;
/** Whether end-of-file has arrived. */
readonly ended: () => boolean;
/** Stops reading and closes the pipe, so its writers see it closed. */
readonly cancel: () => void;
}
/** Appends a stream's decoded text to `sink` as it arrives. */
function drain(stream: ReadableStream<Uint8Array>, sink: (s: string) => void): Drain {
const reader = stream.getReader();
const decoder = new TextDecoder();
let ended = false;
const pump = (): Promise<void> =>
reader.read().then((chunk) => {
if (chunk.done) {
ended = true;
sink(decoder.decode());
return undefined;
}
sink(decoder.decode(chunk.value, { stream: true }));
return pump();
});
return {
done: pump(),
ended: () => ended,
cancel: () => {
reader.cancel().catch(() => undefined);
},
};
}
/** Resolves `"late"` after `ms`; `clear` cancels the timer. */
function lateAfter(ms: number): { readonly late: Promise<"late">; readonly clear: () => void } {
let timer: ReturnType<typeof setTimeout> | undefined;
const late = new Promise<"late">((done) => {
timer = setTimeout(() => done("late"), ms);
});
return { late, clear: () => clearTimeout(timer) };
}
export interface SpawnWithLimitOptions {
readonly env: Record<string, string>;
readonly cwd?: string;
/** Written to the child's stdin, then closed; absent, stdin is ignored. */
readonly stdin?: string;
readonly limitMs: number;
}
/**
* Runs `cmd` to completion and captures its output, but never longer than
* `limitMs`: a child still running then is killed, and the call fails with
* the command line, the elapsed time, when its last output arrived and the
* stdout and stderr captured so far. A child that hangs (seen on the
* Windows runner) thus fails its test with evidence instead of a bare test
* timeout. No retry.
*
* The child's exit decides, not end-of-file on its pipes: a process the
* child started can inherit the pipes and keep them open long after the
* child is gone. After the exit the pipes get {@link EXIT_DRAIN_GRACE_MS}
* to deliver what is buffered; a pipe still open then is closed on this
* side, and the result carries a `warning` (also written to this process's
* stderr) naming the open pipes, so a leaked handle is seen, not hidden.
* The readers are stopped with a limit failure too, so they never outlive
* the call. On Windows the failure also names the child's state from the
* operating system at the limit and whether it is gone after the kill
* (`windows-process-probe.ts`).
*/
export async function spawnWithLimit(
cmd: ReadonlyArray<string>,
opts: SpawnWithLimitOptions,
): Promise<RunResult> {
const started = Date.now();
const proc = Bun.spawn([...cmd], {
cwd: opts.cwd ?? ROOT,
env: opts.env,
stdin: opts.stdin === undefined ? "ignore" : "pipe",
stdout: "pipe",
stderr: "pipe",
});
let stdout = "";
let stderr = "";
let lastOutputAt: number | null = null;
const outputAt = (): void => {
lastOutputAt = Date.now();
};
const drains = [
drain(proc.stdout, (s) => {
if (s !== "") outputAt();
stdout += s;
}),
drain(proc.stderr, (s) => {
if (s !== "") outputAt();
stderr += s;
}),
];
const stopReading = (): void => {
for (const d of drains) d.cancel();
};
const output = Promise.all(drains.map((d) => d.done));
// A reader's failure surfaces after the exit, where `output` is awaited.
output.catch(() => undefined);
const run = (async (): Promise<number> => {
if (opts.stdin !== undefined && proc.stdin !== undefined) {
proc.stdin.write(opts.stdin);
await proc.stdin.end();
}
return await proc.exited;
})();
const limit = lateAfter(opts.limitMs);
let outcome: number | "late";
try {
outcome = await Promise.race([run, limit.late]);
} catch (err) {
// A failed run (stdin delivery) must not leave the child running
// without its limit.
proc.kill("SIGKILL");
stopReading();
throw err;
} finally {
limit.clear();
}
if (outcome !== "late") return await afterExit(outcome);
const elapsedMs = Date.now() - started;
const windows = process.platform === "win32";
const atLimit = windows ? await windowsProcessState(proc.pid, started) : null;
proc.kill("SIGKILL");
await Promise.race([proc.exited, new Promise((r) => setTimeout(r, KILL_REAP_MS))]);
const afterKill = windows
? windowsProcessAfterKill(proc.pid, proc.exitCode ?? proc.signalCode)
: null;
stopReading();
// Keep the run's late rejection (if any) from surfacing unhandled.
run.catch(() => undefined);
const lastOutput: number | null = lastOutputAt;
throw new Error(
[
`CLI child still running after the ${opts.limitMs} ms per-call limit: killed.`,
`command: ${cmd.map((part) => JSON.stringify(part)).join(" ")}`,
`cwd: ${opts.cwd ?? ROOT}`,
`pid: ${proc.pid}, elapsed ${elapsedMs} ms, exit after kill: ${proc.exitCode ?? "not reaped"}, stdin: ${opts.stdin === undefined ? "ignored" : `${opts.stdin.length} chars, closed`}`,
// Output that arrived after the limit (during the probe and the
// kill) means a slow child, not a stuck one.
`last output: ${lastOutput === null ? "none" : `${lastOutput - started} ms after the spawn`}`,
...(atLimit === null ? [] : [atLimit]),
...(afterKill === null ? [] : [afterKill]),
`--- stdout so far (${stdout.length} chars) ---`,
stdout,
`--- stderr so far (${stderr.length} chars) ---`,
stderr,
].join("\n"),
);
/** The result once the child exited, with at most a short wait for its pipes. */
async function afterExit(returncode: number): Promise<RunResult> {
const grace = lateAfter(EXIT_DRAIN_GRACE_MS);
let drained: void[] | "late";
try {
drained = await Promise.race([output, grace.late]);
} finally {
grace.clear();
}
if (drained !== "late") return { stdout, stderr, returncode };
const open = [drains[0]?.ended() ? null : "stdout", drains[1]?.ended() ? null : "stderr"]
.filter((name): name is string => name !== null)
.join(" and ");
stopReading();
const warning =
`${open} still open ${EXIT_DRAIN_GRACE_MS} ms after the child exited with ${returncode}: ` +
"a process it started holds the pipe; the result is returned without waiting for it";
process.stderr.write(
`spawnWithLimit: ${warning}\ncommand: ${cmd.map((part) => JSON.stringify(part)).join(" ")}\n`,
);
return { stdout, stderr, returncode, warning };
}
}
/** Fresh-process invocation - the original behavior, kept for isolation cases. */
async function runCliSubprocess(
args: ReadonlyArray<string>,
opts: RunCliOptions,
): Promise<RunResult> {
const { env, cleanupDir } = resolveEnv(opts.env ?? {});
let result: RunResult;
try {
result = await spawnWithLimit(["bun", "run", CLI_ENTRY, ...args], {
env,
...(opts.cwd !== undefined ? { cwd: opts.cwd } : {}),
...(opts.stdin !== undefined ? { stdin: opts.stdin } : {}),
limitMs: opts.limitMs ?? CLI_CHILD_LIMIT_MS,
});
} catch (err) {
// After a killed child (Windows keeps its files busy for a moment) a
// failed cleanup must not replace the evidence.
if (cleanupDir !== null) {
try {
rmSync(cleanupDir, { recursive: true, force: true });
} catch {
// the evidence below matters more than the temp directory
}
}
throw err;
}
if (cleanupDir !== null) rmSync(cleanupDir, { recursive: true, force: true });
return result;
}
/**
* In-process invocation: apply the resolved env + cwd, capture stdout/stderr,
* call `main()`, then restore everything. `main()` never calls `process.exit`
* (that lives behind its `import.meta.main` guard) and returns an exit code, so
* a direct call is a faithful black-box of the full parse + dispatch path. An
* uncaught throw is mapped to code 1 with the message on stderr, matching how a
* crashing child process would surface.
*/
/**
* In-process runs mutate process-wide state - the environment, the working
* directory, and both output streams - and restore it in a `finally`. Two
* overlapping runs therefore capture each other’s swapped state as their
* "saved" state and restore the wrong thing, which leaves a test-scoped
* config path installed for the rest of the process and misroutes captured
* output. The corruption surfaces far away, in an unrelated later file, as
* a vault that cannot be found.
*
* So overlapping is refused rather than survived. A caller that genuinely
* needs concurrency passes `subprocess: true`, which owns none of this
* state.
*/
let inProcessRunActive = false;
/** Thrown when a second in-process CLI run starts while one is still open. */
export class ConcurrentInProcessRunError extends Error {
constructor(args: ReadonlyArray<string>) {
super(
`runCli(${JSON.stringify(args)}) started while another in-process run was ` +
"still open. In-process runs swap process.env, the working directory and " +
"both output streams, so they cannot overlap: await each run, or pass " +
"{ subprocess: true } for the ones that must run concurrently.",
);
this.name = "ConcurrentInProcessRunError";
}
}
async function runCliInProcess(
args: ReadonlyArray<string>,
opts: RunCliOptions,
): Promise<RunResult> {
if (inProcessRunActive) throw new ConcurrentInProcessRunError(args);
inProcessRunActive = true;
// Everything from here to the outer `finally` runs under the flag,
// setup included. An earlier version claimed the flag only while the CLI
// itself ran, which left `resolveEnv` and `process.cwd()` outside it -
// and `process.cwd()` throws ENOENT when the directory a test removed is
// still the process's own, which is routine in a suite that builds and
// deletes temp vaults. A throw there left the flag raised for the rest of
// the process and every later run failed blaming a concurrency that never
// happened, which is the same misdirected report this guard exists to
// stop.
let savedEnv: NodeJS.ProcessEnv | null = null;
let savedCwd: string | null = null;
let realOut: typeof process.stdout.write | null = null;
let realErr: typeof process.stderr.write | null = null;
let cleanupDir: string | null = null;
let stdout = "";
let stderr = "";
try {
const resolved = resolveEnv(opts.env ?? {});
cleanupDir = resolved.cleanupDir;
savedEnv = process.env;
// A cwd that no longer exists is not an error here: the run is about to
// chdir anyway, and only the restore needs somewhere to go back to.
savedCwd = currentDirectoryOrNull();
realOut = process.stdout.write.bind(process.stdout);
realErr = process.stderr.write.bind(process.stderr);
process.env = resolved.env;
try {
process.chdir(opts.cwd ?? ROOT);
} catch {
// A caller cwd that does not exist would also fail a subprocess spawn.
}
process.stdout.write = captureWrite((s) => (stdout += s)) as typeof process.stdout.write;
process.stderr.write = captureWrite((s) => (stderr += s)) as typeof process.stderr.write;
let returncode: number;
try {
returncode = await main(args);
} catch (err) {
stderr += `${(err as Error)?.stack ?? String(err)}\n`;
returncode = 1;
}
return { stdout, stderr, returncode };
} finally {
if (realOut !== null) process.stdout.write = realOut;
if (realErr !== null) process.stderr.write = realErr;
if (savedEnv !== null) process.env = savedEnv;
if (savedCwd !== null) {
try {
process.chdir(savedCwd);
} catch {
/* restore best-effort */
}
}
if (cleanupDir !== null) rmSync(cleanupDir, { recursive: true, force: true });
inProcessRunActive = false;
}
}
export async function runCli(
args: ReadonlyArray<string>,
opts: RunCliOptions = {},
): Promise<RunResult> {
// Real stdin or an explicit isolation request needs a child process; every
// other command runs in-process for speed.
if (opts.subprocess === true || opts.stdin !== undefined) {
return runCliSubprocess(args, opts);
}
return runCliInProcess(args, opts);
}