wicked-crew-api-types 0.19.0 → 0.25.0

package/index.d.ts

@@ -197,9 +197,14 @@ export interface AgentSession {
    *
    *   - `'delivered'` — a PR was opened for this run (by the deliver phase, or post-hoc via
    *     `POST /runs/:id/deliver`); `deliverUrl` carries the PR URL.
-   *   - `'stranded'`  — a COMPLETED repo-scoped run with no recorded PR whose worktree still
-   *     exists on disk AND carries work: reviewable work nobody lifted. Derived honestly for
-   *     OLD runs too — records written before this field existed strand exactly the same way.
+   *   - `'stranded'`  — reviewable work nobody lifted, reached two ways: a COMPLETED repo-scoped
+   *     run with no recorded PR whose worktree still exists on disk AND carries work (derived
+   *     honestly for OLD runs too — records written before this field existed strand the same
+   *     way); OR (crew#418) a run whose deliver phase hit a LIFT collision — a rebase conflict or
+   *     non-fast-forward push — which the daemon reinterprets from the engine's `failed` to
+   *     `completed`+`stranded`: its work is committed on the `wicked/<id>` branch (the engine
+   *     reaps the now-clean worktree, but never the branch), recoverable via `POST /runs/:id/
+   *     deliver`, which stands a throwaway worktree back up from that branch to lift it.
    *   - `'vacuous'`   — a COMPLETED repo-scoped run whose surviving worktree carries NO
    *     contribution at all (crew#311: nothing uncommitted, no run-branch commit — units all
    *     reached "done" while producing nothing). There is nothing to deliver; the recovery is a
@@ -250,6 +255,33 @@ export interface AgentSession {
    * `GET /campaigns`.
    */
   group_label?: string;
+  /**
+   * When this run was LAUNCHED — unix SECONDS (home command-center run metrics; api-types 0.24.0).
+   * Daemon-derived at DTO assembly on BOTH `GET /runs` and `GET /runs/:id` from the `run.launched`
+   * audit entry's timestamp (the daemon's durable system-of-record for run provenance — task #88),
+   * joined exactly like {@link retry_of} / {@link guidance} and hydrated from the SAME trail scan
+   * at boot, so it survives a daemon restart.
+   *
+   * This is the ONE launch instant the daemon records: "created" and "started" are the SAME event
+   * here — the engine's `AgentSession` (wicked-core `domain.rs`) carries no launch time, so there
+   * is no separate queued-vs-started split to expose. Unlocks time-bucketed KPI deltas and a real
+   * 7/30/90-day range on the home dashboard.
+   *
+   * ABSENT — never `null`, never fabricated — when the daemon has no `run.launched` entry for the
+   * run: a run launched OFF the `POST /runs` path (a repo's onboarding run, a campaign's own
+   * DAG-node runs), a run predating this field, or a `--db`-isolated daemon reading a trail that
+   * never saw the launch. Read with `typeof === 'number'`; a bucketed KPI or a 7/30/90-day range
+   * must EXCLUDE an undated run, never date it with a fabricated now.
+   *
+   * COST (deferred, not faked): a per-run cost/spend figure is deliberately NOT joined onto this
+   * DTO. Cost exists only on the per-unit {@link CliUsageEvent} (`costUsd`), streamed over `/ws`
+   * and never accumulated per run daemon-side — a reliable per-run total would require replaying
+   * the durable event log per run on this hot path (the unbounded cost the GET /runs delivery-cache
+   * architecture forbids) or a new live cliUsage accumulator plus a durable per-run store. A burn
+   * chart should sum `cliUsage.costUsd` from the live `/ws` stream (or `GET /runs/:id/events`) for
+   * now; a joined `AgentSession.cost` is a follow-up once that store exists.
+   */
+  created_at?: number;
 }
 
 /** An ordered unit of work within a run (`WorkUnit`). */
@@ -425,6 +457,13 @@ export interface GateInfo {
   prompt: string;
   lifecycle: string;
   receivedAt: string;
+  /**
+   * Refusal-detection warning (issue #419, api-types 0.20.0). Present ONLY when the gate prompt
+   * reads as a pure sandbox/tool refusal — the worker reported it could not act, with no sign of
+   * productive work — so an operator does not approve a refusal as if it were work. Additive and
+   * advisory: it never gates a decision, and is omitted entirely on a normal gate.
+   */
+  refusal?: { matched: boolean; reason: string };
 }
 
 /** Approve / reject payload for the steering gate (`POST /runs/:id/gate`). On a
@@ -436,6 +475,16 @@ export interface GateDecision {
   amend?: string;
 }
 
+/**
+ * Body of `POST /runs/:id/reassign` — the manual operator lever that reassigns a wedged run's
+ * cursor unit through the same engine path the stall-watchdog's automatic escalation uses
+ * (crew#442). `cli` omitted lets the engine's council re-pick the seat; when present it must be
+ * a seat in the run's own pool (`SessionView.clis`) or the route answers 400.
+ */
+export interface ReassignRequest {
+  cli?: string;
+}
+
 /**
  * A CoreEvent frame as delivered verbatim over `/ws` — a tagged-JSON object
  * discriminated on `type` (wicked-core-ts `event_to_json`). The named optional
@@ -531,7 +580,15 @@ export interface CoreEvent {
   updatedDescription?: string;
   // unitOutputCaptured (EVT-013)
   outputBytes?: number;
-  stepStatus?: 'ok' | 'failed' | 'cancelled';
+  /**
+   * How the worker step finished. `'elicitation_failed'` (DES-002) and `'timed_out'` (perf#4 —
+   * the ENGINE's own turn ceiling, `WICKED_UNIT_TIMEOUT_SECS`) widen the original trio.
+   * `'timed_out'` vs `'cancelled'` is THE wire distinction between the platform's deadline and
+   * an operator cancel: automation may key recovery on `'timed_out'`, and must treat
+   * `'cancelled'` as final. Older engines never send the newer values — consumers keying on
+   * them degrade to doing nothing, which is the safe direction.
+   */
+  stepStatus?: 'ok' | 'failed' | 'cancelled' | 'elicitation_failed' | 'timed_out';
   /** `unitOutputDelta` (api-types 0.5.1): one streamed chunk of a worker's live output text. */
   text?: string;
   // unitPlanned enrichment fields — the wire spelling is camelCase (event_to_json);
@@ -649,13 +706,15 @@ export type WorkerStalledFrame = {
 
 /**
  * The stall watchdog's ESCALATION frame (crew#341; api-types 0.18.0). DAEMON-SYNTHETIC, emitted
- * only when escalation is armed (`SystemSettings.workerStallEscalateMinutes` > 0 — OFF by
- * default) and a detected stall stays silent past that threshold. Reports what the watchdog DID
- * and how it ended, one escalation per quiet period:
+ * only when escalation is armed (`SystemSettings.workerStallEscalateMinutes` > 0 — ON by default
+ * as of perf#4, default 30 minutes; an explicit `0` disarms) and a detected stall stays silent
+ * past that threshold. Reports what the watchdog DID and how it ended, one escalation per quiet
+ * period:
  *
- * - `action: 'reassign'` — the wedged cursor unit was recycled in place (engine `reassignUnit`:
- *   the stale turn is superseded, the session closed, the unit re-dispatched; queued operator
- *   injects survive into the fresh turn). `outcome: 'ok' | 'failed' | 'exhausted'`.
+ * - `action: 'reassign'` — the wedged cursor unit was recycled (engine `reassignUnit`: the stale
+ *   turn is superseded, the session closed, the unit re-dispatched; queued operator injects
+ *   survive into the fresh turn), routed to a DIFFERENT seat from the run's pool when one is
+ *   available (perf#4) and in place otherwise. `outcome: 'ok' | 'failed' | 'exhausted'`.
  * - `action: 'notify'` — surface loudly without touching the run (the fail-loud rung).
  *
  * `needsYou: true` marks the frames a human should act on (failed / exhausted / notify).
@@ -675,8 +734,14 @@ export type WorkerStallEscalatedFrame = {
   outcome: 'ok' | 'failed' | 'exhausted';
   /** True when a human should look; false = the platform recovered on its own. */
   needsYou: boolean;
-  /** action `reassign`: the seat the unit was re-dispatched to, when known. */
+  /** action `reassign`: the seat the unit was re-dispatched to, when known. As of perf#4 this
+   *  is the failover TARGET — a different seat from the run's pool when one exists, else the
+   *  stalled seat recycled in place. */
   cli?: string;
+  /** action `reassign` (perf#4, additive): the seat that was stalled and reassigned AWAY from,
+   *  when the watchdog knew it. Equal to `cli` on a single-seat in-place recycle. Absent on
+   *  frames from daemons predating the field. */
+  previousCli?: string;
   /** action `reassign`: automatic reassigns consumed for this run, this one included. */
   escalations?: number;
   /** outcome `failed`: bounded excerpt of what the recovery call threw. */
@@ -939,8 +1004,10 @@ export interface UnitReworkAmendedEvent {
 }
 
 /** P2 — a worker's ApplyStepResult arrived and output is ready to be gated. Fires before GateDecided.
- *  `outputBytes` is the byte length of the worker's output; `stepStatus` is "ok"/"failed"/"cancelled";
- *  `governed` reflects whether the runner armed input governance for this unit. */
+ *  `outputBytes` is the byte length of the worker's output; `stepStatus` is "ok" / "failed" /
+ *  "cancelled" / "elicitation_failed" (DES-002) / "timed_out" (perf#4 — the engine's own turn
+ *  ceiling, kept apart from "cancelled" so an operator cancel is never mistaken for a platform
+ *  timeout); `governed` reflects whether the runner armed input governance for this unit. */
 export interface UnitOutputCapturedEvent {
   type: 'unitOutputCaptured';
   session: string;
@@ -948,7 +1015,7 @@ export interface UnitOutputCapturedEvent {
   attempt: number;
   /** Byte length of the worker's raw output — distinguishes 0-byte from 8 MB truncated. */
   outputBytes: number;
-  stepStatus: 'ok' | 'failed' | 'cancelled';
+  stepStatus: 'ok' | 'failed' | 'cancelled' | 'elicitation_failed' | 'timed_out';
   governed: boolean;
 }
 
@@ -1095,6 +1162,21 @@ export interface ConformanceRule {
   obligations?: string[];
   /** The frozen acceptance-criteria text (becomes a claim's `criteria` when the rule decides a gate). */
   criteria?: string;
+  /**
+   * Unix-SECONDS timestamp of when this rule FIRST entered the store — the "added" time the Steering
+   * surface sorts + date-filters on (NOT the latest-edit time), stamped once by the engine on first
+   * create and preserved across updates (api-types 0.23.0).
+   *
+   * WIRED-BUT-PENDING A CORE-TS BUMP: the field exists on the engine's `ConformanceRule`
+   * (wicked-core `conformance.rs`, serialized with `skip_serializing_if = Option::is_none`), but it
+   * landed AFTER the published `core-ts-v0.7.16` this daemon builds against — so a rule served by
+   * the current binding carries NO `created_at`. The daemon passes the field through verbatim
+   * (`listConformanceRules` returns the parsed rows unchanged), so it begins flowing the moment
+   * crew re-pins to a core-ts that includes it — no daemon change needed. ABSENT — never
+   * fabricated — on any rule the engine did not stamp (pre-field rows, and every row from a
+   * pre-bump binding), so a `since`/`until` filter cannot assert an undated rule in range.
+   */
+  created_at?: number;
 }
 
 /** Facet query for `GET /governance/rules/preview`. All fields are optional. */
@@ -1130,6 +1212,21 @@ export interface RuleBrowseQuery {
    * contradict, and picking a winner silently would answer a question the caller didn't ask).
    */
   include_retired?: 'true' | 'false';
+  /**
+   * Inclusive LOWER date bound (api-types 0.23.0): keep only rules with `created_at >= since`.
+   * Unix SECONDS, a non-negative integer (a present-but-non-integer value is a 400). Applied
+   * server-side over the listed rows, alongside the facet filters. A rule with NO `created_at`
+   * is EXCLUDED whenever `since` (or `until`) is set — see {@link ConformanceRule.created_at}: on
+   * a pre-bump core-ts binding NO rule carries the field, so this filter narrows to empty until the
+   * engine surfaces it. Omitted ⇒ no lower bound.
+   */
+  since?: string;
+  /**
+   * Inclusive UPPER date bound (api-types 0.23.0): keep only rules with `created_at <= until`.
+   * Same units/validation/undated-exclusion as {@link RuleBrowseQuery.since}. Omitted ⇒ no upper
+   * bound.
+   */
+  until?: string;
 }
 
 // ── Steering management (STEERING program) ──────────────────────────────────────
@@ -1412,6 +1509,66 @@ export interface ImportEvalCorpusResponse {
   embedded: boolean;
 }
 
+// ── Eval run history (crew-side EvalRunStore) — the Evals section's real list ───
+
+/**
+ * One steering type's slice of an eval run's rollup — the same four counts as
+ * {@link GovernanceEvalSummary}, derived from the run's results grouped by `sample.steering_type`.
+ * This is what makes "which steering type carries the gaps" a stored field, not a per-request
+ * recompute over the full results.
+ */
+export interface EvalRunPerTypeCount {
+  total: number;
+  caught: number;
+  gaps: number;
+  false_positives: number;
+}
+
+/**
+ * One PERSISTED eval run — the listable rollup row (`GET /testing/evals`). A run is one
+ * `POST /testing/evals/run` and its report, stamped with WHO ran it, WHAT it ran against, and
+ * WHEN, so the Evals section is a real history instead of a single session-local report that a
+ * reload loses. The per-sample `results` are NOT here — they live on {@link EvalRunDetail} (the
+ * drilldown), so listing the history stays cheap no matter how large a custom corpus is.
+ *
+ * Evals take no repo/project (they judge a STORE, not a workspace), so this is a single GLOBAL
+ * feed per daemon — unlike recon campaign runs, which file into projects.
+ */
+export interface EvalRunSummary {
+  /** Server-minted run id. */
+  id: string;
+  /** Unix SECONDS the run was recorded (the crew `created_at` convention — see AgentSession). */
+  created_at: number;
+  /** The authenticated actor who ran it. */
+  actor: string;
+  /** The corpus scope (`evals:<name>`), or null for the engine's built-in dev-behaviors corpus. */
+  corpus: string | null;
+  /** The single steering type the run was narrowed to, or null when it ran all seven. */
+  type_filter: SteeringType | null;
+  /** The steering rule store the run was judged against (the daemon's `--db` steering store). */
+  rule_store: string;
+  /** The report's rollup, verbatim ({@link GovernanceEvalSummary}). */
+  summary: GovernanceEvalSummary;
+  /** Per-steering-type rollup, derived from the results — present only for the types the run covered. */
+  per_type: Partial<Record<SteeringType, EvalRunPerTypeCount>>;
+  /** `'facet-only'` when the run degraded to facet matching; null when it ran full-fidelity. */
+  degraded: 'facet-only' | null;
+}
+
+/**
+ * One eval run WITH its full per-sample results (`GET /testing/evals/:id`) — the drilldown behind a
+ * history row. `results` is the same verbatim {@link GovernanceEvalResult} array the run's original
+ * `POST /testing/evals/run` returned, so the existing report view renders it unchanged.
+ */
+export interface EvalRunDetail extends EvalRunSummary {
+  results: GovernanceEvalResult[];
+}
+
+/** The `GET /testing/evals` 200 body — the eval run history, newest first. */
+export interface ListEvalRunsResponse {
+  runs: EvalRunSummary[];
+}
+
 /**
  * The `POST /testing/recon` request body (api-types 0.15.0) — the Testing page's campaign-recon
  * trigger. `problem` is the recon brief, passed to every launched run VERBATIM (the client owns
@@ -1826,16 +1983,23 @@ export interface SystemSettings {
   /**
    * The stall watchdog's ESCALATION threshold (crew#341; api-types 0.18.0): quiet minutes before
    * the watchdog ACTS on a detected stall (see {@link WorkerStallEscalatedFrame}). Integer
-   * 0..1440; **absent or 0 = escalation OFF — the shipped default** (the issue's design: automatic
-   * recovery on a run that is merely slow would be worse than the wedge). Values below
+   * 0..1440; `0` = escalation OFF. **Absent = the daemon default (30 — armed)**: as of perf#4 the
+   * ladder is ON by default (run 616c8661 burned a full 2h turn ceiling with the watchdog
+   * detection-only; the engine's `reassignUnit` supersedes the wedged turn safely, so acting is
+   * strictly better than watching). 30 leaves ~55% headroom over the slowest legitimate
+   * time-to-first-output observed in the field (~19.4 min) while still recovering ~4x faster
+   * than the 2h ceiling. Opt out with an explicit `0`. Values below
    * `workerStallMinutes` escalate at the detection threshold — the ladder never acts before it
    * has notified.
    */
   workerStallEscalateMinutes?: number;
   /**
    * What an armed escalation DOES (crew#341): `'reassign'` (default) recycles the wedged cursor
-   * unit in place — the engine supersedes the stale turn, closes the worker session, bumps the
-   * attempt, and re-dispatches (queued operator injects survive into the fresh turn);
+   * unit — the engine supersedes the stale turn, closes the worker session, bumps the
+   * attempt, and re-dispatches (queued operator injects survive into the fresh turn). As of
+   * perf#4 the watchdog routes the re-dispatch to a DIFFERENT seat from the run's own pool when
+   * one is available (a seat that just sat silent past the escalation threshold is the last
+   * seat to hand the retry to), falling back to an in-place recycle on a single-seat pool.
    * `'notify'` is the fail-loud rung — a `needsYou` `workerStallEscalated` frame + an audit
    * entry, the run untouched.
    */
@@ -2718,3 +2882,191 @@ export interface DiagnosticsResponse {
   recentErrors: DiagnosticsRecentError[];
   acp: AcpDiagnostics;
 }
+
+// ── Memory proposal queue (DES-MEM-FACETED-001 §5.0, api-types 0.21.0) ─────────
+
+/**
+ * A proposal's lifecycle state. A proposal is INERT while `pending` (never recalled/applied);
+ * `approve` promotes its payload to the active store and marks it `approved`, `reject` marks it
+ * `rejected`.
+ */
+export type ProposalState = 'pending' | 'approved' | 'rejected';
+
+/**
+ * One entry in the estate proposal queue — a type-generic, inert write agents submit and operators
+ * decide (estate #162). The shape is the estate MCP `proposal.list` wire form verbatim.
+ */
+export interface Proposal {
+  /** Stable proposal-node id. */
+  id: string;
+  /** `"memory"` | `"policy:<steering_type>"` | future — the router key `approve` promotes by. */
+  kind_type: string;
+  /** The proposed content (a memory body, a policy rule, …). Opaque here; narrowed by `kind_type`. */
+  payload: unknown;
+  /** Agent-declared orthogonal facets (axis → value). */
+  facets: Record<string, string>;
+  /** Run/unit/agent attribution — AUTHORITY-STAMPED by the estate MCP from its launch env, never
+   *  taken from the submitter. Empty when the server had no `WICKED_RUN_*` env. */
+  provenance: Record<string, string>;
+  state: ProposalState;
+  /** Unix seconds. */
+  created_at: number;
+}
+
+/** `GET /proposals` query filters — both optional; omitting a filter lists across that dimension. */
+export interface ListProposalsQuery {
+  kind_type?: string;
+  state?: ProposalState;
+}
+
+/** `GET /proposals` → 200. */
+export interface ListProposalsResponse {
+  proposals: Proposal[];
+}
+
+/**
+ * The result of landing an approved POLICY proposal as a steering rule (DES-MEM-FACETED-001 §5.2).
+ * estate performs no rules-write for a policy proposal (the AW-11 invariant) — it hands the payload
+ * to crew, the one governed rules-write path, which shapes a `ConformanceRule` and upserts it. Like
+ * the steering-author landing (crew#388) the estate decision (approve) stands regardless, so a
+ * landing that could not complete reports `outcome:"failed"` with a loud, operator-readable `error`
+ * (recoverable by hand via `POST /governance/rules`) rather than turning the approve into a 500.
+ */
+export interface PolicyLandingResult {
+  /** `landed` = the steering rule is in the store; `failed` = the proposal is approved but no rule
+   *  was written — `error` says why. */
+  outcome: 'landed' | 'failed';
+  /** The upserted rule's id (deterministic `proposal:<proposalId>`, idempotent on replay). Present on `landed`. */
+  ruleId?: string;
+  /** The steering type derived from the proposal's `kind_type` (`policy:<type>`). Present on `landed`. */
+  steering_type?: SteeringType;
+  /** Present iff `outcome:"failed"` — the loud reason the rule did not land. */
+  error?: string;
+}
+
+/**
+ * `POST /proposals/:id/approve` → 200. A MEMORY proposal is `promoted` (its payload is now an
+ * active memory, `active_id`) and is complete. A POLICY proposal is `handed_off` — its `payload`
+ * (`{ rule, severity }`) is still returned verbatim, and `landing` now reports the steering rule
+ * crew created from it (`landing.outcome:"landed"` with the `ruleId`), or the loud reason it could
+ * not (`landing.outcome:"failed"`). `landing` is absent only from responses served by a daemon
+ * predating the policy→steering landing (forward-additive, DES-MEM-FACETED-001 §5.2).
+ */
+export type ApproveProposalResponse =
+  | { outcome: 'promoted'; active_id: string }
+  | { outcome: 'handed_off'; payload: unknown; landing?: PolicyLandingResult };
+
+/** `POST /proposals/:id/reject` → 200. */
+export interface RejectProposalResponse {
+  ok: true;
+}
+
+// ── Memory management (governed-knowledge surface, DES-MEM-FACETED-001, api-types 0.22.0) ──────
+//
+// The studio's surface for managing the memories that ALREADY exist in the operator store — the
+// counterpart to the proposal queue (which decides learnings not yet stored). Backed by the estate
+// MCP memory tools (memory.recall / memory.coverage / memory.erase) exposed over crew's /api/v1.
+// The granularity is estate's, surfaced honestly: browse is query-based (no "list all"), and
+// retire is SUBTREE-scoped (no per-id delete).
+
+/**
+ * One memory as browsed from the store (`GET /memory`, from estate `memory.recall`).
+ *
+ * estate `memory.recall` is query-based and token-budgeted — there is NO "list all" — and returns
+ * `{ memory_id, scope, content, tier, score }` per item. It does NOT surface per-item `facets`, so
+ * `facets` is presently always `{}` (kept in the shape for forward-compatibility and to mirror
+ * `Proposal.facets`); `score` is the recall relevance score, absent when estate omits it.
+ */
+export interface MemoryItem {
+  /** Stable memory-node id (estate `memory_id`). */
+  id: string;
+  /** The memory body. */
+  content: string;
+  /** Tier: `working` | `episodic` | `semantic` | `procedural` | `archival`. */
+  tier: string;
+  /** The memory's own hierarchical scope path (slash-separated `kind:id` segments; `""` = root). */
+  scope: string;
+  /** Orthogonal facets (axis → value) the memory is tagged with. Populated by estate `memory.list`
+   *  (the management browse) — this is what powers the surface's facet filter. `{}` for an
+   *  unfaceted memory (and for a `memory.recall`-sourced item, which carries no facets). */
+  facets: Record<string, string>;
+  /** Relevance score — only present on a `memory.recall` item; `memory.list` (the browse) is not
+   *  relevance-ranked, so it is absent there. */
+  score?: number;
+  /**
+   * Unix-SECONDS timestamp of when this memory FIRST entered the store — the "added" time the
+   * governance surface sorts + date-filters on (api-types 0.23.0). Populated from estate
+   * `memory.list`, which returns `created_at` per item; ABSENT — never fabricated — on a memory
+   * whose creation time the store did not report (and on a `memory.recall`-sourced item, which
+   * carries none). Additive: absence is the one spelling of "unknown", so a `since`/`until` filter
+   * cannot assert an undated memory in range.
+   */
+  created_at?: number;
+}
+
+/**
+ * `GET /memory` query filters. All optional. The browse itself lists the COMPLETE in-scope set via
+ * estate `memory.list`; `query`, `facets`, and `limit` are applied server-side as post-filters over
+ * that set (they are NOT a relevance query). `scope_prefix` is the only estate-side argument — a
+ * subtree filter where `""`/omitted matches EVERY memory (the same predicate as retire). `query` is
+ * a case-insensitive CONTENT substring match. `facets` is a JSON-encoded object of axis→value
+ * strings; an item is kept only if it carries every pair. `limit` caps the returned ROW count.
+ */
+export interface ListMemoriesQuery {
+  /** Case-insensitive content substring filter over the complete set. */
+  query?: string;
+  scope_prefix?: string;
+  /** JSON-encoded `Record<string, string>` (axis→value); a malformed value is a 400. */
+  facets?: string;
+  /** Positive integer; caps the returned row count. */
+  limit?: string;
+  /**
+   * Inclusive LOWER date bound (api-types 0.23.0): keep only memories with `created_at >= since`.
+   * Unix SECONDS, a non-negative integer (a present-but-non-integer value is a 400). Applied
+   * server-side over the loaded set, alongside `query`/`facets`. A memory with NO `created_at`
+   * is EXCLUDED whenever `since` (or `until`) is set — an unknown creation time is not asserted
+   * in range. Omitted ⇒ no lower bound.
+   */
+  since?: string;
+  /**
+   * Inclusive UPPER date bound (api-types 0.23.0): keep only memories with `created_at <= until`.
+   * Same units/validation/undated-exclusion as {@link ListMemoriesQuery.since}. Omitted ⇒ no
+   * upper bound.
+   */
+  until?: string;
+}
+
+/** `GET /memory` → 200. */
+export interface ListMemoriesResponse {
+  memories: MemoryItem[];
+}
+
+/** `GET /memory/coverage` query — an optional subtree filter (`""`/omitted = global totals). */
+export interface MemoryCoverageQuery {
+  scope_prefix?: string;
+}
+
+/**
+ * `GET /memory/coverage` → 200 (estate `memory.coverage`). Memory-node counts, optionally scoped to
+ * a subtree: `total`, plus per-tier and per-kind breakdowns.
+ */
+export interface MemoryCoverageResponse {
+  total: number;
+  by_tier: Record<string, number>;
+  by_kind: Record<string, number>;
+}
+
+/**
+ * `POST /memory/retire` body. Retire is SUBTREE-scoped, never per-id: estate `memory.erase`
+ * hard-deletes EVERY memory whose scope equals or descends from `scope_prefix`. `scope_prefix` is
+ * required and must be non-empty (estate refuses a total wipe) — the surface must show the operator
+ * the whole subtree it will remove, not a single row.
+ */
+export interface RetireMemoryBody {
+  scope_prefix: string;
+}
+
+/** `POST /memory/retire` → 200. The number of memories the subtree wipe deleted. */
+export interface RetireMemoryResponse {
+  erased: number;
+}

package/package.json

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