bareloop 0.44.0 → 0.46.0

package/src/schedulewords.js

@@ -232,7 +232,7 @@ export function startedAuditWords(rec, originNo) {
 
 /** a refusal's own words without its trailing "Nothing started." @param {unknown} why */
 function reasonOf(why) {
-  return String(why ?? '').replace(/\s*Nothing (started|spent)\.\s*$/, '').trim().replace(/\.$/, '');
+  return String(why ?? '').replace(/(?<!\s)\s*Nothing (started|spent)\.\s*$/, '').trim().replace(/\.$/, '');
 }
 
 /**

package/src/source.js

@@ -1273,7 +1273,7 @@ export async function proveRubricInputs({ inputs, into, destination, fetchUrl =
     labels.add(label.toLowerCase());
     if (isWebUrl(value)) {
       const got = await fetchUrl(value.trim());
-      if (!got.ok) return bad('input-url-unreadable', n, `${got.error.replace(/[.\s]+$/, '')}.`);
+      if (!got.ok) return bad('input-url-unreadable', n, `${got.error.replace(/(?<![.\s])[.\s]+$/, '')}.`);
       const pageBuf = Buffer.from(got.text, 'utf8');
       const leak = secretPatternNames(got.text);
       if (leak.length) return bad('input-url-secret', n, `the page at ${got.url} carries a known secret shape (${leak.join(', ')}) - refused, secrets never enter a job.`);

package/src/stagewords.js

@@ -0,0 +1,144 @@
+// The ONE owner of a stage's plain question ("did it change any file?", "no failing tests?"). Moved out of
+// src/panel/server.js (verbatim) so the Audit/step map AND the learnings cards read the same sentence from the same
+// code — a second spelling is how two screens come to disagree about one check. Pure; no file IO, no model.
+
+/**
+ * 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 const GENRE_WHAT = Object.freeze({ TYPES: 'type errors' });
+
+/** `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) {
+  if (!params || typeof params.cmd !== 'string' || params.cmd.length === 0) return null;
+  const args = Array.isArray(params.args) ? params.args : [];
+  return JSON.stringify([params.cmd, args]);
+}
+
+export function stageQuestionText({
+  kind, params, genre, suiteCmdKeys,
+}) {
+  if (kind === 'files-changed') return 'did it change any file?';
+  if (kind === 'pattern-absent-in-diff') return 'no casts or silencers added?';
+  if (kind === 'command-exit') return 'does the test suite pass?';
+  // Part 1a: one rubric-step stage = one job line's output file
+  if (kind === 'rubric-step') return params && Number.isInteger(params.step) ? `line ${params.step} — does its output pass the line's checks?` : null;
+  if (kind !== 'count-not-worse' || !params || typeof params !== 'object') return null;
+  const what = Object.hasOwn(GENRE_WHAT, String(genre)) ? GENRE_WHAT[String(genre)] : null;
+  if (params.direction === 'higher-is-better' && params.baseline === 'seed') {
+    return 'did all the old tests still exist?';
+  }
+  if (!what) return null;
+  const scope = params.scope && typeof params.scope === 'object' ? params.scope : null;
+  if (params.direction === 'lower-is-better' && params.baseline === 0) {
+    const key = cmdKey(params);
+    if (key !== null && suiteCmdKeys instanceof Set && suiteCmdKeys.has(key)) return 'no failing tests?';
+    const include = scope && Array.isArray(scope.includePrefixes) ? scope.includePrefixes : null;
+    if (include && include.length === 1 && typeof include[0] === 'string' && include[0].length > 0) {
+      return `${include[0]} has 0 ${what}?`;
+    }
+    return `${what} is 0?`;
+  }
+  if (params.direction === 'lower-is-better' && params.baseline === 'seed') {
+    const exclude = scope && Array.isArray(scope.excludePrefixes) ? scope.excludePrefixes : null;
+    if (exclude && exclude.length > 0) return `other files didn't get more ${what}?`;
+    return null;
+  }
+  return 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) {
+  /** @type {Map<string, string|null>} */
+  const out = new Map();
+  if (!spec || typeof spec !== 'object' || !spec.closeDecl || !Array.isArray(spec.closeDecl.stages)) return out;
+  const genre = typeof spec.closeDecl.genre === 'string' ? spec.closeDecl.genre : null;
+  /** @type {Set<string>} */
+  const suiteCmdKeys = new Set();
+  for (const s of spec.closeDecl.stages) {
+    if (s && s.kind === 'command-exit') {
+      const key = cmdKey(s.params);
+      if (key !== null) suiteCmdKeys.add(key);
+    }
+  }
+  for (const s of spec.closeDecl.stages) {
+    if (!s || typeof s.name !== 'string' || s.name.length === 0) continue;
+    const kind = typeof s.kind === 'string' ? s.kind : null;
+    const params = s.params && typeof s.params === 'object' ? s.params : null;
+    out.set(s.name, stageQuestionText({ kind, params, genre, suiteCmdKeys }));
+  }
+  return out;
+}

package/src/text.js

@@ -42,10 +42,12 @@ const FENCE_PREAMBLE_LINES = 5;
  */
 export function extractArtifact(t) {
   const text = String(t ?? '');
-  const m = text.match(/```[^\n`]*\n?([\s\S]*?)```/);
+  // (?=([^\n`]*))\1 reads the info string atomically: giving characters back can never find a closing fence the full read missed (a fence starts with a
+  // backtick, which the info string excludes), so an unclosed "```aaaa..." fails once instead of once per giveback (quadratic). The body is group 2.
+  const m = text.match(/```(?=([^\n`]*))\1\n?([\s\S]*?)```/);
   if (m) {
     if (text.slice(0, /** @type {number} */ (m.index)).split('\n').length - 1 < FENCE_PREAMBLE_LINES) {
-      const code = m[1].trim();
+      const code = m[2].trim();
       return code ? { code, red: null } : { code: null, red: 'empty fenced block' };
     }
     // deep fence = the artifact's own content: verbatim, NO fence strips — the

package/src/userrun.js

@@ -82,6 +82,7 @@ import { keysForDoor } from './keysfile.js';
 import { parseJsonl } from './replayio.js';
 import { claimRun, monthlyRefusalText, legSpend, chainSpend } from './monthly.js';
 import { ConfigError } from './config.js';
+import { learnAtRunEnd, hintsForRun, releaseRun } from './learnstore.js';
 import { commandFor } from './invoke.js';
 import { judgeRatesFor, keyNameFor, keyValueOf, priceReadout, ratesFor, ratesOfLine, resolveWorker, judgeRowFor, rowsForHome, REFUSE_NAME_MODEL } from './providerrows.js';
 // the banner's wall arithmetic, extracted so it is reachable by a test (F83): the
@@ -1306,6 +1307,11 @@ async function execute(ctx) {
     if (RULING.decision !== 'rerun') {
       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.`);
       if (RULING.decision === 'accept') {
+        // Cross-run learnings: the human Accept is what releases a held rubric run's lessons so they count (forward only; a rerun or a
+        // pause never does). Its own try/catch: a record, never a verdict.
+        if (cfgOn && DOOR !== null) {
+          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]}).`); }
+        }
         out(`  proved   ${ans.mechanical?.ran ?? 0} mechanical stage(s) re-ran on the tree as it stands, and passed — an accept is not a rubber stamp`);
         out(`  credit   ${ans.released ? 'RELEASED — this workflow is now eligible for reuse' : ((ctx.registry ?? null) === null ? 'not released: no --registry was named, so there is no entry to release (the answer is on the spine)' : (quarantinesCredit(spec.verdictType) ? 'nothing left to release — this row was already released by an earlier accept (a repeat answer records nothing new)' : 'nothing was held to release — a green-class row is minted born RELEASED (hamr, 2026-08-30): a machine proved it, so there was never a credit to quarantine'))}`);
         if (ans.note) out(`  note     ${ans.note}`);
@@ -1895,10 +1901,18 @@ async function execute(ctx) {
   // honours it, and the `finally` below clears whatever is left when the leg ends.
   const stopFile = stopFilePath(spineFile);
   try { rmSync(stopFile, { force: true }); } catch { /* best-effort — a stop surface must never kill the run */ }
+  // Cross-run learnings (src/learn.js): the PLANNER's block, made once from the ledger as it stood — empty when the one setting
+  // (`learningHints` in config.json) is off. A record read, never a verdict: a failure here is no hints, never a failed run.
+  /** @type {{text: string, ids: string[]}|null} */
+  let learnHints = null;
+  if (cfgOn) {
+    try { learnHints = hintsForRun({ home: cfgHome, spec, specHash }); } catch { learnHints = null; }
+  }
   let outcome;
   try {
     outcome = await runJob(spec, {
       stopFile,
+      ...(learnHints === null ? {} : { learnHints }),
       // PRD item 27/M3 — the SAME `emit` the pre-run close-timing reading above
       // used (never a second `makeSpine(spineFile)` here: two independent
       // emitters against one file would both start their seq counter at 0 and
@@ -2010,6 +2024,20 @@ async function execute(ctx) {
       appendRunEvent({ runid, type: 'settled', by: runid, spentUsd: fin.usd, spendComplete: fin.complete, at: new Date().toISOString(), ...(LEG > 1 ? { leg: LEG } : {}) }, { home: cfgHome });
     } 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.`); }
   }
+  // The run-end tally of cross-run learnings ($0, code only, no model): the whole spine (all legs) and the gate audit become cards
+  // folded into the ONE ledger (a rubric job's are held until the human Accept). Its own try/catch, like the settle above: a
+  // record, never a verdict — a failure prints one WARNING line and can never change the outcome, the exit code or the spend.
+  // `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
+  // on or off (OFF only means the planner is handed nothing). With no config home (a test with an injected env) it writes nothing.
+  if (je && cfgOn) {
+    try {
+      const filedAudit = ctx.bundle ? join(spineDir, 'gate-audit.jsonl') : join(spineDir, `u-${runid}-gate-audit.jsonl`);
+      learnAtRunEnd({
+        home: cfgHome, runid, events: allEvents, auditFiles: [filedAudit, join(wd, 'gate-audit.jsonl')], spec, specHash, workdir: wd,
+        trust: quarantinesCredit(spec.verdictType) ? 'rubric' : 'deterministic',
+      });
+    } 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.`); }
+  }
   // the ONE spelling of the text-side scan (src/validate.js) — a hand-rolled copy
   // here would be the ninth, and one that misses a shape leaks on the very output
   // it guards. Only the COUNT is ever read out; the matches themselves stay here.

package/src/validate.js

@@ -167,14 +167,19 @@ export function closeScriptCandidateToken(cmd) {
 // redactor passes is a leak on the very output the validator was guarding.
 export const SECRET_PATTERNS = [
   /(?<![A-Za-z0-9_-])sk-[A-Za-z0-9_-]{16,}/,
-  /(?<![A-Za-z0-9_-])ghp_[A-Za-z0-9]{20,}/,
-  /(?<![A-Za-z0-9_-])github_pat_[A-Za-z0-9_]{20,}/,
-  /(?<![A-Za-z0-9_-])AKIA[0-9A-Z]{16}/,
-  /(?<![A-Za-z0-9_-])xox[bap]-[A-Za-z0-9-]{10,}/,
+  // The prefixes below are distinctive (an ordinary hyphenated word never starts with `ghp_`, `AKIA`, ...), so their left bound
+  // drops only the `-`: a key right after a hyphen (`step-ghp_...`) is still a key. `sk-` keeps the full bound above, because
+  // `sk-` ends real words (`task-`, `desk-`, `risk-`...). KNOWN LIMIT: an `sk-` key directly after a hyphen or word character
+  // (`step-sk-...`) is not found by THIS inventory, so the scan (validator, source door, pagefetch) misses it. (Measured: the
+  // redactor still masks it today, but through bareguard's own built-in `sk-` shape, not through this list.)
+  /(?<![A-Za-z0-9_])ghp_[A-Za-z0-9]{20,}/,
+  /(?<![A-Za-z0-9_])github_pat_[A-Za-z0-9_]{20,}/,
+  /(?<![A-Za-z0-9_])AKIA[0-9A-Z]{16}/,
+  /(?<![A-Za-z0-9_])xox[bap]-[A-Za-z0-9-]{10,}/,
   // Google/Gemini API key: `AIza` + 35 chars of [0-9A-Za-z_-] (39 total, fixed
   // length by Google's own issuance format). Admitted with the gemini-api
   // provider (PRD item 31.3, F160) — was missing on this branch until then.
-  /(?<![A-Za-z0-9_-])AIza[0-9A-Za-z_-]{35}/,
+  /(?<![A-Za-z0-9_])AIza[0-9A-Za-z_-]{35}/,
 ];
 const SECRET_RE = new RegExp(SECRET_PATTERNS.map((r) => r.source).join('|'));
 

package/src/worktree.js

@@ -101,7 +101,8 @@ const COMMIT_CONFIG = [
 ];
 
 /** what never goes into the work commit: the arbiter's own books and installed packages */
-const NOT_WORK = [':(exclude).smoke', ':(exclude).litectx', ':(exclude)gate-audit.jsonl', ':(exclude,glob)**/node_modules/**'];
+const NOT_WORK_PATHS = ['.smoke', '.litectx', 'gate-audit.jsonl'];
+const NOT_WORK_GLOB = ':(exclude,glob)**/node_modules/**';
 
 /**
  * The run's final commit, on whatever branch the worktree stands on: everything the run changed except the
@@ -113,7 +114,12 @@ const NOT_WORK = [':(exclude).smoke', ':(exclude).litectx', ':(exclude)gate-audi
  */
 export function commitWork(dir, message) {
   const run = (/** @type {string[]} */ args) => execFileSync('git', ['-C', dir, ...COMMIT_CONFIG, ...args], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
-  run(['add', '-A', '--', '.', ...NOT_WORK]);
+  // `git add` exits 1 when an exclude names a path that exists AND is gitignored (it prints "paths are ignored").
+  // An ignored path is never staged without -f, so its exclude is redundant: only exclude what git would otherwise add.
+  // check-ignore: 0 = ignored, 1 = not ignored, anything else = a real failure (execFileSync throws on 128).
+  const ignored = (/** @type {string} */ p) => { try { run(['check-ignore', '-q', '--', p]); return true; } catch (e) { if (/** @type {any} */ (e)?.status === 1) return false; throw e; } };
+  const excludes = NOT_WORK_PATHS.filter((p) => !ignored(p)).map((p) => `:(exclude)${p}`);
+  run(['add', '-A', '--', '.', ...excludes, NOT_WORK_GLOB]);
   const staged = run(['diff', '--cached', '--name-only']).trim();
   if (staged !== '') run(['commit', '-q', '-m', message]);
   return { committed: staged !== '', sha: run(['rev-parse', '--short', 'HEAD']).trim() };

package/types/attemptdiff.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Cut `text` to at most `max` bytes at a LINE boundary (never mid-line).
+ * @param {string} text @param {number} max
+ * @returns {{text: string, truncated: boolean, cutLines: number}}
+ */
+export function cutAtLine(text: string, max: number): {
+    text: string;
+    truncated: boolean;
+    cutLines: number;
+};
+/**
+ * Begin recording one worker try. Call BEFORE the worker's turn; call `finish()` after
+ * (in a `finally`). Never throws.
+ * @param {{workdir: string, fence: string[], redact?: (s: string) => string}} o
+ *   `fence` = the ABSOLUTE write-scope prefixes the gate enforces for this try.
+ * @returns {Promise<{finish: () => Promise<null | {files: {path: string, diff: string, truncated: boolean, cutLines: number}[], binary: string[], truncated: boolean, gitError?: string}>}>}
+ *   `finish()` resolves null when the try changed nothing in scope.
+ */
+export function startAttemptDiff({ workdir, fence, redact }: {
+    workdir: string;
+    fence: string[];
+    redact?: (s: string) => string;
+}): Promise<{
+    finish: () => Promise<null | {
+        files: {
+            path: string;
+            diff: string;
+            truncated: boolean;
+            cutLines: number;
+        }[];
+        binary: string[];
+        truncated: boolean;
+        gitError?: string;
+    }>;
+}>;
+/** per-file and per-event byte caps for the recorded diff text */
+export const ATTEMPT_DIFF_FILE_MAX: 4096;
+export const ATTEMPT_DIFF_EVENT_MAX: 16384;

package/types/authorjob.d.ts

@@ -87,7 +87,8 @@ export function refuseLockedKind(kind: string): Refusal;
  *   rates?: {in: number, out: number}|null, draftThinking?: 'on'|'off',
  *   onPhase?: (phase: string, data?: any) => void,
  *   onCall?: (call: {label: string, costUsd: number|null, unpricedRounds: number, thinkingStatus?: string}) => void,
- *   seedFn?: Function, scoutFn?: Function, listingFn?: Function, lookFn?: Function|null,
+ *   seedFn?: Function, scoutFn?: Function, listingFn?: Function, lookFn?: Function|null, fitFn?: Function|null,
+ *   fitAsk?: ((question: string) => Promise<string|null>)|null, onFit?: (fit: {state: string, asks: any[], notFound: any[]}) => void,
  *   authorFn?: Function, authorOpts?: object, writeScope?: string[]|null,
  *   signerFix?: Function|any, proposeFn?: Function, compileOpts?: object,
  *   ask?: ((step: {kind: string, [k: string]: any}) => Promise<string|null>)|null,
@@ -99,7 +100,7 @@ export function refuseLockedKind(kind: string): Refusal;
  *   closeDecl: any, seedRef: string|null, authoring: any, judged: any, reds: Red[],
  *   stop: string|null, cost: any, interview: any, confirmed: any}>}
  */
-export function authorCloseForJob({ answers, repoPath, lang, verdictType, questions, jobLines, inputs, generate, provider, seedRef, scout, listing, ceilingUsd, rates, draftThinking, writeScope, judgeModel, onPhase, onCall, seedFn, scoutFn, listingFn, lookFn, authorFn, authorOpts, signerFix, proposeFn, compileOpts, ask, confirmGenerate, isRepo, langResult, answerQuestions, }: {
+export function authorCloseForJob({ answers, repoPath, lang, verdictType, questions, jobLines, inputs, generate, provider, seedRef, scout, listing, ceilingUsd, rates, draftThinking, writeScope, judgeModel, onPhase, onCall, seedFn, scoutFn, listingFn, lookFn, fitFn, fitAsk, onFit, authorFn, authorOpts, signerFix, proposeFn, compileOpts, ask, confirmGenerate, isRepo, langResult, answerQuestions, }: {
     answers: Record<string | number, any>;
     repoPath?: string | null;
     lang: string;
@@ -137,6 +138,13 @@ export function authorCloseForJob({ answers, repoPath, lang, verdictType, questi
     scoutFn?: Function;
     listingFn?: Function;
     lookFn?: Function | null;
+    fitFn?: Function | null;
+    fitAsk?: ((question: string) => Promise<string | null>) | null;
+    onFit?: (fit: {
+        state: string;
+        asks: any[];
+        notFound: any[];
+    }) => void;
     authorFn?: Function;
     authorOpts?: object;
     writeScope?: string[] | null;

package/types/config.d.ts

@@ -36,7 +36,7 @@ export function modelsProblem(list: unknown): string | null;
  * `keys` merges per key variable name, then per field; `models.<ENV>` is REPLACED WHOLE (`null`
  * clears it). Validated before anything is written; nothing is written on a refusal.
  *
- * Patch fields understood: `monthlyLimitUsd` (finite > 0), `keys.<ENV>.{shape,baseUrl,legacyMaxTokens}`,
+ * Patch fields understood: `monthlyLimitUsd` (finite > 0), `learningHints` (true | false), `keys.<ENV>.{shape,baseUrl,legacyMaxTokens}`,
  * `models.<ENV>` (a list judged by {@link modelsProblem}). The first write of a row's `models` list
  * removes that row's older `name` / `priceInPerM` / `priceOutPerM` in the SAME write (never two
  * sources); a retired top-level `anthropicBalanceNote` is dropped on any write. Any other field is

package/types/fitcheck.d.ts

@@ -0,0 +1,113 @@
+/**
+ * What the AI is told: the job lines (the numbered text only, no `~` rules) and the WHOLE text of every input under its label. Adapted from the POC
+ * call (.claude/scratch/fit-poc6/run.mjs): the asks are copied from each job line instead of hand-written.
+ * @param {{jobLines: {n: number, text: string}[], texts: Record<string, string>}} o
+ * @returns {string}
+ */
+export function fitPrompt({ jobLines, texts }: {
+    jobLines: {
+        n: number;
+        text: string;
+    }[];
+    texts: Record<string, string>;
+}): string;
+/**
+ * Read the AI's reply and decide, all in code. Malformed (no repair): not JSON, another form, a line that is not a job line, an ask not copied from its own
+ * line, found not a boolean, a quote neither text nor null, or a job line with no ask. An ask is found only if `found` is true AND its quote is on a page;
+ * `found` with a quote that is not on any page (or no quote) is made up and counts as not found.
+ * @param {unknown} text the reply
+ * @param {{n: number, text: string}[]} jobLines
+ * @param {Record<string, string>} texts the frozen input texts by label
+ * @returns {{status: 'malformed'}|{status: 'ok', state: 'fits'|'ask', asks: FitAsk[], notFound: {line: number, ask: string}[]}}
+ */
+export function decideFit(text: unknown, jobLines: {
+    n: number;
+    text: string;
+}[], texts: Record<string, string>): {
+    status: "malformed";
+} | {
+    status: "ok";
+    state: "fits" | "ask";
+    asks: FitAsk[];
+    notFound: {
+        line: number;
+        ask: string;
+    }[];
+};
+/**
+ * Run the fit check: one call (one retry on a malformed reply or a transport failure or a 429). Never throws on a call casualty; every failure is `absent`.
+ * @param {{jobLines: {n: number, text: string}[], texts: Record<string, string>, provider?: any, maxTokens?: number, ceilingUsd?: number|null,
+ *   callTimeoutMs?: number, onCall?: (call: {label: string, costUsd: number|null, unpricedRounds: number, thinkingStatus?: string, raw?: string}) => void,
+ *   createLoop?: Function, rates?: {in: number, out: number}|null, callOptions?: Record<string, any>, sleep?: (ms: number) => Promise<void>}} o
+ * @returns {Promise<{state: 'fits'|'ask'|'absent', asks: FitAsk[], notFound: {line: number, ask: string}[], reason: string|null, cause: string|null,
+ *   calls: {label: string, costUsd: number|null, unpricedRounds: number}[], budgetStop: 'cap-halt'|'pricing-red'|null}>}
+ */
+export function runFitCheck({ jobLines, texts, provider, maxTokens, ceilingUsd, callTimeoutMs, onCall, createLoop, rates, callOptions, sleep, }: {
+    jobLines: {
+        n: number;
+        text: string;
+    }[];
+    texts: Record<string, string>;
+    provider?: any;
+    maxTokens?: number;
+    ceilingUsd?: number | null;
+    callTimeoutMs?: number;
+    onCall?: (call: {
+        label: string;
+        costUsd: number | null;
+        unpricedRounds: number;
+        thinkingStatus?: string;
+        raw?: string;
+    }) => void;
+    createLoop?: Function;
+    rates?: {
+        in: number;
+        out: number;
+    } | null;
+    callOptions?: Record<string, any>;
+    sleep?: (ms: number) => Promise<void>;
+}): Promise<{
+    state: "fits" | "ask" | "absent";
+    asks: FitAsk[];
+    notFound: {
+        line: number;
+        ask: string;
+    }[];
+    reason: string | null;
+    cause: string | null;
+    calls: {
+        label: string;
+        costUsd: number | null;
+        unpricedRounds: number;
+    }[];
+    budgetStop: "cap-halt" | "pricing-red" | null;
+}>;
+/** the label of the one paid call, as the drafting book and the progress line see it */
+export const FIT_CALL_LABEL: "fit-check";
+/** what the chat says when the check did not finish (drafting goes on) */
+export const FIT_ABSENT_NOTE: "The fit check did not finish; drafting goes on.";
+/** the answer that keeps drafting after the fit question (any case, a closing full stop allowed) */
+export const FIT_GO_ON: "go on";
+export function isGoOn(text: unknown): boolean;
+export const FIT_SYSTEM: "You check whether saved web pages show what a job asks for. You never invent words: every ask must be copied from its job line and every quote must be copied from the page, character for character.";
+export function norm(s: unknown): string;
+export function notFoundList(notFound: {
+    line: number;
+    ask: string;
+}[]): string;
+export function fitQuestionText({ found, total, notFound }: {
+    found: number;
+    total: number;
+    notFound: {
+        line: number;
+        ask: string;
+    }[];
+}): string;
+export type FitAsk = {
+    line: number;
+    ask: string;
+    found: boolean;
+    quote: string | null;
+    madeUp: boolean;
+    ignored?: "number";
+};

package/types/inputlook.d.ts

@@ -185,29 +185,6 @@ export function labelListsOf(texts: Record<string, string>): {
     scans: Record<string, import("./labelscan.js").LabelScan>;
     lists: Record<string, string>;
 };
-/**
- * L3: a reason the AI gave, cut only at a sentence end (never mid-sentence): whole sentences while they fit in `max` characters,
- * and nothing at all if the first one alone does not fit. A trailing full stop is dropped (the caller closes the clause).
- * @param {string} text @param {number} max @returns {string}
- */
-export function wholeSentences(text: string, max: number): string;
-/**
- * I1 (hamr, 2026-10-13, "Ruled by hamr" 2): when the look shows the person's intent on one `~` rule was NOT captured - its words or
- * meaning are not in the source - the person is asked about THAT rule at once, named by its line and rule. Only a look entry that names
- * a rule number counts; anything else the look could not find is not asked piecemeal (it is Not checked, or the whole job is reviewed).
- * The wording is the code's own, never the model's. The keep-or-drop and the cap are `normalizeQuestions` (src/authorflow.js).
- * @param {LookNotFound[]} notFound @param {{n: number, text?: string, rule?: string, rules?: string[]}[]} jobLines
- * @returns {{line: number, question: string}[]} every candidate question (the caller applies the machine's caps)
- */
-export function ruleQuestions(notFound: LookNotFound[], jobLines: {
-    n: number;
-    text?: string;
-    rule?: string;
-    rules?: string[];
-}[]): {
-    line: number;
-    question: string;
-}[];
 /** the name of the answer tool - the one place the AI's report enters */
 export const LOOK_REPORT_TOOL: "report_look";
 /** how many hits one search returns at most, and how long a snippet or a read line is */

package/types/labelscan.d.ts

@@ -29,6 +29,12 @@ export const MIN_COUNT: 1;
 export const MAX_PER_SHAPE: 40;
 /** only this much of a source is scanned (a source over it is scanned up to a line end) */
 export const SCAN_MAX_CHARS: 2000000;
+/**
+ * The page reader's bracketed tag (`[ref=549]`), shared by the three places that strip it. The lookahead and lookbehind add no match and drop no
+ * match: a `[` that sits inside the run of an earlier `[letters=` (no `]` or white space between) is skipped, because that earlier start reads the same
+ * run to the same end - it matches (and consumes this one) or fails (and so does this one). Without them "[a=[a=[a=..." with no `]` is quadratic.
+ */
+export const TAG: RegExp;
 export type LabelEntry = {
     id: string;
     label: string;