bareloop 0.5.0 → 0.6.0

package/types/plan.d.ts

@@ -1,19 +1,110 @@
+/**
+ * The MENU of legal `tree-changed` scopes — choose-don't-describe (design record
+ * §4, hamr's correction: *"did agent choose from a list or not?"*).
+ *
+ * F60 measured 13 of 18 validator reds as ONE class: the agent writes
+ * `scope: "src/*.js"`, the grammar accepts only a trailing `/**` or `/*`, and
+ * each red costs a redraft call. Teaching the rule in the prompt or widening the
+ * grammar both leave the agent authoring a free-text string and guessing its
+ * shape. Enumerating instead makes an illegal scope INEXPRESSIBLE.
+ *
+ * This is the only producer of scope menus, and it filters by the signed fence —
+ * so a menu entry that escapes containment cannot be constructed, rather than
+ * being caught by a downstream check. `globToPrefix` is untouched: this changes
+ * what the agent is OFFERED, never what the fence ENFORCES.
+ *
+ * @param {string[]} writeScope the signed fence entries (always offerable — they
+ *   cover directories a step has not created yet, which `snapshotScope` treats
+ *   as an empty snapshot)
+ * @param {string[]} [dirs] workdir-relative directories discovered under the
+ *   fence; each becomes `<dir>/**`
+ * @param {number} [cap] the menu bound; `Infinity` asks for the UNCAPPED set, so
+ *   a caller can report how many entries the cap dropped (no silent caps — a menu
+ *   that reads as complete when it is not is the blind-instrument class)
+ * @returns {string[]} the offerable scopes, deduped, shallowest-first, capped
+ */
+export function legalScopes(writeScope: string[], dirs?: string[], cap?: number): string[];
+/**
+ * F49 — a heuristic reject for the catastrophic-backtracking footgun: an
+ * unbounded quantifier applied to a group whose body itself repeats unboundedly
+ * (`(a+)+`, `(\d*)*`, `([a-z]+){1,}`) — including through a redundant wrapping
+ * group (`((a+))+`, `(?:(a+))*`), which is the SAME exponential class as `(a+)+`
+ * and is caught by propagating the inner repeat up through the wrapper. Such a
+ * pattern can hang `RegExp.test` for
+ * seconds on a short crafted body, and `evalExits` runs the agent-authored
+ * `artifact-written` pattern with NO timeout. This is self-DoS only — the agent
+ * authors both the pattern and (via the worker) the artifact, so a hang burns
+ * only its own run's wall-clock; there is NO arbiter compromise (it cannot
+ * escape the fence, forge a green, or leak a secret). So the reject targets the
+ * dominant exponential class and fails it as a mechanical gap at the validation
+ * gate, before any tokens burn. A full ReDoS analyzer needs a real regex engine
+ * (an external native dep we do not take for a LOW issue); exotic
+ * overlapping-alternation blowup is out of scope by decision.
+ *
+ * SCOPE IS ASYMMETRIC, both directions named on purpose:
+ *   - false NEGATIVE: overlapping-alternation blowup (`(a|ab)+`-class) is not
+ *     detected — out of scope (self-DoS only, no arbiter compromise).
+ *   - false POSITIVE: a group whose repetitions are disambiguated by a literal
+ *     anchor/delimiter (`(?:^- .+$\n?)+`, `(?:CHANGELOG:.+\n)+`) is FLAGGED even
+ *     though a real engine runs it linearly — the scan sees the nested-quantifier
+ *     SHAPE, not the disambiguation. Rejecting it is the FAIL-SAFE direction (it
+ *     never admits an unsafe pattern), and the cost is bounded: the plan drafter
+ *     gets a mechanical gap and rewrites (drop the outer `+`, or match once).
+ *     Detecting "safe because anchored" needs the same real engine we declined,
+ *     and guessing it wrong would ADMIT an exponential pattern — so the shape
+ *     reject stands, and the over-rejection is a named, accepted limitation.
+ *
+ * The input is guaranteed to compile as a RegExp (checked first by the caller),
+ * so this scan assumes valid, balanced JS regex syntax.
+ * @param {string} src a compiled regex source string
+ * @returns {boolean} true iff a nested unbounded quantifier is present
+ */
+export function hasNestedQuantifier(src: string): boolean;
+/**
+ * The close, as the ordered STAGE LIST the plan flow actually executes (PRD
+ * v1.28). A staged close is already that list; the legacy object form is the
+ * ONE-stage list it stands for, named `close`. Anything else — a gold, rubric or
+ * hitl close, which names no command to run — is null, and the runner escalates
+ * `close-unsupported` before any tokens.
+ *
+ * W4 — this is the ONE staging, and it exists because there used to be two. The
+ * runner synthesized the single stage and derived its check menu from THAT, while
+ * `planPrompt` and `validatePlan` called `checkMenu` on the RAW spec — where an
+ * object close is not an array, so the menu came back empty. The result was a
+ * runner announcing and preflighting a stage the drafter was never offered and the
+ * validator would have redded `check-unknown`. Same class as the two-transforms
+ * defects before it: the fix is one derivation every consumer calls, not three
+ * copies kept in step by comment.
+ *
+ * Lives here rather than beside `checkMenu` in job.js only because job.js owns the
+ * SIGNED vocabulary and this is the consumer-side reading of it; `plan.js` is the
+ * lowest module every check-menu consumer already imports (planrun imports plan,
+ * never the reverse), so it is the one place all three can share without a cycle.
+ * @param {any} close the spec's `close` field, any shape
+ * @returns {any[]|null} the stage list, or null when the close names no command
+ */
+export function stageClose(close: any): any[] | null;
 /** @typedef {{code: string, path: string, detail?: string, verb?: string}} Red */
 /**
  * Validate an agent-authored plan (`schema: "plan-v1"`) against the SIGNED
  * job spec. Never throws on JSON text or plain parsed data; every failure is
  * a named red. Returns the parsed plan on ok (single parse), null on any red.
  * @param {object|string} input parsed plan, or raw JSON text (parse failures are a red)
- * @param {{ job?: any, maxStepRounds?: number }} [opts] `job`: the
+ * @param {{ job?: any, maxStepRounds?: number, scopes?: string[], capRuns?: number }} [opts] `job`: the
  *   validateJob-GREEN four-field spec (the ceiling, the fence, and the checks
  *   menu all come from it — a missing or non-plan-shape job fails CLOSED);
  *   `maxStepRounds`: the shell's per-step rounds ceiling (interpret's
- *   tool-mode TURNS_PER_ATTEMPT) — a step may tighten it, never exceed it.
+ *   tool-mode TURNS_PER_ATTEMPT) — a step may tighten it, never exceed it;
+ *   `scopes`: the offered `tree-changed` menu from `legalScopes` (the SAME array
+ *   the drafting prompt enumerated). Omitted, it derives from the signed
+ *   writeScope — never a free-text fallback (F50).
  * @returns {{ ok: boolean, reds: Red[], plan: object|null }}
  */
-export function validatePlan(input: object | string, { job, maxStepRounds }?: {
+export function validatePlan(input: object | string, { job, maxStepRounds, scopes, capRuns }?: {
     job?: any;
     maxStepRounds?: number;
+    scopes?: string[];
+    capRuns?: number;
 }): {
     ok: boolean;
     reds: Red[];
@@ -29,13 +120,22 @@ export const MAX_EXITS_PER_STEP: 2;
 /** plan size bound — per-step rounds bound the spend, but an unbounded step
  * COUNT is still an unbounded claim on the wallet; same 8 as loop.maxIterations */
 export const MAX_PLAN_STEPS: 8;
-/** the write-class verbs (BA-13: `edit` is judged by the same fence as
- * `write`) — a step granting one is a WRITE step for the F17 pairing rule
- * and the v1.18 target requirement */
-export const WRITE_VERBS: readonly string[];
+export { WRITE_VERBS };
+/** scope-menu bound: the menu is a PROMPT ingredient on every draft and
+ * redraft, so an unbounded repo would price the drafting call by its directory
+ * count. Shallow entries survive the cap (see `legalScopes`) because they are
+ * the useful ones — a deep leaf is reachable via its parent. */
+export const MAX_SCOPE_MENU: 24;
+/** P (design record 2026-07-28): the signed per-step model-tier menu. Closed by
+ * construction — the agent picks a tier, never names an arbitrary model string
+ * (the tier→model mapping and any effort params are the RUNNER's, per provider).
+ * opus is deliberately absent: reserved for fresh builds hamr explicitly assigns,
+ * never plan-selectable. */
+export const STEP_MODELS: readonly string[];
 export type Red = {
     code: string;
     path: string;
     detail?: string;
     verb?: string;
 };
+import { WRITE_VERBS } from './job.js';

package/types/planrun.d.ts

@@ -1,5 +1,30 @@
 /**
- * Execute a validateJob-GREEN plan-shape job (goal/verdictType/close/checks[]).
+ * The plan-drafting prompt: a schema DESCRIPTION built from the live validator
+ * menus — never a copyable example (the drafter must author, not echo; the
+ * run.js draftPrompt precedent). Check NAMES only: a check's command is
+ * arbiter territory the planner never sees.
+ * @param {any} job @param {string} scoutBlob @param {any[]|null} reds
+ * @param {number} maxStepRounds @param {string|null} failure replan context
+ * @param {string[]|undefined} scopes the offered `tree-changed` menu (`legalScopes`).
+ *   Choose-don't-describe (§4): the agent picks a value, never authors a glob and
+ *   guesses its shape. Omitted, it derives from the signed fence — the SAME
+ *   fail-closed derivation `validatePlan` uses, so prompt and validator can never
+ *   disagree about what was offered.
+ * @param {{ balanceUsd?: number|null, remainingMs?: number|null, progress?: string }} [materials]
+ *   what the run has LEFT (T/A). Omitted → no materials block at all, which is the
+ *   pre-T behaviour and keeps every existing caller byte-identical.
+ * @param {number} [capRuns] the shell's attempt cap — the ceiling `attempts` may only
+ *   TIGHTEN. Interpolated the way every sibling bound is: `validatePlan` reds outside
+ *   `1..capRuns`, and a prompt that says only "integer" spends a round teaching it.
+ *   Defaults to validatePlan's own default so existing callers are unchanged.
+ */
+export function planPrompt(job: any, scoutBlob: string, reds: any[] | null, maxStepRounds: number, failure: string | null, scopes: string[] | undefined, materials?: {
+    balanceUsd?: number | null;
+    remainingMs?: number | null;
+    progress?: string;
+}, capRuns?: number): string;
+/**
+ * Execute a validateJob-GREEN plan-shape job (goal/verdictType/close).
  * Called by runJob after the approval gate, validation, and the smoke — this
  * function owns the plan flow only; the caller owns the job-end record and the
  * one ledger (every provider round is emitted here as `worker-round`, which
@@ -20,14 +45,33 @@
  * @param {() => number} opts.remainingUsd the one wallet: what is left of the signed budget right now
  * @param {() => boolean} [opts.isUnpriced] has any round come back with a null cost? (F6) — the
  *   plan flow bails IN-FLIGHT on the first unpriced round instead of burning the whole plan
+ * @param {(tier: string) => any} [opts.providerFor] P: per-step model-tier factory
+ *   (tier ∈ STEP_MODELS → a provider). A plan naming a tier with no factory supplied is an
+ *   interpreter-red STOP — never silently run the default tier as if the choice was honoured.
  * @param {number} [opts.capRuns] shell-owned per-step attempt cap
  * @param {number} [opts.closeTimeoutMs] close/check wall-clock cap (shell territory)
  * @param {number} [opts.maxStepRounds] the shell's per-step rounds ceiling (validatePlan's bound)
+ * @param {number} [opts.scoutRounds] the read-only survey's round bound (F59: the LAST round is
+ *   reserved — a scout that spends every round on tools gets one toolless round to write its
+ *   survey, because the bound halts it mid-tool-use and text is its only deliverable)
+ * @param {boolean} [opts.layerRoot=false] Layer R — the within-run ratchet (src/root.js),
+ *   scoped PER STEP's ralph loop (each micro-wheel is the Layer-1 atom). Shell-assembled from
+ *   the step's own books: per-attempt write-sets from the F32 workerWrites audit (teed for
+ *   same-path rewrites, which the cumulative audit alone cannot see) and the red-set from the
+ *   exit evaluator's own gap. Defaults OFF (decided 2026-07-21, F41): fixation is extinct on
+ *   every current job, so ON has never won its A/B; `true` is the ON/experimental arm, and the
+ *   first plan-flow job to emit `root-injected` runs the pre-registered ON-vs-OFF acceptance
+ *   read (the Layer R default-flip, LAYERS.md ⚠). Excluded on native (clipipe): the native
+ *   worker has no onToolResult seam, so the tee cannot settle and same-path rewrites are blind.
+ * @param {() => number} [opts.now] the wall clock's time source, injected. The real clock is the
+ *   default; a caller supplies this to drive time deterministically (the same seam `createClock`
+ *   already exposes — a run's terminal cannot otherwise be exercised without waiting out a cap
+ *   whose floor is one close timeout).
  * @returns {Promise<string>} 'green' | 'already-green' | 'escalated' | 'plan-red' |
  *   'check-red' | 'close-red' | 'close-unsupported' | 'pricing-red' | 'cap-halt' |
- *   'provider-red' | 'interpreter-red' | `step-red:<id>`
+ *   'wall-halt' | 'provider-red' | 'interpreter-red' | 'step-stalled' | `step-red:<id>`
  */
-export function runPlan(job: any, { workdir, provider, nativeProvider, emit, remainingUsd, isUnpriced, capRuns, closeTimeoutMs, maxStepRounds }: {
+export function runPlan(job: any, { workdir, provider, nativeProvider, providerFor, emit, remainingUsd, isUnpriced, capRuns, closeTimeoutMs, maxStepRounds, layerRoot, scoutRounds, now }: {
     workdir: string;
     provider: any;
     nativeProvider?: ((o: {
@@ -39,9 +83,13 @@ export function runPlan(job: any, { workdir, provider, nativeProvider, emit, rem
     emit: (type: string, data?: object) => object;
     remainingUsd: () => number;
     isUnpriced?: (() => boolean) | undefined;
+    providerFor?: ((tier: string) => any) | undefined;
     capRuns?: number | undefined;
     closeTimeoutMs?: number | undefined;
     maxStepRounds?: number | undefined;
+    scoutRounds?: number | undefined;
+    layerRoot?: boolean | undefined;
+    now?: (() => number) | undefined;
 }): Promise<string>;
 export type CategorizedError = Error & {
     category?: string;

package/types/ralph.d.ts

@@ -60,9 +60,9 @@
  *   (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',
+ * @returns {Promise<{verdict: 'satisfied'|'needs_revision'|'failed'|'timed-out'|'killed'|'crashed',
  *   gap?: string, exitCode?: number, signal?: string, detail?: string,
- *   judgedCount?: number|null, unaudited?: boolean}}
+ *   judgedCount?: number|null, unaudited?: boolean}>}
  */
 export function runClose(close: string[], redact?: (s: string) => string, { timeoutMs, cwd, expect, judged, gapKeep }?: {
     timeoutMs?: number;
@@ -73,7 +73,7 @@ export function runClose(close: string[], redact?: (s: string) => string, { time
         min: number;
     };
     gapKeep?: string;
-}): {
+}): Promise<{
     verdict: "satisfied" | "needs_revision" | "failed" | "timed-out" | "killed" | "crashed";
     gap?: string;
     exitCode?: number;
@@ -81,7 +81,36 @@ export function runClose(close: string[], redact?: (s: string) => string, { time
     detail?: string;
     judgedCount?: number | null;
     unaudited?: boolean;
-};
+}>;
+/**
+ * Run a STAGED close (PRD v1.28) — an ordered list of named command stages, run
+ * in order until one renders a verdict that is not `satisfied`. The return is
+ * runClose's own shape, so every consumer (the precheck, ralph's judge, the
+ * escalation's CLOSE_FAULTS routing) is unchanged: a staged close is still ONE
+ * verdict, not a scoreboard.
+ *
+ * Two additions, both mechanical information the worker can act on:
+ *  - `stage` names which stage rendered the verdict. The close's output must
+ *    never name the CULPRIT FILE (v1.12/F28 — the worker finds that itself), and
+ *    naming the wall it hit is the opposite of that: it is the mechanical genre
+ *    that converts (F38/F46), not the answer.
+ *  - `stages` is the ordered record of what actually ran. A stage after the
+ *    first red never runs, so a later green can never mask an earlier failure.
+ *
+ * The same function runs a DERIVED CHECK: a check is its stage's chain
+ * (`checkMenu` puts the prerequisites first), so there is one execution path for
+ * the close and for the rulers derived from it — never two, which is the F9
+ * two-transforms class applied to the arbiter.
+ *
+ * @param {any[]} stages the stage list (already validated by validateJob)
+ * @param {(s: string) => string} [redact] scrub, applied at capture on EVERY stage
+ * @param {{timeoutMs?: number, cwd?: string}} [opts]
+ * @returns {Promise<any>} runClose's verdict shape, plus `stage` and `stages`
+ */
+export function runStages(stages: any[], redact?: (s: string) => string, { timeoutMs, cwd }?: {
+    timeoutMs?: number;
+    cwd?: string;
+}): Promise<any>;
 /**
  * The loop: `while close-red and under-cap: run the middle`. Stops at first
  * green (within-run tuning past a visible close is the fit-to-pass surface,
@@ -151,6 +180,35 @@ export function ralph({ middle, close, judge, capRuns, emit, redact, closeTimeou
     gapKeep?: string | undefined;
     workerWrites?: (() => string[]) | undefined;
 }): Promise<"green" | "escalated">;
+/**
+ * What the close child must NOT be able to read (operator ruling, 2026-07-31:
+ * "strip it when unnecessary, minimize unneeded exposure").
+ *
+ * The close child executes WORKER-AUTHORED CODE. `pytest`, `npm test`, `tsc`
+ * run whatever the worker just wrote into the tree, in a child that — before
+ * this — inherited the whole operator environment, credentials included. None
+ * of git/npm/tsc/pytest/mypy needs an API key to judge a tree, so the exposure
+ * bought nothing and is removed. This is EXPOSURE REDUCTION, not a sandbox:
+ * see the threat-model note in the PRD (v1.41) and README for what remains.
+ *
+ * Two rules, deliberately kept BOTH ways round:
+ *  - `names` / `prefixes` — the knowns. A literal denylist is a chase (every
+ *    new provider mints a new variable), so it is not load-bearing on its own;
+ *    it exists for names the shape rule cannot see (`AWS_ACCESS_KEY_ID`).
+ *  - `shape` — the NAME-SHAPE rule, which is what bounds the chase: anything
+ *    whose name ends in the credential suffixes goes, whoever minted it and
+ *    whether or not anyone here has heard of it. Case-insensitive; no `g` flag,
+ *    so `.test` stays stateless and safe to reuse across every key.
+ *
+ * It is arbiter territory like the rest of this file: no drafted plan or config
+ * can express, widen, or opt out of it.
+ * @type {Readonly<{names: readonly string[], prefixes: readonly string[], shape: RegExp}>}
+ */
+export const CLOSE_ENV_DENY: Readonly<{
+    names: readonly string[];
+    prefixes: readonly string[];
+    shape: RegExp;
+}>;
 export const GAP_KEEP_TRIM_MARKER: "more elided by the";
 /**
  * The forbidden zone, named (PRD v1.11). Each row is an outcome in which the

package/types/root.d.ts

@@ -66,13 +66,21 @@ export function createRoot({ gapKeep, redact, writesInformative }?: {
      * Called at the START of attempt `iteration`, with the PREVIOUS attempt's
      * gap. Finalizes that attempt from the books, runs the detector, and
      * returns the injection for the attempt about to run — or null (inert).
-     * @param {{iteration: number, gap?: string, writes: string[]}} o
+     *
+     * `redStage`/`redKeep` are the STAGED-CLOSE seam (PRD v1.28): a close is an
+     * ordered list of named stages, the first red renders the verdict, so the
+     * pattern that designates failures belongs to whichever stage rendered it
+     * THIS attempt. Callers with a single red-set source (the per-step exit
+     * evaluator) pass neither and keep the constructor's run-wide pattern.
+     * @param {{iteration: number, gap?: string, writes: string[], redStage?: string, redKeep?: string}} o
      * @returns {null | {stage: 'summary'|'verbatim', note: string, event: object}}
      */
-    observe({ iteration, gap, writes }: {
+    observe({ iteration, gap, writes, redStage, redKeep }: {
         iteration: number;
         gap?: string;
         writes: string[];
+        redStage?: string;
+        redKeep?: string;
     }): null | {
         stage: "summary" | "verbatim";
         note: string;

package/types/run.d.ts

@@ -27,32 +27,31 @@
  * @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; the Loop path)
  * @param {(o: {policy: Function, onTurn?: Function, maxTurns: number, hasTools: boolean}) => any} [opts.nativeProvider]
  *   native clipipe provider factory (BA-16), required for a `clipipe-subscription` plan-shape job —
  *   threaded to runPlan, which builds one per worker (native tool mode when `hasTools`, else a
  *   metered claude-json text provider for the toolless drafter); ignored on every Loop-driven provider
  * @param {(type: string, data?: object) => object} opts.emit spine emitter
- * @param {number} [opts.capRuns] shell-owned per-step iteration cap
+ * @param {(tier: string) => any} [opts.providerFor] P: per-step model-tier provider factory (forwarded to the plan flow)
+ * @param {number} [opts.capRuns] shell-owned per-step attempt 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
  * @param {boolean} [opts.layerRoot=false] Layer R (within-run ratchet) — shell
- *        territory, threaded to every predicate step's interpreter. Defaults OFF
+ *        territory, threaded to the plan flow. Defaults OFF
  *        (decided 2026-07-21): fixation is extinct on every current job (F41), so
  *        ON has never won its own A/B — the acceptance read defers to Layer 2 (or
  *        a manufactured-fixation probe). `true` is the ON/experimental arm; the
  *        default is the OFF arm. (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>`
+ * @returns {Promise<string>} outcome: 'green' | 'already-green' | 'escalated' |
+ *   'unapproved-spec' | 'job-red' | 'smoke-red' | 'plan-red' | 'check-red' |
+ *   'close-red' | 'close-unsupported' | 'pricing-red' | 'provider-red' |
+ *   'interpreter-red' | 'cap-halt' | 'wall-halt' | 'step-stalled' | `step-red:<id>`
  */
-export function runJob(rawSpec: object | string, { approvals, workdir, target, provider, nativeProvider, emit, capRuns, shellCapUsd, closeTimeoutMs, execCmd, layerRoot }: {
+export function runJob(rawSpec: object | string, { approvals, workdir, provider, nativeProvider, providerFor, emit, capRuns, shellCapUsd, closeTimeoutMs, layerRoot }: {
     approvals: unknown;
     workdir: string;
-    target?: string | undefined;
     provider: any;
     nativeProvider?: ((o: {
         policy: Function;
@@ -61,10 +60,10 @@ export function runJob(rawSpec: object | string, { approvals, workdir, target, p
         hasTools: boolean;
     }) => any) | undefined;
     emit: (type: string, data?: object) => object;
+    providerFor?: ((tier: string) => any) | undefined;
     capRuns?: number | undefined;
     shellCapUsd?: number | undefined;
     closeTimeoutMs?: number | undefined;
-    execCmd?: ExecCmd | undefined;
     layerRoot?: boolean | undefined;
 }): Promise<string>;
 export type Red = {
@@ -72,10 +71,3 @@ export type Red = {
     path: string;
     detail?: string;
 };
-export type ExecCmd = (argv: string[], opts?: {
-    cwd?: string;
-}) => {
-    status: number | null;
-    stdout: string;
-    stderr: string;
-};

package/types/stall.d.ts

@@ -0,0 +1,80 @@
+/**
+ * @typedef {Object} StallWatch
+ * @property {<T>(call: (gen: number) => Promise<T>) => Promise<T>} watch run `call`,
+ *   reissuing it whenever it goes `stallMs` without a beat; rejects `StallError` past
+ *   `maxStalls`. Each issue is handed its GENERATION — the token every callback that
+ *   call installs must carry back, so a corpse's callbacks cannot touch the live call.
+ * @property {(gen: number) => void} beat a round completed on generation `gen` — reset
+ *   the window. From any other generation it is inert.
+ * @property {(gen: number) => boolean} isCurrent is `gen` still the call this watch is
+ *   waiting on? The caller reads it to withhold everything else a dead call would do.
+ * @property {() => number} stalls how many stalls this watch has absorbed
+ */
+/**
+ * Start a stall watchdog.
+ * @param {{ stallMs?: number, maxStalls?: number, onStall?: (n: number) => void,
+ *          expired?: () => boolean,
+ *          setTimer?: (fn: () => void, ms: number) => any,
+ *          clearTimer?: (id: any) => void }} [opts]
+ *   `onStall` is announced for EVERY stall including the last — a trim or a
+ *   recovery that happens silently is indistinguishable from one that never
+ *   happened (F28's rule, applied to time).
+ *   `expired` is the run's WALL, read at the one moment this module decides to
+ *   spend again (L4). Omitted, the watch behaves exactly as it did before the wall
+ *   existed — a caller with no clock reissues on the same rules.
+ * @returns {StallWatch}
+ */
+export function createStallWatch({ stallMs, maxStalls, onStall, expired, setTimer, clearTimer, }?: {
+    stallMs?: number;
+    maxStalls?: number;
+    onStall?: (n: number) => void;
+    expired?: () => boolean;
+    setTimer?: (fn: () => void, ms: number) => any;
+    clearTimer?: (id: any) => void;
+}): StallWatch;
+/** hamr's number: no completed round for five minutes is a stall. */
+export const STALL_MS: 300000;
+/** hamr's number: three stalls, then stop reissuing and replan. The count is
+ * CUMULATIVE over the watch's whole life and `watch()` never resets it — planrun
+ * builds one watch per WORKER, so the ceiling is spent across the STEP, not per
+ * call: two stalls on one call and one on the next give up just the same. That
+ * is deliberate (a step that keeps hanging is a step to replan, not a call to
+ * retry forever), and it is why nothing here says "on one call". */
+export const MAX_STALLS: 3;
+/**
+ * A stall gave up. Carries the category the step loop's replan trigger reads and
+ * the `lib` attribution stamped AT THE THROW SITE (never sniffed from prose).
+ */
+export class StallError extends Error {
+    /** @param {string} message @param {number} stalls */
+    constructor(message: string, stalls: number);
+    /** @type {string} */
+    category: string;
+    /** @type {string} */
+    lib: string;
+    /** @type {number} */
+    stalls: number;
+}
+export type StallWatch = {
+    /**
+     * run `call`,
+     * reissuing it whenever it goes `stallMs` without a beat; rejects `StallError` past
+     * `maxStalls`. Each issue is handed its GENERATION — the token every callback that
+     * call installs must carry back, so a corpse's callbacks cannot touch the live call.
+     */
+    watch: <T>(call: (gen: number) => Promise<T>) => Promise<T>;
+    /**
+     * a round completed on generation `gen` — reset
+     * the window. From any other generation it is inert.
+     */
+    beat: (gen: number) => void;
+    /**
+     * is `gen` still the call this watch is
+     * waiting on? The caller reads it to withhold everything else a dead call would do.
+     */
+    isCurrent: (gen: number) => boolean;
+    /**
+     * how many stalls this watch has absorbed
+     */
+    stalls: () => number;
+};