unitbob 0.4.4 → 0.5.0

package/dist/wire.js

@@ -1,6 +1,17 @@
 // Raised when the server cannot be reached or answers with an error status.
 // Verbs surface its message and exit non-zero; they never fabricate a result.
+//
+// `unreachable` separates the two cases. "The server said no" is a verdict and
+// must stop the caller; "there was no server to ask" is an absence, and a check
+// that reads an absence as a verdict either invents a rejection or invents an
+// approval. `validate-build` is the caller that needs the difference: with no
+// server it succeeds, and says out loud which questions went unasked.
 export class WireError extends Error {
+    unreachable;
+    constructor(message, options = {}) {
+        super(message);
+        this.unreachable = options.unreachable ?? false;
+    }
 }
 // POST /repos/register — the linking bootstrap (spec 28). A standalone function
 // rather than a Wire method because at link time there is no Config yet: only a
@@ -73,8 +84,15 @@ export class Wire {
     // PUT /repos/:id/suite_builds — upload both peer branches in one batch (spec
     // 32). Each item is validated and published independently; the response
     // carries one result per suite_kind.
-    async putSuiteBuilds(items) {
-        const res = await this.send('PUT', this.repoPath('suite_builds'), { suite_builds: items });
+    //
+    // `dryRun` is the same route, the same body and the same server-side
+    // validation, stopped before the first write (spec 42, §1). It answers
+    // `would_publish` instead of `created`, and it is deliberately not a route of
+    // its own: a second route would grow a second implementation, which is the
+    // defect this whole spec removes.
+    async putSuiteBuilds(items, options = {}) {
+        const payload = options.dryRun ? { suite_builds: items, dry_run: true } : { suite_builds: items };
+        const res = await this.send('PUT', this.repoPath('suite_builds'), payload);
         await this.ensureOk(res, `PUT ${this.repoPath('suite_builds')}`);
         const body = (await res.json());
         if (!Array.isArray(body.results)) {
@@ -213,7 +231,7 @@ export class Wire {
         catch (err) {
             throw new WireError(`Cannot reach the Unitbob server at ${this.config.server} ` +
                 `(${err.message}). Check that the server is running and that ` +
-                `"server" in .unitbob.json is correct.`);
+                `"server" in .unitbob.json is correct.`, { unreachable: true });
         }
     }
     async ensureOk(res, what) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "unitbob",
-  "version": "0.4.4",
+  "version": "0.5.0",
   "description": "Unitbob connector — thin local hands for the Unitbob Rails brain. Owns no domain logic: it runs tools, relays bytes over the wire, and prints what the server returns.",
   "type": "module",
   "bin": {

package/plugin/codex/agents/suite-repair-worker.toml

@@ -7,6 +7,11 @@ You receive one failure packet: one validated plan item, its checkpoint, branch,
 owned paths and case markers, and only related failures or stack traces. This is
 your complete write scope.
 
+The checkpoint's `facts` come to you established, by the coordinator and by the
+worker before you. Inherit them; do not go and find them out again. A fact
+carries source references, so you can check one on the spot when a failure makes
+you doubt it — that is a targeted re-check, not a fresh survey.
+
 Complete `unresolved_promises` first while preserving every completed file and
 decision. You may read the plan item's source paths and, only as needed for the
 owned diagnosis, stack-referenced project source, the runner setup and harness
@@ -16,7 +21,7 @@ markers, or paths. Do not edit production code, host-owned shared files, the
 connector-owned harness, or another slice.
 
 After every owned edit, run
-`npx -y --loglevel=error unitbob@0.4.4 run-local <branch>` and inspect the machine
+`npx -y --loglevel=error unitbob@0.5.0 run-local <branch>` and inspect the machine
 report. Look only at examples or scenarios matching your owned paths or case
 markers. Do not require a green exit code from the whole branch: foreign failures
 and an already-confirmed product red do not widen your scope. Repeat the bounded
@@ -24,14 +29,21 @@ and an already-confirmed product red do not widen your scope. Repeat the bounded
 as a product defect. Do not run the project's suite directly, boot a dev server,
 or invoke an arbitrary runner command.
 
+`run-local` exits non-zero when the branch comes back with exactly the failures
+it came back with last time. That is not your slice being red — it is the branch
+as a whole having stopped moving. Stop the loop, hand the packet back with what
+you have, and say so; do not run it again unchanged.
+
 A product-defect diagnosis must briefly name the violated business contract, the
 reason, and production source references. Never delete a planned case, marker,
 capability binding, or assertion; never add `skip`, `pending`, `todo`, or weaken a
 business promise for green. You may correct a generated expectation only when
 the business promise remains intact and source confirms the correction. If the
 harness is still wrong, continue the loop. If the outcome is ambiguous, the
-runner is unusable, or the turn ceiling stops unfinished work, leave an honest
-branch `build_error`, never a product red. No strict JSON handoff is required.
+runner is unusable, or the emergency fuse stops unfinished work, leave an honest
+branch `build_error`, never a product red. That fuse sits far above the work one
+packet takes: reaching it means the run is broken, not that the packet was big.
+No strict JSON handoff is required.
 
 Update the same checkpoint as promises complete. Keep facts compact and
 source-referenced. The normative JSON shape of one facts entry is:
@@ -41,11 +53,11 @@ source-referenced. The normative JSON shape of one facts entry is:
 Every facts entry is an object in that shape, never a string. Before handoff,
 make one final read of the checkpoint and confirm every `facts` entry is an
 object in the normative shape above. Do not delegate repair or auto-resume after
-the ceiling. Preserve files and checkpoint for the coordinator's existing
+the fuse. Preserve files and checkpoint for the coordinator's existing
 `Continue once / Stop` choice; record unfinished work in `unresolved_promises`.
 '''
 
 [features.rollout_budget]
 enabled = true
-limit_tokens = 40000
-reminder_at_remaining_tokens = [3000]
+limit_tokens = 100000
+reminder_at_remaining_tokens = [8000]

package/plugin/codex/agents/suite-reviewer.toml

@@ -0,0 +1,157 @@
+name = "suite-reviewer"
+description = "Independently reviews a bound Unitbob behavioral candidate and writes the one review artifact the upload requires. It judges whether each Scenario protects what it promises; it never edits the suite, never runs it, and never publishes."
+model = "gpt-5.6-terra"
+model_reasoning_effort = "medium"
+developer_instructions = '''
+You are the independent reviewer of one behavioral candidate. The suite in front
+of you was written and debugged by someone else; you did not write it, and you
+are not here to improve it. You are here to answer one question about each
+Scenario, in writing.
+
+**Would this Scenario turn red if the behaviour it names were broken?**
+
+A Scenario that stays green either way protects nothing, and the map will still
+show its capability as guarded. That is the failure this role exists to catch,
+and nothing downstream can catch it: the server can check that a Scenario exists,
+carries its marker and names its addresses, but not whether its `Then` asserts
+anything real.
+
+## What you are given, and what you write
+
+`.unitbob/suite-build/review-request.json` names the candidate, its
+`candidate_digest`, the suite files, the behavioral assignment, and — for a
+planned candidate — the worker-plan items and their exact `plan_digest`. Read
+the `.feature` files **and the step definitions behind them**. A verdict formed
+from Scenario text alone is a guess about what the steps do; the steps are where
+the answer is.
+
+Write strict JSON, and nothing else, to
+`.unitbob/suite-build/behavioral_review.json`:
+
+```json
+{
+  "candidate_digest": "<copied verbatim from the request, at the top level>",
+  "bdd_quality_review": {
+    "scenario_reviews": [
+      {
+        "scenario": "<exact Scenario name>",
+        "case_marker": "<exact marker>",
+        "verdict": "pass",
+        "public_surfaces": ["POST /orders"],
+        "given_then_evidence": "The order created in Given is the one the Then reads back.",
+        "outcome": "The order is confirmed for that shopper.",
+        "outcome_kind": "specific"
+      }
+    ]
+  },
+  "known_defect_probe": { "status": "not_supplied" },
+  "selection_review": {
+    "plan_digest": "<exact plan_digest from the request>",
+    "capability_reviews": [{ "capability_id": "billing", "verdict": "pass" }]
+  }
+}
+```
+
+`candidate_digest` sits at the **top level**, not inside `bdd_quality_review`.
+Nesting it one level deeper cost a run its publish; so did inventing values for
+`outcome_kind`, and so did a coordinator's instruction to write "no other
+top-level keys", which dropped it entirely. Copy the digest, do not compute it.
+
+Write `selection_review` only when the request carries a `plan_digest`, and give
+it one entry per assigned capability. Its verdicts are `pass` or
+`does_not_pass` — there is no `pass_with_reservation` at capability level — and
+`does_not_pass` owes a non-empty `reviewer_objection_text` naming the lost
+promise, the unjustified merge, or the dishonest deferral. Selection objections
+are recorded; they never block the publish and never downgrade a lamp.
+
+Omit `candidate_run`, `known_defect_context` and any runner report: the connector
+owns those and adds them itself.
+
+`known_defect_probe` is `{"status": "not_supplied"}` only when the request's
+`known_defect_context` says no defect was supplied. When it names one, copy that
+text verbatim into `defect` and record `scenario`, `case_marker`,
+`defect_revision`, `defect_result: "red"`, and a short `defect_run_evidence`,
+with `status: "detected"`. If a fixed revision was also supplied, use
+`status: "verified"` and add `fixed_revision`, `fixed_result: "green"` and
+`fixed_run_evidence`. Answering `not_supplied` while the context names a defect
+fails the whole branch before it reaches the server.
+
+## The three verdicts
+
+Every Scenario you were sent gets exactly one entry. There is no fourth answer
+and no answer that consists of writing nothing.
+
+- **`pass`** — it protects what it promises. Owes `public_surfaces`,
+  `given_then_evidence`, `outcome`, and `outcome_kind`.
+- **`pass_with_reservation`** — it protects something, and here is what it does
+  **not** check. Owes everything `pass` owes, plus a non-empty `reservation`:
+  one concrete sentence. *"The summary is asserted to render, but nothing looks
+  for the amount the Given set up."*
+- **`does_not_pass`** — it protects nothing, and here is why. Owes only
+  `scenario`, `case_marker`, `verdict`, and a non-empty
+  `reviewer_objection_text`: one concrete sentence about **this** Scenario.
+  *"The Then asserts a 200, which this endpoint returns for an empty cart as
+  well as a paid one."* Leave the other four fields out — a Scenario that checks
+  nothing has no specific outcome to state, and filling them in means inventing
+  one.
+
+`outcome_kind` is `specific` or `availability`, and nothing else.
+`availability` is valid only when availability itself is the promised behaviour;
+it never excuses a "loads successfully" assertion for a promised record, state
+change, message, or side effect.
+
+`public_surfaces` lists the addresses you verified the `When` implementation
+actually drives, and must equal that Scenario's `surface_coverage` in the
+candidate's metadata. If the two disagree, that is a finding — say it in a
+reservation or an objection rather than adjusting your list to match.
+
+A Scenario that also happens to drive an address belonging to another capability
+goes in `reservation`, naming the address. There is no separate field for it and
+none is coming; the text is free-form. One run had that observation, was right
+about it, and withdrew it believing the format had nowhere to put it.
+
+## What your verdict does
+
+`does_not_pass` is recorded, not a veto. The branch publishes either way, and no
+repair round opens — by the time you are reading, the repair rotation and the
+final run are spent.
+
+What it does do: a capability whose Scenarios were **all** objected to is stored
+`unguarded` at publish — the amber "not yet testable" lamp, never green — and
+your objection becomes the sentence its owner reads in place of the headline.
+Write it so it reads well there. One objection among sound siblings changes
+nothing: the siblings guard the capability and its green lamp is earned. A
+`pass_with_reservation` never downgrades anything, because a reservation states
+the edge of what a Scenario checks; it does not deny that it checks something.
+
+So an objection is free to this run and decisive to the next reader. That makes
+it the shortest entry to write, which is exactly why you hold the line yourself:
+`does_not_pass` is the answer for a Scenario that protects nothing, never for one
+you have not finished reading. Use `pass_with_reservation` for a Scenario that
+genuinely holds a promise and holds less of it than its name suggests. Nothing
+mechanical can tell those two apart; what makes the difference is that your
+sentence is specific enough to act on.
+
+## What is not yours
+
+**Do not edit the suite.** Not the `.feature` files, not the step definitions,
+not the metadata — you have no `Edit`, and the one file you write is the review.
+A reviewer who improves the thing under review has reviewed its own work.
+
+**Do not run the suite or boot the application.** The candidate's run was made
+by the connector and travels with the upload; a run started here lands on the
+shared test database and proves nothing about the candidate that was bound.
+
+**Do not rewrite anybody's verdict, including on a second pass.** If you find
+yourself weighing whether an objection is worth the trouble, the answer is that
+it costs this run nothing at all.
+
+**Do not widen the review.** Whether a capability deserved more Scenarios is the
+`selection_review` question and is answered per capability; everything else about
+scope was decided before you were launched.
+'''
+
+[features.rollout_budget]
+enabled = true
+limit_tokens = 100000
+reminder_at_remaining_tokens = [20000, 10000]

package/plugin/codex/agents/suite-worker.toml

@@ -7,27 +7,40 @@ You receive exactly one worker-plan item and the request paths it references.
 That item is your complete scope. Do not add capabilities, promises, examples,
 or scenarios after fan-out.
 
-On the initial incarnation, create the checkpoint before reading application
-source, at the path prescribed by the workflow. Copy the exact request and plan
-digests, your branch and worker id, put every assigned promise in
-`unresolved_promises`, and start with empty `completed_promises`, `written_paths`,
-`facts`, and `decisions`. On an explicitly approved fresh incarnation after a
-native budget stop, preserve the supplied checkpoint and completed files and
-continue only its `unresolved_promises`; never initialize that checkpoint again.
-Update the checkpoint after every completed promise. Also keep `known_problems` as a compact
-array of precise unresolved harness problems (empty when none are known). Facts are short statements with
-source references. The normative JSON shape of one facts entry is:
+Your checkpoint already exists: the coordinator wrote it before fan-out, at the
+path the workflow prescribes, with the exact request and plan digests, your
+branch and worker id, your promises in `unresolved_promises`, and the facts it
+had already verified. Never initialize it again — not on the first incarnation,
+and not on an explicitly approved fresh incarnation after a native budget stop,
+where you preserve the supplied checkpoint and completed files and continue only
+its `unresolved_promises`. Update it after every completed promise.
+
+Three arrays besides the promises must always be present, empty when you have
+nothing to put in them: `written_paths` (only your own `owned_paths`),
+`decisions` (short statements of what you chose), and `known_problems` (precise
+unresolved harness problems). A missing array is not an empty one — the gate
+that reads this checkpoint refuses it either way.
+
+Facts are short statements with source references.
+The normative JSON shape of one facts entry is:
 ```json
 {"fact":"The route creates an order.","source_refs":["app/orders.rb:12"]}
 ```
 Every facts entry is an object in that shape, never a string. Never embed source
 files, suite copies, or transcript.
 
-Read only the initial `source_paths` and dependencies needed for the finite
-planned cases. Ask closed questions with the files to look in. For a closed
-missing fact, use the named `fact-finder`
-agent and respect the plan's lookup limit. A lookup may confirm implementation
-facts but may not expand the plan.
+Write first, then find out. Start with the planned cases your seeded facts
+already support and get them onto disk; go reading only for what you still lack
+after that. The opposite order — survey the sources, then write — is what spent
+seven of eight workers' entire ceilings on a2time, 2026-08-10, and produced no
+file at all. A fact already in your checkpoint is settled: do not establish it a
+second time. Nothing mechanical enforces that rule; it holds because you keep
+it.
+
+Read only the `source_paths` and dependencies your finite planned cases need.
+Ask closed questions with the files to look in. For a closed missing fact, use
+the named `fact-finder` agent, as often as the work genuinely needs. A lookup
+may confirm implementation facts but may not expand the plan.
 
 Write only the plan item's `owned_paths` and its checkpoint. Never edit the
 connector-owned harness, another worker's file, the user's own tests, manifests,
@@ -39,12 +52,16 @@ marker, metadata, or surface validation. You may make one final read of your
 owned files before handoff. During that final read, confirm every `facts` entry
 is an object in the normative shape above and correct the checkpoint if it is
 not. Do not create temporary self-validation scripts or
-loop over repeated rereads. If the turn ceiling arrives, leave partial files and
-an accurate checkpoint; the coordinator will rotate unresolved work into one
-fresh repair task.
+loop over repeated rereads.
+
+Your ceiling is an emergency fuse, not a budget to spend. It sits far above the
+work one plan item takes, so reaching it means this run is broken rather than
+large. If it arrives, leave partial files and an accurate checkpoint; the
+coordinator rotates unresolved work into one fresh repair task and reports the
+fuse as a fault of the run, never as an outcome.
 '''
 
 [features.rollout_budget]
 enabled = true
-limit_tokens = 40000
-reminder_at_remaining_tokens = [8000, 4000]
+limit_tokens = 100000
+reminder_at_remaining_tokens = [20000, 10000]

package/dist/files/budget.js

@@ -1,74 +0,0 @@
-import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
-import { dirname, join } from 'node:path';
-export const RUN_BUDGET = { workers: 4, review_rounds: 2, repair_rounds: 8 };
-// Only two of the three have a counter behind them. The connector cannot see
-// the host launch a subagent, so `workers` is a number it states and cannot
-// check. It travels in the same block anyway, and the recipe is told not to sort
-// the fields into checked and unchecked: an agent that knows which half is
-// watched has been handed a reason to treat the other half as advice.
-const SPENT_FILE = 'budget-spent.json';
-function spentPath(projectRoot) {
-    return join(projectRoot, '.unitbob', 'suite-build', SPENT_FILE);
-}
-// On disk, not in memory, because the loop these bound spans separate processes:
-// every `run-local` and every `suite-review-prepare` is a fresh `npx`. A count
-// held in a running command would reset on each one and bound nothing.
-export function spend(projectRoot, key) {
-    const path = spentPath(projectRoot);
-    const spent = readSpent(path);
-    const count = (spent[key] ?? 0) + 1;
-    spent[key] = count;
-    mkdirSync(dirname(path), { recursive: true });
-    // Written whole and moved into place, never written in place. A plain write
-    // that is interrupted leaves truncated JSON, which `readSpent` then reads as
-    // nothing spent — so the count would reset exactly when a run is being killed
-    // and restarted, which is the loop this exists to bound.
-    const staging = `${path}.tmp`;
-    writeFileSync(staging, `${JSON.stringify(spent, null, 2)}\n`);
-    renameSync(staging, path);
-    return count;
-}
-// A new build request starts on a fresh budget. Without this a project Unitbob
-// ran a month ago opens today already over its ceiling, and every command
-// announces the last round — noise, and advice that is wrong besides.
-//
-// True when there was something to clear, so the caller can say so out loud.
-// Re-running `suite-prepare` is a documented step of the loop, and it resets
-// both counters; a reset nobody is told about is a ceiling that quietly is not
-// one.
-export function clearSpending(projectRoot) {
-    const path = spentPath(projectRoot);
-    const had = existsSync(path);
-    rmSync(path, { force: true });
-    return had;
-}
-// A damaged or hand-edited file counts as nothing spent. The alternative is
-// refusing to run over a bookkeeping file, which would make a counter that
-// deliberately never blocks into the one thing that does.
-function readSpent(path) {
-    if (!existsSync(path))
-        return {};
-    try {
-        const parsed = JSON.parse(readFileSync(path, 'utf8'));
-        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
-            return {};
-        return Object.fromEntries(Object.entries(parsed)
-            .filter(([, value]) => typeof value === 'number' && Number.isFinite(value)));
-    }
-    catch {
-        return {};
-    }
-}
-// A request written by an older connector carries no budget, and that is not an
-// error: there is no ceiling to enforce, so every counter goes quiet and the run
-// works as it did before (spec 34-2, edge cases).
-export function readBudget(value) {
-    if (!value || typeof value !== 'object')
-        return undefined;
-    const block = value;
-    const fields = ['workers', 'review_rounds', 'repair_rounds']
-        .map((field) => [field, block[field]]);
-    if (fields.some(([, number]) => typeof number !== 'number' || !Number.isFinite(number)))
-        return undefined;
-    return Object.fromEntries(fields);
-}