bantamkit-mcp 0.34.3 → 0.35.1

package/README.md

@@ -5,7 +5,7 @@ store, JSON Schema validation and shift-work tools. Install it from **npm** with
 command, connect it to **Claude Code**, **Claude Desktop**, **Cursor** or **GitHub Copilot in VS
 Code**, and every later launch starts **offline**. No Python, `pip`, `uv`, `pipx` or venv.
 
-It serves the same twelve tools, `bantamkit_status` prompt and two resource templates as the
+It serves the same fourteen tools, `bantamkit_status` prompt and two resource templates as the
 Python server on **PyPI** (`pip install "bantamkit[mcp]"`), and reads and writes the same memory
 store. The two are compared frame by frame: 8,130 conformance cases on 2026-09-15, with every
 intentional difference written down as a ruling.
@@ -50,9 +50,9 @@ npx -y bantamkit-mcp@latest --install claude   # or claude-desktop, copilot, cur
 From 0.34.0 this runs `npm install --prefix ~/.bantamkit/mcp` once (Windows:
 `%USERPROFILE%\.bantamkit\mcp`, not measured) and records
 `<the node that ran it> ~/.bantamkit/mcp/node_modules/bantamkit-mcp/dist/cli.js`, both absolute.
-No later launch needs npx, the registry or your PATH. Measured from the published 0.34.0:
-install exit 0 in 8.14 s; the recorded command then served 12 tools in 0.09 s with the network
-cut.
+No later launch needs npx, the registry or your PATH. Measured from the published 0.34.0
+(served-tools: dated — the surface was twelve then): install exit 0 in 8.14 s; the recorded
+command then served 12 tools in 0.09 s with the network cut.
 
 - **`@latest` matters:** without it npx may reuse an older cached resolve.
 - **It skips npm when the kept install already reports this version or a newer one.** It never
@@ -235,10 +235,15 @@ startup. In Claude Code: `/mcp` → reconnect. In Claude Desktop: a full restart
 **Verify with `bantamkit_status`, not the install log.** It reports the version and the
 `build_id` of *the code that is answering you*:
 
+*(A capture from 0.30.0. The version and build-digest bytes are left as a dated transcript
+rather than hand-edited to a number nobody ran; **line 3 is the exception and tracks the
+surface**, for the reason `docs/status.md` gives — the tool count is a live claim this repo
+gates against a running server, and a marker would only hide it from that gate.)*
+
 ```
 bantamkit Active 🟢
 version 0.30.0, build sha256:4441619d…
-serving 12 tools, 1 prompt, 2 resource templates
+serving 14 tools, 1 prompt, 2 resource templates
 ```
 
 A version that moved and a `build_id` that did not means you are reading a config, not a process.

package/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"
+  }
+}

package/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"
+  }
+}

package/dist/eventlog.js

@@ -32,11 +32,14 @@
  *   one stray write breaks the wire suite. Nothing in this module names `process.stdout`,
  *   `process.stderr` or `console`.
  * * **Metadata only.** Never a tool argument's value, never a memory body, never a
- *   validated output, never a query, never a document row. Most of the twelve tools take
- *   unbounded free text and two take absolute paths (`skill_audit`'s `root`, and
- *   `token_ledger`'s `root` and `prices`; `bantamkit_read`'s `path` and `repo_map`'s `root`
- *   and `focus` were two more until both tools left the roster — job50 I5, 2026-09-12 — and
- *   their DORMANT handlers still record the same way); each record carries counts and
+ *   validated output, never a query, never a document row. Nine of the fourteen tools take
+ *   an unbounded string and among those `skill_audit`'s `root`, `token_ledger`'s `root` and
+ *   `prices` and the four shift-work tools' `checkpoint` are absolute paths
+ *   (`bantamkit_read`'s `path` and `repo_map`'s `root` and `focus` were two more until both
+ *   tools left the roster — job50 I5, 2026-09-12 — and their DORMANT handlers still record
+ *   the same way; `work_plan` is NOT one of the nine: its `nodes` is an array of objects,
+ *   not an array of strings, so the rule does not reach the ids inside it); each record
+ *   carries counts and
  *   tokens from a closed set — never the path, never a part name, never a skill id, never a
  *   mapped file, never a session id, never a model name).
  *   Every value written here is an ASCII token from a closed set, a number, or a boolean.

package/dist/mcp/pyargs.d.ts

@@ -31,7 +31,7 @@ import { type PyValue } from '../pyjson.js';
 /** What a parameter accepts. `optional` is `| None = None` in the signature. */
 export interface FieldSpec {
     readonly name: string;
-    readonly kind: 'str' | 'int' | 'bool' | 'dict' | 'dictInt' | 'dictStr' | 'listStr';
+    readonly kind: 'str' | 'int' | 'bool' | 'dict' | 'dictInt' | 'dictStr' | 'listDict' | 'listStr';
     readonly optional: boolean;
     /** `Field(le=...)`: an inclusive ceiling, checked AFTER the lax int parse succeeds. */
     readonly le?: bigint;

package/dist/mcp/pyargs.js

@@ -174,6 +174,16 @@ export const ARG_MODELS = {
             opt('versions', 'dictStr'),
         ],
     },
+    // `work_plan(nodes: list[dict[str, Any]])` on the reference (W4). The only
+    // `list[dict[...]]` on the surface and the reason `listDict` exists: pydantic validates
+    // the list's ITEMS, one error per bad element and in the list's own order, with the
+    // INDEX in the location — `nodes.0`, the way `listStr` reports it. `dict[str, Any]` puts
+    // no constraint on what is INSIDE a node, so `{}` and `{'id': 5}` both validate here and
+    // reach `workplan.plan`, exactly as they do on the reference.
+    work_plan: { model: 'work_planArguments', fields: [req('nodes', 'listDict')] },
+    // `shiftwork_plan(checkpoint: str)` — the same one strict `str` the other four
+    // shift-work tools take.
+    shiftwork_plan: { model: 'shiftwork_planArguments', fields: [req('checkpoint', 'str')] },
 };
 /** `type(value).__name__`, for the `input_type=` half of the sentence. */
 function pyTypeName(value) {
@@ -287,6 +297,28 @@ function checkField(spec, value) {
             }
             return bad.length > 0 ? bad : { value: { t: 'dict', v: coerced } };
         }
+        case 'listDict': {
+            // `list[dict[str, Any]]`. The same shape as `listStr` below with the `dict`
+            // validator on the items: measured against pydantic 2.13, `{'nodes': 'x'}` is one
+            // `list_type` at `nodes` and `{'nodes': [1, {...}, 'z']}` is TWO `dict_type` errors,
+            // `nodes.0` and `nodes.2` — every bad item, not the first.
+            if (value.t !== 'list') {
+                return [{ loc: spec.name, type: 'list_type', msg: 'Input should be a valid list', input: value }];
+            }
+            const bad = [];
+            for (let i = 0; i < value.v.length; i += 1) {
+                const item = value.v[i];
+                if (item.t !== 'dict') {
+                    bad.push({
+                        loc: `${spec.name}.${i}`,
+                        type: 'dict_type',
+                        msg: 'Input should be a valid dictionary',
+                        input: item,
+                    });
+                }
+            }
+            return bad.length > 0 ? bad : { value };
+        }
         case 'listStr': {
             if (value.t !== 'list') {
                 return [{ loc: spec.name, type: 'list_type', msg: 'Input should be a valid list', input: value }];

package/dist/mcp/server.d.ts

@@ -4,13 +4,20 @@ import { EventLog } from '../eventlog.js';
 import type { Memory } from '../memory/component.js';
 import type { RawStdioTransport } from './transport.js';
 /**
- * The twelve, in the order `build_server` lists them — which is the order `tools/list` emits.
+ * The fourteen, in the order `build_server` lists them — which is the order `tools/list` emits.
  *
  * `bantamkit_status` went LAST rather than first, `memory_compact` after it rather than
  * beside `memory_save` where a reader would look for it, `skill_audit` after that,
- * `memory_dream` after that and `token_ledger` after that, for the same reason the reference
- * appends: registration order IS the served order, and appending is the only edit that
- * leaves the others where every existing declaration says they are.
+ * `memory_dream` after that, `token_ledger` after that and `work_plan` then `shiftwork_plan`
+ * after that, for the same reason the reference appends: registration order IS the served
+ * order, and appending is the only edit that leaves the others where every existing
+ * declaration says they are.
+ *
+ * `work_plan` BEFORE `shiftwork_plan` is the reference's order (`mcpserver.py`'s `tools`
+ * list), and it is load-bearing rather than alphabetical: `runtime-py/tests/data/
+ * served-tool-surface.json` pins the served order as a golden and `wire.mjs` compares the
+ * two `tools/list` answers frame by frame, so registering them the other way round is a
+ * red in three places and a wire change nobody asked for.
  *
  * `bantamkit_read` (tenth) and `repo_map` (thirteenth) LEFT this list on the user's ruling
  * of 2026-09-12 (job50, I5), the same ruling that took them out of the reference's
@@ -22,7 +29,7 @@ import type { RawStdioTransport } from './transport.js';
  * its argument model. The handlers below are DORMANT, not gone: a roster decision, not a
  * deletion of working code.
  */
-export declare const MCP_TOOLS: readonly ["memory_save", "memory_recall", "validate_json", "shiftwork_clock_in", "shiftwork_clock_out", "shiftwork_status", "build_identity", "bantamkit_status", "memory_compact", "skill_audit", "memory_dream", "token_ledger"];
+export declare const MCP_TOOLS: readonly ["memory_save", "memory_recall", "validate_json", "shiftwork_clock_in", "shiftwork_clock_out", "shiftwork_status", "build_identity", "bantamkit_status", "memory_compact", "skill_audit", "memory_dream", "token_ledger", "work_plan", "shiftwork_plan"];
 /**
  * The advertisement for one tool, out of its manifest, with the surface checked.
  *

package/dist/mcp/server.js

@@ -43,18 +43,26 @@ import { EventLog } from '../eventlog.js';
 import { PyOSError, asPyOSError, pyReadText } from '../memory/pyfs.js';
 import { fromJs, parseJson, reprValue, toJs } from '../pyjson.js';
 import * as shiftwork from '../shiftwork.js';
+import { plan } from '../workplan.js';
 import { buildIdentity, SERVER_NAME } from './identity.js';
 import { ARG_MODELS, PyValidationFailure, validateArguments } from './pyargs.js';
 import { sdkJson } from './sdkjson.js';
 import { degradedConditions, degradedNotice, SERVED_PROMPTS, SERVED_RESOURCE_TEMPLATES, statusReport, STATUS_NAME, STATUS_PROMPT_DESCRIPTION, STATUS_PROMPT_TAIL, STATUS_PROMPT_TITLE, } from './status.js';
 /**
- * The twelve, in the order `build_server` lists them — which is the order `tools/list` emits.
+ * The fourteen, in the order `build_server` lists them — which is the order `tools/list` emits.
  *
  * `bantamkit_status` went LAST rather than first, `memory_compact` after it rather than
  * beside `memory_save` where a reader would look for it, `skill_audit` after that,
- * `memory_dream` after that and `token_ledger` after that, for the same reason the reference
- * appends: registration order IS the served order, and appending is the only edit that
- * leaves the others where every existing declaration says they are.
+ * `memory_dream` after that, `token_ledger` after that and `work_plan` then `shiftwork_plan`
+ * after that, for the same reason the reference appends: registration order IS the served
+ * order, and appending is the only edit that leaves the others where every existing
+ * declaration says they are.
+ *
+ * `work_plan` BEFORE `shiftwork_plan` is the reference's order (`mcpserver.py`'s `tools`
+ * list), and it is load-bearing rather than alphabetical: `runtime-py/tests/data/
+ * served-tool-surface.json` pins the served order as a golden and `wire.mjs` compares the
+ * two `tools/list` answers frame by frame, so registering them the other way round is a
+ * red in three places and a wire change nobody asked for.
  *
  * `bantamkit_read` (tenth) and `repo_map` (thirteenth) LEFT this list on the user's ruling
  * of 2026-09-12 (job50, I5), the same ruling that took them out of the reference's
@@ -79,6 +87,8 @@ export const MCP_TOOLS = [
     'skill_audit',
     'memory_dream',
     'token_ledger',
+    'work_plan',
+    'shiftwork_plan',
 ];
 /** The served set, for the call path: a name outside it is unknown, whatever `ARG_MODELS` says. */
 const SERVED = new Set(MCP_TOOLS);
@@ -163,6 +173,44 @@ function rpcError(code, message, data) {
 }
 const asDict = (value) => (value.t === 'dict' ? value.v : new Map());
 const asText = (value) => (value && value.t === 'str' ? value.v : '');
+/**
+ * `work_plan`'s `nodes` as `workplan.plan` takes them.
+ *
+ * The reference's model is `list[dict[str, Any]]`, so pydantic guarantees a list of dicts
+ * and NOTHING about what is inside one; `workplan.plan` then reads `node["id"]`,
+ * `node.get("depends_on") or []` and `node.get("priority", 0)` off raw Python objects. This
+ * reproduces those three reads and their defaults.
+ *
+ * A NODE WITH NO `id` RAISES, and raising is the port: `node["id"]` is a `KeyError` on the
+ * reference, whose `str()` is the key in single quotes, so the SDK's envelope reads
+ * `Error executing tool work_plan: 'id'`. Defaulting it here would answer a plan over a
+ * node the reference refused to look at.
+ *
+ * WHERE THE DYNAMIC HALF STOPS, said rather than hidden. Python keeps an id's own type and
+ * this side stringifies it with `str()`'s spelling (`reprValue` for every non-`str`), so a
+ * document mixing `5` and `"5"` is two nodes there and one here, and a non-numeric
+ * `priority` is a `TypeError` there and a 0 here. Both need a node whose types contradict
+ * `assets/tools/work_plan.json`, which nothing in the shift-work corpus produces; they are
+ * named here because an unwritten difference is the one that is found later.
+ */
+function planNodes(value) {
+    const pyText = (v) => (v.t === 'str' ? v.v : reprValue(v));
+    const items = value !== undefined && value.t === 'list' ? value.v : [];
+    return items.map((item) => {
+        const node = item.t === 'dict' ? item.v : new Map();
+        const id = node.get('id');
+        if (id === undefined)
+            throw new BantamError("'id'");
+        const declared = node.get('depends_on');
+        const priority = node.get('priority');
+        return {
+            id: pyText(id),
+            // `list(node.get("depends_on") or [])`: missing, `null` and `[]` are one case.
+            depends_on: declared !== undefined && declared.t === 'list' ? declared.v.map(pyText) : [],
+            priority: priority !== undefined && (priority.t === 'int' || priority.t === 'float') ? Number(priority.v) : 0,
+        };
+    });
+}
 /** `int | None` after validation: the tagged int, or `null` for the default. */
 function asInt(value) {
     return value && value.t === 'int' ? Number(value.v) : null;
@@ -879,6 +927,47 @@ function runTool(name, memory, args, version, log, documents) {
                 return { value: { t: 'str', v: noted(tokenledger.asJson(result)) }, wrapped: true };
             });
         }
+        case 'work_plan':
+            // `depends_on` turned into the batches that may run in parallel, over any task list
+            // the caller hands over. No path, no file, no clock: `workplan.plan` is Layer 1 and
+            // this is the seam that serves it.
+            //
+            // `result` is added HERE and not in `workplan.plan`, which answers the COMPUTATION
+            // (`batches`, `sequence`, `width`) rather than a wire shape. The wire shape is the
+            // tool asset's, so the verdict key goes on at the seam that serves it — the same
+            // division `shiftwork.planBatches` uses one layer down. A refusal already carries its
+            // own `result` and passes through untouched, because `recordResult` reads that key to
+            // write the register's verdict to the log.
+            //
+            // THE MAPPING IS INSIDE THE CLOSURE, not above it, so that a node the core cannot
+            // read raises where the reference raises: within `_record_result`, which records the
+            // exception and re-raises it into the `Error executing tool work_plan:` envelope.
+            return {
+                value: notedDict(recordResult(log, name, () => {
+                    const answer = plan(planNodes(args.get('nodes')));
+                    if ('result' in answer)
+                        return { t: 'dict', v: new Map([['result', { t: 'str', v: 'error' }], ['reason', { t: 'str', v: answer.reason }]]) };
+                    return {
+                        t: 'dict',
+                        v: new Map([
+                            ['result', { t: 'str', v: 'plan' }],
+                            ['batches', { t: 'list', v: answer.batches.map((batch) => ({ t: 'list', v: batch.map((id) => ({ t: 'str', v: id })) })) }],
+                            ['sequence', { t: 'list', v: answer.sequence.map((id) => ({ t: 'str', v: id })) }],
+                            ['width', { t: 'int', v: BigInt(answer.width) }],
+                        ]),
+                    };
+                })),
+                wrapped: false,
+            };
+        case 'shiftwork_plan':
+            // The read-only batch view of a checkpoint. Registered beside `shiftwork_status`
+            // because it is the same kind of thing: a path in, an answer out, and not one byte
+            // written — `test/shiftwork.test.mjs` hashes the checkpoint AND its `.log.jsonl`
+            // before and after to hold that, rather than commenting it.
+            return {
+                value: notedDict(recordResult(log, name, () => shiftwork.planBatches(asText(args.get('checkpoint'))))),
+                wrapped: false,
+            };
         default:
             // `tool_manager.call_tool` raises `ToolError(f"Unknown tool: {name}")`, which the
             // handler turns into an isError result rather than a JSON-RPC error.

package/dist/memory/cli.js

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

package/dist/shiftwork.d.ts

@@ -80,3 +80,36 @@ export declare function clockOut(checkpoint: string, unitId: string, status: str
  * The result is dumped without `sort_keys` on the wire, so that order is observable.
  */
 export declare function status(checkpoint: string): PyValue;
+/**
+ * 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.** `clockOut` 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: `readValid`'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.
+ */
+export declare function planBatches(checkpoint: string): PyValue;

package/dist/shiftwork.js

@@ -47,17 +47,24 @@
  * same place. That makes three refusal strings, not two, and the third is likewise a
  * per-side literal.
  *
- * WHAT IS NOT PORTED, DELIBERATELY. The `depends_on` field is ignored on cursor advance
- * (v1-linear, the Python module's own ruling), there is no lock (the MCP topology has one
- * orchestrator by construction), and log-then-commit ordering is preserved exactly: the
- * accounting line is appended BEFORE the atomic rename, so a partial failure can lose the
- * commit but never the accounting.
+ * WHAT IS NOT PORTED, DELIBERATELY. There is no lock (the MCP topology has one orchestrator
+ * by construction), and log-then-commit ordering is preserved exactly: the accounting line is
+ * appended BEFORE the atomic rename, so a partial failure can lose the commit but never the
+ * accounting.
+ *
+ * `depends_on` USED TO BE LISTED ABOVE, AND NO LONGER BELONGS THERE. `planBatches` below
+ * READS `depends_on` and answers the batch view, so the module no longer ignores the field;
+ * what still ignores it is CURSOR ADVANCE, which stays v1-linear (the Python module's own
+ * ruling) — it moves to the first non-terminal unit in `plan.units` order, and a non-linear
+ * plan still needs a planner unit to reorder `plan.units` first. The batch view is read-only
+ * and moves nothing.
  */
 import { AssetNotFound, loadSchema, loadToolAsset } from './assets.js';
 import { schemaError } from './contract.js';
 import { pyAppendText, pyJoin, PyOSError, pyReplace, pySuffix, pyUnlink, pyWithSuffix, pyWriteText, pyReadText, PyUnicodeDecodeError, } from './memory/pyfs.js';
 import { dumpJson, fromJs, parseJson, PyJSONDecodeError, reprValue } from './pyjson.js';
 import { checkSchema, PyJsonSchemaUnsupported } from './pyjsonschema.js';
+import { plan } from './workplan.js';
 export const SCHEMA_NAME = 'shiftwork-checkpoint';
 /** The accounting line's shape lives on the TOOL asset, not in a second copy here (F5). */
 const TOOL_ASSET = 'shiftwork_clock_out';
@@ -692,3 +699,74 @@ export function status(checkpoint) {
         ['last_history', history.v.length > 0 ? history.v[history.v.length - 1] : { t: 'null' }],
     ]);
 }
+// ------------------------------------------------------------------------- plan_batches
+/**
+ * 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.** `clockOut` 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: `readValid`'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.
+ */
+export function planBatches(checkpoint) {
+    const { document, refusal } = readValid(pyJoin(checkpoint));
+    if (refusal !== null)
+        return refusal;
+    const doc = document;
+    const units = subList(subDict(doc, 'plan'), 'units').v;
+    const terminal = (unit) => TERMINAL_UNIT_STATUS.has(text(unit.v.get('status')));
+    const satisfied = new Set();
+    for (const unit of units) {
+        if (terminal(unit))
+            satisfied.add(text(unit.v.get('id')));
+    }
+    const nodes = [];
+    for (const unit of units) {
+        const u = unit;
+        if (terminal(u))
+            continue;
+        // `list(unit.get("depends_on") or [])`. `depends_on` is REQUIRED by the schema, so
+        // `readValid` has already refused a unit without it and this default cannot fire —
+        // it is written anyway because the reference writes it, and a default on one side
+        // only is how two runtimes come to disagree about real data.
+        const declared = u.v.get('depends_on');
+        const deps = declared !== undefined && declared.t === 'list' ? declared.v.map(text) : [];
+        nodes.push({ id: text(u.v.get('id')), depends_on: deps.filter((dep) => !satisfied.has(dep)), priority: 0 });
+    }
+    const answer = plan(nodes);
+    if ('result' in answer)
+        return errorResult(answer.reason);
+    const batches = answer.batches.map((batch) => ({ t: 'list', v: batch.map(str) }));
+    return dict([
+        ['result', str('plan')],
+        ['batches', { t: 'list', v: batches }],
+        ['ready', batches.length > 0 ? batches[0] : { t: 'list', v: [] }],
+        ['sequence', { t: 'list', v: answer.sequence.map(str) }],
+        ['width', int(answer.width)],
+        ['cursor', field(subDict(doc, 'plan'), 'cursor')],
+    ]);
+}

package/dist/workplan.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Layer 1 — the work-plan planner: `depends_on` turned into batches that may run in parallel.
+ *
+ * A pure function. No filesystem, no clock, no `mcp` import, no dependency: `docs/architecture.md`
+ * puts a deterministic graph planner in Core, and `shiftwork.ts` — which is Layer 5 — is the thing
+ * that will call it, not the thing it lives in.
+ *
+ * WHERE THE SEMANTICS COME FROM. `docs/superpowers/specs/2026-09-18-workplan-dag-design.md`. The
+ * user's own `ex-flow@1.1.0` measured the numbers in that spec, and it is deliberately NOT an
+ * install: `runtime-ts/package.json` declares exactly one runtime dependency,
+ * `@modelcontextprotocol/sdk`, and `docs/porting.md` uses "no runtime dependency is allowed into
+ * `runtime-ts`" as the live justification for three divergence rows. So `ex-flow` is the
+ * SPECIFICATION and this is one of two hand-written implementations held to it — the other being
+ * `runtime-py/src/bantamkit/workplan.py`, written independently so that
+ * `tools/conformance/suites/workplan.mjs` proves an agreement rather than a copy.
+ *
+ * WHAT IS DELIBERATELY LEFT OUT of `ex-flow`'s surface: `deadlineStrategy`, `weightStrategy`,
+ * `fairnessPolicy`/`maxDeferralRounds` aging, `schedulerMode: "throughput"`, `concurrencyCap`,
+ * `resourceCaps`, the clone modes and the config builder. None of the 19 measured checkpoints
+ * supplies a deadline, a weight or a resource class, so every one of them would be untested
+ * surface. `sequence` is `ex-flow`'s `fullSequence` under a shorter name.
+ *
+ * WHAT THIS DOES NOT CLAIM. `depends_on` encodes logical order, not file contention. Measured on
+ * `.shiftwork/checkpoint-job44.json`, whose first batch is twelve units wide, seven of those
+ * twelve name `runtime-ts/src/docread.ts`. The graph says they may run in parallel; the filesystem
+ * does not. This function reports what the graph permits and the orchestrator stays responsible
+ * for what it actually dispatches.
+ */
+/** One task. `priority` is optional and absent means `0` — the checkpoint schema has no such field. */
+export interface PlanNode {
+    id: string;
+    depends_on: string[];
+    priority?: number;
+}
+/** A plan: the batches, the same ids read end to end, and the widest fan-out in the plan. */
+export interface PlanOk {
+    batches: string[][];
+    sequence: string[];
+    width: number;
+}
+/**
+ * A refusal, in the `{result, reason}` shape `shiftwork` already returns, so nothing new is
+ * invented for it. The three sentences are pinned per-side in `test/workplan.test.mjs` because a
+ * sentence both runtimes copied is invisible to the differential.
+ */
+export interface PlanError {
+    result: 'error';
+    reason: string;
+}
+export type PlanResult = PlanOk | PlanError;
+/**
+ * Level-synchronous Kahn: batch *k* holds every node whose dependencies all appear in batches < *k*.
+ *
+ * **Empty input is not an error.** `plan([])` is `{batches: [], sequence: [], width: 0}` — a plan
+ * with nothing left to do is the answer, the same reasoning `clock_in` applies when an all-terminal
+ * checkpoint reports success rather than escalating on a dangling cursor.
+ *
+ * **The three refusals are checked in a fixed order** — duplicate id, then unknown dependency, then
+ * cycle — because a graph can carry two faults at once and both runtimes have to name the same one.
+ */
+export declare function plan(nodes: readonly PlanNode[]): PlanResult;

package/dist/workplan.js

@@ -0,0 +1,126 @@
+/**
+ * Layer 1 — the work-plan planner: `depends_on` turned into batches that may run in parallel.
+ *
+ * A pure function. No filesystem, no clock, no `mcp` import, no dependency: `docs/architecture.md`
+ * puts a deterministic graph planner in Core, and `shiftwork.ts` — which is Layer 5 — is the thing
+ * that will call it, not the thing it lives in.
+ *
+ * WHERE THE SEMANTICS COME FROM. `docs/superpowers/specs/2026-09-18-workplan-dag-design.md`. The
+ * user's own `ex-flow@1.1.0` measured the numbers in that spec, and it is deliberately NOT an
+ * install: `runtime-ts/package.json` declares exactly one runtime dependency,
+ * `@modelcontextprotocol/sdk`, and `docs/porting.md` uses "no runtime dependency is allowed into
+ * `runtime-ts`" as the live justification for three divergence rows. So `ex-flow` is the
+ * SPECIFICATION and this is one of two hand-written implementations held to it — the other being
+ * `runtime-py/src/bantamkit/workplan.py`, written independently so that
+ * `tools/conformance/suites/workplan.mjs` proves an agreement rather than a copy.
+ *
+ * WHAT IS DELIBERATELY LEFT OUT of `ex-flow`'s surface: `deadlineStrategy`, `weightStrategy`,
+ * `fairnessPolicy`/`maxDeferralRounds` aging, `schedulerMode: "throughput"`, `concurrencyCap`,
+ * `resourceCaps`, the clone modes and the config builder. None of the 19 measured checkpoints
+ * supplies a deadline, a weight or a resource class, so every one of them would be untested
+ * surface. `sequence` is `ex-flow`'s `fullSequence` under a shorter name.
+ *
+ * WHAT THIS DOES NOT CLAIM. `depends_on` encodes logical order, not file contention. Measured on
+ * `.shiftwork/checkpoint-job44.json`, whose first batch is twelve units wide, seven of those
+ * twelve name `runtime-ts/src/docread.ts`. The graph says they may run in parallel; the filesystem
+ * does not. This function reports what the graph permits and the orchestrator stays responsible
+ * for what it actually dispatches.
+ */
+const refuse = (reason) => ({ result: 'error', reason });
+/**
+ * Name the cycle that stopped Kahn, deterministically.
+ *
+ * Two runtimes left to their own devices will name two different — equally correct — cycles in the
+ * same graph, and the conformance suite goes red for a reason that is not a defect. The rule, and
+ * the three rulings that disambiguate it:
+ *
+ * - Scan the nodes Kahn could not emit **in input order** and start at the first.
+ * - Walk `depends_on` **in declared order**, following only dependencies that are themselves
+ *   UN-EMITTED. A dependency already emitted in an earlier batch can never close a cycle, so
+ *   following it would dead-end on a graph that does have one. (Every un-emitted node has at least
+ *   one un-emitted dependency — otherwise it was ready — so the walk can never run out of edges.)
+ * - The first repeated id closes the cycle, and the reported path is the CYCLE, not the whole walk:
+ *   the scan may have started merely downstream of the loop, and a sentence that named a node
+ *   outside the loop would be describing something other than the cycle it claims to name.
+ */
+function cyclePath(nodes, emitted) {
+    const byId = new Map(nodes.map((node) => [node.id, node]));
+    const path = [];
+    /** id -> where it sits in `path`, which is what turns "seen before" into "trim the tail here". */
+    const at = new Map();
+    let current = nodes.find((node) => !emitted.has(node.id));
+    while (current !== undefined) {
+        const repeat = at.get(current.id);
+        if (repeat !== undefined)
+            return [...path.slice(repeat), current.id];
+        at.set(current.id, path.length);
+        path.push(current.id);
+        const next = current.depends_on.find((dep) => !emitted.has(dep));
+        current = next === undefined ? undefined : byId.get(next);
+    }
+    // Unreachable on a graph that reached here: the walk only ends by repeating an id.
+    return path;
+}
+/**
+ * Level-synchronous Kahn: batch *k* holds every node whose dependencies all appear in batches < *k*.
+ *
+ * **Empty input is not an error.** `plan([])` is `{batches: [], sequence: [], width: 0}` — a plan
+ * with nothing left to do is the answer, the same reasoning `clock_in` applies when an all-terminal
+ * checkpoint reports success rather than escalating on a dangling cursor.
+ *
+ * **The three refusals are checked in a fixed order** — duplicate id, then unknown dependency, then
+ * cycle — because a graph can carry two faults at once and both runtimes have to name the same one.
+ */
+export function plan(nodes) {
+    // 1 — duplicate id. First in input order wins.
+    const declared = new Set();
+    for (const node of nodes) {
+        if (declared.has(node.id))
+            return refuse(`duplicate node id ${node.id}`);
+        declared.add(node.id);
+    }
+    // 2 — a dependency nothing declares. First node in input order, first dep in declared order.
+    for (const node of nodes) {
+        for (const dep of node.depends_on) {
+            if (!declared.has(dep)) {
+                return refuse(`node ${node.id} depends on ${dep}, which no node declares`);
+            }
+        }
+    }
+    // 3 — the batches.
+    const emitted = new Set();
+    const batches = [];
+    const sequence = [];
+    let width = 0;
+    while (emitted.size < nodes.length) {
+        /**
+         * Carry the input index explicitly rather than leaning on `Array.prototype.sort` being stable.
+         * It is, in every Node this package supports — but the tie-break is the thing the conformance
+         * gate compares against Python, and a reader has to be able to SEE that it is insertion order
+         * and not a property of the sort.
+         */
+        const ready = [];
+        for (const [index, node] of nodes.entries()) {
+            if (emitted.has(node.id))
+                continue;
+            if (node.depends_on.every((dep) => emitted.has(dep))) {
+                ready.push({ id: node.id, priority: node.priority ?? 0, index });
+            }
+        }
+        // Nothing is ready and something is left: the remainder contains a cycle.
+        if (ready.length === 0) {
+            return refuse(`the graph has a cycle: ${cyclePath(nodes, emitted).join(' -> ')}`);
+        }
+        // Priority descending, then insertion order.
+        ready.sort((a, b) => b.priority - a.priority || a.index - b.index);
+        const batch = ready.map((entry) => entry.id);
+        batches.push(batch);
+        for (const id of batch) {
+            emitted.add(id);
+            sequence.push(id);
+        }
+        if (batch.length > width)
+            width = batch.length;
+    }
+    return { batches, sequence, width };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bantamkit-mcp",
-  "version": "0.34.3",
+  "version": "0.35.1",
   "description": "Memory MCP server for Claude Code, Cursor, VS Code Copilot and Claude Desktop: per-person memory, JSON Schema validation, shift-work tools. Pure Node; install once with npx, run offline.",
   "keywords": [
     "mcp",
@@ -44,7 +44,8 @@
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "sync-assets": "node scripts/sync-assets.mjs",
-    "prepack": "node scripts/sync-assets.mjs",
+    "prepack": "node scripts/build-for-pack.mjs && npm run sync-assets",
+    "prepublishOnly": "node scripts/gate-before-publish.mjs",
     "pretest": "npm run build",
     "test": "node scripts/run-tests.mjs"
   },