npm - @coreplane/switchboard - Versions diffs - 1.240.0 → 1.242.0 - Mend

@coreplane/switchboard 1.240.0 → 1.242.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (146) hide show

package/dist/assets/src/core/coordinator/driver.ts CHANGED Viewed

@@ -57,7 +57,7 @@ import {
   type UnitPipelineInput,
   type UnitPipelineState,
 } from "../ship/coordinator.js";
-import { isCoordinatorUnit, runFinishedEventType, type CoordinatorUnit } from "./contract.js";
+import { checksSettledEventType, isCoordinatorUnit, runFinishedEventType, type CoordinatorUnit } from "./contract.js";
 const MIN = 60_000;
@@ -429,6 +429,22 @@ async function perform(
     case "sleep":
       await step.sleep(action.step, action.ms);
       return { type: "sleep", step: action.step };
+    case "wait-checks": {
+      // The intake's checks-settled event at the approved head (http-ingress.md
+      // item 12), with the machine's bounded timeout as the fallback: either
+      // way the machine re-asks the merge door, which is the guard.
+      let outcome: "event" | "timeout";
+      try {
+        await step.waitForEvent(action.step, {
+          type: checksSettledEventType(action.headSha),
+          timeout: action.timeoutMs,
+        });
+        outcome = "event";
+      } catch {
+        outcome = "timeout";
+      }
+      return { type: "wait-checks", step: action.step, outcome };
+    }
     case "merge":
       return mergeReturn(
         action.step,

package/dist/assets/src/core/coordinator/instancesRoute.ts CHANGED Viewed

@@ -131,6 +131,78 @@ export function parseInstanceStatusPath(pathname: string): string | undefined {
   return INSTANCE_ID_PATTERN.test(id) ? id : undefined;
 }
+/** `POST /admin/coordinator/instances/<id>/events` — the shim's event relay
+ *  (docs/reference/specs/http-ingress.md item 12): the bot holds no Workflow
+ *  binding, so the check-run intake sends `checks-settled-<head>` through this
+ *  route and the shim's own `SHIP_COORDINATOR.get(id).sendEvent` delivers it. */
+export const COORDINATOR_INSTANCE_EVENTS_SUFFIX = "/events";
+/** The instance id an event path names, or undefined for any other path. */
+export function parseInstanceEventPath(pathname: string): string | undefined {
+  if (!pathname.startsWith(COORDINATOR_INSTANCE_STATUS_PREFIX)) return undefined;
+  if (!pathname.endsWith(COORDINATOR_INSTANCE_EVENTS_SUFFIX)) return undefined;
+  const id = pathname.slice(
+    COORDINATOR_INSTANCE_STATUS_PREFIX.length,
+    pathname.length - COORDINATOR_INSTANCE_EVENTS_SUFFIX.length,
+  );
+  return INSTANCE_ID_PATTERN.test(id) ? id : undefined;
+}
+export type ParsedSendEvent = { ok: true; type: string; payload: unknown } | { ok: false; reason: string };
+/** The Workflow event alphabet — what the engine's `sendEvent` accepts as a type. */
+const EVENT_TYPE_PATTERN = /^[A-Za-z0-9_-]{1,100}$/;
+/** The body: `{ type, payload? }` — the typed event the instance's `waitForEvent` waits on. */
+export function parseSendEventRequest(text: string): ParsedSendEvent {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    return { ok: false, reason: "body is not valid JSON" };
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed))
+    return { ok: false, reason: "body must be a JSON object" };
+  const b = parsed as Record<string, unknown>;
+  if (typeof b.type !== "string" || !EVENT_TYPE_PATTERN.test(b.type))
+    return { ok: false, reason: "`type` must be a Workflow event type: letters, digits, `_` and `-`, at most 100" };
+  return { ok: true, type: b.type, payload: b.payload };
+}
+/** How the send ended on the shim: delivered, no such instance (the engine's
+ *  own `instance.not_found`), or the engine refusing by reason (an instance
+ *  that already ended is a refusal, not an absence). */
+export type SendEventOutcome =
+  { kind: "sent"; id: string } | { kind: "absent"; id: string } | { kind: "failed"; id: string; reason: string };
+export function sendEventResponse(outcome: SendEventOutcome): { status: number; body: Record<string, unknown> } {
+  switch (outcome.kind) {
+    case "sent":
+      return { status: 200, body: { ok: true, id: outcome.id, sent: true } };
+    case "absent":
+      return { status: 404, body: { ok: false, error: "no_instance", id: outcome.id } };
+    case "failed":
+      return { status: 502, body: { ok: false, error: "send_failed", id: outcome.id, message: outcome.reason } };
+  }
+}
+/** The send answer as the bot reads it back: sent, absent, or unanswered by reason. */
+export type SendEventAnswer = { kind: "sent" } | { kind: "absent" } | { kind: "unanswered"; reason: string };
+export function readSendEventAnswer(status: number, text: string): SendEventAnswer {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    parsed = undefined;
+  }
+  const body = typeof parsed === "object" && parsed !== null ? (parsed as Record<string, unknown>) : undefined;
+  if (status === 200 && body?.ok === true && body.sent === true) return { kind: "sent" };
+  if (status === 404 && body?.error === "no_instance") return { kind: "absent" };
+  const detail = typeof body?.error === "string" ? body.error : text.slice(0, 200);
+  return { kind: "unanswered", reason: `HTTP ${status} — ${detail}` };
+}
 /** How the status read ended on the shim: the platform's status word, no such
  *  instance, or the engine failing by reason. */
 export type InstanceStatusOutcome =

package/dist/assets/src/core/costs.ts CHANGED Viewed

@@ -72,6 +72,9 @@ export interface CostsConfig {
   snapshot: {
     /** Hours between two reads of the billing sources. */
     everyHours: number;
+    /** The platform-namespaced channel (`slack:C…`) told when takes keep failing and when they
+     *  land again (`ALERT_AFTER_FAILURES` in a row); absent → the status alone says so. */
+    alertChannel?: string;
   };
 }
@@ -82,13 +85,15 @@ const DEFAULT_ANTHROPIC_ADMIN_ENV = "ANTHROPIC_ADMIN_KEY";
  *  default — both sources bucket by UTC day, and the page is read about as often. */
 export const COSTS_SNAPSHOT_EVERY_HOURS = Object.freeze({ default: 24, min: 1, max: 168 });
-/** `costs.snapshot`: absent → the default interval; a value outside the bounds or not a whole number throws by name. */
+/** `costs.snapshot`: absent → the default interval and no alert channel; a value outside the
+ *  bounds or not a whole number throws by name; `alertChannel`, when given, is a platform-namespaced id. */
 function snapshotConfig(raw: unknown): CostsConfig["snapshot"] {
   if (raw === undefined) return { everyHours: COSTS_SNAPSHOT_EVERY_HOURS.default };
   if (typeof raw !== "object" || raw === null || Array.isArray(raw))
     throw new Error("costs.snapshot must be a mapping");
-  const every = (raw as Record<string, unknown>).everyHours;
-  if (every === undefined) return { everyHours: COSTS_SNAPSHOT_EVERY_HOURS.default };
+  const r = raw as Record<string, unknown>;
+  // `undefined` alone defaults: a bare `everyHours:` key (null) is a malformed value, refused below by name.
+  const every = r.everyHours === undefined ? COSTS_SNAPSHOT_EVERY_HOURS.default : r.everyHours;
   if (
     typeof every !== "number" ||
     !Number.isInteger(every) ||
@@ -98,7 +103,10 @@ function snapshotConfig(raw: unknown): CostsConfig["snapshot"] {
     throw new Error(
       `costs.snapshot.everyHours must be a whole number of hours between ${COSTS_SNAPSHOT_EVERY_HOURS.min} and ${COSTS_SNAPSHOT_EVERY_HOURS.max}`,
     );
-  return { everyHours: every };
+  if (r.alertChannel === undefined) return { everyHours: every };
+  if (typeof r.alertChannel !== "string" || !/^[a-z]+:.+$/.test(r.alertChannel))
+    throw new Error("costs.snapshot.alertChannel must be a platform-namespaced channel id (`slack:C…`)");
+  return { everyHours: every, alertChannel: r.alertChannel };
 }
 function labelMap(raw: unknown, what: string): Record<string, string> {
@@ -762,10 +770,15 @@ export function anthropicTokensCostUsd(modelId: string, t: AnthropicTokens): num
 // ---- range ----------------------------------------------------------------------------
 const DEFAULT_DAYS = 30;
-/** The widest range the page offers — and the window a costs snapshot is read for. */
-export const MAX_DAYS = 90;
-/** `?days=N` → a UTC date range ending today. Garbage → default; clamped 1..90. */
+/** The widest range the page offers — and the window a costs snapshot is read for.
+ *  Cloudflare's analytics on a Workers account answer no range wider than 4w4d
+ *  (32 days) and hold no data older than that (`cannot request a time range
+ *  wider than 4w4d`, `cannot request data older than 4w4d` — measured live), so
+ *  a wider window is a refused read, not more history: 31 UTC days is the most
+ *  a take can ask for. */
+export const MAX_DAYS = 31;
+/** `?days=N` → a UTC date range ending today. Garbage → default; clamped 1..31. */
 export function resolveRange(daysParam: string | null, now: Date = new Date(systemClock())): DateRange {
   const parsed = daysParam === null ? NaN : Number(daysParam);
   const days = Number.isInteger(parsed) ? Math.min(MAX_DAYS, Math.max(1, parsed)) : DEFAULT_DAYS;
@@ -1070,7 +1083,7 @@ export class AnthropicCostReportSource implements LlmCostSource {
     if (range.from >= endExclusive) return { rows, closedThrough };
     let page: string | null = null;
     for (let i = 0; ; i++) {
-      // Like the non-USD check: refuse rather than mis-sum. A ≤90-day range at
+      // Like the non-USD check: refuse rather than mis-sum. A ≤31-day range at
       // limit=31 is at most 3 pages, so hitting the cap means the API changed.
       if (i >= MAX_COST_PAGES)
         throw new Error(

package/dist/assets/src/core/harness/scope.ts ADDED Viewed

@@ -0,0 +1,21 @@
+// Where a preset's harness word is set (docs/reference/specs/harness.md item
+// 8), in a module with no imports of its own: the run record (`run_meta.harnessScope`)
+// and the timeline fold read it, and both are compiled into the Workers' and
+// the dashboard's programs, where the roster's neighbours — the harness
+// objects, their Node-only process code — must not follow. The roster
+// re-exports these names, so every reader inside the bot can still take them
+// from there.
+/** The scopes a word is set at, most specific first — the order the resolution
+ *  walks the layers: the requester's own scope, the channel's, then the
+ *  deployment's top-level `harness` block, which is the defaults layer under
+ *  its one spelling. What `run_meta.harnessScope` and the config block name, so
+ *  a reader of a run on OpenCode never guesses whose word put it there. */
+export const HARNESS_SCOPES = ["user", "channel", "defaults"] as const;
+export type HarnessScope = (typeof HARNESS_SCOPES)[number];
+/** Whether a value is one of the scopes a word is set at: the timeline's test
+ *  for the field a record carries. */
+export function isHarnessScope(value: unknown): value is HarnessScope {
+  return typeof value === "string" && (HARNESS_SCOPES as readonly string[]).includes(value);
+}

package/dist/assets/src/core/runEvents.ts CHANGED Viewed

@@ -2,6 +2,7 @@
 // the node-free contract the memory Worker and web app compile with their own
 // tsconfigs — importing prDescription.ts would drag zod into those graphs.
 import type { PrDescription, RenderedTourStep } from "./prDescriptionTypes.js";
+import type { HarnessScope } from "./harness/scope.js";
 /** The `pr_description` review artifact minus the event envelope
  *  (docs/reference/specs/reading-diff.md item 7). */
@@ -97,6 +98,11 @@ export type RunNoteKind =
   /** The PR head moved while a review ran and the same run is re-reviewing at
    *  the new head (agent-review.md item 12). Published by the dispatcher. */
   | "head_moved"
+  /** The run loop threw and the run finishes `failed`: the summary is the
+   *  error's message, redacted and capped, so the run page says why a failed
+   *  run failed even when the reply is never delivered (run-history.md).
+   *  Published by the run loop's catch, before the finish. */
+  | "run_failed"
   /** An MCP server configured for this agent did not answer discovery
    *  (docs/reference/specs/mcp-tools.md item 8); the run proceeds without its tools. One
    *  note per server, published by the dispatcher before the first turn. */
@@ -187,6 +193,11 @@ export type RunNoteKind =
    *  item 7): the summary names the tool and the rule; the model read the same
    *  reason as the tool's result. Published by the bot's authorize route. */
   | "tool_refused"
+  /** A ship coding child's budget ended with work still in the tree: the run
+   *  loop committed and pushed it to the unit's branch (or says plainly that
+   *  there was nothing to push), so a re-issue starts from the partial work
+   *  (docs/reference/specs/agent-ship.md item 8). */
+  | "budget_salvage"
   /** The native loop's stuck-loop guard: the same tool call failed identically
    *  six times in a row and the run was forced into its write-up. Written by
    *  no loop since that loop's deletion; a record from before it may carry it. */
@@ -205,6 +216,7 @@ export const RUN_NOTE_KINDS = [
   "stopped",
   "spans_dropped",
   "head_moved",
+  "run_failed",
   "mcp_unavailable",
   "follow_up",
   "resumed",
@@ -220,6 +232,7 @@ export const RUN_NOTE_KINDS = [
   "harness_error",
   "policy_refusal",
   "tool_refused",
+  "budget_salvage",
   "stuck_loop",
 ] as const satisfies readonly RunNoteKind[];
 type _EveryKindListed = [RunNoteKind] extends [(typeof RUN_NOTE_KINDS)[number]] ? true : never;
@@ -519,9 +532,15 @@ export type RunEvent =
       /** The request's trace id (docs/reference/specs/tracing.md), once the root exists. */
       traceId?: string;
       /** The harness the run is driven by (`Harness.name`; docs/reference/specs/harness.md
-       *  item 8): `pi` today. Absent on a command run, which starts no process,
+       *  items 8 and 10): the word the scopes resolved for the preset, `pi`
+       *  when none named it. Absent on a command run, which starts no process,
        *  and on a record written before the seam existed. Additive. */
       harness?: string;
+      /** Whose word put the run on that harness (item 10): the requester's own
+       *  scope, the channel's, or the deployment's top-level block. Absent when
+       *  no scope named the preset — the roster's default — and on records
+       *  written before the word was a scope setting. */
+      harnessScope?: HarnessScope;
       effort?: string;
       repo?: string;
       ref?: string;

package/dist/assets/src/core/runLedger/types.ts CHANGED Viewed

@@ -56,6 +56,8 @@ export interface LiveRunMeta {
   /** The bound credential behind the person (authorization.md item 15): a
    *  resume or restart dispatches under ITS grants again, never the person's. */
   authenticatedAs?: string;
+  /** The app that relayed the request for the person (authorization.md item 14): a resume or restart keeps app ∩ person at the gates. */
+  postedBy?: string;
   effort?: string;
   ref?: string;
   headSha?: string;

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

@@ -109,6 +109,9 @@ export interface RunRecord {
   receivedAt?: number;
   sealedAt?: number;
   replyOk?: boolean;
+  /** Why a `replyOk: false` reply was not delivered (e.g. "no channel to deliver
+   *  to", run-history.md item 38). Absent when the reply was delivered or none was made. */
+  replyNote?: string;
   stepCount?: number;
   schema?: number;
   status: RunStatus;
@@ -783,6 +786,7 @@ export function isRunRecord(v: unknown): v is RunRecord {
     if (r[key] !== undefined && !isFiniteNumber(r[key])) return false;
   }
   if (r.replyOk !== undefined && typeof r.replyOk !== "boolean") return false;
+  if (r.replyNote !== undefined && typeof r.replyNote !== "string") return false;
   for (const key of ["stepCount", "schema"] as const) {
     if (r[key] !== undefined && (!isFiniteNumber(r[key]) || !Number.isInteger(r[key]) || (r[key] as number) < 0))
       return false;

package/dist/assets/src/core/ship/contract.ts CHANGED Viewed

@@ -428,8 +428,10 @@ function renderFirstInstruction(rebase: ChildContract["rebase"]): string {
   return (
     `Rebase ${branch} onto ${onto} before any other work — the parent unit has merged and the base has moved; ` +
     `the only writes are your own on that branch. A conflict ends the unit: report it as the handoff and stop. ` +
-    `Right before the push, fetch ${onto} again and rebase once more if it moved during verify, ` +
-    `so the pull request is not born conflicting.`
+    `Push the branch as soon as the change exists and its cheapest proving checks pass — before the project's ` +
+    `full verification, which runs after that push with any fix as a further commit; an unpushed tree does not ` +
+    `survive the run's end. Right before each push, fetch ${onto} again and rebase once more if it moved while ` +
+    `you worked, so the pull request is not born conflicting.`
   );
 }

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

@@ -448,6 +448,8 @@ export type CoordinatorAction =
       recover?: { runId: string };
     }
   | { type: "merge"; step: string; prNumber: number; headSha: string }
+  /** 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 }
   | { type: "end"; step: string; ending: UnitEnding };
@@ -508,6 +510,7 @@ export type StepReturn =
   // fired, or a person merged — so the runner merged nothing (`by: other`).
   | { type: "merge"; step: string; outcome: "merged"; by: "other"; sha: string; mergedAt: string; at: number }
   | { type: "merge"; step: string; outcome: "pending" | "refused"; reason: string; at: number }
+  | { type: "wait-checks"; step: string; outcome: "event" | "timeout" }
   | { type: "sleep"; step: string };
 /** How one unit's pipeline ended — the truthful vocabulary the ship pipeline
@@ -628,7 +631,7 @@ type Phase =
       dead?: "failed" | "interrupted";
     }
   | { at: "merge"; pr: PrRef; headSha: string; n: number; since: number }
-  | { at: "merge-sleep"; pr: PrRef; headSha: string; n: number; since: number }
+  | { at: "merge-wait"; pr: PrRef; headSha: string; n: number; since: number }
   | { at: "ended" };
 export interface UnitPipelineState {
@@ -668,9 +671,16 @@ export const WAIT_MARGIN_MS = 5 * MIN;
  *  margin and the merge poll are the same number), and it keeps a round to a
  *  few steps: a coding child's 45 minutes are ten waits and ten reads. */
 export const WAIT_CHUNK_MS = 5 * MIN;
-/** How often the runner asks for the merge while the guards are still pending, and for how long at most. */
-export const MERGE_POLL_MS = 5 * MIN;
+/** How long the merge step waits for the guards at most. While checks are
+ *  pending the machine waits on the intake's `checks-settled-<head>` event
+ *  (http-ingress.md item 12) — one bounded wait per ask, the remainder of this
+ *  cap, as the fallback when the event never arrives. */
 export const MERGE_WAIT_MAX_MS = 60 * MIN;
+/** One merge wait's fallback timeout: the old poll's cadence. The event wakes
+ *  the machine at once when the intake delivers it; without one (the webhook
+ *  not configured, a delivery lost) the door is still re-asked every chunk, so
+ *  a merge is never slower than the poll it replaced. */
+export const MERGE_WAIT_CHUNK_MS = 5 * MIN;
 /** A `busy` without the live run's id: nothing to wait on, so a short sleep before the spawn is asked again. */
 export const BUSY_RETRY_MS = 2 * MIN;
@@ -816,8 +826,13 @@ export function nextAction(s: UnitPipelineState): CoordinatorAction {
       };
     case "merge":
       return { type: "merge", step: `${unit}/merge/${p.n}`, prNumber: p.pr.number, headSha: p.headSha };
-    case "merge-sleep":
-      return { type: "sleep", step: `${unit}/merge/sleep/${p.n}`, ms: MERGE_POLL_MS };
+    case "merge-wait":
+      return {
+        type: "wait-checks",
+        step: `${unit}/merge/wait/${p.n}`,
+        headSha: p.headSha,
+        timeoutMs: Math.max(MIN, Math.min(MERGE_WAIT_CHUNK_MS, MERGE_WAIT_MAX_MS - (s.clock - p.since))),
+      };
     case "ended":
       return { type: "end", step: `${unit}/end`, ending: s.ending! };
   }
@@ -1349,11 +1364,11 @@ export function applyReturn(s: UnitPipelineState, ret: StepReturn): Transition {
           reviewRounds: s.reviewRounds,
         });
       return {
-        state: { ...clocked, phase: { at: "merge-sleep", pr: p.pr, headSha: p.headSha, n: p.n, since: p.since } },
+        state: { ...clocked, phase: { at: "merge-wait", pr: p.pr, headSha: p.headSha, n: p.n, since: p.since } },
         notes: [],
       };
     }
-    case "merge-sleep":
+    case "merge-wait":
       return {
         state: { ...s, phase: { at: "merge", pr: p.pr, headSha: p.headSha, n: p.n + 1, since: p.since } },
         notes: [],

package/dist/assets/src/core/trace/attrs.ts CHANGED Viewed

@@ -8,7 +8,7 @@
  *  field. */
 export type Backend = "local" | "resident" | "sandbox" | "e2b";
-export type Channel = "slack" | "http" | "mcp" | "cli";
+export type Channel = "slack" | "http" | "mcp" | "cli" | "web";
 /** Every attribute key any span may carry, with its value domain. */
 export interface AttrDomain {

package/dist/assets/src/execution/bindingPurge.ts CHANGED Viewed

@@ -14,8 +14,8 @@ export interface PurgeableBinding {
 export type PurgeDecision = { ok: true; purge: string[]; keptLive: string[] } | { ok: false; error: string };
 /** Thread-key namespaces real channels mint (docs/reference/specs/http-ingress.md item 1,
- *  slack, mcp, the CLI). A purge is for synthetic keys only. */
-const PRODUCTION_NAMESPACES = new Set(["slack", "http", "mcp", "cli"]);
+ *  slack, mcp, the CLI, the web chat). A purge is for synthetic keys only. */
+const PRODUCTION_NAMESPACES = new Set(["slack", "http", "mcp", "cli", "web"]);
 /** A prefix must be a whole namespace (`load:`) or longer (`load:r1:`), never
  *  empty, never a bare partial namespace, never a production namespace. */

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

@@ -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 CHANGED Viewed

@@ -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 ADDED Viewed

@@ -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 CHANGED Viewed

@@ -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;
@@ -234,6 +238,7 @@ export function classifyRefreshFailure(input: {
   const { step, message } = input;
   if (input.runtimeUnreachable) {
     return {
+      step,
       interrupted: false,
       diskFull: false,
       runtimeUnreachable: true,
@@ -242,6 +247,7 @@ export function classifyRefreshFailure(input: {
   }
   if (isDiskFullMessage(message)) {
     return {
+      step,
       interrupted: false,
       diskFull: true,
       runtimeUnreachable: false,
@@ -251,6 +257,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 +266,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 CHANGED Viewed

@@ -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 objects (fault injection)",
   "unmount-restores": "unmounting earlier restores",
   "mirror-restore-extract": "extracting the mirror snapshot",
   "checkout-restore-extract": "extracting the checkout snapshot",