bareloop 0.46.0 → 0.47.0

package/src/panel/index.html

@@ -2910,7 +2910,17 @@
       });
     });
     if(sum){
-      var first = items.length ? (Array.isArray(items[0].hints) ? items[0].hints.length : 0) : 0;
+      // count DISTINCT hints across the draft and replan blocks: the same ledger row (ids[i], parallel to hints[i]) handed twice is one hint
+      var seen = {};
+      var first = 0;
+      items.forEach(function(it){
+        var hs = Array.isArray(it.hints) ? it.hints : [];
+        var byId = Array.isArray(it.ids) && it.ids.length === hs.length;
+        hs.forEach(function(h, i){
+          var key = byId ? "id:" + it.ids[i] : "n:" + it.phase + ":" + h.n;
+          if(!seen[key]){ seen[key] = true; first += 1; }
+        });
+      });
       var label = items.length ? head + " \u00B7 " + first + (first === 1 ? " hint" : " hints") : head;
       // no arrow (hamr 2026-10-23): the state chip leads; aria-expanded carries open/closed. The same `[✓] word` state markup the schedule/step headers wear (stateDotHTML), then the plain-words title
       var paint = function(){ sum.innerHTML = stateDotHTML(glyphClass("\u2713"), "learnings", "audit-learnings-state") + " " + escapeXml(label); };
@@ -4939,6 +4949,8 @@
         var suffix = reach.modelListed === false ? " (model not listed)" : "";
         return { keyOk: true, ok: true, text: "[✓] " + r.envKey + " found · " + modelId + " reachable" + suffix };
       }
+      // a blank Base URL is nothing to probe, not flakiness: say the server's own plain sentence (src/modellist.js owns it)
+      if(reach.status === "no-base-url" && reach.note) return { keyOk: true, ok: false, text: "[✗] " + reach.note };
       return { keyOk: true, ok: false, text: reachStatusText(reach.status) };
     }
     function refreshModelStatus(){

package/src/panel/schedulestart.js

@@ -46,6 +46,11 @@ export function perFireSpec(schedule, cause) {
   if (jobSpecHash(schedule.spec) !== schedule.specHash) return { ok: false, why: 'The saved schedule no longer matches what you signed. Nothing started.' };
   const spec = JSON.parse(JSON.stringify(schedule.spec));
   if (cause.kind === 'file') {
+    // the card text is `label: value` lines: a name holding a line break would read back as ANOTHER Inputs line, and edge whitespace
+    // is trimmed to a path that does not exist (a leading space in the file name sits mid-path and is harmless). Refused with its reason, never rewritten.
+    if (/[\r\n]/.test(cause.path) || cause.path !== cause.path.trim()) {
+      return { ok: false, why: `The file name ${JSON.stringify(cause.path)} has a line break or a space at its end, which the job form cannot carry. Rename the file. Nothing started.` };
+    }
     const first = Array.isArray(spec.inputs) ? spec.inputs[0] : null;
     if (!first) return { ok: false, why: 'The saved schedule has no input for the file to replace. Nothing started.' };
     spec.inputs = [{ ...first, value: cause.path }, ...spec.inputs.slice(1)];

package/src/panel/server.js

@@ -68,7 +68,7 @@ import { SHAPES } from '../providershapes.js';
 import { resolveProvider } from '../providers.js';
 import { readResume, checkpointAgeGate, CHECKPOINT_OUTCOMES } from '../reuse.js';
 import {
-  statusFor, partStatusFor, GOAL_MET_LINE, doorViewOf, ACTOR_MARKER, DOOR_WORDS,
+  statusFor, partStatusFor, GOAL_MET_LINE, doorViewOf, ACTOR_MARKER, DOOR_WORDS, isReusableGreen,
 } from './status.js';
 import { thinkingJobText } from '../thinking.js';
 import { judgedFilesOf, lineRules, stepFileRel, proseNotCheckedItems } from '../rubricstep.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;
 
@@ -542,7 +553,7 @@ function endedBase(summary, death, o) {
     if (o.destinationRefused) {
       // Reuse workflow only on a run that earned its green (hamr 2026-10-08, as below); every ending offers Reuse workflow
       // (withReuseAction adds it) and is told to change the job
-      const earned = outcome === 'green';
+      const earned = isReusableGreen(outcome);
       return {
         reason: 'Goal met, but the output could not be delivered.',
         next: earned ? 'Fix the destination, then Reuse workflow.' : CHANGE,
@@ -550,10 +561,9 @@ function endedBase(summary, death, o) {
         actions: earned ? REUSE : [],
       };
     }
-    // hamr 2026-10-08: already-green (the check passed before any work) is not a reusable job — only a run that
-    // earned its green offers Reuse workflow; every ending offers Reuse workflow (withReuseAction adds it). `satisfied` is a
-    // close VERDICT, never a run outcome (ralph and the job-end emitters write `green`), so it rides with already-green.
-    if (outcome !== 'green') return { reason: 'Goal met.', next: CHANGE, line: GOAL_MET_LINE, actions: [] };
+    // a reusable green (isReusableGreen: green or already-green, hamr 2026-10-15) says nothing is left to do; every ending offers
+    // Reuse workflow (withReuseAction adds it). `satisfied` is a close VERDICT, never a run outcome, so it is not one.
+    if (!isReusableGreen(outcome)) return { reason: 'Goal met.', next: CHANGE, line: GOAL_MET_LINE, actions: [] };
     return { reason: 'Goal met.', next: 'Nothing to do.', line: GOAL_MET_LINE, actions: REUSE };
   }
   if (outcome === 'cap-halt') {
@@ -1057,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
@@ -1530,7 +1559,8 @@ function scheduleExtrasFor(runid, job, rows, nos, opts, view) {
             }
             const got = hit ?? fallback;
             const no = got ? nos.get(got.r.runid) : undefined;
-            const word = got ? summarizeRow(got.r).status?.word : undefined;
+            // events: a fire refused at the run-start fetch has no spine, only its settled event; without them it has no status word
+            const word = got ? summarizeRow(got.r, Date.now(), undefined, readRunList(opts).events).status?.word : undefined;
             lastWords = `last ${dateTimeWords(Number(lastRow.at))}${no ? ` · run-${no}` : ''}${word ? ` · ${word}` : ''}${got?.rec.catchUp === true ? ' · catch-up' : ''}`;
           } else {
             lastWords = `last ${dateTimeWords(Number(lastRow.at))} · ${skippedWords(lastRow, true)}`;
@@ -3514,7 +3544,7 @@ export function getStartFrom(runid, opts = {}) {
     // T D.2: a SCHEDULED run's green reads `green-held` until the person accepts it, so that same refusal holds it unchanged
     outcome: (() => {
       const o = legsOf(records).at(-1)?.outcome ?? null;
-      return o === 'green' && heldScheduled(records, triggerRecordOf(row)) ? 'green-held' : o;
+      return isReusableGreen(o) && heldScheduled(records, triggerRecordOf(row)) ? 'green-held' : o;
     })(),
     card,
     from: 'signed job',
@@ -3579,7 +3609,7 @@ export function listReuseJobs(opts = {}) {
     try { records = parseJsonl(row.spine).records; } catch { continue; }
     const outcome = legsOf(records).at(-1)?.outcome ?? null;
     // a real green or an already-green (hamr 2026-10-15: if it is already fixed and nothing is to be done, it is green and can be reused)
-    if (outcome !== 'green' && outcome !== 'already-green') continue;
+    if (!isReusableGreen(outcome)) continue;
     if (heldScheduled(records, triggerRecordOf(row))) continue; // T D.2: a scheduled green waits for the person's Accept
     const signed = signedSpecForRun(row, records);
     if (!signed) continue;
@@ -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/panel/status.js

@@ -20,6 +20,17 @@ import { capKindOf } from '../legs.js';
 /** the sentence a passed run carries as its reason (the Ended block's `line`) */
 export const GOAL_MET_LINE = 'goal met';
 
+/**
+ * ONE spelling of "this run's outcome is a green that can be reused" (the Reuse picker, the Reuse start/prefill, the Ended block's
+ * next line). hamr 2026-10-15: an `already-green` (fixed before any work) counts. `satisfied` is a close verdict, never a run outcome.
+ * The SCHEDULE gate (schedules.js greenFor) deliberately stays on a real `green` only (T3).
+ * @param {string|null|undefined} outcome
+ * @returns {boolean}
+ */
+export function isReusableGreen(outcome) {
+  return outcome === 'green' || outcome === 'already-green';
+}
+
 /** @typedef {'running'|'waiting'|'passed'|'failed'|'capped'|'stopped'|'died'} StatusKey */
 
 /** the table: key -> sign + word */

package/src/stagewords.js

@@ -2,6 +2,24 @@
 // src/panel/server.js (verbatim) so the Audit/step map AND the learnings cards read the same sentence from the same
 // code — a second spelling is how two screens come to disagree about one check. Pure; no file IO, no model.
 
+/** the genre-owned noun for the count a TYPES-genre typecheck stage measures (see {@link stageQuestionText}) */
+export const GENRE_WHAT = Object.freeze({ TYPES: 'type errors' });
+
+/** `cmd`+`args`, as a comparable key — the one signal (besides `kind`
+ * itself) that two stages measure the SAME command's output, used to tell a
+ * genuine typecheck stage apart from the TYPES genre's other `lower-is-
+ * better`/`baseline: 0` stage (the failing-test-count half of `suite-green`'s
+ * "two assertions"), which shares that stage's own shape but not its
+ * population. `null` for a stage whose `cmd` isn't a non-empty string —
+ * never matches anything, so it never falsely suppresses a real typecheck
+ * question.
+ * @param {any} params @returns {string|null} */
+export function cmdKey(params) {
+  if (!params || typeof params.cmd !== 'string' || params.cmd.length === 0) return null;
+  const args = Array.isArray(params.args) ? params.args : [];
+  return JSON.stringify([params.cmd, args]);
+}
+
 /**
  * THE PLAIN-QUESTION OWNER (plain-checks build, 2026-09-28, hamr's ruling:
  * the "checks N/M" headline is WITHDRAWN — "confusing, reads like 6 failed
@@ -64,23 +82,6 @@
  * @param {{kind: string|null, params: any, genre: string|null, suiteCmdKeys: Set<string>}} o
  * @returns {string|null}
  */
-export const GENRE_WHAT = Object.freeze({ TYPES: 'type errors' });
-
-/** `cmd`+`args`, as a comparable key — the one signal (besides `kind`
- * itself) that two stages measure the SAME command's output, used to tell a
- * genuine typecheck stage apart from the TYPES genre's other `lower-is-
- * better`/`baseline: 0` stage (the failing-test-count half of `suite-green`'s
- * "two assertions"), which shares that stage's own shape but not its
- * population. `null` for a stage whose `cmd` isn't a non-empty string —
- * never matches anything, so it never falsely suppresses a real typecheck
- * question.
- * @param {any} params @returns {string|null} */
-export function cmdKey(params) {
-  if (!params || typeof params.cmd !== 'string' || params.cmd.length === 0) return null;
-  const args = Array.isArray(params.args) ? params.args : [];
-  return JSON.stringify([params.cmd, args]);
-}
-
 export function stageQuestionText({
   kind, params, genre, suiteCmdKeys,
 }) {

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/authorreadout.d.ts

@@ -303,6 +303,13 @@ export function redsRecord(reds: PlainRed[], { cases, signing }?: {
 }): Record<string, any>[];
 /** the stops this module explains in plain words */
 export const PLAIN_PROPOSAL_STOPS: readonly string[];
+/**
+ * ONE owner of the plain sentence for every drafting stop code (hamr 2026-10-09: "a user should get a reason they can
+ * understand and do something about"). What happened; `STOP_TODO` below overrides the default "draft again" where that is wrong.
+ * Used by `draftStopText` for every stop the panel and the CLI show; a code not listed reads `STOP_UNKNOWN`, never the raw code.
+ * @type {Record<string, string>}
+ */
+export const STOP_HEADS: Record<string, string>;
 /** codes the declaration gates (validateJob, validateCloseDecl) raise: one plain sentence covers the family */
 export const DECLARATION_CODES: readonly string[];
 export type PlainRed = {

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;
+};