bantamkit-mcp 0.35.7 → 0.35.8

package/dist/hookadapter.js

@@ -264,9 +264,71 @@ function readLedger(run, sessionId) {
         return { reads: {} };
     }
 }
+/**
+ * Temp-and-rename, never a bare `writeFileSync` (job65, J65-4, #167): a reader that lands
+ * between a whole-file truncate and its write sees an empty ledger, which `readLedger` reads
+ * as "nothing seen". The rename is atomic on both platforms; the name carries the pid so two
+ * writers never share a temp file.
+ */
 function writeLedger(run, sessionId, ledger) {
     fs.mkdirSync(run.state, { recursive: true });
-    fs.writeFileSync(ledgerPath(run, sessionId), JSON.stringify(ledger));
+    const file = ledgerPath(run, sessionId);
+    const tmp = `${file}.${process.pid}.tmp`;
+    fs.writeFileSync(tmp, JSON.stringify(ledger));
+    fs.renameSync(tmp, file);
+}
+/** How long a writer waits for the ledger lock before going ahead without it. */
+const LEDGER_LOCK_WAIT_MS = 2000;
+/** A lock file older than this was left by a hook process that died holding it. */
+const LEDGER_LOCK_STALE_MS = 10_000;
+/** The poll between two attempts at the lock. */
+const LEDGER_LOCK_POLL_MS = 5;
+/**
+ * One read-modify-write of the session ledger, under a lock (job65, J65-4, #167).
+ *
+ * THE RACE THIS CLOSES IS MEASURED, not supposed: the host fires one hook PROCESS per tool
+ * call and a parallel tool block fires them at once, so twenty Reads in one block are twenty
+ * processes each doing read → add one entry → write the whole file, and the last writer wins.
+ * Measured at 64ae11d over 20 distinct files: 6 of 20 entries survived on this side, 16 of 20
+ * on the reference (`.shiftwork/notes-job65/J65-4.md`). An atomic write alone cannot close it
+ * — the lost entries are lost between the read and the write, not inside the write — so the
+ * whole read-modify-write runs under `<ledger>.lock`, taken with `O_EXCL` (the one primitive
+ * both platforms and both runtimes share without a dependency). A lock older than
+ * `LEDGER_LOCK_STALE_MS` is a dead holder's and is removed; a writer that cannot take the
+ * lock within `LEDGER_LOCK_WAIT_MS` goes ahead unlocked, because a hook that fails the tool
+ * call over its own cache is worse than a lost entry. `update` returns whether the ledger
+ * changed; nothing is written when it did not.
+ */
+function updateLedger(run, sessionId, update) {
+    fs.mkdirSync(run.state, { recursive: true });
+    const lock = `${ledgerPath(run, sessionId)}.lock`;
+    const deadline = Date.now() + LEDGER_LOCK_WAIT_MS;
+    let held = false;
+    while (!held && Date.now() < deadline) {
+        try {
+            fs.closeSync(fs.openSync(lock, 'wx'));
+            held = true;
+        }
+        catch {
+            try {
+                if (Date.now() - fs.statSync(lock).mtimeMs > LEDGER_LOCK_STALE_MS)
+                    fs.rmSync(lock, { force: true });
+            }
+            catch {
+                /* the holder released it between the open and the stat: go round again */
+            }
+            Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, LEDGER_LOCK_POLL_MS);
+        }
+    }
+    try {
+        const ledger = readLedger(run, sessionId);
+        if (update(ledger))
+            writeLedger(run, sessionId, ledger);
+    }
+    finally {
+        if (held)
+            fs.rmSync(lock, { force: true });
+    }
 }
 // ------------------------------------- the host's auto-memory directory, and A's export
 //
@@ -494,6 +556,7 @@ function exportToNative(dir, store) {
         bytes: 0,
         indexBytes: 0,
         skipped: [],
+        unparsed: [],
         index: 'absent',
     };
     const indexFile = path.join(dir, NATIVE_INDEX);
@@ -510,8 +573,11 @@ function exportToNative(dir, store) {
     let named = seeded;
     const appended = [];
     try {
-        const { facts, indexLine } = new MemoryStore(store).internals();
-        const ranked = rankBySessionDropRule(facts().map((fact, position) => ({
+        const source = new MemoryStore(store);
+        const { indexLine } = source.internals();
+        const { facts, skipped } = tolerantFacts(source);
+        result.unparsed = skipped;
+        const ranked = rankBySessionDropRule(facts.map((fact, position) => ({
             fact,
             position,
             line: indexLine(fact),
@@ -608,8 +674,10 @@ function rankBySessionDropRule(all) {
     return [...all].sort((a, b) => decays(a) - decays(b) || cmp(evidence(b), evidence(a)) || cmp(a.name, b.name) || a.position - b.position);
 }
 function cappedIndex(root, header, max) {
-    const { facts, indexLine } = new MemoryStore(root).internals();
-    const all = facts().map((fact, position) => ({
+    const store = new MemoryStore(root);
+    const { indexLine } = store.internals();
+    const { facts, skipped } = tolerantFacts(store);
+    const all = facts.map((fact, position) => ({
         fact,
         position,
         line: indexLine(fact),
@@ -631,13 +699,15 @@ function cappedIndex(root, header, max) {
         .map((f) => f.line)
         .join('')
         .replace(/\n$/, ''), max);
-    const lines = [header(dropped.length ? `${shown.length} of ${all.length}` : String(all.length))];
+    const lines = [header(dropped.length ? `${shown.length} of ${all.length}` : String(all.length), all.length)];
     if (body)
         lines.push(body);
     if (dropped.length) {
         lines.push(`[${dropped.length} of ${all.length} not shown — the block is capped at ${max} bytes; kept by rule: ${SESSION_DROP_RULE}; ~/.bantamkit/hooks/hook-log.jsonl names the dropped; mcp__bantamkit__memory_recall reads any fact by name]`);
     }
-    return { block: lines.join('\n'), total: all.length, injected: shown.length, dropped };
+    if (skipped.length)
+        lines.push(skippedLine(skipped));
+    return { block: lines.join('\n'), total: all.length, injected: shown.length, dropped, skipped };
 }
 function countFacts(store) {
     try {
@@ -647,6 +717,25 @@ function countFacts(store) {
         return 0;
     }
 }
+/**
+ * Every fact `store` can read, and the files it could not: `MemoryStore.readableFacts`. A
+ * store whose `facts/` cannot be LISTED still throws, exactly as before: that is a layer that
+ * could not be read, not a fact.
+ */
+function tolerantFacts(store) {
+    return store.readableFacts();
+}
+/** "1 fact" / "N facts" (#188). The noun follows the block's TOTAL, the last number shown. */
+function factNoun(total) {
+    return total === 1 ? 'fact' : 'facts';
+}
+/** The block's footer when files were left out: their names, never their contents. */
+function skippedLine(skipped) {
+    const n = skipped.length;
+    return capBytes(`[${n} fact ${n === 1 ? 'file' : 'files'} not read — not a valid fact: ${skipped.map((s) => s.file).join(', ')}; ~/.bantamkit/hooks/hook-log.jsonl has the reason]`, SKIPPED_LINE_MAX);
+}
+/** A footer naming many broken files is still bounded, like everything else this file injects. */
+const SKIPPED_LINE_MAX = 500;
 // ------------------------------------------------------- the stale-install signal
 // Reader 2 and Writer 1 of `docs/superpowers/specs/2026-09-19-stale-version-signal-design.md`.
 // One line at SessionStart when the install this hook can SEE is older than what the package
@@ -817,10 +906,19 @@ function sessionStart(run, input) {
     const cwd = input.cwd || process.cwd();
     const parts = [];
     const profileFacts = countFacts(run.profile);
-    let profile = { block: '', total: 0, injected: 0, dropped: [] };
+    let profile = { block: '', total: 0, injected: 0, dropped: [], skipped: [] };
+    // IN ITS OWN TRY (job65, #119): this block used to sit outside every try, so a profile store
+    // the hook could not read at all threw past the arm and the session got NO context — not the
+    // project block, not the toolbox line. One unreadable FILE is handled inside `cappedIndex`;
+    // this catch is for a store that cannot even be listed, and it costs the profile block only.
     if (profileFacts > 0) {
-        profile = cappedIndex(run.profile, (count) => `[bantamkit profile memory — ${count} facts learned across projects]`, SESSION_INJECT_MAX);
-        parts.push(profile.block);
+        try {
+            profile = cappedIndex(run.profile, (count, total) => `[bantamkit profile memory — ${count} ${factNoun(total)} learned across projects]`, SESSION_INJECT_MAX);
+            parts.push(profile.block);
+        }
+        catch (e) {
+            log(run, { event: 'SessionStart', warn: `profile: ${message(e)}` });
+        }
     }
     // WHERE THE HOST'S OWN AUTO-MEMORY DIRECTORY IS, resolved ONCE per session and used twice:
     // it decides whether the project index has to be injected at all, and it is where A exports.
@@ -843,7 +941,7 @@ function sessionStart(run, input) {
         const store = discoverProjectStore(cwd);
         if (path.resolve(store) !== path.resolve(run.profile) && countFacts(store) > 0) {
             if (native.dir === null) {
-                project = cappedIndex(store, (count) => `[bantamkit project memory — ${count} facts]`, SESSION_INJECT_MAX);
+                project = cappedIndex(store, (count, total) => `[bantamkit project memory — ${count} ${factNoun(total)}]`, SESSION_INJECT_MAX);
                 project.facts = countFacts(store);
                 parts.push(project.block);
             }
@@ -906,8 +1004,16 @@ function sessionStart(run, input) {
         profileFacts,
         profileInjected: profile.injected,
         profileDropped: profile.dropped,
+        // #119: the files left out, by name and the store's reason — present only when non-empty,
+        // so a healthy session's record is the shape it always was.
+        ...(profile.skipped.length ? { profileSkipped: profile.skipped } : {}),
         ...(project
-            ? { projectFacts: project.facts, projectInjected: project.injected, projectDropped: project.dropped }
+            ? {
+                projectFacts: project.facts,
+                projectInjected: project.injected,
+                projectDropped: project.dropped,
+                ...(project.skipped.length ? { projectSkipped: project.skipped } : {}),
+            }
             : {}),
         dropRule: SESSION_DROP_RULE,
         // A — the host's auto-memory directory. `nativeBranch` / `nativeTried` are the one line
@@ -925,6 +1031,7 @@ function sessionStart(run, input) {
                 nativeBytes: exported.bytes,
                 nativeIndexBytes: exported.indexBytes,
                 nativeSkipped: exported.skipped,
+                ...(exported.unparsed.length ? { nativeUnparsed: exported.unparsed } : {}),
                 nativeIndex: exported.index,
                 ...(exported.error ? { nativeError: exported.error } : {}),
             }
@@ -1009,17 +1116,26 @@ function userPromptSubmit(run, input) {
     // prompt, for up to three files — and the rules keyed on that date (compaction's
     // stalest-first, the SessionStart drop rule, the Stop dream's store fingerprint) were
     // reading this arm's traffic. An explicit `memory_recall` still stamps.
-    const o = m.recallOutcome(prompt, 3, RECALL_MIN_SCORE_RATIO, false);
+    const ask = () => m.recallOutcome(prompt, 3, RECALL_MIN_SCORE_RATIO, false);
+    // ONE UNREADABLE FACT COSTS THAT FACT (job65, #119): the recall reads every layer past the
+    // files it cannot read and names them in `o.skipped`; one recall, healthy or not. A layer
+    // that cannot be LISTED fails exactly as it did.
+    const o = ask();
+    const skipped = o.skipped.map((s) => ({ ...s }));
+    const degraded = skipped.length ? { skipped } : {};
     if (o.status !== 'answered') {
-        log(run, { event: 'UserPromptSubmit', action: 'none', status: o.status, candidates: o.candidates });
+        log(run, { event: 'UserPromptSubmit', action: 'none', status: o.status, candidates: o.candidates, ...degraded });
         return;
     }
     // Only the HEADER line of each hit — `[layer] [name] (type) description`. The body costs
     // ~1.5 KB a fact and would be re-sent on every later call; the header is ~150 B and
     // tells the model exactly which name to pass to memory_recall if it wants the body.
-    const heads = o.reply.split('\n').filter((l) => RECALL_HEADER.test(l));
+    // Read off `o.headers`, built from the parsed fields (job65, #155), never by filtering the
+    // reply's lines: a fact BODY line shaped like `[profile] [x] (feedback) ...` used to pass
+    // for a header and be injected as a memory nobody saved.
+    const heads = o.headers.filter((l) => RECALL_HEADER.test(l));
     if (heads.length === 0) {
-        log(run, { event: 'UserPromptSubmit', action: 'none', reason: 'no-headers' });
+        log(run, { event: 'UserPromptSubmit', action: 'none', reason: 'no-headers', ...degraded });
         return;
     }
     // WHAT THIS CONTEXT HAS ALREADY BEEN SHOWN IS NOT SHOWN AGAIN (job64, J64-2). Measured
@@ -1056,6 +1172,7 @@ function userPromptSubmit(run, input) {
             session: input.session_id ?? null,
             prompt: promptFingerprint(prompt),
             suppressed,
+            ...degraded,
         });
         return;
     }
@@ -1094,6 +1211,7 @@ function userPromptSubmit(run, input) {
         injected,
         dropped: fresh.length - injected.length,
         suppressed,
+        ...degraded,
     });
     emit({ hookSpecificOutput: { hookEventName: 'UserPromptSubmit', additionalContext: ctx } });
 }
@@ -1103,7 +1221,15 @@ function userPromptSubmit(run, input) {
 // because they never pass through bantamkit's Agent. A PreToolUse hook is the one place
 // that does see them. Keyed by transcript (a subagent has its own transcript and has NOT
 // seen the parent's read), by path+offset+limit, and by mtime+size so an edit re-arms it.
-// REFUSES ONCE: the second identical call goes through, so nothing can be hard-blocked.
+// REFUSES ONCE: the second identical call goes through, so nothing can be hard-blocked —
+// and ONLY once (job65, J65-4, #166): the allowed retry used to write `refused: false`
+// back, which re-armed the gate and refused every other read (allow, deny, allow, deny, …)
+// of a file the docs promise is "refused once". The record now keeps `refused: true` until
+// the signature changes, so the sequence is allow, deny, allow, allow, … and an edit re-arms.
+// ONLY REGULAR FILES (#190): a directory stats fine, so it was ledgered and its retry refused
+// with "use the content from that earlier read" — content the host never produced, because
+// the first Read failed with EISDIR. Anything that is not a regular file is treated like a
+// missing path: not ledgered, never refused, Read produces its own error.
 function preToolUseRead(run, input) {
     const ti = input.tool_input ?? {};
     const file = typeof ti['file_path'] === 'string' ? ti['file_path'] : '';
@@ -1116,6 +1242,22 @@ function preToolUseRead(run, input) {
     catch {
         return; // missing file: let Read produce its own error
     }
+    if (!st.isFile())
+        return; // a directory/device read has no file content to reuse
+    // NOR A FILE THIS PROCESS MAY NOT READ (job65, #192). `isFile` closed the directory case of
+    // #190 but the ledger still recorded on PreToolUse, before the host's Read could fail: a
+    // `chmod 000` file was ledgered and its retry refused with "use the content from that
+    // earlier read" — content the host never produced. The hook runs as the same user as the
+    // host's Read, so `R_OK` here is the host's answer; a file that fails it is treated like a
+    // missing path: not ledgered, never refused. Chosen over moving the record to
+    // PostToolUse[Read] because it is one check in the arm that already decides, on both
+    // runtimes, and needs no second event to agree with the first (docs/hooks.md, PreToolUse).
+    try {
+        fs.accessSync(file, fs.constants.R_OK);
+    }
+    catch {
+        return;
+    }
     const offset = ti['offset'];
     const limit = ti['limit'];
     // The transcript is the CONTEXT dimension: a subagent has its own transcript and has not
@@ -1123,14 +1265,39 @@ function preToolUseRead(run, input) {
     // `preCompact` must filter on it and a path may itself contain the key's delimiter.
     const transcript = String(input.transcript_path || input.session_id || '');
     const key = `${transcript}|${file}|${offset ?? ''}|${limit ?? ''}`;
-    const ledger = readLedger(run, input.session_id);
-    const prev = ledger.reads[key];
     const sig = `${st.mtimeMs}|${st.size}`;
-    if (prev && prev.sig === sig && !prev.refused) {
-        prev.refused = true;
-        prev.count += 1;
-        writeLedger(run, input.session_id, ledger);
-        const reason = `bantamkit filegraph: ${file}${offset != null ? ` (offset ${offset}${limit != null ? `, limit ${limit}` : ''})` : ''} was already read in this context at ${prev.at} and is unchanged on disk (same mtime and size). Use the content from that earlier read. If you genuinely need it again, repeat the exact same call — this refusal fires only once per unchanged file.`;
+    const decision = {
+        action: 'record',
+        refusedAt: '',
+    };
+    // The whole read-modify-write under the ledger lock (#167); the decision is emitted after.
+    updateLedger(run, input.session_id, (ledger) => {
+        const prev = ledger.reads[key];
+        if (prev && prev.sig === sig) {
+            prev.count += 1;
+            if (!prev.refused) {
+                prev.refused = true;
+                decision.action = 'refuse';
+                decision.refusedAt = prev.at;
+            }
+            else {
+                decision.action = 'allow-after-refuse-or-change'; // refused once already; every later repeat goes through
+            }
+            return true;
+        }
+        ledger.reads[key] = {
+            sig,
+            at: new Date().toISOString(),
+            count: (prev ? prev.count : 0) + 1,
+            refused: false,
+            transcript,
+            file,
+        };
+        decision.action = prev ? 'allow-after-refuse-or-change' : 'record';
+        return true;
+    });
+    if (decision.action === 'refuse') {
+        const reason = `bantamkit filegraph: ${file}${offset != null ? ` (offset ${offset}${limit != null ? `, limit ${limit}` : ''})` : ''} was already read in this context at ${decision.refusedAt} and is unchanged on disk (same mtime and size). Use the content from that earlier read. If you genuinely need it again, repeat the exact same call — this refusal fires only once per unchanged file.`;
         log(run, { event: 'PreToolUse', action: 'refuse', file, size: st.size });
         emit({
             hookSpecificOutput: {
@@ -1141,21 +1308,7 @@ function preToolUseRead(run, input) {
         });
         return;
     }
-    ledger.reads[key] = {
-        sig,
-        at: new Date().toISOString(),
-        count: (prev ? prev.count : 0) + 1,
-        refused: false,
-        transcript,
-        file,
-    };
-    writeLedger(run, input.session_id, ledger);
-    log(run, {
-        event: 'PreToolUse',
-        action: prev ? 'allow-after-refuse-or-change' : 'record',
-        file,
-        size: st.size,
-    });
+    log(run, { event: 'PreToolUse', action: decision.action, file, size: st.size });
 }
 // ---------------------------------------------- PostToolUse → the usage events log
 // One line per tool call, for `tools/ledger/tool-usage.mjs` to read when a transcript is gone.
@@ -2070,7 +2223,7 @@ function stop(run, input) {
     const toolUses = (text.match(/"type":\s*"tool_use"/g) || []).length;
     const saved = (ledger.saved || 0) > 0 ||
         /"name":\s*"mcp__bantamkit__memory_save"/.test(text) ||
-        /"file_path":"[^"]*[\\/]memory[\\/][^"]*\.md"/.test(text);
+        transcriptWroteMemory(text);
     if (toolUses < STOP_NUDGE_MIN_TOOL_CALLS || saved) {
         log(run, { event: 'Stop', action: 'pass', toolUses, saved });
         return;
@@ -2083,6 +2236,51 @@ function stop(run, input) {
         reason: `bantamkit: this session made ${toolUses} tool calls and saved no memory. Before stopping, decide whether anything durable was learned that is NOT derivable from the repo, git history, or docs — a correction or preference the user stated (feedback), a fact about ongoing work or a decision (project), a URL/ticket/dashboard (reference). If so, call mcp__bantamkit__memory_save for each (at most 3, description written as the words a future query would use). If nothing qualifies, stop with one line saying so. This nudge fires once per session.`,
     });
 }
+/** The native write tools whose `file_path` can put a fact into a `memory/` directory. */
+const SAVE_WRITE_TOOLS = new Set(['Write', 'Edit', 'MultiEdit']);
+/** The path shape of a native memory write: a `.md` under any `memory/` directory. */
+const SAVE_WRITE_PATH = /[\\/]memory[\\/][\s\S]*\.md$/;
+/** A line can only hold a native write if it names one of the tools; the rest are never parsed. */
+const SAVE_LINE_HINT = /"name":\s*"(?:Write|Edit|MultiEdit)"/;
+/**
+ * Did the transcript WRITE a native memory file (job65, #169)? Only a `tool_use` counts: a
+ * Write/Edit/MultiEdit whose `file_path` is a `.md` under a `memory/` directory. Before this a
+ * regex over the whole text took ANY `"file_path"` under `memory/` — a Read of
+ * `docs/memory/notes.md` included — as a save, and silenced the nudge. (A `memory_save` call
+ * is still recognised by its tool name, as it always was; that half was never the defect.)
+ *
+ * Lines are prefiltered on the tool names and only those are parsed, so a long transcript
+ * costs one regex per line and a `JSON.parse` only where a write could be. A line that does
+ * not parse is not a save.
+ */
+function transcriptWroteMemory(text) {
+    for (const line of text.split('\n')) {
+        if (!SAVE_LINE_HINT.test(line))
+            continue;
+        let record;
+        try {
+            record = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        const msg = record && typeof record === 'object' ? record.message : undefined;
+        const content = msg && typeof msg === 'object' ? msg.content : undefined;
+        if (!Array.isArray(content))
+            continue;
+        for (const block of content) {
+            if (!block || typeof block !== 'object')
+                continue;
+            const b = block;
+            if (b.type !== 'tool_use' || typeof b.name !== 'string' || !SAVE_WRITE_TOOLS.has(b.name))
+                continue;
+            const fp = b.input && typeof b.input === 'object' ? b.input.file_path : undefined;
+            if (typeof fp === 'string' && SAVE_WRITE_PATH.test(fp))
+                return true;
+        }
+    }
+    return false;
+}
 // ---------------------------------------------------------------------- dispatch
 /** Read the whole of stdin. One JSON object is the entire input contract. */
 async function readStdin() {
@@ -2109,7 +2307,15 @@ export async function runHook() {
             input = parsed;
     }
     catch {
-        log(run, { event: 'parse-error', raw: raw.slice(0, 200) });
+        // THE INPUT IS NOT LOGGED, AT ANY LENGTH (job65, #168): a truncated UserPromptSubmit event
+        // carries the user's prompt, and this line used to keep its first 200 characters. Its
+        // size and a SHA-256 digest are kept instead, the same fingerprint `promptFingerprint`
+        // gives a prompt that did parse, so a bad input can still be recognised twice.
+        log(run, {
+            event: 'parse-error',
+            bytes: Buffer.byteLength(raw),
+            sha256: createHash('sha256').update(raw, 'utf8').digest('hex'),
+        });
         return;
     }
     const ev = input.hook_event_name;