@reticlehq/server 3.5.0 → 3.6.0

package/dist/surface/tools/harness-script.js

@@ -0,0 +1,342 @@
+/**
+ * The Harness with no journey named: plan the drive from what the project knows, then run the plan.
+ *
+ * Saved flows replay in lanes side by side (each lane its own leased browser context, when the pool
+ * can lease one), flows that start the same way are driven once and branched from, and the open
+ * journeys (personas, the user's request, unproved intents) go to the model. The plan is drawn on
+ * the HUD and redrawn as each part starts and ends.
+ */
+import { randomUUID } from 'node:crypto';
+import { join } from 'node:path';
+import { ReticleCommand, ReticleTool, ScriptStatus, asRecord } from '@reticlehq/core';
+import { PromptContextSchema, checkScript } from '@reticlehq/core/artifacts';
+import { runScript, } from '../../features/harness/script/script-run.js';
+import { CUSTOM_DRIVER_NAME } from '../../features/harness/drivers.js';
+import { checkTally, verdictLine } from '../../features/harness/drive-report.js';
+import { runHarness, StopReason, } from '../../features/harness/harness.js';
+import { reticleDirPaths } from '../../memory/project/dir/reticle-dir.js';
+import { harnessRunId, noteHarnessGoal } from '../../judgement/runs/drive-run.js';
+import { openSessionIntents } from '../../memory/intent/open-intents.js';
+import { sessionRoot, sessionTarget } from '../../memory/project/session-root.js';
+import { leasableAppUrl } from '../../language/flows/flow-tools.js';
+import { acquireLeasedSession } from './lease-tools.js';
+import { reticleToolset } from './harness-toolset.js';
+import { laneIds } from '../../features/harness/script/lane-ids.js';
+import { appControlsOf } from '../../features/harness/script/app-controls.js';
+import { PlanStepKind, aboutTheApp, planAsText, withoutReplays, } from './harness-plan.js';
+import { journeyResults, personasIn, proposeScript, reportPlanResults, } from '../../features/harness/platform/script.js';
+import { checkGoals, goalsIn } from '../../features/harness/goals.js';
+import { serverOptionsFromEnv } from '../../features/harness/platform/server-driver.js';
+import { MSG_HARNESS_DISABLED, bankOpenRecording, buildDriver, flowsThatCheckNothing, maxStepsFromEnv, narrator, pinned, productRules, readFlows, readPlan, reconcileFlows, recordPersona, refusedByPlatform, withProjectFlows, } from './harness-explore.js';
+/** A request older than this is about some earlier task, not the one being driven. */
+const REQUEST_FRESH_MS = 6 * 60 * 60 * 1000;
+const MAX_GOAL_CHARS = 500;
+/**
+ * Lanes at once. Each is a fresh context loading the app cold, and eight against a dev server timed
+ * out together. ponytail: a fixed cap; read it from the pool's measured load time if 4 is too few.
+ */
+const MAX_LANES = 4;
+/** How often a scripted drive asks whether autonomous driving was switched off. */
+const STOP_POLL_MS = 10_000;
+/**
+ * The platform plans the drive; this machine runs the plan: saved flows replayed in lanes side by side, shared starts
+ * driven once and branched from, open journeys handed to the model. `undefined` when there is
+ * nothing to plan from, so the caller drives the app with no plan, as before.
+ */
+export async function exploreScript(deps, env, options, before) {
+    const reads = withProjectFlows(deps, options.sessionId);
+    const plan = await readPlan(reads, options.sessionId);
+    // A named journey is the whole plan: no other flows replayed, no personas proposed beside it.
+    const focus = options.focus;
+    const replay = focus === undefined
+        ? plan.steps.filter((s) => PlanStepKind.REPLAY === s.kind).map((s) => s.target)
+        : [];
+    const goals = focus === undefined ? await memoryGoals(deps, options.sessionId) : [focus];
+    const gaps = plan.steps.filter((s) => PlanStepKind.DRIVE === s.kind).map((s) => s.why);
+    const flows = await readFlows(reads);
+    const known = await productRules(deps, options.sessionId);
+    // The platform plans: personas, order, branches and the product rules each journey proves.
+    // A platform that cannot plan leaves the caller to drive the journey through it unplanned.
+    const platform = serverOptionsFromEnv(env);
+    if (platform === undefined)
+        return undefined;
+    // What the screen offers, for a named journey too. The platform splits a broad request ("test my
+    // app, make a plan") into journeys through these controls and leaves a narrow one whole; without
+    // them, a chat-requested drive of a desktop app planned one step that restated the request.
+    const about = await aboutTheApp(planAsText(plan), (name, args) => reticleToolset(deps, pinned(options)).invoke(name, args), await controlsSeenBefore(deps, options.sessionId));
+    const personas = focus === undefined ? personasIn(flows) : [];
+    const proposed = await proposeScript(platform, {
+        about,
+        flows,
+        replay,
+        goals,
+        gaps,
+        rules: known,
+        personas,
+    });
+    if (proposed === undefined || 0 < checkScript(proposed.script).length)
+        return undefined;
+    const { script, planId } = proposed;
+    // Saved the moment it exists, so a drive that breaks still leaves its plan behind.
+    const planFile = await savePlan(deps, options.sessionId, { planId, script });
+    const maxSteps = options.maxSteps ?? maxStepsFromEnv(env);
+    // The script replays the saved flows itself; a model handed them too replayed them again per goal.
+    const open = withoutReplays(plan);
+    // The journey itself leads (its rules are already written into it by the platform): a driver
+    // with nothing named to prove stopped after its first half.
+    const planFor = (goal) => {
+        if (goal === undefined)
+            return open;
+        const journey = { kind: PlanStepKind.DRIVE, target: 'this journey, to its end', why: goal };
+        return { ...open, steps: [journey, ...open.steps] };
+    };
+    const driverFor = (persona, goal) => options.driver === undefined
+        ? buildDriver(env, maxSteps, planFor(goal), options.driverName, persona, persona === undefined ? goal : undefined)
+        : { driver: options.driver, name: CUSTOM_DRIVER_NAME };
+    const driverName = driverFor().name;
+    const harness = randomUUID();
+    const narrate = narrator(deps, options);
+    // Lanes run side by side only in leased contexts; without a pool they take turns on this tab.
+    const pool = deps.pool;
+    const appUrl = leasableAppUrl(deps, options.sessionId);
+    const leasing = pool !== undefined && appUrl !== undefined && 1 < script.lanes.length;
+    const projectId = safeProjectId(deps, options.sessionId);
+    let off = false;
+    const poll = setInterval(() => {
+        void refusedByPlatform(env, options).then((refusal) => {
+            if (MSG_HARNESS_DISABLED === refusal)
+                off = true;
+        });
+    }, STOP_POLL_MS);
+    poll.unref();
+    const lanes = laneIds(harness, leasing);
+    // Keyed by the tool list, which the script runner's recording wrapper passes through unchanged.
+    const harnessOf = new WeakMap();
+    const ports = {
+        parallel: leasing ? Math.max(1, Math.min(script.lanes.length, pool.capacity(), MAX_LANES)) : 1,
+        stopped: () => off,
+        lease: async () => {
+            if (!leasing)
+                return { ...pinned(options), release: () => Promise.resolve() };
+            const acquire = () => acquireLeasedSession(pool, deps.sessions, appUrl, projectId);
+            // A cold dev server can miss the first load while other lanes compile it; the second finds it warm.
+            return acquire().catch(acquire);
+        },
+        toolset: (sessionId, persona) => {
+            const id = lanes.idFor(sessionId);
+            const toolset = reticleToolset(deps, {
+                ...(sessionId === undefined ? {} : { sessionId }),
+                drivenBy: {
+                    harness: id,
+                    driver: driverName,
+                    ...(persona === undefined ? {} : { persona }),
+                },
+            });
+            harnessOf.set(toolset.tools, id);
+            return toolset;
+        },
+        drive: async (toolset, goal, steps) => {
+            const persona = focus ??
+                (script.personas.find((p) => goal.startsWith(`${p.name}:`)) === undefined
+                    ? undefined
+                    : goal);
+            const ahead = new Set(await reads.flows.list());
+            const result = await runHarness(driverFor(persona, goal).driver, toolset, {
+                maxSteps: Math.min(steps, maxSteps),
+                focus: [planAsText(planFor(goal)), `Focus: ${goal}`].join('\n\n'),
+            });
+            // Before the lane's session ends and is graded, so its run cannot read "Proved" over a goal
+            // the drive did not reach.
+            noteHarnessGoal(harnessOf.get(toolset.tools) ?? harness, result.goalMet);
+            await bankOpenRecording(toolset, result, persona);
+            if (persona !== undefined) {
+                const saved = reconcileFlows(ahead, await reads.flows.list(), result.toolCalls);
+                await recordPersona(reads, [...saved.savedFlows, ...saved.rewroteFlows], persona);
+            }
+            return result;
+        },
+    };
+    narrate(`Harness plan from the platform · ${String(script.journeys.length)} journeys in ${String(script.lanes.length)} lane(s)` +
+        (1 < ports.parallel ? `, ${String(ports.parallel)} at once` : ''));
+    let run;
+    try {
+        run = await runScript(script, ports, (view) => {
+            try {
+                deps.sessions.resolve(options.sessionId).pushView(ReticleCommand.PLAN, view);
+            }
+            catch {
+                /* nobody is watching: the plan still runs */
+            }
+        });
+    }
+    finally {
+        clearInterval(poll);
+    }
+    // The whole app, after the journeys: a crawl clicks every reachable control (nothing destructive)
+    // and finds what no journey is aimed at — a nav link that renders nothing, a dead control, an
+    // error in the console. On the merchant dashboard eight blank pages went unreported without it.
+    // After the journeys, so the lanes start sooner. (Run first, it once left every lane unable to
+    // start; that did not reproduce on a clean install, and was the checkout's, not the order's.)
+    const crawled = focus === undefined && !run.stopped
+        ? await crawlApp(deps, options, harness, driverName)
+        : undefined;
+    // How each journey went: kept beside the plan here, and told to the platform, whose next plan
+    // drives what failed first.
+    const results = journeyResults(run.view);
+    await savePlan(deps, options.sessionId, { planId, script, results, ...appControlsOf(run.toolCalls, crawled) }, planFile);
+    if (planId !== undefined)
+        await reportPlanResults(platform, planId, results);
+    for (const line of run.lines)
+        narrate(line);
+    narrate(run.stopped
+        ? 'Autonomous driving switched off — the Harness stopped. What it drove is kept.'
+        : `Harness finished the plan — ${String(run.lines.filter((l) => l.startsWith('✓')).length)} of ${String(run.lines.length)} journeys passed. ${verdictLine(checkTally(run.toolCalls))}`);
+    const sum = (pick) => run.drives.reduce((n, r) => n + pick(r), 0);
+    // A model drive that broke breaks the run: "finished" over a platform that answered 500 hid it.
+    const broke = run.drives.find((d) => StopReason.BROKEN === d.stopReason);
+    const drive = {
+        stopReason: run.stopped
+            ? StopReason.STOPPED
+            : broke !== undefined
+                ? StopReason.BROKEN
+                : StopReason.FINISHED,
+        ...(broke?.error === undefined ? {} : { error: broke.error }),
+        summary: run.drives
+            .map((d) => d.summary)
+            .filter((t) => 0 < t.length)
+            .join('\n'),
+        steps: run.toolCalls.length,
+        toolCalls: crawled === undefined ? run.toolCalls : [crawled, ...run.toolCalls],
+        usage: {
+            input: sum((r) => r.usage.input),
+            output: sum((r) => r.usage.output),
+            cacheRead: sum((r) => r.usage.cacheRead),
+            cacheWrite: sum((r) => r.usage.cacheWrite),
+        },
+        proved: run.view.lanes.some((lane) => lane.journeys.some((card) => ScriptStatus.PASSED === card.status)),
+        // Unmet if any journey's goal was judged unmet; met only when every judged one was.
+        ...goalOfRun(run.drives),
+    };
+    const reconciled = reconcileFlows(before, await reads.flows.list(), run.toolCalls);
+    const runIds = lanes.all().flatMap((id) => {
+        const runId = harnessRunId(id);
+        return runId === undefined ? [] : [runId];
+    });
+    const unverifiedFlows = await flowsThatCheckNothing(reads, [
+        ...reconciled.savedFlows,
+        ...reconciled.rewroteFlows,
+    ]);
+    return {
+        drive,
+        plan,
+        driverName,
+        ...reconciled,
+        unverifiedFlows,
+        // The texts a named journey quoted must be on the page at the end, checked as the persona
+        // drive always checked them.
+        goals: await checkGoals((name, args) => ports.toolset(pinned(options).sessionId, focus).invoke(name, args), options.goals ?? goalsIn(focus)),
+        ...(0 === runIds.length ? {} : { runIds }),
+        planLines: [
+            `Plan · ${String(script.journeys.length)} journeys in ${String(script.lanes.length)} lane(s)`,
+            ...run.lines,
+        ],
+    };
+}
+/** What the project still owes, in its own words: the user's recent request, then open intents. */
+async function memoryGoals(deps, sessionId) {
+    const goals = [];
+    try {
+        const parsed = PromptContextSchema.safeParse(JSON.parse(await deps.fs.readFile(reticleDirPaths(sessionRoot(deps, sessionId)).request)));
+        const at = parsed.success ? parsed.data.at : undefined;
+        const request = parsed.success ? parsed.data.request : undefined;
+        if (request !== undefined && at !== undefined && deps.now() - at < REQUEST_FRESH_MS) {
+            goals.push(request);
+        }
+    }
+    catch {
+        /* no request declared: the common case */
+    }
+    try {
+        for (const intent of await openSessionIntents(deps, sessionId))
+            goals.push(intent.statement);
+    }
+    catch {
+        /* no intent ledger */
+    }
+    return [...new Set(goals.map((g) => g.trim().slice(0, MAX_GOAL_CHARS)))].filter((g) => 0 < g.length);
+}
+function safeProjectId(deps, sessionId) {
+    try {
+        return sessionTarget(deps, sessionId).projectId;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Keep a plan in `.reticle/plans/`, and how it went once it has run. The same file is rewritten
+ * with the results, so one plan is one file. Never fails the drive: a plan that cannot be written
+ * is still a plan that runs.
+ */
+async function savePlan(deps, sessionId, plan, file) {
+    try {
+        const dir = reticleDirPaths(sessionRoot(deps, sessionId)).plans;
+        const path = file ?? join(dir, `${new Date(deps.now()).toISOString().replace(/[:.]/g, '-')}.json`);
+        await deps.fs.mkdir(dir);
+        await deps.fs.writeFile(path, `${JSON.stringify({ at: deps.now(), ...plan }, null, 2)}\n`);
+        return path;
+    }
+    catch {
+        return file;
+    }
+}
+/** The run's goal verdict: false if any drive missed its goal, true if all judged ones reached it. */
+function goalOfRun(drives) {
+    const judged = drives.flatMap((d) => (d.goalMet === undefined ? [] : [d.goalMet]));
+    return 0 === judged.length ? {} : { goalMet: judged.every(Boolean) };
+}
+/** Controls the opening crawl clicks: enough for a dashboard's navigation and its main buttons. */
+const CRAWL_STEPS = 30;
+const CRAWL_ACTION = 'crawl';
+/** The opening crawl, as one recorded call. Undefined when it could not run; the plan runs anyway. */
+async function crawlApp(deps, options, harness, driver) {
+    // The crawl is an action of `reticle_verify` now; by its old name it answered "unknown tool",
+    // which read as a crawl that found nothing.
+    const args = { action: CRAWL_ACTION, maxSteps: CRAWL_STEPS };
+    try {
+        const result = await reticleToolset(deps, {
+            ...pinned(options),
+            drivenBy: { harness, driver },
+        }).invoke(ReticleTool.VERIFY, args);
+        if (undefined !== asRecord(result)['error'])
+            return undefined;
+        return { id: 'crawl', name: ReticleTool.CRAWL, args, result, isError: false };
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The controls the last crawl saw, from the newest saved plan that kept them. The planner reads the
+ * start page only; without these it never learned the refund buttons on another page existed, and
+ * no journey went near the app's costliest defects.
+ */
+async function controlsSeenBefore(deps, sessionId) {
+    try {
+        const dir = reticleDirPaths(sessionRoot(deps, sessionId)).plans;
+        const files = (await deps.fs.readdir(dir))
+            .filter((f) => f.endsWith('.json'))
+            .sort()
+            .reverse();
+        for (const file of files) {
+            const saved = asRecord(JSON.parse(await deps.fs.readFile(join(dir, file))));
+            const controls = saved['appControls'];
+            if (Array.isArray(controls))
+                return controls.filter((c) => 'string' === typeof c);
+        }
+    }
+    catch {
+        /* no plans yet: the planner works from the screen alone */
+    }
+    return [];
+}

package/dist/surface/tools/harness-toolset.d.ts

@@ -7,6 +7,7 @@
  * is missing a tool and THAT is the bug. Every capability a harness run proves is one a user's own
  * agent can reach.
  */
+import { type DrivenBy } from '@reticlehq/core';
 import { type ToolDeps } from './tools.js';
 import type { HarnessToolset } from '../../features/harness/harness.js';
 export interface ReticleToolsetOptions {
@@ -14,6 +15,10 @@ export interface ReticleToolsetOptions {
     sessionId?: string;
     /** Restrict to these names. Defaults to the advertised surface plus the recording pair. */
     only?: readonly string[];
+    /** Stamped on every action this drive journals, so its verdicts fold into a run of their own. */
+    drivenBy?: DrivenBy;
+    /** The pinned session wins over any a call names: a remote caller never reaches another tab. */
+    locked?: boolean;
 }
 /**
  * Bind the live tool surface to a set of dependencies.
@@ -32,4 +37,12 @@ export declare function reticleToolset(deps: ToolDeps, options?: ReticleToolsetO
  * ids, and silently overwriting one would make a deliberate cross-tab call lie about which tab it
  * read.
  */
-export declare function pinSession(args: Record<string, unknown>, sessionId: string | undefined): Record<string, unknown>;
+export declare function pinSession(args: Record<string, unknown>, sessionId: string | undefined, locked?: boolean): Record<string, unknown>;
+/**
+ * A desktop app's backend is its IPC: a claim that the app writes to its backend means that call.
+ *
+ * Reported from a chat-requested drive of a Tauri app: the platform claimed a POST for Add, the app
+ * made the same write as `ipc://add_todo` (200), and the step was graded `no`. Only a MUTATING method
+ * is read this way; a read, an unbound request and every other kind keep their meaning.
+ */
+export declare function desktopBackendClaims(args: Record<string, unknown>): Record<string, unknown>;

package/dist/surface/tools/harness-toolset.js

@@ -9,11 +9,12 @@
  */
 import { z } from 'zod';
 import { zodToJsonSchema } from 'zod-to-json-schema';
-import { ReticleTool } from '@reticlehq/core';
+import { AppRuntime, ConsequenceKind, NetInitiator, ReticleTool, } from '@reticlehq/core';
 import { TOOLS } from './tools.js';
 import { runTool } from './invoke-tool.js';
 import { TOOL_SURFACE, filterTools } from './tool-surface.js';
 import { withTimeout } from '../../features/harness/with-timeout.js';
+import { runDrivenBy } from '../../hooks/driven-by.js';
 /**
  * The two tools the harness is given beyond the advertised surface.
  *
@@ -43,6 +44,34 @@ const HARNESS_EXTRA_TOOLS = [
  * meant to protect.
  */
 const HARNESS_EXCLUDED = new Set([ReticleTool.FEEDBACK]);
+/**
+ * All a locked (remote) drive may run: reading and driving the one tab it was given, and keeping or
+ * replaying what it drove there. Nothing that lists other tabs, opens a browser, spends the local
+ * model, deletes saved work or sends a picture the person did not ask to send.
+ */
+const REMOTE_TOOLS = new Set([
+    ReticleTool.LOOK,
+    ReticleTool.SNAPSHOT,
+    ReticleTool.QUERY,
+    ReticleTool.INSPECT,
+    ReticleTool.NAVIGATE,
+    ReticleTool.REFRESH,
+    ReticleTool.ACT,
+    ReticleTool.ACT_AND_WAIT,
+    ReticleTool.ACT_SEQUENCE,
+    ReticleTool.OBSERVE,
+    ReticleTool.WAIT_FOR,
+    ReticleTool.WAIT_READY,
+    ReticleTool.SCROLL_TO,
+    ReticleTool.ASSERT,
+    ReticleTool.NETWORK,
+    ReticleTool.CONSOLE,
+    ReticleTool.STATE,
+    ReticleTool.RECORD,
+    ReticleTool.FLOW_SAVE,
+    ReticleTool.FLOW_REPLAY,
+    ReticleTool.RUN,
+]);
 /**
  * Parameters the model is never asked for, because the harness supplies them.
  *
@@ -93,7 +122,7 @@ function toHarnessTool(tool) {
  * a harness run a measurement of the product rather than of a test harness.
  */
 export function reticleToolset(deps, options = {}) {
-    const usable = TOOLS.filter((tool) => !HARNESS_EXCLUDED.has(tool.name));
+    const usable = TOOLS.filter((tool) => !HARNESS_EXCLUDED.has(tool.name) && (true !== options.locked || REMOTE_TOOLS.has(tool.name)));
     /**
      * Everything callable, whether or not it is advertised. `reticle_run` dispatches against this, so
      * trimming the ADVERTISED list never trims what a drive can reach.
@@ -115,8 +144,14 @@ export function reticleToolset(deps, options = {}) {
                 // list, and this is the same recovery the MCP surface gives an agent that does the same.
                 return { error: `unknown tool ${target ?? name}`, available: [...byName.keys()] };
             }
-            const scoped = pinSession(targetArgs, options.sessionId);
-            return withTimeout(runTool(tool, deps, scoped), TOOL_TIMEOUT_MS, `${tool.name} never returned`);
+            const pinned = pinSession(targetArgs, options.sessionId, true === options.locked);
+            const scoped = isDesktopSession(deps, pinned['sessionId'])
+                ? desktopBackendClaims(pinned)
+                : pinned;
+            const drivenBy = options.drivenBy;
+            return withTimeout(drivenBy === undefined
+                ? runTool(tool, deps, scoped)
+                : runDrivenBy(drivenBy, () => runTool(tool, deps, scoped)), TOOL_TIMEOUT_MS, `${tool.name} never returned`);
         },
     };
 }
@@ -129,11 +164,47 @@ export function reticleToolset(deps, options = {}) {
  * ids, and silently overwriting one would make a deliberate cross-tab call lie about which tab it
  * read.
  */
-export function pinSession(args, sessionId) {
-    if (sessionId === undefined || 'sessionId' in args)
+export function pinSession(args, sessionId, locked = false) {
+    if (sessionId === undefined || (!locked && 'sessionId' in args))
         return args;
     return { ...args, sessionId };
 }
+/** The HTTP methods a "saves" or "updates" claim names: a write to the app's backend. */
+const MUTATING_METHODS = new Set(['POST', 'PUT', 'PATCH', 'DELETE']);
+function isDesktopSession(deps, sessionId) {
+    try {
+        const runtime = deps.sessions.resolve('string' === typeof sessionId ? sessionId : undefined).runtime;
+        return AppRuntime.ELECTRON === runtime || AppRuntime.TAURI === runtime;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * A desktop app's backend is its IPC: a claim that the app writes to its backend means that call.
+ *
+ * Reported from a chat-requested drive of a Tauri app: the platform claimed a POST for Add, the app
+ * made the same write as `ipc://add_todo` (200), and the step was graded `no`. Only a MUTATING method
+ * is read this way; a read, an unbound request and every other kind keep their meaning.
+ */
+export function desktopBackendClaims(args) {
+    const rewrite = (value) => {
+        if (Array.isArray(value))
+            return value.map(rewrite);
+        if ('object' !== typeof value || null === value)
+            return value;
+        const record = value;
+        const method = record['method'];
+        const ipc = ConsequenceKind.NET === record['kind'] &&
+            'string' === typeof method &&
+            MUTATING_METHODS.has(method.toUpperCase());
+        return Object.fromEntries(Object.entries(record).map(([key, inner]) => [
+            key,
+            ipc && 'method' === key ? NetInitiator.IPC : rewrite(inner),
+        ]));
+    };
+    return rewrite(args);
+}
 function asName(value) {
     return 'string' === typeof value && value.length > 0 ? value : undefined;
 }

package/dist/surface/tools/invoke-tool.js

@@ -1,4 +1,9 @@
 import { healthEnvelope } from '../../portal/session/session-health.js';
+import { logToolCall, toolLogPath } from '../../hooks/tool-log.js';
+import { nextStep } from './next-step.js';
+import { currentDrivenBy } from '../../hooks/driven-by.js';
+import { sessionRoot } from '../../memory/project/session-root.js';
+import { takePlatformMoment } from './platform-moment.js';
 import { verifyNextBaton, SUPPRESS_VERIFY_NEXT_ENV } from './verify-next-baton.js';
 import { TelemetryActor, TelemetryEventKind, TRANSPORT_LIMITS, fingerprintFinding, } from '@reticlehq/core';
 import { getSessionMetrics } from '../../telemetry/session-metrics.js';
@@ -340,6 +345,22 @@ function pinnedArgs(args, explicitSessionId, session) {
     return { ...args, [SESSION_ID_ARG]: session.id };
 }
 export async function runTool(tool, deps, args) {
+    const logPath = toolLogPath();
+    if (logPath === undefined)
+        return dispatchTool(tool, deps, args);
+    const at = deps.now();
+    try {
+        const result = await dispatchTool(tool, deps, args);
+        logToolCall(logPath, { tool: tool.name, args, at, ms: deps.now() - at, result });
+        return result;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        logToolCall(logPath, { tool: tool.name, args, at, ms: deps.now() - at, error: message });
+        throw error;
+    }
+}
+async function dispatchTool(tool, deps, args) {
     // Both dispatch paths (MCP + programmatic) pass through here — the one place "which tool is mostly
     // used" can be counted. This used to EMIT an event per call; it now increments an in-process counter
     // that leaves once, with the session summary. A verification loop is 50–200 calls, and PostHog bills
@@ -605,13 +626,33 @@ export async function runTool(tool, deps, args) {
     // RETURN an error. So the denominator was counting a small, unrepresentative slice of the
     // invitations and reading near-empty, which looks identical to a nudge that never fires.
     const friction = frictionInviteFor(tool.name, raw);
+    // Once per project, on a proved verdict, when the runs live only on this machine.
+    const platform = isPlainObject(raw)
+        ? await takePlatformMoment(deps, raw, () => sessionRoot(deps, rawSessionId))
+        : undefined;
+    // What the agent should do next, on every client that reads results. Not for the Harness, whose
+    // runs the daemon syncs itself and which cannot relay the user's words, and not on `reticle_run`'s
+    // outer result: the inner call already carried one.
+    const next = isPlainObject(raw) && ReticleTool.RUN !== tool.name && currentDrivenBy() === undefined
+        ? nextStep({
+            tool: tool.name,
+            verdict: 'verified' in raw,
+            root: safeRoot(() => sessionRoot(deps, rawSessionId)),
+            // A partial deps (tests, the demo) may carry no clock; the line is advice, never a reason to fail.
+            now: 'function' === typeof deps.now ? deps.now() : Date.now(),
+        })
+        : undefined;
     const result = prompt === undefined &&
         update === undefined &&
         skew === undefined &&
         undelivered === undefined &&
-        friction === undefined
+        friction === undefined &&
+        platform === undefined &&
+        next === undefined
         ? raw
         : {
+            // First, so a model that truncates a long result still reads it.
+            ...(next !== undefined ? { [EnvelopeKey.NEXT]: next } : {}),
             ...raw,
             ...(friction !== undefined
                 ? {
@@ -623,6 +664,7 @@ export async function runTool(tool, deps, args) {
             ...(prompt !== undefined ? { [EnvelopeKey.FEEDBACK_PROMPT]: prompt } : {}),
             ...(update !== undefined ? { [EnvelopeKey.UPDATE_AVAILABLE]: update } : {}),
             ...(skew !== undefined ? { [EnvelopeKey.VERSION_SKEW]: skew } : {}),
+            ...(platform !== undefined ? { [EnvelopeKey.PLATFORM]: platform } : {}),
             ...(undelivered !== undefined
                 ? {
                     [EnvelopeKey.FEEDBACK_UNDELIVERED]: `your earlier report did NOT send: ${undelivered}. Tell the human what you found so it is not lost.`,
@@ -683,3 +725,12 @@ export async function runTool(tool, deps, args) {
         envelope[EnvelopeKey.VERIFY_NEXT] = verifyNextBaton(unverified, resolved.lastAct?.effect() ?? {});
     return Object.keys(envelope).length > 0 ? { ...result, ...envelope } : result;
 }
+/** A root, or undefined when none can be resolved: a missing root is never a reason to throw. */
+function safeRoot(get) {
+    try {
+        return get();
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/surface/tools/lease-seed.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Seeded storage for a lease, and the errors a lease's navigation throws: what a caller may see of
+ * them without seeing the secrets it seeded. Split from lease-tools.ts, which crossed the line cap.
+ */
+import { type SeedStorage } from '@reticlehq/core';
+/**
+ * Scrub known secret shapes and raw seedStorage values (cookies, localStorage, sessionStorage)
+ * from an error string before it reaches daemon logs, metrics, or MCP error responses.
+ */
+export declare function scrubSeedFromError(text: string, seed?: unknown): string;
+/** True for a Playwright `storageState()` export (`{ origins: [...] }`), not our seed shape. */
+export declare function looksLikeStorageStateExport(seed: unknown): boolean;
+/**
+ * Turn a raw navigation failure (Playwright's `page.goto: net::ERR_… at <url>\nCall log:…`, often
+ * with ANSI codes) into a short, clean reason — so the agent/user sees "is the app running?" instead
+ * of an internals-leaking wall of text.
+ */
+export declare function cleanNavError(err: unknown, seed?: SeedStorage): string;
+/**
+ * Determine if a required seedStorage application precondition failed.
+ *
+ * Checks strong signals:
+ * 1. HTTP 401/403 status on the initial navigation.
+ * 2. Cross-origin redirect when localStorage or sessionStorage was requested (skipped by origin-scoping).
+ * 3. Clear redirect to an authentication/login endpoint when the requested URL was not a login page.
+ *
+ * Normal app redirects (e.g. / → /dashboard) are valid and return undefined.
+ */
+export declare function evaluateSeedPrecondition(requestedUrl: string, actualUrl: string | undefined, seed: SeedStorage, navStatus?: number): string | undefined;