@reticlehq/server 3.8.1 → 3.9.0

package/dist/portal/pool/page-error-journal.js

@@ -0,0 +1,181 @@
+/**
+ * Journal the uncaught page errors the SDK was never installed in time to see.
+ *
+ * An app whose module graph throws during the first navigation fires its `error` event while the
+ * page still has no Reticle SDK in it — the zero-install reader is only evaluated after `goto`
+ * resolves. The agent then saw a blank page and a bare console-error count, and had to re-run the
+ * app under `--enable-logging` to learn why (#1966). The pool's Playwright handle is attached
+ * before the navigation, so the server is the one witness that cannot miss the throw.
+ *
+ * The pool hands errors here with the lease id. The session for that lease usually does not exist
+ * yet, so errors buffer per lease and flush the moment the session connects
+ * (`bridge.attachSessionCreate`). One already connected means the error is journaled at once.
+ *
+ * The daemon runs for days, so both maps are told to forget: a lease that is released or reaped
+ * has its buffer dropped (`onLeaseClosed`), and a session that has ended has its dedupe memory
+ * dropped (`onSessionEnd`). Without those, every failed lease and every ended session leaves an
+ * entry behind forever.
+ *
+ * Deduplication: when the SDK IS installed it reports the same throw as `error.uncaught` — with
+ * the browser's `Uncaught ` prefix on the message, which Playwright's spelling lacks. Both
+ * spellings fold into one identity (`uncaughtIdentity`), and whichever source is seen first
+ * suppresses the other's copy. A journal write is deferred by a short window first, so an SDK
+ * event racing the page error lands inside the window and wins. The reverse race — our copy
+ * first, the SDK's right after — can still journal both; the SDK's own event is authoritative and
+ * only the redundant second copy is cost, not wrong evidence.
+ */
+import { CONSOLE_EVENT, EventType, RETICLE_URL_PARAM } from '@reticlehq/core';
+/** How many errors wait per lease for a session that may never connect. Older ones give way. */
+const MAX_BUFFERED_PER_LEASE = 8;
+/** How many recent error identities a session tracks — the dedupe memory for both sources. */
+const MAX_TRACKED_IDENTITIES = 32;
+/**
+ * How long a journal write waits before committing, so an SDK event for the same throw — the
+ * websocket hop against a CDP callback — can arrive first and claim the identity.
+ */
+const DEDUPE_WAIT_MS = 50;
+/**
+ * Fold the two spellings of one throw into one identity. Chromium prefixes a window-reported
+ * uncaught error with `Uncaught ` and often the error class (`Uncaught TypeError: ...`); the
+ * Playwright `pageerror` message is the bare exception text. Everything after the first line is a
+ * stack fragment and never matches, so it is dropped.
+ */
+export function uncaughtIdentity(rawMessage) {
+    const withoutPrefix = rawMessage.replace(/^Uncaught\s+/i, '');
+    const firstLine = withoutPrefix.split('\n')[0] ?? withoutPrefix;
+    // Lazy `*?`: the greedy spelling cannot match a BARE `Error: ` — the leading character class
+    // eats the `E` and backtracking never gives it back.
+    return firstLine.replace(/^[A-Za-z0-9_]*?(?:Error|Exception):\s*/, '');
+}
+/** The first stack frame's file and line — the `source (file:line)` the issue asks the agent to see. */
+const STACK_FRAME = /\bat\s+(\S+?):(\d+):\d+\b/;
+function originOf(stack) {
+    if (stack === undefined) {
+        return {};
+    }
+    const frame = STACK_FRAME.exec(stack);
+    const source = frame?.[1];
+    const line = frame?.[2];
+    if (source === undefined || line === undefined) {
+        return {};
+    }
+    return { source, line: Number(line) };
+}
+function leaseParamOf(url) {
+    if (url === undefined) {
+        return undefined;
+    }
+    try {
+        return new URL(url).searchParams.get(RETICLE_URL_PARAM.SESSION) ?? undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+const realSleep = (ms) => {
+    return new Promise((resolve) => {
+        setTimeout(resolve, ms);
+    });
+};
+export function makePageErrorJournal(deps) {
+    const sleep = deps.sleep ?? realSleep;
+    /** Errors heard before their session connected, keyed by lease id. */
+    const buffered = new Map();
+    /** Per session: identities already claimed by the SDK or by us, oldest first. */
+    const seen = new Map();
+    const mark = (sessionId, identity) => {
+        const identities = seen.get(sessionId) ?? [];
+        if (identities.includes(identity)) {
+            return;
+        }
+        identities.push(identity);
+        if (identities.length > MAX_TRACKED_IDENTITIES) {
+            identities.shift();
+        }
+        seen.set(sessionId, identities);
+    };
+    const seenBefore = (sessionId, identity) => {
+        return (seen.get(sessionId) ?? []).includes(identity);
+    };
+    const journal = async (session, error, droppedCount) => {
+        await sleep(DEDUPE_WAIT_MS);
+        const identity = uncaughtIdentity(error.message);
+        if (seenBefore(session.id, identity)) {
+            return;
+        }
+        mark(session.id, identity);
+        const { source, line } = originOf(error.stack);
+        session.pushEvent({
+            t: 0, // pushEvent re-stamps with the session's own clock
+            type: EventType.CONSOLE_ERROR,
+            sessionId: session.id,
+            data: {
+                message: error.message,
+                kind: CONSOLE_EVENT.PAGE_ERROR,
+                ...(error.stack === undefined ? {} : { stack: error.stack }),
+                ...(source === undefined ? {} : { source }),
+                ...(line === undefined ? {} : { line }),
+                ...(droppedCount === undefined
+                    ? {}
+                    : { [CONSOLE_EVENT.DROPPED_PAGE_ERRORS]: droppedCount }),
+            },
+        });
+    };
+    // A page error must never break the connect path or the session that receives it.
+    const journalSafely = (session, error, droppedCount) => {
+        journal(session, error, droppedCount).catch(() => undefined);
+    };
+    return {
+        onPoolPageError(leaseId, error) {
+            const session = deps.resolveSession(leaseId);
+            if (session !== undefined) {
+                journalSafely(session, error);
+                return;
+            }
+            const entry = buffered.get(leaseId) ?? { errors: [], dropped: 0 };
+            if (entry.errors.length >= MAX_BUFFERED_PER_LEASE) {
+                entry.errors.shift();
+                entry.dropped += 1;
+            }
+            entry.errors.push(error);
+            buffered.set(leaseId, entry);
+        },
+        onSessionCreate(session) {
+            // Claim identities the SDK reports, so a page error the SDK already journaled adds no copy.
+            session.onEvent((event) => {
+                if (event.type !== EventType.ERROR_UNCAUGHT) {
+                    return;
+                }
+                const message = event.data['message'];
+                if ('string' !== typeof message) {
+                    return;
+                }
+                mark(session.id, uncaughtIdentity(message));
+            });
+            const leaseId = leaseParamOf(session.url);
+            if (leaseId === undefined) {
+                return;
+            }
+            const entry = buffered.get(leaseId);
+            if (entry === undefined) {
+                return;
+            }
+            buffered.delete(leaseId);
+            // The buffer is bounded, so a page that threw harder than the bound reports the loss on the
+            // first error that survived — the count names what the agent is not seeing.
+            entry.errors.forEach((error, i) => {
+                journalSafely(session, error, 0 === i && entry.dropped > 0 ? entry.dropped : undefined);
+            });
+        },
+        // A lease that is released or reaped will never flush: its session already ended, or its page
+        // died before any SDK connected. The buffer has nowhere to go, so it goes away.
+        onLeaseClosed(leaseId) {
+            buffered.delete(leaseId);
+        },
+        // The dedupe memory belongs to one session's lifetime; an ended session's identities would
+        // otherwise suppress nothing real and grow for the life of the daemon.
+        onSessionEnd(sessionId) {
+            seen.delete(sessionId);
+        },
+    };
+}

package/dist/portal/pool/playwright-launcher.js

@@ -8,11 +8,13 @@
 import { BrowserLaunchKind } from '@reticlehq/core/telemetry';
 import { ActionType, HIDE_RETICLE_CHROME_CSS, RETICLE_OVERLAY_SELECTOR } from '@reticlehq/core';
 import { launchChromium } from '../../launch-chromium.js';
+import { pageViewportOptions } from '../../chromium-launch-options.js';
 import { getSessionMetrics } from '../../telemetry/session-metrics.js';
 import { classifyConnectFailure } from '../../telemetry/connect-failure.js';
 import { chromiumInstallCommand, chromiumInstallDepsCommand, bundledPlaywrightVersion, } from '../../command/cli/doctor/browser/chromium-hint.js';
 import { installNetworkMocks } from '../input/network-mock.js';
-import { performGesture } from '../input/real-input.js';
+import { performGesture, withChromePassThrough, } from '../input/real-input.js';
+import { widenDocumentCsp } from './csp-widen.js';
 /** A key addresses focus, not a point; the gesture driver takes a box for every action. */
 const NO_BOX = { x: 0, y: 0, width: 0, height: 0 };
 const sleepFor = (ms) => new Promise((r) => setTimeout(r, ms));
@@ -91,17 +93,17 @@ export function gotoOptions(timeoutMs) {
         ...(timeoutMs === undefined ? {} : { timeout: timeoutMs }),
     };
 }
-function wrapBrowser(browser) {
+function wrapBrowser(browser, headless) {
     return {
         isConnected: () => browser.isConnected(),
         newContext: async (opts) => {
             // Media and viewport ride on the context, so the first paint of the first page has them.
             const { ignoreHTTPSErrors, ...emulate } = opts ?? {};
-            const contextOpts = {
+            const context = await browser.newContext({
                 ...(true === ignoreHTTPSErrors ? { ignoreHTTPSErrors: true } : {}),
                 ...emulate,
-            };
-            const context = await browser.newContext(0 < Object.keys(contextOpts).length ? contextOpts : undefined);
+                ...pageViewportOptions(headless, emulate.viewport),
+            });
             return {
                 newPage: async () => {
                     const page = await context.newPage();
@@ -121,11 +123,12 @@ function wrapBrowser(browser) {
                         },
                         // Three moves, same as performGesture: a single move to the center can be a no-op if
                         // the pointer was already there, and CSS :hover needs a native hit-test to apply.
-                        hover: async (x, y) => {
+                        // Through Reticle's own UI, like every other real gesture (#992).
+                        hover: (x, y) => withChromePassThrough(page, async () => {
                             await page.mouse.move(x, y);
                             await page.mouse.move(x + 1, y);
                             await page.mouse.move(x, y);
-                        },
+                        }),
                         // The same driver `reticle drive` presses with, so a held key and a chord read alike.
                         emulateMedia: (media) => page.emulateMedia(media),
                         press: (args) => performGesture(page, ActionType.PRESS, NO_BOX, args, sleepFor),
@@ -148,6 +151,12 @@ function wrapBrowser(browser) {
                         bringToFront: () => page.bringToFront(),
                         onCrash: (handler) => page.on('crash', handler),
                         onConsole: (handler) => page.on('console', (msg) => handler(msg.text())),
+                        // Playwright's `pageerror` carries the full exception even when the page's own window
+                        // listener never ran — the import-time throw that lands before any SDK is injected.
+                        onPageError: (handler) => page.on('pageerror', (error) => handler({
+                            message: error.message,
+                            ...(error.stack === undefined ? {} : { stack: error.stack }),
+                        })),
                         onDialog: (handler) => page.on('dialog', (dialog) => handler({ message: dialog.message(), dismiss: () => dialog.dismiss() })),
                         addInitScript: async (script, arg) => {
                             const handle = (await page.addInitScript(script, arg));
@@ -162,6 +171,10 @@ function wrapBrowser(browser) {
                 addCookies: (cookies) => context.addCookies(cookies),
                 grantPermissions: (permissions, opts) => context.grantPermissions(permissions, opts),
                 clearPermissions: () => context.clearPermissions(),
+                // On the context, so a page route that falls back still reaches it. See csp-widen.ts.
+                widenCsp: async (origin, onWidened) => {
+                    await context.route(ANY_URL, (route) => widenDocumentCsp(route, origin, onWidened));
+                },
                 close: () => context.close(),
             };
         },
@@ -233,7 +246,7 @@ export function playwrightLauncher(opts = {}) {
         // number that actually costs memory and the one that explains a slow machine.
         const settle = getSessionMetrics().recordConnectAttempt(BrowserLaunchKind.POOLED);
         try {
-            const browser = wrapBrowser(await launchChromium(chromium, headless));
+            const browser = wrapBrowser(await launchChromium(chromium, headless), headless);
             settle();
             return browser;
         }

package/dist/portal/pool/pool-contract.d.ts

@@ -21,6 +21,14 @@ export interface PooledPage {
      * "the page said nothing", never as "the page dialled correctly".
      */
     onConsole?(handler: (text: string) => void): void;
+    /**
+     * Fires for each error the page threw with no handler for it — an import-time module throw
+     * included. OPTIONAL like `onConsole`: a fake without it makes the pool hear nothing, which
+     * degrades to the old behaviour instead of inventing an error nobody reported. The handler must
+     * be installed BEFORE the first navigation — an import-time throw lands during `goto`, and a
+     * listener attached after it reads a broken page as healthy (#1966).
+     */
+    onPageError?(handler: (error: PooledPageError) => void): void;
     /**
      * Capture the page as a PNG, or a JPEG at `jpegQuality` (a live picture, where size matters more). OPTIONAL, like `onConsole`: a fake that does not implement it makes
      * the pool report "no provider", which is the correct degradation — an absent screenshotter must
@@ -91,6 +99,14 @@ export interface PooledDialog {
     readonly message: string;
     dismiss(): Promise<void>;
 }
+/**
+ * One uncaught error the page threw, as the engine reported it. The message is the exception text
+ * without the console's `Uncaught ` prefix; the stack is present when the engine had one.
+ */
+export interface PooledPageError {
+    readonly message: string;
+    readonly stack?: string;
+}
 export interface InitScriptHandle {
     dispose(): Promise<void>;
 }
@@ -133,6 +149,12 @@ export interface PooledContext {
     }): Promise<void>;
     /** Drop every permission granted on this context. OPTIONAL, for the same reason. */
     clearPermissions?(): Promise<void>;
+    /**
+     * Add `origin` to the `connect-src` of each top document's CSP, and call `onWidened` when that
+     * changed a response (see `csp-widen.ts`). OPTIONAL: without it a deployed page with a strict CSP
+     * blocks the reader, and the lease says `sdk_never_dialled`, which is true.
+     */
+    widenCsp?(origin: string, onWidened: () => void): Promise<void>;
 }
 /** The launched browser. Real Playwright `Browser` satisfies this. */
 export interface PooledBrowser {

package/dist/portal/pool/pool-lease.d.ts

@@ -2,7 +2,7 @@
  * The pool's lease handle and lease record, its options, and its limits: the types and constants
  * `BrowserPool` is built from.
  */
-import type { InitScriptHandle, Launcher, PooledBrowser, PooledContext, PooledPage } from './pool-contract.js';
+import type { InitScriptHandle, Launcher, PooledBrowser, PooledContext, PooledPage, PooledPageError } from './pool-contract.js';
 /** A leased context+page for one flow. `release` frees the slot and closes the context. */
 export interface Lease {
     readonly sessionId: string;
@@ -46,8 +46,27 @@ export interface BrowserPoolOptions {
     /**
      * The zero-install reader, built where the daemon knows its own port and pairing token. A thunk so
      * the ~450KB build is only read if some page ever needs it; undefined when there is none to give.
+     * Called with the lease url, because a page off loopback gets its own nonce, not the token.
      */
-    zeroInstallScript?: () => string | undefined;
+    zeroInstallScript?: (url: string) => string | undefined;
+    /**
+     * The WebSocket origin the reader dials (`ws://localhost:<port>`). A lease on a page that is not
+     * on loopback adds it to the page's CSP `connect-src` (#2016). Absent: no page CSP is changed.
+     */
+    daemonOrigin?: string;
+    /**
+     * Sink for uncaught page errors — an import-time throw the SDK was never installed in time to
+     * see (#1966). Called with the lease id, so the wiring can reach the session that connects for
+     * this lease later. Optional: without it the pool hears errors and drops them, which is the
+     * behaviour the repo had before the sink existed.
+     */
+    onPageError?: (leaseId: string, error: PooledPageError) => void;
+    /**
+     * Sink for lease release — manual release, the reaper, and a crash reclaim all funnel through
+     * it. Lets the wiring drop state it kept FOR that lease (the page-error buffer) instead of
+     * holding it for the life of the daemon. Optional: no sink, nothing to clean up.
+     */
+    onLeaseClosed?: (leaseId: string) => void;
     /**
      * Launches a browser with a window, for a lease somebody wants to watch. Launched only when the
      * first headed lease is asked for. Absent: a headed lease is refused.
@@ -106,6 +125,8 @@ export interface ActiveLease {
      * context for "why did the page look frozen for a moment", not a log an agent needs to replay.
      */
     lastDialogMessage?: string;
+    /** Why the last screenshot of this lease failed, if it did. Cleared by the next one that works. */
+    captureError?: string;
     /**
      * The disposable handle of the caller's init script, when the lease was opened with one — a stub
      * of the bindings a desktop shell injects. Disposed with the lease, so a reload or a later
@@ -123,6 +144,18 @@ export interface ActiveLease {
     permissions: readonly string[];
     /** Whether its context accepts any TLS certificate (#1255). Fixed when the context is made. */
     ignoresHTTPSErrors: boolean;
+    /** `widenedFor`: the origin added to this page's CSP `connect-src`, once one was (#2016). */
+    csp: {
+        widenedFor?: string;
+    };
 }
 /** Whether the page's document has not finished loading. A page that cannot be asked counts as loaded. */
 export declare function pageLoading(page: PooledPage): Promise<boolean>;
+/**
+ * The HTTP status a navigation ended on, or undefined when the page shape reports none.
+ *
+ * Real Playwright answers `goto` with a response object exposing `status()`; the fakes hand back
+ * whatever they like. A status accessor that THROWS says nothing usable, so it reads as absent
+ * rather than breaking the lease that is otherwise fine.
+ */
+export declare function navStatusOf(navRes: unknown): number | undefined;

package/dist/portal/pool/pool-lease.js

@@ -47,3 +47,26 @@ export async function pageLoading(page) {
     const state = await page.evaluate('document.readyState');
     return 'string' === typeof state && state !== 'complete';
 }
+/**
+ * The HTTP status a navigation ended on, or undefined when the page shape reports none.
+ *
+ * Real Playwright answers `goto` with a response object exposing `status()`; the fakes hand back
+ * whatever they like. A status accessor that THROWS says nothing usable, so it reads as absent
+ * rather than breaking the lease that is otherwise fine.
+ */
+export function navStatusOf(navRes) {
+    if (null === navRes || 'object' !== typeof navRes || !('status' in navRes)) {
+        return undefined;
+    }
+    const s = navRes.status;
+    if ('function' === typeof s) {
+        try {
+            const code = s.call(navRes);
+            return 'number' === typeof code ? code : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    return 'number' === typeof s ? s : undefined;
+}

package/dist/portal/pool/zero-install.js

@@ -37,6 +37,74 @@ const HTML_CONTENT_TYPES = ['text/html', 'application/xhtml+xml'];
  */
 const NOT_HTML_GUARD = `if (globalThis.document !== undefined && !${JSON.stringify(HTML_CONTENT_TYPES)}.includes(globalThis.document.contentType)) ` +
     `return ${JSON.stringify(READER_NOT_HTML)};`;
+/*
+ * Keep what the page says before the SDK's observers exist, and hand it to them after `connect()`.
+ *
+ * The observers install in `connect()`, which waits for DOMContentLoaded (below). The app's start-up
+ * scripts run before that, so a console error or an uncaught error while the page loaded was not
+ * seen, and a page that crashed at start-up gave a clean capture. Only the reader does this: it is
+ * installed before the page's scripts, and an app's own SDK connects from inside them.
+ *
+ * Kept in the order the page said it: `console.error` calls, uncaught script errors and unhandled
+ * rejections. After `connect()`, each console error is said again through the patched console with
+ * the native print off, so the console shows it once. Each error event is dispatched again on
+ * `window`, where the SDK listens. The app's own error listeners see a replayed error a second time.
+ * A resource that failed to load is not kept: the network observer reads it from resource timing.
+ */
+const EARLY_KEEP = 'if ("function" === typeof globalThis.addEventListener && globalThis.console !== undefined) {\n' +
+    'const early = { said: [], replaying: false };\n' +
+    'globalThis.__reticleEarly = early;\n' +
+    'const nativeError = globalThis.console.error;\n' +
+    'globalThis.console.error = function (...args) {\n' +
+    '  if (early.said !== null) early.said.push(args);\n' +
+    '  if (!early.replaying) return nativeError.apply(this, args);\n' +
+    '};\n' +
+    'early.keep = (e) => { if (early.said !== null && (e.type !== "error" || e instanceof globalThis.ErrorEvent)) early.said.push(e); };\n' +
+    'globalThis.addEventListener("error", early.keep, true);\n' +
+    'globalThis.addEventListener("unhandledrejection", early.keep);\n' +
+    '}';
+const EARLY_REPLAY = 'const early = globalThis.__reticleEarly;\n' +
+    'if (early !== undefined) {\n' +
+    '  globalThis.__reticleEarly = undefined;\n' +
+    '  globalThis.removeEventListener("error", early.keep, true);\n' +
+    '  globalThis.removeEventListener("unhandledrejection", early.keep);\n' +
+    '  const said = early.said;\n' +
+    '  early.said = null;\n' +
+    '  for (const item of said) {\n' +
+    '    if (Array.isArray(item)) {\n' +
+    '      early.replaying = true;\n' +
+    '      try { globalThis.console.error(...item); } finally { early.replaying = false; }\n' +
+    '    } else if ("error" === item.type) {\n' +
+    '      globalThis.dispatchEvent(new globalThis.ErrorEvent("error", { message: item.message, filename: item.filename, lineno: item.lineno, colno: item.colno, error: item.error }));\n' +
+    '    } else {\n' +
+    '      globalThis.dispatchEvent(new globalThis.PromiseRejectionEvent("unhandledrejection", { promise: item.promise, reason: item.reason }));\n' +
+    '    }\n' +
+    '  }\n' +
+    '}';
+/*
+ * Connect once the DOM exists. The reader also runs as an init script on every later document of the
+ * lease, before the parser makes <head> and <body>. `connect()` mounts page UI before it dials the
+ * bridge, so it threw there and never dialled: every full navigation after the first page lost the
+ * lease's session (#1897). The bundle still loads at once, so the observers start early.
+ */
+const CONNECT_WHEN_DOM_READY = (args) => `const connect = () => { globalThis.__reticleInstance.connect(${args}); ${EARLY_REPLAY} };\n` +
+    `if (globalThis.document !== undefined && 'loading' === globalThis.document.readyState) ` +
+    `globalThis.document.addEventListener('DOMContentLoaded', connect, { once: true });\n` +
+    `else connect();`;
+/** Where every zod copy in a page keeps its shared settings (`z.config`). */
+const ZOD_CONFIG = 'globalThis.__zod_globalConfig';
+/*
+ * Turn zod `jitless` on for the page, unless the page set it itself.
+ *
+ * The reader is evaluated over CDP, where `new Function` works even on a page whose CSP forbids
+ * `unsafe-eval`. Zod's eval probe then answered true and cached it, and later parses compiled a fast
+ * path with `new Function` in the page: CSP threw, and the session stopped answering (#2016,
+ * nextjs.org). Zod reads `jitless` when a schema is made, and the SDK makes some schemas later, also
+ * inside a CDP evaluate. So the setting stays on.
+ * ponytail: the page's own zod then parses without its compiled fast path. Results are the same;
+ * only parse speed changes. Scope it to the bundle's own zod copy if that speed is ever seen.
+ */
+const ZOD_JITLESS = `(${ZOD_CONFIG} ??= {}).jitless ??= true;`;
 /**
  * The script for a page: install the SDK if the page has none, then connect it to this daemon.
  *
@@ -47,7 +115,7 @@ const NOT_HTML_GUARD = `if (globalThis.document !== undefined && !${JSON.stringi
  */
 export function zeroInstallScript(bundle, opts) {
     const args = JSON.stringify(injectedConnectArgs(opts));
-    return `(() => {\n${NOT_HTML_GUARD}\nif (!globalThis.__reticleInstance) {\n${bundle}\n}\nglobalThis.__reticleInstance.connect(${args});\n})();`;
+    return `(() => {\n${NOT_HTML_GUARD}\nif (!globalThis.__reticleInstance) {\n${EARLY_KEEP}\n${ZOD_JITLESS}\n${bundle}\n}\n${CONNECT_WHEN_DOM_READY(args)}\n})();`;
 }
 /** The page is not an HTML document, so the lease did not give it the zero-install reader. */
 export class NotHtmlDocumentError extends Error {

package/dist/portal/session/dev-server/dev-command.d.ts

@@ -19,6 +19,14 @@ export interface DevCommand {
     /** The app's directory, when it is not the project root. The caller must run the command there. */
     directory?: string;
 }
+/**
+ * The direct child folders of `directory` that are apps with a dev command, sorted by name.
+ *
+ * Only for a folder with no package.json of its own. A task folder holds the app one level down, and
+ * no workspace file lists it, so `workspacePackageDirs` never finds it. Folders that are not apps
+ * (no package.json, or no dev script), `node_modules` and hidden folders are skipped.
+ */
+export declare function childDevApps(directory: string, read?: (path: string) => string | undefined, listDirs?: (path: string) => readonly string[]): readonly string[];
 /**
  * The dev command for the project in `directory`, or undefined when there is not one to be sure of.
  *

package/dist/portal/session/dev-server/dev-command.js

@@ -36,6 +36,7 @@ const YARN_DLX = 'yarn dlx';
 const INIT_VERB = 'init';
 const DEFAULT_PACKAGE_MANAGER = 'npm';
 const PACKAGE_JSON = 'package.json';
+const PNPM_WORKSPACE = 'pnpm-workspace.yaml';
 /** `--port 4311` / `--port=4311`, the flag every dev server in this list accepts. */
 const PORT_FLAG = /--port[= ]\s*(\d+)/;
 /**
@@ -59,15 +60,17 @@ function readTextFile(path) {
 function pinnedPort(script) {
     const match = PORT_FLAG.exec(script) ?? PORT_SHORT_FLAG.exec(script) ?? PORT_ENV.exec(script);
     const digits = match?.[1];
-    if (digits === undefined)
+    if (digits === undefined) {
         return undefined;
+    }
     const port = Number.parseInt(digits, 10);
     return Number.isSafeInteger(port) ? port : undefined;
 }
 /** The parsed package.json, or undefined for anything unreadable/unparseable. */
 function readManifest(raw) {
-    if (raw === undefined)
+    if (raw === undefined) {
         return undefined;
+    }
     try {
         return JSON.parse(raw);
     }
@@ -77,11 +80,13 @@ function readManifest(raw) {
 }
 /** The scripts block of a parsed package.json, or an empty one. */
 function scriptsOf(manifest) {
-    if (null === manifest || 'object' !== typeof manifest)
+    if (null === manifest || 'object' !== typeof manifest) {
         return {};
+    }
     const scripts = manifest.scripts;
-    if (null === scripts || 'object' !== typeof scripts)
+    if (null === scripts || 'object' !== typeof scripts) {
         return {};
+    }
     return scripts;
 }
 /** The package manager the lockfiles under `directory` identify. Anything else is npm. */
@@ -98,8 +103,9 @@ function devCommandFor(directory, manager, read) {
     // spawns are the same.
     const desktop = desktopLaunch(manifest);
     if (desktop !== undefined) {
-        if ('command' in desktop)
+        if ('command' in desktop) {
             return { command: desktop.command };
+        }
         const command = `${manager} run ${desktop.script}`;
         return {
             command: 0 < desktop.args.length ? `${command} ${desktop.args}` : command,
@@ -108,8 +114,9 @@ function devCommandFor(directory, manager, read) {
     }
     for (const script of DEV_SCRIPTS) {
         const body = scripts[script];
-        if ('string' !== typeof body || 0 === body.trim().length)
+        if ('string' !== typeof body || 0 === body.trim().length) {
             continue;
+        }
         const port = pinnedPort(body);
         return {
             command: `${manager} run ${script}`,
@@ -119,6 +126,28 @@ function devCommandFor(directory, manager, read) {
     }
     return undefined;
 }
+/** Folders never read as an app: dependencies, and anything hidden (`.git`, `.cache`). */
+const NODE_MODULES = 'node_modules';
+const HIDDEN_PREFIX = '.';
+/**
+ * The direct child folders of `directory` that are apps with a dev command, sorted by name.
+ *
+ * Only for a folder with no package.json of its own. A task folder holds the app one level down, and
+ * no workspace file lists it, so `workspacePackageDirs` never finds it. Folders that are not apps
+ * (no package.json, or no dev script), `node_modules` and hidden folders are skipped.
+ */
+export function childDevApps(directory, read = readTextFile, listDirs = readDirNames) {
+    if (read(join(directory, PACKAGE_JSON)) !== undefined) {
+        return [];
+    }
+    return listDirs(directory)
+        .filter((name) => NODE_MODULES !== name && !name.startsWith(HIDDEN_PREFIX))
+        .filter((name) => {
+        const child = join(directory, name);
+        return devCommandFor(child, packageManager(child, read), read) !== undefined;
+    })
+        .sort();
+}
 /** Directory names under `path`, or none when it cannot be read. */
 function readDirNames(path) {
     try {
@@ -151,16 +180,35 @@ export function detectDevCommand(directory, read = readTextFile) {
 export function detectDevCommandInProject(directory, read = readTextFile, listDirs = readDirNames) {
     const manager = packageManager(directory, read);
     const here = devCommandFor(directory, manager, read);
-    if (here !== undefined)
+    if (here !== undefined) {
         return here;
+    }
+    // No package.json and no pnpm workspace file: a task folder, with the app one level down. With two
+    // apps there, choosing the first would start the wrong one; the caller names them through
+    // `childDevApps`. With none, the workspace search below still looks a level deeper.
+    if (read(join(directory, PACKAGE_JSON)) === undefined &&
+        read(join(directory, PNPM_WORKSPACE)) === undefined) {
+        const [only, ...others] = childDevApps(directory, read, listDirs);
+        if (0 < others.length) {
+            return undefined;
+        }
+        if (only !== undefined) {
+            const child = join(directory, only);
+            const found = devCommandFor(child, packageManager(child, read), read);
+            if (found !== undefined) {
+                return { ...found, directory: only };
+            }
+        }
+    }
     const packages = workspacePackageDirs({
         readFile: (path) => read(join(directory, path)) ?? null,
         listDirs: (path) => listDirs(join(directory, path)),
     });
     for (const sub of packages) {
         const found = devCommandFor(join(directory, sub), manager, read);
-        if (found !== undefined)
+        if (found !== undefined) {
             return { ...found, directory: sub };
+        }
     }
     return undefined;
 }