@reticlehq/server 3.4.0 → 3.5.0

package/dist/command/cli/auth/cloud-session.d.ts

@@ -21,17 +21,17 @@ declare const SessionSchema: z.ZodObject<{
     /** Who signed in. Absent in sessions written before it was recorded. */
     email: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
-    url: string;
     token: string;
+    url: string;
     orgName: string;
-    email?: string | undefined;
     orgId?: string | undefined;
+    email?: string | undefined;
 }, {
-    url: string;
     token: string;
+    url: string;
     orgName: string;
-    email?: string | undefined;
     orgId?: string | undefined;
+    email?: string | undefined;
 }>;
 export type Session = z.infer<typeof SessionSchema>;
 /** Trailing slashes are not identity: `https://x/` and `https://x` are one host. */

package/dist/command/cli/auth/device-flow.d.ts

@@ -53,18 +53,18 @@ export declare const DevicePollSchema: z.ZodObject<{
     }>>;
 }, "strip", z.ZodTypeAny, {
     status: string;
+    token?: string | undefined;
     org?: {
         name: string;
         id?: string | undefined;
     } | undefined;
-    token?: string | undefined;
 }, {
     status: string;
+    token?: string | undefined;
     org?: {
         name: string;
         id?: string | undefined;
     } | undefined;
-    token?: string | undefined;
 }>;
 /**
  * Best-effort open the approval page in the default browser.

package/dist/command/cli/cli-parse.d.ts

@@ -15,7 +15,7 @@ export { AGENT_FLAG, BUG_FLAG, FEEDBACK_KINDS, KIND_FLAG, RATING_FLAG, } from '.
  * telling readers to do exactly that on 110 lines before it was caught, so the invocation now leads
  * the usage block rather than being a footnote somewhere else.
  */
-export declare const CLI_USAGE = "usage:  npx @reticlehq/server <command>   (or `reticle <command>` once the bin is on your PATH)\n\n  reticle init  [--dry-run] [--port N] [--no-mcp] [--no-install] [--app <dir>]\n                [--env KEY=VALUE]... [--files-only] [--hooks]  (wire Reticle into the project in this directory)\n                init is ONBOARDING: it wires the project, boots the app and proves a session\n                connected. It does not drive. The FIRST RUN is the stage that proves a flow:\n                reticle verify <url> --explore --persona \"<who does what>\", or the same thing\n                from an agent as reticle_verify { action: \"explore\", persona: \"\u2026\" }\n                --app picks WHICH app in a monorepo, when several are found\n                --env is what the app needs to reach a usable state: the key from\n                .env.example, the mock backend, the variable that skips an auth wall.\n                Repeatable, and a value may contain spaces and equals signs\n                --files-only writes the files and stops, which is what init did before it\n                learned to boot the app and prove the install works\n                --relaunch prints the exact command that restarts THIS conversation with\n                the tools loaded, so the restart is not a chore handed to a human. It\n                refuses when the session id has no transcript behind it, because\n                --resume on an empty id opens a blank conversation that looks like\n                success. Works with --files-only\n                --license writes the key to .env and keeps .env out of git\n                --json puts the result on stdout, so an agent reads one object\n                --no-open / --no-agents / --url / --timeout are the runtime dials: CI, a\n                headless box, or an app you already run\n                --no-mcp skips MORE than the server registration: also the agent rule files\n                (CLAUDE.md / AGENTS.md / .cursor) and the /reticle command, because all three\n                only make sense once the tools are reachable.\n  reticle serve [--port N] [--drive <url>] [--headless] [--http] [--http-port N] [--http-token T]\n  reticle stop  [--port N] [--quiet]                    (stop the daemon we started, by its recorded pid)\n  reticle kill  [--port N] [--force]                   (free the port by its LISTENER, never the agent's mcp proxy)\n  reticle restart [--port N] [--force]                 (kill, then start a daemon and wait for a real bind)\n  reticle status [--port N] [--json]                   (a readable block; --json for the event)\n  reticle doctor [--port N]                            (one command to diagnose setup: Chromium, daemon, port)\n  reticle open  [url] [--port N]                        (show the app: reuse the connected tab, else open one)\n  reticle verify <url> [--port N] [--headed] [--timeout N] [--storage-state <file>] [--session-id <id>]  (one-shot: drive the URL, verify saved flows, exit 0=pass)\n                       [--explore] [--persona <who>]   (no saved flows? let Reticle drive the app itself and record them)\n                       [--select <label>]              (repeatable: verify only flows carrying these labels \u2014 no model, exit 0=pass)\n                [--expect '<json predicate>' | --expect-file <path>]   (one verdict, no saved\n                flows needed. --expect-file is the form no shell can mangle: cmd.exe keeps the\n                single quotes the docs show, and PowerShell strips the inner double quotes, and\n                a predicate that does not parse produces no verdict at all \u2014 asks the daemon that\n                is already running, so nothing is bound and nothing is stopped. It NEEDS that\n                daemon: with none on the port it refuses and names the flag, rather than reporting\n                on your saved flows instead. Cannot be combined with --storage-state, which this\n                path has nowhere to load. This is the path when your client never loaded the\n                reticle_* tools. exit 0 ONLY on verified:\"yes\" \u2014 \"unknown\" is not a pass)\n  reticle affected [--since <ref>] [file...]           (which saved flows must re-verify for the changed files)\n  reticle gate [--since <ref>] [--accept-coverage] [file...]  (exit non-zero unless passing artifacts cover the affected flows)\n  reticle report [--session <id>] [--hook]             (what the latest session claimed, and what held)\n  reticle setup mcp                                    (register the MCP server with your agents; the installer's registration half)\n  reticle capsules                                     (list the saved fail-to-pass bug capsules in .reticle/capsules)\n  reticle hunt <dir>                                   (aggregate a directory of crawl reports into one false-green rate)\n  reticle watch [url]                                  (on save, report which saved flows must re-verify)\n  reticle drive <url> [--headless]                     (foreground mode, for debugging)\n  reticle mcp   [--port N] [--drive <url>] [--headless] (MCP stdio proxy; auto-starts daemon if needed)\n  reticle update                                       (install the latest server version and restart)\n  reticle rollback                                     (restore the previous server version and restart)\n  reticle license                                      (show enterprise license status: active | eval | missing)\n  reticle telemetry [status|enable|disable]            (anonymous usage metrics; status shows what's sent + the policy)\n  reticle feedback [--rating 1-5] [--bug] \"message\"    (tell us what worked and what didn't; prints exactly what it sends)\n  reticle feedback --agent --kind <bug|gap|ambiguity|feature_request|improvement|experience> \"message\"\n                                                       (agents: file from anywhere, including a setup that never finished)\n  reticle identify --context company|side_project|open_source|learning [--company N] [--email E] [--forget]\n                                                       (OPT-IN: tell us who you are, e.g. for support or an enterprise trial)\n\nCloud (link this project to Reticle; runs/flows recorded on the dashboard):\n  reticle login [--url <u>] [--email <e>] [--code <c>] [--org <n>]\n                                                       (browser device flow by default; --email mails a code)\n  reticle logout [--url <u>]                           (sign out of ONE host; others stay signed in)\n  reticle link  [--project <name|id>]                  (bind this repo: mints a scoped key, writes .reticle/cloud.json)\n  reticle whoami                                        (who am I signed in as, and is this repo attached?)\n  reticle project <ls|create <name>>                   (list or create cloud projects)\n  reticle config [--runs on|off] [--memory on|off] [--flows on|off] [--verify local|server]\n  reticle push | sync [--watch]                        (one sync cycle: send the difference, collect decisions)\n  reticle runs | regression | share <runId>            (read cloud state; regression exits 3 if any flow broke)\n\n'drive' shows the browser; everything else is hidden (serve/mcp own the pool behind leases, replay\nand the spec runner: batch work). --headed opts any of them in, --headless hides drive, CI hides it.";
+export declare const CLI_USAGE = "usage:  npx @reticlehq/server <command>   (or `reticle <command>` once the bin is on your PATH)\n\n  reticle init  [--dry-run] [--port N] [--no-mcp] [--no-install] [--app <dir>]\n                [--env KEY=VALUE]... [--files-only] [--hooks]  (wire Reticle into the project in this directory)\n                init is ONBOARDING: it wires the project, boots the app and proves a session\n                connected. It does not drive. The FIRST RUN is the stage that proves a flow:\n                reticle verify <url> --explore --persona \"<who does what>\", or the same thing\n                from an agent as reticle_verify { action: \"explore\", persona: \"\u2026\" }\n                --app picks WHICH app in a monorepo, when several are found\n                --env is what the app needs to reach a usable state: the key from\n                .env.example, the mock backend, the variable that skips an auth wall.\n                Repeatable, and a value may contain spaces and equals signs\n                --files-only writes the files and stops, which is what init did before it\n                learned to boot the app and prove the install works\n                --relaunch prints the exact command that restarts THIS conversation with\n                the tools loaded, so the restart is not a chore handed to a human. It\n                refuses when the session id has no transcript behind it, because\n                --resume on an empty id opens a blank conversation that looks like\n                success. Works with --files-only\n                --license writes the key to .env and keeps .env out of git\n                --json puts the result on stdout, so an agent reads one object\n                --no-open / --no-agents / --url / --timeout are the runtime dials: CI, a\n                headless box, or an app you already run\n                --no-mcp skips MORE than the server registration: also the agent rule files\n                (CLAUDE.md / AGENTS.md / .cursor) and the /reticle command, because all three\n                only make sense once the tools are reachable.\n  reticle serve [--port N] [--drive <url>] [--headless] [--http] [--http-port N] [--http-token T]\n  reticle stop  [--port N] [--quiet]                    (stop the daemon we started, by its recorded pid)\n  reticle kill  [--port N] [--force]                   (free the port by its LISTENER, never the agent's mcp proxy)\n  reticle restart [--port N] [--force]                 (kill, then start a daemon and wait for a real bind)\n  reticle status [--port N] [--json]                   (a readable block; --json for the event)\n  reticle doctor [--port N]                            (one command to diagnose setup: Chromium, daemon, port)\n  reticle open  [url] [--port N]                        (show the app: reuse the connected tab, else open one)\n  reticle verify <url> [--port N] [--headed] [--timeout N] [--storage-state <file>] [--session-id <id>]  (one-shot: drive the URL, verify saved flows, exit 0=pass)\n                       [--explore] [--persona <who>]   (no saved flows? let Reticle drive the app itself and record them)\n                       [--select <label>]              (repeatable: verify only flows carrying these labels \u2014 no model, exit 0=pass)\n                [--expect '<json predicate>' | --expect-file <path>]   (one verdict, no saved\n                flows needed. --expect-file is the form no shell can mangle: cmd.exe keeps the\n                single quotes the docs show, and PowerShell strips the inner double quotes, and\n                a predicate that does not parse produces no verdict at all \u2014 asks the daemon that\n                is already running, so nothing is bound and nothing is stopped. It NEEDS that\n                daemon: with none on the port it refuses and names the flag, rather than reporting\n                on your saved flows instead. Cannot be combined with --storage-state, which this\n                path has nowhere to load. This is the path when your client never loaded the\n                reticle_* tools. exit 0 ONLY on verified:\"yes\" \u2014 \"unknown\" is not a pass)\n  reticle affected [--since <ref>] [file...]           (which saved flows must re-verify for the changed files)\n  reticle gate [--since <ref>] [--accept-coverage] [file...]  (exit non-zero unless passing artifacts cover the affected flows)\n  reticle report [--session <id>] [--hook]             (what the latest session claimed, and what held)\n  reticle setup mcp                                    (register the MCP server with your agents; the installer's registration half)\n  reticle capsules                                     (list the saved fail-to-pass bug capsules in .reticle/capsules)\n  reticle hunt <dir>                                   (aggregate a directory of crawl reports into one false-green rate)\n  reticle watch [url]                                  (on save, report which saved flows must re-verify)\n  reticle drive <url> [--headless]                     (foreground mode, for debugging)\n  reticle mcp   [--port N] [--drive <url>] [--headless] (MCP stdio proxy; auto-starts daemon if needed)\n  reticle update                                       (install the latest server version and restart)\n  reticle rollback                                     (restore the previous server version and restart)\n  reticle license                                      (show enterprise license status: active | eval | missing)\n  reticle telemetry [status|enable|disable]            (anonymous usage metrics; status shows what's sent + the policy)\n  reticle feedback [--rating 1-5] [--bug] \"message\"    (tell us what worked and what didn't; prints exactly what it sends)\n  reticle feedback --agent --kind <bug|gap|ambiguity|feature_request|improvement|experience> \"message\"\n                                                       (agents: file from anywhere, including a setup that never finished)\n  reticle identify --context company|side_project|open_source|learning [--company N] [--email E] [--forget]\n                                                       (OPT-IN: tell us who you are, e.g. for support or an enterprise trial)\n\nCloud (link this project to Reticle; runs/flows recorded on the dashboard):\n  reticle connect [--project <name|id>] [--url <cloud origin>]\n                                                       (wire this app if needed, sign in, link, send local history)\n  reticle login [--url <u>] [--email <e>] [--code <c>] [--org <n>]\n                                                       (browser device flow by default; --email mails a code)\n  reticle logout [--url <u>]                           (sign out of ONE host; others stay signed in)\n  reticle link  [--project <name|id>]                  (bind this repo: mints a scoped key, writes .reticle/cloud.json)\n  reticle whoami                                        (who am I signed in as, and is this repo attached?)\n  reticle project <ls|create <name>>                   (list or create cloud projects)\n  reticle config [--runs on|off] [--memory on|off] [--flows on|off] [--verify local|server]\n  reticle push | sync [--watch]                        (one sync cycle: send the difference, collect decisions)\n  reticle runs | regression | share <runId>            (read cloud state; regression exits 3 if any flow broke)\n\n'drive' shows the browser; everything else is hidden (serve/mcp own the pool behind leases, replay\nand the spec runner: batch work). --headed opts any of them in, --headless hides drive, CI hides it.";
 /** The `reticle telemetry` sub-actions. Bare `reticle telemetry` means `status`. */
 export declare const TelemetryAction: {
     readonly STATUS: "status";

package/dist/command/cli/cli-parse.js

@@ -85,6 +85,8 @@ export const CLI_USAGE = `usage:  npx @reticlehq/server <command>   (or \`reticl
                                                        (OPT-IN: tell us who you are, e.g. for support or an enterprise trial)
 
 Cloud (link this project to Reticle; runs/flows recorded on the dashboard):
+  reticle connect [--project <name|id>] [--url <cloud origin>]
+                                                       (wire this app if needed, sign in, link, send local history)
   reticle login [--url <u>] [--email <e>] [--code <c>] [--org <n>]
                                                        (browser device flow by default; --email mails a code)
   reticle logout [--url <u>]                           (sign out of ONE host; others stay signed in)
@@ -170,7 +172,7 @@ const KNOWN_COMMANDS = new Set([
     FEEDBACK_COMMAND,
     IDENTIFY_COMMAND,
     DAEMON_INNER_COMMAND,
-    // Cloud subcommands dispatch before the local parser but are still commands a human ran.
+    'connect',
     'login',
     'logout',
     'whoami',

package/dist/command/cli/cloud-cli.js

@@ -42,6 +42,7 @@ import { diskSink, diskSource, readCloudIssues, readCloudState } from '../../mem
  */
 const CLOUD_COMMANDS = new Set([
     'login',
+    'connect',
     'logout',
     'whoami',
     'link',
@@ -438,6 +439,62 @@ const cmdLink = async (argv) => {
     }
     return 0;
 };
+/**
+ * `reticle connect` finishes the cloud half of first-run setup in one invocation. The CLI entry
+ * initializes an unwired app before calling this verb. A saved login is checked against this exact
+ * host before reuse; an expired one opens the normal browser approval flow. Login does not auto-link
+ * here because this command links once, to the project the caller named, then sends local history.
+ */
+const cmdConnect = async (argv) => {
+    for (let i = 0; i < argv.length; i += 2) {
+        const flag = argv[i];
+        const value = argv[i + 1];
+        if ((flag !== '--project' && flag !== '--url') ||
+            value === undefined ||
+            0 === value.length ||
+            value.startsWith('--')) {
+            err('usage: reticle connect [--project <name|id>] [--url <cloud origin>]');
+            return 2;
+        }
+    }
+    if (!(await createNodeFileSystem().exists(join(process.cwd(), RETICLE_CONFIG_BASENAME)))) {
+        err('this app is not wired yet — run `reticle init` in its directory, then `reticle connect`');
+        return 2;
+    }
+    const f = flags(argv);
+    const url = baseUrl(null, f['url']);
+    if (undefined === apiKeyFrom(process.env)) {
+        const session = await readSessionFor(url);
+        let signedIn = false;
+        if (session !== null) {
+            try {
+                await api('GET', `${url}/v1/me`, session.token);
+                signedIn = true;
+            }
+            catch {
+                hint('saved sign-in needs renewal — opening browser approval');
+            }
+        }
+        if (!signedIn) {
+            const code = await cmdLogin(['--url', url], cmdLink, false);
+            if (code !== 0)
+                return code;
+        }
+    }
+    const linkArgs = [
+        '--url',
+        url,
+        ...(f['project'] === undefined ? [] : ['--project', f['project']]),
+    ];
+    const linked = await cmdLink(linkArgs);
+    if (linked !== 0)
+        return linked;
+    const pushed = await cmdPush();
+    if (pushed !== 0)
+        return pushed;
+    hint('Connected. Open your coding agent and ask it to verify one flow in your app.');
+    return 0;
+};
 /** `reticle config [--runs on|off] [--memory on|off] [--flows on|off] [--verify local|server]`. */
 const cmdConfig = async (argv) => {
     const f = flags(argv);
@@ -661,6 +718,8 @@ export const runCloudCommand = async (argv) => {
                 // The linker is passed in rather than imported by cloud-login: login ends by linking and
                 // link needs a session, so the cycle is broken at this one call site.
                 return await cmdLogin(rest, cmdLink);
+            case 'connect':
+                return await cmdConnect(rest);
             case 'logout':
                 return await cmdLogout(rest);
             case 'whoami':

package/dist/command/cli/cloud-login.d.ts

@@ -4,7 +4,7 @@ type Linker = (argv: readonly string[]) => Promise<number>;
  * `reticle login` — browser device flow by default; `--email <e>` (or a positional email) keeps the
  * headless two-step code path for CI/servers where opening a browser makes no sense.
  */
-export declare const cmdLogin: (argv: readonly string[], link: Linker) => Promise<number>;
+export declare const cmdLogin: (argv: readonly string[], link: Linker, autoLink?: boolean) => Promise<number>;
 /** `reticle logout` — forget the cached session token (per-project keys under credentials.json stay). */
 /**
  * `reticle logout` — sign out of ONE host, not of everywhere.

package/dist/command/cli/cloud-login.js

@@ -48,7 +48,7 @@ const signedInEmail = async (url, token) => {
     }
 };
 /** Persist a session token under ~/.reticle and print the next step. Shared by both login paths. */
-const writeSession = async (url, token, orgName, orgId, project, link, email) => {
+const writeSession = async (url, token, orgName, orgId, project, link, email, autoLink = true) => {
     await mkdir(join(home(), SESSIONS_DIR), { recursive: true });
     // Who signed in, so a flow saved on this machine can say which person made it (FlowFile.author).
     const who = email ?? (await signedInEmail(url, token));
@@ -65,7 +65,8 @@ const writeSession = async (url, token, orgName, orgId, project, link, email) =>
     await writeFile(sessionPath(home(), url), body);
     await writeFile(join(home(), SESSION_FILE), body);
     emit({ loggedIn: orgName, session: join(home(), SESSION_FILE) });
-    await linkAfterLogin(url, project, link);
+    if (autoLink)
+        await linkAfterLogin(url, project, link);
 };
 /**
  * Finish the job when the shell is already standing in an unlinked Reticle project.
@@ -124,7 +125,7 @@ const linkAfterLogin = async (url, project, link) => {
  * Browser device flow — the DEFAULT `reticle login` (like `gh auth login`): fetch a device + user code,
  * open the browser to approve, then poll until the user confirms. No email to type, no code to copy back.
  */
-const cmdLoginDevice = async (explicitUrl, project, link) => {
+const cmdLoginDevice = async (explicitUrl, project, link, autoLink) => {
     const url = baseUrl(null, explicitUrl);
     const started = DeviceStartSchema.parse(await api('POST', `${url}/v1/auth/device/start`, null, {}));
     hint(`Opening ${started.verificationUri} — confirm this code in the browser: ${started.userCode}`);
@@ -134,7 +135,7 @@ const cmdLoginDevice = async (explicitUrl, project, link) => {
         await sleep(intervalMs);
         const poll = DevicePollSchema.parse(await api('POST', `${url}/v1/auth/device/token`, null, { deviceCode: started.deviceCode }));
         if ('approved' === poll.status && poll.token !== undefined && poll.org !== undefined) {
-            await writeSession(url, poll.token, poll.org.name, poll.org.id, project, link);
+            await writeSession(url, poll.token, poll.org.name, poll.org.id, project, link, undefined, autoLink);
             return 0;
         }
         if ('pending' === poll.status) {
@@ -154,12 +155,12 @@ const cmdLoginDevice = async (explicitUrl, project, link) => {
  * `reticle login` — browser device flow by default; `--email <e>` (or a positional email) keeps the
  * headless two-step code path for CI/servers where opening a browser makes no sense.
  */
-export const cmdLogin = async (argv, link) => {
+export const cmdLogin = async (argv, link, autoLink = true) => {
     const f = flags(argv);
     const positional = argv[0] !== undefined && !argv[0].startsWith('--') ? argv[0] : undefined;
     const email = f['email'] ?? positional;
     if (email === undefined)
-        return cmdLoginDevice(f['url'], f['project'], link);
+        return cmdLoginDevice(f['url'], f['project'], link, autoLink);
     const org = f['org'];
     const url = baseUrl(null, f['url']);
     let code = f['code'];
@@ -177,7 +178,7 @@ export const cmdLogin = async (argv, link) => {
         code = requested.devCode;
     }
     const parsed = LoginSchema.parse(await api('POST', `${url}/v1/auth/login`, null, { email, code }));
-    await writeSession(url, parsed.token, parsed.org.name, parsed.org.id, f['project'], link, email);
+    await writeSession(url, parsed.token, parsed.org.name, parsed.org.id, f['project'], link, email, autoLink);
     return 0;
 };
 /** `reticle logout` — forget the cached session token (per-project keys under credentials.json stay). */

package/dist/command/cli/setup-mcp-cli.js

@@ -1,7 +1,7 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname } from 'node:path';
 import { homedir } from 'node:os';
-import { probeCli, terminalWidth, wrapForTerminal } from '@reticlehq/init';
+import { claudeAddCommand, McpClient, probeCli, terminalWidth, wrapForTerminal, } from '@reticlehq/init';
 import { installClosing, tutorialShownSteps } from './tutorial.js';
 import { setupMcp, knownClientLabels } from '../setup/setup-mcp.js';
 import { reportInstallSteps } from '../setup/setup-install.js';
@@ -49,6 +49,14 @@ export function handleSetupMcp(reportStep, standalone = true) {
         io.print(`  ✓ ${id}`);
     for (const id of result.alreadyThere)
         io.print(`  ✓ ${id} (already set up)`);
+    for (const id of result.failed) {
+        io.print(`  ⚠ ${id}: Reticle registration failed; this agent may not have the tools.`);
+        io.print(id === McpClient.CLAUDE_CODE
+            ? `    Run this command to see the error and retry: ${claudeAddCommand().display}`
+            : '    Check your agent config file permissions, then retry: reticle setup mcp');
+    }
+    if (result.failed.length > 0)
+        process.exitCode = 1;
     // Said, not skipped. These are the clients whose format we will not rewrite, and they used to be
     // counted as registered: the line below is the difference between a user who adds four lines to
     // one file and a user who believes they are set up and has no tools.

package/dist/command/cli.js

@@ -79,7 +79,7 @@ async function handleInit(parsed) {
         daemonPresent: async (p) => presenceIsUsable(await probePresence(p, { tcpOpen: probeDaemon, status: fetchStatus })),
         pickPort: (p) => pickDaemonPortToBind(p),
     });
-    const io = buildNodeIo(cwd, serverInitHost());
+    const io = buildNodeIo(cwd, serverInitHost(), { stderr: true === parsed.json });
     const result = runInit({
         cwd,
         port,
@@ -587,6 +587,22 @@ export function main() {
             process.stdout.write(`${CLI_USAGE}\n`);
             return;
         }
+        if ('connect' === argv[0]) {
+            void (async () => {
+                // A fresh project gets the same install, dev-server handover and browser proof as `init`.
+                // Its failure exits non-zero before any cloud binding can claim this repo is ready.
+                if (readProjectId(process.cwd()) === undefined) {
+                    await handleInit({ port: undefined, mcp: true, dryRun: false, install: true });
+                }
+                return runCloudCommand(argv);
+            })()
+                .then((code) => process.exit(code))
+                .catch((cause) => {
+                process.stderr.write(`reticle connect: ${cause instanceof Error ? cause.message : String(cause)}\n`);
+                process.exit(1);
+            });
+            return;
+        }
         void runCloudCommand(argv).then((code) => process.exit(code));
         return;
     }

package/dist/command/setup/bringup/dev-server-wait.d.ts

@@ -25,6 +25,8 @@ export interface WaitFacts {
     readonly quietForMs: number;
     /** Milliseconds since the wait began. */
     readonly elapsedMs: number;
+    /** Explicit caller limit; otherwise a busy build keeps the default ceiling. */
+    readonly budgetMs?: number | undefined;
     /**
      * How long silence may mean "still starting" on THIS machine. Defaults to QUIET_MEANS_HUNG_MS.
      *

package/dist/command/setup/bringup/dev-server-wait.js

@@ -38,7 +38,7 @@ export function judgeWait(facts) {
         return WaitVerdict.READY;
     if (facts.launcherExited)
         return WaitVerdict.DEAD;
-    if (facts.elapsedMs >= WAIT_CEILING_MS)
+    if (facts.elapsedMs >= (facts.budgetMs ?? WAIT_CEILING_MS))
         return WaitVerdict.HUNG;
     // Output IS progress. Silence is what distinguishes a build from a wedge.
     return facts.quietForMs >= (facts.quietMeansHungMs ?? QUIET_MEANS_HUNG_MS)

package/dist/command/setup/init/init-runtime.js

@@ -6,8 +6,8 @@
  * every command harder to read.
  */
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
-import { RETICLE_DEFAULT_PORT } from '@reticlehq/core';
-import { FEEDBACK_HINT, Framework } from '@reticlehq/init';
+import { InitConfirmation, RETICLE_DEFAULT_PORT } from '@reticlehq/core';
+import { FEEDBACK_HINT, Framework, InitFailure } from '@reticlehq/init';
 import { confirmInstall, nodeConfirmDeps } from '../terminal/confirm.js';
 import { writeLicenseKey } from '../license-key.js';
 import { registerOtherAgents, runSetupCommand } from '../setup-command.js';
@@ -20,6 +20,8 @@ import { probeDaemon } from '../../../surface/mcp/proxy/proxy-daemon-probe.js';
 import { fetchStatus } from '../../daemon/binding/daemon-status-probe.js';
 import { collectEnv, DEFAULT_PHASE_TIMEOUT_MS } from '../setup-options.js';
 import { staticPageDevCommand } from '../bringup/static-page-server.js';
+import { SetupPhase } from '../run-setup.js';
+import { reportInitOutcome } from '../../../telemetry/init-telemetry.js';
 /** How often the runtime phases look again: fast enough not to be the wait, slow enough to be free. */
 const POLL_MS = 250;
 /**
@@ -59,9 +61,9 @@ function printRelaunch(parsed, io, cwd) {
 }
 export async function continueAfterInit(parsed, result, io, cwd) {
     const port = parsed.port ?? RETICLE_DEFAULT_PORT;
-    // Before anything else: the key belongs in .env whichever way this run ends, and the CLI folds a
-    // project-local .env into the environment on every invocation.
-    if (undefined !== parsed.licenseKey) {
+    // Real installs persist the key whichever way setup ends. A preview must leave .env and
+    // .gitignore untouched, just as it leaves project wiring and agent configuration untouched.
+    if (!parsed.dryRun && undefined !== parsed.licenseKey) {
         const written = writeLicenseKey(cwd, parsed.licenseKey, licenseIo);
         io.print(written.message);
     }
@@ -79,9 +81,12 @@ export async function continueAfterInit(parsed, result, io, cwd) {
         // has: nothing reaches back into a machine that installed Reticle a version ago, so the
         // upgrade path is re-running init, and the light form of init has to be enough to carry it.
         // A dry run writes nothing anywhere, including here.
-        if (true === parsed.filesOnly && wantsAgents(parsed))
+        if (!parsed.dryRun && true === parsed.filesOnly && wantsAgents(parsed)) {
             registerOtherAgents(io.print);
+        }
         return confirmInstall(result, io, nodeConfirmDeps(port)).then(() => {
+            if (true === parsed.json)
+                process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
             if (!result.ok)
                 process.exit(1);
         });
@@ -96,8 +101,15 @@ export async function continueAfterInit(parsed, result, io, cwd) {
     if (context === undefined) {
         // Nothing was established, so there is nothing to run against. init has already said why.
         ask();
+        if (true === parsed.json)
+            process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
         process.exit(1);
     }
+    const reportFailure = (reason) => {
+        if (result.outcome !== undefined) {
+            reportInitOutcome({ ...result.outcome, ok: false, reason });
+        }
+    };
     // A PENDING connect step is not a reason to skip the runtime phase, and treating it as one made
     // `init` stop with "paste this snippet" while never looking at the app.
     //
@@ -113,10 +125,17 @@ export async function continueAfterInit(parsed, result, io, cwd) {
     // Before the connect wait, never after: a bridge held by a stranger makes a session impossible,
     // so going ahead spends the entire budget and then reports what reads as an instrumentation
     // problem — the one place that is fine. See bridge-port.ts.
-    const refusal = bridgeOccupied(await probePresence(port, { tcpOpen: probeDaemon, status: fetchStatus }), port);
+    const refusal = bridgeOccupied(await probePresence(port, { tcpOpen: probeDaemon, status: fetchStatus }).catch((error) => {
+        reportFailure(InitFailure.RUNTIME_ERROR);
+        throw error;
+    }), port);
     if (refusal !== undefined) {
+        reportFailure(InitFailure.BRIDGE_OCCUPIED);
         io.print(refusal);
         ask();
+        if (true === parsed.json) {
+            process.stdout.write(`${JSON.stringify({ ok: false, reason: InitFailure.BRIDGE_OCCUPIED }, null, 2)}\n`);
+        }
         process.exit(1);
     }
     return runSetupCommand({
@@ -136,7 +155,10 @@ export async function continueAfterInit(parsed, result, io, cwd) {
         // keeps deciding, so nobody who passed nothing waits less than they used to.
         ...(undefined === parsed.timeoutSeconds
             ? {}
-            : { connectBudgetMs: parsed.timeoutSeconds * 1000 }),
+            : {
+                connectBudgetMs: parsed.timeoutSeconds * 1000,
+                startupBudgetMs: parsed.timeoutSeconds * 1000,
+            }),
         pollMs: POLL_MS,
         htmlCarriesSdk: HTML_CARRIES_SDK.has(context.framework),
         // A plain page with no dev script gets Reticle's own static server, so the page is actually
@@ -153,6 +175,26 @@ export async function continueAfterInit(parsed, result, io, cwd) {
         })(),
         ...(undefined === parsed.url ? {} : { suppliedUrl: parsed.url }),
     }, (line) => io.print(line)).then((outcome) => {
+        if (result.outcome !== undefined) {
+            const init = {
+                ...result.outcome,
+                ok: outcome.ok,
+            };
+            if (outcome.ok) {
+                delete init.reason;
+                init.confirmation = InitConfirmation.CONNECTED;
+            }
+            else {
+                // A failed startup does not establish whether a daemon or instrumented page exists.
+                // Keep the watcher's no_daemon/no_session/no_page classifications for observed facts.
+                delete init.confirmation;
+                init.reason =
+                    outcome.reachedPhase === SetupPhase.DEV_SERVER
+                        ? InitFailure.DEV_SERVER
+                        : InitFailure.APP_CONNECTION;
+            }
+            reportInitOutcome(init);
+        }
         // One object, so an agent reads a result instead of interpreting a report.
         if (true === parsed.json) {
             process.stdout.write(`${JSON.stringify(outcome, null, 2)}\n`);
@@ -201,5 +243,8 @@ export async function continueAfterInit(parsed, result, io, cwd) {
             io.print(`   ${i + 1}. ${step}`);
         ask();
         process.exit(1);
+    }, (error) => {
+        reportFailure(InitFailure.RUNTIME_ERROR);
+        throw error;
     });
 }

package/dist/command/setup/node-effects.js

@@ -23,6 +23,8 @@ import { reticleStateHome } from '../daemon/daemon.js';
 import { descendants, parseLsofPorts, parseNetstatListeners, parseWmicProcesses, } from './terminal/listeners.js';
 import { isAddressMiss, loopbackProbeUrls } from './probe/loopback-probe-urls.js';
 const WINDOWS = 'win32' === process.platform;
+/** Astro otherwise daemonizes automatically when it detects an agent terminal. */
+const ASTRO_DEV_BACKGROUND_ENV = 'ASTRO_DEV_BACKGROUND';
 /** A page fetch that is slow is a page fetch that failed, for our purposes. */
 const PROBE_TIMEOUT_MS = 5_000;
 /** The supervisor that owns the server's output and keeps its log bounded. */
@@ -64,7 +66,10 @@ export class OwnedDevServer {
             detached: !WINDOWS,
             // Nothing of ours: the supervisor holds the server's pipes, and init holds none of its.
             stdio: 'ignore',
-            env: { ...process.env, ...env },
+            // Reticle already provides the detached supervisor. Astro's agent auto-backgrounding
+            // would escape its process group and leave the recorded handover PID pointing at a dead
+            // launcher, so re-init and cleanup could no longer find or stop the actual server.
+            env: { ...process.env, ...env, [ASTRO_DEV_BACKGROUND_ENV]: '1' },
         });
         this.log = log;
         this.cwd = cwd;

package/dist/command/setup/run-setup.d.ts

@@ -132,6 +132,8 @@ export interface SetupInput {
      * before setup could say what was wrong.
      */
     readonly connectBudgetMs?: number | undefined;
+    /** Explicit --timeout for startup; absent preserves the adaptive build wait. */
+    readonly startupBudgetMs?: number | undefined;
     readonly openBrowser: boolean;
     /** Web, Electron or Tauri. Desktop changes three things; see desktop-shape.ts. */
     readonly shape: AppShape;

package/dist/command/setup/run-setup.js

@@ -159,6 +159,7 @@ export async function runSetupPhases(input, fx) {
                     serving,
                     quietForMs: fx.devServerQuietForMs(),
                     elapsedMs: fx.now() - startedAt,
+                    budgetMs: input.startupBudgetMs,
                     quietMeansHungMs: WINDOWS_QUIET_MEANS_HUNG_MS_APPLIES
                         ? WINDOWS_QUIET_MEANS_HUNG_MS
                         : QUIET_MEANS_HUNG_MS,
@@ -184,8 +185,12 @@ export async function runSetupPhases(input, fx) {
                     // Says BOTH were checked. A server that prints nothing but IS listening is the CRA case and
                     // must not be failed, so a reader has to be able to tell "we looked at the log" from "we
                     // looked at the log AND the ports".
-                    note('The dev server neither printed a URL nor bound a port, so setup has nothing to open. ' +
-                        'Check its log, or pass --url with the address it serves.');
+                    note((input.startupBudgetMs !== undefined && fx.now() - startedAt >= input.startupBudgetMs
+                        ? `The dev server did not become ready within ${String(input.startupBudgetMs)}ms. `
+                        : undefined === watching
+                            ? 'The dev server neither printed a URL nor bound a port, so setup has nothing to open. '
+                            : `The dev server stopped making progress before ${watching} became ready. `) +
+                        'Check its log, increase --timeout for a slow build, or pass --url with the address it serves.');
                     return stop(input, SetupPhase.DEV_SERVER, {}, notes);
                 }
                 await fx.sleep(input.pollMs);

package/dist/command/setup/setup-mcp.d.ts

@@ -32,6 +32,8 @@ export interface SetupMcpResult {
     readonly detected: readonly string[];
     readonly registered: readonly string[];
     readonly alreadyThere: readonly string[];
+    /** Automatic registration was attempted but failed. */
+    readonly failed: readonly string[];
     /**
      * Clients whose config this will NOT rewrite, and which therefore still need a human.
      *

package/dist/command/setup/setup-mcp.js

@@ -4,6 +4,7 @@ export function setupMcp(io) {
     const detected = [];
     const registered = [];
     const alreadyThere = [];
+    const failed = [];
     const manual = [];
     /*
      * Claude Code first, because nothing else can find it.
@@ -30,6 +31,8 @@ export function setupMcp(io) {
             const cmd = claudeAddCommand();
             if (io.runCli(cmd.command, cmd.args))
                 registered.push(McpClient.CLAUDE_CODE);
+            else
+                failed.push(McpClient.CLAUDE_CODE);
         }
     }
     for (const client of detectMcpClients(io)) {
@@ -47,8 +50,13 @@ export function setupMcp(io) {
             manual.push({ id: client.id, configPath: client.configPath, docs: spec.docs });
             continue;
         }
-        io.writeFile(client.configPath, merged.content);
-        registered.push(client.id);
+        try {
+            io.writeFile(client.configPath, merged.content);
+            registered.push(client.id);
+        }
+        catch {
+            failed.push(client.id);
+        }
     }
     /*
      * Both INSTALL steps, reported from the one place that knows the answer.
@@ -69,7 +77,8 @@ export function setupMcp(io) {
          * SKIPPED when there was nothing to register with — not failed. Nothing went wrong; there was
          * simply no agent here, and counting that as our failure would hide the ones that are.
          *
-         * FAILED when every client we found needs a hand. That case used to fall through to COMPLETED,
+         * FAILED when no detected client is usable, whether registration failed or needs a hand.
+         * That case used to fall through to COMPLETED,
          * so the cohort with the tools registered NOWHERE was counted among the successful installs, and
          * the one number that says "did this machine get Reticle" read yes for the people it read no
          * for. Registering some and not others is still COMPLETED: the agent they are using may well be
@@ -79,11 +88,11 @@ export function setupMcp(io) {
             ? OnboardingStepStatus.SKIPPED
             : 0 === registered.length && alreadyThere.length > 0
                 ? OnboardingStepStatus.SKIPPED
-                : 0 === registered.length && 0 === alreadyThere.length && manual.length > 0
+                : 0 === registered.length && 0 === alreadyThere.length
                     ? OnboardingStepStatus.FAILED
                     : OnboardingStepStatus.COMPLETED,
     });
-    return { detected, registered, alreadyThere, manual };
+    return { detected, registered, alreadyThere, failed, manual };
 }
 /** Everything this machine could be asked about, for the report when nothing was found. */
 export function knownClientLabels() {

package/dist/command/version/peer-announce.d.ts

@@ -1,4 +1,8 @@
 export declare const PEER_VERSION_PARAM = "peerVersion";
 export declare const PEER_CONTRACT_PARAM = "peerContract";
-/** Compare an attaching agent process against this daemon, and queue the nudge when they disagree. */
-export declare function noteAgentPeer(version: string | null, contract: string | null): void;
+/**
+ * Compare an attaching agent process against this daemon: the skew to tell THAT connection, or
+ * undefined when they agree. Returned rather than queued daemon-wide, because it is true only for the
+ * agent that announced it (#1136).
+ */
+export declare function agentPeerSkew(version: string | null, contract: string | null): string | undefined;

package/dist/command/version/peer-announce.js

@@ -13,12 +13,15 @@
  */
 import { CONTRACT_FINGERPRINT } from '@reticlehq/core';
 import { SERVER_VERSION } from './identity/server-version.js';
-import { daemonFix, describeSkew, SkewPair } from './version-skew.js';
-import { noteVersionSkew } from './version-nudge.js';
+import { daemonFix, describeSkew } from './version-skew.js';
 export const PEER_VERSION_PARAM = 'peerVersion';
 export const PEER_CONTRACT_PARAM = 'peerContract';
-/** Compare an attaching agent process against this daemon, and queue the nudge when they disagree. */
-export function noteAgentPeer(version, contract) {
+/**
+ * Compare an attaching agent process against this daemon: the skew to tell THAT connection, or
+ * undefined when they agree. Returned rather than queued daemon-wide, because it is true only for the
+ * agent that announced it (#1136).
+ */
+export function agentPeerSkew(version, contract) {
     const skew = describeSkew({
         what: "the agent's MCP server",
         version: version ?? undefined,
@@ -27,6 +30,5 @@ export function noteAgentPeer(version, contract) {
         // MCP server, so the daemon is the newer half whenever the announcing agent is behind.
         fix: daemonFix(SERVER_VERSION, version ?? undefined),
     }, { version: SERVER_VERSION, contract: CONTRACT_FINGERPRINT });
-    if (skew !== undefined)
-        noteVersionSkew(SkewPair.DAEMON, skew);
+    return skew;
 }