@coreplane/switchboard 1.260.0 → 1.260.1

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

@@ -551,10 +551,10 @@ export type CoordinatorAction =
   | { type: "merge"; step: string; prNumber: number; headSha: string; queued?: true }
   /** Read the check runs at the reviewed head (record 0055, the round verdict):
    *  the merge door's own reading, folded into the round. `retry` names the
-   *  failed checks whose one flake re-run the machine is spending: the bot
-   *  re-runs their failed jobs (the CI retry the deploy already uses) instead
-   *  of reading. */
-  | { type: "checks"; step: string; prNumber: number; headSha: string; retry?: string[] }
+   *  failed checks whose one flake re-run the machine is spending; `refire`
+   *  asks for the one close/reopen recovery when no required check launched.
+   *  Either effect runs instead of a read. */
+  | { type: "checks"; step: string; prNumber: number; headSha: string; retry?: string[]; refire?: true }
   /** Wait for the intake's checks-settled event at the approved head, bounded as the fallback. */
   | { type: "wait-checks"; step: string; headSha: string; timeoutMs: number }
   | { type: "sleep"; step: string; ms: number }
@@ -680,10 +680,18 @@ export type StepReturn =
    *  queue removed it — the reason is the queue's own (issue 2011). */
   | { type: "merge"; step: string; outcome: "pending" | "refused" | "enqueued" | "removed"; reason: string; at: number }
   /** The checks read at the reviewed head; `checks` absent means GitHub could
-   *  not be read, which the machine treats as pending (record 0055). A retry
-   *  ask answers `retried` instead: whether the bot dispatched the re-run —
-   *  false means there is nothing to wait for at the unchanged head. */
-  | { type: "checks"; step: string; checks?: RoundChecks; draft?: boolean; retried?: boolean; at: number }
+   *  not be read, which the machine treats as pending (record 0055). Effect
+   *  asks answer `retried` or `refired` instead; false still spends that one
+   *  recovery so an unchanged head cannot loop on the write. */
+  | {
+      type: "checks";
+      step: string;
+      checks?: RoundChecks;
+      draft?: boolean;
+      retried?: boolean;
+      refired?: boolean;
+      at: number;
+    }
   | { type: "wait-checks"; step: string; outcome: "event" | "timeout" }
   | { type: "sleep"; step: string };
 
@@ -699,14 +707,18 @@ export interface CheckFailure {
 }
 
 /** The check runs at the reviewed head as the round's checks step reads them.
- *  `expected` names checks the head must still gain — a required check, or the
- *  repository's approve workflow whose run does not exist yet (issue 2063):
- *  the base's required contexts not among the reported runs. The table reads
- *  an expected-but-unreported check exactly as a pending one. */
+ *  `required` carries the base's whole required-context set and `expected`
+ *  its unreported subset. The whole set lets the table distinguish no required
+ *  check launching from an unrelated run that did report; an ordinary missing
+ *  subset reads exactly as pending (issue 2063). */
 export interface RoundChecks {
   total: number;
   pending: string[];
   failed: CheckFailure[];
+  /** Every check context required by the base. Together with `expected`, this
+   *  distinguishes an empty required-check launch from an unrelated check
+   *  that did report (for example the title workflow). */
+  required?: string[];
   expected?: string[];
 }
 
@@ -831,6 +843,8 @@ export type UnitEnding =
       finalReply?: string;
       /** A changes-requested review posted this round before the stop. */
       postedReview?: boolean;
+      /** The mechanical WIP checkpoint a stopped coding child pushed before teardown. */
+      checkpoint?: { branch: string; sha: string };
     }
   | {
       kind: "aborted";
@@ -874,7 +888,14 @@ export type UnitEnding =
    *  `transient` so it reads as a condition beside `checks_failed` and `held`
    *  in the plane's table, never as the child failing on its task. */
   | { kind: "transient"; round: RoundRef; runId: string; reviewRounds: number }
-  | { kind: "interrupted"; round: RoundRef; runId: string; reviewRounds: number; cause?: InterruptionCause }
+  | {
+      kind: "interrupted";
+      round: RoundRef;
+      runId: string;
+      reviewRounds: number;
+      cause?: InterruptionCause;
+      checkpoint?: { branch: string; sha: string };
+    }
   | { kind: "refused"; refusal: string; message?: string; round: RoundRef; reviewRounds: number }
   /** The unit idles instead of ending (record 0051): with the resolved
    *  `ship.idleDays` above zero, `end()` wraps an idling kind — every kind but
@@ -1072,9 +1093,10 @@ type Phase =
   | { at: "merge-wait"; pr: PrRef; headSha: string; n: number; since: number; waitMs: number; queued?: true }
   /** The round's checks step (record 0055): the check runs at the reviewed head
    *  are read after an approve settles, before merge_ready or the merge door.
-   *  `graced`: a head with no check reported has had its one-chunk grace;
-   *  `retried`: the one flake re-run is spent; `retry` names the failed checks
-   *  the next ask re-runs instead of reading. */
+   *  `graced`: a head with no required check reported has had its one-chunk
+   *  grace; `refired`: the one pull_request close/reopen recovery is spent;
+   *  `retried`: the one flake re-run is spent. `retry` and `refire` make the
+   *  next ask perform that effect instead of reading. */
   | {
       at: "checks";
       round: RoundRef;
@@ -1085,7 +1107,9 @@ type Phase =
       waitMs: number;
       graced: boolean;
       retried: boolean;
+      refired: boolean;
       retry?: string[];
+      refire?: true;
     }
   /** Waiting on `checks-settled-<head>` between two checks reads, in the merge
    *  wait's own chunks — the intake wakes the machine when the head settles. */
@@ -1099,6 +1123,7 @@ type Phase =
       waitMs: number;
       graced: boolean;
       retried: boolean;
+      refired: boolean;
     }
   | { at: "ended" };
 
@@ -1338,6 +1363,7 @@ export function nextAction(s: UnitPipelineState): CoordinatorAction {
         prNumber: p.prNumber,
         headSha: p.headSha,
         ...(p.retry !== undefined ? { retry: p.retry } : {}),
+        ...(p.refire === true ? { refire: true as const } : {}),
       };
     case "checks-wait":
       return {
@@ -1518,6 +1544,16 @@ function nextReview(s: UnitPipelineState, notes: CoordinatorNote[] = []): Transi
 const stopMode = (status: RunStatus): "soft" | "hard" | undefined =>
   status === "stopped_soft" ? "soft" : status === "stopped_hard" ? "hard" : undefined;
 
+/** The last mechanical WIP push to this unit branch. Unlike an ordinary push,
+ *  it says the child ended before its work was ready for review. */
+function interruptedCheckpoint(
+  s: UnitPipelineState,
+  pushed: readonly PushedHeadFact[] | undefined,
+): { branch: string; sha: string } | undefined {
+  const found = pushed?.filter((p) => p.ref === s.input.unit.branch && p.by === "salvage").at(-1);
+  return found ? { branch: found.ref, sha: found.sha } : undefined;
+}
+
 /** A coding run's confirmed end: round 0's child, or the run a findings step dispatched. */
 function settleCoding(
   s: UnitPipelineState,
@@ -1545,6 +1581,7 @@ function settleCoding(
         }
       : {}),
   };
+  const checkpoint = interruptedCheckpoint(next, facts.pushed);
   const mode = stopMode(facts.status);
   if (mode !== undefined)
     return end(
@@ -1555,13 +1592,33 @@ function settleCoding(
         round,
         reviewRounds: next.reviewRounds,
         ...(facts.finalReply !== undefined ? { finalReply: facts.finalReply } : {}),
+        ...(checkpoint !== undefined ? { checkpoint } : {}),
       },
       [roundNote(round, "stopped")],
     );
+  // A mechanical WIP push means the child did not declare the work ready for
+  // review. Keep the unit branch as the resumption point and abort this
+  // attempt; an ordinary push still takes the established recover-PR path.
+  if (facts.status === "failed" && checkpoint !== undefined) {
+    const cause =
+      facts.failure?.kind === "provider_transient"
+        ? "the model provider's transport retry budget was spent"
+        : "it failed before finishing";
+    return end(
+      next,
+      {
+        kind: "aborted",
+        reason: `⚠️ The coding child ended because ${cause}; the branch carries the interrupted work at \`${checkpoint.sha.slice(0, 7)}\` on \`${checkpoint.branch}\`. Re-issue the request to resume from it instead of starting over.`,
+        round,
+        reviewRounds: next.reviewRounds,
+      },
+      [roundNote(round, "aborted")],
+    );
+  }
   // A failed coding child no longer aborts outright: the pr-check looks at the
-  // branch first — a push before the death is recovered as the round's pull
-  // request (agent-ship items 10 and 15), and only a branch with
-  // nothing on it ends the unit with the child's own reason.
+  // branch first — an ordinary push before the death is recovered as the
+  // round's pull request, and only a branch with nothing on it ends the unit
+  // with the child's own reason.
   if (facts.status === "failed")
     return {
       state: {
@@ -1745,6 +1802,7 @@ function enterChecks(s: UnitPipelineState, round: RoundRef, notes: CoordinatorNo
         waitMs,
         graced: false,
         retried: false,
+        refired: false,
       },
     },
     notes,
@@ -1764,14 +1822,16 @@ function enterChecks(s: UnitPipelineState, round: RoundRef, notes: CoordinatorNo
  *      (`expected`: a required check, or the repository's approve workflow
  *      whose run does not exist yet), or GitHub unreadable: the head waits on
  *      the settled event and is read again;
- *  (—) no check reported at all: one chunk of grace, never more;
+ *  (—) no required check reported: one chunk of grace, then the pull_request
+ *      event is re-fired once by closing and reopening the pull request;
  *  (c) every expected check reported green: the round proceeds with no wait. */
 function checksVerdict(
   checks: RoundChecks | undefined,
-  p: { retried: boolean; graced: boolean },
+  p: { retried: boolean; graced: boolean; refired: boolean },
   draft?: boolean,
 ):
   | { kind: "retry"; names: string[] }
+  | { kind: "refire" }
   | { kind: "failed"; failed: CheckFailure[] }
   | { kind: "draft" }
   | { kind: "pending" }
@@ -1791,14 +1851,18 @@ function checksVerdict(
   // person's "ready" changes anything — a red check above still gets its fix
   // round, since that work stands whether or not the pull request is a draft.
   if (draft === true) return { kind: "draft" };
+  const required = checks?.required ?? [];
+  const missing = checks?.expected ?? [];
+  const noRequiredReported = required.length > 0 && missing.length === required.length;
+  // A check launcher may report an unrelated workflow while every required
+  // context is still absent. Give it one normal chunk; if it remains empty,
+  // re-fire pull_request once. This is the same recovery a person performs for
+  // a CI run that exists but started no workflows.
+  if ((checks?.total === 0 || noRequiredReported) && !p.graced) return { kind: "grace" };
+  if (noRequiredReported && !p.refired) return { kind: "refire" };
   // GitHub unreadable answers as pending and is re-read at the chunk's end;
   // an expected check not yet reported (issue 2063) is pending the same way.
-  if (checks === undefined || checks.pending.length > 0 || (checks.expected?.length ?? 0) > 0)
-    return { kind: "pending" };
-  // No check reported at the head: one chunk of grace — the first check starts
-  // within minutes where CI exists — then the round proceeds, so a repository
-  // without CI costs one chunk per round and never idles (record 0055).
-  if (checks.total === 0 && !p.graced) return { kind: "grace" };
+  if (checks === undefined || checks.pending.length > 0 || missing.length > 0) return { kind: "pending" };
   return { kind: "green" };
 }
 
@@ -1810,14 +1874,15 @@ function checksVerdict(
  *  is still pending (issue 1991); only a head with no failed check waits a
  *  chunk inside the step's ask on what is unreadable or pending and then
  *  proceeds — the ending's facts read names what is still pending; a head with
- *  no check reported waits one chunk of grace and never more; a green head
- *  proceeds with no wait added. */
+ *  no required check reported gets one grace chunk and one event re-fire; a
+ *  green head proceeds with no wait added. */
 function settleChecks(
   s: UnitPipelineState,
   p: Extract<Phase, { at: "checks" }>,
   checks: RoundChecks | undefined,
   retried?: boolean,
   draft?: boolean,
+  refired?: boolean,
 ): Transition {
   const { round } = p;
   const wait = (over: Partial<Extract<Phase, { at: "checks-wait" }>>): Transition => ({
@@ -1833,11 +1898,23 @@ function settleChecks(
         waitMs: p.waitMs,
         graced: p.graced,
         retried: p.retried,
+        refired: p.refired,
         ...over,
       },
     },
     notes: [],
   });
+  // The pull_request re-fire is an effect ask after a whole grace chunk with
+  // no required check. Whether GitHub accepted it or not, spend the one attempt
+  // and read immediately: that read registers the ordinary bounded wait. A
+  // successful effect adds the round boundary the card renders.
+  if (p.refire === true) {
+    const { refire: _refire, ...read } = p;
+    return {
+      state: { ...s, phase: { ...read, n: p.n + 1, refired: true } },
+      notes: refired === true ? [roundNote(p.round, "checks_restarted")] : [],
+    };
+  }
   // The retry ask. Dispatched: wait for the head to settle, then read again;
   // a second failure is the finding. NOT dispatched (`retried: false` — no
   // re-runnable run behind the checks, or GitHub refused): the one re-run is
@@ -1858,6 +1935,11 @@ function settleChecks(
         state: { ...s, phase: { ...p, n: p.n + 1, retry: verdict.names } },
         notes: [],
       };
+    case "refire":
+      return {
+        state: { ...s, phase: { ...p, n: p.n + 1, refire: true } },
+        notes: [],
+      };
     case "failed": {
       const findings = [...(s.findingsByRound[round.index] ?? []), ...verdict.failed.map(checkFinding)];
       const next: UnitPipelineState = {
@@ -2387,7 +2469,8 @@ export function applyReturn(s: UnitPipelineState, ret: StepReturn): Transition {
       // The hosted parent's hard stop landed while this child ran (record 0060;
       // issue 1924): the unit ends stopped as the child ends, whatever the
       // child's own status — the runner runs nothing more of it.
-      if (r.stopped === true)
+      if (r.stopped === true) {
+        const checkpoint = p.round.kind === "review" ? undefined : interruptedCheckpoint(clocked, r.run.pushed);
         return end(
           clocked,
           {
@@ -2396,14 +2479,33 @@ export function applyReturn(s: UnitPipelineState, ret: StepReturn): Transition {
             round: p.round,
             reviewRounds: s.reviewRounds,
             ...(r.run.finalReply !== undefined ? { finalReply: r.run.finalReply } : {}),
+            ...(checkpoint !== undefined ? { checkpoint } : {}),
           },
           [roundNote(p.round, "stopped")],
         );
+      }
       if (r.run.status === "interrupted") {
         const cause = r.run.interruption;
-        // A dead CODING child may have pushed before the ledger closed it: the
-        // pr-check recovers the branch. A review child has nothing on the
-        // branch to recover, so its interruption still ends the unit at once.
+        const checkpoint = interruptedCheckpoint(clocked, r.run.pushed);
+        // A mechanical WIP checkpoint is deliberately not opened for review:
+        // the interrupted child never declared it finished. The next attempt
+        // starts from the unit branch at that head.
+        if (p.round.kind !== "review" && checkpoint !== undefined)
+          return end(
+            clocked,
+            {
+              kind: "interrupted",
+              round: p.round,
+              runId: p.runId,
+              reviewRounds: s.reviewRounds,
+              ...(cause !== undefined ? { cause } : {}),
+              checkpoint,
+            },
+            [roundNote(p.round, "aborted")],
+          );
+        // A dead CODING child may have pushed normally before the ledger closed
+        // it: the pr-check recovers that branch. A review child has nothing on
+        // the branch to recover, so its interruption still ends the unit at once.
         if (p.round.kind !== "review")
           return {
             state: {
@@ -2438,7 +2540,7 @@ export function applyReturn(s: UnitPipelineState, ret: StepReturn): Transition {
       return settlePrCheck(clocked, p, (ret as Extract<StepReturn, { type: "pr-check" }>).pr);
     case "checks": {
       const r = ret as Extract<StepReturn, { type: "checks" }>;
-      return settleChecks(clocked, p, r.checks, r.retried, r.draft);
+      return settleChecks(clocked, p, r.checks, r.retried, r.draft, r.refired);
     }
     case "checks-wait":
       // The event fired or the chunk elapsed either way the head is read again.
@@ -2455,6 +2557,7 @@ export function applyReturn(s: UnitPipelineState, ret: StepReturn): Transition {
             waitMs: p.waitMs,
             graced: p.graced,
             retried: p.retried,
+            refired: p.refired,
           },
         },
         notes: [],
@@ -2725,6 +2828,10 @@ export function renderUnitReport(
       ? `Findings below ${level}, left as-is: ${skipped.map((f) => `${f.id} (${f.severity}) — ${f.title}`).join("; ")}`
       : undefined;
   const join = (parts: Array<string | undefined>) => parts.filter(Boolean).join("\n\n");
+  const checkpointLine = (checkpoint: { branch: string; sha: string } | undefined) =>
+    checkpoint === undefined
+      ? undefined
+      : `The branch carries the interrupted work at \`${checkpoint.sha.slice(0, 7)}\` on \`${checkpoint.branch}\`; re-issue to resume from it instead of starting over.`;
   switch (e.kind) {
     case "merged":
       if (e.by === "other")
@@ -2873,9 +2980,11 @@ export function renderUnitReport(
         aside(reissue),
       ]);
     case "stopped":
-      if (!shows(verbosity, "verbose")) return `${e.mode === "hard" ? "⛔" : "⏹"} Stopped.${prLine}`;
+      if (!shows(verbosity, "verbose"))
+        return join([`${e.mode === "hard" ? "⛔" : "⏹"} Stopped.${prLine}`, checkpointLine(e.checkpoint)]);
       return join([
         `${e.mode === "hard" ? "⛔" : "⏹"} Ship stopped by operator (${e.mode} stop) after ${rounds}.${prLine}`,
+        checkpointLine(e.checkpoint),
         writeUpPointer(
           s,
           e.round.kind,
@@ -2930,7 +3039,7 @@ export function renderUnitReport(
         reissue,
       ]);
     case "interrupted":
-      return shipInterruptedNote(prUrl, e.cause, (s.input.idleDays ?? 0) > 0);
+      return join([shipInterruptedNote(prUrl, e.cause, (s.input.idleDays ?? 0) > 0), checkpointLine(e.checkpoint)]);
     case "idle_expired":
       return "⌛ Idle expired: no reply continued this unit before its idle window closed.";
     case "refused":

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

@@ -18,6 +18,8 @@ import type { Handoff } from "./handoff.js";
 export interface PushedHeadFact {
   ref: string;
   sha: string;
+  /** Mechanical WIP checkpoints are preserved work, not a completed agent push. */
+  by?: "push" | "salvage";
   at?: number;
 }
 

package/dist/assets/src/deploy/liveGate.ts

@@ -22,6 +22,9 @@ export interface HealthzBody {
   build?: { commit?: unknown; builtAt?: unknown } | unknown;
   /** ISO process start — `deploy restart`'s identity (the image, hence `build.commit`, is unchanged). */
   startedAt?: unknown;
+  /** A refusal-only production boot's public reason. Such a generation owns a
+   *  port so the operator can diagnose it, but is never live. */
+  config?: unknown;
 }
 
 /** Parse a `/healthz` response body; undefined when it is not a JSON object
@@ -83,6 +86,11 @@ function decideReady<Identity>(
   let reason: string;
   if (!body) {
     reason = "/healthz not answering with JSON (container restarting, or unreachable)";
+  } else if (body.ok !== true) {
+    reason =
+      typeof body.config === "string" && body.config !== ""
+        ? `config: ${body.config}`
+        : "/healthz reports this container is not ready";
   } else {
     const verdict = identify(body);
     if (verdict.live) return { kind: "live", ...verdict.identity };

package/dist/assets/src/deploy/profile.ts

@@ -79,6 +79,14 @@ export const profileSchema = z.object({
   /** Where the bot's runtime config comes from at deploy time; `deploy all`
    *  materializes it into the image's build context. */
   configSource: source,
+  /** The ingress-token subject allowed to stop the bot container. Rendered as
+   *  a Worker var, so config recovery never depends on the runtime document it
+   *  may be repairing. Absent disables the restart route. */
+  restart: z
+    .object({
+      deployer: z.string().regex(/^[A-Za-z0-9_.:@/-]+$/, "an ingress identity subject, without whitespace"),
+    })
+    .optional(),
   /** Where `secrets put` reads values from: a directory of `<NAME>` files, or
    *  `op://Vault/Item` with the secret's name as the field. Optional: the
    *  secrets tooling has its own default directory. */

package/dist/assets/src/deploy/restart.ts

@@ -18,34 +18,25 @@ import { profileUrls, type DeploymentProfile } from "./profile.js";
 // (src/deploy/run.ts `runBotRestart`), so both sides are unit-tested here and
 // nothing in this file imports node:*.
 //
-// Authorization: the bearer must be an entry of the bot's own
-// `SWITCHBOARD_INGRESS_TOKENS` map whose `http:<subject>` actor holds
-// `deploy:write` in the bot's config (`grants`, authorization.md item 9) — the
-// very action the `deploy.restart` command declares, so the Worker route is
-// authorized exactly as `/api/deploy.restart` would be if the bot served it.
-// Two halves, because the two sides hold different things: the Worker holds the
-// token map (it fires scheduled runs with the `cron` entry) and can tell WHO a
-// bearer is — `authenticateRestart`, 401/503 without touching the container —
-// but the grants live in the container's config, so it asks the bot
-// (`POST /admin/restart/authorize`, src/channels/adminRestartAuthorize.ts) whether
-// that subject holds the action and relays the answer (`parseRestartAuthorization`).
-// The Worker names the subject it authenticated in `RESTART_SUBJECT_HEADER` and
-// the bot decides the grant for THAT subject without re-authenticating the
-// bearer: the two sides can hold different generations of the token map (a
-// `wrangler secret put` reaches the Worker's env at once and the container's
-// only after a restart), so re-authenticating in the container would refuse the
-// very rotation the restart exists to finish. The header is trustworthy because
-// the container is reachable only through the Worker, which strips it from every
-// proxied request (`stripRestartSubject`) and sets it only on its own internal
-// call. The bot's own `/admin/crash` runs the whole check in one place
-// (`authorizeRestart`).
+// Authorization stays entirely on the Worker side: the bearer is an entry of
+// `SWITCHBOARD_INGRESS_TOKENS`, and its subject must equal
+// `SWITCHBOARD_RESTART_DEPLOYER`, rendered from the deployment profile (or set
+// directly as a Worker var). The route never asks the container or its runtime
+// grants: a missing/invalid config is exactly when recovery must still work.
+// The bot's separate `/admin/crash` check still uses `authorizeRestart`, the
+// ordinary runtime-grant path for a route served by the bot itself.
 //
 // The route's URL is the installation's: the deployment profile names the
 // bot's hostname, `planRestart` derives `https://<bot>/admin/restart` from it.
 
 /** The operator's env var holding a `SWITCHBOARD_INGRESS_TOKENS` bearer with `deploy:write`. */
 export const RESTART_TOKEN_ENV = "SWITCHBOARD_DEPLOY_TOKEN";
-/** The scope the bearer's identity must carry — the `deploy.restart` command's own. */
+/** Worker var naming the authenticated ingress subject allowed to restart. It
+ * is rendered from the deployment profile and never forwarded into the
+ * container, so a broken runtime config cannot lock out its own recovery. */
+export const RESTART_DEPLOYER_ENV = "SWITCHBOARD_RESTART_DEPLOYER";
+/** The scope the command declares. The Worker-side restart grant above is the
+ * independent recovery authorization for the route. */
 export const RESTART_SCOPE = "deploy:write";
 
 // ---- refusal decision (Worker side; the CLI relies on the 409) -----------------------------
@@ -122,6 +113,25 @@ export function constantTimeEqual(a: string, b: string): boolean {
   return diff === 0;
 }
 
+/** Authorize the already-authenticated ingress subject against the deployment
+ * profile's Worker var. This check deliberately has no ConfigStore input: the
+ * route exists to recover a missing or invalid runtime config. */
+export function authorizeRestartDeployer(subject: string, configured: string | undefined): RestartAuth {
+  if (!configured)
+    return {
+      ok: false,
+      status: 503,
+      reason: `restart disabled: ${RESTART_DEPLOYER_ENV} is not set by the deployment profile or Worker env`,
+    };
+  if (!constantTimeEqual(subject, configured))
+    return {
+      ok: false,
+      status: 403,
+      reason: `forbidden: identity "${subject}" is not the restart deployer named by ${RESTART_DEPLOYER_ENV}`,
+    };
+  return { ok: true, subject };
+}
+
 /** Find the presented bearer among the configured tokens by comparing against
  *  EVERY entry (fixed work; a plain object-key lookup would let a probe learn
  *  which prefixes exist from timing). Returns the matched identity, if any. */
@@ -134,14 +144,14 @@ export function lookupConstantTime<T>(tokens: Record<string, T>, presented: stri
 export type RestartAuth = { ok: true; subject: string } | { ok: false; status: 401 | 403 | 503; reason: string };
 export type RestartAuthn = { ok: true; identity: IngressIdentity } | { ok: false; status: 401 | 503; reason: string };
 
-/** The bot route the Worker asks before stopping the container: 200 `{ ok, subject }`
- *  when the bearer's actor holds `deploy:write`, else `authorizeRestart`'s 401/403/503. */
+/** Compatibility contract for a bot-served authorization probe. The external
+ * restart route no longer calls it; keeping the pure shape avoids breaking an
+ * older shim while a fleet rolls between versions. */
 export const RESTART_AUTHORIZE_PATH = "/admin/restart/authorize";
-/** The header the Worker sets on its internal authorize call, naming the subject it
- *  authenticated from its own token map; stripped from every proxied request. */
 export const RESTART_SUBJECT_HEADER = "x-switchboard-restart-subject";
 
-/** WHETHER, for a subject the Worker already authenticated: the bot's grants alone. */
+/** WHETHER for the bot's own runtime-granted admin routes (`/admin/crash`).
+ * The Worker's restart route deliberately does not call this path. */
 export function authorizeRestartSubject(subject: string, grantsFor: GrantsLookup): RestartAuth {
   if (subject.trim() === "") return { ok: false, status: 401, reason: "unauthorized: an empty subject" };
   if (!hasAction(grantsFor(`http:${subject}`).actions, RESTART_SCOPE))
@@ -153,8 +163,7 @@ export function authorizeRestartSubject(subject: string, grantsFor: GrantsLookup
   return { ok: true, subject };
 }
 
-/** The request without the subject header — what the Worker forwards to the container for
- *  every route it does not answer itself, so a caller can never assert a subject. */
+/** Strip the compatibility probe's trusted header from ordinary proxying. */
 export function stripRestartSubject(request: Request): Request {
   if (!request.headers.has(RESTART_SUBJECT_HEADER)) return request;
   const headers = new Headers(request.headers);
@@ -232,11 +241,8 @@ export function authorizeIngressBearer(
   return { ok: true, subject: identity.subject };
 }
 
-/** The bot's `POST /admin/restart/authorize` answer, as the Worker reads it: 200
- *  `{ ok: true, subject }` → allowed; 401 / 403 / 503 `{ ok: false, error }` →
- *  relayed as they are; anything else (a bot without the route, a non-JSON body,
- *  an unexpected status) → 503, fail-closed — the Worker never restarts on an
- *  answer it cannot read. */
+/** Parse the compatibility probe's answer. New restart routes authorize on the
+ * Worker without making this request. */
 export function parseRestartAuthorization(status: number, text: string): RestartAuth {
   let parsed: unknown;
   try {
@@ -358,6 +364,9 @@ export interface RestartPlan {
   target: "bot";
   adminUrl: string;
   healthUrl: string;
+  /** The source and durable base document this restart must prove equal before
+   * it stops anything. `generation` is the document version read at runtime. */
+  config: { source: string; document: "base"; stateWorkerUrl?: string };
   tokenEnv: string;
   force: boolean;
   /** Budget for waiting out a 409 (runs in flight) before giving up. */
@@ -373,6 +382,11 @@ export function planRestart(opts: RestartOptions, profile: DeploymentProfile): R
     target: opts.only,
     adminUrl: urls.botAdminRestartUrl,
     healthUrl: `${urls.publicBaseUrl}/healthz`,
+    config: {
+      source: profile.configSource,
+      document: "base",
+      ...(urls.stateWorkerUrl !== undefined ? { stateWorkerUrl: urls.stateWorkerUrl } : {}),
+    },
     tokenEnv: RESTART_TOKEN_ENV,
     force: opts.force,
     waitMaxMs: opts.waitMaxMinutes * 60_000,
@@ -386,7 +400,7 @@ export function formatRestartPlan(plan: RestartPlan): string {
     ? `preflight FORCED — in-flight runs are drained (SIGTERM), killed only at the drain deadline`
     : `refused while runs are in flight or draining (409) — retry every ${plan.pollMs / 1000}s up to ${plan.waitMaxMs / 60_000} min`;
   return [
-    `Restart ${plan.target}: POST ${plan.adminUrl} (bearer from $${plan.tokenEnv}, needs ${RESTART_SCOPE}) — ${gate}`,
+    `Restart ${plan.target}: prove ${plan.config.source} matches document "${plan.config.document}" on ${plan.config.stateWorkerUrl ?? "the missing state Worker"}, then POST ${plan.adminUrl} (bearer from $${plan.tokenEnv}, needs ${RESTART_SCOPE}) — ${gate}`,
     `  then wait until ${plan.healthUrl} answers not draining with a later startedAt (up to ${Math.round(plan.liveDeadlineMs / 60_000)} min: drain + cold start)`,
     `  no image build: the container restarts on the same build with the Worker's CURRENT secrets`,
   ].join("\n");