wicked-crew-api-types 0.40.0 → 0.73.0

package/index.d.ts

@@ -84,7 +84,25 @@ export interface AuditEntry {
   [k: string]: unknown;
 }
 
-/** `GET /audit` — newest first, filterable by `?runId=` / `?action=` / `?limit=`. */
+/**
+ * `GET /audit`'s query (api-types 0.43.0 adds `since`). Every filter is optional and they
+ * compose (AND); an empty value is absent. A malformed `limit` or `since` answers 400.
+ */
+export interface AuditQuery {
+  runId?: string;
+  action?: string;
+  /** Max entries returned, newest first. Default 200, capped at 1000. */
+  limit?: number;
+  /**
+   * Inclusive lower bound on {@link AuditEntry.ts} (unix MILLIS): keep entries with
+   * `ts >= since`. Applied before `limit`. The "while you were away" read: a skin passes the
+   * operator's last-visit instant and gets what happened since, including `system` actors'
+   * actions (the stall watchdog's `run.stall.*` entries).
+   */
+  since?: number;
+}
+
+/** `GET /audit` — newest first, filterable by {@link AuditQuery} (`?runId=` / `?action=` / `?limit=` / `?since=`). */
 export interface AuditPage {
   entries: AuditEntry[];
 }
@@ -166,6 +184,8 @@ export type RoutingInfo =
 export interface HealthResponse {
   status: string;
   version: string;
+  /** The engine actor's answer (`"ok"`), or `"busy"` when the actor did not answer within ~1 s
+   *  (crew#471): the daemon serves while the engine is occupied — a large launch is planning. */
   ping: string;
   capabilities?: HealthCapabilities;
   /**
@@ -211,6 +231,12 @@ export interface HealthCapabilities {
    * on such a daemon.
    */
   seatChipOnCreate?: boolean;
+  /**
+   * `AgentSession.chat_id` is served on every run launched from a chat, terminal ones included
+   * (C1; crew ≥ the release carrying api-types 0.71.0). ABSENT on a daemon before the field — read
+   * as `false`: group such a daemon's runs one session per run.
+   */
+  runChatId?: boolean;
 }
 
 /** One `GET /health.warnings[]` entry (additive; wicked-core#411 / wicked-crew#497). */
@@ -289,12 +315,18 @@ export interface AgentSession {
    *
    *   - `'delivered'` — a PR was opened for this run (by the deliver phase, or post-hoc via
    *     `POST /runs/:id/deliver`); `deliverUrl` carries the PR URL.
+   *   - `'pushed'`    — (api-types 0.69.0, N1) the run's branch was PUSHED and that is the whole
+   *     delivery: no pull request could be opened because the origin is not a GitHub host gh can
+   *     resolve (a local path, SSH, GitLab, ADO, Gitea…). `deliverBranch` + `deliverRemote` say
+   *     what is where. Nothing is left to lift, so no post-hoc deliver is offered (`POST
+   *     /runs/:id/deliver` answers 409); opening the pull/merge request is the forge's, by hand.
    *   - `'stranded'`  — reviewable work nobody lifted, reached two ways: a COMPLETED repo-scoped
    *     run with no recorded PR whose worktree still exists on disk AND carries work (derived
    *     honestly for OLD runs too — records written before this field existed strand the same
-   *     way); OR (crew#418) a run whose deliver phase hit a LIFT collision — a rebase conflict or
-   *     non-fast-forward push — which the daemon reinterprets from the engine's `failed` to
-   *     `completed`+`stranded`: its work is committed on the `wicked/<id>` branch (the engine
+   *     way); OR (crew#418) a run whose deliver phase hit a LIFT collision — a rebase conflict
+   *     (a push the remote REFUSED no longer strands: since 0.69.0 it parks the run at the
+   *     engine's deliver-refusal gate, N4) — which the daemon reinterprets from the engine's
+   *     `failed` to `completed`+`stranded`: its work is committed on the `wicked/<id>` branch (the engine
    *     reaps the now-clean worktree, but never the branch), recoverable via `POST /runs/:id/
    *     deliver`, which stands a throwaway worktree back up from that branch to lift it.
    *   - `'vacuous'`   — a COMPLETED repo-scoped run whose surviving worktree carries NO
@@ -317,7 +349,7 @@ export interface AgentSession {
    * FAILURE of a deliver phase is not spelled here; it is `units[].status === 'rejected'`
    * plus `denial_reason` (crew#318's message), both already on the list wire.
    */
-  delivery?: 'delivered' | 'stranded' | 'vacuous' | 'none';
+  delivery?: 'delivered' | 'pushed' | 'stranded' | 'vacuous' | 'none';
   /**
    * The delivered PR's URL (crew#393; api-types 0.18.0) — present exactly when
    * `delivery === 'delivered'`; absent otherwise (absence is the one spelling, never `null`).
@@ -328,6 +360,13 @@ export interface AgentSession {
    * idempotent against the existing branch) and `'none'` after it is cleaned up.
    */
   deliverUrl?: string;
+  /** The pushed run branch (api-types 0.69.0, N1) — present exactly when `delivery === 'pushed'`. */
+  deliverBranch?: string;
+  /**
+   * The remote the branch was pushed to (api-types 0.69.0, N1), with any URL userinfo removed —
+   * present exactly when `delivery === 'pushed'`. May be a filesystem path (a local bare origin).
+   */
+  deliverRemote?: string;
   /**
    * The campaign this AD-HOC run was attached to at launch (`LaunchRunBody.campaignId`;
    * wicked-studio#27, api-types 0.19.0) — daemon-joined at DTO assembly on `GET /runs` and
@@ -419,6 +458,15 @@ export interface AgentSession {
   /** Wave 6 (F-7R2-006): the seats BENCHED for this run — never convened, never a failover or
    *  judge target. Absent (never `[]`) when none / on an older engine. */
   benched_seats?: BenchedSeat[];
+  /**
+   * The run's APPROVED INTENT AMENDMENTS, in the order a human decided them (wicked-core#555;
+   * additive, engine ≥ the core-ts release after 0.7.30) — the `amend_intent` arm of a gate
+   * ({@link GateDecision.action}). Each amendment is appended to every unit at or after the
+   * gate's cursor, so the acceptance list each LATER EVALUATOR is handed changed with the
+   * decision. Render them beside the run's original intent: this is what was withdrawn or
+   * changed, and when. ABSENT (never `[]`) on an unamended run and on an older engine.
+   */
+  intent_amendments?: IntentAmendment[];
   /** crew#661: the declared skills this run's phases ran WITHOUT (the published skills snapshot did not
    *  hold them when the launching subsystem armed) — the run proceeded DEGRADED, and says so here.
    *  ABSENT (never `[]`) when the run launched fully armed, and on a daemon before this field. */
@@ -450,6 +498,85 @@ export interface AgentSession {
    * this field.
    */
   chat_grounded?: boolean;
+  /**
+   * The chat this run was launched from (`LaunchRunBody.chatId`; C1, api-types 0.71.0) — on EVERY
+   * run, terminal ones included, and after a daemon restart (read back from the `run.launched`
+   * trail entry). ABSENT — never `null` — when the run was not launched from a chat, or on a daemon
+   * before the field: check `GET /health.capabilities.runChatId` before grouping runs by chat.
+   */
+  chat_id?: string;
+  /**
+   * The engine's plan state (wicked-core `TeamPlanState`, DES-TEAMING-002 §8.4-§8.6; api-types
+   * 0.46.0 types the engine field) — present on a run launched from a PLAN or a PRESET, ABSENT on
+   * every other run (a registered def, the free-text planner) and on a team run before its launch
+   * is scored. Engine-computed; typed here only as far as a skin reads it. Read the run's kind from
+   * {@link AgentSession.run_identity}, which is resolved from this.
+   */
+  team_plan?: TeamPlanState;
+  /**
+   * What this run IS (seam X2; api-types 0.46.0) — daemon-resolved at DTO assembly on BOTH
+   * `GET /runs` and `GET /runs/:id` from the engine's own record (the plan state above, else the
+   * launch's recorded `sessionStarted`), never from the run's phase sequence. Always present on a
+   * 0.46.0+ daemon; ABSENT from an older one. `system` replaces a skin's own list of system
+   * workflow ids.
+   */
+  run_identity?: RunIdentity;
+}
+
+/**
+ * The fields of the engine's `TeamPlanState` a skin reads (the engine sends more — every field is
+ * engine-computed and additive).
+ */
+export interface TeamPlanState {
+  /** The last plan rev assigned (accepted or held). `0` = none yet. */
+  rev: number;
+  /** The last ACCEPTED plan rev. `0` = no plan accepted yet. */
+  accepted_rev: number;
+  /** The preset the launch named. ABSENT on a user plan. */
+  preset?: string;
+  /**
+   * (wicked-core#633, DES-TEAMING-002 X1; api-types 0.47.0) PRESENT while the run's PA is scoping
+   * its launch plan — a creator plan or preset that declared no `touch` set. Until the `pa-scope`
+   * unit's boundary decides the plan, the run's only unit is `pa-scope` (plan rev 1): what the run
+   * will contain is not known yet. ABSENT once the plan is scoped (or when none needed scoping).
+   */
+  scope?: TeamPlanScopeHold;
+}
+
+/** The launch plan the PA is scoping (the engine's `ScopeHold`). */
+export interface TeamPlanScopeHold {
+  /** The launch plan as authored (the preset's steps or the user's plan), without `pa-scope`. */
+  plan: { steps: TeamPlanStep[] } & Record<string, unknown>;
+  /** The run has no repo: the PA rates the risk (`RISK`) instead of declaring a touch set. */
+  unbound: boolean;
+  /** The scope step's `SCOPE` / `RISK` lines once its turn folds; ABSENT until then. */
+  answer?: { ord: number; attempt: number; by: string; lines: string };
+}
+
+/**
+ * What a run is (seam X2; api-types 0.46.0), resolved by the daemon from the engine's record.
+ *
+ *   - `'preset'`    — launched from a preset; `name` is the preset.
+ *   - `'user_plan'` — launched from a user-composed plan (the engine's per-run `<run>:plan-<rev>`
+ *                     def); `name` is `null`.
+ *   - `'workflow'`  — launched on a registered workflow def; `name` is its id (a crew-composed
+ *                     per-run delivery/floor def reads as its base).
+ *   - `'free_text'` — no workflow and no plan: the free-text planner; `name` is `null`.
+ *   - `'unknown'`   — the daemon has no record of what the launch named (a run predating the
+ *                     engine's event log, or an engine without the log read); `name` is `null`.
+ */
+export interface RunIdentity {
+  kind: 'preset' | 'user_plan' | 'workflow' | 'free_text' | 'unknown';
+  /** The preset or workflow name — `null` unless `kind` is `'preset'` or `'workflow'`. */
+  name: string | null;
+  /** `kind === 'user_plan'`, spelled out. */
+  user_plan: boolean;
+  /**
+   * A machine-owned run (chat, onboarding, the interactive document and video seams, …): skins keep
+   * it off delivery surfaces. Keyed by `name` against the daemon's ONE list — the same list that
+   * stamps `WorkflowDef.is_system` on `GET /workflows`.
+   */
+  system: boolean;
 }
 
 /** An ordered unit of work within a run (`WorkUnit`). */
@@ -494,6 +621,34 @@ export interface WorkUnit {
    * planned before the field existed, and on an older engine.
    */
   base_skill_ref?: string | null;
+  /**
+   * The phase-catalog entry this unit instantiates (`build`, `review`, …) when it was planned from
+   * a catalog-composed plan — a preset or a user plan (wicked-core `WorkUnit.catalog`,
+   * DES-TEAMING-002 T3; api-types 0.46.0 types the engine field). ABSENT on every other unit.
+   */
+  catalog?: string;
+  /** TRUE on a unit of a TEAM run (planned from the per-run plan def); ABSENT otherwise. Engine field. */
+  team_run?: boolean;
+  /**
+   * TRUE when this unit's phase declared `requires_capture_report` (wicked-core#535 / BC-80) —
+   * carried from the def at plan time. ABSENT on every other unit and on an older engine.
+   */
+  requires_capture_report?: boolean;
+  /**
+   * What the capture phase REPORTED, read from its output marker by the gate fold
+   * (wicked-core#535 / BC-80): `derived` learnings, `submitted` proposals, `failed` submissions.
+   * Present once a capture unit emitted a well-formed marker — whether it passed or denied, so the
+   * counts are readable beside the denial. ABSENT on every other unit, on a capture unit whose
+   * marker was MISSING (that denies; the denial is the record), and on an older engine.
+   */
+  capture_report?: CaptureReport;
+}
+
+/** The counts a capture phase reported (`WorkUnit.capture_report`; wicked-core#535). */
+export interface CaptureReport {
+  derived: number;
+  submitted: number;
+  failed: number;
 }
 
 /** A run plus its ordered units (`SessionView`) — the shape `GET /runs` returns. */
@@ -626,9 +781,29 @@ export interface RosterSeat {
    * while every ballot failed. Absent = the probe decided (and since 0.36.0 the probe itself needs
    * a credential-SHAPED file, never mere presence).
    */
-  auth_source?: 'seat-stderr';
-  /** Present with `auth_source: 'seat-stderr'`: the seat's own words, bounded. */
+  auth_source?: 'seat-stderr' | 'probe';
+  /** Present with `auth_source: 'seat-stderr'`, and with `probe` when it read signed out: the
+   *  seat's own words, bounded. */
   auth_evidence?: string;
+  /**
+   * Present with `auth_source: 'probe'` (crew#630): ISO-8601 of the seat's own auth-status check
+   * (`claude auth status`, `codex login status`) under the seat's configuration home, which then
+   * decided `auth` and `signed_in` over the credential file. The daemon re-checks in the
+   * background (a signed-in answer after 5 minutes, any other after 30 s). A probed seat whose
+   * check has not answered yet reads `unknown`, never `signed_in` off its file.
+   */
+  probed_at?: string;
+  /**
+   * How far `auth` was VERIFIED (crew#645): `live` — the seat answered an authenticated request, or
+   * refused one for want of a credential (a status command reads the stored login, so an expired
+   * OAuth login still reads signed in there; the daemon makes one short live request when it says
+   * signed in); `status` — only the status command answered (the live request could not tell);
+   * `unverified` — nothing asked the seat (it has no status command, or its check has not answered
+   * or could not tell). Optional on the wire: a daemon before it sends none.
+   */
+  login_check?: 'live' | 'status' | 'unverified';
+  /** Present unless `login_check` is `live`: why, in the operator's words ("login unverified — …"). */
+  login_note?: string;
   /** Present when `auth` is `not_required`: the free tier the seat answers on. */
   free_tier?: string;
   /**
@@ -659,9 +834,33 @@ export interface RosterSeat {
    * a reader must tolerate absence today.
    */
   council_bench?: RosterSeatCouncilBench;
+  /**
+   * (core#581) Present on a seat whose ACP config pins `verified_version`, once the daemon's
+   * probe has answered: the build the seat's input-governance admission was proven against and
+   * what the binary reports now. `matched: false` with `governanceClaimed: true` means the engine
+   * fails the seat's ACP governance closed at every spawn.
+   */
+  version_pin?: SeatVersionPin;
   [k: string]: unknown;
 }
 
+/**
+ * One pinned seat's `--version` reading (core#581): `RosterSeat.version_pin` and
+ * `AcpCliDiagnostics.versionPin`. Read the way the engine's spawn-time check reads it: the pin
+ * matches only the first line of `--version`, trimmed; `observed` is the first non-empty line,
+ * `null` when the binary did not answer.
+ */
+export interface SeatVersionPin {
+  cli: string;
+  binary: string;
+  pinned: string;
+  observed: string | null;
+  matched: boolean;
+  governanceClaimed: boolean;
+  /** The operator-facing reason when a governed seat's pin does not hold; else `null`. */
+  disclosure: string | null;
+}
+
 /** `RosterSeat.council_bench` (api-types 0.35.0).
  *  @deprecated ABSENT from crew 0.7.36 (see {@link RosterSeat.council_bench}); removed one minor later. */
 export interface RosterSeatCouncilBench {
@@ -679,6 +878,62 @@ export interface RosterSeatCouncilBench {
   window_ms: number;
 }
 
+/**
+ * `GET /roster/record?days=N` (api-types 0.52.0): each seat's record over the last N days (default 7,
+ * max 30), folded from the runs' durable event logs (studio's weekly 1:1 per agent). Nothing new is
+ * stored; the window is by event time. A unit's seat is `unitDistributed.cli` (moved by
+ * `unitReassigned.newCli`), else the unit row's `assigned_cli`. 503 when the engine has no event-log
+ * read binding (a missing binding is not an empty week).
+ */
+export interface SeatRecordResponse {
+  days: number;
+  /** Window start, unix MILLIS. */
+  since: number;
+  /** Window end (the read time), unix MILLIS. */
+  until: number;
+  /** Runs whose event log was read. */
+  runsRead: number;
+  /** True when the daemon's per-read run cap cut the read (the oldest runs in the window were skipped). */
+  truncated: boolean;
+  /** Seats with any record in the window, by key. A roster seat absent here had no units and no bench. */
+  seats: SeatRecord[];
+}
+
+/** One seat's week (`SeatRecordResponse.seats[]`). */
+export interface SeatRecord {
+  /** The roster key. */
+  cli: string;
+  /** Distinct units the seat was dispatched on in the window. */
+  units: number;
+  /** Units of this seat with a gate evaluation in the window. */
+  gated: number;
+  /** Of `gated`: the FIRST evaluation passed (`gateEvaluated.combined` and no `denial`). */
+  firstPass: number;
+  /** Units the seat ran first that were dispatched again (a retry or a send-back) or given a `unitReworkAmended`. */
+  rework: number;
+  /** Distinct units that went quiet (`workerStalled`, engine or daemon watchdog) while the seat ran them. */
+  stalls: number;
+  /** Runs in the window whose `benched_seats` names the seat. */
+  benched: number;
+  /** Bench reason → runs. */
+  benchReasons: Record<string, number>;
+  /** Summed `cliUsage.costUsd` where a price was known; `null` when no usage frame carried one (never `0` for "unknown"). */
+  costUsd: number | null;
+  /** Usage frames that carried a price. */
+  costedUsage: number;
+  /** Phase (`phase_ref`, else `stage`) → the same counts, so a move can name the phase. */
+  byPhase: Record<string, SeatPhaseRecord>;
+}
+
+/** One phase's slice of a {@link SeatRecord}. */
+export interface SeatPhaseRecord {
+  units: number;
+  gated: number;
+  firstPass: number;
+  rework: number;
+  stalls: number;
+}
+
 /** A seat's auth reading (`RosterSeat.auth`; api-types 0.35.0). */
 export type SeatAuth = 'signed_in' | 'signed_out' | 'not_required' | 'unknown';
 
@@ -774,8 +1029,39 @@ export interface GateDecision {
    * `unitDispatched{attempt: last + 1}`); requires `approve: false` — a disagreement between
    * `action` and `approve` answers 400, a gate with no creator phase before it 409. An older
    * daemon's strict schema rejects the key with a 400 — omit it against such servers.
+   *
+   * The ESCALATION arms (additive; wicked-core#469 / #467, engine ≥ the core-ts release after
+   * 0.7.30): all require `approve: true` and take no `amend` / `amendScope` / `plan` (a 400
+   * otherwise). `'extend'` | `'targeted'` | `'accept_partial'` answer the escalation gate of a
+   * repo-checks floor that did not finish (`gateEscalated.denialSource: 'repo_checks_timeout'`):
+   * the engine re-runs the floor on the tree as it stands — the seat does not run again — with
+   * every check under 2× its bound, with the repo's declared `test_targeted` in place of the full
+   * test set (no targeted command ⇒ the test set is waived), or with the checks that did not
+   * finish waived; the re-run goes through the ordinary gate and waived checks are named in
+   * `gateEvaluated.floorNote`. `'accept_suggestion'` answers an evaluator's worktree-guard denial
+   * whose edit was restored and pinned (`gateEscalated.suggestionRef`): the engine applies the
+   * pinned edit and rewinds to the creator (`unitReworkAmended{scope: 'accept_suggestion'}`).
+   * The engine refuses each at any other gate — a 409 — and the gate stays open.
+   *
+   * `'amend_intent'` (additive; wicked-core#555, engine ≥ the core-ts release after 0.7.30)
+   * approves the gate AND AMENDS THE RUN'S INTENT: `amend` carries what the acceptance list now
+   * says (required, non-empty), `approve: true`, and no `amendScope` — the scope IS every unit at
+   * or after the cursor, which is what makes it reach the LATER EVALUATOR. Before it, nothing
+   * amended the list an evaluator is handed, so a mid-run descope could only end in a relaunch.
+   * The engine appends the text to those units' descriptions, records it on the run
+   * (`AgentSession.intent_amendments`) and emits `intentAmended`. Refused at a plan or team gate,
+   * and with empty text — a 409 with the gate left open.
    */
-  action?: 'approve' | 'request_changes' | 'reject';
+  action?:
+    | 'approve'
+    | 'request_changes'
+    | 'reject'
+    | 'edit_plan'
+    | 'extend'
+    | 'targeted'
+    | 'accept_partial'
+    | 'accept_suggestion'
+    | 'amend_intent';
   /**
    * Where an approve's `amend` lands (api-types 0.38.0, additive; same release as `action`).
    * Absent = `'cursor'` (today: the gated unit's description). `'creator'` — the first creator
@@ -784,6 +1070,38 @@ export interface GateDecision {
    * Identical text already present on the target is not appended twice.
    */
   amendScope?: 'cursor' | 'creator';
+  /**
+   * Approve a `plan_approval` gate WITH AN EDIT (DES-TEAMING-002 §8.6, seam T3; additive; needs an
+   * engine whose addon carries `Core.supportsPlanLaunch`). The edited plan: the engine publishes
+   * `plan.proposed{by:"human", kind:"edit"}`, floor-fills it (phases below the floor are ADDED,
+   * never refused) and accepts it as the next `plan_rev` — or refuses it (`plan.refused`) and
+   * re-opens the gate under a new `gate_id`, answering `awaiting_human`. Requires `approve: true`
+   * and `action` omitted or `'edit_plan'`; `amend` / `amendScope` do not apply. A plain approve
+   * (no `plan`) releases the held plan as it is; `approve: false` rejects (cancels).
+   */
+  plan?: LaunchPlan;
+  /**
+   * The gate this decision answers — the unit `ord` its open gate paused before, as `GET
+   * /runs/:id/gate` served it (api-types 0.44.0, additive). When present the daemon compares it to
+   * the run's open gate and answers **409** `{ error, code: 'gate_changed', openOrd }` on a
+   * mismatch, confirming nothing: the gate was answered elsewhere or replaced while the decision
+   * waited (a skin's undo window). When the daemon cannot tell which gate is open it answers
+   * **409** `{ error, code: 'gate_unknown' }` — refresh the gate and decide again. Absent = today's
+   * behaviour (no gate check).
+   */
+  ord?: number;
+}
+
+/**
+ * A USER-COMPOSED plan (DES-TEAMING-002 §8.4, seam T3): ordered `steps[]` over the phase catalog,
+ * the predicted `touch` set (the intent score's input: a plan with a creator step and no `touch`
+ * scores 100, "no declared scope") and an optional MANUAL-mode floor `override` (refused in auto
+ * mode). A step's `id` defaults to its catalog id. The ENGINE validates every key.
+ */
+export interface LaunchPlan {
+  steps: Array<{ catalog: string; id?: string | undefined; [k: string]: unknown }>;
+  touch?: string[];
+  override?: TeamPlanOverride;
 }
 
 /**
@@ -1100,6 +1418,22 @@ export type WorkerStallEscalatedFrame = {
   escalations?: number;
   /** outcome `failed`: bounded excerpt of what the recovery call threw. */
   error?: string;
+  /**
+   * Why the watchdog did not do a plain reassign (crew#638 / #581 / #580; additive, absent on older
+   * daemons): `tool_unit` — the cursor is the engine's own command, nothing to fail over to;
+   * `evaluating` — the worker returned and its gate evaluation is in flight, a reassign would start
+   * a second creator; `evaluator_distinct` — every other seat is one evaluator ≠ creator forbids
+   * (see `avoided`), so the unit was left for a human; `no_output` (outcome `exhausted`) — the
+   * reassigned seat produced nothing past a startup banner.
+   */
+  reason?: 'tool_unit' | 'evaluating' | 'evaluator_distinct' | 'no_output';
+  /**
+   * The seats the failover pick excluded under evaluator ≠ creator (crew#638; additive): a
+   * creator cursor avoids the run's evaluator seats, an evaluator cursor the seats that built its
+   * work, an `evaluator_distinct`-routed unit the seat it was routed away from. Present on an `ok`
+   * reassign that skipped one and on a `reason: 'evaluator_distinct'` notify; absent otherwise.
+   */
+  avoided?: string[];
 };
 
 export interface RecordedEvent extends CoreEvent {
@@ -1998,10 +2332,12 @@ export interface UnitReworkAmendedEvent {
    * 0.7.27): `'cursor'` — the gated unit, today's approve-with-steer (`GateDecision.amendScope`
    * absent or `'cursor'`); `'creator'` — the first creator phase at/after the cursor
    * (`amendScope: 'creator'`); `'request_changes'` — the creator phase the gate rewound to, and
-   * `amendment` then carries the evaluator's full findings + the operator's note. ABSENT on an
-   * engine before the field — read as `'cursor'`.
+   * `amendment` then carries the evaluator's full findings + the operator's note;
+   * `'accept_suggestion'` (wicked-core#467) — the same rewind after the operator adopted the
+   * evaluator's pinned edit, and `amendment` names it. ABSENT on an engine before the field — read
+   * as `'cursor'`.
    */
-  scope?: 'cursor' | 'creator' | 'request_changes';
+  scope?: 'cursor' | 'creator' | 'request_changes' | 'accept_suggestion';
 }
 
 /** P2 — a worker's ApplyStepResult arrived and output is ready to be gated. Fires before GateDecided.
@@ -2119,6 +2455,16 @@ export interface UnitDistributedEvent {
   degraded_reason?: string | null;
 }
 
+/** One APPROVED INTENT AMENDMENT (`AgentSession.intent_amendments`; wicked-core#555). */
+export interface IntentAmendment {
+  /** The human's own words — what the run's acceptance list now says. */
+  text: string;
+  /** The gate's cursor unit `ord`: the first unit the amendment reached. */
+  ord: number;
+  /** When it was decided, unix millis. */
+  at: number;
+}
+
 /** One seat the wave-6 engine BENCHED for a run (`AgentSession.benched_seats`, F-7R2-006): never
  *  convened, never a failover or judge target, named in `unitDistributed.degradedReason`. */
 export interface BenchedSeat {
@@ -2618,6 +2964,30 @@ export interface SkillsManifestResponse {
      *  `recorded.reasons` is `null` for a row written before per-reason portability (0.34.0). */
     drift?: SnapshotRowDrift[];
   } | null;
+  /**
+   * The wicked-garden plugin INSTALLED on this host right now (wicked-studio#388) — so a surface
+   * can say when the daemon's baseline, and therefore every snapshot published from it, is behind
+   * the operator's install. `null` = no plugin is installed (the unseeded case the 503 covers);
+   * absent on a daemon older than the release carrying it. Compare `installed.baseline` with
+   * `manifest.baseline`: different = Refresh baseline, then Publish.
+   */
+  installed?: InstalledPlugin | null;
+}
+
+/** `SkillsManifestResponse.installed` — the live plugin's identity (wicked-studio#388). */
+export interface InstalledPlugin {
+  source: { kind: SkillSourceKind; path: string; plugin_version: string };
+  /** HEAD sha for a `checkout` source; `null` otherwise (or when git could not answer). */
+  git_sha: string | null;
+  /**
+   * The content hash of the INSTALLED bundle, comparable with `SkillManifest.baseline` — the same
+   * identity `POST /skills/refresh-baseline` decides on, never the version string (two installs of
+   * one version with different bytes are two baselines). `null` when the bundle could not be read,
+   * and then `unreadable` says why: a comparison crew could not make is stated, not reported as
+   * agreement.
+   */
+  baseline: string | null;
+  unreadable: string | null;
 }
 
 /** The identity of a portability-rule table (api-types 0.36.0, F-083): its version and the
@@ -3247,6 +3617,14 @@ export interface TestingReconResponse {
   /** Present only when the fan was campaign-registered with a `projectId` and filing a sibling
    *  into the project failed — the runs are LIVE; re-attach via POST /projects/:id/members. */
   projectAttachError?: string;
+  /**
+   * `true` on a **202**: the engine was still launching the fan when the daemon answered (crew#471 —
+   * it plans every node's units before it replies, which held the POST for minutes). The `runIds`
+   * are final (deterministic node ids) and can be followed now; the trail entries and project
+   * filing land when the engine answers, and a late refusal is audited as `campaign.launch_failed`.
+   * Absent on a 201.
+   */
+  launching?: true;
 }
 
 // ── The governed test-authoring launch (wave 6; api-types 0.36.0) ──────────────────────────────
@@ -3421,6 +3799,21 @@ export interface LaunchRunBody {
   repoRef?: string;
   /** Built-in workflow id (`feature` | `bug` | `migration`); omit for free-text single-unit mode. */
   workflow?: string;
+  /**
+   * A USER-COMPOSED plan (DES-TEAMING-002 §8.4, seam T3; additive; needs an engine whose addon
+   * carries `Core.supportsPlanLaunch` — an older one is refused with a 501, never run unplanned).
+   * The ENGINE publishes `plan.proposed{by:"human"}` before any unit runs, scores and floor-fills
+   * it, and holds it at a `plan_approval` gate (`awaiting_human{gate_kind:"plan_approval"}`) when
+   * the approval matrix says so: always in manual mode, and in auto mode when high risk (band
+   * 70-100 or destructive). Mutually exclusive with `workflow` (a plan or a preset).
+   * A creator plan with NO `touch` set — and every creator preset — is scoped by the run's PA
+   * first (wicked-core#633, X1): rev 1 is the read-only `pa-scope` step alone (unit ord 1), the
+   * scored plan is rev 2 proposed by the PA seat (`plan.proposed{by:<PA seat>}`), and its
+   * `plan_approval` gate, when one opens, is at ord 2. Declare `touch` to be scored at launch.
+   * `deliver: "pr"` with a plan (api-types 0.42.0, T8) hands the engine the deliver step, which it
+   * appends to the plan and puts in the floor; `deliver` omitted with a plan means `"none"`.
+   */
+  plan?: LaunchPlan;
   /**
    * The project to file this run into (DES-PROJECT-001 §2.2). The `crew.run` membership is
    * attached atomically with the launch record; an unknown or archived project fails the launch
@@ -3532,6 +3925,29 @@ export interface LaunchRunBody {
   actor?: string;
 }
 
+/**
+ * One issue a launch's intent linked (`#N`, `owner/repo#N`, an issue URL) and whether the daemon
+ * could read it (crew#627, additive). A governed worker cannot read GitHub, so for a workflow launch
+ * the daemon reads each linked issue under its own identity (`gh issue view`, at most 5) and appends
+ * the title, state, body and comments to the problem the engine plans from, inside a marked block.
+ * `resolved: false` names why (`error`) — shown, never skipped.
+ */
+export interface LinkedIssue {
+  ref: string;
+  resolved: boolean;
+  /** Present when `resolved`. */
+  title?: string;
+  /** Present when not `resolved`: why, in one line. */
+  error?: string;
+}
+
+/** The `POST /runs` 201 body. `linkedIssues` (crew#627, additive) is present when the intent of a
+ *  workflow launch named at least one issue; absent otherwise and on an older daemon. */
+export interface LaunchRunResponse {
+  runId: string;
+  linkedIssues?: LinkedIssue[];
+}
+
 /**
  * Body for `PUT /runs/:id/guidance` (DES-UX-002 §7.2, CREW-UX-7; api-types 0.9.0) — upsert the
  * run's ONE durable operator guidance note. `text: ''` CLEARS the note (the DTO field returns
@@ -3663,12 +4079,20 @@ export interface PhaseDef {
    *  run `cmd` directly. */
   executor?: PhaseExecutor;
   /** Per-phase agent instructions folded into the unit prompt by the engine (core PhaseDef.instructions,
-   * Option<String>). Absent = no extra instruction. Mirrors of core drop-ins that carry it (e.g.
-   * survey-repo) MUST reproduce it verbatim or the runtime def diverges from core's — FINDING-011. */
+   * Option<String>). Absent = no extra instruction. Mirrors of core drop-ins that carry it MUST
+   * reproduce it verbatim or the runtime def diverges from core's — FINDING-011. */
   instructions?: string | null;
   gate_type: GateType | null;
   gate: GateSpec;
   executes_code: boolean;
+  /**
+   * The phase must REPORT what it captured (wicked-core#535 / BC-80; additive, engine ≥ the
+   * release carrying it — an older engine's strict def parser refuses the key). Its output must
+   * carry `wicked-capture-report {"derived": N, "submitted": M, "failed": K}`; a missing marker, a
+   * failed submission and proposals derived but never submitted each deny the unit into the human
+   * gate. An honest `0/0/0` passes. Absent/false ⇒ not parsed (every phase but `capture`).
+   */
+  requires_capture_report?: boolean;
   verified_evidence: boolean;
   required_deliverables: string[];
   depends_on: string[];
@@ -3695,6 +4119,29 @@ export interface WorkflowDef {
   base_skill_ref?: string | null;
 }
 
+/** A drop-in workflow definition the ENGINE refused, with the engine's own reason (wicked-crew#718). */
+export interface RefusedWorkflow {
+  /** The def's id, as its file named it. */
+  id: string;
+  /**
+   * wicked-core's refusal, verbatim — e.g. `gate evaluates nothing: write-a-note — the phase
+   * declares executes_code but pins no validator and has no human gate, so its gate would approve
+   * with nothing checked.`
+   */
+  reason: string;
+}
+
+/**
+ * `GET /workflows` (wicked-crew#718). `workflows` is what the ENGINE accepted — the only defs a
+ * launch can name. `unavailable` is the drop-ins it refused, with its reason, so a def that cannot
+ * be launched is NAMED rather than offered and then 400'd `unknown workflow`. Absent on a daemon
+ * older than the release carrying it (read it as `[]`).
+ */
+export interface WorkflowsResponse {
+  workflows: WorkflowDef[];
+  unavailable?: RefusedWorkflow[];
+}
+
 /** Top-level requirements_graph.json artifact (schema 1.0.0). */
 export interface DomainGraph {
   metadata: { schema_version: string; migration_mode: string; source?: string };
@@ -3768,6 +4215,24 @@ export interface CodeGraphData {
   totals?: { nodes: number; edges: number; files: number };
 }
 
+/**
+ * `GET /api/v1/repos/:id/deliver-target` (R3) — where a delivering launch on this repo would push,
+ * read by the same origin preflight the deliver gate card uses (crew#730). `sentence` is the gate's
+ * own target sentence for a run not yet started ("the run branch"); show it verbatim.
+ *  - `github`  — a github.com origin; `githubRepo` is its `owner/repo` on github.com or
+ *                ssh.github.com, and `null` on another `*.github.com` host (gist, api);
+ *  - `local`   — a filesystem path or `file://` URL: no pull request can be opened against it;
+ *  - `other`   — another host: a pull request opens only if gh resolves it as a GitHub host;
+ *  - `none`    — the checkout has no `origin` remote: the push will fail;
+ *  - `unknown` — the origin could not be read; the sentence claims nothing either way.
+ */
+export interface DeliverTargetResponse {
+  repo: string;
+  origin: 'github' | 'local' | 'other' | 'none' | 'unknown';
+  githubRepo: string | null;
+  sentence: string;
+}
+
 /**
  * `GET /repos/:id/graph` → 200 (api-types 0.35.0, F-2R2-005). `graph: null` = the repo's code
  * graph has not been built (nothing at its registered graph path) — and `reason` says WHY, so a
@@ -3800,6 +4265,12 @@ export interface GitContributor {
 export interface SystemSettings {
   /** Max nodes returned by wicked-estate graph-view (default 150). */
   graphNodeLimit: number;
+  /**
+   * The watch registry's operator settings (TR-W5a, api-types 0.73.0): only `enabled` and
+   * `threshold` of a shipped entry, and the LLM lane switch. A `watch` patch needs a human actor
+   * (a worker's bearer is refused 403); the daemon stamps who changed what and when.
+   */
+  watch?: WatchSettings;
   /**
    * Base directory for the ENGINE-OWNED worker CLI config homes (the claude worker home is
    * `<root>/claude`). The daemon applies it as env `WICKED_WORKER_HOME` at boot and on every
@@ -3847,6 +4318,18 @@ export interface SystemSettings {
    * `base_skill_refused`); the finding is an `error`.
    */
   baseSkillPolicy?: 'warn' | 'require';
+  /**
+   * The DELIVER IDENTITY (crew#549; additive): the GitHub login the deliver phase must push as.
+   * The deliver script reads `gh api user` AND asks git which credential it would use for the
+   * remote's host, and REFUSES — before anything is staged, committed or pushed — when either
+   * disagrees with this login (or, with nothing configured, when those two disagree with each
+   * other). `''`/absent ⇒ the `GH_ACCOUNT` env var decides, and unset there means the phase
+   * pushes as whatever login gh holds, said aloud on the gate card.
+   *
+   * A LOGIN ONLY — never a token. The credential itself stays in gh's keyring or in the daemon's
+   * `GH_TOKEN`; `GET /settings` returns this login and no secret ever.
+   */
+  deliverIdentityLogin?: string;
   /**
    * The stall watchdog's DETECTION threshold (crew#287; api-types 0.18.0 — previously a
    * daemon-local extension): minutes a run in `executing` may go without ANY engine event on the
@@ -3992,6 +4475,60 @@ export interface ElicitationResponse {
   content?: { response: string };
 }
 
+// ── Presets (DES-TEAMING-002 §8.4, seam C2) — saved phase selections ──────────
+
+/**
+ * One plan step: the catalog entry it instantiates (`understand`, `build`, …), its phase id,
+ * and the step fields the catalog lets a step set (`gate`, `validator_pin`, `depends_on`, …).
+ * The engine validates it (`plan::compose`); unknown keys are refused there.
+ */
+export interface PresetStep {
+  catalog: string;
+  id: string;
+  [k: string]: unknown;
+}
+
+/**
+ * A preset (`GET /presets`, `PUT /presets/:name`): a named phase selection stored in the core
+ * store. A launch's `workflow` names one (`POST /runs {workflow}`); a project-scoped preset
+ * shadows a global one of the same name for that project. Built-ins carry
+ * `created_by: "builtin"` and cannot be deleted.
+ */
+export interface Preset {
+  name: string;
+  /** `"global"` or `"project:<id>"`. */
+  scope: string;
+  steps: PresetStep[];
+  /** `"builtin"` for a seeded built-in; otherwise the writing surface. */
+  created_by: string;
+  /** Unix millis. */
+  updated_at: number;
+  /**
+   * A machine-owned preset (`chat`, `onboarding`, …): keep it off delivery surfaces and the work-mode
+   * selector. The preset's half of the one name-keyed classification that stamps
+   * `WorkflowDef.is_system` and `run_identity.system` (DES-TEAMING-002 §11.3). The daemon stamps it
+   * on every preset it serves (api-types 0.48.0); absent from an older daemon.
+   */
+  system?: boolean;
+  [k: string]: unknown;
+}
+
+/** `PUT /presets/:name` body. `projectId` absent ⇒ a global preset. */
+export interface PutPresetBody {
+  steps: PresetStep[];
+  projectId?: string;
+}
+
+/** `GET /presets` (`?projectId=`) — the presets a launch in that project sees, by name. */
+export interface PresetListResponse {
+  presets: Preset[];
+}
+
+/** `GET /presets/:name`, `PUT /presets/:name`. */
+export interface PresetResponse {
+  preset: Preset;
+}
+
 // ── Projects (DES-PROJECT-001) — the experience-plane keystone ─────────────────
 
 /** Project lifecycle: `active ⇄ archived`, no hard delete (ADR §1.3). */
@@ -4627,6 +5164,60 @@ export type ChatSeatRefusedFrame = {
   project_id?: string;
 };
 
+// ── Chat citations (crew#561, F-RC1-117; api-types 0.67.0) ───────────────────
+//
+// A seat's answer cites paths, `path:line` / `path:symbol` refs and commit SHAs, and nothing used
+// to check them: on the RC1 Phase 6 re-run 2 of 26 cited SHAs existed in no repo and three line
+// refs were off, rendered as plain text a reader could not tell apart from the real ones. The
+// daemon verifies each citation against the very read roots it handed the seats and publishes the
+// verdicts; the seat's TEXT is never edited — a skin MARKS it from these items.
+
+/** What class of thing a citation is. */
+export type ChatCitationKind = 'path' | 'line' | 'symbol' | 'sha';
+
+/**
+ * The verdict on one citation.
+ *  - `verified` — it exists, exactly as cited;
+ *  - `corrected` — it exists, but not where the reply said (`resolved` is the real place);
+ *  - `unverified` — it is not in the chat's scope (the fabricated-SHA case);
+ *  - `unchecked` — the bounded pass did not reach it. NOT a claim either way.
+ */
+export type ChatCitationStatus = 'verified' | 'corrected' | 'unverified' | 'unchecked';
+
+/** One citation as verified. `raw` is the token EXACTLY as it appears in the reply, so a skin can
+ *  find it in the rendered text without re-parsing. */
+export interface ChatCitationItem {
+  raw: string;
+  kind: ChatCitationKind;
+  status: ChatCitationStatus;
+  /** Where the thing actually is: `alpha/src/foo.ts:2069` for a corrected line ref, the repo name
+   *  for a SHA, the defining line for a symbol. Absent when there is nothing to add. */
+  resolved?: string;
+  /** Why, in one short phrase — a skin's hover text. */
+  note?: string;
+}
+
+/**
+ * DAEMON-SYNTHETIC (like {@link ChatSeatRefusedFrame}): ONE frame per terminal `chatReply` of a
+ * chat that has read roots, broadcast AFTER that reply (verification never delays an answer) and
+ * stamped with the reply's own `turn_id`. ABSENT — never empty — when the reply cites nothing, when
+ * the chat has no read roots to verify against, and for a not-ok reply (a refusal or eviction line
+ * cites nothing a reader would paste). The counts match `items`; `unverifiable` counts `unverified`
+ * only, so `unchecked` is never read as a fabrication.
+ */
+export type ChatCitationsFrame = {
+  type: 'chatCitations';
+  chat: string;
+  cliKey: string;
+  turn_id?: string;
+  verified: number;
+  unverifiable: number;
+  corrected: number;
+  unchecked: number;
+  items: ChatCitationItem[];
+  project_id?: string;
+};
+
 /** One live chat on `GET /chats` (FINDING-027 gap 4; scope fields with crew#502). */
 export interface ChatSummary {
   chatId: string;
@@ -4670,7 +5261,25 @@ export interface ChatUsage {
  */
 export type ChatTranscriptRecord =
   | { at: number; turnId: string; kind: 'user'; text: string; seats: string[] }
-  | { at: number; turnId: string; kind: 'seat'; cliKey: string; text: string; ok: boolean; usage: ChatUsage | null };
+  | { 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,
+   * crew#561) — a SEPARATE record because the transcript is append-only and verification finishes
+   * after the reply is stored. A reader folds it onto that reply; a skin that does not know this
+   * kind ignores it (the `kind` discriminant is the extension point). Present only for a reply that
+   * cited something; the live frame is {@link ChatCitationsFrame}, with the same fields.
+   */
+  | {
+      at: number;
+      turnId: string;
+      kind: 'citations';
+      cliKey: string;
+      verified: number;
+      unverifiable: number;
+      corrected: number;
+      unchecked: number;
+      items: ChatCitationItem[];
+    };
 
 /** `GET /chats/:id` → 200. */
 export interface ChatDetailResponse {
@@ -5045,8 +5654,12 @@ export interface Campaign {
  * `delivery === 'delivered'`.
  */
 export interface CampaignNodeDelivery {
-  delivery: 'delivered' | 'stranded' | 'vacuous' | 'none';
+  delivery: 'delivered' | 'pushed' | 'stranded' | 'vacuous' | 'none';
   deliverUrl?: string;
+  /** Present exactly when `delivery === 'pushed'` (api-types 0.69.0, N1). */
+  deliverBranch?: string;
+  /** Present exactly when `delivery === 'pushed'`; userinfo removed. */
+  deliverRemote?: string;
 }
 
 /**
@@ -5059,8 +5672,12 @@ export interface CampaignNodeDelivery {
 export interface AttachedRunView {
   runId: string;
   status: SessionStatus;
-  delivery: 'delivered' | 'stranded' | 'vacuous' | 'none';
+  delivery: 'delivered' | 'pushed' | 'stranded' | 'vacuous' | 'none';
   deliverUrl?: string;
+  /** Present exactly when `delivery === 'pushed'` (api-types 0.69.0, N1). */
+  deliverBranch?: string;
+  /** Present exactly when `delivery === 'pushed'`; userinfo removed. */
+  deliverRemote?: string;
 }
 
 /**
@@ -5248,6 +5865,9 @@ export interface AcpCliDiagnostics {
   lastStartedTs: number | null;
   /** Epoch ms of the newest `acpFallback`, or `null` when none recorded. */
   lastFallbackTs: number | null;
+  /** (core#581) The seat's ACP version pin, probed now — present only for a pinned seat, which
+   *  lists here even with no ACP events yet (zero counts). */
+  versionPin?: SeatVersionPin;
 }
 
 /** The ACP fold of `GET /diagnostics` — keyed by `cliKey` (`claude`, `pi`, `codex`, …). */
@@ -5364,6 +5984,36 @@ export interface DiagnosticsGovernance {
   findings: DiagnosticsGovernanceFinding[];
 }
 
+/** `POST /governance/deadletters/replay` body (api-types 0.51.0): replay THIS daemon's dead-letter
+ *  outbox into its own governance store. `dryRun: true` folds the outbox and moves nothing. */
+export interface GovernanceReplayBody {
+  dryRun?: boolean;
+}
+
+/** `POST /governance/deadletters/replay` answer (api-types 0.51.0) — the `governance replay` CLI's
+ *  outcome. A dry run carries `fold` (what the outbox holds) and `blocker`: why a real replay could
+ *  not run on this daemon (in-memory store, an engine without the binding), `null` when it can. A
+ *  real replay reports what landed (`replayed`), what an earlier replay had already landed
+ *  (`alreadyPresent`, `null` on an engine that does not say) and what did not (`failed` — those
+ *  entries are back on the live outbox and stay dead letters). 409: no governance store / a replay
+ *  already running / a blocker; 501: the engine cannot replay. */
+export interface GovernanceReplayOutcome {
+  outbox: string;
+  store: { path: string; source: DiagnosticsGovernanceStoreSource };
+  /** Where a real replay archived the drained outbox; `null` on a dry run. */
+  archive: string | null;
+  read: number;
+  replayed: number;
+  alreadyPresent: number | null;
+  failed: number;
+  dryRun: boolean;
+  /** The same-event conflation caveat the CLI prints, or `null`. */
+  note: string | null;
+  /** Dry run only: the outbox fold (the `/diagnostics` dead-letter block minus the legacy pointer). */
+  fold?: Omit<DiagnosticsGovernanceDeadletters, 'legacyOutbox'>;
+  blocker: string | null;
+}
+
 /** The skills seam's state as `GET /diagnostics` reports it (skills keystone, api-types 0.28.0). */
 export type DiagnosticsSkillsState = 'published' | 'fallback' | 'blocked' | 'config-error' | 'disabled';
 
@@ -5670,9 +6320,219 @@ export interface PolicyLandingResult {
  * predating the policy→steering landing (forward-additive, DES-MEM-FACETED-001 §5.2).
  */
 export type ApproveProposalResponse =
-  | { outcome: 'promoted'; active_id: string }
+  | { outcome: 'promoted'; active_id: string; edited?: ProposalEdit }
   | { outcome: 'handed_off'; payload: unknown; landing?: PolicyLandingResult };
 
+/**
+ * `POST /proposals/:id/approve` body (api-types 0.49.0) — present only for an accept WITH an edit;
+ * no body (or `{}`) is the plain approve. estate has no proposal edit, so the daemon submits the
+ * edited copy to the same queue (`payload.edited_from = <id>`), approves it, then rejects the
+ * original. Memory proposals only (400 otherwise; 404 when `id` is not pending; 409 while another
+ * accept of the same `id` is in flight).
+ */
+export interface ApproveProposalBody {
+  /** The edited memory text (replaces `payload.content`). */
+  content?: string;
+  /** `"pattern"`: the copy drops its `project`/`repo` facets, so it may be recalled on ANY project
+   *  (the human act that lets a pattern cross projects; refused on anything but a captured memory, `payload.capture: "memory"`).
+   *  `"project"`: it stays scoped to its project — gaining the proposing run's project as its
+   *  `project` facet when the worker filed none (400 when no project files that run). An accept
+   *  that changes nothing the store keeps approves the original as filed (no copy, no `edited`). */
+  reach?: 'project' | 'pattern';
+}
+
+/**
+ * `POST /proposals` body (api-types 0.54.0) — a skin files ONE preference into the review queue
+ * (studio's takes: "prefers takes like X", filed when a person picks one of two candidate outputs).
+ * The daemon files it as `kind_type: "memory"` with `payload {content, tier: "semantic",
+ * capture: "preference", source?}`; the kind is never the caller's (unknown keys are a 400).
+ * Nothing is learned until the person accepts it on `/proposals`.
+ */
+export interface FileProposalBody {
+  /** The preference in words (1–4000 chars, trimmed). */
+  content: string;
+  /** Becomes the `project` facet, so the preference is recalled on that project only. */
+  project?: string;
+  /** Where the pick was made, e.g. `doc:<docId>@v3` (kept on the payload). */
+  source?: string;
+}
+
+/** `POST /proposals` → 201: the pending proposal's id. */
+export interface FileProposalResponse {
+  id: string;
+}
+
+/** An accept-with-edit's trail: the original proposal (now rejected) and the approved copy. */
+export interface ProposalEdit {
+  from: string;
+  to: string;
+  /** The copy was approved but rejecting the original failed: it is still pending, for the person
+   *  to reject. Absent when the original was rejected. */
+  originalPending?: true;
+}
+
+// ── Capture (Studio OS behaviour 8, api-types 0.49.0) ─────────────────────────────
+
+/** One dropped text file (a transcript, meeting notes). */
+export interface CaptureTextFile {
+  name: string;
+  text: string;
+}
+
+/** One dropped photo, read by a vision-capable seat. `mediaType` is image/png, image/jpeg,
+ *  image/gif or image/webp. */
+export interface CaptureImageFile {
+  name: string;
+  mediaType: string;
+  dataBase64: string;
+}
+
+/**
+ * `POST /projects/:id/capture` body: notes and/or files (at least one). The daemon lands them in a
+ * per-run inbox and launches a repo-less run filed to the project (through `POST /runs`, so its
+ * refusals are that route's). The run's output is proposals in the `/proposals` queue — each with
+ * `kind_type: "memory"` (or `"policy:<type>"` for a rule), `payload.capture` = `intent` |
+ * `decision` | `memory` | `rule`, `provenance.run_id` = the returned `runId`, and `facets.project`
+ * unless the team marked a memory `payload.reach: "pattern"` (the user decides on accept).
+ */
+export interface CaptureBody {
+  notes?: string;
+  files?: Array<CaptureTextFile | CaptureImageFile>;
+}
+
+/** `POST /projects/:id/capture` → 201. */
+export interface CaptureResponse {
+  runId: string;
+}
+
+// ── The Demo experience (wicked-studio#373, api-types 0.61.0) ────────────────────────────────
+
+/**
+ * `POST /projects/:id/demo` body: the app to film, who the demo is for and what to show. The daemon
+ * mints the run's demo root, writes the brief there and launches the built-in `demo` preset (the
+ * wicked-garden demo skill's plan → record → review) through `POST /runs`, so its refusals are that
+ * route's. The demo root is the run's only extra write root; a caller never names it.
+ */
+export interface DemoLaunchBody {
+  /** The running app (http or https). The recorder is read-only against it. */
+  url: string;
+  audience: string;
+  show: string;
+  /** The roster to seat the team from, as `POST /runs` takes it. Omit for the daemon's roster. */
+  clisJson?: string;
+}
+
+/** `POST /projects/:id/demo` → 201. */
+export interface DemoLaunchResponse {
+  runId: string;
+}
+
+/** `PUT /runs/:id/demo/script` body: the presenter's edit of `script.md` (plan gate only; ≤ 256 KB). */
+export interface DemoScriptBody {
+  content: string;
+}
+
+/**
+ * Where a demo run stands. `preparing` covers the PA's scope step and any phase the floor added before
+ * `plan`; `team_gate` is the team plan's approval gate (`plan_approval`: the run holds a plan rev past
+ * the accepted one), which opens before `plan` runs and is answered like any gate; `plan_gate` and `review_gate` are the run's human gates (answered through `POST /runs/:id/gate`:
+ * approve, or `action: 'request_changes'` with the note as `amend` — at the plan gate it re-runs `plan`,
+ * at the review gate it rewinds to `record`). The review gate is the one after `review` passed, or the
+ * engine's escalation gate when the review did not pass (`review.rejected`).
+ */
+export type DemoStage =
+  | 'preparing'
+  | 'team_gate'
+  | 'planning'
+  | 'plan_gate'
+  | 'recording'
+  | 'reviewing'
+  | 'review_gate'
+  | 'done'
+  | 'failed';
+
+/** One chapter of the plan's `chapters.json`, with whether its segment has been recorded. */
+export interface DemoChapter {
+  /** `NN-slug` — the segment key record.mjs re-records by. */
+  key: string;
+  title: string;
+  blurb: string;
+  tags: string[];
+  resets: string[];
+  recorded: boolean;
+}
+
+/** A chapter marker of the stitched MP4 (record.mjs's `chapters.md`). */
+export interface DemoMarker {
+  /** `m:ss`. */
+  at: string;
+  sec: number;
+  title: string;
+}
+
+/** One finding of the reviewer's verdict block. */
+export interface DemoFinding {
+  at: string;
+  chapter: string;
+  issue: string;
+  verdict: 're-encode' | 're-record' | 'fix-app';
+}
+
+/** `GET /runs/:id/demo` → 200 (404 for a run that is not a demo run). */
+export interface DemoView {
+  runId: string;
+  /** From the brief the daemon wrote. */
+  url: string | null;
+  audience: string | null;
+  stage: DemoStage;
+  /** `script.md` — the presenter script (null until `plan` writes it). */
+  script: string | null;
+  chapters: DemoChapter[];
+  markers: DemoMarker[];
+  /** Root-relative paths for `GET /runs/:id/demo/file?path=`. */
+  sheets: Array<{ name: 'chapters' | 'joins' | 'end'; path: string }>;
+  video: { path: string; bytes: number } | null;
+  /** From the recorder's `recording.json`: true only when every stitched segment was recorded read-only;
+   *  null before a stitch (or from a recorder without the guard). */
+  recording: { readOnly: boolean | null };
+  /**
+   * The reviewer's last output and its parsed verdict block (empty until `review` has finished).
+   * `rejected`: the engine judged the review NOT PASS, so the review gate is its escalation gate — a
+   * failed review cannot be accepted: approve re-runs the reviewer, `request_changes` sends the note back
+   * to `record`, reject cancels the run.
+   */
+  review: { verdict: 'accept' | 'changes' | null; findings: DemoFinding[]; text: string | null; rejected: boolean };
+  /** The seats that recorded and reviewed — evaluator ≠ creator puts them apart. */
+  seats: { recorder: string | null; reviewer: string | null };
+  /** The script says which data is synthetic. */
+  syntheticLabelled: boolean;
+}
+
+/** What `POST /runs/:id/demo/export` makes (EP-C3; api-types 0.72.0). The MP4 itself needs no export: download `video.path`. */
+export type DemoExportFormat = 'gif' | 'poster';
+
+/**
+ * `POST /runs/:id/demo/export` body (EP-C3; api-types 0.72.0). `gif` encodes the stitched MP4 into
+ * `demo-video/demo.gif` (two-pass palette, 10 fps, 720 px wide); `poster` writes one frame to
+ * `demo-video/poster.jpg`. The daemon encodes with ffmpeg off its event loop and a timeout (GIF 180 s,
+ * poster 30 s), only at the review gate or once the run has ended. Refusals: 400 a bad body, 404 not a demo run, 409 no stitched MP4 yet / the run is still recording / `demo-video/` changed mid-encode, 422 no frame
+ * at `atSec`, 502 ffmpeg failed, 503 no ffmpeg on the daemon host (`hint` says how to install it),
+ * 504 the encode ran past its timeout. A second identical request while one encodes joins it.
+ */
+export interface DemoExportBody {
+  format: DemoExportFormat;
+  /** Poster only: the frame, in seconds from the start (0 … 86400). Default: the first chapter marker + 1 s, or 1 s with no markers. */
+  atSec?: number;
+}
+
+/** `POST /runs/:id/demo/export` → 200: the file, ready for `GET /runs/:id/demo/file?path=`. */
+export interface DemoExportResponse {
+  format: DemoExportFormat;
+  /** `demo-video/demo.gif` or `demo-video/poster.jpg` (root-relative). */
+  path: string;
+  bytes: number;
+}
+
 /** `POST /proposals/:id/reject` → 200. */
 export interface RejectProposalResponse {
   ok: true;
@@ -5774,16 +6634,1703 @@ export interface MemoryCoverageResponse {
 }
 
 /**
- * `POST /memory/retire` body. Retire is SUBTREE-scoped, never per-id: estate `memory.erase`
- * hard-deletes EVERY memory whose scope equals or descends from `scope_prefix`. `scope_prefix` is
- * required and must be non-empty (estate refuses a total wipe) — the surface must show the operator
- * the whole subtree it will remove, not a single row.
+ * `POST /memory/retire` body. This retire is SUBTREE-scoped: estate `memory.erase` hard-deletes
+ * EVERY memory whose scope equals or descends from `scope_prefix`. `scope_prefix` is required and
+ * must be non-empty (estate refuses a total wipe) — the surface must show the operator the whole
+ * subtree it will remove. To remove ONE row, use {@link RetireMemoryItemBody}.
  */
 export interface RetireMemoryBody {
   scope_prefix: string;
 }
 
-/** `POST /memory/retire` → 200. The number of memories the subtree wipe deleted. */
-export interface RetireMemoryResponse {
+/**
+ * `POST /memory/retire-item` body (studio#206; api-types 0.60.0): exactly ONE memory, by the
+ * `memory_id` `GET /memory` listed. 404 when no memory has that id; 501 `estate_upgrade_required`
+ * when the estate predates erase-by-id (wicked-estate#188) — nothing is deleted then.
+ */
+export interface RetireMemoryItemBody {
+  memory_id: string;
+}
+
+/** `POST /memory/retire` / `POST /memory/retire-item` → 200. How many memories were deleted
+ *  (always 1 for `retire-item`). */
+export interface RetireMemoryResponse {
   erased: number;
 }
+
+// ── Team events on the bus (DES-TEAMING-002 §6, wicked-core T1; api-types 0.41.0) ──────────────
+//
+// The `wicked.team.*` facts wicked-core publishes on the cross-product bus (`domain`
+// `wicked-core`, `subdomain` `core.team`), one owner per type (DES-002 §7: E engine, S supervisor,
+// R attempt runner). Crew publishes none of them: it relays and reads. Mirrors wicked-core
+// `src/team/events.rs`; `packages/crew/tests/team-events.test.ts` pins every type against the
+// engine's own round-trip fixtures by value. Payload keys are snake_case and every key is
+// present (an absent value is `null`), except a plan step's optional fields, which a plan omits
+// when unset. The embedded {@link TeamLedger} keeps DES-001 §7's camelCase.
+
+/** The 25 `wicked.team.<noun>.<verb>` event types. */
+export type TeamEventType =
+  | 'wicked.team.path.started'
+  | 'wicked.team.path.scored'
+  | 'wicked.team.plan.proposed'
+  | 'wicked.team.plan.revised'
+  | 'wicked.team.plan.accepted'
+  | 'wicked.team.plan.refused'
+  | 'wicked.team.member.joined'
+  | 'wicked.team.member.left'
+  | 'wicked.team.step.claimed'
+  | 'wicked.team.checkpoint.reached'
+  | 'wicked.team.finding.raised'
+  | 'wicked.team.advice.delivered'
+  | 'wicked.team.advice.answered'
+  | 'wicked.team.help.requested'
+  | 'wicked.team.help.answered'
+  | 'wicked.team.change.requested'
+  | 'wicked.team.step.completed'
+  | 'wicked.team.step.reviewed'
+  | 'wicked.team.finding.settled'
+  | 'wicked.team.council.called'
+  | 'wicked.team.council.ruled'
+  | 'wicked.team.ledger.folded'
+  | 'wicked.team.gate.opened'
+  | 'wicked.team.gate.decided'
+  | 'wicked.team.path.ended';
+
+/** The fields every team payload carries. */
+export interface TeamEnvelope {
+  run_id: string;
+  ord: number | null;
+  attempt: number | null;
+  /**
+   * Who acted: a seated CLI instance (the PA, a member or the authoring monitor, e.g.
+   * `'claude#1'`, `'claude#2'`, `'codex'`), `'engine'`, `'human'` or `'council:<task id>'`.
+   */
+  by: string;
+  /** Epoch milliseconds at the producer. */
+  at: number;
+  /** The row this one answers, e.g. `'finding.raised#4'`. */
+  re: string | null;
+}
+
+/** A plan step: a catalog entry plus the step fields a plan may set (omitted when unset). */
+export interface TeamPlanStep {
+  catalog: string;
+  id: string;
+  instructions?: string;
+  owner?: 'pa' | 'team' | (string & {});
+  depends_on?: string[];
+  /** A raised gate, as the workflow's externally tagged `GateSpec`. */
+  gate?: unknown;
+  added_by?: 'plan' | 'floor' | (string & {});
+  floor_reason?: string;
+  late?: boolean;
+}
+
+export interface TeamPlanOverride {
+  remove: string[];
+  reason: string;
+}
+
+export type TeamPathStartedPayload = TeamEnvelope & {
+  cli: string;
+  selection: 'chosen' | 'random' | (string & {});
+  roster: string[];
+  request: string;
+  workflow: string | null;
+  plan: boolean;
+};
+
+export type TeamPathScoredPayload = TeamEnvelope & {
+  /** `'intent:<proposal_id>'` | `'diff:<ord>:<attempt>:<rescore_seq>'`. */
+  score_source: string;
+  basis: 'intent' | 'diff' | (string & {});
+  score: number;
+  deterministic: number;
+  reasons: string[];
+  model: { add: number; rationale: string } | null;
+  signals: {
+    changed_symbols: number;
+    dependents: number;
+    products: number;
+    contract_change: boolean;
+    test_gap: number;
+    critical: boolean;
+    destructive: boolean;
+    truncated: boolean;
+  } | null;
+  plan: { monitors: number; depth: string; post_hoc_reviewer: boolean; post_hoc_other_cli: boolean };
+  tree: string | null;
+};
+
+export type TeamPlanProposedPayload = TeamEnvelope & {
+  proposal_id: string;
+  base_rev: number | null;
+  kind: 'initial' | 'change' | 'edit' | (string & {});
+  preset: string | null;
+  steps: TeamPlanStep[];
+  monitors: { asked: number };
+  asks: string[];
+  touch: string[];
+  override: TeamPlanOverride | null;
+  rationale: string;
+};
+
+export type TeamPlanRevisedPayload = TeamEnvelope & {
+  plan_rev: number;
+  proposal_id: string | null;
+  reason: 'floor_raised' | 'pa_added' | 'member_request' | (string & {});
+  from_band: string;
+  to_band: string;
+  high_risk: boolean;
+  added: TeamPlanStep[];
+};
+
+export type TeamPlanAcceptedPayload = TeamEnvelope & {
+  plan_rev: number;
+  workflow_id: string;
+  band: string;
+  high_risk: boolean;
+  mode: 'auto' | 'manual' | (string & {});
+  steps: TeamPlanStep[];
+  override: TeamPlanOverride | null;
+  proposal_id: string | null;
+};
+
+export type TeamPlanRefusedPayload = TeamEnvelope & {
+  proposal_id: string;
+  base_rev: number | null;
+  reason: string;
+};
+
+export type TeamMemberJoinedPayload = TeamEnvelope & {
+  member_id: string;
+  open_seq: number;
+  seat: string;
+  role: 'monitor' | (string & {});
+  status: 'attached' | 'failed' | (string & {});
+  reason: string;
+  error: string | null;
+};
+
+export type TeamMemberLeftPayload = TeamEnvelope & {
+  member_id: string;
+  open_seq: number;
+  seat: string;
+  status: 'completed' | 'budget_exhausted' | 'failed' | 'timed_out' | (string & {});
+  batches: number;
+  error: string | null;
+};
+
+export type TeamStepClaimedPayload = TeamEnvelope & {
+  step_id: string;
+  role: string;
+  kind: string;
+  phase: string;
+  criterion: string;
+  baseline_tree: string | null;
+  repo: { workdir: string; git_dir: string } | null;
+  code_graph_db: string | null;
+};
+
+export type TeamCheckpointReachedPayload = TeamEnvelope & {
+  seq: number;
+  tool_call_id: string;
+  kind: string;
+  title: string;
+  status: 'completed' | 'failed' | (string & {});
+  paths: string[];
+};
+
+export type TeamFindingRaisedPayload = TeamEnvelope & {
+  raise_seq: number;
+  finding_id: string;
+  member_id: string;
+  line_key: string | null;
+  anchor: string | null;
+  anchor_source: 'graph' | 'hunk' | 'none' | (string & {}) | null;
+  severity: 'high' | 'medium' | (string & {});
+  path: string;
+  line: number;
+  evidence: string;
+  claim: string;
+  suggestion: string | null;
+  tree: string;
+  in_diff: boolean;
+  corroborated_by: string[];
+};
+
+export type TeamAdviceDeliveredPayload = TeamEnvelope & {
+  raise_seq: number;
+  finding_id: string;
+  /** The steer id | `'boundary:<step_id>:<attempt>'` | `'end:<attempt>'`. */
+  delivery_id: string;
+  steer_id: string | null;
+  channel: 'acp_steering' | 'boundary' | 'none' | (string & {});
+  outcome: 'injected' | 'turn_ended' | 'refused' | 'not_delivered' | (string & {});
+  detail: string | null;
+};
+
+export type TeamAdviceAnsweredPayload = TeamEnvelope & {
+  raise_seq: number;
+  /** `'<step_id>:<attempt>'`. */
+  answered_in: string;
+  finding_id: string;
+  disposition: 'accepted' | 'declined' | (string & {});
+  reason: string;
+};
+
+export type TeamHelpRequestedPayload = TeamEnvelope & {
+  help_id: string;
+  help_seq: number;
+  question: string;
+  context: string;
+};
+
+export type TeamHelpAnsweredPayload = TeamEnvelope & {
+  help_id: string;
+  answer_id: string;
+  answer: string;
+  evidence: string[];
+};
+
+export type TeamChangeRequestedPayload = TeamEnvelope & {
+  change_id: string;
+  change_seq: number;
+  steps: TeamPlanStep[];
+  reason: string;
+};
+
+export type TeamStepCompletedPayload = TeamEnvelope & {
+  step_id: string;
+  status: 'ok' | 'failed' | 'cancelled' | 'elicitation_failed' | 'timed_out' | (string & {});
+  tree: string | null;
+  output_bytes: number;
+  output_ref: string;
+};
+
+export type TeamStepReviewedPayload = TeamEnvelope & {
+  step_id: string;
+  verdict: 'accepted' | 'rejected' | (string & {});
+  to: 'member' | 'pa' | (string & {}) | null;
+  reason: string;
+};
+
+export type TeamFindingSettledPayload = TeamEnvelope & {
+  raise_seq: number;
+  finding_id: string;
+  status: 'held' | 'withdrawn' | 'superseded' | (string & {});
+  reason: string;
+  final_line: number | null;
+};
+
+export type TeamCouncilCalledPayload = TeamEnvelope & {
+  /** `'finding:<raise_seq>'` | `'step:<step_id>:<attempt>'`. */
+  subject: string;
+  finding_id: string | null;
+  trigger: 'unresolved_high' | 'member_step' | (string & {});
+  question: string;
+  positions: { by: string; position: string; reason: string }[];
+  evidence: string;
+  excluded_seats: string[];
+  transcript: number[];
+};
+
+export type TeamCouncilRuledPayload = TeamEnvelope & {
+  subject: string;
+  verdict: 'yes' | 'no' | 'no_verdict' | (string & {});
+  reason: 'no_quorum' | 'seats_benched' | 'error' | 'timeout' | 'cap' | (string & {}) | null;
+  task_id: string | null;
+  consensus: boolean;
+  agreement_pct: number;
+  dissent: string[];
+  returned: number;
+  seated: number;
+};
+
+/** DES-001 §7 `teamLedger.findings[]` (camelCase). */
+export interface TeamLedgerFinding {
+  findingId: string;
+  monitorId: string;
+  seat: string;
+  severity: 'high' | 'medium' | (string & {});
+  path: string;
+  line: number;
+  evidence: string;
+  claim: string;
+  suggestion: string | null;
+  tree: string;
+  inDiff: boolean;
+  finalLine: number | null;
+  corroboratedBy: string[];
+  delivery: 'injected' | 'not_delivered' | (string & {});
+  status: 'accepted' | 'declined' | 'withdrawn' | 'unanswered' | 'superseded' | (string & {});
+  workerReason: string | null;
+  monitorReply: { kind: 'hold' | 'withdraw' | (string & {}); reason: string } | null;
+  dispute: {
+    verdict: 'yes' | 'no' | 'no_verdict' | (string & {});
+    agreementPct: number | null;
+    dissent: number | null;
+    seats: string[];
+    reason: string | null;
+  } | null;
+  /**
+   * (T6, api-types 0.42.0) The enclosing location the finding id is minted over (git's funcname
+   * heuristic). Omitted when file-level.
+   */
+  anchor?: string;
+  /** (T6, api-types 0.42.0) The attempt that first raised it, when it was carried into a redriven attempt. Omitted otherwise. */
+  carriedFromAttempt?: number;
+}
+
+/**
+ * (T6, DES-002 §8.8; api-types 0.42.0) The PA's review of a member's step, as the attempt that
+ * carried the review recorded it.
+ */
+export interface TeamStepReview {
+  stepId: string;
+  /** The member attempt the review is about. */
+  reviewedAttempt: number;
+  verdict: 'accepted' | 'rejected' | (string & {});
+  to: 'member' | 'pa' | (string & {}) | null;
+  reason: string;
+  /** On a rejection: `true` the member held (`HOLD`), `false` it accepted, `null` no answer on record. */
+  held: boolean | null;
+  memberReason: string | null;
+  /** The one-off council a hold convened. */
+  dispute: TeamLedgerFinding['dispute'];
+}
+
+/** DES-001 §7 `teamLedger` without its envelope: the fold of one attempt's team stream. */
+export interface TeamLedger {
+  finalPass: 'completed' | 'timed_out' | 'skipped' | 'stream_gap' | (string & {});
+  renderedToJudge: boolean;
+  teamPause: boolean;
+  monitors: {
+    monitorId: string;
+    seat: string;
+    batches: number;
+    status: 'completed' | 'budget_exhausted' | 'failed' | 'timed_out' | (string & {});
+    error: string | null;
+  }[];
+  findings: TeamLedgerFinding[];
+  rejected: { malformed: number; belowBar: number; unconfirmed: number; duplicate: number };
+  /** (T6, api-types 0.42.0) The PA's reviews of member steps this attempt carried. Omitted when none. */
+  stepReviews?: TeamStepReview[];
+}
+
+export type TeamLedgerFoldedPayload = TeamEnvelope & {
+  final_pass: 'completed' | 'timed_out' | 'skipped' | 'stream_gap' | (string & {});
+  ledger: TeamLedger;
+  transport: 'bus' | 'none' | (string & {});
+  transcript: {
+    from_event_id: number;
+    to_event_id: number;
+    count: number;
+    truncated: boolean;
+    events: { event_id: number; event_type: string; payload: unknown }[];
+  };
+};
+
+/** `gate.opened`'s kind-specific fields, discriminated on `kind`. */
+export type TeamGateOpenedPayload = TeamEnvelope & { gate_id: string } & (
+  | { kind: 'unit_review'; ledger_ref: string | null; ledger_source: 'folded' | 'synthesized' | 'no_bus' | (string & {}) }
+  | {
+      kind: 'plan_approval';
+      reviewing_ord: number;
+      plan_rev: number;
+      band: string;
+      high_risk: boolean;
+      mode: 'auto' | 'manual' | (string & {});
+      reason: 'manual_mode' | 'high_risk' | 'into_high_risk' | 'override' | (string & {});
+      diff: { from_rev: number | null; added: string[] };
+    }
+  | { kind: 'team_dispute'; finding_ids: string[] }
+  | { kind: 'team_transport'; fact: string; reason: string }
+);
+
+export type TeamGateDecidedPayload = TeamEnvelope & {
+  gate_id: string;
+  kind: 'unit_review' | 'plan_approval' | 'team_dispute' | 'team_transport' | (string & {});
+  decision:
+    | 'allow'
+    | 'deny'
+    | 'paused'
+    | 'human_approved'
+    | 'human_amended'
+    | 'human_rejected'
+    | (string & {});
+  combined: boolean | null;
+  team_pause: boolean;
+  unresolved: string[];
+};
+
+export type TeamPathEndedPayload = TeamEnvelope & {
+  status: 'completed' | 'failed' | 'cancelled' | (string & {});
+};
+
+/** Each team event type's payload. */
+export interface TeamEventPayloads {
+  'wicked.team.path.started': TeamPathStartedPayload;
+  'wicked.team.path.scored': TeamPathScoredPayload;
+  'wicked.team.plan.proposed': TeamPlanProposedPayload;
+  'wicked.team.plan.revised': TeamPlanRevisedPayload;
+  'wicked.team.plan.accepted': TeamPlanAcceptedPayload;
+  'wicked.team.plan.refused': TeamPlanRefusedPayload;
+  'wicked.team.member.joined': TeamMemberJoinedPayload;
+  'wicked.team.member.left': TeamMemberLeftPayload;
+  'wicked.team.step.claimed': TeamStepClaimedPayload;
+  'wicked.team.checkpoint.reached': TeamCheckpointReachedPayload;
+  'wicked.team.finding.raised': TeamFindingRaisedPayload;
+  'wicked.team.advice.delivered': TeamAdviceDeliveredPayload;
+  'wicked.team.advice.answered': TeamAdviceAnsweredPayload;
+  'wicked.team.help.requested': TeamHelpRequestedPayload;
+  'wicked.team.help.answered': TeamHelpAnsweredPayload;
+  'wicked.team.change.requested': TeamChangeRequestedPayload;
+  'wicked.team.step.completed': TeamStepCompletedPayload;
+  'wicked.team.step.reviewed': TeamStepReviewedPayload;
+  'wicked.team.finding.settled': TeamFindingSettledPayload;
+  'wicked.team.council.called': TeamCouncilCalledPayload;
+  'wicked.team.council.ruled': TeamCouncilRuledPayload;
+  'wicked.team.ledger.folded': TeamLedgerFoldedPayload;
+  'wicked.team.gate.opened': TeamGateOpenedPayload;
+  'wicked.team.gate.decided': TeamGateDecidedPayload;
+  'wicked.team.path.ended': TeamPathEndedPayload;
+}
+
+/** One team bus row, discriminated on `event_type`. */
+export type TeamBusEvent = {
+  [K in TeamEventType]: { event_type: K; payload: TeamEventPayloads[K] };
+}[TeamEventType];
+
+// ── The crew team surface (DES-TEAMING-002 T8; api-types 0.42.0) ─────────────────────────────
+//
+// Commands go through the API, facts go on the bus (§4.0). Crew RELAYS the engine's
+// `wicked.team.*` rows onto `/ws`, READS them back per run, and POSTs commands to the engine. It
+// publishes no team row.
+
+/**
+ * A `/ws` frame carrying one `wicked.team.*` bus row, relayed verbatim (the `interactiveEvent`
+ * pattern). `project_id` is set when the run's membership files it, as on every other frame.
+ */
+export interface TeamEventFrame {
+  type: 'teamEvent';
+  /** The whole bus row as wicked-bus delivers it. */
+  event: TeamBusEvent & { event_id: number; [k: string]: unknown };
+  project_id?: string;
+}
+
+// ── The watch registry wire contract (DES-TRIGGER-REGISTRY-001 §4.5; TR-W4; api-types 0.70.0) ──
+//
+// The registry is advisory by construction: a watch row can never allow, approve or block. Its
+// facts are two bus types owned by crew (`wicked.crew.watch_finding.{raised,cleared}`), relayed
+// onto `/ws` as {@link WatchEventFrame} by a bus tap (never broadcast directly, so the socket and
+// the record cannot disagree). Types only: the runtime lands in TR-W5a, and a daemon without it
+// simply never sends these frames or serves these routes.
+
+/** The two bus types the watch registry publishes. */
+export type WatchEventType = 'wicked.crew.watch_finding.raised' | 'wicked.crew.watch_finding.cleared';
+
+/** How a watch row is meant: a contradiction in the work's own evidence, a look-worthy flag, or a candidate rule for the review queue. */
+export type WatchEmitAs = 'finding' | 'flag' | 'proposal';
+export type WatchSeverity = 'high' | 'medium' | 'info';
+/** The Watchtower's kind column. There is no `needs` kind: needs-you stays studio's own fold. */
+export type WatchKind = 'problem' | 'decision' | 'done' | 'quiet' | 'delivery';
+/** `p0` is never shed; `p1` is shed after `p2` when the push ring overflows. */
+export type WatchPriority = 'p0' | 'p1' | 'p2';
+
+/** Where in the run a watch row points: "Jump in" scrolls to the nearest event at or after `at`. */
+export interface WatchAnchor {
+  run_id: string;
+  ord: number | null;
+  attempt: number | null;
+  /** Unix millis of the source event. */
+  at: number;
+}
+
+/** One piece of evidence a watch row cites. `run_event` names a persisted CoreEvent; `bus_row` a bus row. */
+export interface WatchEvidenceRef {
+  kind: 'run_event' | 'bus_row' | (string & {});
+  type: string;
+  ord?: number | null;
+  attempt?: number | null;
+  /** For `bus_row`: the cited row's `event_id`. */
+  event_id?: number;
+}
+
+/**
+ * The payload of `wicked.crew.watch_finding.raised`. Its first six fields are the team
+ * envelope's (`DES-TEAMING-002` §4.4). `watch_id` is `"w-"` + the deterministic key over
+ * (`run_id | "-"`, `entry_id`, `entry_version`, `subject`), so a replay or a redelivery resolves to
+ * the same row.
+ */
+export interface WatchFinding {
+  /** `null` for a row no run owns (a registry-internal flag such as `registry-lagging`). */
+  run_id: string | null;
+  ord: number | null;
+  attempt: number | null;
+  /** `"watch:<entry_id>@<entry_version>"`. */
+  by: string;
+  /** Unix millis the row was produced. */
+  at: number;
+  /** What it answers: `"<CoreEvent type>#<ord>:<attempt>"`, or a bus source row's idempotency key. */
+  re: string;
+  watch_id: string;
+  entry_id: string;
+  entry_version: number;
+  /** `"deterministic:<name>"` or `"llm:<prompt-ref>@<n>"`. */
+  check: string;
+  kind: WatchEmitAs;
+  severity: WatchSeverity;
+  watch_kind: WatchKind;
+  /** `"gate"`: render as one line on the open gate's existing row, never a new row. */
+  attach: 'gate' | null;
+  /** The run's project membership, as the relay tags frames; absent when the run is unfiled. */
+  project_id?: string;
+  /** The one plain sentence the Watchtower shows. */
+  sentence: string;
+  /** Entry-specific facts, at most 4 KB, redacted. */
+  facts: Record<string, unknown>;
+  anchor: WatchAnchor | null;
+  evidence: WatchEvidenceRef[];
+  /** Set for an `llm:*` check only. */
+  model: { seat: string; model: string; latency_ms: number } | null;
+  /** How many later rows this roll-up stands for (`0` on an ordinary row). */
+  rolled_up: number;
+}
+
+/** The fields every `wicked.crew.watch_finding.cleared` payload carries. */
+export interface WatchFindingClearedBase {
+  run_id: string | null;
+  ord: number | null;
+  attempt: number | null;
+  by: string;
+  at: number;
+  re: string;
+  /** The raised row this clears. */
+  watch_id: string;
+  entry_id: string;
+  entry_version: number;
+  project_id?: string;
+}
+
+/**
+ * The payload of `wicked.crew.watch_finding.cleared`, discriminated on `reason`: the raised row
+ * `watch_id` names is resolved (a later attempt passed, the worker produced output), dismissed by
+ * the operator ("Seen, not a problem": `dismissed_by` says who), or replaced by a roll-up
+ * (`replaced_by` names it). The set is closed on purpose: no clearing reason is allow-like.
+ */
+export type WatchFindingCleared =
+  | (WatchFindingClearedBase & { reason: 'resolved' })
+  | (WatchFindingClearedBase & { reason: 'dismissed'; dismissed_by: string })
+  | (WatchFindingClearedBase & { reason: 'rolled_up'; replaced_by: string });
+
+export interface WatchEventPayloads {
+  'wicked.crew.watch_finding.raised': WatchFinding;
+  'wicked.crew.watch_finding.cleared': WatchFindingCleared;
+}
+
+/** One watch bus row, discriminated on `event_type`. */
+export type WatchBusEvent = {
+  [K in WatchEventType]: { event_type: K; payload: WatchEventPayloads[K] };
+}[WatchEventType];
+
+/**
+ * A `/ws` frame carrying one `wicked.crew.watch_finding.*` bus row, relayed verbatim (the
+ * {@link TeamEventFrame} pattern). `project_id` is set when the run's membership files it.
+ */
+export interface WatchEventFrame {
+  type: 'watchEvent';
+  /** The whole bus row as wicked-bus delivers it. */
+  event: WatchBusEvent & { event_id: number; [k: string]: unknown };
+  project_id?: string;
+}
+
+/**
+ * What one check can see on one run. Studio never renders an empty list as "all clear" when an entry
+ * was `not_checked`; a `not_checked` entry always says why, in plain words ("no declared scope", "the
+ * daemon was down").
+ */
+export type WatchCoverage =
+  | { entry_id: string; state: 'checked' }
+  | { entry_id: string; state: 'not_checked'; reason: string };
+
+/** `GET /watch?project=&kind=&run=&since=&limit=`: the feed fold, newest first. */
+export interface WatchFeedResponse {
+  findings: WatchFinding[];
+  /**
+   * The clearing rows of the findings on this page (a late join folds them as the live
+   * `watch_finding.cleared` frames would: Fixed, Dismissed, rolled up). api-types 0.73.0.
+   */
+  cleared?: WatchFindingCleared[];
+  /** Present with `run=` only. */
+  coverage?: WatchCoverage[];
+}
+
+/**
+ * Where an entry's key point comes from. `core`: a CoreEvent from the daemon fan-in. `bus`: a pulled
+ * 4-segment bus type. `watchdog`: a stall-watchdog frame (`workerStalled`, …). `internal`: the
+ * registry's own tick or check-failure report (`registry-lagging`, `registry-check-failed`).
+ * (api-types 0.73.0 adds `watchdog` and `internal`.)
+ */
+export type WatchEntrySource = 'core' | 'bus' | 'watchdog' | 'internal';
+
+/** Who changed one operator setting of an entry, and when (stamped by the daemon, never the caller). */
+export interface WatchSettingStamp {
+  by: string;
+  /** Unix millis. */
+  at: number;
+}
+
+/** One entry's operator override in `SystemSettings.watch.entries`. */
+export interface WatchEntryOverride {
+  enabled?: boolean;
+  /** Merged over the shipped threshold, validated by the entry's check. */
+  threshold?: Record<string, unknown>;
+  /** Daemon-stamped; a caller cannot set these. */
+  enabled_changed?: WatchSettingStamp;
+  threshold_changed?: WatchSettingStamp;
+}
+
+/** `SystemSettings.watch`. */
+export interface WatchSettings {
+  entries?: Record<string, WatchEntryOverride>;
+  /** The LLM lane (off by default; TR-W9). */
+  llm?: boolean;
+}
+
+/**
+ * One registry entry (`packages/crew/watch/entries/<id>.json`), as `GET /watch/entries` serves it:
+ * the effective entry (the operator's `enabled` / `threshold` override applied) plus its threshold
+ * in plain words. The schema has no allow-like `emit.as` value.
+ */
+export interface WatchEntry {
+  /** Stable, `[a-z0-9-]{3,48}`; equals the file name. */
+  id: string;
+  /** Bumped on any semantic change; part of every finding key. */
+  version: number;
+  /** See {@link WatchEntrySource}. A `bus` type is a 4-segment `wicked.<domain>.<noun>.<verb>` type. */
+  on: { source: WatchEntrySource; type: string };
+  /** JSON-path equality, AND of keys; an array means "any of". */
+  filter: Record<string, unknown>;
+  check: string;
+  params: Record<string, unknown>;
+  threshold: Record<string, unknown>;
+  emit: {
+    as: WatchEmitAs;
+    severity: WatchSeverity;
+    watch_kind: WatchKind;
+    attach: 'gate' | null;
+    /** Past `per_run`, one roll-up replaces the rest. */
+    rate: { per_run: number };
+  };
+  priority: WatchPriority;
+  enabled: boolean;
+  /** The threshold in plain words, for "When Studio speaks up". Always set on `GET /watch/entries`. */
+  threshold_text: string;
+}
+
+/** Who changed an operator-adjustable entry setting, and when (read from the `settings.updated` audit entry). */
+export interface WatchEntryChange {
+  id: string;
+  by: string;
+  /** Unix millis. */
+  at: number;
+}
+
+/** `GET /watch/health`. Every turned-off entry and every changed threshold is listed with who and when. */
+export interface WatchHealth {
+  /** The registry is running. `false` ⇒ `reason` says why. */
+  armed: boolean;
+  reason: string | null;
+  sources: {
+    bus: 'ok' | 'lagging' | 'down' | (string & {});
+    core: 'ok' | 'lagging' | 'down' | (string & {});
+    watchdog: 'ok' | 'lagging' | 'down' | (string & {});
+  };
+  queue: { depth: number; hwm: number; shed_by_priority: Record<WatchPriority, number> };
+  tail_lag_ms: number;
+  emit: { failed: number };
+  entries: {
+    loaded: number;
+    refused: Array<{ id: string; reason: string }>;
+    off: WatchEntryChange[];
+    thresholds_changed: WatchEntryChange[];
+  };
+  llm: { enabled: boolean; inflight: number; timeouts: number; skipped_no_seat: number };
+  /** `core_gap: true`: runs that started and ended while the daemon was down were not evaluated this boot. */
+  replay?: { core_gap: boolean };
+}
+
+/** One `wicked.team.*` bus row as `GET /runs/:id/team` returns it. */
+export type TeamRow = TeamBusEvent & {
+  event_id: number;
+  /** wicked-bus `emitted_at` (Unix millis). */
+  emitted_at: number;
+  /**
+   * Set on a `wicked.team.ledger.folded` row the unit's gate did NOT read: a `gate.opened
+   * {kind:"unit_review"}` for the same ord and attempt names another ledger (`ledger_ref` null,
+   * a synthesized ledger). `gate.opened.ledger_ref` is the only authority on what the gate read.
+   */
+  unused?: true;
+};
+
+/**
+ * One unit's team state in {@link RunTeamResponse}: the engine's persisted snapshot
+ * (`Core.runTeam`; the last five fields are `null` until the unit's attempt folded) plus the
+ * unit's bus rows.
+ */
+export interface RunTeamUnit {
+  ord: number;
+  /** `null` until the unit dispatched. */
+  transport: 'bus' | 'none' | (string & {}) | null;
+  reason: string | null;
+  /** Where the gate's ledger came from: folded by the supervisor, synthesized by the worker on the final-pass timeout, or local (no bus). */
+  ledgerSource: 'folded' | 'synthesized' | 'no_bus' | (string & {}) | null;
+  /** The supervisor row the gate read (`"ledger.folded#<ord>:<attempt>"`); `null` for a synthesized or local ledger. */
+  ledgerRef: string | null;
+  finalPass: 'completed' | 'timed_out' | 'skipped' | 'stream_gap' | (string & {}) | null;
+  /** An unresolved HIGH (or an incomplete record) stands without a council YES: the run pauses `team_dispute`. */
+  teamPause: boolean | null;
+  /** How many findings the attempt's ledger holds. */
+  findings: number | null;
+  /** The unit's bus rows (`payload.ord` = this ord), every attempt, ordered by `event_id`. Empty when the bus has none. */
+  rows: TeamRow[];
+  /**
+   * The folded ledger the gate read (the `ledger.folded` row `ledgerRef` names), or `null`: not
+   * folded yet, synthesized or local (read `UnitEvidence.team` on the evidence route), or the bus
+   * no longer has the row (the snapshot fields above still stand).
+   */
+  ledger: TeamLedger | null;
+}
+
+/**
+ * `GET /runs/:id/team`. The run's team transport and per-unit team state. A run that is not a team
+ * run (free text, a registered def: bug, chat, onboarding, …) answers `teamed: false`,
+ * `transport: null` and `units: []` — nothing to render, and no outage.
+ */
+export interface RunTeamResponse {
+  runId: string;
+  /** Whether the run is a team run at all. `false` ⇒ `transport` and `reason` are `null`. */
+  teamed: boolean;
+  /**
+   * For a team run: `"bus"`; `"none"` (the teamed run fell back to no team transport: render the
+   * "team transport unavailable" banner with `reason`); `"pending"` (not decided yet);
+   * `"unavailable"` (this daemon has no bus: the run is paused `team_transport` until the operator
+   * answers it). `null` for a run that is not a team run.
+   */
+  transport: 'bus' | 'none' | 'pending' | 'unavailable' | (string & {}) | null;
+  reason: string | null;
+  /** The first bus event id of the run's stream. */
+  streamFloor: number | null;
+  planRev: number | null;
+  /** The required fact the run waits on (its event type), if any. */
+  pending: string | null;
+  /** The run is terminal and its end is on record (a run that is not a team run: its status is terminal). */
+  ended: boolean;
+  units: RunTeamUnit[];
+  /** The run-level rows (`payload.ord` null: `path.*`, `plan.*`), ordered by `event_id`. */
+  rows: TeamRow[];
+}
+
+/**
+ * `POST /runs/:id/plan` body: a plan edit. At a `plan_approval` gate the edit IS the gate answer
+ * (the engine proposes, floor-fills and accepts it, or refuses it and re-opens the gate) and the
+ * route answers `{ status }`. Anywhere else on a live planned run (running, or paused at another
+ * gate) it is a MID-RUN edit (`Core.proposePlan`): `plan.steps` are the steps to ADD, held and
+ * applied at the run's next step boundary — its author approved it, so no gate opens — and the
+ * route answers {@link PlanProposalResponse}. A mid-run edit carries no `touch` / `override`.
+ */
+export interface EditPlanBody {
+  plan: LaunchPlan;
+  /**
+   * The caller's id for this edit: the engine's idempotency key for a mid-run edit, so a retried
+   * POST carrying the same id proposes once (`duplicate: true`). Omitted ⇒ the daemon mints a
+   * fresh UUID for that POST, so an omitted-id retry is a SECOND edit — send one to retry safely.
+   * A gate edit is keyed on its gate, not on this id.
+   */
+  requestId?: string;
+}
+
+/** `POST /runs/:id/plan` at a `plan_approval` gate: the run's status after the gate answer. */
+export interface EditPlanGateResponse {
+  status: SessionStatus;
+}
+
+/**
+ * `POST /runs/:id/plan` mid-run: the engine's `PlanProposal` (`Core.proposePlan`), what the held
+ * edit does to the run — read off the dry run it was validated by, since the author's own edit
+ * opens no gate. Refusals (a plan awaiting approval — edit it at the gate —, a started deliver
+ * step, a finished or unplanned run, an edit the revision refuses) answer 409 with the engine
+ * reason.
+ */
+export interface PlanProposalResponse {
+  /** The `plan.proposed` id the edit is published under. */
+  proposal_id: string;
+  /** `true`: this `requestId` was already taken — nothing new is held or published. */
+  duplicate: boolean;
+  /** The floor band of the rev the edit makes (`"40-69"`, …); `null` for a duplicate. */
+  band: string | null;
+  /** §8.5's high-risk rule on that rev: `true` = the edit moved the run into high risk. `null` for a duplicate. */
+  high_risk: boolean | null;
+  /** The floor phase types (catalog ids) the edit adds; empty for a duplicate. */
+  floor_added: string[];
+}
+
+/** `POST /runs/:id/plan`: a gate answer (`status`) or a mid-run proposal (`proposal_id`). */
+export type EditPlanResponse = EditPlanGateResponse | PlanProposalResponse;
+
+/** `POST /team/outbox/replay`: the engine's replay of `<state home>/team-outbox.ndjson`. */
+export interface TeamOutboxReplayReport {
+  /** `[idempotency key, bus event id]` of every fact that reached the bus, in publish order. */
+  published: Array<[string, number]>;
+  superseded: number;
+  invalid: number;
+  remaining: number;
+  /** `[run id, reason]` per lane that stopped. */
+  failures: Array<[string, string]>;
+}
+
+/** One phase type of the engine's catalog (`GET /catalog`, `Core.catalog`), in catalog order —
+ *  the row studio's phase picker renders. */
+export interface CatalogEntry {
+  id: string;
+  kind: StageKindPhase;
+  role: PhaseRole;
+  gate: GateSpec;
+  gate_type: GateType | null;
+  executes_code: boolean;
+  /** `"tool"`: a step of this entry supplies its own command (`deliver`); else `"agent"`. */
+  executor: 'agent' | 'tool';
+  validator_pin: string | null;
+  /** The entry carries a validator pin (a step may not remove or swap it). */
+  pinned: boolean;
+  /** That pin is the evidence floor. */
+  evidence_floor: boolean;
+  /**
+   * The entry declares re-verified evidence: a step of it is an acceptance requirement of the run
+   * that contains it (`test`, `domain_coverage`). ABSENT from an engine before the flag (api-types
+   * 0.46.0) — the daemon then fails a plan run's acceptance closed rather than guess.
+   */
+  verified_evidence?: boolean;
+  skill_ref: string | null;
+  /** The entry's one-line description; `null` when it has none. */
+  description: string | null;
+}
+
+/** `GET /catalog`. */
+export interface CatalogResponse {
+  entries: CatalogEntry[];
+}
+
+/** `POST /plans/preview` body: a draft plan, previewed as the `POST /runs {plan}` launch with the
+ *  same fields would decide it. */
+export interface PlanPreviewBody {
+  plan: LaunchPlan;
+  /** Only matters to a preset name, so it does not change a plan's preview. */
+  projectId?: string;
+  /** The launch's gate mode (`humanConfirm` on `POST /runs`); absent = auto. */
+  humanConfirm?: string;
+  /** The registered repo the launch would run on: a behavioural `touch` set is scored against its
+   *  code graph at the base the launch would start from (read locally, no fetch). An unregistered
+   *  repo is a 400. Absent ⇒ the fail-closed score (`graph: "unavailable"`). */
+  repoRef?: string;
+  /** The launch's delivery (`deliver` on `POST /runs`): `"pr"` hands the engine the launch's
+   *  deliver step, so the preview's floor carries `deliver` as the launch's would. Absent or
+   *  `"none"` ⇒ no deliver step (a plan launch's own default). */
+  deliver?: 'pr' | 'none';
+}
+
+/**
+ * `POST /plans/preview`: the engine's `PlanPreview` (`Core.previewPlan`) — what the launch would
+ * compute (precheck, intent score, floor fill, approval matrix, planning checks), persisting and
+ * publishing nothing. A refusal (the launch's own, an unregistered repo) is a 400.
+ */
+export interface PlanPreviewResponse {
+  /** The intent score (§8.2), its deterministic part, one reason per contribution. */
+  score: number;
+  deterministic: number;
+  reasons: string[];
+  /** The destructive signal the floor fill reads. */
+  destructive: boolean;
+  /** The floor band the score lands in (`"40-69"`, `"70-100"`, …). */
+  band: string;
+  high_risk: boolean;
+  /** The floor phase types the plan owes, in order. The steps the floor ADDED are the `steps`
+   *  with `added_by: "floor"`. */
+  floor: string[];
+  /** The floor override as recorded (manual mode only). */
+  floor_override: TeamPlanOverride | null;
+  /** The floor-filled steps; each carries `added_by`, and `floor_reason` when the floor added it. */
+  steps: TeamPlanStep[];
+  /** The def the run would plan from (`compose` of `steps`). */
+  def: WorkflowDef;
+  /** `true` ⇒ the launch would pause at a `plan_approval` gate before its first unit. */
+  pauses: boolean;
+  pause_reason: 'manual_mode' | 'high_risk' | 'override' | (string & {}) | null;
+  /** `"ready"`: the score read the repo's code graph. `"not_needed"`: a docs-only touch set (or no
+   *  creator and no touch set). `"unavailable"`: the fail-closed score (no repo, no or a stale
+   *  graph — `reasons` says which). `"pending_pa_scope"` (wicked-core#633, DES-TEAMING-002 X1;
+   *  api-types 0.47.0): a creator plan with no `touch` set — the launch runs the PA's read-only
+   *  `pa-scope` step first and scores the plan from its answer, so `score`, `band` and the floor
+   *  shown are the baseline's with `pa-scope` first, NOT the plan's final risk, and `pauses` is
+   *  manual mode's alone (an auto-mode launch may still pause once the PA's scope lands high). */
+  graph: 'ready' | 'not_needed' | 'unavailable' | 'pending_pa_scope';
+}
+
+// ── Standing orders (Studio OS behaviour 10; api-types 0.50.0) ─────────────────────────────────
+
+/**
+ * A standing order's structured rule — parsed from plain words by a seat and CONFIRMED by the
+ * operator before it is stored. `trigger.phase` is the phase the gate reviews (the reviewed unit's
+ * `phase_ref`) or `*`. The invariant: `approve` never answers the deliver gate, a plan approval,
+ * an escalation, a failure or a triage gate, and never a finding (the create route refuses a rule
+ * that approves `deliver`, `plan_approval` or a finding with a 400 `order_refused`).
+ */
+export interface StandingOrderRule {
+  scope: { kind: 'all' } | { kind: 'project'; projectId: string };
+  /** `band` (api-types 0.53.0, optional): the order matches only a run whose accepted plan landed in
+   *  that band (`"0-19"`, …); a run with no scored plan never matches a band-scoped order.
+   *  `preset` (api-types 0.56.0, optional): only a run launched from that preset (`team_plan.preset`).
+   *  `phase: "plan_approval"` with `action: "approve"` is a TRUST RECEIPT (0.56.0): accepted only
+   *  with `band: "0-19"`, a `preset` and a `project` scope, and it answers a run's plan gate only
+   *  when that open gate itself reports band 0-19 and no high risk. `deliver` is never approvable. */
+  trigger: { kind: 'gate'; phase: string; band?: string | undefined; preset?: string | undefined } | { kind: 'finding'; severity: 'high' | 'medium' | '*' };
+  action: 'approve' | 'hold' | 'notify';
+  activeWhen: 'away' | 'always';
+}
+
+export interface StandingOrder {
+  id: string;
+  /** The operator's own words. */
+  text: string;
+  rule: StandingOrderRule;
+  /** Unix millis. */
+  createdAt: number;
+}
+
+/** An outbound message a `notify` order wanted sent. Only ever QUEUED — the daemon sends nothing. */
+export interface QueuedStandingMessage {
+  id: string;
+  orderId: string;
+  orderText: string;
+  runId: string | null;
+  text: string;
+  /** Unix millis. */
+  at: number;
+  status: 'queued';
+}
+
+/** `GET /standing-orders`, and the answer to `PUT /standing-orders/away`. */
+export interface StandingOrdersState {
+  away: boolean;
+  /** Unix millis the flag turned on; `null` while present. */
+  awaySince: number | null;
+  orders: StandingOrder[];
+  outbox: QueuedStandingMessage[];
+}
+
+/** `PUT /standing-orders/away`. */
+export interface StandingAwayBody {
+  away: boolean;
+}
+
+/** `POST /standing-orders/parse` — the plain words one seat reads. */
+export interface ParseStandingOrderBody {
+  text: string;
+}
+
+/** `POST /standing-orders/parse`'s 200: the rule to show back for confirmation. `refused` is set
+ *  when storing it would be refused (the invariant), in plain words. A 422 carries the seat's own
+ *  `answer` when it could not produce a rule; 409 = no seat can take a turn; 502 = the seat failed. */
+export interface ParsedStandingOrder {
+  rule: StandingOrderRule;
+  seat: string;
+  refused?: string;
+}
+
+/** `POST /standing-orders` — the confirmed rule. 201 `{ order }`. */
+export interface CreateStandingOrderBody {
+  text: string;
+  rule: StandingOrderRule;
+}
+
+// ── Decided-gate history (api-types 0.53.0) ────────────────────────────────────────────────────
+
+/**
+ * One decided gate — `GET /gates/decided?since=<unix ms>` (newest first, at most 1000). One row per
+ * `gate.decided` audit line, joined to the engine's gate row for the same `(run, ord)` and to the
+ * run. What a skin needs for a seat's track record on a step, and for the preview of a proposed
+ * standing order (`phase` and `orderApprovable` are the order evaluator's own readings).
+ */
+export interface DecidedGate {
+  runId: string;
+  /** The unit the gate paused before; `null` when the decision named none (a plan edit). */
+  ord: number | null;
+  /** Unix millis. */
+  decidedAt: number;
+  decision: 'approve' | 'request_changes' | 'reject' | 'edit_plan';
+  /** Who decided: a person's actor id, or `standing-order:<id>`. */
+  actor: string;
+  /** A standing order decided it (the actor is `standing-order:<id>`). */
+  byOrder: boolean;
+  /** The engine's gate kind (`def`, `run_level`, `terminal`, `deliver`, `plan_approval`, …); `null` when unknown. */
+  gateKind: string | null;
+  /** The phase an order's trigger matches (`intake`, or the reviewed unit's phase); `null` when unknown. */
+  phase: string | null;
+  projectId: string | null;
+  /** The band the run's accepted plan landed in; `null` for an unscored run. */
+  band: string | null;
+  /** The unit whose work the gate judged (the newest creator before the gate) and its seat; `null` when none. */
+  creator: { seat: string; phase: string | null; ord: number } | null;
+  /** A standing order could have approved this gate (a phase-review gate of a run that lands no doctrine). */
+  orderApprovable: boolean;
+}
+
+/** `GET /gates/decided`'s 200. A malformed `since` answers 400. */
+export interface DecidedGatesResponse {
+  gates: DecidedGate[];
+}
+
+// ── Freeze deliveries (api-types 0.55.0) ───────────────────────────────────────────────────────
+
+/**
+ * `GET|PUT /deliveries/freeze` — the one switch that holds every deliver gate. While `frozen`, an
+ * approve of a gate that would run a deliver unit answers 409 `{code: "deliveries_frozen"}` and
+ * `POST /runs/:id/deliver` refuses the same way; the gate stays open, so unfreezing lets the same
+ * approve through. A run launched with `deliverGate: "auto"` has no gate and is not held.
+ * Audited as `deliveries.frozen {reason?}` / `deliveries.unfrozen`; a restart keeps the freeze.
+ */
+export interface DeliveryFreezeState {
+  frozen: boolean;
+  /** ISO time it was turned on; `null` while thawed. */
+  since: string | null;
+  /** The actor id that turned it on; `null` while thawed. */
+  by: string | null;
+  reason: string | null;
+}
+
+/** `PUT /deliveries/freeze`. `reason` (1–500 chars) is kept only when freezing. */
+export interface PutDeliveryFreezeBody {
+  frozen: boolean;
+  reason?: string;
+}
+
+// ── MCP tools registry (DES-MCP-TOOLS-001 §5, §8, slice S2; api-types 0.58.0) ─────────────────
+
+/**
+ * How crew reaches an upstream: an MCP server over stdio or streamable HTTP, or a plain REST API
+ * wrapped as tools from its OpenAPI document (`rest`, api-types 0.64.0).
+ */
+export type McpUpstreamKind = 'mcp-stdio' | 'mcp-http' | 'rest';
+/**
+ * A tool's class, from its own `tools/list` annotations (never from a carrier): `read` when
+ * `readOnlyHint` is true; else `destructive` unless `destructiveHint` is false; else `write`. A tool
+ * with no annotations, or with neither `readOnlyHint` nor `destructiveHint`, is `write`. An
+ * operator's `classOverride` wins.
+ */
+export type McpToolClass = 'read' | 'write' | 'destructive';
+/**
+ * `registered`: the schema the operator saved is the one the server lists. `unregistered`: the
+ * schema changed, or the server added the tool after the save; it is denied until previewed and
+ * saved again. `gone`: the server no longer lists it (kept so old records resolve).
+ */
+export type McpToolStatus = 'registered' | 'unregistered' | 'gone';
+/** `failing` after 3 consecutive failed probes; `never` = no probe has succeeded yet. */
+export type McpHealthState = 'ok' | 'failing' | 'never';
+/** `none` = the server needs no secret; `missing` = its reference resolves to nothing. */
+export type McpAuthState = 'none' | 'set' | 'missing';
+
+/** The spec's tool annotations, only the fields it defines. */
+export interface McpToolAnnotations {
+  title?: string;
+  readOnlyHint?: boolean;
+  destructiveHint?: boolean;
+  idempotentHint?: boolean;
+  openWorldHint?: boolean;
+}
+
+/**
+ * Where a server's secret comes from and where crew injects it. The registry stores this
+ * reference only, never a value. `ref` is `keychain:wicked-mcp/<name>` (written by
+ * `PUT /mcp/servers/:name/secret`) or `env:<NAME>` (the daemon's env). An `mcp-stdio` server gets
+ * the value in env variable `env`; an `mcp-http` or `rest` server in header `header`, after `prefix`.
+ */
+export interface McpAuthConfig {
+  ref: string;
+  env?: string;
+  header?: string;
+  prefix?: string;
+}
+
+/**
+ * `POST /mcp/servers/preview`. `mcp-stdio` takes `command` (+ `args`); `mcp-http` takes `url`.
+ * `rest` takes `url`, the base URL every call of the API is pinned to (its scheme, host and port,
+ * and its path as a prefix), plus its OpenAPI 3 document: `openapiUrl` (fetched by crew) or
+ * `openapi` (the document itself, pasted), never both. `operations` picks which operations become
+ * tools (by `operationId` or tool name); absent = all of them.
+ */
+export interface McpServerConfigBody {
+  /** 1–63 of `a-z 0-9 _ -`; the `<server>` of the subject `mcp:<server>/<tool>`. */
+  name: string;
+  kind: McpUpstreamKind;
+  command?: string;
+  args?: string[];
+  url?: string;
+  auth?: McpAuthConfig | null;
+  /** `rest` only: where crew fetches the OpenAPI 3 document (JSON or YAML). */
+  openapiUrl?: string;
+  /** `rest` only: the OpenAPI 3 document itself (instead of `openapiUrl`); at most 1 MB as JSON. */
+  openapi?: Record<string, unknown>;
+  /** `rest` only: the operations to wrap, by `operationId` or tool name; absent = all. */
+  operations?: string[];
+  /**
+   * The secret VALUE this server's keychain entry will hold (wicked-crew#719). The preview is
+   * probed with it and it is held with the preview; `POST /mcp/servers` writes it to the OS store
+   * as part of the save, so the secret and the registry row commit together — studio used to write
+   * the keychain itself first, and a failure between the two writes left a keychain entry with no
+   * server, or a server whose secret never landed. Requires `auth.ref` =
+   * `keychain:wicked-mcp/<name>`; `501` when the platform has no OS secret store. It is in no
+   * response, log, audit entry or file.
+   */
+  secret?: string;
+}
+
+/**
+ * How a `rest` tool turns its arguments into one HTTP request (api-types 0.64.0). The arguments are
+ * an ALLOWLIST: an argument that no map names is dropped, never sent (its name is disclosed in the
+ * result's `_meta["wicked/rest"].droppedArgs`). The request goes only to the server's base URL: a
+ * request that would leave its scheme, host, port or base path, or a redirect to another host, is
+ * refused before (or instead of) being followed, and recorded as a `guard_error`.
+ */
+export interface McpRestMapping {
+  method: 'GET' | 'HEAD' | 'OPTIONS' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+  /** The OpenAPI path, e.g. `/issues/{id}`; joined onto the base URL's path. */
+  pathTemplate: string;
+  /** argument → `{variable}` of `pathTemplate`. */
+  pathMap: Record<string, string>;
+  /** argument → query parameter. */
+  queryMap: Record<string, string>;
+  /** argument → request header (never the auth header, `Host`, `Cookie` or a hop-by-hop header). */
+  headerMap: Record<string, string>;
+  /** argument → top-level key of the JSON request body; `null` when the body is one argument or none. */
+  bodyMap: Record<string, string> | null;
+  /** The argument that is the whole JSON request body; `null` when the body is mapped by key or absent. */
+  bodyArg: string | null;
+  /** Every argument that is sent: the union of the maps and `bodyArg`. */
+  argAllowlist: string[];
+  timeoutMs: number;
+}
+
+export interface McpHealth {
+  state: McpHealthState;
+  consecutiveFailures: number;
+  checkedAt: string | null;
+  /** The last probe's error, with any secret scrubbed out. */
+  lastError: string | null;
+}
+
+export interface McpTool {
+  name: string;
+  /** A `rest` tool's request mapping (api-types 0.64.0); `null` for an MCP server's tool. */
+  rest?: McpRestMapping | null;
+  /** The policy token: `mcp:<server>/<tool>`. */
+  subject: string;
+  description: string | null;
+  annotations: McpToolAnnotations | null;
+  inputSchema: Record<string, unknown> | null;
+  derivedClass: McpToolClass;
+  classOverride: McpToolClass | null;
+  /** `classOverride ?? derivedClass`: what a policy sees. */
+  class: McpToolClass;
+  enabled: boolean;
+  status: McpToolStatus;
+  /** The saved schema's hash; `null` = never saved. */
+  schemaHash: string | null;
+  /** The hash the last probe saw. */
+  observedSchemaHash: string;
+}
+
+export interface McpServer {
+  name: string;
+  kind: McpUpstreamKind;
+  command: string | null;
+  args: string[];
+  url: string | null;
+  auth: McpAuthConfig | null;
+  /** `rest` only (api-types 0.64.0): the OpenAPI URL, `null` when the document was pasted. */
+  openapiUrl?: string | null;
+  /** `rest` only: the operations that were picked; `null` = all. */
+  operations?: string[] | null;
+  authState: McpAuthState;
+  enabled: boolean;
+  health: McpHealth;
+  registeredAt: string;
+  updatedAt: string;
+  tools: McpTool[];
+  /** Over the tools that are not `gone`. */
+  counts: { total: number; enabled: number; registered: number; read: number; write: number; destructive: number };
+}
+
+/**
+ * A server configured in a CLI's own home, by name only (never its command, URL or env).
+ * `origin: 'worker'` is a server in a seat's worker home, which no wicked-handed server may be.
+ */
+export interface McpDiscoveredServer {
+  name: string;
+  cli: string;
+  origin: 'operator' | 'worker';
+  /** The config file, relative to `~` or `<worker home>`. */
+  source: string;
+  /** Whether a registered server has the same name. */
+  managed: boolean;
+}
+
+/** `GET /mcp/servers`. */
+export interface McpServersResponse {
+  servers: McpServer[];
+  discovered: McpDiscoveredServer[];
+}
+
+/** The difference between the registered tools and a probe, by tool name. */
+export interface McpToolDiff {
+  added: string[];
+  removed: string[];
+  changed: string[];
+  unchanged: string[];
+}
+
+export interface McpPreviewTool {
+  name: string;
+  /** A `rest` tool's request mapping (api-types 0.64.0); `null` for an MCP server's tool. */
+  rest?: McpRestMapping | null;
+  subject: string;
+  description: string | null;
+  annotations: McpToolAnnotations | null;
+  inputSchema: Record<string, unknown> | null;
+  class: McpToolClass;
+  schemaHash: string;
+}
+
+/**
+ * `POST /mcp/servers/preview`'s 200. Save it with `POST /mcp/servers {previewHash}` before
+ * `expiresAt`. `diff` compares with the registered server of the same name, `null` when none.
+ * A server that does not answer is a 502 `probe_failed`.
+ */
+export interface McpPreviewResponse {
+  previewHash: string;
+  expiresAt: string;
+  server: {
+    name: string;
+    kind: McpUpstreamKind;
+    command: string | null;
+    args: string[];
+    url: string | null;
+    auth: McpAuthConfig | null;
+    openapiUrl?: string | null;
+    operations?: string[] | null;
+  };
+  serverInfo: { name: string; version: string } | null;
+  tools: McpPreviewTool[];
+  diff: McpToolDiff | null;
+  /** `rest` only (api-types 0.64.0): operations that could not be wrapped, each with why. */
+  skipped?: string[];
+  /**
+   * Each tool's decision per phase role × seat × mode under the current policies and approvals,
+   * judged as if this preview were saved now (api-types 0.63.0); see `withdrawOnSave`. `null` when
+   * the engine cannot preview.
+   */
+  policies?: McpPolicyPreviewResponse | null;
+}
+
+/** `POST /mcp/servers`. No `previewHash`, or one that is unknown or expired, is a 409. */
+export interface SaveMcpServerBody {
+  previewHash?: string;
+}
+
+/** `PATCH /mcp/servers/:name`. */
+export interface PatchMcpServerBody {
+  enabled: boolean;
+}
+
+/** `PATCH /mcp/tools/:subject` (subject URL-encoded). At least one field. */
+export interface PatchMcpToolBody {
+  enabled?: boolean;
+  classOverride?: McpToolClass | null;
+}
+
+/** `POST /mcp/servers/:name/test`'s 200: a failed probe is `ok: false` and counts toward `failing`. */
+export interface McpServerTestResponse {
+  ok: boolean;
+  error: string | null;
+  /** `null` when the probe failed. */
+  diff: McpToolDiff | null;
+  server: McpServer;
+}
+
+/** `PUT /mcp/servers/:name/secret`: one line, 8–8192 characters. */
+export interface PutMcpSecretBody {
+  value: string;
+}
+
+/** The value is never echoed; `ref` goes into the server's `auth.ref`. 501 = no OS secret store. */
+export interface McpSecretResponse {
+  ref: string;
+  set: true;
+}
+
+// ── MCP broker call path (DES-MCP-TOOLS-001 §6, §8 `POST /mcp/call`; slice S3) ─────────────────
+
+/** `POST /mcp/call`: what the garden shim sends. `token` is the worker's `WICKED_MCP_TOKEN`. */
+export interface McpCallBody {
+  token: string;
+  /** `mcp:<server>/<tool>`. */
+  subject: string;
+  /** The tool's arguments (a JSON object); absent = `{}`. */
+  args?: Record<string, unknown>;
+}
+
+/** How a brokered call ended. Every outcome but `ok` means the result was not handed back. */
+export type McpCallOutcome =
+  /** The call ran; `result` is the scrubbed upstream result (it may itself be a tool error, `isError`). */
+  | 'ok'
+  /** Refused by a policy or an engine gate before anything ran (403). The worker continues. */
+  | 'denied'
+  /** Waits for the operator's approval (first use of a server, or the run's mode) (409). */
+  | 'pending_approval'
+  /** The call ran, but the output policy withheld its result (403). */
+  | 'withheld'
+  /** The unit's call budget is spent (429). */
+  | 'budget_exhausted'
+  /** The tool failed 5 times in a row and is refused for 60 s (503). */
+  | 'breaker_open'
+  /** The upstream failed (502) or timed out (504). */
+  | 'upstream_error'
+  /**
+   * The call could not be judged, scrubbed or recorded, or (a `rest` tool) its request would have
+   * left the API's pinned host (`status.errorClass` `rest_host_escape`): refused, fail closed (500).
+   */
+  | 'guard_error';
+
+/** Who decided a call: an engine gate (`engine:mcp-*`), a steering rule, or the broker itself. */
+export type McpDecisionBy = string;
+
+/** `POST /mcp/call`'s answer, on every status. Never carries a secret; `result` only on `ok`. */
+export interface McpCallResponse {
+  outcome: McpCallOutcome;
+  subject: string;
+  /** The call record's span id (`GET /mcp/usage` and the run's Governance panel resolve it). */
+  callId: string | null;
+  /** The scrubbed `tools/call` result — only when `outcome` is `ok`. */
+  result?: Record<string, unknown>;
+  /** The rules or gates that decided (deny, ask, withheld). */
+  ruleIds: string[];
+  /** Why the result is not handed back; absent on `ok`. */
+  reason?: string;
+  /** What the worker can do instead. */
+  remedy?: string;
+  /** `pending_approval` only: the subject the operator is asked to approve. */
+  pending_approval?: string;
+  /** `denied` / `withheld`: the call was refused (the unit continues). */
+  denied?: true;
+}
+
+export type McpCallDecision = 'allow' | 'ask' | 'deny' | 'guard_error';
+
+/**
+ * One call record (`<state home>/mcp/calls.ndjson`), OTel span shaped. Arguments and results are
+ * NEVER captured: only the subject, the decision, timings and the byte count.
+ */
+export interface McpCallRecord {
+  /** The run id, or `null` when the token resolved to no unit (a guard error before judging). */
+  traceId: string | null;
+  spanId: string;
+  /** The unit, `<ord>:<attempt>`; `null` with `traceId`. */
+  parentSpanId: string | null;
+  name: 'mcp.tool.call';
+  start: string;
+  end: string;
+  ms: number;
+  status: { code: 'ok' | 'error'; errorClass: string | null };
+  decision: { decision: McpCallDecision; by: McpDecisionBy; ruleIds: string[]; claimId: string | null };
+  outcome: McpCallOutcome;
+  attrs: {
+    'mcp.subject': string;
+    'mcp.class': McpToolClass | null;
+    'mcp.kind': McpUpstreamKind | null;
+    'wicked.seat': string | null;
+    'wicked.phase': string | null;
+    'wicked.carrier': 'shim';
+    'bytes.out': number;
+    retries: number;
+  };
+}
+
+/** The `/ws` frame each call record rides (additive CoreEvent contract: skins that don't know it ignore it). */
+export interface McpCallCompletedFrame {
+  type: 'mcpCallCompleted';
+  record: McpCallRecord;
+}
+
+// ── The unit's tool list (DES-MCP-TOOLS-001 §8, slice S4; api-types 0.65.0) ─────────────────────
+
+/**
+ * `POST /mcp/tools`: what the garden shim's `list` sends. The token travels in the body, never the
+ * query string, so it stays out of request logs.
+ */
+export interface McpToolsBody {
+  token: string;
+}
+
+/** One tool the token's unit may try, judged now with no arguments. A certain deny is left out. */
+export interface McpVisibleTool {
+  /** `mcp:<server>/<tool>`. */
+  subject: string;
+  class: McpToolClass;
+  /** `allow` = a call runs; `ask` = it waits for the operator's approval. */
+  decision: 'allow' | 'ask';
+  ruleIds: string[];
+  /** Why a call would ask. */
+  reason?: string;
+  /** The tool's description, from the server's `tools/list`. */
+  description: string | null;
+  /** The tool's argument JSON schema, from `tools/list`. */
+  inputSchema: Record<string, unknown> | null;
+}
+
+/** `POST /mcp/tools`'s answer: the unit the token is bound to and its tools. */
+export interface McpToolsResponse {
+  unit: { runId: string; ord: number; attempt: number; phase: string; seat: string };
+  tools: McpVisibleTool[];
+}
+
+// ── MCP policies: the preview matrix and approvals (DES-MCP-TOOLS-001 §4.5, §4.7, §8, slice S6; api-types 0.63.0) ──
+
+/** A policy decision: `ask` = the call waits for the operator's approval (it does not run). */
+export type McpDecision = 'allow' | 'ask' | 'deny';
+/**
+ * The phase role a matrix row stands for: `creator` = a creator phase with full write posture;
+ * `evaluator` = an evaluator phase (read-only); `recon` = a neutral phase with a read-only posture.
+ */
+export type McpPhaseRole = 'creator' | 'evaluator' | 'recon';
+/** The run's mode (studio's launch autonomy): Gate every step / Gate by risk / Auto. */
+export type McpRunMode = 'ask' | 'balanced' | 'autonomous';
+
+/** One matrix cell: what a call from a unit of this shape would get now. Nothing is recorded. */
+export interface McpPolicyCell {
+  role: McpPhaseRole;
+  seat: string;
+  mode: McpRunMode;
+  phaseId?: string;
+  decision: McpDecision;
+  /** The class the engine judged (the tool's override, else its annotations; none = `write`). */
+  class: McpToolClass;
+  /** The rules that decided: `engine:*` gates first, then steering rule ids (each a Steering row). */
+  ruleIds: string[];
+  obligations: string[];
+  reason: string | null;
+}
+
+/** Whether a tool is approved in each ledger, and by which token (`server` = `mcp:<server>`). */
+export interface McpApprovalState {
+  /** `MCP-FIRST-USE`: the first use of a server asks in every mode until approved. */
+  firstUse: 'server' | 'tool' | null;
+  /** `MCP-POSTURE-WRITE`: in balanced mode a write asks until approved. */
+  write: 'server' | 'tool' | null;
+}
+
+export interface McpPolicyPreviewTool {
+  subject: string;
+  server: string;
+  tool: string;
+  class: McpToolClass;
+  status: McpToolStatus;
+  /** The server and the tool are both enabled. */
+  enabled: boolean;
+  /** What the broker sends the engine: enabled and `registered`; otherwise D-5 denies it. */
+  registered: boolean;
+  approval: McpApprovalState;
+  /** One per role × seat × mode, in `roles`, `seats`, `modes` order. */
+  cells: McpPolicyCell[];
+}
+
+/** `POST /mcp/policies/preview`. Every field narrows; none = every tool, role, seat and mode. */
+export interface McpPolicyPreviewBody {
+  /** One tool: `mcp:<server>/<tool>`. */
+  subject?: string;
+  server?: string;
+  phaseRole?: McpPhaseRole;
+  seat?: string;
+  mode?: McpRunMode;
+  /** A workflow phase id a policy may name (`review`, `build`, ...). */
+  phaseId?: string;
+}
+
+/** `POST /mcp/policies/preview`'s 200, and `McpPreviewResponse.policies`. */
+export interface McpPolicyPreviewResponse {
+  roles: McpPhaseRole[];
+  seats: string[];
+  modes: McpRunMode[];
+  phaseId: string | null;
+  /**
+   * Server previews only (`[]` elsewhere): the approvals saving this preview withdraws, because a
+   * saved tool's schema changed. The cells are judged under the CURRENT approvals, so a tool listed
+   * here (or every tool, when `mcp:<server>` is listed) asks again after the save.
+   */
+  withdrawOnSave: string[];
+  tools: McpPolicyPreviewTool[];
+}
+
+/** An approved subject and the ledgers that hold it. */
+export interface McpApproval {
+  subject: string;
+  scope: 'server' | 'tool';
+  firstUse: boolean;
+  write: boolean;
+}
+
+/** A registered, enabled tool that would ask in balanced mode, and why. */
+export interface McpPendingApproval {
+  subject: string;
+  server: string;
+  tool: string;
+  class: McpToolClass;
+  needs: Array<'first-use' | 'write'>;
+}
+
+export interface McpLedgerState {
+  id: string;
+  /** `false` = the mcp-defaults pack was not seeded; approvals are refused (503). */
+  present: boolean;
+  /** A retired first-use ledger still asks: the engine reads it either way. */
+  retired: boolean;
+}
+
+/** `GET /mcp/approvals`. */
+export interface McpApprovalsResponse {
+  approved: McpApproval[];
+  pending: McpPendingApproval[];
+  ledgers: { firstUse: McpLedgerState; write: McpLedgerState };
+}
+
+/**
+ * `POST /mcp/approvals`, an audited edit of the ledger rules' `excludes`. `mcp:<server>` approves
+ * the server's FIRST USE (`MCP-FIRST-USE`); its write tools still ask in balanced mode.
+ * `mcp:<server>/<tool>` approves that tool's first use and its writes (`MCP-POSTURE-WRITE` too).
+ * An approval never lifts an engine gate or an explicit deny rule.
+ */
+export interface McpApprovalBody {
+  subject: string;
+}
+
+/** `POST /mcp/approvals` and `DELETE /mcp/approvals/:subject`: the ledger rules the edit changed. */
+export interface McpApprovalResponse {
+  subject: string;
+  approved: boolean;
+  rulesChanged: string[];
+}
+
+// ── MCP usage: the fold over the call records (DES-MCP-TOOLS-001 §7 Usage, §8 `GET /mcp/usage`; slice S7; api-types 0.66.0) ──
+
+/** Every call record in a window, split by the broker's decision. */
+export interface McpDecisionCounts {
+  allow: number;
+  ask: number;
+  deny: number;
+  guard_error: number;
+}
+
+/**
+ * The numbers a set of call records folds to. `ran` counts the calls the broker let through
+ * (`decision: allow`); the error rate and the latency percentiles are over those calls only, since
+ * a denied or asked call never reached an upstream. Percentiles are nearest-rank: the value at
+ * position `ceil(q * n)` of the sorted durations. `null` = no call ran.
+ */
+export interface McpUsageStats {
+  calls: number;
+  decisions: McpDecisionCounts;
+  ran: number;
+  /** Ran calls whose status is `error` (an upstream failure or a tool error, `isError`). */
+  errors: number;
+  errorRate: number | null;
+  p50Ms: number | null;
+  p95Ms: number | null;
+  p99Ms: number | null;
+}
+
+/** One tool's row of the per-tool table. */
+export interface McpUsageTool extends McpUsageStats {
+  subject: string;
+  server: string;
+  tool: string;
+  /** The class the engine judged on the newest record; `null` = never judged (a guard error). */
+  class: McpToolClass | null;
+  /** The seats that called it, sorted. */
+  seats: string[];
+  lastCall: string;
+}
+
+/** One server's totals: its row's "last used" and "calls over the window". */
+export interface McpUsageServer {
+  server: string;
+  calls: number;
+  decisions: McpDecisionCounts;
+  lastCall: string;
+}
+
+/** The drill-down: one tool × seat × run. `runId: null` = calls the broker refused before judging. */
+export interface McpUsageRun {
+  subject: string;
+  seat: string | null;
+  runId: string | null;
+  calls: number;
+  decisions: McpDecisionCounts;
+  /** Ran calls whose status is `error`, as in {@link McpUsageStats}. */
+  errors: number;
+  lastCall: string;
+}
+
+/**
+ * A tool chain: `from` then `to`, two consecutive calls of one unit attempt (by start time), with
+ * different subjects. `count` = how often; `runs` = in how many runs.
+ */
+export interface McpUsageChain {
+  from: string;
+  to: string;
+  count: number;
+  runs: number;
+}
+
+/** One UTC day the window touches (its first day is partial), days with no calls included. */
+export interface McpUsageDay {
+  day: string;
+  calls: number;
+  decisions: McpDecisionCounts;
+}
+
+/**
+ * `GET /mcp/usage?days&subject&seat&decision`. `days` is 1-30 (default 7); the window is the last
+ * `days` × 24 h. Every filter narrows every section, except `chains`: a chain is folded from the
+ * unit's calls under the seat and decision filters, then kept when either end is `subject`.
+ * Records older than 30 days are folded into `calls-daily.ndjson` and are not in any window.
+ */
+export interface McpUsageResponse {
+  days: number;
+  since: string;
+  until: string;
+  filters: { subject: string | null; seat: string | null; decision: McpCallDecision | null };
+  totals: McpUsageStats;
+  /** Most calls first, then by subject. */
+  tools: McpUsageTool[];
+  /** Most calls first, then by name. */
+  servers: McpUsageServer[];
+  /** Newest first, at most 200. */
+  runs: McpUsageRun[];
+  /** Most frequent first, at most 20. */
+  chains: McpUsageChain[];
+  /** Oldest first. */
+  daily: McpUsageDay[];
+  /** The seats seen in the window before any filter (the seat filter's options), sorted. */
+  seats: string[];
+  /** Lines of `calls.ndjson` that did not parse as a call record. */
+  skipped: number;
+}