wicked-crew-api-types 0.31.0 → 0.33.0

package/index.d.ts

@@ -341,8 +341,31 @@ export interface RepoEntry {
    * Optional in the TYPE, mandatory in practice: an addon predating the field omits it, and
    * `codeGraphDb()` in the daemon's `repoPaths.ts` is where that turns into a loud error. Never
    * join this path yourself — six independent spellings is what FINDING-069 was.
+   *
+   * Since wicked-core#406 the path is `<daemon state home>/repo-graphs/<key>/estate.db` — never
+   * inside `root_path`; a checkout's in-tree `.codegraph/` is reported in `findings`, not adopted.
    */
   code_graph_db?: string;
+  /**
+   * Diagnostics about the checkout the engine wants shown on the repo card (wicked-core#406) —
+   * derived by the engine on every read like `code_graph_db`, never authoritative in the record.
+   * An empty array for a clean checkout; optional in the TYPE only because an addon predating the
+   * field omits it. Today's codes: `in_tree_code_graph_ignored` (the checkout carries a
+   * `.codegraph/` an older engine indexed in-tree — ignored; `path` names the directory and
+   * `message` says how to clear it) and `code_graph_root_unresolvable` (no repo-graph root
+   * resolves for this daemon, so `code_graph_db` is empty).
+   */
+  findings?: RepoFinding[];
+}
+
+/** One engine diagnostic on a registered repo (`RepoEntry.findings[]`; wicked-core#406). */
+export interface RepoFinding {
+  /** Stable machine code (`snake_case`) a consumer switches on. */
+  code: string;
+  /** Operator-facing explanation: what was found, why it is ignored, how to clear it. */
+  message: string;
+  /** The filesystem path the finding is about, or `null` when it has none. */
+  path: string | null;
 }
 
 /** The run id of the onboarding run launched when a repo was registered (`GET /repos/:id/onboard`). */
@@ -567,6 +590,12 @@ export interface CoreEvent {
   denialReason?: string | null;
   /** `gateEvaluated`: the final deny-dominant decision over all layers (mirrors `gateDecided.allow`). */
   combined?: boolean;
+  /** `gateEvaluated` (wicked-core#431, api-types 0.33.0): WHO rendered `agentVerdict` — the council seat key
+   *  the layer-2 judge ran under; `null` when no judge ran, and on the bus-mediated path. */
+  judgeCli?: string | null;
+  /** `gateEvaluated` (wicked-core#431): whether that judge was identity-distinct from the work's author
+   *  (`true` = the rotation pick, `false` = the single default runner); `null` when no judge ran. */
+  judgeDistinct?: boolean | null;
   // sessionStarted enrichment fields (snake_case — serde wire names)
   workflow_id?: string | null;
   cli_count?: number;
@@ -665,7 +694,10 @@ export interface CoreEvent {
   /** campaignNodeStarted / campaignNodeAwaitingHuman: the node's attempt-keyed Run id. */
   runId?: string;
   // assumptionRecorded (external-transform convention) — camelCase per event_to_json
-  kind?: string;
+  /** `assumptionRecorded`: the assumption kind; `councilSeatFailed`: the failure branch;
+   *  `evaluatorToolCallDenied` (wicked-core#431, api-types 0.33.0): the ACP `toolCall.kind` — `null`
+   *  when the agent sent none. Widened to admit that `null`; every other producer still sends a string. */
+  kind?: string | null;
   library?: string;
   transform?: string;
   known?: boolean;
@@ -846,7 +878,11 @@ export interface UnitDenial {
 
 /** §3 B1 — the gate's decision depth, emitted alongside `gateDecided`. `denial` is the structured
  *  twin of `denialReason`: `null` when the gate approved, else the winning layer (deny-dominates) —
- *  `worktree_guard` and `repo_checks` are the two wicked-core F-036/F-039 layers. */
+ *  `worktree_guard` and `repo_checks` are the two wicked-core F-036/F-039 layers. `judgeCli` /
+ *  `judgeDistinct` (wicked-core#431 / F-3R2-007, api-types 0.33.0) name WHO rendered `agentVerdict`,
+ *  so evaluator ≠ creator is auditable from the event stream alone (compare with the unit's
+ *  `unitDistributed.cli`). Both keys are ALWAYS present: `null` when no judge ran (`agentVerdict`
+ *  is `null` too) and on the bus-mediated evaluator path, where the seat is not reported back. */
 export interface GateEvaluatedEvent {
   type: 'gateEvaluated';
   session: string;
@@ -862,6 +898,13 @@ export interface GateEvaluatedEvent {
   denialReason: string | null;
   denial: UnitDenial | null;
   combined: boolean;
+  /** The council seat key the layer-2 judge ran under (`codex`, `pi`, …) — WHO rendered
+   *  `agentVerdict`. `null` when no judge ran, and on the bus-mediated path. */
+  judgeCli: string | null;
+  /** Whether that judge seat was IDENTITY-DISTINCT from the work's author: `true` for the rotation
+   *  pick, `false` when the judge fell back to the single default runner (prompt-only independence).
+   *  `null` when no judge ran or the seat is unknown. */
+  judgeDistinct: boolean | null;
 }
 
 /** Foundation wave: session started with enriched context. */
@@ -911,13 +954,36 @@ export interface AcpSessionStartedEvent {
   acpSessionId: string;
 }
 
-/** P1 — ACP unavailable or failed for a CLI; the run continues with single-shot fallback. */
+/**
+ * `acpFallback.fallbackKind` — WHY a unit left the ACP carrier for the wrapped (single-shot) one:
+ * - `binary_unavailable` / `session_died` / `auth_required` — the ACP session could not be had; the
+ *   run continues single-shot (a FAILURE of the seat's transport or account, counted by seat health);
+ * - `governance_requires_wrapped` — a governed unit on a seat whose ACP adapter cannot enforce input
+ *   governance is routed to the wrapped carrier by design (crew#276);
+ * - `read_only_requires_wrapped` (wicked-core#431 / F-3R2-009, api-types 0.33.0) — an
+ *   `executes_code: false` unit (an evaluator, a recon rung, a review) on an ACP seat NOT admitted to
+ *   input governance (pi-acp, codex-acp) is routed to the wrapped carrier BEFORE any ACP turn, where
+ *   the read-only lever is an argv fact (`--sandbox read-only` / `--exclude-tools edit,write`). No
+ *   per-call {@link EvaluatorToolCallDeniedEvent} exists on that route — consumers must not wait for one.
+ * The two `*_requires_wrapped` kinds are deliberate routing, not failures — never a seat-health signal.
+ * Open-ended (`string & {}`) so a newer engine's kind parses in an older consumer.
+ */
+export type AcpFallbackKind =
+  | 'binary_unavailable'
+  | 'session_died'
+  | 'auth_required'
+  | 'governance_requires_wrapped'
+  | 'read_only_requires_wrapped'
+  | (string & {});
+
+/** P1 — ACP unavailable or failed for a CLI, or the unit was deliberately routed off ACP; the run
+ *  continues on the wrapped carrier. `fallbackKind` says which (see {@link AcpFallbackKind}). */
 export interface AcpFallbackEvent {
   type: 'acpFallback';
   session: string;
   cliKey: string;
   reason: string;
-  fallbackKind: string;
+  fallbackKind: AcpFallbackKind;
 }
 
 // ── P2 observability events ─────────────────────────────────────────────────
@@ -1066,6 +1132,17 @@ export type EvaluatorMutatedWorktreeEvent = {
   afterTree: string;
   headMoved: boolean;
   changed: WorktreeChangedPath[];
+  /** wicked-core#431 / F-3R2-010 (api-types 0.33.0): whether the engine RESTORED the creator's tree
+   *  (`beforeTree`) in the worktree right after detecting the mutation — so the retry a human
+   *  approves runs against the VERIFIED tree, never against the evaluator's edit. When `true` a
+   *  {@link WorktreeRestoredEvent} follows with the discarded paths, the gate's `denialReason` says the
+   *  edit was discarded, and the `awaitingHuman` prompt reads "… its edit was discarded and the
+   *  creator's verified tree restored. Approve to retry the phase against the restored tree …" (the
+   *  pre-0.33.0 prompt was "confirm to retry the phase"; a card that matched the old text must
+   *  re-check). `false` = the restore failed or was not attempted — `restoreError` says why — and the
+   *  denial keeps the manual `git read-tree` remedy. */
+  restored: boolean;
+  restoreError: string | null;
 };
 
 /** One repository check the engine ran in the run's worktree (wicked-core F-039). */
@@ -1073,7 +1150,11 @@ export interface RepoCheckRun {
   /** `install` | `typecheck` | `lint` | `test` | `cargo-test`. */
   name: string;
   argv: string[];
-  /** Provenance an operator can verify: `package.json scripts.test`, `Cargo.toml`, … */
+  /** Provenance an operator can verify: `package.json scripts.test`, `Cargo.toml`, … For the `install`
+   *  step the lockfile and WHY it ran: `package-lock.json (node_modules absent)`, `pnpm-lock.yaml (…)`,
+   *  `yarn.lock (…)`, `package.json (…, no lockfile)` — and, since wicked-core#431 / #433, `… (forced:
+   *  lockfile drift)` when the deliver lift moved a lockfile/manifest between the old base and the
+   *  remote tip and the re-verify re-installed (frozen lockfile, `--ignore-scripts`) before the checks. */
   source: string;
   /** The process exit code; `null` when it produced none (timed out / could not spawn). */
   exitCode: number | null;
@@ -1113,7 +1194,17 @@ export interface RepoCheckRun {
  *  true`): no manifest at all, or a readable `package.json` with no string `typecheck`/`lint`/`test`
  *  script and no `Cargo.toml`. A manifest that cannot be read or trusted still FAILS.
  *  "Done" for a verify phase is now the exit code the engine observed, not the seat's account of
- *  having run the suite. `type` alias on purpose — see {@link EvaluatorMutatedWorktreeEvent}. */
+ *  having run the suite.
+ *
+ *  wicked-core#431 (api-types 0.33.0): the frame ALSO arrives for the DELIVER ord — a Tool unit —
+ *  whenever the worktree's tree is NOT the tree the run verified when the deliver phase is about to
+ *  push: after a lift onto the remote tip ({@link DeliverLiftEvaluatedEvent} `outcome: 'lifted'`), on
+ *  a retry after a failed re-verify, after an operator's by-hand rebase, or for a run that recorded
+ *  no verified tree. The engine re-runs the repository's checks on the tree that would ship before
+ *  allowing the push (a lockfile that moved with the base forces a frozen `--ignore-scripts` install
+ *  first), and the deliver unit's `gateEvaluated` then carries `hasDeterministicFloor: true` with
+ *  this floor's `criterion`. `passed: false` there fails the deliver unit closed — nothing is pushed.
+ *  `type` alias on purpose — see {@link EvaluatorMutatedWorktreeEvent}. */
 export type RepoChecksEvaluatedEvent = {
   type: 'repoChecksEvaluated';
   session: string;
@@ -1125,9 +1216,155 @@ export type RepoChecksEvaluatedEvent = {
   skipped: string[];
 };
 
-/** The gate-evidence events (wicked-core F-036/F-039) as a discriminated union for consumers that
- *  narrow on `type`; they also flow through the permissive {@link CoreEvent}. */
-export type GateEvidenceEvent = EvaluatorMutatedWorktreeEvent | RepoChecksEvaluatedEvent;
+// ── wicked-core#431 gate / deliver evidence (F-3R2-013 / -010 / -009; api-types 0.33.0) ──────────
+
+/** wicked-core#431 / F-3R2-010 — the engine PUT THE CREATOR'S TREE BACK after an `executes_code:
+ *  false` phase changed it ({@link EvaluatorMutatedWorktreeEvent} with `restored: true`): the run
+ *  branch's `HEAD` is back at the baseline commit when the phase had moved it (`head`), the index and
+ *  working tree match `tree` (the baseline the actor snapshotted at dispatch), and every path the
+ *  phase ADDED is deleted. `discarded` names exactly what the evaluator's edit was — the same list the
+ *  mutation event carried as `changed` — so the ledger shows what was thrown away, and `suggestionRef`
+ *  says where the discarded edit was pinned so it can be read back. Emitted at the gate fold, AFTER
+ *  `evaluatorMutatedWorktree` and BEFORE `gateEvaluated`. `type` alias on purpose — see
+ *  {@link EvaluatorMutatedWorktreeEvent}. */
+export type WorktreeRestoredEvent = {
+  type: 'worktreeRestored';
+  session: string;
+  ord: number;
+  attempt: number;
+  /** The seat that ran the unit. */
+  cli: string;
+  /** The workflow phase id (`verify`, `adversarial-review`, …). */
+  phase: string;
+  /** The tree id the worktree was restored to (the creator's baseline). */
+  tree: string;
+  /** The commit `HEAD` was reset to when the phase had moved it; `null` when it had not. */
+  head: string | null;
+  discarded: WorktreeChangedPath[];
+  /** Where the DISCARDED tree was pinned so the edit is never lost (wicked-core#433 review
+   *  F-433-008 — the seam wicked-core#432's suggestion lane reads from):
+   *  `refs/wicked/suggestions/<run>/<ord>/<attempt>`, a commit whose tree is the mutation event's
+   *  `afterTree`. `null` when the pin failed (the discarded content is then only a gc-prunable
+   *  dangling tree). */
+  suggestionRef: string | null;
+};
+
+/**
+ * `deliverLiftEvaluated.outcome` — what the engine's pre-push lift onto the remote default branch did:
+ * - `unchanged` — the base was already the remote tip; the deliver rebase is a no-op and the tree the
+ *   checks verified is the tree that ships;
+ * - `lifted` — the remote moved; the run's changes were re-applied onto its tip in the worktree
+ *   (`treeBefore` → `treeAfter`) and the repository's own checks were RE-RUN on the lifted tree (a
+ *   {@link RepoChecksEvaluatedEvent} for this ord) before the push was allowed;
+ * - `conflict` — the lift would conflict in `conflicts`; the worktree was left exactly as verified and
+ *   the deliver unit FAILED with a `deliver: LIFT-CONFLICT — …` remedy — nothing rebased or pushed
+ *   (crew reads that marker as a recoverable strand, `delivery: 'stranded'`);
+ * - `skipped` — the lift could not be DECIDED (no remote / fetch failed / git too old / a branch
+ *   carrying its own commits); the worktree was never touched and the deliver script's own rebase
+ *   stands, as before;
+ * - `failed` — the lift was decided but its APPLICATION failed part-way; the worktree may hold a
+ *   partial state, the deliver unit fails closed, nothing was pushed.
+ * Open-ended (`string & {}`) so a newer engine's outcome parses in an older consumer.
+ */
+export type DeliverLiftOutcome =
+  | 'unchanged'
+  | 'lifted'
+  | 'conflict'
+  | 'skipped'
+  | 'failed'
+  | (string & {});
+
+/** wicked-core#431 / F-3R2-013 — before the run's `deliver` Tool phase pushed, the engine LIFTED the
+ *  run's work onto the remote default branch's CURRENT tip (in memory, `git merge-tree`) and said what
+ *  that did (see {@link DeliverLiftOutcome}). Emitted once per deliver attempt, BEFORE the deliver
+ *  unit's `repoChecksEvaluated` (when a re-verify ran — the tree that would ship is not the recorded
+ *  verified tree) / `stepFailed` (conflict, failed, or a failed re-verify) / `unitDone`. The deliver
+ *  gate never pushes a tree that was not verified: on `unchanged` / `lifted` the deliver command
+ *  receives the verified remote-tip commit as `WICKED_DELIVER_VERIFIED_BASE` and crew's script refuses
+ *  to rebase past it (`deliver: BASE MOVED since verification — …`). `type` alias on purpose. */
+export type DeliverLiftEvaluatedEvent = {
+  type: 'deliverLiftEvaluated';
+  session: string;
+  ord: number;
+  attempt: number;
+  outcome: DeliverLiftOutcome;
+  /** The remote default ref the lift targets (`origin/main`), when one was resolved. */
+  baseRef: string | null;
+  /** The run branch's `HEAD` before the lift (the base the work was verified on). */
+  baseBefore: string | null;
+  /** The remote tip the work now sits on (`lifted`) or would have (`conflict`). */
+  baseAfter: string | null;
+  treeBefore: string | null;
+  treeAfter: string | null;
+  /** The paths the lift would conflict in (`conflict`); empty otherwise. */
+  conflicts: string[];
+  /** Why the lift was skipped / failed, or a disclosed degradation (a failed fetch); `null` otherwise. */
+  note: string | null;
+};
+
+/** wicked-core#431 / F-3R2-009 — an `executes_code: false` phase (an evaluator, a recon rung, a
+ *  review) asked to run a WRITE-CLASS tool (edit/write/delete/move, by ACP `kind` or by tool name) and
+ *  the engine REFUSED the call at the carrier's permission boundary, answering the agent's own reject
+ *  option. Fires on the ACP carrier (`carrier: 'acp'`) for a seat whose adapter is ADMITTED to input
+ *  governance (claude, opencode). A guarded unit on an UNADMITTED ACP seat never starts an ACP turn —
+ *  it is rerouted with `acpFallback {fallbackKind: 'read_only_requires_wrapped'}` and no per-call
+ *  event exists on that route. A refused call costs the seat one tool call, not the phase a retry;
+ *  the worktree guard ({@link EvaluatorMutatedWorktreeEvent}) remains the backstop for what a
+ *  permission boundary cannot see (a `bash` heredoc). `type` alias on purpose. */
+export type EvaluatorToolCallDeniedEvent = {
+  type: 'evaluatorToolCallDenied';
+  session: string;
+  ord: number;
+  attempt: number;
+  /** The registry seat key (ACP-path convention, as `governanceUnenforced`). */
+  cli: string;
+  /** The carrier the refusal happened on — `'acp'` today. Open-ended for a future carrier. */
+  carrier: 'acp' | (string & {});
+  /** The tool the agent asked for, as it named it (`edit`, `write`, `str_replace_based_edit_tool`, …). */
+  tool: string;
+  /** The ACP `toolCall.kind` when the agent sent one (`edit`, `delete`, `move`, …); `null` otherwise. */
+  kind: string | null;
+  /** The path the call targeted, when its arguments carried one; `null` otherwise. */
+  path: string | null;
+  reason: string;
+};
+
+/** wicked-core#431 / F-3R2-013 — how the run's BASE commit was chosen when its worktree was minted:
+ *  the engine fetches `origin` and, when the registered clone's `HEAD` is strictly behind the remote
+ *  default branch's tip, bases the run on that tip — so the worker starts from the current code and
+ *  the deliver lift has nothing to move. `lifted: true` = the base moved off the clone's `HEAD` by
+ *  `behind` commits; `false` = `HEAD` was already the tip, or was ahead of / diverged from it (local
+ *  unpushed work — kept, `note` says so), or no remote default ref resolved (`baseRef: null`).
+ *  Emitted once per freshly minted worktree, BEFORE `worktreeReady`; a resumed run reuses its live
+ *  worktree and emits nothing. Session-level (no `ord`). `type` alias on purpose. */
+export type RunBaseResolvedEvent = {
+  type: 'runBaseResolved';
+  session: string;
+  /** The remote default ref (`origin/main`), or `null` when none could be resolved. */
+  baseRef: string | null;
+  /** The commit the run worktree was minted from. */
+  baseCommit: string;
+  /** The registered clone's `HEAD` at mint time. */
+  localHead: string;
+  /** How many commits `localHead` was behind `baseRef`; `0` when not behind or unknown. */
+  behind: number;
+  /** Whether `git fetch origin` succeeded (a failed fetch is disclosed in `note`, cached refs used). */
+  fetched: boolean;
+  lifted: boolean;
+  note: string | null;
+};
+
+/** The gate-evidence events (wicked-core F-036/F-039, extended by wicked-core#431 — api-types 0.33.0
+ *  added {@link WorktreeRestoredEvent}, {@link DeliverLiftEvaluatedEvent} and
+ *  {@link EvaluatorToolCallDeniedEvent}) as a discriminated union for consumers that narrow on `type`;
+ *  they also flow through the permissive {@link CoreEvent}. {@link RunBaseResolvedEvent} is
+ *  session-level evidence and stands on its own. */
+export type GateEvidenceEvent =
+  | EvaluatorMutatedWorktreeEvent
+  | RepoChecksEvaluatedEvent
+  | WorktreeRestoredEvent
+  | DeliverLiftEvaluatedEvent
+  | EvaluatorToolCallDeniedEvent;
 
 // ── P2 decisions-full observability events (wicked-core EVT-001/012/013) ────
 
@@ -3070,13 +3307,105 @@ export interface ProjectPrompts {
   prompts: InteractionRequest[];
 }
 
-/** `POST /chats` body (gains `projectId` with DES-PROJECT-001). */
+/**
+ * `POST /chats` body (gains `projectId` with DES-PROJECT-001; `repoRefs` and the SCOPE semantics
+ * with crew#502).
+ *
+ * A chat is SCOPED (crew#502, F-067): its seats run in a private scratch root — never a repo and
+ * never the daemon's working directory — with the scoped repositories as read roots and, where a
+ * graph can be bound, a READ-ONLY wicked-estate MCP over it (the grounding governed runs get). The
+ * scope is: the explicit `repoRefs` (plus the legacy single `repoRef`, merged in) when given, else
+ * ALL of `projectId`'s registered `crew.repo` members, else nothing (the seats see only their
+ * scratch root). The resolved scope comes back as {@link ChatOpenResponse.scope}.
+ */
 export interface ChatOpenBody {
   chatId?: string;
   clis?: string[];
+  /** One repo in scope — the legacy spelling; merged into `repoRefs`. */
   repoRef?: string;
-  /** File the chat into a project (`crew.chat` membership, attached on open). */
+  /** The repos in scope, by registry id or name (1–32). With `projectId` the PROJECT graph grounds
+   *  them; without it a single repo's own graph does, and several repos get no graph. */
+  repoRefs?: string[];
+  /** File the chat into a project (`crew.chat` membership, attached on open) — and, when no
+   *  `repoRefs` are given, scope it to every registered `crew.repo` member of that project. */
+  projectId?: string;
+}
+
+/** How a chat's scope was chosen (crew#502). */
+export type ChatScopeKind = 'project' | 'repos' | 'none';
+
+/** One repository a chat's seats may read. */
+export interface ChatScopeRepo {
+  id: string;
+  name: string;
+  /** The registered root path — the read root the seats are pointed at. */
+  rootPath: string;
+}
+
+/**
+ * What a chat's seats can see — decided at `POST /chats`, stated to the seats in their scratch
+ * root's `AGENTS.md` / `CLAUDE.md`, and returned to the caller so the UI can show it. Additive:
+ * older skins ignore it.
+ */
+export interface ChatScope {
+  kind: ChatScopeKind;
+  /** The project the chat is filed into, when any. */
   projectId?: string;
+  /** The repositories in scope (read-only). Empty for `kind: 'none'`. */
+  repos: ChatScopeRepo[];
+  /** The seats' working directory: the chat's private scratch root under the OS temp dir. */
+  cwd: string;
+  /** Whether a READ-ONLY estate MCP over a code graph is attached, and why / why not. `repoLabel`
+   *  is the estate label the project graph indexes the (single) scoped repo under, when the
+   *  binding was repo-bound — informational; the engine binds by graph path. */
+  graph: { bound: boolean; reason: string; repoLabel?: string };
+  /** `crew.repo` members of the project whose registry record is gone — named, not readable. */
+  dangling: string[];
+}
+
+/** One seat's warm-up outcome on `POST /chats`. */
+export interface ChatSeatOutcome {
+  cliKey: string;
+  ok: boolean;
+  error?: string;
+}
+
+/** `POST /chats` → 201. */
+export interface ChatOpenResponse {
+  chatId: string;
+  seats: ChatSeatOutcome[];
+  /** The resolved scope (crew#502). */
+  scope: ChatScope;
+  /** Present when the chat opened but its `crew.chat` filing into `projectId` failed. */
+  projectAttachError?: string;
+}
+
+/** One live chat on `GET /chats` (FINDING-027 gap 4; scope fields with crew#502). */
+export interface ChatSummary {
+  chatId: string;
+  /** The seats currently warm, sorted. */
+  seats: string[];
+  /** Seconds since the chat's last open/ensure/turn; `null` when it has no activity stamp. */
+  idleSecs: number | null;
+  /** The seats' working directory as the engine recorded it; absent on an engine predating scope. */
+  cwd?: string | null;
+  /** The estate graph the seats' read-only estate MCP is bound to; `null` ⇒ none. */
+  codeGraphDb?: string | null;
+  /** The repository roots in scope. */
+  readRoots?: string[];
+}
+
+/** `GET /chats` → 200. */
+export interface ChatListResponse {
+  chats: ChatSummary[];
+}
+
+/** `GET /chats/:id` → 200. */
+export interface ChatDetailResponse {
+  chatId: string;
+  seats: string[];
+  /** The scope recorded at open; `null` for a chat this daemon did not open (or after a restart). */
+  scope: ChatScope | null;
 }
 
 // ── Project code graph (DES-PROJECT-001; the co-located multi-repo graph) ──────
@@ -3616,7 +3945,9 @@ export interface AcpCliDiagnostics {
   sessionsStarted: number;
   /** Count of `acpFallback` events (ACP unavailable/failed; run continued single-shot). */
   fallbacks: number;
-  /** Fallback counts by `fallbackKind` (`session_died`, `auth_required`, `binary_unavailable`, …). */
+  /** Fallback counts by `fallbackKind` (`session_died`, `auth_required`, `binary_unavailable`, and the
+   *  two deliberate reroutes `governance_requires_wrapped` / `read_only_requires_wrapped` — see
+   *  {@link AcpFallbackKind}). */
   fallbackKinds: Record<string, number>;
   /** Epoch ms of the newest `acpSessionStarted`, or `null` when none recorded. */
   lastStartedTs: number | null;
@@ -3638,13 +3969,92 @@ export interface AcpDiagnostics {
 export interface DiagnosticsResponse {
   components: DiagnosticsComponents;
   daemon: DiagnosticsDaemon;
-  /** `core.db` + sidecars + the events dir (as a total), sorted by name. */
+  /** `core.db` + sidecars + the events dir (as a total), sorted by name, followed by one entry per
+   *  repo code graph under the state home (`repo-graphs/<key>/estate.db`, key-sorted;
+   *  wicked-core#406). */
   stores: DiagnosticsStoreFile[];
   /** Bounded tail of the daemon's own error-level log lines, newest first. */
   recentErrors: DiagnosticsRecentError[];
   acp: AcpDiagnostics;
   /** The skills seam's last outcome (api-types 0.28.0) — see `DiagnosticsSkills`. */
   skills: DiagnosticsSkills;
+  /** Whether the engine's governance evidence is LANDING (api-types 0.31.0, crew#495) — see `DiagnosticsGovernance`. */
+  governance: DiagnosticsGovernance;
+}
+
+// ── Diagnostics — governance store + dead letters (api-types 0.31.0, crew#495 / F-022) ─────────
+//
+// The engine's emit seam writes every cross-product `wicked.*` event — conformance claims and
+// decisions, phase transitions, the steering-rule lifecycle — onto the shared estate store named
+// by `WICKED_ESTATE_DB`, or, when it cannot, spools the event to an NDJSON dead-letter outbox
+// (`WICKED_APPS_EMIT_DEADLETTER`). `serve` now resolves that store (`--governance-db` /
+// `WICKED_CREW_GOVERNANCE_DB` › an inherited `WICKED_ESTATE_DB` › `<core db>.governance/
+// governance.db`) and keeps the outbox under the state home (`<core db>.governance/
+// emit-outbox.ndjson`), never under HOME; this block is the read-only account of both.
+
+/** Which rule chose the store: the flag, crew's env override, the engine's own inherited
+ *  `WICKED_ESTATE_DB`, or the default sidecar of the core db. */
+export type DiagnosticsGovernanceStoreSource = 'flag' | 'env-crew' | 'env-estate' | 'core-db-sidecar';
+
+/** The store the engine's emit seam writes governance events to. */
+export interface DiagnosticsGovernanceStore {
+  /** The store as exported to the engine — an absolute SQLite path, or `:memory:`. The emit seam is SQLite-only,
+   *  so a URL spec (`postgres://…`) is refused at boot and never appears here. */
+  path: string;
+  source: DiagnosticsGovernanceStoreSource;
+}
+
+/** EVENT records on the governance store. Counted through the engine binding; an engine without
+ *  it answers `null` for both — never a fabricated 0. */
+export interface DiagnosticsGovernanceRecords {
+  /** Event records on the store right now (short-TTL), or `null` when the engine cannot count. */
+  total: number | null;
+  /** Records landed since this daemon's API came up (`total − baseline`; the baseline is taken when the routes
+   *  register, after the engine has booted, so its boot-time emits are in the baseline), or `null` when either
+   *  side is unknown. */
+  sinceBoot: number | null;
+}
+
+/** The dead-letter outbox, folded (streamed, size-capped). */
+export interface DiagnosticsGovernanceDeadletters {
+  /** The outbox this daemon exports to the engine; `null` when no store was resolved (library boot). */
+  path: string | null;
+  /** Entries in the outbox — 0 is the good answer. A floor when `truncated`. */
+  count: number;
+  /** Entries per event type (`wicked.crew.governance.conformance_recorded`, …); overflow folds into `other`. */
+  byType: Record<string, number>;
+  /** Entries per reason bucket — the engine's reason text before its first `:` (`no shared store (WICKED_ESTATE_DB unset)`,
+   *  `open shared store failed`, `store write failed`). */
+  byReason: Record<string, number>;
+  /** Entries carrying the engine's `ts` (epoch ms; written by wicked-core builds that stamp spooled records). */
+  timestamped: number;
+  /** Entries without a timestamp (a pre-stamp engine, or an unparseable line) — counted, never given an invented time. */
+  untimestamped: number;
+  /** Epoch ms of the oldest / newest timestamped entry, or `null` when none carries one. */
+  oldestTs: number | null;
+  newestTs: number | null;
+  /** `true` when the fold stopped at its byte cap — `count` is then a floor. */
+  truncated: boolean;
+  /** The pre-fix outbox under HOME (`~/.something-wicked/wicked-apps/emit-outbox.ndjson`) when it exists and is
+   *  non-empty — events earlier daemons on this host spooled there; `null` otherwise. Reported, never written. */
+  legacyOutbox: { path: string; bytes: number } | null;
+}
+
+/** One governance finding. `governance.store` (error) = no store resolved, every emit dead-letters;
+ *  `governance.deadletter` (error) = the outbox holds entries; `governance.legacy-outbox` (warning) =
+ *  the pre-fix HOME outbox exists. Every message names the replay command. */
+export interface DiagnosticsGovernanceFinding {
+  kind: 'governance.store' | 'governance.deadletter' | 'governance.legacy-outbox';
+  severity: 'warning' | 'error';
+  message: string;
+}
+
+/** `GET /diagnostics` → `governance` (api-types 0.31.0). */
+export interface DiagnosticsGovernance {
+  store: DiagnosticsGovernanceStore | null;
+  records: DiagnosticsGovernanceRecords;
+  deadletters: DiagnosticsGovernanceDeadletters;
+  findings: DiagnosticsGovernanceFinding[];
 }
 
 /** The skills seam's state as `GET /diagnostics` reports it (skills keystone, api-types 0.28.0). */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wicked-crew-api-types",
-  "version": "0.31.0",
+  "version": "0.33.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",