@reticlehq/server 3.6.0 → 3.7.0

package/dist/command/version/version-skew.js

@@ -30,6 +30,12 @@ export const SkewPair = {
     SDK: 'sdk',
     /** Another Reticle process — a CLI, or the MCP server an agent spawned — vs this daemon. */
     DAEMON: 'daemon',
+    /**
+     * The SDK in the page is a minor or more behind, on the same contract: compatible, so it is news
+     * and not a cause. Its own pair so it never displaces an untold real skew, and never stands in for
+     * the advice on an error it did not cause (see takeVersionSkewOnto).
+     */
+    SDK_BEHIND: 'sdk_behind',
 };
 /**
  * Names the peer speaks that we have never heard of.
@@ -50,6 +56,9 @@ function namesWeDoNotKnow(peer, self) {
     ].filter((name) => !RETIRED_WIRE_NAMES.includes(name));
     return [...new Set(unknown)].sort();
 }
+/** The fix for two builds of one version. */
+const SAME_VERSION_FIX = 'Both say the same version, so one of them is an older build of it: run `reticle restart`, then ' +
+    'reload the page so it loads the SDK the dev server serves now.';
 function versionPhrase(peer, self) {
     return peer.version === undefined
         ? `${peer.what} is on an unknown version; this daemon is ${self.version}`
@@ -72,9 +81,12 @@ function versionPhrase(peer, self) {
  * a build provably older than this daemon. With neither signal there is nothing to go on, and
  * inventing a warning would be as dishonest as staying silent about a real one.
  */
-export function describeSkew(peer, self) {
-    if (peer.contract !== undefined && peer.contract === self.contract)
+export function describeSkew(given, self) {
+    if (given.contract !== undefined && given.contract === self.contract)
         return undefined;
+    // One version, two builds (a daemon running code older than its install, a cached page bundle):
+    // installing that version again changes nothing, so the fix is the restart and the reload.
+    const peer = given.version === self.version ? { ...given, fix: SAME_VERSION_FIX } : given;
     // Both sides said which names they speak, so compare the names rather than a hash over them.
     if (peer.contractParts !== undefined && self.contractParts !== undefined) {
         const unknown = namesWeDoNotKnow(peer.contractParts, self.contractParts);
@@ -152,6 +164,30 @@ function compareVersions(a, b) {
     }
     return 0;
 }
+/** The same fact for the person looking at the page, on its overlay. */
+export const SDK_BEHIND_NARRATION = (sdk, daemon) => `This app runs Reticle SDK ${sdk}, older than Reticle ${daemon}. Run \`reticle update\` in the ` +
+    "app's folder, then restart its dev server.";
+/**
+ * A page whose SDK is a minor release or more behind this daemon.
+ *
+ * `describeSkew` is silent here on purpose: the contract matches, so the page connects and every
+ * verdict is sound. But whatever shipped since is not in the page, the overlay included, and from
+ * the field that looked exactly like a broken release: the CLI reported the new version while the
+ * page showed an overlay without the newer controls, and nothing anywhere said which SDK it was
+ * running. Patch releases stay silent for the cry-wolf reason in the header. `fix` is a thunk
+ * because reading the project's manifest is only worth it when the page IS behind.
+ */
+export function describeSdkBehind(sdk, daemon, fix) {
+    const minorOf = (v) => v.split('-')[0]?.split('.').slice(0, 2).join('.') ?? v;
+    if (sdk === undefined)
+        return undefined;
+    const order = compareVersions(minorOf(sdk), minorOf(daemon));
+    if (order === undefined || order >= 0)
+        return undefined;
+    return (`This page runs Reticle SDK ${sdk}, older than Reticle ${daemon}. It connects and verifies, ` +
+        `but everything added since is missing from the page, the overlay's newer controls included. ` +
+        fix());
+}
 /**
  * The fix line for another Reticle process that disagrees with the daemon it attached to.
  *

package/dist/features/crawl/crawl.js

@@ -33,6 +33,13 @@ function revealedControlsNote(count) {
         'started were never visited — interactiveFound is a floor, not a total; re-run the crawl from ' +
         'the state you are now in to cover them');
 }
+/**
+ * Controls that end the signed-in session. Not destructive (signing out is reversible, so the
+ * action gate lets it through), but a crawl that presses one drives everything after it signed out:
+ * every Harness plan run clicked the sidebar's "Sign out", then stale refs on the sign-in page.
+ */
+const ENDS_SESSION = /\b(?:sign ?out|log ?out|sign ?off|log ?off)\b/i;
+const ENDS_SESSION_NOT_PRESSED = 'not pressed: it ends the signed-in session the crawl is driving';
 /** Why a silent control on a throttled page is not reported as dead. */
 const BACKGROUND_TAB_NOT_JUDGED = 'not judged: the page is throttled (its tab is in the background, or it has not been heard from recently), so a reaction may not show inside the sample window; bring the tab to the front and crawl again';
 /** Any buffer event that proves the app reacted to a click (vs a dead/no-op control). */
@@ -278,6 +285,10 @@ export async function crawl(session, opts, sleep) {
             if (seen.has(dedupeKey))
                 continue; // don't re-click the same control
             seen.add(dedupeKey);
+            if (ENDS_SESSION.test(item.desc)) {
+                notJudged.push({ ref: item.ref, desc: item.desc, reason: ENDS_SESSION_NOT_PRESSED });
+                continue;
+            }
             stepsRun += 1;
             visited.push(item.desc);
             const since = session.elapsed();
@@ -436,6 +447,8 @@ export async function crawl(session, opts, sleep) {
     // unvisited. Skipped when the snapshot was already capped: that case has its own note and a second
     // one would only muddy it.
     const revealed = coverageCapped ? 0 : (await revealedItems(session, opts, found)).length;
+    // Left alone on purpose, so not a step the budget ran out before.
+    const leftAlone = notJudged.filter((n) => ENDS_SESSION_NOT_PRESSED === n.reason).length;
     return {
         interactiveFound: found.length,
         stepsRun,
@@ -446,7 +459,7 @@ export async function crawl(session, opts, sleep) {
         // True when coverage was bounded for EITHER reason: the step budget ran out, or the page was
         // bigger than one snapshot. Conflating "I stopped early" with "I saw everything" is what turns a
         // partial sweep into "all controls healthy".
-        truncated: found.length > stepsRun || coverageCapped || revealed > 0,
+        truncated: found.length - leftAlone > stepsRun || coverageCapped || revealed > 0,
         ...(coverageCapped
             ? { coverageNote: CAPPED_SNAPSHOT_NOTE }
             : revealed > 0

package/dist/features/exhaust/ledger.d.ts

@@ -47,12 +47,12 @@ declare const LedgerSchema: z.ZodObject<{
         proved: z.ZodArray<z.ZodString, "many">;
     }, "strip", z.ZodTypeAny, {
         proved: string[];
-        touched: string[];
         seen: string[];
+        touched: string[];
     }, {
         proved: string[];
-        touched: string[];
         seen: string[];
+        touched: string[];
     }>;
     journeys: z.ZodObject<{
         completed: z.ZodArray<z.ZodString, "many">;
@@ -66,12 +66,12 @@ declare const LedgerSchema: z.ZodObject<{
         branched: z.ZodArray<z.ZodString, "many">;
         unhandled: z.ZodArray<z.ZodString, "many">;
     }, "strip", z.ZodTypeAny, {
-        branched: string[];
         seen: string[];
+        branched: string[];
         unhandled: string[];
     }, {
-        branched: string[];
         seen: string[];
+        branched: string[];
         unhandled: string[];
     }>;
     code: z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodObject<{
@@ -92,6 +92,9 @@ declare const LedgerSchema: z.ZodObject<{
         name: string;
         executed: boolean;
     }>>;
+    journeys: {
+        completed: string[];
+    };
     best: Record<string, number>;
     routes: {
         reached: string[];
@@ -99,15 +102,12 @@ declare const LedgerSchema: z.ZodObject<{
     };
     controls: {
         proved: string[];
-        touched: string[];
         seen: string[];
-    };
-    journeys: {
-        completed: string[];
+        touched: string[];
     };
     writes: {
-        branched: string[];
         seen: string[];
+        branched: string[];
         unhandled: string[];
     };
     codeTaken: Record<string, number>;
@@ -116,6 +116,9 @@ declare const LedgerSchema: z.ZodObject<{
         name: string;
         executed: boolean;
     }>>;
+    journeys: {
+        completed: string[];
+    };
     best: Record<string, number>;
     routes: {
         reached: string[];
@@ -123,15 +126,12 @@ declare const LedgerSchema: z.ZodObject<{
     };
     controls: {
         proved: string[];
-        touched: string[];
         seen: string[];
-    };
-    journeys: {
-        completed: string[];
+        touched: string[];
     };
     writes: {
-        branched: string[];
         seen: string[];
+        branched: string[];
         unhandled: string[];
     };
     codeTaken?: Record<string, number> | undefined;

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

@@ -17,6 +17,7 @@
  * that is what a coding agent has to gate on, and it says "not proved" in those words rather than
  * leaving a verdict of `unknown` to be read as a pass.
  */
+import { Verified } from '@reticlehq/core';
 import type { ToolOutcome } from './harness.js';
 /** One driven action, reduced to what a reader needs: what was done, and what it proved. */
 export interface DrivenStep {
@@ -26,6 +27,8 @@ export interface DrivenStep {
     target: string;
     /** The engine's verdict for this step, when the step declared anything. */
     verified: string | undefined;
+    /** A route claim that missed: the driver's own guess, or a menu it opened. Never a check. */
+    guess?: true;
     /** The one sentence naming the deciding evidence. */
     because: string | undefined;
     /**
@@ -64,6 +67,8 @@ export declare const ReplayOutcome: {
     readonly ERROR: "error";
     /** Stopped at a step the flow marks destructive: not run, which is not a regression. */
     readonly GUARDED: "guarded";
+    /** Not saved on this computer: nothing ran, which is not a regression either. */
+    readonly MISSING: "missing";
 };
 export declare function replayedFlows(toolCalls: readonly ToolOutcome[]): {
     name: string;
@@ -71,20 +76,49 @@ export declare function replayedFlows(toolCalls: readonly ToolOutcome[]): {
 }[];
 /** Reduce the raw call log to the actions that actually drove the app. */
 export declare function drivenSteps(toolCalls: readonly ToolOutcome[]): DrivenStep[];
+/** Whether the drive did anything to the app: an action that ran, or a flow it replayed. */
+export declare function actedOnApp(toolCalls: readonly ToolOutcome[]): boolean;
+/** The pages the drive's own snapshots reported, in order, each distinct page once. */
+export declare function pagesReached(toolCalls: readonly ToolOutcome[]): string[];
+/** The values the drive's acts filled or typed, sequence steps included. */
+export declare function typedValues(toolCalls: readonly ToolOutcome[]): string[];
 /** How the drive's checks came out: act_and_wait with an `until`, and asserts. */
 export declare function checkTally(toolCalls: readonly ToolOutcome[]): {
     held: number;
     failed: number;
     undecided: number;
 };
+/** A plan journey's status, as far as the run's verdict reads it. */
+export interface JourneyStatus {
+    status: string;
+}
+/** A run's verdict and the line that says it: the word is decided once, never read back out of the line. */
+export interface RunVerdict {
+    verified: Verified;
+    line: string;
+}
 /**
- * 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 declare function runVerdict(tally: {
+    held: number;
+    failed: number;
+    undecided: number;
+}, goalMet?: boolean, 
+/** A plan's journeys: when there are any, their verdict is the run's. */
+journeys?: readonly JourneyStatus[]): RunVerdict;
+/** The line alone. */
 export declare function verdictLine(tally: {
     held: number;
     failed: number;
     undecided: number;
-}): string;
-export declare function describeDrive(toolCalls: readonly ToolOutcome[], savedFlows: readonly string[], unverifiedFlows?: readonly string[]): string;
+}, goalMet?: boolean, journeys?: readonly JourneyStatus[]): string;
+/** Whether the run is proved, exactly as its headline says: the `proved` an answer carries. */
+export declare function runProved(tally: {
+    held: number;
+    failed: number;
+    undecided: number;
+}, goalMet?: boolean, journeys?: readonly JourneyStatus[]): boolean;
+export declare function describeDrive(toolCalls: readonly ToolOutcome[], savedFlows: readonly string[], unverifiedFlows?: readonly string[], goalMet?: boolean, journeys?: readonly JourneyStatus[]): string;