@reticlehq/server 3.4.0 → 3.6.0

package/dist/memory/project/artifact-root-resolver.js

@@ -7,12 +7,21 @@
  *
  * It lives here rather than in the daemon bootstrap because it is a subject, not wiring — and
  * because the bootstrap is at its line cap, which is the cohesion signal that rule doing its job.
+ *
+ * ## Why `artifactRootResolver` takes a `deps`
+ *
+ * Both of its IO answers come from the REAL disk and the REAL `process.cwd()`: which projects this
+ * machine knows, and whether the daemon's own directory declares one. That left the file untestable
+ * at the level where its defect actually lives — the `unmatchedRoot` specs next door hand a
+ * `daemonProjectId` straight in, so a mistake in READING it would leave every one of them green
+ * while the worktree bug reproduced unchanged. The defaults are the production answers; the seam is
+ * what lets a test say "these are the projects on this machine" without one.
  */
-import { existsSync, readFileSync } from 'node:fs';
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { homedir } from 'node:os';
 import { PROJECT_REGISTRY_FILE, emptyProjectRegistry, parseProjectRegistry, } from '@reticlehq/core/artifacts';
-import { ReticleDir } from '@reticlehq/core';
+import { DevServerEntrySchema, ReticleDir, ReticleEnv, devServerRegistryPort, } from '@reticlehq/core';
 import { discoverProjectConfigs, hasProjectConfig, } from '../../command/cli/config/config-discovery.js';
 import { log } from '../../log.js';
 import { ArtifactRootReason, projectCandidatesFrom, resolveArtifactRoot, unmatchedRoot, } from './artifact-root.js';
@@ -34,32 +43,127 @@ function daemonSitsInAProject(daemonRoot) {
         return false;
     }
 }
-export function artifactRootResolver(daemonRoot) {
-    const daemonIsProject = daemonSitsInAProject(daemonRoot);
-    return (projectId, origin) => {
-        let registry = emptyProjectRegistry();
-        try {
-            const path = join(homedir(), ReticleDir.ROOT, PROJECT_REGISTRY_FILE);
-            registry = existsSync(path)
-                ? parseProjectRegistry(JSON.parse(readFileSync(path, 'utf8')))
-                : registry;
-        }
-        catch {
-            // A cache that cannot be read is an empty cache, never an error: the daemon still resolves
-            // through discovery, and falls back to its own root exactly as it did before this existed.
-        }
-        let discovery = { found: [], searched: [] };
-        try {
-            discovery = discoverProjectConfigs(process.cwd());
+/**
+ * The project a candidate list says lives at the daemon's own directory.
+ *
+ * Not the same question as `daemonSitsInAProject`: that one asks whether the tree invited Reticle in
+ * at all (either mark counts, including a bare `.reticle/` from a version that predates the config
+ * file), and this one asks WHICH project it is. The difference is the whole of #1244 — a daemon in
+ * repo A serving an app from a git worktree B belongs to A and is being asked about B.
+ *
+ * Takes the candidates rather than gathering them, so the answer is a function of one list and a test
+ * can supply it. Read from that same list the resolver already builds, so there is one answer to
+ * "where does this project live" rather than a second `.reticle.json` parser here. A daemon whose
+ * root was passed explicitly (`--root`, or an embedder's own `reticleRoot`) is not in that list and
+ * answers undefined, which is the safe direction: it cannot prove the named project is its own, so it
+ * declines the daemon root and the session goes to the unmatched bucket instead.
+ */
+function daemonOwnProjectId(daemonRoot, candidates) {
+    const directory = dirname(daemonRoot);
+    return candidates.find((candidate) => candidate.directory === directory)?.projectId;
+}
+/**
+ * Every project this machine knows the directory of: discovered `.reticle.json` files first, then
+ * the user-level registry, then the dev servers the build plugin announced. Read on each call, since
+ * `init` can run in another terminal while the daemon is up.
+ *
+ * Exported because sync must cover exactly the projects runs are written into. It kept its own list
+ * without the announced dev servers, so a project known only through its running dev server had its
+ * runs written to its `.reticle/runs/` and never sent, with nothing reporting a problem.
+ */
+export function knownProjectCandidates() {
+    let registry = emptyProjectRegistry();
+    try {
+        const path = join(homedir(), ReticleDir.ROOT, PROJECT_REGISTRY_FILE);
+        registry = existsSync(path)
+            ? parseProjectRegistry(JSON.parse(readFileSync(path, 'utf8')))
+            : registry;
+    }
+    catch {
+        // A cache that cannot be read is an empty cache, never an error: the daemon still resolves
+        // through discovery, and falls back to its own root exactly as it did before this existed.
+    }
+    let discovery = { found: [], searched: [] };
+    try {
+        discovery = discoverProjectConfigs(process.cwd());
+    }
+    catch {
+        // Same reasoning: a diagnostic search that throws must not take a tool call with it.
+    }
+    return projectCandidatesFrom(discovery, registry, announcedDevServers());
+}
+/**
+ * The dev servers the build plugin announced, with the project id and root each serves. Read from
+ * the same state directory the plugin writes to. Unreadable or malformed entries are skipped: a stale
+ * announcement only ever names a directory that really was that project.
+ */
+function announcedDevServers() {
+    const override = process.env[ReticleEnv.STATE_DIR];
+    const dir = override !== undefined && 0 < override.length ? override : join(homedir(), ReticleDir.ROOT);
+    const servers = [];
+    try {
+        for (const name of readdirSync(dir)) {
+            if (null === devServerRegistryPort(name))
+                continue;
+            try {
+                const parsed = DevServerEntrySchema.safeParse(JSON.parse(readFileSync(join(dir, name), 'utf8')));
+                if (parsed.success)
+                    servers.push({ projectId: parsed.data.projectId, root: parsed.data.root });
+            }
+            catch {
+                /* one bad announcement does not hide the others */
+            }
         }
-        catch {
-            // Same reasoning: a diagnostic search that throws must not take a tool call with it.
+    }
+    catch {
+        /* no state directory yet: nothing has been announced */
+    }
+    return servers;
+}
+/**
+ * The directory of the project a page announced, or undefined when this machine does not know it.
+ *
+ * A daemon is shared: started from `$HOME`, a monorepo root, or another project's MCP client, its
+ * cwd is often not the app that sent the HELLO. The version-skew remedy read `package.json` from
+ * cwd anyway, so it fell back to the generic sensor package and told a Next.js project to install
+ * `@reticlehq/browser` (#1135). This is the same lookup the artifact root uses, keyed by the page's
+ * own project id.
+ */
+export function projectDirectoryFor(projectId) {
+    if (projectId === undefined)
+        return undefined;
+    const directories = new Set(knownProjectCandidates()
+        .filter((candidate) => candidate.projectId === projectId)
+        .map((candidate) => candidate.directory));
+    // Two checkouts declaring one id are refused, as the artifact root refuses them: naming one of
+    // them would read the wrong app's package.json and prescribe its packages to the other.
+    return 1 === directories.size ? [...directories][0] : undefined;
+}
+export function artifactRootResolver(daemonRoot, deps) {
+    const candidates = deps.candidates ?? knownProjectCandidates;
+    const sitsInAProject = deps.daemonIsProject ?? daemonSitsInAProject;
+    const { servingDirectory } = deps;
+    const daemonIsProject = sitsInAProject(daemonRoot);
+    // Resolved beside it and ONCE, for the same reason: a directory's `.reticle.json` does not change
+    // between two tabs connecting. Only read when the daemon really is in a project, since it is the
+    // sole thing that can license a write into the daemon's own tree.
+    const daemonProjectId = daemonIsProject
+        ? daemonOwnProjectId(daemonRoot, candidates())
+        : undefined;
+    return (projectId, origin) => {
+        const known = candidates();
+        let resolved = resolveArtifactRoot({ projectId, candidates: known, daemonRoot });
+        // Several checkouts declare this project — every git worktree carries the same committed
+        // `.reticle.json`. Only now is the serving process looked up: it shells out, and the tie is the
+        // one case where where the page was SERVED from is the deciding fact.
+        if (resolved.reason === ArtifactRootReason.AMBIGUOUS && origin !== undefined) {
+            resolved = resolveArtifactRoot({
+                projectId,
+                candidates: known,
+                daemonRoot,
+                servingDirectory: servingDirectory(origin),
+            });
         }
-        const resolved = resolveArtifactRoot({
-            projectId,
-            candidates: projectCandidatesFrom(discovery, registry),
-            daemonRoot,
-        });
         if (resolved.reason === ArtifactRootReason.MATCHED_PROJECT)
             return resolved;
         // Could not name the project. The old code wrote into the daemon's directory anyway and said
@@ -71,6 +175,7 @@ export function artifactRootResolver(daemonRoot) {
             daemonRoot,
             daemonIsProject,
             home: homedir(),
+            ...(daemonProjectId === undefined ? {} : { daemonProjectId }),
             ...(projectId === undefined ? {} : { projectId }),
             // Only reached when no project id survives the guard. Without it every app that never
             // stamped one shares a single directory -- and that directory holds the durable half, so one
@@ -80,6 +185,9 @@ export function artifactRootResolver(daemonRoot) {
         if (root !== daemonRoot) {
             log('artifact_root_unmatched', {
                 projectId: projectId ?? null,
+                // The other half of the comparison, so a reader can tell "the daemon was a guest" from
+                // "the daemon is in a DIFFERENT project" without reading the config files by hand.
+                daemonProjectId: daemonProjectId ?? null,
                 reason: resolved.reason,
                 root,
             });

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

@@ -43,6 +43,13 @@ interface ArtifactRootQuery {
     candidates: readonly ProjectCandidate[];
     /** Where artifacts go when the project cannot be identified. Already a `.reticle` path. */
     daemonRoot: string;
+    /**
+     * The directory the dev server that served this page runs in, when the caller could observe it.
+     * Only consulted to break an AMBIGUOUS tie: every git worktree carries the same committed
+     * `.reticle.json`, so the projectId cannot tell them apart, but the serving process runs inside
+     * exactly one of them.
+     */
+    servingDirectory?: string | undefined;
 }
 export interface ArtifactRoot {
     /** Absolute path to the `.reticle` directory. Always present, on every branch. */
@@ -68,7 +75,10 @@ export declare function resolveArtifactRoot(query: ArtifactRootQuery): ArtifactR
  * 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 declare function projectCandidatesFrom(discovery: ConfigDiscovery, registry: ProjectRegistry): ProjectCandidate[];
+export declare function projectCandidatesFrom(discovery: ConfigDiscovery, registry: ProjectRegistry, devServers?: readonly {
+    projectId?: string | undefined;
+    root: string;
+}[]): ProjectCandidate[];
 /** Where evidence goes when no project could be named and the daemon is a guest in this tree. */
 export declare const UNMATCHED_SUBDIR = "unmatched";
 /**
@@ -83,20 +93,47 @@ export declare const UNMATCHED_SUBDIR = "unmatched";
  * Two cases, and only one of them was ever the intended behaviour:
  *
  *   - the daemon is sitting IN a Reticle project (a developer who ran `reticle serve` in their own
- *     app). Its root is the right answer, and it is the case the old fallback was written for.
- *   - the daemon is a guest — no `.reticle.json`, no `.reticle/` already there. Then the evidence
- *     goes to the user's own `~/.reticle/unmatched/<projectId>`, which is Reticle's to write.
+ *     app), and the session is asking about THAT project. Its root is the right answer, and it is
+ *     the case the old fallback was written for.
+ *   - otherwise — a guest in the tree, or a daemon in its own checkout serving a DIFFERENT project.
+ *     Then the evidence goes to the user's own `~/.reticle/unmatched/<projectId>`, which is
+ *     Reticle's to write.
  *
  * It is never dropped. A verdict with nowhere to live is a worse failure than one in an unexpected
  * place, and the caller says out loud where it went.
  *
+ * ## The second case in that list used to be missing, and it is not an edge case
+ *
+ * `daemonIsProject` answers "is the daemon sitting in SOME Reticle project". The guard below read it
+ * as "this session's project", and those are different questions whenever the two ids differ. Run
+ * the daemon in repo A, then connect an app from a git worktree B of that same repo: B has its own
+ * `projectId` in its own `.reticle.json`, and discovery cannot see it — it walks out from A's
+ * `process.cwd()` and never crosses into a sibling checkout — so this function is reached with a
+ * NAMED project and the daemon's root came back anyway. B's intents, flows and runs were written
+ * into A's checkout, and the returned path said A, so nothing looked wrong.
+ *
+ * A real identity always wins. The daemon's root is only the answer when it is that identity's own
+ * root, or when no identity was named at all.
+ *
  * `projectId` arrives in HELLO from the page, so it is untrusted input on a path join and is held
- * to one safe segment — the same guard session ids and flow names already pass.
+ * to one safe segment — the same guard session ids and flow names already pass. `daemonProjectId`
+ * is read from the daemon's own `.reticle.json` and gets the same treatment, because equality
+ * against a guarded value is only as strong as the weaker side.
  */
 export declare function unmatchedRoot(query: {
     daemonRoot: string;
     /** Whether the daemon's own directory is a Reticle project — an IO question, answered by the caller. */
     daemonIsProject: boolean;
+    /**
+     * The daemon's OWN projectId, when its directory declares one. Absent means the daemon cannot
+     * prove which project it belongs to, so a named project that is not demonstrably its own declines.
+     *
+     * A plain `string` rather than a `ProjectId`, because it arrives from a `ProjectCandidate` — the
+     * registry's view of a `.reticle.json` — and the brand is only minted where the id is read out of
+     * that file for this daemon. Comparing it against a branded session id is unaffected: the brand is
+     * a `string`, and the guard below is what actually holds it to one safe path segment.
+     */
+    daemonProjectId?: string | undefined;
     /** The user's home directory. Passed in rather than read, so this stays pure. */
     home: string;
     projectId?: ProjectId | undefined;

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

@@ -1,4 +1,4 @@
-import { join } from 'node:path';
+import { isAbsolute, join, relative, sep } from 'node:path';
 import { SAFE_SEGMENT_PATTERN, ReticleDir, fnv1a, projectCandidates, } from '@reticlehq/core';
 /**
  * Which `.reticle/` a session's artifacts belong in.
@@ -51,6 +51,10 @@ export function resolveArtifactRoot(query) {
         return { root: daemonRoot, reason: ArtifactRootReason.NO_MATCH };
     }
     if (matches.length > 1) {
+        const served = checkoutContaining(matches, query.servingDirectory);
+        if (served !== undefined) {
+            return { root: join(served, ReticleDir.ROOT), reason: ArtifactRootReason.MATCHED_PROJECT };
+        }
         return {
             root: daemonRoot,
             reason: ArtifactRootReason.AMBIGUOUS,
@@ -66,6 +70,24 @@ export function resolveArtifactRoot(query) {
     }
     return { root: join(directory, ReticleDir.ROOT), reason: ArtifactRootReason.MATCHED_PROJECT };
 }
+/**
+ * The checkout the serving directory sits in, or undefined when it is in none of them.
+ *
+ * Deepest wins, because a worktree can live INSIDE the primary checkout (`.claude/worktrees/x`) and
+ * then sits under both; the deeper one is the one the server actually runs in. `relative` rather
+ * than a string prefix, so `/wt/pr-77` is not read as inside `/wt/pr-7`, and on every platform.
+ */
+function checkoutContaining(matches, servingDirectory) {
+    if (servingDirectory === undefined || 0 === servingDirectory.length)
+        return undefined;
+    const inside = matches
+        .map((candidate) => candidate.directory)
+        .filter((directory) => {
+        const rel = relative(directory, servingDirectory);
+        return '' === rel || ('..' !== rel && !rel.startsWith(`..${sep}`) && !isAbsolute(rel));
+    });
+    return inside.sort((a, b) => b.length - a.length)[0];
+}
 /**
  * One entry per directory.
  *
@@ -92,11 +114,21 @@ function dedupeByDirectory(matches) {
  * 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) {
+export function projectCandidatesFrom(discovery, registry, devServers = []) {
     const discovered = discovery.found.flatMap((config) => config.projectId === undefined || 0 === config.projectId.length
         ? []
         : [{ projectId: config.projectId, directory: config.directory }]);
-    return [...discovered, ...projectCandidates(registry)];
+    const known = [...discovered, ...projectCandidates(registry)];
+    // A dev server's own announcement of its project id and root, ONLY for an id nothing above names.
+    // It is the one source that knows an app wired by the build plugin alone (no `.reticle.json`, never
+    // `init`-ed), whose runs otherwise went to `unmatched/`, which nothing syncs. It fills gaps and never
+    // competes: `init` at a monorepo root names the root while the dev server names the app's subfolder,
+    // and counting both refused a project that resolved fine before.
+    const named = new Set(known.map((candidate) => candidate.projectId));
+    const announced = devServers.flatMap((server) => server.projectId === undefined || 0 === server.projectId.length || named.has(server.projectId)
+        ? []
+        : [{ projectId: server.projectId, directory: server.root }]);
+    return [...known, ...announced];
 }
 /** Where evidence goes when no project could be named and the daemon is a guest in this tree. */
 export const UNMATCHED_SUBDIR = 'unmatched';
@@ -132,23 +164,70 @@ const ORIGIN_BUCKET_PREFIX = 'origin-';
  * Two cases, and only one of them was ever the intended behaviour:
  *
  *   - the daemon is sitting IN a Reticle project (a developer who ran `reticle serve` in their own
- *     app). Its root is the right answer, and it is the case the old fallback was written for.
- *   - the daemon is a guest — no `.reticle.json`, no `.reticle/` already there. Then the evidence
- *     goes to the user's own `~/.reticle/unmatched/<projectId>`, which is Reticle's to write.
+ *     app), and the session is asking about THAT project. Its root is the right answer, and it is
+ *     the case the old fallback was written for.
+ *   - otherwise — a guest in the tree, or a daemon in its own checkout serving a DIFFERENT project.
+ *     Then the evidence goes to the user's own `~/.reticle/unmatched/<projectId>`, which is
+ *     Reticle's to write.
  *
  * It is never dropped. A verdict with nowhere to live is a worse failure than one in an unexpected
  * place, and the caller says out loud where it went.
  *
+ * ## The second case in that list used to be missing, and it is not an edge case
+ *
+ * `daemonIsProject` answers "is the daemon sitting in SOME Reticle project". The guard below read it
+ * as "this session's project", and those are different questions whenever the two ids differ. Run
+ * the daemon in repo A, then connect an app from a git worktree B of that same repo: B has its own
+ * `projectId` in its own `.reticle.json`, and discovery cannot see it — it walks out from A's
+ * `process.cwd()` and never crosses into a sibling checkout — so this function is reached with a
+ * NAMED project and the daemon's root came back anyway. B's intents, flows and runs were written
+ * into A's checkout, and the returned path said A, so nothing looked wrong.
+ *
+ * A real identity always wins. The daemon's root is only the answer when it is that identity's own
+ * root, or when no identity was named at all.
+ *
  * `projectId` arrives in HELLO from the page, so it is untrusted input on a path join and is held
- * to one safe segment — the same guard session ids and flow names already pass.
+ * to one safe segment — the same guard session ids and flow names already pass. `daemonProjectId`
+ * is read from the daemon's own `.reticle.json` and gets the same treatment, because equality
+ * against a guarded value is only as strong as the weaker side.
  */
 export function unmatchedRoot(query) {
-    if (query.daemonIsProject)
+    if (query.daemonIsProject && isTheDaemonsOwnProject(query.daemonProjectId, query.projectId))
         return query.daemonRoot;
     const id = query.projectId ?? '';
     const named = SAFE_SEGMENT_PATTERN.test(id) && !id.includes('..');
     return join(query.home, ReticleDir.ROOT, UNMATCHED_SUBDIR, named ? id : unnamedSegment(query.origin));
 }
+/**
+ * May the daemon write this session's artifacts into its own `.reticle/`?
+ *
+ * Two ways to qualify, and the difference between them is the whole bug: belonging to the directory
+ * is not the same as owning it.
+ *
+ *   - Nobody named a project (a pre-2.0 SDK sends no projectId). There is no identity to disagree
+ *     with, and the daemon's own root is the only thing on offer.
+ *   - The named project IS the daemon's own, and the daemon can prove it — `.reticle.json` sits in
+ *     its directory and declares the same id. Both sides go through the same segment guard, because
+ *     an equality between a guarded value and an unguarded one is only as strong as the loose side.
+ *
+ * A NAMED project the daemon cannot match declines, including when it has a `.reticle/` but no
+ * readable id. Declining costs the session its home directory and buys the guarantee that one
+ * checkout never receives another's ledger; the alternative is a wrong answer that reports success.
+ *
+ * The two ids are REQUIRED parameters rather than one object, and that is load-bearing. Taking a
+ * partial object let a caller omit a field and still compile — and an omitted `projectId` reads as
+ * "nobody named a project", which answers `true` and puts the session straight back into the daemon's
+ * checkout. That is the original defect, reachable by a typo rather than by a decision.
+ */
+function isTheDaemonsOwnProject(daemonProjectId, projectId) {
+    if (projectId === undefined || 0 === projectId.length)
+        return true;
+    if (daemonProjectId === undefined || 0 === daemonProjectId.length)
+        return false;
+    return (daemonProjectId === projectId &&
+        SAFE_SEGMENT_PATTERN.test(daemonProjectId) &&
+        !daemonProjectId.includes('..'));
+}
 /** Hashed, not spelled: an origin carries a host and a port, and neither belongs in a path segment. */
 function unnamedSegment(origin) {
     if (origin === undefined || 0 === origin.trim().length)

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

@@ -17,8 +17,6 @@ export interface ReticleDirPaths {
     impact: string;
     /**.../.reticle/intent.json — the LEGACY single ledger, read until the first write migrates it into .reticle/intent/ */
     intent: string;
-    /**.../.reticle/fill-values.json (what a drive types into each labelled field — git-checked) */
-    fillValues: string;
     /**.../.reticle/visual (PNG baselines + diffs) */
     visual: string;
     /**.../.reticle/runs (verification-run artifacts) */
@@ -37,6 +35,10 @@ export interface ReticleDirPaths {
     coverage: string;
     /**.../.reticle/assertion-tiers.json (last-passing assertion tiers; anti-reward-hacking baseline) */
     tiers: string;
+    /**.../.reticle/request.json (the user's latest request, relayed by the agent, classified) */
+    request: string;
+    /** .reticle/plans/ — every Harness drive plan made here, and how it went. */
+    plans: string;
 }
 export declare function reticleDirPaths(root: string): ReticleDirPaths;
 /** The verification-run artifact path for `runId`.reticle/runs/<runId>.json). */

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

@@ -10,7 +10,6 @@ export function reticleDirPaths(root) {
         project: join(root, ReticleDir.PROJECT_FILE),
         impact: join(root, ReticleDir.IMPACT_FILE),
         intent: join(root, ReticleDir.INTENT_FILE),
-        fillValues: join(root, ReticleDir.FILL_VALUES_FILE),
         visual: join(root, ReticleDir.VISUAL_SUBDIR),
         runs: join(root, ReticleDir.RUNS_SUBDIR),
         sessions: join(root, ReticleDir.SESSIONS_SUBDIR),
@@ -20,6 +19,9 @@ export function reticleDirPaths(root) {
         flake: join(root, ReticleDir.FLAKE_FILE),
         coverage: join(root, ReticleDir.COVERAGE_FILE),
         tiers: join(root, ReticleDir.TIERS_FILE),
+        // Beside `intent/`, not in it: `intent/` is committed, and this is the user's own words.
+        request: join(root, ReticleDir.REQUEST_FILE),
+        plans: join(root, ReticleDir.PLANS_SUBDIR),
     };
 }
 /** The verification-run artifact path for `runId`.reticle/runs/<runId>.json). */

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

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { describeSync, overallStatus, readSyncSummary } from './sync-status.js';
 import { sessionRoot } from './session-root.js';
 import { projectForRoot } from './project-for-root.js';
 import { ProjectReadError, RunStatus } from '@reticlehq/core';
@@ -94,6 +95,7 @@ export const PROJECT_TOOLS = [
         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.'),
+            push: z.boolean().optional().describe('Sync with the platform now, before answering.'),
             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.'),
@@ -110,14 +112,31 @@ export const PROJECT_TOOLS = [
             cloud: z.unknown().optional(),
         },
         handler: async (deps, args) => {
-            const cloud = await cloudRegression(deps, asString(args['sessionId']));
-            const withCloud = (obj) => cloud === undefined ? obj : { ...obj, cloud };
+            // A push asked for is done first, so the status below describes what it achieved.
+            if (true === args['push'])
+                await deps.syncNow?.().catch(() => undefined);
+            const root = sessionRoot(deps, asString(args['sessionId']));
+            const linked = (await deps.linkedCloud?.().catch(() => null)) ?? null;
+            const summary = readSyncSummary(root, null !== linked);
+            const sync = {
+                ...summary,
+                status: overallStatus(summary),
+                said: describeSync(summary, deps.now()),
+            };
+            const regression = await cloudRegression(deps, asString(args['sessionId']));
+            // Where this project's work stands with the platform rides in `cloud` beside the team's
+            // regression report: the two answers to "what does the platform know about this project".
+            const cloud = {
+                ...('object' === typeof regression && null !== regression ? regression : {}),
+                sync,
+            };
+            const withCloud = (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'
+                        ? 'no .reticle/project.json yet — the first verified run writes it: drive one step with reticle_act_and_wait and an `until`'
                         : '.reticle/project.json is malformed — it will self-heal on the next recorded run',
                     reason: read.reason,
                 });

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

@@ -1,5 +1,21 @@
 import type { ProjectId } from '@reticlehq/core';
 import type { ToolDeps } from '../../surface/tools/tool-kit.js';
+/**
+ * Which project a call is about, and the page origin it came through.
+ *
+ * The projectId alone is not an address: every git worktree carries the same committed
+ * `.reticle.json`, so a daemon serving several worktrees sees one id for all of them. The origin
+ * names the dev server that served the page, and the resolver uses it to pick the checkout that
+ * server runs in. Carried as one value so no caller can resolve with half of it -- a flow saved
+ * through the worktree and replayed through the id alone would land in one tree and be read from
+ * another.
+ */
+export interface ProjectTarget {
+    projectId: ProjectId | undefined;
+    origin?: string | undefined;
+}
+/** The target for a caller that genuinely holds no session -- the id is all there is. */
+export declare function projectOnly(projectId: ProjectId | undefined): ProjectTarget;
 /**
  * The `.reticle` directory a tool call's artifacts belong in.
  *
@@ -24,7 +40,7 @@ export declare function sessionRoot(deps: ToolDeps, sessionId: string | undefine
  * 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;
+export declare function rootForTarget(deps: ToolDeps, target: ProjectTarget): 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
@@ -50,3 +66,10 @@ export declare function projectDirFor(deps: ToolDeps, sessionId: string | undefi
  * there is no answer either.
  */
 export declare function sessionProjectId(deps: ToolDeps, sessionId: string | undefined): ProjectId | undefined;
+/**
+ * `sessionTarget` for the paths that degrade instead of refusing: replay and learning resolve a
+ * missing session to the global store, and keep doing so -- with the origin when there is one.
+ */
+export declare function safeSessionTarget(deps: ToolDeps, sessionId: string | undefined): ProjectTarget;
+/** `sessionProjectId` plus the origin the session's page was served from. Same refusals. */
+export declare function sessionTarget(deps: ToolDeps, sessionId: string | undefined): ProjectTarget;

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

@@ -1,4 +1,23 @@
 import { dirname } from 'node:path';
+/**
+ * The scheme://host:port a session's page was served from. Local rather than the session manager's
+ * copy because `memory/project` does not reach `portal/session`, and five lines are cheaper than a
+ * new dependency between the two.
+ */
+function originOf(url) {
+    if (url === undefined)
+        return undefined;
+    try {
+        return new URL(url).origin;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The target for a caller that genuinely holds no session -- the id is all there is. */
+export function projectOnly(projectId) {
+    return { projectId };
+}
 /**
  * The `.reticle` directory a tool call's artifacts belong in.
  *
@@ -26,7 +45,7 @@ export function sessionRoot(deps, sessionId) {
     // 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));
+    return rootForTarget(deps, nothingToRefuse ? projectOnly(undefined) : sessionTarget(deps, sessionId));
 }
 /**
  * The same answer for a caller that already holds the projectId rather than a sessionId.
@@ -37,8 +56,8 @@ export function sessionRoot(deps, sessionId) {
  * 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;
+export function rootForTarget(deps, target) {
+    return deps.artifactRootFor?.(target.projectId, target.origin).root ?? deps.reticleRoot;
 }
 /**
  * The PROJECT directory -- one level above `.reticle` -- for a caller that runs a tool in a tree
@@ -74,12 +93,29 @@ export function projectDirFor(deps, sessionId) {
  * from this file so they cannot disagree again.
  */
 export function sessionProjectId(deps, sessionId) {
+    return sessionTarget(deps, sessionId).projectId;
+}
+/**
+ * `sessionTarget` for the paths that degrade instead of refusing: replay and learning resolve a
+ * missing session to the global store, and keep doing so -- with the origin when there is one.
+ */
+export function safeSessionTarget(deps, sessionId) {
+    try {
+        return sessionTarget(deps, sessionId);
+    }
+    catch {
+        return projectOnly(undefined);
+    }
+}
+/** `sessionProjectId` plus the origin the session's page was served from. Same refusals. */
+export function sessionTarget(deps, sessionId) {
     try {
-        return deps.sessions.resolve(sessionId).projectId;
+        const session = deps.sessions.resolve(sessionId);
+        return { projectId: session.projectId, origin: originOf(session.url) };
     }
     catch (cause) {
         if (sessionId === undefined)
-            return undefined;
+            return projectOnly(undefined);
         throw unresolvedTargetRefusal(sessionId, cause);
     }
 }