Skip to content

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.

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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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 processes
const 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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 }] };
});