bareloop 0.47.0 → 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.
@@ -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)
@@ -10,10 +11,11 @@
10
11
  * @property {number[]} [ports] an explicit port list (tests); wins over portStart/portCount
11
12
  * @property {number} [timeoutMs] probe timeout per port
12
13
  * @property {number} [deadlineMs] start/stop wait deadline
14
+ * @property {number} [silentWaitMs] how long start keeps asking a taken, silent port (default 10 s)
13
15
  * @property {string} [nodeVersion] default process.versions.node
14
16
  * @property {typeof fetch} [fetchImpl]
15
17
  * @property {(cmd: string, args: string[], o: object) => any} [spawnFn] default node:child_process spawn
16
- * @property {(pid: number, sig: string) => void} [kill] default process.kill
18
+ * @property {(pid: number, sig: string|number) => void} [kill] default process.kill
17
19
  * @property {((target: string) => Promise<boolean>)} [open] default the shared OS opener
18
20
  * @property {(port: number) => Promise<boolean>} [portFree] default: try to bind 127.0.0.1:port
19
21
  * @property {(ms: number) => Promise<void>} [sleep]
@@ -50,6 +52,24 @@ export function installState(o: {
50
52
  ok: boolean;
51
53
  problem: string | null;
52
54
  };
55
+ /**
56
+ * Ask one port for `/api/whoami`. Never throws. `silent` = no reply inside the timeout (a loaded or stuck process may still be a
57
+ * panel); `other` = something replied (or refused) and it is not a bareloop whoami.
58
+ * @param {{port: number, timeoutMs?: number, fetchImpl?: typeof fetch}} o
59
+ * @returns {Promise<{state: 'panel', panel: Panel}|{state: 'other'}|{state: 'silent'}>}
60
+ */
61
+ export function probePort(o: {
62
+ port: number;
63
+ timeoutMs?: number;
64
+ fetchImpl?: typeof fetch;
65
+ }): Promise<{
66
+ state: "panel";
67
+ panel: Panel;
68
+ } | {
69
+ state: "other";
70
+ } | {
71
+ state: "silent";
72
+ }>;
53
73
  /**
54
74
  * Ask 127.0.0.1 across the ports in parallel; a reply with `app === "bareloop"` is a panel. Never throws.
55
75
  * @param {{ports: number[], timeoutMs?: number, fetchImpl?: typeof fetch}} o
@@ -138,8 +158,27 @@ export function stopCmd(args: string[], io: {
138
158
  panels: Panel[];
139
159
  }): Promise<number>;
140
160
  /**
141
- * The bare `bareloop` menu: header, the four choices, one question. Runs the chosen command and returns its exit code.
142
- * @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
143
182
  * @returns {Promise<number>}
144
183
  */
145
184
  export function menuCmd(io: {
@@ -147,6 +186,12 @@ export function menuCmd(io: {
147
186
  err: (s: string) => void;
148
187
  }, d: LauncherDeps & {
149
188
  version?: string;
189
+ jobs?: {
190
+ export: () => Promise<number>;
191
+ run: () => Promise<number>;
192
+ resume: () => Promise<number>;
193
+ history: () => Promise<number>;
194
+ };
150
195
  }): Promise<number>;
151
196
  /** the first port tried, and how many in a row (4700..4709) */
152
197
  export const PORT_START: 4700;
@@ -161,6 +206,10 @@ export type Panel = {
161
206
  drafts: number;
162
207
  schedules: number;
163
208
  url: string;
209
+ /**
210
+ * ISO time the panel process started (`whoami`); absent on an older panel
211
+ */
212
+ startedAt?: string | null | undefined;
164
213
  };
165
214
  /**
166
215
  * every OS touch, injectable (a test passes all of them)
@@ -184,6 +233,10 @@ export type LauncherDeps = {
184
233
  * start/stop wait deadline
185
234
  */
186
235
  deadlineMs?: number | undefined;
236
+ /**
237
+ * how long start keeps asking a taken, silent port (default 10 s)
238
+ */
239
+ silentWaitMs?: number | undefined;
187
240
  /**
188
241
  * default process.versions.node
189
242
  */
@@ -196,7 +249,7 @@ export type LauncherDeps = {
196
249
  /**
197
250
  * default process.kill
198
251
  */
199
- kill?: ((pid: number, sig: string) => void) | undefined;
252
+ kill?: ((pid: number, sig: string | number) => void) | undefined;
200
253
  /**
201
254
  * default the shared OS opener
202
255
  */
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 = {
@@ -24,16 +24,17 @@ export function writeLedger(ledger: import("./learn.js").Ledger, home?: string):
24
24
  /**
25
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
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.
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
27
+ * @param {{home?: string, runid: string, build: import('./learn.js').CardBuild, workflow: string, place: string|null, specHash: string|null, workflowKey?: string|null, trust: 'deterministic'|'rubric', at: string, now?: Date}} o
28
28
  * @returns {{wrote: boolean, counted: number, held: number, problem: string|null}}
29
29
  */
30
- export function foldRunIntoLedger({ home, runid, build, workflow, place, specHash, trust, at, now }: {
30
+ export function foldRunIntoLedger({ home, runid, build, workflow, place, specHash, workflowKey, trust, at, now }: {
31
31
  home?: string;
32
32
  runid: string;
33
33
  build: import("./learn.js").CardBuild;
34
34
  workflow: string;
35
35
  place: string | null;
36
36
  specHash: string | null;
37
+ workflowKey?: string | null;
37
38
  trust: "deterministic" | "rubric";
38
39
  at: string;
39
40
  now?: Date;
@@ -57,8 +58,8 @@ export function releaseRun({ home, runid, now }: {
57
58
  problem: string | null;
58
59
  };
59
60
  /**
60
- * The ONE setting: `learningHints` in config.json. Ships OFF (absent = off). OFF still writes the tally ($0) and the planner
61
- * is simply handed nothing, so an ON/OFF contrast has data at once. An unreadable config reads as OFF.
61
+ * The ONE setting: `learningHints` in config.json. Ships ON (hamr 2026-10-24): absent = on; only an explicit `false` turns it off. OFF still writes
62
+ * the tally ($0) and the planner is simply handed nothing. An unreadable config reads as OFF (the safe side).
62
63
  * @param {string} [home]
63
64
  * @returns {boolean}
64
65
  */
@@ -68,16 +69,17 @@ export function learningHintsOn(home?: string): boolean;
68
69
  * ledger (a rubric job's count too, trust kept). Called once from the one engine's run-end block (src/userrun.js
69
70
  * `execute`, shared by the panel, the CLI and the bundle runner), inside its own try/catch: it is a record, never a verdict,
70
71
  * and can never change a run's outcome, exit code or spend. It runs whether the hints setting is on or off.
71
- * @param {{home?: string, runid: string, events: any[], auditFiles?: string[], spec: any, specHash: string|null, workdir: string|null, trust: 'deterministic'|'rubric', now?: Date}} o
72
+ * @param {{home?: string, runid: string, events: any[], auditFiles?: string[], spec: any, specHash: string|null, workflowKey?: string|null, workdir: string|null, trust: 'deterministic'|'rubric', now?: Date}} o
72
73
  * @returns {{wrote: boolean, counted: number, held: number, problem: string|null, noise: string|null, cards: number}}
73
74
  */
74
- export function learnAtRunEnd({ home, runid, events, auditFiles, spec, specHash, workdir, trust, now }: {
75
+ export function learnAtRunEnd({ home, runid, events, auditFiles, spec, specHash, workflowKey, workdir, trust, now }: {
75
76
  home?: string;
76
77
  runid: string;
77
78
  events: any[];
78
79
  auditFiles?: string[];
79
80
  spec: any;
80
81
  specHash: string | null;
82
+ workflowKey?: string | null;
81
83
  workdir: string | null;
82
84
  trust: "deterministic" | "rubric";
83
85
  now?: Date;
@@ -91,16 +93,35 @@ export function learnAtRunEnd({ home, runid, events, auditFiles, spec, specHash,
91
93
  };
92
94
  /**
93
95
  * The block the planner is handed for this job, made ONCE at run start from the ledger as it stood — empty when the
94
- * setting is off, when there is no ledger, or when nothing is readable. The one `renderHints` render, never a second.
95
- * @param {{home?: string, spec: any, specHash: string|null, now?: Date}} o
96
+ * setting is off, when there is no ledger, or when no lesson fits; an unreadable ledger THROWS (use {@link handedHints}, which
97
+ * hands nothing and keeps the reason). The one `renderHints` render, never a second.
98
+ * @param {{home?: string, spec: any, workflowKey?: string|null, now?: Date}} o
96
99
  * @returns {{text: string, ids: string[]}|null}
97
100
  */
98
- export function hintsForRun({ home, spec, specHash, now }: {
101
+ export function hintsForRun({ home, spec, workflowKey, now }: {
99
102
  home?: string;
100
103
  spec: any;
101
- specHash: string | null;
104
+ workflowKey?: string | null;
102
105
  now?: Date;
103
106
  }): {
104
107
  text: string;
105
108
  ids: string[];
106
109
  } | null;
110
+ /**
111
+ * {@link hintsForRun} for the engine: never throws. A broken ledger hands the planner nothing and the reason comes back
112
+ * (first line, secrets masked) so the run records it beside the hints; the run itself goes on.
113
+ * @param {{home?: string, spec: any, workflowKey?: string|null, now?: Date}} o
114
+ * @returns {{hints: {text: string, ids: string[]}|null, error: string|null}}
115
+ */
116
+ export function handedHints(o: {
117
+ home?: string;
118
+ spec: any;
119
+ workflowKey?: string | null;
120
+ now?: Date;
121
+ }): {
122
+ hints: {
123
+ text: string;
124
+ ids: string[];
125
+ } | null;
126
+ error: string | null;
127
+ };
@@ -1,4 +1,4 @@
1
- /** bareloop's own version, from its package.json (read each time the page is served); 'unknown' if it cannot be read, never a guess
1
+ /** bareloop's own version, from its package.json (read once when the panel starts); 'unknown' if it cannot be read, never a guess
2
2
  * @param {string} [file] test seam: another package.json
3
3
  * @returns {string} */
4
4
  export function packageVersion(file?: string): string;
@@ -124,9 +124,10 @@ export function legDividersFor(spineRecords: any[], parts: any[]): {
124
124
  * @param {{outcome: string|null, stopReason: string|null, spentUsd: number|null, budgetUsd: number|null, lastEscalation?: any}} summary
125
125
  * @param {{died: boolean, lastThing: string|null}} death
126
126
  * @param {{resume?: {ok: boolean, why?: string}|null, destinationRefused?: string|null, moneyHalt?: boolean,
127
- * worktree?: {folder: string, repo: string, branch: string|null, exists: boolean}|null}} [o]
127
+ * worktree?: {folder: string, repo: string, branch: string|null, exists: boolean}|null, exportName?: string|null}} [o]
128
128
  * `worktree` (P6 item 1): the run's worktree in the person's repo, from {@link worktreeOfRun}; absent for every other run
129
- * @returns {{reason: string, next: string, line: string, actions: {id: string, label: string}[]}|null}
129
+ * `exportName` (PRD v1.114): the run's `job (run-N)` name; a green worktree run (a repo job) shows the export command to copy beside the merge text
130
+ * @returns {{reason: string, next: string, rows?: [string, string][], line: string, actions: {id: string, label: string}[]}|null}
130
131
  */
131
132
  export function endedFor(summary: {
132
133
  outcome: string | null;
@@ -150,9 +151,11 @@ export function endedFor(summary: {
150
151
  branch: string | null;
151
152
  exists: boolean;
152
153
  } | null;
154
+ exportName?: string | null;
153
155
  }): {
154
156
  reason: string;
155
157
  next: string;
158
+ rows?: [string, string][];
156
159
  line: string;
157
160
  actions: {
158
161
  id: string;
@@ -782,11 +785,13 @@ export function getStartFromImport(id: string, opts?: {
782
785
  * only `createPanelServer` below always supplies one.
783
786
  * @param {import('node:http').IncomingMessage} req
784
787
  * @param {import('node:http').ServerResponse} res
785
- * @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
788
+ * @param {{ home?: string, sessionsRoot?: string, version?: string, startedAt?: 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
786
789
  */
787
790
  export function handleRequest(req: import("node:http").IncomingMessage, res: import("node:http").ServerResponse, opts: {
788
791
  home?: string;
789
792
  sessionsRoot?: string;
793
+ version?: string;
794
+ startedAt?: string;
790
795
  packageJsonPath?: string;
791
796
  port: number;
792
797
  token?: string;
@@ -0,0 +1,21 @@
1
+ /**
2
+ * One readline over `stdin`, with a LINE QUEUE: lines that arrive before the next question (piped input, a paste) wait for it instead
3
+ * of being dropped, and a closed stdin answers '' (the safe default) and never hangs.
4
+ * @param {{ stdin?: any, stdout?: any }} [io]
5
+ * @returns {{ ask: (q: string) => Promise<string>, close: () => void }}
6
+ */
7
+ export function openAsker(io?: {
8
+ stdin?: any;
9
+ stdout?: any;
10
+ }): {
11
+ ask: (q: string) => Promise<string>;
12
+ close: () => void;
13
+ };
14
+ /**
15
+ * A required prompt (hamr 2026-10-25): an empty Enter asks ONCE more; a second empty Enter gives up; `q` gives up at once. `null` = nothing was chosen
16
+ * (the caller ends its command cleanly: a plain line, nothing run, exit 0).
17
+ * @param {(q: string) => Promise<string>} ask @param {string} question
18
+ * @returns {Promise<string|null>}
19
+ */
20
+ export function askRequired(ask: (q: string) => Promise<string>, question: string): Promise<string | null>;
21
+ export function isQuit(s: string): boolean;
package/types/reuse.d.ts CHANGED
@@ -163,6 +163,9 @@ export function selectBridge({ registry, job, ask, provider, pinned, shortlist,
163
163
  forceCold?: boolean | undefined;
164
164
  exclude?: string[] | undefined;
165
165
  }): Promise<any>;
166
+ /** what the run's own spine says about a try, read back after it returns
167
+ * @param {any[]} events @returns {any} */
168
+ export function readTry(events: any[]): any;
166
169
  /**
167
170
  * Read a killed reuse run's OWN SPINE back into the state a resume continues from.
168
171
  *
@@ -0,0 +1,58 @@
1
+ /**
2
+ * Everything knowable about a run before any number is read: green (a run that was already green at start saved no plan), a signed spec
3
+ * beside it, a repo job, a saved plan made under that spec. The one check the list and the export share, so the list never offers
4
+ * what export would refuse for one of these reasons.
5
+ * @param {any} row a run-list row @param {string} name its `job (run-N)` name
6
+ * @returns {{ ok: true, records: any[], signed: { spec: any, specHash: string }, bf: any } | { ok: false, why: string }}
7
+ */
8
+ export function checkExportable(row: any, name: string): {
9
+ ok: true;
10
+ records: any[];
11
+ signed: {
12
+ spec: any;
13
+ specHash: string;
14
+ };
15
+ bf: any;
16
+ } | {
17
+ ok: false;
18
+ why: string;
19
+ };
20
+ /**
21
+ * The green panel / run-u runs export CAN take, oldest first, as `{name, runid, job}`. A run export would refuse for a reason knowable
22
+ * here (already green with no saved plan, a rubric / page-link / folder job, no signed spec) is not listed; a number it cannot read
23
+ * (cost, time, rounds, patient) is still refused at export, in words. Rows made by `bareloop run` or a backfill are not listed.
24
+ * @param {{ home?: string }} [opts]
25
+ * @returns {{ name: string, runid: string, job: string, at: string, outcome: string, row: any }[]}
26
+ */
27
+ export function listGreenRuns(opts?: {
28
+ home?: string;
29
+ }): {
30
+ name: string;
31
+ runid: string;
32
+ job: string;
33
+ at: string;
34
+ outcome: string;
35
+ row: any;
36
+ }[];
37
+ /**
38
+ * Build the bundle for one green run. Never throws for a run it cannot export: every stop is `{ok:false, why}` in plain words.
39
+ * @param {{ name: string, outDir: string, home?: string, bareloopVersion: string, now?: () => number }} o
40
+ * @returns {{ ok: true, runid: string, job: string, name: string, dir: string, bundleHash: string } | { ok: false, why: string }}
41
+ */
42
+ export function exportRun({ name, outDir, home, bareloopVersion, now }: {
43
+ name: string;
44
+ outDir: string;
45
+ home?: string;
46
+ bareloopVersion: string;
47
+ now?: () => number;
48
+ }): {
49
+ ok: true;
50
+ runid: string;
51
+ job: string;
52
+ name: string;
53
+ dir: string;
54
+ bundleHash: string;
55
+ } | {
56
+ ok: false;
57
+ why: string;
58
+ };
@@ -0,0 +1,40 @@
1
+ /**
2
+ * `<out>/source-<seed>/<job>-bareloop/u-<runid>.jsonl` -> the two files an
3
+ * authoring session leaves BESIDE that layout — `<out>/resolved-spec.json`
4
+ * (the signed spec `--spec`/a JOBS-table row ran) and
5
+ * `<out>/source-<seed>/source.json` (the source front door's manifest) —
6
+ * verified against `src/userrun.js`'s own construction (`specWorkdir = join(into,
7
+ * 'tree')`, `spineDir = join(wd, '..', target.spine)`, both `--spec` and the
8
+ * `pulselog-person-strict` JOBS-table row read `into` the same way) and a real
9
+ * archived run (pulselog-person-live-2, run mu2p83go): `dirname(spine)` is
10
+ * `<into>/<job>-bareloop`, `dirname(dirname(spine))` is `<into>` itself
11
+ * (`source-<seed>`, carrying `source.json`), and `dirname(dirname(dirname(spine)))`
12
+ * is `<out>` (carrying `resolved-spec.json`).
13
+ *
14
+ * Only resolves when `<into>`'s own name starts with `source-` — the one
15
+ * shape marker this convention always carries — and each file is checked to
16
+ * actually exist before being handed back; any other spine layout (the bundle
17
+ * `spine.jsonl`, a JOBS-table row whose workdir has no source-seed copy, e.g.
18
+ * `litectx-u`) returns both fields `null`, never a guessed path (build spec
19
+ * item 2, 2026-09-25: "don't search the disk broadly — fall through").
20
+ * @param {string} spinePath
21
+ * @returns {{ specPath: string|null, sourceJsonPath: string|null }}
22
+ */
23
+ export function sourceNearSpine(spinePath: string): {
24
+ specPath: string | null;
25
+ sourceJsonPath: string | null;
26
+ };
27
+ /**
28
+ * The signed spec a run's LATEST leg ran under — the `resolved-spec*.json` beside the run whose hash is the one its
29
+ * latest `job-start` carries (the same lookup `resumePlanFor` does). `null` = no such file.
30
+ * @param {{ spine: string }} row
31
+ * @param {any[]} records
32
+ * @returns {{spec: any, specPath: string, specHash: string}|null}
33
+ */
34
+ export function signedSpecForRun(row: {
35
+ spine: string;
36
+ }, records: any[]): {
37
+ spec: any;
38
+ specPath: string;
39
+ specHash: string;
40
+ } | null;