@reticlehq/server 3.6.0 → 3.7.0

package/dist/command/cli/daemon-start-options.d.ts

@@ -30,4 +30,7 @@ export declare function daemonStartOptions(parsed: DaemonFlags): StartOptions;
  * idea: that headless belongs to the drive URL. It belongs to the pool, which exists either way.
  */
 export declare function daemonSpawnArgs(parsed: DaemonFlags): string[];
+/** Set (to anything but '', '0' or 'false') to hide every browser Reticle opens. Batteries set it. */
+export declare const HEADLESS_ENV = "RETICLE_HEADLESS";
+export declare function headlessByDefault(env: Readonly<Record<string, string | undefined>>, platform: string): boolean;
 export {};

package/dist/command/cli/daemon-start-options.js

@@ -1,4 +1,4 @@
-import { DAEMON_INNER_COMMAND, DRIVE_FLAG, HEADED_FLAG, HTTP_FLAG, HTTP_PORT_FLAG, HTTP_TOKEN_FLAG, PORT_FLAG, } from './cli-parse.js';
+import { DAEMON_INNER_COMMAND, DRIVE_FLAG, HEADED_FLAG, HEADLESS_FLAG, HTTP_FLAG, HTTP_PORT_FLAG, HTTP_TOKEN_FLAG, PORT_FLAG, } from './cli-parse.js';
 export function daemonStartOptions(parsed) {
     return {
         port: parsed.port,
@@ -25,8 +25,9 @@ export function daemonSpawnArgs(parsed) {
     const args = [DAEMON_INNER_COMMAND, PORT_FLAG, String(parsed.port)];
     if (parsed.driveUrl !== undefined)
         args.push(DRIVE_FLAG, parsed.driveUrl);
-    if (!parsed.headless)
-        args.push(HEADED_FLAG);
+    // Said either way: the child decides its own default from its environment, so a parent that
+    // resolved hidden must say so rather than leave it to a default that may differ.
+    args.push(parsed.headless ? HEADLESS_FLAG : HEADED_FLAG);
     if (parsed.http) {
         args.push(HTTP_FLAG);
         if (parsed.httpPort !== undefined)
@@ -36,3 +37,23 @@ export function daemonSpawnArgs(parsed) {
     }
     return args;
 }
+/*
+ * Whether a browser a daemon opens is shown or hidden when no flag says. Here because both callers that
+ * decide it -- `cli.ts` and init's bring-up -- already start daemons through this module.
+ */
+/** Set (to anything but '', '0' or 'false') to hide every browser Reticle opens. Batteries set it. */
+export const HEADLESS_ENV = 'RETICLE_HEADLESS';
+/**
+ * Whether a browser Reticle opens is hidden when no flag says. Shown by default, for every command:
+ * the pool behind `serve`/`mcp` used to be hidden on the theory that nobody watches batch work, and
+ * from the field that was a person watching an agent drive their app and seeing nothing happen.
+ * Hidden where showing is impossible or unwanted: CI, the test batteries, and a Linux machine with
+ * no display server, where a headed launch fails instead of showing anything.
+ */
+const OFF = new Set(['', '0', 'false']);
+export function headlessByDefault(env, platform) {
+    const forced = env[HEADLESS_ENV];
+    if (env['CI'] !== undefined || (forced !== undefined && !OFF.has(forced)))
+        return true;
+    return ('linux' === platform && env['DISPLAY'] === undefined && env['WAYLAND_DISPLAY'] === undefined);
+}

package/dist/command/cli/doctor/doctor-coverage-line.d.ts

@@ -0,0 +1,2 @@
+/** The rows for every tab the status names; nothing when it names none. Never throws. */
+export declare function coverageLines(status: unknown): string[];

package/dist/command/cli/doctor/doctor-coverage-line.js

@@ -0,0 +1,47 @@
+/**
+ * `doctor`'s coverage rows: what Reticle sees in each connected app, read from the daemon's
+ * `/status` (`coverage`), and — once a verdict recorded a gap — the prompt to hand a coding agent.
+ * A terminal cannot copy, so the prompt is printed whole, ready to paste.
+ */
+import { DoctorRow, doctorRow } from './doctor-rows.js';
+const capabilitiesIn = (value) => Array.isArray(value)
+    ? value.flatMap((item) => {
+        const name = 'object' === typeof item && null !== item
+            ? item['capability']
+            : item;
+        return 'string' === typeof name ? [name] : [];
+    })
+    : [];
+/** The rows for every tab the status names; nothing when it names none. Never throws. */
+export function coverageLines(status) {
+    const list = 'object' === typeof status && null !== status
+        ? status['coverage']
+        : undefined;
+    if (!Array.isArray(list))
+        return [];
+    return list.flatMap((raw) => {
+        const tab = ('object' === typeof raw && null !== raw ? raw : {});
+        if ('number' !== typeof tab.covered || 'number' !== typeof tab.total)
+            return [];
+        const missing = capabilitiesIn(tab.missing);
+        const notSeen = capabilitiesIn(tab.notSeenYet);
+        const parts = [
+            `${String(tab.covered)}/${String(tab.total)}${'string' === typeof tab.url ? ` at ${tab.url}` : ''}`,
+            ...(0 === missing.length ? [] : [`missing: ${missing.join(', ')}`]),
+            ...(0 === notSeen.length ? [] : [`not seen yet: ${notSeen.join(', ')}`]),
+        ];
+        const prompt = 'string' === typeof tab.prompt
+            ? [
+                '    prompt for your coding agent (copy it):',
+                ...tab.prompt.split('\n').map((line) => `      ${line}`),
+            ]
+            : [];
+        const gate = tab.harnessGate;
+        const reason = 'object' === typeof gate && null !== gate
+            ? gate['reason']
+            : undefined;
+        // The Harness gate, in the sentence a refused drive says.
+        const locked = 'string' === typeof reason ? [`    ${reason}`] : [];
+        return [doctorRow(DoctorRow.COVERAGE, parts.join(' — ')), ...locked, ...prompt];
+    });
+}

package/dist/command/cli/doctor/doctor-project-line.d.ts

@@ -1,15 +1,3 @@
-/**
- * Whether `init` has wired THIS directory — the check `doctor` was missing.
- *
- * `doctor` already read `.reticle.json` for the port, so it knew whether the file existed and never
- * said so. In a project where `init` has not run the checklist came out clean: node fine, chromium
- * fine, a daemon that starts on demand, a bridge port. Every line true, and the app carrying no SDK
- * went unremarked — which is exactly the state that produces "the tools are here and nothing ever
- * verifies", and the state `doctor` is run to explain.
- *
- * Registering the MCP server and instrumenting the app are two different halves of the install, and
- * more than one route does the first without the second.
- */
 interface ProjectWiringFacts {
     /** The id from `.reticle.json`, or undefined when there is no config here. */
     projectId: string | undefined;

package/dist/command/cli/doctor/doctor-project-line.js

@@ -10,6 +10,7 @@
  * Registering the MCP server and instrumenting the app are two different halves of the install, and
  * more than one route does the first without the second.
  */
+import { DoctorRow, doctorRow } from './doctor-rows.js';
 /**
  * One line, in the same shape as the checks beside it.
  *
@@ -20,16 +21,16 @@
  */
 export function projectWiringLine(facts) {
     if (facts.projectId !== undefined) {
-        return `  project      ✓ wired here (${facts.projectId})`;
+        return doctorRow(DoctorRow.PROJECT, `✓ wired here (${facts.projectId})`);
     }
     if (facts.previouslyConnected) {
-        return '  project      ✓ an app has connected here before, so it is wired (no .reticle.json — a build plugin can wire an app without one)';
+        return doctorRow(DoctorRow.PROJECT, '✓ an app has connected here before, so it is wired (no .reticle.json — a build plugin can wire an app without one)');
     }
     if (true === facts.configPresent) {
-        return ('  project      ✗ .reticle.json is here but carries no readable projectId — a corrupt or ' +
+        return doctorRow(DoctorRow.PROJECT, '✗ .reticle.json is here but carries no readable projectId — a corrupt or ' +
             'hand-edited config reads the same as no config, and points this project at the default ' +
             'daemon. Run `npx @reticlehq/server init` in the app directory to rewrite it');
     }
-    return ('  project      ✗ no .reticle.json here and nothing has ever connected — the tools may be ' +
+    return doctorRow(DoctorRow.PROJECT, '✗ no .reticle.json here and nothing has ever connected — the tools may be ' +
         'registered, but this app is not instrumented. Run `npx @reticlehq/server init` in the app directory');
 }

package/dist/command/cli/doctor/doctor-rows.d.ts

@@ -40,6 +40,8 @@ export declare const DoctorRow: {
      * verification." Every row in this list checks a COMPONENT; none checked a LINK.
      */
     readonly AGENT_LINK: "agent link";
+    /** Is the APP in this folder wired, not just the tools. Printed by `doctor-project-line.ts`. */
+    readonly PROJECT: "project";
     /**
      * Which of `localhost`'s two answers reaches the bridge, printed only when they disagree.
      *
@@ -58,6 +60,10 @@ export declare const DoctorRow: {
     readonly DAEMON_LOG: "daemon log";
     readonly TRACING: "tracing";
     readonly DESKTOP: "desktop";
+    /** What Reticle sees in each connected app, out of eight capabilities. Only with a live tab. */
+    readonly COVERAGE: "coverage";
+    /** A project folder holding runs the platform never got. Only when there is one. */
+    readonly UNSYNCED: "unsynced";
 };
 type DoctorRowLabel = (typeof DoctorRow)[keyof typeof DoctorRow];
 export declare const DOCTOR_ROW_LABELS: readonly DoctorRowLabel[];

package/dist/command/cli/doctor/doctor-rows.js

@@ -40,6 +40,8 @@ export const DoctorRow = {
      * verification." Every row in this list checks a COMPONENT; none checked a LINK.
      */
     AGENT_LINK: 'agent link',
+    /** Is the APP in this folder wired, not just the tools. Printed by `doctor-project-line.ts`. */
+    PROJECT: 'project',
     /**
      * Which of `localhost`'s two answers reaches the bridge, printed only when they disagree.
      *
@@ -58,6 +60,10 @@ export const DoctorRow = {
     DAEMON_LOG: 'daemon log',
     TRACING: 'tracing',
     DESKTOP: 'desktop',
+    /** What Reticle sees in each connected app, out of eight capabilities. Only with a live tab. */
+    COVERAGE: 'coverage',
+    /** A project folder holding runs the platform never got. Only when there is one. */
+    UNSYNCED: 'unsynced',
 };
 export const DOCTOR_ROW_LABELS = Object.values(DoctorRow);
 /** Indent every row carries, before the label. */

package/dist/command/cli/doctor/doctor-signing-line.d.ts

@@ -0,0 +1,38 @@
+/** What `codesign -dv` says about one binary. */
+export interface Signature {
+    /** Ad-hoc signed, or not signed at all: no identity the keychain can recognise. */
+    adhoc: boolean;
+    identifier?: string;
+    teamId?: string;
+}
+export declare const KEYCHAIN_NOTE: string;
+/** `codesign -dv` output (it writes to stderr), or undefined when it said nothing usable. */
+export declare function parseCodesign(output: string): Signature | undefined;
+/** The note, when the build is unsigned, ad-hoc, or signed by another team than the installed app. */
+export declare function signingNote(build: Signature | undefined, installed: Signature | undefined): string | undefined;
+/**
+ * The dev binary `tauri dev` runs, the release builds `tauri build` leaves (the bundle first), and
+ * where an installed copy of the same app would be.
+ */
+export declare function tauriDevBinary(read: (path: string) => string | undefined): {
+    build: string;
+    release: string[];
+    installed?: string;
+} | undefined;
+/** How to look at a project, injected so the decision is a unit test. */
+export interface SigningProbe {
+    read: (relative: string) => string | undefined;
+    codesign?: (path: string) => Signature | undefined;
+    platform?: NodeJS.Platform;
+    /** The project folder the dev build's relative path is under. */
+    dir?: string;
+}
+/** On macOS, the keychain note for the Tauri build Reticle drives, when it applies. */
+export declare function keychainNoteFor(probe: SigningProbe): string | undefined;
+/** A project folder's files, read relative to it. */
+export declare const projectReader: (dir: string) => (relative: string) => string | undefined;
+/**
+ * The note for an agent session's first answer, then never again for that session: the person
+ * flooded with password dialogs is talking to the agent, and may never run doctor.
+ */
+export declare function keychainNoticeOnce(attach: string, probe: SigningProbe): string | undefined;

package/dist/command/cli/doctor/doctor-signing-line.js

@@ -0,0 +1,114 @@
+/**
+ * Whether macOS will ask for the keychain password every time the app Reticle drives reads it.
+ *
+ * Reported from the field: a signed macOS Tauri app driven by Reticle flooded its user with password
+ * dialogs. Reticle never touches the keychain; macOS binds each keychain item to the signature of
+ * the app that saved it, and the build Reticle runs (`tauri dev`, ad-hoc signed) is another app to
+ * the keychain. Read from `codesign -dv`, through an injected runner, so the parsing is a unit test.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { isAbsolute, join, posix } from 'node:path';
+export const KEYCHAIN_NOTE = "macOS ties keychain items to the app's signature; this build is signed differently, so the " +
+    "app's keychain reads will ask for your password. Set your release identity " +
+    '(APPLE_SIGNING_IDENTITY, or signingIdentity in tauri.conf.json) and `reticle setup` signs the ' +
+    'dev build it starts with it; or use a separate keychain service in dev.';
+const NOT_SIGNED = 'code object is not signed at all';
+const NO_TEAM = 'not set';
+/** `codesign -dv` output (it writes to stderr), or undefined when it said nothing usable. */
+export function parseCodesign(output) {
+    if (output.includes(NOT_SIGNED))
+        return { adhoc: true };
+    const field = (key) => new RegExp(`^${key}=(.+)$`, 'm').exec(output)?.[1]?.trim();
+    const identifier = field('Identifier');
+    if (identifier === undefined)
+        return undefined;
+    const team = field('TeamIdentifier');
+    return {
+        adhoc: 'adhoc' === field('Signature'),
+        identifier,
+        ...(team === undefined || NO_TEAM === team ? {} : { teamId: team }),
+    };
+}
+/** The note, when the build is unsigned, ad-hoc, or signed by another team than the installed app. */
+export function signingNote(build, installed) {
+    if (build === undefined)
+        return undefined;
+    if (build.adhoc)
+        return KEYCHAIN_NOTE;
+    if (installed !== undefined && installed.teamId !== build.teamId)
+        return KEYCHAIN_NOTE;
+    return undefined;
+}
+/**
+ * The dev binary `tauri dev` runs, the release builds `tauri build` leaves (the bundle first), and
+ * where an installed copy of the same app would be.
+ */
+export function tauriDevBinary(read) {
+    const cargo = read('src-tauri/Cargo.toml');
+    const name = cargo === undefined ? undefined : /^name\s*=\s*"([^"]+)"/m.exec(cargo)?.[1];
+    if (name === undefined)
+        return undefined;
+    let product;
+    try {
+        product = JSON.parse(read('src-tauri/tauri.conf.json') ?? '{}')['productName'];
+    }
+    catch {
+        product = undefined;
+    }
+    const named = 'string' === typeof product && 0 < product.length ? product : undefined;
+    return {
+        build: `src-tauri/target/debug/${name}`,
+        release: [
+            ...(named === undefined ? [] : [`src-tauri/target/release/bundle/macos/${named}.app`]),
+            `src-tauri/target/release/${name}`,
+        ],
+        ...(named === undefined ? {} : { installed: `/Applications/${named}.app` }),
+    };
+}
+/** `codesign -dv` of one path, as it prints it (to stderr). Undefined when nothing ran. */
+function codesignOf(path) {
+    if (!existsSync(path))
+        return undefined;
+    const run = spawnSync('codesign', ['-dv', '--verbose=2', path], { encoding: 'utf8' });
+    return parseCodesign(`${run.stdout}${run.stderr}`);
+}
+/** On macOS, the keychain note for the Tauri build Reticle drives, when it applies. */
+export function keychainNoteFor(probe) {
+    if ('darwin' !== (probe.platform ?? process.platform))
+        return undefined;
+    const app = tauriDevBinary(probe.read);
+    if (app === undefined)
+        return undefined;
+    const codesign = probe.codesign ?? codesignOf;
+    const installed = app.installed === undefined ? undefined : codesign(app.installed);
+    // Every build on disk, debug and release: a person with only a release build heard nothing.
+    for (const build of [app.build, ...app.release]) {
+        // macOS only, so a POSIX path on every host the unit test runs on.
+        const note = signingNote(codesign(posix.join(probe.dir ?? process.cwd(), build)), installed);
+        if (note !== undefined)
+            return note;
+    }
+    return undefined;
+}
+/** A project folder's files, read relative to it. */
+export const projectReader = (dir) => (relative) => {
+    try {
+        return readFileSync(isAbsolute(relative) ? relative : join(dir, relative), 'utf8');
+    }
+    catch {
+        return undefined;
+    }
+};
+// ponytail: grows by one id per agent connection the daemon ever served; bound it if that matters.
+const noticed = new Set();
+/**
+ * The note for an agent session's first answer, then never again for that session: the person
+ * flooded with password dialogs is talking to the agent, and may never run doctor.
+ */
+export function keychainNoticeOnce(attach, probe) {
+    if (noticed.has(attach))
+        return undefined;
+    noticed.add(attach);
+    return keychainNoteFor(probe);
+}

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

@@ -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');

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.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) {
         /**

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>;