bareloop 0.45.0 → 0.46.1

package/types/pagerules.d.ts

@@ -19,6 +19,12 @@ export function tieOf(from: unknown, jobLines: {
  * @param {unknown} shape @param {unknown} r @returns {boolean}
  */
 export function validReading(shape: unknown, r: unknown): boolean;
+/**
+ * The number written at the very end of `s` (only whitespace after it): the leftmost match of NUM followed by `\s*$`. Shared with src/pagedry.js (one copy). Scans back from the end, so a
+ * long run of digits and commas costs O(n) where a backtracking regex is quadratic.
+ * @param {string} s @returns {string|undefined}
+ */
+export function numberAtEnd(s: string): string | undefined;
 /**
  * Apply the rules to the AI's map over one saved page. Returns the kept facts and, for everything a rule removed, one `dropped` entry.
  * The order of the rules is the POC's (apply-v3.mjs): found-on-page, then the rules that read the page. A place is read as a phrase.
@@ -74,7 +80,7 @@ export type KeptFact = {
     reading?: Reading;
 };
 /**
- * `other` = what the drop is compared to: the first label (R1), the primary form (R1L), the fact it would have repeated (S1)
+ * `other` = what the drop is compared to: the first label (R1), the primary form (R1L), the fact it would have repeated (S1), the phrase it looked for (phrase-no-result)
  */
 export type Dropped = {
     line: number;

package/types/panel/status.d.ts

@@ -1,3 +1,11 @@
+/**
+ * ONE spelling of "this run's outcome is a green that can be reused" (the Reuse picker, the Reuse start/prefill, the Ended block's
+ * next line). hamr 2026-10-15: an `already-green` (fixed before any work) counts. `satisfied` is a close verdict, never a run outcome.
+ * The SCHEDULE gate (schedules.js greenFor) deliberately stays on a real `green` only (T3).
+ * @param {string|null|undefined} outcome
+ * @returns {boolean}
+ */
+export function isReusableGreen(outcome: string | null | undefined): boolean;
 /**
  * The status of one run.
  * @param {{outcome: string|null|undefined, died?: boolean, category?: string|null, moneyHalt?: boolean}} o

package/types/planrun.d.ts

@@ -149,6 +149,8 @@ export function boundedNote(bounded: {
  *   is STATED as well as enforced (the mailbox precedent again: a law only the validator
  *   knows costs a redraft per draft). The arms without it — `false` and `'diff'` — render
  *   byte-identically to the pre-shim prompt.
+ * @param {string|null} [hints] the cross-run learnings block (src/learn.js `renderHints`), verbatim; null/empty
+ *   renders byte-identically to the prompt without it. Only ever passed for the draft and the first replan.
  */
 export function planPrompt(job: any, scoutBlob: string, reds: any[] | null, maxStepRounds: number, failure: string | null, scopes: string[] | undefined, materials?: {
     balanceUsd?: number | null;
@@ -157,7 +159,7 @@ export function planPrompt(job: any, scoutBlob: string, reds: any[] | null, maxS
 }, startingDraft?: object | null, checkFacts?: {
     seedRed?: string[];
     priorChecks?: string[];
-}, doorNote?: string | null, readShim?: boolean | "cap" | "diff"): string;
+}, doorNote?: string | null, readShim?: boolean | "cap" | "diff", hints?: string | null): string;
 /**
  * Execute a validateJob-GREEN plan-shape job (goal/verdictType/close).
  * Called by runJob after the approval gate, validation, and the smoke — this
@@ -402,12 +404,16 @@ export function planPrompt(job: any, scoutBlob: string, reds: any[] | null, maxS
  *   the file, end the Loop after that round, and end the leg `stopped` (a checkpoint outcome, filed
  *   the way a mid-step cap-halt is; resume re-enters that step, or continues the phase). Nothing is in flight at that
  *   point, so the spend is exact. `null` = no stop surface (the default).
+ * @param {{text: string, ids: string[]}|null} [opts.learnHints=null] cross-run learnings (src/learn.js `renderHints`, made once at
+ *   run start from the ledger as it stood). Handed to the PLANNER only: the first draft and the FIRST replan. No worker ever
+ *   receives it, and a later replan gets nothing. Each injection is recorded on the spine as a `learnings` record (the exact
+ *   text) so the Audit can show it and the byte check can compare it with a fresh render. `null` = no hints (the default).
  * @returns {Promise<string>} 'green' | 'already-green' | 'escalated' | 'plan-red' |
  *   'check-red' | 'close-red' | 'close-unsupported' | 'recipe-stale' | 'pricing-red' |
  *   'branch-red' | 'cap-halt' | 'wall-halt' | 'stopped' | 'provider-red' | 'interpreter-red' |
  *   'step-stalled' | 'hitl-pause' | 'hitl-decision-red' | `step-red:<id>`
  */
-export function runPlan(job: any, { workdir, provider, nativeProvider, providerFor, judgeProvider, judgeModel, rates, judgeRates, emit, remainingUsd, isUnpriced, spendComplete, capRuns, strikeLimit, closeTimeoutMs, closeDir, maxStepRounds, layerRoot, readShim, scout, scoutRounds, bridge, now, priorWallMs, resumeSeed, resumeGrades, resumeReplans, resumeBranch, humanRuling, heldRuling, priorSpentUsd, reviewDoor, doorRerun, resumable, stopFile }: {
+export function runPlan(job: any, { workdir, provider, nativeProvider, providerFor, judgeProvider, judgeModel, rates, judgeRates, emit, remainingUsd, isUnpriced, spendComplete, capRuns, strikeLimit, closeTimeoutMs, closeDir, maxStepRounds, layerRoot, readShim, scout, scoutRounds, bridge, now, priorWallMs, resumeSeed, resumeGrades, resumeReplans, resumeBranch, humanRuling, heldRuling, priorSpentUsd, reviewDoor, doorRerun, resumable, stopFile, learnHints }: {
     workdir: string;
     provider: any;
     nativeProvider?: ((o: {
@@ -437,7 +443,7 @@ export function runPlan(job: any, { workdir, provider, nativeProvider, providerF
     maxStepRounds?: number | undefined;
     scout?: boolean | undefined;
     scoutRounds?: number | undefined;
-    readShim?: boolean | "cap" | "diff" | undefined;
+    readShim?: boolean | "diff" | "cap" | undefined;
     layerRoot?: boolean | undefined;
     bridge?: unknown;
     priorWallMs?: number | undefined;
@@ -471,6 +477,10 @@ export function runPlan(job: any, { workdir, provider, nativeProvider, providerF
     } | null | undefined;
     resumable?: boolean | undefined;
     stopFile?: string | null | undefined;
+    learnHints?: {
+        text: string;
+        ids: string[];
+    } | null | undefined;
 }): Promise<string>;
 export { rateSourceFields };
 /**

package/types/reuse.d.ts

@@ -414,7 +414,7 @@ export function runReuse(opts: {
     closeTimeoutMs?: number | undefined;
     closeDir?: string | undefined;
     layerRoot?: boolean | undefined;
-    readShim?: boolean | "cap" | "diff" | undefined;
+    readShim?: boolean | "diff" | "cap" | undefined;
     resume?: any;
     runJob?: typeof shippedRunJob | undefined;
     now?: (() => number) | undefined;

package/types/run.d.ts

@@ -198,6 +198,8 @@
  * @param {string|null} [opts.stopFile=null] P5 item 5 — the run's STOP REQUEST file
  *   (`stopFilePath(spine)`, src/legs.js), forwarded verbatim to the plan flow, which reads it at the
  *   round-boundary seam (where the money cap binds) and ends the leg `stopped`. `null` = no stop surface.
+ * @param {{text: string, ids: string[]}|null} [opts.learnHints=null] cross-run learnings for the PLANNER only (the draft and the
+ *   first replan); forwarded verbatim to the plan flow, which records what it handed over as a `learnings` spine record.
  * @returns {Promise<string>} outcome: 'green' | 'already-green' | 'escalated' |
  *   'unapproved-spec' | 'job-red' | 'smoke-red' | 'plan-red' | 'check-red' |
  *   'close-red' | 'close-unsupported' | 'recipe-stale' | 'branch-red' | 'pricing-red' | 'provider-red' |
@@ -212,7 +214,7 @@
  *   deliberately NOT in the resumable/checkpoint set (`src/reuse.js`) — an
  *   unknown in-flight state is not a known-safe resume point.
  */
-export function runJob(rawSpec: object | string, { approvals, workdir, provider, nativeProvider, providerFor, judgeProvider, judgeModel, rates, judgeRates, emit, capRuns, strikeLimit, shellCapUsd, closeTimeoutMs, closeDir, layerRoot, readShim, scout, bridge, draftSpentUsd, draftSpendComplete, priorSpentUsd, priorSpendComplete, priorWallMs, resumeSeed, resumeGrades, resumeReplans, resumeBranch, humanRuling, heldRuling, reviewDoor, doorRerun, resumable, stopFile }: {
+export function runJob(rawSpec: object | string, { approvals, workdir, provider, nativeProvider, providerFor, judgeProvider, judgeModel, rates, judgeRates, emit, capRuns, strikeLimit, shellCapUsd, closeTimeoutMs, closeDir, layerRoot, readShim, scout, bridge, draftSpentUsd, draftSpendComplete, priorSpentUsd, priorSpendComplete, priorWallMs, resumeSeed, resumeGrades, resumeReplans, resumeBranch, humanRuling, heldRuling, reviewDoor, doorRerun, resumable, stopFile, learnHints }: {
     approvals: unknown;
     workdir: string;
     provider: any;
@@ -255,7 +257,7 @@ export function runJob(rawSpec: object | string, { approvals, workdir, provider,
         grantUsed?: boolean;
     } | null | undefined;
     resumeBranch?: string | null | undefined;
-    readShim?: boolean | "cap" | "diff" | undefined;
+    readShim?: boolean | "diff" | "cap" | undefined;
     scout?: boolean | undefined;
     layerRoot?: boolean | undefined;
     humanRuling?: {
@@ -275,6 +277,10 @@ export function runJob(rawSpec: object | string, { approvals, workdir, provider,
     } | null | undefined;
     resumable?: boolean | undefined;
     stopFile?: string | null | undefined;
+    learnHints?: {
+        text: string;
+        ids: string[];
+    } | null | undefined;
 }): Promise<string>;
 /** @typedef {{code: string, path: string, detail?: string}} Red */
 /**

package/types/stagewords.d.ts

@@ -0,0 +1,91 @@
+/** `cmd`+`args`, as a comparable key — the one signal (besides `kind`
+ * itself) that two stages measure the SAME command's output, used to tell a
+ * genuine typecheck stage apart from the TYPES genre's other `lower-is-
+ * better`/`baseline: 0` stage (the failing-test-count half of `suite-green`'s
+ * "two assertions"), which shares that stage's own shape but not its
+ * population. `null` for a stage whose `cmd` isn't a non-empty string —
+ * never matches anything, so it never falsely suppresses a real typecheck
+ * question.
+ * @param {any} params @returns {string|null} */
+export function cmdKey(params: any): string | null;
+/**
+ * THE PLAIN-QUESTION OWNER (plain-checks build, 2026-09-28, hamr's ruling:
+ * the "checks N/M" headline is WITHDRAWN — "confusing, reads like 6 failed
+ * when 5 never ran"). ONE pure function mapping a declared stage's own
+ * signed `kind`+`params` (plus the close's own `genre`, also a signed field)
+ * to a short plain-English question a person can read without knowing the
+ * catalogue — never a second spelling on the client, and never anything the
+ * model authored (the catalogue's kinds/params are the whole vocabulary this
+ * reads).
+ *
+ * Every branch is traced straight off `src/kinds.js`'s runner semantics and
+ * the TYPES genre template (`src/authoring.js` `TYPES_GENRE_TEMPLATE`,
+ * `classGuards`'s `MECHANICAL_GUARDS`) — never guessed:
+ *   - `files-changed` is always the `changed-from-seed` guard: "did it
+ *     change any file?"
+ *   - `pattern-absent-in-diff` is always the `no-suppressions` guard: "no
+ *     casts or silencers added?"
+ *   - `rubric-step` (Part 1a) is one job line's output file: "line N — does its output pass the line's checks?"
+ *   - `command-exit` is the genre's `suite-green` stage (the only shipped use
+ *     of this kind): "does the test suite pass?"
+ *   - `count-not-worse` splits three ways on its own declared
+ *     `direction`/`baseline` (never the runtime number — see
+ *     {@link stageKindMetaFromSpec}'s own doc for why the baseline KIND must
+ *     travel separately from the measured figure):
+ *       - `higher-is-better` + `baseline: 'seed'` is the genre's `tests-kept`
+ *         floor: "did all the old tests still exist?"
+ *       - `lower-is-better` + `baseline: 0` is the genre's in-scope
+ *         `typecheck` stage — UNLESS its own `cmd`+`args` is the SAME
+ *         command a `command-exit` stage in the same close already runs
+ *         (`suiteCmdKeys`, below): the TYPES template's `suite-green` is "the
+ *         suite exits clean AND reports zero failing tests — TWO assertions"
+ *         over ONE population (the same `npm test`/`pytest` invocation), so a
+ *         `count-not-worse` stage sharing that exact command is the failing-
+ *         test-count half of that pair, never a typecheck stage: "no failing
+ *         tests?" — derived from the same cmd+args correlation (the stage
+ *         counts the suite's own failing tests), never from the stage's own
+ *         name string. The live check that found this (run mul5fofw's own
+ *         `suite-zero-failing-tests`, cmd `npm test`, same as its sibling
+ *         `suite-green` command-exit stage) would otherwise have read "test/
+ *         has 0 type errors?", which is false: its parser counts FAILING
+ *         TESTS (`^# fail (\d+)$`), not type-checker output. hamr's ruling:
+ *         name this half honestly rather than reusing "type errors" for a
+ *         population it was never about, or falling back to the stage's raw
+ *         name. When the command differs from every sibling `command-exit`
+ *         stage, the declared `scope.includePrefixes` naming exactly ONE path
+ *         is quoted verbatim (a signed param, never invented): "<path> has 0
+ *         type errors?" — otherwise the generic "type errors is 0?", never a
+ *         guessed filename.
+ *       - `lower-is-better` + `baseline: 'seed'` with a non-empty
+ *         `scope.excludePrefixes` is the genre's `typecheck-outside` ceiling:
+ *         "other files didn't get more type errors?"
+ * The "type errors" wording is genre-owned (`GENRE_WHAT`), because TYPES is
+ * the only genre this catalogue admits today (doc-genre kinds are not yet
+ * built) — an unrecognised genre, or a `count-not-worse` shape none of the
+ * three above matches, returns `null` rather than invent a fourth shape.
+ *
+ * `null` means "no honest plain question" — the caller (buildAttemptsList,
+ * partLine1Text's `attemptChecksLine`) falls back to the stage's OWN name,
+ * exactly as it already does for a stage with no resolvable kind at all.
+ * @param {{kind: string|null, params: any, genre: string|null, suiteCmdKeys: Set<string>}} o
+ * @returns {string|null}
+ */
+export function stageQuestionText({ kind, params, genre, suiteCmdKeys, }: {
+    kind: string | null;
+    params: any;
+    genre: string | null;
+    suiteCmdKeys: Set<string>;
+}): string | null;
+/**
+ * Stage name to its plain question, off a signed spec's `closeDecl.stages` — the one pass that gathers every
+ * `command-exit` stage's cmd+args FIRST (so the failing-test-count half of `suite-green`'s pair can be told from a
+ * genuine typecheck stage) and then asks {@link stageQuestionText} per stage. `null` for a stage with no honest
+ * question; an empty map for a spec with no declared stages.
+ * @param {any} spec
+ * @returns {Map<string, string|null>}
+ */
+export function stageQuestionsByName(spec: any): Map<string, string | null>;
+/** the genre-owned noun for the count a TYPES-genre typecheck stage measures (see {@link stageQuestionText}) */
+export const GENRE_WHAT: Readonly<{
+    TYPES: "type errors";
+}>;