@reticlehq/server 2.14.0 → 3.2.0

package/dist/memory/project/project-store.js

@@ -0,0 +1,244 @@
+import { PROJECT_FILE_VERSION, PROJECT_ROUTE_CAP, PROJECT_RUN_CAP, ProjectFileSchema, ProjectReadError, } from '@reticlehq/core';
+import { reticleDirPaths } from './dir/reticle-dir.js';
+import { withFileLock } from './file-lock.js';
+const JSON_INDENT = 2;
+const EMPTY_PROJECT = { version: PROJECT_FILE_VERSION, runs: [] };
+/**
+ * The `version` a file declares, if it declares one this release does not use.
+ *
+ * `undefined` covers both "no version at all" and "the version we expect", which are the two cases
+ * that mean the file is damaged rather than foreign.
+ */
+function versionOf(parsed) {
+    if ('object' !== typeof parsed || null === parsed)
+        return undefined;
+    const version = parsed.version;
+    if ('number' !== typeof version || version === PROJECT_FILE_VERSION)
+        return undefined;
+    return version;
+}
+/**
+ * Cross-run outcome memory persisted at .reticle/project.json. Models FlowStore:
+ * injected FileSystemPort + Clock, byte-stable serialize, never-throws read. The clock is the
+ * single `at`-stamp site so handlers pass an un-stamped record and no Date.now leaks into logic.
+ */
+export class ProjectStore {
+    #fs;
+    #root;
+    #clock;
+    constructor(fs, root, clock) {
+        this.#fs = fs;
+        this.#root = root;
+        this.#clock = clock;
+    }
+    /**
+     * Byte-stable serializer: fixed field order (rebuilt literals, never insertion order), 2-space
+     * indent + trailing newline. `runs` stays chronological (append order = the data, never sorted);
+     * `learned` arrays ARE sorted for diff-stability. Two semantically-equal files → identical bytes.
+     */
+    #serialize(file) {
+        const envelope = {
+            version: PROJECT_FILE_VERSION,
+            ...(file.learned !== undefined ? { learned: serializeLearned(file.learned) } : {}),
+            runs: file.runs.map(serializeRun),
+        };
+        return `${JSON.stringify(envelope, null, JSON_INDENT)}\n`;
+    }
+    /** Never throws. Missing → MISSING. Bad JSON / failed schema → MALFORMED. Mirrors readContract. */
+    async read() {
+        const path = reticleDirPaths(this.#root).project;
+        if (!(await this.#fs.exists(path)))
+            return { ok: false, reason: ProjectReadError.MISSING };
+        let text;
+        try {
+            text = await this.#fs.readFile(path);
+        }
+        catch (error) {
+            return {
+                ok: false,
+                reason: this.#fs.isNotFound(error) ? ProjectReadError.MISSING : ProjectReadError.MALFORMED,
+            };
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(text);
+        }
+        catch {
+            return { ok: false, reason: ProjectReadError.MALFORMED };
+        }
+        const result = ProjectFileSchema.safeParse(parsed);
+        if (result.success)
+            return { ok: true, file: result.data };
+        // Which KIND of unreadable. A file whose version we do not recognise is intact and belongs to
+        // another release; anything else is damage. They are repaired differently, so they are named
+        // differently -- one message for both would send somebody hunting a typo in a healthy file.
+        return {
+            ok: false,
+            reason: versionOf(parsed) === undefined
+                ? ProjectReadError.MALFORMED
+                : ProjectReadError.WRONG_VERSION,
+        };
+    }
+    /**
+     * Append a run, stamping `at` from the injected clock (the one clock site). A MISSING **or
+     * MALFORMED** existing file self-heals to a fresh empty file so corrupt history never blocks
+     * recording — unlike the read path, which surfaces MALFORMED honestly. Truncates per policy
+     * (last PER_NAME of any one name, then cap to TOTAL overall) and writes byte-stably.
+     */
+    async recordRun(record) {
+        const path = reticleDirPaths(this.#root).project;
+        // Serialized per file: a parallel flow_verify records N runs concurrently, and an unlocked
+        // read-append-write drops every run but the last writer's (each read the same base list).
+        await withFileLock(path, async () => {
+            const existing = await this.read();
+            // Refuse rather than repair. Starting fresh here would overwrite a history this release cannot
+            // read but the one that wrote it can, and the user would lose it without anything failing.
+            if (!existing.ok && ProjectReadError.WRONG_VERSION === existing.reason) {
+                throw new Error(`refusing to record: ${reticleDirPaths(this.#root).project} was written by a different ` +
+                    'version of Reticle and this one cannot read it. Nothing has been changed. Upgrade ' +
+                    'Reticle, or move that file aside if you do not need its history.');
+            }
+            const base = existing.ok ? existing.file : EMPTY_PROJECT;
+            const stamped = { ...record, at: this.#clock.now() };
+            const runs = truncate([...base.runs, stamped]);
+            const next = { ...base, runs };
+            await this.#fs.mkdir(reticleDirPaths(this.#root).root);
+            await this.#fs.writeFile(path, this.#serialize(next));
+        });
+    }
+    /**
+     * Add discovered routes to the learned app map. Empty input is a no-op so "nothing observed"
+     * does not materialize as `learned.routes: []`; non-empty updates are serialized per file so
+     * concurrent browser sessions accumulate rather than overwriting one another.
+     */
+    async recordRoutes(routes) {
+        const additions = routes.filter((route) => route.length > 0);
+        if (0 === additions.length)
+            return;
+        const path = reticleDirPaths(this.#root).project;
+        await withFileLock(path, async () => {
+            const existing = await this.read();
+            // Refuse rather than repair. Starting fresh here would overwrite a history this release cannot
+            // read but the one that wrote it can, and the user would lose it without anything failing.
+            if (!existing.ok && ProjectReadError.WRONG_VERSION === existing.reason) {
+                throw new Error(`refusing to record: ${reticleDirPaths(this.#root).project} was written by a different ` +
+                    'version of Reticle and this one cannot read it. Nothing has been changed. Upgrade ' +
+                    'Reticle, or move that file aside if you do not need its history.');
+            }
+            const base = existing.ok ? existing.file : EMPTY_PROJECT;
+            const current = base.learned?.routes ?? [];
+            const merged = [...new Set([...current, ...additions])].slice(0, PROJECT_ROUTE_CAP);
+            if (merged.length === current.length &&
+                merged.every((route, index) => route === current[index]))
+                return;
+            const learned = { ...base.learned, routes: merged };
+            const next = { ...base, learned };
+            await this.#fs.mkdir(reticleDirPaths(this.#root).root);
+            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();
+            // Refuse rather than repair. Starting fresh here would overwrite a history this release cannot
+            // read but the one that wrote it can, and the user would lose it without anything failing.
+            if (!existing.ok && ProjectReadError.WRONG_VERSION === existing.reason) {
+                throw new Error(`refusing to record: ${reticleDirPaths(this.#root).project} was written by a different ` +
+                    'version of Reticle and this one cannot read it. Nothing has been changed. Upgrade ' +
+                    'Reticle, or move that file aside if you do not need its history.');
+            }
+            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();
+        if (!read.ok)
+            return undefined;
+        for (let i = read.file.runs.length - 1; i >= 0; i -= 1) {
+            const run = read.file.runs[i];
+            if (run !== undefined && run.name === name)
+                return run;
+        }
+        return undefined;
+    }
+}
+/** Field-ordered rebuild of one run record so serialization is byte-stable. */
+function serializeRun(run) {
+    return {
+        kind: run.kind,
+        name: run.name,
+        status: run.status,
+        at: run.at,
+        ...(run.summary !== undefined ? { summary: run.summary } : {}),
+        ...(run.evidence !== undefined ? { evidence: run.evidence } : {}),
+        ...(run.durationMs !== undefined ? { durationMs: run.durationMs } : {}),
+    };
+}
+/** Sorted, field-ordered rebuild of the learned map for diff-stability. */
+function serializeLearned(learned) {
+    return {
+        ...(learned.flows !== undefined ? { flows: [...learned.flows].sort() } : {}),
+        ...(learned.routes !== undefined ? { routes: [...learned.routes].sort() } : {}),
+    };
+}
+/**
+ * Cap project memory while GUARANTEEING each flow keeps its last-known-good. Pass 1 reserves the
+ * most-recent run of every distinct name (never evicted by the TOTAL cap), so a fresh session can always
+ * answer "did my last run of this flow pass?" locally — the durable, free regression memory the solo
+ * loop needs. Pass 2 fills the remaining budget with additional recent runs (PER_NAME per name, TOTAL
+ * overall). Chronological order (oldest→newest) is preserved.
+ */
+function truncate(runs) {
+    const perName = new Map();
+    const kept = new Set();
+    // Pass 1 (newest→oldest): reserve each name's latest run. Kept regardless of the TOTAL cap.
+    const seen = new Set();
+    for (let i = runs.length - 1; i >= 0; i -= 1) {
+        const run = runs[i];
+        if (run === undefined || seen.has(run.name))
+            continue;
+        seen.add(run.name);
+        kept.add(i);
+        perName.set(run.name, 1);
+    }
+    // Pass 2 (newest→oldest): fill the rest with extra recent runs, respecting PER_NAME and TOTAL.
+    for (let i = runs.length - 1; i >= 0 && kept.size < PROJECT_RUN_CAP.TOTAL; i -= 1) {
+        const run = runs[i];
+        if (run === undefined || kept.has(i))
+            continue;
+        const count = perName.get(run.name) ?? 0;
+        if (count >= PROJECT_RUN_CAP.PER_NAME)
+            continue;
+        perName.set(run.name, count + 1);
+        kept.add(i);
+    }
+    return runs.filter((_, i) => kept.has(i));
+}

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

@@ -0,0 +1,8 @@
+import type { ToolDef } from '../../surface/tools/tool-kit.js';
+/**
+ * The cross-run memory tools. `reticle_project` reads .reticle/project.json (optionally scoped to a
+ * name, with a diff-vs-last summary); `reticle_run_record` explicitly records an outcome (the manual
+ * companion to the auto-record on `reticle_flow_replay`). Both keep the agent's "did this behave
+ * like last run?" question answerable without re-deriving it from raw observations.
+ */
+export declare const PROJECT_TOOLS: ToolDef[];

package/dist/memory/project/project-tools.js

@@ -0,0 +1,160 @@
+import { z } from 'zod';
+import { sessionRoot } from './session-root.js';
+import { projectForRoot } from './project-for-root.js';
+import { ProjectReadError, RunStatus } from '@reticlehq/core';
+import { ReticleTool } from '@reticlehq/core';
+import { countSchema } from '../../surface/tools/args/numeric-bounds.js';
+import { sessionIdShape } from '../../surface/tools/tool-kit.js';
+import { asNumber, asString } from '@reticlehq/core';
+import { cloudFetch, fetchProjectRegressionFromCloud, resolveCloudConfig, } from '../cloud/cloud-sync.js';
+import { RunStore } from '../../judgement/runs/artifact/run-store.js';
+import { diffRuns as diffVerificationRuns, } from '../../judgement/runs/artifact/run-diff.js';
+const REGRESSION_STATUSES = new Set([
+    RunStatus.FAIL,
+    RunStatus.DRIFT,
+    RunStatus.ERROR,
+]);
+function diffRuns(previous, current) {
+    const consoleErrorsDelta = numericDelta(previous.evidence?.consoleErrors, current.evidence?.consoleErrors);
+    const driftStepsDelta = numericDelta(previous.evidence?.driftSteps, current.evidence?.driftSteps);
+    return {
+        statusChanged: previous.status !== current.status,
+        previousStatus: previous.status,
+        currentStatus: current.status,
+        // Regressed = current is a non-pass outcome that the previous run was not.
+        regressed: REGRESSION_STATUSES.has(current.status) && !REGRESSION_STATUSES.has(previous.status),
+        ...(consoleErrorsDelta !== undefined ? { consoleErrorsDelta } : {}),
+        ...(driftStepsDelta !== undefined ? { driftStepsDelta } : {}),
+    };
+}
+function numericDelta(before, after) {
+    if (before === undefined && after === undefined)
+        return undefined;
+    return (after ?? 0) - (before ?? 0);
+}
+/**
+ * Pull the team's server-side regression memory when logged in. This is what keeps a context-lost or
+ * brand-new agent (whose local project.json may be empty) oriented: the same reticle_project call folds in
+ * "what's broken vs before" from the cloud. Absent creds / unreachable → undefined (agent stays local).
+ */
+async function cloudRegression(deps, sessionId) {
+    const config = resolveCloudConfig(process.env);
+    if (null === config)
+        return undefined;
+    let projectId;
+    try {
+        projectId = deps.sessions.resolve(sessionId).projectId;
+    }
+    catch {
+        projectId = undefined;
+    }
+    const report = await fetchProjectRegressionFromCloud(config, projectId, cloudFetch);
+    return report ?? undefined;
+}
+/** Runs returned when the caller does not ask for a specific count. */
+const DEFAULT_RUN_LIMIT = 25;
+/** The two most-recent runs for `name`, oldest-first, or undefined if there are fewer than two. */
+function lastTwoFor(runs, name) {
+    const matching = runs.filter((r) => r.name === name);
+    const n = matching.length;
+    if (n < 2)
+        return undefined;
+    const previous = matching[n - 2];
+    const current = matching[n - 1];
+    if (previous === undefined || current === undefined)
+        return undefined;
+    return [previous, current];
+}
+/**
+ * The per-flow diff between the two most-recent verification ARTIFACTS (.reticle/runs), or undefined when
+ * fewer than two exist. Never throws — a missing/unreadable artifact must not break reading run history.
+ */
+async function lastTwoRunArtifacts(deps, 
+/** The session's root — the same address `persistAndSyncVerificationRun` wrote the pair to. */
+root) {
+    try {
+        const pair = await new RunStore(deps.fs, root).latestTwo();
+        return pair === undefined ? undefined : diffVerificationRuns(pair[0], pair[1]);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The cross-run memory tools. `reticle_project` reads .reticle/project.json (optionally scoped to a
+ * name, with a diff-vs-last summary); `reticle_run_record` explicitly records an outcome (the manual
+ * companion to the auto-record on `reticle_flow_replay`). Both keep the agent's "did this behave
+ * like last run?" question answerable without re-deriving it from raw observations.
+ */
+export const PROJECT_TOOLS = [
+    {
+        name: ReticleTool.PROJECT,
+        description: 'Read cross-run history from .reticle/project.json — the memory of how past runs behaved. With { name } it also returns the last run for that flow plus a diff-vs-last summary (status change, regressed flag, consoleErrors/driftSteps deltas) so you can answer "did it behave like last time?". `diff` is the lightweight status/console/drift delta vs the previous run of that NAME; `runDiff` is the per-flow duration/status delta between the two most-recent full verification artifacts ("step 3: 412ms -> 987ms (+140%), +2 requests"). When logged in to Reticle, also returns `cloud`: the team\'s server-side regression report (broken/changed flows vs before) — the durable memory a fresh or context-lost agent can rely on even when local history is empty. Returns { runs, learned?, lastRun?, diff?, runDiff?, cloud? } or { error, reason, cloud? }.',
+        inputSchema: {
+            name: z.string().optional().describe('Filter runs by this name. Omit to return all runs.'),
+            limit: countSchema
+                .optional()
+                .describe('Most-recent N runs to return. Defaults to 25 — the full history is unbounded and grows with every run (measured at ~20KB / ~5,000 tokens on a modest project), which is a large slice of an agent context for data it mostly does not read. `totalRuns` always reports the true count, so a cap is never silent.'),
+            ...sessionIdShape,
+        },
+        outputSchema: {
+            runs: z.array(z.unknown()),
+            totalRuns: z
+                .number()
+                .optional()
+                .describe('How many runs exist in total. Compare against runs.length to see if it was capped.'),
+            diff: z.unknown().optional(),
+            runDiff: z.unknown().optional(),
+            cloud: z.unknown().optional(),
+        },
+        handler: async (deps, args) => {
+            const cloud = await cloudRegression(deps, asString(args['sessionId']));
+            const withCloud = (obj) => cloud === undefined ? obj : { ...obj, cloud };
+            const project = projectForRoot(deps, sessionRoot(deps, asString(args['sessionId'])));
+            const read = await project.read();
+            if (!read.ok) {
+                return withCloud({
+                    error: read.reason === ProjectReadError.MISSING
+                        ? 'no .reticle/project.json yet — run a flow (reticle_flow_replay) or reticle_run_record first'
+                        : '.reticle/project.json is malformed — it will self-heal on the next recorded run',
+                    reason: read.reason,
+                });
+            }
+            const name = asString(args['name']);
+            // The most recent N, in the order they happened. The history is append-only and unbounded —
+            // measured at ~20KB (~5,000 tokens) across 176 runs on this repo — and an agent asking "how
+            // did this behave before" wants the recent past, not every run ever recorded. `totalRuns`
+            // travels with it so the cap is never silent, per the repo's no-silent-caps rule.
+            //
+            // Order is left alone deliberately. Reversing to newest-first was tried and reverted: it read
+            // better but broke an existing contract for no reason the bound required, and a caller relying
+            // on chronological order would have been silently handed the reverse.
+            const cap = asNumber(args['limit']) ?? DEFAULT_RUN_LIMIT;
+            const recent = (runs) => runs.slice(-cap);
+            if (name === undefined) {
+                return withCloud({
+                    runs: recent(read.file.runs),
+                    totalRuns: read.file.runs.length,
+                    learned: read.file.learned,
+                });
+            }
+            const lastRun = await project.lastRun(name);
+            const pair = lastTwoFor(read.file.runs, name);
+            //: the RICH run diff (per-flow duration deltas past a noise floor, status changes, new/removed
+            // flows, verdict change) over the last two verification ARTIFACTS. That lives alongside — not
+            // instead of — the lightweight RunRecord diff above: `diff` answers "did this named run behave like
+            // last time?" from project.json, while `runDiff` answers "what changed between the last two full
+            // verification runs?" from .reticle/runs. Best-effort: no artifacts simply means no runDiff.
+            const runDiff = await lastTwoRunArtifacts(deps, sessionRoot(deps, asString(args['sessionId'])));
+            const forName = read.file.runs.filter((r) => r.name === name);
+            return withCloud({
+                runs: recent(forName),
+                totalRuns: forName.length,
+                learned: read.file.learned,
+                lastRun,
+                ...(pair !== undefined ? { diff: diffRuns(pair[0], pair[1]) } : {}),
+                ...(runDiff === undefined ? {} : { runDiff }),
+            });
+        },
+    },
+];

package/dist/memory/project/reticle-deps.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The `@reticlehq/*` packages a project actually declares.
+ *
+ * Shared by `reticle update` (which syncs them) and the version-skew remedy (which names them).
+ *
+ * It is a fact about the PROJECT -- what this app has declared -- rather than a step in updating
+ * anything, so it lives with the rest of what we know about a project. It used to sit under
+ * `update/`, where it was the only thing the version code needed from there, and the two directories
+ * ended up needing each other for one twenty-line function.
+ *
+ * It is not in the scaffolder, deliberately: the daemon has to be able to read a project's
+ * package.json without pulling the installer in behind it.
+ */
+/** The Reticle packages this project declares, from either dependency section. */
+export declare function reticleDepsOf(pkgJson: unknown): string[];

package/dist/memory/project/reticle-deps.js

@@ -0,0 +1,33 @@
+/**
+ * The `@reticlehq/*` packages a project actually declares.
+ *
+ * Shared by `reticle update` (which syncs them) and the version-skew remedy (which names them).
+ *
+ * It is a fact about the PROJECT -- what this app has declared -- rather than a step in updating
+ * anything, so it lives with the rest of what we know about a project. It used to sit under
+ * `update/`, where it was the only thing the version code needed from there, and the two directories
+ * ended up needing each other for one twenty-line function.
+ *
+ * It is not in the scaffolder, deliberately: the daemon has to be able to read a project's
+ * package.json without pulling the installer in behind it.
+ */
+/** Everything we publish is scoped here. */
+const RETICLE_SCOPE = '@reticlehq/';
+/**
+ * The CLI. Never an app dependency: it carries the Node MCP server and `ws`, and putting it in a
+ * browser app's tree is what the retired `@reticlehq/core` umbrella got wrong.
+ */
+const SERVER_PACKAGE = '@reticlehq/server';
+function namesIn(section) {
+    if ('object' !== typeof section || null === section)
+        return [];
+    return Object.keys(section);
+}
+/** The Reticle packages this project declares, from either dependency section. */
+export function reticleDepsOf(pkgJson) {
+    if ('object' !== typeof pkgJson || null === pkgJson)
+        return [];
+    const manifest = pkgJson;
+    const declared = [...namesIn(manifest['dependencies']), ...namesIn(manifest['devDependencies'])];
+    return [...new Set(declared)].filter((name) => name.startsWith(RETICLE_SCOPE) && name !== SERVER_PACKAGE);
+}

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

@@ -0,0 +1,52 @@
+import type { ProjectId } from '@reticlehq/core';
+import type { ToolDeps } from '../../surface/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 — EXCEPT when the
+ * caller named a session that resolves to nothing, which is the one case where the fallback is a
+ * wrong answer rather than a cautious one. See `sessionProjectId`.
+ */
+export declare function sessionRoot(deps: ToolDeps, sessionId: string | undefined): string;
+/**
+ * The same answer for a caller that already holds the projectId rather than a sessionId.
+ *
+ * The suite paths resolve the project ONCE and thread it down -- the run artifact, the cloud link,
+ * the flake ledger and the flows all belong to that one project -- so asking them to go back to the
+ * session manager for an id they already have is how a caller ends up taking the root from one
+ * place and the id from another. `sessionRoot` is now this function plus a lookup, so the two
+ * cannot disagree about what a resolved root is.
+ */
+export declare function rootForProjectId(deps: ToolDeps, projectId: ProjectId | undefined): string;
+/**
+ * The PROJECT directory -- one level above `.reticle` -- for a caller that runs a tool in a tree
+ * rather than writing a file into one. `git diff` is the case: it was being run in the daemon's
+ * `.reticle` subdirectory, which answers about the wrong repository (or, from a globally-registered
+ * daemon at `/` or `$HOME`, about none) while reporting a clean "nothing changed".
+ */
+export declare function projectDirFor(deps: ToolDeps, sessionId: string | undefined): string;
+/**
+ * The connected session's projectId, or undefined when there is no session to ask.
+ *
+ * `sessions.resolve` throws for three reasons, and they do not all mean the same thing. Nothing
+ * connected, and several connected with none named, both mean "we cannot tell which project this
+ * call is about" — on a call that named no session that is not a reason to fail the caller's tool,
+ * which may not need a session at all, so it degrades to the daemon's own root.
+ *
+ * A sessionId that names NO session is the third, and it is a different fact. An agent that passes
+ * an id has named the project too, so swallowing that throw does not degrade to a cautious answer:
+ * it silently retargets the call at whichever checkout the daemon was started in (#994).
+ * The same fallback can expose another project's ledger on reads as well as misdirect writes.
+ *
+ * So the ambiguous case still declines (the resolver has its own `AMBIGUOUS` branch for the same
+ * reason) and the mis-addressed case refuses. There is no root that is right for a dead id, so
+ * there is no answer either.
+ */
+export declare function sessionProjectId(deps: ToolDeps, sessionId: string | undefined): ProjectId | undefined;

package/dist/memory/project/session-root.js

@@ -0,0 +1,100 @@
+import { dirname } from 'node:path';
+/**
+ * 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 — EXCEPT when the
+ * caller named a session that resolves to nothing, which is the one case where the fallback is a
+ * wrong answer rather than a cautious one. See `sessionProjectId`.
+ */
+export function sessionRoot(deps, sessionId) {
+    // Skip the LOOKUP, never the refusal.
+    //
+    // `artifactRootFor?.(…)` short-circuits its own argument, so an unwired caller used to skip
+    // resolution entirely and hand a named-but-dead session the daemon's own directory without ever
+    // checking the id -- which is how one app's intents, flows and runs land in another app's
+    // checkout. Resolving as an ARGUMENT fixes that, because arguments are evaluated first.
+    //
+    // But `resolve(undefined)` is not free: it builds the ranked no-session diagnosis and records
+    // which branch it took. With no resolver wired AND no id named there is nothing to refuse and
+    // nothing its answer could change, so that one case skips the lookup and costs what it always
+    // did. Every embedder of this engine, and every older construction of ToolDeps, is on it.
+    const nothingToRefuse = deps.artifactRootFor === undefined && sessionId === undefined;
+    return rootForProjectId(deps, nothingToRefuse ? undefined : sessionProjectId(deps, sessionId));
+}
+/**
+ * The same answer for a caller that already holds the projectId rather than a sessionId.
+ *
+ * The suite paths resolve the project ONCE and thread it down -- the run artifact, the cloud link,
+ * the flake ledger and the flows all belong to that one project -- so asking them to go back to the
+ * session manager for an id they already have is how a caller ends up taking the root from one
+ * place and the id from another. `sessionRoot` is now this function plus a lookup, so the two
+ * cannot disagree about what a resolved root is.
+ */
+export function rootForProjectId(deps, projectId) {
+    return deps.artifactRootFor?.(projectId).root ?? deps.reticleRoot;
+}
+/**
+ * The PROJECT directory -- one level above `.reticle` -- for a caller that runs a tool in a tree
+ * rather than writing a file into one. `git diff` is the case: it was being run in the daemon's
+ * `.reticle` subdirectory, which answers about the wrong repository (or, from a globally-registered
+ * daemon at `/` or `$HOME`, about none) while reporting a clean "nothing changed".
+ */
+export function projectDirFor(deps, sessionId) {
+    return dirname(sessionRoot(deps, sessionId));
+}
+/**
+ * The connected session's projectId, or undefined when there is no session to ask.
+ *
+ * `sessions.resolve` throws for three reasons, and they do not all mean the same thing. Nothing
+ * connected, and several connected with none named, both mean "we cannot tell which project this
+ * call is about" — on a call that named no session that is not a reason to fail the caller's tool,
+ * which may not need a session at all, so it degrades to the daemon's own root.
+ *
+ * A sessionId that names NO session is the third, and it is a different fact. An agent that passes
+ * an id has named the project too, so swallowing that throw does not degrade to a cautious answer:
+ * it silently retargets the call at whichever checkout the daemon was started in (#994).
+ * The same fallback can expose another project's ledger on reads as well as misdirect writes.
+ *
+ * So the ambiguous case still declines (the resolver has its own `AMBIGUOUS` branch for the same
+ * reason) and the mis-addressed case refuses. There is no root that is right for a dead id, so
+ * there is no answer either.
+ */
+/*
+ * Exported alongside `sessionRoot`, and that is the point rather than a convenience. A caller that
+ * takes the ROOT from the session and the PROJECT ID from somewhere else has resolved half an
+ * address, which is the defect the comment above predicted and `loadNamedFlows` then shipped: it
+ * read the id from `readProjectId(process.cwd())` while its root came from here. Both halves come
+ * from this file so they cannot disagree again.
+ */
+export function sessionProjectId(deps, sessionId) {
+    try {
+        return deps.sessions.resolve(sessionId).projectId;
+    }
+    catch (cause) {
+        if (sessionId === undefined)
+            return undefined;
+        throw unresolvedTargetRefusal(sessionId, cause);
+    }
+}
+/**
+ * Why a named-but-dead session gets no directory, and what to do instead.
+ *
+ * The manager's own message is carried verbatim at the end because it is the actionable half — it
+ * names the sessions that ARE connected, with their ids and urls, or says that none are. Rebuilding
+ * a worse version of that here is how the two no-session paths drifted apart the last time.
+ */
+function unresolvedTargetRefusal(sessionId, cause) {
+    const because = cause instanceof Error ? cause.message : String(cause);
+    return new Error(`sessionId '${sessionId}' names no session, so there is no project to resolve this call's ` +
+        '.reticle directory against, and nothing was read or written. Reticle refuses rather than ' +
+        "falling back to the daemon's own directory, which belongs to whatever project the daemon " +
+        "was started in — that is how one app's intents, flows and runs land in another app's " +
+        `checkout. Omit sessionId to use the connected app, or name one that is live. ${because}`);
+}

package/dist/memory/recall/memory-tools.d.ts

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