@reticlehq/server 2.13.0 → 2.14.0

package/dist/session/session-health.js

@@ -1,4 +1,61 @@
-import { BrowserBrand, BUFFER_EVICTION_WARNING, THROTTLED_WARNING } from '@reticlehq/core';
+import { BrowserBrand, EventType, BUFFER_EVICTION_WARNING, THROTTLED_STARVED_NOTE, THROTTLED_WARNING, } from '@reticlehq/core';
+/**
+ * How long a request may be in flight before it is worth reporting on session health.
+ *
+ * A drive always has requests in the air, so a low bar puts a scary number on every healthy session
+ * and trains agents to ignore the field — the same way a guard that fires on routine controls trains
+ * them to pass `confirmDangerous` reflexively.
+ *
+ * 10s, and it is a HEURISTIC with no clean separation available: "a slow endpoint" and "a server
+ * that will never answer" are the same observation until one of them finishes. The number is chosen
+ * to sit between the two things actually measured, not derived from anything.
+ *
+ * Below it: this repo's own battery runs its API with `REFLECT_MS=6000` on purpose, and at the 5s
+ * this first shipped with, a healthy app with one slow route was permanently non-nominal and carried
+ * a scary number on every result.
+ *
+ * Above it: both reported wedges — 10.4s on one, 170s+ on the other. 10.4s clears this by 400ms,
+ * which is thin, and an app with an 8-second endpoint will not be warned about a wedge until 10s.
+ * That is the trade: an over-firing field gets ignored, and a field nobody reads catches nothing.
+ */
+export const PENDING_NAVIGATION_NOTICE_MS = 10_000;
+/**
+ * Said beside `dispatched` / `settled` on a skewed session, because those fields read as success.
+ *
+ * The reporter's own account of the cost: "the false-positive dispatch confirmation is what cost the
+ * most time — I trusted `dispatched: true, domMutatedWithin: Nms` as real signal for a long time
+ * before suspecting the skew banner." Stating the contradiction is the whole job here; the existing
+ * banner was accurate and simply never appeared where it was needed.
+ */
+const SKEW_VERDICT_WARNING = 'version skew: `dispatched` and `settled` on this session mean the event was sent, NOT that the ' +
+    'app acted on it — a skewed pair drops actions silently. Re-read the control (aria-checked, ' +
+    'data-state, its text) before trusting any verdict from this session, and converge the versions:';
+/**
+ * The age of the oldest request that STARTED and never completed, or undefined when there is none
+ * worth reporting.
+ *
+ * Matched on request id, the way `detectHungRequests` and the route oracle's `unansweredIn` do: a
+ * NET_PENDING with no NET_REQUEST carrying the same id. Three readings of one fact is two too many,
+ * but they read different windows — this one is the whole session, which is the point: a wedge that
+ * began before the current action is exactly the case a per-window reading cannot see.
+ */
+export function pendingNavigationMs(events, nowMs) {
+    const settled = new Set();
+    for (const e of events)
+        if (e.type === EventType.NET_REQUEST)
+            settled.add(e.data['id']);
+    let oldest;
+    for (const e of events) {
+        if (e.type !== EventType.NET_PENDING || settled.has(e.data['id']))
+            continue;
+        if (oldest === undefined || e.t < oldest)
+            oldest = e.t;
+    }
+    if (oldest === undefined)
+        return undefined;
+    const age = nowMs - oldest;
+    return age >= PENDING_NAVIGATION_NOTICE_MS ? age : undefined;
+}
 /**
  * Buffer-honesty envelope for observe/network/console. When the ring buffer has evicted anything
  * (age/size cap), a "no such event" answer may be a false negative — so we attach the drop count and
@@ -20,9 +77,21 @@ export function bufferEnvelope(session) {
  */
 export function healthEnvelope(session) {
     const health = session.health();
-    const nominal = !health.throttled && health.focused && health.recommendation === undefined;
+    // A request stuck in flight makes a session non-nominal even when the tab is fine, because it is
+    // the one condition where every observation is about to be about a page that is not moving.
+    const nominal = !health.throttled &&
+        health.focused &&
+        health.recommendation === undefined &&
+        health.pendingNavigationMs === undefined &&
+        health.versionSkew === undefined;
     if (nominal)
         return {};
+    // Skew outranks the throttle warning when both hold: a throttled tab makes a reading unreliable,
+    // a skewed link makes the ACTION unreliable, and there is no point warning about the quality of an
+    // observation of something that may never have happened.
+    if (health.versionSkew !== undefined) {
+        return { session: health, warning: `${SKEW_VERDICT_WARNING} ${health.versionSkew}` };
+    }
     return health.throttled ? { session: health, warning: THROTTLED_WARNING } : { session: health };
 }
 /**
@@ -50,12 +119,23 @@ const STARVED_WAIT_NOTE = ' (the tab was throttled during this wait, so starvati
  * Suffix the starvation note onto a FAILED predicate verdict when the tab is throttled. A pass is
  * returned untouched — starvation is context for a failure, not a reason to doubt a hold. Pure and
  * generic over the verdict shape so assert/wait_for/act_and_wait share one rule.
+ *
+ * The sentence FOLLOWS the field, and does not decide for itself. `annotateThrottledMiss`
+ * (predicate.ts) owns the question of whether this failure was reached by not having seen
+ * something, which is the only reading a starved tab casts doubt on; it stamps
+ * `THROTTLED_STARVED_NOTE` when it was. Deciding again here got two answers to one question:
+ * an `absent: true` assertion that MATCHED 13 elements was graded honestly in the field an agent
+ * gates on, and told in prose that the tab may never have rendered. It also doubled up on a failure
+ * that already carried a more specific reason (an unreadable locator, a superseded window), where
+ * the concrete diagnosis is the one that should lead.
  */
 export function annotateStarvedFailure(session, verdict) {
     if (true === verdict.pass || verdict.failureReason === undefined)
         return verdict;
     if (true !== session.throttled())
         return verdict;
+    if (THROTTLED_STARVED_NOTE !== verdict.inconclusive)
+        return verdict;
     return { ...verdict, failureReason: `${verdict.failureReason}${STARVED_WAIT_NOTE}` };
 }
 /**

package/dist/session/session-manager.d.ts

@@ -1,7 +1,8 @@
-import type { NoSessionReason } from '@reticlehq/core';
+import type { NoSessionReason } from '@reticlehq/core/telemetry';
 import { Session, type SessionInfo } from './session.js';
 import { AttachmentHistory } from './attachment-history.js';
 import type { NoSessionNextAction } from './no-session-next-action.js';
+import { type SessionIdentity } from './session-successor.js';
 /**
  * The agent's active project, used to scope auto-selection. `projectId` is the stable build-stamped
  * identity (authoritative when present); `url` is the app origin, a fallback hint for older SDKs that
@@ -61,6 +62,15 @@ export declare class SessionManager {
      * vanished rather than about the daemon's lifetime history (#611).
      */
     lastDeparted(): string | undefined;
+    /**
+     * The session that most recently disappeared — id, last URL, project — or undefined.
+     *
+     * `lastDeparted` is the id alone, which is what lease-expiry attribution needs. This is the
+     * rest: a route that 500s tears the page down and the SDK never reconnects, and without the
+     * URL `reticle_sessions` is an empty list with no history (#808). Tombstones, not live rows:
+     * a connected tab is in `list()`, not here.
+     */
+    lastKnown(): SessionIdentity | undefined;
     resolve(sessionId?: string, scope?: ResolveScope): Session;
 }
 export {};

package/dist/session/session-manager.js

@@ -303,9 +303,20 @@ export class SessionManager {
      * vanished rather than about the daemon's lifetime history (#611).
      */
     lastDeparted() {
+        return this.lastKnown()?.id;
+    }
+    /**
+     * The session that most recently disappeared — id, last URL, project — or undefined.
+     *
+     * `lastDeparted` is the id alone, which is what lease-expiry attribution needs. This is the
+     * rest: a route that 500s tears the page down and the SDK never reconnects, and without the
+     * URL `reticle_sessions` is an empty list with no history (#808). Tombstones, not live rows:
+     * a connected tab is in `list()`, not here.
+     */
+    lastKnown() {
         let last;
-        for (const id of this.#tombstones.keys())
-            last = id;
+        for (const record of this.#tombstones.values())
+            last = record;
         return last;
     }
     /**
@@ -324,8 +335,12 @@ export class SessionManager {
     #unknownSessionError(sessionId) {
         const live = [...this.#sessions.values()];
         if (0 === live.length) {
+            const known = this.lastKnown();
+            const where = undefined === known ? '' : ` Last seen on ${known.url}.`;
             return (`no connected session with id '${sessionId}', and no sessions are connected at all — so ` +
-                'there is no other id to retry with. The app is not dialling this daemon; call ' +
+                'there is no other id to retry with.' +
+                where +
+                ' The app is not dialling this daemon; call ' +
                 'reticle_sessions for the diagnosis rather than retrying this call.');
         }
         const named = live.map((s) => `'${s.id}' (${s.url})`).join(', ');

package/dist/session/session-replaced.d.ts

@@ -0,0 +1,24 @@
+/**
+ * "The page reconnected under the same id" — one sentence, and one way to recognise it.
+ *
+ * A server-rendered app reconnects its SDK on EVERY full page load, so on an MPA this is the normal
+ * consequence of following a link, not a fault. The bridge rejects any command that was in flight
+ * when it happens, and a caller that reads that rejection as fatal cannot walk past the first link:
+ * reported against `reticle_verify action=crawl`, which died on link one of every Django, Rails and
+ * plain-HTML app.
+ *
+ * The prefix lives here so the producer and the predicate cannot drift apart. This repo has already
+ * shipped that exact bug twice — a remedy string restated in a second place, and a redaction name
+ * derived two different ways — and both times the halves disagreed silently.
+ */
+/** The start of the reason the bridge hands to commands displaced by a reconnect. */
+export declare const SESSION_REPLACED_PREFIX = "session replaced by a newer connection";
+/** Build the full reason. The only place this sentence is written. */
+export declare function sessionReplacedReason(id: string, url: string): string;
+/**
+ * Was this failure a reconnect rather than a fault?
+ *
+ * Accepts the thrown value rather than a string so every call site can hand over whatever it caught
+ * without each one re-deriving a message — an `Error`, a bare string, or something else entirely.
+ */
+export declare function isSessionReplacedError(error: unknown): boolean;

package/dist/session/session-replaced.js

@@ -0,0 +1,29 @@
+/**
+ * "The page reconnected under the same id" — one sentence, and one way to recognise it.
+ *
+ * A server-rendered app reconnects its SDK on EVERY full page load, so on an MPA this is the normal
+ * consequence of following a link, not a fault. The bridge rejects any command that was in flight
+ * when it happens, and a caller that reads that rejection as fatal cannot walk past the first link:
+ * reported against `reticle_verify action=crawl`, which died on link one of every Django, Rails and
+ * plain-HTML app.
+ *
+ * The prefix lives here so the producer and the predicate cannot drift apart. This repo has already
+ * shipped that exact bug twice — a remedy string restated in a second place, and a redaction name
+ * derived two different ways — and both times the halves disagreed silently.
+ */
+/** The start of the reason the bridge hands to commands displaced by a reconnect. */
+export const SESSION_REPLACED_PREFIX = 'session replaced by a newer connection';
+/** Build the full reason. The only place this sentence is written. */
+export function sessionReplacedReason(id, url) {
+    return `${SESSION_REPLACED_PREFIX} claiming the same id (${id}) from ${url}`;
+}
+/**
+ * Was this failure a reconnect rather than a fault?
+ *
+ * Accepts the thrown value rather than a string so every call site can hand over whatever it caught
+ * without each one re-deriving a message — an `Error`, a bare string, or something else entirely.
+ */
+export function isSessionReplacedError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return message.includes(SESSION_REPLACED_PREFIX);
+}

package/dist/session/session-successor.js

@@ -73,13 +73,29 @@ export function pickDocumentSuccessor(live, departed) {
     const origin = originOf(departed.url);
     if (origin === undefined)
         return undefined;
+    // A candidate must belong to the same app. `sessionStorage` is scoped to the ORIGIN rather than
+    // the app, so recycling a port (stop app A on :3000, start app B, reload the tab) has app B read
+    // app A's id out of storage and register under it with its own projectId. The guard was on the
+    // candidate search only, and a matching id returned before it ran — so an explicit sessionId was
+    // answered by a different product, and every observation afterwards was about the wrong app
+    // (#785).
+    const sameProject = (s) => departed.projectId === undefined || s.projectId === departed.projectId;
     const atOrigin = live.filter((s) => originOf(s.url) === origin);
     const sameId = atOrigin.find((s) => s.id === departed.id);
+    // `mayInherit` deliberately does NOT apply here. It asks whether ANOTHER session may take over a
+    // claimed identity, and a matching id is not another session — it is this one, reconnecting with
+    // the id that survived in sessionStorage. The claim lives in a URL PARAM, which an ordinary
+    // navigation drops (`navigate { url, reload: true }` reloads the bare address), so demanding it
+    // again would refuse the reload this whole mechanism exists for. A leased context has its own
+    // sessionStorage, so a human's tab cannot pick the id up that way — only by carrying the param,
+    // which satisfies `mayInherit` anyway. The gate would cost the ordinary case and buy nothing.
+    //
+    // Refusal, not a second guess, when the project does not match: an exact id match belonging to
+    // another app is the strongest evidence there is that the caller's id is stale, so falling
+    // through to whatever else sits on the origin would be the silent redirect this prevents.
     if (sameId !== undefined)
-        return sameId;
-    const others = atOrigin.filter((s) => s.id !== departed.id &&
-        (departed.projectId === undefined || s.projectId === departed.projectId) &&
-        mayInherit(departed, s));
+        return sameProject(sameId) ? sameId : undefined;
+    const others = atOrigin.filter((s) => s.id !== departed.id && sameProject(s) && mayInherit(departed, s));
     if (1 !== others.length)
         return undefined;
     return others[0];

package/dist/session/session.d.ts

@@ -43,6 +43,15 @@ export declare class Session {
     hasCapabilities: boolean;
     /** Set when the page's SDK version differs from the daemon's (see version-skew.ts). */
     versionSkew?: string;
+    /** SDK version from HELLO; kept so a remedy can check it applies — see body-capture-remedy.ts. */
+    sdkVersion?: string | undefined;
+    /** Whether the page records network bodies; undefined on an SDK too old to say. See HELLO. */
+    captureBodies?: boolean | undefined;
+    /**
+     * Whether this build stamps `data-reticle-source`, when the build plugin said. See HELLO.
+     * `false` separates "the project turned it off" from "nothing provides one"; undefined is unknown.
+     */
+    sourceMapping?: boolean | undefined;
     /**
      * Extra key names this app declared sensitive via `connect({ redact: { keys } })`. Held so the
      * DRIVEN path can redact them too — a request body the daemon captures from the network stack
@@ -86,6 +95,9 @@ export declare class Session {
     get currentDocumentId(): string | undefined;
     /** The edit epoch the most recent stamped event was observed under. See `#editEpoch`. */
     get currentEditEpoch(): number | undefined;
+    /** Seed/auth precondition failure reason, if any. */
+    setPreconditionFailure(reason: string): void;
+    preconditionFailure(): string | undefined;
     /** Re-stamp an incoming event with server-relative time, buffer it, and fan out. */
     pushEvent(event: ReticleEvent, byteSize?: number): void;
     recordActedRef(ref: string): void;
@@ -264,9 +276,5 @@ export declare class Session {
     /** Wired by SessionManager.add, the one place every session registers. */
     setViewers(read: () => Session[]): void;
 }
-/**
- * Re-exported from session-manager.ts so the public import path (`./session.js`) is unchanged for
- * the many call sites that resolve a target session. The class lives in its own file to keep both
- * units under the file-size cap.
- */
+/** Re-exported so the public import path (`./session.js`) is unchanged. */
 export { SessionManager } from './session-manager.js';

package/dist/session/session.js

@@ -3,7 +3,7 @@ import { LastAct } from './last-act.js';
 import { GapLedger } from '../honesty/gap-ledger.js';
 import { CaptureLedger } from '../honesty/feature-capture.js';
 import { commandTimeoutMessage } from './command-timeout.js';
-import { readHealthEvent } from './session-health.js';
+import { readHealthEvent, pendingNavigationMs } from './session-health.js';
 import { MIRRORED_COMMANDS, mirroredNarration } from './session-mirror.js';
 /** The HUD does not need 200 frames to watch a counter climb; the last state always lands. */
 const IMPACT_PUSH_DEBOUNCE_MS = 700;
@@ -86,6 +86,15 @@ export class Session {
     hasCapabilities;
     /** Set when the page's SDK version differs from the daemon's (see version-skew.ts). */
     versionSkew;
+    /** SDK version from HELLO; kept so a remedy can check it applies — see body-capture-remedy.ts. */
+    sdkVersion;
+    /** Whether the page records network bodies; undefined on an SDK too old to say. See HELLO. */
+    captureBodies;
+    /**
+     * Whether this build stamps `data-reticle-source`, when the build plugin said. See HELLO.
+     * `false` separates "the project turned it off" from "nothing provides one"; undefined is unknown.
+     */
+    sourceMapping;
     /**
      * Extra key names this app declared sensitive via `connect({ redact: { keys } })`. Held so the
      * DRIVEN path can redact them too — a request body the daemon captures from the network stack
@@ -128,28 +137,16 @@ export class Session {
     #journalReader;
     /** What this session has learned by watching its own stream: ambient churn + blind-spot levels. */
     #observed = new ObservedState();
+    /** Set when a required application precondition (e.g. seedStorage) was not established. */
+    #preconditionFailure;
     /**
      * Which document is on screen right now — the one the most recent stamped event was observed under.
-     *
-     * DERIVED, never announced. The SDK mints a document id once per real document and stamps it on
-     * every event, so the stream already carries the answer; asking the page for it separately would be
-     * a second source of truth that can disagree with the evidence it is supposed to scope. A full
-     * navigation or a reload builds a new document, mints a new id, and the first event carrying it
-     * moves this forward — which is exactly the moment the previous document's evidence stops being
-     * about the world. An SPA route change keeps the same document and so keeps the same id, which is
-     * correct rather than a limitation: same JavaScript context, same in-flight requests, same evidence.
-     *
-     * An UNSTAMPED event never clears this. An SDK older than the field stamps nothing, and letting one
-     * such event blank the current document would make every later comparison vacuous.
+     * DERIVED, never announced: the SDK stamps it on events. An unstamped event never clears this.
      */
     #documentId;
     /**
-     * The edit epoch of the most recent stamped event. DERIVED for the same reason `#documentId` is:
-     * the stream already carries it, and asking the page separately would be a second source of truth.
-     *
-     * A hot update advances it INSIDE the same document, which is the case `#documentId` structurally
-     * cannot see — no navigation, same page, replaced code. An unstamped event never clears it: most
-     * pages have no hot-update channel at all, so absence is "unknown", never "back to no edits".
+     * The edit epoch of the most recent stamped event. DERIVED for the same reason `#documentId` is.
+     * A hot update advances it inside the same document. An unstamped event never clears it.
      */
     #editEpoch;
     constructor(hello, socket, clock) {
@@ -159,6 +156,7 @@ export class Session {
         this.title = hello.title;
         this.adapters = hello.adapters;
         this.hasCapabilities = hello.hasCapabilities ?? false;
+        this.sourceMapping = hello.sourceMapping;
         this.redactKeys = hello.redactKeys ?? [];
         this.#socket = socket;
         this.#clock = clock;
@@ -214,10 +212,17 @@ export class Session {
     }
     /** The attachable health block — single source of truth for the tools. */
     health() {
+        // From event t=0, not a cursor: a wedge that began before the current action is exactly the
+        // case a per-window reading cannot see, and is the one both reporters hit.
+        const stuck = pendingNavigationMs(this.eventsSince(0), this.elapsed());
         const base = {
             lastSeenMs: this.lastSeenMs(),
             throttled: this.throttled(),
             focused: this.#focused,
+            ...(stuck === undefined ? {} : { pendingNavigationMs: stuck }),
+            // Carried onto every act/assert result, not just reticle_sessions: skew drops actions
+            // SILENTLY, and the fields it contradicts are on the act verdict.
+            ...(this.versionSkew === undefined ? {} : { versionSkew: this.versionSkew }),
         };
         // attach the escape-hatch hint only when un-scriptable (keeps field absent otherwise).
         const recommendation = buildSessionRecommendation({
@@ -268,6 +273,13 @@ export class Session {
     get currentEditEpoch() {
         return this.#editEpoch;
     }
+    /** Seed/auth precondition failure reason, if any. */
+    setPreconditionFailure(reason) {
+        this.#preconditionFailure = reason;
+    }
+    preconditionFailure() {
+        return this.#preconditionFailure;
+    }
     /** Re-stamp an incoming event with server-relative time, buffer it, and fan out. */
     pushEvent(event, byteSize) {
         if (event.documentId !== undefined)
@@ -875,9 +887,5 @@ export class Session {
         }
     }
 }
-/**
- * Re-exported from session-manager.ts so the public import path (`./session.js`) is unchanged for
- * the many call sites that resolve a target session. The class lives in its own file to keep both
- * units under the file-size cap.
- */
+/** Re-exported so the public import path (`./session.js`) is unchanged. */
 export { SessionManager } from './session-manager.js';

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

@@ -40,7 +40,7 @@ export interface PlatformPaths {
     readonly linux: string;
     readonly win32: string;
 }
-export interface AgentClient {
+interface AgentClient {
     readonly id: string;
     readonly name: string;
     readonly confidence: AgentConfidence;
@@ -68,7 +68,7 @@ export interface AgentPlanStep {
     readonly entry?: Readonly<Record<string, unknown>> | undefined;
     readonly why: string;
 }
-export interface AgentPlanInput {
+interface AgentPlanInput {
     readonly home: string;
     readonly platform: keyof PlatformPaths;
     readonly exists: (path: string) => boolean;
@@ -94,3 +94,4 @@ export declare const joinFor: (os: keyof PlatformPaths) => ((...parts: string[])
  * makes the Windows rows testable from any machine.
  */
 export declare function planAgentConfigs(input: AgentPlanInput): AgentPlanStep[];
+export {};

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

@@ -17,7 +17,7 @@ export interface AgentWriterIo {
     readonly writeFile: (path: string, contents: string) => void;
     readonly mkdirp: (dir: string) => void;
 }
-export interface AgentWriteResult {
+interface AgentWriteResult {
     readonly id: string;
     readonly name: string;
     readonly file: string;
@@ -35,7 +35,7 @@ export interface AgentWriteResult {
 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 {
+interface SkillWriteResult {
     readonly id: string;
     readonly file: string;
 }
@@ -49,3 +49,4 @@ export declare function applyAgentSkills(io: AgentWriterIo, where: {
     readonly home: string;
     readonly platform: keyof PlatformPaths;
 }): SkillWriteResult[];
+export {};

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

@@ -33,7 +33,7 @@ export interface MigrationDeps {
     readonly version: string;
     readonly log: (event: string, data: Record<string, unknown>) => void;
 }
-export interface MigrationResult {
+interface MigrationResult {
     readonly ran: boolean;
     readonly granted: readonly string[];
     readonly deferred: readonly string[];
@@ -45,3 +45,4 @@ export interface MigrationResult {
  * re-scan on every editor launch for the rest of the version's life.
  */
 export declare function migrateApprovals(deps: MigrationDeps): MigrationResult;
+export {};

package/dist/setup/approval-migration.js

@@ -47,7 +47,7 @@ export function migrateApprovals(deps) {
     }
     let results = [];
     try {
-        results = grantAutoApproval(io, { home, platform }, undefined, { onlyIfNoSupersede: true });
+        results = grantAutoApproval(io, { home, platform });
     }
     catch {
         return NOTHING;

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

@@ -13,9 +13,12 @@
  *    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.
+ * 2. Nothing is CREATED where the file itself takes over settings we cannot read — Cursor's
+ *    permissions.json supersedes its in-app allowlist and pins the run mode to Allowlist, so a user
+ *    who ran everything without asking loses that and cannot switch back while the file exists.
+ *    Merging into one they already have is fine; making one is not, so that case is DEFERRED with
+ *    the in-app step to take instead. Nothing is written at all for an agent that is not installed:
+ *    an absent agent has no Accept button to remove.
  *
  * 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
@@ -36,8 +39,8 @@ export interface ApprovalGrant {
     /** 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.
+     * True where CREATING this file supersedes in-app settings we can neither read nor restore. Such
+     * a grant is only ever merged into a file the user already owns, never created.
      */
     readonly supersedesInApp?: boolean;
 }
@@ -60,26 +63,15 @@ export interface ApprovalResult {
     /** Set where the user has to be told something the write alone does not say. */
     readonly warn?: string;
 }
-export interface ApprovalWhere {
+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[];
+export declare function grantAutoApproval(io: AgentWriterIo, where: ApprovalWhere, grants?: readonly ApprovalGrant[]): ApprovalResult[];
+export {};

package/dist/setup/auto-approve.js

@@ -13,9 +13,12 @@
  *    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.
+ * 2. Nothing is CREATED where the file itself takes over settings we cannot read — Cursor's
+ *    permissions.json supersedes its in-app allowlist and pins the run mode to Allowlist, so a user
+ *    who ran everything without asking loses that and cannot switch back while the file exists.
+ *    Merging into one they already have is fine; making one is not, so that case is DEFERRED with
+ *    the in-app step to take instead. Nothing is written at all for an agent that is not installed:
+ *    an absent agent has no Accept button to remove.
  *
  * 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
@@ -54,8 +57,11 @@ export const APPROVAL_GRANTS = [
         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.
+        // for that type" — and in practice it costs more than that. A non-empty mcpAllowlist also locks
+        // the run mode to Allowlist, so a user who had Run Everything ("YOLO") on loses it and cannot
+        // turn it back on while the file exists; Cursor has acknowledged that as their bug. Merging into
+        // a file the user already made is safe — they are already in Allowlist mode. Creating one is
+        // not, so we never do: see the DEFERRED branch below.
         supersedesInApp: true,
         grant: (c) => addToList(c, null, 'mcpAllowlist', `${RETICLE_KEY}:*`),
     },
@@ -107,7 +113,7 @@ export const ApprovalOutcome = {
  * 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 = {}) {
+export function grantAutoApproval(io, where, grants = APPROVAL_GRANTS) {
     const join = joinFor(where.platform);
     return grants.map((grant) => {
         const file = join(where.home, grant.paths[where.platform]);
@@ -117,11 +123,11 @@ export function grantAutoApproval(io, where, grants = APPROVAL_GRANTS, options =
             return { ...base, outcome: ApprovalOutcome.ABSENT };
         try {
             const existed = io.exists(file);
-            if (true === options.onlyIfNoSupersede && true === grant.supersedesInApp && !existed) {
+            if (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`,
+                    warn: `left ${grant.name}'s approvals alone — creating ${file} would take over its in-app settings and pin the run mode to Allowlist. If ${grant.name} asks before every reticle tool call, add \`${RETICLE_KEY}:*\` under Settings → Agents → Approvals & Execution (nothing to do if you run everything already).`,
                 };
             }
             // A settings file we cannot parse is left exactly as it is. Reformatting somebody's config to
@@ -134,10 +140,7 @@ export function grantAutoApproval(io, where, grants = APPROVAL_GRANTS, options =
                 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 }) };
+            return { ...base, outcome: ApprovalOutcome.GRANTED };
         }
         catch (err) {
             return {

package/dist/{init → setup}/confirm.js

@@ -31,7 +31,7 @@
 import { InitConfirmation, RETICLE_DEFAULT_PORT } from '@reticlehq/core';
 import { fetchStatus, summarizeStatus } from '../cli/cli-launch.js';
 import { readDevServers } from '../daemon/dev-servers.js';
-import { devServersForProject } from '@reticlehq/core';
+import { devServersForProject } from '@reticlehq/core/artifacts';
 import { readProjectId } from '../cli/cli-port.js';
 import { reticleStateHome } from '../daemon/daemon.js';
 import { reportInitOutcome } from '../telemetry/init-telemetry.js';

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

@@ -24,7 +24,7 @@ export declare const AppShape: {
 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 {
+interface ShapeEvidence {
     /** `src-tauri/tauri.conf.json` exists. */
     readonly hasTauriConf: boolean;
     /** `electron` is a dependency or devDependency. */
@@ -44,7 +44,7 @@ export declare function isDesktopOrigin(url: string): boolean;
  * 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 {
+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. */
@@ -55,3 +55,4 @@ export interface ShapePolicy {
     readonly note: string | undefined;
 }
 export declare function policyFor(shape: AppShape): ShapePolicy;
+export {};