Self-hosted MCP server + dashboard giving Claude Code, Cursor & Hermes agents shared long-term memory over a git-backed markdown vault. Agent-native, Obsidian-compatible second brain — markdown RAG, no vector DB.
TypeScript agent-memoryai-agentsanthropicclaude-codecursorgitknowledge-baseknowledge-graphllmmarkdownmcpmcp-servermodel-context-protocolnote-takingobsidianpkmragsecond-brainself-hostedzettelkasten
fix: brain_append silently discarded its payload and reported ok:true (#10)
Ronalds Palacis5dc524c04ec8
diff --git a/app/api/mcp/route.ts b/app/api/mcp/route.tsindex ef0021e..10b789f 100644--- a/app/api/mcp/route.ts+++ b/app/api/mcp/route.ts@@ -5,6 +5,7 @@ import { oauthEnabled, verifyAccessToken, wwwAuthenticate } from "@/lib/oauth";import { withActor } from "@/lib/actor";import { VERSION } from "@/lib/version";import { TOOL_MAP, visibleTools } from "@/lib/mcp/tools";+import { callTool } from "@/lib/mcp/call";export const dynamic = "force-dynamic";@@ -62,7 +63,9 @@ async function handleMessage(msg: Json, caller: Caller): Promise<Json | null> {}try {// Stamp every write this call causes with the caller's name, for the git audit trail.- const out = await withActor(caller.name, () => tool.handler(params?.arguments ?? {}));+ // callTool validates `arguments` against the tool's inputSchema first — a malformed call+ // must surface as an error, never as a successful no-op write.+ const out = await withActor(caller.name, () => callTool(tool.name, params?.arguments ?? {}));const text = typeof out === "string" ? out : JSON.stringify(out, null, 2);return rpc(id, { content: [{ type: "text", text }] });} catch (e) {diff --git a/lib/agent.ts b/lib/agent.tsindex 6c7eec3..0186765 100644--- a/lib/agent.ts+++ b/lib/agent.ts@@ -2,6 +2,7 @@ import Anthropic from "@anthropic-ai/sdk";import { DEFAULT_CURATOR_MODEL, SUPPORTED_MODEL_IDS } from "@/lib/models";import { anthropicApiKey } from "@/lib/settings";import { TOOLS, type Tool } from "@/lib/mcp/tools";+import { validateArgs } from "@/lib/mcp/call";import { readVaultFile, vaultConventions } from "@/lib/vault/store";import { normalizeNotePath, guardOverwrite } from "@/lib/vault/write";import { withActor } from "@/lib/actor";@@ -168,6 +169,13 @@ export async function* agentStream(opts: AgentOpts): AsyncGenerator<AgentEvent>const blocked = guardOverwrite(name, target, (p) => readPaths.has(p));if (blocked) return { error: blocked };+ // Validate against the tool's inputSchema first — a model driving this loop mixes up+ // `text`/`content`/`body` exactly like a model driving MCP, and an unvalidated call there+ // wrote a blank line and reported success. Returning the message (rather than throwing) keeps+ // the loop alive so the model can correct its own call on the next turn.+ const problem = validateArgs(tool, input);+ if (problem) return { error: problem };+const out = await withActor(opts.actor ?? "curator", () => tool.handler(input));if (name === "brain_read" && target) readPaths.add(target);diff --git a/lib/git.test.ts b/lib/git.test.tsnew file mode 100644index 0000000..c257bf7--- /dev/null+++ b/lib/git.test.ts@@ -0,0 +1,267 @@+import { afterAll, beforeAll, describe, expect, test } from "bun:test";+import fs from "node:fs";+import path from "node:path";+import { simpleGit } from "simple-git";++/**+ * The vault-sync durability tests.+ *+ * Two defects shipped inside the 2026-07-15 "serialize git-sync" fix, both of which the vault's+ * own history shows running in production:+ *+ * 1. `withGitLock` returned `undefined` for "the lock was held", but its callback was typed+ * `Promise<void>` and so also resolved to `undefined`. Every successful sync looked like a+ * skip, so `runSync` re-queued its reasons and rescheduled itself forever — `pending` never+ * drained. Commit subjects on 2026-08-06 read `1 change(s)` → `2` → `3` → `4` → `5`, each+ * repeating every earlier reason, and a git subprocess pair ran every 2.5s indefinitely.+ *+ * 2. Both pull paths used `git pull --rebase --autostash`. Autostash reverts the working tree+ * to HEAD for the duration of the rebase and restores it after — and when the restore fails+ * git says so on STDOUT and still exits 0. The notes end up reverted with their content in a+ * stash nobody reads. Untracked files (a brand-new note) are never stashed, which is why+ * creating a note survived what modifying one did not.+ */++const LAB = path.join(process.env.ENGRAM_DATA_DIR!, "gitlab");+const REMOTE = path.join(LAB, "remote.git");+const REPO_ID = "sync-test";+const VAULT = path.join(process.env.ENGRAM_DATA_DIR!, "vaults", REPO_ID);+const SEED = path.join(LAB, "seed");+const NOTE = "clients/kolumbi/delivery.md";++const V0 = `---+title: Delivery+updated: '2026-07-14'+---++# Delivery++## Log++- **2026-07-20** — Phase 3 content build completed.+`;++const vaultGit = () => simpleGit(VAULT);+const onDisk = () => fs.readFileSync(path.join(VAULT, NOTE), "utf8");++/**+ * Every branch name here is pinned explicitly.+ *+ * The fixture used to let the working branch come from the host's `init.defaultBranch` while+ * pushing to `refs/heads/main`. On a machine defaulting to `main` that is silently consistent; on+ * one defaulting to `master` — a GitHub runner — the seed clone sits on `master` tracking+ * `origin/main`, and `git push` under the default `push.default=simple` refuses:+ * "The upstream branch of your current branch does not match the name of your current branch."+ * Three tests failed on CI and passed locally for that reason alone. A test fixture must not+ * inherit the thing it is testing around.+ */+const BRANCH = "main";++async function seedRemoteAndClone() {+ fs.rmSync(LAB, { recursive: true, force: true });+ fs.rmSync(VAULT, { recursive: true, force: true });+ fs.mkdirSync(LAB, { recursive: true });++ await simpleGit().raw(["init", "--bare", "-b", BRANCH, REMOTE]);+ await simpleGit().clone(REMOTE, SEED);+ const seed = simpleGit(SEED);+ await seed.addConfig("user.email", "seed@test");+ await seed.addConfig("user.name", "Seed");+ // Works on an unborn branch, unlike `checkout -B`, so it can run before the first commit.+ await seed.raw(["symbolic-ref", "HEAD", `refs/heads/${BRANCH}`]);+ fs.mkdirSync(path.join(SEED, path.dirname(NOTE)), { recursive: true });+ fs.writeFileSync(path.join(SEED, NOTE), V0);+ await seed.add(["-A"]);+ await seed.commit("init");+ await seed.push(["origin", `HEAD:refs/heads/${BRANCH}`]);+ await seed.raw(["branch", `--set-upstream-to=origin/${BRANCH}`, BRANCH]);++ await simpleGit().clone(REMOTE, VAULT);+ const v = vaultGit();+ await v.addConfig("user.email", "engram@test");+ await v.addConfig("user.name", "Engram");+ await v.raw(["checkout", "-B", BRANCH, `origin/${BRANCH}`]);+ await v.raw(["branch", `--set-upstream-to=origin/${BRANCH}`, BRANCH]);++ // Fail loudly here rather than as three puzzling assertion failures further down. The vault's+ // push goes through production code with no refspec, so its branch and upstream must line up.+ const st = await v.status();+ if (st.current !== BRANCH || st.tracking !== `origin/${BRANCH}`) {+ throw new Error(`fixture: vault is on ${st.current} tracking ${st.tracking}, expected ${BRANCH}/origin/${BRANCH}`);+ }++ fs.writeFileSync(+ path.join(process.env.ENGRAM_DATA_DIR!, "repos.json"),+ JSON.stringify([+ { id: REPO_ID, name: "vault", url: REMOTE, branch: BRANCH, active: true, addedAt: "2026-01-01T00:00:00.000Z" },+ ]),+ );+}++/** A second writer pushing to the same remote — the shape that made autostash lose data. */+async function secondWriterPushes(line: string) {+ const seed = simpleGit(SEED);+ await seed.raw(["pull", "--rebase", "origin", BRANCH]);+ fs.appendFileSync(path.join(SEED, NOTE), `${line}\n`);+ await seed.add(["-A"]);+ await seed.commit("second writer");+ // Explicit refspec: never depends on push.default or on the local branch name matching.+ await seed.push(["origin", `HEAD:refs/heads/${BRANCH}`]);+}++let appendNote: typeof import("./vault/write").appendNote;+let pullActive: typeof import("./git").pullActive;+let syncNow: typeof import("./git").syncNow;+let pendingReasons: typeof import("./git").pendingReasons;+let requestSync: typeof import("./git").requestSync;+let syncStatus: typeof import("./git").syncStatus;+let rebuildIndex: typeof import("./vault/store").rebuildIndex;++beforeAll(async () => {+ await seedRemoteAndClone();+ // test/setup.ts pins GIT_SYNC_ENABLED=false for every other suite; this one needs it on.+ const settings = await import("./settings");+ settings.updateSettings({ gitSyncEnabled: true, gitAuthorName: "Engram", gitAuthorEmail: "engram@test" });+ ({ pullActive, syncNow, pendingReasons, requestSync, syncStatus } = await import("./git"));+ ({ appendNote } = await import("./vault/write"));+ ({ rebuildIndex } = await import("./vault/store"));+});++afterAll(async () => {+ const settings = await import("./settings");+ settings.updateSettings({ gitSyncEnabled: false });+ fs.rmSync(path.join(process.env.ENGRAM_DATA_DIR!, "repos.json"), { force: true });+});++describe("the sync queue drains", () => {+ test("a completed sync does not re-queue its reasons", async () => {+ requestSync("Agent Yang: append delivery.md");+ expect(pendingReasons().length).toBe(1);++ fs.appendFileSync(path.join(VAULT, NOTE), "- **2026-08-06** — first entry.\n");+ const out = await syncNow();++ expect(out?.committed).toBe(true);+ // The bug: `pending` still held the reason, so the next commit repeated it.+ expect(pendingReasons()).toEqual([]);+ });++ test("consecutive syncs do not accumulate each other's reasons in the commit subject", async () => {+ const subjects: string[] = [];+ for (const entry of ["second", "third", "fourth"]) {+ fs.appendFileSync(path.join(VAULT, NOTE), `- **2026-08-06** — ${entry} entry.\n`);+ requestSync(`Agent Yang: append ${entry}`);+ await syncNow();+ subjects.push((await vaultGit().log({ maxCount: 1 })).latest!.message);+ }+ // Production showed "1 change(s)" → "2" → "3": every subject restating all earlier reasons.+ for (const s of subjects) expect(s).toContain("brain: 1 change(s)");+ expect(subjects[2]).toContain("fourth");+ expect(subjects[2]).not.toContain("second");+ });+});++describe("a pull never rebases over uncommitted vault writes", () => {+ test("an uncommitted append survives a concurrent pull, with a second writer on the same note", async () => {+ await syncNow(); // start from a clean tree+ await secondWriterPushes("- **2026-08-05** — line from the other writer.");++ const entry = "- **2026-08-06** — MARKER Bitwarden collection created.";+ await appendNote(NOTE, entry); // on disk, not yet committed (2.5s debounce)++ const res = await pullActive();++ expect(res.ok).toBe(true);+ // The append must still be on disk, whatever the pull decided to do.+ expect(onDisk()).toContain(entry);+ // …and not smuggled into a stash where nobody would look for it.+ expect((await vaultGit().stashList()).total).toBe(0);+ // …and not left as a conflicted merge for the next writer to trip over.+ expect(onDisk()).not.toContain("<<<<<<<");+ });++ test("a conflicting second writer never corrupts the note or strands the repo mid-rebase", async () => {+ const entry = "- **2026-08-06** — MARKER Bitwarden collection created.";+ const out = await syncNow();++ // Both writers appended to the end of the same note, so the rebase conflicts. What matters is+ // that our content survives, the note is clean, and the repo is left usable.+ expect(out?.committed).toBe(true);+ const body = onDisk();+ expect(body).toContain(entry); // ours, still here+ expect(body).toContain("Phase 3 content build completed."); // and the original+ expect(body).not.toContain("<<<<<<<"); // never conflict markers on disk+ expect(body).not.toContain(">>>>>>>");++ // Not stranded: on a branch, no rebase in flight, nothing hidden in a stash.+ const status = await vaultGit().status();+ expect(status.current).toBe(BRANCH);+ expect(status.conflicted).toEqual([]);+ expect((await vaultGit().stashList()).total).toBe(0);++ // And the divergence is reported rather than swallowed.+ expect(out?.conflicted).toBe(true);+ expect(out?.error).toMatch(/diverged/);+ const s = (await syncStatus()) as { lastError?: string };+ expect(s.lastError).toMatch(/diverged/);+ });++ test("no conflict markers are ever committed to the vault", async () => {+ const log = await vaultGit().raw(["log", "-p", "--all", "-S", "<<<<<<<", "--", NOTE]);+ expect(log.trim()).toBe("");+ });++ test("a non-conflicting second writer merges cleanly and both sides land", async () => {+ // Reset to a shared base, then have the other writer touch a DIFFERENT note — the ordinary+ // case, which must rebase through without deferring, conflicting, or losing either side.+ const g = vaultGit();+ await g.raw(["fetch", "origin"]);+ await g.raw(["reset", "--hard", `origin/${BRANCH}`]);+ rebuildIndex();++ const seed = simpleGit(SEED);+ await seed.raw(["pull", "--rebase", "origin", BRANCH]);+ fs.writeFileSync(path.join(SEED, "clients/kolumbi/access.md"), "---\ntitle: Access\n---\n\n- their note\n");+ await seed.add(["-A"]);+ await seed.commit("second writer, different file");+ await seed.push(["origin", `HEAD:refs/heads/${BRANCH}`]);++ const ours = "- **2026-08-06** — ours, on a different line.";+ await appendNote(NOTE, ours);+ const out = await syncNow();++ expect(out?.conflicted).toBeFalsy();+ expect(out?.pushed).toBe(true);+ expect(onDisk()).toContain(ours);+ expect(fs.readFileSync(path.join(VAULT, "clients/kolumbi/access.md"), "utf8")).toContain("their note");+ });++ test("repeated append-then-pull cycles lose nothing", async () => {+ for (let i = 0; i < 5; i++) {+ const entry = `- **2026-08-06** — cycle-${i} entry.`;+ await appendNote(NOTE, entry);+ await pullActive();+ expect(onDisk()).toContain(entry);+ await syncNow();+ expect(onDisk()).toContain(entry);+ }+ const body = onDisk();+ for (let i = 0; i < 5; i++) expect(body).toContain(`cycle-${i} entry.`);+ expect((await vaultGit().stashList()).total).toBe(0);+ });+});++describe("sync failures are reportable, not just console noise", () => {+ test("syncStatus surfaces a stranded stash so old autostash losses can be recovered", async () => {+ await syncNow();+ // Simulate what the old --autostash pull left behind: vault content parked in a stash.+ fs.appendFileSync(path.join(VAULT, NOTE), "- stranded content\n");+ await vaultGit().stash(["push", "-m", "autostash"]);++ const s = (await syncStatus()) as { enabled: boolean; stashed?: number };+ expect(s.enabled).toBe(true);+ expect(s.stashed).toBe(1);++ await vaultGit().stash(["drop"]);+ });+});diff --git a/lib/git.ts b/lib/git.tsindex 98c986e..2385280 100644--- a/lib/git.ts+++ b/lib/git.ts@@ -18,8 +18,22 @@ let pending: string[] = [];* (write-sync) instead of stacking more work on top.*/let gitBusy = false;-async function withGitLock<T>(fn: () => Promise<T>): Promise<T | undefined> {- if (gitBusy) return undefined;++/**+ * Returned when the lock was held and `fn` never ran.+ *+ * A Symbol, not `undefined`: the original guard returned `undefined` for "skipped", but a callback+ * typed `Promise<void>` also resolves to `undefined`, so "we skipped" and "we ran and finished"+ * were the same value. `runSync` therefore treated EVERY successful sync as a skip — it re-queued+ * its reasons and rescheduled itself, forever. The vault's git history shows it plainly: on+ * 2026-08-06 the commit subjects grew `1 change(s)` → `2` → `3` → `4` → `5`, each repeating every+ * earlier reason, because `pending` never drained. A sentinel that cannot be produced by `fn`+ * makes the two cases impossible to confuse.+ */+const SKIPPED = Symbol("git-busy");++async function withGitLock<T>(fn: () => Promise<T>): Promise<T | typeof SKIPPED> {+ if (gitBusy) return SKIPPED;gitBusy = true;try {return await fn();@@ -41,21 +55,28 @@ export function gitVaultDir(): string | null {}/**- * The environment for a git child process.+ * The environment for a git child process: the host environment with every `GIT_*` inherited+ * variable dropped, plus the identity and prompt settings this sync needs.+ *+ * simple-git refuses to spawn when certain variables are inherited from the host — `GIT_EDITOR`,+ * `GIT_ASKPASS`, `GIT_CONFIG_COUNT` and friends — because a hostile value would execute arbitrary+ * code or rewrite config. It throws, and the only symptom is a console.error while the vault+ * quietly stops syncing and the write tools keep answering `ok: true`.*- * simple-git refuses to run when an editor variable is inherited from the host- * ("Use of GIT_EDITOR is not permitted without enabling allowUnsafeEditor"), because a- * hostile value would execute arbitrary code. Plenty of shells and CI images export one, and- * the only symptom was a console.error while the vault quietly stopped syncing — so strip- * them rather than re-permitting them. `-m` commits need no editor anyway.+ * The previous version named two variables (`GIT_EDITOR`, `GIT_SEQUENCE_EDITOR`) and so had to be+ * right about a list that grows: `GIT_ASKPASS` alone is exported by both VS Code and the `gh` CLI.+ * Dropping the whole `GIT_*` namespace ends that game and is what we actually want — Engram sets+ * its own author, needs no editor, and must never inherit `GIT_DIR`, `GIT_WORK_TREE` or+ * `GIT_INDEX_FILE`, any of which would silently point the commit at the wrong repository.+ * `SSH_ASKPASS` is the one non-`GIT_` member of the same family.** GIT_TERMINAL_PROMPT=0 stops a missing credential from hanging the push forever.*/-function commitEnv(name: string, email: string): Record<string, string> {+function gitEnv(name: string, email: string): Record<string, string> {const env: Record<string, string> = {};for (const [k, v] of Object.entries(process.env)) {if (v === undefined) continue;- if (k === "GIT_EDITOR" || k === "GIT_SEQUENCE_EDITOR") continue;+ if (k.startsWith("GIT_") || k === "SSH_ASKPASS") continue;env[k] = v;}return {@@ -68,6 +89,16 @@ function commitEnv(name: string, email: string): Record<string, string> {};}+/**+ * A git client for the vault with the sanitised environment already applied — to EVERY command,+ * not just the commit. Pull and push spawn child processes through the same guard, so an+ * inherited `GIT_ASKPASS` broke them exactly as it broke commits.+ */+function vaultGit(dir: string) {+ const { name, email } = gitAuthor();+ return simpleGit(dir).env(gitEnv(name, email));+}+/*** Debounced commit + pull --rebase + push of the active vault. No-op unless git-sync is on* AND the vault is its own git repo (see gitVaultDir).@@ -79,79 +110,233 @@ export function requestSync(reason: string): void {timer = setTimeout(runSync, 2500);}-async function runSync(): Promise<void> {- const reasons = pending;- pending = [];- const ran = await withGitLock(async () => {+export interface SyncOutcome {+ committed: boolean;+ pulled: boolean;+ pushed: boolean;+ /** The rebase conflicted and was aborted: the local commit is safe, the vault is behind. */+ conflicted?: boolean;+ error?: string;+}++/** The last thing that went wrong in a sync, surfaced by syncStatus() instead of only console. */+let lastSyncError: string | undefined;+const errText = (e: unknown) => (e instanceof Error ? e.message : String(e));++/**+ * Undo a rebase that stopped on a conflict, restoring the pre-pull state.+ *+ * A `git pull --rebase` that hits a conflict leaves the repo mid-rebase: HEAD detached, the+ * conflicted note carrying `<<<<<<<` markers in the working tree. Nothing here used to notice —+ * the error was logged and the next sync tick ran `git add -A` and committed, writing conflict+ * markers into the note and pushing them to the vault. Aborting puts our own commit back on the+ * branch with the note intact; we stay behind the remote until a human merges the two edits, and+ * `syncStatus().lastError` says so. Diverging visibly beats corrupting quietly.+ *+ * This is the failure mode the vault's own warning describes: "a second git writer causes merge+ * conflicts and lost edits (it already discarded a staging-URL update on 2026-07-14)".+ */+async function abortRebaseIfAny(dir: string, g: ReturnType<typeof vaultGit>): Promise<boolean> {+ const inRebase =+ fs.existsSync(path.join(dir, ".git", "rebase-merge")) || fs.existsSync(path.join(dir, ".git", "rebase-apply"));+ if (!inRebase) return false;+ try {+ await g.rebase(["--abort"]);+ console.error("[git] rebase conflicted — aborted; the vault is behind the remote until this is merged by hand");+ return true;+ } catch (e) {+ console.error("[git] rebase abort failed", e);+ return false;+ }+}++/**+ * Commit everything dirty in the vault, then rebase onto the remote and push. Runs under the git+ * lock. Always returns an outcome — never `undefined` — so the caller can tell "ran" from "skipped".+ */+async function syncOnce(reasons: string[]): Promise<SyncOutcome> {+ const out: SyncOutcome = { committed: false, pulled: false, pushed: false };+ try {+ const dir = gitVaultDir(); // may have changed since the debounce fired+ if (!dir) return out;+ const g = vaultGit(dir);+ await g.add(["-A"]);+ const status = await g.status();+ if (status.files.length === 0) return out;+ await g.commit(`brain: ${reasons.length} change(s) — ${reasons.slice(0, 3).join("; ")}`);+ out.committed = true;++ // Commit FIRST, then rebase — so the working tree is clean and the rebase has nothing to+ // stash. Deliberately no `--autostash`: see the note on pullActive. If a write landed in the+ // gap, `git pull --rebase` refuses on a dirty tree, which loses nothing; the next tick retries.+ const before = await g.revparse(["HEAD"]).catch(() => "");try {- const dir = gitVaultDir(); // may have changed since the debounce fired- if (!dir) return;- const g = simpleGit(dir);- await g.add(["-A"]);- const status = await g.status();- if (status.files.length === 0) return;- const { name, email } = gitAuthor();- await g.env(commitEnv(name, email)).commit(`brain: ${reasons.length} change(s) — ${reasons.slice(0, 3).join("; ")}`);- try {- await g.pull(["--rebase", "--autostash"]);- } catch (e) {- console.error("[git] pull failed", e);- }+ await g.pull(["--rebase"]);+ out.pulled = true;+ const after = await g.revparse(["HEAD"]).catch(() => "");+ // A rebase that replayed our commit over remote work rewrote the tree; the index must+ // follow. Previously only pullActive rebuilt, so commits arriving down THIS path left+ // search answering from pre-pull content until the watcher happened to catch up.+ if (before !== after) rebuildIndex();+ } catch (e) {+ const aborted = await abortRebaseIfAny(dir, g);+ out.error = aborted+ ? `vault diverged from its remote and the rebase conflicted; the local commit is intact but unpushed. Merge by hand. (${errText(e)})`+ : errText(e);+ out.conflicted = aborted;+ console.error("[git] pull failed", e);+ }+ // Pushing a detached HEAD or a half-finished rebase cannot help, and its failure would+ // overwrite the conflict message with a less useful one.+ if (!out.conflicted) {try {await g.push();+ out.pushed = true;} catch (e) {+ out.error = errText(e);console.error("[git] push failed", e);}- } catch (e) {- console.error("[git] sync failed", e);}- });- if (ran === undefined) {+ } catch (e) {+ out.error = errText(e);+ console.error("[git] sync failed", e);+ }+ return out;+}++async function runSync(): Promise<void> {+ const reasons = pending;+ pending = [];+ const outcome = await withGitLock(() => syncOnce(reasons));+ if (outcome === SKIPPED) {// The lock was held by a pull. The changed files are still dirty on disk, so don't drop them:// re-queue the reasons and retry once the repo is free.pending.unshift(...reasons);if (timer) clearTimeout(timer);timer = setTimeout(runSync, 2500);+ return;+ }+ lastSyncError = outcome.error;+}++/** Run the debounced sync immediately. Returns SKIPPED-as-null when a pull holds the repo. */+export async function syncNow(reason = "manual sync"): Promise<SyncOutcome | null> {+ if (!gitSyncEnabled() || !gitVaultDir()) return null;+ const reasons = pending.length > 0 ? pending : [reason];+ pending = [];+ if (timer) clearTimeout(timer);+ timer = null;+ const outcome = await withGitLock(() => syncOnce(reasons));+ if (outcome === SKIPPED) {+ pending.unshift(...reasons);+ return null;}+ lastSyncError = outcome.error;+ return outcome;+}++/** Test seam: the reasons still waiting to be committed. */+export function pendingReasons(): string[] {+ return [...pending];}export async function syncStatus() {const dir = gitVaultDir();if (!dir || !gitSyncEnabled()) return { enabled: false as const };try {- const s = await simpleGit(dir).status();- return { enabled: true as const, dirty: s.files.length, ahead: s.ahead, behind: s.behind, branch: s.current };+ const g = vaultGit(dir);+ const s = await g.status();+ // Stash entries are reported because nothing in Engram creates one any more. Any that exist+ // are vault content the old `--autostash` pull stranded — recoverable with `git stash list`+ // / `git stash pop`, but invisible until someone is told it is there.+ const stashed = await g+ .stashList()+ .then((l) => l.total)+ .catch(() => 0);+ return {+ enabled: true as const,+ dirty: s.files.length,+ ahead: s.ahead,+ behind: s.behind,+ branch: s.current,+ pending: pending.length,+ ...(stashed > 0 ? { stashed } : {}),+ ...(lastSyncError ? { lastError: lastSyncError } : {}),+ };} catch {return { enabled: true as const, error: true };}}+export interface PullResult {+ ok: boolean;+ changed: boolean;+ /** True when the pull was postponed because the vault had uncommitted writes. Not an error. */+ deferred?: boolean;+ error?: string;+}+/**- * Pull remote commits into the ACTIVE vault clone (rebase, autostash). This is how changes- * pushed to the repo from OUTSIDE Engram (an agent, a teammate, a direct git push) show up —- * the chokidar watcher then rebuilds the index. Independent of the push side; a fresh- * connected workspace should always reflect its remote. No-op for the sample/local vault.+ * Pull remote commits into the ACTIVE vault clone (rebase). This is how changes pushed to the repo+ * from OUTSIDE Engram (an agent, a teammate, a direct git push) show up — the index is rebuilt when+ * HEAD moves. Independent of the push side; a fresh connected workspace should always reflect its+ * remote. No-op for the sample/local vault.+ *+ * Postpones itself rather than rebasing over uncommitted vault writes — see below.*/-export async function pullActive(): Promise<{ ok: boolean; changed: boolean; error?: string }> {+export async function pullActive(): Promise<PullResult> {const active = getActive();if (!active) return { ok: true, changed: false };- const result = await withGitLock(async () => {+ const result = await withGitLock(async (): Promise<PullResult> => {const dir = activeVaultDir();try {- const g = simpleGit(dir);+ const g = vaultGit(dir);++ // Never rebase over uncommitted vault writes.+ //+ // This used to pull with `--autostash`, which stashes the dirty working tree for the+ // duration of the rebase and restores it after. Two ways that loses a note, both silent:+ // while the stash is held the note on disk is back at HEAD, so a `brain_append` landing in+ // that window does its read-modify-write against stale content; and if the restore then+ // fails (upstream touched the same file, or the tree moved under it), git prints "Applying+ // autostash resulted in conflicts. Your changes are safe in the stash." and STILL EXITS 0 —+ // the note is reverted, the writes live only in a stash nobody reads, and every caller was+ // already told `ok: true`. Committing first (below) is strictly better than stashing: the+ // content is in history either way, and a commit is a place people look.+ const dirty = (await g.status()).files.length > 0;+ if (dirty) {+ if (gitSyncEnabled()) {+ // The write-sync commits, then pulls, then pushes. Let it own this cycle.+ requestSync("pull deferred — uncommitted vault writes");+ return { ok: true, changed: false, deferred: true };+ }+ return {+ ok: false,+ changed: false,+ error: "vault has uncommitted changes and git-sync is off — refusing to pull over them",+ };+ }+const before = await g.revparse(["HEAD"]).catch(() => "");- await g.pull(["--rebase", "--autostash"]); // pull already fetches — a separate g.fetch() only doubles the child processes+ await g.pull(["--rebase"]); // pull already fetches — a separate g.fetch() only doubles the child processesconst after = await g.revparse(["HEAD"]).catch(() => "");const changed = before !== after;if (changed) rebuildIndex();return { ok: true, changed };} catch (e) {+ // Same reason as in syncOnce: a conflicted rebase left in place means the next `git add -A`+ // commits conflict markers into a note.+ const aborted = await abortRebaseIfAny(dir, vaultGit(dir));console.error("[git] pull failed", e);- return { ok: false, changed: false, error: e instanceof Error ? e.message : String(e) };+ return {+ ok: false,+ changed: false,+ error: aborted ? `vault diverged from its remote; rebase aborted. Merge by hand. (${errText(e)})` : errText(e),+ };}});- // undefined = a sync was already in flight; a skipped tick is not an error.- return result ?? { ok: true, changed: false };+ // SKIPPED = a sync was already in flight; a skipped tick is not an error.+ return result === SKIPPED ? { ok: true, changed: false } : result;}export interface ActivityEntry {diff --git a/lib/mcp/args.test.ts b/lib/mcp/args.test.tsnew file mode 100644index 0000000..75bb80a--- /dev/null+++ b/lib/mcp/args.test.ts@@ -0,0 +1,183 @@+import { afterEach, describe, expect, test } from "bun:test";+import fs from "node:fs";+import path from "node:path";+import { TOOL_MAP } from "./tools";+import { callTool } from "./call";++/**+ * The 2026-08-06 silent data-loss incident, pinned.+ *+ * Five `brain_append` calls to `clients/kolumbi/delivery.md` and `access.md` each returned+ * `{ ok: true }` and each committed exactly ONE BLANK LINE — the payload never reached disk.+ * The tool takes `text`; its siblings `brain_write`/`brain_edit` take `content`. Nothing on the+ * server validated `arguments` against `inputSchema`, so a call carrying `content` destructured+ * `text` as `undefined`, `String(undefined ?? "")` became `""`, and `appendNote` wrote+ * `existing + "\n"`. The caller was told it succeeded.+ *+ * Two independent defects, so two independent guards:+ * 1. arguments are validated against the tool's own inputSchema before the handler runs, and+ * 2. an append with nothing to append is refused outright.+ */++const vault = process.env.VAULT_DIR!;++function seed(rel: string, content: string): string {+ const abs = path.join(vault, rel);+ fs.mkdirSync(path.dirname(abs), { recursive: true });+ fs.writeFileSync(abs, content, "utf8");+ return abs;+}+const read = (rel: string) => fs.readFileSync(path.join(vault, rel), "utf8");+const exists = (rel: string) => fs.existsSync(path.join(vault, rel));++const NOTE = "clients/kolumbi/delivery.md";+const BODY = `---+title: Delivery+updated: '2026-07-14'+---++# Delivery++## Log++- **2026-07-20** — Phase 3 content build completed.+`;++afterEach(() => {+ fs.rmSync(path.join(vault, "clients"), { recursive: true, force: true });+ fs.rmSync(path.join(vault, "undefined.md"), { force: true });+});++describe("brain_append — the incident", () => {+ test("a payload under the wrong key is REFUSED, not silently dropped", async () => {+ seed(NOTE, BODY);+ // Exactly what production received: `content` (brain_write's parameter) instead of `text`.+ await expect(+ callTool("brain_append", { path: NOTE, content: "- **2026-08-06** — Bitwarden collection created." }),+ ).rejects.toThrow(/text/);+ // and the note is untouched — no stray blank line+ expect(read(NOTE)).toBe(BODY);+ });++ test("the refusal names the parameter the caller should have used", async () => {+ seed(NOTE, BODY);+ const err = await callTool("brain_append", { path: NOTE, content: "x" }).catch((e: Error) => e);+ expect((err as Error).message).toContain("brain_append");+ expect((err as Error).message).toContain("text");+ expect((err as Error).message).toContain("content");+ });++ test("an empty or whitespace-only append is refused", async () => {+ seed(NOTE, BODY);+ for (const text of ["", " ", "\n\n"]) {+ await expect(callTool("brain_append", { path: NOTE, text })).rejects.toThrow(/[Nn]othing to append/);+ }+ expect(read(NOTE)).toBe(BODY);+ });++ test("a missing `text` is refused rather than appending a blank line", async () => {+ seed(NOTE, BODY);+ await expect(callTool("brain_append", { path: NOTE })).rejects.toThrow();+ expect(read(NOTE)).toBe(BODY);+ });++ test("a well-formed append still works, and the text is on disk", async () => {+ seed(NOTE, BODY);+ const entry = "- **2026-08-06** — Bitwarden collection created for Kolumbi.";+ const res = (await callTool("brain_append", { path: NOTE, text: entry })) as { ok: boolean; path: string };+ expect(res.ok).toBe(true);+ expect(read(NOTE)).toContain(entry);+ expect(read(NOTE).startsWith(BODY)).toBe(true);+ });++ test("consecutive appends all survive", async () => {+ seed(NOTE, BODY);+ for (const n of ["ONE", "TWO", "THREE"]) {+ await callTool("brain_append", { path: NOTE, text: `- entry ${n}` });+ }+ const out = read(NOTE);+ for (const n of ["ONE", "TWO", "THREE"]) expect(out).toContain(`- entry ${n}`);+ });+});++describe("argument validation covers every tool", () => {+ test("an unknown argument is refused everywhere, not coerced", async () => {+ seed(NOTE, BODY);+ await expect(callTool("brain_read", { path: NOTE, sekshun: "Log" })).rejects.toThrow(/sekshun/);+ });++ test("a missing required argument is refused before the handler runs", async () => {+ // brain_move without `to` used to rename the note to `undefined.md` and report ok.+ seed(NOTE, BODY);+ await expect(callTool("brain_move", { from: NOTE })).rejects.toThrow(/to/);+ expect(exists(NOTE)).toBe(true);+ expect(exists("undefined.md")).toBe(false);+ });++ test("brain_supersede cannot retire a note into `undefined.md`", async () => {+ seed(NOTE, BODY);+ await expect(callTool("brain_supersede", { from: NOTE })).rejects.toThrow(/to/);+ expect(read(NOTE)).toBe(BODY);+ expect(exists("undefined.md")).toBe(false);+ });++ test("a write with no `path` cannot land in `undefined.md`", async () => {+ // This one is not hypothetical: vault commit 5703072 (2026-07-10) is+ // "brain: 1 change(s) — edit undefined.md", a real 38-line decision note filed at the vault+ // root because `String(undefined)` is "undefined". It was spotted and moved 90 seconds later;+ // nothing but luck made it visible.+ await expect(callTool("brain_write", { body: "---\ntitle: Decision\n---\nreal content" })).rejects.toThrow(/path/);+ await expect(callTool("brain_edit", { content: "---\ntitle: Decision\n---\nreal content" })).rejects.toThrow(/path/);+ expect(exists("undefined.md")).toBe(false);+ });++ test("a wrongly-typed argument is refused rather than stringified", async () => {+ seed(NOTE, BODY);+ await expect(callTool("brain_append", { path: NOTE, text: { md: "hi" } })).rejects.toThrow(/string/);+ expect(read(NOTE)).toBe(BODY);+ });++ test("every tool's required list only names properties it declares", () => {+ // A required key absent from `properties` would be unvalidatable and always reject.+ for (const t of TOOL_MAP.values()) {+ const schema = t.inputSchema as { properties?: Record<string, unknown>; required?: string[] };+ for (const r of schema.required ?? []) {+ expect(Object.keys(schema.properties ?? {})).toContain(r);+ }+ }+ });+});++describe("the write tools refuse an empty payload consistently", () => {+ // brain_write/brain_edit already refused; brain_append did not. That inconsistency IS the bug —+ // a client that says `content` everywhere got an error from one tool and silence from the other.+ test("brain_write refuses an empty note", async () => {+ await expect(callTool("brain_write", { path: "scratch/empty.md" })).rejects.toThrow(/[Nn]othing to write/);+ expect(exists("scratch/empty.md")).toBe(false);+ });++ test("brain_edit refuses an empty overwrite", async () => {+ // A fresh path, so the empty-payload guard is what fires rather than read-before-overwrite+ // (which correctly refuses first on an existing note — see the guardOverwrite tests).+ await expect(callTool("brain_edit", { path: "clients/kolumbi/fresh.md", body: " " })).rejects.toThrow(+ /[Nn]othing to write/,+ );+ expect(exists("clients/kolumbi/fresh.md")).toBe(false);+ });++ test("no write tool reports ok:true without changing anything", async () => {+ seed(NOTE, BODY);+ const before = read(NOTE);+ const attempts: Array<[string, Record<string, unknown>]> = [+ ["brain_append", { path: NOTE, text: "" }],+ ["brain_append", { path: NOTE, content: "dropped" }],+ ["brain_write", { path: NOTE }],+ ["brain_edit", { path: NOTE, content: "" }],+ ];+ for (const [name, args] of attempts) {+ const res = await callTool(name, args).catch((e: Error) => e);+ expect(res).toBeInstanceOf(Error);+ }+ expect(read(NOTE)).toBe(before);+ });+});diff --git a/lib/mcp/call.ts b/lib/mcp/call.tsnew file mode 100644index 0000000..9036e87--- /dev/null+++ b/lib/mcp/call.ts@@ -0,0 +1,117 @@+import { TOOL_MAP, type Tool } from "./tools";++/**+ * The dispatch boundary: validate a tool call's arguments against the tool's OWN inputSchema,+ * then run it.+ *+ * Why this exists — the 2026-08-06 incident. `brain_append` takes `text`; its siblings+ * `brain_write` and `brain_edit` take `content`. A caller sent `content` to `brain_append`.+ * Nothing validated arguments, so the handler destructured `text` as `undefined`,+ * `String(undefined ?? "")` collapsed to `""`, and the note was "appended" with a single blank+ * line — five times, each reported as `{ ok: true }`. The vault's own git history is the receipt:+ * five commits, `+1 line (0 non-blank)` each.+ *+ * Handlers coerce with `String(x)`, which turns a missing argument into the string "undefined" —+ * that is how `brain_move` without `to` renamed a live note to `undefined.md` and reported success.+ * Coercion cannot be made safe one handler at a time; the schema is the contract, so it is+ * enforced here, once, before any handler runs.+ *+ * Strict about unknown keys on purpose. An argument the server silently ignores is an argument the+ * caller believed it had sent, and this failure mode is exactly that bug with a different name.+ * The error names the parameters the tool does accept, so a model can retry correctly first time.+ */++// eslint-disable-next-line @typescript-eslint/no-explicit-any+type Args = Record<string, any>;++interface PropSchema {+ type?: string;+}+interface ToolSchema {+ properties?: Record<string, PropSchema>;+ required?: string[];+}++/** MCP reserves `_`-prefixed keys for protocol metadata; they are not tool arguments. */+const isMeta = (k: string) => k.startsWith("_");++function typeMatches(expected: string | undefined, value: unknown): boolean {+ switch (expected) {+ case "string":+ return typeof value === "string";+ case "number":+ return typeof value === "number" && Number.isFinite(value);+ case "boolean":+ return typeof value === "boolean";+ case "object":+ return typeof value === "object" && value !== null && !Array.isArray(value);+ case "array":+ return Array.isArray(value);+ default:+ return true; // no declared type — nothing to check+ }+}++function describeType(value: unknown): string {+ if (value === null) return "null";+ if (Array.isArray(value)) return "array";+ return typeof value;+}++/**+ * Check `args` against `tool.inputSchema`. Returns an error message for the caller, or null when+ * the call is well-formed. The message is written for a model that has to fix its own call.+ */+export function validateArgs(tool: Tool, args: Args): string | null {+ const schema = tool.inputSchema as ToolSchema;+ const props = schema.properties ?? {};+ const accepted = Object.keys(props);+ const acceptedList = accepted.length > 0 ? accepted.join(", ") : "(none)";++ if (typeof args !== "object" || args === null || Array.isArray(args)) {+ return `${tool.name}: \`arguments\` must be an object with ${acceptedList}.`;+ }++ // Unknown keys first: when a caller sends `content` to a tool that wants `text`, naming the+ // mistake beats reporting the resulting "missing required" further down.+ const unknown = Object.keys(args).filter((k) => !isMeta(k) && !(k in props));+ if (unknown.length > 0) {+ return (+ `${tool.name} does not accept ${unknown.map((k) => `\`${k}\``).join(", ")}. ` ++ `Its parameters are: ${acceptedList}. Nothing was written — re-send the call with the ` ++ `payload under the right parameter name.`+ );+ }++ for (const key of schema.required ?? []) {+ const v = args[key];+ if (v === undefined || v === null) {+ return `${tool.name} requires \`${key}\`, which was missing. Its parameters are: ${acceptedList}. Nothing was written.`;+ }+ }++ for (const [key, value] of Object.entries(args)) {+ if (isMeta(key) || value === undefined || value === null) continue;+ const expected = props[key]?.type;+ if (!typeMatches(expected, value)) {+ return `${tool.name}: \`${key}\` must be a ${expected}, got ${describeType(value)}. Nothing was written.`;+ }+ }++ return null;+}++/**+ * Look up a tool, validate its arguments, and run it. Throws on an unknown tool or a call that+ * does not satisfy the tool's schema — the MCP route turns a throw into an `isError` result, so a+ * rejected call is visible to the caller instead of being reported as a successful write.+ *+ * Scope enforcement stays in the route: it depends on the authenticated caller, not the arguments.+ */+export async function callTool(name: string, args: Args): Promise<unknown> {+ const tool = TOOL_MAP.get(name);+ if (!tool) throw new Error(`unknown tool: ${name}`);+ const problem = validateArgs(tool, args ?? {});+ if (problem) throw new Error(problem);+ return await tool.handler(args ?? {});+}diff --git a/lib/vault/write.ts b/lib/vault/write.tsindex 0180a8a..2da2989 100644--- a/lib/vault/write.ts+++ b/lib/vault/write.ts@@ -147,8 +147,23 @@ export async function writeNote(return writeNoteRaw(relPath, content, { ...opts, strict: true });}+/**+ * Append text to a note, creating it if missing.+ *+ * Refuses an empty append. `writeNote` has always refused to create an empty note; this path did+ * not, so an append whose payload never arrived wrote `existing + "\n"` and reported success — a+ * blank line where a log entry should have been (the 2026-08-06 incident). An append with nothing+ * to append is never intentional, and the write path must not be the layer that discovers this+ * quietly.+ */export async function appendNote(relPath: string, text: string): Promise<string> {const p = normalizeNotePath(relPath);+ if (typeof text !== "string" || text.trim() === "") {+ throw new Error(+ `Nothing to append to ${p}: \`text\` was empty. Pass the markdown to append as \`text\` ` ++ `(brain_append takes \`text\`, not \`content\` or \`body\`). The note was not modified.`,+ );+ }const abs = safeAbs(p);let existing = "";try {diff --git a/scripts/mcp-stdio.ts b/scripts/mcp-stdio.tsindex 2842674..50b9396 100644--- a/scripts/mcp-stdio.ts+++ b/scripts/mcp-stdio.ts@@ -69,7 +69,8 @@ async function main() {// Local mode: never touch git, never require an Anthropic key for introspection.process.env.GIT_SYNC_ENABLED = "false";- const { TOOLS, TOOL_MAP } = await import("@/lib/mcp/tools");+ const { TOOLS } = await import("@/lib/mcp/tools");+ const { callTool } = await import("@/lib/mcp/call");const { VERSION } = await import("@/lib/version");const { Server } = await import("@modelcontextprotocol/sdk/server/index.js");const { StdioServerTransport } = await import("@modelcontextprotocol/sdk/server/stdio.js");@@ -82,9 +83,10 @@ async function main() {}));server.setRequestHandler(CallToolRequestSchema, async (req) => {- const tool = TOOL_MAP.get(req.params.name);- if (!tool) throw new Error(`unknown tool: ${req.params.name}`);- const out = await tool.handler(req.params.arguments ?? {});+ // Via callTool, so this transport validates arguments against each tool's inputSchema exactly+ // like the HTTP route. Dispatching straight to `tool.handler` is what let a `brain_append`+ // carrying its payload under the wrong key write a blank line and report success.+ const out = await callTool(req.params.name, req.params.arguments ?? {});const text = typeof out === "string" ? out : JSON.stringify(out, null, 2);return { content: [{ type: "text", text }] };});