@coreplane/switchboard 1.202.0 → 1.203.0

package/dist/assets/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "switchboard",
-  "version": "1.202.0",
+  "version": "1.203.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "switchboard",
-      "version": "1.202.0",
+      "version": "1.203.0",
       "license": "Apache-2.0",
       "workspaces": [
         "web",
@@ -18806,7 +18806,7 @@
     },
     "packages/switchboard": {
       "name": "@coreplane/switchboard",
-      "version": "1.202.0",
+      "version": "1.203.0",
       "license": "Apache-2.0",
       "dependencies": {
         "@anthropic-ai/sdk": "^0.124.0",
@@ -18818,7 +18818,7 @@
         "zod": "^4.5.4"
       },
       "bin": {
-        "switchboard": "dist/cli.js"
+        "switchboard": "bin/switchboard.js"
       },
       "devDependencies": {
         "esbuild": "^0.28.2",

package/dist/assets/package.json

@@ -1,6 +1,6 @@
 {
   "name": "switchboard",
-  "version": "1.202.0",
+  "version": "1.203.0",
   "private": true,
   "description": "Mention it in Slack and an agent reviews the PR, ships the fix, or answers the question — on the model you choose, with its tools running where you decide.",
   "license": "Apache-2.0",

package/dist/assets/source.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.202.0",
-  "commit": "1da9e3cbb372db6a36b9218f2df3f33a9ed0a828",
-  "builtAt": "2026-09-11T21:24:21.512Z"
+  "version": "1.203.0",
+  "commit": "e3f155d00ca4b1131eb3bbe4d9274a825afa4e9e",
+  "builtAt": "2026-09-11T23:34:59.316Z"
 }

package/dist/assets/src/core/authz/policy.ts

@@ -112,6 +112,10 @@ export const POLICY: readonly Rule[] = [
   // ── help / schedules / deploy / env / setup ──────────────────────────────────────
   { action: "help:read", resource: "command", when: [grant("help:read")] },
   { action: "status:read", resource: "command", when: [grant("status:read")] },
+  // `delivery report` reads GitHub with the App's token and the caller's own
+  // visible runs: the grant admits the command (browsers through the read
+  // baseline, tokens minted with it); which runs join is the `runs:read` predicate.
+  { action: "delivery:read", resource: "command", when: [grant("delivery:read")] },
   { action: "schedule:read", resource: "command", when: [grant("schedule:read")] },
   { action: "deploy:read", resource: "command", when: [grant("deploy:read")] },
   { action: "deploy:write", resource: "command", when: [grant("deploy:write")] },

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

@@ -1,6 +1,7 @@
 import type { ChannelVisibility, Predicate } from "./authz/types.js";
 import type { RunEvent } from "./runEvents.js";
 import { isHeadMaterial, isSpanRecord } from "./runEvents.js";
+import { isHandoffShape, type Handoff } from "./ship/handoff.js";
 import {
   FRICTION_CATEGORIES,
   type CategoryTotals,
@@ -89,6 +90,13 @@ export interface RunRecord {
   /** The thread that started the run (`IncomingMessage.sourceUrl`), for the
    *  index's hover link. Optional as above. */
   sourceUrl?: string;
+  /** The typed handoff a coding child submitted (docs/reference/specs/agent-ship.md
+   *  item 14): its deviations from the plan unit, its follow-ups and the
+   *  criteria it could not prove — redacted like every stored string. Present
+   *  only on a run that submitted one (an affirmed empty handoff is stored as
+   *  three empty lists, distinguishable from none); absent on every other run
+   *  and on records written before it existed. */
+  handoff?: Handoff;
 }
 
 /** A run as a listing shows it: the record minus its events. `diagnosis` stays —
@@ -408,6 +416,9 @@ export function isRunRecord(v: unknown): v is RunRecord {
   )
     return false;
   if (!isOptionalString(r.activity) || !isOptionalString(r.sourceUrl) || !isOptionalString(r.userName)) return false;
+  // The handoff is checked for shape, not bounds (docs/reference/specs/agent-ship.md
+  // item 14): redaction may lengthen a stored string past the tool's limit.
+  if (r.handoff !== undefined && !isHandoffShape(r.handoff)) return false;
   if (typeof r.channelId !== "string" || typeof r.userId !== "string" || typeof r.threadKey !== "string") return false;
   // Absent on records written before the stamp existed (read as `unknown`); present → a known value.
   if (r.channelVisibility !== undefined && !CHANNEL_VISIBILITIES.includes(r.channelVisibility as ChannelVisibility))

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

@@ -116,7 +116,7 @@ export const SCHEDULES: readonly ScheduleDef[] = [
     cron: "*/10 * * * *",
     worker: "resident",
     description:
-      "Resident watchdog: re-arm dead refresh alarm chains (marking degraded(alarm-missed)), time out stuck onboarding, and create the refresh Workflow instance for residents whose lifecycle is `workflow`. Cadence must stay shorter than the resident SLEEP_AFTER (20m). Not a run.",
+      "Resident watchdog: create each resident's refresh Workflow instance when its ten-minute bucket is due, name a stale mid-flight marker by its instance, and time out stuck onboarding. Cadence must stay shorter than the resident SLEEP_AFTER (20m). Not a run.",
     action: { type: "watchdog" },
   },
 ];
@@ -376,9 +376,7 @@ export interface WatchdogSummary {
     action?: unknown;
     error?: string;
     disk?: unknown;
-    /** `alarm` or `workflow`: which scheduler drives this resident's refresh cycle. */
-    lifecycle?: unknown;
-    /** What the pass did about the resident's refresh Workflow instance (`workflow` residents only). */
+    /** What the pass did about the resident's refresh Workflow instance: `{id, action, why}`. */
     instance?: unknown;
   }>;
 }
@@ -396,6 +394,14 @@ function fullestDisk(results: WatchdogSummary["results"]): string | undefined {
   return best ? `${best.pct}% (${best.resource.replace(/^repo:/, "")})` : undefined;
 }
 
+/** The `action` word of a resident's refresh-instance outcome on a watchdog
+ *  pass (`created | duplicate | skipped | failed`), or undefined when the row
+ *  carries none. */
+function instanceActionOf(instance: unknown): string | undefined {
+  const action = (instance as { action?: unknown } | null | undefined)?.action;
+  return typeof action === "string" ? action : undefined;
+}
+
 /** Turn a watchdog pass (or the error it threw) into a firing record. A pass is
  *  `completed` when every resident was checked; any per-resident error — or a
  *  throw before the sweep — is `failed`, naming the first failing resident. */
@@ -407,10 +413,10 @@ export function watchdogFiring(
   if (result instanceof Error)
     return { schedule: schedule.name, firedAt, outcome: "failed", detail: cap(`watchdog threw: ${result.message}`) };
   const errors = result.results.filter((r) => r.error !== undefined);
-  const reArmed = result.results.filter((r) => r.action === "re-armed").length;
+  const created = result.results.filter((r) => instanceActionOf(r.instance) === "created").length;
   const timedOut = result.results.filter((r) => r.action === "provision-timed-out").length;
   const disk = fullestDisk(result.results);
-  const counts = `${result.count}/${result.cap} residents · ${reArmed} re-armed · ${timedOut} timed out · ${errors.length} errors${disk ? ` · disk max ${disk}` : ""}`;
+  const counts = `${result.count}/${result.cap} residents · ${created} refreshed · ${timedOut} timed out · ${errors.length} errors${disk ? ` · disk max ${disk}` : ""}`;
   const first = errors[0];
   return {
     schedule: schedule.name,

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

@@ -0,0 +1,246 @@
+import { redactSecrets } from "../redact.js";
+
+// The handoff (docs/decisions/0031-the-coordinator-runs-a-plan-not-a-pull-request.md,
+// 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
+// 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
+// disposition and amends the plan's follow-ups ledger while the plan is still
+// `proposed` — no bot path writes a plan record.
+//
+// Pure and dependency-light on purpose: `runRecord.ts` (node-free, shared with
+// the state Worker) imports the type and the shape check, so nothing here may
+// pull in zod or a Node built-in. The validator is hand-written like
+// `isRunRecord`; the redaction seam is the same import-free module every
+// surface uses.
+
+export interface HandoffDeviation {
+  /** What the unit said. */
+  from: string;
+  /** What was done instead. */
+  to: string;
+  why: string;
+}
+
+export interface HandoffFollowUp {
+  /** What was found and not done. */
+  what: string;
+  /** Where it belongs — a file, a unit, a spec. */
+  where: string;
+}
+
+export interface HandoffUnproven {
+  /** The unit's test scenario or criterion. */
+  criterion: string;
+  why: string;
+}
+
+export interface Handoff {
+  deviations: HandoffDeviation[];
+  followUps: HandoffFollowUp[];
+  unproven: HandoffUnproven[];
+}
+
+/** The most entries one list may carry: a handoff is a summary for a person,
+ *  not a second review. */
+export const HANDOFF_MAX_ITEMS = 20;
+/** The most characters one field may carry, on the way in. Stored records are
+ *  checked for shape only (`isHandoffShape`): redaction may lengthen a string. */
+export const HANDOFF_MAX_FIELD_CHARS = 500;
+
+type ListKey = keyof Handoff;
+
+/** Each list's entry fields, the one source for the validator, the redactor and the renderers. */
+const FIELDS: Readonly<Record<ListKey, readonly string[]>> = {
+  deviations: ["from", "to", "why"],
+  followUps: ["what", "where"],
+  unproven: ["criterion", "why"],
+};
+const LISTS: readonly 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>[]>;
+
+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;
+
+export function emptyHandoff(): Handoff {
+  return asHandoff(emptyLists());
+}
+
+export function isEmptyHandoff(h: Handoff): boolean {
+  return LISTS.every((k) => h[k].length === 0);
+}
+
+function isRecord(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+/** Structural check — the three lists, each entry an object whose named fields
+ *  are strings. What a stored record is validated with: no bounds, so a record
+ *  never becomes unreadable because redaction lengthened a field. */
+export function isHandoffShape(v: unknown): v is Handoff {
+  if (!isRecord(v)) return false;
+  return LISTS.every((key) => {
+    const list = v[key];
+    return (
+      Array.isArray(list) &&
+      list.every((entry) => isRecord(entry) && FIELDS[key].every((f) => typeof entry[f] === "string"))
+    );
+  });
+}
+
+export type ParsedHandoff = { ok: true; handoff: Handoff } | { ok: false; error: string };
+
+const fieldList = (key: ListKey): string => {
+  const fs = FIELDS[key];
+  return `${fs.slice(0, -1).join(", ")} and ${fs[fs.length - 1]}`;
+};
+
+/** 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. */
+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 (!Array.isArray(list))
+      return { ok: false, error: `${key}: must be an array (empty when there is nothing to say)` };
+    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];
+      if (!isRecord(entry)) return { ok: false, error: `${key}.${i}: must be an object with ${fieldList(key)}` };
+      const clean: Record<string, string> = {};
+      for (const f of FIELDS[key]) {
+        const raw = entry[f];
+        const value = typeof raw === "string" ? raw.trim() : "";
+        if (value.length === 0 || value.length > HANDOFF_MAX_FIELD_CHARS)
+          return {
+            ok: false,
+            error: `${key}.${i}.${f}: must be a non-empty string of at most ${HANDOFF_MAX_FIELD_CHARS} characters`,
+          };
+        clean[f] = value;
+      }
+      out[key].push(clean);
+    }
+  }
+  return { ok: true, handoff: asHandoff(out) };
+}
+
+/** Every string leaf through the redaction seam (`redactSecrets` by default),
+ *  structure preserved, the input untouched — the same rule the published
+ *  description follows, so a credential pasted into a handoff never reaches a
+ *  run record or a board issue. */
+export function redactHandoff(h: Handoff, redact: (s: string) => string = redactSecrets): Handoff {
+  const out = emptyLists();
+  for (const key of LISTS) {
+    for (const entry of asLists(h)[key]) {
+      const clean: Record<string, string> = {};
+      for (const f of FIELDS[key]) clean[f] = redact(entry[f]!);
+      out[key].push(clean);
+    }
+  }
+  return asHandoff(out);
+}
+
+// ---- the renders ---------------------------------------------------------------------------------
+
+export interface HandoffRenderContext {
+  /** The unit's id as the plan spells it (`U17`). */
+  unitId: string;
+  /** The unit's pull request, when the round opened or edited one. */
+  pr?: { number: number; url: string };
+}
+
+/** The header of the plan's follow-ups ledger (Appendix B), so the rows below
+ *  paste into it as the same table. */
+export const HANDOFF_LEDGER_HEADER = "| Follow-up | Source | Disposition |\n|---|---|---|";
+
+/** One line: a newline would end a bullet or a table row. */
+function line(s: string): string {
+  return s.replace(/\s*\n\s*/g, " ");
+}
+
+/** A table cell: a literal `|` would split the row; a backslash is escaped
+ *  first so an input `\|` does not become an escaped escape. */
+function cell(s: string): string {
+  return line(s.replace(/\\/g, "\\\\").replace(/\|/g, "\\|"));
+}
+
+/** Each entry as one line of prose, the same words in a bullet and in a ledger row. */
+function entryLines(h: Handoff): Array<{ list: ListKey; bullet: string; row: string }> {
+  return [
+    ...h.deviations.map((d) => {
+      const text = `${d.from} → ${d.to} — ${d.why}`;
+      return { list: "deviations" as const, bullet: text, row: `Deviation: ${text}` };
+    }),
+    ...h.followUps.map((f) => {
+      const text = `${f.what} — ${f.where}`;
+      return { list: "followUps" as const, bullet: text, row: text };
+    }),
+    ...h.unproven.map((u) => {
+      const text = `${u.criterion} — ${u.why}`;
+      return { list: "unproven" as const, bullet: text, row: `Unproven: ${text}` };
+    }),
+  ];
+}
+
+function prLink(pr: HandoffRenderContext["pr"]): string | undefined {
+  return pr ? `[#${pr.number}](${pr.url})` : undefined;
+}
+
+/**
+ * The rows a person pastes into the plan's follow-ups ledger — one per entry,
+ * in the ledger's shape `| Follow-up | Source | Disposition |`, the source
+ * naming the unit's handoff and its pull request, the disposition `open` until
+ * a person decides. Empty string for an empty handoff.
+ */
+export function renderHandoffLedgerRows(h: Handoff, ctx: HandoffRenderContext): string {
+  const link = prLink(ctx.pr);
+  const source = `${ctx.unitId} handoff${link ? ` (${link})` : ""}`;
+  return entryLines(h)
+    .map((e) => `| ${cell(e.row)} | ${cell(source)} | open |`)
+    .join("\n");
+}
+
+const HEADINGS: Readonly<Record<ListKey, string>> = {
+  deviations: "### Deviations",
+  followUps: "### Follow-ups",
+  unproven: "### Unproven",
+};
+
+/**
+ * The comment the parent posts on the unit's board issue: the unit id and the
+ * pull request in the first line, each non-empty list under its own heading,
+ * then the ledger rows in a fenced block a person pastes into the plan while
+ * it is `proposed`. An empty list is omitted with its heading; an entirely
+ * empty handoff renders nothing — there is nothing for a person to decide.
+ * The same object renders to the same bytes.
+ */
+export function renderHandoffComment(h: Handoff, ctx: HandoffRenderContext): string | undefined {
+  if (isEmptyHandoff(h)) return undefined;
+  const link = prLink(ctx.pr);
+  const parts: string[] = [`**Handoff — ${ctx.unitId}** · ${link ? `pull request ${link}` : "no pull request"}`];
+  const lines = entryLines(h);
+  for (const key of LISTS) {
+    const bullets = lines.filter((e) => e.list === key).map((e) => `- ${line(e.bullet)}`);
+    if (bullets.length > 0) parts.push(`${HEADINGS[key]}\n\n${bullets.join("\n")}`);
+  }
+  parts.push(
+    "### Ledger rows\n\n" +
+      "Paste into the plan's follow-ups ledger while the plan is `proposed`; a person decides each disposition.\n\n" +
+      `\`\`\`markdown\n${HANDOFF_LEDGER_HEADER}\n${renderHandoffLedgerRows(h, ctx)}\n\`\`\``,
+  );
+  return parts.join("\n\n");
+}

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

@@ -10,8 +10,8 @@
 // falls back cold with a message that reads like a lock bug, and nothing frees
 // the disk. Two facts fix that: the failure is classified `disk-full` (never
 // serviceable, so the bot skips the attach and the card names the disk), and
-// the resident recycles its container — the disk is a cache; the next alarm
-// restores mirror + checkout from R2 — once nothing live would be lost.
+// the resident recycles its container — the disk is a cache; the next refresh
+// cycle restores mirror + checkout from R2 — once nothing live would be lost.
 
 /** The errno wording tools print for ENOSPC: Node's `ENOSPC` code and libc's
  *  strerror text (git, cp, tar, pnpm all pass it through). A message carrying

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

@@ -1,44 +1,43 @@
 /** The refresh cycle as a cron-created Workflow instance — the id scheme, the
- *  per-resident lifecycle flag and the cron's decision to create one
+ *  per-resident lifecycle row and the cron's decision to create one
  *  (docs/reference/specs/resident-repos.md item 7), kept pure and
  *  dependency-free so it is unit-testable from src/ and imported by the
  *  resident Worker like residentRefresh — the tested code IS the shipped code.
  *
- *  Background: the refresh cycle is driven by a self-rearming alarm chain,
- *  and every failure between two re-arms ends the chain silently; a watchdog
- *  guesses from a timestamp. A Cloudflare Workflow instance is the durable
- *  fact the chain lacks: the engine records that a sequence is in progress
- *  and which step it reached, retries a failed step on a policy, and shows a
- *  failed instance by name. The port runs behind a per-resident flag,
- *  `lifecycle: alarm | workflow`, default `alarm`: one resident can run its
- *  cycles as instances while the fleet keeps the chain, and the two
- *  schedulers never both drive a cycle for the same resident.
+ *  Background: the refresh cycle used to be driven by a self-rearming alarm
+ *  chain, and every failure between two re-arms ended the chain silently; a
+ *  watchdog guessed from a timestamp. A Cloudflare Workflow instance is the
+ *  durable fact the chain lacked: the engine records that a sequence is in
+ *  progress and which step it reached, retries a failed step on a policy,
+ *  and shows a failed instance by name. The port ran behind a per-resident
+ *  flag for one release; the chain is gone now and Workflows is the one
+ *  scheduler, so every row reads `workflow` whatever it stores.
  *
  *  Shape: a cycle is one SHORT instance, not a loop — the resident Worker's
  *  existing ten-minute cron creates one per eligible resident with a
  *  deterministic id per resident and ten-minute bucket, so a second firing in
  *  the same bucket is refused as a duplicate id and cycles stay serialized
- *  per resident the way the chain serialized them. (A perpetual instance
- *  that slept between cycles was rejected by arithmetic: five steps every
- *  600 s reaches the engine's 10,000-step instance cap in about two weeks.) */
+ *  per resident. (A perpetual instance that slept between cycles was
+ *  rejected by arithmetic: five steps every 600 s reaches the engine's
+ *  10,000-step instance cap in about two weeks.) */
 
 import { STALE_MIDFLIGHT_MS } from "./residentIncarnation.js";
-import { nextRefreshDelayS } from "./residentRefresh.js";
 import type { ResidentLifecycleState } from "./residentState.js";
 
-// -- the flag ----------------------------------------------------------------
+// -- the lifecycle row ---------------------------------------------------------
 
-/** Which scheduler drives a resident's refresh cycle. */
-export type ResidentLifecycle = "alarm" | "workflow";
+/** Which scheduler drives a resident's refresh cycle: there is one. The row
+ *  survives from the flagged rollout so `/status` can say so; an `alarm` value
+ *  a flip left behind names a chain that no longer exists. */
+export type ResidentLifecycle = "workflow";
 
-/** The alarm chain is the default; a row without the field reads as `alarm`. */
-export const DEFAULT_LIFECYCLE: ResidentLifecycle = "alarm";
+export const DEFAULT_LIFECYCLE: ResidentLifecycle = "workflow";
 
 export function parseLifecycle(value: unknown): ResidentLifecycle | undefined {
-  return value === "alarm" || value === "workflow" ? value : undefined;
+  return value === "workflow" ? value : undefined;
 }
 
-/** What a stored row means: the two words, else the default. */
+/** What a stored row means: `workflow`, whatever it says. */
 export function lifecycleOf(stored: unknown): ResidentLifecycle {
   return parseLifecycle(stored) ?? DEFAULT_LIFECYCLE;
 }
@@ -94,7 +93,6 @@ export function refreshInstanceId(owner: string, name: string, atMs: number): st
 
 /** What the cron reads about one resident before creating its instance. */
 export interface RefreshRow {
-  lifecycle: ResidentLifecycle;
   state: ResidentLifecycleState;
   /** When the state last changed (epoch ms); null when the row never recorded one. */
   updatedAt: number | null;
@@ -110,36 +108,41 @@ export interface RefreshRow {
 }
 
 export interface RefreshCadence {
-  /** The awake cadence (the alarm's REFRESH_INTERVAL_S). */
+  /** The awake cadence (REFRESH_INTERVAL_S). */
   intervalS: number;
-  /** The idle cadence (the alarm's IDLE_REFRESH_INTERVAL_S). */
+  /** The idle cadence (IDLE_REFRESH_INTERVAL_S). */
   idleIntervalS: number;
 }
 
-export type InstanceDecision =
-  | { create: true; why: "due" }
-  | { create: false; why: "alarm-lifecycle" | "not-serving" | "mid-cycle" | "not-due" | "running" };
-
-/** Create an instance only for a `workflow` row that is serving, is not in a
- *  live cycle (a `refreshing` marker younger than the stale bound; an older
- *  one is an orphan the next cycle normalizes, exactly as the watchdog
- *  judges it), and whose cadence has elapsed since the last instance —
- *  counted in whole buckets so cron jitter never skips a due bucket: the
- *  awake cadence is one bucket, the idle cadence the row records is
- *  `nextRefreshDelayS`'s idle interval in buckets. */
-export function shouldCreateRefreshInstance(row: RefreshRow, nowMs: number, cadence: RefreshCadence): InstanceDecision {
-  if (row.lifecycle !== "workflow") return { create: false, why: "alarm-lifecycle" };
-  if (row.state === "onboarding" || row.state === "down") return { create: false, why: "not-serving" };
-  if (row.instanceRunning) return { create: false, why: "running" };
+/** Why no cycle may start for a row right now, or null when one may: the
+ *  resident is not serving (`onboarding` is provisioning's, `down` is a
+ *  rebuild's); the engine still runs the last instance; or a `refreshing`
+ *  marker younger than the stale bound says a cycle is live (an older one is
+ *  an orphan the next cycle normalizes, exactly as the watchdog judges it).
+ *  Shared by the cron's decision and the admin `refresh-now` op, which
+ *  starts a cycle whether or not one is due but never beside a live one. */
+export function refreshCycleBlocked(row: RefreshRow, nowMs: number): "not-serving" | "running" | "mid-cycle" | null {
+  if (row.state === "onboarding" || row.state === "down") return "not-serving";
+  if (row.instanceRunning) return "running";
   if (row.state === "refreshing" && row.updatedAt !== null && nowMs - row.updatedAt <= STALE_MIDFLIGHT_MS) {
-    return { create: false, why: "mid-cycle" };
+    return "mid-cycle";
   }
+  return null;
+}
+
+export type InstanceDecision =
+  { create: true; why: "due" } | { create: false; why: "not-serving" | "mid-cycle" | "not-due" | "running" };
+
+/** Create an instance only for a row no live cycle blocks (`refreshCycleBlocked`)
+ *  whose cadence has elapsed since the last instance — counted in whole
+ *  buckets so cron jitter never skips a due bucket: the awake cadence is one
+ *  bucket, the idle cadence the row records (`idleSince` set) is the idle
+ *  interval in buckets. */
+export function shouldCreateRefreshInstance(row: RefreshRow, nowMs: number, cadence: RefreshCadence): InstanceDecision {
+  const blocked = refreshCycleBlocked(row, nowMs);
+  if (blocked) return { create: false, why: blocked };
   if (row.lastInstanceAt !== null) {
-    const delayS = nextRefreshDelayS({
-      outcome: row.idleSince !== null ? "idle" : "normal",
-      intervalS: cadence.intervalS,
-      idleIntervalS: cadence.idleIntervalS,
-    });
+    const delayS = row.idleSince !== null ? cadence.idleIntervalS : cadence.intervalS;
     const dueBuckets = Math.max(1, Math.ceil((delayS * 1000) / REFRESH_BUCKET_MS));
     if (refreshBucket(nowMs) - refreshBucket(row.lastInstanceAt) < dueBuckets) return { create: false, why: "not-due" };
   }