bareloop 0.50.0 → 0.51.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -5,6 +5,21 @@ All notable changes to bareloop are documented here. Format:
5
5
  [SemVer](https://semver.org/spec/v2.0.0.html). Pre-1.0: **minor** = a ladder rung or
6
6
  feature lands, **patch** = docs, fixes, scaffolding.
7
7
 
8
+ ## [0.51.0] - 2026-10-29
9
+
10
+ ### Added
11
+
12
+ - **A handoff note: later workers are told which files earlier workers read (F253).** The next step or fix ask of a run (a retry of the same step too) gets a code-written map appended to its first prompt: one line per file an earlier ask read, with its line count and, from the LiteCtx index, its function names and line ranges. Capped at 8,000 characters (oldest paths dropped first, with a marker); arbiter books, `.git` and anything outside the job root are never named; scout and drafter prompts are unchanged. On by default; a signed spec's optional `handoffNote: false` turns it off (absent keeps the old hash). One report-only `handoff-note` spine record per note given. A resumed leg starts with an empty map.
13
+ - **An online/offline dot in the panel header, left of Settings.** When the panel's node process dies the open page used to look exactly like a live one; the Runs list read (already polled every 10 s) now paints a green "online" on any HTTP reply, even an error, and a red "offline" only when the read fails with no HTTP status. No new endpoint or timer. `getJSON` now tags its HTTP error with `.status` (message unchanged).
14
+
15
+ ### Fixed
16
+
17
+ - **A page render error no longer paints the online dot offline.** If drawing the Runs list threw after the fetch had succeeded, the error fell into the same handler as a failed read and the header showed "offline" while the panel was up. The render now has its own guard that logs the error to the browser console; only a real fetch failure (no HTTP reply) paints offline.
18
+ - **A command check now names its own command in the panel (F256).** Every check that runs a command used to read "does the test suite pass?", so a whole-repo `npx tsc --noEmit --strict` check and the real test suite read the same question. It now quotes the signed command: `does "npm test" exit clean?`, `does "npx tsc --noEmit --strict" exit clean?`. A check with no command falls back to its own name, as before.
19
+ - **The drafter is told to count one file with scope, never a path in `lineMatch` or a region anchor, with an example (F255).** The author prompt's parser description now says: to count lines about one file or folder, keep `lineMatch` general (e.g. `error TS\d+`) and put the file or folder in `scope.includePrefixes`, because a path in `lineMatch` stops matching once that file is clean and the check becomes a broken instrument instead of reading zero; it shows one legal `count-not-worse` example. Prompt-only; the validator is unchanged. Proven in a $0.73 drafter POC (path-in-parser 8/10 before, 0/10 after), not yet in a live run.
20
+ - **The planner is told `exit` is required on every step, with a legal example (F254).** The plan prompt called `exit` "1..2 form checks" and never said every step needs one, and a redraft got only the validator's rule. The prompt now says `REQUIRED on EVERY step` and shows two legal `exit` shapes, and the missing-exit red carries the same example. On deepseek-flash first drafts refused 8 of 23 before and 1 of 24 after; plan-red 1 before, 0 after.
21
+ - **The read shim no longer tells a later attempt it already holds a file it never received.** Every `ask()` builds a fresh Loop with a fresh transcript, but the shim's delivered-ledger lived for the whole worker, so attempt 2 re-reading a file attempt 1 had fully received got "unchanged since you read it, you already hold all N bytes" about bytes its model never saw. The ledger now resets at the start of each `ask()` (not at `askFrom`, which continues the same transcript); the run-level MEMORY-CACHE counts are untouched. (F252)
22
+
8
23
  ## [0.50.0] - 2026-10-28
9
24
 
10
25
  ### Added
@@ -159,6 +159,7 @@ minting claim, or the shell-owned retry cap — all unknown-field reds.
159
159
  | `closeTimeoutMs` | optional integer ms `>= CLOSE_TIMEOUT_FLOOR_MS` (120,000 — hamr's arbiter floor, 2026-09-07) | PRD item 27/M3's SIGNED override for the close's own per-stage wall-clock cap. Absent (the normal case): the run autosets it from a $0 seed timing pass — `max(FLOOR, K × slowest measured stage)`, `K = 5` (hamr, 2026-09-07: "2 and 5 are fine"). Present: the operator's own number wins outright and may legally sit ABOVE *or below* the autoset estimate (the rates-passthrough shape, F113 — never tighten-only). Arbiter territory exactly like `budgetUsd`/`maxWallMs`/`close[].sha256`: the authoring pipeline's `assembleSpec` refuses a draft carrying it |
160
160
  | `model` | optional non-empty string, the exact model id of a line ticked in Settings > Providers | the WORKER's model. A job carries its own model (P8: bareloop has no default); a spec signed before that (no `model`, perhaps no `baseUrl`) runs on the line `--model <id>` names (plus `--provider <KEY>` when two keys tick it) — the signed hash is untouched. Present, it wins over a `--model` flag outright, and a flag naming a different id is refused (`resolveWorkerModel`, `src/job.js`) rather than silently overridden. Part of the signed hash like every other field. Worker only — the JUDGE's model comes from the `judge` row below, which DEFAULTS to this same worker model |
161
161
  | `thinking` | optional boolean | the job's "Thinking on" tick (P8): absent = off, and an old spec keeps the hash it always had; present it is signed like `model`. Covers DRAFTING and the rubric JUDGE, and makes every WORKER call think (see "Thinking on" below) |
162
+ | `handoffNote` | optional boolean | the handoff note switch: absent = ON, only an explicit `false` turns it off; an old spec keeps the hash it always had, and a present value is signed (the switch enters `jobSpecHash` and `workflowKey`; the note's text never does). Not shown in the panel. See "Handoff note" below |
162
163
  | `judge` | optional `{provider, model}`, both non-empty; `provider` from the `PROVIDERS` menu | the signed JUDGE override (PRD item 32). Absent, the judge resolves to this job's own `provider`/`model` (`resolveJudge`) — which is what lets a non-Anthropic job judge without a second account. Present, it pins a judge deliberately different from the worker (an independent reader). Both halves are required together: a judge with a provider and no model is an identity nobody signed. Part of the signed hash, so changing it kills the signature and forces recalibration. Unknown nested keys red — no smuggling level exists in a signed spec. The drafting agent cannot express it: naming your own examiner is arbiter territory |
163
164
  | `writeScope` | array of contained globs | the operator's outer fence; the plan's own scopes must fit inside it, same containment code |
164
165
  | `steps` | RETIRED | operator-authored `steps[]` was deleted (PRD v1.32); a spec carrying it reds `shape-retired:steps` by name rather than half-running |
@@ -363,7 +364,7 @@ middle writes; `validatePlan` gates it against the SIGNED job spec before tokens
363
364
  | `steps[].model` | optional; `sonnet` (`STEP_MODELS`) | the step's model TIER — a menu, never a model string the agent spells (`sonnet` is a schema token meaning this job's worker model; the runner maps it, there is no tier table). `opus` is deliberately absent: reserved for work the human assigns, never plan-selectable; `haiku` was removed 2026-08-06 as a reversible ATTRIBUTION PROBE (F87, see `STEP_MODELS`), so the menu is one entry deep and the field is no longer offered in the drafting prompt. The field and its validator branch STAY: `model: "sonnet"` still validates, a stored bridge declaring it still loads, and restoring haiku is a one-token edit — this is not a finding that haiku is incapable. **The narrowing binds only what the AGENT may express.** Which real model a tier maps to, and what the caller runs as its own default worker model, stay the OPERATOR's: `providerFor` is yours, and the in-repo runner's `--model haiku` probe knob is untouched (PRD v1.36) — the runner's tier map is deliberately WIDER than the plan menu. Off-menu reds `invalid-value`. A step naming a tier when the caller supplied no `providerFor` factory is an `interpreter-red` STOP, never a silent run on the default tier |
364
365
  | `steps[].attempts` | optional; int `>= 1` | **RETIRED and INERT (F79) — it bounds nothing.** A step's iterations are governed by the STRIKE LADDER (below), which is shell-owned and inexpressible from the plan. The field is no longer offered in the drafting prompt and the runner ignores it; it is deliberately still ACCEPTED, because stored bridge plans carry it and a plan minted under one runner's number must not red under another's. The shape is still checked (a known field holding garbage stays a `bounds` red); the old `<= capRuns` ceiling is gone with the cap it named. It was previously TIGHTEN-only — which meant a step that needed MORE iterations could not ask, and drafters measurably tightened it instead (F77) |
365
366
  | `steps[].scope` | optional; one value from the SAME menu `tree-changed` uses | narrows this step's live WRITE fence to a subset of the signed `writeScope` — chosen from the offered scope menu (below), never authored. Off-menu reds `invalid-value` carrying the menu |
366
- | `steps[].exit` | 1..2 items (`MAX_EXITS_PER_STEP`), ALL must pass (AND-only, no OR/NOT) | closed menu (`EXIT_TYPES`): `artifact-written(path, pattern?)` · `tree-changed(scope)` · `json-valid(path)` · `check-passes(name)`. **`tree-changed.scope` is a MENU, not a glob the agent authors** — the runner enumerates the signed fence entries plus the real directories beneath them (shallowest-first, capped at `MAX_SCOPE_MENU`=24; `legalScopes` in `src/plan.js`), `planPrompt` lists them verbatim, and `validatePlan` accepts membership only — the SAME array on both sides, so what was offered is what is accepted; omitted, it derives from `writeScope` alone — never a free-text fallback. An off-menu value that escapes the fence still reds `scope-escape` (the ledger's attribution class), an in-fence unoffered value reds `invalid-value` carrying the menu. `runPlan` emits `scope-menu {offered, truncated, offerableCount?, cap?}` so a capped menu is never silently complete. `check-passes` must name a stage on the close's DERIVED menu (`check-unknown` red names the offered menu — no operator authors this list, it comes straight from `checkMenu(close)`); on a write-granted step it must be paired with `tree-changed` (`exit-illegal` — the seed tree is green, a lone check would pass untouched, F17/F46). **`check-passes` also requires a write-class verb (`write`/`edit`) on the SAME step** (`exit-illegal` — BREAKING for plan authors: a read-only "verify" step carrying a check used to validate and no longer does). A failing check's gap is re-delivered to that step's OWN worker, so a step holding a check must be able to act on it; a read-only one is a mailbox with no hands and stalls to cap on a byte-identical gap (measured on 4 of 4 drafted plans). The check belongs on the step that fixes; the run's final verification is the operator's close, which the agent never authors. The rule is stated identically in the drafter prompt and the validator, so the two can never disagree — and it is suppressed when `tools` failed to parse (the step's hands are unknowable then, and the real defect already redded: one defect, one red). `artifact-written.pattern` must compile AND survive a ReDoS shape check — an unbounded quantifier over a group that itself repeats unboundedly (`(a+)+`, `(\d*)*`, even wrapped: `((a+))+`) is an `invalid-value` red (F49, catastrophic-backtracking footgun; rewrite without a repeated group inside a repeat). Exits verify FORM, not truth — progress gates; the operator's close stays the one arbiter |
367
+ | `steps[].exit` | 1..2 items (`MAX_EXITS_PER_STEP`), ALL must pass (AND-only, no OR/NOT) | closed menu (`EXIT_TYPES`): `artifact-written(path, pattern?)` · `tree-changed(scope)` · `json-valid(path)` · `check-passes(name)`. **`tree-changed.scope` is a MENU, not a glob the agent authors** — the runner enumerates the signed fence entries plus the real directories beneath them (shallowest-first, capped at `MAX_SCOPE_MENU`=24; `legalScopes` in `src/plan.js`), `planPrompt` lists them verbatim, and `validatePlan` accepts membership only — the SAME array on both sides, so what was offered is what is accepted; omitted, it derives from `writeScope` alone — never a free-text fallback. `exit` is REQUIRED on every step: the planner prompt says so and shows one legal example (`EXIT_EXAMPLE`, `src/plan.js`), and the `missing-required` red carries the same example (F254). An off-menu value that escapes the fence still reds `scope-escape` (the ledger's attribution class), an in-fence unoffered value reds `invalid-value` carrying the menu. `runPlan` emits `scope-menu {offered, truncated, offerableCount?, cap?}` so a capped menu is never silently complete. `check-passes` must name a stage on the close's DERIVED menu (`check-unknown` red names the offered menu — no operator authors this list, it comes straight from `checkMenu(close)`); on a write-granted step it must be paired with `tree-changed` (`exit-illegal` — the seed tree is green, a lone check would pass untouched, F17/F46). **`check-passes` also requires a write-class verb (`write`/`edit`) on the SAME step** (`exit-illegal` — BREAKING for plan authors: a read-only "verify" step carrying a check used to validate and no longer does). A failing check's gap is re-delivered to that step's OWN worker, so a step holding a check must be able to act on it; a read-only one is a mailbox with no hands and stalls to cap on a byte-identical gap (measured on 4 of 4 drafted plans). The check belongs on the step that fixes; the run's final verification is the operator's close, which the agent never authors. The rule is stated identically in the drafter prompt and the validator, so the two can never disagree — and it is suppressed when `tools` failed to parse (the step's hands are unknowable then, and the real defect already redded: one defect, one red). `artifact-written.pattern` must compile AND survive a ReDoS shape check — an unbounded quantifier over a group that itself repeats unboundedly (`(a+)+`, `(\d*)*`, even wrapped: `((a+))+`) is an `invalid-value` red (F49, catastrophic-backtracking footgun; rewrite without a repeated group inside a repeat). Exits verify FORM, not truth — progress gates; the operator's close stays the one arbiter |
367
368
 
368
369
  **A step has exactly ONE check slot — plan for it.** The three exit rules above compose into
369
370
  a ceiling worth stating on its own, because it decides what a plan can enforce *during* a
@@ -644,6 +645,8 @@ plan with the first leg's spend carried as prior spend and `offerQuestions: fals
644
645
  plan's open questions) are a separate, unchanged mechanism: they are asked before drafting, about the plan; try-3 questions
645
646
  are asked after two failed drafts, about a job line.
646
647
 
648
+ **Handoff note (per job; hamr 2026-10-28, F253).** When a worker's ask ends, code records the files it READ (the allowed `shell_read` and `ctx_get` calls; scout, step and fix asks all feed it). The NEXT step or fix ask of the same run, a retry of the same step included, gets a note appended to its first user prompt under the fixed heading `== Files earlier workers in this run read (a map only; contents are not included; line ranges as ctx_recall prints them) ==`, one line per file: `- <path> (<N> lines): <symbol> <a>-<b>, ...`. Code writes it, never a model; it names files and carries no content. The symbol map is the LiteCtx index's named chunks, refreshed before the note is built when the worker holds a retrieval verb, and dropped for a plain line count when the index is missing (LiteCtx indexes git-tracked files only) or older than the file. The scout and the drafter are never handed a note. Capped at 8,000 characters (`HANDOFF_CAP`, src/handoff.js): the oldest paths go first with a `[trimmed: N older path(s)]` marker. The arbiter's books (`.smoke`, `.litectx`, the gate audit), `.git`, `.bareloop` and anything outside the job root are never named. The store lives in memory for one leg: a resumed leg starts empty, so its first ask gets no note and later ones do. Each note given is one report-only spine record `{type:'handoff-note', phase, iteration, chars, paths}` (a path COUNT, never a name; catalogue entry `handoff-note` under the spine records). Switch: the signed spec's optional boolean `handoffNote`, absent = on, `false` = off (no note, no record).
649
+
647
650
  **Thinking on (per job; hamr 2026-10-11).** The New job card has a "Thinking on" tick under Model, unticked by default, saved in the SIGNED job as the optional
648
651
  boolean `thinking` (absent = off; an old spec and any unticked job keep the hash they would have had; a ticked job's `jobSpecHash` and `workflowKey` differ). It
649
652
  covers DRAFTING (scout, confirm, author, revise, structure retries) AND the rubric JUDGE, and as the think-everywhere override it makes every WORKER call think too (below). A Reuse card does not
@@ -1362,7 +1365,7 @@ measured correctness point); and `validatePlan` reds `read-blind` on any step gr
1362
1365
  without `recall` and `get`. Where only the DIFF runs, nothing is capped (a first read delivers
1363
1366
  whole, whatever the size), an unchanged re-read re-delivers rather than pointing, and G1 does not
1364
1367
  exist — G1 is the cap's compensation, and an arm that caps nothing has nothing to compensate for.
1365
- The ledger is per worker, so it resets with every step. On the native (clipipe) surface a CAPPING
1368
+ The ledger is per `ask()`, not per worker: every `ask()` builds a fresh transcript, so the ledger resets at the start of each one (F252; a later attempt's re-read gets the bytes, never a pointer for bytes its model never saw), while an `askFrom` continuation keeps the same transcript and its ledger. The run-level MEMORY-CACHE counts do not reset. On the native (clipipe) surface a CAPPING
1366
1369
  arm replaces the CLI-display cap rather than stacking on it; a non-capping arm leaves that wrapper
1367
1370
  installed *inside* the shim, so native never loses its bound. Default-flip pending a paid contrast;
1368
1371
  see CHANGELOG for the replay numbers behind it.
@@ -2737,6 +2740,16 @@ unreferenced loose objects are left. Gitignored files inside the fence are seen
2737
2740
  changed nothing in scope emits nothing, and a failed capture emits `gitError` with empty lists: a record,
2738
2741
  never a verdict, and it never throws. No prompt carries it; the learnings cards read it ("What changed").
2739
2742
 
2743
+ #### `handoff-note` — a note handed to a worker ask (`src/handoff.js`, `src/planrun.js`)
2744
+
2745
+ One report-only spine record per handoff note given: `{type:'handoff-note', phase, iteration, chars, paths}`.
2746
+ `phase` is `step:<id>` or `fix`; `iteration` is the round iteration at the ask; `chars` is the note's length in
2747
+ characters (at most 8,000); `paths` is a COUNT of the files the note lists after any trimming, never a name.
2748
+ `runPlan` writes it right before the ask runs, once per step or close-fix ask that actually receives a note: an
2749
+ ask with nothing yet read gets no note and no record, and the scout and the drafter are never handed one. It
2750
+ carries no cost fields (not a spend record) and no verdict. The switch is the signed spec's optional boolean
2751
+ `handoffNote`: absent = on, `false` = off (no note, no record). The prose rules are under "Handoff note".
2752
+
2740
2753
  ### `replayRun(spineEvents, auditEvents?, { runId? })` / `formatReplay(summary)` / `summarizeForAllLine(summary)` / `formatAllLines(entries)` — `src/replay.js`
2741
2754
 
2742
2755
  `summarizeForAllLine(summary)` reduces one `replayRun` summary to one `--all`/directory-
@@ -3539,7 +3552,7 @@ key you want first (the panel picks the row by the Model menu).
3539
3552
  lowered from the original 2s per F195 — `listRuns()` re-replays every archived spine on
3540
3553
  every call, ~457ms CPU at 250 rows, open/escalated), except the tick right after the open
3541
3554
  run stops being live, which forces one immediate list refresh so that row's glyph doesn't
3542
- wait up to 10s. Both fetches skip re-rendering when the payload's JSON is byte-identical to
3555
+ wait up to 10s. The Runs list read is also the panel's heartbeat for the topbar online dot (see "Panel topbar"). Both fetches skip re-rendering when the payload's JSON is byte-identical to
3543
3556
  the last one, restore each pane's scroll position across a poll-driven rebuild, and pause
3544
3557
  while the tab is hidden (`document.hidden`), catching up immediately on
3545
3558
  `visibilitychange`. The Audit tab does **not** join this loop — it refetches only when
@@ -4449,7 +4462,7 @@ A **Rubric** job whose first Input is the full path of a FILE (not a repo folder
4449
4462
  - **Panel wording.** `stageQuestionText` words a rubric-step stage "line N — does its output pass the line's checks?". The worker brief also tells the worker to copy every number, time and price in a claim exactly as the input writes it ("9:27 AM", not "09:27").
4450
4463
  - **Shown == run (run mv5bk400).** The plan card after drafting is built from the signed close (`checksOfClose`, code-written sentences), not from the confirm turn's prose. A countable part may list the confirmed checks it carries out in `covers` (the composer prompt numbers them `#n`); `reconcileRubricPlan` moves every confirmed check no part covers to Not checked ("... — nothing in this close counts it or checks it against a quote"). `signRun` calls `planMatchesClose(session.state.finalPlan.checkItems, closeDecl)` and refuses, spawning nothing, when the two differ. `minClaims` / `maxClaims` (parts with `value` + `source`) count the claims listed under an input: `flattenStep` takes the count from the file's own `cites.<label>` list as the field `claims:<label>` and bareguard's `min`/`max` compares it. A free-text note is never a check.
4451
4464
  - **Labels.** A text close carries `genre: "TEXT"` (`genreForLang`; `TYPES` is for code languages, and a genre must match its language); its spine records carry no `judgedCount` (no judge ran); the progress list words a file job's steps from `FILE_JOB_STEP_LABELS` ("copying input files", "reading input files").
4452
- - **Panel topbar.** `bareloop · v<version> · automate a job, verified`: the version is bareloop's own package.json, read once when the panel starts and templated into the page when it is served (`__BARELOOP_PANEL_VERSION__`), so it is the version the process runs, not what package.json says now.
4465
+ - **Panel topbar.** `bareloop · v<version> · automate a job, verified`: the version is bareloop's own package.json, read once when the panel starts and templated into the page when it is served (`__BARELOOP_PANEL_VERSION__`), so it is the version the process runs, not what package.json says now. Right of the host line and left of Settings sits the online dot (`#online-dot`): the Runs list read (the 10 s poll, no new endpoint or timer) paints green `online` on any HTTP reply, even an error status or a 200 whose body will not parse, and red `offline` only when the read fails with no HTTP status (the panel process is gone); a page render error after a good read never paints it offline.
4453
4466
  - **After drafting, the code-worded card is the only plan on screen (run mv5e1ktb).** The confirm turn's plan bubble is the drafter's own prose (written before any close existed) and used to stay in the thread above the code-worded card; when the rubric card is ready the earlier `kind:'plan'` messages are dropped. `partSentence` now reads "1 line" / "1 word" for a count of one.
4454
4467
  - **Each `~` guardrail is its own row on the plan card.** `planFromSpec` / `planFromConfirm` lines carry `rules: string[]` (the line's own `rules`, else the joined `rule` split on "; "); `renderJobPlan` draws one `~ rule` row per rule under its numbered line, in the plan card and the Job tab alike (one renderer). Gutter numbers stay on job lines only.
4455
4468
  - **The review door's held line is true for a no-judge close.** Credit is held by VERDICT CLASS (`quarantinesCredit`: soft-green), whether or not a judge ran; the door now says "this is a rubric (soft-green) job, so its green earns NO reuse and NO learning credit until you accept it, whether or not a judge ran". Wording only; `bridges.js`/`reuse.js`/the Reuse refusal still say "rendered by the judged floor".
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "bareloop",
3
- "version": "0.50.0",
3
+ "version": "0.51.0",
4
4
  "description": "Workflows that earn their own design, with receipts — agent-authored workflows for repeated, long, verifiable jobs that improve across runs under an un-gameable gate.",
5
5
  "type": "module",
6
6
  "main": "./src/index.js",
package/src/authorflow.js CHANGED
@@ -1072,7 +1072,16 @@ THE PARSER reads ONE number out of a command's output, as signed arithmetic over
1072
1072
  region "whole-output", or {anchor, capture} to search only inside the part of the output the
1073
1073
  anchor locates. A region that cannot be located is a broken instrument.
1074
1074
  sign ${SIGNS.join(' | ')}. Subtraction is how you exclude things that were reported but did
1075
- not actually happen.`;
1075
+ not actually happen.
1076
+
1077
+ To count lines about one file or folder, keep lineMatch general (match the error line itself, e.g.
1078
+ "error TS\\d+") and put the file or folder in scope.includePrefixes. Never put a file path inside
1079
+ lineMatch or inside a region anchor: once that file is clean the command still fails on other files,
1080
+ nothing matches, and the check stops as a broken instrument instead of reading zero.
1081
+
1082
+ {"kind": "count-not-worse", "params": {"cmd": "npm", "args": ["run", "typecheck", "--", "--strict"],
1083
+ "parser": {"terms": [{"lineMatch": "error TS\\\\d+", "capture": null, "sign": 1, "aggregate": "sum", "region": "whole-output"}]},
1084
+ "scope": {"includePrefixes": ["src/target.js"]}, "direction": "lower-is-better", "baseline": 0}}`;
1076
1085
  }
1077
1086
 
1078
1087
  /**
package/src/handoff.js ADDED
@@ -0,0 +1,100 @@
1
+ // The handoff note (F253): a map of the files earlier workers in THIS run read, appended to the next step/fix
2
+ // worker's first prompt. Code-written only, never a model; names files, never carries their content.
3
+ // The switch is the signed spec's `handoffNote` (absent = on, only `false` turns it off; see src/job.js).
4
+ import { readFileSync, statSync } from 'node:fs';
5
+ import { isAbsolute, relative, resolve } from 'node:path';
6
+ import { isArbiterBook } from './kinds.js';
7
+
8
+ /** The one cap on a note, in characters. */
9
+ export const HANDOFF_CAP = 8000;
10
+ export const HANDOFF_HEADING = '== Files earlier workers in this run read (a map only; contents are not included; line ranges as ctx_recall prints them) ==';
11
+ /** Per-entry symbol-map cap, so one huge file cannot eat the whole note. */
12
+ const ENTRY_MAP_CAP = 500;
13
+
14
+ /**
15
+ * Is this repo-relative path off limits to a note: outside the job root, an arbiter book (the one list,
16
+ * `isArbiterBook`: .smoke — spine, attempt-diff, bridges — .litectx, the gate audit), or inside `.git` / `.bareloop`.
17
+ * @param {string} rel
18
+ */
19
+ export function isHandoffExcluded(rel) {
20
+ if (rel === '' || rel === '..' || rel.startsWith('../') || isAbsolute(rel)) return true;
21
+ if (isArbiterBook(rel) !== null) return true;
22
+ return rel.split('/').some((seg) => seg === '.git' || seg === '.bareloop');
23
+ }
24
+
25
+ /**
26
+ * Wrap the worker's read-class tools (the real names come from the caller: shell_read, ctx_get) so a call that
27
+ * reached `execute` (the gate already allowed it) and returned a file's text is reported to `onRead`.
28
+ * Wraps in place: tool objects are fresh per worker.
29
+ * @param {{name: string, execute: Function}[]} tools
30
+ * @param {string[]} names
31
+ * @param {(absPath: string) => void} onRead
32
+ * @param {string} workdir
33
+ */
34
+ export function trackReads(tools, names, onRead, workdir) {
35
+ for (const t of tools) {
36
+ if (!names.includes(t.name)) continue;
37
+ const inner = t.execute;
38
+ t.execute = async (/** @type {any} */ args) => {
39
+ const r = await inner(args);
40
+ if (typeof r === 'string' && typeof args?.path === 'string' && !/^ctx_get failed/.test(r)) {
41
+ const abs = isAbsolute(args.path) ? args.path : resolve(workdir, args.path);
42
+ try { if (statSync(abs).isFile()) onRead(abs); } catch { /* not a file: nothing was read */ }
43
+ }
44
+ return r;
45
+ };
46
+ }
47
+ }
48
+
49
+ /**
50
+ * Run-level store of the paths earlier workers read. Newest read last; a re-read moves a path to newest.
51
+ * In memory only: a resumed leg starts empty (the first ask of a resumed leg gets no note, later asks do).
52
+ * @param {{workdir: string}} o
53
+ */
54
+ export function createHandoffStore({ workdir }) {
55
+ /** @type {Set<string>} insertion order = oldest first */
56
+ const paths = new Set();
57
+ /** @param {Iterable<string>} absPaths */
58
+ const absorb = (absPaths) => {
59
+ for (const a of absPaths) {
60
+ const rel = relative(workdir, a).split('\\').join('/');
61
+ if (isHandoffExcluded(rel)) continue;
62
+ paths.delete(rel);
63
+ paths.add(rel);
64
+ }
65
+ };
66
+ /**
67
+ * @param {{getNode?: (rel: string) => any}} [o] `getNode`: the LiteCtx index's node for a path (its `chunks`)
68
+ * @returns {{text: string, paths: number}} text '' when nothing was read; else heading + body, length <= HANDOFF_CAP
69
+ */
70
+ const render = ({ getNode = () => null } = {}) => {
71
+ if (paths.size === 0) return { text: '', paths: 0 };
72
+ const lineCount = (/** @type {string} */ rel) => { try { return readFileSync(resolve(workdir, rel), 'utf8').split('\n').length; } catch { return null; } };
73
+ const entries = [...paths].map((rel) => {
74
+ const n = lineCount(rel);
75
+ let node = null;
76
+ try { node = getNode(rel); } catch { node = null; }
77
+ // Fresh index only: a node whose last chunk ends past the file's current end is stale — fall back to the count.
78
+ const named = (node?.chunks ?? []).filter((/** @type {any} */ c) => c.symbol);
79
+ const fresh = n !== null && named.every((/** @type {any} */ c) => c.endLine <= n);
80
+ let map = '';
81
+ let more = 0;
82
+ for (let i = 0; fresh && i < named.length; i++) {
83
+ const c = named[i];
84
+ const piece = `${c.symbol} ${c.startLine}-${c.endLine}`;
85
+ if ((map ? map.length + 2 : 0) + piece.length > ENTRY_MAP_CAP) { more = named.length - i; break; }
86
+ map += (map ? ', ' : '') + piece;
87
+ }
88
+ return `- ${rel}${n === null ? '' : ` (${n} lines)`}${map ? `: ${map}` : ''}${more ? `, +${more} more` : ''}`;
89
+ });
90
+ const wrap = (/** @type {string[]} */ es, /** @type {number} */ dropped) => `${HANDOFF_HEADING}\n${dropped ? `[trimmed: ${dropped} older path(s)]\n` : ''}${es.join('\n')}`;
91
+ let dropped = 0;
92
+ let out = wrap(entries, 0);
93
+ while (out.length > HANDOFF_CAP && dropped < entries.length) {
94
+ dropped++;
95
+ out = wrap(entries.slice(dropped), dropped);
96
+ }
97
+ return { text: out, paths: entries.length - dropped };
98
+ };
99
+ return { absorb, render, size: () => paths.size };
100
+ }
package/src/job.js CHANGED
@@ -170,7 +170,7 @@ export const CONDITION_KEYS = Object.freeze(['providerPath', 'closeVerbosity', '
170
170
  // `steps` stays in the field list ONLY so a retired spec reds by name
171
171
  // (`shape-retired`) instead of falling through to a generic unknown-field —
172
172
  // the operator gets told what happened, not just that something is wrong.
173
- const JOB_FIELDS = ['schema', 'job', 'description', 'provider', 'baseUrl', 'conditions', 'cadence', 'trigger', 'budgetUsd', 'maxWallMs', 'closeTimeoutMs', 'model', 'thinking', 'judge', 'writeScope', 'steps', 'escalation', 'goal', 'verdictType', 'close', 'closeDecl', 'checks', 'tools', 'jobLines', 'inputs'];
173
+ const JOB_FIELDS = ['schema', 'job', 'description', 'provider', 'baseUrl', 'conditions', 'cadence', 'trigger', 'budgetUsd', 'maxWallMs', 'closeTimeoutMs', 'model', 'thinking', 'handoffNote', 'judge', 'writeScope', 'steps', 'escalation', 'goal', 'verdictType', 'close', 'closeDecl', 'checks', 'tools', 'jobLines', 'inputs'];
174
174
  /** the exact fields of a signed `judge` override — nested objects red unknown
175
175
  * keys too, because no smuggling level exists in a signed spec */
176
176
  const JUDGE_FIELDS = ['provider', 'model'];
@@ -349,6 +349,11 @@ export function validateJob(input, { shellCapUsd = 2 } = {}) {
349
349
  if (spec.thinking !== undefined && typeof spec.thinking !== 'boolean') {
350
350
  red('invalid-value', 'thinking', 'true or false — the job\'s "Thinking on" tick (absent = off)');
351
351
  }
352
+ // THE HANDOFF NOTE (src/handoff.js): a declared job condition, signed like `thinking`. A boolean; ABSENT = on (an old spec keeps its
353
+ // bytes, so its hash), only an explicit `false` turns the note off. The switch is hashed; the note's text never is.
354
+ if (spec.handoffNote !== undefined && typeof spec.handoffNote !== 'boolean') {
355
+ red('invalid-value', 'handoffNote', 'true or false (absent = on): whether the next step/fix worker is handed a map of the files earlier workers read');
356
+ }
352
357
 
353
358
  // JUDGE — PRD item 32.1 (hamr, 2026-09-10: the judge "defaults to whatever
354
359
  // llm is used and can be overriden"). OPTIONAL, and the OVERRIDE half: absent,
@@ -118,6 +118,8 @@
118
118
  .topbar .version{flex:none;}
119
119
  @media (max-width: 600px){ .topbar .tagline{display:none;} }
120
120
  .topbar-right{display:flex;align-items:center;gap:10px;flex-wrap:wrap;}
121
+ #online-dot{font-size:12px;white-space:nowrap;flex:none;}
122
+ #online-dot.on{color:var(--green);} #online-dot.off{color:var(--red);}
121
123
 
122
124
  [hidden]{display:none !important;}
123
125
  .main{display:flex;flex:1;min-height:0;}
@@ -717,6 +719,7 @@
717
719
  </div>
718
720
  <div class="topbar-right">
719
721
  <span class="hint" id="host-line"></span>
722
+ <span id="online-dot" class="on" data-testid="online-dot" role="status">&#9679; online</span>
720
723
  <button class="btn small" type="button" id="btn-settings" data-testid="btn-settings">&#9881; Settings</button>
721
724
  <button class="theme-toggle" id="theme-toggle" type="button" aria-label="Toggle light/dark theme">&#9789;</button>
722
725
  </div>
@@ -1116,8 +1119,9 @@
1116
1119
  // ---- fetch helpers ----
1117
1120
  function getJSON(path){
1118
1121
  return fetch(path, { headers: { accept: "application/json" } }).then(function(r){
1119
- if(!r.ok) throw new Error(path + ": HTTP " + r.status);
1120
- return r.json();
1122
+ // `.status` marks "node answered": an HTTP error, or a 200 whose body would not parse — the online dot reads it (only a status-less failure is offline).
1123
+ if(!r.ok){ var err = new Error(path + ": HTTP " + r.status); err.status = r.status; throw err; }
1124
+ return r.json().catch(function(e){ e.status = r.status; throw e; });
1121
1125
  });
1122
1126
  }
1123
1127
 
@@ -4101,24 +4105,37 @@
4101
4105
  });
4102
4106
  }
4103
4107
 
4108
+ // The Runs list poll (every RUNS_LIST_POLL_MS) is the panel's heartbeat: ANY reply (even an HTTP error) = node answered = online; only a read that failed
4109
+ // with no HTTP status (the network, a dead panel) = offline. ONE painter writes the dot; the served page starts online.
4110
+ function paintOnline(isOnline){
4111
+ var el = document.getElementById("online-dot");
4112
+ el.className = isOnline ? "on" : "off";
4113
+ el.textContent = isOnline ? "\u25CF online" : "\u25CF offline";
4114
+ }
4115
+
4104
4116
  function refreshRunsList(force){
4105
4117
  var now = Date.now();
4106
4118
  if(!force && (now - lastRunsListRefreshAt) < RUNS_LIST_POLL_MS) return Promise.resolve();
4107
4119
  lastRunsListRefreshAt = now;
4108
4120
  return getJSON("/api/runs").then(function(result){
4109
4121
  pollFailStreak = 0;
4122
+ paintOnline(true);
4110
4123
  var runs = result.runs || [];
4111
4124
  var next = sig(result);
4112
4125
  if(next === lastRunsPayloadSig) return runs; // unchanged payload — never rebuild the DOM for nothing
4113
4126
  lastRunsPayloadSig = next;
4114
4127
  lastRunsSig = sig(runs);
4115
- withScrollPreserved(["left-pane-body"], function(){
4116
- // the painter re-runs the SAME filter/search state — a poll tick never resets it, and it writes a box only when its markup changed.
4117
- setRunsData(result);
4118
- runsFilterBar.refresh();
4119
- });
4128
+ // a render throw is a page bug, not the panel being down: log it here so it never reaches the status catch below (which would paint "offline")
4129
+ try {
4130
+ withScrollPreserved(["left-pane-body"], function(){
4131
+ // the painter re-runs the SAME filter/search state — a poll tick never resets it, and it writes a box only when its markup changed.
4132
+ setRunsData(result);
4133
+ runsFilterBar.refresh();
4134
+ });
4135
+ } catch(renderErr){ console.error("runs list render failed", renderErr); }
4120
4136
  return runs;
4121
- }).catch(function(){
4137
+ }).catch(function(err){
4138
+ paintOnline(!!(err && typeof err.status === "number"));
4122
4139
  pollFailStreak++;
4123
4140
  // Keep the last good render; a transient failure is invisible. Only a
4124
4141
  // PERSISTENT failure (3+ ticks, ~6s) gets a quiet, non-alarming note —
package/src/plan.js CHANGED
@@ -36,6 +36,10 @@ export const EXIT_TYPES = Object.freeze(['artifact-written', 'tree-changed', 'js
36
36
  /** decision 8: AND-only conjunction, bounded — no OR (a weak arm would
37
37
  * launder the exit), no NOT */
38
38
  export const MAX_EXITS_PER_STEP = 2;
39
+ /** a legal-example sentence for the exit menu — shown in the planner prompt and
40
+ * appended to the missing-required exit red, so a redraft sees a legal shape,
41
+ * not only the rule (F254: `exit` is required on EVERY step) */
42
+ export const EXIT_EXAMPLE = 'Legal exit examples: a step with no check uses [{"type":"artifact-written","path":"<its target>"},{"type":"tree-changed","scope":"<an offered scope>"}]; a step with a check uses [{"type":"tree-changed","scope":"<an offered scope>"},{"type":"check-passes","name":"<a check name>"}].';
39
43
  /** plan size bound — per-step rounds bound the spend, but an unbounded step
40
44
  * COUNT is still an unbounded claim on the wallet; same 8 as loop.maxIterations */
41
45
  export const MAX_PLAN_STEPS = 8;
@@ -519,7 +523,7 @@ export function validatePlan(input, { job, maxStepRounds = 40, scopes, seedRed,
519
523
  */
520
524
  function validateExit(s, at, red, { checkNames, fence, insideFence, writeStep, toolsParsed, scopeMenu, stepScope, overlapsStepScope, seedRedNames, isFinalWrite }) {
521
525
  if (!Array.isArray(s.exit) || s.exit.length === 0) {
522
- red('missing-required', `${at}.exit`, `non-empty array from the closed menu ${EXIT_TYPES.join('|')} — ALL listed exits must pass (AND-only); a step without an exit has no progress gate`);
526
+ red('missing-required', `${at}.exit`, `non-empty array from the closed menu ${EXIT_TYPES.join('|')} — ALL listed exits must pass (AND-only); a step without an exit has no progress gate — ${EXIT_EXAMPLE}`);
523
527
  return;
524
528
  }
525
529
  if (s.exit.length > MAX_EXITS_PER_STEP) {
package/src/planrun.js CHANGED
@@ -28,7 +28,7 @@ import { Gate } from 'bareguard';
28
28
  import { LiteCtx } from 'litectx';
29
29
  import { runClose, runStages, ralph, CLOSE_FAULTS, boundGap } from './ralph.js';
30
30
  import { validatePlan, legalScopes, closeStagesOf } from './plan.js';
31
- import { WRITE_VERBS, EXIT_TYPES, MAX_EXITS_PER_STEP, MAX_PLAN_STEPS, MAX_SCOPE_MENU, RETRIEVAL_PAIR } from './plan.js';
31
+ import { WRITE_VERBS, EXIT_TYPES, MAX_EXITS_PER_STEP, MAX_PLAN_STEPS, MAX_SCOPE_MENU, RETRIEVAL_PAIR, EXIT_EXAMPLE } from './plan.js';
32
32
  import { snapshotScope, evalExits, CHECK_GAP_MAX } from './exits.js';
33
33
  import { createRoot } from './root.js';
34
34
  import { createStallWatch, STALL_MS, MAX_STALLS } from './stall.js';
@@ -38,6 +38,7 @@ import { TOOL_MENU, STORE_VERBS, checkMenu } from './job.js';
38
38
  import { TOOL_BY_VERB, CTX_TOOLS, createCtxTools, toolAction, PERSONA_TOOLS, strategyFor } from './tools.js';
39
39
  import { anySuppressionWarning } from './authoring.js';
40
40
  import { createReadShim, readShimArm, readShimStrategy } from './readshim.js';
41
+ import { createHandoffStore, trackReads } from './handoff.js';
41
42
  import { globToPrefix, redactSecrets, SECRET_PATTERNS } from './validate.js';
42
43
  import { startAttemptDiff } from './attemptdiff.js';
43
44
  import { validateBridge, loadGate, newestEligibleVersion, reuseEligibility, quarantinesCredit, QUARANTINED_CODE } from './bridges.js';
@@ -699,7 +700,7 @@ strictly in array order. Each step (no other fields exist):
699
700
  inside it, and a "tree-changed" exit's scope must not be disjoint from it (one that
700
701
  CONTAINS it is fine) — otherwise every write the step could make is denied, or the
701
702
  exit can never pass, on every attempt.
702
- - "exit": 1..${MAX_EXITS_PER_STEP} form checks that ALL must pass (AND), each one of:
703
+ - "exit": REQUIRED on EVERY step — 1..${MAX_EXITS_PER_STEP} form checks that ALL must pass (AND), each one of:
703
704
  {"type":"artifact-written","path":"...","pattern":"optional regex"}
704
705
  {"type":"tree-changed","scope":"<copy one value from the offered scopes below>"}
705
706
  {"type":"json-valid","path":"..."}
@@ -708,6 +709,7 @@ strictly in array order. Each step (no other fields exist):
708
709
  it character for character. No other name exists, and you cannot add one.
709
710
  A check-passes on a write-granted step MUST be paired with a tree-changed exit
710
711
  (the repository starts green — a lone check would pass on the untouched tree).
712
+ ${EXIT_EXAMPLE}
711
713
  A check-passes may ONLY appear on a step whose tools include write or edit: a
712
714
  failing check is reported back to THAT step's worker for another attempt, so
713
715
  the step must be able to act on the report. Do not plan a separate read-only
@@ -1022,6 +1024,10 @@ export async function runPlan(job, { workdir, provider, nativeProvider, provider
1022
1024
  // would be wrong and would look fine). Only the guard runs here; the flag itself
1023
1025
  // is still threaded onward as written.
1024
1026
  readShimArm(readShim);
1027
+ // THE HANDOFF NOTE (src/handoff.js): the paths earlier asks of THIS run read. In memory only, so a resumed leg starts empty.
1028
+ // The switch is the signed spec's `handoffNote` (absent = on, only `false` turns it off).
1029
+ const handoffOn = job.handoffNote !== false;
1030
+ const handoff = createHandoffStore({ workdir });
1025
1031
  // The scout switch's guard, same class and same door: a mis-typed value
1026
1032
  // coerced by truthiness would run the scout under an "off" label (or skip it
1027
1033
  // under an "on" one) and no reading of the results afterwards could recover
@@ -2567,6 +2573,26 @@ export async function runPlan(job, { workdir, provider, nativeProvider, provider
2567
2573
  // below anything a second/minute-scale timer can perceive. Store output is byte-identical.
2568
2574
  if (ctx.length) await lc.index({ yield: true });
2569
2575
  const toolDefs = [...shell, ...ctx];
2576
+ // The handoff note: record what each ask READS (the allowed read-class calls), hand the next step/fix ask the map.
2577
+ // Scout and drafter asks feed the store but are never given a note.
2578
+ /** @type {Set<string>} */
2579
+ let askReads = new Set();
2580
+ if (handoffOn) trackReads(toolDefs, [TOOL_BY_VERB.read, TOOL_BY_VERB.get], (a) => askReads.add(a), workdir);
2581
+ /** @param {(prompt: string, defs?: any) => Promise<any>} inner */
2582
+ const withHandoff = (inner) => (!handoffOn ? inner : async (/** @type {string} */ prompt, /** @type {any} */ defs) => {
2583
+ askReads = new Set();
2584
+ let p = prompt;
2585
+ if (phase === 'fix' || phase.startsWith('step:')) {
2586
+ // The index is incremental: refreshing it here is what keeps the symbol ranges true to the files as they now are.
2587
+ try { if (ctx.length) await lc.index({ yield: true }); } catch { /* the map falls back to line counts */ }
2588
+ const note = handoff.render({ getNode: (rel) => lc.getNode(rel) });
2589
+ if (note.text) {
2590
+ p = `${prompt}\n\n${note.text}`;
2591
+ emit('handoff-note', { phase, iteration: roundIteration, chars: note.text.length, paths: note.paths });
2592
+ }
2593
+ }
2594
+ try { return await inner(p, defs); } finally { handoff.absorb(askReads); }
2595
+ });
2570
2596
  // F19 per VERB (P, corrected 2026-07-31): a strategy SENTENCE rides only with
2571
2597
  // the verb it names. Gating per COMPONENT was close but over-reached — a
2572
2598
  // worker granted only `impact` must not be steered to tools it lacks, and the
@@ -2633,6 +2659,7 @@ export async function runPlan(job, { workdir, provider, nativeProvider, provider
2633
2659
  const askFrom = async () => null;
2634
2660
  const ask = async (prompt, defs = toolDefs) => {
2635
2661
  let r;
2662
+ shim.reset(); // each ask() is a fresh session: the model holds nothing earlier asks were handed
2636
2663
  try {
2637
2664
  r = await loop.run([{ role: 'user', content: prompt }], defs, { maxTokens: 32000 });
2638
2665
  } catch (e) {
@@ -2663,7 +2690,7 @@ export async function runPlan(job, { workdir, provider, nativeProvider, provider
2663
2690
  }
2664
2691
  return r;
2665
2692
  };
2666
- return { ask, askFrom, workerWrites, writeCount, setIteration, wasBounded: () => attemptBounded };
2693
+ return { ask: withHandoff(ask), askFrom, workerWrites, writeCount, setIteration, wasBounded: () => attemptBounded };
2667
2694
  }
2668
2695
 
2669
2696
  // ── LOOP path: the injected provider (anthropic-api and every other
@@ -2862,6 +2889,10 @@ export async function runPlan(job, { workdir, provider, nativeProvider, provider
2862
2889
  };
2863
2890
  const ask = async (prompt, defs = toolDefs) => {
2864
2891
  let r;
2892
+ // A fresh Loop = a fresh transcript: the read shim's delivered-ledger resets with it, or a
2893
+ // later attempt's re-read is answered with a pointer to bytes its model never saw (F252).
2894
+ // askFrom (a continuation of a prior transcript) deliberately does NOT reset.
2895
+ shim.reset();
2865
2896
  const thinkOpts = thinkingForCall();
2866
2897
  try {
2867
2898
  r = await stallWatch.watch((gen) => newLoop(gen).run([{ role: 'user', content: prompt }], defs, { cacheMessages: true, maxTokens: 32000, ...callBounds(), ...thinkOpts }));
@@ -2933,7 +2964,7 @@ export async function runPlan(job, { workdir, provider, nativeProvider, provider
2933
2964
  }
2934
2965
  return r;
2935
2966
  };
2936
- return { ask, askFrom, workerWrites, writeCount, setIteration, wasBounded: () => attemptBounded };
2967
+ return { ask: withHandoff(ask), askFrom, workerWrites, writeCount, setIteration, wasBounded: () => attemptBounded };
2937
2968
  }
2938
2969
 
2939
2970
  /** relay a throw from OUTSIDE ralph (scout/plan drafting/fix) as its honest
package/src/readshim.js CHANGED
@@ -555,7 +555,23 @@ export function createReadShim({ cap = READ_SHIM_CAP, arm = ARM_ALL, onCount = n
555
555
  * the diff lever (L2) is a different response shape and is not counted here. */
556
556
  const summary = () => ({ pointered, capped, bytesWithheld });
557
557
 
558
- return { arm, cap, wrapRead, serveStale, summary };
558
+ /**
559
+ * A NEW ask() builds a fresh Loop with a fresh transcript — the model holds NONE of
560
+ * what earlier asks delivered — so the delivery ledger must forget with it. Left in
561
+ * place, attempt 2 re-reading a file attempt 1 fully received is answered "unchanged,
562
+ * you already hold all N bytes": untruthful, the one thing this module exists to
563
+ * prevent (FINDINGS F252). Over-delivery is the legal direction; a false pointer is not.
564
+ *
565
+ * It clears ONLY the ledger (what the model was handed). It does NOT touch the
566
+ * MEMORY-CACHE counters (`pointered`/`capped`/`bytesWithheld`, and the caller's run-level
567
+ * `onCount` sum): those are a record of bytes already withheld, not of what a model holds,
568
+ * and zeroing them would erase real savings from the readout. `serveStale` holds no ledger.
569
+ * Not called for a continuation (`askFrom` re-runs the SAME transcript — the model still
570
+ * holds everything, so its ledger stays true).
571
+ */
572
+ const reset = () => { ledger.clear(); };
573
+
574
+ return { arm, cap, wrapRead, serveStale, summary, reset };
559
575
  }
560
576
 
561
577
  /**
package/src/stagewords.js CHANGED
@@ -38,8 +38,13 @@ export function cmdKey(params) {
38
38
  * - `pattern-absent-in-diff` is always the `no-suppressions` guard: "no
39
39
  * casts or silencers added?"
40
40
  * - `rubric-step` (Part 1a) is one job line's output file: "line N — does its output pass the line's checks?"
41
- * - `command-exit` is the genre's `suite-green` stage (the only shipped use
42
- * of this kind): "does the test suite pass?"
41
+ * - `command-exit` quotes its OWN signed command verbatim:
42
+ * `does "<cmd> <args joined by space>" exit clean?` (e.g. `does "npm test"
43
+ * exit clean?`, `does "npx tsc --noEmit --strict" exit clean?`). It used
44
+ * to read "does the test suite pass?" for every command, so F256's run
45
+ * mvtatlxw showed two different commands (the real suite and a whole-repo
46
+ * `tsc --strict`) reading the same question. A missing or non-string
47
+ * `cmd` returns `null` (the caller falls back to the stage name).
43
48
  * - `count-not-worse` splits three ways on its own declared
44
49
  * `direction`/`baseline` (never the runtime number — see
45
50
  * {@link stageKindMetaFromSpec}'s own doc for why the baseline KIND must
@@ -87,7 +92,11 @@ export function stageQuestionText({
87
92
  }) {
88
93
  if (kind === 'files-changed') return 'did it change any file?';
89
94
  if (kind === 'pattern-absent-in-diff') return 'no casts or silencers added?';
90
- if (kind === 'command-exit') return 'does the test suite pass?';
95
+ if (kind === 'command-exit') {
96
+ if (!params || typeof params.cmd !== 'string' || params.cmd.length === 0) return null;
97
+ const args = Array.isArray(params.args) ? params.args.filter((a) => typeof a === 'string') : [];
98
+ return `does "${[params.cmd, ...args].join(' ')}" exit clean?`;
99
+ }
91
100
  // Part 1a: one rubric-step stage = one job line's output file
92
101
  if (kind === 'rubric-step') return params && Number.isInteger(params.step) ? `line ${params.step} — does its output pass the line's checks?` : null;
93
102
  if (kind !== 'count-not-worse' || !params || typeof params !== 'object') return null;
@@ -0,0 +1,39 @@
1
+ /**
2
+ * Is this repo-relative path off limits to a note: outside the job root, an arbiter book (the one list,
3
+ * `isArbiterBook`: .smoke — spine, attempt-diff, bridges — .litectx, the gate audit), or inside `.git` / `.bareloop`.
4
+ * @param {string} rel
5
+ */
6
+ export function isHandoffExcluded(rel: string): boolean;
7
+ /**
8
+ * Wrap the worker's read-class tools (the real names come from the caller: shell_read, ctx_get) so a call that
9
+ * reached `execute` (the gate already allowed it) and returned a file's text is reported to `onRead`.
10
+ * Wraps in place: tool objects are fresh per worker.
11
+ * @param {{name: string, execute: Function}[]} tools
12
+ * @param {string[]} names
13
+ * @param {(absPath: string) => void} onRead
14
+ * @param {string} workdir
15
+ */
16
+ export function trackReads(tools: {
17
+ name: string;
18
+ execute: Function;
19
+ }[], names: string[], onRead: (absPath: string) => void, workdir: string): void;
20
+ /**
21
+ * Run-level store of the paths earlier workers read. Newest read last; a re-read moves a path to newest.
22
+ * In memory only: a resumed leg starts empty (the first ask of a resumed leg gets no note, later asks do).
23
+ * @param {{workdir: string}} o
24
+ */
25
+ export function createHandoffStore({ workdir }: {
26
+ workdir: string;
27
+ }): {
28
+ absorb: (absPaths: Iterable<string>) => void;
29
+ render: ({ getNode }?: {
30
+ getNode?: (rel: string) => any;
31
+ }) => {
32
+ text: string;
33
+ paths: number;
34
+ };
35
+ size: () => number;
36
+ };
37
+ /** The one cap on a note, in characters. */
38
+ export const HANDOFF_CAP: 8000;
39
+ export const HANDOFF_HEADING: "== Files earlier workers in this run read (a map only; contents are not included; line ranges as ctx_recall prints them) ==";
package/types/plan.d.ts CHANGED
@@ -123,6 +123,10 @@ export const EXIT_TYPES: readonly string[];
123
123
  /** decision 8: AND-only conjunction, bounded — no OR (a weak arm would
124
124
  * launder the exit), no NOT */
125
125
  export const MAX_EXITS_PER_STEP: 2;
126
+ /** a legal-example sentence for the exit menu — shown in the planner prompt and
127
+ * appended to the missing-required exit red, so a redraft sees a legal shape,
128
+ * not only the rule (F254: `exit` is required on EVERY step) */
129
+ export const EXIT_EXAMPLE: "Legal exit examples: a step with no check uses [{\"type\":\"artifact-written\",\"path\":\"<its target>\"},{\"type\":\"tree-changed\",\"scope\":\"<an offered scope>\"}]; a step with a check uses [{\"type\":\"tree-changed\",\"scope\":\"<an offered scope>\"},{\"type\":\"check-passes\",\"name\":\"<a check name>\"}].";
126
130
  /** plan size bound — per-step rounds bound the spend, but an unbounded step
127
131
  * COUNT is still an unbounded claim on the wallet; same 8 as loop.maxIterations */
128
132
  export const MAX_PLAN_STEPS: 8;
@@ -67,6 +67,7 @@ export function createReadShim({ cap, arm, onCount }?: {
67
67
  capped: number;
68
68
  bytesWithheld: number;
69
69
  };
70
+ reset: () => void;
70
71
  };
71
72
  /**
72
73
  * The one-tool spelling, kept for every caller written before the shim became an
@@ -26,8 +26,13 @@ export function cmdKey(params: any): string | null;
26
26
  * - `pattern-absent-in-diff` is always the `no-suppressions` guard: "no
27
27
  * casts or silencers added?"
28
28
  * - `rubric-step` (Part 1a) is one job line's output file: "line N — does its output pass the line's checks?"
29
- * - `command-exit` is the genre's `suite-green` stage (the only shipped use
30
- * of this kind): "does the test suite pass?"
29
+ * - `command-exit` quotes its OWN signed command verbatim:
30
+ * `does "<cmd> <args joined by space>" exit clean?` (e.g. `does "npm test"
31
+ * exit clean?`, `does "npx tsc --noEmit --strict" exit clean?`). It used
32
+ * to read "does the test suite pass?" for every command, so F256's run
33
+ * mvtatlxw showed two different commands (the real suite and a whole-repo
34
+ * `tsc --strict`) reading the same question. A missing or non-string
35
+ * `cmd` returns `null` (the caller falls back to the stage name).
31
36
  * - `count-not-worse` splits three ways on its own declared
32
37
  * `direction`/`baseline` (never the runtime number — see
33
38
  * {@link stageKindMetaFromSpec}'s own doc for why the baseline KIND must