@coreplane/switchboard 1.236.0 → 1.237.0

package/dist/assets/src/core/authz/types.ts

@@ -47,6 +47,16 @@ export interface Actor {
   readonly onBehalfOf?: Actor;
   /** Where a chat actor is speaking from — context, never authority. */
   readonly origin?: { readonly channelId: string; readonly threadKey: string };
+  /**
+   * The ids that mean "me" for this actor (record 0042): its own `id` first,
+   * then the person it is linked to — a dashboard session whose Access email
+   * names one Slack user carries that `slack:U…` id here. Read by `is-self`,
+   * `acts-as-person`, the `me` tier and the "mine" filters; NEVER by a grant
+   * check — the link is identity, not authority. Absent → `[id]`.
+   */
+  readonly self?: readonly string[];
+  /** The linked person, for display and the audit line (`asUser`); absent when unlinked. */
+  readonly asUser?: { readonly id: string; readonly name?: string };
 }
 
 /** `<group>:<read|write|exec>` plus the non-command actions. A plain
@@ -103,8 +113,12 @@ export type Condition =
    *  resource's channel is `public` (a run's stamped `channelVisibility`;
    *  `unknown` is never public). One definition for both evaluators. */
   | { readonly kind: "member-of" }
-  /** resource.userId === actor.id (or the on-behalf-of principal's id). */
+  /** resource.userId is one of the principal's `self` ids (its own id, or the person it is linked to). */
   | { readonly kind: "is-self" }
+  /** The principal's `self` names a chat identity (`slack:U…`): every chat
+   *  actor, and a dashboard session linked to its person (record 0042) — never
+   *  an unlinked browser session or a credential. */
+  | { readonly kind: "acts-as-person" }
   /** actor.grants.repos contains the resource's repo (or is "all"). */
   | { readonly kind: "owner-of" }
   /** actor.grants.channels === "all". */

package/dist/assets/src/core/coordinator/driver.ts

@@ -314,7 +314,11 @@ function prCheckReturn(step: string, a: BotAnswer): StepReturn {
 }
 
 function mergeReturn(step: string, a: BotAnswer): StepReturn {
-  const { ok, outcome, sha, reason, at } = a.body;
+  const { ok, outcome, by, sha, mergedAt, reason, at } = a.body;
+  // The door found the pull request already merged after the approval: the
+  // merge commit and the time ride the answer, and the unit ends `by: other`.
+  if (ok === true && outcome === "merged" && by === "other" && typeof sha === "string" && typeof mergedAt === "string")
+    return { type: "merge", step, outcome: "merged", by: "other", sha, mergedAt, at };
   if (ok === true && outcome === "merged" && typeof sha === "string")
     return { type: "merge", step, outcome: "merged", sha, at };
   if (ok === true && (outcome === "pending" || outcome === "refused") && typeof reason === "string")

package/dist/assets/src/core/runEvents.ts

@@ -76,13 +76,17 @@ export type RunNoteKind =
    *  wait had refused; on pi the container is provisioned before pi starts, so
    *  the note is a record fact from before the loop's deletion. */
   | "fleet_busy"
-  /** The container the run's pi ran in was replaced under the live run
+  /** The container the run's process ran in was replaced under the live run
    *  (docs/reference/specs/harness-pi.md item 16; the resident's roll,
-   *  resident-repos.md item 65): the harness settled the call in flight with
-   *  the restart note, the summary names both containers, and the run ends
-   *  `interrupted` for a restart from its request. On a record from before the
-   *  native loop's deletion the note says that loop's settlement instead: the
-   *  executor waited for the wake and the run went on. */
+   *  resident-repos.md item 65). The harness's note is the verdict: the call
+   *  in flight settled with the restart note, the summary naming both
+   *  containers. The run loop then decides between two outcomes (harness.md
+   *  item 6): a relaunch in the replacement, said in a `resumed` note, or —
+   *  the relaunch refused by name, the ceiling among them — a second note of
+   *  this kind saying why and that the run closes `interrupted` for a restart
+   *  from its request. On a record from before the native loop's deletion the
+   *  note says that loop's settlement instead: the executor waited for the
+   *  wake and the run went on. */
   | "sandbox_restarted"
   | "stop_requested"
   | "stopped"

package/dist/assets/src/core/ship/coordinator.ts

@@ -145,6 +145,14 @@ export function unitBranch(planId: string, slug: string): string {
   return `plan/${planId}/${slug}`;
 }
 
+/** Whether `ref` is a unit branch of ship's own — `plan/<plan-id>/<unit-slug>`.
+ *  A thread keeps the binding its last run opened a pull request on, so after
+ *  a plan's unit it sits at that unit branch; a fresh task there must not take
+ *  it as the base (the pull request would target the earlier unit). */
+export function isUnitBranch(ref: string): boolean {
+  return /^plan\/[^/]+\/[^/]+$/.test(ref);
+}
+
 /** The plan and unit a head branch names, or undefined for any other branch — the merge grant's line. */
 export function parsePlanBranch(branch: string): { planId: string; unitSlug: string } | undefined {
   const m = PLAN_BRANCH.exec(branch);
@@ -496,6 +504,9 @@ export type StepReturn =
   | { type: "read-record"; step: string; run: ChildFacts; at: number }
   | { type: "pr-check"; step: string; pr: PrCheck; at: number }
   | { type: "merge"; step: string; outcome: "merged"; sha: string; at: number }
+  // The door found the pull request already merged after the approval — auto-merge
+  // fired, or a person merged — so the runner merged nothing (`by: other`).
+  | { type: "merge"; step: string; outcome: "merged"; by: "other"; sha: string; mergedAt: string; at: number }
   | { type: "merge"; step: string; outcome: "pending" | "refused"; reason: string; at: number }
   | { type: "sleep"; step: string };
 
@@ -1260,7 +1271,18 @@ export function applyReturn(s: UnitPipelineState, ret: StepReturn): Transition {
     case "merge": {
       const r = ret as Extract<StepReturn, { type: "merge" }>;
       if (r.outcome === "merged")
-        return end(clocked, { kind: "merged", by: "runner", pr: p.pr, sha: r.sha, reviewRounds: s.reviewRounds });
+        // Found already merged at the door — auto-merge or a person, after the
+        // approval: the unit is done, the runner merged nothing (`by: other`).
+        return "by" in r
+          ? end(clocked, {
+              kind: "merged",
+              by: "other",
+              pr: p.pr,
+              sha: r.sha,
+              mergedAt: r.mergedAt,
+              reviewRounds: s.reviewRounds,
+            })
+          : end(clocked, { kind: "merged", by: "runner", pr: p.pr, sha: r.sha, reviewRounds: s.reviewRounds });
       if (r.outcome === "refused")
         return end(clocked, { kind: "merge_refused", pr: p.pr, reason: r.reason, reviewRounds: s.reviewRounds });
       const waited = r.at - p.since;

package/dist/assets/src/execution/residentDepsStore.ts

@@ -299,6 +299,14 @@ export function parseDepsStoreListing(stdout: string): DepsStoreListing {
  *  attaches. Raise with the instance, never by feel. */
 export const DEPS_STORE_MAX_UNREFERENCED = 1;
 
+/** How many spares the attach's disk-pressure path keeps: none. A spare is a
+ *  warm cache for a lockfile key no live tree references, worth minutes on
+ *  the next attach at that key; a tree refused for want of space is a run
+ *  falling to a cold sandbox now. Under pressure the spare goes first, before
+ *  any idle tree (docs/reference/specs/resident-repos.md item 55), and its
+ *  entry backup with it — the next attach at that key restores or installs. */
+export const DEPS_STORE_MAX_UNREFERENCED_UNDER_PRESSURE = 0;
+
 /** Eviction candidates coldest first. Never a protected key (the checkout's,
  *  a live binding's, an install in flight). Debris — an incomplete entry
  *  with nothing in flight for it — is always first: it is half an install
@@ -318,6 +326,9 @@ export interface DepsEvictionPlan {
   remove: string[];
   /** Keys that stay, for the log. */
   keep: string[];
+  /** The entries `remove` names (debris first, then the coldest spares), with
+   *  their measured sizes — what a pressure eviction gives back. */
+  evicted: DepsStoreEntry[];
 }
 
 export function planDepsEviction(input: {
@@ -336,7 +347,8 @@ export function planDepsEviction(input: {
   const evictSpares = spares.slice(0, Math.max(0, spares.length - max));
   const remove = [...debris, ...evictSpares].map((e) => depsEntryPath(e.key, storeDir));
   remove.push(...input.leftovers);
-  const removed = new Set([...debris, ...evictSpares].map((e) => e.key));
+  const evicted = [...debris, ...evictSpares];
+  const removed = new Set(evicted.map((e) => e.key));
   const keep = input.entries.filter((e) => !removed.has(e.key)).map((e) => e.key);
-  return { remove, keep };
+  return { remove, keep, evicted };
 }

package/dist/assets/src/execution/residentDiskBudget.ts

@@ -151,9 +151,19 @@ export { parseDfKiB };
 // ---------------------------------------------------------------------------
 
 /** The refresh cycle snapshots mirror + checkout to R2 through the Sandbox
- *  SDK (`createBackup`); whether it stages a tarball on local disk is
- *  SDK-internal, so the budget holds room for one compressed copy of what it
- *  archives — the same ratio `instanceSizing.test.ts` sizes the instance with. */
+ *  SDK (`createBackup`), which stages each archive on the container's own disk
+ *  (`/var/backups/<id>.sqsh`, lz4 squashfs) before the upload and removes it
+ *  after, the pair concurrently — so the budget holds room for one compressed
+ *  copy of what the cycle archives, at the ratio `instanceSizing.test.ts` sizes
+ *  the instance with. Since item 61 PR B the checkout archive EXCLUDES
+ *  node_modules (`CHECKOUT_SNAPSHOT_EXCLUDES`): the deps are not in the
+ *  cycle's staging. The deps-store entry has its own archive, taken once per
+ *  lockfile key right after the entry is committed, and that one IS staged
+ *  from the deps — the reserve counts it only while such a backup is in
+ *  flight (`depsBackupInFlight`), never as a standing charge. Before this,
+ *  the standing term multiplied the deps too: on a resident whose deps are
+ *  6.9 GiB of an 8.3 GiB archived set, five gigabytes were held for an archive
+ *  of about one, and every attach was refused with 6.7 GiB free. */
 export const SNAPSHOT_STAGING_RATIO = 0.6;
 
 /** The fixed floor under the staging term: at least 1 GiB, or 5 % of the disk
@@ -173,13 +183,26 @@ export interface DiskReserve {
   totalKiB: number;
 }
 
+/** What the reserve knows beyond the sample: whether a deps-store entry
+ *  backup is being taken right now (item 61), whose archive is staged from
+ *  the deps and so needs their share of the ratio while it runs. */
+export interface DiskReserveInput {
+  depsBackupInFlight?: boolean;
+}
+
 /** `staging + floor`. Staging is computed from the MEASURED mirror and
- *  checkout (deps + rest); an unmeasured part counts as 0 there — the floor
- *  still stands, and `projectThreadCostKiB` refuses to project from missing
- *  parts, so an unmeasured resident never admits on a guess. */
-export function diskReserveKiB(sample: Pick<DiskSample, "totalKiB" | "parts">): DiskReserve {
-  const archived = (sample.parts.mirror ?? 0) + (sample.parts.deps ?? 0) + (sample.parts.checkout ?? 0);
-  const stagingKiB = Math.round(archived * SNAPSHOT_STAGING_RATIO);
+ *  checkout (the checkout's own bytes: history + tree + build output, never
+ *  the deps, which the checkout archive excludes), plus the deps while a
+ *  deps-store entry backup is in flight; an unmeasured part counts as 0 there
+ *  — the floor still stands, and `projectThreadCostKiB` refuses to project
+ *  from missing parts, so an unmeasured resident never admits on a guess. */
+export function diskReserveKiB(
+  sample: Pick<DiskSample, "totalKiB" | "parts">,
+  input: DiskReserveInput = {},
+): DiskReserve {
+  const staged = (sample.parts.mirror ?? 0) + (sample.parts.checkout ?? 0);
+  const depsStaged = input.depsBackupInFlight ? (sample.parts.deps ?? 0) : 0;
+  const stagingKiB = Math.round((staged + depsStaged) * SNAPSHOT_STAGING_RATIO);
   const floorKiB = Math.max(DISK_FLOOR_MIN_KIB, Math.round(sample.totalKiB * DISK_FLOOR_FRACTION));
   return { stagingKiB, floorKiB, totalKiB: stagingKiB + floorKiB };
 }
@@ -261,11 +284,14 @@ export function checkDiskAdmission(input: {
   committedKiB?: number;
   diskBudgetMb?: number;
   kind: ThreadCostKind;
+  /** A deps-store entry backup is in flight: its archive is staged from the
+   *  deps, so the reserve holds their share for as long as it runs. */
+  depsBackupInFlight?: boolean;
 }): AdmissionVerdict {
   const rawFree = Math.max(0, (input.freeKiB ?? input.sample.freeKiB) - (input.committedKiB ?? 0));
   const live = { ...input.sample, freeKiB: rawFree, usedKiB: input.sample.totalKiB - rawFree };
   const { capacityKiB, freeKiB, capped } = effectiveFreeKiB(live, input.diskBudgetMb);
-  const reserve = diskReserveKiB(input.sample);
+  const reserve = diskReserveKiB(input.sample, { depsBackupInFlight: input.depsBackupInFlight });
   const projectedKiB = projectThreadCostKiB(input.sample.parts, input.kind);
   const headroomKiB = freeKiB - reserve.totalKiB - (projectedKiB ?? 0);
   const math: AdmissionMath = { projectedKiB, kind: input.kind, freeKiB, capacityKiB, capped, reserve, headroomKiB };
@@ -401,6 +427,9 @@ export function diskPressureReason(input: {
   verdict: Extract<AdmissionVerdict, { fits: false }>;
   evicted: ReadonlyArray<{ freedKiB: number | null }>;
   kept: ReadonlyArray<{ why: DiskKeepWhy }>;
+  /** Deps-store spares removed first under the pressure (item 55), with the
+   *  bytes each gave back. */
+  spares?: ReadonlyArray<{ freedKiB: number }>;
 }): string {
   const { math } = input.verdict;
   const need =
@@ -412,10 +441,15 @@ export function diskPressureReason(input: {
     `${DISK_PRESSURE_REASON}: need ${need}, but ${formatGiB(math.freeKiB)} free${cap} minus the ${formatGiB(math.reserve.totalKiB)} reserve ` +
       `(snapshot staging ${formatGiB(math.reserve.stagingKiB)} + floor ${formatGiB(math.reserve.floorKiB)}) leaves ${formatGiB(Math.max(0, math.freeKiB - math.reserve.totalKiB))} — short by ${formatGiB(input.verdict.shortfallKiB)}`,
   ];
+  const spares = input.spares ?? [];
+  if (spares.length > 0) {
+    const freed = spares.reduce((a, e) => a + e.freedKiB, 0);
+    parts.push(`evicted ${spares.length} deps-store spare(s) (${formatGiB(freed)} back)`);
+  }
   if (input.evicted.length > 0) {
     const freed = input.evicted.reduce((a, e) => a + (e.freedKiB ?? 0), 0);
     parts.push(`evicted ${input.evicted.length} idle tree(s) (${formatGiB(freed)} back)`);
-  } else parts.push("evicted nothing");
+  } else parts.push(spares.length > 0 ? "evicted no idle tree" : "evicted nothing");
   if (input.kept.length > 0) {
     const counts = new Map<DiskKeepWhy, number>();
     for (const k of input.kept) counts.set(k.why, (counts.get(k.why) ?? 0) + 1);

package/dist/assets/src/execution/residentHead.ts

@@ -42,19 +42,45 @@ export function wantShaForBinding(input: {
   return input.wantSha;
 }
 
-/** Whether the attach must fetch the mirror before cloning the thread tree.
- *  - the ref is not in the mirror → fetch (the only pre-existing rule);
+/** Why the attach fetches the mirror before cloning the thread tree. The
+ *  Worker treats the three differently when the fetch fails: a `missing-ref`
+ *  or `stale-tip` fetch that fails fails the attach, as it always did; a
+ *  `returnable-ref` fetch only verifies a ref the mirror holds, so its
+ *  failure is one log line and the attach goes on with the mirror's ref. */
+export type FetchReason = "missing-ref" | "stale-tip" | "returnable-ref";
+
+/** Whether — and why — the attach must fetch the mirror before cloning the
+ *  thread tree; null when the mirror is good enough as it stands.
+ *  - the ref is not in the mirror → `missing-ref` (the oldest rule);
  *  - a `wantSha` was named and the mirror's tip of the ref is not that
- *    commit → fetch;
- *  - otherwise the mirror is good enough as it stands.
+ *    commit → `stale-tip`;
+ *  - the bound ref is one the binding could return from — a branch a rebind
+ *    moved it onto, or one the thread's own runs pushed (`canReturnToDefault`,
+ *    resident-repos.md item 16) → `returnable-ref`: such a branch dies when
+ *    its pull request merges, and the deletion reaches the mirror only through
+ *    a `fetch --prune`. Trusting the mirror because it still holds the ref
+ *    would provision a tree at the deleted branch's stale tip until the
+ *    refresh cycle's prune caught up — whether the thread returned to the
+ *    default would depend on where in the cycle its follow-up landed. So the
+ *    ref is verified against the origin at every attach, and the return is
+ *    decided at the first attach after the deletion. The default cannot be
+ *    lost and a ref a person named that the thread never pushed has no way
+ *    back, so neither pays this fetch: the refresh cycle is their freshness.
+ *  - otherwise null.
  *  A fetch that STILL leaves the tip elsewhere (a push racing this attach, or
  *  a force-push) is not this function's concern: the attach proceeds on the
  *  fetched tip and reports it, and the reviewed-head guard decides what a
  *  review of it may do. */
-export function mirrorNeedsFetch(input: { refExists: boolean; mirrorSha?: string; wantSha: string | null }): boolean {
-  if (!input.refExists) return true;
-  if (input.wantSha === null) return false;
-  return input.mirrorSha !== input.wantSha;
+export function mirrorFetchReason(input: {
+  refExists: boolean;
+  mirrorSha?: string;
+  wantSha: string | null;
+  returnable: boolean;
+}): FetchReason | null {
+  if (!input.refExists) return "missing-ref";
+  if (input.wantSha !== null && input.mirrorSha !== input.wantSha) return "stale-tip";
+  if (input.returnable) return "returnable-ref";
+  return null;
 }
 
 /** What the attach checks out, once the mirror is as fresh as it will get. */

package/dist/assets/src/execution/residentRebind.ts

@@ -35,15 +35,21 @@
  *  Every refusal is named in the attach answer so the bot can say why the
  *  follow-up runs where it does.
  *
- *  The second movement: a rebound binding names a branch that can die — the
- *  pull request merges and the branch is deleted. A binding left on it would
- *  fail every later attach (`unknown-ref`) for the thread's whole life. So a
- *  binding a rebind moved, whose branch the mirror no longer holds after a
- *  fetch, goes back to the default it was bound to (`canReturnToDefault`,
- *  `returnToDefault`); the attach provisions the tree there, clean, and the
- *  thread is default-bound again, so a later own pull request may move it once
- *  more. A ref a person named that vanished keeps the `unknown-ref` refusal:
- *  that branch is the person's to sort out. */
+ *  The second movement: a binding can sit on a branch that dies — the pull
+ *  request merges and the branch is deleted. A binding left on it would fail
+ *  every later attach (`unknown-ref`) for the thread's whole life. So a
+ *  binding whose ref the mirror no longer holds after a fetch goes back to the
+ *  default (`canReturnToDefault`, `returnToDefault`) when the gone ref is
+ *  EITHER the branch a rebind moved it onto OR one of the thread's own
+ *  branches — a branch this thread's runs pushed (`ownBranches`), whatever
+ *  `boundBy` says: a ship unit's coding child binds its unit branch by name,
+ *  pushes it and opens the pull request, and the unit's merge deletes it. The
+ *  attach provisions the tree at the default, clean, and the thread is
+ *  default-bound again (`boundBy: default` — the default was chosen for want
+ *  of the branch it was on), so a later own pull request may move it once
+ *  more. A ref a person named that the thread never pushed keeps the
+ *  `unknown-ref` refusal: a person's branch that is gone is not this thread's
+ *  finished work, and the resident never swaps it for the default unasked. */
 
 /** The pull request the thread's own run opened, and its head branch — the
  *  reason a caller's refHint is that branch. */
@@ -136,9 +142,15 @@ export function rememberOwnBranches(
   return [...kept, ...added].slice(-OWN_BRANCHES_MAX);
 }
 
+/** The binding's memory of `ref` as a branch the thread's own runs pushed —
+ *  the pull request it heads and when it was told — or none. */
+export function ownBranchOf(binding: { ownBranches?: readonly OwnBranch[] }, ref: string): OwnBranch | undefined {
+  return (binding.ownBranches ?? []).find((b) => b.ref === ref);
+}
+
 /** Whether the thread's own runs pushed `ref`, as the binding remembers it. */
 export function isOwnBranch(binding: { ownBranches?: readonly OwnBranch[] }, ref: string): boolean {
-  return (binding.ownBranches ?? []).some((b) => b.ref === ref);
+  return ownBranchOf(binding, ref) !== undefined;
 }
 
 /** How a binding's ref was chosen: the repo default for want of a named
@@ -171,8 +183,12 @@ export interface Rebound {
   returnedAt?: string;
 }
 
-/** The move back, in the attach answer: from the branch that is gone, to the
- *  default, for the pull request whose branch it was, when. */
+/** The move back (the second movement), on the binding and in the attach
+ *  answer: from the branch that is gone, to the default, for the pull request
+ *  whose branch it was — the rebind's, or the one the binding remembers the
+ *  branch heading — when. On the binding it is the LAST move back: a rebind's
+ *  own record keeps its `returnedAt` beside it, and a binding never rebound
+ *  (its unit branch bound by name and pushed) has only this. */
 export interface Returned {
   from: string;
   to: string;
@@ -199,6 +215,8 @@ export interface RebindableBinding {
   evicted?: boolean;
   boundBy?: BoundBy;
   rebound?: Rebound;
+  /** The binding's last move back to the default (the second movement). */
+  returned?: Returned;
   /** The branches the thread's own runs pushed, handed over at each release. */
   ownBranches?: OwnBranch[];
 }
@@ -320,29 +338,68 @@ export function rebindVerdict(plan: { to: string; pr: number; own?: boolean }, t
   return { kind: "rebind" };
 }
 
-/** Whether a binding whose ref the mirror no longer holds goes back to the
- *  default branch (the second movement): only a binding a rebind moved onto
- *  its own pull request's branch — bound by default in the first place, still
- *  on that branch, the move not yet returned. Anything else keeps the
- *  attach's `unknown-ref` refusal: a ref a person named is that person's to
- *  sort out, and a binding on the default cannot lose its ref. */
-export function canReturnToDefault(
-  binding: { ref: string; boundBy?: BoundBy; rebound?: Rebound },
+/** What the second movement reads off a binding. */
+export type ReturnableBinding = Pick<RebindableBinding, "ref" | "boundBy" | "rebound" | "ownBranches">;
+
+/** The way back a binding whose ref is gone may take, if any — the one place
+ *  the second movement is decided, so the predicate and the move cannot
+ *  disagree: `rebind` — a rebind moved the binding onto the branch (bound by
+ *  default in the first place, still on that branch, the move not yet
+ *  returned); `own` — the branch is one this thread's own runs pushed, as the
+ *  binding remembers it, whatever `boundBy` says. A binding on the default
+ *  cannot lose its ref, and a ref a person named that the thread never pushed
+ *  has no way back: that branch is the person's to sort out. */
+function wayBack(
+  binding: ReturnableBinding,
   defaultRef: string,
-): boolean {
+): { kind: "rebind"; rebound: Rebound } | { kind: "own"; branch: OwnBranch } | undefined {
+  if (binding.ref === defaultRef) return undefined;
   const r = binding.rebound;
-  if (r === undefined || r.returnedAt !== undefined || binding.ref !== r.to) return false;
-  return binding.ref !== defaultRef && boundByOf(binding, defaultRef) === "default";
+  if (
+    r !== undefined &&
+    r.returnedAt === undefined &&
+    binding.ref === r.to &&
+    boundByOf(binding, defaultRef) === "default"
+  ) {
+    return { kind: "rebind", rebound: r };
+  }
+  const branch = ownBranchOf(binding, binding.ref);
+  return branch === undefined ? undefined : { kind: "own", branch };
+}
+
+/** Whether a binding whose ref the mirror no longer holds goes back to the
+ *  default branch (the second movement): a binding a rebind moved onto its
+ *  own pull request's branch, or one on a branch this thread itself pushed.
+ *  Anything else keeps the attach's `unknown-ref` refusal. */
+export function canReturnToDefault(binding: ReturnableBinding, defaultRef: string): boolean {
+  return wayBack(binding, defaultRef) !== undefined;
 }
 
-/** The move back: the binding's ref becomes the default and the move that
- *  brought it here is stamped returned, so the thread may move again. Only
- *  ever applied to a binding `canReturnToDefault` admitted. */
-export function returnToDefault<B extends { ref: string; rebound?: Rebound }>(
-  binding: B & { rebound: Rebound },
+/** The move back: the binding's ref becomes the default, the binding reads as
+ *  bound by default (the default was chosen for want of the branch it was on,
+ *  so its next own pull request may move it — a binding that named its unit
+ *  branch included), a rebind's move is stamped returned, and the last move
+ *  back is recorded. The pull request named is the rebind's, else the one the
+ *  binding remembers the gone branch heading. Undefined for a binding
+ *  `canReturnToDefault` does not admit: nothing to write. */
+export function returnToDefault<B extends ReturnableBinding>(
+  binding: B,
   defaultRef: string,
   at: string,
-): { binding: B; returned: Returned } {
-  const returned: Returned = { from: binding.ref, to: defaultRef, pr: binding.rebound.pr, at };
-  return { binding: { ...binding, ref: defaultRef, rebound: { ...binding.rebound, returnedAt: at } }, returned };
+): { binding: B; returned: Returned } | undefined {
+  const way = wayBack(binding, defaultRef);
+  if (way === undefined) return undefined;
+  const pr = way.kind === "rebind" ? way.rebound.pr : way.branch.pr;
+  const returned: Returned = { from: binding.ref, to: defaultRef, pr, at };
+  const rebound = way.kind === "rebind" ? { ...way.rebound, returnedAt: at } : binding.rebound;
+  return {
+    binding: {
+      ...binding,
+      ref: defaultRef,
+      boundBy: "default",
+      ...(rebound !== undefined ? { rebound } : {}),
+      returned,
+    },
+    returned,
+  };
 }

package/dist/assets/src/execution/sandboxLifecycle.ts

@@ -76,3 +76,36 @@ export function recycledMidCommandMessage(elapsedMs: number, msg: string, certai
     `check /workspace before continuing: it is empty if the container was replaced (re-clone), intact if only its runtime restarted (${msg})`
   );
 }
+
+/** The redirects a detached job's wrapper must carry so the command that
+ *  forked it owns none of its descriptors — the same string the harness seam
+ *  uses for its own start (`DETACHED_STDIO` in src/core/harness/container.ts;
+ *  a test holds the two equal). Without them the runtime waits for an end of
+ *  output the detached child never gives (item 24). */
+export const DETACH_REDIRECTS = "</dev/null >/dev/null 2>&1";
+
+/** The way a command detaches a job that must outlive it, as the exit-124
+ *  hint and the docs spell it: the job's own output into a file, the
+ *  wrapper's stdio to /dev/null. */
+export const DETACH_HINT = `setsid -f sh -c '<command> > /tmp/job.log 2>&1' ${DETACH_REDIRECTS}`;
+
+/** How long past the process's exit the Durable Object waits for its output
+ *  stream to end before it answers with the exit code alone. The runtime
+ *  reports the stream's end only when every holder of the command's stdout
+ *  and stderr is gone; a detached child that inherited them holds it open
+ *  for its own lifetime. Twenty seconds covers coreutils `timeout -k 10`'s
+ *  SIGKILL follow-up and the runtime's teardown, and stays inside the
+ *  executor's per-send margin (EXEC_CALL_MARGIN_MS, 30 s) so this answer
+ *  reaches the bot before it gives the command up. */
+export const OUTPUT_AFTER_EXIT_MS = 20_000;
+
+/** The stderr line an exec answers with when its process exited but its
+ *  output never ended: what happened, why the output is missing, and how to
+ *  detach a job so it does not happen again. */
+export function heldOutputNote(exitCode: number): string {
+  return (
+    `the command exited (code ${exitCode}) but its output could not be collected: a process it started still holds its stdout or stderr open ` +
+    `(a background job started without redirecting the wrapper's own stdio); its output is lost to this call, the job itself is still running — ` +
+    `detach with \`${DETACH_HINT}\` so the command's descriptors close when it does`
+  );
+}