local-operator-ui 0.33.16 → 0.33.17

package/out/preload/index.js

@@ -1,5 +1,6 @@
 "use strict";
 const electron = require("electron");
+const zod = require("zod");
 const electronAPI = {
   ipcRenderer: {
     send(channel, ...args) {
@@ -86,6 +87,2065 @@ function readTelemetryArgument(argv) {
 const BACKEND_STATUS_CHANNEL = "backend-status";
 const BACKEND_STATUS_EVENT = "backend-status-changed";
 const BACKEND_RECONNECT_CHANNEL = "backend-reconnect";
+const id = zod.z.string().min(1).max(128).regex(/^[a-zA-Z0-9_-]+$/);
+const settingKey = zod.z.string().min(1).max(256).regex(/^[a-zA-Z0-9_][a-zA-Z0-9_.-]*$/);
+const secret = zod.z.string().min(1).max(32768);
+const sessionIdPattern = /^[a-f0-9]{12}$/;
+const sessionId = zod.z.string().regex(sessionIdPattern);
+const skillCwd = zod.z.string().min(1).max(4096);
+const mcpServerName = zod.z.string().regex(/^[A-Za-z0-9_.:-]{1,100}$/);
+const mcpSecretReference = zod.z.string().regex(/^\$\{[A-Za-z_][A-Za-z0-9_]*\}$/);
+const mcpOperationId = zod.z.string().regex(/^[a-f0-9]{32}$/);
+const mcpCatalogCwdPattern = /^(\/|[A-Za-z]:[\\/])/;
+const mcpCatalogCwd = zod.z.string().min(1).max(4096).regex(mcpCatalogCwdPattern);
+const SUBSCRIPTION_ID_PATTERN = /^[a-f0-9]{32}$/;
+const requestId = zod.z.string().regex(/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/);
+const meshId = zod.z.string().regex(/^[A-Za-z0-9_-]{1,128}$/);
+const approvalId = zod.z.string().regex(/^ap_[0-9a-hjkmnp-tv-z]{1,64}$/);
+const sessionImage = zod.z.object({
+  data_b64: zod.z.string().min(1).max(1e6),
+  mime_type: zod.z.enum(["image/png", "image/jpeg", "image/gif", "image/webp"])
+}).strict();
+const DESKTOP_MESSAGE_MAX_CHARS = 2e5;
+const DESKTOP_MESSAGE_MAX_IMAGES = 8;
+const SESSION_SEARCH_MAX_CHARS = 256;
+const CHECKPOINT_WARM_MAX_IDS = 16;
+const THREAD_FIND_MAX_CHARS = 256;
+const THREAD_FIND_MAX_LIMIT = 200;
+const DESKTOP_SYSTEM_PROMPT_MAX_CHARS = 1e6;
+const profileName = zod.z.string().min(1).max(128).refine(
+  (name) => name !== "." && name !== ".." && !name.includes("/") && !name.includes("\\") && [...name].every(
+    (character) => character.charCodeAt(0) >= 32 && character.charCodeAt(0) !== 127
+  )
+);
+const target = zod.z.object({ kind: zod.z.enum(["agent", "team"]), name: profileName }).strict();
+const modelSelection = zod.z.object({
+  provider: zod.z.string().min(1).max(128),
+  model_id: zod.z.string().min(1).max(512),
+  reasoning_effort: zod.z.string().min(1).max(64).nullable()
+}).strict();
+const profileFields = zod.z.object({
+  kind: zod.z.enum(["role", "specialist"]).optional(),
+  description: zod.z.string().max(8e3).optional(),
+  instructions: zod.z.string().max(8e3).optional(),
+  tools: zod.z.array(zod.z.string().min(1).max(128)).max(256).optional(),
+  effort: zod.z.string().max(64).optional(),
+  delegate: zod.z.boolean().optional(),
+  /*
+   * The action class (`reactive` | `proactive`), the field the Class control
+   * writes. An ENUM rather than a free string, because the route takes a
+   * `Literal` and a spelling this schema let through would be a 422 the
+   * caller could not tell from a bug — the same reasoning `scheduleUnit`
+   * above states. Optional like every other field here: an omitted key means
+   * "leave the class alone" on an update, which is what lets the control send
+   * the class and nothing else.
+   */
+  action_class: zod.z.enum(["reactive", "proactive"]).optional()
+}).strict();
+const teamFields = zod.z.object({
+  name: zod.z.string().min(1).max(64).optional(),
+  description: zod.z.string().max(8e3).optional(),
+  manager: profileName.optional(),
+  members: zod.z.array(
+    zod.z.object({
+      role: profileName,
+      count: zod.z.number().int().min(1).max(16),
+      kind: zod.z.enum(["agent", "team"])
+    }).strict()
+  ).max(128).optional(),
+  instructions: zod.z.string().max(8e3).optional(),
+  project: zod.z.string().max(8e3).optional()
+}).strict();
+const chains = zod.z.record(zod.z.array(zod.z.string().max(1024)).max(100));
+const scheduleUnit = zod.z.enum(["minutes", "hours", "days"]);
+function isAddressableVariableKey(key) {
+  return !/^\.+$/.test(key);
+}
+const variableKey = zod.z.string().min(1).max(128).refine(
+  (key) => [...key].every(
+    (character) => character.charCodeAt(0) >= 32 && character.charCodeAt(0) !== 127 && character !== "/" && character !== "\\"
+  )
+).refine(isAddressableVariableKey);
+const variableType = zod.z.enum(["str", "int", "float", "bool", "list", "dict"]);
+const variableValue = zod.z.string().max(16384);
+const WAKE_MESSAGE_MAX_CHARS = 2e3;
+const wakeMessage = zod.z.string().min(1).max(WAKE_MESSAGE_MAX_CHARS);
+const wakeId = zod.z.string().min(1).max(64);
+const monitorId = zod.z.string().min(1).max(64);
+const scheduleWrite = zod.z.object({
+  is_active: zod.z.boolean().nullish(),
+  one_time: zod.z.boolean().nullish(),
+  start_time_utc: zod.z.string().max(64).nullish(),
+  end_time_utc: zod.z.string().max(64).nullish()
+}).strict();
+const configUpdate = zod.z.object({
+  conversation_length: zod.z.number().int().optional(),
+  detail_length: zod.z.number().int().optional(),
+  max_learnings_history: zod.z.number().int().optional(),
+  hosting: zod.z.string().max(256).optional(),
+  model_name: zod.z.string().max(1024).optional(),
+  auto_save_conversation: zod.z.boolean().optional()
+}).strict();
+const PUBLICATION_NAME_MAX_CHARS = 128;
+const PUBLICATION_DESCRIPTION_MAX_CHARS = 2e3;
+const PUBLICATION_INSTRUCTIONS_MAX_CHARS = 8e3;
+const PUBLICATION_TOOL_MAX_CHARS = 64;
+const PUBLICATION_TOOLS_MAX_ITEMS = 64;
+const publicationCharCount = (value) => [...value].length;
+const isPublicationWhiteSpace = (point) => point >= 9 && point <= 13 || point >= 28 && point <= 32 || point === 133 || point === 160 || point === 5760 || point >= 8192 && point <= 8202 || point === 8232 || point === 8233 || point === 8239 || point === 8287 || point === 12288;
+const isPublicationControlWhitespace = (point) => point === 9 || point === 10 || point === 11 || point === 12 || point === 13 || point === 133;
+const isPublicationControl = (point) => point <= 31 || point >= 127 && point <= 159;
+const isPublicationFormat = (point) => /\p{Cf}/u.test(String.fromCodePoint(point));
+const isPublicationBidiOverride = (point) => point >= 8234 && point <= 8238 || point >= 8294 && point <= 8297;
+const publicationHasCodePoint = (value, predicate) => {
+  for (const character of value) {
+    if (predicate(character.codePointAt(0) ?? 0)) return true;
+  }
+  return false;
+};
+const publicationTrim = (value) => {
+  const characters = [...value];
+  let start = 0;
+  let end = characters.length;
+  while (start < end && isPublicationWhiteSpace(characters[start].codePointAt(0) ?? 0))
+    start++;
+  while (end > start && isPublicationWhiteSpace(characters[end - 1].codePointAt(0) ?? 0))
+    end--;
+  return characters.slice(start, end).join("");
+};
+function publicationNameRule(name) {
+  const trimmed = publicationTrim(name);
+  if (!trimmed) return "must not be empty";
+  if (publicationCharCount(trimmed) > PUBLICATION_NAME_MAX_CHARS)
+    return `must be at most ${PUBLICATION_NAME_MAX_CHARS} characters`;
+  if (/[/\\:]/.test(trimmed)) return 'must not contain "/", "\\" or ":"';
+  if (publicationHasCodePoint(trimmed, isPublicationBidiOverride))
+    return "must not contain Unicode bidirectional override characters";
+  if (publicationHasCodePoint(trimmed, isPublicationControlWhitespace))
+    return "must not contain whitespace";
+  if (publicationHasCodePoint(trimmed, isPublicationControl))
+    return "must not contain control characters";
+  if (publicationHasCodePoint(trimmed, isPublicationFormat))
+    return "must not contain invisible Unicode formatting characters";
+  const characters = [...trimmed];
+  if ("-.".includes(characters[0]) || "-.".includes(characters[characters.length - 1]))
+    return 'must not begin or end with "-" or "."';
+  return null;
+}
+function publicationDescriptionRule(description) {
+  if (!description.trim()) return "must not be empty";
+  if (publicationCharCount(description) > PUBLICATION_DESCRIPTION_MAX_CHARS)
+    return `must be at most ${PUBLICATION_DESCRIPTION_MAX_CHARS} characters`;
+  return null;
+}
+function publicationInstructionsRule(instructions) {
+  if (!instructions.trim()) return "must not be empty";
+  if (publicationCharCount(instructions) > PUBLICATION_INSTRUCTIONS_MAX_CHARS)
+    return `must be at most ${PUBLICATION_INSTRUCTIONS_MAX_CHARS} characters`;
+  return null;
+}
+function publicationToolsRule(tools) {
+  if (tools.length > PUBLICATION_TOOLS_MAX_ITEMS)
+    return `must hold at most ${PUBLICATION_TOOLS_MAX_ITEMS} items`;
+  for (const tool of tools) {
+    if (!tool.trim() || publicationCharCount(tool) > PUBLICATION_TOOL_MAX_CHARS)
+      return `must hold items of 1 to ${PUBLICATION_TOOL_MAX_CHARS} characters`;
+  }
+  return null;
+}
+const isPublishableName = (name) => publicationNameRule(name) === null;
+const publicationName = zod.z.string().refine(isPublishableName, {
+  message: "That is not a name the hub can publish."
+});
+const publicationInstructions = zod.z.string().refine(
+  (instructions) => publicationInstructionsRule(instructions) === null,
+  { message: "That instruction body cannot be published." }
+);
+const publicationDescription = zod.z.string().refine((description) => publicationDescriptionRule(description) === null, {
+  message: "That description cannot be published."
+});
+const publicationTools = zod.z.array(zod.z.string()).refine((tools) => publicationToolsRule(tools) === null, {
+  message: "That tool list cannot be published."
+});
+const publicationDocument = zod.z.object({
+  name: publicationName,
+  description: publicationDescription,
+  instructions: publicationInstructions,
+  kind: zod.z.enum(["role", "specialist"]),
+  when_to_use: zod.z.string(),
+  tools: publicationTools,
+  effort: zod.z.string(),
+  delegate: zod.z.boolean(),
+  version: zod.z.string(),
+  categories: zod.z.array(zod.z.string()),
+  tags: zod.z.array(zod.z.string())
+}).partial().strict();
+const catalogueScopeKind = zod.z.enum(["team", "agent"]);
+const catalogueScopeName = zod.z.string().min(1).max(64);
+const catalogueCursor = zod.z.string().min(1).max(256);
+const PROJECT_NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+const projectName = zod.z.string().regex(PROJECT_NAME_PATTERN, {
+  message: "Letters, digits, dot, underscore and dash; no spaces."
+});
+const PROJECT_STATUSES = [
+  "planning",
+  "active",
+  "qa",
+  "validation",
+  "done",
+  "paused",
+  "archived"
+];
+const projectStatus = zod.z.enum(PROJECT_STATUSES);
+const projectDate = zod.z.string().regex(/^$|^\d{4}-\d{2}-\d{2}$/, "Dates are YYYY-MM-DD, or empty to clear.");
+const projectTags = zod.z.array(zod.z.string().min(1).max(24)).max(8);
+const projectKey = zod.z.string().min(1).max(64);
+const PROJECT_PROGRESS_MAX_CHARS = 1e3;
+const PROJECT_DESCRIPTION_MAX_CHARS = 240;
+const PROJECT_MILESTONE_NAME_MAX_CHARS = 80;
+const PROJECTS_SEARCH_MAX_CHARS = 256;
+const PROJECTS_SEARCH_MAX_LIMIT = 200;
+const hubItemKind = zod.z.enum(["agent", "team"]);
+const desktopRequestUnion = zod.z.discriminatedUnion("op", [
+  zod.z.object({ op: zod.z.literal("capabilities") }).strict(),
+  /*
+   * THE MACHINE'S RUNTIME ROSTER, read for the straggler census a completed
+   * server update reports (`GET /v1/desktop/runtimes`). A GET with a fixed
+   * shape, so the whole request is the op.
+   *
+   * It reads the INVENTORY (`probe=false` in the path composer): the census
+   * asks every row what build it booted with, and the route's per-row loopback
+   * connects answer a different question ("did it answer?") that nothing here
+   * acts on. Skipping them also keeps the response inside the control budget
+   * without depending on the probe pool's own deadline logic.
+   *
+   * THE CONTROL BUDGET IS THE RIGHT ONE, and it is a bound rather than a hope:
+   * the route's own ceiling is the two external reads in front of the
+   * composition (5 s process table + 3 s socket table, stated in `roster.py`),
+   * and `probe=false` skips the per-row connects entirely - so the worst case
+   * is ~8 s, well under the 20 s control deadline. It is NOT on the long-read
+   * list: nothing here fans out to a provider or walks a ledger.
+   */
+  zod.z.object({ op: zod.z.literal("runtimes.list") }).strict(),
+  zod.z.object({ op: zod.z.literal("profiles.list") }).strict(),
+  zod.z.object({ op: zod.z.literal("profiles.get"), name: profileName }).strict(),
+  zod.z.object({ op: zod.z.literal("profiles.install"), name: profileName, requestId }).strict(),
+  zod.z.object({
+    op: zod.z.literal("profiles.create"),
+    name: profileName,
+    requestId,
+    fields: profileFields.extend({
+      description: zod.z.string().max(8e3),
+      instructions: zod.z.string().min(1).max(8e3)
+    })
+  }).strict(),
+  zod.z.object({
+    op: zod.z.literal("profiles.update"),
+    name: profileName,
+    requestId,
+    fields: profileFields
+  }).strict(),
+  /*
+   * THE HUB AUTO-UPDATE PLANE (backend `server/routes/desktop_hub.py`, gated by
+   * the `hub_updates` capability). `hub.updates` is a STORE READ on the backend
+   * (no network, O(items)), which is what makes it safe to poll from the
+   * sidebar; the five mutations are the ones that touch the hub or write a
+   * local definition, and each carries a `requestId` so a lost response is
+   * replayed by the server's receipts rather than re-run.
+   *
+   * `kind` is closed to the two definition families the hub carries, and `name`
+   * is the profile/team NAME because names are the runtime's attachment keys.
+   * `prefer` is per-item only: the backend refuses it on apply-all, since a
+   * conflict decision cannot be made for a set of items at once, so the
+   * apply-all schema does not offer it.
+   */
+  zod.z.object({ op: zod.z.literal("hub.updates") }).strict(),
+  zod.z.object({
+    op: zod.z.literal("hub.check"),
+    requestId,
+    kind: hubItemKind.optional(),
+    name: profileName.optional()
+  }).strict(),
+  zod.z.object({
+    op: zod.z.literal("hub.apply"),
+    requestId,
+    kind: hubItemKind,
+    name: profileName,
+    prefer: zod.z.enum(["local", "remote"]).optional(),
+    acknowledgeUnknownBaseline: zod.z.boolean().optional(),
+    dryRun: zod.z.boolean().optional()
+  }).strict(),
+  zod.z.object({
+    op: zod.z.literal("hub.applyAll"),
+    requestId,
+    kind: hubItemKind.optional()
+  }).strict(),
+  zod.z.object({
+    op: zod.z.literal("hub.retry"),
+    requestId,
+    kind: hubItemKind,
+    name: profileName
+  }).strict(),
+  zod.z.object({ op: zod.z.literal("teams.list") }).strict(),
+  zod.z.object({ op: zod.z.literal("teams.get"), name: profileName }).strict(),
+  zod.z.object({
+    op: zod.z.literal("teams.create"),
+    requestId,
+    fields: teamFields.extend({ name: zod.z.string().min(1).max(64) })
+  }).strict(),
+  zod.z.object({
+    op: zod.z.literal("teams.update"),
+    name: profileName,
+    requestId,
+    fields: teamFields
+  }).strict(),
+  zod.z.object({
+    op: zod.z.literal("sessions.list"),
+    limit: zod.z.number().int().min(1).max(500).optional(),
+    /*
+     * Whether ARCHIVED conversations belong in the answer.
+     *
+     * ABSENT MEANS `false`, and that default is a compatibility promise rather
+     * than a preference: a client that predates archiving sends no such field
+     * and must keep the list it always had rather than acquiring rows it has no
+     * way to mark, filter or restore. This app sends `true` and partitions the
+     * archived rows out of every default list itself (see `fetchSessions` in the
+     * canonical sessions store and `visibleRows` in `features/chat/chat-archived`),
+     * which is what lets ONE fetch serve both the hidden list and the two
+     * questions a list that hides them cannot answer: the open conversation's own
+     * archived state, and an unarchive control on a row found by search.
+     */
+    include_archived: zod.z.boolean().optional(),
+    /*
+     * Whether conversations OTHER devices hold belong in the answer.
+     *
+     * ABSENT MEANS `false`, the same compatibility promise `include_archived`
+     * makes and for the same reason: the app's own sidebar fetch has always
+     * meant "this device's catalogue", and a client that predates the mesh must
+     * keep reading exactly that. The Mesh tab is the ONE surface that asks for
+     * the federated list, because "which conversation is on which device" is its
+     * question and it cannot answer it from `session_count` alone.
+     *
+     * THE COST IS NOT ZERO, which is why only that surface asks: the backend's
+     * peer projection dials each peer's relay under a 12 s fan-out budget and is
+     * TTL-cached at 20 s (`network/relay.py`, `session/peer_rows.py`), while a
+     * machine in no network short-circuits to no call at all — so the flag costs
+     * a paired device one cached fan-out per cadence, and an unpaired one
+     * nothing. The sidebar's two-second poll must never carry it.
+     */
+    include_peers: zod.z.boolean().optional(),
+    /*
+     * The four parameters that make the catalogue PAGEABLE, and the switch that
+     * makes the daemon count it.
+     *
+     * ALL FOUR ARE OPTIONAL AND DEFAULTED, which is the whole compatibility
+     * promise: a request that sends none of them is byte-identical to the one
+     * this app sent before they existed, and an older daemon is therefore fully
+     * supported. They are gated on the `session_catalogue_page` capability rather
+     * than on a `session_catalogue` version bump, for the reason that map's own
+     * register states (an EXISTING surface must keep working against a backend
+     * that lacks the new one): FastAPI silently ignores unknown query parameters,
+     * so an un-gated client asking for `scope_kind=team&scope_name=lopdev` would
+     * receive the UNSCOPED page and draw other teams' rows under that team, and an
+     * un-gated `cursor` would receive page one again and duplicate it. The client
+     * has to be able to ask whether the daemon understands these, and the
+     * capability map is how this codebase asks.
+     *
+     * They travel as ONE contract revision rather than three: counts without the
+     * scope could not be rendered consistently with that scope's paged rows.
+     */
+    scope_kind: catalogueScopeKind.optional(),
+    scope_name: catalogueScopeName.optional(),
+    cursor: catalogueCursor.optional(),
+    with_counts: zod.z.boolean().optional()
+  }).strict(),
+  /*
+   * Acknowledge the one-time delegated-cleanup notice:
+   * `POST /v1/desktop/delegated-cleanup-notice/ack`.
+   *
+   * The notice rides `sessions.list` UNTIL this write lands: the GET is a
+   * non-consuming peek (every list answer keeps carrying the field while the
+   * store is unacknowledged, which is what lets a second window see the same
+   * notice), and this op is the one thing that flips `notice_acknowledged` on
+   * disk. The route is idempotent - acknowledging an acknowledged store writes
+   * what is already there - so, like `sessions.archive`, it needs no
+   * `requestId`: a retry cannot flip anything back.
+   */
+  zod.z.object({ op: zod.z.literal("delegated_cleanup_notice.ack") }).strict(),
+  zod.z.object({
+    // Content search over the store: name, id, exact conversation body, and
+    // a bounded soft tier. `q` is capped at the backend's own 256-character
+    // bound so an over-long query is refused here, by name, rather than by
+    // the backend's generic "invalid fields" 422.
+    op: zod.z.literal("sessions.search"),
+    // `.min(1)`: an EMPTY query is not a search. The backend answers one by
+    // listing the whole store (documented there, and used by the phone's web
+    // client), but this surface has that list already — its box is a filter
+    // over the catalogue — so an empty `q` here would ask the server to send
+    // back everything the client is holding. Refusing it by name is how the
+    // closed vocabulary stays closed: no caller can send a request whose
+    // answer it would have to discard.
+    q: zod.z.string().min(1).max(SESSION_SEARCH_MAX_CHARS),
+    limit: zod.z.number().int().min(1).max(500).optional(),
+    /*
+     * Whether the SCAN admits archived conversations, absent meaning `false`
+     * (the same compatibility promise `sessions.list` states).
+     *
+     * The sidebar's "Include archived" control is the only writer, and the flag is
+     * in the query's cache key on this side because the two answers to one query
+     * are different questions: without that, toggling the control off would serve
+     * the answer that carries the archived hits and the rows would linger - the
+     * stale-row failure `chat-search.test.mjs` pins.
+     */
+    include_archived: zod.z.boolean().optional()
+  }).strict(),
+  /*
+   * Archive or unarchive ONE conversation: `POST /v1/desktop/sessions/{id}/archive`.
+   *
+   * DESIRED STATE ON THE WIRE (`archived: true|false`), never a bare toggle, for
+   * the reason the pin op states beside its own field: over HTTP a toggle is not
+   * idempotent, and a request retried after a dropped response would flip the
+   * conversation back. Idempotent by construction here rather than by a receipt:
+   * re-archiving an archived conversation writes what is already there, so the op
+   * carries no `requestId` (the same at-most-once trade `sessions.warm` makes for
+   * a call that already is).
+   *
+   * Archiving is RECOVERABLE and therefore never confirmed: it hides the
+   * conversation from the default lists and from search, and unarchiving restores
+   * it. Deliberately NOT a `MESSAGE_OPS` member (see `desktopRequestByteBudget`):
+   * a boolean and a 12-char id are not prose.
+   */
+  zod.z.object({
+    op: zod.z.literal("sessions.archive"),
+    sessionId,
+    archived: zod.z.boolean()
+  }).strict(),
+  /*
+   * Delete ONE conversation PERMANENTLY: `DELETE /v1/desktop/sessions/{id}`.
+   *
+   * `confirmed: true` is required and is not a receipt: it is the wire's own echo
+   * of the user's answer to a danger dialog, so a caller that has not asked cannot
+   * express this request at all (a missing field is a 422 here, by name, rather
+   * than a delete nobody confirmed). The route refuses the delete of a session
+   * that is LIVE with a 409 and a sentence naming the guard - the one refusal this
+   * surface renders inside the dialog that asked, which is why the op needs no
+   * failure vocabulary of its own.
+   *
+   * It removes exactly the addressed conversation and NOT its subagent children;
+   * a surface that has children to mention says so in its own copy rather than
+   * implying a wider blast radius. No `requestId`: the delete is not retried by
+   * this client, and a retry of a delete cannot be owed an answer - the second
+   * call's honest answer is 404 and the outcome the user asked for either way.
+   */
+  zod.z.object({
+    op: zod.z.literal("sessions.delete"),
+    sessionId,
+    confirmed: zod.z.literal(true)
+  }).strict(),
+  zod.z.object({
+    op: zod.z.literal("sessions.create"),
+    requestId,
+    /*
+     * OPTIONAL ONLY FOR A `purpose` CREATE, and the pair is enforced below by
+     * the union's own `superRefine` rather than by two union members: a
+     * `discriminatedUnion` accepts one member per `op` value, and a `.refine`
+     * on a member would make it a `ZodEffects` the union refuses (the same
+     * constraint `agent.publish`'s pairing rule states).
+     *
+     * WHY A CONFIGURATION RUN OMITS IT AT ALL. `cwd` exists so a conversation
+     * has a folder to work in, and this app has always refused an empty one
+     * precisely because it would resolve to "a directory the user never named".
+     * A configuration run edits this device's registries and holds no file
+     * tools at all, so its cwd is not authority — and the renderer cannot name
+     * one honestly: it would have to invent a path it cannot verify exists.
+     * The backend resolves it (to the config directory) when `purpose` is set.
+     */
+    cwd: zod.z.string().min(1).max(4096).optional(),
+    target: target.optional(),
+    /*
+     * WHAT KIND OF SESSION THIS IS, when it is not a conversation the operator
+     * asked for: `agents-config` starts a supervised configuration run (the
+     * Agents page's composer), which the backend stamps as a hidden origin and
+     * admits through the desktop door for watch/events/messages/interrupt
+     * without ever listing it as one of the operator's conversations.
+     *
+     * A LITERAL, so a typo is a compile error on this side and a 422 on a
+     * backend that does not know the value. It is capability-gated before it is
+     * ever sent (`agents_config`), because a backend older than this field
+     * validates the create body with `extra="forbid"` and would report a
+     * malformed request for a request the app deliberately made.
+     */
+    purpose: zod.z.literal("agents-config").optional(),
+    /*
+     * OMITTED when the user never picked anything, so the body is the one
+     * this op sent before the draft's chips could open: making them
+     * actionable is strictly additive, and a `null` here would be a
+     * different request for every caller that never asked.
+     */
+    model: modelSelection.optional(),
+    /*
+     * The id a `sessions.draft` mint handed the pane, when it has one: the
+     * create then adopts that id (and the runtime already engaged for it)
+     * instead of minting a fresh session id. OMITTED when the pane never
+     * minted — an older backend, a draft the user sent before the first
+     * keystroke's mint answered, or a set of fields that changed since the
+     * mint (see the store's drop rule) — so the body is byte-for-byte the
+     * request this op sent before the draft could be warmed, and a backend
+     * that cannot resolve the id mints fresh rather than failing the send.
+     */
+    draftId: sessionId.optional(),
+    /*
+     * The DEVICE to create the conversation on (`features.peers`): the mesh route's
+     * own field, sent only when the user actually picked one, so the body of an
+     * ordinary create is unchanged. Omitted means this device.
+     *
+     * THE DIRECTORY RULE THAT COMES WITH IT, which is why the app must not offer this
+     * choice without saying so: a remote create carries an explicit `cwd` and an EMPTY
+     * one resolves to that device's home rather than to this project, so a pane with a
+     * peer destination names the directory it will use.
+     *
+     * `--yolo` and friends are NOT here because the peer's own route refuses them: a
+     * remote create that let this machine run tools unattended on another one is the
+     * thing the route declines to express.
+     */
+    peer: meshId.optional()
+  }).strict(),
+  /*
+   * What a NEW conversation's readings would be, without creating anything.
+   *
+   * The composer's status strip needs a model, an effort ladder and a window
+   * BEFORE a session exists, and every honest way to get them was rejected: a
+   * `sessions.create` on pane open writes a directory and a marker, so every
+   * abandoned new-chat pane would leave a visible empty row in the sidebar,
+   * and composing it in the renderer from `config.get` + `models.catalogue`
+   * moves model RESOLUTION (Python policy) into the app and reports nothing
+   * when the pair is absent from the catalogue. This op runs the backend's own
+   * cold resolution and returns the same canonical projection a cold session
+   * publishes, so the strip keeps one arithmetic path and the draft cannot
+   * disagree with the session the first send creates.
+   *
+   * Body and response mirror `sessions.create` deliberately: same `cwd`, same
+   * optional `target`, same `model` and same 422 for an unresolvable profile —
+   * the pane is asking the question it will ask for real on the first send, so
+   * the two bodies are derived from one selection. The response is a
+   * `CanonicalFrontendSync` — the wire shape `sessions.watch` streams — whose
+   * `snapshot.session_id` is EMPTY, because there is no session. The renderer
+   * passes it to the strip and never into the canonical sessions store.
+   */
+  zod.z.object({
+    op: zod.z.literal("sessions.preview"),
+    requestId,
+    cwd: zod.z.string().min(1).max(4096),
+    target: target.optional(),
+    /* Present only when the pane's chips were used: the preview then answers
+       the reading the CHOSEN model gives, which is the ladder and window the
+       first turn will actually get. */
+    model: modelSelection.optional()
+  }).strict(),
+  /*
+   * Mint the id a NEW chat's runtime is warmed and then born on, from the
+   * pane's first keystroke.
+   *
+   * WHY THE OP EXISTS. A draft pane has no session to address, so there is
+   * nothing to warm: `sessions.warm` needs an id, and the multi-second engage
+   * the first send pays is exactly what the draft cannot pre-empt without one.
+   * The mint allocates that id and registers it with the daemon (fast, no
+   * engage), and the id then unlocks the same three doors a session pane uses
+   * — `events`, `watch` (the lease) and `warm` — through a deliberately narrow
+   * allow-list on the backend. `sessions.create` adopts the id on send, so the
+   * conversation the user lands in IS the one that was warmed; a daemon that
+   * has never seen the id (restart, expiry, eviction) mints fresh and the send
+   * works exactly as it did before this op existed.
+   *
+   * THE MINT ENGAGES NOTHING, and that is the lifetime design rather than an
+   * omission: the pane's own subscription and watch lease hold the bridge that
+   * keeps a warm alive, exactly as they do for a session, so abandoning the
+   * pane cancels an in-flight warm through the same `_detach` and a runtime
+   * nobody holds is reaped by the residency drain. There is no second, warmer-
+   * owned lifetime to get wrong.
+   *
+   * `requestId` IS A RECEIPT KEY, unlike `sessions.preview`'s token: a mint is
+   * fired once per pane, and a retry — a fast second keystroke, a lost
+   * response — must replay the SAME id, because two ids for one pane would
+   * warm two runtimes and leave a registry entry nobody can ever consume.
+   *
+   * The body is `sessions.create`'s first half, deliberately: same `cwd` bounds,
+   * same optional `target`, same optional `model` and the same 422 for an
+   * unresolvable profile. The pane is asking the question it will ask for real
+   * on the first send, so both derive from one selection and cannot disagree.
+   *
+   * Deliberately NOT a `MESSAGE_OPS` member (see `desktopRequestByteBudget`):
+   * a path and two optional short ids are not prose, so the mint costs the
+   * control budget — which is what lets a KEYSTROKE issue it.
+   */
+  zod.z.object({
+    op: zod.z.literal("sessions.draft"),
+    requestId,
+    cwd: zod.z.string().min(1).max(4096),
+    target: target.optional(),
+    model: modelSelection.optional()
+  }).strict(),
+  zod.z.object({ op: zod.z.literal("sessions.get"), sessionId }).strict(),
+  zod.z.object({
+    op: zod.z.literal("sessions.history"),
+    sessionId,
+    beforeId: id.optional(),
+    limit: zod.z.number().int().min(1).max(500).optional()
+  }).strict(),
+  /*
+   * The transcript checkpoint rail's manifest (design D1/D9): every material
+   * checkpoint of one LOCAL conversation — the reader's own messages and each
+   * completed turn — with the seq-proportional ordinal the rail places a tick
+   * by, and a completion's optional generated name.
+   *
+   * The answer is deliberately cheap and never blocks on a scan: a cold or
+   * stale index answers `state: "building"` while a refresh runs in the
+   * background (the backend measures 22 s for this machine's 272 MB journal),
+   * so the rail's first paint is immediate and the hook polls while anything
+   * it asked for is still pending. A remote/peer conversation answers
+   * `state: "unsupported"` — a fact about where the bytes are, not a failure
+   * — and the rail hides, the same degradation as an empty manifest.
+   */
+  zod.z.object({ op: zod.z.literal("sessions.checkpoints"), sessionId }).strict(),
+  /*
+   * Buy names for checkpoints (design D2/D9): idempotent, bounded, and never
+   * blocking on the model call itself — the backend schedules one
+   * `complete_once` per turn (15 s budget, single attempt, a 10-minute
+   * cooldown after a failure) and answers accepted/pending immediately.
+   *
+   * `ids` is the hover gesture's arm (a bounded set of explicit checkpoint
+   * ids); omitting it is the rail-open arm, where the backend selects the
+   * most recent checkpoints missing names under its own default. Both fields
+   * are optional, and an older backend that predates the op answers the same
+   * 404/422 a missing route always does — the hook treats any failure as "no
+   * rail here", never as a user-facing error.
+   */
+  zod.z.object({
+    op: zod.z.literal("sessions.checkpoints.warm"),
+    sessionId,
+    ids: zod.z.array(id).max(CHECKPOINT_WARM_MAX_IDS).optional(),
+    limit: zod.z.number().int().min(1).max(CHECKPOINT_WARM_MAX_IDS).optional()
+  }).strict(),
+  /*
+   * In-thread find (D9): messages of ONE conversation matching `q`, best
+   * first, served from the per-session transcript index.
+   *
+   * A READ like `history` and `checkpoints` beside it. The answer's `state` is
+   * the checkpoint manifest's own ladder: a cold or stale index answers
+   * `building` inside the first-paint budget (with hits ranked from the
+   * previous scan marked `partial`) while the background refresh runs, so the
+   * overlay's first paint is immediate; `unsupported` is a peer conversation
+   * whose journal is not on this device; `error` is a failed refresh inside
+   * its cooldown. The overlay renders both tiers (`exact`/`soft`) and treats
+   * `ranges` as snippet-relative — empty on a soft hit, which has no literal
+   * occurrence of the query by construction.
+   */
+  zod.z.object({
+    op: zod.z.literal("sessions.find"),
+    sessionId,
+    // `.min(1)`: an empty query is not a search. The overlay's client never
+    // sends one — it answers an empty query locally, without a request — so
+    // refusing it by name keeps the vocabulary closed rather than paying a
+    // round trip for an answer the box already knows.
+    q: zod.z.string().min(1).max(THREAD_FIND_MAX_CHARS),
+    limit: zod.z.number().int().min(1).max(THREAD_FIND_MAX_LIMIT).optional()
+  }).strict(),
+  /*
+   * One child's durable transcript, for the run panel's reader
+   * (`docs/run-sidebar.md` § 10.1, § 10.3).
+   *
+   * Both ids are the same `^[a-f0-9]{12}$` the whole desktop surface already
+   * validates on, and NEITHER is a path: the child directory is resolved by the
+   * route from the id and from the parent's own roster, so the renderer cannot
+   * name a directory at all. That containment is the route's, not the caller's —
+   * a schema that accepted a path here would be the whole boundary.
+   *
+   * `beforeId` is an entry id (max 128 chars, the `id` shape) rather than an
+   * offset, matching `sessions.history`: file compaction replaces the JSONL
+   * atomically, so offsets become lies while ids stay meaningful.
+   */
+  zod.z.object({
+    op: zod.z.literal("subagents.transcript"),
+    sessionId,
+    childId: sessionId,
+    beforeId: id.optional(),
+    limit: zod.z.number().int().min(1).max(500).optional()
+  }).strict(),
+  zod.z.object({
+    op: zod.z.literal("sessions.message"),
+    sessionId,
+    requestId,
+    text: zod.z.string().max(DESKTOP_MESSAGE_MAX_CHARS),
+    images: zod.z.array(sessionImage).max(DESKTOP_MESSAGE_MAX_IMAGES).optional(),
+    mode: zod.z.enum(["prompt", "steer"]).optional(),
+    /*
+     * HOW THE MESSAGE WAS PRODUCED (arch §4.2), and the harness gate is what
+     * keeps this `optional`: `features.input_mode`. Absent means a legacy
+     * body (and is what every older build sends), so an older harness's own
+     * `.strict()` schema never sees the key at all.
+     *
+     * `inputPath` is RESERVED (§4.2a): the route cascade owns its
+     * vocabulary and no caller sets it yet; it is accepted here - bounded -
+     * so the first caller that does does not also need a contract change.
+     */
+    inputMode: zod.z.enum(["typed", "dictated", "mixed"]).optional(),
+    inputPath: zod.z.string().max(1024).optional()
+  }).strict(),
+  zod.z.object({
+    op: zod.z.literal("sessions.command"),
+    sessionId,
+    requestId,
+    command: zod.z.string().regex(/^\/?[A-Za-z]+$/).max(64),
+    args: zod.z.string().max(DESKTOP_MESSAGE_MAX_CHARS).optional(),
+    images: zod.z.array(sessionImage).max(DESKTOP_MESSAGE_MAX_IMAGES).optional()
+  }).strict(),
+  /*
+   * Point a LIVE session at another working directory (the desktop's `/move`).
+   *
+   * Its own op rather than an argument to `sessions.command`, and the reason is
+   * where the work happens: the move is executed in the SERVER process against
+   * the session's viewer (`POST
+   * /v1/desktop/sessions/{id}/working-directory`), while the command endpoint
+   * answers a `NativeAction | OwnerCommandResult` - the union's other member is
+   * the RUNTIME's own slash answer, and a move produces neither. `/move`
+   * therefore stays a presentation request in the backend's command catalogue
+   * (`desktop_destination="session.move"`): a bare `/move` opens the picker,
+   * and the argument form and the chip both call this op instead. The shape is
+   * `sessions.warm`'s: a lifecycle operation on the session's runtime, with its
+   * own receipt.
+   *
+   * Deliberately NOT a `MESSAGE_OPS` member (see `desktopRequestByteBudget`): a
+   * path is not prose, and claiming image-sized room for a 4 KB field would
+   * spend the message budget on nothing. `cwd` carries the same bound as
+   * `sessions.create`/`sessions.preview` because it reaches the same route
+   * model, which refuses anything else.
+   */
+  zod.z.object({
+    op: zod.z.literal("sessions.move"),
+    sessionId,
+    requestId,
+    cwd: zod.z.string().min(1).max(4096)
+  }).strict(),
+  zod.z.object({
+    op: zod.z.literal("sessions.answer"),
+    sessionId,
+    /**
+     * The owner epoch, for the two GATE shapes. Optional here because a queued
+     * ask has no epoch to give — `ask_id` is the other selector and the checks
+     * below require exactly one of the pair.
+     */
+    epoch: id.optional(),
+    requestId: id.optional(),
+    value: zod.z.string().max(32768).optional(),
+    approved: zod.z.boolean().optional(),
+    questionIndex: zod.z.number().int().min(0).optional(),
+    /**
+     * The queued ask's id (`a-3f9c`). Its presence selects the THIRD body shape —
+     * `{ask_id, answers}` or `{ask_id, decline}` — and, per the backend's own
+     * contract, makes `epoch` irrelevant rather than optional-but-checked: an ask
+     * outlives the owner that queued it, so requiring an epoch would refuse
+     * exactly the case the feature exists for (a cold session whose asks are
+     * still open). The single-winner rule that the epoch check used to provide
+     * now lives on the ask log, where the first `answered` event wins.
+     */
+    askId: id.optional(),
+    /**
+     * The WHOLE ask's answers, keyed by question id, each a list because a
+     * question may be multi-select.
+     *
+     * One atomic body rather than a per-question stream: the blocking path
+     * answered one question at a time over the wire, and a client that died
+     * part-way left an ask half-settled — the exact state the atomic submit
+     * exists to make unrepresentable.
+     */
+    answers: zod.z.record(zod.z.string(), zod.z.array(zod.z.string().max(32768))).optional(),
+    /** "No answer — decide yourself", the explicit form of today's Esc. */
+    decline: zod.z.boolean().optional(),
+    /**
+     * CHANGE a recorded answer instead of submitting a first one (design §10,
+     * #1936).
+     *
+     * A modifier on the SAME `{ask_id, answers}` body, and it has to be sent
+     * explicitly because the intent is not recoverable from the values: equal
+     * values are not a retry marker and different values are not a revision
+     * (§10 — "no layer may infer a revision by comparing values"). The backend
+     * accepts it only while the answer is still UNDELIVERED and refuses it with
+     * its own sentence once the response row exists; this client does not
+     * pre-judge that, it renders the owner's refusal.
+     */
+    revise: zod.z.boolean().optional()
+  }).strict(),
+  zod.z.object({
+    op: zod.z.literal("sessions.seen"),
+    sessionId,
+    completionToken: zod.z.string().uuid()
+  }).strict(),
+  /*
+   * Bulk acknowledgement: mark many completions read in ONE user gesture
+   * (`POST /v1/desktop/attention/seen`).
+   *
+   * Its OWN op rather than a loop over `sessions.seen`, for two reasons that are
+   * both about what the receipt MEANS. The backend writes the whole batch in one
+   * `BEGIN IMMEDIATE`, so an observer sees the pre-batch or the post-batch receipt
+   * set and never a prefix; N round trips would expose a partial batch to every
+   * poller, and a failure half way would leave the user unable to tell which
+   * marks went. And the items are TOKEN-bound on purpose: the batch names exactly
+   * the completions the client has RENDERED, so a completion published between
+   * the render and the click is not in it and stays unread. A watermark sweep
+   * ("acknowledge everything now") would clear exactly that result instead, which
+   * is the hazard the per-session receipt exists to prevent — so this op never
+   * carries a time, a count or a "all" flag, only the pairs the client observed.
+   *
+   * `items` is 1..500: 500 is the catalogue's own maximum page, so every row the
+   * sidebar can hold is sendable in one call and `markAllRead` never has to
+   * chunk (chunking would break "one gesture, one request").
+   */
+  zod.z.object({
+    op: zod.z.literal("attention.seen"),
+    items: zod.z.array(
+      zod.z.object({
+        sessionId,
+        // A REAL uuid, like `sessions.seen`: a token that is not one cannot
+        // name a completion, so it is refused here rather than round-tripped
+        // to answer `unknown` for an item the client should not have sent.
+        completionToken: zod.z.string().uuid()
+      }).strict()
+    ).min(1).max(500)
+  }).strict(),
+  // Cross-surface delivery claim, NOT a read receipt. `claim_delivery`
+  // serialises the observers that can see one completion (a TUI, this app) so
+  // exactly one of them toasts it. It deliberately never advances the read
+  // watermark: routing a notification must not clear the sidebar's unseen mark
+  // for a session the user never opened, which is why this is its own op and
+  // not a reuse of `sessions.seen`.
+  zod.z.object({
+    op: zod.z.literal("sessions.notified"),
+    sessionId,
+    completionToken: zod.z.string().uuid()
+  }).strict(),
+  /*
+   * Pin or unpin a conversation, in the SHARED pin store the terminal's `f10`
+   * writes (`local_operator/tui/sidebar_pins.py`), so a conversation pinned in
+   * the TUI is pinned in this app and the other way round.
+   *
+   * DESIRED STATE ON THE WIRE (`pinned: true|false`), never a bare toggle, and
+   * this is the decision the op exists to carry. The TUI's verb is a toggle
+   * because it is a keypress; over HTTP a toggle is not idempotent - a request
+   * retried after a dropped response flips the pin back, and the user reports
+   * "the pin keeps un-pinning itself" in the one feature whose whole value is
+   * reliability. The route makes the call idempotent BY CONSTRUCTION instead of
+   * putting it on the receipt ladder: re-pinning an already-pinned conversation
+   * is a no-op that does not reorder, and unpinning an unpinned one writes
+   * nothing. That is also why there is no `requestId` here - at-most-once is
+   * bought only for calls that ADMIT WORK (`sessions.warm` carries no receipt
+   * for the same reason), and a call that is already idempotent needs none.
+   *
+   * Deliberately NOT a `MESSAGE_OPS` member (see `desktopRequestByteBudget`):
+   * a boolean and a 12-char id are not prose, so this costs the control budget.
+   */
+  zod.z.object({
+    op: zod.z.literal("sessions.pin"),
+    sessionId,
+    pinned: zod.z.boolean()
+  }).strict(),
+  zod.z.object({
+    op: zod.z.literal("sessions.watch"),
+    sessionId,
+    subscriptionId: zod.z.string().regex(SUBSCRIPTION_ID_PATTERN),
+    visible: zod.z.boolean(),
+    canNotify: zod.z.boolean()
+  }).strict(),
+  // Speculative runtime engage. Carries no payload BY DESIGN: it admits no
+  // work, so it is not receipt-keyed and not a `MESSAGE_OPS` member - see
+  // `desktopRequestByteBudget`. Firing it costs the control budget and a
+  // 2-byte body, which is what lets the renderer issue it from a keystroke.
+  zod.z.object({ op: zod.z.literal("sessions.warm"), sessionId }).strict(),
+  /*
+   * Stop the session's CURRENT TURN and the work under it, leaving the session
+   * and its process alive: the composer's Stop control and the Escape that is
+   * its accelerator.
+   *
+   * Its OWN op rather than an argument to `sessions.command`, because the
+   * command endpoint answers a presentation form: `/stop` is a catalogue entry
+   * whose `native_action` asks the client to open the session-stop picker, so a
+   * body of `{command: "stop"}` there answers 200, changes nothing, and reads as
+   * a stop that worked. That is the reported defect this op exists to remove.
+   *
+   * NOT `sessions.stop` either, and the two are one letter apart on purpose of
+   * naming rather than of meaning: `sessions.stop` is the KILL SWITCH (deny the
+   * pending gates, dispose the runtime, release the writer lease, unpublish,
+   * exit) reached from the `/stop` picker, and it is the rung ABOVE this one. A
+   * client that could not interrupt a turn can still stop a session; a backend
+   * that can do the second must not be told it can do the first, which is why
+   * the capability key is new rather than a `lifecycle` bump.
+   *
+   * `requestId` is the route's receipt key: "make the current turn stop" is
+   * idempotent and creates or destroys nothing, so the same id replayed with the
+   * same body answers the first receipt rather than interrupting twice.
+   *
+   * Deliberately NOT a `MESSAGE_OPS` member (see `desktopRequestByteBudget`): a
+   * uuid is not prose, so this costs the control budget.
+   */
+  zod.z.object({ op: zod.z.literal("sessions.interrupt"), sessionId, requestId }).strict(),
+  /*
+   * A session's code memory: the names the session's own cells have left in its
+   * eval namespace.
+   *
+   * Session-addressed, because the runtime is what holds a namespace and the
+   * kernel it lives in is keyed by session id. The legacy
+   * `/v1/agents/{id}/execution-variables` route answered through the agent
+   * registry instead, which resolves agent-directory UUIDs - so a canonical
+   * session id could only ever 404 there, and the panel that taught "code
+   * memory" never loaded once.
+   */
+  zod.z.object({ op: zod.z.literal("sessions.variables.list"), sessionId }).strict(),
+  zod.z.object({
+    op: zod.z.literal("sessions.variables.create"),
+    sessionId,
+    key: variableKey,
+    value: variableValue,
+    type: variableType
+  }).strict(),
+  zod.z.object({
+    op: zod.z.literal("sessions.variables.update"),
+    sessionId,
+    key: variableKey,
+    value: variableValue,
+    type: variableType
+  }).strict(),
+  zod.z.object({
+    op: zod.z.literal("sessions.variables.delete"),
+    sessionId,
+    key: variableKey
+  }).strict(),
+  // Machine-wide desktop presence. NOT a watch lease and deliberately not
+  // shaped like one: it names no session, because the fact it carries is
+  // "somebody is at this machine's screen and this app can raise a banner",
+  // which is a property of the app rather than of any conversation. The
+  // backend reads it to decide whether a BACKGROUND completion is worth a
+  // banner here at all (a session runtime with no surface to present on
+  // otherwise toasts on its own host, where nobody may be).
+  //
+  // `subscription_id` is the LIVE feed subscription the presence belongs to,
+  // not a per-session watch subscription: the server holds the lease against
+  // that socket, so a dropped feed revokes the claim without waiting for a
+  // heartbeat to go stale. That is the whole reason presence is a route on the
+  // feed rather than a local file - a desktop paired to a backend on another
+  // host cannot write to that host's disk.
+  zod.z.object({
+    op: zod.z.literal("sessions.presence"),
+    subscriptionId: zod.z.string().regex(/^[a-f0-9]{1,64}$/),
+    canNotify: zod.z.boolean(),
+    /*
+     * WHY THE CLAIM CARRIES MORE THAN "a desktop is connected".
+     *
+     * The backend's delivery lease answers two separate questions from
+     * this one beat, and a claim that names neither is a claim that
+     * delivers NOTHING:
+     *
+     * - `can_notify_kinds` is what `delivers(kind)` reads. Empty (the
+     *   default for a client that forgot) means rung 2 is never eligible
+     *   for any completion, so rung 4 raises the runtime's own banner —
+     *   earlier, and its claim advances the read watermark, so the
+     *   clickable banner this app exists to raise never composes.
+     *   The backend's own test for this is
+     *   `test_a_claim_with_no_kinds_claims_nothing`: an app that does not
+     *   advertise must not win the rung.
+     * - `window` (with `session_id`) is what `attended` reads. Without it
+     *   this app counts as watching NOTHING, so a completion in the
+     *   conversation on screen raises a banner — the inverse of rung 1,
+     *   and a regression against the per-session flag it replaces.
+     *
+     * `window` is sent even when there is no window: a windowless app
+     * (macOS, alive in the dock) can still raise a banner but cannot be
+     * displaying anything, which is why `session_id` must be "" there
+     * rather than the last conversation the closed window held.
+     */
+    canNotifyKinds: zod.z.array(zod.z.enum(["complete", "error"])).max(4),
+    sessionId: zod.z.string().regex(/^([a-f0-9]{12})?$/),
+    window: zod.z.object({
+      exists: zod.z.boolean(),
+      focused: zod.z.boolean(),
+      visible: zod.z.boolean(),
+      minimized: zod.z.boolean()
+    }).strict()
+  }).strict(),
+  // The legacy surface, reached through the same authenticated vocabulary as
+  // everything else. These routes are gated in managed mode (agent inventory,
+  // cwd paths, job history and conversation content are the same tenant's data
+  // as the control plane), so a bare renderer fetch would 401 against exactly
+  // the backend this app starts.
+  zod.z.object({
+    op: zod.z.literal("legacy.models"),
+    provider: zod.z.string().max(128).optional(),
+    // Mirrors ModelSortKey / ModelSortDirection in models-api.ts. Enumerated
+    // rather than free text so the renderer cannot smuggle a query fragment.
+    sort: zod.z.enum(["id", "name", "provider", "recommended"]).optional(),
+    direction: zod.z.enum(["ascending", "descending"]).optional()
+  }).strict(),
+  zod.z.object({ op: zod.z.literal("legacy.models.providers") }).strict(),
+  // Reachability is checked only when the user asks for it: a probe is a real
+  // network round trip, and nothing behind first paint may make one.
+  zod.z.object({ op: zod.z.literal("auth.probe"), provider: id }).strict(),
+  zod.z.object({ op: zod.z.literal("legacy.agent.upload"), agentId: id }).strict(),
+  /*
+   * Publication, beside the legacy zip upload it replaces for this surface.
+   *
+   * `legacy.agent.upload` stays exactly as it is — it is how an agent published
+   * under the old standard is still updated, and an older desktop build still
+   * pushes through it — but the app's own publish action moves onto the document
+   * ops below, which carry the instruction set instead of a zip of the agent
+   * directory.
+   */
+  zod.z.object({
+    op: zod.z.literal("agent.publish"),
+    agentId: id,
+    document: publicationDocument.optional(),
+    /*
+     * The publication TARGET (§4.4/§4.7). Both travel together or neither does,
+     * and the rule is a `superRefine` on the whole UNION (below) rather than a
+     * `.refine` here — a refined member becomes a `ZodEffects`, which cannot be a
+     * member of a discriminated union; measured, it does not compile.
+     *
+     * WHY THE COMMENT CHANGED (security review round 1, S-1). It used to say a
+     * half-specified target was "refused there rather than silently published to
+     * the public hub". The local server's route does refuse one, but
+     * `desktopEndpoint` dropped an unpaired half before the request was composed,
+     * so what reached the server was indistinguishable from a deliberate public
+     * publication: the documented guarantee held at neither boundary, and it
+     * failed OPEN on a privacy-relevant target. Measured at the previous head:
+     * each half parsed on its own and `desktopEndpoint({visibility: "org"})`
+     * composed a plain `/publish` with no query at all.
+     *
+     * Absent means the public hub, which is exactly what every caller did before
+     * this field existed — so the rule is "one half is an error", not "absent is
+     * an error".
+     */
+    visibility: zod.z.literal("org").optional(),
+    tenantId: id.optional()
+  }).strict(),
+  zod.z.object({
+    op: zod.z.literal("agent.republish"),
+    agentId: id,
+    // The HUB listing to update. Required rather than inferred: the local
+    // registry keeps no link to the listing a row was published as, so a
+    // republish that did not name one would have to guess which public row to
+    // overwrite — and guessing here overwrites somebody's listing.
+    hubAgentId: id,
+    document: publicationDocument.optional(),
+    /** The publication target, on the same terms as `agent.publish` above. */
+    visibility: zod.z.literal("org").optional(),
+    tenantId: id.optional()
+  }).strict(),
+  /*
+   * Pulling a published organization team into this machine's local registry
+   * (§4.5/§8.4's "list + pull action").
+   *
+   * The id is the HUB document's id, not a local row's: the pull addresses what
+   * was published, and the local copy gets its own fresh id (the local server's
+   * `GET /v1/teams/pull/{team_id}` reconstructs it, renaming on a local id
+   * clash through the registry's own convention). `tenantId` is OPTIONAL and is
+   * the caller's statement of which organization owns the document, not part of
+   * the address: §4.5's pull path is org-agnostic by id, the local server
+   * verifies the claim and refuses a document owned by another tenant, and the
+   * credential that reads it is the one the local server already holds.
+   */
+  zod.z.object({
+    op: zod.z.literal("team.pull"),
+    teamId: id,
+    /*
+     * The caller's statement of which organization owns the document. The local
+     * server verifies it and refuses a document owned by another tenant rather
+     * than storing it under the wrong expectation, so sending it is a stronger
+     * read where the caller knows the org — and omitting it is still legal
+     * (§4.5's pull path is org-agnostic by id).
+     */
+    tenantId: id.optional()
+  }).strict(),
+  zod.z.object({
+    op: zod.z.literal("agent.nameAvailability"),
+    // Deliberately looser than `publicationName`: this op asks whether a name
+    // is publishable, and a name that breaks the rules is a question the
+    // dialog does not ask (it shows the rule locally instead). The route is
+    // public, so the only thing this bound has to keep out is a query the
+    // backend can make no sense of.
+    name: zod.z.string().min(1).max(PUBLICATION_NAME_MAX_CHARS)
+  }).strict(),
+  zod.z.object({
+    op: zod.z.literal("legacy.agents.list"),
+    page: zod.z.number().int().min(1).optional(),
+    perPage: zod.z.number().int().min(1).max(500).optional(),
+    name: zod.z.string().max(256).optional(),
+    sort: zod.z.string().max(64).optional(),
+    direction: zod.z.enum(["asc", "desc"]).optional()
+  }).strict(),
+  zod.z.object({ op: zod.z.literal("legacy.agent.get"), agentId: id }).strict(),
+  zod.z.object({
+    op: zod.z.literal("legacy.agent.history"),
+    agentId: id,
+    page: zod.z.number().int().min(1).optional(),
+    perPage: zod.z.number().int().min(1).max(500).optional()
+  }).strict(),
+  zod.z.object({
+    op: zod.z.literal("legacy.jobs.list"),
+    agentId: id.optional(),
+    status: zod.z.string().max(64).optional()
+  }).strict(),
+  zod.z.object({ op: zod.z.literal("legacy.job.get"), jobId: id }).strict(),
+  // The schedules surface. Gated in managed mode not because a schedule is
+  // sensitive to READ but because both writes hand their `prompt` to the
+  // scheduler, which later runs it as the user's own agent -- so a bare
+  // renderer fetch would 401 against exactly the backend this app starts.
+  zod.z.object({
+    op: zod.z.literal("legacy.schedules.list"),
+    page: zod.z.number().int().min(1).optional(),
+    perPage: zod.z.number().int().min(1).max(100).optional()
+  }).strict(),
+  zod.z.object({
+    op: zod.z.literal("legacy.agent.schedules.list"),
+    agentId: id,
+    page: zod.z.number().int().min(1).optional(),
+    perPage: zod.z.number().int().min(1).max(100).optional()
+  }).strict(),
+  zod.z.object({
+    op: zod.z.literal("legacy.agent.schedule.create"),
+    agentId: id,
+    // Passed through as the request body. Declared field-by-field rather
+    // than as a passthrough object so the renderer cannot smuggle keys the
+    // backend model would silently accept.
+    schedule: scheduleWrite.extend({
+      prompt: zod.z.string().max(64e3),
+      interval: zod.z.number().int().min(1),
+      unit: scheduleUnit
+    })
+  }).strict(),
+  zod.z.object({ op: zod.z.literal("legacy.schedule.get"), scheduleId: id }).strict(),
+  zod.z.object({
+    op: zod.z.literal("legacy.schedule.edit"),
+    scheduleId: id,
+    // Every field optional: the backend applies `exclude_unset`, so sending
+    // a key the user did not touch would overwrite it with a default.
+    schedule: scheduleWrite.extend({
+      prompt: zod.z.string().max(64e3).nullish(),
+      interval: zod.z.number().int().min(1).nullish(),
+      unit: scheduleUnit.nullish()
+    })
+  }).strict(),
+  zod.z.object({ op: zod.z.literal("legacy.schedule.remove"), scheduleId: id }).strict(),
+  // The remaining gated legacy writes and reads the renderer still issued as
+  // bare same-origin `fetch`. `apiConfig.baseUrl` points AT THE BACKEND, not
+  // through the main-process relay, so in managed mode these went out with no
+  // bearer and 401'd -- agent creation among them, which is the app's most
+  // basic action (review round 3, Q7).
+  zod.z.object({
+    op: zod.z.literal("legacy.agent.create"),
+    // The body is forwarded whole: the backend model owns which fields
+    // exist, and enumerating ~20 optional agent fields here would be a
+    // second schema to keep in step with it. `strict()` on the wrapper
+    // still stops any key outside `agent` from riding along.
+    agent: zod.z.record(zod.z.unknown())
+  }).strict(),
+  zod.z.object({
+    op: zod.z.literal("legacy.agent.update"),
+    agentId: id,
+    update: zod.z.record(zod.z.unknown())
+  }).strict(),
+  zod.z.object({ op: zod.z.literal("legacy.agent.delete"), agentId: id }).strict(),
+  zod.z.object({ op: zod.z.literal("legacy.agent.conversation.clear"), agentId: id }).strict(),
+  zod.z.object({ op: zod.z.literal("legacy.agent.systemPrompt.get"), agentId: id }).strict(),
+  zod.z.object({
+    op: zod.z.literal("legacy.agent.systemPrompt.update"),
+    agentId: id,
+    systemPrompt: zod.z.string().max(DESKTOP_SYSTEM_PROMPT_MAX_CHARS)
+  }).strict(),
+  zod.z.object({ op: zod.z.literal("legacy.agent.download"), agentId: id }).strict(),
+  zod.z.object({ op: zod.z.literal("legacy.job.cancel"), jobId: id }).strict(),
+  zod.z.object({ op: zod.z.literal("commands.list") }).strict(),
+  zod.z.object({
+    op: zod.z.literal("commands.entities"),
+    sessionId,
+    command: id,
+    name: zod.z.string().max(128).optional()
+  }).strict(),
+  zod.z.object({
+    op: zod.z.literal("models.catalogue"),
+    live: zod.z.boolean().optional(),
+    /*
+     * Which view of the catalogue to answer with: `usable` (the rows this
+     * machine can run, plus the session's current model) or `all`. Absent
+     * means `all`, which is also what a backend that predates the
+     * parameter does with it — the picker stays correct either way, because
+     * a compile-time-correct request against an old backend is filtered
+     * client-side by `scopeCatalogue`.
+     */
+    scope: zod.z.enum(["usable", "all"]).optional()
+  }).strict(),
+  zod.z.object({
+    op: zod.z.literal("usage.get"),
+    provider: id.optional(),
+    live: zod.z.boolean().optional(),
+    refresh: zod.z.boolean().optional()
+  }).strict(),
+  zod.z.object({
+    op: zod.z.literal("analytics.get"),
+    sessionId: sessionId.optional(),
+    sinceMs: zod.z.number().int().nonnegative().optional(),
+    untilMs: zod.z.number().int().nonnegative().optional(),
+    days: zod.z.number().int().min(1).max(366).optional()
+  }).strict(),
+  /*
+   * The per-model rate table's own read, and a SEPARATE op on purpose.
+   *
+   * Its rows come from a grouped scan of the RAW LEDGER rather than from the
+   * rollup `analytics.get` reads, which is what makes it cover the operator's
+   * whole existing history rather than only the days since the rollup shipped
+   * — and is also what makes it cost seconds on a large ledger. Riding
+   * `analytics.get` would add that scan to every analytics panel load,
+   * including the ones that never scroll to the table, so it is fetched on its
+   * own and its wait is bounded and stated on its own section.
+   *
+   * Same arguments as `analytics.get`, same `.strict()` door, same window
+   * bounds: the two ops are windowed by the same `since_ms`/`until_ms`, which
+   * is the one property that lets a reader hold a row here against the
+   * headline Total above it.
+   */
+  zod.z.object({
+    op: zod.z.literal("analytics.models"),
+    sessionId: sessionId.optional(),
+    sinceMs: zod.z.number().int().nonnegative().optional(),
+    untilMs: zod.z.number().int().nonnegative().optional(),
+    days: zod.z.number().int().min(1).max(366).optional()
+  }).strict(),
+  /*
+   * The two diagnostics reads. They ride their own capability key
+   * (`diagnostics`) rather than the catalogue one, because `/analytics` and
+   * `/failovers` must keep working against a backend that lacks these routes.
+   */
+  zod.z.object({ op: zod.z.literal("info.get") }).strict(),
+  zod.z.object({
+    op: zod.z.literal("sessions.report"),
+    sessionId,
+    /*
+     * 0..50, matching the route's own clamp. The client always sends it:
+     * the number of rows the panel draws is a design decision made here, and
+     * inheriting the route's default would let the two drift apart.
+     */
+    recentLimit: zod.z.number().int().min(0).max(50).optional()
+  }).strict(),
+  zod.z.object({
+    op: zod.z.literal("skills.list"),
+    /*
+     * The sessionless arm's pair, both optional, `cwd` wins when both are sent
+     * (the explicit folder beats the implied one; the route's docstring owns
+     * the rule). `cwd` given → the folder's own discovery roots (identical to
+     * the session created there); `session_id` given → the session's cwd
+     * (compat, for the `/skills` panel and released clients); NEITHER → the
+     * daemon's home roots, explicitly — never the daemon's process cwd.
+     */
+    sessionId: sessionId.optional(),
+    cwd: skillCwd.optional(),
+    name: id.optional()
+  }).strict(),
+  zod.z.object({ op: zod.z.literal("sessions.failovers"), sessionId }).strict(),
+  zod.z.object({
+    op: zod.z.literal("sessions.credential"),
+    sessionId,
+    action: zod.z.enum(["list", "store", "forget"]),
+    key: settingKey.optional(),
+    value: secret.optional(),
+    confirmed: zod.z.boolean().optional()
+  }).strict(),
+  zod.z.object({
+    op: zod.z.literal("sessions.fork"),
+    sessionId,
+    requestId,
+    message: zod.z.string().max(2e5).optional(),
+    /*
+     * WHERE THE COPY STOPS. `next_safe` is the historical form and the default
+     * (the whole committed conversation, waiting for a turn boundary);
+     * `at_entry` cuts through `entryId` and needs no boundary, because a named
+     * point is already committed.
+     *
+     * `entryId` is bounded rather than patterned for the route's reason -
+     * entry ids are minted in more than one shape and existence in the
+     * CONVERSATION is what decides whether one is real (the route answers an
+     * unknown or foreign id with a refusal, never a fork of the wrong
+     * history) - so this client validates the shape it can and lets the
+     * backend adjudicate the rest.
+     *
+     * BOTH ARE OPTIONAL AND ABSENT IS THE OLD CALL, key for key: a typed
+     * `/fork` and the palette's fork send neither, and the body builder below
+     * omits `entry_id` entirely rather than sending it as null.
+     */
+    boundary: zod.z.enum(["next_safe", "at_entry"]).optional(),
+    entryId: zod.z.string().max(128).optional()
+  }).strict(),
+  zod.z.object({
+    op: zod.z.literal("sessions.stop"),
+    requestId,
+    targets: zod.z.array(sessionId).min(1).max(100),
+    confirmed: zod.z.literal(true)
+  }).strict(),
+  zod.z.object({
+    op: zod.z.literal("sessions.aside"),
+    sessionId,
+    requestId,
+    text: zod.z.string().min(1).max(32768),
+    asideId: requestId.optional(),
+    /*
+     * THE SUBSCRIPTION THAT WANTS THE ANSWER'S CHUNKS, named by the viewer
+     * that is asking.
+     *
+     * `aside_delta` is published on the session's stream, and the stream is
+     * read by every attached viewer of a session - so the owner has to be
+     * told WHICH of them asked, or an off-record answer is broadcast to
+     * windows that never asked the question. The same id the `open` frame
+     * hands the renderer (`payload.subscription_id`), which is also what
+     * `sessions.watch` leases it with, so the two cannot disagree about
+     * which subscription a viewer is.
+     *
+     * OPTIONAL, and that is the backward-compatibility half: an owner that
+     * predates the routing sends no `aside_delta` at all, and a viewer that
+     * has no subscription yet (the stream has not opened) still gets the
+     * settled answer from the POST's response.
+     */
+    subscriptionId: zod.z.string().regex(SUBSCRIPTION_ID_PATTERN).optional()
+  }).strict(),
+  zod.z.object({
+    op: zod.z.literal("sessions.adopt"),
+    sessionId,
+    requestId,
+    asideId: requestId,
+    confirmed: zod.z.literal(true)
+  }).strict(),
+  zod.z.object({
+    op: zod.z.literal("sessions.aside.get"),
+    sessionId,
+    asideId: requestId
+  }).strict(),
+  zod.z.object({
+    op: zod.z.literal("sessions.aside.close"),
+    sessionId,
+    asideId: requestId
+  }).strict(),
+  /*
+   * The wake surface: the Schedules page's machine-wide read and its writes.
+   *
+   * Deliberately NOT an extension of `sessions.*`. The session list is
+   * paginated by recency (`limit ≤ 500`), so a session armed once and never
+   * opened falls off it - and the page whose whole job is "every session that
+   * has wakes" would then list fewer sessions than exist. `wakes.list` reads
+   * the wake index instead, which is one small JSON file per wake-carrying
+   * session and is complete at any store size.
+   *
+   * The four ops sit behind the same router-level desktop bearer as their
+   * `sessions.*` siblings, and every one of them does its filesystem work off
+   * the event loop, so a listing over a cold store cannot stall the desktop
+   * plane's other readers.
+   */
+  zod.z.object({
+    op: zod.z.literal("wakes.list"),
+    /* Bounded like `sessions.list`: the field exists so a pathological
+       store degrades visibly (through `truncated`) rather than silently. */
+    limit: zod.z.number().int().min(1).max(500).optional(),
+    /* Dormant rows are the ones whose session was stopped, which the page
+       SHOWS ("parked") rather than hides: stopping a conversation parks its
+       wakes, and a management surface that dropped them would report a
+       scheduled task as gone when it is only parked. */
+    includeDormant: zod.z.boolean().optional()
+  }).strict(),
+  zod.z.object({
+    op: zod.z.literal("wakes.create"),
+    requestId,
+    /*
+     * The session half of the request is EXACTLY ONE of two shapes: name an
+     * existing `sessionId`, or name a `cwd` (plus an optional `target`) and
+     * have the backend create the conversation and arm the wake in one
+     * call. The exclusivity cannot be stated with a `.refine()` on this
+     * object - that turns the member into a `ZodEffects`, which a
+     * discriminated union cannot take (see `mcp.credentials.store`, which
+     * records the same trap) - so the API client enforces it on the way out
+     * with `wakeCreateBody`, and the backend refuses the malformed shape
+     * with a 422 rather than a 500.
+     */
+    sessionId: sessionId.optional(),
+    cwd: zod.z.string().min(1).max(4096).optional(),
+    target: target.optional(),
+    message: wakeMessage,
+    /*
+     * Timing, in the same spellings the wake tool and `lop wake create`
+     * take, parsed by the backend's own `parse_wake_duration` /
+     * `parse_wake_at`: a relative duration (`30m`), an ISO instant or the
+     * next `HH:MM`. The dialog's presets are `in`/`at` pairs so the common
+     * path never touches a calendar, and `Pick a time…` sends the ISO
+     * instant the picker yields.
+     */
+    in: zod.z.string().min(1).max(64).optional(),
+    at: zod.z.string().min(1).max(64).optional(),
+    every: zod.z.string().min(1).max(64).optional(),
+    until: zod.z.string().min(1).max(64).optional(),
+    limit: zod.z.number().int().min(1).optional(),
+    /*
+     * The conversation's own title, when a caller wants to override the one
+     * derived from the prompt.
+     *
+     * Carried because the interface declares it, and never set by this
+     * page: the prompt IS the name here (the backend writes it into the
+     * session's stored-title sidecar, which `resume.session_name` consults
+     * first), which is what keeps the create flow free of a "name" field
+     * nobody would fill in.
+     */
+    title: zod.z.string().min(1).max(200).optional()
+  }).strict(),
+  zod.z.object({
+    op: zod.z.literal("wakes.edit"),
+    sessionId,
+    wakeId,
+    /* Every field optional, and the body is sent with the absent ones
+       OMITTED rather than nulled: the backend applies the update against
+       the schedule it holds, so a `null` here would be a request to clear
+       a bound the user did not touch. */
+    message: wakeMessage.optional(),
+    in: zod.z.string().min(1).max(64).optional(),
+    at: zod.z.string().min(1).max(64).optional(),
+    every: zod.z.string().min(1).max(64).optional(),
+    until: zod.z.string().min(1).max(64).optional(),
+    limit: zod.z.number().int().min(1).optional()
+  }).strict(),
+  zod.z.object({ op: zod.z.literal("wakes.remove"), sessionId, wakeId }).strict(),
+  /*
+   * The monitor surface's one write that has a UI: cancelling a standing watch
+   * (`DELETE /v1/desktop/monitors/{session_id}/{monitor_id}`). The sibling
+   * routes - the machine-wide listing and the arm - are deliberately not
+   * mirrored yet: the pane and the composer's chip read the SESSION's own
+   * `frontend.monitors` field (the design's §12 row states the desktop contract
+   * as "the `monitors` field + command routes"), so a listing op would have no
+   * reader, and the arm op waits for the form that will use it.
+   */
+  zod.z.object({
+    op: zod.z.literal("monitors.cancel"),
+    sessionId,
+    monitorId
+  }).strict(),
+  zod.z.object({ op: zod.z.literal("mcp.list"), sessionId }).strict(),
+  zod.z.object({
+    op: zod.z.literal("mcp.credentials.store"),
+    sessionId,
+    name: zod.z.string().min(1).max(256),
+    values: zod.z.record(zod.z.string().min(1).max(128), zod.z.string().min(1).max(32768)).refine(
+      (secrets) => Object.keys(secrets).length <= 32 && Object.values(secrets).reduce(
+        (total, value) => total + value.length,
+        0
+      ) <= 65536,
+      // Mirrors the owner's own bound (`local_operator/mcp/credentials.py`),
+      // so an oversized paste is refused as a sentence rather than
+      // serialized into a request the control budget rejects as an
+      // opaque 413.
+      {
+        message: "Too many secret values, or too much secret text, for one MCP credential write."
+      }
+    ),
+    confirmedReplace: zod.z.array(zod.z.string().min(1).max(128)).max(32)
+  }).strict(),
+  zod.z.object({
+    op: zod.z.literal("mcp.control"),
+    sessionId,
+    control: zod.z.object({
+      action: zod.z.enum([
+        "list",
+        "add",
+        "remove",
+        "reload",
+        "connect",
+        "probe",
+        "disconnect",
+        "login",
+        "logout",
+        "reauth",
+        "status",
+        "cancel"
+      ]),
+      name: mcpServerName.optional(),
+      scope: zod.z.enum(["global", "project"]).optional(),
+      command: zod.z.string().min(1).max(4096).optional(),
+      args: zod.z.array(zod.z.string().max(8192)).max(128).optional(),
+      env: zod.z.record(mcpSecretReference).optional(),
+      url: zod.z.string().max(4096).optional(),
+      headers: zod.z.record(mcpSecretReference).optional(),
+      oauth: zod.z.boolean().optional(),
+      confirmed: zod.z.boolean().optional(),
+      operation_id: mcpOperationId.optional()
+    }).strict()
+  }).strict(),
+  /*
+   * The SESSIONLESS MCP catalog (`GET|POST /v1/desktop/mcp`), gated on the
+   * `mcp_catalog` capability. Settings > Integrations reads and writes MCP
+   * CONFIGURATION through these, so it no longer needs a running conversation -
+   * the session route above booted a whole runtime (and so needed a model
+   * provider) just to write a JSON file (UX walk U5). The session ops stay: the
+   * run panel is a live per-runtime view, and `connect`/`disconnect`/`reload`
+   * are about a runtime's live connection, so they are not accepted here.
+   *
+   * `cwd` is optional (the backend defaults it to the user's home, the desktop's
+   * own default) and must be absolute: the backend 422s anything else, and the
+   * schema refuses it first so a relative path never reaches the wire.
+   */
+  zod.z.object({
+    op: zod.z.literal("mcp.catalog"),
+    cwd: mcpCatalogCwd.optional(),
+    sessionId: sessionId.optional()
+  }).strict(),
+  zod.z.object({
+    op: zod.z.literal("mcp.catalog.control"),
+    cwd: mcpCatalogCwd.optional(),
+    control: zod.z.object({
+      action: zod.z.enum([
+        "add",
+        "remove",
+        "test",
+        "login",
+        "reauth",
+        "logout",
+        "status",
+        "cancel"
+      ]),
+      name: mcpServerName.optional(),
+      scope: zod.z.enum(["global", "project"]).optional(),
+      command: zod.z.string().min(1).max(4096).optional(),
+      args: zod.z.array(zod.z.string().max(8192)).max(128).optional(),
+      env: zod.z.record(mcpSecretReference).optional(),
+      url: zod.z.string().max(4096).optional(),
+      headers: zod.z.record(mcpSecretReference).optional(),
+      confirmed: zod.z.boolean().optional(),
+      operation_id: mcpOperationId.optional()
+    }).strict()
+  }).strict(),
+  zod.z.object({
+    op: zod.z.literal("mcp.catalog.credentials"),
+    /*
+     * WHICH HEADER OR ENV NAME THE KEY BELONGS TO (backend #1511
+     * `aa927158a`). A server with no `${ID}` reference has nothing for the
+     * catalog's own `set_key` to fill, so the credential write names the
+     * header itself and the backend adds `headers[header] = "${ID}"` to the
+     * defining file. Refused (`invalid_target`) for a header the transport
+     * owns, one already set, a malformed name, or an invalid id - and
+     * refused with NOTHING written.
+     */
+    header: zod.z.string().min(1).max(128).optional(),
+    cwd: mcpCatalogCwd.optional(),
+    name: mcpServerName,
+    values: zod.z.record(zod.z.string().min(1).max(128), zod.z.string().min(1).max(32768)).refine(
+      (secrets) => Object.keys(secrets).length <= 32 && Object.values(secrets).reduce(
+        (total, value) => total + value.length,
+        0
+      ) <= 65536,
+      {
+        message: "Too many secret values, or too much secret text, for one MCP credential write."
+      }
+    ),
+    confirmedReplace: zod.z.array(zod.z.string().min(1).max(128)).max(32)
+  }).strict(),
+  zod.z.object({
+    op: zod.z.literal("radient.request"),
+    control: zod.z.object({
+      operation: zod.z.enum([
+        "account",
+        "prices",
+        "credits",
+        "usage",
+        "provision",
+        "application.create",
+        "agents.list",
+        "agents.get",
+        "agents.create",
+        "agents.update",
+        "agents.delete",
+        "agents.like",
+        "agents.unlike",
+        "agents.liked",
+        "agents.like_count",
+        "agents.favourite",
+        "agents.unfavourite",
+        "agents.favourited",
+        "agents.favourite_count",
+        "agents.download_count",
+        /*
+         * The viewer's own like/favourite state for a whole page of agents. The
+         * closed vocabulary has to name it here as well as in
+         * `shared/api/radient/proxy.ts`, because this schema is what validates
+         * the request the renderer actually sends.
+         */
+        "agents.statuses",
+        "comments.list",
+        "comments.create",
+        "comments.update",
+        "comments.delete",
+        "account.agents",
+        /*
+         * The organization operations (design §4.7). They are named here as well as
+         * in `shared/api/radient/proxy.ts` because this schema is what validates the
+         * request the renderer actually sends: an op in one list and not the other
+         * is a request that never leaves the renderer. `team_id` is the published
+         * team document an `org_team.get` pull names.
+         */
+        "memberships.list",
+        "org_agents.list",
+        "org_team.get",
+        "org_teams.list"
+      ]),
+      request_id: requestId.optional(),
+      tenant_id: id.optional(),
+      account_id: id.optional(),
+      agent_id: id.optional(),
+      comment_id: id.optional(),
+      team_id: id.optional(),
+      query: zod.z.record(zod.z.union([zod.z.string().max(1024), zod.z.number().int()])).optional(),
+      payload: zod.z.record(zod.z.unknown()).optional(),
+      confirmed: zod.z.boolean().optional()
+    }).strict()
+  }).strict(),
+  zod.z.object({ op: zod.z.literal("providers.list") }).strict(),
+  zod.z.object({ op: zod.z.literal("accounts.list") }).strict(),
+  zod.z.object({
+    op: zod.z.literal("accounts.remove"),
+    accountId: zod.z.number().int().positive(),
+    confirmed: zod.z.literal(true)
+  }).strict(),
+  zod.z.object({ op: zod.z.literal("auth.start"), provider: id }).strict(),
+  zod.z.object({ op: zod.z.literal("auth.status"), id }).strict(),
+  zod.z.object({ op: zod.z.literal("auth.input"), id, promptId: id, value: secret }).strict(),
+  zod.z.object({ op: zod.z.literal("auth.cancel"), id }).strict(),
+  zod.z.object({ op: zod.z.literal("auth.key"), provider: id, value: secret }).strict(),
+  zod.z.object({ op: zod.z.literal("auth.logout"), provider: id }).strict(),
+  zod.z.object({ op: zod.z.literal("settings.list") }).strict(),
+  zod.z.object({
+    op: zod.z.literal("settings.edit"),
+    key: settingKey,
+    value: zod.z.unknown().refine((value) => value !== void 0, "A setting value is required."),
+    base: chains.optional()
+  }).strict(),
+  zod.z.object({ op: zod.z.literal("settings.reset"), key: settingKey }).strict(),
+  /*
+   * THE VOICING SURFACE's read (`features.tts`), and the twin of the STT
+   * cascade report: every rung in order with its availability and the reason a
+   * reader would be shown, plus the surface's own `servable` bit. It is a GET
+   * with no parameters - the daemon resolves the cascade against THIS
+   * machine's stored credentials - so a client cannot scope it to anything and
+   * has nothing to send.
+   *
+   * Gated on its own capability key rather than on `settings`: the two are
+   * different contracts on different release trains (a backend can serve the
+   * registry and predate voicing), and a surface that fired this read at such a
+   * backend would render a 404 as a failure of the user's own account.
+   */
+  zod.z.object({ op: zod.z.literal("tts.paths") }).strict(),
+  zod.z.object({ op: zod.z.literal("config.get") }).strict(),
+  zod.z.object({ op: zod.z.literal("config.update"), value: configUpdate }).strict(),
+  zod.z.object({ op: zod.z.literal("instructions.get") }).strict(),
+  zod.z.object({
+    op: zod.z.literal("instructions.update"),
+    content: zod.z.string().max(64e3)
+  }).strict(),
+  zod.z.object({ op: zod.z.literal("credentials.list") }).strict(),
+  zod.z.object({
+    op: zod.z.literal("credentials.update"),
+    key: settingKey,
+    value: secret
+  }).strict(),
+  /*
+   * THE MESH READS (`features.peers`).
+   *
+   * Both reach a peer only THROUGH this app's one backend: the renderer never dials
+   * a peer, never learns an address to dial and holds no mesh credential, because a
+   * UI that could would have to re-implement the relay's authorisation model in
+   * JavaScript.
+   *
+   * THE MUTATING MESH OPS LANDED WITH THE SURFACES THAT USE THEM (slice 2: the drag
+   * layer, the invite action, the member list), which is the rule this block stated
+   * while they were still absent: a request schema entry with no caller is a
+   * capability this app advertises but cannot exercise.
+   *
+   * `features.session_transfer` gates the TRANSFER and only it (`capabilities.py`):
+   * a backend can host a network, mint invites and remove members without being able
+   * to move a conversation, and the surfaces that gate on the wrong key draw a
+   * control that 404s. The three ops below therefore sit behind different keys —
+   * `networks.invite`/`networks.member.remove` behind `features.peers` (they are
+   * routes the mesh itself introduced), `sessions.transfer` behind
+   * `features.session_transfer`.
+   *
+   * WHAT TRAVELS, AND WHAT DOES NOT. `to` is the destination device id or the
+   * literal `"local"` (a RECALL), because that is the route's own shape: one route,
+   * two protocols, and the direction is decided by which of the two ends is asking
+   * — see `guide://network`. `request_id` is minted by the CALLER and is what makes
+   * a retry replay a recorded outcome instead of starting a second move for a
+   * request that may still be running, so it is sent on every drop rather than kept
+   * for a retry path this surface does not have.
+   */
+  zod.z.object({ op: zod.z.literal("peers.list") }).strict(),
+  zod.z.object({ op: zod.z.literal("networks.list") }).strict(),
+  /*
+   * Mint an invite. `role` is the joined device's own role in the network and
+   * `device` BINDS the token to one device id, so a token intercepted on its way to
+   * another machine cannot be redeemed by a third one. The token itself NEVER
+   * crosses this API (the receipt carries a path, and it is written where the
+   * renderer cannot read it) — which is why the answer is a receipt and not a
+   * secret.
+   */
+  zod.z.object({
+    op: zod.z.literal("networks.invite"),
+    networkId: meshId,
+    role: zod.z.enum(["read", "drive", "admin"]),
+    deviceId: meshId.optional()
+  }).strict(),
+  /*
+   * Revoke a membership. `confirm` is the NETWORK'S NAME, typed by the user, and
+   * the route compares it exactly: this is the one mesh act that changes other
+   * devices' state (every peer is rekeyed and the removed device is locked out on
+   * its next handshake), so the request must carry what the user was shown rather
+   * than a bool a stray retry could also send.
+   */
+  zod.z.object({
+    op: zod.z.literal("networks.member.remove"),
+    networkId: meshId,
+    deviceId: meshId,
+    confirm: zod.z.string().min(1).max(256)
+  }).strict(),
+  /*
+   * Ask a device to take a conversation, or ask THIS device to take one back.
+   *
+   * THE DIRECTION IS THE PROTOCOL'S, not a UI preference: there is no push verb, so
+   * a drop on a peer is this device asking that peer to PULL (`to: <device_id>`),
+   * and a drop on this device is a recall (`to: "local"`). `keep` is the reversible
+   * half — it mints a new id at the destination and leaves the source running —
+   * while a move deletes the source's copy once the handoff commits, which is why
+   * `source_retired = (mode == "move")` on the receipt.
+   *
+   * `wait_s` is a CEILING ON WAITING INSIDE THE REQUEST, not a promise: the route
+   * returns as soon as it has a definite outcome, and a `busy` source refuses
+   * rather than being interrupted. The desktop's own deadline for this op is
+   * derived from the route's published bound rather than from the 20 s control
+   * budget (see `moveClientBoundMs`) — the defect this avoids is a client that gives
+   * up first and reports its own timeout for a move the backend was about to answer.
+   */
+  zod.z.object({
+    op: zod.z.literal("sessions.transfer"),
+    sessionId,
+    to: zod.z.union([zod.z.literal("local"), meshId]),
+    keep: zod.z.boolean().optional(),
+    waitS: zod.z.number().min(0).max(300).optional(),
+    requestId: requestId.optional()
+  }).strict(),
+  /*
+   * THE ONBOARDING APPROVALS (`features.approvals`), the third mesh-adjacent
+   * family: one durable, signed record per remote-onboarding request, kept
+   * DEVICE-LOCALLY under `<config>/network/approvals/` (remote-onboarding
+   * design §2.3 — the badge must answer on a machine whose relay is down, which
+   * is why the record is a flat file rather than something behind the relay).
+   *
+   * THE LIST IS THE BADGE READ and it dials nothing: every row comes off this
+   * machine's own directory, so a rail-mounted interval costs one local scan
+   * rather than a peer fan-out — the reason it is the ONE mesh-family read a
+   * sidebar badge may poll (see `mesh-approvals.ts` for the cadence argument).
+   * Each row is the frozen §3.5 shape — `what` (the scope block), the
+   * where-block (`device` for `device_onboard`, `machine` for `local_authority`;
+   * the KIND is which key is present), `requested_by` and the expiry — and the
+   * surfaces do their own wording, so the wire stays the record's own
+   * vocabulary and a new scope does not need a wire change.
+   *
+   * THE DECISIONS TAKE NO BODY, deliberately (`routes/desktop_approvals.py`:
+   * "the two decision routes take NO body at all — approving is the gesture").
+   * `approve` runs the SAME presence-gated signing call the CLI's `approve`
+   * verb runs, so its latency includes a human's — see
+   * `APPROVAL_APPROVE_DEADLINE_MS` for why this op alone carries its own
+   * budget. `deny` never signs: it is write-once and settles in the safe
+   * direction.
+   */
+  zod.z.object({ op: zod.z.literal("approvals.list") }).strict(),
+  zod.z.object({ op: zod.z.literal("approvals.approve"), approvalId }).strict(),
+  zod.z.object({ op: zod.z.literal("approvals.deny"), approvalId }).strict(),
+  /*
+   * THE FLEET ASKS READ (`GET /v1/desktop/asks`), the cross-session companion of
+   * the per-session queue the canonical frame carries. A GET with no parameters
+   * at all: the route answers from the DERIVED ask index under the config dir,
+   * so it needs no session id and no `cwd` — the rows name their own conversation
+   * (`session_id`, `cwd` are the frozen `PendingAsk` shape plus those two keys).
+   *
+   * IT IS A SEPARATE OP FROM THE SESSION QUEUE, deliberately. The session's asks
+   * arrive on its own canonical stream (the frontend state's `asks`), which is
+   * scoped to the conversation being watched and is therefore silent about every
+   * other conversation by construction; "what is waiting across the whole app" is
+   * a question no per-session frame can answer, which is why the drawer's other
+   * scope needs its own read rather than a widened filter on that one.
+   *
+   * THE ANSWER IS A LIST OF RAW ROWS rather than a modelled shape, matching the
+   * route's own reasoning: the rows ARE the frozen `PendingAsk` wire shape, and
+   * re-declaring their fields here would be a third copy of §4 to keep in step.
+   */
+  zod.z.object({ op: zod.z.literal("asks.list") }).strict(),
+  /*
+   * The Projects surface (`/v1/desktop/projects*`), APPENDED to the union
+   * rather than inserted beside the other catalogue ops: the backend serves
+   * these routes from its own release, and an older daemon that has never
+   * heard of the op is a backend this app must be able to gate against —
+   * which it does through the `projects` capability key, not through this
+   * schema (a request this client refuses to build is not a negotiation).
+   *
+   * One op per route; the wipe and the milestone routes are the two shapes
+   * that do not fit the plain CRUD, and both exist because the backend
+   * declared them separately (a milestone is add-or-update-by-name, and a
+   * removal is a DELETE with the name in the path). `projects.update` carries
+   * its editable fields as a NESTED `fields` object for the same reason the
+   * profile ops do: the fields differ per surface, and a flat op would put
+   * every future field at the top level of a union member.
+   */
+  zod.z.object({ op: zod.z.literal("projects.list") }).strict(),
+  zod.z.object({ op: zod.z.literal("projects.get"), key: projectKey }).strict(),
+  zod.z.object({
+    op: zod.z.literal("projects.create"),
+    name: projectName,
+    description: zod.z.string().max(PROJECT_DESCRIPTION_MAX_CHARS).optional(),
+    status: projectStatus.optional(),
+    tags: projectTags.optional()
+  }).strict(),
+  zod.z.object({
+    op: zod.z.literal("projects.update"),
+    key: projectKey,
+    /*
+     * Only the keys the caller includes travel; an omitted key leaves the
+     * field alone, and `""` clears a date, the progress snippet or an
+     * attribution (the route forwards `model_fields_set`, and this client
+     * mirrors it). The three attribution/title steps are bounded at 80 —
+     * the store's `ATTRIBUTION_MAX`/`TITLE_MAX` — so a client cannot build
+     * a body the route would refuse for length alone.
+     */
+    fields: zod.z.object({
+      name: projectName.optional(),
+      title: zod.z.string().max(80).optional(),
+      owner: zod.z.string().max(80).optional(),
+      team: zod.z.string().max(80).optional(),
+      description: zod.z.string().max(PROJECT_DESCRIPTION_MAX_CHARS).optional(),
+      status: projectStatus.optional(),
+      progress: zod.z.string().max(PROJECT_PROGRESS_MAX_CHARS).optional(),
+      tags: projectTags.optional(),
+      start_date: projectDate.optional(),
+      target_date: projectDate.optional(),
+      completed_at: projectDate.optional(),
+      estimate: zod.z.number().positive().max(1e3).optional(),
+      estimate_unit: zod.z.enum(["points", "days"]).optional()
+    }).strict(),
+    /*
+     * `force_done` is a flag about THIS CALL, not a field of the row, so it
+     * sits at the op's top level and never inside `fields` (the strict
+     * `fields` object above rejects it there). It is the daemon's deliberate
+     * escape from the done-gate: close the project with milestones still
+     * open. Sent ONLY when true (see the mapper) because a daemon that
+     * predates the `projects_force_done` capability 422s an unknown body key
+     * - the renderer gates the offer on that key, and an absent flag keeps
+     * every other PATCH byte-identical to what shipped before.
+     */
+    force_done: zod.z.boolean().optional()
+  }).strict(),
+  zod.z.object({
+    op: zod.z.literal("projects.delete"),
+    key: projectKey,
+    confirmed_name: projectName
+  }).strict(),
+  zod.z.object({
+    op: zod.z.literal("projects.link"),
+    key: projectKey,
+    sessionId
+  }).strict(),
+  zod.z.object({
+    op: zod.z.literal("projects.unlink"),
+    key: projectKey,
+    sessionId
+  }).strict(),
+  zod.z.object({
+    op: zod.z.literal("projects.milestone"),
+    key: projectKey,
+    name: zod.z.string().min(1).max(PROJECT_MILESTONE_NAME_MAX_CHARS),
+    /** `""` clears it; omitted leaves it alone. */
+    targetDate: projectDate.optional(),
+    /** `true` stamps today, `false` clears; omitted leaves it alone. */
+    completed: zod.z.boolean().optional()
+  }).strict(),
+  zod.z.object({
+    op: zod.z.literal("projects.milestone.remove"),
+    key: projectKey,
+    name: zod.z.string().min(1).max(PROJECT_MILESTONE_NAME_MAX_CHARS)
+  }).strict(),
+  /*
+   * The check-in fan-out (`POST /v1/desktop/projects/{project}/request-update`):
+   * ask every linked session to post a progress update. APPENDED to the union
+   * like its siblings, and gated by its OWN capability key
+   * (`features.projects_request_update`) rather than a bump of `projects`: the
+   * tab renders perfectly well against a backend that cannot ask its sessions
+   * for anything, so the version would hide a working surface behind an update
+   * it does not need (the `session_search` rule above). The key is the row's
+   * address (id or name) - the same shape every other projects op takes.
+   */
+  zod.z.object({
+    op: zod.z.literal("projects.request_update"),
+    key: projectKey
+  }).strict(),
+  /*
+   * THE DERIVED SEARCH INDEX (`GET /v1/desktop/projects/search`). APPENDED like
+   * its siblings, and gated by a `projects` VERSION BUMP (1 -> 2) rather than a
+   * key of its own: the route ranks over the same store the listing reads and is
+   * additive by construction — every version-1 call keeps its exact behaviour —
+   * so the version is what lets a client ask for the new read without a second
+   * negotiation. The backend's own register states the same split
+   * (`routes/capabilities.py`: "a client gates ONLY the two new calls on
+   * ``>= 2``").
+   *
+   * `.min(1)`: an EMPTY query is not a search. The route answers one with the
+   * listing's own order truncated to `limit`, but this surface already holds
+   * that list — its box is a filter over the catalogue — so an empty `q` would
+   * ask the server to send back everything the client is holding, which is the
+   * refusal `sessions.search` above states in the same words.
+   */
+  zod.z.object({
+    op: zod.z.literal("projects.search"),
+    q: zod.z.string().min(1).max(PROJECTS_SEARCH_MAX_CHARS),
+    limit: zod.z.number().int().min(1).max(PROJECTS_SEARCH_MAX_LIMIT).optional()
+  }).strict(),
+  /*
+   * AIDA'S CONTROL PLANE: one read and one control op on the same route
+   * (`/v1/desktop/aida`), because the rail's row and the composer's `/aida`
+   * need the SAME state and a second spelling of it would be a second answer
+   * about her one long session (`design.md` § 4 freezes the route).
+   *
+   * The feature is gated by its OWN capability key (`features.aida`), never a
+   * bump of `commands`: a renderer that does not read it keeps working against
+   * this backend, and this renderer must not call the route while the key is
+   * absent or 0 (§ 3.4's version skew).
+   *
+   * Deliberately NOT a `MESSAGE_OPS` member (see `desktopRequestByteBudget`):
+   * an enum word and a receipt are not prose, so this costs the control budget.
+   */
+  zod.z.object({ op: zod.z.literal("aida.status") }).strict(),
+  zod.z.object({
+    op: zod.z.literal("aida.control"),
+    /*
+     * The route's own op vocabulary, held to it here: a word the backend does
+     * not serve must fail at this boundary rather than travel as a 422 the
+     * user reads as a defect of their press.
+     */
+    action: zod.z.enum(["open", "pause", "resume", "greet", "status"])
+  }).strict()
+]);
+desktopRequestUnion.superRefine(
+  (request, ctx) => {
+    if (request.op === "sessions.answer") {
+      if (request.askId !== void 0) {
+        if (!request.askId)
+          ctx.addIssue({
+            code: zod.z.ZodIssueCode.custom,
+            message: "ask_id must be a non-empty string",
+            path: ["askId"]
+          });
+        if (request.decline !== true && !request.answers)
+          ctx.addIssue({
+            code: zod.z.ZodIssueCode.custom,
+            message: "A queued-ask answer needs answers or decline",
+            path: ["answers"]
+          });
+        else if (request.decline === true && request.answers !== void 0)
+          ctx.addIssue({
+            code: zod.z.ZodIssueCode.custom,
+            message: "Supply either answers or decline",
+            path: ["decline"]
+          });
+        else if (request.revise === true && request.decline === true)
+          ctx.addIssue({
+            code: zod.z.ZodIssueCode.custom,
+            message: "Supply either decline or revise",
+            path: ["revise"]
+          });
+        else if (request.answers !== void 0 && Object.keys(request.answers).length === 0)
+          ctx.addIssue({
+            code: zod.z.ZodIssueCode.custom,
+            message: "answers must name at least one question",
+            path: ["answers"]
+          });
+        return;
+      }
+      if (!request.epoch)
+        ctx.addIssue({
+          code: zod.z.ZodIssueCode.custom,
+          message: "An epoch is required to answer a gate",
+          path: ["epoch"]
+        });
+      if (!request.requestId)
+        ctx.addIssue({
+          code: zod.z.ZodIssueCode.custom,
+          message: "A request id is required to answer a gate",
+          path: ["requestId"]
+        });
+      if (request.revise === true)
+        ctx.addIssue({
+          code: zod.z.ZodIssueCode.custom,
+          message: "revise applies to a queued ask",
+          path: ["revise"]
+        });
+      return;
+    }
+    if (request.op === "sessions.create" && request.purpose === void 0) {
+      if (request.cwd === void 0) {
+        ctx.addIssue({
+          code: zod.z.ZodIssueCode.custom,
+          message: "A conversation needs a working directory: only a configuration run (`purpose`) may omit `cwd`.",
+          path: ["cwd"]
+        });
+      }
+      return;
+    }
+    if (request.op === "sessions.create" && request.purpose !== void 0) {
+      for (const field of ["cwd", "target", "model", "draftId"]) {
+        if (request[field] === void 0) continue;
+        ctx.addIssue({
+          code: zod.z.ZodIssueCode.custom,
+          message: `A configuration run resolves its own \`${field}\`: send \`purpose\` alone.`,
+          path: [field]
+        });
+      }
+      return;
+    }
+    if (request.op !== "agent.publish" && request.op !== "agent.republish") {
+      return;
+    }
+    if (Boolean(request.visibility === "org") !== Boolean(request.tenantId)) {
+      ctx.addIssue({
+        code: zod.z.ZodIssueCode.custom,
+        message: 'A publication target needs both `visibility: "org"` and `tenantId`, or neither: one half would publish to the public hub.'
+      });
+    }
+  }
+);
+const LEDGER_READ_OPS = /* @__PURE__ */ new Set([
+  "analytics.get",
+  /*
+   * The worst case of the same shape, and the reason the set is spelled by
+   * shape rather than by measured cost: `/analytics/models` is a grouped scan
+   * of the raw ledger with no covering index, measured in SECONDS on a 1.95 M
+   * row ledger where `analytics.get` measures 12-40 s cold. On the control
+   * budget it would be abandoned mid-read on nearly every open, so it is here
+   * beside the op it is a slower sibling of.
+   */
+  "analytics.models",
+  "sessions.report"
+]);
+const PROVIDER_READ_OPS = /* @__PURE__ */ new Set(["usage.get"]);
+const MESH_READ_OPS = /* @__PURE__ */ new Set([
+  "networks.list",
+  "peers.list"
+]);
+/* @__PURE__ */ new Set([
+  ...LEDGER_READ_OPS,
+  ...PROVIDER_READ_OPS,
+  ...MESH_READ_OPS
+]);
+const EXTERNAL_OPEN_REFUSED_CHANNEL = "external-open-refused";
 const DESKTOP_STREAM_DETAIL = {
   /** The IPC subscribe itself rejected before a stream existed. */
   openFailed: "The event stream could not be opened."
@@ -139,8 +2199,8 @@ function readOpenSessionArgv(argv) {
   return found !== null && SESSION_ID.test(found) ? found : null;
 }
 function readLaunchTarget(argv) {
-  const sessionId = readOpenSessionArgv(argv);
-  if (sessionId) return { kind: "session", sessionId };
+  const sessionId2 = readOpenSessionArgv(argv);
+  if (sessionId2) return { kind: "session", sessionId: sessionId2 };
   if (argv.includes(OPEN_CATALOGUE_FLAG)) return { kind: "catalogue" };
   return { kind: "restore" };
 }
@@ -477,7 +2537,28 @@ const api = {
    * directory the user typed a `/` into.
    */
   listDirectory: (dir, cwd) => electron.ipcRenderer.invoke("list-directory", dir, cwd),
+  /**
+   * Hand a URL to the OS, through the main process's vetted door. The outcome
+   * is the door's verdict (round-2 R-4): the toolbar's Open shows a refusal
+   * rather than resolving quietly.
+   */
   openExternal: (url) => electron.ipcRenderer.invoke("open-external", url),
+  /**
+   * A refused external open, pushed to the window whose content asked. The
+   * `openExternal` call answers its caller directly; this is the half a
+   * markdown anchor's click has (round-2 R-4): it left through the main
+   * process's `window.open` door, so main is where the refusal is known and
+   * the renderer is where it must be shown.
+   */
+  onExternalOpenRefused: (callback) => {
+    const handler = (_event, payload) => {
+      if (payload && typeof payload.reason === "string") callback(payload);
+    };
+    electron.ipcRenderer.on(EXTERNAL_OPEN_REFUSED_CHANNEL, handler);
+    return () => {
+      electron.ipcRenderer.removeListener(EXTERNAL_OPEN_REFUSED_CHANNEL, handler);
+    };
+  },
   showItemInFolder: (filePath) => electron.ipcRenderer.invoke("show-item-in-folder", filePath),
   // System information
   systemInfo: {
@@ -768,7 +2849,7 @@ const api = {
     /** `sessionId` attributes the tab to the conversation it was opened from
      * (design R1); `null` is a tab that belongs to no conversation, which is what
      * the route and a draft pane open. Main validates it rather than trusting it. */
-    newTab: (sessionId) => electron.ipcRenderer.invoke("browser-new-tab", sessionId ?? null),
+    newTab: (sessionId2) => electron.ipcRenderer.invoke("browser-new-tab", sessionId2 ?? null),
     closeTab: (tabId) => electron.ipcRenderer.invoke("browser-close-tab", tabId),
     /** A bulk close: `{ mode: "ids", tabIds }` for tabs the user could see, or
      * `{ mode: "conversation", sessionId }` which MAIN resolves at execution time
@@ -782,7 +2863,7 @@ const api = {
     history: (direction) => electron.ipcRenderer.invoke("browser-history", direction),
     setContentRect: (rect) => electron.ipcRenderer.invoke("browser-set-content-rect", rect),
     setViewVisible: (visible) => electron.ipcRenderer.invoke("browser-set-visible", visible),
-    handOver: (tabId, sessionId) => electron.ipcRenderer.invoke("browser-hand-over", tabId, sessionId),
+    handOver: (tabId, sessionId2) => electron.ipcRenderer.invoke("browser-hand-over", tabId, sessionId2),
     revokeHandOver: (tabId) => electron.ipcRenderer.invoke("browser-revoke-hand-over", tabId),
     respondToConsent: (entryId, decision) => electron.ipcRenderer.invoke("browser-consent-respond", entryId, decision),
     revokeApproval: (origin) => electron.ipcRenderer.invoke("browser-revoke-approval", origin),
@@ -797,7 +2878,7 @@ const api = {
      * request id, so this carries no authority of its own — it is the user's
      * choice travelling one way.
      */
-    respondToWebauthn: (requestId, credentialId) => electron.ipcRenderer.invoke("browser-webauthn-respond", requestId, credentialId),
+    respondToWebauthn: (requestId2, credentialId) => electron.ipcRenderer.invoke("browser-webauthn-respond", requestId2, credentialId),
     /** A `navigator.credentials.get()` matched more than one passkey, and the
      * user has to be asked which one to use. Shapes are validated here the way
      * every other inbound payload is: main is trusted, but a malformed payload
@@ -907,7 +2988,7 @@ const api = {
    * the wrong direction, which is why this namespace exists at all.
    */
   console: {
-    state: (sessionId) => electron.ipcRenderer.invoke("console-state", sessionId ?? null),
+    state: (sessionId2) => electron.ipcRenderer.invoke("console-state", sessionId2 ?? null),
     /** Create a surface the USER asked for. Main sets the origin to `user`; the
      * renderer cannot name it, because provenance is not a renderer's to claim. */
     createSurface: (request) => electron.ipcRenderer.invoke("console-create-surface", request),