mulmoclaude 0.9.0 → 0.9.2

package/server/api/routes/agent.ts

@@ -1,9 +1,11 @@
+import { randomUUID } from "node:crypto";
 import { Router, Request, Response } from "express";
 import { getSessionQuery } from "../../utils/request.js";
 import {
   createSessionMeta,
   backfillFirstUserMessage as backfillMeta,
   backfillOrigin,
+  incrementUserQueryCount,
   readSessionMetaFull,
   readSessionMeta,
   setClaudeSessionId as setClaudeId,
@@ -33,7 +35,14 @@ import { createArgsCache, recordToolEvent } from "../../workspace/tool-trace/ind
 import { API_ROUTES } from "../../../src/config/apiRoutes.js";
 import { EVENT_TYPES } from "../../../src/types/events.js";
 import { isSessionOrigin, SESSION_ORIGINS, type SessionOrigin } from "../../../src/types/session.js";
-import { releaseBackgroundSession } from "../../agent/backgroundSessions.js";
+import {
+  tryReserveBackgroundSession,
+  releaseBackgroundSession,
+  registerCompletionHook,
+  runCompletionHook,
+  MAX_BACKGROUND_SESSIONS,
+  type CompletionHook,
+} from "../../agent/backgroundSessions.js";
 // Imports kept commented (instead of deleted) alongside the
 // publishNotification call in `runPostTurnSideEffects` — see the
 // duplicate-notification comment there for context. (`SESSION_ORIGINS`
@@ -133,6 +142,54 @@ export interface StartChatParams {
 
 export type StartChatResult = { kind: "started"; chatSessionId: string } | { kind: "error"; error: string; status?: number };
 
+/** Outcome of launching a worker session. */
+export type SpawnSystemWorkerResult = { ok: true; chatId: string } | { ok: false; error: string };
+
+// Launch a host-side worker session. `hidden` decides visibility:
+//   - true  → origin `system`: never appears in the session list, runaway-cap
+//             reserved, `finalizeRun` invokes the completion hook + cleans up.
+//             Used for SCHEDULED agent-ingest refreshes (no one is watching).
+//   - false → origin `skill`: a normal visible chat the user can open from
+//             history, no cap, NO completion hook (the user watches it run
+//             directly). Used for a MANUAL Refresh-button refresh so it's
+//             debuggable.
+// Exported so non-MCP host callers (the agent-ingest engine, wired in via
+// `setAgentWorkerRunner`) can spawn one without going through the tool layer.
+export async function spawnSystemWorker(args: {
+  message: string;
+  roleId: string;
+  hidden: boolean;
+  onComplete?: CompletionHook;
+}): Promise<SpawnSystemWorkerResult> {
+  const chatId = randomUUID();
+  const origin: SessionOrigin = args.hidden ? SESSION_ORIGINS.system : SESSION_ORIGINS.skill;
+  // The runaway cap guards hidden workers only — a visible run is user-initiated
+  // and self-limiting. Reserve ATOMICALLY before launching; rolled back below if
+  // the launch fails (otherwise released in `runAgentInBackground`'s finally).
+  if (args.hidden && !tryReserveBackgroundSession(chatId)) {
+    return { ok: false, error: `too many background sessions already in flight (max ${MAX_BACKGROUND_SESSIONS})` };
+  }
+  let result: StartChatResult;
+  try {
+    result = await startChat({ message: args.message, roleId: args.roleId, chatSessionId: chatId, origin });
+  } catch (err) {
+    // `startChat` is normally fire-and-forget, but a synchronous setup failure
+    // can reject — release the reservation so the slot isn't leaked until restart.
+    if (args.hidden) releaseBackgroundSession(chatId);
+    return { ok: false, error: errorMessage(err) };
+  }
+  if (result.kind === "error") {
+    if (args.hidden) releaseBackgroundSession(chatId); // roll back the reservation
+    return { ok: false, error: result.error };
+  }
+  // Register the completion hook AFTER a successful launch (the subprocess can't
+  // finish before this synchronous code returns, so `finalizeRun` won't miss
+  // it). Only hidden (system) sessions run it — `finalizeRun` skips the hook for
+  // visible origins, which take the normal post-turn path instead.
+  if (args.hidden && args.onComplete) registerCompletionHook(chatId, args.onComplete);
+  return { ok: true, chatId };
+}
+
 export async function startChat(params: StartChatParams): Promise<StartChatResult> {
   const { message, roleId, chatSessionId, selectedImageData, attachments, userTimezone } = params;
   // Bridge-only compat: external bridge clients may still populate
@@ -224,6 +281,10 @@ export async function startChat(params: StartChatParams): Promise<StartChatResul
       await backfillOrigin(chatSessionId, validOrigin);
     }
   }
+  // Count this user turn (createSessionMeta seeds no count, so the first
+  // turn bumps undefined→1). Lets the sidebar tell a one-shot apart from
+  // a long conversation.
+  await incrementUserQueryCount(chatSessionId);
 
   // Append user message for this turn
   await appendSessionLine(
@@ -870,6 +931,12 @@ export const _splitSkillAndReplyForTest = splitSkillAndReply;
 //   }
 // }
 
+/** A stale `--resume` failure we can recover from by retrying without it: an
+ *  error event carrying a stale-session message, while failover budget remains. */
+function isRecoverableStaleSession(event: { type: string; message?: unknown }, failoverAttemptsRemaining: number): boolean {
+  return failoverAttemptsRemaining > 0 && event.type === EVENT_TYPES.error && typeof event.message === "string" && isStaleSessionError(event.message);
+}
+
 async function runAgentInBackground(params: BackgroundRunParams): Promise<void> {
   const { decoratedMessage, role, chatSessionId, claudeSessionId, abortSignal, resultsFilePath, requestStartedAt, toolArgsCache, attachments, userTimezone } =
     params;
@@ -908,7 +975,7 @@ async function runAgentInBackground(params: BackgroundRunParams): Promise<void>
         attachments,
         userTimezone,
       })) {
-        if (failoverAttemptsRemaining > 0 && event.type === EVENT_TYPES.error && typeof event.message === "string" && isStaleSessionError(event.message)) {
+        if (isRecoverableStaleSession(event, failoverAttemptsRemaining)) {
           // Swallow the error — we're about to recover. `break`
           // abandons the current generator; since the event is only
           // yielded after the CLI has already exited non-zero, the
@@ -918,6 +985,12 @@ async function runAgentInBackground(params: BackgroundRunParams): Promise<void>
           failoverAttemptsRemaining--;
           break;
         }
+        // A yielded error event (non-zero Claude exit, missing binary, a tool
+        // surfacing an error) is a real failure even though the generator
+        // didn't throw — record it so `finalizeRun`'s hidden-worker cleanup and
+        // the agent-ingest completion hook see `didError`. The stale-session
+        // failover above returns earlier, so a recoverable id doesn't count.
+        if (event.type === EVENT_TYPES.error) didError = true;
         await handleAgentEvent(event, eventCtx);
       }
       if (!staleSessionDetected) break;
@@ -978,6 +1051,10 @@ async function finalizeRun(chatSessionId: string, origin: SessionOrigin | undefi
     // plumbing and pollute wiki backlinks), and clean up its files on
     // success — keep them on error so a failed worker stays inspectable.
     releaseBackgroundSession(chatSessionId);
+    // Fire any one-shot completion hook (e.g. agent-ingest failure tracking)
+    // AFTER the slot is freed, BEFORE files are cleaned up. Best-effort —
+    // a throwing hook is logged, never propagated.
+    await runCompletionHook(chatSessionId, { didError }).catch(logBackgroundError("background-session-completion-hook"));
     if (!didError) {
       await deleteSessionFiles(chatSessionId).catch(logBackgroundError("background-session-cleanup"));
     }

package/server/api/routes/collections.ts

@@ -10,7 +10,7 @@
 
 import { Router, Request, Response, NextFunction } from "express";
 import { API_ROUTES } from "../../../src/config/apiRoutes.js";
-import { actionVisible } from "@mulmoclaude/collection-plugin";
+import { actionVisible } from "@mulmoclaude/core/collection";
 import {
   discoverCollections,
   generateItemId,
@@ -23,8 +23,10 @@ import {
   readItem,
   readSkillTemplate,
   readCustomViewHtml,
+  readCustomViewI18n,
   buildActionSeedPrompt,
   buildCollectionActionSeedPrompt,
+  promptPathsFor,
   resolveCreateItemId,
   toDetail,
   toSummary,
@@ -44,7 +46,7 @@ import { badRequest, notFound, conflict, forbidden, serverError } from "../../ut
 import { errorMessage } from "../../utils/errors.js";
 import { log } from "../../system/logger/index.js";
 import { workspacePath } from "../../workspace/workspace.js";
-import { refreshOne } from "../../workspace/feeds/index.js";
+import { refreshOne } from "@mulmoclaude/core/feeds/server";
 import { manageCollection } from "../../agent/mcp-tools/manageCollection.js";
 import { clampCapabilities, mintViewToken, requireViewToken, type ViewCapability } from "../auth/viewToken.js";
 
@@ -279,6 +281,13 @@ interface RefreshResponse {
   refreshed: true;
   written: number;
   errors: string[];
+  /** True when an agent-ingest refresh dispatched a worker (fire-and-forget):
+   *  records update asynchronously, so the client shows a note rather than a
+   *  written count. */
+  dispatched?: boolean;
+  /** The visible worker's chat session id (manual Refresh only) so the client
+   *  can open it to watch the refresh run. */
+  chatId?: string;
 }
 
 // Re-run a feed collection's retrieval now. Generic over kind — the
@@ -296,9 +305,12 @@ router.post(API_ROUTES.collections.refresh, async (req: Request<{ slug: string }
     return;
   }
   try {
-    const result = await refreshOne(workspacePath, collection);
-    log.info("collections", "feed refreshed via collection route", { slug: collection.slug, written: result.written });
-    res.json({ refreshed: true, written: result.written, errors: result.errors });
+    // Manual Refresh button → run a VISIBLE worker (hidden:false) so the user
+    // can open the session and watch/debug it. Scheduled refreshes (the
+    // `refreshDue` loop) stay hidden. Declarative feeds ignore the flag.
+    const result = await refreshOne(workspacePath, collection, { hidden: false });
+    log.info("collections", "feed refreshed via collection route", { slug: collection.slug, written: result.written, dispatched: result.dispatched ?? false });
+    res.json({ refreshed: true, written: result.written, errors: result.errors, dispatched: result.dispatched, chatId: result.chatId });
   } catch (err) {
     log.warn("collections", "feed refresh failed", { slug: collection.slug, error: errorMessage(err) });
     serverError(res, errorMessage(err));
@@ -340,7 +352,7 @@ router.post(API_ROUTES.collections.itemAction, async (req: Request<{ slug: strin
       return;
     }
     log.info("collections", "action seed built", { slug: collection.slug, itemId: req.params.itemId, actionId: action.id });
-    res.json({ prompt: buildActionSeedPrompt(record, template), role: action.role });
+    res.json({ prompt: buildActionSeedPrompt(record, template, promptPathsFor(collection, workspacePath)), role: action.role });
   } catch (err) {
     log.warn("collections", "action seed failed", {
       slug: collection.slug,
@@ -361,7 +373,7 @@ async function buildCollectionActionSeed(collection: LoadedCollection, action: C
   if (template === null) return null;
   const items = await listItems(collection.dataDir);
   log.info("collections", "collection action seed built", { slug: collection.slug, actionId: action.id, items: items.length });
-  return { prompt: buildCollectionActionSeedPrompt(items, collection.schema, template), role: action.role };
+  return { prompt: buildCollectionActionSeedPrompt(items, collection.schema, template, promptPathsFor(collection, workspacePath)), role: action.role };
 }
 
 // Like the per-record route but with no `itemId`: there is no record to read or
@@ -471,6 +483,47 @@ router.get(API_ROUTES.collections.viewFile, async (req: Request<{ slug: string }
   }
 });
 
+// Translation dict for ONE custom view, locale-filtered server-side. The
+// client passes its active app locale; the host returns only that locale's
+// strings (fallback `"en"`, then `{}`). The view never sees other locales'
+// strings — the host is the picker, the iframe is the consumer. Empty dict
+// + `locale: ""` when the view has no `i18n` declared or the file is
+// absent / malformed; the iframe-side `__MC_VIEW.t(key)` falls back to the
+// key, so an i18n-less view keeps working unchanged.
+router.get(API_ROUTES.collections.viewI18n, async (req: Request<{ slug: string }>, res: Response) => {
+  try {
+    const { slug } = req.params;
+    const viewId = typeof req.query.id === "string" ? req.query.id : "";
+    const locale = typeof req.query.locale === "string" ? req.query.locale : "";
+    const collection = await loadCollection(slug);
+    if (!collection) {
+      notFound(res, `collection '${slug}' not found`);
+      return;
+    }
+    const view = (collection.schema.views ?? []).find((entry) => entry.id === viewId);
+    if (!view) {
+      notFound(res, `custom view '${viewId}' not found on collection '${slug}'`);
+      return;
+    }
+    if (!view.i18n) {
+      // The view declared no translation file — return the empty contract so
+      // the client doesn't have to special-case "no i18n" with a different
+      // shape. `t(key)` will just echo the key.
+      res.json({ locale: "", dict: {} });
+      return;
+    }
+    const result = await readCustomViewI18n(collection, view.i18n, locale);
+    res.json(result);
+  } catch (err) {
+    // Strip CR/LF before logging — `loadCollection` already rejects malformed
+    // slugs above (so this path always has a safe slug in practice), but
+    // belt-and-suspenders for log-injection / forged-line resistance per
+    // CodeRabbit review on #1842.
+    log.warn("collections", "view-i18n read failed", { slug: req.params.slug.replace(/[\r\n]/g, " "), error: errorMessage(err) });
+    serverError(res, errorMessage(err));
+  }
+});
+
 // Mint a scoped token for a custom view. Behind the global bearer (only the
 // real frontend can mint); clamps requested caps to what the view declared
 // so a `read`-only view can never obtain a `write` token.

package/server/api/routes/collectionsRegistry.ts

@@ -0,0 +1,113 @@
+// Read endpoints for the curated collection registries (Discover tab). Backs
+// `GET /api/collections-registry` by server-fetching every configured registry's
+// published index.json (official receptron/mulmoclaude-collections plus any
+// user-added entries from `config/collections-registries.json`) and returning
+// merged entries. The host never exposes upstream URLs to the client; it proxies
+// + caches each one.
+//
+// The registry import/export engine lives in @mulmoclaude/core/collection/registry,
+// wired to this workspace through the shared `configureCollectionHost` binding (see
+// server/workspace/collections/configure.ts). This route is thin host glue.
+
+import { Router, Request, Response } from "express";
+
+import type { RegistryEntry, RegistryListResponse, RegistryImportResponse } from "@mulmoclaude/core/collection/registry";
+import { listRegistry, previewCollection, importRegistry, performExport } from "@mulmoclaude/core/collection/registry/server";
+
+import { API_ROUTES } from "../../../src/config/apiRoutes.js";
+import { badRequest } from "../../utils/httpError.js";
+import { workspacePath } from "../../workspace/workspace.js";
+
+const router = Router();
+
+interface ErrorResponse {
+  error: string;
+}
+
+router.get(API_ROUTES.collectionsRegistry.list, async (_req: Request, res: Response<RegistryListResponse | ErrorResponse>) => {
+  res.json(await listRegistry());
+});
+
+interface RegistryPreviewResponse {
+  entry: RegistryEntry;
+  schema: Record<string, unknown>;
+  meta: Record<string, unknown>;
+}
+
+router.get(API_ROUTES.collectionsRegistry.preview, async (req: Request, res: Response<RegistryPreviewResponse | ErrorResponse>) => {
+  const author = typeof req.query.author === "string" ? req.query.author : "";
+  const slug = typeof req.query.slug === "string" ? req.query.slug : "";
+  const registry = typeof req.query.registry === "string" && req.query.registry ? req.query.registry : null;
+  if (!author || !slug) {
+    badRequest(res, "author and slug query params are required");
+    return;
+  }
+  const result = await previewCollection(author, slug, registry);
+  if (!result.ok) {
+    res.status(result.status).json({ error: result.error });
+    return;
+  }
+  res.json({ entry: result.entry, schema: result.schema, meta: result.meta });
+});
+
+interface ImportBody {
+  author?: unknown;
+  slug?: unknown;
+  registry?: unknown;
+}
+
+router.post(API_ROUTES.collectionsRegistry.import, async (req: Request<object, unknown, ImportBody>, res: Response<RegistryImportResponse | ErrorResponse>) => {
+  const author = typeof req.body.author === "string" ? req.body.author : "";
+  const slug = typeof req.body.slug === "string" ? req.body.slug : "";
+  const registry = typeof req.body.registry === "string" && req.body.registry ? req.body.registry : null;
+  if (!author || !slug) {
+    badRequest(res, "author and slug are required");
+    return;
+  }
+  const result = await importRegistry(author, slug, workspacePath, registry);
+  if (!result.ok) {
+    res.status(result.status).json({ error: result.error });
+    return;
+  }
+  res.json(result.response);
+});
+
+interface ExportBody {
+  slug?: unknown;
+  author?: unknown;
+  license?: unknown;
+  includeSeed?: unknown;
+}
+
+interface ExportResponse {
+  outputPath: string;
+  fileCount: number;
+  seedCount: number;
+  seedSkipped: number;
+  warnings: string[];
+}
+
+router.post(API_ROUTES.collectionsRegistry.export, async (req: Request<object, unknown, ExportBody>, res: Response<ExportResponse | ErrorResponse>) => {
+  const slug = typeof req.body.slug === "string" ? req.body.slug : "";
+  const author = typeof req.body.author === "string" ? req.body.author : "";
+  if (!slug || !author) {
+    badRequest(res, "slug and author are required");
+    return;
+  }
+  const license = typeof req.body.license === "string" && req.body.license ? req.body.license : "MIT";
+  const includeSeed = req.body.includeSeed === true;
+  const result = await performExport(slug, { author, license, includeSeed }, workspacePath);
+  if (!result.ok) {
+    res.status(result.status).json({ error: result.error });
+    return;
+  }
+  res.json({
+    outputPath: result.outputPath,
+    fileCount: result.fileCount,
+    seedCount: result.seedCount,
+    seedSkipped: result.seedSkipped,
+    warnings: result.warnings,
+  });
+});
+
+export default router;

package/server/api/routes/dashboard.ts

@@ -0,0 +1,47 @@
+// HTTP route for the dashboard layout (per-tile view mode + tile order
+// for the favorites grid).
+//
+//   GET /api/dashboard  → { tiles }
+//   PUT /api/dashboard  → replace the full list → { tiles }
+//
+// The client owns ordering / view mode and sends the whole array; the
+// server normalises (non-empty slug, dedupe on slug, optional string
+// viewMode) before persisting. A single replace-endpoint mirrors the
+// shortcuts route.
+
+import { Router, Request, Response } from "express";
+import { API_ROUTES } from "../../../src/config/apiRoutes.js";
+import type { DashboardFile } from "../../../src/types/dashboard.js";
+import { readDashboard, writeDashboard } from "../../utils/files/dashboard-io.js";
+import { errorMessage } from "../../utils/errors.js";
+import { badRequest, serverError } from "../../utils/httpError.js";
+import { log } from "../../system/logger/index.js";
+
+const router = Router();
+
+type DashboardResponse = DashboardFile;
+
+router.get(API_ROUTES.dashboard, async (_req: Request, res: Response<DashboardResponse>) => {
+  try {
+    res.json(await readDashboard());
+  } catch (err) {
+    log.warn("dashboard", "read failed", { error: errorMessage(err) });
+    serverError(res, errorMessage(err));
+  }
+});
+
+router.put(API_ROUTES.dashboard, async (req: Request, res: Response<DashboardResponse>) => {
+  const { tiles, rowHeights } = req.body ?? {};
+  if (!Array.isArray(tiles)) {
+    badRequest(res, "Request body must be { tiles: DashboardTile[], rowHeights?: number[] }");
+    return;
+  }
+  try {
+    res.json(await writeDashboard({ tiles, rowHeights }));
+  } catch (err) {
+    log.warn("dashboard", "write failed", { error: errorMessage(err) });
+    serverError(res, errorMessage(err));
+  }
+});
+
+export default router;

package/server/api/routes/feeds.ts

@@ -9,7 +9,7 @@
 import { Router, Request, Response } from "express";
 import { workspacePath } from "../../workspace/workspace.js";
 import { API_ROUTES } from "../../../src/config/apiRoutes.js";
-import { listFeeds, readFeedState, removeFeed } from "../../workspace/feeds/index.js";
+import { listFeeds, readFeedState, removeFeed } from "@mulmoclaude/core/feeds/server";
 import { errorMessage } from "../../utils/errors.js";
 import { serverError } from "../../utils/httpError.js";
 import { log } from "../../system/logger/index.js";
@@ -33,7 +33,7 @@ router.get(API_ROUTES.feeds.list, async (_req: Request, res: Response<FeedsListR
     const feeds = await listFeeds(workspacePath);
     const summaries: FeedSummary[] = [];
     for (const feed of feeds) {
-      const state = await readFeedState(workspacePath, feed.slug);
+      const state = await readFeedState(workspacePath, feed);
       const { ingest } = feed.schema;
       summaries.push({
         slug: feed.slug,

package/server/api/routes/files.ts

@@ -753,8 +753,7 @@ router.get(API_ROUTES.files.content, (req: Request<object, unknown, unknown, Pat
 });
 
 type PutContentValidation =
-  | { ok: true; relPath: string; content: string; bytes: number }
-  | { ok: false; logMsg: string; logExtra?: Record<string, unknown>; message: string };
+  { ok: true; relPath: string; content: string; bytes: number } | { ok: false; logMsg: string; logExtra?: Record<string, unknown>; message: string };
 
 // Runtime-shape gate for PUT /api/files/content's body. Returns either
 // the narrowed inputs + their byte length (computed once and reused

package/server/api/routes/pdf.ts

@@ -19,7 +19,9 @@ const router = Router();
 
 const MARKDOWN_CSS = `
   body {
-    font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial, sans-serif;
+    font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial,
+                 "Hiragino Sans", "Hiragino Kaku Gothic ProN", "Yu Gothic", Meiryo,
+                 "Noto Sans CJK JP", "Noto Sans JP", sans-serif;
     font-size: 13px;
     line-height: 1.6;
     color: #1f2937;
@@ -246,7 +248,7 @@ async function renderPdf(fullHtml: string, format: "Letter" | "A4" = "Letter"):
   }
 }
 
-async function renderMarpPdf(markdown: string, baseDir?: string): Promise<Buffer> {
+async function renderMarpHtml(markdown: string, baseDir?: string): Promise<{ fullHtml: string; slideWidth: number; slideHeight: number }> {
   // Shared render core (@mulmoclaude/markdown-plugin) — the MarpView
   // preview and every host's PDF export use the same Marp config + theme
   // registration + custom-size bridging, so they can't drift. Twemoji
@@ -273,7 +275,28 @@ div.marpit > svg > foreignObject > section img:not([data-marp-twemoji]) {
   max-height: 60cqh;
   object-fit: contain;
 }
+/* CJK font fallback for headless-Chromium PDF render (#1821). The Marp
+   default theme's font-family is Latin-only, so puppeteer renders
+   Japanese / Chinese / Korean glyphs as tofu on hosts without a CJK
+   font. Append a CJK stack on the section root — macOS / Windows hit
+   Hiragino / Yu Gothic / Meiryo, Linux hits Noto Sans CJK (must be
+   installed on the host). Scoped to the section selector only (no
+   descendant combinator) so the cascade still lets the theme's
+   per-element fonts win — code and pre keep their monospace stack
+   and are not silently replaced with this sans-serif chain. Code
+   blocks containing CJK still fall through to the OS's monospace
+   CJK substitution (e.g. macOS Osaka / Linux Noto Sans Mono CJK). */
+div.marpit > svg > foreignObject > section {
+  font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial,
+               "Hiragino Sans", "Hiragino Kaku Gothic ProN", "Yu Gothic", Meiryo,
+               "Noto Sans CJK JP", "Noto Sans JP", sans-serif;
+}
 </style></head><body>${inlinedHtml}</body></html>`;
+  return { fullHtml, slideWidth, slideHeight };
+}
+
+async function renderMarpPdf(markdown: string, baseDir?: string): Promise<Buffer> {
+  const { fullHtml, slideWidth, slideHeight } = await renderMarpHtml(markdown, baseDir);
   const browser = await puppeteer.launch({ headless: true });
   try {
     const page = await browser.newPage();
@@ -302,18 +325,34 @@ export interface RenderMarkdownPdfOptions {
   stripFrontmatter?: boolean;
 }
 
+export interface RenderMarkdownHtmlOptions {
+  markdown: string;
+  /** Render via Marp (slide deck) instead of the `marked` pipeline. */
+  marp?: boolean;
+  /** Workspace-relative source dir for resolving relative `<img>` refs. */
+  baseDir?: string;
+  stripFrontmatter?: boolean;
+}
+
+/** Markdown (or a Marp deck) → a self-contained HTML string: CSS inlined
+ *  and local images embedded as data URIs. Shared by the PDF render
+ *  (`renderMarkdownPdf`) and the zip share (`packMarkdownZip`) so the two
+ *  can never drift. */
+export async function renderMarkdownHtml(options: RenderMarkdownHtmlOptions): Promise<string> {
+  const { markdown, marp = false, baseDir, stripFrontmatter = false } = options;
+  if (marp) return (await renderMarpHtml(markdown, baseDir)).fullHtml;
+  const source = stripFrontmatter ? parseFrontmatter(markdown).body : markdown;
+  return wrapHtml(inlineImages(await marked.parse(source), { sourceDir: baseDir }), MARKDOWN_CSS);
+}
+
 /** Render markdown (or a Marp deck) to a PDF buffer. The single code
  *  path behind both `POST /api/pdf/markdown` and the markdown plugin's
  *  `exportPdf` host capability (`server/plugins/markdown-builtin.ts`),
  *  so the HTTP route and the plugin dispatch can never drift. */
 export async function renderMarkdownPdf(options: RenderMarkdownPdfOptions): Promise<Buffer> {
-  const { markdown, marp = false, baseDir, format = "Letter", stripFrontmatter = false } = options;
-  if (marp) {
-    return renderMarpPdf(markdown, baseDir);
-  }
-  const source = stripFrontmatter ? parseFrontmatter(markdown).body : markdown;
-  const html = inlineImages(await marked.parse(source), { sourceDir: baseDir });
-  return renderPdf(wrapHtml(html, MARKDOWN_CSS), format);
+  const { markdown, marp = false, baseDir, format = "Letter" } = options;
+  if (marp) return renderMarpPdf(markdown, baseDir);
+  return renderPdf(await renderMarkdownHtml(options), format);
 }
 
 function sendPdf(res: Response, buffer: Buffer, filename: string): void {

package/server/api/routes/plugins.ts

@@ -6,7 +6,7 @@ import { executeForm } from "../../../src/plugins/presentForm/plugin.js";
 import { executePresentCollection } from "../../../src/plugins/presentCollection/plugin.js";
 import type { PresentCollectionArgs } from "../../../src/plugins/presentCollection/types.js";
 import { loadCollection, validateCollectionRecords } from "../../workspace/collections/index.js";
-import { defangForPrompt } from "@mulmoclaude/collection-plugin";
+import { defangForPrompt } from "@mulmoclaude/core/collection";
 import { executeOpenCanvas } from "../../../src/plugins/canvas/definition.js";
 import { executePresent3D } from "@gui-chat-plugin/present3d";
 import { executeMapControl } from "@gui-chat-plugin/google-map";
@@ -259,7 +259,7 @@ bindRoute(
 // the LLM reads) so the model — which is told to call presentCollection
 // after every write — fixes the file instead of losing the record.
 // `defangForPrompt` (shared with the client Repair button via
-// `@mulmoclaude/collection-plugin`) strips markup / escape sequences, collapses
+// `@mulmoclaude/core/collection`) strips markup / escape sequences, collapses
 // whitespace, and clips — so record-controlled text in a validation issue (a
 // filename, id, or enum value) can't be read as instructions once appended to
 // the LLM-facing result.

package/server/api/routes/remoteHost.ts

@@ -0,0 +1,55 @@
+// HTTP routes for the remote-host runner (phase 1).
+//
+//   POST /api/remote-host/connect     { idToken }  → { status }
+//   POST /api/remote-host/disconnect               → { status }
+//   GET  /api/remote-host/status                   → { status }
+//
+// connect signs in to Firebase as the user with the browser-minted Google ID
+// token and starts the host runner (command loop + presence heartbeat);
+// disconnect stops it and signs out. Bearer-guarded like every other /api route
+// (the browser's apiPost attaches the token); the idToken is a secret carried
+// in the POST body over the loopback listener only — never logged.
+import { Router, Request, Response } from "express";
+
+import { API_ROUTES } from "../../../src/config/apiRoutes.js";
+import { connect, disconnect, status, type RemoteHostStatus } from "../../remoteHost/index.js";
+import { errorMessage } from "../../utils/errors.js";
+import { badRequest, serverError } from "../../utils/httpError.js";
+import { log } from "../../system/logger/index.js";
+
+const PREFIX = "remote-host";
+const router = Router();
+
+interface StatusResponse {
+  status: RemoteHostStatus;
+}
+
+router.post(API_ROUTES.remoteHost.connect, async (req: Request, res: Response<StatusResponse>) => {
+  const idToken = typeof req.body?.idToken === "string" ? req.body.idToken.trim() : "";
+  if (!idToken) {
+    badRequest(res, "Request body must be { idToken: string }");
+    return;
+  }
+  try {
+    res.json({ status: await connect(idToken) });
+  } catch (err) {
+    // Never include idToken in the message.
+    log.warn(PREFIX, "connect failed", { error: errorMessage(err) });
+    serverError(res, errorMessage(err, "remote-host connect failed"));
+  }
+});
+
+router.post(API_ROUTES.remoteHost.disconnect, async (_req: Request, res: Response<StatusResponse>) => {
+  try {
+    res.json({ status: await disconnect() });
+  } catch (err) {
+    log.warn(PREFIX, "disconnect failed", { error: errorMessage(err) });
+    serverError(res, errorMessage(err, "remote-host disconnect failed"));
+  }
+});
+
+router.get(API_ROUTES.remoteHost.status, (_req: Request, res: Response<StatusResponse>) => {
+  res.json({ status: status() });
+});
+
+export default router;