bantamkit-mcp 0.32.1 → 0.33.0

package/README.md

@@ -1,7 +1,7 @@
 # bantamkit-mcp
 
 The bantamkit MCP server as a pure-Node package: `npx bantamkit-mcp`, no Python, no
-`uv`, no `pipx`, no interpreter bootstrap. It serves the same fourteen tools, the same
+`uv`, no `pipx`, no interpreter bootstrap. It serves the same twelve tools, the same
 `bantamkit_status` prompt and the same two resource templates as `runtime-py`'s server,
 reads and writes the same memory store, and is checked against the Python server frame by
 frame — 4500+ conformance cases, with every intentional difference written down as a
@@ -323,7 +323,7 @@ the `build_id` of *the code that is answering you*:
 ```
 bantamkit Active 🟢
 version 0.30.0, build sha256:4441619d…
-serving 14 tools, 1 prompt, 2 resource templates
+serving 12 tools, 1 prompt, 2 resource templates
 ```
 
 A version string that moved and a `build_id` that did not means you are reading a config,

package/assets/schemas/shiftwork-checkpoint.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://bantamkit.dev/schemas/shiftwork-checkpoint.json",
   "title": "Shift-work checkpoint contract v1",
-  "$comment": "Encodes checkpoint contract v1 (docs/superpowers/specs/2026-08-10-shift-work-checkpoint-contract-draft.md) plus the two driver-forced deltas: plan.units[].role (model dispatch without reading briefs) and state.external[].until_cmd (machine-checkable wait, replacing prose `until`). Re-planning needs no schema change: a planner unit is just a unit. STRICTNESS POSTURE: `version` is const-pinned to 1 so a reader can refuse unknown majors; every object the driver or a session reads by field name sets additionalProperties:false, and every field the draft's schema block shows on every instance is required (empty arrays are legal, so a fresh checkpoint is cheap to write). The two exceptions are `history[]` and `retro[]` items: those are the free-text annotation space the draft treats as notes, so they allow extra keys (e.g. a session adding `seq` or `tokens`) while still requiring their load-bearing fields. `units[].commits` is optional because the draft only carries it on completed units. `state.external[].status` is a non-empty string rather than an enum: the draft closes the enum for unit status (the driver's SUCCESS test) but never enumerates external status, and inventing values here would reject honest checkpoints. `plan.cursor` must name an existing unit id — JSON Schema cannot express that cross-reference, so the driver checks it structurally and escalates on a dangling cursor. Serialization: checkpoints are YAML for humans per the draft, but the v1 driver reads JSON only (stdlib-only rule), so sessions driven by driver.py write .json; this schema validates the parsed document either way. AMENDMENT (job46/AS-2, docs/roadmap-agent-stack.md): `job.roles` is a THIRD v1 addition, beyond the two driver-forced deltas named above, and it is OPTIONAL — a checkpoint that omits it is exactly the document the rest of this comment describes, and every checkpoint written before it existed still validates unchanged. Both CLAUDE.md files say the model a unit runs on is `per role, never random, always logged`; logged it was, in `history[]`/`retro[]`, which are the two objects here that allow extra keys, so nothing could ever compare the model a role was ALLOWED to use against the model that answered. `job.roles` is that declaration, and it sits on `job` because that is where a reader already looks for the rules binding every unit. It is a MAP (unit role -> the model identifiers that role may report), not a record the driver reads by fixed field name, so the closure the rest of this file spells `additionalProperties: false` is spelled here as `propertyNames` over the SAME three names `plan.units[].role` enumerates, with `additionalProperties` carrying the value schema once instead of three times: a key outside the role enum is refused, and so is a value that is not a non-empty array of non-empty strings (an empty list would be a rule no session could satisfy, which is a typo and not a policy). A role the map does not name is unconstrained — declaring one role does not silently forbid the others. The ENFORCEMENT is not here: this file states the contract and the runtimes state the refusal, so no example error text appears in these descriptions. `version` stays 1 because nothing already in the document changes meaning: a reader that ignored `roles` would still read every other field correctly. What it would not do is enforce the rule — and since `job` is closed, an older reader does not ignore the key, it refuses the whole file. That refusal is the intended behaviour and not a gap: opening `job` so an old reader could skip the key is what would make this check bypassable by running an older bantamkit.",
+  "$comment": "Encodes checkpoint contract v1 (docs/superpowers/specs/2026-08-10-shift-work-checkpoint-contract-draft.md) plus the two driver-forced deltas: plan.units[].role (model dispatch without reading briefs) and state.external[].until_cmd (machine-checkable wait, replacing prose `until`). Re-planning needs no schema change: a planner unit is just a unit. STRICTNESS POSTURE: `version` is const-pinned to 1 so a reader can refuse unknown majors; every object the driver or a session reads by field name sets additionalProperties:false, and every field the draft's schema block shows on every instance is required (empty arrays are legal, so a fresh checkpoint is cheap to write). The two exceptions are `history[]` and `retro[]` items: those are the free-text annotation space the draft treats as notes, so they allow extra keys (e.g. a session adding `seq` or `tokens`) while still requiring their load-bearing fields. `units[].commits` is optional because the draft only carries it on completed units. `state.external[].status` is a non-empty string rather than an enum: the draft closes the enum for unit status (the driver's SUCCESS test) but never enumerates external status, and inventing values here would reject honest checkpoints. `plan.cursor` must name an existing unit id — JSON Schema cannot express that cross-reference, so the driver checks it structurally and escalates on a dangling cursor. Serialization: checkpoints are YAML for humans per the draft, but the v1 driver reads JSON only (stdlib-only rule), so sessions driven by driver.py write .json; this schema validates the parsed document either way. AMENDMENT (job46/AS-2, docs/roadmap-agent-stack.md): `job.roles` is a THIRD v1 addition, beyond the two driver-forced deltas named above, and it is OPTIONAL — a checkpoint that omits it is exactly the document the rest of this comment describes, and every checkpoint written before it existed still validates unchanged. Both CLAUDE.md files say the model a unit runs on is `per role, never random, always logged`; logged it was, in `history[]`/`retro[]`, which are the two objects here that allow extra keys, so nothing could ever compare the model a role was ALLOWED to use against the model that answered. `job.roles` is that declaration, and it sits on `job` because that is where a reader already looks for the rules binding every unit. It is a MAP (unit role -> the model identifiers that role may report), not a record the driver reads by fixed field name, so the closure the rest of this file spells `additionalProperties: false` is spelled here as `propertyNames` over the SAME three names `plan.units[].role` enumerates, with `additionalProperties` carrying the value schema once instead of three times: a key outside the role enum is refused, and so is a value that is not a non-empty array of non-empty strings (an empty list would be a rule no session could satisfy, which is a typo and not a policy). A role the map does not name is unconstrained — declaring one role does not silently forbid the others. The ENFORCEMENT is not here: this file states the contract and the runtimes state the refusal, so no example error text appears in these descriptions. `version` stays 1 because nothing already in the document changes meaning: a reader that ignored `roles` would still read every other field correctly. What it would not do is enforce the rule — and since `job` is closed, an older reader does not ignore the key, it refuses the whole file. That refusal is the intended behaviour and not a gap: opening `job` so an old reader could skip the key is what would make this check bypassable by running an older bantamkit. AMENDMENT (job50/F8): `handoff.notes` is a FOURTH v1 addition and, like `job.roles`, OPTIONAL, so every checkpoint written before it validates unchanged. `handoff` was the one closed object with nowhere to put a fact that is not an imperative, a question, or a prohibition — a gate baseline, a last commit, a technique worth reusing — and the ledger shows sessions inventing a key for each such fact, being refused, and folding the fact into `next_action` prose instead. The field is a STRING and `handoff` stays `additionalProperties: false`: the defect was the absence of a place for a sentence, not the strictness, and a misspelled `next_action` is refused after this amendment exactly as it was before. The reason it is a string and not a map is in its own description.",
   "type": "object",
   "required": ["version", "job", "plan", "state", "history", "retro", "handoff"],
   "additionalProperties": false,
@@ -192,6 +192,10 @@
           "type": "array",
           "items": {"type": "string", "minLength": 1},
           "description": "Negative space — near-mistakes past sessions made."
+        },
+        "notes": {
+          "type": "string",
+          "description": "OPTIONAL. Free-form prose the next session should read that no other key names: a gate baseline, the last commit, a technique worth reusing. A STRING, not a map: every key sessions tried to carry here before this field existed was an attempt to say one sentence, and a map keyed by fact would grow a key per session — the journal the ≤ 2 KB index posture bans, one level down, and an object no schema can close. The same word means the same thing as `history[].notes`. Empty is legal: `handoff` is shallow-merged at clock-out, so a note outlives the unit that wrote it until a later session overwrites it, and the empty string is that overwrite. Declaring this key is what keeps `handoff` closed — a sentence has a home, so an unknown sibling is still a typo and still refused."
         }
       }
     }

package/assets/tools/bantamkit_read.json

@@ -1,9 +1,7 @@
 {
   "name": "bantamkit_read",
   "description": "Read a document through a program, never its raw bytes. Call with `path` alone for the manifest: the file's kind, every part (sheet, document, page) with its row count and byte size, and every omission the reader had to make (embedded images, blank rows, unmapped glyphs, unread pages). Then call with `part` (and `offset`) to page rows; row 0 is the header and each page ends with a continuation line naming the next offset or the end of the part. Do not page through a part to find a row: estimate its offset from the row count and jump. Supported kinds: text/markdown/code, docx, xlsx, html, mhtml; pdf on the Python server only. The Node server refuses pdf, doc and rtf until its reader is ported. A refusal names what the reader actually saw in the file rather than the format's error.",
-  "surfaces": [
-    "mcp"
-  ],
+  "surfaces": [],
   "parameters": {
     "type": "object",
     "required": [

package/assets/tools/repo_map.json

@@ -1,9 +1,7 @@
 {
   "name": "repo_map",
   "description": "A ranked map of a source tree: every file's definitions, ordered by how central that file is to the files you name in `focus`, truncated to a byte budget. Call it when you are about to work on a file and want to know which OTHER files matter to it — the ports, the callers, the module it reaches through a private helper — rather than reading a directory listing and guessing. `focus` is the file or files you are editing, relative to `root` and POSIX-separated; they are excluded from the listing because you already have them open, and an empty focus gives plain centrality over the whole tree. This is a PRECISION pass and it is not a token saving: the gate this feature was supposed to clear was refuted by measurement — discovery is 0.114% of real prompt tokens, because 97.8% of the bill is cache_read — so a map does not make a session cheaper. What it buys is the right file found sooner. Nothing the scanner cannot read is dropped silently: every unread file resolves into a named omission (unknown-language, unreadable-bytes, size-cap, no-definitions, unreachable, per-file-cap, budget) counted in a footer that is NOT charged to the budget. The budget is UTF-8 BYTES of the listing, not tokens; there is no model tokenizer in either runtime and this tool will not pretend to one.",
-  "surfaces": [
-    "mcp"
-  ],
+  "surfaces": [],
   "parameters": {
     "type": "object",
     "required": [

package/assets/tools/shiftwork_clock_in.json

@@ -1,6 +1,6 @@
 {
   "name": "shiftwork_clock_in",
-  "description": "Shift-work clock-in: schema-validate the checkpoint file and return the brief for the unit at plan.cursor — {unit, role, invariants, handoff, do_not, files} — to hand to the spawned agent verbatim. Structured refusals, never exceptions: result=escalate when handoff.open_questions is non-empty, result=success when every unit is done or dropped, result=error when the checkpoint fails validation.",
+  "description": "Shift-work clock-in: schema-validate the checkpoint file and return the brief for the unit at plan.cursor — {unit, role, invariants, handoff, do_not, files} — to hand to the spawned agent verbatim. Structured refusals, never exceptions: result=escalate when handoff.open_questions is non-empty, result=success when every unit is done or dropped, result=error when the checkpoint fails validation. Clock-in also WRITES: on result=brief, and only then, it appends one line {event: brief, ts, unit, role} to <checkpoint>.log.jsonl — best-effort: a log it cannot write costs the brief nothing (the brief still returns, no error, only the record is lost). clock_out reads those lines back to write `briefed` on every accounting line, so the ledger is no longer one line per clock-out; a brief line carries `event` and no `status`. See docs/shiftwork.md.",
   "surfaces": [
     "mcp"
   ],

package/assets/tools/shiftwork_clock_out.json

@@ -1,6 +1,6 @@
 {
   "name": "shiftwork_clock_out",
-  "description": "Shift-work clock-out: record a finished unit — set its status, advance plan.cursor, merge handoff_patch, push history_entry onto the 5-entry ring — validating the whole mutated document against the checkpoint schema BEFORE an atomic write (a failure writes nothing and returns result=error). Every success appends one accounting line (unit, role, status, ts, plus your accounting fields, e.g. tokens/duration/model) to <checkpoint>.log.jsonl. If the checkpoint's job.roles names this unit's role, accounting.model must be one of that role's model identifiers, spelled exactly \u2014 a model that is not on the list, or none reported at all, is refused before anything is written; a role job.roles omits, and a checkpoint carrying no job.roles, are unconstrained.",
+  "description": "Shift-work clock-out: record a finished unit — set its status, advance plan.cursor, merge handoff_patch, push history_entry onto the 5-entry ring — validating the whole mutated document against the checkpoint schema BEFORE an atomic write (a failure writes nothing and returns result=error). Every success appends one accounting line (unit, role, status, ts, briefed, plus your accounting fields, e.g. tokens/duration_ms/model) to <checkpoint>.log.jsonl, beside the brief lines clock_in writes (a brief line carries `event` and no `status`). `briefed` is written by the runtime, never taken from you — a self-reported value is overwritten by the measured one: true when a brief was issued for this unit since its LAST clock-out (not ever), so a unit re-run inline after a blocked clock-out reads false. It records; it never refuses — a unit that was never clocked in still clocks out, with briefed=false. If the checkpoint's job.roles names this unit's role, accounting.model must be one of that role's model identifiers, spelled exactly \u2014 a model that is not on the list, or none reported at all, is refused before anything is written; a role job.roles omits, and a checkpoint carrying no job.roles, are unconstrained.",
   "surfaces": [
     "mcp"
   ],
@@ -31,8 +31,43 @@
       "accounting": {
         "anyOf": [
           {
-            "additionalProperties": true,
-            "type": "object"
+            "type": "object",
+            "description": "Per-unit cost. Written verbatim, beside ts/unit/role/status, as one line of <checkpoint>.log.jsonl - the ledger the N-sessions experiment reads. The keys named here have fixed meanings so a reader holding only the ledger knows what each number counts, in which unit, and which model produced it; any other key passes through unchanged (a refused key is friction, not safety). Lines written before this schema existed may spell these differently; the schema governs new writes only.",
+            "properties": {
+              "tokens": {
+                "type": "integer",
+                "minimum": 0,
+                "description": "Tokens the unit consumed as the harness's subagent counter reports them: every class it reports (input, output, cache creation) summed, EXCLUDING cache reads. Required, because a unit whose cost is unknown cannot be compared with any other; a rounded self-estimate is allowed only if `note` says it is one."
+              },
+              "cache_read_tokens": {
+                "type": "integer",
+                "minimum": 0,
+                "description": "Tokens the unit's requests served from prompt cache, kept OUT of `tokens` because they dominate a real session's traffic and would swamp the work signal. Optional: omit it when the harness reports no such figure - a written 0 means the unit read nothing from cache."
+              },
+              "duration_ms": {
+                "type": "integer",
+                "minimum": 0,
+                "description": "Wall-clock from spawning the subagent to its final message, in whole milliseconds. Required, and the only duration key with a defined meaning: older lines carry `duration`, `duration_min` or `duration_s`, which this schema neither reads nor renames."
+              },
+              "model": {
+                "type": "string",
+                "description": "The exact identifier of the model the subagent actually ran on (e.g. `claude-sonnet-5`) and nothing else - a caveat about how it was chosen belongs in `note`. Not required here: when the checkpoint's job.roles names this unit's role, clock_out already requires it and refuses a value off that role's list, spelled exactly; a checkpoint with no job.roles leaves it optional. This schema does not change that gate."
+              },
+              "tool_uses": {
+                "type": "integer",
+                "minimum": 0,
+                "description": "Tool calls the subagent made, as the harness counts them. Optional; it is the denominator that makes `tokens` comparable across units of different size (per-unit cost is linear in tool calls, not in unit length)."
+              },
+              "note": {
+                "type": "string",
+                "description": "Free text for what the fields above cannot say: that `tokens` is an estimate, that this is a retry or a second scope under the same unit id, what a harness counter excludes. Anything that is not a model identifier goes here, not in `model`."
+              }
+            },
+            "required": [
+              "tokens",
+              "duration_ms"
+            ],
+            "additionalProperties": true
           },
           {
             "type": "null"

package/assets/tools/skill_audit.json

@@ -1,6 +1,6 @@
 {
   "name": "skill_audit",
-  "description": "Price the skill catalogue every session pays for, and name the collisions in it. A skill's `description:` frontmatter is loaded into the agent's context in EVERY session; its body is read only when the skill is invoked, so the descriptions are the standing bill. Walks `root` for `<marketplace>/<plugin>/<version>/skills/<name>/SKILL.md` and answers one JSON document: `roots` (what was scanned), `skills` (how many were counted), `catalogue_bytes` (UTF-8 bytes of their `description:` values), `findings` and `omissions`. Counted skills plus omissions account for every SKILL.md found — an omission is `{subject, count, size, what}` with subject one of `plugin-not-enabled`, `duplicate-skill`, `stale-version`, `unreadable-file`, `unparsed-frontmatter`, and `what` naming the paths. Pass `enabled` with the plugin ids the host has switched on (`<plugin>@<marketplace>`, as settings.json spells them): the plugin cache also holds disabled plugins and stale version directories, and counting those inflated a real audit to 41 skills / 19,065 B against a true 34 / 14,515. Identity comes from the path: `<marketplace>/<plugin>/<version>/skills/<name>/SKILL.md` relative to `root`; any other shape is a skill outside a plugin, identified by its directory name alone and never excluded by `enabled`. Exactly ONE version directory is resolved per (marketplace, plugin) BEFORE anything is counted, and its skills are that plugin's skills: a name absent from the resolved version is absent, never merged in from another version directory. The winner is the version directory name that sorts LAST in byte order — a byte order and deliberately not a semver comparison, so two runtimes cannot disagree about which directory was read, and so that names which are not versions at all still have a total order (a real cache spells nine of one plugin's directories as content hashes plus the literal `unknown`). What byte order gets wrong is stated rather than hidden: `10.0.0` loses to `9.0.0`, and among non-version names the winner is deterministic but arbitrary; both losers are named in an omission record. Pass `versions` with the version directory the host actually serves, per `<plugin>@<marketplace>` — the `installPath` recorded in the same `installed_plugins.json` the caller reads `enabled` out of — and that plugin is resolved to the named directory whatever byte order would have said; a plugin absent from `versions` falls back to byte order. It is host truth the caller supplies, exactly as `enabled` is, and it is not refused when it names a plugin or a directory this `root` does not hold: a plugin with no version directory here is not resolved at all, and a directory that is not here means every directory that IS here loses and is named in a `stale-version` record. Measured 2026-09-05 on a real cache, byte order picks `unknown` for a plugin whose host serves `1dd995193ba2`, so the installed copy is discarded as a duplicate. The candidates are the version DIRECTORIES on disk — every path spelled `<marketplace>/<plugin>/<version>/skills` — and not the skills that survived reading: a version directory holding no `SKILL.md`, or only files that will not decode or will not parse, still exists and the host still serves it, so an older directory must not win by default. Every SKILL.md under a version directory that did not win is omitted, under one of two subjects: `duplicate-skill` when the resolved version has a skill of the same name standing in for it, `stale-version` when it does not — a skill the resolved version DROPPED, which is on disk, in nobody's bill, and would otherwise be resurrected by the audit. Deduping by the (marketplace, plugin, name) triple instead merges versions rather than choosing between them, and measured 2026-09-05 over a real cache holding a plugin's `0.4.0` (14 skills) and `0.5.0` (5, nine having moved to another plugin) it answered 31 skills / 9,280 bytes where the host serves 22 / 3,396. Inside the resolved version `duplicate-skill` still covers two files claiming the same (marketplace, plugin, name), which is reachable only for skills outside a plugin; the last in scan order wins. Every omission carries the bytes it would have added. A skill is identified as `<plugin>:<name>`, the spelling the host uses and the key `usage` is looked up by, or as `<name>` when it has no plugin. A `description:` folded over several lines is joined with single spaces before it is counted or scanned, and a value written as a whole-value quoted YAML scalar is UNWRAPPED after that fold and before either — the host's parser strips those quotes before a session sees the description, so they are not `catalogue_bytes`, and only quotes INSIDE the value delimit a trigger phrase. The unwrap applies to every frontmatter key, not just `description:`, so `name: \"s\"` is the name `s` and `router: \"true\"` is a router. A value is a whole-value scalar only when it begins with `\"` or `'` AND that opening quote's own closing quote is the value's LAST character, judged by YAML's two escape rules and no others: inside a `\"` scalar a backslash escapes the character after it, so `\\\"` does not close it and the sequences `\\\"` and `\\\\` resolve to `\"` and `\\` while every other `\\x` is left exactly as written; inside a `'` scalar a doubled `''` is one literal apostrophe, so it does not close it and resolves to `'`. Every other value is left as written and scanned literally: `\"a\" and \"b\"` begins and ends with `\"` and is NOT one scalar, because its opening quote closes at index 2, and stripping it would weld the value into one junk phrase and destroy both real ones. A value that OPENS with a quote and never closes one — including one whose last quote is escaped — is a LITERAL: it is not unwrapped, its quote character is counted, its unpaired quote opens no phrase, and it is not a `frontmatter-malformed` finding, which names failures of the BLOCK and not of one value. Measured 2026-09-05 over a real plugin cache: 17 of 31 enabled skills write `description: \"...\"`, so a reader that takes those quotes literally over-prices the majority of a catalogue and buries any phrase quoted inside them. Five findings, each `{kind, severity, skills, detail}`, severity fixed per kind: `shared-trigger-phrase` (high) — two or more skills quote the same literal phrase, so which one fires is a coin flip; `catalogue-over-budget` (high) — `catalogue_bytes` exceeds `budget`; `never-invoked` (low) — a counted skill has zero calls in `usage`; `frontmatter-malformed` (medium) — no frontmatter block, an unterminated one, or no `description:` key, where a block that cannot be parsed at all is also omitted as `unparsed-frontmatter` and adds nothing to `skills` while a parsed block with no description is a skill costing zero bytes; `name-mismatch` (medium) — the frontmatter `name:` is not the skill's directory name. Collisions are EXACT matches on literal quoted phrases and never a similarity score: Jaccard over description tokens was measured across 820 real pairs and refuted, topping out at 0.239 and ranking the two real collisions 118th and 791st of 820. Phrases are the text of the UNWRAPPED value between `\"` pairs, or between `'` pairs where the quote is not flanked by letters — `'don't'` is a contraction, not a phrase — and a phrase with no letter or digit in it is ignored. A router, a skill whose frontmatter carries `router: true`, quotes its siblings' phrases by design and is left out of the phrase index entirely. Four argument failures are refused with their own sentences and never as a partial answer: an unknown `check`, a negative `budget`, a `root` that is missing or is a file, and an EMPTY `root` — which passes JSON-schema `string` and would otherwise resolve to the server's own working directory. Nothing about the CONTENT of the tree refuses. Deterministic: the tool reads nothing but `root`. The three facts a directory of files cannot answer arrive from the caller — call counts in `usage` (`node tools/ledger/tool-usage.mjs --group skill --json`), switched-on plugins in `enabled`, served version directories in `versions` — never by reading the host's transcripts, settings or plugin registry.",
+  "description": "Price the skill catalogue every session pays for, and name the collisions in it. A skill's `description:` frontmatter is loaded into the agent's context in EVERY session; its body is read only when the skill is invoked, so the descriptions are the standing bill. Call it before adding or retiring a skill, or when two skills keep firing on the same phrase. Walks `root` for `<marketplace>/<plugin>/<version>/skills/<name>/SKILL.md` and answers one JSON document: `roots`, `skills` (counted), `catalogue_bytes` (UTF-8 bytes of their `description:` values), `findings` and `omissions`. Read `findings` first — each is `{kind, severity, skills, detail}`: `shared-trigger-phrase` (high; two skills quote the same literal phrase, so which fires is a coin flip), `catalogue-over-budget` (high; only when `budget` is given), `never-invoked` (low; only when `usage` is given), `frontmatter-malformed` and `name-mismatch` (medium). Then `omissions`: counted skills plus omissions account for every SKILL.md found, each `{subject, count, size, what}` with subject one of `plugin-not-enabled`, `duplicate-skill`, `stale-version`, `unreadable-file`, `unparsed-frontmatter`. The tool reads nothing but `root`; the three facts a directory cannot answer come from the caller — `enabled` (plugin ids the host has switched on, `<plugin>@<marketplace>`; the cache also holds disabled plugins, so without it the bill is inflated), `usage` (call counts per skill) and `versions` (the version directory the host serves per plugin; a plugin absent from it gets the directory name that sorts LAST in byte order, which is wrong for `10.0.0` against `9.0.0`). Refused with their own sentence, never as a partial answer: an unknown `check`, a negative `budget`, an EMPTY `root`, a `root` that is missing or is a file. Full rules in docs/skill-audit.md.",
   "surfaces": [
     "mcp"
   ],

package/assets/tools/token_ledger.json

@@ -1,6 +1,6 @@
 {
   "name": "token_ledger",
-  "description": "What a session actually cost, read off the host's own transcripts. Walks `root` for `*.jsonl` transcripts -- the host writes `<cwd-slug>/<session>.jsonl` and `<cwd-slug>/<session>/subagents/*.jsonl` beneath a projects directory, which on this machine is `~/.claude/projects` -- and answers ONE JSON document: `root` (echoed as given), `transcripts` (files read), `lines` (records seen), `requests` (distinct API requests counted), `totals` (the four token classes), `sessions` (one row each), `omissions` (every line that was read and not counted), and `cost` only when `model` is given. This is the ONLY reader of the token counts: `docs/eventlog.md`'s four event streams record decisions, injections, tool calls and the host's arrival log, and NONE of the four carries a token count. Every figure here is the API's own `usage` block and nothing is estimated -- the byte-derived `est` figures in `tools/ledger/token-ledger.mjs` (tool_result bytes, repeated Reads) are deliberately NOT served, because an estimate handed to a model through a tool is an estimate that will be quoted back as a fact. COUNTING IS PER `requestId`, NEVER PER LINE: the host writes one API response as several assistant records -- a text block, a tool_use block -- which all carry the SAME `usage`, so summing records overcounts by the number of content blocks. The dedupe spans the WHOLE walk and not one file, because a resumed session rewrites earlier records verbatim into a new file and a per-file rule counts that request twice; the first occurrence in walk order wins and every later copy is reported as a `duplicate-request` omission rather than dropped in silence. EVERY LINE IS COUNTED OR OMITTED AND THE TWO ADD UP: `lines` equals `requests` plus the sum of every omission's `count`, always, so 'your transcripts hold no usage' is distinguishable from 'I skipped most of your transcripts'. An omission is `{subject, count, what}` with subject one of `undecodable-file`, `unparsed-line`, `not-an-object`, `no-session-id`, `not-an-assistant-record`, `no-usage`, `malformed-usage`, `no-request-id`, `duplicate-request`, and `what` naming the FIRST site as `<relpath>:<line>` plus `and N more` -- bounded on purpose, because a real corpus omits tens of thousands of lines as `not-an-assistant-record` (the host writes attachments, mode changes and titles into the same file) and listing them all would hand back a megabyte of paths in place of an answer. A blank line is not a record and is counted nowhere. A record is counted only when it carries a non-empty `sessionId`, `type` of `assistant`, a `message.usage` object holding ALL FOUR of `input_tokens`, `cache_creation_input_tokens`, `cache_read_input_tokens` and `output_tokens` as non-negative integers below 2**53, and a non-empty `requestId`; the host's other `usage` keys (`service_tier`, `iterations`, `server_tool_use`) are ignored, but a MISSING class is `malformed-usage` and never a zero, because a class defaulted to zero is a token invented. A session row carries `cwd` (the first one seen), `first` and `last` (the minimum and maximum timestamp, as strings), `requests`, `sidechain_requests` and the four classes. `sidechain_requests` is stated rather than hidden because it is an ASYMMETRY a caller would otherwise discover late: a subagent's transcript carries its PARENT's `sessionId` with `isSidechain: true`, so its cost lands in the parent session and is not a session of its own. Sessions are ordered by `first` as a STRING then by session id, both in code-point order, never by parsed time -- the host writes ISO-8601 with a `Z`, for which byte order already is time order. Directory listings are sorted by name in code-point order at every level, so the walk order -- which decides which copy of a duplicated `requestId` counts -- is a property of the tree and not of the filesystem. THERE IS NO TIME WINDOW, deliberately: the operator script has `--days N` and this has nothing, because a tool whose answer depends on the wall clock cannot be pinned by a gate that runs twice, and 'the last 7 days' is a question about a live machine rather than a fact about a corpus. `root` is the CALLER's, exactly as `skill_audit`'s is: this tool reads nothing but `root`, so it can be pointed at a frozen corpus and asked the same question twice. Pass `model` to convert the totals into money through the price table; `assets/pricing/default.json` ships with NO rates on purpose, so `{\"unavailable\": \"no rate recorded for model ...\"}` is the NORMAL answer and not an error path -- a rate enters only as an operator's own fact with its date and its source, through `$BANTAMKIT_PRICES` or through `prices`. `cost` carries `micros` (integer micro-USD), `amount` (a fixed-6-decimal string), a per-class `breakdown` and the `rate` that produced it; the four classes are priced separately because 98.1 % of a real prompt measured here was `cache_read`, and one averaged rate would be wrong in exactly that direction. Four argument failures are refused with their own sentences and never as a partial answer: an EMPTY `root` -- which passes JSON-schema `string` and would otherwise resolve to the server's own working directory -- a `root` that is missing, a `root` that is a file, and an EMPTY `model`, which would otherwise be reported as \"no rate recorded for model ''\" and read as a missing price rather than a missing argument. Nothing about the CONTENT of the tree refuses: a transcript that will not decode, a line that will not parse and a record with no usage are omissions and are counted, because a ledger that refused over one of eight hundred transcripts would have said nothing about the other seven hundred and ninety-nine. The one content failure that DOES refuse is a token total above 2**53-1, which is exact in Python and rounded in JavaScript: the place the two runtimes would part company is a refusal, not a wrong number. Deterministic: the tool reads `root`, and `prices` or `$BANTAMKIT_PRICES` when a `model` is named.",
+  "description": "What a session actually cost, read off the host's own transcripts. Walks `root` for `*.jsonl` transcripts — the host writes `<cwd-slug>/<session>.jsonl` and `<cwd-slug>/<session>/subagents/*.jsonl` beneath `~/.claude/projects` — and answers ONE JSON document: `root`, `transcripts`, `lines`, `requests` (distinct API requests), `totals` (the four classes: `input_tokens`, `cache_creation_input_tokens`, `cache_read_input_tokens`, `output_tokens`), `sessions` (one row each), `omissions`, and `cost` only when `model` is given. Call it to answer 'what did this work cost' from the API's own `usage` blocks — nothing here is estimated. Point `root` at ONE project's slug directory, not the whole projects tree: there is no time window and no summary mode, so a whole-corpus call answers a row per session ever recorded and blows the host's tool-result cap. The four classes are reported and priced separately because on a real prompt 98.1 % of the tokens were `cache_read`. Counting is per `requestId`, never per line: one response is written as several records with the same `usage`, so the dedupe spans the whole walk and every later copy is a `duplicate-request` omission. A subagent's transcript carries its PARENT's `sessionId`, so its cost lands in the parent row as `sidechain_requests`. `lines` equals `requests` plus the sum of every omission's `count`, always. An omission is `{subject, count, what}`; `what` names the first site as `<relpath>:<line>` plus `and N more`. `cost` needs a rate: the shipped price table has none, so `{\"unavailable\": \"no rate recorded for model ...\"}` is the NORMAL answer, not an error; a rate enters through `$BANTAMKIT_PRICES` or `prices`. Refused with their own sentence: an EMPTY `root`, a `root` that is missing or is a file, an EMPTY `model`, and a token total above 2**53-1. The record rule and the nine omission subjects: docs/ledger.md.",
   "surfaces": [
     "mcp"
   ],

package/dist/eventlog.js

@@ -32,10 +32,11 @@
  *   one stray write breaks the wire suite. Nothing in this module names `process.stdout`,
  *   `process.stderr` or `console`.
  * * **Metadata only.** Never a tool argument's value, never a memory body, never a
- *   validated output, never a query, never a document row. Eight of the fourteen tools take
- *   unbounded free text and seven take absolute paths (`bantamkit_read`'s `path` is one,
- *   `skill_audit`'s `root` is another, `repo_map`'s `root` and `focus` are the third and
- *   `token_ledger`'s `root` and `prices` are the fourth; each record carries counts and
+ *   validated output, never a query, never a document row. Most of the twelve tools take
+ *   unbounded free text and two take absolute paths (`skill_audit`'s `root`, and
+ *   `token_ledger`'s `root` and `prices`; `bantamkit_read`'s `path` and `repo_map`'s `root`
+ *   and `focus` were two more until both tools left the roster — job50 I5, 2026-09-12 — and
+ *   their DORMANT handlers still record the same way); each record carries counts and
  *   tokens from a closed set — never the path, never a part name, never a skill id, never a
  *   mapped file, never a session id, never a model name).
  *   Every value written here is an ASCII token from a closed set, a number, or a boolean.

package/dist/mcp/pyargs.js

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

package/dist/mcp/server.d.ts

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

package/dist/mcp/server.js

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

package/dist/memory/cli.js

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

package/dist/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.
  *

package/dist/shiftwork.js

@@ -10,7 +10,9 @@
  *   * the rewritten checkpoint — `json.dumps(document, indent=2) + "\n"`, `.tmp` then
  *     `replace()`;
  *   * the `.log.jsonl` line — `json.dumps(record, sort_keys=True) + "\n"`, append mode,
- *     **never read back**, so a wrong line is never noticed by the code that wrote it;
+ *     read back by exactly ONE thing since job50/F6 — `briefed()`, which looks at the `unit`
+ *     and `event` keys and nothing else — so a wrong line is still never noticed by the
+ *     code that wrote it;
  *   * the returned dict, which the MCP surface hands straight to the model.
  *
  * THE ensure_ascii RULING. `json.dumps` defaults to `ensure_ascii=True` and
@@ -51,15 +53,33 @@
  * accounting line is appended BEFORE the atomic rename, so a partial failure can lose the
  * commit but never the accounting.
  */
-import { loadSchema } from './assets.js';
+import { AssetNotFound, loadSchema, loadToolAsset } from './assets.js';
 import { schemaError } from './contract.js';
-import { pyAppendText, pyJoin, PyOSError, pyReplace, pySuffix, pyUnlink, pyWithSuffix, pyWriteText, pyReadText, } from './memory/pyfs.js';
+import { pyAppendText, pyJoin, PyOSError, pyReplace, pySuffix, pyUnlink, pyWithSuffix, pyWriteText, pyReadText, PyUnicodeDecodeError, } from './memory/pyfs.js';
 import { dumpJson, fromJs, parseJson, PyJSONDecodeError, reprValue } from './pyjson.js';
+import { checkSchema, PyJsonSchemaUnsupported } from './pyjsonschema.js';
 export const SCHEMA_NAME = 'shiftwork-checkpoint';
+/** The accounting line's shape lives on the TOOL asset, not in a second copy here (F5). */
+const TOOL_ASSET = 'shiftwork_clock_out';
+/**
+ * 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 const ACCOUNTING_SHAPE_UNREADABLE = "cannot clock out: the shiftwork_clock_out tool asset cannot be read as the " +
+    "accounting line's shape, so it allows no accounting line";
 /** The driver's SUCCESS test. */
 export const TERMINAL_UNIT_STATUS = new Set(['done', 'dropped']);
 /** The schema's `maxItems` — older entries fall off the ring. */
 export 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 const BRIEF_EVENT = 'brief';
 // ------------------------------------------------------------------- tagged-value sugar
 const str = (v) => ({ t: 'str', v });
 const int = (v) => ({ t: 'int', v: BigInt(v) });
@@ -161,6 +181,100 @@ export function timestamp(now) {
     return (`${pad(when.getUTCFullYear(), 4)}-${pad(when.getUTCMonth() + 1)}-${pad(when.getUTCDate())}` +
         `T${pad(when.getUTCHours())}:${pad(when.getUTCMinutes())}:${pad(when.getUTCSeconds())}Z`);
 }
+// ------------------------------------------------------------------------ F6: the ledger
+/**
+ * `Path(str(path) + ".log.jsonl")` — string concatenation on the NORMALIZED path, not
+ * `with_suffix`, so `cp.json` gets `cp.json.log.jsonl` and not `cp.log.jsonl`.
+ */
+function logPath(path) {
+    return `${path}.log.jsonl`;
+}
+/**
+ * `_record_brief`: append the brief line — best effort, NEVER throws for a store that
+ * refuses writes, never changes the brief.
+ *
+ * One line per call. A unit clocked in twice before it clocks out (a relaunch after a
+ * crashed subagent) leaves two brief lines, and a reader should conclude exactly that. The
+ * ledger records events, not state.
+ *
+ * THE NARROWNESS IS THE PORT OF `except OSError`. `pyAppendText` converts every filesystem
+ * failure into a `PyOSError` — a read-only directory, a directory where the file belongs, a
+ * full disk — and that is the ONLY class swallowed here. Anything else out of this block (a
+ * `TypeError` from a record that could not be dumped, a bug in this function) is not an
+ * OSError in Python and is rethrown here, because hiding it would leave every unit
+ * `briefed: false` forever with no red anywhere. The same `instanceof PyOSError` test the
+ * two write legs of `clockOut` already use, for the same reason.
+ */
+function recordBrief(log, unitId, role, now) {
+    const record = new Map([
+        ['event', str(BRIEF_EVENT)],
+        ['ts', str(timestamp(now))],
+        ['unit', str(unitId)],
+        ['role', role],
+    ]);
+    try {
+        pyAppendText(log, `${dumpJson({ t: 'dict', v: record }, { sortKeys: true })}\n`);
+    }
+    catch (e) {
+        if (!(e instanceof PyOSError))
+            throw e;
+    }
+}
+/**
+ * `str.splitlines()` — the boundaries CPython splits on, which are more than `\n`. The
+ * CRLF and bare CR forms are already folded by `pyReadText` (universal newlines, as
+ * `Path.read_text` folds them), so they do not need to be here, but nothing is lost by it.
+ */
+const SPLITLINES = /\r\n|[\n\r\x0b\x0c\x1c\x1d\x1e\x85\u2028\u2029]/;
+/**
+ * `_briefed`: was a brief issued for `unitId` since its last clock-out? Read off the ledger.
+ *
+ * Walk the ledger in order, tracking only lines that name this unit: a brief line sets the
+ * flag, an accounting line (any line that is not a brief event) clears it. The answer is the
+ * flag at the end — so a clock-out CONSUMES the brief: brief, blocked, re-run without a
+ * clock_in reads `false`; brief, blocked, clock_in, done reads `true`. Detectable false
+ * negatives (a retried clock-out's duplicate line) beat undetectable false positives (an
+ * inline re-run marked briefed because a brief was issued once, ever).
+ *
+ * Reads the ledger the way a reader must: a missing or unreadable log is `false`, a line
+ * that is not JSON or not an object is skipped, never fatal. `record.get("unit") != unit_id`
+ * is a Python `!=`, so a `unit` that is not a string never equals the id; and the read is
+ * `except OSError` — a ledger that does not DECODE as UTF-8 raises out of Python's
+ * `clock_out` (`UnicodeDecodeError` is a `ValueError`), so `PyUnicodeDecodeError` is
+ * rethrown here for the same reason `recordBrief` rethrows: the port does not swallow what
+ * the reference does not.
+ */
+function briefed(log, unitId) {
+    let content;
+    try {
+        content = pyReadText(log);
+    }
+    catch (e) {
+        if (!(e instanceof PyOSError))
+            throw e;
+        return false;
+    }
+    let flag = false;
+    for (const line of content.split(SPLITLINES)) {
+        let record;
+        try {
+            record = parseJson(line);
+        }
+        catch (e) {
+            if (!(e instanceof PyJSONDecodeError))
+                throw e;
+            continue;
+        }
+        if (record.t !== 'dict')
+            continue;
+        const unit = record.v.get('unit');
+        if (unit === undefined || unit.t !== 'str' || unit.v !== unitId)
+            continue;
+        const event = record.v.get('event');
+        flag = event !== undefined && event.t === 'str' && event.v === BRIEF_EVENT;
+    }
+    return flag;
+}
 // ----------------------------------------------------------------------------- clock_in
 /**
  * Validate the checkpoint and return the cursor unit's brief, or a refusal.
@@ -175,7 +289,7 @@ export function timestamp(now) {
  * 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 function clockIn(checkpoint) {
+export function clockIn(checkpoint, options = {}) {
     const { document, refusal } = readValid(pyJoin(checkpoint));
     if (refusal !== null)
         return refusal;
@@ -204,6 +318,10 @@ export function clockIn(checkpoint) {
             ['reason', str(`cursor ${cursor} names no unit`)],
         ]);
     }
+    // F6: the brief is issued, so say so in the ledger — best effort, and only on this branch:
+    // a refusal above issued nothing and therefore records nothing. `pyJoin` is the same
+    // normalisation `clockOut` applies before it builds ITS log path, so the two land in one file.
+    recordBrief(logPath(pyJoin(checkpoint)), cursor, field(unit, 'role'), options.now ?? Date.now() / 1000);
     return dict([
         ['result', str('brief')],
         ['unit', unit],
@@ -305,6 +423,137 @@ function modelRefusal(document, unitId, unit, accounting) {
     }
     return null;
 }
+/**
+ * The accounting line's shape, read off the clock_out TOOL asset — never a second copy.
+ *
+ * J50-7 put the definition on `parameters.properties.accounting` of the tool manifest,
+ * which is what the wire advertises; but the MCP call path enforces only the argument
+ * kind (`dict`), so a host is held to what it was promised only if this function reads
+ * the same file. The declared value is `anyOf: [object, null]`. The null arm is the
+ * caller's (a null line is legal and is not an audit record), so only the object arm is
+ * validated here, wrapped under the key `accounting` so the pointed error names
+ * `accounting` / `accounting/<key>` exactly the way `checkpoint invalid:` names a path —
+ * one renderer for every schema refusal this module makes, not a second one.
+ *
+ * Returns null when the pack CANNOT SUPPLY the shape (J50-9A, ported J50-9B). Reading the
+ * asset gave this module a dependency the roles gate never had, and a `BANTAMKIT_ASSETS`
+ * pack trimmed to `schemas/` — the very pack both runtimes' roles tests build — made
+ * `clockOut` die on `AssetNotFound` where the module promises a structured refusal. The
+ * caller turns null into `ACCOUNTING_SHAPE_UNREADABLE`, fail CLOSED, per J47-4: a
+ * declaration this code cannot read is not a licence. MISSING AND MALFORMED ARE ONE CASE,
+ * not two, because the property is one — the line cannot be checked, so it is not allowed —
+ * and a second sentence would either render an exception message the two runtimes spell
+ * differently, or split one property into per-shape cases that can each be missed. The
+ * shapes folded in, each MEASURED to throw out of `clockOut` before this existed: no
+ * `tools/` dir or no file (`AssetNotFound`); bytes that are not UTF-8
+ * (`PyUnicodeDecodeError`) or not JSON (`SyntaxError`); a manifest without
+ * `parameters.properties.accounting.anyOf` at each step of that path (`TypeError`, five
+ * ways); an `anyOf` with no object arm (a hand-thrown `Error`); and an object arm the
+ * validator refuses as a schema (`PyJsonSchemaUnsupported`, checked here so
+ * `accountingRefusal` only ever validates a schema).
+ */
+function accountingSchema() {
+    let manifest;
+    try {
+        manifest = loadToolAsset(TOOL_ASSET);
+    }
+    catch (e) {
+        // `except (AssetNotFound, OSError, ValueError)`: no `tools/` dir or no file; a file the
+        // OS will not hand over; bytes that are not UTF-8 (`UnicodeDecodeError`, a `ValueError`
+        // there and `PyUnicodeDecodeError` here); text that is not JSON (`JSONDecodeError` there,
+        // `SyntaxError` out of `JSON.parse` here). Anything else is a defect and still escapes.
+        if (e instanceof AssetNotFound ||
+            e instanceof PyOSError ||
+            e instanceof PyUnicodeDecodeError ||
+            e instanceof SyntaxError) {
+            return null;
+        }
+        throw e;
+    }
+    // `isinstance(declared, dict) and key in declared`, at each step of the path. A JSON
+    // array is not a dict, and neither is `null` — `typeof null === 'object'` is not a policy.
+    let declared = manifest;
+    for (const key of ['parameters', 'properties', 'accounting', 'anyOf']) {
+        if (!isDict(declared) || !(key in declared))
+            return null;
+        declared = declared[key];
+    }
+    if (!Array.isArray(declared))
+        return null;
+    // `next((a for a in declared if isinstance(a, dict) and a.get("type") == "object"), None)`
+    const arm = declared.find((a) => isDict(a) && a.type === 'object');
+    if (arm === undefined)
+        return null;
+    const schema = { type: 'object', properties: { accounting: arm } };
+    // `check_schema`, taken HERE so `accountingRefusal` only ever validates a schema. The
+    // port's `validate` runs the same check first and would throw the same class out of
+    // `schemaError`; catching it there would make one property two sites.
+    try {
+        checkSchema(fromJs(schema));
+    }
+    catch (e) {
+        if (e instanceof PyJsonSchemaUnsupported)
+            return null;
+        throw e;
+    }
+    return schema;
+}
+/** `isinstance(x, dict)` for a value that came out of `JSON.parse`. */
+function isDict(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * F5 (job50): an accounting line that does not fit its declared shape is refused.
+ *
+ * Returns the refusal sentence, or null when the clock-out may proceed. The sentence is
+ * a fixed frame around the SAME `schemaError` rendering the checkpoint refusals use
+ * (`checkpoint invalid: …`, `refused to write: …`), over the same `{"accounting": …}`
+ * wrapper the reference builds, so the differential compares like with like. The frame
+ * is J50-8's, read out of `_accounting_refusal` and reproduced to the character:
+ * `unit {unit_id} in role {role} reported an accounting line the schema refuses: {problem}`.
+ *
+ * Checked BEFORE anything is written: no accounting line, no cursor advance, the
+ * checkpoint byte-unchanged. Same posture as `modelRefusal`, same place in `clockOut`.
+ *
+ * THREE RULINGS, decided in Python and binding here:
+ *
+ *   * ORDER. The roles gate runs first and keeps its sentence; this check runs second. A
+ *     non-string `model` under a role `job.roles` names gets the ROLES sentence (`reported
+ *     model 5, which job.roles.implementer does not allow…`); the schema's `model: string`
+ *     fires only when the roles gate is silent (no map, or a role the map omits).
+ *   * NULL STAYS LEGAL. `accounting: null` is not validated — the container is not
+ *     required. In Node that is three spellings of nothing: the JS `null`, an omitted
+ *     argument (`undefined`), and the tagged `{t: 'null'}` the MCP server hands over.
+ *   * ODD KEYS PASS. `additionalProperties: true` — a key the schema does not name is
+ *     written verbatim. Only the NAMED keys have a type, and only `tokens` and
+ *     `duration_ms` are required.
+ *   * NO SHAPE, NO LINE (J50-9A). When the pack cannot supply the shape the line is
+ *     refused with `ACCOUNTING_SHAPE_UNREADABLE`, in this same place, writing nothing —
+ *     not skipped. Skipping is the fail-open this file has already had once (job47's
+ *     `modelRefusal` returning unconstrained on an unreadable declaration). A null line
+ *     is still not validated, so a pack with no `tools/` can clock out a unit that
+ *     reports no accounting.
+ *
+ * One measured fact reproduced rather than reasoned about: under 2020-12 semantics a float
+ * that is a whole number (`1234.0`) IS an `integer`; `12.5`, `"1234"`, `true` and `-1` are
+ * not. `pyjsonschema` already carries that rule (`instance.t === 'float' &&
+ * Number.isInteger(instance.v)`), and the float only survives to reach it on the
+ * parsed-from-bytes route — a JS-object `1234.0` is `1234` before this code sees it.
+ */
+function accountingRefusal(unitId, unit, accounting) {
+    if (accounting === null || accounting === undefined)
+        return null;
+    const line = asPyValue(accounting);
+    if (line.t === 'null')
+        return null;
+    const schema = accountingSchema();
+    if (schema === null)
+        return ACCOUNTING_SHAPE_UNREADABLE;
+    const problem = schemaError(dumpJson(dict([['accounting', line]])), schema);
+    if (problem === null)
+        return null;
+    return `unit ${unitId} in role ${text(field(unit, 'role'))} reported an accounting line the schema refuses: ${problem}`;
+}
 /**
  * Apply the cursor unit's result, validate the WHOLE mutated document, write atomically.
  *
@@ -314,7 +563,10 @@ function modelRefusal(document, unitId, unit, accounting) {
  * 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.
  *
@@ -344,6 +596,9 @@ export function clockOut(checkpoint, unitId, status, handoffPatch, historyEntry,
     const wrongModel = modelRefusal(doc, unitId, unit, accounting);
     if (wrongModel !== null)
         return errorResult(wrongModel);
+    const badLine = accountingRefusal(unitId, unit, accounting);
+    if (badLine !== null)
+        return errorResult(badLine);
     unit.v.set('status', str(status));
     const remaining = subList(plan, 'units').v.filter((u) => !TERMINAL_UNIT_STATUS.has(text(u.v.get('status'))));
     plan.v.set('cursor', remaining.length > 0 ? field(remaining[0], 'id') : str(unitId));
@@ -369,11 +624,14 @@ export function clockOut(checkpoint, unitId, status, handoffPatch, historyEntry,
     ]);
     for (const [key, value] of asPatch(accounting))
         record.set(key, value);
-    // `Path(str(path) + ".log.jsonl")` — string concatenation on the NORMALIZED path, not
-    // `with_suffix`, so `cp.json` gets `cp.json.log.jsonl` and not `cp.log.jsonl`.
-    const logPath = `${path}.log.jsonl`;
+    const log = logPath(path);
+    // F6: `briefed` is MEASURED off the ledger, AFTER the orchestrator's keys are merged, so the
+    // runtime's answer wins over a self-reported one — the order is load-bearing. It is written
+    // on every line, `accounting: null` included: the base shape (ts/unit/role/status) is the
+    // runtime's, and so is this field. Never a refusal.
+    record.set('briefed', { t: 'bool', v: briefed(log, unitId) });
     try {
-        pyAppendText(logPath, `${dumpJson({ t: 'dict', v: record }, { sortKeys: true })}\n`);
+        pyAppendText(log, `${dumpJson({ t: 'dict', v: record }, { sortKeys: true })}\n`);
     }
     catch (e) {
         if (!(e instanceof PyOSError))
@@ -403,7 +661,7 @@ export function clockOut(checkpoint, unitId, status, handoffPatch, historyEntry,
         ['unit', str(unitId)],
         ['status', str(status)],
         ['cursor', field(plan, 'cursor')],
-        ['log', str(logPath)],
+        ['log', str(log)],
     ]);
 }
 // ------------------------------------------------------------------------------- status

package/package.json

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