@qontinui/shared-types 2.1.0 → 2.3.0

package/dist/refusal.d.cts

@@ -50,6 +50,10 @@ interface NextAction {
   /**
    * What the action applies to: the command to run, the page to open, the
    * setting to set, the gate to wait for. Its meaning is fixed by `kind`.
+   * On [`NextActionKind::RetryLater`] it is what to re-check BEFORE
+   * retrying, because the earlier attempt may already have taken effect (a
+   * [`RefusalCode::UpstreamTimeout`] write); [`NextAction::render`] then
+   * says so. Omit it on a retry that is safe to repeat blindly.
    */
   target?: string | null;
   /**
@@ -80,6 +84,19 @@ type RefusalCode =
   | "sibling_checkout_absent"
   | "endpoint_unresolved"
   | "glossary_term_unknown"
+  | "authentication_required"
+  | "credential_rejected"
+  | "permission_denied"
+  | "not_found"
+  | "conflict"
+  | "invalid_request"
+  | "rate_limited"
+  | "quota_exceeded"
+  | "upstream_unavailable"
+  | "upstream_timeout"
+  | "device_not_connected"
+  | "service_unavailable"
+  | "internal_error"
   | "unknown";
 
 /* eslint-disable */

package/dist/refusal.d.ts

@@ -50,6 +50,10 @@ interface NextAction {
   /**
    * What the action applies to: the command to run, the page to open, the
    * setting to set, the gate to wait for. Its meaning is fixed by `kind`.
+   * On [`NextActionKind::RetryLater`] it is what to re-check BEFORE
+   * retrying, because the earlier attempt may already have taken effect (a
+   * [`RefusalCode::UpstreamTimeout`] write); [`NextAction::render`] then
+   * says so. Omit it on a retry that is safe to repeat blindly.
    */
   target?: string | null;
   /**
@@ -80,6 +84,19 @@ type RefusalCode =
   | "sibling_checkout_absent"
   | "endpoint_unresolved"
   | "glossary_term_unknown"
+  | "authentication_required"
+  | "credential_rejected"
+  | "permission_denied"
+  | "not_found"
+  | "conflict"
+  | "invalid_request"
+  | "rate_limited"
+  | "quota_exceeded"
+  | "upstream_unavailable"
+  | "upstream_timeout"
+  | "device_not_connected"
+  | "service_unavailable"
+  | "internal_error"
   | "unknown";
 
 /* eslint-disable */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qontinui/shared-types",
-  "version": "2.1.0",
+  "version": "2.3.0",
   "description": "Shared TypeScript types for the Qontinui ecosystem",
   "type": "module",
   "main": "./dist/index.js",

package/src/generated/BoundKind.d.ts

@@ -0,0 +1,11 @@
+/* eslint-disable */
+/**
+ * This file was automatically generated.
+ * DO NOT MODIFY IT BY HAND. Regenerate with
+ * `qontinui-runner/src-tauri/scripts/generate_types.sh`.
+ */
+
+/**
+ * The wire discriminant of a [`Bound`].
+ */
+export type BoundKind = "exact" | "at_least" | "complete" | "unknown";

package/src/generated/BoundedReadMeta.d.ts

@@ -0,0 +1,95 @@
+/* eslint-disable */
+/**
+ * This file was automatically generated.
+ * DO NOT MODIFY IT BY HAND. Regenerate with
+ * `qontinui-runner/src-tauri/scripts/generate_types.sh`.
+ */
+
+import type { BoundKind } from "./BoundKind";
+import type { FilterNarrowing } from "./FilterNarrowing";
+
+/**
+ * The envelope keys every bounded read serves beside its own collection key
+ * (plan `2026-09-05-every-bounded-read-is-a-page-that-reads-as-a-corpus`,
+ * §3 Layer 2).
+ *
+ * **Every key is ALWAYS present, and `null` is a value here, not an
+ * absence.** This deliberately departs from the crate's
+ * `skip_serializing_if = "Option::is_none"` convention: `total: null` says "no
+ * count ran", `truncated: null` says "unknown", and `next_cursor: null` says
+ * "there is no next page" — each a positive statement a reader must be able
+ * to see, not a key it might be missing because of an older server.
+ *
+ * Enforced on all three sides, because an absent key that silently reads as
+ * `null` is exactly the "absent is UNKNOWN, never a default" defect:
+ * serialization never skips a field; every `Option` field carries
+ * `#[schemars(required, schema_with = "nullable::<T>")]` — `required` because
+ * schemars 1 otherwise omits an `Option` from `required` (the generated
+ * Pydantic model would then default a missing key to `None`), and
+ * `schema_with` because `required` alone makes schemars emit the INNER type's
+ * schema, dropping `null` so generated models reject the value this wire
+ * sends; and deserialization uses `Option::deserialize`, which refuses a
+ * MISSING key instead of defaulting it (serde's derive otherwise treats an
+ * absent `Option` as `None`). Pinning tests assert, structurally, that
+ * `required` is exactly the field set and that every nullable key admits
+ * `null`.
+ *
+ * `count` and `limit` keep the spellings list doors already serve (coord
+ * #1897 put `count` on every agent list door; web proxies and runner pollers
+ * read both), so merging this into an existing response rewrites them with
+ * the same values rather than moving them.
+ */
+export interface BoundedReadMeta {
+  /**
+   * `false` ONLY when the store is unprovisioned: an empty page with
+   * `available: false` is UNKNOWN, not "nothing matched".
+   */
+  available: boolean;
+  /**
+   * Which kind of bound produced `total` / `truncated`.
+   */
+  bound_kind: BoundKind;
+  /**
+   * Rows in this page (the legacy spelling of `shown`).
+   */
+  count: number;
+  /**
+   * For a relevance-RANKED read, which can never hand out a cursor: the
+   * door that enumerates the same corpus by an immutable sort key (plan
+   * `2026-09-05-every-bounded-read-is-a-page-that-reads-as-a-corpus` D8), so
+   * a `truncated: true, next_cursor: null` answer still says how to reach
+   * the rest. `null` on a keyset walk, whose `next_cursor` is the way on.
+   */
+  enumerate_via: string | null;
+  /**
+   * A FILTER the surface narrowed before the read ran, or `null`.
+   */
+  filter_narrowed: FilterNarrowing | null;
+  /**
+   * The cap actually applied to this page.
+   */
+  limit: number;
+  /**
+   * The opaque token for the next page — pass it back verbatim as
+   * `cursor`. `null` iff `truncated` is not `true`, OR the read is a
+   * RANKING that cannot be paged — then `truncated` may be `true` with
+   * `next_cursor: null`, and `enumerate_via` names the door that walks the
+   * corpus by an immutable key.
+   */
+  next_cursor: string | null;
+  /**
+   * Rows in this page.
+   */
+  shown: number;
+  /**
+   * The exact match count from this page's start position — a number only
+   * when `bound_kind` is `exact`, else `null`.
+   */
+  total: number | null;
+  /**
+   * Whether matching rows exist beyond this page; `null` when
+   * `bound_kind` is `unknown`.
+   */
+  truncated: boolean | null;
+  [k: string]: unknown;
+}

package/src/generated/CapabilityState.d.ts

@@ -0,0 +1,25 @@
+/* eslint-disable */
+/**
+ * This file was automatically generated.
+ * DO NOT MODIFY IT BY HAND. Regenerate with
+ * `qontinui-runner/src-tauri/scripts/generate_types.sh`.
+ */
+
+/**
+ * Three-valued capability fact.
+ *
+ * `Unknown` is the default for anything a profile or catalog does not state.
+ * It is a distinct value from `Unsupported` on purpose: a boolean cannot
+ * represent "we never asked", and coercing that to "no" silently disables
+ * working capabilities.
+ *
+ * Moved here from qontinui-runner `src-tauri/src/model_catalog.rs` so the
+ * model/API layer (`ModelFacts`) and the CLI-session layer ([`CliProfile`])
+ * speak one tri-state; `model_catalog` re-exports it. Serialized as
+ * `"supported"` / `"unsupported"` / `"unknown"`.
+ *
+ * [`CapabilityState::Unknown`] must never be a reason to strip content or
+ * refuse a route. Callers that must act on an unknown fact should attempt the
+ * capability and let the backend be the authority.
+ */
+export type CapabilityState = "supported" | "unsupported" | "unknown";

package/src/generated/CliProfile.d.ts

@@ -0,0 +1,492 @@
+/* eslint-disable */
+/**
+ * This file was automatically generated.
+ * DO NOT MODIFY IT BY HAND. Regenerate with
+ * `qontinui-runner/src-tauri/scripts/generate_types.sh`.
+ */
+
+import type { CapabilityState } from "./CapabilityState";
+
+/**
+ * How one account's CLI state is kept apart from another's.
+ *
+ * Wire shape (internally tagged with `"kind"`):
+ * - `{ "kind": "env_var", "name": "CLAUDE_CONFIG_DIR" }`
+ * - `{ "kind": "home_dir" }` / `{ "kind": "none" }` / `{ "kind": "unknown" }`
+ */
+export type AccountIsolation =
+  | {
+      kind: "env_var";
+      /**
+       * The variable's name (`"CLAUDE_CONFIG_DIR"`).
+       */
+      name: string;
+      [k: string]: unknown;
+    }
+  | {
+      kind: "home_dir";
+      [k: string]: unknown;
+    }
+  | {
+      kind: "none";
+      [k: string]: unknown;
+    }
+  | {
+      kind: "unknown";
+      [k: string]: unknown;
+    };
+/**
+ * One way a CLI can be authenticated.
+ *
+ * Wire shape (internally tagged with `"kind"`):
+ * - `{ "kind": "cli_login", "args": ["login"] }`
+ * - `{ "kind": "api_key_env", "vars": ["OPENAI_API_KEY"] }`
+ *
+ * No `unknown` arm: an unknown auth story is an empty
+ * [`CliProfile::auth`] list.
+ */
+export type AuthMethod =
+  | {
+      /**
+       * Arguments after the program (`["login"]`, or `["/login"]` typed in
+       * the TUI).
+       */
+      args: string[];
+      kind: "cli_login";
+      [k: string]: unknown;
+    }
+  | {
+      kind: "api_key_env";
+      /**
+       * Variable names, in the CLI's precedence order.
+       */
+      vars: string[];
+      [k: string]: unknown;
+    };
+/**
+ * How the CLI is launched without per-tool approval prompts.
+ *
+ * Wire shape (internally tagged with `"kind"`):
+ * - `{ "kind": "flags", "argv": ["--permission-mode", "bypassPermissions"],
+ *   "detect": ["--dangerously-skip-permissions", "bypassPermissions"] }`
+ * - `{ "kind": "none" }` / `{ "kind": "unknown" }`
+ */
+export type AutoApprove =
+  | {
+      /**
+       * The flags the runner appends to enable auto-approval.
+       */
+      argv: string[];
+      /**
+       * Tokens whose presence on an existing argv means auto-approval is
+       * already on — every spelling the CLI accepts, not only the one the
+       * runner writes.
+       */
+      detect: string[];
+      kind: "flags";
+      [k: string]: unknown;
+    }
+  | {
+      kind: "none";
+      [k: string]: unknown;
+    }
+  | {
+      kind: "unknown";
+      [k: string]: unknown;
+    };
+/**
+ * How the runner asks a live session to exit cleanly.
+ *
+ * Wire shape (internally tagged with `"kind"`):
+ * - `{ "kind": "typed_command", "text": "/exit" }`
+ * - `{ "kind": "signal" }` / `{ "kind": "unknown" }`
+ *
+ * `Unknown` means the runner must type nothing and report that it could not
+ * exit the session gracefully.
+ */
+export type GracefulExit =
+  | {
+      kind: "typed_command";
+      /**
+       * The command text (`"/exit"`).
+       */
+      text: string;
+      [k: string]: unknown;
+    }
+  | {
+      kind: "signal";
+      [k: string]: unknown;
+    }
+  | {
+      kind: "unknown";
+      [k: string]: unknown;
+    };
+/**
+ * How the runner learns a CLI session's id.
+ *
+ * Wire shape (internally tagged with `"kind"`):
+ * - `{ "kind": "pinned", "flag": "--session-id" }`
+ * - `{ "kind": "read_back", "capture": "codex_session_file" }`
+ * - `{ "kind": "unknown" }`
+ */
+export type IdentitySource =
+  | {
+      /**
+       * The flag that takes the id (`"--session-id"`).
+       */
+      flag: string;
+      kind: "pinned";
+      [k: string]: unknown;
+    }
+  | {
+      /**
+       * Name of the runner capture mechanism that recovers the id
+       * (`"codex_session_file"`). The mechanism itself is runner behaviour.
+       */
+      capture: string;
+      kind: "read_back";
+      [k: string]: unknown;
+    }
+  | {
+      kind: "unknown";
+      [k: string]: unknown;
+    };
+/**
+ * What a restore of a CLI's session can honestly bring back.
+ *
+ * Serialized in the coord wire spelling the runner's `RestoreTier::wire_str`
+ * already uses: `"full"` / `"terminal_only"`.
+ *
+ * Defaults to `TerminalOnly` — the conservative claim: a profile that has not
+ * established resume must not promise the conversation back.
+ */
+export type RestoreTier = "full" | "terminal_only";
+/**
+ * How a session is resumed by id.
+ *
+ * Wire shape (internally tagged with `"kind"`):
+ * - `{ "kind": "by_id_argv", "template": ["claude", "--resume", "{id}"] }`
+ * - `{ "kind": "none" }` / `{ "kind": "unknown" }`
+ */
+export type ResumeSpec =
+  | {
+      kind: "by_id_argv";
+      /**
+       * The argv template (`["codex", "resume", "{id}"]`).
+       */
+      template: string[];
+      [k: string]: unknown;
+    }
+  | {
+      kind: "none";
+      [k: string]: unknown;
+    }
+  | {
+      kind: "unknown";
+      [k: string]: unknown;
+    };
+/**
+ * The machine-readable protocol a CLI offers besides its TUI.
+ *
+ * Wire shape (internally tagged with `"kind"` so an arm can gain data, e.g.
+ * an adapter command for `acp`, without a breaking change):
+ * `{ "kind": "claude_stream_json" }`, `{ "kind": "codex_app_server" }`,
+ * `{ "kind": "acp" }`, `{ "kind": "none" }`, `{ "kind": "unknown" }`.
+ */
+export type StructuredLane =
+  | {
+      kind: "claude_stream_json";
+      [k: string]: unknown;
+    }
+  | {
+      kind: "codex_app_server";
+      [k: string]: unknown;
+    }
+  | {
+      kind: "acp";
+      [k: string]: unknown;
+    }
+  | {
+      kind: "none";
+      [k: string]: unknown;
+    }
+  | {
+      kind: "unknown";
+      [k: string]: unknown;
+    };
+/**
+ * Where the CLI writes its conversation transcript.
+ *
+ * Wire shape (internally tagged with `"kind"`):
+ * - `{ "kind": "jsonl_under_config_dir", "subdir": "projects" }`
+ * - `{ "kind": "session_file_glob", "glob": ".codex/sessions/** /rollout-*.jsonl" }`
+ * - `{ "kind": "none" }` / `{ "kind": "unknown" }`
+ */
+export type TranscriptSpec =
+  | {
+      kind: "jsonl_under_config_dir";
+      /**
+       * Subdirectory of the config dir holding transcripts (`"projects"`).
+       */
+      subdir: string;
+      [k: string]: unknown;
+    }
+  | {
+      /**
+       * The glob (`".codex/sessions/** /rollout-*.jsonl"`).
+       */
+      glob: string;
+      kind: "session_file_glob";
+      [k: string]: unknown;
+    }
+  | {
+      kind: "none";
+      [k: string]: unknown;
+    }
+  | {
+      kind: "unknown";
+      [k: string]: unknown;
+    };
+/**
+ * Whether the CLI stops on a folder-trust prompt at first launch in a
+ * directory.
+ *
+ * Wire shape (internally tagged with `"kind"`):
+ * - `{ "kind": "prompt", "markers": ["Do you trust the files in this folder?"], "accept": "1" }`
+ * - `{ "kind": "none" }` / `{ "kind": "unknown" }`
+ */
+export type TrustDialog =
+  | {
+      /**
+       * The keystroke text that accepts it (sent followed by Enter).
+       */
+      accept: string;
+      kind: "prompt";
+      /**
+       * Case-insensitive substrings that identify the prompt on the
+       * ANSI-stripped screen.
+       */
+      markers: string[];
+      [k: string]: unknown;
+    }
+  | {
+      kind: "none";
+      [k: string]: unknown;
+    }
+  | {
+      kind: "unknown";
+      [k: string]: unknown;
+    };
+
+/**
+ * Everything the runner needs to know about one AI CLI's session behaviour.
+ *
+ * One instance per CLI (`claude`, `codex`, …), built by the runner as static
+ * data and served to the frontend (`GET /terminals/cli-profiles`, Tauri
+ * command `terminal_cli_profiles`) so no consumer holds a second copy.
+ *
+ * Every fact that can be unverified defaults to its `Unknown` arm; see the
+ * module docs. Scraped facts ([`Self::handshake`], [`Self::usage_limit_phrases`],
+ * [`TrustDialog::Prompt`]) break when the CLI changes its screens, which is
+ * why [`Self::verified_version`] records the CLI version they were verified
+ * against.
+ */
+export interface CliProfile {
+  /**
+   * How one account's CLI state is kept apart from another's.
+   */
+  accountIsolation?: AccountIsolation & {};
+  /**
+   * The ways the CLI can be authenticated. Empty means none are recorded —
+   * UNKNOWN, not "needs no authentication".
+   */
+  auth: AuthMethod[];
+  /**
+   * How the CLI is launched without per-tool approval prompts, and how an
+   * existing argv is recognised as already doing so.
+   */
+  autoApprove?: AutoApprove & {};
+  /**
+   * Human-readable name for launch menus and zone labels (`"Claude Code"`).
+   */
+  displayName: string;
+  /**
+   * How the runner asks a live session to exit cleanly.
+   */
+  gracefulExit?: GracefulExit & {};
+  /**
+   * On-screen markers that decide whether a resume succeeded or failed.
+   */
+  handshake?: HandshakePatterns & {};
+  /**
+   * Stable provider id (`"claude"`, `"codex"`). The same string the runner
+   * stores as a terminal session record's `provider`.
+   */
+  id: string;
+  /**
+   * How the runner learns the CLI's session id.
+   */
+  identity?: IdentitySource & {};
+  /**
+   * Per-OS install commands, shown beside a disabled launch entry when the
+   * CLI's binary is absent.
+   */
+  install?: InstallCommands & {};
+  /**
+   * Free-form caveats a reader should see beside the profile (e.g. "macOS:
+   * same code path, unverified on hardware").
+   */
+  notes?: string[];
+  /**
+   * Arguments that make the structured lane hand each tool approval to the
+   * runner as a typed permission request instead of deciding it itself
+   * (`["--permission-prompt-tool", "stdio"]`), verified against
+   * [`Self::verified_version`]. Rendered only for a launch that asks to be
+   * prompted, and never beside an auto-approve flag. Empty means no such
+   * arguments are known, so a prompted structured launch is not offered.
+   */
+  permissionPromptArgs?: string[];
+  /**
+   * Program stems that identify this CLI on an argv head or in a process
+   * census, without directory or extension (`["claude"]`). Matching strips
+   * the path and a Windows `.exe`/`.cmd` suffix before comparing.
+   */
+  programs: string[];
+  /**
+   * Arguments the runner appends to every PTY-hosted (interactive TUI)
+   * launch of this CLI, verified against [`Self::verified_version`]
+   * (`["--teammate-mode", "in-process"]`, which keeps Claude Code agent
+   * teams inside the session instead of splitting the caller's tmux window).
+   * Empty means none.
+   */
+  ptyArgs?: string[];
+  /**
+   * Whether the structured lane emits a typed rate-limit event.
+   */
+  rateLimitEvent?: CapabilityState & string;
+  /**
+   * What a restore of this CLI's session can honestly bring back.
+   */
+  restoreTier?: RestoreTier & string;
+  /**
+   * How a session is resumed by id.
+   */
+  resume?: ResumeSpec & {};
+  /**
+   * Other spellings the CLI accepts for the resume flag of
+   * [`ResumeSpec::ByIdArgv`] (`["-r"]`). Matched only as a whole argv
+   * token followed by the id, and only when the argv's program is this
+   * CLI: a short flag like `-r` means something else to most programs.
+   * Empty means none are known.
+   */
+  resumeFlagAliases?: string[];
+  /**
+   * Argv tokens, besides the identity flag, the resume flag and its
+   * aliases, by which the user picks the session themselves
+   * (`["--continue", "-c"]` — continue the most recent session). Any of
+   * them on a launch means the runner must not pin an id of its own. A token
+   * matches a whole argv entry case-insensitively; a `--long` token also
+   * matches `--long=…`. Empty means none are known.
+   */
+  sessionChoiceArgs?: string[];
+  /**
+   * The machine-readable protocol the CLI offers besides its TUI.
+   */
+  structuredLane?: StructuredLane & {};
+  /**
+   * Where the CLI writes its conversation transcript.
+   */
+  transcript?: TranscriptSpec & {};
+  /**
+   * Whether the CLI stops on a folder-trust prompt at first launch in a
+   * directory, and how to recognise and answer it.
+   */
+  trustDialog?: TrustDialog & {};
+  /**
+   * Whether the structured lane emits an explicit end-of-turn event.
+   */
+  turnBoundaryEvent?: CapabilityState & string;
+  /**
+   * Whether the structured lane delivers a typed permission request (a
+   * tool-use approval the runner answers) rather than bypassing approval.
+   */
+  typedPermission?: CapabilityState & string;
+  /**
+   * Case-insensitive phrases the CLI paints when an account's usage limit
+   * is reached. A grid match is a `Hint`-confidence
+   * [`FailureKind::QuotaExhausted`] signal, never a confirmed one. Empty
+   * means no phrases are known.
+   */
+  usageLimitPhrases: string[];
+  /**
+   * CLI version the scraped facts in this profile were verified against
+   * (`"2.1.285"`). `None` means no version was recorded — treat every
+   * scraped fact as unverified.
+   */
+  verifiedVersion?: string | null;
+  [k: string]: unknown;
+}
+/**
+ * On-screen markers that decide whether a resume succeeded or failed.
+ *
+ * Substring lists match the ANSI-stripped screen case-insensitively; regex
+ * lists are compiled by BOTH the Rust `regex` crate and JavaScript `RegExp`,
+ * so a pattern must stay in the syntax both engines accept (no look-around,
+ * no backreferences, no named-group syntax that differs between them).
+ *
+ * Regex sources are ALWAYS matched case-insensitively, like the substrings:
+ * each engine compiles them with its own case-insensitive switch (Rust
+ * `RegexBuilder::case_insensitive`, the JavaScript `i` flag). A source must
+ * therefore not carry inline flags such as `(?i)`, which JavaScript rejects.
+ *
+ * All body lists empty means no markers are known, and a resume cannot be
+ * verified from the screen.
+ */
+export interface HandshakePatterns {
+  /**
+   * Substrings whose presence means the resume failed.
+   */
+  failure: string[];
+  /**
+   * Regex sources (matched case-insensitively) whose match means the
+   * resume failed.
+   */
+  failureRegex: string[];
+  /**
+   * Substrings whose presence means the resumed session came up.
+   */
+  success: string[];
+  /**
+   * Regex sources (matched case-insensitively) whose match means the
+   * resumed session came up.
+   */
+  successRegex: string[];
+  /**
+   * Regex sources (matched case-insensitively) matched against the pane's
+   * CURRENT window title only, never its body, whose match means the
+   * resumed session came up. A title the CLI sets at launch is evidence the
+   * body cannot fake, provided the pattern is anchored to the CLI's own
+   * title (the shell titles the window too). Empty means none are known.
+   */
+  titleRegex?: string[];
+  [k: string]: unknown;
+}
+/**
+ * Per-OS install commands for a CLI. `None` for an OS means no command is
+ * recorded for it.
+ */
+export interface InstallCommands {
+  /**
+   * Install command on Linux (`"npm i -g @openai/codex"`).
+   */
+  linux?: string | null;
+  /**
+   * Install command on macOS.
+   */
+  macos?: string | null;
+  /**
+   * Install command on Windows.
+   */
+  windows?: string | null;
+  [k: string]: unknown;
+}

package/src/generated/FilterNarrowing.d.ts

@@ -0,0 +1,35 @@
+/* eslint-disable */
+/**
+ * This file was automatically generated.
+ * DO NOT MODIFY IT BY HAND. Regenerate with
+ * `qontinui-runner/src-tauri/scripts/generate_types.sh`.
+ */
+
+/**
+ * A FILTER the surface narrowed before running the read — reported, never
+ * applied silently, because a narrowed filter that reads as a complete answer
+ * is the same defect class as a silent empty.
+ *
+ * Promoted from `coord.findings`' `resource_keys_truncated`, the only
+ * narrowing any surface reported when this type was written: a list-valued
+ * filter truncated at a cap rather than refused (truncating a FILTER only
+ * narrows a read). Minimal on purpose — which parameter, how many values
+ * were actually applied, and the cap that dropped the rest. A caller seeing
+ * it knows a miss is meaningless for the values beyond the cap.
+ */
+export interface FilterNarrowing {
+  /**
+   * How many values of it the read actually applied.
+   */
+  applied: number;
+  /**
+   * The cap the surface enforces; values past it were dropped.
+   */
+  cap: number;
+  /**
+   * The query parameter that was narrowed, spelled as the caller spelled it
+   * on the wire (e.g. `resource_keys`).
+   */
+  parameter: string;
+  [k: string]: unknown;
+}

package/src/generated/FrontierEntry.d.ts

@@ -0,0 +1,62 @@
+/* eslint-disable */
+/**
+ * This file was automatically generated.
+ * DO NOT MODIFY IT BY HAND. Regenerate with
+ * `qontinui-runner/src-tauri/scripts/generate_types.sh`.
+ */
+
+import type { JourneyNode } from "./JourneyNode";
+
+/**
+ * An interactive affordance seen at a node and not yet the trigger of an
+ * edge from it — a row of `project.journey_frontier`, keyed
+ * `(app_id, node_key, affordance_fingerprint)`.
+ */
+export interface FrontierEntry {
+  /**
+   * Structural fingerprint of the affordance.
+   */
+  affordanceFingerprint: string;
+  /**
+   * ARIA role of the affordance; `None` = not reported.
+   */
+  affordanceRole?: string | null;
+  /**
+   * The registered app id.
+   */
+  appId: string;
+  /**
+   * The affordance's declared effect; `None` = undeclared.
+   */
+  declaredEffect?: ("read" | "write" | "destructive") | null;
+  /**
+   * First time it was seen at this node (ISO 8601).
+   */
+  firstSeenAt: string;
+  /**
+   * Most recent time it was seen at this node (ISO 8601).
+   */
+  lastSeenAt: string;
+  /**
+   * The run that most recently saw it; `None` = not reported.
+   */
+  lastSeenRunId?: string | null;
+  /**
+   * The node the affordance was seen at.
+   */
+  node: JourneyNode;
+  /**
+   * `node.key()` — stored so the primary key is a plain text column.
+   */
+  nodeKey: string;
+  /**
+   * Why it is on the frontier.
+   */
+  reason:
+    | "not_yet_activated"
+    | "effect_undeclared"
+    | "effect_write"
+    | "effect_destructive"
+    | "budget_exhausted"
+    | "activation_failed";
+}

package/src/generated/JourneyEdgeObservation.d.ts

@@ -0,0 +1,91 @@
+/* eslint-disable */
+/**
+ * This file was automatically generated.
+ * DO NOT MODIFY IT BY HAND. Regenerate with
+ * `qontinui-runner/src-tauri/scripts/generate_types.sh`.
+ */
+
+import type { JourneyNode } from "./JourneyNode";
+import type { JourneyTrigger } from "./JourneyTrigger";
+
+/**
+ * One observed edge of the journey graph — a row of
+ * `project.journey_edge_observations`.
+ *
+ * Invariants (checked by [`JourneyEdgeObservation::validate`]; the first also
+ * by the migration's CHECK): `to_node` is `None` iff `outcome` is
+ * [`EdgeOutcome::ToNodeUnobserved`]; `no_change` joins nodes with equal
+ * keys (a `changed` edge may also join equal keys).
+ *
+ * The ledger's `timeline` column is deliberately unrepresented until
+ * Phase 4; readers select explicit columns rather than `*`.
+ */
+export interface JourneyEdgeObservation {
+  /**
+   * The registered app id.
+   */
+  appId: string;
+  /**
+   * The SDK's self-reported version (`SdkAppInfo.version`, semver or git
+   * short-SHA); `None` = not reported, never "no version".
+   */
+  appVersion?: string | null;
+  /**
+   * The configuration the action was taken from.
+   */
+  fromNode: JourneyNode;
+  /**
+   * Row id (UUID).
+   */
+  id: string;
+  /**
+   * When the row was withdrawn (ISO 8601); `None` = live.
+   */
+  invalidatedAt?: string | null;
+  /**
+   * Who withdrew the row.
+   */
+  invalidatedBy?: string | null;
+  /**
+   * Why the row was withdrawn.
+   */
+  invalidatedReason?: string | null;
+  /**
+   * Token grouping one bulk withdrawal, as on `co_occurrence_observations`.
+   */
+  invalidationToken?: string | null;
+  /**
+   * When the edge CLOSED (to-snapshot seen, or diff returned), ISO 8601.
+   */
+  observedAt: string;
+  /**
+   * How the edge closed.
+   */
+  outcome:
+    "changed" | "no_change" | "error" | "settle_timeout" | "to_node_unobserved";
+  /**
+   * Agent session / task-run / recording-session id; `None` = not reported.
+   */
+  runId?: string | null;
+  /**
+   * Who produced the edge.
+   */
+  runKind: "agent_action" | "explorer" | "passive_session";
+  /**
+   * The runner's own `buildId`.
+   */
+  runnerBuildId: string;
+  /**
+   * Same meaning as `co_occurrence_observations.runner_instance`.
+   */
+  runnerInstance: string;
+  /**
+   * The configuration observed after it; `None` iff
+   * `outcome == to_node_unobserved`.
+   */
+  toNode?: JourneyNode | null;
+  /**
+   * What caused the edge.
+   */
+  trigger: JourneyTrigger;
+}

package/src/generated/JourneyLedgerHealth.d.ts

@@ -0,0 +1,21 @@
+/* eslint-disable */
+/**
+ * This file was automatically generated.
+ * DO NOT MODIFY IT BY HAND. Regenerate with
+ * `qontinui-runner/src-tauri/scripts/generate_types.sh`.
+ */
+
+/**
+ * Body of `GET /apps/{app_id}/journey/health`, and the ledger block every
+ * journey query response repeats.
+ */
+export interface JourneyLedgerHealth {
+  /**
+   * Human-readable cause, e.g. `"embedded DB predates the journey tables"`.
+   */
+  detail: string;
+  /**
+   * The ledger's state.
+   */
+  state: "writing" | "schema_absent" | "write_failing";
+}

package/src/generated/JourneyNode.d.ts

@@ -0,0 +1,72 @@
+/* eslint-disable */
+/**
+ * This file was automatically generated.
+ * DO NOT MODIFY IT BY HAND. Regenerate with
+ * `qontinui-runner/src-tauri/scripts/generate_types.sh`.
+ */
+
+/**
+ * A vertex of the journey graph: one observed configuration of one page.
+ *
+ * Identity is a deterministic predicate, not a judgment: a node is
+ * `(spec_id, sorted active IR state ids)` within an app. When the page has
+ * no spec, or no state was classified present, the node is UNMODELLED and is
+ * identified by its route template (else its page label) — it still takes
+ * part in reachability and is counted as unmodelled in coverage.
+ *
+ * Build one with [`JourneyNode::new`], which sorts and dedups `state_ids`
+ * and derives `modelled`; [`JourneyNode::key`] is the canonical string form
+ * stored in `journey_frontier.node_key`.
+ *
+ * Node identity is `key()` / `node_key` — NEVER jsonb equality of the
+ * serialized node (which also carries non-identity detail such as
+ * `pageLabel` on a modelled node).
+ * Unlike the crate's other optional fields, this struct's optional fields
+ * always serialize, as `null` when absent, so every stored node has the same
+ * key set.
+ */
+export interface JourneyNode {
+  /**
+   * True iff `spec_id` is present AND `state_ids` is non-empty.
+   */
+  modelled: boolean;
+  /**
+   * An APP-DECLARED page identifier — never a URL path, never user input.
+   *
+   * PRODUCER OBLIGATION (this is the privacy guarantee): fill it only from
+   * the snapshot's `page.pageContext.meta.tabId`, then `activeTab`, then
+   * `page.pageContext.name`, and NEVER from `page.pathname` in any form,
+   * raw or slugged. (The runner's existing `resolve_page_label` in
+   * `state_discovery/capture.rs` has a fourth fallback that slugs
+   * `page.pathname`; the journey producer must not use that fallback.)
+   * `pageContext.name` is a free-form display name (e.g. `"Import /
+   * Export"`), so the producer SLUGS it before storing — which leaves a
+   * `/` meaning only one thing: a leaked, unslugged path.
+   *
+   * [`JourneyNode::validate`] rejects a `/` as a TRIPWIRE for that leak.
+   * It is not the guarantee: a slugged path contains no `/` and passes.
+   */
+  pageLabel: string | null;
+  /**
+   * The framework route PATTERN the snapshot's page was served under
+   * (e.g. `/admin/coord/runs/[id]`), when known. Never a concrete URL path:
+   * a concrete path can embed user input (`/search/<term>`,
+   * `/users/<email>`). Not heuristically validated — the producer must
+   * fill it from the router's pattern, not from `location.pathname`.
+   */
+  pathnameTemplate: string | null;
+  /**
+   * The page spec the snapshot matched; `None` = no spec for this page.
+   * Load-bearing: some state ids are declared on more than one page.
+   * Must not contain `#` or start with `unmodelled:` (see [`JourneyNode::key`]).
+   */
+  specId: string | null;
+  /**
+   * Ids of the IR states classified present — deduped, in BYTE-WISE
+   * (UTF-8) ascending order, i.e. Rust's `str` ordering. Producers in
+   * other languages must sort by UTF-8 bytes (not UTF-16 code units, not
+   * a locale collation) or their keys will not match. No id may contain
+   * `,` (see [`JourneyNode::key`]).
+   */
+  stateIds: string[];
+}

package/src/generated/JourneyTrigger.d.ts

@@ -0,0 +1,47 @@
+/* eslint-disable */
+/**
+ * This file was automatically generated.
+ * DO NOT MODIFY IT BY HAND. Regenerate with
+ * `qontinui-runner/src-tauri/scripts/generate_types.sh`.
+ */
+
+/**
+ * What caused an edge — structurally only.
+ *
+ * `deny_unknown_fields` and the deliberate absence of any text/value field
+ * are the privacy control: a caller cannot smuggle a typed value into the
+ * ledger, because no such key deserializes and no such field exists to set.
+ */
+export interface JourneyTrigger {
+  /**
+   * The action verb (`click`, `type`, `select`, a component action id, …).
+   */
+  actionType: string;
+  /**
+   * Which runner choke point captured it.
+   */
+  chokePoint:
+    | "element_action"
+    | "batch_action"
+    | "component_action"
+    | "sdk_element_action"
+    | "execute_with_diff"
+    | "navigation";
+  /**
+   * The affordance's declared effect; `None` = undeclared (NOT "safe").
+   */
+  declaredEffect?: ("read" | "write" | "destructive") | null;
+  /**
+   * How the transition was initiated.
+   */
+  navigationTrigger:
+    "affordance" | "push" | "replace" | "pop" | "initial" | "hash";
+  /**
+   * Structural fingerprint of the target element; `None` = not resolved.
+   */
+  targetFingerprint?: string | null;
+  /**
+   * ARIA role of the target; `None` = not reported.
+   */
+  targetRole?: string | null;
+}

package/src/generated/NextAction.d.ts

@@ -21,6 +21,10 @@ export interface NextAction {
   /**
    * What the action applies to: the command to run, the page to open, the
    * setting to set, the gate to wait for. Its meaning is fixed by `kind`.
+   * On [`NextActionKind::RetryLater`] it is what to re-check BEFORE
+   * retrying, because the earlier attempt may already have taken effect (a
+   * [`RefusalCode::UpstreamTimeout`] write); [`NextAction::render`] then
+   * says so. Omit it on a retry that is safe to repeat blindly.
    */
   target?: string | null;
   /**

package/src/generated/RefusalCode.d.ts

@@ -17,4 +17,17 @@ export type RefusalCode =
   | "sibling_checkout_absent"
   | "endpoint_unresolved"
   | "glossary_term_unknown"
+  | "authentication_required"
+  | "credential_rejected"
+  | "permission_denied"
+  | "not_found"
+  | "conflict"
+  | "invalid_request"
+  | "rate_limited"
+  | "quota_exceeded"
+  | "upstream_unavailable"
+  | "upstream_timeout"
+  | "device_not_connected"
+  | "service_unavailable"
+  | "internal_error"
   | "unknown";

package/src/generated/SessionFailure.d.ts

@@ -0,0 +1,129 @@
+/* eslint-disable */
+/**
+ * This file was automatically generated.
+ * DO NOT MODIFY IT BY HAND. Regenerate with
+ * `qontinui-runner/src-tauri/scripts/generate_types.sh`.
+ */
+
+/**
+ * An action a surface may offer for a failure. Serialized `snake_case`.
+ */
+export type FailureAction =
+  "retry" | "login" | "switch_account" | "new_session" | "resume" | "none";
+
+/**
+ * One failure of an AI session, whichever lane noticed it.
+ *
+ * Emitted on the runner's `session-failure` event and readable from its
+ * failures route, so a surface can render *why* a session stopped and which
+ * actions are available, instead of an exit code or a bare banner. The
+ * runner's classifier fills it from a signal and its recovery table chooses
+ * [`Self::recovery_policy`]; neither lives in this crate.
+ */
+export interface SessionFailure {
+  /**
+   * The account the session was running under, when known.
+   */
+  account?: string | null;
+  /**
+   * Actions a surface may offer the user, in display order.
+   */
+  actions: FailureAction[];
+  /**
+   * Coarse grouping of [`Self::kind`] for filtering and styling.
+   */
+  category:
+    | "limit"
+    | "context"
+    | "auth"
+    | "provider"
+    | "process"
+    | "session"
+    | "request"
+    | "unknown";
+  /**
+   * Longer human-readable explanation.
+   */
+  details?: string | null;
+  evidence: FailureEvidence;
+  /**
+   * Unique id of this failure occurrence (UUID minted by the runner).
+   */
+  id: string;
+  /**
+   * What went wrong. [`FailureKind::Unknown`] is a real answer, not "fine".
+   */
+  kind:
+    | "rate_limited"
+    | "quota_exhausted"
+    | "budget_exhausted"
+    | "context_exhausted"
+    | "auth_required"
+    | "access_denied"
+    | "overloaded"
+    | "transport_lost"
+    | "resume_failed"
+    | "spawn_failed"
+    | "process_exited"
+    | "bad_request"
+    | "internal_error"
+    | "unknown";
+  /**
+   * The [`CliProfile::id`] of the CLI whose session failed.
+   */
+  provider: string;
+  /**
+   * The raw reason the source gave, verbatim (a provider error type, a
+   * stderr line, the matched screen phrase), for diagnosis.
+   */
+  reason?: string | null;
+  /**
+   * What the runner does about it automatically.
+   */
+  recoveryPolicy:
+    | "never"
+    | "backoff_then_retry"
+    | "wait_until_reset"
+    | "migrate_account"
+    | "login_then_resume"
+    | "resume_same_id"
+    | "handoff_new_session";
+  /**
+   * When a limit resets (RFC 3339), when the source states it.
+   */
+  resetAt?: string | null;
+  /**
+   * How serious the failure is for the session.
+   */
+  severity: "info" | "warning" | "error";
+  /**
+   * One-line human-readable summary.
+   */
+  title: string;
+  /**
+   * The turn that failed, when the source identifies one.
+   */
+  turnId?: string | null;
+  [k: string]: unknown;
+}
+/**
+ * Where the failure was observed and how sure the runner is of it.
+ */
+export interface FailureEvidence {
+  /**
+   * Whether the source states the failure or merely suggests it.
+   */
+  confidence: "confirmed" | "hint";
+  /**
+   * The signal source.
+   */
+  source:
+    | "structured_event"
+    | "hook"
+    | "stderr"
+    | "grid_scrape"
+    | "exit_status"
+    | "transcript"
+    | "handshake_timeout";
+  [k: string]: unknown;
+}

package/src/generated/index.ts

@@ -55,6 +55,8 @@ export type { BatchComputeEmbeddingRequest } from './BatchComputeEmbeddingReques
 export type { BatchComputeEmbeddingResponse } from './BatchComputeEmbeddingResponse';
 export type { BatchEmbeddingResult } from './BatchEmbeddingResult';
 export type { BetweenIterations } from './BetweenIterations';
+export type { BoundKind } from './BoundKind';
+export type { BoundedReadMeta } from './BoundedReadMeta';
 export type { BoundingBox } from './BoundingBox';
 export type { BridgeFingerprint } from './BridgeFingerprint';
 export type { BuildPhaseConfig } from './BuildPhaseConfig';
@@ -62,10 +64,12 @@ export type { BuiltinOverrideProposal } from './BuiltinOverrideProposal';
 export type { CandidateMiss } from './CandidateMiss';
 export type { CanonicalStep } from './CanonicalStep';
 export type { CanvasPanel } from './CanvasPanel';
+export type { CapabilityState } from './CapabilityState';
 export type { CatchUpPolicy } from './CatchUpPolicy';
 export type { Category } from './Category';
 export type { CheckIssueDetail } from './CheckIssueDetail';
 export type { CheckType } from './CheckType';
+export type { CliProfile } from './CliProfile';
 export type { CodeExecutionStep } from './CodeExecutionStep';
 export type { CommandMode } from './CommandMode';
 export type { CommandStep } from './CommandStep';
@@ -172,6 +176,7 @@ export type { ExportResult } from './ExportResult';
 export type { ExtendIterationsRequest } from './ExtendIterationsRequest';
 export type { FieldDiff } from './FieldDiff';
 export type { FileChange } from './FileChange';
+export type { FilterNarrowing } from './FilterNarrowing';
 export type { Finding } from './Finding';
 export type { FindingActionType } from './FindingActionType';
 export type { FindingBatchCreate } from './FindingBatchCreate';
@@ -188,6 +193,7 @@ export type { FindingUpdate } from './FindingUpdate';
 export type { FindingUserInput } from './FindingUserInput';
 export type { FindingsSummary } from './FindingsSummary';
 export type { FlowEvent } from './FlowEvent';
+export type { FrontierEntry } from './FrontierEntry';
 export type { FullRunnerStep } from './FullRunnerStep';
 export type { FunctionalSpec } from './FunctionalSpec';
 export type { GUIElementChunk } from './GUIElementChunk';
@@ -241,6 +247,10 @@ export type { JobItem } from './JobItem';
 export type { JobListResponse } from './JobListResponse';
 export type { JobStatus } from './JobStatus';
 export type { JobSummary } from './JobSummary';
+export type { JourneyEdgeObservation } from './JourneyEdgeObservation';
+export type { JourneyLedgerHealth } from './JourneyLedgerHealth';
+export type { JourneyNode } from './JourneyNode';
+export type { JourneyTrigger } from './JourneyTrigger';
 export type { LLMCostSummary } from './LLMCostSummary';
 export type { LLMMetrics } from './LLMMetrics';
 export type { LegacyAssertion } from './LegacyAssertion';
@@ -395,6 +405,7 @@ export type { SearchStrategy } from './SearchStrategy';
 export type { SectionVerdict } from './SectionVerdict';
 export type { SemanticSearchRequest } from './SemanticSearchRequest';
 export type { SemanticSearchResponse } from './SemanticSearchResponse';
+export type { SessionFailure } from './SessionFailure';
 export type { SessionLite } from './SessionLite';
 export type { SessionSource } from './SessionSource';
 export type { SpecApiEvent } from './SpecApiEvent';