@coreplane/switchboard 1.260.5 → 1.261.0

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

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

@@ -550,7 +550,7 @@ export type CoordinatorAction =
   | { type: "branch"; step: string; branch: string; from: string }
   | { type: "spawn"; step: string; preset: ChildPreset; round: RoundRef; budgetMinutes: number; brief: Brief }
   | { type: "wait"; step: string; runId: string; timeoutMs: number }
-  | { type: "read-record"; step: string; runId: string }
+  | { type: "read-record"; step: string; runId: string; finishedObserved?: true }
   /** Tell a child whose pull request became terminal or moved to end at its
    *  next turn boundary without publishing anything. This is a steer through
    *  the child's inbox, never a stop that tears down its workspace. */
@@ -1170,7 +1170,7 @@ type Phase =
   | { at: "busy-wait"; round: RoundRef; runId?: string; n: number }
   /** `until`: when the child's budget plus the margin runs out, counted from the spawn's answer — the wait's last slice ends there. */
   | { at: "wait"; round: RoundRef; runId: string; n: number; until: number }
-  | { at: "read"; round: RoundRef; runId: string; n: number; until: number }
+  | { at: "read"; round: RoundRef; runId: string; n: number; until: number; finishedObserved: boolean }
   /** A live child lost authority because its pull request became terminal,
    *  its reviewed head moved, or its branch disappeared. Steer once, then
    *  drain the child to its recorded end while ignoring every late artifact. */
@@ -1197,6 +1197,7 @@ type Phase =
       n: number;
       until: number;
       supersession: ChildSupersession;
+      finishedObserved: boolean;
     }
   /** A moved-head child has drained. Re-read the adopted pull request before
    *  restarting review because it may have merged, closed or moved again. */
@@ -1533,7 +1534,12 @@ export function nextAction(s: UnitPipelineState): CoordinatorAction {
         timeoutMs: Math.min(waitSliceMs(s.clock, p.until), s.pr !== undefined ? PR_TRANSITION_GUARD_MS : WAIT_CHUNK_MS),
       };
     case "read":
-      return { type: "read-record", step: `${roundStep(s, p.round)}/read/${p.n}`, runId: p.runId };
+      return {
+        type: "read-record",
+        step: `${roundStep(s, p.round)}/read/${p.n}`,
+        runId: p.runId,
+        ...(p.finishedObserved ? { finishedObserved: true as const } : {}),
+      };
     case "steer":
       return {
         type: "steer",
@@ -1553,6 +1559,7 @@ export function nextAction(s: UnitPipelineState): CoordinatorAction {
         type: "read-record",
         step: `${roundStep(s, p.round)}/superseded/read/${p.n}`,
         runId: p.runId,
+        ...(p.finishedObserved ? { finishedObserved: true as const } : {}),
       };
     case "superseded-pr-check":
       return {
@@ -2960,11 +2967,23 @@ export function applyReturn(s: UnitPipelineState, ret: StepReturn): Transition {
         notes: [],
       };
     }
-    case "wait":
+    case "wait": {
+      const r = ret as Extract<StepReturn, { type: "wait" }>;
       return {
-        state: { ...s, phase: { at: "read", round: p.round, runId: p.runId, n: p.n, until: p.until } },
+        state: {
+          ...s,
+          phase: {
+            at: "read",
+            round: p.round,
+            runId: p.runId,
+            n: p.n,
+            until: p.until,
+            finishedObserved: r.outcome === "event",
+          },
+        },
         notes: [],
       };
+    }
     case "read": {
       const r = ret as Extract<StepReturn, { type: "read-record" }>;
       const supersession = childSupersession(clocked, p.round, r.pullRequest);
@@ -2979,6 +2998,7 @@ export function applyReturn(s: UnitPipelineState, ret: StepReturn): Transition {
             n: p.n,
             until: p.until,
             supersession,
+            finishedObserved: p.finishedObserved,
           };
           return finishSupersededChild(clocked, terminalPhase);
         }
@@ -3098,7 +3118,8 @@ export function applyReturn(s: UnitPipelineState, ret: StepReturn): Transition {
         notes: [],
       };
     }
-    case "superseded-wait":
+    case "superseded-wait": {
+      const r = ret as Extract<StepReturn, { type: "wait" }>;
       return {
         state: {
           ...s,
@@ -3109,10 +3130,12 @@ export function applyReturn(s: UnitPipelineState, ret: StepReturn): Transition {
             n: p.n,
             until: p.until,
             supersession: p.supersession,
+            finishedObserved: r.outcome === "event",
           },
         },
         notes: [],
       };
+    }
     case "superseded-read": {
       const r = ret as Extract<StepReturn, { type: "read-record" }>;
       if (r.run.finished) return finishSupersededChild(clocked, p);