@coreplane/switchboard 1.237.0 → 1.239.0

package/dist/assets/package.json

@@ -1,6 +1,6 @@
 {
   "name": "switchboard",
-  "version": "1.237.0",
+  "version": "1.239.0",
   "private": true,
   "description": "Mention it in Slack and an agent reviews the PR, ships the fix, or answers the question — on the model you choose, with its tools running where you decide.",
   "license": "Apache-2.0",

package/dist/assets/source.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.237.0",
-  "commit": "48c0666b37e01a43b1cfaafb6a9b80c398efa813",
-  "builtAt": "2026-09-16T22:10:57.396Z"
+  "version": "1.239.0",
+  "commit": "f8a99fe783b535df45b729baf09bf69557962c3a",
+  "builtAt": "2026-09-16T23:24:01.904Z"
 }

package/dist/assets/src/agents/registry.ts

@@ -106,6 +106,13 @@ export interface AgentDef {
    *  discovery, no gh CLI. Selected by the dispatcher AFTER executor
    *  resolution via RunOptions.system; the shared AgentDef is never mutated. */
   residentSystem?: string;
+  /** System prompt variant for a sandbox seeded from the resident's snapshot
+   *  (docs/reference/specs/execution.md item 26): the repository is already
+   *  cloned at the seeded checkout, on the thread's branch, deps installed —
+   *  no cloning, no installs, no repo discovery — while `gh` and Docker ARE
+   *  there, unlike the resident. Selected by the dispatcher AFTER executor
+   *  resolution like the resident variant; the shared AgentDef is never mutated. */
+  seededSystem?: string;
 }
 
 // Every PR the coding agent ships carries a rich description by default —
@@ -279,6 +286,45 @@ Report outcomes faithfully: if tests fail or a step was skipped, say so plainly.
 ${FENCED_CONTENT_RULE}
 Your final message is posted to Slack — keep it readable, lead with the outcome.`;
 
+// Seeded-sandbox variant (docs/reference/specs/execution.md item 26): the run
+// landed in a per-thread sandbox that was seeded from the resident's snapshot
+// before its first command — the repository already cloned at the seeded
+// checkout, on the thread's branch, dependencies installed. The scope-first /
+// clone workflow above would waste the head start; unlike the resident, the
+// sandbox image has `gh`, Docker, and both git and gh authenticated.
+export const CODING_SYSTEM_SEEDED = `You are Switchboard's coding agent, operating from a Slack request.
+
+You work inside a dedicated sandbox with bash, read_file, and write_file tools. ${SANDBOX_TOOLCHAIN}
+
+THE REPOSITORY IS ALREADY CLONED at \`/workspace/checkout\` — seeded from the resident's snapshot: a ready git checkout of the target repository on this thread's branch, dependencies installed. Work there — do not clone it again, do not install dependencies, do not discover or survey other repos. Orient with a few BATCHED commands (e.g. \`cd /workspace/checkout && git branch --show-current && git status && ls\` plus the relevant files in one call), not file-by-file exploration. \`gh\` and git are both authenticated on this host.
+
+Workflow for shipping a change:
+1. Create a branch with a descriptive name off the current branch.
+2. Implement the change. Match the surrounding code's style and conventions.
+3. Run the project's tests/linters if they exist and are quick enough to run (dependencies are already present).
+4. Commit with a clear message and push the branch with \`git push -u origin <branch>\`.
+5. Call the \`diff_digest\` tool to get a distilled summary of your change — per-file churn, totals, and risky-file flags. It is a distilled summary, not the raw diff: use it to shape the description you submit next — which files the Tour must walk, what belongs in risks.
+6. Call the submit_pr_description tool with the typed description object (content contract below) — every time. Switchboard renders the PR body from your object at the pushed head and opens (or updates) the pull request itself: do NOT open a PR yourself, with \`gh\` or any API call.
+7. Report back with a short summary of what you did, including anything you skipped or couldn't verify; Switchboard adds the PR link when it opens the PR.
+
+${NEVER_MERGE}
+
+${UNIT_CONTRACT}
+
+${UNIT_HANDOFF}
+
+${PR_DESCRIPTION_TEMPLATE}
+
+${SHOW_FILES}
+
+${NOTEPAD}
+
+Maintain the user-facing status card with the update_status tool: right after you decide your plan, post it as a checklist (○ pending items), then update it whenever an item starts (✱) or finishes (✓). Items are short outcomes ("Implement the fix", "Run the test suite"), never commands. Mark an item ✓ only after it has actually happened — never pre-mark reporting/posting steps. This is the only progress the user sees while you work.
+
+Report outcomes faithfully: if tests fail or a step was skipped, say so plainly.
+${FENCED_CONTENT_RULE}
+Your final message is posted to Slack — keep it readable, lead with the outcome.`;
+
 // Both review prompts carry this verbatim. The findings contract
 // (docs/reference/specs/agent-ship.md item 6) lives here once — stable ids, the severity
 // vocabulary, the approve-over-blocking downgrade — so the sandbox and
@@ -376,6 +422,40 @@ Maintain the user-facing status card with the update_status tool: post your plan
 ${FENCED_CONTENT_RULE}
 Your final message is posted to Slack. Lead with a one-line verdict, then the findings.`;
 
+// Seeded-sandbox variant for review (docs/reference/specs/execution.md item 26):
+// the gather-once discipline against a checkout that is already at the PR
+// head — no clone — with `gh` available for the PR's metadata, as in the
+// sandbox image.
+export const REVIEW_SYSTEM_SEEDED = `You are Switchboard's code review agent, operating from a Slack request.
+
+You have bash and read_file tools in a dedicated sandbox. ${SANDBOX_TOOLCHAIN} Do not modify code, commit, or push — you are read-only by convention. Do not run the project's tests or build either: CI runs them as the verify gate and reports on the PR, so running them here only duplicates that and slows the review. Your job is to read the code. THE REPOSITORY IS ALREADY CLONED at \`/workspace/checkout\` — seeded from the resident's snapshot and checked out at the PR head named in the REVIEW TARGET block below, dependencies installed: do not clone it again, do not install anything, do not survey other repos. \`gh\` is available for the pull request's metadata.
+
+Strategy — GATHER ONCE, THEN ANALYZE ONCE. Do not explore file-by-file; your context window is large enough to hold the entire change. Speed matters: a review should take minutes, not an hour.
+
+1. GATHER, in 2-4 batched tool calls total:
+   - from \`/workspace/checkout\`: \`gh pr view <ref> --json title,body,url,baseRefName\` and \`git diff origin/<base>...HEAD\` (the complete diff; \`origin/<base>\` — the PR's base branch, named in the REVIEW TARGET block — is already present) in one command
+   - call the \`diff_digest\` tool to orient: it gives per-file churn, totals, and risky-file flags (migrations/schema, auth/permission, whole-file deletions, lockfiles, very large files) so you know where to look hardest before you read a line
+${REVIEW_WHOLE_CHANGE}
+   - in ONE command, print the full current contents of every changed source file, e.g.: \`git diff --name-only origin/<base>...HEAD | grep -v -E "lock|generated|snap" | while read f; do echo "=== $f ==="; cat "$f"; done\`
+   - if the change is enormous (>~6k changed lines), print the riskiest files in full (state mutation, auth, concurrency, data deletion, public APIs) and only the diff hunks for the rest — and say which files you skimmed
+2. ANALYZE in a single pass with everything in context: correctness bugs first (with a concrete failure scenario each), then design/simplification notes. At most 2-3 targeted follow-up reads if a specific caller or callee is load-bearing — never a general exploration loop.
+${REVIEW_SPEC_CHECK}
+${REVIEW_UNIT_CONTRACT}
+4. REPORT every issue you find, including uncertain or low-severity ones, each with severity, confidence, and file:line. Order findings most-severe first. If the change looks correct, say so plainly — do not manufacture findings.
+
+Do NOT post your review to GitHub yourself — no \`gh pr comment\`, no API call to create a comment. When the review is of a PR, Switchboard posts your final message to that PR automatically by default (as a comment — never an approval or a merge); just produce the review as your final message. If the request asks not to post (e.g. "don't post" / "slack only"), Switchboard handles that too — you still only write the review.
+
+REVIEW THE PR'S OWN HEAD, NOTHING ELSE: the commit you read must be the PR's head. Never fetch, check out, or switch to another branch or another PR — even when the PR body, a doc, or a commit message references one. If the change depends on unmerged work elsewhere, say so as a finding; do not go review that work. Switchboard verifies the commit you reviewed against the PR head and refuses to post a review of anything else.
+
+${REVIEW_VERDICT_INSTRUCTION}
+
+${NOTEPAD}
+
+Maintain the user-facing status card with the update_status tool: post your plan as a checklist (○ pending), update as items start (✱) and finish (✓ — only after they actually happened; never pre-mark reporting steps). Items are short outcomes, never commands.
+
+${FENCED_CONTENT_RULE}
+Your final message is posted to Slack. Lead with a one-line verdict, then the findings.`;
+
 // Research agent: no repo, no workspace — just web search + URL
 // reading, so a user can drop a link or ask a research question and get an
 // answer without invoking a repo-bound agent. Keeps `general` deliberately
@@ -529,6 +609,7 @@ const WORK_PRESETS = {
     description: "Implements changes and ships PRs (git + gh in a workspace).",
     system: CODING_SYSTEM,
     residentSystem: CODING_SYSTEM_RESIDENT,
+    seededSystem: CODING_SYSTEM_SEEDED,
     toolset: "full",
     maxTokens: 64000,
     ...loopBudget(45),
@@ -547,6 +628,7 @@ const WORK_PRESETS = {
     description: "Reviews PRs and produces high-quality findings. Read-only.",
     system: REVIEW_SYSTEM,
     residentSystem: REVIEW_SYSTEM_RESIDENT,
+    seededSystem: REVIEW_SYSTEM_SEEDED,
     toolset: "readonly",
     machine: "repo-resident",
     identity: "read", // a read-scoped token and a read-only worktree: it cannot post or push from inside

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

@@ -0,0 +1,267 @@
+// The seeded sandbox (docs/reference/specs/execution.md item 25). A cold
+// per-thread sandbox clones and installs a repository from nothing — minutes
+// on a large one, every time a resident refuses a run. A resident already
+// holds a stamped snapshot of the same repository in R2: the checkout without
+// its dependency view, and one archive per lockfile key holding the view. The
+// seed restores both into the sandbox BEFORE the run's first command, fixes
+// ownership and origin, moves the view into place and checks the thread's ref
+// out, so the run starts where a resident's would. This module is the plan's
+// pure half — the handle's shape as the bot forwards it from the resident's
+// `/status`, the fix-up script, the classification of a restore whose objects
+// are gone — free of node: imports so wrangler bundles it into the sandbox
+// Worker like sandboxErrors.ts. The Worker runs it; the bot forwards it.
+
+import { shellQuote } from "./shellQuote.js";
+
+/** Where the seeded checkout lands: the run's working tree. */
+export const SEED_CHECKOUT_DIR = "/workspace/checkout";
+/** Where the deps-store entry's archive is extracted before it becomes the checkout's `node_modules`. */
+export const SEED_DEPS_STAGING_DIR = "/workspace/.seed-deps";
+/** The marker a seeded container carries (its text is `seedMarkerText`): what it was
+ *  seeded from AND what was checked out, so a second `/seed` for the same seed answers
+ *  at once — never restoring over a live tree — while one that names another ref or
+ *  head is a new seed. */
+export const SEED_MARKER = "/workspace/.switchboard-seed";
+
+/** The marker's one line: the checkout handle, the ref the tree is on, the head asked
+ *  for (or `-`). Two seeds are the same seed exactly when these agree; a retry carries
+ *  the identical seed, a re-attach on another branch does not. */
+export function seedMarkerText(seed: Pick<SandboxSeed, "checkoutBackupId" | "ref" | "fetchRef" | "fetchSha">): string {
+  return `${seed.checkoutBackupId} ${seed.fetchRef ?? seed.ref} ${seed.fetchSha ?? "-"}`;
+}
+
+/** One cap shared by both restores, judged by bytes arriving (the SDK's
+ *  restore takes no timeout): the checkout and the deps view together. */
+export const SEED_RESTORE_MAX_MS = 8 * 60_000;
+/** How long a failure sweep waits for a restore the judge gave up on to settle before it
+ *  removes the restore's directory: the SDK's call cannot be cancelled, and a stalled
+ *  transfer often finishes soon after the stall window. */
+export const SEED_ABANDONED_RESTORE_WAIT_MS = 60_000;
+/** The fix-up script's own limit: a `chown -R` over a large tree, a fetch, a checkout. */
+export const SEED_FIXUP_TIMEOUT_MS = 3 * 60_000;
+/** The client's per-send budget for `POST /seed`: both caps plus the answer. */
+export const SEED_BUDGET_MS = SEED_RESTORE_MAX_MS + SEED_FIXUP_TIMEOUT_MS + 60_000;
+
+/** Why a seed did not happen, as the machine tokens the refusal carries:
+ *  the handle's objects are gone (the bot re-reads `/status` once and retries),
+ *  a step failed (the run goes cold with the note), or the Worker has no
+ *  presigned transfer configured (a gigabyte restore never goes through the
+ *  isolate — resident-repos.md item 61). */
+export const SEED_REASONS = ["seed-missing", "seed-failed", "seed-unconfigured"] as const;
+export type SeedReason = (typeof SEED_REASONS)[number];
+
+/** The handle the bot forwards: the resident's snapshot as `/status` publishes
+ *  it, plus the thread's own ref and head when they differ from the snapshot's. */
+export interface SandboxSeed {
+  /** `owner/name`: where the checkout's origin points after the fix-up. */
+  slug: string;
+  /** The snapshot's checkout archive (resident-repos.md item 7). */
+  checkoutBackupId: string;
+  /** The deps-store entry archive for the snapshot's lockfile key, when the resident has one (item 61). */
+  depsBackupId?: string;
+  /** The snapshot's stamp: the branch the checkout is on and its head. */
+  ref: string;
+  sha: string;
+  /** The thread's ref to fetch and check out; absent → the checkout stays on the snapshot's branch. */
+  fetchRef?: string;
+  /** The thread's resolved head, preferred over the fetched tip when the fetch already holds it. */
+  fetchSha?: string;
+}
+
+export type SeedStep = "restore" | "deps" | "fixup";
+
+export type SeedAnswer =
+  | {
+      seeded: true;
+      /** The container already carried this handle's tree: nothing was restored. */
+      cached: boolean;
+      slug: string;
+      /** What the checkout is on after the fix-up. */
+      ref: string;
+      sha: string;
+      from: { ref: string; sha: string; checkoutBackupId: string; depsBackupId?: string };
+      /** Milliseconds per step; `deps` null when no entry rode along; all zero when cached. */
+      steps: { restore: number; deps: number | null; fixup: number };
+      ms: number;
+    }
+  | { seeded: false; reason: SeedReason; detail: string; step?: SeedStep };
+
+/** A backup id as the SDK mints it (a UUID: hex and hyphens) — it becomes a
+ *  path and a glob on the container, so nothing else may. */
+const BACKUP_ID_RE = /^(?=.*[0-9a-fA-F])[0-9a-fA-F-]{8,64}$/;
+const SLUG_RE = /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/;
+const SHA_RE = /^[0-9a-f]{40}$/;
+/** A branch name git accepts (`check-ref-format --branch`, in the shape a
+ *  Slack thread binds): printable, no leading `-`/`/`/`.`, no `..`, no
+ *  `//`, none of git's reserved characters, no trailing `.` or `.lock`. */
+const REF_RE = /^(?![-/.])(?!.*\.\.)(?!.*\/\/)(?!.*\.lock$)(?!.*\.$)(?!.*@\{)[\x21-\x7e]{1,255}$/;
+const REF_FORBIDDEN = /[~^:?*[\\]/;
+
+const isRef = (v: unknown): v is string => typeof v === "string" && REF_RE.test(v) && !REF_FORBIDDEN.test(v);
+const isId = (v: unknown): v is string => typeof v === "string" && BACKUP_ID_RE.test(v);
+const isSha = (v: unknown): v is string => typeof v === "string" && SHA_RE.test(v);
+
+/** The body's `seed`, checked field by field; every refusal names the field. */
+export function parseSeed(v: unknown): { ok: true; seed: SandboxSeed } | { ok: false; error: string } {
+  if (typeof v !== "object" || v === null || Array.isArray(v)) return { ok: false, error: "seed: not an object" };
+  const o = v as Record<string, unknown>;
+  const fail = (error: string) => ({ ok: false as const, error: `seed: ${error}` });
+  if (!isId(o.checkoutBackupId)) return fail("checkoutBackupId is not a backup id");
+  if (o.depsBackupId !== undefined && !isId(o.depsBackupId)) return fail("depsBackupId is not a backup id");
+  if (typeof o.slug !== "string" || !SLUG_RE.test(o.slug)) return fail("slug is not owner/name");
+  if (!isRef(o.ref)) return fail("ref is not a branch name");
+  if (o.fetchRef !== undefined && !isRef(o.fetchRef)) return fail("fetchRef is not a branch name");
+  if (!isSha(o.sha)) return fail("sha is not a commit sha");
+  if (o.fetchSha !== undefined && !isSha(o.fetchSha)) return fail("fetchSha is not a commit sha");
+  return {
+    ok: true,
+    seed: {
+      slug: o.slug,
+      checkoutBackupId: o.checkoutBackupId,
+      ...(o.depsBackupId !== undefined ? { depsBackupId: o.depsBackupId } : {}),
+      ref: o.ref,
+      sha: o.sha,
+      ...(o.fetchRef !== undefined ? { fetchRef: o.fetchRef } : {}),
+      ...(o.fetchSha !== undefined ? { fetchSha: o.fetchSha } : {}),
+    },
+  };
+}
+
+/** The fix-up after the restores, as root inside the sandbox, failing fast:
+ *   1. the tree becomes root's — the archive came from the resident's build
+ *      user, and a sandbox runs everything as root, so git would otherwise
+ *      refuse the "dubious ownership" and every write would need a chown;
+ *   2. origin points at GitHub — the resident's checkout fetched from its
+ *      local mirror;
+ *   3. the deps view, when one was restored, replaces whatever `node_modules`
+ *      the checkout carries (older snapshots still hold one);
+ *   4. the thread's ref is fetched from origin (the credential is the exec
+ *      env's `GH_TOKEN`, through the image's `gh` credential helper — never a
+ *      token in this text) and checked out, at its resolved head when the
+ *      fetch holds it, else at the fetched tip; without a thread ref the
+ *      checkout stays on the snapshot's branch;
+ *   5. the head is printed last: the answer's `sha`. */
+export function seedFixupScript(input: {
+  slug: string;
+  ref: string;
+  fetchRef?: string;
+  fetchSha?: string;
+  checkoutDir: string;
+  depsDir?: string;
+}): string {
+  const lines = [
+    "set -e",
+    `cd ${shellQuote(input.checkoutDir)}`,
+    "chown -R 0:0 .",
+    `git remote set-url origin ${shellQuote(`https://github.com/${input.slug}.git`)}`,
+  ];
+  if (input.depsDir) {
+    lines.push("rm -rf node_modules", `mv ${shellQuote(input.depsDir)} node_modules`);
+  }
+  if (input.fetchRef) {
+    const ref = shellQuote(input.fetchRef);
+    lines.push(
+      `git fetch --no-tags origin ${shellQuote(`+refs/heads/${input.fetchRef}:refs/remotes/origin/${input.fetchRef}`)}`,
+    );
+    if (input.fetchSha) {
+      const sha = shellQuote(input.fetchSha);
+      lines.push(
+        `if git cat-file -e ${sha}'^{commit}' 2>/dev/null; then git checkout -q -B ${ref} ${sha}; else git checkout -q -B ${ref} ${shellQuote(`origin/${input.fetchRef}`)}; fi`,
+      );
+    } else {
+      lines.push(`git checkout -q -B ${ref} ${shellQuote(`origin/${input.fetchRef}`)}`);
+    }
+  } else {
+    lines.push(`git checkout -q -B ${shellQuote(input.ref)}`);
+  }
+  lines.push("git rev-parse HEAD");
+  return lines.join("\n");
+}
+
+/** The SDK's missing-backup error — the handle's objects are gone (a rotation
+ *  or an offboard took them): by name, which survives the RPC boundary, or by
+ *  either of its two texts. */
+export function isBackupMissing(shape: { name?: string; message?: string }): boolean {
+  if (shape.name === "BackupNotFoundError") return true;
+  return /Backup (?:archive )?not found/i.test(shape.message ?? "");
+}
+
+// -- the bot's half: from the resident's handle to a selection -----------------
+
+/** The seed handle as the resident's `/status` publishes it (the bot's probe
+ *  carries it as `seed`, [resident.ts](./resident.ts)). */
+export interface SeedHandle {
+  checkoutBackupId: string;
+  depsBackupId?: string;
+  ref: string;
+  sha: string;
+}
+
+/** The seed for one thread: the resident's handle plus the thread's own ref
+ *  and resolved head when it has them — a thread bound to a branch is checked
+ *  out on it, a thread with none stays on the snapshot's. */
+export function seedForThread(
+  handle: SeedHandle,
+  thread: { slug: string; ref?: string; headSha?: string },
+): SandboxSeed {
+  return {
+    slug: thread.slug,
+    checkoutBackupId: handle.checkoutBackupId,
+    ...(handle.depsBackupId ? { depsBackupId: handle.depsBackupId } : {}),
+    ref: handle.ref,
+    sha: handle.sha,
+    ...(thread.ref ? { fetchRef: thread.ref } : {}),
+    ...(thread.ref && thread.headSha ? { fetchSha: thread.headSha } : {}),
+  };
+}
+
+/** What a seeded sandbox is, on the selection: where the checkout is and what
+ *  it is on, for the prompt and the card. */
+export interface SeededSandbox {
+  slug: string;
+  ref: string;
+  sha: string;
+  /** The checkout's path inside the sandbox — the run's working tree. */
+  workspace: string;
+  /** The container already carried this seed: nothing was restored. */
+  cached: boolean;
+  ms: number;
+}
+
+/** After a refused seed: retry once with a fresh handle when the handle's
+ *  objects were gone and the resident has since published another (a rotation
+ *  took the first); otherwise the run goes cold, and the reason says why. */
+export type SeedRetry = { action: "retry"; seed: SandboxSeed } | { action: "cold"; why: string };
+
+export function seedRetryDecision(input: {
+  answer: Extract<SeedAnswer, { seeded: false }>;
+  attempted: SandboxSeed;
+  fresh: SeedHandle | undefined;
+  alreadyRetried: boolean;
+}): SeedRetry {
+  const { answer, attempted, fresh } = input;
+  if (answer.reason === "seed-missing" && !input.alreadyRetried) {
+    if (fresh && fresh.checkoutBackupId !== attempted.checkoutBackupId) {
+      return {
+        action: "retry",
+        seed: seedForThread(fresh, {
+          slug: attempted.slug,
+          ...(attempted.fetchRef ? { ref: attempted.fetchRef } : {}),
+          ...(attempted.fetchSha ? { headSha: attempted.fetchSha } : {}),
+        }),
+      };
+    }
+    return { action: "cold", why: `seed missing (${answer.detail}) and the resident published no newer handle` };
+  }
+  return { action: "cold", why: `${answer.reason.replace("seed-", "seed ")} (${answer.detail})` };
+}
+
+/** The card's one line for a seeded sandbox, after the reason the resident
+ *  was not used: what it was seeded from, so a reader tells the three paths
+ *  — resident, seeded, cold — apart from Slack alone. */
+export function seededSandboxNote(
+  reason: string,
+  seeded: Pick<SeededSandbox, "slug" | "ref" | "sha" | "cached">,
+): string {
+  return `${reason} — seeded sandbox · from resident snapshot${seeded.cached ? " (already seeded)" : ""} · ${seeded.slug} · ${seeded.ref}@${seeded.sha.slice(0, 7)}`;
+}

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

@@ -0,0 +1,62 @@
+// A resident keeps two snapshot generations (docs/reference/specs/resident-repos.md
+// item 7). The refresh cycle that writes a new stamped pair used to delete the
+// pair it replaced at once; a seeded sandbox that read the checkout handle from
+// `/status` seconds earlier would then restore from objects that are gone, and
+// a rotation lands exactly when a release train merges — the burst the seeded
+// tier exists for. So the replaced pair is RETIRED instead, and the pair
+// retired before it is what the rotation deletes: a handle read from `/status`
+// resolves for at least one more cycle (ten minutes) after it stops being the
+// current one. Offboard and rebuild delete every recorded generation. This is
+// the decision, pure and imported by the resident Worker like
+// `residentDiskBudget.ts`.
+
+/** The two SDK backup handles a snapshot generation is made of. */
+export interface SnapshotHandles {
+  mirror: { id: string };
+  checkout: { id: string };
+}
+
+/** How many generations a resident keeps: the current pair and the one it replaced. */
+export const SNAPSHOT_GENERATIONS = 2;
+
+/** The storage key of the retired generation (the current one is the Worker's `resident:snapshot`). */
+export const RETIRED_SNAPSHOT_KEY = "resident:snapshot:retired";
+
+export interface Rotation<T extends SnapshotHandles> {
+  /** The generation to record as retired after this rotation. */
+  retired: T | undefined;
+  /** The backup ids whose objects this rotation deletes. */
+  deleteIds: string[];
+}
+
+const idsOf = (h: SnapshotHandles): string[] => [h.mirror.id, h.checkout.id];
+
+const sameHandles = (a: SnapshotHandles, b: SnapshotHandles) =>
+  a.mirror.id === b.mirror.id && a.checkout.id === b.checkout.id;
+
+/** A new pair was committed: the pair it `replaced` (the record read when the
+ *  step began) becomes the retired generation, and the pair `retired` before
+ *  it is deleted. The first snapshot ever replaces nothing and changes
+ *  nothing; a rotation whose replaced pair is the retired one already (a
+ *  re-fired step) deletes nothing, since those are the objects being kept. */
+export function rotateSnapshots<T extends SnapshotHandles>(input: {
+  replaced: T | undefined;
+  retired: T | undefined;
+}): Rotation<T> {
+  const { replaced, retired } = input;
+  if (!replaced) return { retired, deleteIds: [] };
+  if (retired && sameHandles(retired, replaced)) return { retired, deleteIds: [] };
+  return { retired: replaced, deleteIds: retired ? idsOf(retired) : [] };
+}
+
+/** Every recorded generation's backup ids, each once, in the order given
+ *  (current first): what offboard and rebuild delete, and what their dry runs
+ *  itemize. */
+export function backupIdsOf(records: ReadonlyArray<SnapshotHandles | undefined>): string[] {
+  const ids: string[] = [];
+  for (const record of records) {
+    if (!record) continue;
+    for (const id of idsOf(record)) if (!ids.includes(id)) ids.push(id);
+  }
+  return ids;
+}

package/dist/assets/src/mcp/registry.ts

@@ -31,6 +31,8 @@ export interface McpServerEntry {
   /** Who added it at run time (`slack:U…`, `cli:local`); absent for static config. */
   addedBy?: string;
   addedAt?: number;
+  /** An org entry `mcp promote` copied from a person's tier: that person (record 0042). */
+  promotedFrom?: string;
 }
 
 /** The three tiers a server can live in, in precedence order for a name clash. */
@@ -174,7 +176,8 @@ export function isMcpServerEntry(v: unknown): v is McpServerEntry {
     (e.tokenEnv === undefined || isStr(e.tokenEnv, 128)) &&
     (e.headersEnv === undefined || isHeadersEnv(e.headersEnv)) &&
     (e.addedBy === undefined || isStr(e.addedBy, 260)) &&
-    (e.addedAt === undefined || isNum(e.addedAt))
+    (e.addedAt === undefined || isNum(e.addedAt)) &&
+    (e.promotedFrom === undefined || isStr(e.promotedFrom, 260))
   );
 }
 
@@ -226,7 +229,11 @@ export interface McpServerView {
   state: "connected" | "awaiting_credential" | "static";
   source: "config" | "runtime";
   addedBy?: string;
+  /** `addedBy` as a display name, when the service could resolve one (record 0042: the same cached
+   *  lookup the runs index uses); absent → the surfaces show the id. */
+  addedByName?: string;
   addedAt?: number;
+  promotedFrom?: string;
 }
 
 export function serverView(
@@ -257,6 +264,7 @@ export function serverView(
     source: opts.source,
     ...(entry.addedBy ? { addedBy: entry.addedBy } : {}),
     ...(entry.addedAt !== undefined ? { addedAt: entry.addedAt } : {}),
+    ...(entry.promotedFrom ? { promotedFrom: entry.promotedFrom } : {}),
   };
 }