@coreplane/switchboard 1.250.0 → 1.252.0

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
@@ -32,11 +32,23 @@ export type LevelMap = Record<Effort, LevelWord | "refused"> | "unknown";
 export type InputSupport = boolean | "unknown";
 export type CacheRule = "automatic" | "markers" | "none" | "unknown";
 
+/** One long-context tier of a card's rate (pi's rule, `calculateCost`): when
+ *  the request's input side (input + cache reads + cache writes) exceeds
+ *  `inputTokensAbove`, the WHOLE request re-rates at the tier. */
+export interface CardPriceTier {
+  inputTokensAbove: number;
+  input: number;
+  output: number;
+  cacheRead: number;
+  cacheWrite: number;
+}
+
 export interface CardPrice {
   input: number;
   output: number;
   cacheRead: number;
   cacheWrite: number;
+  tiers?: readonly CardPriceTier[];
 }
 
 export interface ModelCard {
@@ -123,14 +135,30 @@ function levelMapOf(map: Record<string, string | null> | undefined, reasoning: b
   return out;
 }
 
-function priceOf(
-  raw: { input?: number; output?: number; cacheRead?: number; cacheWrite?: number } | undefined,
-): CardPrice | undefined {
+type RawPrice = {
+  input?: number;
+  output?: number;
+  cacheRead?: number;
+  cacheWrite?: number;
+  tiers?: Array<{ inputTokensAbove?: number } & Omit<RawPrice, "tiers">>;
+};
+
+function priceOf(raw: RawPrice | undefined): CardPrice | undefined {
   if (!raw) return undefined;
   const { input, output, cacheRead, cacheWrite } = raw;
   if (input === undefined || output === undefined || cacheRead === undefined || cacheWrite === undefined)
     return undefined;
-  return { input, output, cacheRead, cacheWrite };
+  // A tier missing a field cannot re-rate the whole request; it is dropped,
+  // never guessed at the base rate.
+  const tiers = (raw.tiers ?? []).filter(
+    (t): t is CardPriceTier =>
+      t.inputTokensAbove !== undefined &&
+      t.input !== undefined &&
+      t.output !== undefined &&
+      t.cacheRead !== undefined &&
+      t.cacheWrite !== undefined,
+  );
+  return { input, output, cacheRead, cacheWrite, ...(tiers.length > 0 ? { tiers } : {}) };
 }
 
 /**
@@ -335,13 +363,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/modelPricing.ts

@@ -1,4 +1,6 @@
-import { parseModelRef } from "./provider.js";
+import { parseModelRef, type TokenUsage } from "./provider.js";
+import type { CardPrice } from "./modelCard.js";
+import type { ReportedCost } from "./modelProxy/usage.js";
 import type { ModelUsage, RunUsage } from "./runUsage.js";
 
 // The price of a model's tokens (docs/reference/specs/costs.md): one table
@@ -148,6 +150,105 @@ export function modelPriceOf(ref: string, prices: ModelPriceTable = NO_PRICES):
   return { input: list.input, output: list.output, cacheRead: list.cacheRead, cacheWrite: list.cacheWrite5m };
 }
 
+// ---- one turn, priced at the proxy (model-proxy.md item 6) -----------------------
+
+/** Which layer priced the turn: the provider's own reported cost, the
+ *  operator's table (`costs.prices` or a block's `models.<id>.price`), the
+ *  registry card (the Anthropic family list folds into this layer), or none —
+ *  an unpriced turn is never $0. */
+export type PriceSource = "provider" | "operator" | "registry" | "none";
+
+/** The meter row's dollars: `usd` when a layer priced the turn, `feeUsd` on a
+ *  BYOK turn (the aggregator's fee — inside `usd` when the vendor's charge was
+ *  reported beside it, otherwise beside the layer that priced the tokens),
+ *  and the layer. */
+export interface TurnPrice {
+  usd?: number;
+  feeUsd?: number;
+  priceSource: PriceSource;
+}
+
+/** What `priceTurn` reads of the run's model card: the ref the spans name,
+ *  the card's rate when a layer named one, and which layer did
+ *  (`ModelCard.provenance.price`). */
+export interface TurnPriceCard {
+  ref: string;
+  price?: CardPrice;
+  pricedBy?: "operator" | "registry" | "wire";
+}
+
+const turnTokensUsd = (u: TokenUsage, p: { input: number; output: number; cacheRead: number; cacheWrite: number }) =>
+  (u.inputTokens * p.input +
+    u.outputTokens * p.output +
+    (u.cacheReadTokens ?? 0) * p.cacheRead +
+    (u.cacheWriteTokens ?? 0) * p.cacheWrite) /
+  1_000_000;
+
+/** A card rate over one turn's counts, tiers by pi's rule (`calculateCost`):
+ *  the input side is input + cache reads + cache writes, and the WHOLE request
+ *  re-rates at the highest tier whose threshold it exceeds. */
+export function cardPriceUsd(usage: TokenUsage, price: CardPrice): number {
+  const inputSide = usage.inputTokens + (usage.cacheReadTokens ?? 0) + (usage.cacheWriteTokens ?? 0);
+  let rates: { input: number; output: number; cacheRead: number; cacheWrite: number } = price;
+  let matched = -1;
+  for (const tier of price.tiers ?? []) {
+    if (inputSide > tier.inputTokensAbove && tier.inputTokensAbove > matched) {
+      rates = tier;
+      matched = tier.inputTokensAbove;
+    }
+  }
+  return turnTokensUsd(usage, rates);
+}
+
+/**
+ * One turn's price, by record 0052's precedence: a provider-reported cost is
+ * stored as reported (`provider`; on BYOK the fee and the vendor's upstream
+ * charge sum into `usd` with `feeUsd` beside), else the operator's layer
+ * (`costs.prices` for the exact ref, or the card's operator-named rate), else
+ * the registry layer (the card's rate with its tiers, or the Anthropic family
+ * list — costs.md item 4b's fallback, folded here), else `none` — a turn no
+ * layer prices, and a stream broken before its usage arrived, stays unpriced.
+ */
+export function priceTurn(
+  card: TurnPriceCard,
+  reported: ReportedCost | undefined,
+  usage: TokenUsage | undefined,
+  prices: ModelPriceTable = NO_PRICES,
+): TurnPrice {
+  if (reported) {
+    if (!reported.byok) return { usd: reported.cost, priceSource: "provider" };
+    if (reported.upstreamCost !== undefined) {
+      return { usd: reported.cost + reported.upstreamCost, priceSource: "provider", feeUsd: reported.cost };
+    }
+    // A BYOK chunk without the vendor's charge: the fee is not the turn's
+    // dollars, so it rides beside whatever layer below prices the tokens —
+    // never as an authoritative figure that understates the turn.
+    return { ...priceTurn(card, undefined, usage, prices), feeUsd: reported.cost };
+  }
+  if (!usage) return { priceSource: "none" };
+  const operator = prices[card.ref];
+  if (operator) return { usd: turnTokensUsd(usage, operator), priceSource: "operator" };
+  if (card.price) {
+    return {
+      usd: cardPriceUsd(usage, card.price),
+      priceSource: card.pricedBy === "operator" ? "operator" : "registry",
+    };
+  }
+  const list = anthropicPriceOf(modelIdOf(card.ref));
+  if (list) {
+    return {
+      usd: turnTokensUsd(usage, {
+        input: list.input,
+        output: list.output,
+        cacheRead: list.cacheRead,
+        cacheWrite: list.cacheWrite5m,
+      }),
+      priceSource: "registry",
+    };
+  }
+  return { priceSource: "none" };
+}
+
 /** What a model's counted tokens cost at a price, USD. */
 export function modelUsageUsd(m: ModelUsage, p: ModelPrice): number {
   return (
@@ -211,6 +312,15 @@ export function llmUsdOfUsage(
   let unpricedTokens = 0;
   const byModel: Record<string, PricedModelUsage> = {};
   for (const [ref, m] of Object.entries(usage.byModel)) {
+    // A model whose spans priced their own turns (model-proxy item 6) keeps
+    // the recorded figure — a provider-reported cost beats any table — and
+    // null (a turn without a figure) reads as unpriced, never re-priced here.
+    if (m.usd !== undefined) {
+      if (m.usd === null) unpricedTokens += m.inputTokens + m.outputTokens + m.cacheReadTokens + m.cacheWriteTokens;
+      else usd += m.usd;
+      byModel[ref] = { ...m, usd: m.usd };
+      continue;
+    }
     const price = modelPriceOf(ref, prices);
     const priced = price ? modelUsageUsd(m, price) : undefined;
     if (priced === undefined) unpricedTokens += m.inputTokens + m.outputTokens + m.cacheReadTokens + m.cacheWriteTokens;

package/dist/assets/src/core/modelProxy/usage.ts

@@ -0,0 +1,88 @@
+// A provider's usage object as the proxy's meter reads it
+// (docs/reference/specs/model-proxy.md item 6): the three wire shapes the proxy
+// forwards — Anthropic's `message.usage`, the Chat Completions `usage` and the
+// Responses API's `usage` — each
+// normalized to the one `TokenUsage` every `model.turn` span carries. Undefined
+// unless both core counts are numbers: a malformed or absent usage never fails
+// a completion, it only leaves the turn unmetered. The first two readers were the
+// native adapters' until record 0032's series deleted the adapters; the proxy
+// is their one reader now.
+
+import type { TokenUsage } from "../provider.js";
+
+/** Anthropic `message.usage` → TokenUsage. */
+export function usageFromAnthropic(u: unknown): TokenUsage | undefined {
+  if (typeof u !== "object" || u === null) return undefined;
+  const o = u as Record<string, unknown>;
+  if (typeof o.input_tokens !== "number" || typeof o.output_tokens !== "number") return undefined;
+  const usage: TokenUsage = { inputTokens: o.input_tokens, outputTokens: o.output_tokens };
+  if (typeof o.cache_read_input_tokens === "number") usage.cacheReadTokens = o.cache_read_input_tokens;
+  if (typeof o.cache_creation_input_tokens === "number") usage.cacheWriteTokens = o.cache_creation_input_tokens;
+  return usage;
+}
+
+/** OpenAI-style `usage` → TokenUsage. `prompt_tokens_details.cached_tokens` is
+ *  the cache-read count where the server reports one. */
+export function usageFromOpenAI(u: unknown): TokenUsage | undefined {
+  if (typeof u !== "object" || u === null) return undefined;
+  const o = u as Record<string, unknown>;
+  if (typeof o.prompt_tokens !== "number" || typeof o.completion_tokens !== "number") return undefined;
+  const usage: TokenUsage = { inputTokens: o.prompt_tokens, outputTokens: o.completion_tokens };
+  const details = o.prompt_tokens_details;
+  if (typeof details === "object" && details !== null) {
+    const cached = (details as Record<string, unknown>).cached_tokens;
+    if (typeof cached === "number") usage.cacheReadTokens = cached;
+  }
+  return usage;
+}
+
+/** A provider-reported cost beside the counters (model-proxy.md item 6): the
+ *  OpenRouter final chunk's `usage.cost` in USD — on a BYOK turn (`is_byok`)
+ *  the aggregator's fee alone, with what the vendor billed the operator's own
+ *  key in `cost_details.upstream_inference_cost`. Read off the same usage
+ *  object the counters come from; a usage without a finite `cost` reports
+ *  none (Anthropic's wire never carries one). */
+export interface ReportedCost {
+  /** The figure as reported, stored as reported (record 0052). */
+  cost: number;
+  /** OpenRouter's `is_byok`: the turn billed the operator's own vendor key. */
+  byok?: boolean;
+  /** `cost_details.upstream_inference_cost`: the vendor's own charge on a BYOK turn. */
+  upstreamCost?: number;
+}
+
+/** The cost fields of one wire `usage` object, or undefined when it carries none. */
+export function reportedCostOf(u: unknown): ReportedCost | undefined {
+  if (typeof u !== "object" || u === null) return undefined;
+  const o = u as Record<string, unknown>;
+  if (typeof o.cost !== "number" || !Number.isFinite(o.cost)) return undefined;
+  const details = o.cost_details;
+  const upstream =
+    typeof details === "object" && details !== null
+      ? (details as Record<string, unknown>).upstream_inference_cost
+      : undefined;
+  return {
+    cost: o.cost,
+    ...(o.is_byok === true ? { byok: true } : {}),
+    ...(typeof upstream === "number" && Number.isFinite(upstream) ? { upstreamCost: upstream } : {}),
+  };
+}
+
+/** The Responses API's `usage` → TokenUsage. `input_tokens_details.cached_tokens`
+ *  is the cache-read count and `input_tokens_details.cache_write_tokens` the
+ *  cache-write count where a server reports one (OpenAI itself never does; a
+ *  gateway on the wire may). `output_tokens_details.reasoning_tokens` rides
+ *  inside `output_tokens` — the shape is read, never a fifth counter. */
+export function usageFromResponses(u: unknown): TokenUsage | undefined {
+  if (typeof u !== "object" || u === null) return undefined;
+  const o = u as Record<string, unknown>;
+  if (typeof o.input_tokens !== "number" || typeof o.output_tokens !== "number") return undefined;
+  const usage: TokenUsage = { inputTokens: o.input_tokens, outputTokens: o.output_tokens };
+  const details = o.input_tokens_details;
+  if (typeof details === "object" && details !== null) {
+    const { cached_tokens, cache_write_tokens } = details as Record<string, unknown>;
+    if (typeof cached_tokens === "number") usage.cacheReadTokens = cached_tokens;
+    if (typeof cache_write_tokens === "number") usage.cacheWriteTokens = cache_write_tokens;
+  }
+  return usage;
+}

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

@@ -23,7 +23,21 @@ export interface RegistryCard {
    *  not named (the card's reader applies pi's rule). */
   thinkingLevelMap?: Record<string, string | null>;
   input?: string[];
-  cost?: { input?: number; output?: number; cacheRead?: number; cacheWrite?: number };
+  cost?: {
+    input?: number;
+    output?: number;
+    cacheRead?: number;
+    cacheWrite?: number;
+    /** pi's long-context tiers: the whole request re-rates at the highest tier
+     *  whose threshold the input side (input + cache reads + cache writes) exceeds. */
+    tiers?: Array<{
+      inputTokensAbove?: number;
+      input?: number;
+      output?: number;
+      cacheRead?: number;
+      cacheWrite?: number;
+    }>;
+  };
   contextWindow?: number;
   maxTokens?: number;
   compat?: Record<string, unknown>;

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

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

@@ -56,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",
@@ -85,6 +87,7 @@ const CAUSE_OF = {
   ship_preflight_head_unknown: "system",
   ship_preflight_closed_resume: "request",
   ship_preflight_no_task: "request",
+  ship_preflight_base_missing: "request",
   // the plan hand-off's fifteen sentences (two share `plan_history_unavailable`)
   plan_base_unknown: "request",
   plan_routed_seed: "request",
@@ -100,12 +103,9 @@ const CAUSE_OF = {
   plan_runner_conflict: "system",
   plan_instance_orphaned: "system",
   plan_start_failed: "system",
-  // the directive and resolve parsers' thrown errors (A6 of the inventory)
-  directive_agent: "request",
-  directive_effort: "request",
-  directive_budget: "request",
-  directive_severity: "request",
-  directive_renewals: "request",
+  // the resolve parser's thrown errors (A6 of the inventory); the directive
+  // parser no longer refuses — a token whose value is outside its vocabulary
+  // is text (the interim grammar, src/directives.ts)
   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/reviewVerdict.ts

@@ -108,6 +108,10 @@ export interface Finding {
   line?: number;
   /** One line naming the issue; the full explanation lives in the prose. */
   title: string;
+  /** Machine provenance: true only on a check finding the ship round's checks
+   *  step itself appended (ship/coordinator.ts `checkFinding`) — never set from
+   *  a reviewer's input, whatever id the reviewer chose. */
+  check?: true;
 }
 
 export interface ReviewVerdict {

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

@@ -397,6 +397,10 @@ export type ShipRoundOutcome =
   | "approve"
   | "request_changes"
   | "no_verdict"
+  /** The round's checks step read a failed check at the reviewed head (record
+   *  0055): the failures become check findings and the findings step runs as
+   *  for any changes-requested round. */
+  | "checks_failed"
   | "aborted"
   | "stopped"
   /** The coding round ended at its lease with the unit unfinished and the row
@@ -536,6 +540,11 @@ export type RunEvent =
       callId?: string;
       spanId?: string;
       logIndex?: number;
+      /** The bound the call itself declared, in ms (a bash `timeout`, clamped
+       *  by nothing here — pi runs an unbounded call until the loop's end).
+       *  The stall signal (docs/reference/specs/live-view.md item 32) marks a
+       *  call past it; absent when the call declared none. */
+      boundMs?: number;
       seq?: number;
       at?: number;
     }
@@ -671,8 +680,12 @@ export type RunEvent =
    *  and — for a repo run — the repo, ref, PR number and PR head as resolved
    *  BEFORE the first model turn (`RepoContext`). Published by the dispatcher
    *  right after `input`, once per run, so the run page can head its Request
-   *  block with linked `owner/repo · ref · #PR · sha`. Additive: every
-   *  consumer that only knows the other types keeps working. */
+   *  block with linked `owner/repo · ref · #PR · sha`. A HOSTED ship parent
+   *  (record 0060) carries a second one at the hand-off naming its runner
+   *  instance (`instanceId`): `run_meta` may repeat on such a run, and every
+   *  reader of a run's instance id resolves it from the LAST `run_meta`
+   *  carrying one. Additive: every consumer that only knows the other types
+   *  keeps working. */
   | {
       type: "run_meta";
       agent: string;
@@ -865,6 +878,23 @@ export type RunEvent =
    *  `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 }
+  /** A coordinator child interrupted under a deploy roll (docs/reference/specs/run-history.md
+   *  item 47a): the run closes `interrupted` for a restart from its request —
+   *  a workspace lost across a bot roll, the resident's container replaced
+   *  with the relaunch refused — and the record says so as a typed fact
+   *  beside the `resumed`/`sandbox_restarted` notes, `reason` the refusal or
+   *  note in one line. Published straight to the registry by the reattach
+   *  path and the run loop's interruption; the parent's wait settles on its
+   *  Workflow twin (`child-interrupted-<runId>`) beside `run-finished-<runId>`
+   *  and confirms by `read-record`. Additive: unknown → ignored. */
+  | { type: "child_interrupted"; parentInstanceId: string; reason: string; seq?: number; at?: number }
+  /** A coordinator child resumed across a deploy roll (run-history item 47a):
+   *  the same run re-attached its workspace and carries on under its record,
+   *  tag and budget. Published straight to the registry by the reattach path;
+   *  the Workflow twin (`child-resumed-<runId>`) tells the parent's wait to
+   *  keep waiting rather than walk out the chunk asking. Additive: unknown →
+   *  ignored. */
+  | { type: "child_resumed"; parentInstanceId: string; summary: 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,
@@ -905,6 +935,25 @@ export type RunEvent =
       seq?: number;
       at?: number;
     }
+  /** A hosted ship parent's unit fact (record 0060; docs/reference/specs/agent-ship.md
+   *  item 17): the runner's routes write it to the parent run through the
+   *  coordinator's `hostPublish` — `unit-start` publishes state `started` with
+   *  the unit's thread key and lead, `round` the round's outcome as the unit's
+   *  state, `unit-end` the ending's kind with its report — carrying the pull
+   *  request number when the unit's row knows one. The run page draws it as a
+   *  step whose detail is the report; the friction analyzer counts it as a
+   *  side fact, never activity. Additive: unknown → ignored. */
+  | {
+      type: "ship_unit";
+      unit: string;
+      state: string;
+      threadKey?: string;
+      lead?: string;
+      report?: string;
+      pr?: number;
+      seq?: number;
+      at?: number;
+    }
   /** The request router's decision (docs/reference/specs/routing-and-config.md
    *  item 21): the preset a plain message was routed to, the one-line reason
    *  the router gave (redacted, capped — the same text the card's `routed:`

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

@@ -413,8 +413,10 @@ export function analyzeRunFriction(events: readonly RunEvent[], opts: FrictionOp
     // call that already produced its own tool pair, and artifact beside the
     // attach_file call (or the dispatcher's staging) that moved the file;
     // review_artifact, pr_description, pr_opened, review_posted, the ship_round
-    // boundaries and the router's route are published by the dispatcher/pipeline
-    // outside the model loop entirely. Counting any of them would distort the story.
+    // boundaries, the hosted parent's ship_unit facts (record 0060 — written by
+    // the runner's routes, not the model) and the router's route are published
+    // by the dispatcher/pipeline outside the model loop entirely. Counting any
+    // of them would distort the story.
     if (
       ev.type === "skill_use" ||
       ev.type === "artifact" ||
@@ -423,8 +425,11 @@ export function analyzeRunFriction(events: readonly RunEvent[], opts: FrictionOp
       ev.type === "pr_opened" ||
       ev.type === "coordinator_tag" ||
       ev.type === "ship_handoff" ||
+      ev.type === "child_interrupted" ||
+      ev.type === "child_resumed" ||
       ev.type === "review_posted" ||
       ev.type === "ship_round" ||
+      ev.type === "ship_unit" ||
       ev.type === "route" ||
       ev.type === "refusal" ||
       ev.type === "reference" ||

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

@@ -59,6 +59,14 @@ 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;
+  /** 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
+   *  occupancy readers that key on the ledger's key column never see it. */
+  hosted?: true;
+  /** The run's index label (the registry sets it at create): on the row so a
+   *  hosted run listed from the ledger reads as its registry view does. */
+  label?: string;
   ref?: string;
   headSha?: string;
   pr?: number;
@@ -96,10 +104,10 @@ export interface LiveRunMeta {
   request?: Record<string, unknown>;
   /** The router's decision when it chose the run's preset (routing-and-config
    *  item 21) — the same fields the record's `route` event carries. On the row
-   *  so a resume repaints the card as it was (` · routed: <reason>`, the
-   *  parts, the override footer on the close) and a reclaim closing the run
-   *  knows it was routed without reading the events. Absent for a preset a
-   *  person, a scope or the default chose. */
+   *  so a resume repaints the card as it was (the `route reason:` note at
+   *  debug, the parts) and a record built from the row knows it was routed
+   *  without reading the events. Absent for a preset a person, a scope or the
+   *  default chose. */
   route?: {
     preset: string;
     reason: string;
@@ -113,6 +121,17 @@ export interface LiveRunMeta {
  *  the checklist, the pushed branch, the review head, the infra counters). */
 export type RunState = Record<string, unknown>;
 
+/** A hosted ship parent's hosting fact on the row's state (record 0060): the
+ *  runner instance the run hosts and the deadline past which a reclaim closes
+ *  the row `interrupted` instead of re-hosting it. Set by the ship branch once
+ *  the instance exists; read by the boot reclaim. */
+export interface HostingState {
+  instanceId: string;
+  /** Epoch ms: the hand-off time plus the instance's `caps.maxMinutes` plus
+   *  `HOSTED_DEADLINE_MARGIN_MINUTES`. */
+  until: number;
+}
+
 export interface LiveRunRow {
   runId: string;
   threadKey: string;

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

@@ -39,6 +39,12 @@ import {
 // reached `finish`.
 export type RunStatus = "completed" | "stopped_soft" | "stopped_hard" | "failed" | "interrupted";
 
+/** How every store-only reader renders a record still in its provisional
+ *  window (run-history.md item 27's third state): not `interrupted` (a real
+ *  terminal state) and not `running` (the store cannot know). One string for
+ *  the CLI's `runs list`/`runs get` and the web's index row and run page. */
+export const PROVISIONAL_LABEL = "unfinished — no finish recorded";
+
 const RUN_STATUSES: readonly RunStatus[] = ["completed", "stopped_soft", "stopped_hard", "failed", "interrupted"];
 
 /** Every `runs.*` id: checked before any store call. */
@@ -115,6 +121,13 @@ export interface RunRecord {
   stepCount?: number;
   schema?: number;
   status: RunStatus;
+  /** Present on a tombstone record still in its provisional window — the
+   *  start-of-run `interrupted` or the drain-deadline upgrade — before the
+   *  run's final write lands. Absent on every final (finished) record. A
+   *  store-only reader must render a provisional record as "unfinished — no
+   *  finish recorded" rather than as `interrupted`, because the run may still
+   *  be live in a registry the reader cannot see (run-history.md item 27). */
+  provisional?: true;
   /** The failure by name, when a `failed` run has one (item 57):
    *  `policy_refusal`, the provider refused the run's model call under its
    *  usage policy. Absent on a run that did not fail, on one that failed for
@@ -944,6 +957,9 @@ export function isRunRecord(v: unknown): v is RunRecord {
       return false;
   }
   if (!RUN_STATUSES.includes(r.status as RunStatus)) return false;
+  // A provisional tombstone carries `provisional: true`; any other value (false,
+  // a string, etc.) is a malformed record — only the presence of the flag matters.
+  if (r.provisional !== undefined && r.provisional !== true) return false;
   if (!isFiniteNumber(r.eventCount) || !isFiniteNumber(r.storedEventCount)) return false;
   if (typeof r.truncated !== "boolean") return false;
   if (!Array.isArray(r.events)) return false;