@coreplane/switchboard 1.267.2 → 1.268.0

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

@@ -89,6 +89,18 @@ import {
 } from "./legacyCredentials.js";
 import { hasUnexpectedOwnedThreadDir } from "./orphanThreadUsers.js";
 import { KeyedAsyncLock } from "./keyedAsyncLock.js";
+import {
+  nextDeployImageReconcile,
+  replacementContainerStarted,
+  type DeployImageReconcileState,
+} from "./imageReconcileState.js";
+import {
+  registeredRunAllowsClaim,
+  registeredRunAllowsReattach,
+  registeredRunNeedsProtection,
+  registeredRunOwnsRelease,
+} from "./runRegistration.js";
+import { DAY_MS, RUN_REGISTRATION_GRACE_MS } from "../../src/core/budgets.js";
 import { BASH_TIMEOUT_MAX_MS, clampBashTimeout } from "../../src/execution/bashTimeout.js";
 import { RESIDENT_MIRROR_PERMISSIONS, verifyGithubMintScope } from "../../src/execution/githubMintScope.js";
 import { selectBindingsToPurge } from "../../src/execution/bindingPurge.js";
@@ -172,15 +184,17 @@ import { shellQuote } from "../../src/execution/shellQuote.js";
 import { envFromRequest } from "../../src/execution/sandboxEnv.js";
 import { CREDENTIAL_EXPIRY_MARGIN_MS } from "../../src/execution/residentCredentials.js";
 import { destroyWithPersistentFence } from "../../src/execution/residentDestroyGate.js";
-import { ResidentRecreateAdmission } from "../../src/execution/residentRecreateAdmission.js";
+import { ResidentRecreateAdmission, idleForPoolRecycle } from "../../src/execution/residentRecreateAdmission.js";
 import {
   claimPoolBinding,
   mayRunAsPoolUser,
+  ownedPoolUsers,
   parsePoolBindings,
   parseSpentPoolUsers,
   rebuildPoolBindingIndex,
   releasePoolBinding,
   spendPoolUser,
+  unavailablePoolUsers,
 } from "../../src/execution/residentPoolSpends.js";
 import {
   recordFiring,
@@ -584,16 +598,10 @@ const THREADS_DIR = "/workspace/threads";
  *  at the latest (disk is cache). */
 const OPS_DIR = "/workspace/ops";
 
-/** The thread-user pool. worker1 is the engine's build user; each
- *  attach allocates one of these to the thread (persisted in the binding)
- *  and every /exec /read /write for that thread runs privilege-dropped as
- *  that user. The pool is released by the inactivity sweep. */
-/** Pool of OS users for thread worktrees (worker1 is the build user). Sized
- *  for SIMULTANEOUS runs, not for every thread ever seen: a run returns its
- *  user via /detach when it ends, so the pool only fills when 16 runs on one
- *  repo are genuinely concurrent. Memory, not this list, is the real ceiling
- *  — see the instance_type note in wrangler.jsonc. Must match the useradd loop
- *  in the Dockerfile. */
+/** Pool of OS users for thread worktrees and disposable ops. A UID stays with
+ *  its first owner for this VM generation; detach releases the live binding,
+ *  not the UID spend. Exhaustion may recycle a proven-idle VM. Must match the
+ *  useradd loop in the Dockerfile. */
 const THREAD_USERS = Array.from({ length: THREAD_POOL_SIZE }, (_, i) => `worker${i + 2}`);
 
 /** Force-detach: after killing the thread user's processes, how long
@@ -1194,6 +1202,8 @@ interface ThreadBinding {
   lastAttachAt: string;
   evicted?: boolean;
   evictedAt?: string;
+  /** Owner of the registration removed with this tree, for a delayed push receipt. */
+  lastRunOwner?: { runId?: string; ownerGen?: string; ownerFence?: number };
   /** Why the last eviction happened (the audit trail): `ttl`, `clean-idle`,
    *  `detach`, `disk-pressure`, or a reclamation fate — `merged #N` /
    *  `closed #N` / `gone`. */
@@ -1287,7 +1297,7 @@ interface AttachOk {
   returned?: Returned;
 }
 
-/** What `POST /detach` answers: whether the pool user went back, why not, and
+/** What `POST /detach` answers: whether the live binding was released, why not, and
  *  — on a release — what the tree still held (item 16a), now gone with it. */
 interface DetachAnswer {
   released: boolean;
@@ -1469,6 +1479,7 @@ const DRAIN_KEY = "drain";
  *  verify this resident's container on the new image; the next reconcile that
  *  finds it current reports to the registry and clears it. */
 const IMAGE_REPORT_PENDING_KEY = "imageReportPending";
+const IMAGE_RECONCILE_KEY = "imageReconcile";
 
 type OnboardResult = { ok: true; record: ResidentRecord } | { ok: false; status: number; error: string };
 
@@ -1764,9 +1775,17 @@ const parentDir = (p: string): string => p.slice(0, p.lastIndexOf("/"));
  *  a fresh isolate still counts the process that survived in the container. */
 const RUN_REG_KEY_PREFIX = "runReg:";
 const runRegKey = (threadKey: string) => `${RUN_REG_KEY_PREFIX}${threadKey}`;
+// A thread's highest accepted ledger claim survives registration release and
+// binding purge: a delayed older /attach must never reopen an evicted tree.
+const RUN_FENCE_KEY_PREFIX = "runFence:";
+const runFenceKey = (threadKey: string) => `${RUN_FENCE_KEY_PREFIX}${threadKey}`;
 interface RunRegistration {
   threadKey: string;
   registeredAt: string;
+  deadlineAt?: number;
+  runId?: string;
+  ownerGen?: string;
+  ownerFence?: number;
 }
 
 /** Deterministic per-thread+ref worktree path. Slugs replace anything outside
@@ -3893,8 +3912,8 @@ export class ResidentDO extends Sandbox<Env> {
     await this.ctx.storage.delete(INFRA_STREAK_KEY);
     await this.setResidentState("warm");
     // Event-triggered reclamation: the prune above already told the
-    // mirror which branches died; finished refs give their worktree and
-    // pool user back now, not at the idle TTL. Housekeeping, never a
+    // mirror which branches died; finished refs release their worktree and
+    // live binding now, not at the idle TTL. Housekeeping, never a
     // lifecycle flip — a failure here is a log line.
     try {
       const gc = await this.reclaimFinishedRefs(resource, facts.defaultRef, cycle.token);
@@ -4644,23 +4663,21 @@ export class ResidentDO extends Sandbox<Env> {
 
   /** 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. */
+   *  The run registration protects the gap between tool calls past this floor.
+   *  The idle-sleep gate (item 16b) and disk-full recycle (item 54) both read
+   *  the floor and the bounded registrations, never what a tree holds (item
+   *  17): a dirty tree no run is using protects nothing. */
   private recentlyUsed(live: ThreadBinding[]): boolean {
     const recent = systemClock() - IDLE_AFTER_S * 1000;
     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. */
+  /** A live run registration prevents sleep even after an hour without an op;
+   *  an expired one cannot keep the container awake. */
   private async isIdle(): Promise<boolean> {
     if (this.recentlyUsed(await this.liveBindings())) return false;
-    return this.inFlightCount() === 0;
+    if (this.inFlightCount() > 0) return false;
+    return (await this.registeredRunsBeyondOps()) === 0;
   }
 
   /** Bindings that hold a pool user and a tree on disk (not evicted). */
@@ -4698,10 +4715,10 @@ export class ResidentDO extends Sandbox<Env> {
    *  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
+   *  the idle floor and no live run registration — the idle-sleep gate's own
+   *  predicates, 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
@@ -4710,21 +4727,23 @@ export class ResidentDO extends Sandbox<Env> {
    *  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 = (live: ThreadBinding[]) =>
-      planDiskFullRecovery({
+    const plan = async (live: ThreadBinding[]) => {
+      const liveRegistrations = await this.registeredRunsBeyondOps();
+      return planDiskFullRecovery({
         now: systemClock(),
         lastRecycleAt,
         inFlight: this.inFlightCount() - selfInFlight,
-        recentlyUsed: this.recentlyUsed(live),
+        recentlyUsed: this.recentlyUsed(live) || liveRegistrations > 0,
         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);
+    const first = await 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
@@ -4737,7 +4756,7 @@ export class ResidentDO extends Sandbox<Env> {
       : 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());
+    const verdict = await 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})`,
@@ -5153,8 +5172,8 @@ export class ResidentDO extends Sandbox<Env> {
    *  run — stop the container so it restarts on the current image (state is DO
    *  storage + R2 — the disk is a cache). A deferred restart re-checks on
    *  every later refresh cycle until the resident is quiet; a registration
-   *  whose release never came defers it only until the clean-idle sweep drains
-   *  that registration. The attach path never stops the container (issue 2101,
+   *  whose release never came defers it only through the clean-idle window;
+   *  a later sweep removes its binding. The attach path never stops the container (issue 2101,
    *  the `stale` answer below); the stop is the refresh cycle's or the
    *  deploy's alone. Answers `restarted` when a stop was issued, else why
    *  not. */
@@ -5233,7 +5252,12 @@ export class ResidentDO extends Sandbox<Env> {
     }
     console.log(`image-stale (${where}): ${stale} — stopping so it restarts on the current image`);
     this.swapIncarnation(); // deliberate incarnation swap
-    await this.stop().catch((err) => console.log(`image-stale: stop failed: ${errMsg(err)}`));
+    try {
+      await this.stop();
+    } catch (err) {
+      console.log(`image-stale: stop failed: ${errMsg(err)}`);
+      if (where === "deploy") return "deferred";
+    }
     // A successful stop proves only that the old process is gone. The pending
     // marker deliberately survives it: the replacement's own hydration reports
     // after reaching `warm`, so `imageReport: current` can never precede a
@@ -5289,9 +5313,66 @@ export class ResidentDO extends Sandbox<Env> {
    *  added afterwards would wait for a report nothing sends (until the drain's
    *  `until`). Held first, every report finds its hold. */
   async reconcileForDeploy(resource: string): Promise<{ result: ImageReconcileResult; verified: boolean }> {
-    await registryStub(this.env).holdDrainFor([resource]);
-    await this.ctx.storage.put(IMAGE_REPORT_PENDING_KEY, { resource });
+    // The deploy's image report and an idle pool recycle both reason about the
+    // same VM. Admit reconciliation as disk work before its first await, so a
+    // recycle sees it as busy; a recycle already holding admission defers this
+    // pass for the deploy's bounded readiness retry.
+    const admitted = await this.withRecreateSafeAdmin(() => this.reconcileForDeployAdmitted(resource));
+    return "error" in admitted ? { result: "deferred", verified: false } : admitted;
+  }
+
+  private async reconcileForDeployAdmitted(
+    resource: string,
+  ): Promise<{ result: ImageReconcileResult; verified: boolean }> {
+    const progress = await this.ctx.storage.get<DeployImageReconcileState>(IMAGE_RECONCILE_KEY);
+    const pending = await this.ctx.storage.get<{ resource: string }>(IMAGE_REPORT_PENDING_KEY);
+    const action = nextDeployImageReconcile(BUILD.commit, progress, pending !== undefined);
+    if (action === "verified") return { result: "current", verified: true };
+    if (action === "start") {
+      await registryStub(this.env).holdDrainFor([resource]);
+      await this.ctx.storage.put(IMAGE_REPORT_PENDING_KEY, { resource });
+      await this.ctx.storage.put(IMAGE_RECONCILE_KEY, { build: BUILD.commit, cycleIssued: false });
+    }
+    if (action === "await-report") {
+      const active = await this.isRuntimeActive().catch(() => null);
+      if (active === false) await this.reportPendingImageCurrent("deploy");
+      else if (active === true) {
+        const [state, facts] = await Promise.all([
+          this.ctx.storage.get<ResidentState>(STATE_KEY),
+          this.ctx.storage.get<RepoFacts>(FACTS_KEY),
+        ]);
+        // A replacement can reuse the disk and leave `warm` unchanged; that
+        // hydrate shortcut does not send a report. A different boot after the
+        // successful stop is proof that a replacement started. Finish its
+        // hydration before reporting; an old warm state alone proves nothing.
+        if (replacementContainerStarted(progress?.containerBeforeCycle, await this.containerIdentity())) {
+          await this.ensureHydrated();
+          await this.reportPendingImageCurrent("deploy");
+        } else if (
+          state === "warm" &&
+          facts?.lastRestore?.at &&
+          Date.parse(facts.lastRestore.at) >= Date.parse(progress?.cycleStoppedAt ?? "")
+        ) {
+          await this.reportPendingImageCurrent("deploy");
+        }
+      }
+      return {
+        result: active === false ? "inactive" : "deferred",
+        verified: (await this.ctx.storage.get(IMAGE_REPORT_PENDING_KEY)) === undefined,
+      };
+    }
+    // Reading the boot ID runs a command and would wake a sleeping resident.
+    // Preserve the inactive path's report-without-start behavior.
+    const activeBeforeCycle = await this.isRuntimeActive().catch(() => null);
+    const containerBeforeCycle = activeBeforeCycle === true ? await this.containerIdentity() : undefined;
     const result = await this.reconcileImage("deploy", true);
+    if (result === "restarted")
+      await this.ctx.storage.put(IMAGE_RECONCILE_KEY, {
+        build: BUILD.commit,
+        cycleIssued: true,
+        cycleStoppedAt: new Date(systemClock()).toISOString(),
+        containerBeforeCycle,
+      } satisfies DeployImageReconcileState);
     if (result === "deferred") return { result, verified: false };
     // Inactivity reports synchronously; a successful stop does not. A
     // concurrent fresh start may also have hydrated while this reconcile
@@ -5598,7 +5679,11 @@ export class ResidentDO extends Sandbox<Env> {
   /** Storage bindings, active ops and inspections all reserve a pool user.
    * Claim inside this method, before its promise resolves: two concurrent
    * callers must not each read the same free UID before either can claim it. */
-  private async findFreePoolUser(excludeThreadKey?: string, excluded = new Set<string>()): Promise<string | undefined> {
+  private async findFreePoolUser(
+    excludeThreadKey?: string,
+    excluded = new Set<string>(),
+    preferred: readonly string[] = [],
+  ): Promise<string | undefined> {
     const all = await this.ctx.storage.list<ThreadBinding>({ prefix: THREAD_KEY_PREFIX });
     const used = new Set(
       [...all.values()].filter((b) => !b.evicted && b.user && b.threadKey !== excludeThreadKey).map((b) => b.user),
@@ -5606,7 +5691,7 @@ export class ResidentDO extends Sandbox<Env> {
     for (const u of this.opUsersInUse.keys()) used.add(u);
     for (const u of this.poolUsersInspecting) used.add(u);
     for (const u of excluded) used.add(u);
-    const user = THREAD_USERS.find((u) => !used.has(u));
+    const user = [...preferred, ...THREAD_USERS].find((u) => !used.has(u));
     if (user) this.poolUsersInspecting.add(user);
     return user;
   }
@@ -5643,19 +5728,82 @@ export class ResidentDO extends Sandbox<Env> {
     throw new Error("pool-user-stage-scan-invalid");
   }
 
+  /** A full one-use pool can serve the next request by destroying its VM,
+   * never by assigning another owner's UID. The admission mark closes every
+   * other entry before the idle read and stays held through the restore. */
+  private async recycleSpentPoolForAdmission(): Promise<true | ThreadErr> {
+    try {
+      const admission = await this.recreateAdmission.run(async (): Promise<true | ThreadErr> => {
+        const spent = parseSpentPoolUsers(await this.ctx.storage.get<unknown>(SPENT_POOL_USERS_KEY), THREAD_USERS);
+        if (!spent) return { error: "pool-generation-unknown: fresh VM required before UID assignment", status: 503 };
+        if (spent.size < THREAD_USERS.length) return true; // another checked recreate already cleared the generation
+        const [status, drain, imagePending, snapshot, registeredRuns, bindings] = await Promise.all([
+          this.getStatus(),
+          this.registry().getDrain(),
+          this.ctx.storage.get(IMAGE_REPORT_PENDING_KEY),
+          this.ctx.storage.get(SNAPSHOT_KEY),
+          this.registeredRunsBeyondOps(),
+          this.ctx.storage.list<ThreadBinding>({ prefix: THREAD_KEY_PREFIX }),
+        ]);
+        if (
+          !snapshot ||
+          !idleForPoolRecycle({
+            state: status.state,
+            draining: liveDrain(drain, systemClock()) !== null,
+            imagePending: imagePending !== undefined,
+            inFlight: this.inFlightCount(),
+            refreshAdmissions: this.refreshAdmissionsInFlight,
+            adminWork: this.adminWorkInFlight,
+            hydrating: this.hydration !== null,
+            registeredRuns,
+            liveBindings: [...bindings.values()].filter((binding) => !binding.evicted).length,
+            inspecting: this.poolUsersInspecting.size,
+          })
+        )
+          return {
+            error: "pool-recycle-required: all UIDs spent and the resident is not idle for checked VM recycle",
+            status: 503,
+          };
+        await this.recreateContainer("pool-recycle: all UIDs spent; no other resident work owns this VM");
+        await this.ensureHydrated();
+        const fresh = parseSpentPoolUsers(await this.ctx.storage.get<unknown>(SPENT_POOL_USERS_KEY), THREAD_USERS);
+        const ready = await this.getStatus();
+        const imageStillPending = (await this.ctx.storage.get(IMAGE_REPORT_PENDING_KEY)) !== undefined;
+        if (!fresh || fresh.size !== 0 || ready.state !== "warm" || imageStillPending)
+          return { error: "pool-recycle-failed: the restored VM is not warm, current and empty", status: 503 };
+        return true;
+      });
+      return admission.busy ? this.recreateRefusal() : admission.value;
+    } catch (err) {
+      console.log(`pool-recycle: checked VM recycle failed (${errMsg(err)})`);
+      return { error: "pool-recycle-failed: the checked VM restore did not complete", status: 503 };
+    }
+  }
+
   private async reserveSafePoolUser(owner: string, excludeThreadKey?: string): Promise<string | ThreadErr> {
-    const spent = parseSpentPoolUsers(await this.ctx.storage.get<unknown>(SPENT_POOL_USERS_KEY), THREAD_USERS);
+    let spent = parseSpentPoolUsers(await this.ctx.storage.get<unknown>(SPENT_POOL_USERS_KEY), THREAD_USERS);
     if (!spent) return { error: "pool-generation-unknown: fresh VM required before UID assignment", status: 503 };
-    const excluded = new Set(spent.keys());
+    let excluded = unavailablePoolUsers(spent, owner);
     let contaminated = false;
+    let recycled = false;
     for (;;) {
-      const user = await this.findFreePoolUser(excludeThreadKey, excluded);
-      if (!user)
+      const user = await this.findFreePoolUser(excludeThreadKey, excluded, ownedPoolUsers(spent, owner));
+      if (!user) {
+        if (!contaminated && excluded.size === THREAD_USERS.length && !recycled) {
+          recycled = true;
+          const result = await this.recycleSpentPoolForAdmission();
+          if (result !== true) return result;
+          spent = parseSpentPoolUsers(await this.ctx.storage.get<unknown>(SPENT_POOL_USERS_KEY), THREAD_USERS);
+          if (!spent) return { error: "pool-generation-unknown: fresh VM required before UID assignment", status: 503 };
+          excluded = unavailablePoolUsers(spent, owner);
+          continue;
+        }
         return contaminated
           ? { error: "pool-user-contaminated: no clean pool user is available", status: 503 }
           : excluded.size === THREAD_USERS.length
             ? { error: "pool-recycle-required: all UIDs spent on this VM; confirm idle and recreate it", status: 503 }
             : { error: "user-pool-exhausted: no safe pool user is available", status: 429 };
+      }
       let safe = false;
       try {
         const clean = !(await this.poolUserHasOldThreadDir(user, [])) && !(await this.poolUserHasOldStageContent(user));
@@ -5798,23 +5946,37 @@ export class ResidentDO extends Sandbox<Env> {
     traceparent?: string,
     reason: RefHintReason = NO_REF_HINT_REASON,
     githubDoor?: { baseUrl: string; bearer: string },
+    runBudgetMs?: number,
+    runId?: string,
+    ownerGen?: string,
+    ownerFence?: number,
   ): Promise<AttachOk | ThreadErr> {
     // One step trace per attach (docs/reference/specs/tracing.md item 19): every command
     // the attach runs lands on it, and the answer carries it.
     const t0 = systemClock();
     const trace = createStepTrace(t0);
     let res: AttachOk | ThreadErr;
-    if (this.recreateAdmission.pending) {
-      res = this.recreateRefusal();
-    } else {
-      this.attachAdmissionsInFlight++;
-      try {
-        res = await this.stepTrace.run(trace, () =>
-          this.attachThreadTraced(threadKey, refHint, readonly, wantSha, reuse, record, t0, reason, githubDoor),
-        );
-      } finally {
-        this.attachAdmissionsInFlight--;
-      }
+    this.attachAdmissionsInFlight++;
+    try {
+      res = await this.stepTrace.run(trace, () =>
+        this.attachThreadTraced(
+          threadKey,
+          refHint,
+          readonly,
+          wantSha,
+          reuse,
+          record,
+          t0,
+          reason,
+          githubDoor,
+          runBudgetMs,
+          runId,
+          ownerGen,
+          ownerFence,
+        ),
+      );
+    } finally {
+      this.attachAdmissionsInFlight--;
     }
     // The same steps as the resident's own `resident.attach` root (item 22).
     emitStepRoot("resident.attach", t0, trace.steps(), traceparent, "error" in res ? refusalOutcome(res) : "ok");
@@ -5832,56 +5994,80 @@ export class ResidentDO extends Sandbox<Env> {
     t0: number,
     reason: RefHintReason,
     githubDoor?: { baseUrl: string; bearer: string },
+    runBudgetMs?: number,
+    runId?: string,
+    ownerGen?: string,
+    ownerFence?: number,
   ): Promise<AttachOk | ThreadErr> {
     try {
-      if (await this.recreateAdmission.blocked()) return this.recreateRefusal();
-      await this.ensureHydrated();
-      if (await this.recreateAdmission.blocked()) return this.recreateRefusal();
-      // The fleet drain (item 69): a deploy is waiting for the runs in flight
-      // to end, and a NEW run's attach is refused with the record the bot
-      // waits on — a real 503 in the streamed document, read by the client as
-      // `draining`, never as the platform's transient. A run already in flight
-      // — registered from its attach to its release (item 44) — re-attaches
-      // through: a rolled container, an evicted worktree, a resumed run are
-      // the runs the drain waits FOR, and refusing them would hold the fleet
-      // closed on the run it is closed for. Read before the image reconcile so
-      // a refused attach never restarts a container.
-      const drain = await this.fleetDrain();
-      const registered = (await this.ctx.storage.get(runRegKey(threadKey))) !== undefined;
-      if (drain && !registered) {
-        const refusal: ThreadErr & { draining: DrainRecord } = drainRefusal(drain);
-        return refusal;
-      }
-      // Item 70: above the soft memory threshold a NEW attach is refused like
-      // `mirror-busy` (the bot falls back or waits, the card says why) — after
-      // the drain (storage only, cheaper) and before the image reconcile, so a
-      // refused attach never restarts a container. A registered run's
-      // re-attach passes for the same reason it passes the drain above.
-      const memory = await this.memoryGate("attach", registered);
-      if (memory) return memory;
-      const resourceId = (await this.ctx.storage.get<string>(RESOURCE_KEY)) ?? "";
-      // An attach never restarts the container (issue 2101): a `stale` verdict
-      // refuses the NEW run — it falls back to the seeded sandbox — while a
-      // registered run's re-attach passes exactly as it passes the drain and
-      // the memory gate; the restart itself is the refresh cycle's or the
-      // deploy's.
-      if ((await this.reconcileImage("attach")) === "stale" && !registered) {
-        const s = await this.getStatus();
-        return {
-          error:
-            "image-stale: the container predates the deploy and restarts on the next quiet refresh; new runs use the fallback sandbox until then",
-          status: 503,
-          state: s.state,
-          stateReason: s.reason,
-          reason: "image-stale",
-        };
-      }
-      // From here the attach may hold the mirror lock through clone/install:
-      // count it so a concurrent refresh-cycle reconcileImage never stops the
-      // container under it (and isIdle never parks the cycle mid-attach).
-      this.attachesInFlight++;
-      try {
-        return await this.threadAttaches.run(threadKey, async () => {
+      return await this.threadAttaches.run(threadKey, async () => {
+        // The attachment fence takes precedence over every 503 gate. Keep the
+        // same thread lock through the gates and registration write so a newer
+        // attach cannot slip between this check and a fallback-eligible refusal.
+        const current = await this.ctx.storage.get<RunRegistration>(runRegKey(threadKey));
+        const accepted = await this.ctx.storage.get<Pick<RunRegistration, "runId" | "ownerGen" | "ownerFence">>(
+          runFenceKey(threadKey),
+        );
+        if (
+          !registeredRunAllowsClaim(current, runId, ownerGen, ownerFence) ||
+          !registeredRunAllowsClaim(accepted, runId, ownerGen, ownerFence)
+        )
+          return { error: "run-registration-mismatch: a newer generation owns the thread", status: 409 };
+        if (await this.recreateAdmission.blocked()) return this.recreateRefusal();
+        await this.ensureHydrated();
+        if (await this.recreateAdmission.blocked()) return this.recreateRefusal();
+        // The fleet drain (item 69): a deploy is waiting for the runs in flight
+        // to end, and a NEW run's attach is refused with the record the bot
+        // waits on — a real 503 in the streamed document, read by the client as
+        // `draining`, never as the platform's transient. A run already in flight
+        // — with an owned, live registration (item 44) — re-attaches
+        // through: a rolled container, an evicted worktree, a resumed run are
+        // the runs the drain waits FOR, and refusing them would hold the fleet
+        // closed on the run it is closed for. Read before the image reconcile so
+        // a refused attach never restarts a container.
+        const drain = await this.fleetDrain();
+        const registration = await this.ctx.storage.get<RunRegistration>(runRegKey(threadKey));
+        const registered = registeredRunAllowsReattach(
+          registration,
+          runId,
+          systemClock(),
+          RUN_REGISTRATION_GRACE_MS,
+          ownerGen,
+          ownerFence,
+        );
+        if (drain && !registered) {
+          const refusal: ThreadErr & { draining: DrainRecord } = drainRefusal(drain);
+          return refusal;
+        }
+        // Item 70: above the soft memory threshold a NEW attach is refused like
+        // `mirror-busy` (the bot falls back or waits, the card says why) — after
+        // the drain (storage only, cheaper) and before the image reconcile, so a
+        // refused attach never restarts a container. An owned, live run's
+        // re-attach passes for the same reason it passes the drain above.
+        const memory = await this.memoryGate("attach", registered);
+        if (memory) return memory;
+        const resourceId = (await this.ctx.storage.get<string>(RESOURCE_KEY)) ?? "";
+        // An attach never restarts the container (issue 2101): a `stale` verdict
+        // refuses the NEW run — it falls back to the seeded sandbox — while a
+        // owned, live run's re-attach passes exactly as it passes the drain and
+        // the memory gate; the restart itself is the refresh cycle's or the
+        // deploy's.
+        if ((await this.reconcileImage("attach")) === "stale" && !registered) {
+          const s = await this.getStatus();
+          return {
+            error:
+              "image-stale: the container predates the deploy and restarts on the next quiet refresh; new runs use the fallback sandbox until then",
+            status: 503,
+            state: s.state,
+            stateReason: s.reason,
+            reason: "image-stale",
+          };
+        }
+        // From here the attach may hold the mirror lock through clone/install:
+        // count it so a concurrent refresh-cycle reconcileImage never stops the
+        // container under it (and isIdle never parks the cycle mid-attach).
+        this.attachesInFlight++;
+        try {
           const res = await this.attachThreadBody(
             threadKey,
             refHint,
@@ -5896,12 +6082,12 @@ export class ResidentDO extends Sandbox<Env> {
           );
           // The run this attach opens is now in flight until its release —
           // whatever its op counters read between the bot's calls (item 44).
-          if (!("error" in res)) await this.registerRun(threadKey);
+          if (!("error" in res)) await this.registerRun(threadKey, runBudgetMs, runId, ownerGen, ownerFence);
           return res;
-        });
-      } finally {
-        this.attachesInFlight--;
-      }
+        } finally {
+          this.attachesInFlight--;
+        }
+      });
     } catch (err) {
       return catchAllErr(err, "attach-failed");
     }
@@ -7736,6 +7922,7 @@ export class ResidentDO extends Sandbox<Env> {
       user: "",
       evicted: true,
       evictedAt: new Date(systemClock()).toISOString(),
+      lastRunOwner: await this.ctx.storage.get<RunRegistration>(runRegKey(binding.threadKey)),
       evictedWhy: why,
       evictedLeftBehind: tree && "leftBehind" in tree ? tree.leftBehind : undefined,
       evictedUnmeasured: tree && "unmeasured" in tree ? tree.unmeasured : undefined,
@@ -7747,9 +7934,9 @@ export class ResidentDO extends Sandbox<Env> {
     return "evicted";
   }
 
-  /** POST /detach: a run has ended — give the thread's pool user back now
-   *  instead of holding it until the TTL sweep (the pool is sized for
-   *  simultaneous runs). A run starts from a clean tree (item 17), so the tree
+  /** POST /detach: a run has ended — release its live binding now instead of
+   *  holding it until the TTL sweep. The UID remains spent for this VM
+   *  generation. A run starts from a clean tree (item 17), so the tree
    *  goes whatever it holds: what it held — uncommitted changes, unpushed
    *  commits — is measured once, as the thread user, and named in the answer
    *  (`leftBehind`) so the loss is never silent. The one thing that keeps a
@@ -7763,65 +7950,77 @@ export class ResidentDO extends Sandbox<Env> {
     force: boolean,
     /** What the ending run pushed (item 16a): remembered on the binding first, whatever the detach then decides. */
     pushed: readonly PushedBranch[] = [],
+    runId?: string,
+    ownerGen?: string,
+    ownerFence?: number,
   ): Promise<DetachAnswer | ThreadErr> {
-    if (pushed.length > 0) await this.rememberOwnBranches(threadKey, pushed);
-    const binding = await this.ctx.storage.get<ThreadBinding>(threadBindingKey(threadKey));
-    if (!binding) return { error: `no-binding: ${threadKey} has never attached to this resident`, status: 404 };
-    if (binding.evicted || !binding.user) return { released: false, reason: "already-evicted" };
-    if (!(await this.poolUserOwnerMatches(binding.user, `thread:${threadKey}`)))
-      return { error: "pool-owner-mismatch: detach refused for conflicting UID owner", status: 503 };
-    const plan = planForceDetach({
-      force,
-      inFlight: this.threadOpsInFlight.get(threadKey) ?? 0,
-      user: binding.user,
-      poolUsers: THREAD_USERS,
-    });
-    if (plan.action === "refuse") return { released: false, reason: plan.reason, user: binding.user };
-    if (plan.action === "kill") {
-      if (!(await this.killThreadUserProcesses(plan.user, threadKey)))
-        return { error: "pool-owner-mismatch: force detach refused before kill", status: 503 };
-      console.log(
-        `detach: force — killed ${plan.user}'s processes for ${threadKey} (${plan.inFlight} op(s) were in flight)`,
-      );
-      const left = await this.waitForThreadDrain(threadKey);
-      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 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.
-    const busyNow = this.threadOpsInFlight.get(threadKey) ?? 0;
-    if (busyNow > 0)
-      return {
-        released: false,
-        reason: `busy: ${busyNow} operation(s) started during detach — kept`,
+    return this.threadAttaches.run(threadKey, async () => {
+      const binding = await this.ctx.storage.get<ThreadBinding>(threadBindingKey(threadKey));
+      if (!binding) return { error: `no-binding: ${threadKey} has never attached to this resident`, status: 404 };
+      if (binding.evicted || !binding.user) {
+        if (pushed.length > 0 && registeredRunOwnsRelease(binding.lastRunOwner, runId, ownerGen, ownerFence))
+          await this.rememberOwnBranches(threadKey, pushed);
+        return { released: false, reason: "already-evicted" };
+      }
+      const registration = await this.ctx.storage.get<RunRegistration>(runRegKey(threadKey));
+      if (!registeredRunOwnsRelease(registration, runId, ownerGen, ownerFence))
+        return { released: false, reason: "run-registration-mismatch: the workspace belongs to another run" };
+      if (pushed.length > 0) await this.rememberOwnBranches(threadKey, pushed);
+      if (!(await this.poolUserOwnerMatches(binding.user, `thread:${threadKey}`)))
+        return { error: "pool-owner-mismatch: detach refused for conflicting UID owner", status: 503 };
+      const plan = planForceDetach({
+        force,
+        inFlight: this.threadOpsInFlight.get(threadKey) ?? 0,
         user: binding.user,
-      };
-    // Same re-read as the sweep: a re-attach during the measurement means a
-    // fresh tree we must not remove from a stale snapshot.
-    const current = await this.ctx.storage.get<ThreadBinding>(threadBindingKey(threadKey));
-    if (!current || current.evicted) return { released: false, reason: "already-evicted" };
-    if (current.lastAttachAt !== binding.lastAttachAt)
-      return { released: false, reason: "re-attached during the detach — kept", user: current.user };
-    const user = current.user;
-    // 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(() => true);
-    const eviction = await this.evictBinding(current, activeNow, `detach`, "detach", tree);
-    if (eviction === "cleanup-failed")
-      return { released: false, reason: "thread-cleanup-failed: pool user kept", user };
-    if (eviction === "changed") return { released: false, reason: "re-attached during eviction — kept", user };
-    // 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 } : {}) };
+        poolUsers: THREAD_USERS,
+      });
+      if (plan.action === "refuse") return { released: false, reason: plan.reason, user: binding.user };
+      if (plan.action === "kill") {
+        if (!(await this.killThreadUserProcesses(plan.user, threadKey)))
+          return { error: "pool-owner-mismatch: force detach refused before kill", status: 503 };
+        console.log(
+          `detach: force — killed ${plan.user}'s processes for ${threadKey} (${plan.inFlight} op(s) were in flight)`,
+        );
+        const left = await this.waitForThreadDrain(threadKey);
+        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 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.
+      const busyNow = this.threadOpsInFlight.get(threadKey) ?? 0;
+      if (busyNow > 0)
+        return {
+          released: false,
+          reason: `busy: ${busyNow} operation(s) started during detach — kept`,
+          user: binding.user,
+        };
+      // Same re-read as the sweep: a re-attach during the measurement means a
+      // fresh tree we must not remove from a stale snapshot.
+      const current = await this.ctx.storage.get<ThreadBinding>(threadBindingKey(threadKey));
+      if (!current || current.evicted) return { released: false, reason: "already-evicted" };
+      if (current.lastAttachAt !== binding.lastAttachAt)
+        return { released: false, reason: "re-attached during the detach — kept", user: current.user };
+      const user = current.user;
+      // 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(() => true);
+      const eviction = await this.evictBinding(current, activeNow, `detach`, "detach", tree);
+      if (eviction === "cleanup-failed")
+        return { released: false, reason: "thread-cleanup-failed: pool user kept", user };
+      if (eviction === "changed") return { released: false, reason: "re-attached during eviction — kept", user };
+      // 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 } : {}) };
+    });
   }
 
   /** Force-detach's kill: end every process owned by the pool user —
@@ -7936,25 +8135,74 @@ export class ResidentDO extends Sandbox<Env> {
   async getInFlightCount(): Promise<number> {
     return this.inFlightCount() + (await this.registeredRunsBeyondOps());
   }
-  /** A run holds its worktree from `/attach` to its release (`/detach`, the
-   *  sweep, disk pressure — every path ends in `evictBinding`, which clears
-   *  the row). Written by the attach; idempotent, a re-attach refreshes it. */
-  private async registerRun(threadKey: string): Promise<void> {
-    await this.ctx.storage.put(runRegKey(threadKey), {
-      threadKey,
-      registeredAt: new Date(systemClock()).toISOString(),
-    } satisfies RunRegistration);
+  /** A run's registration protects its worktree until release or the bounded
+   *  deadline. `/detach`, the sweep, and disk pressure end in `evictBinding`,
+   *  which clears the row; a re-attach refreshes it. */
+  private async registerRun(
+    threadKey: string,
+    runBudgetMs?: number,
+    runId?: string,
+    ownerGen?: string,
+    ownerFence?: number,
+  ): Promise<void> {
+    const now = systemClock();
+    await this.ctx.storage.transaction(async (txn) => {
+      if (ownerFence !== undefined) await txn.put(runFenceKey(threadKey), { runId, ownerGen, ownerFence });
+      await txn.put(runRegKey(threadKey), {
+        threadKey,
+        registeredAt: new Date(now).toISOString(),
+        ...(runBudgetMs !== undefined ? { deadlineAt: now + runBudgetMs } : {}),
+        ...(runId !== undefined ? { runId } : {}),
+        ...(ownerGen !== undefined ? { ownerGen } : {}),
+        ...(ownerFence !== undefined ? { ownerFence } : {}),
+      } satisfies RunRegistration);
+    });
+  }
+  /** The harness's lease begins after attach. Tighten the provisional setup
+   * bound to its actual remaining clock, only for the run that attached. */
+  async updateRunDeadline(
+    threadKey: string,
+    runId: string,
+    remainingMs: number,
+    ownerGen?: string,
+    ownerFence?: number,
+  ): Promise<{ deadlineAt: number } | ThreadErr> {
+    return this.ctx.storage.transaction(async (txn) => {
+      const registration = await txn.get<RunRegistration>(runRegKey(threadKey));
+      if (
+        !registration ||
+        registration.runId !== runId ||
+        registration.ownerGen !== ownerGen ||
+        registration.ownerFence !== ownerFence
+      )
+        return { error: "run-registration-mismatch: this run does not own the thread", status: 409 };
+      const deadlineAt = systemClock() + remainingMs;
+      await txn.put(runRegKey(threadKey), { ...registration, deadlineAt });
+      return { deadlineAt };
+    });
   }
   /** The registrations the op counters do not already see: a thread with an
    *  op in flight is counted by `runsInFlightCount`, so its registration is
-   *  not counted again. Deliberately NOT part of `inFlightCount()`: the
-   *  container-lifecycle predicates (isIdle, reconcileImage) must not let a
-   *  stale registration pin a container awake — the clean-idle sweep is what
-   *  drains a registration whose release never came. */
+   *  not counted again. The idle, image-reconcile and disk-recycle gates read
+   *  this bounded count alongside their op counters, so a live run protects
+   *  its container while a stale registration cannot pin it awake. */
   private async registeredRunsBeyondOps(): Promise<number> {
     const regs = await this.ctx.storage.list<RunRegistration>({ prefix: RUN_REG_KEY_PREFIX });
+    const cutoff = systemClock() - CLEAN_IDLE_RELEASE_S * 1000;
     let n = 0;
-    for (const r of regs.values()) if ((this.threadOpsInFlight.get(r.threadKey) ?? 0) === 0) n++;
+    for (const r of regs.values()) {
+      const binding = await this.ctx.storage.get<ThreadBinding>(threadBindingKey(r.threadKey));
+      if (
+        registeredRunNeedsProtection(
+          binding?.lastAttachAt,
+          this.threadOpsInFlight.get(r.threadKey) ?? 0,
+          cutoff,
+          r.deadlineAt === undefined ? undefined : r.deadlineAt + RUN_REGISTRATION_GRACE_MS,
+          systemClock(),
+        )
+      )
+        n++;
+    }
     return n;
   }
   private attachesInFlight = 0;
@@ -7983,6 +8231,15 @@ export class ResidentDO extends Sandbox<Env> {
     const idleCutoff = systemClock() - CLEAN_IDLE_RELEASE_S * 1000;
     for (const binding of all.values()) {
       if (binding.evicted || !binding.user) continue;
+      const registration = await this.ctx.storage.get<RunRegistration>(runRegKey(binding.threadKey));
+      if (
+        registration?.deadlineAt !== undefined &&
+        Number.isSafeInteger(registration.deadlineAt) &&
+        systemClock() <= registration.deadlineAt + RUN_REGISTRATION_GRACE_MS
+      ) {
+        kept++;
+        continue;
+      }
       const last = Date.parse(binding.lastAttachAt);
       if (last >= cutoff) {
         // Not past the TTL. Still release it if it has been idle for an hour
@@ -7991,9 +8248,9 @@ export class ResidentDO extends Sandbox<Env> {
         // a clean tree (item 17) — so there is nothing to keep it for. This is
         // what drains the bindings of runs whose release never came (a
         // resident that was sick at the run's end, a run older than
-        // `/detach`). A live run is protected by its op in flight, not by its
-        // dirt. A slept container has no tree any more anyway (sleep destroys
-        // the disk).
+        // `/detach`). A live run is protected by its budget above or an op
+        // in flight, not by its dirt. A slept container has no tree any more
+        // anyway (sleep destroys the disk).
         const busy = this.threadOpsInFlight.get(binding.threadKey) ?? 0;
         if (last >= idleCutoff || busy > 0) {
           kept++;
@@ -8390,13 +8647,30 @@ export class ResidentDO extends Sandbox<Env> {
         fates.set(ref, { fate: looked.fate, detail });
       }),
     );
-    // The runs registered on this resident (item 44): a run holds its tree
-    // from its attach to its release, and its process lives in the container
+    // The runs registered on this resident (item 44): a live registration
+    // holds its tree through the deadline, and its process lives in the container
     // between the bot's calls — the op counters read 0 while its model thinks.
+    const registrations = new Map(
+      [...(await this.ctx.storage.list<RunRegistration>({ prefix: RUN_REG_KEY_PREFIX })).values()].map((r) => [
+        r.threadKey,
+        r,
+      ]),
+    );
+    const protectsTree = (binding: ThreadBinding, registration: RunRegistration | undefined): boolean => {
+      if (!registration) return false;
+      const now = systemClock();
+      return registeredRunNeedsProtection(
+        binding.lastAttachAt,
+        0,
+        now - CLEAN_IDLE_RELEASE_S * 1000,
+        registration.deadlineAt === undefined ? undefined : registration.deadlineAt + RUN_REGISTRATION_GRACE_MS,
+        now,
+      );
+    };
     const registered = new Set(
-      [...(await this.ctx.storage.list<RunRegistration>({ prefix: RUN_REG_KEY_PREFIX })).values()].map(
-        (r) => r.threadKey,
-      ),
+      live
+        .filter((binding) => protectsTree(binding, registrations.get(binding.threadKey)))
+        .map((binding) => binding.threadKey),
     );
     for (const binding of live) {
       const isDefaultRef = binding.ref === defaultRef;
@@ -8423,7 +8697,8 @@ export class ResidentDO extends Sandbox<Env> {
         continue;
       }
       // A run attached while the tree was measured holds it now (item 44).
-      if ((await this.ctx.storage.get<RunRegistration>(runRegKey(binding.threadKey))) !== undefined) {
+      const currentRegistration = await this.ctx.storage.get<RunRegistration>(runRegKey(binding.threadKey));
+      if (protectsTree(current ?? binding, currentRegistration)) {
         kept.push({ threadKey: binding.threadKey, ref: binding.ref, why: "run-held" });
         continue;
       }
@@ -8643,6 +8918,7 @@ export class ResidentDO extends Sandbox<Env> {
     // The runs whose process lives in the container between operator calls
     // (item 44): what the deploy preflight must see, added to both counts.
     const registeredRuns = await this.registeredRunsBeyondOps();
+    const poolSpends = parseSpentPoolUsers(map.get(SPENT_POOL_USERS_KEY), THREAD_USERS);
     return {
       resource: map.get(RESOURCE_KEY) ?? null,
       state: this.destroying || map.get(DESTROY_UNCONFIRMED_KEY) ? "down" : (map.get(STATE_KEY) ?? "down"),
@@ -8674,7 +8950,10 @@ export class ResidentDO extends Sandbox<Env> {
       // running container the last deploy could not verify.
       imageReport: map.get(IMAGE_REPORT_PENDING_KEY) !== undefined ? "pending" : "current",
       recreateAdmissionHeld: this.recreateAdmission.pending || map.get(RECREATE_ADMISSION_KEY) === true,
-      poolUsersSpent: parseSpentPoolUsers(map.get(SPENT_POOL_USERS_KEY), THREAD_USERS)?.size ?? null,
+      poolUsersSpent: poolSpends?.size ?? null,
+      // Read-scoped owner receipts explain historical occupancy even after
+      // every live binding and disposable op has ended.
+      poolUserSpends: poolSpends ? [...poolSpends].map(([user, owner]) => ({ user, owner })) : null,
       // Item 22: who holds what, as the rows say — the mirror mutex and the
       // cycle/hydration leases, each judged against this incarnation.
       incarnation: this.incarnation,
@@ -9249,6 +9528,7 @@ const ROUTES: Record<string, { scope: Scope; method: string }> = {
   "/debug": { scope: "read", method: "POST" }, // per-op: READ_DEBUG_OPS for read scope, everything for admin
   "/status": { scope: "operator", method: "GET" },
   "/attach": { scope: "operator", method: "POST" },
+  "/run-deadline": { scope: "operator", method: "POST" },
   "/detach": { scope: "operator", method: "POST" },
   "/exec": { scope: "operator", method: "POST" },
   "/read": { scope: "operator", method: "POST" },
@@ -9366,6 +9646,8 @@ export default {
             return await handleStatus(env, url);
           case "/attach":
             return await handleAttach(env, body, traceparent);
+          case "/run-deadline":
+            return await handleRunDeadline(env, body);
           case "/detach":
             return await handleDetach(env, body);
           case "/exec":
@@ -9996,6 +10278,27 @@ async function handleAttach(env: Env, body: Record<string, unknown>, traceparent
   if ("error" in want) return json({ error: want.error }, 400);
   const reuse = parseReuse(body.reuse);
   if ("error" in reuse) return json({ error: reuse.error }, 400);
+  let runBudgetMs: number | undefined;
+  if (body.runBudgetMs !== undefined) {
+    const value = body.runBudgetMs;
+    if (typeof value !== "number" || !Number.isSafeInteger(value) || value <= 0 || value > DAY_MS)
+      return json({ error: "invalid run budget" }, 400);
+    runBudgetMs = value;
+  }
+  const runId = body.runId;
+  if (runId !== undefined && (typeof runId !== "string" || runId.length === 0 || runId.length > 128))
+    return json({ error: "invalid run id" }, 400);
+  const ownerGen = body.ownerGen;
+  if (ownerGen !== undefined && (typeof ownerGen !== "string" || ownerGen.length === 0 || ownerGen.length > 128))
+    return json({ error: "invalid run generation" }, 400);
+  const ownerFence = body.ownerFence;
+  if (
+    ownerFence !== undefined &&
+    (typeof ownerFence !== "number" || !Number.isSafeInteger(ownerFence) || ownerFence <= 0)
+  )
+    return json({ error: "invalid run fence" }, 400);
+  if (ownerFence !== undefined && (runId === undefined || ownerGen === undefined))
+    return json({ error: "run fence requires a run id and generation" }, 400);
   // Why the hint is what it is (item 16): the thread's own pull request and
   // its head branch — the branch checked against the one ref pattern like
   // every ref, before it can become a git argument — and the bound-by-default flag.
@@ -10050,6 +10353,10 @@ async function handleAttach(env: Env, body: Record<string, unknown>, traceparent
         traceparent,
         reason,
         githubDoor,
+        runBudgetMs,
+        runId,
+        ownerGen,
+        ownerFence,
       ),
     ),
     ({ result, levels }) => ({ ...(result as object), ...(levels ? { levels } : {}) }),
@@ -10057,6 +10364,29 @@ async function handleAttach(env: Env, body: Record<string, unknown>, traceparent
   );
 }
 
+async function handleRunDeadline(env: Env, body: Record<string, unknown>): Promise<Response> {
+  const ctx = await resolveThreadRoute(env, body);
+  if (ctx instanceof Response) return ctx;
+  const runId = body.runId;
+  const ownerGen = body.ownerGen;
+  const ownerFence = body.ownerFence;
+  const remainingMs = body.remainingMs;
+  if (typeof runId !== "string" || runId.length === 0 || runId.length > 128)
+    return json({ error: "invalid run id" }, 400);
+  if (ownerGen !== undefined && (typeof ownerGen !== "string" || ownerGen.length === 0 || ownerGen.length > 128))
+    return json({ error: "invalid run generation" }, 400);
+  if (
+    ownerFence !== undefined &&
+    (typeof ownerFence !== "number" || !Number.isSafeInteger(ownerFence) || ownerFence <= 0)
+  )
+    return json({ error: "invalid run fence" }, 400);
+  if (typeof remainingMs !== "number" || !Number.isSafeInteger(remainingMs) || remainingMs <= 0 || remainingMs > DAY_MS)
+    return json({ error: "invalid remaining lease" }, 400);
+  const result = await ctx.stub.updateRunDeadline(ctx.threadKey, runId, remainingMs, ownerGen, ownerFence);
+  if ("error" in result) return threadErrResponse(result);
+  return json(result);
+}
+
 /** POST /await-restore (docs/reference/specs/execution.md item 27): the bot's
  *  one held request while the resident restores. Held server-side by the DO's
  *  waiter ledger; the answer streams like /attach (heartbeat whitespace then
@@ -10078,6 +10408,18 @@ async function handleAwaitRestore(env: Env, body: Record<string, unknown>): Prom
 async function handleDetach(env: Env, body: Record<string, unknown>): Promise<Response> {
   const ctx = await resolveThreadRoute(env, body);
   if (ctx instanceof Response) return ctx;
+  const runId = body.runId;
+  if (runId !== undefined && (typeof runId !== "string" || runId.length === 0 || runId.length > 128))
+    return json({ error: "invalid run id" }, 400);
+  const ownerGen = body.ownerGen;
+  if (ownerGen !== undefined && (typeof ownerGen !== "string" || ownerGen.length === 0 || ownerGen.length > 128))
+    return json({ error: "invalid run generation" }, 400);
+  const ownerFence = body.ownerFence;
+  if (
+    ownerFence !== undefined &&
+    (typeof ownerFence !== "number" || !Number.isSafeInteger(ownerFence) || ownerFence <= 0)
+  )
+    return json({ error: "invalid run fence" }, 400);
   // What the run pushed (item 16a), each ref through the one ref pattern
   // before it can be stored or become a git argument.
   const pushed = parsePushed(body.pushed);
@@ -10086,7 +10428,14 @@ async function handleDetach(env: Env, body: Record<string, unknown>): Promise<Re
     const ref = parseRef(entry.ref, "pushed[].ref");
     if ("error" in ref) return json({ error: ref.error }, 400);
   }
-  const result = await ctx.stub.detachThread(ctx.threadKey, body.force === true, pushed.pushed);
+  const result = await ctx.stub.detachThread(
+    ctx.threadKey,
+    body.force === true,
+    pushed.pushed,
+    runId,
+    ownerGen,
+    ownerFence,
+  );
   if ("error" in result) return threadErrResponse(result);
   return json(result);
 }