@reticlehq/server 2.4.0 → 2.6.0

package/dist/capsule/divergence.js

@@ -1,28 +1,28 @@
-import { EventType } from '@reticlehq/core';
+import { ConsequenceKind, EventType } from '@reticlehq/core';
 function net(events) {
     return events.filter((e) => e.type === EventType.NET_REQUEST);
 }
 function satisfies(link, events) {
     switch (link.kind) {
-        case 'signal':
+        case ConsequenceKind.SIGNAL:
             return events.some((e) => e.type === EventType.SIGNAL && e.data['name'] === link.name);
-        case 'state':
+        case ConsequenceKind.STATE:
             return events.some((e) => e.type === EventType.STATE_CHANGE && e.data['name'] === link.name);
-        case 'net':
-            return net(events).some((e) => typeof e.data['url'] === 'string' &&
+        case ConsequenceKind.NET:
+            return net(events).some((e) => 'string' === typeof e.data['url'] &&
                 e.data['url'].includes(link.urlContains) &&
                 (link.status === undefined || e.data['status'] === link.status));
     }
 }
 /** Describe what WAS observed for a link that failed — the closest attempt, for a side-by-side. */
 function observedFor(link, events) {
-    if (link.kind === 'net') {
-        const match = net(events).find((e) => typeof e.data['url'] === 'string' && e.data['url'].includes(link.urlContains));
+    if (ConsequenceKind.NET === link.kind) {
+        const match = net(events).find((e) => 'string' === typeof e.data['url'] && e.data['url'].includes(link.urlContains));
         if (match === undefined)
             return `no request to ${link.urlContains}`;
         return `${link.urlContains} responded ${String(match.data['status'])} (expected ${String(link.status)})`;
     }
-    if (link.kind === 'signal')
+    if (ConsequenceKind.SIGNAL === link.kind)
         return `signal "${link.name}" never fired`;
     return `state "${link.name}" never changed`;
 }

package/dist/capsule/predicate-to-links.js

@@ -1,3 +1,4 @@
+import { ConsequenceKind, PredicateKind } from '@reticlehq/core';
 /**
  * Convert a mustHold predicate into the ordered ExpectedLinks the divergence capsule walks. Only the
  * consequence kinds (signal/net/state) become links — a presence check (element/text) can't diverge in a
@@ -5,24 +6,26 @@
  */
 export function predicateToExpectedLinks(predicate) {
     switch (predicate.kind) {
-        case 'signal':
-            return predicate.name === undefined ? [] : [{ kind: 'signal', name: predicate.name }];
-        case 'net':
+        case PredicateKind.SIGNAL:
+            return predicate.name === undefined
+                ? []
+                : [{ kind: ConsequenceKind.SIGNAL, name: predicate.name }];
+        case PredicateKind.NET:
             return predicate.urlContains === undefined
                 ? []
                 : [
                     {
-                        kind: 'net',
+                        kind: ConsequenceKind.NET,
                         urlContains: predicate.urlContains,
                         ...(predicate.status === undefined ? {} : { status: predicate.status }),
                     },
                 ];
-        case 'state': {
+        case PredicateKind.STATE: {
             const name = predicate.store ?? predicate.path;
-            return [{ kind: 'state', name }];
+            return [{ kind: ConsequenceKind.STATE, name }];
         }
-        case 'allOf':
-        case 'anyOf':
+        case PredicateKind.ALL_OF:
+        case PredicateKind.ANY_OF:
             return predicate.predicates.flatMap(predicateToExpectedLinks);
         default:
             return [];

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

@@ -0,0 +1 @@
+export declare function handleDoctor(port: number): Promise<void>;

package/dist/cli/cli-doctor.js

@@ -0,0 +1,135 @@
+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/port-presence.js';
+import { probeDaemon } from '../mcp/mcp-proxy.js';
+import { fetchStatus } from './cli-launch.js';
+import { daemonLine } from './doctor-daemon-line.js';
+import { describeForeignHolder, findPortHolder } from './port-holder.js';
+import { spawnSync } from 'node:child_process';
+import { SERVER_VERSION } from '../version/server-version.js';
+import { CONTRACT_FINGERPRINT } from '@reticlehq/core';
+import { diagnoseDesktop, isDesktopProject } from '../init/desktop-doctor.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).
+ */
+/**
+ * Run a lookup and return its stdout, or null if it could not run.
+ *
+ * Null on ANY failure — no lsof (every Windows user, a slim container), a non-zero exit, a throw.
+ * This is a diagnostic nicety inside the command people run when things are already broken; it must
+ * never be the reason `doctor` fails. `describeForeignHolder` handles the null by saying it could
+ * not identify the holder and naming our recorded pid, rather than asserting the holder is not ours
+ * — a claim it has no evidence for, and one that was wrong for every Windows user.
+ */
+function runCapture(command, args) {
+    try {
+        const result = spawnSync(command, [...args], { encoding: 'utf8', timeout: LOOKUP_TIMEOUT_MS });
+        return 0 === result.status && 'string' === typeof result.stdout ? result.stdout : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Bound on the holder lookup. A hung `lsof` must not hang the command that diagnoses hangs. */
+const LOOKUP_TIMEOUT_MS = 2_000;
+/** 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 }),
+    };
+}
+export async function handleDoctor(port) {
+    const line = (s) => {
+        process.stdout.write(`${s}\n`);
+    };
+    line('reticle doctor');
+    line(`  node         ${process.version}`);
+    try {
+        const { chromium } = await import('playwright');
+        const path = chromium.executablePath();
+        line(existsSync(path)
+            ? '  chromium     ✓ installed'
+            : '  chromium     ✗ missing — run: npx playwright install chromium');
+    }
+    catch {
+        line('  chromium     ✗ missing — run: npx playwright install chromium');
+    }
+    // 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 status = asIdentity(await fetchStatus(port));
+        const built = daemonLine(port, pid, status, {
+            version: SERVER_VERSION,
+            contract: CONTRACT_FINGERPRINT,
+        });
+        line(built.text);
+        if (built.skew !== undefined)
+            line(`  version      ✗ ${built.skew}`);
+    }
+    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(`  daemon       ✗ ${describeForeignHolder(port, findPortHolder(port, runCapture), pid)}`);
+    }
+    else {
+        line(`  daemon       ✗ not running on :${port} — your agent runs \`reticle mcp\` (or \`reticle serve\`)`);
+    }
+    line(`  bridge port  ${port}  (your app must dial THIS port — not your dev-server port)`);
+    // 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(`  daemon log   ${join(reticleStateHome(), `daemon-${String(port)}.log`)}`);
+    line(`  tracing      ${ReticleEnv.TRACE}=1 on the daemon for per-stage timings in that log`);
+    // 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;
+        }
+    };
+    const desktop = diagnoseDesktop(readProjectFile, port);
+    if (desktop.length > 0) {
+        line('');
+        line(`  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('  desktop      ✓ desktop wiring looks right');
+    }
+}

package/dist/{cli-flow-commands.d.ts → cli/cli-flow-commands.d.ts}

@@ -5,8 +5,8 @@
  * 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 FileSystemPort } from './project/fs-port.js';
-import { type NamedFlow } from './flows/flow-sources.js';
+import { type FileSystemPort } from '../project/fs-port.js';
+import { type NamedFlow } from '../flows/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. */
 export declare function resolveChangedFiles(files: string[], since: string | undefined): Promise<string[]>;

package/dist/{cli-flow-commands.js → cli/cli-flow-commands.js}

@@ -6,23 +6,23 @@
  * verification state, and none of them touch daemon lifecycle, which is what the rest of cli.ts does.
  */
 import { readProjectId } from './cli-port.js';
-import { changedFilesSince } from './flows/git-changed.js';
+import { changedFilesSince } from '../flows/git-changed.js';
 import { join } from 'node:path';
 import { ReticleDir, RunFlowStatus } from '@reticlehq/core';
-import { FlowStore } from './flows/flows.js';
-import { RunStore } from './runs/run-store.js';
-import { createNodeFileSystem } from './project/fs-port.js';
-import { affectedSavedFlows } from './flows/flow-sources.js';
-import { gateDecision } from './flows/gate.js';
-import { FlakeStore } from './flows/flake-store.js';
-import { formatBuddyStatus } from './flows/buddy-status.js';
-import { CapsuleStore } from './capsule/capsule-store.js';
-import { AssertionTiersStore } from './flows/assertion-tiers-store.js';
-import { detectDowngrades } from './flows/assertion-integrity.js';
-import { computeCoverage } from './flows/coverage.js';
-import { createWatchBatcher } from './flows/watch-batcher.js';
+import { FlowStore } from '../flows/flows.js';
+import { RunStore } from '../runs/run-store.js';
+import { createNodeFileSystem } from '../project/fs-port.js';
+import { affectedSavedFlows } from '../flows/flow-sources.js';
+import { gateDecision } from '../flows/gate.js';
+import { FlakeStore } from '../flows/flake-store.js';
+import { formatBuddyStatus } from '../flows/buddy-status.js';
+import { CapsuleStore } from '../capsule/capsule-store.js';
+import { AssertionTiersStore } from '../flows/assertion-tiers-store.js';
+import { detectDowngrades } from '../flows/assertion-integrity.js';
+import { computeCoverage } from '../flows/coverage.js';
+import { createWatchBatcher } from '../flows/watch-batcher.js';
 import { watch } from 'node:fs';
-import { log } from './log.js';
+import { log } from '../log.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. */
 export async function resolveChangedFiles(files, since) {
@@ -107,7 +107,7 @@ export function handleWatch() {
         .then((flows) => emitBuddyStatus(fs, reticleRoot, flows, []))
         .catch(() => undefined);
     watch(process.cwd(), { recursive: true }, (_event, filename) => {
-        if (typeof filename === 'string' && WATCHED_EXTENSIONS.test(filename))
+        if ('string' === typeof filename && WATCHED_EXTENSIONS.test(filename))
             batcher.onChange(filename);
     });
 }

package/dist/{cli-launch.d.ts → cli/cli-launch.d.ts}

@@ -20,12 +20,26 @@ export declare function summarizeStatus(payload: unknown): {
     sessionCount: number;
     sessions: StatusSession[];
 };
+/**
+ * Warn when the daemon already on this port is a different version than this CLI, and attach anyway.
+ *
+ * Attaching to whatever owns the port is the point of a daemon — but it means an upgrade does not
+ * take effect until that daemon dies, and nothing used to say so. Killing it here would take out
+ * another agent's session on a version bump, which is worse than a loud line.
+ */
+export declare function warnOnDaemonSkew(port: number): Promise<void>;
 /** GET the daemon's /status JSON. Resolves to the parsed body, or undefined on any failure. */
 export declare function fetchStatus(port: number): Promise<unknown>;
 /** What `reticle open` should do: reuse an already-connected tab, open a new one, or ask for a url. */
 type OpenDecision = {
     action: 'reuse';
     url: string;
+}
+/** A tab on that origin exists, but on another page — kept, and NOT reported as done. */
+ | {
+    action: 'left-as-is';
+    url: string;
+    requested: string;
 } | {
     action: 'open';
     url: string;
@@ -36,8 +50,16 @@ type OpenDecision = {
  * Decide what `reticle open [url]` does, given the currently-connected tabs. Pure.
  * - no url + a tab connected → reuse it (the app is already open; don't spawn a duplicate).
  * - no url + nothing connected → ask for one.
- * - url + a tab already on that origin → reuse it (idempotent — re-running never piles up tabs).
+ * - url + a tab already AT that url → reuse it (idempotent — re-running never piles up tabs).
+ * - url + a tab on that origin but another page → keep it, and say so (`left-as-is`).
  * - url + no matching tab → open it.
+ *
+ * The origin match is why re-running this never piles up tabs, and it stays. What changed is the
+ * REPORT: matching by origin meant `reticle open http://localhost:3000/settings` answered `reusing`
+ * for a tab sitting on `http://localhost:3000/` and exited 0, so the caller read a success for a page
+ * that was never opened. Navigating the tab instead was the other option and is worse: `reticle open`
+ * is run by a human whose browser this is, and yanking the page they are looking at to somewhere else
+ * is a bigger surprise than being told where the tab actually is.
  */
 export declare function decideOpen(sessions: {
     url: string;
@@ -47,6 +69,13 @@ export declare function openCommand(url: string, platform: NodeJS.Platform): {
     cmd: string;
     args: string[];
 };
-/** Launch the default browser at `url` (detached). The spawn is injected so tests stay hermetic. */
-export declare function openInBrowser(url: string, platform?: NodeJS.Platform, run?: (cmd: string, args: string[]) => void): void;
+/**
+ * Launch the default browser at `url` (detached). The spawn is injected so tests stay hermetic.
+ *
+ * Resolves to whether the launch COMMAND started — not to whether a page appeared. It used to return
+ * nothing at all and the caller printed `{"opened": url}` unconditionally, so a launcher that failed
+ * outright still reported success. Reported from the field as twenty minutes lost chasing a phantom
+ * port problem while nothing had ever opened.
+ */
+export declare function openInBrowser(url: string, platform?: NodeJS.Platform, run?: (cmd: string, args: string[]) => Promise<string | null>): Promise<string | null>;
 export {};

package/dist/cli/cli-launch.js

@@ -0,0 +1,171 @@
+import * as http from 'node:http';
+import { NodePlatform } from '../platform.js';
+import { spawn } from 'node:child_process';
+import { isOpaqueOrigin, LOOPBACK_HOST, STATUS_PATH } from '@reticlehq/core';
+import { describeSkew, DAEMON_FIX } from '../version/version-skew.js';
+import { CONTRACT_FINGERPRINT } from '@reticlehq/core';
+import { SERVER_VERSION } from '../version/server-version.js';
+import { log } from '../log.js';
+/**
+ * Reduce the daemon's /status JSON to the compact view `reticle status` prints. Pure: narrows the
+ * untrusted wire payload (never `any`) and tolerates a missing/partial body so a malformed response
+ * degrades to "running, 0 sessions" instead of throwing.
+ */
+export function summarizeStatus(payload) {
+    if (typeof payload !== 'object' || null === payload)
+        return { sessionCount: 0, sessions: [] };
+    const obj = payload;
+    const raw = Array.isArray(obj['sessions']) ? obj['sessions'] : [];
+    const sessions = raw
+        .map((s) => {
+        if (typeof s !== 'object' || null === s)
+            return null;
+        const r = s;
+        const sessionId = 'string' === typeof r['sessionId'] ? r['sessionId'] : '';
+        if ('' === sessionId)
+            return null;
+        return {
+            sessionId,
+            url: 'string' === typeof r['url'] ? r['url'] : '',
+            throttled: true === r['throttled'],
+            stale: true === r['stale'],
+            pendingMarks: 'number' === typeof r['pendingMarks'] ? r['pendingMarks'] : 0,
+        };
+    })
+        .filter((s) => s !== null);
+    const sessionCount = 'number' === typeof obj['sessionCount'] ? obj['sessionCount'] : sessions.length;
+    return { sessionCount, sessions };
+}
+/** A string field off the /status body, or undefined on a daemon too old to report it. */
+function statusField(payload, key) {
+    if (typeof payload !== 'object' || null === payload)
+        return undefined;
+    const value = payload[key];
+    return 'string' === typeof value && value.length > 0 ? value : undefined;
+}
+/**
+ * Warn when the daemon already on this port is a different version than this CLI, and attach anyway.
+ *
+ * Attaching to whatever owns the port is the point of a daemon — but it means an upgrade does not
+ * take effect until that daemon dies, and nothing used to say so. Killing it here would take out
+ * another agent's session on a version bump, which is worse than a loud line.
+ */
+export async function warnOnDaemonSkew(port) {
+    const status = await fetchStatus(port);
+    const skew = describeSkew({
+        what: 'the daemon already running on this port',
+        version: statusField(status, 'version'),
+        contract: statusField(status, 'contract'),
+        fix: DAEMON_FIX,
+    }, { version: SERVER_VERSION, contract: CONTRACT_FINGERPRINT });
+    if (skew !== undefined)
+        log('reticle_daemon_skew', { port, warning: skew });
+}
+/** How long the daemon /status probe waits before giving up — a local loopback call is near-instant. */
+const STATUS_PROBE_TIMEOUT_MS = 1000;
+/** GET the daemon's /status JSON. Resolves to the parsed body, or undefined on any failure. */
+export function fetchStatus(port) {
+    return new Promise((resolve) => {
+        const req = http.get({ host: LOOPBACK_HOST, port, path: STATUS_PATH, timeout: STATUS_PROBE_TIMEOUT_MS }, (res) => {
+            let body = '';
+            res.setEncoding('utf8');
+            res.on('data', (chunk) => (body += chunk));
+            res.on('end', () => {
+                try {
+                    resolve(JSON.parse(body));
+                }
+                catch {
+                    resolve(undefined);
+                }
+            });
+        });
+        req.on('error', () => resolve(undefined));
+        req.on('timeout', () => {
+            req.destroy();
+            resolve(undefined);
+        });
+    });
+}
+function sameOrigin(a, b) {
+    try {
+        const origin = new URL(a).origin;
+        // Two opaque origins (desktop webviews, file:// docs) BOTH stringify to "null", so comparing them
+        // would call every desktop app the same app and reuse the wrong session. Never match on opaque.
+        if (isOpaqueOrigin(origin))
+            return false;
+        return origin === new URL(b).origin;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Decide what `reticle open [url]` does, given the currently-connected tabs. Pure.
+ * - no url + a tab connected → reuse it (the app is already open; don't spawn a duplicate).
+ * - no url + nothing connected → ask for one.
+ * - url + a tab already AT that url → reuse it (idempotent — re-running never piles up tabs).
+ * - url + a tab on that origin but another page → keep it, and say so (`left-as-is`).
+ * - url + no matching tab → open it.
+ *
+ * The origin match is why re-running this never piles up tabs, and it stays. What changed is the
+ * REPORT: matching by origin meant `reticle open http://localhost:3000/settings` answered `reusing`
+ * for a tab sitting on `http://localhost:3000/` and exited 0, so the caller read a success for a page
+ * that was never opened. Navigating the tab instead was the other option and is worse: `reticle open`
+ * is run by a human whose browser this is, and yanking the page they are looking at to somewhere else
+ * is a bigger surprise than being told where the tab actually is.
+ */
+export function decideOpen(sessions, url) {
+    if (url === undefined) {
+        const first = sessions[0];
+        return first !== undefined ? { action: 'reuse', url: first.url } : { action: 'need-url' };
+    }
+    const exact = sessions.find((s) => s.url === url);
+    if (exact !== undefined)
+        return { action: 'reuse', url: exact.url };
+    const onOrigin = sessions.find((s) => sameOrigin(s.url, url));
+    return onOrigin !== undefined
+        ? { action: 'left-as-is', url: onOrigin.url, requested: url }
+        : { action: 'open', url };
+}
+/**
+ * Percent-encode the cmd.exe metacharacters that `start` re-parses so a URL can't break out into
+ * command execution on Windows (`?next=x&calc` → command chaining). `%` is left untouched so an
+ * already-encoded URL isn't double-encoded; the browser decodes the escapes back to the real URL.
+ */
+function encodeForWindowsStart(url) {
+    return url.replace(/[&^|<>()"'!]/g, (ch) => `%${ch.charCodeAt(0).toString(16).toUpperCase()}`);
+}
+/** The OS command that opens a URL in the default browser, per platform. Pure — unit-tested. */
+export function openCommand(url, platform) {
+    if (NodePlatform.MACOS === platform)
+        return { cmd: 'open', args: [url] };
+    if (NodePlatform.WINDOWS === platform) {
+        return { cmd: 'cmd', args: ['/c', 'start', '', encodeForWindowsStart(url)] };
+    }
+    return { cmd: 'xdg-open', args: [url] };
+}
+/**
+ * Launch the default browser at `url` (detached). The spawn is injected so tests stay hermetic.
+ *
+ * Resolves to whether the launch COMMAND started — not to whether a page appeared. It used to return
+ * nothing at all and the caller printed `{"opened": url}` unconditionally, so a launcher that failed
+ * outright still reported success. Reported from the field as twenty minutes lost chasing a phantom
+ * port problem while nothing had ever opened.
+ */
+export async function openInBrowser(url, platform = process.platform, run = defaultRun) {
+    const { cmd, args } = openCommand(url, platform);
+    return run(cmd, args);
+}
+/** null when the launcher started; the failure message when it could not be run at all. */
+function defaultRun(cmd, args) {
+    return new Promise((resolve) => {
+        const child = spawn(cmd, args, { detached: true, stdio: 'ignore' });
+        // An unhandled 'error' on a ChildProcess throws — and ENOENT on the launcher is exactly the case
+        // this function exists to report, so it must be listened for either way.
+        child.on('error', (err) => resolve(err.message));
+        child.on('spawn', () => {
+            child.unref();
+            resolve(null);
+        });
+    });
+}

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

@@ -0,0 +1,31 @@
+/** `reticle feedback --rating 4 "the words"` — the human half of the channel. */
+export declare const RATING_FLAG = "--rating";
+export declare const BUG_FLAG = "--bug";
+/**
+ * The AGENT half of the same channel, for the phase where `reticle_feedback` does not exist yet.
+ *
+ * An agent that is still installing Reticle — or that just watched `init` fail, or a daemon refuse to
+ * start — has no MCP tools to file with, and that is exactly the report we most need: the failures
+ * that happen before the tool surface is reachable are invisible to every other path we have. This
+ * gives that agent the same shape the tool takes, over a command that needs nothing running.
+ */
+export declare const KIND_FLAG = "--kind";
+export declare const AGENT_FLAG = "--agent";
+/** 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. */
+export type ParsedFeedback = {
+    kind: 'feedback';
+    text: string;
+    rating?: number;
+    /** The FeedbackKind name from `--kind`; absent means the legacy bug/experience split. */
+    feedbackKind?: string;
+    bug: boolean;
+    /** `--agent`: file as the agent, so agent reports never dilute the human rating signal. */
+    agent: boolean;
+} | {
+    kind: 'error';
+    message: string;
+};
+/** Parse everything after `reticle feedback`. */
+export declare function parseFeedbackArgs(rest: string[]): ParsedFeedback;

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

@@ -0,0 +1,56 @@
+/**
+ * The `reticle feedback` grammar — flags, kind validation, and the message-vs-flag split.
+ *
+ * Split out of `cli-parse.ts` when that file crossed the line cap. Cohesive on its own terms: this
+ * 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';
+/** `reticle feedback --rating 4 "the words"` — the human half of the channel. */
+export const RATING_FLAG = '--rating';
+export const BUG_FLAG = '--bug';
+/**
+ * The AGENT half of the same channel, for the phase where `reticle_feedback` does not exist yet.
+ *
+ * An agent that is still installing Reticle — or that just watched `init` fail, or a daemon refuse to
+ * start — has no MCP tools to file with, and that is exactly the report we most need: the failures
+ * that happen before the tool surface is reachable are invisible to every other path we have. This
+ * gives that agent the same shape the tool takes, over a command that needs nothing running.
+ */
+export const KIND_FLAG = '--kind';
+export const AGENT_FLAG = '--agent';
+/** 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`. */
+export function parseFeedbackArgs(rest) {
+    const ratingAt = rest.indexOf(RATING_FLAG);
+    const rating = -1 === ratingAt ? undefined : Number(rest[ratingAt + 1]);
+    if (rating !== undefined && (!Number.isInteger(rating) || rating < 1 || rating > 5)) {
+        return { kind: 'error', message: `${RATING_FLAG} takes a whole number from 1 to 5` };
+    }
+    const kindAt = rest.indexOf(KIND_FLAG);
+    const feedbackKind = -1 === kindAt ? undefined : rest[kindAt + 1];
+    if (feedbackKind !== undefined && !FEEDBACK_KINDS.includes(feedbackKind)) {
+        return { kind: 'error', message: `${KIND_FLAG} takes one of: ${FEEDBACK_KINDS.join(', ')}` };
+    }
+    // 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
+    // with the word "bug".
+    const consumed = new Set([
+        ...(-1 === ratingAt ? [] : [ratingAt, ratingAt + 1]),
+        ...(-1 === kindAt ? [] : [kindAt, kindAt + 1]),
+    ]);
+    const text = rest
+        .filter((arg, i) => !consumed.has(i) && !arg.startsWith('--'))
+        .join(' ')
+        .trim();
+    return {
+        kind: 'feedback',
+        text,
+        ...(rating !== undefined ? { rating } : {}),
+        ...(feedbackKind !== undefined ? { feedbackKind } : {}),
+        bug: rest.includes(BUG_FLAG),
+        agent: rest.includes(AGENT_FLAG),
+    };
+}