@reticlehq/server 3.5.0 → 3.7.0

package/dist/start-wiring.js

@@ -0,0 +1,169 @@
+/**
+ * The wiring `start` and `startDaemon` share, built in one place so the two entry points cannot drift.
+ *
+ * Split from `index.ts`: that file is the package's front door and the two entry points; these are
+ * the pieces both of them assemble — the browser pool, the drive/real-input provider, the CDP network
+ * router, and the per-project lookups the daemon closes over. `daemon-parity.test.ts` checks both
+ * entry points still call them.
+ */
+import { join } from 'node:path';
+import { cpus, homedir } from 'node:os';
+import { bridgeWsUrl, EventType, ReticleDir, ReticleEnv } from '@reticlehq/core';
+import { fetchPlatformConfig } from './features/harness/platform-config.js';
+import { platformEnvPort } from './memory/cloud/cloud-config.js';
+import { knownProjectCandidates, projectDirectoryFor, } from './memory/project/artifact-root-resolver.js';
+import { createNodeFileSystem } from './memory/project/fs/fs-port.js';
+import { originOf } from './portal/session/session-manager.js';
+import { setBrowserMode, BrowserMode } from './telemetry/browser-mode.js';
+import { sdkFixForDirectory } from './command/version/sdk-fix.js';
+import { SERVER_VERSION } from './command/version/identity/server-version.js';
+import { CdpRealInputProvider, LaunchedRealInputProvider } from './portal/input/real-input.js';
+import { BrowserPool } from './portal/pool/browser-pool.js';
+import { playwrightLauncher, resolveMaxContexts } from './portal/pool/playwright-launcher.js';
+import { readReaderBundle, zeroInstallScript as zeroInstallScriptFor, } from './portal/pool/zero-install.js';
+/**
+ * Build the shared browser pool (one headless Chromium, N capped isolated leased contexts). Lazy —
+ * no Chromium launches until the first lease — so creating it is free even when never used.
+ */
+/** Where the zero-install reader connects: this daemon's own bridge, with its pairing token. */
+export function readerConnect(port, token) {
+    return { url: bridgeWsUrl(port), ...(token === undefined ? {} : { token }) };
+}
+export function createBrowserPool(headless, reader) {
+    const maxContexts = resolveMaxContexts(process.env[ReticleEnv.MAX_CONTEXTS], cpus().length);
+    const genSessionId = () => `lease-${'function' === typeof globalThis.crypto?.randomUUID
+        ? globalThis.crypto.randomUUID()
+        : String(Date.now())}`;
+    // Built on first use and kept: the page that needs it is one whose app never connected.
+    let script;
+    const zeroInstallScript = () => {
+        if (script === undefined) {
+            const bundle = readReaderBundle();
+            script = bundle === undefined ? null : zeroInstallScriptFor(bundle, reader);
+        }
+        return script ?? undefined;
+    };
+    return new BrowserPool(playwrightLauncher({ headless }), {
+        maxContexts,
+        genSessionId,
+        zeroInstallScript,
+        launchHeaded: playwrightLauncher({ headless: false }),
+    });
+}
+/**
+ * Route CDP-authoritative network detail onto the driven session's journal.
+ *
+ * The page and the SDK session share an origin, so a NET_DETAIL is pushed to the matching connected
+ * session. Shared by both entry points: `startDaemon` previously omitted it entirely, so on the path
+ * users actually take, CDP network detail was collected and then dropped on the floor.
+ */
+export function makeNetworkDetailRouter(bridge, driveUrl) {
+    const driveOrigin = originOf(driveUrl ?? '');
+    return (detail) => {
+        // Route by the DOCUMENT that issued the request, not by the request's own origin.
+        //
+        // Matching the request's origin only works for same-origin calls. An app on one origin calling an
+        // API on another — most API calls — produced a detail matching no session, and it was dropped
+        // without a trace. The drive-URL fallback papered over it on the launched path and did nothing on
+        // the CDP-attach path, where driveUrl is undefined and the fallback compares against ''.
+        const pageOrigin = originOf(detail.pageUrl ?? '');
+        const requestOrigin = originOf(detail.url);
+        for (const session of bridge.sessions.all()) {
+            const origin = originOf(session.url);
+            // originOf returns `string | undefined`, NEVER '' — so the old `!== ''` guards were dead, and a
+            // bare `origin === requestOrigin` matched `undefined === undefined` when BOTH the session URL and
+            // the detail URL were unparseable. That routed a NET_DETAIL (with its response headers, incl.
+            // set-cookie) onto an unrelated session. Require a DEFINED origin; undefined operands then simply
+            // fail to match any of the three candidates.
+            const matches = origin !== undefined &&
+                (origin === pageOrigin || origin === requestOrigin || origin === driveOrigin);
+            if (matches) {
+                session.pushEvent({
+                    t: 0,
+                    type: EventType.NET_DETAIL,
+                    sessionId: session.id,
+                    data: { ...detail },
+                });
+            }
+        }
+    };
+}
+/**
+ * Resolve the drive/real-input provider from options — shared by start and startDaemon so the
+ * precedence (driveUrl launch+own → CDP attach → none) and the storageState/injectConnect plumbing
+ * live in ONE place. `onNavigateError` is the entrypoint's own cleanup (close the bridge/shared server)
+ * so a failed launch never leaks a WS port. A past divergence between the two paths let daemon mode
+ * run with a different setup — this removes that risk.
+ */
+export async function resolveRealInput(options, onNavigateError, onNetworkDetail) {
+    const driveUrl = options.driveUrl;
+    if (driveUrl !== undefined && driveUrl.length > 0) {
+        const headless = options.headless ?? true;
+        // The one place that knows. Everything downstream reads it rather than re-deriving it, and a
+        // daemon that launches nothing keeps the default (ATTACHED) rather than guessing.
+        setBrowserMode(headless ? BrowserMode.HEADLESS : BrowserMode.HEADED);
+        const injectConnect = options.injectConnect;
+        const storageState = options.storageState;
+        const factory = options.realInputFactory ??
+            ((opts) => new LaunchedRealInputProvider({
+                driveUrl: opts.driveUrl,
+                headless: opts.headless,
+                ...(injectConnect !== undefined ? { injectConnect } : {}),
+                ...(storageState !== undefined ? { storageState } : {}),
+                ...(onNetworkDetail !== undefined ? { onNetworkDetail } : {}),
+            }));
+        const launched = factory({ driveUrl, headless });
+        try {
+            await launched.navigate();
+        }
+        catch (error) {
+            await onNavigateError(); // no leaked WS port on a failed start
+            throw error;
+        }
+        return { realInput: launched, owned: launched };
+    }
+    const cdpUrl = options.cdpUrl ?? process.env[ReticleEnv.CDP_URL];
+    if (cdpUrl !== undefined && cdpUrl.length > 0) {
+        // Same network sink as the launched path. Whether Reticle opened the browser or attached to one
+        // someone else opened has no bearing on whether it can read that browser's network.
+        const cdp = new CdpRealInputProvider({
+            cdpUrl,
+            ...(onNetworkDetail !== undefined ? { onNetworkDetail } : {}),
+        });
+        return { realInput: cdp, owned: cdp };
+    }
+    return {};
+}
+/**
+ * The SDK-upgrade sentence for the package.json of the project the page announced, evaluated at
+ * each HELLO so a just-edited manifest is what we name. The daemon's cwd only when that project's
+ * directory is unknown, and the framework-neutral sensor when that is not an app either (#1135).
+ */
+export function sdkFixForProject(projectId) {
+    return sdkFixForDirectory(SERVER_VERSION, projectDirectoryFor(projectId) ?? process.cwd());
+}
+/**
+ * Resolve a session's artifact root, from everything this machine knows about where projects live.
+ *
+ * Built once per daemon and closed over by every tool call. The two sources are read lazily and
+ * cheaply on each call rather than snapshotted at startup: `init` can run in another terminal while
+ * this daemon is up, and a resolution that used a startup snapshot would keep answering with a map
+ * from before the project the agent is now driving existed.
+ */
+/**
+ * Every `.reticle` root on this machine that sync should consider, from the same two sources the
+ * artifact resolver uses.
+ *
+ * Read on every call rather than snapshotted, for the same reason: `reticle link` can run in
+ * another terminal while this daemon is up, and a startup snapshot would keep that repo silent
+ * until somebody restarted a process they have no reason to suspect.
+ *
+ * Returns directories that MIGHT be linked; the caller resolves each and skips the ones that are
+ * not. Deciding that here would mean reading every cloud.json on every tick.
+ */
+export function knownProjectRoots() {
+    return [...new Set(knownProjectCandidates().map((c) => join(c.directory, ReticleDir.ROOT)))];
+}
+/** This project's platform credential (stored, else the env key), as the env the platform readers take. */
+export const platformEnvFor = (root) => platformEnvPort(createNodeFileSystem(), root ?? join(process.cwd(), ReticleDir.ROOT), homedir(), process.env);
+export const loadHarnessConfig = async (root) => fetchPlatformConfig(await platformEnvFor(root)());

package/dist/status-payload.d.ts

@@ -7,6 +7,7 @@
  * answering requests. See takeVersionSkewOnto in command/version/version-nudge.ts.
  */
 import type { SessionInfo } from './portal/session/session-info.js';
+import { instrumentationOf, type InstrumentedTab } from './portal/session/recorded-gaps.js';
 interface StatusPayload {
     running: true;
     version: string;
@@ -30,12 +31,23 @@ interface StatusPayload {
     whyLead?: string;
     /** Port of the verify HTTP endpoint this daemon serves — present only when started with `--http`. */
     verifyPort?: number;
+    /**
+     * Each connected tab's instrumentation coverage and, once a verdict recorded a gap, the prompt for
+     * a coding agent — what `reticle doctor` prints as its coverage line.
+     */
+    coverage?: TabCoverage[];
 }
+type TabCoverage = {
+    sessionId: string;
+    url?: string;
+} & ReturnType<typeof instrumentationOf>;
 export declare function statusPayload(sessionCount: number, sessions: SessionInfo[], 
 /** The no-session diagnosis, injected so this stays pure and the port probe stays off this path. */
 why?: string, verifyPort?: number, 
 /** The short rendering of the same diagnosis. Absent on a daemon that has no provider wired. */
-whyLead?: string): StatusPayload;
+whyLead?: string, 
+/** The live tabs, for their coverage. */
+tabs?: readonly InstrumentedTab[]): StatusPayload;
 /**
  * Why `serve --http` cannot claim success against an already-running daemon — or undefined when
  * that daemon already serves the verify HTTP endpoint on the wanted port.
@@ -47,4 +59,14 @@ whyLead?: string): StatusPayload;
  * which errs loud rather than green.
  */
 export declare function verifyEndpointMismatch(status: unknown, wantedPort: number): string | undefined;
+/**
+ * What a restart is about to do to the agents attached to the daemon whose `/status` this is, or
+ * undefined when nothing.
+ *
+ * A restart puts this CLI's version on the daemon. An agent whose own MCP server is older stays
+ * attached to a daemon it no longer matches, and a running agent cannot restart its own MCP server,
+ * so the restart that was meant to converge the versions strands it instead (#812). Said before the
+ * kill, with the way to restart at the version the attached agents run.
+ */
+export declare function strandedClientsNote(status: unknown, next?: string): string | undefined;
 export {};

package/dist/status-payload.js

@@ -1,10 +1,13 @@
 import { CONTRACT_FINGERPRINT } from '@reticlehq/core';
 import { SERVER_VERSION } from './command/version/identity/server-version.js';
+import { instrumentationOf } from './portal/session/recorded-gaps.js';
 export function statusPayload(sessionCount, sessions, 
 /** The no-session diagnosis, injected so this stays pure and the port probe stays off this path. */
 why, verifyPort, 
 /** The short rendering of the same diagnosis. Absent on a daemon that has no provider wired. */
-whyLead) {
+whyLead, 
+/** The live tabs, for their coverage. */
+tabs = []) {
     return {
         running: true,
         version: SERVER_VERSION,
@@ -16,6 +19,15 @@ whyLead) {
         ...(0 === sessionCount && why !== undefined ? { why } : {}),
         ...(0 === sessionCount && whyLead !== undefined ? { whyLead } : {}),
         ...(verifyPort === undefined ? {} : { verifyPort }),
+        ...(0 === tabs.length
+            ? {}
+            : {
+                coverage: tabs.map((tab) => ({
+                    sessionId: tab.id,
+                    ...(tab.url === undefined ? {} : { url: tab.url }),
+                    ...instrumentationOf(tab),
+                })),
+            }),
     };
 }
 /**
@@ -39,3 +51,26 @@ export function verifyEndpointMismatch(status, wantedPort) {
         ? `the daemon already running serves the verify HTTP endpoint on :${String(served)}, not :${String(wantedPort)} — ${fix}`
         : `a daemon is already running without the verify HTTP endpoint — \`--http\` cannot be applied to it; ${fix}`;
 }
+/**
+ * What a restart is about to do to the agents attached to the daemon whose `/status` this is, or
+ * undefined when nothing.
+ *
+ * A restart puts this CLI's version on the daemon. An agent whose own MCP server is older stays
+ * attached to a daemon it no longer matches, and a running agent cannot restart its own MCP server,
+ * so the restart that was meant to converge the versions strands it instead (#812). Said before the
+ * kill, with the way to restart at the version the attached agents run.
+ */
+export function strandedClientsNote(status, next = SERVER_VERSION) {
+    const raw = 'object' === typeof status && null !== status
+        ? status.mcpPeers
+        : undefined;
+    const peers = Array.isArray(raw) ? raw.filter((v) => 'string' === typeof v) : [];
+    const behind = [...new Set(peers.filter((v) => v !== next))];
+    const pin = behind[0];
+    if (pin === undefined)
+        return undefined;
+    return (`warning: ${String(peers.length)} agent MCP server(s) are attached at ${behind.join(', ')}, ` +
+        `and this restart runs the daemon at ${next}. They stay attached to a daemon they no longer ` +
+        'match until their editor restarts its MCP server. To keep them working, restart at their ' +
+        `version instead: npx @reticlehq/server@${pin} restart`);
+}

package/dist/surface/http-server.js

@@ -5,6 +5,7 @@ import { getSessionMetrics } from '../telemetry/session-metrics.js';
 import { agentPeerSkew, PEER_VERSION_PARAM, PEER_CONTRACT_PARAM, } from '../command/version/peer-announce.js';
 import { log } from '../log.js';
 import { isLoopbackHost, isLocalWebOrigin, isLoopbackPeer, requestToken, tokensMatch, } from '../portal/bridge/token-auth.js';
+import { clientDirectoryFromPeer, runWithClientDirectory } from '../hooks/client-directory.js';
 import { LOOPBACK_IDLE_MS } from './loopback-agent.js';
 /**
  * Creates a shared HTTP server that handles both the WebSocket bridge (browser SDK) and the
@@ -27,6 +28,8 @@ export function createSharedServer(options = {}) {
      * and this message is addressed to the proxy rather than to the client behind it.
      */
     const sseStreams = new Map();
+    /** The version each attached agent's MCP server announced, by SSE session. */
+    const peerVersions = new Map();
     const token = options.token;
     // The agent control plane (MCP transport) and /status carry the same trust as the browser WS: a
     // loopback peer is trusted (the local stdio proxy and `reticle status` always dial 127.0.0.1), but any
@@ -78,7 +81,11 @@ export function createSharedServer(options = {}) {
         if ('GET' === req.method && path === STATUS_PATH) {
             // A setup run waiting on this daemon says so on its polls; see daemon-usefulness.
             const held = url.searchParams.has(STATUS_HOLD_QUERY);
-            const body = JSON.stringify(statusProvider?.(held) ?? { running: true });
+            const status = statusProvider?.(held) ?? { running: true };
+            // The attached agents' MCP versions, so `restart` can say whom it is about to strand (#812).
+            const body = JSON.stringify('object' === typeof status && null !== status && 0 < peerVersions.size
+                ? { ...status, mcpPeers: [...peerVersions.values()] }
+                : status);
             res.writeHead(200, { 'Content-Type': 'application/json' });
             res.end(body);
             return;
@@ -156,11 +163,15 @@ export function createSharedServer(options = {}) {
             const sid = transport.sessionId;
             transports.set(sid, transport);
             sseStreams.set(sid, res);
+            const peerVersion = url.searchParams.get(PEER_VERSION_PARAM);
+            if (null !== peerVersion && 0 < peerVersion.length)
+                peerVersions.set(sid, peerVersion);
             if (1 === transports.size)
                 agentPresence?.(true); // first agent attached
             res.on('close', () => {
                 transports.delete(sid);
                 sseStreams.delete(sid);
+                peerVersions.delete(sid);
                 transport.close().catch(() => undefined);
                 mcpServer.close().catch(() => undefined);
                 log('mcp_client_disconnected', { sessionId: sid });
@@ -202,7 +213,12 @@ export function createSharedServer(options = {}) {
                 res.end('session not found');
                 return;
             }
-            transport.handlePostMessage(req, res).catch((err) => {
+            const clientDirectory = clientDirectoryFromPeer(isLoopbackPeer(req.socket.remoteAddress), req.headers);
+            const deliver = () => transport.handlePostMessage(req, res);
+            const posted = clientDirectory === undefined
+                ? deliver()
+                : runWithClientDirectory(clientDirectory, deliver);
+            posted.catch((err) => {
                 const message = err instanceof Error ? err.message : String(err);
                 log('mcp_message_error', { error: message });
             });

package/dist/surface/mcp/attach-memory.d.ts

@@ -71,6 +71,7 @@ export declare function describeAttachState(state: AttachState): string | undefi
 /** What `reticle status` reports about the client side of the install. */
 interface AttachStatusFields {
     mcpClient: AttachState;
+    mcpClientSaid: string;
     mcpClientAction?: string;
 }
 /**

package/dist/surface/mcp/attach-memory.js

@@ -169,6 +169,13 @@ export function describeAttachState(state) {
         return NEVER_CALLED_ACTION;
     return undefined;
 }
+/** Each state in words, for a person: the state names are the record's, never the reader's. */
+const ATTACH_STATE_SAID = {
+    [AttachState.ENUMERATED]: "✓ your agent has read and used Reticle's tools",
+    [AttachState.NEVER_CALLED]: "your agent read Reticle's tools and has not called one yet",
+    [AttachState.NEVER_ENUMERATED]: '✗ your agent started Reticle and never read its tools',
+    [AttachState.NEVER_ATTACHED]: 'no agent has started Reticle on this port yet',
+};
 /**
  * The client-side fields for one `status` run.
  *
@@ -181,5 +188,9 @@ export function attachStatusFields(stateDir, port) {
     const action = describeAttachState(state);
     // OMITTED rather than undefined: `exactOptionalPropertyTypes` is on, and an absent key is also
     // what keeps the healthy line to one fact.
-    return { mcpClient: state, ...(action === undefined ? {} : { mcpClientAction: action }) };
+    return {
+        mcpClient: state,
+        mcpClientSaid: ATTACH_STATE_SAID[state],
+        ...(action === undefined ? {} : { mcpClientAction: action }),
+    };
 }

package/dist/surface/mcp/mcp-proxy.d.ts

@@ -25,6 +25,8 @@ export declare const RECONNECT_INITIALIZE_ID = "__reticle_proxy_reinit";
 export declare class PendingRequests {
     #private;
     observeOutbound(line: string): void;
+    /** Whether this unanswered request asked for a Harness drive. */
+    isDrive(id: unknown): boolean;
     observeInbound(line: string): void;
     get unanswered(): string[];
     /**
@@ -34,6 +36,8 @@ export declare class PendingRequests {
     take(id: unknown): boolean;
     /** Take every unanswered id and forget them, so the same request is failed at most once. */
     drain(): string[];
+    /** Forget which requests were drives, once their replies are written. */
+    clearDrives(): void;
 }
 /**
  * JSON-RPC errors for every request that was in flight when the stream died.
@@ -99,6 +103,11 @@ export declare class HandshakeReplay {
  * to reconnect and how to answer what it cannot send.
  */
 export declare function buildSessionUrl(rawData: string, port: number): string | null;
+/** The briefing's facts about this directory; a live session outweighs stale memory (#1138). */
+export declare function instructionStateAt(port: number, liveSessions?: number): {
+    previouslyConnected: boolean;
+    appHere: boolean;
+};
 export declare function startMcpProxy(port: number, 
 /**
  * Bring a daemon back before reconnecting. Without it the proxy retried a DEAD port until the

package/dist/surface/mcp/mcp-proxy.js

@@ -9,7 +9,7 @@ export { SseFrameParser } from './sse-frame-parser.js';
 export { probeDaemon, waitForDaemon, waitForDaemonBind } from './proxy/proxy-daemon-probe.js';
 import { probeDaemon } from './proxy/proxy-daemon-probe.js';
 import { SERVER_VERSION } from '../../command/version/identity/server-version.js';
-import { buildServerInstructions } from './server-instructions.js';
+import { buildServerInstructions, localizeInstructions } from './server-instructions.js';
 import { hasAnyProjectConnectedBefore } from '../../memory/recall/prior/connection-memory.js';
 import { reticleStateHome } from '../../command/daemon/daemon.js';
 import { projectIdsAt } from '../../command/cli/ports/resolve/cli-port.js';
@@ -17,6 +17,7 @@ import { PEER_VERSION_PARAM, PEER_CONTRACT_PARAM } from '../../command/version/p
 import { onStreamDrop, onClientRequest, onReconnectBudgetSpent, onQueueExpired, OnDrop, OnRequest, } from './proxy/proxy-lifecycle.js';
 import { describePresence, probePresence } from '../../command/daemon/binding/port-presence.js';
 import { flushProxySessionMetrics } from '../../telemetry/proxy-telemetry.js';
+import { detectStack } from '../../telemetry/feedback-context.js';
 /**
  * The same `/status` probe `doctor`, `status` and `kill` ask with. Reused rather than re-written:
  * the whole defect this import closes was the proxy answering a DIFFERENT question from every other
@@ -31,6 +32,7 @@ export { accountProxyLogWrite, proxyLog, proxyLogPath, PROXY_LOG_CHECK_BYTES, re
 import { proxyLog } from './proxy/proxy-log.js';
 import { OutageReason, OutageStage, reportMcpOutage } from './faults/mcp-outage.js';
 import { postToSession } from './proxy/mcp-post-transport.js';
+import { MSG_DRIVE_MAY_BE_RUNNING, isHarnessDriveCall } from './proxy/drive-calls.js';
 import { reconnectDelayMs } from './proxy/proxy-backoff.js';
 import { PROXY_IDLE_EXIT_EVENT, ProxyIdleExit, resolveProxyIdleExitMs } from './proxy-idle-exit.js';
 export { reconnectDelayMs } from './proxy/proxy-backoff.js';
@@ -83,11 +85,20 @@ const INITIALIZED_METHOD = 'notifications/initialized';
  */
 export class PendingRequests {
     #ids = new Set();
+    /** The pending requests that start or poll a Harness drive, which outlives a lost connection. */
+    #drives = new Set();
     observeOutbound(line) {
         const msg = parseJsonRpc(line);
         if (null === msg || msg.id === undefined || msg.method === undefined)
             return;
-        this.#ids.add(JSON.stringify(msg.id));
+        const id = JSON.stringify(msg.id);
+        this.#ids.add(id);
+        if (isHarnessDriveCall(msg))
+            this.#drives.add(id);
+    }
+    /** Whether this unanswered request asked for a Harness drive. */
+    isDrive(id) {
+        return this.#drives.has(JSON.stringify(id));
     }
     observeInbound(line) {
         const msg = parseJsonRpc(line);
@@ -103,6 +114,7 @@ export class PendingRequests {
      * a duplicate response to one id is a protocol violation, not a belt-and-braces retry.
      */
     take(id) {
+        this.#drives.delete(JSON.stringify(id));
         return this.#ids.delete(JSON.stringify(id));
     }
     /** Take every unanswered id and forget them, so the same request is failed at most once. */
@@ -111,6 +123,10 @@ export class PendingRequests {
         this.#ids.clear();
         return ids;
     }
+    /** Forget which requests were drives, once their replies are written. */
+    clearDrives() {
+        this.#drives.clear();
+    }
 }
 /**
  * JSON-RPC errors for every request that was in flight when the stream died.
@@ -125,9 +141,12 @@ export class PendingRequests {
  * with the MCP server still perfectly alive. An agent cannot tell that apart from "still working".
  */
 export function streamLossReplies(pending, reason, nextStep) {
-    return pending
-        .drain()
-        .map((id) => transportLossReply(JSON.parse(id), reason, nextStep));
+    const replies = pending.drain().map((id) => {
+        const parsed = JSON.parse(id);
+        return transportLossReply(parsed, reason, nextStep, pending.isDrive(parsed));
+    });
+    pending.clearDrives();
+    return replies;
 }
 /**
  * -32001: a server-defined error. Not -32603 (internal): nothing went wrong INSIDE the call, the
@@ -141,14 +160,16 @@ const TRANSPORT_LOSS_CODE = -32001;
  * `nextStep` is appended when the caller knows one. Without it this reply describes a condition and
  * stops there, which is all a first-run user got out of their first ever tool call.
  */
-function transportLossReply(id, reason, nextStep) {
+function transportLossReply(id, reason, nextStep, drive = false) {
     return JSON.stringify({
         jsonrpc: '2.0',
         id,
         error: {
             code: TRANSPORT_LOSS_CODE,
-            message: `the daemon connection dropped (${reason}) before this call was answered — it did NOT ` +
-                'complete. Reticle is recovering the connection; retry if the action is safe to repeat.' +
+            message: (drive
+                ? `the daemon connection dropped (${reason}) before this call was answered. ${MSG_DRIVE_MAY_BE_RUNNING}`
+                : `the daemon connection dropped (${reason}) before this call was answered — it did NOT ` +
+                    'complete. Reticle is recovering the connection; retry if the action is safe to repeat.') +
                 (nextStep === undefined ? '' : ` ${nextStep}`),
         },
     });
@@ -288,14 +309,43 @@ export function buildSessionUrl(rawData, port) {
  */
 function proxyInstructions(port) {
     try {
-        return buildServerInstructions({
-            previouslyConnected: hasAnyProjectConnectedBefore(reticleStateHome(), port, projectIdsAt(process.cwd())),
-        });
+        return buildServerInstructions(instructionStateAt(port));
     }
     catch {
         return buildServerInstructions({ previouslyConnected: false });
     }
 }
+/** The briefing's facts about this directory; a live session outweighs stale memory (#1138). */
+export function instructionStateAt(port, liveSessions = 0) {
+    const cwd = process.cwd();
+    return {
+        previouslyConnected: liveSessions > 0 || hasAnyProjectConnectedBefore(reticleStateHome(), port, projectIdsAt(cwd)),
+        appHere: detectStack(cwd).stack !== undefined,
+    };
+}
+/** An `initialize` reply re-briefed for the AGENT's directory; see localizeInstructions. */
+function withLocalBriefing(line, appHere) {
+    if (!line.includes('"instructions"'))
+        return line;
+    try {
+        const msg = JSON.parse(line);
+        if (null === msg || 'object' !== typeof msg || !('result' in msg))
+            return line;
+        const result = msg.result;
+        if (null === result || 'object' !== typeof result || !('instructions' in result))
+            return line;
+        const { instructions } = result;
+        if ('string' !== typeof instructions)
+            return line;
+        const localized = localizeInstructions(instructions, appHere);
+        if (localized === instructions)
+            return line;
+        return JSON.stringify({ ...msg, result: { ...result, instructions: localized } });
+    }
+    catch {
+        return line;
+    }
+}
 export function startMcpProxy(port, 
 /**
  * Bring a daemon back before reconnecting. Without it the proxy retried a DEAD port until the
@@ -395,6 +445,7 @@ onUsableSession = () => undefined) {
             queueTimer.unref();
         };
         const replay = new HandshakeReplay();
+        const appHere = detectStack(process.cwd()).stack !== undefined;
         const pending = new PendingRequests();
         const quit = (code) => {
             if (stopped)
@@ -421,7 +472,7 @@ onUsableSession = () => undefined) {
         const emit = (line) => {
             idleExit.noteTraffic();
             pending.observeInbound(line);
-            process.stdout.write(`${line}\n`);
+            process.stdout.write(`${withLocalBriefing(line, appHere)}\n`);
         };
         let attempts = 0;
         /** The daemon announced a planned shutdown; the next drop is that, not a fault. */
@@ -459,6 +510,7 @@ onUsableSession = () => undefined) {
                 if (null === failure)
                     return;
                 const msg = parseJsonRpc(line);
+                const drive = null !== msg && pending.isDrive(msg.id);
                 if (null === msg || msg.id === undefined || !pending.take(msg.id))
                     return;
                 // No outage is reported here, deliberately. A POST leg that died while the SSE stream is
@@ -472,7 +524,7 @@ onUsableSession = () => undefined) {
                     reason: failure.reason,
                     note: 'the stream is still up, so nothing else would ever have answered this call',
                 });
-                emit(transportLossReply(msg.id, failure.reason));
+                emit(transportLossReply(msg.id, failure.reason, undefined, drive));
             });
         };
         function onSseEvent(event, data, p) {

package/dist/surface/mcp/mcp.d.ts

@@ -3,15 +3,21 @@ import { z } from 'zod';
 import { type ToolDeps } from '../tools/tools.js';
 import type { ToolDef } from '../tools/tools.js';
 import { type ToolSurface } from '../tools/tool-surface.js';
+import { type ToolCall } from '../tools/tool-kit.js';
+import { type InstructionState } from './server-instructions.js';
 /** The JSON-RPC method the SDK registers its tool dispatcher under. */
 export declare const CALL_TOOL_METHOD = "tools/call";
 /**
- * Merge the runtime-spliced envelope (health/lease/age/control) into a session-bound tool's declared
- * outputSchema so structuredContent validation keeps those fields instead of dropping them. The tool's
- * own keys win over the permissive envelope defaults (e.g. ACT keeps its typed `session` shape).
- * Non-session-bound tools (and tools with no outputSchema) are returned unchanged.
+ * Merge the runtime-spliced envelope into a tool's declared outputSchema so structuredContent
+ * validation keeps those fields instead of rejecting the call. The tool's own keys win over the
+ * permissive envelope defaults (e.g. ACT keeps its typed `session` shape).
+ *
+ * EVERY tool with an output schema, not only the session-bound ones: `runTool` adds `next`,
+ * `update_available`, `version_skew` and the feedback keys to any tool's result, and a session-exempt
+ * tool with a strict schema (`reticle_context`) failed the whole call on a validating client the
+ * first time one of them rode on it.
  */
-export declare function withSessionEnvelope(name: string, outputSchema: z.ZodRawShape | undefined): z.ZodRawShape | undefined;
+export declare function withSessionEnvelope(_name: string, outputSchema: z.ZodRawShape | undefined): z.ZodRawShape | undefined;
 /**
  * Abbreviations whose internal period is NOT a sentence end.
  *
@@ -31,6 +37,28 @@ export { firstSentence } from '../tools/first-sentence.js';
  * form with `RETICLE_ENCODING=pretty`; `RETICLE_ENCODING=toon` is the even-denser tabular encoding.
  */
 export declare function encodeResult(result: unknown, encoding: string): string;
+/** The slice of the SDK's per-request `extra` a tool call reads: cancellation and progress. */
+interface McpRequestExtra {
+    signal?: AbortSignal;
+    _meta?: {
+        progressToken?: string | number;
+    };
+    sendNotification?: (notification: {
+        method: typeof PROGRESS_NOTIFICATION;
+        params: {
+            progressToken: string | number;
+            progress: number;
+            message: string;
+        };
+    }) => Promise<void>;
+}
+declare const PROGRESS_NOTIFICATION = "notifications/progress";
+/**
+ * The request's cancellation and, when the client sent a progress token, a progress reporter. A
+ * long call (a Harness drive's wait) reports each step, so a client that resets its timeout on
+ * progress keeps waiting instead of abandoning a call that is working.
+ */
+export declare function toolCallOf(extra: McpRequestExtra | undefined): ToolCall;
 /**
  * The tools a profile advertises directly.
  *
@@ -77,7 +105,7 @@ export declare function createMcpServer(rawDeps: ToolDeps, profile?: ToolSurface
  * told to instrument a project that is already wired loses a paragraph, while an agent not told
  * loses the entire install — and the second is what the field overwhelmingly shows.
  */
-previouslyConnected?: boolean, 
+previouslyConnected?: boolean | Omit<InstructionState, 'advertised'>, 
 /**
  * The full tool table this server serves. Defaults to what this package ships.
  *