bantamkit-mcp 0.33.0 → 0.34.0

package/README.md

@@ -29,6 +29,13 @@ That is the whole install. No `pip`, no venv, no `PYTHONPATH`. `runtime-ts/mcp.j
 in the repository is the annotated version, with the four forms and the two measured
 questions that decide between them.
 
+> **AMENDED 2026-09-15 (job51) — this is no longer the recommended form.** The block above
+> resolves the package against the registry at every launch. When the registry cannot be
+> reached, it hangs silently, even with a warm cache (measured below). From 0.34.0,
+> `npx -y bantamkit-mcp@latest --install <host>` writes an entry that starts with no network.
+> See *Install once, run offline*. `mcp.json.example` now has five forms, and the kept install
+> is the first.
+
 **Pass `-y`.** `npx` historically prompted before installing a package it had not seen,
 and stdin here is the JSON-RPC channel: a prompt that consumed one frame looks like a
 server that lost a request. npm 11.6.2 was measured sending that prompt to stderr rather
@@ -49,6 +56,23 @@ npx -y bantamkit-mcp --install copilot         # GitHub Copilot in VS Code
 npx -y bantamkit-mcp --install cursor          # Cursor
 ```
 
+> **ADDED 2026-09-15 (job51) — what these commands record changes in 0.34.0.** 0.33.0 and
+> earlier record `npx -y bantamkit-mcp`. From 0.34.0 they record
+> `<absolute node> <absolute dist/cli.js>`:
+>
+> - **Run from an npx cache**, as the lines above are, the `cli.js` belongs to a *kept
+>   install* at `~/.bantamkit/mcp`. On Windows that is `%USERPROFILE%\.bantamkit\mcp`, which was
+>   not measured. The kept install is made once with `npm install --prefix`, and only when it
+>   does not already report this version.
+> - **Run from any other install** (`npm i -g`, `npm i --prefix`, a checkout), it is that
+>   install's own `dist/cli.js`.
+>
+> If npm fails, no host file is read or written and no backup is taken. Add `@latest`
+> (`npx -y bantamkit-mcp@latest --install <host>`) so npx does not reuse an older cached
+> resolve. Two further points are explained in *Install once, run offline*. Moving from an
+> existing `npx` entry needs `--force`, and on Claude Code it needs `claude mcp remove`
+> first. The recorded node path names one node version.
+
 `--install claude` runs `claude mcp add` rather than editing `~/.claude.json` directly:
 that file is the host's, and it carries state that is not MCP configuration. What happens on
 a second run there is Claude Code's decision, not this command's, and `--force` does not
@@ -63,6 +87,26 @@ not parse is refused rather than replaced.
 The rest of this section is what those commands write, for anyone who would rather do it by
 hand. Every host runs the same command; only the file and the key around it change.
 
+**AMENDED 2026-09-15 (job51) — the forms below are the online ones.** They are what 0.33.0
+and earlier write. From 0.34.0, `--install` writes the kept install instead, and that is also
+the recommended form to write by hand. Make the install once, then register node and its
+`cli.js`, both by absolute path:
+
+```bash
+npm install --prefix ~/.bantamkit/mcp bantamkit-mcp@0.33.0
+claude mcp add bantamkit -s user -- "$(node -p process.execPath)" ~/.bantamkit/mcp/node_modules/bantamkit-mcp/dist/cli.js
+```
+
+Both lines were run against a scratch `HOME`. npm exited 0, and Claude Code recorded
+`"command": "<…>/mise/installs/node/25.2.1/bin/node"` with the absolute `cli.js` as the one
+argument. For the three JSON hosts below, keep the file and the key, keep Copilot's
+`"type": "stdio"`, and use this `command`/`args` pair (`node -p process.execPath` prints the
+first path):
+
+```json
+{"command": "/absolute/path/to/node", "args": ["/Users/you/.bantamkit/mcp/node_modules/bantamkit-mcp/dist/cli.js"]}
+```
+
 **Claude Code** — one command, no file to edit. `-s user` makes it available in every
 project; drop it for this project only.
 
@@ -174,6 +218,121 @@ exactly when nobody is watching.
 If offline operation matters, do not use `npx`. Run `npm i -g bantamkit-mcp` once and
 point the config at the installed binary, or keep using `tools/bantamkit-mcp`.
 
+> **AMENDED 2026-09-15 (job51) — "A warm cache does not have this problem" is false on npm
+> 11.6.2 for every spec a host config actually types.** Both paragraphs are kept rather than
+> rewritten, because the table above still holds. With a warm cache and the network cut,
+> `npx -y bantamkit-mcp@0.33.0`, `npx -y bantamkit-mcp` and `npx -y bantamkit-mcp@latest` all
+> hung silently, as the next section measures. "Point the config at the installed binary"
+> has a trap of its own under a GUI host: see the `.bin` row in that table. The next section
+> replaces both paragraphs.
+
+### Install once, run offline
+
+`node tools/conformance/npx-cold-start.mjs --offline` printed every row below in a single run.
+It ran on 2026-09-15 at commit `2f58af4`, with node v25.2.1 and npm 11.6.2, on macOS 26.6.2 on
+Apple silicon, and took 299.94 s wall. It cuts the network by pointing `npm_config_proxy`
+and `npm_config_https_proxy` at `http://127.0.0.1:1`. It does not use `npm_config_registry`,
+which changes npm's cache key and would make a warm cache measure as cold. "GUI PATH" means
+`/usr/bin:/bin:/usr/sbin:/sbin`, the PATH a GUI-launched host inherits on this machine.
+
+| arm | outcome | wall | stdout |
+|---|---|---|---|
+| cold cache, registry refusing connections, `npx -y` | exit 1, 0 frames | 140.29 s | 0 bytes |
+| registry spec, warm cache, network cut: `npx -y bantamkit-mcp@0.33.0` | **silent hang**, killed at the 45 s bound | 45.01 s | 0 bytes |
+| the same, `npx -y bantamkit-mcp` | **silent hang** | 45.01 s | 0 bytes |
+| the same, `npx -y bantamkit-mcp@latest` | **silent hang** | 45.02 s | 0 bytes |
+| the same warm cache, network cut: `npx --offline -y bantamkit-mcp@0.33.0` | OK, 12 tools | 0.40 s | — |
+| local tarball spec (`--package=<file>.tgz`), warm cache, network cut: `npx -y` | OK | 1.35 s | 27987 bytes |
+| cold cache, `npx --offline -y` (tarball spec) | exit 1, `npm error code ENOTCACHED` | 2.69 s | — |
+| kept install: `npm install --prefix <dir> <tarball>`, once, online | OK | 4.82 s | — |
+| that install as `<abs node> <dir>/node_modules/bantamkit-mcp/dist/cli.js`, GUI PATH, network cut | OK, 12 tools | 0.09 s | — |
+| that install's `node_modules/.bin/bantamkit-mcp`, same PATH | exit 127, `env: node: No such file or directory` | 0.16 s | — |
+
+What the table says:
+
+- **The hang comes from a registry spec, not from npx in general.** npx resolves a registry
+  spec against the registry at every start, so a warm cache does not save it. A local tarball
+  on its own warm cache answered in 1.35 s with the same cut. Do not read the three hung rows
+  as "every npx launch hangs offline".
+- **`npx --offline` is the middle option.** It serves a warm cache without the registry, in
+  0.40 s here. On a cache that has never seen the package it fails at once with
+  `ENOTCACHED`. It suits a machine that has already run that exact spec online once, and it
+  cannot start a new one.
+- **Only a kept install launched as node plus `cli.js` needs nothing.** No package is
+  resolved and no PATH lookup happens. The `.bin` shim fails because its first line is
+  `#!/usr/bin/env node`, and a GUI host's PATH has no `node`. An `npm i -g` bin runs the
+  same file, so the global advice above hits the same trap unless `node` is on the host's
+  PATH.
+
+**From 0.34.0, `--install` builds the kept install for you.** Run as
+`npx -y bantamkit-mcp@latest --install <host>`, it finds that it is running from an npx cache.
+It then installs `bantamkit-mcp@<its own version>` into `~/.bantamkit/mcp` with
+`npm install --prefix`, and records `<process.execPath> ~/.bantamkit/mcp/node_modules/bantamkit-mcp/dist/cli.js`
+with both paths absolute. It skips npm — and never downgrades — when the kept install already
+reports this version or a newer one; an unparseable kept version sorts as newer and is left
+alone too (J51-9a). Only an older, missing or blank kept version, or one whose `cli.js` is
+gone, runs npm. Measured in this unit: a kept install's manifest was hand-edited to
+`0.100.0` (newer than the `0.33.0` tarball below), then `--install`ed again with the network
+cut (`npm_config_proxy`/`npm_config_https_proxy` pointed at a closed port) — exit 0 in 0.355 s,
+npm never ran, and the kept manifest still read `0.100.0` afterward.
+
+**This installs the registry's package for that version, not this tree's code.** The `npm
+install --prefix` above asks the registry for `bantamkit-mcp@<version>`, so a checkout or an
+`npm pack` tarball only supplies the version *number*; the bytes that end up in
+`~/.bantamkit/mcp` are whatever the registry published under that number. Measured in this
+unit: a `0.33.0` tarball packed from this tree carries the string `J51-9a` twice in
+`dist/hostinstall.js` (`tar -xOzf bantamkit-mcp-0.33.0.tgz package/dist/hostinstall.js | grep
+-c J51-9a` → `2`), but after `--install cursor` ran from that same tarball, the kept
+`~/.bantamkit/mcp/node_modules/bantamkit-mcp/dist/hostinstall.js` carries it zero times — the
+kept install is the published `0.33.0`, which predates J51-9a, not the tree that was packed.
+Measured end to end from `npm pack` of this tree (version string still 0.33.0), in a scratch
+`HOME` with an empty npm cache — read the table below as *when* the install happens, not
+*whose code* it installs:
+
+| command | result |
+|---|---|
+| `npx -y -p <tgz> bantamkit-mcp --install cursor` | exit 0 in 11.60 s; wrote `"command": "/Users/…/mise/installs/node/25.2.1/bin/node"` and `"args": ["<HOME>/.bantamkit/mcp/node_modules/bantamkit-mcp/dist/cli.js"]` |
+| the same with `--install copilot`, network cut | exit 0 in 0.35 s; npm did not run |
+| `--install cursor` over an existing `npx -y bantamkit-mcp` entry | exit 1: `cursor already has a bantamkit entry with different settings` … `re-run with --force to replace it` |
+| the same with `--force` | exit 0, `backup : …/mcp.json.backup-2026-09-15` |
+
+0.34.0 was not yet on npm when this was written. Measured the same day,
+`npx -y bantamkit-mcp@0.33.0 --install cursor` still writes
+`"command": "npx", "args": ["-y", "bantamkit-mcp"]`. Until 0.34.0 is out, make the kept install
+by hand, as shown in *Connect it to a host*.
+
+**Two consequences to know.**
+
+1. **The recorded node is one version of node.** Under mise, `process.execPath` is
+   `~/.local/share/mise/installs/node/25.2.1/bin/node`. Uninstall or switch away from that
+   version and the host can no longer spawn the server. Re-run
+   `npx -y bantamkit-mcp@latest --install <host> --force` with the node you have now. nvm
+   also keeps one directory per version; that was not measured here.
+2. **Moving from an `npx` entry needs `--force`**, as the table shows. On Claude Code
+   `--force` does not help: `claude mcp add` refuses a name it already has
+   (`MCP server bantamkit already exists in user config`, exit 1, measured with Claude Code
+   2.1.270 against a scratch `HOME`). Run `claude mcp remove bantamkit -s user` first.
+
+**Updating the kept install.** From 0.34.0, `npx -y bantamkit-mcp@latest --update` run from
+an npx cache finds `~/.bantamkit/mcp`. It compares that install's version with the registry,
+and when they differ it runs `npm install --prefix ~/.bantamkit/mcp bantamkit-mcp@latest`.
+With no kept install, it refuses exactly as it did before. Measured with a kept 0.32.1 in a
+scratch `HOME`:
+
+```console
+$ npx -y -p <tgz> bantamkit-mcp --update
+bantamkit-mcp 0.32.1 is installed; the package index has 0.33.0.
+updating from the package index: npm install --prefix <HOME>/.bantamkit/mcp bantamkit-mcp@latest
+the command printed:
+<npm's own output>
+updated bantamkit-mcp from 0.32.1 to 0.33.0.
+restart the server: a running bantamkit-mcp keeps serving the code it loaded at startup, so bantamkit_status will report 0.32.1 until the host reconnects.
+```
+
+That run exited 0 in 1.58 s. A second run printed `up to date.` and exited 0. Then reconnect
+the server in the host. Nothing checks for updates at server startup, and startup never
+touches the network.
+
 ### Measured: `npx` is not on a login-less PATH
 
 ```sh
@@ -206,6 +365,12 @@ Two ways out, both in `runtime-ts/mcp.json.example`:
 { "command": "/usr/local/bin/bantamkit-mcp", "args": [] }
 ```
 
+> **AMENDED 2026-09-15 (job51) — the second form has the same problem one level down.**
+> `bantamkit-mcp` runs `dist/cli.js`, whose first line is `#!/usr/bin/env node`. Under this
+> PATH the kept install's `.bin` shim exited 127 (`env: node: No such file or directory`). A
+> global link runs the same file, though it was not launched separately here. Name node by
+> absolute path instead, as *Install once, run offline* shows.
+
 ## What `npx` gives up versus `tools/bantamkit-mcp`
 
 The sh launcher is not obsolete. It guarantees things `npx` cannot, and this table is the
@@ -218,7 +383,7 @@ prep probe's, unsoftened.
 | code from the worktree, deps from the main checkout | yes (`PYTHONPATH` + `PYTHONSAFEPATH`) | **no Node analogue.** `NODE_PATH` is ignored by ESM and there is no `-P`. `npm link` and workspaces are a different failure surface, not the same one solved |
 | stdin is the JSON-RPC channel | yes | yes, with `-y` |
 | names the cause when dependencies are missing | yes | the analogous failure is *no network*, and it has no message at all — see the table above |
-| starts without a network | yes | **no**, on a cold cache |
+| starts without a network | yes | **no**, on a cold cache. *Amended 2026-09-15:* nor on a warm one, for a registry spec (silent hang at a 45 s bound; *Install once, run offline*). From 0.34.0 `--install` records a kept install that does start offline |
 | `--which`, for diagnosing which endpoint answered | the flag exists | **not in the npx CLI** — but `tools/bantamkit-mcp-node --which` has it, see below |
 | one config line, no clone, no venv | no | **yes.** This is the whole reason the package exists |
 
@@ -280,31 +445,39 @@ that were imported (RB-P84).
 **Pin the version in the config** if you want this to be a non-issue:
 `"args": ["-y", "bantamkit-mcp@0.30.0"]`.
 
+A kept install (what `--install` records from 0.34.0) does not float either. It serves the
+version in `~/.bantamkit/mcp` until someone runs `--update`.
+
 ## Updating
 
-**There is no `bantamkit-mcp --update`, deliberately.** The package manager that installed
-this is the thing that updates it, and there are five install shapes with five different
-answers. Pick the row you are actually on — and note that **the running server keeps
-serving the code it loaded at startup**, so every row ends with restarting it in the host.
-
-> **AMENDED 2026-09-11 — there IS a `bantamkit-mcp --update` now, and the paragraph above is
-> kept rather than rewritten because everything in it is still true of what the flag does.**
-> `bantamkit-mcp --update` asks the npm registry for `latest` and compares it to the version
-> that is installed. If they match it prints both numbers and `up to date.` and stops. If the
-> index is ahead **and this is a registry install**, it runs the row below that applies to you
-> and prints what npm said. If the index is ahead and this is any OTHER shape, **it refuses,
-> exits 1, and names the row you are on** — it will not write a registry install into a tree
-> you manage with `git`, and a command that exits 0 having changed nothing is worse than one
-> that says no. Either way it ends by telling you to restart the server, for the reason the
-> paragraph above gives: a successful update does not change the process that is answering
-> you. The flag reaches the network and nothing else here does — not at startup, not on
-> `bantamkit_status`, not on any tool — with a 10-second timeout, and being offline is a named
-> refusal on stderr, never a traceback. The table below is still the reference for what to do
-> by hand, and it is what `--update` prints back at you when it will not act.
+**Updating.** `bantamkit-mcp --update` — quoted verbatim from `--help`, run in this job
+(`node runtime-ts/dist/cli.js --help`, the same line as `.venv/bin/bantamkit-mcp --help`):
+`--update  check the package index and update this install if it differs, then exit`. It asks
+the npm registry for `latest` and compares it to the version installed. If they match, it
+prints both numbers and `up to date.` and stops. If the index is ahead **and this is a
+registry install, or, from 0.34.0, a kept install made by `--install`**, it runs the row below
+that applies to you and prints what npm said. If the index is ahead and this is any OTHER
+shape — a checkout, a linked tree, a local file, or an npx cache with no kept install — **it
+refuses, exits 1, and names the row you are on**: it will not write a registry install into a
+tree you manage with `git`, and a command that exits 0 having changed nothing is worse than
+one that says no. Either way it ends by telling you to restart the server — **the running
+server keeps serving the code it loaded at startup**, so every row ends with restarting it in
+the host. The flag reaches the network and nothing else here does — not at startup, not on
+`bantamkit_status`, not on any tool — with a 10-second timeout, and being offline is a named
+refusal on stderr, never a traceback. The table below is the reference for what to do by hand,
+and it is what `--update` prints back at you when it will not act.
+
+> **J51-9b (2026-09-15).** This section used to open "There is no `bantamkit-mcp --update`,
+> deliberately," amended below rather than rewritten (2026-09-11, when the flag first
+> shipped). A review (F4) found that opening sentence sitting directly above this job's own
+> `--update` table row and flagged it as actively wrong, not merely stale, so this time the
+> paragraph is rewritten rather than amended again; it says nothing the 2026-09-11 amendment
+> did not already say, plus the 0.34.0 kept-install route this job added to the table below.
 
 | how it was installed | how to update |
 |---|---|
 | `npx -y bantamkit-mcp` in the host config | nothing to update — but npx **caches the resolved version**, so add `@latest` (or a pinned `@0.30.0`) or it will keep serving what it resolved weeks ago. `rm -rf ~/.npm/_npx` forces a clean resolve. |
+| `npx -y bantamkit-mcp --install <host>` from 0.34.0: a kept install at `~/.bantamkit/mcp` (added 2026-09-15) | `npx -y bantamkit-mcp@latest --update` patches it in place, or `npm i --prefix ~/.bantamkit/mcp bantamkit-mcp@latest`. The recorded paths do not change. Before 0.34.0, `--update` from an npx cache refuses instead |
 | `npm i -g bantamkit-mcp` | `npm i -g bantamkit-mcp@latest` |
 | `npm i --prefix <dir> bantamkit-mcp` | `npm i --prefix <dir> bantamkit-mcp@latest` |
 | PyPI (`pip install "bantamkit[mcp]"`) | `pip install -U "bantamkit[mcp]"` · pipx: `pipx upgrade bantamkit` · uv: `uv tool upgrade bantamkit` |
@@ -533,7 +706,7 @@ From the repository root:
 ```sh
 node tools/conformance/run.mjs --all                   # Node vs Python, 4300+ cases
 node tools/conformance/npx-cold-start.mjs              # pack, cold npx, warm npx, PATH
-node tools/conformance/npx-cold-start.mjs --offline    # + the no-registry probe (~2.5 min)
+node tools/conformance/npx-cold-start.mjs --offline    # + the no-network arms (299.94 s on 2026-09-15)
 ```
 
 The conformance harness shells out to a CPython to produce the reference side. That is a

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;
+}

package/dist/selfupdate.d.ts

@@ -1,11 +1,11 @@
+import { compareVersions, PACKAGE, runInstaller, shlexJoin } from './npminstall.js';
+export { compareVersions, PACKAGE, runInstaller, shlexJoin };
 /**
  * The command the operator typed, on BOTH runtimes. Not the package name — see the module
  * docstring: PyPI has `bantamkit`, npm has `bantamkit-mcp`, and only this word is the same on
  * both, so only this word can appear in a sentence the reference and this file share verbatim.
  */
 export declare const PROGRAM = "bantamkit-mcp";
-/** The npm package this install would upgrade. Divergent by construction (`DISTRIBUTION`). */
-export declare const PACKAGE = "bantamkit-mcp";
 /**
  * The one URL this toolbox ever fetches. Divergent by construction (`INDEX_URL`).
  *
@@ -98,6 +98,9 @@ export declare const NO_RECORDED_ROUTE = "There is no recorded update route for
  * byte-identical config can be running builds resolved weeks apart. So this row is true of the
  * cache that actually exists rather than of a fresh resolve that does not happen, and it names
  * the only thing that changes it: the spec on the host's command line.
+ *
+ * Since J51-5 this row is reached only when there is NO kept install (`keptInstall`): with one,
+ * `runUpdate` updates that install instead, so the sentence stays true of what it describes.
  */
 export declare const ROUTES: Record<string, string>;
 /**
@@ -174,16 +177,6 @@ export declare function installEnvironment(runningFile?: string): Environment;
  * suite asserts against by name, and a silent passthrough is how one ships.
  */
 export declare function fill(template: string, values: Readonly<Record<string, string | number>>): 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;
 /**
  * The version string out of the registry's JSON, or a named refusal. Pure — no network here.
  *
@@ -234,32 +227,6 @@ export declare function fetchIndex(url?: string, timeout?: number): Promise<stri
  * this code's.
  */
 export declare function upgradeCommand(environment: Environment): string[];
-/**
- * Run the installer, capture what it said, return both. The only side effect in this module.
- *
- * 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.
- *
- * 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;
 /**
  * `10` rather than `10.0`, because the sentence is read by a person, not parsed.
  *
@@ -275,7 +242,41 @@ export interface UpdateOptions {
     readonly url?: string;
     readonly timeout?: number;
     readonly environment?: Environment;
+    /**
+     * Which install is running, as `runUpdate` asks it. Default: `currentInstall()`, and nothing
+     * else in `src/` passes one. A seam so the `ephemeral` arms are reachable from a test running
+     * in a checkout; `update()` itself never reads it.
+     */
+    readonly install?: () => {
+        readonly shape: string;
+        readonly source: string | null;
+    };
 }
+/** The kept install `--update` targets from an `npx` cache: its version and its `--prefix` tree. */
+export interface KeptInstall {
+    readonly version: string;
+    readonly environment: Environment;
+}
+/**
+ * The kept install `--install` left at `keptPrefix()` (J51-4), or `null` when there is none to
+ * patch. A local read and nothing more — no network, no spawn.
+ *
+ * WHY `--update` LOOKS FOR IT. From an `npx` cache there is nothing to update in place, but the
+ * hosts do not launch the cache: `--install` recorded the kept install's `cli.js`. So an operator
+ * who types `npx -y bantamkit-mcp@latest --update` is asking about THAT install, and it is a
+ * `--prefix` tree `npm install --prefix` updates in place (measured: 0.32.1 to 0.33.0, exit 0).
+ *
+ * THERE IS ONE ONLY WHEN ALL OF THIS HOLDS, and anything short of it is `null` — which leaves
+ * today's `ephemeral` refusal exactly as it was:
+ *
+ *   - the kept manifest (`keptManifest`, never respelled) is readable JSON with a non-blank
+ *     string `version`;
+ *   - `installEnvironment` on the kept `cli.js` says it is NOT the global tree. npm writes a
+ *     `package.json` at a `--prefix` it installed into, so a real kept install always passes.
+ *     One without it would render `npm install --global`, which updates some other install and
+ *     reports success about this one — worse than refusing.
+ */
+export declare function keptInstall(prefix?: string): KeptInstall | null;
 /**
  * The whole flag: ask the index, compare, and act — or refuse, by name.
  *

package/dist/selfupdate.js

@@ -40,19 +40,23 @@
  * `test/selfupdate.test.mjs` — and it calls `runUpdate` from the flag and returns before a
  * memory store or a transport exists, the same shape `--assets-root` and `--install` use.
  */
-import { spawnSync } from 'node:child_process';
 import { readFileSync } from 'node:fs';
 import { basename, dirname, join, resolve } 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';
+// `PACKAGE`, `shlexJoin` and `runInstaller` moved to `npminstall.ts` in job51 so `--install` can
+// share the npm spawner without importing this module (see that file's header). Re-exported so
+// this module's surface — and every test importing these from `dist/selfupdate.js` — is unchanged.
+// `compareVersions` followed in J51-9a, for the same reason: `--install` from an `npx` cache orders
+// the kept install's version against its own, and must not import this module to do it.
+export { compareVersions, PACKAGE, runInstaller, shlexJoin };
 /**
  * The command the operator typed, on BOTH runtimes. Not the package name — see the module
  * docstring: PyPI has `bantamkit`, npm has `bantamkit-mcp`, and only this word is the same on
  * both, so only this word can appear in a sentence the reference and this file share verbatim.
  */
 export const PROGRAM = 'bantamkit-mcp';
-/** The npm package this install would upgrade. Divergent by construction (`DISTRIBUTION`). */
-export const PACKAGE = 'bantamkit-mcp';
 /**
  * The one URL this toolbox ever fetches. Divergent by construction (`INDEX_URL`).
  *
@@ -164,6 +168,9 @@ export const NO_RECORDED_ROUTE = 'There is no recorded update route for a {shape
  * byte-identical config can be running builds resolved weeks apart. So this row is true of the
  * cache that actually exists rather than of a fresh resolve that does not happen, and it names
  * the only thing that changes it: the spec on the host's command line.
+ *
+ * Since J51-5 this row is reached only when there is NO kept install (`keptInstall`): with one,
+ * `runUpdate` updates that install instead, so the sentence stays true of what it describes.
  */
 export const ROUTES = {
     'local-file': 'It was installed from the file {source}, which is not the package index: reinstall it ' +
@@ -234,26 +241,6 @@ export function fill(template, values) {
         return String(values[key]);
     });
 }
-/**
- * `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(' ');
-}
 /**
  * The version string out of the registry's JSON, or a named refusal. Pure — no network here.
  *
@@ -358,88 +345,6 @@ export function upgradeCommand(environment) {
         return ['npm', 'install', '--global', `${PACKAGE}@latest`];
     return ['npm', 'install', '--prefix', environment.root, `${PACKAGE}@latest`];
 }
-/**
- * Run the installer, capture what it said, return both. The only side effect in this module.
- *
- * 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.
- *
- * 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;
-}
 /**
  * `10` rather than `10.0`, because the sentence is read by a person, not parsed.
  *
@@ -451,6 +356,40 @@ export function compareVersions(installed, latest) {
 export function seconds(timeout) {
     return String(timeout);
 }
+/**
+ * The kept install `--install` left at `keptPrefix()` (J51-4), or `null` when there is none to
+ * patch. A local read and nothing more — no network, no spawn.
+ *
+ * WHY `--update` LOOKS FOR IT. From an `npx` cache there is nothing to update in place, but the
+ * hosts do not launch the cache: `--install` recorded the kept install's `cli.js`. So an operator
+ * who types `npx -y bantamkit-mcp@latest --update` is asking about THAT install, and it is a
+ * `--prefix` tree `npm install --prefix` updates in place (measured: 0.32.1 to 0.33.0, exit 0).
+ *
+ * THERE IS ONE ONLY WHEN ALL OF THIS HOLDS, and anything short of it is `null` — which leaves
+ * today's `ephemeral` refusal exactly as it was:
+ *
+ *   - the kept manifest (`keptManifest`, never respelled) is readable JSON with a non-blank
+ *     string `version`;
+ *   - `installEnvironment` on the kept `cli.js` says it is NOT the global tree. npm writes a
+ *     `package.json` at a `--prefix` it installed into, so a real kept install always passes.
+ *     One without it would render `npm install --global`, which updates some other install and
+ *     reports success about this one — worse than refusing.
+ */
+export function keptInstall(prefix = keptPrefix()) {
+    let version;
+    try {
+        version = JSON.parse(readFileSync(keptManifest(prefix), 'utf8')).version;
+    }
+    catch {
+        return null;
+    }
+    if (typeof version !== 'string' || version.trim() === '')
+        return null;
+    const environment = installEnvironment(keptCli(prefix));
+    if (environment.global)
+        return null;
+    return { version, environment };
+}
 /**
  * The whole flag: ask the index, compare, and act — or refuse, by name.
  *
@@ -566,7 +505,7 @@ export async function runUpdate(out, err, installed, packageDirectory, options =
     let shape;
     let recorded;
     try {
-        const install = currentInstall();
+        const install = (options.install ?? currentInstall)();
         shape = install.shape;
         recorded = install.source;
     }
@@ -580,9 +519,24 @@ export async function runUpdate(out, err, installed, packageDirectory, options =
     // path could not be read — `registry`, where the route is this flag itself, and `checkout`,
     // whose tree IS the thing to update. The running package directory is not a guess: it is
     // where the code being executed lives, and it is the tree the route says to `git pull`.
-    const origin = { shape, source: recorded ?? packageDirectory };
+    let origin = { shape, source: recorded ?? packageDirectory };
+    let current = installed;
+    let chosen = options;
+    // J51-5: an `npx` cache WITH a kept install updates the kept install — its version is the one
+    // compared and printed, and its prefix is where npm points — through exactly the registry
+    // route's lines. Decided HERE and not in `update()`, so `update()` stays a function of its
+    // arguments and never of whatever `~/.bantamkit/mcp` the machine running it happens to hold.
+    // No kept install: nothing below changes and the `ephemeral` refusal is today's.
+    if (shape === 'ephemeral') {
+        const kept = keptInstall();
+        if (kept !== null) {
+            origin = { shape: 'registry', source: kept.environment.root };
+            current = kept.version;
+            chosen = { ...options, environment: kept.environment };
+        }
+    }
     try {
-        out(`${await update(installed, origin, options)}\n`);
+        out(`${await update(current, origin, chosen)}\n`);
     }
     catch (e) {
         if (!(e instanceof UpdateRefused))

package/package.json

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