@reticlehq/server 2.10.0 → 2.12.0

package/dist/project/artifact-root.js

@@ -0,0 +1,112 @@
+import { join } from 'node:path';
+import { ReticleDir, projectCandidates, } from '@reticlehq/core';
+/**
+ * Which `.reticle/` a session's artifacts belong in.
+ *
+ * Everything Reticle persists — flows, the capability contract, baselines, capsules, the cross-run
+ * project memory — used to resolve against the DAEMON's own `process.cwd()`. That is a statement
+ * about where the daemon was launched and it was being read as a statement about which project is
+ * being verified. Those are not the same thing and are usually not even the same tree: a user-scoped
+ * MCP registration is the common case, and the editor that spawns it starts it wherever it likes.
+ *
+ * Three field shapes, one defect: `cwd=/` gave `ENOENT: mkdir '/.reticle'`; a daemon started in
+ * project A wrote project B's flow into A's checkout and reported success without naming the path;
+ * and `verify_change` could only answer "unknown" because no flow could be persisted for it to match
+ * against.
+ *
+ * ## Two sources, one rule
+ *
+ * Candidates arrive from config discovery (which walks out from the daemon's own directory) and from
+ * the user-level project registry (which `init` writes, and which reaches checkouts discovery cannot
+ * see). This function takes the merged list and does not know or care which source an entry came
+ * from — a privileged source would be a second rule, and two rules for one question is how the
+ * answers start disagreeing.
+ *
+ * ## Why matching on projectId, and not a new wire field
+ *
+ * HELLO already stamps `projectId`, and `.reticle.json` already declares the same id sitting next to
+ * the code it configures. The join is therefore available today, for every SDK already in the field.
+ * Adding a `root` to HELLO would move the wire contract, strand every older SDK on the fallback, and
+ * buy nothing this does not already give.
+ *
+ * ## Why it can decline to answer
+ *
+ * Every non-matching branch returns the daemon root and SAYS which branch it was. A wrong root is
+ * worse than no root — it writes a caller's evidence into a tree they never drove — so the ambiguous
+ * case refuses rather than picks, exactly as `discoverProjectConfigs` refuses to pick one config.
+ * The reason travels with the answer so callers can report the surprise instead of hiding it.
+ */
+/** Why the root below is the root. Travels with the answer so a caller can say what happened. */
+export const ArtifactRootReason = {
+    /** Exactly one discovered config declares this session's project. The good case. */
+    MATCHED_PROJECT: 'matched-project',
+    /** The session declared no projectId — a pre-2.0 SDK. Nothing to match on. */
+    NO_PROJECT_ID: 'no-project-id',
+    /** The search ran and nothing it found declares this project. */
+    NO_MATCH: 'no-match',
+    /** Two or more checkouts declare this project. Refused rather than guessed. */
+    AMBIGUOUS: 'ambiguous',
+};
+/**
+ * Resolve the artifact root for one session.
+ *
+ * Pure: no IO, no cwd, no clock. The filesystem walk belongs to `discoverProjectConfigs` and is
+ * passed in, which is what makes every branch below testable without a fixture tree.
+ */
+export function resolveArtifactRoot(query) {
+    const { projectId, candidates, daemonRoot } = query;
+    if (projectId === undefined || 0 === projectId.length) {
+        return { root: daemonRoot, reason: ArtifactRootReason.NO_PROJECT_ID };
+    }
+    const matches = dedupeByDirectory(candidates.filter((c) => c.projectId === projectId));
+    if (0 === matches.length) {
+        return { root: daemonRoot, reason: ArtifactRootReason.NO_MATCH };
+    }
+    if (matches.length > 1) {
+        return {
+            root: daemonRoot,
+            reason: ArtifactRootReason.AMBIGUOUS,
+            candidates: matches.map((config) => config.directory),
+        };
+    }
+    const [only] = matches;
+    // `matches.length === 1` above, so this is defined — but the codebase forbids `!`, and a default
+    // that can never be taken is cheaper than the alternative spelling.
+    const directory = only?.directory ?? '';
+    if (0 === directory.length) {
+        return { root: daemonRoot, reason: ArtifactRootReason.NO_MATCH };
+    }
+    return { root: join(directory, ReticleDir.ROOT), reason: ArtifactRootReason.MATCHED_PROJECT };
+}
+/**
+ * One entry per directory.
+ *
+ * Discovery and the registry routinely name the SAME checkout — the registry remembers what `init`
+ * wrote, and discovery finds that same file whenever the daemon happens to be in the tree. Counting
+ * it twice would read as two competing checkouts and make the resolver refuse, which is the one
+ * outcome worse than either source alone.
+ */
+function dedupeByDirectory(matches) {
+    const seen = new Set();
+    const out = [];
+    for (const candidate of matches) {
+        if (seen.has(candidate.directory))
+            continue;
+        seen.add(candidate.directory);
+        out.push(candidate);
+    }
+    return out;
+}
+/**
+ * Everything this machine knows about where projects live, from both sources.
+ *
+ * Discovery first, deliberately: it read a `.reticle.json` that exists RIGHT NOW, while the registry
+ * is a cache of something `init` saw once. Order only decides which duplicate survives dedupe, and
+ * the one confirmed a moment ago is the better survivor.
+ */
+export function projectCandidatesFrom(discovery, registry) {
+    const discovered = discovery.found.flatMap((config) => config.projectId === undefined || 0 === config.projectId.length
+        ? []
+        : [{ projectId: config.projectId, directory: config.directory }]);
+    return [...discovered, ...projectCandidates(registry)];
+}

package/dist/project/fs-port.d.ts

@@ -36,7 +36,10 @@ export interface FileSystemPort {
     /** Modification time in epoch ms — for recency-based retention pruning. Rejects if absent. */
     stat(path: string): Promise<{
         mtimeMs: number;
+        size: number;
     }>;
+    /** Resolve symlinks to their real path — for upload trust-boundary checks. Rejects if absent. */
+    realpath(path: string): Promise<string>;
     /** ENOENT classifier — narrows unknown without `any`, so callers can distinguish missing-file. */
     isNotFound(error: unknown): boolean;
 }

package/dist/project/fs-port.js

@@ -1,4 +1,4 @@
-import { access, appendFile, mkdir, open, readdir, readFile, rename, rm, stat, writeFile, } from 'node:fs/promises';
+import { access, appendFile, mkdir, open, readdir, readFile, realpath, rename, rm, stat, writeFile, } from 'node:fs/promises';
 /** Production adapter — the single import site of node:fs/promises in the server. */
 export function createNodeFileSystem() {
     return {
@@ -46,8 +46,9 @@ export function createNodeFileSystem() {
         },
         stat: async (path) => {
             const s = await stat(path);
-            return { mtimeMs: s.mtimeMs };
+            return { mtimeMs: s.mtimeMs, size: s.size };
         },
+        realpath: (path) => realpath(path),
         isNotFound: (error) => 'ENOENT' === error?.code,
     };
 }

package/dist/project/memory-fs.d.ts

@@ -0,0 +1,9 @@
+import type { FileSystemPort } from './fs-port.js';
+export interface MemoryFs {
+    fs: FileSystemPort;
+    /** Every file written, keyed by normalised absolute path. */
+    written: Map<string, string>;
+    /** Every directory created. */
+    dirs: Set<string>;
+}
+export declare function createMemoryFs(): MemoryFs;

package/dist/project/memory-fs.js

@@ -0,0 +1,93 @@
+/**
+ * An in-memory `FileSystemPort`, and the map it wrote into.
+ *
+ * Three specs had hand-rolled their own copy of this before it was extracted, each one slightly
+ * different and each one a fresh chance to reintroduce the same fixture bug: the code under test
+ * joins paths with the PLATFORM separator, the fixtures are written with POSIX ones, and a spec that
+ * forgets to normalise passes on macOS and fails on Windows. Normalising at the port — once, here —
+ * is what stops that recurring.
+ *
+ * Exposing `written` is the other reason this exists. A store's return value says what it believes it
+ * did; the map says where the bytes actually went, which is the only way to test a defect about
+ * writing to the wrong directory.
+ */
+/** POSIX form, so a `\`-joined path and a `/`-joined one are the same key. */
+const norm = (path) => path.split('\\').join('/');
+export function createMemoryFs() {
+    const written = new Map();
+    const dirs = new Set();
+    const notFound = () => {
+        const err = new Error('ENOENT: no such file or directory');
+        err.code = 'ENOENT';
+        return err;
+    };
+    const fs = {
+        readFile(path) {
+            const value = written.get(norm(path));
+            return value === undefined ? Promise.reject(notFound()) : Promise.resolve(value);
+        },
+        writeFile(path, data) {
+            written.set(norm(path), data);
+            return Promise.resolve();
+        },
+        appendFile(path, data) {
+            written.set(norm(path), (written.get(norm(path)) ?? '') + data);
+            return Promise.resolve();
+        },
+        readFileBytes(path) {
+            const value = written.get(norm(path));
+            return value === undefined
+                ? Promise.reject(notFound())
+                : Promise.resolve(new TextEncoder().encode(value));
+        },
+        writeFileBytes(path, data) {
+            written.set(norm(path), new TextDecoder().decode(data));
+            return Promise.resolve();
+        },
+        mkdir(path) {
+            dirs.add(norm(path));
+            return Promise.resolve();
+        },
+        exists(path) {
+            const key = norm(path);
+            return Promise.resolve(written.has(key) || dirs.has(key));
+        },
+        readdir(path) {
+            const prefix = `${norm(path)}/`;
+            const names = new Set();
+            for (const key of written.keys()) {
+                if (key.startsWith(prefix)) {
+                    const rest = key.slice(prefix.length).split('/')[0];
+                    if (rest !== undefined && rest.length > 0)
+                        names.add(rest);
+                }
+            }
+            return Promise.resolve([...names]);
+        },
+        rename(from, to) {
+            const value = written.get(norm(from));
+            if (value === undefined)
+                return Promise.reject(notFound());
+            written.set(norm(to), value);
+            written.delete(norm(from));
+            return Promise.resolve();
+        },
+        rm(path) {
+            written.delete(norm(path));
+            dirs.delete(norm(path));
+            return Promise.resolve();
+        },
+        stat(path) {
+            return written.has(norm(path))
+                ? Promise.resolve({ mtimeMs: 0, size: 0 })
+                : Promise.reject(notFound());
+        },
+        realpath(path) {
+            return written.has(norm(path)) ? Promise.resolve(norm(path)) : Promise.reject(notFound());
+        },
+        isNotFound(error) {
+            return 'ENOENT' === error?.code;
+        },
+    };
+    return { fs, written, dirs };
+}

package/dist/project/project-store.d.ts

@@ -32,6 +32,23 @@ export declare class ProjectStore {
      * concurrent browser sessions accumulate rather than overwriting one another.
      */
     recordRoutes(routes: readonly string[]): Promise<void>;
+    /**
+     * The best observability this project has reached, and the raiser of that bar.
+     *
+     * Read returns undefined on a first run or an unreadable file, which is the honest "no best to
+     * fall from" — never a zero, which would make every first run look like a recovery.
+     */
+    bestObservability(): Promise<{
+        percent: number;
+    } | undefined>;
+    /**
+     * Raise the bar, if this run cleared it. Lowering is deliberately impossible.
+     *
+     * A best that could fall would let a weakened run quietly redefine what good looks like, which is
+     * precisely the gaming the figure exists to resist. Serialized per file so two sessions racing
+     * cannot lose the higher of the two.
+     */
+    raiseObservability(percent: number): Promise<void>;
     /** The most-recent run for `name` (undefined on missing/malformed/none). Powers diff-vs-last. */
     lastRun(name: string): Promise<RunRecord | undefined>;
 }

package/dist/project/project-store.js

@@ -101,6 +101,39 @@ export class ProjectStore {
             await this.#fs.writeFile(path, this.#serialize(next));
         });
     }
+    /**
+     * The best observability this project has reached, and the raiser of that bar.
+     *
+     * Read returns undefined on a first run or an unreadable file, which is the honest "no best to
+     * fall from" — never a zero, which would make every first run look like a recovery.
+     */
+    async bestObservability() {
+        const existing = await this.read();
+        return existing.ok ? existing.file.learned?.bestObservability : undefined;
+    }
+    /**
+     * Raise the bar, if this run cleared it. Lowering is deliberately impossible.
+     *
+     * A best that could fall would let a weakened run quietly redefine what good looks like, which is
+     * precisely the gaming the figure exists to resist. Serialized per file so two sessions racing
+     * cannot lose the higher of the two.
+     */
+    async raiseObservability(percent) {
+        const path = reticleDirPaths(this.#root).project;
+        await withFileLock(path, async () => {
+            const existing = await this.read();
+            const base = existing.ok ? existing.file : EMPTY_PROJECT;
+            const current = base.learned?.bestObservability?.percent;
+            if (current !== undefined && percent <= current)
+                return;
+            const learned = {
+                ...base.learned,
+                bestObservability: { percent, at: this.#clock.now() },
+            };
+            await this.#fs.mkdir(reticleDirPaths(this.#root).root);
+            await this.#fs.writeFile(path, this.#serialize({ ...base, learned }));
+        });
+    }
     /** The most-recent run for `name` (undefined on missing/malformed/none). Powers diff-vs-last. */
     async lastRun(name) {
         const read = await this.read();

package/dist/project/project-tools.js

@@ -1,9 +1,9 @@
 import { z } from 'zod';
-import { ProjectReadError, RunKind, RunStatus } from '@reticlehq/core';
+import { ProjectReadError, RunStatus } from '@reticlehq/core';
 import { ReticleTool } from '../tools/tool-names.js';
 import { sessionIdShape } from '../tools/tool-kit.js';
 import { asNumber, asString } from '../tools/tools-helpers.js';
-import { fetchProjectRegressionFromCloud, resolveCloudConfig } from '../cloud/cloud-sync.js';
+import { cloudFetch, fetchProjectRegressionFromCloud, resolveCloudConfig, } from '../cloud/cloud-sync.js';
 import { RunStore } from '../runs/run-store.js';
 import { diffRuns as diffVerificationRuns, } from '../runs/run-diff.js';
 const REGRESSION_STATUSES = new Set([
@@ -45,7 +45,7 @@ async function cloudRegression(deps, sessionId) {
     catch {
         projectId = undefined;
     }
-    const report = await fetchProjectRegressionFromCloud(config, projectId, (url, init) => fetch(url, init));
+    const report = await fetchProjectRegressionFromCloud(config, projectId, cloudFetch);
     return report ?? undefined;
 }
 /** The two most-recent runs for `name`, oldest-first, or undefined if there are fewer than two. */
@@ -152,33 +152,4 @@ export const PROJECT_TOOLS = [
             });
         },
     },
-    {
-        name: ReticleTool.RUN_RECORD,
-        description: 'Explicitly record a run outcome into .reticle/project.json (the manual companion to the auto-record on reticle_flow_replay). Use it to log the result of an assertion sequence or a manual journey so future runs can diff against it. Returns { recorded:true, name, status }.',
-        inputSchema: {
-            name: z.string().describe('Run name for grouping in reticle_project history.'),
-            status: z.nativeEnum(RunStatus).describe('Outcome: pass | fail | drift | error'),
-            kind: z.nativeEnum(RunKind).optional(),
-            summary: z.string().optional().describe('One-line human summary of what this run covered.'),
-            ...sessionIdShape,
-        },
-        outputSchema: {
-            recorded: z.boolean(),
-            runName: z.string(),
-            status: z.string(),
-        },
-        handler: async (deps, args) => {
-            const name = asString(args['name']) ?? '';
-            const status = args['status'];
-            const kindArg = args['kind'];
-            const summary = asString(args['summary']);
-            await deps.project.recordRun({
-                kind: 'string' === typeof kindArg ? kindArg : RunKind.MANUAL,
-                name,
-                status,
-                ...(summary !== undefined ? { summary } : {}),
-            });
-            return { recorded: true, runName: name, status };
-        },
-    },
 ];

package/dist/project/remember-project.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Record where this project lives, so a daemon started somewhere else can still find it.
+ *
+ * Called at the end of `init`, which is the one moment both halves are known for certain: the
+ * directory being initialised, and the projectId that was just written into its `.reticle.json`.
+ *
+ * Deliberately runs on EVERY init, not only the first. Most init runs report "already wired", and a
+ * re-run in a re-cloned or moved checkout is exactly when the remembered path has gone stale — so
+ * the run that would have been a no-op is the one that repairs the entry.
+ *
+ * Every failure is swallowed. This is a cache that makes a later resolution better; a read-only home
+ * directory, a full disk or a hand-mangled file must not turn a successful init into a failed one.
+ * The user's project is wired either way, and `init`'s report is the first thing a new user reads.
+ */
+/** The sync filesystem seam `init` already carries. Narrowed to what this needs. */
+export interface RegistryIo {
+    readFile(path: string): string | null;
+    writeFile(path: string, content: string): void;
+    exists(path: string): boolean;
+    homeDir(): string;
+}
+/** The `projectId` a `.reticle.json` declares, or undefined when it declares none we can use. */
+export declare function projectIdOf(configSource: string | null): string | undefined;
+export declare function rememberProjectOnDisk(io: RegistryIo, projectId: string, directory: string, now: number): boolean;

package/dist/project/remember-project.js

@@ -0,0 +1,40 @@
+import { join } from 'node:path';
+import { PROJECT_REGISTRY_FILE, ReticleDir, emptyProjectRegistry, parseProjectRegistry, rememberProject, } from '@reticlehq/core';
+/** The `projectId` a `.reticle.json` declares, or undefined when it declares none we can use. */
+export function projectIdOf(configSource) {
+    if (null === configSource || 0 === configSource.length)
+        return undefined;
+    try {
+        const parsed = JSON.parse(configSource);
+        if ('object' !== typeof parsed || null === parsed || Array.isArray(parsed))
+            return undefined;
+        const id = parsed['projectId'];
+        return 'string' === typeof id && id.length > 0 ? id : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function rememberProjectOnDisk(io, projectId, directory, now) {
+    if (0 === projectId.length || 0 === directory.length)
+        return false;
+    try {
+        const path = join(io.homeDir(), ReticleDir.ROOT, PROJECT_REGISTRY_FILE);
+        const existing = io.exists(path) ? io.readFile(path) : null;
+        const registry = null === existing ? emptyProjectRegistry() : parseProjectRegistry(safeJson(existing));
+        const next = rememberProject(registry, projectId, directory, now);
+        io.writeFile(path, `${JSON.stringify(next, null, 2)}\n`);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function safeJson(raw) {
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/project/reticle-dir.d.ts

@@ -15,6 +15,8 @@ export interface ReticleDirPaths {
     project: string;
     /**.../.reticle/impact.json (what Reticle has done for this user, local only) */
     impact: string;
+    /**.../.reticle/intent.json (what changes were supposed to make true — git-checked) */
+    intent: string;
     /**.../.reticle/visual (PNG baselines + diffs) */
     visual: string;
     /**.../.reticle/runs (verification-run artifacts) */

package/dist/project/reticle-dir.js

@@ -8,6 +8,7 @@ export function reticleDirPaths(root) {
         baselines: join(root, ReticleDir.BASELINES_SUBDIR),
         project: join(root, ReticleDir.PROJECT_FILE),
         impact: join(root, ReticleDir.IMPACT_FILE),
+        intent: join(root, ReticleDir.INTENT_FILE),
         visual: join(root, ReticleDir.VISUAL_SUBDIR),
         runs: join(root, ReticleDir.RUNS_SUBDIR),
         sessions: join(root, ReticleDir.SESSIONS_SUBDIR),

package/dist/project/session-root.d.ts

@@ -0,0 +1,15 @@
+import type { ToolDeps } from '../tools/tool-kit.js';
+/**
+ * The `.reticle` directory a tool call's artifacts belong in.
+ *
+ * Every call site that reads or writes a project artifact goes through here, and that is the whole
+ * point of the function existing rather than each site asking `deps.artifactRootFor` itself. The
+ * write half and the read half MUST agree: a `flow_save` that resolves to the project while
+ * `verify_change` still reads the daemon's own directory would be a worse defect than the one being
+ * fixed — the flow would save successfully and then be invisible to the tool that exists to replay
+ * it, which reads as "no flows covered this change" rather than as an error.
+ *
+ * Falls back to `deps.reticleRoot` whenever resolution cannot name a project, which is exactly the
+ * behaviour every call site had before the resolver existed.
+ */
+export declare function sessionRoot(deps: ToolDeps, sessionId: string | undefined): string;

package/dist/project/session-root.js

@@ -0,0 +1,31 @@
+/**
+ * The `.reticle` directory a tool call's artifacts belong in.
+ *
+ * Every call site that reads or writes a project artifact goes through here, and that is the whole
+ * point of the function existing rather than each site asking `deps.artifactRootFor` itself. The
+ * write half and the read half MUST agree: a `flow_save` that resolves to the project while
+ * `verify_change` still reads the daemon's own directory would be a worse defect than the one being
+ * fixed — the flow would save successfully and then be invisible to the tool that exists to replay
+ * it, which reads as "no flows covered this change" rather than as an error.
+ *
+ * Falls back to `deps.reticleRoot` whenever resolution cannot name a project, which is exactly the
+ * behaviour every call site had before the resolver existed.
+ */
+export function sessionRoot(deps, sessionId) {
+    return deps.artifactRootFor?.(sessionProjectIdOf(deps, sessionId)).root ?? deps.reticleRoot;
+}
+/**
+ * The connected session's projectId, or undefined when there is no session to ask.
+ *
+ * `sessions.resolve` throws when nothing is connected, when the id names no session, and when
+ * several are connected and none was named. All three mean the same thing here — we cannot tell
+ * which project this call is about — and none of them is a reason to fail the caller's tool.
+ */
+function sessionProjectIdOf(deps, sessionId) {
+    try {
+        return deps.sessions.resolve(sessionId).projectId;
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/runs/context-tools.d.ts

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

package/dist/runs/context-tools.js

@@ -0,0 +1,89 @@
+import { z } from 'zod';
+import {} from '@reticlehq/core';
+import { runContextFor } from './run-context.js';
+import { openSessionIntents } from '../intent/open-intents.js';
+import { ReticleTool } from '../tools/tool-names.js';
+import { sessionIdShape } from '../tools/tool-kit.js';
+import { asString } from '../tools/tools-helpers.js';
+/**
+ * What this run has established, asked for by the one party that knows when it is needed.
+ *
+ * Reticle holds the trajectory: the journal, the verdicts, the intent ledger. The agent holds a copy
+ * in its context window, and that copy is the one that disappears — at a compaction, at the end of a
+ * turn, at the handover to a sub-agent. Reticle's does not disappear at the same moment. So this is
+ * not a competing memory; it is the ground truth compaction destroyed, handed back on request.
+ *
+ * ## Why it is PULLED
+ *
+ * The same content was once pushed onto every session-bound tool response. It cost +136% on a
+ * verdict and was cut, because most of the time the agent still had the context and we were paying
+ * on every call to duplicate what it knew. Nobody but the agent can tell when that stops being true.
+ * So the agent asks, once, at the moment it knows its own memory is gone, and pays once.
+ *
+ * ## Why it is on the EXTENDED surface rather than the default
+ *
+ * The default surface is a hard COUNT — editors budget tools across every connected MCP server, so a
+ * slot taken here is taken from a tool that has already earned it, and nothing on that list has been
+ * demoted for this. The claim behind this tool is unmeasured, which is the same test `reticle_intent`
+ * and the `reticle_capabilities` demotion were held to, and it fails that test today.
+ *
+ * The reachability argument is also stronger here than for most of the cold tail. The caller is,
+ * by construction, an agent that has just lost its context and is re-reading the tool list it was
+ * handed this turn — so `reticle_tools` (advertised on every surface) is exactly the call it is
+ * already going to make, and this tool is one `reticle_run` hop behind it. A tool that is only useful
+ * after a discovery step, to a caller who is already performing a discovery step, is the cheapest
+ * possible thing to leave off the hot list. It moves to the default surface when a measurement says
+ * the pull happens often enough to be worth a permanent slot, and not before.
+ */
+/** What the run has established, and where each part of it came from. */
+const CONTEXT_OUTPUT_SCHEMA = {
+    step: z
+        .number()
+        .describe('How many actions this run has dispatched. Counted off the journal, not a counter of its own.'),
+    established: z
+        .array(z.unknown())
+        .describe('What Reticle OBSERVED, folded and capped, each `{ key, fact, source?, doc?, epoch? }`. `key` is the subject, so re-observing it supersedes rather than appends. Anything seen under a replaced document or a pre-edit epoch is already gone from this list.'),
+    proven: z
+        .array(z.unknown())
+        .describe('Claims a verdict already settled, each `{ claim, verified, source?, doc?, epoch? }`. Read this before re-driving something: re-proving it is slow, and assuming it is a false green.'),
+    remaining: z
+        .array(z.string())
+        .describe('The intents from .reticle/intent.json that no verdict has discharged. Derived from the ledger, never a guess at what you meant to do next.'),
+};
+/** The ledger and the live page state this run is folded out of. `[]`/undefined when nothing is connected. */
+async function evidenceFor(deps, sessionId) {
+    try {
+        const session = deps.sessions.resolve(sessionId);
+        return {
+            actions: await session.readJournalActions(),
+            events: await session.queryEvents({}),
+            currentDocumentId: session.currentDocumentId,
+            currentEditEpoch: session.currentEditEpoch,
+        };
+    }
+    catch {
+        // `resolve` throws when nothing is connected, when the id names no session, and when several are
+        // connected and none was named. All three mean the same thing here: there is no run to report,
+        // and an empty context is the honest answer rather than a reason to fail the call.
+        return {
+            actions: [],
+            events: [],
+            currentDocumentId: undefined,
+            currentEditEpoch: undefined,
+        };
+    }
+}
+export const CONTEXT_TOOLS = [
+    {
+        name: ReticleTool.CONTEXT,
+        description: 'What THIS run has already established, so you do not rediscover it. Call it when your own copy is gone: right after a compaction, at the top of a fresh sub-agent, or at the start of a turn you did not begin. Returns `established` (what Reticle OBSERVED, with the source file:line where one was reported), `proven` (claims a verdict already settled, so you neither re-prove them nor assume them) and `remaining` (the intents from .reticle/intent.json that nothing has discharged). It is a FOLD over the journal, never a second store, so it cannot disagree with the ledger. Bounded and superseding rather than accumulating, and anything observed under a replaced document or before your last source edit is already dropped rather than presented as current. Only what Reticle observed goes in: it never reports what you intended or believed.',
+        example: {},
+        inputSchema: { ...sessionIdShape },
+        outputSchema: CONTEXT_OUTPUT_SCHEMA,
+        handler: async (deps, args) => {
+            const sessionId = asString(args['sessionId']);
+            const evidence = await evidenceFor(deps, sessionId);
+            return runContextFor({ ...evidence, intents: await openSessionIntents(deps, sessionId) });
+        },
+    },
+];

package/dist/runs/run-context.d.ts

@@ -0,0 +1,40 @@
+import { type EstablishedFact, type Intent, type JournalAction, type ProvenClaim, type ReticleEvent, type RunContext } from '@reticlehq/core';
+/**
+ * The SUBJECT a journal action was about: the ref it spent, else the target it resolved from.
+ *
+ * Exported so the feature-use instrument files a re-fetch under the same key this fold establishes
+ * it under. A second copy of this rule there would be a second definition of "the same subject".
+ */
+export declare function subjectOf(action: JournalAction): string | undefined;
+/**
+ * Fold the journal into candidate facts, newest last.
+ *
+ * Only the last `RUN_ESTABLISHED_CAP` actions are read: anything older cannot survive the fold, so
+ * parsing it would be work done to throw away. An action with no observed settle outcome states
+ * nothing and is skipped — "we drove it and cannot say what happened" is not an established fact,
+ * and writing it down as one is how a memory starts lying.
+ */
+export declare function establishedFromJournal(actions: readonly JournalAction[], events: readonly ReticleEvent[]): EstablishedFact[];
+/**
+ * What a verdict already settled, newest last.
+ *
+ * Both verdict tools write here. `reticle_act_and_wait` closes its attribution window with one;
+ * `reticle_assert` drives nothing, so it appends its record WITHOUT opening a window — same effect
+ * shape, so this fold reads one kind of verdict rather than two.
+ */
+export declare function provenFromJournal(actions: readonly JournalAction[], events: readonly ReticleEvent[]): ProvenClaim[];
+/**
+ * The context for one run.
+ *
+ * `step` is the journal's action count rather than a counter of its own, for the reason at the top
+ * of this file: a second counter is a second thing that can disagree with the ledger. The document
+ * and epoch are the session's own, so the staleness rule here is the same one every other verdict in
+ * this codebase is scoped by.
+ */
+export declare function runContextFor(input: {
+    actions: readonly JournalAction[];
+    events: readonly ReticleEvent[];
+    intents: readonly Intent[];
+    currentDocumentId: string | undefined;
+    currentEditEpoch: number | undefined;
+}): RunContext;