bareloop 0.46.0 → 0.47.0

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

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

@@ -25,6 +25,7 @@ import { readFileSync } from 'node:fs';
 import { planMatchesClose } from '../rubricstep.js';
 import { createSession, validateJobCard, validateReuseCard, jobBoxesChanged, buildReuseSpec, cardFields, nextFreeJobName, startDestinationProblem, STEP_LABELS } from './authorsession.js';
 import { parseInputs } from '../jobblock.js';
+import { isReusableGreen } from './status.js';
 import { proveInputFiles, looksLikeRubricInput, webFetchState } from '../source.js';
 import { validateJob } from '../job.js';
 
@@ -282,7 +283,7 @@ export function createAuthorRoutes(opts) {
         ok: true, origin: pre.origin, card, from: pre.from, note: pre.note,
         // ONE door (v1.101): `green` = the origin earned a real green (an imported job counts), so an unchanged job reuses the signed plan;
         // `nextName` = the Job name box once a job box changes (the box shows the origin's name until then). Nothing is locked.
-        green: pre.origin.importId !== undefined || pre.outcome === 'green' || pre.outcome === 'already-green',
+        green: pre.origin.importId !== undefined || isReusableGreen(pre.outcome),
         nextName: nextFreeJobName(pre.origin.job, opts.runJobNames ? opts.runJobNames() : [], { jobsDir: opts.jobsDir }),
         specHash: pre.specHash, workflowKey: pre.workflowKey, trackRecord: pre.trackRecord,
         line: pre.line, specNamesModel: pre.specNamesModel, specWorker: pre.specWorker,
@@ -357,7 +358,7 @@ export function createAuthorRoutes(opts) {
           // a scheduled run's green waits for the person's Accept (quarantine): its plan is neither reused nor re-drafted until then
           if (pre.outcome === 'green-held') { send(409, { ok: false, error: 'This run was started by a schedule and is waiting for your Accept. Accept it first, then it can be reused.' }); return true; }
           card.jobName = pre.origin.job; // an unchanged job keeps its name; a typed one is ignored
-          if (fromImport !== null || pre.outcome === 'green' || pre.outcome === 'already-green') {
+          if (fromImport !== null || isReusableGreen(pre.outcome)) {
             const rv = validateReuseCard(card, { rows });
             if (!rv.ok) { send(400, { ok: false, error: rv.error }); return true; }
             const spec = buildReuseSpec(pre.spec, card, rows);
@@ -431,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/authorsession.js

@@ -1146,13 +1146,11 @@ export function createSession(card, deps = {}) {
         const no = state.steps.findLastIndex((/** @type {any} */ x) => x.status === 'running');
         appendDraftLog(outDir, { kind: 'step-reds', no: no === -1 ? state.steps.length - 1 : no, stop: authored.stop ?? 'authoring-failed', reds: redsRecord(stopReds), at: new Date().toISOString() });
       }
-      refuse(authored.stop === 'confirm-abandoned' || authored.stop === 'confirm-restart'
-        ? `Stopped: ${authored.stop}${authored.refusal ? ` — ${authored.refusal.detail}` : ''}`
-        : draftStopText({
-          stop: String(authored.stop ?? 'authoring-failed'), reds: stopReds, refusal: authored.refusal,
-          spend: { knownUsd: state.draftSpentUsd, spendComplete: state.draftSpendComplete },
-          wholeJob: RUBRIC_FILES,
-        }), authored.stop === 'confirm-abandoned' ? 'abandoned' : 'refused');
+      refuse(draftStopText({
+        stop: String(authored.stop ?? 'authoring-failed'), reds: stopReds, refusal: authored.refusal,
+        spend: { knownUsd: state.draftSpentUsd, spendComplete: state.draftSpendComplete },
+        wholeJob: RUBRIC_FILES,
+      }), authored.stop === 'confirm-abandoned' ? 'abandoned' : 'refused');
       return;
     }