@reticlehq/server 2.11.0 → 2.13.0

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 });
+    },
+};

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

@@ -0,0 +1,51 @@
+/**
+ * Carrying out an agent-config plan.
+ *
+ * The plan decides; this writes. Kept apart because the deciding is where the judgement is — which
+ * paths are evidenced, which formats are safe to touch — and it is worth testing against a pretend
+ * filesystem rather than a real one.
+ *
+ * One rule governs everything here: only our key is ever written. The rest of somebody's config is
+ * copied through untouched, and a file we cannot parse is left exactly as it is. A config file is
+ * not ours, and the cost of being wrong about that is not a failed install but a broken editor.
+ */
+import { AgentAction, type AgentPlanStep, type PlatformPaths } from './agent-configs.js';
+/** The filesystem, injected so the writer is testable without one. */
+export interface AgentWriterIo {
+    readonly exists: (path: string) => boolean;
+    readonly readFile: (path: string) => string;
+    readonly writeFile: (path: string, contents: string) => void;
+    readonly mkdirp: (dir: string) => void;
+}
+export interface AgentWriteResult {
+    readonly id: string;
+    readonly name: string;
+    readonly file: string;
+    /** What actually happened, which is not always what was planned. */
+    readonly action: AgentAction | 'created' | 'merged';
+    readonly why: string;
+}
+/**
+ * Write what the plan says to write, and nothing else.
+ *
+ * A step that fails becomes a `manual` result rather than an exception: one unwritable config on a
+ * machine with a dozen agents is not a reason to abandon the other eleven, and the user needs to be
+ * told which one to do by hand.
+ */
+export declare function applyAgentPlan(plan: readonly AgentPlanStep[], io: AgentWriterIo): AgentWriteResult[];
+/** The `/reticle` instruction, for agents that load skills from a directory. */
+export declare const RETICLE_SKILL = "---\nname: reticle\ndescription: Verify a change against the running app, from inside it, before calling it done.\n---\n\nReticle exposes the running app to you as `reticle_*` MCP tools. Look, act, observe, assert.\n\nOnly `reticle_act_and_wait` and `reticle_assert` produce a verdict. Everything else moves or\nreads the app and proves nothing, so a drive that ends without one of those has no result however\nmany tools it used.\n\n`verified: \"unknown\"` is not a pass: it means Reticle could not tell what happened.\n`verified: \"no-fault\"` is not a pass either, because nothing was declared to prove. Never weaken a\ncheck to make it pass.\n\nThe cheapest path that answers the question:\n\n- \"did my edit break anything?\" -> `reticle_run({ tool: \"reticle_verify\", args: { action: \"change\", files: [...] } })`\n- \"does this known journey still work?\" -> `reticle_run({ tool: \"reticle_flow_replay\", args: { flowName: \"...\" } })`\n- \"does this new behaviour work?\" -> `reticle_act_sequence` for the setup, then ONE `reticle_act_and_wait`\n";
+export interface SkillWriteResult {
+    readonly id: string;
+    readonly file: string;
+}
+/**
+ * Write the skill for agents that have somewhere to put it, and only where they are installed.
+ *
+ * Scaffolding a skills tree for software somebody does not have is litter, and unlike a config file
+ * it is not even inert: it is a directory that appears in their home for no reason they can trace.
+ */
+export declare function applyAgentSkills(io: AgentWriterIo, where: {
+    readonly home: string;
+    readonly platform: keyof PlatformPaths;
+}): SkillWriteResult[];

package/dist/setup/agent-writer.js

@@ -0,0 +1,115 @@
+/**
+ * Carrying out an agent-config plan.
+ *
+ * The plan decides; this writes. Kept apart because the deciding is where the judgement is — which
+ * paths are evidenced, which formats are safe to touch — and it is worth testing against a pretend
+ * filesystem rather than a real one.
+ *
+ * One rule governs everything here: only our key is ever written. The rest of somebody's config is
+ * copied through untouched, and a file we cannot parse is left exactly as it is. A config file is
+ * not ours, and the cost of being wrong about that is not a failed install but a broken editor.
+ */
+import { AgentAction, AGENT_CLIENTS, joinFor, } from './agent-configs.js';
+/** Two spaces, because that is what every one of these files already uses. */
+const INDENT = 2;
+const RETICLE_KEY = 'reticle';
+/** A fresh Continue config. YAML is only ever created, never edited. */
+const CONTINUE_YAML = 'mcpServers:\n  - name: reticle\n    type: stdio\n    command: npx\n    args: ["@reticlehq/server", "mcp"]\n';
+const parentOf = (path) => path.slice(0, Math.max(0, path.lastIndexOf('/')));
+/**
+ * Write what the plan says to write, and nothing else.
+ *
+ * A step that fails becomes a `manual` result rather than an exception: one unwritable config on a
+ * machine with a dozen agents is not a reason to abandon the other eleven, and the user needs to be
+ * told which one to do by hand.
+ */
+export function applyAgentPlan(plan, io) {
+    return plan.map((step) => {
+        const base = { id: step.id, name: step.name, file: step.file, why: step.why };
+        if (AgentAction.SKIP === step.action ||
+            AgentAction.ALREADY === step.action ||
+            AgentAction.MANUAL === step.action) {
+            return { ...base, action: step.action };
+        }
+        try {
+            io.mkdirp(parentOf(step.file));
+            if (AgentAction.CREATE_YAML === step.action) {
+                io.writeFile(step.file, CONTINUE_YAML);
+                return { ...base, action: 'created' };
+            }
+            const key = step.key;
+            if (undefined === key || undefined === step.entry) {
+                return {
+                    ...base,
+                    action: AgentAction.MANUAL,
+                    why: 'the plan named no key or entry to write',
+                };
+            }
+            // Only our key. Everything else in the file is read and written back untouched.
+            const current = AgentAction.MERGE === step.action
+                ? JSON.parse(io.readFile(step.file))
+                : {};
+            const bucket = current[key];
+            const servers = 'object' === typeof bucket && null !== bucket ? bucket : {};
+            const next = { ...current, [key]: { ...servers, [RETICLE_KEY]: step.entry } };
+            io.writeFile(step.file, `${JSON.stringify(next, null, INDENT)}\n`);
+            return { ...base, action: AgentAction.MERGE === step.action ? 'merged' : 'created' };
+        }
+        catch (err) {
+            return {
+                ...base,
+                action: AgentAction.MANUAL,
+                why: `could not write it (${String(err?.message ?? err).slice(0, 120)})`,
+            };
+        }
+    });
+}
+/** The `/reticle` instruction, for agents that load skills from a directory. */
+export const RETICLE_SKILL = `---
+name: reticle
+description: Verify a change against the running app, from inside it, before calling it done.
+---
+
+Reticle exposes the running app to you as \`reticle_*\` MCP tools. Look, act, observe, assert.
+
+Only \`reticle_act_and_wait\` and \`reticle_assert\` produce a verdict. Everything else moves or
+reads the app and proves nothing, so a drive that ends without one of those has no result however
+many tools it used.
+
+\`verified: "unknown"\` is not a pass: it means Reticle could not tell what happened.
+\`verified: "no-fault"\` is not a pass either, because nothing was declared to prove. Never weaken a
+check to make it pass.
+
+The cheapest path that answers the question:
+
+- "did my edit break anything?" -> \`reticle_run({ tool: "reticle_verify", args: { action: "change", files: [...] } })\`
+- "does this known journey still work?" -> \`reticle_run({ tool: "reticle_flow_replay", args: { flowName: "..." } })\`
+- "does this new behaviour work?" -> \`reticle_act_sequence\` for the setup, then ONE \`reticle_act_and_wait\`
+`;
+/**
+ * Write the skill for agents that have somewhere to put it, and only where they are installed.
+ *
+ * Scaffolding a skills tree for software somebody does not have is litter, and unlike a config file
+ * it is not even inert: it is a directory that appears in their home for no reason they can trace.
+ */
+export function applyAgentSkills(io, where) {
+    const written = [];
+    const join = joinFor(where.platform);
+    for (const client of AGENT_CLIENTS) {
+        const dir = client.skillDir;
+        if (undefined === dir)
+            continue;
+        if (!io.exists(join(where.home, client.marker[where.platform])))
+            continue;
+        try {
+            const target = join(where.home, dir);
+            io.mkdirp(target);
+            io.writeFile(join(target, 'SKILL.md'), RETICLE_SKILL);
+            written.push({ id: client.id, file: join(target, 'SKILL.md') });
+        }
+        catch {
+            /* an unwritable home directory is not a reason to fail an install */
+        }
+    }
+    return written;
+}

package/dist/setup/approval-migration.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Carrying the pre-approval rules onto a machine that installed Reticle before they existed.
+ *
+ * The alternative was a command the user has to know to type. Nothing reaches back into an existing
+ * install, so `init --files-only` is a real upgrade path but only for somebody who reads a
+ * changelog; everyone else keeps clicking Accept on every call forever, which is precisely the
+ * thing this was supposed to end.
+ *
+ * So it runs from `reticle mcp` — the one process every client starts, every session, on the
+ * version they actually have. Four properties make that safe to do unattended:
+ *
+ * 1. **Once per version.** A stamp in the state dir, so it is not a write on every editor launch.
+ * 2. **Only where an agent is installed**, and only ever the `reticle` server.
+ * 3. **Never a create that supersedes an allowlist we cannot read.** Cursor's file is deferred to an
+ *    explicit `init` when it does not already exist: a version bump that silently makes somebody's
+ *    OTHER MCP servers start prompting again is a regression we caused and they cannot trace.
+ * 4. **Never throws, never writes to stdout.** This runs inside a stdio MCP server, where a stray
+ *    byte on stdout corrupts the protocol, and where a crash is experienced as "Reticle is down".
+ * 5. **Never runs against a sandboxed state directory.** A gate or a fixture that points Reticle at
+ *    a temp state dir is not asking to have the real user's editor config rewritten, and every
+ *    battery in this repo starts MCP servers. The one write in this repo that reached a developer's
+ *    own home did so from a gate run, which is exactly the shape this rules out.
+ */
+import type { AgentWriterIo } from './agent-writer.js';
+import { type PlatformPaths } from './agent-configs.js';
+export declare const APPROVAL_STAMP_FILE = "approvals.json";
+export interface MigrationDeps {
+    readonly io: AgentWriterIo;
+    readonly home: string;
+    readonly platform: keyof PlatformPaths;
+    /** The state directory, which is where the once-per-version stamp lives. */
+    readonly stateHome: string;
+    readonly version: string;
+    readonly log: (event: string, data: Record<string, unknown>) => void;
+}
+export interface MigrationResult {
+    readonly ran: boolean;
+    readonly granted: readonly string[];
+    readonly deferred: readonly string[];
+}
+/**
+ * Apply the approval rules once for this version, and record that it happened.
+ *
+ * The stamp is written even when nothing was granted. A machine with no agents installed should not
+ * re-scan on every editor launch for the rest of the version's life.
+ */
+export declare function migrateApprovals(deps: MigrationDeps): MigrationResult;

package/dist/setup/approval-migration.js

@@ -0,0 +1,68 @@
+/**
+ * Carrying the pre-approval rules onto a machine that installed Reticle before they existed.
+ *
+ * The alternative was a command the user has to know to type. Nothing reaches back into an existing
+ * install, so `init --files-only` is a real upgrade path but only for somebody who reads a
+ * changelog; everyone else keeps clicking Accept on every call forever, which is precisely the
+ * thing this was supposed to end.
+ *
+ * So it runs from `reticle mcp` — the one process every client starts, every session, on the
+ * version they actually have. Four properties make that safe to do unattended:
+ *
+ * 1. **Once per version.** A stamp in the state dir, so it is not a write on every editor launch.
+ * 2. **Only where an agent is installed**, and only ever the `reticle` server.
+ * 3. **Never a create that supersedes an allowlist we cannot read.** Cursor's file is deferred to an
+ *    explicit `init` when it does not already exist: a version bump that silently makes somebody's
+ *    OTHER MCP servers start prompting again is a regression we caused and they cannot trace.
+ * 4. **Never throws, never writes to stdout.** This runs inside a stdio MCP server, where a stray
+ *    byte on stdout corrupts the protocol, and where a crash is experienced as "Reticle is down".
+ * 5. **Never runs against a sandboxed state directory.** A gate or a fixture that points Reticle at
+ *    a temp state dir is not asking to have the real user's editor config rewritten, and every
+ *    battery in this repo starts MCP servers. The one write in this repo that reached a developer's
+ *    own home did so from a gate run, which is exactly the shape this rules out.
+ */
+import { grantAutoApproval, ApprovalOutcome } from './auto-approve.js';
+import { joinFor } from './agent-configs.js';
+export const APPROVAL_STAMP_FILE = 'approvals.json';
+const NOTHING = { ran: false, granted: [], deferred: [] };
+/**
+ * Apply the approval rules once for this version, and record that it happened.
+ *
+ * The stamp is written even when nothing was granted. A machine with no agents installed should not
+ * re-scan on every editor launch for the rest of the version's life.
+ */
+export function migrateApprovals(deps) {
+    const { io, home, platform, stateHome, version, log } = deps;
+    const stamp = joinFor(platform)(stateHome, APPROVAL_STAMP_FILE);
+    try {
+        if (io.exists(stamp)) {
+            const seen = JSON.parse(io.readFile(stamp));
+            if (version === seen.version)
+                return NOTHING;
+        }
+    }
+    catch {
+        // An unreadable stamp means we do not know what has run, and the grants below are idempotent,
+        // so the safe reading is "not yet" rather than skipping the migration forever.
+    }
+    let results = [];
+    try {
+        results = grantAutoApproval(io, { home, platform }, undefined, { onlyIfNoSupersede: true });
+    }
+    catch {
+        return NOTHING;
+    }
+    const granted = results.filter((r) => ApprovalOutcome.GRANTED === r.outcome).map((r) => r.name);
+    const deferred = results.filter((r) => ApprovalOutcome.DEFERRED === r.outcome).map((r) => r.name);
+    try {
+        io.mkdirp(stateHome);
+        io.writeFile(stamp, `${JSON.stringify({ version }, null, 2)}\n`);
+    }
+    catch {
+        // A stamp we could not write means this runs again next launch. Wasteful, not harmful.
+    }
+    if (0 < granted.length || 0 < deferred.length) {
+        log('reticle_approvals_migrated', { version, granted, deferred });
+    }
+    return { ran: true, granted, deferred };
+}