@dimina-kit/devtools 0.4.0-dev.20260703051110 → 0.4.0-dev.20260706064107

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,6 @@ 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
@@ -343,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
@@ -516,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)
@@ -562,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
@@ -573,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
@@ -589,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 = {
@@ -619,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,
@@ -704,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
@@ -722,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,
@@ -741,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);
@@ -813,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.
@@ -821,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
@@ -837,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
@@ -899,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) {
@@ -1005,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':
@@ -1024,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.)
@@ -1037,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
@@ -1153,6 +1365,14 @@ function handleNavBarApi(ap, page, name, params) {
     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
@@ -1162,11 +1382,44 @@ function sendActionOrFail(ap, eventName, payload, name, params) {
         ap.simulatorWc.send(eventName, payload);
         return;
     }
-    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`);
 }
-function handleNavActionApi(ap, page, name, params) {
+/** 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;
+        }
+    }
     const payload = {
         appSessionId: ap.appSessionId,
         bridgeId: page.bridgeId,
@@ -1243,7 +1496,7 @@ async function handleSimulatorApi(state, ap, page, body, ctx) {
         return;
     }
     if (NAV_ACTION_NAMES.has(name)) {
-        handleNavActionApi(ap, page, name, params);
+        handleNavActionApi(ap, ctx, page, name, params);
         return;
     }
     if (TAB_ACTION_NAMES.has(name)) {
@@ -1288,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
@@ -1308,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,
@@ -1381,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);
     }
@@ -1658,6 +1929,10 @@ async function disposeAppSession(state, appSessionId, opts = {}) {
     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
@@ -1693,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.
@@ -1701,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);