bantamkit-mcp 0.32.1 → 0.34.0

package/dist/hostinstall.d.ts

@@ -1,3 +1,5 @@
+import { keptCli, keptPrefix } from './npminstall.js';
+export { keptCli, keptPrefix };
 /** The four hosts, in the order they print in `--help`. */
 export declare const HOSTS: readonly ["claude", "claude-desktop", "copilot", "cursor"];
 export type Host = (typeof HOSTS)[number];
@@ -21,16 +23,46 @@ export declare function configKey(host: Host): string;
 export declare function entryFor(host: Host, command: string, args: string[]): Record<string, unknown>;
 /** Register this server with `host`. Returns the report to print; throws `InstallError`. */
 export declare function install(host: Host, command: string, args: string[], force?: boolean): string;
+/** The seams `thisCommand` takes, so no test ever reaches npm or the network. */
+export interface CommandOptions {
+    /** The install shape. Default: `currentInstall().shape` — never a second detector. */
+    readonly shape?: () => string;
+    /** Runs an argv and returns `[exit code, output]`. Default: `npminstall.runInstaller`. */
+    readonly installer?: (command: string[]) => [number, string];
+    /** This process's version. Default: the `package.json` this build ships with. */
+    readonly version?: string;
+}
 /**
- * What a host should run to get THIS server.
+ * What a host should run to get THIS server: `<absolute node> <absolute dist/cli.js>`.
+ *
+ * NOT `npx -y bantamkit-mcp` ANY MORE — see the module header for the measurement: with a warm
+ * cache and no network that command hangs silently, so a host that launches it offline sees a
+ * handshake timeout. Not a bare `node` either, because a GUI host's PATH need not have one, and
+ * not a `.bin` shim, whose `#!/usr/bin/env node` fails the same way (measured: exit 127).
+ * `process.execPath` is the node binary running THIS process, which is known to work.
+ *
+ * WHICH `cli.js` DEPENDS ON THE INSTALL SHAPE, and the shape is `currentInstall()`'s answer:
  *
- * `npx -y bantamkit-mcp` and not this process's own path, and the two are not the same
- * thing: a global install, an `npx` cache entry and a checkout all have different paths,
- * while the published name resolves the same everywhere. `-y` because `npx` historically
- * prompts before installing a package it has not seen, and stdin here is the JSON-RPC
- * channel — a prompt that ate one frame would look like a server that lost a request.
+ *   - `ephemeral` (an `npx` cache): this process's own `cli.js` lives in a cache npm may discard,
+ *     so the recorded one is the KEPT install at `keptPrefix()`. If its manifest already reports
+ *     this version OR A NEWER ONE and its `cli.js` is there, nothing runs — a second `--install`
+ *     for another host works offline, and a stale `npx` cache never moves a kept install that
+ *     `--update` took further back to its own version (J51-9a). Otherwise `npm install --prefix <kept> bantamkit-mcp@<this version>`
+ *     runs once, through the same spawner `--update` uses, and the `cli.js` is confirmed after.
+ *     npm creates a missing prefix directory itself (measured, npm 11.6.2), so nothing is made
+ *     here first and a failed install leaves no empty directory of this module's making.
+ *   - every other shape (`registry`, `local-file`, `linked`, `checkout`) is already kept, so it
+ *     is this process's own `dist/cli.js`.
+ *
+ * Every failure is an `InstallError` thrown BEFORE any host configuration is read or written.
  */
-export declare function thisCommand(): {
+export declare function thisCommand(options?: CommandOptions): {
     command: string;
     args: string[];
 };
+/**
+ * `--install <host>` whole: resolve the command (making the kept install if this is an `npx`
+ * cache), THEN touch the host. The order is the property: a refusal from npm leaves the host's
+ * file byte-unchanged with no backup, because `install` has not been reached.
+ */
+export declare function installSelf(host: Host, force?: boolean, options?: CommandOptions): string;

package/dist/hostinstall.js

@@ -17,15 +17,29 @@
  *      runtimes write different bytes for the same install.
  *
  * WHAT IS RULED DIFFERENT, and it is one field: the COMMAND. This side records
- * `npx -y bantamkit-mcp`; the reference records its own console script. The thing installed
- * should be the thing that answers, and neither side should send a host looking for the
- * other's runtime. `docs/porting.md` carries the row.
+ * `<absolute node> <absolute .../dist/cli.js>`; the reference records its own console script.
+ * The thing installed should be the thing that answers, and neither side should send a host
+ * looking for the other's runtime. `docs/porting.md` carries the row.
+ *
+ * JOB51 CHANGED THIS SIDE'S COMMAND, AND THE REASON IS A MEASUREMENT. It used to be
+ * `npx -y bantamkit-mcp`. On npm 11.6.2, with a WARM cache and the network cut (proxies pointed
+ * at a closed port, which leaves the cache key alone), that command — pinned, unpinned or
+ * `@latest` — hung silently past 45 s with zero bytes on stdout, so a host reports a handshake
+ * timeout. A kept `npm install --prefix` launched as `<abs node> <abs dist/cli.js>` answered in
+ * 0.11 s under a GUI-shaped PATH (`/usr/bin:/bin:/usr/sbin:/sbin`), where that install's own
+ * `.bin/bantamkit-mcp` shim exits 127 (`env: node: No such file or directory`). The user ruled
+ * (2026-09-15): `--install` makes a one-time kept install under `~/.bantamkit`, and the host
+ * launches it without the network. See `thisCommand`.
  */
 import { spawnSync } from 'node:child_process';
 import { chmodSync, copyFileSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync, } from 'node:fs';
 import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { currentInstall, Undetermined } from './mcp/identity.js';
+import { compareVersions, keptCli, keptManifest, keptPrefix, PACKAGE, runInstaller, shlexJoin } from './npminstall.js';
 import { dumpJson, fromJs } from './pyjson.js';
+export { keptCli, keptPrefix };
 /** The four hosts, in the order they print in `--help`. */
 export const HOSTS = ['claude', 'claude-desktop', 'copilot', 'cursor'];
 /** The entry name written into every host. */
@@ -233,15 +247,95 @@ export function install(host, command, args, force = false) {
         lines.push(`  backup : ${copied}`);
     return lines.join('\n');
 }
+function ownVersion() {
+    return JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'))
+        .version;
+}
+/** The kept install's version, or `null` when there is no readable manifest with one. */
+function keptVersion(prefix) {
+    try {
+        const manifest = JSON.parse(readFileSync(keptManifest(prefix), 'utf8'));
+        return typeof manifest.version === 'string' ? manifest.version : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** The installer's last non-blank line — stderr's, when npm wrote any, since it is appended last. */
+function lastLine(output) {
+    const lines = output.split(/\r?\n/).map((l) => l.trim()).filter((l) => l !== '');
+    return lines.length === 0 ? 'it printed nothing' : (lines[lines.length - 1] ?? '');
+}
 /**
- * What a host should run to get THIS server.
+ * What a host should run to get THIS server: `<absolute node> <absolute dist/cli.js>`.
+ *
+ * NOT `npx -y bantamkit-mcp` ANY MORE — see the module header for the measurement: with a warm
+ * cache and no network that command hangs silently, so a host that launches it offline sees a
+ * handshake timeout. Not a bare `node` either, because a GUI host's PATH need not have one, and
+ * not a `.bin` shim, whose `#!/usr/bin/env node` fails the same way (measured: exit 127).
+ * `process.execPath` is the node binary running THIS process, which is known to work.
  *
- * `npx -y bantamkit-mcp` and not this process's own path, and the two are not the same
- * thing: a global install, an `npx` cache entry and a checkout all have different paths,
- * while the published name resolves the same everywhere. `-y` because `npx` historically
- * prompts before installing a package it has not seen, and stdin here is the JSON-RPC
- * channel — a prompt that ate one frame would look like a server that lost a request.
+ * WHICH `cli.js` DEPENDS ON THE INSTALL SHAPE, and the shape is `currentInstall()`'s answer:
+ *
+ *   - `ephemeral` (an `npx` cache): this process's own `cli.js` lives in a cache npm may discard,
+ *     so the recorded one is the KEPT install at `keptPrefix()`. If its manifest already reports
+ *     this version OR A NEWER ONE and its `cli.js` is there, nothing runs — a second `--install`
+ *     for another host works offline, and a stale `npx` cache never moves a kept install that
+ *     `--update` took further back to its own version (J51-9a). Otherwise `npm install --prefix <kept> bantamkit-mcp@<this version>`
+ *     runs once, through the same spawner `--update` uses, and the `cli.js` is confirmed after.
+ *     npm creates a missing prefix directory itself (measured, npm 11.6.2), so nothing is made
+ *     here first and a failed install leaves no empty directory of this module's making.
+ *   - every other shape (`registry`, `local-file`, `linked`, `checkout`) is already kept, so it
+ *     is this process's own `dist/cli.js`.
+ *
+ * Every failure is an `InstallError` thrown BEFORE any host configuration is read or written.
  */
-export function thisCommand() {
-    return { command: 'npx', args: ['-y', 'bantamkit-mcp'] };
+export function thisCommand(options = {}) {
+    let shape;
+    try {
+        shape = (options.shape ?? (() => currentInstall().shape))();
+    }
+    catch (e) {
+        if (!(e instanceof Undetermined))
+            throw e;
+        throw new InstallError(`--install could not tell how this install was made, so it will not guess which copy a host should launch: ${e.message}`);
+    }
+    const node = process.execPath;
+    if (shape !== 'ephemeral') {
+        return { command: node, args: [fileURLToPath(new URL('./cli.js', import.meta.url))] };
+    }
+    const version = options.version ?? ownVersion();
+    const prefix = keptPrefix();
+    const cli = keptCli(prefix);
+    const kept = keptVersion(prefix);
+    // NEVER LOWER THE KEPT INSTALL (J51-9a). An `npx` cache can be older than the kept install —
+    // `--update` moved the kept install on, and this cache was filled weeks ago — and every host
+    // already launches the kept one, so installing THIS version over it would move them all back.
+    // A kept version at or above this one is recorded as it is. `compareVersions` is total: a
+    // component that is not all digits sorts after every number, so a version it cannot read as
+    // numbers counts as newer and is left alone rather than overwritten. A blank one is no version.
+    if (kept !== null && kept.trim() !== '' && compareVersions(kept, version) >= 0 && existsSync(cli)) {
+        return { command: node, args: [cli] };
+    }
+    const command = ['npm', 'install', '--prefix', prefix, `${PACKAGE}@${version}`];
+    const rendered = shlexJoin(command);
+    const [code, output] = (options.installer ?? runInstaller)(command);
+    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)}`);
+    if (!existsSync(cli))
+        throw new InstallError(`${refused} but left no ${cli}`);
+    return { command: node, args: [cli] };
+}
+/**
+ * `--install <host>` whole: resolve the command (making the kept install if this is an `npx`
+ * cache), THEN touch the host. The order is the property: a refusal from npm leaves the host's
+ * file byte-unchanged with no backup, because `install` has not been reached.
+ */
+export function installSelf(host, force = false, options = {}) {
+    if (!HOSTS.includes(host)) {
+        throw new InstallError(`unknown host '${host}'; choose one of: ${HOSTS.join(', ')}`);
+    }
+    const { command, args } = thisCommand(options);
+    return install(host, command, args, force);
 }

package/dist/index.d.ts

@@ -18,7 +18,7 @@ export { absolutise, blockKey, claimSlot, collapse, dream, formatFixed3, mergeBo
 export type { DateHit, DreamMerge, DreamResult, SimilarPair, Superseded } from './memory/dream.js';
 export { CAP_BYTES, DEFAULT_RELATIVE_PATH, defaultPath, encodeRecord, EVENT_LOG_ENV, EventLog, formatTimestamp, resolvePath, SCHEMA_VERSION, } from './eventlog.js';
 export type { DetailValue } from './eventlog.js';
-export { DEFAULT_INDEX_BUDGET, DUPLICATE_JACCARD, jaccard, MemoryBudgetExceeded, MemoryStore, MemoryValidationError, pyCompareLt, pyEqualValue, pyHashKey, pyText, RECALL_MIN_SCORE_RATIO, sortScored, tokens, VALID_TYPES, } from './memory/store.js';
+export { BANTAMKIT_GITIGNORE_TEXT, DEFAULT_INDEX_BUDGET, DUPLICATE_JACCARD, ensureBantamkitGitignore, jaccard, MemoryBudgetExceeded, MemoryStore, MemoryValidationError, pyCompareLt, pyEqualValue, pyHashKey, pyText, RECALL_MIN_SCORE_RATIO, sortScored, tokens, VALID_TYPES, } from './memory/store.js';
 export type { MemoryStoreOptions, SaveResult, StoreInternals } from './memory/store.js';
 export { asPyOSError, cmpCodepoint, matchesMd, normcase, pyDecodeUtf8, pyCwd, pyExists, pyExpanduser, pyHome, pyIsAbsolute, pyIsDir, pyIsFile, pyJoin, pyLexists, pyMkdirParents, pyMtimeDate, pyName, PyOSError, pyParent, pyParents, pyReadText, pyReplace, pyRepr, pyResolve, PyRuntimeError, pyScandirNames, PyUnicodeDecodeError, pyAppendText, pyStatIsDir, pySuffix, pyUnlink, pyWithSuffix, pyWriteText, sortedPathNames, sortedPathParts, STRERROR_NAMES, } from './memory/pyfs.js';
 export { clockIn, clockOut, HISTORY_RING_SIZE, SCHEMA_NAME, status, TERMINAL_UNIT_STATUS, timestamp, } from './shiftwork.js';

package/dist/index.js

@@ -9,6 +9,6 @@ export { countFacts, discoverProjectStore, loadGrants, MEMORY_DIR_ENV, PROJECT_S
 export { layerLabel, Memory, normalizeName, profileStore } from './memory/component.js';
 export { absolutise, blockKey, claimSlot, collapse, dream, formatFixed3, mergeBodies, mergeDescriptions, mergeLinks, PROFILE_LAYER, PROJECT_LAYER, pyIntDigits, sortedNames, splitBlocks, SUPERSEDED_HEADING, } from './memory/dream.js';
 export { CAP_BYTES, DEFAULT_RELATIVE_PATH, defaultPath, encodeRecord, EVENT_LOG_ENV, EventLog, formatTimestamp, resolvePath, SCHEMA_VERSION, } from './eventlog.js';
-export { DEFAULT_INDEX_BUDGET, DUPLICATE_JACCARD, jaccard, MemoryBudgetExceeded, MemoryStore, MemoryValidationError, pyCompareLt, pyEqualValue, pyHashKey, pyText, RECALL_MIN_SCORE_RATIO, sortScored, tokens, VALID_TYPES, } from './memory/store.js';
+export { BANTAMKIT_GITIGNORE_TEXT, DEFAULT_INDEX_BUDGET, DUPLICATE_JACCARD, ensureBantamkitGitignore, jaccard, MemoryBudgetExceeded, MemoryStore, MemoryValidationError, pyCompareLt, pyEqualValue, pyHashKey, pyText, RECALL_MIN_SCORE_RATIO, sortScored, tokens, VALID_TYPES, } from './memory/store.js';
 export { asPyOSError, cmpCodepoint, matchesMd, normcase, pyDecodeUtf8, pyCwd, pyExists, pyExpanduser, pyHome, pyIsAbsolute, pyIsDir, pyIsFile, pyJoin, pyLexists, pyMkdirParents, pyMtimeDate, pyName, PyOSError, pyParent, pyParents, pyReadText, pyReplace, pyRepr, pyResolve, PyRuntimeError, pyScandirNames, PyUnicodeDecodeError, pyAppendText, pyStatIsDir, pySuffix, pyUnlink, pyWithSuffix, pyWriteText, sortedPathNames, sortedPathParts, STRERROR_NAMES, } from './memory/pyfs.js';
 export { clockIn, clockOut, HISTORY_RING_SIZE, SCHEMA_NAME, status, TERMINAL_UNIT_STATUS, timestamp, } from './shiftwork.js';

package/dist/mcp/pyargs.js

@@ -112,6 +112,9 @@ export const ARG_MODELS = {
     // `maximum` are advisory to the client for `limit` and for `offset`'s floor; the handler
     // clamps `limit` to `[1, 200]` and `offset` to `>= 0` itself, the way `memory_recall`
     // clamps `k`. `offset`'s CEILING is bound in the model, as it is on the reference (F2).
+    // DORMANT — `bantamkit_read` left the roster (job50 I5, 2026-09-12). The model stays so the
+    // roster line can return with its validation intact; `tools/call` consults `MCP_TOOLS`
+    // before this table, so the entry serves nothing today.
     bantamkit_read: {
         model: 'bantamkit_readArguments',
         fields: [req('path', 'str'), opt('part', 'str'), opt('offset', 'int', { le: OFFSET_MAXIMUM }), opt('limit', 'int')],
@@ -144,6 +147,8 @@ export const ARG_MODELS = {
     // explicit `null` is the default. No `le`, because the reference binds none — the
     // manifest's `minimum: 0` is advisory to the client and the handler's own refusal is the
     // negative one, exactly as `skill_audit`'s `budget` works.
+    // DORMANT — `repo_map` left the roster (job50 I5, 2026-09-12); kept for the same reason as
+    // `bantamkit_read` above, and equally unreachable from the wire.
     repo_map: {
         model: 'repo_mapArguments',
         fields: [req('root', 'str'), opt('focus', 'listStr'), opt('budget', 'int')],

package/dist/mcp/server.d.ts

@@ -4,17 +4,25 @@ import { EventLog } from '../eventlog.js';
 import type { Memory } from '../memory/component.js';
 import type { RawStdioTransport } from './transport.js';
 /**
- * The thirteen, in the order `build_server` lists them — which is the order `tools/list` emits.
+ * The twelve, in the order `build_server` lists them — which is the order `tools/list` emits.
  *
  * `bantamkit_status` went LAST rather than first, `memory_compact` after it rather than
- * beside `memory_save` where a reader would look for it, `bantamkit_read` after that,
- * `skill_audit` after that, `memory_dream` after that, `repo_map` after that and
- * `token_ledger` after that, for the
- * same reason the reference appends all six: registration order IS the served order, and
- * appending is the only edit that leaves the other twelve where every existing declaration
- * says they are.
+ * beside `memory_save` where a reader would look for it, `skill_audit` after that,
+ * `memory_dream` after that and `token_ledger` after that, for the same reason the reference
+ * appends: registration order IS the served order, and appending is the only edit that
+ * leaves the others where every existing declaration says they are.
+ *
+ * `bantamkit_read` (tenth) and `repo_map` (thirteenth) LEFT this list on the user's ruling
+ * of 2026-09-12 (job50, I5), the same ruling that took them out of the reference's
+ * `tools = [...]`: measured over the transcript corpus, neither was called — auto-mode routes
+ * discovery and reading through Bash — and every request re-sent their descriptions. Their
+ * assets claim NO surface now (`"surfaces": []`), so putting either name back here without
+ * also restoring `"mcp"` to its asset is refused by `fromManifest` at startup; and a name
+ * that is not here is `Unknown tool:` on `tools/call` even though `ARG_MODELS` still holds
+ * its argument model. The handlers below are DORMANT, not gone: a roster decision, not a
+ * deletion of working code.
  */
-export declare const MCP_TOOLS: readonly ["memory_save", "memory_recall", "validate_json", "shiftwork_clock_in", "shiftwork_clock_out", "shiftwork_status", "build_identity", "bantamkit_status", "memory_compact", "bantamkit_read", "skill_audit", "memory_dream", "repo_map", "token_ledger"];
+export declare const MCP_TOOLS: readonly ["memory_save", "memory_recall", "validate_json", "shiftwork_clock_in", "shiftwork_clock_out", "shiftwork_status", "build_identity", "bantamkit_status", "memory_compact", "skill_audit", "memory_dream", "token_ledger"];
 /**
  * The advertisement for one tool, out of its manifest, with the surface checked.
  *
@@ -35,6 +43,10 @@ export declare function fromManifest(name: string): Record<string, unknown>;
  * The last paragraph of every `repo_map` reply, refusal excepted. FIXED AND MANDATORY, and
  * byte-identical to the reference's `REPO_MAP_TAIL`.
  *
+ * DORMANT — `repo_map` left the roster (job50 I5, 2026-09-12). The tail, `REPO_MAP_EMPTY`
+ * and `repoMapReply` below stay with the handler: a roster decision, not a deletion of
+ * working code.
+ *
  * Roadmap row 10's build gate was "build only after #4 shows discovery tokens dominate",
  * and #4 REFUTED it: discovery is 0.114 % of real prompt tokens because 97.8 % of the bill
  * is `cache_read`. The feature ships on an explicit ruling to build it anyway, as a

package/dist/mcp/server.js

@@ -17,10 +17,14 @@
  * framing, request routing, the initialize handshake, cancellation, error codes.
  *
  * THE `surfaces` GATE IS LOAD-BEARING. `assets/tools/` serves the eval agent too, and three
- * of the thirteen manifests (`document_list`, `document_read`, `file_graph`) claim only `agent`.
- * `fromManifest` REFUSES those by name rather than filtering them out, because a filter is
- * indistinguishable from a typo: a manifest renamed or a surface dropped would silently
- * shrink the served set, and the field would be a comment.
+ * of the seventeen manifests (`document_list`, `document_read`, `file_graph`) claim only
+ * `agent`, while two (`bantamkit_read`, `repo_map`) claim NO surface at all since job50 I5
+ * (2026-09-12). `fromManifest` REFUSES those by name rather than filtering them out, because
+ * a filter is indistinguishable from a typo: a manifest renamed or a surface dropped would
+ * silently shrink the served set, and the field would be a comment. `MCP_TOOLS` below is the
+ * SAME literal list the reference's `build_server` holds, in the same order, and the asset is
+ * the gate on every name in it — not the source of the names, because the served ORDER is
+ * part of the wire and no asset carries it.
  */
 import { existsSync, readFileSync, realpathSync, statSync } from 'node:fs';
 import { dirname, join } from 'node:path';
@@ -44,15 +48,23 @@ import { ARG_MODELS, PyValidationFailure, validateArguments } from './pyargs.js'
 import { sdkJson } from './sdkjson.js';
 import { degradedConditions, degradedNotice, SERVED_PROMPTS, SERVED_RESOURCE_TEMPLATES, statusReport, STATUS_NAME, STATUS_PROMPT_DESCRIPTION, STATUS_PROMPT_TAIL, STATUS_PROMPT_TITLE, } from './status.js';
 /**
- * The thirteen, in the order `build_server` lists them — which is the order `tools/list` emits.
+ * The twelve, in the order `build_server` lists them — which is the order `tools/list` emits.
  *
  * `bantamkit_status` went LAST rather than first, `memory_compact` after it rather than
- * beside `memory_save` where a reader would look for it, `bantamkit_read` after that,
- * `skill_audit` after that, `memory_dream` after that, `repo_map` after that and
- * `token_ledger` after that, for the
- * same reason the reference appends all six: registration order IS the served order, and
- * appending is the only edit that leaves the other twelve where every existing declaration
- * says they are.
+ * beside `memory_save` where a reader would look for it, `skill_audit` after that,
+ * `memory_dream` after that and `token_ledger` after that, for the same reason the reference
+ * appends: registration order IS the served order, and appending is the only edit that
+ * leaves the others where every existing declaration says they are.
+ *
+ * `bantamkit_read` (tenth) and `repo_map` (thirteenth) LEFT this list on the user's ruling
+ * of 2026-09-12 (job50, I5), the same ruling that took them out of the reference's
+ * `tools = [...]`: measured over the transcript corpus, neither was called — auto-mode routes
+ * discovery and reading through Bash — and every request re-sent their descriptions. Their
+ * assets claim NO surface now (`"surfaces": []`), so putting either name back here without
+ * also restoring `"mcp"` to its asset is refused by `fromManifest` at startup; and a name
+ * that is not here is `Unknown tool:` on `tools/call` even though `ARG_MODELS` still holds
+ * its argument model. The handlers below are DORMANT, not gone: a roster decision, not a
+ * deletion of working code.
  */
 export const MCP_TOOLS = [
     'memory_save',
@@ -64,12 +76,12 @@ export const MCP_TOOLS = [
     'build_identity',
     'bantamkit_status',
     'memory_compact',
-    'bantamkit_read',
     'skill_audit',
     'memory_dream',
-    'repo_map',
     'token_ledger',
 ];
+/** The served set, for the call path: a name outside it is unknown, whatever `ARG_MODELS` says. */
+const SERVED = new Set(MCP_TOOLS);
 /**
  * The advertisement for one tool, out of its manifest, with the surface checked.
  *
@@ -169,6 +181,10 @@ const EXISTS_IGNORED = new Set(['ENOENT', 'ENOTDIR', 'EBADF', 'ELOOP']);
  * The last paragraph of every `repo_map` reply, refusal excepted. FIXED AND MANDATORY, and
  * byte-identical to the reference's `REPO_MAP_TAIL`.
  *
+ * DORMANT — `repo_map` left the roster (job50 I5, 2026-09-12). The tail, `REPO_MAP_EMPTY`
+ * and `repoMapReply` below stay with the handler: a roster decision, not a deletion of
+ * working code.
+ *
  * Roadmap row 10's build gate was "build only after #4 shows discovery tokens dominate",
  * and #4 REFUTED it: discovery is 0.114 % of real prompt tokens because 97.8 % of the bill
  * is `cache_read`. The feature ships on an explicit ruling to build it anyway, as a
@@ -243,6 +259,9 @@ function recordRaise(log, tool, body) {
 /**
  * The last `docread.extract` result this server produced, and what it was OF.
  *
+ * DORMANT — its one user, `bantamkit_read`, left the roster (job50 I5, 2026-09-12); kept
+ * with the handler so the roster line can come back without re-deriving the cache.
+ *
  * The port of `mcpserver._DocumentCache` (register entry (i), `docs/roadmap-toolbox.md` row
  * 8). `bantamkit_read` re-parsed the whole document on EVERY call, so a caller paging a
  * 12,001-row sheet in 200-row pages parsed the workbook once per page — paging was O(N^2) in
@@ -539,6 +558,12 @@ function runTool(name, memory, args, version, log, documents) {
             return { value: { t: 'str', v: noted(outcome.reply) }, wrapped: true };
         }
         case 'bantamkit_read': {
+            // DORMANT — NOT ON THE ROSTER since job50 I5 (user ruling, 2026-09-12): `bantamkit_read`
+            // left `MCP_TOOLS` because the transcript corpus showed it was never called. The reader
+            // (`docread`, `contract`) and its tests are untouched; this arm, `DocumentCache` and
+            // `OFFSET_MAXIMUM` are kept, unreachable from the wire (`SERVED` gates the call path),
+            // so the roster line can return without a rewrite.
+            //
             // The reader on the MCP surface (job43): `docread` digests, `contract` words it. The
             // handler makes the SAME `contract` calls the reference's `bantamkit_read` makes,
             // with the path standing in for the document name, so the two servers print the
@@ -736,6 +761,11 @@ function runTool(name, memory, args, version, log, documents) {
             });
         }
         case 'repo_map': {
+            // DORMANT — NOT ON THE ROSTER since job50 I5 (user ruling, 2026-09-12): `repo_map` left
+            // `MCP_TOOLS` because the transcript corpus showed it was never called. The engine
+            // (`repomap.ts`) and its tests are untouched; this arm is kept, unreachable from the
+            // wire (`SERVED` gates the call path), so the roster line can return without a rewrite.
+            //
             // The ranked definition map on the MCP surface (job45 row 10): `repomap` measures,
             // this serves it. Byte for byte the reference's `repo_map` handler.
             //
@@ -991,7 +1021,10 @@ export function buildServer(memory, wire, version, log = EventLog.fromEnv(memory
         let structuredValue = null;
         let isError;
         try {
-            const model = ARG_MODELS[name];
+            // The roster decides what exists, not the argument table: `ARG_MODELS` still carries
+            // the DORMANT `bantamkit_read` and `repo_map` models (job50 I5), and the reference
+            // answers `Unknown tool:` for a handler it never registered.
+            const model = SERVED.has(name) ? ARG_MODELS[name] : undefined;
             if (model === undefined)
                 throw new BantamError(`Unknown tool: ${name}`);
             const bound = validateArguments(model, args);

package/dist/memory/cli.js

@@ -4,7 +4,7 @@
  *
  * `docs/memory.md` states, as a design decision, that `lint`, `archived` and `restore`
  * are **not** agent tools — "lifecycle is an operator decision, not a model decision" —
- * and the fourteen-tool surface holds to it; `compact` is the one exception since job42
+ * and the twelve-tool surface holds to it; `compact` is the one exception since job42
  * (`memory_compact`, the on-refusal path the model reaches itself). `runtime-py` made that
  * position coherent in August 2026 by giving the operator `python -m bantamkit.memory`.
  * `runtime-ts` did not. MEASURED 2026-08-24 before this file existed: `node dist/cli.js -h`

package/dist/memory/store.d.ts

@@ -1,6 +1,53 @@
 import { BantamError } from '../errors.js';
 import type { Fact, FactValue } from './factfile.js';
 export type { Fact } from './factfile.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`).
+ * Both runtimes hold this text byte-for-byte -- a conformance case pins it against the
+ * Python literal -- so it is spelled once, here, rather than re-typed at each call site.
+ * `runtime-py/src/bantamkit/memory/store.py`'s `BANTAMKIT_GITIGNORE_TEXT` is the reference.
+ */
+export declare const BANTAMKIT_GITIGNORE_TEXT: string;
+/**
+ * Best-effort, idempotent: give `directory` a self-ignoring `.gitignore` if it is literally
+ * named `.bantamkit` AND `created` says THIS CALLER'S OWN mkdir is what just brought it into
+ * existence.
+ *
+ * USER RULING #2 (2026-09-15, after J51-8 measured the fallout of the first rule): the
+ * ignore file is written only when bantamkit itself creates the `.bantamkit` directory. An
+ * existing `.bantamkit` -- made by an earlier bantamkit, by hand, or checked out from git;
+ * with or without a `.gitignore` already in it -- is never given one. That is why `created`
+ * is the caller's job, not this function's: only the caller knows whether `.bantamkit`
+ * existed immediately before ITS mkdir, because by the time this function runs the directory
+ * unconditionally exists either way. (Was: written whenever the ignore file itself was
+ * absent, regardless of whether `.bantamkit` predated the call -- which meant deleting the
+ * file never stuck, and a store a team already commits would silently start ignoring new
+ * fact files after an upgrade. `P0-probes.md` ruling 4.)
+ *
+ * THE PROPERTY, not the mechanism: whenever a `.bantamkit` directory is brought into
+ * existence -- by `MemoryStore.ensureDirs`, or by anything else in this runtime that creates
+ * one, such as `EventLog`'s own append-time `mkdirSync` when the event log is on and the
+ * project store was never saved to -- this is the one place that decides whether it gets
+ * ignored. A second creator that skipped this call, or that got `created` wrong, would leave
+ * a `.bantamkit` that git can see (or ignore one it should not), which is the whole bug this
+ * closes.
+ *
+ * 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
+ * output against what is on disk.
+ *
+ * NEVER RAISES. Failing to write the ignore file must never be why a fact does not get
+ * saved -- the parent write still has to succeed exactly as it does today. An unwritable
+ * filesystem, a permissions error, or the directory disappearing under this call are all
+ * swallowed, mirroring the reference's `except OSError: pass`.
+ *
+ * NEVER CREATES `directory` ITSELF. A write into a missing parent fails like any other
+ * filesystem error here, so calling this before `directory` exists is a no-op, not a way to
+ * bring `.bantamkit` into existence early.
+ */
+export declare function ensureBantamkitGitignore(directory: string, created: boolean): void;
 /** `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,67 @@ 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, pyReadText, pyReplace, pyScandirNames, pySuffix, pyUnlink, pyWithSuffix, pyWriteText, PyOSError, sortedPathNames, } from './pyfs.js';
+import { asPyOSError, cmpCodepoint, matchesMd, pyExists, pyJoin, pyLexists, pyMkdirParents, pyMtimeDate, pyName, pyParent, 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`).
+ * Both runtimes hold this text byte-for-byte -- a conformance case pins it against the
+ * Python literal -- so it is spelled once, here, rather than re-typed at each call site.
+ * `runtime-py/src/bantamkit/memory/store.py`'s `BANTAMKIT_GITIGNORE_TEXT` is the reference.
+ */
+export const BANTAMKIT_GITIGNORE_TEXT = '# Created by bantamkit: this directory is local state. Delete this file to commit it.\n' +
+    '*\n';
+/**
+ * Best-effort, idempotent: give `directory` a self-ignoring `.gitignore` if it is literally
+ * named `.bantamkit` AND `created` says THIS CALLER'S OWN mkdir is what just brought it into
+ * existence.
+ *
+ * USER RULING #2 (2026-09-15, after J51-8 measured the fallout of the first rule): the
+ * ignore file is written only when bantamkit itself creates the `.bantamkit` directory. An
+ * existing `.bantamkit` -- made by an earlier bantamkit, by hand, or checked out from git;
+ * with or without a `.gitignore` already in it -- is never given one. That is why `created`
+ * is the caller's job, not this function's: only the caller knows whether `.bantamkit`
+ * existed immediately before ITS mkdir, because by the time this function runs the directory
+ * unconditionally exists either way. (Was: written whenever the ignore file itself was
+ * absent, regardless of whether `.bantamkit` predated the call -- which meant deleting the
+ * file never stuck, and a store a team already commits would silently start ignoring new
+ * fact files after an upgrade. `P0-probes.md` ruling 4.)
+ *
+ * THE PROPERTY, not the mechanism: whenever a `.bantamkit` directory is brought into
+ * existence -- by `MemoryStore.ensureDirs`, or by anything else in this runtime that creates
+ * one, such as `EventLog`'s own append-time `mkdirSync` when the event log is on and the
+ * project store was never saved to -- this is the one place that decides whether it gets
+ * ignored. A second creator that skipped this call, or that got `created` wrong, would leave
+ * a `.bantamkit` that git can see (or ignore one it should not), which is the whole bug this
+ * closes.
+ *
+ * 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
+ * output against what is on disk.
+ *
+ * NEVER RAISES. Failing to write the ignore file must never be why a fact does not get
+ * saved -- the parent write still has to succeed exactly as it does today. An unwritable
+ * filesystem, a permissions error, or the directory disappearing under this call are all
+ * swallowed, mirroring the reference's `except OSError: pass`.
+ *
+ * NEVER CREATES `directory` ITSELF. A write into a missing parent fails like any other
+ * filesystem error here, so calling this before `directory` exists is a no-op, not a way to
+ * bring `.bantamkit` into existence early.
+ */
+export function ensureBantamkitGitignore(directory, created) {
+    if (pyName(directory) !== '.bantamkit' || !created)
+        return;
+    const gitignore = pyJoin(directory, '.gitignore');
+    if (pyExists(gitignore))
+        return;
+    try {
+        pyWriteText(gitignore, BANTAMKIT_GITIGNORE_TEXT);
+    }
+    catch {
+        /* best-effort: a missing ignore file is not worth a lost fact */
+    }
+}
 /** `sorted(VALID_TYPES)` is what the error message interpolates, so the order is load-bearing. */
 export const VALID_TYPES = ['feedback', 'project', 'reference', 'user'];
 /**
@@ -535,6 +595,11 @@ export class MemoryStore {
      * what lets one conformance case pin this line byte for byte.
      */
     ensureDirs() {
+        // 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);
         try {
             pyMkdirParents(pyJoin(this.root, 'facts'));
             pyMkdirParents(pyJoin(this.root, 'archive'));
@@ -545,6 +610,7 @@ 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);
     }
     // ---- ops ----
     /**

package/dist/npminstall.d.ts

@@ -0,0 +1,54 @@
+/** The npm package this install would upgrade. Divergent by construction (`DISTRIBUTION`). */
+export declare const PACKAGE = "bantamkit-mcp";
+/**
+ * Where `--install` keeps the one-time install a host launches: `<homedir>/.bantamkit/mcp`.
+ *
+ * DEFINED ONCE, HERE, because two flags must agree on it byte for byte: `--install` makes it and
+ * records its `cli.js`, and `--update` from an `npx` cache patches it in place. A second spelling
+ * of this path would be a second place for the two to disagree about a user's install.
+ *
+ * `homedir()` and nothing else — `HOME` on POSIX, `USERPROFILE` on Windows — so pointing those at
+ * a scratch directory moves it, which is what makes the tests possible.
+ */
+export declare function keptPrefix(home?: string): string;
+/** The `dist/cli.js` inside the kept install — what a host is told to run with node. */
+export declare function keptCli(prefix?: string): string;
+/** The `package.json` inside the kept install, whose `version` says whether it is current. */
+export declare function keptManifest(prefix?: string): string;
+/**
+ * `shlex.join`: `shlex.quote` each word and space them.
+ *
+ * Hand-rolled from CPython's own rule — `_find_unsafe = re.compile(r'[^\w@%+=:,./-]', re.ASCII)`
+ * — because the rendered command is printed to the operator by `UPDATING`, by `COMMAND_FAILED`
+ * and by the `local-file` route, and a prefix path with a space in it is the normal case on
+ * macOS and on Windows. Single quotes, with an embedded `'` closed and reopened the way
+ * `shlex.quote` does it, so the line can be pasted back into a shell unchanged.
+ */
+export declare function shlexJoin(command: readonly string[]): string;
+/**
+ * Run the installer, capture what it said, return both.
+ *
+ * CAPTURED RATHER THAN INHERITED so the report has one shape whether or not anybody is
+ * watching, and so a test can inject a substitute and assert on the command WITHOUT a real
+ * install ever running. On the `--install` path this also keeps npm's progress off stdout,
+ * which is the operator's report and nothing else.
+ *
+ * THE ONE PLACE THIS IS NOT THE REFERENCE'S BEHAVIOUR: `stderr=STDOUT` genuinely interleaves
+ * the two streams in the order they happened, and `spawnSync` has no fd-dup, so the two pipes
+ * are concatenated instead — stdout, then stderr. npm writes its progress to stderr and its
+ * result to stdout, so an operator reading a failure still gets both, in two blocks rather than
+ * one. The installer's own words are never compared across runtimes; the sentences around them
+ * are.
+ *
+ * `shell: true` ON WINDOWS ONLY, the idiom `hostinstall.installViaClaudeCli` established for
+ * the same reason: npm is a `npm.cmd` batch shim there and `spawnSync` returns ENOENT for a
+ * batch file without a shell. Arguments are quoted because `cmd.exe` gets a string.
+ */
+export declare function runInstaller(command: readonly string[]): [number, string];
+/**
+ * -1 when the index is ahead, 0 when they agree, 1 when the installed version is ahead.
+ *
+ * The shorter of the two is padded with numeric zeros, so `0.30` and `0.30.0` agree — which is
+ * what a person means by them and what both registries would print for one release.
+ */
+export declare function compareVersions(installed: string, latest: string): number;