@coreplane/switchboard 1.234.0 → 1.236.0

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

@@ -116,10 +116,13 @@ import {
   type ThreadDepsMechanism,
 } from "../../src/execution/residentDepCache.js";
 import {
-  leftBehindOf,
+  evictedTreeOf,
+  evictedTreeSentence,
   parseWorktreeCleanliness,
   worktreeCleanlinessScript,
+  type EvictedTree,
   type LeftBehind,
+  type WorktreeCleanliness,
 } from "../../src/execution/residentCleanliness.js";
 import {
   base64LengthOf,
@@ -502,16 +505,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
@@ -1023,8 +1028,26 @@ interface ThreadBinding {
   evicted?: boolean;
   evictedAt?: string;
   /** Why the last eviction happened (the audit trail): `ttl`, `clean-idle`,
-   *  `detach`, or a reclamation fate — `merged #N` / `closed #N` / `gone`. */
+   *  `detach`, `disk-pressure`, or a reclamation fate — `merged #N` /
+   *  `closed #N` / `gone`. */
   evictedWhy?: string;
+  /** What the tree held when that eviction removed it (item 17: never a
+   *  reason to keep the tree, never discarded silently): the tracked changes
+   *  and unpushed commits measured as the thread user. Absent when the tree
+   *  was clean, already gone with the disk, or not measured (a force detach). */
+  evictedLeftBehind?: LeftBehind;
+  /** 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
@@ -2933,12 +2956,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 →
@@ -2990,7 +3012,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, {
@@ -3786,15 +3808,25 @@ export class ResidentDO extends Sandbox<Env> {
     });
   }
 
-  /** Idle = no live binding attached within IDLE_AFTER_S AND (when the
-   *  runtime is up) no live tree is dirty. Bindings are storage; dirtiness
-   *  needs the container — if it is already asleep there is nothing to lose. */
-  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;
-    if (this.inFlightCount() > 0) return false;
-    return this.liveTreesClean(live);
+    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;
   }
 
   /** Bindings that hold a pool user and a tree on disk (not evicted). */
@@ -3803,18 +3835,6 @@ export class ResidentDO extends Sandbox<Env> {
     return [...all.values()].filter((b) => !b.evicted && b.user);
   }
 
-  /** True when no live tree holds work a lost disk would destroy: every one
-   *  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 — the idle gate does not pay a 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.
@@ -3840,28 +3860,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
@@ -3869,6 +3915,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
@@ -3948,10 +4015,11 @@ export class ResidentDO extends Sandbox<Env> {
    *  already on disk is `reuse` (0 — a dirty/stale recreate frees the old one
    *  first). A ref not yet in the mirror (fetched under the lock, moments later)
    *  is projected as `hardlink`, the common case. When it does not fit, the
-   *  coldest clean idle trees go first (`orderEvictionCandidates`: never the
+   *  coldest idle trees go first (`orderEvictionCandidates`: never the
    *  requesting thread, a busy tree, the default branch, or one attached within
-   *  DISK_EVICT_MIN_IDLE_MS; cleanliness checked as the thread user, dirty or
-   *  unreadable kept — the sweep's rules), `df` re-probed after each; still
+   *  DISK_EVICT_MIN_IDLE_MS), whatever they hold — item 17: dirt never keeps a
+   *  tree; each is measured as its thread user for the eviction's record —
+   *  `df` re-probed after each; still
    *  short → `503 {reason:"disk-pressure"}` with the whole math in `error`, the
    *  same shape as `mirror-busy`, so the bot falls back cold legibly. Never a
    *  lifecycle flip: the checkout is intact and every existing tree keeps
@@ -4021,12 +4089,10 @@ export class ResidentDO extends Sandbox<Env> {
         if (verdict.fits) break;
         const binding = live.find((b) => b.threadKey === c.threadKey);
         if (!binding) continue;
-        const clean = await this.worktreeCleanliness(binding);
-        if (!clean.clean) {
-          kept.push({ threadKey: c.threadKey, why: "dirty" });
-          continue;
-        }
-        // Same re-read guards as the sweep: the clean check awaited.
+        // What the tree holds goes on the eviction's record (item 17), never
+        // into a keep; the runtime is up — this attach is running on it.
+        const tree = await this.measureTreeBeforeEviction(binding);
+        // Same re-read guards as the sweep: the measurement awaited.
         const current = await this.ctx.storage.get<ThreadBinding>(threadBindingKey(c.threadKey));
         if (
           !current ||
@@ -4037,7 +4103,7 @@ export class ResidentDO extends Sandbox<Env> {
           kept.push({ threadKey: c.threadKey, why: "busy" });
           continue;
         }
-        if (!(await this.evictBinding(current, true, "disk-pressure", DISK_PRESSURE_REASON))) {
+        if (!(await this.evictBinding(current, true, "disk-pressure", DISK_PRESSURE_REASON, tree))) {
           kept.push({ threadKey: c.threadKey, why: "other" });
           continue;
         }
@@ -6022,13 +6088,21 @@ export class ResidentDO extends Sandbox<Env> {
 
   /** Remove a thread's worktree (when the runtime is up — a slept container
    *  already lost it) and release its pool user; the binding is KEPT, marked
-   *  evicted, so the ref stays sticky and the next attach recreates the tree
-   *  with it. Shared by the inactivity sweep and /detach. */
+   *  evicted with the cause (`evictedWhy`) and with what the tree held
+   *  (`evictedLeftBehind`, or `evictedUnmeasured` when git could not read it
+   *  — item 17: never a reason to keep the tree, never discarded silently), so
+   *  the ref stays sticky and the next attach recreates the tree with it.
+   *  Shared by the inactivity sweep, the reclamation pass, the disk-pressure
+   *  path and /detach. */
   private async evictBinding(
     binding: ThreadBinding,
     runtimeActive: boolean,
     logCtx: string,
     why: string,
+    /** What the caller measured in the tree first (`measureTreeBeforeEviction`,
+     *  as the thread user with the runtime up); absent when the tree was clean,
+     *  already gone with the disk, or not measured (a force detach). */
+    tree?: EvictedTree,
   ): Promise<boolean> {
     const threadDir = parentDir(binding.worktreePath);
     if (runtimeActive && threadDir.startsWith(`${THREADS_DIR}/`)) {
@@ -6064,7 +6138,10 @@ export class ResidentDO extends Sandbox<Env> {
       evicted: true,
       evictedAt: new Date(systemClock()).toISOString(),
       evictedWhy: why,
+      evictedLeftBehind: tree && "leftBehind" in tree ? tree.leftBehind : undefined,
+      evictedUnmeasured: tree && "unmeasured" in tree ? tree.unmeasured : undefined,
     } satisfies ThreadBinding);
+    if (tree) console.log(`${logCtx}: ${binding.threadKey} evicted (${why}) — ${evictedTreeSentence(tree)}`);
     return true;
   }
 
@@ -6105,17 +6182,13 @@ export class ResidentDO extends Sandbox<Env> {
       if (left > 0) return { released: false, reason: busyAfterKillReason(left), user: binding.user };
     }
     const active = await this.isRuntimeActive().catch(() => false);
-    // What the tree still holds, for the answer — never a reason to keep it.
-    // Not measured on a force release: a read-only tree holds nothing, and a
-    // hard stop's tree is whatever the killed command left. A probe that
-    // fails names nothing (never a guess) and is a log line.
-    let leftBehind: LeftBehind | undefined;
-    if (!force && active) {
-      const measured = await this.worktreeCleanliness(binding);
-      leftBehind = leftBehindOf(measured);
-      if (!measured.clean && leftBehind === undefined)
-        console.log(`detach: ${threadKey}: the tree could not be measured before its release (${measured.reason})`);
-    }
+    // What the tree still holds, for the answer and the eviction's record —
+    // never a reason to keep it. Not measured on a force release: a read-only
+    // tree holds nothing, and a hard stop's tree is whatever the killed
+    // command left. A probe that fails names nothing in the answer (never a
+    // guess); the record and the log say it could not be measured.
+    let tree: EvictedTree | undefined;
+    if (!force && active) tree = await this.measureTreeBeforeEviction(binding);
     // Re-check right before removal: the measurement above awaited (the DO
     // yields at each await), so an exec that arrived mid-detach would otherwise
     // have its tree removed under it.
@@ -6136,16 +6209,12 @@ export class ResidentDO extends Sandbox<Env> {
     // Same as the sweep: `active` was read before the measurement's awaits; a
     // container that woke meanwhile must get the rm, not an orphaned tree.
     const activeNow = await this.isRuntimeActive().catch(() => false);
-    if (!(await this.evictBinding(current, activeNow, `detach`, "detach"))) {
+    if (!(await this.evictBinding(current, activeNow, `detach`, "detach", tree))) {
       return { released: false, reason: "re-attached during eviction — kept", user };
     }
-    if (leftBehind) {
-      console.log(
-        `detach: ${threadKey} released — left behind ${leftBehind.uncommittedChanges} uncommitted change(s) and ${leftBehind.unpushedCommits} unpushed commit(s), discarded with the tree`,
-      );
-    }
     // Item 55: the tree is gone; the gauge catches up at the next refresh
     // instance's `measure` step, and the admission's `df` sees the space now.
+    const leftBehind = tree && "leftBehind" in tree ? tree.leftBehind : undefined;
     return { released: true, user, ...(leftBehind !== undefined ? { leftBehind } : {}) };
   }
 
@@ -6183,20 +6252,21 @@ export class ResidentDO extends Sandbox<Env> {
     }
   }
 
-  /** Is this thread's tree safe to destroy? The git probes run AS THE THREAD
-   *  USER (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. Unknown (git
-   *  failed) counts as NOT clean — never destroy work on a guess. A tree
-   *  that no longer exists (disk recycled by a sleep/wake) has nothing to
-   *  preserve: releasable, so a post-wake binding does not hold a pool user
-   *  for 7 days on behalf of files that are already gone.
+  /** What this thread's tree holds: the tracked changes and unpushed commits,
+   *  or that git could not read it. The git probes run AS THE THREAD USER
+   *  (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` 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
    *  commands inside a single privilege-dropped `su`, tagged lines out);
    *  `parseWorktreeCleanliness` encodes the exact decision table above. */
-  private async worktreeCleanliness(binding: ThreadBinding): Promise<{ clean: boolean; reason?: string }> {
+  private async worktreeCleanliness(binding: ThreadBinding): Promise<WorktreeCleanliness> {
     const injected = { GIT_TERMINAL_PROMPT: "0" }; // same injection as threadRun — fail fast, never prompt
     validateEnvNames(injected);
     const r = await this.run(["sh", "-c", worktreeCleanlinessScript(binding.worktreePath, binding.user)], {
@@ -6206,6 +6276,15 @@ export class ResidentDO extends Sandbox<Env> {
     return parseWorktreeCleanliness(r);
   }
 
+  /** 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. */
+  private async measureTreeBeforeEviction(binding: ThreadBinding): Promise<EvictedTree | undefined> {
+    return evictedTreeOf(await this.worktreeCleanliness(binding));
+  }
+
   /** Anything that must not be interrupted by a container stop or counted
    *  as idle: thread exec/read/write, disposable /op runs, and attaches past
    *  their own image check (mid clone/install under the mirror lock). */
@@ -6278,8 +6357,17 @@ export class ResidentDO extends Sandbox<Env> {
       // attach), and an eviction decided on a stale "inactive" would skip the
       // rm and orphan a real tree.
       const activeNow = await this.isRuntimeActive().catch(() => false);
+      // What the tree holds goes on the eviction's record (item 17), measured
+      // while the runtime is up; a slept container has no tree to measure.
+      const tree = activeNow ? await this.measureTreeBeforeEviction(current) : undefined;
       if (
-        await this.evictBinding(current, activeNow, `worktree-sweep ${resource}`, last >= cutoff ? "clean-idle" : "ttl")
+        await this.evictBinding(
+          current,
+          activeNow,
+          `worktree-sweep ${resource}`,
+          last >= cutoff ? "clean-idle" : "ttl",
+          tree,
+        )
       )
         evicted.push(binding.threadKey);
       else kept++;
@@ -6537,9 +6625,11 @@ export class ResidentDO extends Sandbox<Env> {
    *  mirror (the refresh cycle's `fetch --prune` just ran) or its PR was
    *  merged/closed. Runs inside the refresh cycle — a poll on the existing
    *  cadence, since the GitHub App has webhooks off — and via /debug
-   *  reclaim-now. Never touches the default branch, a busy thread, or a dirty
-   *  tree (reclaimDecision); every keep is named. The eviction itself is the
-   *  sweep's `evictBinding` with the same re-read guards. */
+   *  reclaim-now. Never touches the default branch or a busy thread
+   *  (reclaimDecision); every keep is named. What the tree holds is never a
+   *  reason to keep it (item 17) — it is measured once as the thread user and
+   *  recorded by the eviction, the sweep's `evictBinding` with the same
+   *  re-read guards. */
   async reclaimFinishedRefs(
     resource: string,
     defaultRef: string,
@@ -6599,21 +6689,16 @@ export class ResidentDO extends Sandbox<Env> {
       // by name), so its fate is never looked up.
       const { fate, detail } = (!isDefaultRef && fates.get(binding.ref)) || { fate: "unknown" as RefFate, detail: "" };
       const busy = this.threadOpsInFlight.get(binding.threadKey) ?? 0;
-      // The clean check runs as the thread user and only when it can decide
-      // anything: a finished ref, nothing running, runtime up (down → the tree
-      // is already gone with the disk → null).
-      const finished = fate === "gone" || fate === "merged" || fate === "closed";
-      const clean = !active
-        ? null
-        : finished && !isDefaultRef && busy === 0
-          ? (await this.worktreeCleanliness(binding)).clean
-          : null;
-      const decision = reclaimDecision({ fate, isDefaultRef, busy, clean });
+      const decision = reclaimDecision({ fate, isDefaultRef, busy });
       if (!decision.reclaim) {
         kept.push({ threadKey: binding.threadKey, ref: binding.ref, why: decision.why });
         continue;
       }
-      // Same guards as the sweep: the clean check awaited, so re-read the
+      // What the tree holds goes on the eviction's record (item 17), never
+      // into the decision: measured as the thread user while the runtime is
+      // up; down → the tree is already gone with the disk.
+      const tree = active ? await this.measureTreeBeforeEviction(binding) : undefined;
+      // Same guards as the sweep: the measurement awaited, so re-read the
       // binding (a re-attach means a fresh tree) and the op counter.
       const busyNow = this.threadOpsInFlight.get(binding.threadKey) ?? 0;
       const current = await this.ctx.storage.get<ThreadBinding>(threadBindingKey(binding.threadKey));
@@ -6627,7 +6712,7 @@ export class ResidentDO extends Sandbox<Env> {
       }
       const activeNow = await this.isRuntimeActive().catch(() => false);
       const why = `${decision.why}${detail}`;
-      if (await this.evictBinding(current, activeNow, `reclaim ${resource}`, why)) {
+      if (await this.evictBinding(current, activeNow, `reclaim ${resource}`, why, tree)) {
         reclaimed.push({ threadKey: binding.threadKey, ref: binding.ref, why });
         console.log(`reclaim ${resource}: evicted ${binding.threadKey} on ${binding.ref} — ${why}`);
       } else kept.push({ threadKey: binding.threadKey, ref: binding.ref, why: "re-attached" });
@@ -6738,18 +6823,39 @@ export class ResidentDO extends Sandbox<Env> {
     // left out; nothing here is secret (credential files are never persisted).
     const threads = [...bindings.values()]
       .sort((a, b) => b.lastAttachAt.localeCompare(a.lastAttachAt))
-      .map(({ threadKey, ref, sha, user, deps, boundAt, lastAttachAt, evicted, evictedAt, evictedWhy }) => ({
-        threadKey,
-        ref,
-        sha: sha ?? null,
-        user,
-        deps: deps ?? null,
-        boundAt,
-        lastAttachAt,
-        evicted: evicted ?? false,
-        evictedAt: evictedAt ?? null,
-        evictedWhy: evictedWhy ?? null,
-      }));
+      .map(
+        ({
+          threadKey,
+          ref,
+          sha,
+          user,
+          deps,
+          boundAt,
+          lastAttachAt,
+          evicted,
+          evictedAt,
+          evictedWhy,
+          evictedLeftBehind,
+          evictedUnmeasured,
+          recycledLeftBehind,
+          recycledUnmeasured,
+        }) => ({
+          threadKey,
+          ref,
+          sha: sha ?? null,
+          user,
+          deps: deps ?? null,
+          boundAt,
+          lastAttachAt,
+          evicted: evicted ?? false,
+          evictedAt: evictedAt ?? null,
+          evictedWhy: evictedWhy ?? null,
+          evictedLeftBehind: evictedLeftBehind ?? null,
+          evictedUnmeasured: evictedUnmeasured ?? null,
+          recycledLeftBehind: recycledLeftBehind ?? null,
+          recycledUnmeasured: recycledUnmeasured ?? null,
+        }),
+      );
     return {
       resource: map.get(RESOURCE_KEY) ?? null,
       state: map.get(STATE_KEY) ?? "down",

package/dist/assets/deploy/cloudflare-sandbox/Dockerfile

@@ -176,6 +176,17 @@ RUN npm install -g @earendil-works/pi-coding-agent@0.85.1 \
   && pi --version | grep -qx '0.85.1' \
   && pi --help | grep -q -- '--mode <mode>'
 
+# OpenCode, the second harness (docs/reference/specs/harness.md): `@opencode/cli`
+# at the EXACT pin held by src/deploy/imageOpenCodeHarness.test.ts, beside pi.
+# The wrapper's postinstall hard-links the platform binary into place, so it
+# is the one install script allowed by name; the grep proves the binary on
+# PATH prints the pin's version text (`opencode v2.0.3`, exactly); the npm
+# cache (a 200 MB tarball) is dropped in the same layer. Dark until a
+# deployment names it: nothing here starts it on its own.
+RUN npm install -g --allow-scripts=@opencode/cli @opencode/cli@2.0.3 \
+  && npm cache clean --force \
+  && opencode --version | grep -qx 'opencode v2.0.3'
+
 # The container outlives a crash of the SDK's container server (the
 # supervisor's header says why). The base image's ENTRYPOINT is tini running
 # the server, so one uncaught exception there ended the container; here tini