bantamkit-mcp 0.32.0 → 0.32.1

package/dist/cli.js

@@ -80,7 +80,7 @@ import { packFileCount } from './mcp/identity.js';
 import { buildServer } from './mcp/server.js';
 import { RawStdioTransport } from './mcp/transport.js';
 import { ArgumentTypeError, ArgvError, formatHelp, formatUsageBlock, HelpRequested, helpWidth, parseArgs as parseWithSpec, pyIntStrict, } from './pyargparse.js';
-import { pyRepr } from './memory/pyfs.js';
+import { pyJoin, PyOSError, pyRepr, pyStatIsDir } from './memory/pyfs.js';
 import { HOSTS, install as installHost, InstallError, thisCommand } from './hostinstall.js';
 import { runUpdate } from './selfupdate.js';
 import { statusLine } from './statusline.js';
@@ -330,10 +330,86 @@ function buildMemory(options) {
     if (options.store !== null) {
         if (options.store === '')
             throw new Refusal('--store requires a non-empty path');
+        checkStoreFlag(options.store);
         return new Memory(options.store, shared);
     }
     return Memory.layered(options.start, shared);
 }
+/**
+ * `--store` may name a store that is missing, never one that is not a store.
+ *
+ * THIS CHECK IS RESTORED, NOT INVENTED, and the distinction is the point. Until the project
+ * layer was built lazily there WAS a `--store` validation, and it was entirely accidental: the
+ * constructor ran `pyMkdirParents`, so a `--store` pointing at a regular file or at a path
+ * under a directory that does not exist took the process down with a `PyOSError` stack out of
+ * `pyfs`. The reference's `test_statusline.py::
+ * test_the_flag_returns_before_anything_a_server_would_touch` depends on it — it arms
+ * `--store <a regular file>` as a trap and shows `--statusline` walking past it — and a lazy
+ * layer disarms the trap by making that same argv exit 0. The honest way to keep that test
+ * true is to mean the refusal on purpose.
+ *
+ * IT IS `layers.pinnedStore`'s CHECK MINUS ONE ARM, and the missing arm is deliberate and
+ * measured. The pin refuses a path that is not there ("nothing was created"); this flag does
+ * NOT, and must not, for two reasons that are both already pinned elsewhere in this
+ * repository:
+ *
+ * - The sibling CLI's identical flag is contracted to CREATE one. `tools/conformance/suites/
+ *   memorycli.mjs` carries `status-creates-a-missing-store`, `--store {BED}/nowhere` over an
+ *   empty bed, whose whole job is to say the two runtimes create the same two directories
+ *   there. Refusing a missing `--store` here would put two flags of the same name, in two
+ *   programs of the same product, in direct contradiction.
+ * - "Missing" is no longer a broken state anywhere in this program. The walk designates a
+ *   project store without creating it, and the first save brings it into existence or refuses
+ *   by name (`store.ensureDirs`). A `--store` at a path that is not there is that same
+ *   designated state, reached by being told instead of by searching. MEASURED on the reference
+ *   side: requiring existence reddened 14 tests that have nothing to do with this defect —
+ *   `test_tool_manifest.py` ×7, `test_mcpserver.py` ×6, `test_mcp_endpoint.py` — every one of
+ *   them a fixture naming a store under `tmp_path` it never made, because that is what this
+ *   flag has always meant.
+ *
+ * What is left is the arm the accident actually covered and the only one it covered: a
+ * `--store` that names something which EXISTS and is NOT A DIRECTORY. That is not a store and
+ * never becomes one — `mkdir` under it is ENOTDIR on both runtimes and on every platform, the
+ * one row of the errno table where they already agree — so it is refused here, by name, before
+ * a transport exists.
+ *
+ * `FileNotFoundError` and not an errno comparison: the absent case is selected by the exception
+ * CPython raises for it, and `pyfs`' `PyOSError` carries that class as its `name`. Every other
+ * `stat` failure — a permission wall on the parent, a symlink loop — is a real fault about a
+ * path the operator named, and it keeps the pin's sentence.
+ *
+ * `pyStatIsDir` rather than an `existsSync`/`isDirectory` pair, and that too is `pinnedStore`'s
+ * reasoning: a predicate that swallows `PermissionError` and answers false would report an
+ * operator's real store as a typo. A single named path gets the accurate reason.
+ *
+ * `Refusal` and not `MemoryValidationError`, so that both halves of this flag's refusal family
+ * read the same way on the terminal: `--store requires a non-empty path` is already bare on
+ * stderr at exit 1, and the reference spells both as `SystemExit`.
+ */
+function checkStoreFlag(raw) {
+    // NOT `pyExpanduser`, unlike the pin. `new Memory(store, ...)` builds the root from this
+    // string verbatim, so expanding here would check one path and serve another: `--store ~/x`
+    // left unexpanded by the shell would pass a check against the home directory and then build
+    // a store in a directory literally named `~`. The check must stat the path the store is
+    // going to be. `pyJoin` of the one argument is `Path(raw)`: the same normalisation
+    // `MemoryStore` applies to its root, so the path this stats and the path it names in a
+    // refusal are the path the store would have used.
+    const store = pyJoin(raw);
+    let isDir;
+    try {
+        isDir = pyStatIsDir(store);
+    }
+    catch (e) {
+        if (!(e instanceof PyOSError))
+            throw e;
+        // designated, not broken: the first save makes it or refuses by name
+        if (e.name === 'FileNotFoundError')
+            return;
+        throw new Refusal(`--store is unreachable: ${store}: ${e.strerror}; nothing was created`);
+    }
+    if (!isDir)
+        throw new Refusal(`--store is not a directory: ${store}`);
+}
 /**
  * The version this build declares — the same bytes npm packs the tarball from.
  *

package/dist/memory/component.d.ts

@@ -128,10 +128,14 @@ export declare class Memory {
     private readonly layers;
     private showLayers;
     /**
-     * How this store came to be the store, captured once. It cannot be re-derived later: the
-     * constructor above has already made the directory, so a store that was only DESIGNATED a
-     * moment ago is indistinguishable on disk from one that was found empty. `null` means the
-     * caller named the path outright and no resolution happened to report.
+     * How this store came to be the store, captured once. It is still captured here and not
+     * re-derived later, but the reason has changed with the constructor below and the old one is
+     * recorded rather than deleted: it WAS that the constructor had already made the directory,
+     * so a store that was only DESIGNATED a moment ago was indistinguishable on disk from one
+     * that was found empty. That complaint is now discharged — nothing is created — and the
+     * binding is kept because it also carries WHY this path (`origin`, `searchedFrom`), which no
+     * amount of looking at the disk recovers. `null` means the caller named the path outright
+     * and no resolution happened to report.
      */
     private readonly binding;
     constructor(store: string, options?: MemoryOptions, binding?: StoreBinding | null);
@@ -140,8 +144,15 @@ export declare class Memory {
      *
      * `resolveProjectStore` rather than `discoverProjectStore`: the path both return is the
      * same path, but only the binding carries WHY it is that path and whether it holds
-     * anything — and `recall` cannot recover either fact afterwards, because constructing the
-     * store creates the directory.
+     * anything — and `recall` cannot recover either fact afterwards.
+     *
+     * AMENDMENT 2026-09-12 (job48, J48-2), correcting the reason the clause above used to give
+     * and not the clause itself. WAS: "because constructing the store creates the directory."
+     * NOW that is false — the project layer is built `create: false` (see the constructor) and
+     * constructing it creates nothing. The binding is still the only carrier of WHY, because
+     * `origin` and `searchedFrom` were never on the disk to begin with; what the disk has
+     * stopped being able to answer is merely "was this empty or brand new", which it now answers
+     * correctly for the first time.
      */
     static layered(start?: string | null, options?: MemoryOptions): Memory;
     /** The labels, in order. `_layers` is private in the reference too; this is for the tests. */
@@ -280,6 +291,12 @@ export declare class Memory {
      * at construction and has been saved to since really can answer. The DIAGNOSIS is keyed on
      * the binding, because "designated" stops being visible on disk the moment `MemoryStore`
      * creates the directory.
+     *
+     * AMENDMENT 2026-09-12 (job48, J48-2). The reason in the clause above no longer holds and
+     * the keying does: the project layer is built `create: false`, so a designated store IS now
+     * distinguishable on disk — it is absent. The DIAGNOSIS still keys on the binding because
+     * only the binding carries `origin` and `searchedFrom`, which the disk never held, and
+     * because an absent directory and an emptied one must not be told apart by a race.
      */
     private nothingToReport;
     /**

package/dist/memory/component.js

@@ -123,17 +123,45 @@ export class Memory {
     layers;
     showLayers = false;
     /**
-     * How this store came to be the store, captured once. It cannot be re-derived later: the
-     * constructor above has already made the directory, so a store that was only DESIGNATED a
-     * moment ago is indistinguishable on disk from one that was found empty. `null` means the
-     * caller named the path outright and no resolution happened to report.
+     * How this store came to be the store, captured once. It is still captured here and not
+     * re-derived later, but the reason has changed with the constructor below and the old one is
+     * recorded rather than deleted: it WAS that the constructor had already made the directory,
+     * so a store that was only DESIGNATED a moment ago was indistinguishable on disk from one
+     * that was found empty. That complaint is now discharged — nothing is created — and the
+     * binding is kept because it also carries WHY this path (`origin`, `searchedFrom`), which no
+     * amount of looking at the disk recovers. `null` means the caller named the path outright
+     * and no resolution happened to report.
      */
     binding;
     constructor(store, options = {}, binding = null) {
         const k = options.k ?? 3;
+        // `create: false`, AND IT IS THE WHOLE OF THE cwd-`/` FIX. This was the last eager layer —
+        // grants and the profile store have always been lazy — so a cwd that no directory can be
+        // created under was a STARTUP CRASH: every GUI MCP host launches its child with cwd `/`,
+        // measured live on this machine (`lsof -p <pid> -a -d cwd` on Claude Desktop and all four
+        // of its `bantamkit-mcp` children returns `/`), and the client saw only CONNECTION_CLOSED.
+        // Refusing at startup with a sentence was the other candidate and it is REFUTED by
+        // measurement: it leaves those same four processes dead, which is strictly worse than
+        // today. Built lazily, the server starts from `/`, binds `['project', 'profile']`, and
+        // answers out of the profile layer. The sentence still exists — it is what
+        // `MemoryStore.save`/`compact` say when a write actually needs the directory
+        // (`store.ensureDirs`).
+        //
+        // It is legal because every READ is already defined over an absent directory:
+        // `recall() -> []`, `archived() -> []`, `indexText() -> ''`. `facts()`' docstring says so
+        // outright, and `create: false` is one of the three callers it names.
+        //
+        // THE PRICE, stated rather than discovered: a bare server start in a perfectly good cwd no
+        // longer scatters `.bantamkit/memory/{facts,archive}` there before anything is saved. That
+        // moves TOWARD a stance this file already holds — see the binding comment above, and
+        // `cli.ts`'s bare-TTY guard.
+        //
+        // The reference is `component.py`'s `Memory.__init__` (job48, J48-1); this is the same
+        // change in the same place, and the two sentences below are spelled byte for byte.
         this.store = new MemoryStore(store, {
             indexBudget: options.indexBudget ?? DEFAULT_INDEX_BUDGET,
             k,
+            create: false,
             ...(options.today ? { today: options.today } : {}),
         });
         this.k = k;
@@ -145,8 +173,15 @@ export class Memory {
      *
      * `resolveProjectStore` rather than `discoverProjectStore`: the path both return is the
      * same path, but only the binding carries WHY it is that path and whether it holds
-     * anything — and `recall` cannot recover either fact afterwards, because constructing the
-     * store creates the directory.
+     * anything — and `recall` cannot recover either fact afterwards.
+     *
+     * AMENDMENT 2026-09-12 (job48, J48-2), correcting the reason the clause above used to give
+     * and not the clause itself. WAS: "because constructing the store creates the directory."
+     * NOW that is false — the project layer is built `create: false` (see the constructor) and
+     * constructing it creates nothing. The binding is still the only carrier of WHY, because
+     * `origin` and `searchedFrom` were never on the disk to begin with; what the disk has
+     * stopped being able to answer is merely "was this empty or brand new", which it now answers
+     * correctly for the first time.
      */
     static layered(start, options = {}) {
         const binding = resolveProjectStore(start);
@@ -566,6 +601,12 @@ export class Memory {
      * at construction and has been saved to since really can answer. The DIAGNOSIS is keyed on
      * the binding, because "designated" stops being visible on disk the moment `MemoryStore`
      * creates the directory.
+     *
+     * AMENDMENT 2026-09-12 (job48, J48-2). The reason in the clause above no longer holds and
+     * the keying does: the project layer is built `create: false`, so a designated store IS now
+     * distinguishable on disk — it is absent. The DIAGNOSIS still keys on the binding because
+     * only the binding carries `origin` and `searchedFrom`, which the disk never held, and
+     * because an absent directory and an emptied one must not be told apart by a race.
      */
     nothingToReport() {
         let status;
@@ -670,9 +711,19 @@ export class Memory {
             where = `The project store ${root} is empty.`;
         }
         else if (binding.state === 'designated') {
+            // AMENDED 2026-09-12 (job48, J48-2) because the sentence became FALSE, not because it
+            // read badly. WAS: "No memory store existed at or above <from>, so the empty <root> was
+            // created for this session." Under a lazily-built project layer nothing is created — the
+            // path is designated and stays absent until a save needs it — so the old sentence told
+            // an operator to go look for a directory that is not there. The new one borrows the
+            // pin's own closing clause, "nothing was created", because it is the same claim about
+            // the same thing, and it reuses the binding's existing `designated` vocabulary rather
+            // than minting a word for it. The remedy that follows — "otherwise save a memory to
+            // start this one" — is now literally true: the save is what brings the directory into
+            // existence. Byte for byte the reference's, `component.py`'s `_binding_diagnosis`.
             where =
-                `No memory store existed at or above ${binding.searchedFrom}, so the ` +
-                    `empty ${root} was created for this session.`;
+                `No memory store existed at or above ${binding.searchedFrom}, so ${root} ` +
+                    `was designated for this session; nothing was created there.`;
         }
         else if (binding.origin === 'pin') {
             where = `The project store ${root} is empty; ${MEMORY_DIR_ENV} pinned it.`;

package/dist/memory/store.d.ts

@@ -213,6 +213,35 @@ export declare class MemoryStore {
     readonly k: number;
     private readonly today;
     constructor(root: string, options?: MemoryStoreOptions);
+    /**
+     * Bring the store's directories into existence, or refuse the write that needs them.
+     *
+     * THE PROPERTY: a store that cannot be brought into existence cannot be written to, and the
+     * refusal names which directory and why. It is a refusal and not a crash because the only
+     * callers are the two WRITES (`save`, `compact`); every read is already defined over an
+     * absent directory — `facts()`' own docstring rules it, "AN ABSENT DIRECTORY IS `[]`, NOT AN
+     * ERROR" — which is what makes a lazily-built project layer legal at all.
+     *
+     * THE PREDICATE IS THE OUTCOME AND NEVER AN ERRNO, and that is measured rather than tidy.
+     * One cwd, `/`, gives CPython EROFS(30) at `/.bantamkit` and Node ENOENT(-2) at
+     * `/.bantamkit/memory/facts`, because Node's recursive mkdir does not pass EROFS through and
+     * stats the missing path instead — re-measured here at cwd `/`,
+     * `mkdirSync('/.bantamkit', {recursive: true})` is ENOENT(-2) where `mkdirSync('/.bantamkit')`
+     * is EROFS(-30); a `chmod 555` directory gives EACCES(13) on both; and on Linux `/` is a
+     * writable root owned by root, so the same cwd gives EACCES there. Three platforms, three
+     * numbers, one fact — the directory could not be made — so the `catch` is the whole of
+     * `PyOSError`, which is this runtime's `OSError`, and the sentence carries no errno. A fix
+     * keyed on the number would have been green on Linux CI and wrong on the machine the bug was
+     * reported from, and on THIS side it would additionally have been keyed on a number libuv
+     * invented rather than on the one the filesystem returned.
+     *
+     * THE SENTENCE NAMES `this.root` AND NOTHING DEEPER, for the same reason. The two runtimes
+     * fail at different components of the same path (`/.bantamkit` against
+     * `/.bantamkit/memory/facts`) and report different strerrors for it, so a sentence carrying
+     * the failing leaf, or that strerror, would be a divergence manufactured by mkdir's
+     * internals. `this.root` is the path the caller named and both sides agree on it, which is
+     * what lets one conformance case pin this line byte for byte.
+     */
     private ensureDirs;
     /**
      * Write a fact, or refuse it as a near-duplicate of one already here.

package/dist/memory/store.js

@@ -505,9 +505,46 @@ export class MemoryStore {
         if (options.create ?? true)
             this.ensureDirs();
     }
+    /**
+     * Bring the store's directories into existence, or refuse the write that needs them.
+     *
+     * THE PROPERTY: a store that cannot be brought into existence cannot be written to, and the
+     * refusal names which directory and why. It is a refusal and not a crash because the only
+     * callers are the two WRITES (`save`, `compact`); every read is already defined over an
+     * absent directory — `facts()`' own docstring rules it, "AN ABSENT DIRECTORY IS `[]`, NOT AN
+     * ERROR" — which is what makes a lazily-built project layer legal at all.
+     *
+     * THE PREDICATE IS THE OUTCOME AND NEVER AN ERRNO, and that is measured rather than tidy.
+     * One cwd, `/`, gives CPython EROFS(30) at `/.bantamkit` and Node ENOENT(-2) at
+     * `/.bantamkit/memory/facts`, because Node's recursive mkdir does not pass EROFS through and
+     * stats the missing path instead — re-measured here at cwd `/`,
+     * `mkdirSync('/.bantamkit', {recursive: true})` is ENOENT(-2) where `mkdirSync('/.bantamkit')`
+     * is EROFS(-30); a `chmod 555` directory gives EACCES(13) on both; and on Linux `/` is a
+     * writable root owned by root, so the same cwd gives EACCES there. Three platforms, three
+     * numbers, one fact — the directory could not be made — so the `catch` is the whole of
+     * `PyOSError`, which is this runtime's `OSError`, and the sentence carries no errno. A fix
+     * keyed on the number would have been green on Linux CI and wrong on the machine the bug was
+     * reported from, and on THIS side it would additionally have been keyed on a number libuv
+     * invented rather than on the one the filesystem returned.
+     *
+     * THE SENTENCE NAMES `this.root` AND NOTHING DEEPER, for the same reason. The two runtimes
+     * fail at different components of the same path (`/.bantamkit` against
+     * `/.bantamkit/memory/facts`) and report different strerrors for it, so a sentence carrying
+     * the failing leaf, or that strerror, would be a divergence manufactured by mkdir's
+     * internals. `this.root` is the path the caller named and both sides agree on it, which is
+     * what lets one conformance case pin this line byte for byte.
+     */
     ensureDirs() {
-        pyMkdirParents(pyJoin(this.root, 'facts'));
-        pyMkdirParents(pyJoin(this.root, 'archive'));
+        try {
+            pyMkdirParents(pyJoin(this.root, 'facts'));
+            pyMkdirParents(pyJoin(this.root, 'archive'));
+        }
+        catch (e) {
+            if (!(e instanceof PyOSError))
+                throw e;
+            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');
+        }
     }
     // ---- ops ----
     /**
@@ -742,6 +779,14 @@ export class MemoryStore {
      */
     compact(reserve = null) {
         const facts = this.facts();
+        // SECOND, NOT FIRST, and the order is the reference's own ruling kept intact: the listing
+        // still refuses an unreadable store before anything here moves a file. What this line adds
+        // is the other half of the same stance — this method WRITES (every `pyReplace` below lands
+        // in `archive/`, and `rebuildIndex` writes `index.md` into the root whether or not a single
+        // fact was archived), so a root that does not exist and cannot be made is refused here, by
+        // name, instead of surfacing as a `FileNotFoundError` out of the final write. `exist_ok`
+        // semantics make it free for every store that is already there.
+        this.ensureDirs();
         const sizes = new Map();
         for (const fact of facts) {
             sizes.set(pyHashKey(fact.name), Buffer.byteLength(this.indexLine(fact), 'utf8'));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bantamkit-mcp",
-  "version": "0.32.0",
+  "version": "0.32.1",
   "description": "bantamkit MCP server — pure Node, runnable with npx",
   "type": "module",
   "bin": {