wicked-crew-api-types 0.30.0 → 0.32.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`). */
@@ -802,7 +825,51 @@ export interface DataUsedEvent {
   files: string[];
 }
 
-/** §3 B1 — the gate's decision depth, emitted alongside `gateDecided`. */
+/**
+ * The layer that denied a unit — a stable token (wicked-core `UnitDenial.source`):
+ * - `governance` — the unit's own gate; `input_governance` — the tool-call hook / boundary;
+ * - `pinned_validator` — the deterministic re-verify; `agent_validator` — the LLM judge;
+ *   `evaluator` — the evaluator≠creator second pass;
+ * - `worker_failure` — the CLI process failed; `substance` — no reviewable substance;
+ *   `deliverables` — declared deliverables missing; `elicitation` — ACP elicitation ended;
+ * - `worktree_guard` — a def-driven, agent-executed `executes_code: false` phase changed the
+ *   worktree it was reviewing (wicked-core F-036, see {@link EvaluatorMutatedWorktreeEvent}) — or
+ *   the guard could not re-verify it (no baseline persisted at dispatch, comparison unverifiable),
+ *   which denies fail-closed WITHOUT that event; `reason` names the cause;
+ * - `repo_checks` — the repository's own checks failed in the worktree (wicked-core F-039, see
+ *   {@link RepoChecksEvaluatedEvent}).
+ * Open-ended (`string & {}`) so a newer engine's source parses in an older studio.
+ */
+export type UnitDenialSource =
+  | 'governance'
+  | 'input_governance'
+  | 'pinned_validator'
+  | 'agent_validator'
+  | 'evaluator'
+  | 'worker_failure'
+  | 'substance'
+  | 'deliverables'
+  | 'elicitation'
+  | 'worktree_guard'
+  | 'repo_checks'
+  | (string & {});
+
+/** The MACHINE-READABLE twin of `gateEvaluated.denialReason` (wicked-core `UnitDenial`, camelCase on
+ *  the wire): which layer denied, the prose reason, and — when the layer recorded them — the
+ *  conformance claim id, the firing rule ids, the refused tool and the unit-phase token. `null`
+ *  fields are the engine's `Option::None`, never absent. */
+export interface UnitDenial {
+  source: UnitDenialSource;
+  reason: string;
+  claimId: string | null;
+  ruleIds: string[];
+  deniedTool: string | null;
+  phase: string | null;
+}
+
+/** §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. */
 export interface GateEvaluatedEvent {
   type: 'gateEvaluated';
   session: string;
@@ -813,7 +880,10 @@ export interface GateEvaluatedEvent {
   agentVerdict: string | null;
   agentReasoning: string | null;
   evaluatorPass: boolean | null;
+  /** Policy ids the evaluator≠creator pass applied (empty = vacuous default-allow, FINDING-025). */
+  evaluatorPolicies: string[];
   denialReason: string | null;
+  denial: UnitDenial | null;
   combined: boolean;
 }
 
@@ -979,6 +1049,109 @@ export interface GovernanceUnenforcedEvent {
   reason: string;
 }
 
+/** One path an `executes_code: false` phase changed, with git's one-letter status
+ *  (`A`dded, `M`odified, `D`eleted, `T`ype-changed). */
+export interface WorktreeChangedPath {
+  status: string;
+  path: string;
+}
+
+/** wicked-core F-036 — an `executes_code: false` phase (an evaluator, a recon rung, a review) CHANGED
+ *  the worktree it was working in. Scope: the guard governs a DEF-DRIVEN, AGENT-executed
+ *  `executes_code: false` phase (`WorkUnit.worktree_guarded`, derived at plan time); Tool phases —
+ *  crew's `deliver-pr` included — and prose-planned runs are not guarded. The engine snapshots the
+ *  tree at dispatch and takes the FINAL snapshot after everything the phase owned has run (seat
+ *  quiesced — its process group killed, a persistent session closed — judge rendered, repo checks
+ *  done), for EVERY seat and carrier regardless of governance adapter. `changed` is EVERY path that
+ *  differs, and every one DENIES the unit (its `gateEvaluated.denial.source` is `worktree_guard`):
+ *  there are NO exemptions — not documentation, not a declared `required_deliverables` entry, not
+ *  tool state (a phase whose deliverable must live in the tree is a code phase; the engine's own
+ *  `tmp/` scratch is excluded from the snapshot by construction). `headMoved`: the run branch was
+ *  committed/amended/reset. The event is emitted exactly when a MUTATION denies the unit (`changed`
+ *  non-empty and/or `headMoved`), so an operator always sees what an evaluator wrote. A
+ *  `worktree_guard` denial can also come from the guard's fail-closed paths — no baseline persisted
+ *  at dispatch, or the comparison unverifiable — and those carry NO `evaluatorMutatedWorktree`
+ *  event: the gate's `denial.reason` names the cause. Evaluator ≠ creator is no longer a promise the
+ *  seat keeps; it is a check.
+ *
+ *  `type` alias on purpose, not `interface`: only anonymous object types satisfy `CoreEvent`'s index
+ *  signature, which is what lets the frame flow through CoreEvent-typed broadcast seams. */
+export type EvaluatorMutatedWorktreeEvent = {
+  type: 'evaluatorMutatedWorktree';
+  session: string;
+  ord: number;
+  attempt: number;
+  /** The seat that ran the unit (`assigned_cli`; `''` when unassigned). */
+  cli: string;
+  /** The workflow phase id (`verify`, `adversarial-review`, …). */
+  phase: string;
+  beforeTree: string;
+  afterTree: string;
+  headMoved: boolean;
+  changed: WorktreeChangedPath[];
+};
+
+/** One repository check the engine ran in the run's worktree (wicked-core F-039). */
+export interface RepoCheckRun {
+  /** `install` | `typecheck` | `lint` | `test` | `cargo-test`. */
+  name: string;
+  argv: string[];
+  /** Provenance an operator can verify: `package.json scripts.test`, `Cargo.toml`, … */
+  source: string;
+  /** The process exit code; `null` when it produced none (timed out / could not spawn). */
+  exitCode: number | null;
+  timedOut: boolean;
+  /** The OS error when the command could not be started (binary not on PATH, …); `null` otherwise
+   *  — the key is always present on the wire. */
+  spawnError: string | null;
+  durationMs: number;
+  /** The last 4 KiB of each stream — the evidence, verbatim. */
+  stdoutTail: string;
+  stderrTail: string;
+}
+
+/** wicked-core F-039 — the engine ran the repository's OWN checks in the worktree for the def's
+ *  code-verifying unit (`verified_evidence` with an `executes_code` creator upstream: `bug/verify`,
+ *  `feature/test`, `migration/verify`) and folded them into the gate as a deterministic floor. Fires
+ *  once per fold, just before `gateEvaluated` (whose `hasDeterministicFloor`/`criterion` include this
+ *  floor). `checks` is what actually ran, in order (`package.json` `typecheck`/`lint`/`test` via the
+ *  lockfile's package manager, an `install` first when `node_modules/` is absent; `Cargo.toml` →
+ *  `cargo test`); `skipped` names detected checks not run because an earlier one failed. `passed:
+ *  false` ⇒ the unit is denied (`denial.source` is `repo_checks`).
+ *
+ *  The checks are repo-controlled code and run ONLY inside an OS write boundary (macOS
+ *  `sandbox-exec` / Linux `bwrap`: writes confined to the worktree, the curated secret directories
+ *  unreadable, network open for installs) with an isolated `HOME`, `npm_config_cache`, `CARGO_HOME`,
+ *  `CARGO_TARGET_DIR` and `XDG_*` under `<worktree>/tmp/wicked-checks/`, and with a MINIMAL
+ *  environment — the daemon's env is cleared and only `PATH`, locale (`LANG`/`LC_*`), `TERM`,
+ *  `USER`/`LOGNAME`, `RUSTUP_HOME`, the Windows shell essentials and those isolation overrides
+ *  (`CI=1` included) reach a check: no token, API key or `WICKED_*` variable does; installs are always
+ *  `--ignore-scripts` (`--no-package-lock` when the repo ships no lockfile). When NO boundary can be
+ *  armed (no sandbox tool on the host — Windows) the checks do NOT run and the floor FAILS
+ *  (`passed: false`, `checks: []`, the reason on the unit record) — repo-controlled scripts never
+ *  run unsandboxed. Detection is fail-closed the same way: a `package.json` that cannot be read or
+ *  parsed, or a symlinked manifest/lockfile/`node_modules` (every probe `lstat`s, opens `O_NOFOLLOW`
+ *  and `fstat`s the opened descriptor before reading — links are never followed), FAILS the floor.
+ *  Only a repo with NO DETECTABLE check is the disclosed vacuous pass (`checks: []`, `passed:
+ *  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}. */
+export type RepoChecksEvaluatedEvent = {
+  type: 'repoChecksEvaluated';
+  session: string;
+  ord: number;
+  attempt: number;
+  passed: boolean;
+  criterion: string;
+  checks: RepoCheckRun[];
+  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;
+
 // ── P2 decisions-full observability events (wicked-core EVT-001/012/013) ────
 
 /** P2 — a structured workflow def was selected; fires once per session, after SessionStarted and before
@@ -2920,15 +3093,107 @@ 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) ──────
 //
 // A project's `crew.repo` members indexed into ONE wicked-estate database, each under a stable
@@ -3488,13 +3753,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.30.0",
+  "version": "0.32.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",