@reticlehq/server 3.3.0 → 3.5.0

package/dist/index.js

@@ -4,12 +4,12 @@ import { fetchPlatformConfig } from './features/harness/platform-config.js';
 import { join } from 'node:path';
 import { existsSync, readFileSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { linkedCloudPort } from './memory/cloud/cloud-config.js';
+import { linkedCloudPort, platformEnvPort } from './memory/cloud/cloud-config.js';
 import { attachCloudSync } from './memory/cloud/sync-daemon.js';
 import { wireHooks } from './hooks/hook-commands.js';
 import { PROJECT_REGISTRY_FILE, parseProjectRegistry, projectCandidates, } from '@reticlehq/core/artifacts';
 import { discoverProjectConfigs } from './command/cli/config/config-discovery.js';
-import { artifactRootResolver } from './memory/project/artifact-root-resolver.js';
+import { artifactRootResolver, projectDirectoryFor, } from './memory/project/artifact-root-resolver.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { AGENT_STOPPED_NOTICE, RETICLE_DEFAULT_PORT, bridgeWsUrl, ReticleCommand, ReticleDir, ReticleEnv, LOOPBACK_HOST, ReplayStatus, EventType, } from '@reticlehq/core';
 import { originOf } from './portal/session/session-manager.js';
@@ -21,10 +21,12 @@ import { reportAppInstrumented } from './telemetry/app-instrumented.js';
 import { resolveBridgeSecurityWithAutoToken } from './portal/bridge/bridge-security.js';
 import { Bridge } from './portal/bridge/bridge.js';
 import { sdkFixForDirectory } from './command/version/sdk-fix.js';
+import { connectionSkew } from './command/version/version-nudge.js';
 import { SERVER_VERSION } from './command/version/identity/server-version.js';
 import { BaselineStore } from './memory/project/baselines.js';
 import { RecordingStore } from './language/flows/recording/tape/recordings.js';
 import { initImpact } from './memory/impact/impact-recorder.js';
+import { flowAuthor } from './language/flows/flow-author.js';
 import { FlowStore } from './language/flows/flows.js';
 import { buildFlowChips } from './language/flows/flow-scope.js';
 import { ProjectStore } from './memory/project/project-store.js';
@@ -42,7 +44,7 @@ import { LEASE_ACQUIRE_TOOL } from './surface/tools/lease-tools.js';
 import { runTool } from './surface/tools/invoke-tool.js';
 import { SessionReaper, endAllSessions, MCP_DISCONNECT_SUMMARY, } from './portal/session/session-reaper.js';
 import { wireSessionScope } from './portal/session/no-session-watch.js';
-import { buildIdlePredicate } from './command/daemon/lifetime/daemon-usefulness.js';
+import { buildIdlePredicate, noteSetupHold } from './command/daemon/lifetime/daemon-usefulness.js';
 import { resolveToolSurface } from './surface/tools/tool-surface.js';
 import { statusPayload } from './status-payload.js';
 import { CdpRealInputProvider, LaunchedRealInputProvider } from './portal/input/real-input.js';
@@ -54,7 +56,7 @@ import { LeaseReaper } from './portal/pool/lease-reaper.js';
 import { findProjectConfig, projectIdsAt, readJournalEnabled, readProjectId, } from './command/cli/ports/resolve/cli-port.js';
 import { hasAnyProjectConnectedBefore } from './memory/recall/prior/connection-memory.js';
 import { reticleStateHome } from './command/daemon/daemon.js';
-import { probeChromium } from './command/cli/doctor/browser/chromium-hint.js';
+import { probeLaunchableChromium } from './launch-chromium.js';
 import { attachJournal } from './wire-journal.js';
 import { reportOnboardingStep } from './telemetry/onboarding-funnel.js';
 import { AMBIENT_RECORDING } from './language/flows/recording/tape/recordings.js';
@@ -80,6 +82,15 @@ export { buildSessionRecommendation } from './portal/session/presence/session-re
 export { TOOLS } from './surface/tools/tools.js';
 export { createToolInvoker, UNKNOWN_TOOL_ERROR } from './surface/tools/tool-invoker.js';
 export { runTool, SESSION_BOUND_TOOLS, SESSION_EXEMPT_TOOLS } from './surface/tools/invoke-tool.js';
+/**
+ * The port-presence check the CLI commands (`drive`, `verify`, `status`, `doctor`, `kill`) all share,
+ * re-exported so a consumer embedding `start()` in its own process can refuse a taken port the same
+ * honest way instead of letting a raw `EADDRINUSE` stack out — the gap `@reticlehq/test`'s
+ * `bootSession()` had (reticlehq/reticle#1141): it called `start()` directly with no pre-flight probe.
+ */
+export { probePresence, describePresence, PortPresence, } from './command/daemon/binding/port-presence.js';
+export { probeDaemon } from './surface/mcp/proxy/proxy-daemon-probe.js';
+export { fetchStatus } from './command/daemon/binding/daemon-status-probe.js';
 export { BaselineStore, normalizeLines, diffLines } from './memory/project/baselines.js';
 export { RecordingStore } from './language/flows/recording/tape/recordings.js';
 export { FlowStore, recordedStepToFlowStep } from './language/flows/flows.js';
@@ -215,12 +226,12 @@ async function resolveRealInput(options, onNavigateError, onNetworkDetail) {
 }
 /** Start the Reticle bridge (browser WS endpoint) and, by default, the MCP stdio server. */
 /**
- * The SDK-upgrade sentence for THIS project's package.json, evaluated at each HELLO so a
- * just-edited manifest is what we name. Falls back to the framework-neutral sensor when cwd is
- * not an app.
+ * The SDK-upgrade sentence for the package.json of the project the page announced, evaluated at
+ * each HELLO so a just-edited manifest is what we name. The daemon's cwd only when that project's
+ * directory is unknown, and the framework-neutral sensor when that is not an app either (#1135).
  */
-function sdkFixForCwd() {
-    return sdkFixForDirectory(SERVER_VERSION, process.cwd());
+function sdkFixForProject(projectId) {
+    return sdkFixForDirectory(SERVER_VERSION, projectDirectoryFor(projectId) ?? process.cwd());
 }
 /**
  * Resolve a session's artifact root, from everything this machine knows about where projects live.
@@ -263,6 +274,8 @@ function knownProjectRoots() {
     }
     return [...roots];
 }
+/** This project's platform credential (stored, else the env key), as the env the platform readers take. */
+const platformEnvFor = (root) => platformEnvPort(createNodeFileSystem(), root ?? join(process.cwd(), ReticleDir.ROOT), homedir(), process.env);
 export async function start(options = {}) {
     const port = options.port ?? RETICLE_DEFAULT_PORT;
     // Open the user's impact record before anything can connect. Not inside the MCP branch: a daemon
@@ -273,11 +286,11 @@ export async function start(options = {}) {
         // The daemon owns both sides of this seam, so it is the layer that may join them: the cache
         // lives in cloud memory, the platform read lives in the harness feature, and neither is allowed
         // to reach for the other.
-        config: harnessConfigSource(() => fetchPlatformConfig(process.env)),
+        config: harnessConfigSource(async () => fetchPlatformConfig(await platformEnvFor(options.reticleRoot)())),
     });
     const uninstallHooks = wireHooks(options.reticleRoot ?? join(process.cwd(), ReticleDir.ROOT), readProjectId(process.cwd()));
     const security = await resolveBridgeSecurityWithAutoToken(options);
-    const bridge = new Bridge({ port, sdkFix: sdkFixForCwd, ...security });
+    const bridge = new Bridge({ port, sdkFix: sdkFixForProject, ...security });
     // Server-authoritative liveness: a Node-side reaper (immune to browser throttling) ends sessions
     // whose agent has gone idle, so a forgotten/crashed agent never leaves the HUD "running" forever.
     const reaper = new SessionReaper(bridge.sessions);
@@ -316,6 +329,7 @@ export async function start(options = {}) {
             takeAmbientTape: () => recordings.stop(AMBIENT_RECORDING),
             reportStep: reportOnboardingStep,
             flows,
+            author: flowAuthor,
         });
         const project = new ProjectStore(fs, reticleRoot, { now });
         attachRouteLearning(bridge, projectStoreResolver(fs, project, reticleRoot, now));
@@ -352,16 +366,23 @@ export async function start(options = {}) {
             project,
             fs,
             reticleRoot,
+            linkedCloud: linkedCloudPort(fs, reticleRoot, homedir(), process.env),
             artifactRootFor: artifactRootResolver(reticleRoot),
             now,
             bridgePort: port,
-            browserProbe: probeChromium,
+            browserProbe: probeLaunchableChromium,
             // The daemon's OWN project, so a tool can tell "this session is mine" from "this session
             // belongs to a sibling app under the same daemon". contract_save refuses on the second.
             ...(activeProjectId === undefined ? {} : { projectId: activeProjectId }),
         };
         const profile = resolveToolSurface(options.toolProfile);
-        const server = createMcpServer(realInput !== undefined ? { ...deps, realInput } : deps, profile, hasAnyProjectConnectedBefore(reticleStateHome(), port, projectIdsAt(process.cwd())));
+        const server = createMcpServer(realInput !== undefined ? { ...deps, realInput } : deps, profile, 
+        // A session live RIGHT NOW is stronger evidence than the durable memory, which can be empty or
+        // stale for a project the plugin wired without writing `.reticle.json` (see connection-memory.ts's
+        // KNOWN LIMIT). Without this OR, that project's `initialize` led with the first-install steps
+        // while a real session was already connected — see #1138.
+        bridge.sessions.count() > 0 ||
+            hasAnyProjectConnectedBefore(reticleStateHome(), port, projectIdsAt(process.cwd())));
         // When the agent (the MCP client) disconnects cleanly, end every active session at once so the
         // HUD doesn't linger. (If the agent instead KILLS this process, the WS dies and the browser
         // self-ends via SESSION_LIFECYCLE.BRIDGE_LOST_MS — see transport.ts.)
@@ -404,11 +425,16 @@ export async function startDaemon(options = {}) {
         // The daemon owns both sides of this seam, so it is the layer that may join them: the cache
         // lives in cloud memory, the platform read lives in the harness feature, and neither is allowed
         // to reach for the other.
-        config: harnessConfigSource(() => fetchPlatformConfig(process.env)),
+        config: harnessConfigSource(async () => fetchPlatformConfig(await platformEnvFor(options.reticleRoot)())),
     });
     const security = await resolveBridgeSecurityWithAutoToken(options);
     const shared = createSharedServer(security.token === undefined ? {} : { token: security.token });
-    const bridge = new Bridge({ port, server: shared.httpServer, sdkFix: sdkFixForCwd, ...security });
+    const bridge = new Bridge({
+        port,
+        server: shared.httpServer,
+        sdkFix: sdkFixForProject,
+        ...security,
+    });
     // The daemon owns listen (below), so the real bind error is reported there; absorb bridge.ready's
     // mirror rejection so a port collision can't surface as an unhandled promise rejection.
     void bridge.ready.catch(() => undefined);
@@ -420,7 +446,12 @@ export async function startDaemon(options = {}) {
     // answers WHY rather than just "sessionCount: 0".
     // `verifyPort` rides along so a later `serve --http` can tell whether this daemon already honours
     // the requested `--http-port` instead of silently ignoring the flag (#687).
-    shared.attachStatus(() => statusPayload(bridge.sessions.count(), bridge.sessions.list(), bridge.sessions.noSessionHint(), verifyHttp?.port, bridge.sessions.noSessionLead()));
+    shared.attachStatus((held) => {
+        // `init` holds the daemon it is waiting on, so the idle rule cannot shut it down mid-wait.
+        if (held)
+            noteSetupHold(Date.now());
+        return statusPayload(bridge.sessions.count(), bridge.sessions.list(), bridge.sessions.noSessionHint(), verifyHttp?.port, bridge.sessions.noSessionLead());
+    });
     // Agent-independent presence: the daemon outlives any single agent, so when the LAST agent's MCP
     // connection drops (it stopped, or is waiting on the human), end every session and push a clear
     // "go to your terminal" notice to the panel — the human is on the browser and must not lose a typed
@@ -462,6 +493,7 @@ export async function startDaemon(options = {}) {
         takeAmbientTape: () => recordings.stop(AMBIENT_RECORDING),
         reportStep: reportOnboardingStep,
         flows,
+        author: flowAuthor,
         onRunPersisted: () => syncNudge.run?.(),
     });
     const project = new ProjectStore(fs, reticleRoot, { now });
@@ -501,7 +533,7 @@ export async function startDaemon(options = {}) {
     // console and the panel cannot disagree about a setting they both offer. Nothing is awaited and a
     // failure is not surfaced: the next snapshot re-reads the platform, so a lost write shows up as
     // the switch springing back, which is the truthful outcome.
-    bridge.attachHarnessRequest((enabled) => void writeHarnessSwitch(process.env, enabled));
+    bridge.attachHarnessRequest((enabled) => void platformEnvFor(reticleRoot)().then((env) => writeHarnessSwitch(env, enabled)));
     // Scope auto-selection to the active project (from .reticle.json) so a stray tab from another app is
     // never picked when the agent omits a sessionId. Explicit per-call scope/sessionId still overrides.
     // Scope + the no-session diagnosis: "no browser session connected" is the error that ends most
@@ -533,7 +565,7 @@ export async function startDaemon(options = {}) {
         artifactRootFor: artifactRootResolver(reticleRoot),
         now,
         bridgePort: port,
-        browserProbe: probeChromium,
+        browserProbe: probeLaunchableChromium,
         // A finished verification should not sit behind a one-minute timer — see ToolDeps.onRunPersisted.
         onRunPersisted: () => cloudSync.nudge(),
     };
@@ -541,7 +573,12 @@ export async function startDaemon(options = {}) {
     const effectiveDeps = realInput !== undefined ? { ...deps, realInput } : deps;
     // Read per attach, not once: a project that gets wired while this daemon is alive should stop
     // being told to wire itself on the next agent that connects.
-    shared.attachMcp(() => createMcpServer(effectiveDeps, profile, hasAnyProjectConnectedBefore(reticleStateHome(), port, projectIdsAt(process.cwd()))));
+    shared.attachMcp((peerSkew) => createMcpServer(peerSkew === undefined
+        ? effectiveDeps
+        : { ...effectiveDeps, peerSkew: connectionSkew(peerSkew) }, profile, 
+    // See the sibling call in `start`: a live session outweighs empty/stale durable memory (#1138).
+    bridge.sessions.count() > 0 ||
+        hasAnyProjectConnectedBefore(reticleStateHome(), port, projectIdsAt(process.cwd()))));
     // `reticle drive <url>` when this daemon already owns the port: it asks HERE instead of trying to
     // bind a port we are holding, and gets the same pooled context an agent's reticle_lease returns —
     // through runTool, so it is counted and reported like any other call rather than being a second,

package/dist/judgement/capsule/capsule-store.d.ts

@@ -42,10 +42,10 @@ declare const CapsuleSchema: z.ZodObject<{
     seen: z.ZodOptional<z.ZodNumber>;
     lastSeenAt: z.ZodOptional<z.ZodNumber>;
 }, "strip", z.ZodTypeAny, {
-    expected: string;
-    origin: string;
     version: 1;
     id: string;
+    origin: string;
+    expected: string;
     steps: FlowStep[];
     createdAt: number;
     observed: string;
@@ -53,10 +53,10 @@ declare const CapsuleSchema: z.ZodObject<{
     seen?: number | undefined;
     lastSeenAt?: number | undefined;
 }, {
-    expected: string;
-    origin: string;
     version: 1;
     id: string;
+    origin: string;
+    expected: string;
     steps: FlowStep[];
     createdAt: number;
     observed: string;

package/dist/judgement/domain/domain-model.js

@@ -12,7 +12,7 @@
  *
  * Pure: no IO, no clock. The tool layer loads flows + contract and calls this.
  */
-import { AnchorKind, PredicateKind, } from '@reticlehq/core';
+import { AnchorKind, PredicateKind, compareSourceClauses, } from '@reticlehq/core';
 import { classifyFlowAssertions, FlowAssertionGrade } from '../../language/flows/flow-classify.js';
 import { successLabel } from '../../language/flows/flow-success.js';
 import { flowRisk, latestRun, rankByRisk, RiskLevel } from './flow-risk.js';
@@ -41,6 +41,8 @@ function walkClauses(predicate) {
     }
     if (PredicateKind.NOT === predicate.kind)
         return walkClauses(predicate.predicate);
+    if (PredicateKind.COMPARE === predicate.kind)
+        return compareSourceClauses(predicate);
     return [predicate];
 }
 function signalNamesIn(predicate) {

package/dist/judgement/oracles/self-instrument.js

@@ -9,7 +9,7 @@
  * `missing-signal` while honesty said `no-signal-on-mutation` for the same absence.
  */
 import { InstrumentationGapKind } from '@reticlehq/core/artifacts';
-/** PascalCase a store name for a `useX.getState` hint (cart → Cart). */
+/** PascalCase a store name for a `useX` hint (cart → Cart). */
 function pascal(name) {
     return 0 === name.length ? name : name[0]?.toUpperCase() + name.slice(1);
 }
@@ -18,7 +18,9 @@ function insertFor(gap) {
         case InstrumentationGapKind.NO_SIGNAL_ON_MUTATION:
             return `reticle.signal('${gap.name}');`;
         case InstrumentationGapKind.NO_STORE_REGISTERED:
-            return `registerStore('${gap.name}', () => use${pascal(gap.name)}.getState());`;
+            // The store itself, so its subscribe is wired too. A `() => useX.getState()` getter is
+            // readable but never reports a change, which is the state this gap is about (#1146).
+            return `registerStore('${gap.name}', use${pascal(gap.name)});`;
         case InstrumentationGapKind.MISSING_TESTID:
             return `data-testid="${gap.name}"`;
     }

package/dist/judgement/runs/artifact/replay-mapping.d.ts

@@ -4,8 +4,8 @@
  * perspective a flow that drifted no longer behaves, so it must not read as green. The actionable
  * "why" is lifted from the replay's decision envelope (or its error) into failureReason.
  */
-import { ReplayStatus, RunFlowStatus, type FlowReplayResult, type RunFlowResult } from '@reticlehq/core';
+import { ReplayStatus, RunFlowStatus, type FlowFile, type FlowReplayResult, type RunFlowResult } from '@reticlehq/core';
 /** OK → PASS; DRIFT/ERROR → FAIL (a healed flow is produced by the heal path, not plain replay). */
 export declare function runFlowStatusOf(status: ReplayStatus): RunFlowStatus;
 /** Map one replay (plus its measured duration) into a RunFlowResult for the artifact's flows[]. */
-export declare function mapReplayToFlowResult(replay: FlowReplayResult, durationMs: number): RunFlowResult;
+export declare function mapReplayToFlowResult(replay: FlowReplayResult, durationMs: number, flow?: FlowFile): RunFlowResult;

package/dist/judgement/runs/artifact/replay-mapping.js

@@ -4,21 +4,52 @@
  * perspective a flow that drifted no longer behaves, so it must not read as green. The actionable
  * "why" is lifted from the replay's decision envelope (or its error) into failureReason.
  */
-import { ReplayStatus, RunFlowStatus, } from '@reticlehq/core';
+import { ReplayStatus, RUN_RECORDING_MAX_BYTES, RUN_STEP_RESULTS_MAX, RUN_TEXT_MAX, RunFlowStatus, } from '@reticlehq/core';
 import { SUCCESS_STEP_TOOL } from '../../../language/flows/flow-success.js';
 /** OK → PASS; DRIFT/ERROR → FAIL (a healed flow is produced by the heal path, not plain replay). */
 export function runFlowStatusOf(status) {
     return status === ReplayStatus.OK ? RunFlowStatus.PASS : RunFlowStatus.FAIL;
 }
+const clip = (text) => text.length > RUN_TEXT_MAX ? `${text.slice(0, RUN_TEXT_MAX - 1)}…` : text;
+/** One step as synced: what it did, where, and whether it held. */
+function stepResultOf(step) {
+    return {
+        step: step.step,
+        anchor: clip(step.anchor),
+        ok: step.ok,
+        ...(step.page === undefined ? {} : { page: step.page }),
+        ...(step.endPage === undefined ? {} : { endPage: step.endPage }),
+        ...(step.consequence === undefined ? {} : { consequence: clip(step.consequence) }),
+        ...(step.error === undefined ? {} : { error: clip(step.error) }),
+        ...(step.drift === undefined ? {} : { drift: step.drift.reasonKind }),
+    };
+}
+/**
+ * The flow as recorded, when it is small enough to travel — what lets a teammate replay this run
+ * from the cloud. Fill values were already redacted when the flow was saved.
+ */
+function recordingOf(flow) {
+    const recording = {
+        ...(flow.startPath === undefined ? {} : { startPath: flow.startPath }),
+        steps: flow.steps,
+    };
+    return Buffer.byteLength(JSON.stringify(recording)) > RUN_RECORDING_MAX_BYTES
+        ? { recordingOmitted: true }
+        : { recording };
+}
 /** Map one replay (plus its measured duration) into a RunFlowResult for the artifact's flows[]. */
-export function mapReplayToFlowResult(replay, durationMs) {
-    const status = runFlowStatusOf(replay.status);
-    const failureReason = status === RunFlowStatus.FAIL
-        ? (replay.decision?.whatChanged ??
-            replay.decision?.summary ??
-            replay.error?.message ??
-            'flow failed')
-        : undefined;
+export function mapReplayToFlowResult(replay, durationMs, flow) {
+    // A replay that could not start returns OK with no steps. Nothing ran, so it is SKIPPED — which
+    // every reader of a run (the verdict, the gate) already refuses to count as a pass.
+    const status = replay.unverifiable === undefined ? runFlowStatusOf(replay.status) : RunFlowStatus.SKIPPED;
+    const failureReason = replay.unverifiable !== undefined
+        ? replay.unverifiable.reason
+        : status === RunFlowStatus.FAIL
+            ? (replay.decision?.whatChanged ??
+                replay.decision?.summary ??
+                replay.error?.message ??
+                'flow failed')
+            : undefined;
     // A flow with a success oracle gets a synthetic 'success' step appended by replay; surface its label
     // as the run's `oracle` so the verdict counts this flow as consequence-backed (→ HIGH confidence),
     // not a bare smoke click. Without this, an oracle-backed pass reads as MEDIUM and undersells itself.
@@ -30,5 +61,9 @@ export function mapReplayToFlowResult(replay, durationMs) {
         durationMs,
         ...(oracle !== undefined ? { oracle } : {}),
         ...(failureReason !== undefined ? { failureReason } : {}),
+        ...(0 === replay.steps.length
+            ? {}
+            : { stepResults: replay.steps.slice(0, RUN_STEP_RESULTS_MAX).map(stepResultOf) }),
+        ...(flow === undefined ? {} : recordingOf(flow)),
     };
 }

package/dist/judgement/runs/verification-sync.d.ts

@@ -1,9 +1,11 @@
-import { type ProjectId, type FlowReplayResult } from '@reticlehq/core';
+import { type ProjectId, type FlowFile, type FlowReplayResult } from '@reticlehq/core';
 import type { ToolDeps } from '../../surface/tools/tool-kit.js';
 /** A replay plus the wall-clock time it took — the shape the verify handler already collects. */
 export interface TimedReplay {
     replay: FlowReplayResult;
     durationMs: number;
+    /** The flow file that was replayed, so the synced run can carry its recording. */
+    flow?: FlowFile;
 }
 /**
  * Persist the suite's run artifact and best-effort mirror it to the cloud. Never throws into the verify

package/dist/judgement/runs/verification-sync.js

@@ -23,7 +23,7 @@ import { rootForProjectId } from '../../memory/project/session-root.js';
 const RETICLE_MCP_AGENT_ID = 'reticle-mcp';
 /** Assemble the ReticleVerificationRun artifact for a verify suite (pure — no IO). */
 function assembleRun(deps, timed, projectId) {
-    const flows = timed.map((t) => mapReplayToFlowResult(t.replay, t.durationMs));
+    const flows = timed.map((t) => mapReplayToFlowResult(t.replay, t.durationMs, t.flow));
     const input = {
         runId: defaultRunId(),
         durationMs: flows.reduce((sum, f) => sum + f.durationMs, 0),

package/dist/language/flows/change/affected.d.ts

@@ -22,3 +22,12 @@ export interface AffectedResult {
  * a repo-relative change matches an absolute stamp and vice-versa.
  */
 export declare function affectedFlows(flows: readonly FlowSources[], changedFiles: readonly string[]): AffectedResult;
+export declare function isInteractiveSource(text: string): boolean;
+/**
+ * Changed interactive components that no saved flow's manifest names.
+ *
+ * `affectedFlows` starts from the flows, so a file no flow ever touched affects nothing — and a gate
+ * built only on it passed a brand-new feature that had never been driven. This starts from the
+ * change instead. `isInteractive` is injected so the decision stays pure; the CLI reads the file.
+ */
+export declare function unflowedFiles(flows: readonly FlowSources[], changedFiles: readonly string[], isInteractive: (file: string) => boolean): string[];

package/dist/language/flows/change/affected.js

@@ -33,3 +33,38 @@ export function affectedFlows(flows, changedFiles) {
     }
     return { affected, unknownProvenance };
 }
+/** A file a source stamper can put on an element — the only files a flow's manifest can ever name. */
+const COMPONENT_FILE = /\.(?:jsx|tsx|vue|svelte|astro)$/;
+/** Same test-file rule the stampers use, so a test is never demanded a flow. */
+const TEST_FILE = /(?:\.(?:test|spec)\.[^./]+$)|(?:^|\/)__tests__\//;
+/**
+ * Something a step could act on: a handler prop (`onClick=`, `@click`, `v-on:`, `on:submit`) or a
+ * native control.
+ *
+ * ponytail: a text heuristic, not a parse. A flow's manifest only names the file of the element a
+ * step ACTED on, so a display-only component can never be attributed and demanding a flow for one
+ * would block forever. A handler passed in from a parent under another name escapes it; upgrade to
+ * recording the source of the element an `expect` matched if that proves common.
+ */
+const INTERACTIVE = /\bon[A-Z]\w*=|@[a-z]+[=.]|\bv-on:|\bon:[a-z]+|<(?:button|input|select|textarea|form|a|summary)[\s>/]/;
+export function isInteractiveSource(text) {
+    return INTERACTIVE.test(text);
+}
+/**
+ * Changed interactive components that no saved flow's manifest names.
+ *
+ * `affectedFlows` starts from the flows, so a file no flow ever touched affects nothing — and a gate
+ * built only on it passed a brand-new feature that had never been driven. This starts from the
+ * change instead. `isInteractive` is injected so the decision stays pure; the CLI reads the file.
+ */
+export function unflowedFiles(flows, changedFiles, isInteractive) {
+    const sources = flows.flatMap((flow) => (flow.sources ?? []).map(normalize));
+    return changedFiles.filter((file) => {
+        const c = normalize(file);
+        if (!COMPONENT_FILE.test(c) || TEST_FILE.test(c))
+            return false;
+        if (sources.some((s) => c === s || c.endsWith(`/${s}`) || s.endsWith(`/${c}`)))
+            return false;
+        return isInteractive(file);
+    });
+}

package/dist/language/flows/change/gate.d.ts

@@ -22,6 +22,16 @@ interface GateInput {
     downgraded?: readonly DowngradedFlow[];
     /** Flows that covered a changed file but no longer exist — coverage deleted rather than satisfied. */
     deleted?: readonly string[];
+    /** Changed interactive components no saved flow touches — a change nothing has driven. */
+    unflowed?: readonly string[];
+    /** Coverage levels below the best they ever reached — something new appeared, nothing covered it. */
+    coverageRegressed?: readonly {
+        level: string;
+        was: number;
+        now: number;
+    }[];
+    /** Changed files the browser loaded and never ran a function of. */
+    unexecuted?: readonly string[];
 }
 interface GateResult {
     /** True when every affected, non-flaky flow has a passing artifact AND nothing was weakened/deleted. */
@@ -34,6 +44,16 @@ interface GateResult {
     downgraded: DowngradedFlow[];
     /** Deleted flows that covered changed files — BLOCKING for the same reason. */
     deleted: string[];
+    /** Changed interactive components no flow covers — BLOCKING: the change was never driven. */
+    unflowed: string[];
+    /** BLOCKING: the app grew something nothing has covered. */
+    coverageRegressed: {
+        level: string;
+        was: number;
+        now: number;
+    }[];
+    /** BLOCKING: changed code that never ran in any drive. */
+    unexecuted: string[];
 }
 export declare function gateDecision(input: GateInput): GateResult;
 export {};

package/dist/language/flows/change/gate.js

@@ -23,11 +23,22 @@ export function gateDecision(input) {
     // trivially gameable, which is the exact failure this gate exists to prevent.
     const downgraded = [...(input.downgraded ?? [])];
     const deleted = [...(input.deleted ?? [])];
+    const unflowed = [...(input.unflowed ?? [])];
+    const coverageRegressed = [...(input.coverageRegressed ?? [])];
+    const unexecuted = [...(input.unexecuted ?? [])];
     return {
-        pass: 0 === uncovered.length && 0 === downgraded.length && 0 === deleted.length,
+        pass: 0 === uncovered.length &&
+            0 === downgraded.length &&
+            0 === deleted.length &&
+            0 === unflowed.length &&
+            0 === coverageRegressed.length &&
+            0 === unexecuted.length,
         uncovered,
         quarantined,
         downgraded,
         deleted,
+        unflowed,
+        coverageRegressed,
+        unexecuted,
     };
 }

package/dist/language/flows/flow-author.d.ts

@@ -0,0 +1,7 @@
+import type { FlowFile } from '@reticlehq/core';
+/**
+ * Who is making a flow right now: the agent that announced itself over MCP, and the person signed in
+ * to Reticle on this machine. A key handed over in the environment names no person, so none is
+ * written — the cloud can still attribute the push by the key that sent it.
+ */
+export declare function flowAuthor(env?: NodeJS.ProcessEnv, home?: string): FlowFile['author'];

package/dist/language/flows/flow-author.js

@@ -0,0 +1,19 @@
+import { homedir } from 'node:os';
+import { mcpClientIdentity } from '../../surface/mcp/peer/client-identity.js';
+import { readAccountState } from '../../memory/cloud/account-state.js';
+/**
+ * Who is making a flow right now: the agent that announced itself over MCP, and the person signed in
+ * to Reticle on this machine. A key handed over in the environment names no person, so none is
+ * written — the cloud can still attribute the push by the key that sent it.
+ */
+export function flowAuthor(env = process.env, home = homedir()) {
+    const agent = mcpClientIdentity().name;
+    const account = readAccountState(home, env);
+    const person = account.signedIn ? account.email : undefined;
+    if (agent === undefined && person === undefined)
+        return undefined;
+    return {
+        ...(agent === undefined ? {} : { agent }),
+        ...(person === undefined ? {} : { person }),
+    };
+}

package/dist/language/flows/flow-expect-grammar.js

@@ -215,7 +215,7 @@ export function parseFlowFileText(text) {
             ok: false,
             code: FlowErrorCode.WRONG_VERSION,
             detail: `this flow file is version ${String(declared)} and this Reticle reads versions ` +
-                `${[...READABLE_FLOW_VERSIONS].join(' and ')}. The file is not damaged, the reader is the ` +
+                `${[...READABLE_FLOW_VERSIONS].join(', ')}. The file is not damaged, the reader is the ` +
                 'wrong one. ' +
                 'Upgrade or downgrade Reticle rather than editing the flow.',
         };

package/dist/language/flows/flow-journey.d.ts

@@ -0,0 +1,54 @@
+import { type FlowFile, type FlowStep, type Predicate } from '@reticlehq/core';
+/** A short, stable identity for a journey's shape: its start page and its steps. */
+export declare function journeyFingerprint(flow: Pick<FlowFile, 'startPath' | 'steps'>): string;
+/**
+ * Fold two copies of one journey into one file.
+ *
+ * Gap-filling, never overwriting: whatever the kept flow already says — its name, its intent, a
+ * step's declared consequence, a quarantine a person wrote — survives, and the other copy only
+ * supplies what is missing. So a merge can add an assertion or an intent and can never remove one.
+ */
+export declare function mergeJourney(kept: FlowFile, other: FlowFile): FlowFile;
+/**
+ * The name a new journey saves under.
+ *
+ * Its readable name when that is free or already this journey's; otherwise the same name with the
+ * fingerprint's head, so two different journeys that share an intent never overwrite each other.
+ */
+export declare function journeyName(base: string, fingerprint: string, taken: ReadonlyMap<string, string>): string;
+/**
+ * What must hold before a journey and what it leaves behind, read from where it started and ended.
+ *
+ * Routes only: the page is the one piece of state every recorded step knows for certain, and a
+ * claim written from a guess about the rest would be a precondition nobody met. Written in the
+ * exact form `canFollow` compares by value, so A-then-B is answerable from the two files alone.
+ */
+export declare function routeClaims(startPath: string | undefined, steps: readonly FlowStep[]): {
+    requires?: Predicate[];
+    ensures?: Predicate[];
+};
+/**
+ * The preconditions only another flow can establish.
+ *
+ * A route claim on the page the flow starts on is not one of them: replay navigates there itself, so
+ * it neither opts the flow out of the reset nor gates the run. That is the claim a saved drive writes
+ * for the map (see routeClaims) — reading it as "starts from leftover state" would stop every
+ * auto-saved flow from ever being reset.
+ */
+export declare function establishedState(flow: FlowFile): readonly Predicate[];
+/**
+ * Is the tab where the flow asked to start? Up to a trailing slash, and up to the query the flow
+ * did not ask about.
+ *
+ * `startPath` is the SPECIFICATION, so it decides what counts. A query it recorded is compared:
+ * `?tab=wrap` and `?tab=summary` are different pages, and a replay that starts on the wrong one
+ * proves nothing about the right one. A query it did NOT record is ignored: the tab carrying
+ * `?next=%2F` on a login page, or the identity params Reticle puts on a leased tab, are not the flow
+ * being elsewhere, and navigating to strip them costs a session for nothing.
+ *
+ * The asymmetry is the whole point and the reason `observed` and `expected` are named rather than
+ * `a` and `b`. Comparing with the query on both sides always re-navigated a query-bearing
+ * `startPath` (#1059, which killed the session mid-flow); comparing with it on neither side reads a
+ * tab on `?tab=summary` as already at `?tab=wrap`.
+ */
+export declare function samePath(observed: string, expected: string): boolean;