tumwater 0.4.2 → 0.4.4

package/dist/src/failure/failure-state-change.js

@@ -8,13 +8,12 @@
 import { truncateExample } from "./failure-cluster.js";
 import { cutSplitsSurrogatePair, isNonBlankString } from "../text/text.js";
 import { finiteNumber, isJsonObject, stringList } from "../files/json-object.js";
-import { orchestratorStopPhrase, backendKindPhrase, budgetPhrase, teamPausePhrase, teamResumePhrase, holdPhrase, plural, rolePausePhrase, roleResumePhrase, rolesPhrase, shortSpanPhrase, rendersAsBackendFailure, PAUSE_EXPIRED_SUFFIX } from "../text/phrases.js";
+import { orchestratorStopPhrase, backendKindPhrase, budgetPhrase, teamPausePhrase, teamResumePhrase, holdPhrase, plural, rolePausePhrase, roleResumePhrase, rolesPhrase, rendersAsBackendFailure, PAUSE_EXPIRED_SUFFIX } from "../text/phrases.js";
 import { shortSha } from "../text/format.js";
 import { deferredReasonText, untilClockSuffix, gigabytes, windowSuffix, windowResetPhrase, backendLabel } from "../events/event-format.js";
-import { claudeUtilizationPct } from "../agent/claude/claude-account.js";
 /** The transition events the digest replays: the decisions the harness made about itself (the
  * cap/team gates and the team hold, the error-streak breaker's pause, the role's own daily
- * cap, model fallbacks, live-config edits, self-hosted redeploys, need-based deferrals,
+ * cap, live-config edits, self-hosted redeploys, need-based deferrals,
  * orchestrator lifecycle, and the gate holds/lifts that stop and restart work — low disk,
  * quiet hours, the maintenance allowance and the subscription-window reserve). Everything the
  * set omits is deliberately excluded and named in STATE_CHANGE_EXCLUDED_TYPES; the two sets
@@ -25,48 +24,55 @@ import { claudeUtilizationPct } from "../agent/claude/claude-account.js";
  * selfcheck role's load-bearing rule asks it to
  * judge — whether the harness's RESPONSE to a failure was wrong (plans/telemetry-role.md) —
  * so they sit beside the outcomes rather than being dropped. */
-export const STATE_CHANGE_TYPES = new Set([
-    "budget_paused",
-    "budget_fallback",
-    "budget_resumed",
-    "team_paused",
-    "team_resumed",
-    "role_paused",
-    "role_resumed",
-    "role_streak_paused",
-    "role_cap_paused",
-    "role_cap_resumed",
-    "model_fallback_started",
-    "model_fallback_ended",
-    "rate_limit_hold",
-    "rate_limit_resumed",
-    "max_concurrent_changed",
-    "retention_changed",
-    "config_changed",
-    "build_stale",
-    "restart_pending",
-    "restart",
-    "restart_refused",
-    "restart_blocked",
-    "run_deferred",
-    "orchestrator_start",
-    "orchestrator_stop",
-    "supervisor_exit",
-    "disk_low",
-    "disk_ok",
-    "quiet_hours_started",
-    "quiet_hours_ended",
-    "maintenance_quota_hold",
-    "maintenance_quota_resumed",
-    "subscription_window_reserved",
-    "subscription_window_limited",
-    "subscription_window_reset",
-    "provider_concurrency_changed",
-    "model_changed",
-    "bootstrap_complete",
-    "fallback_switched",
-    "budget_handback",
-]);
+const STATE_CHANGE_FAMILY = {
+    // Budget and window reopening.
+    budget_paused: budgetStateChange,
+    budget_fallback: budgetStateChange,
+    budget_resumed: budgetStateChange,
+    // Pauses and resumes of teams, roles and caps.
+    team_paused: pauseStateChange,
+    team_resumed: pauseStateChange,
+    role_paused: pauseStateChange,
+    role_resumed: pauseStateChange,
+    role_streak_paused: pauseStateChange,
+    role_cap_paused: pauseStateChange,
+    role_cap_resumed: pauseStateChange,
+    // Model and fallback wiring.
+    model_changed: modelStateChange,
+    fallback_switched: modelStateChange,
+    budget_handback: modelStateChange,
+    // Provider hold and resume.
+    rate_limit_hold: providerHoldStateChange,
+    rate_limit_resumed: providerHoldStateChange,
+    // Live-config edits.
+    max_concurrent_changed: liveConfigStateChange,
+    retention_changed: liveConfigStateChange,
+    config_changed: liveConfigStateChange,
+    // Self-hosted redeploys.
+    build_stale: updateStateChange,
+    restart_pending: updateStateChange,
+    restart: updateStateChange,
+    restart_refused: updateStateChange,
+    restart_blocked: updateStateChange,
+    // Need-based deferrals and gate holds/lifts.
+    run_deferred: waitStateChange,
+    disk_low: waitStateChange,
+    disk_ok: waitStateChange,
+    quiet_hours_started: waitStateChange,
+    quiet_hours_ended: waitStateChange,
+    maintenance_quota_hold: waitStateChange,
+    maintenance_quota_resumed: waitStateChange,
+    subscription_window_limited: waitStateChange,
+    subscription_window_reset: waitStateChange,
+    // Orchestrator lifecycle.
+    orchestrator_start: lifecycleStateChange,
+    orchestrator_stop: lifecycleStateChange,
+    supervisor_exit: lifecycleStateChange,
+    bootstrap_complete: lifecycleStateChange,
+};
+/** The event types the digest replays, derived from STATE_CHANGE_FAMILY's keys so the filter
+ * set can never drift from the dispatch. */
+export const STATE_CHANGE_TYPES = new Set(Object.keys(STATE_CHANGE_FAMILY));
 /** The event types the digest deliberately does not replay, one per EVENT_TYPE_LABELS key that
  * is not a STATE_CHANGE_TYPES member. Together with STATE_CHANGE_TYPES it partitions
  * EVENT_TYPE_LABELS' keys, so a new event type must be classified in one set or the other — the
@@ -120,13 +126,13 @@ export const STATE_CHANGE_EXCLUDED_TYPES = new Set([
     "check_wait",
     // Observations and actions.
     "disk_reclaim",
-    "subscription_window_warning",
     "image_blind",
     // State-adjacent but not self-decisions.
     "state_migrated",
     "restart_forced",
     "backend_binary",
     "opencode_free_model_billed",
+    "image_reroute",
 ]);
 /** The Team state changes section's caps: newest N transitions, each line's payload capped at
  * STATE_CHANGE_MAX (a marked word-boundary cut per truncateExample), each free field within it
@@ -171,16 +177,10 @@ function field(v) {
 }
 /** The backend a fallback-ish decision line names, as "provider/model", defaulting each half
  * to pi's own default when the event omits it and slicing both through field. Shared by the
- * budget_fallback and model_fallback lines so the default and its slice rule stay in one place. */
+ * budget_fallback line so the default and its slice rule stay in one place. */
 function providerModel(ev) {
     return `${field(ev.provider ?? "pi default")}/${field(ev.model ?? "pi default")}`;
 }
-/** A utilization fraction as its whole-number percent, read through finiteNumber so a torn or
- * hand-edited subscription event renders 0% rather than NaN — the same corrupt-field rule the
- * feed's own subscription lines apply. */
-function pct(v) {
-    return claudeUtilizationPct(finiteNumber(v, 0));
-}
 /** A per-family builder of one state-change line, one per event family, so the budget, pause,
  * model-wiring, provider-hold, live-config, update, wait and lifecycle wordings are each found
  * by name. Each is a total function over any HarnessEvent — its `default` returns the bare type
@@ -250,18 +250,6 @@ function pauseStateChange(ev) {
 function modelStateChange(ev) {
     let text;
     switch (ev.type) {
-        case "model_fallback_started":
-            // The role tripped off its primary onto its fallback after provider-class failures.
-            text = `model fallback — ${providerModel(ev)} engaged (${field(ev.reason ?? "backend failure")})`;
-            break;
-        case "model_fallback_ended":
-            // The return counterpart: names the primary the role resumed on and how long the
-            // off-model episode ran.
-            text = `model fallback ended — back on ${providerModel(ev)} after ${shortSpanPhrase(finiteNumber(ev.durationMs, 0))}`;
-            break;
-        case "provider_concurrency_changed":
-            text = `${field(ev.provider)} concurrency ${field(ev.from)} → ${field(ev.to)}`;
-            break;
         case "model_changed":
             // A model_cleared (or a roles.<id>.model-only) live edit arrives with `to: null`;
             // name pi's default the way the feed does so the digest never renders a bare
@@ -401,9 +389,6 @@ function waitStateChange(ev) {
         case "maintenance_quota_resumed":
             text = `maintenance allowance reopened — ${field(ev.maint)}/${field(ev.allowance)} in 24h`;
             break;
-        case "subscription_window_reserved":
-            text = `waiting: ${backendLabel(ev)} window ${field(ev.windowType)} at ${pct(ev.utilization)}% past its ${pct(ev.reserve)}% reserve`;
-            break;
         case "subscription_window_limited":
             text = `waiting: ${backendLabel(ev)} window ${field(ev.windowType)} rejected${windowResetPhrase(ev)}`;
             break;
@@ -442,56 +427,5 @@ function lifecycleStateChange(ev) {
  * read as complete or stand mid-word where a key or value should be; the render adds the
  * timestamp and a roleCell-sliced role, so no unbounded field reaches the page. */
 export function describeStateChange(ev) {
-    switch (ev.type) {
-        case "budget_paused":
-        case "budget_fallback":
-        case "budget_resumed":
-            return truncateExample(budgetStateChange(ev), STATE_CHANGE_MAX);
-        case "team_paused":
-        case "team_resumed":
-        case "role_paused":
-        case "role_resumed":
-        case "role_streak_paused":
-        case "role_cap_paused":
-        case "role_cap_resumed":
-            return truncateExample(pauseStateChange(ev), STATE_CHANGE_MAX);
-        case "model_fallback_started":
-        case "model_fallback_ended":
-        case "provider_concurrency_changed":
-        case "model_changed":
-        case "fallback_switched":
-        case "budget_handback":
-            return truncateExample(modelStateChange(ev), STATE_CHANGE_MAX);
-        case "rate_limit_hold":
-        case "rate_limit_resumed":
-            return truncateExample(providerHoldStateChange(ev), STATE_CHANGE_MAX);
-        case "max_concurrent_changed":
-        case "retention_changed":
-        case "config_changed":
-            return truncateExample(liveConfigStateChange(ev), STATE_CHANGE_MAX);
-        case "build_stale":
-        case "restart_pending":
-        case "restart":
-        case "restart_refused":
-        case "restart_blocked":
-            return truncateExample(updateStateChange(ev), STATE_CHANGE_MAX);
-        case "run_deferred":
-        case "disk_low":
-        case "disk_ok":
-        case "quiet_hours_started":
-        case "quiet_hours_ended":
-        case "maintenance_quota_hold":
-        case "maintenance_quota_resumed":
-        case "subscription_window_reserved":
-        case "subscription_window_limited":
-        case "subscription_window_reset":
-            return truncateExample(waitStateChange(ev), STATE_CHANGE_MAX);
-        case "orchestrator_start":
-        case "orchestrator_stop":
-        case "supervisor_exit":
-        case "bootstrap_complete":
-            return truncateExample(lifecycleStateChange(ev), STATE_CHANGE_MAX);
-        default:
-            return truncateExample(ev.type, STATE_CHANGE_MAX);
-    }
+    return truncateExample(STATE_CHANGE_FAMILY[ev.type]?.(ev) ?? ev.type, STATE_CHANGE_MAX);
 }

package/dist/src/failure/{time-spend.js → failure-time-spend.js}

@@ -87,92 +87,125 @@ function resolveQueuedRuns(runEvents, allEvents) {
 }
 /** Classify one run's loss cause into the key/kind/example triple the ranking folds, or null
  * when the run prices no loss. The branch order is the contract: refused, then cut-off, then
- * no_change, then clustered, then the three queued outcomes; the deadline-killed merge-block
- * special case still overrides `key`/`example` inside its branch. Reads the per-runner join
- * indexes from `indexes` so the ladder names each rule by a single lookup. */
+ * no_change, then clustered, then the three queued outcomes — each rule owned by its own
+ * named helper below, so the `??` chain reads left to right in the same order. Reads the
+ * per-runner join indexes from `indexes` so each helper names a rule by a single lookup. */
 function lossCauseFor(ev, cls, resolvedOutcome, indexes) {
-    let key = null;
-    let kind = "error-cluster";
-    let example = "";
-    if (ev.result === "refused") {
-        // A refusal is a deliberate objection that blocks its entry, not quiet idleness — the
-        // reason live in the event + lastSummary (src/verdict/refusal.ts). Rank it as its own
-        // per-role cause so the digest surfaces the objection instead of pricing the run
-        // exactly like a silently idle one; the branch sits BEFORE the no_change one because a
-        // refused run is also no_change-class in the outcome table. The example rides the
-        // refusal's summary the way a review-rejected cause rides its reason.
-        key = `refused\u0000${eventRole(ev)}`;
-        kind = "refused";
-        example = typeof ev.summary === "string" ? truncateExample(ev.summary) : "";
-    }
-    else if (cls === "no_change" && ev.cutOff === true) {
-        // A run truncated at its model's context ceiling ends no_change with cutOff: true
-        // (diagnoseNoChange in src/run/run-verdict.ts), and finalizeRun rides that flag onto
-        // the run_end. Rank it as its own per-role cause so the digest separates the churn of
-        // a context ceiling — a cost of a long session, which the harness resumes — from
-        // deliberate idleness; the branch sits BEFORE the no_change one because a cut-off run
-        // is also no_change-class in the outcome table. No example, like the no_change cause.
-        key = `cutoff\u0000${eventRole(ev)}`;
-        kind = "cutoff";
-    }
-    else if (cls === "no_change") {
-        key = `no_change\u0000${eventRole(ev)}`;
-        kind = "no_change";
-    }
-    else if (CLUSTERED_RESULTS.has(String(ev.result))) {
-        // A clustered result with no error text still owns its time: an abort's run_end never
-        // carries one (planRunStart clears s.lastError, run-finalize logs error: undefined),
-        // and a malformed error run can lose it too, so both take the same placeholder cause the
-        // error-clusters section already itemizes rather than dropping the span itemized nowhere.
-        ({ key, example } = pooledClusterCause(ev.error));
-    }
-    else if (ev.result === "queued" && resolvedOutcome?.result === "rejected") {
-        key = `review-rejected\u0000${eventRole(ev)}`;
-        kind = "review-rejected";
-        // Match the merge ATTEMPT, not the pin's sha: every verification rebases its pin onto main
-        // before the gate (syncPinToMain), so `review_rejected.head` is the rebased commit while
-        // `merge_queued` keeps the authored one — exact-sha equality names no reason for a rebased
-        // rejection (BUGS.md 2026-10-10). The rejection for this attempt is the one inside the
-        // claimed pin and its outcome, the window no other attempt can occupy.
-        const rej = newestAttemptEvent(indexes.rejectedByRunner, eventRole(ev), resolvedOutcome);
-        const reasons = stringList(rej?.reasons);
-        example = reasons[0] !== undefined ? truncateExample(reasons[0]) : "";
-    }
-    else if (ev.result === "queued" && resolvedOutcome?.result === "review_error") {
-        // The review process itself failed (a dead backend, a timeout, no parseable verdict):
-        // the pin was kept and re-queued, and the matching `review_failed` event carries the
-        // message the review-failure section already clusters. Price the authoring span under
-        // that cluster's key — a review timeout pools into the shared `timed out after <dur>`
-        // cause via poolTimeoutKey — and fall back to the shared placeholder when no event is
-        // visible, so the span is itemized rather than hidden. The match keys on the merge
-        // ATTEMPT, not the pin's sha: every verification rebases its pin onto main before the gate
-        // (syncPinToMain), so `review_failed.head` is the rebased commit while `merge_queued`
-        // keeps the authored one — exact-sha equality missed every rebased verification (BUGS.md
-        // 2026-10-10). The review failure for this attempt is the one that falls inside the
-        // claimed pin and its outcome, the window no other attempt can occupy.
-        const failed = newestAttemptEvent(indexes.reviewFailedByRunner, eventRole(ev), resolvedOutcome);
-        ({ key, example } = pooledClusterCause(failed?.message));
-    }
-    else if (ev.result === "queued" &&
-        (resolvedOutcome?.result === "merge_conflict" || resolvedOutcome?.result === "merge_blocked")) {
-        // The merge failed to merge (a conflict, or a blocked fast-forward/rebase): this
-        // authoring span burned. The `merge_failed` event carries no message — writeMergeOutcome
-        // logs only result/commit/durationMs/usage — so the cause is named by its own result and
-        // takes the shared no-text placeholder, the same fallback a message-less aborted run_end
-        // uses, rather than dropping a span the error-class cell already priced (BUGS.md
-        // 2026-10-10).
-        key = `${resolvedOutcome.result}\u0000${eventRole(ev)}`;
-        kind = resolvedOutcome.result === "merge_conflict" ? "merge-conflict" : "merge-blocked";
-        example = errorTextOrPlaceholder(undefined);
-        // A merge-scope check the harness killed at its own deadline is the team's load, not a
-        // verdict on the change: split it into its own cause so the ranking names it.
-        const killed = newestAttemptEvent(indexes.deadlineKilledByRunner, eventRole(ev), resolvedOutcome);
-        if (kind === "merge-blocked" && killed) {
-            key = `merge_blocked_deadline\u0000${eventRole(ev)}`;
-            example = `${String(killed.scope)} build check killed at its ${nonNegativeNumber(killed.timeoutMs, 0) / 1000}s deadline (tumwater's own timeout, not a test failure)`;
-        }
+    return (refusedLoss(ev) ??
+        cutoffLoss(ev, cls) ??
+        noChangeLoss(ev, cls) ??
+        clusteredLoss(ev) ??
+        reviewRejectedLoss(ev, resolvedOutcome, indexes) ??
+        reviewErrorLoss(ev, resolvedOutcome, indexes) ??
+        mergeFailureLoss(ev, resolvedOutcome, indexes));
+}
+/** The refused rule: a run whose verdict refused prices its own per-role cause, not no_change. */
+function refusedLoss(ev) {
+    if (ev.result !== "refused")
+        return null;
+    // A refusal is a deliberate objection that blocks its entry, not quiet idleness — the
+    // reason live in the event + lastSummary (src/verdict/refusal.ts). Rank it as its own
+    // per-role cause so the digest surfaces the objection instead of pricing the run
+    // exactly like a silently idle one; the branch sits BEFORE the no_change one because a
+    // refused run is also no_change-class in the outcome table. The example rides the
+    // refusal's summary the way a review-rejected cause rides its reason.
+    return {
+        key: `refused\u0000${eventRole(ev)}`,
+        kind: "refused",
+        example: typeof ev.summary === "string" ? truncateExample(ev.summary) : "",
+    };
+}
+/** The cut-off rule: a no_change run truncated at its context ceiling prices its own cause. */
+function cutoffLoss(ev, cls) {
+    if (cls !== "no_change" || ev.cutOff !== true)
+        return null;
+    // A run truncated at its model's context ceiling ends no_change with cutOff: true
+    // (diagnoseNoChange in src/run/run-verdict.ts), and finalizeRun rides that flag onto
+    // the run_end. Rank it as its own per-role cause so the digest separates the churn of
+    // a context ceiling — a cost of a long session, which the harness resumes — from
+    // deliberate idleness; the branch sits BEFORE the no_change one because a cut-off run
+    // is also no_change-class in the outcome table. No example, like the no_change cause.
+    return { key: `cutoff\u0000${eventRole(ev)}`, kind: "cutoff", example: "" };
+}
+/** The no_change rule: a silent no_change run prices its own per-role cause. */
+function noChangeLoss(ev, cls) {
+    if (cls !== "no_change")
+        return null;
+    return { key: `no_change\u0000${eventRole(ev)}`, kind: "no_change", example: "" };
+}
+/** The clustered rule: a clustered result with no error text prices under the pooled cluster. */
+function clusteredLoss(ev) {
+    if (!CLUSTERED_RESULTS.has(String(ev.result)))
+        return null;
+    // A clustered result with no error text still owns its time: an abort's run_end never
+    // carries one (planRunStart clears s.lastError, run-finalize logs error: undefined),
+    // and a malformed error run can lose it too, so both take the same placeholder cause the
+    // error-clusters section already itemizes rather than dropping the span itemized nowhere.
+    const pooled = pooledClusterCause(ev.error);
+    return { key: pooled.key, kind: "error-cluster", example: pooled.example };
+}
+/** The review-rejected rule: a queued run whose merge was rejected prices its reason. */
+function reviewRejectedLoss(ev, resolvedOutcome, indexes) {
+    if (ev.result !== "queued" || resolvedOutcome?.result !== "rejected")
+        return null;
+    // Match the merge ATTEMPT, not the pin's sha: every verification rebases its pin onto main
+    // before the gate (syncPinToMain), so `review_rejected.head` is the rebased commit while
+    // `merge_queued` keeps the authored one — exact-sha equality names no reason for a rebased
+    // rejection (BUGS.md 2026-10-10). The rejection for this attempt is the one inside the
+    // claimed pin and its outcome, the window no other attempt can occupy.
+    const rej = newestAttemptEvent(indexes.rejectedByRunner, eventRole(ev), resolvedOutcome);
+    const reasons = stringList(rej?.reasons);
+    return {
+        key: `review-rejected\u0000${eventRole(ev)}`,
+        kind: "review-rejected",
+        example: reasons[0] !== undefined ? truncateExample(reasons[0]) : "",
+    };
+}
+/** The review_error rule: a queued run whose review process failed prices under its cluster. */
+function reviewErrorLoss(ev, resolvedOutcome, indexes) {
+    if (ev.result !== "queued" || resolvedOutcome?.result !== "review_error")
+        return null;
+    // The review process itself failed (a dead backend, a timeout, no parseable verdict):
+    // the pin was kept and re-queued, and the matching `review_failed` event carries the
+    // message the review-failure section already clusters. Price the authoring span under
+    // that cluster's key — a review timeout pools into the shared `timed out after <dur>`
+    // cause via poolTimeoutKey — and fall back to the shared placeholder when no event is
+    // visible, so the span is itemized rather than hidden. The match keys on the merge
+    // ATTEMPT, not the pin's sha: every verification rebases its pin onto main before the gate
+    // (syncPinToMain), so `review_failed.head` is the rebased commit while `merge_queued`
+    // keeps the authored one — exact-sha equality missed every rebased verification (BUGS.md
+    // 2026-10-10). The review failure for this attempt is the one that falls inside the
+    // claimed pin and its outcome, the window no other attempt can occupy.
+    const failed = newestAttemptEvent(indexes.reviewFailedByRunner, eventRole(ev), resolvedOutcome);
+    const pooled = pooledClusterCause(failed?.message);
+    return { key: pooled.key, kind: "error-cluster", example: pooled.example };
+}
+/** The merge-failure rule: a queued run whose merge conflicted or was blocked prices its own
+ * cause, with the deadline-killed merge-block special case overriding key/example. */
+function mergeFailureLoss(ev, resolvedOutcome, indexes) {
+    if (ev.result !== "queued" ||
+        (resolvedOutcome?.result !== "merge_conflict" && resolvedOutcome?.result !== "merge_blocked"))
+        return null;
+    // The merge failed to merge (a conflict, or a blocked fast-forward/rebase): this
+    // authoring span burned. The `merge_failed` event carries no message — writeMergeOutcome
+    // logs only result/commit/durationMs/usage — so the cause is named by its own result and
+    // takes the shared no-text placeholder, the same fallback a message-less aborted run_end
+    // uses, rather than dropping a span the error-class cell already priced (BUGS.md
+    // 2026-10-10).
+    const key = `${resolvedOutcome.result}\u0000${eventRole(ev)}`;
+    const kind = resolvedOutcome.result === "merge_conflict" ? "merge-conflict" : "merge-blocked";
+    const example = errorTextOrPlaceholder(undefined);
+    // A merge-scope check the harness killed at its own deadline is the team's load, not a
+    // verdict on the change: split it into its own cause so the ranking names it.
+    const killed = newestAttemptEvent(indexes.deadlineKilledByRunner, eventRole(ev), resolvedOutcome);
+    if (kind === "merge-blocked" && killed) {
+        return {
+            key: `merge_blocked_deadline\u0000${eventRole(ev)}`,
+            kind,
+            example: `${String(killed.scope)} build check killed at its ${nonNegativeNumber(killed.timeoutMs, 0) / 1000}s deadline (tumwater's own timeout, not a test failure)`,
+        };
     }
-    return key === null ? null : { key, kind, example };
+    return { key, kind, example };
 }
 /** The pooled cluster key and truncated example a failure-message source's span prices under:
  * the shared placeholder when the source carries no message, the pooled render

package/dist/src/files/files.js

@@ -117,6 +117,25 @@ export function readTextOrNull(file) {
         return null; // Missing or unreadable — no data.
     }
 }
+/** Read a text file whole, but only when it is a regular file: a symlink (or directory,
+ * gitlink, FIFO) is never followed, so a hostile entry that points out of the worktree cannot
+ * pull an arbitrary host file's text into whatever reads it (the same lstat policy INV-G3 and
+ * INV-G4 pin for the merge gates). A symlink holds no text of its own and its target could
+ * name a sensitive host path, so it reads as absent. Null when the file is missing/unreadable,
+ * or not a regular file. This is the reader for the two prompt-input files whose text is
+ * injected into every model run — PRINCIPLES.md and a role's notes — and their operator
+ * readers, so the prompt and the surfaces reporting on those files cannot disagree;
+ * readTextOrNull stays for paths where following a symlink is acceptable or impossible. */
+export function readRegularTextOrNull(file) {
+    try {
+        if (!fs.lstatSync(file).isFile())
+            return null; // not a regular file: never followed
+        return fs.readFileSync(file, "utf8");
+    }
+    catch {
+        return null; // Missing or unreadable — no data.
+    }
+}
 /** Read a text file whole, or null only when it does not exist (ENOENT) — for the paths that
  * must never mistake an unreadable file for an absent one. A permission or I/O failure (EACCES,
  * EISDIR, EMFILE) is rethrown so the caller fails loudly instead of treating the file as gone:
@@ -351,6 +370,17 @@ export function removeQuiet(file) {
         // Already gone (or unremovable) — cleanup must not throw.
     }
 }
+/** Delete `file` and return whether it was there to delete — the toggle-lift idiom shared by
+ * resumeTeam and cancelScheduledStop (the team's marker-lift functions): true when a marker
+ * was present and removed, false when it was already gone. Relies on removeQuiet's
+ * never-throws delete, so a marker vanishing between an existsSync check and the unlink reads
+ * as success rather than a failure to surface from a toggle. */
+export function removeIfPresent(file) {
+    if (!fs.existsSync(file))
+        return false;
+    removeQuiet(file);
+    return true;
+}
 /** Delete a directory tree, retrying the transient filesystem races (`ENOTEMPTY`/`EBUSY`/
  * `EPERM`) that recursive `rmSync` otherwise turns into a hard failure. Node defaults
  * `maxRetries` to 0, and on macOS an entry appearing between `rmSync`'s walk and its `rmdir`

package/dist/src/files/json-object.js

@@ -16,8 +16,8 @@ export function isJsonObject(value) {
  * when it is an array and [] otherwise — the one home of the "an event/record field is the
  * list or it is nothing" read every formatter applies (event-format.ts's review_rejected
  * reasons, dep_install packages, config_changed keys; src/failure/failure-state-change.ts's
- * config_changed keys; time-spend.ts's review-rejection reasons; team-state.ts's paused-roles
- * list). A torn or hand-edited line
+ * config_changed keys; failure-time-spend.ts's review-rejection reasons; team-state.ts's
+ * paused-roles list). A torn or hand-edited line
  * never throws and never renders a placeholder: the field reads as absent, and the caller's
  * empty-list branch fires. Foreign entries inside an array are dropped for the same reason —
  * letting them through made `join` render "[object Object]" and handed
@@ -36,9 +36,9 @@ export function stringList(value) {
  * build_stale, slot_wait, restart, and permit_reserve renderers (aheadCommits, waitedMs,
  * abortedRuns, reserve → 0); phrases.ts's budgetPhrase (spentUsd, capUsd → 0); redeploy.ts's
  * autoRestartRecord (lastAt → null); build/build-info.ts's readBuildInfo (builtAt → 0);
- * failure/failure-state-change.ts's model_fallback_ended (durationMs → 0) and build_stale
- * renderer (aheadCommits → 0); gates/maintenance-quota.ts's foldLine and seed (ev.ts → null);
- * team/orchestrator-info.ts's isFiniteNumber (v → undefined); team/team-state.ts's
+ * failure/failure-state-change.ts's build_stale renderer (aheadCommits → 0);
+ * gates/maintenance-quota.ts's foldLine and seed (ev.ts → null);
+ * team/team-orchestrator-info.ts's isFiniteNumber (v → undefined); team/team-state.ts's
  * standingMarker, pausedRoles, and standingRolesUntil (until → undefined);
  * operator/operator-requests.ts's consumeWakeRequest (notBeforeMs → undefined);
  * git/slots-state.ts's readSlotRecord (pinnedAt, lastReleasedAt → null); git/worktree-use.ts's
@@ -57,9 +57,9 @@ export function finiteNumber(value, fallback) {
  * runner/runner-state-load.ts's healNumber (every numeric RunnerState field → 0),
  * run/run-usage.ts's counter (each persisted usage count → 0), pi/pi-stream.ts's usageNumber
  * (one wire usage number → 0), ui/progress-data.ts's message_end read (totalTokens → the
- * previous context, output and its peak floor → 0), time-spend.ts's runDurationMs (an event's
- * durationMs → null, the "no own duration" marker) and its merge_blocked_deadline example
- * (the deadline-killed check's timeoutMs → 0, so a torn deadline prices as 0s, never NaN);
+ * previous context, output and its peak floor → 0), failure-time-spend.ts's runDurationMs (an
+ * event's durationMs → null, the "no own duration" marker) and its merge_blocked_deadline
+ * example (the deadline-killed check's timeoutMs → 0, so a torn deadline prices as 0s, never NaN);
  * pi-extension/context-budget.ts's
  * contextNote (usedTokens, usedWindow → null), pi-extension/context-shake.ts's percentOf
  * (tokens, contextWindow → null), merge/merge-queue.ts's isMergeEntry (run, enqueuedAt,

package/dist/src/files/stat-cache.js

@@ -1,4 +1,4 @@
-import { readTextOrNull, sameStatIdentity, statOrNull } from "./files.js";
+import { readRegularTextOrNull, sameStatIdentity, statOrNull } from "./files.js";
 /** Safety cap so a stat-keyed cache can never grow unbounded (e.g. many short-lived roots in
  * tests). Evicting only costs one re-read per file on the next call. */
 const MAX_STAT_CACHED = 64;
@@ -32,15 +32,19 @@ export function cachedByStat(cache, key, file, load, clone) {
     return clone(value);
 }
 /** One stat-cached read of a text file, or null when it is missing or unreadable — the shared
- * load half over `cachedByStat` for the readers that parse a markdown/text file: readTextOrNull
- * reads it, and a null (no data) propagates through so a render path never throws on the file's
- * state. `parse` runs only on a cache miss and receives the file's text (never null); `clone`
- * hands each caller its own copy. The callers: backlog.ts's sectionEntries and
- * sectionCompletionDates, and backlog-structure.ts's strandedPlanEntriesFor and
- * actionableEntryRangesFor, and backlog-index.ts's renderBacklogIndexBlock. */
+ * load half over `cachedByStat` for the readers that parse a markdown/text file: it reads the
+ * file through readRegularTextOrNull, so a symlink (or directory/gitlink) is never followed —
+ * a hostile entry dropped at a backlog file path cannot pull an arbitrary host file's text into
+ * the run prompts and surfaces these readers feed (the same lstat policy INV-G3/G4 pin for the
+ * prompt readers and merge gates) — and a null (no data) propagates through so a render path
+ * never throws on the file's state. `parse` runs only on a cache miss and receives the file's
+ * text (never null); `clone` hands each caller its own copy. The callers: backlog.ts's
+ * sectionEntries and sectionCompletionDates, backlog-structure.ts's strandedPlanEntriesFor and
+ * actionableEntryRangesFor, backlog-index-data.ts's actionableEntryRangesFor, and
+ * backlog-index.ts's renderBacklogIndexBlock. */
 export function cachedTextByStat(cache, key, file, parse, clone) {
     return cachedByStat(cache, key, file, () => {
-        const md = readTextOrNull(file); // Missing or unreadable — no data.
+        const md = readRegularTextOrNull(file); // Missing, unreadable, or not a regular file — no data.
         return md === null ? null : parse(md);
     }, clone);
 }