@reticlehq/server 3.7.0 → 3.8.1

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

@@ -4,19 +4,34 @@
  * 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).
+ * never connected, the next step: the zero-install lease, and the consent question for `init`.
+ *
+ * This call changes no file. It used to run `init` in an unwired project: an agent that only
+ * listed sessions changed package.json, the lockfile and the build config, and started a second
+ * dev server, which the user did not ask for. Wiring is the user's decision.
  */
 import { dirname } from 'node:path';
 import { z } from 'zod';
-import { DiscoveryInvite, NoSessionAction } from '@reticlehq/core';
+import { DiscoveryInvite, NextStepOffered, NoSessionAction } from '@reticlehq/core';
 import { readProjectId } from '../../command/cli/ports/resolve/cli-port.js';
 import { callingClientDirectory } from '../../hooks/client-directory.js';
-/** The answers that mean "this app is not set up yet", which a first run can settle by wiring it. */
+import { initCommandIn } from '../../portal/session/dev-server/dev-command.js';
+import { wiringConsent, zeroInstallLease, } from '../../portal/session/no-session-next-action.js';
+import { noteNextStepOffered } from '../../telemetry/onboarding-firsts.js';
+// The handshake reads the consent wording from here, so `mcp` needs no reach into `session`.
+export { wiringConsent };
+/** The answers that mean "this app is not set up yet". */
 const FIRST_RUN_ACTIONS = new Set([
     NoSessionAction.RUN_INIT,
     NoSessionAction.START_DEV_SERVER,
     NoSessionAction.OPEN_APP,
 ]);
+/** The answers where an app is up, so the lease can check it now. */
+const LEASABLE_ACTIONS = new Set([
+    NoSessionAction.RUN_INIT,
+    NoSessionAction.OPEN_APP,
+]);
+const LOCALHOST = 'http://localhost';
 /** 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
@@ -36,10 +51,14 @@ export const EMPTY_SESSION_LIST_OUTPUT = {
         .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())
+    next_step: z
+        .object({
+        offered: z.nativeEnum(NextStepOffered),
+        lease: z.string().optional(),
+        consent: z.string(),
+    })
         .optional()
-        .describe('Files the first run changed (`steps`); tell the user.'),
+        .describe('Present ONLY when this project is not wired. Nothing was installed and no file changed. `lease` is the call that checks the running app now, with nothing installed: do it first. `consent` is the question for wiring the app for good: ask the user, and run the command only if they agree.'),
     lastKnown: z
         .object({
         sessionId: z.string(),
@@ -49,63 +68,72 @@ export const EMPTY_SESSION_LIST_OUTPUT = {
         .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.'),
 };
 /**
- * Wire the calling project when another project's tab is the one currently connected.
+ * The next step for an unwired project, or undefined when the project is wired or cannot be told.
+ *
+ * The lease leads when an app is up: it checks the change now and installs nothing. When no app
+ * is up there is nothing to lease yet, so the consent question leads. Both name the consent
+ * question, because only the user can agree to the file changes that `init` makes.
+ */
+function nextStepFor(deps, dir, next) {
+    if (next === undefined || !FIRST_RUN_ACTIONS.has(next.action)) {
+        return undefined;
+    }
+    const project = deps.firstRun?.projectDirectory(dir());
+    if (project === undefined) {
+        return undefined;
+    }
+    const consent = wiringConsent(initCommandIn(project));
+    const leasable = LEASABLE_ACTIONS.has(next.action) && next.port !== undefined;
+    const offered = leasable ? NextStepOffered.LEASE : NextStepOffered.INIT_CONSENT;
+    noteNextStepOffered(offered, () => readProjectId(project) !== undefined);
+    if (!leasable) {
+        return { offered, consent };
+    }
+    return { offered, lease: zeroInstallLease(`${LOCALHOST}:${String(next.port)}`), consent };
+}
+/**
+ * The next step for the calling project when another project's tab is the one connected.
  *
  * The list handler only used to reach {@link emptySessionList} when the daemon's whole list was
  * empty. A live tab in project A then answered project B's first call with A's sessions, and B
- * was never wired.
+ * never heard that it was not wired.
  */
-export async function wireCallerBesideLiveSessions(deps, sessions) {
+export function nextStepBesideLiveSessions(deps, sessions) {
     const dir = callingClientDirectory();
-    if (dir === undefined)
+    if (dir === undefined) {
         return undefined;
+    }
     const projectId = readProjectId(dir);
     if (projectId !== undefined && sessions.some((session) => session.projectId === projectId)) {
         return undefined;
     }
-    const next = deps.sessions.noSessionNextAction();
-    const target = next !== undefined && FIRST_RUN_ACTIONS.has(next.action)
-        ? deps.firstRun?.projectDirectory(dir)
-        : undefined;
-    if (target === undefined || deps.firstRun === undefined)
-        return undefined;
-    return deps.firstRun.wire(target);
+    return nextStepFor(deps, () => dir, deps.sessions.noSessionNextAction());
 }
 /** The departed tab for this call: the caller's own project when it named one, else the daemon's newest. */
 function departedForCaller(deps) {
     const dir = callingClientDirectory();
-    if (dir === undefined)
+    if (dir === undefined) {
         return deps.sessions.lastKnown?.();
+    }
     const projectId = readProjectId(dir);
-    if (projectId === undefined)
+    if (projectId === undefined) {
         return undefined;
+    }
     return deps.sessions.lastKnownFor?.(projectId);
 }
-export async function emptySessionList(deps, sessions) {
+export function emptySessionList(deps, sessions) {
     // The lead and its next action: the full differential (~3 KB of ranked causes) read as
     // speculation on the call an agent makes first. Optional-call: test stubs predate the lead.
     const why = deps.sessions.noSessionLead?.() ?? 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 the client is in, not the directory the daemon was started in.
-    // One daemon serves every project; the proxy names its cwd on the call. With no caller (an
-    // embed, a test) it is still the daemon's own project. A daemon outside any project asks instead.
-    // ponytail: cwd, not an MCP roots/list round trip. A proxy started outside the project still
-    // answers run_init; roots are the upgrade when a client launches there but names the project.
-    // 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(callingClientDirectory() ?? 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 project the client is in, not the directory the daemon was started in. One daemon serves
+    // every project; the proxy names its cwd on the call. With no caller (an embed, a test) it is the
+    // daemon's own project. A daemon outside any project offers no step.
+    // ponytail: cwd, not an MCP roots/list round trip. Roots are the upgrade when a client launches
+    // outside the project but names it.
+    const nextStep = nextStepFor(deps, () => callingClientDirectory() ?? dirname(deps.reticleRoot), next);
     // The last tab, when one was here. Optional-call: test stubs of SessionManager predate it.
     const known = departedForCaller(deps);
     const lastKnown = undefined === known ? undefined : { sessionId: known.id, url: known.url };
@@ -113,6 +141,7 @@ export async function emptySessionList(deps, sessions) {
         sessions,
         ...(why === undefined ? {} : { why }),
         ...(next === undefined ? {} : { next_action: next }),
+        ...(nextStep === undefined ? {} : { next_step: nextStep }),
         ...(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

@@ -8,7 +8,7 @@
  * 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 } from '@reticlehq/core';
+import { RefusalReason, type CodedRefusal } from '@reticlehq/core';
 /** The recovery hints, named so they are not free strings and can be asserted in tests. */
 export declare const RECOVERY: {
     readonly NO_SESSION: string;
@@ -41,6 +41,7 @@ export declare const RECOVERY: {
      */
     readonly AMBIGUOUS_TARGET: string;
     readonly NO_SUCH_OPTION: string;
+    readonly PRODUCTION_POLICY: string;
     readonly BAD_ARGUMENTS: string;
     readonly WRONG_TARGET: string;
     readonly NOT_EDITABLE: string;
@@ -54,9 +55,10 @@ export declare const RECOVERY: {
      * something that is not a top-level parameter is the whole distance between a one-line retry and
      * a lost budget.
      *
-     * The classifier is also wider than "destructive": it matches `deploy` and `publish`, so an
-     * ordinary "New deploy" button trips it. Naming a real trigger word here keeps that from reading
-     * as a malfunction on an app where nothing is being deleted.
+     * The classifier also stops a control that moves money, which is not "destructive". Naming the
+     * real trigger words here keeps a refusal on a "Pay" button from reading as a malfunction. Only
+     * words the classifier matches are named: `deploy` and `publish` are excluded on purpose (see
+     * `core/src/verdict/security.ts`).
      */
     readonly CONFIRM_DANGEROUS: string;
     readonly UNSUPPORTED_SURFACE: string;
@@ -85,7 +87,6 @@ export declare const RECOVERY: {
      * agent's malformed call: it was then told to fix arguments that were never wrong.
      */
     readonly HARNESS_LOCKED: string;
-    readonly HARNESS_NOT_LINKED: string;
 };
 /**
  * The actionable next move for a known error message, or undefined when none is recognized.
@@ -104,7 +105,7 @@ export declare function recoveryFor(message: string): string | undefined;
  * is the bucket that says the classifier has a blind spot — and a growing `other` is a finding about
  * this table rather than about anybody's app.
  */
-export declare function refusalReasonFor(rawMessage: string): RefusalReason;
+export declare function refusalReasonFor(rawMessage: string, coded?: CodedRefusal): RefusalReason;
 /**
  * The ask attached to errors we do NOT recognize. An unrecognized error is, by definition, the case
  * where Reticle failed in a way nobody anticipated — the single highest-value moment to hear from the
@@ -120,11 +121,20 @@ interface ErrorPayload {
     error: string;
     recovery?: string;
     feedback?: string;
+    /** A coded refusal: what it is, and who does what next, as data. */
+    code?: CodedRefusal['code'];
+    next?: CodedRefusal['next'];
 }
+/**
+ * The code and next steps a thrown refusal carries (`HarnessNotLinkedError`), or undefined. Read from
+ * the error itself, so a refusal is recognized by its code and never by a regular expression over
+ * its sentence: the not-linked refusal was matched by its prose, and the prose was rewritten.
+ */
+export declare function codedRefusalOf(error: unknown): CodedRefusal | undefined;
 /**
  * Build the tool-error payload spliced at the MCP boundary. `recovery` is added when the error is
  * known; the feedback ask is added when it is NOT — the two are mutually exclusive by design, so the
  * agent always gets exactly one next move.
  */
-export declare function buildErrorPayload(rawMessage: string): ErrorPayload;
+export declare function buildErrorPayload(rawMessage: string, coded?: CodedRefusal): ErrorPayload;
 export {};

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

@@ -8,10 +8,12 @@
  * 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, ReticleEnv, TRANSPORT_LIMITS, UNISSUED_REF_REFUSAL } from '@reticlehq/core';
+import { CodedRefusalSchema, PRODUCTION_REFUSAL_PREFIX, RefusalCode, RefusalReason, ReticleEnv, TRANSPORT_LIMITS, UNISSUED_REF_REFUSAL, } from '@reticlehq/core';
 import { SELF_RECOVERING_MARKER } from '../../portal/session/no-session-diagnosis.js';
 import { MSG_HARNESS_DISABLED, MSG_HARNESS_UNCLAIMED, MSG_HARNESS_UNCONFIRMED, PlatformRefusalCode, RefusalLead, } from '../../features/harness/platform/refusal.js';
 import { BODY_CLAUSE_REFUSAL_OPENING } from '@reticlehq/engine/evidence/body-capture-remedy.js';
+import { EMPTY_FIND_OPENING } from './read/query-shape.js';
+import { UNKNOWN_FLOW_OPENING } from '../../language/flows/suite-selection.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] …';
@@ -64,6 +66,10 @@ const SELF_RECOVERING = [
     // 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 find with nothing to find names the fields to pass; an unknown flow name lists the saved ones.
+    // Both are the caller's to fix, and the defect ask on top told an agent to file a bug about them.
+    { match: literally(EMPTY_FIND_OPENING), reason: RefusalReason.BAD_ARGS },
+    { match: literally(UNKNOWN_FLOW_OPENING), reason: RefusalReason.NO_MATCH },
 ];
 /**
  * The refusal for a `ref` Reticle never minted — decided BEFORE every other rule, not by one inside
@@ -158,6 +164,11 @@ export const RECOVERY = {
         'and the change event that follows has been observed persisting an empty setting into the app. ' +
         'Retry with one of the listed values — note they are option VALUES, which often differ from the ' +
         'visible labels shown in brackets. This is an invalid call, not a Reticle defect.',
+    PRODUCTION_POLICY: 'The production policy refused this act before it reached the site, and nothing was done. The ' +
+        'call itself was valid. Do not retry it: the policy refuses it every time. Leave this step out, ' +
+        'or, when the message names an intent, end the lease and acquire a new one whose ' +
+        '`production.intent` names the action. This is a refusal by design, not a Reticle defect: there ' +
+        'is nothing to report.',
     BAD_ARGUMENTS: "That call did not match the tool's schema — the message above names the tool and the exact " +
         "argument it wanted. Re-read that tool's parameters and retry with the missing or corrected " +
         'argument. This is an invalid call, not a Reticle defect: there is nothing to report.',
@@ -181,12 +192,13 @@ export const RECOVERY = {
      * something that is not a top-level parameter is the whole distance between a one-line retry and
      * a lost budget.
      *
-     * The classifier is also wider than "destructive": it matches `deploy` and `publish`, so an
-     * ordinary "New deploy" button trips it. Naming a real trigger word here keeps that from reading
-     * as a malfunction on an app where nothing is being deleted.
+     * The classifier also stops a control that moves money, which is not "destructive". Naming the
+     * real trigger words here keeps a refusal on a "Pay" button from reading as a malfunction. Only
+     * words the classifier matches are named: `deploy` and `publish` are excluded on purpose (see
+     * `core/src/verdict/security.ts`).
      */
-    CONFIRM_DANGEROUS: 'Reticle blocked a control whose label reads as consequential (delete, remove, revoke, deploy, ' +
-        'publish, pay…) on purpose. If you mean it, send the SAME call again with ' +
+    CONFIRM_DANGEROUS: 'Reticle blocked a control whose label reads as consequential (delete, remove, revoke, pay…) ' +
+        'on purpose. If you mean it, send the SAME call again with ' +
         '`args: { confirmDangerous: true }` — it goes inside the `args` object, not beside it. This is ' +
         'a deliberate refusal, not a defect: there is nothing to report.',
     UNSUPPORTED_SURFACE: 'That surface is not supported yet, and Reticle refuses rather than pretending — a rich-text ' +
@@ -260,13 +272,9 @@ export const RECOVERY = {
      * the refusal names reticle_act_and_wait as the alternative, which the catch-all below read as an
      * agent's malformed call: it was then told to fix arguments that were never wrong.
      */
-    HARNESS_LOCKED: 'The Harness unlocks once Reticle sees enough of this app; the refusal names what is missing ' +
-        'and how to close each gap. Nothing to report: close them, or drive the journey yourself with ' +
-        'reticle_act_and_wait and an `until` on its last step. Every other tool works at any coverage.',
-    HARNESS_NOT_LINKED: 'This project is not linked to the Reticle platform, where the Harness runs. The call itself was ' +
-        'valid. Either the human runs `npx @reticlehq/server connect` once in the app directory, or you ' +
-        'drive the journey yourself: reticle_navigate, then reticle_act_and_wait with an `until` on its ' +
-        'last step. There is nothing to report.',
+    HARNESS_LOCKED: 'An older Reticle platform locked the Harness on its setup score. Nothing to report: drive the ' +
+        'journey yourself with reticle_act_and_wait and an `until` on its last step. Every tool works ' +
+        'at any coverage.',
 };
 /**
  * Which OWNER each recovery belongs to, for `tool_refused`.
@@ -305,12 +313,12 @@ const REASON_OF = {
     NOT_EDITABLE: RefusalReason.UNSUPPORTED,
     CONFIRM_DANGEROUS: RefusalReason.UNSUPPORTED,
     WRONG_TARGET: RefusalReason.UNSUPPORTED,
+    // The call was valid; the drive's policy refuses what it asked for, as for a destructive control.
+    PRODUCTION_POLICY: RefusalReason.UNSUPPORTED,
     BAD_ARGUMENTS: RefusalReason.BAD_ARGS,
     INVALID_NAME: RefusalReason.BAD_ARGS,
     // Nothing about the app or the call is wrong; the feature is switched off or unpaid for.
     HARNESS_OFF: RefusalReason.UNSUPPORTED,
-    // Nothing about the call is wrong either; the project is not linked yet.
-    HARNESS_NOT_LINKED: RefusalReason.UNSUPPORTED,
     // The call is valid; the app is not instrumented enough for the Harness yet.
     HARNESS_LOCKED: RefusalReason.UNSUPPORTED,
 };
@@ -349,11 +357,10 @@ const RULES = [
     // platform's: matching it is matching ourselves.
     { match: /credits are used\./, hint: RECOVERY.HARNESS_OFF },
     {
-        // The gate's own words, and the platform's "locked: connect your app first": expected states.
-        match: new RegExp(`(?:^Harness unlocks at \\d+% instrumentation)|(?:^${escapeRegExp(RefusalLead[PlatformRefusalCode.HARNESS_LOCKED])})`),
+        // An older platform's "locked": an expected state, not a defect.
+        match: new RegExp(`^${escapeRegExp(RefusalLead[PlatformRefusalCode.HARNESS_LOCKED])}`),
         hint: RECOVERY.HARNESS_LOCKED,
     },
-    { match: /The Reticle Harness runs on the Reticle platform/, hint: RECOVERY.HARNESS_NOT_LINKED },
     // Three conditions the daemon understands perfectly and still asked for a bug report about. Each
     // 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).
@@ -412,6 +419,8 @@ const RULES = [
         match: /target matched \d+ elements and an action must not guess/i,
         hint: RECOVERY.AMBIGUOUS_TARGET,
     },
+    // Before the catch-all: every refusal names `reticle_lease`, and the call was valid.
+    { match: new RegExp(`^${PRODUCTION_REFUSAL_PREFIX}`), hint: RECOVERY.PRODUCTION_POLICY },
     // Authored by Reticle, about the caller's arguments: the message already names the valid answers.
     { match: /^unknown action '/i, hint: RECOVERY.BAD_ARGUMENTS },
     { match: /^unsupported query strategy '/i, hint: RECOVERY.BAD_ARGUMENTS },
@@ -473,7 +482,9 @@ export function recoveryFor(message) {
  * is the bucket that says the classifier has a blind spot — and a growing `other` is a finding about
  * this table rather than about anybody's app.
  */
-export function refusalReasonFor(rawMessage) {
+export function refusalReasonFor(rawMessage, coded) {
+    if (coded !== undefined)
+        return REASON_OF_CODE[coded.code];
     const message = zodArrayAsSentence(rawMessage);
     if (isUnissuedRefRefusal(message))
         return RefusalReason.BAD_ARGS;
@@ -591,15 +602,37 @@ const INVALID_NAME_REJECTION = /^invalid (?:[a-z]+ )*name: /i;
 export const FEEDBACK_ASK = 'This error is not one Reticle recognizes, which means it may be a defect in Reticle rather than in ' +
     'the app. If you believe Reticle misbehaved, call reticle_session { action: "feedback" } with a root-cause analysis and ' +
     'the call trace before moving on — that report is the only way this gets fixed.';
+/** Which owner each coded refusal belongs to, for `tool_refused`. */
+const REASON_OF_CODE = {
+    // Nothing about the call is wrong; the project is not linked yet.
+    [RefusalCode.HARNESS_NOT_LINKED]: RefusalReason.UNSUPPORTED,
+};
+/**
+ * The code and next steps a thrown refusal carries (`HarnessNotLinkedError`), or undefined. Read from
+ * the error itself, so a refusal is recognized by its code and never by a regular expression over
+ * its sentence: the not-linked refusal was matched by its prose, and the prose was rewritten.
+ */
+export function codedRefusalOf(error) {
+    if (!(error instanceof Error))
+        return undefined;
+    const parsed = CodedRefusalSchema.safeParse({
+        code: 'code' in error ? error.code : undefined,
+        next: 'next' in error ? error.next : undefined,
+    });
+    return parsed.success ? parsed.data : undefined;
+}
 /**
  * Build the tool-error payload spliced at the MCP boundary. `recovery` is added when the error is
  * known; the feedback ask is added when it is NOT — the two are mutually exclusive by design, so the
  * agent always gets exactly one next move.
  */
-export function buildErrorPayload(rawMessage) {
+export function buildErrorPayload(rawMessage, coded) {
     // Render the zod array BEFORE capping: the cap would otherwise truncate the JSON mid-issue and
     // leave an unparseable fragment as the agent's error text — the worst of both shapes.
     const message = capMessage(zodArrayAsSentence(rawMessage));
+    // A coded refusal says who does what next itself: no hint beside it, and no bug-report ask.
+    if (coded !== undefined)
+        return { error: message, code: coded.code, next: coded.next };
     if (isUnissuedRefRefusal(message))
         return { error: message, recovery: RECOVERY.UNISSUED_REF };
     // A self-diagnosing message gets NEITHER a generic recovery nor the feedback ask. It already

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

@@ -30,6 +30,16 @@ export type ExploreDrive = (deps: ToolDeps, env: Record<string, string | undefin
  * with the drive already running rather than paying for another.
  */
 export declare function answerExplore(deps: ToolDeps, args: Record<string, unknown>, call: ToolCall | undefined, drive: ExploreDrive): Promise<unknown>;
+/**
+ * What a finished drive asks of the agent that reads it: a failed check is a defect to fix, and the
+ * fix is proved only when the same drive runs again. Without it the agent read "1 failed" and stopped.
+ */
+export declare function fixRequest(result: Record<string, unknown>): string | undefined;
+/**
+ * The platform's failed checks, each verbatim, read from its run summary. A plan run leaves the
+ * driver's account out of the answer, and with it went "totalCents 16700, the claim says 13360".
+ */
+export declare function platformFindings(summary: string): string[];
 /** The tool's answer for a finished drive. */
 export declare function exploreReport(explored: ExploreResult): Record<string, unknown>;
 /**

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

@@ -10,6 +10,7 @@
  * 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 { HarnessRunReason } from '@reticlehq/core/telemetry';
 import { z } from 'zod';
 import { randomUUID } from 'node:crypto';
 import { join } from 'node:path';
@@ -27,7 +28,7 @@ import { RESULT_FIELD, exploreResult, resultField } from './reticle-result.js';
 import { runTool } from './invoke-tool.js';
 import { harnessRunSource, reportHarnessBlocked, reportHarnessRun, } from '../../telemetry/harness-run.js';
 import { driveVerdict } from '../../features/harness/platform/remote-drive.js';
-import { harnessLockRefusal, firstLine, exploreApp, harnessAvailable, withLinkedCredential, MSG_NO_HARNESS_KEY, } from './harness-explore.js';
+import { harnessStartRefusal, firstLine, exploreApp, harnessAvailable, withLinkedCredential, HarnessNotLinkedError, } from './harness-explore.js';
 import { EXPLORE_NEEDS } from '../../features/harness/drivers.js';
 import { checkTally, describeDrive, replayedFlows, runProved, } from '../../features/harness/drive-report.js';
 import { StopReason } from '../../features/harness/harness.js';
@@ -36,7 +37,7 @@ export const WAIT_MAX_S = 240;
 export const EXPLORE_TOOLS = [
     {
         name: ReticleTool.VERIFY_EXPLORE,
-        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 instead of a context full of snapshots: within `wait` seconds, the result or { status: "running", runId } to poll with `runId`. Never start a second. 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. 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. ' +
+        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 instead of a context full of snapshots: within `wait` seconds, the result or { status: "running", runId } to poll with `runId`. Never start a second. 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. 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 credits. ' +
             EXPLORE_NEEDS,
         inputSchema: {
             persona: z
@@ -54,14 +55,15 @@ export const EXPLORE_TOOLS = [
                 .string()
                 .optional()
                 .describe('Active session ID from reticle_sessions. Omit when only one browser session is open.'),
-            driveId: z.string().optional(),
-            // Bare on purpose: the description and every `running` answer say how to poll, and this
-            // schema is re-sent on every turn of every session.
+            driveId: z.string().optional().describe('The drive id an explore call answered with.'),
             wait: z.number().min(0).max(WAIT_MAX_S).optional().describe('Seconds; default 50.'),
-            runId: z.string().optional(),
+            runId: z
+                .string()
+                .optional()
+                .describe('The run id an explore call answered with; pass it to poll that run.'),
             planId: z.string().optional().describe('Run a plan saved on the dashboard, as it stands.'),
-            stop: z.boolean().optional(),
-            say: z.string().optional(),
+            stop: z.boolean().optional().describe('With runId: stop that Harness run.'),
+            say: z.string().optional().describe('With runId: a note to the running Harness.'),
         },
         // Everything the handler returns has to be declared, or a schema-aware client never sees it.
         // Optional throughout: a drive still running answers only its status, id and progress.
@@ -76,7 +78,7 @@ export const EXPLORE_TOOLS = [
             next: z.object({ action: z.string(), runId: z.string() }).optional(),
             /** Seconds since the drive started, while it runs. */
             elapsedS: z.number().optional(),
-            /** While it runs: poll again with the same call; stopping never stops the drive. */
+            /** While it runs: poll again. Once it ended with a failed check: fix the code, then drive again. */
             instruction: z.string().optional(),
             stopReason: z.string().optional(),
             /** Which driver actually drove, so a comparison can never misattribute its own result. */
@@ -127,6 +129,11 @@ export const EXPLORE_TOOLS = [
              * at its end, which a caller that only shows the verdict otherwise cannot tell anybody.
              */
             driverAccount: z.string().optional(),
+            /**
+             * The platform's own failed checks, verbatim: what was expected, what was observed, on which
+             * request. The fix request quotes them, so the agent knows exactly what to fix.
+             */
+            findings: z.array(z.string()).optional(),
             /** Present when the drive broke: a model that would not answer, a wedged browser. */
             error: z.string().optional(),
             /** What the drive cost, cache hits included, so an expensive run is visible rather than felt. */
@@ -196,7 +203,7 @@ export async function answerExplore(deps, args, call, drive) {
         // Billed to the one free drive the platform granted, never to another.
         ...('string' === typeof driveId ? { [ReticleEnv.DRIVE_ID]: driveId } : {}),
     };
-    // The coverage gate first: it is local, and the one thing to fix before anything else matters.
+    // The build check first: it is local, and the one thing to fix before anything else matters.
     // Not for a saved plan that only replays flows (no model turn to guard), and a plan it refuses
     // is told so, so the plan's history records the attempt.
     const planId = str(args['planId']);
@@ -213,17 +220,16 @@ export async function answerExplore(deps, args, call, drive) {
         source: harnessRunSource(origin, planId),
         hosted: platform !== undefined,
     };
-    const locked = replayOnly ? undefined : await harnessLockRefusal(deps, sessionId, env);
-    if (locked !== undefined)
-        reportHarnessBlocked(runStart);
+    const locked = replayOnly ? undefined : await harnessStartRefusal(deps, sessionId);
     if (locked !== undefined) {
+        reportHarnessBlocked(runStart, locked.reason);
         if (planId !== undefined && platform !== undefined)
-            await reportPlanBlocked(platform, planId, firstLine(locked));
-        throw new Error(locked);
+            await reportPlanBlocked(platform, planId, firstLine(locked.text));
+        throw new Error(locked.text);
     }
     if (!harnessAvailable(env)) {
-        reportHarnessBlocked(runStart);
-        throw new Error(MSG_NO_HARNESS_KEY);
+        reportHarnessBlocked(runStart, HarnessRunReason.NOT_LINKED);
+        throw new HarnessNotLinkedError();
     }
     const harness = randomUUID();
     const runId = harnessRunId(harness);
@@ -260,12 +266,56 @@ async function answerDrive(deps, runId, waitMs, call, sessionId, refuseBroken) {
             instruction: stillRunning(runId, record.steps, elapsedS),
         };
     }
-    if (record.result !== undefined)
-        return { status: record.status, runId, ...record.result };
+    if (record.result !== undefined) {
+        const fix = fixRequest(record.result);
+        return {
+            status: record.status,
+            runId,
+            ...record.result,
+            ...(fix === undefined ? {} : { instruction: fix }),
+        };
+    }
     if (refuseBroken && record.error !== undefined)
         throw new Error(record.error);
     return { status: record.status, runId, steps: record.steps, error: record.error ?? 'no result' };
 }
+/**
+ * What a finished drive asks of the agent that reads it: a failed check is a defect to fix, and the
+ * fix is proved only when the same drive runs again. Without it the agent read "1 failed" and stopped.
+ */
+export function fixRequest(result) {
+    const failed = asRecord(result['checks'])['failed'];
+    const findings = Array.isArray(result['findings'])
+        ? result['findings'].filter((f) => 'string' === typeof f)
+        : [];
+    const rerun = 'Fix the code, then start the same drive again (the same persona or planId) to verify the fix. ' +
+        'Do not report it fixed before that drive passes.';
+    if (0 < findings.length)
+        return `The Harness found a defect: ${findings.join(' ')} ${rerun}`;
+    if ('number' === typeof failed && failed >= 1)
+        return (`The Harness found a defect: ${String(failed)} check${1 === failed ? '' : 's'} failed. Read ` +
+            `\`summary\` and \`goals\` for what failed. ${rerun}`);
+    // A drive that ran to its end and still missed its goal is not a pass either: on the broken
+    // checkout every check held while the order went out at full price. It is a lead, not a verdict,
+    // so the agent is asked to find out which, not told there is a defect.
+    if (StopReason.FINISHED === result['stopReason'] && false === result['goalMet'])
+        return ('The Harness drive did not reach its goal, so nothing is proved. Read `summary` and check the ' +
+            'outcome the goal names (for example the request body with reticle_observe). If it shows a ' +
+            'defect, fix the code, then start the same drive again (the same persona or planId) to verify ' +
+            'the fix. Do not report it fixed before that drive passes.');
+    return undefined;
+}
+/** How the platform opens a check it failed in a drive's summary: "Not proved: <what, where>". */
+const PLATFORM_FAILED = /Not proved: ([^\n]+)/g;
+/** How the answer's summary says one of them. */
+const FINDING_LEAD = 'Failed on the platform:';
+/**
+ * The platform's failed checks, each verbatim, read from its run summary. A plan run leaves the
+ * driver's account out of the answer, and with it went "totalCents 16700, the claim says 13360".
+ */
+export function platformFindings(summary) {
+    return [...summary.matchAll(PLATFORM_FAILED)].flatMap((m) => m[1] === undefined ? [] : [m[1].trim()]);
+}
 /** A run this machine no longer holds, from the platform it synced to. */
 async function fromPlatform(deps, runId) {
     const platform = serverOptionsFromEnv(await withLinkedCredential(deps, process.env));
@@ -354,8 +404,10 @@ const exploreDrive = async (deps, env, args, harness, control) => {
 export function exploreReport(explored) {
     const { drive, savedFlows, rewroteFlows, unverifiedFlows, driverName, plan, goals, planLines, runIds, runUrl, journeys, planId, planUrl, disparity, } = explored;
     const checks = checkTally(drive.toolCalls);
+    const findings = platformFindings(drive.summary);
     return {
         stopReason: drive.stopReason,
+        ...(0 === findings.length ? {} : { findings }),
         driver: driverName,
         steps: drive.steps,
         savedFlows: [...savedFlows],
@@ -395,6 +447,7 @@ export function exploreReport(explored) {
             ...(planLines ?? []),
             describeDrive(drive.toolCalls, [...savedFlows, ...rewroteFlows], unverifiedFlows, drive.goalMet, journeys),
             ...[unprovedGoals(goals)].filter((line) => line !== undefined),
+            ...findings.map((finding) => `${FINDING_LEAD} ${finding}`),
         ].join('\n'),
         // Not beside a platform plan: its lanes' accounts count saves the platform asked for ("saved 3
         // flow(s)") where `savedFlows` lists what is on disk, and an answer has one count. Each journey's