@reticlehq/server 3.7.0 → 3.8.1

package/dist/portal/session/no-session-next-action.js

@@ -67,7 +67,17 @@ function reopenableUrl(raw) {
  * bin on PATH, so a bare `reticle init` fails with "command not found" exactly where it is handed out.
  */
 const CLI = 'npx @reticlehq/server';
-const INIT_COMMAND = `${CLI} init`;
+export const INIT_COMMAND = `${CLI} init`;
+/**
+ * The consent question for wiring, in one wording for every place that offers `init`: the
+ * handshake, the first session call, every next action and the plugin hook. `init` changes the user's files, so the
+ * agent asks first. The lease changes nothing, so it needs no question.
+ */
+export function wiringConsent(init = INIT_COMMAND) {
+    return ('`init` changes files: it adds a dev-only SDK to package.json and the lockfile, edits the ' +
+        'build config and starts the dev server. Ask the user before you wire the app. If they ' +
+        `agree, run \`${init}\` in the app's folder. If they decline, do not ask again.`);
+}
 const OPEN_COMMAND = `${CLI} open`;
 const LOCALHOST = 'http://localhost';
 /**
@@ -77,13 +87,26 @@ const LOCALHOST = 'http://localhost';
 const ZERO_INSTALL_SEES = 'the lease supplies the SDK itself: DOM, network, console and routes, but no component state ' +
     'or source file:line until the app is wired';
 /** The zero-install call, with the URL only when it can be named without guessing. */
-function zeroInstallLease(url) {
-    return `reticle_lease {action:"acquire", url:"${url ?? "<the app's URL>"}"}`;
+export function zeroInstallLease(url) {
+    // Through reticle_run: reticle_lease is not on the default surface, and reticle_run is on every one (#1547).
+    return `reticle_run { tool: "reticle_lease", args: { action: "acquire", url: "${url ?? "<the app's URL>"}" } }`;
 }
 /** Nothing here says this project was ever wired: no config, no recorded connection, no session. */
 function neverWired(facts) {
     return !facts.initialized && true !== facts.previouslyConnected && !facts.everConnected;
 }
+/**
+ * The start advice's first claim when no port is this project's. A scan that heard a page it could
+ * not tie to this project says so, because "nothing is listening" is then false.
+ */
+function notThisProject(others) {
+    if (others === undefined || 0 === others.length) {
+        return 'nothing is listening on the ports Reticle scans, so the app is probably not running — ';
+    }
+    const named = others.map((port) => `:${String(port)}`).join(', ');
+    return (`${named} serves a page, but its process does not run in this project's folder, so this app ` +
+        `is probably not running — if one of them IS this app, open it instead of starting a second one, `);
+}
 export function nextActionFor(facts) {
     // FIRST, above every other cause, because it is the only one supported by positive evidence about
     // a daemon rather than by an absence. This project's own connection record names a live daemon
@@ -149,7 +172,8 @@ export function nextActionFor(facts) {
                 (departedTo === undefined || '' === departedTo
                     ? 'the tab was closed, reloaded, or the lease aged out. '
                     : `the page navigated away to ${redactUrl(departedTo)}. `) +
-                'Reopen the app, or take one you own with reticle_lease {action:"acquire", url}.' +
+                'Reopen the app, or take one you own with ' +
+                'reticle_run { tool: "reticle_lease", args: { action: "acquire", url } }.' +
                 bound,
         };
     }
@@ -163,8 +187,8 @@ export function nextActionFor(facts) {
         const projectIds = configsElsewhere.flatMap((config) => config.projectId === undefined ? [] : [config.projectId]);
         const leaseAlternative = 0 === projectIds.length
             ? ''
-            : ' Alternatively, acquire the app URL explicitly with reticle_lease ' +
-                '{action:"acquire", url, projectId} using the matching projectId above.';
+            : ' Alternatively, acquire the app URL explicitly with reticle_run { tool: "reticle_lease", ' +
+                'args: { action: "acquire", url, projectId } } using the matching projectId above.';
         return {
             action: NoSessionAction.OPEN_APP,
             reason: `a \`.reticle.json\` was found outside this daemon's directory: ${named}. This is a ` +
@@ -215,8 +239,8 @@ export function nextActionFor(facts) {
                 'This daemon was started outside the project (an IDE that registers the MCP server ' +
                 'globally starts it in `/` or your home directory), so it has no `.reticle.json` to match ' +
                 'the page against. Do NOT run `reticle init`: the config it would write is already correct ' +
-                'somewhere else. Take a context you own instead with reticle_lease {action:"acquire", url, ' +
-                "projectId}, or restart the daemon from the app's own directory.",
+                'somewhere else. Take a context you own instead with reticle_run { tool: "reticle_lease", ' +
+                'args: { action: "acquire", url, projectId } }, or restart the daemon from the app\'s own directory.',
         };
     }
     if (0 === facts.listening.length || departedPortIsGone) {
@@ -229,7 +253,7 @@ export function nextActionFor(facts) {
             : ` The session that was on ${redactUrl(stopped.url)} is gone and nothing listens there now.`;
         const notRunning = departedPortIsGone
             ? "nothing answers on the port this project's app was last on, so the app is probably not running — "
-            : 'nothing is listening on the ports Reticle scans, so the app is probably not running — ';
+            : notThisProject(facts.otherListeners);
         if (dev === undefined) {
             if (facts.exists !== undefined && !facts.exists('package.json')) {
                 const ecosystem = detectNonJsEcosystem(facts.exists);
@@ -279,12 +303,12 @@ export function nextActionFor(facts) {
                 (undefined === dev.script ? 'launcher' : `\`${dev.script}\` script`) +
                 (dev.directory === undefined ? '' : `, in \`${dev.directory}\``) +
                 ` — run it in the ` +
-                'background, tell the human it is running, then call reticle_sessions again.' +
+                'background, tell the human it is running, then call reticle_session { action: "list" } again.' +
                 stoppedNote +
                 (neverWired(facts)
                     ? ` Once it is up, ${zeroInstallLease(dev.port === undefined ? undefined : `${LOCALHOST}:${String(dev.port)}`)} ` +
                         `gets a verdict with nothing installed (${ZERO_INSTALL_SEES}); ` +
-                        `\`${facts.init ?? INIT_COMMAND}\` wires it for good — then restart the dev server and reload.`
+                        `To wire it for good: ${wiringConsent(facts.init ?? INIT_COMMAND)} Then restart the dev server and reload.`
                     : ''),
         };
     }
@@ -301,9 +325,9 @@ export function nextActionFor(facts) {
             reason: `something is listening (${ports}) but no \`.reticle.json\` was found, so the app may ` +
                 'carry no Reticle SDK. For a verdict NOW with nothing installed: ' +
                 `${zeroInstallLease(target === undefined ? undefined : `${LOCALHOST}:${String(target)}`)} — ` +
-                `${ZERO_INSTALL_SEES}. To wire it for good, run this command yourself (it runs in the ` +
-                "APP's own folder, not where this daemon stands), then restart the dev server and reload " +
-                'the page.',
+                `${ZERO_INSTALL_SEES}. To wire it for good: ${wiringConsent(facts.init ?? INIT_COMMAND)} ` +
+                "The app's folder is not always where this daemon stands. Then restart the dev server and " +
+                'reload the page.',
         };
     }
     if (only === undefined) {
@@ -343,7 +367,8 @@ export function nextActionFor(facts) {
 /** The same action as one sentence, for the prose message the human reads. */
 export function renderNextAction(next) {
     const command = next.command;
-    return command === undefined
+    // `init` changes the user's files, so its line repeats the consent in the reason, not an order.
+    return command === undefined || NoSessionAction.RUN_INIT === next.action
         ? `NEXT ACTION: ${next.reason}`
         : `NEXT ACTION: run \`${command}\` — ${next.reason}`;
 }

package/dist/portal/session/no-session-watch.d.ts

@@ -67,6 +67,13 @@ interface NoSessionWatchOptions {
      * somebody else's app. Injected for tests; production reads the registry scoped by projectId/root.
      */
     ownDevServerPorts?: () => readonly number[];
+    /**
+     * The folder the process listening on `port` runs in, or undefined when it cannot be read.
+     *
+     * An unwired project announces no port, so this is the one fact that ties a running dev server
+     * to it. Injected for tests; a test that injects `probe` and omits this observes no folder.
+     */
+    listenerDirectory?: (port: number) => string | undefined;
     /**
      * What the route the last session was on answers right now, as an HTTP status, or undefined
      * when there is no answer to report.

package/dist/portal/session/no-session-watch.js

@@ -30,6 +30,8 @@ import { findOccupiedSiblings } from '../../command/cli/ports/sibling-ports.js';
 import { isAuthRefusalReason } from '../bridge/auth-failure-reason.js';
 import { devServersForProject } from '@reticlehq/core';
 import { readDevServers } from '../../command/daemon/dev-servers.js';
+import { servingDirectoryOf } from './serving-directory.js';
+import { within } from './zero-install-first-call.js';
 /** Slow enough to be free, fast enough that a dev server started 15s ago is already reflected. */
 const REFRESH_MS = 15_000;
 /** The URL an auto-attach opens. `localhost` for the same reason the probe uses it: both stacks. */
@@ -69,6 +71,12 @@ export function startNoSessionWatch(options) {
      * `options.probe` returns only the serving set, so this stays empty for injected probes.
      */
     let slowListeners = [];
+    /** The folder each listening port's process runs in, read on the scan's cadence, not when asked. */
+    let listenerDirs = new Map();
+    const listenerDirectory = options.listenerDirectory ??
+        (options.probe === undefined
+            ? (port) => servingDirectoryOf(`${LOCALHOST}:${String(port)}`)
+            : () => undefined);
     let siblingListeners = [];
     /**
      * What the last-known route answered, cached beside the port scan for the same reason the scan
@@ -97,8 +105,9 @@ export function startNoSessionWatch(options) {
      */
     const projectScopeFacts = () => {
         const initialized = isWired();
-        if (initialized)
+        if (initialized) {
             return { initialized };
+        }
         const discovery = discoverProjectConfigs(directory);
         const elsewhere = discovery.found.filter((config) => config.directory !== directory);
         if (elsewhere.length > 0) {
@@ -192,21 +201,25 @@ export function startNoSessionWatch(options) {
      */
     const scanPorts = () => {
         const ports = new Set(DEV_SERVER_PORTS);
-        for (const port of ownDevServerPorts())
+        for (const port of ownDevServerPorts()) {
             ports.add(port);
+        }
         const pinned = detectDevCommandInProject(directory)?.port;
-        if (pinned !== undefined)
+        if (pinned !== undefined) {
             ports.add(pinned);
+        }
         const known = options.sessions.lastKnown?.();
         const knownPort = known === undefined ? undefined : portOfUrl(known.url);
-        if (knownPort !== undefined)
+        if (knownPort !== undefined) {
             ports.add(knownPort);
+        }
         // Every departed project, not only the newest. B can still be serving on :3005 after A leaves
         // on :5173, and a scan that never asked :3005 would report B's app as stopped.
         for (const url of options.sessions.tombstoneUrls?.() ?? []) {
             const port = portOfUrl(url);
-            if (port !== undefined)
+            if (port !== undefined) {
                 ports.add(port);
+            }
         }
         return [...ports];
     };
@@ -216,8 +229,9 @@ export function startNoSessionWatch(options) {
      * browser is worse than the sentence the diagnosis already writes about the ports it saw.
      */
     const attributable = (port) => {
-        if (ownDevServerPorts().includes(port))
+        if (ownDevServerPorts().includes(port)) {
             return true;
+        }
         const known = options.sessions.lastKnown?.();
         const projectId = readProjectId(directory);
         if (known === undefined || projectId === undefined || known.projectId !== projectId) {
@@ -232,17 +246,22 @@ export function startNoSessionWatch(options) {
     };
     const autoAttach = async (ports) => {
         const attach = options.attach;
-        if (attach === undefined)
+        if (attach === undefined) {
             return;
-        if (1 !== ports.length)
+        }
+        if (1 !== ports.length) {
             return;
+        }
         const [only] = ports;
-        if (only === undefined || attempted.has(only))
+        if (only === undefined || attempted.has(only)) {
             return;
-        if (!isWired())
+        }
+        if (!isWired()) {
             return;
-        if (!attributable(only))
+        }
+        if (!attributable(only)) {
             return;
+        }
         attempted.add(only);
         try {
             await attach(`${LOCALHOST}:${String(only)}`);
@@ -254,10 +273,12 @@ export function startNoSessionWatch(options) {
     const refresh = () => {
         // Nothing to diagnose while a session is live, and no reason to scan. What the last scan saw
         // predates this session, so it is no observation of where the session goes on to depart from.
-        if (options.sessions.count() > 0)
+        if (options.sessions.count() > 0) {
             probed = new Set();
-        if (running || options.sessions.count() > 0)
+        }
+        if (running || options.sessions.count() > 0) {
             return;
+        }
         running = true;
         const candidates = scanPorts();
         void (options.probe === undefined
@@ -269,6 +290,10 @@ export function startNoSessionWatch(options) {
             .then(async (ports) => {
             probed = new Set(candidates);
             listening = ports;
+            listenerDirs = new Map(ports.flatMap((port) => {
+                const dir = listenerDirectory(port);
+                return dir === undefined ? [] : [[port, dir]];
+            }));
             siblingListeners =
                 options.occupiedSiblings !== undefined
                     ? await options.occupiedSiblings()
@@ -280,8 +305,9 @@ export function startNoSessionWatch(options) {
             const known = options.sessions.lastKnown?.();
             if (known !== undefined && lastKnownStatus?.url !== known.url) {
                 const status = await routeStatus(known.url);
-                if (status !== undefined)
+                if (status !== undefined) {
                     lastKnownStatus = { url: known.url, status };
+                }
             }
             await autoAttach(ports);
         })
@@ -324,10 +350,12 @@ export function startNoSessionWatch(options) {
      */
     const currentHelloRefusal = () => {
         const closure = options.sessions.lastClosure?.();
-        if (closure?.page === undefined || isAuthRefusalReason(closure.reason))
+        if (closure?.page === undefined || isAuthRefusalReason(closure.reason)) {
             return undefined;
-        if (true === options.sessions.connectedSinceLastClosure?.())
+        }
+        if (true === options.sessions.connectedSinceLastClosure?.()) {
             return undefined;
+        }
         return { reason: closure.reason, ...closure.page };
     };
     /**
@@ -354,15 +382,25 @@ export function startNoSessionWatch(options) {
         const ownPorts = new Set(devServersForProject(readDevServers(stateDir), { projectId, root: dir }).map((entry) => entry.port));
         if (known !== undefined) {
             const port = portOfUrl(known.url);
-            if (port !== undefined)
+            if (port !== undefined) {
                 ownPorts.add(port);
+            }
+        }
+        // A process that runs in this folder is this project's dev server, announced or not. An unwired
+        // project announces nothing, and without this its running app read as absent.
+        for (const port of listening) {
+            if (within(listenerDirs.get(port), dir)) {
+                ownPorts.add(port);
+            }
         }
         const heard = listening.filter((port) => ownPorts.has(port));
+        const others = listening.filter((port) => !ownPorts.has(port));
         // Not in the last scan means we have not looked, not that the server stopped. Treating the
         // gap as "down" is what tells a still-running app to start a second one.
         for (const port of ownPorts) {
-            if (!probed.has(port) && !heard.includes(port))
+            if (!probed.has(port) && !heard.includes(port)) {
                 heard.push(port);
+            }
         }
         const slow = slowListeners.filter((port) => ownPorts.has(port));
         const closure = options.sessions.lastClosure?.();
@@ -433,6 +471,7 @@ export function startNoSessionWatch(options) {
             ...(helloRefused === undefined ? {} : { helloRefused: helloRefused.reason }),
             ...(split === undefined ? {} : { splitBrain: split }),
             listening: heard,
+            ...(0 === others.length ? {} : { otherListeners: others }),
             slowListeners: slow,
             ...(known === undefined
                 ? {}
@@ -451,8 +490,9 @@ export function startNoSessionWatch(options) {
      */
     const callerAnswer = () => {
         const caller = callingClientDirectory();
-        if (caller === undefined)
+        if (caller === undefined) {
             return undefined;
+        }
         return diagnosisFor(caller);
     };
     /**
@@ -489,8 +529,9 @@ export function startNoSessionWatch(options) {
             // command and the sentence beside it name the same page.
             ...(() => {
                 const known = options.sessions.lastKnown?.();
-                if (known === undefined)
+                if (known === undefined) {
                     return {};
+                }
                 return {
                     lastKnownUrl: known.url,
                     ...(known.departedTo === undefined ? {} : { departedTo: known.departedTo }),
@@ -512,8 +553,9 @@ export function startNoSessionWatch(options) {
     // calls a moment apart can genuinely disagree (#615).
     const explain = () => {
         const caller = callerAnswer();
-        if (caller !== undefined)
+        if (caller !== undefined) {
             return explainNoSession(caller.facts);
+        }
         const scope = projectScopeFacts();
         return explainNoSession({
             everConnected: options.sessions.everConnected(),
@@ -563,8 +605,9 @@ export function startNoSessionWatch(options) {
             // has none to name.
             ...(() => {
                 const known = options.sessions.lastKnown?.();
-                if (undefined === known)
+                if (undefined === known) {
                     return {};
+                }
                 // The status rides only when it was fetched for THIS url. A departure since the fetch
                 // means the cached answer is about a route nobody is asking about.
                 const status = lastKnownStatus !== undefined && lastKnownStatus.url === known.url
@@ -635,8 +678,9 @@ export function wireSessionScope(sessions, activeProjectId, port,
 wasReapedLease, 
 /** Opens a URL in a Reticle-owned browser (the pool). Omitted ⇒ auto-attach is off. */
 attach) {
-    if (activeProjectId !== undefined)
+    if (activeProjectId !== undefined) {
         sessions.setDefaultScope({ projectId: activeProjectId });
+    }
     return startNoSessionWatch({
         sessions,
         port,

package/dist/portal/session/output-budget.d.ts

@@ -79,4 +79,14 @@ export declare function sizeCost(payload: unknown): SizeCost;
  * Non-object results (e.g. a thrown-error envelope) pass through unchanged.
  */
 export declare function withSizeCost<T>(result: T): T;
+/**
+ * Drop `sessionId` from an event in a response the caller scoped to ONE session.
+ *
+ * The caller passed that id in the request, so echoing it on every event is the request quoted back
+ * once per row. Measured on a live app it was 25% of a four-event `reticle_observe` payload, and it
+ * grows linearly with the timeline — a fifty-event window spends ~2.5KB restating a fact the caller
+ * supplied. The id stays on the wire between SDK and bridge, where events from different sessions
+ * really do interleave; it is only redundant at this boundary.
+ */
+export declare function withoutConstantSessionId(event: unknown): unknown;
 export {};

package/dist/portal/session/output-budget.js

@@ -106,3 +106,19 @@ export function withSizeCost(result) {
         return result;
     return { ...result, cost: sizeCost(result) };
 }
+/**
+ * Drop `sessionId` from an event in a response the caller scoped to ONE session.
+ *
+ * The caller passed that id in the request, so echoing it on every event is the request quoted back
+ * once per row. Measured on a live app it was 25% of a four-event `reticle_observe` payload, and it
+ * grows linearly with the timeline — a fifty-event window spends ~2.5KB restating a fact the caller
+ * supplied. The id stays on the wire between SDK and bridge, where events from different sessions
+ * really do interleave; it is only redundant at this boundary.
+ */
+export function withoutConstantSessionId(event) {
+    if (typeof event !== 'object' || null === event) {
+        return event;
+    }
+    const { sessionId: _sessionId, ...rest } = event;
+    return rest;
+}

package/dist/portal/session/presence/session-lease.d.ts

@@ -12,3 +12,5 @@ export interface SessionLease {
     IMPORTANT: string;
 }
 export declare function buildSessionLease(sessionId: string, openedAt: number): SessionLease;
+/** The age warning spliced onto session-bound results after SESSION_LEASE.WARN_AFTER_MS, else undefined. */
+export declare function sessionAgeWarning(sessionId: string, ageMs: number): string | undefined;

package/dist/portal/session/presence/session-lease.js

@@ -1,3 +1,4 @@
+import { SESSION_LEASE } from '@reticlehq/core';
 /**
  * Kept SHORT on purpose, and this is the reason to read before editing it.
  *
@@ -12,3 +13,10 @@ const SESSION_LEASE_NOTICE = 'When you stop driving, call reticle_session {actio
 export function buildSessionLease(sessionId, openedAt) {
     return { sessionId, opened_at: openedAt, IMPORTANT: SESSION_LEASE_NOTICE };
 }
+/** The age warning spliced onto session-bound results after SESSION_LEASE.WARN_AFTER_MS, else undefined. */
+export function sessionAgeWarning(sessionId, ageMs) {
+    if (ageMs < SESSION_LEASE.WARN_AFTER_MS)
+        return undefined;
+    const minutes = Math.floor(ageMs / 60_000);
+    return `Session ${sessionId} has been open for ${String(minutes)} minutes. If your task is complete, call reticle_session{action:"end"} now.`;
+}

package/dist/portal/session/recorded-gaps.d.ts

@@ -1,5 +1,5 @@
 import type { InboxMessage } from './human/live-control.js';
-import { type Coverage, CoverageCapability, type ImpactSnapshot } from '@reticlehq/core';
+import { type Coverage, CoverageCapability, type ImpactSnapshot, ENGINE_BLIND_SPOTS_FIELD, type EngineBlindSpot, type Predicate } from '@reticlehq/core';
 export interface RecordedGap {
     kind: string;
     missing: string;
@@ -46,6 +46,16 @@ export interface ProbedTab extends NotedTab {
  * True when a page showed something not known before.
  */
 export declare function probeMarkers(tabs: readonly ProbedTab[]): Promise<boolean>;
+/**
+ * The `engineBlindSpots` field for a verdict result: what this engine could not observe in the
+ * session so far. Notes this verdict's own comparison first, so a `compare` clears the arithmetic
+ * spot on the result that ran it. `claims`: the inline intent, then the run's declared intents.
+ */
+export declare function engineBlindSpotsField(sessionId: string, predicate: Predicate | undefined, intent: unknown, declared: readonly {
+    statement: string;
+}[]): {
+    [ENGINE_BLIND_SPOTS_FIELD]: EngineBlindSpot[];
+};
 /** What this session's verdicts recorded, newest first. */
 export declare function recordedGaps(sessionId: string): readonly RecordedGap[];
 /** Forget a session that ended. What its app has shown is kept: it is still that app's. */
@@ -72,22 +82,16 @@ export declare function announcedChannels(tab: InstrumentedTab): string[];
  * The platform reads the same list from the local-apps report, so both sides move together.
  */
 export declare function notApplicableOf(tab: NotedTab): CoverageCapability[];
-/** Whether the Harness may drive this tab's app (see core's `instrumentation-coverage.ts`), as pushed. */
-export interface TabHarnessGate {
-    percent: number;
-    unlocked: boolean;
-    reason?: string;
-}
 /**
- * This tab's coverage and its Harness gate, with the coding-agent prompt when its verdicts recorded
- * any gap or the gate is shut: below the gate the prompt names every unseen capability, so there is
- * always something to hand the agent.
+ * This tab's coverage and its setup score (see core's `instrumentation-coverage.ts`), with the
+ * coding-agent prompt when its verdicts recorded any gap. The score is information: it never gates
+ * the Harness.
  */
 export declare function instrumentationOf(tab: InstrumentedTab, 
 /** The app's other tabs: what any of them has seen or recorded counts, as on the platform. */
 siblings?: readonly InstrumentedTab[]): Coverage & {
     prompt?: string;
-    harnessGate: TabHarnessGate;
+    setupScore: number;
 };
 /**
  * The impact snapshot a tab is pushed, carrying that tab's own coverage, running drive and agent

package/dist/portal/session/recorded-gaps.js

@@ -8,7 +8,7 @@
  */
 import { withRunningDrive } from '../../features/harness/drive-runs.js';
 import { agentLinkOf } from './agent-link.js';
-import { CoverageMarker, InstrumentationGapKind, LINK_APP_GAPS_MAX, ReticleCommand, agentPromptFor, coverageOf, harnessGateOf, harnessUnlockPrompt, CoverageCapability, } from '@reticlehq/core';
+import { CoverageMarker, InstrumentationGapKind, LINK_APP_GAPS_MAX, ReticleCommand, agentPromptFor, coverageOf, coveragePercent, CoverageCapability, ENGINE_BLIND_SPOTS_FIELD, computesComparison, engineBlindSpots, } from '@reticlehq/core';
 const bySession = new Map();
 const text = (value) => 'string' === typeof value && 0 < value.length ? value : undefined;
 /** Remember gaps a verdict on this session just reported. Malformed entries are skipped. */
@@ -90,6 +90,13 @@ export function noteActedElement(tab, result) {
         return;
     const acted = result;
     noteTestidSeen(tab, text(acted['testid']));
+    // An action that ran with a canvas on screen: its pixels go unobserved for this run.
+    const effect = acted['effect'];
+    const canvases = 'object' === typeof effect && null !== effect
+        ? effect['canvases']
+        : undefined;
+    if ('number' === typeof canvases && 0 < canvases)
+        canvasSeen.add(tab.id);
     const source = acted['source'];
     if ('object' === typeof source && null !== source) {
         const file = text(source['file']);
@@ -146,6 +153,29 @@ export async function probeMarkers(tabs) {
     }));
     return before < sourceSeen.size + testidSeen.size;
 }
+/**
+ * Sessions where an action ran with a canvas on screen, and sessions where a verdict ran a computed
+ * comparison. Facts about a RUN, so a reload (a new HELLO under the same id) does not clear them.
+ */
+const canvasSeen = new Set();
+const comparedSeen = new Set();
+/**
+ * The `engineBlindSpots` field for a verdict result: what this engine could not observe in the
+ * session so far. Notes this verdict's own comparison first, so a `compare` clears the arithmetic
+ * spot on the result that ran it. `claims`: the inline intent, then the run's declared intents.
+ */
+export function engineBlindSpotsField(sessionId, predicate, intent, declared) {
+    if (computesComparison(predicate))
+        comparedSeen.add(sessionId);
+    const claims = [text(intent), ...declared.map((each) => each.statement)];
+    return {
+        [ENGINE_BLIND_SPOTS_FIELD]: engineBlindSpots({
+            canvasSeen: canvasSeen.has(sessionId),
+            compared: comparedSeen.has(sessionId),
+            claims,
+        }),
+    };
+}
 /** What this session's verdicts recorded, newest first. */
 export function recordedGaps(sessionId) {
     return bySession.get(sessionId) ?? [];
@@ -162,6 +192,8 @@ export function forgetAllRecordedGaps() {
     sourceSeen.clear();
     testidSeen.clear();
     sourceNotApplicable.clear();
+    canvasSeen.clear();
+    comparedSeen.clear();
 }
 /**
  * The tab's HELLO channels, plus the `source` marker when an act or verdict mapped a control to
@@ -204,9 +236,9 @@ export function notApplicableOf(tab) {
         : [];
 }
 /**
- * This tab's coverage and its Harness gate, with the coding-agent prompt when its verdicts recorded
- * any gap or the gate is shut: below the gate the prompt names every unseen capability, so there is
- * always something to hand the agent.
+ * This tab's coverage and its setup score (see core's `instrumentation-coverage.ts`), with the
+ * coding-agent prompt when its verdicts recorded any gap. The score is information: it never gates
+ * the Harness.
  */
 export function instrumentationOf(tab, 
 /** The app's other tabs: what any of them has seen or recorded counts, as on the platform. */
@@ -220,21 +252,10 @@ siblings = []) {
     const url = tab.url ?? '';
     const appName = appNameOf(url);
     const notApplicable = notApplicableOf(tab);
-    const gate = harnessGateOf(coverage, notApplicable);
-    const harnessGate = {
-        percent: gate.percent,
-        unlocked: gate.unlocked,
-        ...(gate.reason === undefined ? {} : { reason: gate.reason }),
-    };
-    if (!gate.unlocked)
-        return {
-            ...coverage,
-            harnessGate,
-            prompt: harnessUnlockPrompt({ coverage, gaps, appName, url, notApplicable }),
-        };
+    const setupScore = coveragePercent(coverage, notApplicable);
     return 0 === gaps.length
-        ? { ...coverage, harnessGate }
-        : { ...coverage, harnessGate, prompt: agentPromptFor({ gaps, appName, url }) };
+        ? { ...coverage, setupScore }
+        : { ...coverage, setupScore, prompt: agentPromptFor({ gaps, appName, url }) };
 }
 /**
  * The impact snapshot a tab is pushed, carrying that tab's own coverage, running drive and agent

package/dist/portal/session/serving-directory.d.ts

@@ -8,13 +8,24 @@
  * which `memory/project` has no business knowing. The resolver takes the answer as an injected
  * function; the composition roots pass this one.
  */
-import { type DevServerEntry } from '@reticlehq/core';
+import { type Checkout, type DevServerEntry } from '@reticlehq/core';
+import { type CheckoutSource } from './session-manager.js';
 /** Where `servingDirectoryOf` gets its two observations. Injected so a test needs no processes. */
 export interface ServingDirectoryIo {
     /** Live dev servers that announced themselves (the Vite plugin writes `devserver-<port>.json`). */
     devServers: () => readonly DevServerEntry[];
     /** The working directory of whatever listens on `port`, or null when it cannot be read. */
     listenerCwd: (port: number) => string | null;
+    /** A running dev proxy that serves names under `.localhost`, or undefined when there is none. */
+    devProxy?: () => DevProxy | undefined;
+}
+/** A dev proxy: the ports it listens on, and the dev server port behind each name it serves. */
+export interface DevProxy {
+    ports: readonly number[];
+    routes: readonly {
+        hostname: string;
+        port: number;
+    }[];
 }
 /**
  * The directory of the dev server that served `origin`, or undefined when it cannot be observed.
@@ -22,6 +33,17 @@ export interface ServingDirectoryIo {
  * Two observations, exact one first. A dev server whose plugin announced this port names its own
  * root and works on every platform. Otherwise the process listening on the port is asked for its
  * working directory, which covers frameworks with no announcing plugin (Next.js) wherever `lsof`
- * runs. Loopback only: a remote page's port says nothing about any process on this machine.
+ * runs. Behind a dev proxy, the proxy's route table first names the dev server's own port. Loopback
+ * only: a remote page's port says nothing about any process on this machine.
  */
 export declare function servingDirectoryOf(origin: string, io?: ServingDirectoryIo): string | undefined;
+/**
+ * The live answers for a worktree-scoped resolve: the calling agent's checkout (from the directory
+ * its MCP proxy runs in) and each tab's checkout (from the dev server that served it).
+ *
+ * A tab is placed once for each connection. A page that a different dev server serves has reloaded,
+ * and a reload is a new connection. A cache by origin and time named a port that moved to another
+ * worktree after the old one for its whole lifetime.
+ * ponytail: a lookup that failed stays failed for that connection; the tab then counts as unknown.
+ */
+export declare function liveCheckoutSource(placeOrigin?: (origin: string) => Checkout | undefined): CheckoutSource;