bantamkit-mcp 0.32.1 → 0.34.0

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/dist/shiftwork.d.ts

@@ -1,9 +1,23 @@
 import { type PyValue } from './pyjson.js';
 export declare const SCHEMA_NAME = "shiftwork-checkpoint";
+/**
+ * J50-9A/9B: the one sentence for a pack that cannot supply the accounting shape. FIXED —
+ * no path, no exception text, no unit — read out of `ACCOUNTING_SHAPE_UNREADABLE` in the
+ * Python module byte for byte, so a differential case can compare the two; which of the
+ * shapes failed is not said, because the property is the same for all of them (see
+ * `accountingSchema`).
+ */
+export declare const ACCOUNTING_SHAPE_UNREADABLE: string;
 /** The driver's SUCCESS test. */
 export declare const TERMINAL_UNIT_STATUS: ReadonlySet<string>;
 /** The schema's `maxItems` — older entries fall off the ring. */
 export declare const HISTORY_RING_SIZE = 5;
+/**
+ * F6: the `event` value of the ledger line `clockIn` appends when it issues a brief. The word
+ * is the register's own — `clock_in` answers `result: "brief"` — so the ledger names the
+ * thing it recorded with the same word the wire used. `BRIEF_EVENT` in `shiftwork.py`.
+ */
+export declare const BRIEF_EVENT = "brief";
 /**
  * `time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime(now))` — UTC, SECOND precision.
  *
@@ -30,7 +44,7 @@ export interface ClockOptions {
  * all-terminal test before the cursor lookup — so an empty plan reports success rather than
  * escalating on its dangling cursor, because `all([])` is true.
  */
-export declare function clockIn(checkpoint: string): PyValue;
+export declare function clockIn(checkpoint: string, options?: ClockOptions): PyValue;
 /**
  * Apply the cursor unit's result, validate the WHOLE mutated document, write atomically.
  *
@@ -40,7 +54,10 @@ export declare function clockIn(checkpoint: string): PyValue;
  * any mutation and before the accounting line. Extended 2026-09-11 (job47): so is a
  * `job.roles` value for that role that is not a list of model identifiers — an unreadable
  * declaration allows no model, and it is refused in the same place, by the same structured
- * return, writing nothing. Mutations: set the unit's status, advance
+ * return, writing nothing. Extended 2026-09-13 (job50/F5): and so is an accounting line
+ * that does not fit the shape the `shiftwork_clock_out` asset declares — checked after the
+ * roles gate, before any mutation, same structured return, nothing written; a null
+ * accounting is not validated and stays legal. Mutations: set the unit's status, advance
  * `plan.cursor` to the first non-terminal unit in PLAN order (`depends_on` is ignored),
  * shallow-merge `handoffPatch` into `handoff`, push `historyEntry` onto the 5-entry ring.
  *