@coreplane/switchboard 1.235.0 → 1.237.0

package/dist/assets/deploy/cloudflare-resident/worker.ts

@@ -252,7 +252,13 @@ import {
   type DiskSample,
   type ThreadCostKind,
 } from "../../src/execution/residentDiskBudget.js";
-import { attachTarget, mirrorNeedsFetch, parseWantSha, wantShaForBinding } from "../../src/execution/residentHead.js";
+import {
+  attachTarget,
+  type FetchReason,
+  mirrorFetchReason,
+  parseWantSha,
+  wantShaForBinding,
+} from "../../src/execution/residentHead.js";
 import { residentText, sanitizeResidentBody } from "../../src/execution/residentText.js";
 import {
   abandonedWaitStepResult,
@@ -297,6 +303,9 @@ import {
   parseDepsStoreListing,
   planDepsEviction,
   planDepsMaterialization,
+  DEPS_STORE_MAX_UNREFERENCED_UNDER_PRESSURE,
+  type DepsEvictionPlan,
+  type DepsStoreListing,
 } from "../../src/execution/residentDepsStore.js";
 import { buildId, injectedBuildStamp } from "../../src/deploy/buildStamp.js";
 import { createRefreshInstance, createRefreshInstanceNow, type RefreshInstanceParams } from "./refresh";
@@ -505,16 +514,18 @@ const FORCE_DETACH_KILL_TIMEOUT_MS = 2_000;
  *  binding record is KEPT so the next attach recreates with the same
  *  ref. Overridable per resident via the onboard-time `worktreeTtlDays`. */
 const WORKTREE_TTL_DAYS_DEFAULT = 7;
-/** A live binding whose last attach is older than this AND whose tree is clean
- *  (no uncommitted/unpushed work) is released by the sweep step (every refresh
- *  instance runs one) — runs that ended before /detach existed, or whose
- *  release call was lost. Dirty trees keep to the TTL. */
+/** A live binding whose last attach is older than this and has no op in
+ *  flight is released by the sweep step (every refresh instance runs one),
+ *  whatever its tree holds (item 17) — runs that ended before /detach existed,
+ *  or whose release call was lost. */
 const CLEAN_IDLE_RELEASE_S = 60 * 60;
-/** Idle sleep: when no thread has attached within this window and no live
- *  tree is dirty, the refresh cycle skips the fetch and the cron holds the
- *  next instance to the idle cadence, so the container can actually sleep
- *  (SLEEP_AFTER); the next attach refreshes first if the mirror is stale
- *  (refresh-on-attach). */
+/** Idle sleep: when no live binding was attached to or used within this
+ *  window and nothing is in flight, the refresh cycle skips the fetch and the
+ *  cron holds the next instance to the idle cadence, so the container can
+ *  actually sleep (SLEEP_AFTER); the next attach refreshes first if the mirror
+ *  is stale (refresh-on-attach). The disk-full recycle (item 54) reads the
+ *  same window through the same predicate (`recentlyUsed`): a sleep and a
+ *  recycle destroy the same disk, so one rule says when it may go away. */
 const IDLE_AFTER_S = 60 * 60;
 /** LRU eviction floor: an over-cap onboard with `evictColdest:true` may
  *  offboard the coldest eligible warm resident, but never one whose last
@@ -1000,10 +1011,11 @@ interface ResidentRecord {
 interface ThreadBinding {
   threadKey: string;
   ref: string;
-  /** How `ref` was chosen when the binding was made: the repo default for want
-   *  of a named branch (item 30), or a branch someone named. Absent on a
-   *  binding made before the field: read as `default` iff `ref` is the default
-   *  branch. Only a `default` binding may ever move. */
+  /** How `ref` was chosen: the repo default for want of a named branch — when
+   *  the binding was made (item 30), or when a return put it there because the
+   *  branch it was on is gone (`returned`) — or a branch someone named. Absent
+   *  on a binding made before the field: read as `default` iff `ref` is the
+   *  default branch. Only a `default` binding may ever move onto a branch. */
   boundBy?: BoundBy;
   /** The move a binding may make (item 16): from the default it was bound to,
    *  onto the branch the thread's own run opened a pull request on. Set, the
@@ -1011,6 +1023,12 @@ interface ThreadBinding {
    *  branch was gone from the mirror and the binding went back to the
    *  default), and then for the next own pull request. */
   rebound?: Rebound;
+  /** The binding's last move back to the default (item 16's second movement):
+   *  the branch it was on — one a rebind moved it onto, or one this thread's
+   *  own runs pushed (`ownBranches`) and bound by name, a ship unit's — was
+   *  gone from the mirror at an attach. From where, to where, which pull
+   *  request's branch it was, when. */
+  returned?: Returned;
   /** The branches the thread's own runs pushed and the pull requests they
    *  head, as each run's release handed them over (`/detach` `pushed`, item
    *  16a) — written before any eviction decision, so the fact outlives the
@@ -1037,6 +1055,15 @@ interface ThreadBinding {
   /** Why the tree could not be measured before that eviction (git could not
    *  read it) — so an unreadable tree is never recorded as clean. */
   evictedUnmeasured?: string;
+  /** What the tree held when the last disk-full recycle (item 54) discarded
+   *  it with the disk — the same measurement as `evictedLeftBehind`, under its
+   *  own name because the binding is not evicted: its user is kept and the
+   *  next attach recreates the tree (`worktree-missing`). Both rewritten on
+   *  every recycle; absent when the tree was clean or already gone. */
+  recycledLeftBehind?: LeftBehind;
+  /** Why the tree could not be measured before that recycle (git could not
+   *  read it) — still discarded with the disk, never recorded as clean. */
+  recycledUnmeasured?: string;
   /** How deps were last materialized (evidence that the per-branch reconciliation ran). */
   deps?: ThreadDepsMechanism;
   /** Commit the worktree was last attached at (the ref's tip in the mirror
@@ -1111,9 +1138,10 @@ interface AttachOk {
    *  and why — so the bot can say where the follow-up runs and why. */
   rebindRefused?: RebindRefused;
   /** This attach moved the binding BACK to the default branch (item 16's
-   *  second movement): the branch a rebind had moved it onto is gone from the
-   *  mirror, so the tree was provisioned on the default instead of the attach
-   *  failing `unknown-ref`. From where, to where, which PR's branch it was. */
+   *  second movement): the branch it was on — a rebind's, or one this thread
+   *  itself pushed — is gone from the mirror, so the tree was provisioned on
+   *  the default instead of the attach failing `unknown-ref`. From where, to
+   *  where, which PR's branch it was. */
   returned?: Returned;
 }
 
@@ -2083,13 +2111,20 @@ export class ResidentDO extends Sandbox<Env> {
     throw new StepError("cat-file", `git cat-file exited ${r.exitCode}: ${r.stderr.trim() || "(no output)"}`);
   }
 
-  /** Attach's fetch decision (item 51) over the mirror's actual state: the ref
-   *  is missing, or `wantSha` names a commit the ref's tip is not at. The
-   *  decision itself is the pure, tested `mirrorNeedsFetch`. */
-  private async mirrorNeedsFetchFor(ref: string, wantSha: string | null): Promise<boolean> {
+  /** Attach's fetch decision (item 51) over the mirror's actual state — why
+   *  the mirror is fetched before the tree is cloned, or null: the ref is
+   *  missing, `wantSha` names a commit the ref's tip is not at, or the ref is
+   *  one the binding could return from (item 16's second movement) and is
+   *  verified against the origin before the mirror's word on it is trusted.
+   *  The decision itself is the pure, tested `mirrorFetchReason`. */
+  private async mirrorFetchReasonFor(
+    ref: string,
+    wantSha: string | null,
+    returnable: boolean,
+  ): Promise<FetchReason | null> {
     const refExists = await this.refExists(ref);
     const mirrorSha = refExists && wantSha !== null ? await this.readMirrorSha(ref) : undefined;
-    return mirrorNeedsFetch({ refExists, mirrorSha, wantSha });
+    return mirrorFetchReason({ refExists, mirrorSha, wantSha, returnable });
   }
 
   /** Dependency/build cache key: sha256 over the ls-tree lines (mode,
@@ -2945,12 +2980,11 @@ export class ResidentDO extends Sandbox<Env> {
       throw new CycleRestartError("image-stale-restart");
     }
 
-    // Idle sleep: nobody has attached for IDLE_AFTER_S and no live tree is
-    // dirty → skip this fetch; the cron holds the next instance to the idle
+    // Idle sleep: no live binding used within IDLE_AFTER_S and nothing in
+    // flight → skip this fetch; the cron holds the next instance to the idle
     // cadence, so SLEEP_AFTER can elapse. Staleness is repaid at the next
-    // attach (refreshIfStale). A
-    // dirty live tree pins the container awake: sleep destroys the disk and
-    // uncommitted work is not snapshotted.
+    // attach (refreshIfStale). What a live tree holds is not asked (item 17):
+    // sleep destroys the disk, and a tree no run is using protects nothing.
     // Only a SETTLED resident may park: a cycle that finds `refreshing`/
     // `restoring` at entry is looking at a marker left by a cycle that died
     // mid-flight (a deploy evicting the DO: stuck `refreshing` + parked →
@@ -3002,7 +3036,7 @@ export class ResidentDO extends Sandbox<Env> {
       await this.ctx.storage.delete(DEGRADED_STREAK_KEY);
     }
     if (settled && (await this.isIdle())) {
-      // isIdle awaited (git status per live tree) — re-read before writing.
+      // isIdle awaited (the bindings listing) — re-read before writing.
       const now = (await this.ctx.storage.get<RepoFacts>(FACTS_KEY)) ?? facts;
       if (!now.idleSince)
         await this.ctx.storage.put(FACTS_KEY, {
@@ -3798,15 +3832,24 @@ export class ResidentDO extends Sandbox<Env> {
     });
   }
 
-  /** Idle = no live binding attached within IDLE_AFTER_S and nothing in
-   *  flight. What a live tree holds is not asked (item 17): a dirty tree no
-   *  run is using protects nothing — the next attach wipes it — so it is
-   *  never a reason to keep the container awake; the sweep's release records
-   *  what it held. Bindings are storage, so this needs no container. */
-  private async isIdle(): Promise<boolean> {
-    const live = await this.liveBindings();
+  /** Whether a run may be using this disk: a live binding attached to or
+   *  used (an exec bumps `lastAttachAt` too, item 21) within IDLE_AFTER_S.
+   *  The op counter is 0 between a run's tool calls, so this floor is what
+   *  stands for a run mid-flight. The one predicate behind "the disk may go
+   *  away": the idle-sleep gate (item 16b — a platform sleep destroys the
+   *  disk) and the disk-full recycle (item 54) both read it, and neither asks
+   *  what a tree holds (item 17): a dirty tree no run is using protects
+   *  nothing — the next attach wipes it. Bindings are storage, so this needs
+   *  no container. */
+  private recentlyUsed(live: ThreadBinding[]): boolean {
     const recent = systemClock() - IDLE_AFTER_S * 1000;
-    if (live.some((b) => Date.parse(b.lastAttachAt) >= recent)) return false;
+    return live.some((b) => Date.parse(b.lastAttachAt) >= recent);
+  }
+
+  /** Idle = no live binding used within the floor and nothing in flight; the
+   *  sweep's release records what an idle tree held. */
+  private async isIdle(): Promise<boolean> {
+    if (this.recentlyUsed(await this.liveBindings())) return false;
     return this.inFlightCount() === 0;
   }
 
@@ -3816,17 +3859,6 @@ export class ResidentDO extends Sandbox<Env> {
     return [...all.values()].filter((b) => !b.evicted && b.user);
   }
 
-  /** The disk-full recycle's tree guard (item 54), its one reader: true when
-   *  every live tree is clean as its thread user, or the runtime is already
-   *  down — a sleep has destroyed the disk, so there is nothing left to lose. */
-  private async liveTreesClean(live: ThreadBinding[]): Promise<boolean> {
-    if (!(await this.isRuntimeActive().catch(() => false))) return true;
-    // Concurrent: each check touches only its own (disjoint) tree, and one
-    // spawn each — no serial 3-probe round-trip per live binding.
-    const checks = await Promise.all(live.map((b) => this.worktreeCleanliness(b)));
-    return checks.every((c) => c.clean); // any dirty or unknown → not clean
-  }
-
   // -- disk-full (docs/reference/specs/resident-repos.md item 54) ---------------------------
 
   /** Free space on the workspace mount in KiB; `null` when df cannot answer.
@@ -3852,28 +3884,54 @@ export class ResidentDO extends Sandbox<Env> {
 
   /** The disk is a cache: stop the container so the next cycle attempt
    *  restores mirror + checkout from R2 onto an empty disk — the same wake
-   *  path as a platform sleep. Only when the pure plan allows it: nothing in
-   *  flight (`selfInFlight` excludes the calling refresh cycle from the
-   *  count), every live tree clean, and no recycle within the cooldown. A
-   *  refused recycle is written to `lastRefreshError` with its why, so
-   *  `/residents` says what an operator must do; the `degraded` reason stays
-   *  the clean `disk-full: …`. Answers whether the container was recycled. */
+   *  path as a platform sleep. Only when the pure plan allows it: no recycle
+   *  within the cooldown, nothing in flight (`selfInFlight` excludes the
+   *  calling refresh cycle from the count) and no live binding used within
+   *  the idle floor — the idle-sleep gate's own predicate (`recentlyUsed`),
+   *  because a sleep and a recycle destroy the same disk: it may go away when
+   *  no run is using it, never for what the trees hold (item 17). A recycle
+   *  discards every live tree the way an eviction does, so each is measured
+   *  first, as its thread user, and its binding records what went
+   *  (`recordRecycledTree`); the plan is decided again after those awaits,
+   *  right before the stop. A refused recycle is written to
+   *  `lastRefreshError` with its why, so `/residents` says what an operator
+   *  must do; the `degraded` reason stays the clean `disk-full: …`. Answers
+   *  whether the container was recycled. */
   private async recoverFromDiskFull(reason: string, selfInFlight: number): Promise<boolean> {
     const lastRecycleAt = await this.ctx.storage.get<number>(DISK_FULL_RECYCLE_KEY);
-    const plan = planDiskFullRecovery({
-      now: systemClock(),
-      lastRecycleAt,
-      inFlight: this.inFlightCount() - selfInFlight,
-      treesClean: await this.liveTreesClean(await this.liveBindings()),
-    });
-    if (plan.action === "wait") {
-      console.log(`disk-full: container kept — ${plan.why}`);
-      await this.recordRefreshError(`${reason} — container kept: ${plan.why}`);
+    const plan = (live: ThreadBinding[]) =>
+      planDiskFullRecovery({
+        now: systemClock(),
+        lastRecycleAt,
+        inFlight: this.inFlightCount() - selfInFlight,
+        recentlyUsed: this.recentlyUsed(live),
+        idleFloorS: IDLE_AFTER_S,
+      });
+    const kept = async (why: string) => {
+      console.log(`disk-full: container kept — ${why}`);
+      await this.recordRefreshError(`${reason} — container kept: ${why}`);
       return false;
-    }
+    };
+    const live = await this.liveBindings();
+    const first = plan(live);
+    if (first.action === "wait") return kept(first.why);
+    // What each live tree holds, for its record — never a reason to keep the
+    // container. Concurrent: each probe touches only its own tree, one spawn
+    // each. Runtime down: the disk, and every tree with it, is already gone.
+    const active = await this.isRuntimeActive().catch(() => false);
+    const trees = active
+      ? await Promise.all(
+          live.map(async (binding) => [binding, await this.measureTreeBeforeEviction(binding)] as const),
+        )
+      : live.map((binding) => [binding, undefined] as const);
+    // The measurement awaited (the DO yields at each await): decide again over
+    // fresh facts — an attach or an op that landed meanwhile keeps the container.
+    const verdict = plan(await this.liveBindings());
+    if (verdict.action === "wait") return kept(verdict.why);
     console.log(
       `disk-full: recycling the container — the next cycle restores mirror + checkout from R2 onto an empty disk (${reason})`,
     );
+    for (const [binding, tree] of trees) await this.recordRecycledTree(binding, tree);
     await this.ctx.storage.put(DISK_FULL_RECYCLE_KEY, systemClock());
     await this.recordRefreshError(`${reason} — container recycled; restoring from R2 on the next cycle`);
     this.swapIncarnation(); // deliberate incarnation swap
@@ -3881,6 +3939,27 @@ export class ResidentDO extends Sandbox<Env> {
     return true;
   }
 
+  /** The disk-full recycle's record for one live tree (item 54), written the
+   *  way `evictBinding` writes an eviction's — but the binding stays live, its
+   *  pool user kept and its tree recreated on the next attach, so this is not
+   *  an eviction and the record sits under its own name beside
+   *  `evictedLeftBehind`: the counts when something was there, the probe's
+   *  first error line when git could not read the tree, both rewritten on
+   *  every recycle so nothing lingers from an earlier one, and one log line
+   *  when the tree held something. Re-read first: a binding evicted or
+   *  re-attached during the measurement is left as is. */
+  private async recordRecycledTree(binding: ThreadBinding, tree: EvictedTree | undefined): Promise<void> {
+    const now = await this.ctx.storage.get<ThreadBinding>(threadBindingKey(binding.threadKey));
+    if (!now || now.evicted || now.lastAttachAt !== binding.lastAttachAt) return;
+    await this.ctx.storage.put(threadBindingKey(binding.threadKey), {
+      ...now,
+      recycledLeftBehind: tree && "leftBehind" in tree ? tree.leftBehind : undefined,
+      recycledUnmeasured: tree && "unmeasured" in tree ? tree.unmeasured : undefined,
+    } satisfies ThreadBinding);
+    if (tree)
+      console.log(`disk-full: ${binding.threadKey} tree discarded with the disk — ${evictedTreeSentence(tree)}`);
+  }
+
   // -- disk budget (docs/reference/specs/resident-repos.md item 55) -------------------------
 
   /** The `df` half: total/used/free of the workspace mount; null when df
@@ -4012,12 +4091,36 @@ export class ResidentDO extends Sandbox<Env> {
         committedKiB: this.diskCommittedKiB,
         diskBudgetMb: input.record.diskBudgetMb,
         kind,
+        // A deps-store entry backup stages its archive from the deps (item
+        // 61); the reserve holds their share only while one runs.
+        depsBackupInFlight: this.depsBackupsInFlight.size > 0,
       });
     let rawFree = df.freeKiB;
     let verdict = decide(rawFree);
     const evicted: Array<{ threadKey: string; freedKiB: number | null }> = [];
     // Item 62: keep decisions travel as tokens; the key stays for the log line.
     const kept: Array<{ threadKey: string; why: DiskKeepWhy }> = [];
+    // The deps store's spares go first (item 55): a warm cache no live tree
+    // references, worth minutes on a future attach, against a tree refused
+    // now. Their bytes come back before any idle tree is considered.
+    let spares: Array<{ key: string; freedKiB: number }> = [];
+    if (!verdict.fits) {
+      spares = await this.evictDepsSparesUnderPressure().catch((err) => {
+        console.log(`disk-pressure: deps spare eviction failed: ${errMsg(err)}`);
+        return [];
+      });
+      if (spares.length > 0) {
+        console.log(
+          `disk-pressure: evicted ${spares.length} deps-store spare(s) (${formatGiB(spares.reduce((a, e) => a + e.freedKiB, 0))} back) to make room for ${input.threadKey}`,
+        );
+        rawFree = rawFreeAfterEviction(
+          rawFree,
+          await this.dfSample(),
+          spares.reduce((a, e) => a + e.freedKiB, 0),
+        );
+        verdict = decide(rawFree);
+      }
+    }
     if (!verdict.fits) {
       const live = await this.liveBindings();
       const candidates: DiskEvictionCandidate[] = live.map((b) => ({
@@ -4064,7 +4167,7 @@ export class ResidentDO extends Sandbox<Env> {
     // truthiness does not narrow a boolean-literal discriminant.
     const final = verdict;
     if (final.fits === false) {
-      const reason = diskPressureReason({ verdict: final, evicted, kept });
+      const reason = diskPressureReason({ verdict: final, evicted, kept, spares });
       console.log(`attach ${input.threadKey}: ${reason}`);
       const s = await this.getStatus();
       return { error: reason, status: 503, state: s.state, reason: DISK_PRESSURE_REASON };
@@ -4072,7 +4175,7 @@ export class ResidentDO extends Sandbox<Env> {
     const m = final.math;
     console.log(
       `attach ${input.threadKey}: disk admitted — ${kind} ${formatGiB(m.projectedKiB)} projected, ${formatGiB(m.freeKiB)} free, ` +
-        `reserve ${formatGiB(m.reserve.totalKiB)}, headroom ${formatGiB(m.headroomKiB)}${evicted.length > 0 ? `, evicted ${evicted.map((e) => e.threadKey).join(", ")}` : ""}`,
+        `reserve ${formatGiB(m.reserve.totalKiB)}, headroom ${formatGiB(m.headroomKiB)}${spares.length > 0 ? `, evicted ${spares.length} deps spare(s)` : ""}${evicted.length > 0 ? `, evicted ${evicted.map((e) => e.threadKey).join(", ")}` : ""}`,
     );
     const committedKiB = m.projectedKiB ?? 0;
     this.diskCommittedKiB += committedKiB;
@@ -4406,12 +4509,13 @@ export class ResidentDO extends Sandbox<Env> {
       lastAttachAt: now,
       evicted: false,
       // An evicted binding's own history: how its ref was chosen (absent on
-      // one made before the field — never overwritten by this attach's flag)
-      // and the one move it may have made.
+      // one made before the field — never overwritten by this attach's flag),
+      // the one move it may have made and its last move back.
       ...(existing
         ? {
             ...(existing.boundBy !== undefined ? { boundBy: existing.boundBy } : {}),
             ...(existing.rebound !== undefined ? { rebound: existing.rebound } : {}),
+            ...(existing.returned !== undefined ? { returned: existing.returned } : {}),
             ...(existing.ownBranches !== undefined ? { ownBranches: existing.ownBranches } : {}),
           }
         : { boundBy }),
@@ -4764,27 +4868,27 @@ export class ResidentDO extends Sandbox<Env> {
 
   /** Item 16's second movement, decided where the fact is established — under
    *  the mirror mutex, after the attach's fetch found the bound ref gone: a
-   *  binding a rebind moved onto its own pull request's branch, that branch
-   *  now deleted (its pull request merged), goes back to the default it was
-   *  bound to, so the run starts clean there (item 17) instead of the thread
-   *  failing `unknown-ref` for the rest of its life. The row as it stands is
-   *  re-read and re-judged (`canReturnToDefault`: a ref a person named never
-   *  returns — that branch is theirs to sort out), the move stamped returned
-   *  so the thread may follow its next pull request, and the answer carries
-   *  the move back for the card. A row that no longer qualifies — another
-   *  attach moved it meanwhile — is answered as it stands, nothing written. */
+   *  binding on a branch that is now deleted (its pull request merged) goes
+   *  back to the default, so the run starts clean there (item 17) instead of
+   *  the thread failing `unknown-ref` for the rest of its life — when the
+   *  branch is one a rebind moved it onto, or one this thread's own runs
+   *  pushed as the binding remembers it (`ownBranches`): a ship unit's coding
+   *  child binds its unit branch by name and pushes it, and the merge deletes
+   *  it. The row as it stands is re-read and re-judged (the pure
+   *  `returnToDefault`, which writes nothing for a row `canReturnToDefault`
+   *  does not admit: a ref a person named that the thread never pushed never
+   *  returns — that branch is theirs to sort out), the move recorded so the
+   *  thread may follow its next pull request, and the answer carries the move
+   *  back for the card. A row that no longer qualifies — another attach moved
+   *  it meanwhile — is answered as it stands, nothing written. */
   private async returnBindingToDefault(
     binding: ThreadBinding,
     defaultRef: string,
   ): Promise<{ binding: ThreadBinding; returned?: Returned }> {
     const key = threadBindingKey(binding.threadKey);
     const current = (await this.ctx.storage.get<ThreadBinding>(key)) ?? binding;
-    if (current.rebound === undefined || !canReturnToDefault(current, defaultRef)) return { binding: current };
-    const back = returnToDefault(
-      { ...current, rebound: current.rebound },
-      defaultRef,
-      new Date(systemClock()).toISOString(),
-    );
+    const back = returnToDefault(current, defaultRef, new Date(systemClock()).toISOString());
+    if (back === undefined) return { binding: current };
     await this.ctx.storage.put(key, back.binding);
     console.log(
       `attach ${binding.threadKey}: ${back.returned.from} is gone from the mirror (the thread's own pull request #${back.returned.pr}) — returned to ${back.returned.to}; the tree is provisioned there`,
@@ -4866,9 +4970,22 @@ export class ResidentDO extends Sandbox<Env> {
     // The expected head applies to the ref it was resolved for; a sticky
     // binding on another branch drops it (item 51) rather than fetching on
     // every attach of a thread that can never be at that commit.
+    // A ref the binding could return from — a branch a rebind moved it onto,
+    // or one its own runs pushed (item 16's second movement) — is fetched for
+    // whether or not the mirror holds it: the branch dies when its pull
+    // request merges, the deletion reaches the mirror only through a
+    // `fetch --prune`, and a mirror trusted for still holding the ref would
+    // provision a tree at the deleted branch's stale tip until the refresh
+    // cycle's prune caught up. One predicate, read once here, drives the mint
+    // pre-check, the fetch under the lock and the return gate alike.
     let want = wantShaForBinding({ boundRef: binding.ref, refHint, wantSha });
+    const returnable = canReturnToDefault(binding, facts.defaultRef);
     let fetchToken: string | null = token;
-    if (!fetchToken && githubAppConfigured(this.env) && (await this.mirrorNeedsFetchFor(binding.ref, want))) {
+    if (
+      !fetchToken &&
+      githubAppConfigured(this.env) &&
+      (await this.mirrorFetchReasonFor(binding.ref, want, returnable)) !== null
+    ) {
       fetchToken = (await mintRepoScopedToken(this.env, slug).catch(() => null))?.token ?? null;
     }
 
@@ -4876,14 +4993,27 @@ export class ResidentDO extends Sandbox<Env> {
     try {
       locked = await this.withMirrorLock(async () => {
         await this.ensureGitSetup();
-        const fetched = await this.mirrorNeedsFetchFor(binding.ref, want);
-        if (fetched) {
-          await this.gitWithCred(
-            fetchToken,
-            ["-C", MIRROR_DIR, "fetch", "--prune", "origin"],
-            "fetch",
-            GIT_NETWORK_TIMEOUT_MS,
-          );
+        const why = await this.mirrorFetchReasonFor(binding.ref, want, returnable);
+        if (why !== null) {
+          try {
+            await this.gitWithCred(
+              fetchToken,
+              ["-C", MIRROR_DIR, "fetch", "--prune", "origin"],
+              "fetch",
+              GIT_NETWORK_TIMEOUT_MS,
+            );
+          } catch (err) {
+            // A fetch for a missing or stale ref fails the attach as it always
+            // did. One that only verifies a returnable ref the mirror holds is
+            // not the attach's failure — the origin unreachable, no token for
+            // a private repo — so the attach goes on with the mirror's ref, as
+            // it did before the verification existed; the return is only
+            // ever decided on a fetch that ran.
+            if (why !== "returnable-ref") throw err;
+            console.log(
+              `attach ${threadKey}: the fetch verifying ${binding.ref} at the origin failed (${errMsg(err)}) — the attach goes on with the mirror's ref`,
+            );
+          }
         }
         // What to check out, now that the mirror is as fresh as it will get
         // (item 51, the pure `attachTarget`): the ref's tip when the ref is
@@ -4892,18 +5022,21 @@ export class ResidentDO extends Sandbox<Env> {
         // `refs/pull/N/head` still names its head, and the caller told us that
         // head — so a review of a merged PR stays on the warm resident instead
         // of falling back to a cold sandbox that clones the same commit itself.
-        // No fetch ran ⇒ the ref existed at the check: `mirrorNeedsFetch` fetches
-        // for every missing ref, so only a fetched mirror needs the re-read.
-        // (Under the mirror mutex — the mirror cannot change in between.)
-        const refExists = !fetched || (await this.refExists(binding.ref));
+        // No fetch was due ⇒ the ref existed at the check: `mirrorFetchReason`
+        // fetches for every missing ref, so only a fetched mirror needs the
+        // re-read — and a returnable ref is re-read for real, the fact the
+        // second movement is decided on. (Under the mirror mutex — the mirror
+        // cannot change in between.)
+        const refExists = why === null || (await this.refExists(binding.ref));
         let target = attachTarget({
           refExists,
           wantSha: want,
           commitInMirror: !refExists && want !== null && (await this.commitInMirror(want)),
         });
-        if (target.kind === "unknown-ref" && canReturnToDefault(binding, facts.defaultRef)) {
-          // The branch a rebind moved this thread onto is gone even after the
-          // fetch — deleted once its pull request merged. The binding goes
+        if (target.kind === "unknown-ref" && returnable) {
+          // The thread's branch — one a rebind moved it onto, or one its own
+          // runs pushed and it was bound to by name — is gone even after the
+          // fetch: deleted once its pull request merged. The binding goes
           // back to the default (item 16's second movement) and the attach
           // goes on there: the default is always in the mirror, and the
           // worktree step below provisions the tree at its tip.
@@ -5658,27 +5791,24 @@ export class ResidentDO extends Sandbox<Env> {
    *  in flight, and remove what `planDepsEviction` names — debris first, then
    *  the coldest spares beyond DEPS_STORE_MAX_UNREFERENCED. Housekeeping:
    *  a failure is a log line, never a lifecycle flip. */
-  private async sweepDepsStore(): Promise<void> {
-    const listed = await this.run(["sh", "-c", depsStoreListScript()], { timeoutMs: DU_TIMEOUT_MS });
-    if (listed.exitCode !== 0) return;
-    const listing = parseDepsStoreListing(listed.stdout);
-    if (listing.entries.length === 0 && listing.leftovers.length === 0) return;
+  /** The store entries no eviction may touch: the checkout's key, every live
+   *  binding's, every install and every entry backup in flight. */
+  private async depsProtectedKeys(): Promise<Set<string>> {
     const facts = await this.ctx.storage.get<RepoFacts>(FACTS_KEY);
     const protectedKeys = new Set<string>([...this.depsInFlight.keys(), ...this.depsBackupsInFlight]);
     if (facts?.lockfileHash) protectedKeys.add(facts.lockfileHash);
     for (const b of await this.liveBindings()) if (b.depsKey) protectedKeys.add(b.depsKey);
-    // A scratch/staging dir of an install still running in this incarnation
-    // is live work, not debris; the listing cannot tell them apart, so
-    // leftovers wait for a sweep with nothing in flight.
-    const leftovers = this.depsInFlight.size > 0 ? [] : listing.leftovers;
-    const plan = planDepsEviction({ entries: listing.entries, leftovers, protectedKeys });
-    if (plan.remove.length === 0) return;
+    return protectedKeys;
+  }
+
+  /** Remove the store entries a plan names and drop their entry backups with
+   *  them (item 61 PR B: a spare nothing references on disk is a spare nothing
+   *  will wake into). Shared by the sweep and the attach's pressure path. */
+  private async applyDepsEviction(plan: DepsEvictionPlan, listing: DepsStoreListing, who: string): Promise<void> {
     await this.runOk(["rm", "-rf", ...plan.remove], "deps-evict", { timeoutMs: DU_TIMEOUT_MS });
     console.log(
-      `deps: evicted ${plan.remove.length} path(s) — ${plan.remove.map((p) => p.slice(DEPS_STORE_DIR.length + 1, DEPS_STORE_DIR.length + 9)).join(", ")}; kept ${plan.keep.map((k) => k.slice(0, 8)).join(", ")}`,
+      `deps: ${who} evicted ${plan.remove.length} path(s) — ${plan.remove.map((p) => p.slice(DEPS_STORE_DIR.length + 1, DEPS_STORE_DIR.length + 9)).join(", ")}; kept ${plan.keep.map((k) => k.slice(0, 8)).join(", ")}`,
     );
-    // The evicted entries' archives go with them (item 61 PR B): a spare
-    // nothing references on disk is a spare nothing will wake into.
     const kept = new Set(plan.keep);
     const evictedKeys = listing.entries.map((e) => e.key).filter((k) => !kept.has(k));
     const drop = depsBackupsToDrop({
@@ -5693,6 +5823,44 @@ export class ResidentDO extends Sandbox<Env> {
     }
   }
 
+  /** Under disk pressure (item 55) the store keeps no spare: every complete
+   *  entry no live tree references goes, coldest first, before any idle tree
+   *  is considered — a spare is a cache worth minutes on a future attach, a
+   *  refused tree is a run falling to a cold sandbox now. Leftovers are the
+   *  sweep's business (they may be live installs' scratch). Answers what it
+   *  removed with the bytes each measured at; a listing that fails answers
+   *  nothing and the tree path decides as before. */
+  private async evictDepsSparesUnderPressure(): Promise<Array<{ key: string; freedKiB: number }>> {
+    const listed = await this.run(["sh", "-c", depsStoreListScript()], { timeoutMs: DU_TIMEOUT_MS });
+    if (listed.exitCode !== 0) return [];
+    const listing = parseDepsStoreListing(listed.stdout);
+    if (listing.entries.length === 0) return [];
+    const plan = planDepsEviction({
+      entries: listing.entries,
+      leftovers: [],
+      protectedKeys: await this.depsProtectedKeys(),
+      maxUnreferenced: DEPS_STORE_MAX_UNREFERENCED_UNDER_PRESSURE,
+    });
+    if (plan.remove.length === 0) return [];
+    await this.applyDepsEviction(plan, listing, "disk-pressure");
+    return plan.evicted.map((e) => ({ key: e.key, freedKiB: e.kib }));
+  }
+
+  private async sweepDepsStore(): Promise<void> {
+    const listed = await this.run(["sh", "-c", depsStoreListScript()], { timeoutMs: DU_TIMEOUT_MS });
+    if (listed.exitCode !== 0) return;
+    const listing = parseDepsStoreListing(listed.stdout);
+    if (listing.entries.length === 0 && listing.leftovers.length === 0) return;
+    const protectedKeys = await this.depsProtectedKeys();
+    // A scratch/staging dir of an install still running in this incarnation
+    // is live work, not debris; the listing cannot tell them apart, so
+    // leftovers wait for a sweep with nothing in flight.
+    const leftovers = this.depsInFlight.size > 0 ? [] : listing.leftovers;
+    const plan = planDepsEviction({ entries: listing.entries, leftovers, protectedKeys });
+    if (plan.remove.length === 0) return;
+    await this.applyDepsEviction(plan, listing, "sweep");
+  }
+
   /** The per-user 700 staging dir (`install -d` is idempotent), memoized per
    *  incarnation — the write/credential paths used to fork for it on every
    *  call. Cleared with the other memos; a fresh disk simply re-creates it. */
@@ -6202,11 +6370,10 @@ export class ResidentDO extends Sandbox<Env> {
    *  (su), never as root: the worktree is thread-owned, so root git in it
    *  would be refused by safe.directory and would be the exact repo-local-
    *  config execution vector safe.directory exists to block. Read by
-   *  `measureTreeBeforeEviction` for the eviction's record — never a reason
-   *  to keep a tree (item 17) — and by the disk-full recycle's guard (item
-   *  54), where unknown (git failed) counts as NOT clean. A tree that no
-   *  longer exists (disk recycled by a sleep/wake) is clean with nothing
-   *  measured: there was nothing to discard.
+   *  `measureTreeBeforeEviction` alone, for the record of an eviction or of
+   *  the disk-full recycle — never a reason to keep a tree or a container
+   *  (item 17). A tree that no longer exists (disk recycled by a sleep/wake)
+   *  is clean with nothing measured: there was nothing to discard.
    *
    *  ONE spawn: the presence test and both git probes fold
    *  into the pure `worktreeCleanlinessScript` (test -d as root, both git
@@ -6222,7 +6389,8 @@ export class ResidentDO extends Sandbox<Env> {
     return parseWorktreeCleanliness(r);
   }
 
-  /** What a tree holds right before its eviction, for the record and the log
+  /** What a tree holds right before its eviction — or before the disk-full
+   *  recycle discards it with the disk (item 54) — for the record and the log
    *  (item 17): the one-spawn probe as the thread user, read once into
    *  `evictedTreeOf` — never into a keep decision. Callers skip it when the
    *  runtime is down: the disk, and the tree with it, is already gone. */
@@ -6782,6 +6950,8 @@ export class ResidentDO extends Sandbox<Env> {
           evictedWhy,
           evictedLeftBehind,
           evictedUnmeasured,
+          recycledLeftBehind,
+          recycledUnmeasured,
         }) => ({
           threadKey,
           ref,
@@ -6795,6 +6965,8 @@ export class ResidentDO extends Sandbox<Env> {
           evictedWhy: evictedWhy ?? null,
           evictedLeftBehind: evictedLeftBehind ?? null,
           evictedUnmeasured: evictedUnmeasured ?? null,
+          recycledLeftBehind: recycledLeftBehind ?? null,
+          recycledUnmeasured: recycledUnmeasured ?? null,
         }),
       );
     return {