@reticlehq/server 3.5.0 → 3.7.0

package/dist/command/cli/adhoc-verdict.js

@@ -1,4 +1,5 @@
 import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { CLI_CLIENT_NAME } from '../../judgement/runs/verification-sync.js';
 import { SSEClientTransport } from '@modelcontextprotocol/sdk/client/sse.js';
 import { LOOPBACK_HOST, MCP_SSE_PATH } from '@reticlehq/core';
 import { TOKEN_QUERY_PARAM } from '../../portal/bridge/token-auth.js';
@@ -20,12 +21,30 @@ const leaseFailedLine = (url) => `could not open ${url} in a Reticle browser, so
  * the caller must hand to `releaseLease`; `{ failed }` is the lease's own refusal, as lines to print —
  * a missing browser, an app that is not up — so nothing is asserted against a page that never opened.
  */
-export async function leaseIfNoTab(caller, url, sessions) {
+export async function leaseIfNoTab(caller, url, sessions, 
+/** The caller's project `.reticle`, so the lease's runs land where this command looks. */
+root) {
     const open = [...(await sessions())];
     if ('open' !== decideOpen(open, url).action) {
         return open.some((s) => sameDocument(s.url, url)) ? { alreadyAt: true } : {};
     }
-    return acquireLease(caller, url);
+    return acquireLease(caller, url, false, root);
+}
+/**
+ * Whether the tab named by `sessionId` already shows `url`'s document.
+ *
+ * Read from the same status the unpinned path reads. A status read that fails, or a session the
+ * daemon does not list, answers false: navigating is the old behaviour, so a doubt costs a reload
+ * rather than an assert against a page that is not there.
+ */
+async function pinnedTabIsAt(sessions, sessionId, url) {
+    try {
+        const pinned = (await sessions()).find((s) => s.sessionId === sessionId);
+        return pinned !== undefined && sameDocument(pinned.url, url);
+    }
+    catch {
+        return false;
+    }
 }
 /**
  * Whether two urls name the same document, ignoring a trailing slash and the hash.
@@ -50,11 +69,26 @@ function sameDocument(a, b) {
  * caller hands to `releaseLease`; `{ failed }` is the lease's own refusal, as lines to print.
  * `init`'s connect proof on a machine with no system browser takes this path directly.
  */
-export async function acquireLease(caller, url) {
-    const acquired = await caller.call(ReticleTool.RUN, { tool: ReticleTool.LEASE, args: { action: LeaseAction.ACQUIRE, url } }, LEASE_TIMEOUT_MS);
-    const sessionId = verdictOf(acquired, 'sessionId')?.['sessionId'];
-    if ('string' === typeof sessionId)
-        return { leased: sessionId };
+export async function acquireLease(caller, url, 
+/** Open it in a window somebody can watch, whatever the daemon was started as. */
+headed, 
+/** The `.reticle` the lease's runs belong in: the caller's project, not wherever the page resolves. */
+root) {
+    const acquired = await caller.call(ReticleTool.RUN, {
+        tool: ReticleTool.LEASE,
+        args: {
+            action: LeaseAction.ACQUIRE,
+            url,
+            ...(true === headed ? { headed } : {}),
+            ...(root === undefined ? {} : { root }),
+        },
+    }, LEASE_TIMEOUT_MS);
+    const report = verdictOf(acquired, 'sessionId');
+    const sessionId = report?.['sessionId'];
+    // `zeroInstall`: the page never dialled in, so the lease supplied Reticle's own reader.
+    if ('string' === typeof sessionId) {
+        return { leased: sessionId, zeroInstall: true === report?.['zeroInstall'] };
+    }
     const why = verdictOf(acquired, 'error')?.['error'];
     return {
         failed: [
@@ -81,7 +115,7 @@ export function endpointFor(port, token) {
     return url;
 }
 export async function connectOverSse(endpoint) {
-    const client = new Client({ name: 'reticle-cli', version: '1' }, { capabilities: {} });
+    const client = new Client({ name: CLI_CLIENT_NAME, version: '1' }, { capabilities: {} });
     await client.connect(new SSEClientTransport(endpoint));
     return {
         call: async (name, args, timeoutMs) => await client.callTool({ name, arguments: args }, undefined, timeoutMs === undefined ? undefined : { timeout: timeoutMs }),
@@ -190,8 +224,14 @@ export async function runAdhocVerdict(options) {
         // OTHER listening port as the one to open. The caller already said which url; open it here, in
         // a Reticle browser, and hand the lease back when the verdict is in.
         let alreadyAt = false;
+        // A named tab gets the same same-document rule: navigating to the url it already shows is a
+        // reload, which throws away client-only state (page 2, a half-filled form) and in a desktop
+        // window disconnects the session the assert is about to read (#1409).
+        if (url !== undefined && options.sessionId !== undefined && options.sessions !== undefined) {
+            alreadyAt = await pinnedTabIsAt(options.sessions, options.sessionId, url);
+        }
         if (url !== undefined && options.sessionId === undefined && options.sessions !== undefined) {
-            const opened = await leaseIfNoTab(caller, url, options.sessions);
+            const opened = await leaseIfNoTab(caller, url, options.sessions, options.root);
             if ('failed' in opened)
                 return { code: 1, lines: ['verified: unknown', ...opened.failed] };
             leased = opened.leased;
@@ -237,3 +277,30 @@ export async function runAdhocVerdict(options) {
         await caller.close().catch(() => undefined);
     }
 }
+const EXPLORE_ACTION = 'explore';
+const DRIVE_RUNNING = 'running';
+/** The most one explore call waits on its drive (the tool's own ceiling), and the call's slack. */
+const EXPLORE_WAIT_MAX_S = 240;
+const CALL_SLACK_MS = 15_000;
+const MS_PER_S = 1000;
+/**
+ * One Harness drive through the daemon, polled to its end or until `budgetMs` runs out.
+ *
+ * An explore answers `{ status: "running", runId }` when its drive outlasts the call's wait, so a
+ * caller that wants the finished report asks again by `runId` rather than starting a second drive.
+ */
+export async function exploreToEnd(caller, args, budgetMs, now = Date.now) {
+    const deadline = now() + budgetMs;
+    const ask = (more) => {
+        const wait = Math.max(0, Math.min(EXPLORE_WAIT_MAX_S, Math.floor((deadline - now() - CALL_SLACK_MS) / MS_PER_S)));
+        return caller.call(ReticleTool.VERIFY, { ...more, action: EXPLORE_ACTION, wait }, wait * MS_PER_S + CALL_SLACK_MS);
+    };
+    let result = await ask(args);
+    for (;;) {
+        const report = verdictOf(result, 'status');
+        const runId = report?.['runId'];
+        if (DRIVE_RUNNING !== report?.['status'] || 'string' !== typeof runId || now() >= deadline)
+            return result;
+        result = await ask({ runId });
+    }
+}

package/dist/command/cli/answers/gate-exit.d.ts

@@ -18,4 +18,27 @@ export declare const GateExit: {
     readonly FAIL: 1;
     /** The gate ran and had nothing to judge — no flows recorded. Non-zero, but not a regression. */
     readonly NOTHING_TO_CHECK: 2;
+    /** The platform knows a flow that passed before and is broken now: `reticle runs regression`'s code. */
+    readonly REGRESSION: 3;
 };
+/**
+ * The gate's code once the platform has been asked about regressions: a known one fails the build
+ * with `reticle runs regression`'s code, whatever the local answer was, so the gate is the one
+ * command CI needs. `undefined` (not linked, or the platform did not answer) changes nothing.
+ */
+export declare function gateExitWith(local: number, regressed: number | undefined, 
+/** The platform the project is linked to refused its credential: the gate fails closed. */
+refused?: boolean): number;
+/**
+ * Said when the linked platform refused the key. A CI pipeline whose key was revoked stayed green
+ * and silent: the gate lost the platform's regression report and the only trace was a log line.
+ */
+export declare function msgGateRefused(why: string): string;
+/** Said when the gate had no saved flows to judge, so exit 2 does not read as the change failing. */
+export declare const MSG_GATE_NO_FLOWS: string;
+/**
+ * Said when the platform knows a regression, outside a hook. Exit 3 printed only the JSON log, whose
+ * coverage field still read "no flows recorded — nothing was checked", so nothing a person read
+ * said "regression".
+ */
+export declare function msgGateRegression(broken: readonly unknown[]): string;

package/dist/command/cli/answers/gate-exit.js

@@ -18,4 +18,49 @@ export const GateExit = {
     FAIL: 1,
     /** The gate ran and had nothing to judge — no flows recorded. Non-zero, but not a regression. */
     NOTHING_TO_CHECK: 2,
+    /** The platform knows a flow that passed before and is broken now: `reticle runs regression`'s code. */
+    REGRESSION: 3,
 };
+/**
+ * The gate's code once the platform has been asked about regressions: a known one fails the build
+ * with `reticle runs regression`'s code, whatever the local answer was, so the gate is the one
+ * command CI needs. `undefined` (not linked, or the platform did not answer) changes nothing.
+ */
+export function gateExitWith(local, regressed, 
+/** The platform the project is linked to refused its credential: the gate fails closed. */
+refused = false) {
+    if (regressed !== undefined && 0 < regressed)
+        return GateExit.REGRESSION;
+    return refused && GateExit.PASS === local ? GateExit.FAIL : local;
+}
+/**
+ * Said when the linked platform refused the key. A CI pipeline whose key was revoked stayed green
+ * and silent: the gate lost the platform's regression report and the only trace was a log line.
+ */
+export function msgGateRefused(why) {
+    return (`Reticle gate: ${why.replace(/\.+$/, '')}. The gate could not ask the platform this project is linked to for its ` +
+        'regression report, so it fails closed rather than pass without it.');
+}
+/** Said when the gate had no saved flows to judge, so exit 2 does not read as the change failing. */
+export const MSG_GATE_NO_FLOWS = 'Reticle gate: no saved flows here, so there was nothing to check; this is not a failure of this ' +
+    'change. Record one by driving the app with reticle_act_and_wait, or run ' +
+    '`reticle verify <url> --explore`, then run the gate again.';
+/**
+ * Said when the platform knows a regression, outside a hook. Exit 3 printed only the JSON log, whose
+ * coverage field still read "no flows recorded — nothing was checked", so nothing a person read
+ * said "regression".
+ */
+export function msgGateRegression(broken) {
+    const names = broken.map((entry) => {
+        if ('string' === typeof entry)
+            return entry;
+        const record = 'object' === typeof entry && null !== entry ? entry : {};
+        const name = record['flowName'] ?? record['name'];
+        const was = record['previousStatus'];
+        const now = record['currentStatus'];
+        const flow = 'string' === typeof name ? name : 'a flow';
+        return 'string' === typeof was && 'string' === typeof now ? `${flow} (${was} → ${now})` : flow;
+    });
+    return (`Reticle gate: regression — ${names.join(', ')} passed before and fails now on the platform. ` +
+        'See `reticle runs regression`.');
+}

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

@@ -27,6 +27,8 @@ interface GateHookInput {
     coverageRegressed?: readonly string[];
     /** Changed files the browser loaded and never ran a function of. */
     unexecuted?: readonly string[];
+    /** Flows the platform says passed before and are broken now. */
+    regressed?: number;
 }
 /**
  * The message, or undefined when there is nothing to say.

package/dist/command/cli/answers/gate-hook-message.js

@@ -28,9 +28,11 @@ function name(list) {
  * interrupted.
  */
 export function gateHookMessage(exit, input) {
-    if (GateExit.FAIL !== exit)
+    if (GateExit.FAIL !== exit && GateExit.REGRESSION !== exit)
         return undefined;
     const lines = ['Reticle: this change is not verified.'];
+    if (input.regressed !== undefined && 0 < input.regressed)
+        lines.push(`  ${String(input.regressed)} flow(s) that passed before are broken now — \`reticle runs regression\` names them`);
     if (input.uncovered.length > 0)
         lines.push(`  no passing run covers: ${name(input.uncovered)}`);
     if (input.downgraded.length > 0)

package/dist/command/cli/answers/open-note.d.ts

@@ -18,3 +18,5 @@
  * So the substitution is stated FIRST, with both numbers, before any cause that assumes they match.
  */
 export declare function openFailureNote(port: number, requestedPort: number): string;
+/** Recovery when the OS could not open a URL: agents can use Reticle's browser lease instead. */
+export declare function openLaunchFailureNote(url: string, launcher: string): string;

package/dist/command/cli/answers/open-note.js

@@ -1,3 +1,18 @@
+import { ReticleTool } from '@reticlehq/core';
+const LeaseAction = { ACQUIRE: 'acquire' };
+const LeaseArgument = {
+    TOOL: 'tool',
+    ARGS: 'args',
+    ACTION: 'action',
+    URL: 'url',
+};
+const OpenLaunchFailureCopy = {
+    NOTHING_OPENED: 'Nothing was opened.',
+    OS_BROWSER: 'This command asks the OS to open a url in your default browser',
+    LAUNCH_FAILED: (launcher) => `(\`${launcher}\` on this platform) and that failed,`,
+    OPEN_MANUALLY: 'so open the url yourself or set a default browser.',
+    RETICLE_BROWSER: 'If you are using Reticle tools, open it in a Reticle-owned browser with',
+};
 /**
  * What `reticle open` says when it launched a URL and no session appeared.
  *
@@ -35,3 +50,10 @@ export function openFailureNote(port, requestedPort) {
         `non-localhost host, which needs BOTH allowNonLocalhost: true AND a pairing token ` +
         `(~/.reticle/pairing-token) — the flag alone is not sufficient.`);
 }
+/** Recovery when the OS could not open a URL: agents can use Reticle's browser lease instead. */
+export function openLaunchFailureNote(url, launcher) {
+    return (`${OpenLaunchFailureCopy.NOTHING_OPENED} ${OpenLaunchFailureCopy.OS_BROWSER} ` +
+        `${OpenLaunchFailureCopy.LAUNCH_FAILED(launcher)} ${OpenLaunchFailureCopy.OPEN_MANUALLY} ` +
+        `${OpenLaunchFailureCopy.RETICLE_BROWSER} ` +
+        `\`${ReticleTool.RUN} { ${LeaseArgument.TOOL}: "${ReticleTool.LEASE}", ${LeaseArgument.ARGS}: { ${LeaseArgument.ACTION}: "${LeaseAction.ACQUIRE}", ${LeaseArgument.URL}: ${JSON.stringify(url)} } }\`.`);
+}

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

@@ -19,19 +19,19 @@ export declare const DeviceStartSchema: z.ZodObject<{
     interval: z.ZodNumber;
     expiresAt: z.ZodNumber;
 }, "strip", z.ZodTypeAny, {
-    expiresAt: number;
     deviceCode: string;
     userCode: string;
     verificationUri: string;
     verificationUriComplete: string;
     interval: number;
-}, {
     expiresAt: number;
+}, {
     deviceCode: string;
     userCode: string;
     verificationUri: string;
     verificationUriComplete: string;
     interval: number;
+    expiresAt: number;
 }>;
 /**
  * What `/v1/auth/device/token` answers while polling. Everything past `status` is optional because
@@ -66,6 +66,17 @@ export declare const DevicePollSchema: z.ZodObject<{
         id?: string | undefined;
     } | undefined;
 }>;
+/**
+ * Where a sign-in started, carried to the approval page as `from` so the platform can attribute the
+ * signup. The platform's `/device` reads the same closed set (plus `app`, its own).
+ */
+export declare const LoginOrigin: {
+    readonly TERMINAL: "terminal";
+    readonly HUD: "hud";
+};
+export type LoginOrigin = (typeof LoginOrigin)[keyof typeof LoginOrigin];
+/** The approval URL with `from` set; a URL that does not parse is left as the cloud sent it. */
+export declare function withLoginOrigin(url: string, from: LoginOrigin): string;
 /**
  * Best-effort open the approval page in the default browser.
  *

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

@@ -31,6 +31,23 @@ export const DevicePollSchema = z.object({
     token: z.string().optional(),
     org: z.object({ id: z.string().optional(), name: z.string() }).optional(),
 });
+/**
+ * Where a sign-in started, carried to the approval page as `from` so the platform can attribute the
+ * signup. The platform's `/device` reads the same closed set (plus `app`, its own).
+ */
+export const LoginOrigin = { TERMINAL: 'terminal', HUD: 'hud' };
+const FROM_PARAM = 'from';
+/** The approval URL with `from` set; a URL that does not parse is left as the cloud sent it. */
+export function withLoginOrigin(url, from) {
+    try {
+        const parsed = new URL(url);
+        parsed.searchParams.set(FROM_PARAM, from);
+        return parsed.toString();
+    }
+    catch {
+        return url;
+    }
+}
 /**
  * Best-effort open the approval page in the default browser.
  *

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

@@ -1,4 +1,5 @@
 import { existsSync, readFileSync } from 'node:fs';
+import { keychainNoteFor } from './doctor/doctor-signing-line.js';
 import { join } from 'node:path';
 import { devServersForProject, ReticleEnv } from '@reticlehq/core';
 import { readPid, reticleStateHome } from '../daemon/daemon.js';
@@ -18,6 +19,11 @@ import { CONTRACT_FINGERPRINT } from '@reticlehq/core';
 import { CspBasis, diagnoseDesktop, diagnoseObservedWebCsp, diagnoseWebCsp, isDesktopProject, resolveWebCspFindings, webCspOptionsFor, } from '@reticlehq/init';
 import { RETICLE_CONFIG_BASENAME, diagnosePortMismatch, readProjectFramework, readProjectId, readProjectPort, } from './ports/resolve/cli-port.js';
 import { DoctorRow, doctorRow } from './doctor/doctor-rows.js';
+import { coverageLines } from './doctor/doctor-coverage-line.js';
+import { homedir } from 'node:os';
+import { createNodeFileSystem } from '../../memory/project/fs/fs-port.js';
+import { describeUnsynced } from '../../memory/cloud/unsynced-roots.js';
+import { machineUnsyncedRoots } from '../../memory/project/sync-status.js';
 import { attachState, describeAttachState } from '../../surface/mcp/attach-memory.js';
 import { findOccupiedSiblings, siblingListenerNote } from './ports/sibling-ports.js';
 import { daemonsServingProjectElsewhere, resolveDaemonForProject, splitBrainNote, wrongDaemonNote, } from '../daemon/daemon-resolve.js';
@@ -118,6 +124,11 @@ export async function handleDoctor(port) {
     }
     if (sessions !== undefined)
         line(sessions.text);
+    for (const row of coverageLines(daemonStatus))
+        line(row);
+    // Runs nothing will send, named by folder with the one command that sends them.
+    for (const entry of await machineUnsyncedRoots(createNodeFileSystem(), homedir(), process.env))
+        line(doctorRow(DoctorRow.UNSYNCED, `✗ ${describeUnsynced(entry, process.cwd())}`));
     line(doctorRow(DoctorRow.BRIDGE_PORT, `${port}  (your app must dial THIS port, not your dev-server port)`));
     const projectPort = readProjectPort(process.cwd());
     const mismatch = diagnosePortMismatch(port, projectPort);
@@ -234,4 +245,7 @@ export async function handleDoctor(port) {
         // findings above exist to remove.
         line(doctorRow(DoctorRow.DESKTOP, '✓ desktop wiring looks right'));
     }
+    const keychain = keychainNoteFor({ read: readProjectFile });
+    if (keychain !== undefined)
+        line(doctorRow(DoctorRow.DESKTOP, `⚠ ${keychain}`));
 }

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

@@ -26,17 +26,6 @@ export declare function resolveChangedFiles(files: string[], since: string | und
  * confident negative about somebody else's project, which is worse than an error.
  */
 export declare function loadNamedFlows(fs: FileSystemPort, reticleRoot: string, projectId: ProjectId | undefined): Promise<NamedFlow[]>;
-/**
- * `reticle watch [url]` — on every save, report which saved flows must re-verify (the affected set).
- * Environment-side (costs the agent nothing per turn); the buddy loop. This v1 detects + reports on
- * change; auto-replaying the affected flows against the app is the next increment. Long-running.
- */
-export declare function handleWatch(): void;
-/**
- * `reticle capsules` — list saved fail-to-pass bug capsules (.reticle/capsules). Each is a minimal
- * failing reproduction plus the consequence that should have held; replay one with reticle_flow_replay.
- */
-export declare function handleCapsules(): Promise<void>;
 export declare function handleGate(files: string[], since: string | undefined, 
 /** Hook mode: prose for a human, and silence when there was simply nothing to check. */
 hook?: boolean, 

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

@@ -5,27 +5,25 @@
  * 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 { GateExit } from './answers/gate-exit.js';
+import { GateExit, MSG_GATE_NO_FLOWS, msgGateRegression, msgGateRefused, gateExitWith, } from './answers/gate-exit.js';
+import { knownRegression } from './known-regression.js';
 import { gateHookMessage, GATE_SKIP_ENV } from './answers/gate-hook-message.js';
 import { readProjectId } from './ports/resolve/cli-port.js';
 import { changedFilesSince } from '../../language/flows/change/git-changed.js';
 import { join } from 'node:path';
-import { ReticleDir, RunFlowStatus } from '@reticlehq/core';
+import { ReticleDir } from '@reticlehq/core';
 import { FlowStore } from '../../language/flows/flows.js';
 import { RunStore } from '../../judgement/runs/artifact/run-store.js';
 import { createNodeFileSystem } from '../../memory/project/fs/fs-port.js';
 import { affectedSavedFlows, toFlowSources, } from '../../language/flows/change/flow-sources.js';
 import { isInteractiveSource, unflowedFiles } from '../../language/flows/change/affected.js';
 import { LedgerStore, regressions, staleChanged, unexecutedChanged, } from '../../features/exhaust/ledger.js';
-import { gateDecision } from '../../language/flows/change/gate.js';
+import { gateDecision, passingFlowNames } from '../../language/flows/change/gate.js';
 import { FlakeStore } from '../../language/flows/stores/flake-store.js';
-import { formatBuddyStatus } from '../../language/flows/buddy-status.js';
-import { CapsuleStore } from '../../judgement/capsule/capsule-store.js';
 import { AssertionTiersStore } from '../../language/flows/stores/assertion-tiers-store.js';
 import { detectDowngrades } from '../../judgement/outcome/assertion-integrity.js';
 import { computeCoverage, flowCoverageReport } from '../../language/flows/suite/coverage.js';
-import { createWatchBatcher } from '../../language/flows/change/watch-batcher.js';
-import { readFileSync, statSync, watch } from 'node:fs';
+import { readFileSync, statSync } from 'node:fs';
 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. */
@@ -63,103 +61,6 @@ export async function loadNamedFlows(fs, reticleRoot, projectId) {
     }
     return flows;
 }
-/** File-change extensions worth reacting to (skip node_modules churn, dotfiles, build output). */
-/**
- * The buddy channel: one ambient line a human can park in a statusline. Deliberately best-effort
- * and silent on failure — a status line that throws is worse than no status line, and it must never
- * interfere with the watch loop it rides on.
- */
-async function emitBuddyStatus(fs, reticleRoot, flows, affected) {
-    try {
-        const latest = await new RunStore(fs, reticleRoot).latest();
-        const passingNames = new Set((latest?.flows ?? [])
-            .filter((f) => f.status === RunFlowStatus.PASS || f.status === RunFlowStatus.HEALED)
-            .map((f) => f.name));
-        const quarantined = await new FlakeStore(fs, reticleRoot).flakyFlows();
-        const flaky = new Set(quarantined);
-        // A deviation is an at-risk flow with no passing artifact — and a quarantined flake is not a deviation.
-        const deviations = affected.filter((n) => !passingNames.has(n) && !flaky.has(n));
-        log('reticle_buddy', {
-            status: formatBuddyStatus({
-                total: flows.length,
-                passing: passingNames.size,
-                deviations,
-                quarantined,
-            }),
-        });
-    }
-    catch {
-        // never let the ambient line break the watcher
-    }
-}
-const WATCHED_EXTENSIONS = /\.(ts|tsx|js|jsx|mjs|cjs|vue|svelte)$/;
-const WATCH_DEBOUNCE_MS = 200;
-/**
- * `reticle watch [url]` — on every save, report which saved flows must re-verify (the affected set).
- * Environment-side (costs the agent nothing per turn); the buddy loop. This v1 detects + reports on
- * change; auto-replaying the affected flows against the app is the next increment. Long-running.
- */
-export function handleWatch() {
-    const fs = createNodeFileSystem();
-    const reticleRoot = join(process.cwd(), ReticleDir.ROOT);
-    const batcher = createWatchBatcher({
-        debounceMs: WATCH_DEBOUNCE_MS,
-        schedule: (fn, ms) => {
-            setTimeout(fn, ms).unref();
-        },
-        onFlush: (files) => {
-            void loadNamedFlows(fs, reticleRoot, readProjectId(process.cwd()))
-                .then(async (flows) => {
-                const result = affectedSavedFlows(flows, files);
-                if (result.affected.length > 0) {
-                    log('reticle_watch_affected', { changed: files, affected: result.affected });
-                }
-                await emitBuddyStatus(fs, reticleRoot, flows, result.affected);
-            })
-                .catch((error) => {
-                log('reticle_watch_failed', {
-                    error: error instanceof Error ? error.message : String(error),
-                });
-            });
-        },
-    });
-    log('reticle_watch_started', { cwd: process.cwd() });
-    // Print the ambient line once at startup so the human sees where they stand before touching anything.
-    void loadNamedFlows(fs, reticleRoot, readProjectId(process.cwd()))
-        .then((flows) => emitBuddyStatus(fs, reticleRoot, flows, []))
-        .catch(() => undefined);
-    watch(process.cwd(), { recursive: true }, (_event, filename) => {
-        if ('string' === typeof filename && WATCHED_EXTENSIONS.test(filename))
-            batcher.onChange(filename);
-    });
-}
-/**
- * `reticle capsules` — list saved fail-to-pass bug capsules (.reticle/capsules). Each is a minimal
- * failing reproduction plus the consequence that should have held; replay one with reticle_flow_replay.
- */
-export async function handleCapsules() {
-    try {
-        const fs = createNodeFileSystem();
-        const capsules = await new CapsuleStore(fs, join(process.cwd(), ReticleDir.ROOT)).all();
-        log('reticle_capsules', {
-            count: capsules.length,
-            capsules: capsules.map((c) => ({
-                id: c.id,
-                ...(c.flow === undefined ? {} : { flow: c.flow }),
-                origin: c.origin,
-                expected: c.expected,
-                observed: c.observed,
-                steps: c.steps.length,
-            })),
-        });
-    }
-    catch (error) {
-        log('reticle_capsules_failed', {
-            error: error instanceof Error ? error.message : String(error),
-        });
-        process.exitCode = 1;
-    }
-}
 /**
  * `reticle gate <file...>` — exit non-zero unless passing artifacts cover the flows affected by the
  * changed files. Flaky flows are quarantined (surfaced, not blocking). The environment-side enforcement
@@ -202,9 +103,7 @@ acceptCoverage = false) {
         const allFlows = await loadNamedFlows(fs, reticleRoot, readProjectId(process.cwd()));
         const affected = affectedSavedFlows(allFlows, changed).affected;
         const latest = await new RunStore(fs, reticleRoot).latest();
-        const passing = (latest?.flows ?? [])
-            .filter((f) => f.status === RunFlowStatus.PASS || f.status === RunFlowStatus.HEALED)
-            .map((f) => f.name);
+        const passing = passingFlowNames(latest?.flows ?? []);
         const flaky = await new FlakeStore(fs, reticleRoot).flakyFlows();
         // Anti-reward-hacking: diff each flow's CURRENT assertions against what it asserted the last
         // time it passed. A mustHold that dropped from a real consequence to a fakeable presence check is a
@@ -264,8 +163,19 @@ acceptCoverage = false) {
         // verdict already applies to `reticle verify`; see flowCoverageReport.
         const flowCoverage = flowCoverageReport(coverage.flows);
         const pass = result.pass && flowCoverage.outcome === undefined;
+        // What the platform knows decides too (a regression, a refused key), so the line is written
+        // once the exit code is: it said "pass": true over an exit of 1 or 3.
+        const known = await knownRegression(reticleRoot);
+        const regressed = known.broken;
+        const local = pass
+            ? GateExit.PASS
+            : result.pass && flowCoverage.outcome !== undefined
+                ? GateExit.NOTHING_TO_CHECK
+                : GateExit.FAIL;
+        // Fails closed in CI, not in an agent's stop hook, where it would block over a key, not a change.
+        const code = gateExitWith(local, regressed?.length, !hook && known.refused !== undefined);
         log('reticle_gate', {
-            pass,
+            pass: GateExit.PASS === code,
             uncovered: result.uncovered,
             quarantined: result.quarantined,
             ...(result.downgraded.length > 0 ? { downgraded: result.downgraded } : {}),
@@ -283,10 +193,18 @@ acceptCoverage = false) {
         // problem to fail. A Stop hook wants to block a real regression and NOT block a project that
         // has simply not recorded a flow yet — which is every project on its first day, and measured
         // before this change as an exit 1 that would have blocked every stop. See GateExit.
-        if (!pass) {
-            const code = result.pass && flowCoverage.outcome !== undefined
-                ? GateExit.NOTHING_TO_CHECK
-                : GateExit.FAIL;
+        // A regression the platform already knows fails the build here too, with `reticle runs
+        // regression`'s code, so the gate is the one command CI needs. Best-effort: unlinked or offline
+        // changes nothing.
+        if (regressed !== undefined && 0 < regressed.length)
+            log('reticle_gate_regression', { broken: regressed });
+        if (known.refused !== undefined)
+            process.stderr.write(`${msgGateRefused(known.refused)}\n`);
+        if (GateExit.NOTHING_TO_CHECK === code && !hook)
+            process.stderr.write(`${MSG_GATE_NO_FLOWS}\n`);
+        if (GateExit.REGRESSION === code && !hook && regressed !== undefined)
+            process.stderr.write(`${msgGateRegression(regressed)}\n`);
+        if (GateExit.PASS !== code) {
             process.exitCode = code;
             if (hook) {
                 // An honest escape hatch, because the alternative to one is not compliance — it is somebody
@@ -305,6 +223,7 @@ acceptCoverage = false) {
                     unflowed: result.unflowed,
                     coverageRegressed: result.coverageRegressed.map((r) => `${r.level} ${String(r.was)}% -> ${String(r.now)}%`),
                     unexecuted: result.unexecuted,
+                    regressed: regressed?.length ?? 0,
                 });
                 if (message !== undefined)
                     process.stderr.write(`${message}\n`);

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

@@ -64,8 +64,9 @@ export function planKill(input) {
         holder: listener,
         reason: `pid ${String(listener.pid)} ("${listener.command}") is listening, and it is not a Reticle ` +
             `daemon — it never answered /status and it is not the pid Reticle recorded. Killing it would ` +
-            `be killing someone else's process. Run it again with ${FORCE_FLAG} if that is what you ` +
-            `meant, or start Reticle on another port.`,
+            `be killing someone else's process. If that is what you meant, \`reticle restart ${FORCE_FLAG}\` ` +
+            `stops it and starts Reticle there (\`stop ${FORCE_FLAG}\` never does); or start Reticle on ` +
+            `another port.`,
     };
 }
 /** How long the target gets to exit on SIGTERM before we stop asking politely. */

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

@@ -34,3 +34,27 @@ export declare const VERIFY_COMMAND = "verify";
  * missed for a release.
  */
 export declare const EXPECT_FLAG = "--expect";
+/**
+ * The account and cloud commands. They are dispatched before the typed parser, and listed here so
+ * that the dispatcher and the telemetry vocabulary read one list instead of two.
+ */
+export declare const CLOUD_COMMANDS: readonly string[];
+/**
+ * Old command names that still run, for one release, under the name that replaced them. Each one
+ * prints a single line saying so, then does what it always did.
+ */
+export declare const RENAMED_COMMANDS: ReadonlyMap<string, string>;
+/**
+ * The command an old name now goes by, when the note saying so should print; otherwise undefined.
+ * Not for a request for help (that answer names the new command itself), and not for
+ * `login --email`, which `connect --help` documents as the sign-in for CI and agents.
+ */
+export declare function renamedCommandFor(argv: readonly string[]): string | undefined;
+/**
+ * Commands that were removed, and what to use instead. They stay in the telemetry vocabulary, so
+ * the people still typing one show up as that name rather than as `unknown`.
+ */
+export declare const REMOVED_COMMANDS: ReadonlyMap<string, string>;
+export declare const removedNote: (command: string, instead: string) => string;
+/** One line on stderr when an old name ran: dim on a terminal, plain anywhere else. */
+export declare const renamedNote: (command: string, now: string, colour: boolean) => string;