@reticlehq/server 2.14.0 → 3.2.0

package/dist/command/cli/cloud-kit.d.ts

@@ -0,0 +1,37 @@
+import { type Session } from './auth/cloud-session.js';
+/** Where `reticle login` dials when nothing says otherwise: the hosted service. */
+export declare const DEFAULT_URL = "https://app.reticle.sh";
+export declare const RETICLE_DIR = ".reticle";
+export declare const SESSION_FILE = "session.json";
+export declare const CREDENTIALS_FILE = "credentials.json";
+/** The user-level reticle directory, `~/.reticle`. Sessions and credentials live here, not in a repo. */
+export declare const home: () => string;
+export declare const err: (msg: string) => void;
+/** A next-step nudge on stderr (humans read it; agents parse stdout JSON and ignore this). */
+export declare const hint: (msg: string) => void;
+export declare const emit: (obj: unknown) => void;
+/** Read + parse a JSON file, or null when missing/malformed (never throws). */
+export declare const readJson: (path: string) => Promise<unknown>;
+/** Parse `--flag value` pairs out of an argv tail. */
+export declare const flags: (argv: readonly string[]) => Record<string, string>;
+/** The ACTIVE session — the last host logged in to. What a bare command resolves its URL through. */
+export declare const readSession: () => Promise<Session | null>;
+/**
+ * The session for ONE host, or null.
+ *
+ * The whole safety property, holding by construction rather than by a guard somebody has to
+ * remember: a token is looked up BY the host it will be sent to, so no arrangement of environment
+ * variables can fetch one host's credential for a request to another. Falls back to `session.json`
+ * when it names this host, so a machine that logged in before per-host sessions existed is not
+ * silently signed out by an upgrade.
+ */
+export declare const readSessionFor: (url: string) => Promise<Session | null>;
+export declare const baseUrl: (session: {
+    url: string;
+} | null, explicit?: string) => string;
+/** Bearer for a command: an explicit api key (agent) wins, else the human login token. */
+export declare const bearer: (session: {
+    token: string;
+} | null) => string | null;
+/** One `/v1` call. Throws a friendly Error on a non-2xx so the command surfaces it and exits 1. */
+export declare const api: (method: string, url: string, token: string | null, body?: unknown) => Promise<unknown>;

package/dist/command/cli/cloud-kit.js

@@ -0,0 +1,117 @@
+/**
+ * The layer every cloud verb sits on: where files live, how output is written, and how a `/v1` call
+ * is made and authorised.
+ *
+ * Extracted because it was the reason `cloud-cli` could not be split. Each verb is small and mostly
+ * independent, but all of them reach for the same dozen helpers, so any attempt to lift one command
+ * out dragged the plumbing with it or duplicated it. Naming the layer makes the verbs separable —
+ * `cloud-login` is the first to move — and it is a real seam rather than a file-size dodge: nothing
+ * here knows what a project, a credential or a link is.
+ */
+import { apiKeyFrom } from '@reticlehq/core';
+import { readFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { z } from 'zod';
+import { cloudFetch } from '../../memory/cloud/cloud-sync.js';
+import { normalizeUrl, readSessionFrom, resolveSessionFor, sessionPath, } from './auth/cloud-session.js';
+/** Where `reticle login` dials when nothing says otherwise: the hosted service. */
+export const DEFAULT_URL = 'https://app.reticle.sh';
+export const RETICLE_DIR = '.reticle';
+export const SESSION_FILE = 'session.json';
+export const CREDENTIALS_FILE = 'credentials.json';
+/** The user-level reticle directory, `~/.reticle`. Sessions and credentials live here, not in a repo. */
+export const home = () => join(homedir(), RETICLE_DIR);
+export const err = (msg) => {
+    process.stderr.write(`reticle: ${msg}\n`);
+};
+/** A next-step nudge on stderr (humans read it; agents parse stdout JSON and ignore this). */
+export const hint = (msg) => {
+    process.stderr.write(`→ ${msg}\n`);
+};
+export const emit = (obj) => {
+    process.stdout.write(`${JSON.stringify(obj, null, 2)}\n`);
+};
+/** Read + parse a JSON file, or null when missing/malformed (never throws). */
+export const readJson = async (path) => {
+    try {
+        return JSON.parse(await readFile(path, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+};
+/** Parse `--flag value` pairs out of an argv tail. */
+export const flags = (argv) => {
+    const f = {};
+    for (let i = 0; i < argv.length; i += 1) {
+        const a = argv[i];
+        if (a !== undefined && a.startsWith('--') && i + 1 < argv.length) {
+            const v = argv[i + 1];
+            if (v !== undefined)
+                f[a.slice(2)] = v;
+            i += 1;
+        }
+    }
+    return f;
+};
+/** The ACTIVE session — the last host logged in to. What a bare command resolves its URL through. */
+export const readSession = async () => readSessionFrom(readJson(join(home(), SESSION_FILE)));
+/**
+ * The session for ONE host, or null.
+ *
+ * The whole safety property, holding by construction rather than by a guard somebody has to
+ * remember: a token is looked up BY the host it will be sent to, so no arrangement of environment
+ * variables can fetch one host's credential for a request to another. Falls back to `session.json`
+ * when it names this host, so a machine that logged in before per-host sessions existed is not
+ * silently signed out by an upgrade.
+ */
+export const readSessionFor = async (url) => resolveSessionFor(url, await readSessionFrom(readJson(sessionPath(home(), url))), await readSession());
+export const baseUrl = (session, explicit) => {
+    // `--url` wins over the environment: it is typed for THIS command, it is visible in shell history,
+    // and it cannot leak into a sibling process the way an exported variable does.
+    if (explicit !== undefined && explicit.length > 0)
+        return normalizeUrl(explicit);
+    const env = process.env['RETICLE_CLOUD_URL'];
+    if (env !== undefined && env.length > 0)
+        return env.replace(/\/+$/, '');
+    if (null !== session && session.url.length > 0)
+        return session.url;
+    // No hint here any more. This used to warn that it was falling back to localhost, which was worth
+    // saying because that default was wrong for everyone except us. The default is now the hosted
+    // service, so the fallback IS the intended path — and a warning printed on the correct path is
+    // how people learn to ignore stderr, which is where the real problems are written.
+    return DEFAULT_URL;
+};
+/** Bearer for a command: an explicit api key (agent) wins, else the human login token. */
+export const bearer = (session) => apiKeyFrom(process.env) ?? session?.token ?? null;
+/** One `/v1` call. Throws a friendly Error on a non-2xx so the command surfaces it and exits 1. */
+export const api = async (method, url, token, body) => {
+    const headers = {};
+    if (token !== null)
+        headers['authorization'] = `Bearer ${token}`;
+    if (body !== undefined)
+        headers['content-type'] = 'application/json';
+    const init = {
+        method,
+        headers,
+    };
+    if (body !== undefined)
+        init.body = JSON.stringify(body);
+    const res = await cloudFetch(url, init);
+    const text = await res.text();
+    let json = null;
+    if (text.length > 0) {
+        try {
+            json = JSON.parse(text);
+        }
+        catch {
+            throw new Error(`expected JSON from ${method} ${url} but got: ${text.slice(0, 120)}`);
+        }
+    }
+    if (!res.ok) {
+        const parsed = z.object({ error: z.object({ message: z.string() }) }).safeParse(json);
+        throw new Error(parsed.success ? parsed.data.error.message : `${res.status} ${res.statusText}`);
+    }
+    return json;
+};

package/dist/command/cli/cloud-login.js

@@ -0,0 +1,183 @@
+/**
+ * `reticle login` and `reticle logout` — getting a session onto this machine, and off it.
+ *
+ * Split from `cloud-cli` because this is a coherent story on its own: prove who you are, write the
+ * token where the other verbs will find it, and finish the job by binding the repo you are standing
+ * in. The rest of the CLI reads sessions; only this file creates and destroys them.
+ *
+ * `cmdLink` arrives as a PARAMETER rather than an import. Login ends by linking and link needs a
+ * session, so the two genuinely depend on each other; passing the linker in breaks the cycle at the
+ * one call site instead of merging two commands into one file to satisfy the module graph.
+ */
+import { mkdir, rm, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { z } from 'zod';
+import { setTimeout as sleep } from 'node:timers/promises';
+import { createNodeFileSystem } from '../../memory/project/fs/fs-port.js';
+import { CLOUD_LINK_FILE } from '../../memory/cloud/cloud-config.js';
+import { RETICLE_CONFIG_BASENAME } from './ports/resolve/cli-port.js';
+import { DevicePollSchema, DeviceStartSchema, openBrowser } from './auth/device-flow.js';
+import { normalizeUrl, sessionPath, SESSIONS_DIR } from './auth/cloud-session.js';
+import { api, baseUrl, emit, err, flags, hint, home, readSession, RETICLE_DIR, SESSION_FILE, } from './cloud-kit.js';
+const LoginSchema = z.object({
+    token: z.string(),
+    org: z.object({ id: z.string().optional(), name: z.string() }),
+});
+/**
+ * `reticle login --email <e> [--org <name>] [--code <123456>]` — sign in, cache the token under
+ * ~/.reticle.
+ *
+ * TWO STEPS, because the cloud proves you own the inbox before it hands out a session: ask for a code,
+ * then exchange it. (It used to take an email alone — which meant anyone who knew your address owned your
+ * org.) `--org` is only consulted when the account is brand new; a returning user never needs it.
+ *
+ * Without `--code` we request one and stop, telling the user to re-run with it. The one exception is a
+ * LOCAL cloud, whose dev mailer cannot actually deliver mail and so echoes the code back in its response
+ * (`devCode`) — there we complete the login in a single command rather than asking a developer to read a
+ * code out of a server log they may not even be tailing.
+ */
+const RequestCodeSchema = z.object({ devCode: z.string().optional() });
+/** Persist a session token under ~/.reticle and print the next step. Shared by both login paths. */
+const writeSession = async (url, token, orgName, orgId, project, link) => {
+    await mkdir(join(home(), SESSIONS_DIR), { recursive: true });
+    const body = `${JSON.stringify({ url: normalizeUrl(url), token, orgName, ...(orgId === undefined ? {} : { orgId }) }, null, 2)}\n`;
+    // Both, on purpose. The per-host file is what lets another environment stay logged in; the active
+    // file is what a bare command with no override resolves through, and keeping it means nothing
+    // about the single-environment workflow changes.
+    await writeFile(sessionPath(home(), url), body);
+    await writeFile(join(home(), SESSION_FILE), body);
+    emit({ loggedIn: orgName, session: join(home(), SESSION_FILE) });
+    await linkAfterLogin(url, project, link);
+};
+/**
+ * Finish the job when the shell is already standing in an unlinked Reticle project.
+ *
+ * `login` used to end by printing "next: `reticle link`", which made getting from local-only to
+ * reporting a TWO command trip whose second half nothing enforces — and the HUD's own invitation
+ * names one command, so the gap was ours to close rather than the reader's to notice. Somebody who
+ * ran `reticle login` inside their instrumented repo wanted their runs on the dashboard; there is no
+ * second thing they could have meant.
+ *
+ * Deliberately narrow, because a login that writes files in a directory the user did not mean is
+ * worse than an extra step:
+ *   - a `.reticle.json` must already exist. That is what `init` writes and what puts a projectId in
+ *     the app's BUNDLE, which is the only thing letting the daemon attribute runs to this repo. A
+ *     bare `.reticle/` directory is NOT the marker: gating on it produced repos that were linked and
+ *     structurally unable to report, whose runs pooled under the daemon's own root instead.
+ *   - an existing `cloud.json` is left completely alone. Re-linking would re-resolve the project and
+ *     is exactly how somebody re-pointing an environment loses a binding they meant to keep.
+ *   - a failure is reported and swallowed. The login SUCCEEDED and its token is already on disk;
+ *     turning that into a non-zero exit would make the recoverable half look like the broken one.
+ */
+const linkAfterLogin = async (url, project, link) => {
+    const fs = createNodeFileSystem();
+    /*
+     * The marker is `.reticle.json`, NOT a `.reticle/` directory.
+     *
+     * `.reticle.json` is what `init` writes and what puts a projectId in the app's bundle, which is
+     * the only thing that lets the daemon attribute a session's runs to this repo. A bare `.reticle/`
+     * proves nothing — it is also created by artifacts and by older builds — and auto-linking on it
+     * produced a repo that was LINKED to a cloud project and yet unable to report to it: runs pooled
+     * into the daemon's own ledger, and `reticle sync` here answered "nothing to send" straight after
+     * two verdicts had been recorded. Measured, on this very repo's bench app.
+     */
+    if (!(await fs.exists(join(process.cwd(), RETICLE_CONFIG_BASENAME)))) {
+        hint('next: `reticle init` here first, then `reticle link` — or log in from a project directory');
+        return;
+    }
+    /*
+     * An explicit `--project` is an instruction, so it re-binds even a repo that is already linked.
+     * Without a project named, an existing binding is left completely alone — re-resolving it is how
+     * somebody repointing an environment loses a binding they meant to keep.
+     */
+    if (project === undefined &&
+        (await fs.exists(join(process.cwd(), RETICLE_DIR, CLOUD_LINK_FILE)))) {
+        hint('this repo is already linked — `reticle push` to send what it has recorded');
+        return;
+    }
+    try {
+        await link(project === undefined ? ['--url', url] : ['--url', url, '--project', project]);
+    }
+    catch {
+        hint('signed in, but linking this repo failed — run `reticle link` to retry');
+    }
+};
+/**
+ * Browser device flow — the DEFAULT `reticle login` (like `gh auth login`): fetch a device + user code,
+ * open the browser to approve, then poll until the user confirms. No email to type, no code to copy back.
+ */
+const cmdLoginDevice = async (explicitUrl, project, link) => {
+    const url = baseUrl(null, explicitUrl);
+    const started = DeviceStartSchema.parse(await api('POST', `${url}/v1/auth/device/start`, null, {}));
+    hint(`Opening ${started.verificationUri} — confirm this code in the browser: ${started.userCode}`);
+    openBrowser(started.verificationUriComplete);
+    const intervalMs = Math.max(1, started.interval) * 1000;
+    for (;;) {
+        await sleep(intervalMs);
+        const poll = DevicePollSchema.parse(await api('POST', `${url}/v1/auth/device/token`, null, { deviceCode: started.deviceCode }));
+        if ('approved' === poll.status && poll.token !== undefined && poll.org !== undefined) {
+            await writeSession(url, poll.token, poll.org.name, poll.org.id, project, link);
+            return 0;
+        }
+        if ('pending' === poll.status) {
+            if (Date.now() > started.expiresAt) {
+                err('device login expired — run `reticle login` again');
+                return 1;
+            }
+            continue;
+        }
+        err('denied' === poll.status
+            ? 'device login was denied in the browser'
+            : 'device login expired — run `reticle login` again');
+        return 1;
+    }
+};
+/**
+ * `reticle login` — browser device flow by default; `--email <e>` (or a positional email) keeps the
+ * headless two-step code path for CI/servers where opening a browser makes no sense.
+ */
+export const cmdLogin = async (argv, link) => {
+    const f = flags(argv);
+    const positional = argv[0] !== undefined && !argv[0].startsWith('--') ? argv[0] : undefined;
+    const email = f['email'] ?? positional;
+    if (email === undefined)
+        return cmdLoginDevice(f['url'], f['project'], link);
+    const org = f['org'];
+    const url = baseUrl(null, f['url']);
+    let code = f['code'];
+    if (code === undefined) {
+        const requested = RequestCodeSchema.parse(await api('POST', `${url}/v1/auth/request-code`, null, {
+            email,
+            ...(org !== undefined ? { orgName: org } : {}),
+        }));
+        // A real cloud mails the code and never echoes it; a local one cannot mail, so it hands it back.
+        if (requested.devCode === undefined) {
+            emit({ codeSent: true, to: email });
+            hint(`check your inbox, then: \`reticle login --email ${email} --code <the 6-digit code>\``);
+            return 0;
+        }
+        code = requested.devCode;
+    }
+    const parsed = LoginSchema.parse(await api('POST', `${url}/v1/auth/login`, null, { email, code }));
+    await writeSession(url, parsed.token, parsed.org.name, parsed.org.id, f['project'], link);
+    return 0;
+};
+/** `reticle logout` — forget the cached session token (per-project keys under credentials.json stay). */
+/**
+ * `reticle logout` — sign out of ONE host, not of everywhere.
+ *
+ * Which host is the same question every other verb asks: `--url`, else the environment, else the
+ * active session. Signing out of staging must leave production alone — a logout that quietly
+ * cleared every environment would be discovered at the worst possible moment, mid-incident, on the
+ * one you did not mean.
+ */
+export const cmdLogout = async (argv = []) => {
+    const active = await readSession();
+    const url = baseUrl(active, flags(argv)['url']);
+    await rm(sessionPath(home(), url), { force: true }).catch(() => undefined);
+    // The active pointer only moves if it was pointing at the host just signed out of.
+    if (null !== active && normalizeUrl(active.url) === url)
+        await writeFile(join(home(), SESSION_FILE), '').catch(() => undefined);
+    emit({ loggedOut: true, url });
+    return 0;
+};

package/dist/command/cli/config/config-discovery.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Where the project config actually is, and — when we cannot find it — where we looked.
+ *
+ * `findProjectConfig` walks UP from the daemon's working directory, which is right for a developer
+ * who ran `reticle` in their project and wrong for the way most daemons are actually started.
+ * Editors launch MCP servers from wherever they like, and in at least one popular one that is the
+ * user's home directory: the config then sits at `<repo>/apps/web/.reticle.json`, the up-walk from
+ * home never touches it, and Reticle confidently reports the project unwired. Reported twice, plus a
+ * git-worktree variant of the same shape.
+ *
+ * So: walk up, then — from the repo root, if there is one — look in the workspace directories the
+ * project's OWN manifest declares, falling back to the two conventions everybody uses.
+ *
+ * The second half is the `searched` list. "There is no `.reticle.json`" is unfalsifiable without it,
+ * and this file exists because that claim was made, confidently, about configs that were right
+ * there. Every result carries the places that were checked.
+ *
+ * Deliberately NOT a "pick one" function. Several configs means several projects, and choosing one
+ * silently is how an agent ends up with a confident verdict about an app it never touched. Callers
+ * are handed the list and must name it.
+ */
+interface FoundConfig {
+    /** Absolute path to the `.reticle.json`. */
+    path: string;
+    /** The directory it configures — what a reader needs in order to act. */
+    directory: string;
+    /** Its projectId, when it declares a usable one. */
+    projectId?: string;
+}
+export interface ConfigDiscovery {
+    found: FoundConfig[];
+    /** Every directory checked, in the order checked. The answer to "are you sure?". */
+    searched: string[];
+}
+/**
+ * Has this directory ever been through `init` — is there a `.reticle.json` in it?
+ *
+ * A single directory, not a walk: the caller is asking whether THIS tree invited Reticle in, which
+ * is what decides whether a session with no resolvable project may write here at all. An ancestor's
+ * config says nothing about that, so the up-walk `discoverProjectConfigs` does would answer a
+ * different question and answer it yes too often.
+ *
+ * Lives here so the question stays in the directory that owns the config file, rather than every
+ * caller importing the basename and re-deriving the join.
+ */
+export declare function hasProjectConfig(directory: string): boolean;
+export declare function discoverProjectConfigs(cwd: string): ConfigDiscovery;
+export {};

package/dist/command/cli/config/config-discovery.js

@@ -0,0 +1,183 @@
+/**
+ * Where the project config actually is, and — when we cannot find it — where we looked.
+ *
+ * `findProjectConfig` walks UP from the daemon's working directory, which is right for a developer
+ * who ran `reticle` in their project and wrong for the way most daemons are actually started.
+ * Editors launch MCP servers from wherever they like, and in at least one popular one that is the
+ * user's home directory: the config then sits at `<repo>/apps/web/.reticle.json`, the up-walk from
+ * home never touches it, and Reticle confidently reports the project unwired. Reported twice, plus a
+ * git-worktree variant of the same shape.
+ *
+ * So: walk up, then — from the repo root, if there is one — look in the workspace directories the
+ * project's OWN manifest declares, falling back to the two conventions everybody uses.
+ *
+ * The second half is the `searched` list. "There is no `.reticle.json`" is unfalsifiable without it,
+ * and this file exists because that claim was made, confidently, about configs that were right
+ * there. Every result carries the places that were checked.
+ *
+ * Deliberately NOT a "pick one" function. Several configs means several projects, and choosing one
+ * silently is how an agent ends up with a confident verdict about an app it never touched. Callers
+ * are handed the list and must name it.
+ */
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { RETICLE_CONFIG_BASENAME } from '../ports/resolve/cli-port.js';
+/** How far up to walk. Matches the existing config search so the two cannot disagree. */
+const MAX_UP_LEVELS = 6;
+/**
+ * Workspace directories checked when the manifest declares none.
+ *
+ * Not a guess at where an app might be — these are the two layouts the JS ecosystem converged on,
+ * and both reported cases used one of them.
+ */
+const CONVENTIONAL_WORKSPACES = ['apps', 'packages'];
+/** How many entries of one workspace directory to stat. A backstop, not a policy. */
+const MAX_WORKSPACE_ENTRIES = 64;
+function readConfig(directory) {
+    const path = join(directory, RETICLE_CONFIG_BASENAME);
+    try {
+        const parsed = JSON.parse(readFileSync(path, 'utf8'));
+        if ('object' !== typeof parsed || null === parsed || Array.isArray(parsed))
+            return undefined;
+        const projectId = parsed['projectId'];
+        return {
+            path,
+            directory,
+            ...('string' === typeof projectId && projectId.length > 0 ? { projectId } : {}),
+        };
+    }
+    catch {
+        // Absent, unreadable, or not JSON. A malformed config is reported elsewhere; here it is simply
+        // not a config we can name a project from.
+        return undefined;
+    }
+}
+/** The nearest ancestor holding a `.git`, or undefined. The repo root is where workspaces hang off. */
+function repoRootOf(start) {
+    let dir = start;
+    for (let level = 0; level <= MAX_UP_LEVELS; level += 1) {
+        if (existsSync(join(dir, '.git')))
+            return dir;
+        const parent = dirname(dir);
+        if (parent === dir)
+            return undefined;
+        dir = parent;
+    }
+    return undefined;
+}
+/**
+ * The workspace directories this repo declares, from its own manifest where it has one.
+ *
+ * Reading `pnpm-workspace.yaml` with a substring scan rather than a YAML parser is deliberate: the
+ * only thing wanted from it is the leading path segment of each glob, the file is machine-written in
+ * practice, and a parser dependency to read one list of strings does not pay for itself.
+ */
+function declaredWorkspaceDirs(repoRoot) {
+    const dirs = new Set();
+    try {
+        const pkg = JSON.parse(readFileSync(join(repoRoot, 'package.json'), 'utf8'));
+        if ('object' === typeof pkg && null !== pkg) {
+            const workspaces = pkg['workspaces'];
+            const globs = Array.isArray(workspaces)
+                ? workspaces
+                : 'object' === typeof workspaces && null !== workspaces
+                    ? (workspaces['packages'] ?? [])
+                    : [];
+            if (Array.isArray(globs)) {
+                for (const glob of globs)
+                    if ('string' === typeof glob)
+                        dirs.add(firstSegment(glob));
+            }
+        }
+    }
+    catch {
+        // No manifest, or one we cannot read. The conventions below still apply.
+    }
+    try {
+        const yaml = readFileSync(join(repoRoot, 'pnpm-workspace.yaml'), 'utf8');
+        for (const line of yaml.split('\n')) {
+            const match = /^\s*-\s*['"]?([^'"\s]+)/.exec(line);
+            const glob = match?.[1];
+            if (glob !== undefined)
+                dirs.add(firstSegment(glob));
+        }
+    }
+    catch {
+        // Not a pnpm workspace.
+    }
+    for (const conventional of CONVENTIONAL_WORKSPACES)
+        dirs.add(conventional);
+    return [...dirs].filter((dir) => dir.length > 0 && !dir.startsWith('.'));
+}
+/** `apps/*` -> `apps`. The glob machinery is not needed; the leading directory is all we scan. */
+function firstSegment(glob) {
+    const [first] = glob.split('/');
+    return first ?? '';
+}
+/**
+ * Has this directory ever been through `init` — is there a `.reticle.json` in it?
+ *
+ * A single directory, not a walk: the caller is asking whether THIS tree invited Reticle in, which
+ * is what decides whether a session with no resolvable project may write here at all. An ancestor's
+ * config says nothing about that, so the up-walk `discoverProjectConfigs` does would answer a
+ * different question and answer it yes too often.
+ *
+ * Lives here so the question stays in the directory that owns the config file, rather than every
+ * caller importing the basename and re-deriving the join.
+ */
+export function hasProjectConfig(directory) {
+    try {
+        return existsSync(join(directory, RETICLE_CONFIG_BASENAME));
+    }
+    catch {
+        return false;
+    }
+}
+export function discoverProjectConfigs(cwd) {
+    const searched = [];
+    const found = [];
+    const seen = new Set();
+    const check = (directory) => {
+        if (seen.has(directory))
+            return;
+        seen.add(directory);
+        searched.push(directory);
+        const config = readConfig(directory);
+        if (config !== undefined)
+            found.push(config);
+    };
+    let dir = resolve(cwd);
+    for (let level = 0; level <= MAX_UP_LEVELS; level += 1) {
+        check(dir);
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    const repoRoot = repoRootOf(resolve(cwd));
+    if (repoRoot === undefined)
+        return { found, searched };
+    for (const workspace of declaredWorkspaceDirs(repoRoot)) {
+        const base = join(repoRoot, workspace);
+        let entries = [];
+        try {
+            entries = readdirSync(base).slice(0, MAX_WORKSPACE_ENTRIES);
+        }
+        catch {
+            continue; // A declared workspace directory that does not exist is not an error here.
+        }
+        check(base);
+        for (const entry of entries) {
+            const candidate = join(base, entry);
+            try {
+                if (!statSync(candidate).isDirectory())
+                    continue;
+            }
+            catch {
+                continue;
+            }
+            check(candidate);
+        }
+    }
+    return { found, searched };
+}

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

@@ -0,0 +1,33 @@
+/**
+ * Turn the parsed `_daemon` / `serve` flags into the options `startDaemon` takes.
+ *
+ * Extracted from `handleDaemonInner` to be testable, because the thing it got wrong was invisible
+ * from outside: `headless` used to be spread INSIDE the `driveUrl !== undefined` branch, so
+ * `reticle serve --headed` — no `--drive` — parsed the flag correctly and then dropped it on the
+ * floor. `startDaemon` fell back to `headless ?? true` and the pool launched hidden, which reads to
+ * a user as "--headed does nothing" and cost a real session of being told a run was visible when
+ * four chrome-headless-shell processes said otherwise.
+ *
+ * `headless` and `driveUrl` are independent: the flag governs the shared browser POOL (leases,
+ * replay, the spec runner), which exists whether or not a drive URL was named.
+ */
+import type { StartOptions } from '../../index.js';
+type DaemonFlags = {
+    port: number;
+    driveUrl?: string;
+    headless: boolean;
+    http: boolean;
+    httpPort?: number;
+    httpToken?: string;
+};
+export declare function daemonStartOptions(parsed: DaemonFlags): StartOptions;
+/**
+ * The argv a parent hands its detached `_daemon` child.
+ *
+ * `serve` and `mcp` each built this list by hand and each made the SAME mistake as the options
+ * builder above — pushing `--headed` only inside the `driveUrl` branch — so the flag survived
+ * parsing, was dropped at the spawn, and the child launched a hidden pool. Three sites, one wrong
+ * idea: that headless belongs to the drive URL. It belongs to the pool, which exists either way.
+ */
+export declare function daemonSpawnArgs(parsed: DaemonFlags): string[];
+export {};