local-operator-ui 0.16.0 → 0.17.1

package/out/main/index.js

@@ -63,7 +63,21 @@ const mediaRequestSchema = zod.z.discriminatedUnion("op", [
   // rather than the JSON transport: `desktopEndpoint`'s envelope has nowhere to
   // put binary. It is the only read here, which is why `endpoint()` below
   // returns a method instead of assuming POST.
-  zod.z.object({ op: zod.z.literal("agent.export"), agentId: id$1 }).strict()
+  zod.z.object({ op: zod.z.literal("agent.export"), agentId: id$1 }).strict(),
+  // A durable transcript row references an image by content digest with the
+  // payload stripped, so rendering a screenshot after a reload means fetching
+  // bytes. That cannot go through the JSON transport (its envelope has nowhere
+  // to put them), which is what puts it on this relay.
+  //
+  // Both identifiers are shape-constrained here as well as by the backend
+  // route: this file's whole premise is that renderer code cannot pick a URL,
+  // and a digest that reaches `endpoint()` unvalidated is renderer-controlled
+  // path text.
+  zod.z.object({
+    op: zod.z.literal("sessions.attachment"),
+    sessionId: zod.z.string().regex(/^[a-f0-9]{12}$/),
+    digest: zod.z.string().regex(/^[a-f0-9]{32}$/)
+  }).strict()
 ]);
 function endpoint(request) {
   switch (request.op) {
@@ -77,6 +91,11 @@ function endpoint(request) {
       return { path: "/v1/agents/import", method: "POST" };
     case "agent.export":
       return { path: `/v1/agents/${request.agentId}/export`, method: "GET" };
+    case "sessions.attachment":
+      return {
+        path: `/v1/desktop/sessions/${request.sessionId}/attachments/${request.digest}`,
+        method: "GET"
+      };
   }
 }
 async function requestDesktopMedia(input, bytes, backendUrl, token) {
@@ -98,7 +117,7 @@ async function requestDesktopMedia(input, bytes, backendUrl, token) {
   const target2 = endpoint(request);
   let body;
   let contentType;
-  if (request.op === "agent.export") {
+  if (request.op === "agent.export" || request.op === "sessions.attachment") {
     body = void 0;
   } else if (request.op === "speech.create" || request.op === "speech.agent") {
     body = JSON.stringify(request.request);
@@ -123,7 +142,7 @@ async function requestDesktopMedia(input, bytes, backendUrl, token) {
     const response = await fetch(new URL(target2.path, backendUrl), {
       method: target2.method,
       headers: {
-        Accept: "application/json, audio/*, application/octet-stream",
+        Accept: "application/json, audio/*, image/*, application/octet-stream",
         ...contentType ? { "Content-Type": contentType } : {},
         Authorization: `Bearer ${token}`
       },
@@ -311,6 +330,8 @@ 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_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
@@ -410,7 +431,7 @@ const desktopRequestSchema = zod.z.discriminatedUnion("op", [
     op: zod.z.literal("sessions.message"),
     sessionId,
     requestId,
-    text: zod.z.string().max(2e5),
+    text: zod.z.string().max(DESKTOP_MESSAGE_MAX_CHARS),
     images: zod.z.array(sessionImage).max(8).optional(),
     mode: zod.z.enum(["prompt", "steer"]).optional()
   }).strict(),
@@ -419,7 +440,7 @@ const desktopRequestSchema = zod.z.discriminatedUnion("op", [
     sessionId,
     requestId,
     command: zod.z.string().regex(/^\/?[A-Za-z]+$/).max(64),
-    args: zod.z.string().max(2e5).optional(),
+    args: zod.z.string().max(DESKTOP_MESSAGE_MAX_CHARS).optional(),
     images: zod.z.array(sessionImage).max(8).optional()
   }).strict(),
   zod.z.object({
@@ -436,6 +457,17 @@ const desktopRequestSchema = zod.z.discriminatedUnion("op", [
     sessionId,
     completionToken: zod.z.string().uuid()
   }).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(),
   zod.z.object({
     op: zod.z.literal("sessions.watch"),
     sessionId,
@@ -546,7 +578,7 @@ const desktopRequestSchema = zod.z.discriminatedUnion("op", [
   zod.z.object({
     op: zod.z.literal("legacy.agent.systemPrompt.update"),
     agentId: id,
-    systemPrompt: zod.z.string().max(1e6)
+    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.agent.variables.list"), agentId: id }).strict(),
@@ -746,6 +778,34 @@ const desktopRequestSchema = zod.z.discriminatedUnion("op", [
     value: secret
   }).strict()
 ]);
+const DESKTOP_MESSAGE_BYTE_BUDGET = 88e4;
+const DESKTOP_CONTROL_BYTE_BUDGET = 262144;
+const DESKTOP_SYSTEM_PROMPT_BYTE_BUDGET = 11e5;
+const MESSAGE_OPS = /* @__PURE__ */ new Set([
+  "sessions.message",
+  "sessions.command",
+  // `sessions.fork` declares the SAME 200,000-character text field as
+  // `sessions.message` and carries it to the same session, so it belongs in the
+  // same tier; leaving it on the control budget refused a fork message the
+  // schema promised to accept (round 1, R3).
+  "sessions.fork"
+]);
+function desktopRequestByteBudget(op) {
+  if (op === "legacy.agent.systemPrompt.update")
+    return DESKTOP_SYSTEM_PROMPT_BYTE_BUDGET;
+  return MESSAGE_OPS.has(op) ? DESKTOP_MESSAGE_BYTE_BUDGET : DESKTOP_CONTROL_BYTE_BUDGET;
+}
+const DESKTOP_REQUEST_TOO_LARGE_DETAIL = "This message is too large to send in one request. Remove an image, or split the text across two messages.";
+function desktopRequestTooLargeDetail(op) {
+  if (op === "legacy.agent.systemPrompt.update")
+    return "This system prompt is too large to save in one request. Shorten it.";
+  if (op === "sessions.fork")
+    return "This first message is too large to send with the fork. Shorten it, or send it in the new conversation instead.";
+  if (op === "sessions.command")
+    return "This command is too large to send in one request. Shorten it, or put the text in a message instead.";
+  if (MESSAGE_OPS.has(op)) return DESKTOP_REQUEST_TOO_LARGE_DETAIL;
+  return "This request is too large to send. Shorten the text in this form.";
+}
 function desktopEndpoint(request) {
   switch (request.op) {
     case "capabilities":
@@ -868,6 +928,12 @@ function desktopEndpoint(request) {
         method: "POST",
         body: { completion_token: request.completionToken }
       };
+    case "sessions.notified":
+      return {
+        path: `/v1/desktop/sessions/${request.sessionId}/notified`,
+        method: "POST",
+        body: { completion_token: request.completionToken }
+      };
     case "sessions.watch":
       return {
         path: `/v1/desktop/sessions/${request.sessionId}/watch`,
@@ -1214,10 +1280,10 @@ async function requestDesktop(input, backendUrl, token) {
   const target2 = desktopEndpoint(request);
   try {
     const body = target2.body === void 0 ? void 0 : JSON.stringify(target2.body);
-    if (body && Buffer.byteLength(body) > 262144) {
+    if (body && Buffer.byteLength(body) > desktopRequestByteBudget(request.op)) {
       return {
         status: 413,
-        body: { detail: "This desktop request is too large." }
+        body: { detail: desktopRequestTooLargeDetail(request.op) }
       };
     }
     const response = await fetch(new URL(target2.path, backendUrl), {
@@ -1786,6 +1852,31 @@ class BackendServiceManager {
   /** Survives relay recreation so notifications never silently detach
    * when the backend URL rotates. */
   streamObserver = null;
+  /**
+   * Called every time the backend becomes reachable and authenticated.
+   *
+   * The desktop token is minted inside `start()`, so anything that must query
+   * the backend cannot be issued from `app.whenReady()` — at that point the
+   * port is dead on the ordinary self-managed cold start and the request is
+   * lost. This fires after the health check passes, which is the first moment
+   * `requestDesktop` can succeed.
+   *
+   * It fires AGAIN on every restart and on external-backend discovery, on
+   * purpose: the backend underneath a running app can be replaced by a
+   * different version, and a capability read taken once at startup would
+   * outlive the backend it described.
+   */
+  backendReadyObserver = null;
+  onBackendReady(observer) {
+    this.backendReadyObserver = observer;
+  }
+  notifyBackendReady() {
+    try {
+      this.backendReadyObserver?.();
+    } catch (error) {
+      logger.error("Backend-ready observer threw:", LogFileType.BACKEND, error);
+    }
+  }
   getStreamRelay() {
     if (!this.streamRelay || this.streamRelayUrl !== this.backendUrl) {
       this.streamRelay?.dispose();
@@ -2133,6 +2224,7 @@ class BackendServiceManager {
           LogFileType.BACKEND
         );
         this.isExternalBackend = true;
+        this.notifyBackendReady();
         return true;
       }
     } catch (error) {
@@ -2162,6 +2254,7 @@ class BackendServiceManager {
               LogFileType.BACKEND
             );
             this.isExternalBackend = true;
+            this.notifyBackendReady();
             return true;
           }
         }
@@ -2195,6 +2288,7 @@ class BackendServiceManager {
         "Backend Service Manager is disabled. Skipping backend start.",
         LogFileType.BACKEND
       );
+      this.notifyBackendReady();
       return true;
     }
     if (await this.checkExistingBackend()) {
@@ -2330,6 +2424,7 @@ class BackendServiceManager {
         if (await this.checkHealth()) {
           this.isRunning = true;
           this.startHealthCheck();
+          this.notifyBackendReady();
           return true;
         }
         await new Promise((resolve) => setTimeout(resolve, 1e3));
@@ -3889,6 +3984,21 @@ function registerDesktopIPC(window, expectedUrl, request, streams, media, notifi
 }
 const NOTIFY_TTL_MS = 10 * 60 * 1e3;
 const MAX_DEDUPE_KEYS = 2048;
+const CONTRACT_PROBE_ATTEMPTS = 3;
+const CONTRACT_PROBE_RETRY_MS = 250;
+const MAX_BODY_CHARS = 240;
+const TRAILING_COLONS = /:+$/;
+const GATE_BODIES = {
+  ask: "Waiting for your answer",
+  approval: "Waiting for approval"
+};
+function gateBody(kind, gateTitle, gateDetail) {
+  let subject = (gateDetail ?? "").trim();
+  if (subject && gateTitle && !subject.toLowerCase().startsWith(gateTitle.toLowerCase())) {
+    subject = `${gateTitle}: ${subject}`.trim().replace(TRAILING_COLONS, "").trim();
+  }
+  return subject || GATE_BODIES[kind] || GATE_BODIES.approval;
+}
 class DesktopNotifier {
   constructor(window, request) {
     this.window = window;
@@ -3899,9 +4009,163 @@ class DesktopNotifier {
   epochs = /* @__PURE__ */ new Map();
   /** Window state per (window id) used to decide whether a toast is needed. */
   windows = /* @__PURE__ */ new Map();
+  /**
+   * `features.notification_contract` from `/v1/capabilities`; 0 means legacy.
+   *
+   * A HARD switch, not a heuristic. At >= 1 the backend owns every completion
+   * toast and the legacy event path must stay silent or one turn produces two
+   * banners. Absent or unfetchable stays 0 on purpose: a missing capability
+   * response is a transient HTTP failure far more often than it is an old
+   * backend, and failing toward silence would lose completions outright.
+   */
+  notificationContract = 0;
+  /**
+   * The capability read in flight, or the last one that settled.
+   *
+   * `null` only before the first read is ever issued.
+   */
+  contractProbe = null;
+  /**
+   * Generation of the newest capability read, so the LAST-STARTED one wins.
+   *
+   * Probes are not idempotent and they overlap: the backend-ready hook can
+   * fire twice in a tick (external-backend discovery and `start()` both
+   * reported ready), a health-check restart can fire it while an earlier probe
+   * is still retrying, and `awaitContract` starts one of its own. Without this
+   * the shared fields are written by whichever probe SETTLES last, which on a
+   * transient blip is the older read — a successful answer clobbered by a
+   * stale failure, decided by timing rather than by recency (review round 2,
+   * R2-2).
+   *
+   * A superseded probe therefore writes nothing at all and returns. It is not
+   * cancelled — its in-flight `fetch` is left to settle on its own, because
+   * the only cost is one wasted response and the alternative is threading an
+   * `AbortSignal` through the desktop transport for no user-visible gain.
+   */
+  contractGeneration = 0;
+  /**
+   * Whether a capability read has ever come back with a real HTTP answer.
+   *
+   * This is the distinction that closes the double-banner window BY
+   * CONSTRUCTION. A `notificationContract` of 0 has three causes that look
+   * identical on the field alone: the backend answered and has no contract
+   * (old backend, legacy path is correct), nobody has asked yet, and the ask
+   * never reached a backend at all. Only the first is an answer. The other two
+   * are the cold start the review reproduced — the read went to a port nothing
+   * was listening on, was swallowed, and the legacy `agent_end` toast then
+   * fired alongside the composed frame, two banners for one turn.
+   *
+   * So the legacy path re-asks until it has a genuine answer rather than
+   * reading an unanswered 0 as "no contract". Failing toward the legacy path
+   * rather than toward silence (design 4.3) is preserved: once a bounded probe
+   * really has failed at the moment the toast is due, the toast is raised.
+   *
+   * ONCE TRUE THIS AND `notificationContract` MOVE ONLY TOGETHER. A failed
+   * probe that reset the value while leaving this true produced a pair meaning
+   * "we were told there is no contract" when in fact we were told nothing, and
+   * `awaitContract` then declined to re-ask — the double banner returned and
+   * STAYED, every turn, until the next backend bounce (review round 2, R2-1).
+   */
+  contractAnswered = false;
   get canNotify() {
     return electron.Notification.isSupported();
   }
+  /**
+   * Read `features.notification_contract` from the connected backend.
+   *
+   * Call this every time the backend becomes reachable — first start, a health
+   * check restarting it, external-backend discovery rotating the URL. It is
+   * wired to `BackendServiceManager.onBackendReady` for exactly that reason:
+   * issuing it earlier (inside `app.whenReady()`) queries a port nothing is
+   * listening on yet on the ordinary self-managed cold start, and a swallowed
+   * failure there leaves the gate on the legacy path against a backend that
+   * composes — two banners for one turn.
+   *
+   * Re-reading is also the downgrade story the design names (4.3): an app
+   * pointed from a new backend at an old one re-reads 0 and gets its legacy
+   * completion signal back. The previous one-way latch could not do that.
+   *
+   * A throw or a non-200 after the bounded retry leaves the gate at 0, which
+   * is the legacy path rather than silence: see `notificationContract`.
+   */
+  refreshNotificationContract() {
+    const generation = ++this.contractGeneration;
+    const probe = this.probeNotificationContract(generation);
+    this.contractProbe = probe;
+    return probe;
+  }
+  async probeNotificationContract(generation) {
+    for (let attempt = 0; attempt < CONTRACT_PROBE_ATTEMPTS; attempt++) {
+      let response = null;
+      try {
+        response = await this.request({ op: "capabilities" });
+      } catch {
+      }
+      if (generation !== this.contractGeneration) return;
+      if (response?.status === 200) {
+        const body = response.body;
+        this.applyNotificationContract(
+          body?.result?.features?.notification_contract
+        );
+        this.contractAnswered = true;
+        return;
+      }
+      if (attempt + 1 < CONTRACT_PROBE_ATTEMPTS) {
+        await new Promise(
+          (resolve) => setTimeout(resolve, CONTRACT_PROBE_RETRY_MS)
+        );
+        if (generation !== this.contractGeneration) return;
+      }
+    }
+  }
+  /**
+   * Block until a capability read has ANSWERED against the current backend,
+   * or until a fresh bounded probe has failed here and now.
+   *
+   * Issuing the probe itself when none has answered is what makes the legacy
+   * path safe by construction rather than by call-site discipline. The failure
+   * the review reproduced is a read fired before the backend existed: it is
+   * not enough to move that call later, because any read can lose its race
+   * with a backend that is still starting, and a swallowed one leaves a 0 that
+   * reads exactly like an old backend. Re-asking at the moment the answer is
+   * actually needed cannot be beaten by a slow start.
+   *
+   * Loops rather than awaiting once because a backend rotation can start a
+   * new probe while we are waiting on the old one, and the legacy path must
+   * never be decided on the previous backend's answer.
+   */
+  async awaitContract() {
+    if (!this.contractAnswered) this.refreshNotificationContract();
+    let awaited = null;
+    while (this.contractProbe !== awaited) {
+      awaited = this.contractProbe;
+      await awaited;
+    }
+  }
+  /**
+   * Record the contract version a backend reported.
+   *
+   * Being told the value directly IS an answer, so this also stops the legacy
+   * path issuing a probe of its own and overwriting it.
+   *
+   * Bumps the generation for the same reason a probe does: this is the newest
+   * reading of the backend, so an older probe still in flight must not settle
+   * on top of it.
+   */
+  setNotificationContract(version2) {
+    this.contractGeneration++;
+    this.applyNotificationContract(version2);
+    this.contractAnswered = true;
+  }
+  /**
+   * Normalise a reported contract value. Both callers are ANSWERS and both
+   * set `contractAnswered` themselves; nothing else may write this field.
+   * That invariant is the fix for R2-1, so a third caller that resets the
+   * value without answering re-opens it.
+   */
+  applyNotificationContract(version2) {
+    this.notificationContract = typeof version2 === "number" && Number.isFinite(version2) && version2 > 0 ? version2 : 0;
+  }
   /**
    * Renderer heartbeat. Forwarded to the backend as the watch lease for the
    * renderer's active subscription; `can_notify` is asserted only when main
@@ -3930,21 +4194,103 @@ class DesktopNotifier {
     if (frame.type === "snapshot") {
       this.epochs.set(sessionId2, frame.payload.frontend.epoch);
       const gate = frame.payload.frontend.snapshot.pending_gate;
-      if (gate) this.gate(sessionId2, gate.request_id, gate.title, gate.detail);
+      if (gate) this.gate(sessionId2, gate);
       return;
     }
     if (frame.type === "frontend.update") {
       this.epochs.set(sessionId2, frame.payload.epoch);
       const gate = frame.payload.changes.pending_gate;
-      if (gate) this.gate(sessionId2, gate.request_id, gate.title, gate.detail);
+      if (gate) this.gate(sessionId2, gate);
+      return;
+    }
+    if (frame.type === "notification") {
+      void this.composed(sessionId2, frame.payload);
       return;
     }
     if (frame.type === "event") {
-      const eventType = String(frame.payload.type ?? "");
-      if (eventType === "agent_end" || eventType === "turn_end") {
-        this.turn(sessionId2, frame.seq);
+      if (String(frame.payload.type ?? "") !== "agent_end") return;
+      void this.legacyTurn(sessionId2, frame.seq);
+    }
+  }
+  /**
+   * The legacy completion toast, raised only against a backend that composes
+   * none of its own.
+   *
+   * DEFERRED, never raced. A backend advertising `notification_contract` owns
+   * every completion toast, so this must stay silent against it or the user
+   * gets two banners for one turn: the legacy one here plus the composed frame.
+   * `agent_end` is published the moment the turn's last model call returns,
+   * while the composed frame follows from the backend's 1 s attention poll
+   * (design 6.1) — so the event reliably arrives FIRST, and any check that
+   * reacts to a frame already in hand closes the window one frame too late.
+   * Waiting for the capability read to settle is what closes it by
+   * construction. The wait is bounded by `CONTRACT_PROBE_*` and only ever
+   * applies before the first answer of a run.
+   *
+   * `agent_end` survives on this path only because dropping it too would leave
+   * an old backend with no completion signal at all. It is still wrong (it
+   * arrives while `task` children run), which is exactly what the
+   * backend-composed path fixes. The event itself is NEVER filtered out of the
+   * stream: the transcript reducer settles on it.
+   */
+  async legacyTurn(sessionId2, seq) {
+    await this.awaitContract();
+    if (this.notificationContract > 0) return;
+    this.turn(sessionId2, seq);
+  }
+  /**
+   * Deliver one backend-composed notification.
+   *
+   * The order of these four checks is load-bearing and is the whole of 7.3.
+   * Dedupe and the focus gate run BEFORE the claim so a toast we are not going
+   * to show never burns the cross-surface claim; the claim runs immediately
+   * before delivery so the claimant really is the deliverer.
+   */
+  async composed(sessionId2, n) {
+    if (!this.claim(n.dedupe_key)) return;
+    if (n.focus_policy === "when_unfocused" && this.anyFocused()) return;
+    if (n.completion_token) {
+      const outcome = await this.claimDelivery(sessionId2, n.completion_token);
+      if (outcome !== "won") {
+        if (outcome === "failed") this.delivered.delete(n.dedupe_key);
+        return;
       }
     }
+    this.show(
+      sessionId2,
+      n.title,
+      n.status,
+      n.body,
+      n.body_is_snippet,
+      n.body_is_failure ?? false
+    );
+  }
+  /**
+   * Ask the backend whether this surface owns this completion's toast.
+   *
+   * Fails CLOSED on the TOAST: neither `lost` nor `failed` shows anything,
+   * because the failure mode of failing open is the duplicate banner on every
+   * surface this whole mechanism exists to prevent.
+   *
+   * The two non-winning outcomes are still reported separately, because they
+   * differ in who owns the completion afterwards. `lost` means the backend
+   * answered and another surface has it. `failed` means the backend was never
+   * reached or never answered cleanly, so nothing was claimed anywhere and the
+   * completion is still owed to somebody — see the caller.
+   */
+  async claimDelivery(sessionId2, completionToken) {
+    try {
+      const response = await this.request({
+        op: "sessions.notified",
+        sessionId: sessionId2,
+        completionToken
+      });
+      if (response.status !== 200) return "failed";
+      const body = response.body;
+      return body?.result?.claimed === true ? "won" : "lost";
+    } catch {
+      return "failed";
+    }
   }
   anyFocused() {
     for (const state of this.windows.values()) {
@@ -3952,16 +4298,59 @@ class DesktopNotifier {
     }
     return false;
   }
-  gate(sessionId2, requestId2, title, detail) {
+  /**
+   * Raise the banner for a pending approval or question.
+   *
+   * A gate is worth a toast even when the window is focused: the user may be
+   * reading another conversation in the same window.
+   *
+   * When the backend supplies `session_name`, the banner takes the SHAPE of a
+   * completion banner — session name as the title, the gate's own title
+   * leading the detail. Without it, a gate named only its category while
+   * completions named their session, so the banner a user can safely ignore
+   * identified itself and the banner holding a run hostage did not; with two
+   * or three sessions running, that one cannot be triaged without clicking,
+   * which is the action the user was deciding whether to take.
+   *
+   * The name is rendered ONLY as the backend sent it. `session_name` is
+   * additive and optional: it is absent on an older backend and empty when the
+   * `session_names_in_notifications()` privacy flag is off. The backend owns
+   * that decision because only it can read the flag, so this app must never
+   * resolve the name from a snapshot instead — doing so would leak a name the
+   * user opted out of, on every gate, forever.
+   */
+  gate(sessionId2, gate) {
+    const { request_id: requestId2, kind, title, detail } = gate;
     const key = `gate:${sessionId2}:${this.epochs.get(sessionId2) ?? ""}:${requestId2}`;
     if (!this.claim(key)) return;
-    this.show(sessionId2, title || "Approval needed", detail);
+    const fallback = kind === "ask" ? "Question" : "Approval needed";
+    const sessionName = gate.session_name?.trim() || "";
+    if (!sessionName) {
+      this.show(
+        sessionId2,
+        title.trim() || fallback,
+        "",
+        gateBody(kind, "", detail)
+      );
+      return;
+    }
+    this.show(
+      sessionId2,
+      sessionName,
+      "",
+      gateBody(kind, title.trim() || fallback, detail)
+    );
   }
+  /**
+   * Legacy completion toast: canned copy, reached only against a backend that
+   * does not advertise `notification_contract`. Keyed on `session:epoch:seq`
+   * as it always was — an old backend mints no `dedupe_key` to key on.
+   */
   turn(sessionId2, seq) {
     const key = `turn:${sessionId2}:${this.epochs.get(sessionId2) ?? ""}:${seq}`;
     if (!this.claim(key)) return;
     if (this.anyFocused()) return;
-    this.show(sessionId2, "Turn complete", "The agent finished its turn.");
+    this.show(sessionId2, "Turn complete", "", "The agent finished its turn.");
   }
   claim(key) {
     const now = Date.now();
@@ -3974,10 +4363,52 @@ class DesktopNotifier {
     }
     return true;
   }
-  show(sessionId2, title, body) {
+  /**
+   * Render one toast.
+   *
+   * `status` leads the body rather than riding `subtitle`. Electron's
+   * `subtitle` option is documented macOS-only, so on Windows and Linux the
+   * state category would simply vanish and those users would read a bare
+   * snippet with no indication of whether the turn succeeded or failed. One
+   * shape that degrades on no platform beats a second, platform-forked one.
+   * The strings themselves are the backend's, unchanged; only the join is ours.
+   *
+   * The design doc's stated reason for keeping the status out of the title —
+   * "macOS clips a title at ~43 characters" — is FALSE on a current macOS
+   * banner: rendered frames show an 80-character title wrapping across two
+   * lines, not clipping (design review round 1). The real constraint is a
+   * total budget of roughly five text lines for title and body together, after
+   * which macOS truncates the BODY with its own ellipsis. That is why the join
+   * is spent sparingly below.
+   *
+   * WHETHER THE BODY NAMES THE OUTCOME ITSELF decides whether the status earns
+   * its place, and the backend sends two flags for the two kinds of body that
+   * do not. A model-written snippet describes the work, and the session's own
+   * recorded failure text describes the cause ("anthropic: 429
+   * rate_limit_error - credit balance too low"); neither says whether the turn
+   * succeeded, so the category in front of it is the only thing that does. The
+   * house bodies ("Task complete", "Stopped with an error") already name the
+   * state, so prefixing them renders "Complete — Task complete": one fact
+   * asserted twice in the two lines a banner gets, which is what every user
+   * with the session-name privacy flag off would have received.
+   *
+   * Reading only `body_is_snippet` split the world in two where the backend
+   * made it three, and it inverted the intent of the failure text (design
+   * round 1, D4): a raw 429 envelope under a session name reads as routine log
+   * noise, so the ONE banner that demands action was the one that never said
+   * anything had gone wrong — and it was worse with the privacy flag ON (the
+   * default, which is what produces the failure text) than off, where the user
+   * at least got "Stopped with an error" (QA round 1, Q-1).
+   *
+   * These are the backend's own flags for exactly this difference, so this app
+   * still re-words nothing (design 8.4). Gates pass `status = ""` and are
+   * unaffected either way.
+   */
+  show(sessionId2, title, status, body, isSnippet = false, isFailure = false) {
+    const lead = (isSnippet || isFailure) && status ? `${status} — ` : "";
     const notification = new electron.Notification({
       title,
-      body: body.slice(0, 240),
+      body: `${lead}${body}`.slice(0, MAX_BODY_CHARS),
       silent: false
     });
     notification.on("click", () => {
@@ -5384,6 +5815,9 @@ electron.app.whenReady().then(async () => {
     (input) => backendService.requestDesktop(input)
   );
   const desktopNotifier = new DesktopNotifier(() => mainWindow, sendDesktop);
+  backendService.onBackendReady(() => {
+    void desktopNotifier.refreshNotificationContract();
+  });
   backendService.observeStream((sessionId2, data) => {
     try {
       desktopNotifier.observe(sessionId2, JSON.parse(data));
@@ -5448,6 +5882,15 @@ electron.app.whenReady().then(async () => {
     const normalizedPath = filePath.startsWith("~/") ? path.join(electron.app.getPath("home"), filePath.slice(2)) : filePath;
     return fs.existsSync(normalizedPath);
   });
+  electron.ipcMain.handle("directory-exists", async (_, dirPath) => {
+    const home = electron.app.getPath("home");
+    const normalizedPath = dirPath === "~" ? home : dirPath.startsWith("~/") ? path.join(home, dirPath.slice(2)) : dirPath;
+    try {
+      return fs.statSync(normalizedPath, { throwIfNoEntry: false })?.isDirectory() ?? false;
+    } catch {
+      return false;
+    }
+  });
   electron.ipcMain.handle("show-open-dialog", async (_, options) => {
     if (!mainWindow) {
       logger.error(

package/out/preload/index.js

@@ -223,6 +223,12 @@ const api = {
   saveFile: (filePath, content, encoding) => electron.ipcRenderer.invoke("save-file", filePath, content, encoding),
   /** Checks if a file exists at the specified path */
   fileExists: (filePath) => electron.ipcRenderer.invoke("file-exists", filePath),
+  /**
+   * Checks that a path exists AND is a directory. `fileExists` cannot answer
+   * this: it says yes for a regular file, so a working directory of
+   * `/etc/hosts` passed validation and failed at session creation instead.
+   */
+  directoryExists: (dirPath) => electron.ipcRenderer.invoke("directory-exists", dirPath),
   // Add methods for installer
   ipcRenderer: {
     send: (channel, ...args) => {