bareloop 0.46.1 → 0.47.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -170,6 +170,8 @@
170
170
  1.2s, matching design/panel-mockup.html's pulsing amber dot exactly —
171
171
  one fixed rhythm, never re-derived per call site. */
172
172
  @keyframes pulse-glyph{0%,100%{opacity:1;}50%{opacity:0.3;}}
173
+ .audit-caret{flex:none;color:var(--text-faint);margin-right:.6em;}
174
+ @media (max-width: 640px){ .audit-caret{margin-right:.2em;} }
173
175
  .dot.amber::before{content:"[▶]";color:var(--amber);}
174
176
  /* RULED 2026-10-15 (matches fwdloop glyphPulses): a sign blinks only while running or waiting for your Accept, keyed to `.pulse` (dotPulses decides) */
175
177
  .dot.pulse::before{animation:pulse-glyph 1.2s ease-in-out infinite;}
@@ -1116,7 +1118,9 @@
1116
1118
  }
1117
1119
 
1118
1120
  // ---- step map renderer (buildStepMapHTML below — ONE renderer, no second hand-authored map anywhere on this page) ----
1119
- function escapeXml(s){
1121
+ // The one Audit fold arrow (fwdloop's): \u25B6 closed, \u25BC open, faint, never shrinking; the gap after it is CSS (smaller on a phone).
1122
+ function auditCaret(open){ return '<span class="audit-caret">' + (open ? "\u25BC" : "\u25B6") + '</span>'; }
1123
+ function escapeXml(s){
1120
1124
  return String(s).replace(/&/g,"&amp;").replace(/</g,"&lt;").replace(/>/g,"&gt;").replace(/"/g,"&quot;");
1121
1125
  }
1122
1126
  // s.noNumber (F196): a synthetic placeholder box (e.g. "died during
@@ -2922,8 +2926,8 @@
2922
2926
  });
2923
2927
  });
2924
2928
  var label = items.length ? head + " \u00B7 " + first + (first === 1 ? " hint" : " hints") : head;
2925
- // 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
2926
- var paint = function(){ sum.innerHTML = stateDotHTML(glyphClass("\u2713"), "learnings", "audit-learnings-state") + " " + escapeXml(label); };
2929
+ // arrow back (hamr 2026-10-24, latest wins over 2026-10-23): auditCaret (\u25BC open / \u25B6 closed) first, as the schedule header; then the same `[✓] word` state markup the schedule/step headers wear (stateDotHTML), then the plain-words title
2930
+ var paint = function(){ sum.innerHTML = auditCaret(sum.getAttribute("aria-expanded") === "true") + stateDotHTML(glyphClass("\u2713"), "learnings", "audit-learnings-state") + " " + escapeXml(label); };
2927
2931
  paint();
2928
2932
  // ONE fold, same as the other Audit sections: the header button toggles the body (wired once)
2929
2933
  sum.onclick = function(){
@@ -3451,7 +3455,7 @@
3451
3455
  gBtn.className = "btn audit-part-toggle";
3452
3456
  gBtn.setAttribute("aria-expanded", "false");
3453
3457
  gBtn.setAttribute("data-testid", "audit-schedule-toggle");
3454
- var secHead = function(open){ return (open ? "\u25BE " : "\u25B8 ") + stateDotHTML(glyphClass(sec.sign), sec.word, "audit-schedule-state") + " " + escapeXml(sec.title) + " &middot; " + escapeXml(sec.head); };
3458
+ var secHead = function(open){ return auditCaret(open) + stateDotHTML(glyphClass(sec.sign), sec.word, "audit-schedule-state") + " " + escapeXml(sec.title) + " &middot; " + escapeXml(sec.head); };
3455
3459
  gBtn.innerHTML = secHead(false);
3456
3460
  var gBody = document.createElement("div");
3457
3461
  gBody.className = "audit-part-body";
@@ -3500,11 +3504,15 @@
3500
3504
  headBtn.setAttribute("aria-expanded", startExpanded ? "true" : "false");
3501
3505
  headBtn.setAttribute("data-testid", "audit-part-toggle-" + idx);
3502
3506
  var groupResultGlyph = partResultGlyph(part, box);
3503
- headBtn.innerHTML =
3504
- stepStateHTML(box, 'audit-part-state-' + idx) + ' ' + titleText + ' &middot; ' + partLine1Text(part, detail) +
3505
- (groupResultGlyph !== null ? ' &middot; ' + groupResultGlyph : '') +
3506
- (box.blocked > 0 ? ' <span class="badge red" data-testid="audit-part-blocked-' + idx + '">' + box.blocked + ' blocked</span>' : '') +
3507
- actorMarkHtml(part);
3507
+ // same arrow as the schedule section's secHead (auditCaret): \u25BC open, \u25B6 closed, at the very start of the button text
3508
+ var partHead = function(open){
3509
+ return auditCaret(open) +
3510
+ stepStateHTML(box, 'audit-part-state-' + idx) + ' ' + titleText + ' &middot; ' + partLine1Text(part, detail) +
3511
+ (groupResultGlyph !== null ? ' &middot; ' + groupResultGlyph : '') +
3512
+ (box.blocked > 0 ? ' <span class="badge red" data-testid="audit-part-blocked-' + idx + '">' + box.blocked + ' blocked</span>' : '') +
3513
+ actorMarkHtml(part);
3514
+ };
3515
+ headBtn.innerHTML = partHead(startExpanded);
3508
3516
  var body = document.createElement("div");
3509
3517
  body.className = "audit-part-body";
3510
3518
  body.hidden = !startExpanded;
@@ -3550,6 +3558,7 @@
3550
3558
  var expanded = headBtn.getAttribute("aria-expanded") === "true";
3551
3559
  headBtn.setAttribute("aria-expanded", expanded ? "false" : "true");
3552
3560
  body.hidden = expanded;
3561
+ headBtn.innerHTML = partHead(!expanded);
3553
3562
  if(!expanded && !built) buildBody();
3554
3563
  });
3555
3564
  rowWrap.appendChild(headBtn);
@@ -79,16 +79,27 @@ import { stageQuestionsByName } from '../stagewords.js';
79
79
 
80
80
  const HERE = dirname(fileURLToPath(import.meta.url));
81
81
 
82
- /** bareloop's own version, from its package.json (read each time the page is served); 'unknown' if it cannot be read, never a guess
82
+ /** bareloop's own version, from its package.json (read once when the panel starts); 'unknown' if it cannot be read, never a guess
83
83
  * @param {string} [file] test seam: another package.json
84
84
  * @returns {string} */
85
- function packageVersion(file = join(HERE, '..', '..', 'package.json')) {
85
+ export function packageVersion(file = join(HERE, '..', '..', 'package.json')) {
86
86
  try {
87
87
  const v = JSON.parse(readFileSync(file, 'utf8')).version;
88
88
  return typeof v === 'string' && v.length > 0 ? v : 'unknown';
89
89
  } catch { return 'unknown'; }
90
90
  }
91
91
 
92
+ /**
93
+ * `GET /api/whoami` body. `drafts` counts the person's drafting sessions that are not finished (the headless scheduled ones are not drafts).
94
+ * @param {{ port: number, version?: string, packageJsonPath?: string, authorRoutes?: ReturnType<typeof createAuthorRoutes>, schedules?: ReturnType<typeof createScheduleDoor> }} opts
95
+ */
96
+ function whoamiPayload(opts) {
97
+ const drafts = opts.authorRoutes ? opts.authorRoutes.openDrafts() : 0;
98
+ let schedules = 0;
99
+ try { schedules = opts.schedules ? opts.schedules.scan().length : 0; } catch { schedules = 0; }
100
+ return { app: 'bareloop', version: opts.version ?? packageVersion(opts.packageJsonPath), pid: process.pid, port: opts.port, drafts, schedules };
101
+ }
102
+
92
103
  /** Largest POST body the panel buffers (job cards are short prose); a bigger one is refused with 413. */
93
104
  const MAX_BODY_BYTES = 1024 * 1024;
94
105
 
@@ -1056,6 +1067,25 @@ export function runsListPayload(opts = {}) {
1056
1067
  return { runs, jobs, scheduled, gaveUp, limits: RUNS_LIST_LIMITS };
1057
1068
  }
1058
1069
 
1070
+ /**
1071
+ * The runs list as the panel builds it, for a caller with no panel running (the launcher header): the same `runsListPayload` over a
1072
+ * schedule door built read-only (no scheduler, no timer), so Needs you = the rows tagged `needs` + the schedules that gave up, ONE owner.
1073
+ * @param {{ home?: string, now?: number, env?: Record<string, string|undefined> }} [opts]
1074
+ * @returns {{ runs: any[], gaveUp: any[] }}
1075
+ */
1076
+ export function runsListForCount(opts = {}) {
1077
+ const home = opts.home;
1078
+ const schedules = createScheduleDoor({
1079
+ ...(home ? { home } : {}),
1080
+ jobRuns: (job) => jobRunsOf(job, { home }),
1081
+ startFrom: (runid) => getStartFrom(runid, { home }),
1082
+ jobOfRun: (runid) => readRunList({ home }).rows.find((r) => r && r.runid === runid)?.job ?? null,
1083
+ rowsFor: () => rowsForHome(keysHome(home), keysForDoor({ env: opts.env ?? {}, keysHome: home }).env),
1084
+ });
1085
+ const { runs, gaveUp } = runsListPayload({ home, ...(opts.now !== undefined ? { now: opts.now } : {}), schedules });
1086
+ return { runs, gaveUp };
1087
+ }
1088
+
1059
1089
  /**
1060
1090
  * The run's DRAFTING PART (hamr 2026-10-06, option A), or null: it exists only when the run came out of a panel
1061
1091
  * session whose drafting log carries a metered call (src/draftspend.js, `draftingPartFor`) and the spine carries the
@@ -3713,7 +3743,7 @@ function sendText(res, code, text) {
3713
3743
  * only `createPanelServer` below always supplies one.
3714
3744
  * @param {import('node:http').IncomingMessage} req
3715
3745
  * @param {import('node:http').ServerResponse} res
3716
- * @param {{ home?: string, sessionsRoot?: string, packageJsonPath?: string, port: number, token?: string, authorRoutes?: ReturnType<typeof createAuthorRoutes>, settingsRoutes?: ReturnType<typeof createSettingsRoutes>, runRoutes?: ReturnType<typeof createRunRoutes>, importRoutes?: ReturnType<typeof createImportRoutes>, schedules?: ReturnType<typeof createScheduleDoor> }} opts
3746
+ * @param {{ home?: string, sessionsRoot?: string, version?: string, packageJsonPath?: string, port: number, token?: string, authorRoutes?: ReturnType<typeof createAuthorRoutes>, settingsRoutes?: ReturnType<typeof createSettingsRoutes>, runRoutes?: ReturnType<typeof createRunRoutes>, importRoutes?: ReturnType<typeof createImportRoutes>, schedules?: ReturnType<typeof createScheduleDoor> }} opts
3717
3747
  */
3718
3748
  export function handleRequest(req, res, opts) {
3719
3749
  /** the ONE writable route family for a path, or null — `/api/author/*` (authoring) or
@@ -3809,9 +3839,9 @@ export function handleRequest(req, res, opts) {
3809
3839
  return;
3810
3840
  }
3811
3841
  html = html.replace(/__BARELOOP_PANEL_PORT__/g, String(opts.port));
3812
- // the topbar reads `bareloop · v<version> · ...`: the version is bareloop's OWN package.json, read when the page is served
3842
+ // the topbar reads `bareloop · v<version> · ...`: the version is bareloop's OWN package.json, read once when the panel starts
3813
3843
  // and templated in exactly like the port — never written into the HTML
3814
- html = html.replace(/__BARELOOP_PANEL_VERSION__/g, packageVersion(opts.packageJsonPath));
3844
+ html = html.replace(/__BARELOOP_PANEL_VERSION__/g, opts.version ?? packageVersion(opts.packageJsonPath));
3815
3845
  // PANEL-BUILD.md P3's human-click guard: a per-server-start token,
3816
3846
  // templated into the page exactly like the port — absent on every P1/P2
3817
3847
  // caller (no `opts.token`), which is fine: the page's own JS only reads
@@ -3827,6 +3857,13 @@ export function handleRequest(req, res, opts) {
3827
3857
  return;
3828
3858
  }
3829
3859
 
3860
+ // L (PANEL-BUILD.md addendum 2026-10-24): who is answering here — the launcher's probe (`bareloop start|stop|status`). Read-only, no token;
3861
+ // the Host guard above already holds. `drafts` = open drafting sessions (in memory, lost on stop); `schedules` = jobs with a schedule on.
3862
+ if (pathname === '/api/whoami') {
3863
+ send(200, whoamiPayload(opts));
3864
+ return;
3865
+ }
3866
+
3830
3867
  if (pathname === '/api/runs') { send(200, runsListPayload({ home: opts.home, schedules: opts.schedules })); return; }
3831
3868
 
3832
3869
  const runMatch = /^\/api\/runs\/([^/]+)(\/(audit|job|rounds|result|download))?$/.exec(pathname);
@@ -3895,6 +3932,15 @@ export function handleRequest(req, res, opts) {
3895
3932
  sendText(res, 404, 'not found');
3896
3933
  }
3897
3934
 
3935
+ /**
3936
+ * The ONE spelling of the panel's own address (the launcher prints and opens it too).
3937
+ * @param {number} boundPort
3938
+ * @returns {string}
3939
+ */
3940
+ export function panelUrl(boundPort) {
3941
+ return `http://127.0.0.1:${boundPort}`;
3942
+ }
3943
+
3898
3944
  /**
3899
3945
  * Start the panel server. Binds `127.0.0.1` ONLY. A taken port is a LOUD,
3900
3946
  * non-zero-exit failure — this never falls back to another port (see file
@@ -3922,6 +3968,8 @@ export function createPanelServer(opts = {}) {
3922
3968
  const requestedPort = opts.port ?? DEFAULT_PORT;
3923
3969
  const home = opts.home;
3924
3970
  const token = mintToken();
3971
+ // the version THIS process runs, read once at start: package.json on disk can move on while the panel keeps running old code
3972
+ const version = packageVersion(opts.packageJsonPath);
3925
3973
  return new Promise((resolve, reject) => {
3926
3974
  // Bound port is resolved from the live socket (`server.address().port`)
3927
3975
  // once listening starts, not the requested value — this is what makes
@@ -3944,7 +3992,7 @@ export function createPanelServer(opts = {}) {
3944
3992
  const server = createServer((req, res) => {
3945
3993
  try {
3946
3994
  handleRequest(req, res, {
3947
- home, sessionsRoot: opts.sessionsRoot, port: boundPort, token, authorRoutes, settingsRoutes, runRoutes, importRoutes, packageJsonPath: opts.packageJsonPath, schedules: schedulesRef,
3995
+ home, sessionsRoot: opts.sessionsRoot, port: boundPort, token, authorRoutes, settingsRoutes, runRoutes, importRoutes, version, packageJsonPath: opts.packageJsonPath, schedules: schedulesRef,
3948
3996
  });
3949
3997
  } catch (e) {
3950
3998
  sendText(res, 500, `internal error: ${/** @type {Error} */ (e).message}`);
@@ -4057,7 +4105,7 @@ export async function panelMain(argv, ctx) {
4057
4105
  }
4058
4106
  try {
4059
4107
  const { port: boundPort } = await createPanelServer({ port, home: ctx.runlistHome, env: ctx.env });
4060
- ctx.out(`bareloop panel — read-only, http://127.0.0.1:${boundPort} (Ctrl-C to stop)`);
4108
+ ctx.out(`bareloop panel — read-only, ${panelUrl(boundPort)} (Ctrl-C to stop)`);
4061
4109
  // never resolves on its own — the process stays up until killed, same
4062
4110
  // shape any other long-running dev server takes.
4063
4111
  await new Promise(() => {});
@@ -21,7 +21,7 @@ import {
21
21
  readConfig, updateConfig, ConfigError, providerFieldProblem, cleanBaseUrl, modelsProblem,
22
22
  } from '../config.js';
23
23
  import { spendSummary, monthlyLimitOf } from '../monthly.js';
24
- import { spawn as realSpawn } from 'node:child_process';
24
+ import { openInOs } from '../opener.js';
25
25
  import { loadKeysEnv, keysFilePath, keysHome, filledKeyNames, ensureKeysFile } from '../keysfile.js';
26
26
  import { SHAPES } from '../providershapes.js';
27
27
  import { keyRows, effectiveModels, usableKey, rowNamesOf } from '../providerrows.js';
@@ -208,24 +208,10 @@ export function createSettingsRoutes(opts) {
208
208
  }
209
209
  const dir = keysHome(opts.home);
210
210
  const cannot = () => reply(200, { ok: true, opened: false, path: dir });
211
- const platform = opts.platform ?? process.platform;
212
- const cmd = platform === 'linux' ? 'xdg-open' : (platform === 'darwin' ? 'open' : null);
213
211
  // under a test process (NODE_ENV=test or `node --test`) nothing is spawned unless a test injected an opener
214
212
  const underTest = process.env.NODE_ENV === 'test' || process.env.NODE_TEST_CONTEXT !== undefined;
215
- const opener = opts.openFolderSpawn ?? (underTest ? null : realSpawn);
216
- if (!cmd || !opener) return Promise.resolve(cannot());
217
- return new Promise((resolve) => {
218
- let child;
219
- try { child = opener(cmd, [dir], { detached: true, stdio: 'ignore' }); } catch { resolve(cannot()); return; }
220
- let settled = false;
221
- child.once('error', () => { if (!settled) { settled = true; resolve(cannot()); } });
222
- child.once('spawn', () => {
223
- if (settled) return;
224
- settled = true;
225
- if (typeof child.unref === 'function') child.unref();
226
- resolve(reply(200, { ok: true, opened: true, path: dir }));
227
- });
228
- });
213
+ return openInOs(dir, { platform: opts.platform, spawnFn: opts.openFolderSpawn, underTest })
214
+ .then((opened) => (opened ? reply(200, { ok: true, opened: true, path: dir }) : cannot()));
229
215
  }
230
216
 
231
217
  /**
@@ -0,0 +1,27 @@
1
+ // ONE place for terminal colour (the launcher's header, menu and messages). Colours wrap words and never change them: with colour off
2
+ // every helper returns its text untouched, so plain-text readers (tests, pipes, logs) see the same words.
3
+
4
+ const wrap = (/** @type {string} */ code) => (/** @type {string} */ s) => `\x1b[${code}m${s}\x1b[0m`;
5
+ const id = (/** @type {string} */ s) => s;
6
+
7
+ /**
8
+ * @typedef {object} Paint
9
+ * @property {boolean} on
10
+ * @property {(s: string) => string} grey @property {(s: string) => string} green @property {(s: string) => string} yellow
11
+ * @property {(s: string) => string} red @property {(s: string) => string} cyan @property {(s: string) => string} boldCyan
12
+ */
13
+
14
+ /**
15
+ * Colour is on only for a terminal: the stream says it is a TTY, `NO_COLOR` is empty/unset, and `TERM` is not `dumb`.
16
+ * @param {{isTTY?: boolean}|undefined} stream the output stream (process.stdout)
17
+ * @param {Record<string, string|undefined>} [env]
18
+ * @returns {Paint}
19
+ */
20
+ export function makePaint(stream, env = process.env) {
21
+ const on = Boolean(stream && stream.isTTY) && !(env.NO_COLOR ?? '') && env.TERM !== 'dumb';
22
+ if (!on) return { on, grey: id, green: id, yellow: id, red: id, cyan: id, boldCyan: id };
23
+ return { on, grey: wrap('90'), green: wrap('32'), yellow: wrap('33'), red: wrap('31'), cyan: wrap('36'), boldCyan: wrap('1;36') };
24
+ }
25
+
26
+ /** the no-colour paint, the default when a caller passes none */
27
+ export const PLAIN = makePaint(undefined, {});
package/src/userrun.js CHANGED
@@ -1307,7 +1307,7 @@ async function execute(ctx) {
1307
1307
  if (RULING.decision !== 'rerun') {
1308
1308
  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.`);
1309
1309
  if (RULING.decision === 'accept') {
1310
- // Cross-run learnings: the human Accept is what releases a held rubric run's lessons so they count (forward only; a rerun or a
1310
+ // 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
1311
1311
  // pause never does). Its own try/catch: a record, never a verdict.
1312
1312
  if (cfgOn && DOOR !== null) {
1313
1313
  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) {
2025
2025
  } 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.`); }
2026
2026
  }
2027
2027
  // The run-end tally of cross-run learnings ($0, code only, no model): the whole spine (all legs) and the gate audit become cards
2028
- // folded into the ONE ledger (a rubric job's are held until the human Accept). Its own try/catch, like the settle above: a
2028
+ // folded into the ONE ledger (a rubric job's count at run end too). Its own try/catch, like the settle above: a
2029
2029
  // record, never a verdict — a failure prints one WARNING line and can never change the outcome, the exit code or the spend.
2030
2030
  // `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
2031
2031
  // 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 CHANGED
@@ -3,7 +3,7 @@
3
3
  * code, so `bin/bareloop.mjs` can set `process.exitCode` and let node flush
4
4
  * queued stdout on its own (F-something: `process.exit()` can discard it).
5
5
  * @param {string[]} argv
6
- * @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
6
+ * @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
7
7
  * @returns {Promise<number>}
8
8
  */
9
9
  export function main(argv: string[], deps?: {
@@ -19,4 +19,5 @@ export function main(argv: string[], deps?: {
19
19
  stdin?: any;
20
20
  runlistHome?: string;
21
21
  keysHome?: string;
22
+ processEnv?: Record<string, string | undefined>;
22
23
  }): Promise<number>;
@@ -0,0 +1,257 @@
1
+ /**
2
+ * @typedef {object} Panel one answered probe
3
+ * @property {number} port @property {number} pid @property {string} version @property {number} drafts @property {number} schedules
4
+ * @property {string} url
5
+ */
6
+ /**
7
+ * @typedef {object} LauncherDeps every OS touch, injectable (a test passes all of them)
8
+ * @property {string} [home] the bareloop home (`~/.config/bareloop`); undefined = the real one
9
+ * @property {number} [portStart] @property {number} [portCount]
10
+ * @property {number[]} [ports] an explicit port list (tests); wins over portStart/portCount
11
+ * @property {number} [timeoutMs] probe timeout per port
12
+ * @property {number} [deadlineMs] start/stop wait deadline
13
+ * @property {number} [silentWaitMs] how long start keeps asking a taken, silent port (default 10 s)
14
+ * @property {string} [nodeVersion] default process.versions.node
15
+ * @property {typeof fetch} [fetchImpl]
16
+ * @property {(cmd: string, args: string[], o: object) => any} [spawnFn] default node:child_process spawn
17
+ * @property {(pid: number, sig: string|number) => void} [kill] default process.kill
18
+ * @property {((target: string) => Promise<boolean>)} [open] default the shared OS opener
19
+ * @property {(port: number) => Promise<boolean>} [portFree] default: try to bind 127.0.0.1:port
20
+ * @property {(ms: number) => Promise<void>} [sleep]
21
+ * @property {(question: string) => Promise<string>} [ask] the y/N and menu reader
22
+ * @property {string} [bareloopBin] default bin/bareloop.mjs of this package
23
+ * @property {import('./tty-colour.js').Paint} [paint] colour for stdout lines (default none); {@link makePaint} decides TTY / NO_COLOR / TERM
24
+ * @property {import('./tty-colour.js').Paint} [paintErr] colour for stderr lines (default: `paint`)
25
+ * @property {number} [now] ms clock for the run list's age rules (default: real time); tests pass their own
26
+ * @property {string} [platform]
27
+ * @property {Record<string, string|undefined>} [env] raw env handed to the panel child (default process.env)
28
+ */
29
+ /**
30
+ * The run counts, from the panel's own `listRuns` rows. `status.key === 'running'` is the panel's word; `needs` is the one tag
31
+ * {@link import('./panel/server.js').needsStateFor} decides. A part that is 0 still shows.
32
+ * @param {any[]} rows
33
+ * @param {number} [gaveUp] schedules that gave up: the panel's Needs-you holds them too
34
+ * @returns {{running: number, needYou: number, total: number}}
35
+ */
36
+ export function countRuns(rows: any[], gaveUp?: number): {
37
+ running: number;
38
+ needYou: number;
39
+ total: number;
40
+ };
41
+ /**
42
+ * "installed ✓" = the folder exists, config.json is there and reads with no problem, `.env` exists with mode 600, node >= 22.
43
+ * Otherwise the FIRST missing thing in plain words.
44
+ * @param {{home?: string, nodeVersion?: string}} o
45
+ * @returns {{ok: boolean, problem: string|null}}
46
+ */
47
+ export function installState(o: {
48
+ home?: string;
49
+ nodeVersion?: string;
50
+ }): {
51
+ ok: boolean;
52
+ problem: string | null;
53
+ };
54
+ /**
55
+ * Ask one port for `/api/whoami`. Never throws. `silent` = no reply inside the timeout (a loaded or stuck process may still be a
56
+ * panel); `other` = something replied (or refused) and it is not a bareloop whoami.
57
+ * @param {{port: number, timeoutMs?: number, fetchImpl?: typeof fetch}} o
58
+ * @returns {Promise<{state: 'panel', panel: Panel}|{state: 'other'}|{state: 'silent'}>}
59
+ */
60
+ export function probePort(o: {
61
+ port: number;
62
+ timeoutMs?: number;
63
+ fetchImpl?: typeof fetch;
64
+ }): Promise<{
65
+ state: "panel";
66
+ panel: Panel;
67
+ } | {
68
+ state: "other";
69
+ } | {
70
+ state: "silent";
71
+ }>;
72
+ /**
73
+ * Ask 127.0.0.1 across the ports in parallel; a reply with `app === "bareloop"` is a panel. Never throws.
74
+ * @param {{ports: number[], timeoutMs?: number, fetchImpl?: typeof fetch}} o
75
+ * @returns {Promise<Panel[]>} in port order
76
+ */
77
+ export function probePanels(o: {
78
+ ports: number[];
79
+ timeoutMs?: number;
80
+ fetchImpl?: typeof fetch;
81
+ }): Promise<Panel[]>;
82
+ /**
83
+ * The header, ONCE per call: the two lines every `bareloop` command prints first, plus the panels the probe found (the commands
84
+ * reuse them, so nothing is probed twice).
85
+ * @param {LauncherDeps & {version?: string}} d
86
+ * @returns {Promise<{lines: string[], panels: Panel[]}>}
87
+ */
88
+ export function buildHeader(d: LauncherDeps & {
89
+ version?: string;
90
+ }): Promise<{
91
+ lines: string[];
92
+ panels: Panel[];
93
+ }>;
94
+ /**
95
+ * @param {LauncherDeps & {version?: string}} d
96
+ * @returns {Promise<string[]>} the two header lines
97
+ */
98
+ export function headerLines(d: LauncherDeps & {
99
+ version?: string;
100
+ }): Promise<string[]>;
101
+ /**
102
+ * `bareloop install` — creates only what is missing, never reads a key value.
103
+ * @param {{out: (s: string) => void, err: (s: string) => void}} io @param {LauncherDeps & {version?: string}} d @param {{lines: string[], panels: Panel[]}} [shown]
104
+ * @returns {Promise<number>}
105
+ */
106
+ export function installCmd(io: {
107
+ out: (s: string) => void;
108
+ err: (s: string) => void;
109
+ }, d: LauncherDeps & {
110
+ version?: string;
111
+ }, shown?: {
112
+ lines: string[];
113
+ panels: Panel[];
114
+ }): Promise<number>;
115
+ /**
116
+ * `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.
117
+ * @param {{out: (s: string) => void}} io @param {LauncherDeps & {version?: string}} d @param {{lines: string[], panels: Panel[]}} [shown] header the menu already printed
118
+ * @returns {Promise<number>}
119
+ */
120
+ export function statusCmd(io: {
121
+ out: (s: string) => void;
122
+ }, d: LauncherDeps & {
123
+ version?: string;
124
+ }, shown?: {
125
+ lines: string[];
126
+ panels: Panel[];
127
+ }): Promise<number>;
128
+ /**
129
+ * `bareloop start` — find a running panel first; else start one detached on the first free port 4700..4709, wait until it answers,
130
+ * open the page.
131
+ * @param {{out: (s: string) => void, err: (s: string) => void}} io @param {LauncherDeps & {version?: string}} d @param {{lines: string[], panels: Panel[]}} [shown]
132
+ * @returns {Promise<number>}
133
+ */
134
+ export function startCmd(io: {
135
+ out: (s: string) => void;
136
+ err: (s: string) => void;
137
+ }, d: LauncherDeps & {
138
+ version?: string;
139
+ }, shown?: {
140
+ lines: string[];
141
+ panels: Panel[];
142
+ }): Promise<number>;
143
+ /**
144
+ * `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
145
+ * port stops answering. Drafts are in memory: warn (summed over all found panels) and ask y/N unless `--yes`.
146
+ * @param {string[]} args
147
+ * @param {{out: (s: string) => void, err: (s: string) => void}} io @param {LauncherDeps & {version?: string}} d @param {{lines: string[], panels: Panel[]}} [shown]
148
+ * @returns {Promise<number>}
149
+ */
150
+ export function stopCmd(args: string[], io: {
151
+ out: (s: string) => void;
152
+ err: (s: string) => void;
153
+ }, d: LauncherDeps & {
154
+ version?: string;
155
+ }, shown?: {
156
+ lines: string[];
157
+ panels: Panel[];
158
+ }): Promise<number>;
159
+ /**
160
+ * The bare `bareloop` menu: header, the four choices, one question. Runs the chosen command and returns its exit code.
161
+ * @param {{out: (s: string) => void, err: (s: string) => void}} io @param {LauncherDeps & {version?: string}} d
162
+ * @returns {Promise<number>}
163
+ */
164
+ export function menuCmd(io: {
165
+ out: (s: string) => void;
166
+ err: (s: string) => void;
167
+ }, d: LauncherDeps & {
168
+ version?: string;
169
+ }): Promise<number>;
170
+ /** the first port tried, and how many in a row (4700..4709) */
171
+ export const PORT_START: 4700;
172
+ export const PORT_COUNT: 10;
173
+ /**
174
+ * one answered probe
175
+ */
176
+ export type Panel = {
177
+ port: number;
178
+ pid: number;
179
+ version: string;
180
+ drafts: number;
181
+ schedules: number;
182
+ url: string;
183
+ };
184
+ /**
185
+ * every OS touch, injectable (a test passes all of them)
186
+ */
187
+ export type LauncherDeps = {
188
+ /**
189
+ * the bareloop home (`~/.config/bareloop`); undefined = the real one
190
+ */
191
+ home?: string | undefined;
192
+ portStart?: number | undefined;
193
+ portCount?: number | undefined;
194
+ /**
195
+ * an explicit port list (tests); wins over portStart/portCount
196
+ */
197
+ ports?: number[] | undefined;
198
+ /**
199
+ * probe timeout per port
200
+ */
201
+ timeoutMs?: number | undefined;
202
+ /**
203
+ * start/stop wait deadline
204
+ */
205
+ deadlineMs?: number | undefined;
206
+ /**
207
+ * how long start keeps asking a taken, silent port (default 10 s)
208
+ */
209
+ silentWaitMs?: number | undefined;
210
+ /**
211
+ * default process.versions.node
212
+ */
213
+ nodeVersion?: string | undefined;
214
+ fetchImpl?: typeof fetch | undefined;
215
+ /**
216
+ * default node:child_process spawn
217
+ */
218
+ spawnFn?: ((cmd: string, args: string[], o: object) => any) | undefined;
219
+ /**
220
+ * default process.kill
221
+ */
222
+ kill?: ((pid: number, sig: string | number) => void) | undefined;
223
+ /**
224
+ * default the shared OS opener
225
+ */
226
+ open?: ((target: string) => Promise<boolean>) | undefined;
227
+ /**
228
+ * default: try to bind 127.0.0.1:port
229
+ */
230
+ portFree?: ((port: number) => Promise<boolean>) | undefined;
231
+ sleep?: ((ms: number) => Promise<void>) | undefined;
232
+ /**
233
+ * the y/N and menu reader
234
+ */
235
+ ask?: ((question: string) => Promise<string>) | undefined;
236
+ /**
237
+ * default bin/bareloop.mjs of this package
238
+ */
239
+ bareloopBin?: string | undefined;
240
+ /**
241
+ * colour for stdout lines (default none); {@link makePaint} decides TTY / NO_COLOR / TERM
242
+ */
243
+ paint?: import("./tty-colour.js").Paint | undefined;
244
+ /**
245
+ * colour for stderr lines (default: `paint`)
246
+ */
247
+ paintErr?: import("./tty-colour.js").Paint | undefined;
248
+ /**
249
+ * ms clock for the run list's age rules (default: real time); tests pass their own
250
+ */
251
+ now?: number | undefined;
252
+ platform?: string | undefined;
253
+ /**
254
+ * raw env handed to the panel child (default process.env)
255
+ */
256
+ env?: Record<string, string | undefined> | undefined;
257
+ };
package/types/learn.d.ts CHANGED
@@ -193,7 +193,7 @@ export function foldCards(cards: Card[]): Card[][];
193
193
  * @typedef {object} Ledger
194
194
  * @property {1} version
195
195
  * @property {Row[]} rows
196
- * @property {Pending[]} pending rubric cards held until a human Accept (NOT counted, NOT readable)
196
+ * @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
197
197
  * @property {Card[]} suspect CHECK-SUSPECT cards, listed, newest last
198
198
  * @property {Record<string, {at: string, noise: string|null, cards: number, suspect: number, thin: number}>} health per run (idempotent by run id)
199
199
  */
@@ -208,8 +208,9 @@ export function lessonOf(c: Card): string;
208
208
  * Fold ONE run's cards into the ledger. Pure: returns a new ledger.
209
209
  *
210
210
  * +1 per RUN per row: the run's own cards are folded into lessons first, and a row whose `runIds` already holds the
211
- * run id is never counted twice (a resumed run, one id, never double counts). A matching lesson replaces the row's
212
- * sample, bumps the model count and appends the run id (a row last seen 56+ days ago counts +1 and is read again);
211
+ * run id is never counted twice (a resumed run, one id, never double counts) but IS refreshed: the resumed leg's card
212
+ * replaces the sample, lesson, key, lastSeen, hash and place (a leg-1 NEVER FIXED row becomes the leg-2 FIXED one). A
213
+ * 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);
213
214
  * otherwise it opens a new row at count 1. NEVER FIXED cards count like FIXED ones (RULING 3). A workflow row of
214
215
  * another signed hash is never matched here: the new version opens its own rows. Nothing is ever deleted or stamped.
215
216
  * @param {Ledger} ledger
@@ -234,8 +235,8 @@ export function countLedger(ledger: Ledger, { runid, cards, workflow, place, spe
234
235
  */
235
236
  export function climb(rows: Row[]): Row[];
236
237
  /**
237
- * A rubric run's cards are HELD, not counted, until a human Accept (the existing quarantine is the rule). Replaces
238
- * an earlier hold for the same run id (a resumed run re-derives its cards). Pure.
238
+ * 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
239
+ * end); kept so a hold already in a ledger file still has a writer for tests and a reader in {@link releasePending}. Pure.
239
240
  * @param {Ledger} ledger
240
241
  * @param {{runid: string, cards: Card[], workflow: string, place: string|null, specHash: string|null, at: string}} o
241
242
  * @param {Date} now @returns {Ledger}
@@ -249,7 +250,7 @@ export function holdPending(ledger: Ledger, { runid, cards, workflow, place, spe
249
250
  at: string;
250
251
  }, now: Date): Ledger;
251
252
  /**
252
- * The human Accept releases a held rubric run: its cards count now (trust `rubric`). Only forward, only here. A hold
253
+ * 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
253
254
  * older than 60 days is dropped uncounted. Idempotent (no hold = nothing to do; run ids stop a double count).
254
255
  * @param {Ledger} ledger @param {string} runid @param {Date} now
255
256
  * @returns {{ledger: Ledger, released: number}}
@@ -510,7 +511,7 @@ export type Ledger = {
510
511
  version: 1;
511
512
  rows: Row[];
512
513
  /**
513
- * rubric cards held until a human Accept (NOT counted, NOT readable)
514
+ * holds written by v0.46.x for rubric runs, released by the human Accept (NOT counted, NOT readable); new runs never write one
514
515
  */
515
516
  pending: Pending[];
516
517
  /**
@@ -22,9 +22,8 @@ export function readLedger(home?: string): {
22
22
  */
23
23
  export function writeLedger(ledger: import("./learn.js").Ledger, home?: string): string;
24
24
  /**
25
- * Fold ONE finished run into the ledger on disk: a deterministic job's cards COUNT now; a rubric job's cards are HELD
26
- * until a human Accept (they are written to `pending`, never counted, never readable). The run's health line is recorded
27
- * either way. Never throws on a bad ledger file: it reports `problem` and writes nothing.
25
+ * Fold ONE finished run into the ledger on disk: every run's cards COUNT now, rubric jobs too (trust kept on new rows;
26
+ * 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.
28
27
  * @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
29
28
  * @returns {{wrote: boolean, counted: number, held: number, problem: string|null}}
30
29
  */
@@ -45,7 +44,7 @@ export function foldRunIntoLedger({ home, runid, build, workflow, place, specHas
45
44
  problem: string | null;
46
45
  };
47
46
  /**
48
- * The human Accept at the review door: release the run's held rubric cards so they count (only forward, only here).
47
+ * 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).
49
48
  * @param {{home?: string, runid: string, now?: Date}} o
50
49
  * @returns {{released: number, problem: string|null}}
51
50
  */
@@ -66,7 +65,7 @@ export function releaseRun({ home, runid, now }: {
66
65
  export function learningHintsOn(home?: string): boolean;
67
66
  /**
68
67
  * THE RUN-END TALLY ($0, code only, no model): turn the finished run's whole record into cards and fold them into the
69
- * ledger (a rubric job's are held until Accept). Called once from the one engine's run-end block (src/userrun.js
68
+ * ledger (a rubric job's count too, trust kept). Called once from the one engine's run-end block (src/userrun.js
70
69
  * `execute`, shared by the panel, the CLI and the bundle runner), inside its own try/catch: it is a record, never a verdict,
71
70
  * and can never change a run's outcome, exit code or spend. It runs whether the hints setting is on or off.
72
71
  * @param {{home?: string, runid: string, events: any[], auditFiles?: string[], spec: any, specHash: string|null, workdir: string|null, trust: 'deterministic'|'rubric', now?: Date}} o