@reticlehq/server 3.5.0 → 3.7.0

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

@@ -0,0 +1,88 @@
+import type { ToolDeps } from './tool-kit.js';
+import { type ConfigFetch } from '../../features/harness/platform-config.js';
+/** What the platform half of the gate reads off a drive's options; `ExploreOptions` satisfies it. */
+export interface HarnessAsk {
+    skipPlatformConfig?: boolean;
+    configFetch?: ConfigFetch;
+    planId?: string;
+}
+/**
+ * Why the harness is unavailable, phrased as the way to make it available.
+ *
+ * A missing key is a configuration fact, not a fault, and the sentence a user reads has to tell them
+ * the one thing to do about it. Named here because both the CLI and the honest no-flows refusal
+ * print it, and two copies of this sentence would drift.
+ */
+export declare const MSG_NO_HARNESS_KEY: string;
+/**
+ * The environment, plus the credential this machine already has.
+ *
+ * `reticle link` mints a project-scoped key and files it in `~/.reticle/credentials.json`; the CLI
+ * has read it from there for as long as it has existed. The harness did not, and read only
+ * `process.env` — so somebody who had signed in, linked their project and been told they were
+ * connected still got "no model configured to drive the app", and the only way out was to find the
+ * key in the console and export it by hand. Five manual steps to reach a feature they had already
+ * finished setting up.
+ *
+ * Resolved into the env rather than threaded through four call sites: the drivers and the
+ * preference lookup all read an env record, and giving them a completed one leaves each of them
+ * exactly as simple as it was. The key precedence is the resolver's, the same as sync's and the
+ * CLI's: the stored key for the link's host, else the exported one (which is how CI, with no
+ * keystore, gets here). An explicitly exported HOST still wins, so a proxy is not overridden.
+ *
+ * The credential arrives through `deps.linkedCloud`, a port, because resolving it here would make
+ * the tool surface reach into `memory/cloud` — a reach the directory guard refused, correctly.
+ */
+export declare function withLinkedCredential(deps: ToolDeps, env: Record<string, string | undefined>, 
+/**
+ * The tab a drive is for: its own project's link, not the daemon's. A plan saved with the
+ * daemon's key while its runs synced under the tab's project left every run link of the plan
+ * "Run unavailable". Absent: the daemon's own link.
+ */
+tab?: {
+    sessionId: string | undefined;
+}): Promise<Record<string, string | undefined>>;
+/** Introduces the prompt under a coverage refusal, so the agent knows it is for itself. */
+export declare const MSG_GATE_PROMPT_LEAD = "To unlock it, do this (or hand it to your coding agent):";
+/**
+ * Why the Harness must not drive this tab's app yet, or undefined when it may: below the coverage
+ * gate (core's `instrumentation-coverage.ts`), one reason sentence and the prompt that closes it. Every Harness
+ * start passes here (an agent's explore, Run Harness, `reticle try`, the platform's chat), so the
+ * gate holds wherever a drive starts; every other tool works at any coverage. A tab that cannot be
+ * resolved is not refused here: the drive itself answers for a missing tab. Counted once per refusal.
+ */
+export declare function coverageRefusal(deps: ToolDeps, sessionId: string | undefined): string | undefined;
+/**
+ * The gate a Harness start obeys. When the project is linked, the platform's verdict is the one
+ * source of truth: it locks a run mid-drive on the same report, so a daemon that refused what the
+ * platform unlocked showed two scores for one project. The daemon's own reading only refuses when
+ * the platform said nothing (not linked, unreachable, an older API) or said locked too, in which
+ * case the daemon's sentence names what this tab can fix.
+ */
+export declare function harnessLockRefusal(deps: ToolDeps, sessionId: string | undefined, env: Record<string, string | undefined>, fetchConfig?: ConfigFetch): Promise<string | undefined>;
+/**
+ * Can this machine reach the Harness? Only through the platform: a linked project or a platform
+ * key. Whether the workspace is entitled is the platform's answer, asked when the drive starts.
+ */
+export declare function harnessAvailable(env: Record<string, string | undefined>): boolean;
+/**
+ * The reason this drive must not start, or `undefined` to go ahead.
+ *
+ * A drive on somebody's OWN model key never waits on the platform beyond the off switch: their key,
+ * their spend. A drive through the platform proxy bills Reticle, and that one needs a confirmed yes
+ * — enabled, entitled, and a model ready. It used to fail open: `fetchPlatformConfig` answers
+ * `undefined` on a network error, a non-2xx, a body that does not parse, or a two-second timeout,
+ * and all four read as "carry on", so a slow second on a settings endpoint let an unentitled
+ * workspace drive on Reticle's budget. Now the same silence refuses with a message that says to
+ * retry or bring a key. Fields an older platform omits still default to yes inside
+ * `fetchPlatformConfig`; only an answer that never arrived is a no.
+ */
+export declare function refusedByPlatform(env: Record<string, string | undefined>, options: HarnessAsk): Promise<string | undefined>;
+/**
+ * `refusedByPlatform`, for a run that may be a saved plan. A plan that only replays saved flows
+ * spends no model turn, so a model drive's gates do not stop it; a refused plan is still reported to
+ * the plan, every journey blocked with the reason, so its history records the attempt.
+ */
+export declare function refusedForPlan(env: Record<string, string | undefined>, options: HarnessAsk): Promise<string | undefined>;
+/** The sentence a refusal leads with, without the prompt that follows it. */
+export declare const firstLine: (text: string) => string;

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

@@ -0,0 +1,235 @@
+/**
+ * Whether the Harness may drive at all, and with which credential — answered before a drive starts.
+ *
+ * Split from `harness-explore.ts`, which runs the drive. This is the gate every Harness start passes
+ * through (an agent's explore, Run Harness, `reticle try`, the platform's chat): the linked
+ * credential, the instrumentation-coverage lock, and the platform's own yes or no.
+ */
+import { reportAppsNow } from '../../features/harness/platform/local-apps.js';
+import { serverOptionsFromEnv } from '../../features/harness/platform/server-driver.js';
+import { ReticleEnv, cloudUrlFrom } from '@reticlehq/core';
+import { creditsSpent, creditsUsedLine } from '@reticlehq/core/hud';
+import { planUrl } from '../../features/harness/platform/platform-drives.js';
+import { isUnmatchedRoot } from '../../memory/project/dir/reticle-dir.js';
+import { sessionRoot } from '../../memory/project/session-root.js';
+import { fetchPlatformConfig } from '../../features/harness/platform-config.js';
+import { reportPlanBlocked, savedPlanDrivesNothing } from '../../features/harness/platform/script.js';
+import { instrumentationOf, probeMarkers } from '../../portal/session/recorded-gaps.js';
+import { getSessionMetrics } from '../../telemetry/session-metrics.js';
+import { MSG_HARNESS_DISABLED, MSG_HARNESS_UNCLAIMED, MSG_HARNESS_UNCONFIRMED, } from '../../features/harness/platform/refusal.js';
+/**
+ * Why the harness is unavailable, phrased as the way to make it available.
+ *
+ * A missing key is a configuration fact, not a fault, and the sentence a user reads has to tell them
+ * the one thing to do about it. Named here because both the CLI and the honest no-flows refusal
+ * print it, and two copies of this sentence would drift.
+ */
+export const MSG_NO_HARNESS_KEY = `The Reticle Harness runs on the Reticle platform, and a new account gets 10 free credits ` +
+    `to try it: run \`reticle connect\` to link this project and sign in. ` +
+    `Without it, drive the journey yourself with reticle_act_and_wait and an \`until\` on its last step: ` +
+    `what you drive is saved as a flow just the same.`;
+/**
+ * The environment, plus the credential this machine already has.
+ *
+ * `reticle link` mints a project-scoped key and files it in `~/.reticle/credentials.json`; the CLI
+ * has read it from there for as long as it has existed. The harness did not, and read only
+ * `process.env` — so somebody who had signed in, linked their project and been told they were
+ * connected still got "no model configured to drive the app", and the only way out was to find the
+ * key in the console and export it by hand. Five manual steps to reach a feature they had already
+ * finished setting up.
+ *
+ * Resolved into the env rather than threaded through four call sites: the drivers and the
+ * preference lookup all read an env record, and giving them a completed one leaves each of them
+ * exactly as simple as it was. The key precedence is the resolver's, the same as sync's and the
+ * CLI's: the stored key for the link's host, else the exported one (which is how CI, with no
+ * keystore, gets here). An explicitly exported HOST still wins, so a proxy is not overridden.
+ *
+ * The credential arrives through `deps.linkedCloud`, a port, because resolving it here would make
+ * the tool surface reach into `memory/cloud` — a reach the directory guard refused, correctly.
+ */
+export async function withLinkedCredential(deps, env, 
+/**
+ * The tab a drive is for: its own project's link, not the daemon's. A plan saved with the
+ * daemon's key while its runs synced under the tab's project left every run link of the plan
+ * "Run unavailable". Absent: the daemon's own link.
+ */
+tab) {
+    try {
+        const root = tab === undefined ? undefined : tabRoot(deps, tab);
+        // A tab whose page reported no project (its root is `unmatched/`) is nobody else's: it drives on
+        // the daemon's own link, never "run reticle connect" to a project that is linked.
+        const own = root !== undefined && isUnmatchedRoot(root) ? undefined : root;
+        const linked = await deps.linkedCloud?.(own);
+        if (linked === undefined || null === linked)
+            return env;
+        return {
+            ...env,
+            [ReticleEnv.API_KEY]: linked.apiKey,
+            [ReticleEnv.CLOUD_URL]: cloudUrlFrom(env) ?? linked.url,
+        };
+    }
+    catch {
+        // A credential store that cannot be read is "not linked", not an error. The harness is optional
+        // and its absence is a routine answer; a drive must never fail because a JSON file was odd.
+        return env;
+    }
+}
+/** A tab's `.reticle`, or undefined (the daemon's) when the tab cannot be resolved to one. */
+function tabRoot(deps, tab) {
+    try {
+        return sessionRoot(deps, tab.sessionId);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Introduces the prompt under a coverage refusal, so the agent knows it is for itself. */
+export const MSG_GATE_PROMPT_LEAD = 'To unlock it, do this (or hand it to your coding agent):';
+/**
+ * Why the Harness must not drive this tab's app yet, or undefined when it may: below the coverage
+ * gate (core's `instrumentation-coverage.ts`), one reason sentence and the prompt that closes it. Every Harness
+ * start passes here (an agent's explore, Run Harness, `reticle try`, the platform's chat), so the
+ * gate holds wherever a drive starts; every other tool works at any coverage. A tab that cannot be
+ * resolved is not refused here: the drive itself answers for a missing tab. Counted once per refusal.
+ */
+export function coverageRefusal(deps, sessionId) {
+    const refused = localGateRefusal(deps, sessionId);
+    if (refused !== undefined)
+        getSessionMetrics().recordHarnessRefused(refused.percent);
+    return refused?.text;
+}
+/** This tab and every other live tab of its app, or undefined when the tab cannot be resolved. */
+function appTabsOf(deps, sessionId) {
+    let tab;
+    try {
+        tab = deps.sessions.resolve(sessionId);
+    }
+    catch {
+        return undefined;
+    }
+    // Every tab of the app, the way the platform's merged report reads it, so the two name the same
+    // missing items.
+    const siblings = (deps.sessions.list?.() ?? [])
+        .filter((info) => info.sessionId !== tab.id && sameApp(info.projectId, tab.projectId))
+        .flatMap((info) => {
+        const live = deps.sessions.get?.(info.sessionId);
+        return live === undefined ? [] : [live];
+    });
+    return { tab, siblings };
+}
+/** The daemon's own reading of the gate for this tab's app, uncounted. */
+function localGateRefusal(deps, sessionId) {
+    const app = appTabsOf(deps, sessionId);
+    if (app === undefined)
+        return undefined;
+    const { tab } = app;
+    const siblings = app.siblings.map((live) => ({
+        id: live.id,
+        url: live.url,
+        projectId: live.projectId,
+        channels: live.channels,
+        sourceMapping: live.sourceMapping,
+    }));
+    const coverage = instrumentationOf(tab, siblings);
+    const gate = coverage.harnessGate;
+    if (gate.unlocked || gate.reason === undefined)
+        return undefined;
+    const text = coverage.prompt === undefined
+        ? gate.reason
+        : `${gate.reason}\n\n${MSG_GATE_PROMPT_LEAD}\n${coverage.prompt}`;
+    return { text, percent: gate.percent };
+}
+/**
+ * The gate a Harness start obeys. When the project is linked, the platform's verdict is the one
+ * source of truth: it locks a run mid-drive on the same report, so a daemon that refused what the
+ * platform unlocked showed two scores for one project. The daemon's own reading only refuses when
+ * the platform said nothing (not linked, unreachable, an older API) or said locked too, in which
+ * case the daemon's sentence names what this tab can fix.
+ */
+export async function harnessLockRefusal(deps, sessionId, env, fetchConfig) {
+    // What the app's pages carry decides, not what an act happened to reach: ask them first.
+    const app = appTabsOf(deps, sessionId);
+    // Learned something: the platform hears it before it is asked, or it refuses on its old score.
+    if (app !== undefined && (await probeMarkers([app.tab, ...app.siblings])))
+        await reportAppsNow().catch(() => undefined);
+    if (undefined === localGateRefusal(deps, sessionId))
+        return undefined;
+    const platform = await fetchPlatformConfig(env, fetchConfig);
+    if (true === platform?.gate?.unlocked)
+        return undefined;
+    return coverageRefusal(deps, sessionId);
+}
+/** Two tabs are one app when both name the same project. A tab that names none stands alone. */
+const sameApp = (a, b) => a !== undefined && a === b;
+/**
+ * Can this machine reach the Harness? Only through the platform: a linked project or a platform
+ * key. Whether the workspace is entitled is the platform's answer, asked when the drive starts.
+ */
+export function harnessAvailable(env) {
+    return serverOptionsFromEnv(env) !== undefined;
+}
+/** One read, however many questions are asked of the answer. */
+function platformConfig(env, options) {
+    return options.configFetch === undefined
+        ? fetchPlatformConfig(env)
+        : fetchPlatformConfig(env, options.configFetch);
+}
+/**
+ * The reason this drive must not start, or `undefined` to go ahead.
+ *
+ * A drive on somebody's OWN model key never waits on the platform beyond the off switch: their key,
+ * their spend. A drive through the platform proxy bills Reticle, and that one needs a confirmed yes
+ * — enabled, entitled, and a model ready. It used to fail open: `fetchPlatformConfig` answers
+ * `undefined` on a network error, a non-2xx, a body that does not parse, or a two-second timeout,
+ * and all four read as "carry on", so a slow second on a settings endpoint let an unentitled
+ * workspace drive on Reticle's budget. Now the same silence refuses with a message that says to
+ * retry or bring a key. Fields an older platform omits still default to yes inside
+ * `fetchPlatformConfig`; only an answer that never arrived is a no.
+ */
+export async function refusedByPlatform(env, options) {
+    if (true === options.skipPlatformConfig)
+        return undefined;
+    // No platform, no Harness: it runs there, on the workspace's credits.
+    if (serverOptionsFromEnv(env) === undefined)
+        return MSG_NO_HARNESS_KEY;
+    const config = await platformConfig(env, options);
+    // It needs a confirmed yes, not the absence of a no. The platform also checks on every turn.
+    if (config === undefined)
+        return MSG_HARNESS_UNCONFIRMED;
+    // The project-wide lock before the switch: a fresh tab passes the per-tab gate with no gaps
+    // recorded, and "off" hid the one refusal that names its fix.
+    const gate = config.gate;
+    if (false === gate?.unlocked && gate.reason !== undefined)
+        return gate.prompt === undefined
+            ? gate.reason
+            : `${gate.reason}\n\n${MSG_GATE_PROMPT_LEAD}\n${gate.prompt}`;
+    if (!config.harnessEnabled)
+        return MSG_HARNESS_DISABLED;
+    // Before entitlement: no credits left is why most workspaces are not entitled, said as the HUD says it.
+    if (config.credits !== undefined && creditsSpent(config.credits))
+        return creditsUsedLine(config.credits, 
+        // The platform's own page; built from the API origin only for a platform that names none.
+        config.planUrl ?? planUrl(config.platformUrl ?? cloudUrlFrom(env) ?? ''));
+    if (!config.harnessEntitled)
+        return MSG_HARNESS_UNCLAIMED;
+    return undefined;
+}
+/**
+ * `refusedByPlatform`, for a run that may be a saved plan. A plan that only replays saved flows
+ * spends no model turn, so a model drive's gates do not stop it; a refused plan is still reported to
+ * the plan, every journey blocked with the reason, so its history records the attempt.
+ */
+export async function refusedForPlan(env, options) {
+    const planId = options.planId;
+    const platform = serverOptionsFromEnv(env);
+    if (planId === undefined || platform === undefined)
+        return refusedByPlatform(env, options);
+    if (await savedPlanDrivesNothing(platform, planId))
+        return undefined;
+    const refusal = await refusedByPlatform(env, options);
+    if (refusal !== undefined)
+        await reportPlanBlocked(platform, planId, firstLine(refusal));
+    return refusal;
+}
+/** The sentence a refusal leads with, without the prompt that follows it. */
+export const firstLine = (text) => text.split('\n')[0] ?? text;

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

@@ -0,0 +1,43 @@
+import type { RunDisparity } from '@reticlehq/core';
+import type { HarnessMap } from '@reticlehq/core/artifacts';
+import { type Goal, type GoalCheck } from '../../features/harness/goals.js';
+import type { ToolOutcome } from '../../features/harness/harness.js';
+import type { Invoke } from '../../features/harness/explore/page-tree.js';
+import type { ToolDeps } from './tool-kit.js';
+/** The pages a map knows, by route: what a drive is pointed at before it guesses. */
+export declare const knownRoutes: (map: HarnessMap | undefined) => string[];
+/** The app's map: the kept one while it is fresh, else a new survey merged over it. */
+export declare function siteMapFor(deps: ToolDeps, sessionId: string | undefined, invoke: Invoke): Promise<HarnessMap | undefined>;
+/** What a drive read, folded into the kept map, so the map grows from use. */
+export declare function refreshMap(deps: ToolDeps, sessionId: string | undefined, map: HarnessMap | undefined, calls: readonly ToolOutcome[]): Promise<void>;
+/** A drive's goals as graded, and how each compared with the agent's verdict. */
+export interface Graded {
+    goals: GoalCheck[];
+    disparity: RunDisparity[];
+    /** The navigations and clicks the hunt made: the Harness driving the app, said as such. */
+    moved: ToolOutcome[];
+}
+/**
+ * One grade from each lane's: per goal, the lane that proved it, else one that disproved it on its
+ * own page, else the first. A plan's lane that reached the end text proved it, whatever the others
+ * (a known-defects lane, a lane on another page) saw.
+ */
+export declare function bestOfLanes(lanes: readonly Graded[]): Graded;
+/**
+ * The goals graded after a hunt for the journey's end. The end is the last goal the page did not
+ * already show; when the hunt does not find it the check is undecided and says where it looked.
+ */
+export declare function huntAndGrade(deps: ToolDeps, driving: Invoke, ask: {
+    sessionId?: string | undefined;
+    goals: readonly (string | Goal)[];
+    expect?: Record<string, unknown> | undefined;
+    opening?: string | undefined;
+    journey?: string | undefined;
+    map?: HarnessMap | undefined;
+    /** Text the Harness wrote besides the journey: its plan's journeys, its flows' names. */
+    own?: readonly string[] | undefined;
+    /** The pages the drive reached (`pagesReached`), searched when the end is not where it stopped. */
+    reached?: readonly string[] | undefined;
+    /** The values the drive typed (`typedValues`): inputs, graded only when one is the end. */
+    typed?: readonly string[] | undefined;
+}): Promise<Graded>;

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

@@ -0,0 +1,215 @@
+/**
+ * The exploratory Harness around a drive: map the app first, hunt for the goal before grading it,
+ * and compare the verdict with the coding agent's. The drive itself is the platform's; these are the
+ * daemon's deterministic halves, shared by the planned and the unplanned path.
+ */
+import { dirname, join } from 'node:path';
+import { checkExpect, checkGoals, endGoalsOf, } from '../../features/harness/goals.js';
+import { ReticleTool } from '@reticlehq/core';
+import { searchForGoal } from '../../features/harness/explore/goal-search.js';
+import { MAP_FRESH_MS, mergePages, pagesReadIn, parseMap, surveyApp, } from '../../features/harness/explore/site-map.js';
+import { agentVerdictsIn, disparityFor } from '../../features/harness/explore/disparity.js';
+import { reticleDirPaths } from '../../memory/project/dir/reticle-dir.js';
+import { sessionRoot } from '../../memory/project/session-root.js';
+import { JournalActionSchema, ReticleDir, Verified, VerifiedReason, } from '@reticlehq/core';
+import { isValidSessionId } from '../../memory/project/dir/reticle-dir.js';
+/**
+ * Kept beside the plans: what this machine's drives learned about the app, local like them.
+ * ponytail: a file in `plans/`, not a new `.reticle/` name, which would need the workspace tiers
+ * and the ignore file to learn it; give it its own name if it ever needs to be shared.
+ */
+const HARNESS_MAP_FILE = 'harness-map.json';
+/** Fewer pages than this and the kept map is not a map of the app. */
+const MIN_MAPPED_PAGES = 2;
+/** Sessions read from disk for the agent's verdicts: the recent past of one project, not its history. */
+const MAX_JOURNALS_READ = 40;
+function mapPath(deps, sessionId) {
+    try {
+        return join(reticleDirPaths(sessionRoot(deps, sessionId)).plans, HARNESS_MAP_FILE);
+    }
+    catch {
+        return undefined;
+    }
+}
+async function readMap(deps, path) {
+    try {
+        return parseMap(await deps.fs.readFile(path));
+    }
+    catch {
+        return undefined;
+    }
+}
+async function writeMap(deps, path, map) {
+    try {
+        await deps.fs.mkdir(dirname(path));
+        await deps.fs.writeFile(path, `${JSON.stringify(map, null, 2)}\n`);
+    }
+    catch {
+        /* a map that cannot be kept is surveyed again next time */
+    }
+}
+/** The pages a map knows, by route: what a drive is pointed at before it guesses. */
+export const knownRoutes = (map) => map === undefined ? [] : [...new Set(map.pages.map((page) => page.route))];
+/** The app's map: the kept one while it is fresh, else a new survey merged over it. */
+export async function siteMapFor(deps, sessionId, invoke) {
+    const path = mapPath(deps, sessionId);
+    const kept = path === undefined ? undefined : await readMap(deps, path);
+    // A map of one page is a survey that saw nothing (a menu was open): it is surveyed again.
+    if (kept !== undefined &&
+        MIN_MAPPED_PAGES <= kept.pages.length &&
+        deps.now() - kept.surveyedAt < MAP_FRESH_MS)
+        return kept;
+    const surveyed = await surveyApp(invoke, deps.now);
+    if (surveyed === undefined)
+        return kept;
+    const map = kept === undefined ? surveyed : mergePages(kept, surveyed.pages, surveyed.surveyedAt);
+    if (path !== undefined)
+        await writeMap(deps, path, map);
+    return map;
+}
+/** What a drive read, folded into the kept map, so the map grows from use. */
+export async function refreshMap(deps, sessionId, map, calls) {
+    const path = mapPath(deps, sessionId);
+    if (path === undefined || map === undefined)
+        return;
+    const read = pagesReadIn(calls, deps.now());
+    if (0 < read.length)
+        await writeMap(deps, path, mergePages(map, read));
+}
+/**
+ * The decided verdicts the connected agent made on this app: in its live tabs, and in the journals
+ * on disk of tabs that have closed. Persona 21's agent proved both goals on a tab that had closed by
+ * the time the Harness graded, and the comparison was never made.
+ */
+async function agentVerdicts(deps, sessionId) {
+    let projectId;
+    let own;
+    try {
+        const tab = deps.sessions.resolve(sessionId);
+        projectId = tab.projectId;
+        own = tab.id;
+    }
+    catch {
+        return [];
+    }
+    const tabs = deps.sessions
+        .all()
+        .filter((s) => s.id === own || (projectId !== undefined && s.projectId === projectId));
+    const live = await Promise.all(tabs.map((s) => s.readJournalActions().catch(() => [])));
+    const onDisk = await journalsOnDisk(deps, sessionId, new Set(tabs.map((s) => s.id)));
+    return agentVerdictsIn([...live.flat(), ...onDisk]);
+}
+/** A journal's lines as actions; a line that does not parse is left out, as the journal reader does. */
+function actionsIn(text) {
+    return text.split('\n').flatMap((line) => {
+        if (0 === line.trim().length)
+            return [];
+        try {
+            const parsed = JournalActionSchema.safeParse(JSON.parse(line));
+            return parsed.success ? [parsed.data] : [];
+        }
+        catch {
+            return [];
+        }
+    });
+}
+/** The actions of this project's sessions that are no longer live, from their journals. */
+async function journalsOnDisk(deps, sessionId, live) {
+    try {
+        const root = sessionRoot(deps, sessionId);
+        const ids = (await deps.fs.readdir(reticleDirPaths(root).sessions))
+            .filter((id) => !live.has(id) && isValidSessionId(id))
+            .slice(-MAX_JOURNALS_READ);
+        const read = await Promise.all(ids.map((id) => deps.fs
+            .readFile(join(reticleDirPaths(root).sessions, id, ReticleDir.JOURNAL_ACTIONS_FILE))
+            .then(actionsIn)
+            .catch(() => [])));
+        return read.flat();
+    }
+    catch {
+        return [];
+    }
+}
+/** What the hunt does to the app. Its asserts are not kept here: they would count as checks. */
+const HUNT_MOVES = new Set([ReticleTool.NAVIGATE, ReticleTool.ACT]);
+/** The invoke, keeping each move it makes. */
+function keepingMoves(invoke, moved) {
+    return async (name, args) => {
+        const result = await invoke(name, args);
+        if (HUNT_MOVES.has(name))
+            moved.push({ id: `hunt-${String(moved.length + 1)}`, name, args, result, isError: false });
+        return result;
+    };
+}
+const RANK = { [Verified.YES]: 0, [Verified.NO]: 1 };
+/**
+ * One grade from each lane's: per goal, the lane that proved it, else one that disproved it on its
+ * own page, else the first. A plan's lane that reached the end text proved it, whatever the others
+ * (a known-defects lane, a lane on another page) saw.
+ */
+export function bestOfLanes(lanes) {
+    const first = lanes[0] ?? { goals: [], disparity: [], moved: [] };
+    const goals = first.goals
+        .map((_, i) => {
+        const all = lanes.flatMap((l) => (l.goals[i] === undefined ? [] : [l.goals[i]]));
+        return ([...all].sort((a, b) => (RANK[a.verified] ?? 2) - (RANK[b.verified] ?? 2))[0] ??
+            first.goals[i]);
+    })
+        .filter((g) => g !== undefined);
+    const disparity = goals.flatMap((g) => {
+        const lane = lanes.find((l) => l.goals.includes(g));
+        return lane?.disparity.filter((d) => d.goal === g.text) ?? [];
+    });
+    return { goals, disparity, moved: lanes.flatMap((l) => l.moved) };
+}
+/**
+ * The goals graded after a hunt for the journey's end. The end is the last goal the page did not
+ * already show; when the hunt does not find it the check is undecided and says where it looked.
+ */
+export async function huntAndGrade(deps, driving, ask) {
+    const moved = [];
+    const invoke = keepingMoves(driving, moved);
+    // The journey names the plan and the flows this run saves: shown back on a page, it proves nothing.
+    const own = [...(ask.own ?? []), ...(ask.journey === undefined ? [] : [ask.journey])];
+    const goals = endGoalsOf(ask.goals.map((g) => ('string' === typeof g ? { text: g } : g)), ask.typed ?? []);
+    const end = goals
+        .filter((g) => true !== g.absent && true !== ask.opening?.includes(g.text))
+        .at(-1);
+    const hunt = (goal) => searchForGoal(invoke, {
+        goal,
+        ...(ask.journey === undefined ? {} : { journey: ask.journey }),
+        ...(ask.map === undefined ? {} : { map: ask.map }),
+        ...(ask.reached === undefined ? {} : { reached: ask.reached }),
+        own,
+    });
+    const search = end === undefined ? undefined : await hunt(end.text);
+    // The end not found anywhere: the tab is left where an earlier goal is, so that one is graded
+    // where it shows rather than where the hunt gave up.
+    if (search !== undefined && !search.found)
+        for (const earlier of goals.filter((g) => g !== end && true !== g.absent).reverse())
+            if ((await hunt(earlier.text)).found)
+                break;
+    const checks = (await checkGoals(invoke, goals, ask.opening, own)).map((c) => end !== undefined &&
+        c.text === end.text &&
+        Verified.YES !== c.verified &&
+        search !== undefined &&
+        !search.found
+        ? {
+            ...c,
+            reason: `${VerifiedReason.INCONCLUSIVE}: not found after searching ${search.searched.join(' → ')}`,
+        }
+        : c);
+    const agent = await agentVerdicts(deps, ask.sessionId);
+    const disparity = checks.flatMap((c) => {
+        const d = disparityFor(c, agent, c.text === end?.text ? search : undefined);
+        return d === undefined ? [] : [d];
+    });
+    return {
+        goals: [
+            ...checks,
+            ...(ask.expect === undefined ? [] : [await checkExpect(invoke, ask.expect)]),
+        ],
+        disparity,
+        moved,
+    };
+}

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

@@ -74,3 +74,20 @@ export declare function buildHarnessPlan(domain: DomainModel): HarnessPlan;
  * so it can prefer finishing the cheap deterministic half before spending itself on the rest.
  */
 export declare function planAsText(plan: HarnessPlan): string;
+/**
+ * The plan a model drives from: the gaps only. Saved flows are replayed by the plan's own lanes, or
+ * not at all when a person named the journey; a model handed them replayed every one, unrelated to
+ * the journey it was asked for, and spent most of its drive there.
+ */
+export declare function withoutReplays(plan: HarnessPlan): HarnessPlan;
+/**
+ * The plan a drive is handed: the gaps, or nothing beside a journey a person named. A named run was
+ * handed every other session's open intents too, and named its flow after one of them.
+ */
+export declare function drivingPlan(plan: HarnessPlan, focus: string | undefined): HarnessPlan;
+/**
+ * What the planner is told about the product: the plan from `.reticle`, then the app's own controls
+ * as they are on screen now. With only the plan, an empty project read "PLAN: none" and the planner
+ * proposed generic people (an admin, a sign-in journey) for an app that has neither.
+ */
+export declare function aboutTheApp(planText: string, invoke: (name: string, args: Record<string, unknown>) => Promise<unknown>, seenBefore?: readonly string[]): Promise<string>;

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

@@ -21,6 +21,7 @@
  * Nothing here calls a model. The plan is the deterministic half, and the model's only job is to
  * choose among steps somebody already decided were worth taking.
  */
+import { ReticleTool } from '@reticlehq/core';
 export const PlanStepKind = {
     /** Already recorded: replay it deterministically instead of paying a model to rediscover it. */
     REPLAY: 'replay',
@@ -154,3 +155,40 @@ export function planAsText(plan) {
     const lines = plan.steps.map((step, index) => ` ${String(index + 1)}. [${step.kind}] ${step.target} — ${step.why}`);
     return `PLAN (from .reticle, not from the source):\n${lines.join('\n')}`;
 }
+/**
+ * The plan a model drives from: the gaps only. Saved flows are replayed by the plan's own lanes, or
+ * not at all when a person named the journey; a model handed them replayed every one, unrelated to
+ * the journey it was asked for, and spent most of its drive there.
+ */
+export function withoutReplays(plan) {
+    return { ...plan, steps: plan.steps.filter((step) => PlanStepKind.DRIVE === step.kind) };
+}
+/**
+ * The plan a drive is handed: the gaps, or nothing beside a journey a person named. A named run was
+ * handed every other session's open intents too, and named its flow after one of them.
+ */
+export function drivingPlan(plan, focus) {
+    return focus === undefined ? withoutReplays(plan) : { ...plan, steps: [] };
+}
+/** How much of the live page the planner reads. Enough for a dashboard's nav and main controls. */
+const MAX_ABOUT_SNAPSHOT = 6_000;
+/**
+ * What the planner is told about the product: the plan from `.reticle`, then the app's own controls
+ * as they are on screen now. With only the plan, an empty project read "PLAN: none" and the planner
+ * proposed generic people (an admin, a sign-in journey) for an app that has neither.
+ */
+export async function aboutTheApp(planText, invoke, seenBefore = []) {
+    const seen = 0 === seenBefore.length
+        ? ''
+        : `\n\nCONTROLS SEEN ACROSS THE WHOLE APP LAST TIME, BY PAGE (not only this page):\n${seenBefore.join('\n')}`;
+    try {
+        const snap = await invoke(ReticleTool.SNAPSHOT, { mode: 'interactive' });
+        const tree = 'object' === typeof snap && null !== snap ? snap.tree : undefined;
+        if ('string' !== typeof tree || 0 === tree.length)
+            return `${planText}${seen}`;
+        return `${planText}\n\nTHE APP AS IT IS ON SCREEN NOW (its own controls, in its own words):\n${tree.slice(0, MAX_ABOUT_SNAPSHOT)}${seen}`;
+    }
+    catch {
+        return `${planText}${seen}`;
+    }
+}