@reticlehq/server 3.5.0 → 3.7.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/known-regression.d.ts

@@ -0,0 +1,13 @@
+/** The `broken` list of a regression report, or undefined when the report has none. */
+export declare function brokenOf(report: unknown): unknown[] | undefined;
+/** What the platform said about regressions: the broken list, or that it refused the credential. */
+export interface KnownRegression {
+    broken?: unknown[];
+    /** The platform refused this project's key: said, and the gate fails closed on it. */
+    refused?: string;
+}
+/**
+ * Nothing when `reticleRoot` is not linked or the platform did not answer (offline is not a failure);
+ * `refused` when it answered and refused the key — a revoked key left CI green and silent.
+ */
+export declare function knownRegression(reticleRoot: string): Promise<KnownRegression>;

package/dist/command/cli/known-regression.js

@@ -0,0 +1,34 @@
+/**
+ * The flows the linked project's platform says passed before and are broken now — what
+ * `reticle runs regression` prints, read here so `reticle gate` can fail on it too.
+ *
+ * Its own module, not a call into `cloud-cli.ts`: the gate is on the library's import path, and the
+ * cloud CLI reaches the install-time surface the library must never load.
+ */
+import { homedir } from 'node:os';
+import { z } from 'zod';
+import { resolveProjectCloud } from '../../memory/cloud/cloud-config.js';
+import { createNodeFileSystem } from '../../memory/project/fs/fs-port.js';
+import { CredentialRefusedError, api } from './cloud-kit.js';
+const REGRESSION_PATH = '/v1/project/regression';
+/** The `broken` list of a regression report, or undefined when the report has none. */
+export function brokenOf(report) {
+    const parsed = z.object({ broken: z.array(z.unknown()) }).safeParse(report);
+    return parsed.success ? parsed.data.broken : undefined;
+}
+/**
+ * Nothing when `reticleRoot` is not linked or the platform did not answer (offline is not a failure);
+ * `refused` when it answered and refused the key — a revoked key left CI green and silent.
+ */
+export async function knownRegression(reticleRoot) {
+    try {
+        const cloud = await resolveProjectCloud(createNodeFileSystem(), reticleRoot, homedir(), process.env);
+        if (null === cloud.config)
+            return {};
+        const broken = brokenOf(await api('GET', `${cloud.config.url}${REGRESSION_PATH}`, cloud.config.apiKey));
+        return broken === undefined ? {} : { broken };
+    }
+    catch (error) {
+        return error instanceof CredentialRefusedError ? { refused: error.message } : {};
+    }
+}

package/dist/command/cli/launch/sdk-version-match.d.ts

@@ -36,6 +36,12 @@ export declare function installedSdkVersion(projectDir: string, readFile: (path:
 export declare function readTextFile(path: string): string | undefined;
 /** The one line a person sees on stderr when the CLI hands over — stdout belongs to the protocol. */
 export declare function versionMatchNote(sdkVersion: string, cliVersion: string): string;
+/**
+ * The line `--help` opens with when the command it describes would run at another version (#1378).
+ * Help stays on this binary, so without it the flags listed are this release's, and the re-run
+ * rejected the ones its older release never had, as an unknown parameter.
+ */
+export declare function helpVersionNote(sdkVersion: string, cliVersion: string): string;
 export interface VersionMatchInput {
     argv: readonly string[];
     cliVersion: string;
@@ -48,6 +54,12 @@ export interface VersionMatchInput {
  * environment are handed in.
  */
 export declare function versionToMatch(input: VersionMatchInput): string | undefined;
+/**
+ * The version the command asked about with `--help`, or `help <command>`, would actually run at.
+ * Undefined when help was not asked for, or when that command runs on this binary. Pure, like
+ * `versionToMatch`: it asks that same question about the command with the help request removed.
+ */
+export declare function helpRunsAt(input: VersionMatchInput): string | undefined;
 /** How to launch `npx --yes @reticlehq/server@<version> <args>` on this platform. */
 export declare function npxInvocation(version: string, args: readonly string[], on: string): {
     file: string;

package/dist/command/cli/launch/sdk-version-match.js

@@ -58,6 +58,8 @@ const KEEP_COMMANDS = new Set([
     '_daemon',
 ]);
 const KEEP_FLAGS = new Set(['--version', '-v', '--help', '-h']);
+const HELP_COMMAND = 'help';
+const HELP_FLAGS = new Set(['--help', '-h']);
 const SETUP_COMMAND = 'setup';
 const SETUP_INSTALL = 'install';
 /** A published release — not `workspace:*`, a link, or a tag npx could not pin. */
@@ -105,6 +107,17 @@ export function versionMatchNote(sdkVersion, cliVersion) {
     return (`This project's Reticle SDK is ${sdkVersion}; running ${SERVER_PACKAGE}@${sdkVersion} to match ` +
         `(this CLI is ${cliVersion}, a different major). Set ${VersionMatchEnv.OPT_OUT}=1 to keep this one.`);
 }
+/**
+ * The line `--help` opens with when the command it describes would run at another version (#1378).
+ * Help stays on this binary, so without it the flags listed are this release's, and the re-run
+ * rejected the ones its older release never had, as an unknown parameter.
+ */
+export function helpVersionNote(sdkVersion, cliVersion) {
+    return (`This help describes ${SERVER_PACKAGE} ${cliVersion}, but in this project the command runs at ` +
+        `${SERVER_PACKAGE}@${sdkVersion} to match its SDK, which may not take every flag listed here. ` +
+        `Run npx ${SERVER_PACKAGE}@${sdkVersion} <command> --help for that version's help, or set ` +
+        `${VersionMatchEnv.OPT_OUT}=1 to run this one.`);
+}
 /** Did the person name a version on the npx line (`npx @reticlehq/server@<version> …`)? */
 function pinnedOnNpxLine(spec) {
     if (spec === undefined || !spec.startsWith(`${SERVER_PACKAGE}@`))
@@ -141,6 +154,18 @@ export function versionToMatch(input) {
         return undefined;
     return sdkMajor === majorOf(input.cliVersion) ? undefined : sdk;
 }
+/**
+ * The version the command asked about with `--help`, or `help <command>`, would actually run at.
+ * Undefined when help was not asked for, or when that command runs on this binary. Pure, like
+ * `versionToMatch`: it asks that same question about the command with the help request removed.
+ */
+export function helpRunsAt(input) {
+    const viaCommand = HELP_COMMAND === input.argv[0];
+    if (!viaCommand && !input.argv.some((arg) => HELP_FLAGS.has(arg)))
+        return undefined;
+    const asked = (viaCommand ? input.argv.slice(1) : input.argv).filter((arg) => !HELP_FLAGS.has(arg));
+    return versionToMatch({ ...input, argv: asked });
+}
 /** How to launch `npx --yes @reticlehq/server@<version> <args>` on this platform. */
 export function npxInvocation(version, args, on) {
     const argv = [NPX_YES, `${SERVER_PACKAGE}@${version}`, ...args];

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';
@@ -121,8 +121,17 @@ export function handleStop(port, quiet) {
     const pid = readPid(port);
     if (null === pid || !isAlive(pid)) {
         removePid(port);
-        if (!quiet)
-            log('reticle_daemon_not_running', { port });
+        // No pid on record is not "not running": a daemon whose pid file vanished still answers its
+        // port, and `kill` finds the listener and confirms it is Reticle's before signalling it.
+        void fetchStatus(port).then(async (status) => {
+            if (status !== undefined) {
+                if (!(await runKill(port, false)))
+                    process.exit(1);
+                return;
+            }
+            if (!quiet)
+                log('reticle_daemon_not_running', { port });
+        });
         return;
     }
     process.kill(pid, 'SIGTERM');
@@ -168,6 +177,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/mcp-command.d.ts

@@ -7,6 +7,12 @@
  * talks to for the rest of its life — and the port resolution at the top is the fix for agents on
  * different projects silently sharing one daemon, one identity and one blast radius.
  */
+/**
+ * Whether the daemon this proxy starts hides its browser. A daemon on a port nobody chose — the
+ * requested one served another project, so this one was moved — was opening a visible browser the
+ * person never asked for, on a port nothing records. Only the requested port gets the default.
+ */
+export declare function spawnsHeadless(headless: boolean, requested: number, resolved: number): boolean;
 /**
  * MCP proxy mode: ensures the daemon is running, then bridges Claude Code's
  * stdin/stdout to the daemon's SSE endpoint. This is the recommended way to

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

@@ -12,8 +12,8 @@ import { isAlive, spawnDaemon, reticleStateHome } from '../daemon/daemon.js';
 import { PortPresence, probePresence, presenceIsUsable, describePresence, } from '../daemon/binding/port-presence.js';
 import { waitForDaemon, startMcpProxy, probeDaemon, proxyLog, setProxyLogPort, } from '../../surface/mcp/mcp-proxy.js';
 import { installProxyResilience } from '../daemon/daemon-resilience.js';
-import { readProjectId } from './ports/resolve/cli-port.js';
-import { resolveMcpPort, daemonProjectAt } from '../daemon/daemon-resolve.js';
+import { readProjectId, readProjectPort } from './ports/resolve/cli-port.js';
+import { resolveMcpPort, daemonProjectAt, relocationReason, } from '../daemon/daemon-resolve.js';
 import { daemonSpawnArgs } from './daemon-start-options.js';
 import { WakeAction, decideWake } from '../daemon/wake-decision.js';
 import { pickDaemonPortToBind } from '../daemon/binding/free-port.js';
@@ -23,6 +23,14 @@ import { ReticleEnv } from '@reticlehq/core';
 import { agentIo } from '../setup/agent-io.js';
 import { SERVER_VERSION } from '../version/identity/server-version.js';
 import { homedir } from 'node:os';
+/**
+ * Whether the daemon this proxy starts hides its browser. A daemon on a port nobody chose — the
+ * requested one served another project, so this one was moved — was opening a visible browser the
+ * person never asked for, on a port nothing records. Only the requested port gets the default.
+ */
+export function spawnsHeadless(headless, requested, resolved) {
+    return headless || requested !== resolved;
+}
 /**
  * MCP proxy mode: ensures the daemon is running, then bridges Claude Code's
  * stdin/stdout to the daemon's SSE endpoint. This is the recommended way to
@@ -64,12 +72,12 @@ export async function handleMcp(opts) {
         alive: isAlive,
         daemonPresent: async (p) => presenceIsUsable(await probePresence(p, { tcpOpen: probeDaemon, status: fetchStatus })),
         pickPort: (p) => pickDaemonPortToBind(p),
-    });
+    }, readProjectPort(process.cwd()));
     if (port !== opts.port) {
         log('reticle_mcp_port_relocated', {
             requested: opts.port,
             port,
-            reason: 'the requested port serves a different project',
+            reason: relocationReason(opts.port, port, projectId, reticleStateHome(), isAlive),
         });
     }
     // The proxy IS the MCP server the editor launched. Nothing respawns it, so an uncaught throw here
@@ -119,7 +127,7 @@ export async function handleMcp(opts) {
         }
         const daemonArgs = daemonSpawnArgs({
             port,
-            headless,
+            headless: spawnsHeadless(headless, opts.port, port),
             http,
             ...(driveUrl !== undefined ? { driveUrl } : {}),
             ...(httpPort !== undefined ? { httpPort } : {}),

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

@@ -83,7 +83,7 @@ ourPid) {
     // Naming the command matters more than naming the process. "Stop that process" describes an
     // outcome and leaves the reader to invent a route to it, and the route they invent is the `-ti`
     // pipeline that takes their agent's proxy down with the holder.
-    const tail = 'a daemon cannot bind it. Free it with `reticle kill --force` (it signals the listener only, ' +
+    const tail = 'a daemon cannot bind it. Free it with `reticle restart --force` (it signals the listener only, ' +
         "never the agent's mcp proxy), or run Reticle on a different port (`--port`), then retry.";
     if (null === holder) {
         /**
@@ -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/project-name.d.ts

@@ -11,6 +11,7 @@
  * A repo already knows its name: the directory it lives in. That is not a guess, it is the name its
  * owner chose and the one they will look for in a project list.
  */
+import { z } from 'zod';
 /** The id used when a directory name yields nothing usable — the historical behaviour, unchanged. */
 export declare const DEFAULT_PROJECT_ID = "default";
 /**
@@ -27,4 +28,31 @@ export declare const slugifyProjectName: (raw: string) => string;
  * do to rotate a key or repoint an environment — must land in that same project or the history
  * silently splits in two, which is worse than the shared-bucket problem this fixes.
  */
-export declare const defaultProjectFor: (cwdBasename: string, existingProjectId: string | undefined) => string;
+export declare const defaultProjectFor: (cwdBasename: string, existingProjectId: string | undefined, 
+/** The `projectId` `init` wrote into `.reticle.json`, when there is one. */
+localProjectId?: string) => string;
+export declare const CreatedProjectSchema: z.ZodObject<{
+    projectId: z.ZodString;
+    name: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    projectId: string;
+}, {
+    name: string;
+    projectId: string;
+}>;
+/** ` in workspace "<name>"`, or nothing when no name is known. */
+export declare const inWorkspace: (name: string | undefined) => string;
+/**
+ * Which repository, and which folder in it, a project folder is: a hash of the `origin` remote and
+ * the folder's path inside the checkout, so every clone of one app agrees and two different apps
+ * both named `web` do not. Undefined outside git or with no remote. Neither leaves the machine.
+ */
+export declare function repoIdentity(dir: string): string | undefined;
+export declare function resolveProjectId(url: string, token: string, wanted: string, workspace?: string, repo?: string, 
+/**
+ * The id `init` wrote into `.reticle.json`, for a project created by default: the platform is
+ * asked to keep it, so the folder and the dashboard name one project by one id. A platform that
+ * does not know the field ignores it and answers with its own, which is what gets linked.
+ */
+localId?: string): Promise<string>;

package/dist/command/cli/project-name.js

@@ -11,6 +11,12 @@
  * A repo already knows its name: the directory it lives in. That is not a guess, it is the name its
  * owner chose and the one they will look for in a project list.
  */
+import { createHash } from 'node:crypto';
+import { execFileSync } from 'node:child_process';
+import { relative } from 'node:path';
+import { z } from 'zod';
+import { PROJECT_ID_HASH_LENGTH } from '@reticlehq/core';
+import { CredentialRefusedError, api, hint } from './cloud-kit.js';
 /** Cap the slug so a deep or oddly-named checkout cannot produce an unreadable project id. */
 const MAX_SLUG = 48;
 /** The id used when a directory name yields nothing usable — the historical behaviour, unchanged. */
@@ -37,8 +43,107 @@ export const slugifyProjectName = (raw) => {
  * do to rotate a key or repoint an environment — must land in that same project or the history
  * silently splits in two, which is worse than the shared-bucket problem this fixes.
  */
-export const defaultProjectFor = (cwdBasename, existingProjectId) => {
+export const defaultProjectFor = (cwdBasename, existingProjectId, 
+/** The `projectId` `init` wrote into `.reticle.json`, when there is one. */
+localProjectId) => {
     if (existingProjectId !== undefined && existingProjectId.length > 0)
         return existingProjectId;
-    return slugifyProjectName(cwdBasename);
+    // The name part of `init`'s `<name>-<hash>`, else the id as written: a name the owner chose.
+    const named = localProjectId === undefined || 0 === localProjectId.length
+        ? undefined
+        : (nameOfLocalId(localProjectId) ?? localProjectId);
+    return slugifyProjectName(named ?? cwdBasename);
 };
+/** `init`'s id is the app's name and a short hash of where it lives: `nina-todo-f96721e8`. */
+const LOCAL_ID = new RegExp(`^(.+)-[0-9a-f]{${String(PROJECT_ID_HASH_LENGTH)}}$`);
+/**
+ * The name part of the id `init` wrote. One project carried two names: `.reticle.json` said
+ * `nina-todo-f96721e8` (from the package) while the dashboard said `app` (the folder), so the person
+ * looked for one and the list showed the other. The dashboard now takes the name `init` wrote.
+ */
+function nameOfLocalId(localProjectId) {
+    return LOCAL_ID.exec(localProjectId)?.[1];
+}
+export const CreatedProjectSchema = z.object({ projectId: z.string(), name: z.string() });
+const ProjectsListSchema = z.object({
+    projects: z.array(z.object({ projectId: z.string(), name: z.string(), repo: z.string().optional() })),
+});
+/** ` in workspace "<name>"`, or nothing when no name is known. */
+export const inWorkspace = (name) => name === undefined || 0 === name.length ? '' : ` in workspace "${name}"`;
+/** Characters of the repository identity: enough to tell repositories apart, nothing to read. */
+const REPO_ID_CHARS = 16;
+/**
+ * Which repository, and which folder in it, a project folder is: a hash of the `origin` remote and
+ * the folder's path inside the checkout, so every clone of one app agrees and two different apps
+ * both named `web` do not. Undefined outside git or with no remote. Neither leaves the machine.
+ */
+export function repoIdentity(dir) {
+    try {
+        const git = (...args) => execFileSync('git', args, {
+            cwd: dir,
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+        }).trim();
+        const remote = git('config', '--get', 'remote.origin.url')
+            .replace(/\.git$/, '')
+            .replace(/^[a-z+]+:\/\/|^[^@]+@/i, '')
+            .replace(':', '/')
+            .toLowerCase();
+        if (0 === remote.length)
+            return undefined;
+        const inside = relative(git('rev-parse', '--show-toplevel'), dir).split('\\').join('/');
+        return createHash('sha256')
+            .update(`${remote}\u0000${inside}`)
+            .digest('hex')
+            .slice(0, REPO_ID_CHARS);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The id for the project the caller named, creating it if it does not exist yet — and saying so,
+ * in which workspace. A project of that NAME made for another repository is not reused: two apps
+ * whose package is `web` shared one dashboard project. A project with no recorded repository, or an
+ * id named outright, is reused as before.
+ */
+/** Projects named when creating one was refused. */
+const MAX_NAMED = 5;
+export async function resolveProjectId(url, token, wanted, workspace, repo, 
+/**
+ * The id `init` wrote into `.reticle.json`, for a project created by default: the platform is
+ * asked to keep it, so the folder and the dashboard name one project by one id. A platform that
+ * does not know the field ignores it and answers with its own, which is what gets linked.
+ */
+localId) {
+    const { projects } = ProjectsListSchema.parse(await api('GET', `${url}/v1/projects`, token));
+    const lc = wanted.toLowerCase();
+    const holding = localId === undefined ? undefined : projects.find((p) => p.projectId === localId);
+    if (holding !== undefined)
+        return holding.projectId;
+    const match = projects.find((p) => p.projectId === wanted ||
+        (p.name.toLowerCase() === lc &&
+            (repo === undefined || p.repo === undefined || p.repo === repo)));
+    if (match !== undefined)
+        return match.projectId;
+    let answer;
+    try {
+        answer = await api('POST', `${url}/v1/projects`, token, {
+            name: wanted,
+            ...(repo === undefined ? {} : { repo }),
+            ...(localId === undefined ? {} : { projectId: localId }),
+        });
+    }
+    catch (error) {
+        // Refused to create one (a contributor): the platform's words, then the step that works.
+        if (error instanceof CredentialRefusedError ||
+            !(error instanceof Error) ||
+            0 === projects.length)
+            throw error;
+        const names = projects.map((p) => p.name).slice(0, MAX_NAMED);
+        throw new Error(`${error.message}\nTo link one that exists: ${names.map((n) => `\`reticle connect --project ${n}\``).join(', ')}`);
+    }
+    const created = CreatedProjectSchema.parse(answer);
+    hint(`created project "${wanted}" (${created.projectId})${inWorkspace(workspace)} — it did not exist yet`);
+    return created.projectId;
+}

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

@@ -14,7 +14,23 @@ import type { OnboardingStep } from '@reticlehq/core/telemetry';
  * so the entry point supplies it and every layer below stays a function of its arguments.
  */
 export type StepReporter = (step: OnboardingStep) => void;
-export declare function handleSetupMcp(reportStep: StepReporter, standalone?: boolean): void;
+/** How many coding agents on this machine have Reticle's tools after this run. */
+export declare function handleSetupMcp(reportStep: StepReporter, standalone?: boolean): number;
+/**
+ * The one line the launchers read and strip: what they cannot know and the next steps depend on.
+ *
+ * The launchers own the closing words (served from main, so wording changes on merge) and used to
+ * print "restart your coding agent" to a machine with none, and "cd your-app" to somebody already
+ * standing in it. An older launcher shows this line as is; a launcher reading an older CLI finds no
+ * line and keeps its generic wording, so neither half has to ship first.
+ */
+export declare const INSTALL_RESULT_PREFIX = "RETICLE_INSTALL";
+/** Whether the folder the installer ran in is an app: `init` runs here, or after a `cd`. */
+export declare const InstallAppHere: {
+    readonly HERE: "here";
+    readonly NONE: "none";
+};
+export declare function installResultLine(agents: number, cwd: string): string;
 /**
  * `reticle setup install` — the Node half of the one-line installer.
  *