bantamkit 0.34.2__tar.gz → 0.35.0__tar.gz

{bantamkit-0.34.2 → bantamkit-0.35.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: bantamkit
-Version: 0.34.2
+Version: 0.35.0
 Summary: Memory MCP server for Claude Code, Cursor, VS Code Copilot and Claude Desktop, plus a Python library that lifts small-model agents. Install once, run offline.
 Project-URL: Homepage, https://github.com/Ink01101011/bantamkit
 Project-URL: Repository, https://github.com/Ink01101011/bantamkit
@@ -55,7 +55,7 @@ easy.
 | [Configuration](#configuration) | Every flag and variable, with its default |
 | [Update](#update) | `--update`, pipx, uv, then restart |
 | [Troubleshooting](#troubleshooting) | Timeouts, refusals, the wrong store |
-| [What it serves](#what-it-serves) | 12 tools, one prompt, two resource templates |
+| [What it serves](#what-it-serves) | 14 tools, one prompt, two resource templates |
 | [Requirements](#requirements) | Python and dependencies |
 | [The asset pack](#the-asset-pack) | `--assets-root`, `BANTAMKIT_ASSETS` |
 | [The operator CLI: `python -m bantamkit.memory`](#the-operator-cli-python--m-bantamkitmemory) | status, lint, compact, archived, archive, restore |
@@ -88,7 +88,8 @@ python -m venv <env>
 ```
 
 `--install` records the venv's console script by absolute path with `"args": []`, so no launch
-needs the network or your shell's PATH. Measured on macOS arm64, it served 12 tools under a GUI
+needs the network or your shell's PATH. Measured on macOS arm64 (served-tools: dated — the
+surface was twelve then), it served 12 tools under a GUI
 app's PATH, `/usr/bin:/bin:/usr/sbin:/sbin`; the Windows layout (`<env>\Scripts\`) was not.
 
 **No network on the target? Carry a wheelhouse.** Download it on a machine with the **same OS,
@@ -96,9 +97,9 @@ CPU architecture and Python minor version** (some wheels, such as `pydantic_core
 one platform only), copy `wheels/` across, and install from it:
 
 ```bash
-python -m pip download "bantamkit[mcp]==0.34.2" -d wheels
+python -m pip download "bantamkit[mcp]==0.35.0" -d wheels
 python -m venv <env>
-<env>/bin/pip install --no-index --find-links wheels "bantamkit[mcp]==0.34.2"
+<env>/bin/pip install --no-index --find-links wheels "bantamkit[mcp]==0.35.0"
 <env>/bin/bantamkit-mcp --install cursor
 ```
 
@@ -247,10 +248,10 @@ pipx upgrade bantamkit                 # pipx
 uv tool upgrade bantamkit              # uv
 ```
 
-`--update` (`check the package index and update this install if it differs, then exit`) is the
-only network access here. An editable install, a local file or a source tree is refused with
-exit 1 and a sentence naming the manual route (for a clone, `git pull`). For a wheelhouse, repeat
-the download and install.
+`--update` (`check the package index and update this install if it differs, then exit`) upgrades
+an install from PyPI with this interpreter's pip; it is the only network access here. An editable
+install, a local file or a source tree is refused with exit 1 and a sentence naming the manual
+route (for a clone, `git pull`). For a wheelhouse, repeat the download and install.
 
 **Then restart the server in the host** (`/mcp` → reconnect in Claude Code; fully restart Claude
 Desktop). `bantamkit_status` prints the version **and the `build_id` of the code answering
@@ -272,7 +273,7 @@ you**; a new version with an old `build_id` means an old process.
 
 ## What it serves
 
-12 tools, the `bantamkit_status` prompt and two resource templates
+It serves 14 tools, the `bantamkit_status` prompt and two resource templates
 (`bantamkit://skills/{name}`, `bantamkit://rubrics/{name}`):
 
 | Tool | What it does |
@@ -286,9 +287,11 @@ you**; a new version with an old `build_id` means an old process.
 | `shiftwork_clock_in` | open a unit of work and get its brief |
 | `shiftwork_clock_out` | close a unit with status and accounting |
 | `shiftwork_status` | report the open cursor |
+| `shiftwork_plan` | read-only: which units of a checkpoint its `depends_on` graph permits to run at once. Never moves the cursor |
+| `work_plan` | turn any `{id, depends_on, priority}` graph into the batches that may run in parallel, plus the widest fan-out |
 | `token_ledger` | what a session cost, read off the host's transcripts |
 | `bantamkit_status` | report store health against its budget |
-| `build_identity` | report the fingerprint of the source on disk, not the executing code |
+| `build_identity` | report the fingerprint of the source on disk, not the executing code — useful when a machine carries two installs under one name |
 
 The document reader `bantamkit_read` left the served tools in job50 (2026-09-12) and stays in the
 library as `bantamkit.docread`.
@@ -303,7 +306,7 @@ under the `[mcp]` extra.
 Contracts, schemas, eval tasks, rubrics and tool manifests ship inside the package.
 `bantamkit-mcp --assets-root` prints the resolved directory and its file count, and
 `BANTAMKIT_ASSETS` overrides it. A build that cannot find the pack fails instead of shipping
-without it.
+without it — deliberately, because the silent version shipped once.
 
 ## The operator CLI: `python -m bantamkit.memory`
 
@@ -342,7 +345,7 @@ git clone https://github.com/Ink01101011/bantamkit
 cd bantamkit
 python -m venv .venv && .venv/bin/pip install -e "runtime-py[dev,mcp]"
 .venv/bin/python -m pytest runtime-py/tests -q
-.venv/bin/ruff check runtime-py
+.venv/bin/ruff check runtime-py tools
 ```
 
 The cross-runtime gate needs Node:

{bantamkit-0.34.2 → bantamkit-0.35.0}/README.md

@@ -27,7 +27,7 @@ easy.
 | [Configuration](#configuration) | Every flag and variable, with its default |
 | [Update](#update) | `--update`, pipx, uv, then restart |
 | [Troubleshooting](#troubleshooting) | Timeouts, refusals, the wrong store |
-| [What it serves](#what-it-serves) | 12 tools, one prompt, two resource templates |
+| [What it serves](#what-it-serves) | 14 tools, one prompt, two resource templates |
 | [Requirements](#requirements) | Python and dependencies |
 | [The asset pack](#the-asset-pack) | `--assets-root`, `BANTAMKIT_ASSETS` |
 | [The operator CLI: `python -m bantamkit.memory`](#the-operator-cli-python--m-bantamkitmemory) | status, lint, compact, archived, archive, restore |
@@ -60,7 +60,8 @@ python -m venv <env>
 ```
 
 `--install` records the venv's console script by absolute path with `"args": []`, so no launch
-needs the network or your shell's PATH. Measured on macOS arm64, it served 12 tools under a GUI
+needs the network or your shell's PATH. Measured on macOS arm64 (served-tools: dated — the
+surface was twelve then), it served 12 tools under a GUI
 app's PATH, `/usr/bin:/bin:/usr/sbin:/sbin`; the Windows layout (`<env>\Scripts\`) was not.
 
 **No network on the target? Carry a wheelhouse.** Download it on a machine with the **same OS,
@@ -68,9 +69,9 @@ CPU architecture and Python minor version** (some wheels, such as `pydantic_core
 one platform only), copy `wheels/` across, and install from it:
 
 ```bash
-python -m pip download "bantamkit[mcp]==0.34.2" -d wheels
+python -m pip download "bantamkit[mcp]==0.35.0" -d wheels
 python -m venv <env>
-<env>/bin/pip install --no-index --find-links wheels "bantamkit[mcp]==0.34.2"
+<env>/bin/pip install --no-index --find-links wheels "bantamkit[mcp]==0.35.0"
 <env>/bin/bantamkit-mcp --install cursor
 ```
 
@@ -219,10 +220,10 @@ pipx upgrade bantamkit                 # pipx
 uv tool upgrade bantamkit              # uv
 ```
 
-`--update` (`check the package index and update this install if it differs, then exit`) is the
-only network access here. An editable install, a local file or a source tree is refused with
-exit 1 and a sentence naming the manual route (for a clone, `git pull`). For a wheelhouse, repeat
-the download and install.
+`--update` (`check the package index and update this install if it differs, then exit`) upgrades
+an install from PyPI with this interpreter's pip; it is the only network access here. An editable
+install, a local file or a source tree is refused with exit 1 and a sentence naming the manual
+route (for a clone, `git pull`). For a wheelhouse, repeat the download and install.
 
 **Then restart the server in the host** (`/mcp` → reconnect in Claude Code; fully restart Claude
 Desktop). `bantamkit_status` prints the version **and the `build_id` of the code answering
@@ -244,7 +245,7 @@ you**; a new version with an old `build_id` means an old process.
 
 ## What it serves
 
-12 tools, the `bantamkit_status` prompt and two resource templates
+It serves 14 tools, the `bantamkit_status` prompt and two resource templates
 (`bantamkit://skills/{name}`, `bantamkit://rubrics/{name}`):
 
 | Tool | What it does |
@@ -258,9 +259,11 @@ you**; a new version with an old `build_id` means an old process.
 | `shiftwork_clock_in` | open a unit of work and get its brief |
 | `shiftwork_clock_out` | close a unit with status and accounting |
 | `shiftwork_status` | report the open cursor |
+| `shiftwork_plan` | read-only: which units of a checkpoint its `depends_on` graph permits to run at once. Never moves the cursor |
+| `work_plan` | turn any `{id, depends_on, priority}` graph into the batches that may run in parallel, plus the widest fan-out |
 | `token_ledger` | what a session cost, read off the host's transcripts |
 | `bantamkit_status` | report store health against its budget |
-| `build_identity` | report the fingerprint of the source on disk, not the executing code |
+| `build_identity` | report the fingerprint of the source on disk, not the executing code — useful when a machine carries two installs under one name |
 
 The document reader `bantamkit_read` left the served tools in job50 (2026-09-12) and stays in the
 library as `bantamkit.docread`.
@@ -275,7 +278,7 @@ under the `[mcp]` extra.
 Contracts, schemas, eval tasks, rubrics and tool manifests ship inside the package.
 `bantamkit-mcp --assets-root` prints the resolved directory and its file count, and
 `BANTAMKIT_ASSETS` overrides it. A build that cannot find the pack fails instead of shipping
-without it.
+without it — deliberately, because the silent version shipped once.
 
 ## The operator CLI: `python -m bantamkit.memory`
 
@@ -314,7 +317,7 @@ git clone https://github.com/Ink01101011/bantamkit
 cd bantamkit
 python -m venv .venv && .venv/bin/pip install -e "runtime-py[dev,mcp]"
 .venv/bin/python -m pytest runtime-py/tests -q
-.venv/bin/ruff check runtime-py
+.venv/bin/ruff check runtime-py tools
 ```
 
 The cross-runtime gate needs Node:

bantamkit-0.35.0/_assets/tools/shiftwork_plan.json

@@ -0,0 +1,25 @@
+{
+  "name": "shiftwork_plan",
+  "description": "Shift-work plan: read-only batch view of a checkpoint — which units its `depends_on` graph permits to run in parallel. Answers `{\"result\": \"plan\", \"batches\", \"ready\", \"sequence\", \"width\", \"cursor\"}`: `ready` is `batches[0]`, the units dispatchable right now, and `width` is the largest batch length, the widest fan-out. Units with status `done` or `dropped` are satisfied — dropped from the graph, and edges pointing at them treated as already resolved; `todo`, `in_progress` and `blocked` stay in it. Every unit has priority 0, because the checkpoint schema has no priority field, so order inside a batch is `plan.units` order. Same refusal sentences as `work_plan` for a duplicate id, an unknown dependency or a cycle, and the same refusals `shiftwork_status` gives for a checkpoint it cannot read. It reports what the dependency graph permits; it does not move the cursor, which is echoed unchanged so the single-pointer contract and the batch view can be read side by side. An orchestrator stays responsible for what it actually dispatches: `depends_on` encodes logical order, not file contention. Never mutates.",
+  "surfaces": [
+    "mcp"
+  ],
+  "parameters": {
+    "properties": {
+      "checkpoint": {
+        "title": "Checkpoint",
+        "type": "string"
+      }
+    },
+    "required": [
+      "checkpoint"
+    ],
+    "type": "object",
+    "title": "shiftwork_planArguments"
+  },
+  "output_schema": {
+    "type": "object",
+    "additionalProperties": true,
+    "title": "shiftwork_planDictOutput"
+  }
+}

bantamkit-0.35.0/_assets/tools/work_plan.json

@@ -0,0 +1,49 @@
+{
+  "name": "work_plan",
+  "description": "Work plan: turn a dependency graph into the batches that may run in parallel. Takes `nodes`, each `{id, depends_on, priority}` — `priority` defaults to 0 — and answers `{\"result\": \"plan\", \"batches\", \"sequence\", \"width\"}`: batch k holds every node whose dependencies all appear in batches below k, `sequence` is those batches flattened in order, and `width` is the largest batch length — the widest fan-out, which is the number an orchestrator needs to decide whether it can afford the batch. Order inside a batch is priority descending, then the order the nodes were given; both halves are contract, because determinism inside a batch is what two implementations are held to. Empty `nodes` is an ANSWER, not a refusal: no batches, no sequence, width 0. Three refusals, checked in this order and one sentence each: `duplicate node id <id>`, `node <id> depends on <dep>, which no node declares`, and `the graph has a cycle: <a> -> <b> -> <a>`. It reports what the graph permits and decides nothing about what may actually be dispatched together — `depends_on` encodes logical order, not file contention, so a batch this tool calls parallel may still hold work that writes one file. Pure computation over the nodes it was handed: it opens no file and takes no path. Never mutates.",
+  "surfaces": [
+    "mcp"
+  ],
+  "parameters": {
+    "properties": {
+      "nodes": {
+        "title": "Nodes",
+        "type": "array",
+        "items": {
+          "type": "object",
+          "properties": {
+            "id": {
+              "type": "string",
+              "description": "The node's identifier, unique across `nodes`"
+            },
+            "depends_on": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              },
+              "description": "Ids this node waits for; every one of them must be declared by some node"
+            },
+            "priority": {
+              "type": "integer",
+              "description": "Tie-break inside a batch, descending. Optional; 0 when absent"
+            }
+          },
+          "required": [
+            "id",
+            "depends_on"
+          ]
+        }
+      }
+    },
+    "required": [
+      "nodes"
+    ],
+    "type": "object",
+    "title": "work_planArguments"
+  },
+  "output_schema": {
+    "type": "object",
+    "additionalProperties": true,
+    "title": "work_planDictOutput"
+  }
+}

{bantamkit-0.34.2 → bantamkit-0.35.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.34.2"
+__version__ = "0.35.0"

{bantamkit-0.34.2 → bantamkit-0.35.0}/src/bantamkit/eventlog.py

@@ -30,11 +30,13 @@ 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 twelve tools take
+  validated output, never a query, never a document row. Nine of the fourteen 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
+  job50 I5 retired them from the roster — and `work_plan` is NOT one of them: its `nodes`
+  is an array of objects, not an array of strings, so the rule does not reach the ids
+  inside it) and among those `skill_audit`'s `root`,
+  `token_ledger`'s `root` and `prices` and the four 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
@@ -69,7 +71,7 @@ from datetime import UTC, datetime, timedelta
 from pathlib import Path
 from typing import Any
 
-from bantamkit.memory.store import ensure_bantamkit_gitignore
+from bantamkit.memory.store import bantamkit_dir_for, 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
@@ -289,11 +291,12 @@ class EventLog:
         # 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
+        #
+        # J54-3: the walk moved into `bantamkit_dir_for` beside the writer it feeds, so the
+        # two creators in this runtime ask the same question in the same words rather than
+        # keeping a copy each. The answer here is unchanged -- a log file is never itself
+        # named `.bantamkit`, so self-or-ancestors and ancestors give the same directory.
+        bantamkit_dir = bantamkit_dir_for(self.path)
         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:

{bantamkit-0.34.2 → bantamkit-0.35.0}/src/bantamkit/mcpserver.py

@@ -30,6 +30,7 @@ from bantamkit import (
     shiftwork,
     skillaudit,
     tokenledger,
+    workplan,
 )
 from bantamkit.assets import AssetNotFound, assets_root, load_skill, load_tool_asset
 from bantamkit.client import BantamError
@@ -1474,6 +1475,24 @@ def build_server(memory: Memory, log: EventLog | None = None) -> Any:
             _record_result(log, "shiftwork_status", lambda: shiftwork.status(checkpoint))
         )
 
+    def work_plan(nodes: list[dict[str, Any]]) -> dict[str, Any]:
+        # `result` is added HERE and not in `workplan.plan`, which is Layer 1 and answers
+        # the computation (`batches`, `sequence`, `width`) rather than a wire shape. The
+        # wire shape is the tool asset's, so the verdict key is put on at the seam that
+        # serves it — the same division `plan_batches` uses one layer down. A refusal
+        # already carries its own `result` and passes through untouched, because
+        # `_record_result` reads that key to write the register's verdict to the log.
+        def answered() -> dict[str, Any]:
+            plan = workplan.plan(nodes)
+            return plan if plan.get("result") == "error" else {"result": "plan", **plan}
+
+        return _noted_dict(_record_result(log, "work_plan", answered))
+
+    def shiftwork_plan(checkpoint: str) -> dict[str, Any]:
+        return _noted_dict(
+            _record_result(log, "shiftwork_plan", lambda: shiftwork.plan_batches(checkpoint))
+        )
+
     # A TOOL and not a resource or an `initialize` field, because the gap RB-P84 names is
     # an AGENT MID-CALL: the host reads `serverInfo` once at handshake and the
     # tool-calling model never sees it, and `resources/read` is a host-facing surface
@@ -1832,6 +1851,8 @@ def build_server(memory: Memory, log: EventLog | None = None) -> Any:
         _from_manifest(skill_audit, "skill_audit"),
         _from_manifest(memory_dream, "memory_dream"),
         _from_manifest(token_ledger, "token_ledger"),
+        _from_manifest(work_plan, "work_plan"),
+        _from_manifest(shiftwork_plan, "shiftwork_plan"),
     ]
 
     server = MCPServer(

{bantamkit-0.34.2 → bantamkit-0.35.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 twelve-tool surface holds to it; `compact` is the one
+model decision" — and the fourteen-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

{bantamkit-0.34.2 → bantamkit-0.35.0}/src/bantamkit/memory/store.py

@@ -286,6 +286,14 @@ def ensure_bantamkit_gitignore(directory: Path, *, created: bool) -> None:
     would leave a `.bantamkit` that git can see (or ignore one it should not), which is
     the whole bug this closes.
 
+    THE CREATORS, ENUMERATED (J54-3), because "anything else" is how one got missed: in
+    THIS runtime there are exactly two -- `MemoryStore._ensure_dirs` and `EventLog._append`
+    -- and both now ask `bantamkit_dir_for` which directory the decision is about, rather
+    than assuming the root's parent is it. `runtime-ts` has a THIRD, `hostinstall`'s
+    `thisCommand`, where npm creates `~/.bantamkit/mcp` for `--install`; there is no npm
+    install path in this runtime (the offline install is Node-only by user ruling), which
+    is why that creator has no counterpart here. `docs/porting.md` carries the row.
+
     NEVER REWRITES. A `.gitignore` that already exists -- whatever its bytes -- is left
     exactly as it is, kept as a second guard even when `created` is `True`: an operator
     who deleted it to commit the directory keeps that decision, and this never diffs its
@@ -313,6 +321,34 @@ def ensure_bantamkit_gitignore(directory: Path, *, created: bool) -> None:
         pass
 
 
+def bantamkit_dir_for(path: Path) -> Path | None:
+    """The `.bantamkit` directory a `mkdir(parents=True)` of `path` would create or fill,
+    or `None` when there is none: `path` itself if it is named `.bantamkit`, otherwise its
+    nearest ancestor that is.
+
+    WHY A WALK AND NOT `path.parent` (J54-3). Every creator has to hand
+    `ensure_bantamkit_gitignore` the directory the decision is ABOUT, and `parent` is the
+    right answer for exactly one shape of path, `<x>/.bantamkit/memory`. A store rooted AT
+    the `.bantamkit` directory (`--store ~/.bantamkit`) or nested deeper under it
+    (`<x>/.bantamkit/memory/extra`) creates a `.bantamkit` whose gitignore decision was
+    taken about the wrong directory -- so no decision was taken at all, and git could see
+    the whole tree. MEASURED, not hypothetical: `~/.bantamkit` on the machine this was
+    found on holds an empty `facts/` and `archive/` beside `memory/`, left by a store once
+    rooted at it, and no `.gitignore`.
+
+    NEAREST AND NOT OUTERMOST, which is the choice `EventLog._append` already made and this
+    function now carries for both creators: under a `<x>/.bantamkit/y/.bantamkit/z` the
+    directory a reader would expect to be ignored is the one the store is actually in.
+
+    READ-ONLY. It looks at names, never at the filesystem, so it is equally valid before or
+    after the mkdir -- but `created` is answered by checking THIS path's existence BEFORE.
+    """
+    for candidate in (path, *path.parents):
+        if candidate.name == ".bantamkit":
+            return candidate
+    return None
+
+
 class MemoryStore:
     def __init__(
         self,
@@ -405,8 +441,16 @@ class MemoryStore:
         # Checked BEFORE the mkdir, per user ruling #2: this is the one moment that can
         # tell whether `.bantamkit` already existed. After the mkdir it unconditionally
         # exists either way, so the answer has to be captured now or not at all.
-        bantamkit_dir = self.root.parent
-        bantamkit_dir_existed_before = bantamkit_dir.exists()
+        #
+        # J54-3: `bantamkit_dir_for`, not `self.root.parent`. The mkdir below is
+        # `parents=True`, so it creates every missing component of `self.root` -- a root
+        # that IS the `.bantamkit` directory, or one nested deeper under it, brought a
+        # `.bantamkit` into existence while the decision was being taken about some other
+        # directory, which meant no decision at all.
+        bantamkit_dir = bantamkit_dir_for(self.root)
+        bantamkit_dir_existed_before = (
+            bantamkit_dir is not None and bantamkit_dir.exists()
+        )
         try:
             (self.root / "facts").mkdir(parents=True, exist_ok=True)
             (self.root / "archive").mkdir(parents=True, exist_ok=True)
@@ -415,7 +459,10 @@ class MemoryStore:
                 f"memory store could not be created: {self.root}; the directory is not"
                 " there and this filesystem would not make it, so nothing was written"
             ) from e
-        ensure_bantamkit_gitignore(bantamkit_dir, created=not bantamkit_dir_existed_before)
+        if bantamkit_dir is not None:
+            ensure_bantamkit_gitignore(
+                bantamkit_dir, created=not bantamkit_dir_existed_before
+            )
 
     # ---- ops ----
 

{bantamkit-0.34.2 → bantamkit-0.35.0}/src/bantamkit/shiftwork.py

@@ -67,7 +67,9 @@ a missing one.
 
 Cursor advance is v1-linear: it moves to the first non-terminal unit in plan
 order and ignores `depends_on` — non-linear plans need a planner unit to
-reorder `plan.units` first.
+reorder `plan.units` first. `plan_batches` below READS `depends_on` and answers
+the batch view, so the module no longer ignores the field; what still ignores it
+is CURSOR ADVANCE, and the batch view is read-only and moves nothing.
 
 No lock: the MCP topology has one orchestrator by construction. The driver's
 O_EXCL lock guards cross-process races this shape does not have, and clock-out
@@ -84,6 +86,7 @@ from typing import Any
 
 import jsonschema
 
+from bantamkit import workplan
 from bantamkit.assets import AssetNotFound, load_schema, load_tool_asset
 from bantamkit.contract import schema_error
 
@@ -550,3 +553,67 @@ def status(checkpoint: str) -> dict[str, Any]:
         "open_questions": len(document["handoff"]["open_questions"]),
         "last_history": history[-1] if history else None,
     }
+
+
+def plan_batches(checkpoint: str) -> dict[str, Any]:
+    """Read-only batch view of a checkpoint. Never mutates.
+
+    The adapter over `workplan.plan`, and it holds no graph logic of its own: a loop over
+    `depends_on` here would be Layer 1's work done in Layer 5. Its whole content is the
+    three decisions below plus the shape it answers in.
+
+    **A `done` or `dropped` unit is SATISFIED**, which is two things and not one: it
+    leaves the graph, AND every edge pointing at it is treated as already resolved. Only
+    the first would be a defect rather than a simplification — `workplan.plan` refuses an
+    edge into an id no node declares, so dropping the unit while keeping the edge would
+    make every checkpoint with one finished unit unplannable, which is every checkpoint
+    after its first clock-out. `todo`, `in_progress` and `blocked` are all still work and
+    all stay in. The terminal pair is `TERMINAL_UNIT_STATUS`, the same constant the
+    driver's success test uses, so "finished" means one thing in this module.
+
+    **Every unit gets priority 0.** The checkpoint schema has no priority field and this
+    design does not add one, so the tie-break inside a batch falls through to the core's
+    insertion order — `plan.units` order, which is the order a reader of the checkpoint
+    already sees.
+
+    **The cursor is ECHOED, never written.** `clock_out` remains the only thing that
+    moves it and stays v1-linear; this tool reports what the graph PERMITS beside the
+    single pointer that says what the driver will actually do next, so an orchestrator
+    can read the two side by side and decide. Advisory, in one direction only.
+
+    Returns `{"result": "plan", "batches", "ready", "sequence", "width", "cursor"}` —
+    `ready` is `batches[0]`, or `[]` when the plan is all terminal, which is an ANSWER
+    and not a refusal. Refusals pass through verbatim in both directions: `_read_valid`'s
+    for a checkpoint that cannot be read or does not validate, and the core's own
+    duplicate-id / unknown-dependency / cycle sentences for a graph that cannot batch.
+    """
+    document, refusal = _read_valid(Path(checkpoint))
+    if refusal is not None:
+        return refusal
+    nodes = [
+        # `depends_on` is required by the schema, so `_read_valid` has already refused a
+        # unit without it and the default below cannot fire here. It is written anyway
+        # because the Node adapter reaches the same mapping and MUST default it too: a
+        # default on one side only is how two runtimes come to disagree about real data.
+        {"id": unit["id"], "depends_on": list(unit.get("depends_on") or []), "priority": 0}
+        for unit in document["plan"]["units"]
+        if unit["status"] not in TERMINAL_UNIT_STATUS
+    ]
+    satisfied = {
+        unit["id"] for unit in document["plan"]["units"] if unit["status"] in TERMINAL_UNIT_STATUS
+    }
+    for node in nodes:
+        node["depends_on"] = [dep for dep in node["depends_on"] if dep not in satisfied]
+
+    answer = workplan.plan(nodes)
+    if answer.get("result") == "error":
+        return answer
+    batches = answer["batches"]
+    return {
+        "result": "plan",
+        "batches": batches,
+        "ready": batches[0] if batches else [],
+        "sequence": answer["sequence"],
+        "width": answer["width"],
+        "cursor": document["plan"]["cursor"],
+    }