@reticlehq/server 3.6.0 → 3.7.0

package/dist/command/cli/verify-results.js

@@ -0,0 +1,29 @@
+/**
+ * `reticle verify --results-json <file>`: the run, one line per journey, for a machine to read.
+ *
+ * The rendered report is for a person, and a CI step that has to post per-journey verdicts somewhere
+ * else would otherwise scrape it. Three words only, the engine's own: a skipped flow is `unknown`,
+ * never rounded up to `yes`, and the run is `yes` only when every journey is.
+ */
+import { RunFlowStatus, VerdictStatus, Verified, } from '@reticlehq/core';
+function journeyVerdict(status) {
+    if (RunFlowStatus.FAIL === status)
+        return Verified.NO;
+    // A heal is consequence-verified before it is reported, so it proves as much as a pass.
+    if (RunFlowStatus.PASS === status || RunFlowStatus.HEALED === status)
+        return Verified.YES;
+    return Verified.UNKNOWN;
+}
+export function verifyResults(run) {
+    const results = run.flows.map((flow) => ({
+        journey: flow.name,
+        verdict: journeyVerdict(flow.status),
+        ...(flow.failureReason === undefined ? {} : { reason: flow.failureReason }),
+    }));
+    const verdict = results.some((r) => Verified.NO === r.verdict)
+        ? Verified.NO
+        : VerdictStatus.PASS === run.verdict.status && results.every((r) => Verified.YES === r.verdict)
+            ? Verified.YES
+            : Verified.UNKNOWN;
+    return { verdict, results };
+}

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

@@ -8,14 +8,3 @@ import type { OnboardingStep } from '@reticlehq/core/telemetry';
  * reporter is built here and handed down to every command that needs one.
  */
 export declare const reportStepFromCli: (step: OnboardingStep) => void;
-/**
- * The two ONBOARD steps `reticle tutorial` can honestly answer.
- *
- * Asking for the tour is a fact here, and so is having been shown what Reticle is. Whether the
- * reader then looked, acted or proved is not — even on `tutorial --run`, which drives the demo: those
- * three are reported by the daemon at the first look / act / verdict it actually witnesses, through
- * the dispatch chokepoint, because that is the only place they are observations rather than claims.
- * Reporting them from here would turn "the tour reached step four" into "somebody verified something",
- * which is the same substitution the fourth step of the tour exists to warn about.
- */
-export declare function reportTutorialShown(): void;

package/dist/command/cli-onboarding.js

@@ -1,5 +1,4 @@
 import { reportOnboardingStep } from '../telemetry/onboarding-funnel.js';
-import { tutorialShownSteps } from './cli/tutorial.js';
 /**
  * The CLI's half of the setup funnel.
  *
@@ -11,17 +10,3 @@ import { tutorialShownSteps } from './cli/tutorial.js';
 export const reportStepFromCli = (step) => {
     void reportOnboardingStep(step);
 };
-/**
- * The two ONBOARD steps `reticle tutorial` can honestly answer.
- *
- * Asking for the tour is a fact here, and so is having been shown what Reticle is. Whether the
- * reader then looked, acted or proved is not — even on `tutorial --run`, which drives the demo: those
- * three are reported by the daemon at the first look / act / verdict it actually witnesses, through
- * the dispatch chokepoint, because that is the only place they are observations rather than claims.
- * Reporting them from here would turn "the tour reached step four" into "somebody verified something",
- * which is the same substitution the fourth step of the tour exists to warn about.
- */
-export function reportTutorialShown() {
-    for (const step of tutorialShownSteps())
-        reportStepFromCli(step);
-}

package/dist/command/cli.d.ts

@@ -2,6 +2,20 @@
 import { parseCliArgs, CLI_USAGE } from './cli/cli-parse.js';
 export { parseCliArgs, CLI_USAGE };
 export type { CliResult } from './cli/cli-parse.js';
+/**
+ * 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 declare const MSG_CONNECTED_DEPS_PENDING: string;
+/**
+ * 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 declare function connectExit(cloudCode: number, initUnfinished: string | undefined): {
+    code: number;
+    note?: string;
+};
 /**
  * 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

package/dist/command/cli.js

@@ -1,9 +1,8 @@
 #!/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, openLaunchFailureNote } from './cli/answers/open-note.js';
 import { realpathSync } from 'node:fs';
@@ -16,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 { handleContext } from './cli/context-command.js';
 import { daemonProjectAt, readDaemonRegistry, resolveDaemonForProject, } from './daemon/daemon-resolve.js';
 import { pickDaemonPortToBind } from './daemon/binding/free-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';
@@ -46,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
@@ -83,7 +111,7 @@ async function handleInit(parsed) {
             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,
@@ -102,7 +130,8 @@ 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.
@@ -126,7 +155,15 @@ export function reportStatus(fields, json) {
     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());
@@ -269,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) => {
@@ -437,7 +438,11 @@ function handleOpen(requestedPort, url) {
 }
 function handleDaemonInner(parsed) {
     // The daemon the CLI starts is the one that can sign in for the panel: it owns ~/.reticle.
-    const options = { ...daemonStartOptions(parsed), hudSignIn };
+    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 });
@@ -555,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, {
@@ -571,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.
     //
@@ -582,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])) {
@@ -590,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) => {
@@ -641,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)) {
@@ -686,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);
@@ -708,22 +750,6 @@ 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;
@@ -733,23 +759,17 @@ export function main() {
         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/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

@@ -112,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.
  *
@@ -133,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,7 +19,7 @@
 import { readdirSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { DaemonRegistryEntrySchema, daemonRegistryPort, pickDaemonPort, } from '@reticlehq/core/artifacts';
-import { ReticleEnv } from '@reticlehq/core';
+import { ReticleEnv, RETICLE_DEFAULT_PORT } from '@reticlehq/core';
 const RETICLE_PORT_ENV = ReticleEnv.PORT;
 /**
  * Every well-formed registry entry in `home`.
@@ -156,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.
@@ -184,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.
  *
@@ -201,7 +225,9 @@ 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;
@@ -209,10 +235,23 @@ export async function resolveMcpPort(preferred, projectId, home, deps) {
         // 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) : [];
+        // 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;
     }
-    return adoptable(daemonProjectAt(preferred, home), projectId)
-        ? preferred
-        : deps.pickPort(preferred);
+    if (adoptable(daemonProjectAt(preferred, home), projectId))
+        return 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/bringup/bridge-port.d.ts

@@ -12,4 +12,6 @@
  */
 import { PortPresence } from '../../daemon/binding/port-presence.js';
 /** The refusal to print, or undefined when the port is usable. */
-export declare function bridgeOccupied(presence: PortPresence, port: number): string | undefined;
+export declare function bridgeOccupied(presence: PortPresence, port: number, freePort?: number): string | undefined;
+/** The first port after `port` that nothing answers on, or undefined within the scan. */
+export declare function freePortAfter(port: number, isOpen: (port: number) => Promise<boolean>): Promise<number | undefined>;

package/dist/command/setup/bringup/bridge-port.js

@@ -12,13 +12,23 @@
  */
 import { PortPresence } from '../../daemon/binding/port-presence.js';
 /** The refusal to print, or undefined when the port is usable. */
-export function bridgeOccupied(presence, port) {
+export function bridgeOccupied(presence, port, freePort) {
     // DAEMON is the ordinary case — that is the daemon init is about to use. FREE is fine too: one
     // gets started. Only a stranger is fatal.
     if (PortPresence.FOREIGN !== presence)
         return undefined;
     return (`port ${String(port)} is held by something that is not a Reticle daemon. That is the bridge — ` +
         'the channel between the daemon and the SDK in your page — so no session can ever appear while ' +
-        'it is occupied, however correct the wiring is. Free it, or re-run with --port <n> and set the ' +
-        'same port in .reticle.json.');
+        'it is occupied, however correct the wiring is. Free it, or re-run on another port (init moves ' +
+        `the config and the page with it): reticle init --port ${freePort === undefined ? '<n>' : String(freePort)}`);
+}
+/** How many ports past the held one are tried before giving up on a suggestion. */
+const FREE_PORT_SCAN = 20;
+/** The first port after `port` that nothing answers on, or undefined within the scan. */
+export async function freePortAfter(port, isOpen) {
+    for (let candidate = port + 1; candidate <= port + FREE_PORT_SCAN; candidate++) {
+        if (!(await isOpen(candidate)))
+            return candidate;
+    }
+    return undefined;
 }

package/dist/command/setup/bringup/dev-server-log-cap.js

@@ -101,6 +101,8 @@ function main(argv) {
     const child = spawn(command, {
         shell: true,
         stdio: ['ignore', 'pipe', 'pipe'],
+        // This supervisor runs detached with no console on Windows, so the shell would open a window.
+        windowsHide: true,
         env: process.env,
     });
     child.stdout.on('data', (chunk) => log.write(chunk));