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
/**
* Ctrl-C, and the four operations it cannot reach.
*
* The branch wired `onInterrupt()` into six verbs and claimed all six were
* interruptible. Four of them - dream, bridges, clusters, architect - run
* fully synchronously, and a JavaScript signal handler is dispatched from
* the event loop, so it cannot run while they do. Registering the listener
* anyway made those four STRICTLY worse: the listener suppresses Node's
* default termination, so the first keystroke stopped killing the process
* and started doing nothing at all.
*
* These tests pin the three rules that replaced the claim.
*
* 1. A handle may only be opened for an operation that yields to the
* event loop. Asking for one for an operation that does not is a
* defect reported by name, not a handle that quietly does nothing.
* 2. A verb whose operation cannot observe the signal registers no
* listener at all, so the keystroke keeps its default meaning.
* 3. An interrupt that arrived and that no operation acted on still ends
* the run. A verb cannot return 0 for a pass the operator stopped.
*
* Rules 3 and the platform fact underneath all of this are exercised in
* child processes: they turn on real signal delivery and on real process
* termination, neither of which can be faked in-process, and neither of
* which may be aimed at the test runner itself.
*/
import { describe, expect, setDefaultTimeout, test } from "bun:test";
import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { join, resolve } from "node:path";
import { bootstrapBrain } from "../../src/core/brain/init.ts";
import { interruptIsObservable, onInterrupt } from "../../src/cli/interrupt.ts";
import { OPERATION, type Operation } from "../../src/core/brain/safeguard.ts";
import { atomicWriteFileSync } from "../../src/core/fs-atomic.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 SRC = resolve(import.meta.dir, "..", "..", "src");
interface DriverResult {
readonly stdout: string;
readonly stderr: string;
readonly code: number | null;
readonly signal: string | null;
}
/**
* Run `body` as its own process and report how it ended.
*
* A child rather than the runner because every property here is about a
* real SIGINT: delivered by the kernel, dispatched by the receiving
* process's own event loop, and - in the cases that matter - killing the
* process it reaches. A test that aimed any of that at the runner would
* take the suite with it.
*/
async function runDriver(body: string): Promise<DriverResult> {
const dir = mkdtempSync(join(tmpdir(), "o2b-interrupt-driver-"));
try {
const file = join(dir, "driver.ts");
writeFileSync(file, body, "utf8");
const proc = Bun.spawn(["bun", "run", file], {
stdout: "pipe",
stderr: "pipe",
// Bun hands a child without `env` the environment this process STARTED
// with, not the live `process.env`: pass it so the child sees the
// throwaway config tests/setup.ts installs, not the operator's real one.
env: { ...process.env },
});
const [stdout, stderr] = await Promise.all([
new Response(proc.stdout).text(),
new Response(proc.stderr).text(),
]);
await proc.exited;
return {
stdout,
stderr,
code: proc.exitCode,
signal: proc.signalCode == null ? null : String(proc.signalCode),
};
} finally {
rmSync(dir, { recursive: true, force: true });
}
}
describe("the platform fact the rules rest on", () => {
// Needs a real POSIX SIGINT delivered by `kill -INT`; Windows has no such signal delivery.
test.skipIf(process.platform === "win32")(
"a delivered SIGINT is invisible to a fully synchronous checkpoint loop",
async () => {
// `dreamRun`, `detectCommunitiesRun`, `discoverBridgesRun` and
// `generateRun` are all declared `function`, not `async`, and contain
// no `await`. This drives production `onInterrupt` and production
// `createSafeguard` through exactly that shape, with a real signal
// pending for most of it, and records what the checkpoint saw.
const result = await runDriver(`
import { onInterrupt } from ${JSON.stringify(join(SRC, "cli", "interrupt.ts"))};
import { createSafeguard, SafeguardAbortError, OPERATION } from ${JSON.stringify(join(SRC, "core", "brain", "safeguard.ts"))};
const interrupt = onInterrupt(OPERATION.reindex);
const safeguard = createSafeguard({ operation: "dream", signal: interrupt.signal });
Bun.spawn(["bash", "-c", \`sleep 0.3; kill -INT \${process.pid}\`]);
let checkpoints = 0;
let stoppedByCtrlC = false;
const start = Date.now();
try {
while (Date.now() - start < 1500) { safeguard.checkpoint(); checkpoints++; }
} catch (e) { stoppedByCtrlC = e instanceof SafeguardAbortError; }
const duringRun = interrupt.received();
await new Promise((r) => setTimeout(r, 50));
console.log(JSON.stringify({
checkpoints, stoppedByCtrlC, duringRun, afterOneEventLoopTurn: interrupt.received(),
}));
interrupt.acknowledge();
interrupt.release();
`);
const seen = JSON.parse(result.stdout.trim()) as Record<string, unknown>;
// Millions of checkpoints, every one of them past the moment the key
// was pressed, and not one of them saw it.
expect(seen["checkpoints"]).toBeGreaterThan(100_000);
expect(seen["stoppedByCtrlC"]).toBe(false);
expect(seen["duringRun"]).toBeNull();
// And it was never in doubt that the signal arrived: one turn of the
// event loop later, it is there.
expect(seen["afterOneEventLoopTurn"]).toBe("SIGINT");
},
30_000,
);
});
describe("a handle is opened only where the operation can observe it", () => {
const SYNCHRONOUS: Operation[] = [
OPERATION.dream,
OPERATION.bridges,
OPERATION.clusters,
OPERATION.architect,
];
test.each(SYNCHRONOUS)("%s cannot observe an interrupt, and says so", (operation) => {
expect(interruptIsObservable(operation)).toBe(false);
// Not a no-op handle: a handle that installs nothing would make the
// wrong call site look like the right one.
expect(() => onInterrupt(operation)).toThrow(
new RegExp(`${operation}[\\s\\S]*runs to completion without yielding`),
);
});
const ASYNCHRONOUS: Operation[] = [OPERATION.reindex, OPERATION.maintenance];
test.each(ASYNCHRONOUS)("%s yields to the event loop, so it may hold a handle", (operation) => {
expect(interruptIsObservable(operation)).toBe(true);
const handle = onInterrupt(operation);
try {
expect(handle.signal.aborted).toBe(false);
expect(handle.received()).toBeNull();
} finally {
handle.release();
}
});
test("every operation in the vocabulary has an answer", () => {
for (const operation of Object.values(OPERATION)) {
expect(typeof interruptIsObservable(operation)).toBe("boolean");
}
});
});
describe("a verb that cannot observe the signal leaves it alone", () => {
/**
* Registering a SIGINT listener suppresses the default terminate for as
* long as it is registered. So for the four synchronous operations the
* observable property is not "the handle works" - it cannot - it is
* that no listener is installed, which is what keeps the keystroke
* lethal. Counting after the run would see nothing either way, because
* `release()` removes what it added; the registration itself is what
* has to be watched.
*/
async function signalListenersRegisteredDuring(
args: ReadonlyArray<string>,
env: Record<string, string>,
): Promise<string[]> {
const registered: string[] = [];
const realOnce = process.once.bind(process);
const spy = ((event: string, listener: (...a: unknown[]) => void) => {
if (event === "SIGINT" || event === "SIGTERM") registered.push(event);
return realOnce(event as never, listener as never);
}) as typeof process.once;
process.once = spy;
try {
await runCli(args, { env });
} finally {
process.once = realOnce;
}
return registered;
}
test("`brain dream` registers no signal listener", async () => {
const vault = mkdtempSync(join(tmpdir(), "o2b-interrupt-vault-"));
const cfgHome = mkdtempSync(join(tmpdir(), "o2b-interrupt-cfg-"));
const configPath = join(cfgHome, "config.yaml");
try {
atomicWriteFileSync(configPath, `vault: ${vault}\n`);
bootstrapBrain(vault, { configPath });
const registered = await signalListenersRegisteredDuring(["brain", "dream", "--dry-run"], {
OPEN_SECOND_BRAIN_CONFIG: configPath,
});
expect(registered).toEqual([]);
} finally {
rmSync(vault, { recursive: true, force: true });
rmSync(cfgHome, { recursive: true, force: true });
}
}, 60_000);
});
describe("an interrupt nobody acted on still ends the run", () => {
// Needs a real POSIX SIGINT delivered by `kill -INT`; Windows has no such signal delivery.
test.skipIf(process.platform === "win32")(
"release re-raises a signal the operation never observed",
async () => {
// The window every one of the six verbs leaves open: `Store.open`, a
// proposal write, a report render - work inside the handle's lifetime
// that never consults the signal. Before this rule the controller
// aborted, nobody read it, and the verb returned 0.
const result = await runDriver(`
import { onInterrupt } from ${JSON.stringify(join(SRC, "cli", "interrupt.ts"))};
import { OPERATION } from ${JSON.stringify(join(SRC, "core", "brain", "safeguard.ts"))};
const interrupt = onInterrupt(OPERATION.reindex);
try {
Bun.spawn(["bash", "-c", \`sleep 0.2; kill -INT \${process.pid}\`]);
await new Promise((r) => setTimeout(r, 600));
console.log("the operation finished without ever reading the signal");
} finally {
interrupt.release();
}
console.log("UNREACHABLE: the verb returned normally");
process.exit(0);
`);
expect(result.stdout).toContain("without ever reading the signal");
expect(result.stdout).not.toContain("UNREACHABLE");
expect(result.stderr).toContain("interrupted");
// The keystroke's own code, so a shell and a parent process read it
// the way they read any other Ctrl-C. Asserted as the code rather
// than as `signalCode`: Bun's default SIGINT disposition surfaces to
// a parent as `exitCode: 130, signalCode: null` where a re-raise under
// Node's would surface as the signal. What must hold is the number a
// caller gates on, and that it is not 0.
expect(result.code).toBe(130);
},
30_000,
);
// Needs a real POSIX SIGINT delivered by `kill -INT`; Windows has no such signal delivery.
test.skipIf(process.platform === "win32")(
"an acknowledged interrupt lets the verb report its own exit code",
async () => {
const result = await runDriver(`
import { onInterrupt, reportInterrupted, EXIT_INTERRUPTED } from ${JSON.stringify(join(SRC, "cli", "interrupt.ts"))};
import { OPERATION, SafeguardAbortError } from ${JSON.stringify(join(SRC, "core", "brain", "safeguard.ts"))};
const interrupt = onInterrupt(OPERATION.reindex);
let code;
try {
Bun.spawn(["bash", "-c", \`sleep 0.2; kill -INT \${process.pid}\`]);
await new Promise((r) => setTimeout(r, 600));
// What the real catch arm does when the operation stopped at a
// checkpoint of its own.
code = reportInterrupted(interrupt, new SafeguardAbortError("reindex"), false);
} finally {
interrupt.release();
}
console.log("verb returned " + code);
process.exit(code);
`);
// Reported, not re-raised: the verb's own answer stands, and the line
// after `reportInterrupted` still runs - which is the whole difference
// from the unacknowledged case above.
expect(result.stdout).toContain("verb returned 130");
expect(result.stderr).not.toContain("stopping now");
expect(result.code).toBe(130);
},
30_000,
);
test("a run nobody interrupted releases silently and exits 0", async () => {
const result = await runDriver(`
import { onInterrupt } from ${JSON.stringify(join(SRC, "cli", "interrupt.ts"))};
import { OPERATION } from ${JSON.stringify(join(SRC, "core", "brain", "safeguard.ts"))};
const interrupt = onInterrupt(OPERATION.reindex);
try { await new Promise((r) => setTimeout(r, 20)); } finally { interrupt.release(); }
console.log("clean");
process.exit(0);
`);
expect(result.stdout).toContain("clean");
expect(result.stderr).toBe("");
expect(result.code).toBe(0);
}, 30_000);
});