dsh-zen-remote 2.3.6 → 2.3.8

package/lib/index.js

@@ -34,7 +34,7 @@ import { createRelayClient, RelayError, volatileUpdateTouchesServerName } from '
 import { computeFingerprints } from './fingerprint.js';
 import { runSelfCheck, installIntercept } from './intercept.js';
 import { checkGatewayShape } from './intercept-shape.js';
-import { checkFetchRouteShape, installFetchRouteIntercept } from './fetch-route-intercept.js';
+import { checkFetchRouteShape, installFetchRouteIntercept, shouldFallbackInstall } from './fetch-route-intercept.js';
 import { checkWebServerShape, installPluginRouteIntercept } from './plugin-route-intercept.js';
 import { normalizeAdapter, adapterOwnsRegistryEntry } from './plugin-adapter-core.js';
 import { ADAPTERS } from './adapters/index.js';
@@ -56,6 +56,7 @@ import { detectForwardedSource, parseProxyList } from './wizard/source-detect.js
 import { createVerificationManager } from './wizard/verify.js';
 import { createPluginLoopback } from './plugin-loopback.js';
 import { createPluginTunnel } from './plugin-tunnel.js';
+import { createLogRing, createPluginLog } from './log-ring.js';
 import { DEFAULT_MAX_UPLOAD_BYTES } from './upload-limits.js';
 // The loader's config schema (settings form) and the role normalizer live in
 // src/config.ts next to the resolution they describe; re-exported so the
@@ -72,6 +73,20 @@ import * as gateway from '../lan-gate.mjs';
 import * as push from '../dsh-push.mjs';
 /** Exact route the phone composer POSTs one file body to. */
 export const UPLOAD_ROUTE = '/_dsh/mobile-nav/upload';
+/**
+ * This package's own version, read once off the package root (`../package.json`
+ * resolves there both from src/ under the type-stripping scripts and from the
+ * built lib/ in production). The debug report's `_meta` plate carries it —
+ * issue triage starts at "which build is this" — and the row-apply log line
+ * stamps it. Unreadable file degrades to `'unknown'`, never throws.
+ */
+let pluginVersion = 'unknown';
+try {
+    const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+    if (typeof pkg?.version === 'string' && pkg.version !== '')
+        pluginVersion = pkg.version;
+}
+catch { /* keep 'unknown' */ }
 /**
  * The one piece of cordis the typert interception needs at RUNTIME: the
  * registered symbol under which every cordis proxy answers with its raw
@@ -357,8 +372,14 @@ async function writeUpload(req, directory, filename, maxBytes) {
  *   request must ask the connection service itself, its refusal relayed
  *   verbatim — same first wall as the admin and client routes. Optional only
  *   for the direct-drive check scripts; production always passes it.
+ * @param warn - where the rejection line goes. apply() passes its double-
+ *   writer (context logger + the CU-1 log ring), so a rejected upload — the
+ *   very path issue #49 is triaged on — shows up in the debug report. The
+ *   ring is per-apply on purpose (a row reload clears it), which is why it
+ *   arrives as a parameter instead of a module singleton. Defaults to the
+ *   context logger for the direct-drive check scripts.
  */
-export async function handleUpload(ctx, maxBytes, req, res, admit) {
+export async function handleUpload(ctx, maxBytes, req, res, admit, warn) {
     if (admit !== undefined) {
         const admission = admit(req);
         if ('rejection' in admission) {
@@ -397,7 +418,10 @@ export async function handleUpload(ctx, maxBytes, req, res, admit) {
     catch (error) {
         const status = error instanceof UploadError ? error.status : 400;
         const code = error instanceof UploadError ? error.code : 'upload-rejected';
-        ctx.logger.warn('dsh-mobile-nav upload rejected: %s', message(error));
+        if (warn !== undefined)
+            warn('dsh-mobile-nav upload rejected: %s', message(error));
+        else
+            ctx.logger.warn('dsh-mobile-nav upload rejected: %s', message(error));
         responseJson(res, status, { ok: false, error: { code, message: message(error) } });
     }
 }
@@ -423,7 +447,20 @@ export async function handleUpload(ctx, maxBytes, req, res, admit) {
  *   request.
  */
 export function apply(ctx, config = {}) {
+    // CU-1: the plugin's own log ring (SPEC 方案 C) — rebuilt per apply, so a
+    // row reload clears it (expected: the report describes THIS process
+    // generation). `logWarn` / `logInfo` are the branch-shared double-writers:
+    // every line below reaches the context logger exactly as before and the
+    // ring besides, so the debug report (CU-2) can answer "what did the plugin
+    // actually log" without a log file (the desktop app writes none).
+    const ring = createLogRing();
+    const pluginLog = createPluginLog(ring, ctx.logger);
+    const logWarn = pluginLog.warn;
+    const logInfo = pluginLog.info;
     const effective = resolveConfig(config, readFileConfig(), process.env);
+    // Lifecycle: the row came up. Role and both versions are the first things
+    // an issue report needs.
+    ring.push('info', 'row apply: role=%s plugin=%s dsh=%s', effective.values.role, pluginVersion, resolveDshVersion());
     // RD-6 probe fact: whether the fetch-route inject callback (below, in the
     // client-half wiring) ever fired. On a composition where `connection` or
     // `fileUploads` never becomes available the callback stays silently
@@ -431,31 +468,45 @@ export function apply(ctx, config = {}) {
     // diagnostic stays undefined — this flag is the one honest signal of that
     // state. Declared this early because probes on BOTH role branches read it.
     let fetchRouteInjectSeen = false;
+    /** BU-1: how the fetch-route wrap got installed — `'inject'` via the
+     * primary `ctx.inject` callback, `'fallback'` via the bounded lazy timer
+     * below, `undefined` while not installed. Read live by the service probe. */
+    let fetchRouteInstalledVia;
+    /** BU-1: ISO timestamp of the moment a fallback attempt FAILED (shape
+     * refused, original unresolvable) — the tick stops after one, so this is
+     * also "the fallback gave up here". An install success does not set it. */
+    let fetchRouteFallbackTriedAt;
     /** The client branch's fetch-route diagnostics getter, assigned once that
      * branch declares it; the probe reads it lazily through this slot so both
      * role mounts can share one probe factory. */
     let fetchRouteDiagnosticsRef;
     /** RD-6: build the lazy service probe against a context whose own inject
      * already resolved (the client-routes mounts qualify on both roles). One
-     * reflection per process: `connection` / `fileUploads` presence plus the
-     * fetchRoutes table's shape — enough to name the missing service. */
+     * reflection per process for the SERVICE PRESENCE facts (below); the
+     * fetch-route facts are re-read live on every call — they change while the
+     * page is open (the inject may fire, or the fallback may step in, long
+     * after the first probe). */
     const uploadServiceProbe = (probeCtx) => {
         let cached;
         return () => {
-            if (cached !== undefined)
-                return cached;
-            const reflect = probeCtx.reflect;
-            const connection = reflect?.get('connection');
-            const fileUploads = reflect?.get('fileUploads');
+            if (cached === undefined) {
+                const reflect = probeCtx.reflect;
+                const connection = reflect?.get('connection');
+                const fileUploads = reflect?.get('fileUploads');
+                cached = {
+                    connectionService: connection === undefined ? 'absent' : 'present',
+                    fileUploadsService: fileUploads === undefined ? 'absent' : 'present',
+                    ...(connection === undefined ? {} : { connectionShape: checkFetchRouteShape(connection) }),
+                };
+            }
             const fetchRoute = fetchRouteDiagnosticsRef?.();
-            cached = {
+            return {
                 uploadInjectSeen: fetchRouteInjectSeen,
-                connectionService: connection === undefined ? 'absent' : 'present',
-                fileUploadsService: fileUploads === undefined ? 'absent' : 'present',
-                ...(connection === undefined ? {} : { connectionShape: checkFetchRouteShape(connection) }),
+                installedVia: fetchRouteInstalledVia,
+                ...(fetchRouteFallbackTriedAt === undefined ? {} : { fallbackTriedAt: fetchRouteFallbackTriedAt }),
+                ...cached,
                 ...(fetchRoute === undefined ? {} : { fetchRoute }),
             };
-            return cached;
         };
     };
     // The plugin bridge's zenRemote service (PB-1), provided on BOTH roles
@@ -475,7 +526,7 @@ export function apply(ctx, config = {}) {
     // failing the row over — the bridge stays off, everything else keeps
     // working — so it degrades to a warning like the session feeds do.
     const registry = createBridgeRegistry({
-        warn: (text) => { ctx.logger?.warn('dsh-zen-remote plugin bridge: %s', text); },
+        warn: (text) => { logWarn('dsh-zen-remote plugin bridge: %s', text); },
     });
     bridgeRegistry = registry;
     try {
@@ -485,7 +536,7 @@ export function apply(ctx, config = {}) {
         ctx.provide('zenRemote', service);
     }
     catch (error) {
-        ctx.logger?.warn('dsh-zen-remote: cannot provide the "zenRemote" service: %s', message(error));
+        logWarn('dsh-zen-remote: cannot provide the "zenRemote" service: %s', message(error));
     }
     ctx.effect(() => () => {
         if (bridgeRegistry === registry)
@@ -510,7 +561,7 @@ export function apply(ctx, config = {}) {
     // halves.
     const adapters = [];
     {
-        const adapterWarn = (text) => { ctx.logger?.warn('dsh-zen-remote adapter: %s', text); };
+        const adapterWarn = (text) => { logWarn('dsh-zen-remote adapter: %s', text); };
         for (const adapter of ADAPTERS) {
             try {
                 const holder = ctx;
@@ -560,10 +611,10 @@ export function apply(ctx, config = {}) {
                 registry.registerNormalized(normalized.declaration);
                 adapters.push(normalized);
                 if (unlisted && surfaceDigest !== undefined) {
-                    ctx.logger?.info('dsh-zen-remote adapter: %s bridged by surface digest %s (version %s unlisted)', normalized.plugin, surfaceDigest, installedVersion);
+                    logInfo('dsh-zen-remote adapter: %s bridged by surface digest %s (version %s unlisted)', normalized.plugin, surfaceDigest, installedVersion);
                 }
                 else {
-                    ctx.logger?.info('dsh-zen-remote adapter: %s adapted at version %s', normalized.plugin, installedVersion);
+                    logInfo('dsh-zen-remote adapter: %s adapted at version %s', normalized.plugin, installedVersion);
                 }
             }
             catch (error) {
@@ -571,6 +622,19 @@ export function apply(ctx, config = {}) {
             }
         }
     }
+    // CU-3: the debug-report route's profile fact — read per call through the
+    // reflection layer's store lookup (a composition without profileContext
+    // answers undefined, and a throwing read degrades to undefined too).
+    const profileName = () => {
+        try {
+            const holder = ctx;
+            const profile = holder.get?.('profileContext');
+            return typeof profile?.name === 'string' && profile.name !== '' ? profile.name : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    };
     if (effective.values.role === 'host') {
         // A row that switched from client to host must not leave a stale relay
         // client where getRelayClient() can find it (T23a-fix).
@@ -579,7 +643,27 @@ export function apply(ctx, config = {}) {
         // gateway child through LAN_GATE_RELAY_SECRET and kept here for the
         // relay routes below. The push half never sees it.
         const relaySecret = randomBytes(32).toString('hex');
-        ctx.plugin(gateway, { ...effective.values, relaySecret });
+        // CU-1 lifecycle: the gateway child's spawn/exit, reported back through
+        // this hook (lan-gate.mjs reads it off the config object it is handed).
+        // The child runs in a subprocess whose console the ring cannot see, so
+        // these two lines are the debug report's only record of it. Either call
+        // must never break the gateway half — lan-gate.mjs guards its side, we
+        // guard ours. The hook rides as a NON-enumerable property: it is wiring,
+        // not configuration — the gateway's config stays exactly "resolved values
+        // + relaySecret" for every spread, deep compare and serialization (the
+        // role-wiring test pins that shape), while a direct read still finds it.
+        const gatewayEvent = (event, detail) => {
+            try {
+                if (event === 'spawn')
+                    ring.push('info', 'gateway spawned (port=%s)', String(detail.port ?? '?'));
+                else
+                    ring.push('warn', 'gateway exited (code=%s signal=%s error=%s)', String(detail.code ?? '—'), String(detail.signal ?? '—'), String(detail.error ?? '—'));
+            }
+            catch { /* the ring must never break the wiring */ }
+        };
+        const gatewayConfig = { ...effective.values, relaySecret };
+        Object.defineProperty(gatewayConfig, 'gatewayEvent', { value: gatewayEvent, enumerable: false });
+        ctx.plugin(gateway, gatewayConfig);
         ctx.plugin(push, effective.values);
         // The shared-session table backing the relay's access control. The relay
         // route consumes it below; the activity tracker and idle sweeper (T22c)
@@ -624,7 +708,7 @@ export function apply(ctx, config = {}) {
             });
         }
         catch (error) {
-            ctx.logger.warn('dsh-zen-remote cannot listen on "session/event": %s', message(error));
+            logWarn('dsh-zen-remote cannot listen on "session/event": %s', message(error));
         }
         // Auto-share and fork-following (T33a), off `agent/created` — the only
         // host event that fires EXACTLY ONCE per NEW session. Its `source` is
@@ -664,12 +748,12 @@ export function apply(ctx, config = {}) {
                     });
                 }
                 catch (error) {
-                    ctx.logger.warn('dsh-zen-remote cannot share new session "%s": %s', agent.id, message(error));
+                    logWarn('dsh-zen-remote cannot share new session "%s": %s', agent.id, message(error));
                 }
             });
         }
         catch (error) {
-            ctx.logger.warn('dsh-zen-remote cannot listen on "agent/created": %s', message(error));
+            logWarn('dsh-zen-remote cannot listen on "agent/created": %s', message(error));
         }
         // Busy restore (T33a): `busy` is never persisted, so right after a row
         // restart every shared session believes itself idle — including one whose
@@ -690,7 +774,7 @@ export function apply(ctx, config = {}) {
             ctx.inject(['sessionPersistence'], (persistenceCtx) => {
                 const persistence = persistenceCtx.sessionPersistence;
                 if (persistence === undefined) {
-                    ctx.logger.warn('dsh-zen-remote: no sessionPersistence service — pre-restart subagent sessions stay not-shared until they emit an event');
+                    logWarn('dsh-zen-remote: no sessionPersistence service — pre-restart subagent sessions stay not-shared until they emit an event');
                     return;
                 }
                 void persistence
@@ -698,13 +782,13 @@ export function apply(ctx, config = {}) {
                     .then((snapshots) => {
                     const recorded = seedParentIndexFromSnapshots(parentIndex, snapshots);
                     if (recorded > 0)
-                        ctx.logger.info?.('dsh-zen-remote: restored %d persisted parent links', recorded);
+                        logInfo('dsh-zen-remote: restored %d persisted parent links', recorded);
                 })
-                    .catch((error) => ctx.logger.warn('dsh-zen-remote cannot seed parent links from persisted sessions: %s', message(error)));
+                    .catch((error) => logWarn('dsh-zen-remote cannot seed parent links from persisted sessions: %s', message(error)));
             });
         }
         catch (error) {
-            ctx.logger.warn('dsh-zen-remote cannot listen on "sessionPersistence": %s', message(error));
+            logWarn('dsh-zen-remote cannot listen on "sessionPersistence": %s', message(error));
         }
         // Settings-surface admin routes (T14). The browser cannot call the
         // gateway's loopback-only admin API from DSH's origin, so the host
@@ -1132,6 +1216,39 @@ export function apply(ctx, config = {}) {
                 };
             }, 'dsh-zen-remote: relay route');
         });
+        // CU-3 (host mount): the gateway child's summary plate for the debug
+        // report — one best-effort probe of the gateway's own status endpoint
+        // (the same seam the wizard's runtime probe reads) reduced to liveness,
+        // port and COUNTS. The endpoint's device rows carry no tokens and we
+        // keep none of their fields anyway; the share table's size is read off
+        // the store this apply owns. The gateway being down IS the summary.
+        const gatewaySummary = async () => {
+            let reachable = false;
+            let port;
+            let deviceCount;
+            let pushSubscriptions;
+            try {
+                const response = await fetch(`http://127.0.0.1:${effective.values.port}/lan-gate/status`, { signal: AbortSignal.timeout(3000) });
+                reachable = response.ok;
+                if (reachable) {
+                    const body = await response.json();
+                    if (typeof body?.port === 'number')
+                        port = body.port;
+                    if (Array.isArray(body?.devices))
+                        deviceCount = body.devices.length;
+                    if (typeof body?.pushSubscriptions === 'number')
+                        pushSubscriptions = body.pushSubscriptions;
+                }
+            }
+            catch { /* unreachable is an honest answer */ }
+            return {
+                reachable,
+                ...(port === undefined ? {} : { port }),
+                ...(deviceCount === undefined ? {} : { deviceCount }),
+                ...(pushSubscriptions === undefined ? {} : { pushSubscriptions }),
+                shareCount: store.list().length,
+            };
+        };
         // The remote-status route lives on BOTH roles (T34-fix): it is what the
         // client-half parts poll, and a desktop app can switch roles without a
         // code path change — on a host it reads the empty
@@ -1150,6 +1267,10 @@ export function apply(ctx, config = {}) {
                     getRowConfig: () => config,
                     remoteStatusOnly: true,
                     getServiceProbe: uploadServiceProbe(clientCtx),
+                    getLogSnapshot: () => ring.snapshot(),
+                    getGatewaySummary: gatewaySummary,
+                    getProfileName: profileName,
+                    getPluginVersion: () => pluginVersion,
                 }),
             }), 'dsh-zen-remote: client routes (host)');
         });
@@ -1191,6 +1312,24 @@ export function apply(ctx, config = {}) {
         // and `online` is the client's CURRENT state — so a registry change, a
         // fresh handshake or a link flip shows up at the very next read.
         const pluginBridgeStatus = () => compareBridges(registry.list(), relayClient.handshakeInfo?.plugins, relayClient.state === 'online');
+        // CU-1 lifecycle: the relay link's flips enter the ring — `online` with
+        // the server id it handshook, `offline` with the mapped failure code
+        // (relayClient.lastError is a short code by contract, never free text).
+        // subscribe re-announces the CURRENT state when only the handshake
+        // identity moved (the T59 heartbeat), so the dedupe below keeps the
+        // heartbeats out of the ring: one line per actual state change.
+        let lastRelayRingState;
+        const offRelayRing = relayClient.subscribe((state) => {
+            if (state === lastRelayRingState)
+                return;
+            lastRelayRingState = state;
+            if (state === 'online') {
+                ring.push('info', 'relay link online (server=%s)', relayClient.handshakeInfo?.serverId ?? '?');
+            }
+            else if (state === 'offline') {
+                ring.push('warn', 'relay link offline (code=%s)', relayClient.lastError ?? '?');
+            }
+        });
         // A stopped or reloaded row must not leave a stale instance where the
         // module getter can hand it out (T23a-fix), and its reconnect machinery
         // (T43) must not outlive the row either: stop() cancels the armed retry
@@ -1198,6 +1337,7 @@ export function apply(ctx, config = {}) {
         // dispose from clearing a NEWER row's instance that a reload already
         // installed.
         ctx.effect(() => () => {
+            offRelayRing();
             relayClient.stop();
             if (clientRelayClient === relayClient)
                 clientRelayClient = undefined;
@@ -1237,7 +1377,7 @@ export function apply(ctx, config = {}) {
                 };
             }
             catch (error) {
-                ctx.logger.warn('dsh-zen-remote: cannot listen on "loader/volatile-update" for relay credentials: %s', message(error));
+                logWarn('dsh-zen-remote: cannot listen on "loader/volatile-update" for relay credentials: %s', message(error));
                 return () => { };
             }
         }, 'dsh-zen-remote: relay credentials watcher');
@@ -1249,7 +1389,7 @@ export function apply(ctx, config = {}) {
             if (error instanceof RelayError && error.code === 'unpaired')
                 return;
             const code = error instanceof RelayError ? error.code : 'error';
-            ctx.logger.warn('dsh-zen-remote relay client initial connect failed (%s): %s', code, message(error));
+            logWarn('dsh-zen-remote relay client initial connect failed (%s): %s', code, message(error));
         });
         // The typertGateway interception (T23b-1): remote-session calls ride the
         // relay, everything else reaches the local gateway untouched. The live
@@ -1316,9 +1456,6 @@ export function apply(ctx, config = {}) {
             return undefined;
         };
         ctx.inject(['typertGateway'], (gatewayCtx) => {
-            // Degraded logging: the real cordis context always carries a logger,
-            // but a row fake without one must not crash apply.
-            const logWarn = (...args) => { ctx.logger?.warn(...args); };
             const proxy = gatewayCtx.typertGateway;
             const raw = proxy !== null && typeof proxy === 'object'
                 ? proxy[symbols.original]
@@ -1344,7 +1481,7 @@ export function apply(ctx, config = {}) {
                 // PB-25b: each merged stream reports its real-session inventory
                 // share into the union above.
                 createSessionInventorySlot,
-                log: (format, ...args) => { ctx.logger?.info(`dsh-zen-remote ${format}`, ...args); },
+                log: (format, ...args) => { logInfo(`dsh-zen-remote ${format}`, ...args); },
             });
             interceptHandle = handle;
             gatewayCtx.effect(() => () => {
@@ -1367,7 +1504,7 @@ export function apply(ctx, config = {}) {
             void runSelfCheck(raw, {
                 handle,
                 log: logWarn,
-                info: (format, ...args) => { ctx.logger?.info(`dsh-zen-remote ${format}`, ...args); },
+                info: (format, ...args) => { logInfo(`dsh-zen-remote ${format}`, ...args); },
                 getPeer: createOwnerPeerSource(() => gatewayCtx.reflect.get('connection')),
             });
         });
@@ -1411,8 +1548,13 @@ export function apply(ctx, config = {}) {
         fetchRouteDiagnosticsRef = fetchRouteDiagnostics;
         ctx.inject(['connection', 'fileUploads'], (connectionCtx) => {
             fetchRouteInjectSeen = true;
-            const logWarn = (...args) => { ctx.logger?.warn(...args); };
-            const logInfo = (...args) => { ctx.logger?.info(...args); };
+            // BU-1 double-install guard: the fallback timer may have installed
+            // while this callback sat PENDING — or recorded a refusal. Either way
+            // this primary path has nothing left to do; installing again would
+            // chain a second wrap over the first (behaviorally right, structurally
+            // dirty) and overwrite the diagnostics' installedVia.
+            if (fetchRouteHandle !== undefined || fetchRouteRefused !== undefined)
+                return;
             const proxy = connectionCtx.connection;
             const raw = proxy !== null && typeof proxy === 'object'
                 ? proxy[symbols.original]
@@ -1438,12 +1580,112 @@ export function apply(ctx, config = {}) {
                 log: (format, ...args) => { logInfo(`dsh-zen-remote ${format}`, ...args); },
             });
             fetchRouteHandle = handle;
+            fetchRouteInstalledVia = 'inject';
+            // CU-1 lifecycle: a successful install logs nothing today (the wrap's
+            // own log lines only fire per call), so the ring gets one explicit
+            // record — the debug report's "did the redirect actually attach" fact.
+            // The refused and fallback paths funnel through logWarn/logInfo below
+            // and enter the ring that way.
+            ring.push('info', 'fetch-route intercept attached (via=inject)');
             connectionCtx.effect(() => () => {
                 handle.uninstall();
-                if (fetchRouteHandle === handle)
+                if (fetchRouteHandle === handle) {
                     fetchRouteHandle = undefined;
+                    fetchRouteInstalledVia = undefined;
+                }
             }, 'dsh-zen-remote: fetch-route intercept');
         });
+        // BU-1: the fetch-route FALLBACK install (SPEC §2). RD-6 proved the
+        // machine-local failure mode: on one Windows client the
+        // `['connection','fileUploads']` inject above sat silently PENDING (a
+        // stuck row keeps cordis waiting forever, printing nothing), the wrap
+        // never installed, and every remote upload fell through to the local
+        // backend. The inject stays the FIRST choice — this timer only acts when
+        // it demonstrably has not fired while BOTH services are present in the
+        // reflection layer, then installs through the same
+        // checkFetchRouteShape → symbols.original → installFetchRouteIntercept
+        // path, sharing the handle/refused slots (which is also the
+        // double-install guard: whichever path runs first, the other sees the
+        // slots set and stands down). Bounded: a 3 s tick, at most 20 (a minute)
+        // — a composition that never ships the services stops probing; unref'd
+        // and cleared with the row.
+        let fallbackTimer;
+        let fallbackAttempts = 0;
+        const stopFallbackTimer = () => {
+            if (fallbackTimer !== undefined) {
+                clearInterval(fallbackTimer);
+                fallbackTimer = undefined;
+            }
+        };
+        fallbackTimer = setInterval(() => {
+            // The tick budget is checked BEFORE acting but does not cancel the
+            // current tick: attempt #20 still runs, no tick #21 ever comes.
+            fallbackAttempts += 1;
+            if (fallbackAttempts >= 20)
+                stopFallbackTimer();
+            // Same reflection the service probe reads: both services must be
+            // PRESENT — their absence means a legitimate startup wait (or a
+            // composition without them), where the inject must stay first choice.
+            const reflect = ctx.reflect;
+            const connection = reflect?.get('connection');
+            const fileUploads = reflect?.get('fileUploads');
+            if (!shouldFallbackInstall({
+                injectSeen: fetchRouteInjectSeen,
+                handleSet: fetchRouteHandle !== undefined,
+                refused: fetchRouteRefused !== undefined,
+                servicesPresent: connection !== undefined && fileUploads !== undefined,
+            })) {
+                // The services being absent is a WAIT (next tick re-judges); the
+                // primary path having advanced is a VERDICT — the fallback has no
+                // business left, stop probing.
+                if (fetchRouteInjectSeen || fetchRouteHandle !== undefined || fetchRouteRefused !== undefined)
+                    stopFallbackTimer();
+                return;
+            }
+            // Shape against the proxy first (fetchRoutes reads through it); the
+            // raw instance comes off the same symbols slot the inject path uses.
+            const shape = checkFetchRouteShape(connection);
+            if (!shape.ok) {
+                // Structural mismatch is a verdict, not a wait: record the attempt
+                // and stop. A later inject trigger may still install (it checks the
+                // RAW instance, which can differ from what the proxy exposed).
+                fetchRouteFallbackTriedAt = new Date().toISOString();
+                stopFallbackTimer();
+                logWarn('dsh-zen-remote fetch-route fallback declined: %s', shape.reasons.join('; '));
+                return;
+            }
+            const raw = connection !== null && typeof connection === 'object'
+                ? connection[symbols.original]
+                : undefined;
+            if (raw === null || typeof raw !== 'object') {
+                fetchRouteFallbackTriedAt = new Date().toISOString();
+                stopFallbackTimer();
+                logWarn('dsh-zen-remote fetch-route fallback declined: %s', 'original: connection[symbols.original] is not an object');
+                return;
+            }
+            const handle = installFetchRouteIntercept({
+                connection: raw,
+                relay: relayClient,
+                getServerId: () => relayClient.handshakeInfo?.serverId,
+                log: (format, ...args) => { logInfo(`dsh-zen-remote ${format}`, ...args); },
+            });
+            fetchRouteHandle = handle;
+            fetchRouteInstalledVia = 'fallback';
+            stopFallbackTimer();
+            logInfo('dsh-zen-remote fetch-route intercept installed via the fallback timer (inject never fired)');
+            // Same disposal contract as the inject path: the wrap dies with the
+            // row (the fallback has no service context of its own to hang on).
+            ctx.effect(() => () => {
+                handle.uninstall();
+                if (fetchRouteHandle === handle) {
+                    fetchRouteHandle = undefined;
+                    fetchRouteInstalledVia = undefined;
+                }
+            }, 'dsh-zen-remote: fetch-route intercept (fallback)');
+        }, 3_000);
+        if (typeof fallbackTimer.unref === 'function')
+            fallbackTimer.unref();
+        ctx.effect(() => () => { stopFallbackTimer(); }, 'dsh-zen-remote: fetch-route fallback timer');
         // The plugin bridge's route interception (PB-4): the local webServer's
         // `match` wrap forwarding bridged-plugin requests for REMOTE sessions
         // through the relay. Injected on `webServer` alone — the only service
@@ -1475,7 +1717,6 @@ export function apply(ctx, config = {}) {
             return undefined;
         };
         ctx.inject(['webServer'], (wsCtx) => {
-            const logWarn = (...args) => { ctx.logger?.warn(...args); };
             const proxy = wsCtx.webServer;
             const raw = proxy !== null && typeof proxy === 'object'
                 ? proxy[symbols.original]
@@ -1514,7 +1755,7 @@ export function apply(ctx, config = {}) {
                 // client's only early notice of a row that rides no workspace/follow
                 // frame — hand it to the summary sync so the sidebar row appears.
                 onMintedVirtualIds: (ids) => { interceptHandle?.nudgeSummarySync(ids); },
-                log: (format, ...args) => { ctx.logger?.info(`dsh-zen-remote ${format}`, ...args); },
+                log: (format, ...args) => { logInfo(`dsh-zen-remote ${format}`, ...args); },
             });
             pluginRouteHandle = handle;
             wsCtx.effect(() => () => {
@@ -1537,6 +1778,9 @@ export function apply(ctx, config = {}) {
                     getPluginRouteIntercept: pluginRouteDiagnostics,
                     getPluginBridgeStatus: pluginBridgeStatus,
                     onCurrentSession,
+                    getLogSnapshot: () => ring.snapshot(),
+                    getProfileName: profileName,
+                    getPluginVersion: () => pluginVersion,
                 }),
             }), 'dsh-zen-remote: client routes');
         });
@@ -1563,18 +1807,22 @@ export function apply(ctx, config = {}) {
     // dispose-and-reload entry. A fake context without a fiber (the route
     // tests) only ever reaches the warn.
     const reload = () => {
+        // CU-1 lifecycle: the row is about to reload — the ring dies with this
+        // apply right after, so this line is the reload's only witness in the
+        // NEXT generation's report (the fresh apply's row-apply line follows).
+        ring.push('info', 'row reload: a restart-required setting changed, reloading the plugin row');
         const fiber = ctx.fiber;
         if (fiber?.restart === undefined) {
-            ctx.logger.warn('dsh-zen-remote: a restart-required setting changed, but no fiber is available to reload the plugin row');
+            logWarn('dsh-zen-remote: a restart-required setting changed, but no fiber is available to reload the plugin row');
             return;
         }
         try {
             Promise.resolve(fiber.restart()).catch((error) => {
-                ctx.logger.warn('dsh-zen-remote: plugin row reload failed: %s', message(error));
+                logWarn('dsh-zen-remote: plugin row reload failed: %s', message(error));
             });
         }
         catch (error) {
-            ctx.logger.warn('dsh-zen-remote: plugin row reload failed: %s', message(error));
+            logWarn('dsh-zen-remote: plugin row reload failed: %s', message(error));
         }
     };
     ctx.effect(() => {
@@ -1588,7 +1836,7 @@ export function apply(ctx, config = {}) {
             ctx.on('loader/volatile-update', () => { watcher.checkNow(); });
         }
         catch (error) {
-            ctx.logger.warn('dsh-zen-remote: cannot listen on "loader/volatile-update": %s', message(error));
+            logWarn('dsh-zen-remote: cannot listen on "loader/volatile-update": %s', message(error));
         }
         return watcher.stop;
     }, 'dsh-zen-remote: restart watcher');
@@ -1614,7 +1862,7 @@ export function apply(ctx, config = {}) {
                 // and a rejection escaping it must reach webServer's unified error
                 // handling instead of vanishing into an unhandled rejection (T17b
                 // restored the await-shaped contract the route used to have).
-                return handleUpload(webCtx, maxBytes, req, res, (admitReq) => webCtx.connection.admit(admitReq));
+                return handleUpload(webCtx, maxBytes, req, res, (admitReq) => webCtx.connection.admit(admitReq), logWarn);
             },
         }), 'dsh-mobile-nav: upload route');
     });