bantamkit 0.37.2__tar.gz → 0.38.1__tar.gz

{bantamkit-0.37.2 → bantamkit-0.38.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bantamkit
-Version: 0.37.2
+Version: 0.38.1
 Summary: Persistent memory for coding agents: an MCP server for Claude Code, Claude Desktop, Cursor and VS Code Copilot, plus a Python library that lifts small-model agents. Install once, run offline.
 Project-URL: Homepage, https://github.com/Ink01101011/bantamkit
 Project-URL: Repository, https://github.com/Ink01101011/bantamkit
@@ -26,7 +26,7 @@ Requires-Dist: hatchling>=1.24; extra == 'dev'
 Requires-Dist: pytest>=8.0; extra == 'dev'
 Requires-Dist: ruff>=0.4; extra == 'dev'
 Provides-Extra: mcp
-Requires-Dist: mcp<2.1,>=2.0; extra == 'mcp'
+Requires-Dist: mcp<2.4,>=2.3; extra == 'mcp'
 Description-Content-Type: text/markdown
 
 # bantamkit — memory MCP server for Claude Code, Cursor, VS Code Copilot and Claude Desktop (Python)
@@ -144,9 +144,9 @@ CPU architecture and Python minor version** (some wheels, such as `pydantic_core
 one platform only), copy `wheels/` across, and install from it:
 
 ```bash
-python -m pip download "bantamkit[mcp]==0.37.2" -d wheels
+python -m pip download "bantamkit[mcp]==0.38.1" -d wheels
 python -m venv <env>
-<env>/bin/pip install --no-index --find-links wheels "bantamkit[mcp]==0.37.2"
+<env>/bin/pip install --no-index --find-links wheels "bantamkit[mcp]==0.38.1"
 <env>/bin/bantamkit-mcp --install cursor
 ```
 
@@ -328,7 +328,7 @@ you**; a new version with an old `build_id` means an old process.
 
 ## 🧰 What it serves
 
-It serves 15 tools, three prompts (`bantamkit_status`, `skill_audit` and `skill_propose`) and two resource templates
+It serves 16 tools, three prompts (`bantamkit_status`, `skill_audit` and `skill_propose`) and two resource templates
 (`bantamkit://skills/{name}`, `bantamkit://rubrics/{name}`):
 
 | Tool | What it does |

{bantamkit-0.37.2 → bantamkit-0.38.1}/README.md

@@ -113,9 +113,9 @@ CPU architecture and Python minor version** (some wheels, such as `pydantic_core
 one platform only), copy `wheels/` across, and install from it:
 
 ```bash
-python -m pip download "bantamkit[mcp]==0.37.2" -d wheels
+python -m pip download "bantamkit[mcp]==0.38.1" -d wheels
 python -m venv <env>
-<env>/bin/pip install --no-index --find-links wheels "bantamkit[mcp]==0.37.2"
+<env>/bin/pip install --no-index --find-links wheels "bantamkit[mcp]==0.38.1"
 <env>/bin/bantamkit-mcp --install cursor
 ```
 
@@ -297,7 +297,7 @@ you**; a new version with an old `build_id` means an old process.
 
 ## 🧰 What it serves
 
-It serves 15 tools, three prompts (`bantamkit_status`, `skill_audit` and `skill_propose`) and two resource templates
+It serves 16 tools, three prompts (`bantamkit_status`, `skill_audit` and `skill_propose`) and two resource templates
 (`bantamkit://skills/{name}`, `bantamkit://rubrics/{name}`):
 
 | Tool | What it does |

{bantamkit-0.37.2 → bantamkit-0.38.1}/_assets/schemas/shiftwork-checkpoint.json

@@ -38,6 +38,91 @@
             "items": {"type": "string", "minLength": 1},
             "description": "The model identifiers this role may report, spelled exactly as a session logs them. Non-empty: a role allowed no model is a typo, not a policy."
           }
+        },
+        "authorized": {
+          "type": "array",
+          "items": {"type": "string", "minLength": 1},
+          "description": "OPTIONAL (#225). The irreversible verbs the user granted for this job (merge, tag, publish, ...), written once at plan time. Declared, clock_in escalates on a unit whose `irreversible` verb is not listed; absent keeps today's behaviour."
+        },
+        "kind": {
+          "type": "string",
+          "enum": ["investigation", "experimentation"],
+          "description": "OPTIONAL (#264, #265). `investigation`: the job answers `question` by testing `hypotheses` in run units, each supported claim replayed by another role before `conclusion` may say resolved. `experimentation`: candidate units compete in their own worktrees on `experiment.objective`, each validated by another role at the exact SHA it submitted. Absent = today's job."
+        },
+        "experiment": {
+          "type": "object",
+          "required": ["objective", "direction", "base_sha", "harness", "concurrency_cap"],
+          "additionalProperties": false,
+          "properties": {
+            "objective": {"type": "string", "minLength": 1, "description": "What a candidate's score measures."},
+            "direction": {"type": "string", "enum": ["minimize", "maximize"], "description": "Which way a better score points."},
+            "base_sha": {"type": "string", "minLength": 1, "description": "The commit every candidate starts from. Frozen: once a brief or clock-out has read it, a checkpoint that says otherwise is refused."},
+            "harness": {"type": "string", "minLength": 1, "description": "The command that scores a candidate. Frozen like base_sha."},
+            "concurrency_cap": {"type": "integer", "minimum": 1, "description": "At most this many candidates in flight; clock_in refuses the next."},
+            "candidate_budget": {
+              "type": "object",
+              "additionalProperties": false,
+              "minProperties": 1,
+              "properties": {
+                "tokens": {"type": "integer", "minimum": 0, "description": "Tokens one candidate's accounting lines may record."},
+                "wallclock_ms": {"type": "integer", "minimum": 0, "description": "duration_ms one candidate's accounting lines may record."}
+              },
+              "description": "Per candidate, read off its own accounting lines; a candidate that has spent it is refused at clock_in."
+            }
+          },
+          "description": "OPTIONAL (#265). Required by `kind: experimentation`."
+        },
+        "question": {
+          "type": "string",
+          "minLength": 1,
+          "description": "OPTIONAL (#264). The question an investigation answers."
+        },
+        "hypotheses": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["id", "claim", "falsified_by"],
+            "additionalProperties": false,
+            "properties": {
+              "id": {"type": "string", "minLength": 1, "description": "What a run's `tests` and the conclusion's `supported` name."},
+              "claim": {"type": "string", "minLength": 1, "description": "What the hypothesis says is true."},
+              "falsified_by": {"type": "string", "minLength": 1, "description": "The observation that would refute it, written before any run."}
+            }
+          },
+          "description": "OPTIONAL (#264). An investigation declares at least two, or one with `single_hypothesis_rationale`; the batch view, clock_in and clock_out refuse one that does not."
+        },
+        "single_hypothesis_rationale": {
+          "type": "string",
+          "minLength": 1,
+          "description": "OPTIONAL (#264). Why an investigation tests only one hypothesis."
+        },
+        "conclusion": {
+          "type": "object",
+          "required": ["outcome", "evidence"],
+          "additionalProperties": false,
+          "properties": {
+            "outcome": {"type": "string", "enum": ["resolved", "inconclusive", "stopped"], "description": "`resolved` needs `supported`, a done run testing it, a done replay of that run, and a done review of either; the other two are never refused."},
+            "supported": {"type": "string", "minLength": 1, "description": "The hypothesis id the evidence supports."},
+            "evidence": {"type": "array", "items": {"type": "string", "minLength": 1}, "description": "Refs to what was observed: run outputs, commits, files."}
+          },
+          "description": "OPTIONAL (#264). Set only through clock_out's `conclusion`, by a unit with `concludes: true`."
+        },
+        "agreements": {
+          "type": "array",
+          "maxItems": 20,
+          "items": {"type": "string", "minLength": 1},
+          "description": "OPTIONAL (#261). Working agreements adopted during the job, carried on every brief. Changed only through clock_out's `agreements` {adopt, retire}; each change is recorded in retro[]."
+        },
+        "budget": {
+          "type": "object",
+          "description": "OPTIONAL (#262). What the job may spend, read back from <checkpoint>.log.jsonl: shiftwork_plan reports spent/remaining/affordable, clock_in refuses a brief that does not fit, and clock_out refuses a 0-token accounting line not marked `estimate`. Absent keeps today's behaviour exactly.",
+          "additionalProperties": false,
+          "minProperties": 1,
+          "properties": {
+            "tokens": {"type": "integer", "minimum": 1, "description": "Token ceiling, counted as accounting `tokens`."},
+            "units": {"type": "integer", "minimum": 1, "description": "Accounting lines (clock-outs) the job may record."},
+            "wallclock_ms": {"type": "integer", "minimum": 1, "description": "Sum of accounting `duration_ms` the job may record."}
+          }
         }
       }
     },
@@ -76,6 +161,79 @@
                 "description": "Driver dispatch key: role -> model/allowed tools, set in driver config."
               },
               "depends_on": {"type": "array", "items": {"type": "string", "minLength": 1}},
+              "attempts": {
+                "type": "array",
+                "maxItems": 3,
+                "description": "This unit's clock-outs, newest last, at most 3 (#259). Written by clock_out from its status and history_entry; clock_in hands them back as prior_attempts and as a dependant's upstream[].last.",
+                "items": {
+                  "type": "object",
+                  "required": ["status", "outcome"],
+                  "additionalProperties": false,
+                  "properties": {
+                    "status": {"type": "string", "enum": ["todo", "in_progress", "done", "blocked", "dropped"]},
+                    "outcome": {"type": "string", "minLength": 1},
+                    "notes": {"type": "string", "maxLength": 2000},
+                    "produced": {
+                      "type": "array",
+                      "items": {
+                        "type": "object",
+                        "required": ["kind", "ref"],
+                        "additionalProperties": false,
+                        "properties": {"kind": {"type": "string", "minLength": 1}, "ref": {"type": "string", "minLength": 1}}
+                      }
+                    }
+                  }
+                }
+              },
+              "reviews": {
+                "type": "array",
+                "items": {"type": "string", "minLength": 1},
+                "description": "Unit ids this unit reviews (#263). Optional. Each must be declared, be in this unit's depends_on, and have a different role from this unit; the batch view, clock_in and clock_out refuse a checkpoint that breaks any of the three."
+              },
+              "candidate": {
+                "type": "object",
+                "required": ["workspace", "author_role"],
+                "additionalProperties": false,
+                "properties": {
+                  "workspace": {"type": "string", "minLength": 1, "description": "The worktree the orchestrator created for this candidate, recorded here and removed by the orchestrator after validation."},
+                  "author_role": {"type": "string", "minLength": 1, "description": "The role that writes the candidate; must be this unit's role."}
+                },
+                "description": "OPTIONAL (#265). This unit is a candidate: `touches` does not hold it (its own worktree), its clock-out done reports {kind: commit, ref: <full sha>} and {kind: score, ref: <number>}, and a unit that `reviews` it validates that exact SHA."
+              },
+              "tests": {
+                "type": "array",
+                "items": {"type": "string", "minLength": 1},
+                "description": "OPTIONAL (#264). The hypothesis ids this run unit tests; each must be declared. A run clocked out done must report a `produced` item of kind `run-output`."
+              },
+              "procedure": {
+                "type": "string",
+                "minLength": 1,
+                "description": "OPTIONAL (#264). The command or brief path a run follows; a replay must name the same text exactly."
+              },
+              "replay_of": {
+                "type": "string",
+                "minLength": 1,
+                "description": "OPTIONAL (#264). The run this unit repeats: it must be declared, name a procedure equal to this unit's, and be in another role."
+              },
+              "concludes": {
+                "type": "boolean",
+                "description": "OPTIONAL (#264). The unit whose clock_out may set job.conclusion."
+              },
+              "irreversible": {
+                "type": "string",
+                "minLength": 1,
+                "description": "OPTIONAL (#225). The verb of an action that cannot be undone (merge, tag, publish, delete-branch). clock_in refuses such a unit without `prove`, and escalates when job.authorized is declared and does not list the verb."
+              },
+              "prove": {
+                "type": "string",
+                "minLength": 1,
+                "description": "OPTIONAL (#225). A command run against the BUILT artifact (packed tarball, installed wheel), beside `verify`, which checks the source. Required on an `irreversible` unit."
+              },
+              "touches": {
+                "type": "array",
+                "items": {"type": "string"},
+                "description": "Repo-relative POSIX paths this unit will WRITE (#257). Optional; absent or [] claims nothing. The batch view never puts two units sharing a path in one batch, and clock_in refuses a unit whose path a unit still in flight touches."
+              },
               "verify": {
                 "type": "string",
                 "minLength": 1,
@@ -185,8 +343,23 @@
         },
         "open_questions": {
           "type": "array",
-          "items": {"type": "string", "minLength": 1},
-          "description": "The autonomy switch: empty = driver keeps cycling, non-empty = STOP and ask."
+          "items": {
+            "anyOf": [
+              {"type": "string", "minLength": 1, "description": "A decision question: the user's to answer."},
+              {
+                "type": "object",
+                "required": ["q", "kind"],
+                "additionalProperties": false,
+                "description": "#225: a question with a kind. `decision` is the user's; `relay` is answered by its `probe` (shell, exit 0 = answered), which clock_in runs before deciding to escalate.",
+                "properties": {
+                  "q": {"type": "string", "minLength": 1, "description": "The question."},
+                  "kind": {"type": "string", "enum": ["relay", "decision"], "description": "`decision` needs the user; `relay` needs only its probe run."},
+                  "probe": {"type": "string", "minLength": 1, "description": "Shell command run from the repo root; exit 0 answers a relay question. Required on a relay: clock_out refuses one without it."}
+                }
+              }
+            ]
+          },
+          "description": "The autonomy switch: empty = driver keeps cycling, non-empty = STOP and ask — unless every entry is a relay question its probe answers (#225)."
         },
         "do_not": {
           "type": "array",

{bantamkit-0.37.2 → bantamkit-0.38.1}/_assets/tools/bantamkit_status.json

@@ -1,12 +1,18 @@
 {
   "name": "bantamkit_status",
   "title": "bantamkit status",
-  "description": "Is bantamkit working, and which bantamkit? Returns a short report a person can read in the transcript: `bantamkit Active 🟢` or `bantamkit Degraded 🟠` on the first line, then the version and `build_id` of the code answering, the surfaces it serves, the memory store it is bound to with its index size against its budget, whether the event log is on, and — when degraded — every condition in full with what to do about it. Call it when the user asks whether the server is alive or working, when a bantamkit tool answered oddly and you need to know whether the server is the reason, or when a reply arrived carrying a `bantamkit degraded` footer and you want the rest of it. Every fact is observed at call time from the server's own state; nothing is a heartbeat or a cached verdict. Takes no arguments, writes nothing, and never echoes another call's arguments. build_identity answers only the `build_id` fingerprint, as JSON, when all you need is to compare two installs; shiftwork_status reports a job, not the server.",
+  "description": "Is bantamkit working, and which bantamkit? Returns a short report a person can read in the transcript: `bantamkit Active 🟢` or `bantamkit Degraded 🟠` on the first line, then the version and `build_id` of the code answering, the surfaces it serves, the memory store it is bound to with its index size against its budget, whether the event log is on, and — when degraded — every condition in full with what to do about it. Call it when the user asks whether the server is alive or working, when a bantamkit tool answered oddly and you need to know whether the server is the reason, or when a reply arrived carrying a `bantamkit degraded` footer and you want the rest of it. Every fact is observed at call time from the server's own state; nothing is a heartbeat or a cached verdict. Pass `detail: true` to list every usage and touch ledger on its own line instead of one summary line per family. Writes nothing, and never echoes another call's arguments. build_identity answers only the `build_id` fingerprint, as JSON, when all you need is to compare two installs; shiftwork_status reports a job, not the server.",
   "surfaces": [
     "mcp"
   ],
   "parameters": {
-    "properties": {},
+    "properties": {
+      "detail": {
+        "type": "boolean",
+        "default": false,
+        "description": "true lists every usage and touch ledger on its own line; the default folds each family into one summary line."
+      }
+    },
     "type": "object",
     "title": "bantamkit_statusArguments",
     "additionalProperties": false

{bantamkit-0.37.2 → bantamkit-0.38.1}/_assets/tools/shiftwork_clock_in.json

@@ -1,7 +1,7 @@
 {
   "name": "shiftwork_clock_in",
   "title": "Shift work: clock in",
-  "description": "Shift-work clock-in: validate the checkpoint against the checkpoint schema and return the brief of ONE unit — {unit, role, invariants, handoff, do_not, files} — to hand to the agent you spawn, verbatim. Call it once per unit, right before spawning; use shiftwork_plan first to see the `ready` batch when several units are to run at once, and shiftwork_clock_out, not this tool, when a unit finishes. The unit briefed is plan.cursor, or `unit_id` when given; either way it must be in shiftwork_plan's `ready` — a done or dropped cursor, a cursor whose dependencies have not run, or a `unit_id` naming no unit answers {\"result\": \"error\", \"reason\": \"unit <id> is not ready; ready is <a, b>\"}, and the batch view's own refusals (cycle, unknown dependency, unreadable checkpoint) pass through verbatim. The other outcomes, never exceptions: `escalate` when handoff.open_questions is non-empty (stop and ask the user) or when the cursor names no unit, `success` when every unit is done or dropped, `error` when the checkpoint fails validation. It never moves plan.cursor; clock_out does. What it WRITES: on result=brief, and only then, one line {event: brief, ts, unit, role} appended to <checkpoint>.log.jsonl — best-effort, so a log it cannot write costs the brief nothing. That line is what later lets clock_out accept the unit while the cursor is elsewhere and sets `briefed` on its accounting line. The checkpoint file itself is never modified. See docs/shiftwork.md.",
+  "description": "Shift-work clock-in: validate the checkpoint against the checkpoint schema and return the brief of ONE unit — {unit, role, invariants, handoff, do_not, files} — to hand to the agent you spawn, verbatim. Call it once per unit, right before spawning; use shiftwork_plan first to see the `ready` batch when several units are to run at once, and shiftwork_clock_out, not this tool, when a unit finishes. The unit briefed is plan.cursor, or `unit_id` when given; either way it must be in shiftwork_plan's `ready` — a done or dropped cursor, a cursor whose dependencies have not run, or a `unit_id` naming no unit answers {\"result\": \"error\", \"reason\": \"unit <id> is not ready; ready is <a, b>\"}, and the batch view's own refusals (cycle, unknown dependency, unreadable checkpoint) pass through verbatim. A ready unit whose `touches` shares a path with a unit briefed and not yet clocked out is refused too, before any brief: `unit <id> touches <path>, which <other> holds until its clock-out`. A checkpoint whose `reviews` break review independence is refused with shiftwork_plan's sentence. With job.budget declared, a brief that does not fit is refused: `budget <dim> spent: <n> of <limit>; raise job.budget or stop the job`. The other outcomes, never exceptions: `escalate` when handoff.open_questions is non-empty (stop and ask the user) or when the cursor names no unit, `success` when every unit is done or dropped, `error` when the checkpoint fails validation. It never moves plan.cursor; clock_out does. What it WRITES: on result=brief, and only then, one line {event: brief, ts, unit, role} appended to <checkpoint>.log.jsonl — best-effort, so a log it cannot write costs the brief nothing. That line is what later lets clock_out accept the unit while the cursor is elsewhere and sets `briefed` on its accounting line. The checkpoint file itself is never modified. See docs/shiftwork.md.",
   "surfaces": [
     "mcp"
   ],
@@ -70,12 +70,30 @@
         "type": "array",
         "description": "state.artifacts: the files the job has produced so far."
       },
-      "open_questions": {
+      "upstream": {
+        "type": "array",
+        "description": "One {unit, title, status, last} per depends_on id, in depends_on order: last is that unit's newest attempt (status, outcome, notes?, produced?) or null. Always present with a brief."
+      },
+      "prior_attempts": {
+        "type": "array",
+        "description": "This unit's own attempts, oldest first, at most 3; [] when none. A unit clocked out todo and briefed again is a rework, and this is what it found."
+      },
+      "agreements": {
         "type": "array",
         "items": {
           "type": "string"
         },
-        "description": "With result `escalate`: the questions the orchestrator must put to the user before any unit runs."
+        "description": "job.agreements: the working agreements adopted so far through clock_out, carried on every brief; [] when none."
+      },
+      "open_questions": {
+        "type": "array",
+        "items": {
+          "anyOf": [
+            {"type": "string", "description": "A decision question."},
+            {"type": "object", "description": "A question with a kind (#225): {q, kind: relay|decision, probe}. Escalation happens only for a decision or a relay whose probe did not exit 0; an answered relay is logged as a `resolved` ledger event."}
+          ]
+        },
+        "description": "With result `escalate`: the questions the orchestrator must put to the user before any unit runs. An irreversible unit whose verb job.authorized does not grant also escalates (#225), with no open_questions."
       },
       "reason": {
         "type": "string",

{bantamkit-0.37.2 → bantamkit-0.38.1}/_assets/tools/shiftwork_clock_out.json

@@ -1,7 +1,7 @@
 {
   "name": "shiftwork_clock_out",
   "title": "Shift work: clock out",
-  "description": "Shift-work clock-out: record that a unit finished — set its status, advance plan.cursor, merge `handoff_patch` into handoff, push `history_entry` onto the 5-entry history ring, and append one accounting line to <checkpoint>.log.jsonl. Call it once per unit after its agent returns: shiftwork_clock_in briefs, this tool closes, and shiftwork_status reads what both wrote. The whole mutated document is validated against the checkpoint schema BEFORE one atomic write, so a failure writes nothing and answers {\"result\": \"error\", \"reason\": ...}; nothing is ever deleted from the checkpoint. `unit_id` must be plan.cursor — which needs no brief and clocks out with briefed=false — or a unit clock_in briefed since its own last clock-out; any other id is refused with `unit X is not the cursor unit Y`. `handoff_patch` and `history_entry` are both required arguments: pass `{}` to leave handoff unchanged, and give history_entry at least `unit` and `outcome`. plan.cursor then moves to the head of the ready batch recomputed on the new document — plan.units order over the remaining non-terminal units when the graph cannot batch, `unit_id` when none remain. The accounting line carries unit, role, status, ts and `briefed` (written by the runtime, never taken from you: true only when a brief was issued since this unit's LAST clock-out) plus your `accounting` fields when given. When job.roles names this unit's role, `accounting.model` must be on that role's list, spelled exactly, or nothing is written — see the `model` property.",
+  "description": "Shift-work clock-out: record that a unit finished — set its status, advance plan.cursor, merge `handoff_patch` into handoff, push `history_entry` onto the 5-entry history ring, and append one accounting line to <checkpoint>.log.jsonl. Call it once per unit after its agent returns: shiftwork_clock_in briefs, this tool closes, and shiftwork_status reads what both wrote. The whole mutated document is validated against the checkpoint schema BEFORE one atomic write, so a failure writes nothing and answers {\"result\": \"error\", \"reason\": ...}; nothing is ever deleted from the checkpoint. `unit_id` must be plan.cursor — which needs no brief and clocks out with briefed=false — or a unit clock_in briefed since its own last clock-out; any other id is refused with `unit X is not the cursor unit Y`. `handoff_patch` and `history_entry` are both required arguments: pass `{}` to leave handoff unchanged, and give history_entry at least `unit` and `outcome`. plan.cursor then moves to the head of the ready batch recomputed on the new document — plan.units order over the remaining non-terminal units when the graph cannot batch, `unit_id` when none remain. The accounting line carries unit, role, status, ts and `briefed` (written by the runtime, never taken from you: true only when a brief was issued since this unit's LAST clock-out) plus your `accounting` fields when given. `follow_ups` appends the work it discovered as todo units. `agreements` adopts or retires a working agreement every later brief carries. Each clock-out also appends {status, outcome, notes?, produced?} to the unit's attempts (newest 3 kept). With job.budget declared, a line reporting 0 tokens is refused unless it carries `estimate: true`. When job.roles names this unit's role, `accounting.model` must be on that role's list, spelled exactly, or nothing is written — see the `model` property.",
   "surfaces": [
     "mcp"
   ],
@@ -43,10 +43,21 @@
           "open_questions": {
             "type": "array",
             "items": {
-              "type": "string",
-              "minLength": 1
+              "anyOf": [
+                {"type": "string", "minLength": 1, "description": "A decision question: the user's to answer."},
+                {
+                  "type": "object",
+                  "required": ["q", "kind"],
+                  "additionalProperties": false,
+                  "properties": {
+                    "q": {"type": "string", "minLength": 1, "description": "The question."},
+                    "kind": {"type": "string", "enum": ["relay", "decision"], "description": "`decision` needs the user; `relay` is answered by its probe."},
+                    "probe": {"type": "string", "minLength": 1, "description": "Shell command run from the repo root by clock_in; exit 0 answers the relay. Required on a relay, or nothing is written."}
+                  }
+                }
+              ]
             },
-            "description": "The autonomy switch: empty = driver keeps cycling, non-empty = STOP and ask."
+            "description": "The autonomy switch: empty = driver keeps cycling, non-empty = STOP and ask. A bare string is a decision; a `relay` question carries a `probe` that clock_in runs instead of escalating (#225)."
           },
           "do_not": {
             "type": "array",
@@ -84,7 +95,30 @@
           },
           "notes": {
             "type": "string",
-            "description": "Optional free text for the next session reading the ring."
+            "description": "Optional free text for the next session reading the ring, and recorded in the unit's attempt (#259): at most 2000 code points."
+          },
+          "produced": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "required": [
+                "kind",
+                "ref"
+              ],
+              "properties": {
+                "kind": {
+                  "type": "string",
+                  "minLength": 1,
+                  "description": "What sort of thing: commit, file, pr, run-output."
+                },
+                "ref": {
+                  "type": "string",
+                  "minLength": 1,
+                  "description": "Where it is: a SHA, a path, a URL."
+                }
+              }
+            },
+            "description": "What the unit produced, [{kind, ref}] (a commit, a file, a run output). Recorded with the unit's attempt, and handed to every unit that depends on it as upstream[].last."
           }
         }
       },
@@ -92,7 +126,7 @@
         "anyOf": [
           {
             "type": "object",
-            "description": "Per-unit cost. Written verbatim, beside ts/unit/role/status, as one line of <checkpoint>.log.jsonl - the ledger the N-sessions experiment reads. The keys named here have fixed meanings so a reader holding only the ledger knows what each number counts, in which unit, and which model produced it; any other key passes through unchanged, except the five the runtime writes itself — unit, role, status, ts, event — which are refused (result=error) before anything is written; a self-reported briefed is overwritten, not refused. Lines written before this schema existed may spell these differently; the schema governs new writes only.",
+            "description": "Per-unit cost. Written verbatim, beside ts/unit/role/status, as one line of <checkpoint>.log.jsonl - the ledger the N-sessions experiment reads. The keys named here have fixed meanings so a reader holding only the ledger knows what each number counts, in which unit, and which model produced it; any other key passes through unchanged, except the six the runtime writes itself — unit, role, status, ts, event, agent_id — which are refused (result=error) before anything is written; a self-reported briefed is overwritten, not refused. Lines written before this schema existed may spell these differently; the schema governs new writes only.",
             "properties": {
               "tokens": {
                 "type": "integer",
@@ -118,6 +152,10 @@
                 "minimum": 0,
                 "description": "Tool calls the subagent made, as the harness counts them. Optional; it is the denominator that makes `tokens` comparable across units of different size (per-unit cost is linear in tool calls, not in unit length)."
               },
+              "estimate": {
+                "type": "boolean",
+                "description": "true when `tokens` is a guess rather than the host's figure. With job.budget declared, a line reporting 0 tokens is refused unless it carries estimate: true."
+              },
               "note": {
                 "type": "string",
                 "description": "Free text for what the fields above cannot say: that `tokens` is an estimate, that this is a retry or a second scope under the same unit id, what a harness counter excludes. Anything that is not a model identifier goes here, not in `model`."
@@ -136,6 +174,154 @@
         "default": null,
         "title": "Accounting",
         "description": "Per-unit cost line, or null (the default) to log a line with no cost figures at all. A non-null line must carry `tokens` and `duration_ms`; `model` is required when job.roles names this unit's role. The object shape is described below."
+      },
+      "follow_ups": {
+        "anyOf": [
+          {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "required": [
+                "id",
+                "title",
+                "role",
+                "brief_path"
+              ],
+              "properties": {
+                "id": {
+                  "type": "string",
+                  "minLength": 1,
+                  "description": "The new unit's id; must not be a unit already, nor repeat in this list."
+                },
+                "title": {
+                  "type": "string",
+                  "minLength": 1,
+                  "description": "One line naming the work."
+                },
+                "role": {
+                  "type": "string",
+                  "enum": [
+                    "planner",
+                    "implementer",
+                    "reviewer"
+                  ],
+                  "description": "Who runs it; when job.roles is declared it must be one of its keys."
+                },
+                "brief_path": {
+                  "type": "string",
+                  "minLength": 1,
+                  "description": "Its brief, a file that must already exist, relative to the repo (the nearest ancestor of the checkpoint holding .git)."
+                },
+                "depends_on": {
+                  "type": "array",
+                  "items": {
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "description": "Unit ids it waits for; absent means the unit being clocked out."
+                },
+                "verify": {
+                  "type": "string",
+                  "minLength": 1,
+                  "description": "Command proving it done; absent means the clocked-out unit's verify."
+                },
+                "touches": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  },
+                  "description": "Repo-relative paths it will write (#257)."
+                }
+              }
+            }
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "default": null,
+        "title": "Follow Ups",
+        "description": "Work this unit discovered (#260): each item becomes a todo unit appended to plan.units in the given order, on the same write. Refused whole, nothing written, on a duplicate id, a brief that is not a file, an unknown dependency or a cycle (the planner's sentence), or a role job.roles does not declare."
+      },
+      "agreements": {
+        "anyOf": [
+          {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "adopt": {
+                "type": "array",
+                "items": {
+                  "type": "string",
+                  "minLength": 1
+                },
+                "description": "Agreements to add to job.agreements; text already listed is left as it is."
+              },
+              "retire": {
+                "type": "array",
+                "items": {
+                  "type": "string",
+                  "minLength": 1
+                },
+                "description": "Agreements to remove, by exact text; one not on the list is refused."
+              }
+            }
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "default": null,
+        "title": "Agreements",
+        "description": "A lesson this unit wants every later brief to carry (#261): retire by exact text, then adopt. Refused, nothing written, for text not on the list or a result over 20; each applied change is recorded in retro[]."
+      },
+      "conclusion": {
+        "anyOf": [
+          {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["outcome", "evidence"],
+            "properties": {
+              "outcome": {
+                "type": "string",
+                "enum": ["resolved", "inconclusive", "stopped"],
+                "description": "`inconclusive` and `stopped` are never refused; `resolved` needs the evidence below."
+              },
+              "supported": {
+                "type": "string",
+                "minLength": 1,
+                "description": "The hypothesis id the evidence supports; required for `resolved`."
+              },
+              "evidence": {
+                "type": "array",
+                "items": {
+                  "type": "string",
+                  "minLength": 1
+                },
+                "description": "Refs to what was observed: run outputs, commits, files."
+              }
+            }
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "default": null,
+        "title": "Conclusion",
+        "description": "An investigation's answer (#264), written to job.conclusion. Only a unit with `concludes: true` may send it; `resolved` is refused unless `supported` has a done run, a done replay of that run in another role, and a done review of either. A run unit (`tests` or `replay_of`) clocked out done must report a `run-output` in history_entry.produced."
+      },
+      "agent_id": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "default": null,
+        "title": "Agent Id",
+        "description": "The `agentId` the Agent tool's result returned for this unit's subagent (#266), copied verbatim: 1 to 64 letters, digits, - or _, or nothing is written. It goes on the accounting line, never into the checkpoint, and is how the skill miner attributes the skill uses the hook logged inside that subagent to this unit. Omit it for a unit run inline."
       }
     },
     "required": [