@reticlehq/server 3.5.0 → 3.7.0

package/dist/command/cli.js

@@ -1,10 +1,10 @@
 #!/usr/bin/env node
+import { PlatformLinkVia } from '@reticlehq/core/telemetry';
+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 { reportStepFromCli } from './cli-onboarding.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,21 +15,24 @@ 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 { handleContext } from './cli/context-command.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 { handleGate, loadNamedFlows, resolveChangedFiles } from './cli/cli-flow-commands.js';
 import { RETICLE_DEFAULT_PORT, ReticleDir, ReticleEnv, devServersForProject, } from '@reticlehq/core';
 import { loadDotEnv } from '../telemetry/dev-repo.js';
 import { licenseKeyFromEnvFiles } from '../features/license/license-env.js';
 import { LICENSE_KEY_ENV } from '../features/license/license.js';
 import { createNodeFileSystem } from '../memory/project/fs/fs-port.js';
+import { localLinkOf, workspaceAppLinks } from './cli/status/workspace-links.js';
 import { affectedSavedFlows } from '../language/flows/change/flow-sources.js';
 import { availableUpdate } from './update/update-nudge.js';
 import { handleUpdate, handleRollback } from './cli/cli-update-commands.js';
+import { headlessByDefault } from './cli/daemon-start-options.js';
 import { startDaemon } from '../index.js';
-import { isCloudCommand, runCloudCommand } from './cli/cloud-cli.js';
+import { accountStatusFields, cmdLink, connectInstalls, isCloudCommand, runCloudCommand, } from './cli/cloud-cli.js';
 import { SERVER_VERSION } from './version/identity/server-version.js';
 import { log } from '../log.js';
 import { readPid, isAlive, removePid, spawnDaemon, discoverDaemonPort, writeDaemonRegistry, } from './daemon/daemon.js';
@@ -45,20 +48,46 @@ import { fetchStatus } from './daemon/binding/daemon-status-probe.js';
 import { handleDrive } from './cli/drive/drive-command.js';
 import { handleVerify } from './cli/cli-verify.js';
 import { runKill } from './cli/cli-kill.js';
-import { summarizeHunt } from '../judgement/hunt/hunt-report.js';
-import { runInit, buildNodeIo } from '@reticlehq/init';
+import { runInit, buildNodeIo, InitFailure } from '@reticlehq/init';
 import { continueAfterInit } from './setup/init/init-runtime.js';
+import { initFirstFlow } from './cli/try-command.js';
 import { handleDoctor } from './cli/cli-doctor.js';
 import { serverInitHost } from './setup/init/init-host.js';
 import { describeLicense } from '../features/license/license.js';
 import { isLikelyDevServerPort, devServerPortWarning, readProjectPort, readProjectId, workspacePortConflict, projectDirOf, } from './cli/ports/resolve/cli-port.js';
-import { nodeSpawner, readTextFile, reexecAtVersion, versionMatchNote, versionToMatch, } from './cli/launch/sdk-version-match.js';
+import { helpRunsAt, helpVersionNote, nodeSpawner, readTextFile, reexecAtVersion, versionMatchNote, versionToMatch, } from './cli/launch/sdk-version-match.js';
 import { DAEMON_INNER_COMMAND, PORT_FLAG, parseCliArgs, CLI_USAGE, dialsTheDaemon, } from './cli/cli-parse.js';
-import { handleFeedback, handleIdentify, handleTelemetry } from '../telemetry/feedback-cli.js';
+import { renderHelp } from './cli/cli-usage.js';
+import { RENAMED_COMMANDS, renamedCommandFor, renamedNote } from './cli/cli-parse-grammar.js';
+import { handleFeedback, handleTelemetry } from '../telemetry/feedback-cli.js';
 import { installDaemonTelemetry } from '../telemetry/daemon-telemetry.js';
 import { reportCliRun } from '../telemetry/cli-telemetry.js';
 // Re-exported so existing imports (and the CLI tests) keep resolving from '@/cli.js'.
 export { parseCliArgs, CLI_USAGE };
+/** Said when `connect` carries on past an init whose setup did not finish. */
+const MSG_CONNECT_AFTER_UNFINISHED_INIT = 'Setup did not finish (above) — signing in and linking anyway. Fix what it names, then run ' +
+    '`reticle init` again.';
+/**
+ * Said last, when the account is linked and the one thing left is installing a dependency. Exit 0:
+ * connect's job — signing in and linking — is done, and a non-zero exit read as a failed connect.
+ */
+export const MSG_CONNECTED_DEPS_PENDING = '⚠ Connected, but the dependency install did not finish (see above). Run the install it names, ' +
+    'then `reticle init` to wire the app.';
+/**
+ * How `reticle connect` exits: the cloud step's code when linking failed; 0 when it linked and setup
+ * finished or left only the dependency install (said in `note`); 1 when setup stopped for anything
+ * else. `initUnfinished` is why init's setup did not finish, or undefined when it did.
+ */
+export function connectExit(cloudCode, initUnfinished) {
+    if (0 !== cloudCode)
+        return { code: cloudCode };
+    if (initUnfinished === undefined)
+        return { code: 0 };
+    if (InitFailure.DEPENDENCY_INSTALL === initUnfinished) {
+        return { code: 0, note: MSG_CONNECTED_DEPS_PENDING };
+    }
+    return { code: 1 };
+}
 async function handleInit(parsed) {
     const cwd = process.cwd();
     // RETICLE_PORT counts as explicit, as it does for every other command: resolved once here, so the
@@ -78,7 +107,11 @@ 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);
+        },
+    }, cwd);
     const io = buildNodeIo(cwd, serverInitHost(), { stderr: true === parsed.json });
     const result = runInit({
         cwd,
@@ -97,28 +130,40 @@ async function handleInit(parsed) {
         deferOutcome: true,
         continuesToRuntime: true !== parsed.filesOnly && true !== parsed.dryRun,
     }, io);
-    await continueAfterInit({ ...parsed, port }, result, io, cwd);
+    await continueAfterInit({ ...parsed, port }, result, io, cwd, initFirstFlow);
+    return result;
 }
 // `serve`, `stop` and `restart` live in `cli/lifecycle/daemon-lifecycle.ts`: one idea, and the
 // largest group this file could give up without splitting something that belongs together.
 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`);
 }
 export async function handleStatus(port, json = false) {
-    const report = (fields) => reportStatus(fields, json);
+    // A broken session file must not cost the reader the rest of the status.
+    const account = await accountStatusFields().catch(() => ({}));
+    // At a workspace root that is no app of its own, each app and its link: "not linked" named none.
+    const linked = account.linkedProject;
+    if ('string' !== typeof linked && readProjectId(process.cwd()) === undefined)
+        Object.assign(account, {
+            workspaceApps: await workspaceAppLinks(process.cwd(), localLinkOf).catch(() => []),
+        });
+    const report = (fields) => reportStatus({ ...fields, ...account }, json);
     const pid = readPid(port);
     // Durable, so it survives the daemon idling out — which is the state `status` is most often run in.
     const projectId = readProjectId(process.cwd());
@@ -223,14 +268,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). */
@@ -262,42 +306,6 @@ async function handleAffected(files, since) {
         });
     }
 }
-/**
- * `reticle hunt <dir>` — aggregate crawl reports from many checkouts into one number.
- *
- * Detection already exists (`reticle_crawl`). This is the arithmetic that turns a pile of runs into
- * the claim worth making: over N already-merged, already-green changes, how many carried a candidate
- * false green? No control arm is needed, because those changes SHIPPED — the counterfactual is
- * already established, which is what makes this the cheapest credible evidence available.
- *
- * Each file in <dir> is one crawl result. Producing them is a shell loop over a commit range:
- * check out, boot the app, `reticle_crawl`, write the JSON here.
- */
-async function handleHunt(dir) {
-    try {
-        const fs = createNodeFileSystem();
-        const names = await fs.readdir(dir);
-        const runs = [];
-        for (const name of names.filter((n) => n.endsWith('.json'))) {
-            const raw = await fs.readFile(join(dir, name));
-            if (raw === undefined)
-                continue;
-            const parsed = JSON.parse(raw);
-            const report = parsed;
-            runs.push({
-                label: report.label ?? name.replace(/\.json$/, ''),
-                anomalies: report.anomalies ?? [],
-                ...(report.stepsRun === undefined ? {} : { stepsRun: report.stepsRun }),
-            });
-        }
-        log('reticle_hunt', { ...summarizeHunt(runs) });
-    }
-    catch (error) {
-        log('reticle_hunt_failed', {
-            error: error instanceof Error ? error.message : String(error),
-        });
-    }
-}
 /** Ensure a daemon is reachable on `port` (probe the real port; spawn + wait only if nothing's there). */
 function ensureDaemon(port) {
     return probePresence(port, { tcpOpen: probeDaemon, status: fetchStatus }).then(async (presence) => {
@@ -395,9 +403,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 +437,12 @@ 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: (repaint, link) => hudSignIn(repaint, undefined, undefined, link),
+        hudLink: (root) => cmdLink([], root, PlatformLinkVia.HUD),
+    };
     startDaemon(options)
         .then((server) => {
         log('reticle_daemon_ready', { port: parsed.port, pid: process.pid });
@@ -549,13 +560,15 @@ export function main() {
     // `version_skew`, and the unpinned `npx @reticlehq/server` every agent entry uses resolves the
     // LATEST major whatever the project installed. Hand the same arguments to the matching release and
     // step aside — it reports its own run. See cli/launch/sdk-version-match.ts.
-    const matchVersion = versionToMatch({
+    // One project lookup for both questions below: it reads config and walks the workspace.
+    const versionInput = {
         argv,
         cliVersion: SERVER_VERSION,
         env: process.env,
         projectDir: projectDirOf(process.cwd()),
         readFile: readTextFile,
-    });
+    };
+    const matchVersion = versionToMatch(versionInput);
     if (matchVersion !== undefined) {
         process.stderr.write(`${versionMatchNote(matchVersion, SERVER_VERSION)}\n`);
         reexecAtVersion(matchVersion, argv, process.env, {
@@ -565,6 +578,11 @@ export function main() {
         });
         return;
     }
+    // Help stays on this binary, so say which version the command it describes really runs at (#1378).
+    const helpVersion = helpRunsAt(versionInput);
+    if (helpVersion !== undefined) {
+        process.stdout.write(`${helpVersionNote(helpVersion, SERVER_VERSION)}\n\n`);
+    }
     // Every invocation passes through here — the single chokepoint for the "how often is it used / how
     // many distinct machines + projects" metrics. Fire-and-forget: a metric must never delay or fail a run.
     //
@@ -576,6 +594,13 @@ export function main() {
     // just the scale, which is the kind of error you cannot correct for after the fact. The daemon's
     // own lifecycle is already reported by `daemon_started` / `daemon_stopped`; it is not a CLI run.
     reportCliRun(argv);
+    // An old name still runs, for one release, and says once what it is called now. Not when the
+    // person only asked for help: that answer names the new command itself, on stdout.
+    const renamedTo = renamedCommandFor(argv);
+    if (renamedTo !== undefined) {
+        const colour = true === process.stderr.isTTY && process.env['NO_COLOR'] === undefined;
+        process.stderr.write(`${renamedNote(argv[0] ?? '', renamedTo, colour)}\n`);
+    }
     // Cloud subcommands (login/link/project/config/push) are a distinct family with their own async client;
     // handle them before the local typed parser so `reticle login` etc. work as one tool.
     if (isCloudCommand(argv[0])) {
@@ -584,17 +609,39 @@ export function main() {
         // `reticle link --help` used to run the command: it reached for the network and answered
         // `fetch failed` with exit 1, to somebody who had asked what the command was for.
         if (argv.some((arg) => '--help' === arg || '-h' === arg)) {
-            process.stdout.write(`${CLI_USAGE}\n`);
+            process.stdout.write(`${renderHelp(argv[0], RENAMED_COMMANDS)}\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.
+                // A setup that did not finish is said above and still fails the run, but no longer ends it
+                // before sign-in: the second identical run was the only way to get signed in.
+                let unfinished;
                 if (readProjectId(process.cwd()) === undefined) {
-                    await handleInit({ port: undefined, mcp: true, dryRun: false, install: true });
+                    const init = await handleInit({
+                        port: undefined,
+                        mcp: true,
+                        dryRun: false,
+                        install: connectInstalls(argv),
+                        keepGoing: true,
+                    });
+                    if (1 === process.exitCode) {
+                        // init hands no context over exactly when the dependency install failed (run.ts); its
+                        // outcome's own reason is unset when the files were all written and the app was not.
+                        unfinished =
+                            init.context === undefined && init.outcome !== undefined
+                                ? InitFailure.DEPENDENCY_INSTALL
+                                : (init.outcome?.reason ?? InitFailure.OTHER);
+                        process.exitCode = 0;
+                        process.stderr.write(`${MSG_CONNECT_AFTER_UNFINISHED_INIT}\n`);
+                    }
                 }
-                return runCloudCommand(argv);
+                const exit = connectExit(await runCloudCommand(argv), unfinished);
+                if (exit.note !== undefined)
+                    process.stderr.write(`${exit.note}\n`);
+                return exit.code;
             })()
                 .then((code) => process.exit(code))
                 .catch((cause) => {
@@ -635,7 +682,7 @@ export function main() {
     const defaultPort = envPort ?? projectPort ?? myDaemonPort ?? RETICLE_DEFAULT_PORT;
     // Headed by default; hidden only where there is no display to be headed on. A run nobody can see
     // is a run nobody trusts, and every "did it actually do anything?" cost a human round-trip.
-    const parsed = parseCliArgs(argv, defaultPort, process.env['CI'] !== undefined);
+    const parsed = parseCliArgs(argv, defaultPort, headlessByDefault(process.env, process.platform));
     // The refusal the line above promised. Printing it and carrying on let the default port answer
     // anyway, for whichever project's daemon owned it.
     if (portConflict !== undefined && dialsTheDaemon(parsed)) {
@@ -680,14 +727,15 @@ export function main() {
         case 'feedback':
             void handleFeedback(parsed.text, parsed.rating, parsed.bug, parsed.feedbackKind, parsed.agent);
             break;
-        case 'identify':
-            void handleIdentify(parsed);
-            break;
         case 'version':
             handleVersion();
             break;
         case 'help':
-            process.stdout.write(`${CLI_USAGE}\n`);
+            process.stdout.write(`${renderHelp(parsed.topic, RENAMED_COMMANDS)}\n`);
+            break;
+        case 'removed':
+            process.stderr.write(`${parsed.message}\n`);
+            process.exit(1);
             break;
         case 'doctor':
             void handleDoctor(parsed.port);
@@ -702,48 +750,26 @@ export function main() {
                 mcp: parsed.mcp,
             }, reportStepFromCli);
             break;
-        case 'tutorial':
-            // Reported for BOTH paths, and before either: a run is a tour too, and these two steps are
-            // about the tour being asked for, which is already true by the time we get here.
-            reportTutorialShown();
-            if (parsed.run) {
-                void runDemoTour({
-                    port: parsed.port,
-                    headless: parsed.headless,
-                    say: (line) => process.stdout.write(`${line}\n`),
-                }).then((result) => {
-                    process.exit(result.code);
-                });
-                break;
-            }
-            process.stdout.write(`${renderTutorial(parsed.audience)}\n`);
-            break;
         case 'open':
             handleOpen(parsed.port, parsed.url);
             break;
         case 'drive':
-            handleDrive(parsed);
+            handleDrive(parsed, readProjectId(process.cwd()));
             break;
         case 'verify':
             handleVerify(parsed);
             break;
-        case 'capsules':
-            void handleCapsules();
-            break;
         case 'affected':
             void handleAffected(parsed.files, parsed.since);
             break;
-        case 'hunt':
-            void handleHunt(parsed.dir);
-            break;
         case 'gate':
             void handleGate(parsed.files, parsed.since, parsed.hook, parsed.acceptCoverage);
             break;
         case 'report':
             void handleReport(parsed.session, parsed.hook);
             break;
-        case 'watch':
-            handleWatch();
+        case 'context':
+            void handleContext(parsed.session);
             break;
         case 'update':
             void handleUpdate();

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-resilience.js

@@ -8,7 +8,7 @@
  * per Node's guidance, so LOG a clear reason and exit cleanly; the next `reticle mcp` respawns a fresh
  * daemon, which beats crashing silently or limping along corrupt.
  */
-import { RETICLE_DEFAULT_PORT, TelemetryActor, TelemetryEventKind } from '@reticlehq/core';
+import { RETICLE_DEFAULT_PORT, TelemetryEventKind } from '@reticlehq/core';
 import { errorSkeleton, errorTypeOf, fingerprintCrash, MAX_REPORTED_FRAMES, reticleFrames, } from '../../telemetry/error-fingerprint.js';
 import { getSessionMetrics } from '../../telemetry/session-metrics.js';
 import { machineSnapshot } from '../../telemetry/machine-snapshot.js';
@@ -157,9 +157,9 @@ function reportCrash(kind, value) {
              * gone for months.
              */
             detach: true,
-            // A crash is ALWAYS reached through something the agent asked for — the daemon does nothing on
-            // its own — so attributing it to the agent is accurate rather than a guess.
-            actor: TelemetryActor.AGENT,
+            // No `actor`. The daemon does plenty on its own (timers, the bridge, a page's SDK, the update
+            // check), and the core contract says a crash is neither human nor agent: tagging every one
+            // `agent` put the whole crash count on the agent side of every actor split.
             crash: {
                 kind,
                 errorType,

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.
  *
@@ -98,6 +112,12 @@ export declare function splitBrainNote(myPort: number, elsewhere: readonly numbe
  * being inspected is the project's own.
  */
 export declare function wrongDaemonNote(inspectedPort: number, ownPort: number | undefined): string | undefined;
+/**
+ * Why the proxy serves `port` and not the `requested` one, in words a person can act on. It said
+ * "the requested port serves a different project" for every move, including the commonest one: this
+ * project's own daemon was already running elsewhere (a `connect` started it on the default).
+ */
+export declare function relocationReason(requested: number, port: number, projectId: string | undefined, home: string, alive: (pid: number) => boolean): string;
 /**
  * The port this agent's MCP proxy should serve, decided BEFORE the proxy starts.
  *
@@ -119,4 +139,6 @@ export declare function resolveMcpPort(preferred: number, projectId: string | un
     alive: (pid: number) => boolean;
     daemonPresent: (port: number) => Promise<boolean>;
     pickPort: (preferred: number) => Promise<number>;
-}): Promise<number>;
+}, 
+/** The port this project's `.reticle.json` names: the one its app dials. */
+own?: number): Promise<number>;

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, RETICLE_DEFAULT_PORT } 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.
  *
@@ -130,12 +156,17 @@ export function splitBrainNote(myPort, elsewhere) {
         return undefined;
     const listed = elsewhere.map((port) => `:${String(port)}`).join(', ');
     const first = elsewhere[0] ?? myPort;
+    // The agent moves, not the app (#1546). The daemon the app is on is a working session this agent
+    // did not start, and it may be a person's, another agent's or another project's. Stopping it was
+    // the first thing this used to say. It comes last now, with what it costs.
     return (`this project's app is connected to a DIFFERENT Reticle daemon (${listed}), while this one is ` +
         `on :${String(myPort)} — two daemons for one project, and the agent is attached to the empty ` +
-        'half. Nothing is wrong with the app or the wiring. Stop the other daemon with ' +
-        `\`reticle stop --port ${String(first)}\` and restart the dev server so the app rediscovers ` +
-        'this one, or start the agent and the dev server from the same project directory so both ' +
-        'resolve the same daemon.');
+        'half. Nothing is wrong with the app or the wiring. Move the agent to the app: set ' +
+        `${RETICLE_PORT_ENV}=${String(first)} in this MCP server's config, or launch the agent from the ` +
+        `project directory the dev server runs in, then restart the agent session. Leave :${String(first)} ` +
+        'running. Only if nothing else is using it, `reticle stop --port ' +
+        `${String(first)}\` and a dev server restart move the app here instead; that disconnects every ` +
+        'tab and agent on that daemon.');
 }
 /**
  * The other stance on the same split, for a command standing on the port that HAS the app.
@@ -158,6 +189,25 @@ export function wrongDaemonNote(inspectedPort, ownPort) {
         'be different processes, with both reporting healthy. Stop one of them and restart the dev ' +
         'server so everything lands on the same port.');
 }
+/**
+ * Why the proxy serves `port` and not the `requested` one, in words a person can act on. It said
+ * "the requested port serves a different project" for every move, including the commonest one: this
+ * project's own daemon was already running elsewhere (a `connect` started it on the default).
+ */
+export function relocationReason(requested, port, projectId, home, alive) {
+    const at = `:${String(port)}`;
+    if (projectId !== undefined && resolveDaemonForProject(projectId, home, alive) === port)
+        return (`this project's daemon is already running on ${at}, so the agent uses it instead of ` +
+            `:${String(requested)}. To use :${String(requested)}, run \`reticle stop --port ${String(port)}\` ` +
+            'and reconnect the agent.');
+    const holder = daemonProjectAt(requested, home);
+    if (holder !== undefined && holder !== projectId)
+        return (`:${String(requested)} serves project "${holder}", so this one is served on ${at}. Give this ` +
+            'project its own port (RETICLE_PORT, or `port` in its .reticle.json) and restart the agent.');
+    if (projectId === undefined)
+        return `no project here, and the one live project daemon is on ${at}: the agent uses it.`;
+    return `nothing usable answered on :${String(requested)}, so the agent is served on ${at}.`;
+}
 /**
  * The port this agent's MCP proxy should serve, decided BEFORE the proxy starts.
  *
@@ -175,13 +225,33 @@ export function wrongDaemonNote(inspectedPort, ownPort) {
  * silent adoption is what made every agent on a machine share one process, one identity and one
  * blast radius.
  */
-export async function resolveMcpPort(preferred, projectId, home, deps) {
+export async function resolveMcpPort(preferred, projectId, home, deps, 
+/** The port this project's `.reticle.json` names: the one its app dials. */
+own) {
     const mine = resolveDaemonForProject(projectId, home, deps.alive);
     if (mine !== undefined)
         return mine;
-    if (!(await deps.daemonPresent(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.
+        // Only on the DEFAULT port, which is the guess #1240 corrects. A port passed with --port or
+        // RETICLE_PORT is a choice: relocating it attached an unwired app to another project's daemon.
+        const projects = projectId === undefined && RETICLE_DEFAULT_PORT === preferred
+            ? projectDaemonsElsewhere(preferred, home, deps.alive)
+            : [];
+        return 1 === projects.length ? (projects[0]?.port ?? preferred) : preferred;
+    }
+    if (adoptable(daemonProjectAt(preferred, home), projectId))
         return preferred;
-    return adoptable(daemonProjectAt(preferred, home), projectId)
-        ? preferred
-        : deps.pickPort(preferred);
+    // Moved off a port another project holds: to the one this project's app dials, when it is free or
+    // already ours. A random port served nobody — the app kept dialling its own, and the agent was
+    // told "wired, and a dev server is listening, but no session".
+    if (own !== undefined && own !== preferred) {
+        if (!(await deps.daemonPresent(own)))
+            return own;
+        if (adoptable(daemonProjectAt(own, home), projectId))
+            return own;
+    }
+    return 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;