pmx-canvas 0.3.2 → 0.3.3

package/dist/types/cli/daemon.d.ts

@@ -17,6 +17,8 @@ export declare function removePidFile(path: string): void;
 export interface HealthStatus {
     responsive: boolean;
     workspace: string | null;
+    /** The serving process's own pid, self-reported by /health (0.3.3+ servers). */
+    pid: number | null;
 }
 export declare function readHealthStatus(url: string): Promise<HealthStatus>;
 export declare function isHealthy(url: string): Promise<boolean>;
@@ -65,6 +67,21 @@ export declare function startDaemonMode(options: DaemonPaths & {
     waitMs: number;
     entry: string;
 }): Promise<void>;
+/**
+ * Resolve the pid story `serve status` reports. The AUTHORITATIVE pid is the
+ * serving process's self-reported /health pid: the pid file can go stale when
+ * something other than `serve --daemon` (re)spawned the server on this port —
+ * e.g. a host adapter respawn (0.3.2 report Finding P). Reporting the dead
+ * file pid as `pid` while `running` was true made agents read a contradiction
+ * (`running: true, pidRunning: false`); report the real listener instead and
+ * mark the file explicitly stale. Pre-0.3.3 servers don't self-report a pid —
+ * for those, fall back to the pid-file view unchanged.
+ */
+export declare function resolveDaemonPidView(pidFilePid: number | null, pidFilePidRunning: boolean, health: HealthStatus): {
+    pid: number | null;
+    pidRunning: boolean;
+    pidFileStale: boolean;
+};
 export declare function showServeStatus(options: DaemonPaths & {
     entry: string;
 }): Promise<void>;

package/dist/types/client/nodes/ExtAppFrame.d.ts

@@ -38,6 +38,19 @@ export declare function resolveExtAppDisplayModeRequest(requestedMode: DisplayMo
 export declare function sendExtAppBootstrapState(bridge: ExtAppBridgeNotifications, toolInput: Record<string, unknown>, toolResult: CallToolResult | undefined): Promise<void>;
 export declare function resolveExtAppSandbox(value: unknown): string;
 export declare function buildExtAppAxBridgeScript(axToken: string, nodeId: string): string;
+/**
+ * Boot beacon injected into EVERY ext-app document (not gated on AX): posts one
+ * parent message the moment the iframe's scripts execute. This is the liveness
+ * signal the WebKit never-booted watchdog keys on — it distinguishes an app
+ * that is alive but boots via the 1200ms bootstrap fallback (e.g. a non-SDK
+ * widget that never sends ui/notifications/initialized) from a dead window
+ * whose scripts never ran. Without it, the watchdog treated every
+ * fallback-booted app as never-booted and remounted it up to the attempt cap —
+ * a reboot/flicker loop for exactly the apps the fallback exists to support
+ * (0.3.2 pre-release review). The token scopes the message to this component;
+ * the host also checks event.source against the live iframe.
+ */
+export declare function buildExtAppBootBeaconScript(frameToken: string, nodeId: string): string;
 export declare function injectExtAppAxBridgeScript(html: string, axBridgeScript: string): string;
 export declare function resolveExtAppContainerDimensions(target: ExtAppHostDimensionsTarget | null | undefined, fallback: {
     width: number;

package/docs/RELEASE.md

@@ -124,6 +124,17 @@ If this is the first release from your machine, run `bunx npm login`
 once so Bun can reuse your npm credentials. CI does not need this —
 it uses `NPM_TOKEN` directly.
 
+## Sync consumer skill mirrors
+
+Every release since 0.3.0 has been retested against **stale** skill mirrors:
+consumer workspaces (e.g. `personalclaude`) carry copies of the pmx-canvas
+skill under `.github/`, `.codex/`, `.claude/`, and `.agents/`, and testers
+repeatedly had to sync them mid-cycle before results were trustworthy. After
+publishing, update the installed package in the consumer workspace and re-sync
+its four mirrors from
+`<global npm root>/pmx-canvas/skills/pmx-canvas/` so the first test pass runs
+against the released skill, not the previous version's guidance.
+
 ## GitHub release
 
 After `npm publish` succeeds:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pmx-canvas",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "description": "Spatial canvas workbench for coding agents — infinite 2D canvas with agent-native CLI, MCP integration, nodes, edges, file watching, and snapshots",
   "type": "module",
   "main": "./src/server/index.ts",

package/skills/pmx-canvas/SKILL.md

@@ -217,14 +217,17 @@ Prefer `canvas_query { action: "search" }` over parsing the full layout.
   loads (e.g. the GitHub Copilot app's embedded WKWebView) can render as a black tile — a host
   compositor paint race on the nested iframe, **not** a broken node (the session is healthy and
   `sessionStatus` is `ready`; it renders fine in Chrome, the Codex browser, and for nodes created
-  live after the panel hydrates). Under WebKit the canvas auto-recovers: after boot, each
-  present-at-load ext-app is remounted through a **serialized, boot-aware queue** (one app at a
-  time, each waiting for the previous app's handshake + scene replay), with a watchdog retry for
-  iframes that never boot — so multi-app boards converge to painted tiles within a few seconds of
-  panel load. In rare cases a tile can still end up black (compositing success is not observable
-  from page JS, so retries are bounded); recovery is deterministic: **expand-then-close** the
-  black tile (forces a fresh mount in the fullscreen overlay, which always paints), or open the
-  workbench in a normal browser (Chrome). Do not diagnose a healthy app session as a broken node.
+  live after the panel hydrates). Under WebKit the canvas ATTEMPTS auto-recovery: after boot,
+  each present-at-load ext-app is remounted through a serialized, boot-aware queue (one app at a
+  time), with a watchdog retry for iframes that never boot and a re-arm when a panel that loaded
+  hidden becomes visible. Treat the auto-recovery as best-effort, NOT guaranteed — the 0.3.2
+  Copilot-host report shows tiles can still come up black in real WKWebView panels (compositing
+  success is not observable from page JS, so retries are bounded). Keep the cautionary behavior:
+  recovery is deterministic via **expand-then-close** of the black tile (forces a fresh mount in
+  the fullscreen overlay, which always paints), or open the workbench in a normal browser
+  (Chrome). Do not diagnose a healthy app session as a broken node. When reporting a black tile,
+  fetch `GET /api/canvas/debug/ext-app-recovery` from the daemon and attach the trace — it shows
+  what the recovery queue actually did in that panel.
 - Graph and json-render standalone surfaces use `display=site` and fill the browser viewport, and
   reflow on a live window resize in a normal browser. Some single-tab host browsers (e.g. the
   Codex in-app browser) don't deliver live-resize events, so a resized standalone chart can look

package/src/cli/daemon.ts

@@ -88,20 +88,26 @@ export function removePidFile(path: string): void {
 export interface HealthStatus {
   responsive: boolean;
   workspace: string | null;
+  /** The serving process's own pid, self-reported by /health (0.3.3+ servers). */
+  pid: number | null;
 }
 
 export async function readHealthStatus(url: string): Promise<HealthStatus> {
   try {
     const response = await fetch(url);
-    if (!response.ok) return { responsive: false, workspace: null };
+    if (!response.ok) return { responsive: false, workspace: null, pid: null };
     const payload = (await response.json().catch(() => null)) as unknown;
     const workspace =
       payload && typeof payload === 'object' && 'workspace' in payload && typeof payload.workspace === 'string'
         ? payload.workspace
         : null;
-    return { responsive: true, workspace };
+    const pid =
+      payload && typeof payload === 'object' && 'pid' in payload && typeof payload.pid === 'number'
+        ? payload.pid
+        : null;
+    return { responsive: true, workspace, pid };
   } catch {
-    return { responsive: false, workspace: null };
+    return { responsive: false, workspace: null, pid: null };
   }
 }
 
@@ -335,17 +341,41 @@ export async function startDaemonMode(
   process.exit(0);
 }
 
+/**
+ * Resolve the pid story `serve status` reports. The AUTHORITATIVE pid is the
+ * serving process's self-reported /health pid: the pid file can go stale when
+ * something other than `serve --daemon` (re)spawned the server on this port —
+ * e.g. a host adapter respawn (0.3.2 report Finding P). Reporting the dead
+ * file pid as `pid` while `running` was true made agents read a contradiction
+ * (`running: true, pidRunning: false`); report the real listener instead and
+ * mark the file explicitly stale. Pre-0.3.3 servers don't self-report a pid —
+ * for those, fall back to the pid-file view unchanged.
+ */
+export function resolveDaemonPidView(
+  pidFilePid: number | null,
+  pidFilePidRunning: boolean,
+  health: HealthStatus,
+): { pid: number | null; pidRunning: boolean; pidFileStale: boolean } {
+  const authoritative = health.responsive && health.pid !== null;
+  return {
+    pid: authoritative ? health.pid : pidFilePid,
+    pidRunning: authoritative ? true : pidFilePidRunning,
+    pidFileStale: pidFilePid !== null && !pidFilePidRunning && (!health.responsive || health.pid !== pidFilePid),
+  };
+}
+
 export async function showServeStatus(options: DaemonPaths & { entry: string }): Promise<void> {
   const healthUrl = `http://localhost:${options.port}/health`;
   const url = `http://localhost:${options.port}/workbench`;
-  const pid = readPidFile(options.pidFile);
-  const pidRunning = pid ? isOwnDaemonProcess(pid, options.entry) : false;
+  const pidFilePid = readPidFile(options.pidFile);
+  const pidFilePidRunning = pidFilePid ? isOwnDaemonProcess(pidFilePid, options.entry) : false;
   const health = await readHealthStatus(healthUrl);
   const responsive = health.responsive;
-  const running = responsive || pidRunning;
+  const running = responsive || pidFilePidRunning;
+  const { pid, pidRunning, pidFileStale } = resolveDaemonPidView(pidFilePid, pidFilePidRunning, health);
   // Clean up a stale pid file, but never a concurrent starter's fresh empty
   // spawn lock (that would let a racing `serve --daemon` double-spawn).
-  if (!running && existsSync(options.pidFile) && !pidRunning && !isFreshEmptyLock(options.pidFile)) {
+  if (!running && existsSync(options.pidFile) && !pidFilePidRunning && !isFreshEmptyLock(options.pidFile)) {
     removePidFile(options.pidFile);
   }
 
@@ -357,6 +387,8 @@ export async function showServeStatus(options: DaemonPaths & { entry: string }):
     workspace: health.workspace,
     pid,
     pidRunning,
+    pidFilePid,
+    pidFileStale,
     url,
     healthUrl,
     logFile: options.logFile,

package/src/client/nodes/ExtAppFrame.tsx

@@ -92,6 +92,33 @@ export function extAppRecoveryLog(nodeId: string, event: string): void {
   const host = window as unknown as { __PMX_EXTAPP_LOG?: Array<{ t: number; nodeId: string; event: string }> };
   host.__PMX_EXTAPP_LOG ??= [];
   if (host.__PMX_EXTAPP_LOG.length < 500) host.__PMX_EXTAPP_LOG.push({ t: Date.now(), nodeId, event });
+  queueExtAppRecoveryReport({ t: Date.now(), nodeId, event });
+}
+
+// Mirror the recovery trail to the daemon (batched, fire-and-forget) so a host
+// panel without devtools access — the Copilot WKWebView, exactly where the
+// black tiles happen — still yields an actionable trace: agents read it back
+// via GET /api/canvas/debug/ext-app-recovery (0.3.2 report Finding N).
+let extAppReportQueue: Array<{ t: number; nodeId: string; event: string; visibility?: string }> = [];
+let extAppReportTimer: ReturnType<typeof setTimeout> | null = null;
+function queueExtAppRecoveryReport(entry: { t: number; nodeId: string; event: string }): void {
+  extAppReportQueue.push({
+    ...entry,
+    ...(typeof document !== 'undefined' ? { visibility: document.visibilityState } : {}),
+  });
+  if (extAppReportTimer) return;
+  extAppReportTimer = setTimeout(() => {
+    extAppReportTimer = null;
+    const entries = extAppReportQueue.splice(0);
+    if (entries.length === 0) return;
+    void fetch('/api/canvas/debug/ext-app-recovery', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ entries }),
+    }).catch(() => {
+      // Diagnostics only — never let reporting failures affect recovery.
+    });
+  }, 1500);
 }
 
 let webkitRemountChain: Promise<void> = Promise.resolve();
@@ -204,6 +231,24 @@ export function buildExtAppAxBridgeScript(axToken: string, nodeId: string): stri
 </script>`;
 }
 
+/**
+ * Boot beacon injected into EVERY ext-app document (not gated on AX): posts one
+ * parent message the moment the iframe's scripts execute. This is the liveness
+ * signal the WebKit never-booted watchdog keys on — it distinguishes an app
+ * that is alive but boots via the 1200ms bootstrap fallback (e.g. a non-SDK
+ * widget that never sends ui/notifications/initialized) from a dead window
+ * whose scripts never ran. Without it, the watchdog treated every
+ * fallback-booted app as never-booted and remounted it up to the attempt cap —
+ * a reboot/flicker loop for exactly the apps the fallback exists to support
+ * (0.3.2 pre-release review). The token scopes the message to this component;
+ * the host also checks event.source against the live iframe.
+ */
+export function buildExtAppBootBeaconScript(frameToken: string, nodeId: string): string {
+  return `<script data-pmx-canvas-boot-beacon>
+window.parent.postMessage({ source: 'pmx-canvas-ext-app-alive', token: ${JSON.stringify(frameToken)}, nodeId: ${JSON.stringify(nodeId)} }, '*');
+</script>`;
+}
+
 export function injectExtAppAxBridgeScript(html: string, axBridgeScript: string): string {
   if (!axBridgeScript) return html;
   const headMatch = /<head\b[^>]*>/i.exec(html);
@@ -262,8 +307,15 @@ export function ExtAppFrame({ node, expanded = false }: { node: CanvasNodeState;
   // handshake (bridge.oninitialized) — NOT by the 1200ms bootstrap fallback,
   // which flips status via notifications that resolve even into a dead iframe.
   const appInitializedRef = useRef(false);
+  // Liveness signal from the injected boot beacon: the CURRENT frame's scripts
+  // executed. Proves "alive" for apps that boot via the fallback path without
+  // ever sending initialized; a dead window never beacons.
+  const appScriptsRanRef = useRef(false);
   const bootWaitersRef = useRef<Array<() => void>>([]);
   const remountQueuedRef = useRef(false);
+  // Recovery ran while the document was hidden (compositing suppressed) — re-arm
+  // one fresh remount round when the panel becomes visible (Finding N).
+  const bootedWhileHiddenRef = useRef(false);
   const unmountedRef = useRef(false);
   const [status, setStatus] = useState<ExtAppFrameStatus>('loading');
   const [error, setError] = useState<string | null>(null);
@@ -298,7 +350,26 @@ export function ExtAppFrame({ node, expanded = false }: { node: CanvasNodeState;
   const axEnabled = axCaps?.enabled === true && typeof html === 'string' && html.length > 0;
   const axToken = useMemo(() => `ax-${crypto.randomUUID()}`, []);
   const axBridgeScript = axEnabled ? buildExtAppAxBridgeScript(axToken, nodeId) : '';
-  const iframeDocument = useIframeDocument(injectExtAppAxBridgeScript(html ?? '', axBridgeScript), iframeSandbox);
+  // The boot beacon precedes the AX bridge so it runs first at parse time; it
+  // shares the per-component token (used purely to authenticate the message).
+  const bootBeaconScript =
+    typeof html === 'string' && html.length > 0 ? buildExtAppBootBeaconScript(axToken, nodeId) : '';
+  const iframeDocument = useIframeDocument(
+    injectExtAppAxBridgeScript(html ?? '', bootBeaconScript + axBridgeScript),
+    iframeSandbox,
+  );
+
+  useEffect(() => {
+    function onBootBeacon(event: MessageEvent) {
+      if (event.source !== iframeRef.current?.contentWindow) return;
+      const data = event.data as { source?: string; token?: string; nodeId?: string } | null;
+      if (!data || data.source !== 'pmx-canvas-ext-app-alive' || data.token !== axToken || data.nodeId !== nodeId)
+        return;
+      appScriptsRanRef.current = true;
+    }
+    window.addEventListener('message', onBootBeacon);
+    return () => window.removeEventListener('message', onBootBeacon);
+  }, [axToken, nodeId]);
 
   useEffect(() => {
     if (!axEnabled) return;
@@ -361,6 +432,12 @@ export function ExtAppFrame({ node, expanded = false }: { node: CanvasNodeState;
           extAppRecoveryLog(nodeId, 'remount-skipped');
           return false;
         }
+        // Stamp visibility at RUN time, not schedule time: the serialized queue
+        // can hold this slot for many seconds, and what decides whether the
+        // repaint can composite is the document's visibility when the remount
+        // actually executes (the Finding N re-arm keys on this flag). Covers
+        // every scheduling path (post-boot repaint, boot watchdog, re-arm).
+        bootedWhileHiddenRef.current = typeof document !== 'undefined' && document.visibilityState === 'hidden';
         extAppRecoveryLog(nodeId, `remount-run #${webkitRemountAttemptsRef.current}`);
         setRetryKey((k) => k + 1);
         return true;
@@ -401,11 +478,42 @@ export function ExtAppFrame({ node, expanded = false }: { node: CanvasNodeState;
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [status, hasReplayToolResult]);
 
-  // Never-booted watchdog (0.3.1): an iframe whose scripts never ran in the burst
+  // Finding N (0.3.2 report): the Copilot panel can load the canvas while the
+  // WKWebView document is HIDDEN (panel backgrounded/occluded). WebKit suppresses
+  // compositing for hidden documents, so the whole serialized recovery above can
+  // run to completion without ever producing a visible paint — and nothing
+  // retried once the panel was shown, which is why tiles stayed black until a
+  // manual expand+close (necessarily performed while visible). When the document
+  // becomes visible again, re-arm ONE fresh serialized remount round for frames
+  // whose recovery ran while hidden.
+  useEffect(() => {
+    if (expanded) return;
+    if (typeof document === 'undefined' || typeof navigator === 'undefined' || typeof window === 'undefined') return;
+    if (!isWebKitOnlyHost(navigator.userAgent)) return;
+    function onVisibilityChange() {
+      if (document.visibilityState !== 'visible') return;
+      if (!bootedWhileHiddenRef.current || unmountedRef.current) return;
+      bootedWhileHiddenRef.current = false;
+      // Fresh visibility = fresh recovery budget: the hidden-run attempts were
+      // spent without a chance of compositing.
+      webkitRemountAttemptsRef.current = 0;
+      extAppRecoveryLog(nodeId, 'visible-again-rearm');
+      scheduleWebkitRemount('visible-after-hidden-boot');
+    }
+    document.addEventListener('visibilitychange', onVisibilityChange);
+    return () => document.removeEventListener('visibilitychange', onVisibilityChange);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [expanded, nodeId]);
+
+  // Never-booted watchdog (0.3.2): an iframe whose scripts never ran in the burst
   // shows no error — the bootstrap fallback flips status via notifications that
-  // resolve into a dead window, so the tile just stays black. If the CURRENT frame
-  // has not completed the genuine initialize handshake within the watchdog window,
-  // retry it through the same serialized queue (bounded by the shared attempt cap).
+  // resolve into a dead window, so the tile just stays black. "Alive" is either
+  // boot signal from the CURRENT frame: the genuine initialize handshake, or the
+  // injected boot beacon (which covers apps that boot via the fallback without
+  // ever sending initialized — remounting those was a flicker loop, and checking
+  // bridgeReadyRef instead would be wrong: the fallback sets it blindly, dead
+  // window or not). Only a frame with NEITHER signal is retried through the
+  // serialized queue (bounded by the shared attempt cap).
   const WEBKIT_BOOT_WATCHDOG_MS = 6000;
   useEffect(() => {
     if (expanded) return;
@@ -413,7 +521,7 @@ export function ExtAppFrame({ node, expanded = false }: { node: CanvasNodeState;
     if (!isWebKitOnlyHost(navigator.userAgent)) return;
     if (!iframeDocument.ready) return;
     const timer = window.setTimeout(() => {
-      if (appInitializedRef.current || unmountedRef.current) return;
+      if (appInitializedRef.current || appScriptsRanRef.current || unmountedRef.current) return;
       scheduleWebkitRemount('boot-watchdog');
     }, WEBKIT_BOOT_WATCHDOG_MS);
     return () => window.clearTimeout(timer);
@@ -494,9 +602,11 @@ export function ExtAppFrame({ node, expanded = false }: { node: CanvasNodeState;
     lastSentToolResultRef.current = undefined;
     toolResultSendingRef.current = null;
     bridgeReadyRef.current = false;
-    // New frame = new boot attempt: the genuine-initialized signal belongs to the
-    // CURRENT iframe. The queue's awaitBoot waits on this frame's handshake.
+    // New frame = new boot attempt: both boot signals belong to the CURRENT
+    // iframe (the beacon listener also pins event.source to the live element).
+    // The queue's awaitBoot waits on this frame's handshake.
     appInitializedRef.current = false;
+    appScriptsRanRef.current = false;
 
     const clearFallbackTimer = (): void => {
       if (!fallbackTimer) return;

package/src/server/bundled-skills.ts

@@ -65,7 +65,11 @@ export function findBundledSkillsRoot(): string | null {
   return null;
 }
 
-function parseFrontmatterDescription(markdown: string): string {
+function parseFrontmatterDescription(rawMarkdown: string): string {
+  // Normalize CRLF first: a git checkout with autocrlf (the Windows default)
+  // puts a trailing \r on every line, which `(.*)$` cannot match (JS `.` and
+  // `$` both exclude \r), silently emptying every description.
+  const markdown = rawMarkdown.replace(/\r\n/g, '\n');
   // YAML frontmatter lives between two `---` fences at the very top.
   if (!markdown.startsWith('---')) return '';
   const end = markdown.indexOf('\n---', 3);

package/src/server/server.ts

@@ -1120,6 +1120,44 @@ function handleFrameDocument(pathname: string): Response {
   });
 }
 
+// ── Ext-app recovery diagnostics (0.3.2 report Finding N) ──────
+//
+// The WebKit black-tile recovery trail is otherwise trapped inside host panels
+// without devtools (the Copilot WKWebView). Clients mirror their bounded
+// recovery log here; agents/testers read it back over HTTP. In-memory only,
+// diagnostics-grade: no persistence, no snapshots.
+const EXT_APP_RECOVERY_LOG_MAX = 500;
+const EXT_APP_RECOVERY_FIELD_MAX = 300;
+const extAppRecoveryEntries: Array<Record<string, unknown>> = [];
+
+/**
+ * Clamp a reported entry to the known trail shape ({ t, nodeId, event,
+ * visibility }) with bounded string lengths. The count trim below caps the
+ * number of entries; this caps bytes per entry, so the in-memory log stays
+ * diagnostics-sized no matter what a client posts.
+ */
+function clampExtAppRecoveryEntry(entry: Record<string, unknown>): Record<string, unknown> {
+  const clamped: Record<string, unknown> = {};
+  if (typeof entry.t === 'number' && Number.isFinite(entry.t)) clamped.t = entry.t;
+  for (const key of ['nodeId', 'event', 'visibility'] as const) {
+    const value = entry[key];
+    if (typeof value === 'string') clamped[key] = value.slice(0, EXT_APP_RECOVERY_FIELD_MAX);
+  }
+  return clamped;
+}
+
+function handleExtAppRecoveryReport(entries: unknown): Response {
+  if (!Array.isArray(entries)) return responseJson({ ok: false, error: 'entries must be an array' }, 400);
+  for (const entry of entries.slice(0, 100)) {
+    if (!entry || typeof entry !== 'object' || Array.isArray(entry)) continue;
+    extAppRecoveryEntries.push(clampExtAppRecoveryEntry(entry as Record<string, unknown>));
+  }
+  if (extAppRecoveryEntries.length > EXT_APP_RECOVERY_LOG_MAX) {
+    extAppRecoveryEntries.splice(0, extAppRecoveryEntries.length - EXT_APP_RECOVERY_LOG_MAX);
+  }
+  return responseJson({ ok: true, total: extAppRecoveryEntries.length });
+}
+
 // ── Node surfaces ("Open as site") ─────────────────────────────
 //
 // One stable, node-addressable URL — /api/canvas/surface/:nodeId — that serves
@@ -2843,7 +2881,10 @@ export function startCanvasServer(options: CanvasServerOptions = {}): string | n
           const url = new URL(req.url);
 
           if (url.pathname === '/health') {
-            return responseJson({ ok: true, workspace: activeWorkspaceRoot });
+            // `pid` lets `serve status` report the ACTUAL serving process even
+            // when the pid file is stale (e.g. an adapter respawned the server
+            // outside `serve --daemon` — 0.3.2 report Finding P).
+            return responseJson({ ok: true, workspace: activeWorkspaceRoot, pid: process.pid });
           }
 
           if (url.pathname === '/favicon.ico' || url.pathname === '/favicon.svg') {
@@ -2854,10 +2895,25 @@ export function startCanvasServer(options: CanvasServerOptions = {}): string | n
             return handleArtifactView(url);
           }
 
-          if (url.pathname === '/api/canvas/json-render/view' && req.method === 'GET') {
+          // Standalone surfaces answer HEAD like GET (status + headers, no body):
+          // tooling probes these advertised URLs, and a HEAD 404 against a
+          // working GET reads as a broken surface (0.3.2 report Finding O).
+          // Bun.serve strips the body and keeps the true Content-Length on HEAD,
+          // so the GET handler's response is returned as-is.
+          if (url.pathname === '/api/canvas/json-render/view' && (req.method === 'GET' || req.method === 'HEAD')) {
             return handleJsonRenderView(url);
           }
 
+          if (url.pathname === '/api/canvas/debug/ext-app-recovery' && req.method === 'POST') {
+            const body = await readJson(req);
+            if (body === null) return malformedJsonResponse();
+            return handleExtAppRecoveryReport(body.entries);
+          }
+
+          if (url.pathname === '/api/canvas/debug/ext-app-recovery' && req.method === 'GET') {
+            return responseJson({ ok: true, entries: extAppRecoveryEntries });
+          }
+
           if (url.pathname === '/api/canvas/frame-documents' && req.method === 'POST') {
             return handleCreateFrameDocument(req);
           }
@@ -2866,7 +2922,7 @@ export function startCanvasServer(options: CanvasServerOptions = {}): string | n
             return handleFrameDocument(url.pathname);
           }
 
-          if (url.pathname.startsWith('/api/canvas/surface/') && req.method === 'GET') {
+          if (url.pathname.startsWith('/api/canvas/surface/') && (req.method === 'GET' || req.method === 'HEAD')) {
             return handleNodeSurface(url.pathname, url);
           }