@reticlehq/server 3.7.0 → 3.8.1

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

@@ -10,19 +10,22 @@
 import { log } from '../../log.js';
 import { isAlive, spawnDaemon, reticleStateHome } from '../daemon/daemon.js';
 import { PortPresence, probePresence, presenceIsUsable, describePresence, } from '../daemon/binding/port-presence.js';
-import { waitForDaemon, startMcpProxy, probeDaemon, proxyLog, setProxyLogPort, } from '../../surface/mcp/mcp-proxy.js';
+import { waitForDaemon, startMcpProxy, probeDaemon, proxyLog, setProxyLogPort, flushProxyExit, reportWakeRefused, } from '../../surface/mcp/mcp-proxy.js';
 import { installProxyResilience } from '../daemon/daemon-resilience.js';
 import { readProjectId, readProjectPort } from './ports/resolve/cli-port.js';
 import { resolveMcpPort, daemonProjectAt, relocationReason, } from '../daemon/daemon-resolve.js';
 import { daemonSpawnArgs } from './daemon-start-options.js';
 import { WakeAction, decideWake } from '../daemon/wake-decision.js';
+import { runKill } from './cli-kill.js';
 import { pickDaemonPortToBind } from '../daemon/binding/free-port.js';
-import { fetchStatus } from '../daemon/binding/daemon-status-probe.js';
+import { fetchStatus, summarizeStatus } from '../daemon/binding/daemon-status-probe.js';
+import { isNewerVersion } from '../update/update-nudge.js';
 import { migrateApprovals } from '../setup/approval-migration.js';
-import { ReticleEnv } from '@reticlehq/core';
+import { ProxyExitReason, ReticleEnv, WakeRefusalPresence } from '@reticlehq/core';
 import { agentIo } from '../setup/agent-io.js';
 import { SERVER_VERSION } from '../version/identity/server-version.js';
 import { homedir } from 'node:os';
+import { platformKey } from '../setup/agent-configs.js';
 /**
  * Whether the daemon this proxy starts hides its browser. A daemon on a port nobody chose — the
  * requested one served another project, so this one was moved — was opening a visible browser the
@@ -31,6 +34,41 @@ import { homedir } from 'node:os';
 export function spawnsHeadless(headless, requested, resolved) {
     return headless || requested !== resolved;
 }
+const RELEASE_VERSION = /^\d+\.\d+\.\d+/;
+/** The first release whose `/status` names the agents attached to it (`mcpPeers`). */
+const MCP_PEERS_SINCE = '3.6.0';
+/**
+ * Should a proxy stop the older daemon it found, and start its own release?
+ *
+ * Only an OLDER daemon, read from `/status`, with no tab attached and no other agent attached. A
+ * tab or an agent can have a call in flight, so that daemon stays and the skew is described as
+ * before. A daemon before `MCP_PEERS_SINCE` does not report its agents, so it stays too. A status
+ * that does not parse, or a version that does not compare, keeps the daemon.
+ */
+export function retiresOlderDaemon(status, proxyVersion) {
+    if (typeof status !== 'object' || null === status) {
+        return false;
+    }
+    const fields = status;
+    const version = fields['version'];
+    if ('string' !== typeof version) {
+        return false;
+    }
+    // Only a plain release number compares; anything else keeps the daemon.
+    if (!RELEASE_VERSION.test(version) || !isNewerVersion(proxyVersion, version)) {
+        return false;
+    }
+    // An older daemon never sends `mcpPeers`, so it cannot say that no agent is attached.
+    if (isNewerVersion(MCP_PEERS_SINCE, version)) {
+        return false;
+    }
+    const peers = fields['mcpPeers'];
+    // A daemon sends `mcpPeers` only when an agent is attached.
+    if (Array.isArray(peers) && 0 < peers.length) {
+        return false;
+    }
+    return 0 === summarizeStatus(status).sessionCount;
+}
 /**
  * MCP proxy mode: ensures the daemon is running, then bridges Claude Code's
  * stdin/stdout to the daemon's SSE endpoint. This is the recommended way to
@@ -46,10 +84,9 @@ export async function handleMcp(opts) {
     // takes the requested port when it is free or unclaimed, and relocates to an OS-assigned port
     // rather than adopting a daemon that belongs to somebody else.
     //
-    // Synchronous-looking on purpose: a probe is one loopback connect, and doing it here keeps the
-    // proxy's transport built around a single fixed number. Making the proxy chase a moving port would
-    // mean reworking the reconnect path, which is the one piece whose failure reads to a user as
-    // "the MCP server disappeared mid-session".
+    // The reconnect path keeps one port. Only a WAKE, which already starts from a dormant proxy,
+    // resolves again and moves the proxy: see `ensure`. The reconnect path is the one piece whose
+    // failure reads to a user as "the MCP server disappeared mid-session", so it does not chase.
     // Read once and reused by the wake path below: the boot resolution and every later wake must be
     // defending the SAME identity, and computing it twice is how they drift apart.
     // Before the port work, because it is the only moment we are guaranteed to get on a machine that
@@ -61,24 +98,29 @@ export async function handleMcp(opts) {
         migrateApprovals({
             io: agentIo,
             home: homedir(),
-            platform: process.platform,
+            platform: platformKey(process.platform),
             stateHome: reticleStateHome(),
             version: SERVER_VERSION,
             log,
         });
     }
     const projectId = readProjectId(process.cwd());
-    const port = await resolveMcpPort(opts.port, projectId, reticleStateHome(), {
+    const resolvePort = () => resolveMcpPort(opts.port, projectId, reticleStateHome(), {
         alive: isAlive,
         daemonPresent: async (p) => presenceIsUsable(await probePresence(p, { tcpOpen: probeDaemon, status: fetchStatus })),
         pickPort: (p) => pickDaemonPortToBind(p),
     }, readProjectPort(process.cwd()));
-    if (port !== opts.port) {
+    const noteRelocated = (to) => {
         log('reticle_mcp_port_relocated', {
             requested: opts.port,
-            port,
-            reason: relocationReason(opts.port, port, projectId, reticleStateHome(), isAlive),
+            port: to,
+            reason: relocationReason(opts.port, to, projectId, reticleStateHome(), isAlive),
         });
+    };
+    // `let`: a wake that finds the port taken resolves again, and the proxy follows (#1651, #1652).
+    let port = await resolvePort();
+    if (port !== opts.port) {
+        noteRelocated(port);
     }
     // The proxy IS the MCP server the editor launched. Nothing respawns it, so an uncaught throw here
     // is what a user experiences as "the MCP server disconnected — open /mcp and reconnect". Log it,
@@ -88,7 +130,11 @@ export async function handleMcp(opts) {
     // swallows stderr, so wiring these to `log` meant a crash was handled and then unrecorded — the
     // failure a user reports as "it disconnected" left nothing behind to read.
     setProxyLogPort(port);
-    const resilience = installProxyResilience(process, proxyLog);
+    // The storm exit is a proxy exit too: report it before the process goes.
+    // Only the client pipes count toward the storm exit; see installProxyResilience.
+    const resilience = installProxyResilience(process, proxyLog, undefined, () => {
+        void flushProxyExit(ProxyExitReason.CLIENT_GONE_STORM).finally(() => process.exit(0));
+    }, [process.stdin, process.stdout]);
     /**
      * Make sure a daemon is on the port, spawning one if not.
      *
@@ -97,7 +143,10 @@ export async function handleMcp(opts) {
      * a dead port until the budget ran out and the agent's MCP server exited with it. Reticle simply
      * disappeared mid-session with nothing said. Respawning here makes the reconnect self-healing.
      */
-    const ensure = async () => {
+    // Resolved when a new daemon process starts, so the proxy can answer the handshake at once.
+    let markSpawning = () => undefined;
+    const spawning = new Promise((resolve) => (markSpawning = resolve));
+    const ensure = async (mayRelocate = true) => {
         // The same question every other surface asks. It used to be a bare TCP connect, so a stranger on
         // the bridge port answered "a daemon is here" — the proxy connected, the stream ended, and each
         // client request woke into the identical non-answer. Rejecting here is what puts the proxy
@@ -112,9 +161,34 @@ export async function handleMcp(opts) {
         // APPLICATION. That is worse than the disconnect it was reintroduced under the cover of, because
         // a disconnect is visible and this is a false green wearing a valid session.
         const wake = decideWake(presence, daemonProjectAt(port, reticleStateHome()), projectId);
-        if (WakeAction.USE === wake)
-            return;
+        if (WakeAction.USE === wake) {
+            // A proxy from a newer release stops an older daemon that nobody is using, and starts its own.
+            // Otherwise every tool refused on the skew until a person ran `reticle restart`.
+            const status = await fetchStatus(port);
+            if (!retiresOlderDaemon(status, SERVER_VERSION)) {
+                return port;
+            }
+            log('reticle_mcp_retiring_older_daemon', { port, proxyVersion: SERVER_VERSION });
+            // Not stopped: use it. The daemon describes the skew to this agent, as before.
+            if (!(await runKill(port, false))) {
+                return port;
+            }
+        }
+        if (WakeAction.REFUSE === wake && mayRelocate) {
+            // Somebody else took the port after our daemon left it. Resolve again, as at boot: our own
+            // daemon wherever it moved, else a free port. Once per wake, so it cannot loop.
+            const moved = await resolvePort();
+            if (moved !== port) {
+                noteRelocated(moved);
+                port = moved;
+                setProxyLogPort(port);
+                return ensure(false);
+            }
+        }
         if (WakeAction.REFUSE === wake) {
+            void reportWakeRefused(PortPresence.DAEMON === presence
+                ? WakeRefusalPresence.OTHER_PROJECT
+                : WakeRefusalPresence.FOREIGN);
             throw new Error(PortPresence.DAEMON === presence
                 ? `the daemon on port ${String(port)} belongs to a different project, so this one will ` +
                     'not adopt it. Stop it, or start this project on its own port.'
@@ -123,6 +197,7 @@ export async function handleMcp(opts) {
         const scriptPath = process.argv[1];
         if (scriptPath === undefined) {
             log('reticle_mcp_no_script', {});
+            await flushProxyExit(ProxyExitReason.WAKE_FAILED);
             process.exit(1);
         }
         const daemonArgs = daemonSpawnArgs({
@@ -133,6 +208,7 @@ export async function handleMcp(opts) {
             ...(httpPort !== undefined ? { httpPort } : {}),
             ...(httpToken !== undefined ? { httpToken } : {}),
         });
+        markSpawning();
         spawnDaemon(process.execPath, scriptPath, daemonArgs, port);
         // Announce the daemon only once the PORT ACCEPTS. This line used to be written the instant the
         // child was spawned, which on a Windows first bootstrap meant `reticle_mcp_daemon_started`
@@ -141,6 +217,7 @@ export async function handleMcp(opts) {
         // none: a client that believes it stops waiting for the thing that has not happened.
         await waitForDaemon(port);
         log('reticle_mcp_daemon_started', { port, ...(driveUrl !== undefined ? { driveUrl } : {}) });
+        return port;
     };
     // Start the proxy WHATEVER happened to the daemon.
     //
@@ -150,35 +227,44 @@ export async function handleMcp(opts) {
     // editor shows a server that failed to start. Nothing about that is unrecoverable: the proxy
     // answers `initialize` itself, serves the cached catalog, and its wake path retries a daemon on
     // every client request. Present-and-complaining beats absent, because absent needs a human.
-    // `void`: the chain handles its own failure and the process must not wait on it — the proxy is
-    // started from `finally` either way.
-    void ensure()
-        .catch((err) => {
+    //
+    // The proxy starts NOW, beside the daemon start, and dials when the start is done. A client that
+    // does not wait for MCP servers gets the handshake and the tool list before the daemon is up.
+    const ready = ensure().catch((err) => {
         log('reticle_mcp_daemon_unavailable', {
             error: err instanceof Error ? err.message : String(err),
             note: 'serving anyway — the next tool call will try to start a daemon again',
         });
-    })
-        .finally(() => {
-        // Also `void`: the proxy runs for the life of the process and is never awaited by anyone.
-        //
-        // The `.catch` is load-bearing despite that. `startMcpProxy` rejects when its FIRST connect
-        // fails — which is precisely the case this block exists to tolerate, a daemon that is not
-        // there yet — and with nothing attached that reject became an unhandledRejection. Reported
-        // from a win32 user as a crash reading `connect ECONNREFUSED` with an EMPTY frame list,
-        // because the stack of a refused socket is entirely node internals and the privacy filter
-        // keeps only Reticle frames. So the one path we most want diagnosable arrived as an anonymous
-        // crash. The proxy itself is unaffected — it has already installed its stdin reader and goes
-        // on serving from cache, waking a daemon on the next request — which is exactly why this
-        // must be logged as the expected condition it is rather than reported as a defect.
-        void startMcpProxy(port, ensure, undefined, () => {
-            resilience.noteUsableSession();
-        }).catch((err) => {
-            log('reticle_mcp_proxy_first_connect_failed', {
-                port,
-                error: err instanceof Error ? err.message : String(err),
-                note: 'serving from cache; the next client request will try to start a daemon',
-            });
+    });
+    // Also `void`: the proxy runs for the life of the process and is never awaited by anyone.
+    //
+    // The `.catch` is load-bearing despite that. `startMcpProxy` rejects when its FIRST connect
+    // fails — which is precisely the case this block exists to tolerate, a daemon that is not
+    // there yet — and with nothing attached that reject became an unhandledRejection. Reported
+    // from a win32 user as a crash reading `connect ECONNREFUSED` with an EMPTY frame list,
+    // because the stack of a refused socket is entirely node internals and the privacy filter
+    // keeps only Reticle frames. So the one path we most want diagnosable arrived as an anonymous
+    // crash. The proxy itself is unaffected — it has already installed its stdin reader and goes
+    // on serving from cache, waking a daemon on the next request — which is exactly why this
+    // must be logged as the expected condition it is rather than reported as a defect.
+    void startMcpProxy(port, ensure, undefined, () => {
+        resilience.noteUsableSession();
+    }, {
+        ready,
+        spawning,
+        // Loaded only when needed: the tool table is large, and a warm start never uses it.
+        tools: async () => {
+            const [{ staticToolCatalog }, { resolveToolSurface }] = await Promise.all([
+                import('../../surface/mcp/mcp.js'),
+                import('../../surface/tools/tool-surface.js'),
+            ]);
+            return staticToolCatalog(resolveToolSurface());
+        },
+    }).catch((err) => {
+        log('reticle_mcp_proxy_first_connect_failed', {
+            port,
+            error: err instanceof Error ? err.message : String(err),
+            note: 'serving from cache; the next client request will try to start a daemon',
         });
     });
 }

package/dist/command/cli/open-navigate.d.ts

@@ -0,0 +1,43 @@
+import { type ToolCaller } from './adhoc-verdict.js';
+/**
+ * `reticle open <url> --navigate`: move the tab that is already on this origin to `url`.
+ *
+ * The default leaves that tab where it is, on purpose: `open` is often run by a person whose tab it
+ * is (see `decideOpen`). But a caller with no MCP tools, a shell loop or an agent whose MCP link
+ * timed out, then had no way past the first page of a multi-page site short of restarting the
+ * daemon (#1140). This is the explicit opt-in. It sends the same `reticle_navigate` an agent would,
+ * over the daemon's own SSE transport, exactly as `verify --expect` does, and waits for arrival.
+ */
+export interface OpenNavigateOptions {
+    port: number;
+    sessionId: string;
+    url: string;
+    /**
+     * The daemon's pairing token. Omitted, it is read here, the way `verify --expect` reads it, so the
+     * CLI entry point does not reach into the bridge itself. A test that injects `connect` gets none.
+     */
+    token?: string;
+    /** Injected so a test does not need a live daemon. */
+    connect?: (endpoint: URL) => Promise<ToolCaller>;
+}
+/** Accepted by the browser, but no page on the url was observed: not `navigated`, and not an error. */
+export declare const NAVIGATE_UNCONFIRMED_NOTE: string;
+/**
+ * Navigate the session and describe the outcome as fields for the `reticle_open` line. `navigated`
+ * is set only when the tool says the page arrived; otherwise the tool's own reason is passed on,
+ * never a success the navigate did not report.
+ */
+export declare function navigateLeftTab(options: OpenNavigateOptions): Promise<Record<string, unknown>>;
+/** `--navigate` found a tab on the origin, but the tab never said which session it is. */
+export declare const NAVIGATE_NO_SESSION_ID: string;
+/**
+ * The tabs `open` may pick from.
+ *
+ * `--navigate` MOVES a tab, so it may only pick one of this project's: on a daemon serving two
+ * projects, the origin match alone could hand it the other project's tab. A tab that reports no
+ * project is kept, since nothing says it is someone else's. Reuse and the left-as-is note only read,
+ * so without `--navigate`, or with no project to scope by, every tab stays a candidate.
+ */
+export declare function openCandidates<T extends {
+    projectId?: string | undefined;
+}>(sessions: T[], navigate: boolean, myProject: string | undefined): T[];

package/dist/command/cli/open-navigate.js

@@ -0,0 +1,85 @@
+import { ReticleTool } from '@reticlehq/core';
+import { connectOverSse, endpointFor, verdictOf } from './adhoc-verdict.js';
+import { readOrCreatePairingTokenSync, defaultPairingTokenDir, } from '../../portal/bridge/pairing-token.js';
+/** Named, as the repository asks of every user-facing string. */
+const DAEMON_UNREACHABLE = 'could not reach the daemon to navigate';
+const NAVIGATE_FAILED = 'navigate failed';
+const NO_ARRIVAL_REPORTED = 'reticle_navigate did not report arrival';
+/** Accepted by the browser, but no page on the url was observed: not `navigated`, and not an error. */
+export const NAVIGATE_UNCONFIRMED_NOTE = 'the browser accepted the navigation, but no page on that url reconnected in the wait window, so ' +
+    'arrival was not observed. Re-run `reticle status` before relying on the tab being there.';
+/**
+ * Navigate the session and describe the outcome as fields for the `reticle_open` line. `navigated`
+ * is set only when the tool says the page arrived; otherwise the tool's own reason is passed on,
+ * never a success the navigate did not report.
+ */
+export async function navigateLeftTab(options) {
+    const connect = options.connect ?? connectOverSse;
+    let caller;
+    try {
+        const token = options.token ??
+            (options.connect === undefined
+                ? readOrCreatePairingTokenSync(defaultPairingTokenDir())
+                : undefined);
+        caller = await connect(endpointFor(options.port, token));
+    }
+    catch (error) {
+        return {
+            error: `${DAEMON_UNREACHABLE}: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+    try {
+        const result = await caller.call(ReticleTool.NAVIGATE, {
+            url: options.url,
+            sessionId: options.sessionId,
+        });
+        // `ok` is the field every navigate answer carries, so a text-only answer is read too.
+        const report = verdictOf(result, 'ok') ?? {};
+        const landedOn = 'string' === typeof report['landedOn'] ? report['landedOn'] : undefined;
+        // A navigation reconnects as a NEW session; the id to act on next is the arrival's, not ours.
+        const arrivedAs = 'string' === typeof report['sessionId'] ? report['sessionId'] : options.sessionId;
+        if (true === report['ok'] && false === report['confirmed'] && landedOn === undefined) {
+            return { requested: options.url, sessionId: arrivedAs, note: NAVIGATE_UNCONFIRMED_NOTE };
+        }
+        if (true === report['ok']) {
+            return {
+                navigated: options.url,
+                sessionId: arrivedAs,
+                ...(landedOn === undefined ? {} : { landedOn }),
+            };
+        }
+        const reason = 'string' === typeof report['reason']
+            ? report['reason']
+            : 'string' === typeof report['error']
+                ? report['error']
+                : NO_ARRIVAL_REPORTED;
+        return {
+            error: `${NAVIGATE_FAILED} (${options.url}): ${reason}`,
+            sessionId: options.sessionId,
+        };
+    }
+    catch (error) {
+        return {
+            error: `${NAVIGATE_FAILED} (${options.url}): ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+    finally {
+        await caller.close().catch(() => undefined);
+    }
+}
+/** `--navigate` found a tab on the origin, but the tab never said which session it is. */
+export const NAVIGATE_NO_SESSION_ID = '--navigate could not move it: that tab reported no session id. Drive it with reticle_navigate, ' +
+    'or open the url in the browser yourself.';
+/**
+ * The tabs `open` may pick from.
+ *
+ * `--navigate` MOVES a tab, so it may only pick one of this project's: on a daemon serving two
+ * projects, the origin match alone could hand it the other project's tab. A tab that reports no
+ * project is kept, since nothing says it is someone else's. Reuse and the left-as-is note only read,
+ * so without `--navigate`, or with no project to scope by, every tab stays a candidate.
+ */
+export function openCandidates(sessions, navigate, myProject) {
+    if (!navigate || myProject === undefined)
+        return sessions;
+    return sessions.filter((s) => s.projectId === undefined || s.projectId === myProject);
+}

package/dist/command/cli/ports/port-holder.d.ts

@@ -26,7 +26,7 @@ export interface PortHolder {
  * identify the holder, rather than asserting the holder is not ours — a claim it has no evidence
  * for, and one that was wrong for every Windows user.
  */
-export declare function captureLookup(command: string, args: readonly string[]): string | null;
+export declare function captureLookup(command: string, args: readonly string[], timeoutMs?: number): string | null;
 /**
  * The FIRST listener in `lsof -nP -iTCP:<port> -sTCP:LISTEN -F pc` output, or null.
  *
@@ -53,11 +53,23 @@ ourPid?: number | null): string;
 export declare function findPortHolder(port: number, exec: (command: string, args: readonly string[]) => string | null): PortHolder | null;
 /** The path in `lsof -a -p <pid> -d cwd -Fn` output, or null when it printed none. */
 export declare function parseProcessCwd(stdout: string): string | null;
+/**
+ * The folder that holds the `node_modules` a command line runs from, or null.
+ *
+ * A dev server started from a project runs a script under that project's `node_modules`, so the
+ * folder before it is the project. The path starts at the last drive letter before it, because an
+ * unquoted node path can come first. No `node_modules` is no evidence, and the answer is null.
+ * ponytail: compares as written; a drive letter in another case does not match.
+ */
+export declare function parseCommandLineRoot(commandLine: string): string | null;
 /**
  * The working directory of whatever LISTENS on `port`, or null.
  *
  * How the daemon tells which checkout served a page when every git worktree declares the same
- * projectId: the dev server runs inside exactly one of them. Null wherever `lsof` cannot answer —
- * Windows, a slim container — and the caller then keeps the answer it had without this.
+ * projectId: the dev server runs inside exactly one of them. Null wherever the lookup cannot answer
+ * — a slim container with no `lsof` — and the caller then keeps the answer it had without this.
+ *
+ * Windows has no `lsof`, and no command shows another process's working directory. There the
+ * answer is the project folder in the listener's command line, from PowerShell.
  */
-export declare function findListenerCwd(port: number, exec: (command: string, args: readonly string[]) => string | null): string | null;
+export declare function findListenerCwd(port: number, exec: (command: string, args: readonly string[], timeoutMs?: number) => string | null, platform?: NodeJS.Platform): string | null;

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

@@ -25,9 +25,14 @@ const LOOKUP_TIMEOUT_MS = 2_000;
  * identify the holder, rather than asserting the holder is not ours — a claim it has no evidence
  * for, and one that was wrong for every Windows user.
  */
-export function captureLookup(command, args) {
+export function captureLookup(command, args, timeoutMs = LOOKUP_TIMEOUT_MS) {
     try {
-        const result = spawnSync(command, [...args], { encoding: 'utf8', timeout: LOOKUP_TIMEOUT_MS });
+        // 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 {
@@ -52,20 +57,25 @@ export function parsePortHolder(stdout) {
     let command;
     for (const raw of stdout.split('\n')) {
         const line = raw.trim();
-        if (0 === line.length)
+        if (0 === line.length) {
             continue;
+        }
         const value = line.slice(1);
         if (line.startsWith(PID_FIELD)) {
-            if (pid !== undefined)
-                break; // a second record: the first one is the answer
+            // A second record: the first one is the answer.
+            if (pid !== undefined) {
+                break;
+            }
             const parsed = Number(value);
-            if (!Number.isInteger(parsed) || parsed <= 0)
+            if (!Number.isInteger(parsed) || parsed <= 0) {
                 return null;
+            }
             pid = parsed;
             continue;
         }
-        if (line.startsWith(COMMAND_FIELD) && command === undefined)
+        if (line.startsWith(COMMAND_FIELD) && command === undefined) {
             command = value;
+        }
     }
     return pid === undefined || command === undefined ? null : { pid, command };
 }
@@ -126,22 +136,58 @@ const NAME_FIELD = 'n';
 /** The path in `lsof -a -p <pid> -d cwd -Fn` output, or null when it printed none. */
 export function parseProcessCwd(stdout) {
     for (const raw of stdout.split('\n')) {
-        if (raw.startsWith(NAME_FIELD) && raw.length > NAME_FIELD.length)
+        if (raw.startsWith(NAME_FIELD) && raw.length > NAME_FIELD.length) {
             return raw.slice(1);
+        }
     }
     return null;
 }
+/** A Windows PowerShell cold start alone can take more than the lsof bound. */
+const WINDOWS_LOOKUP_TIMEOUT_MS = 8_000;
+/** The listener's command line: Windows does not show another process's working directory. */
+const windowsListenerScript = (port) => `$c = Get-NetTCPConnection -State Listen -LocalPort ${String(port)} -ErrorAction Stop | ` +
+    'Select-Object -First 1; ' +
+    '(Get-CimInstance Win32_Process -Filter "ProcessId=$($c.OwningProcess)").CommandLine';
+const NODE_MODULES = /[\\/]node_modules[\\/]/i;
+const DRIVE_START = /[A-Za-z]:[\\/]/g;
+/**
+ * The folder that holds the `node_modules` a command line runs from, or null.
+ *
+ * A dev server started from a project runs a script under that project's `node_modules`, so the
+ * folder before it is the project. The path starts at the last drive letter before it, because an
+ * unquoted node path can come first. No `node_modules` is no evidence, and the answer is null.
+ * ponytail: compares as written; a drive letter in another case does not match.
+ */
+export function parseCommandLineRoot(commandLine) {
+    const end = commandLine.search(NODE_MODULES);
+    if (end < 0) {
+        return null;
+    }
+    const head = commandLine.slice(0, end);
+    const starts = [...head.matchAll(DRIVE_START)];
+    const start = starts[starts.length - 1]?.index;
+    return start === undefined ? null : head.slice(start);
+}
 /**
  * The working directory of whatever LISTENS on `port`, or null.
  *
  * How the daemon tells which checkout served a page when every git worktree declares the same
- * projectId: the dev server runs inside exactly one of them. Null wherever `lsof` cannot answer —
- * Windows, a slim container — and the caller then keeps the answer it had without this.
+ * projectId: the dev server runs inside exactly one of them. Null wherever the lookup cannot answer
+ * — a slim container with no `lsof` — and the caller then keeps the answer it had without this.
+ *
+ * Windows has no `lsof`, and no command shows another process's working directory. There the
+ * answer is the project folder in the listener's command line, from PowerShell.
  */
-export function findListenerCwd(port, exec) {
+export function findListenerCwd(port, exec, platform = process.platform) {
+    if ('win32' === platform) {
+        const args = ['-NoProfile', '-NonInteractive', '-Command', windowsListenerScript(port)];
+        const line = exec('powershell', args, WINDOWS_LOOKUP_TIMEOUT_MS);
+        return null === line ? null : parseCommandLineRoot(line.trim());
+    }
     const holder = findPortHolder(port, exec);
-    if (null === holder)
+    if (null === holder) {
         return null;
+    }
     const out = exec('lsof', ['-a', '-p', String(holder.pid), '-d', 'cwd', '-Fn']);
     return null === out ? null : parseProcessCwd(out);
 }

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

@@ -10,7 +10,7 @@
 import { readFileSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { SILENT_HOST, buildNodeIo, deriveProjectId, findWorkspaceApps, isDesktopProject, packageName, } from '@reticlehq/init';
-import { asProjectId } from '@reticlehq/core';
+import { asProjectId, mainCheckoutTwin } from '@reticlehq/core';
 /** The project config `reticle init` writes. */
 export const RETICLE_CONFIG_BASENAME = '.reticle.json';
 /**
@@ -35,9 +35,25 @@ const MAX_CONFIG_SEARCH_DEPTH = 6;
  * Returns undefined when nothing is found, which keeps every caller's existing default intact.
  */
 export function findProjectConfig(cwd) {
-    const dir = findProjectConfigDir(cwd);
+    const dir = findProjectConfigDir(cwd) ?? configDirInMainCheckout(cwd);
     return dir === undefined ? undefined : readConfigAt(dir);
 }
+/**
+ * The main checkout's config folder, for a git worktree that has no `.reticle.json` of its own (it
+ * is git-ignored, or not committed yet). Every worktree is the same project, so it keeps one id and
+ * one port. Only the config's VALUES come from here; the worktree stays the project folder.
+ */
+function configDirInMainCheckout(cwd) {
+    const twin = mainCheckoutTwin(resolve(cwd), (path) => {
+        try {
+            return readFileSync(path, 'utf8');
+        }
+        catch {
+            return undefined; // Missing or a directory: not the `.git` file this looks for.
+        }
+    });
+    return twin === undefined ? undefined : findProjectConfigDir(twin);
+}
 /** The directory holding the nearest `.reticle.json` at or above `cwd`, by the same walk. */
 function findProjectConfigDir(cwd) {
     let dir = resolve(cwd);

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/cli/report-command.d.ts

@@ -1,3 +1,5 @@
+/** What the Stop hook tells an agent that tried to stop while its Harness drive runs. */
+export declare function keepAliveReason(runId: string): string;
 export interface ReportInput {
     cwd: string;
     now: number;
@@ -5,12 +7,16 @@ export interface ReportInput {
     treeChanged: boolean;
     session?: string;
     hook?: boolean;
+    /** The user's home, whose `~/.reticle/unmatched` is read too. Absent: the project's root alone. */
+    home?: string;
 }
 export declare function reportFor(input: ReportInput): Promise<{
     lines: string[];
+    block?: string;
 }>;
 /**
- * The command. As a hook it prints Claude Code's `systemMessage` shape and always exits 0: it is
- * print-only by design, so the human sees the gap and the agent is never blocked by it.
+ * The command. As a hook it prints Claude Code's `systemMessage` shape and always exits 0, so the
+ * human sees the gap. It blocks the stop in one case only: a Harness drive the agent started is still
+ * running, bounded by `KEEP_ALIVE_MAX_MS`.
  */
 export declare function handleReport(session: string | undefined, hook: boolean): Promise<void>;