@reticlehq/server 3.5.0 → 3.6.0

package/dist/surface/tools/empty-session-list.js

@@ -0,0 +1,80 @@
+/**
+ * What `reticle_session { action: "list" }` answers when nothing is connected.
+ *
+ * An empty list is the most common thing that tool returns, and on its own it is a dead end: the
+ * agent asked the one question it knows to ask and got no next step. So it carries why nothing is
+ * connected, the executable next action, the last tab that was here, and, on a project that has
+ * never connected, the first-run wiring itself (see first-run-wiring.ts).
+ */
+import { dirname } from 'node:path';
+import { z } from 'zod';
+import { DiscoveryInvite, NoSessionAction } from '@reticlehq/core';
+/** The answers that mean "this app is not set up yet", which a first run can settle by wiring it. */
+const FIRST_RUN_ACTIONS = new Set([
+    NoSessionAction.RUN_INIT,
+    NoSessionAction.START_DEV_SERVER,
+    NoSessionAction.OPEN_APP,
+]);
+/** The fields only an empty list carries, declared so a schema-aware client does not strip them. */
+export const EMPTY_SESSION_LIST_OUTPUT = {
+    why: z
+        .string()
+        .optional()
+        .describe('Present ONLY when `sessions` is empty: why nothing is connected, and the next action that fixes it. An empty list is never the end of the road — read this before concluding the app cannot be driven.'),
+    next_action: z
+        .object({
+        action: z.nativeEnum(NoSessionAction),
+        command: z.string().optional(),
+        port: z.number().optional(),
+        reason: z.string(),
+    })
+        .optional()
+        .describe("Present ONLY when `sessions` is empty: the same answer as `why`, executable. `command` is the LITERAL command to run, sourced from this project's own package.json scripts and lockfile — it is absent, never guessed, when the project declares no dev script. `action` is one of daemon_split | start_dev_server | run_init | open_app | reopen_app. `daemon_split` outranks the rest and means the app IS running and instrumented, on a DIFFERENT daemon than the one you are attached to — do not start or re-init anything, read `reason`."),
+    talk_to_us: z
+        .string()
+        .optional()
+        .describe('Present ONLY when `sessions` is empty: a call with the founder for the person you are working with. Offer it; never act on it.'),
+    wired: z
+        .record(z.unknown())
+        .optional()
+        .describe('Files the first run changed (`steps`); tell the user.'),
+    lastKnown: z
+        .object({
+        sessionId: z.string(),
+        url: z.string(),
+    })
+        .optional()
+        .describe('Present ONLY when `sessions` is empty AND a tab was connected to this daemon earlier: the last sessionId and URL that tab was on when it disappeared. A route that 500s tears the page down and the SDK never reconnects — this is the last thing we knew, not a route-500 verdict. An empty list with no lastKnown is a tab that never arrived.'),
+};
+export async function emptySessionList(deps, sessions) {
+    const why = deps.sessions.noSessionHint();
+    // The executable half. `why` is for the human reading the transcript; this is the one the
+    // agent acts on, so it never has to parse a paragraph to find a command inside it.
+    const next = deps.sessions.noSessionNextAction();
+    // The first run wires the app, not the installation: the daemon runs init itself, once,
+    // in its own project, and says what it changed. A daemon outside any project asks instead.
+    // Not only on `run_init`: an unwired app whose dev server is not running yet answers
+    // `start_dev_server`, which is the commonest first run of all, and init starts that server itself.
+    // `projectDirectory` refuses a project that is already wired, so a wired app is never re-run.
+    const dir = next !== undefined && FIRST_RUN_ACTIONS.has(next.action)
+        ? deps.firstRun?.projectDirectory(dirname(deps.reticleRoot))
+        : undefined;
+    if (dir !== undefined && deps.firstRun !== undefined) {
+        const wired = await deps.firstRun.wire(dir);
+        const connected = deps.sessions.list();
+        if (wired.ok && 0 < connected.length)
+            return { sessions: connected, wired };
+        return { sessions, wired, ...(why === undefined ? {} : { why }) };
+    }
+    // The last tab, when one was here. Optional-call: test stubs of SessionManager predate it.
+    const known = deps.sessions.lastKnown?.();
+    const lastKnown = undefined === known ? undefined : { sessionId: known.id, url: known.url };
+    return {
+        sessions,
+        ...(why === undefined ? {} : { why }),
+        ...(next === undefined ? {} : { next_action: next }),
+        ...(undefined === lastKnown ? {} : { lastKnown }),
+        // Setup that never connects is where most people give up; it is the talk worth having.
+        talk_to_us: DiscoveryInvite.AGENT,
+    };
+}

package/dist/surface/tools/error-recovery.d.ts

@@ -66,6 +66,12 @@ export declare const RECOVERY: {
     readonly COMMAND_TIMEOUT: string;
     readonly FLOW_STEP_MISSING: string;
     readonly NO_POOL: string;
+    /**
+     * RETICLE_CHROMIUM_PATH names a browser the daemon cannot launch. The call was fine and so is the
+     * Playwright install, so neither a retry nor the install command can help: only the daemon's own
+     * environment can, and a running daemon keeps the values it started with.
+     */
+    readonly CHROMIUM_PATH: string;
     /**
      * The two ways a platform answer can refuse a drive. Neither is a fault, and both were telling the
      * agent that a perfectly understood refusal might be a defect in Reticle — which is how a person

package/dist/surface/tools/error-recovery.js

@@ -8,9 +8,10 @@
  * on stable, human-authored substrings of the thrown messages (see session-manager.ts, the flow/
  * baseline stores). No clock, no IO — unit-testable in isolation.
  */
-import { RefusalReason, TRANSPORT_LIMITS } from '@reticlehq/core';
+import { RefusalReason, ReticleEnv, TRANSPORT_LIMITS } from '@reticlehq/core';
 import { SELF_RECOVERING_MARKER } from '../../portal/session/no-session-diagnosis.js';
-import { chromiumInstallCommand, bundledPlaywrightVersion, } from '../../command/cli/doctor/browser/chromium-hint.js';
+import { BODY_CLAUSE_REFUSAL_OPENING } from '@reticlehq/engine/evidence/body-capture-remedy.js';
+import { CHROMIUM_PATH_REFUSAL_PREFIX, chromiumInstallCommand, bundledPlaywrightVersion, } from '../../command/cli/doctor/browser/chromium-hint.js';
 /** Marks where an over-long message had its middle removed. Named so tests assert it by value. */
 const ELISION = '… [elided] …';
 /**
@@ -33,11 +34,21 @@ function capMessage(message) {
     const keep = Math.floor((max - ELISION.length) / 2);
     return `${message.slice(0, keep)}${ELISION}${message.slice(message.length - keep)}`;
 }
+/**
+ * A fixed phrase as a pattern for the table below, which matches on phrasing.
+ *
+ * The phrase comes from the module that throws it rather than being retyped here, and a constant is
+ * still text: escaped so a future reword containing `(` or `?` cannot turn into a pattern that means
+ * something else — or fails to compile at import time, taking the whole surface with it.
+ */
+function literally(phrase) {
+    return new RegExp(phrase.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'), 'i');
+}
 /**
  * Messages that already spell out the exact retry, so any hint we add can only argue with them.
  *
  * The no-session diagnosis is one (it inspected the machine and named the cause). The native-input
- * refusal is the other: it names the tool, the argument and the follow-up call to make instead — and
+ * refusal is another: it names the tool, the argument and the follow-up call to make instead — and
  * it was still collecting the defect ask, inviting a bug report about a refusal that had just told
  * the agent precisely what to do.
  */
@@ -47,6 +58,11 @@ const SELF_RECOVERING = [
     // the current ids" to a message that just named them contradicts the shorter path it offers, and
     // a contradicted instruction is how one agent came to retry a dead id twelve times.
     { match: /Connected right now:/i, reason: RefusalReason.NO_SESSION },
+    // The body-clause pre-flight: nothing ran, no action was spent, and the message names the setting
+    // to switch on — or says the page's SDK predates it, which is a limit and not a defect either. It
+    // was collecting the defect ask on top of its own remedy, so the envelope contradicted itself and
+    // asked for a bug report about somebody's connect() options.
+    { match: literally(BODY_CLAUSE_REFUSAL_OPENING), reason: RefusalReason.UNSUPPORTED },
 ];
 /** A message that already carries its own concrete next action, so nothing should be appended. */
 function isSelfRecovering(message) {
@@ -199,6 +215,17 @@ export const RECOVERY = {
         chromiumInstallCommand(bundledPlaywrightVersion()) +
         '` if that is what is missing. Meanwhile drive ' +
         'a tab the human already has open — reticle_sessions lists them.',
+    /**
+     * RETICLE_CHROMIUM_PATH names a browser the daemon cannot launch. The call was fine and so is the
+     * Playwright install, so neither a retry nor the install command can help: only the daemon's own
+     * environment can, and a running daemon keeps the values it started with.
+     */
+    CHROMIUM_PATH: `Reticle cannot launch the browser ${ReticleEnv.CHROMIUM_PATH} names (the message above says ` +
+        'what is wrong with the path). The call itself was fine, so retrying it will not help, and ' +
+        'neither will installing Chromium. Ask the human to fix that path, or unset it to use ' +
+        "Playwright's own Chromium, in the environment the daemon starts from, then run " +
+        '`npx @reticlehq/server restart`. Meanwhile drive a tab the human already has open, which ' +
+        'reticle_sessions lists. This is configuration, not a Reticle defect: there is nothing to report.',
     /**
      * The two ways a platform answer can refuse a drive. Neither is a fault, and both were telling the
      * agent that a perfectly understood refusal might be a defect in Reticle — which is how a person
@@ -227,6 +254,7 @@ const REASON_OF = {
     THROTTLED: RefusalReason.NOT_READY,
     COMMAND_TIMEOUT: RefusalReason.NOT_READY,
     NO_POOL: RefusalReason.NOT_READY,
+    CHROMIUM_PATH: RefusalReason.NOT_READY,
     TOKEN_REQUIRED: RefusalReason.NOT_READY,
     MISSING_BASELINE: RefusalReason.NO_MATCH,
     MISSING_RECORDING: RefusalReason.NO_MATCH,
@@ -252,6 +280,11 @@ const REASON_OF = {
 const REASON_BY_HINT = new Map(Object.entries(RECOVERY).map(([key, hint]) => [hint, REASON_OF[key]]));
 /** Ordered match rules; the first hit wins. Substrings track the thrown messages they recover. */
 const RULES = [
+    // First, because the message carries a path the user chose, and a path can hold any word a later
+    // rule keys on. Without it the variable's name read as a `reticle_*` tool and the agent was told
+    // its call failed the schema. Not anchored, so a launch error that wraps it is still caught. The
+    // prefix has no regex metacharacters, so it is used as is.
+    { match: new RegExp(CHROMIUM_PATH_REFUSAL_PREFIX), hint: RECOVERY.CHROMIUM_PATH },
     { match: /no browser session connected/i, hint: RECOVERY.NO_SESSION },
     { match: /multiple sessions connected/i, hint: RECOVERY.MULTIPLE_SESSIONS },
     { match: /no connected session with id/i, hint: RECOVERY.UNKNOWN_SESSION },
@@ -267,7 +300,7 @@ const RULES = [
     // needs its own rule: none of them contains "no browser session connected" (the scope miss is
     // "no browser session FOR project 'x'", which is the opposite claim — sessions exist).
     {
-        match: /scope mismatch|session\(s\) ARE connected under a different project/i,
+        match: /scope mismatch|session\(s\) ARE connected (?:under a different project|with no projectId)/i,
         hint: RECOVERY.SCOPE_MISMATCH,
     },
     { match: /^session disconnected$|session .* never connected/i, hint: RECOVERY.SESSION_GONE },

package/dist/surface/tools/explore-tools.d.ts

@@ -10,5 +10,14 @@
  * Those flows are the point. From the second run onwards `reticle_verify { action: "flows" }` replays
  * them deterministically with no model in the loop at all.
  */
-import type { ToolDef } from './tool-kit.js';
+import type { ToolDef, ToolDeps } from './tool-kit.js';
+import { type RemoteDriveOutcome } from '../../features/harness/platform/remote-drive.js';
 export declare const EXPLORE_TOOLS: ToolDef[];
+/**
+ * A drive the platform's chat asked for, run as the very tool an agent would call.
+ *
+ * Through `runTool`, not a second path to `exploreApp`: a dispatch that skips it is a drive nobody
+ * counted, and the chat's answer is then the same derived summary the agent would have read — never
+ * a model's account of its own drive.
+ */
+export declare function driveForChat(deps: ToolDeps, goal: string, sessionId?: string): Promise<RemoteDriveOutcome>;

package/dist/surface/tools/explore-tools.js

@@ -11,28 +11,28 @@
  * them deterministically with no model in the loop at all.
  */
 import { z } from 'zod';
+import { unprovedGoals } from '../../features/harness/goals.js';
 import { ReticleTool, asRecord } from '@reticlehq/core';
 import { stepCountSchema } from './args/numeric-bounds.js';
+import { runTool } from './invoke-tool.js';
+import { driveVerdict } from '../../features/harness/platform/remote-drive.js';
 import { exploreApp, harnessAvailable, withLinkedCredential, MSG_NO_HARNESS_KEY, } from './harness-explore.js';
-import { DRIVER_NAMES } from '../../features/harness/drivers.js';
-import { describeDrive, replayedFlows } from '../../features/harness/drive-report.js';
+import { EXPLORE_NEEDS } from '../../features/harness/drivers.js';
+import { checkTally, describeDrive, replayedFlows } from '../../features/harness/drive-report.js';
 import { StopReason } from '../../features/harness/harness.js';
 export const EXPLORE_TOOLS = [
     {
         name: ReticleTool.VERIFY_EXPLORE,
-        description: 'Drive the app yourself? Do not — call this instead. A model inside the daemon drives it through this same tool surface, records what it drove as saved flows, and answers in a few lines, so the whole drive costs you one tool call instead of a context full of snapshots. Pass `persona` to say who to be or what to accomplish ("a returning customer checking out", "an admin revoking a seat") and it completes that whole journey rather than clicking at random. Returns { stopReason, steps, savedFlows, summary, usage }. The saved flows are the point: from the next run on, reticle_verify { action: "flows" } replays them deterministically with NO model in the loop. DESTRUCTIVE — it really drives the app, and it spends model budget. Needs ANTHROPIC_API_KEY in the daemon environment.',
+        description: 'Drive the app yourself? Do not — call this instead. The Reticle Harness drives it through this same tool surface (it decides on the Reticle platform, this daemon executes each step), records what it drove as saved flows, and answers in a few lines, so the whole drive costs you one tool call instead of a context full of snapshots. Pass `persona` to say who to be or what to accomplish ("a returning customer checking out", "an admin revoking a seat") and it completes that whole journey rather than clicking at random. Returns { stopReason, steps, savedFlows, summary, usage }. The saved flows are the point: from the next run on, reticle_verify { action: "flows" } replays them deterministically with NO model in the loop. DESTRUCTIVE — it really drives the app, and it spends Harness credits. ' +
+            EXPLORE_NEEDS,
         inputSchema: {
             persona: z
                 .string()
                 .optional()
-                .describe('Who to be, or what to accomplish. A journey ("sign up, then invite a teammate") drives far better than no focus at all.'),
+                .describe('The journey in plain words; any "quoted text" must be on the page when it ends (checked).'),
             maxSteps: stepCountSchema
                 .optional()
-                .describe('Ceiling on model turns. Bounds cost, not value — the drive is graded however it ends.'),
-            driver: z
-                .enum(DRIVER_NAMES)
-                .optional()
-                .describe('Which model drives. An unconfigured one is an error, never a substitution, so an A/B cannot measure the same driver twice. Omit for the default.'),
+                .describe('Ceiling on model turns; the drive is graded however it ends.'),
             sessionId: z
                 .string()
                 .optional()
@@ -47,6 +47,21 @@ export const EXPLORE_TOOLS = [
             savedFlows: z.array(z.string()),
             /** Flows that already existed and were driven and written again. A second run's ordinary result. */
             rewroteFlows: z.array(z.string()),
+            /** Saved flows with no step that asserts anything: their replay verifies nothing. */
+            unverifiedFlows: z.array(z.string()),
+            /** Whether the drive ran at least one check. A drive that did not proved nothing. */
+            proved: z.boolean(),
+            /**
+             * Whether every journey reached its goal, as the platform judged when the drive finished.
+             * Absent when no journey's goal was judged. Checks that held are not the goal reached.
+             */
+            goalMet: z.boolean().optional(),
+            /** How the drive's checks came out, one per control and claim at its worst. */
+            checks: z.object({ held: z.number(), failed: z.number(), undecided: z.number() }),
+            /** The runs this drive syncs as (`harness-<uuid>`): what the platform links its check to. */
+            runIds: z.array(z.string()).optional(),
+            /** One verdict per requested goal, checked by the harness itself. Only `yes` is proved. */
+            goals: z.array(z.object({ text: z.string(), verified: z.string() })),
             /**
              * What the drive set out to do, read from `.reticle` BEFORE it started — every recorded
              * journey with the consequence that must still hold, and the declared intent nobody has
@@ -81,12 +96,10 @@ export const EXPLORE_TOOLS = [
             const persona = args['persona'];
             const maxSteps = args['maxSteps'];
             const sessionId = args['sessionId'];
-            const driver = args['driver'];
-            const { drive, savedFlows, rewroteFlows, driverName, plan } = await exploreApp(deps, env, {
+            const { drive, savedFlows, rewroteFlows, unverifiedFlows, driverName, plan, goals, planLines, runIds, } = await exploreApp(deps, env, {
                 ...('string' === typeof persona ? { focus: persona } : {}),
                 ...('number' === typeof maxSteps ? { maxSteps } : {}),
                 ...('string' === typeof sessionId ? { sessionId } : {}),
-                ...('string' === typeof driver ? { driverName: driver } : {}),
             });
             return {
                 stopReason: drive.stopReason,
@@ -94,11 +107,19 @@ export const EXPLORE_TOOLS = [
                 steps: drive.steps,
                 savedFlows: [...savedFlows],
                 rewroteFlows: [...rewroteFlows],
+                unverifiedFlows: [...unverifiedFlows],
+                proved: drive.proved,
+                checks: checkTally(drive.toolCalls),
+                ...(drive.goalMet === undefined ? {} : { goalMet: drive.goalMet }),
+                ...(runIds === undefined ? {} : { runIds: [...runIds] }),
+                goals: [...goals],
                 plan: { summary: plan.summary, steps: [...plan.steps] },
                 // Derived, not narrated. The driver's own `summary` is appended only when it said
                 // something — it is the one part of this a model authored, so it goes last and is labelled.
                 summary: [
-                    describeDrive(drive.toolCalls, [...savedFlows, ...rewroteFlows]),
+                    ...(planLines ?? []),
+                    describeDrive(drive.toolCalls, [...savedFlows, ...rewroteFlows], unverifiedFlows),
+                    ...[unprovedGoals(goals)].filter((line) => line !== undefined),
                     ...(0 === drive.summary.length ? [] : [`The driver's own account: ${drive.summary}`]),
                 ].join('\n'),
                 ...(drive.error === undefined ? {} : { error: drive.error }),
@@ -159,4 +180,52 @@ const NOTHING_RECORDED = {
     [StopReason.BUDGET]: 'The drive ran out of steps before saving a flow. Raise `maxSteps`, or give it a narrower `persona` so it spends the budget on one journey.',
     [StopReason.STALLED]: 'The drive stopped asking for tools without finishing. Nothing was saved, and nothing is proved.',
     [StopReason.BROKEN]: 'The drive broke before saving anything — read `error`. Nothing is proved.',
+    [StopReason.STOPPED]: 'Autonomous driving was switched off before the drive saved anything. Nothing is proved; switch it back on to drive again.',
 };
+/**
+ * A drive the platform's chat asked for, run as the very tool an agent would call.
+ *
+ * Through `runTool`, not a second path to `exploreApp`: a dispatch that skips it is a drive nobody
+ * counted, and the chat's answer is then the same derived summary the agent would have read — never
+ * a model's account of its own drive.
+ */
+export async function driveForChat(deps, goal, sessionId) {
+    const explore = EXPLORE_TOOLS.find((tool) => ReticleTool.VERIFY_EXPLORE === tool.name);
+    if (explore === undefined)
+        throw new Error('this build has no Harness drive');
+    const out = asRecord(await runTool(explore, deps, {
+        persona: goal,
+        ...(sessionId === undefined ? {} : { sessionId }),
+    }));
+    const summary = 'string' === typeof out['summary'] ? out['summary'] : '';
+    const error = 'string' === typeof out['error'] ? out['error'] : undefined;
+    const note = 'string' === typeof out['note'] ? out['note'] : undefined;
+    const goals = Array.isArray(out['goals'])
+        ? out['goals'].flatMap((g) => {
+            const verified = asRecord(g)['verified'];
+            return 'string' === typeof verified ? [{ verified }] : [];
+        })
+        : [];
+    const goalMet = out['goalMet'];
+    const tally = asRecord(out['checks']);
+    const count = (key) => ('number' === typeof tally[key] ? tally[key] : 0);
+    const checks = { held: count('held'), failed: count('failed'), undecided: count('undecided') };
+    const runIds = Array.isArray(out['runIds'])
+        ? out['runIds'].filter((id) => 'string' === typeof id)
+        : [];
+    return {
+        // Only a drive that ran a check and did not break counts as one that proved anything.
+        ok: true === out['proved'] && error === undefined,
+        ...(0 === runIds.length ? {} : { runIds }),
+        verdict: driveVerdict({
+            proved: true === out['proved'],
+            checks,
+            goals,
+            ...(error === undefined ? {} : { error }),
+            ...('boolean' === typeof goalMet ? { goalMet } : {}),
+        }),
+        summary: [summary, note, error === undefined ? undefined : `Error: ${error}`]
+            .filter((line) => line !== undefined && 0 < line.length)
+            .join('\n'),
+    };
+}

package/dist/surface/tools/feedback-tools.js

@@ -17,6 +17,17 @@ import { ReticleTool } from '@reticlehq/core';
 import { asNumber, asString } from '@reticlehq/core';
 import { submitFeedback, feedbackDisabled } from '../../telemetry/feedback.js';
 import { getTelemetry } from '../../telemetry/telemetry.js';
+import { dirname } from 'node:path';
+import { sessionRoot } from '../../memory/project/session-root.js';
+/** The project folder this call's session belongs to, when one can be told. */
+function projectDir(deps, sessionId) {
+    try {
+        return { cwd: dirname(sessionRoot(deps, sessionId)) };
+    }
+    catch {
+        return {};
+    }
+}
 /** One optional string arg, present only when the agent actually supplied it. */
 function optionalText(args, key) {
     const value = asString(args[key]);
@@ -175,6 +186,9 @@ export const FEEDBACK_TOOLS = [
                 ...optionalRating(args),
             }, {
                 session: sessionFacts(deps, asString(args['sessionId'])),
+                // A report that cannot be sent is written into the project being verified, never into
+                // whatever folder the daemon happened to start in.
+                ...projectDir(deps, asString(args['sessionId'])),
                 // The AGENT does not wait for the network. `reticle feedback` (a human, at a terminal,
                 // watching for an answer) still does — see submitFeedback's `background`.
                 background: true,

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

@@ -7,13 +7,17 @@
  * nothing grades) but the flows that now exist on disk, because every future run replays those
  * deterministically with no model in the loop at all.
  */
+import { type FlowFile } from '@reticlehq/core';
 import type { ToolDeps } from './tool-kit.js';
 import { type HarnessPlan } from './harness-plan.js';
 import { type ConfigFetch } from '../../features/harness/platform-config.js';
-import { type HarnessResult, type ModelDriver, type ToolOutcome } from '../../features/harness/harness.js';
+import { type HarnessResult, type HarnessToolset, type ModelDriver, type ToolOutcome } from '../../features/harness/harness.js';
+import { type GoalCheck } from '../../features/harness/goals.js';
 export interface ExploreOptions {
     /** Who to be, or what to accomplish. Appended to the standing instruction. */
     focus?: string;
+    /** Texts the drive must leave on the page. Default: whatever `focus` quoted. See goals.ts. */
+    goals?: readonly string[];
     /** Pinned tab, when the app has more than one connected. */
     sessionId?: string;
     /** Hard ceiling on model turns. Bounds cost, not value — the drive is usable however it ends. */
@@ -51,6 +55,8 @@ export interface ExploreResult {
     plan: HarnessPlan;
     /** Flows that exist now and did not before — the part of a drive that is worth paying for twice. */
     savedFlows: readonly string[];
+    /** Of the saved and rewritten flows, the ones with no step that checks anything. */
+    unverifiedFlows: readonly string[];
     /**
      * Flows that already existed and were written again by this drive.
      *
@@ -64,6 +70,10 @@ export interface ExploreResult {
      * journeys under the same names — so this is the ordinary case, not the corner one.
      */
     rewroteFlows: readonly string[];
+    /** One verdict per goal, checked by the harness after the drive rather than taken on its word. */
+    goals: readonly GoalCheck[];
+    /** The persona plan and how each persona ended, when the platform proposed the personas. */
+    planLines?: readonly string[];
     /**
      * Which driver actually drove.
      *
@@ -73,6 +83,8 @@ export interface ExploreResult {
      * comparison. `custom` is an injected driver, which is neither of ours to name.
      */
     driverName: string;
+    /** The run this drive syncs as (`harness-<id>`), so a caller can find it on the platform. */
+    runIds?: readonly string[];
 }
 /**
  * Why the harness is unavailable, phrased as the way to make it available.
@@ -82,10 +94,6 @@ export interface ExploreResult {
  * print it, and two copies of this sentence would drift.
  */
 export declare const MSG_NO_HARNESS_KEY: string;
-/** Asked for Jev specifically and it is not configured. Distinct from having no model at all. */
-export declare const MSG_NO_JEV_KEY: string;
-/** Asked for OpenAI specifically and it is not configured. Never substituted, same as Jev. */
-export declare const MSG_NO_OPENAI_KEY: string;
 /**
  * The environment, plus the credential this machine already has.
  *
@@ -106,7 +114,10 @@ export declare const MSG_NO_OPENAI_KEY: string;
  * 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>): Promise<Record<string, string | undefined>>;
-/** Is there a model the harness can drive with? A read, because "not configured" is not a failure. */
+/**
+ * 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;
 /**
  * Read the step ceiling out of the environment.
@@ -125,6 +136,29 @@ export declare function maxStepsFromEnv(env: Record<string, string | undefined>)
  * record and did not — and this product does not get to make that mistake about its own work.
  */
 export declare function exploreApp(deps: ToolDeps, env: Record<string, string | undefined>, options?: ExploreOptions): Promise<ExploreResult>;
+/** A line in the HUD's Agent Log for the person watching; nobody watching is not an error. */
+export declare function narrator(deps: ToolDeps, options: ExploreOptions): (text: string) => void;
+/** What this project's memory says must hold, in its own words. Nothing recorded is none. */
+export declare function productRules(deps: ToolDeps, sessionId?: string): Promise<string[]>;
+/** `deps` whose flow store is the session's own project, where the drive's saves land. */
+export declare function withProjectFlows(deps: ToolDeps, sessionId?: string): ToolDeps;
+/**
+ * Write the persona onto every flow the drive saved or rewrote without an intent.
+ *
+ * Whichever driver saved it, and in whatever words: the cheap driver's own teardown saved its flow
+ * with no intent at all, so a replay could never say which journey it was meant to prove. A flow
+ * that already carries an intent keeps it. Best effort: a flow that cannot be read or rewritten is
+ * still a saved flow.
+ */
+export declare function recordPersona(deps: ToolDeps, names: readonly string[], persona: string): Promise<void>;
+/**
+ * The saved flows with no step that asserts a consequence.
+ *
+ * Such a flow replays as "verified nothing": it clicks through the journey and would pass with the
+ * feature broken. Named so the drive's report does not count it as evidence. A flow that cannot be
+ * read is left out rather than guessed at.
+ */
+export declare function flowsThatCheckNothing(deps: ToolDeps, names: readonly string[]): Promise<readonly string[]>;
 /**
  * What a drive actually left behind, split into flows that are NEW and flows it wrote over.
  *
@@ -161,18 +195,66 @@ export declare const MSG_HARNESS_DISABLED: string;
 /**
  * The other reason a drive can be refused, and it is NOT the same reason.
  *
- * A drive through the platform spends Reticle's model budget. That is free for three months and
- * included on a paid plan, and outside both it is somebody else's money being spent on nothing. The
- * message says which of the two it is and what to do, because "the harness is off" told to a person
- * who never turned anything off is a support ticket rather than an answer.
+ * A drive through the platform spends Reticle's model budget, bounded by the workspace's monthly
+ * Harness credits. The platform answers this only when something other than the switch stops it.
  */
 export declare const MSG_HARNESS_UNCLAIMED: string;
+/** The platform could not be asked, and the drive would spend Reticle's budget without its yes. */
+export declare const MSG_HARNESS_UNCONFIRMED: string;
+/**
+ * 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: ExploreOptions): Promise<string | undefined>;
+/**
+ * Close and save whatever recording the drive left open.
+ *
+ * The driver reserves turns for its own teardown, which covers the ordinary ending. It does NOT
+ * cover a drive that broke, or one whose model went quiet, or one cut off by a budget the caller
+ * shortened — and in every one of those the app really was driven and the record of it is thrown
+ * away. Measured before this existed: a 24-step journey through a real dashboard, saved nothing.
+ *
+ * Failures are swallowed on purpose. This is a last chance, not a checkpoint: if the recording was
+ * already closed the stop is refused and there is nothing to do, and a drive must not fail at the
+ * finish line because the thing it was trying to rescue did not need rescuing.
+ */
 /**
- * A stored preference, kept only if this build can actually honour it.
+ * What a banked recording says it was for: the persona the caller named, when there was one.
  *
- * Exported because it is the whole of the asymmetry with the per-call argument, and the asymmetry
- * is the part somebody will later think is a bug.
+ * It used to be "Autonomous drive of X, banked after the run ended" whatever the caller asked for,
+ * so a replay could never say which journey the flow was meant to prove.
  */
-export declare function knownDriver(provider: string | undefined): string | undefined;
+export declare function bankedIntent(persona: string | undefined, open: string): string;
+export declare function bankOpenRecording(toolset: HarnessToolset, drive: HarnessResult, persona: string | undefined): Promise<void>;
 /** The recording started and never stopped, if there is one. Exported because it is the decision. */
 export declare function openRecordingName(toolCalls: readonly ToolOutcome[]): string | undefined;
+/**
+ * Read the project's own record of what it does and what is proved about it.
+ *
+ * No browser, no model, no source. A failure here is "nothing is recorded yet", which is the
+ * ordinary state of a new project and not a reason to refuse to drive — so it answers an empty
+ * plan rather than throwing.
+ */
+export declare function readFlows(deps: ToolDeps): Promise<FlowFile[]>;
+export declare function readPlan(deps: ToolDeps, sessionId?: string): Promise<HarnessPlan>;
+export declare function pinned(options: ExploreOptions): {
+    sessionId?: string;
+};
+/**
+ * The driver: the platform's Harness, which decides every step on its side while this machine
+ * executes. There is no other: the decisions, the models and the planning run only on the platform.
+ */
+export declare function buildDriver(env: Record<string, string | undefined>, maxSteps: number, plan: HarnessPlan, requested?: string, persona?: string, 
+/** A goal driven with no persona: it names the drive's flows as a persona would. */
+journey?: string): {
+    driver: ModelDriver;
+    name: string;
+};