bareloop 0.46.1 → 0.47.0

package/CHANGELOG.md

@@ -5,6 +5,20 @@ All notable changes to bareloop are documented here. Format:
 [SemVer](https://semver.org/spec/v2.0.0.html). Pre-1.0: **minor** = a ladder rung or
 feature lands, **patch** = docs, fixes, scaffolding.
 
+## [0.47.0] - 2026-10-24
+
+### Added
+
+- **`bareloop` is a launcher (PANEL-BUILD.md addendum L, hamr 2026-10-24).** Bare `bareloop` shows a menu (`1 start  2 stop  3 status  4 install  q quit`) under two header lines (installed or not, panel running or not, `runs: N running · N need you · N in all`); the same four work as `bareloop start | stop | status | install`. No pid file: the panel is found by asking ports 4700-4709 for the new read-only `GET /api/whoami`. `start` runs the panel detached on the first free port (log: `~/.config/bareloop/panel.log`) and opens the page; `stop` stops every panel it finds (one panel at a time; no `--port`, no which-one question), warns about open drafts summed over them and asks (`--yes` skips); `status` prints `Panel not running.` and exits 3 when no panel runs (0 from the menu); `install` creates only what is missing. The old `1 export / 2 run / 3 history` menu is gone (the sub-commands stay). `bareloop panel [--port N]` is unchanged. Coloured on a terminal (off when piped, `NO_COLOR` set or `TERM=dumb`). `status` and the header show the running panel's version, with a stop-and-start note when it differs from the CLI's. The header's `need you` count matches the panel's Needs-you list, schedules that gave up included. `GET /api/whoami` (app, version, pid, port, drafts, schedules) sits behind the Host guard and needs no token. The panel address has one owner (`panelUrl`); no address literal lives in the launcher, and the OS opener is shared with Settings.
+
+### Changed
+
+- **A rubric run's lessons count at run end, like a deterministic run's (hamr 2026-10-24, option A).** `foldRunIntoLedger` no longer holds a `rubric` run's cards in `pending` until the human Accept: they go through `countLedger` now, FIXED and NEVER FIXED alike, with `trust: 'rubric'` kept on new rows; `held` is always 0. A hold already in a ledger file (written by v0.46.x) still releases on the door Accept. Reuse and bridge credit is unchanged and still waits for the Accept. Noise runs stay dropped.
+
+### Fixed
+
+- **A resumed leg updates its own run's ledger row.** `countLedger` skipped a row that already held the run id, so a NEVER FIXED lesson from leg 1 stayed NEVER FIXED when leg 2 (same run id) fixed it. The row is now refreshed from the new card (sample, lesson, key, lastSeen, hash, place) while its count, model tally and run ids stay one per run; an older run's cards re-folded later never step a row back. Found by fwdloop.
+
 ## [0.46.1] - 2026-10-24
 
 ### Fixed

package/README.md

@@ -68,6 +68,8 @@ building it.
 npm install bareloop
 ```
 
+Quick start: `npm install -g bareloop`, then `bareloop` — a menu to start the panel, stop it, see its status, and set up `~/.config/bareloop/`.
+
 ## Usage
 
 A signed job spec goes in. A verdict comes out.

package/bareloop.context.md

@@ -3291,16 +3291,35 @@ real key check is skipped entirely — a scripted provider *is* the run, the
 same seam `tests/planrun-*.test.js` uses. `deps` also accepts `env`, `stdout`, `stderr`, `cwd`,
 `now`, `stdin` — omit any of them and the real `process.*` equivalent is used.
 
-Bare `bareloop` (no sub-command) prints a numbered menu — `1 export  2 run  3 history  q
-quit` — and asks each sub-command's arguments one line at a time over the SAME code paths
-below. `run-u`, `interview` and `author` (below) are not on this menu (PANEL-BUILD.md P0
-tasks 2/4-4/4): each one's own flag grammar is too wide for a line-at-a-time wizard, and the
-menu's job is to ask the SAME questions the sub-command below already answers, never to
-invent a new interview — this is doubly true for `interview`/`author`, which already ARE
-interviews of their own. Choice `2 run` is handed the SAME resolved keys home `bareloop run <bundle>` gets, so the
-monthly limit, your price and the key-row choice apply exactly as on the sub-command (before this it
-got none, and a run started from the menu skipped the limit). All three are dispatched by name only: `bareloop run-u <flags…>`,
-`bareloop interview <flags…>`, `bareloop author <flags…>`.
+Bare `bareloop` (no sub-command) is the **launcher menu** (PANEL-BUILD.md addendum L, `src/launcher.js`): two header lines, then
+`1 start   2 stop   3 status   4 install   q quit`. The header is printed first by EVERY call (menu and each of
+`bareloop start | stop | status | install`), from one function:
+
+```
+bareloop 0.47.0 · installed ✓ · panel running at http://127.0.0.1:4701
+runs: 1 running · 2 need you · 375 in all
+```
+
+Colour (`src/tty-colour.js`): on only when stdout is a terminal, `NO_COLOR` is empty/unset and `TERM` is not `dumb`; it wraps words and never
+changes them, and a piped or `NO_COLOR` run prints the plain words above (the thin `─` rules around the header appear only with colour).
+
+- `installed ✓` = `~/.config/bareloop/` exists, `config.json` is there and reads with no problem, `.env` exists with mode 600, node >= 22;
+  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
+  run list file ($0, works with the panel stopped).
+- **No pid file.** The panel is found by asking `127.0.0.1:4700..4709` for `GET /api/whoami` (300 ms each, in parallel); a reply with `app: "bareloop"` is a panel.
+  `GET /api/whoami` → `{ app: "bareloop", version, pid, port, drafts, schedules }` (open drafting sessions, jobs with a schedule), read-only, same Host guard as every
+  route, no token.
+- **`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
+  `~/.config/bareloop/panel.log`) on the first free port from 4700 (a taken port is skipped and named), waits up to 10 s for it to answer, opens the page with
+  `xdg-open`/`open` (no opener: prints the URL). `bareloop panel [--port N]` is unchanged (foreground, fixed port).
+- **`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 port is quiet. Open drafts (in memory, summed over all found panels) are warned about and a y/N is asked;
+  `--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.
+- **`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).
+- **`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;
+  `Already installed, nothing to do.` when there is nothing to add. Needs node >= 22.
+
+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
+by name only: `bareloop run-u <flags…>`, `bareloop interview <flags…>`, `bareloop author <flags…>`.
 
 When two key rows share one provider and endpoint, a CLI run uses the FIRST row in the keys list, so put the
 key you want first (the panel picks the row by the Model menu).
@@ -3890,7 +3909,7 @@ No model is called anywhere in learnings (a test walks the import closure). Pure
 - **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.
 - **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.
 - **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.
-- **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` (held rubric cards), `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), `holdPending` / `releasePending` (rubric cards count only after the human Accept; `releaseRun` is called from the door's accept path), `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.
+- **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.
 - **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).
 
 ### 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`)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bareloop",
-  "version": "0.46.1",
+  "version": "0.47.0",
   "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.",
   "type": "module",
   "main": "./src/index.js",

package/src/cli.js

@@ -36,6 +36,8 @@ import { bundleMain } from './bundlerun.js';
 // rather than re-parsing argv a second time here keeps exactly one code
 // path for the flag grammar; `src/cli.js` only supplies the deps shape
 // (`out`/`err`/`env`) this command's own callers already use.
+import { startCmd, stopCmd, statusCmd, installCmd, menuCmd } from './launcher.js';
+import { makePaint } from './tty-colour.js';
 import { main as runUMain } from './userrun.js';
 // PANEL-BUILD.md P0 task 3/4 — `bareloop interview` and `bareloop author`
 // wrap the close-authoring interview and authoring-pipeline flows' own
@@ -272,50 +274,30 @@ function doRuns(args, { out, err, cwd }) {
 }
 
 /**
- * The bare `bareloop` menu: `1 export  2 run  3 history  q quit`, then the
- * SAME code path as the sub-command, asking its args line by line. `run-u`,
- * `interview`, `author` and `replay` are NOT wizarded here — a line-at-a-time
- * prompt for `run-u`'s 13 flags (or the others' own argv shapes) would be
- * inventing new interactive UX, not wiring, and that judgement stands. This
- * menu is fixed instead: it now says those four commands exist and how to
- * reach them, rather than implying only three commands do at all.
- * `keysHome` is the home `main` already resolved (`keysForDoor`), handed on so choice 2 reads the
- * SAME config.json (monthly limit, price, key row) as `bareloop run <bundle>` — never resolved twice.
- * @param {any} deps @param {{ out: (s: string) => void, err: (s: string) => void, cwd: string, env: any, now: () => number }} ctx @param {string|undefined} keysHome
+ * The launcher doors (L, PANEL-BUILD.md addendum 2026-10-24): the bare `bareloop` menu and `start | stop | status | install`. All logic is
+ * `src/launcher.js`; this only supplies the home (the SAME one `main` resolved for the keys file and config.json) and the line reader.
+ * `deps.launcher` is the test seam for every OS touch (ports, spawn, kill, opener, clock).
+ * @param {string} cmd 'menu' | 'start' | 'stop' | 'status' | 'install' @param {string[]} rest
+ * @param {any} deps @param {{ out: (s: string) => void, err: (s: string) => void }} io @param {string|undefined} home
+ * @returns {Promise<number>}
  */
-async function runMenu(deps, ctx, keysHome) {
-  const stdin = deps.stdin;
-  const stdout = deps.stdout;
-  const rl = createInterface({ input: stdin, output: stdout });
+async function runLauncher(cmd, rest, deps, io, home) {
+  const rl = createInterface({ input: deps.stdin ?? process.stdin, output: deps.stdout ?? process.stdout });
+  let closed = false;
+  rl.once('close', () => { closed = true; });
+  // a closed stdin answers '' (= the safe default: quit / "no"), never hangs
+  const ask = (/** @type {string} */ q) => (closed ? Promise.resolve('') : Promise.race([
+    rl.question(q),
+    new Promise((resolve) => { rl.once('close', () => resolve('')); }),
+  ]).then(String));
+  const rawEnv = deps.processEnv ?? process.env;
+  const d = { home, ask, paint: makePaint(deps.stdout ?? process.stdout, rawEnv), paintErr: makePaint(deps.stderr ?? process.stderr, rawEnv), ...(deps.launcher ?? {}) };
   try {
-    ctx.out('1 export  2 run  3 history  q quit');
-    ctx.out('(also on the command line, not wizarded here: run-u, interview, author, replay, runs, panel — run `bareloop <name>` with its own flags)');
-    const choice = (await rl.question('> ')).trim().toLowerCase();
-    if (choice === '' || choice === 'q' || choice === 'quit') return 0;
-    if (choice === '1') {
-      const specPath = (await rl.question('job spec path: ')).trim();
-      const registry = (await rl.question('registry dir: ')).trim();
-      const outDir = (await rl.question('out dir: ')).trim();
-      return doExport([specPath, '--registry', registry, '--out', outDir], ctx);
-    }
-    if (choice === '2') {
-      const bundleDir = (await rl.question('bundle dir: ')).trim();
-      const repo = (await rl.question('repo path: ')).trim();
-      const budget = (await rl.question('budget (blank to skip): ')).trim();
-      const wall = (await rl.question('wall minutes (blank to skip): ')).trim();
-      const approve = (await rl.question('approve hash (blank to skip): ')).trim();
-      const args = [bundleDir, '--repo', repo];
-      if (budget) args.push('--budget', budget);
-      if (wall) args.push('--wall', wall);
-      if (approve) args.push('--approve', approve);
-      return await bundleMain(args, { ...ctx, deps, keysHome, parseFlags, printReds });
-    }
-    if (choice === '3') {
-      const bundleDir = (await rl.question('bundle dir: ')).trim();
-      return doHistory([bundleDir], ctx);
-    }
-    ctx.err(`unknown choice ${JSON.stringify(choice)} — one of: 1, 2, 3, q`);
-    return 1;
+    if (cmd === 'start') return await startCmd(io, d);
+    if (cmd === 'stop') return await stopCmd(rest, io, d);
+    if (cmd === 'status') return await statusCmd(io, d);
+    if (cmd === 'install') return await installCmd(io, d);
+    return await menuCmd(io, d);
   } finally {
     rl.close();
   }
@@ -326,7 +308,7 @@ async function runMenu(deps, ctx, keysHome) {
  * code, so `bin/bareloop.mjs` can set `process.exitCode` and let node flush
  * queued stdout on its own (F-something: `process.exit()` can discard it).
  * @param {string[]} argv
- * @param {{ env?: Record<string,string|undefined>, stdout?: any, stderr?: any, cwd?: string, provider?: any, providerFor?: any, judgeProvider?: any, judgeModel?: string|null, now?: () => number, stdin?: any, runlistHome?: string, keysHome?: string }} deps
+ * @param {{ env?: Record<string,string|undefined>, stdout?: any, stderr?: any, cwd?: string, provider?: any, providerFor?: any, judgeProvider?: any, judgeModel?: string|null, now?: () => number, stdin?: any, runlistHome?: string, keysHome?: string, processEnv?: Record<string,string|undefined> }} deps
  * @returns {Promise<number>}
  */
 export async function main(argv, deps = {}) {
@@ -345,7 +327,9 @@ export async function main(argv, deps = {}) {
 
   const [cmd, ...rest] = argv;
   if (keys.warning && cmd && ['run', 'run-u', 'interview', 'author', 'panel'].includes(cmd)) err(`WARNING: ${keys.warning}`);
-  if (!cmd) return runMenu({ ...deps, stdin: deps.stdin ?? process.stdin, stdout }, ctx, keys.home);
+  const launcherHome = keys.home ?? deps.runlistHome;
+  if (!cmd) return runLauncher('menu', [], { ...deps, stdout }, ctx, launcherHome);
+  if (cmd === 'start' || cmd === 'stop' || cmd === 'status' || cmd === 'install') return runLauncher(cmd, rest, { ...deps, stdout }, ctx, launcherHome);
   if (cmd === 'export') return doExport(rest, ctx);
   if (cmd === 'run') return bundleMain(rest, { ...ctx, keysHome: keys.home, parseFlags, printReds });
   if (cmd === 'history') return doHistory(rest, ctx);
@@ -388,6 +372,6 @@ export async function main(argv, deps = {}) {
   // and spine/gate-audit reads over `127.0.0.1` only. `deps.runlistHome`
   // rides through the same injectable seam `run`/`run-u` already use.
   if (cmd === 'panel') return panelMain(rest, { out, err, runlistHome: deps.runlistHome, env: deps.env });
-  err(`unknown command ${JSON.stringify(cmd)} — one of: export, run, history, run-u, interview, author, replay, runs, panel`);
+  err(`unknown command ${JSON.stringify(cmd)} — one of: export, run, history, run-u, interview, author, replay, runs, panel, start, stop, status, install`);
   return 1;
 }

package/src/launcher.js

@@ -0,0 +1,409 @@
+// L (PANEL-BUILD.md addendum 2026-10-24) — the `bareloop` launcher: the bare-`bareloop` menu and `bareloop start | stop | status | install`.
+//
+// No pid file: the panel is FOUND by asking 127.0.0.1:4700..4709 for `GET /api/whoami` (src/panel/server.js), several at once, 300 ms
+// each; a reply with `app === "bareloop"` is a panel. Every call prints the same two header lines first, from {@link buildHeader}.
+// The run counts are the panel's own (`runsListForCount`: the `listRuns` rows' `status.key` and `needs`, plus the schedules that gave up) — never a second spelling of "running" or "needs you".
+// This file owns no arbiter state: it starts/stops the panel process and reads the run list at $0. Every OS touch (spawn, kill, open,
+// port bind, clock, stdin) comes through `deps` so tests inject all of them and never see a real panel.
+
+import {
+  existsSync, statSync, mkdirSync, chmodSync, openSync, closeSync,
+} from 'node:fs';
+import { createServer } from 'node:net';
+import { spawn as realSpawn } from 'node:child_process';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { readConfig, updateConfig, ConfigError } from './config.js';
+import { keysHome, keysFilePath, ensureKeysFile } from './keysfile.js';
+import { openInOs } from './opener.js';
+import { PLAIN } from './tty-colour.js';
+import { runsListForCount, packageVersion, panelUrl } from './panel/server.js';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+/** the first port tried, and how many in a row (4700..4709) */
+export const PORT_START = 4700;
+export const PORT_COUNT = 10;
+const PROBE_TIMEOUT_MS = 300;
+const WAIT_DEADLINE_MS = 10_000;
+const POLL_MS = 100;
+const MIN_NODE_MAJOR = 22;
+const RULE_WIDTH = 56;
+
+/**
+ * @typedef {object} Panel one answered probe
+ * @property {number} port @property {number} pid @property {string} version @property {number} drafts @property {number} schedules
+ * @property {string} url
+ */
+
+/**
+ * @typedef {object} LauncherDeps every OS touch, injectable (a test passes all of them)
+ * @property {string} [home] the bareloop home (`~/.config/bareloop`); undefined = the real one
+ * @property {number} [portStart] @property {number} [portCount]
+ * @property {number[]} [ports] an explicit port list (tests); wins over portStart/portCount
+ * @property {number} [timeoutMs] probe timeout per port
+ * @property {number} [deadlineMs] start/stop wait deadline
+ * @property {string} [nodeVersion] default process.versions.node
+ * @property {typeof fetch} [fetchImpl]
+ * @property {(cmd: string, args: string[], o: object) => any} [spawnFn] default node:child_process spawn
+ * @property {(pid: number, sig: string) => void} [kill] default process.kill
+ * @property {((target: string) => Promise<boolean>)} [open] default the shared OS opener
+ * @property {(port: number) => Promise<boolean>} [portFree] default: try to bind 127.0.0.1:port
+ * @property {(ms: number) => Promise<void>} [sleep]
+ * @property {(question: string) => Promise<string>} [ask] the y/N and menu reader
+ * @property {string} [bareloopBin] default bin/bareloop.mjs of this package
+ * @property {import('./tty-colour.js').Paint} [paint] colour for stdout lines (default none); {@link makePaint} decides TTY / NO_COLOR / TERM
+ * @property {import('./tty-colour.js').Paint} [paintErr] colour for stderr lines (default: `paint`)
+ * @property {number} [now] ms clock for the run list's age rules (default: real time); tests pass their own
+ * @property {string} [platform]
+ * @property {Record<string, string|undefined>} [env] raw env handed to the panel child (default process.env)
+ */
+
+/**
+ * The run counts, from the panel's own `listRuns` rows. `status.key === 'running'` is the panel's word; `needs` is the one tag
+ * {@link import('./panel/server.js').needsStateFor} decides. A part that is 0 still shows.
+ * @param {any[]} rows
+ * @param {number} [gaveUp] schedules that gave up: the panel's Needs-you holds them too
+ * @returns {{running: number, needYou: number, total: number}}
+ */
+export function countRuns(rows, gaveUp = 0) {
+  let running = 0;
+  let needYou = gaveUp;
+  for (const r of rows) {
+    if (r && r.status && r.status.key === 'running') running += 1;
+    if (r && typeof r.needs === 'string' && r.needs !== '') needYou += 1;
+  }
+  return { running, needYou, total: rows.length };
+}
+
+/**
+ * "installed ✓" = the folder exists, config.json is there and reads with no problem, `.env` exists with mode 600, node >= 22.
+ * Otherwise the FIRST missing thing in plain words.
+ * @param {{home?: string, nodeVersion?: string}} o
+ * @returns {{ok: boolean, problem: string|null}}
+ */
+export function installState(o) {
+  const dir = keysHome(o.home);
+  if (!existsSync(dir)) return { ok: false, problem: 'no bareloop folder yet' };
+  const cfg = readConfig({ home: o.home });
+  if (cfg.problem) return { ok: false, problem: 'config.json cannot be read' };
+  if (!cfg.exists) return { ok: false, problem: 'no settings file yet' };
+  const env = keysFilePath(o.home);
+  if (!existsSync(env)) return { ok: false, problem: 'no keys file yet' };
+  try {
+    if ((statSync(env).mode & 0o077) !== 0) return { ok: false, problem: 'the keys file is readable by other users' };
+  } catch { return { ok: false, problem: 'the keys file cannot be read' }; }
+  const major = Number((o.nodeVersion ?? process.versions.node).split('.')[0]);
+  if (!(major >= MIN_NODE_MAJOR)) return { ok: false, problem: `node ${MIN_NODE_MAJOR} or newer is needed` };
+  return { ok: true, problem: null };
+}
+
+/**
+ * Ask 127.0.0.1 across the ports in parallel; a reply with `app === "bareloop"` is a panel. Never throws.
+ * @param {{ports: number[], timeoutMs?: number, fetchImpl?: typeof fetch}} o
+ * @returns {Promise<Panel[]>} in port order
+ */
+export async function probePanels(o) {
+  const f = o.fetchImpl ?? fetch;
+  const ms = o.timeoutMs ?? PROBE_TIMEOUT_MS;
+  const answers = await Promise.all(o.ports.map(async (port) => {
+    try {
+      const res = await f(`${panelUrl(port)}/api/whoami`, { signal: AbortSignal.timeout(ms) });
+      if (!res.ok) return null;
+      const j = /** @type {any} */ (await res.json());
+      if (!j || j.app !== 'bareloop') return null;
+      return /** @type {Panel} */ ({
+        port,
+        pid: Number(j.pid),
+        version: String(j.version ?? ''),
+        drafts: Number(j.drafts) || 0,
+        schedules: Number(j.schedules) || 0,
+        url: panelUrl(port),
+      });
+    } catch { return null; }
+  }));
+  return /** @type {Panel[]} */ (answers.filter((a) => a !== null));
+}
+
+/** @param {LauncherDeps} d @returns {number[]} */
+function portsOf(d) {
+  if (d.ports) return d.ports;
+  const start = d.portStart ?? PORT_START;
+  return Array.from({ length: d.portCount ?? PORT_COUNT }, (_, i) => start + i);
+}
+
+/** @param {LauncherDeps} d @returns {Promise<Panel[]>} */
+function probeAll(d) {
+  return probePanels({ ports: portsOf(d), timeoutMs: d.timeoutMs, fetchImpl: d.fetchImpl });
+}
+
+/**
+ * The header, ONCE per call: the two lines every `bareloop` command prints first, plus the panels the probe found (the commands
+ * reuse them, so nothing is probed twice).
+ * @param {LauncherDeps & {version?: string}} d
+ * @returns {Promise<{lines: string[], panels: Panel[]}>}
+ */
+export async function buildHeader(d) {
+  const version = d.version ?? packageVersion();
+  const panels = await probeAll(d);
+  const inst = installState({ home: d.home, nodeVersion: d.nodeVersion });
+  const P = d.paint ?? PLAIN;
+  const sep = P.grey(' · ');
+  const where = panels.length === 0
+    ? `panel ${P.grey('not running')}`
+    : `panel${panels.length > 1 ? 's' : ''} ${P.green('running')} at ${panels.map((p) => P.cyan(p.url) + (p.version !== version ? P.yellow(` (version ${p.version} — stop and start to use ${version})`) : '')).join(', ')}`;
+  const state = inst.ok ? P.green('installed ✓') : `${P.red('not installed')} — ${inst.problem}, pick ${P.boldCyan('4')} install`;
+  const first = `${P.boldCyan('bareloop')} ${P.grey(version)}${sep}${state}${sep}${where}`;
+  let second;
+  try {
+    const l = runsListForCount({ home: d.home, ...(typeof d.now === 'number' ? { now: d.now } : {}) });
+    const c = countRuns(l.runs, l.gaveUp.length);
+    second = `${P.grey('runs:')} ${c.running > 0 ? P.green(`${c.running} running`) : P.grey(`${c.running} running`)}${sep}`
+      + `${c.needYou > 0 ? P.yellow(`${c.needYou} need you`) : P.grey(`${c.needYou} need you`)}${sep}${c.total} in all`;
+  } catch {
+    second = `${P.grey('runs:')} the run list could not be read`;
+  }
+  // the thin rule frames the header only on a colour terminal (plain output keeps exactly the two lines)
+  const rule = P.on ? [P.grey('─'.repeat(RULE_WIDTH))] : [];
+  return { lines: [...rule, first, second, ...rule], panels };
+}
+
+/**
+ * @param {LauncherDeps & {version?: string}} d
+ * @returns {Promise<string[]>} the two header lines
+ */
+export async function headerLines(d) {
+  return (await buildHeader(d)).lines;
+}
+
+/**
+ * Print the header unless the caller (the menu) already did; hand back the panels either way.
+ * @param {{out: (s: string) => void}} io @param {LauncherDeps & {version?: string}} d @param {{lines: string[], panels: Panel[]}} [shown]
+ */
+async function headerOnce(io, d, shown) {
+  if (shown) return shown;
+  const h = await buildHeader(d);
+  for (const l of h.lines) io.out(l);
+  return h;
+}
+
+/** stderr line, red on a colour terminal @param {{err: (s: string) => void}} io @param {LauncherDeps} d @param {string} text */
+const fail = (io, d, text) => io.err((d.paintErr ?? d.paint ?? PLAIN).red(text));
+
+/** @param {number} n @param {string} one @param {string} many */
+const plural = (n, one, many) => `${n} ${n === 1 ? one : many}`;
+
+/** @param {LauncherDeps} d */
+const sleepOf = (d) => d.sleep ?? ((/** @type {number} */ ms) => new Promise((r) => { setTimeout(r, ms); }));
+
+/** @param {number} port @returns {Promise<boolean>} true when nothing holds 127.0.0.1:port */
+function bindFree(port) {
+  return new Promise((resolve) => {
+    const s = createServer();
+    s.once('error', () => resolve(false));
+    s.listen(port, '127.0.0.1', () => { s.close(() => resolve(true)); });
+  });
+}
+
+/**
+ * `bareloop install` — creates only what is missing, never reads a key value.
+ * @param {{out: (s: string) => void, err: (s: string) => void}} io @param {LauncherDeps & {version?: string}} d @param {{lines: string[], panels: Panel[]}} [shown]
+ * @returns {Promise<number>}
+ */
+export async function installCmd(io, d, shown) {
+  await headerOnce(io, d, shown);
+  const major = Number((d.nodeVersion ?? process.versions.node).split('.')[0]);
+  if (!(major >= MIN_NODE_MAJOR)) {
+    fail(io, d, `bareloop needs node ${MIN_NODE_MAJOR} or newer; this is node ${d.nodeVersion ?? process.versions.node}. Nothing was changed.`);
+    return 1;
+  }
+  const dir = keysHome(d.home);
+  /** @type {string[]} */
+  const made = [];
+  if (!existsSync(dir)) { mkdirSync(dir, { recursive: true, mode: 0o700 }); made.push(`${dir} (only you can open it)`); }
+  const envFile = keysFilePath(d.home);
+  if (ensureKeysFile(d.home)) made.push(`${envFile} (the keys file, only you can read it)`);
+  else {
+    try {
+      if ((statSync(envFile).mode & 0o077) !== 0) { chmodSync(envFile, 0o600); made.push(`${envFile} set so only you can read it`); }
+    } catch { /* unreadable: the header says so */ }
+  }
+  const cfg = readConfig({ home: d.home });
+  if (cfg.problem) {
+    fail(io, d, `${cfg.problem}. Install did not touch it.`);
+    return 1;
+  }
+  if (!cfg.exists) {
+    try { updateConfig({}, { home: d.home }); made.push(`${join(dir, 'config.json')} (your settings)`); } catch (e) {
+      if (!(e instanceof ConfigError)) throw e;
+      fail(io, d, `${e.message}. Install did not touch it.`);
+      return 1;
+    }
+  }
+  if (made.length === 0) { io.out('Already installed, nothing to do.'); return 0; }
+  io.out('Installed. Created:');
+  for (const m of made) io.out(`  ${m}`);
+  return 0;
+}
+
+/**
+ * `bareloop status` — the header, then one line per panel (or `Panel not running.`). Exit 0 running, 3 not running; 0 when the menu ran it.
+ * @param {{out: (s: string) => void}} io @param {LauncherDeps & {version?: string}} d @param {{lines: string[], panels: Panel[]}} [shown] header the menu already printed
+ * @returns {Promise<number>}
+ */
+export async function statusCmd(io, d, shown) {
+  const h = await headerOnce(io, d, shown);
+  if (h.panels.length === 0) {
+    io.out('Panel not running.');
+    // the sub-command's exit says "not running" (3); from the menu the menu itself worked (0)
+    return shown ? 0 : 3;
+  }
+  for (const p of h.panels) {
+    const body = `pid ${p.pid} · version ${p.version} · ${plural(p.drafts, 'draft', 'drafts')} open · ${plural(p.schedules, 'schedule', 'schedules')} on`;
+    io.out(h.panels.length > 1 ? `${p.url} · ${body}` : body);
+  }
+  return 0;
+}
+
+/**
+ * Wait until `port` stops (gone=true) or starts (gone=false) answering whoami as bareloop.
+ * @param {LauncherDeps} d @param {number} port @param {boolean} gone
+ * @returns {Promise<boolean>} false when the deadline passed first
+ */
+async function waitFor(d, port, gone) {
+  const sleep = sleepOf(d);
+  const deadline = d.deadlineMs ?? WAIT_DEADLINE_MS;
+  for (let waited = 0; waited <= deadline; waited += POLL_MS) {
+    const found = await probePanels({ ports: [port], timeoutMs: d.timeoutMs, fetchImpl: d.fetchImpl });
+    if (gone ? found.length === 0 : found.length > 0) return true;
+    await sleep(POLL_MS);
+  }
+  return false;
+}
+
+/**
+ * `bareloop start` — find a running panel first; else start one detached on the first free port 4700..4709, wait until it answers,
+ * open the page.
+ * @param {{out: (s: string) => void, err: (s: string) => void}} io @param {LauncherDeps & {version?: string}} d @param {{lines: string[], panels: Panel[]}} [shown]
+ * @returns {Promise<number>}
+ */
+export async function startCmd(io, d, shown) {
+  const h = await headerOnce(io, d, shown);
+  const P = d.paint ?? PLAIN;
+  const open = d.open ?? ((/** @type {string} */ t) => openInOs(t, { platform: d.platform, underTest: false }));
+  /** @param {string} url @param {string} said */
+  const finish = async (url, said) => {
+    const opened = await open(url);
+    io.out(opened ? `${said} — opening the page.` : `${said} — open it in your browser.`);
+    return 0;
+  };
+  if (h.panels.length > 0) {
+    const rc = await finish(h.panels[0].url, `Panel already running at ${P.cyan(h.panels[0].url)}`);
+    const mine = d.version ?? packageVersion();
+    if (h.panels[0].version !== mine) io.out(P.yellow(`It is version ${h.panels[0].version}; this bareloop is ${mine}. Run bareloop stop, then bareloop start, to use ${mine}.`));
+    return rc;
+  }
+  const free = d.portFree ?? bindFree;
+  const ports = portsOf(d);
+  /** @type {number|null} */
+  let chosen = null;
+  for (const p of ports) { if (await free(p)) { chosen = p; break; } }
+  if (chosen === null) {
+    fail(io, d, `Every port from ${ports[0]} to ${ports[ports.length - 1]} is taken by something else, so the panel was not started.`);
+    return 1;
+  }
+  if (chosen !== ports[0]) io.out(`${ports[0]} is taken, using ${chosen}.`);
+  const dir = keysHome(d.home);
+  try { mkdirSync(dir, { recursive: true, mode: 0o700 }); } catch { /* the log open below reports it */ }
+  const logFile = join(dir, 'panel.log');
+  /** @type {number|null} */
+  let logFd = null;
+  try { logFd = openSync(logFile, 'a'); } catch { logFd = null; }
+  const bin = d.bareloopBin ?? join(HERE, '..', 'bin', 'bareloop.mjs');
+  const platform = d.platform ?? process.platform;
+  const argv = [process.execPath, bin, 'panel', '--port', String(chosen)];
+  const spawnFn = d.spawnFn ?? realSpawn;
+  const [cmd, args] = platform === 'linux' ? ['setsid', argv] : [argv[0], argv.slice(1)];
+  try {
+    const child = spawnFn(cmd, args, { detached: true, stdio: ['ignore', logFd ?? 'ignore', logFd ?? 'ignore'], env: d.env ?? process.env });
+    if (child && typeof child.once === 'function') child.once('error', () => { /* seen as "never answered" below */ });
+    if (child && typeof child.unref === 'function') child.unref();
+  } catch (e) {
+    fail(io, d, `Could not start the panel: ${/** @type {Error} */ (e).message}`);
+    return 1;
+  } finally {
+    if (logFd !== null) { try { closeSync(logFd); } catch { /* the child holds its own copy */ } }
+  }
+  if (!(await waitFor(d, chosen, false))) {
+    fail(io, d, `The panel did not answer within ${(d.deadlineMs ?? WAIT_DEADLINE_MS) / 1000} seconds. See ${logFile}.`);
+    return 1;
+  }
+  return finish(panelUrl(chosen), `${P.green('Panel started')} at ${P.cyan(panelUrl(chosen))}`);
+}
+
+/**
+ * `bareloop stop [--yes]` — SIGTERM the pid of EVERY panel the probe finds (one panel at a time is the rule; no "which one"), wait until each
+ * port stops answering. Drafts are in memory: warn (summed over all found panels) and ask y/N unless `--yes`.
+ * @param {string[]} args
+ * @param {{out: (s: string) => void, err: (s: string) => void}} io @param {LauncherDeps & {version?: string}} d @param {{lines: string[], panels: Panel[]}} [shown]
+ * @returns {Promise<number>}
+ */
+export async function stopCmd(args, io, d, shown) {
+  const bad = args.find((a) => a !== '--yes');
+  if (bad !== undefined) {
+    fail(io, d, `Unknown option ${JSON.stringify(bad)} — bareloop stop takes only --yes. It stops every panel it finds.`);
+    return 1;
+  }
+  const h = await headerOnce(io, d, shown);
+  const yes = args.includes('--yes');
+  const panels = h.panels;
+  if (panels.length === 0) { io.out('Panel not running.'); return 0; }
+  const ask = d.ask;
+  const drafts = panels.reduce((n, p) => n + p.drafts, 0);
+  if (drafts > 0 && !yes) {
+    io.out(`${drafts === 1 ? '1 draft is' : `${drafts} drafts are`} open in the panel and will be lost.`);
+    io.out('Runs keep going. Scheduled runs wait until the panel is started again.');
+    const a = ask ? (await ask('Stop the panel? [y/N] ')).trim().toLowerCase() : '';
+    if (a !== 'y' && a !== 'yes') { io.out('Not stopped.'); return 0; }
+  }
+  const kill = d.kill ?? ((/** @type {number} */ pid, /** @type {string} */ sig) => process.kill(pid, /** @type {NodeJS.Signals} */ (sig)));
+  for (const p of panels) {
+    if (!Number.isInteger(p.pid) || p.pid <= 1) { fail(io, d, `The panel at ${p.url} reported no usable pid, so it was not stopped.`); return 1; }
+    try { kill(p.pid, 'SIGTERM'); } catch (e) {
+      fail(io, d, `Could not stop the panel at ${p.url} (pid ${p.pid}): ${/** @type {Error} */ (e).message}`);
+      return 1;
+    }
+  }
+  for (const p of panels) {
+    if (!(await waitFor(d, p.port, true))) {
+      fail(io, d, `The panel at ${p.url} still answers after ${(d.deadlineMs ?? WAIT_DEADLINE_MS) / 1000} seconds (pid ${p.pid}).`);
+      return 1;
+    }
+  }
+  io.out((d.paint ?? PLAIN).green(panels.length > 1 ? `${panels.length} panels stopped.` : 'Panel stopped.'));
+  return 0;
+}
+
+/**
+ * The bare `bareloop` menu: header, the four choices, one question. Runs the chosen command and returns its exit code.
+ * @param {{out: (s: string) => void, err: (s: string) => void}} io @param {LauncherDeps & {version?: string}} d
+ * @returns {Promise<number>}
+ */
+export async function menuCmd(io, d) {
+  const ask = d.ask;
+  const h = await buildHeader(d);
+  for (const l of h.lines) io.out(l);
+  const P = d.paint ?? PLAIN;
+  if (!P.on) io.out('');
+  const n = (/** @type {string} */ k) => P.boldCyan(k);
+  const items = `${n('1')} start   ${n('2')} stop   ${n('3')} status   ${n('4')} install   ${n('q')} quit`;
+  io.out(P.on ? `  ${items}` : items);
+  const choice = ask ? (await ask(`${P.cyan('>')} `)).trim().toLowerCase() : 'q';
+  // the header is already on screen: the chosen command reuses it instead of printing it a second time
+  if (choice === '1' || choice === 'start') return startCmd(io, d, h);
+  if (choice === '2' || choice === 'stop') return stopCmd([], io, d, h);
+  if (choice === '3' || choice === 'status') return statusCmd(io, d, h);
+  if (choice === '4' || choice === 'install') return installCmd(io, d, h);
+  if (choice === '' || choice === 'q' || choice === 'quit') return 0;
+  fail(io, d, `unknown choice ${JSON.stringify(choice)} — one of: 1, 2, 3, 4, q`);
+  return 1;
+}