mulmoclaude 0.9.2 → 0.9.3

package/server/workspace/collections/remoteView.ts

@@ -0,0 +1,290 @@
+// Assemble one mobile (`target: "mobile"`) custom view for the remote client:
+// find the view entry, read its HTML (source-aware staging read), pick its
+// i18n dict for the requested locale, wrap it into the sandboxed srcdoc
+// (CSP + postMessage bootstrap — @mulmoclaude/core/remote-view), and enforce
+// the 1 MiB command-document budget. Shared by the `getRemoteView` channel
+// handler and the desktop preview's HTTP route so both serve the IDENTICAL
+// artifact (plans/feat-remote-custom-view.md, decision 2).
+//
+// Discriminated result (not throw) so the HTTP route can map each failure to
+// its status; the channel handler converts non-ok to a thrown error via
+// `remoteViewFailureMessage`. Factory keeps the mapping unit-testable with the
+// engine stubbed.
+import {
+  buildRemoteViewSrcdoc,
+  clampImageMaxEdge,
+  pageFromItems,
+  REMOTE_VIEW_ITEMS_MAX_BYTES,
+  REMOTE_VIEW_MAX_BYTES,
+  type RemoteViewItem,
+  type RemoteViewMutateRequest,
+  type RemoteViewPage,
+  type RemoteViewPageRequest,
+} from "@mulmoclaude/core/remote-view";
+import { deriveAll } from "@mulmoclaude/core/collection";
+import {
+  deleteItem,
+  listItems,
+  readCustomViewHtml,
+  readCustomViewI18n,
+  readItem,
+  safeRecordId,
+  writeItem,
+  type CollectionCustomView,
+  type CollectionItem,
+  type CollectionSchema,
+  type LoadedCollection,
+} from "./index.js";
+import { resolveThumbnail } from "../../utils/files/thumbnail-store.js";
+
+export interface RemoteViewInfo {
+  id: string;
+  label: string;
+  icon?: string;
+  target: "mobile";
+}
+
+export type RemoteViewBuildResult =
+  | { kind: "ok"; view: RemoteViewInfo; srcdoc: string; bytes: number }
+  | { kind: "view-not-found"; viewId: string }
+  | { kind: "not-mobile"; viewId: string }
+  | { kind: "file-missing"; file: string }
+  | { kind: "too-large"; bytes: number };
+
+export interface BuildRemoteViewDeps {
+  readCustomViewHtml: typeof readCustomViewHtml;
+  readCustomViewI18n: typeof readCustomViewI18n;
+}
+
+export const createBuildRemoteView =
+  (deps: BuildRemoteViewDeps) =>
+  async (collection: LoadedCollection, viewId: string, locale: string): Promise<RemoteViewBuildResult> => {
+    const view = (collection.schema.views ?? []).find((entry) => entry.id === viewId);
+    if (!view) return { kind: "view-not-found", viewId };
+    // A desktop view's HTML assumes the token/dataUrl contract and would just
+    // break on the phone — refuse it instead of serving a broken page.
+    if (view.target !== "mobile") return { kind: "not-mobile", viewId };
+    const html = await deps.readCustomViewHtml(collection, view.file);
+    if (html === null) return { kind: "file-missing", file: view.file };
+    const i18n = view.i18n ? await deps.readCustomViewI18n(collection, view.i18n, locale) : { locale: "", dict: {} };
+    // `writable` gates the client-side updateItem/deleteItem install; the host
+    // re-derives + enforces the actual policy on every mutate (createMutateRemoteView).
+    const writable = isWritableView(view);
+    const srcdoc = buildRemoteViewSrcdoc(html, { slug: collection.slug, locale: i18n.locale, dict: i18n.dict, writable });
+    const bytes = Buffer.byteLength(srcdoc, "utf8");
+    if (bytes > REMOTE_VIEW_MAX_BYTES) return { kind: "too-large", bytes };
+    return { kind: "ok", view: { id: view.id, label: view.label, ...(view.icon ? { icon: view.icon } : {}), target: "mobile" }, srcdoc, bytes };
+  };
+
+export const buildRemoteView = createBuildRemoteView({ readCustomViewHtml, readCustomViewI18n });
+
+/** One message per failure kind, shared by the channel handler (throws it) and
+ *  the HTTP route (sends it with the matching status). */
+export function remoteViewFailureMessage(result: Exclude<RemoteViewBuildResult, { kind: "ok" }>, slug: string): string {
+  if (result.kind === "view-not-found") return `custom view '${result.viewId}' not found on collection '${slug}'`;
+  if (result.kind === "not-mobile") return `custom view '${result.viewId}' is not a mobile view — declare target: "mobile" in its views[] entry`;
+  if (result.kind === "file-missing") return `view file '${result.file}' not found — author it at data/skills/${slug}/${result.file}`;
+  return `mobile view srcdoc is ${result.bytes} bytes — over the ${REMOTE_VIEW_MAX_BYTES}-byte command-channel budget; slim the HTML`;
+}
+
+// ── Mutate (phase 4 — plans/feat-remote-writable-view.md) ──
+// A `target: "mobile"` view's update/delete, authorized by its OWN declared
+// surface (editableFields / allowDelete) and enforced HOST-side — the client is
+// never trusted. Shared by the `mutateRemoteViewItem` channel handler (phone)
+// and the `…/remote-view/:viewId/mutate` HTTP route (desktop preview), so both
+// transports apply identical policy. Discriminated result (not throw) mirrors
+// the build result above.
+
+/** True when a mobile view declared ANY write surface. Also gates the srcdoc's
+ *  `writable` boot flag so the client only exposes methods the host will honor. */
+function isWritableView(view: CollectionCustomView): boolean {
+  return (view.editableFields?.length ?? 0) > 0 || view.allowDelete === true;
+}
+
+export type MutateRemoteViewResult =
+  | { kind: "ok"; op: "update"; item: CollectionItem }
+  | { kind: "ok"; op: "delete"; id: string }
+  | { kind: "view-not-found"; viewId: string }
+  | { kind: "not-mobile"; viewId: string }
+  | { kind: "not-writable"; viewId: string }
+  | { kind: "field-not-editable"; field: string }
+  | { kind: "delete-not-allowed" }
+  | { kind: "invalid-patch" }
+  | { kind: "item-not-found"; id: string }
+  | { kind: "invalid-id"; id: string }
+  | { kind: "path-escape" };
+
+export interface MutateRemoteViewDeps {
+  readItem: typeof readItem;
+  writeItem: typeof writeItem;
+  deleteItem: typeof deleteItem;
+  resolveThumbnail: typeof resolveThumbnail;
+}
+
+export const createMutateRemoteView =
+  (deps: MutateRemoteViewDeps) =>
+  async (collection: LoadedCollection, viewId: string, request: RemoteViewMutateRequest): Promise<MutateRemoteViewResult> => {
+    const view = (collection.schema.views ?? []).find((entry) => entry.id === viewId);
+    if (!view) return { kind: "view-not-found", viewId };
+    if (view.target !== "mobile") return { kind: "not-mobile", viewId };
+    if (!isWritableView(view)) return { kind: "not-writable", viewId };
+    return request.op === "delete" ? deleteViaView(deps, collection, view.allowDelete === true, request.id) : updateViaView(deps, collection, view, request);
+  };
+
+async function deleteViaView(deps: MutateRemoteViewDeps, collection: LoadedCollection, allowDelete: boolean, itemId: string): Promise<MutateRemoteViewResult> {
+  if (!allowDelete) return { kind: "delete-not-allowed" };
+  const result = await deps.deleteItem(collection.dataDir, itemId, { slug: collection.slug });
+  if (result.kind === "invalid-id") return { kind: "invalid-id", id: result.itemId };
+  if (result.kind === "path-escape") return { kind: "path-escape" };
+  if (result.kind === "not-found") return { kind: "item-not-found", id: result.itemId };
+  return { kind: "ok", op: "delete", id: result.itemId };
+}
+
+async function updateViaView(
+  deps: MutateRemoteViewDeps,
+  collection: LoadedCollection,
+  view: CollectionCustomView,
+  request: Extract<RemoteViewMutateRequest, { op: "update" }>,
+): Promise<MutateRemoteViewResult> {
+  const { primaryKey } = collection.schema;
+  const patchKeys = Object.keys(request.patch);
+  if (patchKeys.length === 0) return { kind: "invalid-patch" };
+  const allowed = new Set(view.editableFields ?? []);
+  // The primary key is never patchable (it is the record id — renaming it would
+  // desync the file name from the record) even if an author listed it.
+  const offending = patchKeys.find((key) => key === primaryKey || !allowed.has(key));
+  if (offending) return { kind: "field-not-editable", field: offending };
+  // Classify a bad id BEFORE readItem — which returns null for an unsafe id, a
+  // path-escape, AND a genuinely-missing record alike — so update reports the
+  // same explicit `invalid-id` the delete path does (via deleteItem) instead of
+  // masking it as a 404. (A valid id whose dataDir escapes the workspace can
+  // hold no record, so it still resolves to item-not-found; a real write is
+  // additionally refused by writeItem's own containment guard below.)
+  if (safeRecordId(request.id) === null) return { kind: "invalid-id", id: request.id };
+  const existing = await deps.readItem(collection.dataDir, request.id, { slug: collection.slug });
+  if (!existing) return { kind: "item-not-found", id: request.id };
+  const merged: CollectionItem = { ...existing, ...request.patch, [primaryKey]: request.id };
+  const result = await deps.writeItem(collection.dataDir, request.id, merged, { slug: collection.slug });
+  if (result.kind === "invalid-id") return { kind: "invalid-id", id: result.itemId };
+  if (result.kind === "path-escape") return { kind: "path-escape" };
+  if (result.kind === "conflict") return { kind: "item-not-found", id: result.itemId }; // unreachable: refuseOverwrite is false
+  // The returned item must be shaped like a `getItems` item — with the view's
+  // declared image fields inlined as `data:` URLs — so a view that merges the
+  // result (as the help file recommends) doesn't clobber a good thumbnail with a
+  // bare path. No projection here (the whole record is returned), so inline every
+  // declared image-type field. Budget the thumbnail against the serialized item
+  // (same as the page builder) so a record with large text/markdown fields can't
+  // push the mutate result over the command-document cap — over budget, the field
+  // stays a path (placeholder), never a doc-write failure.
+  const item = result.item as RemoteViewItem;
+  const imageFields = inlineFields(view, collection.schema, undefined);
+  if (imageFields.length > 0) {
+    const budget = REMOTE_VIEW_ITEMS_MAX_BYTES - Buffer.byteLength(JSON.stringify(item), "utf8");
+    await inlineImages([item], imageFields, clampImageMaxEdge(view.imageMaxEdge), deps.resolveThumbnail, Math.max(0, budget));
+  }
+  return { kind: "ok", op: "update", item: item as CollectionItem };
+}
+
+export const mutateRemoteView = createMutateRemoteView({ readItem, writeItem, deleteItem, resolveThumbnail });
+
+// ── Item pages with inlined image thumbnails (phase 5 — plans/feat-remote-view-images.md) ──
+// A mobile view's `getItems`, view-aware so it can inline the `imageFields` its
+// declaration whitelists: derive computed fields → slice/project (the phase-2
+// page semantics) → replace each declared image-type field's workspace path with
+// a downscaled `data:` URL thumbnail, within a per-page byte budget so the 1 MiB
+// command doc is never risked. Shared by the `getRemoteViewItems` channel handler
+// (phone) and the `…/remote-view/:viewId/items` HTTP route (desktop preview).
+
+export type RemoteViewItemsResult =
+  { kind: "ok"; page: RemoteViewPage; inlined: number; omitted: number } | { kind: "view-not-found"; viewId: string } | { kind: "not-mobile"; viewId: string };
+
+export interface RemoteViewItemsDeps {
+  listItems: typeof listItems;
+  resolveThumbnail: typeof resolveThumbnail;
+}
+
+/** The declared image fields that are actually inlineable this page: image-type
+ *  in the schema AND kept by the request's `fields` projection (a projection
+ *  that dropped the column ships no image bytes). A declared non-image field is
+ *  ignored, not an error. */
+function inlineFields(view: CollectionCustomView, schema: CollectionSchema, requested: string[] | undefined): string[] {
+  const declared = view.imageFields ?? [];
+  if (declared.length === 0) return [];
+  const kept = requested ? new Set([schema.primaryKey, ...requested]) : null;
+  return declared.filter((name) => schema.fields[name]?.type === "image" && (kept === null || kept.has(name)));
+}
+
+/** Replace declared image paths with thumbnail `data:` URLs in place, stopping
+ *  once the accumulated thumbnail bytes would exceed `budget` — a field left as
+ *  its path (over budget, unresolvable, or already inlined) counts as `omitted`
+ *  and the view renders it as a placeholder. */
+async function inlineImages(
+  items: RemoteViewItem[],
+  fields: string[],
+  maxEdge: number,
+  resolve: typeof resolveThumbnail,
+  budget: number,
+): Promise<{ inlined: number; omitted: number }> {
+  let used = 0;
+  let inlined = 0;
+  let omitted = 0;
+  for (const item of items) {
+    for (const field of fields) {
+      const value = item[field];
+      if (typeof value !== "string" || value.length === 0 || value.startsWith("data:")) continue;
+      const dataUrl = used < budget ? await resolve(value, maxEdge) : null;
+      if (dataUrl && used + dataUrl.length <= budget) {
+        item[field] = dataUrl;
+        used += dataUrl.length;
+        inlined += 1;
+      } else {
+        omitted += 1;
+      }
+    }
+  }
+  return { inlined, omitted };
+}
+
+export const createRemoteViewItems =
+  (deps: RemoteViewItemsDeps) =>
+  async (collection: LoadedCollection, viewId: string, request: RemoteViewPageRequest): Promise<RemoteViewItemsResult> => {
+    const view = (collection.schema.views ?? []).find((entry) => entry.id === viewId);
+    if (!view) return { kind: "view-not-found", viewId };
+    if (view.target !== "mobile") return { kind: "not-mobile", viewId };
+    // Derive record-local formulas with an empty ref cache — same as the phase-2
+    // channel handlers and the preview, so `getItems` numbers match the desktop.
+    const derived = (await deps.listItems(collection.dataDir)).map((item) => deriveAll(collection.schema, item, {}) as RemoteViewItem);
+    const page = pageFromItems(derived, request, collection.schema.primaryKey);
+    const fields = inlineFields(view, collection.schema, request.fields);
+    if (fields.length === 0) return { kind: "ok", page, inlined: 0, omitted: 0 };
+    // Budget the thumbnails against what's left of the doc after the (tiny,
+    // path-only) base JSON, so the serialized page stays under the cap.
+    const budget = REMOTE_VIEW_ITEMS_MAX_BYTES - Buffer.byteLength(JSON.stringify(page), "utf8");
+    const { inlined, omitted } = await inlineImages(page.items, fields, clampImageMaxEdge(view.imageMaxEdge), deps.resolveThumbnail, Math.max(0, budget));
+    return { kind: "ok", page, inlined, omitted };
+  };
+
+export const remoteViewItems = createRemoteViewItems({ listItems, resolveThumbnail });
+
+/** Message per non-ok item-page kind — shared by the channel handler (throws)
+ *  and the HTTP route (sends with the matching status). */
+export function remoteViewItemsFailureMessage(result: Exclude<RemoteViewItemsResult, { kind: "ok" }>, slug: string): string {
+  if (result.kind === "not-mobile") return `custom view '${result.viewId}' is not a mobile view — declare target: "mobile" in its views[] entry`;
+  return `custom view '${result.viewId}' not found on collection '${slug}'`;
+}
+
+/** Message per non-ok mutate kind — shared by the channel handler (throws) and
+ *  the HTTP route (sends with the matching status). */
+export function mutateRemoteViewFailureMessage(result: Exclude<MutateRemoteViewResult, { kind: "ok" }>, slug: string): string {
+  if (result.kind === "view-not-found") return `custom view '${result.viewId}' not found on collection '${slug}'`;
+  if (result.kind === "not-mobile") return `custom view '${result.viewId}' is not a mobile view — declare target: "mobile" in its views[] entry`;
+  if (result.kind === "not-writable")
+    return `mobile view '${result.viewId}' is read-only — declare editableFields and/or allowDelete in its views[] entry to allow writes`;
+  if (result.kind === "field-not-editable")
+    return `field '${result.field}' is not editable from this view — add it to the view's editableFields (the primary key is never editable)`;
+  if (result.kind === "delete-not-allowed") return `this view may not delete records — set allowDelete: true in its views[] entry`;
+  if (result.kind === "invalid-patch") return `update patch must be a non-empty object of field changes`;
+  if (result.kind === "item-not-found") return `item '${result.id}' not found in collection '${slug}'`;
+  if (result.kind === "invalid-id") return `invalid item id: ${result.id}`;
+  return `data directory for collection '${slug}' escapes the workspace`;
+}

package/src/App.vue

@@ -320,7 +320,7 @@
 </template>
 
 <script setup lang="ts">
-import { ref, computed, watch, nextTick, onMounted, reactive } from "vue";
+import { ref, computed, watch, nextTick, onMounted, onScopeDispose, reactive } from "vue";
 import { useI18n } from "vue-i18n";
 import { v4 as uuidv4 } from "uuid";
 import { getPlugin } from "./tools";
@@ -425,7 +425,7 @@ const currentSessionId = ref("");
 // --- Debug beat (pub/sub) ---
 const { debugTitleStyle } = useDebugBeat();
 
-const { subscribe: pubsubSubscribe } = usePubSub();
+const { subscribe: pubsubSubscribe, onReconnect: pubsubOnReconnect } = usePubSub();
 
 // --- Routing ---
 const route = useRoute();
@@ -482,7 +482,7 @@ const pastedFiles = ref<PastedFile[]>([]);
 const activePane = ref<"sidebar" | "main">("sidebar");
 
 const { sessions, historyError, fetchSessions, setBookmark, deleteSession: deleteSessionFromHistory } = useSessionHistory();
-const { markSessionRead } = useSessionSync({
+const { markSessionRead, refreshSessionStates } = useSessionSync({
   sessionMap,
   currentSessionId,
   fetchSessions,
@@ -991,6 +991,16 @@ function hasPendingGenerations(sessionId: string): boolean {
 }
 
 function handleSessionFinished(sessionId: string): void {
+  // Trust the definitive server signal and flip the local indicator
+  // immediately (#1915 Fix A). Without this, the "thinking" spinner stays
+  // stuck until the `sessions` channel notification arrives via a separate
+  // socket.io frame — which can go missing on a network hiccup or on
+  // Safari's tab-throttling flow while the sessionChannel frame did land.
+  const session = sessionMap.get(sessionId);
+  if (session) {
+    session.isRunning = false;
+    session.statusMessage = "";
+  }
   refreshSessionTranscript(sessionId).catch((err) => {
     console.error("[handleSessionFinished] refresh failed:", err);
   });
@@ -1001,6 +1011,50 @@ function handleSessionFinished(sessionId: string): void {
   }
 }
 
+// After the client silently loses events, this pulls fresh state from the
+// server so the UI recovers without a page reload (#1915). Two trigger
+// surfaces:
+//   - socket.io reconnect (network hiccup, WS bounce)
+//   - document visibility flips to `visible` (Safari's silent tab
+//     throttling — WS keeps `connected` on the server but delivery stops
+//     while the tab is backgrounded, and there's no `disconnect` event to
+//     hook on reconnect)
+// refreshSessionStates() carries its own sequence guard inside
+// useSessionSync so concurrent catch-ups can't overwrite newer live state
+// with an older-but-slower response. refreshSessionTranscript() only
+// upgrades toolResults when the server view is strictly larger, so it's
+// already idempotent against interleaving.
+function catchUpMissedEvents(reason: "reconnect" | "visibility"): void {
+  console.info(`[chat-ui] catching up after ${reason}`);
+  refreshSessionStates().catch((err) => {
+    console.warn("[chat-ui] refreshSessionStates failed:", err);
+  });
+  const currentId = currentSessionId.value;
+  if (currentId) {
+    refreshSessionTranscript(currentId).catch((err) => {
+      console.warn("[chat-ui] refreshSessionTranscript failed:", err);
+    });
+  }
+}
+
+// Capture the unsubscribe so remount / HMR doesn't accumulate stale
+// module-level reconnect handlers (Codex review).
+const unsubReconnect = pubsubOnReconnect(() => catchUpMissedEvents("reconnect"));
+
+function handleVisibilityChange(): void {
+  if (document.visibilityState === "visible") {
+    catchUpMissedEvents("visibility");
+  }
+}
+
+onMounted(() => {
+  document.addEventListener("visibilitychange", handleVisibilityChange);
+});
+onScopeDispose(() => {
+  document.removeEventListener("visibilitychange", handleVisibilityChange);
+  unsubReconnect();
+});
+
 function createSessionEventHandler(session: ActiveSession, ctx: AgentEventContext): (data: unknown) => void {
   return (data: unknown) => {
     const event = data as SseEvent;

package/src/composables/collections/uiHost.ts

@@ -12,6 +12,9 @@
 // `notifiedSeverities` returns an empty map.
 import {
   configureCollectionUi,
+  type CollectionRemoteViewResult,
+  type CollectionRemoteViewMutateResult,
+  type CollectionRemoteViewItemsResult,
   type CollectionViewI18nResult,
   type CollectionViewToken,
   type RegistryListResponse,
@@ -57,6 +60,10 @@ const collectionActionUrl = (slug: string, actionId: string): string =>
   withSlug(API_ROUTES.collections.collectionAction, slug).replace(":actionId", encodeURIComponent(actionId));
 const viewDeleteUrl = (slug: string, viewId: string): string =>
   withSlug(API_ROUTES.collections.viewDelete, slug).replace(":viewId", encodeURIComponent(viewId));
+const remoteViewMutateUrl = (slug: string, viewId: string): string =>
+  withSlug(API_ROUTES.collections.remoteViewMutate, slug).replace(":viewId", encodeURIComponent(viewId));
+const remoteViewItemsUrl = (slug: string, viewId: string): string =>
+  withSlug(API_ROUTES.collections.remoteViewItems, slug).replace(":viewId", encodeURIComponent(viewId));
 
 // ── Deferred app bindings (need a component context; set by App.vue setup) ──
 type StartChat = (prompt: string, role: string) => void;
@@ -98,6 +105,14 @@ configureCollectionUi({
     }
   },
   fetchViewI18n: (slug, viewId, locale) => apiGet<CollectionViewI18nResult>(withSlug(API_ROUTES.collections.viewI18n, slug), { id: viewId, locale }),
+  fetchRemoteView: (slug, viewId, locale) => apiGet<CollectionRemoteViewResult>(withSlug(API_ROUTES.collections.remoteView, slug), { id: viewId, locale }),
+  mutateRemoteView: (slug, viewId, request) => apiPost<CollectionRemoteViewMutateResult>(remoteViewMutateUrl(slug, viewId), request),
+  fetchRemoteViewItems: (slug, viewId, request) =>
+    apiGet<CollectionRemoteViewItemsResult>(remoteViewItemsUrl(slug, viewId), {
+      offset: request.offset,
+      limit: request.limit,
+      fields: request.fields?.join(",") || undefined,
+    }),
   buildViewSrcdoc: (html, boot) => buildCustomViewSrcdoc(html, boot),
 
   // record CRUD + actions

package/src/composables/usePubSub.ts

@@ -7,11 +7,17 @@ interface PubSubMessage {
 
 type Callback = (data: unknown) => void;
 type Unsubscribe = () => void;
+type ReconnectHandler = () => void;
 
 // On reconnect we re-emit every live subscription so the rooms list survives the bounce.
 let socket: Socket | null = null;
 
 const listeners = new Map<string, Set<Callback>>();
+const reconnectHandlers = new Set<ReconnectHandler>();
+// First `connect` is the initial establishment; every subsequent one is a
+// reconnect and needs a state catch-up (missed events during the down window
+// are lost because the pub/sub server has no replay buffer). See #1915.
+let hasConnectedOnce = false;
 
 function resendSubscriptions(sock: Socket): void {
   for (const channel of listeners.keys()) {
@@ -19,6 +25,16 @@ function resendSubscriptions(sock: Socket): void {
   }
 }
 
+function fireReconnectHandlers(): void {
+  for (const handler of reconnectHandlers) {
+    try {
+      handler();
+    } catch (err) {
+      console.error("[usePubSub] reconnect handler threw:", err);
+    }
+  }
+}
+
 function connect(): Socket {
   if (socket) return socket;
 
@@ -28,7 +44,14 @@ function connect(): Socket {
     transports: ["websocket"],
   });
 
-  sock.on("connect", () => resendSubscriptions(sock));
+  sock.on("connect", () => {
+    resendSubscriptions(sock);
+    if (hasConnectedOnce) {
+      fireReconnectHandlers();
+    } else {
+      hasConnectedOnce = true;
+    }
+  });
 
   sock.on("data", (msg: PubSubMessage) => {
     const cbs = listeners.get(msg.channel);
@@ -46,6 +69,10 @@ function maybeDisconnect(): void {
   if (!socket) return;
   socket.disconnect();
   socket = null;
+  // Reset so the next `connect()` cycle is a true initial connect again —
+  // catch-up handlers only make sense against state accumulated on this
+  // socket, not across an unsubscribe/resubscribe cycle.
+  hasConnectedOnce = false;
 }
 
 export function usePubSub() {
@@ -73,5 +100,16 @@ export function usePubSub() {
     };
   }
 
-  return { subscribe };
+  // Register a handler that fires on every reconnect (not the initial
+  // connect). Callers use this to catch up on missed events after the
+  // socket bounces — the pub/sub server has no replay buffer, so anything
+  // published during the down window is gone. See #1915.
+  function onReconnect(handler: ReconnectHandler): Unsubscribe {
+    reconnectHandlers.add(handler);
+    return () => {
+      reconnectHandlers.delete(handler);
+    };
+  }
+
+  return { subscribe, onReconnect };
 }

package/src/composables/useSessionSync.ts

@@ -30,7 +30,15 @@ export function useSessionSync(opts: {
   const { sessionMap, currentSessionId, fetchSessions, onCurrentSessionDeleted } = opts;
   const { subscribe } = usePubSub();
 
+  // Monotonic sequence token — protects sessionMap from stale overwrites when
+  // two concurrent refreshes race (e.g. reconnect fires while a
+  // visibilitychange is mid-flight). Every call increments the token before
+  // awaiting; after the fetch resolves, we mutate only if our token is still
+  // the latest, so the older-but-slower response can never regress live
+  // state (e.g. re-flip isRunning back to true after session_finished).
+  let refreshToken = 0;
   async function refreshSessionStates(): Promise<void> {
+    const myToken = ++refreshToken;
     let summaries: SessionSummary[];
     try {
       summaries = await fetchSessions();
@@ -40,6 +48,7 @@ export function useSessionSync(opts: {
       console.warn("[session-sync] failed to fetch sessions:", err);
       return;
     }
+    if (myToken !== refreshToken) return;
     for (const summary of summaries) {
       const live = sessionMap.get(summary.id);
       if (!live) continue;

package/src/config/apiRoutes.ts

@@ -293,6 +293,26 @@ const HOST_API_ROUTES = {
     /** GET ?id=<viewId> → the custom view's HTML file (global-bearer auth),
      *  read from data/skills/:slug/views/. The parent renders it sandboxed. */
     viewFile: "/api/collections/:slug/view-file",
+    /** GET ?id=<viewId>&locale=<tag> → a mobile (`target: "mobile"`) custom
+     *  view wrapped into its sandboxed srcdoc (global-bearer auth) →
+     *  { view, srcdoc, bytes }. Same builder as the command channel's
+     *  `getRemoteView`, so the desktop phone-frame preview renders the exact
+     *  artifact the phone receives (plans/feat-remote-custom-view.md). */
+    remoteView: "/api/collections/:slug/remote-view",
+    /** POST { op: "update"|"delete", id, patch? } → apply one mutate on behalf
+     *  of a `target: "mobile"` view, authorized by that view's declared
+     *  editableFields / allowDelete and enforced host-side (global-bearer auth).
+     *  The desktop phone-frame preview's write channel — same builder the
+     *  command channel's `mutateRemoteViewItem` uses, so preview === phone
+     *  (plans/feat-remote-writable-view.md). */
+    remoteViewMutate: "/api/collections/:slug/remote-view/:viewId/mutate",
+    /** GET ?offset&limit&fields=<csv> → one page of a `target: "mobile"` view's
+     *  records with its declared `imageFields` inlined as `data:` URL thumbnails
+     *  (global-bearer auth) → { page, inlined, omitted }. Same builder as the
+     *  command channel's `getRemoteViewItems`, so the desktop phone-frame preview
+     *  pages the exact data (incl. real thumbnails) the phone will
+     *  (plans/feat-remote-view-images.md). */
+    remoteViewItems: "/api/collections/:slug/remote-view/:viewId/items",
     /** GET ?id=<viewId>&locale=<tag> → translation dict for one custom view
      *  (global-bearer auth) → { locale, dict }. `dict` is the host-picked
      *  flat map for the requested locale (fallback `"en"`, else `{}`); the

package/src/config/roles.ts

@@ -46,7 +46,7 @@ export const ROLES: Role[] = [
   {
     id: "general",
     name: "General",
-    icon: "star",
+    icon: "auto_awesome",
     prompt:
       "You are a helpful assistant with access to the user's workspace. Help with tasks, answer questions, and use available tools when appropriate.\n\n" +
       "## Asking the user to choose\n\n" +
@@ -372,7 +372,7 @@ export const ROLES: Role[] = [
   {
     id: "debug",
     name: "Debug",
-    icon: "star",
+    icon: "bug_report",
     prompt:
       "You are a helpful assistant with access to the user's workspace. Help with tasks, answer questions, and use available tools when appropriate.\n\n" +
       "## Asking the user to choose\n\n" +

package/src/lang/de.ts

@@ -949,6 +949,8 @@ const deMessages = {
     cancel: "Abbrechen",
     seededByPlugin: "von {pkg}",
     seededByPluginTooltip: "Diese Nachricht wurde vom Plugin {pkg} erstellt und nicht von Ihnen gesendet.",
+    truncatedForRender:
+      "Diese Nachricht ist ungewöhnlich lang (insgesamt {total} Zeichen). Nur der erste Teil wird angezeigt – {omitted} Zeichen ausgeblendet, damit der Tab reaktionsfähig bleibt. Nutze „Kopieren“ für den vollständigen Text.",
   },
   pluginSkill: {
     noDescription: "(keine Beschreibung)",

package/src/lang/en.ts

@@ -961,6 +961,8 @@ const enMessages = {
     cancel: "Cancel",
     seededByPlugin: "from {pkg}",
     seededByPluginTooltip: "This message was seeded by the {pkg} plugin, not sent by you.",
+    truncatedForRender:
+      "This message is unusually long ({total} chars total). Only the first portion is rendered — {omitted} chars hidden to keep the tab responsive. Use Copy for the full raw text.",
   },
   pluginSkill: {
     noDescription: "(no description)",

package/src/lang/es.ts

@@ -947,6 +947,8 @@ const esMessages = {
     cancel: "Cancelar",
     seededByPlugin: "desde {pkg}",
     seededByPluginTooltip: "Este mensaje fue generado por el plugin {pkg}, no enviado por ti.",
+    truncatedForRender:
+      "Este mensaje es inusualmente largo ({total} caracteres en total). Solo se muestra la primera parte — {omitted} caracteres ocultos para mantener la pestaña receptiva. Usa Copiar para obtener el texto completo.",
   },
   pluginSkill: {
     noDescription: "(sin descripción)",

package/src/lang/fr.ts

@@ -937,6 +937,8 @@ const frMessages = {
     cancel: "Annuler",
     seededByPlugin: "depuis {pkg}",
     seededByPluginTooltip: "Ce message a été généré par le plugin {pkg}, et non envoyé par vous.",
+    truncatedForRender:
+      "Ce message est exceptionnellement long ({total} caractères au total). Seule la première partie est affichée — {omitted} caractères masqués pour garder l'onglet réactif. Utilisez « Copier » pour obtenir le texte complet.",
   },
   pluginSkill: {
     noDescription: "(aucune description)",

package/src/lang/ja.ts

@@ -935,6 +935,8 @@ const jaMessages = {
     cancel: "キャンセル",
     seededByPlugin: "{pkg} から",
     seededByPluginTooltip: "このメッセージは {pkg} プラグインによって作成されたもので、あなたが送信したものではありません。",
+    truncatedForRender:
+      "このメッセージは非常に長いため（全 {total} 文字）、描画のフリーズを防ぐため先頭のみ表示しています（{omitted} 文字を省略）。全文はコピーボタンから取得できます。",
   },
   pluginSkill: {
     noDescription: "(説明なし)",

package/src/lang/ko.ts

@@ -935,6 +935,8 @@ const koMessages = {
     cancel: "취소",
     seededByPlugin: "{pkg}에서",
     seededByPluginTooltip: "이 메시지는 사용자가 보낸 것이 아니라 {pkg} 플러그인에서 작성한 것입니다.",
+    truncatedForRender:
+      "이 메시지는 매우 깁니다(총 {total}자). 탭이 멈추지 않도록 앞부분만 표시됩니다 — {omitted}자 숨김. 전체 원문은 복사 버튼으로 가져올 수 있습니다.",
   },
   pluginSkill: {
     noDescription: "(설명 없음)",

package/src/lang/pt-BR.ts

@@ -936,6 +936,8 @@ const ptBRMessages = {
     cancel: "Cancelar",
     seededByPlugin: "de {pkg}",
     seededByPluginTooltip: "Esta mensagem foi gerada pelo plugin {pkg}, não foi enviada por você.",
+    truncatedForRender:
+      "Esta mensagem é excepcionalmente longa ({total} caracteres no total). Apenas a primeira parte é renderizada — {omitted} caracteres ocultos para manter a aba responsiva. Use Copiar para obter o texto completo.",
   },
   pluginSkill: {
     noDescription: "(sem descrição)",

package/src/lang/zh.ts

@@ -925,6 +925,7 @@ const zhMessages = {
     cancel: "取消",
     seededByPlugin: "来自 {pkg}",
     seededByPluginTooltip: "此消息由 {pkg} 插件生成，并非您发送。",
+    truncatedForRender: "该消息异常长（共 {total} 个字符）。为保持标签页响应，仅渲染开头部分 — 隐藏了 {omitted} 个字符。使用复制按钮获取完整原文。",
   },
   pluginSkill: {
     noDescription: "(无描述)",