@reticlehq/server 3.5.0 → 3.6.0

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

@@ -1,8 +1,13 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
 import { z } from 'zod';
+import { StatementSource, classifyStatement, splitStatements, } from '@reticlehq/core/artifacts';
+import { redactFeedbackText } from '../../telemetry/feedback.js';
+import { reticleDirPaths } from '../project/dir/reticle-dir.js';
 import { IntentStore } from './intent-store.js';
 import { IntentShardStore } from './intent-shard-store.js';
 import { IntentStatus } from './intent-shard.js';
-import { ReticleTool } from '@reticlehq/core';
+import { ReticleDir, ReticleTool, apiKeyFrom } from '@reticlehq/core';
 import { sessionIdShape } from '../../surface/tools/tool-kit.js';
 import { PredicateSchema } from '@reticlehq/engine/question/predicate/predicate.js';
 import { sessionRoot } from '../project/session-root.js';
@@ -32,7 +37,7 @@ const MIGRATE = 'migrate';
 export const INTENT_TOOLS = [
     {
         name: ReticleTool.INTENT,
-        description: 'Record what a change is SUPPOSED to make true, as a durable statement ABOUT THE PRODUCT that a teammate who was not here will understand in six months — name the behaviour, not this run or its step number, and never "renders cleanly", which nothing can check. It is SHARED memory: pooled per project and read back by later agents. Capture it while you still know — then verification does not have to re-derive it from the DOM later. { action:"declare", intents:[{ id, statement, surface? }] } takes prose and needs NO predicate: at declare time there is often no route, no ref and no code yet, and a predicate demanded there is just a mechanism. Declare EARLY (as you build) and batch them — one call per feature is the whole budget. { action:"bind", id, binding } attaches the predicate that would prove it once you know how; an intent with no binding is not a failure, it is the most interesting row in the ledger — something meant that nothing can currently prove. { action:"list" } returns what is still open. Stored in .reticle/intent/<subject>/intent.json (a flow name is its subject), git-checked so a human sees in review if an intent was later narrowed to match what was easy to prove.',
+        description: 'Record what a change is SUPPOSED to make true, as a durable statement ABOUT THE PRODUCT that a teammate who was not here will understand in six months — name the behaviour, not this run or its step number, and never "renders cleanly", which nothing can check. It is SHARED memory: pooled per project and read back by later agents. Capture it while you still know — then verification does not have to re-derive it from the DOM later. { action:"declare", intents:[{ id, statement, surface? }] } takes prose and needs NO predicate: at declare time there is often no route, no ref and no code yet, and a predicate demanded there is just a mechanism. Declare EARLY (as you build) and batch them — one call per feature is the whole budget. { action:"bind", id, binding } attaches the predicate that would prove it once you know how; an intent with no binding is not a failure, it is the most interesting row in the ledger — something meant that nothing can currently prove. { action:"list" } returns what is still open. Pass `request` (what the user asked, verbatim) once per task. Stored in .reticle/intent/, git-checked.',
         example: {
             action: DECLARE,
             intents: [
@@ -74,6 +79,7 @@ export const INTENT_TOOLS = [
                 .min(1)
                 .optional()
                 .describe('declare only. Batchable — declare every intent for a feature in one call.'),
+            request: z.string().optional().describe("declare: the user's words, verbatim."),
             id: z.string().optional().describe('bind only: which intent the predicate proves.'),
             /*
              * The predicate schema, not `unknown`.
@@ -155,6 +161,12 @@ export const INTENT_TOOLS = [
                 return { intents: await store.open() };
             }
             const raw = args['intents'];
+            const request = asString(args['request']);
+            if (request !== undefined && 0 < request.trim().length) {
+                await recordRequest(deps, root, request, Array.isArray(raw) ? raw : []);
+                if (!Array.isArray(raw) || 0 === raw.length)
+                    return { request: 'recorded', path: root };
+            }
             // Refused, not read as an empty list: `declare` with nothing to declare stored nothing and
             // answered `{ intents: [] }`, which an agent reads as a declaration that worked (#1118).
             if (!Array.isArray(raw) || 0 === raw.length) {
@@ -171,3 +183,69 @@ export const INTENT_TOOLS = [
         },
     },
 ];
+const MAX_REQUEST = 20_000;
+const MAX_STATEMENT = 500;
+const MAX_STATEMENTS = 100;
+const PROJECT_CONFIG = '.reticle.json';
+/** Credentials and personal data out, length capped: the same rules feedback reports follow. */
+function redactSecrets(text, max) {
+    return redactFeedbackText(text, max).text;
+}
+/**
+ * Whether the request goes to the platform with the runs that verify it.
+ *
+ * A LINKED project shares it unless `.reticle.json` says `"shareRequests": false`: the platform
+ * reads what each run was for, which is half of what a run means. An unlinked project has nowhere
+ * to send it, and `"shareRequests": true` still shares from one that links later.
+ */
+function sharesRequests(projectDir, reticleRoot) {
+    let setting;
+    try {
+        const config = JSON.parse(readFileSync(join(projectDir, PROJECT_CONFIG), 'utf8'));
+        setting = config?.shareRequests;
+    }
+    catch {
+        setting = undefined;
+    }
+    if (false === setting)
+        return false;
+    if (true === setting)
+        return true;
+    // Linked by `reticle connect` (cloud.json), or by a key in the environment, the way CI syncs.
+    return (existsSync(join(reticleRoot, ReticleDir.CLOUD_LINK_FILE)) ||
+        apiKeyFrom(process.env) !== undefined);
+}
+/**
+ * Keep the user's request, and every statement in it and in the declared intents, classified and
+ * attributed, for the runs that verify it. Secrets are redacted before anything is written.
+ *
+ * Shared with the platform from a linked project unless `.reticle.json` says `"shareRequests": false`.
+ */
+async function recordRequest(deps, root, request, declared) {
+    const text = redactSecrets(request, MAX_REQUEST);
+    const agentStatements = declared.flatMap((d) => {
+        const statement = d?.statement;
+        return 'string' === typeof statement ? [statement] : [];
+    });
+    const context = {
+        request: text,
+        statements: [
+            ...splitStatements(text).map((t) => ({ text: t, source: StatementSource.USER })),
+            ...agentStatements.map((t) => ({
+                text: redactSecrets(t, MAX_STATEMENT),
+                source: StatementSource.AGENT,
+            })),
+        ]
+            .slice(0, MAX_STATEMENTS)
+            .map((s) => ({
+            ...s,
+            text: s.text.slice(0, MAX_STATEMENT),
+            kind: classifyStatement(s.text),
+        })),
+        at: deps.now(),
+        shared: sharesRequests(dirname(root), root),
+    };
+    const path = reticleDirPaths(root).request;
+    await deps.fs.mkdir(dirname(path));
+    await deps.fs.writeFile(path, `${JSON.stringify(context, null, 2)}\n`);
+}

package/dist/memory/journal/envelope.d.ts

@@ -113,13 +113,13 @@ export declare const RouteEnvelopeSchema: z.ZodObject<{
             m2: number;
             max: number;
         };
-        netErrors: {
+        consoleErrors: {
             count: number;
             mean: number;
             m2: number;
             max: number;
         };
-        consoleErrors: {
+        netErrors: {
             count: number;
             mean: number;
             m2: number;
@@ -138,13 +138,13 @@ export declare const RouteEnvelopeSchema: z.ZodObject<{
             m2: number;
             max: number;
         };
-        netErrors: {
+        consoleErrors: {
             count: number;
             mean: number;
             m2: number;
             max: number;
         };
-        consoleErrors: {
+        netErrors: {
             count: number;
             mean: number;
             m2: number;
@@ -167,13 +167,13 @@ export declare const RouteEnvelopeSchema: z.ZodObject<{
             m2: number;
             max: number;
         };
-        netErrors: {
+        consoleErrors: {
             count: number;
             mean: number;
             m2: number;
             max: number;
         };
-        consoleErrors: {
+        netErrors: {
             count: number;
             mean: number;
             m2: number;
@@ -196,13 +196,13 @@ export declare const RouteEnvelopeSchema: z.ZodObject<{
             m2: number;
             max: number;
         };
-        netErrors: {
+        consoleErrors: {
             count: number;
             mean: number;
             m2: number;
             max: number;
         };
-        consoleErrors: {
+        netErrors: {
             count: number;
             mean: number;
             m2: number;

package/dist/memory/journal/journal-recorder.js

@@ -1,5 +1,6 @@
 import { EventAttribution, JOURNAL_FILE_VERSION, } from '@reticlehq/core';
 import { isSelfObservation } from './self-observation.js';
+import { currentDrivenBy } from '../../hooks/driven-by.js';
 import { log } from '../../log.js';
 /**
  * Logged the FIRST time a journal write is lost, and never again for that recorder.
@@ -65,7 +66,7 @@ export class JournalRecorder {
     }
     /** Open an attribution window. One action is active at a time (the agent drives sequentially). */
     beginAction(actionId, tool, args) {
-        this.#active = { actionId, tool, args, tStart: this.#now() };
+        this.#active = { actionId, tool, args, tStart: this.#now(), drivenBy: currentDrivenBy() };
     }
     /** Close the active window: persist its buffered events, then the action record. No-op if none active. */
     finishAction(effect, settled, settledInMs) {
@@ -86,6 +87,7 @@ export class JournalRecorder {
                 : { from: active.seqFrom, to: active.seqTo },
             tRange: { from: active.tStart, to: this.#now() },
             at: active.tStart,
+            ...(active.drivenBy === undefined ? {} : { drivenBy: active.drivenBy }),
         };
         this.#enqueueFlush();
         this.#chain = this.#chain
@@ -123,6 +125,10 @@ export class JournalRecorder {
             // of zero, which is exactly how much time this action attributed events over.
             tRange: { from: at, to: at },
             at,
+            ...(() => {
+                const by = currentDrivenBy();
+                return by === undefined ? {} : { drivenBy: by };
+            })(),
         };
         this.#enqueueFlush();
         this.#chain = this.#chain

package/dist/memory/journal/on-disk/retention.d.ts

@@ -11,6 +11,8 @@ export declare const DEFAULT_DIFF_RETENTION = 10;
  * for the one case where delivery was refused and somebody has to file the report by hand.
  */
 export declare const DEFAULT_FEEDBACK_RETENTION = 20;
+/** Harness plans kept on disk: the platform keeps every one, this machine the recent ones. */
+export declare const DEFAULT_PLAN_RETENTION = 50;
 /**
  * The TOTAL the evidence tier of one `.reticle/` may occupy, across sessions, runs, overlay diffs
  * and feedback copies together.
@@ -141,5 +143,6 @@ export declare function pruneEvidenceBudget(fs: FileSystemPort, root: string, bu
  * Capped from here rather than from the writer, which lives in an area this file does not own. A
  * retention rule is the same rule whether the directory holds journals, diffs or reports.
  */
+export declare function prunePlans(fs: FileSystemPort, root: string, retention?: number): Promise<void>;
 export declare function pruneFeedback(fs: FileSystemPort, root: string, retention?: number): Promise<void>;
 export {};

package/dist/memory/journal/on-disk/retention.js

@@ -14,6 +14,8 @@ export const DEFAULT_DIFF_RETENTION = 10;
  * for the one case where delivery was refused and somebody has to file the report by hand.
  */
 export const DEFAULT_FEEDBACK_RETENTION = 20;
+/** Harness plans kept on disk: the platform keeps every one, this machine the recent ones. */
+export const DEFAULT_PLAN_RETENTION = 50;
 const DIFF_SUFFIX = '.diff.png';
 const PNG_SUFFIX = '.png';
 /**
@@ -287,6 +289,9 @@ export async function pruneEvidenceBudget(fs, root, budgetBytes = DEFAULT_EVIDEN
  * Capped from here rather than from the writer, which lives in an area this file does not own. A
  * retention rule is the same rule whether the directory holds journals, diffs or reports.
  */
+export async function prunePlans(fs, root, retention = DEFAULT_PLAN_RETENTION) {
+    await pruneByRecency(fs, join(root, ReticleDir.PLANS_SUBDIR), retention);
+}
 export async function pruneFeedback(fs, root, retention = DEFAULT_FEEDBACK_RETENTION) {
     await pruneByRecency(fs, join(root, ReticleDir.FEEDBACK_SUBDIR), retention);
 }

package/dist/memory/journal/on-disk/startup-maintenance.js

@@ -1,4 +1,4 @@
-import { pruneEvidenceBudget, pruneFeedback, pruneSessions, pruneVisualDiffs, } from './retention.js';
+import { pruneEvidenceBudget, pruneFeedback, prunePlans, pruneSessions, pruneVisualDiffs, } from './retention.js';
 import { DEFAULT_RETAIN } from './retain-policy.js';
 export async function pruneWorkspace(fs, root, live, options = {}) {
     const retain = { ...DEFAULT_RETAIN, ...options };
@@ -9,6 +9,8 @@ export async function pruneWorkspace(fs, root, live, options = {}) {
     await pruneVisualDiffs(fs, root, retain.visual);
     // Write-only local copies of reports the outbox already carries.
     await pruneFeedback(fs, root, retain.feedback);
+    // The recent plans are what somebody reads back; the platform holds every one.
+    await prunePlans(fs, root);
     // LAST, and the one that was missing: the only bound that limits SIZE rather than count.
     await pruneEvidenceBudget(fs, root, retain.budgetBytes, live);
 }

package/dist/memory/journal/on-disk/workspace-tiers.js

@@ -45,6 +45,8 @@ export const WORKSPACE_TIERS = {
     [ReticleDir.VISUAL_SUBDIR]: localDir,
     // Write-only: a local copy of what was already sent. The outbox is the record.
     [ReticleDir.FEEDBACK_SUBDIR]: localDir,
+    // What the Harness planned on this machine, and how it went. The platform keeps the team's copy.
+    [ReticleDir.PLANS_SUBDIR]: localDir,
     [ReticleDir.PROJECT_FILE]: localFile,
     [ReticleDir.AMBIENT_FILE]: localFile,
     [ReticleDir.ENVELOPES_FILE]: localFile,
@@ -52,6 +54,11 @@ export const WORKSPACE_TIERS = {
     // What THIS machine's drives covered, and the best each level reached — the gate's ratchet.
     [ReticleDir.COVERAGE_FILE]: localFile,
     [ReticleDir.TIERS_FILE]: localFile,
+    // The user's request in their own words: it leaves only with `shareRequests`, never by git push.
+    [ReticleDir.REQUEST_FILE]: localFile,
+    [ReticleDir.PLATFORM_MOMENTS_FILE]: localFile,
+    // Notes a human pinned in the HUD: free text about the page. The team reads them on the platform.
+    [ReticleDir.NOTES_FILE]: localFile,
     // The user's own record of what Reticle did for them, on THIS machine.
     [ReticleDir.IMPACT_FILE]: localFile,
     // This machine's conversation with the server. Its own doc comment says why committing it is
@@ -72,10 +79,6 @@ export const WORKSPACE_TIERS = {
     // credential, so it is safe to commit — the same reasoning that puts `cloud.json` here while its
     // API key stays in ~/.reticle.
     [ReticleDir.HOOKS_FILE]: sharedFile,
-    // What a drive types into each labelled field. Committed for two reasons: a replay must send
-    // exactly what the recording sent or it is not a replay, and a value a model wrote once should be
-    // reviewable and editable by the team rather than regenerated differently on every machine.
-    [ReticleDir.FILL_VALUES_FILE]: sharedFile,
 };
 function namesWhere(match) {
     return Object.entries(WORKSPACE_TIERS)

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

@@ -13,7 +13,7 @@ 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 { 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,7 +173,7 @@ export async function recordDriveRun(deps, session) {
     if (session.readJournalActions === undefined)
         return;
     const actions = await session.readJournalActions();
-    const input = driveRunFrom(actions, {
+    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
@@ -182,7 +182,7 @@ export async function recordDriveRun(deps, session) {
         runId: driveRunId(session.id),
         ...(session.projectId === undefined ? {} : { projectId: session.projectId }),
     });
-    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
@@ -201,7 +201,9 @@ export async function recordDriveRun(deps, session) {
     // 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())));
+    for (const input of inputs) {
+        await store.write(buildVerificationRun({ ...input, ...(subject === undefined ? {} : { subject }) }, deps.now ?? (() => Date.now())));
+    }
 }
 /** Persist what this session drove as a replayable flow, when it declared anything provable. */
 async function saveDrivenFlow(deps, session) {

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 { 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,12 +43,35 @@ 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);
+    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. 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 +90,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 +139,31 @@ 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;
     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: servingDirectory(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,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
@@ -107,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;