@reticlehq/server 2.14.0 → 3.2.0

package/dist/command/dev/stale-issue-guard.d.ts

@@ -0,0 +1,35 @@
+/**
+ * An issue we have already fixed must not still read as available work.
+ *
+ * A commit saying it closes an issue is a claim that the issue is done. If that issue is still open
+ * and unlabelled afterwards, the tracker is lying to whoever reads it next — and the person it lies
+ * to is by definition someone looking for something to work on. Remembering is not a mechanism; this
+ * is the smallest one that works.
+ *
+ * ## Why `fixed-pending-release` is an accepted answer
+ *
+ * Work fixed on an unreleased branch is legitimately still open; the issue closes when the version
+ * ships. The label is what tells a contributor not to start, so the label — not the closure — is
+ * what this guard is actually asking for. That is also why the fix is cheap: nobody has to change
+ * when they close things, only to say so.
+ *
+ * Pure. The git log and the GitHub lookup belong to the caller, which is what makes every branch
+ * below testable without a network or a repo.
+ */
+export interface IssueState {
+    number: number;
+    state: 'open' | 'closed';
+    labels: readonly string[];
+}
+export declare function closedRefsIn(commitMessage: string): number[];
+/**
+ * Of the issues these commits claimed to close, the ones still reading as available work.
+ *
+ * An issue that could not be looked up is deliberately silent rather than failing. A rate limit, a
+ * transferred issue or a deleted one would otherwise turn this red for a reason unrelated to what it
+ * guards, and a guard that goes red for unrelated reasons gets disabled — which costs more than the
+ * defect it was catching.
+ */
+export declare function staleIssues(claimed: readonly number[], issues: readonly IssueState[]): number[];
+/** The message the guard prints. Held here so the check and its tests cannot describe it differently. */
+export declare function staleIssueReport(stale: readonly number[]): string;

package/dist/command/dev/stale-issue-guard.js

@@ -0,0 +1,69 @@
+/**
+ * An issue we have already fixed must not still read as available work.
+ *
+ * A commit saying it closes an issue is a claim that the issue is done. If that issue is still open
+ * and unlabelled afterwards, the tracker is lying to whoever reads it next — and the person it lies
+ * to is by definition someone looking for something to work on. Remembering is not a mechanism; this
+ * is the smallest one that works.
+ *
+ * ## Why `fixed-pending-release` is an accepted answer
+ *
+ * Work fixed on an unreleased branch is legitimately still open; the issue closes when the version
+ * ships. The label is what tells a contributor not to start, so the label — not the closure — is
+ * what this guard is actually asking for. That is also why the fix is cheap: nobody has to change
+ * when they close things, only to say so.
+ *
+ * Pure. The git log and the GitHub lookup belong to the caller, which is what makes every branch
+ * below testable without a network or a repo.
+ */
+/** The label that means "fixed, waiting for a release" — an honest reason to still be open. */
+const PENDING_RELEASE_LABEL = 'fixed-pending-release';
+/**
+ * Issue numbers a commit message CLAIMS to have closed.
+ *
+ * Only the closing verbs GitHub itself acts on. A bare `#447`, a `Refs #447` or a `see #447` is how
+ * a change points at context it did not close — the exact habit we want to encourage — so counting
+ * those would make the guard cry wolf on good behaviour, and a check that cries wolf is one people
+ * learn to skip.
+ */
+const CLOSING_REF = /\b(?:close[sd]?|fix(?:e[sd])?|resolve[sd]?)\s+#(\d+)/gi;
+export function closedRefsIn(commitMessage) {
+    const seen = new Set();
+    for (const match of commitMessage.matchAll(CLOSING_REF)) {
+        const raw = match[1];
+        if (raw === undefined)
+            continue;
+        const parsed = Number.parseInt(raw, 10);
+        if (Number.isFinite(parsed))
+            seen.add(parsed);
+    }
+    return [...seen];
+}
+/**
+ * Of the issues these commits claimed to close, the ones still reading as available work.
+ *
+ * An issue that could not be looked up is deliberately silent rather than failing. A rate limit, a
+ * transferred issue or a deleted one would otherwise turn this red for a reason unrelated to what it
+ * guards, and a guard that goes red for unrelated reasons gets disabled — which costs more than the
+ * defect it was catching.
+ */
+export function staleIssues(claimed, issues) {
+    const byNumber = new Map(issues.map((issue) => [issue.number, issue]));
+    return claimed.filter((number) => {
+        const issue = byNumber.get(number);
+        if (issue === undefined)
+            return false;
+        if ('closed' === issue.state)
+            return false;
+        return !issue.labels.includes(PENDING_RELEASE_LABEL);
+    });
+}
+/** The message the guard prints. Held here so the check and its tests cannot describe it differently. */
+export function staleIssueReport(stale) {
+    const list = stale.map((n) => `#${String(n)}`).join(', ');
+    return (`${list} ${1 === stale.length ? 'is' : 'are'} still OPEN, and a commit on this branch says it ` +
+        `closes ${1 === stale.length ? 'it' : 'them'}. Anyone browsing the tracker reads that as work ` +
+        `nobody has started. Close ${1 === stale.length ? 'it' : 'them'}, or label ` +
+        `${1 === stale.length ? 'it' : 'them'} \`${PENDING_RELEASE_LABEL}\` if the fix is waiting on a ` +
+        `release. This has cost three contributors an evening each; it is not bookkeeping.`);
+}

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

@@ -0,0 +1,111 @@
+/**
+ * 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;
+}
+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;
+}
+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);
+/**
+ * The directory holding a path the planner already produced.
+ *
+ * This READS a separator rather than writing one, so unlike `joinFor` it takes no platform: the
+ * path in hand already carries the separator it was planned with, and the writers that call this
+ * have a plan, not an os. `win32.dirname` is the one that can answer for both, because Windows
+ * accepts either separator and the planned posix paths never contain a backslash.
+ *
+ * Both callers used to hand-roll `slice(0, Math.max(0, lastIndexOf('/')))`. On a win32 path there
+ * is no '/' to find, so that returned '' and the writer called `mkdir('')` — which is how a Windows
+ * install registered one agent out of thirteen and reported `ENOENT: mkdir ''` for the other
+ * twelve. Returning a root is the point: `dirname` never answers with the empty string.
+ */
+export declare const parentOf: (path: 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[];
+export {};

package/dist/command/setup/agent-configs.js

@@ -0,0 +1,365 @@
+/**
+ * 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' },
+    },
+];
+/**
+ * Does this YAML already carry OUR entry?
+ *
+ * Deliberately a text match and not a YAML parse: the reason this format is never rewritten is that
+ * we will not take a dependency on round-tripping somebody's comments and ordering, and a parser
+ * here would be the first half of exactly that. Both halves are required so a file that merely
+ * mentions the word in a comment is not mistaken for a registration.
+ */
+function yamlHasReticle(text) {
+    return text.includes(`name: ${RETICLE_KEY}`) && text.includes(SERVER_PACKAGE);
+}
+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;
+/**
+ * The directory holding a path the planner already produced.
+ *
+ * This READS a separator rather than writing one, so unlike `joinFor` it takes no platform: the
+ * path in hand already carries the separator it was planned with, and the writers that call this
+ * have a plan, not an os. `win32.dirname` is the one that can answer for both, because Windows
+ * accepts either separator and the planned posix paths never contain a backslash.
+ *
+ * Both callers used to hand-roll `slice(0, Math.max(0, lastIndexOf('/')))`. On a win32 path there
+ * is no '/' to find, so that returned '' and the writer called `mkdir('')` — which is how a Windows
+ * install registered one agent out of thirteen and reported `ENOENT: mkdir ''` for the other
+ * twelve. Returning a root is the point: `dirname` never answers with the empty string.
+ */
+export const parentOf = (path) => win32.dirname(path);
+/**
+ * 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) {
+            // "Exists" was standing in for "somebody else wrote this", and the file Reticle wrote on the
+            // first run is not somebody else. Without this the second init reported MANUAL and closed by
+            // telling the user to add by hand the entry already sitting in that file — on every re-run,
+            // which is the documented upgrade path. Read for OUR entry, not for the file.
+            if (exists(file) && yamlHasReticle(readFile(file))) {
+                return { id: c.id, name: c.name, file, action: AgentAction.ALREADY, why: 'already wired' };
+            }
+            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/command/setup/agent-notice-memory.d.ts

@@ -0,0 +1,16 @@
+/** One client we could not write to, and why. */
+export interface ManualNotice {
+    readonly name: string;
+    readonly file: string;
+    readonly why: string;
+}
+/** Where the stamp lives, under the state home the caller resolves. */
+export declare const NOTICE_MEMORY_BASENAME = "agent-notices.json";
+/** Identity of a notice: the same client, the same file, for the same reason. */
+export declare function noticeKey(n: ManualNotice): string;
+/** Pure. The notices `said` has not already recorded, in order, without repeats. */
+export declare function unsaidNotices(said: readonly string[], notices: readonly ManualNotice[]): ManualNotice[];
+/** Every key recorded before. An unreadable or malformed stamp reads as "nothing was said". */
+export declare function readSaid(stateHome: string): string[];
+/** Record these keys beside whatever was there. A failed write costs a repeated line, nothing more. */
+export declare function rememberSaid(stateHome: string, keys: readonly string[]): void;

package/dist/command/setup/agent-notice-memory.js

@@ -0,0 +1,65 @@
+/**
+ * Which "add the reticle entry by hand" lines have already been said on this machine.
+ *
+ * Two commands register agents, deliberately: the installer does it because it once reached fewer
+ * clients than `init` and sent people to a project directory to finish a half-done job, and `init`
+ * does it because that is where the project gets wired. Both then narrate the clients whose config
+ * we refuse to rewrite -- a Zed settings file with comments in it, a Continue YAML somebody
+ * formatted -- so a `curl | sh` followed by `reticle init` prints the same two paragraphs twice in
+ * one sitting, and prints them again on every re-run after that, forever.
+ *
+ * The REGISTRATION stays in both places. The sentence is the thing that repeats, and it is a
+ * sentence about a MACHINE rather than about a run: a config we will not rewrite stays un-rewritten
+ * until somebody edits it, at which point the notice's own text changes and it is said again.
+ *
+ * Stamped by content, not by run. If the stamp cannot be read or written the notice simply prints,
+ * which is the failure that costs a duplicate line rather than a missed instruction.
+ */
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+/** Where the stamp lives, under the state home the caller resolves. */
+export const NOTICE_MEMORY_BASENAME = 'agent-notices.json';
+/** Identity of a notice: the same client, the same file, for the same reason. */
+export function noticeKey(n) {
+    return JSON.stringify([n.name, n.file, n.why]);
+}
+/** Pure. The notices `said` has not already recorded, in order, without repeats. */
+export function unsaidNotices(said, notices) {
+    const seen = new Set(said);
+    const out = [];
+    for (const n of notices) {
+        const key = noticeKey(n);
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        out.push(n);
+    }
+    return out;
+}
+/** Every key recorded before. An unreadable or malformed stamp reads as "nothing was said". */
+export function readSaid(stateHome) {
+    try {
+        const raw = readFileSync(join(stateHome, NOTICE_MEMORY_BASENAME), 'utf8');
+        const parsed = JSON.parse(raw);
+        if (!Array.isArray(parsed))
+            return [];
+        return parsed.filter((k) => 'string' === typeof k);
+    }
+    catch {
+        return [];
+    }
+}
+/** Record these keys beside whatever was there. A failed write costs a repeated line, nothing more. */
+export function rememberSaid(stateHome, keys) {
+    if (0 === keys.length)
+        return;
+    const merged = [...new Set([...readSaid(stateHome), ...keys])];
+    try {
+        mkdirSync(stateHome, { recursive: true });
+        writeFileSync(join(stateHome, NOTICE_MEMORY_BASENAME), JSON.stringify(merged, null, 2));
+    }
+    catch {
+        // Said once too often is the cost. Silence here is deliberate: a stamp that cannot be written
+        // must not fail an install.
+    }
+}