@reticlehq/server 2.13.0 → 2.14.0

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

@@ -10,12 +10,17 @@
  * — is unit-tested without launching a real browser.
  */
 import { type ReticleVerificationRun } from '@reticlehq/core';
+import { type VerifyProgressListener } from '../runs/reticle-runner.js';
 /** The live capabilities runVerify needs — faked in tests so the logic runs without a browser. */
 export interface VerifyConnection {
     /** Resolve true once a browser session has connected, or false at timeout. */
     sessionReady(timeoutMs: number): Promise<boolean>;
     listFlows(): Promise<string[]>;
-    verify(): Promise<ReticleVerificationRun>;
+    /**
+     * `onProgress` is narration for a run in flight — see `verify-progress.ts` in core. Optional at
+     * every layer: a connection that ignores it behaves exactly as it did before.
+     */
+    verify(onProgress?: VerifyProgressListener): Promise<ReticleVerificationRun>;
     close(): Promise<void>;
 }
 export interface VerifyPorts {
@@ -48,17 +53,29 @@ export declare function urlParts(url: string): {
  * worst answer available, and reached most often by the people with the fewest other options, since
  * the skill offers this command as the way to a verdict with no MCP at all.
  *
- * Three ways out, in the order they are worth trying, and the message says all three rather than
- * picking one: an agent that already has the tools should ask the daemon that is running instead of
- * starting a second one; somebody who wants this command specifically can stop the daemon; and a
- * second port works when the app is configured for it.
+ * The message says every way out rather than picking one, and it says FIRST that a busy port is the
+ * normal state rather than a fault — an install that worked leaves a daemon on it, so a reader who
+ * arrives here has done nothing wrong and should not go looking for what they broke (#689).
  *
- * Attaching to the running daemon the way `reticle drive` now does is the better answer and is not
- * this change — see cli/drive-attach.ts for the shape it should take.
+ * `reticle drive` leads, because it is the only option that works in the state most people are in
+ * when they reach this message: the client exposes no `reticle_*` tools (Codex, Cursor Cloud,
+ * Antigravity, a session whose MCP link dropped), which is exactly when the CLI is reached for. It
+ * ATTACHES to the running daemon rather than binding — see cli/drive-attach.ts — so there is nothing
+ * to stop, nothing to race, and it hands back a sessionId the daemon owns. The advice that used to
+ * lead, "ask the daemon through the tools", is the one thing that reader by construction cannot do.
+ *
+ * Stopping the daemon stays on the list and stays LAST of the working options, with the reason: the
+ * MCP proxy respawns one into the gap, so `stop` is a race the caller usually loses, and it kills
+ * the agent's own link on the way past.
+ *
+ * `verify` itself attaching, rather than needing the port at all, is the real fix and is #689's
+ * first bullet — not this change.
  */
 export declare function portBusyMessage(port: number): string;
 export declare function handleVerify(parsed: {
     url: string;
+    /** A parsed predicate for a flow-free, one-shot verdict against the running daemon. */
+    expect?: unknown;
     headless: boolean;
     timeoutMs?: number;
     storageState?: string;

package/dist/cli/cli-verify.js

@@ -10,13 +10,15 @@
  * — is unit-tested without launching a real browser.
  */
 import { join, basename } from 'node:path';
+import { runAdhocVerdict } from './adhoc-verdict.js';
+import { readOrCreatePairingTokenSync, defaultPairingTokenDir } from '../bridge/pairing-token.js';
 import { randomUUID } from 'node:crypto';
-import { RETICLE_DEFAULT_PORT, ReticleEnv, bridgeWsUrl, isLoopbackHostname, ReticleDir, RunAgentKind, RunFramework, RunProfile, RunTrigger, VerdictStatus, } from '@reticlehq/core';
+import { RETICLE_DEFAULT_PORT, ReticleEnv, bridgeWsUrl, isLoopbackHostname, ReticleDir, RunAgentKind, RunFramework, RunProfile, RunTrigger, VerdictStatus, VerifyPhase, } from '@reticlehq/core';
 import { start } from '../index.js';
 import { probePresence, PortPresence } from '../daemon/port-presence.js';
 import { probeDaemon } from '../mcp/mcp-proxy.js';
 import { fetchStatus } from './cli-launch.js';
-import { cloudFetch, resolveCloudConfig, syncRunToCloud, SyncOutcome, } from '../cloud/cloud-sync.js';
+import { cloudFetch, createProgressReporter, resolveCloudConfig, syncProgressToCloud, syncRunToCloud, SyncOutcome, } from '../cloud/cloud-sync.js';
 import { ReticleRunner } from '../runs/reticle-runner.js';
 import { createRunnerPort } from '../runs/runner-port.js';
 import { RunStore } from '../runs/run-store.js';
@@ -71,8 +73,44 @@ export async function runVerify(args, ports) {
             ports.exit(EXIT_FAIL);
             return;
         }
-        const run = await conn.verify();
+        /*
+         * Narrate the run while it happens.
+         *
+         * Everything else the CLI reports is a finished artifact, which is the right shape for evidence
+         * and the wrong shape for the minutes a verification actually takes. Without this the dashboard
+         * has nothing to show between "linked" and "done", and a run that is working looks exactly like
+         * one that has died — the ambiguity somebody spent fifteen minutes inside.
+         *
+         * Opt-in and best-effort: no cloud credentials means nothing is buffered and nothing is sent.
+         */
+        /*
+         * A correlation id for the STREAM, minted before the run exists.
+         *
+         * The artifact's own `runId` is only assigned once verification finishes, and these events have
+         * to be attributable from the first one — so the stream gets its own id, and the dashboard keys
+         * live progress by it until the finished run replaces the whole picture.
+         */
+        const streamId = randomUUID();
+        const cloud = resolveCloudConfig(process.env);
+        const progress = createProgressReporter(streamId, cloud, cloudFetch);
+        let run;
+        try {
+            run = await conn.verify(progress.onProgress);
+        }
+        finally {
+            // Stopped before the last flush so the timer cannot fire mid-send, and flushed after it so the
+            // events from the final flow are not thrown away with the interval that would have sent them.
+            progress.stop();
+            await progress.flush().catch(() => undefined);
+        }
         await pushRunToCloud(run, ports); // best-effort; opt-in; never changes the verdict or exit code
+        /*
+         * The last event anybody watching is waiting for, sent after the artifact has actually landed —
+         * so "pushed" on a dashboard means the run is really there, not that we were about to try.
+         */
+        await syncProgressToCloud(streamId, 
+        // The run's OWN injected timestamp — no wall clock is read in this path (rule 7).
+        [{ phase: VerifyPhase.PUSHED, at: run.createdAt }], cloud, cloudFetch).catch(() => undefined);
         ports.out(renderRunReport(run));
         ports.exit(run.verdict.status === VerdictStatus.PASS ? EXIT_PASS : EXIT_FAIL);
     }
@@ -179,12 +217,13 @@ async function openLiveConnection(opts) {
     return {
         sessionReady: (timeoutMs) => waitForSession(deps.sessions, timeoutMs, opts.now),
         listFlows: () => deps.flows.list(),
-        verify: async () => {
+        verify: async (onProgress) => {
             const run = await runner.verify({
                 project: { name: opts.projectName, framework: RunFramework.OTHER, previewUrl: opts.url },
                 agent: { id: VERIFY_AGENT_ID, kind: RunAgentKind.OEM_PIPELINE },
                 trigger: { kind: RunTrigger.OEM },
                 profile: RunProfile.PROD_PREVIEW,
+                ...(onProgress === undefined ? {} : { onProgress }),
             });
             // Persist the artifact. `reticle gate` decides from RunStore.latest, so without this the
             // documented CI loop is broken end to end: `reticle verify` could pass and the gate would still
@@ -214,22 +253,38 @@ async function openLiveConnection(opts) {
  * worst answer available, and reached most often by the people with the fewest other options, since
  * the skill offers this command as the way to a verdict with no MCP at all.
  *
- * Three ways out, in the order they are worth trying, and the message says all three rather than
- * picking one: an agent that already has the tools should ask the daemon that is running instead of
- * starting a second one; somebody who wants this command specifically can stop the daemon; and a
- * second port works when the app is configured for it.
+ * The message says every way out rather than picking one, and it says FIRST that a busy port is the
+ * normal state rather than a fault — an install that worked leaves a daemon on it, so a reader who
+ * arrives here has done nothing wrong and should not go looking for what they broke (#689).
+ *
+ * `reticle drive` leads, because it is the only option that works in the state most people are in
+ * when they reach this message: the client exposes no `reticle_*` tools (Codex, Cursor Cloud,
+ * Antigravity, a session whose MCP link dropped), which is exactly when the CLI is reached for. It
+ * ATTACHES to the running daemon rather than binding — see cli/drive-attach.ts — so there is nothing
+ * to stop, nothing to race, and it hands back a sessionId the daemon owns. The advice that used to
+ * lead, "ask the daemon through the tools", is the one thing that reader by construction cannot do.
  *
- * Attaching to the running daemon the way `reticle drive` now does is the better answer and is not
- * this change — see cli/drive-attach.ts for the shape it should take.
+ * Stopping the daemon stays on the list and stays LAST of the working options, with the reason: the
+ * MCP proxy respawns one into the gap, so `stop` is a race the caller usually loses, and it kills
+ * the agent's own link on the way past.
+ *
+ * `verify` itself attaching, rather than needing the port at all, is the real fix and is #689's
+ * first bullet — not this change.
  */
 export function portBusyMessage(port) {
     return (`reticle verify needs port ${String(port)} — the port your app dials — and a Reticle daemon is ` +
         'already listening on it. It did not start a second one.\n\n' +
-        '  • If you have the Reticle tools, ask the daemon that is already running instead: ' +
+        '  This is the NORMAL state after a working install, not a fault: the daemon your MCP client ' +
+        'started owns that port.\n\n' +
+        `  • Drive the app through the daemon that is already there — this needs no tools and stops ` +
+        `nothing: npx @reticlehq/server drive <url>\n` +
+        '  • If your client HAS the Reticle tools, ask that daemon directly: ' +
         'reticle_run { tool: "reticle_verify", args: { action: "change", files: ["..."] } }\n' +
-        `  • Or stop it and re-run: npx @reticlehq/server stop --port ${String(port)}\n` +
         `  • Or run both on another port, if your app is configured for it: RETICLE_PORT=<port> ` +
-        'npx @reticlehq/server verify <url>');
+        'npx @reticlehq/server verify <url>\n' +
+        `  • Stopping the daemon (npx @reticlehq/server stop --port ${String(port)}) works, but it cuts ` +
+        "your agent's MCP link and the proxy usually respawns a daemon into the gap before verify can " +
+        'bind — prefer one of the above.');
 }
 export function handleVerify(parsed) {
     const now = () => Date.now();
@@ -257,6 +312,25 @@ export function handleVerify(parsed) {
         const port = parsed.port ?? RETICLE_DEFAULT_PORT;
         if ((await probePresence(port, { tcpOpen: probeDaemon, status: fetchStatus })) ===
             PortPresence.DAEMON) {
+            // A daemon owning the port is the NORMAL state after a working install, and it used to be the
+            // end of the road: `verify` refused, the other verdict paths need saved flows a first-install
+            // project does not have, and stopping the daemon cuts the agent's own MCP link. An agent could
+            // hold a live, correctly-wired app and have no way to reach a verdict at all.
+            //
+            // With `--expect` there is now a way, and it does not need the port: ask the daemon that
+            // already owns it. See runAdhocVerdict.
+            if (parsed.expect !== undefined) {
+                const verdict = await runAdhocVerdict({
+                    port,
+                    ...(parsed.url !== undefined && '' !== parsed.url ? { url: parsed.url } : {}),
+                    predicate: parsed.expect,
+                    ...((t) => (t === undefined || 0 === t.length ? {} : { token: t }))(readOrCreatePairingTokenSync(defaultPairingTokenDir())),
+                });
+                for (const line of verdict.lines)
+                    ports.out(line);
+                ports.exit(verdict.code);
+                return;
+            }
             ports.fail(portBusyMessage(port));
             ports.exit(1);
             return;

package/dist/cli/cloud-keystore.d.ts

@@ -5,7 +5,7 @@
  * caller is expected to establish the tenant before trusting what comes back.
  */
 export declare const findCredential: (raw: unknown, projectId: string, url: string, orgId: string | undefined) => string | undefined;
-export interface CredentialWrite {
+interface CredentialWrite {
     projectId: string;
     url: string;
     key: string;
@@ -35,3 +35,4 @@ export interface CredentialWrite {
 export declare const applyCredential: (store: Record<string, unknown>, write: CredentialWrite) => Record<string, unknown>;
 /** Where the store lives, given the reticle home directory. */
 export declare const credentialsPath: (homeDir: string, file: string) => string;
+export {};

package/dist/cli/cloud-login.d.ts

@@ -1,5 +1,5 @@
 /** Run `reticle link` with these arguments. Injected; see the note at the top of this file. */
-export type Linker = (argv: readonly string[]) => Promise<number>;
+type Linker = (argv: readonly string[]) => Promise<number>;
 /**
  * `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.
@@ -15,3 +15,4 @@ export declare const cmdLogin: (argv: readonly string[], link: Linker) => Promis
  * one you did not mean.
  */
 export declare const cmdLogout: (argv?: readonly string[]) => Promise<number>;
+export {};

package/dist/cli/cloud-session.d.ts

@@ -8,7 +8,7 @@
 import { z } from 'zod';
 /** Where per-host sessions live under the reticle home directory. */
 export declare const SESSIONS_DIR = "sessions";
-export declare const SessionSchema: z.ZodObject<{
+declare const SessionSchema: z.ZodObject<{
     url: z.ZodString;
     token: z.ZodString;
     orgName: z.ZodString;
@@ -46,3 +46,4 @@ export declare const readSessionFrom: (raw: Promise<unknown>) => Promise<Session
  * sessions existed keeps working and is not silently signed out by an upgrade.
  */
 export declare const resolveSessionFor: (url: string, perHost: Session | null, active: Session | null) => Session | null;
+export {};

package/dist/cli/cloud-session.js

@@ -9,7 +9,7 @@ import { z } from 'zod';
 import { join } from 'node:path';
 /** Where per-host sessions live under the reticle home directory. */
 export const SESSIONS_DIR = 'sessions';
-export const SessionSchema = z.object({
+const SessionSchema = z.object({
     url: z.string(),
     token: z.string(),
     orgName: z.string(),

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

@@ -12,7 +12,7 @@
  * replay, the spec runner), which exists whether or not a drive URL was named.
  */
 import type { StartOptions } from '../index.js';
-export type DaemonFlags = {
+type DaemonFlags = {
     port: number;
     driveUrl?: string;
     headless: boolean;
@@ -30,3 +30,4 @@ export declare function daemonStartOptions(parsed: DaemonFlags): StartOptions;
  * idea: that headless belongs to the drive URL. It belongs to the pool, which exists either way.
  */
 export declare function daemonSpawnArgs(parsed: DaemonFlags): string[];
+export {};

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

@@ -53,18 +53,18 @@ export declare const DevicePollSchema: z.ZodObject<{
     }>>;
 }, "strip", z.ZodTypeAny, {
     status: string;
+    token?: string | undefined;
     org?: {
         name: string;
         id?: string | undefined;
     } | undefined;
-    token?: string | undefined;
 }, {
     status: string;
+    token?: string | undefined;
     org?: {
         name: string;
         id?: string | undefined;
     } | undefined;
-    token?: string | undefined;
 }>;
 /**
  * Best-effort open the approval page in the default browser.

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

@@ -18,7 +18,7 @@ export interface DaemonIdentity {
     version?: string;
     contract?: string;
 }
-export interface DaemonLine {
+interface DaemonLine {
     /** The `daemon ✓ …` line itself. */
     text: string;
     /** A skew sentence to print underneath, when this CLI and that daemon disagree. */
@@ -35,3 +35,4 @@ export declare function daemonLine(port: number, pid: number | null, peer: Daemo
     version: string;
     contract: string;
 }): DaemonLine;
+export {};

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

@@ -10,7 +10,7 @@
  * Registering the MCP server and instrumenting the app are two different halves of the install, and
  * more than one route does the first without the second.
  */
-export interface ProjectWiringFacts {
+interface ProjectWiringFacts {
     /** The id from `.reticle.json`, or undefined when there is no config here. */
     projectId: string | undefined;
     /** Has an app for this project ever connected on this port? Durable across daemon restarts. */
@@ -35,3 +35,4 @@ export interface ProjectWiringFacts {
  * other way — and `init` is the one action that can overwrite a setup that already works.
  */
 export declare function projectWiringLine(facts: ProjectWiringFacts): string;
+export {};

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

@@ -47,7 +47,7 @@ export declare const DoctorRow: {
     readonly TRACING: "tracing";
     readonly DESKTOP: "desktop";
 };
-export type DoctorRowLabel = (typeof DoctorRow)[keyof typeof DoctorRow];
+type DoctorRowLabel = (typeof DoctorRow)[keyof typeof DoctorRow];
 export declare const DOCTOR_ROW_LABELS: readonly DoctorRowLabel[];
 /**
  * Width the label column pads to.
@@ -60,3 +60,4 @@ export declare const DOCTOR_ROW_LABELS: readonly DoctorRowLabel[];
 export declare const LABEL_COLUMN: number;
 /** Build one `doctor` row: the standard indent, the label padded to the column, then `rest`. */
 export declare function doctorRow(label: DoctorRowLabel, rest: string): string;
+export {};

package/dist/cli/drive-attach.d.ts

@@ -42,7 +42,7 @@ export type DriveMode = (typeof DriveMode)[keyof typeof DriveMode];
 /** Pure. Exhaustive by switch, so a fourth presence has to decide what driving means for it. */
 export declare function decideDriveMode(presence: PortPresence): DriveMode;
 /** A driveable session the daemon opened on our behalf. */
-export interface DriveSession {
+interface DriveSession {
     sessionId: string;
     /** Whether the tab's SDK actually registered — false ⇒ the app may not embed @reticlehq/core. */
     ready: boolean;
@@ -51,7 +51,7 @@ export interface DriveSession {
     /** The daemon's own diagnosis when the tab did not connect. */
     hint?: string;
 }
-export type DriveAttachResult = {
+type DriveAttachResult = {
     ok: true;
     session: DriveSession;
 } | {
@@ -59,7 +59,7 @@ export type DriveAttachResult = {
     reason: string;
 };
 /** POST the drive request. Injected so the decision logic is tested without a socket. */
-export type DrivePost = (port: number, path: string, body: string) => Promise<{
+type DrivePost = (port: number, path: string, body: string) => Promise<{
     status: number;
     body: string;
 }>;
@@ -110,3 +110,4 @@ export declare function driveForeignHolder(description: string): string;
  * and that sentence is "run it again", because the second run attaches instead of binding.
  */
 export declare function driveRaceLost(port: number, url: string): string;
+export {};

package/dist/cli/gate-hook-message.d.ts

@@ -12,7 +12,7 @@
  */
 /** Named so a reader of the hook output knows the flag is real and not a suggestion. */
 export declare const GATE_SKIP_ENV = "RETICLE_SKIP_GATE";
-export interface GateHookInput {
+interface GateHookInput {
     /** Flows the changed files touch that have no passing artifact. */
     uncovered: readonly string[];
     /** Flows held back as flaky — reported, never counted as a pass. */
@@ -31,3 +31,4 @@ export interface GateHookInput {
  * interrupted.
  */
 export declare function gateHookMessage(exit: number, input: GateHookInput): string | undefined;
+export {};

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

@@ -21,17 +21,6 @@ import { nextActionFor } from '../session/no-session-next-action.js';
 export function statusNextAction(facts) {
     if (facts.sessionCount > 0)
         return undefined;
-    // Ahead of everything else, because it dominates: an app that was never wired cannot connect, and
-    // no advice about dev servers or ports applies until it is. `previouslyConnected` overrides it —
-    // an app CAN be wired by the Vite or Babel plugin with no `.reticle.json` at all, so a project
-    // that has connected here before is wired whatever this file says, and sending it back to `init`
-    // would be the same wrong answer in the other direction.
-    if (!facts.initialized && !facts.previouslyConnected) {
-        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.');
-    }
     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
@@ -43,6 +32,16 @@ export function statusNextAction(facts) {
             `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. `previouslyConnected` overrides this branch because plugin-based wiring may
+    // connect without creating `.reticle.json`.
+    if (!facts.initialized && !facts.previouslyConnected) {
+        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.

package/dist/cli.d.ts

@@ -3,3 +3,4 @@ import { parseCliArgs, CLI_USAGE } from './cli/cli-parse.js';
 export { parseCliArgs, CLI_USAGE };
 export type { CliResult } from './cli/cli-parse.js';
 export declare function handleStatus(port: number): Promise<void>;
+export declare function main(): void;

package/dist/cli.js

@@ -33,15 +33,16 @@ import { installDaemonResilience, recordExitReason, DaemonExitReason, } from './
 import { IdleShutdown, resolveIdleShutdownMs, resolveIdleCheckMs } from './daemon/idle-shutdown.js';
 import { DaemonHeartbeat, resolveHeartbeatMs } from './daemon/heartbeat.js';
 import { everServedToolCall } from './daemon/daemon-usefulness.js';
+import { DAEMON_START_FAILED_EVENT, readDaemonStartupCause } from './daemon/startup-failure.js';
 import { fetchStatus, summarizeStatus, warnOnDaemonSkew, decideOpen, openInBrowser, openCommand, } from './cli/cli-launch.js';
 import { handleDrive } from './cli/drive-command.js';
 import { handleVerify } from './cli/cli-verify.js';
 import { runKill } from './cli/cli-kill.js';
 import { summarizeHunt } from './hunt/hunt-report.js';
-import { runInit } from './init/run.js';
+import { runInit, buildNodeIo } from '@reticlehq/init';
 import { continueAfterInit } from './setup/init-runtime.js';
 import { handleDoctor } from './cli/cli-doctor.js';
-import { buildNodeIo } from './init/node-io.js';
+import { serverInitHost } from './setup/init-host.js';
 import { describeLicense } from './license/license.js';
 import { isLikelyDevServerPort, devServerPortWarning, readProjectPort, readProjectId, } from './cli/cli-port.js';
 import { DAEMON_INNER_COMMAND, PORT_FLAG, parseCliArgs, CLI_USAGE } from './cli/cli-parse.js';
@@ -52,7 +53,7 @@ import { reportCliRun } from './telemetry/cli-telemetry.js';
 export { parseCliArgs, CLI_USAGE };
 function handleInit(parsed) {
     const cwd = process.cwd();
-    const io = buildNodeIo(cwd);
+    const io = buildNodeIo(cwd, serverInitHost());
     const result = runInit({
         cwd,
         port: parsed.port,
@@ -60,6 +61,9 @@ function handleInit(parsed) {
         dryRun: parsed.dryRun,
         install: parsed.install,
         ...(parsed.app === undefined ? {} : { app: parsed.app }),
+        // Handed to init, not only to the drive phase below: the preflight names `--url` as the way
+        // past a missing package manager, and could not honour that while never being told about it.
+        ...(parsed.url === undefined ? {} : { url: parsed.url }),
         captureBodies: true === parsed.captureBodies,
         // The outcome is reported by confirmInstall instead, once it knows whether an app connected —
         // `init` writing files was never the same thing as `init` working (#269).
@@ -122,6 +126,7 @@ async function serveWithHonestExit(parsed) {
         return;
     }
     const daemonArgs = daemonSpawnArgs(parsed);
+    const startupStartedAt = Date.now();
     spawnDaemon(process.execPath, scriptPath, daemonArgs, parsed.port);
     // The child binds asynchronously and, when it cannot, exits 1 long after this process would have
     // reported success. Wait for it to ANSWER — `/status` responding is the only evidence a daemon
@@ -129,12 +134,14 @@ async function serveWithHonestExit(parsed) {
     const bound = await waitForPresence(parsed.port, PortPresence.DAEMON, SERVE_BIND_TIMEOUT_MS);
     if (!bound) {
         const settled = await probePresence(parsed.port, { tcpOpen: probeDaemon, status: fetchStatus });
+        const startupCause = readDaemonStartupCause(logPath(parsed.port), startupStartedAt);
         log('reticle_daemon_start_failed_parent', {
             port: parsed.port,
             presence: settled,
             reason: describePresence(settled, parsed.port),
             log: logPath(parsed.port),
             stateDir: stateDirProblem(reticleStateHome()) === undefined ? 'writable' : 'unwritable',
+            ...(startupCause === undefined ? {} : { cause: startupCause }),
         });
         // Name the CAUSE when we can see it. An unwritable state directory is a first-run failure mode
         // (locked-down home, read-only container mount, managed profile) that produced only "nothing is
@@ -142,8 +149,11 @@ async function serveWithHonestExit(parsed) {
         // cannot exist. Found by stress-testing 2.6.0 with `chmod 555 ~/.reticle`.
         const dirProblem = stateDirProblem(reticleStateHome());
         process.stderr.write(dirProblem === undefined
-            ? `the daemon did not come up on :${String(parsed.port)} — ${describePresence(settled, parsed.port)}\n` +
-                `see ${logPath(parsed.port)}\n`
+            ? startupCause === undefined
+                ? `the daemon did not come up on :${String(parsed.port)} — ${describePresence(settled, parsed.port)}\n` +
+                    `see ${logPath(parsed.port)}\n`
+                : `the daemon did not come up on :${String(parsed.port)}.\n${startupCause}\n` +
+                    `see ${logPath(parsed.port)}\n`
             : `the daemon did not come up on :${String(parsed.port)}.\n${dirProblem}\n`);
         process.exit(1);
         return;
@@ -367,8 +377,10 @@ async function handleAffected(files, since) {
     try {
         const fs = createNodeFileSystem();
         const reticleRoot = join(process.cwd(), ReticleDir.ROOT);
-        const changed = await resolveChangedFiles(files, since);
-        const result = affectedSavedFlows(await loadNamedFlows(fs, reticleRoot), changed);
+        // The CLI gate still degrades to "no changes" rather than crash CI over a bad ref — the
+        // original reasoning, now opted into explicitly instead of handed a clean-looking empty list.
+        const changed = (await resolveChangedFiles(files, since, process.cwd())).files;
+        const result = affectedSavedFlows(await loadNamedFlows(fs, reticleRoot, readProjectId(process.cwd())), changed);
         log('reticle_affected', {
             changedFiles: changed,
             affected: result.affected,
@@ -644,12 +656,12 @@ function handleDaemonInner(parsed) {
     })
         .catch((error) => {
         const message = error instanceof Error ? error.message : String(error);
-        log('reticle_daemon_start_failed', { error: message });
+        log(DAEMON_START_FAILED_EVENT, { error: message });
         removePid(parsed.port);
         process.exit(1);
     });
 }
-function main() {
+export function main() {
     // Before anything reads process.env — notably the telemetry gate and the bridge's security
     // options — fold in a project-local `.env`. Values already in the environment always win.
     loadDotEnv(process.cwd());

package/dist/cloud/account-state.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Is this machine signed in to a Reticle workspace?
+ *
+ * Asked by the HUD, and there are two sources that must not be reimplemented per caller: the session
+ * file `reticle login` writes to `~/.reticle/session.json`, and `RETICLE_CLOUD_KEY` for an agent that
+ * was handed a key instead. Everything that gates on login — the defect sync button, the prompt to sign
+ * in — resolves through here.
+ *
+ * Node-only by design: it reads the filesystem and the environment, so it lives in the server and
+ * only the SHAPE (`AccountState`) is in core, where the contract belongs.
+ */
+import { type AccountState } from '@reticlehq/core';
+/**
+ * Read the account state for this machine.
+ *
+ * The env key WINS over the session file: an agent handed a key is authenticating as that key,
+ * whatever a human left on disk, and reporting the human's org there would be a lie about who is
+ * acting.
+ */
+export declare function readAccountState(home: string, env: NodeJS.ProcessEnv): AccountState;

package/dist/cloud/account-state.js

@@ -0,0 +1,65 @@
+/**
+ * Is this machine signed in to a Reticle workspace?
+ *
+ * Asked by the HUD, and there are two sources that must not be reimplemented per caller: the session
+ * file `reticle login` writes to `~/.reticle/session.json`, and `RETICLE_CLOUD_KEY` for an agent that
+ * was handed a key instead. Everything that gates on login — the defect sync button, the prompt to sign
+ * in — resolves through here.
+ *
+ * Node-only by design: it reads the filesystem and the environment, so it lives in the server and
+ * only the SHAPE (`AccountState`) is in core, where the contract belongs.
+ */
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { ReticleDir } from '@reticlehq/core';
+import { CloudEnv } from './cloud-sync.js';
+import { SESSION_FILE } from '../cli/cloud-kit.js';
+/** Signed OUT is the safe answer: it shows the way in, where a wrong "signed in" hides it. */
+const SIGNED_OUT = { signedIn: false };
+/**
+ * The fields we read off the session file, and nothing else.
+ *
+ * Narrowed by hand rather than parsed with the login schema on purpose: this function must be unable
+ * to carry a token even if the file grows one, and the surest way to guarantee that is never to bind
+ * it to a name here.
+ */
+function fromSessionFile(home) {
+    try {
+        const raw = JSON.parse(readFileSync(join(home, ReticleDir.ROOT, SESSION_FILE), 'utf8'));
+        if ('object' !== typeof raw || null === raw)
+            return undefined;
+        const record = raw;
+        // A half-written or hand-edited file must not read as authenticated. `signedIn: true` is the
+        // claim that costs something when wrong, because it hides the way in.
+        if ('string' !== typeof record['token'] || 0 === record['token'].length)
+            return undefined;
+        const org = record['orgName'];
+        const host = record['url'];
+        return {
+            signedIn: true,
+            ...('string' === typeof org && org.length > 0 ? { org } : {}),
+            ...('string' === typeof host && host.length > 0 ? { host } : {}),
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Read the account state for this machine.
+ *
+ * The env key WINS over the session file: an agent handed a key is authenticating as that key,
+ * whatever a human left on disk, and reporting the human's org there would be a lie about who is
+ * acting.
+ */
+export function readAccountState(home, env) {
+    const key = env[CloudEnv.KEY];
+    const url = env[CloudEnv.URL];
+    if ('string' === typeof key && key.length > 0) {
+        return {
+            signedIn: true,
+            ...('string' === typeof url && url.length > 0 ? { host: url.replace(/\/+$/, '') } : {}),
+        };
+    }
+    return fromSessionFile(home) ?? SIGNED_OUT;
+}