@reticlehq/server 3.7.0 → 3.8.1

package/dist/command/cli.js

@@ -8,34 +8,32 @@ import { openFailureNote, openLaunchFailureNote } from './cli/answers/open-note.
 import { realpathSync } from 'node:fs';
 import { join } from 'node:path';
 import { installCrashGuard } from './setup/setup-command.js';
-import { readDevServers } from './daemon/dev-servers.js';
-import { hasAnyAppConnectedBefore, hasProjectConnectedBefore, } from '../memory/recall/prior/connection-memory.js';
-import { attachStatusFields } from '../surface/mcp/attach-memory.js';
-import { splitBrainFields, withNextAction } from './cli/status-fields.js';
+import { handleStatus } from './cli/status-fields.js';
+export { handleStatus, reportStatus } from './cli/status-fields.js';
 import { reticleStateHome } from './daemon/daemon.js';
 import { handleMcp } from './cli/mcp-command.js';
 import { handleReport } from './cli/report-command.js';
 import { handleContext } from './cli/context-command.js';
+import { handleHook } from './cli/hook/hook-command.js';
+import { HOOK_COMMAND } from './cli/cli-parse.js';
 import { daemonProjectAt, readDaemonRegistry, resolveDaemonForProject, } from './daemon/daemon-resolve.js';
 import { pickDaemonPortToBind } from './daemon/binding/free-port.js';
 import { isSameOrAbove, portForInit, portFromEnv } from './setup/init/init-port.js';
 import { daemonStartOptions } from './cli/daemon-start-options.js';
 import { handleGate, loadNamedFlows, resolveChangedFiles } from './cli/cli-flow-commands.js';
-import { RETICLE_DEFAULT_PORT, ReticleDir, ReticleEnv, devServersForProject, } from '@reticlehq/core';
+import { RETICLE_DEFAULT_PORT, ReticleDir, ReticleEnv } from '@reticlehq/core';
 import { loadDotEnv } from '../telemetry/dev-repo.js';
 import { licenseKeyFromEnvFiles } from '../features/license/license-env.js';
 import { LICENSE_KEY_ENV } from '../features/license/license.js';
 import { createNodeFileSystem } from '../memory/project/fs/fs-port.js';
-import { localLinkOf, workspaceAppLinks } from './cli/status/workspace-links.js';
 import { affectedSavedFlows } from '../language/flows/change/flow-sources.js';
-import { availableUpdate } from './update/update-nudge.js';
 import { handleUpdate, handleRollback } from './cli/cli-update-commands.js';
 import { headlessByDefault } from './cli/daemon-start-options.js';
 import { startDaemon } from '../index.js';
-import { accountStatusFields, cmdLink, connectInstalls, isCloudCommand, runCloudCommand, } from './cli/cloud-cli.js';
+import { cmdLink, connectInstalls, isCloudCommand, runCloudCommand } from './cli/cloud-cli.js';
 import { SERVER_VERSION } from './version/identity/server-version.js';
 import { log } from '../log.js';
-import { readPid, isAlive, removePid, spawnDaemon, discoverDaemonPort, writeDaemonRegistry, } from './daemon/daemon.js';
+import { isAlive, removePid, spawnDaemon, discoverDaemonPort, writeDaemonRegistry, } from './daemon/daemon.js';
 import { PortPresence, probePresence, presenceIsUsable, describePresence, } from './daemon/binding/port-presence.js';
 import { waitForDaemon, probeDaemon } from '../surface/mcp/mcp-proxy.js';
 import { installDaemonResilience, recordExitReason, DaemonExitReason, } from './daemon/daemon-resilience.js';
@@ -44,6 +42,7 @@ import { DaemonHeartbeat, resolveHeartbeatMs } from './daemon/lifetime/heartbeat
 import { everServedToolCall } from './daemon/lifetime/daemon-usefulness.js';
 import { DAEMON_START_FAILED_EVENT } from './daemon/lifetime/startup-failure.js';
 import { summarizeStatus, warnOnDaemonSkew, decideOpen, openInBrowser, openCommand, } from './cli/launch/cli-launch.js';
+import { NAVIGATE_NO_SESSION_ID, navigateLeftTab, openCandidates } from './cli/open-navigate.js';
 import { fetchStatus } from './daemon/binding/daemon-status-probe.js';
 import { handleDrive } from './cli/drive/drive-command.js';
 import { handleVerify } from './cli/cli-verify.js';
@@ -79,10 +78,12 @@ export const MSG_CONNECTED_DEPS_PENDING = '⚠ Connected, but the dependency ins
  * else. `initUnfinished` is why init's setup did not finish, or undefined when it did.
  */
 export function connectExit(cloudCode, initUnfinished) {
-    if (0 !== cloudCode)
+    if (0 !== cloudCode) {
         return { code: cloudCode };
-    if (initUnfinished === undefined)
+    }
+    if (initUnfinished === undefined) {
         return { code: 0 };
+    }
     if (InitFailure.DEPENDENCY_INSTALL === initUnfinished) {
         return { code: 0, note: MSG_CONNECTED_DEPS_PENDING };
     }
@@ -98,8 +99,9 @@ async function handleInit(parsed) {
         // projects its connected pages announced.
         daemonProjects: async (p) => {
             const claimed = daemonProjectAt(p, reticleStateHome());
-            if (claimed !== undefined && claimed.length > 0)
+            if (claimed !== undefined && claimed.length > 0) {
                 return [claimed];
+            }
             const { sessions } = summarizeStatus(await fetchStatus(p));
             return [
                 ...new Set(sessions.flatMap((s) => (s.projectId === undefined ? [] : [s.projectId]))),
@@ -125,6 +127,8 @@ async function handleInit(parsed) {
         ...(parsed.url === undefined ? {} : { url: parsed.url }),
         captureBodies: true === parsed.captureBodies,
         hooks: true === parsed.hooks,
+        newId: true === parsed.newId,
+        promptCapture: false !== parsed.promptCapture,
         // The outcome is reported by confirmInstall instead, once it knows whether an app connected —
         // `init` writing files was never the same thing as `init` working (#269).
         deferOutcome: true,
@@ -136,138 +140,6 @@ async function handleInit(parsed) {
 // `serve`, `stop` and `restart` live in `cli/lifecycle/daemon-lifecycle.ts`: one idea, and the
 // largest group this file could give up without splitting something that belongs together.
 import { handleServe, handleStop, handleRestart } from './cli/lifecycle/daemon-lifecycle.js';
-import { statusLines } from './cli/status/status-lines.js';
-/**
- * Report status to the terminal. `--json` writes one structured line to STDOUT so it can be piped
- * into `jq`; the human-readable block goes to stdout too. `log()` stays on stderr (the MCP
- * transport lives on stdout), so `--json` must not go through it.
- */
-export function reportStatus(fields, json) {
-    if (json) {
-        const line = JSON.stringify({
-            t: new Date().toISOString(),
-            event: 'reticle_status',
-            ...fields,
-        });
-        process.stdout.write(`${line}\n`);
-        return;
-    }
-    process.stdout.write(`${statusLines(fields).join('\n')}\n`);
-}
-export async function handleStatus(port, json = false) {
-    // A broken session file must not cost the reader the rest of the status.
-    const account = await accountStatusFields().catch(() => ({}));
-    // At a workspace root that is no app of its own, each app and its link: "not linked" named none.
-    const linked = account.linkedProject;
-    if ('string' !== typeof linked && readProjectId(process.cwd()) === undefined)
-        Object.assign(account, {
-            workspaceApps: await workspaceAppLinks(process.cwd(), localLinkOf).catch(() => []),
-        });
-    const report = (fields) => reportStatus({ ...fields, ...account }, json);
-    const pid = readPid(port);
-    // Durable, so it survives the daemon idling out — which is the state `status` is most often run in.
-    const projectId = readProjectId(process.cwd());
-    const previouslyConnected = hasAnyAppConnectedBefore(reticleStateHome(), port, projectId);
-    // The narrow twin. Every sentence that says "this project", and the decision about whether THIS
-    // app is instrumented, needs the question the wide one cannot answer without a project id.
-    const projectPreviouslyConnected = hasProjectConnectedBefore(reticleStateHome(), port, projectId);
-    // Whether `init` has run HERE. Registering the MCP server does not wire the app, and more than one
-    // path does the first without the second — so this is the commonest reason `status` has nothing to
-    // report, and it was not among the facts this command could state.
-    const initialized = projectId !== undefined;
-    // The OTHER half of the install, and the half this command could not see. A host that registers
-    // Reticle and never lists its tools looks exactly like an abandoned install from here — same idle
-    // daemon, same zero sessions — and the user sees a tool that does nothing. See attach-memory.ts.
-    const client = attachStatusFields(reticleStateHome(), port);
-    // What the dev servers themselves said. The reason this command could previously only guess at
-    // whether the app was running is that it had no way to see one; now the ones carrying Reticle
-    // announce, and the advice below stops contradicting the terminal the reader is looking at.
-    // Scoped to THIS project: the registry is machine-wide, and an unrelated app's dev server must
-    // not make this project look like it is running.
-    const devServerPorts = devServersForProject(readDevServers(reticleStateHome()), {
-        projectId,
-        root: process.cwd(),
-    }).map((d) => d.port);
-    // The failure where every individual check is green and the chain is broken: the agent's proxy and
-    // the app resolved their ports independently and landed on two different daemons. Reported from
-    // BOTH stances, because neither one can see it alone.
-    const split = splitBrainFields(port, projectId);
-    // Doctor and status must answer the same liveness question. A live pid only says that some
-    // process exists; a Reticle daemon is running only when the shared port probe reaches /status.
-    const presence = await probePresence(port, { tcpOpen: probeDaemon, status: fetchStatus });
-    if (!presenceIsUsable(presence)) {
-        report({
-            port,
-            running: false,
-            presence,
-            ...(presence === PortPresence.FOREIGN ? { reason: describePresence(presence, port) } : {}),
-            // `init` promises this command says why the app has not connected. Without it the answer was
-            // `running: false` and nothing else, which reads as "Reticle is broken" for what is usually
-            // just a daemon that has not been asked to do anything yet.
-            ...withNextAction({
-                running: false,
-                sessionCount: 0,
-                previouslyConnected,
-                projectPreviouslyConnected,
-                initialized,
-                devServerPorts,
-            }),
-            ...client,
-            ...split,
-        });
-        return;
-    }
-    // The daemon answered the same probe doctor trusts — ask it for live sessions + health.
-    const payload = await fetchStatus(port);
-    // `status` is the second-most-run command and the one a HUMAN types. The update nudge otherwise
-    // only rides a tool result, which the majority of daemons never produce — so the people most in
-    // need of an upgrade were the ones with no path to hearing about it.
-    const update = availableUpdate();
-    const nudge = update === undefined ? {} : { updateAvailable: update };
-    if (payload === undefined) {
-        report({
-            port,
-            running: true,
-            pid,
-            ...nudge,
-            ...withNextAction({
-                running: true,
-                sessionCount: 0,
-                previouslyConnected,
-                projectPreviouslyConnected,
-                initialized,
-                devServerPorts,
-            }),
-            ...client,
-            ...split,
-        });
-        return;
-    }
-    const summary = summarizeStatus(payload);
-    // Only when the daemon did NOT already explain itself. It has the whole diagnosis in-process and
-    // puts it on the wire as `why`; printing a second, thinner opinion beside it risks two confident
-    // answers pointing different ways, which is worse than one.
-    const next = summary.why === undefined
-        ? withNextAction({
-            running: true,
-            ...summary,
-            previouslyConnected,
-            projectPreviouslyConnected,
-            initialized,
-            devServerPorts,
-        })
-        : {};
-    report({
-        port,
-        running: true,
-        pid,
-        ...summary,
-        ...next,
-        ...client,
-        ...split,
-        ...nudge,
-    });
-}
 /**
  * Print the running package version (resolved once in server-version.ts), and nothing else.
  *
@@ -313,18 +185,21 @@ function ensureDaemon(port) {
         // upgrade does NOT take effect until that daemon dies, and nothing used to say so. Say it here,
         // where both versions are in hand, and keep attaching: killing another agent's daemon on a
         // version bump is worse than a loud warning.
-        if (presenceIsUsable(presence))
+        if (presenceIsUsable(presence)) {
             return warnOnDaemonSkew(port);
+        }
         // Not free, not a daemon: a stranger holds the port. Spawning here is guaranteed to fail —
         // the child cannot bind — and `waitForDaemon` would then report READY anyway, because its
         // probe is the same bare TCP connect and the stranger accepts. That is the "serve reports
         // success for a daemon that never bound" shape. Refuse instead, with the sentence `doctor`
         // says.
-        if (PortPresence.FREE !== presence)
+        if (PortPresence.FREE !== presence) {
             throw new Error(describePresence(presence, port));
+        }
         const scriptPath = process.argv[1];
-        if (scriptPath === undefined)
+        if (scriptPath === undefined) {
             throw new Error('cannot locate the reticle daemon script');
+        }
         spawnDaemon(process.execPath, scriptPath, [DAEMON_INNER_COMMAND, PORT_FLAG, String(port)], port);
         return waitForDaemon(port);
     });
@@ -348,12 +223,15 @@ async function waitForNewSession(port, before) {
     while (Date.now() < deadline) {
         await new Promise((resolve) => setTimeout(resolve, 400));
         const { sessions } = summarizeStatus(await fetchStatus(port));
-        if (sessions.length > before)
+        if (sessions.length > before) {
             return true;
+        }
     }
     return false;
 }
-function handleOpen(requestedPort, url) {
+/** What to do about a same-origin tab `open` left where it was. */
+const OPEN_LEFT_AS_IS_REMEDY = 'Pass --navigate to move it, drive it with reticle_navigate, or open the url in the browser yourself.';
+function handleOpen(requestedPort, url, navigate = false) {
     // Our project's daemon first: `discoverDaemonPort` returns the LOWEST live daemon on the machine,
     // whoever it belongs to, so on a machine running two projects `reticle open` could drive the other
     // one's browser. It stays as the last resort for a caller with no project id, where any daemon is
@@ -368,7 +246,10 @@ function handleOpen(requestedPort, url) {
         .then(async (port) => {
         await ensureDaemon(port);
         const { sessions } = summarizeStatus(await fetchStatus(port));
-        const decision = decideOpen(sessions, url);
+        // `--navigate` MOVES a tab, so it may only pick one of ours: on a daemon serving two projects,
+        // the origin match alone could hand it the other project's tab. Reuse and the note are read-only.
+        const candidates = openCandidates(sessions, navigate, myProject);
+        const decision = decideOpen(candidates, url);
         if ('need-url' === decision.action) {
             log('reticle_open', {
                 port,
@@ -384,15 +265,33 @@ function handleOpen(requestedPort, url) {
         // A tab on the right origin, on the WRONG page. Kept (that is what stops a tab piling up per
         // run) but never reported as done: `reusing` here read as "your url is open" for a page nobody
         // had opened.
+        if ('left-as-is' === decision.action && navigate && decision.sessionId !== undefined) {
+            const moved = await navigateLeftTab({
+                port,
+                sessionId: decision.sessionId,
+                url: decision.requested,
+            });
+            log('reticle_open', { port, ...moved });
+            // A loop or CI step reads the exit code, so a failed move must not exit 0.
+            if (moved['error'] !== undefined) {
+                process.exit(1);
+            }
+            return;
+        }
         if ('left-as-is' === decision.action) {
+            // `--navigate` was asked for and could not be honoured: the tab never reported a session id
+            // to move. Suggesting `--navigate` back to someone who just passed it reads as being ignored.
+            const remedy = navigate ? NAVIGATE_NO_SESSION_ID : OPEN_LEFT_AS_IS_REMEDY;
             log('reticle_open', {
                 port,
                 reusing: decision.url,
                 requested: decision.requested,
                 note: `a tab is connected on this origin but sitting on ${decision.url} — it was LEFT THERE, ` +
-                    `not navigated to ${decision.requested}. Drive it with reticle_navigate, or open the url ` +
-                    'in the browser yourself.',
+                    `not navigated to ${decision.requested}. ${remedy}`,
             });
+            if (navigate) {
+                process.exit(1);
+            }
             return;
         }
         const launchError = await openInBrowser(decision.url);
@@ -500,6 +399,8 @@ function handleDaemonInner(parsed) {
         // argument, which would otherwise arrive as the reason.
         process.on('SIGTERM', () => shutdown(DaemonExitReason.SIGNAL));
         process.on('SIGINT', () => shutdown(DaemonExitReason.SIGNAL));
+        // `reticle stop` asks here first: on Windows a signal ends the process with no shutdown path.
+        server.onShutdownRequest?.(() => shutdown(DaemonExitReason.SIGNAL));
         // Self-shut-down when idle so a detached daemon (and any headless Chromium it launched) never
         // lingers on the user's machine after the editor closes. Reuses the same clean shutdown path.
         const attachedGraceEnv = process.env[ReticleEnv.IDLE_ATTACHED];
@@ -553,9 +454,22 @@ export function main() {
     // run then reported the licence as `missing`, which is indistinguishable from having none at all.
     // Only the key is taken; see license-env.ts for why nothing else is.
     const licenseKey = licenseKeyFromEnvFiles(process.cwd());
-    if (licenseKey !== undefined)
+    if (licenseKey !== undefined) {
         process.env[LICENSE_KEY_ENV] = licenseKey;
+    }
     const argv = process.argv.slice(2);
+    // The agent's prompt hook, FIRST: before the version re-exec (it must not start a second CLI on
+    // every prompt) and before telemetry, which must never see that a prompt existed, let alone it.
+    // `--help` falls through to the parser, which prints what `hook` does.
+    if (HOOK_COMMAND === argv[0] && !argv.some((arg) => '--help' === arg || '-h' === arg)) {
+        // `tool` too: a hook that fails must never be reported to the agent as its tool failing.
+        const agentHook = ['prompt', 'prompt-write', 'tool', 'tool-write'].includes(argv[1] ?? '');
+        void handleHook(argv.slice(1))
+            .then((code) => process.exit(code))
+            // A hook that fails must still let the prompt through, so `prompt` exits 0 whatever happens.
+            .catch(() => process.exit(agentHook ? 0 : 1));
+        return;
+    }
     // Before anything reports or writes: a CLI a major away from the project's SDK makes every verdict
     // `version_skew`, and the unpinned `npx @reticlehq/server` every agent entry uses resolves the
     // LATEST major whatever the project installed. Hand the same arguments to the matching release and
@@ -639,8 +553,9 @@ export function main() {
                     }
                 }
                 const exit = connectExit(await runCloudCommand(argv), unfinished);
-                if (exit.note !== undefined)
+                if (exit.note !== undefined) {
                     process.stderr.write(`${exit.note}\n`);
+                }
                 return exit.code;
             })()
                 .then((code) => process.exit(code))
@@ -665,8 +580,9 @@ export function main() {
     const portConflict = projectPort === undefined && envPort === undefined && !argv.includes(PORT_FLAG)
         ? workspacePortConflict(process.cwd())
         : undefined;
-    if (portConflict !== undefined)
+    if (portConflict !== undefined) {
         process.stderr.write(`${portConflict}\n`);
+    }
     // Registry BEFORE the default, and after both explicit sources.
     //
     // This is the line that ends the split brain. Build plugins have always asked the registry which
@@ -708,8 +624,9 @@ export function main() {
             break;
         case 'kill':
             void runKill(parsed.port, parsed.force).then((freed) => {
-                if (!freed)
+                if (!freed) {
                     process.exit(1);
+                }
             });
             break;
         case 'restart':
@@ -725,7 +642,7 @@ export function main() {
             handleTelemetry(parsed.action);
             break;
         case 'feedback':
-            void handleFeedback(parsed.text, parsed.rating, parsed.bug, parsed.feedbackKind, parsed.agent);
+            void handleFeedback(parsed.text, parsed.rating, parsed.bug, parsed.feedbackKind, parsed.agent, parsed.contact);
             break;
         case 'version':
             handleVersion();
@@ -751,7 +668,7 @@ export function main() {
             }, reportStepFromCli);
             break;
         case 'open':
-            handleOpen(parsed.port, parsed.url);
+            handleOpen(parsed.port, parsed.url, parsed.navigate);
             break;
         case 'drive':
             handleDrive(parsed, readProjectId(process.cwd()));
@@ -793,10 +710,12 @@ export function main() {
  */
 function isEntryPoint() {
     const argv1 = process.argv[1];
-    if (argv1 === undefined)
+    if (argv1 === undefined) {
         return false;
-    if (import.meta.url === pathToFileURL(argv1).href)
+    }
+    if (import.meta.url === pathToFileURL(argv1).href) {
         return true;
+    }
     try {
         return import.meta.url === pathToFileURL(realpathSync(argv1)).href;
     }

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

@@ -82,5 +82,10 @@ export interface ProxyResilience {
  * `onCrash` is for reporting only — it must not end the process. `onGone` is the ONE exception, and
  * it is the subject of DISCONNECT_STORM below.
  */
-export declare function installProxyResilience(proc: ProcessLike, log: LogFn, onCrash?: (kind: CrashKind, cause: unknown) => void, onGone?: () => void): ProxyResilience;
+export declare function installProxyResilience(proc: ProcessLike, log: LogFn, onCrash?: (kind: CrashKind, cause: unknown) => void, onGone?: () => void, 
+/**
+ * The pipes to the client (stdin and stdout). Only THEIR errors count toward DISCONNECT_STORM.
+ * Empty by default, so a test that wires a fake process never touches the real stdio.
+ */
+clientPipes?: readonly ProcessLike[]): ProxyResilience;
 export {};

package/dist/command/daemon/daemon-resilience.js

@@ -284,34 +284,47 @@ export function installDaemonResilience(proc, log, onFatal) {
  * `onCrash` is for reporting only — it must not end the process. `onGone` is the ONE exception, and
  * it is the subject of DISCONNECT_STORM below.
  */
-export function installProxyResilience(proc, log, onCrash = reportCrash, onGone = () => process.exit(0)) {
+export function installProxyResilience(proc, log, onCrash = reportCrash, onGone = () => process.exit(0), 
+/**
+ * The pipes to the client (stdin and stdout). Only THEIR errors count toward DISCONNECT_STORM.
+ * Empty by default, so a test that wires a fake process never touches the real stdio.
+ */
+clientPipes = []) {
     const expected = {
         disconnected: 'reticle_mcp_proxy_client_disconnected',
         unreachable: 'reticle_mcp_proxy_daemon_unreachable',
     };
     // "Absorb the disconnect and keep serving" is right for ONE disconnect and catastrophic for a
     // stream of them — see DISCONNECT_STORM. Counted since the last USABLE SESSION rather than since
-    // this process started: a lifetime tally reaches the threshold on a working week, because the
-    // classifier reads `ECONNRESET` as "the peer vanished" and on this leg the peer is the DAEMON,
-    // which restarts routinely and is the thing the proxy exists to survive.
+    // this process started, and counted ONLY on the client pipes. An error that reaches the process
+    // comes from a socket with no listener, and in this process those are the sockets to the DAEMON,
+    // which restarts routinely and is the thing the proxy exists to survive. Counting them made the
+    // proxy leave a healthy daemon, and the agent lost its tools.
     let disconnects = 0;
     let gone = false;
-    const absorb = (value) => {
-        if (!absorbExpected(value, log, expected))
-            return false;
-        if (false === expectedCode(value)?.unreachable) {
-            disconnects += 1;
-            if (disconnects >= DISCONNECT_STORM && !gone) {
-                gone = true;
-                log('reticle_mcp_proxy_client_gone', {
-                    disconnects,
-                    note: 'the client end is gone for good, not between reconnects — exiting instead of retrying forever',
-                });
-                onGone();
-            }
+    const absorb = (value) => absorbExpected(value, log, expected);
+    const onClientPipeError = (err) => {
+        if (!absorb(err)) {
+            log('reticle_mcp_proxy_client_pipe_error', { error: describe(err) });
+            onCrash(CrashKind.UNCAUGHT_EXCEPTION, err);
+            return;
+        }
+        if (true === expectedCode(err)?.unreachable) {
+            return;
+        }
+        disconnects += 1;
+        if (disconnects >= DISCONNECT_STORM && !gone) {
+            gone = true;
+            log('reticle_mcp_proxy_client_gone', {
+                disconnects,
+                note: 'the client end is gone for good, not between reconnects — exiting instead of retrying forever',
+            });
+            onGone();
         }
-        return true;
     };
+    for (const pipe of clientPipes) {
+        pipe.on('error', onClientPipeError);
+    }
     const noteUsableSession = () => {
         // Not after `gone`: the process is already leaving, and a late frame must not look like a
         // reason to stay. Nothing brings the proxy back from `onGone` by design.

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,18 @@ 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`.
+     */
+    onUncleanDeath?(ageMs: number): void;
 }
 /**
  * Spawn the reticle daemon as a detached background process, redirecting output to the log file.

package/dist/command/daemon/daemon.js

@@ -2,10 +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';
@@ -196,10 +198,48 @@ 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),
     };
 }
+/**
+ * Report a dead predecessor, aged from its pidfile: the parent writes that file at spawn time.
+ * Read before the unlink, because after it nothing is left to age. A report must never stop a start.
+ */
+function reportUncleanAge(pidFilePath, deps) {
+    try {
+        // The clock is read at this I/O boundary, the same as the log timestamps in this file.
+        deps.onUncleanDeath?.(Math.max(0, Date.now() - statSync(pidFilePath).mtimeMs));
+    }
+    catch {
+        // 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
@@ -242,6 +282,9 @@ export function spawnDaemon(nodeExec, scriptPath, args, port, deps = defaultSpaw
         // a crashed daemon is reclaimed"), it just never said it out loud. Captured before the unlink,
         // because after it there is no trace left that the previous daemon died at all.
         orphanPid = uncleanPredecessor(existing, false, process.pid);
+        if (null !== orphanPid) {
+            reportUncleanAge(pidFilePath, deps);
+        }
         try {
             unlinkSync(pidFilePath);
             lockFd = deps.openFile(pidFilePath, 'wx');
@@ -289,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 {

package/dist/command/daemon/lifetime/daemon-usefulness.d.ts

@@ -27,6 +27,8 @@ export declare function everServedToolCall(): boolean;
  */
 export declare const SETUP_HOLD_MS = 60000;
 export declare function noteSetupHold(now: number): void;
+/** Call on each attach and each detach of an agent. */
+export declare function noteAgentPresence(now: number): void;
 /** Tests only. */
 export declare function resetDaemonUsefulness(): void;
 interface UsefulnessFacts {