@reticlehq/server 2.12.0 → 2.13.1

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

package/dist/setup/auto-approve.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Removing the Accept button, for the tools Reticle owns and nothing else.
+ *
+ * A drive that stops on a per-call approval dialog is not automated, and the dialog is per CALL:
+ * a single verification run makes dozens, so a human sits there clicking through a loop that was
+ * supposed to run without them. Every client below documents a way to pre-approve a named server,
+ * and this writes exactly that rule, at install time, in the client's own spelling.
+ *
+ * Two limits, both deliberate:
+ *
+ * 1. ONLY `reticle` is allowed. Not `mcp(*)`, not a global auto-run switch. Reticle's tools drive
+ *    the user's own dev server on their own machine, which is what makes pre-approving them
+ *    defensible; the same edit made globally would hand the same pass to every other MCP server
+ *    they ever install, including ones that reach the network. Their approval gate is not ours to
+ *    dismantle, only ours to step out of.
+ * 2. Nothing is written for an agent that is not installed. An absent agent has no Accept button to
+ *    remove, and the file would be litter — Cursor's especially, since that one TAKES OVER from an
+ *    allowlist we cannot read.
+ *
+ * Codex is absent by design: its approval policy is global (`approval_policy`), so there is no
+ * reticle-shaped rule to write, and its config is TOML, which this repo never rewrites. Its
+ * headless form, `codex exec`, does not prompt at all — which is the form the drive uses.
+ */
+import { type PlatformPaths } from './agent-configs.js';
+import type { AgentWriterIo } from './agent-writer.js';
+/** A documented way to pre-approve one MCP server, in one client's own spelling. */
+export interface ApprovalGrant {
+    readonly id: string;
+    readonly name: string;
+    /** Home-relative, per platform. */
+    readonly paths: PlatformPaths;
+    /** Present if ANY of these exist. An agent that is not installed is not configured. */
+    readonly markers: readonly PlatformPaths[];
+    /** The rule, in the client's words, for the plan output. */
+    readonly rule: string;
+    /** Adds our rule to a parsed config, leaving everything else exactly as it was. */
+    readonly grant: (current: Record<string, unknown>) => Record<string, unknown>;
+    /**
+     * True where creating this file supersedes an in-app allowlist we cannot read, so the user has to
+     * be told rather than have their other servers quietly start prompting again.
+     */
+    readonly supersedesInApp?: boolean;
+}
+export declare const APPROVAL_GRANTS: readonly ApprovalGrant[];
+export declare const ApprovalOutcome: {
+    readonly GRANTED: "granted";
+    readonly ALREADY: "already";
+    readonly ABSENT: "absent";
+    /** Deliberately left for an explicit run, because doing it unattended costs the user something. */
+    readonly DEFERRED: "deferred";
+    readonly FAILED: "failed";
+};
+export type ApprovalOutcome = (typeof ApprovalOutcome)[keyof typeof ApprovalOutcome];
+export interface ApprovalResult {
+    readonly id: string;
+    readonly name: string;
+    readonly file: string;
+    readonly outcome: ApprovalOutcome;
+    readonly rule: string;
+    /** Set where the user has to be told something the write alone does not say. */
+    readonly warn?: string;
+}
+export interface ApprovalWhere {
+    readonly home: string;
+    readonly platform: keyof PlatformPaths;
+}
+export interface ApprovalOptions {
+    /**
+     * Refuse any grant that would CREATE a file superseding an allowlist we cannot read.
+     *
+     * Set on the unattended path. Writing Cursor's permissions.json for the first time takes over
+     * from what the user approved inside the app, which is a fair trade when they just ran a command
+     * and can read the line saying so, and not a fair trade at all when a version bump did it behind
+     * them: their OTHER MCP servers would start prompting again and nothing would connect that to us.
+     * Merging into a file they already own stays safe either way.
+     */
+    readonly onlyIfNoSupersede?: boolean;
+}
+/**
+ * Pre-approve Reticle's tools everywhere the machine has an agent that would otherwise ask.
+ *
+ * A client that cannot be written is reported, never thrown: one unwritable settings file is not a
+ * reason to leave the other three prompting.
+ */
+export declare function grantAutoApproval(io: AgentWriterIo, where: ApprovalWhere, grants?: readonly ApprovalGrant[], options?: ApprovalOptions): ApprovalResult[];

package/dist/setup/auto-approve.js

@@ -0,0 +1,150 @@
+/**
+ * Removing the Accept button, for the tools Reticle owns and nothing else.
+ *
+ * A drive that stops on a per-call approval dialog is not automated, and the dialog is per CALL:
+ * a single verification run makes dozens, so a human sits there clicking through a loop that was
+ * supposed to run without them. Every client below documents a way to pre-approve a named server,
+ * and this writes exactly that rule, at install time, in the client's own spelling.
+ *
+ * Two limits, both deliberate:
+ *
+ * 1. ONLY `reticle` is allowed. Not `mcp(*)`, not a global auto-run switch. Reticle's tools drive
+ *    the user's own dev server on their own machine, which is what makes pre-approving them
+ *    defensible; the same edit made globally would hand the same pass to every other MCP server
+ *    they ever install, including ones that reach the network. Their approval gate is not ours to
+ *    dismantle, only ours to step out of.
+ * 2. Nothing is written for an agent that is not installed. An absent agent has no Accept button to
+ *    remove, and the file would be litter — Cursor's especially, since that one TAKES OVER from an
+ *    allowlist we cannot read.
+ *
+ * Codex is absent by design: its approval policy is global (`approval_policy`), so there is no
+ * reticle-shaped rule to write, and its config is TOML, which this repo never rewrites. Its
+ * headless form, `codex exec`, does not prompt at all — which is the form the drive uses.
+ */
+import { joinFor } from './agent-configs.js';
+const RETICLE_KEY = 'reticle';
+const INDENT = 2;
+const home = (path) => ({ darwin: path, linux: path, win32: path });
+/** Append to a nested array, without duplicating and without disturbing what is already in it. */
+function addToList(current, outer, key, value) {
+    const scope = null === outer
+        ? current
+        : 'object' === typeof current[outer] && null !== current[outer]
+            ? { ...current[outer] }
+            : {};
+    const list = Array.isArray(scope[key]) ? scope[key] : [];
+    if (list.includes(value))
+        return current;
+    const next = { ...scope, [key]: [...list, value] };
+    return null === outer ? next : { ...current, [outer]: next };
+}
+export const APPROVAL_GRANTS = [
+    {
+        id: 'claude-code',
+        name: 'Claude Code',
+        paths: home('.claude/settings.json'),
+        markers: [home('.claude')],
+        rule: 'permissions.allow += "mcp__reticle"',
+        grant: (c) => addToList(c, 'permissions', 'allow', 'mcp__reticle'),
+    },
+    {
+        id: 'cursor',
+        name: 'Cursor',
+        paths: home('.cursor/permissions.json'),
+        markers: [home('.cursor')],
+        rule: 'mcpAllowlist += "reticle:*"',
+        // Documented: "when a key appears in permissions.json, it fully replaces the in-app allowlist
+        // for that type". Merging keeps everything already in the FILE; it cannot restore what was only
+        // ever clicked in the UI, so the user is told.
+        supersedesInApp: true,
+        grant: (c) => addToList(c, null, 'mcpAllowlist', `${RETICLE_KEY}:*`),
+    },
+    {
+        id: 'antigravity',
+        name: 'Antigravity',
+        paths: home('.gemini/antigravity-cli/settings.json'),
+        markers: [
+            {
+                darwin: 'Library/Application Support/Antigravity',
+                linux: '.config/Antigravity',
+                win32: 'AppData/Roaming/Antigravity',
+            },
+            home('.gemini/antigravity-cli'),
+        ],
+        rule: 'permissions.allow += "mcp(reticle/*)"',
+        grant: (c) => addToList(c, 'permissions', 'allow', `mcp(${RETICLE_KEY}/*)`),
+    },
+    {
+        id: 'gemini-cli',
+        name: 'Gemini CLI',
+        paths: home('.gemini/settings.json'),
+        markers: [home('.gemini')],
+        rule: 'mcpServers.reticle.trust = true',
+        // Gemini has no allowlist: trust is a property of the server entry itself, so this reaches into
+        // the entry init already wrote rather than adding a rule beside it.
+        grant: (c) => {
+            const servers = 'object' === typeof c['mcpServers'] && null !== c['mcpServers']
+                ? { ...c['mcpServers'] }
+                : {};
+            const entry = 'object' === typeof servers[RETICLE_KEY] && null !== servers[RETICLE_KEY]
+                ? servers[RETICLE_KEY]
+                : {};
+            return { ...c, mcpServers: { ...servers, [RETICLE_KEY]: { ...entry, trust: true } } };
+        },
+    },
+];
+export const ApprovalOutcome = {
+    GRANTED: 'granted',
+    ALREADY: 'already',
+    ABSENT: 'absent',
+    /** Deliberately left for an explicit run, because doing it unattended costs the user something. */
+    DEFERRED: 'deferred',
+    FAILED: 'failed',
+};
+/**
+ * Pre-approve Reticle's tools everywhere the machine has an agent that would otherwise ask.
+ *
+ * A client that cannot be written is reported, never thrown: one unwritable settings file is not a
+ * reason to leave the other three prompting.
+ */
+export function grantAutoApproval(io, where, grants = APPROVAL_GRANTS, options = {}) {
+    const join = joinFor(where.platform);
+    return grants.map((grant) => {
+        const file = join(where.home, grant.paths[where.platform]);
+        const base = { id: grant.id, name: grant.name, file, rule: grant.rule };
+        const installed = grant.markers.some((m) => io.exists(join(where.home, m[where.platform])));
+        if (!installed)
+            return { ...base, outcome: ApprovalOutcome.ABSENT };
+        try {
+            const existed = io.exists(file);
+            if (true === options.onlyIfNoSupersede && true === grant.supersedesInApp && !existed) {
+                return {
+                    ...base,
+                    outcome: ApprovalOutcome.DEFERRED,
+                    warn: `creating ${file} would supersede what you approved inside ${grant.name}, which is not something to do unannounced. Run: npx @reticlehq/server init --files-only`,
+                };
+            }
+            // A settings file we cannot parse is left exactly as it is. Reformatting somebody's config to
+            // add one line is a worse outcome than one dialog they have to click.
+            const current = existed
+                ? JSON.parse(io.readFile(file))
+                : {};
+            const next = grant.grant(current);
+            if (next === current)
+                return { ...base, outcome: ApprovalOutcome.ALREADY };
+            io.mkdirp(file.slice(0, Math.max(0, file.lastIndexOf('/'))));
+            io.writeFile(file, `${JSON.stringify(next, null, INDENT)}\n`);
+            const warn = true === grant.supersedesInApp && !existed
+                ? `${file} now governs which MCP tools run without asking; anything you had approved inside ${grant.name} itself will ask again until it is listed here too`
+                : undefined;
+            return { ...base, outcome: ApprovalOutcome.GRANTED, ...(undefined === warn ? {} : { warn }) };
+        }
+        catch (err) {
+            return {
+                ...base,
+                outcome: ApprovalOutcome.FAILED,
+                warn: String(err?.message ?? err).slice(0, 120),
+            };
+        }
+    });
+}

package/dist/setup/bridge-port.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The bridge port, checked before the connect wait.
+ *
+ * The bridge is the channel between the daemon and the SDK in the page. While something else holds
+ * that port no session can ever appear, however correct the instrumentation is — so a run that goes
+ * ahead spends its entire connect budget and then reports what looks like a wiring problem, sending
+ * the reader to the one place that is fine.
+ *
+ * `serve` refuses a held port too, in prose written for somebody starting a daemon. This is the same
+ * fact told to somebody installing, and it has to say what the bridge IS: that sentence is what
+ * makes "no session appeared" mean something.
+ */
+import { PortPresence } from '../daemon/port-presence.js';
+/** The refusal to print, or undefined when the port is usable. */
+export declare function bridgeOccupied(presence: PortPresence, port: number): string | undefined;

package/dist/setup/bridge-port.js

@@ -0,0 +1,24 @@
+/**
+ * The bridge port, checked before the connect wait.
+ *
+ * The bridge is the channel between the daemon and the SDK in the page. While something else holds
+ * that port no session can ever appear, however correct the instrumentation is — so a run that goes
+ * ahead spends its entire connect budget and then reports what looks like a wiring problem, sending
+ * the reader to the one place that is fine.
+ *
+ * `serve` refuses a held port too, in prose written for somebody starting a daemon. This is the same
+ * fact told to somebody installing, and it has to say what the bridge IS: that sentence is what
+ * makes "no session appeared" mean something.
+ */
+import { PortPresence } from '../daemon/port-presence.js';
+/** The refusal to print, or undefined when the port is usable. */
+export function bridgeOccupied(presence, port) {
+    // DAEMON is the ordinary case — that is the daemon init is about to use. FREE is fine too: one
+    // gets started. Only a stranger is fatal.
+    if (PortPresence.FOREIGN !== presence)
+        return undefined;
+    return (`port ${String(port)} is held by something that is not a Reticle daemon. That is the bridge — ` +
+        'the channel between the daemon and the SDK in your page — so no session can ever appear while ' +
+        'it is occupied, however correct the wiring is. Free it, or re-run with --port <n> and set the ' +
+        'same port in .reticle.json.');
+}

package/dist/setup/desktop-shape.d.ts

@@ -0,0 +1,57 @@
+/**
+ * How a desktop app differs from a web app, for the phases that run after the files are written.
+ *
+ * `init` already understands Electron and Tauri when it writes files: desktop-doctor.ts checks the
+ * Tauri CSP for a blocked bridge or IPC, the Electron preload, the capture helper. The runtime
+ * phases did not, and they made three web-shaped assumptions that are wrong here — one of them
+ * actively harmful.
+ *
+ * 1. **Do not open a browser.** The app's own window IS the client. Opening a tab creates a SECOND
+ *    session that is not the app, and the session picker would then have to choose between them —
+ *    which is exactly the stale-tab false green, arranged deliberately.
+ * 2. **Do not wait for an HTTP port.** Tauri serves `tauri://localhost` (`http://tauri.localhost`
+ *    on Windows) from inside the webview; there is nothing for `fetch` to probe. Electron under
+ *    electron-vite does serve a renderer over HTTP, but the window is what matters, not the port.
+ * 3. **Wait for the app to launch instead.** `tauri dev` builds Rust before a window appears, which
+ *    is minutes on a cold cache, so the budget has to be the app's, not a web app's.
+ */
+/** What kind of thing setup is about to run. */
+export declare const AppShape: {
+    readonly WEB: "web";
+    readonly ELECTRON: "electron";
+    readonly TAURI: "tauri";
+};
+export type AppShape = (typeof AppShape)[keyof typeof AppShape];
+export declare const isDesktop: (shape: AppShape) => boolean;
+/** Files and dependencies that name the shell, read through an injected reader. */
+export interface ShapeEvidence {
+    /** `src-tauri/tauri.conf.json` exists. */
+    readonly hasTauriConf: boolean;
+    /** `electron` is a dependency or devDependency. */
+    readonly hasElectronDep: boolean;
+}
+/**
+ * Which shell this is.
+ *
+ * Tauri wins when both are present: a project with a Tauri config is a Tauri app whatever else it
+ * has installed, and electron sometimes appears in a monorepo's root devDependencies.
+ */
+export declare function readShape(evidence: ShapeEvidence): AppShape;
+export declare function isDesktopOrigin(url: string): boolean;
+/**
+ * How the phases should behave for this shape.
+ *
+ * Returned as data rather than branched at each call site, so the differences are visible in one
+ * place and testable without a desktop runtime.
+ */
+export interface ShapePolicy {
+    /** Open a browser at the url. False for desktop: the app window is already the client. */
+    readonly openBrowser: boolean;
+    /** Require an HTTP response before looking for a session. */
+    readonly requireHttpReady: boolean;
+    /** How long the app gets to produce a session, which for Tauri includes a Rust build. */
+    readonly connectBudgetMs: number;
+    /** Said out loud, because a desktop run looks stuck if nobody explains the wait. */
+    readonly note: string | undefined;
+}
+export declare function policyFor(shape: AppShape): ShapePolicy;