@reticlehq/server 2.11.0 → 2.13.0

package/dist/impact/impact-store.d.ts

@@ -1,13 +1,17 @@
-import { type ImpactCounts, type ImpactScope, type ImpactSnapshot } from '@reticlehq/core';
+import { type ImpactCounts, type ImpactDefect, type ImpactScope, type ImpactSnapshot } from '@reticlehq/core';
 export interface ImpactPaths {
     project: string;
     global: string;
 }
 /**
- * `reticleRoot` is the project's own `.reticle` directory (what every other store here is handed);
- * the global scope always lives beside the daemon's own state in `~/.reticle`.
+ * Where this project's dashboard lives, if `reticle link` recorded one.
+ *
+ * Read from the link file rather than derived from the API url, because the API origin and the
+ * console origin are different hosts in every deployment that is not a laptop. Synchronous and
+ * best-effort, like every other read in this file: a missing or malformed link file means no link
+ * in the HUD, never a failed tool call.
  */
-export declare function impactPaths(reticleRoot: string): ImpactPaths;
+export declare function readDashboardUrl(reticleRoot: string): string | undefined;
 /** Read a scope, tolerating absence and corruption: a broken file starts over rather than throwing. */
 export declare function readScope(path: string, now: number): ImpactScope;
 /** YYYY-MM-DD in local time - the day boundary a person recognises, not UTC's. */
@@ -22,6 +26,11 @@ export declare function isoDay(now: number): string;
  */
 export interface ImpactFoldMeta {
     runMs?: number;
+    /**
+     * The defect this call caught, when it caught one. Carried beside the counters rather than in
+     * them because it is not a tally: `counts.failed` says how many, this says which.
+     */
+    defect?: ImpactDefect;
 }
 /** Fold one delta into a scope: totals, today's bucket, records and streak. Pure. */
 export declare function applyDelta(scope: ImpactScope, delta: Partial<ImpactCounts>, now: number, meta?: ImpactFoldMeta): ImpactScope;

package/dist/impact/impact-store.js

@@ -1,7 +1,7 @@
 import { mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { homedir } from 'node:os';
-import { ReticleDir, IMPACT_DAILY_BUCKETS, IMPACT_SCHEMA_VERSION, ImpactScopeSchema, addImpactCounts, emptyImpactCounts, emptyImpactRecords, estimateImpactSavings, } from '@reticlehq/core';
+import { ReticleDir, IMPACT_DAILY_BUCKETS, IMPACT_DEFECT_LIMIT, IMPACT_SCHEMA_VERSION, ImpactScopeSchema, addImpactCounts, emptyImpactCounts, emptyImpactRecords, estimateImpactSavings, } from '@reticlehq/core';
 /**
  * Where Reticle keeps the record of what it has done for you.
  *
@@ -14,16 +14,38 @@ import { ReticleDir, IMPACT_DAILY_BUCKETS, IMPACT_SCHEMA_VERSION, ImpactScopeSch
  */
 /** Writes are debounced: a verification loop is 50-200 calls, and each one is a counter bump. */
 const WRITE_DEBOUNCE_MS = 800;
+/** The project's cloud binding, written by `reticle link`. Absent for an unlinked project. */
+const CLOUD_LINK_FILE = 'cloud.json';
 /**
  * `reticleRoot` is the project's own `.reticle` directory (what every other store here is handed);
  * the global scope always lives beside the daemon's own state in `~/.reticle`.
  */
-export function impactPaths(reticleRoot) {
+function impactPaths(reticleRoot) {
     return {
         project: join(reticleRoot, ReticleDir.IMPACT_FILE),
         global: join(homedir(), ReticleDir.ROOT, ReticleDir.IMPACT_FILE),
     };
 }
+/**
+ * Where this project's dashboard lives, if `reticle link` recorded one.
+ *
+ * Read from the link file rather than derived from the API url, because the API origin and the
+ * console origin are different hosts in every deployment that is not a laptop. Synchronous and
+ * best-effort, like every other read in this file: a missing or malformed link file means no link
+ * in the HUD, never a failed tool call.
+ */
+export function readDashboardUrl(reticleRoot) {
+    try {
+        const raw = JSON.parse(readFileSync(join(reticleRoot, CLOUD_LINK_FILE), 'utf8'));
+        if ('object' !== typeof raw || null === raw)
+            return undefined;
+        const value = raw['dashboardUrl'];
+        return 'string' === typeof value && value.length > 0 ? value : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 function emptyScope(now) {
     const counts = emptyImpactCounts();
     return {
@@ -32,6 +54,7 @@ function emptyScope(now) {
         records: emptyImpactRecords(),
         savings: estimateImpactSavings(counts),
         since: now,
+        defects: [],
     };
 }
 /** Read a scope, tolerating absence and corruption: a broken file starts over rather than throwing. */
@@ -105,7 +128,21 @@ export function applyDelta(scope, delta, now, meta = {}) {
     }
     records.bestStreakDays = Math.max(records.bestStreakDays, records.streakDays);
     records.longestRunMs = Math.max(records.longestRunMs, meta.runMs ?? 0);
-    return { counts, days, records, savings: estimateImpactSavings(counts), since: scope.since };
+    /*
+     * Newest first, capped. Prepending is what makes the HUD's short list the CURRENT breakage rather
+     * than the first ten things that ever broke — which, after a week, is a list about the past.
+     */
+    const defects = meta.defect === undefined
+        ? scope.defects
+        : [meta.defect, ...scope.defects].slice(0, IMPACT_DEFECT_LIMIT);
+    return {
+        counts,
+        days,
+        records,
+        savings: estimateImpactSavings(counts),
+        since: scope.since,
+        defects,
+    };
 }
 /**
  * The live impact record for one project.
@@ -117,6 +154,7 @@ export class ImpactStore {
     #paths;
     #now;
     #projectName;
+    #dashboardUrl;
     #project;
     #global;
     #timer;
@@ -125,6 +163,7 @@ export class ImpactStore {
         this.#paths = impactPaths(opts.reticleRoot);
         this.#now = opts.now ?? (() => Date.now());
         this.#projectName = opts.projectName;
+        this.#dashboardUrl = readDashboardUrl(opts.reticleRoot);
         const now = this.#now();
         this.#project = readScope(this.#paths.project, now);
         this.#global = readScope(this.#paths.global, now);
@@ -148,6 +187,8 @@ export class ImpactStore {
         };
         if (this.#projectName !== undefined)
             snap.projectName = this.#projectName;
+        if (this.#dashboardUrl !== undefined)
+            snap.dashboardUrl = this.#dashboardUrl;
         return snap;
     }
     /** Write now (process exit, tests). */

package/dist/index.d.ts

@@ -117,7 +117,10 @@ export interface StartOptions {
     pairingTokenDir?: string;
     /** injectable clock for contract.json's generatedAt stamp. Defaults to Date.now. */
     now?: () => number;
-    /** 'core' exposes the lean tool surface. Defaults to env RETICLE_TOOL_PROFILE, else 'full'. */
+    /**
+     * Retired profile name (`core`/`full`/…). Old values still map. The live switch is
+     * RETICLE_ADVERTISE_ALL_TOOLS=1; the default is the lean surface.
+     */
     toolProfile?: string;
     /** Start the OEM/CI verify HTTP endpoint alongside the daemon (`reticle serve --http`). */
     httpVerify?: boolean;

package/dist/index.js

@@ -1,7 +1,9 @@
 import { join } from 'node:path';
 import { existsSync, readFileSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { PROJECT_REGISTRY_FILE, emptyProjectRegistry, parseProjectRegistry } from '@reticlehq/core';
+import { resolveProjectCloud } from './cloud/cloud-config.js';
+import { startSyncDaemon } from './cloud/sync-daemon.js';
+import { PROJECT_REGISTRY_FILE, emptyProjectRegistry, parseProjectRegistry, projectCandidates, } from '@reticlehq/core';
 import { discoverProjectConfigs } from './cli/config-discovery.js';
 import { projectCandidatesFrom, resolveArtifactRoot, } from './project/artifact-root.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
@@ -14,6 +16,8 @@ import { openLoopbackAlias } from './daemon/loopback-alias.js';
 import { reportAppInstrumented } from './telemetry/app-instrumented.js';
 import { resolveBridgeSecurityWithAutoToken } from './bridge/bridge-security.js';
 import { Bridge } from './bridge/bridge.js';
+import { sdkFixForDirectory } from './version/sdk-fix.js';
+import { SERVER_VERSION } from './version/server-version.js';
 import { BaselineStore } from './project/baselines.js';
 import { RecordingStore } from './flows/recordings.js';
 import { initImpact } from './impact/impact-recorder.js';
@@ -39,6 +43,7 @@ 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 { AGENT_ALREADY_DRIVING_ELSEWHERE, shouldGreetWithLeaseNotice, } from './session/lease-visibility.js';
 import { playwrightLauncher, resolveMaxContexts } from './pool/playwright-launcher.js';
 import { LeaseReaper } from './pool/lease-reaper.js';
 import { readJournalEnabled, readProjectId } from './cli/cli-port.js';
@@ -187,7 +192,14 @@ function makeNetworkDetailRouter(bridge, driveUrl) {
 function attachJournal(bridge, deps) {
     const journalAttach = makeJournalAttach(deps);
     const ambientStore = new AmbientStore(deps.fs, deps.reticleRoot);
+    // Built once, not per session: the resolver walks config discovery and the user-level registry,
+    // and neither changes between two tabs connecting a second apart.
+    const resolveArtifactRoot = artifactRootResolver(deps.reticleRoot);
     bridge.attachSessionCreate((session) => {
+        // Stamp the project's own `.reticle` before ANY counter fires for this session. Without it every
+        // verdict is recorded against wherever the daemon was started, which is how one app's evidence
+        // reached a different account's production dashboard.
+        session.artifactRoot = resolveArtifactRoot(session.projectId).root;
         journalAttach(session);
         // Seed the learned ambient map so a fresh session starts knowing which regions churn, instead of
         // re-learning from zero. Best-effort + async: a late seed still helps, a failure is silent.
@@ -256,6 +268,14 @@ async function resolveRealInput(options, onNavigateError, onNetworkDetail) {
     return {};
 }
 /** Start the Reticle bridge (browser WS endpoint) and, by default, the MCP stdio server. */
+/**
+ * The SDK-upgrade sentence for THIS project's package.json, evaluated at each HELLO so a
+ * just-edited manifest is what we name. Falls back to the framework-neutral sensor when cwd is
+ * not an app.
+ */
+function sdkFixForCwd() {
+    return sdkFixForDirectory(SERVER_VERSION, process.cwd());
+}
 /**
  * Resolve a session's artifact root, from everything this machine knows about where projects live.
  *
@@ -264,6 +284,39 @@ async function resolveRealInput(options, onNavigateError, onNetworkDetail) {
  * this daemon is up, and a resolution that used a startup snapshot would keep answering with a map
  * from before the project the agent is now driving existed.
  */
+/**
+ * Every `.reticle` root on this machine that sync should consider, from the same two sources the
+ * artifact resolver uses.
+ *
+ * Read on every call rather than snapshotted, for the same reason: `reticle link` can run in
+ * another terminal while this daemon is up, and a startup snapshot would keep that repo silent
+ * until somebody restarted a process they have no reason to suspect.
+ *
+ * Returns directories that MIGHT be linked; the caller resolves each and skips the ones that are
+ * not. Deciding that here would mean reading every cloud.json on every tick.
+ */
+function knownProjectRoots() {
+    const roots = new Set();
+    try {
+        const path = join(homedir(), ReticleDir.ROOT, PROJECT_REGISTRY_FILE);
+        if (existsSync(path)) {
+            const registry = parseProjectRegistry(JSON.parse(readFileSync(path, 'utf8')));
+            for (const candidate of projectCandidates(registry))
+                roots.add(join(candidate.directory, ReticleDir.ROOT));
+        }
+    }
+    catch {
+        // A registry that cannot be read is an empty one — never a reason to stop syncing.
+    }
+    try {
+        for (const config of discoverProjectConfigs(process.cwd()).found)
+            roots.add(join(config.directory, ReticleDir.ROOT));
+    }
+    catch {
+        // Same: a diagnostic walk that throws must not take the sync loop with it.
+    }
+    return [...roots];
+}
 function artifactRootResolver(daemonRoot) {
     return (projectId) => {
         let registry = emptyProjectRegistry();
@@ -298,7 +351,7 @@ export async function start(options = {}) {
     // "nothing recorded yet" over a month of history on disk is the worst version of this feature.
     initImpact({ reticleRoot: options.reticleRoot ?? join(process.cwd(), ReticleDir.ROOT) });
     const security = await resolveBridgeSecurityWithAutoToken(options);
-    const bridge = new Bridge({ port, ...security });
+    const bridge = new Bridge({ port, sdkFix: sdkFixForCwd, ...security });
     // Server-authoritative liveness: a Node-side reaper (immune to browser throttling) ends sessions
     // whose agent has gone idle, so a forgotten/crashed agent never leaves the HUD "running" forever.
     const reaper = new SessionReaper(bridge.sessions);
@@ -332,6 +385,25 @@ export async function start(options = {}) {
         pool = createBrowserPool(options.headless ?? true);
         leaseReaper = new LeaseReaper(pool);
         leaseReaper.start();
+        /*
+         * Tell a tab that ARRIVES during a lease why its HUD is silent.
+         *
+         * The acquire-time notice only reaches tabs already connected, so opening the app — or merely
+         * reloading it — while an agent held a lease landed somebody on a dark HUD with nothing
+         * explaining it. That is the more common way to hit it, because a person opens the dashboard
+         * precisely when they want to watch. Reported as "dashboard is being watched, but the agent chat
+         * shows nothing".
+         *
+         * Registered separately from the journal hook rather than folded into it: this one needs the
+         * pool, which does not exist on the no-drive path, and session-create handlers are additive.
+         */
+        const leasePool = pool;
+        bridge.attachSessionCreate((session) => {
+            const leasedIds = leasePool.leasedSessionIds();
+            const leasedProjects = leasedIds.map((id) => bridge.sessions.get(id)?.projectId);
+            if (shouldGreetWithLeaseNotice(session, leasedIds, leasedProjects))
+                session.pushNarration(AGENT_ALREADY_DRIVING_ELSEWHERE);
+        });
         const deps = {
             sessions: bridge.sessions,
             pool,
@@ -391,14 +463,19 @@ export async function startDaemon(options = {}) {
     initImpact({ reticleRoot: options.reticleRoot ?? join(process.cwd(), ReticleDir.ROOT) });
     const security = await resolveBridgeSecurityWithAutoToken(options);
     const shared = createSharedServer(security.token === undefined ? {} : { token: security.token });
-    const bridge = new Bridge({ port, server: shared.httpServer, ...security });
+    const bridge = new Bridge({ port, server: shared.httpServer, sdkFix: sdkFixForCwd, ...security });
     // The daemon owns listen (below), so the real bind error is reported there; absorb bridge.ready's
     // mirror rejection so a port collision can't surface as an unhandled promise rejection.
     void bridge.ready.catch(() => undefined);
+    // Declared before attachStatus so the closure below can report it; assigned further down, before
+    // listen — the first status request cannot arrive until after the bind.
+    let verifyHttp;
     // `reticle status` GETs this for a live, at-a-glance view of connected tabs + their health.
     // The same diagnosis agents get on an empty `reticle_sessions`, so `reticle status` — the
     // most-run command in the field — stops answering "sessionCount: 0" and nothing else.
-    shared.attachStatus(() => statusPayload(bridge.sessions.count(), bridge.sessions.list(), bridge.sessions.noSessionHint()));
+    // `verifyPort` rides along so a later `serve --http` can tell whether this daemon already honours
+    // the requested `--http-port` instead of silently ignoring the flag (#687).
+    shared.attachStatus(() => statusPayload(bridge.sessions.count(), bridge.sessions.list(), bridge.sessions.noSessionHint(), verifyHttp?.port));
     // 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
@@ -426,6 +503,23 @@ export async function startDaemon(options = {}) {
     const pool = createBrowserPool(options.headless ?? true);
     const leaseReaper = new LeaseReaper(pool);
     leaseReaper.start();
+    /*
+     * Automatic cloud sync, for the session nobody thinks about.
+     *
+     * The daemon outlives every individual tool call and is already running for the whole session, so
+     * it is the only place "keep the dashboard current while work is happening" costs nobody an extra
+     * process to remember. Safe for an UNLINKED project: it resolves the link on every tick and does
+     * nothing until one exists, so `reticle link` takes effect without a restart.
+     */
+    const cloudSync = startSyncDaemon({
+        reticleRoot,
+        cloud: () => resolveProjectCloud(fs, reticleRoot, homedir(), process.env),
+        // Every OTHER linked repo on this machine, not just the directory the daemon was started in.
+        // One daemon serves many projects, and pushing only its own root left the rest silently
+        // reporting nothing — indistinguishable, on the dashboard, from nobody having verified anything.
+        otherRoots: () => Promise.resolve(knownProjectRoots()),
+        cloudFor: (root) => resolveProjectCloud(fs, root, homedir(), process.env),
+    });
     // 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.
     // Scope + the no-session diagnosis: "no browser session connected" is the error that ends most
@@ -433,7 +527,7 @@ export async function startDaemon(options = {}) {
     // Ordered AFTER the pool: the watch may open a browser itself the moment it finds a listening dev
     // server for a wired project (see no-session-watch.ts), and it opens it through the pool — the same
     // path reticle_lease takes, in this process, binding nothing.
-    wireSessionScope(bridge.sessions, readProjectId(process.cwd()), port, () => pool.reapedLeaseCount(), (url) => pool.acquire(url));
+    wireSessionScope(bridge.sessions, readProjectId(process.cwd()), port, (sessionId) => pool.wasReapedLease(sessionId), (url) => pool.acquire(url));
     const deps = {
         sessions: bridge.sessions,
         pool,
@@ -444,9 +538,18 @@ export async function startDaemon(options = {}) {
         project,
         fs,
         reticleRoot,
+        // The long-lived daemon needs this MORE than the standalone MCP process does, not less: it is
+        // the one that outlives a single project and serves every app on the machine. Omitting it here
+        // silently disabled per-session artifact resolution for every agent that attaches to a running
+        // daemon — the common case — so flows were listed, loaded and healed against wherever the
+        // daemon happened to be launched. Wired in only one of the two places, a resolver is a resolver
+        // that does not run.
+        artifactRootFor: artifactRootResolver(reticleRoot),
         now,
         bridgePort: port,
         browserProbe: probeChromium,
+        // A finished verification should not sit behind a one-minute timer — see ToolDeps.onRunPersisted.
+        onRunPersisted: () => cloudSync.nudge(),
     };
     const profile = resolveToolSurface(options.toolProfile);
     const effectiveDeps = realInput !== undefined ? { ...deps, realInput } : deps;
@@ -461,9 +564,11 @@ export async function startDaemon(options = {}) {
     // 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;
+    // (`verifyHttp` itself is declared above attachStatus, which reports its port.)
     if (true === options.httpVerify) {
-        const runStore = new RunStore(fs, reticleRoot);
+        // Wakes cloud sync when the HTTP verify server persists a run — that path does not push
+        // inline the way the MCP one does, so without this its runs waited for the timer.
+        const runStore = new RunStore(fs, reticleRoot, { onWrote: () => cloudSync.nudge() });
         const runner = new ReticleRunner(createRunnerPort(effectiveDeps));
         const token = options.httpVerifyToken ?? process.env[ReticleEnv.VERIFY_TOKEN] ?? '';
         verifyHttp = await startVerifyServer({ runner, token, persist: (run) => runStore.write(run) }, options.httpVerifyPort ?? RETICLE_VERIFY_DEFAULT_PORT);
@@ -552,6 +657,7 @@ export async function startDaemon(options = {}) {
             if (vh !== undefined)
                 await new Promise((resolve) => vh.server.close(() => resolve()));
             leaseReaper.stop();
+            cloudSync.stop();
             await loopbackAlias.close?.();
             await pool.shutdown();
             await owned?.dispose();

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

@@ -1,7 +1,7 @@
 /**
  * `reticle init` writes a behavioral rule into the coding agent's instruction file so the agent
  * VERIFIES a feature with Reticle after building it — not only when the user remembers to say "test
- * it with reticle". Registering the MCP server (mcp.ts / cursor.ts) only makes the tools AVAILABLE;
+ * it with reticle". Registering the MCP server (mcp.ts / mcp-clients.ts) only makes the tools AVAILABLE;
  * this is the piece that makes the agent reach for them, every session, unprompted.
  *
  * It carries a SECOND standing instruction, and that one is not about this project at all: send
@@ -15,7 +15,7 @@
  * written into whichever instruction file the detected agent reads: `CLAUDE.md` (Claude Code),
  * `.cursor/rules/reticle.mdc` (Cursor, `alwaysApply` so it stays in context), or `AGENTS.md` as the
  * 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).
+ * re-run is a no-op. Mirrors the apply/already result shape used across init (see mcp-clients.ts).
  */
 /** Project-root instruction files the agent re-reads every session. */
 export declare const CLAUDE_MD_PATH = "CLAUDE.md";
@@ -36,6 +36,15 @@ export declare const AGENTS_MD_PATH = "AGENTS.md";
 export declare const RETICLE_MD_PATH = "RETICLE.md";
 /** Cursor project rule; the frontmatter `alwaysApply` keeps it in context on every turn. */
 export declare const CURSOR_RULE_PATH = ".cursor/rules/reticle.mdc";
+/**
+ * Does this file already carry the managed block?
+ *
+ * Exported so callers cannot invent their own looser test. The begin marker carries explanatory
+ * text inside the comment, so a substring check for `reticle:begin` matches files that
+ * `mergeMarkedInstruction` would treat as having NO block — and the two disagreeing means a refresh
+ * silently appends a second copy instead of updating the first.
+ */
+export declare function hasManagedBlock(text: string): boolean;
 /**
  * How the agent must INVOKE the CLI.
  *
@@ -60,13 +69,28 @@ export declare const CLI: string;
  * inside a host that asks the human for permission — so a dev server it starts is visible in the
  * transcript, attributable, and stoppable.
  *
- * The guards are the whole reason this is safe, so no renderer may drop them: adopt what is already
- * listening, read the command rather than invent one, never kill, background it and SAY so, and leave
- * the permission prompt to the host.
+ * The guards are the whole reason this is safe, so no renderer may drop them: one server at a time,
+ * read the command rather than invent one, never kill anything you did not start, and leave the
+ * permission prompt to the host. "Background it and say so" is no longer among them because the
+ * branch above now states it at the point of action, and this text is read every turn — a rule
+ * stated twice costs every agent tokens forever and is the first thing to drift.
+ *
+ * The RESTART branch outranks the rest and is stated first. It used to be an aside, while "if a dev
+ * server is already listening, use it" was a numbered guard — so an agent resolving the two
+ * reasonably reused a server started before `init` edited the build config, served a bundle with no
+ * SDK in it, and landed on an empty session list with every other step done correctly.
  *
  * Exported because slash-command.ts renders the same rule; there must not be two versions of it.
  */
-export declare const DEV_SERVER_POLICY = "**If no dev server is listening, start one yourself.** Read the project's own dev script out of `package.json` (`dev`, `start`, whatever this project calls it), run it in the BACKGROUND, tell the user in one line that it is running and how to stop it, then carry on. Stopping to ask is how a verification turn ends with nothing verified.\n\nFive guards, none optional:\n\n1. **Never start a second one.** If something is already listening on the app's port, use it.\n2. **Never guess the command.** It comes from `package.json` scripts. If there is no recognisable dev script, say so and stop rather than inventing one.\n3. **Never kill anything.** Not a dev server, not a daemon, not a port holder \u2014 including one you started.\n4. **Background it, and say so.** The user must know a server is running and how to stop it. A dev server the human does not know about is the same failure one step later.\n5. **The permission prompt belongs to your host.** Never try to bypass, suppress or auto-approve it, and take a refusal as the answer.";
+export declare const DEV_SERVER_POLICY = "**A dev server already running when `reticle init` ran does not have Reticle in its bundle.** It read the build config at boot; `init` edited it afterwards. It serves the old bundle and no session appears. In order:\n\n1. **A dev server was already running?** Restart it, then hard-reload the tab. \"Something is listening\" does not mean the right bundle is served.\n2. **Nothing was running?** Start it in the BACKGROUND and say so in one line. `reticle_sessions` gives you this project's own dev command in `next_action`; use that, never compose one. Started after `init`, it needs no restart.\n\nStopping to ask is how a verification turn ends with nothing verified.\n\nFour guards, none optional:\n\n1. **Never run two at once.** One dev server on the app's port. Restarting a stale one means stopping it first, not starting a second alongside it.\n2. **Never guess the command.** It comes from `package.json` scripts. No recognisable dev script means say so and stop, not invent one.\n3. **Never kill anything you did not start**, and never a daemon or a port holder. The one exception is the restart above, and say in one line that you did it.\n4. **The permission prompt belongs to your host.** Never bypass, suppress or auto-approve it, and take a refusal as the answer.";
+/**
+ * The operative rules, carried by every file that loads on every turn.
+ *
+ * Short on purpose. This is the text that has to CHANGE BEHAVIOUR, so it states when to verify, when
+ * NOT to, how, and the guards against calling something proven when it is not. Everything an agent
+ * needs only at the moment it hits a specific situation lives in RETICLE.md, named at the end.
+ */
+export declare const RULE_BODY: string;
 /** The full-rules file, written verbatim (no markers: `init` owns this file entirely). */
 export declare function reticleMdFile(): string;
 export declare const AgentRuleStatus: {

package/dist/init/agent-rules.js

@@ -1,7 +1,7 @@
 /**
  * `reticle init` writes a behavioral rule into the coding agent's instruction file so the agent
  * VERIFIES a feature with Reticle after building it — not only when the user remembers to say "test
- * it with reticle". Registering the MCP server (mcp.ts / cursor.ts) only makes the tools AVAILABLE;
+ * it with reticle". Registering the MCP server (mcp.ts / mcp-clients.ts) only makes the tools AVAILABLE;
  * this is the piece that makes the agent reach for them, every session, unprompted.
  *
  * It carries a SECOND standing instruction, and that one is not about this project at all: send
@@ -15,7 +15,7 @@
  * written into whichever instruction file the detected agent reads: `CLAUDE.md` (Claude Code),
  * `.cursor/rules/reticle.mdc` (Cursor, `alwaysApply` so it stays in context), or `AGENTS.md` as the
  * 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).
+ * re-run is a no-op. Mirrors the apply/already result shape used across init (see mcp-clients.ts).
  */
 import { NPX } from './mcp.js';
 import { RETICLE_NPM_PACKAGE } from '../version/server-version.js';
@@ -41,6 +41,17 @@ 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 -->';
+/**
+ * Does this file already carry the managed block?
+ *
+ * Exported so callers cannot invent their own looser test. The begin marker carries explanatory
+ * text inside the comment, so a substring check for `reticle:begin` matches files that
+ * `mergeMarkedInstruction` would treat as having NO block — and the two disagreeing means a refresh
+ * silently appends a second copy instead of updating the first.
+ */
+export function hasManagedBlock(text) {
+    return text.includes(RULE_BEGIN);
+}
 /**
  * How the agent must INVOKE the CLI.
  *
@@ -65,21 +76,32 @@ export const CLI = `${NPX} ${RETICLE_NPM_PACKAGE}`;
  * inside a host that asks the human for permission — so a dev server it starts is visible in the
  * transcript, attributable, and stoppable.
  *
- * The guards are the whole reason this is safe, so no renderer may drop them: adopt what is already
- * listening, read the command rather than invent one, never kill, background it and SAY so, and leave
- * the permission prompt to the host.
+ * The guards are the whole reason this is safe, so no renderer may drop them: one server at a time,
+ * read the command rather than invent one, never kill anything you did not start, and leave the
+ * permission prompt to the host. "Background it and say so" is no longer among them because the
+ * branch above now states it at the point of action, and this text is read every turn — a rule
+ * stated twice costs every agent tokens forever and is the first thing to drift.
+ *
+ * The RESTART branch outranks the rest and is stated first. It used to be an aside, while "if a dev
+ * server is already listening, use it" was a numbered guard — so an agent resolving the two
+ * reasonably reused a server started before `init` edited the build config, served a bundle with no
+ * SDK in it, and landed on an empty session list with every other step done correctly.
  *
  * Exported because slash-command.ts renders the same rule; there must not be two versions of it.
  */
-export const DEV_SERVER_POLICY = `**If no dev server is listening, start one yourself.** Read the project's own dev script out of \`package.json\` (\`dev\`, \`start\`, whatever this project calls it), run it in the BACKGROUND, tell the user in one line that it is running and how to stop it, then carry on. Stopping to ask is how a verification turn ends with nothing verified.
+export const DEV_SERVER_POLICY = `**A dev server already running when \`reticle init\` ran does not have Reticle in its bundle.** It read the build config at boot; \`init\` edited it afterwards. It serves the old bundle and no session appears. In order:
+
+1. **A dev server was already running?** Restart it, then hard-reload the tab. "Something is listening" does not mean the right bundle is served.
+2. **Nothing was running?** Start it in the BACKGROUND and say so in one line. \`reticle_sessions\` gives you this project's own dev command in \`next_action\`; use that, never compose one. Started after \`init\`, it needs no restart.
 
-Five guards, none optional:
+Stopping to ask is how a verification turn ends with nothing verified.
 
-1. **Never start a second one.** If something is already listening on the app's port, use it.
-2. **Never guess the command.** It comes from \`package.json\` scripts. If there is no recognisable dev script, say so and stop rather than inventing one.
-3. **Never kill anything.** Not a dev server, not a daemon, not a port holder — including one you started.
-4. **Background it, and say so.** The user must know a server is running and how to stop it. A dev server the human does not know about is the same failure one step later.
-5. **The permission prompt belongs to your host.** Never try to bypass, suppress or auto-approve it, and take a refusal as the answer.`;
+Four guards, none optional:
+
+1. **Never run two at once.** One dev server on the app's port. Restarting a stale one means stopping it first, not starting a second alongside it.
+2. **Never guess the command.** It comes from \`package.json\` scripts. No recognisable dev script means say so and stop, not invent one.
+3. **Never kill anything you did not start**, and never a daemon or a port holder. The one exception is the restart above, and say in one line that you did it.
+4. **The permission prompt belongs to your host.** Never bypass, suppress or auto-approve it, and take a refusal as the answer.`;
 /**
  * The operative rules, carried by every file that loads on every turn.
  *
@@ -87,7 +109,7 @@ Five guards, none optional:
  * NOT to, how, and the guards against calling something proven when it is not. Everything an agent
  * needs only at the moment it hits a specific situation lives in RETICLE.md, named at the end.
  */
-const RULE_BODY = `## Verifying with Reticle
+export const RULE_BODY = `## Verifying with Reticle
 
 This app is instrumented by **Reticle**, an in-app verification layer exposed as \`reticle_*\` MCP tools and the \`${CLI}\` CLI (always through npx: Reticle's server is not installed into this project). Verifying is part of "done", not an optional extra.
 
@@ -103,21 +125,40 @@ This app is instrumented by **Reticle**, an in-app verification layer exposed as
 - **Only \`reticle_act_and_wait\` and \`reticle_assert\` produce a verdict.** \`reticle_act\` and everything else move or read the app and prove nothing, so a session ending without one of those two has no result however many tools it used.
 - Covered flows: \`${CLI} gate\` reports which recorded flows the changed files affect and whether they still pass.
 
+**Setting Reticle up, or just restarted? You are mid-sequence — do not stop until a verdict exists.**
+The whole of it is: instrument the app → get a dev server running → open the app in a browser →
+drive one flow → report the verdict. Every step is yours to do, and none of them needs the user.
+The ONE legitimate pause is a client restart, because a client reads its server list at startup;
+when you come back, you are not finished, you are on the next step — resume it without being asked.
+Stopping anywhere else leaves an app that looks installed and can verify nothing, which is the
+single commonest way this goes wrong. \`/reticle\` carries the full recovery ladder when a step
+does not work; use it rather than guessing, and never report the install as finished without a
+verdict to point at.
+
 **Nothing connected? Get the app running.**
 
 ${DEV_SERVER_POLICY}
 
 A dev server that is already running does not pick up an edited build config or a newly created plugin file — restart it and hard-reload the tab. And if a server IS listening and still nothing connects, the cause is the SDK not loading in the page, not a missing dev server; do not tell the user to start one they are already running.
 
+**Finish \`src/reticle-dev.ts\` before you claim setup is done.** \`init\` writes it and cannot always fill it in: a store that needs an argument only reading the code supplies (Jotai atoms, an XState actor, a TanStack \`queryClient\`) is left as a commented \`registerStore\` line. A file that registers nothing looks exactly like a finished one, and \`reticle_state\` then returns empty forever — which is indistinguishable from an app that has nothing to report, so it reads as success. Uncomment the line, complete it, and prove it by driving one flow and seeing your keys come back. If \`init\` told you to restart your client, this is the job waiting for you on the other side of that restart.
+
+**Verify each feature as you finish it, not all of them at the end.** Asked for four, build one, drive it, get a verdict, then start the second. A red verdict after four builds has four suspects; after one it has none.
+
+**Capture what a change is FOR while you are building it, not afterwards.** \`reticle_intent\` records the business outcome a change is meant to produce, and the only moment anybody knows it is while the change is being made. Pass \`intent\` when you save a flow, so the saved flow carries the reason it exists. A flow without one replays for months and then reports "step 3 failed" instead of what stopped being true for a user.
+
 **Honesty, which is the whole point:**
 
 - **\`verified: "unknown"\` is not a pass.** It means Reticle drove the app and could not tell what happened; \`verifiedReason\` says which clause decided that. Report it as unknown, never as working.
+- **\`verified: "no-fault"\` is not a pass either.** It means nothing was DECLARED to prove: the page settled and no channel complained, but you asserted nothing, so there is no verification. You get it whenever \`until\` is omitted. Name a consequence the action changes — a signal, a request, a route, or store state — and call again.
 - **Never weaken a check to make it green.** Downgrading, skipping or deleting an assertion is a finding, not a fix.
 - **If Reticle cannot run** (no daemon, or this is not a running web app), say so. Do not skip verification silently.
 - **Setup is not finished until one real flow has been driven and produced a verdict.** \`init\` exiting 0, the tools appearing, and a session being listed are all things that happen before anything has been verified.
 
 **The \`/reticle\` skill runs this whole loop for you** — detect, connect, drive one flow, report. If your client does not have it, install it once: \`/plugin marketplace add reticlehq/reticle\` then \`/plugin install reticle@reticlehq\` in Claude Code, or \`npx skills add reticlehq/reticle\` anywhere the skills CLI works.
 
+**A tool you need is missing? It exists.** The default surface advertises a subset; reach any other by name with \`reticle_run { tool, args }\`, and list them with \`reticle_tools\`. Two worth knowing: \`reticle_context\` returns this run's own memory — what is established, what is proven, what is still unverified — which is what you want after a compaction or when picking up work you did not start; \`reticle_intent\` records what a change was MEANT to do, while somebody still knows.
+
 **Report Reticle's own defects with \`reticle_feedback\` the moment you notice**, then carry on with your task. You are the user Reticle is built for and the only one who can say what it cost you, and that knowledge is gone when your context is.
 
 📄 **The rest is in [RETICLE.md](./${RETICLE_MD_PATH}): what to do when the tools are missing, when a result carries \`version_skew\` or \`update_available\`, when \`reticle_state\` comes back empty, and how to write a feedback report that can be acted on. Read it when you hit one of those, not before.**`;

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

@@ -15,3 +15,19 @@ import { type SourcePatch } from './patch-kind.js';
 import { UiLibrary } from './detect.js';
 export declare function patchAstroConfig(source: string): SourcePatch;
 export declare function patchAstroLayout(source: string, port: number | undefined, projectId: string | undefined, uiLibrary?: UiLibrary): SourcePatch;
+/** Where Astro keeps ambient types — `create-astro` ships this file. */
+export declare const ASTRO_ENV_DTS_PATH = "src/env.d.ts";
+/**
+ * The declarations `astro check` needs for the Vite `define` names (#677).
+ *
+ * Matching SvelteKit's `hooks.client.ts` typing: `string | undefined`, because the define can be
+ * absent when the pairing token file is missing.
+ */
+export declare const ASTRO_ENV_DTS_DECLARES: string;
+/**
+ * Append the Vite-define ambient declarations to `src/env.d.ts`, or create the file.
+ *
+ * Without this, `create-astro`'s default `"astro check && astro build"` fails with four
+ * `ts(2304) Cannot find name '__RETICLE_TOKEN__'` errors after a clean init (#677).
+ */
+export declare function patchAstroEnvDts(existing: string | null): SourcePatch;

package/dist/init/astro-patch.js

@@ -270,3 +270,31 @@ export function patchAstroLayout(source, port, projectId, uiLibrary = UiLibrary.
         code: `${source.slice(0, at)}${astroConnectScript(port, projectId, uiLibrary)}${source.slice(at)}`,
     };
 }
+/** Where Astro keeps ambient types — `create-astro` ships this file. */
+export const ASTRO_ENV_DTS_PATH = 'src/env.d.ts';
+/**
+ * The declarations `astro check` needs for the Vite `define` names (#677).
+ *
+ * Matching SvelteKit's `hooks.client.ts` typing: `string | undefined`, because the define can be
+ * absent when the pairing token file is missing.
+ */
+export const ASTRO_ENV_DTS_DECLARES = 'declare const __RETICLE_TOKEN__: string | undefined;\n' +
+    'declare const __RETICLE_ROOT__: string | undefined;\n';
+/** Present once either declare is in the file — both are written together. */
+const ENV_DTS_MARKER = '__RETICLE_TOKEN__';
+/**
+ * Append the Vite-define ambient declarations to `src/env.d.ts`, or create the file.
+ *
+ * Without this, `create-astro`'s default `"astro check && astro build"` fails with four
+ * `ts(2304) Cannot find name '__RETICLE_TOKEN__'` errors after a clean init (#677).
+ */
+export function patchAstroEnvDts(existing) {
+    if (null !== existing && existing.includes(ENV_DTS_MARKER)) {
+        return { kind: PatchKind.ALREADY };
+    }
+    if (null === existing || '' === existing.trim()) {
+        return { kind: PatchKind.APPLY, code: ASTRO_ENV_DTS_DECLARES };
+    }
+    const base = existing.endsWith('\n') ? existing : `${existing}\n`;
+    return { kind: PatchKind.APPLY, code: `${base}${ASTRO_ENV_DTS_DECLARES}` };
+}