@reticlehq/server 2.10.0 → 2.12.0

package/dist/intent/intent-store.js

@@ -0,0 +1,112 @@
+import { bindIntent, declareIntent, dischargeIntent, emptyIntentFile, openIntents, parseIntentFile, upsertIntent, } from '@reticlehq/core';
+import { reticleDirPaths } from '../project/reticle-dir.js';
+import { withFileLock } from '../project/file-lock.js';
+/**
+ * The intent ledger on disk — `.reticle/intent.json`, git-checked and meant to be read in review.
+ *
+ * Git-checked deliberately. The one real defence against an agent quietly narrowing what it meant to
+ * match what it can already prove is that a human sees the narrowing in a diff, and that only works
+ * if the file lives with the code and travels with the PR. It is also why the writes are byte-stable:
+ * a ledger that churns on every run is one whose diffs nobody reads.
+ *
+ * Every operation goes through the same file lock the other stores use, because two sessions driving
+ * one project is ordinary and a lost declaration would be silent.
+ */
+const JSON_INDENT = 2;
+export class IntentStore {
+    #fs;
+    #root;
+    #clock;
+    constructor(fs, root, clock) {
+        this.#fs = fs;
+        this.#root = root;
+        this.#clock = clock;
+    }
+    #path() {
+        return reticleDirPaths(this.#root).intent;
+    }
+    /**
+     * Load the ledger, failing soft to empty.
+     *
+     * This is a git-checked file an agent can write and a human can hand-merge, so a malformed one is
+     * genuinely reachable — a conflict marker left in place is the obvious case. Throwing here would
+     * take down the verdict that was only asking what was still open, which trades a small problem for
+     * a large one.
+     */
+    async #load() {
+        try {
+            const raw = await this.#fs.readFile(this.#path());
+            return parseIntentFile(JSON.parse(raw));
+        }
+        catch {
+            return emptyIntentFile();
+        }
+    }
+    /** Byte-stable: 2-space indent, one trailing newline. An unchanged ledger produces no diff. */
+    async #save(file) {
+        await this.#fs.mkdir(reticleDirPaths(this.#root).root);
+        await this.#fs.writeFile(this.#path(), `${JSON.stringify(file, null, JSON_INDENT)}\n`);
+    }
+    /** Every intent, in declaration order. */
+    async read() {
+        return Object.values((await this.#load()).intents);
+    }
+    /** Everything not yet proved — what an agent asking "am I done?" still owes. */
+    async open() {
+        return openIntents(await this.#load());
+    }
+    /**
+     * Declare one or more intents.
+     *
+     * Batched because the marginal cost of the whole mechanism has to stay at one call per feature; an
+     * agent that must make five calls to declare five things will make none.
+     */
+    async declare(entries) {
+        if (0 === entries.length)
+            return [];
+        return withFileLock(this.#path(), async () => {
+            let file = await this.#load();
+            const now = this.#clock.now();
+            const declared = [];
+            for (const entry of entries) {
+                const intent = declareIntent({ ...entry, now });
+                file = upsertIntent(file, intent);
+                const stored = file.intents[intent.id];
+                if (stored !== undefined)
+                    declared.push(stored);
+            }
+            await this.#save(file);
+            return declared;
+        });
+    }
+    /** Attach the predicate that would prove an intent. False when the id names nothing. */
+    async bind(id, binding) {
+        return withFileLock(this.#path(), async () => {
+            const file = await this.#load();
+            const existing = file.intents[id];
+            if (existing === undefined)
+                return false;
+            await this.#save(upsertIntent(file, bindIntent(existing, binding)));
+            return true;
+        });
+    }
+    /**
+     * Record that a verdict proved an intent.
+     *
+     * False rather than a throw on an unknown or unbound id: discharge runs off the back of a verdict,
+     * and must never be the reason one fails to return.
+     */
+    async discharge(id, proof) {
+        return withFileLock(this.#path(), async () => {
+            const file = await this.#load();
+            const existing = file.intents[id];
+            if (existing === undefined)
+                return false;
+            const proved = dischargeIntent(existing, proof);
+            if (proved === existing)
+                return false;
+            await this.#save(upsertIntent(file, proved));
+            return true;
+        });
+    }
+}

package/dist/intent/intent-tools.d.ts

@@ -0,0 +1,2 @@
+import type { ToolDef } from '../tools/tool-kit.js';
+export declare const INTENT_TOOLS: ToolDef[];

package/dist/intent/intent-tools.js

@@ -0,0 +1,80 @@
+import { z } from 'zod';
+import { IntentStore } from './intent-store.js';
+import { ReticleTool } from '../tools/tool-names.js';
+import { sessionIdShape } from '../tools/tool-kit.js';
+import { sessionRoot } from '../project/session-root.js';
+import { asString } from '../tools/tools-helpers.js';
+/**
+ * Declare what a change was SUPPOSED to make true, while somebody still knows.
+ *
+ * One tool with three actions rather than three tools, because the surface is capped and because an
+ * agent that has to discover three names to use one idea uses none of them.
+ *
+ * There is deliberately no `discharge` action. A verdict discharges an intent by satisfying its
+ * binding, and a discharge an agent has to remember to file would be the same forgetting problem
+ * this exists to solve, moved one layer up.
+ */
+const DECLARE = 'declare';
+const LIST = 'list';
+const BIND = 'bind';
+export const INTENT_TOOLS = [
+    {
+        name: ReticleTool.INTENT,
+        description: 'Record what a change is SUPPOSED to make true, in your own words, while you still know — then verification does not have to re-derive it from the DOM later. { action:"declare", intents:[{ id, statement, surface? }] } takes prose and needs NO predicate: at declare time there is often no route, no ref and no code yet, and a predicate demanded there is just a mechanism. Declare EARLY (as you build) and batch them — one call per feature is the whole budget. { action:"bind", id, binding } attaches the predicate that would prove it once you know how; an intent with no binding is not a failure, it is the most interesting row in the ledger — something meant that nothing can currently prove. { action:"list" } returns what is still open. Stored in .reticle/intent.json, git-checked so a human sees in review if an intent was later narrowed to match what was easy to prove.',
+        example: {
+            action: DECLARE,
+            intents: [
+                { id: 'checkin', statement: 'clicking Send check-in makes the badge read "checked in"' },
+            ],
+        },
+        inputSchema: {
+            action: z.enum([DECLARE, LIST, BIND]),
+            intents: z
+                .array(z.object({
+                id: z.string(),
+                statement: z.string(),
+                surface: z
+                    .object({
+                    route: z.string().optional(),
+                    flow: z.string().optional(),
+                    files: z.array(z.string()).optional(),
+                })
+                    .optional(),
+            }))
+                .optional()
+                .describe('declare only. Batchable — declare every intent for a feature in one call.'),
+            id: z.string().optional().describe('bind only: which intent the predicate proves.'),
+            binding: z
+                .unknown()
+                .optional()
+                .describe("bind only: the predicate that would prove it, in reticle_assert's shape."),
+            ...sessionIdShape,
+        },
+        outputSchema: {
+            intents: z
+                .array(z.unknown())
+                .optional()
+                .describe('The intents this call declared, or on `list` everything still open — each { id, statement, state, declaredAt, binding?, surface?, provenBy?, amended? }. `state` is declared (prose only), bound (a predicate exists), or proved (a verdict satisfied it).'),
+            bound: z.boolean().optional().describe('bind only: false when the id names no intent.'),
+            path: z.string().optional().describe('Where the ledger was written.'),
+        },
+        handler: async (deps, args) => {
+            const root = sessionRoot(deps, asString(args['sessionId']));
+            const store = new IntentStore(deps.fs, root, { now: deps.now });
+            const action = asString(args['action']);
+            if (BIND === action) {
+                const id = asString(args['id']) ?? '';
+                return { bound: await store.bind(id, args['binding']) };
+            }
+            if (LIST === action) {
+                return { intents: await store.open() };
+            }
+            const raw = args['intents'];
+            const entries = Array.isArray(raw)
+                ? raw
+                : [];
+            const declared = await store.declare(entries);
+            return { intents: declared, path: root };
+        },
+    },
+];

package/dist/intent/open-intents.d.ts

@@ -0,0 +1,21 @@
+import type { Intent } from '@reticlehq/core';
+import type { ToolDeps } from '../tools/tool-kit.js';
+/**
+ * What this project still owes — the ledger's undischarged intents, for a tool that has `deps` and a
+ * session id rather than a store.
+ *
+ * One helper rather than the same three-line construction at each site: the ROOT resolution is the
+ * part that must not drift. A caller that resolved the daemon's own directory while the declaring
+ * tool wrote to the project's would read an empty ledger and report that nothing was declared, which
+ * is a false accusation rather than an error.
+ */
+export declare function openSessionIntents(deps: ToolDeps, sessionId: string | undefined): Promise<Intent[]>;
+/**
+ * EVERY intent in the ledger, proved ones included — the denominator the open list is a subset of.
+ *
+ * Separate from `openSessionIntents` rather than a flag on it, because the two answer different
+ * questions: "what does this project still owe" drives a verdict's honesty, and "was anything ever
+ * declared" is what decides whether `reticle_intent` is used at all. Same root resolution, for the
+ * same reason it is shared above.
+ */
+export declare function allSessionIntents(deps: ToolDeps, sessionId: string | undefined): Promise<Intent[]>;

package/dist/intent/open-intents.js

@@ -0,0 +1,25 @@
+import { IntentStore } from './intent-store.js';
+import { sessionRoot } from '../project/session-root.js';
+/**
+ * What this project still owes — the ledger's undischarged intents, for a tool that has `deps` and a
+ * session id rather than a store.
+ *
+ * One helper rather than the same three-line construction at each site: the ROOT resolution is the
+ * part that must not drift. A caller that resolved the daemon's own directory while the declaring
+ * tool wrote to the project's would read an empty ledger and report that nothing was declared, which
+ * is a false accusation rather than an error.
+ */
+export async function openSessionIntents(deps, sessionId) {
+    return new IntentStore(deps.fs, sessionRoot(deps, sessionId), { now: deps.now }).open();
+}
+/**
+ * EVERY intent in the ledger, proved ones included — the denominator the open list is a subset of.
+ *
+ * Separate from `openSessionIntents` rather than a flag on it, because the two answer different
+ * questions: "what does this project still owe" drives a verdict's honesty, and "was anything ever
+ * declared" is what decides whether `reticle_intent` is used at all. Same root resolution, for the
+ * same reason it is shared above.
+ */
+export async function allSessionIntents(deps, sessionId) {
+    return new IntentStore(deps.fs, sessionRoot(deps, sessionId), { now: deps.now }).read();
+}

package/dist/journal/envelope.d.ts

@@ -8,7 +8,7 @@ import type { SegmentRollup } from './rollups.js';
  * (slower, more errors, more requests) — a segment doing less than expected is not a regression.
  */
 /** Online mean/variance/max for one metric (Welford's algorithm). Immutable: addStat returns a copy. */
-export interface MetricStats {
+interface MetricStats {
     count: number;
     mean: number;
     /** Sum of squared deviations (Welford M2); variance = m2/(count-1). */
@@ -22,7 +22,7 @@ export declare function stddev(stats: MetricStats): number;
 export declare function zScore(stats: MetricStats, x: number): number;
 /** The metrics an envelope tracks per route. */
 declare const ENVELOPE_METRICS: readonly ["durationMs", "net", "netErrors", "consoleErrors"];
-export type EnvelopeMetric = (typeof ENVELOPE_METRICS)[number];
+type EnvelopeMetric = (typeof ENVELOPE_METRICS)[number];
 export interface RouteEnvelope {
     route: string;
     /** Runs that contributed a sample — below MIN_ENVELOPE_SAMPLES the envelope is too green to judge. */

package/dist/journal/journal-recorder.d.ts

@@ -7,6 +7,11 @@ export interface JournalSink {
 /** Read side of the durable journal — the fall-through source when the ring buffer has evicted. */
 export interface JournalReader {
     readEvents(): Promise<ReticleEvent[]>;
+    /**
+     * The action ledger. Optional because a test double is a partial reader, and nothing that only
+     * needs events should be forced to grow a second method to satisfy the type.
+     */
+    readActions?(): Promise<JournalAction[]>;
 }
 interface JournalRecorderOptions {
     /** Injected elapsed-ms clock (never read from Date here — the clock-injection rule). */
@@ -32,6 +37,24 @@ export declare class JournalRecorder {
     beginAction(actionId: string, tool: string, args: Record<string, unknown>): void;
     /** Close the active window: persist its buffered events, then the action record. No-op if none active. */
     finishAction(effect?: unknown, settled?: boolean, settledInMs?: number): void;
+    /**
+     * Append one action record for a tool that PROVED something without driving the page.
+     *
+     * `reticle_assert` produces a verdict and moves nothing, so it must never open an attribution
+     * window: while one is open every observed event is stamped with that action's id, and stamping
+     * ambient traffic with an assertion's id would manufacture a causal link that does not exist —
+     * exactly what `EventAttribution.WINDOW` is carefully labelled to avoid claiming. So this writes
+     * the record and leaves `#active` precisely as it found it: an act window open across an assert
+     * keeps attributing to itself, which is the truth of what caused those events.
+     *
+     * `settled` is left unset for the same reason — nothing was dispatched, so there is no settle
+     * outcome to report, and the run fold skips actions that state none rather than inventing one.
+     *
+     * Ordering rides the same chain as `finishAction`: buffered events flush first, so a record is
+     * always persisted after the events that preceded it. Records land in the order verdicts were
+     * REACHED, so an assert taken mid-window is written before the act it interrupted.
+     */
+    recordAction(actionId: string, tool: string, args: Record<string, unknown>, effect?: unknown): void;
     /** Persist any buffered events now (call on session end). Awaits the write chain to settle. */
     flush(): Promise<void>;
 }

package/dist/journal/journal-recorder.js

@@ -65,6 +65,41 @@ export class JournalRecorder {
         this.#enqueueFlush();
         this.#chain = this.#chain.then(() => this.#sink.appendAction(action)).catch(() => undefined);
     }
+    /**
+     * Append one action record for a tool that PROVED something without driving the page.
+     *
+     * `reticle_assert` produces a verdict and moves nothing, so it must never open an attribution
+     * window: while one is open every observed event is stamped with that action's id, and stamping
+     * ambient traffic with an assertion's id would manufacture a causal link that does not exist —
+     * exactly what `EventAttribution.WINDOW` is carefully labelled to avoid claiming. So this writes
+     * the record and leaves `#active` precisely as it found it: an act window open across an assert
+     * keeps attributing to itself, which is the truth of what caused those events.
+     *
+     * `settled` is left unset for the same reason — nothing was dispatched, so there is no settle
+     * outcome to report, and the run fold skips actions that state none rather than inventing one.
+     *
+     * Ordering rides the same chain as `finishAction`: buffered events flush first, so a record is
+     * always persisted after the events that preceded it. Records land in the order verdicts were
+     * REACHED, so an assert taken mid-window is written before the act it interrupted.
+     */
+    recordAction(actionId, tool, args, effect) {
+        const at = this.#now();
+        const action = {
+            v: JOURNAL_FILE_VERSION,
+            actionId,
+            tool,
+            args,
+            effect,
+            // No window was opened, so no event carries this id: `seqRange` is omitted rather than
+            // invented, because any range here would claim an attribution that never happened. `tRange` is
+            // required by the schema and the honest value is the instant the verdict was recorded — a span
+            // of zero, which is exactly how much time this action attributed events over.
+            tRange: { from: at, to: at },
+            at,
+        };
+        this.#enqueueFlush();
+        this.#chain = this.#chain.then(() => this.#sink.appendAction(action)).catch(() => undefined);
+    }
     /** Persist any buffered events now (call on session end). Awaits the write chain to settle. */
     async flush() {
         this.#enqueueFlush();

package/dist/license/license.d.ts

@@ -111,7 +111,7 @@ export interface GateContext {
  * Gate an enterprise feature. No-op in dev/eval (requireLicense:false). In production it throws
  * EnterpriseLicenseError unless a valid, unexpired key that covers `feature` is present.
  */
-export declare function assertEnterprise(feature: string, ctx: GateContext): void;
+export declare function assertEnterprise(feature: string, ctx: GateContext, env?: NodeJS.ProcessEnv, baked?: string): void;
 /** Env names that carry the activation: the operator's key, and the issuer public key baked at release. */
 export declare const LICENSE_KEY_ENV = "RETICLE_LICENSE_KEY";
 export declare const LICENSE_PUBLIC_KEY_ENV = "RETICLE_LICENSE_PUBLIC_KEY";
@@ -131,7 +131,13 @@ export interface LicenseReport {
      * neither, so it told an interested reader to set a variable without saying what it would unlock or
      * how to obtain it. A dead end at exactly the moment somebody is asking.
      */
-    gated: readonly string[];
+    /**
+     * What a licence unlocks in this build. Present on every branch a PROSPECTIVE customer lands on,
+     * because being told to set a variable with no idea what it unlocks is the dead end this exists to
+     * close. Absent once a licence is `active`: that reader has already bought, so naming features at
+     * them reveals the product surface and answers nothing they asked.
+     */
+    gated?: readonly string[];
     contact: string;
     /**
      * The key is valid, and scoped to features this build does not gate, so it unlocks nothing here.

package/dist/license/license.js

@@ -114,26 +114,18 @@ export class EnterpriseLicenseError extends Error {
         this.reason = reason;
     }
 }
-/** The issuer public key from the environment (set at release / by the operator); undefined if unset. */
-function issuerPublicKey() {
-    const pem = process.env[LICENSE_PUBLIC_KEY_ENV];
-    if (pem === undefined || 0 === pem.length)
-        return undefined;
-    try {
-        return createPublicKey(pem);
-    }
-    catch {
-        return undefined;
-    }
-}
 /**
  * Gate an enterprise feature. No-op in dev/eval (requireLicense:false). In production it throws
  * EnterpriseLicenseError unless a valid, unexpired key that covers `feature` is present.
  */
-export function assertEnterprise(feature, ctx) {
+export function assertEnterprise(feature, ctx, env = process.env, baked) {
     if (!ctx.requireLicense)
         return;
-    const publicKey = ctx.publicKey ?? issuerPublicKey();
+    // Resolved exactly as the env-entry point resolves it: BAKED first, env only as the dev/test
+    // hatch. This path used to read the environment alone, so on a real release, where the key is
+    // baked and no env var is set, it denied every valid licence with `no-issuer-key` while
+    // assertEnterpriseFromEnv allowed the same key on the same build. Two gates, one truth.
+    const publicKey = ctx.publicKey ?? loadPublicKey(resolveIssuerPublicKeyPem(env, baked));
     if (publicKey === undefined)
         throw new EnterpriseLicenseError(feature, 'no-issuer-key');
     const check = verifyLicenseKey(ctx.key, publicKey, ctx.now());
@@ -225,7 +217,10 @@ export function describeLicense(now, env = process.env, baked = BAKED_ISSUER_PUB
             ? `licensed to ${org} (${plan}), expires ${new Date(exp).toISOString()}. This key covers ${features?.join(', ')}, and nothing this build gates (${LICENSE_OFFER.gated.join(', ')}) is included. Contact ${LICENSE_CONTACT}`
             : `licensed to ${org} (${plan}), expires ${new Date(exp).toISOString()}`;
         return {
-            ...LICENSE_OFFER,
+            contact: LICENSE_CONTACT,
+            // The one active case that still needs the list: a key covering nothing this build gates is
+            // reported here, and the sentence explaining it is unreadable without both sides named.
+            ...(coversNothingHere ? { gated: LICENSE_OFFER.gated } : {}),
             status: LicenseActivation.ACTIVE,
             licenseId: lid,
             org,

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

@@ -0,0 +1,67 @@
+/**
+ * Two durable bits about the CLIENT side of the install: has an MCP client ever started Reticle's
+ * MCP server on this port, and has one ever asked it for the tool list.
+ *
+ * Some hosts register the server, start it, and then never send `tools/list` until the client is
+ * restarted. The agent has no Reticle tools, the user has no message, and from our side that install
+ * is byte-identical to one somebody wired and abandoned: daemon idle, no sessions, nothing to say.
+ * `status` could report "registered" and "connected"; it could not report the state in between,
+ * which is the one with an answer ("restart your client").
+ *
+ * Both bits record something that HAPPENED — the proxy ran, a `tools/list` arrived — never an
+ * inference from a config file. A config entry proves somebody wrote a line of JSON; it does not
+ * prove a client ever read it, which is precisely the thing in question here.
+ *
+ * Deliberately the same shape as `connection-memory.ts`: one small JSON file per port under the
+ * daemon's state home, best-effort in both directions. It is a HINT, so every failure degrades to
+ * "we do not know" rather than throwing — a diagnostic that can crash the process it is diagnosing
+ * is worse than no diagnostic at all.
+ *
+ * KNOWN LIMIT, and why the messages below say so out loud: the record is per PORT, not per client.
+ * Two clients on one machine share it, so a healthy one masks a broken one, and the record itself
+ * only begins on the version that introduced it — a long-working install reads as never attached
+ * until its client next starts the server. Both limits are stated in the text the user reads,
+ * because an honest "here is what I can see, here is what to check" beats a confident wrong no.
+ */
+/** What the client side of this install has been observed doing on this port. */
+export declare const AttachState: {
+    /** No client has started Reticle's MCP server here, as far as this record goes. */
+    readonly NEVER_ATTACHED: "never-attached";
+    /** A client started it and never asked for the tool list — the state that needs a restart. */
+    readonly NEVER_ENUMERATED: "never-enumerated";
+    /** Started and enumerated. Nothing to say. */
+    readonly ENUMERATED: "enumerated";
+};
+export type AttachState = (typeof AttachState)[keyof typeof AttachState];
+/** Record that an MCP client started the proxy on this port. */
+export declare function rememberProxyStarted(stateDir: string, port: number): void;
+/**
+ * Record that a client asked for the tool list on this port.
+ *
+ * Enumeration implies attachment — a `tools/list` cannot arrive at a server nobody started — so this
+ * sets both bits, and a record written by an older proxy that only ever set one is still read
+ * correctly.
+ */
+export declare function rememberEnumerated(stateDir: string, port: number): void;
+/** Which of the three client-side states this port is in. */
+export declare function attachState(stateDir: string, port: number): AttachState;
+/**
+ * The sentence to print for a state, or `undefined` when there is nothing to fix.
+ *
+ * The healthy case has to stay silent: advice printed beside a working client reads as though
+ * something is still wrong, which is its own kind of lie.
+ */
+export declare function describeAttachState(state: AttachState): string | undefined;
+/** What `reticle status` reports about the client side of the install. */
+export interface AttachStatusFields {
+    mcpClient: AttachState;
+    mcpClientAction?: string;
+}
+/**
+ * The client-side fields for one `status` run.
+ *
+ * The state is reported on EVERY run, healthy included — "the client has read the tools" is the
+ * fact that was missing, and reporting it only when broken leaves the reader unable to tell a
+ * healthy client from a version too old to look. The advice rides along only when there is any.
+ */
+export declare function attachStatusFields(stateDir: string, port: number): AttachStatusFields;

package/dist/mcp/attach-memory.js

@@ -0,0 +1,142 @@
+/**
+ * Two durable bits about the CLIENT side of the install: has an MCP client ever started Reticle's
+ * MCP server on this port, and has one ever asked it for the tool list.
+ *
+ * Some hosts register the server, start it, and then never send `tools/list` until the client is
+ * restarted. The agent has no Reticle tools, the user has no message, and from our side that install
+ * is byte-identical to one somebody wired and abandoned: daemon idle, no sessions, nothing to say.
+ * `status` could report "registered" and "connected"; it could not report the state in between,
+ * which is the one with an answer ("restart your client").
+ *
+ * Both bits record something that HAPPENED — the proxy ran, a `tools/list` arrived — never an
+ * inference from a config file. A config entry proves somebody wrote a line of JSON; it does not
+ * prove a client ever read it, which is precisely the thing in question here.
+ *
+ * Deliberately the same shape as `connection-memory.ts`: one small JSON file per port under the
+ * daemon's state home, best-effort in both directions. It is a HINT, so every failure degrades to
+ * "we do not know" rather than throwing — a diagnostic that can crash the process it is diagnosing
+ * is worse than no diagnostic at all.
+ *
+ * KNOWN LIMIT, and why the messages below say so out loud: the record is per PORT, not per client.
+ * Two clients on one machine share it, so a healthy one masks a broken one, and the record itself
+ * only begins on the version that introduced it — a long-working install reads as never attached
+ * until its client next starts the server. Both limits are stated in the text the user reads,
+ * because an honest "here is what I can see, here is what to check" beats a confident wrong no.
+ */
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+/** What the client side of this install has been observed doing on this port. */
+export const AttachState = {
+    /** No client has started Reticle's MCP server here, as far as this record goes. */
+    NEVER_ATTACHED: 'never-attached',
+    /** A client started it and never asked for the tool list — the state that needs a restart. */
+    NEVER_ENUMERATED: 'never-enumerated',
+    /** Started and enumerated. Nothing to say. */
+    ENUMERATED: 'enumerated',
+};
+/**
+ * What to do about a client that started Reticle and never listed its tools.
+ *
+ * Names the cause AND the action, like the rest of the doctor/status vocabulary, and names its own
+ * blind spot: this record cannot see WHICH client asked, so it must not tell somebody running two
+ * of them that the one in front of them is the broken one.
+ */
+const NEVER_ENUMERATED_ACTION = 'an MCP client started Reticle on this port and never asked for the tool list, so the tools are ' +
+    'here and your client has not read them — restart your MCP client, which is what makes it list ' +
+    'them again. This record is per port, not per client, so with more than one client registered ' +
+    'the one that never listed may not be the one you are looking at.';
+/**
+ * What to do when nothing has ever attached.
+ *
+ * The hedge is not padding. This record begins the first time a client starts the server on a
+ * version that keeps it, so an install that has worked for months reads as never attached until its
+ * client next starts Reticle — and telling that user their server is unregistered would send them
+ * to re-run `init` over a working setup.
+ */
+const NEVER_ATTACHED_ACTION = 'no MCP client has started Reticle on this port, so either the server is not registered with your ' +
+    'client or nothing has attached since this record began — register it with `npx ' +
+    '@reticlehq/server init`, then restart your MCP client and run status again.';
+const EMPTY = { attached: false, enumerated: false };
+function memoryPath(stateDir, port) {
+    return join(stateDir, `attach-${String(port)}.json`);
+}
+/** The record for a port. Empty on absent, unreadable, or malformed state. */
+function read(stateDir, port) {
+    try {
+        const parsed = JSON.parse(readFileSync(memoryPath(stateDir, port), 'utf8'));
+        if ('object' !== typeof parsed || null === parsed)
+            return EMPTY;
+        const record = parsed;
+        return {
+            attached: true === record.attached,
+            enumerated: true === record.enumerated,
+        };
+    }
+    catch {
+        return EMPTY;
+    }
+}
+/** Write the record back, best-effort. A hint must never be the reason a proxy fails to serve. */
+function write(stateDir, port, record) {
+    try {
+        mkdirSync(stateDir, { recursive: true });
+        writeFileSync(memoryPath(stateDir, port), JSON.stringify(record), 'utf8');
+    }
+    catch {
+        // An unwritable state home is already reported elsewhere; it must not break the client path.
+    }
+}
+/** Record that an MCP client started the proxy on this port. */
+export function rememberProxyStarted(stateDir, port) {
+    const known = read(stateDir, port);
+    if (known.attached)
+        return;
+    write(stateDir, port, { ...known, attached: true });
+}
+/**
+ * Record that a client asked for the tool list on this port.
+ *
+ * Enumeration implies attachment — a `tools/list` cannot arrive at a server nobody started — so this
+ * sets both bits, and a record written by an older proxy that only ever set one is still read
+ * correctly.
+ */
+export function rememberEnumerated(stateDir, port) {
+    const known = read(stateDir, port);
+    if (known.enumerated)
+        return;
+    write(stateDir, port, { attached: true, enumerated: true });
+}
+/** Which of the three client-side states this port is in. */
+export function attachState(stateDir, port) {
+    const known = read(stateDir, port);
+    if (known.enumerated)
+        return AttachState.ENUMERATED;
+    return known.attached ? AttachState.NEVER_ENUMERATED : AttachState.NEVER_ATTACHED;
+}
+/**
+ * The sentence to print for a state, or `undefined` when there is nothing to fix.
+ *
+ * The healthy case has to stay silent: advice printed beside a working client reads as though
+ * something is still wrong, which is its own kind of lie.
+ */
+export function describeAttachState(state) {
+    if (state === AttachState.NEVER_ENUMERATED)
+        return NEVER_ENUMERATED_ACTION;
+    if (state === AttachState.NEVER_ATTACHED)
+        return NEVER_ATTACHED_ACTION;
+    return undefined;
+}
+/**
+ * The client-side fields for one `status` run.
+ *
+ * The state is reported on EVERY run, healthy included — "the client has read the tools" is the
+ * fact that was missing, and reporting it only when broken leaves the reader unable to tell a
+ * healthy client from a version too old to look. The advice rides along only when there is any.
+ */
+export function attachStatusFields(stateDir, port) {
+    const state = attachState(stateDir, port);
+    const action = describeAttachState(state);
+    // OMITTED rather than undefined: `exactOptionalPropertyTypes` is on, and an absent key is also
+    // what keeps the healthy line to one fact.
+    return { mcpClient: state, ...(action === undefined ? {} : { mcpClientAction: action }) };
+}

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

@@ -47,13 +47,6 @@ export declare class PendingRequests {
  * with the MCP server still perfectly alive. An agent cannot tell that apart from "still working".
  */
 export declare function streamLossReplies(pending: PendingRequests, reason: string, nextStep?: string): string[];
-/**
- * The one shape every "the transport ate your call" answer takes, whichever leg died.
- *
- * `nextStep` is appended when the caller knows one. Without it this reply describes a condition and
- * stops there, which is all a first-run user got out of their first ever tool call.
- */
-export declare function transportLossReply(id: unknown, reason: string, nextStep?: string): string;
 /**
  * How long a request may sit in the queue, unsent, before the proxy answers it itself.
  *