@coreplane/switchboard 1.238.0 → 1.240.0

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

@@ -0,0 +1,73 @@
+// A resident `down` on a reason only a rebuild can escape is rebuilt on that
+// transition, under a budget (docs/reference/specs/resident-repos.md item 36).
+// Pure: the Worker's `goDown` and the watchdog's backstop both call
+// `autoRebuildDecision` over the history row they persist
+// (`resident:autoRebuilds`, ISO instants of the auto-rebuilds this resident
+// has had), so the transition and the backstop cannot disagree.
+
+/** The `down` reasons a rebuild is the only exit from: a down resident runs no
+ *  cycle, and these say the snapshot (or the container that would restore it)
+ *  cannot be used — never a provision failure, which would loop against the
+ *  same broken build. `runtime-unreachable` is item 64's last rung: a recreated
+ *  container that did not answer either. */
+export const REHYDRATION_FAILURE_RE = /^(r2-restore-failed|snapshot-stamp-mismatch|no-snapshot|runtime-unreachable)/;
+
+/** How many auto-rebuilds one resident gets inside one window. A rebuild is a
+ *  clone, an install and a build (minutes to half an hour) that holds the cap
+ *  slot and writes a fresh snapshot; a resident that comes back `warm` and
+ *  goes `down` again on the same class of reason is flapping on something a
+ *  rebuild does not fix, and the third time it stays down where a person can
+ *  see it. */
+export const AUTO_REBUILD_BUDGET = 2;
+export const AUTO_REBUILD_WINDOW_MS = 24 * 60 * 60_000;
+
+/** The stamp a spent budget leaves on the reason — the one mark the decision
+ *  reads back so the watchdog's passes never judge the same down twice. */
+const SPENT_MARK = " — auto-rebuild budget spent (";
+
+export type AutoRebuildDecision =
+  /** Rebuild now; `history` is what to persist (pruned, this instant appended); `reason` is the rebuild's. */
+  | { action: "rebuild"; history: string[]; reason: string }
+  /** Stay down; `reason` is the down reason stamped with the budget; `history` is pruned. */
+  | { action: "budget-spent"; history: string[]; reason: string }
+  | { action: "not-eligible"; why: "reason" | "already-spent" };
+
+/** A `down` reason the transition (or the watchdog) may rebuild from: a
+ *  rehydration failure that no spent budget has stamped yet. */
+export function isAutoRebuildEligible(reason: string): boolean {
+  return REHYDRATION_FAILURE_RE.test(reason) && !reason.includes(SPENT_MARK);
+}
+
+/** Judge one `down`. `history` are the ISO instants of this resident's past
+ *  auto-rebuilds; entries outside the window (or unparseable) are dropped
+ *  before counting and before writing back. */
+export function autoRebuildDecision(input: {
+  reason: string;
+  history: readonly string[];
+  now: number;
+}): AutoRebuildDecision {
+  if (!REHYDRATION_FAILURE_RE.test(input.reason)) return { action: "not-eligible", why: "reason" };
+  if (input.reason.includes(SPENT_MARK)) return { action: "not-eligible", why: "already-spent" };
+  const windowStart = input.now - AUTO_REBUILD_WINDOW_MS;
+  const kept = input.history
+    .map((iso) => ({ iso, at: Date.parse(iso) }))
+    .filter((e) => Number.isFinite(e.at) && e.at > windowStart)
+    .sort((a, b) => a.at - b.at);
+  const hours = Math.round(AUTO_REBUILD_WINDOW_MS / 3_600_000);
+  if (kept.length >= AUTO_REBUILD_BUDGET) {
+    // No reopen instant on the stamp: a stamped row is never judged again and
+    // a down resident runs no cycle, so nothing resumes when the window
+    // passes — only a person's rebuild recovers it, and the stamp says so.
+    return {
+      action: "budget-spent",
+      history: kept.map((e) => e.iso),
+      reason: `${input.reason}${SPENT_MARK}${AUTO_REBUILD_BUDGET} in ${hours} h) — repo rebuild resets it`,
+    };
+  }
+  const history = [...kept.map((e) => e.iso), new Date(input.now).toISOString()];
+  return {
+    action: "rebuild",
+    history,
+    reason: `auto-rebuild (${history.length} of ${AUTO_REBUILD_BUDGET} in ${hours} h): ${input.reason}`,
+  };
+}

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

@@ -180,7 +180,7 @@ export function killStaleBuildProcessesCommand(user: string, dir: string): strin
  *  a tool naming the signal. A bare "killed" is NOT enough — compilers and
  *  OOM messages say it too — and a step the cycle itself timed out is a real
  *  failure however it died. */
-const INTERRUPTION_SIGNATURE = /\bexit 143\b|Session terminated|SIGTERM/;
+const INTERRUPTION_SIGNATURE = /\bexit 143\b|Session terminated|SIGTERM|^restore-interrupted:/;
 
 /** Message wording of the Sandbox SDK's runtime-replacement error family — the
  *  container went away UNDER a live SDK call, so the failure never reaches the
@@ -396,12 +396,34 @@ export function isRuntimeUnreachableReason(reason: string): boolean {
  *  means the stream ran on before the replacement. */
 export function restoreFailureDisposition(
   message: string,
-  facts: { runtimeReplaced?: boolean } = {},
+  facts: { runtimeReplaced?: boolean; runtimeActive?: boolean } = {},
 ): { action: "interrupted"; reason: string } | { action: "down"; reason: string } {
   const timedOut = /\(timed out\)/.test(message);
-  if (!timedOut && (facts.runtimeReplaced === true || RUNTIME_REPLACEMENT_WORDING.test(message))) {
+  if (timedOut) {
+    return {
+      action: "down",
+      reason: `r2-restore-failed: ${message} — container stopped so the transfer cannot land on a rebuild`,
+    };
+  }
+  // The kill signature the instance step's classifier reads
+  // (INTERRUPTION_SIGNATURE): a container roll SIGTERMs the extract, whose
+  // exec comes back a normal `exit 143` result — the SDK's replacement
+  // wording only reaches the execs that follow. Same event, same reading.
+  if (
+    facts.runtimeReplaced === true ||
+    RUNTIME_REPLACEMENT_WORDING.test(message) ||
+    INTERRUPTION_SIGNATURE.test(message)
+  ) {
     return { action: "interrupted", reason: `restore-interrupted: ${message}` };
   }
+  // The Worker's probe after the failure: a runtime that is no longer active
+  // took the disk the extract wrote to with it, whatever the exit code said.
+  if (facts.runtimeActive === false) {
+    return {
+      action: "interrupted",
+      reason: `restore-interrupted: ${message} — the container stopped under the restore`,
+    };
+  }
   return {
     action: "down",
     reason: `r2-restore-failed: ${message} — container stopped so the transfer cannot land on a rebuild`,

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

@@ -0,0 +1,61 @@
+/** The ledger of held `/await-restore` requests (docs/reference/specs/execution.md
+ *  item 27): each waiter is one resolver held in memory until the resident's
+ *  lifecycle state leaves `restoring`, when `publish` answers every held
+ *  request at once with the state it landed on. Event-driven by construction —
+ *  no polling and no retry timer anywhere: the one publish is the state
+ *  transition itself (`setResidentState`). In-DO memory only: a Durable Object
+ *  restart drops the held RPCs with the waiters, and the bot's own request
+ *  deadline turns that into a named cold fallback, never a hang. */
+export interface RestoreOutcome {
+  /** The lifecycle state the resident landed on when the restore span ended. */
+  state: string;
+  reason: string;
+}
+
+/** One registered waiter: the outcome it will be answered with, and the way
+ *  to withdraw it when the caller learns it need not wait after all. */
+export interface RestoreHold {
+  outcome: Promise<RestoreOutcome>;
+  /** Take the waiter off the ledger; a no-op once a publish answered it. */
+  withdraw(): void;
+}
+
+export class RestoreWaiters {
+  private waiters: Array<(outcome: RestoreOutcome) => void> = [];
+
+  /** How many requests are held right now (the ledger's size, for tests and logs). */
+  get size(): number {
+    return this.waiters.length;
+  }
+
+  /** Register a waiter for the next publish. Register BEFORE reading the
+   *  state you are waiting to leave: a transition that lands between the read
+   *  and the registration would otherwise publish to a ledger this request is
+   *  not on yet, and hold it for a transition that may never come. A caller
+   *  whose read then says the wait is over withdraws. */
+  hold(): RestoreHold {
+    let resolve!: (outcome: RestoreOutcome) => void;
+    const outcome = new Promise<RestoreOutcome>((r) => (resolve = r));
+    this.waiters.push(resolve);
+    return {
+      outcome,
+      withdraw: () => {
+        const at = this.waiters.indexOf(resolve);
+        if (at !== -1) this.waiters.splice(at, 1);
+      },
+    };
+  }
+
+  /** Hold one request until the next publish. */
+  wait(): Promise<RestoreOutcome> {
+    return this.hold().outcome;
+  }
+
+  /** Answer every held request with the state the resident landed on and
+   *  empty the ledger; a publish with nothing held is a no-op. */
+  publish(outcome: RestoreOutcome): void {
+    const held = this.waiters;
+    this.waiters = [];
+    for (const resolve of held) resolve(outcome);
+  }
+}

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/mcp/registry.ts

@@ -234,6 +234,13 @@ export interface McpServerView {
   addedByName?: string;
   addedAt?: number;
   promotedFrom?: string;
+  /** `promotedFrom` as a display name, when the lookup answered. */
+  promotedFromName?: string;
+  /** A user row's owner (the id after `user:` in `scopeKey`) as a display name, when the lookup answered. */
+  ownerName?: string;
+  /** A higher tier holds this name, so runs use that entry and this one is idle (`mcpServersFor`'s
+   *  `shadowedBy`, the winning scope key — `org`, or `channel:<id>`); absent when this entry serves. */
+  shadowedBy?: string;
 }
 
 export function serverView(