@reticlehq/server 3.6.0 → 3.7.0

package/dist/memory/journal/drive-flow.js

@@ -87,6 +87,13 @@ export function driveFlowName(route, steps = []) {
     const parts = [lead, ...('' !== why || 0 === leg.length ? [] : [leg])].filter((p) => '' !== p);
     return asFlowName(`${DRIVE_FLOW_PREFIX}${0 === parts.length ? 'journey' : parts.join('-')}`);
 }
+/** Why session end saved no flow, as reported on the `flow_recorded` step. */
+export const DriveFlowSkipReason = {
+    /** The drive declared no consequence, so a saved flow could never go red. */
+    NO_DECLARED_CONSEQUENCE: 'no_declared_consequence',
+    /** What it proved rested on network mocks the flow would not carry (#1459). */
+    DRIVEN_UNDER_NETWORK_MOCKS: 'driven_under_network_mocks',
+};
 /**
  * Turn this session's ambient tape into a flow, when it is worth one.
  *
@@ -143,24 +150,48 @@ function typesASecret(step) {
     const field = QueryBy.TESTID === by ? step.args['value'] : step.args['name'];
     return 'string' === typeof field && defaultIsSensitiveKey(field);
 }
+/**
+ * The tape without the attempts an agent made again. An action that declared nothing, followed at
+ * once by the same action on the same control that did, is a retry: saved, the flow clicked sign-in
+ * twice, the second click found no form, and every replay of it failed. A step repeated with the
+ * same declaration both times (a double submit on purpose) is two steps, and stays two.
+ */
+function withoutRetries(steps) {
+    return steps.filter((step, i) => {
+        const next = steps[i + 1];
+        if (next === undefined || step.expect !== undefined || next.expect === undefined)
+            return true;
+        // Tried again where it was tried: a page later it is a step of the journey, not a retry.
+        if (step.route !== next.route || step.page !== next.page || step.mocked !== next.mocked)
+            return true;
+        const { expect: _declared, ...again } = next.args;
+        const { expect: _none, ...first } = step.args;
+        return step.tool !== next.tool || JSON.stringify(first) !== JSON.stringify(again);
+    });
+}
 /** A flow per journey, so two journeys in one session are two regression tests rather than one. */
 export function driveFlowsFrom(tape) {
     if (tape === undefined || 0 === tape.steps.length)
         return { programs: [], outcome: {} };
     const programs = [];
     let unproven = 0;
-    for (const segment of segmentsByRoute(tape.steps)) {
+    let mocked = 0;
+    for (const segment of segmentsByRoute(withoutRetries(tape.steps))) {
         if (!carriesAnAssertion(segment.steps)) {
             unproven += segment.steps.length;
             continue;
         }
+        if (segment.steps.some((step) => true === step.mocked)) {
+            mocked += segment.steps.length;
+            continue;
+        }
         const startPath = segment.route ?? tape.startPath;
         programs.push({
             name: driveFlowName(startPath, segment.steps),
             version: REPLAY_PROGRAM_VERSION,
             // The route is recorder-internal and has no business on disk — `startPath` is where the
             // on-disk flow says the same thing, in the field replay actually reads.
-            steps: segment.steps.map(({ route: _route, ...step }) => step),
+            steps: segment.steps.map(({ route: _route, mocked: _mocked, ...step }) => step),
             ...(startPath === undefined ? {} : { startPath }),
         });
     }
@@ -169,6 +200,7 @@ export function driveFlowsFrom(tape) {
         outcome: {
             ...(0 === programs.length ? {} : { saved: programs.map((p) => p.name) }),
             ...(0 === unproven ? {} : { unprovenSteps: unproven }),
+            ...(0 === mocked ? {} : { mockedSteps: mocked }),
         },
     };
 }

package/dist/memory/journal/drive-run-flush.d.ts

@@ -26,6 +26,8 @@ export interface FlushableSession {
 export interface DriveRunFlushDeps<S extends FlushableSession> {
     /** Find the live session a verdict came from, or undefined when it has already gone. */
     resolve: (sessionId: string) => S | undefined;
+    /** Every live session: a Harness note rewrites them all, since it does not say which tab drove. */
+    all?: () => readonly S[];
     /** Write this session's run artifact. The same call teardown makes. */
     write: (session: S) => Promise<void>;
     /** Injected so the test does not wait three real seconds. */

package/dist/memory/journal/drive-run-flush.js

@@ -20,8 +20,9 @@
  * the last verdicts of a session are the ones somebody is waiting on.
  */
 import { HookEvent } from '@reticlehq/core/hooks';
-import { onHook } from '../../hooks/hook-bus.js';
+import { onHook, onPendingWrites } from '../../hooks/hook-bus.js';
 import { log } from '../../log.js';
+import { onHarnessNoted } from '../../judgement/runs/drive-run.js';
 /** Long enough to collapse a burst of verdicts, short enough that a human reads it as "live". */
 const FLUSH_DEBOUNCE_MS = 3_000;
 /**
@@ -55,10 +56,7 @@ export function attachDriveRunFlush(deps) {
             log(`drive run flush failed: ${message}`);
         }
     };
-    const off = onHook(HookEvent.VERDICT, (payload) => {
-        const sessionId = 'sessionId' in payload ? payload.sessionId : undefined;
-        if (sessionId === undefined)
-            return;
+    const schedule = (sessionId) => {
         const existing = pending.get(sessionId);
         if (existing !== undefined)
             clearTimeout(existing);
@@ -69,11 +67,28 @@ export function attachDriveRunFlush(deps) {
         // obligation, and holding the process open for it would make `reticle` feel broken on exit.
         timer.unref?.();
         pending.set(sessionId, timer);
+    };
+    const off = onHook(HookEvent.VERDICT, (payload) => {
+        const sessionId = 'sessionId' in payload ? payload.sessionId : undefined;
+        if (sessionId !== undefined)
+            schedule(sessionId);
     });
+    // A Harness drive is graded after its last verdict: rewrite the runs so the grade reaches them.
+    // ponytail: every live session, since a note names a drive, not a tab; drives end rarely.
+    const offNoted = onHarnessNoted(() => {
+        for (const session of deps.all?.() ?? [])
+            schedule(session.id);
+    });
+    const flushAll = async () => {
+        await Promise.all([...pending.keys()].map(flush));
+    };
+    const unregister = onPendingWrites(flushAll);
     return {
         flushNow: flush,
         stop: () => {
             off();
+            unregister();
+            offNoted();
             for (const timer of pending.values())
                 clearTimeout(timer);
             pending.clear();

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

@@ -1,6 +1,7 @@
-import { EventAttribution, JOURNAL_FILE_VERSION, } from '@reticlehq/core';
+import { ActionType, EventAttribution, REDACTED_VALUE, JOURNAL_FILE_VERSION, } from '@reticlehq/core';
 import { isSelfObservation } from './self-observation.js';
 import { currentDrivenBy } from '../../hooks/driven-by.js';
+import { callerClientName } from '../../hooks/coding-agents.js';
 import { log } from '../../log.js';
 /**
  * Logged the FIRST time a journal write is lost, and never again for that recorder.
@@ -13,6 +14,36 @@ import { log } from '../../log.js';
  * produce one line per batch.
  */
 const JOURNAL_WRITE_LOST = 'journal_write_lost';
+/** The actions whose arguments carry what was typed. */
+const TYPING_ACTIONS = new Set([ActionType.FILL, ActionType.TYPE]);
+const TYPED_KEYS = ['value', 'text'];
+/**
+ * The arguments as the journal keeps them: every typed value replaced, at any depth (a sequence's
+ * steps too). A fill's arguments kept a typed password in clear in `actions.jsonl`; the page cannot
+ * tell the daemon which field was secret before the call is written, and nothing reads a typed value
+ * back from the journal — the run fold reads the ref, the target and the action — so none is kept.
+ */
+function withoutTypedInput(args) {
+    if (Array.isArray(args))
+        return args.map(withoutTypedInput);
+    if ('object' !== typeof args || null === args)
+        return args;
+    const record = args;
+    const typing = TYPING_ACTIONS.has(String(record['action']));
+    const out = {};
+    for (const [key, value] of Object.entries(record)) {
+        const typed = typing && TYPED_KEYS.includes(key) && 'string' === typeof value;
+        out[key] = typed ? REDACTED_VALUE : withoutTypedInput(value);
+    }
+    if (typing && 'object' === typeof record['args'] && null !== record['args']) {
+        const inner = { ...record['args'] };
+        for (const key of TYPED_KEYS)
+            if ('string' === typeof inner[key])
+                inner[key] = REDACTED_VALUE;
+        out['args'] = inner;
+    }
+    return out;
+}
 const DEFAULT_FLUSH_AT = 64;
 /**
  * Owns action-window attribution and batched, order-preserving journaling — the durable half of the
@@ -66,7 +97,14 @@ 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(), drivenBy: currentDrivenBy() };
+        this.#active = {
+            actionId,
+            tool,
+            args: withoutTypedInput(args),
+            tStart: this.#now(),
+            drivenBy: currentDrivenBy(),
+            agent: callerClientName(),
+        };
     }
     /** Close the active window: persist its buffered events, then the action record. No-op if none active. */
     finishAction(effect, settled, settledInMs) {
@@ -88,6 +126,7 @@ export class JournalRecorder {
             tRange: { from: active.tStart, to: this.#now() },
             at: active.tStart,
             ...(active.drivenBy === undefined ? {} : { drivenBy: active.drivenBy }),
+            ...(active.agent === undefined ? {} : { agent: active.agent }),
         };
         this.#enqueueFlush();
         this.#chain = this.#chain
@@ -117,7 +156,7 @@ export class JournalRecorder {
             v: JOURNAL_FILE_VERSION,
             actionId,
             tool,
-            args,
+            args: withoutTypedInput(args),
             effect,
             // No window was opened, so no event carries this id: `seqRange` is omitted rather than
             // invented, because any range here would claim an attribution that never happened. `tRange` is
@@ -129,6 +168,10 @@ export class JournalRecorder {
                 const by = currentDrivenBy();
                 return by === undefined ? {} : { drivenBy: by };
             })(),
+            ...(() => {
+                const agent = callerClientName();
+                return agent === undefined ? {} : { agent };
+            })(),
         };
         this.#enqueueFlush();
         this.#chain = this.#chain

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

@@ -13,6 +13,11 @@ export declare const DEFAULT_DIFF_RETENTION = 10;
 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;
+/**
+ * Keep the step screenshots of at most this many runs. A run's are looked at while it is fresh, or
+ * on the platform it was synced to; the byte budget below is what bounds a single long one.
+ */
+export declare const DEFAULT_STEP_SHOT_RUN_RETENTION = 50;
 /**
  * The TOTAL the evidence tier of one `.reticle/` may occupy, across sessions, runs, overlay diffs
  * and feedback copies together.

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

@@ -1,5 +1,5 @@
 import { basename, join } from 'node:path';
-import { ReticleDir } from '@reticlehq/core';
+import { ReticleDir, STEP_SCREENSHOT } from '@reticlehq/core';
 import { reticleDirPaths, visualDir } from '../../project/dir/reticle-dir.js';
 import { EVIDENCE_DIRS } from './workspace-tiers.js';
 /** Keep at most this many session journals on disk; older ones are pruned by recency. */
@@ -16,6 +16,11 @@ export const DEFAULT_DIFF_RETENTION = 10;
 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;
+/**
+ * Keep the step screenshots of at most this many runs. A run's are looked at while it is fresh, or
+ * on the platform it was synced to; the byte budget below is what bounds a single long one.
+ */
+export const DEFAULT_STEP_SHOT_RUN_RETENTION = 50;
 const DIFF_SUFFIX = '.diff.png';
 const PNG_SUFFIX = '.png';
 /**
@@ -173,7 +178,12 @@ export async function pruneVisualDiffs(fs, root, retention = DEFAULT_DIFF_RETENT
     for (const dir of await visualDirs(fs, root)) {
         await pruneByRecency(fs, dir, retention, isDiff);
     }
+    // Step screenshots are evidence of one run each, read in the minutes after it or synced with it;
+    // the oldest runs' directories go whole.
+    await pruneByRecency(fs, stepShotRunsDir(root), DEFAULT_STEP_SHOT_RUN_RETENTION);
 }
+/** `visual/runs/`, the parent of every run's step screenshots. */
+const stepShotRunsDir = (root) => join(root, ReticleDir.VISUAL_SUBDIR, STEP_SCREENSHOT.RUNS_DIR);
 /** `visual/` plus its per-runtime subdirectories. Empty when nothing has been captured yet. */
 async function visualDirs(fs, root) {
     const top = visualDir(root);
@@ -181,7 +191,8 @@ async function visualDirs(fs, root) {
     try {
         // A per-runtime subdirectory is anything here that is not itself a PNG.
         for (const entry of await fs.readdir(top)) {
-            if (!entry.endsWith(PNG_SUFFIX))
+            // `runs/` holds step screenshots, not baselines, and is bounded on its own.
+            if (!entry.endsWith(PNG_SUFFIX) && STEP_SCREENSHOT.RUNS_DIR !== entry)
                 dirs.push(join(top, entry));
         }
     }
@@ -230,6 +241,20 @@ async function collectEvidence(fs, root) {
     for (const under of EVIDENCE_DIRS) {
         const isVisual = ReticleDir.VISUAL_SUBDIR === under;
         const dirs = isVisual ? await visualDirs(fs, root) : [join(root, under)];
+        // Each run's step screenshots are one evidence entry, evicted whole, oldest first.
+        if (isVisual) {
+            const runs = stepShotRunsDir(root);
+            for (const name of await fs.readdir(runs).catch(() => [])) {
+                const path = join(runs, name);
+                try {
+                    const { mtimeMs } = await fs.stat(path);
+                    entries.push({ path, under, sizeBytes: await sizeOf(fs, path), mtimeMs });
+                }
+                catch {
+                    /* unreadable entry — skip */
+                }
+            }
+        }
         for (const dir of dirs) {
             let names;
             try {

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

@@ -56,6 +56,8 @@ export const WORKSPACE_TIERS = {
     [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,
+    // How to target this app, learned from corrected failures: a teammate's agent needs it too.
+    [ReticleDir.APP_NOTES_FILE]: sharedFile,
     [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,

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 { driveRunId, driveRunsFrom } 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,6 +174,7 @@ export async function recordDriveRun(deps, session) {
     if (session.readJournalActions === undefined)
         return;
     const actions = await session.readJournalActions();
+    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
@@ -180,7 +182,11 @@ export async function recordDriveRun(deps, session) {
         // 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 (0 === inputs.length)
         return;
@@ -196,13 +202,18 @@ 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 });
+    const clock = deps.now ?? (() => Date.now());
     for (const input of inputs) {
-        await store.write(buildVerificationRun({ ...input, ...(subject === undefined ? {} : { subject }) }, deps.now ?? (() => Date.now())));
+        // 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. */
@@ -212,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.
@@ -228,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 }),
     });
 }
 /**
@@ -249,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.js

@@ -18,7 +18,7 @@
  * what lets a test say "these are the projects on this machine" without one.
  */
 import { existsSync, readFileSync, readdirSync } from 'node:fs';
-import { dirname, join } from 'node:path';
+import { dirname, isAbsolute, join, relative } from 'node:path';
 import { homedir } from 'node:os';
 import { PROJECT_REGISTRY_FILE, emptyProjectRegistry, parseProjectRegistry, } from '@reticlehq/core/artifacts';
 import { DevServerEntrySchema, ReticleDir, ReticleEnv, devServerRegistryPort, } from '@reticlehq/core';
@@ -60,7 +60,19 @@ function daemonSitsInAProject(daemonRoot) {
  */
 function daemonOwnProjectId(daemonRoot, candidates) {
     const directory = dirname(daemonRoot);
-    return candidates.find((candidate) => candidate.directory === directory)?.projectId;
+    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
@@ -150,6 +162,16 @@ export function artifactRootResolver(daemonRoot, deps) {
     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 known = candidates();
         let resolved = resolveArtifactRoot({ projectId, candidates: known, daemonRoot });
@@ -161,7 +183,7 @@ export function artifactRootResolver(daemonRoot, deps) {
                 projectId,
                 candidates: known,
                 daemonRoot,
-                servingDirectory: servingDirectory(origin),
+                servingDirectory: servingOf(origin),
             });
         }
         if (resolved.reason === ArtifactRootReason.MATCHED_PROJECT)
@@ -182,7 +204,9 @@ export function artifactRootResolver(daemonRoot, deps) {
             // 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
@@ -190,8 +214,12 @@ export function artifactRootResolver(daemonRoot, deps) {
                 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';
 /**
@@ -60,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.
@@ -79,8 +82,7 @@ export declare function projectCandidatesFrom(discovery: ConfigDiscovery, regist
     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";
+export { UNMATCHED_SUBDIR };
 /**
  * The fallback root for a session whose project could not be resolved.
  *
@@ -143,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 { 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.
@@ -130,8 +131,7 @@ export function projectCandidatesFrom(discovery, registry, devServers = []) {
         : [{ 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';
 /**

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

@@ -41,6 +41,15 @@ export interface ReticleDirPaths {
     plans: string;
 }
 export declare function reticleDirPaths(root: string): ReticleDirPaths;
+/**
+ * A Harness drive's own record beside its run —.reticle/runs/<runId>.drive.json. Not a run: every
+ * reader that counts or syncs run files skips it.
+ */
+export declare const DRIVE_RECORD_SUFFIX = ".drive.json";
+/** Where evidence goes when no project could be named: `~/.reticle/unmatched/<id>`. */
+export declare const UNMATCHED_SUBDIR = "unmatched";
+/** Whether a root is one of those buckets: evidence from a page that never said its project. */
+export declare function isUnmatchedRoot(root: string): boolean;
 /** The verification-run artifact path for `runId`.reticle/runs/<runId>.json). */
 export declare function runPath(root: string, runId: RunId): string;
 /** The journal directory for `sessionId` (.reticle/sessions/<id>). Guard the id first. */
@@ -88,6 +97,11 @@ export declare function visualPath(root: string, name: string, runtime?: string)
  * every pre-existing baseline came from a driven browser, and moving them would orphan them.
  */
 export declare function visualDir(root: string, runtime?: string): string;
+/**
+ * Where one run's step screenshots live: `.reticle/visual/runs/<runId>/`. Throws on an unsafe run id,
+ * like every other path built from one.
+ */
+export declare function stepShotDir(root: string, runId: string): string;
 /** The overlay-diff PNG path for `name`.reticle/visual/<name>.diff.png). */
 export declare function visualDiffPath(root: string, name: string, runtime?: string): string;
 /**

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

@@ -1,6 +1,6 @@
-import { dirname, join } from 'node:path';
+import { basename, dirname, join } from 'node:path';
 import { realmOf } from '@reticlehq/core';
-import { CONTRACT_FILE_VERSION, ContractFileSchema, ContractReadError, FLOW_NAME_PATTERN, SAFE_SEGMENT_PATTERN, ReticleDir, } from '@reticlehq/core';
+import { CONTRACT_FILE_VERSION, ContractFileSchema, ContractReadError, FLOW_NAME_PATTERN, SAFE_SEGMENT_PATTERN, ReticleDir, STEP_SCREENSHOT, } from '@reticlehq/core';
 export function reticleDirPaths(root) {
     return {
         root,
@@ -24,6 +24,18 @@ export function reticleDirPaths(root) {
         plans: join(root, ReticleDir.PLANS_SUBDIR),
     };
 }
+/**
+ * A Harness drive's own record beside its run —.reticle/runs/<runId>.drive.json. Not a run: every
+ * reader that counts or syncs run files skips it.
+ */
+export const DRIVE_RECORD_SUFFIX = '.drive.json';
+/** Where evidence goes when no project could be named: `~/.reticle/unmatched/<id>`. */
+export const UNMATCHED_SUBDIR = 'unmatched';
+/** Whether a root is one of those buckets: evidence from a page that never said its project. */
+export function isUnmatchedRoot(root) {
+    const parent = dirname(root);
+    return UNMATCHED_SUBDIR === basename(parent) && ReticleDir.ROOT === basename(dirname(parent));
+}
 /** The verification-run artifact path for `runId`.reticle/runs/<runId>.json). */
 export function runPath(root, runId) {
     return join(root, ReticleDir.RUNS_SUBDIR, `${runId}.json`);
@@ -92,6 +104,15 @@ export function visualDir(root, runtime) {
         ? join(visual, runtime)
         : visual;
 }
+/**
+ * Where one run's step screenshots live: `.reticle/visual/runs/<runId>/`. Throws on an unsafe run id,
+ * like every other path built from one.
+ */
+export function stepShotDir(root, runId) {
+    if (!isValidRunId(runId))
+        throw new Error(`invalid run id: ${JSON.stringify(runId)}`);
+    return join(root, ReticleDir.VISUAL_SUBDIR, STEP_SCREENSHOT.RUNS_DIR, runId);
+}
 /** The overlay-diff PNG path for `name`.reticle/visual/<name>.diff.png). */
 export function visualDiffPath(root, name, runtime) {
     return join(visualDir(root, runtime), `${name}.diff.png`);