bantamkit-mcp 0.33.0 → 0.34.1

package/dist/cli.js

@@ -81,7 +81,7 @@ 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 { pyJoin, PyOSError, pyRepr, pyStatIsDir } from './memory/pyfs.js';
-import { HOSTS, install as installHost, InstallError, thisCommand } from './hostinstall.js';
+import { HOSTS, InstallError, installSelf } from './hostinstall.js';
 import { runUpdate } from './selfupdate.js';
 import { statusLine } from './statusline.js';
 /** `SystemExit("...")`: the message on stderr, exit 1. */
@@ -471,10 +471,11 @@ async function main(argv) {
     // earlier here made the same argv write a file on one runtime and not the other: one
     // command line, two different states on the user's disk. Reviewed and moved.
     if (options.install !== null && options.install !== undefined) {
-        // Before any store or transport exists, the shape `--assets-root` established.
-        const { command, args } = thisCommand();
+        // Before any store or transport exists, the shape `--assets-root` established. The command
+        // is resolved INSIDE the try: on an `npx` cache it makes the kept install first, and npm
+        // failing there is an `InstallError` like any other refusal — `error:` and exit 1.
         try {
-            process.stdout.write(`${installHost(options.install, command, args, options.force)}\n`);
+            process.stdout.write(`${installSelf(options.install, options.force, { version: version() })}\n`);
         }
         catch (e) {
             if (!(e instanceof InstallError))

package/dist/eventlog.js

@@ -55,7 +55,8 @@
  * notice — the failure mode a diagnostic can least afford.
  */
 import { appendFileSync, mkdirSync, renameSync, statSync } from 'node:fs';
-import { cmpCodepoint, osErrorClassName, PyOSError, pyJoin, pyParent } from './memory/pyfs.js';
+import { cmpCodepoint, osErrorClassName, pyExists, PyOSError, pyJoin, pyName, pyParent, pyParents } from './memory/pyfs.js';
+import { ensureBantamkitGitignore } from './memory/store.js';
 /**
  * Environment switch. Unset or `off`/`0`/`false`/`no`/empty -> disabled. `on`/`1`/`true`/
  * `yes` -> the default file inside the memory store. Anything else is taken as the literal
@@ -242,11 +243,33 @@ export class EventLog {
      * by construction, so that branch is a statement of intent, not a live path.
      */
     append(path, payload) {
+        // AUDIT FINDING (J51-1, mirrored from `runtime-py/src/bantamkit/eventlog.py`): the
+        // `mkdirSync` below can bring a whole `.bantamkit` directory into existence on its own
+        // -- `BANTAMKIT_EVENT_LOG=on` with a project store that was never saved to reaches here
+        // first -- entirely bypassing `MemoryStore.ensureDirs`, which is the only other place a
+        // `.bantamkit` directory gets created. Without this call a store built that way would
+        // never get its self-ignoring `.gitignore`. Cheap and idempotent: a no-op unless one of
+        // `path`'s ancestors is literally named `.bantamkit`.
+        //
+        // USER RULING #2 (J51-8b): the ignore file is written only when THIS call is what
+        // creates `.bantamkit`, so existence has to be checked BEFORE the mkdir below -- after
+        // it, the directory unconditionally exists and the question is unanswerable.
+        let bantamkitDir = null;
+        for (const parent of pyParents(path)) {
+            if (pyName(parent) === '.bantamkit') {
+                bantamkitDir = parent;
+                break;
+            }
+        }
+        const bantamkitDirExistedBefore = bantamkitDir !== null && pyExists(bantamkitDir);
         // `pyParent` and not `node:path`'s `dirname`: this module is reached from a Windows
         // host through the same code, and the reference's `Path(...).parent` is the spelling
         // that understands a drive letter. `.`'s parent is `.` in both, so a bare filename
         // makes the directory that already exists rather than reaching for the root.
         mkdirSync(pyParent(path), { recursive: true });
+        if (bantamkitDir !== null) {
+            ensureBantamkitGitignore(bantamkitDir, !bantamkitDirExistedBefore);
+        }
         let size = 0;
         try {
             size = statSync(path).size;

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/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;

package/dist/npminstall.js

@@ -0,0 +1,141 @@
+/**
+ * The npm spawner and the kept-install location, shared by `--install` and `--update`.
+ *
+ * WHY THIS IS ITS OWN MODULE. `selfupdate.ts` owns the one network request in this runtime, and
+ * `test/selfupdate.test.mjs` pins that `cli.ts` is the ONLY module in `src/` importing it. Job51
+ * made `--install` spawn npm too (the kept install below), and the brief was to SHARE the spawner
+ * rather than write a second one. Moving it here lets `hostinstall.ts` use it without reaching
+ * `selfupdate.ts`; `selfupdate.ts` re-exports all three names, so its surface is unchanged.
+ *
+ * Nothing here touches the network by itself. `runInstaller` spawns whatever argv it is handed,
+ * and only the two operator-typed flags hand it one.
+ */
+import { spawnSync } from 'node:child_process';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+/** The npm package this install would upgrade. Divergent by construction (`DISTRIBUTION`). */
+export 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 function keptPrefix(home = homedir()) {
+    return join(home, '.bantamkit', 'mcp');
+}
+/** The `dist/cli.js` inside the kept install — what a host is told to run with node. */
+export function keptCli(prefix = keptPrefix()) {
+    return join(prefix, 'node_modules', PACKAGE, 'dist', 'cli.js');
+}
+/** The `package.json` inside the kept install, whose `version` says whether it is current. */
+export function keptManifest(prefix = keptPrefix()) {
+    return join(prefix, 'node_modules', PACKAGE, 'package.json');
+}
+/**
+ * `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 function shlexJoin(command) {
+    return command
+        .map((word) => {
+        if (word === '')
+            return "''";
+        if (/^[\w@%+=:,./-]+$/.test(word))
+            return word;
+        return `'${word.replace(/'/g, `'"'"'`)}'`;
+    })
+        .join(' ');
+}
+/**
+ * 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 function runInstaller(command) {
+    const [program, ...args] = command;
+    const win = process.platform === 'win32';
+    const quoted = win ? args.map((a) => (/[\s"^&|<>]/.test(a) ? `"${a.replace(/"/g, '\\"')}"` : a)) : args;
+    const done = spawnSync(program ?? '', quoted, { encoding: 'utf8', shell: win });
+    if (done.error) {
+        // A missing `npm` is not a stack trace: it is a command that failed, and `COMMAND_FAILED`
+        // is the sentence that says so and hands back what went wrong. 127 is the shell's own
+        // code for "command not found", so the number means something to the person reading it.
+        return [127, done.error.message];
+    }
+    return [done.status ?? 1, `${done.stdout ?? ''}${done.stderr ?? ''}`];
+}
+/**
+ * A dotted version as something orderable, deterministically, without claiming PEP 440.
+ *
+ * THE REFERENCE'S RULE, REPRODUCED EXACTLY, INCLUDING THE PART THAT IS WRONG. Split on `.`; a
+ * component that is all digits sorts as a NUMBER, anything else sorts as a STRING after every
+ * number in that position. So `0.9.0 < 0.10.0` — the thing a plain string compare gets wrong,
+ * and the reason this exists — and `0.31.0 < 0.31.0rc1`, which is WRONG BY SEMVER AND BY PEP
+ * 440 and is kept anyway.
+ *
+ * A CORRECT COMPARISON HERE WOULD BE A DIVERGENCE, NOT AN IMPROVEMENT. `_version_key`'s
+ * docstring in the reference gives the reason: bantamkit has never published a prerelease to
+ * either registry, and implementing PEP 440 there in order to reproduce it here would be a
+ * second, larger thing to keep byte-identical in service of a case neither index can currently
+ * return. What matters is that both runtimes are wrong in the SAME direction, which a
+ * conformance case can pin and a reader can check. If a prerelease is ever published, this is
+ * the function to fix — in both runtimes, in one job.
+ *
+ * `/^\d+$/` is ASCII-only, where CPython's `str.isdigit()` is not. That narrowing is the safe
+ * direction: the strings `str.isdigit()` accepts and `int()` then REFUSES (superscripts, for
+ * one) raise in the reference and sort as strings here, and no registry can answer with one.
+ */
+function versionKey(version) {
+    return version.split('.').map((part) => (/^\d+$/.test(part) ? [0, Number(part), ''] : [1, 0, part]));
+}
+const PAD = [0, 0, ''];
+function comparePart(left, right) {
+    if (left[0] !== right[0])
+        return left[0] < right[0] ? -1 : 1;
+    if (left[1] !== right[1])
+        return left[1] < right[1] ? -1 : 1;
+    if (left[2] === right[2])
+        return 0;
+    return left[2] < right[2] ? -1 : 1;
+}
+/**
+ * -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 function compareVersions(installed, latest) {
+    const left = versionKey(installed);
+    const right = versionKey(latest);
+    const width = Math.max(left.length, right.length);
+    for (let i = 0; i < width; i += 1) {
+        const order = comparePart(left[i] ?? PAD, right[i] ?? PAD);
+        if (order !== 0)
+            return order;
+    }
+    return 0;
+}