bantamkit-mcp 0.34.2 → 0.35.0

package/README.md

@@ -5,7 +5,7 @@ store, JSON Schema validation and shift-work tools. Install it from **npm** with
 command, connect it to **Claude Code**, **Claude Desktop**, **Cursor** or **GitHub Copilot in VS
 Code**, and every later launch starts **offline**. No Python, `pip`, `uv`, `pipx` or venv.
 
-It serves the same twelve tools, `bantamkit_status` prompt and two resource templates as the
+It serves the same fourteen tools, `bantamkit_status` prompt and two resource templates as the
 Python server on **PyPI** (`pip install "bantamkit[mcp]"`), and reads and writes the same memory
 store. The two are compared frame by frame: 8,130 conformance cases on 2026-09-15, with every
 intentional difference written down as a ruling.
@@ -30,7 +30,7 @@ intentional difference written down as a ruling.
 | [The operator CLI: `bantamkit-memory`](#the-operator-cli-bantamkit-memory) | The second bin: status, lint, compact, archive, restore |
 | [Memory stores are layered by default](#memory-stores-are-layered-by-default) | Why not to add `--store` by reflex |
 | [The asset pack](#the-asset-pack) | What ships in `assets/` and how it is found |
-| [Sharing a store with the Python server](#sharing-a-store-with-the-python-server) | Concurrent writes, and one hand-edit to avoid |
+| [Where the Python and Node servers differ](#where-the-python-and-node-servers-differ) | One store; concurrent writes, one hand-edit to avoid |
 | [Development](#development) | Build, test, conformance |
 | [Measurements and history](#measurements-and-history) | Where the measured numbers behind this page live |
 
@@ -50,9 +50,9 @@ npx -y bantamkit-mcp@latest --install claude   # or claude-desktop, copilot, cur
 From 0.34.0 this runs `npm install --prefix ~/.bantamkit/mcp` once (Windows:
 `%USERPROFILE%\.bantamkit\mcp`, not measured) and records
 `<the node that ran it> ~/.bantamkit/mcp/node_modules/bantamkit-mcp/dist/cli.js`, both absolute.
-No later launch needs npx, the registry or your PATH. Measured from the published 0.34.0:
-install exit 0 in 8.14 s; the recorded command then served 12 tools in 0.09 s with the network
-cut.
+No later launch needs npx, the registry or your PATH. Measured from the published 0.34.0
+(served-tools: dated — the surface was twelve then): install exit 0 in 8.14 s; the recorded
+command then served 12 tools in 0.09 s with the network cut.
 
 - **`@latest` matters:** without it npx may reuse an older cached resolve.
 - **It skips npm when the kept install already reports this version or a newer one.** It never
@@ -235,10 +235,15 @@ startup. In Claude Code: `/mcp` → reconnect. In Claude Desktop: a full restart
 **Verify with `bantamkit_status`, not the install log.** It reports the version and the
 `build_id` of *the code that is answering you*:
 
+*(A capture from 0.30.0. The version and build-digest bytes are left as a dated transcript
+rather than hand-edited to a number nobody ran; **line 3 is the exception and tracks the
+surface**, for the reason `docs/status.md` gives — the tool count is a live claim this repo
+gates against a running server, and a marker would only hide it from that gate.)*
+
 ```
 bantamkit Active 🟢
 version 0.30.0, build sha256:4441619d…
-serving 12 tools, 1 prompt, 2 resource templates
+serving 14 tools, 1 prompt, 2 resource templates
 ```
 
 A version that moved and a `build_id` that did not means you are reading a config, not a process.
@@ -261,7 +266,7 @@ dependency in a temp directory that will be deleted, and `npm update` cannot hel
 | Two machines with one config run different builds | [Silent version float](#silent-version-float): compare `build_id` |
 | `bantamkit_status` still shows the old version after an update | The host has not reconnected; restart the server |
 | Recall finds nothing, or the wrong store | Set `BANTAMKIT_MEMORY_DIR`; the reply names the store it searched |
-| `malformed fact file …` | A hand-edited fact has a bare non-string field; see [Sharing a store](#sharing-a-store-with-the-python-server) |
+| `malformed fact file …` | A hand-edited fact has a bare non-string field; see [Where the Python and Node servers differ](#where-the-python-and-node-servers-differ) |
 | `AssetNotFound: no assets directory found; set BANTAMKIT_ASSETS` | See [The asset pack](#the-asset-pack) |
 
 ## Configuration
@@ -381,9 +386,12 @@ the pack ships whole — 91 files / 238,751 bytes on 2026-09-15 — or `assets_d
 3. `<repo>/assets/` — two levels above `dist/`, for a dev checkout with nothing vendored.
 4. Otherwise `AssetNotFound: no assets directory found; set BANTAMKIT_ASSETS`.
 
-## Sharing a store with the Python server
+## Where the Python and Node servers differ
 
-Both servers read and write the same memory store; byte-compatibility is the product.
+Both servers read and write the same on-disk store; byte-compatibility is the product. Every
+feature lands in both in one change, and a conformance case compares their answers. Differences
+are deliberate and each is ruled in the
+[divergence table](https://github.com/Ink01101011/bantamkit/blob/main/docs/porting.md#where-the-two-runtimes-deliberately-differ):
 
 - **Concurrent writes are safe for the memory store and lossy for the checkpoint, in both
   runtimes.** `index.md` is derived from `facts/`, so the last writer re-enumerates everything

package/assets/tools/shiftwork_plan.json

@@ -0,0 +1,25 @@
+{
+  "name": "shiftwork_plan",
+  "description": "Shift-work plan: read-only batch view of a checkpoint — which units its `depends_on` graph permits to run in parallel. Answers `{\"result\": \"plan\", \"batches\", \"ready\", \"sequence\", \"width\", \"cursor\"}`: `ready` is `batches[0]`, the units dispatchable right now, and `width` is the largest batch length, the widest fan-out. Units with status `done` or `dropped` are satisfied — dropped from the graph, and edges pointing at them treated as already resolved; `todo`, `in_progress` and `blocked` stay in it. Every unit has priority 0, because the checkpoint schema has no priority field, so order inside a batch is `plan.units` order. Same refusal sentences as `work_plan` for a duplicate id, an unknown dependency or a cycle, and the same refusals `shiftwork_status` gives for a checkpoint it cannot read. It reports what the dependency graph permits; it does not move the cursor, which is echoed unchanged so the single-pointer contract and the batch view can be read side by side. An orchestrator stays responsible for what it actually dispatches: `depends_on` encodes logical order, not file contention. Never mutates.",
+  "surfaces": [
+    "mcp"
+  ],
+  "parameters": {
+    "properties": {
+      "checkpoint": {
+        "title": "Checkpoint",
+        "type": "string"
+      }
+    },
+    "required": [
+      "checkpoint"
+    ],
+    "type": "object",
+    "title": "shiftwork_planArguments"
+  },
+  "output_schema": {
+    "type": "object",
+    "additionalProperties": true,
+    "title": "shiftwork_planDictOutput"
+  }
+}

package/assets/tools/work_plan.json

@@ -0,0 +1,49 @@
+{
+  "name": "work_plan",
+  "description": "Work plan: turn a dependency graph into the batches that may run in parallel. Takes `nodes`, each `{id, depends_on, priority}` — `priority` defaults to 0 — and answers `{\"result\": \"plan\", \"batches\", \"sequence\", \"width\"}`: batch k holds every node whose dependencies all appear in batches below k, `sequence` is those batches flattened in order, and `width` is the largest batch length — the widest fan-out, which is the number an orchestrator needs to decide whether it can afford the batch. Order inside a batch is priority descending, then the order the nodes were given; both halves are contract, because determinism inside a batch is what two implementations are held to. Empty `nodes` is an ANSWER, not a refusal: no batches, no sequence, width 0. Three refusals, checked in this order and one sentence each: `duplicate node id <id>`, `node <id> depends on <dep>, which no node declares`, and `the graph has a cycle: <a> -> <b> -> <a>`. It reports what the graph permits and decides nothing about what may actually be dispatched together — `depends_on` encodes logical order, not file contention, so a batch this tool calls parallel may still hold work that writes one file. Pure computation over the nodes it was handed: it opens no file and takes no path. Never mutates.",
+  "surfaces": [
+    "mcp"
+  ],
+  "parameters": {
+    "properties": {
+      "nodes": {
+        "title": "Nodes",
+        "type": "array",
+        "items": {
+          "type": "object",
+          "properties": {
+            "id": {
+              "type": "string",
+              "description": "The node's identifier, unique across `nodes`"
+            },
+            "depends_on": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              },
+              "description": "Ids this node waits for; every one of them must be declared by some node"
+            },
+            "priority": {
+              "type": "integer",
+              "description": "Tie-break inside a batch, descending. Optional; 0 when absent"
+            }
+          },
+          "required": [
+            "id",
+            "depends_on"
+          ]
+        }
+      }
+    },
+    "required": [
+      "nodes"
+    ],
+    "type": "object",
+    "title": "work_planArguments"
+  },
+  "output_schema": {
+    "type": "object",
+    "additionalProperties": true,
+    "title": "work_planDictOutput"
+  }
+}

package/dist/eventlog.js

@@ -55,8 +55,8 @@
  * notice — the failure mode a diagnostic can least afford.
  */
 import { appendFileSync, mkdirSync, renameSync, statSync } from 'node:fs';
-import { cmpCodepoint, osErrorClassName, pyExists, PyOSError, pyJoin, pyName, pyParent, pyParents } from './memory/pyfs.js';
-import { ensureBantamkitGitignore } from './memory/store.js';
+import { cmpCodepoint, osErrorClassName, pyExists, PyOSError, pyJoin, pyName, pyParent } from './memory/pyfs.js';
+import { bantamkitDirFor, ensureBantamkitGitignore } from './memory/store.js';
 /**
  * Environment switch. Unset or `off`/`0`/`false`/`no`/empty -> disabled. `on`/`1`/`true`/
  * `yes` -> the default file inside the memory store. Anything else is taken as the literal
@@ -254,13 +254,12 @@ export class EventLog {
         // USER RULING #2 (J51-8b): the ignore file is written only when THIS call is what
         // creates `.bantamkit`, so existence has to be checked BEFORE the mkdir below -- after
         // it, the directory unconditionally exists and the question is unanswerable.
-        let bantamkitDir = null;
-        for (const parent of pyParents(path)) {
-            if (pyName(parent) === '.bantamkit') {
-                bantamkitDir = parent;
-                break;
-            }
-        }
+        //
+        // J54-3: the walk moved into `bantamkitDirFor` beside the writer it feeds, so the two
+        // creators in this runtime ask the same question in the same words rather than keeping a
+        // copy each. The answer here is unchanged -- a log file is never itself named
+        // `.bantamkit`, so self-or-ancestors and ancestors give the same directory.
+        const bantamkitDir = bantamkitDirFor(path);
         const bantamkitDirExistedBefore = bantamkitDir !== null && pyExists(bantamkitDir);
         // `pyParent` and not `node:path`'s `dirname`: this module is reached from a Windows
         // host through the same code, and the reference's `Path(...).parent` is the spelling

package/dist/hostinstall.js

@@ -37,6 +37,7 @@ import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { currentInstall, Undetermined } from './mcp/identity.js';
+import { bantamkitDirFor, ensureBantamkitGitignore } from './memory/store.js';
 import { compareVersions, keptCli, keptManifest, keptPrefix, PACKAGE, runInstaller, shlexJoin } from './npminstall.js';
 import { dumpJson, fromJs } from './pyjson.js';
 export { keptCli, keptPrefix };
@@ -319,7 +320,28 @@ export function thisCommand(options = {}) {
     }
     const command = ['npm', 'install', '--prefix', prefix, `${PACKAGE}@${version}`];
     const rendered = shlexJoin(command);
+    // THE THIRD `.bantamkit` CREATOR (J54-3), and the one that creates the most of it: npm makes
+    // a missing `--prefix` itself, so this line — not `MemoryStore`, not `EventLog` — is what
+    // brings `<homedir>/.bantamkit` into existence on a machine that has never saved a memory.
+    // Measured on the machine this was found on: 28 MB of install tree under a `~/.bantamkit`
+    // with no `.gitignore`, every byte of it untracked in a `$HOME` that is a git repository.
+    //
+    // Checked BEFORE npm runs, per user ruling #2, for the reason both other creators check it
+    // before their own mkdir: afterwards the directory exists either way and the question
+    // "did THIS call create it" is unanswerable. A `~/.bantamkit` that was already there —
+    // holding an older kept install, a memory store, or an ignore file the operator deleted on
+    // purpose — is left exactly as it is.
+    const bantamkitDir = bantamkitDirFor(prefix);
+    const bantamkitDirExistedBefore = bantamkitDir !== null && existsSync(bantamkitDir);
     const [code, output] = (options.installer ?? runInstaller)(command);
+    // BEFORE THE REFUSALS, AND THAT ORDER IS MEASURED, not tidy. A `npm install --prefix` that
+    // FAILS still leaves the prefix behind: measured 2026-09-18 with `npm_config_offline=true`
+    // against an empty cache — exit 1, and `<home>/.bantamkit/mcp` there afterwards. A refusal
+    // that returned first would leave exactly the directory this closes over: made by bantamkit's
+    // own command, holding nothing anybody asked for, and visible to git. The helper never
+    // creates `bantamkitDir` itself, so an installer that made nothing writes nothing here.
+    if (bantamkitDir !== null)
+        ensureBantamkitGitignore(bantamkitDir, !bantamkitDirExistedBefore);
     const refused = `could not make the kept install at ${prefix}, so no host configuration was changed: ${rendered} exited ${code}`;
     if (code !== 0)
         throw new InstallError(`${refused}: ${lastLine(output)}`);

package/dist/memory/store.d.ts

@@ -33,6 +33,14 @@ export declare const BANTAMKIT_GITIGNORE_TEXT: string;
  * a `.bantamkit` that git can see (or ignore one it should not), which is the whole bug this
  * closes.
  *
+ * THE CREATORS, ENUMERATED (J54-3), because "anything else" is how one got missed: in THIS
+ * runtime there are exactly three — `MemoryStore.ensureDirs`, `EventLog`'s append-time
+ * `mkdirSync`, and `hostinstall.thisCommand`, where `--install` from an `npx` cache has npm
+ * create `<homedir>/.bantamkit/mcp` (npm makes a missing `--prefix` itself). The first two ask
+ * `bantamkitDirFor` which directory the decision is about rather than assuming the root's
+ * parent is it; the third is the one the reference does not have at all, because the offline
+ * install is Node-only by user ruling. `docs/porting.md` carries the row.
+ *
  * NEVER REWRITES. A `.gitignore` that already exists -- whatever its bytes -- is left
  * exactly as it is, kept as a second guard even when `created` is `true`: an operator who
  * deleted it to commit the directory keeps that decision, and this never diffs its own
@@ -48,6 +56,27 @@ export declare const BANTAMKIT_GITIGNORE_TEXT: string;
  * bring `.bantamkit` into existence early.
  */
 export declare function ensureBantamkitGitignore(directory: string, created: boolean): void;
+/**
+ * The `.bantamkit` directory a recursive mkdir of `path` would create or fill, or `null` when
+ * there is none: `path` itself if it is named `.bantamkit`, otherwise its nearest ancestor
+ * that is. `runtime-py/src/bantamkit/memory/store.py`'s `bantamkit_dir_for` is the reference.
+ *
+ * WHY A WALK AND NOT `pyParent(path)` (J54-3). Every creator has to hand
+ * `ensureBantamkitGitignore` the directory the decision is ABOUT, and the parent is the right
+ * answer for exactly one shape of path, `<x>/.bantamkit/memory`. A store rooted AT the
+ * `.bantamkit` directory (`--store ~/.bantamkit`) or nested deeper under it creates a
+ * `.bantamkit` whose gitignore decision was taken about the wrong directory — so no decision
+ * was taken at all, and git could see the whole tree. MEASURED, not hypothetical: `~/.bantamkit`
+ * on the machine this was found on holds an empty `facts/` and `archive/` beside `memory/`,
+ * left by a store once rooted at it, and no `.gitignore`.
+ *
+ * NEAREST AND NOT OUTERMOST, which is the choice `EventLog`'s append already made and this
+ * function now carries for both creators.
+ *
+ * READ-ONLY. It looks at names, never at the filesystem, so it is equally valid before or after
+ * the mkdir — but `created` is answered by checking THIS path's existence BEFORE.
+ */
+export declare function bantamkitDirFor(path: string): string | null;
 /** `sorted(VALID_TYPES)` is what the error message interpolates, so the order is load-bearing. */
 export declare const VALID_TYPES: readonly ["feedback", "project", "reference", "user"];
 /**

package/dist/memory/store.js

@@ -42,7 +42,7 @@ import { basename } from 'node:path';
 import { BantamError } from '../errors.js';
 import { formatFact, parseFrontmatter, pySplit, pyStrip, todayLocal } from './factfile.js';
 import { PyScalar } from './pyyaml.js';
-import { asPyOSError, cmpCodepoint, matchesMd, pyExists, pyJoin, pyLexists, pyMkdirParents, pyMtimeDate, pyName, pyParent, pyReadText, pyReplace, pyScandirNames, pySuffix, pyUnlink, pyWithSuffix, pyWriteText, PyOSError, sortedPathNames, } from './pyfs.js';
+import { asPyOSError, cmpCodepoint, matchesMd, pyExists, pyJoin, pyLexists, pyMkdirParents, pyMtimeDate, pyName, pyParent, pyParents, pyReadText, pyReplace, pyScandirNames, pySuffix, pyUnlink, pyWithSuffix, pyWriteText, PyOSError, sortedPathNames, } from './pyfs.js';
 /**
  * The exact bytes written into a `.bantamkit/.gitignore` the first time such a directory is
  * brought into existence (user ruling 2026-09-15, `.shiftwork/notes-job51/P0-probes.md`).
@@ -76,6 +76,14 @@ export const BANTAMKIT_GITIGNORE_TEXT = '# Created by bantamkit: this directory
  * a `.bantamkit` that git can see (or ignore one it should not), which is the whole bug this
  * closes.
  *
+ * THE CREATORS, ENUMERATED (J54-3), because "anything else" is how one got missed: in THIS
+ * runtime there are exactly three — `MemoryStore.ensureDirs`, `EventLog`'s append-time
+ * `mkdirSync`, and `hostinstall.thisCommand`, where `--install` from an `npx` cache has npm
+ * create `<homedir>/.bantamkit/mcp` (npm makes a missing `--prefix` itself). The first two ask
+ * `bantamkitDirFor` which directory the decision is about rather than assuming the root's
+ * parent is it; the third is the one the reference does not have at all, because the offline
+ * install is Node-only by user ruling. `docs/porting.md` carries the row.
+ *
  * NEVER REWRITES. A `.gitignore` that already exists -- whatever its bytes -- is left
  * exactly as it is, kept as a second guard even when `created` is `true`: an operator who
  * deleted it to commit the directory keeps that decision, and this never diffs its own
@@ -103,6 +111,33 @@ export function ensureBantamkitGitignore(directory, created) {
         /* best-effort: a missing ignore file is not worth a lost fact */
     }
 }
+/**
+ * The `.bantamkit` directory a recursive mkdir of `path` would create or fill, or `null` when
+ * there is none: `path` itself if it is named `.bantamkit`, otherwise its nearest ancestor
+ * that is. `runtime-py/src/bantamkit/memory/store.py`'s `bantamkit_dir_for` is the reference.
+ *
+ * WHY A WALK AND NOT `pyParent(path)` (J54-3). Every creator has to hand
+ * `ensureBantamkitGitignore` the directory the decision is ABOUT, and the parent is the right
+ * answer for exactly one shape of path, `<x>/.bantamkit/memory`. A store rooted AT the
+ * `.bantamkit` directory (`--store ~/.bantamkit`) or nested deeper under it creates a
+ * `.bantamkit` whose gitignore decision was taken about the wrong directory — so no decision
+ * was taken at all, and git could see the whole tree. MEASURED, not hypothetical: `~/.bantamkit`
+ * on the machine this was found on holds an empty `facts/` and `archive/` beside `memory/`,
+ * left by a store once rooted at it, and no `.gitignore`.
+ *
+ * NEAREST AND NOT OUTERMOST, which is the choice `EventLog`'s append already made and this
+ * function now carries for both creators.
+ *
+ * READ-ONLY. It looks at names, never at the filesystem, so it is equally valid before or after
+ * the mkdir — but `created` is answered by checking THIS path's existence BEFORE.
+ */
+export function bantamkitDirFor(path) {
+    for (const candidate of [path, ...pyParents(path)]) {
+        if (pyName(candidate) === '.bantamkit')
+            return candidate;
+    }
+    return null;
+}
 /** `sorted(VALID_TYPES)` is what the error message interpolates, so the order is load-bearing. */
 export const VALID_TYPES = ['feedback', 'project', 'reference', 'user'];
 /**
@@ -598,8 +633,13 @@ export class MemoryStore {
         // Checked BEFORE the mkdir below, per user ruling #2: this is the one moment that can
         // tell whether `.bantamkit` already existed. After the mkdir it unconditionally exists
         // either way, so the answer has to be captured now or not at all.
-        const bantamkitDir = pyParent(this.root);
-        const bantamkitDirExistedBefore = pyExists(bantamkitDir);
+        //
+        // J54-3: `bantamkitDirFor`, not `pyParent`. The mkdirs below create every missing
+        // component of `this.root` — a root that IS the `.bantamkit` directory, or one nested
+        // deeper under it, brought a `.bantamkit` into existence while the decision was being
+        // taken about some other directory, which meant no decision at all.
+        const bantamkitDir = bantamkitDirFor(this.root);
+        const bantamkitDirExistedBefore = bantamkitDir !== null && pyExists(bantamkitDir);
         try {
             pyMkdirParents(pyJoin(this.root, 'facts'));
             pyMkdirParents(pyJoin(this.root, 'archive'));
@@ -610,7 +650,8 @@ export class MemoryStore {
             throw new MemoryValidationError(`memory store could not be created: ${this.root}; the directory is not` +
                 ' there and this filesystem would not make it, so nothing was written');
         }
-        ensureBantamkitGitignore(bantamkitDir, !bantamkitDirExistedBefore);
+        if (bantamkitDir !== null)
+            ensureBantamkitGitignore(bantamkitDir, !bantamkitDirExistedBefore);
     }
     // ---- ops ----
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bantamkit-mcp",
-  "version": "0.34.2",
+  "version": "0.35.0",
   "description": "Memory MCP server for Claude Code, Cursor, VS Code Copilot and Claude Desktop: per-person memory, JSON Schema validation, shift-work tools. Pure Node; install once with npx, run offline.",
   "keywords": [
     "mcp",