bantamkit-mcp 0.31.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

@@ -25,6 +25,8 @@
  * lines carry a `[project] ` tag that the `--store` form never emits. A port validated
  * against only one of them ships a string the deployment never produces.
  */
+import { realpathSync } from 'node:fs';
+import { resolve } from 'node:path';
 import { BantamError } from '../errors.js';
 import { pyStrip } from './factfile.js';
 import { countFacts, loadGrants, MEMORY_DIR_ENV, PROJECT_STORE, resolveProjectStore, } from './layers.js';
@@ -60,6 +62,55 @@ export function normalizeName(name) {
 export function profileStore() {
     return pyJoin(pyHome(), ...PROJECT_STORE);
 }
+/**
+ * Whether two paths name ONE directory, symlinks and `/var` vs `/private/var` included.
+ *
+ * Port of `_same_directory` (`runtime-py/src/bantamkit/memory/component.py`, J47-1,
+ * 0844ccb). Realpath, not string equality, and that distinction is measured rather than
+ * tidy: on macOS the walk up from a cwd under `/var` returns `/private/var/...` while
+ * `pyHome()` returns `/var/...`, so two spellings of one directory compare unequal as
+ * strings. The Stop hook's `samePath` (`tools/hooks/bantamkit-hook.mjs`) compares the same
+ * two roots the same way and for the same reason — it carried the identical defect, and
+ * J47-7 (`a109f99`) brought it to the same `realpathSync.native`, following this function
+ * rather than leading it. When the resolution itself
+ * fails, an absolute-path comparison is the honest fallback: it can only under-report a
+ * match, never invent one.
+ *
+ * AMENDED 2026-09-11 (J47-3B). The paragraph above stands as the reason this function
+ * resolves rather than compares strings, and the fallback's behaviour is unchanged. Two
+ * things it says are now known to be wrong about `fs.realpathSync` in particular, and
+ * measured: (1) it is NOT the twin of `os.path.realpath`. `realpathSync` hands its argument
+ * to `path.resolve` before it resolves anything, and `path.resolve` pops `..` LEXICALLY —
+ * before the symlink in front of it is followed. `os.path.realpath` and the kernel pop it
+ * AFTER. So a `HOME` spelled `<bed>/link/..`, where `link -> <bed>/deep/real`, is
+ * `<bed>/deep` to the reference and `<bed>` to Node: `realpathSync` then threw ENOENT on a
+ * directory that is there, the fallback under-reported, and `layered` bound one directory as
+ * two layers — the 2026-09-10 self-merge, still live on this side until now. (2) "it can
+ * only under-report a match, never invent one" was offered as reassurance, and
+ * under-reporting is the DANGEROUS direction here: a missed match IS the duplicate layer.
+ *
+ * The mechanism is now `realpathSync.native` — libuv's `uv_fs_realpath`, i.e. the platform's
+ * own `realpath(3)` / `GetFinalPathNameByHandle` — chosen because it pops `..` in the
+ * kernel's order and therefore agrees with `os.path.realpath` byte for byte on that bed,
+ * because it keeps the macOS `/var` vs `/private/var` resolution the original was written
+ * for, and because it adds no path arithmetic of this port's own. `statSync` identity
+ * (`dev` + `ino`) was the other candidate and was not taken: `ino` is not dependable on
+ * every Windows filesystem, and this runtime has to answer the same on Windows.
+ *
+ * The fallback stays `resolve(a) === resolve(b)`, and the under-report it can still produce
+ * is provably harmless where `layered` calls this: the native call throws only for a path
+ * that is not on disk, and `binding.path` always is — `layered` constructs that store, which
+ * creates it, before the guard runs — so a throwing side is a directory that does not exist,
+ * and that cannot be the same directory as one that does.
+ */
+function sameDirectory(a, b) {
+    try {
+        return realpathSync.native(a) === realpathSync.native(b);
+    }
+    catch {
+        return resolve(a) === resolve(b);
+    }
+}
 /** The name a layer answers under: the PROJECT directory, not the store directory. */
 export function layerLabel(root) {
     if (pyName(pyParent(root)) === '.bantamkit')
@@ -72,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;
@@ -94,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);
@@ -110,11 +196,21 @@ export class Memory {
                 false,
             ]);
         }
-        mem.layers.push([
-            'profile',
-            new MemoryStore(profileStore(), { k, create: false, ...(today ? { today } : {}) }),
-            false,
-        ]);
+        // ONE DIRECTORY IS ONE LAYER. The walk above starts at the cwd and climbs, so a
+        // session with no `.bantamkit` anywhere above it resolves `~/.bantamkit/memory` —
+        // the profile store — as its PROJECT store. Binding that directory a second time
+        // gave `dream` the same store twice: every fact collided with itself, was merged
+        // into itself, and the "profile copy" that was archived was the same file. It
+        // archived 20 of 20 of the user's real facts on 2026-09-10. Such a session has one
+        // layer, and `dreamOutcome` already has a true thing to say about that.
+        const profileRoot = profileStore();
+        if (!sameDirectory(profileRoot, binding.path)) {
+            mem.layers.push([
+                'profile',
+                new MemoryStore(profileRoot, { k, create: false, ...(today ? { today } : {}) }),
+                false,
+            ]);
+        }
         return mem;
     }
     /** The labels, in order. `_layers` is private in the reference too; this is for the tests. */
@@ -505,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;
@@ -609,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/dist/shiftwork.d.ts

@@ -37,7 +37,10 @@ export declare function clockIn(checkpoint: string): PyValue;
  * `unitId` must name the cursor unit — the contract is execute-the-cursor (driver parity),
  * never pick-a-unit. When `job.roles` names the unit's role, `accounting.model` must be one
  * of that role's models, spelled exactly; a wrong or missing model is refused here, before
- * any mutation and before the accounting line. Mutations: set the unit's status, advance
+ * any mutation and before the accounting line. Extended 2026-09-11 (job47): so is a
+ * `job.roles` value for that role that is not a list of model identifiers — an unreadable
+ * declaration allows no model, and it is refused in the same place, by the same structured
+ * return, writing nothing. Mutations: set the unit's status, advance
  * `plan.cursor` to the first non-terminal unit in PLAN order (`depends_on` is ignored),
  * shallow-merge `handoffPatch` into `handoff`, push `historyEntry` onto the 5-entry ring.
  *

package/dist/shiftwork.js

@@ -39,7 +39,11 @@
  * therefore pinned as per-side literals in each runtime's own tests. The check runs at
  * validation time — after the cursor check, before the first mutation, and so before the
  * log-then-commit pair below — because a refusal taken after the append would leave an
- * orphan accounting line claiming a model that was rejected.
+ * orphan accounting line claiming a model that was rejected. J47-5: a role the map DOES
+ * name whose value is not a list of model identifiers is refused there too — an unreadable
+ * declaration allows no model, and the refusal is the same structured one, taken in the
+ * same place. That makes three refusal strings, not two, and the third is likewise a
+ * per-side literal.
  *
  * WHAT IS NOT PORTED, DELIBERATELY. The `depends_on` field is ignored on cursor advance
  * (v1-linear, the Python module's own ruling), there is no lock (the MCP topology has one
@@ -252,6 +256,25 @@ function pyFormat(value) {
  * string and the sentence says so. Reachable, and therefore measured: `BANTAMKIT_ASSETS` is
  * honoured by both runtimes, so the tests and the conformance corpus drive this branch
  * through a pack whose schema has lost `minItems`.
+ *
+ * AND A DECLARATION THIS CODE CANNOT READ IS NOT A LICENCE (J47-4, ported here as J47-5).
+ * The same ruling, one step further out: a role the map names is constrained by what it
+ * NAMES, and a value that is not a list of model identifiers names nothing, so it allows
+ * nothing. This port failed open five ways and mangled the declaration two more. MEASURED
+ * end to end under a pack whose `job.roles.additionalProperties` is `true`, with
+ * `model: 'haiku'`: a string, a dict, a number, a null and a bool all came back
+ * `{"result":"ok"}` with the status set, the cursor advanced and an accounting line
+ * written — the clock-out COMPLETED — while `[5]` and `['ok', null]` refused with the
+ * unreadable value rendered into the sentence as `5` and `ok, None`. A list holding a
+ * non-string is the shape a bare kind test cannot catch, which is why the property is
+ * LIST OF STRINGS and not merely list; the reference raised `TypeError: sequence item 0`
+ * on exactly that input. Fail CLOSED, through the same structured `_error` return, saying
+ * only what is true — the declaration cannot be read, therefore no model is allowed —
+ * naming no type (a Python type name would not port: `int` against `number`) and
+ * rendering no part of the value. ONE sentence for both accounting shapes: which model
+ * was reported cannot matter when the declaration that would judge it is unreadable.
+ * `[]` is untouched by this — an empty list IS a list of model identifiers and keeps the
+ * sentence J46-10 pinned.
  */
 function modelRefusal(document, unitId, unit, accounting) {
     const role = text(field(unit, 'role'));
@@ -259,8 +282,16 @@ function modelRefusal(document, unitId, unit, accounting) {
     const allowed = roles === undefined || roles.t !== 'dict' ? undefined : roles.v.get(role);
     // `role not in roles`. The `t !== 'list'` arm is a TYPE guard and not a policy: the schema
     // pins the value to an array, so the only way past it is a document no read would accept.
-    if (allowed === undefined || allowed.t !== 'list')
+    // AMENDED 2026-09-11 (J47-5): the two lines above stand as written and are now FALSE as a
+    // description of this code. A document no read would accept is exactly what a shared asset
+    // drifting produces, the arm answered `unconstrained` for every such document and the
+    // clock-out completed, and `t === 'list'` was never the property anyway — `['ok', null]`
+    // passed the kind test and mangled `None` into the sentence. The arm below is a POLICY.
+    if (allowed === undefined)
         return null;
+    if (allowed.t !== 'list' || !allowed.v.every((model) => model.t === 'str')) {
+        return `unit ${unitId} in role ${role} cannot clock out: job.roles.${role} is not a list of model identifiers, so it allows no model`;
+    }
     const names = allowed.v.map((model) => pyFormat(model)).join(', ');
     const offered = asPatch(accounting).get('model');
     if (offered === undefined || offered.t === 'null') {
@@ -280,7 +311,10 @@ function modelRefusal(document, unitId, unit, accounting) {
  * `unitId` must name the cursor unit — the contract is execute-the-cursor (driver parity),
  * never pick-a-unit. When `job.roles` names the unit's role, `accounting.model` must be one
  * of that role's models, spelled exactly; a wrong or missing model is refused here, before
- * any mutation and before the accounting line. Mutations: set the unit's status, advance
+ * any mutation and before the accounting line. Extended 2026-09-11 (job47): so is a
+ * `job.roles` value for that role that is not a list of model identifiers — an unreadable
+ * declaration allows no model, and it is refused in the same place, by the same structured
+ * return, writing nothing. Mutations: set the unit's status, advance
  * `plan.cursor` to the first non-terminal unit in PLAN order (`depends_on` is ignored),
  * shallow-merge `handoffPatch` into `handoff`, push `historyEntry` onto the 5-entry ring.
  *

package/package.json

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