@reticlehq/server 2.8.0 → 2.10.0

package/dist/impact/impact-store.js

@@ -0,0 +1,171 @@
+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';
+/**
+ * Where Reticle keeps the record of what it has done for you.
+ *
+ * Two scopes, two files, both local and never uploaded: the project's own `.reticle/impact.json`,
+ * and a machine-wide `~/.reticle/impact.json` that answers "what has Reticle done for me overall"
+ * across every app you have instrumented.
+ *
+ * This is NOT telemetry. Telemetry answers our questions about the product and leaves the machine;
+ * this answers the user's question about their own work and never does.
+ */
+/** Writes are debounced: a verification loop is 50-200 calls, and each one is a counter bump. */
+const WRITE_DEBOUNCE_MS = 800;
+/**
+ * `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) {
+    return {
+        project: join(reticleRoot, ReticleDir.IMPACT_FILE),
+        global: join(homedir(), ReticleDir.ROOT, ReticleDir.IMPACT_FILE),
+    };
+}
+function emptyScope(now) {
+    const counts = emptyImpactCounts();
+    return {
+        counts,
+        days: [],
+        records: emptyImpactRecords(),
+        savings: estimateImpactSavings(counts),
+        since: now,
+    };
+}
+/** Read a scope, tolerating absence and corruption: a broken file starts over rather than throwing. */
+export function readScope(path, now) {
+    try {
+        const parsed = JSON.parse(readFileSync(path, 'utf8'));
+        const result = ImpactScopeSchema.safeParse(parsed);
+        return result.success ? result.data : emptyScope(now);
+    }
+    catch {
+        return emptyScope(now);
+    }
+}
+/**
+ * Write a scope atomically.
+ *
+ * tmp + rename, because two daemons can serve two apps in the same repo at once and a half-written
+ * counters file is one the next read discards - silently losing the whole history.
+ */
+function writeScope(path, scope) {
+    try {
+        mkdirSync(dirname(path), { recursive: true });
+        const tmp = `${path}.${String(process.pid)}.tmp`;
+        writeFileSync(tmp, JSON.stringify(scope, null, 2), 'utf8');
+        renameSync(tmp, path);
+    }
+    catch {
+        // A stats file that cannot be written must never break a tool call. The counters stay in
+        // memory and the next write attempt carries them.
+    }
+}
+/** YYYY-MM-DD in local time - the day boundary a person recognises, not UTC's. */
+export function isoDay(now) {
+    const d = new Date(now);
+    const month = String(d.getMonth() + 1).padStart(2, '0');
+    const day = String(d.getDate()).padStart(2, '0');
+    return `${String(d.getFullYear())}-${month}-${day}`;
+}
+/** Whether `b` is the calendar day right after `a` - the streak rule. */
+function isNextDay(a, b) {
+    const prev = new Date(`${a}T00:00:00`);
+    const next = new Date(`${b}T00:00:00`);
+    return 1 === Math.round((next.getTime() - prev.getTime()) / 86_400_000);
+}
+/** Fold one delta into a scope: totals, today's bucket, records and streak. Pure. */
+export function applyDelta(scope, delta, now, meta = {}) {
+    const today = isoDay(now);
+    const counts = addImpactCounts(scope.counts, delta);
+    const days = scope.days.slice();
+    const last = days[days.length - 1];
+    if (last !== undefined && last.date === today) {
+        days[days.length - 1] = { date: today, counts: addImpactCounts(last.counts, delta) };
+    }
+    else {
+        days.push({ date: today, counts: addImpactCounts(emptyImpactCounts(), delta) });
+    }
+    while (days.length > IMPACT_DAILY_BUCKETS)
+        days.shift();
+    const todayCounts = days[days.length - 1]?.counts ?? emptyImpactCounts();
+    const previousDay = days[days.length - 2];
+    const records = { ...scope.records };
+    records.bestVerdictDay = Math.max(records.bestVerdictDay, todayCounts.verdicts);
+    records.bestDefectDay = Math.max(records.bestDefectDay, todayCounts.failed);
+    if (last === undefined || last.date !== today) {
+        // A new day joins the streak only if it follows yesterday; otherwise it starts a new one.
+        records.streakDays =
+            previousDay !== undefined && isNextDay(previousDay.date, today) ? records.streakDays + 1 : 1;
+    }
+    else if (0 === records.streakDays) {
+        records.streakDays = 1;
+    }
+    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 };
+}
+/**
+ * The live impact record for one project.
+ *
+ * Holds both scopes in memory, folds deltas in synchronously (so a reader always sees the truth),
+ * and flushes to disk on a debounce.
+ */
+export class ImpactStore {
+    #paths;
+    #now;
+    #projectName;
+    #project;
+    #global;
+    #timer;
+    #onChange;
+    constructor(opts) {
+        this.#paths = impactPaths(opts.reticleRoot);
+        this.#now = opts.now ?? (() => Date.now());
+        this.#projectName = opts.projectName;
+        const now = this.#now();
+        this.#project = readScope(this.#paths.project, now);
+        this.#global = readScope(this.#paths.global, now);
+    }
+    /** Notified after every fold, so the HUD can be pushed a fresh snapshot. */
+    onChange(fn) {
+        this.#onChange = fn;
+    }
+    record(delta, meta = {}) {
+        const now = this.#now();
+        this.#project = applyDelta(this.#project, delta, now, meta);
+        this.#global = applyDelta(this.#global, delta, now, meta);
+        this.#scheduleFlush();
+        this.#onChange?.();
+    }
+    snapshot() {
+        const snap = {
+            schemaVersion: IMPACT_SCHEMA_VERSION,
+            project: this.#project,
+            global: this.#global,
+        };
+        if (this.#projectName !== undefined)
+            snap.projectName = this.#projectName;
+        return snap;
+    }
+    /** Write now (process exit, tests). */
+    flush() {
+        if (this.#timer !== undefined) {
+            clearTimeout(this.#timer);
+            this.#timer = undefined;
+        }
+        writeScope(this.#paths.project, this.#project);
+        writeScope(this.#paths.global, this.#global);
+    }
+    #scheduleFlush() {
+        if (this.#timer !== undefined)
+            return;
+        this.#timer = setTimeout(() => {
+            this.#timer = undefined;
+            this.flush();
+        }, WRITE_DEBOUNCE_MS);
+        this.#timer.unref?.();
+    }
+}

package/dist/index.d.ts

@@ -28,6 +28,24 @@ export { VisualStore } from './visual/visual-store.js';
 export { diffPng } from './visual/visual-diff.js';
 export type { VisualDiffResult, VisualRect, DiffOptions } from './visual/visual-diff.js';
 export { crawl } from './crawl/crawl.js';
+/**
+ * The contradiction pass, and the seam a consumer adds its own rules through.
+ *
+ * Exported because a service embedding this engine grades a recording the same way the tools do, and
+ * without these it would have to re-implement the fold — a second implementation of the one thing
+ * this product is judged on, and the one nobody dogfoods is the one that rots.
+ */
+export { findContradictions } from './events/contradictions.js';
+/**
+ * The MCP server factory, so a consumer can serve the tool surface it composed.
+ *
+ * Without this the composition seam is unreachable from outside the package: a consumer can build the
+ * list and has nothing to hand it to.
+ */
+export { createMcpServer } from './mcp/mcp.js';
+export type { Contradiction, ContradictionOptions } from './events/contradictions.js';
+export { registerContradictionFold, registeredContradictionFolds, } from './events/contradiction-folds.js';
+export type { ContradictionFold } from './events/contradiction-folds.js';
 export { MCP_SSE_PATH, MCP_MESSAGE_PATH } from '@reticlehq/core';
 export { BrowserPool, DEFAULT_LEASE_TTL_MS } from './pool/browser-pool.js';
 export type { Lease, Launcher, PooledBrowser } from './pool/browser-pool.js';
@@ -123,6 +141,13 @@ export interface RunningServer {
     agentAttached?: () => boolean;
     /** The pairing token the bridge is enforcing (explicit, env, or auto-provisioned); undefined if none. */
     token?: string;
+    /**
+     * Tell every attached MCP proxy this daemon is retiring, before anything closes.
+     *
+     * Optional because only the daemon entry point serves MCP over SSE — `start()` speaks stdio, where
+     * the client owns the process and there is no stream to warn. See SharedServer.announceShutdown.
+     */
+    announceShutdown?: () => void;
     close: () => Promise<void>;
 }
 export { resolveBridgeSecurity } from './bridge/bridge-security.js';

package/dist/index.js

@@ -11,6 +11,7 @@ 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 { initImpact } from './impact/impact-recorder.js';
 import { FlowStore } from './flows/flows.js';
 import { buildFlowChips } from './flows/flow-scope.js';
 import { ProjectStore } from './project/project-store.js';
@@ -23,6 +24,8 @@ 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/mcp.js';
+import { LEASE_ACQUIRE_TOOL } from './tools/lease-tools.js';
+import { runTool } from './tools/invoke-tool.js';
 import { SessionReaper, endAllSessions, MCP_DISCONNECT_SUMMARY } from './session/session-reaper.js';
 import { wireSessionScope } from './session/no-session-watch.js';
 import { buildIdlePredicate } from './daemon/daemon-usefulness.js';
@@ -34,9 +37,13 @@ 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/cli-port.js';
+import { hasProjectConnectedBefore } from './session/connection-memory.js';
+import { reticleStateHome } from './daemon/daemon.js';
+import { probeChromium } from './cli/chromium-hint.js';
 import { makeJournalAttach } from './journal/attach-journal.js';
 import { makeSessionEnd } from './journal/session-end.js';
 import { AmbientStore } from './journal/ambient-store.js';
+import { ensureWorkspaceGitignore } from './journal/workspace-gitignore.js';
 import { pruneSessions } from './journal/retention.js';
 import { log } from './log.js';
 /** A human-facing one-liner for a panel replay verdict — ✓ passed / ⚠ drifted / ✗ errored. */
@@ -65,6 +72,22 @@ export { ProjectStore } from './project/project-store.js';
 export { VisualStore } from './visual/visual-store.js';
 export { diffPng } from './visual/visual-diff.js';
 export { crawl } from './crawl/crawl.js';
+/**
+ * The contradiction pass, and the seam a consumer adds its own rules through.
+ *
+ * Exported because a service embedding this engine grades a recording the same way the tools do, and
+ * without these it would have to re-implement the fold — a second implementation of the one thing
+ * this product is judged on, and the one nobody dogfoods is the one that rots.
+ */
+export { findContradictions } from './events/contradictions.js';
+/**
+ * The MCP server factory, so a consumer can serve the tool surface it composed.
+ *
+ * Without this the composition seam is unreachable from outside the package: a consumer can build the
+ * list and has nothing to hand it to.
+ */
+export { createMcpServer } from './mcp/mcp.js';
+export { registerContradictionFold, registeredContradictionFolds, } from './events/contradiction-folds.js';
 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';
@@ -172,8 +195,14 @@ function attachJournal(bridge, deps) {
     });
     // Teardown: flush the journal tail to disk + persist what this session learned.
     bridge.attachSessionEnd(makeSessionEnd(deps));
-    if (deps.enabled)
+    if (deps.enabled) {
         void pruneSessions(deps.fs, deps.reticleRoot);
+        // Here rather than in `init`, because this is the moment we are actually about to write into
+        // somebody's repository — and the paths that reach it without ever running `init` (a plugin
+        // install, a hand-added client config) are exactly the ones that would otherwise leave an
+        // unexplained pile of untracked files behind. Best-effort and write-once; see the helper.
+        void ensureWorkspaceGitignore(deps.fs, deps.reticleRoot);
+    }
 }
 /**
  * Resolve the drive/real-input provider from options — shared by start and startDaemon so the
@@ -224,6 +253,10 @@ async function resolveRealInput(options, onNavigateError, onNetworkDetail) {
 /** Start the Reticle bridge (browser WS endpoint) and, by default, the MCP stdio server. */
 export async function start(options = {}) {
     const port = options.port ?? RETICLE_DEFAULT_PORT;
+    // Open the user's impact record before anything can connect. Not inside the MCP branch: a daemon
+    // serving a browser with no agent attached still has a HUD to answer, and a report that reads
+    // "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 });
     // Server-authoritative liveness: a Node-side reaper (immune to browser throttling) ends sessions
@@ -271,12 +304,13 @@ export async function start(options = {}) {
             reticleRoot,
             now,
             bridgePort: port,
+            browserProbe: probeChromium,
             // The daemon's OWN project, so a tool can tell "this session is mine" from "this session
             // belongs to a sibling app under the same daemon". contract_save refuses on the second.
             ...(activeProjectId === undefined ? {} : { projectId: activeProjectId }),
         };
         const profile = resolveToolSurface(options.toolProfile);
-        const server = createMcpServer(realInput !== undefined ? { ...deps, realInput } : deps, profile);
+        const server = createMcpServer(realInput !== undefined ? { ...deps, realInput } : deps, profile, hasProjectConnectedBefore(reticleStateHome(), port, activeProjectId));
         // 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
         // self-ends via SESSION_LIFECYCLE.BRIDGE_LOST_MS — see transport.ts.)
@@ -308,6 +342,12 @@ export async function start(options = {}) {
  */
 export async function startDaemon(options = {}) {
     const port = options.port ?? RETICLE_DEFAULT_PORT;
+    // The SAME line as in `start`, because these are two entry points that each wire their own world
+    // and the daemon is the one that actually serves people. Wired only in `start`, the impact record
+    // was never opened in the process the HUD talks to: tool calls still recorded (the dispatch
+    // chokepoint opens it lazily), but a tab that connected before the first tool call was pushed
+    // nothing, so the report read "nothing recorded yet" over a file with history in it.
+    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 });
@@ -332,13 +372,6 @@ export async function startDaemon(options = {}) {
     });
     const reaper = new SessionReaper(bridge.sessions);
     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.
-    // 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.
-    // The pool reader is passed lazily: `pool` is assigned above but may be undefined when this
-    // daemon runs without one, and the diagnosis must degrade to the tab message rather than lie.
-    wireSessionScope(bridge.sessions, readProjectId(process.cwd()), port, () => pool?.reapedLeaseCount() ?? 0);
     const { realInput, owned } = await resolveRealInput(options, () => shared.close(), makeNetworkDetailRouter(bridge, options.driveUrl));
     const fs = createNodeFileSystem();
     const reticleRoot = options.reticleRoot ?? join(process.cwd(), ReticleDir.ROOT);
@@ -352,6 +385,14 @@ export async function startDaemon(options = {}) {
     const pool = createBrowserPool(options.headless ?? true);
     const leaseReaper = new LeaseReaper(pool);
     leaseReaper.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.
+    // 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.
+    // 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));
     const deps = {
         sessions: bridge.sessions,
         pool,
@@ -364,10 +405,18 @@ export async function startDaemon(options = {}) {
         reticleRoot,
         now,
         bridgePort: port,
+        browserProbe: probeChromium,
     };
     const profile = resolveToolSurface(options.toolProfile);
     const effectiveDeps = realInput !== undefined ? { ...deps, realInput } : deps;
-    shared.attachMcp(() => createMcpServer(effectiveDeps, profile));
+    // Read per attach, not once: a project that gets wired while this daemon is alive should stop
+    // being told to wire itself on the next agent that connects.
+    shared.attachMcp(() => createMcpServer(effectiveDeps, profile, hasProjectConnectedBefore(reticleStateHome(), port, readProjectId(process.cwd()))));
+    // `reticle drive <url>` when this daemon already owns the port: it asks HERE instead of trying to
+    // bind a port we are holding, and gets the same pooled context an agent's reticle_lease returns —
+    // through runTool, so it is counted and reported like any other call rather than being a second,
+    // invisible dispatch path. See cli/drive-attach.ts for why attaching beats refereeing the race.
+    shared.attachDrive((url) => runTool(LEASE_ACQUIRE_TOOL, effectiveDeps, { url }));
     // 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`.
@@ -454,6 +503,7 @@ export async function startDaemon(options = {}) {
         // 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,
+        announceShutdown: () => shared.announceShutdown(),
         close: async () => {
             reaper.stop();
             await cleanupCaptureDirectories();

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

@@ -47,6 +47,26 @@ export declare const CURSOR_RULE_PATH = ".cursor/rules/reticle.mdc";
  * the package's own name so the two can never drift apart.
  */
 export declare const CLI: string;
+/**
+ * Who starts the dev server, stated once and rendered everywhere it is needed.
+ *
+ * The old rule was "Reticle never starts the dev server for you — that's your job", and agents obeyed
+ * it exactly: they read it, declined to start anything, and ended the turn with nothing verified. An
+ * instruction that reliably produces no verification is a defect in the instruction.
+ *
+ * The AGENT starts it, not the daemon. A daemon that spawns a build process is invisible to the
+ * person whose machine it is running on, was never consented to, and orphans when the daemon exits.
+ * The agent already has shell access in this repo, already runs install and build commands, and runs
+ * 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.
+ *
+ * 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.";
 /** 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

@@ -52,6 +52,34 @@ const RULE_END = '<!-- reticle:end -->';
  * the package's own name so the two can never drift apart.
  */
 export const CLI = `${NPX} ${RETICLE_NPM_PACKAGE}`;
+/**
+ * Who starts the dev server, stated once and rendered everywhere it is needed.
+ *
+ * The old rule was "Reticle never starts the dev server for you — that's your job", and agents obeyed
+ * it exactly: they read it, declined to start anything, and ended the turn with nothing verified. An
+ * instruction that reliably produces no verification is a defect in the instruction.
+ *
+ * The AGENT starts it, not the daemon. A daemon that spawns a build process is invisible to the
+ * person whose machine it is running on, was never consented to, and orphans when the daemon exits.
+ * The agent already has shell access in this repo, already runs install and build commands, and runs
+ * 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.
+ *
+ * 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.
+
+Five 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.`;
 /**
  * The operative rules, carried by every file that loads on every turn.
  *
@@ -75,6 +103,12 @@ 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.
 
+**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.
+
 **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.
@@ -82,6 +116,8 @@ This app is instrumented by **Reticle**, an in-app verification layer exposed as
 - **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.
+
 **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.js

@@ -11,7 +11,7 @@
  * 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 { RETICLE_DEFAULT_PORT, ReticleDir, bridgeWsUrl } from '@reticlehq/core';
 import { PatchKind } from './patch-kind.js';
 import { UiLibrary } from './detect.js';
 import { sdkImport } from './snippets.js';
@@ -31,6 +31,26 @@ const LAYOUT_MARKER = 'reticle.connect';
  * never got it.
  */
 const SDK_INCLUDE_LITERAL = `'@reticlehq/react'`;
+/**
+ * The daemon's journal directory, kept out of the dev server's watcher.
+ *
+ * The daemon writes `.reticle/` into the project root and rewrites `ambient.json` atomically
+ * (`.tmp` + rename) for as long as a session is live. Astro dev is a Vite dev server watching that
+ * root, and `.reticle/` is not in Vite's default ignore list — so every journal write read as a
+ * project file changing and Vite answered with a full page reload. That closes a loop with no exit:
+ * the page loads, the SDK connects and streams events, the daemon journals them, Vite reloads the
+ * page, the SDK reconnects. It ran several times a second for as long as the dev server was up,
+ * and the symptom looked nothing like the cause — stale refs, actions dying mid-flight, and a log
+ * full of connect/disconnect pairs that read as a flapping SDK.
+ *
+ * The Vite plugin sets the same ignore in its `config` hook. Astro is hand-patched and never loads
+ * that plugin, so it needs its own.
+ *
+ * A RegExp, not a glob. chokidar dropped glob support in v4 and Vite 7+ ships v4/v5, where a
+ * double-star pattern is accepted and matches nothing — the ignore would be visibly present in the
+ * config and do nothing at all. Measured against the chokidar this repo resolves.
+ */
+const WATCH_IGNORE_LITERAL = `/(^|[\\\\/])\\.${ReticleDir.ROOT.slice(1)}([\\\\/]|$)/`;
 /**
  * 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
@@ -72,12 +92,17 @@ const VITE_KEYS = [
         key: 'define',
         inner: `\n      __RETICLE_TOKEN__: JSON.stringify(reticleToken()),\n      __RETICLE_ROOT__: JSON.stringify(process.cwd()),`,
     },
+    // Merged in first, so a `server: { port }` the app already set keeps its port. An app that
+    // already sets `server.watch` itself is the one shape this loses to — the inner `watch` key would
+    // be duplicated and the app's would win — which is the same nested-merge ceiling `build` has.
+    { key: 'server', inner: `\n      watch: { ignored: [${WATCH_IGNORE_LITERAL}] },` },
 ];
 /** 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    },`,
+    server: `\n    server: { watch: { ignored: [${WATCH_IGNORE_LITERAL}] } },`,
 };
 /**
  * Add our keys to an existing `vite: { ... }` block, merging into any the app already set.
@@ -157,6 +182,7 @@ const VITE_BLOCK = `  vite: {
       __RETICLE_TOKEN__: JSON.stringify(reticleToken()),
       __RETICLE_ROOT__: JSON.stringify(process.cwd()),
     },
+    server: { watch: { ignored: [${WATCH_IGNORE_LITERAL}] } },
   },
 `;
 export function patchAstroConfig(source) {

package/dist/init/confirm.d.ts

@@ -19,9 +19,11 @@
  *    keeps today's cost and today's exit behaviour, and blocking never happens where blocking is
  *    wrong. The signal is the standard "am I being piped" one and needs no argument parsing, which
  *    also keeps `init`'s documented flag surface where it is.
- *  - It never starts anything. Reticle attaches to what is already running and does not manage a
- *    dev server; that rule holds here too. So the honest shape is: confirm the app if it connects,
- *    otherwise name the ONE command that is outstanding and the one that proves it worked.
+ *  - It never starts anything. A dev server started by a long-lived daemon is invisible to the
+ *    person whose machine it runs on and orphans when the daemon exits, so the daemon stays out of
+ *    it — the AGENT starts one, under the guards in agent-rules.ts, because it is attributable and
+ *    stoppable there. So the honest shape here is: confirm the app if it connects, otherwise name
+ *    the ONE command that is outstanding and the one that proves it worked.
  */
 import { InitConfirmation } from '@reticlehq/core';
 import type { InitOutcome } from '@reticlehq/core';
@@ -76,6 +78,22 @@ export declare function confirmAppConnected(deps: ConfirmDeps): Promise<InitConf
  * up when the agent loads the tools — so it is a notice.
  */
 export declare function confirmationMessage(confirmation: InitConfirmation, port: number): string;
+/**
+ * What a non-TTY run says instead of waiting.
+ *
+ * `init` deliberately does not block when nobody is at the terminal — a 12-second wait in a script
+ * is wrong, and an agent driving `init` through a shell is never a TTY. But silence was the wrong
+ * other half of that decision: the agent path IS the prescribed path (every skill and every README
+ * block tells an agent to run exactly this command), so the one message joining "init finished" to
+ * "an app connected" was withheld from most of the people who run it. They were left with files on
+ * disk, an exit code of 0, and nothing saying the page half had not happened.
+ *
+ * It claims nothing it did not check. It did not look for a session, so it does not say whether one
+ * exists — a one-shot look would be worse than none, because a daemon is shared across every project
+ * on the machine and "a session exists" is satisfied by somebody else's app, which is the false
+ * green `confirmAppConnected` refuses by design.
+ */
+export declare function unwatchedMessage(port: number): string;
 /**
  * Finish `init` on evidence rather than on a write.
  *

package/dist/init/confirm.js

@@ -19,9 +19,11 @@
  *    keeps today's cost and today's exit behaviour, and blocking never happens where blocking is
  *    wrong. The signal is the standard "am I being piped" one and needs no argument parsing, which
  *    also keeps `init`'s documented flag surface where it is.
- *  - It never starts anything. Reticle attaches to what is already running and does not manage a
- *    dev server; that rule holds here too. So the honest shape is: confirm the app if it connects,
- *    otherwise name the ONE command that is outstanding and the one that proves it worked.
+ *  - It never starts anything. A dev server started by a long-lived daemon is invisible to the
+ *    person whose machine it runs on and orphans when the daemon exits, so the daemon stays out of
+ *    it — the AGENT starts one, under the guards in agent-rules.ts, because it is attributable and
+ *    stoppable there. So the honest shape here is: confirm the app if it connects, otherwise name
+ *    the ONE command that is outstanding and the one that proves it worked.
  */
 import { InitConfirmation, RETICLE_DEFAULT_PORT } from '@reticlehq/core';
 import { fetchStatus, summarizeStatus } from '../cli/cli-launch.js';
@@ -89,10 +91,32 @@ export function confirmationMessage(confirmation, port) {
     }
     return ('  [⚠] no app has connected yet — the files are written, the page half of the install is not ' +
         'done.\n' +
-        '      Restart your dev server (Reticle attaches to it, it never starts it for you) and load ' +
-        'the app in a browser.\n' +
+        '      Restart your dev server and load the app in a browser — or ask your agent to, which it is ' +
+        'now told to do for you, in the background and with the command from your own scripts.\n' +
         `      ${PROVE_COMMAND} then confirms it, or says exactly why it has not connected.`);
 }
+/**
+ * What a non-TTY run says instead of waiting.
+ *
+ * `init` deliberately does not block when nobody is at the terminal — a 12-second wait in a script
+ * is wrong, and an agent driving `init` through a shell is never a TTY. But silence was the wrong
+ * other half of that decision: the agent path IS the prescribed path (every skill and every README
+ * block tells an agent to run exactly this command), so the one message joining "init finished" to
+ * "an app connected" was withheld from most of the people who run it. They were left with files on
+ * disk, an exit code of 0, and nothing saying the page half had not happened.
+ *
+ * It claims nothing it did not check. It did not look for a session, so it does not say whether one
+ * exists — a one-shot look would be worse than none, because a daemon is shared across every project
+ * on the machine and "a session exists" is satisfied by somebody else's app, which is the false
+ * green `confirmAppConnected` refuses by design.
+ */
+export function unwatchedMessage(port) {
+    return ('  [ℹ] the files are written. An app CONNECTING is what finishes the install, and this run did ' +
+        'not wait to see one.\n' +
+        '      Start the dev server, load the app in a browser, then ' +
+        `${PROVE_COMMAND} — it confirms the app, or says exactly why it has not connected.\n` +
+        `      Bridge port ${String(port)}.`);
+}
 const WATCHING = (windowMs) => `  watching for an app to connect (up to ${String(Math.round(windowMs / 1000))}s) — Ctrl-C is safe, ` +
     'everything above is already written.';
 /**
@@ -110,6 +134,9 @@ export async function confirmInstall(result, io, deps, report = reportInitOutcom
     if (outcome === undefined)
         return;
     if (!deps.interactive) {
+        // Still no waiting — see unwatchedMessage for why it speaks anyway.
+        io.print('');
+        io.print(unwatchedMessage(deps.port));
         report(outcome);
         return;
     }

package/dist/init/connect-steps.d.ts

@@ -0,0 +1,2 @@
+/** True when this step is what makes the app dial the daemon. */
+export declare function isConnectStep(title: string): boolean;