@coreplane/switchboard 1.241.0 → 1.242.0

package/dist/assets/src/agents/registry.ts

@@ -223,6 +223,14 @@ export const FENCED_CONTENT_RULE =
 const NOTEPAD = `YOUR NOTES AND YOUR REACH BACK. This thread's conversation outlives your context window and this run: every turn — yours, the person's, every tool call and its output, from this run and the runs before it in this thread — is kept in a log you can search with the \`recall\` tool (words → the matching turns with their numbers; a turn number → that turn whole). When something you need is no longer in front of you, recall it instead of redoing the work or guessing.
 Keep notes with the \`notes\` tool: one short document, replaced whole each time, at most 8 KiB — decisions and their reasons, the names of things you found (files, tests, commits, the head your tests were green at), what is not yet proven. They are the one thing sure to survive a compaction and to reach the next run in this thread: they ride your system prompt at its start and come back to you right after a compaction. A person reads them too, on the run's page, so write them as a document and never as one paragraph: Markdown, a \`##\` heading per section — \`Done\`, \`In progress\`, \`Next\`, \`Facts\` (names, ids, heads, the reasons behind decisions), leaving out a section with nothing in it — one bullet per item, one line per bullet, no prose walls. Write them when you decide something worth keeping, not only at the end.`;
 
+// Every coding prompt carries this verbatim (docs/reference/specs/agent-coding.md
+// item 13): the order of checks and the push. Three plan children died at their
+// budget in one evening with finished work unpushed because each ran the
+// project's most expensive checks first; the rule is the runner's to hold, not
+// a line every requester remembers to paste. Stack-agnostic on purpose — the
+// classes are by duration, the project's own scripts and CI say which is which.
+export const CHECKS_BY_COST = `CHECKS BY COST — push before the expensive ones. Every check you might run has a cost class: seconds (a formatter or a linter on the files you touched, one test file, a docs, link or spec check, the typecheck of one package) or minutes (the whole test suite, a build, a dependency install, an end-to-end or full verification). Know a command's class before you run it — from the project's own scripts and CI configuration, from how long it took last time, or by the class above when you have nothing better. Prove each change with the cheapest check that can prove it, matched to the change's scope: a documentation change gets the documentation checks, one module gets its own tests, a shared type gets the typecheck. As soon as the change exists and those checks pass, commit and push — the pushed branch is the deliverable, and an unpushed tree does not survive the run's end. Only then run the expensive checks, once, and fix forward with further commits and pushes. Never start an operation whose expected duration does not fit the time you have left minus what a commit, a push and the description need: push what there is and say plainly what is unverified instead. The description's validation names exactly what ran; what did not run is CI's to gate, and you say so.`;
+
 const CODING_SYSTEM = `You are Switchboard's coding agent, operating from a Slack request.
 
 You work inside a dedicated workspace directory with bash, read_file, and write_file tools. ${SANDBOX_TOOLCHAIN}
@@ -237,10 +245,13 @@ Workflow for shipping a PR:
 1. Clone the repo into the workspace if it's not already there (use gh or git; both are authenticated on this host). Orient with a few BATCHED commands (tree + the relevant files in one call), not file-by-file exploration.
 2. Create a branch with a descriptive name.
 3. Implement the change. Match the surrounding code's style and conventions.
-4. Run the project's tests/linters if they exist and are quick enough to run.
-5. Commit with a clear message and push the branch.
-6. Call the submit_pr_description tool with the typed description object (content contract below) — every time, bringing forward the context you gained while implementing. Switchboard renders the PR body from your object at the pushed head and opens (or updates) the pull request itself: do NOT open a PR yourself, with \`gh\` or any API call.
-7. Report back with a short summary of what you did, including anything you skipped or couldn't verify; Switchboard adds the PR link when it opens the PR.
+4. Prove the change with the cheapest checks that can (CHECKS BY COST below): the linter and the tests nearest the files you touched, the documentation checks for a documentation change.
+5. Commit with a clear message and push the branch — before any full suite, build or full verification.
+6. Then, if the budget allows, run the project's expensive checks once and fix forward with further commits and pushes.
+7. Call the submit_pr_description tool with the typed description object (content contract below) — every time, bringing forward the context you gained while implementing. Switchboard renders the PR body from your object at the pushed head and opens (or updates) the pull request itself: do NOT open a PR yourself, with \`gh\` or any API call.
+8. Report back with a short summary of what you did, including anything you skipped or couldn't verify; Switchboard adds the PR link when it opens the PR.
+
+${CHECKS_BY_COST}
 
 ${NEVER_MERGE}
 
@@ -279,11 +290,14 @@ Environment notes:
 Workflow for shipping a change:
 1. Create a branch with a descriptive name off the bound branch.
 2. Implement the change. Match the surrounding code's style and conventions.
-3. Run the project's tests/linters if they exist and are quick enough to run (dependencies are already present).
-4. Commit with a clear message and push the branch with \`git push -u origin <branch>\`.
-5. Call the \`diff_digest\` tool to get a distilled summary of your change — per-file churn, totals, and risky-file flags. It is a distilled summary, not the raw diff: use it to shape the description you submit next — which files the Tour must walk, what belongs in risks.
-6. Call the submit_pr_description tool with the typed description object (content contract below) — every time. Switchboard renders the PR body from your object at the pushed head and opens (or updates) the pull request itself: do NOT open a PR yourself, with any API call.
-7. Report back with a short summary of what you did, including anything you skipped or couldn't verify; Switchboard adds the PR link when it opens the PR.
+3. Prove the change with the cheapest checks that can (CHECKS BY COST below): the linter and the tests nearest the files you touched, the documentation checks for a documentation change (dependencies are already present).
+4. Commit with a clear message and push the branch with \`git push -u origin <branch>\` — before any full suite, build or full verification.
+5. Then, if the budget allows, run the project's expensive checks once and fix forward with further commits and pushes.
+6. Call the \`diff_digest\` tool to get a distilled summary of your change — per-file churn, totals, and risky-file flags. It is a distilled summary, not the raw diff: use it to shape the description you submit next — which files the Tour must walk, what belongs in risks.
+7. Call the submit_pr_description tool with the typed description object (content contract below) — every time. Switchboard renders the PR body from your object at the pushed head and opens (or updates) the pull request itself: do NOT open a PR yourself, with any API call.
+8. Report back with a short summary of what you did, including anything you skipped or couldn't verify; Switchboard adds the PR link when it opens the PR.
+
+${CHECKS_BY_COST}
 
 ${NEVER_MERGE}
 
@@ -318,11 +332,14 @@ THE REPOSITORY IS ALREADY CLONED at \`/workspace/checkout\` — seeded from the
 Workflow for shipping a change:
 1. Create a branch with a descriptive name off the current branch.
 2. Implement the change. Match the surrounding code's style and conventions.
-3. Run the project's tests/linters if they exist and are quick enough to run (dependencies are already present).
-4. Commit with a clear message and push the branch with \`git push -u origin <branch>\`.
-5. Call the \`diff_digest\` tool to get a distilled summary of your change — per-file churn, totals, and risky-file flags. It is a distilled summary, not the raw diff: use it to shape the description you submit next — which files the Tour must walk, what belongs in risks.
-6. Call the submit_pr_description tool with the typed description object (content contract below) — every time. Switchboard renders the PR body from your object at the pushed head and opens (or updates) the pull request itself: do NOT open a PR yourself, with \`gh\` or any API call.
-7. Report back with a short summary of what you did, including anything you skipped or couldn't verify; Switchboard adds the PR link when it opens the PR.
+3. Prove the change with the cheapest checks that can (CHECKS BY COST below): the linter and the tests nearest the files you touched, the documentation checks for a documentation change (dependencies are already present).
+4. Commit with a clear message and push the branch with \`git push -u origin <branch>\` — before any full suite, build or full verification.
+5. Then, if the budget allows, run the project's expensive checks once and fix forward with further commits and pushes.
+6. Call the \`diff_digest\` tool to get a distilled summary of your change — per-file churn, totals, and risky-file flags. It is a distilled summary, not the raw diff: use it to shape the description you submit next — which files the Tour must walk, what belongs in risks.
+7. Call the submit_pr_description tool with the typed description object (content contract below) — every time. Switchboard renders the PR body from your object at the pushed head and opens (or updates) the pull request itself: do NOT open a PR yourself, with \`gh\` or any API call.
+8. Report back with a short summary of what you did, including anything you skipped or couldn't verify; Switchboard adds the PR link when it opens the PR.
+
+${CHECKS_BY_COST}
 
 ${NEVER_MERGE}
 

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

@@ -83,15 +83,18 @@ interface BoundFields {
   userName?: string;
 }
 
-/** The actor id whose grants govern a chat message: the credential that
- *  authenticated it when it was bound to a person (`authenticatedAs`), else
- *  the sender. Every `canRunAgent` / `canUseRepo` / `canManageRepos` /
- *  `canEditChannelConfig` question in the dispatch path asks about THIS id,
- *  never `msg.userId`: naming the person on a run must not lend the run the
- *  person's grants (authorization.md item 15). A relayed message (`postedBy`)
- *  is out of scope here — its gates are item 14's. */
-export function grantsSubject(msg: { userId: string; authenticatedAs?: string }): string {
-  return msg.authenticatedAs ?? msg.userId;
+/** The actor every gate in the dispatch path decides on: `resolveChatActor`
+ *  over the message, with config's grants lookup. Every `canRunAgent` /
+ *  `canUseRepo` / `canManageRepos` / `canEditChannelConfig` question asks
+ *  about THIS actor, never `msg.userId`: a relayed message (`postedBy`,
+ *  authorization.md item 14) decides on the app ∩ the person, a bound
+ *  credential (`authenticatedAs`, item 15) on the credential alone — naming
+ *  a person on a run never lends the run the person's grants. */
+export function chatActorOf(
+  config: { grantsFor: GrantsLookup },
+  msg: { userId: string; channelId: string; threadKey: string; postedBy?: string } & BoundFields,
+): Actor {
+  return resolveChatActor(msg, (id) => config.grantsFor(id));
 }
 
 const CHAT_SURFACES: Readonly<Record<string, ActorSurface>> = {

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

@@ -63,6 +63,14 @@ export function principalOf(actor: Actor): Actor {
   return current;
 }
 
+/** The channels the decision's person is in: the root principal's
+ *  `memberOf`, as `selfIdsOf` reads its `self` — a fact from the channel
+ *  directory, never a grant; absent → the empty set. */
+export function memberChannelsOf(actor: Actor): ReadonlySet<string> {
+  return principalOf(actor).memberOf ?? EMPTY_SET;
+}
+const EMPTY_SET: ReadonlySet<string> = new Set();
+
 /** The ids that mean "me" for a decision (record 0042): the root principal's
  *  `self` when it carries one — its own id and the person a dashboard session
  *  is linked to — else its id alone. Never read by a grant check. */
@@ -117,6 +125,7 @@ export function evaluateCondition(
   grants: Grants,
   selfIds: readonly string[],
   attributes: ResourceAttributes,
+  memberOf: ReadonlySet<string> = EMPTY_SET,
 ): boolean {
   switch (condition.kind) {
     case "has-grant": {
@@ -124,11 +133,13 @@ export function evaluateCondition(
       return grant !== undefined && hasAction(grants.actions, grant);
     }
     case "member-of":
-      // Granted the channel, or the channel is public (a run's stamped
+      // Granted the channel, in the channel (the directory's fact on the
+      // actor), or the channel is public (a run's stamped
       // visibility). `unknown` — no stamp, a directory failure — is never
       // public: fail-closed.
       return (
-        (attributes.channelId !== undefined && holds(grants.channels, attributes.channelId)) ||
+        (attributes.channelId !== undefined &&
+          (holds(grants.channels, attributes.channelId) || memberOf.has(attributes.channelId))) ||
         attributes.channelVisibility === "public"
       );
     case "is-self":
@@ -154,7 +165,8 @@ export function evaluateRule(rule: Rule, actor: Actor, resource: Resource): bool
   if (rule.originVisibility && !rule.originVisibility.includes(attributes.visibility)) return false;
   const grants = effectiveGrants(actor);
   const selfIds = selfIdsOf(actor);
-  return rule.when.every((condition) => evaluateCondition(condition, grants, selfIds, attributes));
+  const memberOf = memberChannelsOf(actor);
+  return rule.when.every((condition) => evaluateCondition(condition, grants, selfIds, attributes, memberOf));
 }
 
 /** `authorize` over an explicit (validated) table. Tests use it to drive
@@ -173,9 +185,10 @@ export function authorizeWith(rules: readonly Rule[], actor: Actor, action: Acti
   if (forOrigin.length === 0) return deny("origin-visibility");
   const grants = effectiveGrants(actor);
   const selfIds = selfIdsOf(actor);
+  const memberOf = memberChannelsOf(actor);
   let reason: DenyReason | undefined;
   for (const rule of forOrigin) {
-    const failed = rule.when.find((condition) => !evaluateCondition(condition, grants, selfIds, attributes));
+    const failed = rule.when.find((condition) => !evaluateCondition(condition, grants, selfIds, attributes, memberOf));
     if (!failed) return ALLOW;
     reason ??= FAILURE_REASON[failed.kind];
   }

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

@@ -57,6 +57,15 @@ export interface Actor {
   readonly self?: readonly string[];
   /** The linked person, for display and the audit line (`asUser`); absent when unlinked. */
   readonly asUser?: { readonly id: string; readonly name?: string };
+  /**
+   * The channels the platform says the actor's person is in: the
+   * channel directory's `channelsOf`, resolved once with the actor — a fact
+   * about the person, never a grant from config. `member-of` reads it beside
+   * `grants.channels`, so a private channel's runs and config open to the
+   * people in it. Absent (no directory, a lookup failure, an unlinked session)
+   * → nothing: fail-closed, exactly today's behaviour.
+   */
+  readonly memberOf?: ReadonlySet<string>;
 }
 
 /** `<group>:<read|write|exec>` plus the non-command actions. A plain
@@ -184,4 +193,7 @@ export type Predicate =
 export interface ChannelDirectory {
   info(channelId: string): Promise<{ visibility: ChannelVisibility }>;
   isMember(actorId: string, channelId: string): Promise<boolean | "unknown">;
+  /** Every channel the actor is in, platform-namespaced — what the resolver puts on
+   *  `Actor.memberOf`; `unknown` when the adapter cannot say (fail-closed). */
+  channelsOf(actorId: string): Promise<ReadonlySet<string> | "unknown">;
 }

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

@@ -150,6 +150,8 @@ export interface CoordinatorInstance {
   /** The bound credential behind the person (authorization.md item 15), when
    *  there was one: every child is authorized under ITS grants, as the request was. */
   authenticatedAs?: string;
+  /** The app that relayed the request for the person (authorization.md item 14), when one did: every child is authorized under app ∩ person, as the request was. */
+  postedBy?: string;
   channelId: string;
   channelName?: string;
   /** The requesting thread: where the card lives and where a generated plan's
@@ -260,7 +262,7 @@ export function isCoordinatorInstance(v: unknown): v is CoordinatorInstance {
   if (r.kind !== "ship") return false;
   if (!isText(r.userId) || !isText(r.channelId) || !isText(r.threadKey)) return false;
   if (!isOptionalText(r.userName) || !isOptionalText(r.channelName) || !isOptionalText(r.sourceUrl)) return false;
-  if (!isOptionalText(r.authenticatedAs)) return false;
+  if (!isOptionalText(r.authenticatedAs) || !isOptionalText(r.postedBy)) return false;
   if (typeof r.repo !== "string" || !REPO_SLUG.test(r.repo)) return false;
   if (!isText(r.branch) || !isOptionalText(r.base)) return false;
   if (!isFinite(r.createdAt)) return false;

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

@@ -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> {

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

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

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

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

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

@@ -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/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;
@@ -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

@@ -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",