@reticlehq/server 3.5.0 → 3.7.0

package/dist/command/setup/tauri-signing.js

@@ -0,0 +1,79 @@
+/**
+ * Sign the Tauri dev build Reticle starts with the project's own signing identity, so macOS stops
+ * asking for the keychain password.
+ *
+ * macOS ties a keychain item to the designated requirement of the app that saved it: its code
+ * identifier and its signing team. `tauri dev` produces an ad-hoc signed binary named after the
+ * crate, so every keychain read from it is a different app asking, and macOS prompts each time.
+ * `reticle doctor` explained that; this removes it when the project has said who signs it.
+ *
+ * `APPLE_SIGNING_IDENTITY` cannot simply be passed through: Tauri reads it only when it bundles
+ * (`tauri build`), never in `tauri dev`. What `tauri dev` does run is `cargo run`, and Cargo hands
+ * the freshly built binary to a per-target RUNNER before executing it. The runner written here signs
+ * that binary — with the identity, and with the app's bundle identifier so the requirement matches
+ * the release app's — and then executes it unchanged. A signing failure is said on stderr and never
+ * stops the app.
+ *
+ * Nothing happens off macOS, outside a Tauri project, with no identity, with the ad-hoc identity
+ * `-` (which matches nothing), or when the project already sets a Cargo runner of its own.
+ */
+import { join } from 'node:path';
+/** The env the runner reads its arguments from: the script stays a fixed file. */
+export const SigningEnv = {
+    IDENTITY: 'RETICLE_SIGNING_IDENTITY',
+    IDENTIFIER: 'RETICLE_SIGNING_IDENTIFIER',
+    APPLE: 'APPLE_SIGNING_IDENTITY',
+};
+/** Cargo's runner variable for each Mac target `tauri dev` builds. */
+const RUNNER_VARS = [
+    'CARGO_TARGET_AARCH64_APPLE_DARWIN_RUNNER',
+    'CARGO_TARGET_X86_64_APPLE_DARWIN_RUNNER',
+];
+const DARWIN = 'darwin';
+const AD_HOC = '-';
+const TAURI_CONF = join('src-tauri', 'tauri.conf.json');
+export const RUNNER_FILE = 'tauri-sign-runner.sh';
+/** The runner: sign the binary Cargo built, then run it exactly as Cargo would have. */
+export const RUNNER_SCRIPT = `#!/bin/sh
+# Written by Reticle. Signs the Tauri dev build with this project's signing identity before it
+# starts, so macOS treats it as the app that owns your keychain items and stops asking for the
+# password. Remove RETICLE_SIGNING_IDENTITY from the environment to turn it off.
+codesign --force --sign "$${SigningEnv.IDENTITY}" --identifier "$${SigningEnv.IDENTIFIER}" "$1" >/dev/null 2>&1 ||
+  echo "reticle: could not sign $1 with $${SigningEnv.IDENTITY}; macOS may ask for the keychain password" >&2
+exec "$@"
+`;
+const asRecord = (value) => 'object' === typeof value && null !== value ? value : {};
+const asText = (value) => 'string' === typeof value && 0 < value.trim().length ? value.trim() : undefined;
+/** The extra env for starting a Tauri dev build signed, or `{}` when there is nothing to sign with. */
+export function tauriSigningEnv(deps) {
+    if (DARWIN !== deps.platform)
+        return {};
+    const raw = deps.read(TAURI_CONF);
+    if (raw === undefined)
+        return {};
+    let conf;
+    try {
+        conf = asRecord(JSON.parse(raw));
+    }
+    catch {
+        return {};
+    }
+    const macOS = asRecord(asRecord(conf['bundle'])['macOS']);
+    const identity = asText(deps.env[SigningEnv.APPLE]) ?? asText(macOS['signingIdentity']);
+    const identifier = asText(conf['identifier']);
+    if (identity === undefined || AD_HOC === identity || identifier === undefined)
+        return {};
+    // A project that runs its builds through a runner of its own keeps it.
+    if (RUNNER_VARS.some((name) => deps.env[name] !== undefined))
+        return {};
+    const runner = deps.writeRunner(RUNNER_FILE, RUNNER_SCRIPT);
+    // Cargo splits a runner given in the environment on whitespace, so a path with a space in it
+    // would run the wrong program. ponytail: skip it; doctor still explains the prompt.
+    if (/\s/.test(runner))
+        return {};
+    return {
+        [SigningEnv.IDENTITY]: identity,
+        [SigningEnv.IDENTIFIER]: identifier,
+        ...Object.fromEntries(RUNNER_VARS.map((name) => [name, runner])),
+    };
+}

package/dist/command/setup/terminal/listeners.d.ts

@@ -21,11 +21,20 @@ export declare function parseLsofPorts(out: string): number[];
  * and taking index 1 reads every IPv6 row as port 0 and silently drops half the table.
  */
 export declare function parseNetstatListeners(out: string): Listener[];
-/** One (pid, parent) pair, as `wmic process get ParentProcessId,ProcessId` prints them. */
+/**
+ * One (pid, parent) pair, as `wmic process get CreationDate,ParentProcessId,ProcessId` prints them.
+ *
+ * `startedAtMs` is the process's own creation time, when the source gave one. It is what tells a
+ * real child from a stale link: Windows never clears ParentProcessId when a parent exits, and it
+ * reuses pids, so "ppid matches" alone can adopt an unrelated, older process. See `descendants`.
+ */
 export interface ProcessPair {
     readonly pid: number;
     readonly ppid: number;
+    readonly startedAtMs?: number;
 }
+/** Epoch milliseconds of a WMI datetime, or undefined when it is not one. */
+export declare function parseWmiDatetime(text: string): number | undefined;
 export declare function parseWmicProcesses(out: string): ProcessPair[];
 /**
  * `root` and everything descended from it.

package/dist/command/setup/terminal/listeners.js

@@ -39,16 +39,37 @@ export function parseNetstatListeners(out) {
     }
     return rows;
 }
+/** A WMI datetime: `yyyymmddHHMMSS.ffffff` then the offset from UTC in minutes, `+000` / `-300`. */
+const WMI_DATETIME = /^(\d{4})(\d{2})(\d{2})(\d{2})(\d{2})(\d{2})\.(\d{6})([+-])(\d{3})$/;
+const MICROS_PER_MS = 1000;
+const MS_PER_MINUTE = 60_000;
+/** Epoch milliseconds of a WMI datetime, or undefined when it is not one. */
+export function parseWmiDatetime(text) {
+    const m = WMI_DATETIME.exec(text);
+    if (null === m)
+        return undefined;
+    const n = (index) => Number(m[index]);
+    const local = Date.UTC(n(1), n(2) - 1, n(3), n(4), n(5), n(6), Math.floor(n(7) / MICROS_PER_MS));
+    const minutesEast = '-' === m[8] ? -n(9) : n(9);
+    return local - minutesEast * MS_PER_MINUTE;
+}
 export function parseWmicProcesses(out) {
     const pairs = [];
     for (const line of String(out).split(/\r?\n/)) {
         const f = line.trim().split(/\s+/);
-        if (f.length !== 2)
+        // Two columns (ppid pid), or three with the creation time first: wmic prints its columns in
+        // alphabetical order, and the PowerShell fallback prints the same shape on purpose.
+        const timed = 3 === f.length;
+        if (!timed && 2 !== f.length)
+            continue;
+        const startedAtMs = timed ? parseWmiDatetime(f[0] ?? '') : undefined;
+        if (timed && undefined === startedAtMs)
+            continue;
+        const ppid = Number(f[timed ? 1 : 0]);
+        const pid = Number(f[timed ? 2 : 1]);
+        if (!Number.isInteger(pid) || !Number.isInteger(ppid))
             continue;
-        const ppid = Number(f[0]);
-        const pid = Number(f[1]);
-        if (Number.isInteger(pid) && Number.isInteger(ppid))
-            pairs.push({ pid, ppid });
+        pairs.push(undefined === startedAtMs ? { pid, ppid } : { pid, ppid, startedAtMs });
     }
     return pairs;
 }
@@ -60,8 +81,18 @@ export function parseWmicProcesses(out) {
  * indistinguishable from "no server".
  */
 export function descendants(pairs, root) {
+    const startedAt = new Map();
+    for (const { pid, startedAtMs } of pairs) {
+        if (undefined !== startedAtMs)
+            startedAt.set(pid, startedAtMs);
+    }
     const byParent = new Map();
-    for (const { pid, ppid } of pairs) {
+    for (const { pid, ppid, startedAtMs } of pairs) {
+        // A child created before the parent it names is a stale link left by pid reuse, not a child.
+        const parentStarted = startedAt.get(ppid);
+        if (undefined !== startedAtMs && undefined !== parentStarted && startedAtMs < parentStarted) {
+            continue;
+        }
         const kids = byParent.get(ppid);
         if (kids === undefined)
             byParent.set(ppid, [pid]);

package/dist/command/update/update-nudge.d.ts

@@ -1,3 +1,12 @@
+/**
+ * Is `candidate` a strictly NEWER release than `current`?
+ *
+ * Replaces a plain `!==`, which told anyone on a version newer than the published one — a
+ * prerelease, a local build, a rollback in progress — to "update" to something older. A nudge that
+ * prompts a downgrade is one people learn to ignore. Numeric per segment, so a 10 patch correctly
+ * beats a 9 (string order does not), and a bare release beats its own prerelease.
+ */
+export declare function isNewerVersion(candidate: string, current: string): boolean;
 interface UpdateNudge {
     /** The version available, so the agent can tell the human what they would be moving to. */
     latestVersion: string;

package/dist/command/update/update-nudge.js

@@ -28,7 +28,7 @@ import { creditNudge } from './nudge-credit.js';
  * prompts a downgrade is one people learn to ignore. Numeric per segment, so a 10 patch correctly
  * beats a 9 (string order does not), and a bare release beats its own prerelease.
  */
-function isNewerVersion(candidate, current) {
+export function isNewerVersion(candidate, current) {
     const parse = (v) => {
         const [core = '', ...rest] = v.split(/[-+]/);
         return { parts: core.split('.').map((n) => Number.parseInt(n, 10) || 0), pre: rest.length > 0 };

package/dist/command/update/updater.js

@@ -168,15 +168,6 @@ async function installVersion(version, kind) {
     }
     await runNpm(plan.args, plan.cwd !== undefined ? { cwd: plan.cwd } : {});
 }
-async function installVersionRollback(version, kind) {
-    if (kind === ExecutionKind.NPX) {
-        log('reticle_rollback_npx_strategy', {
-            note: 'Running via npx — update your .mcp.json args to pin the version you want to restore',
-        });
-        return;
-    }
-    await installVersion(version, kind);
-}
 /**
  * Install targetVersion using the appropriate strategy for the detected execution kind,
  * then exit so Claude Code restarts with the new binary. Saves the current version
@@ -209,15 +200,20 @@ export async function rollback() {
     }
     const prev = manifest.previousVersion;
     const kind = detectExecutionKind();
+    // Under npx there is nothing to reinstall: the next start re-resolves the package. Say how to pin
+    // the old version and stop, rather than logging and reporting a rollback that never landed.
+    if (kind === ExecutionKind.NPX) {
+        log('reticle_rollback_npx_strategy', {
+            version: prev,
+            note: 'Running via npx — update your .mcp.json args to pin the version you want to restore',
+        });
+        return;
+    }
     log('reticle_rollback_applying', { version: prev, executionKind: kind });
-    await installVersionRollback(prev, kind);
+    await installVersion(prev, kind);
     log('reticle_rollback_applied', { version: prev, executionKind: kind });
     // A rollback is a release-quality alarm — someone shipped something that broke a real user badly
     // enough for them to go backwards. Worth knowing about within the hour, not at the next retro.
     await reportVersionChange(SERVER_VERSION, prev, VersionChangeDirection.ROLLBACK);
-    // For npx, exiting would let the next restart re-resolve @latest — rolling FORWARD, the opposite
-    // of rollback. installVersionRollback already told the user to pin the version in.mcp.json, so
-    // stay running rather than trigger that. Other kinds installed the old version and must restart.
-    if (kind !== ExecutionKind.NPX)
-        process.exit(0);
+    process.exit(0);
 }

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

@@ -68,6 +68,9 @@ export function takeVersionSkewOnto(payload, connection) {
     const skew = takeVersionSkew(connection);
     if (skew === undefined)
         return payload;
+    // Compatible, so it did not cause this error: ride along, and leave the advice and the ask alone.
+    if (SkewPair.SDK_BEHIND === skew.pair)
+        return { ...payload, [EnvelopeKey.VERSION_SKEW]: skew };
     const { feedback, ...rest } = payload;
     return {
         ...rest,

package/dist/command/version/version-skew.d.ts

@@ -28,6 +28,12 @@ export declare const SkewPair: {
     readonly SDK: "sdk";
     /** Another Reticle process — a CLI, or the MCP server an agent spawned — vs this daemon. */
     readonly 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).
+     */
+    readonly SDK_BEHIND: "sdk_behind";
 };
 export type SkewPair = (typeof SkewPair)[keyof typeof SkewPair];
 /** What a piece says about itself when it connects. */
@@ -78,7 +84,7 @@ interface SelfIdentity {
  * 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 declare function describeSkew(peer: PeerIdentity, self: SelfIdentity): string | undefined;
+export declare function describeSkew(given: PeerIdentity, self: SelfIdentity): string | undefined;
 /**
  * The fix line for a page whose SDK disagrees with this daemon, with no project to read.
  *
@@ -88,6 +94,19 @@ export declare function describeSkew(peer: PeerIdentity, self: SelfIdentity): st
  * `@reticlehq/react` and told Vue projects to install a React package (#618).
  */
 export declare function sdkFix(daemonVersion: string): string;
+/** The same fact for the person looking at the page, on its overlay. */
+export declare const SDK_BEHIND_NARRATION: (sdk: string, daemon: string) => string;
+/**
+ * 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 declare function describeSdkBehind(sdk: string | undefined, daemon: string, fix: () => string): string | undefined;
 /**
  * The fix line for another Reticle process that disagrees with the daemon it attached to.
  *

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

@@ -22,6 +22,7 @@
  * the wire changes and stays put when internals do. Versions still ride along, because they are what
  * a human acts on.
  */
+import { RETIRED_WIRE_NAMES } from '@reticlehq/core';
 import { resolveSdkFix } from './sdk-fix.js';
 /** Which pair disagreed. Named so the nudge can report each independently. */
 export const SkewPair = {
@@ -29,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.
@@ -38,15 +45,20 @@ export const SkewPair = {
  * is not a browser to do -- there is no touch equivalent of a console error. A peer speaking a name
  * we do not know was built against a contract this daemon does not have, and that is a genuine
  * mismatch: one of us is stale, and tools will behave in ways neither side reports.
+ *
+ * A name we RETIRED is not unknown: an older peer still lists it, and we never send it (#1343).
  */
 function namesWeDoNotKnow(peer, self) {
     const unknown = [
         ...peer.commands.filter((name) => !self.commands.includes(name)),
         ...peer.events.filter((name) => !self.events.includes(name)),
         ...peer.actions.filter((name) => !self.actions.includes(name)),
-    ];
+    ].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}`
@@ -69,16 +81,25 @@ 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);
         if (0 === unknown.length)
             return undefined;
+        // Direction comes from the versions when both are known. An older peer naming something we do
+        // not know has a name we removed without retiring it, not a newer contract.
+        const order = compareVersions(peer.version, self.version);
+        const why = order !== undefined && order < 0
+            ? 'though it is the older of the two — so this daemon dropped a name it still uses'
+            : 'so it was built against a newer contract than this one';
         return (`version skew: ${versionPhrase(peer, self)}, and ${peer.what} speaks names this daemon does ` +
-            `not know (${unknown.join(', ')}) — so it was built against a newer contract than this one. ` +
+            `not know (${unknown.join(', ')}) — ${why}. ` +
             `Tools will behave in ways neither side reports. ${peer.fix}`);
     }
     if (peer.contract === undefined) {
@@ -143,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-tools.js

@@ -87,6 +87,10 @@ export const CRAWL_TOOLS = [
                 .optional()
                 .describe('Present only when the page exceeded one snapshot, so controls past the cap were never listed. When present, a zero-anomaly result does NOT mean the app is clean.'),
             truncated: z.boolean(),
+            notJudged: z
+                .array(z.object({ ref: z.string(), desc: z.string(), reason: z.string() }))
+                .optional()
+                .describe('Controls clicked whose silence could not be judged, e.g. on a background tab. They are NOT reported as dead, and they are not known to work either.'),
             // Only on `exhaustive` — see features/exhaust/exhaust-run.ts. Loose: it carries the levels.
             exhaustive: z.record(z.unknown()).optional(),
         },

package/dist/features/crawl/crawl.d.ts

@@ -81,6 +81,12 @@ export interface CrawlReport {
     truncated: boolean;
     /** Present only when the snapshot itself was capped, i.e. controls exist that were never listed. */
     coverageNote?: string;
+    /** Controls whose silence could not be judged, present only when non-empty. */
+    notJudged?: {
+        ref: string;
+        desc: string;
+        reason: string;
+    }[];
 }
 export interface CrawlOptions {
     maxSteps?: number;

package/dist/features/crawl/crawl.js

@@ -33,6 +33,15 @@ 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). */
 function isActivity(e) {
     return (e.type === EventType.NET_REQUEST ||
@@ -255,6 +264,7 @@ export async function crawl(session, opts, sleep) {
     // `truncated:false` would positively assert that nothing was cut.
     const coverageCapped = true === snapshot.truncated;
     const anomalies = [];
+    const notJudged = [];
     const visited = [];
     const counts = { consoleErrors: 0, failedRequests: 0, deadControls: 0, contradictions: 0 };
     const seen = new Set();
@@ -275,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();
@@ -401,7 +415,11 @@ export async function crawl(session, opts, sleep) {
                 //
                 // A second click costs one round trip on the rare control that looked dead, and nothing at all
                 // on every control that did not. A genuinely dead control is silent twice; the flake is not.
-                if (await stillSilent(session, item, settleMs, confirm, sleep)) {
+                // A throttled page may defer DOM observer flushes, so silence cannot prove a dead control.
+                if (true === session.throttled?.()) {
+                    notJudged.push({ ref: item.ref, desc: item.desc, reason: BACKGROUND_TAB_NOT_JUDGED });
+                }
+                else if (await stillSilent(session, item, settleMs, confirm, sleep)) {
                     counts.deadControls += 1;
                     anomalies.push({
                         kind: CrawlAnomalyKind.DEAD_CONTROL,
@@ -429,16 +447,19 @@ 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,
         anomalies,
         counts,
         visited,
+        ...(0 === notJudged.length ? {} : { notJudged }),
         // 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;
@@ -158,6 +158,13 @@ export interface LevelReport {
     /** How many more are missing than `missing` names. */
     missingOverflow?: number;
 }
+/**
+ * Each level's percentage for the project at `reticleRoot`, for the HUD: numbers only, and only the
+ * levels with an honest denominator. Undefined when nothing has been measured yet.
+ *
+ * Synchronous because the impact snapshot it feeds is: one small file read per snapshot.
+ */
+export declare function coveragePercents(reticleRoot: string): Record<string, number> | undefined;
 export declare function emptyLedger(): AppLedger;
 export declare function mergeLedger(into: AppLedger, delta: LedgerDelta): AppLedger;
 export declare function levelsOf(ledger: AppLedger): LevelReport[];

package/dist/features/exhaust/ledger.js

@@ -18,6 +18,7 @@
  * Union-only. A later drive can add coverage and never remove it, so the number only moves down when
  * the app grows something nobody has covered yet — which is precisely what the ratchet is for.
  */
+import { readFileSync } from 'node:fs';
 import { dirname } from 'node:path';
 import { z } from 'zod';
 import { writeFileAtomic } from '../../memory/project/fs/write-atomic.js';
@@ -45,6 +46,39 @@ const LedgerSchema = z.object({
     codeTaken: z.record(z.number()).default({}),
     best: z.record(z.number()),
 });
+/** A ledger file's text, or an empty ledger for anything unreadable: coverage never throws. */
+function parseLedger(text) {
+    try {
+        const parsed = z
+            .object({ version: z.literal(LEDGER_VERSION), ledger: LedgerSchema })
+            .safeParse(JSON.parse(text));
+        return parsed.success ? parsed.data.ledger : emptyLedger();
+    }
+    catch {
+        return emptyLedger();
+    }
+}
+/**
+ * Each level's percentage for the project at `reticleRoot`, for the HUD: numbers only, and only the
+ * levels with an honest denominator. Undefined when nothing has been measured yet.
+ *
+ * Synchronous because the impact snapshot it feeds is: one small file read per snapshot.
+ */
+export function coveragePercents(reticleRoot) {
+    let text;
+    try {
+        text = readFileSync(reticleDirPaths(reticleRoot).coverage, 'utf8');
+    }
+    catch {
+        return undefined;
+    }
+    const out = {};
+    for (const report of levelsOf(parseLedger(text))) {
+        if (report.pct !== undefined)
+            out[report.level] = report.pct;
+    }
+    return 0 < Object.keys(out).length ? out : undefined;
+}
 export function emptyLedger() {
     return {
         routes: { discovered: [], reached: [] },
@@ -213,15 +247,7 @@ export class LedgerStore {
                 return emptyLedger();
             throw error;
         }
-        try {
-            const parsed = z
-                .object({ version: z.literal(LEDGER_VERSION), ledger: LedgerSchema })
-                .safeParse(JSON.parse(text));
-            return parsed.success ? parsed.data.ledger : emptyLedger();
-        }
-        catch {
-            return emptyLedger();
-        }
+        return parseLedger(text);
     }
     /**
      * Fold a delta in, raise the best, persist, and hand back the result. Under the file's lock: two

package/dist/features/harness/app-findings.d.ts

@@ -0,0 +1,2 @@
+import type { ToolOutcome } from './harness.js';
+export declare function appFindings(toolCalls: readonly ToolOutcome[]): string[];