@coreplane/switchboard 1.249.1 → 1.251.0

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

@@ -114,6 +114,8 @@ export type Resource =
       readonly visibility?: ChannelVisibility;
     }
   | { readonly type: "config-scope"; readonly kind: "user"; readonly id: string }
+  /** A thread's runtime scope (`config set thread`, routing-and-config item 27); `id` is the thread key. */
+  | { readonly type: "config-scope"; readonly kind: "thread"; readonly id: string }
   | { readonly type: "config-scope"; readonly kind: "org" }
   | { readonly type: "agent"; readonly name: string }
   /** List-shaped actions with no single resource (`runs.list`, `friction.report`). */

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

@@ -85,6 +85,19 @@ export const DRAIN = {
   defaultMinutes: 60,
 } as const;
 
+/** How long an intake receipt row is kept on the run history object
+ *  (docs/reference/specs/run-history.md item 59; docs/decisions/0058): the larger of one day
+ *  and the reconnect catch-up window the write named plus the drain deadline
+ *  (`DRAIN.maxMinutes`, the longest a fleet drain may last), so a catch-up
+ *  that runs after the longest allowed drain still reads the verdict instead
+ *  of deciding the reply again. The window is clamped to a month so a
+ *  misconfigured writer cannot make retention unbounded. */
+export const INTAKE_WINDOW_MAX_MS = 30 * DAY_MS;
+export function intakeReceiptRetentionMs(catchUpWindowMs: number): number {
+  const window = Math.min(Math.max(0, catchUpWindowMs), INTAKE_WINDOW_MAX_MS);
+  return Math.max(DAY_MS, window + minutesToMs(DRAIN.maxMinutes));
+}
+
 /** The presets that run the tool loop, and the one pipeline preset. */
 export const LOOP_PRESETS = ["general", "coding", "review", "research", "explore", "conductor"] as const;
 export type LoopPreset = (typeof LOOP_PRESETS)[number];

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

@@ -81,6 +81,124 @@ export function runFinishedEventType(runId: string): string {
   return `${RUN_FINISHED_EVENT_PREFIX}${runId}`;
 }
 
+/** A message into a thread an unfinished unit owns (record 0051's reply-as-event rule): one row
+ *  of the unit's event list, appended by the dispatcher, folded into the
+ *  unit's next coding spawn — or run as one fresh turn at the unit's end.
+ *  `mode` is a receipt of the owner's state at append (record 0051): `steer` into a
+ *  live run or between rounds, `wake` into an idle owner, `interrupt` into an
+ *  owner idle after a stop — never a switch the sender fills. */
+export type ThreadEventMode = "steer" | "wake" | "interrupt";
+
+export interface ThreadEventAttachment {
+  mediaType: string;
+  data: string;
+  name?: string;
+}
+
+export interface ThreadEvent {
+  /** Assigned by the store's append, in arrival order, per unit. */
+  seq: number;
+  /** The channel's message id, when the platform gave one. */
+  id?: string;
+  /** The sender (platform-namespaced) and the display name the channel knew. */
+  sender: string;
+  senderName?: string;
+  text: string;
+  attachments?: ThreadEventAttachment[];
+  /** How many attachments were dropped because the event was over the cap. */
+  attachmentsDropped?: number;
+  /** How many characters were cut from the end of `text` because the row was
+   *  still over the cap without any attachment. */
+  textDropped?: number;
+  mode: ThreadEventMode;
+  at: number;
+  /** The spawn step or run that consumed the event; absent while unconsumed. */
+  consumedBy?: string;
+}
+
+/** The most one durable event row may weigh, serialized — the durable inbox's
+ *  own cap (`DURABLE_INBOX_MAX_BYTES`), restated here because this contract is
+ *  node-free and the state Worker enforces it too. */
+export const THREAD_EVENT_MAX_BYTES = 400 * 1024;
+
+const serializedBytes = (v: unknown): number => new TextEncoder().encode(JSON.stringify(v)).length;
+
+/** The event under the cap: attachments ride when the serialized row fits,
+ *  else all of them are dropped and the row says how many — all or nothing,
+ *  like the durable inbox (a partial carry would hand the model some of the
+ *  sender's attachments as if they were all of them). A row still over the cap
+ *  with no attachment left — a text alone past 400 KiB, possible through the
+ *  ingress body — has its text cut from the end until the row fits, and the
+ *  row says how many characters went: no event escapes the constant's promise.
+ *  `TextEncoder`, not `Buffer`: both stores — the bot's and the state Worker's —
+ *  apply it. */
+export function capThreadEvent<T extends Omit<ThreadEvent, "seq"> & { seq?: number }>(
+  event: T,
+): T & Pick<ThreadEvent, "attachmentsDropped" | "textDropped"> {
+  if (serializedBytes(event) <= THREAD_EVENT_MAX_BYTES) return event;
+  const attachments = event.attachments;
+  let capped: T & Pick<ThreadEvent, "attachmentsDropped" | "textDropped"> = event;
+  if (attachments && attachments.length > 0) {
+    const { attachments: _dropped, ...rest } = event;
+    capped = { ...rest, attachmentsDropped: attachments.length } as typeof capped;
+    if (serializedBytes(capped) <= THREAD_EVENT_MAX_BYTES) return capped;
+  }
+  // Text-only overflow: the row's shape is fixed except for the text, so the
+  // text is cut — by characters, so a multibyte cut never splits a code point
+  // pair the decoder would read as garbage — and shrunk until the bytes fit.
+  const text = capped.text;
+  const overhead = serializedBytes({ ...capped, text: "", textDropped: text.length });
+  let keep = Math.max(0, Math.min(text.length, THREAD_EVENT_MAX_BYTES - overhead));
+  for (;;) {
+    const cut = { ...capped, text: text.slice(0, keep), textDropped: text.length - keep };
+    if (keep === 0 || serializedBytes(cut) <= THREAD_EVENT_MAX_BYTES) return cut;
+    keep = Math.floor(keep * 0.9);
+  }
+}
+
+const isThreadEventAttachment = (v: unknown): v is ThreadEventAttachment =>
+  isObject(v) &&
+  typeof v.mediaType === "string" &&
+  typeof v.data === "string" &&
+  (v.name === undefined || typeof v.name === "string");
+
+const isThreadEventMode = (v: unknown): v is ThreadEventMode => v === "steer" || v === "wake" || v === "interrupt";
+
+/** Structural check on an event row from outside the process. */
+export function isThreadEvent(v: unknown): v is ThreadEvent {
+  if (!isObject(v)) return false;
+  const r = v;
+  if (typeof r.seq !== "number" || !Number.isInteger(r.seq) || r.seq < 1) return false;
+  // The fixed fields are bounded too, so the cap's text cut has a floor to
+  // land on: a row whose id or names alone weighed the cap could never fit.
+  if (!isOptionalText(r.id)) return false;
+  if (!isText(r.sender)) return false;
+  if (!isOptionalText(r.senderName)) return false;
+  if (typeof r.text !== "string") return false;
+  if (r.attachments !== undefined && (!Array.isArray(r.attachments) || !r.attachments.every(isThreadEventAttachment)))
+    return false;
+  if (r.attachmentsDropped !== undefined && !isCount(r.attachmentsDropped)) return false;
+  if (r.textDropped !== undefined && !isCount(r.textDropped)) return false;
+  if (!isThreadEventMode(r.mode)) return false;
+  if (!isFinite(r.at)) return false;
+  if (!isOptionalText(r.consumedBy)) return false;
+  return true;
+}
+
+/** The payload-free nudge the dispatcher sends an instance when a thread
+ *  event lands on one of its units (record 0051's reply-as-event rule): the relay's
+ *  alphabet — letters, digits, `_` and `-`, at most 100 characters, a colon
+ *  refused — so the type is the two ids joined by `-`. The send addresses the
+ *  instance by id (`workflow.get(id)`), so the type only has to name the unit
+ *  within it: when the two ids together overflow the cap, the INSTANCE id is
+ *  clipped and the unit is kept whole, and both ends compute the same string. */
+export const UNIT_NUDGE_EVENT_PREFIX = "unit-nudge-";
+export function unitNudgeEventType(key: { instanceId: string; unit: string }): string {
+  const suffix = `-${key.unit}`;
+  const room = 100 - UNIT_NUDGE_EVENT_PREFIX.length - suffix.length;
+  return `${UNIT_NUDGE_EVENT_PREFIX}${key.instanceId.slice(0, room)}${suffix}`;
+}
+
 /** The event the bot's GitHub check-run intake sends a merge-waiting parent:
  *  the type carries the head sha (hex — inside the platform's alphabet), so a
  *  driver waiting at that head matches its own event and any other head's is
@@ -278,6 +396,8 @@ const MAX_ROUNDS = 200;
 const isText = (v: unknown, max = MAX_TEXT): v is string => typeof v === "string" && v.length > 0 && v.length <= max;
 const isOptionalText = (v: unknown): boolean => v === undefined || isText(v);
 const isFinite = (v: unknown): v is number => typeof v === "number" && Number.isFinite(v);
+/** A count the writers produce: a non-negative integer, never a fraction, a negative or NaN. */
+const isCount = (v: unknown): v is number => typeof v === "number" && Number.isInteger(v) && v >= 0;
 const isObject = (v: unknown): v is Record<string, unknown> => typeof v === "object" && v !== null;
 const isPr = (v: unknown): boolean => isObject(v) && isFinite(v.number) && isText(v.url, 2048);
 const isResume = (v: unknown): boolean =>

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

@@ -145,7 +145,7 @@ export function readBotAnswer(
 
 /** The answers the bot itself calls a passing condition — the step is asked
  *  again, under the policy. Everything else, refusals included, is the machine's. */
-const TRANSIENT = new Set(["github_unavailable", "no_channel", "thread_failed", "unit_not_started"]);
+const TRANSIENT = new Set(["github_unavailable", "no_channel", "thread_failed", "unit_not_started", "not_host"]);
 export function transientRefusal(answer: BotAnswer): string | undefined {
   const { ok, error, message } = answer.body;
   if (ok !== false || typeof error !== "string" || !TRANSIENT.has(error)) return undefined;
@@ -172,6 +172,8 @@ interface PlanFacts {
   grantSource: GrantSource;
   /** The instance's mark as the plan route answers it: a generated one-unit plan (a `plan` with no `path`). */
   generated: boolean;
+  /** The runs page base the bot answered: the report links a child's write-up to its run page with it. */
+  runPageBase?: string;
   repo: string;
   base: string;
   caps: ShipCaps;
@@ -217,6 +219,7 @@ function readPlan(a: BotAnswer): PlanFacts {
     grantSource:
       b.grantSource === "run" || b.grantSource === "user" || b.grantSource === "channel" ? b.grantSource : "org",
     generated: b.generated === true,
+    ...(typeof b.runPageBase === "string" && b.runPageBase.length > 0 ? { runPageBase: b.runPageBase } : {}),
     repo: b.repo,
     base: b.base,
     caps: { maxRounds: b.caps.maxRounds, maxMinutes: b.caps.maxMinutes },
@@ -318,7 +321,7 @@ function isCommitChecks(v: unknown): v is { total: number; pending: string[]; fa
 function prCheckReturn(step: string, a: BotAnswer): StepReturn {
   const { ok, state, prNumber, url, headSha, sha, mergedAt, at } = a.body;
   if (ok === true && state === "none") {
-    const { unrecovered, aheadOfBase } = a.body;
+    const { unrecovered, aheadOfBase, prClosed } = a.body;
     return {
       type: "pr-check",
       step,
@@ -328,6 +331,9 @@ function prCheckReturn(step: string, a: BotAnswer): StepReturn {
         // The branch's commits over the base, when the bot could read them
         // (agent-ship item 12): zero is the `already_landed` ending's fact.
         ...(typeof aheadOfBase === "number" ? { aheadOfBase } : {}),
+        // The followed pull request verified closed unmerged (issue 1799):
+        // the machine must not brief a review round on it.
+        ...(prClosed === true ? { prClosed: true } : {}),
       },
       at,
     };
@@ -453,12 +459,19 @@ async function perform(
     case "pr-check":
       // `recover` rides only after a dead coding child: the bot opens the pull
       // request from the pushed branch itself instead of answering `none`.
+      // `pr` is the machine's adopted pull request (issue 1799): the bot
+      // follows it when nothing heads the unit's branch and answers its live
+      // state instead of `none` over a minutes-old record fact.
       return prCheckReturn(
         action.step,
         answerOf(
           "pr-check",
           await step.do(action.step, STEP_CONFIG, () =>
-            call(bot, "pr-check", { ...tag, ...(action.recover !== undefined ? { recover: action.recover } : {}) }),
+            call(bot, "pr-check", {
+              ...tag,
+              ...(action.recover !== undefined ? { recover: action.recover } : {}),
+              ...(action.pr !== undefined ? { pr: action.pr } : {}),
+            }),
           ),
         ),
       );
@@ -537,6 +550,7 @@ async function runUnit(
       grant: plan.grant,
       grantSource: plan.grantSource,
       generated: plan.generated,
+      ...(plan.runPageBase !== undefined ? { runPageBase: plan.runPageBase } : {}),
       ...(resume !== undefined ? { resume } : {}),
       ...(lastPush !== undefined ? { lastPush } : {}),
       ...(session !== undefined ? { session } : {}),

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

@@ -10,7 +10,7 @@
 // catalog lives in ./modelRegistry.ts.
 
 import { EFFORT_LEVELS, type Effort } from "../effort.js";
-import { vendorOf, wireOf, type ProviderConfig, type Wire } from "./provider.js";
+import { billerHarnessProvider, vendorOf, wireOf, type ProviderConfig, type Wire } from "./provider.js";
 import type { RegistryCard } from "./modelRegistry.js";
 
 /** Which layer named a field: the operator's block, the registry card, or the
@@ -335,13 +335,29 @@ export function decideControls(card: ModelCard, asked: AskedControls): ControlDe
     why: windowVouched ? "" : `no layer names the window; compacting at ${card.window}`,
   });
 
-  const cacheNative = card.cache !== "unknown";
+  // A `markers` rule needs a harness-side write that places the markers
+  // (record 0052's amendment: the harness write names the biller's own
+  // provider). The Anthropic wire's own packages place per-block breakpoints;
+  // on the chat wire a biller the table names caches the aggregator's own way
+  // — the pinned OpenCode binary exempts the openrouter route from per-block
+  // placement, so the write carries OpenRouter's top-level
+  // `cache_control: { type: "ephemeral" }` via `settings.extraBody` (measured
+  // in `opencode/testing/realDriver.test.ts`), and pi's compat sends the
+  // per-block markers. A biller served generically degrades, never a silent
+  // `native`.
+  const markersUnplaced =
+    card.cache === "markers" && card.wire === "openai-chat" && billerHarnessProvider(card.block) === undefined;
+  const cacheNative = card.cache !== "unknown" && !markersUnplaced;
   decisions.push({
     control: "cache",
     outcome: cacheNative ? "native" : "degraded",
     applied: card.cache,
     vouched: cacheNative,
-    why: cacheNative ? "" : `no layer names ${card.model}'s cache rule`,
+    why: cacheNative
+      ? ""
+      : markersUnplaced
+        ? `no harness-side provider vouches for the "${card.block}" biller's cache markers; the rule goes out unvouched`
+        : `no layer names ${card.model}'s cache rule`,
   });
 
   return decisions;

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

@@ -37,6 +37,41 @@ export interface RenderedPointer extends Pointer {
   anchor: RenderedPrAnchor;
 }
 
+/** One reason a submitted description was refused, as the refusal and the
+ *  `description_refused` run note carry it: the zod path (`risk`,
+ *  `pointers.0.text`) and the schema's message; on a cap issue also the
+ *  characters to remove (visible ones — raw for the title) and the longest
+ *  prefix of the field that fits, cut at a word boundary (`fitToCap`), absent
+ *  when no word of it fits. */
+export interface DescriptionIssue {
+  path: string;
+  message: string;
+  remove?: number;
+  prefix?: string;
+}
+
+/** The refused object as the `description_refused` note records it: JSON,
+ *  nested at most four objects deep, and nothing else. The record crosses the
+ *  run store's RPC boundary, whose typing walks every field: a field of
+ *  `unknown` types the whole record `never`, and a recursive alias is
+ *  "excessively deep" to it, so the nesting is spelled out level by level
+ *  (as `RouteInputValue` is). A description is three deep at most —
+ *  `pointers[i].anchor` — so one level is to spare; `recordedJson` stores a
+ *  deeper value as its JSON text. */
+export type RecordedJsonLeaf = string | number | boolean | null;
+export type RecordedJsonObject1 = { readonly [key: string]: RecordedJsonLeaf | ReadonlyArray<RecordedJsonLeaf> };
+export type RecordedJson1 =
+  RecordedJsonLeaf | RecordedJsonObject1 | ReadonlyArray<RecordedJsonLeaf | RecordedJsonObject1>;
+export type RecordedJsonObject2 = { readonly [key: string]: RecordedJson1 };
+export type RecordedJson2 =
+  RecordedJsonLeaf | RecordedJsonObject2 | ReadonlyArray<RecordedJsonLeaf | RecordedJsonObject2>;
+export type RecordedJsonObject3 = { readonly [key: string]: RecordedJson2 };
+export type RecordedJson3 =
+  RecordedJsonLeaf | RecordedJsonObject3 | ReadonlyArray<RecordedJsonLeaf | RecordedJsonObject3>;
+export type RecordedJsonObject4 = { readonly [key: string]: RecordedJson3 };
+export type RecordedJson =
+  RecordedJsonLeaf | RecordedJsonObject4 | ReadonlyArray<RecordedJsonLeaf | RecordedJsonObject4>;
+
 /** The PR description as data (docs/decisions/0050): the map above the fold
  *  (tldr, why, pointers, feedbackWanted, risk, verified), every field capped
  *  so the map's size does not grow with the diff, and the collapsed half

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

@@ -95,9 +95,8 @@ export interface Provider {
 
 /** The three wire shapes a provider block may declare (record 0052):
  *  Anthropic's Messages API, OpenAI's Chat Completions and OpenAI's Responses
- *  API. `openai-responses` is a declaration only in this slice — the proxy
- *  still serves two routes (a later slice adds the third) — and a block that names it
- *  keeps routing through the compatible shape until then. */
+ *  API. Each is a proxy route of its own (`PROXY_PATHS`): an `openai-responses`
+ *  block runs on `/v1/responses`, pinned and metered like the other two. */
 export const WIRES = ["anthropic-messages", "openai-chat", "openai-responses"] as const;
 export type Wire = (typeof WIRES)[number];
 
@@ -123,6 +122,12 @@ export interface ProviderModelOverride {
   cache?: "automatic" | "markers" | "none" | "unknown";
   /** USD per million tokens, by kind. */
   price?: { input?: number; output?: number; cacheRead?: number; cacheWrite?: number };
+  /** The answer shapes the model can produce for a forced one-call turn (the
+   *  router's, intake's): `tool` — a forced tool call — and `text` — the
+   *  one-JSON-object text contract. Absent, both are assumed; an empty list
+   *  declares neither, and a load whose intake would classify on such a card
+   *  is refused by name (routing-and-config item 27). */
+  answers?: ("tool" | "text")[];
 }
 
 export interface ProviderConfig {
@@ -204,6 +209,55 @@ export function vendorOf(
   return { block, model, vendor: block, vendorId: model, vendorSource: "block" };
 }
 
+/** The harness-side provider a block's biller implies (record 0052's
+ *  amendment: the harness write names the biller's own provider, never a
+ *  generic alias). Keyed by the biller — the block's name — for the billers
+ *  whose protocol a harness bundles a provider for. The wires with a package
+ *  of their own (`anthropic-messages` → `@ai-sdk/anthropic`,
+ *  `openai-responses` → `@ai-sdk/openai`) need no entry: the wire names the
+ *  package. A chat-wire biller not here is served generically
+ *  (`@ai-sdk/openai-compatible`), under which a `markers` cache rule cannot be
+ *  vouched for (`decideControls`): the generic provider places no cache
+ *  breakpoints. */
+export interface BillerHarnessProvider {
+  /** The AI SDK package OpenCode's configuration names for the biller
+   *  (`openCodeProviderPackage` adds the `aisdk:` prefix). */
+  openCodePackage: string;
+  /** The compat words pi keys on the biller's identity, copied once from pi's
+   *  own completions detection of that biller and never inferred from a URL at
+   *  run time: through the proxy pi sees the bot's URL, so `piModelsJson` must
+   *  say the words the biller's own base URL would have made pi detect. */
+  piCompat: {
+    /** How the wire spells reasoning: `reasoning: { effort }` under
+     *  `"openrouter"`, never the completions shape's flat `reasoning_effort`. */
+    thinkingFormat: string;
+    /** How a session id would ride the headers, were affinity ever turned on. */
+    sessionAffinityFormat: string;
+    /** The vendor-qualified id prefixes the biller grants the developer role:
+     *  any other id is told `supportsDeveloperRole: false`, as pi's own
+     *  detection would say against the biller directly. */
+    developerRoleIdPrefixes: readonly string[];
+  };
+}
+
+/** The biller-to-provider table: one row per biller a harness speaks natively
+ *  — OpenCode's package (U44) and pi's compat words (U45) side by side. */
+export const BILLER_HARNESS_PROVIDERS: Readonly<Record<string, BillerHarnessProvider>> = {
+  openrouter: {
+    openCodePackage: "@openrouter/ai-sdk-provider",
+    piCompat: {
+      thinkingFormat: "openrouter",
+      sessionAffinityFormat: "openrouter",
+      developerRoleIdPrefixes: ["anthropic/", "openai/"],
+    },
+  },
+};
+
+/** The biller's harness-side provider, or undefined when it is served generically. */
+export function billerHarnessProvider(biller: string | undefined): BillerHarnessProvider | undefined {
+  return biller === undefined ? undefined : BILLER_HARNESS_PROVIDERS[biller];
+}
+
 /** The env var Anthropic's own SDK reads when an `anthropic` provider block names none. */
 export const ANTHROPIC_API_KEY_ENV = "ANTHROPIC_API_KEY";
 

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

@@ -22,6 +22,17 @@ export interface Guess {
   evidence: string;
 }
 
+/** A command handler's guess hint (record 0054): the corrected chat form and
+ *  the evidence, without the full proposal — the proposal is synthesised at
+ *  the invocation point from the original message and this hint's `line`. The
+ *  handler carries this lighter type on `CommandError.guess`; the adapter
+ *  (`invokeChatCommand`, `answerCommand`) builds the `Guess` that
+ *  `renderRefusal` expects. */
+export interface CommandGuessHint {
+  line: string;
+  evidence: string;
+}
+
 /** One cause per code — the closed table `causeOf` reads. The codes are the
  *  inventory's: the dispatch gates' `refuse(code)` outcomes, the click's four
  *  `confirmation_*` codes, the two `elsewhere_*` reasons that never reached a
@@ -45,6 +56,8 @@ const CAUSE_OF = {
   which_branch: "request",
   workspace_lost: "system",
   ship_budget: "request",
+  // one pipeline per thread (record 0060): the host key's claim answered thread-live
+  ship_thread_live: "request",
   setup_failed: "system",
   // the click on a confirmation (confirm.ts)
   confirmation_used: "request",
@@ -95,6 +108,7 @@ const CAUSE_OF = {
   directive_budget: "request",
   directive_severity: "request",
   directive_renewals: "request",
+  directive_verbosity: "request",
   provider_unknown: "request",
   // the model card's refusal (record 0052, model-proxy item 11): a control the
   // resolved card does not take, named before any card or model call

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

@@ -1,7 +1,7 @@
 // Types only, and from the zod-free module deliberately: this file is part of
 // 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, RenderedPointer } from "./prDescriptionTypes.js";
+import type { DescriptionIssue, PrDescription, RecordedJson, RenderedPointer } from "./prDescriptionTypes.js";
 import type { HarnessScope } from "./harness/scope.js";
 import type { ModelCard } from "./modelCard.js";
 
@@ -146,6 +146,15 @@ export type RunNoteKind =
    *  bounded extra model turn to submit it (docs/reference/specs/pr-description.md
    *  item 5). Published by the dispatcher before that turn. */
   | "description_turn"
+  /** `submit_pr_description` refused the object (docs/reference/specs/pr-description.md
+   *  item 5): the summary counts the fields over their cap and names them
+   *  (or the issues, when none is a cap), `description` is the object as
+   *  submitted — redacted like the accepted `pr_description` event's, and not
+   *  necessarily a valid `PrDescription` — and `issues` the refusal's list
+   *  with each cap's count to remove and the prefix that fits, so the record
+   *  says what the model changed between one submit and the next. Published
+   *  by the tool, before it answers. */
+  | "description_refused"
   /** A review run's loop ended on a pull request without `submit_verdict`, and
    *  the same run is being given one bounded extra model turn to call it
    *  (docs/reference/specs/agent-review.md item 5; verdictTurn.ts). Published by
@@ -273,7 +282,15 @@ export type RunNoteKind =
   /** 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. */
-  | "stuck_loop";
+  | "stuck_loop"
+  /** OpenCode's reject cascade ended the execution `interrupted` after the bot
+   *  refused one of a step's two (or more) calls — the binary declines every
+   *  other pending ask at a reject and ends the step `session.step.failed
+   *  {aborted}`, the execution ending `session.execution.interrupted` — and the
+   *  model never read the refusal. The loop re-prompts with the refusal so the
+   *  model can continue, exactly as it does after a single refusal. Published
+   *  by the OpenCode bridge. */
+  | "decline_cascade";
 
 /** Every `RunNoteKind`, as a value (a reader that filters notes by kind uses
  *  this; adding a kind to the union without adding it here is a type error). */
@@ -298,6 +315,7 @@ export const RUN_NOTE_KINDS = [
   "seed",
   "redispatch",
   "description_turn",
+  "description_refused",
   "verdict_turn",
   "cold_sandbox",
   "ledger_untracked",
@@ -316,6 +334,7 @@ export const RUN_NOTE_KINDS = [
   "directory_reached",
   "budget_salvage",
   "stuck_loop",
+  "decline_cascade",
 ] as const satisfies readonly RunNoteKind[];
 type _EveryKindListed = [RunNoteKind] extends [(typeof RUN_NOTE_KINDS)[number]] ? true : never;
 const _everyKindListed: _EveryKindListed = true;
@@ -566,6 +585,12 @@ export type RunEvent =
        *  interval the dropped setup records covered — a `not recorded` loss. */
       from?: number;
       to?: number;
+      /** On a `description_refused` note only: the refused object as submitted
+       *  (JSON, not necessarily a valid `PrDescription`; `RecordedJson` says
+       *  why it is typed level by level), every string leaf redacted, and the
+       *  issues the refusal named. */
+      description?: RecordedJson;
+      issues?: DescriptionIssue[];
       spanId?: string;
       seq?: number;
       at?: number;
@@ -600,6 +625,13 @@ export type RunEvent =
        *  run sent rather than a person (a parent's `send_to_run`), that run's
        *  id (docs/reference/specs/agent-conductor.md item 8). */
       source?: { url?: string; channel?: string; user?: string; run?: string };
+      /** How the turn was delivered when it consumed a unit's thread events
+       *  (record 0051's mode-as-receipt rule): the mode read off the owner's state when
+       *  each event arrived — a receipt, never a switch — and the sequence
+       *  numbers consumed, so the record names the events it folded. Absent on
+       *  every run that consumed none. */
+      mode?: "steer" | "wake" | "interrupt";
+      consumed?: number[];
       seq?: number;
       at?: number;
     }
@@ -826,6 +858,13 @@ export type RunEvent =
    *  `base` is absent when the spawn knew none; the post-step then falls to
    *  the coordinator store's `instance.base`. Additive: unknown → ignored. */
   | { type: "coordinator_tag"; parentInstanceId: string; unit?: string; base?: string; seq?: number; at?: number }
+  /** The plan runner instance a ship run's hand-off created (record 0051 R2;
+   *  docs/reference/specs/run-history.md item 2): published by the ship branch
+   *  after `handOffToCoordinator` succeeds, straight to the registry like
+   *  `pr_opened`, and projected onto `RunRecord.instanceId` the way
+   *  `coordinator_tag` is — so the thread's owner rule can find the instance
+   *  from the page's ship run. Additive: unknown → ignored. */
+  | { type: "ship_handoff"; instanceId: string; seq?: number; at?: number }
   /** The review post-step's outcome when the verdict landed
    *  (docs/reference/specs/agent-review.md item 18): the pull request it was
    *  posted to, the head it was pinned to (the carried head after a rebase,
@@ -915,6 +954,14 @@ export type RunEvent =
       seq?: number;
       at?: number;
     }
+  /** A refusal the door made ([record 0054](../../docs/decisions/0054-a-refusal-the-person-caused-is-one-question-with-a-best-guess.md),
+   *  as amended: every refusal is a run record; run-history.md item 2): the
+   *  code, its one cause, and the sentence the person read — redacted and
+   *  capped like a route receipt (`ROUTE_RECEIPT_CAP`). Exactly one per `door`
+   *  record, published by `recordRefusal` beside the redacted request, so the
+   *  door report counts every refusal — a gate refusal before any command is
+   *  bound included — from the run store alone. Additive: unknown → ignored. */
+  | { type: "refusal"; code: string; cause: string; text: string; seq?: number; at?: number }
   /** The span records (docs/reference/specs/tracing.md): published, counted and stored like
    *  every other event, read as timing and never as content. */
   | SpanStartEvent

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

@@ -422,9 +422,11 @@ export function analyzeRunFriction(events: readonly RunEvent[], opts: FrictionOp
       ev.type === "pr_description" ||
       ev.type === "pr_opened" ||
       ev.type === "coordinator_tag" ||
+      ev.type === "ship_handoff" ||
       ev.type === "review_posted" ||
       ev.type === "ship_round" ||
       ev.type === "route" ||
+      ev.type === "refusal" ||
       ev.type === "reference" ||
       ev.type === "lease" ||
       ev.type === "pushed_head"

package/dist/assets/src/core/runLedger/decisions.ts

@@ -2,7 +2,7 @@
 // Durable Object applies them inside one transaction; the in-memory ledger
 // applies them in tests; both agree because this is the only copy.
 
-import type { ClaimResult, FenceResult, LivePhase } from "./types.js";
+import type { ClaimResult, FenceResult, IntakeReceipt, IntakeWriteResult, LivePhase } from "./types.js";
 
 /** One live run per thread. The existing row, if any, is what `live_runs` holds
  *  for the thread; the same run re-claimed by its owner is idempotent (a retry
@@ -26,6 +26,14 @@ export function decideClaim(
   };
 }
 
+/** First writer wins on an intake receipt (item 59): the existing row, if
+ *  any, is what `intake_receipts` holds for the key; only when none stands
+ *  does this write land, and every caller acts on the STORED row. */
+export function decideIntakeInsert(existing: IntakeReceipt | undefined, receipt: IntakeReceipt): IntakeWriteResult {
+  if (existing) return { inserted: false, stored: existing };
+  return { inserted: true, stored: receipt };
+}
+
 /** What an accepted claim does to the thread's row (item 42). `insert`: no row.
  *  `promote`: the owner's claim WITH a prompt on its own `attaching` row — the
  *  prompt, tools, card and state land and the phase goes `live`, identity and

package/dist/assets/src/core/runLedger/sessionLog.ts

@@ -84,6 +84,16 @@ export function roleOfStoredRow(json: string): "user" | "assistant" | undefined
   return role === "user" || role === "assistant" ? role : undefined;
 }
 
+/** The platform-namespaced id of the person who authored the turn a stored
+ *  row belongs to (e.g. `slack:U…`); absent for machine turns, compaction
+ *  rows, unreadable rows, and rows written before record 0057. */
+export function actorOfStoredRow(json: string): string | undefined {
+  const stored = parseStored(json);
+  if (!stored || "compaction" in stored) return undefined;
+  const actor = (stored as { actor?: unknown }).actor;
+  return typeof actor === "string" ? actor : undefined;
+}
+
 /** The notepad's size (record 0035, "The notepad"): one document per session,
  *  written whole, at most this many UTF-8 bytes; `notes` refuses over it naming
  *  the size, and the object's write route does too. */

package/dist/assets/src/core/runLedger/transcript.ts

@@ -23,10 +23,13 @@ import {
 // ~4.2 MB on the wire.
 
 /** The stored form of one part: the turn's role rides on every row so a turn
- *  is reconstructible from its rows alone. */
+ *  is reconstructible from its rows alone. The actor is the platform-namespaced
+ *  id of the person who authored the turn (e.g. `slack:U…`); absent for
+ *  machine turns and rows written before record 0057. */
 export interface StoredPart {
   role: ChatMessage["role"];
   part: ContentPart | (ContentPart & { dataRef: string });
+  actor?: string;
 }
 
 /** The stored form of a compaction row: no role, no part — the entry alone. */
@@ -46,11 +49,14 @@ const isCompaction = (v: ChatMessage | StoredCompaction): v is StoredCompaction
 
 /** One turn → its rows (and any externalized attachments). Refuses a part the
  *  row budget cannot hold: a transcript is never truncated. A compaction entry
- *  is one row at its index, part 0. */
+ *  is one row at its index, part 0. The optional `actor` is the
+ *  platform-namespaced id of the person who authored the turn (absent for
+ *  machine turns, compaction rows and rows written before record 0057). */
 export function turnRows(
   idx: number,
   message: ChatMessage | StoredCompaction,
   opts: { partBytes?: number; attachmentRefBytes?: number } = {},
+  actor?: string,
 ): { rows: TranscriptRow[]; attachments: TranscriptAttachment[] } {
   const partBytes = opts.partBytes ?? TRANSCRIPT_PART_BYTES;
   const refBytes = opts.attachmentRefBytes ?? ATTACHMENT_REF_BYTES;
@@ -73,7 +79,11 @@ export function turnRows(
       attachments.push({ ref, mediaType: part.mediaType, data: part.data });
       stored = { ...(part as ContentPart), data: "", dataRef: ref } as StoredPart["part"];
     }
-    const json = JSON.stringify({ role: message.role, part: stored } satisfies StoredPart);
+    const json = JSON.stringify({
+      role: message.role,
+      part: stored,
+      ...(actor !== undefined ? { actor } : {}),
+    } satisfies StoredPart);
     const bytes = utf8ByteLength(json);
     if (bytes > partBytes) {
       throw new Error(`transcript: part ${i} of turn ${idx} is ${bytes} bytes, over the ${partBytes} row budget`);