@reticlehq/server 2.10.0 → 2.11.0

package/dist/events/predicate-schema.js

@@ -21,6 +21,10 @@ const PREDICATE_ALIASES = {
     // most common thing an agent reaches for here.
     [PredicateKind.ROUTE]: { path: 'pathname', urlContains: 'contains', url: 'contains' },
     [PredicateKind.NET]: { url: 'urlContains' },
+    // `textContains` on a `console` predicate: the reporter who hit the missing matcher reached for
+    // it first, by analogy with `net { urlContains }` — and that parallel is exactly right, since
+    // both mean "this entry must contain this substring". Accepted as an alias for `contains`.
+    [PredicateKind.CONSOLE]: { textContains: 'contains' },
     [PredicateKind.SIGNAL]: { data: 'dataMatches' },
     // `of` on a composite: it reads naturally, several assertion libraries spell it that way, and it has
     // no other meaning here. Observed twice in one drive on a real app, and each rejection cost a round
@@ -246,6 +250,7 @@ function predicateUnion() {
             .object({
             kind: z.literal(PredicateKind.CONSOLE),
             level: z.string().optional(),
+            contains: z.string().min(1).optional(),
             absent: z.boolean().optional(),
             since: z.number().optional(),
         })
@@ -307,3 +312,53 @@ export function predicateFieldsFor(kind) {
     }
     return [];
 }
+/** Peel optional/nullable/default/effects wrappers off a field to reach the schema underneath. */
+function unwrapSchema(schema) {
+    let current = schema;
+    for (;;) {
+        if (current instanceof z.ZodOptional ||
+            current instanceof z.ZodNullable ||
+            current instanceof z.ZodDefault) {
+            current = current._def.innerType;
+            continue;
+        }
+        if (current instanceof z.ZodEffects) {
+            current = current._def.schema;
+            continue;
+        }
+        return current;
+    }
+}
+/**
+ * One level into the fields that are themselves objects — `{ query: ['by', 'value', ...] }`.
+ *
+ * Naming the top-level fields alone leaves `element` unguessable: `query` is an object with its own
+ * required shape, and a plain CSS string works in `reticle_snapshot.scope` and `reticle_query.scope`,
+ * so assuming it works here is the natural guess. The rejection is the only place that inconsistency
+ * can be explained.
+ *
+ * One level only. Derived from the schema for the same reason `predicateFieldsFor` is: a stale field
+ * list is worse than none, because the agent trusts it and retries into the same wall.
+ */
+export function predicateNestedFieldsFor(kind) {
+    for (const option of predicateUnion().options) {
+        const literal = option.shape['kind'];
+        if (!(literal instanceof z.ZodLiteral) || literal.value !== kind)
+            continue;
+        const nested = {};
+        for (const [field, schema] of Object.entries(option.shape)) {
+            if ('kind' === field)
+                continue;
+            const inner = unwrapSchema(schema);
+            // `instanceof z.ZodObject` narrows to ZodObject<any>, whose `.shape` is `any`. Name the shape
+            // type so the keys are read off something typed rather than laundering an `any` through
+            // Object.keys.
+            if (inner instanceof z.ZodObject) {
+                const shape = inner.shape;
+                nested[field] = Object.keys(shape);
+            }
+        }
+        return nested;
+    }
+    return {};
+}

package/dist/flows/flow-tools.js

@@ -14,6 +14,7 @@ import { resolveProjectCloud } from '../cloud/cloud-config.js';
 import { buildSuiteVerdict } from './decision.js';
 import { classifyFlowAssertions } from './flow-classify.js';
 import { isValidFlowName, flowPath } from '../project/reticle-dir.js';
+import { FlowStore } from './flows.js';
 import { replayNamedFlow, flowErrorMessage, latestRecordedFlow, sessionProjectId, } from './flow-replay-run.js';
 import { persistAndSyncVerificationRun } from '../runs/verification-sync.js';
 import { runServerVerify } from './server-verify.js';
@@ -67,6 +68,24 @@ export function leaseFailureReplay(name, error) {
 }
 /** Stand-in path for a flow whose name fails the path-segment guard — never a real join. */
 const INVALID_FLOW_NAME_PATH = '(invalid flow name — not a usable path)';
+/**
+ * The flow store a SESSION's artifacts belong in, and the root it resolved to.
+ *
+ * `deps.flows` is bound to the daemon's own root at construction, which is right only when the
+ * daemon happens to have been started in the project it is driving. When a resolver is wired and it
+ * names a different project, the write has to go there instead — so the store is rebound for this
+ * call. Rebinding is cheap: a FlowStore is a filesystem port, a root and a clock.
+ *
+ * Returns `deps.flows` unchanged when nothing is wired or the roots already agree, so the common
+ * case allocates nothing and behaves exactly as before.
+ */
+function flowsForSession(deps, projectId) {
+    const resolved = deps.artifactRootFor?.(projectId);
+    if (resolved === undefined || resolved.root === deps.reticleRoot) {
+        return { flows: deps.flows, root: deps.reticleRoot };
+    }
+    return { flows: new FlowStore(deps.fs, resolved.root, { now: deps.now }), root: resolved.root };
+}
 export const FLOW_TOOLS = [
     {
         name: ReticleTool.FLOW_SAVE,
@@ -132,16 +151,26 @@ export const FLOW_TOOLS = [
             const emptyRefusal = emptyFlowRefusal(program.steps.length, name);
             if (emptyRefusal !== undefined)
                 return Promise.resolve(emptyRefusal);
-            return deps.flows.save(program, annotations, projectId).then(async (res) => {
+            const { flows, root } = flowsForSession(deps, projectId);
+            return flows.save(program, annotations, projectId).then(async (res) => {
                 if (!res.ok)
                     return { error: flowErrorMessage(res.code), code: res.code };
                 deps.annotations.clear(name);
                 // Grade the saved flow's assertions so the agent learns immediately if it just saved a flow
                 // that asserts nothing observable (passes even when the feature is broken).
-                const loaded = await deps.flows.load(res.value.name, projectId);
+                const loaded = await flows.load(res.value.name, projectId);
+                // The absolute path, always. A save that reports success and not WHERE cost a reporter a
+                // `find` across their disk to discover it had landed in an unrelated repo. The name came
+                // back from a save that succeeded, so the guard is a type narrowing rather than a doubt.
+                const saved = res.value.name;
+                const path = isValidFlowName(saved) ? flowPath(root, saved, projectId) : undefined;
                 return loaded.ok
-                    ? { ...res.value, assertions: classifyFlowAssertions(loaded.value) }
-                    : res.value;
+                    ? {
+                        ...res.value,
+                        ...(path === undefined ? {} : { path }),
+                        assertions: classifyFlowAssertions(loaded.value),
+                    }
+                    : { ...res.value, ...(path === undefined ? {} : { path }) };
             });
         },
     },

package/dist/flows/predicate-to-expect.js

@@ -25,6 +25,14 @@ export function predicateToExpect(predicate) {
             return 0 === Object.keys(net).length ? undefined : { net };
         }
         case PredicateKind.CONSOLE: {
+            // `contains` has no representation in FlowExpect.console (core keeps `level` and `absent`
+            // and nothing else). Copying the rest through anyway would record an assertion the agent
+            // never made: {console, level:'warn', contains:'no-op', absent:true} would save "no warn
+            // entries at all", a false red on any unrelated warning, and in the presence direction it
+            // saves a strictly weaker claim than the one chosen. This file's own rule applies: record
+            // nothing rather than something different, so the flow stays assertion-free there instead.
+            if (predicate.contains !== undefined)
+                return undefined;
             const console_ = {};
             if (predicate.level !== undefined)
                 console_.level = predicate.level;

package/dist/flows/verify-change-tools.js

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { sessionRoot } from '../project/session-root.js';
 import { verdictForSuite } from './verify-change-verdict.js';
 import { attributedFailures } from './attributed-failure.js';
 import { Verified } from '@reticlehq/core';
@@ -62,7 +63,10 @@ export const VERIFY_CHANGE_TOOLS = [
                 : [];
             const since = asString(args['since']);
             const changedFiles = await resolveChangedFiles(files, since);
-            const flows = await loadNamedFlows(deps.fs, deps.reticleRoot);
+            // Same root flow_save wrote to. A read that resolved differently would report "no flows
+            // covered this change" over flows that exist, which reads as a clean result rather than
+            // an error, so the disagreement would be invisible.
+            const flows = await loadNamedFlows(deps.fs, sessionRoot(deps, asString(args['sessionId'])));
             const { affected, unknownProvenance } = affectedSavedFlows(flows, changedFiles);
             if (0 === changedFiles.length) {
                 return {

package/dist/honesty/blind-spots.d.ts

@@ -84,3 +84,12 @@ export declare function blindSpotsFromState(state: Readonly<Record<string, numbe
 export declare function droppedByTransport(events: readonly ReticleEvent[]): number;
 /** The impeaching note for a transport gap, or undefined when the window was intact. */
 export declare function transportGapNote(events: readonly ReticleEvent[]): string | undefined;
+/**
+ * Is the state channel dark?
+ *
+ * Nothing subscribed means NO state change is observed, so an empty `stateDiffs` is a statement
+ * about Reticle rather than about the app. Derived here, once, because two callers now need it —
+ * the act path's causal summary and the instrumentation-gap surface — and a second spelling of this
+ * predicate would eventually disagree with the first about what "unwatched" means.
+ */
+export declare function isStateUnwatched(spots: readonly BlindSpot[]): boolean;

package/dist/honesty/blind-spots.js

@@ -45,10 +45,12 @@ const LABEL = {
     // nothing here can support. Names the one-line fix, because the reader is the one who can apply it.
     [BlindSpotKind.UNWATCHED_STATE]: () => 'no subscribable store is registered, so NO state change is observed — an empty stateDiffs here means unwatched, not unchanged (register the store itself in your reticle-dev module: registerStore(name, store), not a getter)',
     [BlindSpotKind.WRAPPED_NETWORK]: () => 'fetch was already wrapped before Reticle, so recorded requests may differ from what was sent',
-    // A fact about the app's wiring, not a tally. Says what the empty network view MEANS, because an
-    // empty one here is indistinguishable from "this app made no backend calls" — and that reading is
-    // the false green: every IPC call went unseen and every `assert { net }` over them is vacuous.
-    [BlindSpotKind.UNOBSERVED_IPC]: () => "this Electron renderer has no Reticle preload, so NO ipcRenderer.invoke is observed — an empty network view here means unseen, not none (add require('@reticlehq/electron/preload') to your preload)",
+    // A fact about the app's wiring, not a tally. Says what a network view WITHOUT ipc:// records
+    // MEANS, because that state here is indistinguishable from "this app made no backend calls" —
+    // and that reading is the false green: every IPC call went unseen and every `assert { net }` over
+    // them is vacuous. Document-initiated loads ARE seen since subresource observation (#447), so
+    // the note names the missing half instead of claiming the whole view is blind.
+    [BlindSpotKind.UNOBSERVED_IPC]: () => "this Electron renderer has no Reticle preload, so NO ipcRenderer.invoke is observed; document-initiated loads may still appear, so a view with no ipc:// records means unseen IPC, not none (add require('@reticlehq/electron/preload') to your preload)",
 };
 /**
  * Blind spots that IMPEACH the capture, as opposed to bounding what it covers.
@@ -150,3 +152,14 @@ export function transportGapNote(events) {
         ? undefined
         : `the browser dropped ${String(dropped)} event(s) in this window (transport queue overflow), so events that would have contradicted this may never have arrived`;
 }
+/**
+ * Is the state channel dark?
+ *
+ * Nothing subscribed means NO state change is observed, so an empty `stateDiffs` is a statement
+ * about Reticle rather than about the app. Derived here, once, because two callers now need it —
+ * the act path's causal summary and the instrumentation-gap surface — and a second spelling of this
+ * predicate would eventually disagree with the first about what "unwatched" means.
+ */
+export function isStateUnwatched(spots) {
+    return spots.some((spot) => spot.kind === BlindSpotKind.UNWATCHED_STATE && spot.count > 0);
+}

package/dist/honesty/gap-ledger.d.ts

@@ -0,0 +1,52 @@
+import { type InstrumentationGap } from '@reticlehq/core';
+/**
+ * What this session still cannot see, accumulated across its verdicts.
+ *
+ * A gap reported on one verdict and then forgotten is a note. A gap that is still standing when the
+ * agent asks "am I done?" is a piece of work — and that difference is the entire discipline
+ * mechanism, because an agent finishing a task is the one moment it will act on a cost it can close.
+ *
+ * ## Why the LAST verdict decides, not the whole history
+ *
+ * The honest question is "is this app still unverifiable in this way", not "was it ever". An agent
+ * that hits a gap, adds the build plugin and re-verifies has CLOSED it — the later verdict simply
+ * stops emitting that kind — and a ledger that still reported it would punish exactly the behaviour
+ * this exists to cause. Nobody instruments an app twice for a tool that never notices the first time.
+ *
+ * So `open()` reflects the most recent verdict, and `everSeen` is kept separately for the summary,
+ * where "you hit this and fixed it" is worth saying and is not a reason to withhold done.
+ */
+export declare class GapLedger {
+    #private;
+    /**
+     * Record what the verdict just reported. An empty list is a real observation — it is how a gap
+     * gets closed — so it must not be ignored as "nothing to record".
+     */
+    note(gaps: readonly InstrumentationGap[]): void;
+    /** Gaps the most recent verdict still reported. The ones that are work right now. */
+    open(): readonly InstrumentationGap[];
+    /** Every kind seen in this session, including ones since closed. */
+    get everSeen(): readonly string[];
+    /**
+     * Did this session leave the app less verifiable than it could be?
+     *
+     * The one question a "have I finished" call needs answered, and the one a session summary turns
+     * into `unproven` rather than `verified`.
+     */
+    get hasOpen(): boolean;
+}
+/**
+ * Record a verdict's gaps against the session that produced it.
+ *
+ * Tolerates a session with no ledger, and that is a statement about the seam rather than a hedge:
+ * `Session` is satisfied structurally, and dozens of specs — plus any consumer embedding this engine
+ * — build one as an object literal rather than through the constructor. Such a session is a real
+ * caller, it simply keeps no ledger, and recording is a side effect that must never be the reason a
+ * verdict fails to return.
+ *
+ * One helper rather than an optional-chain at each call site: the tolerance is a decision, and a
+ * decision spelled `?.` in two places is one nobody can find later.
+ */
+export declare function noteSessionGaps(session: {
+    gaps?: GapLedger;
+}, gaps: readonly InstrumentationGap[]): void;

package/dist/honesty/gap-ledger.js

@@ -0,0 +1,63 @@
+import { dedupeGaps } from '@reticlehq/core';
+/**
+ * What this session still cannot see, accumulated across its verdicts.
+ *
+ * A gap reported on one verdict and then forgotten is a note. A gap that is still standing when the
+ * agent asks "am I done?" is a piece of work — and that difference is the entire discipline
+ * mechanism, because an agent finishing a task is the one moment it will act on a cost it can close.
+ *
+ * ## Why the LAST verdict decides, not the whole history
+ *
+ * The honest question is "is this app still unverifiable in this way", not "was it ever". An agent
+ * that hits a gap, adds the build plugin and re-verifies has CLOSED it — the later verdict simply
+ * stops emitting that kind — and a ledger that still reported it would punish exactly the behaviour
+ * this exists to cause. Nobody instruments an app twice for a tool that never notices the first time.
+ *
+ * So `open()` reflects the most recent verdict, and `everSeen` is kept separately for the summary,
+ * where "you hit this and fixed it" is worth saying and is not a reason to withhold done.
+ */
+export class GapLedger {
+    #open = [];
+    #everSeen = new Set();
+    /**
+     * Record what the verdict just reported. An empty list is a real observation — it is how a gap
+     * gets closed — so it must not be ignored as "nothing to record".
+     */
+    note(gaps) {
+        this.#open = dedupeGaps(gaps);
+        for (const gap of gaps)
+            this.#everSeen.add(gap.kind);
+    }
+    /** Gaps the most recent verdict still reported. The ones that are work right now. */
+    open() {
+        return this.#open;
+    }
+    /** Every kind seen in this session, including ones since closed. */
+    get everSeen() {
+        return [...this.#everSeen];
+    }
+    /**
+     * Did this session leave the app less verifiable than it could be?
+     *
+     * The one question a "have I finished" call needs answered, and the one a session summary turns
+     * into `unproven` rather than `verified`.
+     */
+    get hasOpen() {
+        return this.#open.length > 0;
+    }
+}
+/**
+ * Record a verdict's gaps against the session that produced it.
+ *
+ * Tolerates a session with no ledger, and that is a statement about the seam rather than a hedge:
+ * `Session` is satisfied structurally, and dozens of specs — plus any consumer embedding this engine
+ * — build one as an object literal rather than through the constructor. Such a session is a real
+ * caller, it simply keeps no ledger, and recording is a side effect that must never be the reason a
+ * verdict fails to return.
+ *
+ * One helper rather than an optional-chain at each call site: the tolerance is a decision, and a
+ * decision spelled `?.` in two places is one nobody can find later.
+ */
+export function noteSessionGaps(session, gaps) {
+    session.gaps?.note(gaps);
+}

package/dist/honesty/instrumentation-gaps.d.ts

@@ -0,0 +1,55 @@
+import { type InstrumentationGap } from '@reticlehq/core';
+/**
+ * The gaps ONE action revealed, derived from facts the act path already holds.
+ *
+ * Pure, and deliberately fed by primitives rather than by the action result: every fact below is
+ * already computed for other reasons — `actedSource` for the red-verdict file:line, `stateUnwatched`
+ * because an empty `stateDiffs` would otherwise read as "the app changed nothing", the signal count
+ * and route movement for the causal summary. Nothing here costs a new observation. The gap surface
+ * is a second reading of evidence Reticle was already collecting and then discarding.
+ *
+ * ## Each kind carries its OWN gate
+ *
+ * The rule is that a gap fires only when the verdict came back weaker because of it — and "weaker"
+ * is different per kind, so a single global flag would be a lie in both directions:
+ *
+ *  - a missing source mapping costs nothing on a PASS. The act path already says so in as many
+ *    words: on green nobody needs the file:line and it is noise. It costs a great deal on a red,
+ *    where it is the first thing the agent wants;
+ *  - a missing store costs nothing unless the caller ASKED about state;
+ *  - a silent mutation costs nothing if the app proved the outcome some other way.
+ *
+ * Encoding the gates per kind is what keeps this from degenerating into a linter that fires on every
+ * uninstrumented control on the page. That surface would be ignored within a day, and it would take
+ * the true positives with it.
+ */
+export interface ActionInstrumentationFacts {
+    /** Did the verdict pass? Several gates turn on this, in different directions. */
+    pass: boolean;
+    /** True when the outcome was positively PROVED rather than inferred. */
+    proved?: boolean;
+    /**
+     * Does Reticle know a `file:line` for what this verdict is about?
+     *
+     * A boolean rather than the source itself, deliberately: the act path holds a `{file, line}` and
+     * the assert path holds a formatted string it remembered from the last act. The gap does not care
+     * which — only whether the agent can be pointed at code — and taking the shape would make one of
+     * the two callers convert for no reason.
+     */
+    sourceKnown: boolean;
+    /** The ref that was driven, for the report. */
+    ref?: string | undefined;
+    /** Did the caller's predicate ask about registered state? */
+    stateAsked: boolean;
+    /** True when the session has no store registered to read. */
+    stateUnwatched: boolean;
+    /** Did the DOM move in this action's window? */
+    domMutated: boolean;
+    /** How many app signals fired in the window. */
+    signalsFired: number;
+    /** Did the route change in this action's window? */
+    routeChanged: boolean;
+    /** Did anything signal that route change? */
+    routeSignalFired: boolean;
+}
+export declare function gapsForAction(facts: ActionInstrumentationFacts): InstrumentationGap[];

package/dist/honesty/instrumentation-gaps.js

@@ -0,0 +1,21 @@
+import { InstrumentationGapKind, dedupeGaps, instrumentationGap, } from '@reticlehq/core';
+export function gapsForAction(facts) {
+    const gaps = [];
+    // A red verdict names the control and cannot name the line that renders it. That is the round trip
+    // the agent is about to spend, and the one a build plugin removes permanently.
+    if (!facts.pass && !facts.sourceKnown) {
+        gaps.push(instrumentationGap(InstrumentationGapKind.NO_SOURCE_MAPPING, 'the control that was driven carries no source mapping', 'this verdict can name the control but not the file and line that render it, so finding the code is a separate search', { ...(facts.ref === undefined ? {} : { ref: facts.ref }) }));
+    }
+    // Asked about state, and there is no state channel to answer from.
+    if (facts.stateAsked && facts.stateUnwatched) {
+        gaps.push(instrumentationGap(InstrumentationGapKind.NO_STORE_REGISTERED, 'no store is registered, and this assertion was about state', 'the assertion could not be answered from the deterministic channel and had to fall back to what the DOM happens to show'));
+    }
+    // The app moved and said nothing, and Reticle could not prove the outcome another way.
+    if (facts.domMutated && 0 === facts.signalsFired && true !== facts.proved) {
+        gaps.push(instrumentationGap(InstrumentationGapKind.NO_SIGNAL_ON_MUTATION, 'the DOM changed and no signal fired for it', 'the outcome had to be inferred from the DOM instead of read from the app asserting its own success, which is the strongest evidence available', { ...(facts.ref === undefined ? {} : { ref: facts.ref }) }));
+    }
+    if (facts.routeChanged && !facts.routeSignalFired) {
+        gaps.push(instrumentationGap(InstrumentationGapKind.NO_ROUTE_SIGNAL, 'the route changed and nothing signalled it', 'route consequences cannot be asserted on this app, so a navigation can only be checked by what rendered afterwards'));
+    }
+    return dedupeGaps(gaps);
+}

package/dist/honesty/observability.d.ts

@@ -0,0 +1,37 @@
+import type { InstrumentationGap } from '@reticlehq/core';
+/**
+ * Of the controls this session drove, how many could Reticle fully observe?
+ *
+ * The first honest denominator this product has ever had. `reticle_verify{action:"coverage"}`
+ * already answers "which controls did you not drive"; this answers the question underneath it —
+ * *of the ones you did drive, how many could the app actually answer for?* A high untouched-count is
+ * work remaining for the agent. A low observability is work remaining in the APP, and no amount of
+ * driving closes it.
+ *
+ * ## Two things it deliberately refuses to do
+ *
+ * **It does not report a percentage for an empty run.** 0/0 rendered as 100% is the most flattering
+ * possible reading of no evidence at all, and a coverage number that starts perfect is one nobody
+ * believes the first time it drops.
+ *
+ * **It does not count app-level gaps against a control.** An unregistered store or an unsignalled
+ * route is missing from the application, not from a button. Attributing it to whichever control
+ * happened to be driven would put the number on the wrong thing and make it move for reasons the
+ * agent cannot act on. Those gaps are reported alongside, not divided into.
+ */
+export interface Observability {
+    /** Distinct controls driven this session. */
+    driven: number;
+    /** How many of them Reticle could fully observe. */
+    observable: number;
+    /** Rounded percentage. OMITTED when nothing was driven — see above. */
+    percent?: number;
+}
+export declare function observabilityOf(drivenRefs: Iterable<string>, gaps: readonly InstrumentationGap[]): Observability;
+export interface CoverageRegression {
+    was: number;
+    now: number;
+}
+export declare function coverageRegressed(best: {
+    percent: number;
+} | undefined, current: Observability): CoverageRegression | undefined;

package/dist/honesty/observability.js

@@ -0,0 +1,40 @@
+export function observabilityOf(
+// Iterable, not an array: the session holds these as a Set, and making the caller spread it would
+// be a conversion that exists only to satisfy a signature.
+drivenRefs, gaps) {
+    const driven = new Set(drivenRefs);
+    const impaired = new Set();
+    for (const gap of gaps) {
+        // App-level gaps carry no ref, and a gap on a control this session never drove is about some
+        // earlier route — neither belongs in a ratio over what WAS driven.
+        if (gap.ref !== undefined && driven.has(gap.ref))
+            impaired.add(gap.ref);
+    }
+    const observable = driven.size - impaired.size;
+    if (0 === driven.size)
+        return { driven: 0, observable: 0 };
+    return { driven: driven.size, observable, percent: Math.round((observable / driven.size) * 100) };
+}
+/**
+ * The floor under the number, shipped with it rather than after it.
+ *
+ * A coverage figure with no downgrade check is a figure that gets gamed, and we would be the ones
+ * teaching agents to game it: the cheapest way to stop a gap firing is to stop asserting the thing
+ * that revealed it. The same reasoning already runs for flow assertions in `assertion-tiers-store`,
+ * where a flow that passes more weakly than it used to is a finding rather than a pass.
+ *
+ * Returns undefined — not a false — when there is nothing honest to compare. A first run has no
+ * best to fall from, and a run that drove almost nothing is evidence of a short session rather than
+ * of a regression.
+ */
+/** Below this, a run is too small for its ratio to mean anything. */
+const MIN_DRIVEN_TO_COMPARE = 3;
+export function coverageRegressed(best, current) {
+    if (best === undefined)
+        return undefined;
+    if (current.percent === undefined)
+        return undefined;
+    if (current.driven < MIN_DRIVEN_TO_COMPARE)
+        return undefined;
+    return current.percent < best.percent ? { was: best.percent, now: current.percent } : undefined;
+}

package/dist/index.d.ts

@@ -151,7 +151,6 @@ export interface RunningServer {
     close: () => Promise<void>;
 }
 export { resolveBridgeSecurity } from './bridge/bridge-security.js';
-/** Start the Reticle bridge (browser WS endpoint) and, by default, the MCP stdio server. */
 export declare function start(options?: StartOptions): Promise<RunningServer>;
 /**
  * Start the Reticle bridge in daemon mode: a single HTTP server handles both the WebSocket

package/dist/index.js

@@ -1,4 +1,9 @@
 import { join } from 'node:path';
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { PROJECT_REGISTRY_FILE, emptyProjectRegistry, parseProjectRegistry } from '@reticlehq/core';
+import { discoverProjectConfigs } from './cli/config-discovery.js';
+import { projectCandidatesFrom, resolveArtifactRoot, } from './project/artifact-root.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { AGENT_STOPPED_NOTICE, RETICLE_DEFAULT_PORT, ReticleCommand, ReticleDir, ReticleEnv, LOOPBACK_HOST, ReplayStatus, EventType, } from '@reticlehq/core';
 import { originOf } from './session/session-manager.js';
@@ -251,6 +256,41 @@ async function resolveRealInput(options, onNavigateError, onNetworkDetail) {
     return {};
 }
 /** Start the Reticle bridge (browser WS endpoint) and, by default, the MCP stdio server. */
+/**
+ * Resolve a session's artifact root, from everything this machine knows about where projects live.
+ *
+ * Built once per daemon and closed over by every tool call. The two sources are read lazily and
+ * cheaply on each call rather than snapshotted at startup: `init` can run in another terminal while
+ * this daemon is up, and a resolution that used a startup snapshot would keep answering with a map
+ * from before the project the agent is now driving existed.
+ */
+function artifactRootResolver(daemonRoot) {
+    return (projectId) => {
+        let registry = emptyProjectRegistry();
+        try {
+            const path = join(homedir(), ReticleDir.ROOT, PROJECT_REGISTRY_FILE);
+            registry = existsSync(path)
+                ? parseProjectRegistry(JSON.parse(readFileSync(path, 'utf8')))
+                : registry;
+        }
+        catch {
+            // A cache that cannot be read is an empty cache, never an error: the daemon still resolves
+            // through discovery, and falls back to its own root exactly as it did before this existed.
+        }
+        let discovery = { found: [], searched: [] };
+        try {
+            discovery = discoverProjectConfigs(process.cwd());
+        }
+        catch {
+            // Same reasoning: a diagnostic search that throws must not take a tool call with it.
+        }
+        return resolveArtifactRoot({
+            projectId,
+            candidates: projectCandidatesFrom(discovery, registry),
+            daemonRoot,
+        });
+    };
+}
 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
@@ -302,6 +342,7 @@ export async function start(options = {}) {
             project,
             fs,
             reticleRoot,
+            artifactRootFor: artifactRootResolver(reticleRoot),
             now,
             bridgePort: port,
             browserProbe: probeChromium,

package/dist/init/node-io.js

@@ -52,6 +52,9 @@ export function buildNodeIo(cwd) {
         homeDir() {
             return homedir();
         },
+        cwd() {
+            return cwd;
+        },
         rootFiles() {
             return readdirSync(cwd).filter((name) => {
                 try {

package/dist/init/run.d.ts

@@ -3,6 +3,8 @@
  * plan (pure), optionally write the apply-steps, and print a human-readable report. All filesystem
  * access goes through `InitIo` so the orchestration is unit-testable with an in-memory IO.
  */
+import { Framework } from './detect.js';
+import { StepStatus } from './plan.js';
 import type { InitOutcome } from '@reticlehq/core';
 /**
  * Resolve the lockfiles set used to pick the package manager. A lockfile in the project root wins;
@@ -56,6 +58,8 @@ export interface InitIo {
     exists(relPath: string): boolean;
     /** The user's home directory (for global agent config like ~/.cursor/mcp.json). */
     homeDir(): string;
+    /** Absolute path of the directory `init` is running in — the project's own root. */
+    cwd(): string;
     /** Basenames present in the project root. */
     rootFiles(): readonly string[];
     /** Subdirectory names inside a project-relative directory; empty when it isn't one. */
@@ -99,4 +103,18 @@ export declare function findWorkspaceApps(io: Pick<InitIo, 'exists' | 'readFile'
  * the workspace redirect is kept from asking twice.
  */
 export declare const FEEDBACK_HINT: string;
+/**
+ * The last two lines a user reads, and the order matters.
+ *
+ * This used to say only "Restart <dev server>, then ask your agent: List Reticle sessions" — and
+ * asking the agent was the one thing that could not work yet. `init` registers the MCP server, but
+ * an agent client reads its tool list when it STARTS and never re-reads it, so the session that
+ * just ran `init` has no `reticle_*` tools however clean the install was. The user follows the
+ * instruction, the agent answers "unknown tool", and the obvious conclusion is that the install
+ * failed.
+ *
+ * So the reload is named FIRST, before the sentence that depends on it. Omitted entirely when this
+ * run did not register MCP (`--no-mcp`), where it would be advice about something we did not do.
+ */
+export declare function restartHint(framework: Framework, mcpStatus: StepStatus | undefined): string;
 export declare function runInit(options: InitOptions, io: InitIo): InitResult;