wicked-crew-api-types 0.36.0 → 0.38.0

package/index.d.ts

@@ -137,6 +137,70 @@ export type RoutingInfo =
   | { method: 'evaluator_distinct'; winner: string; was: string }
   | { method: 'tool' };
 
+/**
+ * `GET /health` (api-types 0.37.0 — the shape was previously undeclared here; `status`,
+ * `version` and `ping` are unchanged since 0.1). `capabilities` (additive) names what the
+ * running daemon + its engine addon can actually do, so a client never promises a behaviour the
+ * deployment cannot keep:
+ *   - `deliverGate` — the engine pauses before the composed `deliver` phase pushes and opens the
+ *     PR unless the launch said `deliverGate: 'auto'` (F-E2E-030; wicked-core-ts ≥ 0.7.24).
+ *     `false` (or the whole object absent — a daemon before 0.7.33) ⇒ delivery follows verify
+ *     UNATTENDED; a composer must say so instead of promising a gate, and must not send
+ *     `deliverGate` (an older daemon's launch schema rejects it).
+ *   - `revisesPr` (api-types 0.38.0, additive) — the daemon accepts `LaunchRunBody.revisesPr`
+ *     (crew#550). Absent or `false` ⇒ a composer must NOT send it (an older daemon's launch
+ *     schema rejects it with a 400) and says "this daemon cannot revise a PR" instead.
+ *
+ * The object is the named {@link HealthCapabilities} since 0.38.0 — the same shape 0.37.0 declared
+ * inline, so nothing a 0.37.0 client compiled against moves.
+ */
+export interface HealthResponse {
+  status: string;
+  version: string;
+  ping: string;
+  capabilities?: HealthCapabilities;
+  /**
+   * Blockers the daemon reports while it still SERVES (additive; wicked-core#411 / wicked-crew#497).
+   * One kind today — `state-home.unregistered`: the daemon's state home holds an entry the worker
+   * Read fence cannot classify, so every governed launch would be refused and `POST /runs` answers
+   * **409** `state_home_unregistered` until it is gone (`GET /diagnostics.stateHome` has the
+   * detail). ABSENT when there is nothing to say, and on a daemon before this field. A composer
+   * shows it as the blocker it is; `status` stays `ok` — the daemon is up, it refuses to launch.
+   */
+  warnings?: HealthWarning[];
+  /**
+   * The BASE skill posture for the NEXT launch (crew#554; additive) — what a composer's confirm
+   * line renders as `discipline skill: <name> gen N` (or `MISSING — runs will be refused at
+   * intake` under `baseSkillPolicy: 'require'`, `MISSING — runs proceed without it` under
+   * `'warn'`). `null` when the setting is off or the skills seam is disabled; absent on a daemon
+   * before this field. Cached by the daemon — reading it costs no I/O.
+   */
+  baseSkill?: BaseSkillPosture | null;
+}
+
+/**
+ * `GET /health.capabilities` (api-types 0.38.0 — named; 0.37.0 declared the same shape inline on
+ * {@link HealthResponse}). What the running daemon + its engine addon can actually do; every key
+ * is a promise the deployment keeps, so a client reads it before offering the behaviour.
+ */
+export interface HealthCapabilities {
+  /** See {@link HealthResponse} — the engine's deliver gate exists (wicked-core-ts ≥ 0.7.24). */
+  deliverGate: boolean;
+  /**
+   * `LaunchRunBody.revisesPr` is accepted (crew#550; crew ≥ 0.7.36). ABSENT on a daemon before
+   * the field — read as `false`: do not send `revisesPr` to such a daemon.
+   */
+  revisesPr?: boolean;
+}
+
+/** One `GET /health.warnings[]` entry (additive; wicked-core#411 / wicked-crew#497). */
+export interface HealthWarning {
+  /** `state-home.unregistered` today; open for later kinds. */
+  kind: string;
+  severity: 'warning' | 'error';
+  message: string;
+}
+
 /** A run (`AgentSession`). */
 export interface AgentSession {
   id: string;
@@ -147,6 +211,14 @@ export interface AgentSession {
   clis: string[];
   status: SessionStatus;
   human_confirm: HumanConfirm;
+  /**
+   * Whether the run's deliver phase may push and open its PR WITHOUT a human confirming it
+   * first (F-E2E-030; api-types 0.37.0, additive). `false` — the engine pauses before the `deliver` Tool unit
+   * whatever `human_confirm` says; `true` — the launch opted out explicitly (`deliverGate:
+   * 'auto'`). ABSENT on runs from an engine that predates the deliver gate (wicked-core-ts <
+   * 0.7.24): such an engine delivers unattended — render no gate promise for it.
+   */
+  auto_deliver?: boolean;
   unit_ix: number;
   attempt: number;
   workdir: string | null;
@@ -282,6 +354,23 @@ export interface AgentSession {
    * now; a joined `AgentSession.cost` is a follow-up once that store exists.
    */
   created_at?: number;
+  /**
+   * When this run reached a TERMINAL status — unix SECONDS (api-types 0.38.0; crew#496 / studio#230).
+   * Mirrors {@link created_at}: daemon-derived at DTO assembly on BOTH `GET /runs` and
+   * `GET /runs/:id` from a `run.ended` audit entry the daemon records when it sees the run's
+   * terminal frame (`sessionCompleted` | `sessionFailed` | `runCancelled`), joined like
+   * {@link retry_of} / {@link guidance} and hydrated from the same trail scan at boot. Together with
+   * {@link created_at} ("started" ≡ "created" — the ONE launch instant) it gives a run its own clock;
+   * a skin prefers these over the moment it happened to attach.
+   *
+   * ABSENT — never `null`, never fabricated — when the daemon has no `run.ended` entry: a run
+   * still live, a run that terminalled before this field existed or before THIS daemon booted
+   * (no re-emission at boot), a lost trail, or the one crash window between the engine's status
+   * write and the daemon's synchronous audit record. Read with `typeof === 'number'`; a duration
+   * or a "finished N minutes ago" MUST be omitted for an undated run, never derived from now.
+   * Distinct from {@link finished_at} (engine-side unix MILLIS, retention bookkeeping).
+   */
+  ended_at?: number;
   /**
    * The interactive DOCUMENT this run answered (wave 6, F-4R2-006 root fix; api-types 0.36.0) —
    * daemon-joined at DTO assembly on `GET /runs` and `GET /runs/:id` from the interactive seams'
@@ -346,6 +435,14 @@ export interface WorkUnit {
    * before the field existed, and on an older engine.
    */
   executes_code?: boolean;
+  /**
+   * The BASE skill this unit follows (wicked-core#468; additive, skip-if-none on the wire): the
+   * run's role-keyed discipline skill, copied onto every AGENT unit at plan time (never a Tool
+   * unit). The unit header renders it with the unit's `role` as `discipline: <name> §<role> gen N`,
+   * `N` from the unit's `skillsSnapshotHanded.gen` frame. Absent on runs without one, on units
+   * planned before the field existed, and on an older engine.
+   */
+  base_skill_ref?: string | null;
 }
 
 /** A run plus its ordered units (`SessionView`) — the shape `GET /runs` returns. */
@@ -412,6 +509,14 @@ export interface OnboardRef {
  * the message — no operator hand-edit involved.
  */
 export interface SeatHealth {
+  /**
+   * `inactive` is NO LONGER PRODUCED from crew 0.7.36 (api-types 0.38.0 doc; DES-L3 R5): the daemon
+   * stopped flipping a seat on `stepFailed{workerError}`, on quota/401/timeout phrases and on
+   * repeated ACP fallback — seat standing is the engine's per-run ballot bench
+   * (`AgentSession.benched_seats`) plus the seat's own auth refusal (`RosterSeat.auth`). The token
+   * stays in the union so a daemon before 0.7.36 still parses; a reader treats it exactly as
+   * before (a seat-level error, recovery by the probe or a restart).
+   */
   status: 'active' | 'inactive';
   /** Bounded excerpt of the last seat-level error; present while `inactive`. */
   message?: string;
@@ -496,12 +601,18 @@ export interface RosterSeat {
    * `councilSeatFailed` evidence (`non_zero_exit` / `timed_out`, the derivative `benched` kind
    * excluded), folded over a bounded window (`window_ms`) and cleared by the seat's next ok unit
    * output. `council_eligible` is false while it is present.
+   *
+   * @deprecated ABSENT from crew 0.7.36 (DES-L3 R5b): the daemon-wide council-failure ledger is
+   * retired — the engine benches a dead seat per run at its own ballot threshold and the run DTO
+   * carries the bench (`AgentSession.benched_seats`). Removed from this contract one minor later;
+   * a reader must tolerate absence today.
    */
   council_bench?: RosterSeatCouncilBench;
   [k: string]: unknown;
 }
 
-/** `RosterSeat.council_bench` (api-types 0.35.0). */
+/** `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 {
   /** Primary ballot failures inside the window. */
   failures: number;
@@ -602,6 +713,26 @@ export interface GateInfo {
 export interface GateDecision {
   approve: boolean;
   amend?: string;
+  /**
+   * The decision ARM (api-types 0.38.0, additive; DES-L1 PR-1B / crew PR-2, crew ≥ 0.7.36 on
+   * wicked-core-ts ≥ 0.7.27). Absent = today's two-arm mapping: `approve: true` approves (retry
+   * the same unit, `amend` steers it), `approve: false` rejects (cancels the run, keeps a dirty
+   * worktree). `'request_changes'` — an ESCALATION gate only: rewind to the most recent creator
+   * phase at or before the gated unit, hand it the evaluator's findings (+ `amend` as the note)
+   * and re-dispatch it (`unitReworkAmended{scope: 'request_changes'}` → `resumed` →
+   * `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.
+   */
+  action?: 'approve' | 'request_changes' | 'reject';
+  /**
+   * 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
+   * phase at or after the cursor receives it (`unitReworkAmended{scope: 'creator'}`) while the
+   * cursor dispatches unamended: the intake steer that must reach the fix phase, not triage.
+   * Identical text already present on the target is not appended twice.
+   */
+  amendScope?: 'cursor' | 'creator';
 }
 
 /**
@@ -620,6 +751,12 @@ export interface ReassignRequest {
  * fields cover the frames the daemon and the studio inspect; the index
  * signature keeps the shape additive-safe so new variants pass through
  * untouched (DES-STUDIO-001 §2.1, §5.1).
+ *
+ * Exact per-frame shapes for consumers that narrow on `type`: the cockpit
+ * {@link InsightEvent} union, the gate-evidence {@link GateEvidenceEvent}
+ * union, and — typed in api-types 0.38.0 as the engine already emits them —
+ * the 11-key {@link GateEscalatedEvent}, {@link SandboxPostureEvent} and
+ * {@link WorktreeRetainedEvent}.
  */
 export interface CoreEvent {
   type: string;
@@ -746,6 +883,9 @@ export interface CoreEvent {
   degradedReason?: string | null;
   degraded_reason?: string | null;
   seatConstraint?: string | null;
+  /** `unitDistributed` (wicked-core#461): the evaluator ≠ creator fallback as a field — see
+   *  `UnitDistributedEvent.distinctnessFallback`. */
+  distinctnessFallback?: 'creator_seat' | null;
   /** `gateEvaluated` (wave 6, F-7R2-005): `true` when NOTHING gated the unit — render as UNGATED. */
   ungated?: boolean;
   /** `gateEvaluated` (wave 6): why, when `ungated`. */
@@ -920,8 +1060,20 @@ export interface RecordedEvent extends CoreEvent {
    * is required and spans every frame of the run; that one is optional and scoped to a stream. The
    * name is inherited from the wire and narrowed here rather than renamed, because the wire is what
    * `runEvents` returns.
+   *
+   * Across a daemon RESTART the counter is re-seeded from the trail's highest `seq` + 1, so `seq`
+   * stays strictly increasing over the whole trail — but two records of one run may be separated
+   * by an engine that lost every in-flight frame in between (api-types 0.38.0; crew#513).
    */
   seq: number;
+  /**
+   * Stamped `true` on exactly ONE record per restart: the first frame a fresh engine writes for a
+   * run whose trail already existed (wicked-core `event_log.rs`; api-types 0.38.0, crew#513). Every
+   * other record omits the key — never `false`. A timeline reads it as a "daemon restarted here"
+   * boundary: frames the previous process never wrote are not coming, and the run's `ended_at` may
+   * be absent for that reason.
+   */
+  daemonRestarted?: true;
 }
 
 /**
@@ -942,6 +1094,20 @@ export interface UnitDispatchedEvent {
   session: string;
   ord: number;
   attempt: number;
+  /**
+   * The BASE skill directive this dispatch carries (wicked-core#468; additive): the run's
+   * role-keyed discipline skill and the `§<role>` section the unit was told to follow. Emitted
+   * unconditionally by an engine that has it — `null` when the run declares none; ABSENT on an
+   * older engine. The generation it is handed from is the same unit's `skillsSnapshotHanded.gen`
+   * (the handoff is where the generation is known truthfully). A run page renders
+   * `discipline: <name> §<role> gen N`.
+   *
+   * `handed` (api-types 0.38.0, additive; wicked-core#479 — typed AHEAD of its producer, which
+   * lands in the wave-3 core-ts): `true` when the admitted snapshot holds the base skill and the
+   * carrier delivered it (the skill form is not `Unloaded`); `false` when the run only NAMED it.
+   * ABSENT ⇒ UNKNOWN (an engine before the field) — render `gen ?`, never "not handed".
+   */
+  baseSkill?: { name: string; role: 'creator' | 'evaluator' | 'neutral'; handed?: boolean } | null;
 }
 
 /** §3 B3 — token/cost burn for one unit run. `costUsd` is `null` when no cost is known. */
@@ -1056,6 +1222,16 @@ export interface GateEvaluatedEvent {
    *  validator gated it) — `"no eligible judge seat distinct from creator \`claude\` (roster: …;
    *  benched: …)"`. `null` when a judge ran or none was wanted; absent on an older engine. */
   judgeSkippedReason?: string | null;
+  /**
+   * The evaluator's own `VERDICT:` token (api-types 0.38.0, additive; DES-L1 PR-1A, wicked-core-ts
+   * ≥ 0.7.27): after trimming leading decoration, the LAST line whose first token is `VERDICT`
+   * decides — `"PASS"`, `"FAIL"`, or whatever token the seat wrote (`"CONDITIONAL"` is not PASS).
+   * Parsed for an Evaluator-role agent unit only; `null` for creator / neutral / tool units and
+   * when no such line exists (then `denial.source` is `evaluator_verdict` and the gate escalates
+   * `verdict_not_pass`). ABSENT on an engine before the field — a reader treats absent as "not
+   * parsed", never as PASS.
+   */
+  evaluatorVerdict?: string | null;
 }
 
 /** Foundation wave: session started with enriched context. */
@@ -1208,15 +1384,88 @@ export interface ValidationPinAttachedEvent {
   criterion: string;
 }
 
-/** P2 — a HumanConfirmIf gate escalated to human review. */
+/**
+ * P2 — a HumanConfirmIf gate escalated to human review. Since wicked-core#464 every fold DENIAL
+ * parks the run here too (followed by `awaitingHuman{gateKind: 'escalation'}`), and `condition`
+ * names the CLASS: `evaluator_mutated_worktree` (the worktree guard) · `boundary_deny` (input
+ * governance refused a tool call) · `dead_seat` (the seat is unusable — signed out / not installed /
+ * benched) · `floor_failed` (a deterministic floor: repo checks, pinned validator, substance,
+ * deliverables) · `verdict_not_pass` (the layer-2 judge, a worker failure, or — wicked-core-ts ≥
+ * 0.7.27 — the evaluator's own `VERDICT` line), or a def-declared `human_confirm_if` condition
+ * (`defGate: true`). `verdictSummary` is the denial reason.
+ *
+ * The seven additive keys (api-types 0.38.0 — the engine has emitted all eleven fields, twelve JSON
+ * keys with `type`, since wicked-core#464; `event.rs::GateEscalated`) carry what a decision arm
+ * needs without re-reading the unit. ABSENT on a daemon whose engine predates them; when present
+ * they are ALWAYS all present.
+ */
 export interface GateEscalatedEvent {
   type: 'gateEscalated';
   session: string;
   ord: number;
   condition: string;
   verdictSummary: string;
+  /** The attempt whose output — persisted as the unit's REJECTED transcript — this gate reviews. */
+  attempt?: number;
+  /**
+   * The raw denial LAYER token (`gateEvaluated.denial.source`): `worktree_guard` ·
+   * `input_governance` · `dead_seat` · `repo_checks` · `repo_checks_timeout` · `pinned_validator`
+   * · `substance` · `deliverables` · `agent_validator` · `worker_failure` · `evaluator_verdict`
+   * (0.7.27) · `governance`. `""` (EMPTY) = a hook veto whose source identity was folded away
+   * (`actor.rs` `boundary_deny` arm with no structured denial) — a reader keys copy on
+   * `(condition, denialSource)` and treats `""` beside `boundary_deny` as input governance.
+   */
+  denialSource?: string;
+  /** `true` when the unit's OWN def declared this escalation (`human_confirm_if`); `false` = engine-authored. */
+  defGate?: boolean;
+  /** The phase produced output text — the precondition of an "accept the captured output" arm. */
+  outputCaptured?: boolean;
+  /**
+   * The worktree guard's restore outcome, mirroring {@link WorktreeRestoredEvent} — meaningful for
+   * `evaluator_mutated_worktree` only; `false` / `[]` / `null` for every other class.
+   */
+  restored?: boolean;
+  /** The paths the restore discarded (`git status --porcelain` status + path), as {@link WorktreeRestoredEvent.discarded}. */
+  discarded?: { status: string; path: string }[];
+  /** The `refs/wicked/suggestions/<run>/<ord>/<attempt>` ref holding the discarded changes; `null` when none. */
+  suggestionRef?: string | null;
 }
 
+/**
+ * F-E2E-039 (api-types 0.38.0; emitted since wicked-core `pipeline.rs` armed it): the containment
+ * POSTURE a unit's worker actually ran under, once per dispatch, so a skin can say it instead of
+ * implying an OS sandbox that was never armed. `os` — the registry seat record arms an OS write
+ * boundary (macOS `sandbox-exec` / Linux `bwrap`); `advisory` — the record arms none, so
+ * containment is the worktree guard plus the command-text fences, which a shell can evade.
+ * `reason` is the engine's sentence naming the deciding record/flag.
+ */
+export type SandboxPostureEvent = {
+  type: 'sandboxPosture';
+  session: string;
+  ord: number;
+  /** The registry seat key. */
+  cli: string;
+  posture: 'os' | 'advisory';
+  reason: string;
+};
+
+/**
+ * F-RC1-064 / F-E2E-028 (api-types 0.38.0; emitted since wicked-core#456): a TERMINAL run's
+ * worktree was KEPT because it holds uncommitted work the run branch does not carry — named on the
+ * wire so a skin can point the operator at the path. Cancel and the terminal reap apply the same
+ * rule; the retention window (`WICKED_COMPLETED_WORKTREE_KEEP_DAYS`) then reaps it clean-only. A
+ * clean tree is reaped and emits nothing. Session-level (no `ord`). Both new frames are `type`
+ * aliases on purpose — see {@link EvaluatorMutatedWorktreeEvent}: an alias satisfies `CoreEvent`'s
+ * index signature and relays through the CoreEvent-typed broadcast seams unchanged.
+ */
+export type WorktreeRetainedEvent = {
+  type: 'worktreeRetained';
+  session: string;
+  /** The kept worktree's absolute path (the engine's; a skin never resolves it). */
+  path: string;
+  reason: string;
+};
+
 /** P2 — a tool-executor command was dispatched (non-agent unit). */
 export interface ToolExecutorDispatchedEvent {
   type: 'toolExecutorDispatched';
@@ -1323,6 +1572,51 @@ export interface RepoCheckRun {
   /** The last 4 KiB of each stream — the evidence, verbatim. */
   stdoutTail: string;
   stderrTail: string;
+  /**
+   * The baseline-diff floor's evidence (api-types 0.38.0 — the seven keys the engine has emitted
+   * since wicked-core#469 / #476). PRESENT ON EVERY CHECK from that engine on: the one producer of
+   * this camelCase form, `event.rs::check_run_json`, writes all seven every time — `0` / `null` / `[]`
+   * when there is nothing to say (the Rust `Option` → `null` rule; the struct's own
+   * `skip_serializing_if` governs the persisted record, not this frame). ABSENT only on an older
+   * engine — the `?:` is that one case, so read with `== null`, never `=== undefined`. `boundS` — the
+   * EFFECTIVE wall-clock bound the check ran under, seconds (base × host-load factor; a bare number,
+   * `0` when unknown); `boundNote` — how it was derived, for the operator (`null` when none).
+   */
+  boundS?: number;
+  boundNote?: string | null;
+  /**
+   * Failure identifiers streamed off the runner's output (`test a::b ... FAILED`, ` FAIL file >
+   * name`, `path: error TS1234: …`) — what the baseline diff compares. `[]` when the runner's format
+   * is not one the scanner knows (the diff then compares exit codes).
+   */
+  failureIds?: string[];
+  /**
+   * Set when the check FAILED and the same check was run on the base (`base`): `regression` (head
+   * failures absent on the base — denies) or `pre_existing_in_sandbox` (equal failure sets — never
+   * this change's doing); `floor_env_mismatch` was emitted by engines before wicked-core-ts 0.7.27
+   * and is retired. An OPEN string — new tokens may follow; `null` when the check passed,
+   * timed out, could not run, or no base comparison was possible (the check then denies as before).
+   */
+  classification?: string | null;
+  /** Head failures that ALSO fail on the base (never this change's doing); `[]` when none. */
+  preExisting?: string[];
+  /** Head failures ABSENT on the base — the regressions that deny; `[]` when none. */
+  regressions?: string[];
+  /** The same check run on the run BASE, when the floor ran it; `null` otherwise. */
+  base?: RepoCheckBaseRun | null;
+}
+
+/**
+ * `RepoCheckRun.base` — the same check on the run base (api-types 0.38.0; wicked-core
+ * `repo_checks.rs::BaseRun`, serialised by `event.rs::base_run_json`). Typed as an OPEN object this
+ * release; the engine writes all four keys every time: `head` (the base commit), `cached` (read back
+ * from this run's cache), `run` (a nested check run — `null` when the base could not be run) and
+ * `error` (why not: export failed, the base declares no such check, its install failed, the repo
+ * opted out — the head check then denies fail-closed; `null` when it ran). The fields are named in
+ * the next minor (DES-L2 2C); read them through `unknown` narrowing until then.
+ */
+export interface RepoCheckBaseRun {
+  [k: string]: unknown;
 }
 
 /** wicked-core F-039 — the engine ran the repository's OWN checks in the worktree for the def's
@@ -1594,6 +1888,15 @@ export interface UnitReworkAmendedEvent {
   amendment: string;
   /** The unit's description after the amendment was injected. */
   updatedDescription: string;
+  /**
+   * WHICH unit received the text and WHY (api-types 0.38.0, additive; DES-L1 PR-1B, wicked-core-ts ≥
+   * 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'`.
+   */
+  scope?: 'cursor' | 'creator' | 'request_changes';
 }
 
 /** P2 — a worker's ApplyStepResult arrived and output is ready to be gated. Fires before GateDecided.
@@ -1680,6 +1983,20 @@ export interface UnitDistributedEvent {
   /** WHY the candidate seats were narrowed BEFORE the council voted (core#401): a non-portable
    *  skill constrained the unit to a claude seat. `null` when every roster seat was a candidate. */
   seatConstraint: string | null;
+  /**
+   * The evaluator ≠ creator DISCLOSURE as a field (wicked-core#461, crew#556): `'creator_seat'` when a
+   * review/test unit STAYS on a seat that built what it checks because no eligible seat distinct from
+   * the builders admits it — a single-eligible-seat roster, or a bench that emptied the pool
+   * (`degradedReason` then says which; on a bench-free single-seat roster it stays `null`, so this
+   * field is the ONLY disclosure). `null` otherwise. The fallback seat is always a still-eligible one:
+   * a benched or dead seat is never the fallback.
+   *
+   * OPTIONAL on this side of the wire deliberately: the engine emits the key unconditionally (`null`,
+   * never absent — the `seatConstraint` rule) from the wicked-core release carrying #461 on, but an
+   * older engine does not send it at all, and this contract must read frames from both. Consumers
+   * guard with `== null`, never `=== undefined`.
+   */
+  distinctnessFallback?: 'creator_seat' | null;
   /** @deprecated api-types 0.36.0 — the engine emits `routingMethod`; removed in 0.37. */
   routing_method?: 'council' | 'degraded' | 'evaluator_distinct' | 'tool';
   /** @deprecated api-types 0.36.0 — the engine emits `agreementPct`; removed in 0.37. */
@@ -2052,6 +2369,11 @@ export interface SkillBaselineRecord {
  *     the portable form names that skill (`wicked-garden-<x>`) instead;
  *   - `requires-harness:claude` — the author declared `metadata.requires-harness: claude` in the
  *     frontmatter: the skill genuinely needs the Claude harness (not an authoring defect).
+ *   - `claude-dispatch` (api-types 0.38.0; crew ≥ 0.7.36, DES-L6 D-21) — the body CALLS a Claude
+ *     Code dispatch primitive (`Task(`, `Skill(`, `context: fork`, `AskUserQuestion`, `TaskCreate`)
+ *     that no other seat has: a pi/opencode/codex worker cannot follow it. The portable form is the
+ *     plain-prose Hand-off paragraph. Reported by the publisher; garden's lint fails the same
+ *     skill (12.38.0). An older daemon never emits the token.
  */
 export type SkillPortabilityReason =
   | 'plugin-root'
@@ -2059,7 +2381,8 @@ export type SkillPortabilityReason =
   | 'cwd-script'
   | 'relative-link'
   | 'cross-skill-path'
-  | 'requires-harness:claude';
+  | 'requires-harness:claude'
+  | 'claude-dispatch';
 
 /** Per-reason portability of a skill (F-079, api-types 0.34.0) — reported beside `portable`. */
 export interface SkillPortability {
@@ -2358,6 +2681,17 @@ export interface SkillMutationResult extends SkillAnalyzeResult {
  *  (`snapshot: null`), not a 409. */
 export interface SkillPublishResult extends SkillAnalyzeResult {
   snapshot: { gen: number; path: string; contentHash: string; skills: number } | null;
+  /** The BASE skill posture AFTER this publish (crew#554): `present: false` with a `finding` is the
+   *  "published a snapshot without the discipline skill" warning. Absent on a daemon before it. */
+  baseSkill?: BaseSkillPosture | null;
+  /**
+   * `true` when the publish found NOTHING to publish (api-types 0.38.0; crew#547 / DES-L6, crew ≥
+   * 0.7.36): the effective tree's `contentHash` equals the current generation's, so no new
+   * `snapshots/<gen>/` was minted, `current` did not move and `snapshot` is the CURRENT generation
+   * (its `gen` unchanged). ABSENT (never `false`) on a publish that staged a generation, and on a
+   * daemon before the field — a skin shows "already published as gen N", not a new generation.
+   */
+  unchanged?: true;
 }
 
 /** `POST /skills/refresh-baseline` 200 body — the three-way merge per FILE (baseline_old /
@@ -2379,6 +2713,9 @@ export interface SkillRefreshResult extends SkillAnalyzeResult {
   removed: string[];
   /** Skills flagged `conflict` by this refresh. */
   conflicts: string[];
+  /** The BASE skill posture AFTER this refresh (crew#554): a refresh moves the CATALOG, not the handed
+   *  generation, so `inCatalog: true, present: false` reads "publish to hand it". Absent on a daemon before it. */
+  baseSkill?: BaseSkillPosture | null;
 }
 
 /** The 409 body of a `/skills` mutation whose `expectedRevision` is stale — a CAS conflict, the
@@ -3000,6 +3337,30 @@ export interface LaunchRunBody {
    * omit the field entirely against pre-0.18 servers.
    */
   deliver?: 'pr' | 'none';
+  /**
+   * Who confirms the deliver phase (F-E2E-030; api-types 0.37.0, additive). `'human'` — the default when omitted:
+   * the ENGINE pauses before the composed `deliver` Tool unit pushes the run branch and opens the
+   * PR, whatever `humanConfirm` says (the push leaves the machine under the daemon's active gh
+   * account, so it is confirmed unless the caller opts out). `'auto'` — the caller's EXPLICIT
+   * opt-out: the push and PR follow verify unattended; a client sending it must name the posture
+   * "auto-deliver" to its operator. `humanConfirm: 'none'` is NOT an opt-out (it is that field's
+   * default and typo fallback). Requires wicked-core-ts ≥ 0.7.24 / crew ≥ 0.7.33 for the gate to
+   * exist at all — read `AgentSession.auto_deliver` to learn whether the engine knows it. An
+   * older daemon's launch schema rejects the field with a 400 — omit it against such servers.
+   */
+  deliverGate?: 'human' | 'auto';
+  /**
+   * REVISE an existing pull request instead of opening a new one (api-types 0.38.0, additive;
+   * crew#550 / DES-L9, crew ≥ 0.7.36 on wicked-core-ts ≥ 0.7.27): the number of an OPEN same-repo PR.
+   * The daemon resolves its head branch (`gh pr view` in the registered clone), the engine bases the
+   * run's worktree on that head, and the deliver phase pushes exactly the run's commits to that
+   * branch and comments the run record on the PR — no second PR, no rebase. Needs `repoRef` and
+   * `workflow` (400 without), a resolved `deliver: 'pr'` (409 otherwise; an explicit
+   * `deliver: 'none'` is a 400), and the PR must be OPEN and not from a fork (409 naming why).
+   * Send it ONLY when `GET /health.capabilities.revisesPr === true` — an older daemon's strict
+   * launch schema rejects the key with a 400.
+   */
+  revisesPr?: number;
   /**
    * Retry lineage (DES-UX-001 §8.3, CREW-UX-3; api-types 0.8.0): the id of the run this
    * launch retries. Must name an EXISTING run id — an unknown id fails the launch (400 with
@@ -3185,6 +3546,15 @@ export interface WorkflowDef {
   phases: PhaseDef[];
   /** True for built-in workflows that have dedicated entry points and must not appear in the work-mode selector. */
   is_system?: boolean;
+  /**
+   * The BASE skill every agent phase of THIS workflow follows (wicked-core#468; additive, engine
+   * ≥ the release carrying it — an older engine's strict def parser refuses the key). The engine
+   * leads every unit prompt with `Invoke your skill "<base>" … and follow its §<role> section`
+   * before the phase's `skill_ref` directive. Absent ⇒ the daemon's `SystemSettings.baseSkillRef`
+   * default (exported as `WICKED_BASE_SKILL_REF`); `""` ⇒ an explicit opt-out for this workflow.
+   * Gated at intake: a launch whose snapshot lacks the skill is refused before any unit is planned.
+   */
+  base_skill_ref?: string | null;
 }
 
 /** Top-level requirements_graph.json artifact (schema 1.0.0). */
@@ -3249,7 +3619,15 @@ export interface CodeGraphEdge { src: string; tgt: string; }
 export interface CodeGraphData {
   nodes: CodeGraphNode[];
   edges: CodeGraphEdge[];
+  /** Counts of the SERVED SLICE (`graph-view --limit`, `SystemSettings.graphNodeLimit`) — what is in `nodes`/`edges`. */
   stats: { nodeCount: number; edgeCount: number; fileCount: number };
+  /**
+   * Whole-graph counts (api-types 0.38.0, additive; crew#505 / F-RC1-100): what the repository's
+   * estate database holds in total, from `wicked-estate stats`, so a tile can read "150 of 5,470
+   * symbols shown" instead of presenting the slice as the repo. ABSENT when the stats line did not
+   * parse or on a daemon before the field — then only the slice is known; never substitute `stats`.
+   */
+  totals?: { nodes: number; edges: number; files: number };
 }
 
 /**
@@ -3311,6 +3689,26 @@ export interface SystemSettings {
    * launches (those are always `'none'`).
    */
   deliverDefault?: 'pr' | 'none';
+  /**
+   * The BASE skill every governed agent unit follows (crew#554 / wicked-core#468; additive): the
+   * frontmatter name the daemon exports as the engine-config default `WICKED_BASE_SKILL_REF`, so
+   * the engine leads EVERY unit prompt with `Invoke your skill "<base>" … and follow its §<role>
+   * section` (`creator` | `evaluator` | `neutral`) ahead of the phase's own `skill_ref` directive.
+   * A workflow def's own `base_skill_ref` overrides it (`""` there = opt-out for that workflow).
+   * Shipped default `"wicked-garden-governed-worker"`; `""` = OFF (the variable is deleted).
+   * Absent reads as the shipped default.
+   */
+  baseSkillRef?: string;
+  /**
+   * What a published snapshot WITHOUT the base skill means (crew#554; additive). `'warn'` (the
+   * default): the daemon exports the variable ONLY when the current generation holds the skill —
+   * otherwise runs proceed without the discipline directive and `GET /diagnostics.skills` carries a
+   * `skills.base-skill` WARNING (a fresh install lacks the skill until the garden that ships it is
+   * published). `'require'`: the variable is always exported and the engine REFUSES every launch at
+   * intake until a generation holding the skill is published (`POST /runs` → 422
+   * `base_skill_refused`); the finding is an `error`.
+   */
+  baseSkillPolicy?: 'warn' | 'require';
   /**
    * 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
@@ -3363,6 +3761,18 @@ export interface SystemSettings {
   [key: `studio.${string}`]: unknown;
 }
 
+/**
+ * `GET /settings` → 200 (api-types 0.38.0 — the body's first named type; the shape `{ settings }`
+ * is unchanged since 0.1). `path` (additive; DES-L10 PR-L10-6, crew ≥ 0.7.35) is the ABSOLUTE
+ * path of the settings file the daemon reads and writes (`WICKED_CREW_SYSTEM_SETTINGS` honoured),
+ * so a skin names the real file instead of a guessed default. ABSENT on a daemon before the field
+ * — render "the daemon's settings file", never a fabricated path.
+ */
+export interface SettingsResponse {
+  settings: SystemSettings;
+  path?: string;
+}
+
 // ── Requirements management (server-side search + overrides; crew api/requirements.ts) ──
 export interface RequirementSummary {
   key: string;
@@ -3997,6 +4407,31 @@ export interface ChatListResponse {
   chats: ChatSummary[];
 }
 
+/**
+ * Token/cost burn of ONE seat's chat turn (api-types 0.38.0; DES-L5, crew ≥ 0.7.35 on wicked-core-ts
+ * ≥ 0.7.26) — mirrors the engine's `Usage` (`workflow.rs`) as `chatReply.usage`: `null` on bridges
+ * that emit no usage (pi, agy). `costUsd` is `null` when no price is known — never `0`.
+ */
+export interface ChatUsage {
+  inputTokens: number;
+  outputTokens: number;
+  cacheReadTokens: number;
+  cacheCreationTokens: number;
+  costUsd: number | null;
+}
+
+/**
+ * One record of a chat's persisted transcript (api-types 0.38.0; DES-L5 D-13): the daemon appends
+ * the operator's message and every seat's reply to `<state home>/chats/<id>.jsonl` for the CHAT'S
+ * LIFETIME (dropped on `chatClosed`, cleared at boot) and serves them on `GET /chats/:id.messages`
+ * in append order. `at` is epoch millis; `turnId` is always present (only turn-stamped frames are
+ * persisted). A `seat` record's `ok: false` text names the reason (a budget eviction reads
+ * "exceeded the N s turn budget … target it on your next message to re-seat it").
+ */
+export type ChatTranscriptRecord =
+  | { at: number; turnId: string; kind: 'user'; text: string; seats: string[] }
+  | { at: number; turnId: string; kind: 'seat'; cliKey: string; text: string; ok: boolean; usage: ChatUsage | null };
+
 /** `GET /chats/:id` → 200. */
 export interface ChatDetailResponse {
   chatId: string;
@@ -4007,6 +4442,12 @@ export interface ChatDetailResponse {
    *  the admission copy survives a reload; `null` for a chat this daemon did not open; absent on a
    *  daemon predating the field. */
   refused?: ChatSeatRefusal[] | null;
+  /**
+   * The chat's transcript so far (api-types 0.38.0, additive; DES-L5, crew ≥ 0.7.35) — `[]` for a
+   * chat with no persisted turn yet; ABSENT on a daemon predating the field (a rejoin then shows
+   * "session continues" without history). Unbounded — a reply may be up to the engine's cap.
+   */
+  messages?: ChatTranscriptRecord[];
 }
 
 // ── Project code graph (DES-PROJECT-001; the co-located multi-repo graph) ──────
@@ -4594,6 +5035,10 @@ export interface DiagnosticsResponse {
   skills: DiagnosticsSkills;
   /** Whether the engine's governance evidence is LANDING (api-types 0.31.0, crew#495) — see `DiagnosticsGovernance`. */
   governance: DiagnosticsGovernance;
+  /** The state-home classification (additive; wicked-core#411 / wicked-crew#497) — see
+   *  `DiagnosticsStateHome`. `null` on a daemon booted without the watch (some tests); ABSENT on a
+   *  daemon before this field. */
+  stateHome?: DiagnosticsStateHome | null;
 }
 
 // ── Diagnostics — governance store + dead letters (api-types 0.31.0, crew#495 / F-022) ─────────
@@ -4702,14 +5147,19 @@ export interface DiagnosticsSkillsFinding {
    *  crew#535) = the CURRENT generation was published under OTHER portability rules than the daemon
    *  now runs — accepted (the snapshot is never rewritten; the runtime stays `published`), the rows
    *  that now derive differently are named (`SkillsManifestResponse.current.drift`), and a publish
-   *  records the running rules and clears it. */
+   *  records the running rules and clears it; `skills.base-skill` (crew#554 / wicked-core#468) =
+   *  the configured BASE skill (`SystemSettings.baseSkillRef`) is not in the current generation —
+   *  a `warning` under `baseSkillPolicy: 'warn'` (runs proceed without the discipline directive),
+   *  an `error` under `'require'` (the engine refuses every launch at intake); cleared by a publish
+   *  that hands it. Also carried as `DiagnosticsSkills.baseSkill.finding`. */
   kind:
     | 'skills.fallback'
     | 'skills.blocked'
     | 'skills.config'
     | 'skills.source'
     | 'skills.manifest'
-    | 'skills.stale-rules';
+    | 'skills.stale-rules'
+    | 'skills.base-skill';
   severity: 'warning' | 'error';
   message: string;
 }
@@ -4738,6 +5188,141 @@ export interface DiagnosticsSkills {
    *  layout. `null` only when `disabled`. */
   stateHome: string | null;
   findings: DiagnosticsSkillsFinding[];
+  /** The BASE skill posture (crew#554) — the System page's "discipline skill" row beside the skills
+   *  generation; its `finding` (when the generation lacks the skill) also rides `findings`. `null`
+   *  when the setting is off or the seam is `disabled`. A daemon before this field omits the key
+   *  (read it as `null`). */
+  baseSkill: BaseSkillPosture | null;
+}
+
+/**
+ * The BASE skill in force for the next launch (crew#554 — the launcher half of wicked-core#468).
+ * The engine leads EVERY agent unit's prompt with one role-keyed directive naming this skill and
+ * the unit's `§<role>` section; a launch whose handed snapshot lacks it is refused at intake. The
+ * daemon judges the setting against the CURRENT published generation and exports
+ * `WICKED_BASE_SKILL_REF` per `policy` (see `SystemSettings.baseSkillPolicy`). Carried by
+ * `GET /health.baseSkill`, `GET /diagnostics.skills.baseSkill`, `POST /skills/publish` and
+ * `POST /skills/refresh-baseline` results, and the 422 `base_skill_refused` launch body.
+ */
+export interface BaseSkillPosture {
+  /** The frontmatter name (`wicked-garden-governed-worker` by default). */
+  name: string;
+  policy: 'warn' | 'require';
+  /** The published generation the engine is handed holds the skill — the intake admission passes. */
+  present: boolean;
+  /** The editor catalog holds the skill enabled — the NEXT publish hands it. */
+  inCatalog: boolean;
+  /** The generation judged (`current`), or `null` when nothing is published. */
+  gen: number | null;
+  /** What `WICKED_BASE_SKILL_REF` is exported as right now: the name, or `null` = unset (runs proceed without a base skill). */
+  engineInput: string | null;
+  /** The `skills.base-skill` finding when the generation lacks the skill (`warning` under `warn`, `error` under `require`); `null` when it holds it. */
+  finding: DiagnosticsSkillsFinding | null;
+}
+
+/**
+ * `POST /runs` **422** (crew#554): the engine refused the launch AT INTAKE because the handed skills
+ * snapshot lacks the run's base skill (`SkillsError::BaseSkillRefused` — `baseSkillPolicy:
+ * 'require'`, or a workflow def's own `base_skill_ref`). Nothing was planned or persisted; no run
+ * id exists. `error` is the engine's message naming the skill; `baseSkill` is the daemon's posture
+ * at refusal time; `remedy` names the fix (publish a generation holding it, or relax the policy).
+ */
+export interface BaseSkillRefusedResponse {
+  code: 'base_skill_refused';
+  error: string;
+  baseSkill: BaseSkillPosture | null;
+  remedy: string;
+}
+
+// ── Diagnostics — the state-home classification (additive; wicked-core#411 / wicked-crew#497) ───
+//
+// The worker Read fence over the daemon state home is an EXPLICIT registry (design v3.1 §1): an
+// entry it does not classify refuses the launch by name, fail closed. Right — but it used to fire
+// at the run's FIRST WORKER, after a planning council and the intake gate, labelled "triage judge
+// errored", while the daemon booted green (F-RC1-011, F-RC2-020, F-032/F-033). Now the daemon
+// surveys the state home at boot and on every read of this block, logs one error line per entry
+// (`recentErrors`), warns on `GET /health`, and answers `POST /runs` 409 `state_home_unregistered`
+// while a handed snapshot derives a state home with such an entry; the engine refuses at intake.
+
+/** One entry the state-home registry cannot classify. */
+export interface DiagnosticsStateHomeEntry {
+  /** The entry's name as listed. */
+  name: string;
+  /** Its absolute path on the daemon host. */
+  path: string;
+  /** `state-home` — a top-level entry; `skills-root` — a child of `<state home>/skills` that is
+   *  neither the read slot (`snapshots`) nor a registered denied child. */
+  level: 'state-home' | 'skills-root';
+}
+
+/** One finding of the state-home survey — the same text `GET /health.warnings[]` carries. */
+export interface DiagnosticsStateHomeFinding {
+  kind: 'state-home.unregistered';
+  severity: 'error';
+  message: string;
+}
+
+/**
+ * `GET /diagnostics` → `stateHome`: which state home the worker Read fence classifies, every entry
+ * it cannot classify there, who classified, and whether that refuses launches. Honest throughout:
+ * a field the daemon cannot answer is `null`, never invented.
+ */
+export interface DiagnosticsStateHome {
+  /** The state home surveyed, or `null` when neither input yields one. */
+  stateHome: string | null;
+  /** `snapshot` — derived from the handed `WICKED_SKILLS_SNAPSHOT` by its
+   *  `<state home>/skills/snapshots/<gen>` shape (the directory the fence classifies); `db` — the
+   *  core db's parent, surveyed for information when no snapshot is handed. */
+  derivedFrom: 'snapshot' | 'db' | null;
+  /** Who classified: the engine (`Core.preflightStateHome`, the fence's own code), crew's registry
+   *  copy on an addon without it, or nobody (`unavailable`: no db path and no snapshot). */
+  source: 'engine' | 'crew' | 'unavailable';
+  unregistered: DiagnosticsStateHomeEntry[];
+  /** `true` exactly when a HANDED snapshot derives a state home with unregistered entries — the
+   *  condition the engine refuses every launch on, and what `POST /runs` answers 409 for. */
+  refusesLaunches: boolean;
+  findings: DiagnosticsStateHomeFinding[];
+  /** What to do, in operator terms — the same text the 409 body and every finding end with. */
+  remedy: string;
+  /** Why the survey could not run (an unresolvable snapshot, an unlistable directory), or `null`. */
+  error: string | null;
+  /** When this survey was taken (unix ms). */
+  checkedAt: number;
+}
+
+/**
+ * The `POST /runs` **409** body while the state home refuses launches (`code:
+ * 'state_home_unregistered'`): the configuration error as fields — every entry and the remedy —
+ * so a composer can show the blocker instead of a bare string.
+ */
+export interface StateHomeBlockerBody {
+  error: string;
+  code: 'state_home_unregistered';
+  stateHome: string | null;
+  unregistered: DiagnosticsStateHomeEntry[];
+  remedy: string;
+}
+
+/**
+ * The `POST /runs` **409** body when the engine refuses the launch at intake because the roster has
+ * NO eligible seat (`code: 'no_eligible_seat'`; wicked-core#461's typed `NoEligibleSeat`, crew#556):
+ * the plan needs a seat and every configured seat was benched by the launcher — signed out, out of
+ * quota, not installed (crew's `council_eligible: false` → the engine's `health.usable: false`).
+ * Nothing was persisted, nothing reached the wire. A 409, not a 400: the body is well-formed and the
+ * same request succeeds once a seat is signed in — the conflict is with the roster's current
+ * standing (the `state_home_unregistered` rule), and not a 5xx: the engine is healthy and said no.
+ */
+export interface NoEligibleSeatBody {
+  /** The engine's own text: `no eligible seat for <run>: <benched> — sign a seat in, or add one, …`. */
+  error: string;
+  code: 'no_eligible_seat';
+  /** The refused run id (never persisted). */
+  runId: string;
+  /** The bench, seat by seat with its cause — `"2 of 2 seats benched: codex (signed out — launcher),
+   *  copilot (quota exhausted — launcher)"` — the engine's `benched_summary`, verbatim. */
+  benched: string;
+  /** What to do, in operator terms. */
+  remedy: string;
 }
 
 // ── Memory proposal queue (DES-MEM-FACETED-001 §5.0, api-types 0.21.0) ─────────

package/package.json

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