wicked-crew-api-types 0.134.0 → 0.137.0

package/index.d.ts

@@ -287,6 +287,22 @@ export interface HealthCapabilities {
    * the run. ABSENT on an older daemon — do not send the field (its strict schema 400s on it).
    */
   launchPrimary?: boolean;
+  /**
+   * (api-types 0.136.0, DES-SYSTEM-VIEW) `GET /system` is served: the Nerve Center snapshot
+   * ({@link SystemSnapshot}). ABSENT on an older daemon — show the older Health cards instead.
+   */
+  system?: boolean;
+  /**
+   * (api-types 0.137.0, DES-SYSTEM-CHAT) The chat history is served: `GET /chats` carries `items` +
+   * `nextCursor`, `GET /chats/:id/messages` reopens a chat, `POST /chats/:id/close` ends one and keeps
+   * its history. ABSENT on an older daemon — hide the past-chats rail.
+   */
+  chatList?: boolean;
+  /**
+   * (api-types 0.137.0) `POST /chats/:id/attachments` and `ChatMessageBody.attachments` are served.
+   * ABSENT on an older daemon — hide upload.
+   */
+  chatAttachments?: boolean;
 }
 
 /** One `GET /health.warnings[]` entry (additive; wicked-core#411 / wicked-crew#497). */
@@ -739,6 +755,12 @@ export interface WorkUnit {
   /** (api-types 0.102.0; wicked-core#850, core-ts ≥ 0.7.46) The receipt of this unit's LAST gate,
    *  as `gateEvaluated.assurance` carried it. ABSENT until a gate ran, and on an older engine. */
   assurance?: AssuranceReceipt;
+  /** (api-types 0.135.0) Every layer other than the repo-checks floor that denied this unit's last
+   *  gate, plus any earlier denial over the same tree that gate did not ask again — the record
+   *  `operator_judgment` reads (it is refused while any stands). `[]`: known, nothing but the floor
+   *  denied. ABSENT (or `null`): unknown — a unit from before the record, or an older engine. The
+   *  engine's own serialization, so its fields are snake_case (`claim_id`, `rule_ids`, …). */
+  denials_behind?: Array<{ source: string; reason: string; [k: string]: unknown }> | null;
   /** Evaluator≠creator role. Present on def-driven units; absent on legacy/free-text. */
   role?: PhaseRole;
   /** Gate policy for this phase. Present on def-driven units; absent on legacy/free-text. */
@@ -1191,6 +1213,13 @@ export interface RosterSeat {
    * `GET /roster/record`. ABSENT when there is no active bench.
    */
   recent_bench?: SeatRecentBench;
+  /**
+   * (unreleased, PRODUCT-WORKS J4) The active bench, flat, for the Nerve Center
+   * (`SystemCli.benchedUntil` / `stateReason`): ISO-8601 of when it lifts (`recent_bench.lifts_at`)
+   * and why, in the operator's words. Both present iff `recent_bench` is.
+   */
+  benchedUntil?: string;
+  benchReason?: string;
   /**
    * (unreleased, wicked-core#976) The engine's HOST-FLOOR bench reason for this seat: on the interim
    * host floor (`WICKED_SEAT_FLOOR` other than `container`) the engine refuses governed work on any
@@ -1288,10 +1317,19 @@ export interface SeatRecentBench {
   runs: number;
   /** ISO-8601 of the latest bench. */
   last_at: string;
-  /** ISO-8601 of when crew stops carrying it to new launches. Crew's window, NOT a provider reset
-   *  time (no provider states one on the wire today). */
+  /** ISO-8601 of when crew stops carrying it to new launches. (unreleased, PRODUCT-WORKS J4) For a
+   *  quota bench (`quota_exhausted`, `usage_limit`): the engine's lift time (the provider's reset time
+   *  when the refusal stated one, else the engine's backoff), or crew's backoff of 15, 30, then 60
+   *  minutes by `strikes`; any other kind keeps crew's 30-minute window. */
   lifts_at: string;
-  /** Who benched it in the run: `worker` or `judge`. */
+  /** (unreleased, J4) Where `lifts_at` came from: the engine's `seatBenched.benchedUntilMs`, crew's
+   *  quota backoff, or the fixed window. */
+  until_source: 'engine' | 'backoff' | 'window';
+  /** (unreleased, J4) Quota benches in a row with no good turn between (the backoff step); 0 on a
+   *  non-quota bench. */
+  strikes: number;
+  /** Who benched it in the run: `worker`, `judge`, or (unreleased, J4) `reprobe` — its quota bench
+   *  fell due and it did not answer the engine's re-probe. */
   source: string;
   /** The engine's own reason, verbatim (technical details). */
   reason: string;
@@ -1706,6 +1744,19 @@ export interface GateDecision {
      *  {@link GateInfo.rejudge} says beforehand. Unlike a plain approve there, it is never the
      *  operator's own judgment. */
     | 'rejudge'
+    /** (api-types 0.135.0, operator ruling 2026-10-21) APPROVE AS YOUR OWN JUDGMENT at the
+     *  escalation gate of a FAILED REPO-CHECKS FLOOR (`gateEscalated.condition: 'floor_failed'`,
+     *  `denialSource: 'repo_checks' | 'repo_checks_timeout'`), with `approve: true` and the written
+     *  rationale in `amend` — required, non-empty (a 400 otherwise); no `amendScope` or `plan`. The
+     *  operator judges from the evidence that the failures are not the work's (load flakes,
+     *  pre-existing reds): the unit counts as it stands, its gate receipt records an
+     *  {@link OperatorJudgment} with `floorOverride` set (the floor result it overrode, labelled
+     *  "floor overridden by operator"), and the run ({@link RunAssurance.floorOverrides}) and the
+     *  delivery carry the label. It overrides the floor ONLY: the engine refuses it (409, gate left
+     *  open) when any other layer of the same gate also denied, on a team member's step, on a tool or
+     *  deliver step and at every other gate. QE acceptance is never waived by it — a run that
+     *  requires it still needs its PASS before delivery. Engine: wicked-core-ts after 0.15.6. */
+    | 'operator_judgment'
     /** (core#820) A `consent` gate's choice from its dry-run plan (`awaitingHuman.choices`), with
      *  `approve: true`: `consent:worker` (the default), `consent:operator`, …; `reject` declines. */
     | `consent:${string}`;
@@ -2317,7 +2368,8 @@ export type AssuranceInstrument =
   | 'judge'
   | 'evaluator_pass'
   | 'distinct_evaluator'
-  /** (api-types 0.110.0) The operator judged a gate whose judge could not rule. */
+  /** (api-types 0.110.0) The operator judged a gate whose judge could not rule — or (api-types
+   *  0.135.0) overrode a failed repo-checks floor (`operatorJudges[].floorOverride`). */
   | 'operator_judge'
   | (string & {});
 
@@ -2330,9 +2382,34 @@ export interface OperatorJudgment {
   by: string;
   /** Unix millis. */
   at: number;
+  /** The operator's note; on a floor override, the written rationale (never empty). */
   note: string | null;
-  /** Why the judge could not rule (the gate's denial reason). */
+  /** Why the judge could not rule (the gate's denial reason) — or, on a floor override, why the
+   *  floor denied. */
   reason: string | null;
+  /** (api-types 0.135.0) Set when this judgment OVERRODE a failed repo-checks floor
+   *  ({@link GateDecision.action} `'operator_judgment'`); ABSENT on a judge-unavailable judgment
+   *  and on an older engine. */
+  floorOverride?: FloorOverride;
+}
+
+/**
+ * (api-types 0.135.0, operator ruling 2026-10-21) The failed floor result an operator's judgment
+ * overrode. It answers the repo-checks floor only: every other layer of the gate still denies, and
+ * QE acceptance is untouched.
+ */
+export interface FloorOverride {
+  /** The floor layer that denied: `repo_checks` | `repo_checks_timeout`. */
+  layer: string;
+  /** The floor result overridden — `<run>:unit-<ord>:attempt-<n>:<layer>`, the unit's
+   *  `repoChecksEvaluated` frame for that attempt (or the carried result it stood on). */
+  resultId: string;
+  ord: number;
+  attempt: number;
+  /** The tree the overridden checks ran on, when the report names it. */
+  tree: string | null;
+  /** `floor overridden by operator` — the line to show as-is. */
+  label: string;
 }
 
 /**
@@ -2375,8 +2452,14 @@ export interface RunAssurance {
    *  exactly when `required` holds `qe_acceptance`. ABSENT on an older engine (then a required
    *  `qe_acceptance` is enforced). */
   qe?: QeAcceptanceDecision;
+  /** (api-types 0.135.0) Every failed floor the operator overrode on this run ("floor overridden
+   *  by operator"), each with who, when and the rationale; ABSENT when none or on an older engine. */
+  floorOverrides?: OperatorJudgment[];
 }
 
+/** (api-types 0.135.0) The label an overridden floor carries on the run, the gate and the delivery. */
+export type FloorOverrideLabel = 'floor overridden by operator';
+
 /** (api-types 0.106.0) `QeAcceptanceDecision.status`. */
 export type QeAcceptanceStatus = 'required' | 'waived' | 'skipped' | (string & {});
 
@@ -6599,6 +6682,8 @@ export interface ChatOpenBody {
    * (`path.started.selection: "random"`).
    */
   primary?: string;
+  /** (api-types 0.137.0, DES-SYSTEM-CHAT) The page the chat was started on, for the history list. */
+  startedOn?: ChatStartedOn;
 }
 
 /** The scope a `POST /chats` caller may name (api-types 0.39.0, studio#323 R4). */
@@ -6859,9 +6944,18 @@ export interface ChatSummary {
   readRoots?: string[];
 }
 
-/** `GET /chats` → 200. */
+/**
+ * `GET /chats` → 200. `chats`: the live engine / ask-path rows, unchanged. From api-types 0.137.0
+ * (DES-SYSTEM-CHAT) also the paged chat HISTORY: `items` newest first by `updatedAt`, and
+ * `nextCursor` to pass as `?cursor=` for the next page (`null` on the last). Query: `?limit=`
+ * (1–100, default 20), `?cursor=`, `?status=open|closed|all` (default `all`). Under
+ * `auth: required` only the caller's own chats are listed. ABSENT on an older daemon (no
+ * `capabilities.chatList`).
+ */
 export interface ChatListResponse {
   chats: ChatSummary[];
+  items?: ChatHistoryEntry[];
+  nextCursor?: string | null;
 }
 
 /**
@@ -6886,7 +6980,8 @@ export interface ChatUsage {
  * "exceeded the N s turn budget … target it on your next message to re-seat it").
  */
 export type ChatTranscriptRecord =
-  | { at: number; turnId: string; kind: 'user'; text: string; seats: string[] }
+  /** `attachments` (api-types 0.137.0): the files the message carried, ABSENT when none. */
+  | { at: number; turnId: string; kind: 'user'; text: string; seats: string[]; attachments?: ChatAttachment[] }
   | { at: number; turnId: string; kind: 'seat'; cliKey: string; text: string; ok: boolean; usage: ChatUsage | null }
   /**
    * The citation verdicts of the `seat` record with the same `turnId` + `cliKey` (api-types 0.68.0,
@@ -6921,6 +7016,133 @@ export type ChatTranscriptRecord =
    */
   | { at: number; turnId: string; kind: 'system'; text: string };
 
+// ── System chat: history, close, attachments (api-types 0.137.0, DES-SYSTEM-CHAT "Crew") ────────
+//
+// The floating system chat's past-chats rail, its Close, and its uploads. Capabilities:
+// `GET /health.capabilities.chatList` (the history list, `POST /chats/:id/close`,
+// `GET /chats/:id/messages`) and `.chatAttachments` (`POST /chats/:id/attachments` and
+// `ChatMessageBody.attachments`). A chat's history is kept until `DELETE /chats/:id`, which still
+// ends the chat AND deletes its history and attachments; `POST /chats/:id/close` ends it and keeps both.
+
+/** The page a chat was started on: studio's route and its human label ("Run 9b43ee44"). */
+export interface ChatStartedOn {
+  route: string;
+  label: string;
+}
+
+/** One past or open system chat, as the history list shows it. */
+export interface ChatHistoryEntry {
+  /** The chat id: `GET /chats/:id/messages` reopens it, `POST /chats/:id/close` ends it. */
+  id: string;
+  /** The first operator message, whitespace-collapsed and cut at 80 characters (an ellipsis
+   *  included); "New chat" before the first message. */
+  title: string;
+  /** Where the chat was started, when the opener said (`ChatOpenBody.startedOn`); else `null`. */
+  startedOn: ChatStartedOn | null;
+  /** The CLI that answers (the chat's primary agent once known, else the operator's choice, else
+   *  its first eligible seat); `null` when none was seated. */
+  cli: string | null;
+  /** ISO-8601. */
+  createdAt: string;
+  /** ISO-8601 of the newest message (or of the open, before any). */
+  updatedAt: string;
+  /** Operator messages plus seat replies (prefaces, citations and decision records excluded). */
+  messageCount: number;
+  /** Files uploaded to the chat. */
+  attachmentCount: number;
+  /** `open`: live on this daemon; `closed`: ended (Close, idle, or a daemon restart), history kept. */
+  status: 'open' | 'closed';
+  /** ISO-8601 of the end; present with `status: 'closed'`. */
+  closedAt?: string;
+}
+
+/** `GET /chats/:id/messages` → 200 (404 for an id with no history). An open chat answers its live
+ *  transcript; a closed one its kept history. Same records as `ChatDetailResponse.messages`. */
+export interface ChatMessagesResponse {
+  chat: ChatHistoryEntry;
+  messages: ChatTranscriptRecord[];
+  attachments: ChatAttachment[];
+}
+
+/** `POST /chats/:id/close` → 200: the chat is ended (its seats released, its run cancelled) and its
+ *  history and attachments are kept. Idempotent: closing a closed chat answers its entry again. */
+export interface ChatCloseResponse {
+  ok: true;
+  chat: ChatHistoryEntry;
+}
+
+/** `POST /chats/:id/close` → **502** when the chat's run could not be cancelled: the chat IS closed
+ *  and its history kept, but its run may still be running — cancel it from the run (`runId`). */
+export interface ChatCloseCancelFailed {
+  error: string;
+  runId: string;
+  chat: ChatHistoryEntry;
+}
+
+/** What an attachment is to a seat: an image (png, jpeg, gif, webp), text (UTF-8), or a pdf. */
+export type ChatAttachmentKind = 'image' | 'text' | 'pdf';
+
+/** One uploaded file. Stored under the state home (`<state home>/chats/attachments/<chat>/`),
+ *  removed with its chat on `DELETE /chats/:id`. */
+export interface ChatAttachment {
+  id: string;
+  chatId: string;
+  /** The uploaded file name, sanitized (no path). */
+  name: string;
+  /** The verified media type (`image/png`, `text/plain`, `application/pdf`, …). */
+  mediaType: string;
+  kind: ChatAttachmentKind;
+  bytes: number;
+  sha256: string;
+  /** ISO-8601. */
+  createdAt: string;
+}
+
+/** The caps an upload and a message are held to (also on every 413). */
+export interface ChatAttachmentLimits {
+  /** One file, bytes. */
+  maxFileBytes: number;
+  /** All files one message references (and one upload request carries), bytes. */
+  maxMessageBytes: number;
+  /** Files per message (and per upload request). */
+  maxFiles: number;
+  /** The media types accepted. */
+  mediaTypes: string[];
+}
+
+/** `POST /chats/:id/attachments` (multipart/form-data, one or more file parts) → 201. */
+export interface ChatAttachmentUploadResponse {
+  attachments: ChatAttachment[];
+  limits: ChatAttachmentLimits;
+}
+
+/**
+ * An upload or a send refused over an attachment: 413 `attachment_too_large` (one file over
+ * `maxFileBytes`) or `attachments_too_large` (the request or the message over `maxMessageBytes`, or
+ * over `maxFiles`); 415 `attachment_type` (not an image, UTF-8 text or pdf, or its bytes do not
+ * match its type); 404 `attachment_unknown` (a message names an id this chat does not have); 400
+ * `attachment_malformed` (not multipart, or no file part).
+ */
+export interface ChatAttachmentError {
+  error: string;
+  code: 'attachment_too_large' | 'attachments_too_large' | 'attachment_type' | 'attachment_unknown' | 'attachment_malformed';
+  /** The file the refusal is about, when one. */
+  name?: string;
+  bytes?: number;
+  limits: ChatAttachmentLimits;
+}
+
+/** `POST /chats/:id/messages` body (named in api-types 0.137.0; `text` and `targets` unchanged). */
+export interface ChatMessageBody {
+  text: string;
+  targets?: string[];
+  /** (api-types 0.137.0) Ids from `POST /chats/:id/attachments` this message carries (at most
+   *  `maxFiles`, together at most `maxMessageBytes`). Each reaches the answering seat as a read-only
+   *  file: a path it can open (images as images where the CLI reads them) plus, for text and pdf,
+   *  the extracted text. Send only when `GET /health.capabilities.chatAttachments === true`. */
+  attachments?: string[];
+}
+
 /** `GET /chats/:id` → 200. */
 export interface ChatDetailResponse {
   chatId: string;
@@ -8035,6 +8257,285 @@ export interface NoEligibleSeatBody {
   remedy: string;
 }
 
+// ── System snapshot — the Nerve Center (api-types 0.136.0, DES-SYSTEM-VIEW) ────────────────────
+//
+// `GET /api/v1/system`: ONE derived, read-only snapshot answering "is anything stopping work, why,
+// and what fixes it?" — the CLIs, the unfinished runs, the infrastructure and the governance
+// instruments, plus `attention[]`, the union of every item that needs a look. Every infra row is a
+// real probe run for THIS request under a bounded timeout (a probe that did not answer reads
+// `unknown` with its timeout, never `ok`); liveness is computed from evidence; a number the daemon
+// cannot count is `null` (or the field is absent where the doc says so), never a fabricated 0. The
+// whole snapshot answers within a fixed overall bound (`budgetMs`) even when probes hang.
+// `GET /health.capabilities.system === true` advertises the route. `/diagnostics` stays the raw dump;
+// each of its blocks is reachable from here (see each row's `details`).
+
+/** One state for every infra row and governance card. `off`: the component is not part of this
+ *  deployment right now (the container gateway on the host floor, an interactive bridge nothing has
+ *  started yet) — not a problem and never in `attention[]`. */
+export type SystemState = 'ok' | 'degraded' | 'down' | 'unknown' | 'off';
+
+/** The Nerve Center light: `red` when work is blocked, `yellow` when something needs a look but
+ *  work still flows, `green` when `attention[]` is empty. Derived from `attention[]` only. */
+export type SystemLevel = 'green' | 'yellow' | 'red';
+
+/** The existing action an attention item or row offers (the snapshot itself is read-only):
+ *  `sign_in` — the CLI's sign-in (`POST /seats/:cli/login…` / the Agents page); `recheck` — read
+ *  the snapshot again (every probe runs fresh per read); `open_gate` — the run's open gate;
+ *  `open_run` — the run. */
+export type SystemActionKind = 'sign_in' | 'recheck' | 'open_gate' | 'open_run';
+
+/** Where an item points. A skin maps it to its own route; crew never spells a studio URL. */
+export type SystemTarget =
+  | { kind: 'infra'; key: SystemInfraKey }
+  | { kind: 'cli'; cli: string }
+  | { kind: 'run'; runId: string; gateOrd?: number; interactionId?: string }
+  | { kind: 'governance'; key: SystemGovernanceKey };
+
+export interface SystemAction {
+  kind: SystemActionKind;
+  /** The button's words ("Sign in", "Re-check", "Open the gate", "Open the run"). */
+  label: string;
+}
+
+/** `GET /api/v1/system`. */
+export interface SystemSnapshot {
+  /** ISO-8601 of when this snapshot was assembled (the probes ran just before it). */
+  checkedAt: string;
+  /** The overall bound the daemon held this answer to, in ms. */
+  budgetMs: number;
+  /** How long assembling it took, in ms. */
+  tookMs: number;
+  /** `red` iff some attention item is `red`, else `yellow` iff any item, else `green`. */
+  level: SystemLevel;
+  /** Every item that needs a look, worst first (red before yellow, then by how many runs it
+   *  blocks, then infra › cli › run › governance). Empty when all is clear. */
+  attention: SystemAttentionItem[];
+  /** One entry per CLI on the roster, in roster order. */
+  clis: SystemCli[];
+  /** Every unfinished run (not completed / cancelled / failed), worst first:
+   *  waiting_on_you › held › stalled › quiet › working, then oldest evidence first. */
+  runs: SystemRun[];
+  infra: SystemInfraRow[];
+  governance: SystemGovernanceCard[];
+}
+
+export interface SystemAttentionItem {
+  /** Stable across reads while the same thing is wrong (`infra:gateway`, `cli:copilot`,
+   *  `run:<id>`, `judge:<runId>`, `governance:dead_letters`). */
+  id: string;
+  severity: 'red' | 'yellow';
+  source: 'infra' | 'cli' | 'run' | 'governance';
+  /** The one-line headline ("gateway down", "copilot benched (quota)", "run 9b43ee44 stalled"). */
+  title: string;
+  /** Why, in plain words. */
+  reason: string;
+  /** What fixes it, in plain words. */
+  remedy: string;
+  /** How many unfinished runs it blocks (0 when it blocks none directly). */
+  blocks: number;
+  target: SystemTarget;
+  /** The one existing action that helps, or `null`. */
+  action: SystemAction | null;
+}
+
+// ── clis[] ──
+
+/** `signed_in`: the roster reads the seat signed in (or not needing a sign-in) and no bench is
+ *  active; `signed_out`: it needs a sign-in; `benched`: the engine benched it in a run on its own
+ *  refusal (quota / 429, usage limit, not logged in…) and crew keeps it out of new launches until
+ *  `benchedUntil`; `unknown`: the daemon cannot tell cheaply (the check has not answered). */
+export type SystemCliState = 'signed_in' | 'signed_out' | 'benched' | 'unknown';
+
+export interface SystemCli {
+  cli: string;
+  label: string;
+  state: SystemCliState;
+  /** Why the state is not `signed_in`, in the operator's words; `null` when it is. */
+  stateReason: string | null;
+  /** ISO-8601 of when an active bench lifts; present only with `state: 'benched'`. */
+  benchedUntil?: string;
+  /** Whether the seat can be signed in from studio (a container sign-in or a login command). */
+  canSignIn: boolean;
+  /** May be seated as a judge/council member right now (the roster's `council_eligible`). */
+  councilEligible: boolean;
+  /** May be seated for work right now (the roster's `work_eligible`; absent there reads true). */
+  workEligible: boolean;
+  /** The installed version the roster's background probe read; `null` before the first reading. */
+  version: string | null;
+  /** The ACP version pin, when the seat is pinned: `matched: false` fails its governance closed. */
+  versionPin: { pinned: string; observed: string | null; matched: boolean } | null;
+  /** The engine's governance class for the seat, verbatim; `null` on an engine without it. */
+  governanceClass: string | null;
+  /** The governance mode per scope kind (`RosterSeat.governance_mode`); `null` when unread. */
+  governanceMode: Record<string, string> | null;
+  /** `wrapped` | `acp` — how the seat runs; `null` when the seat governance read failed. */
+  transport: string | null;
+  /** The seat's sandbox in words: `container` (the seat floor), `host:<launcher>`, `os_sandbox`,
+   *  or `none`. */
+  sandbox: string;
+  /** The last seat-level error the daemon observed, or `null`. */
+  lastError: { at: string; message: string } | null;
+  /** The 7-day record folded from the run store; `null` when the engine has no event-log read
+   *  binding, or the fold did not finish inside the snapshot's bound (`statsNote` says which). */
+  stats: SystemCliStats | null;
+  statsNote?: string;
+  /** The `/diagnostics` facts for this CLI, verbatim: `acp` = `acp.byCli[cli]`, `seatGovernance`
+   *  = its `seatGovernance.seats[]` entry, `health` = `RosterSeat.health`. */
+  details: {
+    acp: AcpCliDiagnostics | null;
+    seatGovernance: DiagnosticsSeatGovernanceEntry | null;
+    health: SeatHealth | null;
+  };
+}
+
+/** A CLI's last 7 days, folded from the runs' durable event logs (event time, `ts`). */
+export interface SystemCliStats {
+  days: number;
+  /** Window start, unix millis. Day buckets are 24 h slices from here. */
+  since: number;
+  /** When the fold ran (unix millis) — the stats are cached up to 30 s; every probe is not. */
+  asOf: number;
+  /** Distinct units dispatched to the CLI inside the window. */
+  units: number;
+  /** Of those, the units whose first gate evaluation in the window ran. */
+  gated: number;
+  /** Units whose first gate evaluation passed (combined, no denial). */
+  firstPass: number;
+  /** `round(firstPass / gated * 100)`; `null` when `gated` is 0. */
+  passPct: number | null;
+  /** Median of dispatch → captured output per unit attempt on this CLI, ms; `null` when none
+   *  finished in the window. */
+  medianUnitMs: number | null;
+  /** `seatBenched` frames for the CLI whose reason is a quota / rate / usage limit (the 429s). */
+  rateLimited: number;
+  /** All `seatBenched` frames for the CLI (any reason). */
+  benches: number;
+  /** `acpFallback` frames for the CLI. */
+  fallbacks: number;
+  /** Units dispatched per 24 h slice, oldest first (`days` entries) — the sparkline. */
+  perDay: number[];
+  /** Tokens, only where the CLI reported them (`cliUsage`); ABSENT otherwise, never 0. */
+  tokens?: { input: number; output: number };
+  /** Dollar cost, only where a price was known; ABSENT otherwise, never 0. */
+  costUsd?: number;
+  /** Runs read for the fold, and whether the run cap cut the window. */
+  runsRead: number;
+  truncated: boolean;
+}
+
+// ── runs[] ──
+
+/**
+ * A run's computed liveness:
+ * - `waiting_on_you` — paused at an open gate or question the operator answers (`gate` says which);
+ * - `held` — paused and escalated (a failed floor, a judge that could not rule, a refused
+ *   hand-over: `gateKind: 'escalation'`), or paused with no open gate on record;
+ * - `stalled` — executing with no evidence (an event, unit output or a busy child process) for at
+ *   least `stallAfterMs`;
+ * - `quiet` — executing with no evidence for at least `quietAfterMs`;
+ * - `working` — executing with evidence inside `quietAfterMs`. Never claimed without evidence: a
+ *   run with no evidence on record at all reads `stalled` (or `quiet` when it began recently).
+ */
+export type SystemRunLiveness = 'waiting_on_you' | 'held' | 'stalled' | 'quiet' | 'working';
+
+export interface SystemRun {
+  runId: string;
+  title: string;
+  /** The engine's status (`SessionStatus`). */
+  status: string;
+  liveness: SystemRunLiveness;
+  /** Plain-words why ("waiting on you: plan approval", "no event for 42 min"). */
+  reason: string;
+  /** The cursor unit's phase (`phase_ref`, else `stage`); `null` before planning. */
+  phase: string | null;
+  /** The cursor unit's ord; `null` when none is in flight. */
+  unitOrd: number | null;
+  /** The seat on the cursor unit; `null` when none. */
+  seat: string | null;
+  /** ISO-8601 of the newest evidence of life (an event or a busy process); `null` when none is on
+   *  record. */
+  lastEventAt: string | null;
+  /** Where `lastEventAt` came from: the durable event log, the live relay, or a busy process. */
+  evidence: 'event_log' | 'relay' | 'process' | null;
+  /** ms since `lastEventAt`; `null` when there is none. */
+  quietForMs: number | null;
+  /** The thresholds the verdict used (from `workerStallMinutes`). */
+  quietAfterMs: number;
+  stallAfterMs: number;
+  /** The open gate or question, when the run waits on one. */
+  gate?: { interactionId: string | null; ord: number | null; kind: string | null; prompt: string | null };
+  /** ISO-8601 the run was launched, when known. */
+  createdAt: string | null;
+}
+
+// ── infra[] ──
+
+export type SystemInfraKey =
+  | 'daemon'
+  | 'gateway'
+  | 'broker'
+  | 'interactive'
+  | 'estate'
+  | 'bus'
+  | 'vault'
+  | 'skills'
+  | 'state_home'
+  | 'stores'
+  | 'seat_floor'
+  | 'disk'
+  | 'load';
+
+export interface SystemInfraRow {
+  key: SystemInfraKey;
+  label: string;
+  state: SystemState;
+  /** What the probe saw, in plain words. */
+  reason: string;
+  /** What fixes it; `null` when `ok` / `off`. */
+  remedy: string | null;
+  /** ISO-8601 of when this row's probe settled (or gave up). */
+  checkedAt: string;
+  /** How long the probe took, ms. */
+  durationMs: number;
+  /** The probe's own bound, ms (present on rows that spawn or dial). */
+  timeoutMs?: number;
+  /** The raw probe reading and the `/diagnostics` block(s) this row covers, verbatim
+   *  (daemon: `components`, `daemon`, `recentErrors`, `ping`, `warnings`; stores: `stores`;
+   *  skills: `skills`; state_home: `stateHome`; estate: `memoryStore`; vault: `vault`;
+   *  seat_floor: `rosterFile`, `hostBoundary`, `roleFindings`). */
+  details: Record<string, unknown>;
+}
+
+// ── governance[] ──
+
+export type SystemGovernanceKey =
+  | 'judges'
+  | 'floor_outcomes'
+  | 'qe_acceptance'
+  | 'gates_answered'
+  | 'dead_letters'
+  | 'steering_rules'
+  | 'findings'
+  | 'store';
+
+export interface SystemGovernanceCard {
+  key: SystemGovernanceKey;
+  label: string;
+  state: SystemState;
+  /** The headline number; `null` when the daemon cannot count it. */
+  value: number | null;
+  /** Counts behind the headline (floor outcomes by kind, gates by who…); absent when none. */
+  breakdown?: Record<string, number>;
+  /** Plain words: what the number means and where it came from. */
+  reason: string;
+  remedy: string | null;
+  /** Window start (unix millis) for the 7-day cards; absent on point-in-time cards. */
+  since?: number;
+  /** The `/diagnostics` facts this card covers, verbatim (store/dead_letters/findings:
+   *  `governance`; findings also `decisions` and the skills findings). */
+  details?: Record<string, unknown>;
+}
+
 // ── Memory proposal queue (DES-MEM-FACETED-001 §5.0, api-types 0.21.0) ─────────
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wicked-crew-api-types",
-  "version": "0.134.0",
+  "version": "0.137.0",
   "description": "The wire contract of the wicked-crew daemon's /api/v1 REST surface and /ws CoreEvent frames \u2014 types only, zero runtime",
   "type": "module",
   "types": "./index.d.ts",