@reticlehq/server 2.14.0 → 3.2.0

package/dist/language/flows/suite/server-verify.js

@@ -0,0 +1,56 @@
+import { VerifyMode } from '../../../memory/cloud/cloud-config.js';
+import { CLOUD_VERIFY_TIMEOUT_MS, cloudFetch, submitServerVerification, } from '../../../memory/cloud/cloud-sync.js';
+import { log } from '../../../log.js';
+const PASS = 'pass';
+const UNVERIFIED = 'unverified';
+const SOURCE = 'reticle-mcp';
+/** Map the hosted runner's report onto the local suite-verdict shape (status/total/passed/failed/failures). */
+export function toSuiteVerdict(report) {
+    const failures = report.flows
+        .filter((f) => f.status !== PASS)
+        .map((f) => ({
+        flow: f.name,
+        verdict: 'fail',
+        nextAction: `verified on the server — see report ${report.verificationId}`,
+    }));
+    const total = report.flows.length;
+    const passed = total - failures.length;
+    const status = report.verdict === PASS && 0 === failures.length ? 'pass' : 'fail';
+    return { status, total, passed, failed: failures.length, summary: report.summary, failures };
+}
+/** Run the suite on the hosted runner, or null to signal the caller should replay locally. */
+export async function runServerVerify(deps, cloud, sessionId, flows) {
+    if (cloud.verify !== VerifyMode.SERVER || null === cloud.config)
+        return null;
+    let previewUrl;
+    try {
+        previewUrl = deps.sessions.resolve(sessionId).url;
+    }
+    catch {
+        previewUrl = undefined;
+    }
+    // The server hits the URL itself; with no URL (or a localhost one it can't reach) fall back to local.
+    if (previewUrl === undefined || 0 === previewUrl.length)
+        return null;
+    // The submit blocks while the hosted runner drives a real browser, so it gets the long budget — but a
+    // budget it must have: this is awaited inside the verify tool, and an unbounded wait here is an MCP
+    // call that never returns. A timeout is reported and then falls back to the local replay below.
+    const report = await submitServerVerification({ previewUrl, flows, source: SOURCE }, cloud.config, async (url, init) => {
+        try {
+            return await cloudFetch(url, init, CLOUD_VERIFY_TIMEOUT_MS);
+        }
+        catch (error) {
+            log('cloud-server-verify-failed', {
+                error: error instanceof Error ? error.message : String(error),
+            });
+            throw error;
+        }
+    });
+    if (null === report)
+        return null;
+    // The hosted runner said it couldn't actually verify (e.g. it's not enabled yet). Never surface that as
+    // a pass or a fail — fall back to the real local replay so the verdict reflects a browser that ran.
+    if (report.verdict === UNVERIFIED)
+        return null;
+    return toSuiteVerdict(report);
+}

package/dist/language/flows/suite/suite-flakes.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Accrue a suite run's outcomes into the flake ledger, and report what the ledger knows.
+ *
+ * This existed twice — once in `flow_verify`'s sequential branch and once, after #240, in its
+ * parallel branch. That duplication is not incidental: the parallel branch shipped WITHOUT it, so an
+ * agent verifying in parallel built no flake evidence at all and never saw the quarantine set, and
+ * nothing went red because the other copy was still correct. One function both branches call is what
+ * makes that miss impossible on one side only.
+ *
+ * It is also what makes the behaviour testable. The handler itself needs a live browser session, so
+ * both branches were only ever pinned by tests that RE-IMPLEMENTED this loop — which passed with the
+ * shipped code reverted (measured on #240: 4/4 green with the fix absent). Extracted, the real thing
+ * runs in a unit test.
+ *
+ * Best-effort on both halves, deliberately: a flake ledger is memory, not a gate. A full disk must
+ * never turn a working verification into an error.
+ */
+import { ReplayStatus } from '@reticlehq/core';
+import type { FileSystemPort } from '../../../memory/project/fs/fs-port.js';
+/** Just the shape this needs from a replay — so a test does not have to build a whole result. */
+interface FlakeOutcome {
+    readonly name: string;
+    readonly status: ReplayStatus;
+}
+/**
+ * Record every outcome, then ask which flows are intermittent.
+ *
+ * Anything that is not `OK` — `ERROR` or `DRIFT` — counts as a failure for the ledger. That is the
+ * rule both call sites already used, preserved rather than chosen here.
+ */
+export declare function recordSuiteFlakes(fs: FileSystemPort, reticleRoot: string, runs: readonly {
+    readonly replay: FlakeOutcome;
+}[]): Promise<readonly string[]>;
+export {};

package/dist/language/flows/suite/suite-flakes.js

@@ -0,0 +1,32 @@
+/**
+ * Accrue a suite run's outcomes into the flake ledger, and report what the ledger knows.
+ *
+ * This existed twice — once in `flow_verify`'s sequential branch and once, after #240, in its
+ * parallel branch. That duplication is not incidental: the parallel branch shipped WITHOUT it, so an
+ * agent verifying in parallel built no flake evidence at all and never saw the quarantine set, and
+ * nothing went red because the other copy was still correct. One function both branches call is what
+ * makes that miss impossible on one side only.
+ *
+ * It is also what makes the behaviour testable. The handler itself needs a live browser session, so
+ * both branches were only ever pinned by tests that RE-IMPLEMENTED this loop — which passed with the
+ * shipped code reverted (measured on #240: 4/4 green with the fix absent). Extracted, the real thing
+ * runs in a unit test.
+ *
+ * Best-effort on both halves, deliberately: a flake ledger is memory, not a gate. A full disk must
+ * never turn a working verification into an error.
+ */
+import { ReplayStatus } from '@reticlehq/core';
+import { FlakeStore } from '../stores/flake-store.js';
+/**
+ * Record every outcome, then ask which flows are intermittent.
+ *
+ * Anything that is not `OK` — `ERROR` or `DRIFT` — counts as a failure for the ledger. That is the
+ * rule both call sites already used, preserved rather than chosen here.
+ */
+export async function recordSuiteFlakes(fs, reticleRoot, runs) {
+    const flakes = new FlakeStore(fs, reticleRoot);
+    for (const { replay } of runs) {
+        await flakes.record(replay.name, ReplayStatus.OK === replay.status).catch(() => undefined);
+    }
+    return flakes.flakyFlows().catch(() => []);
+}

package/dist/language/flows/suite-selection.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Which flows a suite run replays, resolved against the store.
+ *
+ * Shared by the MCP tool and the `reticle verify` command so the two cannot disagree about what a
+ * selection means.
+ *
+ * Lives beside the flow store rather than under `suite/` on purpose: it needs `flowsForSession`, and
+ * from `suite/` that import made `suite` and `flows` need EACH OTHER -- a mutual pair, which the
+ * reach guard forbids growing because two directories that need each other cannot be read, moved or
+ * tested apart. Here it adds no edge at all: `flows` reaching itself is nothing, and `cli -> flows`
+ * already existed. The pure rule lives in core (`selectFlows`); this is the part that has to read
+ * the files, because a label lives in one and `list` returns only names.
+ */
+import { type ProjectId } from '@reticlehq/core';
+import type { ToolDeps } from '../../surface/tools/tool-kit.js';
+/**
+ * Resolve what a suite run should replay, and what it is holding back.
+ *
+ * Loads the candidate flows so selection can read their labels and status — `list` returns names,
+ * and a label lives in the file. The reads are small and the suite is about to replay these anyway.
+ *
+ * A flow that fails to load is kept as a candidate rather than dropped: refusing to run it here
+ * would turn a corrupt file into missing coverage nobody is told about, and replay reports the parse
+ * failure far better than a silent omission does.
+ */
+export declare function resolveSuiteSelection(deps: ToolDeps, projectId: ProjectId | undefined, args: Record<string, unknown>): Promise<{
+    run: string[];
+    quarantined: string[];
+    unmatched: string[];
+    /** Flows in a dependency cycle — none of them ran. */
+    cycles?: string[];
+    /** A flow whose prerequisite is not in this run, so it did not run either. */
+    unsatisfied?: {
+        flow: string;
+        needs: string;
+    }[];
+    /**
+     * Every route the PROJECT'S flows start on, including the ones this selection held back.
+     *
+     * The candidates are already loaded here, so the whole app's known surface costs nothing extra to
+     * report — and it is the only place that has it. By the time the suite has a verdict it knows only
+     * about the flows it ran, which is exactly the set that cannot reveal what was skipped.
+     */
+    knownRoutes: string[];
+}>;

package/dist/language/flows/suite-selection.js

@@ -0,0 +1,84 @@
+/**
+ * Which flows a suite run replays, resolved against the store.
+ *
+ * Shared by the MCP tool and the `reticle verify` command so the two cannot disagree about what a
+ * selection means.
+ *
+ * Lives beside the flow store rather than under `suite/` on purpose: it needs `flowsForSession`, and
+ * from `suite/` that import made `suite` and `flows` need EACH OTHER -- a mutual pair, which the
+ * reach guard forbids growing because two directories that need each other cannot be read, moved or
+ * tested apart. Here it adds no edge at all: `flows` reaching itself is nothing, and `cli -> flows`
+ * already existed. The pure rule lives in core (`selectFlows`); this is the part that has to read
+ * the files, because a label lives in one and `list` returns only names.
+ */
+import { FLOW_FILE_VERSION, orderFlows, selectFlows, } from '@reticlehq/core';
+import { flowsForSession } from './flow-store-for-session.js';
+/**
+ * Resolve what a suite run should replay, and what it is holding back.
+ *
+ * Loads the candidate flows so selection can read their labels and status — `list` returns names,
+ * and a label lives in the file. The reads are small and the suite is about to replay these anyway.
+ *
+ * A flow that fails to load is kept as a candidate rather than dropped: refusing to run it here
+ * would turn a corrupt file into missing coverage nobody is told about, and replay reports the parse
+ * failure far better than a silent omission does.
+ */
+export async function resolveSuiteSelection(deps, projectId, args) {
+    const store = flowsForSession(deps, projectId).flows;
+    const names = await store.list(projectId);
+    const asStrings = (value) => Array.isArray(value) ? value.filter((v) => 'string' === typeof v) : [];
+    const wantedNames = asStrings(args['names']);
+    const wantedLabels = asStrings(args['labels']);
+    const loaded = [];
+    for (const name of names) {
+        const file = await store.load(name, projectId);
+        /*
+         * The LISTED name wins over the file's own.
+         *
+         * The listing is what the store says exists and is what every other caller addresses a flow by;
+         * the `name` inside the file is data that can disagree with it — a hand-edited file, a copy, a
+         * rename that touched one and not the other. Selecting on the file's copy would then run a flow
+         * under a name nothing else recognises.
+         *
+         * An unreadable file keeps its place in the running set rather than being dropped: replay
+         * reports a parse failure far better than a silent omission, which would turn a corrupt file
+         * into missing coverage nobody is told about.
+         */
+        const base = file.ok
+            ? file.value
+            : { version: FLOW_FILE_VERSION, createdAt: 0, steps: [] };
+        loaded.push({ ...base, name });
+    }
+    const chosen = selectFlows(loaded, {
+        ...(0 === wantedNames.length ? {} : { names: wantedNames }),
+        ...(0 === wantedLabels.length ? {} : { labels: wantedLabels }),
+    });
+    /*
+     * A name the caller asked for that no file matches is still ATTEMPTED.
+     *
+     * Replay already answers a missing flow with the real reason, and that is a better answer than
+     * quietly running one fewer flow than was asked for. `unmatched` therefore reports labels, where
+     * a typo has no other way of surfacing -- ask for `@smoek` and, without this, a suite of zero
+     * flows reports a clean pass.
+     */
+    const missingNames = wantedNames.filter((name) => !names.includes(name));
+    /*
+     * Ordered AFTER selection, so a prerequisite filtered out by a label is reported rather than
+     * silently pulled back in. A flow whose `login` was excluded does not run: failing it here would
+     * produce a failure about the wrong thing, and quietly adding `login` back would run a flow the
+     * caller did not ask for.
+     */
+    const ordered = orderFlows(chosen.run);
+    return {
+        run: [...ordered.run.map((flow) => flow.name), ...missingNames],
+        quarantined: chosen.quarantined,
+        unmatched: chosen.unmatched.filter((entry) => !wantedNames.includes(entry)),
+        ...(0 === ordered.cycles.length ? {} : { cycles: ordered.cycles }),
+        ...(0 === ordered.unsatisfied.length ? {} : { unsatisfied: ordered.unsatisfied }),
+        knownRoutes: [
+            ...new Set(loaded
+                .map((flow) => flow.startPath)
+                .filter((path) => path !== undefined && '' !== path)),
+        ],
+    };
+}

package/dist/language/flows/verify-change-tools.d.ts

@@ -0,0 +1,2 @@
+import type { ToolDef } from '../../surface/tools/tool-kit.js';
+export declare const VERIFY_CHANGE_TOOLS: ToolDef[];

package/dist/language/flows/verify-change-tools.js

@@ -0,0 +1,244 @@
+import { z } from 'zod';
+import { sessionRoot, sessionProjectId } from '../../memory/project/session-root.js';
+import { verdictForSuite } from '../../judgement/outcome/verify-change-verdict.js';
+import { attributedFailures } from '../../judgement/outcome/attributed-failure.js';
+import { Verified } from '@reticlehq/core';
+import { ReticleTool } from '@reticlehq/core';
+import { asNumber, asRecord, asString } from '@reticlehq/core';
+import { workerCountSchema } from '../../surface/tools/args/numeric-bounds.js';
+import { loadNamedFlows, resolveChangedFiles } from '../../command/cli/cli-flow-commands.js';
+import { projectDirFor } from '../../memory/project/session-root.js';
+import { affectedSavedFlows } from './change/flow-sources.js';
+import { FLOW_TOOLS } from './flow-tools.js';
+import { findContradictions } from '@reticlehq/engine/disagreement/contradictions.js';
+import { parseControls } from '../../surface/tools/coverage-tools.js';
+import { ReticleCommand, SnapshotMode } from '@reticlehq/core';
+export const VERIFY_CHANGE_TOOLS = [
+    {
+        name: ReticleTool.VERIFY_CHANGE,
+        description: 'Did my change break anything? Give it the files you edited (or `since` for a git ref) and it works out which saved flows cover them, replays exactly those, and answers with one `verified` (yes|no|unknown) plus `because`. `unknown` when NO saved flow covers the change — that is the honest answer, never a green: nothing ran, so nothing was proved. Returns { verified, because, changedFiles, flowsRun, suite, unknownProvenance }.',
+        example: { files: ['src/App.tsx'] },
+        inputSchema: {
+            files: z
+                .array(z.string())
+                .optional()
+                .describe('Changed file paths, repo-relative (e.g. ["src/App.tsx"]).'),
+            since: z
+                .string()
+                .optional()
+                .describe('Git ref to diff against (e.g. "HEAD~1", "main"). Unioned with `files`.'),
+            parallel: workerCountSchema
+                .optional()
+                .describe('Replay this many affected flows at once (needs the browser pool).'),
+            sessionId: z
+                .string()
+                .optional()
+                .describe('OMIT THIS unless you mean a specific tab — Reticle resolves it.'),
+        },
+        outputSchema: {
+            verified: z
+                .string()
+                .describe('yes | no | unknown. `unknown` means the evidence could not decide — most often that no saved flow covers these files, which is NOT a pass.'),
+            because: z.string(),
+            changedFiles: z.array(z.string()),
+            flowsRun: z.array(z.string()),
+            suite: z.unknown().optional(),
+            // Session-EXEMPT: declare the one-shot human feedback ask or a validating profile strips it.
+            feedback_prompt: z.unknown().optional(),
+            unknownProvenance: z.array(z.string()),
+            contradictions: z
+                .array(z.unknown())
+                .optional()
+                .describe('Channels that disagreed DURING the replay. Any entry forces verified:"no" even when every flow passed — a suite that goes green over a failed write is the false green this exists to catch. OMITTED when clean; see `measured` when it could not be looked for.'),
+            untouched: z
+                .array(z.unknown())
+                .optional()
+                .describe('Controls on the page that the covering flows never drove. A green over a small untouched list is stronger evidence than the same green over a large one.'),
+            measured: z
+                .array(z.string())
+                .describe('What was actually looked for. An absent `contradictions` means "none found" ONLY if "contradictions" appears here — otherwise it was never measured.'),
+        },
+        handler: async (deps, args) => {
+            const files = Array.isArray(args['files'])
+                ? args['files'].filter((f) => 'string' === typeof f)
+                : [];
+            const since = asString(args['since']);
+            // The tree to diff is the SESSION's project, and it is neither of the two things this line
+            // used to say it was: `deps.reticleRoot` is the daemon's `.reticle` SUBDIRECTORY, and the
+            // daemon's cwd is wherever the MCP host started it — `/` or `$HOME` for a globally-registered
+            // server. Both answer about the wrong repository while reporting a clean "nothing changed",
+            // which reads as a pass. `projectDirFor` is the directory holding the resolved root.
+            const changed = await resolveChangedFiles(files, since, projectDirFor(deps, asString(args['sessionId'])));
+            const changedFiles = changed.files;
+            // Same root flow_save wrote to. A read that resolved differently would report "no flows
+            // covered this change" over flows that exist, which reads as a clean result rather than
+            // an error, so the disagreement would be invisible.
+            // Both halves of the address from one place. The root was already resolved from the session;
+            // the id used to come from the daemon's cwd, so they named different projects.
+            const sid = asString(args['sessionId']);
+            const flows = await loadNamedFlows(deps.fs, sessionRoot(deps, sid), sessionProjectId(deps, sid));
+            const { affected, unknownProvenance } = affectedSavedFlows(flows, changedFiles);
+            if (0 === changedFiles.length) {
+                return {
+                    verified: Verified.UNKNOWN,
+                    // A git failure and a clean tree both arrive here with no files, and they are opposite
+                    // answers: one means there was nothing to decide about, the other means the question was
+                    // never asked. `unknown` is right either way, but the REASON is what the caller acts on.
+                    because: changed.failed
+                        ? `could not read the diff for \`${String(since)}\`, so nothing was compared: ${changed.reason ?? 'git failed'}`
+                        : 'no changed files were given, so there was nothing to decide about',
+                    changedFiles,
+                    flowsRun: [],
+                    unknownProvenance,
+                    // Nothing was looked for, and the schema requires this field to say so. Omitting it made
+                    // the MCP layer reject the whole response, turning an honest UNKNOWN into a protocol error.
+                    measured: [],
+                };
+            }
+            // The guard: an uncovered change is UNKNOWN. Reporting `yes` here would mean "your change is
+            // fine" on the strength of having run nothing at all.
+            if (0 === affected.length) {
+                return {
+                    verified: Verified.UNKNOWN,
+                    /*
+                     * The way out named here has to be one the CALLER can take.
+                     *
+                     * This used to say "record one with reticle_record { action: start } then
+                     * reticle_flow_save". Neither is advertised on the default surface, and that surface has
+                     * no dispatch hatch — so the honest answer to "nothing covers this change" ended in two
+                     * calls that come back "Tool not found". Driving is reachable from every surface, and a
+                     * drive is captured as a flow automatically at teardown, so it is also the instruction
+                     * that makes the NEXT change to these files replay instead of drive.
+                     */
+                    because: `no saved flow covers ${1 === changedFiles.length ? 'this file' : 'these files'} — nothing ran, so nothing is proved. Drive it and prove it directly; the drive is saved as a flow, so the next change here replays instead`,
+                    changedFiles,
+                    flowsRun: [],
+                    unknownProvenance,
+                    // No flow ran, so nothing was measured — said explicitly rather than left undefined.
+                    measured: [],
+                };
+            }
+            const provenanceNote = unknownProvenance.length > 0
+                ? ` (${String(unknownProvenance.length)} of them re-run only because Reticle cannot tell which sources they cover)`
+                : '';
+            // Marked BEFORE the replay so the contradiction sweep afterwards reads exactly the window the
+            // flows produced, and never events from whatever the agent did before calling this.
+            const cursor = cursorBeforeReplay(deps, args);
+            const verify = FLOW_TOOLS.find((tool) => tool.name === ReticleTool.FLOW_VERIFY);
+            if (verify === undefined)
+                throw new Error('the whole-suite replay tool is not registered');
+            const suite = asRecord(await verify.handler(deps, {
+                names: affected,
+                ...(asNumber(args['parallel']) === undefined ? {} : { parallel: args['parallel'] }),
+                ...(asString(args['sessionId']) === undefined ? {} : { sessionId: args['sessionId'] }),
+            }));
+            const failed = suite.failed ?? 0;
+            const passed = suite.passed ?? 0;
+            // `unverifiable` is NOT a failure — the suite ran and proved nothing, which is the same fact
+            // this tool answers UNKNOWN for an uncovered change. Treating it as a red emitted a bug_found
+            // that nothing earned. See verify-change-verdict.
+            const verdict = verdictForSuite(String(suite.status), failed);
+            // A NO must be EARNED by a failing flow genuinely tied to the changed files. `affectedSavedFlows`
+            // re-runs any flow whose sources it cannot determine — over-running beats skipping — and those
+            // land in `unknownProvenance`. Judging the change on them produced a negative verdict whose own
+            // explanation admitted the evidence was not tied to the file. See attributed-failure.
+            const failingNames = Array.isArray(suite.failures)
+                ? suite.failures
+                    .map((f) => 'object' === typeof f && f !== null ? asString(asRecord(f)['flow']) : undefined)
+                    .filter((n) => n !== undefined)
+                : // No per-failure detail: the failure is somewhere in the set that ran, so ask the question
+                    // of all of them rather than guessing which.
+                    affected;
+            const attributed = attributedFailures(failingNames, unknownProvenance);
+            const earnedNo = verdict === Verified.NO && attributed.length > 0;
+            const reported = verdict === Verified.NO && !earnedNo ? Verified.UNKNOWN : verdict;
+            if (reported !== Verified.YES) {
+                return {
+                    verified: reported,
+                    because: earnedNo
+                        ? `${String(failed)} of ${String(suite.total ?? affected.length)} covering flows failed, including ${attributed.join(', ')}, which cover the changed files${provenanceNote}`
+                        : verdict === Verified.NO
+                            ? `flows failed, but Reticle cannot tell which sources any of them cover (${failingNames.join(', ')}) — so this says nothing about the files you changed. Re-record them so their sources are stamped, or read the replay yourself`
+                            : `the covering flows ran but proved nothing (${String(suite.status)}) — they assert no observable consequence, so a green from them would not have meant your change is safe${provenanceNote}`,
+                    changedFiles,
+                    flowsRun: affected,
+                    suite,
+                    unknownProvenance,
+                    measured: ['flows'],
+                };
+            }
+            // The suite went green. That is exactly when the remaining two channels are worth reading:
+            // a replay that passes while a write fails is the false green this whole product is about.
+            const extra = await inspectAfterReplay(deps, args, cursor);
+            if (extra.contradictions.length > 0) {
+                const kinds = extra.contradictions.map((c) => c.kind).join(', ');
+                return {
+                    verified: Verified.NO,
+                    because: `every covering flow passed, but channels disagreed during the replay (${kinds}) — a green suite over a failed write is the false green worth looking at${provenanceNote}`,
+                    changedFiles,
+                    flowsRun: affected,
+                    suite,
+                    unknownProvenance,
+                    contradictions: extra.contradictions,
+                    ...(extra.untouched === undefined ? {} : { untouched: extra.untouched }),
+                    measured: extra.measured,
+                };
+            }
+            return {
+                verified: Verified.YES,
+                because: `all ${String(passed)} flows covering these files passed${provenanceNote}${extra.untouched === undefined ? '' : `, with ${String(extra.untouched.length)} controls left undriven`}`,
+                changedFiles,
+                flowsRun: affected,
+                suite,
+                unknownProvenance,
+                ...(extra.untouched === undefined ? {} : { untouched: extra.untouched }),
+                measured: extra.measured,
+            };
+        },
+    },
+];
+/** The event cursor to sweep from, or 0 when there is no readable session (nothing to sweep). */
+function cursorBeforeReplay(deps, args) {
+    try {
+        return deps.sessions.resolve(asString(args['sessionId'])).elapsed();
+    }
+    catch {
+        return 0;
+    }
+}
+/**
+ * Read the two channels a suite verdict cannot see: did anything DISAGREE during the replay, and
+ * what did the flows never touch.
+ *
+ * Both are skipped when the flows ran in parallel leased contexts, because the events and driven
+ * refs then belong to those leases rather than to the session read here. Reporting "no
+ * contradictions" from the wrong session would be a false green produced by the false-green
+ * detector, so `measured` states what was actually looked for and the caller is never left to infer
+ * it from an absent field.
+ */
+async function inspectAfterReplay(deps, args, cursor) {
+    if (asNumber(args['parallel']) !== undefined) {
+        return { contradictions: [], measured: ['flows'] };
+    }
+    try {
+        const session = deps.sessions.resolve(asString(args['sessionId']));
+        const contradictions = findContradictions(session.eventsSince(cursor), {
+            currentDocumentId: session.currentDocumentId,
+            currentEditEpoch: session.currentEditEpoch,
+            appOrigin: session.url,
+            // The replay is the action, and the cursor is where it started.
+            actionSince: cursor,
+        });
+        const snapshot = await session.command(ReticleCommand.SNAPSHOT, {
+            mode: SnapshotMode.INTERACTIVE,
+        });
+        const tree = snapshot.ok ? (asString(asRecord(snapshot.result)['tree']) ?? '') : '';
+        const acted = session.actedRefs();
+        const untouched = parseControls(tree).filter((c) => !acted.has(c.ref));
+        return { contradictions, untouched, measured: ['flows', 'contradictions', 'coverage'] };
+    }
+    catch {
+        // A session that went away after the replay is not evidence of cleanliness.
+        return { contradictions: [], measured: ['flows'] };
+    }
+}

package/dist/machine/clock.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The clock this daemon injects, declared once.
+ *
+ * Rule 7 says never call `Date.now()` inside pure logic — pass it in. Nothing said WHERE the type
+ * that gets passed in lives, so it was declared four times: in `flows.ts`, in `intent-store.ts`, in
+ * `intent-shard-store.ts`, and as a differently-shaped `() => number` inside `session.ts`. Three of
+ * the four were the same interface spelled twice as `now(): number` and once as `now: () => number`.
+ *
+ * The cost was not the duplication, it was what the duplication made somebody do: `project-store.ts`
+ * needed a clock type, found the nearest declaration in `flows.ts`, and imported it — so `memory/`
+ * now depended on `language/`, which already depended on `memory/` ten files over. One type-only
+ * import of a two-line interface, reaching across a 975-line module, closed a cycle between two
+ * directories that have no business knowing about each other.
+ *
+ * So it lives here, for the reason `platform.ts` gives next door: Node-side only, ambient, and it
+ * never crosses the wire, so it is deliberately NOT in `@reticlehq/core`. `machine/` imports nothing
+ * and is therefore the one place in this package that cannot be half of a cycle.
+ *
+ * `session.ts` keeps its own `() => number`: a bare function and an object with a `now` are
+ * different contracts, and merging them would change every call site to prove a point about tidiness.
+ */
+export interface Clock {
+    now(): number;
+}

package/dist/machine/clock.js

@@ -0,0 +1 @@
+export {};

package/dist/machine/repo-root.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Where this repository starts on disk.
+ *
+ * Many checks in this package read files that live outside it -- the workflow file, the docs, the
+ * skill, the benchmark scenarios -- and to do that they need the top of the repository.
+ *
+ * Asks git, because a fixed count of `..` segments is a fact about this package's depth, not about
+ * the repository: when the package moved, every count was off by one and each check quietly read a
+ * directory that does not exist. This file sits at a fixed place INSIDE the package, so the way its
+ * neighbours reach it never changes however far the package itself moves.
+ *
+ * Example: a check that wants the workflow file writes
+ * `join(REPO_ROOT, '.github', 'workflows', 'ci.yml')`, and keeps working wherever this package ends
+ * up.
+ */
+export declare const REPO_ROOT: string;

package/dist/machine/repo-root.js

@@ -0,0 +1,20 @@
+import { execFileSync } from 'node:child_process';
+/**
+ * Where this repository starts on disk.
+ *
+ * Many checks in this package read files that live outside it -- the workflow file, the docs, the
+ * skill, the benchmark scenarios -- and to do that they need the top of the repository.
+ *
+ * Asks git, because a fixed count of `..` segments is a fact about this package's depth, not about
+ * the repository: when the package moved, every count was off by one and each check quietly read a
+ * directory that does not exist. This file sits at a fixed place INSIDE the package, so the way its
+ * neighbours reach it never changes however far the package itself moves.
+ *
+ * Example: a check that wants the workflow file writes
+ * `join(REPO_ROOT, '.github', 'workflows', 'ci.yml')`, and keeps working wherever this package ends
+ * up.
+ */
+export const REPO_ROOT = execFileSync('git', ['rev-parse', '--show-toplevel'], {
+    cwd: import.meta.dirname,
+    encoding: 'utf8',
+}).trim();

package/dist/memory/cloud/account-state.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Is this machine signed in to a Reticle workspace?
+ *
+ * Asked by the HUD, and there are two sources that must not be reimplemented per caller: the session
+ * file `reticle login` writes to `~/.reticle/session.json`, and `RETICLE_API_KEY` for an agent that
+ * was handed a key instead. Everything that gates on login — the defect sync button, the prompt to sign
+ * in — resolves through here.
+ *
+ * Node-only by design: it reads the filesystem and the environment, so it lives in the server and
+ * only the SHAPE (`AccountState`) is in core, where the contract belongs.
+ */
+import { type AccountState } from '@reticlehq/core';
+/**
+ * Read the account state for this machine.
+ *
+ * The env key WINS over the session file: an agent handed a key is authenticating as that key,
+ * whatever a human left on disk, and reporting the human's org there would be a lie about who is
+ * acting.
+ */
+export declare function readAccountState(home: string, env: NodeJS.ProcessEnv): AccountState;