@reticlehq/server 2.2.0 → 2.3.0

package/dist/project/project-tools.js

@@ -2,7 +2,8 @@ import { z } from 'zod';
 import { ProjectReadError, RunKind, RunStatus } from '@reticlehq/core';
 import { ReticleTool } from '../tools/tool-names.js';
 import { sessionIdShape } from '../tools/tool-kit.js';
-import { asString } from '../tools/tools-helpers.js';
+import { asNumber, asString } from '../tools/tools-helpers.js';
+import { fetchProjectRegressionFromCloud, resolveCloudConfig } from '../cloud/cloud-sync.js';
 import { RunStore } from '../runs/run-store.js';
 import { diffRuns as diffVerificationRuns, } from '../runs/run-diff.js';
 const REGRESSION_STATUSES = new Set([
@@ -28,7 +29,28 @@ function numericDelta(before, after) {
         return undefined;
     return (after ?? 0) - (before ?? 0);
 }
+/**
+ * Pull the team's server-side regression memory when logged in. This is what keeps a context-lost or
+ * brand-new agent (whose local project.json may be empty) oriented: the same reticle_project call folds in
+ * "what's broken vs before" from the cloud. Absent creds / unreachable → undefined (agent stays local).
+ */
+async function cloudRegression(deps, sessionId) {
+    const config = resolveCloudConfig(process.env);
+    if (config === null)
+        return undefined;
+    let projectId;
+    try {
+        projectId = deps.sessions.resolve(sessionId).projectId;
+    }
+    catch {
+        projectId = undefined;
+    }
+    const report = await fetchProjectRegressionFromCloud(config, projectId, (url, init) => fetch(url, init));
+    return report ?? undefined;
+}
 /** The two most-recent runs for `name`, oldest-first, or undefined if there are fewer than two. */
+/** Runs returned when the caller does not ask for a specific count. */
+const DEFAULT_RUN_LIMIT = 25;
 function lastTwoFor(runs, name) {
     const matching = runs.filter((r) => r.name === name);
     const n = matching.length;
@@ -62,29 +84,54 @@ async function lastTwoRunArtifacts(deps) {
 export const PROJECT_TOOLS = [
     {
         name: ReticleTool.PROJECT,
-        description: 'Read cross-run history from .reticle/project.json — the memory of how past runs behaved. With { name } it also returns the last run for that flow plus a diff-vs-last summary (status change, regressed flag, consoleErrors/driftSteps deltas) so you can answer "did it behave like last time?". Returns { runs, learned?, lastRun?, diff?, runDiff? } — `diff` is the lightweight status/console/drift delta vs the previous run of that NAME; `runDiff` is the per-flow duration/status delta between the two most-recent full verification artifacts ("step 3: 412ms -> 987ms (+140%), +2 requests"). Or { error, reason } when no/invalid history exists.',
+        description: 'Read cross-run history from .reticle/project.json — the memory of how past runs behaved. With { name } it also returns the last run for that flow plus a diff-vs-last summary (status change, regressed flag, consoleErrors/driftSteps deltas) so you can answer "did it behave like last time?". `diff` is the lightweight status/console/drift delta vs the previous run of that NAME; `runDiff` is the per-flow duration/status delta between the two most-recent full verification artifacts ("step 3: 412ms -> 987ms (+140%), +2 requests"). When logged in to Reticle Cloud, also returns `cloud`: the team\'s server-side regression report (broken/changed flows vs before) — the durable memory a fresh or context-lost agent can rely on even when local history is empty. Returns { runs, learned?, lastRun?, diff?, runDiff?, cloud? } or { error, reason, cloud? }.',
         inputSchema: {
             name: z.string().optional().describe('Filter runs by this name. Omit to return all runs.'),
+            limit: z
+                .number()
+                .optional()
+                .describe('Most-recent N runs to return. Defaults to 25 — the full history is unbounded and grows with every run (measured at ~20KB / ~5,000 tokens on a modest project), which is a large slice of an agent context for data it mostly does not read. `totalRuns` always reports the true count, so a cap is never silent.'),
             ...sessionIdShape,
         },
         outputSchema: {
             runs: z.array(z.unknown()),
+            totalRuns: z
+                .number()
+                .optional()
+                .describe('How many runs exist in total. Compare against runs.length to see if it was capped.'),
             diff: z.unknown().optional(),
             runDiff: z.unknown().optional(),
+            cloud: z.unknown().optional(),
         },
         handler: async (deps, args) => {
+            const cloud = await cloudRegression(deps, asString(args['sessionId']));
+            const withCloud = (obj) => cloud === undefined ? obj : { ...obj, cloud };
             const read = await deps.project.read();
             if (!read.ok) {
-                return {
+                return withCloud({
                     error: read.reason === ProjectReadError.MISSING
                         ? 'no .reticle/project.json yet — run a flow (reticle_flow_replay) or reticle_run_record first'
                         : '.reticle/project.json is malformed — it will self-heal on the next recorded run',
                     reason: read.reason,
-                };
+                });
             }
             const name = asString(args['name']);
+            // The most recent N, in the order they happened. The history is append-only and unbounded —
+            // measured at ~20KB (~5,000 tokens) across 176 runs on this repo — and an agent asking "how
+            // did this behave before" wants the recent past, not every run ever recorded. `totalRuns`
+            // travels with it so the cap is never silent, per the repo's no-silent-caps rule.
+            //
+            // Order is left alone deliberately. Reversing to newest-first was tried and reverted: it read
+            // better but broke an existing contract for no reason the bound required, and a caller relying
+            // on chronological order would have been silently handed the reverse.
+            const cap = asNumber(args['limit']) ?? DEFAULT_RUN_LIMIT;
+            const recent = (runs) => runs.slice(-cap);
             if (name === undefined) {
-                return { runs: read.file.runs, learned: read.file.learned };
+                return withCloud({
+                    runs: recent(read.file.runs),
+                    totalRuns: read.file.runs.length,
+                    learned: read.file.learned,
+                });
             }
             const lastRun = await deps.project.lastRun(name);
             const pair = lastTwoFor(read.file.runs, name);
@@ -94,13 +141,15 @@ export const PROJECT_TOOLS = [
             // last time?" from project.json, while `runDiff` answers "what changed between the last two full
             // verification runs?" from .reticle/runs. Best-effort: no artifacts simply means no runDiff.
             const runDiff = await lastTwoRunArtifacts(deps);
-            return {
-                runs: read.file.runs.filter((r) => r.name === name),
+            const forName = read.file.runs.filter((r) => r.name === name);
+            return withCloud({
+                runs: recent(forName),
+                totalRuns: forName.length,
                 learned: read.file.learned,
                 lastRun,
                 ...(pair !== undefined ? { diff: diffRuns(pair[0], pair[1]) } : {}),
                 ...(runDiff === undefined ? {} : { runDiff }),
-            };
+            });
         },
     },
     {
@@ -133,4 +182,3 @@ export const PROJECT_TOOLS = [
         },
     },
 ];
-//# sourceMappingURL=project-tools.js.map

package/dist/project/reticle-dir.d.ts

@@ -83,4 +83,3 @@ export type ReadContractResult = {
 };
 /** Never throws. Missing → MISSING. Bad JSON / failed schema → MALFORMED. */
 export declare function readContract(fs: FileSystemPort, root: string): Promise<ReadContractResult>;
-//# sourceMappingURL=reticle-dir.d.ts.map

package/dist/project/reticle-dir.js

@@ -167,4 +167,3 @@ export async function readContract(fs, root) {
         return { ok: false, reason: ContractReadError.MALFORMED };
     return { ok: true, capabilities: result.data.capabilities, generatedAt: result.data.generatedAt };
 }
-//# sourceMappingURL=reticle-dir.js.map

package/dist/runs/build-verification-run.d.ts

@@ -27,4 +27,3 @@ export declare function computeVerdict(input: VerificationRunInput): RunVerdict;
  * input can never escape as an "artifact".
  */
 export declare function buildVerificationRun(input: VerificationRunInput, now: () => number): ReticleVerificationRun;
-//# sourceMappingURL=build-verification-run.d.ts.map

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

@@ -68,4 +68,3 @@ export function buildVerificationRun(input, now) {
     };
     return redactForProfile(ReticleVerificationRunSchema.parse(run));
 }
-//# sourceMappingURL=build-verification-run.js.map

package/dist/runs/profile-redact.d.ts

@@ -13,4 +13,3 @@ export declare const REDACTED = "[redacted:prod-preview]";
  * the repair block (source-naming) is dropped and stateAssertion values are redacted.
  */
 export declare function redactForProfile(run: ReticleVerificationRun): ReticleVerificationRun;
-//# sourceMappingURL=profile-redact.d.ts.map

package/dist/runs/profile-redact.js

@@ -29,4 +29,3 @@ export function redactForProfile(run) {
     void repair; // intentionally dropped — fix instructions name source files
     return { ...rest, evidence };
 }
-//# sourceMappingURL=profile-redact.js.map

package/dist/runs/render-report.d.ts

@@ -6,4 +6,3 @@
 import { type ReticleVerificationRun } from '@reticlehq/core';
 /** Render the run as a plain-text report. Sections with no content are omitted. */
 export declare function renderRunReport(run: ReticleVerificationRun): string;
-//# sourceMappingURL=render-report.d.ts.map

package/dist/runs/render-report.js

@@ -67,4 +67,3 @@ export function renderRunReport(run) {
     }
     return out.join('\n');
 }
-//# sourceMappingURL=render-report.js.map

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

@@ -14,4 +14,3 @@ export declare function deviationHeadline(deviation: unknown): string | undefine
 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[];
-//# sourceMappingURL=repair-prompt.d.ts.map

package/dist/runs/repair-prompt.js

@@ -69,4 +69,3 @@ export function buildRepairPacket(replay) {
 export function buildRepairPackets(replays) {
     return replays.map(buildRepairPacket).filter((p) => p !== undefined);
 }
-//# sourceMappingURL=repair-prompt.js.map

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

@@ -9,4 +9,3 @@ import { ReplayStatus, RunFlowStatus, type FlowReplayResult, type RunFlowResult
 export declare function runFlowStatusOf(status: ReplayStatus): RunFlowStatus;
 /** Map one replay (plus its measured duration) into a RunFlowResult for the artifact's flows[]. */
 export declare function mapReplayToFlowResult(replay: FlowReplayResult, durationMs: number): RunFlowResult;
-//# sourceMappingURL=replay-mapping.d.ts.map

package/dist/runs/replay-mapping.js

@@ -32,4 +32,3 @@ export function mapReplayToFlowResult(replay, durationMs) {
         ...(failureReason !== undefined ? { failureReason } : {}),
     };
 }
-//# sourceMappingURL=replay-mapping.js.map

package/dist/runs/reticle-runner.d.ts

@@ -45,4 +45,3 @@ export declare class ReticleRunner {
      */
     verify(opts: VerifyOptions): Promise<ReticleVerificationRun>;
 }
-//# sourceMappingURL=reticle-runner.d.ts.map

package/dist/runs/reticle-runner.js

@@ -9,6 +9,7 @@
  * top of this — the orchestration and the verdict live here so the MCP path and the API produce the
  * same artifact byte-for-byte.
  */
+import { reportRunTelemetry } from '../telemetry/run-telemetry.js';
 import { buildVerificationRun } from './build-verification-run.js';
 import { mapReplayToFlowResult } from './replay-mapping.js';
 import { buildRepairPackets } from './repair-prompt.js';
@@ -50,7 +51,8 @@ export class ReticleRunner {
             evidence: { consoleErrors: [], networkAnomalies: [], stateAssertions: [], timeline: [] },
             ...(failurePackets.length > 0 ? { repair: { failurePackets } } : {}),
         };
-        return buildVerificationRun(input, () => this.#port.now());
+        const run = buildVerificationRun(input, () => this.#port.now());
+        reportRunTelemetry(run);
+        return run;
     }
 }
-//# sourceMappingURL=reticle-runner.js.map

package/dist/runs/risk-classify.d.ts

@@ -24,4 +24,3 @@ export declare function classifyChangedFiles(files: ReadonlyArray<ChangedFileInp
  * severity and a gated flag driven by the policy. This is what the verdict counts as blocking.
  */
 export declare function buildRisks(changedFiles: ReadonlyArray<RunChangedFile>, policy?: RiskPolicy): RunRisk[];
-//# sourceMappingURL=risk-classify.d.ts.map

package/dist/runs/risk-classify.js

@@ -73,4 +73,3 @@ export function buildRisks(changedFiles, policy = {}) {
     }
     return risks;
 }
-//# sourceMappingURL=risk-classify.js.map

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

@@ -31,4 +31,3 @@ export declare const DEFAULT_NOISE_FLOOR_PCT = 10;
  * console diffs land once runs persist per-step detail.
  */
 export declare function diffRuns(before: ReticleVerificationRun, after: ReticleVerificationRun, noiseFloorPct?: number): RunDiff;
-//# sourceMappingURL=run-diff.d.ts.map

package/dist/runs/run-diff.js

@@ -68,4 +68,3 @@ export function diffRuns(before, after, noiseFloorPct = DEFAULT_NOISE_FLOOR_PCT)
     };
     return { ...base, headline: headlineFor(base) };
 }
-//# sourceMappingURL=run-diff.js.map

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

@@ -42,4 +42,3 @@ export declare class RunStore {
     latestTwo(): Promise<[ReticleVerificationRun, ReticleVerificationRun] | undefined>;
 }
 export {};
-//# sourceMappingURL=run-store.d.ts.map

package/dist/runs/run-store.js

@@ -135,4 +135,3 @@ export class RunStore {
         return [previous, current];
     }
 }
-//# sourceMappingURL=run-store.js.map

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

@@ -7,4 +7,3 @@ import type { ToolDef } from '../tools/tools.js';
  * reticleRoot (it is stateless), so this needs no new ToolDeps wiring.
  */
 export declare const RUN_TOOLS: ToolDef[];
-//# sourceMappingURL=run-tools.d.ts.map

package/dist/runs/run-tools.js

@@ -79,4 +79,3 @@ export const RUN_TOOLS = [
         },
     },
 ];
-//# sourceMappingURL=run-tools.js.map

package/dist/runs/runner-port.d.ts

@@ -11,4 +11,3 @@ import type { RunnerPort } from './reticle-runner.js';
 export declare function defaultRunId(): RunId;
 /** Wire a RunnerPort to the live session. Pass sessionId to disambiguate when several tabs are open. */
 export declare function createRunnerPort(deps: ToolDeps, sessionId?: string): RunnerPort;
-//# sourceMappingURL=runner-port.d.ts.map

package/dist/runs/runner-port.js

@@ -20,4 +20,3 @@ export function createRunnerPort(deps, sessionId) {
         newRunId: defaultRunId,
     };
 }
-//# sourceMappingURL=runner-port.js.map

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

@@ -0,0 +1,23 @@
+/**
+ * Turn an MCP verification (a `reticle_flow_verify` suite run) into a first-class ReticleVerificationRun:
+ * assemble the artifact from the already-computed replays, persist it to .reticle/runs/ (so
+ * `reticle_run_export` and CI can read it), and — when logged in (cloud creds set) — best-effort push it
+ * to the cloud's `POST /v1/runs` so the team's dashboard Runs tab shows what the agent just verified.
+ *
+ * This is the artifact tier that maps to the dashboard's "Runs" (the OEM/CI-consumable verdict); the
+ * lighter per-flow RunRecord that feeds regression memory is synced separately in flow-replay-run.ts.
+ * Both are best-effort + opt-in: no creds → the artifact still lands on disk, nothing leaves the machine.
+ */
+import { type FlowReplayResult } from '@reticlehq/core';
+import type { ToolDeps } from '../tools/tools.js';
+/** A replay plus the wall-clock time it took — the shape the verify handler already collects. */
+export interface TimedReplay {
+    replay: FlowReplayResult;
+    durationMs: number;
+}
+/**
+ * Persist the suite's run artifact and best-effort mirror it to the cloud. Never throws into the verify
+ * tool — a disk or network failure is logged and swallowed so the verdict the agent asked for is
+ * unaffected. Returns the runId (for logging/tests); undefined if nothing was produced (empty suite).
+ */
+export declare function persistAndSyncVerificationRun(deps: ToolDeps, timed: TimedReplay[], projectId: string | undefined): Promise<string | undefined>;

package/dist/runs/verification-sync.js

@@ -0,0 +1,66 @@
+/**
+ * Turn an MCP verification (a `reticle_flow_verify` suite run) into a first-class ReticleVerificationRun:
+ * assemble the artifact from the already-computed replays, persist it to .reticle/runs/ (so
+ * `reticle_run_export` and CI can read it), and — when logged in (cloud creds set) — best-effort push it
+ * to the cloud's `POST /v1/runs` so the team's dashboard Runs tab shows what the agent just verified.
+ *
+ * This is the artifact tier that maps to the dashboard's "Runs" (the OEM/CI-consumable verdict); the
+ * lighter per-flow RunRecord that feeds regression memory is synced separately in flow-replay-run.ts.
+ * Both are best-effort + opt-in: no creds → the artifact still lands on disk, nothing leaves the machine.
+ */
+import { RunAgentKind, RunFramework, RunProfile, RunTrigger, } from '@reticlehq/core';
+import { homedir } from 'node:os';
+import { buildVerificationRun } from './build-verification-run.js';
+import { mapReplayToFlowResult } from './replay-mapping.js';
+import { defaultRunId } from './runner-port.js';
+import { RunStore } from './run-store.js';
+import { syncRunToCloud, SyncOutcome } from '../cloud/cloud-sync.js';
+import { resolveProjectCloud } from '../cloud/cloud-config.js';
+import { log } from '../log.js';
+/** Assemble the ReticleVerificationRun artifact for a verify suite (pure — no IO). */
+function assembleRun(deps, timed, projectId) {
+    const flows = timed.map((t) => mapReplayToFlowResult(t.replay, t.durationMs));
+    const input = {
+        runId: defaultRunId(),
+        durationMs: flows.reduce((sum, f) => sum + f.durationMs, 0),
+        profile: RunProfile.DEV,
+        project: { name: projectId ?? 'reticle', framework: RunFramework.OTHER },
+        agent: { id: 'reticle-mcp', kind: RunAgentKind.CODING_AGENT },
+        trigger: { kind: RunTrigger.MANUAL },
+        changedFiles: [],
+        flows,
+        checks: [],
+        risks: [],
+        evidence: { consoleErrors: [], networkAnomalies: [], stateAssertions: [], timeline: [] },
+    };
+    return buildVerificationRun(input, () => deps.now());
+}
+/**
+ * Persist the suite's run artifact and best-effort mirror it to the cloud. Never throws into the verify
+ * tool — a disk or network failure is logged and swallowed so the verdict the agent asked for is
+ * 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)
+        return undefined;
+    let run;
+    try {
+        run = assembleRun(deps, timed, projectId);
+        await new RunStore(deps.fs, deps.reticleRoot).write(run);
+    }
+    catch (error) {
+        log('verification-run-persist-failed', {
+            error: error instanceof Error ? error.message : String(error),
+        });
+        return undefined;
+    }
+    // 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)
+        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) {
+        log('cloud-run-sync-failed', { runId: run.runId, status: result.status, error: result.error });
+    }
+    return run.runId;
+}

package/dist/runs/verify-http.d.ts

@@ -31,4 +31,3 @@ export interface VerifyHttpResponse {
  * and returns a status + body. No sockets, no globals — a test calls it directly.
  */
 export declare function handleVerifyRequest(req: VerifyHttpRequest, runner: ReticleRunner, expectedToken: string, persist?: (run: ReticleVerificationRun) => Promise<void>): Promise<VerifyHttpResponse>;
-//# sourceMappingURL=verify-http.d.ts.map

package/dist/runs/verify-http.js

@@ -99,4 +99,3 @@ export async function handleVerifyRequest(req, runner, expectedToken, persist) {
         return { status: 500, body: { error: 'verify failed' } };
     }
 }
-//# sourceMappingURL=verify-http.js.map

package/dist/runs/verify-server.d.ts

@@ -23,4 +23,3 @@ export declare function startVerifyServer(opts: VerifyServerOptions, port: numbe
     server: http.Server;
     port: number;
 }>;
-//# sourceMappingURL=verify-server.d.ts.map

package/dist/runs/verify-server.js

@@ -96,4 +96,3 @@ export function startVerifyServer(opts, port) {
         });
     });
 }
-//# sourceMappingURL=verify-server.js.map

package/dist/server-version.d.ts

@@ -5,4 +5,3 @@ export declare const SERVER_VERSION: string;
  * drift. Self-update installs THIS (never `@reticlehq/core`, which is schema-only and has no bin).
  */
 export declare const RETICLE_NPM_PACKAGE: string;
-//# sourceMappingURL=server-version.d.ts.map

package/dist/server-version.js

@@ -7,4 +7,3 @@ export const SERVER_VERSION = _pkg.version;
  * drift. Self-update installs THIS (never `@reticlehq/core`, which is schema-only and has no bin).
  */
 export const RETICLE_NPM_PACKAGE = _pkg.name;
-//# sourceMappingURL=server-version.js.map

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

@@ -0,0 +1,35 @@
+/**
+ * Turn a bare command timeout into something the reader can act on.
+ *
+ * The default message — `command 'snapshot' timed out after 8000ms` — is eight seconds of silence
+ * followed by a fact with no cause. For a Tauri app the cause is usually not a bug in the app: its
+ * window was hidden before the webview had ever been PRESENTED, and a webview that has never been
+ * presented never loads its page. The session stays connected, so nothing looks wrong, and the
+ * developer goes hunting through their own code for a fault that is not there.
+ *
+ * This advice previously blamed occlusion — "macOS suspends an occluded or off-Space WKWebView" —
+ * which is false, and was the kind of wrong steer this function exists to prevent. A LOADED Tauri
+ * webview keeps answering while minimized, app-hidden, occluded, and on another Space.
+ *
+ * It then over-corrected: it asserted the hidden-before-load ordering as FACT. But the only evidence
+ * here is `hidden === true` — the ordering is never observed. Measured on a Tauri shell pointed at an
+ * external http origin, whose window nothing ever hid: the message confidently prescribed a fix for a
+ * mistake that had not been made, and two rounds of debugging went into the wrong place. A diagnostic
+ * that names the wrong cause is worse than a bare timeout, because the bare timeout at least sends
+ * the reader looking. So this now reports what is KNOWN and ranks the causes rather than picking one.
+ *
+ * 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 {
+    url: string;
+    /** The page's own last visibility report. */
+    hidden: boolean;
+    /** Reported by the SDK. A URL cannot distinguish a Tauri dev server from a plain localhost app. */
+    runtime?: PageRuntime;
+    /** ms since ANY inbound message from the SDK. Small = the page is demonstrably still running. */
+    lastSeenMs?: number;
+}
+export declare function commandTimeoutMessage(name: string, timeoutMs: number, context: TimeoutContext): string;

package/dist/session/command-timeout.js

@@ -0,0 +1,41 @@
+import { 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
+ * events is executing JavaScript by definition.
+ */
+const RECENTLY_HEARD_MS = 2000;
+const ONE_WAY_ADVICE = 'The page is ALIVE — the SDK last reported to the bridge %MS%ms ago — but it is not answering ' +
+    'commands. A page that is still sending is executing JavaScript, so it is not hung, hidden or ' +
+    'suspended: messages are getting OUT and not back IN. Look at the bridge→page direction (a socket ' +
+    'replaced mid-session, a proxy buffering one way) rather than at your app.';
+const HIDDEN_ADVICE = 'The page last reported itself hidden, and this is a WKWebView (Tauri) window, so the webview is ' +
+    'most likely not running the page at all. Two known causes, commonest first: (1) the window was ' +
+    'hidden BEFORE its first page load — a webview that has never been presented never loads, so hide ' +
+    'it from `on_page_load` instead of `setup` (see `reticle_tauri::on_page_load`, which does this for ' +
+    'RETICLE_HEADLESS=1); once the page HAS loaded, hiding it is safe. (2) the window never presented ' +
+    'for another reason — check that it is declared with a visible size and that the page URL actually ' +
+    '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')
+        return true;
+    // A `tauri://` origin is unambiguous even before the first health report lands.
+    if (context.runtime !== undefined)
+        return false;
+    return isOpaqueOrigin(context.url) && context.url.startsWith('tauri:');
+}
+export function commandTimeoutMessage(name, timeoutMs, context) {
+    const base = `command '${name}' timed out after ${String(timeoutMs)}ms`;
+    // Checked FIRST, and it overrides the visibility story: a page that was heard from moments ago is
+    // executing JavaScript, so "hidden, hung or never presented" cannot be the explanation whatever
+    // `hidden` says. Deduced from the invariant, not from a measured incident — the Tauri case that
+    // prompted it turned out to go fully silent instead, which this branch correctly does not claim.
+    const heard = context.lastSeenMs;
+    if (heard !== undefined && heard <= RECENTLY_HEARD_MS) {
+        return `${base}. ${ONE_WAY_ADVICE.replace('%MS%', String(heard))}`;
+    }
+    if (!context.hidden || !isWebKitDesktop(context))
+        return base;
+    return `${base}. ${HIDDEN_ADVICE}`;
+}

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

@@ -9,9 +9,9 @@ interface ControlEnvelope {
 }
 /**
  * Agent-readable hint returned when an action is refused mid-pause. Named, not free — the agent's
- * recovery path (address the guidance, then reticle_resume) lives here in exactly one place.
+ * 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_resume (or wait for the human to resume).";
+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).";
 /** Shape returned by the short-circuit when an action tool refuses while paused. */
 interface PausedResult {
     paused: true;
@@ -54,4 +54,3 @@ export declare function pausedShortCircuit(session: Session): PausedResult | und
  */
 export declare function withControl<T extends object>(session: Session, result: T): T & ControlSpread;
 export {};
-//# sourceMappingURL=control-envelope.d.ts.map

package/dist/session/control-envelope.js

@@ -2,9 +2,9 @@ import { SessionState } from '@reticlehq/core';
 import { z } from 'zod';
 /**
  * Agent-readable hint returned when an action is refused mid-pause. Named, not free — the agent's
- * recovery path (address the guidance, then reticle_resume) lives here in exactly one place.
+ * 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_resume (or wait for the human to resume).';
+export const PAUSE_HINT = 'Paused by the human. Address the guidance, then call reticle_session{action:"resume"} (or wait for the human to resume).';
 /**
  * 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
@@ -53,4 +53,3 @@ export function withControl(session, result) {
     const control = buildControlEnvelope(session);
     return control === undefined ? result : { ...result, control };
 }
-//# sourceMappingURL=control-envelope.js.map

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

@@ -0,0 +1,31 @@
+/**
+ * What the most recent action was, kept so a LATER tool call can judge the window it opened.
+ *
+ * Reticle's act and observe tools are separate calls by design — act returns a cursor immediately and
+ * the agent decides when to look. That split means the tool doing the judging holds none of the facts
+ * the tool doing the acting measured, and every honesty check that needs both has to bridge the gap
+ * somewhere. This is that somewhere.
+ *
+ *  - **cursor** — the evaluation floor for wait_for/assert, so a signal buffered BEFORE the act can
+ *    never fake a later pass.
+ *  - **source** — where the acted control is written, for failures that have no element left to point
+ *    at because the action unmounted it.
+ *  - **action + mutatedWithin** — what was done and how much changed inside the target. Without these
+ *    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 {
+    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;
+    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;
+}

package/dist/session/last-act.js

@@ -0,0 +1,24 @@
+export class LastAct {
+    #cursor;
+    #source;
+    #effect;
+    markCursor(cursor) {
+        this.#cursor = cursor;
+    }
+    cursor() {
+        return this.#cursor;
+    }
+    markSource(source) {
+        this.#source = source;
+    }
+    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.d.ts

@@ -13,4 +13,3 @@ import type { ToolDef } from '../tools/tools.js';
  * elapsed clock at enqueue time.
  */
 export declare const LIVE_CONTROL_TOOLS: ToolDef[];
-//# sourceMappingURL=live-control-tools.d.ts.map

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

@@ -26,7 +26,7 @@ export const LIVE_CONTROL_TOOLS = [
         name: ReticleTool.END_SESSION,
         description: 'End this session for good — use ONLY when the whole task is complete. Sets state "ended" ' +
             '(calm, terminal) and shows the optional `summary` on the panel. If you are just finishing a ' +
-            'turn or waiting on the human, call reticle_yield instead (revivable). Idempotent.',
+            'turn or waiting on the human, call reticle_session{action:"yield"} instead (revivable). Idempotent.',
         inputSchema: { summary: z.string().optional(), ...sessionIdShape },
         outputSchema: { ended: z.boolean(), sessionId: z.string() },
         handler: (deps, args) => {
@@ -43,7 +43,7 @@ export const LIVE_CONTROL_TOOLS = [
             'mode:"waiting" = you are done responding and will continue on their next message. ' +
             'mode:"ask" = you are blocked and need an answer first; put the question in `note` so it shows ' +
             'on the panel. The session is REVIVED automatically on your next tool call, so you never need to ' +
-            'reopen it. Use reticle_end_session instead only when the whole task is truly complete.',
+            'reopen it. Use reticle_session{action:"end"} instead only when the whole task is truly complete.',
         inputSchema: {
             mode: z
                 .enum([PresenterTone.WAITING, PresenterTone.ASK])
@@ -194,6 +194,5 @@ function buildFixHint(m) {
         : m.label !== undefined
             ? `Find the "${m.label}" element`
             : 'Find the flagged element';
-    return `${where} and fix: ${m.note}. Then call reticle_review { resolve: "${m.id}" }.`;
+    return `${where} and fix: ${m.note}. Then call reticle_session { action: "review", resolve: "${m.id}" }.`;
 }
-//# sourceMappingURL=live-control-tools.js.map

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

@@ -35,4 +35,3 @@ export declare class LiveControl {
      */
     nextStateFor(data: HumanControlData): SessionState | undefined;
 }
-//# sourceMappingURL=live-control.d.ts.map