bareloop 0.47.1 → 0.48.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,41 @@ 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.48.0] - 2026-10-25
9
+
10
+ ### Added
11
+
12
+ - **`bareloop restart`, and the panel's start time.** `restart` (menu item 3) is the existing stop (same open-drafts warning and ask; `--yes` skips it) then the existing start, on the port the panel had when it is free again, else the first free one; with no panel running it says so and just starts. `GET /api/whoami` now carries `startedAt`, and the header reads `panel running at http://127.0.0.1:4700 · started 10/24 21:40` (local time, the panel's own date style); `bareloop status` prints it too. An older panel that reports none shows nothing extra.
13
+ - **Export a green panel run by its name (hamr's ruling, 2026-10-25).** `bareloop export "my-job (run-3)" --out ./folder` turns a green run from the panel into a bundle: the run's own signed job, plus a record of the run built from what the run itself recorded (cost, time, rounds, saved plan). With no name it lists your green runs, numbered, and you pick one. A number it cannot read from the run is refused in words, never guessed. For now only repo jobs: a judged job, a page-link job and a plain-folder job are refused with "only repo jobs can be exported for now" and the reason. Each export adds one `exported` line to `runs.jsonl`, so `bareloop run "my-job (run-3)"` finds the bundle by name. The older `export <job.json> --registry <dir> --out <dir>` is unchanged. The panel's Run tab for a green repo run now shows the export command to copy beside the `git merge` text.
14
+ - **One menu.** Bare `bareloop` shows `panel: 1 start 2 stop 3 restart 4 status 5 install` and `jobs: 6 export 7 run 8 resume 9 history`. Each job command asks for what it needs (typed flags skip the question): export a numbered list then a folder; run a bundle (number, name or folder), a repo, then the money and time caps; resume a numbered list of stopped runs, then more money or time; history a bundle. An empty Enter on a required question asks once more; a second empty Enter ends that command with a plain line (exit 0).
15
+ - **A cap can be raised with your yes.** `bareloop run` and `run --resume` used to refuse a cap above the bundle's signed one (`envelope-widen`). They now show it back ("This raises the $ cap from $2 to $10.") and proceed only when you type `yes`; with no terminal it needs `--yes`, else it is refused before anything runs. The approval (who, old, new, when) is written to `runs/<runid>/approvals.jsonl` in the bundle and the history row. A resume still folds what the run already spent. Lowering a cap needs nothing.
16
+
17
+ ### Changed
18
+
19
+ - **The Run tab's NEXT is one instruction per row.** A green repo run reads `in:` the repo, `keep the work:` `git merge …`, `throw it away:` `git branch -D …`, `reusable bundle:` `bareloop export "job (run-N)" --out <folder>` in two columns (muted labels), so a long command wraps under the command column. The two-step endings use the same shape with the panel's own names: `raise the cap:` Cap $ on the Chat card, `then:` press Resume; `raise the time:` Time cap (min) …; `resume:` press Resume, `or change the job:` press Reuse workflow; `fix the destination:` the Destination, `then:` press Reuse workflow. Single-instruction endings stay one line.
20
+ - **`bareloop run` commits a green.** The bundle runner left a green run's work uncommitted on its branch; it now commits it on the work branch (the same call the panel uses) and prints a `commit` line. The merge stays yours.
21
+ - **The first run of an unblessed bundle, typed at a terminal, is signed with a typed yes.** It shows the bundle hash and asks "Type yes to sign it:"; only `yes` proceeds, and the signing is written to the run's `approvals.jsonl`. With flags only, `--approve <hash>` is still how.
22
+ - **Export lists only runs it can take.** A run that was already green (no saved plan), a judged, page-link or folder job, or one with no signed job file is not listed; a number it cannot read is still refused at export, in words.
23
+ - **No line tells you to run `bareloop author` or `bareloop interview` any more** (they left the CLI). Messages name the panel's drafting or `scripts/run-author.mjs` / `scripts/run-interview.mjs`.
24
+ - **The bundle questions show what they ask about.** `history` and `run` list the last 10 bundles you know (exported ones plus any with `bareloop run` runs), newest first, numbered, each as run name + folder, then ask; older ones are reached by typing their run name or folder. `resume` lists the last 10 stopped runs the same way (older by run id or folder). With nothing to pick from they say so in one line ("No exported bundles yet. Export one with 6.") and end.
25
+ - **`q` leaves a job command.** Typing `q` (any case) at any job question (the number, bundle, folder, repo, model, `$` cap, time cap and the yes-to-sign questions of export, run, resume and history) ends that command with a plain "nothing chosen" line and exit 0, like a second empty Enter. It used to be taken as a bundle name or a wrong answer. A folder literally called `q` is still reachable as `./q`.
26
+ - **`bareloop run` asks for what is missing.** No bundle, repo or model typed: it asks (the model from the ones ticked in Settings, only when the bundle names none). A bundle can be named by the run name it was exported under.
27
+ - **`interview`, `author` and `runs backfill` are no longer commands; `replay` is `node scripts/run-replay.mjs`.** `run-u` still works by name (the panel starts runs with it) but is listed nowhere. `scripts/run-interview.mjs` and `scripts/run-author.mjs` are unchanged, and the interview's "run it now" offer starts the author script. The library functions the panel uses stay.
28
+ - **A bundle's money-halt hint no longer says the ceiling cannot be raised.** The resume line reads `--budget <more than $X, above $Y asks you to type yes>`.
29
+ - **`learningHints` is ON by default (hamr's ruling, 2026-10-24).** It shipped OFF behind a `config.json` setting; an absent setting now means ON, so the planner is handed cross-run learnings at the draft and first replan. `"learningHints": false` still turns it off; an unreadable config still reads OFF. The one owner is `learningHintsOn` in `src/learnstore.js`.
30
+
31
+ - **One record of a session's drafting spend, not two.** Each metered drafting call already wrote a `call` line to `draft-log.jsonl` AND rewrote `draft-spend.json` with the running total. The `call` line now also carries the drafting `provider` and `baseUrl`, `draft-spend.json` is no longer written, and the monthly limit and Money tab fold the log's call lines (same `tallyCalls` reader as the session) for a session that never became a run. A session folder left by the old shape (the file, no call lines) is still read from the file, so old money is not lost; a torn log line makes the figure an "at least". Call lines written before they carried the drafting identity take provider, baseUrl and model from the old file, so old drafting spend stays on its Money row.
32
+ - **One `run.log` per run folder.** Accept, Rerun, Pause and Resume each made a new `accept-<id>-<ms>.log` / `resume-<id>-<ms>.log` file; they now append to the folder's `run.log` (the one the first run already writes) under a header line `== <action> <runid> at <time> ==`. A refusal shows only its own action's lines. The `log` field in the reply is now that path. Folders that already hold the old per-action files are left as they are.
33
+ - **`bareloop start` on a silent taken port tells you how to find what holds it.** The stop line now reads "Port N is taken and not answering. To see what holds it: lsof -i :N. If it is a stuck bareloop, end it: kill <pid>" (the old advice, "stop it first", could not be followed: `bareloop stop` only finds a panel that answers).
34
+
35
+ ### Fixed
36
+
37
+ - **`bareloop run --yes <bundle>` keeps the bundle, and a pipe is never asked a question.** `--yes` took the next word as its value, so the bundle vanished and the command asked "which bundle?", found none, and exited 0 with nothing run. `--yes` is now a plain switch. And when `bareloop` is run with input that is not a terminal (`</dev/null`, a pipe) and a required word is missing, you get the usage line and exit 1 instead of a question. The menu still reads its choices from a pipe (`echo q | bareloop`).
38
+ - **The Run tab offers "reusable bundle:" only for a run export will take, and the command pastes into a shell.** The row was shown for a run that was already green (no saved plan) and for judged repo jobs, which export then refuses; it now uses the same check export uses. The command ends `--out "./<job>-bundle"` (a real folder name you may change) instead of `--out <folder>`, which a shell reads as a redirect.
39
+ - **A broken learnings file is no longer the same as "no lessons yet" (hamr's ruling, 2026-10-24, copied from fwdloop).** An unreadable or wrong-version ledger made the planner's hint block silently empty and recorded nothing. The planner still gets nothing and the run still goes on, but the run's `learnings` spine record now carries `hintsError` (first line, secrets masked), and the Audit learnings box prints one plain line: "The learnings file could not be read, so no lessons were given: ..." with a red ✗ header mark instead of the green ✓ (✓ stays when lessons were handed). In the ✗ case the title reads "No lessons were given to the planner", and the shown line writes the home folder as `~` (the spine record keeps the full reason). Hints off still reads nothing and records nothing.
40
+
41
+ - **Lessons follow the workflow, not the signed hash (hamr's ruling, 2026-10-24).** Learnings decided "same job version" by the signed hash, which moves with the money cap, time cap, source, destination, inputs and model. A Reuse with a new cap therefore read none of the earlier lessons, and a Resume that raised the cap counted one run twice (a second ledger row). The version is now the workflow key (the rule Reuse already uses). Rows and holds carry a new `workflowKey` beside `specHash`; rows an older version wrote have none and still match any version. Signing, approvals and bridges are unchanged.
42
+
8
43
  ## [0.47.1] - 2026-10-24
9
44
 
10
45
  ### Fixed
package/README.md CHANGED
@@ -129,18 +129,21 @@ Find it once, keep it, reuse it. It is a seed of something bigger over time.
129
129
 
130
130
  ### Export a job
131
131
 
132
+ When a job in the panel has gone green, keep it as a bundle you can run anywhere:
133
+
132
134
  ```bash
133
- bareloop export jobs/my-maintainer.json --registry ./bridges --out ./my-maintainer.bareloop
134
- bareloop run ./my-maintainer.bareloop --repo /path/to/checkout --approve <bundleHash printed above>
135
+ bareloop export "my-job (run-3)" --out ./my-job.bareloop # or just `bareloop export` and pick from the list
136
+ cd ./my-job.bareloop && npm install
137
+ bareloop run "my-job (run-3)" --repo /path/to/checkout --approve <bundleHash printed above>
135
138
  ```
136
139
 
137
- `export` only ships a job that has already earned a real green — it refuses to bundle an
138
- unproven draft. The first `run` on a new machine asks you to approve the bundle's printed
139
- hash; once that run goes green, later runs need no re-approval as long as the bundle stays
140
- unchanged. Every run works in its own fresh git worktree and leaves the merge to you. `bareloop
141
- run` is a door to the same engine as `bareloop run-u`, so it uses any provider your keys file
142
- has, honours the monthly limit, and a halted run can be continued with
143
- `bareloop run <bundle> --resume <runid>`. Full
140
+ Bare `bareloop` is one menu: the panel (1 start, 2 stop, 3 restart, 4 status, 5 install) and the jobs
141
+ (6 export, 7 run, 8 resume, 9 history), each asking for what it needs. `export` only ships a run that
142
+ already earned a real green, and only repo jobs for now. The first `run` on a new machine asks you to
143
+ approve the bundle's printed hash; once that run goes green, later runs need no re-approval as long
144
+ as the bundle stays unchanged. Every run works in its own fresh git worktree, commits a green on its
145
+ own branch and leaves the merge to you. A cap above the one signed is shown back and needs your
146
+ typed `yes` (or `--yes`). A halted run continues with `bareloop run <bundle> --resume <runid>`. Full
144
147
  contract — flags, approval/blessing rules, exit codes — in
145
148
  [`bareloop.context.md`](bareloop.context.md).
146
149
 
@@ -1247,7 +1247,7 @@ must never make an ordinary first run read as a resume. Belted like `priorSpentU
1247
1247
  non-finite or negative value reads as 0). Rides onto `job-start` as its own field,
1248
1248
  `draftSpentUsd`, only when > 0 — never inside `spentUsd`/`engagementSpentUsd`, which stay
1249
1249
  run-only. `bareloop run-u --draft-spent-usd <n>` is the CLI door (validated: finite, ≥ 0, else
1250
- refused); `bareloop author` prints its own known drafting spend floor and the exact `run-u`
1250
+ refused); `scripts/run-author.mjs` prints its own known drafting spend floor and the exact `run-u`
1251
1251
  command including the flag; the panel's sign route passes the session's own tracked drafting
1252
1252
  spend the same way. `src/replay.js`'s `moneyWithDraft(spendCore, draftSpentUsd, budgetUsd?, draftSpendComplete?)` is
1253
1253
  the one shared display formatter: `"$3.71 ($0.81 drafting) of $5.00"`, unchanged
@@ -1391,7 +1391,7 @@ never greens with no registry row (F207).
1391
1391
  has no guard against being passed without `--draft-spent-usd` — alone it is inert (nothing is
1392
1392
  folded, so no `job-start` field is emitted). Every printed re-invocation tail carries it
1393
1393
  alongside `--draft-spent-usd` (only when drafting spend > 0), so a resumed leg never turns the
1394
- floor back into an exact figure; `bareloop author` and the panel's sign route pass it when the
1394
+ floor back into an exact figure; `scripts/run-author.mjs` and the panel's sign route pass it when the
1395
1395
  session's drafting spend was incomplete.
1396
1396
 
1397
1397
  **`bareloop run-u --draft-spent-usd <n>`** (hamr's ruling 2026-09-28, "one cap covers drafting +
@@ -1401,7 +1401,7 @@ enforced ceiling and reading it as `Infinity` would silently narrow it into "no
1401
1401
  names no drafting spend, so the signed `budgetUsd` is unaffected; this only shrinks THIS leg's
1402
1402
  own enforced remainder (`job.budgetUsd - draftSpentUsd - spentUsd`). Every printed
1403
1403
  resume/decide/door re-invocation carries `--draft-spent-usd` too, mirroring `--read-shim`'s own
1404
- tail — a resumed leg that dropped it would silently widen its ceiling back up. `bareloop author`
1404
+ tail — a resumed leg that dropped it would silently widen its ceiling back up. `scripts/run-author.mjs`
1405
1405
  prints the exact `run-u` command including this flag, with its own known drafting spend (a floor,
1406
1406
  never $0 on an unpriced call — F6). The panel's sign route (`src/panel/authorroutes.js`)
1407
1407
  passes the same flag off the authoring session's own tracked spend.
@@ -3238,6 +3238,7 @@ hash and needs re-approval, exactly like any other semantic edit.
3238
3238
  | `readBundle(dir)` | `dir` → `{ ok, reds, spec, manifest, bridges, blessing, history }` | never throws; every failure is a typed red. Runs the tamper check (below) whenever both a manifest and a spec parsed |
3239
3239
  | `resolveBundleSpec(bundle, bundleDir)` | a `readBundle` result + the bundle dir → `{ spec, approveHash }` | the in-memory `$BARELOOP_BUNDLE` → absolute `bundleDir` substitution; `approveHash` is `jobSpecHash` of the *substituted* spec, never the unresolved one |
3240
3240
  | `checkEnvelope(spec, envelope)` | `spec` (already resolved) + `{ budgetUsd?, maxWallMs? }` → `{ ok, reds }` | tighten-only: a given number must be ≤ the spec's own |
3241
+ | `capRaises(spec, envelope)` | `spec` + `{ budgetUsd?, maxWallMs? }` → `[{ field, old, new }]` | the caps an envelope would RAISE above the signed ones; `bareloop run` shows each and needs a typed `yes` / `--yes` (pure) |
3241
3242
  | `bless(dir, record)` | `dir` + `{ bundleHash, runid, outcome, host?, blessedAt? }` → the blessing object | writes/overwrites `blessing.json`; there is only ever one, for the bundle's current hash |
3242
3243
  | `verifyBlessing(bundle)` | a `readBundle` result → `{ ok, unblessed, reds }` | `unblessed: true` (no red) means never blessed here; a red means blessed-but-stale |
3243
3244
  | `appendHistory(dir, row)` | `dir` + a plain object → `void` | atomic append to `history.jsonl` (`appendFileSync`, same convention as `spine.js`/`ledger.js`) |
@@ -3265,7 +3266,7 @@ hash and needs re-approval, exactly like any other semantic edit.
3265
3266
  | `manifest-invalid` / `spec-invalid` | `readBundle` | `manifest.json`/`spec.json` could not be read or parsed |
3266
3267
  | `bundle-tampered` | `readBundle` | manifest and spec both parsed, but the recomputed `bundleHash` (from what's really on disk) does not match the stored one — **the load-bearing check, N4 below** |
3267
3268
  | `bundle-deps-missing` | `checkBundleDeps` (F128) | the bundle's own `close/` directory cannot resolve `require.resolve('bareloop')` — the bundle was installed the WRONG way (as someone else's dependency) instead of `cd <bundleDir> && npm install`. `bareloop run` calls this as literal step 1b, right after the tamper check, before the envelope check, the key, and any worktree |
3268
- | `envelope-widen` | `checkEnvelope` | a given `budgetUsd`/`maxWallMs` exceeds the bundle's own signed ceiling — raising one is a re-export, never a runner flag |
3269
+ | `envelope-widen` | `checkEnvelope` | a given `budgetUsd`/`maxWallMs` exceeds the bundle's own signed ceiling and no yes was given (`bareloop run` offers the raise first: type `yes`, or pass `--yes`) |
3269
3270
  | `blessing-stale` | `verifyBlessing` | `blessing.json` exists but its `bundleHash` no longer matches the manifest's — the bundle was re-exported/edited since the run that blessed it; re-export and re-approve |
3270
3271
 
3271
3272
  **N4 — why `readBundle`'s tamper check must run before anything else touches the bundle.**
@@ -3292,8 +3293,8 @@ same seam `tests/planrun-*.test.js` uses. `deps` also accepts `env`, `stdout`, `
3292
3293
  `now`, `stdin` — omit any of them and the real `process.*` equivalent is used.
3293
3294
 
3294
3295
  Bare `bareloop` (no sub-command) is the **launcher menu** (PANEL-BUILD.md addendum L, `src/launcher.js`): two header lines, then
3295
- `1 start 2 stop 3 status 4 install q quit`. The header is printed first by EVERY call (menu and each of
3296
- `bareloop start | stop | status | install`), from one function:
3296
+ `panel: 1 start 2 stop 3 restart 4 status 5 install`, `jobs: 6 export 7 run 8 resume 9 history`, `q quit`. The header is printed first by EVERY call (menu and each of
3297
+ `bareloop start | stop | restart | status | install`), from one function:
3297
3298
 
3298
3299
  ```
3299
3300
  bareloop 0.47.0 · installed ✓ · panel running at http://127.0.0.1:4701
@@ -3304,7 +3305,7 @@ Colour (`src/tty-colour.js`): on only when stdout is a terminal, `NO_COLOR` is e
3304
3305
  changes them, and a piped or `NO_COLOR` run prints the plain words above (the thin `─` rules around the header appear only with colour).
3305
3306
 
3306
3307
  - `installed ✓` = `~/.config/bareloop/` exists, `config.json` is there and reads with no problem, `.env` exists with mode 600, node >= 22;
3307
- otherwise `not installed — <first missing thing>, pick 4 install`. The run counts use the panel's own status words and Needs-you rule over the
3308
+ otherwise `not installed — <first missing thing>, pick 5 install`. The run counts use the panel's own status words and Needs-you rule over the
3308
3309
  run list file ($0, works with the panel stopped).
3309
3310
  - **No pid file.** The panel is found by asking `127.0.0.1:4700..4709` for `GET /api/whoami` (2000 ms each, in parallel — a loaded panel answered in 0.8 s; 300 ms missed it); a reply with `app: "bareloop"` is a panel. `start` never opens a second panel next to a silent one: a port that is taken but did not answer is asked again for about 10 s; a late bareloop answer counts as "already running", another kind of reply moves on to the next port, and still silent makes `start` stop with `Port 4700 is taken and not answering. If it's a stuck bareloop, stop it first.` (exit 1, nothing started). `stop` also checks each pid is really gone (signal 0) before it says "Panel stopped."; a pid still alive at the deadline is named (`did not stop`, exit 1) and the ones that did stop are still named.
3310
3311
  `GET /api/whoami` → `{ app: "bareloop", version, pid, port, drafts, schedules }` (`version` is the version the panel STARTED with, read once at start, never re-read from package.json — so a panel on old code after a bump still reports the old one and the launcher's stop-and-start note can fire; the page topbar is the same) (open drafting sessions, jobs with a schedule), read-only, same Host guard as every
@@ -3312,26 +3313,44 @@ changes them, and a piped or `NO_COLOR` run prints the plain words above (the th
3312
3313
  - **`bareloop start`** → already running: says so, opens the page, starts nothing (if the running panel's version differs from this bareloop's it adds `It is version X; this bareloop is Y. Run bareloop stop, then bareloop start, to use Y.`). Else starts `bareloop panel --port N` DETACHED (`setsid`; log appended to
3313
3314
  `~/.config/bareloop/panel.log`) on the first free port from 4700 (a taken port that replies as something else is skipped and named; one that stays silent for ~10 s stops `start` with `Port N is taken and not answering…`, nothing started), waits up to 10 s for it to answer, opens the page with
3314
3315
  `xdg-open`/`open` (no opener: prints the URL). `bareloop panel [--port N]` is unchanged (foreground, fixed port).
3316
+ - **`bareloop restart [--yes]`** (menu 3) → no panel running: `Panel not running — starting it.` and starts. Else the `stop` above (same open-drafts warning and y/N; `--yes` skips it), and only if the panel is really gone (a declined stop starts nothing) the `start` above, trying the port the panel had first (free again) and then the normal first-free-port rule. No new process model, no pid file. `GET /api/whoami` also carries `startedAt` (ISO, set once when the panel process starts); the header shows ` · started MM/DD HH:MM` (local, `dateTimeWords`) after the address and `status` ends its line with it; an older panel without it shows nothing extra.
3315
3317
  - **`bareloop stop [--yes]`** → SIGTERM to the pid of EVERY panel the probe finds (one panel at a time; no which-one question), waits until each pid is gone (signal 0) and each port is quiet; a pid still alive at the 10 s deadline is named and exits 1, never `Panel stopped.`. Open drafts (in memory, summed over all found panels) are warned about and a y/N is asked;
3316
3318
  `--yes` skips it. Not running: `Panel not running.`, exit 0. Several found: all stopped, `N panels stopped.`. Any other option (e.g. `--port`) is refused in plain words. Runs are separate processes and keep going.
3317
3319
  - **`bareloop status`** → header plus `pid N · version X · N draft(s) open · N schedule(s) on`. Exit 0 running, 3 not running. A panel whose version differs from the CLI's shows `(version X — stop and start to use Y)` after its URL in the header (yellow on a terminal).
3318
3320
  - **`bareloop install`** → creates only what is missing (folder mode 700, `.env` with the keys-file comment lines, mode 600, `config.json`); never reads a key value;
3319
3321
  `Already installed, nothing to do.` when there is nothing to add. Needs node >= 22.
3320
3322
 
3321
- The old `1 export 2 run 3 history` menu is gone; `bareloop export|run|history` and the other sub-commands are unchanged. `run-u`, `interview` and `author` are dispatched
3322
- by name only: `bareloop run-u <flags…>`, `bareloop interview <flags…>`, `bareloop author <flags…>`.
3323
+ **One menu (PRD v1.114, F245).** Bare `bareloop` prints the header, then `panel: 1 start 2 stop 3 restart 4 status 5 install`, `jobs: 6 export 7 run 8 resume 9 history` and `q quit`. Each job command asks for what it needs
3324
+ (typed flags skip the question): **export** lists the green runs as numbered `job (run-N)` names, then asks the output folder; **run** asks the bundle (the last 10 known bundles are listed newest first, numbered, as run name + folder; a number picks one, a run name or a folder reaches an older one; none known: `No exported bundles yet. Export one with 6.` and it ends), the repo, then
3325
+ the `$` cap and the time cap (Enter keeps the signed ones); **resume** lists the stopped / capped bundle runs the engine would resume, then offers more money / time; **history** asks the bundle and prints what `bareloop history <bundle>` prints.
3326
+ `q` at any question ends the command cleanly (nothing run, exit `0`). A required question answered with an empty Enter is asked once more; a second empty Enter ends that command with a plain line (nothing chosen, nothing run), exit `0`. `interview`, `author`, `replay` and `runs backfill` are no longer commands
3327
+ (`node scripts/run-replay.mjs`, `scripts/run-interview.mjs`, `scripts/run-author.mjs` run from a source checkout; the library functions the panel uses stay). `run-u` is still dispatched by name (`bareloop run-u <flags…>`: the panel spawns it) but is listed nowhere.
3323
3328
 
3324
3329
  When two key rows share one provider and endpoint, a CLI run uses the FIRST row in the keys list, so put the
3325
3330
  key you want first (the panel picks the row by the Model menu).
3326
3331
 
3332
+ - **`bareloop export ["<job> (run-N)"] [--out <dir>]`** (PRD v1.114; `src/runexport.js`) → a bundle from a GREEN panel / run-u run, by the name the panel shows. No name: the green runs are listed numbered and you pick;
3333
+ no `--out`: the folder is asked. The bundle is the run's OWN signed spec (`closeDecl` kept as signed — no close scripts, nothing edited, same `jobSpecHash`) plus a bridge-v1 record minted with `mintBridge` from the run's saved plan
3334
+ (`bridge-<job>-<runid>.json`, beside its spine) and the run's spine: cost (`job-end` `engagementSpentUsd`, else `spentUsd`), `spendComplete`, wall time (`legsWallMs`), rounds (`readTry`), and the run list's `patient`.
3335
+ A value that cannot be read is refused in plain words naming it, never guessed. **Repo jobs only for now:** a rubric (judged) job, a job that reads a page link and a plain-folder job are refused at $0 with `only repo jobs can be exported for now`
3336
+ and the reason. Each export appends ONE `{type:'exported', runid, job, bundle, bundleHash, at}` row to `runs.jsonl` (ignored by every run-list reader) so `bareloop run "<name>"` finds the bundle. Then `cd <bundle> && npm install`.
3337
+ `exportBundle` takes a spec with `closeDecl` and no `close` (both is a red). Exit `0`, `1` on a refusal. The older form below (`--registry`) is unchanged.
3327
3338
  - **`bareloop export <jobs/x.json> --registry <dir> --out <dir>`** → resolves the spec's
3328
3339
  close-script paths against the spec file's own directory (never the process cwd), calls
3329
3340
  `exportBundle`. On success prints `bundleHash:`, the sorted file list, and "this bundle is
3330
3341
  unblessed until its first run greens on the importer's machine." Exit `1` on any red or
3331
3342
  missing flag, `0` on success.
3332
3343
 
3333
- - **`bareloop run <bundleDir> --repo <path> [--budget N] [--wall MIN] [--approve <bundleHash>]`**
3334
- and **`bareloop run <bundleDir> --resume <runid> [--repo <path>] [...]`** — a thin door
3344
+ - **`bareloop run <bundle> --repo <path> [--model <id>] [--budget N] [--wall MIN] [--yes] [--approve <bundleHash>]`**
3345
+ and **`bareloop run <bundle> --resume <runid> [--repo <path>] [...]`** — `<bundle>` is a folder OR the run name it was exported under (`job (run-N)`, found through the `exported` rows in `runs.jsonl`;
3346
+ `src/bundleref.js`). **PRD v1.114 changes to the steps below:** (a) a missing bundle, repo or model is ASKED for (when stdin is a terminal or a caller-handed stream; a bare uninjected pipe gets the usage line, as before) —
3347
+ the model from the Settings-ticked lines, only when the bundle's spec names none and no `--model` is given; an empty Enter asks once more, a second ends the command (exit `0`, nothing run). A guided run
3348
+ (anything asked) also offers the optional `$` cap and time cap (Enter keeps the signed ones). (b) **A cap ABOVE the signed one is allowed with your yes**, at `run` and at `run --resume`: it prints
3349
+ `This raises the $ cap from $X to $Y.` (or the time cap, in minutes), then `Type yes to sign it:`; only `yes` proceeds. With no terminal a raise needs `--yes`, else it is refused at $0 (`envelope-widen`,
3350
+ the sentence says how). The approval is appended to `<bundleDir>/runs/<runid>/approvals.jsonl` as `{type:'cap-raise', who, field, old, new, at, bundleHash, approveHash}` once the engine accepts the run, and the
3351
+ history row carries `capsRaised`. Lowering needs no confirm. A resume's ceiling still folds prior spend. (c) **A green run commits its work on its work branch** (`commitWork`, the panel's own call: everything
3352
+ changed except the arbiter's books and `node_modules`; a green with nothing to commit says so), printed as a `commit` line before `branch`/`worktree`/`merge`. The folder is kept; the merge stays yours.
3353
+ (d) The first run of an UNBLESSED bundle typed at a terminal (the menu) shows the `bundleHash` and asks `Type yes to sign it:`; only `yes` proceeds and counts as the approval, recorded as `{type:'bundle-approve', who, bundleHash, at}` in `approvals.jsonl`. Flags only keeps `--approve <bundleHash>` (`--yes` signs caps, not a bundle). Export's list shows only runs it can take (green with a saved plan, a signed spec, a repo job). — a thin door
3335
3354
  (`src/bundlerun.js`) to the same engine `bareloop run-u` drives (`src/userrun.js`): one
3336
3355
  runner, so providers, keys (any provider the bundle's spec names — the keys file or env), the
3337
3356
  judge, the monthly $ limit, the outside watchdog and the readout are that engine's. The door
@@ -3341,8 +3360,8 @@ key you want first (the panel picks the row by the Model menu).
3341
3360
  `require.resolve('bareloop')`? A red (`bundle-deps-missing`) prints the exact cure line
3342
3361
  (`cd <bundleDir> && npm install`) and stops, exit `1`, before the envelope check, the
3343
3362
  blessing check, any key, or any worktree.
3344
- 3. `checkEnvelope(spec, { budgetUsd?, maxWallMs? })` — `--wall` is minutes, converted to ms.
3345
- A red (an invalid number, or a widen) stops here, exit `1`.
3363
+ 3. `checkEnvelope(spec, { budgetUsd?, maxWallMs? })` over the LOWERED / equal fields — `--wall` is minutes, converted to ms.
3364
+ A red (an invalid number) stops here, exit `1`. A field above the signed one is a RAISE (`capRaises`): shown back and signed by `yes` / `--yes`, else `envelope-widen`, exit `1` (see the header above).
3346
3365
  4. Blessing — BEFORE any key is read. No `blessing.json` yet: print the bundle's `README.md`
3347
3366
  (the operator questions), the "first run" notice + the minting-run line (F128-corrected —
3348
3367
  see below), the `bundleHash`, and **require** `--approve <bundleHash>` to match exactly, or
@@ -3364,8 +3383,8 @@ key you want first (the panel picks the row by the Model menu).
3364
3383
  (P5-R): no new id, run dir or worktree. The resume command a halted leg prints carries that leg's own
3365
3384
  `--budget`/`--wall`, only if you passed them (a tightened ceiling never silently reverts to the signed
3366
3385
  one). After a MONEY halt the line does NOT repeat the exhausted `--budget` (chain spend is folded, so
3367
- it would halt again at once); it prints `--budget <more than $<spent so far>, at most $<signed
3368
- budgetUsd>>` for you to fill in, and is not runnable until you do. When the run spent the WHOLE signed
3386
+ it would halt again at once); it prints `--budget <more than $<spent so far>, above $<signed
3387
+ budgetUsd> asks you to type yes>` for you to fill in, and is not runnable until you do. When the run spent the WHOLE signed
3369
3388
  ceiling, that range is empty, so no resume line is printed: the block says no room is left under the signed ceiling. A bundle's spec is
3370
3389
  manifest-hashed, so its halt hint never asks you to edit `budgetUsd`.
3371
3390
  6. `resolveBundleSpec` (the `$BARELOOP_BUNDLE` substitution) → tighten `budgetUsd`/`maxWallMs`
@@ -3417,7 +3436,7 @@ key you want first (the panel picks the row by the Model menu).
3417
3436
  writes `JSON.stringify(row)` — `src/bundle.js`), then every bridge's `listingRow(b)` from
3418
3437
  `<bundleDir>/bridges`. Always exit `0`; "(no runs yet)" when `history.jsonl` doesn't exist.
3419
3438
 
3420
- - **`bareloop replay <spine.jsonl>`** / **`bareloop replay --all <dir>`** (PANEL-BUILD.md
3439
+ - **`bareloop replay …` LEFT THE CLI (PRD v1.114): it is `node scripts/run-replay.mjs <spine.jsonl>` / `--all <dir>` now (same output, same exit codes; the library is unchanged).** Historical entry: **`bareloop replay <spine.jsonl>`** / **`bareloop replay --all <dir>`** (PANEL-BUILD.md
3421
3440
  P0, last of the rung's four tasks) → the read side for the panel's History/Run/Audit/Job
3422
3441
  tabs: point it at one run's spine (+ its `-gate-audit.jsonl` sidecar, resolved
3423
3442
  automatically) and get `formatReplay`'s one-page report; point `--all` at a directory and
@@ -3435,7 +3454,7 @@ key you want first (the panel picks the row by the Model menu).
3435
3454
  this command reports, it never grades), `1` on a missing file/directory or a non-spine
3436
3455
  file, `1` with a usage line on no args.
3437
3456
 
3438
- - **`bareloop runs`** / **`bareloop runs backfill <dir>`** (PANEL-BUILD.md P1, 2026-09-24
3457
+ - **`bareloop runs`** still prints the run list; **`runs backfill` LEFT THE CLI (PRD v1.114)** (the library's `backfillRuns` stays). Historical entry: **`bareloop runs`** / **`bareloop runs backfill <dir>`** (PANEL-BUILD.md P1, 2026-09-24
3439
3458
  rulings — "one home for runs", hamr's option B) → the one run list, at `~/.config/bareloop/
3440
3459
  runs.jsonl` (the same directory the keys file, PRD §7d, lives in — outside any repo tree,
3441
3460
  never moved into one). This is a LIST, not a relocation: patient copies stay exactly where
@@ -3549,7 +3568,7 @@ key you want first (the panel picks the row by the Model menu).
3549
3568
  session is still non-terminal — one authoring session at a time) creates a session
3550
3569
  (`src/panel/authorsession.js`) that runs `prepareSource`/`detectLanguage`/`validateJob`/
3551
3570
  `authorCloseForJob`/`assembleSpec`/`prepareSigning` in-process, exactly the library calls
3552
- `bareloop interview`/`bareloop author` already make — never a script's own readline loop,
3571
+ `scripts/run-interview.mjs`/`scripts/run-author.mjs` already make — never a script's own readline loop,
3553
3572
  never a reimplementation of any gate. `GET /api/author/model-check?provider=<KEY>&model=<id>` is the $0 readiness probe the job card runs
3554
3573
  before Start (`checkProviderReachable`, `src/providers.js` — a models-list GET only, never a
3555
3574
  completion; the page sees the key's NAME and a status word, never the value). `POST
@@ -3564,7 +3583,7 @@ key you want first (the panel picks the row by the Model menu).
3564
3583
  `{ok, sessionId, state}` of the ONE live (non-terminal) session, or `{sessionId:null, state:null}`: a refreshed page
3565
3584
  re-attaches to it from the server's session map (nothing is stored page-side). A panel restart mints a new token and
3566
3585
  loses the in-memory sessions: the page then shows one "reload this page" line and stops the Chat poll (no auto-reload;
3567
- drafting money already spent stays booked via `draft-spend.json`, below). `GET /api/author/:id` polls the session's state
3586
+ drafting money already spent stays booked via the session's `draft-log.jsonl`, below). `GET /api/author/:id` polls the session's state
3568
3587
  (phase, chat messages, cost, `specHash` once prepared). `POST /api/author/
3569
3588
  :id/send {text}` answers whatever the confirm turn is currently asking (the `language` pick or a plan's
3570
3589
  own follow-up question — the old `worseThanBefore` ask is retired, 2026-09-28) — refused outright when the pending ask is the
@@ -3586,7 +3605,7 @@ key you want first (the panel picks the row by the Model menu).
3586
3605
  a test can drive the real ask()-channel/hash wiring without a live provider call;
3587
3606
  none of them are reachable from `authorroutes.js`'s real construction path. Sessions live
3588
3607
  under `~/.config/bareloop/panel-sessions/<id>/` (each one's own `resolved-spec.json` and
3589
- `signing.json`, the two files `bareloop author` itself already writes). Edit/re-sign, the
3608
+ `signing.json`, the two files `scripts/run-author.mjs` itself already writes). Edit/re-sign, the
3590
3609
  `~/.config/bareloop/.env` keys-file loader, and Settings have landed (P4a/P4b — see "Settings" below).
3591
3610
 
3592
3611
  - **Panel P5 — the Ended block (`docs/product/PANEL-BUILD.md` Addendum 2026-10-02, item 1)** →
@@ -3641,7 +3660,7 @@ key you want first (the panel picks the row by the Model menu).
3641
3660
  started under is never overwritten, and a run resumed under `r<k>` is resumed again under the
3642
3661
  spec whose hash its `job-start` carries. The spawn is `setsid --wait systemd-inhibit node
3643
3662
  bin/bareloop.mjs run-u --spec <spec> --resume <runid> --approve <hash>` (array argv, detached,
3644
- log `resume-<runid>-<ms>.log` beside the spec; `--draft-spent-usd`/`--draft-spend-incomplete`
3663
+ log appended to the folder's one `run.log` beside the spec, under a header line `== resume <runid> at <ISO> ==` (Accept, Rerun and Pause append there too; a refusal shows only its own action's lines, read from after the header); `--draft-spent-usd`/`--draft-spend-incomplete`
3645
3664
  ride along from the run's `job-start`, so the one cap still covers drafting). `--wait` hands back
3646
3665
  the engine's own exit code: an exit inside the settle window (6s) is the engine's own refusal and
3647
3666
  the log tail is returned as `error` verbatim; otherwise `{ok:true, runid, specHash, capsChanged,
@@ -3800,11 +3819,12 @@ key you want first (the panel picks the row by the Model menu).
3800
3819
  over this same `src/userrun.js:main`, not rewired to go through `src/cli.js`.
3801
3820
  **Printed commands are spelled the way you entered:** every re-invocation these flows print (the approve
3802
3821
  line, resume, pause, reopen, the interview's run-author line, the author's run-u line) reads `bareloop
3803
- run-u …` / `bareloop author …` when reached through `bareloop`, and `node scripts/run-u.mjs …` only through
3804
- the source-tree adapters — the tarball ships no `scripts/`. One owner: `commandFor` (`src/invoke.js`),
3822
+ run-u …` when reached through `bareloop`, and `node scripts/run-u.mjs …` only through
3823
+ the source-tree adapters; `interview` and `author` left the CLI (PRD v1.114), so they are always spelled
3824
+ `node scripts/run-interview.mjs` / `node scripts/run-author.mjs` — the tarball ships no `scripts/`. One owner: `commandFor` (`src/invoke.js`),
3805
3825
  fed by each flow's `deps.invokedAs`.
3806
3826
 
3807
- - **`bareloop interview <flags…>`** (PANEL-BUILD.md P0 task 3/4) → the close-authoring
3827
+ - **`bareloop interview` LEFT THE CLI (PRD v1.114): `node scripts/run-interview.mjs <flags…>` is the door; its "run it now" offer starts `scripts/run-author.mjs`.** Historical entry: **`bareloop interview <flags…>`** (PANEL-BUILD.md P0 task 3/4) → the close-authoring
3808
3828
  interview, at the terminal, one question at a time (D10; `docs/wiki/FINDINGS.md`'s
3809
3829
  interview surface). `src/cli.js`'s `interview` dispatch hands `rest` straight to
3810
3830
  **`src/interviewrun.js`'s own `main(argv, deps)`**, unparsed — the same one-owner shape
@@ -3823,7 +3843,7 @@ key you want first (the panel picks the row by the Model menu).
3823
3843
  `stderr` (the raw streams, not the wrapped `out`/`err` line-functions every other command
3824
3844
  here uses) rather than re-deriving them.
3825
3845
 
3826
- - **`bareloop author <flags…>`** (PANEL-BUILD.md P0 task 4/4) → the authoring pipeline: a
3846
+ - **`bareloop author` LEFT THE CLI (PRD v1.114): `node scripts/run-author.mjs <flags…>`.** Historical entry: **`bareloop author <flags…>`** (PANEL-BUILD.md P0 task 4/4) → the authoring pipeline: a
3827
3847
  real scout over a real repository, a real model filling the close declaration, D9's three
3828
3848
  mechanical gates, stopping at `prepareSigning` (it never signs and never runs the job —
3829
3849
  signing and running are `run-u`'s territory). `src/cli.js`'s `author` dispatch hands `rest`
@@ -3858,9 +3878,10 @@ key you want first (the panel picks the row by the Model menu).
3858
3878
  (`Cap $ − drafting spent`) as ITS own ceiling. Nothing here is left for a person to
3859
3879
  hand-compute or re-type, the same rule F185 set for `--spec`.
3860
3880
 
3861
- **Tighten-only budget/wall.** `--budget`/`--wall` on `bareloop run` may only lower the
3862
- bundle's own signed `budgetUsd`/`maxWallMs` — `checkEnvelope`'s `envelope-widen` red refuses
3863
- anything higher. Raising a ceiling is a re-export (a new signed bundle), never a runner flag.
3881
+ **Lowering is free; raising needs your yes.** `--budget`/`--wall` on `bareloop run` may lower the
3882
+ bundle's own signed `budgetUsd`/`maxWallMs` freely (`checkEnvelope` stays tighten-only). A number above the signed one is a RAISE
3883
+ (`capRaises`): shown back in words and signed by typing `yes` at a terminal (or `--yes`), recorded as a `cap-raise` line in the run's
3884
+ `approvals.jsonl`; with no terminal and no `--yes` it is refused at `$0` as `envelope-widen`.
3864
3885
 
3865
3886
  **First-run approval, blessing, no-resign.** The bundle's own signed `bundleHash` is what a
3866
3887
  human reads and accepts with `--approve` on the run that first blesses it. That first GREEN
@@ -3905,12 +3926,12 @@ yourself if you want a tarball.
3905
3926
 
3906
3927
  No model is called anywhere in learnings (a test walks the import closure). Pure rules in `learn.js`; file IO in `learnstore.js`.
3907
3928
 
3908
- - **Setting:** `learningHints` (`true`/`false`) in `config.json`, absent = OFF. OFF still writes the tally at run end; it only means the planner is handed nothing.
3909
- - **Run end:** `execute` (`src/userrun.js`, shared by the panel, the CLI and the bundle runner) calls `learnAtRunEnd({ home, runid, events, auditFiles, spec, specHash, workdir, trust })` once, right after the claim settles, in its own try/catch: a failure prints one WARNING and never changes the verdict, exit code or spend. It writes nothing when the engine has no config home.
3929
+ - **Setting:** `learningHints` (`true`/`false`) in `config.json`, absent = ON (default ON since 2026-10-24; only an explicit `false` turns it off). OFF still writes the tally at run end; it only means the planner is handed nothing.
3930
+ - **Run end:** `execute` (`src/userrun.js`, shared by the panel, the CLI and the bundle runner) calls `learnAtRunEnd({ home, runid, events, auditFiles, spec, specHash, workflowKey, workdir, trust })` once, right after the claim settles, in its own try/catch: a failure prints one WARNING and never changes the verdict, exit code or spend. It writes nothing when the engine has no config home.
3910
3931
  - **Cards:** `buildCards({ runid, events, audit, workdir, spec, model, questions })` → `{ cards, suspect, thin, noise }`. FIXED = a check red then the same check passes later in the run; NEVER FIXED = still red at run end. Excluded and counted: noise runs (provider-red, close-crashed, worker-crash, no close spoke), CHECK-SUSPECT (a no-suppressions hit on a prose comment), TOO-THIN (no error kind and no fix files). Written files come from `attempt-diff` events and the gate audit's allow write/edit rows relative to the tree.
3911
3932
  - **Fold:** `cardsMatch` / `foldCards`: same job + check, a shared error kind, Jaccard >= 60% on flagged-text tokens (a fit on known cards, not a proof). Code-less cards (kind `other`) fold on the text rule alone, only when both token sets are non-empty (R1, 2026-10-23: UNTESTED on real data; the 60% was fitted on cards with codes). `kindAgrees` is the one kind test.
3912
- - **Ledger** `<config home>/learn/ledger.json` (mode 600, atomic, secrets masked): rows `{ id, lesson, count, sample, models, workflow, place, level, trust, runIds, firstSeen, lastSeen, specHash }`, plus `pending` (holds an older version wrote for rubric runs; new runs write none), `suspect`, `health`. There is no check-wide set-aside (R2, 2026-10-23): a lesson seen in several jobs climbs by the climb rules and is read at its level; all-jobs hints come last. `countLedger` (+1 per run per row), `releasePending` (an OLD hold, written by v0.46.x, counts on the human Accept; `releaseRun` is called from the door's accept path; a rubric run's lessons now count at run end like a deterministic run's, trust `rubric` kept, and `foldRunIntoLedger` returns `held: 0`; reuse/bridge credit still waits for the Accept). A row already holding the run id (a resumed leg, one id) is refreshed from the new card (sample, lesson, key, lastSeen, hash, place) but its count, model tally and run ids do not move, `climb` (the level of a lesson, derived at read time by `readableRows` from the rows not decayed at that moment: it can go back down when siblings age past 56 days; the file stores `workflow` only and ignores an older stored level). The ledger keeps EVERY row (nothing is deleted, no `expired` flag is stored; hamr 2026-10-23). Memory is the filter: `readableRows` / `renderHints` skip a row last seen more than 56 days ago (`isDecayed`) and a workflow row of another signed hash (`otherJobVersion`); a lesson seen again counts +1 on its old row. Old files with `status`/`expiredBy` still load; the fields are ignored and dropped at the next write.
3913
- - **Reading:** `hintsForRun({ home, spec, specHash })` renders once at run start; `runJob(..., { learnHints: { text, ids } })` → `runPlan` hands it to the PLANNER at the draft and the first replan only, and emits a `learnings` spine record with the exact text. `renderHints(ledger, { workflow, place, specHash, now })` is the one render (this job, then this place, then all-jobs, highest count first, 2,000 characters, a hint whole or not at all; all-jobs hints last); a FIXED hint adds `What changed:` (first 3 `+`/`-` lines of the stored diff, 150 chars each, then `(+N more)`; never on NEVER FIXED) and a repeated path in a hint reads as its basename (R3, R5, 2026-10-23); the spine's recorded text is byte-equal to a fresh `renderHints(...).text` from the ledger as it stood. The Audit run detail carries `learnings` (read-only); its header counts DISTINCT hints (the same ledger row handed at the draft and the first replan counts once).
3933
+ - **Ledger** `<config home>/learn/ledger.json` (mode 600, atomic, secrets masked): rows `{ id, lesson, count, sample, models, workflow, place, level, trust, runIds, firstSeen, lastSeen, specHash, workflowKey }` (`workflowKey` is the job version; a row without it, written by an older version, matches any version), plus `pending` (holds an older version wrote for rubric runs; new runs write none), `suspect`, `health`. There is no check-wide set-aside (R2, 2026-10-23): a lesson seen in several jobs climbs by the climb rules and is read at its level; all-jobs hints come last. `countLedger` (+1 per run per row), `releasePending` (an OLD hold, written by v0.46.x, counts on the human Accept; `releaseRun` is called from the door's accept path; a rubric run's lessons now count at run end like a deterministic run's, trust `rubric` kept, and `foldRunIntoLedger` returns `held: 0`; reuse/bridge credit still waits for the Accept). A row already holding the run id (a resumed leg, one id) is refreshed from the new card (sample, lesson, key, lastSeen, hash, key, place) but its count, model tally and run ids do not move, `climb` (the level of a lesson, derived at read time by `readableRows` from the rows not decayed at that moment: it can go back down when siblings age past 56 days; the file stores `workflow` only and ignores an older stored level). The ledger keeps EVERY row (nothing is deleted, no `expired` flag is stored; hamr 2026-10-23). Memory is the filter: `readableRows` / `renderHints` skip a row last seen more than 56 days ago (`isDecayed`) and a workflow row of another workflow key (`otherJobVersion`; a cap, time, source, destination, inputs or model change keeps the lessons); a lesson seen again counts +1 on its old row. Old files with `status`/`expiredBy` still load; the fields are ignored and dropped at the next write.
3934
+ - **Reading:** `hintsForRun({ home, spec, workflowKey })` renders once at run start; `runJob(..., { learnHints: { text, ids } })` → `runPlan` hands it to the PLANNER at the draft and the first replan only, and emits a `learnings` spine record with the exact text. An unreadable ledger file hands the planner nothing, never stops the run, and is not silent: `handedHints` returns the reason and the engine emits a `learnings` record `{phase:'draft', hintsError}` (no `text`); the Audit run detail carries `learningsError` (the plain line from `hintsErrorLine`, home folder written `~`; the spine keeps the full reason) and the learnings box prints it under the title "No lessons were given to the planner" (with hints the title stays "What the planner was told from earlier runs"). `renderHints(ledger, { workflow, place, workflowKey, now })` is the one render (this job, then this place, then all-jobs, highest count first, 2,000 characters, a hint whole or not at all; all-jobs hints last); a FIXED hint adds `What changed:` (first 3 `+`/`-` lines of the stored diff, 150 chars each, then `(+N more)`; never on NEVER FIXED) and a repeated path in a hint reads as its basename (R3, R5, 2026-10-23); the spine's recorded text is byte-equal to a fresh `renderHints(...).text` from the ledger as it stood. The Audit run detail carries `learnings` (read-only); its header counts DISTINCT hints (the same ledger row handed at the draft and the first replan counts once).
3914
3935
 
3915
3936
  ### Settings — the keys file, `config.json`, the monthly $ limit, the Providers tab (PANEL-BUILD.md P4a, `src/keysfile.js`, `src/config.js`, `src/monthly.js`, `src/providerrows.js`, `src/panel/settingsroutes.js`)
3916
3937
 
@@ -3925,7 +3946,7 @@ Two files in `~/.config/bareloop/`, outside any repo:
3925
3946
  real one). The CLI (`run-u`, `interview`, `author`) and the panel both use it.
3926
3947
  - **`config.json` — every setting, never a key value.** `readConfig({ home })` /
3927
3948
  `updateConfig(patch, { home })` (atomic tmp + rename, mode 600, unknown fields kept).
3928
- Fields: `learningHints` (true/false; absent = off; see "Cross-run learnings"), `monthlyLimitUsd` (number above 0; absent or `null` = no limit; any other value present
3949
+ Fields: `learningHints` (true/false; absent = on; see "Cross-run learnings"), `monthlyLimitUsd` (number above 0; absent or `null` = no limit; any other value present
3929
3950
  is a `ConfigError`, refused like an unreadable file), `keys.<ENV NAME>` = `{ shape, baseUrl, legacyMaxTokens }` (the Providers rows' settings: an API shape id, the typed Base URL,
3930
3951
  the "old max_tokens" tick), `models.<ENV NAME>` = a list of `{ model, use, inPerM?, outPerM? }` lines (replaced WHOLE on every save; the customer's own price below). Nothing is built
3931
3952
  in: a row with nothing saved is shape `openai-api`, no address, no lines. A secret-shaped
@@ -3956,14 +3977,15 @@ spends; the CLI prints it to stderr, exit 2) and at the panel's Sign & run (`sig
3956
3977
  same text under `#jf-cap-money` via `GET /api/author/monthly-check?cap=`. "This month" is the local
3957
3978
  calendar month; a died or incomplete-spend run makes the total an "at least" figure.
3958
3979
 
3959
- *Drafting spend that never became a run* (2026-10-05, F213). A panel authoring session writes
3960
- `<session dir>/draft-spend.json` (`{ sessionId, spentUsd, spendComplete, provider, baseUrl, model,
3961
- startedAt, updatedAt }`, atomic) after every metered call, so an abandoned, refused or restarted session's
3962
- drafting money is not lost. `readLegs` (hence `monthSpend`, `spendSummary`, `checkMonthlyRoom` and the Money
3963
- tab) adds every `<home>/panel-sessions/<id>/` that has one and whose folder holds no listed run's `spine` or
3980
+ *Drafting spend that never became a run* (2026-10-05, F213). A panel authoring session appends one `call` line
3981
+ (`{ ..., model, provider, baseUrl, costUsd, unpricedRounds, at }`) to `<session dir>/draft-log.jsonl` after every
3982
+ metered call, so an abandoned, refused or restarted session's drafting money is not lost (there is no second
3983
+ total file: `draft-spend.json` is no longer written, and a folder left by the old shape that has the file and no call
3984
+ lines is still read from it). `readLegs` (hence `monthSpend`, `spendSummary`, `checkMonthlyRoom` and the Money
3985
+ tab) folds the call lines with `tallyCalls` for every `<home>/panel-sessions/<id>/` whose folder holds no listed run's `spine` or
3964
3986
  `patient` (a signed run already carries its drafting spend via `--draft-spent-usd`; no double count). It lands in
3965
- the month of `startedAt` (the first call), under the provider row it was drafted on; `spendComplete: false` or an
3966
- unreadable file makes the figure an "at least". It is not a run: no wall, not in the `runs` count.
3987
+ the month of the first call, under the provider row it was drafted on; an unpriced call, a torn log line or an
3988
+ unreadable log makes the figure an "at least". It is not a run: no wall, not in the `runs` count.
3967
3989
 
3968
3990
  *Hold until done.* A run CLAIMS the limit when it starts and holds it until it is done — no lock file,
3969
3991
  records only. `claimRun` (`src/monthly.js`) writes the run's row FIRST (it carries its `pid` and
@@ -4441,7 +4463,7 @@ Check what the person asked for, not what the worker chose to write. bareloop ne
4441
4463
  - **No record cutting (Part 1c).** A fact part carries no `record`, `tested` or `sample` (a `record` field is an unknown-field red). The worker's brief says "one quote per result, copied from that result's own text" (bareguard's quote cap of 4000 characters stays its own). Drafting does not grade: it only proves each fact CAN be checked (below).
4442
4464
  - **Repeat rule (Part 1c M1, M4).** On a fact line asking for N results (`count.min`), `checkFactWords` (`src/factwords.js`, the one owner) refuses at $0 an anchor label the label list counts fewer than N times (`rubric-fact-label-rare`) and a `phrase` fact whose words `countPhrase` finds in the input fewer than N times (`rubric-fact-phrase-rare`); count 1 or none keeps a once-only one legal. `RUBRIC_RULES` states both.
4443
4465
  - **The look, then the draft (Part 1c; the default look is now the page-word map, next bullet).** For a rubric job on files, `authorCloseForJob` runs the look (`lookFn`, default `runPageMap`; the older search-and-read `runInputLook` in `src/authorscout.js`, pure parts in `src/inputlook.js`, is unwired from the default path) on the frozen input text BEFORE the confirm turn and the draft, when a `provider` is present (`lookFn: null` = no look; a panel test that replaces `generate` gets none unless it passes `lookFn`). Read-only by construction: tools `search_input` / `read_input` over in-memory text, `LOOK_ROUNDS` 8, a reserved final round whose only tool is the strict answer form `report_look`, spend metered into the drafting book (`calls` absorbed like the repo scout's). Its report (facts with a label picked from the list, prose lines, not-found entries) is verified by code (`verifyLookReport`: a label off the list, an unknown shape/line/input, or a phrase not in the source is moved to not-found, named) and rendered into the drafter's prompt (`renderLookReport`); a failed or reportless look is an ABSENT survey and stops drafting at $0 (`scout-absent`, "the first look at your repo or input did not complete"). Every place, date or name in the job line is a fact too, bound to the label before it (a direction = phrase facts `Leaves <place>` / `arrives at <place>`); prose lines and their `~` limits are not looked up.
4444
- - **The page-word map (idea A core, `src/pagemap.js`, `src/pagerules.js`, `docs/product/ITEM33-BUILD.md` "Addendum 2026-10-18 — Idea A core").** The default `lookFn` is `runPageMap`: ONE AI call per page input (the job's drafter identity, thinking off, booked per call into `draft-spend.json`, cap checked before each call) maps the job to the page's OWN words as `{"facts":[{name, from, shape: place|money|time|phrase, words, currency?, unit?}]}`; it takes the old look's arguments and returns the same envelope. Plain code then keeps or drops each word (`applyPageRules(text, mapping, jobLines)` -> `{ facts, dropped }`, pure, ported from the frozen POC): found-on-page (count >= 1), N2 (a label written 2+ times inside one page line is unusable), R1 (a second label stays only if it reads the same values as the first), U1 (a label the page writes AFTER the number, "EUR 490 total", becomes a unit; a label with no number either side is dropped), R1L (a unit/currency form stays only if it reads the same numbers as the primary form; units first; before R1L the forms are sorted by code - a sign is a currency, any other form a unit, whichever box the AI used), S1 (a fact name that counts results is refused; two facts may not share shape AND label). After the rules, `dryReadMoney` (`src/pagedry.js`, called by `runPageMap`) grades an honest claim on every result line with the run's own checker; a money fact that reads none is left under Not checked (`reads-no-result`); then `dryReadPhrases` reads each kept phrase fact against those same result lines (the lines the job's kept money facts read) and drops a phrase found in none of them whole as `phrase-no-result` (Not checked: `"Rome" is on the page but in none of its results, so it is not checked.`); with no kept money fact the result lines are unknown and phrase facts pass untouched. The AI never grades; the answer is read strictly (no JSON repair): a malformed or truncated answer is retried ONCE, twice is the plain stop "The AI's answer about the page was not readable twice. Nothing was signed." (an ABSENT survey; a draft is not a run, so no Resume); one retry on a transport error (booked unpriced, so `spendComplete=false`) or a 429 (the vendor's stated wait). The scrubbed raw answer rides each call into `draft-log.jsonl` (`call.raw`), unsigned, so a run can be replayed at $0. A drafted fact may use only words the map KEPT: a signed anchor, closing label, unit or currency that was dropped is the red `rubric-fact-word-dropped` with the drop's reason, and an anchor must be a kept label (`rubric-fact-label-off-list`, now against the kept set).
4466
+ - **The page-word map (idea A core, `src/pagemap.js`, `src/pagerules.js`, `docs/product/ITEM33-BUILD.md` "Addendum 2026-10-18 — Idea A core").** The default `lookFn` is `runPageMap`: ONE AI call per page input (the job's drafter identity, thinking off, booked per call into `draft-log.jsonl`, cap checked before each call) maps the job to the page's OWN words as `{"facts":[{name, from, shape: place|money|time|phrase, words, currency?, unit?}]}`; it takes the old look's arguments and returns the same envelope. Plain code then keeps or drops each word (`applyPageRules(text, mapping, jobLines)` -> `{ facts, dropped }`, pure, ported from the frozen POC): found-on-page (count >= 1), N2 (a label written 2+ times inside one page line is unusable), R1 (a second label stays only if it reads the same values as the first), U1 (a label the page writes AFTER the number, "EUR 490 total", becomes a unit; a label with no number either side is dropped), R1L (a unit/currency form stays only if it reads the same numbers as the primary form; units first; before R1L the forms are sorted by code - a sign is a currency, any other form a unit, whichever box the AI used), S1 (a fact name that counts results is refused; two facts may not share shape AND label). After the rules, `dryReadMoney` (`src/pagedry.js`, called by `runPageMap`) grades an honest claim on every result line with the run's own checker; a money fact that reads none is left under Not checked (`reads-no-result`); then `dryReadPhrases` reads each kept phrase fact against those same result lines (the lines the job's kept money facts read) and drops a phrase found in none of them whole as `phrase-no-result` (Not checked: `"Rome" is on the page but in none of its results, so it is not checked.`); with no kept money fact the result lines are unknown and phrase facts pass untouched. The AI never grades; the answer is read strictly (no JSON repair): a malformed or truncated answer is retried ONCE, twice is the plain stop "The AI's answer about the page was not readable twice. Nothing was signed." (an ABSENT survey; a draft is not a run, so no Resume); one retry on a transport error (booked unpriced, so `spendComplete=false`) or a 429 (the vendor's stated wait). The scrubbed raw answer rides each call into `draft-log.jsonl` (`call.raw`), unsigned, so a run can be replayed at $0. A drafted fact may use only words the map KEPT: a signed anchor, closing label, unit or currency that was dropped is the red `rubric-fact-word-dropped` with the drop's reason, and an anchor must be a kept label (`rubric-fact-label-off-list`, now against the kept set).
4445
4467
  - **Currency and unit lists (idea A core, `src/facts.js`).** A money fact's `unit` and `currency` may each be one string (every spec signed before lists) or a non-empty list: at most 3 currencies (`$ € £` only; a code like `EUR` is a unit) and 10 units, none repeated, a unit at most 100 characters, enforced by our own plain reds before bareguard is asked. A string reads exactly as a one-element list and is never rewritten, so an old signed spec keeps its bytes and hash. The first listed form is the primary one in the plan row and the worker brief; others read "or". `checkFactWords` requires EVERY listed unit and sign to be on the page.
4446
4468
  - **No silent drop (idea A core, `src/pagedropwords.js`, `withDropNotes` in `src/rubricstep.js`).** Every word, fact or `~` rule the page rules drop is shown as Not checked with a plain sentence from ONE table (no other file writes a drop reason). Before validation `withDropNotes` appends to the declaration: `closeDecl.refused` `{ line, rule, reason }` for a dropped fact whose `~` rule no part carries (never a line-level refusal; a rule the drafter already listed is not listed twice), and one line in `closeDecl.notes` for any other drop, including a word cut from a fact that is still checked. Those word-level lines are not "Not checked": `splitReadNotes` / `isReadNote` (`src/pagedropwords.js`) sort a row whose every sentence only says which written form of a still-checked fact was not used (not on the page, listed twice, not the same values, list limits, and an `s1` copy of a fact that is still signed) into `readNotes`, shown in their own fold "How the page was read · N" right after Not checked (plan card, Job tab, Result tab `readNotes`, CLI confirm menu) and not counted in it; a whole fact left out (`no-label`, `reads-no-result`, `phrase-no-result`, an `s1` copy of an unsigned fact) stays Not checked. The signed fact names come from `signedFactNames(closeDecl)` (older specs too) or the look at the confirm turn (`plan.signedFacts`). The confirm card gets the same lines (`plan.notChecked`) before drafting is paid for, and the drafter's look block says `NOT CHECKED (rule n)` / `LEFT OUT`. Nothing about this changes a signed spec's verdict rules; it is the Not checked list, in the person's words.
4447
4469
  - **Labels are picked, never typed (`src/labelscan.js`).** `scanLabels(text)` lists, per shape (money, number, date, time, text), the words right before each value with counts (top 40 per shape; one generic scan, no per-site table; a page reader's `[ref=N]` tags are ignored). `labelOnList(scan, shape, idOrText)` is the one test (id or exact words, white-space blind). The look and the drafter pick labels only from the list shown in the prompt (`renderLabelList`). Fact-line reds are plain sentences; the confirm step and the drafter share one rule text (`RUBRIC_RULES`), and the drafter's per-shape field guide is generated from bareguard's `rubricVocabulary`.
package/bin/bareloop.mjs CHANGED
@@ -19,5 +19,7 @@ const code = await main(process.argv.slice(2), {
19
19
  stderr: process.stderr,
20
20
  cwd: process.cwd(),
21
21
  stdin: process.stdin,
22
+ // a pipe or </dev/null is read (the menu takes its choices from it) but never asked a missing argument
23
+ interactive: Boolean(process.stdin.isTTY),
22
24
  });
23
25
  process.exitCode = code;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "bareloop",
3
- "version": "0.47.1",
3
+ "version": "0.48.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/bundle.js CHANGED
@@ -344,10 +344,18 @@ export function exportBundle({ spec, closeScripts, registryDir, outDir, bareloop
344
344
  red('invalid-value', 'spec.job', 'a job spec with a job slug is required');
345
345
  return fail();
346
346
  }
347
- if (!Array.isArray(spec.close) || spec.close.length === 0) {
348
- red('invalid-value', 'spec.close', 'a non-empty ordered close stage list is required to export');
347
+ // A panel job is signed with a declared close (`closeDecl`, no `close`): its checks are data the engine builds
348
+ // at run time, so there are no close scripts to relocate. `close` and `closeDecl` are alternatives (both is a red).
349
+ const declared = isObj(spec.closeDecl) && spec.close === undefined;
350
+ if (spec.close !== undefined && spec.closeDecl !== undefined) {
351
+ red('invalid-value', 'spec.closeDecl', 'close and closeDecl are alternatives — a spec declares one');
349
352
  return fail();
350
353
  }
354
+ if (!declared && (!Array.isArray(spec.close) || spec.close.length === 0)) {
355
+ red('invalid-value', 'spec.close', 'a non-empty ordered close stage list (or a closeDecl) is required to export');
356
+ return fail();
357
+ }
358
+ const closeStages = declared ? [] : spec.close;
351
359
  const scripts = isObj(closeScripts) ? closeScripts : {};
352
360
 
353
361
  // outDir: refuse a non-empty destination before any other check runs, since
@@ -389,7 +397,7 @@ export function exportBundle({ spec, closeScripts, registryDir, outDir, bareloop
389
397
  const byPath = new Map();
390
398
  /** @type {Map<string, string>} basename -> scriptPath (collision detection) */
391
399
  const byName = new Map();
392
- spec.close.forEach((/** @type {any} */ stage, /** @type {number} */ i) => {
400
+ closeStages.forEach((/** @type {any} */ stage, /** @type {number} */ i) => {
393
401
  const at = `close.${i}.cmd`;
394
402
  const parsed = parseNodeCmd(isObj(stage) ? stage.cmd : undefined);
395
403
  if (!parsed.ok) { red('close-cmd-unrelocatable', at, `must be "node <absolute path>.mjs …" — got ${JSON.stringify(isObj(stage) ? stage.cmd : stage)}`); return; }
@@ -465,7 +473,7 @@ export function exportBundle({ spec, closeScripts, registryDir, outDir, bareloop
465
473
  relocatedSha.set(scriptPath, hash);
466
474
  }
467
475
 
468
- const specOut = { ...spec, close: spec.close.map((/** @type {any} */ stage) => {
476
+ const specOut = declared ? spec : { ...spec, close: closeStages.map((/** @type {any} */ stage) => {
469
477
  const parsed = parseNodeCmd(stage.cmd);
470
478
  // unreachable: every stage's cmd already passed this same parse above, or
471
479
  // the function returned before reaching this write pass at all
@@ -562,10 +570,10 @@ export function exportBundle({ spec, closeScripts, registryDir, outDir, bareloop
562
570
  ' Every run creates a FRESH detached worktree under',
563
571
  ' <repo>/.bareloop/wt/<runid> and never reuses or deletes one for you;',
564
572
  ' your checkout is never touched.',
565
- '4. Budget/wall (optional) — --budget <usd> and --wall <minutes> may only',
566
- ` TIGHTEN this bundle's own signed ceiling${spec.maxWallMs != null ? 's' : ''} (budgetUsd ${spec.budgetUsd ?? '?'}`
567
- + `${spec.maxWallMs != null ? `, maxWallMs ${spec.maxWallMs}` : ''}); raising either is a`,
568
- ' re-export, never a runner flag.',
573
+ '4. Budget/wall (optional) — --budget <usd> and --wall <minutes> set this run\'s caps.',
574
+ ` Lowering the signed ceiling${spec.maxWallMs != null ? 's' : ''} (budgetUsd ${spec.budgetUsd ?? '?'}`
575
+ + `${spec.maxWallMs != null ? `, maxWallMs ${spec.maxWallMs}` : ''}) needs nothing; raising either shows the raise and needs you to type yes`,
576
+ ' (or pass --yes), and the approval is recorded in the run.',
569
577
  '',
570
578
  ].join('\n');
571
579
  writeFileSync(join(outDir, 'README.md'), readme);
@@ -697,12 +705,31 @@ export function checkEnvelope(spec, envelope = {}) {
697
705
  continue;
698
706
  }
699
707
  if (typeof s[field] === 'number' && e[field] > s[field]) {
700
- reds.push({ code: 'envelope-widen', path: field, detail: `${e[field]} exceeds the bundle's signed ${field} (${s[field]}) — raising a ceiling is a re-export, never a runner flag` });
708
+ reds.push({ code: 'envelope-widen', path: field, detail: `${e[field]} exceeds the bundle's signed ${field} (${s[field]}) — a raise needs your yes: type yes when asked, or pass --yes` });
701
709
  }
702
710
  }
703
711
  return { ok: reds.length === 0, reds };
704
712
  }
705
713
 
714
+ /**
715
+ * The caps a typed envelope would RAISE above the bundle's signed ones (hamr 2026-10-25: a raise is allowed, but only signed by the
716
+ * person typing `yes` or passing `--yes`). Same fields and test as {@link checkEnvelope}'s widen red; a field the spec has no ceiling
717
+ * for cannot be raised. Pure.
718
+ * @param {any} spec the (already `$BARELOOP_BUNDLE`-resolved) bundle spec
719
+ * @param {{ budgetUsd?: number, maxWallMs?: number }} envelope
720
+ * @returns {{ field: 'budgetUsd'|'maxWallMs', old: number, new: number }[]}
721
+ */
722
+ export function capRaises(spec, envelope = {}) {
723
+ /** @type {{ field: 'budgetUsd'|'maxWallMs', old: number, new: number }[]} */
724
+ const out = [];
725
+ const s = isObj(spec) ? spec : {};
726
+ const e = isObj(envelope) ? envelope : {};
727
+ for (const field of /** @type {const} */ (['budgetUsd', 'maxWallMs'])) {
728
+ if (typeof e[field] === 'number' && Number.isFinite(e[field]) && typeof s[field] === 'number' && e[field] > s[field]) out.push({ field, old: s[field], new: e[field] });
729
+ }
730
+ return out;
731
+ }
732
+
706
733
  /**
707
734
  * Write `blessing.json`: the FIRST GREEN RUN on the importer's own machine
708
735
  * signs the bundle as trustworthy (hamr Q2), so later runs need no