@reticlehq/server 3.6.0 → 3.7.0

package/dist/features/harness/drive-report.js

@@ -18,7 +18,11 @@
  * leaving a verdict of `unknown` to be read as a pass.
  */
 import { appFindings } from './app-findings.js';
-import { asRecord, asString, ReticleTool, Verified } from '@reticlehq/core';
+import { MSG_OPENED_MENU, MSG_ROUTE_GUESS_MISSED, claimsOnlyRoute } from './route-guess.js';
+import { asRecord, asString, ActionType, NO_SUCH_FLOW, ReplayStatus, ReticleTool, ScriptStatus, Verified, } from '@reticlehq/core';
+import { supersededChecks } from '@reticlehq/engine/evidence/superseded-checks.js';
+import { PredicateSchema } from '@reticlehq/engine/question/predicate/predicate-schema.js';
+import { describeWaitTarget } from '@reticlehq/engine/evidence/unsettled.js';
 function refusedAsDestructive(call) {
     const error = asString(asRecord(call.result)['error']) ?? '';
     return call.isError && error.includes(DESTRUCTIVE_REFUSAL);
@@ -130,6 +134,8 @@ export const ReplayOutcome = {
     ERROR: 'error',
     /** Stopped at a step the flow marks destructive: not run, which is not a regression. */
     GUARDED: 'guarded',
+    /** Not saved on this computer: nothing ran, which is not a regression either. */
+    MISSING: 'missing',
 };
 export function replayedFlows(toolCalls) {
     const out = [];
@@ -142,9 +148,13 @@ export function replayedFlows(toolCalls) {
         const status = call.isError ? ReplayOutcome.ERROR : asString(result['status']);
         out.push({
             name,
-            status: ReplayOutcome.ERROR === status && message.includes(DESTRUCTIVE_REFUSAL)
-                ? ReplayOutcome.GUARDED
-                : status,
+            status: ReplayOutcome.ERROR !== status
+                ? status
+                : message.includes(DESTRUCTIVE_REFUSAL)
+                    ? ReplayOutcome.GUARDED
+                    : message.includes(NO_SUCH_FLOW)
+                        ? ReplayOutcome.MISSING
+                        : status,
         });
     }
     return out;
@@ -180,10 +190,82 @@ function describeClaim(until) {
         return 'a request or a signal';
     return kind;
 }
+/** The declared consequence: `until`, or `predicate`, its alias on act_and_wait and on assert. */
+function untilOf(args) {
+    return args['until'] ?? args['predicate'];
+}
+/** A `no` on a click whose only claim was a route: the driver's guess, not the app (route-guess.ts). */
+function routeGuessMissed(args, result) {
+    return Verified.NO === result['verified'] && claimsOnlyRoute(untilOf(args));
+}
+/** The line a re-press graded undecided carries instead of the raw `no`. */
+const MSG_REPRESS = "a second press of a control whose claim already held: the Harness's own extra action, not the app";
+/** Every check in drive order: act_and_wait with an `until` and asserts, through reticle_run too. */
+function gradedChecks(toolCalls) {
+    const heldPresses = new Set();
+    const out = [];
+    const checks = toolCalls.flatMap((made, index) => {
+        const call = throughRun(made);
+        const args = asRecord(call.args);
+        const until = untilOf(args);
+        const isCheck = ReticleTool.ASSERT === call.name ||
+            (ReticleTool.ACT_AND_WAIT === call.name && until !== undefined);
+        if (!isCheck || call.isError)
+            return [];
+        const predicate = PredicateSchema.safeParse(until);
+        const key = predicate.success
+            ? `${predicate.data.kind}|${describeWaitTarget(predicate.data)}`
+            : JSON.stringify(until ?? null);
+        return [{ index, call, args, result: asRecord(call.result), key }];
+    });
+    const superseded = supersededChecks(checks.map(({ call, result, key }) => ({
+        key,
+        passive: ReticleTool.ASSERT === call.name,
+        held: Verified.YES === asString(result['verified']),
+        failed: Verified.NO === asString(result['verified']),
+    })));
+    for (const [at, { index, args, result, key }] of checks.entries()) {
+        // The driver's own wrong guess about the route checked the driver, not the app.
+        if (routeGuessMissed(args, result))
+            continue;
+        const verified = asString(result['verified']);
+        // A passive assert that read too early: see superseded-checks.ts.
+        if (superseded.has(at))
+            continue;
+        // A second press of a control whose claim already held is the Harness's own extra action.
+        const ref = asString(args['ref']);
+        const pressed = ref === undefined ? undefined : `${ref}|${key}`;
+        const repress = Verified.NO === verified && pressed !== undefined && heldPresses.has(pressed);
+        if (Verified.YES === verified && pressed !== undefined)
+            heldPresses.add(pressed);
+        const outcome = Verified.YES === verified
+            ? 'held'
+            : Verified.NO === verified && !repress
+                ? 'failed'
+                : 'undecided';
+        out.push({ index, key, outcome, repress });
+    }
+    return out;
+}
+/**
+ * A `reticle_run` call as the tool it ran. A navigation made through it was recorded under the
+ * run's name, and a run that navigated between two pages said it made no action against the app.
+ */
+function throughRun(call) {
+    if (ReticleTool.RUN !== call.name)
+        return call;
+    const args = asRecord(call.args);
+    const name = asString(args['tool']);
+    return name === undefined ? call : { ...call, name, args: asRecord(args['args']) };
+}
 /** Reduce the raw call log to the actions that actually drove the app. */
 export function drivenSteps(toolCalls) {
     const steps = [];
-    for (const [index, call] of toolCalls.entries()) {
+    const represses = new Set(gradedChecks(toolCalls)
+        .filter((check) => check.repress)
+        .map((check) => check.index));
+    for (const [index, made] of toolCalls.entries()) {
+        const call = throughRun(made);
         if (!DRIVING_TOOLS.has(call.name))
             continue;
         const args = asRecord(call.args);
@@ -193,19 +275,49 @@ export function drivenSteps(toolCalls) {
         if (refusedAsDestructive(call))
             continue;
         const action = ReticleTool.NAVIGATE === call.name ? 'navigate' : (asString(args['action']) ?? 'act');
+        const guessMissed = !call.isError && routeGuessMissed(args, result);
+        if (represses.has(index)) {
+            steps.push({
+                action,
+                target: targetOf(args, result),
+                verified: Verified.UNKNOWN,
+                because: MSG_REPRESS,
+                claimed: describeClaim(untilOf(args)),
+                evidence: [],
+            });
+            continue;
+        }
+        // A menu or dialog it opened is the way to the route it named, not a wrong guess.
+        const opened = guessMissed && 0 < openedADialog(result, toolCalls.slice(index + 1)).length;
         steps.push({
+            ...(guessMissed ? { guess: true } : {}),
             action,
             target: targetOf(args, result),
-            verified: call.isError ? 'error' : asString(result['verified']),
-            because: call.isError ? asString(result['error']) : asString(result['because']),
-            claimed: describeClaim(args['until']),
-            evidence: call.isError
+            verified: call.isError
+                ? 'error'
+                : guessMissed
+                    ? Verified.UNKNOWN
+                    : asString(result['verified']),
+            because: call.isError
+                ? asString(result['error'])
+                : opened
+                    ? MSG_OPENED_MENU
+                    : guessMissed
+                        ? MSG_ROUTE_GUESS_MISSED
+                        : asString(result['because']),
+            claimed: describeClaim(untilOf(args)),
+            evidence: call.isError || opened
                 ? []
                 : [...evidenceOf(result), ...openedADialog(result, toolCalls.slice(index + 1))],
         });
     }
     return steps;
 }
+/** Whether the drive did anything to the app: an action that ran, or a flow it replayed. */
+export function actedOnApp(toolCalls) {
+    return (drivenSteps(toolCalls).some((step) => 'error' !== step.verified) ||
+        0 < replayedFlows(toolCalls).length);
+}
 /**
  * The account, as lines.
  *
@@ -218,7 +330,7 @@ export function drivenSteps(toolCalls) {
 /** Every `__reticle_*` query parameter, wherever it sits in the route. */
 const RETICLE_PARAMS = /[?&]__reticle_[^&#]*/g;
 /** The pages the drive's own snapshots reported, in order, each distinct page once. */
-function pagesReached(toolCalls) {
+export function pagesReached(toolCalls) {
     const pages = [];
     for (const call of toolCalls) {
         if (ReticleTool.SNAPSHOT !== call.name || call.isError)
@@ -231,50 +343,131 @@ function pagesReached(toolCalls) {
     }
     return pages;
 }
+/** The values the drive's acts filled or typed, sequence steps included. */
+export function typedValues(toolCalls) {
+    const out = [];
+    const read = (act) => {
+        const inner = asRecord(act['args']);
+        const value = asString(inner['value']) ?? asString(inner['text']);
+        if (value !== undefined &&
+            (ActionType.FILL === act['action'] || ActionType.TYPE === act['action']))
+            out.push(value);
+    };
+    for (const call of toolCalls) {
+        const steps = call.args['steps'];
+        if (Array.isArray(steps))
+            for (const step of steps)
+                read(asRecord(step));
+        else
+            read(call.args);
+    }
+    return out;
+}
 /** How the drive's checks came out: act_and_wait with an `until`, and asserts. */
 export function checkTally(toolCalls) {
-    // One check per control and claim, at its worst: a live drive pressed "Sign in" fifteen times and
-    // reported "15 of 15 check(s) held" for one fact proved fifteen times over.
-    const worst = new Map();
-    for (const call of toolCalls) {
-        const args = asRecord(call.args);
-        const isCheck = ReticleTool.ASSERT === call.name ||
-            (ReticleTool.ACT_AND_WAIT === call.name && args['until'] !== undefined);
-        if (!isCheck || call.isError)
+    // One check per (kind, claim, outcome), exactly as the platform counts a run's checks: a live
+    // drive pressed "Sign in" fifteen times and read "15 of 15 check(s) held" for one fact, and an
+    // answer that counted by control said "2 of 2" beside a dashboard counting the same run otherwise.
+    const seen = new Set();
+    const tally = { held: 0, failed: 0, undecided: 0 };
+    const count = (key, now) => {
+        if (seen.has(`${key}|${now}`))
+            return;
+        seen.add(`${key}|${now}`);
+        tally[now] += 1;
+    };
+    for (const check of gradedChecks(toolCalls))
+        count(check.key, check.outcome);
+    // A replayed flow is a check too: its own expects decided it. A passed replay counted as "no
+    // check" and its run read NOT PROVED beside a dashboard that said Passed.
+    for (const replay of replayedFlows(toolCalls)) {
+        const now = REPLAY_CHECK[replay.status ?? ''];
+        if (now === undefined)
             continue;
-        const result = asRecord(call.result);
-        const effect = asRecord(result['effect']);
-        const control = asString(effect['testid']) ??
-            `${asString(effect['role']) ?? ''} ${asString(effect['name']) ?? asString(args['ref']) ?? ''}`;
-        const key = `${call.name}|${control}|${JSON.stringify(args['until'] ?? args['predicate'] ?? null)}`;
-        const verified = asString(result['verified']);
-        const now = Verified.YES === verified ? 'held' : Verified.NO === verified ? 'failed' : 'undecided';
-        const before = worst.get(key);
-        if (before === undefined || 'failed' === now || ('undecided' === now && 'held' === before))
-            worst.set(key, now);
+        count(`${ReticleTool.FLOW_REPLAY}|${replay.name}`, now);
     }
-    const tally = { held: 0, failed: 0, undecided: 0 };
-    for (const verdict of worst.values())
-        tally[verdict] += 1;
     return tally;
 }
+/** A replay as a check. Guarded and missing never ran, so they are no check at all. */
+const REPLAY_CHECK = {
+    [ReplayOutcome.OK]: 'held',
+    [ReplayOutcome.ERROR]: 'failed',
+    [ReplayOutcome.DRIFT]: 'undecided',
+    [ReplayStatus.UNVERIFIABLE]: 'undecided',
+};
+/** Statuses that leave a plan proved: passed, or a side road deliberately not taken (named in its line). */
+const SETTLED_JOURNEY = new Set([ScriptStatus.PASSED, ScriptStatus.NOT_TAKEN]);
+/**
+ * A plan run's verdict is its journeys', decided as the platform decides it (`planRunVerdict`): any
+ * failed → failed; every journey passed (or deliberately not taken) → proved; some passed beside
+ * journeys left undecided or blocked → not proved. Undefined when there is no plan.
+ *
+ * "Any passed → proved" read PROVED for a plan whose other journeys a credit cut-off had blocked:
+ * one journey proved and the rest never decided, reported as the whole plan proved.
+ */
+function journeysVerdict(journeys, counts) {
+    if (0 === journeys.length)
+        return undefined;
+    const of = (status) => journeys.filter((j) => status === j.status).length;
+    const total = String(journeys.length);
+    const passed = of(ScriptStatus.PASSED);
+    if (0 < of(ScriptStatus.FAILED))
+        return {
+            verified: Verified.NO,
+            line: `NOT PROVED — ${String(of(ScriptStatus.FAILED))} of ${total} journey(s) failed${counts}.`,
+        };
+    if (0 < passed && journeys.every((j) => SETTLED_JOURNEY.has(j.status)))
+        return {
+            verified: Verified.YES,
+            line: `PROVED — ${String(passed)} of ${total} journey(s) passed${counts}.`,
+        };
+    if (0 < passed)
+        return {
+            verified: Verified.UNKNOWN,
+            line: `NOT PROVED — ${String(passed)} of ${total} journey(s) passed and the rest were not decided${counts}.`,
+        };
+    return { verified: Verified.UNKNOWN, line: `NOT PROVED — no journey passed${counts}.` };
+}
 /**
- * The first line a caller reads, and the one the HUD ends on. A drive whose only passing check was
- * a page change, beside a refund that failed, is NOT "proved its checks"; that line ended a run
- * where the journey it was asked to prove had failed.
+ * The first line a caller reads, and the one the HUD ends on, with the verdict it states. A drive
+ * whose only passing check was a page change, beside a refund that failed, is NOT "proved its
+ * checks"; that line ended a run where the journey it was asked to prove had failed.
  */
-export function verdictLine(tally) {
+export function runVerdict(tally, goalMet, 
+/** A plan's journeys: when there are any, their verdict is the run's. */
+journeys = []) {
     const total = tally.held + tally.failed + tally.undecided;
-    if (0 === total)
-        return 'NOT PROVED: the drive ran no check.';
     const counts = `${String(tally.held)} of ${String(total)} check(s) held, ${String(tally.failed)} failed, ${String(tally.undecided)} undecided`;
+    const planned = journeysVerdict(journeys, 0 === total ? '' : `; ${counts}`);
+    const not = (line) => ({ verified: Verified.UNKNOWN, line });
+    // Journeys that passed are not the run's goal reached: the goals the run was asked decide it too.
+    if (Verified.YES === planned?.verified && false === goalMet)
+        return not(`NOT PROVED — ${planned.line.slice('PROVED — '.length).replace(/\.$/, '')}, but the goal was not reached.`);
+    if (planned !== undefined)
+        return planned;
+    if (0 === total)
+        return not('NOT PROVED: the drive ran no check.');
     if (0 < tally.failed)
-        return `NOT PROVED — ${counts}. The failures below are findings.`;
+        return {
+            verified: Verified.NO,
+            line: `NOT PROVED — ${counts}. The failures below are findings.`,
+        };
     if (0 < tally.undecided)
-        return `NOT PROVED — ${counts}.`;
-    return `PROVED — ${counts}.`;
+        return not(`NOT PROVED — ${counts}.`);
+    // Checks that held on the way are not the journey done.
+    if (false === goalMet)
+        return not(`NOT PROVED — ${counts}, but the goal was not reached.`);
+    return { verified: Verified.YES, line: `PROVED — ${counts}.` };
+}
+/** The line alone. */
+export function verdictLine(tally, goalMet, journeys = []) {
+    return runVerdict(tally, goalMet, journeys).line;
 }
-export function describeDrive(toolCalls, savedFlows, unverifiedFlows = []) {
+/** Whether the run is proved, exactly as its headline says: the `proved` an answer carries. */
+export function runProved(tally, goalMet, journeys = []) {
+    return Verified.YES === runVerdict(tally, goalMet, journeys).verified;
+}
+export function describeDrive(toolCalls, savedFlows, unverifiedFlows = [], goalMet, journeys = []) {
     const steps = drivenSteps(toolCalls);
     const replays = replayedFlows(toolCalls);
     /*
@@ -291,11 +484,15 @@ export function describeDrive(toolCalls, savedFlows, unverifiedFlows = []) {
             const failed = replays.filter((r) => ReplayOutcome.ERROR === r.status);
             const drifted = replays.filter((r) => ReplayOutcome.DRIFT === r.status);
             const guarded = replays.filter((r) => ReplayOutcome.GUARDED === r.status);
+            const missing = replays.filter((r) => ReplayOutcome.MISSING === r.status);
             const lines = [
                 `Replayed ${String(replays.length)} recorded journey(s) with NO model in the loop: ` +
                     `${String(held.length)} still hold, ${String(failed.length)} failed, ${String(drifted.length)} drifted` +
-                    `${0 === guarded.length ? '' : `, ${String(guarded.length)} not run`}.`,
+                    `${0 === guarded.length ? '' : `, ${String(guarded.length)} not run`}` +
+                    `${0 === missing.length ? '' : `, ${String(missing.length)} not on this computer`}.`,
             ];
+            if (0 < missing.length)
+                lines.push(`  MISSING: ${missing.map((r) => r.name).join(', ')} — not saved on this computer, or calls a flow that is not, so it never ran. Not a regression: pull or record them here first.`);
             if (0 < failed.length)
                 lines.push(`  FAILED: ${failed.map((r) => r.name).join(', ')} — regressions in journeys that used to pass.`);
             if (0 < guarded.length)
@@ -304,18 +501,32 @@ export function describeDrive(toolCalls, savedFlows, unverifiedFlows = []) {
                 lines.push(`  DRIFTED: ${drifted.map((r) => r.name).join(', ')} — the app moved under these recordings; the flow needs re-anchoring, not the app fixing.`);
             return lines.join('\n');
         })();
-    if (0 === steps.length)
-        return (replayLine ??
-            'Nothing was driven and nothing was replayed: the run made no action against the app.');
+    // A plan run leads with its journeys' verdict even when the model drove nothing: its replays, or
+    // a journey a guard stopped, are a result, never "no action against the app".
+    if (0 === steps.length) {
+        const lead = 0 === journeys.length ? undefined : verdictLine(checkTally(toolCalls), goalMet, journeys);
+        return [
+            lead,
+            replayLine ??
+                (lead === undefined
+                    ? 'Nothing was driven and nothing was replayed: the run made no action against the app.'
+                    : undefined),
+        ]
+            .filter((line) => line !== undefined)
+            .join('\n');
+    }
     const proved = steps.filter((step) => Verified.YES === step.verified);
     const failed = steps.filter((step) => Verified.NO === step.verified);
-    const undecided = steps.filter((step) => Verified.YES !== step.verified && Verified.NO !== step.verified);
+    // The driver's own route guesses are no check (as `checkTally` counts), so not "not decided".
+    const guesses = steps.filter((step) => true === step.guess);
+    const undecided = steps.filter((step) => true !== step.guess && Verified.YES !== step.verified && Verified.NO !== step.verified);
     const pages = pagesReached(toolCalls);
     const lines = [
-        verdictLine(checkTally(toolCalls)),
+        verdictLine(checkTally(toolCalls), goalMet, journeys),
         ...(replayLine === undefined ? [] : [replayLine]),
-        `Drove ${String(steps.length)} action(s): ${String(proved.length)} proved, ` +
-            `${String(failed.length)} failed, ${String(undecided.length)} not decided.`,
+        // The outcomes are counted once, in the checks line above: no second breakdown here.
+        `Drove ${String(steps.length)} action(s)` +
+            (0 === guesses.length ? '.' : `; ${String(guesses.length)} guess of its own, not a check.`),
         // How DEEP it got. An action count reads the same for a checkout walked to its receipt and for
         // eleven clicks on the home page; the pages reached are what tell them apart.
         ...(0 === pages.length
@@ -323,7 +534,7 @@ export function describeDrive(toolCalls, savedFlows, unverifiedFlows = []) {
             : [`Reached ${String(pages.length)} page(s): ${pages.join(' → ')}.`]),
         ...appFindings(toolCalls),
     ];
-    const listed = [...failed, ...proved, ...undecided].slice(0, Math.max(MAX_LISTED, Math.min(failed.length, MAX_FAILED)));
+    const listed = [...failed, ...proved, ...undecided, ...guesses].slice(0, Math.max(MAX_LISTED, Math.min(failed.length, MAX_FAILED)));
     for (const step of listed) {
         const verdict = step.verified ?? 'nothing declared';
         const because = step.because === undefined ? '' : ` — ${step.because}`;
@@ -349,10 +560,16 @@ export function describeDrive(toolCalls, savedFlows, unverifiedFlows = []) {
     const confirmed = confirmedDestructive(toolCalls);
     if (0 < confirmed)
         lines.push(`${String(confirmed)} destructive action(s) were confirmed and REALLY RAN against the app (the drive confirms one only after the gate refuses it; the refusal itself changed nothing).`);
-    if (0 < failed.length)
-        lines.push(`${String(failed.length)} action(s) FAILED — the app did not do what the drive declared it would. These are findings.`);
-    if (0 < undecided.length)
-        lines.push(`${String(undecided.length)} action(s) were NOT PROVED. That is undecided evidence, not a failure: it calls for a better check, not a code change.`);
+    // Counted from the same graded checks as the checks line, never from the raw step verdicts: an
+    // answer read "0 failed" beside "1 action(s) FAILED … These are findings" about one re-press.
+    const tally = checkTally(toolCalls);
+    if (0 < tally.failed)
+        lines.push(`${String(tally.failed)} check(s) FAILED — the app did not do what the drive declared it would. These are findings.`);
+    if (0 < tally.undecided)
+        lines.push(`${String(tally.undecided)} check(s) undecided. That is undecided evidence, not a failure: it calls for a better check, not a code change.`);
+    const undeclared = undecided.filter((step) => step.claimed === undefined).length;
+    if (0 < undeclared)
+        lines.push(`${String(undeclared)} action(s) declared no consequence, so they prove nothing either way: not a check, not a failure.`);
     // A flow with no step that asserts anything replays as "verified nothing": offered as a replay it
     // reads as evidence, so it is named for what it is instead.
     const empty = new Set(unverifiedFlows);

package/dist/features/harness/drive-runs.d.ts

@@ -0,0 +1,120 @@
+/**
+ * The Harness drives this daemon is running, and the ones it finished, by run id.
+ *
+ * A drive takes minutes and an MCP client gives a tool call about one. Awaited inside the call, a
+ * drive outlived the client's timeout: the agent got no run id, the daemon kept driving and
+ * spending, and a retry started a second paid drive. So a drive is started here and the call only
+ * waits on it for a while; whoever asks again by run id (the same agent, another one, the HUD)
+ * reads the same entry.
+ *
+ * No I/O and no tool surface: what to run and where to write it arrive as functions, so this stays
+ * a sink the surface hands things to.
+ */
+import { type ImpactSnapshot } from '@reticlehq/core';
+export declare const DriveStatus: {
+    readonly RUNNING: "running";
+    readonly DONE: "done";
+    readonly STOPPED: "stopped";
+    readonly BROKEN: "broken";
+    /** Refused before it drove anything (switched off, no credits, locked): not a broken drive. */
+    readonly REFUSED: "refused";
+};
+export type DriveStatus = (typeof DriveStatus)[keyof typeof DriveStatus];
+/**
+ * Thrown when the platform or the gate refuses a drive before it drives. Releasing a tab reported
+ * such a run as "broken", which reads as a fault in the Harness; a refusal is a refusal.
+ */
+export declare class DriveRefusedError extends Error {
+}
+/** Who asked for the drive. */
+export declare const DriveOrigin: {
+    readonly AGENT: "agent";
+    readonly HUD: "hud";
+    readonly CHAT: "chat";
+    readonly TRY: "try";
+};
+export type DriveOrigin = (typeof DriveOrigin)[keyof typeof DriveOrigin];
+/**
+ * One drive, as it is written to `.reticle/runs/<run>.drive.json` and answered to a poll.
+ *
+ * The id is `harnessRun`, never `runId`: the sync uploads every file in that directory carrying a
+ * `runId` as a verification run, and this record would then collide with the drive's own run.
+ */
+export interface DriveRecord {
+    harnessRun: string;
+    status: DriveStatus;
+    origin: DriveOrigin;
+    sessionId?: string;
+    startedAt: number;
+    endedAt?: number;
+    steps: number;
+    lastLine: string;
+    /** The tool's full answer, once the drive has ended. */
+    result?: Record<string, unknown>;
+    /** Why it broke, when it threw instead of answering. */
+    error?: string;
+}
+/** What a running drive reads from whoever started it. */
+export interface DriveControl {
+    /** True once somebody asked it to stop. */
+    stopped: () => boolean;
+    /** Text somebody said to it since it last asked, oldest first. */
+    takeSaid: () => string[];
+}
+export interface StartDrive {
+    harness: string;
+    runId: string;
+    origin: DriveOrigin;
+    sessionId?: string;
+    now: () => number;
+    persist: (record: DriveRecord) => Promise<void>;
+    run: (control: DriveControl) => Promise<{
+        status: DriveStatus;
+        result: Record<string, unknown>;
+    }>;
+}
+export declare function startDrive(start: StartDrive): DriveRecord;
+/** The drive this run id names, while this daemon still holds it. */
+export declare function driveRecord(runId: string): DriveRecord | undefined;
+/**
+ * The drive running on this session, if any. An unnamed session matches any running drive, and a
+ * drive started without one matches any session: either way it is the tab a second start would use.
+ */
+export declare function runningDrive(sessionId: string | undefined): DriveRecord | undefined;
+/** Every drive still running, for the HUD. */
+export declare function runningDrives(): DriveRecord[];
+/**
+ * Wait until the drive ends, `ms` passes (no limit when undefined), or `signal` aborts — whichever
+ * is first. Ending the wait never ends the drive. `onChange` hears every step while waiting.
+ */
+export declare function awaitDrive(runId: string, ms: number | undefined, signal?: AbortSignal, onChange?: (record: DriveRecord) => void): Promise<void>;
+/** Ask a running drive to stop. False when there is no such drive running. */
+export declare function stopDrive(runId: string): boolean;
+/** Queue text for the driver's next turn. False when there is no such drive running. */
+export declare function sayToDrive(runId: string, text: string): boolean;
+/** One tool call a drive made. `harness` may be a lane's id (`<harness>-L2`). */
+export declare function noteDriveStep(harness: string, tool: string): void;
+/** A line the drive narrated to the HUD. */
+export declare function noteDriveLine(harness: string, line: string): void;
+/** Hear every step a drive takes, so a panel showing its count can repaint. Returns the unsubscribe. */
+export declare function onDriveStep(listener: (record: DriveRecord) => void): () => void;
+/** Hear every drive start and end, from any origin. Returns the unsubscribe. */
+export declare function onDriveChange(listener: (record: DriveRecord) => void): () => void;
+/**
+ * The notes the agent has not heard: a drive started or finished, from any origin. Taken once.
+ * `except` is the run the agent is already reading, which needs no note about itself.
+ */
+export declare function takeDriveNotes(except?: string): string[];
+/** Tests only: every drive and note forgotten. */
+export declare function forgetDrives(): void;
+/**
+ * How long one poll waits on a drive before answering `running`. Under the 60s tool timeout most
+ * MCP clients use, with room for the answer to travel; a poll's `wait` overrides it.
+ */
+export declare const POLL_WAIT_DEFAULT_S = 50;
+/** The exact call that reads a drive: the same call while it runs and once it has ended. */
+export declare function pollCall(runId: string): string;
+/** What a poll answering `running` tells the agent to do, so it stays rather than walks away. */
+export declare function stillRunning(runId: string, steps: number, elapsedS: number): string;
+/** The impact snapshot, with the drive running on this tab when there is one. */
+export declare function withRunningDrive(snapshot: ImpactSnapshot | undefined, sessionId: string): ImpactSnapshot | undefined;