@reticlehq/server 3.4.0 → 3.6.0

package/dist/command/cli/drive/drive-attach.js

@@ -31,6 +31,7 @@
 import * as http from 'node:http';
 import { DRIVE_PATH, LOOPBACK_HOST } from '@reticlehq/core';
 import { PortPresence } from '../../daemon/binding/port-presence.js';
+import { summarizeStatus } from '../../daemon/binding/daemon-status-probe.js';
 /** What `drive` should do about the port, given what is on it. */
 export const DriveMode = {
     /** Nothing is listening: bind it and run the foreground engine. */
@@ -134,18 +135,84 @@ export async function requestDriveSession(port, url, post = postJson) {
     }
     return readAttachResponse(port, url, res);
 }
+/** Nothing known about the app, as for a page that never connected. */
+export const NO_ATTACHED_APP = { fields: {}, mismatch: false };
+/**
+ * Control characters, and the 0x80 to 0x9f range some terminals also obey. Built with
+ * `fromCharCode` to keep them out of a regex literal (no-control-regex).
+ */
+const TERMINAL_CONTROLS = new RegExp(`[${String.fromCharCode(0)}-${String.fromCharCode(0x1f)}${String.fromCharCode(0x7f)}-${String.fromCharCode(0x9f)}]`, 'g');
+/**
+ * A value safe to print. The project id and title come from the page, and the expected project id
+ * from a `.reticle.json` anyone can commit. All three are written straight to the terminal (and into
+ * the JSON line beside it), so they could otherwise move the cursor or retitle the window. Each
+ * control character becomes U+FFFD, so the reader can still see that something was there.
+ */
+function printable(value) {
+    return value.replace(TERMINAL_CONTROLS, '\uFFFD');
+}
+/**
+ * Pick the attached session out of a `/status` payload. Pure.
+ *
+ * The drive answer is a lease result, which carries no project: the page reports that itself when
+ * it connects, and `/status` is where it is already listed.
+ */
+export function attachedApp(status, sessionId, expectedProjectId) {
+    const row = summarizeStatus(status).sessions.find((s) => s.sessionId === sessionId);
+    return {
+        fields: {
+            ...(row?.projectId === undefined ? {} : { projectId: printable(row.projectId) }),
+            ...(row?.title === undefined ? {} : { title: printable(row.title) }),
+            ...(expectedProjectId === undefined
+                ? {}
+                : { expectedProjectId: printable(expectedProjectId) }),
+        },
+        // Only warned when both sides are known: a page with no project id proves nothing, and neither
+        // does a directory without a `.reticle.json`.
+        mismatch: row?.projectId !== undefined &&
+            expectedProjectId !== undefined &&
+            row.projectId !== expectedProjectId,
+    };
+}
+/** The fallback when the daemon sent no hint for a page that did not connect. */
+const MSG_NOT_READY_HINT = 'Check that the app embeds @reticlehq/browser.';
+/** How the attach line names the page's project. */
+const PROJECT_LABEL = (projectId) => `project ${JSON.stringify(projectId)}`;
+/** The page is a different project from the one this directory's `.reticle.json` names. */
+const MSG_PROJECT_MISMATCH = (url, expected, actual) => `Warning: this directory's .reticle.json is ${PROJECT_LABEL(expected)}, but the page at ${url} ` +
+    `is ${PROJECT_LABEL(actual)}, so another app is probably serving that port. Check which dev ` +
+    'server is on it before trusting anything this session reports.';
+/**
+ * The project and title, and a warning when this directory names a different project.
+ *
+ * In a monorepo the port you meant for one app is easily held by another, and the port, url and
+ * session id read the same either way.
+ */
+function describeApp(url, app) {
+    const { projectId, title, expectedProjectId } = app.fields;
+    const named = [
+        ...(projectId === undefined ? [] : [PROJECT_LABEL(projectId)]),
+        ...(title === undefined ? [] : [JSON.stringify(title)]),
+    ];
+    const label = 0 === named.length ? '' : ` (${named.join(', ')})`;
+    const warning = app.mismatch && projectId !== undefined && expectedProjectId !== undefined
+        ? ` ${MSG_PROJECT_MISMATCH(url, expectedProjectId, projectId)}`
+        : '';
+    return { label, warning };
+}
 /** The success line. Names the session, because that is the handle everything downstream needs. */
-export function describeAttached(port, url, session) {
+export function describeAttached(port, url, session, app = NO_ATTACHED_APP) {
     const life = session.expiresInMs === undefined
         ? ''
         : ` It is released after ${String(Math.round(session.expiresInMs / 1000))}s untouched; any ` +
             'tool call against it resets that.';
     if (!session.ready) {
         return (`the Reticle daemon on :${String(port)} opened ${url} as session ${session.sessionId}, but ` +
-            `the page did not connect to the bridge. ${session.hint ?? 'Check that the app embeds @reticlehq/core.'}`);
+            `the page did not connect to the bridge. ${session.hint ?? MSG_NOT_READY_HINT}`);
     }
-    return (`attached to the Reticle daemon on :${String(port)} — it is driving ${url} as session ` +
-        `${session.sessionId}, which every Reticle tool can address.${life}`);
+    const { label, warning } = describeApp(url, app);
+    return (`attached to the Reticle daemon on :${String(port)} — it is driving ${url}${label} as session ` +
+        `${session.sessionId}, which every Reticle tool can address.${life}${warning}`);
 }
 /**
  * What an attach cannot honour: the window.

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

@@ -6,8 +6,9 @@
  * place. The pure parts (which mode, and every sentence a user reads) live next door in
  * drive-attach.ts, which is where the reasoning for attaching is written down.
  */
+/** `projectId` is the one in this directory's `.reticle.json`, read by the caller. */
 export declare function handleDrive(parsed: {
     port: number;
     driveUrl: string;
     headless: boolean;
-}): void;
+}, projectId?: string): void;

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

@@ -13,9 +13,10 @@ import { probeDaemon } from '../../../surface/mcp/mcp-proxy.js';
 import { readPid } from '../../daemon/daemon.js';
 import { fetchStatus } from '../../daemon/binding/daemon-status-probe.js';
 import { captureLookup, findPortHolder } from '../ports/port-holder.js';
-import { DriveMode, decideDriveMode, describeAttached, driveForeignHolder, driveHeadlessOnAttach, driveRaceLost, requestDriveSession, } from './drive-attach.js';
-export function handleDrive(parsed) {
-    void driveWithHonestConflict(parsed);
+import { DriveMode, NO_ATTACHED_APP, attachedApp, decideDriveMode, describeAttached, driveForeignHolder, driveHeadlessOnAttach, driveRaceLost, requestDriveSession, } from './drive-attach.js';
+/** `projectId` is the one in this directory's `.reticle.json`, read by the caller. */
+export function handleDrive(parsed, projectId) {
+    void driveWithHonestConflict(parsed, projectId);
 }
 /**
  * Decide who gets the port BEFORE binding it — and when the answer is "the daemon", ask it instead.
@@ -29,7 +30,7 @@ export function handleDrive(parsed) {
  * because the MCP proxy respawns a daemon into the gap. So a healthy daemon is now ATTACHED to —
  * see cli/drive/drive-attach.ts.
  */
-async function driveWithHonestConflict(parsed) {
+async function driveWithHonestConflict(parsed, projectId) {
     const presence = await probePresence(parsed.port, { tcpOpen: probeDaemon, status: fetchStatus });
     const mode = decideDriveMode(presence);
     if (DriveMode.REFUSE === mode) {
@@ -43,7 +44,7 @@ async function driveWithHonestConflict(parsed) {
         return;
     }
     if (DriveMode.ATTACH === mode) {
-        await attachToRunningDaemon(parsed.port, parsed.driveUrl, parsed.headless);
+        await attachToRunningDaemon(parsed.port, parsed.driveUrl, parsed.headless, projectId);
         return;
     }
     // The probe cannot close the race: something can take the port between here and the bind, and the
@@ -81,7 +82,7 @@ async function driveWithHonestConflict(parsed) {
  * against it renews its lease), and a foreground hold here could only keep it alive by faking tool
  * calls at it.
  */
-async function attachToRunningDaemon(port, url, headless) {
+async function attachToRunningDaemon(port, url, headless, projectId) {
     const result = await requestDriveSession(port, url);
     if (!result.ok) {
         log('reticle_drive_attach_failed', { port, url, reason: result.reason });
@@ -89,13 +90,18 @@ async function attachToRunningDaemon(port, url, headless) {
         process.exit(1);
         return;
     }
+    // Only a page that connected has reported its project; one that never dialled in is not listed.
+    const app = result.session.ready
+        ? attachedApp(await fetchStatus(port), result.session.sessionId, projectId)
+        : NO_ATTACHED_APP;
     log('reticle_drive_attached', {
         port,
         url,
         sessionId: result.session.sessionId,
         ready: result.session.ready,
+        ...app.fields,
     });
-    process.stderr.write(`${describeAttached(port, url, result.session)}\n`);
+    process.stderr.write(`${describeAttached(port, url, result.session, app)}\n`);
     // The command's own default is headed, and this path cannot deliver that. Said out loud rather
     // than left for the user to discover by watching a window that never opens.
     if (!headless)

package/dist/command/cli/lifecycle/daemon-lifecycle.js

@@ -16,7 +16,7 @@
  */
 import { log } from '../../../log.js';
 import { RETICLE_VERIFY_DEFAULT_PORT } from '../../../index.js';
-import { verifyEndpointMismatch } from '../../../status-payload.js';
+import { strandedClientsNote, verifyEndpointMismatch } from '../../../status-payload.js';
 import { probeDaemon, waitForDaemonBind } from '../../../surface/mcp/mcp-proxy.js';
 import { stateDirProblem } from '../../daemon/state-dir.js';
 import { readPid, isAlive, removePid, spawnDaemon, logPath, reticleStateHome, } from '../../daemon/daemon.js';
@@ -168,6 +168,9 @@ export function handleStop(port, quiet) {
  * anything at all, and a single `ok: false` cannot tell them which happened.
  */
 export async function handleRestart(port, force) {
+    const stranded = strandedClientsNote(await fetchStatus(port));
+    if (stranded !== undefined)
+        process.stderr.write(`${stranded}\n`);
     const freed = await runKill(port, force);
     if (!freed) {
         log('reticle_restart_aborted', {

package/dist/command/cli/ports/port-holder.d.ts

@@ -51,3 +51,13 @@ export declare function describeForeignHolder(port: number, holder: PortHolder |
 ourPid?: number | null): string;
 /** The lookup itself. `exec` is injected so the shelling out never runs in a unit test. */
 export declare function findPortHolder(port: number, exec: (command: string, args: readonly string[]) => string | null): PortHolder | null;
+/** The path in `lsof -a -p <pid> -d cwd -Fn` output, or null when it printed none. */
+export declare function parseProcessCwd(stdout: string): string | null;
+/**
+ * The working directory of whatever LISTENS on `port`, or null.
+ *
+ * How the daemon tells which checkout served a page when every git worktree declares the same
+ * projectId: the dev server runs inside exactly one of them. Null wherever `lsof` cannot answer —
+ * Windows, a slim container — and the caller then keeps the answer it had without this.
+ */
+export declare function findListenerCwd(port: number, exec: (command: string, args: readonly string[]) => string | null): string | null;

package/dist/command/cli/ports/port-holder.js

@@ -121,3 +121,27 @@ export function findPortHolder(port, exec) {
     const out = exec('lsof', ['-nP', `-iTCP:${String(port)}`, '-sTCP:LISTEN', '-F', 'pc']);
     return null === out ? null : parsePortHolder(out);
 }
+/** `lsof -Fn` emits the file name on its own line, prefixed `n`. */
+const NAME_FIELD = 'n';
+/** The path in `lsof -a -p <pid> -d cwd -Fn` output, or null when it printed none. */
+export function parseProcessCwd(stdout) {
+    for (const raw of stdout.split('\n')) {
+        if (raw.startsWith(NAME_FIELD) && raw.length > NAME_FIELD.length)
+            return raw.slice(1);
+    }
+    return null;
+}
+/**
+ * The working directory of whatever LISTENS on `port`, or null.
+ *
+ * How the daemon tells which checkout served a page when every git worktree declares the same
+ * projectId: the dev server runs inside exactly one of them. Null wherever `lsof` cannot answer —
+ * Windows, a slim container — and the caller then keeps the answer it had without this.
+ */
+export function findListenerCwd(port, exec) {
+    const holder = findPortHolder(port, exec);
+    if (null === holder)
+        return null;
+    const out = exec('lsof', ['-a', '-p', String(holder.pid), '-d', 'cwd', '-Fn']);
+    return null === out ? null : parseProcessCwd(out);
+}

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';
@@ -35,20 +35,30 @@ export function handleSetupMcp(reportStep, standalone = true) {
     const result = setupMcp(io);
     if (0 === result.detected.length) {
         // Even with no file-backed client, the broader set may still have somewhere to write.
-        registerOtherAgents((line) => {
+        const preRegistered = registerOtherAgents((line) => {
             io.print(line);
         });
         // Named rather than a bare "none found". A person whose agent IS installed needs to know
         // whether we looked for it at all, and the list is the difference between "we did not find
-        // yours" and "we do not support yours".
-        io.print(`No coding agent config found. Looked for: ${knownClientLabels().join(', ')}.`);
-        io.print('Install one, then run `reticle setup mcp` again.');
+        // yours" and "we do not support yours". When the broader set was written, saying "none found"
+        // right under its tick read as a contradiction: those agents are pre-registered, not found.
+        io.print(0 < preRegistered
+            ? `None of ${knownClientLabels().join(', ')} is installed here yet. The agents above are pre-registered and have Reticle's tools once installed; install one of the others, then run \`reticle setup mcp\` again.`
+            : `No coding agent config found. Looked for: ${knownClientLabels().join(', ')}. Install one, then run \`reticle setup mcp\` again.`);
         return;
     }
     for (const id of result.registered)
         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/tutorial.d.ts

@@ -84,8 +84,8 @@ export declare function tutorialNextSteps(audience: TutorialAudience, restartAge
  * on `process.stdout.isTTY` does not work: that is `undefined` through every pipe, so the tour never
  * prints. A heuristic that silently answers "nobody is watching" is worse than no heuristic.
  *
- * It ends with the tour's OWN closing, which already names `reticle init`. Adding a second "Next:"
- * under it would be the same instruction twice in ten lines.
+ * It ends with the tour's OWN closing. Installing changes no project: the app is wired the first time
+ * an agent uses Reticle in it (see first-run-wiring.ts).
  */
 export declare function installClosing(registered?: boolean): string;
 export declare function renderTutorial(audience: TutorialAudience): string;

package/dist/command/cli/tutorial.js

@@ -95,8 +95,8 @@ export function tutorialNextSteps(audience, restartAgent = false) {
     const lines = TutorialAudience.AGENT === audience
         ? [
             'Next:',
-            '  reticle init            # instrument the project in this directory',
-            '  reticle status          # confirms the app connected, or says why it has not',
+            '  reticle_session list    # the first call wires this project: Reticle runs init itself',
+            '                          # and names every file it changed — tell the user which',
             '  then run the four steps above against it, and report the verdict',
         ]
         : [
@@ -104,12 +104,9 @@ export function tutorialNextSteps(audience, restartAgent = false) {
             ...(restartAgent
                 ? ['  restart your agent                 # it loads new tools only when it starts']
                 : []),
-            '  cd <your project> && reticle init  # wire Reticle into the app',
-            '  npm run dev                        # then load it in a browser',
-            '  reticle status                     # confirms the app connected, or says why not',
             '',
             // One line: the terminal wraps it at the reader's width, not ours.
-            'Then ask your agent to drive one real flow and report the verdict. That is the install proving itself, and it is the agent’s job rather than a command you run.',
+            'Ask your agent to verify one real flow in your project. Nothing in your app changed at install: the first time the agent uses Reticle there, Reticle wires the app, starts it, and tells you which files it changed.',
         ];
     return lines.join('\n');
 }
@@ -120,8 +117,8 @@ export function tutorialNextSteps(audience, restartAgent = false) {
  * on `process.stdout.isTTY` does not work: that is `undefined` through every pipe, so the tour never
  * prints. A heuristic that silently answers "nobody is watching" is worse than no heuristic.
  *
- * It ends with the tour's OWN closing, which already names `reticle init`. Adding a second "Next:"
- * under it would be the same instruction twice in ten lines.
+ * It ends with the tour's OWN closing. Installing changes no project: the app is wired the first time
+ * an agent uses Reticle in it (see first-run-wiring.ts).
  */
 export function installClosing(registered = true) {
     // One line a step. The reasons are for `reticle tutorial`; right after an install they turned a
@@ -140,7 +137,7 @@ export function installClosing(registered = true) {
  * Reticle" points at a panel on screen; straight after an install there is none to point at.
  */
 const INSTALL_SAYS = {
-    connect: 'Once `reticle init` wires your app, a Reticle panel appears in it: your proof the SDK is connected.',
+    connect: 'The first time your agent uses Reticle in a project, it wires the app and a Reticle panel appears in it: your proof the SDK is connected.',
 };
 export function renderTutorial(audience) {
     const steps = tutorialScript(audience)

package/dist/command/cli.d.ts

@@ -2,5 +2,11 @@
 import { parseCliArgs, CLI_USAGE } from './cli/cli-parse.js';
 export { parseCliArgs, CLI_USAGE };
 export type { CliResult } from './cli/cli-parse.js';
+/**
+ * Report status to the terminal. `--json` writes one structured line to STDOUT so it can be piped
+ * into `jq`; the human-readable block goes to stdout too. `log()` stays on stderr (the MCP
+ * transport lives on stdout), so `--json` must not go through it.
+ */
+export declare function reportStatus(fields: Record<string, unknown>, json: boolean): void;
 export declare function handleStatus(port: number, json?: boolean): Promise<void>;
 export declare function main(): void;

package/dist/command/cli.js

@@ -1,10 +1,11 @@
 #!/usr/bin/env node
+import { hudSignIn } from './cli/cloud-login.js';
 import { handleSetupMcp, handleSetupInstall } from './cli/setup-mcp-cli.js';
 import { reportStepFromCli, reportTutorialShown } from './cli-onboarding.js';
 import { runDemoTour } from './cli/demo/demo-run.js';
 import { renderTutorial } from './cli/tutorial.js';
 import { pathToFileURL } from 'node:url';
-import { openFailureNote } from './cli/answers/open-note.js';
+import { openFailureNote, openLaunchFailureNote } from './cli/answers/open-note.js';
 import { realpathSync } from 'node:fs';
 import { join } from 'node:path';
 import { installCrashGuard } from './setup/setup-command.js';
@@ -15,9 +16,9 @@ import { splitBrainFields, withNextAction } from './cli/status-fields.js';
 import { reticleStateHome } from './daemon/daemon.js';
 import { handleMcp } from './cli/mcp-command.js';
 import { handleReport } from './cli/report-command.js';
-import { daemonProjectAt, resolveDaemonForProject } from './daemon/daemon-resolve.js';
+import { daemonProjectAt, readDaemonRegistry, resolveDaemonForProject, } from './daemon/daemon-resolve.js';
 import { pickDaemonPortToBind } from './daemon/binding/free-port.js';
-import { portForInit, portFromEnv } from './setup/init/init-port.js';
+import { isSameOrAbove, portForInit, portFromEnv } from './setup/init/init-port.js';
 import { daemonStartOptions } from './cli/daemon-start-options.js';
 import { handleWatch, handleCapsules, handleGate, loadNamedFlows, resolveChangedFiles, } from './cli/cli-flow-commands.js';
 import { RETICLE_DEFAULT_PORT, ReticleDir, ReticleEnv, devServersForProject, } from '@reticlehq/core';
@@ -78,8 +79,12 @@ async function handleInit(parsed) {
         },
         daemonPresent: async (p) => presenceIsUsable(await probePresence(p, { tcpOpen: probeDaemon, status: fetchStatus })),
         pickPort: (p) => pickDaemonPortToBind(p),
+        daemonStartedHere: (p) => {
+            const started = readDaemonRegistry(reticleStateHome()).find((e) => e.port === p)?.cwd;
+            return started !== undefined && isSameOrAbove(started, cwd);
+        },
     });
-    const io = buildNodeIo(cwd, serverInitHost());
+    const io = buildNodeIo(cwd, serverInitHost(), { stderr: true === parsed.json });
     const result = runInit({
         cwd,
         port,
@@ -104,15 +109,18 @@ async function handleInit(parsed) {
 import { handleServe, handleStop, handleRestart } from './cli/lifecycle/daemon-lifecycle.js';
 import { statusLines } from './cli/status/status-lines.js';
 /**
- * Log the status event AND print it for a person.
- *
- * Both, not either: the JSON line is documented and is what a log is for, and the block is for
- * whoever is reading the terminal — which, once an agent is running the command, is somebody who
- * did not type it and cannot be assumed to parse it.
+ * Report status to the terminal. `--json` writes one structured line to STDOUT so it can be piped
+ * into `jq`; the human-readable block goes to stdout too. `log()` stays on stderr (the MCP
+ * transport lives on stdout), so `--json` must not go through it.
  */
-function reportStatus(fields, json) {
+export function reportStatus(fields, json) {
     if (json) {
-        log('reticle_status', fields);
+        const line = JSON.stringify({
+            t: new Date().toISOString(),
+            event: 'reticle_status',
+            ...fields,
+        });
+        process.stdout.write(`${line}\n`);
         return;
     }
     process.stdout.write(`${statusLines(fields).join('\n')}\n`);
@@ -223,14 +231,13 @@ export async function handleStatus(port, json = false) {
         ...nudge,
     });
 }
-/** Print the running package version (resolved once in server-version.ts). */
+/**
+ * Print the running package version (resolved once in server-version.ts), and nothing else.
+ *
+ * Bare on stdout so `V=$(reticle version)` works. It also wrote a JSON event to stderr, which a
+ * terminal shows: the first thing a new user typed after installing answered with a log line.
+ */
 function handleVersion() {
-    log('reticle_version', { version: SERVER_VERSION });
-    // Also on stdout, bare, because every diagnostic here starts by asking which build is running and
-    // that answer has to be copyable. The event alone looked fine in a terminal -- stderr is on the
-    // screen too -- but `V=$(reticle version)` came back empty, which is exactly the shape somebody
-    // reaches for when writing an issue template or a CI check. The event stays; machine-readable
-    // events all go to stderr and that consistency is worth keeping.
     process.stdout.write(`${SERVER_VERSION}\n`);
 }
 /** `reticle license` — show enterprise activation resolved from the environment (offline; nothing leaves). */
@@ -395,9 +402,7 @@ function handleOpen(requestedPort, url) {
                 // Points at the OS handler, not at `reticle doctor`. Doctor's browser check is about
                 // Reticle's own Chromium, which this command never touches — the same misdirect the
                 // no-session note below spells out at length, left standing here for one more release.
-                recovery: 'Nothing was opened. This command asks the OS to open a url in your default browser ' +
-                    `(\`${openCommand(decision.url, process.platform).cmd}\` on this platform) and that ` +
-                    'failed, so the fix is on the OS side: open the url yourself, or set a default browser.',
+                recovery: openLaunchFailureNote(decision.url, openCommand(decision.url, process.platform).cmd),
             });
             process.exit(1);
             return;
@@ -431,7 +436,8 @@ function handleOpen(requestedPort, url) {
     });
 }
 function handleDaemonInner(parsed) {
-    const options = daemonStartOptions(parsed);
+    // The daemon the CLI starts is the one that can sign in for the panel: it owns ~/.reticle.
+    const options = { ...daemonStartOptions(parsed), hudSignIn };
     startDaemon(options)
         .then((server) => {
         log('reticle_daemon_ready', { port: parsed.port, pid: process.pid });
@@ -587,6 +593,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;
     }
@@ -706,7 +728,7 @@ export function main() {
             handleOpen(parsed.port, parsed.url);
             break;
         case 'drive':
-            handleDrive(parsed);
+            handleDrive(parsed, readProjectId(process.cwd()));
             break;
         case 'verify':
             handleVerify(parsed);

package/dist/command/daemon/binding/daemon-status-probe.d.ts

@@ -15,6 +15,8 @@ interface StatusSession {
     sessionId: string;
     url: string;
     projectId?: string;
+    /** The page's own title. Absent when the page has none, or on a daemon too old to send it. */
+    title?: string;
     throttled: boolean;
     /**
      * The tab is backgrounded. Reported by the daemon on every session; `false` on one too old to say,

package/dist/command/daemon/binding/daemon-status-probe.js

@@ -102,6 +102,7 @@ export function summarizeStatus(payload) {
             ...('string' === typeof r['projectId'] && 0 < r['projectId'].length
                 ? { projectId: r['projectId'] }
                 : {}),
+            ...('string' === typeof r['title'] && 0 < r['title'].length ? { title: r['title'] } : {}),
             throttled: true === r['throttled'],
             hidden: true === r['hidden'],
             stale: true === r['stale'],

package/dist/command/daemon/daemon-resolve.d.ts

@@ -76,6 +76,20 @@ export declare function daemonProjectAt(port: number, home: string): string | un
  * Only LIVE daemons are named: a port a session used yesterday is history, not a split.
  */
 export declare function daemonsServingProjectElsewhere(projectId: string | undefined, myPort: number, home: string, alive: (pid: number) => boolean, connectedOn: (port: number) => boolean): readonly number[];
+/** Live daemons that serve a named project, on any port but `myPort`. */
+export declare function projectDaemonsElsewhere(myPort: number, home: string, alive: (pid: number) => boolean): {
+    port: number;
+    projectId: string;
+}[];
+/**
+ * The sentence for a daemon started outside any project while projects run their own daemons, or
+ * `undefined` when there are none. Its sessions are empty because the apps dial their own ports,
+ * and "check your scope" is not something an agent inside an editor can act on (#1240).
+ */
+export declare function projectlessNote(myPort: number, others: readonly {
+    port: number;
+    projectId: string;
+}[]): string | undefined;
 /**
  * The sentence for a split brain, or `undefined` when there is none.
  *

package/dist/command/daemon/daemon-resolve.js

@@ -19,6 +19,8 @@
 import { readdirSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { DaemonRegistryEntrySchema, daemonRegistryPort, pickDaemonPort, } from '@reticlehq/core/artifacts';
+import { ReticleEnv } from '@reticlehq/core';
+const RETICLE_PORT_ENV = ReticleEnv.PORT;
 /**
  * Every well-formed registry entry in `home`.
  *
@@ -117,6 +119,30 @@ export function daemonsServingProjectElsewhere(projectId, myPort, home, alive, c
         .map((entry) => entry.port)
         .sort((a, b) => a - b);
 }
+/** Live daemons that serve a named project, on any port but `myPort`. */
+export function projectDaemonsElsewhere(myPort, home, alive) {
+    return readDaemonRegistry(home)
+        .filter((entry) => entry.port !== myPort && alive(entry.pid))
+        .flatMap((entry) => entry.projectId === undefined || 0 === entry.projectId.length
+        ? []
+        : [{ port: entry.port, projectId: entry.projectId }])
+        .sort((a, b) => a.port - b.port);
+}
+/**
+ * The sentence for a daemon started outside any project while projects run their own daemons, or
+ * `undefined` when there are none. Its sessions are empty because the apps dial their own ports,
+ * and "check your scope" is not something an agent inside an editor can act on (#1240).
+ */
+export function projectlessNote(myPort, others) {
+    const first = others[0];
+    if (first === undefined)
+        return undefined;
+    const listed = others.map((o) => `${o.projectId} on :${String(o.port)}`).join(', ');
+    return (`this daemon on :${String(myPort)} was started outside any project, and the projects on this ` +
+        `machine run their own daemons: ${listed}. Their apps connect there, not here. Point the MCP ` +
+        `server at one — set ${RETICLE_PORT_ENV}=${String(first.port)} in its config, or launch it from ` +
+        'that project directory.');
+}
 /**
  * The sentence for a split brain, or `undefined` when there is none.
  *
@@ -179,8 +205,13 @@ export async function resolveMcpPort(preferred, projectId, home, deps) {
     const mine = resolveDaemonForProject(projectId, home, deps.alive);
     if (mine !== undefined)
         return mine;
-    if (!(await deps.daemonPresent(preferred)))
-        return preferred;
+    if (!(await deps.daemonPresent(preferred))) {
+        // A caller outside any project (an editor's user-scope MCP, launched from $HOME) used to dial the
+        // default and never see the one project that had moved off it (#1240). With exactly one project
+        // daemon live, that is the one; with several, the no-session answer names them instead.
+        const projects = projectId === undefined ? projectDaemonsElsewhere(preferred, home, deps.alive) : [];
+        return 1 === projects.length ? (projects[0]?.port ?? preferred) : preferred;
+    }
     return adoptable(daemonProjectAt(preferred, home), projectId)
         ? preferred
         : deps.pickPort(preferred);

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

@@ -34,7 +34,7 @@ interface AgentWriteResult {
  */
 export declare function applyAgentPlan(plan: readonly AgentPlanStep[], io: AgentWriterIo): AgentWriteResult[];
 /** The `/reticle` instruction, for agents that load skills from a directory. */
-export declare const RETICLE_SKILL = "---\nname: reticle\ndescription: Verify a change against the running app, from inside it, before calling it done.\n---\n\nReticle exposes the running app to you as `reticle_*` MCP tools. Look, act, observe, assert.\n\nOnly `reticle_act_and_wait` and `reticle_assert` produce a verdict. Everything else moves or\nreads the app and proves nothing, so a drive that ends without one of those has no result however\nmany tools it used.\n\n`verified: \"unknown\"` is not a pass: it means Reticle could not tell what happened.\n`verified: \"no-fault\"` is not a pass either, because nothing was declared to prove. Never weaken a\ncheck to make it pass.\n\nThe cheapest path that answers the question:\n\n- \"did my edit break anything?\" -> `reticle_verify { action: \"change\", files: [...] }`\n- \"does this known journey still work?\" -> `reticle_verify { action: \"flows\", names: [\"...\"] }`\n- \"does this new behaviour work?\" -> `reticle_act { steps: [...] }` for the setup, then ONE `reticle_act_and_wait`\n- \"nothing is recorded yet\" -> `reticle_verify { action: \"explore\", persona: \"<who does what>\" }`, which\n  drives the app and SAVES what it drove, so the next run replays with no model in the loop\n";
+export declare const RETICLE_SKILL = "---\nname: reticle\ndescription: Verify a change against the running app, from inside it, before calling it done.\n---\n\nReticle exposes the running app to you as `reticle_*` MCP tools. Look, act, observe, assert.\n\nOnly `reticle_act_and_wait` and `reticle_assert` produce a verdict. Everything else moves or\nreads the app and proves nothing, so a drive that ends without one of those has no result however\nmany tools it used.\n\n`verified: \"unknown\"` is not a pass: it means Reticle could not tell what happened.\n`verified: \"no-fault\"` is not a pass either, because nothing was declared to prove. Never weaken a\ncheck to make it pass.\n\nThe cheapest path that answers the question:\n\n- \"did my edit break anything?\" -> `reticle_verify { action: \"change\", files: [...] }`\n- \"does this known journey still work?\" -> `reticle_verify { action: \"flows\", names: [\"...\"] }`\n- \"does this new behaviour work?\" -> `reticle_act { steps: [...] }` for the setup, then ONE `reticle_act_and_wait`\n- \"nothing is recorded yet\" -> drive the journey yourself with `reticle_act_and_wait` and an `until` on its\n  last step; it is saved as a flow, so the next run replays with no model in the loop. With a linked\n  project, `reticle_verify { action: \"explore\", persona: \"<who does what>\" }` drives it for you\n";
 interface SkillWriteResult {
     readonly id: string;
     readonly file: string;

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

@@ -84,8 +84,9 @@ The cheapest path that answers the question:
 - "did my edit break anything?" -> \`reticle_verify { action: "change", files: [...] }\`
 - "does this known journey still work?" -> \`reticle_verify { action: "flows", names: ["..."] }\`
 - "does this new behaviour work?" -> \`reticle_act { steps: [...] }\` for the setup, then ONE \`reticle_act_and_wait\`
-- "nothing is recorded yet" -> \`reticle_verify { action: "explore", persona: "<who does what>" }\`, which
-  drives the app and SAVES what it drove, so the next run replays with no model in the loop
+- "nothing is recorded yet" -> drive the journey yourself with \`reticle_act_and_wait\` and an \`until\` on its
+  last step; it is saved as a flow, so the next run replays with no model in the loop. With a linked
+  project, \`reticle_verify { action: "explore", persona: "<who does what>" }\` drives it for you
 `;
 /**
  * Write the skill for agents that have somewhere to put it, and only where they are installed.

package/dist/command/setup/bringup/connect-lease.d.ts

@@ -9,6 +9,7 @@
 /** A lease this run opened, and the way to hand it back; or why it could not be opened. */
 type LeaseOutcome = {
     readonly sessionId: string;
+    readonly zeroInstall: boolean;
     readonly release: () => Promise<void>;
 } | {
     readonly failed: string;

package/dist/command/setup/bringup/connect-lease.js

@@ -25,6 +25,7 @@ export async function openLeaseFor(port, url, token) {
         }
         return {
             sessionId: got.leased,
+            zeroInstall: got.zeroInstall,
             release: async () => {
                 await releaseLease(caller, got.leased);
                 await close();