bareloop 0.2.0 → 0.3.0

package/types/index.d.ts

@@ -1,6 +1,8 @@
 export { makeSpine } from "./spine.js";
-export { ralph, runClose } from "./ralph.js";
-export { validateConfig, diffPaths, globToPrefix, LOOP_SHAPES, SLOTS, VERBS } from "./validate.js";
-export { validateJob, jobSpecHash, checkApproval, CLOSE_TYPES, CLASSES, CLASS_BY_CLOSE, GOLD_COMPARE, CADENCE_UNITS, PROVIDERS, CONDITION_KEYS } from "./job.js";
+export { runJob } from "./run.js";
+export { ralph, runClose, CLOSE_FAULTS } from "./ralph.js";
+export { validateConfig, diffPaths, globToPrefix, scanSecrets, LOOP_SHAPES, SLOTS, VERBS } from "./validate.js";
+export { validateJob, jobSpecHash, checkApproval, CLOSE_TYPES, CLASSES, CLASS_BY_CLOSE, GOLD_COMPARE, CADENCE_UNITS, PROVIDERS, CONDITION_KEYS, STEP_MODES, TOOL_MENU, LOCKED_TOOLS } from "./job.js";
 export { interpret, STALL_REDS } from "./interpret.js";
 export { extractRules, MAX_RULES, MAX_RULE_CHARS } from "./extract.js";
+export { classifyIncidents, foldLedger, ledgerDeltas, updateLedger, LEDGER_CLASSES } from "./ledger.js";

package/types/interpret.d.ts

@@ -4,13 +4,26 @@
  * @param {object|string} configRaw schema v1 config (object or raw JSON text)
  * @param {object} opts
  * @param {string} opts.task implement instruction shown to the worker
- * @param {string} opts.target absolute path the artifact is written to
+ * @param {string} [opts.target] absolute path the artifact is written to —
+ *        required in text mode; unused in tool mode (the worker writes through
+ *        the gated tools, wherever the fence allows)
  * @param {string[]} opts.close argv whose exit code is truth (shell-owned)
+ * @param {number} [opts.closeExpect] the exit code the SIGNED spec calls success
+ * @param {{pattern: string, min: number}} [opts.closeJudged] the signed spec's
+ *   judgment-rendered signal — proof the close actually judged something before
+ *   its exit code is believed in EITHER direction (PRD v1.11; the drafted config
+ *   cannot express it, and must not: it is the arbiter's own honesty check)
+ * @param {string} [opts.closeGapKeep] the signed spec's kept-failures pattern (F28):
+ *   close-output lines matching it survive the gap bound, so a large suite's
+ *   `not ok` names reach the worker instead of being elided into "N fail" — also
+ *   arbiter territory, inexpressible in the drafted config
  * @param {string} opts.workdir run directory (litectx root, gate audit, scope base)
  * @param {number} opts.capRuns shell iteration budget; the config may tighten via loop.maxIterations, never exceed
  * @param {(type: string, data?: object) => object} opts.emit spine emitter
  * @param {object} opts.provider a bareagent provider — SHELL-owned binding (adaptlearn F8: an unsealed binding is a gate bypass)
- * @param {number} [opts.shellCapUsd=2] the shell's USD cap; config budgetUsd is clamped by validation
+ * @param {number} [opts.shellCapUsd=2] the shell's USD cap; a config budgetUsd above it REDS at validation (bounds — no silent clamping)
+ * @param {number} [opts.closeTimeoutMs] close wall-clock cap, threaded to the shell
+ *        (shell/operator territory — the workflow config cannot express it)
  * @param {string[]} [opts.jobWriteScope] the job spec's outer write fence (operator law,
  *        job-v1) — enforced HERE, the one choke point where a config becomes a Gate:
  *        every workflow scope must fit inside it (scope-escape config-red otherwise),
@@ -22,17 +35,33 @@
  *        (arbiter-touch / cap-touch revision-reds otherwise; the run continues on the old
  *        config). Revisor spend rides the run's own gate handlers — same budget axis as
  *        the worker.
+ * @param {string} [opts.closeState] the close's CURRENT output on the tree as it stands
+ *        (the shell's pre-token close check, F13) — shown to the first attempt only, and
+ *        never framed as an attempt: the worker cannot run the close itself (`run` is a
+ *        locked verb), so without this it is asked to fix a failure it cannot see
+ * @param {'text'|'tools'} [opts.mode] middle mode (2b): 'text' (default) writes the ONE
+ *        target from the response artifact; 'tools' gives the worker Gate-governed file
+ *        tools — SPEC-side territory (the step declares it; the config cannot express it)
+ * @param {string[]} [opts.tools] the spec's tool grant (subset of read|grep|write,
+ *        job-v1 validated); defaults to the full menu in tool mode
  * @returns {Promise<'green'|'escalated'|'config-red'>}
  */
-export function interpret(configRaw: object | string, { task, target, close, workdir, capRuns, emit, provider, shellCapUsd, jobWriteScope, revisor }: {
+export function interpret(configRaw: object | string, { task, target, close, workdir, capRuns, emit, provider, shellCapUsd, jobWriteScope, revisor, closeTimeoutMs, mode, tools, closeState, closeExpect, closeJudged, closeGapKeep }: {
     task: string;
-    target: string;
+    target?: string | undefined;
     close: string[];
+    closeExpect?: number | undefined;
+    closeJudged?: {
+        pattern: string;
+        min: number;
+    } | undefined;
+    closeGapKeep?: string | undefined;
     workdir: string;
     capRuns: number;
     emit: (type: string, data?: object) => object;
     provider: object;
     shellCapUsd?: number | undefined;
+    closeTimeoutMs?: number | undefined;
     jobWriteScope?: string[] | undefined;
     revisor?: ((o: {
         config: object;
@@ -44,14 +73,18 @@ export function interpret(configRaw: object | string, { task, target, close, wor
         parseError?: string | null;
         costUsd?: number;
     }>) | undefined;
+    closeState?: string | undefined;
+    mode?: "text" | "tools" | undefined;
+    tools?: string[] | undefined;
 }): Promise<"green" | "escalated" | "config-red">;
-/** @typedef {Error & {category?: string}} CategorizedError the failure map's carrier: ralph relays by `category` */
+/** @typedef {Error & {category?: string, lib?: string}} CategorizedError the failure map's carrier: ralph relays by `category`, and by `lib` when the thrower knows which library owns the failure (the ledger prefers it over prose) */
 export const STALL_REDS: 2;
 /**
- * the failure map's carrier: ralph relays by `category`
+ * the failure map's carrier: ralph relays by `category`, and by `lib` when the thrower knows which library owns the failure (the ledger prefers it over prose)
  */
 export type CategorizedError = Error & {
     category?: string;
+    lib?: string;
 };
 /**
  * litectx recall hit — body present only with `{body: true}`

package/types/job.d.ts

@@ -1,4 +1,4 @@
-/** @typedef {{code: string, path: string, detail?: string}} Red */
+/** @typedef {{code: string, path: string, detail?: string, verb?: string}} Red — `verb` rides request-reds as structured data (the ledger keys on it, never on prose) */
 /**
  * Validate an operator-owned job spec (`schema: "job-v1"`). Never throws on
  * JSON text or plain parsed data — the ingest contract; a live object with a
@@ -44,14 +44,45 @@ export const CLASS_BY_CLOSE: Readonly<{
     hitl: readonly string[];
 }>;
 export const GOLD_COMPARE: readonly string[];
+/** step middle modes (2b): text = single-target artifact; tools = Gate-governed file tools */
+export const STEP_MODES: readonly string[];
+/** the tool grant menu (2b interview #1): read/grep/write, plus the two litectx
+ * RETRIEVAL verbs (F19) — `run` stays locked-but-listed; a spec requesting it
+ * reds, and that red IS the request-red evidence admission waits on (curation
+ * doctrine, PRD F2).
+ *
+ * `recall`/`get` are READ-ONLY BY CONSTRUCTION, not by promise: `recall` returns
+ * pointers (path/symbol/line-range, no bodies) and `get` trades ONE pointer for
+ * ONE chunk — it refuses any range that is not a chunk boundary, so it cannot be
+ * widened into a whole-file read, and it is content-hash gated (a drifted file
+ * throws rather than serving a stale body). Admitting them does NOT weaken the
+ * `run` lock: the worker still cannot execute anything, so it still cannot run
+ * its own close (the arbiter). F19: `shell_read` starts at byte ZERO and cannot
+ * seek, so a pointer was INERT — the worker paged 1.37 MB of source through
+ * context to reach 8 lines. The ranged read is the pager.
+ *
+ * `edit` (BA-13, bare-agent 0.29.0) is the anchored exact-once replace — a
+ * WRITE-class verb judged by the SAME writeScope fence as `write` (bareguard
+ * action type 'edit'). Admitted because whole-file rewrite is measurably
+ * unreliable at size (F31: 4 of 5 big-file whole-writes broke the tree) and
+ * taxes output tokens ∝ file size. It admits no execution either. */
+export const TOOL_MENU: readonly string[];
+/** locked-but-listed tools: real capabilities deliberately outside the grant
+ * menu. Requesting one is a DISTINCT `request-red` (module 4) — the ledger
+ * counts admission demand, and a generic invalid-value would bury it as a typo. */
+export const LOCKED_TOOLS: readonly string[];
 export const CADENCE_UNITS: readonly string[];
 export const PROVIDERS: readonly string[];
 /** V3 environment label: declared keys only — every field is a lineage-key
  * candidate at N3. `provider` is part of the key by definition (top-level,
  * not duplicated here). */
 export const CONDITION_KEYS: readonly string[];
+/**
+ * — `verb` rides request-reds as structured data (the ledger keys on it, never on prose)
+ */
 export type Red = {
     code: string;
     path: string;
     detail?: string;
+    verb?: string;
 };

package/types/ledger.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Classify one spine's events into incident occurrences (the design table in
+ * bareloop vocabulary). Deliberate exclusions — bare cap-halt (a budget story),
+ * close-verdict reds and artifact-red (worker stories, the §5b line), gate-red
+ * (governance working as intended), pr-red (operator environment, not a suite
+ * lib), smoke-red escalations (already counted via primitive-smoke), hitl-close
+ * and close-unsupported (by design) — classify to nothing.
+ * @param {any[]} events one spine's parsed events, in seq order
+ * @param {{spine?: string}} [opts] spine id stamped into samples
+ * @returns {Occurrence[]}
+ */
+export function classifyIncidents(events: any[], { spine }?: {
+    spine?: string;
+}): Occurrence[];
+/**
+ * Fold ledger rows to current state — latest cumulative count per key, latest
+ * human-appended status riding on top (default 'open'). A status row for a key
+ * with no incident row still folds (occurrences 0): a human note must never
+ * silently vanish.
+ * @param {any[]} rows parsed ledger rows, in seq order
+ * @returns {Record<string, FoldEntry>}
+ */
+export function foldLedger(rows: any[]): Record<string, FoldEntry>;
+/**
+ * Compute the append-only delta rows: group occurrences by key; a row is due
+ * only when the key is new or its corpus total grew past the folded count.
+ * detail is first-seen (the fold's wins); samples are the corpus's first few.
+ * @param {Record<string, FoldEntry>} fold current ledger state
+ * @param {Occurrence[]} occurrences the FULL corpus's occurrences
+ * @returns {object[]} lib-incident rows, unstamped (no seq/ts)
+ */
+export function ledgerDeltas(fold: Record<string, FoldEntry>, occurrences: Occurrence[]): object[];
+/**
+ * The collector: read the ledger, classify the FULL spine corpus, append the
+ * deltas (spine conventions: type first, ts stamped last, seq continuing
+ * monotonically across appends). Idempotent over the same corpus; the CLI
+ * wrapping this lands at N5, the panel reads the same file at N6.
+ * @param {{ledgerFile: string, spineFiles: string[]}} o spineFiles: the corpus
+ *   (pass ALL of it each time — counts are totals, not increments)
+ * @returns {{appended: object[], fold: Record<string, FoldEntry>}}
+ */
+export function updateLedger({ ledgerFile, spineFiles }: {
+    ledgerFile: string;
+    spineFiles: string[];
+}): {
+    appended: object[];
+    fold: Record<string, FoldEntry>;
+};
+/** severity order, worst-first (the fold's display order; frequency ranks within) */
+export const LEDGER_CLASSES: readonly string[];
+export type Sample = {
+    spine: string;
+    seq: number;
+};
+export type Occurrence = {
+    key: string;
+    class: string;
+    lib: string;
+    verb: string;
+    sig: string;
+    detail: string;
+    sample: Sample;
+};
+export type FoldEntry = {
+    key: string;
+    lib: string;
+    verb: string;
+    class: string;
+    sig: string;
+    detail: string;
+    occurrences: number;
+    samples: Sample[];
+    suggestedAsk: string;
+    status: string;
+    ref?: string;
+};

package/types/ralph.d.ts

@@ -1,6 +1,34 @@
 /**
  * Run a close command; its exit code is the verdict (hard green, PRD §4).
- * 0 → satisfied; nonzero → needs_revision (gap fed back); spawn error → failed (terminal).
+ * `expect` → satisfied; any other exit → needs_revision (gap fed back).
+ *
+ * THE FORBIDDEN ZONE (PRD v1.11, F17; adaptlearn F25/V10). The two clean bands
+ * are green (exit == expect, judgment rendered) and red (exit != expect,
+ * judgment rendered). Every other outcome rendered NO JUDGMENT and is therefore
+ * NOT A VERDICT — it gets its own name and escalates; coercing one into a
+ * verdict IS the instrument fault (law #8 generalized):
+ *   - `failed`    — the close cannot RUN (spawn error).             → broken-close
+ *   - `timed-out` — it ran and never finished judging.              → close-timeout
+ *   - `killed`    — it died by signal (status null, no spawn error). → close-killed
+ *   - `crashed`   — it ran, exited, and judged nothing.             → close-crashed
+ * `timed-out` is split OUT of `failed` deliberately: "raise the timeout" and
+ * "fix the argv" are different human decisions, so pooling them erases the
+ * decision information the escalation exists to carry.
+ *
+ * `judged` is the judgment-rendered signal, and it is the hard one. Exit code
+ * ALONE cannot separate a crash-at-load from an honest red — they are
+ * byte-identical at this seam, and against `node --test` so are the test counts
+ * (node synthesizes ONE failing test for the file that crashed, so a crash
+ * reports `tests 1 / fail 1`, exactly like a one-assertion failure). So the
+ * signal cannot be "zero judged"; it must be a FLOOR against a declared
+ * baseline: litectx runs ~390 tests, and a run claiming it judged 1 did not
+ * judge. `judged.pattern` extracts one integer from the close's own (redacted)
+ * output; below `judged.min` the close crashed, WHATEVER its exit code says —
+ * and that check runs on the GREEN side too: a close that exits 0 having judged
+ * nothing is a confident fake green, the only real failure there is (law #8).
+ * `judged` is OPTIONAL — a linter or a hitl close may have no count to give —
+ * and its absence stamps `unaudited: true` so the blind spot is NAMED on the
+ * record rather than passed off as a trustworthy exit code.
  *
  * `redact` scrubs the close's own output at the SOURCE — before the gap becomes
  * a spine event or a worker prompt — so a secret a checked command echoes
@@ -10,24 +38,49 @@
  * primitive (bareguard's, wired by the interpreter), never an emergent
  * component — so V4 holds. The shell's canonical emission IS the redacted text;
  * a benign gap is returned byte-identical (default: identity).
+ * `cwd` is where the close RUNS, and it is load-bearing (F8): a close is a
+ * command in a repository — `npm test`, `make check` — and every one of them is
+ * cwd-relative. Run it anywhere but the workdir and the arbiter judges the wrong
+ * tree: exit-code-is-truth silently becomes exit-code-of-some-other-repo-is-truth.
+ * The default (the runner's own cwd) exists only for callers with an absolute
+ * close; the runner and the interpreter always pass the workdir.
+ *
+ * `gapKeep` (F28) is a regex SOURCE whose matching lines are PRESERVED through
+ * the gap bound in addition to the head/tail sample: a large TAP suite prints
+ * its `not ok` lines in the middle of the stream, exactly where `boundGap`
+ * elides — so the failing-test NAMES (the causal input the worker navigates on)
+ * were deleted in transit and the worker was told "5 fail" and never WHICH. It
+ * is arbiter territory like the rest here: the drafted config cannot express it.
+ *
  * @param {string[]} close argv, e.g. ['node', '--test', 'close/']
  * @param {(s: string) => string} [redact] source scrubber; identity by default
+ * @param {{ timeoutMs?: number, cwd?: string, expect?: number, judged?: {pattern: string, min: number}, gapKeep?: string }} [opts]
+ *   close wall-clock cap (operator-set via the runner, never the config's — the
+ *   agent must not author its arbiter's clock), the directory the close runs in
+ *   (the workdir — the tree it is judging), the exit code the SIGNED spec calls
+ *   success, the judgment-rendered signal, and the kept-failures pattern. All
+ *   five are arbiter territory: the drafted workflow config cannot express any.
+ * @returns {{verdict: 'satisfied'|'needs_revision'|'failed'|'timed-out'|'killed'|'crashed',
+ *   gap?: string, exitCode?: number, signal?: string, detail?: string,
+ *   judgedCount?: number|null, unaudited?: boolean}}
  */
-export function runClose(close: string[], redact?: (s: string) => string): {
-    verdict: string;
-    detail: string;
-    gap?: undefined;
-    exitCode?: undefined;
-} | {
-    verdict: string;
-    detail?: undefined;
-    gap?: undefined;
-    exitCode?: undefined;
-} | {
-    verdict: string;
-    gap: string;
-    exitCode: number | null;
-    detail?: undefined;
+export function runClose(close: string[], redact?: (s: string) => string, { timeoutMs, cwd, expect, judged, gapKeep }?: {
+    timeoutMs?: number;
+    cwd?: string;
+    expect?: number;
+    judged?: {
+        pattern: string;
+        min: number;
+    };
+    gapKeep?: string;
+}): {
+    verdict: "satisfied" | "needs_revision" | "failed" | "timed-out" | "killed" | "crashed";
+    gap?: string;
+    exitCode?: number;
+    signal?: string;
+    detail?: string;
+    judgedCount?: number | null;
+    unaudited?: boolean;
 };
 /**
  * The loop: `while close-red and under-cap: run the middle`. Stops at first
@@ -50,12 +103,52 @@ export function runClose(close: string[], redact?: (s: string) => string): {
  * @param {(type: string, data?: object) => object} opts.emit a spine emitter
  * @param {(s: string) => string} [opts.redact] source scrubber for close output
  *   (secrets never enter the spine); injected so the shell stays stdlib-only
+ * @param {number} [opts.closeTimeoutMs] close wall-clock cap (shell/operator
+ *   territory — the workflow config cannot express it)
+ * @param {string} [opts.cwd] the directory every close runs in — the tree it is
+ *   judging (F8: a cwd-relative close run elsewhere judges the wrong repository)
+ * @param {number} [opts.expect] the exit code the SIGNED spec calls success
+ * @param {{pattern: string, min: number}} [opts.judged] the judgment-rendered signal
+ * @param {string} [opts.gapKeep] kept-failures pattern (F28): matching close-output
+ *   lines survive the gap bound so a large suite's `not ok` names reach the worker
+ * @param {() => string[]} [opts.workerWrites] the crash-attribution instrument (F32):
+ *   answers "which files has the WORKER written so far this run?" — the runner wires
+ *   it to the gate audit's allow-decision writes. Injected like `redact` so the shell
+ *   stays stdlib-only and dumb; consulted ONLY at a crashed verdict. With no seam, or
+ *   with zero writes, a crash stays what it always was: an instrument stop.
  * @returns {Promise<'green'|'escalated'>}
  */
-export function ralph({ middle, close, capRuns, emit, redact }: {
+export function ralph({ middle, close, capRuns, emit, redact, closeTimeoutMs, cwd, expect, judged, gapKeep, workerWrites }: {
     middle: (iteration: number, gap?: string) => void | Promise<void>;
     close: string[];
     capRuns: number;
     emit: (type: string, data?: object) => object;
     redact?: ((s: string) => string) | undefined;
+    closeTimeoutMs?: number | undefined;
+    cwd?: string | undefined;
+    expect?: number | undefined;
+    judged?: {
+        pattern: string;
+        min: number;
+    } | undefined;
+    gapKeep?: string | undefined;
+    workerWrites?: (() => string[]) | undefined;
 }): Promise<"green" | "escalated">;
+/**
+ * The forbidden zone, named (PRD v1.11). Each row is an outcome in which the
+ * close rendered NO JUDGMENT — so it is not a verdict, it never feeds a gap
+ * back, and it is never retried. They are kept SEPARATE on purpose: pooling
+ * them would erase the decision information the escalation exists to carry —
+ * "raise the timeout", "fix the argv", and "re-run, it was OOM-killed" are
+ * three different human answers.
+ * Exported because the RUNNER's close-first precheck runs the same arbiter
+ * before any tokens: two maps would be two instruments, and two instruments
+ * disagreeing about the same outcome is the fault this whole addendum exists
+ * to close.
+ * @type {Record<string, {category: string, decision: string, options: string[]}>}
+ */
+export const CLOSE_FAULTS: Record<string, {
+    category: string;
+    decision: string;
+    options: string[];
+}>;

package/types/run.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Run an approved job end to end: approval gate → primitive smoke → sequential
+ * per-step interpret loops under the one ledger → the hitl step opens the draft
+ * PR (deterministic git, never model tools) and becomes the decision-ready
+ * escalation. Every predicate step runs its close FIRST (close-first skip,
+ * resume model): already-green skips the step for zero tokens as a distinct
+ * spine record, so a stopped run reruns from where it died — the workdir plus
+ * the closes are the checkpoint. The sealed config draft (one shot + one
+ * redraft) is deferred to the first step that actually needs a worker; a clean
+ * rerun pays zero provider calls.
+ *
+ * N2 bounds (honest, documented): text-mode steps write a single `target`
+ * artifact; tool-mode steps (2b) work multi-file through the gated shell tools,
+ * granted per step by the SPEC (mode/tools — the drafted config cannot express
+ * either); `gold`/`rubric` closes refuse `close-unsupported` (execution lands
+ * with the verdict classes, N4); the pricing-red halt lands at the step
+ * boundary — the Gate still caps within a step, but an unpriced result cannot
+ * be summed, so the run stops rather than counting it $0 (F6).
+ *
+ * @param {object|string} rawSpec the job spec (job-v1), text or parsed
+ * @param {object} opts
+ * @param {unknown} opts.approvals `{ specHash, signer, ts }` records (from OUTSIDE the spec)
+ * @param {string} opts.workdir the run directory (the fence's root)
+ * @param {string} [opts.target] the step artifact path (text-mode steps; unused by tool-mode steps)
+ * @param {any} opts.provider shell-owned LLM binding (never the config's)
+ * @param {(type: string, data?: object) => object} opts.emit spine emitter
+ * @param {number} [opts.capRuns] shell-owned per-step iteration cap
+ * @param {number} [opts.shellCapUsd] the shell's hard USD ceiling
+ * @param {number} [opts.closeTimeoutMs] close wall-clock cap (shell territory)
+ * @param {ExecCmd} [opts.execCmd] process runner for the hitl PR mechanics
+ *        (shell-owned seam, same doctrine as the provider binding)
+ * @returns {Promise<string>} outcome: 'green' | 'escalated' | 'unapproved-spec' |
+ *   'job-red' | 'smoke-red' | 'config-red' | 'pricing-red' | 'provider-red' |
+ *   'cap-halt' | 'close-unsupported' | `step-red:<id>`
+ */
+export function runJob(rawSpec: object | string, { approvals, workdir, target, provider, emit, capRuns, shellCapUsd, closeTimeoutMs, execCmd }: {
+    approvals: unknown;
+    workdir: string;
+    target?: string | undefined;
+    provider: any;
+    emit: (type: string, data?: object) => object;
+    capRuns?: number | undefined;
+    shellCapUsd?: number | undefined;
+    closeTimeoutMs?: number | undefined;
+    execCmd?: ExecCmd | undefined;
+}): Promise<string>;
+export type Red = {
+    code: string;
+    path: string;
+    detail?: string;
+};
+export type ExecCmd = (argv: string[], opts?: {
+    cwd?: string;
+}) => {
+    status: number | null;
+    stdout: string;
+    stderr: string;
+};

package/types/text.d.ts

@@ -1 +1,35 @@
-export function stripFences(t: string): string;
+/**
+ * Fence-robust artifact extraction (F2 port requirements #1/#2):
+ * - a fenced block opening within the first {@link FENCE_PREAMBLE_LINES} lines
+ *   is the artifact — prose-wrapped and preamble fences extract clean (the F21
+ *   instrument caveat: prose written to the target corrupted the close signal);
+ * - a fence opening deeper is the artifact's own content — the trimmed whole
+ *   text is the artifact (fence-heavy artifacts belong in tool mode, where the
+ *   worker writes files directly and nothing is parsed);
+ * - no fence → the trimmed whole text, with N0's unclosed-leading-fence strip
+ *   as the fallback (reference parity);
+ * - nothing extractable → `code: null` plus a named reason: artifact-red
+ *   material for the caller's OWN axis, never a silent empty write.
+ * Never throws.
+ * @param {string|null|undefined} t
+ * @returns {{ code: string|null, red: string|null }}
+ */
+export function extractArtifact(t: string | null | undefined): {
+    code: string | null;
+    red: string | null;
+};
+/**
+ * The ONE spelling of the F6 honest-null cost read on a bare-agent result.
+ * `metrics.costUsd` is the honest null when NOTHING priced — never fall
+ * through to `cost` when metrics exist: `cost` sums priced rounds only, so an
+ * all-unpriced run reports cost 0 and `?? cost` would launder the explicit
+ * unknown into a silent $0 (the F6 class — four shipped launderings were this
+ * exact fallback chain hand-spelled). `unpricedRounds` makes a PARTIALLY
+ * unpriced run visible (costUsd finite but an under-count).
+ * @param {any} r a Loop.run() result (or null)
+ * @returns {{ costUsd: number|null, unpricedRounds: number }}
+ */
+export function priceOf(r: any): {
+    costUsd: number | null;
+    unpricedRounds: number;
+};

package/types/validate.d.ts

@@ -25,6 +25,18 @@ export function scopeContained(s: string): boolean;
 export function isObj(v: unknown): boolean;
 /** @param {unknown} v @returns {v is string} */
 export function isNonEmptyString(v: unknown): v is string;
+/**
+ * Scan a RAW text stream (a spine file, a close's output, a transcript) for
+ * known secret shapes and return the literal matches. The ONE spelling of the
+ * text-side scan, for the same reason SECRET_PATTERNS is the ONE inventory: a
+ * hand-rolled copy that misses a shape is a leak on the very output it guards
+ * (seven copies of this expression lived in scripts/ before it landed here).
+ * `sweepSecretLiterals` is the config-tree twin — same shapes, tree walk.
+ * Never throws; returns [] for a missing stream.
+ * @param {unknown} raw
+ * @returns {string[]} every match, in stream order per pattern
+ */
+export function scanSecrets(raw: unknown): string[];
 /**
  * Red every string in a config tree that carries a known secret-token shape.
  * @param {any} root
@@ -66,4 +78,5 @@ export function diffPaths(a: object, b: object): string[];
 export const LOOP_SHAPES: readonly string[];
 export const SLOTS: readonly string[];
 export const VERBS: readonly string[];
+export const REMEMBER_KINDS: string[];
 export const SECRET_PATTERNS: RegExp[];