@reticlehq/server 3.5.0 → 3.7.0

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

@@ -63,7 +63,13 @@ export class OwnedDevServer {
         this.child = spawn(process.execPath, [LOG_CAP_SCRIPT, log, String(DEV_SERVER_LOG_CAP_BYTES), command], {
             cwd,
             // Its own process group, so stopping it stops what it started rather than only the wrapper.
-            detached: !WINDOWS,
+            // Detached on Windows too: there libuv puts every non-detached child in a job object that
+            // kills it when this process exits. The supervisor died with `init`, the server it fed lost
+            // its pipe reader, and its next log line was an EPIPE: every Windows install cell whose
+            // server logs per request (Next, Astro) or on an edit (CRA, Angular) failed that way.
+            detached: true,
+            // Detached on Windows means no console; this keeps one from opening as a visible window.
+            windowsHide: true,
             // Nothing of ours: the supervisor holds the server's pipes, and init holds none of its.
             stdio: 'ignore',
             // Reticle already provides the detached supervisor. Astro's agent auto-backgrounding
@@ -106,7 +112,8 @@ export class OwnedDevServer {
         catch {
             /* not written yet */
         }
-        return Date.now() - lastOutputAt;
+        // Filesystem timestamps can include a fractional millisecond beyond Date.now()'s integer.
+        return Math.max(0, Date.now() - lastOutputAt);
     }
     /** Ports anything in this server's process tree is listening on. */
     listeningPorts() {
@@ -168,8 +175,21 @@ export class OwnedDevServer {
         this.child = undefined;
     }
 }
-function run(file, args) {
-    const r = spawnSync(file, args, { encoding: 'utf8', maxBuffer: 8 * 1024 * 1024 });
+/**
+ * How long one process-listing command may take. `init` calls these on every dev-server poll, and
+ * spawnSync blocks the event loop: with no bound, one stalled WMI query on a Windows install cell
+ * froze `init` silently for nine and a half minutes, until the gate killed it.
+ */
+const RUN_TIMEOUT_MS = 15_000;
+/** Run a command and return what it printed, or '' if it failed to finish within `timeoutMs`. */
+export function run(file, args, timeoutMs = RUN_TIMEOUT_MS) {
+    const r = spawnSync(file, args, {
+        encoding: 'utf8',
+        maxBuffer: 8 * 1024 * 1024,
+        timeout: timeoutMs,
+    });
+    if (undefined !== r.error)
+        return '';
     return r.stdout ?? '';
 }
 /**
@@ -182,13 +202,22 @@ function run(file, args) {
  * `init` then waits out the full quiet window and reports "the dev server stopped producing output
  * without ever serving a page" about a Vite server that was serving perfectly the whole time.
  *
- * The fallback prints the same two-integers-per-line shape, so `parseWmicProcesses` reads either
- * without knowing which produced it. Tried in this order because `wmic` is an order of magnitude
- * faster to start than PowerShell, and on a machine that still has it nothing needs to change.
+ * The fallback prints the same `CreationDate ParentProcessId ProcessId` shape (UTC, in WMI's
+ * datetime format), so `parseWmicProcesses` reads either without knowing which produced it. The
+ * creation time is not decoration: Windows keeps a dead parent's pid as ParentProcessId and reuses
+ * pids, and without it the tree walk adopted the runner's sshd and reported port 22 as the dev
+ * server. A process with no creation time (System) prints the old two-column row.
+ *
+ * Tried in this order because `wmic` is an order of magnitude faster to start than PowerShell, and
+ * on a machine that still has it nothing needs to change.
  */
-const POWERSHELL_PAIRS = 'Get-CimInstance Win32_Process | ForEach-Object { "$($_.ParentProcessId) $($_.ProcessId)" }';
+const POWERSHELL_PAIRS = 'Get-CimInstance Win32_Process | ForEach-Object { ' +
+    '$c = $_.CreationDate; ' +
+    "$t = if ($c) { $c.ToUniversalTime().ToString('yyyyMMddHHmmss.ffffff', " +
+    "[Globalization.CultureInfo]::InvariantCulture) + '+000' } else { '' }; " +
+    '"$t $($_.ParentProcessId) $($_.ProcessId)".Trim() }';
 function windowsProcessPairs() {
-    const fromWmic = parseWmicProcesses(run('wmic', ['process', 'get', 'ParentProcessId,ProcessId']));
+    const fromWmic = parseWmicProcesses(run('wmic', ['process', 'get', 'CreationDate,ParentProcessId,ProcessId']));
     if (0 < fromWmic.length)
         return fromWmic;
     return parseWmicProcesses(run('powershell', ['-NoProfile', '-NonInteractive', '-Command', POWERSHELL_PAIRS]));

package/dist/command/setup/probe/existing-app.d.ts

@@ -10,3 +10,15 @@ export declare function urlOfExistingApp(entries: readonly DevServerEntry[], sco
     projectId?: string | undefined;
     root?: string | undefined;
 }): string | undefined;
+/**
+ * The url of a window of THIS project already connected to the daemon, if one is.
+ *
+ * A desktop app with a packaged renderer announces no dev server, so the registry above cannot see
+ * it, and setup started the app again beside the running one. On macOS a build signed differently
+ * from the installed app is a different app to the keychain, so every start asked for the password
+ * again. Scoped to the project the page reported, like the registry: never a sibling's window.
+ */
+export declare function connectedAppUrl(sessions: readonly {
+    readonly url?: string;
+    readonly projectId?: string;
+}[], projectId: string | undefined): string | undefined;

package/dist/command/setup/probe/existing-app.js

@@ -11,3 +11,17 @@ export function urlOfExistingApp(entries, scope) {
     const first = mine[0];
     return first === undefined ? undefined : first.url;
 }
+/**
+ * The url of a window of THIS project already connected to the daemon, if one is.
+ *
+ * A desktop app with a packaged renderer announces no dev server, so the registry above cannot see
+ * it, and setup started the app again beside the running one. On macOS a build signed differently
+ * from the installed app is a different app to the keychain, so every start asked for the password
+ * again. Scoped to the project the page reported, like the registry: never a sibling's window.
+ */
+export function connectedAppUrl(sessions, projectId) {
+    if (projectId === undefined)
+        return undefined;
+    const mine = sessions.find((s) => s.projectId === projectId && 0 < (s.url ?? '').length);
+    return mine?.url;
+}

package/dist/command/setup/remaining-steps.js

@@ -34,7 +34,8 @@ export function remainingSteps(p) {
             '`reticle_*` tools, ending in `reticle_act_and_wait` or `reticle_assert` — those two are ' +
             'what produce a verdict. Or hand the whole drive to Reticle with `reticle_verify { action: ' +
             '"explore", persona: "<who does what>" }`, which records what it drove so later runs replay ' +
-            'with no model in the loop; that route needs ANTHROPIC_API_KEY.');
+            'with no model in the loop; that route runs on the Reticle platform and needs a linked ' +
+            'project (`reticle connect`); a new account gets 10 free credits to try it.');
     }
     // Whether anything is actually outstanding, read BEFORE the docs pointer is added -- that line is
     // an offer, not a task, and a run with nothing left still gets it.

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

@@ -2,12 +2,8 @@
  * The half of setup that happens after the files are written.
  *
  * `init` wires a project; this gets the app running with the SDK inside it and proves a session
- * connected. That is where ONBOARDING ends — the first run, which proves a flow, is a separate
- * stage and a separate command.
- *
- * It does NOT drive a flow. `reticle_verify { action: "explore" }` does that, with a model inside
- * the daemon that already holds the tools — so no client restart is needed and no second CLI has to
- * exist on the machine.
+ * connected. That is where ONBOARDING ends. Then init says what Reticle sees and hands the first
+ * flow to the coding agent (`try-command.ts`'s `initFirstFlow`); nothing in init drives.
  *
  * Every effect is injected. That is not ceremony: the sequence has five phases, each with its own
  * way of going wrong, and the alternative to injecting them is a test that boots a real dev server
@@ -16,6 +12,20 @@
 import { type CandidateSession } from './session-pick.js';
 import { type PageProbe } from './probe/page-probe.js';
 import { AppShape } from './desktop-shape.js';
+/**
+ * Said before Reticle starts its own static server for a plain page, while it can still be acted
+ * on: the page may already be served by something with an API behind it, and only the person
+ * running init knows that (#1426).
+ */
+export declare const STATIC_PAGE_URL_HINT: string;
+/** Whose server the success line names, so a session on Reticle's own is never mistaken for the app. */
+export declare const ServerStartedBy: {
+    readonly CALLER: "you passed its url";
+    readonly ALREADY_RUNNING: "it was already running";
+    readonly RETICLE_STATIC: "Reticle started this static server";
+    readonly SETUP: "setup started the dev server";
+};
+export type ServerStartedBy = (typeof ServerStartedBy)[keyof typeof ServerStartedBy];
 export declare const SetupPhase: {
     readonly DEV_SERVER: "dev-server";
     readonly CONNECT: "connect";
@@ -29,11 +39,14 @@ export interface SetupOutcome {
     readonly url?: string | undefined;
     readonly sessionId?: string | undefined;
     /**
-     * Always false here now, and kept because the callers that report progress still read it.
-     *
-     * Onboarding does not drive, so it cannot save a flow. The first run is what saves one.
+     * Always false: init never drives, and the coding agent proves the first flow after it.
      */
     readonly flowSaved: boolean;
+    /**
+     * The session was a Reticle-owned headless browser, now closed: there is no tab of the person's
+     * own to drive a first flow in.
+     */
+    readonly leased?: boolean;
     /** What the caller should do next, when this did not finish. */
     readonly fallback: string[];
     readonly notes: string[];
@@ -55,6 +68,11 @@ export interface DaemonReason {
 export interface OwnedBrowser {
     readonly sessionId: string;
     readonly release: () => Promise<void>;
+    /**
+     * The page never dialled in, so the lease injected Reticle's own reader. That session proves the
+     * reader, not this install, and must never end onboarding as "connected".
+     */
+    readonly zeroInstall?: boolean;
 }
 export interface SetupEffects {
     /** Start the dev server. Resolves once started; the caller owns stopping it. */
@@ -120,6 +138,13 @@ export interface SetupInput {
     /** This project's id, so a live tab of it can be told from another app's on the same url. */
     readonly projectId?: string | undefined;
     readonly devCommand?: string | undefined;
+    /**
+     * `devCommand` is Reticle's own static server, not the project's. The page may already be served
+     * by something else (python, php, a Node server with an API), and only the person running init
+     * can say so — with --url — so they are told before :5500 starts, and the success line says
+     * whose server it is (#1426).
+     */
+    readonly devCommandIsStaticPage?: boolean | undefined;
     /** The app is already served here, so nothing is started. */
     readonly suppliedUrl?: string | undefined;
     /**

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

@@ -2,18 +2,14 @@
  * The half of setup that happens after the files are written.
  *
  * `init` wires a project; this gets the app running with the SDK inside it and proves a session
- * connected. That is where ONBOARDING ends — the first run, which proves a flow, is a separate
- * stage and a separate command.
- *
- * It does NOT drive a flow. `reticle_verify { action: "explore" }` does that, with a model inside
- * the daemon that already holds the tools — so no client restart is needed and no second CLI has to
- * exist on the machine.
+ * connected. That is where ONBOARDING ends. Then init says what Reticle sees and hands the first
+ * flow to the coding agent (`try-command.ts`'s `initFirstFlow`); nothing in init drives.
  *
  * Every effect is injected. That is not ceremony: the sequence has five phases, each with its own
  * way of going wrong, and the alternative to injecting them is a test that boots a real dev server
  * and a real browser to find out what happens when neither works.
  */
-import { judgeWait, portBusyMessage, QUIET_MEANS_HUNG_MS, urlToWatch, WaitVerdict, } from './bringup/dev-server-wait.js';
+import { judgeWait, devServerDiedMessage, portBusyMessage, QUIET_MEANS_HUNG_MS, urlToWatch, WaitVerdict, } from './bringup/dev-server-wait.js';
 import { connectProgressLine, waitProgressLine } from './terminal/wait-progress.js';
 /**
  * Windows gets longer to say something before silence counts as a wedge.
@@ -47,6 +43,21 @@ const NO_BROWSER_GRACE_MS = 3_000;
  * as opened, and init then waited out its whole connect budget over a correct install.
  */
 const SYSTEM_BROWSER_GRACE_MS = 15_000;
+/**
+ * Said before Reticle starts its own static server for a plain page, while it can still be acted
+ * on: the page may already be served by something with an API behind it, and only the person
+ * running init knows that (#1426).
+ */
+export const STATIC_PAGE_URL_HINT = 'This page has no dev server of its own, so Reticle is starting a static one. ' +
+    'If the page is already served (python -m http.server, php -S, a Node server with an API), ' +
+    're-run with `reticle init --url <app>` to attach to that server instead.';
+/** Whose server the success line names, so a session on Reticle's own is never mistaken for the app. */
+export const ServerStartedBy = {
+    CALLER: 'you passed its url',
+    ALREADY_RUNNING: 'it was already running',
+    RETICLE_STATIC: 'Reticle started this static server',
+    SETUP: 'setup started the dev server',
+};
 export const SetupPhase = {
     DEV_SERVER: 'dev-server',
     CONNECT: 'connect',
@@ -129,12 +140,14 @@ export async function runSetupPhases(input, fx) {
             note(
             // "stop here rather than invent one" is the SKILL.md rule, and the words are the contract —
             // inventing a dev command is how a setup script runs the wrong thing and reports success.
-            'No dev command: the project names no dev, start or serve script, and there is no --url. ' +
+            'No dev command: the project names no dev, start or serve script, and no app url was given (`reticle init --url <app>`). ' +
                 'Stopping here rather than invent one — start the app yourself and pass --url to say ' +
                 'where it is serving, or add a dev/start/serve script to package.json and re-run.');
             return stop(input, SetupPhase.DEV_SERVER, {}, notes);
         }
         else {
+            if (true === input.devCommandIsStaticPage)
+                note(STATIC_PAGE_URL_HINT);
             await fx.startDevServer(input.devCommand, input.appDir);
             const startedAt = fx.now();
             // This loop used to poll in complete silence. Reported as thirty minutes of nothing ending in a
@@ -177,18 +190,20 @@ export async function runSetupPhases(input, fx) {
                     break;
                 }
                 if (WaitVerdict.DEAD === verdict) {
-                    note(portBusyMessage(fx.devServerOutput()) ??
-                        'The dev server exited without serving anything.');
+                    note(portBusyMessage(fx.devServerOutput()) ?? devServerDiedMessage(fx.devServerOutput()));
                     return stop(input, SetupPhase.DEV_SERVER, {}, notes);
                 }
                 if (WaitVerdict.HUNG === verdict) {
                     // 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((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. '
+                    const within = input.startupBudgetMs !== undefined && fx.now() - startedAt >= input.startupBudgetMs
+                        ? ` within ${String(input.startupBudgetMs)}ms`
+                        : undefined;
+                    note((undefined === watching
+                        ? `The dev server neither printed a URL nor bound a port${within ?? ''}, so setup has nothing to open. `
+                        : undefined !== within
+                            ? `The dev server did not become ready${within}. `
                             : `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);
@@ -232,6 +247,23 @@ export async function runSetupPhases(input, fx) {
     // dialled the bridge" over a correct install. With a lease to fall back on it is entered too, and
     // only the system browser is skipped.
     const canLease = undefined !== fx.openLease;
+    const injected = new Set();
+    /**
+     * The lease to keep, or undefined. A lease whose page only connected through Reticle's injected
+     * reader is handed straight back and its session excluded: it would otherwise be picked below and
+     * report a plain server with no SDK as an instrumented app.
+     */
+    const keepLease = async (owned) => {
+        if ('failed' in owned) {
+            note(`Could not open ${url} in a Reticle-owned browser either: ${owned.failed}`);
+            return undefined;
+        }
+        if (true !== owned.zeroInstall)
+            return owned;
+        injected.add(owned.sessionId);
+        await releaseLease(owned);
+        return undefined;
+    };
     if (null === alreadyConnected && policy.openBrowser && (input.openBrowser || canLease)) {
         // SERVED is the precondition, not SDK_PRESENT: a url that answers nothing is the only state
         // where a window is certainly useless. Whether the SDK is in the served HTML is a DIFFERENT
@@ -260,14 +292,9 @@ export async function runSetupPhases(input, fx) {
             const launcherFailed = input.openBrowser ? await fx.openBrowser(url) : undefined;
             openedBrowser = input.openBrowser;
             if (undefined !== fx.openLease && (!input.openBrowser || undefined !== launcherFailed)) {
-                const owned = await fx.openLease(url);
-                if ('failed' in owned) {
-                    note(`Could not open ${url} in a Reticle-owned browser either: ${owned.failed}`);
-                }
-                else {
-                    lease = owned;
+                lease = await keepLease(await fx.openLease(url));
+                if (undefined !== lease)
                     openedBrowser = true;
-                }
             }
         }
     }
@@ -288,7 +315,8 @@ export async function runSetupPhases(input, fx) {
     while (null === session) {
         // On a desktop app, only the desktop window counts. AppShape and the runtime a page reports use
         // the same three names, so the shape IS the requirement — see session-pick.
-        session = pickSession(await fx.listSessions(), url, before, requiredRuntime);
+        const listedNow = (await fx.listSessions()).filter((s) => !injected.has(s.sessionId));
+        session = pickSession(listedNow, url, before, requiredRuntime);
         if (null !== session)
             break;
         if (deadline <= fx.now())
@@ -301,13 +329,7 @@ export async function runSetupPhases(input, fx) {
             !isDesktop(input.shape) &&
             fx.now() - waitStartedAt >= SYSTEM_BROWSER_GRACE_MS) {
             leaseFallbackTried = true;
-            const owned = await fx.openLease(url);
-            if ('failed' in owned) {
-                note(`Could not open ${url} in a Reticle-owned browser either: ${owned.failed}`);
-            }
-            else {
-                lease = owned;
-            }
+            lease = await keepLease(await fx.openLease(url));
             continue;
         }
         // Not in silence: a desktop run used to print one line and then nothing for ten minutes.
@@ -363,41 +385,33 @@ export async function runSetupPhases(input, fx) {
     // Getting started is three stages — installation puts the CLI on the machine, onboarding wires
     // the project, the first run proves a flow — and this command owns the middle one. A connected
     // session is the whole proof that onboarding worked: the SDK is in the page, the bridge paired,
-    // and the tools now have something to talk to.
-    //
-    // `<url>` stays a placeholder in this string on purpose: `guidance-commands-run` feeds every
-    // command we print to the real parser, and an interpolated value reads there as a missing operand.
-    // The live url is named in the sentence instead, where a reader needs it anyway.
-    // Both routes, because `explore` needs a model: without ANTHROPIC_API_KEY it answers "No model
-    // configured to drive the app". Naming only that one hands the reader a dead end on any machine
-    // without a key, which is the same defect this release spent its time removing everywhere else.
-    // A heading and a numbered list rather than one paragraph: a reader scans for what to do next.
+    // and the tools now have something to talk to. What to do next is the first flow's to say.
     //
-    // This was a single 524-character note, measured on a real first run: eighty-three words, no
-    // break, naming `reticle_*` tools at a reader who had just typed `reticle init` in a terminal and
-    // has no such tools to call. The facts were right and the shape made them unreadable, which on
-    // the last line of onboarding is the same as not saying them.
-    note(`✓ Connected. ${url} is instrumented. Onboarding is done; nothing is verified yet.`);
+    // It names whose server that is, because a session on Reticle's static server is not the app a
+    // real server was serving, and "connected" alone let an agent verify the wrong one (#1426).
+    const startedBy = undefined !== input.suppliedUrl
+        ? ServerStartedBy.CALLER
+        : attachedToExisting
+            ? ServerStartedBy.ALREADY_RUNNING
+            : true === input.devCommandIsStaticPage
+                ? ServerStartedBy.RETICLE_STATIC
+                : ServerStartedBy.SETUP;
+    note(`✓ Connected to ${new URL(url).origin} (${startedBy}). Onboarding is done; nothing is verified yet.`);
     // Said, because "connected" otherwise reads as "your browser connected": the page that dialled
     // was a headless one Reticle launched and has now closed, and nothing is open on this screen.
-    if (undefined !== lease && session.sessionId === lease.sessionId) {
+    const leased = undefined !== lease && session.sessionId === lease.sessionId;
+    if (leased) {
         note('The proof came from a Reticle-owned headless browser (now closed), not a window of yours — ' +
             `open ${url} in your own browser to use the app.`);
     }
     await releaseLease(lease);
-    note('');
-    note('Next, prove one flow. Your agent does this:');
-    note('  1. Drive one flow and end it with `reticle_act_and_wait` or `reticle_assert`. Those two ' +
-        'produce a verdict; nothing else does.');
-    note('  2. Or hand over the whole drive: `reticle_verify { action: "explore", persona: "<who does ' +
-        'what>" }` records what it drove, so later runs replay with no model in the loop. Needs ' +
-        'ANTHROPIC_API_KEY.');
     return {
         ok: true,
         reachedPhase: SetupPhase.CONNECT,
         url,
         sessionId: session.sessionId,
         flowSaved: false,
+        leased,
         notes,
         fallback: [],
     };

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

@@ -29,8 +29,32 @@ interface SetupCommandInput extends Omit<SetupInput, 'shape'> {
     readonly registerAgents: boolean;
     /** The bridge's pairing token, for the MCP transport a connect-proof lease is opened over. */
     readonly pairingToken?: string | undefined;
+    /** False for `--no-first-run`: connect, and say nothing more. */
+    readonly firstRun: boolean;
+    /** `--json`: an agent is reading, so nothing is driven on its behalf. */
+    readonly json: boolean;
+    /**
+     * What happens once the connection is proved: the coverage summary and the agent prompt. A port,
+     * because it reads the daemon's status and the link, which this directory does not reach for.
+     */
+    readonly firstFlow?: FirstFlowPort | undefined;
 }
-export declare function registerOtherAgents(print: (line: string) => void): void;
+/** init's ending, as `command/cli/try-command.ts` says it. Structural, so setup imports nothing. */
+export type FirstFlowPort = (ctx: {
+    appDir: string;
+    bridgePort: number;
+    pairingToken?: string | undefined;
+    url: string;
+    sessionId: string;
+    leased: boolean;
+    openBrowser: boolean;
+    firstRun: boolean;
+    json: boolean;
+}, say: (line: string) => void) => Promise<{
+    flowSaved: boolean;
+}>;
+/** Returns how many agents it wrote a config for, so a caller does not then say "none found". */
+export declare function registerOtherAgents(print: (line: string) => void): number;
 type SetupCommandResult = SetupOutcome;
 export declare function runSetupCommand(input: SetupCommandInput, print: (line: string) => void): Promise<SetupCommandResult>;
 export {};

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

@@ -5,11 +5,12 @@
  * three lines it was. The only decision here is which effects to hand over; the sequencing lives in
  * run-setup.ts and the pieces it calls.
  */
-import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { chmodSync, existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { planAgentConfigs } from './agent-configs.js';
 import { AppShape, describeShape, readShape } from './desktop-shape.js';
+import { SigningEnv, tauriSigningEnv } from './tauri-signing.js';
 import { stopOnInterrupt } from './terminal/interrupt.js';
 import { stopOnCrash, crashSentence } from './terminal/crash.js';
 import { applyAgentPlan, applyAgentSkills } from './agent-writer.js';
@@ -22,7 +23,7 @@ import { readProjectId } from '../cli/ports/resolve/cli-port.js';
 import { spawnSync } from 'node:child_process';
 import { isAlive, reticleStateHome } from '../daemon/daemon.js';
 import { readDevServers } from '../daemon/dev-servers.js';
-import { urlOfExistingApp } from './probe/existing-app.js';
+import { connectedAppUrl, urlOfExistingApp } from './probe/existing-app.js';
 import { handedOverUrl, stopHandedOver } from './bringup/dev-server-files.js';
 import { listSessions, OwnedDevServer, probePage } from './node-effects.js';
 import { fetchStatus } from '../daemon/binding/daemon-status-probe.js';
@@ -89,6 +90,7 @@ function hasElectronDependency(dir) {
  */
 /** `agent`, `agents`. */
 const agentWord = (n) => (1 === n ? 'agent' : 'agents');
+/** Returns how many agents it wrote a config for, so a caller does not then say "none found". */
 export function registerOtherAgents(print) {
     const platform = process.platform;
     const home = homedir();
@@ -124,6 +126,7 @@ export function registerOtherAgents(print) {
     for (const noted of approvals.filter((a) => undefined !== a.warn)) {
         print(`  ⚠ ${noted.name}: ${String(noted.warn)}`);
     }
+    return wrote.length;
 }
 /**
  * Run the phases against the real world.
@@ -162,6 +165,31 @@ async function restartHandedOverServer(appDir) {
     }
     return stopped;
 }
+/**
+ * init's ending, inside the dev server's lifetime: coverage is read off the open tab, and the `finally`
+ * in `runSetupCommand` only stops a server that was not handed over. Its lines join the notes, so
+ * `--json` carries the next step too.
+ */
+async function afterConnect(input, url, sessionId, outcome, print) {
+    const notes = [...outcome.notes];
+    if (input.firstFlow === undefined)
+        return { flowSaved: false, notes };
+    const { flowSaved } = await input.firstFlow({
+        appDir: input.appDir,
+        bridgePort: input.bridgePort,
+        pairingToken: input.pairingToken,
+        url,
+        sessionId,
+        leased: true === outcome.leased,
+        openBrowser: input.openBrowser,
+        firstRun: input.firstRun,
+        json: input.json,
+    }, (line) => {
+        notes.push(line);
+        print(line);
+    });
+    return { flowSaved, notes };
+}
 export async function runSetupCommand(input, print) {
     if (input.registerAgents)
         registerOtherAgents(print);
@@ -212,7 +240,29 @@ export async function runSetupCommand(input, print) {
     const effects = {
         startDevServer: (command, cwd) => {
             print(`starting: ${command}`);
-            server.start(command, cwd, input.env);
+            const signing = AppShape.TAURI === shape
+                ? tauriSigningEnv({
+                    platform: process.platform,
+                    env: { ...process.env, ...input.env },
+                    read: (path) => {
+                        try {
+                            return readFileSync(join(cwd, path), 'utf8');
+                        }
+                        catch {
+                            return undefined;
+                        }
+                    },
+                    writeRunner: (name, script) => {
+                        const path = join(reticleStateHome(), name);
+                        writeFileSync(path, script);
+                        chmodSync(path, 0o755);
+                        return path;
+                    },
+                })
+                : {};
+            if (SigningEnv.IDENTITY in signing)
+                print(`signing the dev build as ${String(signing[SigningEnv.IDENTITY])}, so macOS does not ask for the keychain password`);
+            server.start(command, cwd, { ...input.env, ...signing });
             return Promise.resolve();
         },
         // The server the plugin announced (Vite), or failing that the one a previous init handed over
@@ -224,7 +274,9 @@ export async function runSetupCommand(input, print) {
             (await handedOverUrl(reticleStateHome(), input.appDir, {
                 alive: isAlive,
                 answers: async (url) => (await probePage(url)).served,
-            })),
+            })) ??
+            // A desktop window of this project already connected: its renderer announces no server.
+            connectedAppUrl(await listSessions(input.bridgePort), readProjectId(input.appDir)),
         devServerOutput: () => server.output(),
         devServerExited: () => server.exited(),
         devServerQuietForMs: () => server.quietForMs(),
@@ -285,8 +337,11 @@ export async function runSetupCommand(input, print) {
             if (undefined !== log)
                 print(`The dev server keeps running; its output goes to ${log}`);
         }
+        if (!outcome.ok || undefined === outcome.url || undefined === outcome.sessionId)
+            return outcome;
         return {
             ...outcome,
+            ...(await afterConnect(input, outcome.url, outcome.sessionId, outcome, print)),
         };
     }
     finally {

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

@@ -1,5 +1,22 @@
-import { McpClient, MCP_CLIENTS, claudeAddCommand, claudeAvailableProbe, claudeHasReticle, detectMcpClients, mergeClientConfig, clientSpec, ClientMergeStatus, } from '@reticlehq/init';
+import { McpClient, MCP_CLIENTS, claudeAddCommand, claudeAvailableProbe, claudeHasReticle, codexAddCommand, codexAvailableProbe, codexNamesOurServer, detectMcpClients, mergeClientConfig, clientSpec, ClientMergeStatus, } from '@reticlehq/init';
 import { OnboardingPhase, OnboardingStepStatus, } from '@reticlehq/core/telemetry';
+/**
+ * Codex registers through `codex mcp add`, which does the TOML editing we refuse to do (#1238).
+ * `undefined` when that does not apply, and the caller reports a hand edit exactly as before: not
+ * Codex, the `codex` binary is not here, or the config already names a `reticle` server. That last
+ * one matters: `codex mcp add` REPLACES an entry of the same name and still exits 0, so an entry
+ * somebody wrote themselves, in any shape, must never reach it. Otherwise: did the command take.
+ */
+function registerWithCodexCli(io, client, serversKey) {
+    if (McpClient.CODEX !== client.id || codexNamesOurServer(client.existing, serversKey)) {
+        return undefined;
+    }
+    const probe = codexAvailableProbe();
+    if (!io.runCli(probe.command, probe.args))
+        return undefined;
+    const cmd = codexAddCommand();
+    return io.runCli(cmd.command, cmd.args);
+}
 export function setupMcp(io) {
     const detected = [];
     const registered = [];
@@ -47,7 +64,13 @@ export function setupMcp(io) {
         // on an existing file and would CREATE an empty one otherwise, and either way claiming success
         // sends somebody to an agent that has no Reticle tools in it.
         if (ClientMergeStatus.MANUAL === merged.status) {
-            manual.push({ id: client.id, configPath: client.configPath, docs: spec.docs });
+            const viaCli = registerWithCodexCli(io, client, spec.serversKey);
+            if (true === viaCli)
+                registered.push(client.id);
+            else if (false === viaCli)
+                failed.push(client.id);
+            else
+                manual.push({ id: client.id, configPath: client.configPath, docs: spec.docs });
             continue;
         }
         try {

package/dist/command/setup/tauri-signing.d.ts

@@ -0,0 +1,19 @@
+/** The env the runner reads its arguments from: the script stays a fixed file. */
+export declare const SigningEnv: {
+    readonly IDENTITY: "RETICLE_SIGNING_IDENTITY";
+    readonly IDENTIFIER: "RETICLE_SIGNING_IDENTIFIER";
+    readonly APPLE: "APPLE_SIGNING_IDENTITY";
+};
+export declare const RUNNER_FILE = "tauri-sign-runner.sh";
+/** The runner: sign the binary Cargo built, then run it exactly as Cargo would have. */
+export declare const RUNNER_SCRIPT: string;
+export interface SigningDeps {
+    readonly platform: string;
+    readonly env: Readonly<Record<string, string | undefined>>;
+    /** A file's text relative to the app directory, or undefined when it is absent. */
+    readonly read: (path: string) => string | undefined;
+    /** Writes the runner and makes it executable; returns its absolute path. */
+    readonly writeRunner: (name: string, script: string) => string;
+}
+/** The extra env for starting a Tauri dev build signed, or `{}` when there is nothing to sign with. */
+export declare function tauriSigningEnv(deps: SigningDeps): Record<string, string>;