@coreplane/switchboard 1.260.6 → 1.261.1

package/dist/assets/deploy/cloudflare-memory/worker.ts

@@ -134,6 +134,8 @@ import {
   type IntakeWriteResult,
   type LivePhase,
   type LiveRunRow,
+  type LiveStateAssignRequest,
+  type LiveStateAssignResult,
   type ReclaimedRun,
   type RunState,
   type SessionHit,
@@ -154,6 +156,7 @@ import { isRunMetricsPoint, pointTurnsFinal, type RunMetricsPoint } from "../../
 import { AnalyticsEngineSink, NullSink, type RunMetricsSink } from "./runMetricsSink.ts";
 import { injectedBuildStamp } from "../../src/deploy/buildStamp.ts";
 import { systemClock } from "../../src/core/trace/clock.ts";
+import { assignRunLiveState } from "../../src/core/runLiveState.ts";
 import { createTracer } from "../../src/core/trace/tracer.ts";
 import { startAdoptedRoot, workerLogSink } from "../../src/core/trace/workerTrace.ts";
 
@@ -1539,6 +1542,9 @@ type LiveRow = {
 };
 
 function rowToLive(r: LiveRow): LiveRunRow {
+  const state = JSON.parse(r.state_json) as RunState;
+  const liveState = state.liveState as LiveRunRow["liveState"];
+  const liveStateSeq = state.liveStateSeq;
   return {
     runId: r.run_id,
     threadKey: r.thread_key,
@@ -1551,7 +1557,9 @@ function rowToLive(r: LiveRow): LiveRunRow {
     card: r.card_json ? (JSON.parse(r.card_json) as LiveRunRow["card"]) : null,
     system: r.system_text,
     tools: JSON.parse(r.tools_json) as LiveRunRow["tools"],
-    state: JSON.parse(r.state_json) as RunState,
+    state,
+    ...(liveState !== undefined ? { liveState } : {}),
+    ...(typeof liveStateSeq === "number" ? { liveStateSeq } : {}),
   };
 }
 
@@ -2955,7 +2963,7 @@ export class RunHistoryDO extends DurableObject<Env> {
             req.card ? JSON.stringify(req.card) : null,
             req.system,
             JSON.stringify(req.tools),
-            JSON.stringify(req.state ?? {}),
+            JSON.stringify({ ...existing!.state, ...(req.state ?? {}) }),
             req.runId,
           );
           this.registerSession(req);
@@ -3078,6 +3086,78 @@ export class RunHistoryDO extends DurableObject<Env> {
     return out;
   }
 
+  async assignLiveState(
+    runId: string,
+    gen: string,
+    assignment: LiveStateAssignRequest,
+  ): Promise<LiveStateAssignResult> {
+    let out: LiveStateAssignResult = { ok: false, reason: "unknown-run" };
+    this.ctx.storage.transactionSync(() => {
+      const row = this.liveRow(runId);
+      const fence = checkFence(row, gen);
+      if (!fence.ok) {
+        out = fence;
+        return;
+      }
+      if (!row) {
+        out = { ok: false, reason: "unknown-run" };
+        return;
+      }
+      const result = assignRunLiveState(
+        assignment.restart ? undefined : row.liveState,
+        row.liveStateSeq ?? 0,
+        assignment,
+      );
+      if (!result.ok) {
+        out = result;
+        return;
+      }
+      let liveStateSeq = row.liveStateSeq ?? 0;
+      const last = this.sql
+        .exec<{ m: number | null }>(`SELECT MAX(seq) AS m FROM run_events WHERE run_id = ?`, runId)
+        .one().m;
+      let lastEventSeq = last ?? 0;
+      for (const source of assignment.sourceEvents ?? []) {
+        if (source.seq <= lastEventSeq) {
+          out = { ok: false, reason: "stale-sequence" };
+          return;
+        }
+        lastEventSeq = source.seq;
+      }
+      const boundarySeq = result.event ? (assignment.eventSeq ?? lastEventSeq + 1) : undefined;
+      if (boundarySeq !== undefined && boundarySeq <= lastEventSeq) {
+        out = { ok: false, reason: "stale-sequence" };
+        return;
+      }
+      for (const source of assignment.sourceEvents ?? []) {
+        this.sql.exec(
+          `INSERT INTO run_events (run_id, seq, json) VALUES (?, ?, ?)`,
+          runId,
+          source.seq,
+          JSON.stringify(source),
+        );
+        liveStateSeq = source.seq;
+      }
+      if (result.event && boundarySeq !== undefined) {
+        liveStateSeq = boundarySeq;
+        this.sql.exec(
+          `INSERT INTO run_events (run_id, seq, json) VALUES (?, ?, ?)`,
+          runId,
+          liveStateSeq,
+          JSON.stringify({ ...result.event, seq: liveStateSeq }),
+        );
+      }
+      const state = { ...row.state, ...assignment.statePatch, liveState: result.liveState, liveStateSeq };
+      this.sql.exec(`UPDATE live_runs SET state_json = ? WHERE run_id = ?`, JSON.stringify(state), runId);
+      out = {
+        ...result,
+        ...(result.event ? { event: { ...result.event, seq: liveStateSeq } } : {}),
+        liveStateSeq,
+      };
+    });
+    return out;
+  }
+
   async setState(runId: string, gen: string, state: RunState): Promise<FenceResult> {
     let out: FenceResult = { ok: true };
     this.ctx.storage.transactionSync(() => {
@@ -5116,6 +5196,7 @@ const LEDGER_ROUTES = new Set([
   "/runs/claim",
   "/runs/heartbeat",
   "/runs/append",
+  "/runs/live-state",
   "/runs/step",
   "/runs/state",
   "/runs/inbox",
@@ -5954,6 +6035,13 @@ async function handleLedger(pathname: string, body: unknown, env: Env): Promise<
     console.log(`[runs/append] ${key.value} ${runId.value} <- ${events.length} event(s), ok=${r.ok}`);
     return fenced(r);
   }
+  if (pathname === "/runs/live-state") {
+    if (typeof b.assignment !== "object" || b.assignment === null)
+      return json({ error: "assignment must be an object" }, 400);
+    const assignment = b.assignment as unknown as LiveStateAssignRequest;
+    const r = await stub.assignLiveState(runId.value, g.value, assignment);
+    return r.ok ? json(r) : json(r, r.reason === "fenced" || r.reason === "unknown-run" ? 409 : 400);
+  }
   if (pathname === "/runs/step") {
     const record = parseStep(b.record);
     if (!record.ok) return json({ error: record.error }, 400);

package/dist/assets/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "switchboard",
-  "version": "1.260.6",
+  "version": "1.261.1",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "switchboard",
-      "version": "1.260.6",
+      "version": "1.261.1",
       "license": "Apache-2.0",
       "workspaces": [
         "web",
@@ -21060,7 +21060,7 @@
     },
     "packages/switchboard": {
       "name": "@coreplane/switchboard",
-      "version": "1.260.6",
+      "version": "1.261.1",
       "license": "Apache-2.0",
       "dependencies": {
         "@earendil-works/pi-ai": "0.85.1",

package/dist/assets/package.json

@@ -1,6 +1,6 @@
 {
   "name": "switchboard",
-  "version": "1.260.6",
+  "version": "1.261.1",
   "private": true,
   "description": "Mention it in Slack and an agent reviews the PR, ships the fix, or answers the question — on the model you choose, with its tools running where you decide.",
   "license": "Apache-2.0",

package/dist/assets/source.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.260.6",
-  "commit": "903ae2855833637fbcc0c0a22d54e7268be75965",
-  "builtAt": "2026-09-23T04:57:07.101Z"
+  "version": "1.261.1",
+  "commit": "3746a1c5fa2d30bebd66baec1fb3534a1f927e3a",
+  "builtAt": "2026-09-23T21:48:10.555Z"
 }

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

@@ -510,8 +510,9 @@ function prCheckReturn(step: string, a: BotAnswer): Extract<StepReturn, { type:
       },
       at,
     };
-  // A merged pull request is read whole or not at all: the merge commit and
-  // the time are what the unit's ending and its report carry.
+  // A merged pull request is read whole or not at all: its source head is
+  // retained for findings reconciliation, while the merge commit and time
+  // are what the unit's ending and report carry.
   if (
     ok === true &&
     state === "merged" &&
@@ -527,6 +528,7 @@ function prCheckReturn(step: string, a: BotAnswer): Extract<StepReturn, { type:
         state: "merged",
         prNumber,
         url,
+        ...(typeof headSha === "string" ? { headSha } : {}),
         sha,
         mergedAt,
         ...(typeof mergedBy === "string" ? { mergedBy } : {}),
@@ -923,9 +925,19 @@ async function tellStepThrew(
       : at.round.kind === "review" && /\/review\/(read|checks)\b/.test(at.step)
         ? `after round ${at.round.index}'s review verdict (\`${at.step}\`)`
         : `in round ${at.round.index} (\`${at.step}\`)`;
-  const report =
-    `⚠️ The runner failed ${where}: ${line}\n\n` +
-    "The unit remains bound to this thread; the next reply continues it, and a pull request already approved with green checks resumes at the checks step, never at a fresh coding round.";
+  const findingsReconcile = at.round?.kind === "findings" && /\/findings(?:\/a\d+)?\/pr-check$/.test(at.step);
+  const report = findingsReconcile
+    ? [
+        `⚠️ Review did not restart because Switchboard could not read the pull request after the completed findings work: ${line}`,
+        pr !== undefined
+          ? `Saved-work fact: the existing pull request is ${pr.url}, but its current branch and exact head were not verified.`
+          : "Saved-work fact: no open pull request or exact remote head was verified.",
+        "No review was started. Next action: retry ship when the pull request is readable so Switchboard can verify the exact head first.",
+      ].join("\n\n")
+    : [
+        `⚠️ Switchboard failed ${where}: ${line}`,
+        "The unit remains resumable from its recorded branch and pull request facts. No continuation action was scheduled. Next action: start ship again after the failing operation is available.",
+      ].join("\n\n");
   const body = {
     ...tag,
     ending: {

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

@@ -12,6 +12,30 @@ import type { UnitEnding } from "./ship/coordinator.js";
 /** The stage vocabulary (record 0065): what every surface says a unit is in. */
 export type Stage = "coding" | "review" | "fix" | "approved" | "merge-ready" | "merged" | "idle" | "ended";
 
+export const HOSTED_PIPELINE_STARTING_DETAIL = "pipeline starting";
+
+/** Safe detail for a hosted parent's shared `working` state, total over Stage. */
+export function hostedStageDetail(stage: Stage): string {
+  switch (stage) {
+    case "coding":
+      return "coding a unit";
+    case "review":
+      return "reviewing a unit";
+    case "fix":
+      return "fixing review findings";
+    case "approved":
+      return "waiting for checks and merge";
+    case "merge-ready":
+      return "ready for a person to merge";
+    case "merged":
+      return "a unit merged";
+    case "idle":
+      return "waiting for the next pipeline step";
+    case "ended":
+      return "finishing the pipeline";
+  }
+}
+
 export const STAGES = [
   "coding",
   "review",

package/dist/assets/src/core/plane/decide.ts

@@ -12,6 +12,31 @@
 import { PLANE, minutesToMs } from "../budgets.js";
 import type { ProviderFailureCause } from "../provider.js";
 import type { PlaneFinding } from "./findings.js";
+import type { RunLiveStateName } from "../runLiveState.js";
+
+/** The one user wording table for the server-owned live condition. */
+export function liveStateWords(state: RunLiveStateName): string {
+  switch (state) {
+    case "admitted":
+      return "admitted";
+    case "waiting_deploy":
+      return "waiting for the current deploy";
+    case "waiting_repository":
+      return "waiting for the repository container";
+    case "falling_back":
+      return "switching to a fallback workspace";
+    case "preparing":
+      return "preparing the workspace";
+    case "working":
+      return "working";
+    case "waiting_provider":
+      return "waiting for the model provider";
+    case "wrapping_up":
+      return "wrapping up";
+    case "ended":
+      return "ended";
+  }
+}
 
 // ---- endings and their causes (record 0064, "Endings and the watches") ------------------------
 

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

@@ -150,6 +150,10 @@ export interface ReviewVerdict {
 export const LGTM_TOKEN = "LGTM:";
 export const CHANGES_TOKEN = "Changes requested:";
 export const NO_VERDICT_LINE = "No verdict submitted — not approving.";
+/** Conservative ceiling below GitHub's 65,536-character review-body limit.
+ * Counted as Unicode code points so clipping never splits a surrogate pair. */
+export const MAX_REVIEW_POST_CODE_POINTS = 65_000;
+const REVIEW_TRUNCATION_NOTE = "_(review truncated to fit GitHub's review size limit)_";
 
 /** Parse an arbitrary tool input into a verdict, or null when it is not one.
  *  `addressSeverity` is the level in force for the run (default `minor`): an
@@ -383,7 +387,11 @@ function verdictMarker(verdict: ReviewVerdict | undefined, target: ReviewBodyTar
  * `approve`), a GitHub alert callout with the verdict word, the pinned head
  * and the finding counts, the findings as a table (severity, id + title, the
  * file linked at the head), the model's text folded under `Full review`, and
- * the machine-readable marker last. The prose decides nothing above the fold.
+ * the machine-readable marker last. Only the prose may be clipped to fit the
+ * platform: every fixed verdict section and the marker remain byte-for-byte.
+ * If those sections leave no room for a visible bounded review, the oversized
+ * body is returned so the publication boundary can refuse it instead of
+ * silently dropping the write-up. The prose decides nothing above the fold.
  */
 export function buildReviewPostBody(
   answer: string,
@@ -395,10 +403,10 @@ export function buildReviewPostBody(
     ...(target ? [`head \`${target.head.slice(0, 7)}\``] : []),
     verdict ? findingCounts(verdict.findings) : "the run ended without a submit_verdict call",
   ];
-  const parts: string[] = [verdictLine(verdict), `> [!${calloutKind(verdict)}]\n> ${facts.join(" · ")}`];
+  const fixedParts: string[] = [verdictLine(verdict), `> [!${calloutKind(verdict)}]\n> ${facts.join(" · ")}`];
   const findings = verdict?.findings ?? [];
   if (findings.length > 0) {
-    parts.push(
+    fixedParts.push(
       [
         "| Severity | Finding | Where |",
         "| --- | --- | --- |",
@@ -409,10 +417,29 @@ export function buildReviewPostBody(
       ].join("\n"),
     );
   }
+
+  const marker = verdictMarker(verdict, target);
+  const fixedBody = [...fixedParts, marker].join("\n\n");
   const prose = answer.trim();
-  if (prose) parts.push(`<details>\n<summary>Full review</summary>\n\n${prose}\n\n</details>`);
-  parts.push(verdictMarker(verdict, target));
-  return parts.join("\n\n");
+  if (!prose) return fixedBody;
+
+  const details = (text: string, truncated: boolean): string =>
+    `<details>\n<summary>Full review</summary>\n\n${text}${truncated ? `${text ? "\n\n" : ""}${REVIEW_TRUNCATION_NOTE}` : ""}\n\n</details>`;
+  const render = (text: string, truncated: boolean): string =>
+    [...fixedParts, details(text, truncated), marker].join("\n\n");
+  const full = render(prose, false);
+  if ([...full].length <= MAX_REVIEW_POST_CODE_POINTS) return full;
+
+  const clippedShell = render("", true);
+  const proseSeparatorCodePoints = 2; // the blank line before the note when clipped prose is present
+  const proseBudget = MAX_REVIEW_POST_CODE_POINTS - [...clippedShell].length - proseSeparatorCodePoints;
+  if (proseBudget > 0) return render([...prose].slice(0, proseBudget).join(""), true);
+  if ([...clippedShell].length <= MAX_REVIEW_POST_CODE_POINTS) return clippedShell;
+
+  // A successful post must retain a visible write-up. Return the full body
+  // oversized when even the bounded shell cannot fit, so postReviewComment
+  // rejects before fetch and the review remains on the Slack-only path.
+  return full;
 }
 
 /**

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

@@ -5,6 +5,7 @@ import type { DescriptionIssue, PrDescription, RecordedJson, RenderedPointer } f
 import type { HarnessScope } from "./harness/scope.js";
 import type { ModelCard } from "./modelCard.js";
 import type { ProviderFailureCause } from "./provider.js";
+import type { RunStateEvent } from "./runLiveState.js";
 
 /** The `pr_description` review artifact minus the event envelope
  *  (docs/reference/specs/reading-diff.md item 7). */
@@ -492,6 +493,7 @@ export function isHeadMaterial(event: RunEvent): boolean {
     case "context":
     case "reference":
     case "run_meta":
+    case "run_state":
     case "route":
       return true;
     case "run_note":
@@ -923,6 +925,9 @@ export type RunEvent =
    *  start of the loop; a resumed run carries the original. Head material,
    *  like `run_meta`. Additive: unknown → ignored. */
   | { type: "lease"; startedAt: number; endsAt: number; loopEndsAt: number; seq?: number; at?: number }
+  /** A server-owned live-condition boundary. Same-state refreshes update the
+   *  durable projection beside their source event and do not emit this event. */
+  | RunStateEvent
   /** A head the run pushed (docs/reference/specs/run-history.md item 2; decision
    *  0046): the branch and the sha the coding post-step observed on the remote
    *  (`by: "push"`), or the budget-end salvage pushed (`by: "salvage"`),

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

@@ -438,6 +438,7 @@ export function analyzeRunFriction(events: readonly RunEvent[], opts: FrictionOp
       ev.type === "operator" ||
       ev.type === "refusal" ||
       ev.type === "reference" ||
+      ev.type === "run_state" ||
       ev.type === "lease" ||
       ev.type === "pushed_head"
     ) {
@@ -537,6 +538,7 @@ export function analyzeRunFriction(events: readonly RunEvent[], opts: FrictionOp
       return;
     }
 
+    if (ev.type !== "run_note") return;
     switch (ev.kind) {
       case "wrap_up":
         // Its extent is the time from the warning to the end of the window (how

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

@@ -9,6 +9,7 @@ import type { ChannelVisibility } from "../authz/types.js";
 import type { RunProfile } from "../../config/profile.js";
 import type { RunEvent } from "../runEvents.js";
 import type { RunSeed, RunSession } from "../runRecord.js";
+import type { AssignRunLiveStateInput, AssignRunLiveStateResult, RunLiveState } from "../runLiveState.js";
 
 /** How long a generation's claim on a run lasts without a heartbeat. */
 export const LEASE_MS = 30_000;
@@ -158,8 +159,28 @@ export interface LiveRunRow {
   /** The tool definitions the run was started with, verbatim. */
   tools: ToolDef[];
   state: RunState;
+  /** The restart-safe live-condition projection. Optional on legacy rows. */
+  liveState?: RunLiveState;
+  /** Stream sequence that most recently produced or refreshed `liveState`. */
+  liveStateSeq?: number;
 }
 
+/** The atomic live-condition assignment request and answer shared by both ledger implementations. */
+export type LiveStateAssignRequest = AssignRunLiveStateInput & {
+  /** Registry sequence reserved for a changed boundary before fan-out. */
+  eventSeq?: number;
+  /** Other durable row facts that must commit with the projection (for example hosting). */
+  statePatch?: RunState;
+  /** Existing activity facts committed with a same-state projection refresh. */
+  sourceEvents?: AppendableEvent[];
+  /** A new execution segment under the same run id starts after an ended predecessor. */
+  restart?: boolean;
+};
+export type LiveStateAssignResult =
+  | (Extract<AssignRunLiveStateResult, { ok: true }> & { liveStateSeq: number })
+  | Extract<AssignRunLiveStateResult, { ok: false }>
+  | { ok: false; reason: "fenced" | "unknown-run" };
+
 /** One tool call the step dispatched; `tool` decides how a resume settles it.
  *  `boundMs` is the bound the call declared (a bash `timeout`), when it stated
  *  one — what the plane judges a `long_call` steer against (record 0064). */

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

@@ -0,0 +1,205 @@
+import type { PlaneEndingCause } from "./plane/decide.js";
+import { oneLine, redactAndCap } from "./redact.js";
+
+/** The server-owned condition of an admitted run. A plane queue row is not admitted and has none. */
+export type RunLiveStateName =
+  | "admitted"
+  | "waiting_deploy"
+  | "waiting_repository"
+  | "falling_back"
+  | "preparing"
+  | "working"
+  | "waiting_provider"
+  | "wrapping_up"
+  | "ended";
+
+export const RUN_LIVE_STATE_NAMES = [
+  "admitted",
+  "waiting_deploy",
+  "waiting_repository",
+  "falling_back",
+  "preparing",
+  "working",
+  "waiting_provider",
+  "wrapping_up",
+  "ended",
+] as const satisfies readonly RunLiveStateName[];
+
+export const LIVE_STATE_DETAIL_MAX = 160;
+
+export type ResidentLiveStateObservation =
+  | { state: "waiting_deploy"; bound: number; reason: "deploy"; attempt: number }
+  | { state: "waiting_repository"; bound: number; reason: "repository_container"; attempt: number };
+
+export type ResidentLiveStateObserver = (observation: ResidentLiveStateObservation) => Promise<void>;
+
+export interface RunLiveState {
+  state: RunLiveStateName;
+  /** Epoch ms at the most recent state boundary. Same-state refreshes preserve it. */
+  since: number;
+  /** Absolute epoch-ms deadline of the durable fact that created this live condition. */
+  bound?: number;
+  /** Capped, redacted user words. Never a provider body or resident refusal code. */
+  detail?: string;
+}
+
+export interface RunStateEvent extends RunLiveState {
+  type: "run_state";
+  /** Required only for the terminal boundary; it names the plane's existing closed cause. */
+  cause?: PlaneEndingCause;
+  seq?: number;
+  at?: number;
+}
+
+export interface RunLiveStateFoldEvent {
+  type: string;
+  seq?: number;
+  at?: number;
+  state?: unknown;
+  since?: number;
+  bound?: number;
+  detail?: string;
+  endsAt?: number;
+  boundMs?: number;
+}
+
+export interface RunLiveStateMaterialized {
+  liveState?: RunLiveState;
+  /** Authoritative event sequence that produced or refreshed `liveState`. */
+  liveStateSeq?: number;
+}
+
+const TRANSITIONS = {
+  admitted: ["waiting_deploy", "waiting_repository", "falling_back", "preparing", "working", "wrapping_up", "ended"],
+  waiting_deploy: ["waiting_repository", "falling_back", "preparing", "working", "wrapping_up", "ended"],
+  waiting_repository: ["waiting_deploy", "falling_back", "preparing", "working", "wrapping_up", "ended"],
+  falling_back: ["preparing", "working", "wrapping_up", "ended"],
+  preparing: ["waiting_deploy", "waiting_repository", "falling_back", "working", "wrapping_up", "ended"],
+  working: [
+    "waiting_deploy",
+    "waiting_repository",
+    "falling_back",
+    "preparing",
+    "waiting_provider",
+    "wrapping_up",
+    "ended",
+  ],
+  waiting_provider: ["working", "wrapping_up", "ended"],
+  wrapping_up: ["ended"],
+  ended: [],
+} as const satisfies Record<RunLiveStateName, readonly RunLiveStateName[]>;
+
+const UNSAFE_DETAIL =
+  /(?:\bimage-stale\b|\battach-failed\b|\bparked-provider\b|<\/?(?:html|body|head)\b|\bbad gateway\b)/i;
+
+/** Admit only display-ready prose. Typed mappers create normal details; this is the final leak guard. */
+export function safeLiveStateDetail(detail: string | undefined): string | undefined {
+  if (detail === undefined) return undefined;
+  const line = oneLine(detail);
+  if (line === "" || UNSAFE_DETAIL.test(line)) return undefined;
+  return redactAndCap(line, LIVE_STATE_DETAIL_MAX - 1);
+}
+
+export type AssignRunLiveStateInput = {
+  expectedSeq: number;
+  at: number;
+  state: RunLiveStateName;
+  bound?: number;
+  detail?: string;
+  cause?: PlaneEndingCause;
+};
+
+export type AssignRunLiveStateResult =
+  | { ok: true; liveState: RunLiveState; event?: RunStateEvent }
+  | {
+      ok: false;
+      reason:
+        "stale-sequence" | "terminal" | "invalid-transition" | "bound-required" | "invalid-bound" | "cause-required";
+    };
+
+/** Pure assignment gate. Persistence chooses the next stream sequence and commits the result atomically. */
+export function assignRunLiveState(
+  current: RunLiveState | undefined,
+  currentSeq: number,
+  input: AssignRunLiveStateInput,
+): AssignRunLiveStateResult {
+  if (input.expectedSeq !== currentSeq) return { ok: false, reason: "stale-sequence" };
+  if (current === undefined && input.state !== "admitted") return { ok: false, reason: "invalid-transition" };
+  if (current?.state === "ended") return { ok: false, reason: "terminal" };
+  if (input.state !== "ended") {
+    if (input.bound === undefined) return { ok: false, reason: "bound-required" };
+    if (!Number.isFinite(input.bound) || input.bound < input.at) return { ok: false, reason: "invalid-bound" };
+  } else if (input.cause === undefined) return { ok: false, reason: "cause-required" };
+  if (
+    current !== undefined &&
+    current.state !== input.state &&
+    !TRANSITIONS[current.state].includes(input.state as never)
+  )
+    return { ok: false, reason: "invalid-transition" };
+
+  const detail = safeLiveStateDetail(input.detail);
+  const liveState: RunLiveState = {
+    state: input.state,
+    since: current?.state === input.state ? current.since : input.at,
+    ...(input.state !== "ended" ? { bound: input.bound } : {}),
+    ...(detail !== undefined ? { detail } : {}),
+  };
+  if (current?.state === input.state) return { ok: true, liveState };
+  return {
+    ok: true,
+    liveState,
+    event: {
+      type: "run_state",
+      ...liveState,
+      ...(input.state === "ended" ? { cause: input.cause } : {}),
+      at: input.at,
+    },
+  };
+}
+
+/** Rebuild the projection from boundaries. A later event sequence always defeats stale materialized state. */
+export function foldRunLiveState(
+  events: readonly RunLiveStateFoldEvent[],
+  materialized: RunLiveStateMaterialized = {},
+): RunLiveStateMaterialized {
+  let liveState = materialized.liveState;
+  let liveStateSeq = materialized.liveStateSeq ?? 0;
+  let leaseEndsAt: number | undefined;
+  for (const event of [...events].sort((left, right) => (left.seq ?? 0) - (right.seq ?? 0))) {
+    if (event.type === "lease" && event.endsAt !== undefined) leaseEndsAt = event.endsAt;
+    const seq = event.seq ?? 0;
+    if (seq <= liveStateSeq) continue;
+    if (
+      event.type === "run_state" &&
+      RUN_LIVE_STATE_NAMES.includes(event.state as RunLiveStateName) &&
+      event.since !== undefined
+    ) {
+      liveState = {
+        state: event.state as RunLiveStateName,
+        since: event.since,
+        ...(event.bound !== undefined ? { bound: event.bound } : {}),
+        ...(event.detail !== undefined ? { detail: event.detail } : {}),
+      };
+      liveStateSeq = seq;
+      continue;
+    }
+    if (
+      event.type === "tool_call" &&
+      liveState?.state === "working" &&
+      event.at !== undefined &&
+      event.boundMs !== undefined
+    ) {
+      liveState = { ...liveState, bound: event.at + event.boundMs, detail: "running a tool" };
+      liveStateSeq = seq;
+      continue;
+    }
+    if (event.type === "tool_result" && liveState?.state === "working" && leaseEndsAt !== undefined) {
+      liveState = { ...liveState, bound: leaseEndsAt, detail: "model turn" };
+      liveStateSeq = seq;
+    }
+  }
+  return {
+    ...(liveState !== undefined ? { liveState } : {}),
+    ...(liveStateSeq > 0 ? { liveStateSeq } : {}),
+  };
+}

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

@@ -5,6 +5,7 @@ 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";
+import type { RunLiveState } from "./runLiveState.js";
 import { isHandoffShape, type Handoff } from "./ship/handoff.js";
 import {
   type FindingDisposition,
@@ -124,6 +125,9 @@ export interface RunRecord {
   stepCount?: number;
   schema?: number;
   status: RunStatus;
+  /** Final server-owned live condition. Optional on records from older writers. */
+  liveState?: RunLiveState;
+  liveStateSeq?: number;
   /** 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