Skip to content

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
17.3 KB
Raw Blame
/**
 * `discoverConfig` and the ONE failure it is allowed to absorb.
 *
 * The plugin config (`config.yaml`) is the twin of `Brain/_brain.yaml`, and
 * the same two conditions have to stay apart here:
 *
 *   - ABSENT - no config file at all. Every flag is off by documented
 *     default and every resolver answers with its default. This is the
 *     common case on a fresh install and must stay byte-identical.
 *   - PRESENT BUT UNREADABLE - a directory where the file should be, or a
 *     file that cannot be opened. The operator's settings exist and are
 *     NOT in force; answering with the defaults reverts every gate to
 *     `false` while the install looks exactly like one that never set a
 *     flag.
 *
 * There is no third "parses but is invalid" condition to test on this file:
 * `parseSimpleYaml` skips every line that is not `key: value` by design
 * (parity with the legacy Python parser), so it has no failure mode. A
 * malformed plugin config is only ever one of the two I/O conditions above,
 * and the lossy-parse test below pins that the fix did not quietly turn the
 * tolerant parser into a strict one.
 */

import { afterEach, beforeEach, describe, expect, setDefaultTimeout, test } from "bun:test";
import { chmodSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { dirname, join, resolve } from "node:path";
import { fileURLToPath } from "node:url";

import {
  ConfigReadError,
  discoverConfig,
  resolveDeviceId,
  resolveInstallationSecret,
  resolveSkillAutoAttach,
  resolveVault,
  setConfigValue,
} from "../../src/core/config.ts";
import { receiptShardPath } from "../../src/core/brain/decisions/receipts.ts";
import { claimShardPath } from "../../src/core/brain/truth/store.ts";
import { CHMOD_CANNOT_DENY, homeEnv } from "../helpers/platform.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 HOOKS_DIR = resolve(dirname(fileURLToPath(import.meta.url)), "..", "..", "hooks");

/** Env keys these tests must own outright, whatever the outer shell set. */
const OWNED_ENV = [
  "OPEN_SECOND_BRAIN_SKILL_AUTO_ATTACH",
  "VAULT_DIR",
  "OPEN_SECOND_BRAIN_CONFIG",
  "XDG_CONFIG_HOME",
  // The suite preload pins the device id to "" for deterministic log
  // shards; the identity tests below need the config path to be the
  // resolution source, so they own both identity overrides outright.
  "O2B_DEVICE_ID",
  "O2B_INSTALLATION_SECRET",
] as const;

let tmp: string;
const savedEnv: Record<string, string | undefined> = {};

beforeEach(() => {
  tmp = mkdtempSync(join(tmpdir(), "o2b-config-read-failure-"));
  for (const key of OWNED_ENV) {
    savedEnv[key] = process.env[key];
    delete process.env[key];
  }
});

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;
  }
});

/** A config an operator could plausibly have written. */
const VALID_CONFIG = `vault: "/srv/example-vault"\nskill_auto_attach: "true"\n`;

describe("discoverConfig: absent config", () => {
  test("a missing file in an existing directory reports absent, with no data", () => {
    const path = join(tmp, "config.yaml");
    const result = discoverConfig(path);
    expect(result.exists).toBe(false);
    expect(result.path).toBe(path);
    expect(result.data).toEqual({});
  });

  test("a missing parent directory reports absent too", () => {
    const path = join(tmp, "never", "created", "config.yaml");
    const result = discoverConfig(path);
    expect(result.exists).toBe(false);
    expect(result.path).toBe(path);
    expect(result.data).toEqual({});
  });
});

describe("discoverConfig: present but unreadable config", () => {
  test("a directory where the file should be raises, naming the path", () => {
    const path = join(tmp, "config.yaml");
    mkdirSync(path, { recursive: true });
    let caught: unknown;
    try {
      discoverConfig(path);
    } catch (err) {
      caught = err;
    }
    expect(caught).toBeInstanceOf(ConfigReadError);
    expect((caught as ConfigReadError).path).toBe(path);
    expect((caught as ConfigReadError).message).toContain(path);
  });

  // chmod cannot deny access on Windows or as root (tests/helpers/platform.ts).
  test.skipIf(CHMOD_CANNOT_DENY)(
    "a file that cannot be opened raises rather than reading as absent",
    () => {
      const path = join(tmp, "config.yaml");
      writeFileSync(path, VALID_CONFIG, "utf8");
      chmodSync(path, 0o000);
      try {
        let caught: unknown;
        try {
          discoverConfig(path);
        } catch (err) {
          caught = err;
        }
        expect(caught).toBeInstanceOf(ConfigReadError);
        expect((caught as ConfigReadError).path).toBe(path);
        expect((caught as ConfigReadError).message).toContain(path);
      } finally {
        chmodSync(path, 0o600);
      }
    },
  );

  /**
   * The condition an existence check cannot express. `existsSync` answers
   * `false` for EVERY stat failure, not only ENOENT, so a perfectly
   * readable config behind a directory that cannot be traversed reported as
   * absent - the operator's `vault:` and every gate in the file reverting
   * to its default while the install looked like one that never ran
   * `o2b init`. Only ENOENT on the path itself is an absence.
   */
  // chmod cannot deny access on Windows or as root (tests/helpers/platform.ts).
  test.skipIf(CHMOD_CANNOT_DENY)(
    "a config behind an untraversable directory raises, it is not absent",
    () => {
      const dir = join(tmp, "locked");
      mkdirSync(dir, { recursive: true });
      const path = join(dir, "config.yaml");
      writeFileSync(path, VALID_CONFIG, "utf8");
      chmodSync(dir, 0o000);
      try {
        let caught: unknown;
        try {
          discoverConfig(path);
        } catch (err) {
          caught = err;
        }
        expect(caught).toBeInstanceOf(ConfigReadError);
        expect((caught as ConfigReadError).path).toBe(path);
        expect((caught as ConfigReadError).message).toContain(path);
      } finally {
        chmodSync(dir, 0o755);
      }
    },
  );

  /**
   * Same reasoning at the gate: an untraversable parent must never resolve
   * a default-OFF flag to `false`, which is indistinguishable from the
   * operator never having set it.
   */
  // chmod cannot deny access on Windows or as root (tests/helpers/platform.ts).
  test.skipIf(CHMOD_CANNOT_DENY)(
    "a flag gate behind an untraversable directory raises rather than answering `off`",
    () => {
      const dir = join(tmp, "locked");
      mkdirSync(dir, { recursive: true });
      const path = join(dir, "config.yaml");
      writeFileSync(path, VALID_CONFIG, "utf8");
      chmodSync(dir, 0o000);
      try {
        expect(() => resolveSkillAutoAttach(path)).toThrow(ConfigReadError);
      } finally {
        chmodSync(dir, 0o755);
      }
    },
  );

  /**
   * A directory whose contents cannot be listed is still a directory in the
   * config file's place - the not-a-regular-file refusal, reached through
   * the stat rather than through a failed read.
   */
  test("an unreadable directory in the config file's place raises too", () => {
    const path = join(tmp, "config.yaml");
    mkdirSync(path, { recursive: true });
    chmodSync(path, 0o000);
    try {
      expect(() => discoverConfig(path)).toThrow(ConfigReadError);
    } finally {
      chmodSync(path, 0o755);
    }
  });

  /**
   * The opposite outcome, on the same surface: content this parser cannot
   * represent is not an unreadable config. Nested YAML and junk lines are
   * skipped exactly as before, so tightening the read did not tighten the
   * parse - an operator whose file has a comment block and an indented
   * section keeps the keys it can read.
   */
  test("content the flat parser cannot represent is still read, not raised", () => {
    const path = join(tmp, "config.yaml");
    writeFileSync(
      path,
      `# a comment\nvault: "/srv/example-vault"\nnested:\n  key: value\nno-colon-here\n`,
      "utf8",
    );
    const result = discoverConfig(path);
    expect(result.exists).toBe(true);
    expect(result.data["vault"]).toBe("/srv/example-vault");
  });
});

describe("call sites: an unreadable plugin config is surfaced, never read as `off`", () => {
  test("a flag gate on an absent config is off, exactly as before", () => {
    expect(resolveSkillAutoAttach(join(tmp, "config.yaml"))).toBe(false);
  });

  // chmod cannot deny access on Windows or as root (tests/helpers/platform.ts).
  test.skipIf(CHMOD_CANNOT_DENY)(
    "a flag gate on an unreadable config raises instead of answering `off`",
    () => {
      const path = join(tmp, "config.yaml");
      writeFileSync(path, VALID_CONFIG, "utf8");
      chmodSync(path, 0o000);
      try {
        expect(() => resolveSkillAutoAttach(path)).toThrow(ConfigReadError);
      } finally {
        chmodSync(path, 0o600);
      }
    },
  );

  /**
   * The env twin is the escape hatch that makes the raise survivable: an
   * operator whose config file broke can still drive every gate from the
   * environment, because the file is not opened when the env key is set.
   */
  test("the env twin still answers without opening an unreadable config", () => {
    const path = join(tmp, "config.yaml");
    writeFileSync(path, VALID_CONFIG, "utf8");
    chmodSync(path, 0o000);
    process.env["OPEN_SECOND_BRAIN_SKILL_AUTO_ATTACH"] = "true";
    try {
      expect(resolveSkillAutoAttach(path)).toBe(true);
    } finally {
      chmodSync(path, 0o600);
    }
  });

  test("resolveVault on an absent config is `no vault configured`", () => {
    expect(resolveVault(join(tmp, "config.yaml"), { cwd: tmp })).toBeNull();
  });

  // chmod cannot deny access on Windows or as root (tests/helpers/platform.ts).
  test.skipIf(CHMOD_CANNOT_DENY)(
    "resolveVault on an unreadable config raises instead of reporting no vault",
    () => {
      const path = join(tmp, "config.yaml");
      writeFileSync(path, VALID_CONFIG, "utf8");
      chmodSync(path, 0o000);
      try {
        expect(() => resolveVault(path, { cwd: tmp })).toThrow(ConfigReadError);
      } finally {
        chmodSync(path, 0o600);
      }
    },
  );

  /**
   * The write path is the one that made the collapse destructive: reading
   * the existing file as absent meant the merge had nothing to merge, so
   * persisting one key rewrote the operator's whole config down to that
   * single line.
   */
  // chmod cannot deny access on Windows or as root (tests/helpers/platform.ts).
  test.skipIf(CHMOD_CANNOT_DENY)(
    "setConfigValue raises rather than overwriting a config it could not read",
    () => {
      const path = join(tmp, "config.yaml");
      writeFileSync(path, VALID_CONFIG, "utf8");
      chmodSync(path, 0o400);
      let caught: unknown;
      try {
        // Readable-but-not-writable is not the condition under test; make the
        // read itself fail, which is what the old catch absorbed.
        chmodSync(path, 0o000);
        try {
          setConfigValue("agent_name", "someone", path);
        } catch (err) {
          caught = err;
        }
      } finally {
        chmodSync(path, 0o600);
      }
      expect(caught).toBeInstanceOf(ConfigReadError);
      expect(readFileSync(path, "utf8")).toBe(VALID_CONFIG);
    },
  );
});

/**
 * Identity resolution on a config that cannot be read.
 *
 * The decision this pins: it RAISES. `resolveDeviceId` and
 * `resolveInstallationSecret` generate-and-persist on a miss, and an
 * unreadable file is not a miss - proceeding would mint a fresh identity
 * and write it through `setConfigValue`, which merges onto what it read
 * and would therefore flatten the operator's config to a single line. A
 * fresh device id also silently re-shards this device's log; a fresh
 * installation secret silently changes every `vault://` reference agents
 * correlate by. Both are worse than a refusal that names the file.
 */
describe("identity resolution refuses rather than minting a new identity", () => {
  /** Config the resolvers would otherwise overwrite. */
  const IDENTITY_CONFIG = `device_id: "abc12345"\ninstallation_secret: "${"0".repeat(32)}"\n`;

  function brokenConfig(): string {
    const path = join(tmp, "config.yaml");
    writeFileSync(path, IDENTITY_CONFIG, "utf8");
    chmodSync(path, 0o000);
    return path;
  }

  // chmod cannot deny access on Windows or as root (tests/helpers/platform.ts).
  test.skipIf(CHMOD_CANNOT_DENY)("resolveDeviceId raises and persists nothing", () => {
    const path = brokenConfig();
    try {
      expect(() => resolveDeviceId(path)).toThrow(ConfigReadError);
    } finally {
      chmodSync(path, 0o600);
    }
    expect(readFileSync(path, "utf8")).toBe(IDENTITY_CONFIG);
  });

  // chmod cannot deny access on Windows or as root (tests/helpers/platform.ts).
  test.skipIf(CHMOD_CANNOT_DENY)("resolveInstallationSecret raises and persists nothing", () => {
    const path = brokenConfig();
    try {
      expect(() => resolveInstallationSecret(path)).toThrow(ConfigReadError);
    } finally {
      chmodSync(path, 0o600);
    }
    expect(readFileSync(path, "utf8")).toBe(IDENTITY_CONFIG);
  });

  // chmod cannot deny access on Windows or as root (tests/helpers/platform.ts).
  test.skipIf(CHMOD_CANNOT_DENY)(
    "the claim shard path raises rather than silently choosing the legacy file",
    () => {
      const path = brokenConfig();
      try {
        expect(() => claimShardPath(join(tmp, "vault"), path)).toThrow(ConfigReadError);
      } finally {
        chmodSync(path, 0o600);
      }
    },
  );

  // chmod cannot deny access on Windows or as root (tests/helpers/platform.ts).
  test.skipIf(CHMOD_CANNOT_DENY)(
    "the receipt shard path raises rather than silently choosing the legacy file",
    () => {
      const path = brokenConfig();
      try {
        expect(() => receiptShardPath(join(tmp, "vault"), path)).toThrow(ConfigReadError);
      } finally {
        chmodSync(path, 0o600);
      }
    },
  );

  /**
   * The env escape hatch survives the raise, exactly as it does for the
   * flag gates: an operator whose config broke can still name the device
   * id without the file being opened at all.
   */
  test("the device-id env override still answers without opening the file", () => {
    const path = brokenConfig();
    process.env["O2B_DEVICE_ID"] = "workstation";
    try {
      expect(resolveDeviceId(path)).toBe("workstation");
    } finally {
      chmodSync(path, 0o600);
    }
  });
});

/**
 * Hooks are the call sites with no channel of their own: every hook wraps
 * its body in a fail-open catch so a broken install can never take down a
 * session. The raise must therefore change NOTHING observable for them -
 * same exit code, same silence - which is also why the operator's channel
 * for this condition is the CLI, not the hook.
 */
describe("hooks stay fail-open on an unreadable plugin config", () => {
  interface RunResult {
    readonly stdout: string;
    readonly stderr: string;
    readonly exit: number;
  }

  async function run(argv: string[], payload: unknown, env: Record<string, string>) {
    const proc = Bun.spawn(argv, {
      stdin: "pipe",
      stdout: "pipe",
      stderr: "pipe",
      env: { PATH: process.env["PATH"] ?? "", ...homeEnv(tmp), ...env },
    });
    proc.stdin.write(JSON.stringify(payload));
    await proc.stdin.end();
    const stdout = await new Response(proc.stdout).text();
    const stderr = await new Response(proc.stderr).text();
    const exit = await proc.exited;
    return { stdout, stderr, exit } satisfies RunResult;
  }

  test("gap-agenda exits clean and emits nothing when the config cannot be read", async () => {
    const path = join(tmp, "config.yaml");
    writeFileSync(path, VALID_CONFIG, "utf8");
    chmodSync(path, 0o000);
    try {
      const result = await run(
        ["bun", "run", join(HOOKS_DIR, "gap-agenda.ts")],
        { hook_event_name: "SessionStart", session_id: "s1" },
        { OPEN_SECOND_BRAIN_CONFIG: path },
      );
      expect(result.exit).toBe(0);
      expect(result.stdout).toBe("");
    } finally {
      chmodSync(path, 0o600);
    }
  });

  /**
   * The opposite outcome for the test above, which would otherwise pass on
   * a build where nothing raises at all: the SAME resolver, on the SAME
   * broken config, outside a hook's fail-open catch. It exits non-zero and
   * names the file - so the hook's silence is the hook's contract, not an
   * absent raise.
   */
  // chmod cannot deny access on Windows or as root (tests/helpers/platform.ts).
  test.skipIf(CHMOD_CANNOT_DENY)(
    "the same gate outside the hook's catch exits non-zero, naming the file",
    async () => {
      const path = join(tmp, "config.yaml");
      writeFileSync(path, VALID_CONFIG, "utf8");
      chmodSync(path, 0o000);
      const configModule = resolve(
        dirname(fileURLToPath(import.meta.url)),
        "..",
        "..",
        "src",
        "core",
        "config.ts",
      );
      try {
        const result = await run(
          [
            "bun",
            "-e",
            `const m = await import(${JSON.stringify(configModule)});
m.resolveGapLoopEnabled(${JSON.stringify(path)});`,
          ],
          {},
          { OPEN_SECOND_BRAIN_CONFIG: path },
        );
        expect(result.exit).not.toBe(0);
        expect(result.stderr).toContain(path);
      } finally {
        chmodSync(path, 0o600);
      }
    },
  );
});