@dimina-kit/devtools 0.4.0-dev.20260702182435 → 0.4.0-dev.20260703101348

package/dist/main/ipc/bridge-router.js

@@ -2,7 +2,7 @@ import { app, ipcMain, protocol, session as electronSession, webContents } from
 import path from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { BRIDGE_CHANNELS as C, SIMULATOR_EVENTS as E, deviceInfoToHostEnv } from '../../shared/bridge-channels.js';
-import { isPersistentSimulatorApi } from '../../shared/simulator-api-metadata.js';
+import { apiCallWatchdogMs, isPersistentSimulatorApi } from '../../shared/simulator-api-metadata.js';
 import { devtoolsPackageRoot } from '../utils/paths.js';
 import { createSessionListenerBag } from './session-listener-bag.js';
 import { createDebugTap } from '@dimina-kit/electron-deck/main';
@@ -11,6 +11,7 @@ import { buildServiceHostSpawnUrl, createServiceHostWindow, navigateServiceHost,
 import { ServiceHostPool } from '../services/service-host-pool/pool.js';
 import { registerMiniappSessionConfigurator, SHARED_MINIAPP_PARTITION, } from '../services/views/miniapp-partition.js';
 import { createConsoleForwarder } from '../services/console-forward/index.js';
+import { createDiagnosticsBus } from '../services/diagnostics/index.js';
 import { STORAGE_API_NAMES } from '../services/simulator-storage/index.js';
 import { buildPageScrollScript } from './page-scroll.js';
 import { createAppLifecycleController, } from './app-lifecycle.js';
@@ -55,6 +56,13 @@ function rewriteSourceMappingUrl(source, scriptUrl) {
     return `${source.slice(0, lastIndex)}\n//# sourceMappingURL=${absolute}`;
 }
 const STACK_ID = 'stack_0';
+/**
+ * Watchdog window a spawned session gets to reach `'running'` (root page
+ * `domReady`) before `handleSpawn`'s launch timer reports `'launch-failed'`
+ * with `code: 'timeout'`. Exported so tests can assert against the real
+ * constant instead of a magic number.
+ */
+export const LAUNCH_TIMEOUT_MS = 20_000;
 /** Hard ceiling on the pre-warm pool, mirroring ServiceHostPool/doc §3.3. */
 const PREWARM_MAX_POOL_SIZE = 4;
 /**
@@ -92,8 +100,34 @@ function summarizeBridgeMsg(payload) {
     const parts = [type, bridgeId ? `bridge=${bridgeId}` : undefined].filter(Boolean);
     return parts.length > 0 ? parts.join(' ') : undefined;
 }
-/** Default timeout for a simulator-forwarded API call. */
-const API_CALL_TIMEOUT_MS = 5_000;
+// Same-appId matches prefer the MOST RECENT spawn (Maps preserve insertion
+// order): after a respawn/reopen the newest session is the live one — the
+// first match could be a just-superseded session mid-teardown. The loop must
+// scan every session (no early break) so the LAST inserted match wins.
+function findAppSessionByAppId(state, appId) {
+    let match;
+    for (const ap of state.appSessions.values())
+        if (ap.appId === appId)
+            match = ap;
+    return match;
+}
+// No appId hint and no workspace session to disambiguate. Picking by appId is
+// impossible, so fall back to the most-recent spawn — but ONLY when every live
+// session belongs to the same app. Same-appId multiples are a respawn/reopen
+// in progress where the newest is the live one (insertion order = spawn
+// order). Multiple DISTINCT appIds mean a previous project is mid-teardown
+// alongside the new one; any pick is a guess that can resolve the WRONG
+// project's content (the screenshot/inspect-stale-app bug class), so prefer
+// null over a wrong guess.
+function resolveFallbackAppSession(state) {
+    let last;
+    const distinctAppIds = new Set();
+    for (const ap of state.appSessions.values()) {
+        last = ap;
+        distinctAppIds.add(ap.appId);
+    }
+    return distinctAppIds.size <= 1 ? last : undefined;
+}
 /**
  * Resolve the "current" app session: prefer an explicit appId, else the
  * workspace's active project, else the only / most-recently-created session.
@@ -101,24 +135,15 @@ const API_CALL_TIMEOUT_MS = 5_000;
  * rather than assuming a single session.
  */
 function resolveCurrentApp(state, ctx, appId) {
-    // Same-appId matches prefer the MOST RECENT spawn (Maps preserve insertion
-    // order): after a respawn/reopen the newest session is the live one — the
-    // first match could be a just-superseded session mid-teardown.
     if (appId) {
-        let match;
-        for (const ap of state.appSessions.values())
-            if (ap.appId === appId)
-                match = ap;
+        const match = findAppSessionByAppId(state, appId);
         if (match)
             return match;
     }
     const appInfo = ctx.workspace?.getSession?.()?.appInfo;
     const activeAppId = appInfo?.appId;
     if (activeAppId) {
-        let match;
-        for (const ap of state.appSessions.values())
-            if (ap.appId === activeAppId)
-                match = ap;
+        const match = findAppSessionByAppId(state, activeAppId);
         if (match)
             return match;
     }
@@ -128,21 +153,7 @@ function resolveCurrentApp(state, ctx, appId) {
     // while a close is in flight.
     if (ctx.workspace?.isClosing?.())
         return undefined;
-    // No appId hint and no workspace session to disambiguate. Picking by appId is
-    // impossible, so fall back to the most-recent spawn — but ONLY when every live
-    // session belongs to the same app. Same-appId multiples are a respawn/reopen
-    // in progress where the newest is the live one (insertion order = spawn
-    // order). Multiple DISTINCT appIds mean a previous project is mid-teardown
-    // alongside the new one; any pick is a guess that can resolve the WRONG
-    // project's content (the screenshot/inspect-stale-app bug class), so prefer
-    // null over a wrong guess.
-    let last;
-    const distinctAppIds = new Set();
-    for (const ap of state.appSessions.values()) {
-        last = ap;
-        distinctAppIds.add(ap.appId);
-    }
-    return distinctAppIds.size <= 1 ? last : undefined;
+    return resolveFallbackAppSession(state);
 }
 export function installBridgeRouter(ctx) {
     const state = {
@@ -338,13 +349,28 @@ export function installBridgeRouter(ctx) {
     // Chrome DevTools (attached to the service host) prefixed `[视图]` — regardless
     // of whether an automation client is connected. Automation now SUBSCRIBES to
     // this forwarder instead of clobbering `ctx.guestConsole`.
-    const consoleForwarder = createConsoleForwarder(bridgeHandle);
+    // Authoritative diagnostics bus (see workbench-context.ts): the single place
+    // main-synthesized diagnostics are born. The forwarder subscribes to it so
+    // every diagnostic also lands in the owning session's embedded DevTools
+    // Console panel, not just the main-process log / automation subscribers.
+    // A caller (host embedding, or a test) may have already installed one on
+    // `ctx` before `installBridgeRouter` runs — respect it instead of
+    // clobbering it with a fresh bus; only a bus WE create here is ours to
+    // dispose on teardown.
+    const ownsDiagnosticsBus = ctx.diagnostics === undefined;
+    const diagnosticsBus = ctx.diagnostics ?? createDiagnosticsBus();
+    ctx.diagnostics = diagnosticsBus;
+    const consoleForwarder = createConsoleForwarder(bridgeHandle, diagnosticsBus);
     ctx.consoleForwarder = consoleForwarder;
     ctx.guestConsole = consoleForwarder;
     ctx.registry.add(() => {
         void consoleForwarder.dispose();
         ctx.consoleForwarder = undefined;
         ctx.guestConsole = undefined;
+        if (ownsDiagnosticsBus) {
+            diagnosticsBus.dispose();
+            ctx.diagnostics = undefined;
+        }
     });
     // DeviceShell → main: record the visible top-of-stack page bridgeId so the
     // accessor above can resolve "the active page". Sender-validated against the
@@ -511,6 +537,64 @@ export function installBridgeRouter(ctx) {
     });
 }
 // ── Spawn / Open / Close ─────────────────────────────────────────────────────
+/** Clear a session's launch-timeout watchdog, if still armed. Idempotent. */
+function clearLaunchTimer(ap) {
+    if (ap.launchTimer === null)
+        return;
+    clearTimeout(ap.launchTimer);
+    ap.launchTimer = null;
+}
+/**
+ * Arm the `LAUNCH_TIMEOUT_MS` watchdog for a freshly spawned session. Fires
+ * `'launch-failed'` (`code: 'timeout'`) exactly once, and only if the session
+ * is both still registered (not disposed) and has not already reached
+ * `'running'` — both settle paths clear the timer themselves, but a timer
+ * queued just before either lands could still fire on the old macrotask queue.
+ */
+function startLaunchTimer(state, ctx, ap) {
+    ap.launchTimer = setTimeout(() => {
+        ap.launchTimer = null;
+        if (ap.running)
+            return;
+        if (state.appSessions.get(ap.appSessionId) !== ap)
+            return;
+        const reason = `Service host did not report readiness within ${LAUNCH_TIMEOUT_MS}ms`;
+        ctx.diagnostics?.report({
+            severity: 'error',
+            code: 'launch-timeout',
+            message: reason,
+            appSessionId: ap.appSessionId,
+        });
+        pushRuntimeStatus(ctx, ap, { phase: 'launch-failed', code: 'timeout', reason });
+    }, LAUNCH_TIMEOUT_MS);
+}
+/**
+ * Flip a session to `'running'` on its root page's first `domReady` — the
+ * single source-of-truth transition out of `'launching'`. Guarded by
+ * `ap.running` so a later re-render of the same root page (or any non-root
+ * page) never re-fires the notification or re-clears an already-cleared timer.
+ */
+function markSessionRunning(ctx, ap, page) {
+    if (!page.isRoot || ap.running)
+        return;
+    ap.running = true;
+    clearLaunchTimer(ap);
+    pushRuntimeStatus(ctx, ap, { phase: 'running' });
+}
+/**
+ * The single chokepoint for session runtime-status pushes. Every event
+ * carries the session's launch-round facts (appId + pageFallback) alongside
+ * the phase change — the renderer replaces its runtimeStatus wholesale, so an
+ * event that omitted a still-true fallback would silently blank the fallback
+ * banner the moment the phase advances past 'launching'.
+ */
+function pushRuntimeStatus(ctx, session, status) {
+    ctx.notify?.sessionRuntimeStatus?.({
+        appId: session.appId,
+        ...status,
+        ...(session.pageFallback ? { pageFallback: session.pageFallback } : {}),
+    });
+}
 async function handleSpawn(state, ctx, event, opts) {
     const appId = opts.appId;
     if (!appId)
@@ -557,10 +641,21 @@ async function handleSpawn(state, ctx, event, opts) {
     });
     // app-config.json lives at `<base><appId>/<root>/app-config.json` on the dev
     // server, or at the local server root for the fallback path.
-    const appConfig = await loadAppConfig(resourceServer ? resourceServer.baseUrl : `${resourceBaseUrl}${appId}/${root}/`);
+    const appConfig = await loadAppConfig(resourceServer ? resourceServer.baseUrl : `${resourceBaseUrl}${appId}/${root}/`, ({ url, error }) => {
+        ctx.diagnostics?.report({
+            severity: 'error',
+            code: 'app-config-unreachable',
+            message: `app-config.json unreachable at ${url}: ${String(error)}`,
+            appSessionId,
+        });
+    });
     const manifest = buildAppManifest(appConfig, pagePath);
-    const rootWindowConfig = resolvePageWindowConfig(appConfig, pagePath);
-    const isTab = isTabPage(appConfig, pagePath);
+    const { resolvedPagePath, pageFallbackApplied } = resolveRootPagePath(manifest, pagePath);
+    if (pageFallbackApplied) {
+        reportPageNotFound(ctx, appSessionId, pagePath, resolvedPagePath);
+    }
+    const rootWindowConfig = resolvePageWindowConfig(appConfig, resolvedPagePath);
+    const isTab = isTabPage(appConfig, resolvedPagePath);
     // Acquire a pre-warmed service-host window when pooling is enabled; otherwise
     // construct one fresh (default). A pooled/fallback window is warmed on
     // about:blank and must be navigated to the spawn URL below; the fresh path
@@ -568,13 +663,31 @@ async function handleSpawn(state, ctx, event, opts) {
     const usedPool = state.pool !== null;
     let poolEntryId = null;
     let serviceWindow;
+    // Shared spawn-navigation failure handler (fresh AND pooled paths): without
+    // it a loadURL rejection is fully swallowed — did-finish-load never fires and
+    // the only signal is the launch watchdog's late timeout instead of the cause.
+    const reportServiceHostNavigationFailed = (spawnUrl, err) => {
+        const message = `Failed to navigate service host to ${spawnUrl}: ${String(err)}`;
+        ctx.diagnostics?.report({
+            severity: 'error',
+            code: 'service-host-navigation-failed',
+            message,
+            appSessionId,
+        });
+        // The session registers after window construction; resolve it fresh so the
+        // fresh-path callback (created pre-registration) still clears the watchdog.
+        const ap = state.appSessions.get(appSessionId);
+        if (ap)
+            clearLaunchTimer(ap);
+        pushRuntimeStatus(ctx, ap ?? { appId, pageFallback: pageFallbackApplied ? { requested: pagePath, resolved: resolvedPagePath } : null }, { phase: 'launch-failed', code: 'service-host-navigation-failed', reason: message });
+    };
     if (state.pool) {
         const acquired = await state.pool.acquire(serviceHostSpec());
         serviceWindow = acquired.win;
         poolEntryId = acquired.entryId;
     }
     else {
-        serviceWindow = createServiceHostWindow({
+        const freshWindowOptions = {
             bridgeId,
             appId,
             // Same (appId, projectPath) pair the simulator WCV uses, so this project's
@@ -584,12 +697,16 @@ async function handleSpawn(state, ctx, event, opts) {
             // awaits above would otherwise give the service host a different path than
             // the simulator WCV was built with, splitting the partition.
             projectPath: workspaceProjectPath || undefined,
-            pagePath,
+            pagePath: resolvedPagePath,
             pkgRoot,
             root,
             resourceBaseUrl,
             hostEnvSnapshot: hostEnv,
             apiNamespaces,
+        };
+        serviceWindow = createServiceHostWindow({
+            ...freshWindowOptions,
+            onLoadFailed: err => reportServiceHostNavigationFailed(buildServiceHostSpawnUrl(freshWindowOptions), err),
         });
     }
     const appSession = {
@@ -614,11 +731,14 @@ async function handleSpawn(state, ctx, event, opts) {
         onServiceBoot: null,
         listenerBag: createSessionListenerBag(),
         registryHandle: null,
+        running: false,
+        launchTimer: null,
+        pageFallback: pageFallbackApplied ? { requested: pagePath, resolved: resolvedPagePath } : null,
     };
     const rootPage = {
         bridgeId,
         appSessionId,
-        pagePath,
+        pagePath: resolvedPagePath,
         query: opts.query ?? {},
         isRoot: true,
         isTab,
@@ -699,16 +819,19 @@ async function handleSpawn(state, ctx, event, opts) {
         };
         appSession.onServiceBoot = bootOnServiceLoad;
         serviceWindow.webContents.on('did-finish-load', bootOnServiceLoad);
-        void navigateServiceHost(serviceWindow, buildServiceHostSpawnUrl({
+        const spawnUrl = buildServiceHostSpawnUrl({
             bridgeId,
             appId,
-            pagePath,
+            pagePath: resolvedPagePath,
             pkgRoot,
             root,
             resourceBaseUrl,
             hostEnvSnapshot: hostEnv,
             apiNamespaces,
-        }));
+        });
+        void navigateServiceHost(serviceWindow, spawnUrl, {
+            onLoadFailed: err => reportServiceHostNavigationFailed(spawnUrl, err),
+        });
     }
     else {
         // Fresh window: its only navigation is service.html (issued inside
@@ -717,10 +840,33 @@ async function handleSpawn(state, ctx, event, opts) {
             void bootServiceHost(state, appSession, ctx);
         });
     }
+    // Service-host crash (renderer process gone): a session-scoped hook on the
+    // service webContents, bound via the listener bag so `disposeAppSession`
+    // detaches it (matching the 'closed'/'destroyed' hooks registered above).
+    // Not a `.once` — a pooled service window can recover and crash again
+    // across its lifetime, and each crash is independently worth surfacing.
+    // Fires whether the crash lands before or after 'running'; only the launch
+    // timer needs clearing (it may already be null) since a running session no
+    // longer has one armed.
+    const onServiceCrashed = () => {
+        clearLaunchTimer(appSession);
+        ctx.diagnostics?.report({
+            severity: 'error',
+            code: 'service-host-crashed',
+            message: `Service host renderer process gone for appSessionId=${appSessionId}`,
+            appSessionId,
+        });
+        pushRuntimeStatus(ctx, appSession, { phase: 'crashed', code: 'service-host-crashed' });
+    };
+    appSession.listenerBag.on(serviceWindow.webContents, 'render-process-gone', onServiceCrashed);
+    pushRuntimeStatus(ctx, appSession, { phase: 'launching' });
+    startLaunchTimer(state, ctx, appSession);
     return {
         appSessionId,
         bridgeId,
         pagePath,
+        resolvedPagePath,
+        pageFallbackApplied,
         serviceWcId: serviceWindow.webContents.id,
         resourceBaseUrl,
         manifest,
@@ -736,6 +882,15 @@ async function handlePageOpen(state, event, opts) {
         throw new Error('[bridge-router] PAGE_OPEN rejected: caller not bound to app session');
     }
     const pagePath = normalizePagePath(opts.pagePath);
+    // Defense-in-depth against a page absent from the compiled manifest: the
+    // nav gate (handleNavActionApi) already blocks normal navigateTo/switchTab
+    // traffic upstream, but PAGE_OPEN is reachable directly (any IPC caller), so
+    // this refuses to register a PageSession main can never load resources for.
+    // Only enforced against a real compiled manifest ('app-config') — a
+    // 'fallback' manifest has no compiled truth to validate membership against.
+    if (ap.manifest.source === 'app-config' && !ap.manifest.pages.includes(pagePath)) {
+        throw new Error(`[bridge-router] PAGE_OPEN rejected: page-not-found "${pagePath}" is not in the compiled manifest`);
+    }
     const bridgeId = opts.bridgeId || newBridgeId();
     const windowConfig = resolvePageWindowConfig(ap.appConfig, pagePath);
     const isTab = isTabPage(ap.appConfig, pagePath);
@@ -808,6 +963,10 @@ async function bootServiceHost(state, ap, ctx) {
     // app's logic.js into the next spawn (the recycled webContents is shared).
     if (state.appSessions.get(ap.appSessionId) !== ap)
         return;
+    // The service wc just did-finish-load'd (that's how this got invoked) — flush
+    // any diagnostic queued for this session (or the global bucket) into its now
+    // resolvable console. Safe to call even when nothing is queued.
+    ctx.consoleForwarder?.notifyServiceHostReady?.(ap.appSessionId);
     ap.logicInjected = await injectLogicBundle(ap);
     if (!ap.logicInjected) {
         // The compiled logic.js never executed, so `modDefine` registered nothing.
@@ -816,7 +975,9 @@ async function bootServiceHost(state, ap, ctx) {
         // cause (unreachable resource tree / failed compile / unresolved appId).
         // Skip it and surface one actionable diagnostic instead; the render side
         // gates on the same flag in `routeFromRender`.
-        reportLogicLoadFailure(ap, ctx);
+        const reason = reportLogicLoadFailure(ap, ctx);
+        clearLaunchTimer(ap);
+        pushRuntimeStatus(ctx, ap, { phase: 'launch-failed', code: 'logic-bundle-unreachable', reason });
         return;
     }
     // A root page absent from the compiled manifest — most commonly a page the
@@ -832,7 +993,7 @@ async function bootServiceHost(state, ap, ctx) {
     const rootPage = ap.pages.get(ap.appSessionId);
     const rootMissing = !!rootPage && !pageInManifest(ap, rootPage.pagePath);
     if (rootMissing) {
-        reportPageNotFound(ap, ctx, rootPage.pagePath);
+        reportPageNotFound(ctx, ap.appSessionId, rootPage.pagePath);
     }
     else if (rootPage) {
         // serviceLoaded is flipped only when service responds with
@@ -894,34 +1055,65 @@ async function injectLogicBundle(ap) {
 /**
  * Emit one actionable diagnostic when the compiled logic bundle could not be
  * loaded — the single point where "the app's compiled resource tree is
- * unreachable" is known with certainty. Goes to the main-process log AND the
- * guest console sink so it surfaces in the devtools Console panel where the
+ * unreachable" is known with certainty. Reported through `ctx.diagnostics`,
+ * which mirrors it to the main-process log AND — via `consoleForwarder`'s
+ * subscription — injects it into the service host's own console, so it
+ * actually surfaces in the embedded DevTools Console panel where the
  * developer would otherwise see only the misleading `module app not found`.
+ * `guestConsole.emit` is kept alongside for the automation `App.logAdded`
+ * subscriber, which does not consume the diagnostics bus.
+ *
+ * Returns the short (pre-hint) form of the message so `bootServiceHost` can
+ * reuse it verbatim as the `sessionRuntimeStatus` `reason` instead of
+ * duplicating the wording.
  */
 function reportLogicLoadFailure(ap, ctx) {
     const hint = ap.appId === 'unknown'
         ? ' appId could not be resolved (it fell back to "unknown") — the mini-program likely failed to compile or its project manifest/app config is missing.'
         : '';
-    const message = `[dimina-kit] Failed to load the mini-program logic bundle from ${logicBundleUrl(ap)}. `
+    const shortReason = `[dimina-kit] Failed to load the mini-program logic bundle from ${logicBundleUrl(ap)}.`;
+    const message = `${shortReason} `
         + 'The service runtime has no registered modules, so no page can mount.'
         + hint
         + ` Verify the project compiled successfully and that the resource server serves "${ap.appId}/${ap.root}/".`;
-    console.error(message);
+    ctx.diagnostics?.report({
+        severity: 'error',
+        code: 'logic-bundle-unreachable',
+        message,
+        appSessionId: ap.appSessionId,
+    });
     ctx.guestConsole?.emit({ source: 'service', level: 'error', args: [message] });
+    return shortReason;
 }
 /** Whether `pagePath` still exists in the app's freshly compiled manifest. */
 function pageInManifest(ap, pagePath) {
+    // A 'fallback' manifest (app-config.json unreachable) holds only the spawn
+    // request — no compiled truth to check membership against. Every mount gate
+    // keyed on manifest membership must agree: the nav/PAGE_OPEN front gates
+    // already let a fallback manifest through, so this back gate (render
+    // loadResource) must too, or a page they admitted silently never loads.
+    if (ap.manifest.source !== 'app-config')
+        return true;
     return ap.manifest.pages.includes(normalizePagePath(pagePath));
 }
 /**
- * WeChat-devtools-style "page does not exist" diagnostic. Emitted (main log +
- * guest Console) when a mount targets a pagePath that is not in the compiled
- * manifest — most commonly a page the developer deleted, then hot-reloaded.
+ * WeChat-devtools-style "page does not exist" diagnostic. Reported through
+ * `ctx.diagnostics` (main log + injected into the embedded Console panel via
+ * `consoleForwarder`) when a mount targets a pagePath that is not in the
+ * compiled manifest — most commonly a page the developer deleted, then
+ * hot-reloaded. `guestConsole.emit` is kept alongside for the automation
+ * subscriber.
  */
-function reportPageNotFound(ap, ctx, pagePath) {
-    const message = `Page[${pagePath}] not found. May be caused by: 1. Forgetting to add page route in app.json. `
+function reportPageNotFound(ctx, appSessionId, pagePath, fallbackTo) {
+    const base = `Page[${pagePath}] not found. May be caused by: 1. Forgetting to add page route in app.json. `
         + '2. Invoking Page() in async task.';
-    console.error(`[bridge-router] ${message}`);
+    const message = fallbackTo ? `${base} Falling back to "${fallbackTo}".` : base;
+    ctx.diagnostics?.report({
+        severity: 'error',
+        code: 'page-not-found',
+        message,
+        appSessionId,
+    });
     ctx.guestConsole?.emit({ source: 'service', level: 'error', args: [message] });
 }
 function maybeSendResourceLoaded(ap, page) {
@@ -1000,6 +1192,18 @@ function routeFromRender(state, ap, page, msg, ctx) {
         handleContainerMsg(ap, page, msg, ctx, state);
     }
 }
+/**
+ * Report 'service-uncaught-error' for a consoleLog(source:'service') body —
+ * the service preload's uncaught error/unhandledrejection post. CDP's
+ * `Runtime.consoleAPICalled` (services/service-console) never observes these
+ * (they never call `console.*`), so this diagnostics report is the only way
+ * one reaches the Console panel / main log.
+ */
+function reportServiceUncaughtError(ctx, ap, body) {
+    const severity = body.level === 'error' ? 'error' : body.level === 'warn' ? 'warn' : 'info';
+    const message = Array.isArray(body.args) ? body.args.map(a => String(a)).join(' ') : String(body.args ?? '');
+    ctx.diagnostics?.report({ severity, code: 'service-uncaught-error', message, appSessionId: ap.appSessionId });
+}
 function handleContainerMsg(ap, page, msg, ctx, state) {
     switch (msg.type) {
         case 'serviceResourceLoaded':
@@ -1019,12 +1223,12 @@ function handleContainerMsg(ap, page, msg, ctx, state) {
                 ap.simulatorWc.send(E.DOM_READY, { bridgeId: page.bridgeId });
             }
             state.emitRenderEvent({ kind: 'domReady', appId: ap.appId, bridgeId: page.bridgeId });
+            markSessionRunning(ctx, ap, page);
             break;
         case 'invokeAPI':
             void handleSimulatorApi(state, ap, page, msg.body, ctx);
             break;
         case 'serviceHostError': {
-            console.warn('[bridge-router] service host error:', msg.body);
             // Forward the error to every registered `wx.onError` listener. (The dimina
             // service runtime's App lifecycle is only onLaunch/onShow/onHide, so it
             // does not dispatch `App.onError` — `wx.onError` is the supported path.)
@@ -1032,19 +1236,32 @@ function handleContainerMsg(ap, page, msg, ctx, state) {
             // during lifecycle/event dispatch here.
             const errBody = msg.body;
             const errArg = errBody?.message ?? msg.body;
+            // Reported through the diagnostics bus (main log + Console-panel
+            // injection); `ctx.diagnostics.report` replaces the bare `console.warn`
+            // this case used to make directly.
+            ctx.diagnostics?.report({
+                severity: 'error',
+                code: 'service-host-error',
+                message: String(errArg),
+                appSessionId: ap.appSessionId,
+            });
             for (const id of state.appLifecycle.listeners(ap.appSessionId, 'onError')) {
                 sendCallback(ap, id, errArg);
             }
             break;
         }
-        case 'consoleLog':
+        case 'consoleLog': {
             // Native-host console capture: the render-host / service-host guest preloads
             // monkeypatch console.* and post each entry here (one case handles both —
             // distinguish via msg.body.source). Forward to the console sink (set by the
             // automation server under native-host) so it can rebroadcast as App.logAdded.
             // Guarded + non-throwing: console capture must never break message routing.
             ctx.guestConsole?.emit(msg.body);
+            const body = msg.body;
+            if (body?.source === 'service')
+                reportServiceUncaughtError(ctx, ap, body);
             break;
+        }
         case 'storageChanged':
             // Native-host SYNC storage liveness: the service-host's `setStorageSync`/etc.
             // write `localStorage` directly (no main round-trip), so they post the change
@@ -1136,86 +1353,160 @@ const APP_LIFECYCLE_UNREGISTER = {
     offAppHide: 'onAppHide',
     offError: 'onError',
 };
-async function handleSimulatorApi(state, ap, page, body, ctx) {
-    const name = String(body.name ?? '');
-    const params = normalizeParams(body.params);
-    if (NAV_BAR_API_NAMES.has(name)) {
-        if (!ap.simulatorWc.isDestroyed()) {
-            ap.simulatorWc.send(E.NAV_BAR, {
-                bridgeId: page.bridgeId,
-                name,
-                params,
-            });
-        }
-        const successResult = { errMsg: `${name}:ok` };
-        sendCallback(ap, params.success, successResult);
-        sendCallback(ap, params.complete, successResult);
-        return;
-    }
-    if (NAV_ACTION_NAMES.has(name)) {
-        const payload = {
-            appSessionId: ap.appSessionId,
+function handleNavBarApi(ap, page, name, params) {
+    if (!ap.simulatorWc.isDestroyed()) {
+        ap.simulatorWc.send(E.NAV_BAR, {
             bridgeId: page.bridgeId,
-            name: name,
+            name,
             params,
-            callbacks: extractCallbacks(params),
-        };
-        if (!ap.simulatorWc.isDestroyed()) {
-            ap.simulatorWc.send(E.NAV_ACTION, payload);
-        }
-        else {
-            const fail = { errMsg: `${name}:fail simulator window destroyed` };
-            sendCallback(ap, params.fail, fail);
-            sendCallback(ap, params.complete, fail);
-        }
+        });
+    }
+    const successResult = { errMsg: `${name}:ok` };
+    sendCallback(ap, params.success, successResult);
+    sendCallback(ap, params.complete, successResult);
+}
+// Fails a nav/tab action's service-side callback through the same success/
+// complete dispatch every other API branch uses — the one mechanism for
+// answering a call that never reaches (or never should reach) the simulator.
+function failActionCallback(ap, params, errMsg) {
+    const fail = { errMsg };
+    sendCallback(ap, params.fail, fail);
+    sendCallback(ap, params.complete, fail);
+}
+// Shared by handleNavActionApi/handleTabActionApi: both forward a same-shaped
+// payload to the simulator window, differing only in the event name and the
+// payload's static `name` union. Simulator-destroyed fails the callback
+// directly since there is no ack path to fail through otherwise.
+function sendActionOrFail(ap, eventName, payload, name, params) {
+    if (!ap.simulatorWc.isDestroyed()) {
+        ap.simulatorWc.send(eventName, payload);
         return;
     }
-    if (TAB_ACTION_NAMES.has(name)) {
-        const payload = {
-            appSessionId: ap.appSessionId,
-            bridgeId: page.bridgeId,
-            name: name,
-            params,
-            callbacks: extractCallbacks(params),
-        };
-        if (!ap.simulatorWc.isDestroyed()) {
-            ap.simulatorWc.send(E.TAB_ACTION, payload);
-        }
-        else {
-            const fail = { errMsg: `${name}:fail simulator window destroyed` };
-            sendCallback(ap, params.fail, fail);
-            sendCallback(ap, params.complete, fail);
+    failActionCallback(ap, params, `${name}:fail simulator window destroyed`);
+}
+/** The bare page path a nav/tab action targets (query-stripped, normalized), or undefined for an action carrying none (navigateBack). */
+function extractNavTargetPagePath(params) {
+    const raw = params.url;
+    if (typeof raw !== 'string' || !raw)
+        return undefined;
+    return normalizePagePath(raw.split('?')[0] ?? raw);
+}
+/**
+ * Whether a nav/tab action's target page is mountable — checked ONLY against
+ * a real compiled manifest (`source === 'app-config'`); a `'fallback'`
+ * manifest can't tell mountable from not, so it lets everything through.
+ */
+function checkNavTarget(ap, name, targetPagePath) {
+    if (ap.manifest.source !== 'app-config')
+        return { ok: true };
+    if (!ap.manifest.pages.includes(targetPagePath)) {
+        return { ok: false, errMsg: `${name}:fail page "${targetPagePath}" is not found`, reportNotFound: true };
+    }
+    if (name === 'switchTab') {
+        const inTabBar = ap.manifest.tabBar?.list.some(item => normalizePagePath(item.pagePath) === targetPagePath) ?? false;
+        if (!inTabBar)
+            return { ok: false, errMsg: 'switchTab:fail can not switch to no-tabBar page' };
+    }
+    return { ok: true };
+}
+function handleNavActionApi(ap, ctx, page, name, params) {
+    const targetPagePath = extractNavTargetPagePath(params);
+    if (targetPagePath !== undefined) {
+        const verdict = checkNavTarget(ap, name, targetPagePath);
+        if (!verdict.ok) {
+            if (verdict.reportNotFound)
+                reportPageNotFound(ctx, ap.appSessionId, targetPagePath);
+            failActionCallback(ap, params, verdict.errMsg);
+            return;
         }
-        return;
     }
-    // App-level lifecycle listeners (wx.onAppShow / onAppHide / onError + off*).
-    // The service encodes the listener as a keep callback id in `params.success`;
-    // we store it and re-fire on main-window foreground/background (the driver in
-    // installBridgeRouter) and on serviceHostError. `off*` clears the event's
-    // listeners for the session.
+    const payload = {
+        appSessionId: ap.appSessionId,
+        bridgeId: page.bridgeId,
+        name: name,
+        params,
+        callbacks: extractCallbacks(params),
+    };
+    sendActionOrFail(ap, E.NAV_ACTION, payload, name, params);
+}
+function handleTabActionApi(ap, page, name, params) {
+    const payload = {
+        appSessionId: ap.appSessionId,
+        bridgeId: page.bridgeId,
+        name: name,
+        params,
+        callbacks: extractCallbacks(params),
+    };
+    sendActionOrFail(ap, E.TAB_ACTION, payload, name, params);
+}
+// App-level lifecycle listeners (wx.onAppShow / onAppHide / onError + off*).
+// The service encodes the listener as a keep callback id in `params.success`;
+// we store it and re-fire on main-window foreground/background (the driver in
+// installBridgeRouter) and on serviceHostError. `off*` clears the event's
+// listeners for the session. Returns true when `name` matched a lifecycle
+// register/unregister call (fully handled), false to fall through.
+function handleAppLifecycleToggle(state, ap, name, params) {
     const lifecycleRegister = APP_LIFECYCLE_REGISTER[name];
     if (lifecycleRegister) {
         state.appLifecycle.register(ap.appSessionId, lifecycleRegister, params.success);
-        return;
+        return true;
     }
     const lifecycleUnregister = APP_LIFECYCLE_UNREGISTER[name];
     if (lifecycleUnregister) {
         // off(cb) carries the same evtId as the original on(cb) → removes just that
         // listener; off() with no callback carries no id → clears the whole event.
         state.appLifecycle.unregister(ap.appSessionId, lifecycleUnregister, params.success);
+        return true;
+    }
+    return false;
+}
+// pageScrollTo acts on the page's render guest (scroll its document), which
+// only the main process can reach — run the scroll script in the invoking
+// page's render webContents rather than forwarding to the simulator.
+function handlePageScrollApi(ap, page, params) {
+    const renderWc = page.renderWc;
+    if (renderWc && !renderWc.isDestroyed()) {
+        void renderWc.executeJavaScript(buildPageScrollScript(params)).catch(() => { });
+    }
+    const successResult = { errMsg: 'pageScrollTo:ok' };
+    sendCallback(ap, params.success, successResult);
+    sendCallback(ap, params.complete, successResult);
+}
+// Shared try/invoke/callback pattern used by the storageApi and
+// ctx.simulatorApis branches: relay the resolved value through
+// success+complete, or the thrown error through fail+complete with a
+// namespaced errMsg.
+async function invokeSimulatorApiAndCallback(ap, name, params, invoke) {
+    try {
+        const result = await invoke();
+        sendCallback(ap, params.success, result);
+        sendCallback(ap, params.complete, result);
+    }
+    catch (error) {
+        const failResult = { errMsg: `${name}:fail ${error instanceof Error ? error.message : String(error)}` };
+        sendCallback(ap, params.fail, failResult);
+        sendCallback(ap, params.complete, failResult);
+    }
+}
+async function handleSimulatorApi(state, ap, page, body, ctx) {
+    const name = String(body.name ?? '');
+    const params = normalizeParams(body.params);
+    if (NAV_BAR_API_NAMES.has(name)) {
+        handleNavBarApi(ap, page, name, params);
+        return;
+    }
+    if (NAV_ACTION_NAMES.has(name)) {
+        handleNavActionApi(ap, ctx, page, name, params);
+        return;
+    }
+    if (TAB_ACTION_NAMES.has(name)) {
+        handleTabActionApi(ap, page, name, params);
         return;
     }
-    // pageScrollTo acts on the page's render guest (scroll its document), which
-    // only the main process can reach — run the scroll script in the invoking
-    // page's render webContents rather than forwarding to the simulator.
+    if (handleAppLifecycleToggle(state, ap, name, params))
+        return;
     if (name === 'pageScrollTo') {
-        const renderWc = page.renderWc;
-        if (renderWc && !renderWc.isDestroyed()) {
-            void renderWc.executeJavaScript(buildPageScrollScript(params)).catch(() => { });
-        }
-        const successResult = { errMsg: 'pageScrollTo:ok' };
-        sendCallback(ap, params.success, successResult);
-        sendCallback(ap, params.complete, successResult);
+        handlePageScrollApi(ap, page, params);
         return;
     }
     // Native-host storage unification: route async wx.setStorage/getStorage/etc.
@@ -1224,16 +1515,8 @@ async function handleSimulatorApi(state, ap, page, body, ctx) {
     // http:// origin. Without this, async writes and sync writes diverge across
     // two origins even for the running mini-app.
     if (ctx.storageApi && STORAGE_API_NAMES.has(name)) {
-        try {
-            const result = await ctx.storageApi.invoke(ap.appId, name, params);
-            sendCallback(ap, params.success, result);
-            sendCallback(ap, params.complete, result);
-        }
-        catch (error) {
-            const failResult = { errMsg: `${name}:fail ${error instanceof Error ? error.message : String(error)}` };
-            sendCallback(ap, params.fail, failResult);
-            sendCallback(ap, params.complete, failResult);
-        }
+        const storageApi = ctx.storageApi;
+        await invokeSimulatorApiAndCallback(ap, name, params, () => storageApi.invoke(ap.appId, name, params));
         return;
     }
     // Main-process registry (downstream-registered host APIs via
@@ -1242,16 +1525,7 @@ async function handleSimulatorApi(state, ap, page, body, ctx) {
     // MiniApp owns the DOM-touching defaults (wx.getSystemInfo, chooseImage,
     // chooseMedia, fs.*, …) and the bridge-router can't run those itself.
     if (ctx.simulatorApis.has(name)) {
-        try {
-            const result = await ctx.simulatorApis.invoke(name, params);
-            sendCallback(ap, params.success, result);
-            sendCallback(ap, params.complete, result);
-        }
-        catch (error) {
-            const failResult = { errMsg: `${name}:fail ${error instanceof Error ? error.message : String(error)}` };
-            sendCallback(ap, params.fail, failResult);
-            sendCallback(ap, params.complete, failResult);
-        }
+        await invokeSimulatorApiAndCallback(ap, name, params, () => ctx.simulatorApis.invoke(name, params));
         return;
     }
     forwardApiCallToSimulator(state, ap, page, name, params);
@@ -1267,12 +1541,17 @@ function forwardApiCallToSimulator(state, ap, page, name, params) {
     const requestId = newRequestId();
     // Persistent subscriptions (`keep: true`, e.g. audioListen) bind their event
     // bridge synchronously but only emit their FIRST response when the first
-    // event fires (which can be well past the 5s no-handler window). Arming the
+    // event fires (which can be well past the no-handler window). Arming the
     // one-shot timeout would tear the subscription down before it ever delivers,
     // so keep calls run without a timeout and are reaped on page/app teardown.
     // Recognise persistent subscriptions BY NAME (`audioListen`) too: the service
     // host strips the original `keep: true` before forwarding, so `params.keep` is
     // gone by the time we route the call. See shared/simulator-api-metadata.ts.
+    //
+    // The watchdog window is per-call (apiCallWatchdogMs): network-budget APIs
+    // (request/downloadFile/uploadFile) get their wx timeout budget + grace so a
+    // slow-but-alive HTTP call is never torn down before its handler's own
+    // deadline; everything else keeps the flat 5s missing-handler window.
     const keep = params.keep === true || isPersistentSimulatorApi(name);
     const timer = keep
         ? undefined
@@ -1287,7 +1566,7 @@ function forwardApiCallToSimulator(state, ap, page, name, params) {
             const fail = { errMsg: `${pending.name}:fail no handler (timeout)` };
             sendCallback(target, pending.callbacks.fail, fail);
             sendCallback(target, pending.callbacks.complete, fail);
-        }, API_CALL_TIMEOUT_MS);
+        }, apiCallWatchdogMs(name, params));
     state.pendingApiCalls.set(requestId, {
         appSessionId: ap.appSessionId,
         callbacks,
@@ -1360,7 +1639,20 @@ function handleApiResponse(state, sender, payload) {
         sendCallback(ap, pending.callbacks.complete, payload.result ?? { errMsg: `${pending.name}:ok` });
     }
     else {
-        const fail = { errMsg: payload.errMsg ?? `${pending.name}:fail` };
+        // The router is a transport, not an author: the simulator-side fail result
+        // (errno etc.) must reach the service callbacks intact, so spread it
+        // through instead of rebuilding a bare { errMsg }. errMsg is guaranteed
+        // non-empty — `||` (not `??`) so an empty string (e.g. an HTTP/2 response
+        // whose statusText is always '') falls through payload.errMsg →
+        // result.errMsg → the `${name}:fail` default instead of surfacing blank.
+        const result = payload.result && typeof payload.result === 'object' && !Array.isArray(payload.result)
+            ? payload.result
+            : undefined;
+        const resultErrMsg = typeof result?.errMsg === 'string' ? result.errMsg : undefined;
+        const fail = {
+            ...result,
+            errMsg: payload.errMsg || resultErrMsg || `${pending.name}:fail`,
+        };
         sendCallback(ap, pending.callbacks.fail, fail);
         sendCallback(ap, pending.callbacks.complete, fail);
     }
@@ -1544,34 +1836,22 @@ function disposePageSession(state, ap, page) {
     ap.pages.delete(page.bridgeId);
     state.pageSessions.delete(page.bridgeId);
 }
-async function disposeAppSession(state, appSessionId, opts = {}) {
-    const ap = state.appSessions.get(appSessionId);
-    if (!ap)
-        return;
-    state.appSessions.delete(appSessionId);
-    // Remove this session's shutdown-fallback registry entry so the registry does
-    // not accumulate one stale closure per respawn. Ordered AFTER the delete
-    // above: dispose() runs the wrapped fn (disposeAppSession again), which
-    // early-returns now that the session is gone — no recursion, no double-run.
-    // (At whole-app shutdown the registry marks the entry released before calling
-    // the fn, so this dispose() is a no-op then.)
-    const registryHandle = ap.registryHandle;
-    ap.registryHandle = null;
-    void registryHandle?.dispose();
-    state.appLifecycle.dispose(appSessionId);
-    // Evict AppData bridges FIRST — eviction enumerates `ap.pages`, which the
-    // page teardown below progressively empties (and finally clears).
-    state.evictAppDataBridges(ap);
-    // Drain any pending API calls owned by this app session. One-shot calls
-    // normally self-clean on response/timeout, but persistent (`keep: true`)
-    // subscriptions (e.g. audioListen) live with their timer cleared until
-    // teardown — without this they would leak in pendingApiCalls forever.
+// Drain any pending API calls owned by this app session. One-shot calls
+// normally self-clean on response/timeout, but persistent (`keep: true`)
+// subscriptions (e.g. audioListen) live with their timer cleared until
+// teardown — without this they would leak in pendingApiCalls forever.
+function drainPendingApiCallsForSession(state, appSessionId) {
     for (const [requestId, pending] of state.pendingApiCalls) {
         if (pending.appSessionId !== appSessionId)
             continue;
         clearTimeout(pending.timer);
         state.pendingApiCalls.delete(requestId);
     }
+}
+// Closes every page's render guest and drops its wc/pageSessions bindings.
+// Caller clears `ap.pages` itself right after — this only tears each page
+// down, it doesn't touch the map.
+function closeSessionPages(state, ap) {
     for (const page of ap.pages.values()) {
         if (page.renderWc && !page.renderWc.isDestroyed()) {
             state.wcIdToBridgeId.delete(page.renderWc.id);
@@ -1588,15 +1868,11 @@ async function disposeAppSession(state, appSessionId, opts = {}) {
         }
         state.pageSessions.delete(page.bridgeId);
     }
-    ap.pages.clear();
-    // Detach every session-scoped hook on emitters that outlive this session —
-    // the shared simulator WCV's 'destroyed' and the service window's 'closed' —
-    // BEFORE the window is released/closed below: a pool-recycled window must
-    // not re-trigger this session's teardown from a stale 'closed', and the
-    // simulator wc must not accumulate one dead hook per soft reload until the
-    // MaxListeners warning fires. Idempotent with teardown being triggered BY
-    // one of these hooks (removing a fired once() is a no-op).
-    ap.listenerBag.dispose();
+}
+// Three-way release of the session's service-host window: pool release (soft
+// reuse), pool reclaim of an externally-closed window, or a plain close for
+// the unpooled path.
+async function releaseServiceWindow(state, ap, opts) {
     if (ap.poolEntryId !== null && state.pool && !opts.serviceAlreadyClosed) {
         // Soft reuse (foundation.md §4.3): the pooled service-host webContents keeps
         // its wc.id but is about to run a NEW app session. Reset its Connection
@@ -1623,12 +1899,14 @@ async function disposeAppSession(state, appSessionId, opts = {}) {
         // pool only auto-reclaims on render-process-gone — so without this the in-use
         // entry leaks in the pool forever, permanently shrinking capacity. Reclaim
         // the slot explicitly (the window is already gone; releaseDestroyed won't
-        // touch it). (Audit A1)
+        // touch it).
         state.pool.releaseDestroyed(ap.poolEntryId);
     }
     else if (!opts.serviceAlreadyClosed && !ap.serviceWindow.isDestroyed()) {
         ap.serviceWindow.close();
     }
+}
+function unbindSessionFromSharedMaps(state, ap, appSessionId) {
     // Value-checked unbind for the service wc: this delete runs after the
     // pool-release await above, so on the pool path the next spawn may have
     // already re-acquired the SAME window and rebound its wc id — only remove
@@ -1645,6 +1923,42 @@ async function disposeAppSession(state, appSessionId, opts = {}) {
         if (hosted.size === 0)
             state.simulatorWcIdToAppSessionIds.delete(ap.simulatorWc.id);
     }
+}
+async function disposeAppSession(state, appSessionId, opts = {}) {
+    const ap = state.appSessions.get(appSessionId);
+    if (!ap)
+        return;
+    state.appSessions.delete(appSessionId);
+    // Prevent a leaked/stale watchdog: without this, a session disposed while
+    // still 'launching' (e.g. project close mid-launch) would fire its timer
+    // `LAUNCH_TIMEOUT_MS` later against an already-torn-down session.
+    clearLaunchTimer(ap);
+    // Remove this session's shutdown-fallback registry entry so the registry does
+    // not accumulate one stale closure per respawn. Ordered AFTER the delete
+    // above: dispose() runs the wrapped fn (disposeAppSession again), which
+    // early-returns now that the session is gone — no recursion, no double-run.
+    // (At whole-app shutdown the registry marks the entry released before calling
+    // the fn, so this dispose() is a no-op then.)
+    const registryHandle = ap.registryHandle;
+    ap.registryHandle = null;
+    void registryHandle?.dispose();
+    state.appLifecycle.dispose(appSessionId);
+    // Evict AppData bridges FIRST — eviction enumerates `ap.pages`, which the
+    // page teardown below progressively empties (and finally clears).
+    state.evictAppDataBridges(ap);
+    drainPendingApiCallsForSession(state, appSessionId);
+    closeSessionPages(state, ap);
+    ap.pages.clear();
+    // Detach every session-scoped hook on emitters that outlive this session —
+    // the shared simulator WCV's 'destroyed' and the service window's 'closed' —
+    // BEFORE the window is released/closed below: a pool-recycled window must
+    // not re-trigger this session's teardown from a stale 'closed', and the
+    // simulator wc must not accumulate one dead hook per soft reload until the
+    // MaxListeners warning fires. Idempotent with teardown being triggered BY
+    // one of these hooks (removing a fired once() is a no-op).
+    ap.listenerBag.dispose();
+    await releaseServiceWindow(state, ap, opts);
+    unbindSessionFromSharedMaps(state, ap, appSessionId);
     // Only the local fallback server needs closing; the dev-server base is owned
     // by the workspace session, not this app session.
     if (ap.resourceServer) {
@@ -1654,7 +1968,14 @@ async function disposeAppSession(state, appSessionId, opts = {}) {
     }
 }
 // ── App-config / manifest parsing ───────────────────────────────────────────
-async function loadAppConfig(resourceBase) {
+/**
+ * Fetch+parse `app-config.json`. Pure (no `ctx`, no diagnostics dependency) —
+ * a non-2xx response or a parse/network failure reports through `onUnreachable`
+ * (the caller routes it into `ctx.diagnostics`) and returns `{}` either way, so
+ * the spawn flow always continues with a manifest that just falls back to a
+ * single-page/no-tabBar shape (`buildAppManifest`'s fallback).
+ */
+async function loadAppConfig(resourceBase, onUnreachable) {
     // `resourceBase` is the dir/URL that directly contains `app-config.json`:
     // the dev server's `<base><appId>/<root>/` (http) or the local fallback
     // server root (also http). Both are HTTP, so a single fetch path covers them.
@@ -1662,23 +1983,55 @@ async function loadAppConfig(resourceBase) {
     try {
         const res = await fetch(cfgUrl);
         if (!res.ok) {
+            const error = new Error(`app-config.json fetch ${res.status} at ${cfgUrl}`);
             console.warn(`[bridge-router] no app-config.json at ${cfgUrl} (${res.status})`);
+            onUnreachable?.({ url: cfgUrl, error });
             return {};
         }
         return await res.json();
     }
     catch (error) {
         console.warn('[bridge-router] failed to fetch/parse app-config.json:', error);
+        onUnreachable?.({ url: cfgUrl, error });
         return {};
     }
 }
 function buildAppManifest(appConfig, fallbackEntry) {
     const entry = appConfig.app?.entryPagePath || fallbackEntry;
-    const pages = appConfig.app?.pages?.length ? appConfig.app.pages : [entry];
+    const hasCompiledPages = !!appConfig.app?.pages?.length;
+    const pages = hasCompiledPages ? appConfig.app.pages : [entry];
     const tabBar = appConfig.app?.tabBar && Array.isArray(appConfig.app.tabBar.list) && appConfig.app.tabBar.list.length > 0
         ? appConfig.app.tabBar
         : undefined;
-    return { entryPagePath: normalizePagePath(entry), pages: pages.map(normalizePagePath), tabBar };
+    return {
+        entryPagePath: normalizePagePath(entry),
+        pages: pages.map(normalizePagePath),
+        tabBar,
+        // 'app-config' means `pages` above is the real compiled list mount gates
+        // can trust; 'fallback' means app-config.json was unreachable and `pages`
+        // is just the single requested page — nothing to validate membership
+        // against, so every gate keyed on this source lets it through unchanged.
+        source: hasCompiledPages ? 'app-config' : 'fallback',
+    };
+}
+/**
+ * Resolve the root page a spawn actually mounts against the compiled
+ * manifest. The request is trusted verbatim unless the manifest is a real
+ * compiled one (`source === 'app-config'`) AND the request is absent from its
+ * `pages` — in that case the request is unmountable (most commonly a start
+ * page removed by a hot reload) and resolution falls back to
+ * `manifest.entryPagePath`, or `manifest.pages[0]` when even the entry isn't a
+ * member. A `'fallback'` manifest contains only the request itself, so there
+ * is trivially nothing to fall back from.
+ */
+function resolveRootPagePath(manifest, requestedPagePath) {
+    if (manifest.source !== 'app-config' || manifest.pages.includes(requestedPagePath)) {
+        return { resolvedPagePath: requestedPagePath, pageFallbackApplied: false };
+    }
+    const resolvedPagePath = manifest.pages.includes(manifest.entryPagePath)
+        ? manifest.entryPagePath
+        : manifest.pages[0];
+    return { resolvedPagePath, pageFallbackApplied: true };
 }
 function resolvePageWindowConfig(appConfig, pagePath) {
     const normalized = normalizePagePath(pagePath);