bantamkit-mcp 0.35.3 → 0.35.5

package/dist/mcp/pyargs.js

@@ -27,7 +27,7 @@
  *     becomes head-25-bytes + `...` + tail-24-bytes, each end floored to a character
  *     boundary. Thirty Thai characters are 34 repr CHARACTERS and are still truncated.
  */
-import { reprValue } from '../pyjson.js';
+import { parseJson, reprValue } from '../pyjson.js';
 const req = (name, kind) => ({ name, kind, optional: false });
 const opt = (name, kind, bound = {}) => ({
     name,
@@ -78,7 +78,15 @@ export const ARG_MODELS = {
     },
     memory_recall: { model: 'memory_recallArguments', fields: [req('query', 'str'), opt('k', 'int')] },
     validate_json: { model: 'validate_jsonArguments', fields: [req('output', 'str'), req('schema', 'dict')] },
-    shiftwork_clock_in: { model: 'shiftwork_clock_inArguments', fields: [req('checkpoint', 'str')] },
+    // `clock_in(checkpoint: str, unit_id: str | None = None)` since job60: the optional field
+    // is the same `opt(...)` `shiftwork_clock_out`'s `accounting` already is, and `str` is the
+    // strict string `unit_id` is on `shiftwork_clock_out` — one spelling for one argument name
+    // across the two tools. An omitted or explicitly null `unit_id` is the default, which is
+    // the cursor unit and is byte for byte what the tool did before it had the field.
+    shiftwork_clock_in: {
+        model: 'shiftwork_clock_inArguments',
+        fields: [req('checkpoint', 'str'), opt('unit_id', 'str')],
+    },
     shiftwork_clock_out: {
         model: 'shiftwork_clock_outArguments',
         fields: [
@@ -434,6 +442,100 @@ function checkInt(loc, value) {
     }
     return { loc, type: 'int_type', msg: 'Input should be a valid integer', input: value };
 }
+/**
+ * CPython's default `sys.int_max_str_digits`, which `json.loads` hits before it returns.
+ *
+ * `int(<4301 digits>)` is a `ValueError` since CPython 3.11, and the reference's
+ * `_ArgMetadata.pre_parse_json` catches exactly that and leaves the key as the string it was
+ * — measured in `runtime-py/src/bantamkit/mcpserver.py`'s own docstring, review round 3, on
+ * `memory_save(links="[" + "1"*4301 + "]")`. `parseJson` here has no such cap (Python's ints
+ * do not overflow and neither does a `bigint`), so the cap is applied to the RESULT instead:
+ * a document CPython would have refused mid-decode is one holding an integer literal of more
+ * than 4300 digits, and that literal is exactly an `int` node this wide. The observable
+ * effect is the same one — the original string survives into validation — which is why this
+ * is a check on the tree and not a second decoder. Same number as `docread.ts`'s.
+ */
+const INT_MAX_STR_DIGITS = 4300;
+/** Does any integer in this document spell wider than CPython's decoder will convert? */
+function exceedsIntDigitCap(value) {
+    switch (value.t) {
+        case 'int': {
+            const magnitude = value.v < 0n ? -value.v : value.v;
+            return magnitude.toString().length > INT_MAX_STR_DIGITS;
+        }
+        case 'list':
+            return value.v.some(exceedsIntDigitCap);
+        case 'dict': {
+            for (const nested of value.v.values())
+                if (exceedsIntDigitCap(nested))
+                    return true;
+            return false;
+        }
+        default:
+            return false;
+    }
+}
+/**
+ * `FuncMetadata.pre_parse_json` — the SDK step that runs BEFORE `model_validate`.
+ *
+ * WHY THIS EXISTS AT ALL. The reference does not validate the arguments a client sent; it
+ * validates the arguments the SDK handed pydantic, and the SDK unwraps a JSON-encoded string
+ * first, because "Claude Desktop is prone to this — in fact it seems incapable of NOT doing
+ * it" (the SDK's own words). Until this function the port skipped that step entirely, so the
+ * two runtimes read the same `tools/call` differently on every non-`str` argument. Measured
+ * over the real stdio servers on both sides, 2026-09-21, sixteen shapes disagreed, including
+ * the register's own item: `validate_json(output='{"a": 1}', schema='{"type": "object"}')`
+ * answered `{"valid": true}` on Python and `dict_type` on Node. The reference is the
+ * reference, so the port gains the step rather than the reference losing it.
+ *
+ * THE RULE IS THE SDK'S, NOT A PARAPHRASE. A key is unwrapped when all of this holds:
+ *
+ *   * the key names a field of the model — an unknown key is not in `key_to_field_info` and
+ *     is left alone (it is ignored by validation anyway);
+ *   * the value is a string;
+ *   * the field's annotation `is not str`. That is an IDENTITY test on the annotation
+ *     object, so `str | None` is NOT `str` and DOES get unwrapped: `skill_audit(check=
+ *     'null')` reaches the handler as `None` on the reference. Here that is exactly
+ *     "required `str`" — every other kind, and every OPTIONAL `str`, qualifies;
+ *   * `json.loads` succeeds. It can fail two ways and both keep the string: a decode error,
+ *     and the digit cap above;
+ *   * the result is not a `str`, `int` or `float`. `isinstance(True, int)` is true in
+ *     Python, so a `bool` is skipped by that same line — `dry_run='true'` stays the string
+ *     `'true'` and pydantic's lax bool parse is what reads it. What is left, and what this
+ *     therefore replaces, is exactly a list, a dict, or `null`.
+ *
+ * It is NOT applied per tool. The reference's one opt-out, `_NO_JSON_UNWRAP`, is dormant —
+ * `bantamkit_read` left the roster in job50 — so every served tool unwraps today, and a
+ * roster line coming back is the moment to give this function the same set.
+ */
+export function preParseJson(model, args) {
+    if (args.t !== 'dict')
+        return args;
+    const byName = new Map(model.fields.map((field) => [field.name, field]));
+    let unwrapped = null;
+    for (const [key, value] of args.v) {
+        const spec = byName.get(key);
+        if (spec === undefined || value.t !== 'str')
+            continue;
+        if (spec.kind === 'str' && !spec.optional)
+            continue;
+        let parsed;
+        try {
+            parsed = parseJson(value.v);
+        }
+        catch {
+            continue;
+        }
+        if (parsed.t === 'str' || parsed.t === 'int' || parsed.t === 'float' || parsed.t === 'bool')
+            continue;
+        if (exceedsIntDigitCap(parsed))
+            continue;
+        if (unwrapped === null)
+            unwrapped = new Map(args.v);
+        unwrapped.set(key, parsed);
+    }
+    return unwrapped === null ? args : { t: 'dict', v: unwrapped };
+}
 /**
  * The pydantic `ValidationError` text, WITHOUT the `Error executing tool <name>: ` prefix.
  *
@@ -455,9 +557,15 @@ export class PyValidationFailure extends Error {
  * measured server accepts `{"query": "a", "extra": 1}` without complaint. The absent-key case
  * and the explicit-`null` case are different: `{}` is `missing`, `{"handoff_patch": null}` is
  * `dict_type`, and only an OPTIONAL field treats `null` as its default.
+ *
+ * `preParseJson` runs FIRST, and what it returns is what every error below reports. That
+ * ordering is the SDK's: `model_validate` never sees the arguments a client sent, only the
+ * unwrapped ones, so a `missing` error on `memory_recall(k='[1]')` carries `{'k': [1]}` as
+ * its `input_value` and not the string the wire held.
  */
 export function validateArguments(model, args) {
-    const supplied = args.t === 'dict' ? args.v : new Map();
+    const unwrapped = preParseJson(model, args);
+    const supplied = unwrapped.t === 'dict' ? unwrapped.v : new Map();
     const errors = [];
     const bound = new Map();
     for (const spec of model.fields) {
@@ -466,7 +574,7 @@ export function validateArguments(model, args) {
                 bound.set(spec.name, { t: 'null' });
                 continue;
             }
-            errors.push({ loc: spec.name, type: 'missing', msg: 'Field required', input: args });
+            errors.push({ loc: spec.name, type: 'missing', msg: 'Field required', input: unwrapped });
             continue;
         }
         const checked = checkField(spec, supplied.get(spec.name));

package/dist/mcp/server.js

@@ -524,11 +524,17 @@ function runTool(name, memory, args, version, log, documents) {
             log.record('validate_json', error === null ? 'valid' : 'invalid');
             return { value: notedDict({ t: 'dict', v: out }), wrapped: false };
         }
-        case 'shiftwork_clock_in':
+        case 'shiftwork_clock_in': {
+            // J60: optional `unit_id`. Read the way `bantamkit_read` reads its optional `part` —
+            // a value that is not a string is the DEFAULT, which is the cursor unit, so a host
+            // sending `null` gets exactly the call it got before the field existed.
+            const unitArg = args.get('unit_id');
+            const unit = unitArg !== undefined && unitArg.t === 'str' ? unitArg.v : null;
             return {
-                value: notedDict(recordResult(log, name, () => shiftwork.clockIn(asText(args.get('checkpoint'))))),
+                value: notedDict(recordResult(log, name, () => shiftwork.clockIn(asText(args.get('checkpoint')), unit))),
                 wrapped: false,
             };
+        }
         case 'shiftwork_clock_out':
             return {
                 value: notedDict(recordResult(log, name, () => shiftwork.clockOut(asText(args.get('checkpoint')), asText(args.get('unit_id')), asText(args.get('status')), args.get('handoff_patch'), args.get('history_entry'), args.get('accounting') ?? { t: 'null' }))),

package/dist/selfupdate.d.ts

@@ -283,7 +283,10 @@ export declare function keptInstall(prefix?: string): KeptInstall | null;
  * THE PORT OF `selfupdate.record_update`. Its docstring carries the argument and is not
  * restated: no second network call and no new failure mode (`update` already holds `latest`),
  * no directory is ever created, the other runtime's key is left exactly as found, and the
- * write goes through a temp file and a rename so no reader sees half a record.
+ * write goes through a temp file and a rename so no reader sees half a record. That includes
+ * its AMENDED 2026-09-21 clause — this writer stamps its OWN entry's `checked_at` and never
+ * the record's, because the record's stamp means "a writer refreshed the whole record" and
+ * `--update` holds one registry's answer by construction.
  *
  * WHY THE WRITER IS HERE AND NOT IN `updatecheck.ts`. That module is the READER, and
  * `test/updatecheck.test.mjs` gates its source against `writeFileSync`, `renameSync`,

package/dist/selfupdate.js

@@ -421,7 +421,10 @@ function stamp() {
  * THE PORT OF `selfupdate.record_update`. Its docstring carries the argument and is not
  * restated: no second network call and no new failure mode (`update` already holds `latest`),
  * no directory is ever created, the other runtime's key is left exactly as found, and the
- * write goes through a temp file and a rename so no reader sees half a record.
+ * write goes through a temp file and a rename so no reader sees half a record. That includes
+ * its AMENDED 2026-09-21 clause — this writer stamps its OWN entry's `checked_at` and never
+ * the record's, because the record's stamp means "a writer refreshed the whole record" and
+ * `--update` holds one registry's answer by construction.
  *
  * WHY THE WRITER IS HERE AND NOT IN `updatecheck.ts`. That module is the READER, and
  * `test/updatecheck.test.mjs` gates its source against `writeFileSync`, `renameSync`,
@@ -452,8 +455,8 @@ export function recordUpdate(latest, now) {
     const { source, record } = loadRecord(path);
     // An UNREADABLE record is replaced rather than merged: there is nothing in it to preserve.
     const payload = source === SOURCE_RECORD && record !== null ? { ...record } : {};
-    payload['checked_at'] = now ?? stamp();
-    payload[RECORD_KEY] = { package: PACKAGE, latest };
+    const at = now ?? stamp();
+    payload[RECORD_KEY] = { package: PACKAGE, latest, checked_at: at };
     const temporary = join(directory, `.update-check-${process.pid}-${Date.now()}.json`);
     try {
         writeFileSync(temporary, `${JSON.stringify(payload, null, 2)}\n`, 'utf8');

package/dist/shiftwork.d.ts

@@ -32,7 +32,25 @@ export interface ClockOptions {
     now?: number;
 }
 /**
- * Validate the checkpoint and return the cursor unit's brief, or a refusal.
+ * Validate the checkpoint and return a unit's brief, or a refusal.
+ *
+ * `unitId` OMITTED IS THE CURSOR UNIT, BYTE FOR BYTE WHAT IT WAS (J60/D1). Given, it is
+ * briefed instead — IF the batch view says it is ready. That is the only new judgement, it
+ * is taken LAST, and the three above it are untouched, so no existing refusal moves and no
+ * caller that never passes a unit can see a difference. A unit that is not ready, including
+ * an id naming no unit at all, is ONE refusal carrying the list the caller's next move is to
+ * pick from; a batch view that refuses (cycle, unknown dependency) passes through verbatim,
+ * in both directions, exactly as `planBatches` already passes `readValid`'s.
+ *
+ * `ready` cannot be empty here: the all-terminal test above has already answered `success`
+ * for a plan with no non-terminal unit, and a non-terminal unit that cannot batch is a
+ * refusal rather than an empty list. No sentence is written for a case that cannot be
+ * reached.
+ *
+ * STILL NEVER WRITES `plan.cursor`. A wave of N briefs leaves the pointer where it was; it
+ * is `clockOut` that moves it. What each brief DOES write is its own ledger line, naming the
+ * unit actually briefed, so `clockOut`'s `briefed` flag keeps working per unit with no
+ * change to how it is computed — which is what makes D2 possible.
  *
  * `invariants` IS SYNTHESIZED HERE. It is not a key of the checkpoint — it is
  * `document["job"]["constraints"]` under a different name — which is precisely why a brief
@@ -44,12 +62,18 @@ export interface ClockOptions {
  * all-terminal test before the cursor lookup — so an empty plan reports success rather than
  * escalating on its dangling cursor, because `all([])` is true.
  */
-export declare function clockIn(checkpoint: string, options?: ClockOptions): PyValue;
+export declare function clockIn(checkpoint: string, unitId?: string | null, options?: ClockOptions): PyValue;
 /**
  * Apply the cursor unit's result, validate the WHOLE mutated document, write atomically.
  *
- * `unitId` must name the cursor unit — the contract is execute-the-cursor (driver parity),
- * never pick-a-unit. When `job.roles` names the unit's role, `accounting.model` must be one
+ * `unitId` must name the cursor unit OR a unit briefed since its own last clock-out
+ * (J60/D2) — the `briefed` value this module already computes off `<checkpoint>.log.jsonl`
+ * for the accounting line and already refuses to take from the caller, so a wave of briefs
+ * can be clocked out in the order the agents actually return. A unit that was never
+ * dispatched still cannot be clocked out, and it is refused with the sentence it has always
+ * had, unchanged in both runtimes, so every ruled case pinning it stays green;
+ * `docs/shiftwork.md` carries the fuller meaning. The gate still runs BEFORE the AS-2
+ * role/model check and before the first mutation. When `job.roles` names the unit's role, `accounting.model` must be one
  * of that role's models, spelled exactly; a wrong or missing model is refused here, before
  * any mutation and before the accounting line. Extended 2026-09-11 (job47): so is a
  * `job.roles` value for that role that is not a list of model identifiers — an unreadable
@@ -58,7 +82,9 @@ export declare function clockIn(checkpoint: string, options?: ClockOptions): PyV
  * that does not fit the shape the `shiftwork_clock_out` asset declares — checked after the
  * roles gate, before any mutation, same structured return, nothing written; a null
  * accounting is not validated and stays legal. Mutations: set the unit's status, advance
- * `plan.cursor` to the first non-terminal unit in PLAN order (`depends_on` is ignored),
+ * `plan.cursor` to the first unit the GRAPH says is ready (J60/D3 — `ready[0]` of the
+ * mutated document, falling back to the first non-terminal unit in `plan.units` order only
+ * when the graph cannot batch at all, and to `unitId` when nothing is left),
  * shallow-merge `handoffPatch` into `handoff`, push `historyEntry` onto the 5-entry ring.
  *
  * VALIDATE BEFORE WRITING, AND WRITE NOTHING ON REFUSAL. The mutated document goes through
@@ -85,7 +111,9 @@ export declare function status(checkpoint: string): PyValue;
  *
  * 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.
+ * decisions below plus the shape it answers in — and since J60 even the loop that applies
+ * them is `batchView`'s, because `clockIn` and `clockOut` judge by the same three and a
+ * second copy is how they would drift apart again.
  *
  * **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
@@ -101,10 +129,12 @@ export declare function status(checkpoint: string): PyValue;
  * 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.
+ * **The cursor is ECHOED, never written.** `clockOut` remains the only thing that moves it;
+ * 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. Since J60 the pointer is moved BY this same view
+ * (`ready[0]`), so the two fields can no longer contradict each other on a plannable graph
+ * — which was the whole defect — but the echo stays an echo.
  *
  * 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

package/dist/shiftwork.js

@@ -58,6 +58,19 @@
  * 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.
+ *
+ * AMENDED 2026-09-20 (job60). The paragraph above stands as the history and is now FALSE as a
+ * description of this code: cursor advance no longer ignores `depends_on`. A read-only surface
+ * answering from the graph beside a dispatch surface answering from a single pointer is two
+ * answers to one question, and they were MEASURED disagreeing two ways — a two-wide `ready`
+ * the driver gives no way to spend, and a cursor landing on a unit whose `depends_on` has not
+ * run. `docs/superpowers/specs/2026-09-20-clock-in-unit-id-design.md` is the other half of the
+ * 2026-09-18 design, not a repair of it. Three changes, all below: `clockIn` takes an optional
+ * `unitId` and briefs it IF the graph says it is ready; `clockOut` accepts the cursor unit OR
+ * one it briefed, keeping its existing refusal sentence; and cursor advance is `ready[0]`,
+ * falling back to `plan.units` order only for a graph that cannot batch at all. There is ONE
+ * loop over `depends_on` in this module (`batchView`) and three callers, because a second one
+ * is precisely how the two surfaces came to disagree.
  */
 import { AssetNotFound, loadSchema, loadToolAsset } from './assets.js';
 import { schemaError } from './contract.js';
@@ -282,9 +295,81 @@ function briefed(log, unitId) {
     }
     return flag;
 }
+// -------------------------------------------------------------------------- the graph
+/**
+ * The batch view of an IN-MEMORY document — the module's ONE loop over `depends_on`.
+ *
+ * J60. Three callers need the same answer and only one of them has a file to read:
+ * `planBatches` answers it for a checkpoint on disk, `clockIn` needs it to judge a
+ * requested `unitId`, and `clockOut` needs it on the document it has just MUTATED and has
+ * not written yet. A second loop for the in-memory callers is exactly how the advisory
+ * surface and the dispatch surface came to disagree, which is the defect this job closes,
+ * so the loop lives here and the three callers share its answer.
+ *
+ * The three decisions it holds are the ones `planBatches` documents — a `done` or
+ * `dropped` unit is SATISFIED (it leaves the graph and every edge into it is resolved),
+ * every unit has priority 0, and the cursor is not consulted at all. Refusals are the
+ * core's own: a `PlanResult` that is a `PlanError` carries the duplicate-id, unknown-
+ * dependency or cycle sentence, and every caller passes it on verbatim rather than
+ * rewording it.
+ */
+function batchView(doc) {
+    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 });
+    }
+    return plan(nodes);
+}
+/**
+ * `batches[0]`, or `[]` — for a plan that is all terminal AND for a graph that refuses.
+ *
+ * The empty answer is what makes the refusal case fall through to the caller's own
+ * fallback instead of acquiring a new way to refuse: `clockOut` RECORDS, and a recording
+ * surface does not stop working because the graph it was handed cannot be batched.
+ * `clockIn` never reaches this with a refusal — it returns the core's sentence first.
+ */
+function readyIds(view) {
+    if ('result' in view)
+        return [];
+    return view.batches.length > 0 ? view.batches[0] : [];
+}
 // ----------------------------------------------------------------------------- clock_in
 /**
- * Validate the checkpoint and return the cursor unit's brief, or a refusal.
+ * Validate the checkpoint and return a unit's brief, or a refusal.
+ *
+ * `unitId` OMITTED IS THE CURSOR UNIT, BYTE FOR BYTE WHAT IT WAS (J60/D1). Given, it is
+ * briefed instead — IF the batch view says it is ready. That is the only new judgement, it
+ * is taken LAST, and the three above it are untouched, so no existing refusal moves and no
+ * caller that never passes a unit can see a difference. A unit that is not ready, including
+ * an id naming no unit at all, is ONE refusal carrying the list the caller's next move is to
+ * pick from; a batch view that refuses (cycle, unknown dependency) passes through verbatim,
+ * in both directions, exactly as `planBatches` already passes `readValid`'s.
+ *
+ * `ready` cannot be empty here: the all-terminal test above has already answered `success`
+ * for a plan with no non-terminal unit, and a non-terminal unit that cannot batch is a
+ * refusal rather than an empty list. No sentence is written for a case that cannot be
+ * reached.
+ *
+ * STILL NEVER WRITES `plan.cursor`. A wave of N briefs leaves the pointer where it was; it
+ * is `clockOut` that moves it. What each brief DOES write is its own ledger line, naming the
+ * unit actually briefed, so `clockOut`'s `briefed` flag keeps working per unit with no
+ * change to how it is computed — which is what makes D2 possible.
  *
  * `invariants` IS SYNTHESIZED HERE. It is not a key of the checkpoint — it is
  * `document["job"]["constraints"]` under a different name — which is precisely why a brief
@@ -296,7 +381,7 @@ function briefed(log, unitId) {
  * all-terminal test before the cursor lookup — so an empty plan reports success rather than
  * escalating on its dangling cursor, because `all([])` is true.
  */
-export function clockIn(checkpoint, options = {}) {
+export function clockIn(checkpoint, unitId = null, options = {}) {
     const { document, refusal } = readValid(pyJoin(checkpoint));
     if (refusal !== null)
         return refusal;
@@ -318,7 +403,22 @@ export function clockIn(checkpoint, options = {}) {
         ]);
     }
     const cursor = text(field(subDict(doc, 'plan'), 'cursor'));
-    const unit = findUnit(doc, cursor);
+    // D1: selection, and it is the LAST judgement. `selected` differs from `cursor` only on
+    // the new branch, so the dangling-cursor escalation below still says `cursor` truthfully:
+    // a `unitId` that reached `selected` came out of `ready`, whose ids are `plan.units`' own,
+    // and `findUnit` cannot fail for it.
+    let selected = cursor;
+    if (unitId !== null && unitId !== undefined) {
+        const view = batchView(doc);
+        if ('result' in view)
+            return errorResult(view.reason);
+        const ready = readyIds(view);
+        // `", "` in BATCH order, not sorted: the order the caller would dispatch them in.
+        if (!ready.includes(unitId))
+            return errorResult(`unit ${unitId} is not ready; ready is ${ready.join(', ')}`);
+        selected = unitId;
+    }
+    const unit = findUnit(doc, selected);
     if (unit === null) {
         return dict([
             ['result', str('escalate')],
@@ -328,7 +428,8 @@ export function clockIn(checkpoint, options = {}) {
     // F6: the brief is issued, so say so in the ledger — best effort, and only on this branch:
     // a refusal above issued nothing and therefore records nothing. `pyJoin` is the same
     // normalisation `clockOut` applies before it builds ITS log path, so the two land in one file.
-    recordBrief(logPath(pyJoin(checkpoint)), cursor, field(unit, 'role'), options.now ?? Date.now() / 1000);
+    // The line names the unit ACTUALLY briefed, which is what D2 reads back.
+    recordBrief(logPath(pyJoin(checkpoint)), selected, field(unit, 'role'), options.now ?? Date.now() / 1000);
     return dict([
         ['result', str('brief')],
         ['unit', unit],
@@ -564,8 +665,14 @@ function accountingRefusal(unitId, unit, accounting) {
 /**
  * Apply the cursor unit's result, validate the WHOLE mutated document, write atomically.
  *
- * `unitId` must name the cursor unit — the contract is execute-the-cursor (driver parity),
- * never pick-a-unit. When `job.roles` names the unit's role, `accounting.model` must be one
+ * `unitId` must name the cursor unit OR a unit briefed since its own last clock-out
+ * (J60/D2) — the `briefed` value this module already computes off `<checkpoint>.log.jsonl`
+ * for the accounting line and already refuses to take from the caller, so a wave of briefs
+ * can be clocked out in the order the agents actually return. A unit that was never
+ * dispatched still cannot be clocked out, and it is refused with the sentence it has always
+ * had, unchanged in both runtimes, so every ruled case pinning it stays green;
+ * `docs/shiftwork.md` carries the fuller meaning. The gate still runs BEFORE the AS-2
+ * role/model check and before the first mutation. When `job.roles` names the unit's role, `accounting.model` must be one
  * of that role's models, spelled exactly; a wrong or missing model is refused here, before
  * any mutation and before the accounting line. Extended 2026-09-11 (job47): so is a
  * `job.roles` value for that role that is not a list of model identifiers — an unreadable
@@ -574,7 +681,9 @@ function accountingRefusal(unitId, unit, accounting) {
  * that does not fit the shape the `shiftwork_clock_out` asset declares — checked after the
  * roles gate, before any mutation, same structured return, nothing written; a null
  * accounting is not validated and stays legal. Mutations: set the unit's status, advance
- * `plan.cursor` to the first non-terminal unit in PLAN order (`depends_on` is ignored),
+ * `plan.cursor` to the first unit the GRAPH says is ready (J60/D3 — `ready[0]` of the
+ * mutated document, falling back to the first non-terminal unit in `plan.units` order only
+ * when the graph cannot batch at all, and to `unitId` when nothing is left),
  * shallow-merge `handoffPatch` into `handoff`, push `historyEntry` onto the 5-entry ring.
  *
  * VALIDATE BEFORE WRITING, AND WRITE NOTHING ON REFUSAL. The mutated document goes through
@@ -598,8 +707,15 @@ export function clockOut(checkpoint, unitId, status, handoffPatch, historyEntry,
         return errorResult(`unit ${unitId} is not in the plan`);
     const plan = subDict(doc, 'plan');
     const cursor = text(field(plan, 'cursor'));
-    if (unitId !== cursor)
+    const log = logPath(path);
+    // D2: the cursor unit, or one this checkpoint's ledger says was briefed and not yet
+    // clocked out. `briefed` is the SAME helper the accounting line's own field is measured
+    // with, called here rather than reimplemented — two readers of one ledger is the shape
+    // this job exists to remove. The sentence is unchanged, deliberately: it is pinned by
+    // ruled conformance cases, and widening the wording would move every one of them.
+    if (unitId !== cursor && !briefed(log, unitId)) {
         return errorResult(`unit ${unitId} is not the cursor unit ${cursor}`);
+    }
     const wrongModel = modelRefusal(doc, unitId, unit, accounting);
     if (wrongModel !== null)
         return errorResult(wrongModel);
@@ -607,8 +723,19 @@ export function clockOut(checkpoint, unitId, status, handoffPatch, historyEntry,
     if (badLine !== null)
         return errorResult(badLine);
     unit.v.set('status', str(status));
+    // D3: the cursor follows the GRAPH, on the MUTATED document — the unit just finished is
+    // already out of it. Three steps, and the middle one is only reachable for a graph that
+    // cannot batch at all (a cycle, an unknown dependency), because `ready` is computed over
+    // exactly the units `remaining` holds: a recording surface does not acquire a new way to
+    // refuse, so such a checkpoint can still be driven to its end in plan order. For a linear
+    // chain `ready[0] === remaining[0]`, which is why every case written before this holds its
+    // value.
     const remaining = subList(plan, 'units').v.filter((u) => !TERMINAL_UNIT_STATUS.has(text(u.v.get('status'))));
-    plan.v.set('cursor', remaining.length > 0 ? field(remaining[0], 'id') : str(unitId));
+    const ready = readyIds(batchView(doc));
+    if (ready.length > 0)
+        plan.v.set('cursor', str(ready[0]));
+    else
+        plan.v.set('cursor', remaining.length > 0 ? field(remaining[0], 'id') : str(unitId));
     const handoff = subDict(doc, 'handoff');
     for (const [key, value] of asPatch(handoffPatch))
         handoff.v.set(key, value);
@@ -631,7 +758,6 @@ export function clockOut(checkpoint, unitId, status, handoffPatch, historyEntry,
     ]);
     for (const [key, value] of asPatch(accounting))
         record.set(key, value);
-    const log = logPath(path);
     // F6: `briefed` is MEASURED off the ledger, AFTER the orchestrator's keys are merged, so the
     // runtime's answer wins over a self-reported one — the order is load-bearing. It is written
     // on every line, `accounting: null` included: the base shape (ts/unit/role/status) is the
@@ -705,7 +831,9 @@ export function status(checkpoint) {
  *
  * 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.
+ * decisions below plus the shape it answers in — and since J60 even the loop that applies
+ * them is `batchView`'s, because `clockIn` and `clockOut` judge by the same three and a
+ * second copy is how they would drift apart again.
  *
  * **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
@@ -721,10 +849,12 @@ export function status(checkpoint) {
  * 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.
+ * **The cursor is ECHOED, never written.** `clockOut` remains the only thing that moves it;
+ * 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. Since J60 the pointer is moved BY this same view
+ * (`ready[0]`), so the two fields can no longer contradict each other on a plannable graph
+ * — which was the whole defect — but the echo stays an echo.
  *
  * 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
@@ -737,27 +867,7 @@ export function planBatches(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);
+    const answer = batchView(doc);
     if ('result' in answer)
         return errorResult(answer.reason);
     const batches = answer.batches.map((batch) => ({ t: 'list', v: batch.map(str) }));

package/dist/updatecheck.d.ts

@@ -107,9 +107,9 @@ export declare function readRecord(path?: string): Record<string, unknown> | nul
  * Split from the reading so the conformance harness and the tests can construct a state
  * directly and so the only thing that touches a disk is `loadRecord`.
  *
- * `checked_at` is validated in EVERY arm that reached a record and not only on the `current`
- * path: a record that cannot say when it was written is not a record, and one rule is one thing
- * for the two runtimes to reproduce instead of two.
+ * The SELECTED `checked_at` (see `checkedDate`) is validated in EVERY arm that reached a record
+ * and not only on the `current` path: a record that cannot say when it was written is not a
+ * record, and one rule is one thing for the two runtimes to reproduce instead of two.
  */
 export declare function decide(installed: string, source: Source, record: Record<string, unknown> | null, key?: string): UpdateStatus;
 /** Read the record and decide. The whole reader, in one call, for `bantamkit_status`. */