@reticlehq/server 3.6.0 → 3.7.0

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

@@ -8,26 +8,44 @@
  */
 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 { ReticleCommand, ReticleTool, ScriptStatus, asRecord, } from '@reticlehq/core';
+import { JourneyBy, 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 { actedOnApp, checkTally, pagesReached, typedValues, 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 { harnessRunId, noteHarnessDisparity, noteHarnessGoal, noteHarnessSpan, } 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 { leasableAppUrl, sessionUrlOf } from '../../language/flows/flow-tools.js';
+import { acquireLeasedSession, suiteFixtureSeed } 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';
+import { surveyedSince } from '../../features/harness/explore/site-map.js';
+import { PlanStepKind, aboutTheApp, drivingPlan, planAsText, } from './harness-plan.js';
+import { fetchScript, journeyResults, personasIn, proposeScript, reportPlanBlocked, reportPlanResults, } from '../../features/harness/platform/script.js';
+import { endOf, goalOfDrive, parseGoals, readOpening } from '../../features/harness/goals.js';
+import { bestOfLanes, huntAndGrade, knownRoutes, refreshMap, siteMapFor, } from './harness-hunt.js';
+import { serverOptionsFromEnv, } from '../../features/harness/platform/server-driver.js';
+import { MSG_HARNESS_DISABLED, bankOpenRecording, buildDriver, firstLine, flowsThatCheckNothing, maxStepsFromEnv, msgDriveCutOff, narrator, pinned, productRules, readFlows, readPlan, reconcileFlows, recordPersona, refusedByPlatform, steering, withProjectFlows, } from './harness-explore.js';
+/** A saved plan this run was asked for and could not read: said, never swapped for another drive. */
+export const msgSavedPlanUnreadable = (planId) => `The saved plan ${planId} could not be read from the Reticle platform, or it no longer runs as written. Open it on the dashboard, fix it, and run it again.`;
+/** The platform could not plan the run: the drive that follows is the journey alone, unplanned. */
+export const msgNoPlan = (why) => `No plan this time — ${why.replace(/\.$/, '')}. Driving the journey on its own instead.`;
+/** Said when a plan's lanes cannot carry this tab's sign-in into new browsers, so they take turns here. */
+export const MSG_LANES_IN_THIS_TAB = "The plan's lanes take turns in this tab: a new browser would start signed out, and this tab's " +
+    'sign-in could not be copied into one.';
+/**
+ * The sign-in a plan's lanes start from: what this tab's browser holds, or undefined when it cannot
+ * be copied (no browser this daemon drives, nothing to copy), in which case the lanes take turns here.
+ */
+export async function laneSeed(deps, sessionId, appUrl) {
+    if (appUrl === undefined)
+        return undefined;
+    return suiteFixtureSeed(deps.realInput, sessionUrlOf(deps, sessionId) ?? appUrl);
+}
 /** 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;
@@ -52,18 +70,45 @@ export async function exploreScript(deps, env, options, before) {
         ? 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 gaps = drivingPlan(plan, focus).steps.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);
+    // A saved plan is the platform's: without it there is nothing to run, and driving something else
+    // in its place would answer a question nobody asked.
+    if (platform === undefined && options.planId !== undefined)
+        throw new Error(msgSavedPlanUnreadable(options.planId));
     if (platform === undefined)
         return undefined;
+    if (options.planId !== undefined) {
+        const planId = options.planId;
+        // Refused or broken before a journey ran is still said to the plan, so its history shows it.
+        // ponytail: a throw from inside a running plan is reported as all blocked too; runPlan reports
+        // real results itself whenever it returns.
+        try {
+            const saved = await fetchScript(platform, planId);
+            if (saved === undefined)
+                throw new Error(msgSavedPlanUnreadable(planId));
+            return await runPlan(deps, env, options, before, { platform, plan, script: saved, planId });
+        }
+        catch (error) {
+            const why = error instanceof Error ? error.message : String(error);
+            await reportPlanBlocked(platform, planId, firstLine(why));
+            throw error;
+        }
+    }
+    // The same persona runs the plan it made last time, as it stands on the platform now (edits and
+    // replay-first included): a new plan per HUD run meant a passed journey was never replayed.
+    const again = focus === undefined ? undefined : await planMadeFor(deps, options.sessionId, focus);
+    const reused = again === undefined ? undefined : await fetchScript(platform, again);
+    if (again !== undefined && reused !== undefined)
+        return runPlan(deps, env, options, before, { platform, plan, script: reused, planId: again });
     // 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 about = await aboutTheApp(planAsText(focus === undefined ? plan : drivingPlan(plan, focus)), (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,
@@ -74,14 +119,35 @@ export async function exploreScript(deps, env, options, before) {
         rules: known,
         personas,
     });
+    if (proposed !== undefined && 'refused' in proposed) {
+        // Said where the run is watched: the drive goes on without a plan, and that is not what was asked.
+        narrator(deps, options)(msgNoPlan(proposed.refused), true);
+        return undefined;
+    }
     if (proposed === undefined || 0 < checkScript(proposed.script).length)
         return undefined;
-    const { script, planId } = proposed;
+    return runPlan(deps, env, options, before, {
+        platform,
+        plan,
+        script: proposed.script,
+        ...(proposed.planId === undefined ? {} : { planId: proposed.planId }),
+        ...(proposed.creditsSpent === undefined ? {} : { planCredits: proposed.creditsSpent }),
+    });
+}
+/** Run a plan the platform wrote (just now, or saved and maybe edited since), and report how it went. */
+async function runPlan(deps, env, options, before, planned) {
+    const { platform, plan, script, planId } = planned;
+    const reads = withProjectFlows(deps, options.sessionId);
+    const focus = options.focus;
     // 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 planFile = await savePlan(deps, options.sessionId, {
+        planId,
+        script,
+        ...(focus === undefined ? {} : { focus }),
+    });
     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);
+    const open = drivingPlan(plan, focus);
     // 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) => {
@@ -90,16 +156,26 @@ export async function exploreScript(deps, env, options, before) {
         const journey = { kind: PlanStepKind.DRIVE, target: 'this journey, to its end', why: goal };
         return { ...open, steps: [journey, ...open.steps] };
     };
+    // Map first: survey the app (no model) unless its map is fresh; every lane's engine looks goals up
+    // in it, and the hunt before grading starts from it. The tab is left where it started.
+    const mapAsked = deps.now();
+    const map = await siteMapFor(deps, options.sessionId, (name, args) => reticleToolset(deps, pinned(options)).invoke(name, args));
     const driverFor = (persona, goal) => options.driver === undefined
-        ? buildDriver(env, maxSteps, planFor(goal), options.driverName, persona, persona === undefined ? goal : undefined)
+        ? buildDriver(env, maxSteps, planFor(goal), options.driverName, persona, persona === undefined ? goal : undefined, map)
         : { driver: options.driver, name: CUSTOM_DRIVER_NAME };
     const driverName = driverFor().name;
-    const harness = randomUUID();
+    const harness = options.harnessId ?? 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 wantsLanes = pool !== undefined && appUrl !== undefined && 1 < script.lanes.length;
+    // A new context starts signed out: lanes once spent a whole run (three lanes, twelve credits) on
+    // /login, a page that was not the journey. They start from what this tab holds, or take turns here.
+    const seed = wantsLanes ? await laneSeed(deps, options.sessionId, appUrl) : undefined;
+    const leasing = wantsLanes && seed !== undefined;
+    if (wantsLanes && !leasing)
+        narrator(deps, options)(MSG_LANES_IN_THIS_TAB);
     const projectId = safeProjectId(deps, options.sessionId);
     let off = false;
     const poll = setInterval(() => {
@@ -110,15 +186,25 @@ export async function exploreScript(deps, env, options, before) {
     }, STOP_POLL_MS);
     poll.unref();
     const lanes = laneIds(harness, leasing);
+    const endGoalsAsked = options.goals ?? parseGoals(focus);
+    const laneGrades = [];
     // Keyed by the tool list, which the script runner's recording wrapper passes through unchanged.
     const harnessOf = new WeakMap();
+    const own = [...(focus === undefined ? [] : [focus]), ...scriptTexts(script)];
     const ports = {
+        own,
         parallel: leasing ? Math.max(1, Math.min(script.lanes.length, pool.capacity(), MAX_LANES)) : 1,
-        stopped: () => off,
+        stopped: () => off || true === options.stopped?.(),
+        // A replay-only plan started without the model's gates; a fallback is the model, so it asks now.
+        fallbackRefused: async () => {
+            const refusal = await refusedByPlatform(env, options);
+            return refusal === undefined ? undefined : firstLine(refusal);
+        },
+        ...(true === options.confirmDangerous ? { confirmDangerous: true } : {}),
         lease: async () => {
             if (!leasing)
                 return { ...pinned(options), release: () => Promise.resolve() };
-            const acquire = () => acquireLeasedSession(pool, deps.sessions, appUrl, projectId);
+            const acquire = () => acquireLeasedSession(pool, deps.sessions, appUrl, projectId, seed);
             // A cold dev server can miss the first load while other lanes compile it; the second finds it warm.
             return acquire().catch(acquire);
         },
@@ -131,6 +217,9 @@ export async function exploreScript(deps, env, options, before) {
                     driver: driverName,
                     ...(persona === undefined ? {} : { persona }),
                 },
+                // The person's request, never the planned journey's text: a planner-invented journey
+                // ("press Invite") must not be what allows an invite.
+                ...(focus === undefined ? {} : { asked: focus }),
             });
             harnessOf.set(toolset.tools, id);
             return toolset;
@@ -141,16 +230,38 @@ export async function exploreScript(deps, env, options, before) {
                     ? undefined
                     : goal);
             const ahead = new Set(await reads.flows.list());
-            const result = await runHarness(driverFor(persona, goal).driver, toolset, {
+            const driven = await runHarness(driverFor(persona, goal).driver, toolset, {
+                ...steering(options),
                 maxSteps: Math.min(steps, maxSteps),
+                routes: knownRoutes(map),
                 focus: [planAsText(planFor(goal)), `Focus: ${goal}`].join('\n\n'),
+                ...((end) => (end === undefined ? {} : { endsAt: { text: end, own } }))(endOf(goal)),
             });
+            // The driver's word, unless the lane did nothing: then its goal was not met by it.
+            const laneGoal = goalOfDrive(driven.goalMet, [], actedOnApp(driven.toolCalls));
+            const result = { ...driven, ...(laneGoal === undefined ? {} : { goalMet: laneGoal }) };
             // 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);
+            const banked = await bankOpenRecording(toolset, result, persona, goal);
+            // A lane in its own browser is graded where it drove: the caller's tab never saw its pages.
+            if (leasing && 0 < endGoalsAsked.length)
+                laneGrades.push(await huntAndGrade(deps, (name, args) => toolset.invoke(name, args), {
+                    sessionId: options.sessionId,
+                    goals: endGoalsAsked,
+                    expect: options.expect,
+                    opening,
+                    journey: goal,
+                    map,
+                    own,
+                    reached: pagesReached(result.toolCalls),
+                    typed: typedValues(result.toolCalls),
+                }));
             if (persona !== undefined) {
-                const saved = reconcileFlows(ahead, await reads.flows.list(), result.toolCalls);
+                const saved = reconcileFlows(ahead, await reads.flows.list(), [
+                    ...result.toolCalls,
+                    ...banked,
+                ]);
                 await recordPersona(reads, [...saved.savedFlows, ...saved.rewroteFlows], persona);
             }
             return result;
@@ -158,6 +269,10 @@ export async function exploreScript(deps, env, options, before) {
     };
     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` : ''));
+    // Read before anything is driven: a goal this page already shows proves nothing at the end.
+    const endInvoke = (name, args) => ports.toolset(pinned(options).sessionId, focus).invoke(name, args);
+    const opening = await readOpening(endInvoke);
+    const runStarted = deps.now();
     let run;
     try {
         run = await runScript(script, ports, (view) => {
@@ -177,23 +292,32 @@ export async function exploreScript(deps, env, options, before) {
     // 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
+    // Once per map: a run on a fresh map swept the whole app again, every time.
+    const crawled = focus === undefined && !run.stopped && surveyedSince(map, mapAsked)
         ? 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);
+    const results = journeyResults(run.view, run.journeys);
+    await savePlan(deps, options.sessionId, {
+        planId,
+        script,
+        ...(focus === undefined ? {} : { focus }),
+        results,
+        ...appControlsOf(run.toolCalls, crawled),
+    }, planFile);
     for (const line of run.lines)
         narrate(line);
+    const cutOff = run.drives.find((d) => StopReason.BROKEN === d.stopReason);
     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))}`);
+        : cutOff !== undefined
+            ? msgDriveCutOff(cutOff.error)
+            : // One verdict, the journeys': the count of passed journeys is in it, said once.
+                `Harness finished the plan${answeredBy(run.journeys)}. ${verdictLine(checkTally(run.toolCalls), undefined, results)}`);
     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 broke = cutOff;
     const drive = {
         stopReason: run.stopped
             ? StopReason.STOPPED
@@ -215,7 +339,11 @@ export async function exploreScript(deps, env, options, before) {
         },
         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),
+        ...goalOfRun(run.drives, results),
+        // What every lane cost, as the platform said; a planned run dropped it and read as free.
+        ...(run.drives.some((d) => d.creditsSpent !== undefined) || planned.planCredits !== undefined
+            ? { creditsSpent: sum((r) => r.creditsSpent ?? 0) + (planned.planCredits ?? 0) }
+            : {}),
     };
     const reconciled = reconcileFlows(before, await reads.flows.list(), run.toolCalls);
     const runIds = lanes.all().flatMap((id) => {
@@ -226,22 +354,86 @@ export async function exploreScript(deps, env, options, before) {
         ...reconciled.savedFlows,
         ...reconciled.rewroteFlows,
     ]);
+    await refreshMap(deps, options.sessionId, map, run.toolCalls);
+    // The texts a named journey quoted must be on the page at the end, hunted for first (a goal the
+    // drive walked past or stopped short of is looked for, not graded where it stood), and not counted
+    // when the page showed them before the drive began.
+    // Lanes in their own browsers were graded where they drove, and a goal any lane proved is proved;
+    // lanes taking turns here end on this tab, so it is graded here.
+    const graded = 0 < laneGrades.length
+        ? bestOfLanes(laneGrades)
+        : await huntAndGrade(deps, endInvoke, {
+            sessionId: options.sessionId,
+            goals: endGoalsAsked,
+            expect: options.expect,
+            opening,
+            journey: focus,
+            map,
+            own,
+            reached: pagesReached(run.toolCalls),
+            typed: typedValues(run.toolCalls),
+        });
+    const goals = graded.goals;
+    for (const id of lanes.all())
+        noteHarnessDisparity(id, graded.disparity);
+    const goalMet = goalOfDrive(drive.goalMet, goals, actedOnApp(run.toolCalls));
+    if (0 < goals.length)
+        for (const id of lanes.all())
+            noteHarnessGoal(id, goalMet);
+    // After the goals are graded: a journey that "passed" over goals that came back unmet is not.
+    // ponytail: one run-wide goalMet on every journey; per-journey once lanes grade their own goals.
+    if (planId !== undefined)
+        await reportPlanResults(platform, planId, goalMet === undefined ? results : results.map((r) => ({ ...r, goalMet })), runIds);
+    // ponytail: every lane is given the run's time; per-lane timing if lanes ever report their own.
+    for (const id of lanes.all())
+        noteHarnessSpan(id, deps.now() - runStarted);
     return {
-        drive,
+        // The hunt's navigations too, after the goal was decided on what the plan itself drove.
+        drive: {
+            ...drive,
+            toolCalls: [...drive.toolCalls, ...graded.moved],
+            ...(goalMet === undefined ? {} : { goalMet }),
+        },
         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)),
+        goals,
+        ...(0 === graded.disparity.length ? {} : { disparity: graded.disparity }),
         ...(0 === runIds.length ? {} : { runIds }),
+        ...(planId === undefined ? {} : { planId }),
+        journeys: results,
         planLines: [
             `Plan · ${String(script.journeys.length)} journeys in ${String(script.lanes.length)} lane(s)`,
             ...run.lines,
         ],
     };
 }
+/**
+ * How the journeys were answered: replayed with no model, or driven by it and what that cost. Only
+ * what was measured; what a replay saved is not, since its journey was not also driven to compare.
+ */
+function answeredBy(journeys) {
+    if (0 === journeys.length)
+        return '';
+    const driven = journeys.filter((j) => JourneyBy.MODEL === j.by);
+    const replayed = journeys.filter((j) => JourneyBy.REPLAY === j.by).length;
+    const tokens = driven.reduce((n, j) => n + j.tokens, 0);
+    return ` (${String(replayed)} replayed with no model, ${String(driven.length)} driven by the model${0 === driven.length ? '' : `, ${String(tokens)} tokens`})`;
+}
+/**
+ * Every text the plan writes down that a page could show back: journey titles, open goals, personas.
+ * The platform names the saved plan after them, so they are the Harness's words, never evidence.
+ */
+function scriptTexts(script) {
+    return [
+        ...script.journeys.flatMap((j) => [
+            j.title,
+            ...j.steps.flatMap((s) => ('goal' in s && s.goal !== undefined ? [s.goal] : [])),
+        ]),
+        ...script.personas.map((p) => p.journey),
+    ];
+}
 /** What the project still owes, in its own words: the user's recent request, then open intents. */
 async function memoryGoals(deps, sessionId) {
     const goals = [];
@@ -290,8 +482,14 @@ async function savePlan(deps, sessionId, plan, file) {
         return file;
     }
 }
-/** The run's goal verdict: false if any drive missed its goal, true if all judged ones reached it. */
-function goalOfRun(drives) {
+/**
+ * The run's goal verdict: false if any drive missed its goal, true if all judged ones reached it.
+ * Every journey passed is the page's answer, already graded at each journey's end: a driver's own
+ * "not done" (a lane whose model call failed) read "but the goal was not reached" beside it.
+ */
+export function goalOfRun(drives, journeys) {
+    if (0 < journeys.length && journeys.every((j) => ScriptStatus.PASSED === j.status))
+        return {};
     const judged = drives.flatMap((d) => (d.goalMet === undefined ? [] : [d.goalMet]));
     return 0 === judged.length ? {} : { goalMet: judged.every(Boolean) };
 }
@@ -316,6 +514,26 @@ async function crawlApp(deps, options, harness, driver) {
         return undefined;
     }
 }
+/** The platform plan the newest saved run as `focus` ran, or undefined when none did. */
+async function planMadeFor(deps, sessionId, focus) {
+    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 planId = saved['planId'];
+            if (focus === saved['focus'] && 'string' === typeof planId)
+                return planId;
+        }
+    }
+    catch {
+        /* no plans yet: this persona is planned afresh */
+    }
+    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

package/dist/surface/tools/harness-tab-guard.d.ts

@@ -0,0 +1,5 @@
+import type { ToolDeps } from './tool-kit.js';
+/** Said when the agent acts in a tab the Harness is driving. */
+export declare const msgHarnessHasTheTab: (runId: string) => string;
+/** The Harness run driving the tab this agent call would act on, unless the call is the Harness's. */
+export declare function harnessDriving<Ext>(deps: ToolDeps<Ext>, args: Record<string, unknown>): string | undefined;

package/dist/surface/tools/harness-tab-guard.js

@@ -0,0 +1,27 @@
+/**
+ * One driver per tab. The Harness clicking through a page while the agent clicks too is two hands on
+ * one mouse: neither result means anything. While a Harness run drives a tab, the agent's own
+ * actions in it are refused with how to wait for the run or stop it; its reads still run.
+ */
+import { ReticleTool } from '@reticlehq/core';
+import { runningDrive, runningDrives } from '../../features/harness/drive-runs.js';
+import { currentDrivenBy } from '../../hooks/driven-by.js';
+import { sessionIdFromArgs } from './tools-helpers.js';
+/** Said when the agent acts in a tab the Harness is driving. */
+export const msgHarnessHasTheTab = (runId) => `Reticle Harness is driving this tab now (run ${runId}), so this action did not run. Wait for ` +
+    `its result with ${ReticleTool.VERIFY} { action: "explore", runId: "${runId}" }, or stop it ` +
+    `with the same call and stop: true, then act.`;
+/** The Harness run driving the tab this agent call would act on, unless the call is the Harness's. */
+export function harnessDriving(deps, args) {
+    // No drive anywhere is the usual case, and it touches nothing: not even which tab this call is.
+    if (currentDrivenBy() !== undefined || 0 === runningDrives().length)
+        return undefined;
+    let sessionId;
+    try {
+        sessionId = deps.sessions.resolve(sessionIdFromArgs(args)).id;
+    }
+    catch {
+        return undefined; // no tab: the action fails on its own, with the no-session answer
+    }
+    return runningDrive(sessionId)?.harnessRun;
+}

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

@@ -17,6 +17,8 @@ export interface ReticleToolsetOptions {
     only?: readonly string[];
     /** Stamped on every action this drive journals, so its verdicts fold into a run of their own. */
     drivenBy?: DrivenBy;
+    /** The person's own request: the only text that lets the drive press an outward control. */
+    asked?: string;
     /** The pinned session wins over any a call names: a remote caller never reaches another tab. */
     locked?: boolean;
 }
@@ -28,6 +30,12 @@ export interface ReticleToolsetOptions {
  * a harness run a measurement of the product rather than of a test harness.
  */
 export declare function reticleToolset(deps: ToolDeps, options?: ReticleToolsetOptions): HarnessToolset;
+/**
+ * A request the Harness declares must succeed (`ok: true`) unless its claim names a status. A net
+ * claim with no status is met by any answer, so a sign-in whose `POST /api/login` came back 401 was
+ * counted as a check that held. Applied to the top-level claim of a wait or an assert.
+ */
+export declare function requestMustSucceed(args: Record<string, unknown>): Record<string, unknown>;
 /**
  * Stamp the drive's own session onto a call.
  *

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

@@ -9,12 +9,13 @@
  */
 import { z } from 'zod';
 import { zodToJsonSchema } from 'zod-to-json-schema';
-import { AppRuntime, ConsequenceKind, NetInitiator, ReticleTool, } from '@reticlehq/core';
+import { AppRuntime, ConsequenceKind, NetInitiator, PredicateKind, 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';
+import { noteDriveStep } from '../../features/harness/drive-runs.js';
 /**
  * The two tools the harness is given beyond the advertised surface.
  *
@@ -25,7 +26,7 @@ import { runDrivenBy } from '../../hooks/driven-by.js';
  * sometimes skip, which silently turns the cheap path off.
  */
 /**
- * Beyond the default surface, the three tools a drive cannot do its job without.
+ * Beyond the default surface, the tools a drive cannot do its job without.
  *
  * RECORD and FLOW_SAVE are how a drive keeps what it drove. FLOW_REPLAY is how it avoids driving
  * the same thing twice — it was absent, so a driver handed a plan full of already-recorded journeys
@@ -35,6 +36,9 @@ const HARNESS_EXTRA_TOOLS = [
     ReticleTool.RECORD,
     ReticleTool.FLOW_SAVE,
     ReticleTool.FLOW_REPLAY,
+    // A goal below the fold stayed `unknown` on a drive told to scroll to it: nothing it was offered
+    // could scroll. This one brings an element into view by the same query a find uses.
+    ReticleTool.SCROLL_TO,
 ];
 /**
  * The one deliberate subtraction.
@@ -144,17 +148,36 @@ 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 pinned = pinSession(targetArgs, options.sessionId, true === options.locked);
+            const pinned = pinSession(options.drivenBy === undefined ? targetArgs : requestMustSucceed(targetArgs), options.sessionId, true === options.locked);
             const scoped = isDesktopSession(deps, pinned['sessionId'])
                 ? desktopBackendClaims(pinned)
                 : pinned;
             const drivenBy = options.drivenBy;
+            if (drivenBy !== undefined)
+                noteDriveStep(drivenBy.harness, tool.name);
             return withTimeout(drivenBy === undefined
                 ? runTool(tool, deps, scoped)
-                : runDrivenBy(drivenBy, () => runTool(tool, deps, scoped)), TOOL_TIMEOUT_MS, `${tool.name} never returned`);
+                : runDrivenBy(drivenBy, () => runTool(tool, deps, scoped), options.asked), TOOL_TIMEOUT_MS, `${tool.name} never returned`);
         },
     };
 }
+/**
+ * A request the Harness declares must succeed (`ok: true`) unless its claim names a status. A net
+ * claim with no status is met by any answer, so a sign-in whose `POST /api/login` came back 401 was
+ * counted as a check that held. Applied to the top-level claim of a wait or an assert.
+ */
+export function requestMustSucceed(args) {
+    const out = { ...args };
+    for (const key of ['until', 'predicate']) {
+        const claim = args[key];
+        if ('object' !== typeof claim || null === claim)
+            continue;
+        const p = claim;
+        if (PredicateKind.NET === p['kind'] && undefined === p['status'] && undefined === p['ok'])
+            out[key] = { ...p, ok: true };
+    }
+    return out;
+}
 /**
  * Stamp the drive's own session onto a call.
  *

package/dist/surface/tools/human-notes.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The notes a person sent from the HUD, handed to the agent on whatever Reticle call it makes next.
+ *
+ * Act tools already splice them (`withControl`); every other tool did not, so a note waited until
+ * the agent happened to drive the page or poll `messages`. Taken here, once, from the tab the call
+ * is about; a call that names no tab and cannot resolve one takes every tab's, since a note held
+ * back is a note the person believes was read.
+ */
+import type { Session } from '../../portal/session/session.js';
+import type { SessionManager } from '../../portal/session/session-manager.js';
+import type { SessionState } from '@reticlehq/core';
+export interface HumanNotes {
+    state: SessionState;
+    guidance: string[];
+}
+export declare function takeHumanNotes(sessions: SessionManager, sessionId: string | undefined, session: Session | undefined): HumanNotes | undefined;

package/dist/surface/tools/human-notes.js

@@ -0,0 +1,27 @@
+export function takeHumanNotes(sessions, sessionId, session) {
+    let target = session;
+    if (target === undefined) {
+        try {
+            target = sessions.resolve(sessionId);
+        }
+        catch {
+            target = undefined;
+        }
+    }
+    // ponytail: an unresolvable call takes every tab's notes; per-agent routing is the upgrade if two
+    // agents ever share one daemon on different apps and a note lands with the wrong one.
+    try {
+        const holding = (target === undefined ? (sessions.all?.() ?? []) : [target]).filter((tab) => 0 < tab.inboxSize());
+        const first = holding[0];
+        if (first === undefined)
+            return undefined;
+        return {
+            state: first.getState(),
+            guidance: holding.flatMap((tab) => tab.drainInbox().map((message) => message.text)),
+        };
+    }
+    catch {
+        // A courtesy on every call is never the reason a call fails; the notes stay queued.
+        return undefined;
+    }
+}

package/dist/surface/tools/invoke-tool.d.ts

@@ -1,4 +1,5 @@
-import type { ToolDef, ToolDeps } from './tool-kit.js';
+import { type NoticeFold } from './agent/notices.js';
+import type { ToolCall, ToolDef, ToolDeps } from './tool-kit.js';
 export declare const SESSION_BOUND_TOOLS: ReadonlySet<string>;
 /**
  * Tools that carry a `sessionId` arg but are NOT live-session-health tools — they read/write
@@ -7,4 +8,6 @@ export declare const SESSION_BOUND_TOOLS: ReadonlySet<string>;
  * `sessionId`-bearing tool to be classified into exactly one set (bound XOR exempt).
  */
 export declare const SESSION_EXEMPT_TOOLS: ReadonlySet<string>;
-export declare function runTool<Ext>(tool: ToolDef<Ext>, deps: ToolDeps<Ext>, args: Record<string, unknown>): Promise<unknown>;
+export declare function runTool<Ext>(tool: ToolDef<Ext>, deps: ToolDeps<Ext>, given: Record<string, unknown>, call?: ToolCall): Promise<unknown>;
+/** Advisories that become once-per-session notice lines. See agent/notices.ts. */
+export declare const NOTICE_FOLD: NoticeFold;