@coreplane/switchboard 1.241.0 → 1.243.0

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

@@ -196,6 +196,15 @@ function entryLines(h: Handoff): Array<{ list: ListKey; bullet: string; row: str
   ];
 }
 
+/** 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. */
+export function handoffLines(h: Handoff): string[] {
+  return entryLines(h).map((e) => e.row);
+}
+
 function prLink(pr: HandoffRenderContext["pr"]): string | undefined {
   return pr ? `[#${pr.number}](${pr.url})` : undefined;
 }

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

@@ -2,28 +2,31 @@
 // one set of bounds, shared by the tool layer, every executor, and both deploy
 // Workers (which import from src/execution like shellQuote/residentDetach).
 // Deliberately free of node: imports so wrangler can bundle it into Workers.
+// The numbers are rows of src/core/budgets.ts (docs/decisions/0046); this file
+// keeps their names for the readers that learned them here.
+import { ALLOWANCES, BASH_COMMAND, MINUTE_MS } from "../core/budgets.js";
 
 /** Default per-command budget when the caller passes no timeoutMs. */
-export const BASH_TIMEOUT_MS = 5 * 60_000;
+export const BASH_TIMEOUT_MS = BASH_COMMAND.defaultMinutes * MINUTE_MS;
 
 /** Floor: anything lower is a typo or an attack, not a budget. */
-export const BASH_TIMEOUT_MIN_MS = 1_000;
+export const BASH_TIMEOUT_MIN_MS = BASH_COMMAND.minMs;
 
 /** Hard ceiling a caller can raise the budget to. Not by itself a guarantee
  *  against one command eating a run — 20 minutes is 80% of a 25-minute review
  *  — which is what `bashBudgetWithinRun` below is for. */
-export const BASH_TIMEOUT_MAX_MS = 20 * 60_000;
+export const BASH_TIMEOUT_MAX_MS = BASH_COMMAND.maxMinutes * MINUTE_MS;
 
 /** Wall clock a run keeps back from its last command for the write-up: the
  *  runner's deadline forces a final answer, and a command still running at
  *  that moment would have been wasted anyway. */
-export const RUN_DEADLINE_RESERVE_MS = 60_000;
+export const RUN_DEADLINE_RESERVE_MS = ALLOWANCES.commandWriteUp * MINUTE_MS;
 
 /** Margin the remote exec clients add to their HTTP wait over the command
  *  budget, so the server's own timeout answer (a streamed exit 124) wins the
  *  race against the client's transport deadline instead of both firing at the
  *  same instant. */
-export const EXEC_CALL_MARGIN_MS = 30_000;
+export const EXEC_CALL_MARGIN_MS = ALLOWANCES.execCall * MINUTE_MS;
 
 /** The documented clamp rule, applied identically bot-side and server-side
  *  (a server never trusts the client's number): a finite number is truncated

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

@@ -9,8 +9,10 @@
  *  cycle, and these say the snapshot (or the container that would restore it)
  *  cannot be used — never a provision failure, which would loop against the
  *  same broken build. `runtime-unreachable` is item 64's last rung: a recreated
- *  container that did not answer either. */
-export const REHYDRATION_FAILURE_RE = /^(r2-restore-failed|snapshot-stamp-mismatch|no-snapshot|runtime-unreachable)/;
+ *  container that did not answer either; `infra-streak` is item 67's: a
+ *  recreated container whose cycles kept failing in the resident's own steps. */
+export const REHYDRATION_FAILURE_RE =
+  /^(r2-restore-failed|snapshot-stamp-mismatch|no-snapshot|runtime-unreachable|infra-streak)/;
 
 /** How many auto-rebuilds one resident gets inside one window. A rebuild is a
  *  clone, an install and a build (minutes to half an hour) that holds the cap

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

@@ -67,10 +67,9 @@ export type FetchReason = "missing-ref" | "stale-tip" | "returnable-ref";
  *    lost and a ref a person named that the thread never pushed has no way
  *    back, so neither pays this fetch: the refresh cycle is their freshness.
  *  - otherwise null.
- *  A fetch that STILL leaves the tip elsewhere (a push racing this attach, or
- *  a force-push) is not this function's concern: the attach proceeds on the
- *  fetched tip and reports it, and the reviewed-head guard decides what a
- *  review of it may do. */
+ *  A fetch that STILL leaves the tip elsewhere (a push racing this attach, a
+ *  force-push, or a fetch that failed) is `attachTarget`'s concern: the attach
+ *  is refused `stale-tip` rather than run at a commit nobody asked for. */
 export function mirrorFetchReason(input: {
   refExists: boolean;
   mirrorSha?: string;
@@ -85,8 +84,16 @@ export function mirrorFetchReason(input: {
 
 /** What the attach checks out, once the mirror is as fresh as it will get. */
 export type AttachTarget =
-  /** The bound ref is in the mirror: clone its tip, as always. */
+  /** The bound ref is in the mirror, and its tip is the commit the caller
+   *  named (or the caller named none): clone its tip, as always. */
   | { kind: "ref" }
+  /** The bound ref is in the mirror but its tip is NOT the commit the caller
+   *  named, even after the fetch — the mirror is behind it (the fetch failed
+   *  or was skipped) or ahead of it (a push raced the attach). Refused: a run
+   *  executes at the sha it asked for, or not on this resident; the caller
+   *  falls back cold at the requested commit. `tip` is null when the tip
+   *  could not be read — never assumed fresh. */
+  | { kind: "stale-tip"; tip: string | null; want: string }
   /** The ref is gone but the commit the caller expects is in the mirror — a
    *  merged PR's branch was deleted while `refs/pull/N/head` (a `--mirror`
    *  clone carries every ref) still holds its head: check that commit out,
@@ -96,16 +103,22 @@ export type AttachTarget =
   /** Neither: the attach is refused as `unknown-ref`. */
   | { kind: "unknown-ref" };
 
-/** The attach target after the fetch (item 51). The ref wins whenever it
- *  exists — a detached tree is only for a ref that is gone; a caller that
- *  named no commit, or whose commit the mirror does not hold either, gets the
- *  refusal it always got. */
+/** The attach target after the fetch (item 51). A ref that exists is cloned
+ *  at its tip when the caller named no commit or the tip is that commit;
+ *  a tip that is any other commit is `stale-tip`, refused. A detached tree is
+ *  only for a ref that is gone; a caller that named no commit, or whose commit
+ *  the mirror does not hold either, gets the refusal it always got. */
 export function attachTarget(input: {
   refExists: boolean;
   wantSha: string | null;
   commitInMirror: boolean;
+  /** The ref's tip in the mirror after the fetch; null or absent when it could not be read. */
+  tipSha?: string | null;
 }): AttachTarget {
-  if (input.refExists) return { kind: "ref" };
+  if (input.refExists) {
+    if (input.wantSha === null || input.tipSha === input.wantSha) return { kind: "ref" };
+    return { kind: "stale-tip", tip: input.tipSha ?? null, want: input.wantSha };
+  }
   if (input.wantSha !== null && input.commitInMirror) return { kind: "sha", sha: input.wantSha };
   return { kind: "unknown-ref" };
 }

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

@@ -0,0 +1,89 @@
+// A refresh cycle that keeps failing in the resident's OWN steps heals itself
+// (docs/reference/specs/resident-repos.md item 67). Pure: the Worker's
+// `refreshFailed` bumps the row and acts on the rung; the cycle's gate asks
+// `parksOnRepeat` before it counts a degraded reason toward the park streak.
+//
+// The split this module draws: a step that runs the repository's own command
+// (the onboard-time command table — install, build, test) failing is evidence
+// about the repository, and the right response is to park and wait for the
+// head to be fixed, which is what the park streak does. Every other step is
+// the resident's machinery — git against the mirror, the probes, the markers,
+// the restores — and a failure there that repeats is the container or the
+// disk gone wrong, which a rebuild does fix. Item 64 already climbs this
+// ladder for one signature (the control port that never answers); this is
+// the same ladder for every other resident-step failure.
+
+import { STALE_SWEEP_SUFFIX } from "./residentSteps.js";
+
+/** The steps that run the repository's own commands. */
+export const REPO_COMMAND_STEPS: ReadonlySet<string> = new Set(["deps-install", "build", "test"]);
+
+/** Whether a failed step ran the repository's command (evidence about the
+ *  repo) rather than the resident's own machinery. The stale-process sweep
+ *  that precedes a repo step is ours. */
+export function isRepoCommandStep(step: string): boolean {
+  if (step.endsWith(STALE_SWEEP_SUFFIX)) return false;
+  return REPO_COMMAND_STEPS.has(step);
+}
+
+/** The step named by a `<step>-failed:` reason (`classifyRefreshFailure`'s
+ *  plain-failure shape), or null for every other reason. */
+export function stepOfFailedReason(reason: string): string | null {
+  const m = /^([a-z][a-z0-9-]*)-failed:/.exec(reason);
+  return m ? m[1] : null;
+}
+
+/** Whether a repeated degraded reason should PARK the resident (the 6-hour
+ *  cadence, `DEGRADED_PARK_AFTER_CYCLES`): only evidence about the repository
+ *  or about GitHub — a repo-command step's failure, or a reason that names no
+ *  step at all (`github-unreachable`). A resident-step failure never parks:
+ *  the ladder below is its escalation, and parking would only slow it. */
+export function parksOnRepeat(reason: string): boolean {
+  const step = stepOfFailedReason(reason);
+  return step === null || isRepoCommandStep(step);
+}
+
+/** The ladder's rungs: consecutive cycles failed in resident steps. */
+export const INFRA_STREAK_RECREATE_AT = 3;
+export const INFRA_STREAK_DOWN_AT = 5;
+
+export type InfraStreakRung = "count" | "recreate" | "down";
+
+/** Count 1–2: record and let the next cycle try. Count 3: destroy the
+ *  container, snapshots kept — the next cycle restores from the snapshot onto
+ *  a fresh disk (item 64's rung 3). Count 4: the recreated container's one
+ *  cycle of its own. Count ≥ 5: a fresh container failed the same way; `down`
+ *  with a rehydration-flavored reason, so item 36's transition rebuild is the
+ *  exit. */
+export function infraStreakRung(count: number): InfraStreakRung {
+  if (!Number.isFinite(count) || count < 1) {
+    throw new RangeError(`infra-streak rung needs a count of at least 1, got ${count}`);
+  }
+  if (count >= INFRA_STREAK_DOWN_AT) return "down";
+  if (count === INFRA_STREAK_RECREATE_AT) return "recreate";
+  return "count";
+}
+
+/** The persisted row (`resident:infraStreak`): the last failing step, the
+ *  consecutive count and the span. */
+export interface InfraStreakRow {
+  step: string;
+  count: number;
+  firstAt: string;
+  lastAt: string;
+}
+
+const INFRA_STREAK_ACTION: Readonly<Record<Exclude<InfraStreakRung, "count">, string>> = {
+  recreate: "the container was destroyed, snapshots kept; the next cycle restores from the snapshot",
+  down: "a recreated container failed the same way; rebuilding",
+};
+
+/** The reason a rung records: `infra-streak:` so the gate, the serviceability
+ *  check and item 36's eligibility all read it as the resident's, never the repo's. */
+export function infraStreakReason(row: InfraStreakRow, rung: Exclude<InfraStreakRung, "count">): string {
+  return `infra-streak: ${row.count} consecutive cycles failed in the resident's own steps (last: ${row.step}, since ${row.firstAt}) — ${INFRA_STREAK_ACTION[rung]}`;
+}
+
+export function isInfraStreakReason(reason: string): boolean {
+  return /^infra-streak: /.test(reason);
+}

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

@@ -132,6 +132,10 @@ export interface RefreshFailure {
    *  with the attempt count (the ladder below decides what the resident does
    *  about it); real failures keep `<step>-failed:`. */
   reason: string;
+  /** The step that failed, as the caller named it (`refresh` for a failure
+   *  between steps): item 67 reads whether it ran the repository's own command
+   *  or the resident's machinery. */
+  step: string;
   interrupted: boolean;
   diskFull: boolean;
   runtimeUnreachable: boolean;
@@ -205,9 +209,34 @@ const INTERRUPTION_SIGNATURE = /\bexit 143\b|Session terminated|SIGTERM|^restore
  *  exec path and the refresh classifier agree on one wording list (a container
  *  stop mid-snapshot produces "Process supervisor is closed"; classified as the
  *  repo's own `snapshot-failed` it would end the instance `degraded` instead of
- *  being retried into the same step). */
-export const RUNTIME_REPLACEMENT_WORDING =
-  /previous runtime incarnation|interrupted because the runtime changed|runtime identity is no longer active|sandbox lifetime is no longer current|platform was updating the sandbox runtime|no longer identifies pid|process supervisor is closed|container is not running, consider calling start/i;
+ *  being retried into the same step).
+ *
+ *  The list is the union of two a reader tells apart, because the resident's
+ *  `/exec` answer treats them differently (resident-repos item 43): the SDK's
+ *  words that vouch the runtime MOVED — a new incarnation serves the thread,
+ *  so the container the command was aimed at is gone whatever else is known
+ *  — and the platform's words for a container that is merely DOWN, which say
+ *  nothing about a replacement: a stopped container answers "Process
+ *  supervisor is closed" to a spawn, and the workerd binding answers "The
+ *  container is not running" whether the container is asleep, starting, or
+ *  gone under a roll. For the refresh classifier and `isRuntimeReplacement`
+ *  the union is right: a step interrupted either way is retried onto the
+ *  container that comes back. */
+export const RUNTIME_MOVED_WORDING =
+  /previous runtime incarnation|interrupted because the runtime changed|runtime identity is no longer active|sandbox lifetime is no longer current|platform was updating the sandbox runtime|no longer identifies pid/i;
+/** The platform's words for a container that is down under a command (see
+ *  `RUNTIME_MOVED_WORDING`): the spawn refusal of a stopped container and the
+ *  binding's not-running refusal, anchored to the full phrase so a genuine
+ *  crash ("container exited with unexpected exit code") and the readiness
+ *  probe ("the container is not listening") never match. The harness's
+ *  container seam reads the same two as a container down under its one more
+ *  command — a wait, never a judgement (harness.md item 6). */
+export const STOPPED_CONTAINER_WORDING =
+  /process supervisor is closed|container is not running, consider calling start/i;
+export const RUNTIME_REPLACEMENT_WORDING = new RegExp(
+  `${RUNTIME_MOVED_WORDING.source}|${STOPPED_CONTAINER_WORDING.source}`,
+  "i",
+);
 
 /** `runtimeUnreachable` is the caller's word that the failure was the SDK's
  *  connect abort at the exec choke point (the Worker's typed check over the
@@ -234,6 +263,7 @@ export function classifyRefreshFailure(input: {
   const { step, message } = input;
   if (input.runtimeUnreachable) {
     return {
+      step,
       interrupted: false,
       diskFull: false,
       runtimeUnreachable: true,
@@ -242,6 +272,7 @@ export function classifyRefreshFailure(input: {
   }
   if (isDiskFullMessage(message)) {
     return {
+      step,
       interrupted: false,
       diskFull: true,
       runtimeUnreachable: false,
@@ -251,6 +282,7 @@ export function classifyRefreshFailure(input: {
   const timedOut = /\(timed out\)/.test(message);
   if (!timedOut && (INTERRUPTION_SIGNATURE.test(message) || RUNTIME_REPLACEMENT_WORDING.test(message))) {
     return {
+      step,
       interrupted: true,
       diskFull: false,
       runtimeUnreachable: false,
@@ -259,13 +291,20 @@ export function classifyRefreshFailure(input: {
   }
   if (input.freeKiB !== undefined && input.freeKiB !== null && input.freeKiB < DISK_FULL_FREE_KIB) {
     return {
+      step,
       interrupted: false,
       diskFull: true,
       runtimeUnreachable: false,
       reason: diskFullReason({ step, message, freeKiB: input.freeKiB }),
     };
   }
-  return { interrupted: false, diskFull: false, runtimeUnreachable: false, reason: `${step}-failed: ${message}` };
+  return {
+    step,
+    interrupted: false,
+    diskFull: false,
+    runtimeUnreachable: false,
+    reason: `${step}-failed: ${message}`,
+  };
 }
 
 // -- the runtime that never answers --------------------------------------------

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

@@ -49,6 +49,7 @@ export const RESIDENT_STEP_LABELS = {
   "worktree-clean": "cleaning the worktree",
   "clean-workspace": "cleaning the workspace",
   "clean-before-restore": "cleaning before the restore",
+  "break-mirror": "removing the mirror's config (fault injection)",
   "unmount-restores": "unmounting earlier restores",
   "mirror-restore-extract": "extracting the mirror snapshot",
   "checkout-restore-extract": "extracting the checkout snapshot",

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

@@ -53,6 +53,12 @@ const FLEET_BUSY_PATTERNS: readonly RegExp[] = [
   // pool matches on this exact phrase. Seen live passing through as a plain
   // in-body error and ending two reviews in under a minute each.
   /Maximum number of running container instances exceeded/i,
+  // The platform's start-rate limit: a burst of fresh threads (twenty-four
+  // seeded sandboxes started within twenty seconds) had a third of its
+  // container starts refused with this text, and the Worker read it as a
+  // failed seed. It is capacity for a moment, like a full fleet: the
+  // executor waits and re-sends the identical request.
+  /too many containers per second/i,
 ];
 
 export function isFleetBusy(message: string): boolean {

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

@@ -70,6 +70,19 @@ export interface SandboxSeed {
 
 export type SeedStep = "restore" | "deps" | "fixup";
 
+/** One restore's two phases, in milliseconds: the SDK's presigned download of
+ *  the archive (judged by bytes arriving), then the extraction onto the disk. */
+export interface RestorePhases {
+  download: number;
+  extract: number;
+}
+
+export interface SeedPhases {
+  checkout: RestorePhases;
+  /** Null when no deps entry rode along. */
+  deps: RestorePhases | null;
+}
+
 export type SeedAnswer =
   | {
       seeded: true;
@@ -82,6 +95,10 @@ export type SeedAnswer =
       from: { ref: string; sha: string; checkoutBackupId: string; depsBackupId?: string };
       /** Milliseconds per step; `deps` null when no entry rode along; all zero when cached. */
       steps: { restore: number; deps: number | null; fixup: number };
+      /** Each restore split into its two phases — the archive's download to the
+       *  container and its extraction onto the disk — so the gate's reading says
+       *  which one owns a slow seed. Absent when cached. */
+      phases?: SeedPhases;
       ms: number;
     }
   | { seeded: false; reason: SeedReason; detail: string; step?: SeedStep };