@reticlehq/server 3.7.0 → 3.8.1

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

@@ -19,12 +19,19 @@ import { CONTRACT_FINGERPRINT } from '@reticlehq/core';
 import { CspBasis, diagnoseDesktop, diagnoseObservedWebCsp, diagnoseWebCsp, isDesktopProject, resolveWebCspFindings, webCspOptionsFor, } from '@reticlehq/init';
 import { RETICLE_CONFIG_BASENAME, diagnosePortMismatch, readProjectFramework, readProjectId, readProjectPort, } from './ports/resolve/cli-port.js';
 import { DoctorRow, doctorRow } from './doctor/doctor-rows.js';
+import { ReticleDir } from '@reticlehq/core';
+import { resolveProjectCloud } from '../../memory/cloud/cloud-config.js';
+import { BackgroundSyncState, backgroundSyncGate } from '../../memory/cloud/background-sync.js';
+import { readCloudState } from '../../memory/cloud/sync-disk.js';
+import { signedInTo } from './auth/cloud-session.js';
+import { claudeCliHere, projectDirOf, promptCaptureRows } from './hook/hook-command.js';
 import { coverageLines } from './doctor/doctor-coverage-line.js';
 import { homedir } from 'node:os';
 import { createNodeFileSystem } from '../../memory/project/fs/fs-port.js';
 import { describeUnsynced } from '../../memory/cloud/unsynced-roots.js';
 import { machineUnsyncedRoots } from '../../memory/project/sync-status.js';
 import { attachState, describeAttachState } from '../../surface/mcp/attach-memory.js';
+import { agentLinkText } from './doctor/doctor-agent-link.js';
 import { findOccupiedSiblings, siblingListenerNote } from './ports/sibling-ports.js';
 import { daemonsServingProjectElsewhere, resolveDaemonForProject, splitBrainNote, wrongDaemonNote, } from '../daemon/daemon-resolve.js';
 import { isAlive } from '../daemon/daemon.js';
@@ -37,8 +44,9 @@ import { hasConnectedDocument, observeWebDocument, } from '../../portal/session/
  */
 /** Narrow the `/status` payload to the two fields the daemon line reads. */
 function asIdentity(payload) {
-    if (typeof payload !== 'object' || null === payload)
+    if (typeof payload !== 'object' || null === payload) {
         return {};
+    }
     const record = payload;
     const pick = (key) => {
         const value = record[key];
@@ -93,8 +101,9 @@ export async function handleDoctor(port) {
             contract: CONTRACT_FINGERPRINT,
         });
         line(built.text);
-        if (built.skew !== undefined)
+        if (built.skew !== undefined) {
             line(doctorRow(DoctorRow.VERSION, `✗ ${built.skew}`));
+        }
         // The same payload already carries whether anything has CONNECTED, and doctor was reading
         // `version` off it and dropping the rest. Without this the command is silent on the one step the
         // funnel stalls on: wired correctly, daemon up, and no page has ever dialled in.
@@ -122,18 +131,22 @@ export async function handleDoctor(port) {
     else {
         line(doctorRow(DoctorRow.DAEMON, `✗ not running on :${port} — your agent runs \`reticle mcp\` (or \`reticle serve\`)`));
     }
-    if (sessions !== undefined)
+    if (sessions !== undefined) {
         line(sessions.text);
-    for (const row of coverageLines(daemonStatus))
+    }
+    for (const row of coverageLines(daemonStatus)) {
         line(row);
+    }
     // Runs nothing will send, named by folder with the one command that sends them.
-    for (const entry of await machineUnsyncedRoots(createNodeFileSystem(), homedir(), process.env))
+    for (const entry of await machineUnsyncedRoots(createNodeFileSystem(), homedir(), process.env)) {
         line(doctorRow(DoctorRow.UNSYNCED, `✗ ${describeUnsynced(entry, process.cwd())}`));
+    }
     line(doctorRow(DoctorRow.BRIDGE_PORT, `${port}  (your app must dial THIS port, not your dev-server port)`));
     const projectPort = readProjectPort(process.cwd());
     const mismatch = diagnosePortMismatch(port, projectPort);
-    if (mismatch !== undefined)
+    if (mismatch !== undefined) {
         line(doctorRow(DoctorRow.PORT_CHECK, `✗ ${mismatch}`));
+    }
     const projectId = readProjectId(process.cwd());
     // The hop between the agent and this daemon, stated as its own row rather than inferred from the
     // ones above it. `sessions` says the BROWSER reached the daemon; nothing said whether the AGENT
@@ -145,26 +158,23 @@ export async function handleDoctor(port) {
     // attached here" and sends the reader to re-register a server that is registered and running —
     // the confident wrong answer for a link that is not missing but misaimed.
     const split = splitBrainLine(port, projectId);
-    line(doctorRow(DoctorRow.AGENT_LINK, split !== undefined
-        ? `✗ ${split}`
-        : attachAction === undefined
-            ? // A RECORD, not a live check, and the row now says so. The attach memory is durable
-                // and per-port: once a client has attached, enumerated and called, this stays green
-                // forever. A registration pointing at a path that no longer exists produces a client
-                // that cannot start at all, and this row reported the link healthy throughout —
-                // measured, on this machine, for the two days after `packages/` was dissolved and
-                // nothing updated ~/.claude.json. `doctor` is what a stuck human runs, so a row that
-                // answers "did this ever work" while looking like "does this work" is the wrong
-                // shape here even though every word of it is true.
-                '✓ an MCP client attached here and called tools before (a record, not a live check)'
-            : `✗ ${attachAction}`));
+    // The record alone cannot answer whether the link works NOW (#1710): when the port is held
+    // but `/status` does not answer, the record below would still read healthy or blame the
+    // client, while the daemon row above already names the one fix for the held port. So in that
+    // state the agent link row only points back at the daemon row instead of repeating the
+    // record or adding a second command. No probe runs here: `/status` and `/mcp/sse` share one
+    // HTTP server, so silence on `/status` already answers the MCP question, and an SSE connect
+    // would flip agent presence on a daemon with no agents attached.
+    const foreign = presence === PortPresence.FOREIGN;
+    line(doctorRow(DoctorRow.AGENT_LINK, agentLinkText({ split, attachAction, foreign })));
     // Remaining half of #261. The SDK dialling a port we are not on is invisible as a refused inbound,
     // but a listener on a well-known Reticle port is visible. Report the observation; do not conclude
     // it is the daemon this app wants — somebody else's daemon looks the same from here.
     const occupiedSiblings = await findOccupiedSiblings(port, probeDaemon);
     const siblingNote = siblingListenerNote(port, occupiedSiblings);
-    if (siblingNote !== undefined)
+    if (siblingNote !== undefined) {
         line(doctorRow(DoctorRow.SIBLING, siblingNote));
+    }
     // The check this checklist was missing: is the APP wired, not just the tools. Everything above can
     // be green in a project that has never been through `init`, and that combination is precisely the
     // one `doctor` gets run to explain.
@@ -175,6 +185,10 @@ export async function handleDoctor(port) {
         // and telling somebody a file is missing while it sits in front of them is its own dead end.
         configPresent: existsSync(join(process.cwd(), RETICLE_CONFIG_BASENAME)),
     }));
+    // Are prompts reaching `.reticle/`, and is the work reaching the user's own workspace.
+    for (const row of await captureAndSyncLines(process.cwd(), process.env)) {
+        line(row);
+    }
     // Where to LOOK when something is wrong. The daemon has always written a structured log here and
     // nothing ever said so, so the first move in every investigation was reading source instead of
     // reading the log. `RETICLE_TRACE=1` turns the same stream into a per-stage trace — see
@@ -246,6 +260,37 @@ export async function handleDoctor(port) {
         line(doctorRow(DoctorRow.DESKTOP, '✓ desktop wiring looks right'));
     }
     const keychain = keychainNoteFor({ read: readProjectFile });
-    if (keychain !== undefined)
+    if (keychain !== undefined) {
         line(doctorRow(DoctorRow.DESKTOP, `⚠ ${keychain}`));
+    }
+}
+/**
+ * Two rows: does each agent hand its prompts to Reticle, and does the daemon send this
+ * project's work in the background, and if not, why.
+ *
+ * Both answers come from the disk, the same files the hook and the daemon read, so `doctor` needs
+ * no daemon to give them. A sync the platform refused shows as the last error the cycle recorded.
+ */
+async function captureAndSyncLines(cwd, env) {
+    const home = homedir();
+    const projectDir = projectDirOf(cwd);
+    const lines = promptCaptureRows(projectDir, env, claudeCliHere()).map((row) => doctorRow(DoctorRow.PROMPTS, row));
+    const reticleRoot = join(projectDir, ReticleDir.ROOT);
+    const cloud = await resolveProjectCloud(createNodeFileSystem(), reticleRoot, home, env);
+    const gate = backgroundSyncGate({
+        reticleRoot,
+        cloud,
+        env,
+        signedIn: (url) => signedInTo(join(home, ReticleDir.ROOT), url),
+    });
+    const state = readCloudState(reticleRoot);
+    const on = BackgroundSyncState.ON === gate.state;
+    const last = state.lastPushAt === undefined
+        ? 'no push yet'
+        : `last push ${new Date(state.lastPushAt).toISOString()}`;
+    lines.push(doctorRow(DoctorRow.SYNC, `${on ? '✓ on' : '✗ off'}: ${gate.why}; ${last}`));
+    if (state.lastError !== undefined) {
+        lines.push(doctorRow(DoctorRow.SYNC, `✗ last error: ${state.lastError}`));
+    }
+    return lines;
 }

package/dist/command/cli/cli-flow-commands.js

@@ -10,13 +10,13 @@ import { knownRegression } from './known-regression.js';
 import { gateHookMessage, GATE_SKIP_ENV } from './answers/gate-hook-message.js';
 import { readProjectId } from './ports/resolve/cli-port.js';
 import { changedFilesSince } from '../../language/flows/change/git-changed.js';
-import { join } from 'node:path';
+import { isAbsolute, join, sep } from 'node:path';
 import { ReticleDir } from '@reticlehq/core';
 import { FlowStore } from '../../language/flows/flows.js';
 import { RunStore } from '../../judgement/runs/artifact/run-store.js';
 import { createNodeFileSystem } from '../../memory/project/fs/fs-port.js';
 import { affectedSavedFlows, toFlowSources, } from '../../language/flows/change/flow-sources.js';
-import { isInteractiveSource, unflowedFiles } from '../../language/flows/change/affected.js';
+import { isInteractiveSource, sourceMatchesChange, unflowedFiles, } from '../../language/flows/change/affected.js';
 import { LedgerStore, regressions, staleChanged, unexecutedChanged, } from '../../features/exhaust/ledger.js';
 import { gateDecision, passingFlowNames } from '../../language/flows/change/gate.js';
 import { FlakeStore } from '../../language/flows/stores/flake-store.js';
@@ -68,18 +68,31 @@ export async function loadNamedFlows(fs, reticleRoot, projectId) {
  */
 /**
  * A changed file's text, or '' when it is gone. `git diff --name-only` answers from the repository
- * root while the gate may run in a package below it, so leading segments are dropped until the path
- * resolves from `cwd`.
+ * root while the gate may run in a package below it, so a leading segment is dropped only when it is
+ * the directory the gate runs in (or a chain of them ending at `cwd`). An absolute path is read as is.
+ * Never fall through to a shorter suffix that merely happens to exist: that is another file.
  */
 function atChangedPath(cwd, file, read) {
-    const parts = file.split('/');
-    for (let i = 0; i < parts.length; i += 1) {
+    const attempt = (path) => {
         try {
-            return read(join(cwd, ...parts.slice(i)));
+            return read(path);
         }
         catch {
-            // not at this depth; try the path one segment shorter
+            return undefined;
+        }
+    };
+    if (isAbsolute(file))
+        return attempt(file);
+    const parts = file.split('/');
+    const cwdParts = cwd.split(sep);
+    for (let i = 0; i < parts.length; i += 1) {
+        if (i > 0 &&
+            (i > cwdParts.length || cwdParts.slice(-i).join('/') !== parts.slice(0, i).join('/'))) {
+            continue;
         }
+        const found = attempt(join(cwd, ...parts.slice(i)));
+        if (found !== undefined)
+            return found;
     }
     return undefined;
 }
@@ -90,6 +103,30 @@ function readChangedFile(cwd, file) {
 function changedFileModifiedAt(cwd, file) {
     return atChangedPath(cwd, file, (path) => statSync(path).mtimeMs);
 }
+/**
+ * The flows that still count as passing for the gate.
+ *
+ * A flow's newest pass counts only if its run is later than the newest mtime of the changed files
+ * that belong to THAT flow: the changed files that match its sources (the same suffix rule as
+ * `affectedFlows`, so a repo-root path, a package-relative stamp and an absolute stamp all agree).
+ * Edits outside its sources never invalidate it. A flow with no recorded sources cannot be
+ * attributed, so every changed file counts for it. A changed file that is gone fails closed. Only
+ * `affected` flows are judged; any other flow's newest pass stands.
+ */
+async function currentPassing(fs, root, flows, affected, changed) {
+    const sourcesOf = new Map(toFlowSources(flows).map((f) => [f.name, f.sources ?? []]));
+    const passing = [];
+    const cwd = process.cwd();
+    for (const [name, at] of await new RunStore(fs, root).passingFlowTimes(passingFlowNames)) {
+        const sources = sourcesOf.get(name) ?? [];
+        const own = 0 === sources.length ? changed : changed.filter((f) => sourceMatchesChange(f, sources));
+        const stale = affected.includes(name) &&
+            own.some((f) => !((changedFileModifiedAt(cwd, f) ?? Infinity) < at));
+        if (!stale)
+            passing.push(name);
+    }
+    return passing;
+}
 export async function handleGate(files, since, 
 /** Hook mode: prose for a human, and silence when there was simply nothing to check. */
 hook = false, 
@@ -102,8 +139,7 @@ acceptCoverage = false) {
         const changed = (await resolveChangedFiles(files, since, process.cwd())).files;
         const allFlows = await loadNamedFlows(fs, reticleRoot, readProjectId(process.cwd()));
         const affected = affectedSavedFlows(allFlows, changed).affected;
-        const latest = await new RunStore(fs, reticleRoot).latest();
-        const passing = passingFlowNames(latest?.flows ?? []);
+        const passing = await currentPassing(fs, reticleRoot, allFlows, affected, changed);
         const flaky = await new FlakeStore(fs, reticleRoot).flakyFlows();
         // Anti-reward-hacking: diff each flow's CURRENT assertions against what it asserted the last
         // time it passed. A mustHold that dropped from a real consequence to a fakeable presence check is a
@@ -133,9 +169,13 @@ acceptCoverage = false) {
             .map(([name]) => name);
         // Only against a suite that exists: a project with no flows yet is NOTHING_TO_CHECK, and
         // demanding a flow per edited component on its first day would block every stop.
+        const flowSourcesAll = toFlowSources(allFlows);
         const unflowed = 0 === allFlows.length
             ? []
-            : unflowedFiles(toFlowSources(allFlows), changed, (file) => isInteractiveSource(readChangedFile(process.cwd(), file)));
+            : unflowedFiles(flowSourcesAll, changed, (file) => isInteractiveSource(readChangedFile(process.cwd(), file)));
+        // Flows exist but none carries a source stamp (a stack without source stamping, or flows saved before stamping was added): `unflowed`
+        // then names every changed component, which would read as "nothing drove it" when a flow did.
+        const flowsWithoutSources = allFlows.length > 0 && flowSourcesAll.every((f) => 0 === (f.sources ?? []).length);
         // The coverage ledger, when one exists: a level that fell below its best, and changed code the
         // browser loaded and never ran. A project that never folded coverage has an empty ledger and
         // neither can fire.
@@ -181,6 +221,7 @@ acceptCoverage = false) {
             ...(result.downgraded.length > 0 ? { downgraded: result.downgraded } : {}),
             ...(result.deleted.length > 0 ? { deletedCoverage: result.deleted } : {}),
             ...(result.unflowed.length > 0 ? { unflowed: result.unflowed } : {}),
+            ...(result.unflowed.length > 0 && flowsWithoutSources ? { flowsWithoutSources } : {}),
             ...(result.coverageRegressed.length > 0
                 ? { coverageRegressed: result.coverageRegressed }
                 : {}),
@@ -221,6 +262,7 @@ acceptCoverage = false) {
                     downgraded: result.downgraded.map((d) => d.flow),
                     deleted: result.deleted,
                     unflowed: result.unflowed,
+                    flowsWithoutSources,
                     coverageRegressed: result.coverageRegressed.map((r) => `${r.level} ${String(r.was)}% -> ${String(r.now)}%`),
                     unexecuted: result.unexecuted,
                     regressed: regressed?.length ?? 0,

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

@@ -54,6 +54,14 @@ export declare function planKill(input: {
     answersStatus: boolean;
     force: boolean;
 }): KillPlan;
+/**
+ * Ask the daemon on `port` to run its own shutdown path. True when it accepted.
+ *
+ * Asked before any signal, on every OS. On Windows a signal ends the process at once, so the daemon
+ * did not close its browser or send its stop event. False for an older daemon without the route, a
+ * wrong token, or no answer: the caller then sends the signal as before.
+ */
+export declare function requestShutdown(port: number, token?: string | undefined): Promise<boolean>;
 /** `reticle kill` — free the port. Resolves to whether the port is now free. */
 export declare function runKill(port: number, force: boolean): Promise<boolean>;
 export {};

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

@@ -23,6 +23,9 @@ import { probeDaemon } from '../../surface/mcp/mcp-proxy.js';
 import { log } from '../../log.js';
 import { fetchStatus } from '../daemon/binding/daemon-status-probe.js';
 import { captureLookup, findPortHolder } from './ports/port-holder.js';
+import * as http from 'node:http';
+import { LOOPBACK_HOST, SHUTDOWN_PATH } from '@reticlehq/core';
+import { storedPairingToken } from '../../portal/bridge/pairing-token.js';
 /** What the plan says to do with the port. */
 export const KillAction = {
     NOTHING: 'nothing',
@@ -74,14 +77,48 @@ const GRACEFUL_KILL_MS = 5_000;
 /** How long after SIGKILL before we accept the process is not ours to kill and say so. */
 const FORCED_KILL_MS = 2_000;
 const KILL_POLL_MS = 100;
+/** A loopback call: a daemon that does not answer in this time gets the signal instead. */
+const SHUTDOWN_REQUEST_TIMEOUT_MS = 1_000;
+/**
+ * Ask the daemon on `port` to run its own shutdown path. True when it accepted.
+ *
+ * Asked before any signal, on every OS. On Windows a signal ends the process at once, so the daemon
+ * did not close its browser or send its stop event. False for an older daemon without the route, a
+ * wrong token, or no answer: the caller then sends the signal as before.
+ */
+export function requestShutdown(port, token = storedPairingToken()) {
+    if (token === undefined) {
+        return Promise.resolve(false);
+    }
+    return new Promise((resolve) => {
+        const req = http.request({
+            host: LOOPBACK_HOST,
+            port,
+            path: SHUTDOWN_PATH,
+            method: 'POST',
+            headers: { authorization: `Bearer ${token}` },
+            timeout: SHUTDOWN_REQUEST_TIMEOUT_MS,
+        }, (res) => {
+            res.resume();
+            resolve(202 === res.statusCode);
+        });
+        req.on('error', () => resolve(false));
+        req.on('timeout', () => {
+            req.destroy();
+            resolve(false);
+        });
+        req.end();
+    });
+}
 /**
  * Signal ONE pid and wait for it to go: SIGTERM, then SIGKILL, then give up and say it survived.
+ * `asked`: the daemon already accepted a shutdown request, so the SIGTERM is not sent.
  *
  * The escalation is the reason this exists rather than a bare SIGTERM — there is a field report of a
  * daemon that ignored SIGTERM until a human ran `kill -9` by hand, which is the moment the `lsof -ti`
  * pipeline gets typed and the agent's proxy dies with the daemon.
  */
-async function terminate(pid) {
+async function terminate(pid, asked = false) {
     const signal = (name) => {
         try {
             process.kill(pid, name);
@@ -90,7 +127,9 @@ async function terminate(pid) {
             // Gone between the liveness check and here. The next poll reports it as gone.
         }
     };
-    signal('SIGTERM');
+    if (!asked) {
+        signal('SIGTERM');
+    }
     const started = Date.now();
     let escalated = false;
     for (;;) {
@@ -143,7 +182,8 @@ export async function runKill(port, force) {
         log('reticle_kill_nothing_to_do', { port, presence });
         return true;
     }
-    const { gone, escalated } = await terminate(pid);
+    const asked = PortPresence.DAEMON === presence && (await requestShutdown(port));
+    const { gone, escalated } = await terminate(pid, asked);
     if (gone)
         removePid(port);
     log(gone ? 'reticle_killed' : 'reticle_kill_survived', {

package/dist/command/cli/cli-parse-feedback.d.ts

@@ -11,6 +11,8 @@ export declare const BUG_FLAG = "--bug";
  */
 export declare const KIND_FLAG = "--kind";
 export declare const AGENT_FLAG = "--agent";
+/** `--contact <email>`: a reply address, sent only when the person gives it. */
+export declare const CONTACT_FLAG = "--contact";
 /** Accepted `--kind` values, from core's enum — never a second hand-written list to drift from it. */
 export declare const FEEDBACK_KINDS: readonly string[];
 /** What `parseFeedbackArgs` yields: the parsed command, or a usage error to print. */
@@ -23,6 +25,8 @@ export type ParsedFeedback = {
     bug: boolean;
     /** `--agent`: file as the agent, so agent reports never dilute the human rating signal. */
     agent: boolean;
+    /** `--contact`: a reply address the person gave. */
+    contact?: string;
 } | {
     kind: 'error';
     message: string;

package/dist/command/cli/cli-parse-feedback.js

@@ -5,7 +5,7 @@
  * is the one command whose arguments are free text, so it is the only place in the grammar where
  * "everything that is not a flag" is a rule with edge cases rather than a one-liner.
  */
-import { FeedbackKind } from '@reticlehq/core/telemetry';
+import { FEEDBACK_CONTACT_MAX, FeedbackKind, isFeedbackContact } from '@reticlehq/core/telemetry';
 /** `reticle feedback --rating 4 "the words"` — the human half of the channel. */
 export const RATING_FLAG = '--rating';
 export const BUG_FLAG = '--bug';
@@ -19,6 +19,8 @@ export const BUG_FLAG = '--bug';
  */
 export const KIND_FLAG = '--kind';
 export const AGENT_FLAG = '--agent';
+/** `--contact <email>`: a reply address, sent only when the person gives it. */
+export const CONTACT_FLAG = '--contact';
 /** Accepted `--kind` values, from core's enum — never a second hand-written list to drift from it. */
 export const FEEDBACK_KINDS = Object.values(FeedbackKind);
 /** Parse everything after `reticle feedback`. */
@@ -33,6 +35,14 @@ export function parseFeedbackArgs(rest) {
     if (feedbackKind !== undefined && !FEEDBACK_KINDS.includes(feedbackKind)) {
         return { kind: 'error', message: `${KIND_FLAG} takes one of: ${FEEDBACK_KINDS.join(', ')}` };
     }
+    const contactAt = rest.indexOf(CONTACT_FLAG);
+    const contact = -1 === contactAt ? undefined : (rest[contactAt + 1] ?? '');
+    if (contact !== undefined && !isFeedbackContact(contact)) {
+        return {
+            kind: 'error',
+            message: `${CONTACT_FLAG} takes one email address of at most ${String(FEEDBACK_CONTACT_MAX)} characters, such as you@example.com`,
+        };
+    }
     // Everything that is not a flag or a flag's VALUE is the message. Quoting is the user's job for
     // shell reasons, but joining the remainder means an unquoted sentence still works. Both value
     // positions have to be consumed: without that, `--kind bug "..."` filed a report whose text began
@@ -40,6 +50,7 @@ export function parseFeedbackArgs(rest) {
     const consumed = new Set([
         ...(-1 === ratingAt ? [] : [ratingAt, ratingAt + 1]),
         ...(-1 === kindAt ? [] : [kindAt, kindAt + 1]),
+        ...(-1 === contactAt ? [] : [contactAt, contactAt + 1]),
     ]);
     const text = rest
         .filter((arg, i) => !consumed.has(i) && !arg.startsWith('--'))
@@ -52,5 +63,6 @@ export function parseFeedbackArgs(rest) {
         ...(feedbackKind !== undefined ? { feedbackKind } : {}),
         bug: rest.includes(BUG_FLAG),
         agent: rest.includes(AGENT_FLAG),
+        ...(contact !== undefined ? { contact } : {}),
     };
 }

package/dist/command/cli/cli-parse-grammar.d.ts

@@ -46,8 +46,7 @@ export declare const CLOUD_COMMANDS: readonly string[];
 export declare const RENAMED_COMMANDS: ReadonlyMap<string, string>;
 /**
  * The command an old name now goes by, when the note saying so should print; otherwise undefined.
- * Not for a request for help (that answer names the new command itself), and not for
- * `login --email`, which `connect --help` documents as the sign-in for CI and agents.
+ * Not for a request for help (that answer names the new command itself).
  */
 export declare function renamedCommandFor(argv: readonly string[]): string | undefined;
 /**

package/dist/command/cli/cli-parse-grammar.js

@@ -82,19 +82,14 @@ export const RENAMED_COMMANDS = new Map([
     ['memory', 'runs memory'],
 ]);
 const HELP_FLAGS = new Set(['--help', '-h']);
-/** `login --email` is the documented sign-in without a browser, so it is not a renamed `connect`. */
-const BROWSERLESS_LOGIN = { command: 'login', flag: '--email' };
 /**
  * The command an old name now goes by, when the note saying so should print; otherwise undefined.
- * Not for a request for help (that answer names the new command itself), and not for
- * `login --email`, which `connect --help` documents as the sign-in for CI and agents.
+ * Not for a request for help (that answer names the new command itself).
  */
 export function renamedCommandFor(argv) {
     const name = argv[0];
     if (name === undefined || argv.some((arg) => HELP_FLAGS.has(arg)))
         return undefined;
-    if (BROWSERLESS_LOGIN.command === name && argv.includes(BROWSERLESS_LOGIN.flag))
-        return undefined;
     return RENAMED_COMMANDS.get(name);
 }
 /**

package/dist/command/cli/cli-parse-serve.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Force a hidden browser. The default is now HEADED: a run nobody can see is a run nobody trusts,
+ * and every "did it actually do anything?" question cost a round-trip. CI passes this (or just sets
+ * CI, which flips the default) because there is no display there to be headed on.
+ */
+export declare const HEADLESS_FLAG = "--headless";
+export declare const DRIVE_FLAG = "--drive";
+export declare const HTTP_FLAG = "--http";
+export declare const HTTP_PORT_FLAG = "--http-port";
+export declare const HTTP_TOKEN_FLAG = "--http-token";
+type ServeFlags = {
+    kind: 'ok';
+    port: number;
+    driveUrl?: string;
+    headless: boolean;
+    http: boolean;
+    httpPort?: number;
+    httpToken?: string;
+} | {
+    kind: 'error';
+    message: string;
+};
+export declare function parseServeFlags(args: string[], defaultPort: number, defaultHeadless: boolean): ServeFlags;
+export {};

package/dist/command/cli/cli-parse-serve.js

@@ -0,0 +1,124 @@
+/**
+ * The serve / mcp / `_daemon` flag grammar, including the verify HTTP endpoint.
+ *
+ * Split out of `cli-parse.ts` when that file crossed the line cap. These three commands share one
+ * flag set: the bridge port, a drive URL, headless, and the verify endpoint `--http` starts.
+ */
+import { HEADED_FLAG, PORT_FLAG, missingValue, notANumber, unknownArgument, } from './cli-parse-grammar.js';
+/**
+ * Force a hidden browser. The default is now HEADED: a run nobody can see is a run nobody trusts,
+ * and every "did it actually do anything?" question cost a round-trip. CI passes this (or just sets
+ * CI, which flips the default) because there is no display there to be headed on.
+ */
+export const HEADLESS_FLAG = '--headless';
+export const DRIVE_FLAG = '--drive';
+export const HTTP_FLAG = '--http';
+export const HTTP_PORT_FLAG = '--http-port';
+export const HTTP_TOKEN_FLAG = '--http-token';
+const requiresHttp = (flag) => ({
+    kind: 'error',
+    message: `${flag} requires ${HTTP_FLAG} — it configures the verify endpoint ${HTTP_FLAG} starts`,
+});
+/**
+ * The verify endpoint cannot use the bridge port.
+ *
+ * `reticle serve --http --http-port 4400` reached `listen` and died with a raw
+ * `EADDRINUSE 127.0.0.1:4400`. That number is this daemon's bridge port, and MCP is already
+ * served there. Name both ports and stop before anything listens (#1786).
+ */
+const httpPortIsBridge = (httpPort, bridgePort) => ({
+    kind: 'error',
+    message: `${HTTP_PORT_FLAG} ${String(httpPort)} is the bridge port ${String(bridgePort)}. ` +
+        'Pick another port. MCP is already served on the bridge port.',
+});
+export function parseServeFlags(args, defaultPort, defaultHeadless) {
+    let port = defaultPort;
+    let driveUrl;
+    let headless = defaultHeadless;
+    let http = false;
+    let httpPort;
+    let httpToken;
+    let i = 0;
+    while (i < args.length) {
+        const arg = args[i];
+        // `i < args.length` already guarantees this, but the index signature does not say so and the
+        // unknown-argument error needs a real string to name.
+        if (arg === undefined) {
+            break;
+        }
+        if (arg === PORT_FLAG) {
+            i++;
+            const n = args[i];
+            if (n === undefined) {
+                return missingValue(PORT_FLAG);
+            }
+            const parsed = parseInt(n, 10);
+            if (isNaN(parsed)) {
+                return notANumber(PORT_FLAG, n);
+            }
+            port = parsed;
+        }
+        else if (arg === DRIVE_FLAG) {
+            i++;
+            driveUrl = args[i];
+            if (driveUrl === undefined) {
+                return missingValue(DRIVE_FLAG);
+            }
+        }
+        else if (arg === HEADED_FLAG) {
+            headless = false;
+        }
+        else if (arg === HEADLESS_FLAG) {
+            headless = true;
+        }
+        else if (arg === HTTP_FLAG) {
+            http = true;
+        }
+        else if (arg === HTTP_PORT_FLAG) {
+            i++;
+            const n = args[i];
+            if (n === undefined) {
+                return missingValue(HTTP_PORT_FLAG);
+            }
+            const parsed = parseInt(n, 10);
+            if (isNaN(parsed)) {
+                return notANumber(HTTP_PORT_FLAG, n);
+            }
+            httpPort = parsed;
+        }
+        else if (arg === HTTP_TOKEN_FLAG) {
+            i++;
+            httpToken = args[i];
+            if (httpToken === undefined) {
+                return missingValue(HTTP_TOKEN_FLAG);
+            }
+        }
+        else {
+            return unknownArgument(arg);
+        }
+        i++;
+    }
+    // Without `--http` these flags configure an endpoint nothing starts, and they were accepted and
+    // silently ignored — worse than being rejected, because the whole reason to pass them is to be
+    // honoured (#687).
+    if (!http && httpPort !== undefined) {
+        return requiresHttp(HTTP_PORT_FLAG);
+    }
+    if (!http && httpToken !== undefined) {
+        return requiresHttp(HTTP_TOKEN_FLAG);
+    }
+    // `port` is the bridge port this command will bind. The caller passes the resolved default
+    // (RETICLE_PORT, the project port, this project's daemon, or 4400). `--port` replaces it.
+    if (httpPort !== undefined && httpPort === port) {
+        return httpPortIsBridge(httpPort, port);
+    }
+    return {
+        kind: 'ok',
+        port,
+        headless,
+        http,
+        ...(driveUrl !== undefined ? { driveUrl } : {}),
+        ...(httpPort !== undefined ? { httpPort } : {}),
+        ...(httpToken !== undefined ? { httpToken } : {}),
+    };
+}