@reticlehq/server 3.8.0 → 3.8.2

package/dist/command/cli/cli-parse.js

@@ -4,11 +4,13 @@
  * and re-exports this surface.
  */
 import { parseFeedbackArgs } from './cli-parse-feedback.js';
+import { HEADLESS_FLAG, parseServeFlags } from './cli-parse-serve.js';
 import { parseVerifySuffix } from './cli-parse-verify.js';
 import { HEADED_FLAG, PORT_FLAG, VERIFY_COMMAND, missingOperand, missingValue, notANumber, retiredFlag, unknownArgument, CLOUD_COMMANDS, REMOVED_COMMANDS, removedNote, } from './cli-parse-grammar.js';
 // Re-exported because the daemon's own argv builder reaches for these through this module, which is
 // where the grammar has always lived as far as every caller is concerned.
 export { HEADED_FLAG, PORT_FLAG };
+export { DRIVE_FLAG, HEADLESS_FLAG, HTTP_FLAG, HTTP_PORT_FLAG, HTTP_TOKEN_FLAG, } from './cli-parse-serve.js';
 import { FORCE_FLAG } from './cli-kill.js';
 // Re-exported so every existing importer of these flags is unaffected by the file split.
 export { AGENT_FLAG, BUG_FLAG, CONTACT_FLAG, FEEDBACK_KINDS, KIND_FLAG, RATING_FLAG, } from './cli-parse-feedback.js';
@@ -122,24 +124,19 @@ const COMMAND_FLAG_ALIASES = new Map([
  */
 function numberFlag(args, name) {
     const at = args.indexOf(name);
-    if (at < 0)
+    if (at < 0) {
         return 0;
+    }
     const raw = Number(args[at + 1]);
     return Number.isFinite(raw) && raw >= 0 ? Math.floor(raw) : 0;
 }
 /** The subcommand name if we recognize it, else `unknown`. Bare `reticle` reports `help`. */
 export function knownCommand(arg) {
-    if (arg === undefined || '' === arg)
+    if (arg === undefined || '' === arg) {
         return HELP_COMMAND;
+    }
     return KNOWN_COMMANDS.has(arg) ? arg : (COMMAND_FLAG_ALIASES.get(arg) ?? UNKNOWN_COMMAND);
 }
-/**
- * Force a hidden browser. The default is now HEADED: a run nobody can see is a run nobody trusts,
- * and every "did it actually do anything?" question cost a round-trip. CI passes this (or just sets
- * CI, which flips the default) because there is no display there to be headed on.
- */
-export const HEADLESS_FLAG = '--headless';
-export const DRIVE_FLAG = '--drive';
 const QUIET_FLAG = '--quiet';
 const DRY_RUN_FLAG = '--dry-run';
 const YES_FLAG = '--yes';
@@ -211,9 +208,6 @@ const LICENSE_FLAG = '--license';
 const NO_INSTALL_FLAG = '--no-install';
 /** Give this checkout a project id of its own: a copied repository keeps the original's. */
 const NEW_ID_FLAG = '--new-id';
-export const HTTP_FLAG = '--http';
-export const HTTP_PORT_FLAG = '--http-port';
-export const HTTP_TOKEN_FLAG = '--http-token';
 /**
  * A usage error names the thing that was wrong.
  *
@@ -226,98 +220,19 @@ export const HTTP_TOKEN_FLAG = '--http-token';
  * The help text is still shown — cli.ts renders it as readable text underneath. It is just not the
  * message any more.
  */
-const requiresHttp = (flag) => ({
-    kind: 'error',
-    message: `${flag} requires ${HTTP_FLAG} — it configures the verify endpoint ${HTTP_FLAG} starts`,
-});
 const unknownCommand = (command) => ({
     kind: 'error',
     message: `unknown command '${command}'`,
 });
-function parseServeFlags(args, defaultPort, defaultHeadless) {
-    let port = defaultPort;
-    let driveUrl;
-    let headless = defaultHeadless;
-    let http = false;
-    let httpPort;
-    let httpToken;
-    let i = 0;
-    while (i < args.length) {
-        const arg = args[i];
-        // `i < args.length` already guarantees this, but the index signature does not say so and the
-        // unknown-argument error needs a real string to name.
-        if (arg === undefined)
-            break;
-        if (arg === PORT_FLAG) {
-            i++;
-            const n = args[i];
-            if (n === undefined)
-                return missingValue(PORT_FLAG);
-            const parsed = parseInt(n, 10);
-            if (isNaN(parsed))
-                return notANumber(PORT_FLAG, n);
-            port = parsed;
-        }
-        else if (arg === DRIVE_FLAG) {
-            i++;
-            driveUrl = args[i];
-            if (driveUrl === undefined)
-                return missingValue(DRIVE_FLAG);
-        }
-        else if (arg === HEADED_FLAG) {
-            headless = false;
-        }
-        else if (arg === HEADLESS_FLAG) {
-            headless = true;
-        }
-        else if (arg === HTTP_FLAG) {
-            http = true;
-        }
-        else if (arg === HTTP_PORT_FLAG) {
-            i++;
-            const n = args[i];
-            if (n === undefined)
-                return missingValue(HTTP_PORT_FLAG);
-            const parsed = parseInt(n, 10);
-            if (isNaN(parsed))
-                return notANumber(HTTP_PORT_FLAG, n);
-            httpPort = parsed;
-        }
-        else if (arg === HTTP_TOKEN_FLAG) {
-            i++;
-            httpToken = args[i];
-            if (httpToken === undefined)
-                return missingValue(HTTP_TOKEN_FLAG);
-        }
-        else {
-            return unknownArgument(arg);
-        }
-        i++;
-    }
-    // Without `--http` these flags configure an endpoint nothing starts, and they were accepted and
-    // silently ignored — worse than being rejected, because the whole reason to pass them is to be
-    // honoured (#687).
-    if (!http && httpPort !== undefined)
-        return requiresHttp(HTTP_PORT_FLAG);
-    if (!http && httpToken !== undefined)
-        return requiresHttp(HTTP_TOKEN_FLAG);
-    return {
-        kind: 'ok',
-        port,
-        headless,
-        http,
-        ...(driveUrl !== undefined ? { driveUrl } : {}),
-        ...(httpPort !== undefined ? { httpPort } : {}),
-        ...(httpToken !== undefined ? { httpToken } : {}),
-    };
-}
 function parsePortFlag(args, defaultPort) {
     const idx = args.indexOf(PORT_FLAG);
-    if (-1 === idx)
+    if (-1 === idx) {
         return defaultPort;
+    }
     const n = args[idx + 1];
-    if (n === undefined)
+    if (n === undefined) {
         return defaultPort;
+    }
     const parsed = parseInt(n, 10);
     return isNaN(parsed) ? defaultPort : parsed;
 }
@@ -341,8 +256,9 @@ function parseDriveSuffix(args, port, defaultHeadless) {
             return unknownArgument(arg);
         }
     }
-    if (driveUrl === undefined)
+    if (driveUrl === undefined) {
         return missingOperand(DRIVE_COMMAND, 'a url');
+    }
     return { kind: 'ok', port, driveUrl, headless };
 }
 function parseInitFlags(args) {
@@ -372,23 +288,27 @@ function parseInitFlags(args) {
         const arg = args[i];
         // `i < args.length` already guarantees this, but the index signature does not say so and the
         // unknown-argument error needs a real string to name.
-        if (arg === undefined)
+        if (arg === undefined) {
             break;
+        }
         if (arg === PORT_FLAG) {
             i++;
             const n = args[i];
-            if (n === undefined)
+            if (n === undefined) {
                 return missingValue(PORT_FLAG);
+            }
             const parsed = parseInt(n, 10);
-            if (isNaN(parsed))
+            if (isNaN(parsed)) {
                 return notANumber(PORT_FLAG, n);
+            }
             port = parsed;
         }
         else if (arg === APP_FLAG) {
             i++;
             const value = args[i];
-            if (value === undefined)
+            if (value === undefined) {
                 return missingValue(APP_FLAG);
+            }
             app = value;
         }
         else if (arg === FLOW_FLAG || arg === NO_DRIVE_FLAG || arg === DRIVE_MODEL_FLAG) {
@@ -397,8 +317,9 @@ function parseInitFlags(args) {
         else if (arg === ENV_FLAG) {
             i++;
             const value = args[i];
-            if (value === undefined)
+            if (value === undefined) {
                 return missingValue(ENV_FLAG);
+            }
             env.push(value);
         }
         else if (arg === FILES_ONLY_FLAG) {
@@ -434,25 +355,29 @@ function parseInitFlags(args) {
         else if (arg === URL_FLAG) {
             i++;
             const value = args[i];
-            if (value === undefined)
+            if (value === undefined) {
                 return missingValue(URL_FLAG);
+            }
             url = value;
         }
         else if (arg === LICENSE_FLAG) {
             i++;
             const value = args[i];
-            if (value === undefined)
+            if (value === undefined) {
                 return missingValue(LICENSE_FLAG);
+            }
             licenseKey = value;
         }
         else if (arg === TIMEOUT_FLAG_INIT) {
             i++;
             const value = args[i];
-            if (value === undefined)
+            if (value === undefined) {
                 return missingValue(TIMEOUT_FLAG_INIT);
+            }
             const seconds = parseInt(value, 10);
-            if (isNaN(seconds))
+            if (isNaN(seconds)) {
                 return notANumber(TIMEOUT_FLAG_INIT, value);
+            }
             timeoutSeconds = seconds;
         }
         else if (arg === NO_MCP_FLAG) {
@@ -527,8 +452,9 @@ function parseTargetArgs(rest) {
             i += 1;
             continue;
         }
-        if (arg !== undefined && !arg.startsWith('-'))
+        if (arg !== undefined && !arg.startsWith('-')) {
             files.push(arg);
+        }
     }
     return since === undefined ? { files } : { files, since };
 }
@@ -538,8 +464,9 @@ function parseTargetArgs(rest) {
  * workspace itself, and a tutorial only dials one when asked to run.
  */
 export function dialsTheDaemon(parsed) {
-    if ('init' === parsed.kind)
+    if ('init' === parsed.kind) {
         return false;
+    }
     return 'port' in parsed;
 }
 /**
@@ -550,16 +477,19 @@ export function dialsTheDaemon(parsed) {
  */
 export function parseCliArgs(argv, defaultPort, defaultHeadless = false) {
     // Bare `reticle` is `serve`.
-    if (0 === argv.length)
+    if (0 === argv.length) {
         return { kind: 'serve', port: defaultPort, headless: defaultHeadless, http: false };
+    }
     const [cmd, ...rest] = argv;
     // Guaranteed by the bare-argv check above; restated so the unknown-command error can name it.
-    if (cmd === undefined)
+    if (cmd === undefined) {
         return { kind: 'error', message: CLI_USAGE };
+    }
     // `version` (or the conventional -v/--version flags) prints the running version — the diagnostic the
     // troubleshooting docs lean on to confirm which npx-resolved build is actually executing.
-    if (cmd === VERSION_COMMAND || '--version' === cmd || '-v' === cmd)
+    if (cmd === VERSION_COMMAND || '--version' === cmd || '-v' === cmd) {
         return { kind: 'version' };
+    }
     // `help` (and the conventional -h/--help) print usage to stdout and exit 0 — the universal first move
     // for a new user, which otherwise fell through to a JSON error with exit 1.
     //
@@ -573,23 +503,27 @@ export function parseCliArgs(argv, defaultPort, defaultHeadless = false) {
     // Removed commands answer before help does: `reticle hunt --help` should say it is gone, not
     // describe something that no longer runs.
     const removed = REMOVED_COMMANDS.get(cmd);
-    if (removed !== undefined)
+    if (removed !== undefined) {
         return { kind: 'removed', message: removedNote(cmd, removed) };
+    }
     if (HELP_COMMAND === cmd || HELP_FLAGS.has(cmd)) {
         // `reticle help all`, `reticle --help all`, `reticle help init`.
         const topic = rest.find((arg) => !HELP_FLAGS.has(arg));
         return topic === undefined ? { kind: 'help' } : { kind: 'help', topic };
     }
-    if (argv.some((arg) => HELP_FLAGS.has(arg)))
+    if (argv.some((arg) => HELP_FLAGS.has(arg))) {
         return { kind: 'help', topic: cmd };
+    }
     // The list is the gate, so a command cannot be routed without also being named in telemetry.
-    if (!LOCAL_COMMAND_SET.has(cmd))
+    if (!LOCAL_COMMAND_SET.has(cmd)) {
         return unknownCommand(cmd);
+    }
     switch (cmd) {
         case INIT_COMMAND: {
             const r = parseInitFlags(rest);
-            if ('error' === r.kind)
+            if ('error' === r.kind) {
                 return r;
+            }
             return {
                 kind: 'init',
                 port: r.port,
@@ -615,8 +549,9 @@ export function parseCliArgs(argv, defaultPort, defaultHeadless = false) {
         }
         case SERVE_COMMAND: {
             const r = parseServeFlags(rest, defaultPort, defaultHeadless);
-            if ('error' === r.kind)
+            if ('error' === r.kind) {
                 return r;
+            }
             return {
                 kind: 'serve',
                 port: r.port,
@@ -631,8 +566,9 @@ export function parseCliArgs(argv, defaultPort, defaultHeadless = false) {
             const port = parsePortFlag(rest, defaultPort);
             // `stop --force` is what `kill` was: free the port by its listener, which must still be a
             // Reticle daemon. Overriding that refusal stays on `restart --force` and the old `kill --force`.
-            if (rest.includes(FORCE_FLAG))
+            if (rest.includes(FORCE_FLAG)) {
                 return { kind: 'kill', port, force: false };
+            }
             const quiet = rest.includes(QUIET_FLAG);
             return { kind: 'stop', port, quiet };
         }
@@ -687,8 +623,9 @@ export function parseCliArgs(argv, defaultPort, defaultHeadless = false) {
             }
             // Only `mcp` today. A bare `reticle setup` falls to help rather than guessing, because the
             // next subcommand here will not be a synonym for this one.
-            if (what !== 'mcp')
+            if (what !== 'mcp') {
                 return { kind: 'help', topic: SETUP_COMMAND };
+            }
             return { kind: 'setup-mcp' };
         }
         case LICENSE_COMMAND:
@@ -715,14 +652,16 @@ export function parseCliArgs(argv, defaultPort, defaultHeadless = false) {
         }
         case DRIVE_COMMAND: {
             const r = parseDriveSuffix(rest, defaultPort, defaultHeadless);
-            if ('error' === r.kind)
+            if ('error' === r.kind) {
                 return r;
+            }
             return { kind: 'drive', port: r.port, driveUrl: r.driveUrl, headless: r.headless };
         }
         case DAEMON_INNER_COMMAND: {
             const r = parseServeFlags(rest, defaultPort, defaultHeadless);
-            if ('error' === r.kind)
+            if ('error' === r.kind) {
                 return r;
+            }
             return {
                 kind: '_daemon',
                 port: r.port,
@@ -735,8 +674,9 @@ export function parseCliArgs(argv, defaultPort, defaultHeadless = false) {
         }
         case VERIFY_COMMAND: {
             const r = parseVerifySuffix(rest, defaultPort);
-            if ('error' === r.kind)
+            if ('error' === r.kind) {
                 return r;
+            }
             return {
                 kind: 'verify',
                 url: r.url,
@@ -797,8 +737,9 @@ export function parseCliArgs(argv, defaultPort, defaultHeadless = false) {
             return { kind: 'rollback' };
         case MCP_COMMAND: {
             const r = parseServeFlags(rest, defaultPort, defaultHeadless);
-            if ('error' === r.kind)
+            if ('error' === r.kind) {
                 return r;
+            }
             return {
                 kind: 'mcp',
                 port: r.port,

package/dist/command/cli/cli-usage.js

@@ -56,6 +56,9 @@ const VERIFY_DETAIL = `Drives the URL and verifies the saved flows. Exit 0 means
                                 https://docs.reticle.sh/http-transport.md`;
 const BROWSER_NOTE = `The browser Reticle opens for your agent is shown so you can watch the run. --headless hides
 it; CI, RETICLE_HEADLESS=1, or a Linux machine with no display hides it too.`;
+/** What `--http` starts. MCP is already on the bridge port; this flag is the verify endpoint. */
+const HTTP_HELP = '--http starts the verify endpoint. MCP is already served on the bridge port.';
+const DAEMON_DETAIL = `${BROWSER_NOTE}\n\n${HTTP_HELP}`;
 const COMMANDS = [
     {
         name: 'init',
@@ -225,14 +228,14 @@ const COMMANDS = [
         synopsis: 'mcp [--port N] [--drive <url>] [--headless] [--headed] [--http] [--http-port N] [--http-token T]',
         summary: 'The MCP stdio server your agent runs; starts the daemon if needed',
         group: HelpGroup.MORE,
-        detail: BROWSER_NOTE,
+        detail: DAEMON_DETAIL,
     },
     {
         name: 'serve',
         synopsis: 'serve [--port N] [--drive <url>] [--headless] [--headed] [--http] [--http-port N] [--http-token T]',
         summary: 'Start the daemon in the background; returns once it answers',
         group: HelpGroup.MORE,
-        detail: BROWSER_NOTE,
+        detail: DAEMON_DETAIL,
     },
     {
         name: 'drive',

package/dist/command/cli/cloud-link.d.ts

@@ -10,28 +10,9 @@ export declare const validateKey: (url: string, key: string) => Promise<z.infer<
 declare const WhoamiSchema: z.ZodObject<{
     projectId: z.ZodString;
     projectName: z.ZodString;
-    /**
-     * Which tenant the key belongs to. Optional for the same reason `dashboardUrl` is — an older
-     * cloud does not send it — and when it is missing a stored key cannot be proved to be ours, which
-     * is why the reuse path below mints instead of guessing.
-     */
     orgId: z.ZodOptional<z.ZodString>;
-    /**
-     * Where this project's dashboard lives. Optional because an older cloud does not send it, and a
-     * CLI that refused to link against one would break the thing it is supposed to connect.
-     */
     dashboardUrl: z.ZodOptional<z.ZodString>;
-}, "strip", z.ZodTypeAny, {
-    projectId: string;
-    projectName: string;
-    orgId?: string | undefined;
-    dashboardUrl?: string | undefined;
-}, {
-    projectId: string;
-    projectName: string;
-    orgId?: string | undefined;
-    dashboardUrl?: string | undefined;
-}>;
+}, z.core.$strip>;
 export interface PlatformLinked {
     via: PlatformLinkVia;
     /** The project this folder was bound to before, if any: a re-run against it is not a new link. */

package/dist/command/cli/doctor/doctor-agent-link.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The agent link row of `reticle doctor`, as one pure decision (reticlehq/reticle#1710).
+ *
+ * The row used to be built inline from the attach record alone: once a client had attached,
+ * enumerated and called, it stayed green forever, and a client that had started but never listed
+ * was told to restart the client. Both answers are wrong when the port is held but `/status`
+ * does not answer: the record cannot say whether the link works now, and the daemon row above
+ * already names the one fix for the held port. So in that state this row only points back at
+ * the daemon row. It never prints a second command, and it never says "the daemon", because
+ * this state also covers a port held by a different program.
+ *
+ * The record and action strings below are copied verbatim from the inline row this replaces;
+ * this module changes their priority, not their words.
+ */
+export interface AgentLinkInput {
+    /** The split-brain sentence, when this project is served by another daemon. */
+    split: string | undefined;
+    /** The attach-record action, or undefined when the record says the link worked. */
+    attachAction: string | undefined;
+    /** True when the port is held but `/status` does not answer. */
+    foreign: boolean;
+}
+export declare function agentLinkText(input: AgentLinkInput): string;

package/dist/command/cli/doctor/doctor-agent-link.js

@@ -0,0 +1,28 @@
+/**
+ * The agent link row of `reticle doctor`, as one pure decision (reticlehq/reticle#1710).
+ *
+ * The row used to be built inline from the attach record alone: once a client had attached,
+ * enumerated and called, it stayed green forever, and a client that had started but never listed
+ * was told to restart the client. Both answers are wrong when the port is held but `/status`
+ * does not answer: the record cannot say whether the link works now, and the daemon row above
+ * already names the one fix for the held port. So in that state this row only points back at
+ * the daemon row. It never prints a second command, and it never says "the daemon", because
+ * this state also covers a port held by a different program.
+ *
+ * The record and action strings below are copied verbatim from the inline row this replaces;
+ * this module changes their priority, not their words.
+ */
+/** The healthy-record sentence, word for word as doctor printed it before. */
+const RECORD_HEALTHY = '✓ an MCP client attached here and called tools before (a record, not a live check)';
+export function agentLinkText(input) {
+    if (input.split !== undefined) {
+        return `✗ ${input.split}`;
+    }
+    if (input.foreign) {
+        return '✗ the agent link is not checked live here — follow the daemon row above.';
+    }
+    if (input.attachAction === undefined) {
+        return RECORD_HEALTHY;
+    }
+    return `✗ ${input.attachAction}`;
+}

package/dist/command/cli/ports/port-holder.js

@@ -27,7 +27,12 @@ const LOOKUP_TIMEOUT_MS = 2_000;
  */
 export function captureLookup(command, args, timeoutMs = LOOKUP_TIMEOUT_MS) {
     try {
-        const result = spawnSync(command, [...args], { encoding: 'utf8', timeout: timeoutMs });
+        // The daemon has no console: without windowsHide, each lookup opens a visible window on Windows.
+        const result = spawnSync(command, [...args], {
+            encoding: 'utf8',
+            timeout: timeoutMs,
+            windowsHide: true,
+        });
         return 0 === result.status && 'string' === typeof result.stdout ? result.stdout : null;
     }
     catch {

package/dist/command/cli/project-name.d.ts

@@ -34,13 +34,7 @@ localProjectId?: string) => string;
 export declare const CreatedProjectSchema: z.ZodObject<{
     projectId: z.ZodString;
     name: z.ZodString;
-}, "strip", z.ZodTypeAny, {
-    name: string;
-    projectId: string;
-}, {
-    name: string;
-    projectId: string;
-}>;
+}, z.core.$strip>;
 /** ` in workspace "<name>"`, or nothing when no name is known. */
 export declare const inWorkspace: (name: string | undefined) => string;
 /**

package/dist/command/cli/project-name.js

@@ -83,6 +83,7 @@ export function repoIdentity(dir) {
             cwd: dir,
             encoding: 'utf8',
             stdio: ['ignore', 'pipe', 'ignore'],
+            windowsHide: true,
         }).trim();
         const remote = git('config', '--get', 'remote.origin.url')
             .replace(/\.git$/, '')

package/dist/command/daemon/daemon.d.ts

@@ -1,3 +1,4 @@
+import { type EscapeRequest, type EscapeResult } from './win32-escape.js';
 export { MAX_DAEMON_LOG_BYTES, recoverOversizedLog } from './lifetime/log-cap.js';
 /** Env override for the whole state directory — see ReticleEnv.STATE_DIR. */
 export declare const STATE_DIR_ENV: "RETICLE_STATE_DIR";
@@ -72,8 +73,13 @@ export interface SpawnDaemonDeps {
     spawnChild(command: string, args: readonly string[], options: {
         detached: boolean;
         stdio: readonly ('ignore' | number)[];
+        env?: Record<string, string | undefined>;
     }): SpawnedChild;
     pidAlive(pid: number): boolean;
+    /** `process.platform`. Optional so a test that does not care runs the detached start. */
+    readonly platform?: string;
+    /** Windows only: start the daemon outside the Job Object of this process. See win32-escape.ts. */
+    readonly escapeJob?: (request: EscapeRequest) => EscapeResult;
     /**
      * A predecessor died without a clean stop; `ageMs` is how long it had run. Optional so a test that
      * does not care reports nothing. The default sends `daemon_died_unclean`.

package/dist/command/daemon/daemon.js

@@ -2,11 +2,12 @@ import { join } from 'node:path';
 import { homedir } from 'node:os';
 import { mkdirSync, readFileSync, writeFileSync, existsSync, unlinkSync, openSync, closeSync, readdirSync, statSync, renameSync, writeSync, } from 'node:fs';
 import { spawn } from 'node:child_process';
-import { daemonRegistryFileName, ReticleEnv } from '@reticlehq/core';
+import { daemonRegistryFileName, DaemonSpawnMethod, ReticleEnv, } from '@reticlehq/core';
 import { log } from '../../log.js';
 import { uncleanPredecessor } from './lifetime/unclean-predecessor.js';
 import { reportDaemonDiedUnclean } from '../../telemetry/proxy-telemetry.js';
 import { MAX_DAEMON_LOG_BYTES, pruneOldDaemonLogs } from './lifetime/log-cap.js';
+import { escapeJobViaWmi } from './win32-escape.js';
 // Re-exported from their owner so callers outside this directory — the proxy log, the rotation
 // tests — keep reaching `daemon` rather than `lifetime`, which is a sink. See lifetime/log-cap.ts.
 export { MAX_DAEMON_LOG_BYTES, recoverOversizedLog } from './lifetime/log-cap.js';
@@ -197,8 +198,14 @@ function defaultSpawnDaemonDeps() {
         closeFile: closeSync,
         fileSize: (path) => (existsSync(path) ? statSync(path).size : 0),
         renameFile: renameSync,
-        spawnChild: (command, args, options) => spawn(command, [...args], { detached: options.detached, stdio: [...options.stdio] }),
+        spawnChild: (command, args, options) => spawn(command, [...args], {
+            detached: options.detached,
+            stdio: [...options.stdio],
+            ...(options.env === undefined ? {} : { env: options.env }),
+        }),
         pidAlive: isAlive,
+        platform: process.platform,
+        escapeJob: escapeJobViaWmi,
         onUncleanDeath: (ageMs) => void reportDaemonDiedUnclean(ageMs),
     };
 }
@@ -215,6 +222,24 @@ function reportUncleanAge(pidFilePath, deps) {
         // An unreadable pidfile has no age to report.
     }
 }
+const WINDOWS = 'win32';
+/** The WMI start must never stop a daemon start: a throw reads as "nothing launched". */
+function tryEscapeJob(escape, request) {
+    try {
+        return escape(request);
+    }
+    catch {
+        return { launched: false };
+    }
+}
+function removeQuietly(path) {
+    try {
+        unlinkSync(path);
+    }
+    catch {
+        // racing another reclaimer — fine
+    }
+}
 /**
  * Spawn the reticle daemon as a detached background process, redirecting output to the log file.
  * Writes the PID file from the parent before returning so callers can call isRunning
@@ -307,11 +332,36 @@ export function spawnDaemon(nodeExec, scriptPath, args, port, deps = defaultSpaw
             // A log we cannot write is not a reason to refuse to start the daemon.
         }
     }
+    let method = DaemonSpawnMethod.DETACHED;
+    if (WINDOWS === deps.platform && deps.escapeJob !== undefined) {
+        const escaped = tryEscapeJob(deps.escapeJob, {
+            command: nodeExec,
+            args: [scriptPath, ...args],
+            cwd: process.cwd(),
+            env: { ...process.env, [ReticleEnv.SPAWN_METHOD]: DaemonSpawnMethod.WMI },
+            logPath: logFilePath,
+            specPath: join(deps.home, `daemon-${port}.spawn.json`),
+        });
+        if (escaped.launched) {
+            deps.closeFile(logFd);
+            // No pid in time: release the lock, so the pidfile never names a process that is not ours.
+            if (escaped.pid === undefined) {
+                deps.closeFile(lockFd);
+                removeQuietly(pidFilePath);
+                return true;
+            }
+            writeFileSync(lockFd, String(escaped.pid), 'utf8');
+            deps.closeFile(lockFd);
+            return true;
+        }
+        method = DaemonSpawnMethod.WMI_FALLBACK;
+    }
     let child;
     try {
         child = deps.spawnChild(nodeExec, [scriptPath, ...args], {
             detached: true,
             stdio: ['ignore', logFd, logFd],
+            env: { ...process.env, [ReticleEnv.SPAWN_METHOD]: method },
         });
     }
     catch {