bareloop 0.47.1 → 0.48.0

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.
@@ -0,0 +1,65 @@
1
+ // The files that sit beside a run's spine, found the one way (panel and CLI both ask here): the source
2
+ // door's manifest, and the signed spec the run's latest leg ran under. Moved out of src/panel/server.js so
3
+ // `bareloop export` and the panel share ONE spelling (PRD v1.114). Pure reads, $0.
4
+
5
+ import { existsSync, readdirSync, readFileSync } from 'node:fs';
6
+ import { basename, dirname, join } from 'node:path';
7
+ import { legsOf } from './legs.js';
8
+ import { jobSpecHash } from './job.js';
9
+
10
+ /**
11
+ * `<out>/source-<seed>/<job>-bareloop/u-<runid>.jsonl` -> the two files an
12
+ * authoring session leaves BESIDE that layout — `<out>/resolved-spec.json`
13
+ * (the signed spec `--spec`/a JOBS-table row ran) and
14
+ * `<out>/source-<seed>/source.json` (the source front door's manifest) —
15
+ * verified against `src/userrun.js`'s own construction (`specWorkdir = join(into,
16
+ * 'tree')`, `spineDir = join(wd, '..', target.spine)`, both `--spec` and the
17
+ * `pulselog-person-strict` JOBS-table row read `into` the same way) and a real
18
+ * archived run (pulselog-person-live-2, run mu2p83go): `dirname(spine)` is
19
+ * `<into>/<job>-bareloop`, `dirname(dirname(spine))` is `<into>` itself
20
+ * (`source-<seed>`, carrying `source.json`), and `dirname(dirname(dirname(spine)))`
21
+ * is `<out>` (carrying `resolved-spec.json`).
22
+ *
23
+ * Only resolves when `<into>`'s own name starts with `source-` — the one
24
+ * shape marker this convention always carries — and each file is checked to
25
+ * actually exist before being handed back; any other spine layout (the bundle
26
+ * `spine.jsonl`, a JOBS-table row whose workdir has no source-seed copy, e.g.
27
+ * `litectx-u`) returns both fields `null`, never a guessed path (build spec
28
+ * item 2, 2026-09-25: "don't search the disk broadly — fall through").
29
+ * @param {string} spinePath
30
+ * @returns {{ specPath: string|null, sourceJsonPath: string|null }}
31
+ */
32
+ export function sourceNearSpine(spinePath) {
33
+ const into = dirname(dirname(spinePath)); // <into>/<job>-bareloop/u-x.jsonl -> <into>
34
+ if (!basename(into).startsWith('source-')) return { specPath: null, sourceJsonPath: null };
35
+ const sourceJsonPath = join(into, 'source.json');
36
+ const specPath = join(dirname(into), 'resolved-spec.json'); // <into> -> <out>
37
+ return {
38
+ specPath: existsSync(specPath) ? specPath : null,
39
+ sourceJsonPath: existsSync(sourceJsonPath) ? sourceJsonPath : null,
40
+ };
41
+ }
42
+ /**
43
+ * The signed spec a run's LATEST leg ran under — the `resolved-spec*.json` beside the run whose hash is the one its
44
+ * latest `job-start` carries (the same lookup `resumePlanFor` does). `null` = no such file.
45
+ * @param {{ spine: string }} row
46
+ * @param {any[]} records
47
+ * @returns {{spec: any, specPath: string, specHash: string}|null}
48
+ */
49
+ export function signedSpecForRun(row, records) {
50
+ const jobStart = (legsOf(records).findLast((l) => l.jobStart !== null) ?? null)?.jobStart ?? null;
51
+ if (!jobStart || typeof jobStart.specHash !== 'string') return null;
52
+ const near = sourceNearSpine(row.spine);
53
+ if (!near.specPath) return null;
54
+ const dir = dirname(near.specPath);
55
+ /** @type {string[]} */
56
+ let names = [];
57
+ try { names = readdirSync(dir).filter((n) => n === 'resolved-spec.json' || /^resolved-spec-r\d+\.json$/.test(n)); } catch { names = []; }
58
+ for (const n of names) {
59
+ let spec;
60
+ try { spec = JSON.parse(readFileSync(join(dir, n), 'utf8')); } catch { continue; }
61
+ if (!spec || typeof spec !== 'object') continue;
62
+ if (jobSpecHash(spec) === jobStart.specHash) return { spec, specPath: join(dir, n), specHash: jobStart.specHash };
63
+ }
64
+ return null;
65
+ }
package/src/runlist.js CHANGED
@@ -164,6 +164,37 @@ export function readNeedsRemovals(opts = {}) {
164
164
  return out;
165
165
  }
166
166
 
167
+ /**
168
+ * @typedef {{ type: 'exported', runid: string, job: string, bundle: string, bundleHash: string, at: string }} ExportedRow
169
+ * RULED 2026-10-25 (PRD v1.114): `bareloop export` appends ONE of these per bundle it makes, so `bareloop run` can find the bundle by the
170
+ * run's name. Not a run, a claim or an event: {@link readRunList} ignores it (it has a `type`), so the monthly limit, the run counter and the
171
+ * scheduler never see it. Nothing is rewritten.
172
+ */
173
+
174
+ /**
175
+ * Append one {@link ExportedRow}. THROWS on IO failure.
176
+ * @param {Omit<ExportedRow, 'type'>} row
177
+ * @param {{ home?: string }} [opts]
178
+ * @returns {void}
179
+ */
180
+ export function appendExported(row, opts = {}) {
181
+ const path = runlistPath(opts.home);
182
+ mkdirSync(runlistHome(opts.home), { recursive: true, mode: 0o700 });
183
+ appendFileSync(path, `${JSON.stringify({ ...row, type: 'exported' })}\n`);
184
+ try { chmodSync(path, 0o600); } catch { /* best-effort perms */ }
185
+ }
186
+
187
+ /**
188
+ * Every `exported` row, in file order (a re-export of the same run is a later row). An absent file is an empty list.
189
+ * @param {{ home?: string }} [opts]
190
+ * @returns {ExportedRow[]}
191
+ */
192
+ export function readExported(opts = {}) {
193
+ const path = runlistPath(opts.home);
194
+ if (!existsSync(path)) return [];
195
+ return parseJsonl(path).records.filter((r) => r && r.type === 'exported' && typeof r.bundle === 'string' && typeof r.runid === 'string');
196
+ }
197
+
167
198
  /**
168
199
  * @typedef {{ type: 'leg-start', runid: string, leg: number, pid?: number, capUsd?: number, at: string }} LegStart
169
200
  * A resumed run's NEW claim (P5-R, hamr 2026-10-02: one run, one id, one row): appended beside the run's row
@@ -483,3 +514,44 @@ export function formatRunRow(row) {
483
514
  const missing = existsSync(row.spine) ? '' : ' — file missing';
484
515
  return `${row.job} (${row.runid}) · ${date} · ${row.spine}${missing}`;
485
516
  }
517
+
518
+ /**
519
+ * @param {any} r
520
+ * @returns {number}
521
+ */
522
+ export function atMs(r) {
523
+ const t = typeof r?.at === 'string' ? Date.parse(r.at) : NaN;
524
+ return Number.isFinite(t) ? t : 0;
525
+ }
526
+
527
+ /**
528
+ * A run's name for a person: `job (run-N)`, N from {@link runNumbers}. The ONE spelling (the panel, `bareloop export` and `bareloop run` all print it).
529
+ * @param {string} job @param {number|undefined} n
530
+ * @returns {string}
531
+ */
532
+ export function runNameOf(job, n) { return `${job} (run-${n})`; }
533
+
534
+ /**
535
+ * The ONE owner of run names (P6 item 7): runs of the same job (`row.job`) are numbered oldest `at` first, 1-based
536
+ * (ties keep file order). A resume is one row, so it counts once; died and stopped runs are rows too. Every view
537
+ * reads this number — the page never counts on its own.
538
+ * @param {any[]} rows
539
+ * @returns {Map<string, number>} runid → N
540
+ */
541
+ export function runNumbers(rows) {
542
+ /** @type {Map<string, any[]>} */
543
+ const byJob = new Map();
544
+ rows.forEach((row, index) => {
545
+ if (!row || typeof row.runid !== 'string') return;
546
+ const g = byJob.get(row.job) || [];
547
+ g.push({ row, index });
548
+ byJob.set(row.job, g);
549
+ });
550
+ /** @type {Map<string, number>} */
551
+ const out = new Map();
552
+ for (const g of byJob.values()) {
553
+ g.sort((a, b) => (atMs(a.row) - atMs(b.row)) || (a.index - b.index));
554
+ g.forEach(({ row }, i) => out.set(row.runid, i + 1));
555
+ }
556
+ return out;
557
+ }
package/src/userrun.js CHANGED
@@ -32,7 +32,7 @@ import { commitWork, removeWorktree } from './worktree.js';
32
32
  import { moveFile } from './movefile.js';
33
33
  import { runJob } from './run.js';
34
34
  import { moneyWithDraft } from './replay.js';
35
- import { jobSpecHash, resolveWorkerModel, validateJob } from './job.js';
35
+ import { jobSpecHash, resolveWorkerModel, validateJob, workflowKey } from './job.js';
36
36
  import { readShimArm } from './readshim.js';
37
37
  import { closeStagesOf } from './plan.js';
38
38
  import { resolveCloseTimeoutMs } from './closetimeout.js';
@@ -82,7 +82,7 @@ import { keysForDoor } from './keysfile.js';
82
82
  import { parseJsonl } from './replayio.js';
83
83
  import { claimRun, monthlyRefusalText, legSpend, chainSpend } from './monthly.js';
84
84
  import { ConfigError } from './config.js';
85
- import { learnAtRunEnd, hintsForRun, releaseRun } from './learnstore.js';
85
+ import { learnAtRunEnd, handedHints, releaseRun } from './learnstore.js';
86
86
  import { commandFor } from './invoke.js';
87
87
  import { judgeRatesFor, keyNameFor, keyValueOf, priceReadout, ratesFor, ratesOfLine, resolveWorker, judgeRowFor, rowsForHome, REFUSE_NAME_MODEL } from './providerrows.js';
88
88
  // the banner's wall arithmetic, extracted so it is reachable by a test (F83): the
@@ -1906,7 +1906,10 @@ async function execute(ctx) {
1906
1906
  /** @type {{text: string, ids: string[]}|null} */
1907
1907
  let learnHints = null;
1908
1908
  if (cfgOn) {
1909
- try { learnHints = hintsForRun({ home: cfgHome, spec, specHash }); } catch { learnHints = null; }
1909
+ // an unreadable ledger hands nothing but is never silent: the reason rides a `learnings` spine record (hintsError) the Audit prints
1910
+ const handed = handedHints({ home: cfgHome, spec, workflowKey: workflowKey(spec) });
1911
+ learnHints = handed.hints;
1912
+ if (handed.error !== null) emit('learnings', { phase: 'draft', hintsError: handed.error });
1910
1913
  }
1911
1914
  let outcome;
1912
1915
  try {
@@ -2033,7 +2036,7 @@ async function execute(ctx) {
2033
2036
  try {
2034
2037
  const filedAudit = ctx.bundle ? join(spineDir, 'gate-audit.jsonl') : join(spineDir, `u-${runid}-gate-audit.jsonl`);
2035
2038
  learnAtRunEnd({
2036
- home: cfgHome, runid, events: allEvents, auditFiles: [filedAudit, join(wd, 'gate-audit.jsonl')], spec, specHash, workdir: wd,
2039
+ home: cfgHome, runid, events: allEvents, auditFiles: [filedAudit, join(wd, 'gate-audit.jsonl')], spec, specHash, workflowKey: workflowKey(spec), workdir: wd,
2037
2040
  trust: quarantinesCredit(spec.verdictType) ? 'rubric' : 'deterministic',
2038
2041
  });
2039
2042
  } catch (/** @type {any} */ e) { err(`WARNING: could not record this run's lessons in the learnings ledger (${redactSecrets(String(e?.message ?? e)).split('\n')[0]}) — the run itself is unaffected.`); }
@@ -2140,8 +2143,9 @@ async function execute(ctx) {
2140
2143
  out(` trend ${mh.trend} — ${mh.reading}`);
2141
2144
  if (ctx.bundle) {
2142
2145
  // a bundle's spec is manifest-hashed: there is no budgetUsd to edit and no new hash to sign. The room that
2143
- // is left is the signed ceiling, and the ONLY way to use it is the person typing a larger --budget. The
2144
- // exhausted --budget is never echoed (pasted as printed it halts again at once: the chain folds prior spend),
2146
+ // is left is the signed ceiling, and the way to use it is the person typing a larger --budget. Going PAST the
2147
+ // signed ceiling is allowed only with the person's own yes (hamr 2026-10-25), shown back and recorded in the run.
2148
+ // The exhausted --budget is never echoed (pasted as printed it halts again at once: the chain folds prior spend),
2145
2149
  // and nothing is filled in for them.
2146
2150
  const signed = ctx.bundle.signedBudgetUsd;
2147
2151
  const spentUsd = typeof mh.budgetUsd === 'number' && typeof mh.remainingUsd === 'number' ? mh.budgetUsd - mh.remainingUsd : null;
@@ -2152,12 +2156,12 @@ async function execute(ctx) {
2152
2156
  out(` lever ${lever}`);
2153
2157
  if (spentUsd !== null && spentUsd >= signed) {
2154
2158
  // the whole signed ceiling is spent: "more than spent, at most signed" is unsatisfiable, so no resume line is printed
2155
- out(` · no room left under the signed ceiling: this run spent all of the signed $${signed}, and a bundle's ceiling cannot be raised`);
2159
+ out(` · no room left under the signed ceiling: this run spent all of the signed $${signed}, and raising a bundle's ceiling needs your typed yes (--yes)`);
2156
2160
  out(' · abandon the task');
2157
2161
  } else {
2158
- out(` · choose a larger --budget on the resume line below (the room left is the signed $${signed}; it cannot be raised past that)`);
2162
+ out(` · choose a larger --budget on the resume line below (the room left is the signed $${signed}; going past it asks you to type yes)`);
2159
2163
  out(' · abandon the task');
2160
- out(` resume ${ctx.bundle.invoke}${WALL_FLAG} --resume ${runid}${SHIM_TAIL}${SCOUT_TAIL}${DRAFT_TAIL}${REGISTRY_TAIL} --budget <more than ${spentTxt}, at most $${signed}> --approve ${PRINT_APPROVE}`);
2164
+ out(` resume ${ctx.bundle.invoke}${WALL_FLAG} --resume ${runid}${SHIM_TAIL}${SCOUT_TAIL}${DRAFT_TAIL}${REGISTRY_TAIL} --budget <more than ${spentTxt}, above $${signed} asks you to type yes> --approve ${PRINT_APPROVE}`);
2161
2165
  out(' (type the --budget number yourself — nothing here fills it in, so this line does not run as printed; nothing in the run may widen its own budget)');
2162
2166
  }
2163
2167
  } else {
@@ -2580,7 +2584,7 @@ export async function main(argv, deps = {}) {
2580
2584
  if (!existsSync(specPath)) {
2581
2585
  die(`--job ${jobArg}: there is no spec at ${specPath}.\n`
2582
2586
  + ' The table row is the runner\'s half of a job (patient, seed, spine); the SPEC is yours — authored through\n'
2583
- + ` ${commandFor('interview', deps.invokedAs)} and ${commandFor('author', deps.invokedAs)}, then signed. Nothing here can stand in for it: a job\n`
2587
+ + ' the panel\'s drafting (or node scripts/run-interview.mjs and node scripts/run-author.mjs), then signed. Nothing here can stand in for it: a job\n'
2584
2588
  + ' with no spec has no goal, no close, no budget and no hash to approve.');
2585
2589
  }
2586
2590
  try { spec = JSON.parse(readFileSync(specPath, 'utf8')); } catch (e) {
@@ -2592,7 +2596,7 @@ export async function main(argv, deps = {}) {
2592
2596
  specPath = resolve(/** @type {string} */ (specArg));
2593
2597
  if (!existsSync(specPath)) {
2594
2598
  die(`--spec ${specPath} does not exist — a run needs the resolved-spec.json an authoring session actually wrote `
2595
- + `(${commandFor('author', deps.invokedAs)}'s own \`out/resolved-spec.json\`), never a path nobody authored`);
2599
+ + '(the panel\'s drafting session, or node scripts/run-author.mjs\'s own `out/resolved-spec.json`), never a path nobody authored');
2596
2600
  }
2597
2601
  let raw;
2598
2602
  try { raw = readFileSync(specPath, 'utf8'); } catch (e) {
@@ -2632,8 +2636,8 @@ export async function main(argv, deps = {}) {
2632
2636
  if (candidates.length === 0) {
2633
2637
  die(`--spec ${specPath}: no prepared copy beside it — looked for a source-*/ directory carrying source.json in `
2634
2638
  + `${dirname(specPath)} and found none. A --spec run reads its workdir and seed off the copy the authoring `
2635
- + `session prepared; it is never typed or guessed. Prepare one first: ${commandFor('interview', deps.invokedAs)} (or `
2636
- + `${commandFor('author', deps.invokedAs)} directly against a --source) before running this spec.`);
2639
+ + `session prepared; it is never typed or guessed. Prepare one first: draft the job in the panel (or node scripts/run-interview.mjs, `
2640
+ + 'then node scripts/run-author.mjs against a --source) before running this spec.');
2637
2641
  }
2638
2642
  if (candidates.length > 1) {
2639
2643
  die(`--spec ${specPath}: ${candidates.length} prepared copies sit beside it (${candidates.join(', ')}) — `
package/types/bundle.d.ts CHANGED
@@ -120,6 +120,22 @@ export function checkEnvelope(spec: any, envelope?: {
120
120
  ok: boolean;
121
121
  reds: Red[];
122
122
  };
123
+ /**
124
+ * The caps a typed envelope would RAISE above the bundle's signed ones (hamr 2026-10-25: a raise is allowed, but only signed by the
125
+ * person typing `yes` or passing `--yes`). Same fields and test as {@link checkEnvelope}'s widen red; a field the spec has no ceiling
126
+ * for cannot be raised. Pure.
127
+ * @param {any} spec the (already `$BARELOOP_BUNDLE`-resolved) bundle spec
128
+ * @param {{ budgetUsd?: number, maxWallMs?: number }} envelope
129
+ * @returns {{ field: 'budgetUsd'|'maxWallMs', old: number, new: number }[]}
130
+ */
131
+ export function capRaises(spec: any, envelope?: {
132
+ budgetUsd?: number;
133
+ maxWallMs?: number;
134
+ }): {
135
+ field: "budgetUsd" | "maxWallMs";
136
+ old: number;
137
+ new: number;
138
+ }[];
123
139
  /**
124
140
  * Write `blessing.json`: the FIRST GREEN RUN on the importer's own machine
125
141
  * signs the bundle as trustworthy (hamr Q2), so later runs need no
@@ -0,0 +1,63 @@
1
+ /**
2
+ * Every bundle on this machine the CLI knows, NEWEST FIRST, one per folder: the exported ones (the `exported` rows) and any bundle that
3
+ * has `bareloop run` rows (spine `<bundle>/runs/<runid>/spine.jsonl`). `label` = the run name (or the job) and the folder.
4
+ * @param {{ home?: string }} [opts]
5
+ * @returns {{ name: string, dir: string, label: string, atMs: number }[]}
6
+ */
7
+ export function knownBundles(opts?: {
8
+ home?: string;
9
+ }): {
10
+ name: string;
11
+ dir: string;
12
+ label: string;
13
+ atMs: number;
14
+ }[];
15
+ /**
16
+ * The shared bundle question of `run` and `history`: show the last {@link RECENT_BUNDLES} bundles, newest first, numbered; then ask. A number
17
+ * picks one shown; a run name or a folder reaches an older one. None known: one plain line and the command ends.
18
+ * @param {{ ask: (q: string) => Promise<string>, out: (s: string) => void, home?: string, none: string, cancelled: string }} o
19
+ * @returns {Promise<{ ref: string } | { end: true }>} `end` = the command ends cleanly (exit 0)
20
+ */
21
+ export function askBundle({ ask, out, home, none, cancelled }: {
22
+ ask: (q: string) => Promise<string>;
23
+ out: (s: string) => void;
24
+ home?: string;
25
+ none: string;
26
+ cancelled: string;
27
+ }): Promise<{
28
+ ref: string;
29
+ } | {
30
+ end: true;
31
+ }>;
32
+ /**
33
+ * A bundle reference typed by a person: an existing folder (relative to `cwd`), else an exported run name.
34
+ * @param {string} ref @param {{ home?: string, cwd: string }} o
35
+ * @returns {{ ok: true, dir: string } | { ok: false, why: string }}
36
+ */
37
+ export function resolveBundleRef(ref: string, { home, cwd }: {
38
+ home?: string;
39
+ cwd: string;
40
+ }): {
41
+ ok: true;
42
+ dir: string;
43
+ } | {
44
+ ok: false;
45
+ why: string;
46
+ };
47
+ /**
48
+ * The stopped / capped runs of `bareloop run` the engine would accept a resume for, newest first: not alive, no answer yet, an
49
+ * attempt to continue, checkpoint not expired, and the bundle folder still on disk.
50
+ * @param {{ home?: string }} [opts]
51
+ * @returns {{ runid: string, job: string, bundleDir: string, outcome: string, label: string }[]}
52
+ */
53
+ export function listResumableBundleRuns(opts?: {
54
+ home?: string;
55
+ }): {
56
+ runid: string;
57
+ job: string;
58
+ bundleDir: string;
59
+ outcome: string;
60
+ label: string;
61
+ }[];
62
+ /** how many bundles a pick list shows; older ones stay reachable by typing their run name or folder */
63
+ export const RECENT_BUNDLES: 10;
@@ -1,16 +1,20 @@
1
1
  /**
2
- * `bareloop run <bundleDir> --repo <path> [--budget N] [--wall MIN] [--approve <bundleHash>]`
3
- * `bareloop run <bundleDir> --resume <runid> [--repo <path>] [--budget N] [--wall MIN] [--approve <bundleHash>]`
2
+ * `bareloop run <bundle> --repo <path> [--model <id>] [--budget N] [--wall MIN] [--yes] [--approve <bundleHash>]`
3
+ * `bareloop run <bundle> --resume <runid> [--repo <path>] [--budget N] [--wall MIN] [--yes] [--approve <bundleHash>]`
4
+ * `<bundle>` is a bundle folder or the run name it was exported under (`job (run-N)`). A missing bundle, repo or model is asked for
5
+ * (when there is something to ask: `canAsk`); a required answer left empty twice ends the command cleanly (exit 0, nothing run).
6
+ * A cap typed ABOVE the signed one is shown back and needs `yes` (or `--yes`); the approval is recorded in the run's own folder.
4
7
  * @param {string[]} args
5
8
  * @param {{
6
9
  * out: (s: string) => void, err: (s: string) => void, cwd: string,
7
10
  * env: Record<string,string|undefined>, now: () => number, deps: any, keysHome?: string,
11
+ * ask?: (q: string) => Promise<string>, canAsk?: boolean, guided?: boolean,
8
12
  * parseFlags: (a: string[]) => { positional: string[], flags: Record<string, string|true> },
9
13
  * printReds: (reds: import('./bundle.js').Red[], err: (s: string) => void) => void,
10
14
  * }} ctx
11
15
  * @returns {Promise<number>}
12
16
  */
13
- export function bundleMain(args: string[], { out, err, cwd, env, now, deps, keysHome, parseFlags, printReds, }: {
17
+ export function bundleMain(args: string[], { out, err, cwd, env, now, deps, keysHome, ask, canAsk, guided: guidedIn, parseFlags, printReds, }: {
14
18
  out: (s: string) => void;
15
19
  err: (s: string) => void;
16
20
  cwd: string;
@@ -18,6 +22,9 @@ export function bundleMain(args: string[], { out, err, cwd, env, now, deps, keys
18
22
  now: () => number;
19
23
  deps: any;
20
24
  keysHome?: string;
25
+ ask?: (q: string) => Promise<string>;
26
+ canAsk?: boolean;
27
+ guided?: boolean;
21
28
  parseFlags: (a: string[]) => {
22
29
  positional: string[];
23
30
  flags: Record<string, string | true>;
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, processEnv?: Record<string,string|undefined> }} 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, interactive?: boolean, 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?: {
@@ -17,6 +17,7 @@ export function main(argv: string[], deps?: {
17
17
  judgeModel?: string | null;
18
18
  now?: () => number;
19
19
  stdin?: any;
20
+ interactive?: boolean;
20
21
  runlistHome?: string;
21
22
  keysHome?: string;
22
23
  processEnv?: Record<string, string | undefined>;
@@ -5,39 +5,22 @@
5
5
  * - `step-label` {no, label, at} (the step reads `label` from now on, status and times untouched: the thinking row's "the model thought anyway" / "can't change it" / "not confirmed")
6
6
  * - `human` {no, source: 'confirm'|'try-3'|'look', question, answer, line?, at}: one question the person was asked and what they answered (the answer is secret-masked
7
7
  * before it is written; the row is written only when BOTH exist, so a question nobody answered leaves no row)
8
- * - `call` {no, step, label, model, thinking, thinkingSupport, thinkingStatus?, costUsd (null stays null), unpricedRounds, at}: one METERED model call
8
+ * - `call` {no, step, label, model, provider, baseUrl, thinking, thinkingSupport, thinkingStatus?, costUsd (null stays null), unpricedRounds, at}: one METERED model call
9
9
  * (`thinking` = the tick's mode: off | on; `thinkingSupport` = bare-agent's lookup for the model: true | false | 'unverified';
10
10
  * `thinkingStatus` = bare-agent's own verdict for the call's run: applied | unsupported | ignored | unknown, present only when thinkingMode was sent)
11
11
  * (no token counts: the call path does not carry them without reworking the library, so none are recorded)
12
12
  * @typedef {{kind: string, no: number, at: string, [k: string]: any}} DraftEvent
13
13
  */
14
14
  /**
15
- * Append one event to `<dir>/draft-log.jsonl`. Best-effort like draft-spend.json: a disk fault never stops the draft.
15
+ * Append one event to `<dir>/draft-log.jsonl`. Best-effort: a disk fault never stops the draft.
16
16
  * @param {string} dir the session's folder
17
17
  * @param {DraftEvent} ev
18
18
  * @returns {void}
19
19
  */
20
20
  export function appendDraftLog(dir: string, ev: DraftEvent): void;
21
21
  /**
22
- * @typedef {object} DraftSpend
23
- * @property {string} sessionId
24
- * @property {number} spentUsd the known floor of the session's drafting spend
25
- * @property {boolean} spendComplete false = `spentUsd` is a floor ("at least")
26
- * @property {string|null} provider the worker's provider shape (`anthropic-api` | `openai-api` | ...)
27
- * @property {string|null} baseUrl
28
- * @property {string|null} model
29
- * @property {string} startedAt ISO, the first metered call
30
- * @property {string} updatedAt ISO, the latest metered call
31
- */
32
- /**
33
- * (Re)write `<dir>/draft-spend.json` atomically (tmp + rename).
34
- * @param {string} dir the session's folder
35
- * @param {DraftSpend} rec
36
- * @returns {void}
37
- */
38
- export function writeDraftSpend(dir: string, rec: DraftSpend): void;
39
- /**
40
- * Every session folder's drafting spend that never became a run.
22
+ * Every session folder's drafting spend that never became a run: folded from the log's `call` lines, else read from a legacy
23
+ * `draft-spend.json`; a folder with neither is skipped.
41
24
  * @param {{ home?: string, sessionsRoot?: string }} [opts] `home` = the bareloop config dir (as everywhere in src/monthly.js); the sessions live in `<home>/panel-sessions` unless `sessionsRoot` names them
42
25
  * @returns {DraftSpend[]}
43
26
  */
@@ -125,8 +108,9 @@ export function draftingPartFor(row: {
125
108
  home?: string;
126
109
  sessionsRoot?: string;
127
110
  }): any | null;
111
+ /** the OLD per-session total, no longer written; read only for a session folder that predates the log's call lines carrying it */
128
112
  export const DRAFT_SPEND_FILE: "draft-spend.json";
129
- /** the session's drafting LOG: an append-only JSONL beside draft-spend.json (one owner: the session, src/panel/authorsession.js). Three event kinds, see {@link DraftEvent}. */
113
+ /** the session's drafting LOG: an append-only JSONL (one owner: the session, src/panel/authorsession.js). Three event kinds, see {@link DraftEvent}. */
130
114
  export const DRAFT_LOG_FILE: "draft-log.jsonl";
131
115
  /**
132
116
  * One line of the drafting log. `no` = the step's position in the session's progress list (a step id can repeat).
@@ -135,7 +119,7 @@ export const DRAFT_LOG_FILE: "draft-log.jsonl";
135
119
  * - `step-label` {no, label, at} (the step reads `label` from now on, status and times untouched: the thinking row's "the model thought anyway" / "can't change it" / "not confirmed")
136
120
  * - `human` {no, source: 'confirm'|'try-3'|'look', question, answer, line?, at}: one question the person was asked and what they answered (the answer is secret-masked
137
121
  * before it is written; the row is written only when BOTH exist, so a question nobody answered leaves no row)
138
- * - `call` {no, step, label, model, thinking, thinkingSupport, thinkingStatus?, costUsd (null stays null), unpricedRounds, at}: one METERED model call
122
+ * - `call` {no, step, label, model, provider, baseUrl, thinking, thinkingSupport, thinkingStatus?, costUsd (null stays null), unpricedRounds, at}: one METERED model call
139
123
  * (`thinking` = the tick's mode: off | on; `thinkingSupport` = bare-agent's lookup for the model: true | false | 'unverified';
140
124
  * `thinkingStatus` = bare-agent's own verdict for the call's run: applied | unsupported | ignored | unknown, present only when thinkingMode was sent)
141
125
  * (no token counts: the call path does not carry them without reworking the library, so none are recorded)
@@ -2,6 +2,7 @@
2
2
  * @typedef {object} Panel one answered probe
3
3
  * @property {number} port @property {number} pid @property {string} version @property {number} drafts @property {number} schedules
4
4
  * @property {string} url
5
+ * @property {string|null} [startedAt] ISO time the panel process started (`whoami`); absent on an older panel
5
6
  */
6
7
  /**
7
8
  * @typedef {object} LauncherDeps every OS touch, injectable (a test passes all of them)
@@ -157,8 +158,27 @@ export function stopCmd(args: string[], io: {
157
158
  panels: Panel[];
158
159
  }): Promise<number>;
159
160
  /**
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
161
+ * `bareloop restart [--yes]` — the existing stop (same open-drafts warning and ask; `--yes` skips it), then the existing start, on the
162
+ * port the panel had when it is free again (else the normal first-free-port rule). No panel running: says so and just starts.
163
+ * No new process model, no pid file.
164
+ * @param {string[]} args
165
+ * @param {{out: (s: string) => void, err: (s: string) => void}} io @param {LauncherDeps & {version?: string}} d @param {{lines: string[], panels: Panel[]}} [shown]
166
+ * @returns {Promise<number>}
167
+ */
168
+ export function restartCmd(args: string[], io: {
169
+ out: (s: string) => void;
170
+ err: (s: string) => void;
171
+ }, d: LauncherDeps & {
172
+ version?: string;
173
+ }, shown?: {
174
+ lines: string[];
175
+ panels: Panel[];
176
+ }): Promise<number>;
177
+ /**
178
+ * The bare `bareloop` menu (PRD v1.114, one menu): the panel's four choices, the four job commands, one question. Runs the chosen command
179
+ * and returns its exit code. The job commands (6 export, 7 run, 8 resume, 9 history) are `d.jobs`, supplied by the CLI: each prompts for
180
+ * what it needs on the same asker this menu uses.
181
+ * @param {{out: (s: string) => void, err: (s: string) => void}} io @param {LauncherDeps & {version?: string, jobs?: {export: () => Promise<number>, run: () => Promise<number>, resume: () => Promise<number>, history: () => Promise<number>}}} d
162
182
  * @returns {Promise<number>}
163
183
  */
164
184
  export function menuCmd(io: {
@@ -166,6 +186,12 @@ export function menuCmd(io: {
166
186
  err: (s: string) => void;
167
187
  }, d: LauncherDeps & {
168
188
  version?: string;
189
+ jobs?: {
190
+ export: () => Promise<number>;
191
+ run: () => Promise<number>;
192
+ resume: () => Promise<number>;
193
+ history: () => Promise<number>;
194
+ };
169
195
  }): Promise<number>;
170
196
  /** the first port tried, and how many in a row (4700..4709) */
171
197
  export const PORT_START: 4700;
@@ -180,6 +206,10 @@ export type Panel = {
180
206
  drafts: number;
181
207
  schedules: number;
182
208
  url: string;
209
+ /**
210
+ * ISO time the panel process started (`whoami`); absent on an older panel
211
+ */
212
+ startedAt?: string | null | undefined;
183
213
  };
184
214
  /**
185
215
  * every OS touch, injectable (a test passes all of them)
package/types/learn.d.ts CHANGED
@@ -181,13 +181,14 @@ export function foldCards(cards: Card[]): Card[][];
181
181
  * @property {string[]} runIds
182
182
  * @property {string} firstSeen
183
183
  * @property {string} lastSeen
184
- * @property {string|null} specHash the signed hash the lesson was last seen under (a workflow row of another hash is never matched or read)
184
+ * @property {string|null} specHash the signed hash the lesson was last seen under (a record only; the job version is `workflowKey`)
185
+ * @property {string|null} [workflowKey] the workflow key (Reuse's rule: caps, time, source, destination, inputs and model do not move it) the lesson was last seen under; a workflow row of another key is never matched or read. Absent on rows an older version wrote: those match any version
185
186
  * @property {string} key check + sorted kinds (job-independent); information only since R2 removed the check-wide set-aside
186
187
  */
187
188
  /**
188
189
  * @typedef {object} Pending
189
190
  * @property {string} runid @property {string} at @property {string} workflow @property {string|null} place
190
- * @property {string|null} specHash @property {Card[]} cards
191
+ * @property {string|null} specHash @property {string|null} [workflowKey] @property {Card[]} cards
191
192
  */
192
193
  /**
193
194
  * @typedef {object} Ledger
@@ -209,20 +210,21 @@ export function lessonOf(c: Card): string;
209
210
  *
210
211
  * +1 per RUN per row: the run's own cards are folded into lessons first, and a row whose `runIds` already holds the
211
212
  * 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
+ * replaces the sample, lesson, key, lastSeen, hash, key and place (a leg-1 NEVER FIXED row becomes the leg-2 FIXED one). A
213
214
  * 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);
214
215
  * otherwise it opens a new row at count 1. NEVER FIXED cards count like FIXED ones (RULING 3). A workflow row of
215
- * another signed hash is never matched here: the new version opens its own rows. Nothing is ever deleted or stamped.
216
+ * another workflow key is never matched here: the new version opens its own rows. Nothing is ever deleted or stamped.
216
217
  * @param {Ledger} ledger
217
- * @param {{runid: string, cards: Card[], workflow: string, place: string|null, specHash: string|null, trust: 'deterministic'|'rubric', now: Date}} o
218
+ * @param {{runid: string, cards: Card[], workflow: string, place: string|null, specHash: string|null, workflowKey?: string|null, trust: 'deterministic'|'rubric', now: Date}} o
218
219
  * @returns {Ledger}
219
220
  */
220
- export function countLedger(ledger: Ledger, { runid, cards, workflow, place, specHash, trust, now }: {
221
+ export function countLedger(ledger: Ledger, { runid, cards, workflow, place, specHash, workflowKey, trust, now }: {
221
222
  runid: string;
222
223
  cards: Card[];
223
224
  workflow: string;
224
225
  place: string | null;
225
226
  specHash: string | null;
227
+ workflowKey?: string | null;
226
228
  trust: "deterministic" | "rubric";
227
229
  now: Date;
228
230
  }): Ledger;
@@ -238,15 +240,16 @@ export function climb(rows: Row[]): Row[];
238
240
  * 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
241
  * end); kept so a hold already in a ledger file still has a writer for tests and a reader in {@link releasePending}. Pure.
240
242
  * @param {Ledger} ledger
241
- * @param {{runid: string, cards: Card[], workflow: string, place: string|null, specHash: string|null, at: string}} o
243
+ * @param {{runid: string, cards: Card[], workflow: string, place: string|null, specHash: string|null, workflowKey?: string|null, at: string}} o
242
244
  * @param {Date} now @returns {Ledger}
243
245
  */
244
- export function holdPending(ledger: Ledger, { runid, cards, workflow, place, specHash, at }: {
246
+ export function holdPending(ledger: Ledger, { runid, cards, workflow, place, specHash, workflowKey, at }: {
245
247
  runid: string;
246
248
  cards: Card[];
247
249
  workflow: string;
248
250
  place: string | null;
249
251
  specHash: string | null;
252
+ workflowKey?: string | null;
250
253
  at: string;
251
254
  }, now: Date): Ledger;
252
255
  /**
@@ -286,30 +289,36 @@ export function saidLine(said: string[]): string | undefined;
286
289
  * derived HERE by {@link climb} over the rows not decayed at `now` only; the stored level is never read.
287
290
  * Order: this job's, then this place's, then all-jobs LAST (R2: climbing wins, so an all-jobs hint only uses leftover
288
291
  * room); inside each level highest count first (ties: most recent lastSeen, then id), so the order is total and stable.
289
- * @param {Ledger} ledger @param {{workflow: string, place: string|null, specHash?: string|null, now: Date}} o
292
+ * @param {Ledger} ledger @param {{workflow: string, place: string|null, workflowKey?: string|null, now: Date}} o
290
293
  * @returns {Row[]}
291
294
  */
292
- export function readableRows(ledger: Ledger, { workflow, place, specHash, now }: {
295
+ export function readableRows(ledger: Ledger, { workflow, place, workflowKey, now }: {
293
296
  workflow: string;
294
297
  place: string | null;
295
- specHash?: string | null;
298
+ workflowKey?: string | null;
296
299
  now: Date;
297
300
  }): Row[];
298
301
  /**
299
302
  * THE one render: the block the PLANNER reads at draft and at the first replan. Byte-for-byte reproducible from the
300
303
  * ledger as it stood. Stops at 2,000 characters; a hint is added whole or not at all; nothing readable -> empty text.
301
- * @param {Ledger} ledger @param {{workflow: string, place: string|null, specHash?: string|null, now: Date}} o
304
+ * @param {Ledger} ledger @param {{workflow: string, place: string|null, workflowKey?: string|null, now: Date}} o
302
305
  * @returns {{text: string, ids: string[]}}
303
306
  */
304
307
  export function renderHints(ledger: Ledger, o: {
305
308
  workflow: string;
306
309
  place: string | null;
307
- specHash?: string | null;
310
+ workflowKey?: string | null;
308
311
  now: Date;
309
312
  }): {
310
313
  text: string;
311
314
  ids: string[];
312
315
  };
316
+ /**
317
+ * The one plain-words line for a learnings file that could not be read (the Audit prints it; the spine keeps the full
318
+ * reason). The person's home folder is written `~`, so the line stays short and the file can still be found.
319
+ * @param {string} reason @param {string} [userHome] defaults to the OS home @returns {string}
320
+ */
321
+ export function hintsErrorLine(reason: string, userHome?: string): string;
313
322
  /**
314
323
  * Split a block {@link renderHints} wrote back into its hints. The ONLY reader of that text: it lives beside the
315
324
  * writer ({@link hintText}, {@link lessonOf}) and a test renders real blocks and parses them back. A hint it cannot
@@ -348,7 +357,7 @@ export function keyOfCard(c: {
348
357
  kinds: string[];
349
358
  }): string;
350
359
  export function isDecayed(r: Row, now: Date): boolean;
351
- export function otherJobVersion(r: Row, workflow: string, specHash: string | null): boolean;
360
+ export function otherJobVersion(r: Row, workflow: string, workflowKey: string | null | undefined): boolean;
352
361
  /**
353
362
  * PROPOSED header (hamr to confirm). States what the block is, where it came from, and that it is not an order.
354
363
  */
@@ -491,9 +500,13 @@ export type Row = {
491
500
  firstSeen: string;
492
501
  lastSeen: string;
493
502
  /**
494
- * the signed hash the lesson was last seen under (a workflow row of another hash is never matched or read)
503
+ * the signed hash the lesson was last seen under (a record only; the job version is `workflowKey`)
495
504
  */
496
505
  specHash: string | null;
506
+ /**
507
+ * the workflow key (Reuse's rule: caps, time, source, destination, inputs and model do not move it) the lesson was last seen under; a workflow row of another key is never matched or read. Absent on rows an older version wrote: those match any version
508
+ */
509
+ workflowKey?: string | null | undefined;
497
510
  /**
498
511
  * check + sorted kinds (job-independent); information only since R2 removed the check-wide set-aside
499
512
  */
@@ -505,6 +518,7 @@ export type Pending = {
505
518
  workflow: string;
506
519
  place: string | null;
507
520
  specHash: string | null;
521
+ workflowKey?: string | null | undefined;
508
522
  cards: Card[];
509
523
  };
510
524
  export type Ledger = {