@reticlehq/server 3.7.0 → 3.8.1

package/dist/command/version/sdk-fix.js

@@ -5,32 +5,28 @@
  * because those answers are never actively wrong. When a project directory IS in hand, name the
  * packages actually in package.json and the manager the lockfile implies.
  *
- * Does not import `init/`. The library path must never reach the installer
- * (`library-path-boundary.test.ts`); `reticleDepsOf` lives in `update/` for that reason, and the
- * lockfile → manager map is the same evidence `detectPackageManager` reads, kept here so a HELLO
- * does not load the install plan.
+ * The manager is init's own rule, `detectPackageManager` over `resolveLockfiles`, read through a
+ * declared crossing (`library-path-boundary.test.ts`); a copy kept here had fallen behind it.
  */
 import { join } from 'node:path';
 import { readFileSync } from 'node:fs';
+import { detectPackageManager, PackageManager, resolveLockfiles } from '@reticlehq/init';
 import { reticleDepsOf } from '../../memory/project/reticle-deps.js';
-/** Lockfile / marker → manager, same evidence `init/detect.ts` uses. */
-export const PackageManagerName = {
-    PNPM: 'pnpm',
-    YARN: 'yarn',
-    BUN: 'bun',
-    NPM: 'npm',
-};
+/** init's manager names, under the name this module exports. */
+export const PackageManagerName = PackageManager;
 /** Same package a Vue/Nuxt install gets — never the React kit. */
 const FRAMEWORK_NEUTRAL_SDK = '@reticlehq/browser';
 const PACKAGE_JSON = 'package.json';
 const NODE_MODULES = 'node_modules';
-const LOCKFILE_NAMES = ['pnpm-lock.yaml', 'yarn.lock', 'bun.lockb', 'bun.lock'];
-/** Markers each manager leaves inside `node_modules` — stronger than an uncommitted lockfile. */
-const NODE_MODULES_MARKERS = [
-    ['.modules.yaml', PackageManagerName.PNPM],
-    ['.yarn-state.yml', PackageManagerName.YARN],
-    ['.package-lock.json', PackageManagerName.NPM],
+/** The files init's rule reads, probed one by one because this module is handed a file reader. */
+const LOCKFILE_NAMES = [
+    'pnpm-lock.yaml',
+    'yarn.lock',
+    'bun.lockb',
+    'bun.lock',
+    'package-lock.json',
 ];
+const NODE_MODULES_MARKERS = ['.modules.yaml', '.yarn-state.yml', '.package-lock.json'];
 const INSTALL_FLAGS = {
     [PackageManagerName.PNPM]: ['add', '-D'],
     [PackageManagerName.YARN]: ['add', '-D'],
@@ -42,19 +38,6 @@ function packagesFor(ctx) {
         return ctx.packages;
     return [FRAMEWORK_NEUTRAL_SDK];
 }
-function managerOf(lockfiles, nodeModulesMarkers) {
-    if (lockfiles.has('pnpm-lock.yaml'))
-        return PackageManagerName.PNPM;
-    if (lockfiles.has('yarn.lock'))
-        return PackageManagerName.YARN;
-    if (lockfiles.has('bun.lockb') || lockfiles.has('bun.lock'))
-        return PackageManagerName.BUN;
-    for (const [name, pm] of NODE_MODULES_MARKERS) {
-        if (nodeModulesMarkers.has(name))
-            return pm;
-    }
-    return PackageManagerName.NPM;
-}
 function installLine(pm, pkgs) {
     return `${pm} ${[...INSTALL_FLAGS[pm], ...pkgs].join(' ')}`;
 }
@@ -86,7 +69,7 @@ export function sdkFixContextOf(pkgJson, lockfiles, nodeModulesMarkers = new Set
         return undefined;
     return {
         packages: reticleDepsOf(pkgJson),
-        packageManager: managerOf(lockfiles, nodeModulesMarkers),
+        packageManager: detectPackageManager(lockfiles, nodeModulesMarkers, pkgJson),
     };
 }
 /** Reads a file, or undefined if it is not there / not readable. */
@@ -122,6 +105,8 @@ function present(directory, names, read, extra = '') {
  * `read` is injected so the decision is testable without a filesystem; the daemon uses the default.
  */
 export function sdkFixForDirectory(daemonVersion, directory, read = readTextFile) {
-    const ctx = sdkFixContextOf(parseJson(read(join(directory, PACKAGE_JSON))), present(directory, LOCKFILE_NAMES, read), present(directory, NODE_MODULES_MARKERS.map(([name]) => name), read, NODE_MODULES));
+    const markers = present(directory, NODE_MODULES_MARKERS, read, NODE_MODULES);
+    const exists = (path) => read(path) !== undefined;
+    const ctx = sdkFixContextOf(parseJson(read(join(directory, PACKAGE_JSON))), resolveLockfiles(present(directory, LOCKFILE_NAMES, read), directory, { exists }, markers), markers);
     return resolveSdkFix(daemonVersion, ctx);
 }

package/dist/command/version/version-skew.d.ts

@@ -67,6 +67,8 @@ interface SelfIdentity {
     contract: string;
     contractParts?: ContractParts | undefined;
 }
+/** The one line that converges every piece, after the detailed fix. Not said for one version. */
+export declare const SKEW_CONVERGE: string;
 /**
  * The one sentence to tell the agent, or undefined when the pair agrees.
  *
@@ -94,6 +96,14 @@ export declare function describeSkew(given: PeerIdentity, self: SelfIdentity): s
  * `@reticlehq/react` and told Vue projects to install a React package (#618).
  */
 export declare function sdkFix(daemonVersion: string): string;
+/**
+ * Compare two of our own version strings. Numeric dotted compare, prerelease tags ignored: both
+ * sides are Reticle package versions, so this never sees a range or build metadata. Undefined when
+ * either side does not parse, so the caller can decline to guess a direction.
+ */
+export declare function compareVersions(a: string | undefined, b: string): number | undefined;
+/** True when the page SDK is a minor release or more behind the daemon. A patch is not behind. */
+export declare function sdkIsBehind(sdk: string | undefined, daemon: string): boolean;
 /** The same fact for the person looking at the page, on its overlay. */
 export declare const SDK_BEHIND_NARRATION: (sdk: string, daemon: string) => string;
 /**
@@ -117,11 +127,16 @@ export declare function describeSdkBehind(sdk: string | undefined, daemon: strin
  * contract hashes with the roles unchanged. Nothing the agent can do converges that, so say so and
  * ask for the one thing that does, exactly as the SDK branch already does when the page is stale.
  *
+ * It also branches on the connected pages' SDK versions (#1709). When the daemon is the older half
+ * and every connected page runs that same version, a restart replaces one mismatch with a wider
+ * one: the new daemon and every page. Name the SDK update instead. No pages, or pages already on
+ * the agent's version, still restart the daemon.
+ *
  * Both versions are named by ROLE, not by which side is calling: this is read from both ends — a
  * CLI judging the daemon it attached to, and the daemon judging an agent that announced itself —
  * and the advice depends on which piece is behind, not on who noticed.
  */
-export declare function daemonFix(daemonVersion: string | undefined, agentVersion: string | undefined): string;
+export declare function daemonFix(daemonVersion: string | undefined, agentVersion: string | undefined, pageSdkVersions?: readonly (string | undefined)[]): string;
 /** True when `error` is Playwright's closed-target class — not proof the tab is gone. */
 export declare function isPlaywrightClosedError(error: unknown): boolean;
 /**

package/dist/command/version/version-skew.js

@@ -56,6 +56,9 @@ function namesWeDoNotKnow(peer, self) {
     ].filter((name) => !RETIRED_WIRE_NAMES.includes(name));
     return [...new Set(unknown)].sort();
 }
+/** The one line that converges every piece, after the detailed fix. Not said for one version. */
+export const SKEW_CONVERGE = "To put every piece on one version, update the CLI and the app SDK (`reticle update` in the app's " +
+    'folder does both), then restart the MCP host.';
 /** The fix for two builds of one version. */
 const SAME_VERSION_FIX = 'Both say the same version, so one of them is an older build of it: run `reticle restart`, then ' +
     'reload the page so it loads the SDK the dev server serves now.';
@@ -87,6 +90,7 @@ export function describeSkew(given, self) {
     // One version, two builds (a daemon running code older than its install, a cached page bundle):
     // installing that version again changes nothing, so the fix is the restart and the reload.
     const peer = given.version === self.version ? { ...given, fix: SAME_VERSION_FIX } : given;
+    const converge = given.version === self.version ? '' : ` ${SKEW_CONVERGE}`;
     // Both sides said which names they speak, so compare the names rather than a hash over them.
     if (peer.contractParts !== undefined && self.contractParts !== undefined) {
         const unknown = namesWeDoNotKnow(peer.contractParts, self.contractParts);
@@ -100,14 +104,14 @@ export function describeSkew(given, self) {
             : 'so it was built against a newer contract than this one';
         return (`version skew: ${versionPhrase(peer, self)}, and ${peer.what} speaks names this daemon does ` +
             `not know (${unknown.join(', ')}) — ${why}. ` +
-            `Tools will behave in ways neither side reports. ${peer.fix}`);
+            `Tools will behave in ways neither side reports. ${peer.fix}${converge}`);
     }
     if (peer.contract === undefined) {
         if (peer.version === undefined || peer.version === self.version)
             return undefined;
         return (`version skew: ${versionPhrase(peer, self)}, and it is too old to report which wire contract ` +
             `it speaks. They connect anyway and then disagree about behaviour, which usually surfaces as ` +
-            `a bare -32000 with nothing naming a version. ${peer.fix}`);
+            `a bare -32000 with nothing naming a version. ${peer.fix}${converge}`);
     }
     /*
      * A fingerprint alone cannot tell an ADDITION from a RENAME, so this sentence must not claim it can.
@@ -125,7 +129,7 @@ export function describeSkew(given, self) {
     return (`version skew: ${versionPhrase(peer, self)}, and they were built against different wire ` +
         `contracts (${peer.contract} vs ${self.contract}). ${peer.what} is too old to say WHICH names ` +
         `it speaks, so this cannot tell an added name — which breaks nothing — from a renamed one, ` +
-        `which breaks the call that uses it. Update it and the question goes away. ${peer.fix}`);
+        `which breaks the call that uses it. Update it and the question goes away. ${peer.fix}${converge}`);
 }
 /**
  * The fix line for a page whose SDK disagrees with this daemon, with no project to read.
@@ -143,7 +147,7 @@ export function sdkFix(daemonVersion) {
  * sides are Reticle package versions, so this never sees a range or build metadata. Undefined when
  * either side does not parse, so the caller can decline to guess a direction.
  */
-function compareVersions(a, b) {
+export function compareVersions(a, b) {
     const parts = (v) => {
         const head = v.split('-')[0];
         if (head === undefined)
@@ -164,6 +168,15 @@ function compareVersions(a, b) {
     }
     return 0;
 }
+/** True when the page SDK is a minor release or more behind the daemon. A patch is not behind. */
+export function sdkIsBehind(sdk, daemon) {
+    const minorOf = (v) => v.split('-')[0]?.split('.').slice(0, 2).join('.') ?? v;
+    if (sdk === undefined) {
+        return false;
+    }
+    const order = compareVersions(minorOf(sdk), minorOf(daemon));
+    return order !== undefined && order < 0;
+}
 /** The same fact for the person looking at the page, on its overlay. */
 export const SDK_BEHIND_NARRATION = (sdk, daemon) => `This app runs Reticle SDK ${sdk}, older than Reticle ${daemon}. Run \`reticle update\` in the ` +
     "app's folder, then restart its dev server.";
@@ -178,16 +191,61 @@ export const SDK_BEHIND_NARRATION = (sdk, daemon) => `This app runs Reticle SDK
  * because reading the project's manifest is only worth it when the page IS behind.
  */
 export function describeSdkBehind(sdk, daemon, fix) {
-    const minorOf = (v) => v.split('-')[0]?.split('.').slice(0, 2).join('.') ?? v;
-    if (sdk === undefined)
-        return undefined;
-    const order = compareVersions(minorOf(sdk), minorOf(daemon));
-    if (order === undefined || order >= 0)
+    if (sdk === undefined || !sdkIsBehind(sdk, daemon))
         return undefined;
     return (`This page runs Reticle SDK ${sdk}, older than Reticle ${daemon}. It connects and verifies, ` +
         `but everything added since is missing from the page, the overlay's newer controls included. ` +
         fix());
 }
+/**
+ * True when every connected page reported the daemon's SDK version.
+ *
+ * An empty list is not a match: `Array.every` is true for no pages, and no pages is the case that
+ * still restarts the daemon. A page that did not report a version does not match.
+ */
+function pagesMatchDaemon(pageSdkVersions, daemonVersion) {
+    if (0 === pageSdkVersions.length)
+        return false;
+    return pageSdkVersions.every((version) => 0 === compareVersions(version, daemonVersion));
+}
+/**
+ * Pages sit on the older daemon. Restarting it now moves the daemon to the agent and skews every
+ * page (#1709). The SDK update is the step that puts all three on one version.
+ */
+function sdkUpdateConverges(daemonVersion, agentVersion) {
+    return (`The connected pages run SDK ${daemonVersion}, the same version as this daemon. ` +
+        `\`reticle stop\` starts a daemon at ${agentVersion} and skews every page. ` +
+        `${sdkFix(agentVersion)} ` +
+        `That SDK update puts the pages, the daemon and the agent on one version. ` +
+        'Restart the daemon only after the pages load the new SDK.');
+}
+/**
+ * The newest page SDK version that is newer than `agentVersion`, or undefined when no page is.
+ *
+ * The agent's MCP server starts the daemon. When a page is newer than it, `reticle stop` only
+ * starts a daemon at the same old version again, and the advice loops.
+ */
+function newestPageAhead(pageSdkVersions, agentVersion) {
+    let newest;
+    for (const version of pageSdkVersions) {
+        const ahead = compareVersions(version, agentVersion);
+        if (version === undefined || ahead === undefined || ahead <= 0) {
+            continue;
+        }
+        const order = newest === undefined ? 1 : compareVersions(version, newest);
+        if (order !== undefined && order > 0) {
+            newest = version;
+        }
+    }
+    return newest;
+}
+/** The MCP server is the old part: a daemon restart comes back at its version. */
+function mcpServerIsOld(agentVersion, pageVersion) {
+    return (`The connected pages run SDK ${pageVersion}, but the agent's MCP server is ${agentVersion}. ` +
+        `The MCP server starts the daemon, so \`reticle stop\` starts a ${agentVersion} daemon again. ` +
+        'Do not stop the daemon. Tell the human to update the MCP entry (or the Reticle plugin) to ' +
+        `@reticlehq/server@${pageVersion} or later, clear a cached npx copy, and restart the agent.`);
+}
 /**
  * The fix line for another Reticle process that disagrees with the daemon it attached to.
  *
@@ -198,17 +256,33 @@ export function describeSdkBehind(sdk, daemon, fix) {
  * contract hashes with the roles unchanged. Nothing the agent can do converges that, so say so and
  * ask for the one thing that does, exactly as the SDK branch already does when the page is stale.
  *
+ * It also branches on the connected pages' SDK versions (#1709). When the daemon is the older half
+ * and every connected page runs that same version, a restart replaces one mismatch with a wider
+ * one: the new daemon and every page. Name the SDK update instead. No pages, or pages already on
+ * the agent's version, still restart the daemon.
+ *
  * Both versions are named by ROLE, not by which side is calling: this is read from both ends — a
  * CLI judging the daemon it attached to, and the daemon judging an agent that announced itself —
  * and the advice depends on which piece is behind, not on who noticed.
  */
-export function daemonFix(daemonVersion, agentVersion) {
+export function daemonFix(daemonVersion, agentVersion, pageSdkVersions = []) {
     const order = agentVersion === undefined ? undefined : compareVersions(daemonVersion, agentVersion);
     if (order !== undefined && order > 0) {
         return ('The daemon is NEWER than this process, so `reticle stop` will not converge them — it would ' +
             'replace it with another newer daemon and leave the same mismatch. Tell the human to restart ' +
             'the agent so it spawns a current MCP server (or update the package it spawns), then retry.');
     }
+    const pageAhead = agentVersion === undefined ? undefined : newestPageAhead(pageSdkVersions, agentVersion);
+    if (agentVersion !== undefined && pageAhead !== undefined) {
+        return mcpServerIsOld(agentVersion, pageAhead);
+    }
+    if (order !== undefined &&
+        order < 0 &&
+        daemonVersion !== undefined &&
+        agentVersion !== undefined &&
+        pagesMatchDaemon(pageSdkVersions, daemonVersion)) {
+        return sdkUpdateConverges(daemonVersion, agentVersion);
+    }
     return ('A daemon outlives the agents attached to it, so it keeps serving its OWN code until it restarts ' +
         '— anything fixed in the newer package is simply absent. Run `reticle stop` and retry to replace ' +
         'it (other agents on that daemon will need to reconnect).');

package/dist/features/crawl/crawl-tools.js

@@ -80,7 +80,7 @@ export const CRAWL_TOOLS = [
                     .optional()
                     .describe('Where the fault is written, as `file:line`; console errors prefer their own stack and fall back to the clicked control.'),
             })),
-            counts: z.record(z.number()),
+            counts: z.record(z.string(), z.number()),
             visited: z.array(z.string()).describe('The controls actually clicked, in order.'),
             coverageNote: z
                 .string()
@@ -92,7 +92,7 @@ export const CRAWL_TOOLS = [
                 .optional()
                 .describe('Controls clicked whose silence could not be judged, e.g. on a background tab. They are NOT reported as dead, and they are not known to work either.'),
             // Only on `exhaustive` — see features/exhaust/exhaust-run.ts. Loose: it carries the levels.
-            exhaustive: z.record(z.unknown()).optional(),
+            exhaustive: z.record(z.string(), z.unknown()).optional(),
         },
         handler: async (deps, args) => {
             const session = deps.sessions.resolve(asString(args['sessionId']));

package/dist/features/crawl/crawl.js

@@ -375,6 +375,8 @@ export async function crawl(session, opts, sleep) {
                 // need — without it a crawl would report nothing about the UI moving, which is most of what a
                 // crawl is for.
                 actionSince: since,
+                // The control clicked, so a failed write is judged by what became of it.
+                ref: item.ref,
             })) {
                 counts.contradictions += 1;
                 anomalies.push({

package/dist/features/exhaust/ledger.d.ts

@@ -32,110 +32,29 @@ export declare const CoverageLevel: {
 export type CoverageLevel = (typeof CoverageLevel)[keyof typeof CoverageLevel];
 declare const LedgerSchema: z.ZodObject<{
     routes: z.ZodObject<{
-        discovered: z.ZodArray<z.ZodString, "many">;
-        reached: z.ZodArray<z.ZodString, "many">;
-    }, "strip", z.ZodTypeAny, {
-        reached: string[];
-        discovered: string[];
-    }, {
-        reached: string[];
-        discovered: string[];
-    }>;
+        discovered: z.ZodArray<z.ZodString>;
+        reached: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>;
     controls: z.ZodObject<{
-        seen: z.ZodArray<z.ZodString, "many">;
-        touched: z.ZodArray<z.ZodString, "many">;
-        proved: z.ZodArray<z.ZodString, "many">;
-    }, "strip", z.ZodTypeAny, {
-        proved: string[];
-        seen: string[];
-        touched: string[];
-    }, {
-        proved: string[];
-        seen: string[];
-        touched: string[];
-    }>;
+        seen: z.ZodArray<z.ZodString>;
+        touched: z.ZodArray<z.ZodString>;
+        proved: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>;
     journeys: z.ZodObject<{
-        completed: z.ZodArray<z.ZodString, "many">;
-    }, "strip", z.ZodTypeAny, {
-        completed: string[];
-    }, {
-        completed: string[];
-    }>;
+        completed: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>;
     writes: z.ZodObject<{
-        seen: z.ZodArray<z.ZodString, "many">;
-        branched: z.ZodArray<z.ZodString, "many">;
-        unhandled: z.ZodArray<z.ZodString, "many">;
-    }, "strip", z.ZodTypeAny, {
-        seen: string[];
-        branched: string[];
-        unhandled: string[];
-    }, {
-        seen: string[];
-        branched: string[];
-        unhandled: string[];
-    }>;
+        seen: z.ZodArray<z.ZodString>;
+        branched: z.ZodArray<z.ZodString>;
+        unhandled: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>;
     code: z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodObject<{
         name: z.ZodString;
         executed: z.ZodBoolean;
-    }, "strip", z.ZodTypeAny, {
-        name: string;
-        executed: boolean;
-    }, {
-        name: string;
-        executed: boolean;
-    }>>>;
-    /** Per file, when its code coverage was last taken. Absent in a ledger from before it existed. */
+    }, z.core.$strip>>>;
     codeTaken: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodNumber>>;
     best: z.ZodRecord<z.ZodString, z.ZodNumber>;
-}, "strip", z.ZodTypeAny, {
-    code: Record<string, Record<string, {
-        name: string;
-        executed: boolean;
-    }>>;
-    journeys: {
-        completed: string[];
-    };
-    best: Record<string, number>;
-    routes: {
-        reached: string[];
-        discovered: string[];
-    };
-    controls: {
-        proved: string[];
-        seen: string[];
-        touched: string[];
-    };
-    writes: {
-        seen: string[];
-        branched: string[];
-        unhandled: string[];
-    };
-    codeTaken: Record<string, number>;
-}, {
-    code: Record<string, Record<string, {
-        name: string;
-        executed: boolean;
-    }>>;
-    journeys: {
-        completed: string[];
-    };
-    best: Record<string, number>;
-    routes: {
-        reached: string[];
-        discovered: string[];
-    };
-    controls: {
-        proved: string[];
-        seen: string[];
-        touched: string[];
-    };
-    writes: {
-        seen: string[];
-        branched: string[];
-        unhandled: string[];
-    };
-    codeTaken?: Record<string, number> | undefined;
-}>;
+}, z.core.$strip>;
 export type AppLedger = z.infer<typeof LedgerSchema>;
 /** What one producer contributes. Every part optional: a drive adds what it saw and nothing else. */
 export interface LedgerDelta {

package/dist/features/exhaust/ledger.js

@@ -41,10 +41,10 @@ const LedgerSchema = z.object({
     controls: z.object({ seen: names, touched: names, proved: names }),
     journeys: z.object({ completed: names }),
     writes: z.object({ seen: names, branched: names, unhandled: names }),
-    code: z.record(z.record(z.object({ name: z.string(), executed: z.boolean() }))),
+    code: z.record(z.string(), z.record(z.string(), z.object({ name: z.string(), executed: z.boolean() }))),
     /** Per file, when its code coverage was last taken. Absent in a ledger from before it existed. */
-    codeTaken: z.record(z.number()).default({}),
-    best: z.record(z.number()),
+    codeTaken: z.record(z.string(), z.number()).default({}),
+    best: z.record(z.string(), z.number()),
 });
 /** A ledger file's text, or an empty ledger for anything unreadable: coverage never throws. */
 function parseLedger(text) {

package/dist/features/harness/drive-runs.d.ts

@@ -10,7 +10,8 @@
  * No I/O and no tool surface: what to run and where to write it arrive as functions, so this stays
  * a sink the surface hands things to.
  */
-import { type ImpactSnapshot } from '@reticlehq/core';
+import { HarnessRunReason } from '@reticlehq/core/telemetry';
+import { type ImpactSnapshot, type ReticleEvent } from '@reticlehq/core';
 export declare const DriveStatus: {
     readonly RUNNING: "running";
     readonly DONE: "done";
@@ -25,6 +26,11 @@ export type DriveStatus = (typeof DriveStatus)[keyof typeof DriveStatus];
  * such a run as "broken", which reads as a fault in the Harness; a refusal is a refusal.
  */
 export declare class DriveRefusedError extends Error {
+    /** Why, as `harness_run` reports it. */
+    readonly reason: HarnessRunReason;
+    constructor(message: string, 
+    /** Why, as `harness_run` reports it. */
+    reason?: HarnessRunReason);
 }
 /** Who asked for the drive. */
 export declare const DriveOrigin: {
@@ -88,8 +94,23 @@ export declare function runningDrives(): DriveRecord[];
  * is first. Ending the wait never ends the drive. `onChange` hears every step while waiting.
  */
 export declare function awaitDrive(runId: string, ms: number | undefined, signal?: AbortSignal, onChange?: (record: DriveRecord) => void): Promise<void>;
-/** Ask a running drive to stop. False when there is no such drive running. */
-export declare function stopDrive(runId: string): boolean;
+/**
+ * Ask a running drive to stop. False when there is no such drive running. `reason` is said on the
+ * Harness page when something other than the person stopped it (the page reloaded).
+ */
+export declare function stopDrive(runId: string, reason?: string): boolean;
+/** Why no drive started on this tab (a refusal, the cloud unreachable), for its Harness page. */
+export declare function noteHarnessWord(sessionId: string, said: string): void;
+/** Said on the Harness page when a person reloads the page during a run. */
+export declare const MSG_RELOADED = "The page reloaded, so this run stopped. Run again.";
+/** The daemon asked this tab to reload: the page coming back is not a person reloading it. */
+export declare function noteOwnReload(sessionId: string, at: number): void;
+/**
+ * Read each event a tab sends. A document that arrives as a reload the daemon did not ask for is a
+ * person reloading the page, and a drive on that tab cannot go on as if the page had not started
+ * over: it is stopped, and its Harness page says why. Before, it drove on and ended "failed".
+ */
+export declare function notePageLoaded(sessionId: string, event: ReticleEvent, at: number): void;
 /** Queue text for the driver's next turn. False when there is no such drive running. */
 export declare function sayToDrive(runId: string, text: string): boolean;
 /** One tool call a drive made. `harness` may be a lane's id (`<harness>-L2`). */
@@ -116,5 +137,8 @@ export declare const POLL_WAIT_DEFAULT_S = 50;
 export declare function pollCall(runId: string): string;
 /** What a poll answering `running` tells the agent to do, so it stays rather than walks away. */
 export declare function stillRunning(runId: string, steps: number, elapsedS: number): string;
-/** The impact snapshot, with the drive running on this tab when there is one. */
+/**
+ * The impact snapshot, with the drive running on this tab and its step log when there is one, else
+ * how the last one on this tab ended.
+ */
 export declare function withRunningDrive(snapshot: ImpactSnapshot | undefined, sessionId: string): ImpactSnapshot | undefined;