@reticlehq/server 2.12.0 → 2.13.0

package/dist/impact/impact-recorder.js

@@ -1,43 +1,90 @@
-import { Verified } from '@reticlehq/core';
+import { Verified, } from '@reticlehq/core';
 import { estimateTokens } from '../session/output-budget.js';
 import { ImpactStore } from './impact-store.js';
 /**
- * The daemon's single impact recorder.
+ * The daemon's impact recorders — ONE PER PROJECT ROOT.
  *
- * One store per daemon, created on the first call that knows the project's `.reticle` root. A
- * module singleton for the same reason the tool counters are: the dispatch chokepoint has to be
- * able to record without every tool threading a store through its arguments, and a second recorder
- * would silently split the user's own history in half.
+ * This was a single module-level store, and "the first root wins for the daemon's lifetime" was
+ * written down as if it were a design decision. It is only correct for a daemon that serves one
+ * project, and this daemon has never been that: `artifactRootFor` exists precisely because one
+ * daemon serves many, and nine modules already route their artifacts by the SESSION's project.
+ *
+ * Measured, not theorised: with a daemon rooted at repo A, two verdicts driven against app B landed
+ * in A's `impact.json` — B's own ledger never moved — and A's cloud link then carried them to a
+ * PRODUCTION dashboard belonging to a different account than B was linked to. The impact ledger is
+ * what the whole dashboard is computed from, so this was the one artifact whose misrouting was
+ * guaranteed to be visible and billed.
+ *
+ * Keyed by root path, so two projects driven through one daemon keep separate ledgers, and the
+ * daemon's own root remains the answer for anything that cannot name a project.
+ */
+/** One store per `.reticle` root. */
+const stores = new Map();
+/** The daemon's own root — used when a call cannot say which project it was for. */
+let defaultRoot;
+/** Held so a per-root store is built with the same clock and project name as the default. */
+let storeOpts = {};
+/** Get-or-create the store for one root. */
+function storeFor(root) {
+    const key = root ?? defaultRoot;
+    if (key === undefined || 0 === key.length)
+        return undefined;
+    let found = stores.get(key);
+    if (found === undefined) {
+        found = new ImpactStore({ ...storeOpts, reticleRoot: key });
+        stores.set(key, found);
+    }
+    return found;
+}
+/**
+ * Wire the DEFAULT root — the daemon's own. Idempotent; the first one wins.
+ *
+ * Still idempotent, and still first-wins, because the daemon's own root genuinely does not change
+ * while it runs. What changed is that this is no longer the ONLY root: a call that knows its
+ * project passes one, and this is the fallback for calls that do not.
  */
-let store;
-/** Wire the recorder to a project. Idempotent; the first root wins for the daemon's lifetime. */
 export function initImpact(opts) {
     // No root, no record. Programmatic callers and test doubles build their own deps and are not
     // obliged to carry one, and a courtesy counter must never be the reason a tool call throws.
     if (opts.reticleRoot === undefined || 0 === opts.reticleRoot.length)
-        return store;
-    store ??= new ImpactStore({ ...opts, reticleRoot: opts.reticleRoot });
-    return store;
+        return storeFor(undefined);
+    if (defaultRoot === undefined) {
+        defaultRoot = opts.reticleRoot;
+        const { projectName, now } = opts;
+        storeOpts = {
+            ...(projectName === undefined ? {} : { projectName }),
+            ...(now === undefined ? {} : { now }),
+        };
+    }
+    return storeFor(opts.reticleRoot);
 }
-/** The live store, if one has been initialised. */
-export function impactStore() {
-    return store;
+/** The live store for a root (default when omitted), if one has been initialised. */
+export function impactStore(root) {
+    return storeFor(root);
 }
-/** Test seam: drop the singleton so a suite can start from a clean record. */
+/** Test seam: drop the stores so a suite can start from a clean record. */
 export function resetImpactForTest() {
-    store = undefined;
+    stores.clear();
+    defaultRoot = undefined;
+    storeOpts = {};
 }
-/** Record one delta, if the recorder is live. Never throws: stats must not break a tool call. */
-export function recordImpact(delta, meta = {}) {
+/**
+ * Record one delta against a project's ledger. Never throws: stats must not break a tool call.
+ *
+ * `root` is the `.reticle` directory this call's evidence belongs to. Omitted means "could not tell
+ * which project", which falls back to the daemon's own root — the old behaviour, kept for the paths
+ * that genuinely have no session to ask.
+ */
+export function recordImpact(delta, meta = {}, root) {
     try {
-        store?.record(delta, meta);
+        storeFor(root)?.record(delta, meta);
     }
     catch {
         // Counting is a courtesy to the user; failing to count is not worth failing their call over.
     }
 }
-export function impactSnapshot() {
-    return store?.snapshot();
+export function impactSnapshot(root) {
+    return storeFor(root)?.snapshot();
 }
 /**
  * What one tool call did, as counters.
@@ -71,6 +118,42 @@ export function deltaForToolResult(raw, durationMs, refused) {
     }
     return delta;
 }
+/**
+ * What one FAILED verdict was, in a line.
+ *
+ * Only a verified:"no" produces one. That is the same rule the counters follow and the same rule
+ * the product states to agents: an "unknown" is not a defect, it is Reticle admitting it could not
+ * tell — recording those here would fill the user's short list with the tool's own blind spots.
+ *
+ * Everything is read from the result the tool already returned, so this costs nothing extra and
+ * cannot disagree with the verdict it describes.
+ */
+export function defectForToolResult(raw, at) {
+    if (!isRecord(raw) || raw['verified'] !== Verified.NO)
+        return undefined;
+    const effect = isRecord(raw['effect']) ? raw['effect'] : undefined;
+    const verdict = isRecord(raw['verdict']) ? raw['verdict'] : undefined;
+    const named = text(effect?.['name']) ?? text(effect?.['testid']) ?? text(effect?.['component']);
+    const why = text(verdict?.['failureReason']) ?? text(raw['because']);
+    const defect = {
+        at,
+        // The control that was acted on, when the result names one — "Sign In did not sign in" is a
+        // sentence somebody can act on; "a verdict failed" is not.
+        title: named === undefined ? (why ?? 'a declared consequence did not hold') : named,
+    };
+    if (named !== undefined && why !== undefined)
+        defect.detail = why;
+    const source = text(raw['source']);
+    if (source !== undefined)
+        defect.source = source;
+    return defect;
+}
+function text(value) {
+    if ('string' !== typeof value)
+        return undefined;
+    const trimmed = value.trim();
+    return 0 === trimmed.length ? undefined : trimmed;
+}
 function isRecord(value) {
     return 'object' === typeof value && null !== value;
 }

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

@@ -1,8 +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;
 }
+/**
+ * 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 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. */
@@ -17,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,6 +14,8 @@ 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`.
@@ -24,6 +26,26 @@ function impactPaths(reticleRoot) {
         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.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";
@@ -69,13 +69,20 @@ 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.
  *

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';
@@ -76,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.
+
+Stopping to ask is how a verification turn ends with nothing verified.
 
-Five guards, none optional:
+Four guards, none optional:
 
-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.`;
+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.
  *

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;