bantamkit 0.32.0__tar.gz → 0.33.0__tar.gz

{bantamkit-0.32.0 → bantamkit-0.33.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: bantamkit
-Version: 0.32.0
+Version: 0.33.0
 Summary: bantamweight tooling — harness primitives that lift small-model agents
 License-Expression: MIT
 Requires-Python: >=3.11

{bantamkit-0.32.0 → bantamkit-0.33.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.0 → bantamkit-0.33.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.0 → bantamkit-0.33.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.0 → bantamkit-0.33.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.33.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.33.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.33.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.0 → bantamkit-0.33.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.0"
+__version__ = "0.33.0"

{bantamkit-0.32.0 → bantamkit-0.33.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

{bantamkit-0.32.0 → bantamkit-0.33.0}/src/bantamkit/mcpserver.py

@@ -8,6 +8,7 @@ import hashlib
 import json
 import os
 import platform
+import stat as stat_module
 import sys
 from collections.abc import Callable, Iterable, Iterator
 from contextlib import contextmanager
@@ -1014,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"})
 
 
@@ -1038,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
@@ -1219,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
@@ -1515,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
@@ -1659,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`
@@ -1783,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"),
@@ -1799,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"),
     ]
 
@@ -2042,10 +2070,80 @@ def _build_memory(args: argparse.Namespace) -> Memory:
     if args.store is not None:
         if not args.store:
             raise SystemExit("--store requires a non-empty path")
+        _check_store_flag(args.store)
         return Memory(store=args.store, k=args.k, index_budget=args.index_budget)
     return Memory.layered(start=args.start, k=args.k, index_budget=args.index_budget)
 
 
+def _check_store_flag(raw: str) -> None:
+    """`--store` may name a store that is missing, never one that is not a store.
+
+    THIS CHECK IS RESTORED, NOT INVENTED, and the distinction is the point. Until the
+    project layer was built lazily there WAS a `--store` validation, and it was entirely
+    accidental: the constructor ran `mkdir(parents=True)`, so a `--store` pointing at a
+    regular file or at a path under a directory that does not exist took the process down
+    with an `OSError` traceback out of `pathlib`. `test_statusline.py::
+    test_the_flag_returns_before_anything_a_server_would_touch` depends on it -- it arms
+    `--store <a regular file>` as a trap and shows `--statusline` walking past it -- and a
+    lazy layer disarms the trap by making that same argv exit 0. The honest way to keep
+    that test true is to mean the refusal on purpose.
+
+    IT IS `layers._pinned_store`'s CHECK MINUS ONE ARM, and the missing arm is deliberate
+    and measured. The pin refuses a path that is not there ("nothing was created"); this
+    flag does NOT, and must not, for two reasons that are both already pinned elsewhere in
+    this repository:
+
+    - The sibling CLI's identical flag is contracted to CREATE one. `tools/conformance/
+      suites/memorycli.mjs` carries `status-creates-a-missing-store`, `--store {BED}/nowhere`
+      over an empty bed, whose whole job is to say the two runtimes create the same two
+      directories there. Refusing a missing `--store` here would put two flags of the same
+      name, in two programs of the same product, in direct contradiction.
+    - "Missing" is no longer a broken state anywhere in this program. The walk designates a
+      project store without creating it, and the first save brings it into existence or
+      refuses by name (`store._ensure_dirs`). A `--store` at a path that is not there is
+      that same designated state, reached by being told instead of by searching. MEASURED:
+      requiring existence here reddened 14 tests that have nothing to do with this defect
+      -- `test_tool_manifest.py` ×7, `test_mcpserver.py` ×6, `test_mcp_endpoint.py` -- every
+      one of them a fixture naming a store under `tmp_path` it never made, because that is
+      what this flag has always meant.
+
+    What is left is the arm the accident actually covered and the only one it covered: a
+    `--store` that names something which EXISTS and is NOT A DIRECTORY. That is not a store
+    and never becomes one -- `mkdir` under it is ENOTDIR on both runtimes and on every
+    platform, the one row of the errno table where they already agree -- so it is refused
+    here, by name, before a transport exists.
+
+    `FileNotFoundError` and not an errno comparison: the absent case is selected by the
+    exception CPython raises for it, which `runtime-ts`' `pyfs` shim raises under the same
+    name. Every other `stat` failure -- a permission wall on the parent, a symlink loop --
+    is a real fault about a path the operator named, and it keeps the pin's sentence.
+
+    `os.stat` rather than `Path.is_dir()`, and that too is `_pinned_store`'s reasoning:
+    `is_dir()` swallows `PermissionError` and answers False, which would report an
+    operator's real store as a typo. A single named path gets the accurate reason.
+
+    `SystemExit` and not `MemoryValidationError`, so that both halves of this flag's
+    refusal family read the same way on the terminal: `--store requires a non-empty path`
+    is already bare on stderr at exit 1, and the port spells both as `Refusal`.
+    """
+    # NOT `expanduser()`, unlike the pin. `Memory(store=...)` builds `Path(root)` from this
+    # string verbatim, so expanding here would check one path and serve another: `--store
+    # ~/x` left unexpanded by the shell would pass a check against the home directory and
+    # then build a store in a directory literally named `~`. The check must stat the path
+    # the store is going to be.
+    store = Path(raw)
+    try:
+        info = os.stat(store)
+    except FileNotFoundError:
+        return  # designated, not broken: the first save makes it or refuses by name
+    except OSError as e:
+        raise SystemExit(
+            f"--store is unreachable: {store}: {e.strerror}; nothing was created"
+        ) from e
+    if not stat_module.S_ISDIR(info.st_mode):
+        raise SystemExit(f"--store is not a directory: {store}")
+
+
 def _print_mcp_report(args: argparse.Namespace) -> None:
     """`--mcp-report`: the joined report on stdout, then return. No transport, no server.
 
@@ -2184,9 +2282,43 @@ def _refuse_update(sentence: str) -> NoReturn:
 
 
 def main() -> None:
+    """Dispatch one invocation, and hand a refusal to the operator as a SENTENCE.
+
+    THIS ARM IS A PARITY DEFECT BEING CLOSED, not a nicety. `runtime-ts/src/cli.ts` has
+    caught `BantamError` at its top level and written `bantamkit-mcp: <message>` at exit 1
+    since it was written, and `bantamkit/memory/__main__.py` was handed the same defect and
+    fixed the same way for the operator memory CLI. This CLI never got it, so the identical
+    refusal -- `BANTAMKIT_MEMORY_DIR=/nope/pinned`, one sentence that already names the
+    directory and says nothing was created -- was one clean line on Node and a two-stage
+    CPython traceback on Python, carrying this repository's absolute paths and line numbers
+    in place of the store the operator asked about. Nothing covered it, so the suite was
+    green over it.
+
+    `BantamError` AND NOTHING WIDER, in `__main__.py`'s own words: a bug in bantamkit is
+    still a traceback, because that one IS a report for a maintainer. What is caught is the
+    class of failures that are ABOUT the operator's store, and every one of them already
+    carries a sentence that names the directory and says what the consequence would have
+    been -- including `_ensure_dirs`' new one, which is the whole reason a cwd of `/` is now
+    a refused write rather than a dead process.
+
+    `SystemExit` is deliberately not caught: argparse's usage errors are exit 2, and this
+    file's own flag refusals are already their own sentence on stderr.
+
+    Written through `sys.stderr.buffer`, like every other refusal in this file, so the line
+    ends LF on Windows too and cannot drift from the port's `process.stderr.write`.
+    """
     if MCPServer is None:
         raise SystemExit(_INSTALL_HINT)
     args = _parse_args()
+    try:
+        _dispatch(args)
+    except BantamError as e:
+        sys.stderr.buffer.write(f"bantamkit-mcp: {e}\n".encode())
+        sys.stderr.buffer.flush()
+        raise SystemExit(1) from e
+
+
+def _dispatch(args: argparse.Namespace) -> None:
     # Before `_build_memory`, which touches the filesystem, and before the server exists at
     # all -- the Node arm returns from `main` here too, ahead of `new RawStdioTransport()`.
     if args.assets_root:
@@ -2215,6 +2347,14 @@ def main() -> None:
     # `.bantamkit/memory` directory in whatever cwd they were standing in, and the flags
     # above return before a transport for the same class of reason.
     #
+    # AMENDMENT 2026-09-12 (job48, J48-1). "which is what creates a store" is no longer
+    # true of the sentence's own words: the project layer is built `create=False`, so
+    # `_build_memory` designates a path and creates nothing until a save. The guard stays
+    # exactly where it is, for what remains of the reason -- a person typing a command to
+    # see what it does has not asked for a walk up their filesystem either -- and it stays
+    # because the ORDER is the contract the port shares, not because it is the last thing
+    # standing between a bare invocation and a mkdir.
+    #
     # STDOUT AND EXIT 0, i.e. byte-for-byte what `-h` does on this platform, because the
     # request was "ให้แสดงเหมือน --help" -- show it the way `--help` shows it. `print_help`
     # is the same call argparse's own `-h` action makes, so the two cannot diverge: fix

{bantamkit-0.32.0 → bantamkit-0.33.0}/src/bantamkit/memory/__main__.py

@@ -2,7 +2,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
+model decision" — 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). That position is only coherent if the operator can actually make the
 decision. Measured