@coreplane/switchboard 1.248.0 → 1.249.0

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

@@ -4,7 +4,9 @@ import { redactSecrets } from "../redact.js";
 // docs/reference/specs/agent-ship.md item 14, agent-coding.md item 9): what a
 // coding child hands back beside its pull-request description when it ran for
 // a plan unit — where it departed from the unit and why, what it found and did
-// not do, and which of the unit's criteria it could not prove. It is data, not
+// not do, which of the unit's criteria it could not prove, and what of the
+// unit was already on the base before it began (`landed`, the fact the ship
+// machine ends a unit `already_landed` on, agent-ship.md item 12). It is data, not
 // prose in a final message: the child submits it through `submit_handoff` (the
 // same tool path as the description), the run record carries it, and the
 // parent posts it to the unit's board issue, where a person decides each row's
@@ -38,10 +40,24 @@ export interface HandoffUnproven {
   why: string;
 }
 
+/** A part of the unit's scope that was already on the base when the run
+ *  began — the fact the ship machine reads at round 0 (agent-ship.md item 12):
+ *  a handoff naming where the scope landed, beside a branch with no commits
+ *  over the base, ends the unit `already_landed` instead of aborting it. */
+export interface HandoffLanded {
+  /** What of the unit was already there. */
+  what: string;
+  /** Where it landed — the pull request or commit that carries it. */
+  where: string;
+}
+
 export interface Handoff {
   deviations: HandoffDeviation[];
   followUps: HandoffFollowUp[];
   unproven: HandoffUnproven[];
+  /** Absent on a handoff that named none and on a record written before the
+   *  list existed; every reader treats absent as empty. */
+  landed?: HandoffLanded[];
 }
 
 /** The most entries one list may carry: a handoff is a summary for a person,
@@ -58,25 +74,33 @@ const FIELDS: Readonly<Record<ListKey, readonly string[]>> = {
   deviations: ["from", "to", "why"],
   followUps: ["what", "where"],
   unproven: ["criterion", "why"],
+  landed: ["what", "where"],
 };
-const LISTS: readonly ListKey[] = ["deviations", "followUps", "unproven"];
+const LISTS: readonly ListKey[] = ["deviations", "followUps", "unproven", "landed"];
+/** The lists every handoff carries; `landed` is optional (its type says so). */
+const REQUIRED: ReadonlySet<ListKey> = new Set<ListKey>(["deviations", "followUps", "unproven"]);
 
-/** A handoff under construction: each list as entries keyed by `FIELDS`. It IS
- *  a `Handoff` once every entry carries its list's fields — which the two
- *  builders below guarantee — so the one conversion at their boundary is the
- *  table above standing in for three interface declarations. */
-type FieldLists = Record<ListKey, Record<string, string>[]>;
+/** A handoff under construction: each list as entries keyed by `FIELDS`, the
+ *  optional one present only when given. It IS a `Handoff` once every entry
+ *  carries its list's fields — which the two builders below guarantee — so the
+ *  one conversion at their boundary is the table above standing in for four
+ *  interface declarations. */
+type FieldLists = Record<Exclude<ListKey, "landed">, Record<string, string>[]> & {
+  landed?: Record<string, string>[];
+};
 
 const emptyLists = (): FieldLists => ({ deviations: [], followUps: [], unproven: [] });
 const asHandoff = (lists: FieldLists): Handoff => lists as unknown as Handoff;
 const asLists = (h: Handoff): FieldLists => h as unknown as FieldLists;
+/** A list's entries, an absent optional list read as empty. */
+const listOf = (lists: FieldLists, key: ListKey): Record<string, string>[] => lists[key] ?? [];
 
 export function emptyHandoff(): Handoff {
   return asHandoff(emptyLists());
 }
 
 export function isEmptyHandoff(h: Handoff): boolean {
-  return LISTS.every((k) => h[k].length === 0);
+  return LISTS.every((k) => listOf(asLists(h), k).length === 0);
 }
 
 function isRecord(v: unknown): v is Record<string, unknown> {
@@ -90,6 +114,7 @@ export function isHandoffShape(v: unknown): v is Handoff {
   if (!isRecord(v)) return false;
   return LISTS.every((key) => {
     const list = v[key];
+    if (list === undefined) return !REQUIRED.has(key);
     return (
       Array.isArray(list) &&
       list.every((entry) => isRecord(entry) && FIELDS[key].every((f) => typeof entry[f] === "string"))
@@ -105,18 +130,21 @@ const fieldList = (key: ListKey): string => {
 };
 
 /** Validate untrusted input (a tool call) into a Handoff: the three lists
- *  present (each may be empty), at most `HANDOFF_MAX_ITEMS` entries each,
- *  every field a non-empty string of at most `HANDOFF_MAX_FIELD_CHARS` once
- *  trimmed; unknown keys are dropped. A refusal is a string naming the path,
- *  never a throw, so the model can fix the object and call again. */
+ *  present (each may be empty) and `landed` when given, at most
+ *  `HANDOFF_MAX_ITEMS` entries each, every field a non-empty string of at most
+ *  `HANDOFF_MAX_FIELD_CHARS` once trimmed; unknown keys are dropped. A refusal
+ *  is a string naming the path, never a throw, so the model can fix the object
+ *  and call again. */
 export function parseHandoff(input: unknown): ParsedHandoff {
   if (!isRecord(input))
     return { ok: false, error: "handoff: must be an object with deviations, followUps and unproven" };
   const out = emptyLists();
   for (const key of LISTS) {
     const list = input[key];
+    if (list === undefined && !REQUIRED.has(key)) continue;
     if (!Array.isArray(list))
       return { ok: false, error: `${key}: must be an array (empty when there is nothing to say)` };
+    out[key] = [];
     if (list.length > HANDOFF_MAX_ITEMS) return { ok: false, error: `${key}: at most ${HANDOFF_MAX_ITEMS} entries` };
     for (let i = 0; i < list.length; i++) {
       const entry: unknown = list[i];
@@ -132,7 +160,7 @@ export function parseHandoff(input: unknown): ParsedHandoff {
           };
         clean[f] = value;
       }
-      out[key].push(clean);
+      out[key]!.push(clean);
     }
   }
   return { ok: true, handoff: asHandoff(out) };
@@ -144,12 +172,14 @@ export function parseHandoff(input: unknown): ParsedHandoff {
  *  run record or a board issue. */
 export function redactHandoff(h: Handoff, redact: (s: string) => string = redactSecrets): Handoff {
   const out = emptyLists();
+  const lists = asLists(h);
   for (const key of LISTS) {
-    for (const entry of asLists(h)[key]) {
+    if (lists[key] === undefined) continue;
+    out[key] = lists[key].map((entry) => {
       const clean: Record<string, string> = {};
       for (const f of FIELDS[key]) clean[f] = redact(entry[f]!);
-      out[key].push(clean);
-    }
+      return clean;
+    });
   }
   return asHandoff(out);
 }
@@ -193,14 +223,18 @@ function entryLines(h: Handoff): Array<{ list: ListKey; bullet: string; row: str
       const text = `${u.criterion} — ${u.why}`;
       return { list: "unproven" as const, bullet: text, row: `Unproven: ${text}` };
     }),
+    ...(h.landed ?? []).map((l) => {
+      const text = `${l.what} — ${l.where}`;
+      return { list: "landed" as const, bullet: text, row: `Landed: ${text}` };
+    }),
   ];
 }
 
 /** Each entry as one line, list by list — a deviation as `Deviation: from → to
  *  — why`, a follow-up as `what — where`, an unproven criterion as `Unproven:
- *  criterion — why` — the same words the ledger rows carry, for a reader that
- *  wants the handoff as plain lines (the thread's artifacts block). Empty for
- *  an empty handoff. */
+ *  criterion — why`, a landed part as `Landed: what — where` — the same words
+ *  the ledger rows carry, for a reader that wants the handoff as plain lines
+ *  (the thread's artifacts block). Empty for an empty handoff. */
 export function handoffLines(h: Handoff): string[] {
   return entryLines(h).map((e) => e.row);
 }
@@ -227,6 +261,7 @@ const HEADINGS: Readonly<Record<ListKey, string>> = {
   deviations: "### Deviations",
   followUps: "### Follow-ups",
   unproven: "### Unproven",
+  landed: "### Already landed",
 };
 
 /**

package/dist/assets/src/core/trace/workerTrace.ts

@@ -57,9 +57,15 @@ export function shimRoute(pathname: string): string | undefined {
   // The model proxy's two routes (docs/reference/specs/model-proxy.md): a bounded
   // request per model call, forwarded to the container like everything else.
   if (pathname === "/v1/messages" || pathname === "/v1/chat/completions") return "model-proxy";
-  // The pi harness's three routes (docs/reference/specs/harness-pi.md item 7): a
-  // run's extension asking for its tools, a verdict, a relayed tool's result.
-  if (pathname === "/harness/tools" || pathname === "/harness/authorize" || pathname === "/harness/tool")
+  // The pi harness's four routes (docs/reference/specs/harness-pi.md item 7): a
+  // run's extension asking for its tools, a verdict, a relayed tool's result,
+  // how a compaction is written.
+  if (
+    pathname === "/harness/tools" ||
+    pathname === "/harness/authorize" ||
+    pathname === "/harness/tool" ||
+    pathname === "/harness/compaction"
+  )
     return "harness";
   if (pathname === "/docs" || pathname.startsWith("/docs/")) return "docs";
   if (pathname === "/" || pathname === "/index.html") return "page";

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

@@ -0,0 +1,327 @@
+// Channel abstraction. A channel (Slack, CLI, Discord, HTTP, ...) is only a
+// transport: it receives text from a user somewhere, hands it to the core
+// dispatcher as an IncomingMessage, and provides a ChannelIO for the core to
+// talk back through. Everything else — config resolution, permissions, agent
+// selection, execution — is channel-agnostic and lives in the dispatcher.
+
+/** An image the user attached, already downloaded and base64-encoded. */
+export interface ImageAttachment {
+  /** e.g. "image/png" — adapters only pass types every provider accepts */
+  mediaType: string;
+  /** base64 payload, no data: URI prefix */
+  data: string;
+  name?: string;
+}
+
+/**
+ * A non-image file the user attached, already downloaded. Two representations
+ * share this carrier, keyed by `mediaType`:
+ * - PDFs (`mediaType === "application/pdf"`) → `data` is the base64 payload,
+ *   rendered as a provider-native document block where supported.
+ * - Text/code/CSV/log files (any other `mediaType`) → `data` is the decoded
+ *   UTF-8 file content, inlined as a fenced text part.
+ */
+export interface DocumentAttachment {
+  mediaType: string;
+  data: string;
+  name?: string;
+}
+
+/** A file left on the platform by reference (record 0033): what the store's
+ *  copy needs and what the turn's line says — metadata only, never bytes. */
+export interface StagedFile {
+  name: string;
+  size: number;
+  /** The platform's media type, as the object's content type and the line's word. */
+  type: string;
+  /** The platform's private download URL (Slack: `url_private`); the bot's Worker reads it, the bot never does. */
+  url: string;
+  /** The platform's id of the message that carried the file — the per-message segment of its key. */
+  messageId: string;
+}
+
+export interface IncomingMessage {
+  /**
+   * Scope key for channel-level config. Must be globally unique across
+   * platforms — adapters namespace with a platform prefix, e.g. "slack:C0123".
+   */
+  channelId: string;
+  /** Scope key for user-level config and permissions, e.g. "slack:U0123". */
+  userId: string;
+  /**
+   * Stable key for the conversation: same thread => same key => same
+   * workspace/sandbox. e.g. "slack:C0123:1712345.6789".
+   */
+  threadKey: string;
+  /** The request text, already stripped of platform artifacts (mentions etc.). */
+  text: string;
+  /**
+   * Human display name for the channel/conversation (e.g. "general"),
+   * for run labels and other human-facing surfaces. Adapters resolve it from their
+   * platform; the core stays channel-agnostic and treats it as an optional hint —
+   * absent for adapters that have no name (HTTP/MCP) or when a lookup fails.
+   */
+  channelName?: string;
+  /**
+   * Human display name for the sending user (e.g. "alice"). Same contract as
+   * `channelName`: an optional adapter-provided hint, never required by the core.
+   */
+  userName?: string;
+  /**
+   * A link back to the triggering message on its platform (a Slack permalink),
+   * for human-facing surfaces such as the run page's Request block. Optional
+   * adapter hint like the names above — absent for HTTP/MCP.
+   */
+  sourceUrl?: string;
+  /**
+   * The app that posted the message for the person `userId` names, when the
+   * message was not their own (a Claude Code session relaying a request from
+   * its owner's thread, docs/reference/specs/slack-channel.md item 13) — its
+   * display name. Absent when the person posted the message themselves.
+   */
+  relayedBy?: string;
+  /**
+   * The same app as a platform-namespaced actor id (`slack:bot:<bot_id>`), set
+   * exactly when `relayedBy` is: authorization treats the run as that app
+   * acting on behalf of `userId`, so a relayed request never holds more than
+   * the app and the person both hold (authorization.md item 14).
+   */
+  postedBy?: string;
+  /**
+   * The credential that authenticated the request, as a platform-namespaced
+   * actor id (`http:<subject>`, `mcp:<subject>`, `cli:local`), when the
+   * adapter resolved it to the PERSON it is bound to and named them in
+   * `userId` (authorization.md item 15: an ingress token entry's `email`, the
+   * CLI's `SWITCHBOARD_CLI_EMAIL`). Identity, never authority: the run, its
+   * record and its costs are the person's; what the run may do is exactly what
+   * config grants this credential — every gate decides on the actor
+   * `resolveChatActor` builds from it. Absent when the sender and the
+   * credential are one (Slack, an unbound token) or when the request was
+   * relayed (`postedBy`).
+   */
+  authenticatedAs?: string;
+  /** Images attached to the triggering message, if any. */
+  images?: ImageAttachment[];
+  /** Non-image files (PDFs, text/code/CSV/logs) on the triggering message, if any. */
+  documents?: DocumentAttachment[];
+  /** Files the inline path cannot carry — too large, or a type the model does
+   *  not read — left on the platform by reference (record 0033): a run with a
+   *  workspace stages them into `attachments/` before its turn; the bytes never
+   *  enter the bot. Present only when the artifact store is configured. */
+  staged?: StagedFile[];
+  /** The platform's id of this message (Slack's `ts`, the value `staged[].messageId`
+   *  carries): the `input` event and the files received with it name it, so the
+   *  run page joins them by data. Absent for a channel with no message id
+   *  (CLI, HTTP, MCP) → `messageIdOf` uses the run id. */
+  messageId?: string;
+  /**
+   * When OUR process saw the message (ms epoch, from the adapter's clock at its
+   * entry — never from a body or a platform stamp): the run's window opens
+   * here (docs/reference/specs/tracing.md). Absent (tests, older callers) → the dispatcher
+   * reads its own clock at entry.
+   */
+  receivedAt?: number;
+  /**
+   * When the platform says the message was posted (Slack's `ts`), for the
+   * `queued … before we saw it` caption; a caption, never part of a duration.
+   */
+  originAt?: number;
+}
+
+/** The request's message id as its `input` event and its received files record it:
+ *  the platform's when the adapter gave one, else the run id — one deterministic
+ *  value both writers reach for, so a channel without message ids still joins. */
+export function messageIdOf(msg: Pick<IncomingMessage, "messageId">, runId: string): string {
+  return msg.messageId ?? runId;
+}
+
+export interface HistoryItem {
+  role: "user" | "assistant";
+  text: string;
+  /** When the platform stamps its messages: the turn's time in epoch ms, so a
+   *  follow-up can tell the lines written after a run ended from the ones that
+   *  run already saw (docs/reference/specs/session-log.md item 9). */
+  at?: number;
+  /** Images attached to this turn, if any (user turns only in practice). */
+  images?: ImageAttachment[];
+  /** Non-image files attached to this turn, if any (user turns only in practice). */
+  documents?: DocumentAttachment[];
+}
+
+/** What the run is doing right now, typed so each channel draws it in its
+ *  own dialect and none re-parses text to find a command
+ *  (docs/reference/specs/run-visibility.md item 2). `command` is a shell call
+ *  with the command it was given — Slack draws it as a code block; a text
+ *  surface flattens it to one `→ $ …` line. `line` is the one-line trace
+ *  every other event makes (`→ read src/a.ts`, `✓ bash: exit 0`, `💭 thought
+ *  for 5.1s`). */
+export type StatusActivity = { kind: "command"; tool: string; command: string } | { kind: "line"; text: string };
+
+/** A structured progress frame; adapters decide how to render it. */
+export interface StatusUpdate {
+  /** one-line headline, e.g. "⚡ review on anthropic/claude-fable-5 · 42s" */
+  title: string;
+  /** the agent's checklist and any lead lines, one per line */
+  detail?: string;
+  /** the current activity, live frames only — a close never carries it */
+  activity?: StatusActivity;
+  /**
+   * The run's live page, rendered by each channel in its own short form
+   * (Slack: a one-line `<url|label>` hyperlink; CLI: the bare URL). Kept out of
+   * `detail` on purpose: the capability URL is 100+ chars and, inlined, wraps
+   * to four lines on Slack — enough to push the card behind the "Show more"
+   * fold, where EVERY edit (5 s heartbeat included) flashes the card open and
+   * shut and shoves the thread around.
+   */
+  link?: { url: string; label: string };
+}
+
+/** A live, updatable progress indicator (e.g. an edited Slack message). */
+export interface StatusHandle {
+  update(frame: StatusUpdate): void;
+  done(frame: StatusUpdate): Promise<void>;
+  /** Where the indicator lives, when it is a message another process could
+   *  edit (Slack: channel + ts) — recorded on the run ledger so a resumed run
+   *  closes the same card (docs/reference/specs/run-history.md item 35). Absent for a
+   *  no-op handle. */
+  handle?: { channel: string; ts: string };
+}
+
+/** How a run ended, as reported to the channel once its record is closed.
+ *  `interrupted` is a run whose pi container was replaced under it
+ *  (docs/reference/specs/harness-pi.md item 16): its request runs again as a
+ *  new run on the same channel handle, whose own receipt follows. */
+export type RunFinalStatus = "completed" | "failed" | "stopped_soft" | "stopped_hard" | "interrupted";
+
+/** The receipt a channel gets when the run behind its request finishes: the
+ *  run id (the `/runs/:id` record) and its terminal status. Never the view
+ *  token — a receipt names the run, it does not grant access to it. */
+export interface RunReceipt {
+  id: string;
+  status: RunFinalStatus;
+}
+
+/** A thread a channel opened for a child run (docs/reference/specs/thread-admission.md
+ *  item 6): the key the child is dispatched on and the handle its replies,
+ *  card and history go through. */
+export interface OpenedThread {
+  thread: {
+    /** The new thread's key, namespaced like every thread key (`slack:C…:<ts>`). */
+    threadKey: string;
+    /** A link to the thread's lead message on its platform, when the platform has one. */
+    sourceUrl?: string;
+  };
+  io: ChannelIO;
+}
+
+/** A minted one-shot upload (`ChannelIO.uploadTicket`): where the container
+ *  POSTs the bytes, and the call that shares the uploaded file into the
+ *  conversation once the POST succeeded. */
+export interface UploadTicket {
+  /** Accepts one POST of exactly the ticketed size; single use, short-lived. */
+  url: string;
+  /** Share the uploaded file into the conversation with `lead` as its message. */
+  complete(lead: string): Promise<void>;
+}
+
+/** What the core needs from a channel to serve one request. */
+/** What a channel shows for a confirmation (`ChannelIO.offer`): the id its
+ *  affordance carries back, the full command line to run, the one risk line
+ *  (empty when the command declares none), the footer naming the scope that
+ *  asked, and when the offer expires (ms epoch, the config object's clock). */
+export interface ConfirmationOffer {
+  id: string;
+  line: string;
+  risk: string;
+  footer: string;
+  expiresAt: number;
+  /** Present on a question's offer (record 0054): the refusal's sentence,
+   *  shown above the line, and the evidence naming the match, shown under it.
+   *  A channel that offers labels the same two actions Yes and No instead of
+   *  Run and Cancel; Yes redispatches the stored proposal, No cancels. */
+  question?: { text: string; evidence: string };
+}
+
+export interface ChannelIO {
+  /** Post a reply in the conversation. Adapter handles chunking/formatting. */
+  reply(text: string): Promise<void>;
+  /**
+   * Present when this channel has nowhere to deliver a reply (the resumed-run
+   * null channel, docs/reference/specs/run-history.md item 38): the reason, e.g.
+   * "no channel to deliver to". `reply` still resolves (it logs), but the run's
+   * seal must say `replyOk: false` with this reason — a reply nobody could
+   * receive was not delivered. Absent on every real channel.
+   */
+  undeliverable?: string;
+  /**
+   * Post `lead` as the message and `text` as an attached file beside it — for
+   * output too long to read as chat (a 100-tool `mcp show`): the channel's
+   * collapsible container rather than a run of chunked messages. Optional;
+   * a channel without attachments (or one whose upload fails) falls back to
+   * `reply(lead + text)` itself, so callers never branch on the outcome.
+   */
+  attach?(file: { name: string; text: string; lead: string }): Promise<void>;
+  /**
+   * Post `lead` as the message and `bytes` as a file beside it — a screenshot,
+   * a PDF, a recording a run produced in its workspace, for the person to see
+   * inline. The binary sibling of `attach`: bytes have no text fallback, so a
+   * channel that cannot take the file (no upload API, a failed upload) throws
+   * and the caller reports it. Optional; a channel without uploads leaves it
+   * out and the tool behind it says so.
+   */
+  attachFile?(file: { name: string; bytes: Uint8Array; lead: string }): Promise<void>;
+  /**
+   * A one-shot upload the run's CONTAINER performs (docs/reference/specs/agent-coding.md
+   * item 10, record 0033): the channel mints a URL that accepts exactly
+   * `size` bytes under `name`, the container POSTs the file to it, and
+   * `complete(lead)` shares it into the conversation with the lead. The bot
+   * process never holds the bytes — this is how a 1 GB recording reaches the
+   * thread. Optional; a channel without such an API (the CLI, HTTP) leaves it
+   * out and the tool posts the run-page link through `reply` instead.
+   */
+  uploadTicket?(file: { name: string; size: number }): Promise<UploadTicket>;
+  /**
+   * Show the confirmation a routed write is offered as
+   * (docs/reference/specs/routing-and-config.md item 25, record 0044): the full
+   * command line the router bound, its one risk line, the footer naming the
+   * scope that asked, and the id the channel's affordance carries back to
+   * `dispatchClick` — a button whose value is the id, on a channel with
+   * components. Optional; a channel without it (the CLI, an HTTP reply, the
+   * browser) is answered the pasteable line instead, and nothing below the
+   * seam names a channel. The channel shows the offer and holds nothing else:
+   * the row lives in the config object until the click or the expiry.
+   */
+  offer?(offer: ConfirmationOffer): Promise<void>;
+  /** Create a progress indicator. Adapters may return a no-op handle. */
+  status(initial: StatusUpdate): Promise<StatusHandle>;
+  /**
+   * Prior turns of this conversation, oldest first, excluding the triggering
+   * message and any bot status noise. Adapters without history return [].
+   */
+  history(): Promise<HistoryItem[]>;
+  /**
+   * Called once by the core when the run created for this request has been
+   * finished in the registry (agent runs AND inline command runs), before the
+   * reply goes out. Single-shot channels (HTTP) hand the receipt back to their
+   * caller so a machine client — e.g. the Worker shim firing a scheduled job —
+   * can name the run it caused. Optional: Slack/CLI need nothing from it.
+   */
+  runFinished?(receipt: RunReceipt): void;
+  /**
+   * Called once by the core the moment a run has been CREATED in the registry
+   * (before it executes), with the run id. The async HTTP ingress path uses it
+   * to answer `202 Accepted` with the run id while the run continues in the
+   * background; Slack/CLI need nothing from it. Optional, like runFinished.
+   */
+  runStarted?(started: { id: string }): void;
+  /**
+   * Open a thread of this channel's own for a child run
+   * (docs/reference/specs/thread-admission.md item 6): post `lead` where a new
+   * thread can start — top-level in this conversation's channel — and hand
+   * back the thread's key and a handle bound to it. Optional: a single-shot
+   * channel (HTTP, MCP) has no thread to open, and a spawn from such a channel
+   * is refused by name (`spawn_unsupported`); it never falls back to the
+   * parent's own thread.
+   */
+  openThread?(lead: string): Promise<OpenedThread>;
+}

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

@@ -187,6 +187,41 @@ export function decideRestarted(
   });
 }
 
+/** The words of a wait that ran out, per command: what was not done, how to
+ *  run it again, what `--force` would do instead. */
+export interface GaveUpWords {
+  notDone: string;
+  rerun: string;
+  force: string;
+}
+
+/** `deploy all`'s words: the release job is re-run once the runs finish. */
+export const DEPLOY_GAVE_UP_WORDS: GaveUpWords = {
+  notDone: "NOT deployed",
+  rerun: "re-run the deploy once they finish (a CI job: `gh run rerun RUN_ID --failed`)",
+  force: "--force to deploy over them (kills the runs in flight that no resume recovers)",
+};
+
+/** `deploy restart`'s words. */
+export const RESTART_GAVE_UP_WORDS: GaveUpWords = {
+  notDone: "NOT restarted",
+  rerun: "re-run `deploy restart` once they finish",
+  force: "--force to stop over them (kills the runs in flight that no resume recovers)",
+};
+
+/** The failure a preflight still refusing at the end of the wait budget
+ *  produces. The wait is only how long to hold before failing: it never ends
+ *  in a deploy over what refused (a rolled container kills the runs it drives,
+ *  and a handoff is a recovery, not a guarantee), so the line names the budget,
+ *  the refusal, that nothing was done, and the two ways forward. */
+export function preflightGaveUpLine(
+  waitMaxMs: number,
+  reason: string,
+  words: GaveUpWords = DEPLOY_GAVE_UP_WORDS,
+): string {
+  return `preflight still refusing after ${waitMaxMs / 60_000} min (${reason}) — ${words.notDone}; ${words.rerun}, or ${words.force}`;
+}
+
 /** The line printed on every preflight retry, so a long wait is never silent.
  *  `tag` names the command waiting (`deploy:all`, `deploy:restart`). */
 export function heartbeatLine(

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

@@ -53,20 +53,21 @@ export const RESTART_SCOPE = "deploy:write";
 export interface RestartVerdict {
   allow: boolean;
   forced: boolean;
-  /** What refuses (fail-closed: no JSON body, an impossible count). */
+  /** What refuses: runs in flight (a stop rolls the container under them), and the fail-closed cases (no JSON body, an impossible count). */
   problems: string[];
-  /** What is said but does not refuse: runs in flight (they hand off), a drain under way. */
+  /** What is said but does not refuse: a drain under way with nothing in flight. */
   warnings: string[];
   message: string;
 }
 /**
  * Whether the container may be stopped now — the deploy preflight's rules
  * (deploy/cloudflare/preflight.mjs `decide`) minus the rollout-state check (a
- * restart is not a rollout). Since the handoff (docs/reference/specs/run-history.md item
- * 39) runs in flight and a drain under way are WARNINGS, not refusals: SIGTERM
- * hands every resumable run to the next generation. Fail closed on a body
- * that is not JSON or an impossible count; `force` allows those anyway, with
- * the warning.
+ * restart is not a rollout). Runs in flight REFUSE: the stop rolls the
+ * container under them, and the handoff (docs/reference/specs/run-history.md
+ * item 39) is a recovery the next generation may fail, not a guarantee — the
+ * CLI waits the 409 out instead. A drain under way with nothing in flight is a
+ * warning. Fail closed on a body that is not JSON or an impossible count;
+ * `force` allows everything anyway, flagged, naming what it kills.
  */
 export function decideRestart(body: HealthzBody | undefined, opts: { force: boolean }): RestartVerdict {
   const problems: string[] = [];
@@ -79,8 +80,8 @@ export function decideRestart(body: HealthzBody | undefined, opts: { force: bool
     if (!Number.isInteger(body.inFlight) || (body.inFlight as number) < 0) {
       problems.push(`bot reports an impossible inFlight=${JSON.stringify(body.inFlight)} (counter bug or old Worker)`);
     } else if ((body.inFlight as number) > 0) {
-      warnings.push(
-        `${body.inFlight} run(s) in flight — handed to the next generation on SIGTERM (run-history item 39); they continue there`,
+      problems.push(
+        `${body.inFlight} run(s) in flight — a stop rolls the bot container under them (a handoff is a recovery, not a guarantee)`,
       );
     }
     if (body.draining === true)
@@ -98,14 +99,14 @@ export function decideRestart(body: HealthzBody | undefined, opts: { force: bool
       forced: true,
       problems,
       warnings,
-      message: `restart WARNING: stopping by force despite —\n${detail}`,
+      message: `restart WARNING: stopping by force despite —\n${detail}\n  this WILL kill the runs in flight that no resume recovers`,
     };
   return {
     allow: false,
     forced: false,
     problems,
     warnings,
-    message: `restart REFUSED —\n${detail}\n  wait and retry, or pass --force to stop blind`,
+    message: `restart REFUSED —\n${detail}\n  wait for them to finish and retry, or pass --force to stop over them`,
   };
 }