@coreplane/switchboard 1.260.0 → 1.260.2

package/bin/switchboard.js

@@ -1,25 +1,29 @@
 #!/usr/bin/env node
-// The `switchboard` bin: this file hands the process to dist/cli.js, the bundle
-// the build writes (build.mts; docs/reference/specs/packaging.md item 1). A
-// committed entry rather than the bundle itself, because npm links a bin only
-// when its target exists at install time, and the gitignored dist/ does not
-// until the build runs: with dist/cli.js as the bin, `npx <the package>` inside
-// the checkout — where npx prefers the workspace over the registry — found no
-// link and died with `sh: switchboard: command not found`. The published package
-// always carries the bundle, so there this is one extra module load; a checkout
-// that has not built the package is told what to run.
+// The published `switchboard` bin hands the process to the bundle beside it.
+// In a repository checkout npm resolves the package name to this workspace too,
+// but an ignored dist/ may be older than source. The checkout therefore never
+// trusts dist: operators run the root source script, while a tarball runs only
+// the bundle that its build packed.
 import { existsSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 
 const bundle = new URL("../dist/cli.js", import.meta.url);
+const checkoutRoot = new URL("../../../", import.meta.url);
+const runsFromCheckout =
+  existsSync(new URL("project.json", checkoutRoot)) && existsSync(new URL("src/cli.ts", checkoutRoot));
 
-if (!existsSync(bundle)) {
+if (runsFromCheckout) {
   console.error(
-    `switchboard: ${fileURLToPath(bundle)} is missing — the package is not built. Inside the checkout, npx runs this workspace, not the published package: run \`npm run build -w packages/switchboard\` first, or use the checkout's CLI, \`npm run cli -- <group> <verb> …\`.`,
+    "switchboard: npx resolved the package name to this checkout; its ignored dist/ is not authoritative. Run `npm run --silent cli -- <group> <verb> …` from the checkout root instead.",
   );
   process.exit(1);
 }
 
+if (!existsSync(bundle)) {
+  console.error(`switchboard: ${fileURLToPath(bundle)} is missing — the published package is incomplete.`);
+  process.exit(1);
+}
+
 // From here the bundle is the script: its entry claim (src/invokedAsScript.ts)
 // and its usage spelling (`programName`, src/cli.ts) read argv[1].
 process.argv[1] = fileURLToPath(bundle);

package/dist/assets/config/config.example.yaml

@@ -172,6 +172,7 @@ defaults:
 # "config set channel ..." are stored in data/overrides.json and win over these.
 # channels:
 #   slack:C012345:
+#     repo: acme/api                # default repository for repo-bound asks in this channel
 #     agent: review
 #     models:
 #       review: anthropic/claude-opus-5

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

@@ -28,14 +28,10 @@ import {
 import {
   authenticateIngressBearer,
   authenticateRestart,
+  authorizeRestartDeployer,
   decideRestart,
-  parseRestartAuthorization,
   parseRestartRequest,
-  RESTART_AUTHORIZE_PATH,
-  RESTART_SUBJECT_HEADER,
   restartResponse,
-  stripRestartSubject,
-  type RestartAuth,
   type RestartOutcome,
 } from "../../src/deploy/restart.ts";
 import {
@@ -89,7 +85,8 @@ export interface Env {
   ACCESS_TEAM_DOMAIN?: string; // live-view SSO gate: Cloudflare Access team domain (JWKS + iss)
   ACCESS_AUD?: string; // live-view SSO gate: Cloudflare Access application AUD tag
   DASHBOARD_TOKEN?: string; // dashboard auth `token` strategy: the bearer (the default env name; config may name another)
-  SWITCHBOARD_INGRESS_TOKENS?: string; // enables HTTP /ingress + MCP /mcp (JSON token→identity map); the `cron` entry is what scheduled runs present; an entry whose `http:<subject>` actor holds `deploy:write` in the bot's config may POST /admin/restart
+  SWITCHBOARD_INGRESS_TOKENS?: string; // enables HTTP /ingress + MCP /mcp (JSON token→identity map); the `cron` entry is what scheduled runs present
+  SWITCHBOARD_RESTART_DEPLOYER?: string; // deployment-profile grant: the token-map subject allowed to POST /admin/restart; Worker-only, never runtime config
   BRAVE_SEARCH_API_KEY?: string; // web_search backend (Brave); web_fetch works without it
   GITHUB_WEBHOOK_SECRET?: string; // check-run intake: signs POST /webhooks/github; absent, the intake answers 503 disabled
   CF_ANALYTICS_TOKEN?: string; // costs dash: Cloudflare API token, Account Analytics:Read only
@@ -211,37 +208,6 @@ export class SwitchboardServer extends Container<Env> {
     return this.restartRunning(opts);
   }
 
-  /**
-   * `deploy restart`, authorized: the Worker knows WHO the bearer is (the token
-   * map); WHETHER that identity may restart is the bot's config (`grants` —
-   * authorization.md item 9), which only the container holds. So ask it —
-   * `POST /admin/restart/authorize` with the authenticated subject in
-   * `RESTART_SUBJECT_HEADER` (never the bearer: the container may still hold the
-   * token map from before a rotation) — and stop only on a 200. A container that
-   * is not running is started first (the bot must answer): if the bearer is
-   * allowed, that start already put the current env live, so nothing is
-   * stopped and the outcome is `not-running`, exactly as before; if not, the
-   * refusal is relayed and the started container simply keeps serving.
-   */
-  async restartAuthorized(
-    subject: string,
-    opts: { force: boolean },
-  ): Promise<{ auth: RestartAuth; outcome?: RestartOutcome }> {
-    const wasRunning = this.ctx.container?.running === true;
-    await this.startBot();
-    const answer = await this.containerFetch(
-      new Request(`${INTERNAL}${RESTART_AUTHORIZE_PATH}`, {
-        method: "POST",
-        headers: { [RESTART_SUBJECT_HEADER]: subject },
-      }),
-      this.defaultPort,
-    );
-    const auth = parseRestartAuthorization(answer.status, await answer.text().catch(() => ""));
-    if (!auth.ok) return { auth };
-    if (!wasRunning) return { auth, outcome: { kind: "not-running" } };
-    return { auth, outcome: await this.restartRunning(opts) };
-  }
-
   /** The stop itself, for a running container: the preflight's refusal rules over `/healthz`, then SIGTERM. */
   private async restartRunning(opts: { force: boolean }): Promise<RestartOutcome> {
     const health = await this.containerFetch(new Request(`${INTERNAL}/healthz`), this.defaultPort);
@@ -265,12 +231,12 @@ export class SwitchboardServer extends Container<Env> {
   }
 }
 
-/** `POST /admin/restart` — the operator surface behind `deploy restart`
- *  (src/deploy/restart.ts documents the authorization choice: a
- *  SWITCHBOARD_INGRESS_TOKENS bearer whose `http:<subject>` actor holds
- *  `deploy:write` in the bot's config). The Worker authenticates the bearer
- *  against the map it holds — an unknown bearer never touches the container —
- *  and the Container DO asks the bot for the grant before stopping anything.
+/** `POST /admin/restart` — the operator surface behind `deploy restart`.
+ *  The Worker authenticates the bearer against its token map, then authorizes
+ *  that subject against SWITCHBOARD_RESTART_DEPLOYER, rendered from the
+ *  deployment profile (or set directly as a Worker var). Runtime config is
+ *  never consulted: this route must remain usable when that document is what
+ *  the restart is repairing.
  *  Body `{ "force": true }` bypasses the fail-closed refusals (no JSON body,
  *  impossible `inFlight`); runs in flight or a drain warn and never refuse. */
 async function handleAdminRestart(request: Request, env: Env): Promise<Response> {
@@ -283,14 +249,16 @@ async function handleAdminRestart(request: Request, env: Env): Promise<Response>
     console.warn(`[restart] ${authn.status} — ${authn.reason}`);
     return json(authn.status, { ok: false, error: authn.reason });
   }
+  const auth = authorizeRestartDeployer(authn.identity.subject, env.SWITCHBOARD_RESTART_DEPLOYER);
+  if (!auth.ok) {
+    console.warn(`[restart] ${auth.status} — ${auth.reason}`);
+    return json(auth.status, { ok: false, error: auth.reason });
+  }
   const parsed = parseRestartRequest(await request.text().catch(() => ""));
   if (!parsed.ok) return json(400, { ok: false, error: parsed.reason });
-  let auth: RestartAuth;
-  let outcome: RestartOutcome | undefined;
+  let outcome: RestartOutcome;
   try {
-    ({ auth, outcome } = await getContainer(env.SWITCHBOARD, INSTANCE).restartAuthorized(authn.identity.subject, {
-      force: parsed.force,
-    }));
+    outcome = await getContainer(env.SWITCHBOARD, INSTANCE).restart({ force: parsed.force });
   } catch (err) {
     // The container's /healthz probe or the DO call threw (container mid-transition,
     // port not answering): fail closed in the route's own JSON shape so the CLI reads
@@ -299,11 +267,6 @@ async function handleAdminRestart(request: Request, env: Env): Promise<Response>
     console.error(`[restart] ${authn.identity.subject} → error before stop: ${reason}`);
     return json(500, { ok: false, error: `restart failed before stopping anything: ${reason}` });
   }
-  if (!auth.ok || outcome === undefined) {
-    const refusal = auth.ok ? { status: 503 as const, reason: "restart disabled: no outcome" } : auth;
-    console.warn(`[restart] ${refusal.status} — ${refusal.reason}`);
-    return json(refusal.status, { ok: false, error: refusal.reason });
-  }
   console.log(
     `[restart] ${auth.subject} → ${outcome.kind}${outcome.kind === "refused" ? `: ${outcome.problems.join("; ")}` : ""}`,
   );
@@ -494,9 +457,7 @@ export default {
     // caller sent is stripped, and what the container sees carries this
     // Worker's own root. A static asset or the live view's SSE stream gets no
     // root; a refusal's line is dropped by the sink's filter.
-    // The restart-subject header is the Worker's own word to the container (the
-    // authorize call below); a caller cannot be allowed to speak it.
-    const inbound = stripRestartSubject(stripTraceContext(request));
+    const inbound = stripTraceContext(request);
     const route = shimRoute(pathname);
     if (route === undefined) return withLength(await getContainer(env.SWITCHBOARD, INSTANCE).fetch(inbound));
     const root = tracer.start("bot-shim.fetch", { sinks: traceSinks, attrs: { route } });

package/dist/assets/deploy/cloudflare/wrangler.template.jsonc

@@ -31,6 +31,12 @@
     "ACCESS_TEAM_DOMAIN": "{{access.teamDomain}}",
     "ACCESS_AUD": "{{access.aud}}",
     // {{/if}}
+    // The restart route's deployment-side grant. The Worker authenticates a
+    // bearer through SWITCHBOARD_INGRESS_TOKENS and compares its subject here;
+    // it never asks the runtime config it may be restarting to repair.
+    // {{#if restart}}
+    "SWITCHBOARD_RESTART_DEPLOYER": "{{restart.deployer}}",
+    // {{/if}}
     // The state Worker (deploy/cloudflare-memory/): where worker.ts records each
     // scheduled firing for the /runs Scheduled panel, with MEMORY_TOKEN.
     // A profile without a memory Worker renders no var: firings go unrecorded.

package/dist/assets/deploy/cloudflare-memory/backgroundTasks.ts

@@ -0,0 +1,25 @@
+type WaitUntilContext = Pick<DurableObjectState, "waitUntil">;
+
+const TASKS = Symbol.for("switchboard.memory-worker.pending-background-tasks");
+type PendingTasks = Map<Promise<unknown>, string>;
+
+const pendingTasks = (): PendingTasks => {
+  const root = globalThis as typeof globalThis & { [TASKS]?: PendingTasks };
+  return (root[TASKS] ??= new Map());
+};
+
+/** Keep deliberately detached Worker work in the runtime's request lifetime.
+ * The process-wide label set is also the test seam: a case cannot finish while
+ * work it started is still able to contend with the next case. */
+export function holdBackgroundTask(context: WaitUntilContext, label: string, task: Promise<unknown>): void {
+  const pending = pendingTasks();
+  const held = task.finally(() => pending.delete(held));
+  pending.set(held, label);
+  context.waitUntil(held);
+}
+
+export function assertNoPendingBackgroundTasks(): void {
+  const labels = [...pendingTasks().values()];
+  if (labels.length === 0) return;
+  throw new Error(`test ended with ${labels.length} pending background task(s): ${labels.join(", ")}`);
+}

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

@@ -78,6 +78,7 @@ import {
   selectReclaim,
 } from "../../src/core/runLedger/decisions.ts";
 import { intakeReceiptRetentionMs, minutesToMs, PLANE } from "../../src/core/budgets.ts";
+import { holdBackgroundTask } from "./backgroundTasks.ts";
 import {
   causeOfClose,
   causeOfReclaim,
@@ -2058,7 +2059,7 @@ export class RunHistoryDO extends DurableObject<Env> {
   /** The admission ask (`POST /plane/admit`, record 0064 "The queue"): one
    *  transaction decides and writes — `admitted` reserves the thread,
    *  `queued` stores the request under the minted id. */
-  planeAdmit(
+  async planeAdmit(
     post: {
       runId: string;
       requester: string;
@@ -2070,7 +2071,7 @@ export class RunHistoryDO extends DurableObject<Env> {
       reaskMs?: number;
     },
     now: number,
-  ): PlaneAskAnswer {
+  ): Promise<PlaneAskAnswer> {
     let answer!: PlaneAskAnswer;
     this.ctx.storage.transactionSync(() => {
       if (post.reaskMs !== undefined)
@@ -2089,7 +2090,7 @@ export class RunHistoryDO extends DurableObject<Env> {
       this.applyPlaneWrites(decision.writes);
       answer = planeAskAnswerOf(decision, post.runId);
     });
-    if (answer.kind === "queued") void this.ensurePlaneReaskAlarm(now);
+    if (answer.kind === "queued") await this.settlePlaneReaskAlarmAfterCommit(now);
     console.log(
       `[plane/admit] ${post.threadKey} → ${answer.kind}${answer.kind === "queued" ? ` position ${answer.position}` : ""} (run ${post.runId})`,
     );
@@ -2152,7 +2153,10 @@ export class RunHistoryDO extends DurableObject<Env> {
 
   /** A refusal-by-name the bot met at attach or exec (`POST /plane/observe`,
    *  record 0064): an admitted run re-enters the queue at its old position. */
-  planeObserve(post: { runId: string; resident: string; refusal: string }, now: number): { reentered: boolean } {
+  async planeObserve(
+    post: { runId: string; resident: string; refusal: string },
+    now: number,
+  ): Promise<{ reentered: boolean }> {
     let reentered = false;
     this.ctx.storage.transactionSync(() => {
       const decision = decide(this.planeState(), {
@@ -2165,7 +2169,7 @@ export class RunHistoryDO extends DurableObject<Env> {
       this.applyPlaneWrites(decision.writes);
       reentered = decision.writes.length > 0;
     });
-    if (reentered) void this.ensurePlaneReaskAlarm(now);
+    if (reentered) await this.settlePlaneReaskAlarmAfterCommit(now);
     console.log(
       `[plane/observe] run ${post.runId} on ${post.resident}: ${post.refusal.slice(0, 60)} — ${reentered ? "re-entered" : "no-op"}`,
     );
@@ -2194,6 +2198,18 @@ export class RunHistoryDO extends DurableObject<Env> {
     if (set === null || set > due) await this.ctx.storage.setAlarm(due);
   }
 
+  /** Settle alarm I/O without contradicting the plane transaction that already
+   *  committed. A scheduling failure may delay a re-ask until another wake,
+   *  but returning an error would make the caller proceed or retry while the
+   *  durable queued row remains eligible for admission. */
+  private async settlePlaneReaskAlarmAfterCommit(now: number): Promise<void> {
+    try {
+      await this.ensurePlaneReaskAlarm(now);
+    } catch (err) {
+      console.error("[plane/alarm] re-ask scheduling failed after the plane state committed", err);
+    }
+  }
+
   /** The earliest instant the plane must wake at (record 0064): the
    *  earliest hosting deadline, lease end or re-ask across its rows. A due
    *  already past re-offers at the re-ask cadence, never in a hot loop, and
@@ -2372,21 +2388,24 @@ export class RunHistoryDO extends DurableObject<Env> {
 
   /** The transport's push (record 0064, "Where it lives"): committed effects
    *  are pushed to the bot Worker over the service binding, which forwards to
-   *  the container. Fire and forget — a push that fails is not retried by a
-   *  timer; the effect rides the next heartbeat or reclaim-sweep answer. */
+   *  the container. The response does not wait for this best-effort push, but
+   *  the actor does: waitUntil keeps its I/O inside this request's lifetime so
+   *  it cannot contend with an unrelated request after the caller moves on. */
   private pushPlaneEffects(effects: PlaneEffect[]): void {
     if (effects.length === 0) return;
     const bot = this.env.BOT;
     if (!bot) return;
-    void bot
-      .fetch("https://bot/plane/effects", {
-        method: "POST",
-        headers: {
-          "content-type": "application/json",
-          authorization: `Bearer ${this.env.MEMORY_TOKEN ?? ""}`,
-        },
-        body: JSON.stringify({ effects }),
-      })
+    const delivery = Promise.resolve()
+      .then(() =>
+        bot.fetch("https://bot/plane/effects", {
+          method: "POST",
+          headers: {
+            "content-type": "application/json",
+            authorization: `Bearer ${this.env.MEMORY_TOKEN ?? ""}`,
+          },
+          body: JSON.stringify({ effects }),
+        }),
+      )
       .then((r) => {
         if (!r.ok)
           console.warn(
@@ -2398,6 +2417,7 @@ export class RunHistoryDO extends DurableObject<Env> {
           `[plane/push] ${effects.length} effect(s) not delivered: ${err instanceof Error ? err.message : String(err)} — they ride the next heartbeat`,
         );
       });
+    holdBackgroundTask(this.ctx, `plane effect push (${effects.map((effect) => effect.id).join(", ")})`, delivery);
   }
 
   /** The unacknowledged effects, oldest first, at most `PLANE_EFFECTS_PER_ANSWER`

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

@@ -5027,11 +5027,32 @@ export class ResidentDO extends Sandbox<Env> {
    *  deploy's alone. Answers `restarted` when a stop was issued, else why
    *  not. */
   private async reconcileImage(where: "attach" | "refresh" | "deploy", force = false): Promise<ImageReconcileResult> {
-    if (!(await this.isRuntimeActive().catch(() => false))) {
-      // Inactivity proves only that the old process is gone, not that its
-      // replacement started successfully. Keep the marker: the next refresh's
-      // hydration starts the deployed image and reports only after it reaches
-      // `warm` (issue 2101).
+    const active = await this.isRuntimeActive().catch((err) => {
+      console.log(`image-reconcile (${where}): activity probe failed — preserving the pending report: ${errMsg(err)}`);
+      return null;
+    });
+    // A failed probe proves neither state. Preserve the marker and its drain
+    // hold until a later reconcile confirms inactivity or hydrates a fresh
+    // active container. An attach with that marker must fail closed even after
+    // the drain backstop reopens: admitting it could wake a pre-deploy image.
+    if (active === null) {
+      if (
+        where === "attach" &&
+        (await this.ctx.storage.get<{ resource: string }>(IMAGE_REPORT_PENDING_KEY)) !== undefined
+      ) {
+        console.log(
+          "image-stale (attach): activity could not be verified while a new-image report is pending — the attach is refused",
+        );
+        return "stale";
+      }
+      return "deferred";
+    }
+    if (!active) {
+      // An inactive container's next start is on the deployed image by
+      // construction. Report on every reconcile: the deploy may have marked
+      // it pending after an earlier idle cycle, and the drain itself refuses
+      // the attach that would otherwise wake it and provide another reporter.
+      await this.reportPendingImageCurrent(where);
       return "inactive";
     }
     const last = THREAD_USERS[THREAD_USERS.length - 1];
@@ -5091,12 +5112,13 @@ export class ResidentDO extends Sandbox<Env> {
   /** The report a held drain waits for (issue 1931): when the deploy's
    *  reconcile could not verify this resident's fresh container on the new
    *  image, a marker stays in storage and the registry holds the drain. The
-   *  fact the report stands on is the replacement's own completed hydration:
-   *  the fresh container has restored its snapshot and reached `warm`. A stop
-   *  or inactive runtime does not report; each keeps the marker for that next
-   *  start (issue 2101). The marker is deleted only after a successful report:
-   *  a transient failure keeps it for the next reconcile, and the drain's
-   *  `until` is the backstop for a report that never lands. */
+   *  fact the report stands on is either an inactive runtime, whose next start
+   *  uses the deployed image by construction, or the active replacement's own
+   *  completed hydration: the fresh container has restored its snapshot and
+   *  reached `warm`. A stop alone does not report (issue 2101). The marker is
+   *  deleted only after a successful report: a transient failure keeps it for
+   *  the next reconcile, and the drain's `until` is the backstop for a report
+   *  that never lands. */
   private async reportPendingImageCurrent(where: string): Promise<boolean> {
     const pending = await this.ctx.storage.get<{ resource: string }>(IMAGE_REPORT_PENDING_KEY);
     if (pending === undefined) return true;
@@ -5125,9 +5147,9 @@ export class ResidentDO extends Sandbox<Env> {
    *  an active, quiet container is always cycled, but that stop is not a report.
    *  The marker survives until the replacement hydrates and reaches `warm` on
    *  the deploy's image (issue 2101: the old probe raced that restore and lost).
-   *  `verified` true is the fact the reopen may stand on; a cycle or inactive
-   *  result leaves a hold on the drain, cleared by this resident's later
-   *  `reportPendingImageCurrent`, never by a timer.
+   *  `verified` true is the fact the reopen may stand on: inactivity reports
+   *  at once, while an active container's cycle leaves a hold until its fresh
+   *  hydration calls `reportPendingImageCurrent`, never until a timer.
    *
    *  The hold lands BEFORE the marker: the marker is what lets any concurrent
    *  attach/refresh reconcile report, and a report that reaches the registry
@@ -5139,10 +5161,9 @@ export class ResidentDO extends Sandbox<Env> {
     await this.ctx.storage.put(IMAGE_REPORT_PENDING_KEY, { resource });
     const result = await this.reconcileImage("deploy", true);
     if (result === "deferred") return { result, verified: false };
-    // Neither inactivity nor a successful stop is verification: only the
-    // replacement's completed hydration clears the marker. A concurrent fresh
-    // start may have done so while this reconcile yielded, hence the storage
-    // read rather than an unconditional false.
+    // Inactivity reports synchronously; a successful stop does not. A
+    // concurrent fresh start may also have hydrated while this reconcile
+    // yielded, hence the storage read rather than a verdict from `result`.
     const verified = (await this.ctx.storage.get(IMAGE_REPORT_PENDING_KEY)) === undefined;
     return { result, verified };
   }

package/dist/assets/deploy/profile.example.json

@@ -1,5 +1,5 @@
 {
-  "$comment": "The deployment profile: where THIS installation runs. Copy to deploy/profile.json and fill it in (or run `switchboard deploy init`). The account is your Cloudflare account id; every hostname must be under `zone`, a zone in that account, unless the Worker names its own `zone` (also in the account); `workers.bot` is the one required Worker — leave `memory`, `resident` or `sandbox` out and `deploy plan` has no step for them (a bot-only profile is a one-step plan; without `memory` the config is not pushed anywhere). The project's docs site is not a Worker of an installation: it is the project's website, deployed by the project's own CI from project.json, so there is no `docs` entry. `configSource` is where `deploy all` reads the bot's runtime config from before building the image — a path, `github://owner/repo/path@ref` (needs CONFIG_REPO_TOKEN), or `op://Vault/Item/field` (needs OP_SERVICE_ACCOUNT_TOKEN); `secretsSource` is where `secrets put` reads values from — a directory of <NAME> files (the default when absent) or `op://Vault/Item`. `images` is where the bot, resident and sandbox container images come from: `registry` — the release's published images, copied once per version into your account registry by `deploy all` itself (or `deploy images` ahead of it) over HTTPS and referenced from there — no Docker anywhere, a Cloudflare API token with Containers Edit in CLOUDFLARE_API_TOKEN for the copy (an installation deploying published images; what `init` writes from the published package); or `build` (the default when absent) — each Worker's Dockerfile, built by wrangler where `deploy all` runs (a checkout; the project's own production). `artifacts` (optional) names the R2 bucket a run's files move through (docs/reference/specs/execution.md item 20): with it the bot Worker binds the bucket and `deploy` creates it before the upload (the credential then needs Workers R2 Storage: Edit); the bot's runtime config `artifacts.r2.bucket` must say the same name. `metrics` (optional) names the Analytics Engine dataset every finished run's point is written to (docs/reference/specs/run-metrics.md): the state Worker's template then binds it as `RUN_METRICS` with the name beside it in `RUN_METRICS_DATASET` — nothing is created ahead of the deploy, the platform creates the dataset on first write — and the bot's runtime config `metrics.dataset` must say the same name (the bot warns at boot when the two differ). `deploy plan` reads this example when no profile exists; `deploy all` refuses it.",
+  "$comment": "The deployment profile: where THIS installation runs. Copy to deploy/profile.json and fill it in (or run `switchboard deploy init`). The account is your Cloudflare account id; every hostname must be under `zone`, a zone in that account, unless the Worker names its own `zone` (also in the account); `workers.bot` is the one required Worker — leave `memory`, `resident` or `sandbox` out and `deploy plan` has no step for them (a bot-only profile is a one-step plan; without `memory` the config is not pushed anywhere). The project's docs site is not a Worker of an installation: it is the project's website, deployed by the project's own CI from project.json, so there is no `docs` entry. `configSource` is where `deploy all` reads the bot's runtime config from before building the image — a path, `github://owner/repo/path@ref` (needs CONFIG_REPO_TOKEN), or `op://Vault/Item/field` (needs OP_SERVICE_ACCOUNT_TOKEN); `restart.deployer` is the SWITCHBOARD_INGRESS_TOKENS subject the Worker itself allows to restart the bot, independent of runtime config so config recovery cannot lock itself out; `secretsSource` is where `secrets put` reads values from — a directory of <NAME> files (the default when absent) or `op://Vault/Item`. `images` is where the bot, resident and sandbox container images come from: `registry` — the release's published images, copied once per version into your account registry by `deploy all` itself (or `deploy images` ahead of it) over HTTPS and referenced from there — no Docker anywhere, a Cloudflare API token with Containers Edit in CLOUDFLARE_API_TOKEN for the copy (an installation deploying published images; what `init` writes from the published package); or `build` (the default when absent) — each Worker's Dockerfile, built by wrangler where `deploy all` runs (a checkout; the project's own production). `artifacts` (optional) names the R2 bucket a run's files move through (docs/reference/specs/execution.md item 20): with it the bot Worker binds the bucket and `deploy` creates it before the upload (the credential then needs Workers R2 Storage: Edit); the bot's runtime config `artifacts.r2.bucket` must say the same name. `metrics` (optional) names the Analytics Engine dataset every finished run's point is written to (docs/reference/specs/run-metrics.md): the state Worker's template then binds it as `RUN_METRICS` with the name beside it in `RUN_METRICS_DATASET` — nothing is created ahead of the deploy, the platform creates the dataset on first write — and the bot's runtime config `metrics.dataset` must say the same name (the bot warns at boot when the two differ). `deploy plan` reads this example when no profile exists; `deploy all` refuses it.",
   "account": "00000000000000000000000000000000",
   "zone": "example.com",
   "workers": {
@@ -9,5 +9,6 @@
     "sandbox": { "script": "switchboard-sandbox", "hostname": "switchboard-sandbox.example.com" }
   },
   "configSource": "config/config.yaml",
+  "restart": { "deployer": "deployer" },
   "images": "registry"
 }

package/dist/assets/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "switchboard",
-  "version": "1.260.0",
+  "version": "1.260.2",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "switchboard",
-      "version": "1.260.0",
+      "version": "1.260.2",
       "license": "Apache-2.0",
       "workspaces": [
         "web",
@@ -20445,7 +20445,7 @@
     },
     "packages/switchboard": {
       "name": "@coreplane/switchboard",
-      "version": "1.260.0",
+      "version": "1.260.2",
       "license": "Apache-2.0",
       "dependencies": {
         "@earendil-works/pi-ai": "0.85.1",

package/dist/assets/package.json

@@ -1,6 +1,6 @@
 {
   "name": "switchboard",
-  "version": "1.260.0",
+  "version": "1.260.2",
   "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.260.0",
-  "commit": "33c6cd103ce9d8a49be5249f98306fe46160f81c",
-  "builtAt": "2026-09-21T15:19:23.063Z"
+  "version": "1.260.2",
+  "commit": "95c0153dc141f2e586238634e66970fea994bf7b",
+  "builtAt": "2026-09-21T20:25:49.397Z"
 }

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

@@ -447,7 +447,7 @@ Your final message is posted to Slack — keep it readable, lead with the outcom
 // whole reply — so the prose never repeats them and never pads around them.
 const REVIEW_FINAL_MESSAGE = `YOUR FINAL MESSAGE IS THE REVIEW'S TEXT, NOTHING ELSE. Switchboard renders the verdict line and the findings list from your submit_verdict call — on GitHub as the head of the comment, in Slack as the whole reply — and folds your final message under them on GitHub as the full review. So write only what the list cannot carry: one short paragraph per finding, keyed by its id (what is wrong, the concrete failure, the fix). Do not restate the verdict or the findings, do not summarize what you read, do not list what you verified clean, do not describe your method — what you checked belongs in your notes, which the run page shows. A change with no findings needs one sentence, not a tour.`;
 
-const REVIEW_VERDICT_INSTRUCTION = `VERDICT: before your final message, call the submit_verdict tool exactly once with \`approve\` (no finding at or above the severity to address remains — the level in force for this run, \`minor\` by default: a major or a minor finding means \`request_changes\`; nits alone never block) or \`request_changes\`, a one-line summary, \`head\` = the output of \`git rev-parse HEAD\` in the checkout you reviewed, and \`findings\` — every issue you report as a structured entry with a stable id you assign in order (F1, F2, …), a severity of exactly blocking|major|minor|nit, the file (plus line when it points at one), and a one-line title. The findings array is the index of your review: the full explanation of each finding stays in your prose, keyed by the same ids. Switchboard writes the verdict as the first line of the GitHub comment itself, lists the findings under it and folds your text below them as the full review; a review with no submitted verdict is posted as not approving, so never skip it. An \`approve\` carrying a finding at or above the severity to address is downgraded to \`request_changes\` and the tool's ack says so — approve only when every finding sits below the level. Do not write "LGTM" in your own text — the verdict line carries it.`;
+const REVIEW_VERDICT_INSTRUCTION = `VERDICT: before your final message, call the submit_verdict tool exactly once with \`approve\` (no finding at or above the severity to address remains — the level in force for this run, \`minor\` by default: a major or a minor finding means \`request_changes\`; nits alone never block) or \`request_changes\`, a one-line summary, \`head\` = the output of \`git rev-parse HEAD\` in the checkout you reviewed, and \`findings\` — every issue you report as a structured entry with a stable id you assign in order (F1, F2, …), a severity of exactly blocking|major|minor|nit, the file (plus line when it points at one), and a one-line title. The findings array is the index of your review: the full explanation of each finding stays in your prose, keyed by the same ids. Switchboard writes the verdict as the first line of the GitHub comment itself, lists the findings under it and folds your text below them as the full review; a review with no submitted verdict is posted as not approving, so never skip it. The only exception is a preflight infrastructure failure from the REVIEW TARGET block's first-command HEAD check: stop, submit no finding or verdict, and let Switchboard report it without a GitHub post. An \`approve\` carrying a finding at or above the severity to address is downgraded to \`request_changes\` and the tool's ack says so — approve only when every finding sits below the level. Do not write "LGTM" in your own text — the verdict line carries it.`;
 
 // The diff-gated spec review (docs/reference/specs/agent-review.md item 14) and
 // the test guard under it (item 16; specs-coverage.md item 6), one text for
@@ -485,7 +485,7 @@ Strategy — GATHER ONCE, THEN ANALYZE ONCE. Do not explore file-by-file; your c
 
 1. GATHER, in 2-4 batched tool calls total:
    - \`gh pr view <ref> --json title,body,url,baseRefName\` and \`gh pr diff <ref>\` (the complete diff) in one command
-   - clone the repo and check out the PR branch, then call the \`diff_digest\` tool to orient: 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
+   - for a PR review, use the checkout Switchboard provisioned at the head named in the REVIEW TARGET block — do not clone or check out another ref — then call the \`diff_digest\` tool to orient: 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.: \`gh pr diff <ref> --name-only | grep -v -E "lock|generated|snap" | while read f; do echo "=== $f ==="; cat "$f"; done\`
    - if the PR 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

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

@@ -104,11 +104,18 @@ export const HARNESS_PROBE_WAIT_MS = 5 * MINUTE_MS;
  *  `maxMinutes` so one nobody lifted is an hour and a half, not a day. A run
  *  asked during a drain waits at its attach one `pollMs` at a time under its
  *  own lease less `leaseReserveMs` (what the attach and the work after it
- *  need), `waitMaxMs` with no lease to clip it. */
+ *  need), `waitMaxMs` with no lease to clip it — unless a fallback stands
+ *  behind the attach: `fallbackWaitMs` bounds the wait by the FALLBACK's own
+ *  cost, never the deploy's (issue 2101: a run refused by the drain waited
+ *  18 minutes for the whole deploy, then did the job in a seeded sandbox that
+ *  stands up in about two), so a drain refusal on a first attach falls to the
+ *  seeded sandbox after at most a few minutes; a re-attach with no fallback —
+ *  a resumed run, a mid-run recovery — keeps the lease's bound. */
 export const DRAIN = {
   pollMs: 30_000,
   waitMaxMs: 60 * MINUTE_MS,
   leaseReserveMs: 10 * MINUTE_MS,
+  fallbackWaitMs: 3 * MINUTE_MS,
   deployWaitMaxMs: 60 * MINUTE_MS,
   marginMinutes: 5,
   maxMinutes: 90,
@@ -218,13 +225,19 @@ export const MERGE_WAIT_ASK_MINUTES = 60;
  *  request's line with the conflict named, never a retry loop. */
 export const PULL_SWEEP = { leaseMinutes: 15, spendCapUsd: 5 } as const;
 
-/** The provider retry ladder (issue 1932): the backoff before each retry of a
- *  transient model-call failure — a gateway 5xx, a stream cut before
- *  `message_stop`, a gateway timeout. Three attempts with growing waits,
- *  charged to the run's lease; the waits stay small next to the run's minutes
- *  because the observed blips are edge transients of seconds. */
+/** The provider retry ladder: the first backoffs for a transport-class
+ *  model-call failure. The final rung repeats while the run's loop lease has
+ *  time, so these are pacing intervals rather than a three-attempt terminal
+ *  budget. */
 export const PROVIDER_RETRY_BACKOFFS_MS = [5_000, 15_000, 45_000] as const;
 
+/** How often the model proxy writes an SSE comment while the provider is
+ *  reasoning silently. The public container hop has cut an otherwise healthy
+ *  stream at about thirty seconds of silence; a comment inside half that
+ *  window keeps the transport alive without becoming a model event. The
+ *  model call itself remains bounded by the run's lease. */
+export const MODEL_STREAM_HEARTBEAT_MS = 15_000;
+
 /** A hosted ship parent's deadline margin past the pipeline's wall clock
  *  (record 0060): the row's `state.hosting.until` is the hand-off time plus
  *  the instance's `caps.maxMinutes` plus this hour, absorbing the runner's own