bantamkit-mcp 0.35.2 → 0.35.4

package/README.md

@@ -6,9 +6,13 @@ command, connect it to **Claude Code**, **Claude Desktop**, **Cursor** or **GitH
 Code**, and every later launch starts **offline**. No Python, `pip`, `uv`, `pipx` or venv.
 
 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.
+Python server — [`bantamkit` on PyPI](https://pypi.org/project/bantamkit/) — 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.
+
+**This page is the npm package's.** Every command on it runs `bantamkit-mcp` from npm. The
+Python package is named where the two differ, but its own install, update and CLI commands live
+on [its page](https://pypi.org/project/bantamkit/); run them here and you get nothing.
 
 ## Contents
 
@@ -31,6 +35,7 @@ intentional difference written down as a ruling.
 | [Memory stores are layered by default](#memory-stores-are-layered-by-default) | Why not to add `--store` by reflex |
 | [The asset pack](#the-asset-pack) | What ships in `assets/` and how it is found |
 | [Where the Python and Node servers differ](#where-the-python-and-node-servers-differ) | One store; concurrent writes, one hand-edit to avoid |
+| [Module API](#module-api) | The one entry point, all 139 exports it reaches, and the one break in `clockIn` |
 | [Development](#development) | Build, test, conformance |
 | [Measurements and history](#measurements-and-history) | Where the measured numbers behind this page live |
 
@@ -107,7 +112,6 @@ Each host below has the same steps: **1** command, **2** file, **3** entry, **4*
 | Route | `command` | `args` |
 |---|---|---|
 | npm, install once | `/absolute/path/to/node` | `["/Users/you/.bantamkit/mcp/node_modules/bantamkit-mcp/dist/cli.js"]` |
-| Python venv | `/absolute/path/to/env/bin/bantamkit-mcp` | `[]` |
 | npx every launch | `npx` | `["-y", "bantamkit-mcp"]` |
 
 A JSON file cannot expand `~`, so spell both paths out. To check a recorded command, run it in
@@ -226,9 +230,12 @@ It is the only network access here — not at startup, not on `bantamkit_status`
 | `npx -y bantamkit-mcp --install <host>` from 0.34.0: a kept install at `~/.bantamkit/mcp` | `npx -y bantamkit-mcp@latest --update` patches it in place, or `npm i --prefix ~/.bantamkit/mcp bantamkit-mcp@latest`. The recorded paths do not change. Before 0.34.0, `--update` from an npx cache refuses instead |
 | `npm i -g bantamkit-mcp` | `npm i -g bantamkit-mcp@latest` |
 | `npm i --prefix <dir> bantamkit-mcp` | `npm i --prefix <dir> bantamkit-mcp@latest` |
-| PyPI (`pip install "bantamkit[mcp]"`) | `pip install -U "bantamkit[mcp]"` · pipx: `pipx upgrade bantamkit` · uv: `uv tool upgrade bantamkit` |
 | a checkout, via `tools/bantamkit-mcp-node` | `git pull && npm ci --prefix runtime-ts && npm run build --prefix runtime-ts` — no registry, and `runtime-ts/dist/` is build output, so a pull alone changes nothing |
 
+No row above is the Python package. If what you have is **`bantamkit` from PyPI** instead, it
+updates by its own route, written on [its PyPI page](https://pypi.org/project/bantamkit/); the
+two sets of commands are not interchangeable.
+
 **Then restart the server in your host** — a running server keeps serving the code it loaded at
 startup. In Claude Code: `/mcp` → reconnect. In Claude Desktop: a full restart of the app.
 
@@ -405,6 +412,100 @@ are deliberate and each is ruled in the
   the whole store with `malformed fact file …`. Quote it: `description: '2026'`. Every fact the
   tools *write* is quoted correctly (`src/memory/factfile.ts:257`).
 
+## Module API
+
+The package is a server first, but it is importable too: `exports` maps exactly one entry
+point — `.` — to `dist/index.js` and `dist/index.d.ts`, so `import { clockIn } from
+'bantamkit-mcp'` is a supported call, and the names and arities behind that entry point are
+part of what is published.
+
+Everything in this section was measured against the **tarball**, not the source tree: `npm
+pack`, extracted into a throwaway package's `node_modules`, and imported by `node`. A name in
+`src/` that no entry point reaches is not API; the table below is what an importer gets.
+
+**One entry point, and nothing beside it.** There are no subpaths, so every deep import is
+refused by Node's resolver:
+
+| specifier | result |
+| --- | --- |
+| `bantamkit-mcp` | 139 value exports, 26 type-only exports |
+| `bantamkit-mcp/dist/cli.js` | `ERR_PACKAGE_PATH_NOT_EXPORTED` |
+| `bantamkit-mcp/dist/shiftwork.js` | `ERR_PACKAGE_PATH_NOT_EXPORTED` |
+| `bantamkit-mcp/package.json` | `ERR_PACKAGE_PATH_NOT_EXPORTED` |
+| `bantamkit-mcp/assets/tools/memory_save.json` | `ERR_PACKAGE_PATH_NOT_EXPORTED` |
+
+**So what you can import is the library half, not the server.** The MCP server and its
+transport, both CLIs, the host-install and self-update code, the hook adapter, the document
+reader, the repo map, the skill audit, the token ledger, the pricing table and the work planner
+all ship inside `dist/` and none of them is reachable through an import — they are reached by
+running `bantamkit-mcp` and `bantamkit-memory`. Importing the package starts no server and
+opens no transport. The vendored `assets/` is not importable either, but it is *readable*:
+`assetsRoot()` resolves to the `assets/` directory inside the installed package, which is how
+`loadTool('memory_save')` answers from a consumer that never unpacked anything itself.
+
+**What the one entry point exports**, grouped by the module each name comes from:
+
+| module | what it is | exported names |
+| --- | --- | --- |
+| `errors.js` | The base error every other one extends | `BantamError` |
+| `contract.js` | The JSON-answer contract: load it, pull JSON out of a model reply, compose the retry feedback | `ContractParseError`, `extractJson`, `loadContract`, `parseContractDocument`, `parseErrorMessage`, `REQUIRED_KEYS`, `schemaError`, `schemaRetryFeedback`, `validationErrorMessage` |
+| `pyjson.js` | CPython `json` semantics over a `PyValue` tree — float repr and decode errors included | `dumpJson`, `fromJs`, `parseJson`, `PY_NONE`, `pyFloatRepr`, `PyJSONDecodeError`, `PyValueError`, `rawDecode`, `reprValue`, `toJs`<br>*types:* `DumpOptions`, `PyValue` |
+| `pyjsonschema.js` | The JSON Schema validator, with CPython `jsonschema`'s error ordering and best-match | `absolutePath`, `bestMatch`, `iterErrors`, `pyEqual`, `PyJsonSchemaUnsupported`, `validate`<br>*types:* `PyValidationError` |
+| `assets.js` | The vendored asset pack: schemas, skills and tool definitions | `AssetNotFound`, `assetsRoot`, `loadSchema`, `loadSkill`, `loadTool`, `loadToolAsset`<br>*types:* `Tool` |
+| `memory/factfile.js` | One fact file: frontmatter, parse, format | `decodeFactBytes`, `FactParseError`, `formatFact`, `parseFactText`, `parseFrontmatter`, `pySplit`, `pyStrip`, `todayLocal`<br>*types:* `Fact`, `FactMeta`, `FactValue` |
+| `memory/pyyaml.js` | The YAML subset PyYAML's safe loader and dumper accept | `constructPlain`, `PyScalar`, `resolveImplicitTag`, `safeDumpMapping`, `YamlConstructError`, `YamlEmitError`<br>*types:* `PyOrder`, `YamlScalar`, `YamlValue` |
+| `memory/layers.js` | Which stores a recall reads, and where the project store is | `countFacts`, `discoverProjectStore`, `loadGrants`, `MEMORY_DIR_ENV`, `PROJECT_STORE`, `resolveProjectStore`<br>*types:* `StoreBinding` |
+| `memory/component.js` | `Memory`, the save/recall/compact/dream component the server calls | `layerLabel`, `Memory`, `normalizeName`, `profileStore`<br>*types:* `CompactOutcome`, `DreamOutcome`, `MemoryOptions`, `RecallOutcome`, `SaveOutcome` |
+| `memory/dream.js` | The consolidation pass: similarity, merge, supersede | `absolutise`, `blockKey`, `claimSlot`, `collapse`, `dream`, `formatFixed3`, `mergeBodies`, `mergeDescriptions`, `mergeLinks`, `PROFILE_LAYER`, `PROJECT_LAYER`, `pyIntDigits`, `sortedNames`, `splitBlocks`, `SUPERSEDED_HEADING`<br>*types:* `DateHit`, `DreamMerge`, `DreamResult`, `SimilarPair`, `Superseded` |
+| `eventlog.js` | The JSONL event log | `CAP_BYTES`, `DEFAULT_RELATIVE_PATH`, `defaultPath`, `encodeRecord`, `EVENT_LOG_ENV`, `EventLog`, `formatTimestamp`, `resolvePath`, `SCHEMA_VERSION`<br>*types:* `DetailValue` |
+| `memory/store.js` | `MemoryStore`: the on-disk store, its budgets and its dedupe | `BANTAMKIT_GITIGNORE_TEXT`, `DEFAULT_INDEX_BUDGET`, `DUPLICATE_JACCARD`, `ensureBantamkitGitignore`, `jaccard`, `MemoryBudgetExceeded`, `MemoryStore`, `MemoryValidationError`, `pyCompareLt`, `pyEqualValue`, `pyHashKey`, `pyText`, `RECALL_MIN_SCORE_RATIO`, `sortScored`, `tokens`, `VALID_TYPES`<br>*types:* `MemoryStoreOptions`, `SaveResult`, `StoreInternals` |
+| `memory/pyfs.js` | CPython `pathlib` and `os.path` semantics over `node:fs`, error numbering included | `asPyOSError`, `cmpCodepoint`, `matchesMd`, `normcase`, `pyAppendText`, `pyCwd`, `pyDecodeUtf8`, `pyExists`, `pyExpanduser`, `pyHome`, `pyIsAbsolute`, `pyIsDir`, `pyIsFile`, `pyJoin`, `pyLexists`, `pyMkdirParents`, `pyMtimeDate`, `pyName`, `PyOSError`, `pyParent`, `pyParents`, `pyReadText`, `pyReplace`, `pyRepr`, `pyResolve`, `PyRuntimeError`, `pyScandirNames`, `pyStatIsDir`, `pySuffix`, `PyUnicodeDecodeError`, `pyUnlink`, `pyWithSuffix`, `pyWriteText`, `sortedPathNames`, `sortedPathParts`, `STRERROR_NAMES` |
+| `shiftwork.js` | The shift-work checkpoint tools | `clockIn`, `clockOut`, `HISTORY_RING_SIZE`, `SCHEMA_NAME`, `status`, `TERMINAL_UNIT_STATUS`, `timestamp`<br>*types:* `ClockOptions` |
+| **14 modules** | | **139 values, 26 types** |
+
+Two things that table is easy to misread. The `py*` names are not a Python bridge — they are
+this port's re-implementations of CPython semantics (`pyfs.js` alone is 36 of the 139), and
+they are exported because the conformance harness and the operator tooling call them, not
+because an application should. And `Function.length` is not the signature: `clockIn.length` is
+`1` because two of its three parameters have defaults.
+
+**One export changed shape.** `clockIn` took a unit id as its **second positional parameter**,
+ahead of the options object:
+
+```ts
+clockIn(checkpoint: string, unitId: string | null = null, options: ClockOptions = {}): PyValue
+```
+
+A caller who wrote `clockIn(path, { now })` must now write `clockIn(path, null, { now })`, and
+`clockIn(path, 'U3')` briefs a named ready unit. TypeScript rejects the old shape at the type;
+plain JavaScript does not — the object lands in the id slot, the call asks for a unit named
+`[object Object]`, and `now` is dropped, which is a wrong answer rather than an error.
+`clockOut` is unchanged. The reasoning and the measurement behind it are in
+[docs/porting.md → The published export surface](https://github.com/Ink01101011/bantamkit/blob/main/docs/porting.md#the-published-export-surface-and-the-one-break-in-it);
+`docs/` is not in the npm tarball (`files: ["dist", "assets"]`), which is why the migration line
+is repeated here.
+
+**Rerun the whole table.** From a clone, in `runtime-ts/`:
+
+```sh
+npm pack --pack-destination /tmp/bk
+mkdir -p /tmp/bk/consumer/node_modules/bantamkit-mcp
+tar -xzf /tmp/bk/bantamkit-mcp-*.tgz -C /tmp/bk/consumer/node_modules/bantamkit-mcp --strip-components=1
+printf '{"name":"c","private":true,"type":"module"}' > /tmp/bk/consumer/package.json
+cd /tmp/bk/consumer && node -e "import('bantamkit-mcp').then((m) => console.log(Object.keys(m).length))"
+```
+
+It prints `139`, with no `npm install` and nothing fetched: `dist/index.js` pulls in none of the
+server code, so the one runtime dependency is never reached. The 26 type-only exports are in the
+same tarball — from `/tmp/bk/consumer`:
+
+```sh
+node -e "const t=require('fs').readFileSync('node_modules/bantamkit-mcp/dist/index.d.ts','utf8');console.log([...t.matchAll(/export type \{([^}]*)\}/g)].flatMap((m) => m[1].split(',')).map((x) => x.trim()).filter(Boolean).length)"
+```
+
+Both numbers move whenever `src/index.ts` does, which is why they are quoted with the command
+that prints them rather than kept in prose.
+
 ## Development
 
 ```sh

package/assets/tools/shiftwork_clock_in.json

@@ -1,6 +1,6 @@
 {
   "name": "shiftwork_clock_in",
-  "description": "Shift-work clock-in: schema-validate the checkpoint file and return the brief for the unit at plan.cursor — {unit, role, invariants, handoff, do_not, files} — to hand to the spawned agent verbatim. Structured refusals, never exceptions: result=escalate when handoff.open_questions is non-empty, result=success when every unit is done or dropped, result=error when the checkpoint fails validation. 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.",
+  "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. The unit briefed is the one at plan.cursor, or, when unit_id is given, that unit — which must appear in shiftwork_plan's `ready`, the batch the dependency graph says may run now. A unit_id that is not ready, including one naming no unit, is refused with {\"result\": \"error\", \"reason\": \"unit <id> is not ready; ready is <a, b>\"}, and the refusals of the batch view itself (cycle, unknown dependency, unreadable checkpoint) pass through verbatim. Clock-in still never moves plan.cursor; clock_out does. 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"
   ],
@@ -9,6 +9,18 @@
       "checkpoint": {
         "title": "Checkpoint",
         "type": "string"
+      },
+      "unit_id": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "default": null,
+        "title": "Unit Id"
       }
     },
     "required": [

package/assets/tools/shiftwork_clock_out.json

@@ -1,6 +1,6 @@
 {
   "name": "shiftwork_clock_out",
-  "description": "Shift-work clock-out: record a finished unit — set its status, advance plan.cursor, merge handoff_patch, push history_entry onto the 5-entry ring — validating the whole mutated document against the checkpoint schema BEFORE an atomic write (a failure writes nothing and returns result=error). Every success appends one accounting line (unit, role, status, ts, 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.",
+  "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). `unit_id` must be `plan.cursor` — which needs no brief, clocking out with briefed=false — OR a unit briefed since its own last clock-out; any other id keeps its refusal (`unit X is not the cursor unit Y`). plan.cursor then advances to the head of the ready batch recomputed on the mutated document, falling back to plan.units order over the remaining non-terminal units when the graph cannot batch (cycle or unknown dependency), and to unit_id when none remain. `handoff_patch` and `history_entry` are both required arguments: `handoff_patch` is shallow-merged into `handoff` and takes only its four keys (pass `{}` to leave it unchanged); `history_entry` needs `unit` and `outcome`; `status` is one of the five unit statuses — a value outside these shapes is refused by the schema check, nothing written. 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`). `accounting` is optional: null, the default, logs a line with no cost figures at all; a non-null line must fit the accounting shape below. `briefed` is written by the runtime, never taken from you: true when a brief was issued for this unit since its LAST clock-out (not ever), so a unit re-run after a blocked clock-out reads false. If job.roles names this unit's role, accounting.model must be one of that role's model identifiers, spelled exactly, or nothing is written — see the `model` property below.",
   "surfaces": [
     "mcp"
   ],
@@ -12,21 +12,76 @@
       },
       "unit_id": {
         "title": "Unit Id",
-        "type": "string"
+        "type": "string",
+        "description": "The unit being clocked out. Must be plan.cursor, or a unit briefed since its own last clock-out: clock_in briefs the cursor unit by default and, when its unit_id names one, any unit shiftwork_plan reports in `ready` — and that brief is what lets clock_out accept a unit the cursor is not on."
       },
       "status": {
         "title": "Status",
-        "type": "string"
+        "type": "string",
+        "enum": [
+          "todo",
+          "in_progress",
+          "done",
+          "blocked",
+          "dropped"
+        ],
+        "description": "The unit's new status; the same five values the checkpoint schema allows on plan.units[].status."
       },
       "handoff_patch": {
-        "additionalProperties": true,
         "title": "Handoff Patch",
-        "type": "object"
+        "type": "object",
+        "additionalProperties": false,
+        "description": "Shallow-merged into `handoff`: only these four keys exist there, and a key outside them is refused by the schema check. Required; `{}` leaves `handoff` unchanged.",
+        "properties": {
+          "next_action": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Imperative first move — zero re-derivation."
+          },
+          "open_questions": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "minLength": 1
+            },
+            "description": "The autonomy switch: empty = driver keeps cycling, non-empty = STOP and ask."
+          },
+          "do_not": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "minLength": 1
+            },
+            "description": "Negative space — near-mistakes past sessions made."
+          },
+          "notes": {
+            "type": "string",
+            "description": "Free-form prose for the next session, one string; the empty string clears it."
+          }
+        }
       },
       "history_entry": {
-        "additionalProperties": true,
         "title": "History Entry",
-        "type": "object"
+        "type": "object",
+        "required": [
+          "unit",
+          "outcome"
+        ],
+        "additionalProperties": true,
+        "description": "Pushed onto the 5-entry `history` ring; `unit` and `outcome` are required, `notes` optional, other keys pass through.",
+        "properties": {
+          "unit": {
+            "type": "string",
+            "minLength": 1
+          },
+          "outcome": {
+            "type": "string",
+            "minLength": 1
+          },
+          "notes": {
+            "type": "string"
+          }
+        }
       },
       "accounting": {
         "anyOf": [
@@ -37,7 +92,7 @@
               "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."
+                "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. In a non-null accounting line it is required — a line without it is refused before anything is written; only `accounting: null`, the default, is exempt, and that logs no cost at all. A rounded self-estimate is allowed only if `note` says it is one; a unit whose cost is unknown cannot be compared with any other."
               },
               "cache_read_tokens": {
                 "type": "integer",
@@ -47,7 +102,7 @@
               "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."
+                "description": "Wall-clock from spawning the subagent to its final message, in whole milliseconds. In a non-null line it is required, and it is 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",

package/assets/tools/shiftwork_plan.json

@@ -1,6 +1,6 @@
 {
   "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.",
+  "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 whose dependencies are all satisfied, and `width` is the largest batch length, the widest fan-out. A `ready` member beyond the cursor is clockable, but only in that order: shiftwork_clock_in briefs any unit in `ready` when `unit_id` names it, and shiftwork_clock_out then accepts that unit because it was briefed — an id that is neither the cursor nor briefed since its own last clock-out is still refused. 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"
   ],

package/dist/cli.d.ts

@@ -6,11 +6,15 @@ export interface Options {
     store: string | null;
     start: string | null;
     assetsRoot: boolean;
+    hook: boolean;
     mcpReport: boolean;
     statusline: boolean;
     update: boolean;
     install: Host | null;
     force: boolean;
+    installHooks: boolean;
+    removeHooks: boolean;
+    yes: boolean;
 }
 /** `_parse_args`, arm for arm, including the mutually exclusive group and `-h`. */
 export declare function parseArgs(argv: readonly string[]): Options;