@ghilteras/opencode-agent-memory 0.5.2 → 1.2.0

package/README.md

@@ -24,7 +24,7 @@ Think of it as a searchable sidecar to `AGENTS.md`. OpenCode supports [rules](ht
 
 ## Requirements
 
-- [OpenCode](https://opencode.ai/) v1.0.115 or later
+- [OpenCode](https://opencode.ai/) **v2** — this version uses the OpenCode v2 plugin API and does **not** run on v1
 
 ## Installation
 
@@ -32,32 +32,33 @@ Add to your OpenCode config (`~/.config/opencode/opencode.json`):
 
 ```json
 {
-  "plugin": ["@ghilteras/opencode-agent-memory@0.5.2"]
+  "plugins": ["@ghilteras/opencode-agent-memory@1.1.0"]
 }
 ```
 
-OpenCode fetches unpinned plugins from npm on each startup; pinned versions are cached and require a manual version bump to update.
+Note OpenCode **v2** reads the `plugins` key (v1 used `plugin`). OpenCode fetches unpinned plugins from npm on each startup; pinned versions are cached and require a manual version bump to update.
 
 ## Journal
 
-The journal is **opt-in**. Enable it in `~/.config/opencode/agent-memory.json`:
+The journal is **on by default** — the three tools are registered with no configuration required.
+
+To turn it off, set `enabled: false` in `~/.config/opencode/agent-memory.json`:
 
 ```json
 {
   "journal": {
-    "enabled": true
+    "enabled": false
   }
 }
 ```
 
-The plugin does **not** regenerate `agent-memory.json` if it is deleted; its loss otherwise silently disables the journal, which is why the fault warning exists.
-
-- Intentional disable (`"enabled": false`) is silent by design and registers **no tools**.
-- A missing, unreadable, malformed, or schema-invalid config logs `[agent-memory] journal config <resolved path>: <reason>; journal tools will NOT be registered` and registers **no tools**.
+- An explicit disable (`"enabled": false`) is silent by design and registers **no tools**.
+- A config that exists but is unreadable, malformed, or schema-invalid **fails closed**: it logs `[agent-memory] journal config <resolved path>: <reason>; journal tools will NOT be registered` and registers **no tools**.
+- An **absent** config means the default: the tools register. (This changed in 1.0.0 — an absent config used to disable the journal.)
 
 ### Tools
 
-When the journal is enabled, the agent gets 3 tools:
+The agent gets 3 tools:
 
 | Tool | Description |
 |------|-------------|
@@ -119,6 +120,15 @@ By default the transformers.js model cache lives in the default location (`~/.ca
 }
 ```
 
+## Upgrading to 1.0.0
+
+**This release requires OpenCode v2.** The plugin was ported from the v1 plugin API to the v2 plugin API and will not load on v1. The config key is now `plugins` (v1 used `plugin`).
+
+Two behaviour changes:
+
+- **The journal tools are registered by default.** Previously you had to opt in through `agent-memory.json`; now an absent config means the tools are on, and you turn them off with `"enabled": false`.
+- **Storage is unchanged.** Existing entries under `~/.config/opencode/journal/` and their `.embedding` sidecars stay readable; nothing is migrated or rewritten.
+
 ## Upgrading from 0.4.x
 
 Memory blocks and their tools (`memory_list`, `memory_set`, `memory_replace`) are **removed**. Blocks are no longer read, written, or injected into the system prompt; the plugin ships only the journal.
@@ -127,9 +137,9 @@ Existing `~/.config/opencode/memory/` and `.opencode/memory/` directories are **
 
 ## Compatibility & Troubleshooting
 
-- **Requires OpenCode v1.0.115+.**
+- **Requires OpenCode v2.** This release uses the OpenCode v2 plugin API and does not run on v1.
 - **Restart after config changes.** Plugin config changes require a full OpenCode restart to take effect; editing the config file alone is not sufficient.
-- **Journal is opt-in.** You must explicitly enable it in `~/.config/opencode/agent-memory.json`; intentional disablement is silent, while a missing, unreadable, malformed, or schema-invalid config logs a warning and registers no tools.
+- **Journal is on by default.** Turn it off with `"enabled": false`; an explicit disable is silent, while a config that exists but is unreadable, malformed, or schema-invalid logs a warning and registers no tools (fail-closed).
 - **Local embeddings, no data leaves the machine.** Semantic search uses a locally cached transformers.js model; no external API calls are made for search or embedding.
 - **Known limitation (since 0.5.1): guidance-in-descriptions depends on an unverified premise.** 0.5.1 moved journal guidance from the injected system-prompt note into the three journal tool descriptions, so only agents allowed to call those tools should see it. That relies on opencode omitting a permission-denied tool from the definitions sent to the model. This is **unverified**: a `tool.definition` probe on the isolated instance fires before permission filtering, so it cannot confirm what the model actually receives. If the premise does not hold, an agent denied `journal_*` may still read the description text; `deny` still blocks execution, so there is no capability escalation and no data disclosure — the blast radius is the three tools' description strings.
 
@@ -146,3 +156,11 @@ Originally created by Joshua David Thomas and licensed under the MIT license. Ma
 opencode-agent-memory is not built by, or affiliated with, the OpenCode team.
 
 OpenCode is ©2025 Anomaly.
+# Journal diagnostics
+
+Run `bun run journal:doctor [config-dir]` to inspect flat journal Markdown files
+and their `.embedding` sidecars without repairing or changing them. The optional
+directory is the OpenCode state/config directory (the journal is read from its
+`journal/` subdirectory); without it, the default is `~/.config/opencode`.
+The command prints a deterministic JSON report and exits 0 for a complete scan
+without errors, 1 for validation errors, or 2 for an incomplete scan/root error.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ghilteras/opencode-agent-memory",
-  "version": "0.5.2",
+  "version": "1.2.0",
   "description": "Journal-only memory plugin for OpenCode: tagged, searchable, append-only journal with semantic search.",
   "author": "Angelo Pantano <ghilteras@protonmail.com>",
   "license": "MIT",
@@ -17,12 +17,15 @@
     "src"
   ],
   "scripts": {
-    "test": "bun test",
-    "typecheck": "tsc --noEmit"
+    "test": "bun run test:core && bun run test:plugin",
+    "test:core": "bun test src/test-suite.test.ts src/doctor.test.ts src/embeddings.test.ts src/tools.test.ts src/journal.test.ts",
+    "test:plugin": "HF_HUB_OFFLINE=1 TRANSFORMERS_OFFLINE=1 HOME=$(mktemp -d) bun test src/plugin.test.ts src/plugin-disabled.test.ts",
+    "typecheck": "tsc --noEmit",
+    "journal:doctor": "bun run src/journal-doctor.ts"
   },
   "dependencies": {
     "@huggingface/transformers": "^3.8.1",
-    "@opencode-ai/plugin": "^1.0.115",
+    "@opencode/plugin": "^2.0.18",
     "js-yaml": "^4.1.0",
     "zod": "^4.1.13"
   },

package/src/doctor.test.ts

@@ -0,0 +1,183 @@
+import { afterEach, expect, test } from "bun:test";
+import * as fs from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
+import { diagnoseJournal } from "./doctor";
+
+const roots: string[] = [];
+async function fixture() {
+  const root = await fs.mkdtemp(path.join(os.tmpdir(), "journal-doctor-"));
+  roots.push(root);
+  await fs.mkdir(path.join(root, "journal"));
+  return path.join(root, "journal");
+}
+async function entry(dir: string, name: string, yamlText?: string, sidecar?: string) {
+  await fs.writeFile(path.join(dir, `${name}.md`), yamlText === undefined ? "plain text" : `---\n${yamlText}\n---\nbody\n`);
+  if (sidecar !== undefined) await fs.writeFile(path.join(dir, `${name}.embedding`), sidecar);
+}
+afterEach(async () => { await Promise.all(roots.splice(0).map((root) => fs.rm(root, { recursive: true, force: true }))); });
+
+test("classifies frontmatter, created values, sidecars and multiple findings deterministically", async () => {
+  const dir = await fixture();
+  const valid = 'title: Good\ncreated: "2025-01-01T00:00:00Z"';
+  await entry(dir, "00-valid", valid, JSON.stringify({ v: 2, model: "wrong-model", dimension: 2, vector: [0.1, 0.2] }));
+  await entry(dir, "01-missing-title", "created: \"2025-01-01\"");
+  await entry(dir, "02-empty-title", 'title: ""');
+  await entry(dir, "03-wrong-title", "title: 42");
+  await entry(dir, "04-missing-created", "title: Present", "[1,2]");
+  await entry(dir, "05-date-only", "title: Present\ndate: \"2025-01-01\"");
+  await entry(dir, "06-invalid-created", 'title: Present\ncreated: "not a date"');
+  await entry(dir, "07-wrong-created", "title: Present\ncreated: 42");
+  await entry(dir, "08-yaml-timestamp", "title: Present\ncreated: 2025-01-01T00:00:00Z");
+  await entry(dir, "09-bad-yaml", "title: [broken");
+  await entry(dir, "10-no-frontmatter");
+  await entry(dir, "11-malformed-json", valid, "{");
+  await entry(dir, "12-vector-type", valid, '{"v":2,"model":"m","dimension":1,"vector":["x"]}');
+  await entry(dir, "13-empty-vector", valid, '{"v":2,"model":"m","dimension":0,"vector":[]}');
+  await entry(dir, "14-vector-dimension", valid, '{"v":2,"model":"m","dimension":3,"vector":[1,2]}');
+  await entry(dir, "15-legacy", valid, "[1,2]");
+  await entry(dir, "16-legacy-invalid", valid, '[1,"x"]');
+  await entry(dir, "17-missing-sidecar", valid);
+
+  const inventory = async () => Promise.all((await fs.readdir(dir)).sort().map(async (f) => [f, await fs.readFile(path.join(dir, f)), (await fs.stat(path.join(dir, f))).mtimeMs] as const));
+  const before = await inventory();
+  const report = await diagnoseJournal(path.dirname(dir));
+  expect(await diagnoseJournal(path.dirname(dir))).toEqual(report);
+  expect(report.counts.files).toBe(18);
+  const codes = (name: string) => report.findings.filter((f) => f.path.startsWith(name)).map((f) => f.code);
+  expect(codes("01-missing-title")).toContain("frontmatter_title_invalid");
+  expect(codes("02-empty-title")).toContain("frontmatter_title_invalid");
+  expect(codes("03-wrong-title")).toContain("frontmatter_title_invalid");
+  expect(codes("04-missing-created")).toContain("created_missing");
+  expect(codes("05-date-only")).toContain("created_missing");
+  expect(codes("06-invalid-created")).toContain("created_invalid");
+  expect(codes("07-wrong-created")).toContain("frontmatter_created_invalid");
+  expect(codes("08-yaml-timestamp")).toContain("frontmatter_created_invalid");
+  expect(codes("09-bad-yaml")).toContain("yaml_malformed");
+  expect(codes("10-no-frontmatter")).toContain("frontmatter_missing_or_malformed");
+  expect(codes("11-malformed-json")).toContain("embedding_json_malformed");
+  for (const name of ["12-vector-type", "13-empty-vector", "14-vector-dimension", "16-legacy-invalid"]) expect(codes(name)).toContain("embedding_invalid");
+  expect(codes("00-valid")).toContain("embedding_incompatible");
+  expect(codes("15-legacy")).toContain("embedding_model_unknown");
+  expect(codes("17-missing-sidecar")).toContain("embedding_missing");
+  expect(codes("04-missing-created")).toEqual(expect.arrayContaining(["created_missing", "embedding_model_unknown"]));
+  expect(report.findings).toEqual([...report.findings].sort((a, b) => a.path.localeCompare(b.path) || a.code.localeCompare(b.code) || a.severity.localeCompare(b.severity)));
+  expect(report.findings.some((f) => /broken|Good|Present|not a date/.test(JSON.stringify(f)))).toBe(false);
+  expect(await inventory()).toEqual(before);
+});
+
+test("empty, missing, and injected unreadable roots/files have explicit incomplete semantics", async () => {
+  const missing = await diagnoseJournal("/path/that/does/not/exist");
+  expect(missing.complete).toBe(false);
+  expect(missing.findings[0]?.code).toBe("root_unreadable");
+  const dir = await fixture();
+  expect((await diagnoseJournal(path.dirname(dir))).complete).toBe(true);
+  await entry(dir, "a", "title: A"); await entry(dir, "b", "title: B");
+  const failingRead = { ...fs, readFile: async (p: Parameters<typeof fs.readFile>[0], ...args: any[]) => {
+    if (String(p).endsWith("a.md")) throw new Error("injected");
+    return fs.readFile(p, ...(args as [any]));
+  } } as unknown as typeof fs;
+  const report = await diagnoseJournal(path.dirname(dir), failingRead);
+  expect(report.complete).toBe(false);
+  expect(report.findings.some((f) => f.path === "a.md" && f.code === "file_unreadable")).toBe(true);
+  expect(report.findings.some((f) => f.path === "b.md" && f.code === "created_missing")).toBe(true);
+});
+
+test("CLI emits exact bytes and exit codes for clean, warning, error, incomplete and bad invocation", async () => {
+  const dir = await fixture();
+  const cli = path.resolve(import.meta.dir, "journal-doctor.ts");
+  const invoke = (...args: string[]) => Bun.spawnSync([process.execPath, "run", cli, ...args], { stdout: "pipe", stderr: "pipe" });
+  const assertCli = (result: ReturnType<typeof invoke>, stdout: string, stderr: string, exitCode: number) =>
+    expect({ stdout: result.stdout.toString(), stderr: result.stderr.toString(), exitCode: result.exitCode }).toEqual({ stdout, stderr, exitCode });
+  assertCli(invoke(path.dirname(dir)), '{"complete":true,"counts":{"files":0,"errors":0,"warnings":0},"findings":[]}\n', "", 0);
+
+  await entry(dir, "warning", 'title: Warn\ncreated: "2025-01-01"');
+  assertCli(invoke(path.dirname(dir)), '{"complete":true,"counts":{"files":1,"errors":0,"warnings":1},"findings":[{"path":"warning.embedding","code":"embedding_missing","severity":"warning"}]}\n', "", 0);
+
+  await entry(dir, "invalid", "title: 12");
+  assertCli(invoke(path.dirname(dir)), '{"complete":true,"counts":{"files":2,"errors":1,"warnings":2},"findings":[{"path":"invalid.embedding","code":"embedding_missing","severity":"warning"},{"path":"invalid.md","code":"frontmatter_title_invalid","severity":"error"},{"path":"warning.embedding","code":"embedding_missing","severity":"warning"}]}\n', "", 1);
+
+  assertCli(invoke("/path/that/does/not/exist"), '{"complete":false,"counts":{"files":0,"errors":1,"warnings":0},"findings":[{"path":".","code":"root_unreadable","severity":"error"}]}\n', "", 2);
+  assertCli(invoke(path.dirname(dir), "extra"), "", "usage: bun run journal:doctor [config-dir]\n", 2);
+});
+
+test("inventories orphan and associated sidecars independently and emits stable full report", async () => {
+  const dir = await fixture();
+  const valid = 'title: Good\ncreated: "2025-01-01T00:00:00Z"';
+  await entry(dir, "A", valid);
+  await entry(dir, "a", valid, "{");
+  await fs.writeFile(path.join(dir, "_.embedding"), "{");
+  const expected = { complete: true, counts: { files: 2, errors: 2, warnings: 2 }, findings: [
+    { path: "A.embedding", code: "embedding_missing", severity: "warning" },
+    { path: "_.embedding", code: "embedding_json_malformed", severity: "error" },
+    { path: "_.embedding", code: "embedding_orphan", severity: "warning" },
+    { path: "a.embedding", code: "embedding_json_malformed", severity: "error" },
+  ] };
+  const report = await diagnoseJournal(path.dirname(dir));
+  expect(JSON.stringify(report)).toBe(JSON.stringify(expected));
+  const cli = path.resolve(import.meta.dir, "journal-doctor.ts");
+  const result = Bun.spawnSync([process.execPath, "run", cli, path.dirname(dir)], { stdout: "pipe", stderr: "pipe" });
+  expect({ stdout: result.stdout.toString(), stderr: result.stderr.toString(), exitCode: result.exitCode }).toEqual({ stdout: `${JSON.stringify(expected)}\n`, stderr: "", exitCode: 1 });
+});
+
+test("sidecar validation survives markdown read failure; listed sidecar disappearance is incomplete", async () => {
+  const dir = await fixture();
+  await entry(dir, "a", 'title: Good\ncreated: "2025-01-01T00:00:00Z"', "{");
+  const failingRead = { ...fs, readFile: async (p: Parameters<typeof fs.readFile>[0], ...args: any[]) => {
+    if (String(p).endsWith("a.md")) throw Object.assign(new Error("denied"), { code: "EACCES" });
+    return fs.readFile(p, ...(args as [any]));
+  } } as unknown as typeof fs;
+  const failed = await diagnoseJournal(path.dirname(dir), failingRead);
+  expect(failed.complete).toBe(false);
+  expect(failed.findings.map((f) => f.code)).toEqual(expect.arrayContaining(["file_unreadable", "embedding_json_malformed"]));
+
+  let removed = false;
+  const disappearing = { ...fs, readFile: async (p: Parameters<typeof fs.readFile>[0], ...args: any[]) => {
+    if (String(p).endsWith("a.embedding") && !removed) { removed = true; throw Object.assign(new Error("gone"), { code: "ENOENT" }); }
+    return fs.readFile(p, ...(args as [any]));
+  } } as unknown as typeof fs;
+  const gone = await diagnoseJournal(path.dirname(dir), disappearing);
+  expect(gone.complete).toBe(false);
+  expect(gone.findings.some((f) => f.path === "a.embedding" && f.code === "embedding_unreadable")).toBe(true);
+});
+
+test("diagnosis never initializes model pipeline or fetches, while warmup activates trap in child", async () => {
+  const dir = await fixture();
+  await entry(dir, "a", 'title: Good\ncreated: "2025-01-01T00:00:00Z"');
+  const childCode = `
+    import { mock } from "bun:test";
+    let pipelines = 0, fetches = 0;
+    const originalFetch = globalThis.fetch;
+    globalThis.fetch = async (...args) => { fetches++; throw new Error("FETCH_SENTINEL"); };
+    mock.module("@huggingface/transformers", () => ({ pipeline: async () => { pipelines++; throw new Error("PIPELINE_SENTINEL"); } }));
+    const { diagnoseJournal } = await import(${JSON.stringify(path.resolve(import.meta.dir, "doctor.ts"))});
+    const { warmupEmbedder } = await import(${JSON.stringify(path.resolve(import.meta.dir, "embeddings.ts"))});
+    await diagnoseJournal(${JSON.stringify(path.dirname(dir))});
+    if (pipelines !== 0 || fetches !== 0) throw new Error("diagnosis activated model/fetch trap");
+    try { await warmupEmbedder(); throw new Error("pipeline sentinel was not caught"); } catch (error) { if (!String(error).includes("PIPELINE_SENTINEL")) throw error; }
+    if (pipelines !== 1 || fetches !== 0) throw new Error("pipeline trap count mismatch");
+    globalThis.fetch = originalFetch;
+    console.log(JSON.stringify({ pipelines, fetches }));
+  `;
+  const result = Bun.spawnSync([process.execPath, "-e", childCode], { stdout: "pipe", stderr: "pipe" });
+  expect({ stdout: result.stdout.toString(), stderr: result.stderr.toString(), exitCode: result.exitCode }).toEqual({ stdout: '{"pipelines":1,"fetches":0}\n', stderr: "", exitCode: 0 });
+});
+
+test("only flat regular inventory files are read and each sidecar is read once", async () => {
+  const dir = await fixture();
+  await entry(dir, "a", 'title: Good\ncreated: "2025-01-01T00:00:00Z"', "[1]");
+  await fs.mkdir(path.join(dir, "nested"));
+  await fs.writeFile(path.join(dir, "nested", "hidden.md"), "bad");
+  await fs.writeFile(path.join(dir, "nested", "hidden.embedding"), "{");
+  await fs.writeFile(path.join(dir, "ignored.txt"), "bad");
+  await fs.symlink(path.join(dir, "a.md"), path.join(dir, "linked.md"));
+  const reads = new Map<string, number>();
+  const counting = { ...fs, readFile: async (p: Parameters<typeof fs.readFile>[0], ...args: any[]) => {
+    const name = path.basename(String(p)); reads.set(name, (reads.get(name) ?? 0) + 1);
+    return fs.readFile(p, ...(args as [any]));
+  } } as unknown as typeof fs;
+  const report = await diagnoseJournal(path.dirname(dir), counting);
+  expect(report.counts.files).toBe(1);
+  expect([...reads.entries()].sort()).toEqual([["a.embedding", 1], ["a.md", 1]]);
+  expect(report.findings.map((f) => f.path)).toEqual(["a.embedding", "a.embedding"]);
+});

package/src/doctor.ts

@@ -0,0 +1,87 @@
+import * as fs from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
+import * as yaml from "js-yaml";
+import { z } from "zod";
+import { EMBEDDING_DIMENSION, embeddingModelName } from "./embeddings";
+import { splitFrontmatter } from "./frontmatter";
+import { EntryFrontmatterSchema } from "./journal";
+
+export type JournalFinding = { path: string; code: string; severity: "error" | "warning" };
+export type JournalDiagnosticReport = {
+  complete: boolean;
+  counts: { files: number; errors: number; warnings: number };
+  findings: JournalFinding[];
+};
+type FileSystem = Pick<typeof fs, "readdir" | "readFile" | "stat">;
+
+export async function diagnoseJournal(configDir?: string, fileSystem: FileSystem = fs): Promise<JournalDiagnosticReport> {
+  const root = path.resolve(configDir ?? path.join(os.homedir(), ".config", "opencode"), "journal");
+  const findings: JournalFinding[] = [];
+  let complete = true;
+  const add = (file: string, code: string, severity: JournalFinding["severity"]) => findings.push({ path: file, code, severity });
+  let entries: import("node:fs").Dirent[];
+  try { entries = await fileSystem.readdir(root, { withFileTypes: true }); }
+  catch { add(".", "root_unreadable", "error"); complete = false; entries = []; }
+
+  const inventory = entries.filter((entry) => entry.isFile() && (entry.name.endsWith(".md") || entry.name.endsWith(".embedding"))).map((entry) => entry.name).sort((a, b) => a < b ? -1 : a > b ? 1 : 0);
+  const files = inventory.filter((name) => name.endsWith(".md"));
+  const sidecars = inventory.filter((name) => name.endsWith(".embedding"));
+  const sidecarSet = new Set(sidecars);
+  for (const name of files) {
+    const relative = name;
+    let raw: string | undefined;
+    try { raw = await fileSystem.readFile(path.join(root, name), "utf8"); }
+    catch { add(relative, "file_unreadable", "error"); complete = false; }
+    if (raw !== undefined) {
+      const { frontmatterText } = splitFrontmatter(raw);
+      if (frontmatterText === undefined) add(relative, "frontmatter_missing_or_malformed", "error");
+      else {
+        let value: unknown;
+        try { value = yaml.load(frontmatterText); }
+        catch { add(relative, "yaml_malformed", "error"); value = undefined; }
+        {
+          const parsed = EntryFrontmatterSchema.safeParse(value);
+          if (!parsed.success) {
+            const fields = [...new Set(parsed.error.issues.map((issue) => String(issue.path[0] ?? "document")))].sort((a, b) => a < b ? -1 : a > b ? 1 : 0);
+            for (const field of fields) add(relative, `frontmatter_${field}_invalid`, "error");
+          } else {
+            if (parsed.data.created === undefined) add(relative, "created_missing", "warning");
+            else if (!Number.isFinite(new Date(parsed.data.created).getTime())) add(relative, "created_invalid", "error");
+          }
+        }
+      }
+    }
+  }
+
+  for (const sidecar of sidecars) {
+    const associatedMarkdown = `${sidecar.slice(0, -".embedding".length)}.md`;
+    if (!files.includes(associatedMarkdown)) add(sidecar, "embedding_orphan", "warning");
+    try {
+      const content = await fileSystem.readFile(path.join(root, sidecar), "utf8");
+      let value: unknown;
+      try { value = JSON.parse(content); } catch { add(sidecar, "embedding_json_malformed", "error"); continue; }
+      let vector: unknown; let dimension: unknown; let model: unknown; let legacy = false;
+      if (Array.isArray(value)) { vector = value; dimension = value.length; legacy = true; }
+      else if (value && typeof value === "object") {
+        const envelope = z.object({ v: z.literal(2), model: z.string(), dimension: z.number().int().positive(), vector: z.array(z.number().finite()).min(1) }).safeParse(value);
+        if (!envelope.success) { add(sidecar, "embedding_invalid", "error"); continue; }
+        ({ vector, dimension, model } = envelope.data);
+      } else { add(sidecar, "embedding_invalid", "error"); continue; }
+      if (!Array.isArray(vector) || vector.length === 0 || !vector.every((n) => typeof n === "number" && Number.isFinite(n)) || vector.length !== dimension) {
+        add(sidecar, "embedding_invalid", "error"); continue;
+      }
+      if (legacy) add(sidecar, "embedding_model_unknown", "warning");
+      if (vector.length !== EMBEDDING_DIMENSION || (!legacy && model !== embeddingModelName())) add(sidecar, "embedding_incompatible", "warning");
+    } catch (error) {
+      add(sidecar, "embedding_unreadable", "error"); complete = false;
+    }
+  }
+  for (const name of files) {
+    const expectedSidecar = `${name.slice(0, -".md".length)}.embedding`;
+    if (!sidecarSet.has(expectedSidecar)) add(expectedSidecar, "embedding_missing", "warning");
+  }
+  const compare = (a: string, b: string) => a < b ? -1 : a > b ? 1 : 0;
+  findings.sort((a, b) => compare(a.path, b.path) || compare(a.code, b.code) || compare(a.severity, b.severity));
+  return { complete, counts: { files: files.length, errors: findings.filter((f) => f.severity === "error").length, warnings: findings.filter((f) => f.severity === "warning").length }, findings };
+}

package/src/journal-doctor.ts

@@ -0,0 +1,11 @@
+import { diagnoseJournal } from "./doctor";
+
+const args = process.argv.slice(2);
+if (args.length > 1 || args.some((arg) => arg.startsWith("-"))) {
+  console.error("usage: bun run journal:doctor [config-dir]");
+  process.exitCode = 2;
+} else {
+  const report = await diagnoseJournal(args[0]);
+  console.log(JSON.stringify(report));
+  process.exitCode = !report.complete ? 2 : report.counts.errors > 0 ? 1 : 0;
+}

package/src/journal.test.ts

@@ -1,11 +1,13 @@
-import { afterEach, describe, expect, mock, test } from "bun:test";
+import { afterEach, beforeAll, describe, expect, mock, test } from "bun:test";
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
+import * as realEmbeddings from "./embeddings";
 
-import { createJournalStore, loadConfig } from "./journal";
-
-// Mock the embeddings module to avoid downloading a real model in tests
+// Mock the embeddings module to avoid downloading a real model in tests.
+// Spread the real module so every export not overridden here keeps its real
+// value regardless of test-file discovery order.
 mock.module("./embeddings", () => ({
+  ...realEmbeddings,
   generateEmbedding: async (text: string) => {
     // Deterministic fake embedding based on text content
     const hash = Array.from(text).reduce(
@@ -40,6 +42,16 @@ async function mkTmpDir(): Promise<string> {
   return fs.mkdtemp(path.join("/tmp/", "opencode-journal-"));
 }
 
+// Bind the journal module AFTER the embeddings mock registration (above) via
+// dynamic import, so the store uses the fake embeddings regardless of bun's
+// module-mock rewiring semantics; a static import would be hoisted above it.
+let createJournalStore!: (typeof import("./journal"))["createJournalStore"];
+let loadConfig!: (typeof import("./journal"))["loadConfig"];
+
+beforeAll(async () => {
+  ({ createJournalStore, loadConfig } = await import("./journal"));
+});
+
 describe("loadConfig", () => {
   test("classifies a missing file and returns an empty config", async () => {
     const dir = await mkTmpDir();
@@ -75,6 +87,14 @@ describe("loadConfig", () => {
     expect(loaded.config).toEqual({});
   });
 
+  test("rejects an unrecognized journal key instead of silently enabling", async () => {
+    const dir = await mkTmpDir();
+    await fs.writeFile(path.join(dir, "agent-memory.json"), JSON.stringify({ journal: { enabled_: false } }));
+    const loaded = await loadConfig(dir);
+    expect(loaded.status).toBe("invalid");
+    expect(loaded.config).toEqual({});
+  });
+
   test("classifies valid disabled config without changing it", async () => {
     const dir = await mkTmpDir();
     await fs.writeFile(
@@ -513,8 +533,9 @@ describe("journal store", () => {
       body: "unique-sidecar-deleted-content",
     });
 
-    // First search: caches the entry + sidecar fingerprint.
-    const r1 = await store.search({ text: "unique-sidecar-deleted-content" });
+    // Warm the cache chronologically (loads and caches the sidecar
+    // fingerprint) without depending on a synthetic semantic score.
+    const r1 = await store.search({});
     expect(r1.entries.some((e) => e.title === "Sidecar deleted entry")).toBe(true);
 
     // Delete the sidecar file.

package/src/journal.ts

@@ -16,10 +16,10 @@ const TagSchema = z.looseObject({
 const ConfigSchema = z.looseObject({
   cacheDir: z.string().optional(),
   journal: z
-    .looseObject({
+    .object({
       enabled: z.boolean().optional(),
       tags: z.array(TagSchema).optional(),
-    })
+    }).strict()
     .optional(),
 });
 
@@ -98,7 +98,7 @@ export type JournalTag = {
   description: string;
 };
 
-const EntryFrontmatterSchema = z.looseObject({
+export const EntryFrontmatterSchema = z.looseObject({
   title: z.string().min(1),
   project: z.string().optional(),
   model: z.string().optional(),

package/src/plugin-disabled.test.ts

@@ -1,70 +1,39 @@
-import { describe, expect, mock, test } from "bun:test";
+import { expect, mock, test } from "bun:test";
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import * as realEmbeddings from "./embeddings";
 
-// Mock journal module with journal DISABLED — the control path.
-mock.module("./journal", () => ({
-  loadConfig: async () => ({
-    config: { journal: { enabled: false } },
-    status: "ok",
-    configPath: "/tmp/test-plugin-disabled/agent-memory.json",
-  }),
-  createJournalStore: () => ({}),
-}));
+if (process.env.HOME === undefined || !process.env.HOME.startsWith("/tmp/")) {
+  throw new Error("plugin tests require HOME pointed at a /tmp fixture directory; run via `bun run test:plugin`");
+}
+
+const configDir = path.join(process.env.HOME, ".config", "opencode");
 
-// Mock embeddings to avoid model download
 mock.module("./embeddings", () => ({
+  ...realEmbeddings,
+  generateEmbedding: async () => Array.from({ length: 384 }, (_, i) => Math.sin(i) * 0.5),
   warmupEmbedder: async () => {},
 }));
 
-import { MemoryPlugin } from "./plugin";
-import type { PluginInput } from "@opencode-ai/plugin";
-
-const stubInput = { directory: "/tmp/test-plugin-disabled" } as unknown as PluginInput;
-
-describe("plugin disabled path", () => {
-  test("registers zero tools when journal is disabled", async () => {
-    const plugin = await MemoryPlugin(stubInput);
-    // tool should be undefined or an empty object
-    if (plugin.tool) {
-      expect(Object.keys(plugin.tool)).toHaveLength(0);
-    } else {
-      expect(plugin.tool).toBeUndefined();
-    }
-  });
-
-  test("produces no guidance text when disabled", async () => {
-    const plugin = await MemoryPlugin(stubInput);
-    // There should be no system transform hook injecting guidance
-    expect(plugin["experimental.chat.system.transform"]).toBeUndefined();
-    // Tool definitions (if any exist as empty object) must not contain
-    // any description with journal guidance keywords
-    if (plugin.tool) {
-      for (const def of Object.values(plugin.tool)) {
-        const desc = (def as { description?: string }).description ?? "";
-        expect(desc).not.toMatch(/append-only|journal|search.*entry/i);
-      }
-    }
-  });
-
-  test("chat.message hook is still present when disabled", async () => {
-    const plugin = await MemoryPlugin(stubInput);
-    // The chat.message hook updates model/provider context — it should
-    // still be present even when journal is disabled.
-    expect(plugin["chat.message"]).toBeDefined();
-    expect(typeof plugin["chat.message"]).toBe("function");
-  });
-
-  test("does not warn for an intentional disabled configuration", async () => {
-    const originalWarn = console.warn;
-    let warningCount = 0;
-    console.warn = () => {
-      warningCount += 1;
-    };
-
-    try {
-      await MemoryPlugin(stubInput);
-      expect(warningCount).toBe(0);
-    } finally {
-      console.warn = originalWarn;
-    }
-  });
+import plugin from "./plugin";
+
+test("explicit opt-out registers no tools and emits no warning", async () => {
+  await fs.mkdir(configDir, { recursive: true });
+  await fs.writeFile(path.join(configDir, "agent-memory.json"), JSON.stringify({ journal: { enabled: false } }), "utf-8");
+  const definitions: unknown[] = [];
+  const warn = console.warn;
+  let warnings = 0;
+  console.warn = () => { warnings++; };
+  try {
+    await plugin.setup({
+      location: { directory: "/tmp" },
+      session: { hook: async () => {} },
+      tool: { transform: async (callback: (editor: { add: (tool: unknown) => void; list: () => unknown[] }) => void) => callback({ add: (tool) => definitions.push(tool), list: () => [] }) },
+    } as any);
+    expect(definitions).toEqual([]);
+    expect(warnings).toBe(0);
+  } finally {
+    console.warn = warn;
+    await fs.rm(configDir, { recursive: true, force: true });
+  }
 });