@reticlehq/server 3.5.0 → 3.7.0

package/dist/memory/journal/session-end.d.ts

@@ -62,7 +62,8 @@ interface SessionEndDeps {
      * directories into `language/flows/recording/tape/` for a constant and two types was a dependency
      * nobody needed. `directory-reach.test.ts` refused it, and its advice was right.
      */
-    takeAmbientTape?: () => {
+    /** The tape of THIS tab's steps: another app's drive is never saved into this project. */
+    takeAmbientTape?: (sessionId: string) => {
         steps: readonly TapeStep[];
         startPath?: string;
     } | undefined;
@@ -120,4 +121,17 @@ export declare function makeSessionEnd(deps: SessionEndDeps): (session: SessionE
  * dashboard.
  */
 export declare function recordDriveRun(deps: SessionEndDeps, session: SessionEndTarget): Promise<void>;
+/**
+ * Tear down every session still open, and wait for it.
+ *
+ * Teardown is what saves a tab's driven flow and its last run, and it normally fires from the
+ * socket's close handler, unawaited. A daemon closing with tabs open terminated those sockets after
+ * its final sync, so the flow was written too late to be sent, or not at all once the process
+ * exited. Called before that final sync instead: each session leaves the registry first, so the
+ * socket closing later finds nothing to tear down a second time.
+ */
+export declare function endLiveSessions<S>(sessions: {
+    all: () => S[];
+    remove: (session: S) => boolean;
+}, teardown: (session: S) => Promise<void>): Promise<void>;
 export {};

package/dist/memory/journal/session-end.js

@@ -1,4 +1,5 @@
-import { DRIVE_FLOW_PREFIX, driveFlowsFrom, } from './drive-flow.js';
+import { DRIVE_FLOW_PREFIX, DriveFlowSkipReason, driveFlowsFrom, } from './drive-flow.js';
+import { basename, dirname } from 'node:path';
 import { log } from '../../log.js';
 /** What a session's teardown writes to the daemon log when a by-product fails to save. */
 const SESSION_END_LOG = {
@@ -7,13 +8,13 @@ const SESSION_END_LOG = {
 };
 const errorMessage = (error) => error instanceof Error ? error.message : String(error);
 import { journalActionsPath, sessionDirPath } from '../project/dir/reticle-dir.js';
-import { asSessionId } from '@reticlehq/core';
+import { asRunId, asSessionId } from '@reticlehq/core';
 import { OnboardingPhase, OnboardingStepStatus, } from '@reticlehq/core/telemetry';
 import { AmbientStore } from './ambient-store.js';
 import { subjectOf } from '@reticlehq/core';
 import { pruneWorkspace } from './on-disk/startup-maintenance.js';
 import { buildVerificationRun } from '../../judgement/runs/artifact/build-verification-run.js';
-import { driveRunFrom, driveRunId } from '../../judgement/runs/drive-run.js';
+import { agentEndClaims, agentEndCounts, driveRunId, driveRunsFrom, } from '../../judgement/runs/drive-run.js';
 import { RunStore } from '../../judgement/runs/artifact/run-store.js';
 /**
  * Build the teardown handler the bridge fires when a session is removed. Flushes the journal first (so no
@@ -173,16 +174,21 @@ export async function recordDriveRun(deps, session) {
     if (session.readJournalActions === undefined)
         return;
     const actions = await session.readJournalActions();
-    const input = driveRunFrom(actions, {
+    const root = session.artifactRoot ?? deps.reticleRoot;
+    const inputs = driveRunsFrom(actions, {
         // Derived from the session, NOT random. Teardown fires on every socket close, and a reconnecting
         // tab keeps its session id and appends to the same ledger — so a drive across two page reloads
         // would fold the whole ledger twice and publish two overlapping rows, the second a superset of
         // the first. A stable id makes the artifact idempotent: the same session rewrites its own run,
         // and the cloud diffs by runId, so a re-push supersedes rather than duplicates.
         runId: driveRunId(session.id),
+        // Each agent session in the tab, as `reticle_session {end}` cut them, is its own run.
+        agentEnds: agentEndCounts(session.id),
+        agentClaims: agentEndClaims(session.id),
         ...(session.projectId === undefined ? {} : { projectId: session.projectId }),
+        projectName: basename(dirname(root)),
     });
-    if (input === undefined)
+    if (0 === inputs.length)
         return;
     // The protocol reaching the artifact a person actually reads. Only when the session could say
     // where it was: a subject with no locator is not a weaker subject, it is a guess, and the
@@ -196,12 +202,19 @@ export async function recordDriveRun(deps, session) {
             currentDocumentId: session.currentDocumentId,
             currentEditEpoch: session.currentEditEpoch,
         });
-    const store = new RunStore(deps.fs, session.artifactRoot ?? deps.reticleRoot, 
+    const store = new RunStore(deps.fs, root, 
     // Tell the sync daemon a run landed, rather than letting it find out on its next tick. Teardown
     // used to write this artifact with no callback at all, so the evidence from a whole session sat
     // on disk until a timer noticed — which, for the last session of the day, could be never.
     deps.onRunPersisted === undefined ? undefined : { onWrote: deps.onRunPersisted });
-    await store.write(buildVerificationRun({ ...input, ...(subject === undefined ? {} : { subject }) }, deps.now ?? (() => Date.now())));
+    const clock = deps.now ?? (() => Date.now());
+    for (const input of inputs) {
+        // A reload rewrites this session's run under the same id; the first stamp is when it ran, and
+        // restamping on every rewrite showed the tab's close as the drive's time.
+        const held = await store.read(asRunId(input.runId));
+        const firstAt = held.ok ? held.run.createdAt : undefined;
+        await store.write(buildVerificationRun({ ...input, ...(subject === undefined ? {} : { subject }) }, firstAt === undefined ? clock : () => firstAt));
+    }
 }
 /** Persist what this session drove as a replayable flow, when it declared anything provable. */
 async function saveDrivenFlow(deps, session) {
@@ -210,7 +223,7 @@ async function saveDrivenFlow(deps, session) {
     if (takeTape === undefined || flows === undefined)
         return;
     // One flow per journey the session contained, not one flow per session — see drive-flow.ts.
-    const { programs, outcome } = driveFlowsFrom(takeTape());
+    const { programs, outcome } = driveFlowsFrom(takeTape(session.id));
     const author = deps.author?.();
     for (const program of programs) {
         // Folded into any saved copy of the same journey, so each session does not add a near-copy.
@@ -226,7 +239,13 @@ async function saveDrivenFlow(deps, session) {
         phase: OnboardingPhase.FIRST_RUN,
         step: 'flow_recorded',
         status: 0 === programs.length ? OnboardingStepStatus.SKIPPED : OnboardingStepStatus.COMPLETED,
-        ...(outcome.unprovenSteps === undefined ? {} : { reason: 'no_declared_consequence' }),
+        ...(outcome.unprovenSteps === undefined
+            ? {}
+            : { reason: DriveFlowSkipReason.NO_DECLARED_CONSEQUENCE }),
+        // Not saved, with the reason: proved against mocked responses, which replay cannot see (#1459).
+        ...(0 < programs.length || outcome.mockedSteps === undefined
+            ? {}
+            : { reason: DriveFlowSkipReason.DRIVEN_UNDER_NETWORK_MOCKS }),
     });
 }
 /**
@@ -247,3 +266,17 @@ async function dropUndrivenJournal(fs, root, sessionId) {
         // tidying is never the reason a teardown fails
     }
 }
+/**
+ * Tear down every session still open, and wait for it.
+ *
+ * Teardown is what saves a tab's driven flow and its last run, and it normally fires from the
+ * socket's close handler, unawaited. A daemon closing with tabs open terminated those sockets after
+ * its final sync, so the flow was written too late to be sent, or not at all once the process
+ * exited. Called before that final sync instead: each session leaves the registry first, so the
+ * socket closing later finds nothing to tear down a second time.
+ */
+export async function endLiveSessions(sessions, teardown) {
+    const ending = sessions.all().filter((session) => sessions.remove(session));
+    // Teardown is best-effort everywhere it runs: one that fails must not stop the others.
+    await Promise.all(ending.map((session) => teardown(session).catch(() => undefined)));
+}

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

@@ -1,5 +1,16 @@
+import { type ProjectCandidate } from '@reticlehq/core/artifacts';
 import { type ProjectId } from '@reticlehq/core';
 import { type ArtifactRoot } from './artifact-root.js';
+/**
+ * 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 declare function knownProjectCandidates(): ProjectCandidate[];
 /**
  * The directory of the project a page announced, or undefined when this machine does not know it.
  *
@@ -10,4 +21,18 @@ import { type ArtifactRoot } from './artifact-root.js';
  * own project id.
  */
 export declare function projectDirectoryFor(projectId: string | undefined): string | undefined;
-export declare function artifactRootResolver(daemonRoot: string): (projectId: ProjectId | undefined, origin?: string) => ArtifactRoot;
+/** Where this resolver gets its IO answers. The defaults are the production ones. */
+export interface ArtifactRootResolverDeps {
+    /** Every project this machine knows about. Defaults to discovery + the user registry. */
+    candidates?: () => ProjectCandidate[];
+    /** Whether the daemon's own directory is a Reticle project. Defaults to looking at disk. */
+    daemonIsProject?: (daemonRoot: string) => boolean;
+    /**
+     * The directory of the dev server that served a page origin, or undefined when unobservable.
+     * Required, not defaulted: the production answer reads daemon state and shells out, which is the
+     * wiring layer's business (`portal/session/serving-directory.ts`), and a resolver built without it
+     * would silently keep sending every worktree's artifacts to the primary checkout.
+     */
+    servingDirectory: (origin: string) => string | undefined;
+}
+export declare function artifactRootResolver(daemonRoot: string, deps: ArtifactRootResolverDeps): (projectId: ProjectId | undefined, origin?: string) => ArtifactRoot;

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 { dirname, join } from 'node:path';
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { dirname, isAbsolute, join, relative } 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,12 +43,47 @@ function daemonSitsInAProject(daemonRoot) {
         return false;
     }
 }
+/**
+ * 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);
+    const own = candidates.find((candidate) => candidate.directory === directory)?.projectId;
+    // A monorepo root carries the id of the app `init --app` wired, as a pointer for an agent started
+    // there. When an app inside the root declares the same id, the root is pointing at it, not being
+    // it: answering with the id handed a second checkout's flows to this root with no warning.
+    const pointer = candidates.some((candidate) => candidate.projectId === own &&
+        candidate.directory !== directory &&
+        isInside(directory, candidate.directory));
+    return pointer ? undefined : own;
+}
+/** Is `dir` strictly inside `root`? */
+function isInside(root, dir) {
+    const rel = relative(root, dir);
+    return 0 < rel.length && !rel.startsWith('..') && !isAbsolute(rel);
+}
 /**
  * Every project this machine knows the directory of: discovered `.reticle.json` files first, then
- * the user-level registry. Read on each call, since `init` can run in another terminal while the
- * daemon is up.
+ * 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.
  */
-function knownProjectCandidates() {
+export function knownProjectCandidates() {
     let registry = emptyProjectRegistry();
     try {
         const path = join(homedir(), ReticleDir.ROOT, PROJECT_REGISTRY_FILE);
@@ -58,7 +102,35 @@ function knownProjectCandidates() {
     catch {
         // Same reasoning: a diagnostic search that throws must not take a tool call with it.
     }
-    return projectCandidatesFrom(discovery, registry);
+    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 {
+        /* 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.
@@ -79,14 +151,41 @@ export function projectDirectoryFor(projectId) {
     // 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) {
-    const daemonIsProject = daemonSitsInAProject(daemonRoot);
+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;
+    /** Said once per project, reason and folder: one session's calls repeated it 16 times in 3s. */
+    const told = new Set();
+    // ponytail: asked once per origin (it shells out); a dev server moved to another folder on the
+    // same port is named stale until the daemon restarts.
+    const servedFrom = new Map();
+    const servingOf = (origin) => {
+        if (!servedFrom.has(origin))
+            servedFrom.set(origin, servingDirectory(origin));
+        return servedFrom.get(origin);
+    };
     return (projectId, origin) => {
-        const resolved = resolveArtifactRoot({
-            projectId,
-            candidates: knownProjectCandidates(),
-            daemonRoot,
-        });
+        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: servingOf(origin),
+            });
+        }
         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
@@ -98,19 +197,29 @@ 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
             // app's learned expectations become another's.
             ...(origin === undefined ? {} : { origin }),
         });
-        if (root !== daemonRoot) {
+        const key = `${projectId ?? ''}\u0000${resolved.reason}\u0000${root}`;
+        if (root !== daemonRoot && !told.has(key)) {
+            told.add(key);
             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,
+                ...(resolved.candidates === undefined ? {} : { candidates: resolved.candidates }),
             });
         }
-        return { ...resolved, root };
+        // Named so the agent is told WHICH checkout's work is stranded: a clone serving the app was
+        // never named, only the primary checkout's folders.
+        const serving = origin === undefined ? undefined : servingOf(origin);
+        return { ...resolved, root, ...(serving === undefined ? {} : { serving }) };
     };
 }

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

@@ -1,3 +1,4 @@
+import { UNMATCHED_SUBDIR } from './dir/reticle-dir.js';
 import { type ProjectCandidate, type ProjectId, type ProjectRegistry } from '@reticlehq/core';
 import type { ConfigDiscovery } from '../../command/cli/config/config-discovery.js';
 /**
@@ -43,6 +44,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. */
@@ -53,6 +61,8 @@ export interface ArtifactRoot {
      * needs to name them; a caller that does not can ignore the field.
      */
     candidates?: string[];
+    /** The folder whose dev server served the page, when the evidence went unmatched and it is known. */
+    serving?: string;
 }
 /**
  * Resolve the artifact root for one session.
@@ -68,9 +78,11 @@ 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[];
-/** Where evidence goes when no project could be named and the daemon is a guest in this tree. */
-export declare const UNMATCHED_SUBDIR = "unmatched";
+export declare function projectCandidatesFrom(discovery: ConfigDiscovery, registry: ProjectRegistry, devServers?: readonly {
+    projectId?: string | undefined;
+    root: string;
+}[]): ProjectCandidate[];
+export { UNMATCHED_SUBDIR };
 /**
  * The fallback root for a session whose project could not be resolved.
  *
@@ -83,20 +95,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;
@@ -106,4 +145,3 @@ export declare function unmatchedRoot(query: {
      */
     origin?: string | undefined;
 }): string;
-export {};

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

@@ -1,4 +1,5 @@
-import { join } from 'node:path';
+import { isAbsolute, join, relative, sep } from 'node:path';
+import { UNMATCHED_SUBDIR } from './dir/reticle-dir.js';
 import { SAFE_SEGMENT_PATTERN, ReticleDir, fnv1a, projectCandidates, } from '@reticlehq/core';
 /**
  * Which `.reticle/` a session's artifacts belong in.
@@ -51,6 +52,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 +71,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,14 +115,23 @@ 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';
+export { UNMATCHED_SUBDIR };
 /** What a project with NO identity at all is called on disk. Never blank, so the path is always real. */
 const UNNAMED_PROJECT = 'unnamed';
 /**
@@ -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)