@reticlehq/server 2.11.0 → 2.12.0

package/dist/honesty/undeclared-change.js

@@ -0,0 +1,56 @@
+import { NO_EDITS_OBSERVED } from '@reticlehq/core';
+/**
+ * Is this verdict being drawn over code nobody said anything about?
+ *
+ * Declaring intent is opt-in, and nothing has ever noticed that a change landed and nobody said what
+ * it was supposed to make true. That is the moment it matters: a change with no declared intent can
+ * only be verified against itself, which is the definition of a false green.
+ *
+ * ## Why this fires on EVERY verdict, not once per change
+ *
+ * The house rule is that a gap nobody hit is a backlog, and a backlog reported as a finding is how
+ * an agent learns to stop reading findings. This clears that bar on the same test every other
+ * instrumentation gap clears it on: **did the absence make THIS verdict weaker?** An unwatched store
+ * weakens every state assertion made over it, not merely the first, so it is reported on every one.
+ * An undeclared change is the same shape — while nothing says what the edit was for, each verdict
+ * drawn after it is checked against nothing but itself, and that is true of the fifth one exactly as
+ * it was of the first. Reporting it once and then falling silent would leave four verdicts carrying
+ * a weakness they no longer disclose, which is the failure mode this whole surface exists to prevent.
+ *
+ * It is also not a backlog, because it is not a survey of the project: it is answered from what this
+ * session observed (an epoch that moved) about the verdict being returned right now, and it is
+ * closed by one call the agent can make immediately. A finding that stays open only because the
+ * agent has not made that call is a finding about the current verdict, not a chore.
+ *
+ * ## The silences, and why each one is required
+ *
+ *  - **An edit was actually OBSERVED.** The epoch degrades to `NO_EDITS_OBSERVED` outside Vite, and
+ *    that means "no edits observed", never "no edits happened" — a finding built on an absence
+ *    Reticle cannot see would be a fabrication.
+ *  - **The ledger holds nothing undischarged.** An open intent IS the declaration; silence is the
+ *    correct response to it, and declaring one is what turns this off from the next verdict on.
+ *
+ * ## Why "covers the work" is answered as "anything open at all"
+ *
+ * The tempting answer is to match the intent's `surface` against the files that changed. Reticle
+ * cannot do that honestly: it observes that an epoch advanced, not WHAT advanced — the hot-update
+ * channel reports a counter, not a diff — so any file-level matching would be inference dressed as a
+ * fact, and it would fire on an agent that had declared its intent perfectly well. Over-reporting on
+ * a correct agent is the direction of error that trains it to stop reading findings.
+ *
+ * So the question asked is the coarse one, and it is asked honestly: has the agent declared anything
+ * that is still outstanding? If it has, it is working to a stated purpose and this stays quiet.
+ */
+/**
+ * `openIntents` is a thunk rather than a list because reading the ledger touches disk, and the epoch
+ * check answers without it for every page that never reported a hot update — which is most of them.
+ * Once an edit HAS been observed the read happens per verdict, and that is the intended cost: the
+ * ledger is the only thing that can end it, so it has to be re-asked each time.
+ */
+export async function isChangeUndeclared(
+/** The epoch the session is under now. Undefined when the page never stamped one. */
+currentEpoch, openIntents) {
+    if (undefined === currentEpoch || NO_EDITS_OBSERVED === currentEpoch)
+        return false;
+    return 0 === (await openIntents()).length;
+}

package/dist/honesty/verified.d.ts

@@ -76,6 +76,21 @@ interface VerifiedInputs {
      * Empty means nothing went unread.
      */
     outcomeUnread?: readonly string[];
+    /**
+     * The declared consequence that held does not depend on the response body — an exact string
+     * rendered, a store path, a signal. See `declaresBodyIndependentChannel`.
+     *
+     * The unread-body clause exists for the case where the body is the ONLY channel that could have
+     * contradicted the screen (a 200 with batch/GraphQL errors inside). When a body-independent
+     * declaration held, that is no longer true, and grading `unknown` costs a real verdict. The unread
+     * labels still ride out in `because`, the way absence-derived contradictions still ride out in
+     * `contradictions`.
+     *
+     * Narrow: it does not soften a 202, an observed contradiction, a dirty capture, or a net-only
+     * declaration. `declaredConsequence` alone is not enough — a `{ kind: "net", status: 200 }` is a
+     * declaration whose remaining channel IS the body.
+     */
+    independentOfBody?: boolean;
     /**
      * What the wait was for and what the window held when it ended — read ONLY by the two clauses that
      * answer UNSETTLED, which is the commonest reason a verdict comes back `unknown` and was also the

package/dist/honesty/verified.js

@@ -31,6 +31,24 @@ export function decideVerified(inputs) {
                 'to repeat',
         };
     }
+    // ABOVE the failure clause, for the third time and the same reason: absence is not evidence.
+    //
+    // Omitting `until` waits for the page to SETTLE. Nobody declared a consequence, so a settle that
+    // times out says "the page was still busy when I stopped looking" — the definition of an
+    // absence-derived finding. The failure clause below took it at face value and returned
+    // `verified: "no"` with `because: 'the declared consequence did not hold'`, naming a consequence
+    // that does not exist. Measured on the hard fixture, whose push updates mean it never goes idle:
+    // a healthy pagination click was graded NO. Any app with polling or a live feed gets accused of a
+    // defect for being alive, which is the false NEGATIVE the ABSENCE_DERIVED doctrine exists to stop.
+    if (false === pass && false === inputs.declaredConsequence) {
+        return {
+            verified: Verified.UNKNOWN,
+            verifiedReason: VerifiedReason.UNSETTLED,
+            because: 'no consequence was declared, so this only waited for the page to go idle and it never ' +
+                'did — that is a statement about when Reticle stopped looking, not about the app. Pass ' +
+                '`until` naming what the action should cause (a signal, a request, a route, or store state)',
+        };
+    }
     // A failed assertion is the most actionable fact there is; it leads — including over
     // `alreadyTrue`, because a condition that held before AND fails now is a real regression.
     if (false === pass) {
@@ -82,6 +100,27 @@ export function decideVerified(inputs) {
         inputs.unsettled !== undefined &&
         !openWrite &&
         contradictions.every((c) => c.kind === ContradictionKind.REQUEST_NEVER_SETTLED);
+    // `signal-without-consequence` gets its own sentence, because the generic one is FALSE for it.
+    //
+    // That sentence says the window "closed before the app finished" and then explains that a poll or
+    // a timer kept the page busy. Nothing kept this page busy — nothing happened at all, which is the
+    // entire finding. Measured on the bench fixture: the correct UNKNOWN arrived wearing an
+    // explanation that told the agent to wait longer or assert something else, when the fact to act on
+    // was that the app announced a consequence it did not deliver. A right verdict with a wrong reason
+    // sends an agent to the wrong place, which costs as much as the wrong verdict did.
+    const signalOnly = contradictions.length > 0 &&
+        contradictions.every((c) => c.kind === ContradictionKind.SIGNAL_WITHOUT_CONSEQUENCE);
+    if (signalOnly) {
+        return {
+            verified: Verified.UNKNOWN,
+            verifiedReason: VerifiedReason.EVIDENCE_INCOMPLETE,
+            because: 'the app fired the signal you waited for and NOTHING else moved — no DOM, no store, no ' +
+                'route, no request — so the only evidence is the app saying so. A signal emitted from the ' +
+                'value the app was ASKED for, rather than the one it committed, looks exactly like this. ' +
+                'Check the consequence directly (reticle_snapshot for what rendered, reticle_state for what ' +
+                'the store holds) before trusting it',
+        };
+    }
     if (contradictions.length > 0 && !settlementOnly) {
         const kinds = contradictions.map((c) => c.kind).join(', ');
         return {
@@ -142,7 +181,21 @@ export function decideVerified(inputs) {
     // Gated on `true === settled` rather than on a caller's say-so. A call that returned before the app
     // stopped moving has not earned this, whatever it declared — which is what stops `no-fault` from
     // becoming the green-forever button an always-available "nothing was wrong" would be.
-    if (honesty.grade === HonestyGrade.NONE) {
+    // Two ways to have proved nothing, and only one of them used to be caught. Grade NONE is the
+    // engine's own reading — no signal, no request, no state change, nothing pinned. An explicit
+    // `declaredConsequence: false` is the CALLER saying it asserted nothing, which `act_and_wait`
+    // reports whenever `until` is omitted (an omitted `until` becomes `{kind:"settled"}` — a
+    // sleep-replacement, not an assertion).
+    //
+    // Grading alone missed the second case, because a click that merely moves the DOM lifts the grade
+    // to PRESENCE and walks past this branch into a full green. Measured live: clicking a submit
+    // button, and an inert text input, with no `until` both returned `verified:"yes"` /
+    // `verifiedReason:"proved"`. The claim it printed — "assertion held at presence grade" — was true
+    // about a grade and false about an assertion, because there was no assertion.
+    //
+    // It compounds: `reticle_context` persists proven claims, so an undeclared green becomes
+    // established fact for the agent that re-enters after a compaction.
+    if (honesty.grade === HonestyGrade.NONE || false === inputs.declaredConsequence) {
         if (true === settled) {
             return {
                 verified: Verified.NO_FAULT,
@@ -178,7 +231,15 @@ export function decideVerified(inputs) {
     //
     // UNKNOWN, not NO: nothing is known to have failed. The remedy is in the sentence, because an
     // agent that cannot act on a caveat will learn to skip it.
-    if (outcomeUnread !== undefined && outcomeUnread.length > 0) {
+    //
+    // Skipped when the caller declared a consequence that does not depend on the body and it held.
+    // The clause was written for the body being the ONLY remaining channel; a unique row on screen, a
+    // store path, or a signal that held is a different channel, and grading unknown there cost a real
+    // verdict (a 201 plus the exact message text, agent went to enable capture instead of finishing).
+    // The unread write still rides out in `because`. A net-only declaration does not skip: then the
+    // body is still the remaining channel.
+    const unreadHeldIndependently = declaredHeld && true === inputs.independentOfBody;
+    if (outcomeUnread !== undefined && outcomeUnread.length > 0 && !unreadHeldIndependently) {
         return {
             verified: Verified.UNKNOWN,
             verifiedReason: VerifiedReason.OUTCOME_UNREAD,
@@ -214,11 +275,14 @@ export function decideVerified(inputs) {
     const notIdle = false === settled
         ? ', though the page never went idle — this rests on the consequence you declared, not on the page going quiet'
         : '';
+    const unreadCaveat = unreadHeldIndependently && outcomeUnread !== undefined && outcomeUnread.length > 0
+        ? `, though a write returned 2xx with a response body that was never recorded (${outcomeUnread.join('; ')}) — a 200 describes the transport, not the result`
+        : '';
     return {
         verified: Verified.YES,
         verifiedReason: VerifiedReason.PROVED,
         because: true === honesty.coverage?.partial
-            ? `assertion held at ${honesty.grade} grade with no channel disagreeing, but coverage was PARTIAL — see \`coverage\` for what went unobserved${notIdle}`
-            : `assertion held at ${honesty.grade} grade over a clean capture with no channel disagreeing${notIdle}`,
+            ? `assertion held at ${honesty.grade} grade with no channel disagreeing, but coverage was PARTIAL — see \`coverage\` for what went unobserved${notIdle}${unreadCaveat}`
+            : `assertion held at ${honesty.grade} grade over a clean capture with no channel disagreeing${notIdle}${unreadCaveat}`,
     };
 }

package/dist/http-server.d.ts

@@ -50,4 +50,3 @@ export interface SharedServer {
 export declare function createSharedServer(options?: {
     token?: string;
 }): SharedServer;
-export declare function driveSchemeRefusal(url: string): string | undefined;

package/dist/http-server.js

@@ -330,7 +330,7 @@ function schemeOf(url) {
         return undefined;
     }
 }
-export function driveSchemeRefusal(url) {
+function driveSchemeRefusal(url) {
     const scheme = schemeOf(url);
     if (scheme !== undefined && DRIVEABLE_SCHEMES.includes(scheme))
         return undefined;

package/dist/hunt/hunt-report.d.ts

@@ -18,8 +18,6 @@
  * Pure functions over already-collected reports — the driving is `reticle_crawl`'s job, and running
  * it across a commit range is a shell loop. This is only the part that must not be done by eye.
  */
-/** The contradiction kinds — cross-channel disagreement, as opposed to a single-channel fault. */
-export declare const CONTRADICTION_KINDS: readonly string[];
 export interface HuntAnomaly {
     kind: string;
     ref?: string;

package/dist/hunt/hunt-report.js

@@ -19,7 +19,7 @@
  * it across a commit range is a shell loop. This is only the part that must not be done by eye.
  */
 /** The contradiction kinds — cross-channel disagreement, as opposed to a single-channel fault. */
-export const CONTRADICTION_KINDS = [
+const CONTRADICTION_KINDS = [
     'ui-advanced-request-failed',
     'signal-contradicted',
     'response-ignored',

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

@@ -3,11 +3,6 @@ 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`.
- */
-export declare function impactPaths(reticleRoot: string): ImpactPaths;
 /** 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. */

package/dist/impact/impact-store.js

@@ -18,7 +18,7 @@ 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) {
+function impactPaths(reticleRoot) {
     return {
         project: join(reticleRoot, ReticleDir.IMPACT_FILE),
         global: join(homedir(), ReticleDir.ROOT, ReticleDir.IMPACT_FILE),

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/init/agent-rules.d.ts

@@ -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.
  *
@@ -67,6 +76,14 @@ export declare const CLI: string;
  * 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 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

@@ -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.
  *
@@ -87,7 +98,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 +114,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/capabilities.d.ts

@@ -24,8 +24,6 @@ export interface FoundStore {
     /** Module specifier relative to `src/reticle-dev.ts`. */
     importPath: string;
 }
-/** Where the generated dev module lives, for Vite. Next passes its own. */
-export declare const DEFAULT_DEV_MODULE_DIR = "src";
 /**
  * Store instances declared in the app's own source, ready to import and register.
  *

package/dist/init/capabilities.js

@@ -102,7 +102,7 @@ function importPathFor(storePath, fromDir) {
     return rel.startsWith('.') ? rel : `./${rel}`;
 }
 /** Where the generated dev module lives, for Vite. Next passes its own. */
-export const DEFAULT_DEV_MODULE_DIR = 'src';
+const DEFAULT_DEV_MODULE_DIR = 'src';
 /**
  * Store instances declared in the app's own source, ready to import and register.
  *

package/dist/init/closing-hint.d.ts

@@ -0,0 +1,36 @@
+/**
+ * The last thing `init` prints, and the only part of it a user is asked to act on.
+ *
+ * Split out of `run.ts` because that file sits exactly at the 1000-line cohesion cap, and because
+ * this IS a separate concern: everything else in `run.ts` decides what to write, and this decides
+ * what to say afterwards. The two failure modes are different too — a wrong write breaks an
+ * install, a wrong sentence loses a user quietly.
+ */
+import { Framework } from './detect.js';
+import { StepStatus } from './plan.js';
+/**
+ * The standing ask, printed at the end of every `init`.
+ *
+ * Addressed to the agent as much as the human: whichever of them just ran this command is the one
+ * holding the experience, and neither has a Reticle tool surface to file through at this point.
+ *
+ * Printed by the `runInit` wrapper, NOT by `report()` — see the comment there for why, and for how
+ * the workspace redirect is kept from asking twice.
+ */
+export declare const FEEDBACK_HINT: string;
+/**
+ * The last two lines a user reads, and the order matters.
+ *
+ * This used to say only "Restart <dev server>, then ask your agent: List Reticle sessions" — and
+ * asking the agent was the one thing that could not work yet. `init` registers the MCP server, but
+ * an agent client reads its tool list when it STARTS and never re-reads it, so the session that
+ * just ran `init` has no `reticle_*` tools however clean the install was. The user follows the
+ * instruction, the agent answers "unknown tool", and the obvious conclusion is that the install
+ * failed.
+ *
+ * So the reload is named FIRST, before the sentence that depends on it. Omitted entirely when this
+ * run did not register MCP (`--no-mcp`), where it would be advice about something we did not do.
+ */
+export declare function restartHint(framework: Framework, mcpStatus: StepStatus | undefined, 
+/** The project's own dev command, when package.json named one. */
+devCommand?: string): string;

package/dist/init/closing-hint.js

@@ -0,0 +1,120 @@
+/**
+ * The last thing `init` prints, and the only part of it a user is asked to act on.
+ *
+ * Split out of `run.ts` because that file sits exactly at the 1000-line cohesion cap, and because
+ * this IS a separate concern: everything else in `run.ts` decides what to write, and this decides
+ * what to say afterwards. The two failure modes are different too — a wrong write breaks an
+ * install, a wrong sentence loses a user quietly.
+ */
+import { Framework } from './detect.js';
+import { StepStatus } from './plan.js';
+import { wasMcpRegistered } from './mcp-registered.js';
+import { CLI } from './agent-rules.js';
+/**
+ * The standing ask, printed at the end of every `init`.
+ *
+ * Addressed to the agent as much as the human: whichever of them just ran this command is the one
+ * holding the experience, and neither has a Reticle tool surface to file through at this point.
+ *
+ * Printed by the `runInit` wrapper, NOT by `report()` — see the comment there for why, and for how
+ * the workspace redirect is kept from asking twice.
+ */
+export const FEEDBACK_HINT = 'Anything wrong, missing, or awkward — in this setup or in Reticle itself? Tell us; it is the ' +
+    'one thing that decides what gets fixed:\n' +
+    `  ${CLI} feedback --agent --kind <bug|gap|ambiguity|feature_request|improvement> "what happened"   (agents)\n` +
+    `  ${CLI} feedback "what worked, what didn't"   (humans)`;
+/**
+ * What to say about the dev server.
+ *
+ * Names the project's own script when `package.json` has a recognisable one, and otherwise says the
+ * THING rather than guessing the command.
+ *
+ * The guesses that used to live here — `vite`, `next dev`, `astro dev` — were wrong often enough to
+ * be worth deleting. Measured on a real app: rowy has no `dev` script at all, so "Restart `vite`"
+ * sent the reader to work out what was meant instead of starting a server. Nobody needs the guess:
+ * an agent reading this can open package.json, and a human already knows how they start their own
+ * app. A wrong command costs more than a missing one.
+ */
+function devServerRestart(_framework, devCommand) {
+    return devCommand === undefined
+        ? 'Restart your dev server'
+        : `Restart your dev server (\`${devCommand}\`)`;
+}
+/**
+ * The last two lines a user reads, and the order matters.
+ *
+ * This used to say only "Restart <dev server>, then ask your agent: List Reticle sessions" — and
+ * asking the agent was the one thing that could not work yet. `init` registers the MCP server, but
+ * an agent client reads its tool list when it STARTS and never re-reads it, so the session that
+ * just ran `init` has no `reticle_*` tools however clean the install was. The user follows the
+ * instruction, the agent answers "unknown tool", and the obvious conclusion is that the install
+ * failed.
+ *
+ * So the reload is named FIRST, before the sentence that depends on it. Omitted entirely when this
+ * run did not register MCP (`--no-mcp`), where it would be advice about something we did not do.
+ */
+export function restartHint(framework, mcpStatus, 
+/** The project's own dev command, when package.json named one. */
+devCommand) {
+    const dev = `${devServerRestart(framework, devCommand)}.`;
+    // NAME THE COMMAND THAT PROVES IT, not one that merely asks.
+    //
+    // `init` writes files and stops; the install is not finished until an app carrying the SDK has
+    // actually dialled the daemon, and nothing here confirmed that. The field shape is unambiguous:
+    // people complete the agent half, never complete the app half, and keep a daemon running for
+    // weeks with nothing to drive — so this is the last instruction most of them read.
+    //
+    // "Ask your agent: List Reticle sessions" asks a question whose failure is a dead end. `reticle
+    // status` ANSWERS it: as of 2.7.0 it reports the session, or says why there is none — no app
+    // running, an app running that never dialled us, a tab that closed — with the fix for each.
+    // The one thing that works BEFORE the restart, so it goes before it.
+    //
+    // What comes after the restart, named as a JOB rather than as a capability.
+    //
+    // This used to point at a `reticle demo` command that opened its own browser and drove one
+    // control. It was cut: a demo command is a side show. The thing a user needs to see is THEIR app,
+    // instrumented in THEIR codebase, driven by THEIR agent through the tools they just installed —
+    // because that is the workflow they are deciding whether to adopt, and a bespoke demo path proves
+    // nothing about it.
+    //
+    // So the close hands the agent the sequence instead. It is deliberately one drive of one real
+    // flow ending in a verdict, because an install that ends in "the tools are available" is an
+    // install that ends in nothing.
+    const demo = 'Then drive one real flow of your app end to end and report the verdict — that is the install ' +
+        "proving itself, and it is the agent's job, not a separate command.";
+    const prove = 'Then run `npx @reticlehq/server status` — it confirms the app connected, or says exactly why ' +
+        'it has not.';
+    // Nothing registered this run (`--no-mcp`, or a client that needs a manual edit): a restart picks
+    // up nothing, so advice about one would be advice about something we did not do.
+    if (!wasMcpRegistered(mcpStatus))
+        return `${dev}\n${demo}\n${prove}`;
+    // ALREADY: the tools are reachable RIGHT NOW, and this is the branch that used to lie.
+    //
+    // `wasMcpRegistered` is true for both APPLY and ALREADY, which is correct for the funnel field it
+    // was written for and wrong here, because the two cases have opposite answers to "must anybody
+    // restart". Every second project on a machine, and every Claude Code plugin install, took the
+    // APPLY text: "restart your agent — the tools only appear after that". An agent reads this AFTER
+    // whatever its skill file said, and it describes the output in front of it, so it wins. The agent
+    // stops with the project wired and nothing driven, which is the exact failure the install path
+    // exists to prevent, caused by the install path itself.
+    if (mcpStatus === StepStatus.ALREADY) {
+        return (`${dev}\n` +
+            `${demo}\n` +
+            'The Reticle MCP server was already registered on this machine, so there is no restart to do ' +
+            'and the tools are available now.\n' +
+            `${prove}\n` +
+            'Once it shows a session, drive a flow — that is the install finished. Carry straight on; ' +
+            'nothing here is waiting on a human.');
+    }
+    return (`${dev}\n` +
+        `${demo}\n` +
+        'Then restart your agent so it picks up the new MCP server — restart Claude Code, reload the ' +
+        'window in Cursor, or hit Start in `.vscode/mcp.json` in VS Code.\n' +
+        'The tools only appear after that: your agent read its server list before Reticle existed, ' +
+        'and no slash command re-reads it (`/mcp` manages servers already loaded, so it cannot pick ' +
+        'up a new one). This is once per machine — Reticle is registered globally, so every later ' +
+        'project starts with the tools already there.\n' +
+        `${prove}\n` +
+        'Once it shows a session, drive one flow and report the verdict — that is the install ' +
+        'finished. Do it now; nothing here is waiting on a human.');
+}

package/dist/init/confirm.d.ts

@@ -27,15 +27,6 @@
  */
 import { InitConfirmation } from '@reticlehq/core';
 import type { InitOutcome } from '@reticlehq/core';
-/**
- * How long a human is asked to wait.
- *
- * Long enough for a page that is already loading to finish dialling, short enough that somebody who
- * has not restarted their dev server yet is not held hostage by a wait that cannot succeed — they
- * have not typed the command that would make it succeed, and the message tells them which one.
- */
-export declare const CONFIRM_WINDOW_MS = 12000;
-export declare const CONFIRM_POLL_MS = 500;
 export interface ConfirmDeps {
     /** Session ids connected right now, or null when nothing is listening on the bridge port. */
     listSessionIds: () => Promise<readonly string[] | null>;
@@ -78,22 +69,6 @@ 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

@@ -35,8 +35,8 @@ import { reportInitOutcome } from '../telemetry/init-telemetry.js';
  * has not restarted their dev server yet is not held hostage by a wait that cannot succeed — they
  * have not typed the command that would make it succeed, and the message tells them which one.
  */
-export const CONFIRM_WINDOW_MS = 12_000;
-export const CONFIRM_POLL_MS = 500;
+const CONFIRM_WINDOW_MS = 12_000;
+const CONFIRM_POLL_MS = 500;
 /**
  * Poll until an app connects or the window runs out.
  *
@@ -110,7 +110,7 @@ export function confirmationMessage(confirmation, port) {
  * 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) {
+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 ' +

package/dist/init/cra.d.ts

@@ -17,6 +17,19 @@ export declare const CRA_DEV_MODULE_IMPORT = "import './reticle-dev';";
 export declare const CRA_DEV_MODULE_PATH = "src/reticle-dev.ts";
 export declare const CRA_ENV_PATH = ".env.development.local";
 export declare const TOKEN_VAR = "REACT_APP_RETICLE_TOKEN";
+/**
+ * The bridge URL, carried through the same channel as the token.
+ *
+ * CRA is the one supported stack with no build-time hook of ours: no plugin, no config wrapper, no
+ * `define`. Vite and Astro re-resolve the daemon every dev-server start and Next does it through
+ * `withReticle`; CRA has nowhere to run that code. So the URL goes where the token already goes, and
+ * is refreshed by the same `init` step that refreshes the token.
+ *
+ * That makes `reticle init` the heal rather than the dev server, which is weaker and is stated
+ * plainly in the step's own detail. It is still strictly better than a URL frozen into a source file
+ * the owner has to hand-edit, and `.env.development.local` is already the per-machine file.
+ */
+export declare const URL_VAR = "REACT_APP_RETICLE_URL";
 /**
  * What the app itself says when the token is not there.
  *
@@ -45,6 +58,6 @@ export declare const CRA_TOKEN_PER_MACHINE_NOTICE: string;
 /** Add the import after the last existing one, or null when it is already present. */
 export declare function craImportPatch(source: string): string | null;
 /** Set the token variable, or null when nothing needs to change. */
-export declare function craEnvPatch(existing: string | null, token: string): string | null;
+export declare function craEnvPatch(existing: string | null, token: string, url?: string): string | null;
 /** The dev-only connect module imported from `src/index.tsx`. */
 export declare function craDevModuleFile(port: number | undefined, projectId?: string): string;