tumwater 0.2.0 → 0.3.0

package/dist/src/{loop/loop-state.js → runner/runner-state-load.js}

@@ -1,50 +1,20 @@
-import { readJsonFile, writeJsonAtomic } from "../files/json-files.js";
-import { isJsonObject, nonNegativeNumber } from "../files/json-object.js";
+import { APPROVED_PATCH_IDS_MAX, freshRunnerState, SKIP_REASONS } from "./runner-state.js";
 import path from "node:path";
-import { readdirSync } from "node:fs";
+import { dirEntryNames } from "../files/files.js";
+import { readJsonFile } from "../files/json-files.js";
+import { isJsonObject, nonNegativeNumber, validEntries } from "../files/json-object.js";
 import { cachedByStat } from "../files/stat-cache.js";
 import { statePath, STATE_DIR } from "../paths.js";
-import { baseRoleOf } from "../roles/loop-ids.js";
+import { baseRoleOf } from "../roles/runner-ids.js";
 import { allRoleIds } from "../roles/roles.js";
-/** The loop's persisted state file — one JSON object per role under .tumwater/ — and the
- * observation-window counter reset: fresh-state defaults, the tolerant load, the atomic
- * save, and zeroCounters. The scheduling POLICY that mutates this state from tick outcomes
- * and operator wakes — the outcome application and resume limits in tick-apply.ts, the
- * clock arithmetic (backoff ladders, wakes, yield ring) in backoff.ts; the generic file
- * helpers are src/files/files.ts and the JSON convention
- * itself is src/files/json-files.ts. */
-/** How many times a progressing-timeout review may be resumed before the next attempt
- * reviews the change from scratch (LoopState.reviewResume). The budget bounds a reviewer that
- * keeps timing out mid-progress, so a wedged review converges to a fresh run instead of
- * resuming the same session forever. */
-export const REVIEW_RESUME_LIMIT = 2;
-const SKIP_REASONS = [
-    "no-free-entry",
-    "claim-hold",
-    "deferred-backlog",
-    "deferred-no-work",
-    "deferred-plans-full",
-];
-/** A new LoopState for one role, before its first tick. */
-export function freshLoopState(role) {
-    return {
-        role,
-        runs: 0,
-        commits: 0,
-        nextRunAt: 0,
-        backoffSeconds: 0,
-        lastMainHead: "",
-        generatedTokens: 0,
-        peakContextTokens: 0,
-        totalCostUsd: 0,
-        dayStamp: "",
-        dayCostUsd: 0,
-    };
-}
+/** The read side of the runner's persisted state: the tolerant load of one role's file (heals
+ * every field a hand edit or an older build could leave unusable, and renames the keys an older
+ * build wrote) and the live-claim scan over every role's file. The type, the fresh-state
+ * defaults, the atomic save and zeroCounters stay in runner-state.ts. */
 /** A persisted numeric field, healed to a finite non-negative number (the fallback when it is
- * absent, foreign, NaN/±Infinity, or negative). Every numeric field on LoopState — top-level or
+ * absent, foreign, NaN/±Infinity, or negative). Every numeric field on RunnerState — top-level or
  * inside one of the nested records below — is a count, a duration, an epoch-ms stamp, or an
- * amount, so zero is the only sensible repair; the `tick-usage.ts` and `budget.ts` writers floor
+ * amount, so zero is the only sensible repair; the `run-usage.ts` and `budget.ts` writers floor
  * the same three quantities they own. A guard count (mergeConflicts, mergeCheckFailures,
  * unreviewFailures) heals to 0 like the rest: a corrupt strike tally re-accumulates from the
  * next attempt, the same "the field is unusable, start the count over" repair the top-level heal
@@ -55,19 +25,12 @@ function healNumber(value, fallback) {
 /** Heal the per-pair daily spend map: a non-object reads as `{}`, entries that are not
  * non-negative finite numbers drop, and a `__proto__` key stays an own property. */
 function healPairCosts(value) {
-    const out = {};
-    if (typeof value !== "object" || value === null || Array.isArray(value))
-        return out;
-    for (const [k, v] of Object.entries(value)) {
-        if (typeof v === "number" && Number.isFinite(v) && v >= 0)
-            Object.defineProperty(out, k, { value: v, enumerable: true, writable: true, configurable: true });
-    }
-    return out;
+    return validEntries(value, (v) => nonNegativeNumber(v, -1) >= 0);
 }
 /** Heal one OPTIONAL numeric field of a persisted record in place, preserving the field's
  * absent shape: an absent field stays absent (an older state file with no such field reads
  * unchanged), while a present field heals by healNumber's rule. Every optional numeric field
- * loadLoopState repairs — the eight top-level stamps/streaks and conflictHandback.round —
+ * loadRunnerState repairs — the eight top-level stamps/streaks and conflictHandback.round —
  * goes through this one guard, so the "absent stays absent" repair cannot be dropped from
  * one field while another keeps it. */
 function healOptionalNumber(rec, key) {
@@ -77,7 +40,7 @@ function healOptionalNumber(rec, key) {
 }
 /** Heal one persisted nested record: absent stays absent; a present non-object (a string,
  * number, NaN, null, or array) is dropped to undefined — every consumer of these records reads
- * them with property access or mutation (merge-core sets `lastReview.exhausted`, tick-apply
+ * them with property access or mutation (merge-core sets `lastReview.exhausted`, run-apply
  * adds to `mergeConflicts.count`), and property access on a torn scalar reads undefined where
  * the mutation throws "Cannot create property … on string" in a strict ES module; a present
  * object keeps its shape with each numeric field repaired by `heal`. */
@@ -87,13 +50,13 @@ function healRecord(value, heal) {
     heal(value);
     return value;
 }
-/** Keys an older build wrote, mapped to their current names. loadLoopState copies the old key's
+/** Keys an older build wrote, mapped to their current names. loadRunnerState copies the old key's
  * value to the new key when the new key is absent and always drops the old key, so a file holding
  * both keeps the new value and the next save writes only current keys. */
 const LEGACY_STATE_KEYS = {
-    ticks: "runs", // vocabulary-ok: legacy state key read from old files
-    lastTickStartedAt: "lastRunStartedAt", // vocabulary-ok: legacy state key read from old files
-    lastTickEndedAt: "lastRunEndedAt", // vocabulary-ok: legacy state key read from old files
+    ticks: "runs", // retired-name-ok: legacy name
+    lastTickStartedAt: "lastRunStartedAt", // retired-name-ok: legacy name
+    lastTickEndedAt: "lastRunEndedAt", // retired-name-ok: legacy name
     // retired-name-ok:start old state keys
     landingReviewError: "mergeReviewError", // vocabulary-ok: legacy state key read from old files
     landingCheckFailures: "mergeCheckFailures", // vocabulary-ok: legacy state key read from old files
@@ -110,7 +73,7 @@ function migrateLegacyStateKeys(saved) {
         delete saved[oldKey];
     }
 }
-/** Load the loop's persisted state; never throws — a missing or unreadable file yields a
+/** Load the runner's persisted state; never throws — a missing or unreadable file yields a
  * fresh state, fields absent from an older file fall back to defaults, and a numeric field
  * (top-level or nested) that is present but not a finite non-negative number is healed to 0,
  * a nested record that is present but not a plain object is dropped, and lastReview.reasons is
@@ -119,11 +82,19 @@ function migrateLegacyStateKeys(saved) {
  * keeps a hand-edited string, null, or negative out of the schedulers and the dashboards'
  * arithmetic instead of relying on each reader to guard it. Optional fields that are absent
  * stay absent, so an older state file's shape is preserved. */
-export function loadLoopState(root, role) {
+export function loadRunnerState(root, role) {
     const saved = readJsonFile(statePath(root, role));
     if (saved !== undefined && saved !== null && isJsonObject(saved))
         migrateLegacyStateKeys(saved);
-    const s = { ...freshLoopState(role), ...(saved ?? {}) };
+    const s = { ...freshRunnerState(role), ...(saved ?? {}) };
+    // The file name is the identity: a state file written by an older build (or moved by
+    // migrateLegacyRoleIds) can carry a stale `role` inside, and saveRunnerState writes
+    // statePath(root, state.role) — so letting the saved value win would save the file back
+    // under a retired id and leak a frozen copy for every later start to reload (the frozen-copy
+    // split behind BUGS.md 2026-10-23). Force the role the caller asked for, whatever the file
+    // says, so the state saves (and loads) under the name it was asked for.
+    // (Retired-name-ok: legacy role id read from an old state file.)
+    s.role = role;
     s.runs = healNumber(s.runs, 0);
     s.commits = healNumber(s.commits, 0);
     s.nextRunAt = healNumber(s.nextRunAt, 0);
@@ -142,10 +113,21 @@ export function loadLoopState(root, role) {
     healOptionalNumber(s, "quietKillStreak");
     healOptionalNumber(s, "consecutiveErrors");
     healOptionalNumber(s, "noChangeStreak");
+    // The breaker's excused-streak ack is a count like the others — a corrupt value (a negative,
+    // NaN, or foreign type) would otherwise silently defeat or mistime the breaker's bar on the
+    // next poll, so it heals to 0 (a fresh ack) the same way the error streak itself does.
+    healOptionalNumber(s, "streakAcked");
     healOptionalNumber(s, "unreviewFailures");
     healOptionalNumber(s, "parkedSince");
     if (s.skipReason !== undefined && !SKIP_REASONS.includes(s.skipReason))
         delete s.skipReason;
+    // The one-id field an older state file carries folds into the list.
+    const legacy = saved?.lastApprovedPatchId;
+    delete s.lastApprovedPatchId;
+    if (s.approvedPatchIds !== undefined || typeof legacy === "string") {
+        const ids = [...(Array.isArray(s.approvedPatchIds) ? s.approvedPatchIds : []), ...(typeof legacy === "string" ? [legacy] : [])];
+        s.approvedPatchIds = ids.filter((id) => typeof id === "string").slice(-APPROVED_PATCH_IDS_MAX);
+    }
     if (s.reviewResume !== undefined) {
         const r = healRecord(s.reviewResume, (v) => {
             v.attempts = healNumber(v.attempts, 0);
@@ -165,7 +147,7 @@ export function loadLoopState(root, role) {
             v.at = healNumber(v.at, 0);
             // The one nested non-numeric slot whose foreign type throws rather than reads odd: the
             // rejected-review notes build a numbered list from `reasons` (numberedList's `.map`), so
-            // a hand-edited scalar or a missing field would crash the next tick's prompt. Rebuild it
+            // a hand-edited scalar or a missing field would crash the next run's prompt. Rebuild it
             // to its string entries — the same "the field is unusable, start it over" repair the
             // numeric fields get.
             v.reasons = Array.isArray(v.reasons)
@@ -186,6 +168,15 @@ export function loadLoopState(root, role) {
                 ? v.reasonCounts.map((c) => healNumber(c, 0))
                 : undefined;
         });
+    // A torn retry record reads as none: leftover recovery is the backstop for the pin.
+    if (s.mainRedRetry !== undefined &&
+        !(isJsonObject(s.mainRedRetry) &&
+            typeof s.mainRedRetry.head === "string" &&
+            isJsonObject(s.mainRedRetry.entry) &&
+            typeof s.mainRedRetry.entry.role === "string" &&
+            typeof s.mainRedRetry.entry.summary === "string" &&
+            (s.mainRedRetry.waitingSince === undefined || typeof s.mainRedRetry.waitingSince === "number")))
+        s.mainRedRetry = undefined;
     if (s.mergeConflicts !== undefined)
         s.mergeConflicts = healRecord(s.mergeConflicts, (v) => {
             v.count = healNumber(v.count, 0);
@@ -217,9 +208,9 @@ export function loadLoopState(root, role) {
             v.probeAt = healNumber(v.probeAt, 0);
             v.cooldownMs = healNumber(v.cooldownMs, 0);
         });
-    // The image-reroute marker is a one-shot nested record consumed by the next tick; a torn
+    // The image-reroute marker is a one-shot nested record consumed by the next run; a torn
     // scalar is dropped (its consumers read/mutate fields), and the tier is repaired to a
-    // known tier name so a corrupt tier cannot route a rerouted tick to a phantom seam.
+    // known tier name so a corrupt tier cannot route a rerouted run to a phantom seam.
     if (s.imageReroute !== undefined) {
         const healed = healRecord(s.imageReroute, () => { });
         s.imageReroute =
@@ -229,51 +220,11 @@ export function loadLoopState(root, role) {
     }
     return s;
 }
-/** Persist the loop's state atomically via writeJsonAtomic, so a crash mid-write cannot
- * leave a torn file behind. Its per-pid tmp name matters here: two processes can write one
- * role's state concurrently — the orchestrator saves at tick end and around its review gate
- * while `tumwater reset-counters` rewrites the same file from the CLI process — and per-pid
- * names give each writer its own tmp with a clean last-writer-wins. */
-export function saveLoopState(root, state) {
-    writeJsonAtomic(statePath(root, state.role), state);
-}
-/** Zero the accumulated counters (runs, commits, tokens, cost) so a fresh observation
- * window can begin. Pure: returns a new state and preserves everything else — scheduling
- * fields (nextRunAt, backoffSeconds), wake tracking (lastMainHead), and the last-result
- * fields. peakContextTokens is zeroed too: under per-tick semantics it holds the loop's
- * last completed tick's peak, so a fresh window must clear it or sleeping loops keep
- * showing their old value until they next tick. The daily cost budget window (dayStamp/
- * dayCostUsd) is deliberately NOT zeroed: the budget is a safety valve, not an observation
- * window — zeroing today's spend would let the cap be bypassed by running reset-counters.
- */
-export function zeroCounters(s) {
-    return { ...s, runs: 0, commits: 0, generatedTokens: 0, peakContextTokens: 0, totalCostUsd: 0 };
-}
-/** The skip reason a loop's persisted state yields when it does not run this round: a pending
- * resume wait outranks backoff, anything else is idle. The shared tail of the two skip
- * classifiers — once-round.ts's settleSkipped (which adds the disabled arm) and cli/cli-run.ts's
- * once-summary (which adds the team-pause arm) — so the two surfaces cannot drift on which
- * reason wins when several conditions hold at once. */
-export function stateSkipReason(s) {
-    if (s.resumePending)
-        return "resume pending";
-    if (s.backoffSeconds > 0)
-        return "backoff"; // vocabulary-ok: skip-reason code is a state value until the state rename
-    return "idle";
-}
-/** True when the loop still owes follow-up work for its current task after a tick: a rejected
- * change it must revise (state.revision) or a session it must resume (state.resumePending).
- * Both keep the instance bound to the same task, so the claim-release rule
- * (tick/tick-finalize.ts), the conflict-handback rule (tick/tick-apply.ts), and claims.ts's
- * idle test all read this one predicate instead of repeating the revision/resume conjunction. */
-export function hasOutstandingWork(s) {
-    return s.revision !== undefined || s.resumePending === true;
-}
 /** Per-role cache of the persisted live claim, keyed by the state file's stat — one stat per
  * role per call in steady state, a read only when the file changed (cachedByStat's contract),
  * so a team poll's allLiveClaims does no read I/O once every claim is known. */
 const liveClaimCache = new Map();
-/** Every loop id whose persisted claim must be considered — the built-in catalog roles
+/** Every runner id whose persisted claim must be considered — the built-in catalog roles
  * (allRoleIds) plus the parallel-work instance ids (feature-2, bugfix-3, …) that have a state
  * file. Instances are not in the built-in catalog, so they are enumerated from the state
  * directory rather than the config: a claim lives in its role's state file, and reading the
@@ -282,17 +233,13 @@ const liveClaimCache = new Map();
  * base). Any state file whose id resolves away from itself under baseRoleOf is an instance
  * id; the named non-role files in that directory (orchestrator.json, claude-account.json, …)
  * resolve to themselves and so are skipped, as are the base roles allRoleIds already names. */
-function liveClaimLoopIds(root) {
+function liveClaimRunnerIds(root) {
     const ids = new Set(allRoleIds());
-    try {
-        for (const name of readdirSync(path.join(root, STATE_DIR, "state"))) {
-            const id = name.replace(/\.json$/, "");
-            if (baseRoleOf(id) !== id)
-                ids.add(id);
-        }
-    }
-    catch {
-        // no state directory yet — the catalog roles (fresh, claim-less) suffice
+    // No state directory yet reads empty — the catalog roles (fresh, claim-less) suffice.
+    for (const name of dirEntryNames(path.join(root, STATE_DIR, "state"))) {
+        const id = name.replace(/\.json$/, "");
+        if (baseRoleOf(id) !== id)
+            ids.add(id);
     }
     return [...ids];
 }
@@ -308,10 +255,10 @@ function liveClaimLoopIds(root) {
  * under `feature-2`; callers fold it to its base. */
 export function allLiveClaims(root) {
     const out = new Map();
-    for (const id of liveClaimLoopIds(root)) {
+    for (const id of liveClaimRunnerIds(root)) {
         const file = statePath(root, id);
         const claim = cachedByStat(liveClaimCache, file, file, () => {
-            const s = loadLoopState(root, id);
+            const s = loadRunnerState(root, id);
             return s.claim ? { role: id, key: s.claim.key } : null;
         }, (v) => ({ ...v }));
         if (claim)

package/dist/src/runner/runner-state.js

@@ -0,0 +1,102 @@
+import { writeJsonAtomic } from "../files/json-files.js";
+import { statePath } from "../paths.js";
+import { tryOrWarn } from "../events/events.js";
+/** The runner's persisted state file — one JSON object per role under .tumwater/ — and the
+ * observation-window counter reset: fresh-state defaults, the atomic save, and zeroCounters
+ * (the tolerant load and the live-claim scan are runner-state-load.ts). The scheduling POLICY
+ * that mutates this state from run outcomes and operator wakes — the outcome application and
+ * resume limits in run-apply.ts, the clock arithmetic (backoff ladders, wakes, yield ring) in
+ * backoff.ts; the generic file helpers are src/files/files.ts and the JSON convention itself is
+ * src/files/json-files.ts. */
+/** How many times a progressing-timeout review may be resumed before the next attempt
+ * reviews the change from scratch (RunnerState.reviewResume). The budget bounds a reviewer that
+ * keeps timing out mid-progress, so a wedged review converges to a fresh run instead of
+ * resuming the same session forever. */
+export const REVIEW_RESUME_LIMIT = 2;
+/** Approved patch-ids a runner remembers (RunnerState.approvedPatchIds). */
+export const APPROVED_PATCH_IDS_MAX = 8;
+export const SKIP_REASONS = [
+    "no-free-entry",
+    "claim-hold",
+    "deferred-backlog",
+    "deferred-no-work",
+    "deferred-plans-full",
+    "instances-full",
+    "maintenance-due-cap",
+    "yield-gap",
+];
+/** A new RunnerState for one role, before its first run. */
+export function freshRunnerState(role) {
+    return {
+        role,
+        runs: 0,
+        commits: 0,
+        nextRunAt: 0,
+        backoffSeconds: 0,
+        lastMainHead: "",
+        generatedTokens: 0,
+        peakContextTokens: 0,
+        totalCostUsd: 0,
+        dayStamp: "",
+        dayCostUsd: 0,
+    };
+}
+/** Persist the runner's state atomically via writeJsonAtomic, so a crash mid-write cannot
+ * leave a torn file behind. Its per-pid tmp name matters here: two processes can write one
+ * role's state concurrently — the orchestrator saves at run end and around its review gate
+ * while `tumwater reset-counters` rewrites the same file from the CLI process — and per-pid
+ * names give each writer its own tmp with a clean last-writer-wins. */
+export function saveRunnerState(root, state) {
+    writeJsonAtomic(statePath(root, state.role), state);
+}
+/** Save for callers that cannot afford a throw — the orchestrator's poll loop, which has no
+ * catch, and a run's end, where a throw would skip run_end and the launch task's breaker fold:
+ * a failed write warns under the role's id and returns. The in-memory state stays ahead of the
+ * file until the runner's next successful save. */
+export function saveRunnerStateBestEffort(root, state) {
+    tryOrWarn(root, state.role, "save the role's state", () => saveRunnerState(root, state));
+}
+/** Zero the accumulated counters (runs, commits, tokens, cost) so a fresh observation
+ * window can begin. Pure: returns a new state and preserves everything else — scheduling
+ * fields (nextRunAt, backoffSeconds), wake tracking (lastMainHead), and the last-result
+ * fields. peakContextTokens is zeroed too: under per-run semantics it holds the runner's
+ * last completed run's peak, so a fresh window must clear it or sleeping runners keep
+ * showing their old value until they next run. The daily cost budget window (dayStamp/
+ * dayCostUsd) is deliberately NOT zeroed: the budget is a safety valve, not an observation
+ * window — zeroing today's spend would let the cap be bypassed by running reset-counters.
+ */
+export function zeroCounters(s) {
+    return { ...s, runs: 0, commits: 0, generatedTokens: 0, peakContextTokens: 0, totalCostUsd: 0 };
+}
+/** The skip reason a runner's persisted state yields when it does not run this round: a pending
+ * resume wait outranks backoff, anything else is idle. The shared tail of the two skip
+ * classifiers — once-round.ts's settleSkipped (which adds the disabled arm) and cli/cli-start.ts's
+ * once-summary (which adds the team-pause arm) — so the two surfaces cannot drift on which
+ * reason wins when several conditions hold at once. */
+export function stateSkipReason(s) {
+    if (s.resumePending)
+        return "resume pending";
+    if (s.backoffSeconds > 0)
+        return "backoff"; // vocabulary-ok: skip-reason code is a state value until the state rename
+    return "idle";
+}
+/** True when the runner still owes follow-up work for its current task after a run: a rejected
+ * change it must revise (state.revision) or a session it must resume (state.resumePending).
+ * Both keep the instance bound to the same task, so the claim-release rule
+ * (run/run-finalize.ts), the conflict-handback rule (run/run-apply.ts), and claims.ts's
+ * idle test all read this one predicate instead of repeating the revision/resume conjunction. */
+export function hasOutstandingWork(s) {
+    return s.revision !== undefined || s.resumePending === true;
+}
+/** True when the runner got an explicit operator wake after its last completed run
+ * (state.wokenAt newer than lastRunEndedAt), so the scheduler ships its min-interval gap and
+ * the need-based deferral stands the runner down. The single home of the "freshly woken since
+ * the last run end" test, previously repeated inline by the due-check, plan deferral, and
+ * need-based deferral (scheduling.ts's isEligible, planDeferral, and deferRunReason) and by
+ * the orchestrator's fresh-demand and plans-full stand-down tests (scheduling-skip.ts's
+ * per-runner demand and scheduling-admit.ts's stand-down guard), so those surfaces cannot drift
+ * on what counts
+ * as a fresh wake. */
+export function freshlyWoken(s) {
+    return s.wokenAt !== undefined && s.wokenAt > (s.lastRunEndedAt ?? 0);
+}