@reticlehq/server 2.12.0 → 2.13.1

package/dist/session/session.js

@@ -4,6 +4,7 @@ import { GapLedger } from '../honesty/gap-ledger.js';
 import { CaptureLedger } from '../honesty/feature-capture.js';
 import { commandTimeoutMessage } from './command-timeout.js';
 import { readHealthEvent } from './session-health.js';
+import { MIRRORED_COMMANDS, mirroredNarration } from './session-mirror.js';
 /** The HUD does not need 200 frames to watch a counter climb; the last state always lands. */
 const IMPACT_PUSH_DEBOUNCE_MS = 700;
 import { PendingCommands, CommandTimeoutError } from './pending-commands.js';
@@ -52,6 +53,12 @@ const REBINDABLE_COMMANDS = new Set([
 ]);
 /** Prefix on minted action ids (a1, a2, …) — the journal's action identity, independent of commands. */
 const ACTION_ID_PREFIX = 'a';
+/**
+ * How many consecutive unanswered commands make a tab unresponsive. One is a page that was merely
+ * busy for its budget; two in a row with no reply between them is a wedge, and the cost of being
+ * wrong about that is one extra browser tab.
+ */
+const UNRESPONSIVE_AFTER_TIMEOUTS = 2;
 /** ws readyState for an OPEN socket — guard fire-and-forget pushes against a closing tab. */
 const WS_OPEN = 1;
 /**
@@ -62,6 +69,17 @@ export class Session {
     id;
     /** Stable build-stamped project identity; undefined for v1.0 SDKs that omit it. */
     projectId;
+    /**
+     * The `.reticle` directory this session's evidence belongs in — impact counters AND capsules.
+     *
+     * Stamped once when the session is created, from the project it declared in HELLO, rather than
+     * resolved per call: the answer cannot change while the tab is connected, and resolving it once
+     * means every counter that fires for this session agrees about where it goes.
+     *
+     * Undefined when nothing could name a project — the caller then falls back to the daemon's own
+     * root, which is what every counter did unconditionally before this existed.
+     */
+    artifactRoot;
     url;
     title;
     adapters;
@@ -82,6 +100,8 @@ export class Session {
     #listeners = new Set();
     #disconnectListeners = new Set();
     #actionSeq = 0;
+    /** Consecutive missed command budgets — free liveness evidence. Any reply resets it. */
+    #unansweredCommands = 0;
     #lastSeenAt;
     #hidden = false;
     /** Which shell the page reported (PAGE_HEALTH). Undefined until the first report lands. */
@@ -204,6 +224,9 @@ export class Session {
             hidden: this.#hidden,
             throttled: base.throttled,
             focused: base.focused,
+            // Without this the desktop branch is unreachable in production: every unit test would pass and
+            // every real Electron window would still be told to open a browser.
+            runtime: this.#runtime,
         });
         return recommendation === undefined ? base : { ...base, recommendation };
     }
@@ -215,13 +238,24 @@ export class Session {
             title: this.title,
             adapters: this.adapters,
             hasCapabilities: this.hasCapabilities,
+            runtime: this.#runtime,
             versionSkew: this.versionSkew,
             hidden: this.#hidden,
             health: () => this.health(),
             staleMs: () => this.staleMs(),
             pendingMarkCount: () => this.#review.pendingCount(),
+            unresponsive: () => this.unresponsive(),
         });
     }
+    /**
+     * Attached but not answering. A tab can be `connected` with a fresh `lastSeenMs` and still answer
+     * nothing: `lastSeenMs` measures the events the SDK streams, not the commands it replies to. Reuse
+     * and auto-selection read that as health, so `reticle open` handed a wedged tab back forever and
+     * `reticle_session{action:"end"}` — a flag on the record, not on the page — could not help.
+     */
+    unresponsive() {
+        return this.#unansweredCommands >= UNRESPONSIVE_AFTER_TIMEOUTS;
+    }
     /** Wall-clock age of the session in milliseconds. */
     staleMs() {
         return this.#clock() - this.#startedAt;
@@ -264,7 +298,7 @@ export class Session {
                 this.#review.add(parsed.data, this.elapsed());
                 // The impact record's `marks` field existed and nothing ever wrote it: the report would
                 // have shown a permanent zero next to a page covered in pins.
-                recordImpact({ marks: 1 });
+                recordImpact({ marks: 1 }, {}, this.artifactRoot);
             }
         }
         if (event.type === EventType.ROUTE_CHANGE) {
@@ -551,6 +585,8 @@ export class Session {
         // the app taking its time — the split telemetry reports in aggregate, made visible per call.
         return span('browser.command', { command: name, sessionId: this.id }, () => awaited)
             .then((result) => {
+            // Answered — whatever the reply said, the command channel is alive.
+            this.#unansweredCommands = 0;
             // The label is only knowable from the REPLY — the request carries a ref, and a ref dies with
             // the next re-render. Recorded here so coverage survives frameworks that replace nodes.
             if (name === ReticleCommand.ACT)
@@ -566,6 +602,8 @@ export class Session {
             // simply not been answered in budget was read as "you were replaced, ask again" — and
             // against a page re-dialling in a loop that turned one read into hundreds of commands on the
             // wire, minutes of wall clock, and an answer still quoting the budget it had blown.
+            if (error instanceof CommandTimeoutError)
+                this.#unansweredCommands += 1;
             const next = error instanceof CommandTimeoutError ? undefined : this.#liveSuccessor();
             if (next === undefined || !REBINDABLE_COMMANDS.has(name))
                 throw error;
@@ -580,11 +618,14 @@ export class Session {
         });
     }
     handleResult(result) {
+        // Any reply at all clears the wedge, including one for a command that already timed out: it is
+        // still proof that bridge→page→bridge works right now, which is the only thing being claimed.
+        this.#unansweredCommands = 0;
         this.#pending.settle(result);
     }
     /** Reject everything still in flight — used on disconnect. */
-    rejectAll(reason) {
-        this.#pending.rejectAll(reason);
+    rejectAll(reason, replaced = false) {
+        this.#pending.rejectAll(reason, replaced);
         for (const listener of this.#disconnectListeners)
             listener();
         this.#disconnectListeners.clear();
@@ -631,11 +672,11 @@ export class Session {
         return undefined;
     }
     /** End this transport without letting a stale socket remove its replacement session. */
-    disconnect(reason) {
+    disconnect(reason, replaced = false) {
         // "Longest run" means the longest SESSION, and it used to be fed a single tool call's duration
         // - so the report's superlative was a number in milliseconds that never grew past a click.
-        recordImpact({}, { runMs: this.elapsed() });
-        this.rejectAll(reason);
+        recordImpact({}, { runMs: this.elapsed() }, this.artifactRoot);
+        this.rejectAll(reason, replaced);
         try {
             this.#socket.close(1008, reason);
         }
@@ -764,8 +805,47 @@ export class Session {
         const minutes = Math.floor(ageMs / 60_000);
         return `Session ${this.id} has been open for ${String(minutes)} minutes. If your task is complete, call reticle_session{action:"end"} now.`;
     }
-    /** Fire-and-forget command send — NOT registered in #pending (no correlated result expected). */
+    /**
+     * The tabs that should SEE what this session is told, supplied by the SessionManager.
+     *
+     * `reticle drive` attaches to the running daemon and is handed a pooled HEADLESS context, so the
+     * whole HUD feed — the narration, the counters, the bug that was just raised — went to a browser
+     * with nobody in front of it, while the developer's own tab showed nothing. The feed is now a
+     * per-project broadcast: the driven tab is still the only one DRIVEN, and any other tab of the
+     * same app is a viewer.
+     */
+    #viewers;
+    /** Wired by SessionManager.add, the one place every session registers. */
+    setViewers(read) {
+        this.#viewers = read;
+    }
+    /**
+     * Fire-and-forget command send — NOT registered in #pending (no correlated result expected).
+     *
+     * Mirrored to this project's other tabs, for the two commands that are a REPORT of what happened
+     * (narration, impact). PRESENTER is deliberately not among them: it is the glow and the lifecycle
+     * that say "the agent is driving THIS tab", and a viewer that showed it would be claiming
+     * something untrue about itself.
+     */
     #post(name, args) {
+        this.#send(name, args);
+        if (!MIRRORED_COMMANDS.has(name))
+            return;
+        for (const viewer of this.#viewers?.() ?? []) {
+            if (viewer === this)
+                continue;
+            // Straight to the raw send, so a mirrored row is never mirrored again.
+            viewer.#send(name, name === ReticleCommand.NARRATE ? this.#labelled(args) : args);
+        }
+    }
+    /** A narration row re-addressed to a tab that is watching rather than being driven. */
+    #labelled(args) {
+        const text = args['text'];
+        if ('string' !== typeof text)
+            return args;
+        return { ...args, text: mirroredNarration(this.id, text) };
+    }
+    #send(name, args) {
         if (this.#socket.readyState !== WS_OPEN)
             return;
         // Shares the same counter as tracked commands, so a fire-and-forget id can never collide with

package/dist/session/wall-clock.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The real clock, named once.
+ *
+ * The logic that needs a clock takes one as an argument so a test can drive it without waiting
+ * (CLAUDE.md rule 7). That leaves the production callers each constructing the same pair of
+ * closures, which is how two of them end up with different sleep implementations. One export, one
+ * place to look.
+ */
+export declare const WALL_CLOCK: {
+    now: () => number;
+    sleep: (ms: number) => Promise<void>;
+};

package/dist/session/wall-clock.js

@@ -0,0 +1,14 @@
+/**
+ * The real clock, named once.
+ *
+ * The logic that needs a clock takes one as an argument so a test can drive it without waiting
+ * (CLAUDE.md rule 7). That leaves the production callers each constructing the same pair of
+ * closures, which is how two of them end up with different sleep implementations. One export, one
+ * place to look.
+ */
+export const WALL_CLOCK = {
+    now: () => Date.now(),
+    sleep: (ms) => new Promise((resolve) => {
+        setTimeout(resolve, ms).unref?.();
+    }),
+};

package/dist/setup/agent-configs.d.ts

@@ -0,0 +1,96 @@
+/**
+ * The coding agents `init`'s own MCP registration does not reach, and where their config lives.
+ *
+ * `init` covers eight clients and only where it already finds them. That leaves real holes: VS
+ * Code's USER-scope mcp.json exists on machines today and init only ever writes the project-scope
+ * one, so a VS Code user has no tools outside the directory they ran init in. Zed, Warp, Kiro, Amp,
+ * Copilot CLI, Amazon Q, Factory Droid, Cline and Roo are not covered at all.
+ *
+ * Three rules, and the second is what keeps this honest:
+ *
+ * 1. A path with OFFICIAL documentation is written even when the agent is absent, so a later
+ *    install finds itself already wired.
+ * 2. A path we cannot evidence is REFUSED. Cline's and Roo's live under VS Code globalStorage,
+ *    which moves under Insiders, portable installs and a custom --user-data-dir; they are written
+ *    only where the host's standard layout is present. A config file at a guessed location is one
+ *    nobody reads, which is indistinguishable from success.
+ * 3. A format we cannot merge safely is never rewritten. TOML, an existing YAML, JSONC carrying
+ *    comments: we print the snippet instead. Reformatting somebody's config to add one entry is
+ *    not ours to do.
+ */
+export declare const AgentConfidence: {
+    /** Documented by the vendor. Safe to create before the agent exists. */
+    readonly OFFICIAL: "official";
+    /** Community-sourced. Only written where the host's own layout proves the path. */
+    readonly COMMUNITY: "community";
+};
+export type AgentConfidence = (typeof AgentConfidence)[keyof typeof AgentConfidence];
+export declare const AgentAction: {
+    readonly CREATE: "create";
+    readonly CREATE_YAML: "create-yaml";
+    readonly MERGE: "merge";
+    readonly ALREADY: "already";
+    readonly MANUAL: "manual";
+    readonly SKIP: "skip";
+};
+export type AgentAction = (typeof AgentAction)[keyof typeof AgentAction];
+/** Per-platform relative paths, from the user's home directory. */
+export interface PlatformPaths {
+    readonly darwin: string;
+    readonly linux: string;
+    readonly win32: string;
+}
+export interface AgentClient {
+    readonly id: string;
+    readonly name: string;
+    readonly confidence: AgentConfidence;
+    /** `json` merges; `yaml-manual` is only ever created fresh, never edited. */
+    readonly format: 'json' | 'yaml-manual';
+    /** Where the server map lives. Getting this wrong writes a file the client silently ignores. */
+    readonly key: string;
+    readonly entry?: Readonly<Record<string, unknown>> | undefined;
+    readonly paths: PlatformPaths;
+    /** Existence proves the agent is installed. */
+    readonly marker: PlatformPaths;
+    /** The HOST's directory, when the marker belongs to an extension rather than the app. */
+    readonly parentMarker?: PlatformPaths | undefined;
+    /** Where this agent loads reusable skills from, when it has such a place. */
+    readonly skillDir?: string | undefined;
+}
+export declare const AGENT_CLIENTS: readonly AgentClient[];
+/** What to do for one client, decided without touching the disk. */
+export interface AgentPlanStep {
+    readonly id: string;
+    readonly name: string;
+    readonly file: string;
+    readonly action: AgentAction;
+    readonly key?: string | undefined;
+    readonly entry?: Readonly<Record<string, unknown>> | undefined;
+    readonly why: string;
+}
+export interface AgentPlanInput {
+    readonly home: string;
+    readonly platform: keyof PlatformPaths;
+    readonly exists: (path: string) => boolean;
+    readonly readFile: (path: string) => string;
+}
+/**
+ * Join for the platform the CALLER named, never the one this process happens to run on.
+ *
+ * Every planner here takes `platform` as an argument and claims to be pure over it — the doc below
+ * says the Windows rows are "testable from any machine". `node:path`'s bare `join` broke that claim
+ * silently in both directions: a mac planning win32 rows emitted `/` separators into paths Windows
+ * cannot use, and a Windows host planning linux rows emitted `\`. The second half is what turned
+ * the whole Windows CI job red — the pure planners returned `\home\u\.claude\settings.json`,
+ * every injected filesystem is keyed by the POSIX path the caller asked for, so every lookup missed
+ * and every row came back `absent`/`skip`. Twenty-eight tests failed for a reason that had nothing
+ * to do with what they were testing, which left the platform with the most users unwatched.
+ *
+ * A separator is part of the answer, so it belongs to the platform being planned for.
+ */
+export declare const joinFor: (os: keyof PlatformPaths) => ((...parts: string[]) => string);
+/**
+ * Decide what to do for every client. Pure: the filesystem arrives as two functions, which is what
+ * makes the Windows rows testable from any machine.
+ */
+export declare function planAgentConfigs(input: AgentPlanInput): AgentPlanStep[];

package/dist/setup/agent-configs.js

@@ -0,0 +1,333 @@
+/**
+ * The coding agents `init`'s own MCP registration does not reach, and where their config lives.
+ *
+ * `init` covers eight clients and only where it already finds them. That leaves real holes: VS
+ * Code's USER-scope mcp.json exists on machines today and init only ever writes the project-scope
+ * one, so a VS Code user has no tools outside the directory they ran init in. Zed, Warp, Kiro, Amp,
+ * Copilot CLI, Amazon Q, Factory Droid, Cline and Roo are not covered at all.
+ *
+ * Three rules, and the second is what keeps this honest:
+ *
+ * 1. A path with OFFICIAL documentation is written even when the agent is absent, so a later
+ *    install finds itself already wired.
+ * 2. A path we cannot evidence is REFUSED. Cline's and Roo's live under VS Code globalStorage,
+ *    which moves under Insiders, portable installs and a custom --user-data-dir; they are written
+ *    only where the host's standard layout is present. A config file at a guessed location is one
+ *    nobody reads, which is indistinguishable from success.
+ * 3. A format we cannot merge safely is never rewritten. TOML, an existing YAML, JSONC carrying
+ *    comments: we print the snippet instead. Reformatting somebody's config to add one entry is
+ *    not ours to do.
+ */
+import { posix, win32 } from 'node:path';
+export const AgentConfidence = {
+    /** Documented by the vendor. Safe to create before the agent exists. */
+    OFFICIAL: 'official',
+    /** Community-sourced. Only written where the host's own layout proves the path. */
+    COMMUNITY: 'community',
+};
+export const AgentAction = {
+    CREATE: 'create',
+    CREATE_YAML: 'create-yaml',
+    MERGE: 'merge',
+    ALREADY: 'already',
+    MANUAL: 'manual',
+    SKIP: 'skip',
+};
+const NPX = 'npx';
+const SERVER_PACKAGE = '@reticlehq/server';
+const MCP_SUBCOMMAND = 'mcp';
+const RETICLE_KEY = 'reticle';
+/** The stdio entry, in the shape most clients expect. */
+const STDIO = { command: NPX, args: [SERVER_PACKAGE, MCP_SUBCOMMAND] };
+const VSCODE_USER = {
+    darwin: 'Library/Application Support/Code/User',
+    linux: '.config/Code/User',
+    win32: 'AppData/Roaming/Code/User',
+};
+export const AGENT_CLIENTS = [
+    {
+        id: 'vscode-user',
+        name: 'VS Code (user scope)',
+        confidence: AgentConfidence.OFFICIAL,
+        format: 'json',
+        key: 'servers',
+        entry: { type: 'stdio', ...STDIO },
+        paths: {
+            darwin: `${VSCODE_USER.darwin}/mcp.json`,
+            linux: `${VSCODE_USER.linux}/mcp.json`,
+            win32: `${VSCODE_USER.win32}/mcp.json`,
+        },
+        marker: VSCODE_USER,
+    },
+    {
+        id: 'zed',
+        name: 'Zed',
+        confidence: AgentConfidence.OFFICIAL,
+        format: 'json',
+        // NOT `mcpServers`. Zed calls them context servers, and the wrong key writes a file it ignores.
+        key: 'context_servers',
+        entry: { ...STDIO, env: {} },
+        paths: {
+            darwin: '.config/zed/settings.json',
+            linux: '.config/zed/settings.json',
+            win32: 'AppData/Roaming/Zed/settings.json',
+        },
+        marker: { darwin: '.config/zed', linux: '.config/zed', win32: 'AppData/Roaming/Zed' },
+        skillDir: '.agents/skills/reticle',
+    },
+    {
+        id: 'copilot-cli',
+        name: 'GitHub Copilot CLI',
+        confidence: AgentConfidence.OFFICIAL,
+        format: 'json',
+        key: 'mcpServers',
+        entry: STDIO,
+        paths: {
+            darwin: '.copilot/mcp-config.json',
+            linux: '.copilot/mcp-config.json',
+            win32: '.copilot/mcp-config.json',
+        },
+        marker: { darwin: '.copilot', linux: '.copilot', win32: '.copilot' },
+    },
+    {
+        id: 'warp',
+        name: 'Warp',
+        confidence: AgentConfidence.OFFICIAL,
+        format: 'json',
+        key: 'mcpServers',
+        entry: STDIO,
+        paths: { darwin: '.warp/.mcp.json', linux: '.warp/.mcp.json', win32: '.warp/.mcp.json' },
+        marker: { darwin: '.warp', linux: '.warp', win32: '.warp' },
+    },
+    {
+        id: 'factory-droid',
+        name: 'Factory Droid',
+        confidence: AgentConfidence.OFFICIAL,
+        format: 'json',
+        key: 'mcpServers',
+        entry: { type: 'stdio', ...STDIO },
+        paths: { darwin: '.factory/mcp.json', linux: '.factory/mcp.json', win32: '.factory/mcp.json' },
+        marker: { darwin: '.factory', linux: '.factory', win32: '.factory' },
+    },
+    {
+        id: 'kiro',
+        name: 'Kiro',
+        confidence: AgentConfidence.OFFICIAL,
+        format: 'json',
+        key: 'mcpServers',
+        entry: STDIO,
+        paths: {
+            darwin: '.kiro/settings/mcp.json',
+            linux: '.kiro/settings/mcp.json',
+            win32: '.kiro/settings/mcp.json',
+        },
+        marker: { darwin: '.kiro', linux: '.kiro', win32: '.kiro' },
+        skillDir: '.kiro/steering',
+    },
+    {
+        id: 'amazon-q',
+        name: 'Amazon Q Developer CLI',
+        confidence: AgentConfidence.OFFICIAL,
+        format: 'json',
+        key: 'mcpServers',
+        entry: STDIO,
+        paths: {
+            darwin: '.aws/amazonq/mcp.json',
+            linux: '.aws/amazonq/mcp.json',
+            win32: '.aws/amazonq/mcp.json',
+        },
+        marker: { darwin: '.aws/amazonq', linux: '.aws/amazonq', win32: '.aws/amazonq' },
+    },
+    {
+        id: 'cline-cli',
+        name: 'Cline CLI',
+        confidence: AgentConfidence.OFFICIAL,
+        format: 'json',
+        key: 'mcpServers',
+        entry: STDIO,
+        paths: { darwin: '.cline/mcp.json', linux: '.cline/mcp.json', win32: '.cline/mcp.json' },
+        marker: { darwin: '.cline', linux: '.cline', win32: '.cline' },
+    },
+    {
+        id: 'amp',
+        name: 'Amp',
+        confidence: AgentConfidence.OFFICIAL,
+        format: 'json',
+        // A DOTTED key at the TOP level, not nested under "amp". Nesting writes a file Amp ignores.
+        key: 'amp.mcpServers',
+        entry: STDIO,
+        paths: {
+            darwin: '.config/amp/settings.json',
+            linux: '.config/amp/settings.json',
+            win32: '.config/amp/settings.json',
+        },
+        marker: { darwin: '.config/amp', linux: '.config/amp', win32: '.config/amp' },
+    },
+    {
+        id: 'cline',
+        name: 'Cline (VS Code extension)',
+        confidence: AgentConfidence.COMMUNITY,
+        format: 'json',
+        key: 'mcpServers',
+        entry: STDIO,
+        paths: {
+            darwin: `${VSCODE_USER.darwin}/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`,
+            linux: `${VSCODE_USER.linux}/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`,
+            win32: `${VSCODE_USER.win32}/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`,
+        },
+        marker: {
+            darwin: `${VSCODE_USER.darwin}/globalStorage/saoudrizwan.claude-dev`,
+            linux: `${VSCODE_USER.linux}/globalStorage/saoudrizwan.claude-dev`,
+            win32: `${VSCODE_USER.win32}/globalStorage/saoudrizwan.claude-dev`,
+        },
+        parentMarker: VSCODE_USER,
+    },
+    {
+        id: 'roo-code',
+        name: 'Roo Code',
+        confidence: AgentConfidence.COMMUNITY,
+        format: 'json',
+        key: 'mcpServers',
+        entry: STDIO,
+        paths: {
+            darwin: `${VSCODE_USER.darwin}/globalStorage/rooveterinaryinc.roo-cline/settings/mcp_settings.json`,
+            linux: `${VSCODE_USER.linux}/globalStorage/rooveterinaryinc.roo-cline/settings/mcp_settings.json`,
+            win32: `${VSCODE_USER.win32}/globalStorage/rooveterinaryinc.roo-cline/settings/mcp_settings.json`,
+        },
+        marker: {
+            darwin: `${VSCODE_USER.darwin}/globalStorage/rooveterinaryinc.roo-cline`,
+            linux: `${VSCODE_USER.linux}/globalStorage/rooveterinaryinc.roo-cline`,
+            win32: `${VSCODE_USER.win32}/globalStorage/rooveterinaryinc.roo-cline`,
+        },
+        parentMarker: VSCODE_USER,
+    },
+    {
+        id: 'continue',
+        name: 'Continue',
+        confidence: AgentConfidence.OFFICIAL,
+        // YAML, whose `mcpServers` is a LIST of named entries. We create one; we never rewrite one.
+        format: 'yaml-manual',
+        key: 'mcpServers',
+        paths: {
+            darwin: '.continue/config.yaml',
+            linux: '.continue/config.yaml',
+            win32: '.continue/config.yaml',
+        },
+        marker: { darwin: '.continue', linux: '.continue', win32: '.continue' },
+    },
+];
+const forPlatform = (p, os) => p[os];
+/**
+ * Join for the platform the CALLER named, never the one this process happens to run on.
+ *
+ * Every planner here takes `platform` as an argument and claims to be pure over it — the doc below
+ * says the Windows rows are "testable from any machine". `node:path`'s bare `join` broke that claim
+ * silently in both directions: a mac planning win32 rows emitted `/` separators into paths Windows
+ * cannot use, and a Windows host planning linux rows emitted `\`. The second half is what turned
+ * the whole Windows CI job red — the pure planners returned `\home\u\.claude\settings.json`,
+ * every injected filesystem is keyed by the POSIX path the caller asked for, so every lookup missed
+ * and every row came back `absent`/`skip`. Twenty-eight tests failed for a reason that had nothing
+ * to do with what they were testing, which left the platform with the most users unwatched.
+ *
+ * A separator is part of the answer, so it belongs to the platform being planned for.
+ */
+export const joinFor = (os) => 'win32' === os ? win32.join : posix.join;
+/**
+ * Decide what to do for every client. Pure: the filesystem arrives as two functions, which is what
+ * makes the Windows rows testable from any machine.
+ */
+export function planAgentConfigs(input) {
+    const { home, platform, exists, readFile } = input;
+    return AGENT_CLIENTS.map((c) => {
+        const join = joinFor(platform);
+        const file = join(home, forPlatform(c.paths, platform));
+        const detected = exists(join(home, forPlatform(c.marker, platform)));
+        // A NEW yaml file has nobody's formatting to destroy. An existing one does: `mcpServers` there
+        // is a list of named entries, and a naive rewrite loses comments, anchors and ordering.
+        if ('yaml-manual' === c.format) {
+            return exists(file)
+                ? {
+                    id: c.id,
+                    name: c.name,
+                    file,
+                    action: AgentAction.MANUAL,
+                    why: 'its config is YAML and already exists, so rewriting it would lose comments and ordering',
+                }
+                : {
+                    id: c.id,
+                    name: c.name,
+                    file,
+                    action: AgentAction.CREATE_YAML,
+                    why: 'no config yet, so a valid one can be written outright',
+                };
+        }
+        const layoutKnown = c.parentMarker !== undefined && exists(join(home, forPlatform(c.parentMarker, platform)));
+        if (!detected && c.confidence === AgentConfidence.COMMUNITY && !layoutKnown) {
+            return {
+                id: c.id,
+                name: c.name,
+                file,
+                action: AgentAction.SKIP,
+                why: "not installed, and without its host's standard layout on this machine its path is a guess: a guessed path creates a file nobody reads",
+            };
+        }
+        if (!exists(file)) {
+            return {
+                id: c.id,
+                name: c.name,
+                file,
+                action: AgentAction.CREATE,
+                key: c.key,
+                entry: c.entry,
+                why: detected
+                    ? 'installed, with no config yet'
+                    : 'a documented path, so a later install finds it already wired',
+            };
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(readFile(file));
+        }
+        catch {
+            parsed = undefined;
+        }
+        if ('object' !== typeof parsed || null === parsed) {
+            return {
+                id: c.id,
+                name: c.name,
+                file,
+                action: AgentAction.MANUAL,
+                key: c.key,
+                entry: c.entry,
+                why: "the existing config is not plain JSON (comments or trailing commas), and rewriting it would reformat somebody else's file",
+            };
+        }
+        const bucket = parsed[c.key];
+        const existing = 'object' === typeof bucket && null !== bucket
+            ? bucket[RETICLE_KEY]
+            : undefined;
+        if (existing !== undefined) {
+            const ours = JSON.stringify(existing) === JSON.stringify(c.entry);
+            return {
+                id: c.id,
+                name: c.name,
+                file,
+                action: ours ? AgentAction.ALREADY : AgentAction.MANUAL,
+                key: c.key,
+                entry: c.entry,
+                why: ours
+                    ? 'already registered'
+                    : 'a different `reticle` entry is there, and it is not ours to replace',
+            };
+        }
+        return {
+            id: c.id,
+            name: c.name,
+            file,
+            action: AgentAction.MERGE,
+            key: c.key,
+            entry: c.entry,
+            why: 'adding our key beside the servers already there',
+        };
+    });
+}

package/dist/setup/agent-io.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The real filesystem, in the shape the agent writer and the approval grants expect.
+ *
+ * Its own module so the MCP server can reach it without importing `setup-command`, which would pull
+ * the whole drive machinery — child processes, dev-server supervision, page probing — into the
+ * startup path of the one process whose latency a user experiences as "Reticle is slow to connect".
+ */
+import type { AgentWriterIo } from './agent-writer.js';
+export declare const agentIo: AgentWriterIo;

package/dist/setup/agent-io.js

@@ -0,0 +1,16 @@
+/**
+ * The real filesystem, in the shape the agent writer and the approval grants expect.
+ *
+ * Its own module so the MCP server can reach it without importing `setup-command`, which would pull
+ * the whole drive machinery — child processes, dev-server supervision, page probing — into the
+ * startup path of the one process whose latency a user experiences as "Reticle is slow to connect".
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+export const agentIo = {
+    exists: (path) => existsSync(path),
+    readFile: (path) => readFileSync(path, 'utf8'),
+    writeFile: (path, contents) => writeFileSync(path, contents),
+    mkdirp: (dir) => {
+        mkdirSync(dir, { recursive: true });
+    },
+};