@coreplane/switchboard 1.260.4 → 1.260.6

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

@@ -98,6 +98,386 @@ export interface Provider {
   complete(req: CompletionRequest): Promise<CompletionResult>;
 }
 
+/** Every model-call failure crosses this one seam. The cause is deliberately
+ * small and wire-neutral: adapters classify status plus structured body once;
+ * callers decide from `cause` and render only `renderProviderFailure(cause)`.
+ * `operatorUrl` is retained for an admin surface and never appears in the
+ * error's message or the user-facing renderer. */
+export const PROVIDER_FAILURE_CAUSES = [
+  "transient",
+  "rate-limited",
+  "credit-or-quota-exhausted",
+  "key-absent",
+  "key-invalid",
+  "model-unknown",
+  "request-rejected",
+  "permanent",
+] as const;
+export type ProviderFailureCause = (typeof PROVIDER_FAILURE_CAUSES)[number];
+
+export interface ProviderFailureAnswer {
+  status?: number;
+  body?: unknown;
+  error?: unknown;
+  provider?: string;
+  model?: string;
+  /** Only adapters that verified the model proxy's response-specific HMAC
+   * marker may set this. Provider response bodies are never trusted to name
+   * their own disposition. */
+  trustedEnvelope?: boolean;
+}
+
+export interface ProviderSchemaRejection {
+  tool: string;
+  keyword: string;
+}
+
+export interface ProviderFailureDetails extends Pick<ProviderFailureAnswer, "status" | "provider" | "model"> {
+  operatorUrl?: string;
+  /** The configured variable involved in a key failure. It is operator-safe
+   * diagnostic context, never part of the requester-facing renderer. */
+  keyVariable?: string;
+  /** Vouched evidence minted at the provider boundary when its response names
+   * one offered tool and one schema keyword. Callers may repair only on
+   * this pair, never on a generic 400 or provider-controlled prose. */
+  schemaRejection?: ProviderSchemaRejection;
+}
+
+function providerFailureDiagnostic(cause: ProviderFailureCause, details: ProviderFailureDetails): string {
+  if (details.provider !== undefined && details.keyVariable !== undefined) {
+    if (cause === "key-absent") return `Provider "${details.provider}": ${details.keyVariable} is not set`;
+    if (cause === "key-invalid") return `Provider "${details.provider}": ${details.keyVariable} was refused`;
+  }
+  return renderProviderFailure(cause);
+}
+
+export class ProviderFailure extends Error {
+  override readonly name = "ProviderFailure";
+  override readonly cause: ProviderFailureCause;
+  readonly status: number | undefined;
+  readonly provider: string | undefined;
+  readonly model: string | undefined;
+  readonly operatorUrl: string | undefined;
+  readonly keyVariable: string | undefined;
+  readonly schemaRejection: ProviderSchemaRejection | undefined;
+
+  constructor(cause: ProviderFailureCause, details: ProviderFailureDetails = {}) {
+    super(providerFailureDiagnostic(cause, details));
+    this.cause = cause;
+    this.status = details.status;
+    this.provider = details.provider;
+    this.model = details.model;
+    this.operatorUrl = details.operatorUrl;
+    this.keyVariable = details.keyVariable;
+    this.schemaRejection = details.schemaRejection;
+  }
+}
+
+export type ProviderFailureSurface = "parked" | "ended";
+
+/** One cause, one sentence for the surface that owns the disposition. Only a
+ * live leased turn may promise continuation; every pre-run door defaults to
+ * an ending-safe sentence. No wire payload, provider URL or recovery
+ * instruction is accepted as an input. */
+export function renderProviderFailure(cause: ProviderFailureCause, surface: ProviderFailureSurface = "ended"): string {
+  switch (cause) {
+    case "transient":
+      return surface === "parked"
+        ? "The model provider is temporarily unavailable; your work is kept and will continue when service recovers."
+        : "The model provider is temporarily unavailable; this request did not start.";
+    case "rate-limited":
+      return surface === "parked"
+        ? "The model provider is rate-limited; your work is kept and will continue when capacity returns."
+        : "The model provider is rate-limited; this request did not start.";
+    case "credit-or-quota-exhausted":
+      return surface === "parked"
+        ? "The model provider's credit or quota is exhausted; your work is kept and will continue when service recovers."
+        : "The model provider's credit or quota is exhausted; this request did not start.";
+    case "key-absent":
+      return "The model provider key is not configured; this request cannot start until the service is restored.";
+    case "key-invalid":
+      return "The model provider key was refused; this request cannot start until the service is restored.";
+    case "model-unknown":
+      return "The configured model is unavailable from its provider; this request cannot start until the service is restored.";
+    case "request-rejected":
+      return "The model provider rejected the request shape; no work was started.";
+    case "permanent":
+      return "The model provider refused the call; the request ended without exposing the provider's response.";
+  }
+}
+
+const providerFailureRecord = (value: unknown): Record<string, unknown> | undefined =>
+  typeof value === "object" && value !== null && !Array.isArray(value) ? (value as Record<string, unknown>) : undefined;
+
+function providerSchemaRejectionRecord(value: unknown): ProviderSchemaRejection | undefined {
+  const row = providerFailureRecord(value);
+  return typeof row?.tool === "string" &&
+    row.tool.length > 0 &&
+    typeof row.keyword === "string" &&
+    row.keyword.length > 0
+    ? { tool: row.tool, keyword: row.keyword }
+    : undefined;
+}
+
+function providerFailureBody(body: unknown): unknown {
+  if (typeof body !== "string") return body;
+  const text = body.trim();
+  try {
+    return JSON.parse(text) as unknown;
+  } catch {
+    const at = text.indexOf("{");
+    if (at < 0) return undefined;
+    try {
+      return JSON.parse(text.slice(at)) as unknown;
+    } catch {
+      return undefined;
+    }
+  }
+}
+
+function providerFailureSignals(value: unknown, into: string[] = []): string[] {
+  if (Array.isArray(value)) {
+    for (const item of value) providerFailureSignals(item, into);
+    return into;
+  }
+  const row = providerFailureRecord(value);
+  if (!row) return into;
+  for (const [key, item] of Object.entries(row)) {
+    const normalizedKey = key.toLowerCase();
+    if (typeof item === "string" && ["code", "type", "error_type", "reason", "limit_source"].includes(normalizedKey))
+      into.push(item.toLowerCase());
+    else if (typeof item === "number" && normalizedKey === "code") into.push(String(item));
+    providerFailureSignals(item, into);
+  }
+  return into;
+}
+
+function providerFailureStatus(input: ProviderFailureAnswer, text: string): number | undefined {
+  if (input.status !== undefined) return input.status;
+  const match = /(?:^|\b(?:http|status(?: code)?|error|api error)[^0-9]{0,8})([1-5]\d\d)\b/i.exec(text);
+  return match ? Number(match[1]) : undefined;
+}
+
+function providerFailureText(input: ProviderFailureAnswer): string {
+  const error = input.error;
+  if (error instanceof Error) return error.message;
+  if (typeof error === "string") return error;
+  if (typeof input.body === "string") return input.body;
+  try {
+    return input.body === undefined ? "" : JSON.stringify(input.body);
+  } catch {
+    return "";
+  }
+}
+
+function quotedWord(text: string, word: string): boolean {
+  return [`'${word}'`, `"${word}"`, `\`${word}\``].some((candidate) => text.includes(candidate));
+}
+
+function toolSchemaKeywords(value: unknown, into = new Set<string>()): Set<string> {
+  if (Array.isArray(value)) {
+    for (const item of value) toolSchemaKeywords(item, into);
+    return into;
+  }
+  const schema = providerFailureRecord(value);
+  if (!schema) return into;
+  for (const [keyword, item] of Object.entries(schema)) {
+    into.add(keyword);
+    if ((keyword === "properties" || keyword === "$defs" || keyword === "definitions") && providerFailureRecord(item)) {
+      for (const child of Object.values(providerFailureRecord(item)!)) toolSchemaKeywords(child, into);
+    } else {
+      toolSchemaKeywords(item, into);
+    }
+  }
+  return into;
+}
+
+/** The provider adapter's evidence for one repairable schema rejection. The
+ * response must prove schema validation failed and name exactly one offered
+ * tool plus exactly one keyword present in that tool's sent schema. */
+export function providerSchemaRejectionOf(
+  error: unknown,
+  tools: readonly ToolDef[] | undefined,
+): ProviderSchemaRejection | undefined {
+  if (!tools || tools.length === 0) return undefined;
+  const text = providerFailureText({ error });
+  const parsed = providerFailureBody(providerFailureRecord(error) ?? text);
+  const prose = providerFailureProse(parsed ?? text);
+  if (
+    !/(?:invalid|unsupported|refused|rejected)[^.!?]{0,80}(?:json )?schema|(?:json )?schema[^.!?]{0,80}(?:invalid|unsupported|not (?:permitted|supported))/i.test(
+      prose,
+    )
+  )
+    return undefined;
+  const namedTools = tools.filter((tool) => quotedWord(prose, tool.name));
+  if (namedTools.length !== 1) return undefined;
+  const [tool] = namedTools;
+  const namedKeywords = [...toolSchemaKeywords(tool.inputSchema)].filter((keyword) => quotedWord(prose, keyword));
+  if (namedKeywords.length !== 1) return undefined;
+  return { tool: tool.name, keyword: namedKeywords[0]! };
+}
+
+function providerFailureProse(value: unknown, into: string[] = []): string {
+  if (typeof value === "string") {
+    into.push(value);
+    return into.join(" ");
+  }
+  if (Array.isArray(value)) {
+    for (const item of value) providerFailureProse(item, into);
+    return into.join(" ");
+  }
+  const row = providerFailureRecord(value);
+  if (!row) return into.join(" ");
+  for (const [key, item] of Object.entries(row)) {
+    if (key.toLowerCase() !== "cause") providerFailureProse(item, into);
+  }
+  return into.join(" ");
+}
+
+function signalIncludes(signals: readonly string[], words: readonly string[]): boolean {
+  return signals.some((signal) => words.some((word) => signal === word || signal.includes(word)));
+}
+
+function isProviderFailureCause(value: unknown): value is ProviderFailureCause {
+  return typeof value === "string" && (PROVIDER_FAILURE_CAUSES as readonly string[]).includes(value);
+}
+
+function trustedProviderFailureEnvelope(
+  value: unknown,
+): { cause: ProviderFailureCause; schemaRejection?: ProviderSchemaRejection } | undefined {
+  if (Array.isArray(value)) {
+    for (const item of value) {
+      const envelope = trustedProviderFailureEnvelope(item);
+      if (envelope !== undefined) return envelope;
+    }
+    return undefined;
+  }
+  const row = providerFailureRecord(value);
+  if (!row) return undefined;
+  if (row.type === "provider_failure" && isProviderFailureCause(row.cause)) {
+    const schemaRejection = providerSchemaRejectionRecord(row.schemaRejection);
+    return { cause: row.cause, ...(schemaRejection !== undefined ? { schemaRejection } : {}) };
+  }
+  for (const item of Object.values(row)) {
+    const envelope = trustedProviderFailureEnvelope(item);
+    if (envelope !== undefined) return envelope;
+  }
+  return undefined;
+}
+
+/** Status plus structured body → one typed failure. Text is consulted only at
+ * this adapter boundary for transports that expose no structured error; no
+ * consumer owns a word list. Mandatory provider statuses and transport facts
+ * precede every untrusted body signal. Unknown answers fail closed as
+ * `permanent`. */
+export function classifyProviderFailure(input: ProviderFailureAnswer): ProviderFailure {
+  if (input.error instanceof ProviderFailure) return input.error;
+  const text = providerFailureText(input);
+  const parsed = providerFailureBody(input.body ?? providerFailureRecord(input.error) ?? text);
+  const signals = providerFailureSignals(parsed);
+  const trusted = input.trustedEnvelope === true ? trustedProviderFailureEnvelope(parsed) : undefined;
+  const status = providerFailureStatus(input, text);
+  // A parsed provider object contributes its structured signals and prose,
+  // but never its untrusted `cause` value. That preserves message-only
+  // adapters without re-reading `cause: rate-limited` through the regex.
+  const unstructuredText =
+    input.body !== undefined && (providerFailureRecord(parsed) !== undefined || Array.isArray(parsed))
+      ? providerFailureProse(parsed)
+      : text;
+  const transientTransport =
+    status === 408 ||
+    status === 425 ||
+    (input.error instanceof Error && (input.error.name === "AbortError" || input.error.name === "TimeoutError")) ||
+    (status !== undefined && status >= 500) ||
+    /stream ended before message_stop|stream ended without finish_reason|ended before completion/i.test(
+      unstructuredText,
+    ) ||
+    /^(?:(?:AbortError:\s*)?(?:This|The) operation was aborted|Request aborted)\.?$/i.test(unstructuredText.trim()) ||
+    /ECONNRESET|ETIMEDOUT|EPIPE|socket hang up|fetch failed|other side closed|network (?:error|failure)|(?:connection|stream) (?:reset|closed|terminated)|timed? ?out/i.test(
+      unstructuredText,
+    ) ||
+    /^terminated$/i.test(unstructuredText.trim()) ||
+    /\boverloaded\b/i.test(unstructuredText) ||
+    /<html[\s>][\s\S]{0,4000}\b(?:bad gateway|service unavailable|gateway timeout)\b/i.test(unstructuredText);
+  let cause: ProviderFailureCause;
+  if (trusted !== undefined) cause = trusted.cause;
+  else if (status === 402) cause = "credit-or-quota-exhausted";
+  else if (status === 429) cause = "rate-limited";
+  else if (transientTransport) cause = "transient";
+  else if (
+    signalIncludes(signals, [
+      "limit_source",
+      "insufficient_quota",
+      "quota_exceeded",
+      "credit_limit",
+      "billing_hard_limit",
+      "payment_required",
+    ]) ||
+    (providerFailureRecord(parsed)?.metadata !== undefined &&
+      providerFailureRecord(providerFailureRecord(parsed)?.metadata)?.limit_source !== undefined)
+  )
+    cause = "credit-or-quota-exhausted";
+  else if (
+    signalIncludes(signals, ["rate_limit", "too_many_requests"]) ||
+    /\brate[- ]limit(?:ed)?\b/i.test(unstructuredText)
+  )
+    cause = "rate-limited";
+  else if (signalIncludes(signals, ["provider_key_missing", "key_absent", "missing_api_key"])) cause = "key-absent";
+  else if (
+    status === 401 ||
+    signalIncludes(signals, ["authentication_error", "invalid_api_key", "invalid_key", "unauthorized"])
+  )
+    cause = "key-invalid";
+  else if (signalIncludes(signals, ["model_not_found", "unknown_model", "model_unknown"])) cause = "model-unknown";
+  else if (
+    status === 400 ||
+    status === 422 ||
+    signalIncludes(signals, ["invalid_request_error", "invalid_json_schema", "bad_request", "unprocessable_entity"])
+  )
+    cause = "request-rejected";
+  else cause = "permanent";
+  const operatorUrl = /https?:\/\/[^\s"'<>]+/.exec(text)?.[0];
+  return new ProviderFailure(cause, {
+    ...(status !== undefined ? { status } : {}),
+    ...(input.provider !== undefined ? { provider: input.provider } : {}),
+    ...(input.model !== undefined ? { model: input.model } : {}),
+    ...(operatorUrl !== undefined ? { operatorUrl } : {}),
+    ...(trusted?.schemaRejection !== undefined ? { schemaRejection: trusted.schemaRejection } : {}),
+  });
+}
+
+function typedProviderFailureOf(error: unknown, seen = new Set<object>()): ProviderFailure | undefined {
+  if (error instanceof ProviderFailure) return error;
+  const row = providerFailureRecord(error);
+  if (!row || seen.has(row)) return undefined;
+  seen.add(row);
+  if (row.name === "ProviderFailure" && isProviderFailureCause(row.cause)) {
+    return new ProviderFailure(row.cause, {
+      ...(typeof row.status === "number" ? { status: row.status } : {}),
+      ...(typeof row.provider === "string" ? { provider: row.provider } : {}),
+      ...(typeof row.model === "string" ? { model: row.model } : {}),
+      ...(typeof row.operatorUrl === "string" ? { operatorUrl: row.operatorUrl } : {}),
+      ...(typeof row.keyVariable === "string" ? { keyVariable: row.keyVariable } : {}),
+      ...(providerSchemaRejectionRecord(row.schemaRejection) !== undefined
+        ? { schemaRejection: providerSchemaRejectionRecord(row.schemaRejection)! }
+        : {}),
+    });
+  }
+  // StructuredAskError and other boundary wrappers preserve the original
+  // throw as `cause`. Follow typed causes through those wrappers before the
+  // outer error's copied message can be classified without its status/body.
+  return typedProviderFailureOf(row.cause, seen);
+}
+
+export function providerFailureOf(error: unknown): ProviderFailure {
+  return typedProviderFailureOf(error) ?? classifyProviderFailure({ error });
+}
+
+/** Causes that make the provider unavailable rather than ending one call. */
+export function providerFailureParks(cause: ProviderFailureCause): boolean {
+  return cause === "transient" || cause === "rate-limited" || cause === "credit-or-quota-exhausted";
+}
+
 /** The three wire shapes a provider block may declare (record 0052):
  *  Anthropic's Messages API, OpenAI's Chat Completions and OpenAI's Responses
  *  API. Each is a proxy route of its own (`PROXY_PATHS`): an `openai-responses`

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

@@ -47,7 +47,7 @@ const CAUSE_OF = {
   repo_not_onboarded: "request",
   repo_access: "policy",
   pr_head_unknown: "system",
-  branch_moved: "system",
+  workspace_head_mismatch: "system",
   coordinator_thread_live: "system",
   live_agent_allowlist: "policy",
   follow_up_refused: "request",
@@ -103,6 +103,7 @@ const CAUSE_OF = {
   plan_runner_state_unread: "system",
   plan_units_merged: "request",
   plan_history_unavailable: "system",
+  decision_record_store_unavailable: "system",
   plan_runner_conflict: "system",
   plan_instance_orphaned: "system",
   plan_start_failed: "system",

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

@@ -4,6 +4,7 @@
 import type { DescriptionIssue, PrDescription, RecordedJson, RenderedPointer } from "./prDescriptionTypes.js";
 import type { HarnessScope } from "./harness/scope.js";
 import type { ModelCard } from "./modelCard.js";
+import type { ProviderFailureCause } from "./provider.js";
 
 /** The `pr_description` review artifact minus the event envelope
  *  (docs/reference/specs/reading-diff.md item 7). */
@@ -752,6 +753,10 @@ export type RunEvent =
       agentSource?: AgentSource;
       /** Absent on a command run, which resolves no model. */
       model?: string;
+      /** Decision-record reservation carried in a coding child's brief. */
+      record?: string;
+      /** Stable direct-task key used to recover that reservation on a re-issue. */
+      recordTaskKey?: string;
       /** 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
@@ -1118,6 +1123,9 @@ export type RunEvent =
       request?: string;
       refusalCause?: string;
       refusalText?: string;
+      /** The typed cause when the operator model call failed at the provider
+       * boundary. Its refusal text is always the cause-owned renderer. */
+      providerFailure?: ProviderFailureCause;
       attempts?: ReadonlyArray<{ outcome: "accepted" | "violation"; violation?: string }>;
       intake?: { verdict: string; reason: string };
       latencyMs?: number;

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, IntakeReceipt, IntakeWriteResult, LivePhase } from "./types.js";
+import type { ClaimResult, FenceResult, IntakeReceipt, IntakeWriteResult, LivePhase, StepRecord } 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
@@ -80,6 +80,15 @@ export function selectReclaim<T extends { leaseUntil: number; phase: LivePhase;
   return rows.filter((r) => r.ownerGen !== gen && (r.phase === "handoff" || r.leaseUntil <= now));
 }
 
+/** Which inbox rows a reclaim hands the next generation (run-history item 40):
+ *  every row past the last record's cursor, and the rows at or below it the
+ *  record names deferred — handed to the run, never read by its model. */
+export function unreadInbox(lastStep: Pick<StepRecord, "inboxConsumedSeq" | "inboxDeferredSeqs"> | null) {
+  const consumed = lastStep?.inboxConsumedSeq ?? 0;
+  const deferred = new Set(lastStep?.inboxDeferredSeqs ?? []);
+  return (item: { seq: number }): boolean => item.seq > consumed || deferred.has(item.seq);
+}
+
 /** The compare-and-swap table for a run's phase. `attaching → live` (the
  *  prompt landed) or `→ finishing` (the dispatch failed before it — never
  *  handoff: an attaching run has nothing to resume from, so the drain waits

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

@@ -4,7 +4,7 @@
 // bot and by `deploy/cloudflare-memory/worker.ts` alike, the way runRecord.ts is.
 
 import type { ChatMessage } from "../chatMessage.js";
-import type { ToolDef } from "../provider.js";
+import { PROVIDER_FAILURE_CAUSES, type ProviderFailureCause, type ToolDef } from "../provider.js";
 import type { ChannelVisibility } from "../authz/types.js";
 import type { RunProfile } from "../../config/profile.js";
 import type { RunEvent } from "../runEvents.js";
@@ -59,6 +59,10 @@ export interface LiveRunMeta {
   /** 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;
+  /** Decision-record reservation assigned before the attach, so a restart of
+   * the admitted task keeps the same brief and process environment. */
+  record?: string;
+  recordTaskKey?: string;
   /** A ship pipeline's parent (record 0060): claimed under the host key
    *  (`hostKey.ts`) while `threadKey` here names the thread itself, so every
    *  record, notice and rebuilt handle files by the metadata's thread and the
@@ -175,6 +179,9 @@ export interface StepRecord {
   inFlight: InFlightCall[];
   /** The inbox `seq` the run has consumed up to (0 = none). */
   inboxConsumedSeq: number;
+  /** Seqs at or below `inboxConsumedSeq` the run has not consumed yet: a
+   *  reclaim offers them again with every row past the cursor. */
+  inboxDeferredSeqs?: number[];
   remainingMs: number;
   turn: number;
   iteration: number;
@@ -296,6 +303,8 @@ export interface IntakeReceipt {
   verdict: "addressed" | "silent";
   reason: string;
   source: "model" | "mode" | "question" | "error" | "timeout";
+  /** Present only when `source: error` is a failed provider call. */
+  providerFailure?: ProviderFailureCause;
   /** The structured seam's attempts (docs/decisions/0067): what each answer
    *  violated, or that it was accepted; absent when no model was asked. */
   attempts?: ReadonlyArray<{ outcome: "accepted" | "violation"; violation?: string }>;
@@ -336,6 +345,9 @@ export function isIntakeReceipt(v: unknown): v is IntakeReceipt {
       r.source === "question" ||
       r.source === "error" ||
       r.source === "timeout") &&
+    (r.providerFailure === undefined ||
+      (typeof r.providerFailure === "string" &&
+        (PROVIDER_FAILURE_CAUSES as readonly string[]).includes(r.providerFailure))) &&
     (r.mode === "mention" || r.mode === "classify") &&
     typeof r.model === "string" &&
     typeof r.gen === "number" &&

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

@@ -1,6 +1,7 @@
 import type { ChannelVisibility, Predicate } from "./authz/types.js";
 import type { BoundaryScope, Identity, MachineClass, RunProfile } from "../config/profile.js";
 import type { RunEvent } from "./runEvents.js";
+import type { ProviderFailureCause } from "./provider.js";
 import { isHeadMaterial, isSpanRecord } from "./runEvents.js";
 import { isRunUsage, type RunUsage } from "./runUsage.js";
 import type { PushedBranch } from "../execution/residentRebind.js";
@@ -153,6 +154,16 @@ export interface RunRecord {
   /** The thread that started the run (`IncomingMessage.sourceUrl`), for the
    *  index's hover link. Optional as above. */
   sourceUrl?: string;
+  /** The decision-record number the runner reserved and passed in this coding
+   * run's brief. Absent when the task writes no record. */
+  record?: string;
+  /** Stable text-free key for a direct task's re-issue. */
+  recordTaskKey?: string;
+  /** The final workspace head the run loop independently observed (7 to 40
+   *  lowercase hex), after every tail step and mechanical salvage. Present
+   *  only when the workspace had a readable Git HEAD; absent on older records
+   *  and runs without a Git workspace. */
+  headSha?: string;
   /** The typed handoff a coding child submitted (docs/reference/specs/agent-ship.md
    *  item 14): its deviations from the plan unit, its follow-ups and the
    *  criteria it could not prove — redacted like every stored string. Present
@@ -327,6 +338,20 @@ export function instanceIdOfEvents(events: readonly RunEvent[]): string | undefi
   return id;
 }
 
+/** The reservation carried by the last run_meta that names one. */
+export function decisionRecordOfEvents(
+  events: readonly RunEvent[],
+): { record: string; recordTaskKey?: string } | undefined {
+  let reservation: { record: string; recordTaskKey?: string } | undefined;
+  for (const event of events)
+    if (event.type === "run_meta" && event.record !== undefined)
+      reservation = {
+        record: event.record,
+        ...(event.recordTaskKey !== undefined ? { recordTaskKey: event.recordTaskKey } : {}),
+      };
+  return reservation;
+}
+
 /** The pull request a run's events say it opened or edited — the last
  *  `pr_opened` wins, as an edit after an open names the same PR — or nothing. */
 export function prOfEvents(events: readonly RunEvent[]): RunPullRequest | undefined {
@@ -453,6 +478,7 @@ export interface RunOperatorDecision {
   request?: string;
   refusalCause?: string;
   refusalText?: string;
+  providerFailure?: ProviderFailureCause;
   /** The structured seam's attempts (record 0067): what each answer violated,
    *  or that it was accepted. */
   attempts?: { outcome: "accepted" | "violation"; violation?: string }[];
@@ -488,6 +514,7 @@ export function operatorOfEvents(events: readonly RunEvent[]): RunOperatorDecisi
     ...(e.request !== undefined ? { request: e.request } : {}),
     ...(e.refusalCause !== undefined ? { refusalCause: e.refusalCause } : {}),
     ...(e.refusalText !== undefined ? { refusalText: e.refusalText } : {}),
+    ...(e.providerFailure !== undefined ? { providerFailure: e.providerFailure } : {}),
     ...(e.attempts
       ? {
           attempts: e.attempts.map((a) => ({
@@ -1011,6 +1038,10 @@ export function isRunRecord(v: unknown): v is RunRecord {
   )
     return false;
   if (!isOptionalString(r.activity) || !isOptionalString(r.sourceUrl) || !isOptionalString(r.userName)) return false;
+  if (r.record !== undefined && (typeof r.record !== "string" || !/^\d{4}$/.test(r.record))) return false;
+  if (r.recordTaskKey !== undefined && (typeof r.recordTaskKey !== "string" || !/^[0-9a-f]{16}$/.test(r.recordTaskKey)))
+    return false;
+  if (r.headSha !== undefined && (typeof r.headSha !== "string" || !REVIEW_HEAD_PATTERN.test(r.headSha))) return false;
   // The handoff is checked for shape, not bounds (docs/reference/specs/agent-ship.md
   // item 14): redaction may lengthen a stored string past the tool's limit.
   if (r.handoff !== undefined && !isHandoffShape(r.handoff)) return false;

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

@@ -65,6 +65,8 @@ export interface Guard {
 
 export interface ChildContract {
   unit: ContractUnit;
+  /** The decision-record number reserved for this unit at admission. */
+  record?: string;
   specRows: ContractSpecRow[];
   /** Absent when the repository has neither rules file. */
   agentRules: AgentRules | undefined;