bareloop 0.46.1 → 0.47.0

package/src/learn.js

@@ -567,7 +567,7 @@ export function foldCards(cards) {
  * @typedef {object} Ledger
  * @property {1} version
  * @property {Row[]} rows
- * @property {Pending[]} pending     rubric cards held until a human Accept (NOT counted, NOT readable)
+ * @property {Pending[]} pending     holds written by v0.46.x for rubric runs, released by the human Accept (NOT counted, NOT readable); new runs never write one
  * @property {Card[]} suspect        CHECK-SUSPECT cards, listed, newest last
  * @property {Record<string, {at: string, noise: string|null, cards: number, suspect: number, thin: number}>} health  per run (idempotent by run id)
  */
@@ -622,8 +622,9 @@ const byRank = (/** @type {Row} */ a, /** @type {Row} */ b) => b.count - a.count
  * Fold ONE run's cards into the ledger. Pure: returns a new ledger.
  *
  * +1 per RUN per row: the run's own cards are folded into lessons first, and a row whose `runIds` already holds the
- * run id is never counted twice (a resumed run, one id, never double counts). A matching lesson replaces the row's
- * sample, bumps the model count and appends the run id (a row last seen 56+ days ago counts +1 and is read again);
+ * run id is never counted twice (a resumed run, one id, never double counts) but IS refreshed: the resumed leg's card
+ * replaces the sample, lesson, key, lastSeen, hash and place (a leg-1 NEVER FIXED row becomes the leg-2 FIXED one). A
+ * matching lesson replaces the row's sample, bumps the model count and appends the run id (a row last seen 56+ days ago counts +1 and is read again);
  * otherwise it opens a new row at count 1. NEVER FIXED cards count like FIXED ones (RULING 3). A workflow row of
  * another signed hash is never matched here: the new version opens its own rows. Nothing is ever deleted or stamped.
  * @param {Ledger} ledger
@@ -636,16 +637,23 @@ export function countLedger(ledger, { runid, cards, workflow, place, specHash, t
     const rep = group.reduce((a, c) => (c.at >= a.at ? c : a));
     const hit = [...rows].sort(byRank).find((r) => r.workflow === workflow && !otherJobVersion(r, workflow, specHash) && cardsMatch(rep, r.sample).match);
     if (hit) {
-      if (hit.runIds.includes(runid)) continue;
-      hit.count += 1;
-      hit.models[rep.model ?? 'unknown'] = (hit.models[rep.model ?? 'unknown'] ?? 0) + 1;
-      hit.runIds.push(runid);
-      hit.sample = rep;
-      hit.lesson = lessonOf(rep);
-      hit.key = keyOfCard(rep);
-      hit.lastSeen = rep.at;
-      hit.specHash = specHash;
-      hit.place = place ?? hit.place;
+      // A row already holding this run id is the run's OWN row (a resumed leg re-reads the whole spine): refresh it from
+      // the new card, but the count, the model tally and the run id stay one per run.
+      const own = hit.runIds.includes(runid);
+      if (!own) {
+        hit.count += 1;
+        hit.models[rep.model ?? 'unknown'] = (hit.models[rep.model ?? 'unknown'] ?? 0) + 1;
+        hit.runIds.push(runid);
+      }
+      // a refresh never steps the row back: re-folding an older run's cards must not replace a newer run's sample
+      if (!own || rep.at >= hit.lastSeen) {
+        hit.sample = rep;
+        hit.lesson = lessonOf(rep);
+        hit.key = keyOfCard(rep);
+        hit.lastSeen = rep.at;
+        hit.specHash = specHash;
+        hit.place = place ?? hit.place;
+      }
     } else {
       let id = rowId(rep);
       for (let n = 2; rows.some((r) => r.id === id); n += 1) id = `${rowId(rep)}-${n}`;
@@ -712,8 +720,8 @@ export function climb(rows) {
 }
 
 /**
- * A rubric run's cards are HELD, not counted, until a human Accept (the existing quarantine is the rule). Replaces
- * an earlier hold for the same run id (a resumed run re-derives its cards). Pure.
+ * Hold a run's cards until a human Accept. NO LONGER CALLED for new runs (v1.112: a rubric run's lessons count at run
+ * end); kept so a hold already in a ledger file still has a writer for tests and a reader in {@link releasePending}. Pure.
  * @param {Ledger} ledger
  * @param {{runid: string, cards: Card[], workflow: string, place: string|null, specHash: string|null, at: string}} o
  * @param {Date} now @returns {Ledger}
@@ -725,7 +733,7 @@ export function holdPending(ledger, { runid, cards, workflow, place, specHash, a
 }
 
 /**
- * The human Accept releases a held rubric run: its cards count now (trust `rubric`). Only forward, only here. A hold
+ * The human Accept releases an OLD hold (written by v0.46.x; new runs write none): its cards count now (trust `rubric`). Only forward, only here. A hold
  * older than 60 days is dropped uncounted. Idempotent (no hold = nothing to do; run ids stop a double count).
  * @param {Ledger} ledger @param {string} runid @param {Date} now
  * @returns {{ledger: Ledger, released: number}}

package/src/learnstore.js

@@ -9,7 +9,7 @@ import { existsSync, mkdirSync, readFileSync, realpathSync, renameSync, writeFil
 import { join, dirname } from 'node:path';
 import { keysHome } from './keysfile.js';
 import { readConfig } from './config.js';
-import { emptyLedger, redactDeep, countLedger, holdPending, releasePending, recordHealth, buildCards, placeOf, renderHints } from './learn.js';
+import { emptyLedger, redactDeep, countLedger, releasePending, recordHealth, buildCards, placeOf, renderHints } from './learn.js';
 import { stageQuestionsByName } from './stagewords.js';
 
 /**
@@ -57,9 +57,8 @@ export function writeLedger(ledger, home) {
 }
 
 /**
- * Fold ONE finished run into the ledger on disk: a deterministic job's cards COUNT now; a rubric job's cards are HELD
- * until a human Accept (they are written to `pending`, never counted, never readable). The run's health line is recorded
- * either way. Never throws on a bad ledger file: it reports `problem` and writes nothing.
+ * Fold ONE finished run into the ledger on disk: every run's cards COUNT now, rubric jobs too (trust kept on new rows;
+ * v1.112). `held` is always 0 (kept in the shape for callers). The run's health line is recorded. Never throws on a bad ledger file: it reports `problem` and writes nothing.
  * @param {{home?: string, runid: string, build: import('./learn.js').CardBuild, workflow: string, place: string|null, specHash: string|null, trust: 'deterministic'|'rubric', at: string, now?: Date}} o
  * @returns {{wrote: boolean, counted: number, held: number, problem: string|null}}
  */
@@ -67,23 +66,16 @@ export function foldRunIntoLedger({ home, runid, build, workflow, place, specHas
   const cur = readLedger(home);
   if (cur.problem) return { wrote: false, counted: 0, held: 0, problem: cur.problem };
   let L = cur.ledger;
-  let counted = 0;
-  let held = 0;
-  if (trust === 'rubric') {
-    L = holdPending(L, { runid, cards: build.cards, workflow, place, specHash, at }, now);
-    held = build.cards.length;
-  } else {
-    const before = L.rows.reduce((n, r) => n + r.runIds.filter((x) => x === runid).length, 0);
-    L = countLedger(L, { runid, cards: build.cards, workflow, place, specHash, trust, now });
-    counted = L.rows.reduce((n, r) => n + r.runIds.filter((x) => x === runid).length, 0) - before;
-  }
+  const before = L.rows.reduce((n, r) => n + r.runIds.filter((x) => x === runid).length, 0);
+  L = countLedger(L, { runid, cards: build.cards, workflow, place, specHash, trust, now });
+  const counted = L.rows.reduce((n, r) => n + r.runIds.filter((x) => x === runid).length, 0) - before;
   L = recordHealth(L, runid, build, at, now);
   writeLedger(L, home);
-  return { wrote: true, counted, held, problem: null };
+  return { wrote: true, counted, held: 0, problem: null };
 }
 
 /**
- * The human Accept at the review door: release the run's held rubric cards so they count (only forward, only here).
+ * The human Accept at the review door: release a hold an older version wrote for the run so it counts (new runs write none; only forward, only here).
  * @param {{home?: string, runid: string, now?: Date}} o
  * @returns {{released: number, problem: string|null}}
  */
@@ -123,7 +115,7 @@ const realOr = (p) => { try { return realpathSync(p); } catch { return p; } };
 
 /**
  * THE RUN-END TALLY ($0, code only, no model): turn the finished run's whole record into cards and fold them into the
- * ledger (a rubric job's are held until Accept). Called once from the one engine's run-end block (src/userrun.js
+ * ledger (a rubric job's count too, trust kept). Called once from the one engine's run-end block (src/userrun.js
  * `execute`, shared by the panel, the CLI and the bundle runner), inside its own try/catch: it is a record, never a verdict,
  * and can never change a run's outcome, exit code or spend. It runs whether the hints setting is on or off.
  * @param {{home?: string, runid: string, events: any[], auditFiles?: string[], spec: any, specHash: string|null, workdir: string|null, trust: 'deterministic'|'rubric', now?: Date}} o

package/src/opener.js

@@ -0,0 +1,30 @@
+// The ONE "open this in the OS" helper: `xdg-open` (linux) / `open` (macOS), argv array, no shell, detached.
+// Settings' "Open keys folder" and the `bareloop start` launcher both use it. Another OS or a failed spawn
+// resolves `false` (the caller then shows the path/URL as text); it never throws.
+import { spawn as realSpawn } from 'node:child_process';
+
+/**
+ * @param {string} target a folder path or a URL
+ * @param {{ platform?: string, spawnFn?: ((cmd: string, args: string[], o: object) => any)|null, underTest?: boolean }} [opts]
+ *   `spawnFn: null` = no opener at all (resolves false); undefined = the real spawn, unless `underTest`, which spawns nothing
+ *   unless a test injected one
+ * @returns {Promise<boolean>} true once the opener process has started
+ */
+export function openInOs(target, opts = {}) {
+  const platform = opts.platform ?? process.platform;
+  const cmd = platform === 'linux' ? 'xdg-open' : (platform === 'darwin' ? 'open' : null);
+  const opener = opts.spawnFn === undefined ? (opts.underTest ? null : realSpawn) : opts.spawnFn;
+  if (!cmd || !opener) return Promise.resolve(false);
+  return new Promise((resolve) => {
+    let child;
+    try { child = opener(cmd, [target], { detached: true, stdio: 'ignore' }); } catch { resolve(false); return; }
+    let settled = false;
+    child.once('error', () => { if (!settled) { settled = true; resolve(false); } });
+    child.once('spawn', () => {
+      if (settled) return;
+      settled = true;
+      if (typeof child.unref === 'function') child.unref();
+      resolve(true);
+    });
+  });
+}

package/src/panel/authorroutes.js

@@ -432,7 +432,7 @@ export function createAuthorRoutes(opts) {
   }
 
   return {
-    handle, sessions, headless, startSession, envNow, spawnFn, bareloopBin,
+    handle, sessions, headless, openDrafts: () => [...sessions.values()].filter((s) => !TERMINAL_PHASES.has(s.state.phase)).length, startSession, envNow, spawnFn, bareloopBin,
     /** a headless session the starter has removed from disk leaves its map too @param {string} id */
     forgetHeadless: (id) => { headless.delete(id); },
   };

package/src/panel/server.js

@@ -82,13 +82,24 @@ const HERE = dirname(fileURLToPath(import.meta.url));
 /** bareloop's own version, from its package.json (read each time the page is served); 'unknown' if it cannot be read, never a guess
  * @param {string} [file] test seam: another package.json
  * @returns {string} */
-function packageVersion(file = join(HERE, '..', '..', 'package.json')) {
+export function packageVersion(file = join(HERE, '..', '..', 'package.json')) {
   try {
     const v = JSON.parse(readFileSync(file, 'utf8')).version;
     return typeof v === 'string' && v.length > 0 ? v : 'unknown';
   } catch { return 'unknown'; }
 }
 
+/**
+ * `GET /api/whoami` body. `drafts` counts the person's drafting sessions that are not finished (the headless scheduled ones are not drafts).
+ * @param {{ port: number, packageJsonPath?: string, authorRoutes?: ReturnType<typeof createAuthorRoutes>, schedules?: ReturnType<typeof createScheduleDoor> }} opts
+ */
+function whoamiPayload(opts) {
+  const drafts = opts.authorRoutes ? opts.authorRoutes.openDrafts() : 0;
+  let schedules = 0;
+  try { schedules = opts.schedules ? opts.schedules.scan().length : 0; } catch { schedules = 0; }
+  return { app: 'bareloop', version: packageVersion(opts.packageJsonPath), pid: process.pid, port: opts.port, drafts, schedules };
+}
+
 /** Largest POST body the panel buffers (job cards are short prose); a bigger one is refused with 413. */
 const MAX_BODY_BYTES = 1024 * 1024;
 
@@ -1056,6 +1067,25 @@ export function runsListPayload(opts = {}) {
   return { runs, jobs, scheduled, gaveUp, limits: RUNS_LIST_LIMITS };
 }
 
+/**
+ * The runs list as the panel builds it, for a caller with no panel running (the launcher header): the same `runsListPayload` over a
+ * schedule door built read-only (no scheduler, no timer), so Needs you = the rows tagged `needs` + the schedules that gave up, ONE owner.
+ * @param {{ home?: string, now?: number, env?: Record<string, string|undefined> }} [opts]
+ * @returns {{ runs: any[], gaveUp: any[] }}
+ */
+export function runsListForCount(opts = {}) {
+  const home = opts.home;
+  const schedules = createScheduleDoor({
+    ...(home ? { home } : {}),
+    jobRuns: (job) => jobRunsOf(job, { home }),
+    startFrom: (runid) => getStartFrom(runid, { home }),
+    jobOfRun: (runid) => readRunList({ home }).rows.find((r) => r && r.runid === runid)?.job ?? null,
+    rowsFor: () => rowsForHome(keysHome(home), keysForDoor({ env: opts.env ?? {}, keysHome: home }).env),
+  });
+  const { runs, gaveUp } = runsListPayload({ home, ...(opts.now !== undefined ? { now: opts.now } : {}), schedules });
+  return { runs, gaveUp };
+}
+
 /**
  * The run's DRAFTING PART (hamr 2026-10-06, option A), or null: it exists only when the run came out of a panel
  * session whose drafting log carries a metered call (src/draftspend.js, `draftingPartFor`) and the spine carries the
@@ -3827,6 +3857,13 @@ export function handleRequest(req, res, opts) {
     return;
   }
 
+  // L (PANEL-BUILD.md addendum 2026-10-24): who is answering here — the launcher's probe (`bareloop start|stop|status`). Read-only, no token;
+  // the Host guard above already holds. `drafts` = open drafting sessions (in memory, lost on stop); `schedules` = jobs with a schedule on.
+  if (pathname === '/api/whoami') {
+    send(200, whoamiPayload(opts));
+    return;
+  }
+
   if (pathname === '/api/runs') { send(200, runsListPayload({ home: opts.home, schedules: opts.schedules })); return; }
 
   const runMatch = /^\/api\/runs\/([^/]+)(\/(audit|job|rounds|result|download))?$/.exec(pathname);
@@ -3895,6 +3932,15 @@ export function handleRequest(req, res, opts) {
   sendText(res, 404, 'not found');
 }
 
+/**
+ * The ONE spelling of the panel's own address (the launcher prints and opens it too).
+ * @param {number} boundPort
+ * @returns {string}
+ */
+export function panelUrl(boundPort) {
+  return `http://127.0.0.1:${boundPort}`;
+}
+
 /**
  * Start the panel server. Binds `127.0.0.1` ONLY. A taken port is a LOUD,
  * non-zero-exit failure — this never falls back to another port (see file
@@ -4057,7 +4103,7 @@ export async function panelMain(argv, ctx) {
   }
   try {
     const { port: boundPort } = await createPanelServer({ port, home: ctx.runlistHome, env: ctx.env });
-    ctx.out(`bareloop panel — read-only, http://127.0.0.1:${boundPort} (Ctrl-C to stop)`);
+    ctx.out(`bareloop panel — read-only, ${panelUrl(boundPort)} (Ctrl-C to stop)`);
     // never resolves on its own — the process stays up until killed, same
     // shape any other long-running dev server takes.
     await new Promise(() => {});

package/src/panel/settingsroutes.js

@@ -21,7 +21,7 @@ import {
   readConfig, updateConfig, ConfigError, providerFieldProblem, cleanBaseUrl, modelsProblem,
 } from '../config.js';
 import { spendSummary, monthlyLimitOf } from '../monthly.js';
-import { spawn as realSpawn } from 'node:child_process';
+import { openInOs } from '../opener.js';
 import { loadKeysEnv, keysFilePath, keysHome, filledKeyNames, ensureKeysFile } from '../keysfile.js';
 import { SHAPES } from '../providershapes.js';
 import { keyRows, effectiveModels, usableKey, rowNamesOf } from '../providerrows.js';
@@ -208,24 +208,10 @@ export function createSettingsRoutes(opts) {
     }
     const dir = keysHome(opts.home);
     const cannot = () => reply(200, { ok: true, opened: false, path: dir });
-    const platform = opts.platform ?? process.platform;
-    const cmd = platform === 'linux' ? 'xdg-open' : (platform === 'darwin' ? 'open' : null);
     // under a test process (NODE_ENV=test or `node --test`) nothing is spawned unless a test injected an opener
     const underTest = process.env.NODE_ENV === 'test' || process.env.NODE_TEST_CONTEXT !== undefined;
-    const opener = opts.openFolderSpawn ?? (underTest ? null : realSpawn);
-    if (!cmd || !opener) return Promise.resolve(cannot());
-    return new Promise((resolve) => {
-      let child;
-      try { child = opener(cmd, [dir], { detached: true, stdio: 'ignore' }); } catch { resolve(cannot()); return; }
-      let settled = false;
-      child.once('error', () => { if (!settled) { settled = true; resolve(cannot()); } });
-      child.once('spawn', () => {
-        if (settled) return;
-        settled = true;
-        if (typeof child.unref === 'function') child.unref();
-        resolve(reply(200, { ok: true, opened: true, path: dir }));
-      });
-    });
+    return openInOs(dir, { platform: opts.platform, spawnFn: opts.openFolderSpawn, underTest })
+      .then((opened) => (opened ? reply(200, { ok: true, opened: true, path: dir }) : cannot()));
   }
 
   /**

package/src/tty-colour.js

@@ -0,0 +1,27 @@
+// ONE place for terminal colour (the launcher's header, menu and messages). Colours wrap words and never change them: with colour off
+// every helper returns its text untouched, so plain-text readers (tests, pipes, logs) see the same words.
+
+const wrap = (/** @type {string} */ code) => (/** @type {string} */ s) => `\x1b[${code}m${s}\x1b[0m`;
+const id = (/** @type {string} */ s) => s;
+
+/**
+ * @typedef {object} Paint
+ * @property {boolean} on
+ * @property {(s: string) => string} grey @property {(s: string) => string} green @property {(s: string) => string} yellow
+ * @property {(s: string) => string} red @property {(s: string) => string} cyan @property {(s: string) => string} boldCyan
+ */
+
+/**
+ * Colour is on only for a terminal: the stream says it is a TTY, `NO_COLOR` is empty/unset, and `TERM` is not `dumb`.
+ * @param {{isTTY?: boolean}|undefined} stream the output stream (process.stdout)
+ * @param {Record<string, string|undefined>} [env]
+ * @returns {Paint}
+ */
+export function makePaint(stream, env = process.env) {
+  const on = Boolean(stream && stream.isTTY) && !(env.NO_COLOR ?? '') && env.TERM !== 'dumb';
+  if (!on) return { on, grey: id, green: id, yellow: id, red: id, cyan: id, boldCyan: id };
+  return { on, grey: wrap('90'), green: wrap('32'), yellow: wrap('33'), red: wrap('31'), cyan: wrap('36'), boldCyan: wrap('1;36') };
+}
+
+/** the no-colour paint, the default when a caller passes none */
+export const PLAIN = makePaint(undefined, {});

package/src/userrun.js

@@ -1307,7 +1307,7 @@ async function execute(ctx) {
     if (RULING.decision !== 'rerun') {
       out(`\n${RULING.decision === 'accept' ? 'ACCEPTED' : 'PAUSED'} — the verdict this run minted (${doorRecord.outcome}) is UNTOUCHED; what you answered is what happens to the work.`);
       if (RULING.decision === 'accept') {
-        // Cross-run learnings: the human Accept is what releases a held rubric run's lessons so they count (forward only; a rerun or a
+        // Cross-run learnings: the human Accept releases a hold an older version wrote for a rubric run (new runs count at run end) (forward only; a rerun or a
         // pause never does). Its own try/catch: a record, never a verdict.
         if (cfgOn && DOOR !== null) {
           try { releaseRun({ home: cfgHome, runid: DOOR.includes('/') || DOOR.endsWith('.jsonl') ? basename(DOOR).replace(/^u-/, '').replace(/\.jsonl$/, '') : DOOR }); } catch (/** @type {any} */ e) { err(`WARNING: could not release this run's lessons in the learnings ledger (${redactSecrets(String(e?.message ?? e)).split('\n')[0]}).`); }
@@ -2025,7 +2025,7 @@ async function execute(ctx) {
     } catch (/** @type {any} */ e) { err(`WARNING: could not settle this run's claim in ~/.config/bareloop/runs.jsonl (${e.message}) — the next run settles it once this process is gone.`); }
   }
   // The run-end tally of cross-run learnings ($0, code only, no model): the whole spine (all legs) and the gate audit become cards
-  // folded into the ONE ledger (a rubric job's are held until the human Accept). Its own try/catch, like the settle above: a
+  // folded into the ONE ledger (a rubric job's count at run end too). Its own try/catch, like the settle above: a
   // record, never a verdict — a failure prints one WARNING line and can never change the outcome, the exit code or the spend.
   // `execute` is shared by the panel, the CLI and the bundle runner, so this is the ONE call site. It runs with the hints setting
   // on or off (OFF only means the planner is handed nothing). With no config home (a test with an injected env) it writes nothing.

package/types/cli.d.ts

@@ -3,7 +3,7 @@
  * 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 function main(argv: string[], deps?: {
@@ -19,4 +19,5 @@ export function main(argv: string[], deps?: {
     stdin?: any;
     runlistHome?: string;
     keysHome?: string;
+    processEnv?: Record<string, string | undefined>;
 }): Promise<number>;

package/types/launcher.d.ts

@@ -0,0 +1,234 @@
+/**
+ * @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: any[], gaveUp?: number): {
+    running: number;
+    needYou: number;
+    total: number;
+};
+/**
+ * "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: {
+    home?: string;
+    nodeVersion?: string;
+}): {
+    ok: boolean;
+    problem: string | 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 function probePanels(o: {
+    ports: number[];
+    timeoutMs?: number;
+    fetchImpl?: typeof fetch;
+}): Promise<Panel[]>;
+/**
+ * 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 function buildHeader(d: LauncherDeps & {
+    version?: string;
+}): Promise<{
+    lines: string[];
+    panels: Panel[];
+}>;
+/**
+ * @param {LauncherDeps & {version?: string}} d
+ * @returns {Promise<string[]>} the two header lines
+ */
+export function headerLines(d: LauncherDeps & {
+    version?: string;
+}): Promise<string[]>;
+/**
+ * `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 function installCmd(io: {
+    out: (s: string) => void;
+    err: (s: string) => void;
+}, d: LauncherDeps & {
+    version?: string;
+}, shown?: {
+    lines: string[];
+    panels: Panel[];
+}): Promise<number>;
+/**
+ * `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 function statusCmd(io: {
+    out: (s: string) => void;
+}, d: LauncherDeps & {
+    version?: string;
+}, shown?: {
+    lines: string[];
+    panels: Panel[];
+}): Promise<number>;
+/**
+ * `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 function startCmd(io: {
+    out: (s: string) => void;
+    err: (s: string) => void;
+}, d: LauncherDeps & {
+    version?: string;
+}, shown?: {
+    lines: string[];
+    panels: Panel[];
+}): Promise<number>;
+/**
+ * `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 function stopCmd(args: string[], io: {
+    out: (s: string) => void;
+    err: (s: string) => void;
+}, d: LauncherDeps & {
+    version?: string;
+}, shown?: {
+    lines: string[];
+    panels: Panel[];
+}): Promise<number>;
+/**
+ * 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 function menuCmd(io: {
+    out: (s: string) => void;
+    err: (s: string) => void;
+}, d: LauncherDeps & {
+    version?: string;
+}): Promise<number>;
+/** the first port tried, and how many in a row (4700..4709) */
+export const PORT_START: 4700;
+export const PORT_COUNT: 10;
+/**
+ * one answered probe
+ */
+export type Panel = {
+    port: number;
+    pid: number;
+    version: string;
+    drafts: number;
+    schedules: number;
+    url: string;
+};
+/**
+ * every OS touch, injectable (a test passes all of them)
+ */
+export type LauncherDeps = {
+    /**
+     * the bareloop home (`~/.config/bareloop`); undefined = the real one
+     */
+    home?: string | undefined;
+    portStart?: number | undefined;
+    portCount?: number | undefined;
+    /**
+     * an explicit port list (tests); wins over portStart/portCount
+     */
+    ports?: number[] | undefined;
+    /**
+     * probe timeout per port
+     */
+    timeoutMs?: number | undefined;
+    /**
+     * start/stop wait deadline
+     */
+    deadlineMs?: number | undefined;
+    /**
+     * default process.versions.node
+     */
+    nodeVersion?: string | undefined;
+    fetchImpl?: typeof fetch | undefined;
+    /**
+     * default node:child_process spawn
+     */
+    spawnFn?: ((cmd: string, args: string[], o: object) => any) | undefined;
+    /**
+     * default process.kill
+     */
+    kill?: ((pid: number, sig: string) => void) | undefined;
+    /**
+     * default the shared OS opener
+     */
+    open?: ((target: string) => Promise<boolean>) | undefined;
+    /**
+     * default: try to bind 127.0.0.1:port
+     */
+    portFree?: ((port: number) => Promise<boolean>) | undefined;
+    sleep?: ((ms: number) => Promise<void>) | undefined;
+    /**
+     * the y/N and menu reader
+     */
+    ask?: ((question: string) => Promise<string>) | undefined;
+    /**
+     * default bin/bareloop.mjs of this package
+     */
+    bareloopBin?: string | undefined;
+    /**
+     * colour for stdout lines (default none); {@link makePaint} decides TTY / NO_COLOR / TERM
+     */
+    paint?: import("./tty-colour.js").Paint | undefined;
+    /**
+     * colour for stderr lines (default: `paint`)
+     */
+    paintErr?: import("./tty-colour.js").Paint | undefined;
+    /**
+     * ms clock for the run list's age rules (default: real time); tests pass their own
+     */
+    now?: number | undefined;
+    platform?: string | undefined;
+    /**
+     * raw env handed to the panel child (default process.env)
+     */
+    env?: Record<string, string | undefined> | undefined;
+};