@coreplane/switchboard 0.0.0 → 1.18.0

package/dist/assets/deploy/cloudflare/preflight.mjs

@@ -0,0 +1,243 @@
+#!/usr/bin/env node
+// Deploy preflight for the bot Worker (docs/reference/specs/slack-channel.md item 8).
+//
+// `wrangler deploy` rolls the bot container. Cloudflare's rollout sends SIGTERM;
+// since the run ledger's handoff (docs/reference/specs/run-history.md item 39) the bot
+// hands every resumable run to the next generation and exits within seconds,
+// and the next generation continues the runs under their own cards — so a
+// deploy no longer waits on runs, and this preflight no longer refuses for
+// them. `npm run deploy` runs it first and refuses only while
+//   - the container application is not in a settled state (a rollout is still
+//     provisioning/updating — `wrangler containers list --json`): a second
+//     rollout on top of one in progress replaces the instance the first put
+//     into its graceful drain and kills whatever it was running (two deploys
+//     90 s apart once killed a review at 153 s).
+// It WARNS (never refuses) when the bot reports runs in flight (`inFlight > 0`
+// — they hand off) or is already draining (`draining: true` — its resumable
+// runs were handed off; a ship pipeline still in flight would be killed), and
+// when /healthz says the reconnect catch-up is failing or the bot token lacks
+// required scopes (`catchUp.error`, `catchUp.missingScopes`).
+//
+// Fail closed: unreachable bot, a body without the JSON shape (a bot whose
+// /healthz answers a bare `ok` is not one this preflight can read), a wrangler failure, or an app
+// not in the listing all refuse — a deploy never proceeds blind.
+// `SWITCHBOARD_DEPLOY_FORCE=1` (or `--force` when run directly) is the
+// explicit, warned bypass.
+//
+// Dependency-free Node (fetch + child_process). `decide()` is pure and
+// unit-tested (preflight.test.mjs); `main()` only does I/O around it.
+import { execFile } from "node:child_process";
+import { dirname } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+/** The env var naming this Worker's origin. `deploy all` sets it from the deployment profile; the
+ *  preflight has no address of its own (deploy/profile.json is the only place the fleet's hostnames live). */
+export const BASE_URL_ENV = "SWITCHBOARD_BASE_URL";
+/** The Containers application `wrangler deploy` creates for `SwitchboardServer` in wrangler.jsonc. */
+export const APP_NAME = "switchboard-switchboardserver";
+/** Application states in which no rollout is in progress. Anything else —
+ *  `provisioning`, `updating`, or a state this script does not know — refuses. */
+const SETTLED_APP_STATES = new Set(["active", "ready"]);
+
+const HOW_TO_FORCE =
+  "to deploy anyway (over a rollout in progress, or blind when the bot cannot be consulted): `SWITCHBOARD_DEPLOY_FORCE=1 npm run deploy` (`node preflight.mjs --force` checks alone)";
+
+/** GET /healthz. Never throws: `{ok:true,payload}` (parsed JSON, or the raw text when not JSON) or `{ok:false,error}`. */
+export async function fetchHealth(baseUrl, { timeoutMs = 20_000 } = {}) {
+  const url = new URL("/healthz", baseUrl).toString();
+  try {
+    const res = await fetch(url, { signal: AbortSignal.timeout(timeoutMs) });
+    const text = await res.text();
+    if (!res.ok) return { ok: false, error: `GET ${url} → HTTP ${res.status}: ${text.slice(0, 200)}` };
+    try {
+      return { ok: true, payload: JSON.parse(text) };
+    } catch {
+      return { ok: true, payload: text };
+    }
+  } catch (err) {
+    return { ok: false, error: `GET ${url} failed: ${err instanceof Error ? err.message : String(err)}` };
+  }
+}
+
+/**
+ * The words to keep from a failed wrangler command. wrangler prints its
+ * errors on STDOUT (`✘ [ERROR] A request to the Cloudflare API … failed.
+ * Authentication error [code: 10000]`), so a message built from stderr alone
+ * says "Command failed: npx wrangler containers list --json" and nothing else
+ * — which is exactly what the first CI release deploy showed while its token
+ * lacked the Containers scope. Prefer wrangler's own error lines; else the
+ * last non-empty lines of both streams; else the exit description. Pure.
+ */
+/** ANSI colour sequences (ESC `[` … `m`), built from the code point so the regex literal carries no control character. */
+const ANSI_SEQUENCE = new RegExp(`${String.fromCharCode(27)}\\[[0-9;]*m`, "g");
+
+export function wranglerFailureText(err, stdout, stderr, { maxLines = 3 } = {}) {
+  const lines = `${String(stdout ?? "")}\n${String(stderr ?? "")}`
+    .split("\n")
+    .map((l) => l.replace(ANSI_SEQUENCE, "").trim())
+    .filter((l) => l.length > 0 && !/^npm (ERR|WARN|warn)/i.test(l));
+  const errorLines = lines.filter((l) =>
+    /\[ERROR\]|✘|error|Authentication|Unauthorized|not authorized|permission/i.test(l),
+  );
+  const picked = (errorLines.length > 0 ? errorLines : lines).slice(-maxLines);
+  const exit =
+    err && typeof err.code === "number" ? `exit ${err.code}` : err && err.killed ? "killed (timeout?)" : "failed";
+  return picked.length > 0 ? `${exit}: ${picked.join(" | ")}` : `${exit}, no output`;
+}
+
+/** `wrangler containers list --json`, run from this directory so wrangler.jsonc
+ *  selects the account. Never throws: `{ok:true,payload}` or `{ok:false,error}`. */
+export function listContainerApps({ cwd = dirname(fileURLToPath(import.meta.url)), timeoutMs = 60_000 } = {}) {
+  return new Promise((resolve) => {
+    execFile(
+      "npx",
+      ["wrangler", "containers", "list", "--json"],
+      { cwd, timeout: timeoutMs, maxBuffer: 4 * 1024 * 1024 },
+      (err, stdout, stderr) => {
+        if (err)
+          return resolve({
+            ok: false,
+            error: `wrangler containers list failed (${wranglerFailureText(err, stdout, stderr)}) — the credential may lack the Containers scope`,
+          });
+        // wrangler prints its banner before the JSON; the payload starts at the first `[`.
+        const start = String(stdout).indexOf("[");
+        if (start < 0)
+          return resolve({
+            ok: false,
+            error: `wrangler containers list: no JSON array in output: ${String(stdout).slice(0, 200)}`,
+          });
+        try {
+          resolve({ ok: true, payload: JSON.parse(String(stdout).slice(start)) });
+        } catch (parseErr) {
+          resolve({
+            ok: false,
+            error: `wrangler containers list: unparsable JSON: ${parseErr instanceof Error ? parseErr.message : String(parseErr)}`,
+          });
+        }
+      },
+    );
+  });
+}
+
+/**
+ * Warnings (never refusals) from the reconnect catch-up's status on /healthz
+ * (docs/reference/specs/slack-channel.md item 7): a scan that could not run at all
+ * (`catchUp.error`, e.g. `missing_scope`) or a bot token missing required
+ * scopes. Pure; an older payload without `catchUp` says nothing.
+ * @returns {string[]}
+ */
+export function catchUpWarnings(payload) {
+  const c = payload && typeof payload === "object" ? payload.catchUp : undefined;
+  if (!c || typeof c !== "object") return [];
+  const out = [];
+  if (typeof c.error === "string" && c.error) {
+    out.push(
+      `reconnect catch-up is NOT running (last attempt${c.lastRunAt ? ` ${c.lastRunAt}` : ""}): ${c.error} — mentions posted during a rollover are being dropped`,
+    );
+  }
+  if (Array.isArray(c.missingScopes) && c.missingScopes.length > 0) {
+    out.push(
+      `bot token is missing required Slack scopes: ${c.missingScopes.join(", ")} — reinstall the app with them (docs/tutorials/run-it-locally.md → Connect it to Slack)`,
+    );
+  }
+  return out;
+}
+
+/**
+ * The decision, pure. `health` is the result of `fetchHealth`, `apps` of `listContainerApps`.
+ * `warnings` never block: this deploy may be the fix for what they name.
+ * @returns {{ allow: boolean, forced: boolean, problems: string[], warnings: string[], message: string }}
+ */
+export function decide({ health, apps }, { force = false } = {}) {
+  const problems = [];
+  const warnings = health?.ok === true ? catchUpWarnings(health.payload) : [];
+
+  if (!health || health.ok !== true) {
+    problems.push(`bot not consulted: ${health?.error ?? "unknown error"}`);
+  } else {
+    const p = health.payload;
+    if (!p || typeof p !== "object") {
+      problems.push(
+        `bot answered /healthz without JSON (${JSON.stringify(p).slice(0, 40)}) — its /healthz is not the JSON this preflight reads; deploy once with SWITCHBOARD_DEPLOY_FORCE=1`,
+      );
+    } else {
+      if (!Number.isInteger(p.inFlight) || p.inFlight < 0) {
+        problems.push(`bot reports an impossible inFlight=${JSON.stringify(p.inFlight)} (counter bug or old Worker)`);
+      } else if (p.inFlight > 0) {
+        // Not a refusal since the handoff (run-history item 39): SIGTERM hands
+        // every resumable run to the next generation, which continues it.
+        warnings.push(
+          `${p.inFlight} run(s) in flight — handed to the next generation on SIGTERM (run-history item 39); they continue there under their own cards`,
+        );
+      }
+      if (p.draining === true) {
+        warnings.push(
+          "bot is already draining from a previous deploy — its resumable runs are handed off; a ship pipeline still in flight would be killed when this rollout replaces the draining instance",
+        );
+      }
+    }
+  }
+
+  if (!apps || apps.ok !== true) {
+    problems.push(`container application not consulted: ${apps?.error ?? "unknown error"}`);
+  } else {
+    const app = Array.isArray(apps.payload) ? apps.payload.find((a) => a?.name === APP_NAME) : undefined;
+    if (!app) {
+      problems.push(
+        `container application ${APP_NAME} not in \`wrangler containers list\` (wrong account, or renamed class?)`,
+      );
+    } else if (!SETTLED_APP_STATES.has(app.state)) {
+      problems.push(`container rollout in progress: state=${app.state} — wait until it is active`);
+    }
+  }
+
+  const warningText =
+    warnings.length > 0 ? `\n  WARNING (not blocking):\n${warnings.map((w) => `  - ${w}`).join("\n")}` : "";
+  if (problems.length === 0) {
+    return {
+      allow: true,
+      forced: false,
+      problems,
+      warnings,
+      message: `preflight ok: container application settled${warningText}`,
+    };
+  }
+  const detail = problems.map((p) => `  - ${p}`).join("\n");
+  if (force) {
+    return {
+      allow: true,
+      forced: true,
+      problems,
+      warnings,
+      message: `preflight WARNING: deploying by force despite —\n${detail}\n  a rollout landing on one in progress can disrupt it; in-flight runs hand off regardless (run-history item 39)${warningText}`,
+    };
+  }
+  return {
+    allow: false,
+    forced: false,
+    problems,
+    warnings,
+    message: `preflight REFUSED: a Worker deploy rolls the bot container —\n${detail}\n  wait and retry; ${HOW_TO_FORCE}${warningText}`,
+  };
+}
+
+export async function main(argv = process.argv.slice(2), env = process.env) {
+  const force = argv.includes("--force") || env.SWITCHBOARD_DEPLOY_FORCE === "1";
+  const baseUrl = env[BASE_URL_ENV];
+  if (!baseUrl) {
+    console.error(
+      `[bot-preflight] ${BASE_URL_ENV} is not set — the bot's origin comes from the deployment profile; deploy through \`npm run cli -- deploy all\` (it sets it), or set it to https://<bot hostname> to run this alone`,
+    );
+    return 2;
+  }
+  const [health, apps] = await Promise.all([fetchHealth(baseUrl), listContainerApps()]);
+  const d = decide({ health, apps }, { force });
+  (d.allow && !d.forced && d.warnings.length === 0 ? console.log : console.error)(`[bot-preflight] ${d.message}`);
+  return d.allow ? 0 : 1;
+}
+
+// Run only when executed directly (`node preflight.mjs`), not when imported by tests.
+// pathToFileURL, not `file://${argv[1]}`, so the guard also holds on Windows paths.
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  process.exitCode = await main();
+}

package/dist/assets/deploy/cloudflare/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  // Scoped config so `npm run typecheck` here checks worker.ts AND the shared
+  // src/core/schedules.ts it imports by relative path (the schedule registry +
+  // the pure firing helpers). Strict, like the bot — the shared module is
+  // written for strict narrowing.
+  "compilerOptions": {
+    "target": "es2022",
+    "module": "es2022",
+    "moduleResolution": "bundler",
+    "lib": ["es2022"],
+    "types": ["@cloudflare/workers-types"],
+    "strict": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "allowImportingTsExtensions": true
+  },
+  "include": ["worker.ts"]
+}

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

@@ -0,0 +1,382 @@
+// Cloudflare Containers shim: runs the unchanged Switchboard image as a single
+// always-on container instance — the shape of any long-lived server on
+// Cloudflare Containers (singleton DO, cron keep-alive;
+// docs/decisions/0016-long-lived-process-not-serverless.md).
+//
+// The Worker exists to (re)start the container, run health checks, restart the
+// container on request (`POST /admin/restart` — `deploy restart`), and fire
+// the scheduled jobs — all Slack traffic is the container's own outbound Socket
+// Mode websocket, so nothing user-facing flows through here. Scheduled jobs are
+// NOT special: a `run` schedule is POSTed to the bot's generic /ingress as the
+// `cron` identity, so it becomes an ordinary run.
+import { Container, getContainer } from "@cloudflare/containers";
+import { parseHealthz } from "../../src/deploy/liveGate.ts";
+import {
+  authenticateRestart,
+  decideRestart,
+  parseRestartAuthorization,
+  parseRestartRequest,
+  RESTART_AUTHORIZE_PATH,
+  RESTART_SUBJECT_HEADER,
+  restartResponse,
+  stripRestartSubject,
+  type RestartAuth,
+  type RestartOutcome,
+} from "../../src/deploy/restart.ts";
+import {
+  interpretIngressResponse,
+  isRunSchedule,
+  planScheduledFiring,
+  recordFiring as postFiring,
+  scheduleForCron,
+  type ScheduleFiring,
+} from "../../src/core/schedules.ts";
+import { systemClock } from "../../src/core/trace/clock.ts";
+import { createTracer } from "../../src/core/trace/tracer.ts";
+import { shimRoute, stripTraceContext, withTraceContext, workerLogSink } from "../../src/core/trace/workerTrace.ts";
+
+// The Worker's own spans (docs/reference/specs/tracing.md item 22): one `bot-shim.fetch`
+// root per routed request and one `cron.<schedule>` root per fired schedule,
+// on a `slow` log sink whose filter drops the line an unauthenticated refusal
+// would leave. The public edge never adopts a caller's trace context.
+const tracer = createTracer({ clock: systemClock });
+const traceSinks = [workerLogSink((line) => console.log(line))];
+
+interface Env {
+  SWITCHBOARD: DurableObjectNamespace<SwitchboardServer>;
+  // secrets (wrangler secret put ...)
+  SLACK_BOT_TOKEN: string;
+  SLACK_APP_TOKEN: string;
+  ANTHROPIC_API_KEY: string;
+  OPENAI_API_KEY?: string;
+  E2B_API_KEY?: string;
+  SANDBOX_TOKEN?: string; // cloudflare execution: bearer for the sandbox Worker
+  RESIDENT_OPERATOR_TOKEN?: string; // resident repos: operator bearer for the resident Worker
+  RESIDENT_ADMIN_TOKEN?: string; // resident repos: admin bearer for `repo onboard/offboard/...` chat commands
+  GH_TOKEN?: string; // fallback when no GitHub App is configured
+  GITHUB_APP_ID?: string;
+  GITHUB_APP_INSTALLATION_ID?: string;
+  GITHUB_APP_PRIVATE_KEY?: string;
+  PUBLIC_BASE_URL?: string; // live-view: base for /runs/<id>?t=… links on the status card
+  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
+  BRAVE_SEARCH_API_KEY?: string; // web_search backend (Brave); web_fetch works without it
+  CF_ANALYTICS_TOKEN?: string; // costs dash: Cloudflare API token, Account Analytics:Read only
+  ANTHROPIC_ADMIN_KEY?: string; // costs dash (optional): Anthropic Admin API key for the LLM cost report
+  MEMORY_TOKEN?: string; // durable memory + friction ledger + schedule firings + MCP registry: bearer for the state Worker
+  MCP_CREDENTIAL_KEY?: string; // MCP registry: the bot-only key that seals server credentials before they reach the McpDO
+  STATE_WORKER_URL?: string; // var: the state Worker's base URL — where this shim records each scheduled firing
+}
+
+/** Every secret/var the Worker forwards into the container. Optional entries
+ *  are forwarded only when set, so the bot sees "not configured" as absence. */
+const FORWARDED_OPTIONAL = [
+  "OPENAI_API_KEY",
+  "E2B_API_KEY",
+  "SANDBOX_TOKEN",
+  "RESIDENT_OPERATOR_TOKEN",
+  "RESIDENT_ADMIN_TOKEN",
+  "GH_TOKEN",
+  "GITHUB_APP_ID",
+  "GITHUB_APP_INSTALLATION_ID",
+  "GITHUB_APP_PRIVATE_KEY",
+  "PUBLIC_BASE_URL",
+  "ACCESS_TEAM_DOMAIN",
+  "ACCESS_AUD",
+  "DASHBOARD_TOKEN",
+  "CF_ANALYTICS_TOKEN",
+  "ANTHROPIC_ADMIN_KEY",
+  "SWITCHBOARD_INGRESS_TOKENS",
+  "BRAVE_SEARCH_API_KEY",
+  "MEMORY_TOKEN",
+  "MCP_CREDENTIAL_KEY",
+  "STATE_WORKER_URL",
+] as const satisfies readonly (keyof Env)[];
+
+/** The container's environment, computed from the Worker env AT START TIME.
+ *  A running container keeps the env it started with, whatever `wrangler
+ *  secret put` has since changed on the Worker — so this is read on every
+ *  (re)start rather than once in the constructor: after `deploy restart`
+ *  stops the container, the next start carries the current secrets. */
+function containerEnv(env: Env): Record<string, string> {
+  const vars: Record<string, string> = {
+    // The image carries no config: the bot reads the `base` document `deploy config`
+    // pushed to the state Worker (src/configDocument.ts), reached through
+    // STATE_WORKER_URL + MEMORY_TOKEN forwarded below.
+    SWITCHBOARD_CONFIG: "state://base",
+    SLACK_BOT_TOKEN: env.SLACK_BOT_TOKEN,
+    SLACK_APP_TOKEN: env.SLACK_APP_TOKEN,
+    ANTHROPIC_API_KEY: env.ANTHROPIC_API_KEY,
+  };
+  for (const name of FORWARDED_OPTIONAL) {
+    const value = env[name];
+    if (value) vars[name] = value;
+  }
+  return vars;
+}
+
+const INSTANCE = "singleton";
+const INTERNAL = "https://switchboard-keepalive.internal";
+
+export class SwitchboardServer extends Container<Env> {
+  defaultPort = 8080; // the bot's health endpoint (PORT=8080 in the image)
+  // Never let this scale to zero: the Slack websocket must stay connected and
+  // Slack does not redeliver missed Socket Mode events. The keep-alive cron
+  // pings /healthz every MINUTE (wrangler.jsonc `* * * * *`, deliberate: it
+  // bounds the Slack deaf window after a stop/rollover — the sooner a touch
+  // restarts the container, the sooner the reconnect catch-up can run).
+  sleepAfter = "2h";
+
+  /** Start the container if it is not running, with the env computed now.
+   *  Default port-ready timeout is 20s; first boot (npm-less image, but cold
+   *  pull + Slack connect) can exceed it. Already running → a no-op (the
+   *  start options are not applied to a live container). */
+  private startBot(): Promise<void> {
+    return this.startAndWaitForPorts(
+      this.defaultPort,
+      { portReadyTimeoutMS: 120_000 },
+      { envVars: containerEnv(this.env) },
+    );
+  }
+
+  override async fetch(request: Request): Promise<Response> {
+    await this.startBot();
+    return super.fetch(request);
+  }
+
+  /**
+   * `deploy restart`: stop the container WITHOUT an image build so it comes
+   * back on the Worker's current secrets. Cloudflare's idiom — `stop()` sends
+   * SIGTERM, the bot's graceful drain (src/index.ts) finishes in-flight runs
+   * and exits, and the NEXT request through `fetch` starts the container again
+   * (`startBot`, env computed then). The keep-alive cron GETs /healthz every
+   * minute and the CLI's live gate polls it every 15 s, so the next request is
+   * never more than seconds away. Refuses (the deploy preflight's rules) while
+   * runs are in flight or a drain is already under way unless `force`.
+   */
+  async restart(opts: { force: boolean }): Promise<RestartOutcome> {
+    if (!this.ctx.container?.running) return { kind: "not-running" };
+    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);
+    const body = parseHealthz(await health.text().catch(() => ""));
+    const verdict = decideRestart(body, opts);
+    if (!verdict.allow) return { kind: "refused", problems: verdict.problems };
+    const inFlight = typeof body?.inFlight === "number" ? body.inFlight : 0;
+    const previousStartedAt = typeof body?.startedAt === "string" ? body.startedAt : undefined;
+    console.log(
+      `[restart] SIGTERM → container (started ${previousStartedAt ?? "unknown"}, ${inFlight} in flight${verdict.forced ? ", FORCED" : ""})`,
+    );
+    await this.stop();
+    return { kind: "stopping", forced: verdict.forced, inFlight, previousStartedAt };
+  }
+
+  override onStop(params: { exitCode: number; reason: string }): void {
+    // The next fetch (cron keep-alive within a minute, or the CLI's poll) starts it again with the current env.
+    console.log(
+      `[restart] container stopped (exit ${params.exitCode}, ${params.reason}) — restarts with the current env on the next request`,
+    );
+  }
+}
+
+/** `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.
+ *  Body `{ "force": true }` bypasses the in-flight/draining refusal. */
+async function handleAdminRestart(request: Request, env: Env): Promise<Response> {
+  const json = (status: number, body: Record<string, unknown>) =>
+    new Response(JSON.stringify(body), { status, headers: { "content-type": "application/json" } });
+  if (request.method !== "POST") return json(405, { ok: false, error: "method not allowed: POST /admin/restart" });
+  const authorization = request.headers.get("authorization") ?? undefined;
+  const authn = authenticateRestart(authorization, env.SWITCHBOARD_INGRESS_TOKENS);
+  if (!authn.ok) {
+    console.warn(`[restart] ${authn.status} — ${authn.reason}`);
+    return json(authn.status, { ok: false, error: authn.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;
+  try {
+    ({ auth, outcome } = await getContainer(env.SWITCHBOARD, INSTANCE).restartAuthorized(authn.identity.subject, {
+      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
+    // a reason instead of the platform's HTML 500. Nothing was stopped.
+    const reason = err instanceof Error ? err.message : String(err);
+    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("; ")}` : ""}`,
+  );
+  const res = restartResponse(outcome);
+  return json(res.status, res.body);
+}
+
+/** Record a firing on the state Worker's ScheduleDO (the /runs Scheduled panel
+ *  reads it). Best-effort: a failure here is a log line — the run itself (if
+ *  any) already happened and is its own record. */
+async function recordFiring(env: Env, firing: ScheduleFiring): Promise<void> {
+  const res = await postFiring({ url: env.STATE_WORKER_URL, token: env.MEMORY_TOKEN }, firing);
+  if (!res.ok) console.error(`[schedule] ${firing.schedule}: recording the firing failed — ${res.reason}`);
+}
+
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    const pathname = new URL(request.url).pathname;
+    // The public edge (docs/reference/specs/tracing.md item 22): whatever trace context the
+    // 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 route = shimRoute(pathname);
+    if (route === undefined) return getContainer(env.SWITCHBOARD, INSTANCE).fetch(inbound);
+    const root = tracer.start("bot-shim.fetch", { sinks: traceSinks, attrs: { route } });
+    try {
+      const forwarded = withTraceContext(inbound, root);
+      // The one route the Worker answers itself; everything else is the container's.
+      const res =
+        pathname === "/admin/restart"
+          ? await handleAdminRestart(forwarded, env)
+          : await getContainer(env.SWITCHBOARD, INSTANCE).fetch(forwarded);
+      root.end(res.status >= 500 ? "error" : "ok", { httpStatus: res.status });
+      return res;
+    } catch (err) {
+      root.fail(err);
+      root.end("error");
+      throw err;
+    }
+  },
+
+  // Every cron trigger in wrangler.jsonc is a `bot` schedule in the registry
+  // (src/core/schedules.ts — a unit test keeps the two equal). `healthz` (the
+  // internal keep-alive) touches /healthz: any touch starts the container if
+  // stopped and renews the activity timeout, which is also what revives it after
+  // platform maintenance; internal, so nothing is recorded. A `run` schedule
+  // POSTs the bot's generic /ingress as the `cron` identity (its bearer is the
+  // `cron` entry of SWITCHBOARD_INGRESS_TOKENS — no extra secret) with the
+  // schedule's command text; the bot dispatches it as a normal run and answers
+  // with the run's id + status, which is recorded on the state Worker for the
+  // /runs Scheduled panel. Fail-closed: no `cron` token → nothing is sent and the
+  // firing is recorded as `misconfigured`; an ingress error (bot down, unknown
+  // identity) is recorded as `ingress-error`.
+  async scheduled(controller: ScheduledController, env: Env, ctx: ExecutionContext): Promise<void> {
+    const schedule = scheduleForCron(controller.cron, "bot");
+    if (!schedule) {
+      console.error(
+        `[schedule] cron "${controller.cron}" is not a bot schedule in the registry — nothing fired (wrangler.jsonc and src/core/schedules.ts have drifted)`,
+      );
+      return;
+    }
+    if (schedule.action.type === "healthz") {
+      const res = await getContainer(env.SWITCHBOARD, INSTANCE).fetch(new Request(`${INTERNAL}/healthz`));
+      if (!res.ok) console.error(`switchboard health check failed: ${res.status}`);
+      return;
+    }
+    if (!isRunSchedule(schedule)) {
+      console.error(
+        `[schedule] ${schedule.name}: action "${schedule.action.type}" is not something the bot shim fires — nothing fired (the registry entry names the wrong worker)`,
+      );
+      return;
+    }
+
+    const firedAt = controller.scheduledTime || systemClock();
+    const plan = planScheduledFiring(schedule, env.SWITCHBOARD_INGRESS_TOKENS, firedAt);
+    if (!plan.ok) {
+      console.error(`[schedule] ${schedule.name}: not armed — ${plan.reason}; nothing ran`);
+      ctx.waitUntil(
+        recordFiring(env, { schedule: schedule.name, firedAt, outcome: "misconfigured", detail: plan.reason }),
+      );
+      return;
+    }
+    // The firing is one `cron.<schedule>` root (docs/reference/specs/tracing.md item 22):
+    // the ingress request carries it, and the recorded firing names its trace.
+    const root = tracer.start(`cron.${schedule.name}`, { sinks: traceSinks, startedAt: firedAt });
+    let firing: ScheduleFiring;
+    try {
+      const res = await getContainer(env.SWITCHBOARD, INSTANCE).fetch(
+        withTraceContext(
+          new Request(`${INTERNAL}/ingress`, {
+            method: "POST",
+            headers: { "content-type": "application/json", authorization: `Bearer ${plan.token}` },
+            body: JSON.stringify(plan.body),
+          }),
+          root,
+        ),
+      );
+      firing = {
+        ...interpretIngressResponse(schedule, firedAt, res.status, await res.text().catch(() => "")),
+        traceId: root.traceId,
+      };
+    } catch (err) {
+      firing = {
+        schedule: schedule.name,
+        firedAt,
+        outcome: "ingress-error",
+        detail: `fetch failed: ${err instanceof Error ? err.message : String(err)}`.slice(0, 300),
+        traceId: root.traceId,
+      };
+    }
+    root.end(firing.outcome === "ingress-error" ? "error" : "ok", {
+      outcome: firing.outcome,
+      ...(firing.runId ? { runId: firing.runId } : {}),
+    });
+    // Ids, outcome, and the reply's first line only — never a token.
+    console.log(
+      `[schedule] ${schedule.name} → ${firing.outcome}${firing.runId ? ` run ${firing.runId}` : ""}${firing.detail ? ` — ${firing.detail}` : ""}`,
+    );
+    // Telemetry for the /runs Scheduled panel — best-effort and off the
+    // invocation's critical path: the cron completes when the ingress answered,
+    // not when the state Worker has acknowledged the record.
+    ctx.waitUntil(recordFiring(env, firing));
+  },
+} satisfies ExportedHandler<Env>;