bantamkit 0.32.1__tar.gz → 0.34.0__tar.gz

{bantamkit-0.32.1 → bantamkit-0.34.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: bantamkit
-Version: 0.32.1
+Version: 0.34.0
 Summary: bantamweight tooling — harness primitives that lift small-model agents
 License-Expression: MIT
 Requires-Python: >=3.11
@@ -50,6 +50,63 @@ The uv equivalent is `uvx --from "bantamkit[mcp]" bantamkit-mcp`. uv is not
 installed on the machine this README was measured on, so unlike every other
 command here that one is the documented form rather than a measured one.
 
+> **AMENDED 2026-09-15 (job51) — `pipx run` launches online, and it is offline only while
+> pipx's own cache lasts.** The first form above is fine to try the server. As the command a
+> host runs on every launch, it has a cost. Measured with pipx 1.11.1 and `bantamkit 0.33.0`,
+> with the network cut by pointing the proxy variables at a closed port:
+>
+> ```bash
+> PIPX_HOME=<scratch> https_proxy=http://127.0.0.1:1 HTTPS_PROXY=http://127.0.0.1:1 \
+>   http_proxy=http://127.0.0.1:1 HTTP_PROXY=http://127.0.0.1:1 PIP_PROXY=http://127.0.0.1:1 \
+>   PIP_RETRIES=0 PIP_TIMEOUT=5 pipx run --spec "bantamkit[mcp]==0.33.0" bantamkit-mcp --assets-root
+> ```
+>
+> On a `PIPX_HOME` that had never run it, this exited 1 in 1.33 s. After one run online into
+> the same `PIPX_HOME`, the same command exited 0 in 0.47 s. So a `pipx run` host entry needs
+> the package index on a new machine, after the cache is cleared, and whenever pipx decides
+> its cached environment is stale. That last one is pipx's policy and was not measured here.
+> For a host, install into an environment you keep, as in the next section.
+
+### Install once, run offline
+
+Install into an environment you keep, then let `--install` record that environment's console
+script:
+
+```bash
+python -m venv <env>
+<env>/bin/pip install "bantamkit[mcp]"
+<env>/bin/bantamkit-mcp --install cursor     # or claude, claude-desktop, copilot
+```
+
+After that, no launch needs the network. `--install` writes the absolute path of the console
+script you ran. Measured 2026-09-15 on macOS arm64 against `bantamkit 0.33.0`,
+`<env>/bin/bantamkit-mcp --install cursor` wrote `"command": "<env>/bin/bantamkit-mcp", "args": []`.
+That command answered `initialize` and `tools/list` with 12 tools under the PATH a GUI app
+inherits on macOS, `/usr/bin:/bin:/usr/sbin:/sbin`. The Windows layout (`<env>\Scripts\`) was
+not measured.
+
+**For a machine with no network at all, carry a wheelhouse.** On a connected machine with the
+**same operating system, CPU architecture and Python minor version** as the target:
+
+```bash
+python -m pip download "bantamkit[mcp]==0.33.0" -d wheels
+```
+
+With Python 3.12.13 on macOS arm64 that wrote 33 files. One of them is
+`pydantic_core-2.46.5-cp312-cp312-macosx_11_0_arm64.whl`, which is built for CPython 3.12 on
+arm64 macOS and nothing else. That is why the two machines must match. Copy `wheels/` across,
+then on the target:
+
+```bash
+python -m venv <env>
+<env>/bin/pip install --no-index --find-links wheels "bantamkit[mcp]==0.33.0"
+<env>/bin/bantamkit-mcp --install cursor
+```
+
+Measured in a fresh venv with `PIP_INDEX_URL=http://127.0.0.1:1/` (a closed port): the install
+finished in 1.69 s, and the installed console script served the 12 tools as above. To move to
+a newer version, repeat the download and the install with the new version number.
+
 ### Connect it to a host
 
 **One command, and it writes the entry for you:**
@@ -80,6 +137,14 @@ hand. Every host runs the same command; only the file and the key around it chan
 you installed with `pip` into an environment you keep, replace the `command`/`args` pair
 with the absolute path to the `bantamkit-mcp` console script in that environment.
 
+**Prefer that absolute form over the `pipx run` lines below.** A `pipx run` entry needs the
+package index whenever pipx's cache is cold (measured in the amendment under *Install and
+run*). An entry that names a kept console script needs nothing at launch:
+
+```json
+{"mcpServers": {"bantamkit": {"command": "/absolute/path/to/env/bin/bantamkit-mcp", "args": []}}}
+```
+
 **Claude Code** — one command, no file to edit. `-s user` makes it available in every
 project; drop it for this project only.
 

{bantamkit-0.32.1 → bantamkit-0.34.0}/README.md

@@ -33,6 +33,63 @@ The uv equivalent is `uvx --from "bantamkit[mcp]" bantamkit-mcp`. uv is not
 installed on the machine this README was measured on, so unlike every other
 command here that one is the documented form rather than a measured one.
 
+> **AMENDED 2026-09-15 (job51) — `pipx run` launches online, and it is offline only while
+> pipx's own cache lasts.** The first form above is fine to try the server. As the command a
+> host runs on every launch, it has a cost. Measured with pipx 1.11.1 and `bantamkit 0.33.0`,
+> with the network cut by pointing the proxy variables at a closed port:
+>
+> ```bash
+> PIPX_HOME=<scratch> https_proxy=http://127.0.0.1:1 HTTPS_PROXY=http://127.0.0.1:1 \
+>   http_proxy=http://127.0.0.1:1 HTTP_PROXY=http://127.0.0.1:1 PIP_PROXY=http://127.0.0.1:1 \
+>   PIP_RETRIES=0 PIP_TIMEOUT=5 pipx run --spec "bantamkit[mcp]==0.33.0" bantamkit-mcp --assets-root
+> ```
+>
+> On a `PIPX_HOME` that had never run it, this exited 1 in 1.33 s. After one run online into
+> the same `PIPX_HOME`, the same command exited 0 in 0.47 s. So a `pipx run` host entry needs
+> the package index on a new machine, after the cache is cleared, and whenever pipx decides
+> its cached environment is stale. That last one is pipx's policy and was not measured here.
+> For a host, install into an environment you keep, as in the next section.
+
+### Install once, run offline
+
+Install into an environment you keep, then let `--install` record that environment's console
+script:
+
+```bash
+python -m venv <env>
+<env>/bin/pip install "bantamkit[mcp]"
+<env>/bin/bantamkit-mcp --install cursor     # or claude, claude-desktop, copilot
+```
+
+After that, no launch needs the network. `--install` writes the absolute path of the console
+script you ran. Measured 2026-09-15 on macOS arm64 against `bantamkit 0.33.0`,
+`<env>/bin/bantamkit-mcp --install cursor` wrote `"command": "<env>/bin/bantamkit-mcp", "args": []`.
+That command answered `initialize` and `tools/list` with 12 tools under the PATH a GUI app
+inherits on macOS, `/usr/bin:/bin:/usr/sbin:/sbin`. The Windows layout (`<env>\Scripts\`) was
+not measured.
+
+**For a machine with no network at all, carry a wheelhouse.** On a connected machine with the
+**same operating system, CPU architecture and Python minor version** as the target:
+
+```bash
+python -m pip download "bantamkit[mcp]==0.33.0" -d wheels
+```
+
+With Python 3.12.13 on macOS arm64 that wrote 33 files. One of them is
+`pydantic_core-2.46.5-cp312-cp312-macosx_11_0_arm64.whl`, which is built for CPython 3.12 on
+arm64 macOS and nothing else. That is why the two machines must match. Copy `wheels/` across,
+then on the target:
+
+```bash
+python -m venv <env>
+<env>/bin/pip install --no-index --find-links wheels "bantamkit[mcp]==0.33.0"
+<env>/bin/bantamkit-mcp --install cursor
+```
+
+Measured in a fresh venv with `PIP_INDEX_URL=http://127.0.0.1:1/` (a closed port): the install
+finished in 1.69 s, and the installed console script served the 12 tools as above. To move to
+a newer version, repeat the download and the install with the new version number.
+
 ### Connect it to a host
 
 **One command, and it writes the entry for you:**
@@ -63,6 +120,14 @@ hand. Every host runs the same command; only the file and the key around it chan
 you installed with `pip` into an environment you keep, replace the `command`/`args` pair
 with the absolute path to the `bantamkit-mcp` console script in that environment.
 
+**Prefer that absolute form over the `pipx run` lines below.** A `pipx run` entry needs the
+package index whenever pipx's cache is cold (measured in the amendment under *Install and
+run*). An entry that names a kept console script needs nothing at launch:
+
+```json
+{"mcpServers": {"bantamkit": {"command": "/absolute/path/to/env/bin/bantamkit-mcp", "args": []}}}
+```
+
 **Claude Code** — one command, no file to edit. `-s user` makes it available in every
 project; drop it for this project only.
 

{bantamkit-0.32.1 → bantamkit-0.34.0}/_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."
         }
       }
     }

{bantamkit-0.32.1 → bantamkit-0.34.0}/_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": [

{bantamkit-0.32.1 → bantamkit-0.34.0}/_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": [

{bantamkit-0.32.1 → bantamkit-0.34.0}/_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"
   ],

bantamkit-0.34.0/_assets/tools/shiftwork_clock_out.json

@@ -0,0 +1,95 @@
+{
+  "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, 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"
+  ],
+  "parameters": {
+    "properties": {
+      "checkpoint": {
+        "title": "Checkpoint",
+        "type": "string"
+      },
+      "unit_id": {
+        "title": "Unit Id",
+        "type": "string"
+      },
+      "status": {
+        "title": "Status",
+        "type": "string"
+      },
+      "handoff_patch": {
+        "additionalProperties": true,
+        "title": "Handoff Patch",
+        "type": "object"
+      },
+      "history_entry": {
+        "additionalProperties": true,
+        "title": "History Entry",
+        "type": "object"
+      },
+      "accounting": {
+        "anyOf": [
+          {
+            "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"
+          }
+        ],
+        "default": null,
+        "title": "Accounting"
+      }
+    },
+    "required": [
+      "checkpoint",
+      "unit_id",
+      "status",
+      "handoff_patch",
+      "history_entry"
+    ],
+    "type": "object",
+    "title": "shiftwork_clock_outArguments"
+  },
+  "output_schema": {
+    "type": "object",
+    "additionalProperties": true,
+    "title": "shiftwork_clock_outDictOutput"
+  }
+}

bantamkit-0.34.0/_assets/tools/skill_audit.json

@@ -0,0 +1,70 @@
+{
+  "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. 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"
+  ],
+  "parameters": {
+    "type": "object",
+    "required": [
+      "root"
+    ],
+    "properties": {
+      "root": {
+        "type": "string",
+        "description": "Directory to scan for SKILL.md files, absolute or relative to the server's working directory. It must name a directory: the empty string is refused rather than resolved, because resolving it would audit whatever directory the server happens to be standing in"
+      },
+      "enabled": {
+        "type": "array",
+        "items": {
+          "type": "string"
+        },
+        "description": "Plugin ids that are switched on, `<plugin>@<marketplace>`; when given only skills under those plugins are counted, when omitted every skill under `root` counts"
+      },
+      "usage": {
+        "type": "object",
+        "additionalProperties": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "description": "Skill id (`<plugin>:<name>`) to call count, the caller's own measurement; a counted skill absent from a supplied map is treated as zero"
+      },
+      "check": {
+        "type": "string",
+        "enum": [
+          "all",
+          "phrase",
+          "budget",
+          "frontmatter"
+        ],
+        "description": "Which family of findings to report; default `all`. `skills`, `catalogue_bytes` and `omissions` are reported whatever this says"
+      },
+      "budget": {
+        "type": "integer",
+        "minimum": 0,
+        "maximum": 9007199254740991,
+        "description": "Catalogue byte budget; `catalogue-over-budget` is only reported when this is given"
+      },
+      "versions": {
+        "type": "object",
+        "additionalProperties": {
+          "type": "string"
+        },
+        "description": "Plugin id (`<plugin>@<marketplace>`) to the version directory name the host actually serves; when a plugin is named here that directory is resolved whatever byte order would have said, and a plugin absent from it falls back to byte order"
+      }
+    }
+  },
+  "output_schema": {
+    "properties": {
+      "result": {
+        "title": "Result",
+        "type": "string"
+      }
+    },
+    "required": [
+      "result"
+    ],
+    "type": "object",
+    "title": "skill_auditOutput"
+  }
+}

bantamkit-0.34.0/_assets/tools/token_ledger.json

@@ -0,0 +1,40 @@
+{
+  "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 `~/.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"
+  ],
+  "parameters": {
+    "type": "object",
+    "required": [
+      "root"
+    ],
+    "properties": {
+      "root": {
+        "type": "string",
+        "description": "Directory of host transcripts to walk, absolute or relative to the server's working directory; `~/.claude/projects` is where the host keeps them on this machine. It must name a directory: the empty string is refused rather than resolved, because resolving it would read whatever directory the server happens to be standing in"
+      },
+      "model": {
+        "type": "string",
+        "description": "Model to price the totals as, e.g. the id an assistant record's `message.model` carries. Omit it and no `cost` key is reported at all; name one with no recorded rate and `cost` is `{\"unavailable\": ...}`, which is what the shipped table answers for every model"
+      },
+      "prices": {
+        "type": "string",
+        "description": "Price table to read instead of `$BANTAMKIT_PRICES` or the shipped one; only consulted when `model` is given. A malformed table is a configuration fault and stops with its own sentence, rather than being reported as an unpriced model"
+      }
+    }
+  },
+  "output_schema": {
+    "properties": {
+      "result": {
+        "title": "Result",
+        "type": "string"
+      }
+    },
+    "required": [
+      "result"
+    ],
+    "type": "object",
+    "title": "token_ledgerOutput"
+  }
+}

{bantamkit-0.32.1 → bantamkit-0.34.0}/src/bantamkit/__init__.py

@@ -29,4 +29,4 @@ from bantamkit.structured import StructuredOutputError, extract_json, structured
 # file as its dynamic version source, so the wheel's metadata and the string the MCP
 # server advertises are the same committed bytes, and neither is a function of when
 # someone last ran `pip`.
-__version__ = "0.32.1"
+__version__ = "0.34.0"

{bantamkit-0.32.1 → bantamkit-0.34.0}/src/bantamkit/eventlog.py

@@ -30,12 +30,15 @@ THREE HARD RULES, each with the failure it prevents:
   byte-compares both runtimes' streams; one stray write breaks the wire suite. Nothing
   in this module touches `sys.stderr` or `sys.stdout`.
 * **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
-  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).
+  validated output, never a query, never a document row. Eight of the twelve tools take
+  an unbounded string (counted over `assets/tools/`: a `string` parameter with no `enum`
+  or `maxLength`, or an array of such; `bantamkit_read` and `repo_map` were two more until
+  job50 I5 retired them from the roster) and among those `skill_audit`'s `root`,
+  `token_ledger`'s `root` and `prices` and the three shift-work tools' `checkpoint` are
+  absolute paths; 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. The dormant `bantamkit_read` and `repo_map` handlers keep the same
+  discipline: a token and two counts, never `path`, `part`, `root` or `focus`.
   Every value written here is an ASCII token from a closed
   set, an `int`, or a `bool`.
 * **Never `str(exception)`.** Only `type(exc).__name__`. This is not hypothetical: the
@@ -66,6 +69,8 @@ from datetime import UTC, datetime, timedelta
 from pathlib import Path
 from typing import Any
 
+from bantamkit.memory.store import ensure_bantamkit_gitignore
+
 #: Environment switch. Unset or `off`/`0`/`false`/`no`/empty -> disabled. `on`/`1`/
 #: `true`/`yes` -> the default file inside the memory store. Anything else is taken as
 #: the literal path of the log file.
@@ -273,7 +278,28 @@ class EventLog:
         intent, not a live path.
         """
         assert self.path is not None
+        # AUDIT FINDING (J51-1): this `mkdir(parents=True)` can bring a whole `.bantamkit`
+        # directory into existence on its own -- `BANTAMKIT_EVENT_LOG=on` with a project
+        # store that was never saved to reaches here first -- entirely bypassing
+        # `MemoryStore._ensure_dirs`, which is the only other place a `.bantamkit`
+        # directory gets created. Without this call a store built that way would never get
+        # its self-ignoring `.gitignore`. Cheap and idempotent: a no-op unless one of
+        # `self.path`'s ancestors is literally named `.bantamkit`.
+        #
+        # USER RULING #2 (J51-8a): the ignore file is written only when THIS call is what
+        # creates `.bantamkit`, so existence has to be checked BEFORE the mkdir below --
+        # after it, the directory unconditionally exists and the question is unanswerable.
+        bantamkit_dir = None
+        for parent in self.path.parents:
+            if parent.name == ".bantamkit":
+                bantamkit_dir = parent
+                break
+        bantamkit_dir_existed_before = bantamkit_dir is not None and bantamkit_dir.exists()
         self.path.parent.mkdir(parents=True, exist_ok=True)
+        if bantamkit_dir is not None:
+            ensure_bantamkit_gitignore(
+                bantamkit_dir, created=not bantamkit_dir_existed_before
+            )
         try:
             size = self.path.stat().st_size
         except FileNotFoundError:

{bantamkit-0.32.1 → bantamkit-0.34.0}/src/bantamkit/hostinstall.py

@@ -15,10 +15,12 @@ convenience — a file the host owns and rewrites is a file we should not be mer
 hand.
 
 WHAT THIS WRITES IS WHAT IS RUNNING. The command recorded is this interpreter's own
-`bantamkit-mcp` console script, by absolute path. The Node distribution records
-`npx -y bantamkit-mcp` for the same reason: the thing installed should be the thing that
-answers, and neither side should send a host looking for the other's runtime. The two
-outputs therefore DIFFER by construction and that difference is ruled in `docs/porting.md`.
+`bantamkit-mcp` console script, by absolute path. Since J51-4, the Node side records its
+own absolute command the same way -- `<absolute node> <absolute dist/cli.js>` of the kept
+install under `~/.bantamkit/mcp` -- for the same reason: the thing installed should be the
+thing that answers, and neither side should send a host looking for the other's runtime.
+The two outputs therefore DIFFER by construction (different interpreter, different path)
+and that difference is ruled in `docs/porting.md`.
 
 WHY IT NEVER PROMPTS. An overwrite is exactly the moment a program wants to ask, and asking
 requires a terminal. Measured repeatedly on this machine: Claude Code's `!` channel has no

{bantamkit-0.32.1 → bantamkit-0.34.0}/src/bantamkit/mcpserver.py

@@ -1015,6 +1015,9 @@ class _ArgMetadata(FuncMetadata):  # type: ignore[misc,valid-type]
 
 
 # Tools whose arguments reach the handler exactly as sent — see `_ArgMetadata`.
+# DORMANT — `bantamkit_read` left the roster (job50 I5, 2026-09-12), so no served tool is
+# in this set today and `unwrap_json` is `True` for all twelve. The entry stays so that
+# restoring the roster line restores the property with it.
 _NO_JSON_UNWRAP = frozenset({"bantamkit_read"})
 
 
@@ -1039,6 +1042,9 @@ OFFSET_MAXIMUM = 9007199254740991
 class _DocumentCache:
     """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.
+
     Register entry (i): `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 the row window. Measured on this machine over a 1,538,280-byte
@@ -1220,6 +1226,10 @@ def _record_result(log: EventLog, tool: str, call: Callable[[], dict[str, Any]])
 
 #: The last paragraph of every `repo_map` reply, refusal excepted. FIXED AND MANDATORY.
 #:
+#: DORMANT — `repo_map` left the roster (job50 I5, 2026-09-12). The tail, the empty-listing
+#: sentence and `repo_map_reply` 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
@@ -1516,6 +1526,12 @@ def build_server(memory: Memory, log: EventLog | None = None) -> Any:
     ) -> str:
         """The reader on the MCP surface (job43): `docread` digests, `contract` words it.
 
+        DORMANT — NOT REGISTERED since job50 I5 (user ruling, 2026-09-12): `bantamkit_read`
+        left the roster because the transcript corpus showed it was never called. The
+        reader (`docread`, `docmanifest`, `contract`) and its tests are untouched; this
+        handler, its document cache and `OFFSET_MAXIMUM` are kept, unregistered, so the
+        roster line can return without a rewrite.
+
         The eval pair (`evalrun._document_tools`) already renders a manifest, a page and
         every refusal from these two modules, and this handler makes the SAME calls with
         the path standing in for the document name, so the two surfaces print the same
@@ -1660,6 +1676,11 @@ def build_server(memory: Memory, log: EventLog | None = None) -> Any:
     ) -> str:
         """The ranked definition map on the MCP surface: `repomap` measures, this serves it.
 
+        DORMANT — NOT REGISTERED since job50 I5 (user ruling, 2026-09-12): `repo_map` left
+        the roster because the transcript corpus showed it was never called. The engine
+        (`repomap.py`) and its tests are untouched; this handler is kept, unregistered, so
+        the roster line can return without a rewrite.
+
         THE THREE REFUSALS LIVE HERE AND NOT IN `repomap.py`, and that is deliberate.
         `repo_map()` over a root that does not exist answers an EMPTY map on both runtimes
         — `os.walk` yields nothing for a missing directory and `walkSources`' `readdirSync`
@@ -1784,12 +1805,20 @@ def build_server(memory: Memory, log: EventLog | None = None) -> Any:
     # the server, because the server cannot start without it.
     #
     # `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. Registration order IS the served order
+    # than beside `memory_save` where a reader would look for it, `skill_audit` after
+    # that, `memory_dream` after that and `token_ledger` after that. Registration order
+    # IS the served order
     # (`test_tool_manifest.py::test_the_golden_records_the_order_the_wire_actually_
     # serves`), 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): 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 `_from_manifest` at startup. The handlers below are DORMANT, not gone:
+    # a roster decision, not a deletion of working code.
     tools = [
         _from_manifest(memory_save, "memory_save"),
         _from_manifest(memory_recall, "memory_recall"),
@@ -1800,10 +1829,8 @@ def build_server(memory: Memory, log: EventLog | None = None) -> Any:
         _from_manifest(build_identity_tool, "build_identity"),
         _from_manifest(bantamkit_status, "bantamkit_status"),
         _from_manifest(memory_compact, "memory_compact"),
-        _from_manifest(bantamkit_read, "bantamkit_read"),
         _from_manifest(skill_audit, "skill_audit"),
         _from_manifest(memory_dream, "memory_dream"),
-        _from_manifest(repo_map, "repo_map"),
         _from_manifest(token_ledger, "token_ledger"),
     ]