sweetlink 0.1.0 → 0.2.1

package/dist/src/index.js

@@ -1,42 +1,44 @@
 #!/usr/bin/env node
-import { existsSync, readFileSync } from 'node:fs';
-import { mkdir, readFile, rm } from 'node:fs/promises';
-import os from 'node:os';
-import path from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { Command, CommanderError, Option } from 'commander';
-import { compact, uniq } from 'es-toolkit';
-import { createSweetLinkCommandId, } from '../shared/src/index.js';
-import { registerClickCommand } from './commands/click.js';
-import { registerRunJsCommand } from './commands/run-js.js';
-import { registerTrustCaCommand } from './commands/trust-ca.js';
-import { readRootProgramOptions, resolveConfig } from './core/config.js';
-import { loadSweetLinkFileConfig } from './core/config-file.js';
-import { readCommandOptions } from './core/env.js';
-import { cleanupControlledChromeRegistry, registerControlledChromeInstance } from './devtools-registry.js';
-import { sweetLinkCliTestMode, sweetLinkDebug, sweetLinkEnv } from './env.js';
-import { fetchJson } from './http.js';
-import { collectPuppeteerDiagnostics, focusControlledChromePage, launchChrome, launchControlledChrome, prepareChromeLaunch, reuseExistingControlledChrome, signalSweetLinkBootstrap, waitForSweetLinkSession, } from './runtime/chrome.js';
-import { buildCookieOrigins, collectChromeCookies, collectChromeCookiesForDomains, normalizePuppeteerCookie, } from './runtime/cookies.js';
-import { ensureDevStackRunning as ensureDevStackRunningRuntime, isAppReachable as isAppReachableRuntime, maybeInstallMkcertDispatcher, } from './runtime/devstack.js';
-import { attemptTwitterOauthAutoAccept, collectBootstrapDiagnostics, connectToDevTools, createEmptyDevToolsState, createNetworkEntryFromRequest, DEVTOOLS_CONSOLE_LIMIT, DEVTOOLS_NETWORK_LIMIT, DEVTOOLS_STATE_PATH, deriveDevtoolsLinkInfo, diagnosticsContainBlockingIssues, ensureBackgroundDevtoolsListener, fetchDevToolsTabs, formatConsoleArg, loadDevToolsConfig, loadDevToolsState, logBootstrapDiagnostics, saveDevToolsConfig, saveDevToolsState, serializeConsoleMessage, trimBuffer, } from './runtime/devtools.js';
-import { fetchNextDevtoolsErrors } from './runtime/next-devtools.js';
-import { attemptDevToolsCapture, maybeDescribeScreenshot, persistScreenshotResult, tryDevToolsRecovery, tryHtmlToImageFallback, } from './runtime/screenshot.js';
-import { renderCommandResult } from './runtime/scripts.js';
-import { buildClickScript, fetchConsoleEvents, fetchSessionSummaries, formatSessionHeadline, getSessionSummaryById, isSweetLinkSelectorCandidate, isSweetLinkSelectorDiscoveryResult, resolvePromptOption, resolveSessionIdFromHint, } from './runtime/session.js';
-import { buildSmokeRouteUrl, clearSmokeProgress, consoleEventIndicatesAuthIssue, consoleEventIndicatesRuntimeError, DEFAULT_SMOKE_ROUTES, deriveSmokeRoutes, ensureSweetLinkSessionConnected, formatConsoleEventSummary, loadSmokeProgressIndex, navigateSweetLinkSession, saveSmokeProgressIndex, triggerSweetLinkCliAuto, waitForSmokeRouteReady, } from './runtime/smoke.js';
-import { buildWaitCandidateUrls, configurePathRedirects, normalizeUrlForMatch, trimTrailingSlash } from './runtime/url.js';
-import { buildScreenshotHooks } from './screenshot-hooks.js';
-import { fetchCliToken } from './token.js';
-import { describeAppForPrompt, formatAppLabel } from './util/app-label.js';
-import { extractEventMessage, isErrnoException, logDebugError } from './util/errors.js';
+import { existsSync, readFileSync } from "node:fs";
+import { mkdir, readFile, rm } from "node:fs/promises";
+import { spawn } from "node:child_process";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { Command, CommanderError, Option } from "commander";
+import { compact, uniq } from "es-toolkit";
+import { createSweetLinkCommandId, } from "../shared/src/index.js";
+import { registerClickCommand } from "./commands/click.js";
+import { registerRunJsCommand } from "./commands/run-js.js";
+import { registerTrustCaCommand } from "./commands/trust-ca.js";
+import { readRootProgramOptions, resolveConfig } from "./core/config.js";
+import { loadSweetLinkFileConfig } from "./core/config-file.js";
+import { cloneProcessEnv, readCommandOptions } from "./core/env.js";
+import { cleanupControlledChromeRegistry, registerControlledChromeInstance, } from "./devtools-registry.js";
+import { sweetLinkCliTestMode, sweetLinkDebug, sweetLinkEnv } from "./env.js";
+import { fetchJson } from "./http.js";
+import { collectPuppeteerDiagnostics, focusControlledChromePage, launchChrome, launchControlledChrome, prepareChromeLaunch, reuseExistingControlledChrome, signalSweetLinkBootstrap, waitForSweetLinkSession, } from "./runtime/chrome.js";
+import { ensureDeepLinkAuthFlow } from "./runtime/chrome/deep-link.js";
+import { buildCookieOrigins, collectChromeCookies, collectChromeCookiesForDomains, normalizePuppeteerCookie, } from "./runtime/cookies.js";
+import { ensureDevStackRunning as ensureDevStackRunningRuntime, isAppReachable as isAppReachableRuntime, maybeInstallMkcertDispatcher, } from "./runtime/devstack.js";
+import { attemptTwitterOauthAutoAccept, collectBootstrapDiagnostics, connectToDevTools, createEmptyDevToolsState, createNetworkEntryFromRequest, DEVTOOLS_CONSOLE_LIMIT, DEVTOOLS_NETWORK_LIMIT, DEVTOOLS_STATE_PATH, deriveDevtoolsLinkInfo, diagnosticsContainBlockingIssues, ensureBackgroundDevtoolsListener, fetchDevToolsTabs, formatConsoleArg, loadDevToolsConfig, loadDevToolsState, logBootstrapDiagnostics, saveDevToolsConfig, saveDevToolsState, serializeConsoleMessage, trimBuffer, } from "./runtime/devtools.js";
+import { fetchNextDevtoolsErrors } from "./runtime/next-devtools.js";
+import { attemptDevToolsCapture, maybeDescribeScreenshot, persistScreenshotResult, tryDevToolsRecovery, tryHtmlToImageFallback, } from "./runtime/screenshot.js";
+import { renderCommandResult } from "./runtime/scripts.js";
+import { buildClickScript, fetchConsoleEvents, fetchSessionSummaries, formatSessionHeadline, getSessionSummaryById, isSweetLinkSelectorCandidate, isSweetLinkSelectorDiscoveryResult, resolvePromptOption, resolveSessionIdFromHint, } from "./runtime/session.js";
+import { buildSmokeRouteUrl, clearSmokeProgress, consoleEventIndicatesAuthIssue, consoleEventIndicatesRuntimeError, DEFAULT_SMOKE_ROUTES, deriveSmokeRoutes, ensureSweetLinkSessionConnected, formatConsoleEventSummary, loadSmokeProgressIndex, navigateSweetLinkSession, saveSmokeProgressIndex, triggerSweetLinkCliAuto, waitForSmokeRouteReady, } from "./runtime/smoke.js";
+import { buildWaitCandidateUrls, configurePathRedirects, normalizeUrlForMatch, trimTrailingSlash, } from "./runtime/url.js";
+import { buildScreenshotHooks } from "./screenshot-hooks.js";
+import { fetchCliToken } from "./token.js";
+import { describeAppForPrompt, formatAppLabel } from "./util/app-label.js";
+import { extractEventMessage, isErrnoException, logDebugError } from "./util/errors.js";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 function resolveRepoRoot(startDir) {
     let currentDir = startDir;
     // Walk up until a package.json exists or we reach the filesystem root.
     // This keeps the CLI working whether we run from `src` (tsx) or `dist/src`.
-    while (!existsSync(path.join(currentDir, 'package.json'))) {
+    while (!existsSync(path.join(currentDir, "package.json"))) {
         const parent = path.dirname(currentDir);
         if (parent === currentDir) {
             return startDir;
@@ -46,11 +48,11 @@ function resolveRepoRoot(startDir) {
     return currentDir;
 }
 const repoRoot = resolveRepoRoot(__dirname);
-const packageJsonPath = path.join(repoRoot, 'package.json');
-let packageVersion = '0.0.0';
+const packageJsonPath = path.join(repoRoot, "package.json");
+let packageVersion = "0.0.0";
 try {
-    const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf8'));
-    if (typeof packageJson.version === 'string') {
+    const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf8"));
+    if (typeof packageJson.version === "string") {
         packageVersion = packageJson.version;
     }
 }
@@ -63,7 +65,7 @@ const OAUTH_URL_PATTERN = /oauth|authorize/i;
 const TRAILING_SLASH_PATTERN = /\/?$/;
 function formatDuration(ms) {
     if (!Number.isFinite(ms)) {
-        return 'unknown';
+        return "unknown";
     }
     const abs = Math.max(0, ms);
     if (abs < 1000) {
@@ -90,11 +92,11 @@ function formatDuration(ms) {
 }
 const program = new Command();
 program
-    .name('sweetlink')
-    .description('Interact with SweetLink daemon sessions')
-    .version(packageVersion, '-v, --version', 'Show SweetLink CLI version');
+    .name("sweetlink")
+    .description("Interact with SweetLink daemon sessions")
+    .version(packageVersion, "-v, --version", "Show SweetLink CLI version");
 maybeInstallMkcertDispatcher();
-const LOOSE_PATH_SUFFIXES = new Set(['home', 'index', 'overview']);
+const LOOSE_PATH_SUFFIXES = new Set(["home", "index", "overview"]);
 const { config: fileConfig } = loadSweetLinkFileConfig();
 configurePathRedirects(fileConfig.redirects);
 const { appUrl: envAppUrl, daemonUrl: envDaemonUrl, localAdminApiKey, adminApiKey: sharedAdminApiKey, prodAppUrl: envProdAppUrl, } = sweetLinkEnv;
@@ -102,15 +104,15 @@ const defaultAppLabel = formatAppLabel(fileConfig.appLabel ?? sweetLinkEnv.appLa
 const defaultAppUrl = deriveDefaultAppUrl(envAppUrl, fileConfig);
 const defaultProdAppUrl = fileConfig.prodUrl ?? envProdAppUrl;
 const defaultDaemonUrl = fileConfig.daemonUrl ?? envDaemonUrl;
-const defaultAdminKey = fileConfig.adminKey ?? localAdminApiKey ?? sharedAdminApiKey ?? '';
+const defaultAdminKey = fileConfig.adminKey ?? localAdminApiKey ?? sharedAdminApiKey ?? "";
 const defaultHealthPaths = fileConfig.healthChecks?.paths ?? null;
-const LOCAL_DEFAULT_APP_URL = 'http://localhost:3000';
+const LOCAL_DEFAULT_APP_URL = "http://localhost:3000";
 function deriveDefaultAppUrl(envUrl, config) {
-    const configuredAppUrl = typeof config.appUrl === 'string' ? config.appUrl.trim() : '';
+    const configuredAppUrl = typeof config.appUrl === "string" ? config.appUrl.trim() : "";
     if (configuredAppUrl.length > 0) {
         return configuredAppUrl;
     }
-    if (typeof config.port === 'number' && Number.isFinite(config.port) && config.port > 0) {
+    if (typeof config.port === "number" && Number.isFinite(config.port) && config.port > 0) {
         const baseUrl = envUrl ?? LOCAL_DEFAULT_APP_URL;
         return applyPortToUrl(baseUrl, config.port);
     }
@@ -129,22 +131,22 @@ function applyPortToUrl(base, port) {
 function parseCliPort(value) {
     const parsed = Number.parseInt(value, 10);
     if (!Number.isFinite(parsed) || parsed <= 0) {
-        throw new CommanderError(1, 'InvalidPort', `--port expects a positive integer, received "${value}".`);
+        throw new CommanderError(1, "InvalidPort", `--port expects a positive integer, received "${value}".`);
     }
     return parsed;
 }
 program
-    .option('-a, --app-url <url>', 'Application base URL for SweetLink commands', defaultAppUrl)
-    .option('--app-label <label>', 'Friendly name for your application (used in help output)', defaultAppLabel)
-    .option('--url <url>', 'Alias for --app-url')
-    .addOption(new Option('--port <number>', 'Override local app port (defaults to config or 3000)').argParser(parseCliPort))
-    .option('-d, --daemon-url <url>', 'SweetLink daemon base URL', defaultDaemonUrl)
-    .option('-k, --admin-key <key>', 'Optional admin API key (defaults to SWEETLINK_LOCAL_ADMIN_API_KEY or SWEETLINK_ADMIN_API_KEY env; falls back to legacy SWEETISTICS_* keys)', defaultAdminKey)
-    .option('--oauth-script <path>', 'Absolute or relative path to an OAuth automation script (ESM module). Overrides config/env defaults.');
+    .option("-a, --app-url <url>", "Application base URL for SweetLink commands", defaultAppUrl)
+    .option("--app-label <label>", "Friendly name for your application (used in help output)", defaultAppLabel)
+    .option("--url <url>", "Alias for --app-url")
+    .addOption(new Option("--port <number>", "Override local app port (defaults to config or 3000)").argParser(parseCliPort))
+    .option("-d, --daemon-url <url>", "SweetLink daemon base URL", defaultDaemonUrl)
+    .option("-k, --admin-key <key>", "Optional admin API key (defaults to SWEETLINK_LOCAL_ADMIN_API_KEY or SWEETLINK_ADMIN_API_KEY env; falls back to legacy SWEETISTICS_* keys)", defaultAdminKey)
+    .option("--oauth-script <path>", "Absolute or relative path to an OAuth automation script (ESM module). Overrides config/env defaults.");
 program
-    .command('sessions')
-    .description('List active SweetLink sessions')
-    .option('--json', 'Output JSON instead of a table', false)
+    .command("sessions")
+    .description("List active SweetLink sessions")
+    .option("--json", "Output JSON instead of a table", false)
     .action(async (options, command) => {
     const config = resolveConfig(command);
     const token = await fetchCliToken(config);
@@ -167,15 +169,17 @@ program
         return;
     }
     if (sessions.length === 0) {
-        console.log('No active SweetLink sessions.');
-        console.log('Hint: run `pnpm sweetlink open --controlled --path /` to launch an authenticated tab automatically.');
+        console.log("No active SweetLink sessions.");
+        console.log("Hint: run `pnpm sweetlink open --controlled --path /` to launch an authenticated tab automatically.");
         return;
     }
     const now = Date.now();
-    console.log('Active SweetLink sessions:\n');
+    console.log("Active SweetLink sessions:\n");
     for (const session of sessions) {
-        const heartbeatMsAgo = typeof session.heartbeatMsAgo === 'number' ? session.heartbeatMsAgo : Math.max(0, now - session.lastSeenAt);
-        const socketState = session.socketState ?? 'unknown';
+        const heartbeatMsAgo = typeof session.heartbeatMsAgo === "number"
+            ? session.heartbeatMsAgo
+            : Math.max(0, now - session.lastSeenAt);
+        const socketState = session.socketState ?? "unknown";
         const consoleEventsBuffered = session.consoleEventsBuffered ?? 0;
         const consoleErrorsBuffered = session.consoleErrorsBuffered ?? 0;
         const pendingCommandCount = session.pendingCommandCount ?? 0;
@@ -186,30 +190,30 @@ program
         const openedLabel = `${formatDuration(openedMsAgo)} ago`;
         const socketLabel = `socket ${socketState}`;
         console.log(`  - last: ${lastHeartbeatLabel} • opened ${openedLabel} • ${socketLabel}`);
-        const pendingLabel = pendingCommandCount === 1 ? 'command' : 'commands';
+        const pendingLabel = pendingCommandCount === 1 ? "command" : "commands";
         const consoleLabel = consoleEventsBuffered > 0
-            ? `${consoleEventsBuffered} event${consoleEventsBuffered === 1 ? '' : 's'}${consoleErrorsBuffered ? ` (${consoleErrorsBuffered} error${consoleErrorsBuffered === 1 ? '' : 's'})` : ''}`
-            : 'none';
+            ? `${consoleEventsBuffered} event${consoleEventsBuffered === 1 ? "" : "s"}${consoleErrorsBuffered ? ` (${consoleErrorsBuffered} error${consoleErrorsBuffered === 1 ? "" : "s"})` : ""}`
+            : "none";
         console.log(`  - queues: ${pendingCommandCount} ${pendingLabel} • console ${consoleLabel}`);
         if (devtoolsSessionIds.has(session.sessionId)) {
-            console.log(`  - devtools: linked${devtoolsEndpoint ? ` (${devtoolsEndpoint})` : ''}`);
+            console.log(`  - devtools: linked${devtoolsEndpoint ? ` (${devtoolsEndpoint})` : ""}`);
         }
         if (session.userAgent) {
             console.log(`  - ua: ${session.userAgent}`);
         }
-        console.log('');
+        console.log("");
     }
-    console.log('Tip: run `pnpm sweetlink console <sessionId> -n 50` to inspect the most recent console events for a session.');
+    console.log("Tip: run `pnpm sweetlink console <sessionId> -n 50` to inspect the most recent console events for a session.");
 });
 program
-    .command('cookies')
-    .description('Dump Chrome cookies for one or more domains or origins')
-    .argument('<domains...>', 'Domains or fully-qualified origins (e.g. localhost, https://example.com)')
-    .option('--json', 'Output JSON instead of a human-readable list', false)
+    .command("cookies")
+    .description("Dump Chrome cookies for one or more domains or origins")
+    .argument("<domains...>", "Domains or fully-qualified origins (e.g. localhost, https://example.com)")
+    .option("--json", "Output JSON instead of a human-readable list", false)
     .action(async (domains, options) => {
     const uniqueDomains = uniq(compact(domains.map((domain) => domain.trim())));
     if (uniqueDomains.length === 0) {
-        console.log('No domains provided; nothing to collect.');
+        console.log("No domains provided; nothing to collect.");
         return;
     }
     const cookiesByDomain = await collectChromeCookiesForDomains(uniqueDomains);
@@ -220,29 +224,29 @@ program
     for (const domain of uniqueDomains) {
         const domainCookies = cookiesByDomain[domain];
         const cookies = Array.isArray(domainCookies) ? domainCookies : [];
-        console.log(`\n${domain} — ${cookies.length} cookie${cookies.length === 1 ? '' : 's'}`);
+        console.log(`\n${domain} — ${cookies.length} cookie${cookies.length === 1 ? "" : "s"}`);
         if (cookies.length === 0) {
             continue;
         }
         for (const cookie of cookies) {
-            const scope = cookie.domain ? `domain=${cookie.domain}` : `url=${cookie.url ?? 'unknown'}`;
-            const cookiePath = cookie.path ?? '/';
-            const secureFlag = cookie.secure ? '; Secure' : '';
-            const httpOnlyFlag = cookie.httpOnly ? '; HttpOnly' : '';
+            const scope = cookie.domain ? `domain=${cookie.domain}` : `url=${cookie.url ?? "unknown"}`;
+            const cookiePath = cookie.path ?? "/";
+            const secureFlag = cookie.secure ? "; Secure" : "";
+            const httpOnlyFlag = cookie.httpOnly ? "; HttpOnly" : "";
             console.log(`  • ${cookie.name} (${scope} ${cookiePath}${secureFlag}${httpOnlyFlag})`);
             console.log(`    ${cookie.value}`);
         }
     }
-    console.log('');
+    console.log("");
 });
 registerRunJsCommand(program);
 registerTrustCaCommand(program);
 registerClickCommand(program);
 program
-    .command('console <sessionId>')
-    .description('Fetch buffered console events for a session')
-    .option('-n, --limit <count>', 'Show only the last <count> console events', Number)
-    .option('--json', 'Output JSON', false)
+    .command("console <sessionId>")
+    .description("Fetch buffered console events for a session")
+    .option("-n, --limit <count>", "Show only the last <count> console events", Number)
+    .option("--json", "Output JSON", false)
     .action(async (sessionId, options, command) => {
     const config = resolveConfig(command);
     const resolvedSessionId = await resolveSessionIdFromHint(sessionId, config);
@@ -255,10 +259,10 @@ program
         return;
     }
     if (response.events.length === 0) {
-        console.log('No buffered console output.');
+        console.log("No buffered console output.");
         return;
     }
-    const limit = typeof options.limit === 'number' && Number.isFinite(options.limit) && options.limit > 0
+    const limit = typeof options.limit === "number" && Number.isFinite(options.limit) && options.limit > 0
         ? Math.floor(options.limit)
         : null;
     const events = limit ? response.events.slice(-limit) : response.events;
@@ -270,35 +274,43 @@ program
     }
 });
 program
-    .command('open')
+    .command("open")
     .description(`Open ${defaultAppLabel} in Chrome with SweetLink auto-enabled`)
-    .option('-e, --env <env>', 'Environment to open (dev or prod)', 'dev')
-    .option('-p, --path <path>', 'Optional path to append (default "")', '')
-    .option('--url <url>', 'Explicit URL to open (overrides --path and --env)')
-    .option('--controlled', 'Launch Chrome in controlled mode with DevTools enabled', false)
-    .option('--devtools-port <port>', 'Specify DevTools port to use with --controlled', Number)
-    .option('--no-cookie-sync', 'Disable copying cookies from your main Chrome profile into the controlled window', false)
-    .option('--timeout <seconds>', 'Seconds to wait for a SweetLink session (default 15)', Number)
-    .option('--no-devtools', 'Skip DevTools automation when opening in controlled mode')
-    .option('--headless', 'Launch the controlled browser headlessly', false)
-    .option('--foreground', 'Bring the Chrome window to the foreground after opening (macOS only)', false)
+    .option("-e, --env <env>", "Environment to open (dev or prod)", "dev")
+    .option("-p, --path <path>", 'Optional path to append (default "")', "")
+    .option("--url <url>", "Explicit URL to open (overrides --path and --env)")
+    .option("--controlled", "Launch Chrome in controlled mode with DevTools enabled", false)
+    .option("--devtools-port <port>", "Specify DevTools port to use with --controlled", Number)
+    .option("--no-cookie-sync", "Disable copying cookies from your main Chrome profile into the controlled window", false)
+    .option("--timeout <seconds>", "Seconds to wait for a SweetLink session (default 15)", Number)
+    .option("--no-devtools", "Skip DevTools automation when opening in controlled mode")
+    .option("--headless", "Launch the controlled browser headlessly", false)
+    .option("--foreground", "Bring the Chrome window to the foreground after opening (macOS only)", false)
     .action(async (options, command) => {
     await runOpenCommand(options, command, program);
 });
+program
+    .command("daemon")
+    .description("Launch the SweetLink daemon process")
+    .argument("[args...]", "Arguments forwarded to sweetlinkd")
+    .allowUnknownOption(true)
+    .action((_args, command) => {
+    runDaemonCommand(command);
+});
 async function runOpenCommand(options, command, rootProgram) {
     const context = buildOpenCommandContext(options, command, rootProgram);
     if (!context.controlled) {
         if (options.devtools === false) {
-            console.log('--no-devtools is ignored when launching an uncontrolled browser window.');
+            console.log("--no-devtools is ignored when launching an uncontrolled browser window.");
         }
         if (options.headless) {
-            console.log('--headless requires --controlled; launching a regular Chrome window instead.');
+            console.log("--headless requires --controlled; launching a regular Chrome window instead.");
         }
     }
     if (context.headless && context.foreground) {
-        console.log('--foreground is ignored in headless mode.');
+        console.log("--foreground is ignored in headless mode.");
     }
-    if (context.env === 'dev') {
+    if (context.env === "dev") {
         await ensureDevStackRunningRuntime(context.targetUrl, {
             repoRoot,
             healthPaths: context.healthCheckPaths ?? undefined,
@@ -318,6 +330,29 @@ async function runOpenCommand(options, command, rootProgram) {
     }
     await handleUncontrolledOpen(context, waitToken);
 }
+function runDaemonCommand(command) {
+    const parent = command.parent;
+    const rawArgs = parent?.rawArgs ?? process.argv;
+    const daemonIndex = rawArgs.findIndex((arg) => arg === "daemon");
+    const afterDaemon = daemonIndex === -1 ? [] : rawArgs.slice(daemonIndex + 1);
+    const passthroughIndex = afterDaemon.indexOf("--");
+    const forwarded = passthroughIndex >= 0
+        ? afterDaemon.slice(passthroughIndex + 1)
+        : (command.args ?? []).filter((value) => typeof value === "string");
+    const child = spawn("sweetlinkd", forwarded, { stdio: "inherit", env: cloneProcessEnv() });
+    child.on("error", (error) => {
+        if (isErrnoException(error) && error.code === "ENOENT") {
+            console.error('Unable to find "sweetlinkd" on PATH. Try `pnpm exec sweetlinkd` instead.');
+            process.exitCode = 1;
+            return;
+        }
+        console.error("Failed to launch sweetlinkd:", extractEventMessage(error));
+        process.exitCode = 1;
+    });
+    child.on("exit", (code) => {
+        process.exitCode = code ?? 0;
+    });
+}
 function buildOpenCommandContext(options, command, rootProgram) {
     const config = resolveConfig(command);
     const env = normalizeOpenCommandEnvironment(options.env);
@@ -325,11 +360,11 @@ function buildOpenCommandContext(options, command, rootProgram) {
     const parentOptions = readRootProgramOptions(parent);
     const developmentBaseUrl = parentOptions.appUrl;
     const productionBaseUrl = defaultProdAppUrl;
-    const baseUrl = env === 'prod' ? productionBaseUrl : developmentBaseUrl;
+    const baseUrl = env === "prod" ? productionBaseUrl : developmentBaseUrl;
     const explicitTarget = resolveExplicitTargetUrl(options.url);
     const targetUrl = explicitTarget ?? buildOpenCommandTargetUrl(baseUrl, options.path);
     const serverConfig = config.servers[env] ?? null;
-    const preferredPort = typeof options.devtoolsPort === 'number' && Number.isFinite(options.devtoolsPort)
+    const preferredPort = typeof options.devtoolsPort === "number" && Number.isFinite(options.devtoolsPort)
         ? options.devtoolsPort
         : undefined;
     const controlled = Boolean(options.controlled);
@@ -355,8 +390,8 @@ function buildOpenCommandContext(options, command, rootProgram) {
     };
 }
 function normalizeOpenCommandEnvironment(value) {
-    const normalized = (value ?? 'dev').trim().toLowerCase();
-    if (normalized === 'dev' || normalized === 'prod') {
+    const normalized = (value ?? "dev").trim().toLowerCase();
+    if (normalized === "dev" || normalized === "prod") {
         return normalized;
     }
     throw new Error('Invalid environment. Use "dev" or "prod".');
@@ -370,13 +405,13 @@ function buildOpenCommandTargetUrl(baseUrl, rawPath) {
         const message = error instanceof Error ? error.message : String(error);
         throw new Error(`Failed to parse base URL "${baseUrl}": ${message}`);
     }
-    targetUrl.searchParams.set('sweetlink', 'auto');
-    const fallbackPath = '/timeline';
+    targetUrl.searchParams.set("sweetlink", "auto");
+    const fallbackPath = "/timeline";
     const trimmedPath = rawPath?.trim();
     const pathSource = trimmedPath && trimmedPath.length > 0 ? trimmedPath : fallbackPath;
-    const [pathPartRaw, queryPart] = pathSource.split('?', 2);
+    const [pathPartRaw, queryPart] = pathSource.split("?", 2);
     const pathPart = pathPartRaw && pathPartRaw.length > 0 ? pathPartRaw : fallbackPath;
-    targetUrl.pathname = pathPart.startsWith('/') ? pathPart : `/${pathPart}`;
+    targetUrl.pathname = pathPart.startsWith("/") ? pathPart : `/${pathPart}`;
     if (queryPart) {
         const extraSearch = new URLSearchParams(queryPart);
         for (const [key, value] of extraSearch.entries()) {
@@ -395,7 +430,7 @@ function resolveExplicitTargetUrl(raw) {
     }
     try {
         const target = new URL(trimmed);
-        target.searchParams.set('sweetlink', target.searchParams.get('sweetlink') ?? 'auto');
+        target.searchParams.set("sweetlink", target.searchParams.get("sweetlink") ?? "auto");
         return target;
     }
     catch (error) {
@@ -404,14 +439,14 @@ function resolveExplicitTargetUrl(raw) {
     }
 }
 function resolveCookieSyncPreference(command, cookieSyncOption) {
-    const source = command.getOptionValueSource?.('cookieSync');
-    if (source === 'default') {
+    const source = command.getOptionValueSource?.("cookieSync");
+    if (source === "default") {
         return true;
     }
     return cookieSyncOption !== false;
 }
 function resolveOpenCommandTimeoutSeconds(value) {
-    if (typeof value === 'number' && Number.isFinite(value)) {
+    if (typeof value === "number" && Number.isFinite(value)) {
         return Math.max(0, value);
     }
     return 30;
@@ -424,7 +459,7 @@ async function fetchWaitTokenIfNeeded(context) {
         return await fetchCliToken(context.config);
     }
     catch (error) {
-        console.warn('Unable to fetch CLI token for session wait:', error);
+        console.warn("Unable to fetch CLI token for session wait:", error);
         return null;
     }
 }
@@ -446,60 +481,76 @@ async function handleControlledOpen(context, waitToken) {
         await handleControlledReuse(context, waitToken, reuseResult);
         return;
     }
-    console.warn('No reusable controlled Chrome session matched the target; launching a fresh controlled window.');
+    console.warn("No reusable controlled Chrome session matched the target; launching a fresh controlled window.");
     await handleControlledLaunch(context, waitToken);
 }
 async function handleControlledReuse(context, waitToken, reuseResult) {
     const shouldFocus = context.foreground && !context.headless;
+    let deepLinkResult = null;
     if (context.enableDevtools) {
         await registerControlledChromeInstance(reuseResult.devtoolsUrl, reuseResult.userDataDir);
         await cleanupControlledChromeRegistry(reuseResult.devtoolsUrl);
         await signalSweetLinkBootstrap(reuseResult.devtoolsUrl, context.targetUrlString);
         try {
-            const oauthAttempt = await attemptTwitterOauthAutoAccept({
+            deepLinkResult = await ensureDeepLinkAuthFlow({
                 devtoolsUrl: reuseResult.devtoolsUrl,
-                sessionUrl: context.targetUrlString,
-                scriptPath: context.oauthScriptPath,
+                targetUrl: context.targetUrlString,
+                oauthScriptPath: context.oauthScriptPath,
             });
-            if (oauthAttempt.handled) {
-                console.log(`Automatically approved the OAuth prompt via ${oauthAttempt.action ?? 'click'}${oauthAttempt.clickedText ? ` (${oauthAttempt.clickedText})` : ''}.`);
+            if (deepLinkResult.signInClicked) {
+                console.log("Triggered Sweetistics sign-in to reach the deep link.");
             }
-            else if (oauthAttempt.reason && oauthAttempt.reason !== 'button-not-found') {
-                const locationHint = oauthAttempt.url || oauthAttempt.title || oauthAttempt.host
-                    ? ` (at ${oauthAttempt.title ?? oauthAttempt.host ?? 'unknown page'} ${oauthAttempt.url ?? ''})`
-                    : '';
-                console.log(`OAuth auto-accept skipped: ${oauthAttempt.reason}${locationHint}.`);
+            const oauthAttempt = deepLinkResult.oauthAttempt;
+            if (oauthAttempt) {
+                if (oauthAttempt.handled) {
+                    console.log(`Automatically approved the OAuth prompt via ${oauthAttempt.action ?? "click"}${oauthAttempt.clickedText ? ` (${oauthAttempt.clickedText})` : ""}.`);
+                }
+                else if (oauthAttempt.reason && oauthAttempt.reason !== "button-not-found") {
+                    const locationHint = oauthAttempt.url || oauthAttempt.title || oauthAttempt.host
+                        ? ` (at ${oauthAttempt.title ?? oauthAttempt.host ?? "unknown page"} ${oauthAttempt.url ?? ""})`
+                        : "";
+                    console.log(`OAuth auto-accept skipped: ${oauthAttempt.reason}${locationHint}.`);
+                }
             }
         }
         catch (error) {
             if (sweetLinkDebug) {
-                console.warn('OAuth auto-accept attempt failed:', error);
+                console.warn("Deep-link auth flow failed:", error);
             }
         }
     }
     else {
-        console.log('DevTools automation disabled (--no-devtools); skipping telemetry bootstrap and OAuth auto-click.');
+        console.log("DevTools automation disabled (--no-devtools); skipping telemetry bootstrap and OAuth auto-click.");
+    }
+    if (context.enableDevtools && !deepLinkResult?.navigatedToTarget) {
+        console.warn("Deep link did not resolve in reused controlled Chrome; launching a fresh controlled window.");
+        const freshContext = {
+            ...context,
+            preferredPort: undefined,
+        };
+        await handleControlledLaunch(freshContext, waitToken);
+        return;
     }
     console.log(`Reused controlled Chrome at ${reuseResult.devtoolsUrl} (env: ${context.env}).`);
     if (reuseResult.targetAlreadyOpen) {
-        console.log('Target tab was already open; activated existing page.');
+        console.log("Target tab was already open; activated existing page.");
     }
     else {
-        console.log('Opened a new tab in the existing controlled Chrome window.');
+        console.log("Opened a new tab in the existing controlled Chrome window.");
     }
     if (context.enableDevtools) {
-        console.log('The screenshot command will continue to use this DevTools instance.');
+        console.log("The screenshot command will continue to use this DevTools instance.");
     }
     if (shouldFocus && context.enableDevtools) {
         const focused = await focusControlledChromePage(reuseResult.devtoolsUrl, context.targetUrlString);
         if (!focused && sweetLinkDebug) {
-            console.warn('Unable to focus controlled Chrome window automatically.');
+            console.warn("Unable to focus controlled Chrome window automatically.");
         }
     }
     else if (context.foreground && !context.enableDevtools) {
-        console.log('--foreground requires DevTools automation; skipping automatic focus.');
+        console.log("--foreground requires DevTools automation; skipping automatic focus.");
     }
-    console.log('Remember this session codename. Run `pnpm sweetlink sessions`, copy the session id or codename, and use that handle for every follow-up command instead of rerunning `pnpm sweetlink open`.');
+    console.log("Remember this session codename. Run `pnpm sweetlink sessions`, copy the session id or codename, and use that handle for every follow-up command instead of rerunning `pnpm sweetlink open`.");
     await waitForSessionAfterOpen(context, waitToken, {
         devtoolsUrl: context.enableDevtools ? reuseResult.devtoolsUrl : undefined,
         trigger: context.enableDevtools
@@ -509,10 +560,10 @@ async function handleControlledReuse(context, waitToken, reuseResult) {
             ? () => triggerSweetLinkCliAuto(reuseResult.devtoolsUrl, context.targetUrlString)
             : undefined,
         failureMessage: context.enableDevtools
-            ? 'Controlled Chrome reused but SweetLink did not register automatically.'
-            : 'Controlled Chrome reused. DevTools automation disabled; verify the session from the UI if SweetLink does not appear.',
+            ? "Controlled Chrome reused but SweetLink did not register automatically."
+            : "Controlled Chrome reused. DevTools automation disabled; verify the session from the UI if SweetLink does not appear.",
     });
-    await surfaceBlockingDiagnosticsAfterNavigation('SweetLink open', context.enableDevtools ? reuseResult.devtoolsUrl : undefined, context.targetUrlString);
+    await surfaceBlockingDiagnosticsAfterNavigation("SweetLink open", context.enableDevtools ? reuseResult.devtoolsUrl : undefined, context.targetUrlString);
 }
 async function handleControlledLaunch(context, waitToken) {
     const info = await launchControlledChrome(context.targetUrlString, {
@@ -521,62 +572,68 @@ async function handleControlledLaunch(context, waitToken) {
         headless: context.headless,
         foreground: context.foreground,
     });
-    const userDataDirectoryDisplay = info.userDataDir.replace(os.homedir(), '~');
+    const userDataDirectoryDisplay = info.userDataDir.replace(os.homedir(), "~");
     if (context.enableDevtools) {
         await registerControlledChromeInstance(info.devtoolsUrl, info.userDataDir);
         await cleanupControlledChromeRegistry(info.devtoolsUrl);
         await signalSweetLinkBootstrap(info.devtoolsUrl, context.targetUrlString);
         try {
-            const oauthAttempt = await attemptTwitterOauthAutoAccept({
+            const deepLinkResult = await ensureDeepLinkAuthFlow({
                 devtoolsUrl: info.devtoolsUrl,
-                sessionUrl: context.targetUrlString,
-                scriptPath: context.oauthScriptPath,
+                targetUrl: context.targetUrlString,
+                oauthScriptPath: context.oauthScriptPath,
             });
-            if (oauthAttempt.handled) {
-                console.log(`Automatically approved the OAuth prompt via ${oauthAttempt.action ?? 'click'}${oauthAttempt.clickedText ? ` (${oauthAttempt.clickedText})` : ''}.`);
+            if (deepLinkResult.signInClicked) {
+                console.log("Triggered Sweetistics sign-in to reach the deep link.");
             }
-            else if (oauthAttempt.reason && oauthAttempt.reason !== 'button-not-found') {
-                const locationHint = oauthAttempt.url || oauthAttempt.title || oauthAttempt.host
-                    ? ` (at ${oauthAttempt.title ?? oauthAttempt.host ?? 'unknown page'} ${oauthAttempt.url ?? ''})`
-                    : '';
-                console.log(`OAuth auto-accept skipped: ${oauthAttempt.reason}${locationHint}.`);
+            const oauthAttempt = deepLinkResult.oauthAttempt;
+            if (oauthAttempt) {
+                if (oauthAttempt.handled) {
+                    console.log(`Automatically approved the OAuth prompt via ${oauthAttempt.action ?? "click"}${oauthAttempt.clickedText ? ` (${oauthAttempt.clickedText})` : ""}.`);
+                }
+                else if (oauthAttempt.reason && oauthAttempt.reason !== "button-not-found") {
+                    const locationHint = oauthAttempt.url || oauthAttempt.title || oauthAttempt.host
+                        ? ` (at ${oauthAttempt.title ?? oauthAttempt.host ?? "unknown page"} ${oauthAttempt.url ?? ""})`
+                        : "";
+                    console.log(`OAuth auto-accept skipped: ${oauthAttempt.reason}${locationHint}.`);
+                }
             }
         }
         catch (error) {
             if (sweetLinkDebug) {
-                console.warn('OAuth auto-accept attempt failed:', error);
+                console.warn("Deep-link auth flow failed:", error);
             }
         }
     }
     else {
-        console.log('DevTools automation disabled (--no-devtools); launched without OAuth auto-click.');
+        console.log("DevTools automation disabled (--no-devtools); launched without OAuth auto-click.");
     }
     console.log(`Opened controlled Chrome window to ${context.targetUrlString} (env: ${context.env}).`);
     console.log(`DevTools endpoint: ${info.devtoolsUrl}`);
     console.log(`User data dir   : ${userDataDirectoryDisplay}`);
     if (context.enableDevtools) {
-        console.log('The screenshot command will auto-detect this DevTools instance.');
+        console.log("The screenshot command will auto-detect this DevTools instance.");
     }
     if (context.headless) {
-        console.log('Running in headless mode (--headless).');
+        console.log("Running in headless mode (--headless).");
     }
     const shouldFocus = context.foreground && !context.headless;
     if (shouldFocus && context.enableDevtools) {
         const focused = await focusControlledChromePage(info.devtoolsUrl, context.targetUrlString);
         if (!focused && sweetLinkDebug) {
-            console.warn('Unable to focus controlled Chrome window automatically.');
+            console.warn("Unable to focus controlled Chrome window automatically.");
         }
     }
     else if (context.foreground && !context.enableDevtools) {
-        console.log('--foreground requires DevTools automation; skipping automatic focus.');
+        console.log("--foreground requires DevTools automation; skipping automatic focus.");
     }
     await waitForSessionAfterOpen(context, waitToken, {
         devtoolsUrl: context.enableDevtools ? info.devtoolsUrl : undefined,
         failureMessage: context.enableDevtools
-            ? 'Controlled Chrome launched but SweetLink did not register automatically; keep the window open and retry from the UI if needed.'
-            : 'Controlled Chrome launched without DevTools automation; complete the login manually if SweetLink does not register.',
+            ? "Controlled Chrome launched but SweetLink did not register automatically; keep the window open and retry from the UI if needed."
+            : "Controlled Chrome launched without DevTools automation; complete the login manually if SweetLink does not register.",
     });
-    await surfaceBlockingDiagnosticsAfterNavigation('SweetLink open', context.enableDevtools ? info.devtoolsUrl : undefined, context.targetUrlString);
+    await surfaceBlockingDiagnosticsAfterNavigation("SweetLink open", context.enableDevtools ? info.devtoolsUrl : undefined, context.targetUrlString);
 }
 async function waitForSessionAfterOpen(context, waitToken, options) {
     if (!waitToken || context.timeoutSeconds <= 0) {
@@ -621,14 +678,14 @@ async function waitForSessionAfterOpen(context, waitToken, options) {
         try {
             const diagnostics = await collectBootstrapDiagnostics(options.devtoolsUrl, candidates);
             if (diagnostics) {
-                console.warn('SweetLink bootstrap diagnostics (DevTools snapshot):');
-                logBootstrapDiagnostics('SweetLink', diagnostics);
+                console.warn("SweetLink bootstrap diagnostics (DevTools snapshot):");
+                logBootstrapDiagnostics("SweetLink", diagnostics);
             }
         }
         catch (error) {
-            console.warn('Failed to collect DevTools diagnostics:', error);
+            console.warn("Failed to collect DevTools diagnostics:", error);
         }
-        await logPuppeteerPageSnapshot('SweetLink', options.devtoolsUrl, context.targetUrlString);
+        await logPuppeteerPageSnapshot("SweetLink", options.devtoolsUrl, context.targetUrlString);
     }
 }
 // Runs after every navigation so CLI users see the same crash text the browser shows.
@@ -644,7 +701,8 @@ async function surfaceBlockingDiagnosticsAfterNavigation(label, devtoolsUrl, tar
         const diagnostics = await collectBootstrapDiagnostics(devtoolsUrl, candidates);
         if (diagnostics) {
             const bootstrapIncomplete = diagnostics.autoFlag !== true ||
-                (typeof diagnostics.sessionStorageAuto === 'string' && diagnostics.sessionStorageAuto.length > 0);
+                (typeof diagnostics.sessionStorageAuto === "string" &&
+                    diagnostics.sessionStorageAuto.length > 0);
             const hasBlocking = diagnosticsContainBlockingIssues(diagnostics) || bootstrapIncomplete;
             if (hasBlocking) {
                 console.warn(`${label}: detected runtime anomalies after navigation.`);
@@ -661,7 +719,7 @@ async function surfaceBlockingDiagnosticsAfterNavigation(label, devtoolsUrl, tar
         }
     }
     catch (error) {
-        console.warn('Failed to collect DevTools diagnostics after navigation:', error);
+        console.warn("Failed to collect DevTools diagnostics after navigation:", error);
     }
     if (!loggedBlocking) {
         const nextErrors = await fetchNextDevtoolsErrors(targetUrl);
@@ -687,7 +745,7 @@ async function logPuppeteerPageSnapshot(label, devtoolsUrl, targetUrl) {
         }
         if (snapshot.overlayText) {
             console.warn(`${label} overlay (via Puppeteer):`);
-            for (const line of snapshot.overlayText.split('\n')) {
+            for (const line of snapshot.overlayText.split("\n")) {
                 const trimmed = line.trim();
                 if (trimmed.length > 0) {
                     console.warn(`  ${trimmed}`);
@@ -696,7 +754,7 @@ async function logPuppeteerPageSnapshot(label, devtoolsUrl, targetUrl) {
             return;
         }
         if (snapshot.bodyText && snapshot.bodyText.trim().length > 0) {
-            const condensed = snapshot.bodyText.replaceAll(/\s+/g, ' ').trim();
+            const condensed = snapshot.bodyText.replaceAll(/\s+/g, " ").trim();
             const snippet = condensed.length > 600 ? `${condensed.slice(0, 600)}…` : condensed;
             console.warn(`${label} body text (via Puppeteer): ${snippet}`);
         }
@@ -712,50 +770,52 @@ async function handleUncontrolledOpen(context, waitToken) {
     await launchChrome(context.targetUrlString, { foreground: context.foreground });
     console.log(`Opened Chrome to ${context.targetUrlString} (env: ${context.env}).`);
     await waitForSessionAfterOpen(context, waitToken, {
-        failureMessage: 'Chrome tab opened but SweetLink did not register within the timeout window. Use `pnpm sweetlink sessions` to inspect manually.',
+        failureMessage: "Chrome tab opened but SweetLink did not register within the timeout window. Use `pnpm sweetlink sessions` to inspect manually.",
     });
 }
 program
-    .command('smoke')
-    .description('Run the SweetLink authenticated smoke test across non-admin routes')
-    .option('--session <sessionId>', 'Existing SweetLink session id or codename to reuse')
-    .option('--routes <routes>', `Comma-separated list of routes (default ${DEFAULT_SMOKE_ROUTES.join(', ')})`)
-    .option('--timeout <seconds>', 'Per-route timeout in seconds (default 45)', Number)
-    .option('--resume', 'Resume from the last completed route', false)
+    .command("smoke")
+    .description("Run the SweetLink authenticated smoke test across non-admin routes")
+    .option("--session <sessionId>", "Existing SweetLink session id or codename to reuse")
+    .option("--routes <routes>", `Comma-separated list of routes (default ${DEFAULT_SMOKE_ROUTES.join(", ")})`)
+    .option("--timeout <seconds>", "Per-route timeout in seconds (default 45)", Number)
+    .option("--resume", "Resume from the last completed route", false)
     .action(async function () {
     const options = readCommandOptions(this);
     const routes = deriveSmokeRoutes(options.routes, DEFAULT_SMOKE_ROUTES);
     if (routes.length === 0) {
-        console.log('No routes specified for the smoke test. Provide --routes or keep the default set.');
+        console.log("No routes specified for the smoke test. Provide --routes or keep the default set.");
         return;
     }
-    const timeoutSeconds = typeof options.timeout === 'number' && Number.isFinite(options.timeout) ? Math.max(5, options.timeout) : 45;
+    const timeoutSeconds = typeof options.timeout === "number" && Number.isFinite(options.timeout)
+        ? Math.max(5, options.timeout)
+        : 45;
     await runSweetLinkSmoke({ sessionHint: options.session, routes, timeoutSeconds, resume: options.resume === true }, this);
 });
 program
-    .command('screenshot <sessionId>')
-    .description('Capture a JPEG screenshot from a SweetLink session')
-    .option('-s, --selector <selector>', 'CSS selector to capture (defaults to full page)')
-    .option('-q, --quality <0-1>', 'JPEG quality (0-1, default 0.92)', Number)
-    .option('-o, --output <path>', 'Output path (defaults to /tmp/sweetlink-<timestamp>.jpg)')
-    .option('-t, --timeout <ms>', 'Command timeout in milliseconds (default 30_000)', Number, 30_000)
-    .option('--devtools-url <url>', 'DevTools HTTP endpoint (default http://127.0.0.1:9222)')
-    .option('--method <method>', 'Capture method: auto, puppeteer, html2canvas, html-to-image', 'auto')
-    .option('--scroll-into-view', 'Scroll the target into view before capturing', false)
-    .option('--scroll-selector <selector>', 'Selector to scroll into view (defaults to capture selector)')
-    .option('--wait-for-selector <selector>', 'Wait for a selector to appear before capturing')
-    .option('--wait-visible', 'Require the wait selector to be visible', false)
-    .option('--wait-timeout <ms>', 'Timeout for --wait-for-selector (default 10_000)', Number, 10_000)
-    .option('--delay <ms>', 'Delay in milliseconds after hooks run (default 0)', Number)
-    .option('--before-script <codeOrPath>', 'Inline JS (or @path) to run before capture')
-    .option('--preset <name>', 'Hook preset compatibility alias (card-ready is applied automatically and no longer requires this flag)')
-    .option('--prompt <prompt>', 'Send the saved screenshot to Codex for analysis')
-    .addOption(program.createOption('--question <prompt>').hideHelp())
+    .command("screenshot <sessionId>")
+    .description("Capture a JPEG screenshot from a SweetLink session")
+    .option("-s, --selector <selector>", "CSS selector to capture (defaults to full page)")
+    .option("-q, --quality <0-1>", "JPEG quality (0-1, default 0.92)", Number)
+    .option("-o, --output <path>", "Output path (defaults to /tmp/sweetlink-<timestamp>.jpg)")
+    .option("-t, --timeout <ms>", "Command timeout in milliseconds (default 30_000)", Number, 30_000)
+    .option("--devtools-url <url>", "DevTools HTTP endpoint (default http://127.0.0.1:9222)")
+    .option("--method <method>", "Capture method: auto, puppeteer, html2canvas, html-to-image", "auto")
+    .option("--scroll-into-view", "Scroll the target into view before capturing", false)
+    .option("--scroll-selector <selector>", "Selector to scroll into view (defaults to capture selector)")
+    .option("--wait-for-selector <selector>", "Wait for a selector to appear before capturing")
+    .option("--wait-visible", "Require the wait selector to be visible", false)
+    .option("--wait-timeout <ms>", "Timeout for --wait-for-selector (default 10_000)", Number, 10_000)
+    .option("--delay <ms>", "Delay in milliseconds after hooks run (default 0)", Number)
+    .option("--before-script <codeOrPath>", "Inline JS (or @path) to run before capture")
+    .option("--preset <name>", "Hook preset compatibility alias (card-ready is applied automatically and no longer requires this flag)")
+    .option("--prompt <prompt>", "Send the saved screenshot to Codex for analysis")
+    .addOption(program.createOption("--question <prompt>").hideHelp())
     .action(async (sessionId, options, command) => {
     const config = resolveConfig(command);
     const resolvedSessionId = await resolveSessionIdFromHint(sessionId, config);
     const token = await fetchCliToken(config);
-    const mode = options.selector ? 'element' : 'full';
+    const mode = options.selector ? "element" : "full";
     const prompt = resolvePromptOption(options);
     const suppressOutput = Boolean(prompt);
     const logInfo = (...args) => {
@@ -764,15 +824,17 @@ program
         }
     };
     const now = new Date();
-    const defaultOutput = path.join(os.tmpdir(), `sweetlink-${now.toISOString().replaceAll(':', '-').replaceAll('.', '-')}.jpg`);
+    const defaultOutput = path.join(os.tmpdir(), `sweetlink-${now.toISOString().replaceAll(":", "-").replaceAll(".", "-")}.jpg`);
     const outputPath = options.output ? path.resolve(options.output) : defaultOutput;
-    const quality = typeof options.quality === 'number' && !Number.isNaN(options.quality) ? options.quality : 0.92;
+    const quality = typeof options.quality === "number" && !Number.isNaN(options.quality)
+        ? options.quality
+        : 0.92;
     const method = normalizeScreenshotMethod(options.method);
     await mkdir(path.dirname(outputPath), { recursive: true }).catch(() => {
         /* ignore directory creation failures; writeFile will surface if it truly fails */
     });
     const devtoolsConfig = await loadDevToolsConfig();
-    const devtoolsUrl = options.devtoolsUrl ?? devtoolsConfig?.devtoolsUrl ?? 'http://127.0.0.1:9222';
+    const devtoolsUrl = options.devtoolsUrl ?? devtoolsConfig?.devtoolsUrl ?? "http://127.0.0.1:9222";
     let sessionSummary;
     try {
         sessionSummary = await getSessionSummaryById(config, token, resolvedSessionId);
@@ -780,7 +842,7 @@ program
     catch {
         sessionSummary = undefined;
     }
-    const wantsPuppeteer = method === 'puppeteer' || method === 'auto';
+    const wantsPuppeteer = method === "puppeteer" || method === "auto";
     if (wantsPuppeteer && sessionSummary?.url) {
         const devtoolsCaptureResult = await attemptDevToolsCapture({
             devtoolsUrl,
@@ -792,21 +854,24 @@ program
         });
         if (devtoolsCaptureResult) {
             logInfo(`Saved screenshot to ${outputPath} (${devtoolsCaptureResult.width}x${devtoolsCaptureResult.height}, ${devtoolsCaptureResult.sizeKb.toFixed(1)} KB, method: ${devtoolsCaptureResult.renderer}).`);
-            await maybeDescribeScreenshot(prompt, outputPath, { silent: suppressOutput, appLabel: config.appLabel });
+            await maybeDescribeScreenshot(prompt, outputPath, {
+                silent: suppressOutput,
+                appLabel: config.appLabel,
+            });
             return;
         }
-        if (method === 'puppeteer') {
-            throw new Error('Failed to capture via Puppeteer. Ensure Chrome is running with a DevTools port (try `pnpm sweetlink open --controlled`).');
+        if (method === "puppeteer") {
+            throw new Error("Failed to capture via Puppeteer. Ensure Chrome is running with a DevTools port (try `pnpm sweetlink open --controlled`).");
         }
     }
-    const rendererOverride = method === 'html2canvas' || method === 'html-to-image' ? method : undefined;
+    const rendererOverride = method === "html2canvas" || method === "html-to-image" ? method : undefined;
     const beforeScriptCode = await resolveHookSnippet(options.beforeScript);
     const commandOptions = readCommandOptions(command);
     const presetCandidate = commandOptions.preset ?? options.preset;
-    const presetRaw = typeof presetCandidate === 'string' ? presetCandidate.trim() : '';
+    const presetRaw = typeof presetCandidate === "string" ? presetCandidate.trim() : "";
     const presetName = presetRaw.toLowerCase();
     if (presetName.length > 0) {
-        if (presetName === 'card-ready') {
+        if (presetName === "card-ready") {
             logInfo('Preset "card-ready" is now the default hook stack; the flag is optional.');
         }
         else {
@@ -819,31 +884,35 @@ program
         scrollSelector: options.scrollSelector,
         waitSelector: options.waitForSelector,
         waitVisible: options.waitVisible === undefined ? undefined : Boolean(options.waitVisible),
-        waitTimeout: typeof options.waitTimeout === 'number' && Number.isFinite(options.waitTimeout)
+        waitTimeout: typeof options.waitTimeout === "number" && Number.isFinite(options.waitTimeout)
             ? options.waitTimeout
             : undefined,
-        delayMs: typeof options.delay === 'number' && Number.isFinite(options.delay) ? options.delay : undefined,
+        delayMs: typeof options.delay === "number" && Number.isFinite(options.delay)
+            ? options.delay
+            : undefined,
         beforeScript: beforeScriptCode ?? undefined,
     };
     const hooks = buildScreenshotHooks(hookOptions);
     if (hooks.length > 0) {
-        logInfo(`Applying ${hooks.length} pre-capture hook${hooks.length === 1 ? '' : 's'} before screenshot.`);
+        logInfo(`Applying ${hooks.length} pre-capture hook${hooks.length === 1 ? "" : "s"} before screenshot.`);
     }
     const payload = {
-        type: 'screenshot',
+        type: "screenshot",
         id: createSweetLinkCommandId(),
         mode,
         selector: options.selector,
         quality,
-        timeoutMs: typeof options.timeout === 'number' && !Number.isNaN(options.timeout) ? options.timeout : 30_000,
+        timeoutMs: typeof options.timeout === "number" && !Number.isNaN(options.timeout)
+            ? options.timeout
+            : 30_000,
         renderer: rendererOverride,
         hooks: hooks.length > 0 ? hooks : undefined,
     };
     const response = await fetchJson(`${config.daemonBaseUrl}/sessions/${encodeURIComponent(resolvedSessionId)}/command`, {
-        method: 'POST',
+        method: "POST",
         headers: {
             Authorization: `Bearer ${token}`,
-            'Content-Type': 'application/json',
+            "Content-Type": "application/json",
         },
         body: JSON.stringify(payload),
     });
@@ -864,7 +933,9 @@ program
             if (fallbackOutcome.handled) {
                 return;
             }
-            const fallbackError = fallbackOutcome.fallbackResult.ok ? null : fallbackOutcome.fallbackResult.error;
+            const fallbackError = fallbackOutcome.fallbackResult.ok
+                ? null
+                : fallbackOutcome.fallbackResult.error;
             const recovered = await tryDevToolsRecovery({
                 sessionUrl: sessionSummary?.url,
                 devtoolsUrl,
@@ -906,41 +977,44 @@ program
         return;
     }
     await persistScreenshotResult(outputPath, result, { silent: suppressOutput });
-    await maybeDescribeScreenshot(prompt, outputPath, { silent: suppressOutput, appLabel: config.appLabel });
+    await maybeDescribeScreenshot(prompt, outputPath, {
+        silent: suppressOutput,
+        appLabel: config.appLabel,
+    });
 });
 program
-    .command('selectors <sessionId>')
-    .description('Discover candidate selectors within a SweetLink session')
-    .option('-l, --limit <count>', 'Maximum number of candidates to return (default 20)', Number)
-    .option('-m, --max <count>', 'Alias for --limit', Number)
-    .option('--scope <selector>', 'Restrict discovery to elements inside this selector')
-    .option('--include-hidden', 'Include off-screen or hidden elements', false)
-    .option('--json', 'Output JSON payload', false)
+    .command("selectors <sessionId>")
+    .description("Discover candidate selectors within a SweetLink session")
+    .option("-l, --limit <count>", "Maximum number of candidates to return (default 20)", Number)
+    .option("-m, --max <count>", "Alias for --limit", Number)
+    .option("--scope <selector>", "Restrict discovery to elements inside this selector")
+    .option("--include-hidden", "Include off-screen or hidden elements", false)
+    .option("--json", "Output JSON payload", false)
     .action(async (sessionId, options, command) => {
     const config = resolveConfig(command);
     const resolvedSessionId = await resolveSessionIdFromHint(sessionId, config);
     const token = await fetchCliToken(config);
     const limit = (() => {
-        if (typeof options.max === 'number' && Number.isFinite(options.max)) {
+        if (typeof options.max === "number" && Number.isFinite(options.max)) {
             return Math.max(1, Math.floor(options.max));
         }
-        if (typeof options.limit === 'number' && Number.isFinite(options.limit)) {
+        if (typeof options.limit === "number" && Number.isFinite(options.limit)) {
             return Math.max(1, Math.floor(options.limit));
         }
         return 20;
     })();
     const payload = {
-        type: 'discoverSelectors',
+        type: "discoverSelectors",
         id: createSweetLinkCommandId(),
         scopeSelector: options.scope ?? null,
         limit,
         includeHidden: Boolean(options.includeHidden),
     };
     const response = await fetchJson(`${config.daemonBaseUrl}/sessions/${encodeURIComponent(resolvedSessionId)}/command`, {
-        method: 'POST',
+        method: "POST",
         headers: {
             Authorization: `Bearer ${token}`,
-            'Content-Type': 'application/json',
+            "Content-Type": "application/json",
         },
         body: JSON.stringify(payload),
     });
@@ -963,15 +1037,15 @@ program
         return;
     }
     if (candidates.length === 0) {
-        console.log('No candidates were discovered. Ensure the target UI is mounted and try again.');
-        console.log('Tip: use --scope to limit discovery or --include-hidden to inspect collapsed panels.');
+        console.log("No candidates were discovered. Ensure the target UI is mounted and try again.");
+        console.log("Tip: use --scope to limit discovery or --include-hidden to inspect collapsed panels.");
         return;
     }
-    console.log(`Discovered ${candidates.length} selector candidate${candidates.length === 1 ? '' : 's'} (limit ${limit}):\n`);
+    console.log(`Discovered ${candidates.length} selector candidate${candidates.length === 1 ? "" : "s"} (limit ${limit}):\n`);
     for (const candidate of candidates.slice(0, limit)) {
         console.log(`• ${candidate.selector}`);
         console.log(`  Hook     : ${candidate.hook} (score ${candidate.score})`);
-        console.log(`  Visible  : ${candidate.visible ? 'yes' : 'no'} (${candidate.size.width}x${candidate.size.height})`);
+        console.log(`  Visible  : ${candidate.visible ? "yes" : "no"} (${candidate.size.width}x${candidate.size.height})`);
         console.log(`  Text     : ${candidate.textSnippet}`);
         if (candidate.dataTarget) {
             console.log(`  Target   : data-sweetlink-target="${candidate.dataTarget}"`);
@@ -984,64 +1058,66 @@ program
         }
         console.log(`  Position : x=${candidate.position.left}, y=${candidate.position.top}`);
         console.log(`  Path     : ${candidate.path}`);
-        console.log('');
+        console.log("");
     }
 });
-const devtools = program.command('devtools').description('Inspect DevTools-enabled Chrome sessions');
+const devtools = program
+    .command("devtools")
+    .description("Inspect DevTools-enabled Chrome sessions");
 devtools
-    .command('status')
-    .description('Show DevTools connection status and telemetry summary')
-    .option('--json', 'Output JSON payload', false)
+    .command("status")
+    .description("Show DevTools connection status and telemetry summary")
+    .option("--json", "Output JSON payload", false)
     .action(async (options, command) => {
     await devtoolsStatus(options, command);
 });
 devtools
-    .command('tabs')
-    .description('List open tabs in the controlled Chrome window')
-    .option('--json', 'Output JSON payload', false)
+    .command("tabs")
+    .description("List open tabs in the controlled Chrome window")
+    .option("--json", "Output JSON payload", false)
     .action(async (options) => {
     await devtoolsTabs(options);
 });
 devtools
-    .command('console')
-    .description('Print buffered console events from the controlled Chrome window')
-    .option('--tail <count>', 'Number of entries to show (default 50)', Number, 50)
-    .option('--json', 'Output JSON payload', false)
+    .command("console")
+    .description("Print buffered console events from the controlled Chrome window")
+    .option("--tail <count>", "Number of entries to show (default 50)", Number, 50)
+    .option("--json", "Output JSON payload", false)
     .action(async (options) => {
     await devtoolsShowConsole(options);
 });
 devtools
-    .command('network')
-    .description('Print buffered network requests from the controlled Chrome window')
-    .option('--tail <count>', 'Number of entries to show (default 50)', Number, 50)
-    .option('--json', 'Output JSON payload', false)
+    .command("network")
+    .description("Print buffered network requests from the controlled Chrome window")
+    .option("--tail <count>", "Number of entries to show (default 50)", Number, 50)
+    .option("--json", "Output JSON payload", false)
     .action(async (options) => {
     await devtoolsShowNetwork(options);
 });
 devtools
-    .command('listen')
-    .description('Attach to DevTools and buffer console/network telemetry locally')
-    .option('--session <sessionId>', 'Associate telemetry with a SweetLink session id')
-    .option('--reset', 'Clear existing telemetry buffers before listening', false)
-    .option('--background', 'Run without interactive prompts (for automation)', false)
+    .command("listen")
+    .description("Attach to DevTools and buffer console/network telemetry locally")
+    .option("--session <sessionId>", "Associate telemetry with a SweetLink session id")
+    .option("--reset", "Clear existing telemetry buffers before listening", false)
+    .option("--background", "Run without interactive prompts (for automation)", false)
     .action(async (options, command) => {
     await devtoolsListen(options, command);
 });
 devtools
-    .command('authorize')
-    .description('Attempt to auto-click the OAuth authorize prompt in the controlled browser')
-    .option('--url <url>', 'Override the candidate OAuth URL (defaults to the tracked session)')
+    .command("authorize")
+    .description("Attempt to auto-click the OAuth authorize prompt in the controlled browser")
+    .option("--url <url>", "Override the candidate OAuth URL (defaults to the tracked session)")
     .action(async (options, command) => {
     await devtoolsAuthorize(options, command);
 });
-program.hook('preAction', () => {
+program.hook("preAction", () => {
     // Ensure commander does not swallow promise rejections so we can log helpful messages.
-    process.on('unhandledRejection', (error) => {
+    process.on("unhandledRejection", (error) => {
         reportError(error);
         process.exitCode = 1;
     });
 });
-program.addHelpText('afterAll', `
+program.addHelpText("afterAll", `
 DevTools commands:
   devtools status            Show endpoint reachability, viewport, and buffer sizes
   devtools tabs              List open tabs in the controlled Chrome window
@@ -1073,19 +1149,19 @@ async function resolveHookSnippet(value) {
     if (trimmed.length === 0) {
         return null;
     }
-    if (trimmed.startsWith('@')) {
+    if (trimmed.startsWith("@")) {
         const candidatePath = trimmed.slice(1).trim();
         if (!candidatePath) {
-            throw new Error('Expected a file path after @ for --before-script.');
+            throw new Error("Expected a file path after @ for --before-script.");
         }
         const absolute = path.isAbsolute(candidatePath) ? candidatePath : path.resolve(candidatePath);
-        const hookContents = await readFile(absolute, 'utf8');
+        const hookContents = await readFile(absolute, "utf8");
         return hookContents.toString();
     }
     return trimmed;
 }
 export function formatPathForDisplay(value) {
-    return value.replace(os.homedir(), '~');
+    return value.replace(os.homedir(), "~");
 }
 function reportError(error) {
     if (error instanceof CommanderError) {
@@ -1096,32 +1172,32 @@ function reportError(error) {
         console.error(error.message);
         return;
     }
-    console.error('Unexpected error', error);
+    console.error("Unexpected error", error);
 }
 function normalizeScreenshotMethod(input) {
     if (!input) {
-        return 'auto';
+        return "auto";
     }
     const normalized = input.toLowerCase().trim();
     switch (normalized) {
-        case 'auto': {
-            return 'auto';
+        case "auto": {
+            return "auto";
         }
-        case 'puppeteer': {
-            return 'puppeteer';
+        case "puppeteer": {
+            return "puppeteer";
         }
-        case 'html2canvas':
-        case 'html-2-canvas': {
-            return 'html2canvas';
+        case "html2canvas":
+        case "html-2-canvas": {
+            return "html2canvas";
         }
-        case 'html-to-image':
-        case 'htmltoimage':
-        case 'dom-to-image':
-        case 'domtoimage': {
-            return 'html-to-image';
+        case "html-to-image":
+        case "htmltoimage":
+        case "dom-to-image":
+        case "domtoimage": {
+            return "html-to-image";
         }
         default: {
-            throw new Error('Invalid screenshot method. Use auto, puppeteer, html2canvas, or html-to-image.');
+            throw new Error("Invalid screenshot method. Use auto, puppeteer, html2canvas, or html-to-image.");
         }
     }
 }
@@ -1129,7 +1205,7 @@ async function resolveSmokePrerequisites(params, command) {
     const config = resolveConfig(command);
     const devtoolsConfig = await loadDevToolsConfig();
     if (!devtoolsConfig?.devtoolsUrl) {
-        console.error('DevTools endpoint not found. Launch a controlled Chrome window with `pnpm sweetlink open --controlled` first.');
+        console.error("DevTools endpoint not found. Launch a controlled Chrome window with `pnpm sweetlink open --controlled` first.");
         process.exitCode = 1;
         return null;
     }
@@ -1137,7 +1213,7 @@ async function resolveSmokePrerequisites(params, command) {
         ? await resolveSessionIdFromHint(params.sessionHint, config)
         : (devtoolsConfig.sessionId ?? null);
     if (!sessionId) {
-        console.error('Unable to determine a SweetLink session. Pass --session or rerun `pnpm sweetlink open --controlled`.');
+        console.error("Unable to determine a SweetLink session. Pass --session or rerun `pnpm sweetlink open --controlled`.");
         process.exitCode = 1;
         return null;
     }
@@ -1146,7 +1222,7 @@ async function resolveSmokePrerequisites(params, command) {
         token = await fetchCliToken(config);
     }
     catch (error) {
-        console.error('Unable to fetch SweetLink CLI token:', extractEventMessage(error));
+        console.error("Unable to fetch SweetLink CLI token:", extractEventMessage(error));
         process.exitCode = 1;
         return null;
     }
@@ -1173,18 +1249,18 @@ async function determineSmokeStartIndex(options) {
         }
         catch (error) {
             if (sweetLinkDebug) {
-                console.warn('Failed to clear stored smoke progress before run:', error);
+                console.warn("Failed to clear stored smoke progress before run:", error);
             }
         }
         return 0;
     }
     const savedIndex = await loadSmokeProgressIndex(options.baseOrigin, options.routes);
     if (savedIndex === null) {
-        console.log('No prior smoke progress found. Starting from the beginning.');
+        console.log("No prior smoke progress found. Starting from the beginning.");
         return 0;
     }
     if (savedIndex >= options.routes.length) {
-        console.log('Previous smoke run completed every route. Starting from the beginning.');
+        console.log("Previous smoke run completed every route. Starting from the beginning.");
         return 0;
     }
     if (savedIndex > 0) {
@@ -1210,12 +1286,12 @@ async function executeSmokeRoute(context, state, route, routeIndex) {
             lastKnownUrl,
             failure: {
                 route: `#${routeIndex + 1}`,
-                reason: 'Missing route entry in smoke route list.',
+                reason: "Missing route entry in smoke route list.",
             },
         };
     }
     const targetUrl = buildSmokeRouteUrl(context.baseUrl, route);
-    const displayPath = `${targetUrl.pathname}${targetUrl.search || ''}`;
+    const displayPath = `${targetUrl.pathname}${targetUrl.search || ""}`;
     console.log(`\n→ ${displayPath}`);
     const sessionConnected = await ensureSweetLinkSessionConnected({
         config: context.config,
@@ -1228,23 +1304,27 @@ async function executeSmokeRoute(context, state, route, routeIndex) {
         candidateUrls: [targetUrl.toString()],
     });
     if (!sessionConnected) {
-        console.warn('  Unable to verify active SweetLink session before navigation.');
+        console.warn("  Unable to verify active SweetLink session before navigation.");
         return {
             session,
             lastKnownUrl,
-            failure: { route: displayPath, reason: 'session unavailable before navigation' },
+            failure: { route: displayPath, reason: "session unavailable before navigation" },
         };
     }
     const attemptNavigation = async () => {
-        await navigateSweetLinkSession({ sessionId: activeSessionId, targetUrl, config: context.config });
+        await navigateSweetLinkSession({
+            sessionId: activeSessionId,
+            targetUrl,
+            config: context.config,
+        });
     };
     try {
         await attemptNavigation();
     }
     catch (error) {
-        const reason = extractEventMessage(error, 'navigation failed');
+        const reason = extractEventMessage(error, "navigation failed");
         if (SESSION_RECOVERY_PATTERN.test(reason)) {
-            console.warn('  Session went offline during navigation command. Attempting recovery…');
+            console.warn("  Session went offline during navigation command. Attempting recovery…");
             const recovered = await ensureSweetLinkSessionConnected({
                 config: context.config,
                 token: context.token,
@@ -1260,7 +1340,7 @@ async function executeSmokeRoute(context, state, route, routeIndex) {
                     await attemptNavigation();
                 }
                 catch (retryError) {
-                    const retryReason = extractEventMessage(retryError, 'navigation failed');
+                    const retryReason = extractEventMessage(retryError, "navigation failed");
                     console.warn(`  Navigation failed after recovery: ${retryReason}`);
                     return { session, lastKnownUrl, failure: { route: displayPath, reason: retryReason } };
                 }
@@ -1283,7 +1363,7 @@ async function executeSmokeRoute(context, state, route, routeIndex) {
         devtoolsUrl: context.devtoolsUrl,
     });
     if (!handshake && context.devtoolsUrl) {
-        console.warn('  SweetLink session did not reconnect after navigation. Retrying bootstrap…');
+        console.warn("  SweetLink session did not reconnect after navigation. Retrying bootstrap…");
         await triggerSweetLinkCliAuto(context.devtoolsUrl, targetUrl.toString());
         handshake = await waitForSweetLinkSession({
             config: context.config,
@@ -1305,7 +1385,9 @@ async function executeSmokeRoute(context, state, route, routeIndex) {
             });
             if (recovered) {
                 const refreshed = await getSessionSummaryById(context.config, context.token, activeSessionId);
-                const recoveredUrl = typeof refreshed?.url === 'string' && refreshed.url.length > 0 ? refreshed.url : targetUrl.toString();
+                const recoveredUrl = typeof refreshed?.url === "string" && refreshed.url.length > 0
+                    ? refreshed.url
+                    : targetUrl.toString();
                 handshake = {
                     sessionId: activeSessionId,
                     url: recoveredUrl,
@@ -1314,43 +1396,48 @@ async function executeSmokeRoute(context, state, route, routeIndex) {
         }
     }
     if (!handshake) {
-        console.warn('  SweetLink session did not come back online after navigation.');
+        console.warn("  SweetLink session did not come back online after navigation.");
         return {
             session,
             lastKnownUrl,
-            failure: { route: displayPath, reason: 'session did not reconnect' },
+            failure: { route: displayPath, reason: "session did not reconnect" },
         };
     }
     if (handshake.sessionId && handshake.sessionId !== activeSessionId) {
         setActiveSessionId(handshake.sessionId);
     }
     lastKnownUrl = handshake.url ?? targetUrl.toString();
-    session = (await getSessionSummaryById(context.config, context.token, activeSessionId)) ?? session;
+    session =
+        (await getSessionSummaryById(context.config, context.token, activeSessionId)) ?? session;
     const diagnostics = await waitForSmokeRouteReady({
         devtoolsUrl: context.devtoolsUrl,
         targetUrl,
         timeoutMs: context.timeoutSeconds * 1000,
     });
     if (!diagnostics) {
-        console.warn('  Timed out waiting for the route to reach a stable state.');
-        return { session, lastKnownUrl, failure: { route: displayPath, reason: 'timeout awaiting route readiness' } };
+        console.warn("  Timed out waiting for the route to reach a stable state.");
+        return {
+            session,
+            lastKnownUrl,
+            failure: { route: displayPath, reason: "timeout awaiting route readiness" },
+        };
     }
-    const finalHref = diagnostics.locationHref ?? 'unknown';
+    const finalHref = diagnostics.locationHref ?? "unknown";
     if (!urlsRoughlyMatch(finalHref, targetUrl.toString())) {
         console.warn(`  Expected ${targetUrl.toString()} but browser reported ${finalHref}.`);
         return {
             session,
             lastKnownUrl,
-            failure: { route: displayPath, reason: 'unexpected location after navigation' },
+            failure: { route: displayPath, reason: "unexpected location after navigation" },
         };
     }
     if (diagnosticsContainBlockingIssues(diagnostics)) {
-        console.warn('  Blocking diagnostics detected while loading the route:');
-        logBootstrapDiagnostics('Smoke', diagnostics);
+        console.warn("  Blocking diagnostics detected while loading the route:");
+        logBootstrapDiagnostics("Smoke", diagnostics);
         return {
             session,
             lastKnownUrl,
-            failure: { route: displayPath, reason: 'runtime diagnostics reported blocking issues' },
+            failure: { route: displayPath, reason: "runtime diagnostics reported blocking issues" },
         };
     }
     const consoleEvents = await fetchConsoleEvents(context.config, activeSessionId).catch(() => []);
@@ -1360,26 +1447,26 @@ async function executeSmokeRoute(context, state, route, routeIndex) {
     }
     const authEvents = newEvents.filter((event) => consoleEventIndicatesAuthIssue(event));
     if (authEvents.length > 0) {
-        console.warn('  Detected authentication failures in the console log:');
+        console.warn("  Detected authentication failures in the console log:");
         for (const event of authEvents.slice(-5)) {
             console.warn(`    ${formatConsoleEventSummary(event)}`);
         }
         return {
             session,
             lastKnownUrl,
-            failure: { route: displayPath, reason: 'authentication failures detected in console output' },
+            failure: { route: displayPath, reason: "authentication failures detected in console output" },
         };
     }
     const runtimeErrorEvents = newEvents.filter((event) => consoleEventIndicatesRuntimeError(event));
     if (runtimeErrorEvents.length > 0) {
-        console.warn('  Detected console errors after the route finished loading:');
+        console.warn("  Detected console errors after the route finished loading:");
         for (const event of runtimeErrorEvents.slice(-5)) {
             console.warn(`    ${formatConsoleEventSummary(event)}`);
         }
         return {
             session,
             lastKnownUrl,
-            failure: { route: displayPath, reason: 'console errors detected after load' },
+            failure: { route: displayPath, reason: "console errors detected after load" },
         };
     }
     try {
@@ -1387,10 +1474,10 @@ async function executeSmokeRoute(context, state, route, routeIndex) {
     }
     catch (error) {
         if (sweetLinkDebug) {
-            console.warn('Failed to persist smoke progress after route completion:', error);
+            console.warn("Failed to persist smoke progress after route completion:", error);
         }
     }
-    console.log('  ✅ Route passed without authentication or runtime errors.');
+    console.log("  ✅ Route passed without authentication or runtime errors.");
     return {
         session,
         lastKnownUrl,
@@ -1413,9 +1500,9 @@ async function runSweetLinkSmoke(params, command) {
     const initialConsoleEvents = await fetchConsoleEvents(config, sessionId).catch(() => []);
     const seenConsoleIds = new Set(initialConsoleEvents.map((event) => event.id));
     const remainingRouteCount = params.routes.length - startIndex;
-    console.log(`Running SweetLink smoke test across ${remainingRouteCount} route${remainingRouteCount === 1 ? '' : 's'} using session ${formatSessionHeadline(initialSession)}.`);
+    console.log(`Running SweetLink smoke test across ${remainingRouteCount} route${remainingRouteCount === 1 ? "" : "s"} using session ${formatSessionHeadline(initialSession)}.`);
     if (startIndex > 0) {
-        console.log(`Skipping ${startIndex} route${startIndex === 1 ? '' : 's'} that already passed in a previous run.`);
+        console.log(`Skipping ${startIndex} route${startIndex === 1 ? "" : "s"} that already passed in a previous run.`);
     }
     let lastKnownUrl = initialSession.url ?? baseUrl.toString();
     const context = {
@@ -1441,11 +1528,11 @@ async function runSweetLinkSmoke(params, command) {
         }
     }
     if (failures.length > 0) {
-        console.error(`\nSweetLink smoke test detected issues on ${failures.length} route${failures.length === 1 ? '' : 's'}:`);
+        console.error(`\nSweetLink smoke test detected issues on ${failures.length} route${failures.length === 1 ? "" : "s"}:`);
         for (const failure of failures) {
             console.error(`  - ${failure.route}: ${failure.reason}`);
         }
-        console.error('Review the diagnostics above, fix the auth flow, and rerun `pnpm sweetlink smoke`.');
+        console.error("Review the diagnostics above, fix the auth flow, and rerun `pnpm sweetlink smoke`.");
         if (process.exitCode === undefined || process.exitCode === 0) {
             process.exitCode = 1;
         }
@@ -1456,18 +1543,18 @@ async function runSweetLinkSmoke(params, command) {
         }
         catch (error) {
             if (sweetLinkDebug) {
-                console.warn('Failed to clear smoke progress after successful run:', error);
+                console.warn("Failed to clear smoke progress after successful run:", error);
             }
         }
-        console.log('\nSweetLink smoke test passed for all routes.');
+        console.log("\nSweetLink smoke test passed for all routes.");
     }
 }
 function extractPathSegments(routePath) {
     const normalized = trimTrailingSlash(routePath);
-    if (normalized === '/' || normalized.length === 0) {
+    if (normalized === "/" || normalized.length === 0) {
         return [];
     }
-    return normalized.replace(LEADING_SLASH_PATTERN, '').split('/');
+    return normalized.replace(LEADING_SLASH_PATTERN, "").split("/");
 }
 function suffixSegmentsAllowed(segments) {
     if (segments.length === 0) {
@@ -1485,8 +1572,8 @@ export const __sweetlinkCliTestHelpers = {
     buildClickScript,
 };
 /* biome-ignore lint/performance/noBarrelFile: CLI entrypoint intentionally re-exports runtime helpers for compatibility. */
-export { diagnosticsContainBlockingIssues, logBootstrapDiagnostics } from './runtime/devtools.js';
-export { buildClickScript, fetchConsoleEvents, fetchSessionSummaries, formatSessionHeadline, resolvePromptOption, resolveSessionIdFromHint, } from './runtime/session.js';
+export { diagnosticsContainBlockingIssues, logBootstrapDiagnostics } from "./runtime/devtools.js";
+export { buildClickScript, fetchConsoleEvents, fetchSessionSummaries, formatSessionHeadline, resolvePromptOption, resolveSessionIdFromHint, } from "./runtime/session.js";
 function urlsRoughlyMatch(a, b) {
     const urlA = normalizeUrlForMatch(a);
     const urlB = normalizeUrlForMatch(b);
@@ -1516,7 +1603,7 @@ function urlsRoughlyMatch(a, b) {
 async function devtoolsAuthorize(options, command) {
     const devtoolsConfig = await loadDevToolsConfig();
     if (!devtoolsConfig?.devtoolsUrl) {
-        console.log('No DevTools session detected. Launch Chrome with `pnpm sweetlink open --controlled` first.');
+        console.log("No DevTools session detected. Launch Chrome with `pnpm sweetlink open --controlled` first.");
         return;
     }
     const cliConfig = resolveConfig(command);
@@ -1549,12 +1636,12 @@ async function devtoolsAuthorize(options, command) {
         }
         catch (error) {
             if (sweetLinkDebug) {
-                console.warn('Failed to inspect DevTools tabs for authorize command:', error);
+                console.warn("Failed to inspect DevTools tabs for authorize command:", error);
             }
         }
     }
     if (!sessionUrl) {
-        console.error('Unable to determine which tab contains the OAuth consent screen. Pass --url <authorizeUrl> to override.');
+        console.error("Unable to determine which tab contains the OAuth consent screen. Pass --url <authorizeUrl> to override.");
         if (process.exitCode === undefined) {
             process.exitCode = 1;
         }
@@ -1567,18 +1654,18 @@ async function devtoolsAuthorize(options, command) {
             scriptPath: cliConfig.oauthScriptPath,
         });
         if (result.handled) {
-            console.log(`Authorize prompt handled via ${result.action ?? 'click'}${result.clickedText ? ` (${result.clickedText})` : ''}.`);
+            console.log(`Authorize prompt handled via ${result.action ?? "click"}${result.clickedText ? ` (${result.clickedText})` : ""}.`);
         }
         else {
-            const reason = result.reason ?? 'no authorize button detected';
+            const reason = result.reason ?? "no authorize button detected";
             console.log(`Authorize prompt not handled automatically (${reason}).`);
-            if (reason === 'requires-login') {
-                console.log('Twitter login inputs detected. Complete login manually and rerun the command.');
+            if (reason === "requires-login") {
+                console.log("Twitter login inputs detected. Complete login manually and rerun the command.");
             }
         }
     }
     catch (error) {
-        console.error('Failed to trigger OAuth authorize automation:', extractEventMessage(error));
+        console.error("Failed to trigger OAuth authorize automation:", extractEventMessage(error));
         if (process.exitCode === undefined) {
             process.exitCode = 1;
         }
@@ -1587,13 +1674,13 @@ async function devtoolsAuthorize(options, command) {
 async function devtoolsStatus(options, command) {
     const config = await loadDevToolsConfig();
     if (!config) {
-        console.log('No DevTools session detected. Launch Chrome with `pnpm sweetlink open --controlled` first.');
+        console.log("No DevTools session detected. Launch Chrome with `pnpm sweetlink open --controlled` first.");
         return;
     }
     let reachable;
     let tabs = [];
     try {
-        const response = await fetch(`${config.devtoolsUrl.replace(TRAILING_SLASH_PATTERN, '')}/json/version`, { method: 'GET' });
+        const response = await fetch(`${config.devtoolsUrl.replace(TRAILING_SLASH_PATTERN, "")}/json/version`, { method: "GET" });
         if (response.ok) {
             reachable = true;
             tabs = await fetchDevToolsTabs(config.devtoolsUrl);
@@ -1637,7 +1724,7 @@ async function devtoolsStatus(options, command) {
         process.stdout.write(`${JSON.stringify(summary, null, 2)}\n`);
         return;
     }
-    const reachabilityLabel = isReachable ? 'reachable' : 'offline';
+    const reachabilityLabel = isReachable ? "reachable" : "offline";
     console.log(`DevTools endpoint : ${config.devtoolsUrl} (${reachabilityLabel})`);
     console.log(`Last updated      : ${new Date(config.updatedAt).toISOString()}`);
     if (config.viewport) {
@@ -1646,7 +1733,7 @@ async function devtoolsStatus(options, command) {
     }
     console.log(`Tabs              : ${tabs.length}`);
     if (matchedSessionId) {
-        console.log(`Linked session    : ${matchedSessionId}${matchedSessionTitle ? ` (${matchedSessionTitle})` : ''}`);
+        console.log(`Linked session    : ${matchedSessionId}${matchedSessionTitle ? ` (${matchedSessionTitle})` : ""}`);
     }
     console.log(`Console buffer    : ${state?.console.length ?? 0} entries`);
     console.log(`Network buffer    : ${state?.network.length ?? 0} entries`);
@@ -1657,7 +1744,7 @@ async function devtoolsStatus(options, command) {
 async function devtoolsTabs(options) {
     const config = await loadDevToolsConfig();
     if (!config) {
-        console.log('No DevTools session detected. Launch Chrome with `pnpm sweetlink open --controlled` first.');
+        console.log("No DevTools session detected. Launch Chrome with `pnpm sweetlink open --controlled` first.");
         return;
     }
     const tabs = await fetchDevToolsTabs(config.devtoolsUrl);
@@ -1666,23 +1753,23 @@ async function devtoolsTabs(options) {
         return;
     }
     if (tabs.length === 0) {
-        console.log('No tabs reported by DevTools.');
+        console.log("No tabs reported by DevTools.");
         return;
     }
     for (const tab of tabs) {
-        console.log(`• ${tab.title || '(untitled)'}`);
+        console.log(`• ${tab.title || "(untitled)"}`);
         console.log(`  URL : ${tab.url}`);
         console.log(`  ID  : ${tab.id}`);
         if (tab.type) {
             console.log(`  Type: ${tab.type}`);
         }
-        console.log('');
+        console.log("");
     }
 }
 async function devtoolsShowConsole(options) {
     const state = await loadDevToolsState();
     if (!state || state.console.length === 0) {
-        console.log('No console events recorded. Run `pnpm sweetlink devtools listen` to start capturing telemetry.');
+        console.log("No console events recorded. Run `pnpm sweetlink devtools listen` to start capturing telemetry.");
         return;
     }
     const tail = Number.isFinite(options.tail) && options.tail > 0 ? Math.floor(options.tail) : 50;
@@ -1693,19 +1780,19 @@ async function devtoolsShowConsole(options) {
     }
     for (const entry of entries) {
         const timestamp = new Date(entry.ts).toISOString();
-        let location = '';
+        let location = "";
         if (entry.location?.url) {
-            const lineSuffix = entry.location.lineNumber === undefined ? '' : `:${entry.location.lineNumber}`;
-            const columnSuffix = entry.location.columnNumber === undefined ? '' : `:${entry.location.columnNumber}`;
+            const lineSuffix = entry.location.lineNumber === undefined ? "" : `:${entry.location.lineNumber}`;
+            const columnSuffix = entry.location.columnNumber === undefined ? "" : `:${entry.location.columnNumber}`;
             location = ` (${entry.location.url}${lineSuffix}${columnSuffix})`;
         }
-        let argsSuffix = '';
+        let argsSuffix = "";
         if (entry.args.length > 0) {
             const formattedArgs = [];
             for (const value of entry.args) {
                 formattedArgs.push(formatConsoleArg(value));
             }
-            argsSuffix = ` ${formattedArgs.join(' ')}`;
+            argsSuffix = ` ${formattedArgs.join(" ")}`;
         }
         console.log(`[${timestamp}] ${entry.type}: ${entry.text}${argsSuffix}${location}`);
     }
@@ -1713,7 +1800,7 @@ async function devtoolsShowConsole(options) {
 async function devtoolsShowNetwork(options) {
     const state = await loadDevToolsState();
     if (!state || state.network.length === 0) {
-        console.log('No network entries recorded. Run `pnpm sweetlink devtools listen` to start capturing telemetry.');
+        console.log("No network entries recorded. Run `pnpm sweetlink devtools listen` to start capturing telemetry.");
         return;
     }
     const tail = Number.isFinite(options.tail) && options.tail > 0 ? Math.floor(options.tail) : 50;
@@ -1724,8 +1811,8 @@ async function devtoolsShowNetwork(options) {
     }
     for (const entry of entries) {
         const timestamp = new Date(entry.ts).toISOString();
-        const status = entry.status === undefined ? (entry.failureText ?? 'failed') : entry.status;
-        const type = entry.resourceType ? ` [${entry.resourceType}]` : '';
+        const status = entry.status === undefined ? (entry.failureText ?? "failed") : entry.status;
+        const type = entry.resourceType ? ` [${entry.resourceType}]` : "";
         console.log(`[${timestamp}] ${entry.method} ${status} ${entry.url}${type}`);
     }
 }
@@ -1734,7 +1821,7 @@ async function devtoolsListen(options, command) {
     const config = await loadDevToolsConfig();
     if (!config) {
         if (!background) {
-            console.log('No DevTools session detected. Launch Chrome with `pnpm sweetlink open --controlled` first.');
+            console.log("No DevTools session detected. Launch Chrome with `pnpm sweetlink open --controlled` first.");
         }
         return;
     }
@@ -1742,12 +1829,12 @@ async function devtoolsListen(options, command) {
         try {
             await rm(DEVTOOLS_STATE_PATH, { force: true });
             if (!background) {
-                console.log('Cleared cached DevTools telemetry state.');
+                console.log("Cleared cached DevTools telemetry state.");
             }
         }
         catch (error) {
-            if (!isErrnoException(error) || error.code !== 'ENOENT') {
-                console.warn('Failed to reset DevTools state:', error);
+            if (!isErrnoException(error) || error.code !== "ENOENT") {
+                console.warn("Failed to reset DevTools state:", error);
             }
         }
     }
@@ -1763,10 +1850,10 @@ async function devtoolsListen(options, command) {
             await saveDevToolsState(state);
         }
         catch (error) {
-            console.warn('Failed to persist reset DevTools state:', error);
+            console.warn("Failed to persist reset DevTools state:", error);
         }
         if (!background) {
-            console.log('Reset complete. Re-run without --reset to resume live capture.');
+            console.log("Reset complete. Re-run without --reset to resume live capture.");
         }
         return;
     }
@@ -1782,7 +1869,7 @@ async function devtoolsListen(options, command) {
             await saveDevToolsConfig({ devtoolsUrl: config.devtoolsUrl, sessionId });
         }
         catch (error) {
-            logDebugError('Failed to persist DevTools session binding', error);
+            logDebugError("Failed to persist DevTools session binding", error);
         }
     }
     if (!background) {
@@ -1794,8 +1881,8 @@ async function devtoolsListen(options, command) {
         ({ browser, page } = await connectToDevTools(config));
     }
     catch (error) {
-        console.error('Failed to connect to the DevTools endpoint:', extractEventMessage(error));
-        console.error('Hint: ensure a controlled Chrome window is running via `pnpm sweetlink open --controlled`.');
+        console.error("Failed to connect to the DevTools endpoint:", extractEventMessage(error));
+        console.error("Hint: ensure a controlled Chrome window is running via `pnpm sweetlink open --controlled`.");
         process.exitCode = 1;
         return;
     }
@@ -1809,7 +1896,7 @@ async function devtoolsListen(options, command) {
         await saveDevToolsConfig({ devtoolsUrl: config.devtoolsUrl, viewport });
     }
     catch (error) {
-        logDebugError('Failed to persist DevTools viewport configuration', error);
+        logDebugError("Failed to persist DevTools viewport configuration", error);
     }
     const flush = async () => {
         await saveDevToolsState(devtoolsState);
@@ -1824,14 +1911,14 @@ async function devtoolsListen(options, command) {
             timer = setTimeout(() => {
                 timer = null;
                 flush().catch((error) => {
-                    console.warn('Failed to persist DevTools telemetry:', error);
+                    console.warn("Failed to persist DevTools telemetry:", error);
                 });
             }, 300);
         };
     })();
     const attachListeners = (p) => {
         // Capture console and network events for the page and trim buffers as they grow.
-        p.on('console', (message) => {
+        p.on("console", (message) => {
             const persistConsole = async () => {
                 const entry = await serializeConsoleMessage(message);
                 devtoolsState.console.push(entry);
@@ -1839,10 +1926,10 @@ async function devtoolsListen(options, command) {
                 scheduleFlush();
             };
             persistConsole().catch((error) => {
-                console.warn('Failed to serialize console message:', error);
+                console.warn("Failed to serialize console message:", error);
             });
         });
-        p.on('requestfinished', (request) => {
+        p.on("requestfinished", (request) => {
             const persistNetworkEntry = async () => {
                 const response = await request.response();
                 const entry = createNetworkEntryFromRequest(request, response?.status());
@@ -1851,12 +1938,12 @@ async function devtoolsListen(options, command) {
                 scheduleFlush();
             };
             persistNetworkEntry().catch((error) => {
-                console.warn('Failed to serialize network request:', error);
+                console.warn("Failed to serialize network request:", error);
             });
         });
-        p.on('requestfailed', (request) => {
+        p.on("requestfailed", (request) => {
             const failure = request.failure();
-            const entry = createNetworkEntryFromRequest(request, undefined, failure?.errorText ?? 'failed');
+            const entry = createNetworkEntryFromRequest(request, undefined, failure?.errorText ?? "failed");
             devtoolsState.network.push(entry);
             trimBuffer(devtoolsState.network, DEVTOOLS_NETWORK_LIMIT);
             scheduleFlush();
@@ -1864,11 +1951,11 @@ async function devtoolsListen(options, command) {
     };
     attachListeners(page);
     const context = page.context();
-    context.on('page', (newPage) => {
+    context.on("page", (newPage) => {
         attachListeners(newPage);
     });
     if (!background) {
-        console.log('Listening for console and network events… Press Ctrl+C to stop.');
+        console.log("Listening for console and network events… Press Ctrl+C to stop.");
     }
     const shutdown = async () => {
         try {
@@ -1876,7 +1963,7 @@ async function devtoolsListen(options, command) {
         }
         catch (error) {
             if (sweetLinkDebug) {
-                console.warn('Failed to flush DevTools state during shutdown.', error);
+                console.warn("Failed to flush DevTools state during shutdown.", error);
             }
         }
         try {
@@ -1884,22 +1971,22 @@ async function devtoolsListen(options, command) {
         }
         catch (error) {
             if (sweetLinkDebug) {
-                console.warn('Failed to close DevTools browser during shutdown.', error);
+                console.warn("Failed to close DevTools browser during shutdown.", error);
             }
         }
         process.exit(0);
     };
-    process.once('SIGINT', () => {
+    process.once("SIGINT", () => {
         shutdown().catch((error) => {
             if (sweetLinkDebug) {
-                console.warn('Graceful shutdown after SIGINT failed:', error);
+                console.warn("Graceful shutdown after SIGINT failed:", error);
             }
         });
     });
-    process.once('SIGTERM', () => {
+    process.once("SIGTERM", () => {
         shutdown().catch((error) => {
             if (sweetLinkDebug) {
-                console.warn('Graceful shutdown after SIGTERM failed:', error);
+                console.warn("Graceful shutdown after SIGTERM failed:", error);
             }
         });
     });