@reticlehq/server 2.4.0 → 2.5.0

package/dist/index.js

@@ -2,10 +2,11 @@ import { join } from 'node:path';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { AGENT_STOPPED_NOTICE, RETICLE_DEFAULT_PORT, ReticleCommand, ReticleDir, ReticleEnv, LOOPBACK_HOST, ReplayStatus, EventType, } from '@reticlehq/core';
 import { originOf } from './session/session-manager.js';
+import { setBrowserMode, BrowserMode } from './telemetry/browser-mode.js';
 import { replayNamedFlow } from './flows/flow-tools.js';
 import { createSharedServer } from './http-server.js';
-import { resolveBridgeSecurityWithAutoToken } from './bridge-security.js';
-import { Bridge } from './bridge.js';
+import { resolveBridgeSecurityWithAutoToken } from './bridge/bridge-security.js';
+import { Bridge } from './bridge/bridge.js';
 import { BaselineStore } from './project/baselines.js';
 import { RecordingStore } from './flows/recordings.js';
 import { FlowStore } from './flows/flows.js';
@@ -17,15 +18,18 @@ import { ReticleRunner } from './runs/reticle-runner.js';
 import { createRunnerPort } from './runs/runner-port.js';
 import { RunStore } from './runs/run-store.js';
 import { startVerifyServer } from './runs/verify-server.js';
-import { createMcpServer } from './mcp.js';
+import { createMcpServer } from './mcp/mcp.js';
 import { SessionReaper, endAllSessions, MCP_DISCONNECT_SUMMARY } from './session/session-reaper.js';
-import { resolveToolProfile } from './tools/profiles.js';
+import { wireSessionScope } from './session/no-session-watch.js';
+import { buildIdlePredicate } from './daemon/daemon-usefulness.js';
+import { resolveToolSurface } from './tools/tool-surface.js';
+import { statusPayload } from './status-payload.js';
 import { CdpRealInputProvider, LaunchedRealInputProvider } from './input/real-input.js';
 import { cpus } from 'node:os';
 import { BrowserPool } from './pool/browser-pool.js';
 import { playwrightLauncher, resolveMaxContexts } from './pool/playwright-launcher.js';
 import { LeaseReaper } from './pool/lease-reaper.js';
-import { readJournalEnabled, readProjectId } from './cli-port.js';
+import { readJournalEnabled, readProjectId } from './cli/cli-port.js';
 import { makeJournalAttach } from './journal/attach-journal.js';
 import { makeSessionEnd } from './journal/session-end.js';
 import { AmbientStore } from './journal/ambient-store.js';
@@ -41,7 +45,7 @@ function replayVerdictLine(result) {
 }
 export { ReticleTool } from './tools/tool-names.js';
 export { RingBuffer } from './events/ring-buffer.js';
-export { Bridge } from './bridge.js';
+export { Bridge } from './bridge/bridge.js';
 export { Session, SessionManager } from './session/session.js';
 export { buildSessionRecommendation } from './session/session-recommendation.js';
 export { TOOLS } from './tools/tools.js';
@@ -61,9 +65,9 @@ export { MCP_SSE_PATH, MCP_MESSAGE_PATH } from '@reticlehq/core';
 export { BrowserPool, DEFAULT_LEASE_TTL_MS } from './pool/browser-pool.js';
 export { playwrightLauncher, resolveMaxContexts } from './pool/playwright-launcher.js';
 export { appendReticleParams } from './tools/lease-tools.js';
-export { writePid, removePid, isRunning, logPath, readPid, isAlive } from './daemon.js';
+export { writePid, removePid, isRunning, logPath, readPid, isAlive } from './daemon/daemon.js';
 export { scrollToFind } from './input/scroll-find.js';
-export { CORE_TOOL_NAMES, TOOL_PROFILE, TOOL_PROFILE_ENV, filterTools, resolveToolProfile, } from './tools/profiles.js';
+export { CORE_TOOL_NAMES, TOOL_SURFACE, TOOL_PROFILE_ENV, filterTools, resolveToolSurface, } from './tools/tool-surface.js';
 export { AnnotationStore } from './flows/annotation-store.js';
 export { replayFlow, nearestTestid } from './flows/flow-replay.js';
 export { ensureReticleDir, writeContract, readContract, reticleDirPaths, flowPath, baselinePath, } from './project/reticle-dir.js';
@@ -84,14 +88,14 @@ export { buildReactionReport } from './events/reaction.js';
 export { CdpRealInputProvider, LaunchedRealInputProvider, DriveError, performGesture, boxCenter, isPointerAction, } from './input/real-input.js';
 /** Default localhost port for the verify HTTP endpoint (see docs/platform-integration.md). */
 export const RETICLE_VERIFY_DEFAULT_PORT = 7331;
-export { resolveBridgeSecurity } from './bridge-security.js';
+export { resolveBridgeSecurity } from './bridge/bridge-security.js';
 /**
  * Build the shared browser pool (one headless Chromium, N capped isolated leased contexts). Lazy —
  * no Chromium launches until the first lease — so creating it is free even when never used.
  */
 function createBrowserPool(headless) {
     const maxContexts = resolveMaxContexts(process.env[ReticleEnv.MAX_CONTEXTS], cpus().length);
-    const genSessionId = () => `lease-${typeof globalThis.crypto?.randomUUID === 'function'
+    const genSessionId = () => `lease-${'function' === typeof globalThis.crypto?.randomUUID
         ? globalThis.crypto.randomUUID()
         : String(Date.now())}`;
     return new BrowserPool(playwrightLauncher({ headless }), { maxContexts, genSessionId });
@@ -174,6 +178,9 @@ async function resolveRealInput(options, onNavigateError, onNetworkDetail) {
     const driveUrl = options.driveUrl;
     if (driveUrl !== undefined && driveUrl.length > 0) {
         const headless = options.headless ?? true;
+        // The one place that knows. Everything downstream reads it rather than re-deriving it, and a
+        // daemon that launches nothing keeps the default (ATTACHED) rather than guessing.
+        setBrowserMode(headless ? BrowserMode.HEADLESS : BrowserMode.HEADED);
         const injectConnect = options.injectConnect;
         const storageState = options.storageState;
         const factory = options.realInputFactory ??
@@ -254,8 +261,9 @@ export async function start(options = {}) {
             fs,
             reticleRoot,
             now,
+            bridgePort: port,
         };
-        const profile = resolveToolProfile(options.toolProfile);
+        const profile = resolveToolSurface(options.toolProfile);
         const server = createMcpServer(realInput !== undefined ? { ...deps, realInput } : deps, profile);
         // When the agent (the MCP client) disconnects cleanly, end every active session at once so the
         // HUD doesn't linger. (If the agent instead KILLS this process, the WS dies and the browser
@@ -294,11 +302,7 @@ export async function startDaemon(options = {}) {
     // mirror rejection so a port collision can't surface as an unhandled promise rejection.
     void bridge.ready.catch(() => undefined);
     // `reticle status` GETs this for a live, at-a-glance view of connected tabs + their health.
-    shared.attachStatus(() => ({
-        running: true,
-        sessionCount: bridge.sessions.count(),
-        sessions: bridge.sessions.list(),
-    }));
+    shared.attachStatus(() => statusPayload(bridge.sessions.count(), bridge.sessions.list()));
     // Agent-independent presence: the daemon outlives any single agent, so when the LAST agent's MCP
     // connection drops (it stopped, or is waiting on the human), end every session and push a clear
     // "go to your terminal" notice to the panel — the human is on the browser and must not lose a typed
@@ -315,10 +319,9 @@ export async function startDaemon(options = {}) {
     reaper.start();
     // Scope auto-selection to the active project (from .reticle.json) so a stray tab from another app is
     // never picked when the agent omits a sessionId. Explicit per-call scope/sessionId still overrides.
-    const activeProjectId = readProjectId(process.cwd());
-    if (activeProjectId !== undefined) {
-        bridge.sessions.setDefaultScope({ projectId: activeProjectId });
-    }
+    // Scope + the no-session diagnosis: "no browser session connected" is the error that ends most
+    // sessions, and the agent is told to check two things it cannot see. See no-session-diagnosis.ts.
+    wireSessionScope(bridge.sessions, readProjectId(process.cwd()), port);
     const { realInput, owned } = await resolveRealInput(options, () => shared.close(), makeNetworkDetailRouter(bridge, options.driveUrl));
     const fs = createNodeFileSystem();
     const reticleRoot = options.reticleRoot ?? join(process.cwd(), ReticleDir.ROOT);
@@ -342,15 +345,16 @@ export async function startDaemon(options = {}) {
         fs,
         reticleRoot,
         now,
+        bridgePort: port,
     };
-    const profile = resolveToolProfile(options.toolProfile);
+    const profile = resolveToolSurface(options.toolProfile);
     const effectiveDeps = realInput !== undefined ? { ...deps, realInput } : deps;
     shared.attachMcp(() => createMcpServer(effectiveDeps, profile));
     // Optional OEM/CI verify endpoint: a host platform POSTs to /verify and gets an ReticleVerificationRun,
     // driving the same flow-replay machinery the agent uses — no MCP stdio, no human. Each verdict is
     // persisted via RunStore. Localhost-bound + token-guarded. Off unless `reticle serve --http`.
     let verifyHttp;
-    if (options.httpVerify === true) {
+    if (true === options.httpVerify) {
         const runStore = new RunStore(fs, reticleRoot);
         const runner = new ReticleRunner(createRunnerPort(effectiveDeps));
         const token = options.httpVerifyToken ?? process.env[ReticleEnv.VERIFY_TOKEN] ?? '';
@@ -410,9 +414,12 @@ export async function startDaemon(options = {}) {
         ...(realInput !== undefined ? { realInput } : {}),
         ...(verifyHttp !== undefined ? { verifyPort: verifyHttp.port } : {}),
         ...(security.token !== undefined ? { token: security.token } : {}),
-        // Idle = nobody is using the daemon: no agent attached, no browser tab connected, no pool lease.
-        // The daemon entry self-shuts-down after this holds for the grace window (see cli.ts / IdleShutdown).
-        isIdle: () => !agentConnected && bridge.sessions.count() === 0 && pool.activeCount() === 0,
+        // Nobody is using this daemon — self-shuts-down once it holds for the grace window. See
+        // daemon-usefulness.ts for the two ways that can be true.
+        isIdle: buildIdlePredicate(() => agentConnected, bridge.sessions, pool),
+        // Exposed so the shutdown watcher can give an ATTACHED daemon a longer grace. The predicate above
+        // says WHETHER it is idle; this says how long that quiet should be tolerated — see idle-grace.
+        agentAttached: () => agentConnected,
         close: async () => {
             reaper.stop();
             const vh = verifyHttp;

package/dist/init/agent-rules.d.ts

@@ -20,7 +20,7 @@ export declare const AgentRuleStatus: {
     readonly ALREADY: "already";
 };
 export type AgentRuleStatus = (typeof AgentRuleStatus)[keyof typeof AgentRuleStatus];
-export interface AgentRuleResult {
+interface AgentRuleResult {
     status: AgentRuleStatus;
     /** Full file content to write when status is APPLY; the unchanged input otherwise. */
     content: string;
@@ -35,3 +35,4 @@ export declare function markedBlock(): string;
 export declare function mergeMarkedInstruction(existing: string | null | undefined): AgentRuleResult;
 /** The Cursor rule file (.mdc): `alwaysApply` keeps the rule in every turn's context. */
 export declare function cursorRuleFile(): string;
+export {};

package/dist/init/agent-rules.js

@@ -10,6 +10,8 @@
  * cross-agent fallback. Idempotent via a marker block — safe to append to an existing file and a
  * re-run is a no-op. Mirrors the apply/already result shape used across init (see cursor.ts).
  */
+import { NPX } from './mcp.js';
+import { RETICLE_NPM_PACKAGE } from '../version/server-version.js';
 /** Project-root instruction files the agent re-reads every session. */
 export const CLAUDE_MD_PATH = 'CLAUDE.md';
 export const AGENTS_MD_PATH = 'AGENTS.md';
@@ -18,19 +20,31 @@ export const CURSOR_RULE_PATH = '.cursor/rules/reticle.mdc';
 /** Markers delimiting the managed block so a re-run is idempotent and the block stays updatable. */
 const RULE_BEGIN = '<!-- reticle:begin (managed by `reticle init` — edit outside these markers) -->';
 const RULE_END = '<!-- reticle:end -->';
+/**
+ * How the agent must INVOKE the CLI.
+ *
+ * `reticle init` installs the SDK packages, never the server — so there is no `reticle` on the
+ * agent's PATH, and every bare `reticle <cmd>` this rule named was an instruction that could not be
+ * followed. Reported from a field sweep: three of them, in the file the agent re-reads every session.
+ *
+ * `npx @reticlehq/server` is the same invocation the MCP registration uses, and it is derived from
+ * the package's own name so the two can never drift apart.
+ */
+const CLI = `${NPX} ${RETICLE_NPM_PACKAGE}`;
 /** The rule body (markdown). States WHEN to verify, HOW, and never-weaken-a-check. */
 const RULE_BODY = `## Verifying with Reticle
 
-This app is instrumented by **Reticle** — an in-app verification layer exposed as \`reticle_*\` MCP tools and the \`reticle\` CLI. Verifying is part of "done", not an optional extra.
+This app is instrumented by **Reticle** — an in-app verification layer exposed as \`reticle_*\` MCP tools and the \`${CLI}\` CLI (run it through npx — Reticle's server is not installed into this project). Verifying is part of "done", not an optional extra.
 
 - **When:** after you build or change any user-facing feature, flow, or UI, verify it with Reticle **before** telling the user it is complete. Reading the code or passing unit tests is not enough — drive the real running app.
 - **How:** drive the actual flow (\`reticle_act\` / \`reticle_act_and_wait\`), then read the observable effect (\`reticle_assert\`, \`reticle_snapshot\`, \`reticle_state\`, \`reticle_network\`). Confirm the change produced the effect it was meant to, with no new console errors or failed requests.
-- **Covered flows:** run \`reticle gate\` — it reports which recorded flows the changed files affect and whether they still pass.
+- **Covered flows:** run \`${CLI} gate\` — it reports which recorded flows the changed files affect and whether they still pass.
 - **Never weaken a check to make it green.** Downgrading, skipping, or deleting an assertion is a finding, not a fix.
 - **If Reticle can't run** (no daemon, or this is not a running web app), say so — do not skip verification silently.
-- **If a tool result carries \`update_available\`, say so.** Reticle checked npm and a newer version exists. Tell the human the version numbers and offer to run \`reticle update\` — between tasks, never mid-verification, because it restarts the daemon and drops the session. Finish what you are doing first.
-- **Wish Reticle could do something? Ask for it with \`reticle_feedback\`.** Reticle is built for agents, so what you find awkward or missing is what decides the roadmap — and you are the only one who can report it, because that thought disappears when your context does. File \`feature_request\` for something that does not exist, \`improvement\` for something that works but costs too many calls. Say what you are actually trying to achieve (\`need\`) and how you work around it today (\`currentApproach\`), and set \`model\` to the model you are running. File it the moment you notice, then carry on — nothing is too minor.
-- **If Reticle itself fails you, tell its maintainers with \`reticle_feedback\`.** A tool that returned something wrong, a thing Reticle could not observe at all, or a verdict you could not act on — file it with a root-cause analysis and the call trace, then carry on with the task. Working around a broken tool in silence is how the same defect survives. This is about defects in *Reticle*; a bug you find in *this app* is Reticle working, and belongs in your report to the user instead.`;
+- **If a tool result carries \`version_skew\`, act on it before trusting anything else.** Two pieces of Reticle are on different wire contracts, so tools can misbehave in ways neither side reports — a green here is not evidence. The field says which pair disagrees and names the exact fix: run \`${CLI} stop\` and retry when the DAEMON is stale, or tell the human to install the matching SDK and restart their dev server when the PAGE is. Do that first, then redo whatever you were verifying.
+- **If a tool result carries \`update_available\`, say so.** Reticle checked npm and a newer version exists. Tell the human the version numbers and offer to run \`${CLI} update\` — between tasks, never mid-verification, because it restarts the daemon and drops the session. Finish what you are doing first.
+- **Wish Reticle could do something? Ask for it with \`reticle_feedback\`.** Reticle is built for agents, so what you find awkward or missing is what decides the roadmap — and you are the only one who can report it, because that thought disappears when your context does. Put the report itself in \`text\` and pick a \`kind\` — both are required: \`feature_request\` for something that does not exist, \`improvement\` for something that works but costs too many calls, \`bug\` for a tool that returned something wrong, \`gap\` for something Reticle could not observe at all, \`ambiguity\` for a verdict you could not act on. Say what you are actually trying to achieve (\`need\`) and how you work around it today (\`currentApproach\`), and set \`model\` to the model you are running. File it the moment you notice, then carry on — nothing is too minor.
+- **If Reticle itself fails you, tell its maintainers with \`reticle_feedback\`.** A tool that returned something wrong, a thing Reticle could not observe at all, or a verdict you could not act on — file it as \`text\` — a root-cause analysis with the call trace — under \`kind: bug\` (wrong result), \`gap\` (could not observe it) or \`ambiguity\` (undecidable verdict), then carry on with the task. Working around a broken tool in silence is how the same defect survives. This is about defects in *Reticle*; a bug you find in *this app* is Reticle working, and belongs in your report to the user instead.`;
 export const AgentRuleStatus = {
     APPLY: 'apply',
     ALREADY: 'already',
@@ -46,15 +60,39 @@ export function markedBlock() {
  */
 export function mergeMarkedInstruction(existing) {
     if (existing !== null && existing !== undefined && existing.includes(RULE_BEGIN)) {
-        return { status: AgentRuleStatus.ALREADY, content: existing };
+        // A block that can never be updated is not managed. Returning ALREADY on sight of the marker
+        // meant a project that ran init once kept that release's rule text forever, so every improvement
+        // reached only new projects — and a rule about a field introduced later (`version_skew`) could
+        // never arrive at all. The markers promise the inside is ours; idempotence comes from comparing
+        // CONTENT instead of presence.
+        return refreshMarkedBlock(existing);
     }
     const block = markedBlock();
-    if (existing === null || existing === undefined || existing.trim().length === 0) {
+    if (null === existing || existing === undefined || 0 === existing.trim().length) {
         return { status: AgentRuleStatus.APPLY, content: block };
     }
     const separator = existing.endsWith('\n') ? '\n' : '\n\n';
     return { status: AgentRuleStatus.APPLY, content: `${existing}${separator}${block}` };
 }
+/**
+ * Swap the managed block for the current one, leaving every character outside the markers alone.
+ *
+ * A malformed file — a begin marker with no end — is left untouched and reported ALREADY. Rewriting
+ * from a marker to end-of-file would eat whatever the human wrote after it, and silently destroying
+ * someone's instruction file is far worse than a stale rule.
+ */
+function refreshMarkedBlock(existing) {
+    const start = existing.indexOf(RULE_BEGIN);
+    const endAt = existing.indexOf(RULE_END, start);
+    if (-1 === endAt)
+        return { status: AgentRuleStatus.ALREADY, content: existing };
+    const current = existing.slice(start, endAt + RULE_END.length);
+    const wanted = markedBlock().trimEnd();
+    if (current === wanted)
+        return { status: AgentRuleStatus.ALREADY, content: existing };
+    const content = `${existing.slice(0, start)}${wanted}${existing.slice(endAt + RULE_END.length)}`;
+    return { status: AgentRuleStatus.APPLY, content };
+}
 /** The Cursor rule file (.mdc): `alwaysApply` keeps the rule in every turn's context. */
 export function cursorRuleFile() {
     return `---

package/dist/init/app-choice.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Which app in a workspace `reticle init` should wire, when the caller says.
+ *
+ * Refusing to guess between several apps is right — instrumenting one silently would leave the rest
+ * unverified while reporting success. But "re-run inside the one you want" is not an answer a
+ * script, a CI step, or an agent that cannot change directory can act on, so the refusal was a dead
+ * end for exactly the callers most likely to hit it.
+ *
+ * A name that is not one of the discovered apps is refused rather than trusted: it is almost always
+ * a typo or a stale path, and wiring a directory that is not an app writes files nothing compiles.
+ */
+type AppChoice = {
+    ok: true;
+    app: string | undefined;
+} | {
+    ok: false;
+    message: string;
+};
+export declare function chooseWorkspaceApp(requested: string | undefined, apps: readonly string[]): AppChoice;
+export {};

package/dist/init/app-choice.js

@@ -0,0 +1,25 @@
+/**
+ * Which app in a workspace `reticle init` should wire, when the caller says.
+ *
+ * Refusing to guess between several apps is right — instrumenting one silently would leave the rest
+ * unverified while reporting success. But "re-run inside the one you want" is not an answer a
+ * script, a CI step, or an agent that cannot change directory can act on, so the refusal was a dead
+ * end for exactly the callers most likely to hit it.
+ *
+ * A name that is not one of the discovered apps is refused rather than trusted: it is almost always
+ * a typo or a stale path, and wiring a directory that is not an app writes files nothing compiles.
+ */
+export function chooseWorkspaceApp(requested, apps) {
+    if (requested === undefined || '' === requested)
+        return { ok: true, app: undefined };
+    // Tab-completion adds a trailing slash; the discovered names never carry one.
+    const wanted = requested.replace(/\/+$/, '');
+    if (apps.includes(wanted))
+        return { ok: true, app: wanted };
+    return {
+        ok: false,
+        message: 0 === apps.length
+            ? `--app ${requested} was given, but no app was found in this workspace`
+            : `--app ${requested} is not one of the apps found here: ${apps.join(', ')}`,
+    };
+}

package/dist/init/astro-host.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Which Astro file owns the document, and therefore where the SDK script belongs.
+ *
+ * The previous rule was "exactly one `.astro` file in `src/layouts/`". Measured on two real Astro
+ * projects, it fired on neither: one has no `src/layouts/` at all and renders from
+ * `src/pages/index.astro`; the other has three files there, two of which are partials. Both got a
+ * printed recipe instead of a working install.
+ *
+ * A file COUNT cannot tell a layout from a partial, and a directory NAME cannot tell you where the
+ * document shell is. `</body>` can — the file that closes the body is the one every page renders
+ * through, and the only place a script reaches the whole app.
+ *
+ * Ambiguity is still refused rather than guessed. Two document shells means two entry points, and
+ * silently instrumenting one of them would leave half the app unverified while reporting success.
+ */
+interface AstroCandidate {
+    path: string;
+    source: string;
+}
+export declare function pickAstroHost(candidates: readonly AstroCandidate[]): AstroCandidate | undefined;
+export {};

package/dist/init/astro-host.js

@@ -0,0 +1,27 @@
+/**
+ * Which Astro file owns the document, and therefore where the SDK script belongs.
+ *
+ * The previous rule was "exactly one `.astro` file in `src/layouts/`". Measured on two real Astro
+ * projects, it fired on neither: one has no `src/layouts/` at all and renders from
+ * `src/pages/index.astro`; the other has three files there, two of which are partials. Both got a
+ * printed recipe instead of a working install.
+ *
+ * A file COUNT cannot tell a layout from a partial, and a directory NAME cannot tell you where the
+ * document shell is. `</body>` can — the file that closes the body is the one every page renders
+ * through, and the only place a script reaches the whole app.
+ *
+ * Ambiguity is still refused rather than guessed. Two document shells means two entry points, and
+ * silently instrumenting one of them would leave half the app unverified while reporting success.
+ */
+/** Tolerant of whitespace and casing: `</body>`, `</BODY >`, `</body\n>`. */
+const CLOSES_BODY = /<\/\s*body\s*>/i;
+/** Layout files win over pages: a page shell is one route, a layout shell is what routes inherit. */
+const LAYOUT_DIR = 'layouts/';
+export function pickAstroHost(candidates) {
+    const owners = candidates.filter((c) => CLOSES_BODY.test(c.source));
+    if (0 === owners.length)
+        return undefined;
+    const layouts = owners.filter((c) => c.path.includes(LAYOUT_DIR));
+    const preferred = layouts.length > 0 ? layouts : owners;
+    return 1 === preferred.length ? preferred[0] : undefined;
+}

package/dist/init/astro-patch.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Pure, conservative patchers for an Astro app: the config gets the token/root `define` and the
+ * raised build target, one layout gets the dev-only connect `<script>`.
+ *
+ * Astro was the last gated framework where `init` printed a correct recipe and applied none of it —
+ * the only ⚠ left on a supported stack, and the user's first session was two hand-copied snippets
+ * away. Astro is Vite-based but renders its own HTML, so the Vite plugin's injection never fires and
+ * there is no entry module to wire: the connect has to live in a page or layout `<script>`, and the
+ * token has to be inlined by the config because nothing else is in the page's path to inject it.
+ *
+ * Both patchers bail to `manual` (the printed recipe) on any shape they do not fully recognise.
+ * Half-editing a build config is worse than a documented manual step.
+ */
+import { type SourcePatch } from './patch-kind.js';
+export declare function patchAstroConfig(source: string): SourcePatch;
+export declare function patchAstroLayout(source: string, port: number | undefined, projectId: string | undefined): SourcePatch;

package/dist/init/astro-patch.js

@@ -0,0 +1,240 @@
+/**
+ * Pure, conservative patchers for an Astro app: the config gets the token/root `define` and the
+ * raised build target, one layout gets the dev-only connect `<script>`.
+ *
+ * Astro was the last gated framework where `init` printed a correct recipe and applied none of it —
+ * the only ⚠ left on a supported stack, and the user's first session was two hand-copied snippets
+ * away. Astro is Vite-based but renders its own HTML, so the Vite plugin's injection never fires and
+ * there is no entry module to wire: the connect has to live in a page or layout `<script>`, and the
+ * token has to be inlined by the config because nothing else is in the page's path to inject it.
+ *
+ * Both patchers bail to `manual` (the printed recipe) on any shape they do not fully recognise.
+ * Half-editing a build config is worse than a documented manual step.
+ */
+import { RETICLE_DEFAULT_PORT, bridgeWsUrl } from '@reticlehq/core';
+import { PatchKind } from './patch-kind.js';
+/** Present in a patched config AND in a hand-followed recipe — so both count as already wired. */
+const CONFIG_MARKER = '__RETICLE_TOKEN__';
+/** Present in a patched layout and in the printed recipe's script. */
+const LAYOUT_MARKER = 'reticle.connect';
+/**
+ * The SDK, declared so Vite pre-bundles it BEFORE the first page load.
+ *
+ * The connect script does `await import('@reticlehq/react')`. Undeclared, Vite meets that import
+ * mid-load, pre-bundles it, and the hashed `/node_modules/.vite/deps/@reticlehq_react.js?v=…` URL
+ * the browser already requested stops existing — the import rejects with "Failed to fetch
+ * dynamically imported module", connect() never runs, and the page looks entirely normal. Measured
+ * on astro-nanostores, intermittent on whether the dep cache was warm. The Vite plugin has declared
+ * the SDK for this exact reason since the bug was first found on React; Astro is hand-patched and
+ * never got it.
+ */
+const SDK_INCLUDE_LITERAL = `'@reticlehq/react'`;
+/**
+ * An `include:` the app already declared — ours joins that array instead of adding a second key.
+ * Deliberately not anchored to a newline: `optimizeDeps: { include: ['x'] }` on one line is the
+ * common way to write it, and requiring a line break made the merge miss it and duplicate the key.
+ */
+const EXISTING_INCLUDE = /(\s*include\s*:\s*\[)/;
+const DEFINE_CONFIG = /defineConfig\s*\(\s*\{/;
+/** A `vite:` key whose value is an object LITERAL — the one shape we can merge into safely. */
+const VITE_OBJECT_KEY = /(^\s*vite\s*:\s*\{)/m;
+/** Any `vite:` key at all. One that is not an object literal (a spread, an imported config) is ours to refuse. */
+const ANY_VITE_KEY = /^\s*vite\s*:/m;
+const BODY_CLOSE = '</body>';
+const HELPER = `
+function reticleToken() {
+  const dir = process.env['RETICLE_PAIRING_TOKEN_DIR'] || join(homedir(), '.reticle');
+  try { return readFileSync(join(dir, 'pairing-token'), 'utf8').trim(); } catch { return ''; }
+}
+`;
+const HELPER_IMPORTS = `import { readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+`;
+/**
+ * The keys we add inside `vite:`, each with what it must contain.
+ *
+ * Kept as a list rather than one blob because a config that already sets one of these must be merged
+ * INTO, not duplicated: the real astro-nanostores config has `build: { chunkSizeWarningLimit }`, and
+ * inserting our own `build` beside it gave the object two — where the last one wins, so
+ * `target: 'es2022'` was silently discarded while init reported success. Losing that target is not
+ * cosmetic: Astro's default down-levels the modern SDK bundle and dies on a destructuring transform.
+ */
+const VITE_KEYS = [
+    { key: 'build', inner: `\n      target: 'es2022',` },
+    {
+        key: 'optimizeDeps',
+        inner: `\n      include: [${SDK_INCLUDE_LITERAL}],\n      esbuildOptions: { target: 'es2022' },`,
+    },
+    {
+        key: 'define',
+        inner: `\n      __RETICLE_TOKEN__: JSON.stringify(reticleToken()),\n      __RETICLE_ROOT__: JSON.stringify(process.cwd()),`,
+    },
+];
+/** Whole-key form, for a `vite:` block that does not have the key at all. */
+const WHOLE = {
+    build: `\n    build: { target: 'es2022' },`,
+    optimizeDeps: `\n    optimizeDeps: { include: [${SDK_INCLUDE_LITERAL}], esbuildOptions: { target: 'es2022' } },`,
+    define: `\n    define: {\n      __RETICLE_TOKEN__: JSON.stringify(reticleToken()),\n      __RETICLE_ROOT__: JSON.stringify(process.cwd()),\n    },`,
+};
+/**
+ * Add our keys to an existing `vite: { ... }` block, merging into any the app already set.
+ *
+ * Returns null when a colliding key is not an object literal (`build: sharedConfig`) — there is no
+ * brace to merge into, and duplicating or replacing it would corrupt someone's build.
+ */
+function mergeIntoViteBlock(source, braceAt) {
+    let out = source;
+    for (const { key, inner } of VITE_KEYS) {
+        // Scoped to the vite block by searching from its opening brace: a `build:` under `markdown:` or
+        // at the top level is somebody else's key and must not be touched.
+        const existing = new RegExp(`(\\n\\s*${key}\\s*:\\s*)([\\{A-Za-z_])`).exec(out.slice(braceAt));
+        if (existing?.index === undefined) {
+            out = `${out.slice(0, braceAt)}${WHOLE[key] ?? ''}${out.slice(braceAt)}`;
+            continue;
+        }
+        // The character after the colon decides: `{` is a literal we can open; anything else is a
+        // reference we must not touch.
+        if (existing[2] !== '{')
+            return null;
+        const at = braceAt + existing.index + existing[0].length; // just past the `{`
+        // An `include:` the app already wrote is an ARRAY, and a second `include:` key in the same
+        // object literal is not a merge — the last one wins and one of the two silently disappears.
+        // That is how `build.target` was lost while init still reported success. Join their array.
+        // Scoped to THIS block's braces: an `include:` under a later key is somebody else's array, and
+        // appending the SDK to it would both miss the target and edit a config we were not asked to.
+        const own = 'optimizeDeps' === key ? EXISTING_INCLUDE.exec(blockAfter(out, at)) : null;
+        if (own?.index === undefined) {
+            out = insertAt(out, at, inner);
+            continue;
+        }
+        // Their array first, then the rest of our keys at the block's start — inserting at the LOWER
+        // offset second keeps the first offset valid.
+        out = insertAt(out, at + own.index + own[0].length, `${SDK_INCLUDE_LITERAL}, `);
+        out = insertAt(out, at, withoutInclude(inner));
+    }
+    return out;
+}
+function insertAt(source, at, text) {
+    return `${source.slice(0, at)}${text}${source.slice(at)}`;
+}
+/**
+ * The text from just inside an opening brace to its match — a brace count, not a parser.
+ *
+ * Enough for the one question asked of it (does THIS object literal already declare `include`), and
+ * honest about its limit: a `{` or `}` inside a string literal in someone's Vite config would fool
+ * it. That only ever shortens or lengthens the window we search for `include:` in, so the worst case
+ * is the same duplicate-key merge we would have done before, never a corrupted file.
+ */
+function blockAfter(source, at) {
+    let depth = 1;
+    for (let i = at; i < source.length; i++) {
+        if ('{' === source[i])
+            depth += 1;
+        else if ('}' === source[i]) {
+            depth -= 1;
+            if (0 === depth)
+                return source.slice(at, i);
+        }
+    }
+    return source.slice(at);
+}
+/** The optimizeDeps inner minus our `include:` line, for when the app already has one to join. */
+function withoutInclude(inner) {
+    return inner.replace(`\n      include: [${SDK_INCLUDE_LITERAL}],`, '');
+}
+/**
+ * The `vite:` block Astro needs. `build.target` is raised because Astro's default down-levels the
+ * modern SDK bundle and dies on a destructuring transform; `__RETICLE_ROOT__` is defined because
+ * without it every source pointer comes back as an absolute path from the machine that ran `init`.
+ */
+const VITE_BLOCK = `  vite: {
+    build: { target: 'es2022' },
+    optimizeDeps: { include: [${SDK_INCLUDE_LITERAL}], esbuildOptions: { target: 'es2022' } },
+    define: {
+      __RETICLE_TOKEN__: JSON.stringify(reticleToken()),
+      __RETICLE_ROOT__: JSON.stringify(process.cwd()),
+    },
+  },
+`;
+export function patchAstroConfig(source) {
+    if (source.includes(CONFIG_MARKER))
+        return { kind: PatchKind.ALREADY };
+    // A `vite: { ... }` block is an object literal, so our keys can go straight after the brace and
+    // whatever is already in there is untouched. Refusing outright was the only genuine install defect
+    // left in the gate: the config bailed while the LAYOUT patch applied anyway, leaving an app with a
+    // connect snippet, no inlined token and no raised build target — which cannot connect, reported as
+    // one OK step and one warning.
+    const viteObject = VITE_OBJECT_KEY.exec(source);
+    if (viteObject?.index !== undefined) {
+        const at = viteObject.index + viteObject[0].length;
+        const merged = mergeIntoViteBlock(source, at);
+        if (merged !== null) {
+            return {
+                kind: PatchKind.APPLY,
+                code: `${HELPER_IMPORTS}${merged.trimStart()}\n${HELPER}`.trimEnd() + '\n',
+            };
+        }
+        return {
+            kind: PatchKind.MANUAL,
+            reason: 'this config sets a `vite` key Reticle needs (build / optimizeDeps / define) to something ' +
+                'other than an object literal — merging into it is your call, not a text edit Reticle should make',
+        };
+    }
+    if (ANY_VITE_KEY.test(source)) {
+        // `vite: sharedConfig` — not an object literal, so there is no brace to merge into and guessing
+        // would corrupt a build config. The recipe is the honest answer here.
+        return {
+            kind: PatchKind.MANUAL,
+            reason: 'this config sets `vite:` to something other than an object literal — merging into it is your call, not a text edit Reticle should make',
+        };
+    }
+    const opening = DEFINE_CONFIG.exec(source);
+    if (opening?.index === undefined) {
+        return {
+            kind: PatchKind.MANUAL,
+            reason: "couldn't find a `defineConfig({ ... })` call to extend",
+        };
+    }
+    const at = opening.index + opening[0].length;
+    const withBlock = `${source.slice(0, at)}\n${VITE_BLOCK}${source.slice(at)}`;
+    return {
+        kind: PatchKind.APPLY,
+        code: `${HELPER_IMPORTS}${withBlock.trimStart()}\n${HELPER}`.trimEnd() + '\n',
+    };
+}
+/** The dev-only connect that goes inside the layout's `<body>`. */
+function astroConnectScript(port, projectId) {
+    const url = port !== undefined && port !== RETICLE_DEFAULT_PORT
+        ? `\n          url: '${bridgeWsUrl(port)}',`
+        : '';
+    const id = projectId !== undefined && projectId.length > 0 ? `\n          projectId: '${projectId}',` : '';
+    return `    <script>
+      if (import.meta.env.DEV) {
+        const token = typeof __RETICLE_TOKEN__ !== 'undefined' ? __RETICLE_TOKEN__ : '';
+        const root = typeof __RETICLE_ROOT__ !== 'undefined' ? __RETICLE_ROOT__ : '';
+        const { reticle, install } = await import('@reticlehq/react');
+        install();
+        reticle.connect({${id}${url}
+          ...(token.length > 0 ? { token } : {}),
+          ...(root.length > 0 ? { root } : {}),
+        });
+      }
+    </script>
+`;
+}
+export function patchAstroLayout(source, port, projectId) {
+    if (source.includes(LAYOUT_MARKER))
+        return { kind: PatchKind.ALREADY };
+    const at = source.lastIndexOf(BODY_CLOSE);
+    if (at < 0) {
+        return {
+            kind: PatchKind.MANUAL,
+            reason: "couldn't find a `</body>` to place the connect script before",
+        };
+    }
+    return {
+        kind: PatchKind.APPLY,
+        code: `${source.slice(0, at)}${astroConnectScript(port, projectId)}${source.slice(at)}`,
+    };
+}

package/dist/init/capabilities.js

@@ -35,7 +35,10 @@ export function scanTestids(sources) {
  */
 const STORE_LIBRARIES = [
     ['@tanstack/react-query', "registerStore('queries', tanstackQueryStore(queryClient))"],
-    ['zustand', "registerStore('app', useStore) // pass the store itself, not () => store.getState()"],
+    [
+        'zustand',
+        "registerStore('app', useStore) // pass the store itself, not () => store.getState()",
+    ],
     ['@reduxjs/toolkit', "registerStore('app', store)"],
     ['redux', "registerStore('app', store)"],
     ['jotai', "registerStore('app', jotaiStore(getDefaultStore(), { cart, user }))"],