@reticlehq/server 2.14.0 → 3.2.0

package/dist/command/cli/answers/status-next-action.js

@@ -0,0 +1,84 @@
+/**
+ * The sentence `status` owes the user, because `init` promised it.
+ *
+ * `init` closes with "run `npx @reticlehq/server status` — it confirms the app connected, or says
+ * exactly why it has not". On a real install, following that instruction printed `running: false,
+ * presence: "free"` and nothing else: no reason, no next step, no mention of the app. This is the last
+ * checkpoint in the setup path, so a user who arrives here and learns nothing has nowhere left to go.
+ *
+ * Deliberately thin. The differential already exists in `nextActionFor`, which ranks these causes from
+ * what the daemon knows and was rewritten this week to stop leading with a port mismatch; a second
+ * differential here could disagree with the first, and two confident answers pointing different ways
+ * is worse than one. This only supplies the facts the CLI has and renders the answer.
+ */
+import { nextActionFor } from '../../../portal/session/no-session-next-action.js';
+/**
+ * What to do next, or `undefined` when a session is connected and there is nothing to fix.
+ *
+ * The success case has to stay silent: advice printed beside a working session reads as though
+ * something is still wrong, which is its own kind of lie.
+ */
+export function statusNextAction(facts) {
+    if (facts.sessionCount > 0)
+        return undefined;
+    if (!facts.running) {
+        // `running: false` reads as "Reticle is broken", and it usually means the opposite: the daemon is
+        // started by an agent, on demand, and idles out when nobody is driving. A user who has not
+        // attached an agent yet is exactly on track, and saying so is the whole job of this branch.
+        // `previouslyConnected` answers the WIDE question — has any app connected on this port —
+        // because `hasAnyAppConnectedBefore` falls back to that when the directory has no project id, and
+        // the branch below genuinely wants the wide answer: plugin-based wiring can connect without
+        // ever writing `.reticle.json`.
+        //
+        // The sentence here is NARROW. "This project has connected before" attributes a connection to
+        // the directory the user is standing in, and with no project id there is nothing to attribute
+        // it to. Run `status` in an empty directory on a machine that has ever used Reticle and the
+        // old version said the wiring was correct, in a directory with no app, no config and no
+        // instrumentation — the confident-but-unevidenced reassurance this command exists to avoid,
+        // and the same shape as the port-mismatch claim removed from the lease hint.
+        //
+        // So the wide fact gets the wide sentence. Losing the reassurance is the point when the thing
+        // it reassures about cannot be checked.
+        const wiring = facts.projectPreviouslyConnected
+            ? 'This project has connected before, so the wiring is correct.'
+            : facts.previouslyConnected
+                ? 'An app has connected on this port before, though nothing here identifies this directory as that project.'
+                : '';
+        return (`no daemon is running on this port, which is normal — an agent starts it when it first calls a ` +
+            `Reticle tool, and it exits again when idle. ${wiring} Ask your agent to verify something, then ` +
+            `run status again.`).replace(/\s+/g, ' ');
+    }
+    // Only diagnose instrumentation after a live daemon makes that diagnosis possible. When the
+    // daemon is absent, claiming the app is unwired confuses missing evidence with evidence of a
+    // missing install. A previous connection overrides this branch because plugin-based wiring may
+    // connect without creating `.reticle.json`.
+    //
+    // THIS project's previous connection, not any. The override used to read the wide fact, so a
+    // stranger's app touching this port once was enough to silence "your app is not instrumented,
+    // run init" for every uninstrumented directory afterwards. Driving it produced the symptom:
+    // a live daemon, an empty directory, and `status` with no advice at all, while `doctor` two
+    // commands later said the app was not instrumented.
+    if (!facts.initialized && !facts.projectPreviouslyConnected) {
+        return ('no app has ever connected for this project, and there is no Reticle config here — so the ' +
+            'tools are registered and the app itself is not instrumented. Those are two different halves ' +
+            'of the install. Run `npx @reticlehq/server init` in the app directory, then start the dev ' +
+            'server and load the page.');
+    }
+    // The daemon is up and no page has connected. `nextActionFor` owns the ranking; this passes what
+    // it has and lets that function say what is missing rather than guessing at it. It CAN see
+    // listening ports now — the announced ones — which is what the empty list here used to cost.
+    const next = nextActionFor({
+        // The durable bit IS this side's `everConnected`. In-process the flag means "this daemon has served
+        // a session", which a daemon seconds old cannot know; from the CLI the honest equivalent is "an app
+        // for this project has connected on this port", which is the fact that decides whether the wiring
+        // is in question at all.
+        // The comment above this line already described the narrow question — "an app for this
+        // project has connected on this port" — while the wide value was being passed.
+        everConnected: facts.projectPreviouslyConnected,
+        initialized: facts.initialized,
+        listening: facts.devServerPorts ?? [],
+        dev: undefined,
+        previouslyConnected: facts.projectPreviouslyConnected,
+    });
+    return next.reason;
+}

package/dist/command/cli/auth/cloud-keystore.js

@@ -0,0 +1,97 @@
+/**
+ * The machine's credential store: which key belongs to which repo, and who is allowed to write it.
+ *
+ * Split out of `cloud-cli` because both halves — the lookup and the write — encode the same rule
+ * from opposite ends, and reading one without the other is how the rule got broken twice. The store
+ * is `~/.reticle/credentials.json`, a flat map from slot to key.
+ *
+ * There are three generations of slot, and the order matters:
+ *   `<url>::org::<orgId>::<projectId>`  the only unambiguous one
+ *   `<url>::<projectId>`                tells two clouds apart, but not two tenants
+ *   `<projectId>`                       tells nothing apart; the original shape
+ *
+ * Each generation exists because the one before it was found to collide in the field, so the older
+ * two are kept readable (a repo linked by an older CLI must not lose its key) and written only when
+ * doing so cannot mislead somebody else.
+ */
+import { join } from 'node:path';
+import { credentialSlot } from '../../../memory/cloud/cloud-config.js';
+/** Trailing slashes are not identity: `https://x/` and `https://x` are one cloud. */
+const normalizeUrl = (url) => url.replace(/\/+$/, '');
+/** The key held in a slot, whether it is a bare string or the stamped `{ key, url }` shape. */
+const heldKeyOf = (held) => {
+    if ('string' === typeof held)
+        return held.length > 0 ? held : undefined;
+    if ('object' !== typeof held || null === held)
+        return undefined;
+    const key = held['key'];
+    return 'string' === typeof key && key.length > 0 ? key : undefined;
+};
+/**
+ * Find this repo's key, newest slot generation first.
+ *
+ * A hit in an older slot is not proof the key is ours — only that nothing better was filed. The
+ * caller is expected to establish the tenant before trusting what comes back.
+ */
+export const findCredential = (raw, projectId, url, orgId) => {
+    if ('object' !== typeof raw || null === raw)
+        return undefined;
+    const store = raw;
+    const orgScoped = orgId === undefined ? undefined : store[credentialSlot(url, projectId, orgId)];
+    if ('string' === typeof orgScoped && orgScoped.length > 0)
+        return orgScoped;
+    const composite = store[credentialSlot(url, projectId)];
+    if ('string' === typeof composite && composite.length > 0)
+        return composite;
+    const found = store[projectId];
+    if ('string' === typeof found)
+        return found.length > 0 ? found : undefined;
+    if ('object' !== typeof found || null === found)
+        return undefined;
+    const record = found;
+    const key = heldKeyOf(record);
+    const forUrl = record['url'];
+    if (key === undefined)
+        return undefined;
+    // A credential stamped with a DIFFERENT cloud is not this project's, however much the ids match.
+    if ('string' === typeof forUrl && normalizeUrl(forUrl) !== normalizeUrl(url))
+        return undefined;
+    return key;
+};
+/**
+ * Apply a link's key to the store, in place, and return it.
+ *
+ * The org slot is always ours to write. The two ambiguous slots are a compatibility shim for older
+ * daemons, and a shim must not corrupt what it is shimming:
+ *
+ *   - Overwriting a slot that holds a DIFFERENT live key would hand this key to whichever repo that
+ *     entry belongs to — the same cross-tenant disclosure as reusing theirs, pointing the other way.
+ *   - An EMPTY ambiguous slot is a trap too, because the resolver prefers cloud+project over the
+ *     bare legacy entry: filling a free `<url>::default` while another tenant's key sits in
+ *     `default` silently redirects THEIR repo to our key.
+ *
+ * So once another tenant is known to be on this machine, only the org slot is written. Our own
+ * stale or revoked key is not another tenant and is replaced normally — that is the ordinary
+ * re-link, and refusing it would strand the repo.
+ */
+export const applyCredential = (store, write) => {
+    const { projectId, url, key, orgId, priorKey, priorIsForeign } = write;
+    if (orgId !== undefined)
+        store[credentialSlot(url, projectId, orgId)] = key;
+    const mayOverwrite = (slot) => {
+        const held = heldKeyOf(store[slot]);
+        if (held === undefined)
+            return true; // free
+        if (held === key)
+            return true; // already ours
+        return held === priorKey && !priorIsForeign; // our own stale key, not somebody else's
+    };
+    const cloudSlot = credentialSlot(url, projectId);
+    if (!priorIsForeign && mayOverwrite(cloudSlot))
+        store[cloudSlot] = key;
+    if (!priorIsForeign && mayOverwrite(projectId))
+        store[projectId] = { key, url };
+    return store;
+};
+/** Where the store lives, given the reticle home directory. */
+export const credentialsPath = (homeDir, file) => join(homeDir, file);

package/dist/command/cli/auth/device-flow.d.ts

@@ -0,0 +1,76 @@
+/**
+ * The browser device flow's wire shapes and its hand-off to a real browser.
+ *
+ * `reticle login` works like `gh auth login`: the CLI asks the cloud for a device code, opens the
+ * approval page, and polls until a human confirms it in a session that is already signed in. That
+ * confirmation is the whole security of the flow — only somebody already authenticated in the
+ * dashboard can turn a device code into a token for their org.
+ *
+ * Split from `cloud-cli` because it is self-contained: the schemas describe two endpoints and the
+ * opener knows only about platforms. Nothing here reads a session, a credential, or a project.
+ */
+import { z } from 'zod';
+/** What `/v1/auth/device/start` answers: the codes, where to approve, and how fast to poll. */
+export declare const DeviceStartSchema: z.ZodObject<{
+    deviceCode: z.ZodString;
+    userCode: z.ZodString;
+    verificationUri: z.ZodString;
+    verificationUriComplete: z.ZodString;
+    interval: z.ZodNumber;
+    expiresAt: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    expiresAt: number;
+    deviceCode: string;
+    userCode: string;
+    verificationUri: string;
+    verificationUriComplete: string;
+    interval: number;
+}, {
+    expiresAt: number;
+    deviceCode: string;
+    userCode: string;
+    verificationUri: string;
+    verificationUriComplete: string;
+    interval: number;
+}>;
+/**
+ * What `/v1/auth/device/token` answers while polling. Everything past `status` is optional because
+ * only an APPROVED poll carries a token, and `org.id` is absent on a cloud older than org-scoped
+ * credentials.
+ */
+export declare const DevicePollSchema: z.ZodObject<{
+    status: z.ZodString;
+    token: z.ZodOptional<z.ZodString>;
+    org: z.ZodOptional<z.ZodObject<{
+        id: z.ZodOptional<z.ZodString>;
+        name: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        name: string;
+        id?: string | undefined;
+    }, {
+        name: string;
+        id?: string | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    status: string;
+    org?: {
+        name: string;
+        id?: string | undefined;
+    } | undefined;
+    token?: string | undefined;
+}, {
+    status: string;
+    org?: {
+        name: string;
+        id?: string | undefined;
+    } | undefined;
+    token?: string | undefined;
+}>;
+/**
+ * Best-effort open the approval page in the default browser.
+ *
+ * Every failure is swallowed on purpose: the URL is printed either way, and a headless box, a
+ * container, or an SSH session has no opener at all. Refusing to log in because a convenience did
+ * not work would break the one environment that most needs the printed fallback.
+ */
+export declare const openBrowser: (target: string) => void;

package/dist/command/cli/auth/device-flow.js

@@ -0,0 +1,56 @@
+/**
+ * The browser device flow's wire shapes and its hand-off to a real browser.
+ *
+ * `reticle login` works like `gh auth login`: the CLI asks the cloud for a device code, opens the
+ * approval page, and polls until a human confirms it in a session that is already signed in. That
+ * confirmation is the whole security of the flow — only somebody already authenticated in the
+ * dashboard can turn a device code into a token for their org.
+ *
+ * Split from `cloud-cli` because it is self-contained: the schemas describe two endpoints and the
+ * opener knows only about platforms. Nothing here reads a session, a credential, or a project.
+ */
+import { z } from 'zod';
+import { spawn } from 'node:child_process';
+import { NodePlatform } from '../../../machine/platform.js';
+/** What `/v1/auth/device/start` answers: the codes, where to approve, and how fast to poll. */
+export const DeviceStartSchema = z.object({
+    deviceCode: z.string(),
+    userCode: z.string(),
+    verificationUri: z.string(),
+    verificationUriComplete: z.string(),
+    interval: z.number(),
+    expiresAt: z.number(),
+});
+/**
+ * What `/v1/auth/device/token` answers while polling. Everything past `status` is optional because
+ * only an APPROVED poll carries a token, and `org.id` is absent on a cloud older than org-scoped
+ * credentials.
+ */
+export const DevicePollSchema = z.object({
+    status: z.string(),
+    token: z.string().optional(),
+    org: z.object({ id: z.string().optional(), name: z.string() }).optional(),
+});
+/**
+ * Best-effort open the approval page in the default browser.
+ *
+ * Every failure is swallowed on purpose: the URL is printed either way, and a headless box, a
+ * container, or an SSH session has no opener at all. Refusing to log in because a convenience did
+ * not work would break the one environment that most needs the printed fallback.
+ */
+export const openBrowser = (target) => {
+    const cmd = NodePlatform.MACOS === process.platform
+        ? 'open'
+        : NodePlatform.WINDOWS === process.platform
+            ? 'cmd'
+            : 'xdg-open';
+    const args = NodePlatform.WINDOWS === process.platform ? ['/c', 'start', '', target] : [target];
+    try {
+        const child = spawn(cmd, args, { stdio: 'ignore', detached: true });
+        child.on('error', () => undefined);
+        child.unref();
+    }
+    catch {
+        /* no opener available — the user opens the printed URL manually */
+    }
+};

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

@@ -0,0 +1,215 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { ReticleEnv } from '@reticlehq/core';
+import { readPid, reticleStateHome } from '../daemon/daemon.js';
+import { PortPresence, probePresence } from '../daemon/binding/port-presence.js';
+import { isLocalhostSplit, probeLoopbackReach } from '../daemon/binding/loopback-reach.js';
+import { probeDaemon } from '../../surface/mcp/mcp-proxy.js';
+import { fetchStatus } from '../daemon/binding/daemon-status-probe.js';
+import { daemonLine } from './doctor/doctor-daemon-line.js';
+import { projectWiringLine } from './doctor/doctor-project-line.js';
+import { hasProjectConnectedBefore } from '../../memory/recall/prior/connection-memory.js';
+import { sessionsLine } from './doctor/doctor-sessions-line.js';
+import { captureLookup, describeForeignHolder, findPortHolder } from './ports/port-holder.js';
+import { chromiumHint, probeChromium } from './doctor/browser/chromium-hint.js';
+import { SERVER_VERSION } from '../version/identity/server-version.js';
+import { CONTRACT_FINGERPRINT } from '@reticlehq/core';
+import { diagnoseDesktop, isDesktopProject, diagnoseWebCsp } from '@reticlehq/init';
+import { RETICLE_CONFIG_BASENAME, diagnosePortMismatch, readProjectId, readProjectPort, } from './ports/resolve/cli-port.js';
+import { DoctorRow, doctorRow } from './doctor/doctor-rows.js';
+import { attachState, describeAttachState } from '../../surface/mcp/attach-memory.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';
+/**
+ * `reticle doctor` — collapse the ~6 independent first-run failure modes into one command. Checks the
+ * Chromium install (the #1 silent failure), whether a daemon is up on the resolved bridge port, and
+ * reminds the user which port the app must dial. Human-readable to stdout (not the JSON log).
+ */
+/** Narrow the `/status` payload to the two fields the daemon line reads. */
+function asIdentity(payload) {
+    if (typeof payload !== 'object' || null === payload)
+        return {};
+    const record = payload;
+    const pick = (key) => {
+        const value = record[key];
+        return 'string' === typeof value && value.length > 0 ? value : undefined;
+    };
+    // Keys are OMITTED rather than set to undefined: `exactOptionalPropertyTypes` is on, and the
+    // distinction is the point — "this daemon did not say" is not the same as "this daemon said none".
+    const version = pick('version');
+    const contract = pick('contract');
+    return {
+        ...(version === undefined ? {} : { version }),
+        ...(contract === undefined ? {} : { contract }),
+    };
+}
+/**
+ * One project, two daemons — asked from whichever end this command is standing on.
+ *
+ * Shares the rule with `reticle status` rather than restating it: the empty daemon can see that the
+ * app connected somewhere else, the daemon holding the app can only see that this project owns
+ * another one, and a second copy of either half would be a second opinion waiting to disagree.
+ */
+function splitBrainLine(port, projectId) {
+    const home = reticleStateHome();
+    const elsewhere = splitBrainNote(port, daemonsServingProjectElsewhere(projectId, port, home, isAlive, (other) => hasProjectConnectedBefore(home, other, projectId)));
+    return elsewhere ?? wrongDaemonNote(port, resolveDaemonForProject(projectId, home, isAlive));
+}
+export async function handleDoctor(port) {
+    const line = (s) => {
+        process.stdout.write(`${s}\n`);
+    };
+    line('reticle doctor');
+    line(doctorRow(DoctorRow.NODE, process.version));
+    // Filled in only on the daemon branch — there is nothing to ask when no daemon is answering, and
+    // the branches below already say so in their own terms.
+    let sessions;
+    line(doctorRow(DoctorRow.CHROMIUM, chromiumHint(await probeChromium())));
+    // Ask the PORT, not just the pid file. "not running on :4400" has been printed about a port that
+    // was demonstrably occupied, which sends the reader to start a daemon that cannot bind. The three
+    // states are genuinely different problems with different fixes, so doctor names which one it is.
+    const pid = readPid(port);
+    const presence = await probePresence(port, { tcpOpen: probeDaemon, status: fetchStatus });
+    if (presence === PortPresence.DAEMON) {
+        // Name WHICH daemon. The /status payload already carries version + contract, and doctor was
+        // throwing both away — while skew is invisible everywhere else, reaching the agent as a bare
+        // -32000 naming no version. This is the command a human runs at exactly that moment.
+        const payload = await fetchStatus(port);
+        const status = asIdentity(payload);
+        const built = daemonLine(port, pid, status, {
+            version: SERVER_VERSION,
+            contract: CONTRACT_FINGERPRINT,
+        });
+        line(built.text);
+        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.
+        sessions = sessionsLine('object' === typeof payload && null !== payload ? payload : {});
+        // Only meaningful with a daemon answering: this asks which ADDRESS it answers on. `localhost` is
+        // a name with two answers and Windows Chrome tries the IPv6 one first, so a daemon that is up,
+        // healthy and bound to 127.0.0.1 alone is unreachable at the URL the SDK is told to dial. The
+        // alias that forwards `[::1]` is best-effort by contract, and its failure was recorded only as a
+        // field on one JSON log line — so every other row here goes green while the page cannot connect.
+        const reach = await probeLoopbackReach(port);
+        if (isLocalhostSplit(reach)) {
+            line(doctorRow(DoctorRow.LOOPBACK, `✗ :${port} answers on 127.0.0.1 but NOT on [::1], and \`localhost\` tries [::1] first on ` +
+                'Windows — so a page told to dial `localhost` cannot reach this daemon. Dial ' +
+                `\`127.0.0.1:${port}\` explicitly, or free whatever holds [::1]:${port}.`));
+        }
+    }
+    else if (presence === PortPresence.FOREIGN) {
+        // Name the holder when we can. `doctor` exists for exactly this moment, and "another process"
+        // leaves the reader to find a shell command themselves — the obvious one being the `lsof -ti`
+        // pipeline that also kills the agent's own MCP proxy.
+        // `pid` is what our pid file recorded for this port. When it matches the process actually
+        // holding it, this is our OWN daemon wedged, not a stranger — and the fix is different.
+        line(doctorRow(DoctorRow.DAEMON, `✗ ${describeForeignHolder(port, findPortHolder(port, captureLookup), pid)}`));
+    }
+    else {
+        line(doctorRow(DoctorRow.DAEMON, `✗ not running on :${port} — your agent runs \`reticle mcp\` (or \`reticle serve\`)`));
+    }
+    if (sessions !== undefined)
+        line(sessions.text);
+    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)
+        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
+    // did, and those two are exactly the pair a user cannot tell apart when one of them is broken.
+    const attach = attachState(reticleStateHome(), port);
+    const attachAction = describeAttachState(attach);
+    // A SPLIT outranks the attach record, and this is the one place it can. Both records are per PORT,
+    // so on a machine whose daemons have split in two the attach row reports "nothing has ever
+    // 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}`));
+    // 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)
+        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.
+    line(projectWiringLine({
+        projectId,
+        previouslyConnected: hasProjectConnectedBefore(reticleStateHome(), port, projectId),
+        // An absent config and a corrupt one both read back as "no id"; only this tells them apart,
+        // 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)),
+    }));
+    // 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
+    // docs/debugging.md.
+    line(doctorRow(DoctorRow.DAEMON_LOG, join(reticleStateHome(), `daemon-${String(port)}.log`)));
+    line(doctorRow(DoctorRow.TRACING, `${ReticleEnv.TRACE}=1 on the daemon for per-stage timings in that log`));
+    // Below the checklist rather than inline: it is a paragraph, and a paragraph in the middle of a
+    // column of one-line checks buries the checks under it. This is the daemon's own no-session
+    // diagnosis, the same one an agent gets from an empty reticle_sessions.
+    if (sessions?.why !== undefined) {
+        line('');
+        line('  nothing has connected. What the daemon can tell from here:');
+        line(`    ${sessions.why}`);
+    }
+    // Desktop setup RCA. Every one of these fails SILENTLY — a Tauri app with the default CSP runs
+    // perfectly and never connects; an Electron app without the preload line reports zero network
+    // activity forever, which reads as "makes no backend calls" rather than "you are blind to them".
+    const readProjectFile = (relative) => {
+        try {
+            return readFileSync(join(process.cwd(), relative), 'utf8');
+        }
+        catch {
+            return undefined;
+        }
+    };
+    // The web sibling of the desktop findings below: a `connect-src` that excludes the bridge makes
+    // the browser refuse the WebSocket and report it in ITS console only, so every check above passes
+    // at an app that can never connect. Named, with the exact text to paste.
+    const csp = diagnoseWebCsp(readProjectFile, port);
+    if (csp.length > 0) {
+        line('');
+        line(`  csp          ✗ a Content-Security-Policy is blocking the Reticle bridge:`);
+        for (const finding of csp) {
+            line(`                 ${finding.file}`);
+            line(`                   ${finding.problem}`);
+            line(`                   fix: ${finding.fix}`);
+        }
+    }
+    const desktop = diagnoseDesktop(readProjectFile, port);
+    if (desktop.length > 0) {
+        line('');
+        line(doctorRow(DoctorRow.DESKTOP, `✗ ${String(desktop.length)} issue(s) — the app will look fine and not work:`));
+        for (const finding of desktop) {
+            line(`                 ${finding.file}`);
+            line(`                   ${finding.problem}`);
+            line(`                   fix: ${finding.fix}`);
+        }
+    }
+    else if (isDesktopProject(readProjectFile)) {
+        // Say so explicitly. Silence would read as "not checked", which is the same ambiguity the
+        // findings above exist to remove.
+        line(doctorRow(DoctorRow.DESKTOP, '✓ desktop wiring looks right'));
+    }
+}

package/dist/command/cli/cli-flow-commands.d.ts

@@ -0,0 +1,47 @@
+/**
+ * CLI commands that operate on SAVED FLOWS: watch, capsules, and the gate.
+ *
+ * Split out of cli.ts, which was 653 lines — over the project's own cap, and the file a contributor
+ * opens first. These five functions form one cohesive group: they all read the flow store and report on
+ * verification state, and none of them touch daemon lifecycle, which is what the rest of cli.ts does.
+ */
+import { type ChangedFiles } from '../../language/flows/change/git-changed.js';
+import { type ProjectId } from '@reticlehq/core';
+import { type FileSystemPort } from '../../memory/project/fs/fs-port.js';
+import { type NamedFlow } from '../../language/flows/change/flow-sources.js';
+/** Load the {name, steps} of every saved flow for the active project. */
+/** Explicit files plus, when --since is given, the git-changed files since that ref. */
+/**
+ * `cwd` is the tree to diff, and it is a PARAMETER because the two callers do not share one. From a
+ * terminal `process.cwd()` is the project; inside a globally-registered daemon it is `/` or `$HOME`,
+ * where `git diff` answers about the wrong repository or about none.
+ */
+export declare function resolveChangedFiles(files: string[], since: string | undefined, cwd: string): Promise<ChangedFiles>;
+/**
+ * `projectId` is a PARAMETER for the same reason `reticleRoot` already is: the two together are one
+ * address, and reading half of it from a global made them disagree. Resolved through `sessionRoot`
+ * the root named the session's project while `readProjectId(process.cwd())` named the daemon's —
+ * and a daemon started outside a project has none, so the list came back EMPTY. `affected` renders
+ * that as "no saved flows exist yet" and `verify_change` as nothing covering the change: a
+ * confident negative about somebody else's project, which is worse than an error.
+ */
+export declare function loadNamedFlows(fs: FileSystemPort, reticleRoot: string, projectId: ProjectId | undefined): Promise<NamedFlow[]>;
+/**
+ * `reticle watch [url]` — on every save, report which saved flows must re-verify (the affected set).
+ * Environment-side (costs the agent nothing per turn); the buddy loop. This v1 detects + reports on
+ * change; auto-replaying the affected flows against the app is the next increment. Long-running.
+ */
+export declare function handleWatch(): void;
+/**
+ * `reticle capsules` — list saved fail-to-pass bug capsules (.reticle/capsules). Each is a minimal
+ * failing reproduction plus the consequence that should have held; replay one with reticle_flow_replay.
+ */
+export declare function handleCapsules(): Promise<void>;
+/**
+ * `reticle gate <file...>` — exit non-zero unless passing artifacts cover the flows affected by the
+ * changed files. Flaky flows are quarantined (surfaced, not blocking). The environment-side enforcement
+ * that makes verification unavoidable. Never throws; a fault fails closed (exit 1).
+ */
+export declare function handleGate(files: string[], since: string | undefined, 
+/** Hook mode: prose for a human, and silence when there was simply nothing to check. */
+hook?: boolean): Promise<void>;