@reticlehq/server 2.4.0 → 2.5.0

package/dist/oracles/self-instrument.d.ts

@@ -20,7 +20,7 @@ export interface InstrumentationGap {
     /** Why this gap matters (e.g. "checkout flow asserts presence only"). */
     context?: string;
 }
-export interface InstrumentationProposal {
+interface InstrumentationProposal {
     file: string;
     line: number;
     /** The code to insert. */
@@ -29,3 +29,4 @@ export interface InstrumentationProposal {
 }
 /** Turn located capability gaps into ready-to-apply instrumentation proposals. Deterministic. */
 export declare function proposeInstrumentation(gaps: readonly InstrumentationGap[]): InstrumentationProposal[];
+export {};

package/dist/oracles/self-instrument.js

@@ -12,7 +12,7 @@ export const InstrumentationGapKind = {
 };
 /** PascalCase a store name for a `useX.getState` hint (cart → Cart). */
 function pascal(name) {
-    return name.length === 0 ? name : name[0]?.toUpperCase() + name.slice(1);
+    return 0 === name.length ? name : name[0]?.toUpperCase() + name.slice(1);
 }
 function insertFor(gap) {
     switch (gap.kind) {

package/dist/phenomena/phenomena.js

@@ -28,14 +28,14 @@ export function detectHidden500(events) {
     for (const event of events) {
         if (event.type === EventType.PAGE_HEALTH) {
             const h = event.data['hidden'];
-            if (typeof h === 'boolean')
+            if ('boolean' === typeof h)
                 hidden = h;
             continue;
         }
         if (event.type !== EventType.NET_REQUEST)
             continue;
         const status = event.data['status'];
-        if (hidden && typeof status === 'number' && status >= 500) {
+        if (hidden && 'number' === typeof status && status >= 500) {
             findings.push({
                 phenomenon: PhenomenonType.HIDDEN_500,
                 evidence: { url: event.data['url'], status, method: event.data['method'] },
@@ -83,7 +83,7 @@ export function detectSwallowedErrors(events) {
             const detail = event.data['data'];
             findings.push({
                 phenomenon: PhenomenonType.SWALLOWED_ERROR,
-                evidence: typeof detail === 'object' && detail !== null ? detail : {},
+                evidence: 'object' === typeof detail && detail !== null ? detail : {},
             });
         }
     }

package/dist/platform.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The `process.platform` values this daemon actually branches on, named once.
+ *
+ * They were spelled inline in five files — `cli-launch`, `cloud-cli`, `init/node-io`, `update/updater`
+ * — and every one of them gates real behaviour rather than cosmetics: whether a spawn needs a shell,
+ * whether the npm binary is `npm.cmd`, which command opens a browser. A typo in any of those reads as
+ * "Windows is broken" and is invisible on the machine of whoever wrote it, because the wrong branch
+ * simply never runs there.
+ *
+ * Node-side only, so deliberately NOT in `@reticlehq/core` — core is the wire contract, and a
+ * platform name never crosses the wire.
+ */
+export declare const NodePlatform: {
+    readonly WINDOWS: "win32";
+    readonly MACOS: "darwin";
+};

package/dist/platform.js

@@ -0,0 +1,16 @@
+/**
+ * The `process.platform` values this daemon actually branches on, named once.
+ *
+ * They were spelled inline in five files — `cli-launch`, `cloud-cli`, `init/node-io`, `update/updater`
+ * — and every one of them gates real behaviour rather than cosmetics: whether a spawn needs a shell,
+ * whether the npm binary is `npm.cmd`, which command opens a browser. A typo in any of those reads as
+ * "Windows is broken" and is invisible on the machine of whoever wrote it, because the wrong branch
+ * simply never runs there.
+ *
+ * Node-side only, so deliberately NOT in `@reticlehq/core` — core is the wire contract, and a
+ * platform name never crosses the wire.
+ */
+export const NodePlatform = {
+    WINDOWS: 'win32',
+    MACOS: 'darwin',
+};

package/dist/pool/playwright-launcher.d.ts

@@ -6,8 +6,21 @@
  * Headless by default — the pool exists for fault-tolerant headless multi-agent testing.
  */
 import type { Launcher } from './browser-pool.js';
-/** The fix for the most common first-run failure: Chromium isn't installed for Playwright. */
-export declare const CHROMIUM_MISSING_HINT = "Chromium is not installed for Playwright. Run: npx playwright install chromium";
+/**
+ * How a leased tab navigates. Pure, and exported, because the decision in it is worth a test while
+ * the rest of this file needs a real Chromium.
+ *
+ * `waitUntil: 'domcontentloaded'` — NOT Playwright's default of `load`. `load` waits for every
+ * subresource, so an app with one that never finishes burns the whole nav budget and the lease then
+ * reports "is the app running?" about an app that is running. Measured on the sveltekit fixture:
+ * 30,501ms and a false diagnosis. The SDK connect is a module script and runs before
+ * DOMContentLoaded, and the pool separately waits for the session to register, so the load event was
+ * never what proved the page was usable.
+ */
+export declare function gotoOptions(timeoutMs: number | undefined): {
+    waitUntil: 'domcontentloaded';
+    timeout?: number;
+};
 /** A Launcher that boots a real headless Chromium and adapts it to the pool's interface. */
 export declare function playwrightLauncher(opts?: {
     headless?: boolean;

package/dist/pool/playwright-launcher.js

@@ -8,6 +8,25 @@
 import { BrowserLaunchKind } from '@reticlehq/core';
 import { getSessionMetrics } from '../telemetry/session-metrics.js';
 import { classifyConnectFailure } from '../telemetry/connect-failure.js';
+/**
+ * How a leased tab navigates. Pure, and exported, because the decision in it is worth a test while
+ * the rest of this file needs a real Chromium.
+ *
+ * `waitUntil: 'domcontentloaded'` — NOT Playwright's default of `load`. `load` waits for every
+ * subresource, so an app with one that never finishes burns the whole nav budget and the lease then
+ * reports "is the app running?" about an app that is running. Measured on the sveltekit fixture:
+ * 30,501ms and a false diagnosis. The SDK connect is a module script and runs before
+ * DOMContentLoaded, and the pool separately waits for the session to register, so the load event was
+ * never what proved the page was usable.
+ */
+export function gotoOptions(timeoutMs) {
+    return {
+        waitUntil: 'domcontentloaded',
+        // Absent, not zero: zero means "no timeout" to Playwright, which would turn a slow page into a
+        // lease that never returns.
+        ...(timeoutMs === undefined ? {} : { timeout: timeoutMs }),
+    };
+}
 function wrapBrowser(browser) {
     return {
         isConnected: () => browser.isConnected(),
@@ -17,7 +36,7 @@ function wrapBrowser(browser) {
                 newPage: async () => {
                     const page = await context.newPage();
                     return {
-                        goto: (url, opts) => page.goto(url, opts?.timeoutMs === undefined ? undefined : { timeout: opts.timeoutMs }),
+                        goto: (url, opts) => page.goto(url, gotoOptions(opts?.timeoutMs)),
                         close: () => page.close(),
                         onCrash: (handler) => page.on('crash', handler),
                     };
@@ -30,7 +49,7 @@ function wrapBrowser(browser) {
     };
 }
 /** The fix for the most common first-run failure: Chromium isn't installed for Playwright. */
-export const CHROMIUM_MISSING_HINT = 'Chromium is not installed for Playwright. Run: npx playwright install chromium';
+const CHROMIUM_MISSING_HINT = 'Chromium is not installed for Playwright. Run: npx playwright install chromium';
 /** A Launcher that boots a real headless Chromium and adapts it to the pool's interface. */
 export function playwrightLauncher(opts = {}) {
     const headless = opts.headless ?? true;

package/dist/project/fs-port.js

@@ -48,6 +48,6 @@ export function createNodeFileSystem() {
             const s = await stat(path);
             return { mtimeMs: s.mtimeMs };
         },
-        isNotFound: (error) => error?.code === 'ENOENT',
+        isNotFound: (error) => 'ENOENT' === error?.code,
     };
 }

package/dist/project/project-tools.js

@@ -36,7 +36,7 @@ function numericDelta(before, after) {
  */
 async function cloudRegression(deps, sessionId) {
     const config = resolveCloudConfig(process.env);
-    if (config === null)
+    if (null === config)
         return undefined;
     let projectId;
     try {
@@ -173,7 +173,7 @@ export const PROJECT_TOOLS = [
             const kindArg = args['kind'];
             const summary = asString(args['summary']);
             await deps.project.recordRun({
-                kind: typeof kindArg === 'string' ? kindArg : RunKind.MANUAL,
+                kind: 'string' === typeof kindArg ? kindArg : RunKind.MANUAL,
                 name,
                 status,
                 ...(summary !== undefined ? { summary } : {}),

package/dist/runs/build-verification-run.js

@@ -46,7 +46,7 @@ export function computeVerdict(input) {
         status = VerdictStatus.PASS;
     const ran = input.flows.length + input.checks.length;
     let confidence;
-    if (ran === 0)
+    if (0 === ran)
         confidence = RunConfidence.LOW;
     else if (input.flows.some((f) => f.oracle !== undefined) || input.checks.length > 0)
         confidence = RunConfidence.HIGH;

package/dist/runs/repair-prompt.d.ts

@@ -5,12 +5,6 @@
  * RepairPacket shape. This is the OEM self-heal value — a verdict that also says how to fix.
  */
 import { type FlowReplayResult, type RepairPacket } from '@reticlehq/core';
-/**
- * Build a repair packet for a failed replay, or undefined when the flow passed. The actual cause is
- * the decision's whatChanged, falling back to the replay error or a generic message.
- */
-/** The deviation report's headline when it flagged something — narrows the replay's `unknown` deviation. */
-export declare function deviationHeadline(deviation: unknown): string | undefined;
 export declare function buildRepairPacket(replay: FlowReplayResult): RepairPacket | undefined;
 /** Build the repair packets for a set of replays (failed ones only). */
 export declare function buildRepairPackets(replays: ReadonlyArray<FlowReplayResult>): RepairPacket[];

package/dist/runs/repair-prompt.js

@@ -36,11 +36,11 @@ function suggestedPrompt(name, actual, where, nextAction) {
  * the decision's whatChanged, falling back to the replay error or a generic message.
  */
 /** The deviation report's headline when it flagged something — narrows the replay's `unknown` deviation. */
-export function deviationHeadline(deviation) {
-    if (typeof deviation !== 'object' || deviation === null)
+function deviationHeadline(deviation) {
+    if (typeof deviation !== 'object' || null === deviation)
         return undefined;
     const d = deviation;
-    if (Array.isArray(d.deviations) && d.deviations.length > 0 && typeof d.headline === 'string') {
+    if (Array.isArray(d.deviations) && d.deviations.length > 0 && 'string' === typeof d.headline) {
         return d.headline;
     }
     return undefined;

package/dist/runs/risk-classify.js

@@ -62,7 +62,7 @@ export function buildRisks(changedFiles, policy = {}) {
     const risks = [];
     for (const { surface } of RISK_PATTERNS) {
         const files = filesBySurface.get(surface);
-        if (files === undefined || files.length === 0)
+        if (files === undefined || 0 === files.length)
             continue;
         risks.push({
             surface,

package/dist/runs/run-diff.d.ts

@@ -22,8 +22,6 @@ export interface RunDiff {
     };
     headline: string;
 }
-/** Below this percent, a duration change is noise (machine jitter), not a regression. */
-export declare const DEFAULT_NOISE_FLOOR_PCT = 10;
 /**
  * Compare two verification runs — the concrete answer to "what changed between run A and B". Flow
  * durations are diffed with a noise floor (jitter below it is ignored); status changes and new/removed

package/dist/runs/run-diff.js

@@ -1,5 +1,5 @@
 /** Below this percent, a duration change is noise (machine jitter), not a regression. */
-export const DEFAULT_NOISE_FLOOR_PCT = 10;
+const DEFAULT_NOISE_FLOOR_PCT = 10;
 function pct(before, delta) {
     return before > 0 ? Math.round((delta / before) * 100) : 0;
 }
@@ -11,7 +11,7 @@ function headlineFor(diff) {
     const regressions = diff.flows.filter((f) => f.regressed);
     if (regressions.length > 0) {
         const worst = regressions[0];
-        parts.push(`${String(regressions.length)} regression${regressions.length === 1 ? '' : 's'} (worst: ${worst?.name ?? ''} ${String(worst?.durationDeltaPct ?? 0)}%)`);
+        parts.push(`${String(regressions.length)} regression${1 === regressions.length ? '' : 's'} (worst: ${worst?.name ?? ''} ${String(worst?.durationDeltaPct ?? 0)}%)`);
     }
     if (diff.newFlows.length > 0)
         parts.push(`+${String(diff.newFlows.length)} flow`);
@@ -20,7 +20,7 @@ function headlineFor(diff) {
     if (diff.verdictChange !== undefined) {
         parts.push(`verdict ${diff.verdictChange.from}→${diff.verdictChange.to}`);
     }
-    return parts.length === 0 ? 'no significant change between runs' : parts.join(', ');
+    return 0 === parts.length ? 'no significant change between runs' : parts.join(', ');
 }
 /**
  * Compare two verification runs — the concrete answer to "what changed between run A and B". Flow

package/dist/runs/run-tools.js

@@ -38,7 +38,7 @@ export const RUN_TOOLS = [
         handler: async (deps, args) => {
             const store = new RunStore(deps.fs, deps.reticleRoot);
             // format:"diff" is a whole-history operation (two most-recent runs), not a single-run read.
-            if (asString(args['format']) === 'diff') {
+            if ('diff' === asString(args['format'])) {
                 const pair = await store.latestTwo();
                 if (pair === undefined) {
                     return {
@@ -75,7 +75,7 @@ export const RUN_TOOLS = [
                 }
                 run = latest;
             }
-            return asString(args['format']) === 'report' ? { report: renderRunReport(run) } : { run };
+            return 'report' === asString(args['format']) ? { report: renderRunReport(run) } : { run };
         },
     },
 ];

package/dist/runs/verification-sync.js

@@ -41,7 +41,7 @@ function assembleRun(deps, timed, projectId) {
  * unaffected. Returns the runId (for logging/tests); undefined if nothing was produced (empty suite).
  */
 export async function persistAndSyncVerificationRun(deps, timed, projectId) {
-    if (timed.length === 0)
+    if (0 === timed.length)
         return undefined;
     let run;
     try {
@@ -56,7 +56,7 @@ export async function persistAndSyncVerificationRun(deps, timed, projectId) {
     }
     // Per-project cloud: only push when THIS project has cloud attached AND its policy allows runs.
     const cloud = await resolveProjectCloud(deps.fs, deps.reticleRoot, homedir(), process.env);
-    if (cloud.config === null || !cloud.policy.runs)
+    if (null === cloud.config || !cloud.policy.runs)
         return run.runId; // not attached / runs disabled → local only
     const result = await syncRunToCloud(run, cloud.config, (url, init) => fetch(url, init));
     if (result.outcome !== SyncOutcome.SYNCED) {

package/dist/runs/verify-http.js

@@ -67,7 +67,7 @@ function toVerifyOptions(body) {
 }
 /** Constant-time token check. Empty expected token ⇒ open (localhost-only deployments). */
 export function tokenOk(provided, expected) {
-    if (expected.length === 0)
+    if (0 === expected.length)
         return true;
     if (provided === undefined)
         return false;

package/dist/runs/verify-server.js

@@ -91,7 +91,7 @@ export function startVerifyServer(opts, port) {
     return new Promise((resolve) => {
         server.listen(port, LOCALHOST, () => {
             const address = server.address();
-            const boundPort = typeof address === 'object' && address !== null ? address.port : port;
+            const boundPort = 'object' === typeof address && address !== null ? address.port : port;
             resolve({ server, port: boundPort });
         });
     });

package/dist/session/command-timeout.d.ts

@@ -1,3 +1,4 @@
+import { AppRuntime } from '@reticlehq/core';
 /**
  * Turn a bare command timeout into something the reader can act on.
  *
@@ -21,9 +22,15 @@
  * The advice is ADDED, never substituted — the original fact still leads — and only for a runtime
  * that can actually suffer it, since misdirecting an Electron user costs them the same hour.
  */
-/** What the page told us about its shell, via PAGE_HEALTH. Undefined before the first report. */
-export type PageRuntime = 'electron' | 'tauri' | 'web';
-export interface TimeoutContext {
+/**
+ * What the page told us about its shell, via PAGE_HEALTH. Undefined before the first report.
+ *
+ * An alias of core's AppRuntime rather than a second list of the same three strings: the SDK reports
+ * this value, so it is a wire value, and two independent spellings of it is how one side gains a
+ * runtime the other silently refuses to recognise.
+ */
+export type PageRuntime = AppRuntime;
+interface TimeoutContext {
     url: string;
     /** The page's own last visibility report. */
     hidden: boolean;
@@ -33,3 +40,4 @@ export interface TimeoutContext {
     lastSeenMs?: number;
 }
 export declare function commandTimeoutMessage(name: string, timeoutMs: number, context: TimeoutContext): string;
+export {};

package/dist/session/command-timeout.js

@@ -1,4 +1,4 @@
-import { isOpaqueOrigin } from '@reticlehq/core';
+import { AppRuntime, isOpaqueOrigin } from '@reticlehq/core';
 /**
  * Inbound silence beyond this means the page may genuinely be wedged; inside it, the SDK has spoken
  * recently enough that "the page is hung" is provably the wrong story. A page that is streaming
@@ -18,7 +18,7 @@ const HIDDEN_ADVICE = 'The page last reported itself hidden, and this is a WKWeb
     'loaded. If neither fits, the page is reachable but not executing, which is worth reporting.';
 /** True when this session is a WebKit desktop shell — the only runtime that suffers this. */
 function isWebKitDesktop(context) {
-    if (context.runtime === 'tauri')
+    if (AppRuntime.TAURI === context.runtime)
         return true;
     // A `tauri://` origin is unambiguous even before the first health report lands.
     if (context.runtime !== undefined)

package/dist/session/control-envelope.d.ts

@@ -12,6 +12,12 @@ interface ControlEnvelope {
  * recovery path (address the guidance, then reticle_session{action:"resume"}) lives here in exactly one place.
  */
 export declare const PAUSE_HINT = "Paused by the human. Address the guidance, then call reticle_session{action:\"resume\"} (or wait for the human to resume).";
+/**
+ * `because` for the verdict a paused verification returns. Nothing was driven and nothing was
+ * asserted, which is the definition of unknown — never `no`, which would report the human's own
+ * pause as the app failing.
+ */
+export declare const PAUSED_NO_VERDICT = "the human paused this session, so nothing was driven and nothing was asserted";
 /** Shape returned by the short-circuit when an action tool refuses while paused. */
 interface PausedResult {
     paused: true;

package/dist/session/control-envelope.js

@@ -5,6 +5,12 @@ import { z } from 'zod';
  * recovery path (address the guidance, then reticle_session{action:"resume"}) lives here in exactly one place.
  */
 export const PAUSE_HINT = 'Paused by the human. Address the guidance, then call reticle_session{action:"resume"} (or wait for the human to resume).';
+/**
+ * `because` for the verdict a paused verification returns. Nothing was driven and nothing was
+ * asserted, which is the definition of unknown — never `no`, which would report the human's own
+ * pause as the app failing.
+ */
+export const PAUSED_NO_VERDICT = 'the human paused this session, so nothing was driven and nothing was asserted';
 /**
  * outputSchema fields every action tool that can short-circuit on pause MUST declare, or a validating
  * profile strips the WHOLE pause payload — and because `guidance` is drained-once, that loses the
@@ -28,7 +34,7 @@ export const pausedOutputShape = {
 export function buildControlEnvelope(session) {
     const state = session.getState();
     const guidance = session.drainInbox().map((m) => m.text);
-    if (state === SessionState.ACTIVE && guidance.length === 0)
+    if (state === SessionState.ACTIVE && 0 === guidance.length)
         return undefined;
     return { state, guidance };
 }

package/dist/session/dev-server-probe.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Which of the usual dev-server ports have something listening on them.
+ *
+ * The one fact that separates "the app is not running" from "the app is running and never dialled
+ * us" — the difference between two completely different next actions for the agent, which the
+ * no-session message could not tell apart before. See no-session-diagnosis.ts.
+ *
+ * Kept out of the hot path: `SessionManager.resolve` is synchronous and runs on every tool call, so
+ * the probe refreshes in the background and the resolve path reads a cached answer. A stale answer
+ * is fine here — it is a hint in an error message, not a decision.
+ */
+/** Every candidate port serving a document, in ascending order. Never rejects. */
+export declare function probeDevServers(ports?: readonly number[], probe?: (port: number) => Promise<boolean>): Promise<number[]>;

package/dist/session/dev-server-probe.js

@@ -0,0 +1,52 @@
+/**
+ * Which of the usual dev-server ports have something listening on them.
+ *
+ * The one fact that separates "the app is not running" from "the app is running and never dialled
+ * us" — the difference between two completely different next actions for the agent, which the
+ * no-session message could not tell apart before. See no-session-diagnosis.ts.
+ *
+ * Kept out of the hot path: `SessionManager.resolve` is synchronous and runs on every tool call, so
+ * the probe refreshes in the background and the resolve path reads a cached answer. A stale answer
+ * is fine here — it is a hint in an error message, not a decision.
+ */
+import { request } from 'node:http';
+import { DEV_SERVER_PORTS } from '../cli/cli-port.js';
+import { looksLikeDevServer } from './looks-like-dev-server.js';
+/** Give up fast: an HTTP answer from localhost either lands quickly or nothing is there. */
+const HTTP_PROBE_TIMEOUT_MS = 400;
+/**
+ * `localhost`, not `127.0.0.1` — so BOTH address families are tried.
+ *
+ * Measured: a plain `vite --port 4311` on this machine listens on `[::1]` only, and a probe pinned to
+ * the IPv4 loopback cannot see it. The old TCP probe had the same blind spot, which meant the
+ * diagnostic could miss the very dev server it exists to find while still reporting an unrelated
+ * service that happens to bind both stacks (macOS AirPlay does).
+ */
+const PROBE_HOST = 'localhost';
+/**
+ * Does this port serve a DOCUMENT — i.e. is it a dev server rather than merely something listening?
+ *
+ * A bare TCP connect reported macOS ControlCenter (AirPlay Receiver, on by default on every Mac,
+ * port 5000) as the user's dev server. See looks-like-dev-server for what it actually answers and
+ * why "a socket accepted" is the wrong question.
+ */
+function servesDocument(port, host = PROBE_HOST) {
+    return new Promise((resolve) => {
+        const req = request({ host, port, path: '/', method: 'GET', timeout: HTTP_PROBE_TIMEOUT_MS }, (res) => {
+            const answer = looksLikeDevServer(res.statusCode ?? 0, res.headers['content-type']);
+            res.resume(); // drain, so the socket closes rather than lingering
+            resolve(answer);
+        });
+        req.once('timeout', () => {
+            req.destroy();
+            resolve(false);
+        });
+        req.once('error', () => resolve(false));
+        req.end();
+    });
+}
+/** Every candidate port serving a document, in ascending order. Never rejects. */
+export async function probeDevServers(ports = [...DEV_SERVER_PORTS], probe = (p) => servesDocument(p)) {
+    const results = await Promise.all(ports.map((p) => probe(p).then((up) => (up ? p : null))));
+    return results.filter((p) => p !== null).sort((a, b) => a - b);
+}

package/dist/session/last-act.d.ts

@@ -14,18 +14,32 @@
  *    the "this click did nothing" check is unreachable on the ordinary act-then-observe flow: an
  *    empty-window test is a statement about the PAGE, and no real app has a quiet page.
  */
-export interface ActEffect {
+interface ActEffect {
     action?: string | undefined;
     /** DOM mutations inside the acted element's own subtree. Undefined means nobody measured. */
     mutatedWithin?: number | undefined;
 }
 export declare class LastAct {
     #private;
-    markCursor(cursor: number): void;
+    /**
+     * Record an action that ACTUALLY DISPATCHED — cursor and effect together, never one without the
+     * other.
+     *
+     * It used to be two setters called BEFORE the ref was resolved, so a refused act (stale ref, a
+     * disabled control, a paused page) left a cursor and an empty effect standing. The next observe
+     * saw a cursor inside its window, asked for the effect, found `mutatedWithin: undefined` over a
+     * quiet window and reported "the click was dispatched and the page settled … the target does not
+     * react" — about a click nobody dispatched, blaming a control that was fine, on exactly the
+     * re-query-and-retry path the stale-ref message sends the agent down.
+     *
+     * Marking only on the success path is what makes that unrepeatable: a failure mode added later
+     * cannot forget to clean up state that was never written.
+     */
+    markActed(cursor: number, action: string | undefined, mutatedWithin: number | undefined): void;
     cursor(): number | undefined;
     markSource(source: string | undefined): void;
     source(): string | undefined;
-    markEffect(action: string | undefined, mutatedWithin: number | undefined): void;
     /** Empty when nothing has acted — callers then fall back to checks that need no action context. */
     effect(): ActEffect;
 }
+export {};

package/dist/session/last-act.js

@@ -2,8 +2,23 @@ export class LastAct {
     #cursor;
     #source;
     #effect;
-    markCursor(cursor) {
+    /**
+     * Record an action that ACTUALLY DISPATCHED — cursor and effect together, never one without the
+     * other.
+     *
+     * It used to be two setters called BEFORE the ref was resolved, so a refused act (stale ref, a
+     * disabled control, a paused page) left a cursor and an empty effect standing. The next observe
+     * saw a cursor inside its window, asked for the effect, found `mutatedWithin: undefined` over a
+     * quiet window and reported "the click was dispatched and the page settled … the target does not
+     * react" — about a click nobody dispatched, blaming a control that was fine, on exactly the
+     * re-query-and-retry path the stale-ref message sends the agent down.
+     *
+     * Marking only on the success path is what makes that unrepeatable: a failure mode added later
+     * cannot forget to clean up state that was never written.
+     */
+    markActed(cursor, action, mutatedWithin) {
         this.#cursor = cursor;
+        this.#effect = { action, mutatedWithin };
     }
     cursor() {
         return this.#cursor;
@@ -14,9 +29,6 @@ export class LastAct {
     source() {
         return this.#source;
     }
-    markEffect(action, mutatedWithin) {
-        this.#effect = { action, mutatedWithin };
-    }
     /** Empty when nothing has acted — callers then fall back to checks that need no action context. */
     effect() {
         return this.#effect ?? {};

package/dist/session/live-control-tools.js

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { noteEmptyRead } from '../tools/observed-nothing.js';
 import { AGENT_ASK_NOTICE, AGENT_WAITING_NOTICE, PresenterTone, SessionState, } from '@reticlehq/core';
 import { ReticleTool } from '../tools/tool-names.js';
 import { sessionIdShape } from '../tools/tool-kit.js';
@@ -95,7 +96,11 @@ export const LIVE_CONTROL_TOOLS = [
         outputSchema: { messages: z.array(z.unknown()) },
         handler: (deps, args) => {
             const session = deps.sessions.resolve(asString(args['sessionId']));
-            return Promise.resolve({ messages: session.drainInbox() });
+            // An empty inbox and a panel that is not wired both return `[]`. The first means the human has
+            // said nothing; the second means an agent is waiting on a channel that does not exist.
+            return Promise.resolve(noteEmptyRead({ messages: session.drainInbox() }, 'messages', {
+                noun: 'messages from the human since the last poll',
+            }));
         },
     },
     {
@@ -135,7 +140,7 @@ export const LIVE_CONTROL_TOOLS = [
                     session.pushNarration(`✓ fixed: ${mark.note}`);
                 }
             }
-            const source = args['all'] === true ? session.allMarks() : session.pendingMarks();
+            const source = true === args['all'] ? session.allMarks() : session.pendingMarks();
             const marks = source.map((m) => ({ ...m, fix: buildFixHint(m) }));
             const out = {
                 marks,

package/dist/session/live-control.js

@@ -27,7 +27,7 @@ export class LiveControl {
     /** Queue a human note. Empty/whitespace-only text is ignored so a stray enter cannot spam the agent. */
     push(text, t) {
         const trimmed = text.trim();
-        if (trimmed.length === 0)
+        if (0 === trimmed.length)
             return;
         this.#inbox.push({ text: trimmed, t });
     }

package/dist/session/looks-like-dev-server.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Is the thing on this port a DEV SERVER serving the app, or just something on a port?
+ *
+ * The probe used to answer "something accepted a TCP connection", which on macOS means every Mac
+ * reports Apple's AirPlay Receiver on port 5000 as the user's dev server. Reproduced here: it
+ * answers `HTTP/1.1 403 Forbidden`, `Server: AirTunes/950.7.1`, no body. The agent was then told
+ * "something IS listening on port 5000 and this project is wired for Reticle" while the app was on
+ * 3100 — a diagnostic confidently naming a service with nothing to do with the project.
+ *
+ * A dev server serving an app answers `GET /` with a document. That is the whole test. A false
+ * negative costs a less specific message; a false positive costs trust in every diagnostic Reticle
+ * prints, which is far more expensive.
+ */
+export declare function looksLikeDevServer(status: number, contentType: string | undefined): boolean;

package/dist/session/looks-like-dev-server.js

@@ -0,0 +1,25 @@
+/**
+ * Is the thing on this port a DEV SERVER serving the app, or just something on a port?
+ *
+ * The probe used to answer "something accepted a TCP connection", which on macOS means every Mac
+ * reports Apple's AirPlay Receiver on port 5000 as the user's dev server. Reproduced here: it
+ * answers `HTTP/1.1 403 Forbidden`, `Server: AirTunes/950.7.1`, no body. The agent was then told
+ * "something IS listening on port 5000 and this project is wired for Reticle" while the app was on
+ * 3100 — a diagnostic confidently naming a service with nothing to do with the project.
+ *
+ * A dev server serving an app answers `GET /` with a document. That is the whole test. A false
+ * negative costs a less specific message; a false positive costs trust in every diagnostic Reticle
+ * prints, which is far more expensive.
+ */
+/** Statuses that mean "I will not serve you", which no local dev server does for its own app root. */
+const REFUSES = new Set([401, 403, 407]);
+export function looksLikeDevServer(status, contentType) {
+    if (REFUSES.has(status))
+        return false;
+    // A redirect IS a server routing: a dev server on a base path answers `/` with one.
+    if (status >= 300 && status < 400)
+        return true;
+    // Otherwise it has to be serving a document. A 404 that renders HTML is still a dev server — the
+    // server is there, only the route is missing.
+    return contentType !== undefined && contentType.toLowerCase().includes('text/html');
+}