@reticlehq/server 3.4.0 → 3.6.0

package/dist/memory/intent/intent-shard.d.ts

@@ -252,7 +252,6 @@ export declare const IntentShardSchema: z.ZodObject<{
     }>>;
 }, "strip", z.ZodTypeAny, {
     version: 1;
-    subject: string;
     intents: Record<string, {
         status: "proved" | "proposed" | "agreed" | "stale";
         state: "proved" | "declared" | "bound";
@@ -279,9 +278,9 @@ export declare const IntentShardSchema: z.ZodObject<{
             statement: string;
         }[] | undefined;
     }>;
+    subject: string;
 }, {
     version: 1;
-    subject: string;
     intents: Record<string, {
         status: "proved" | "proposed" | "agreed" | "stale";
         state: "proved" | "declared" | "bound";
@@ -308,6 +307,7 @@ export declare const IntentShardSchema: z.ZodObject<{
             statement: string;
         }[] | undefined;
     }>;
+    subject: string;
 }>;
 export type IntentShard = z.infer<typeof IntentShardSchema>;
 export declare const IntentIndexSchema: z.ZodObject<{

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: [
@@ -70,8 +75,11 @@ export const INTENT_TOOLS = [
                 })
                     .optional(),
             }))
+                // Non-empty in the schema too, so the advertised contract says what `declare` enforces.
+                .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`.
@@ -153,9 +161,18 @@ export const INTENT_TOOLS = [
                 return { intents: await store.open() };
             }
             const raw = args['intents'];
-            const entries = Array.isArray(raw)
-                ? raw
-                : [];
+            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) {
+                throw new Error(`${ReticleTool.INTENT} declare: \`intents\` must be a non-empty array of { id, statement }, got ${raw === undefined ? 'nothing' : JSON.stringify(raw)} — nothing was stored`);
+            }
+            const entries = raw;
             const declared = await store.declare(entries);
             // Said, not swallowed: an agent that declared something and finds nothing stored would
             // otherwise conclude the ledger lost it.
@@ -166,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

@@ -101,50 +101,50 @@ export declare const RouteEnvelopeSchema: z.ZodObject<{
             max: number;
         }>;
     }, "strip", z.ZodTypeAny, {
-        durationMs: {
+        net: {
             count: number;
             mean: number;
             m2: number;
             max: number;
         };
-        net: {
+        durationMs: {
             count: number;
             mean: number;
             m2: number;
             max: number;
         };
-        netErrors: {
+        consoleErrors: {
             count: number;
             mean: number;
             m2: number;
             max: number;
         };
-        consoleErrors: {
+        netErrors: {
             count: number;
             mean: number;
             m2: number;
             max: number;
         };
     }, {
-        durationMs: {
+        net: {
             count: number;
             mean: number;
             m2: number;
             max: number;
         };
-        net: {
+        durationMs: {
             count: number;
             mean: number;
             m2: number;
             max: number;
         };
-        netErrors: {
+        consoleErrors: {
             count: number;
             mean: number;
             m2: number;
             max: number;
         };
-        consoleErrors: {
+        netErrors: {
             count: number;
             mean: number;
             m2: number;
@@ -155,25 +155,25 @@ export declare const RouteEnvelopeSchema: z.ZodObject<{
     route: string;
     samples: number;
     stats: {
-        durationMs: {
+        net: {
             count: number;
             mean: number;
             m2: number;
             max: number;
         };
-        net: {
+        durationMs: {
             count: number;
             mean: number;
             m2: number;
             max: number;
         };
-        netErrors: {
+        consoleErrors: {
             count: number;
             mean: number;
             m2: number;
             max: number;
         };
-        consoleErrors: {
+        netErrors: {
             count: number;
             mean: number;
             m2: number;
@@ -184,25 +184,25 @@ export declare const RouteEnvelopeSchema: z.ZodObject<{
     route: string;
     samples: number;
     stats: {
-        durationMs: {
+        net: {
             count: number;
             mean: number;
             m2: number;
             max: number;
         };
-        net: {
+        durationMs: {
             count: number;
             mean: number;
             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-query.d.ts

@@ -62,5 +62,19 @@ export declare function readQueryEvents(reader: JournalReader | undefined, buffe
  * "nothing was lost" — see `JournalReader.readWriteLoss`.
  */
 export declare function readJournalWriteLoss(reader: JournalReader | undefined, buffer: QueryBuffer): Promise<JournalWriteLoss | undefined>;
+/** The slice of the ring buffer `windowLost` reads. `RingBuffer` satisfies it structurally. */
+export interface LossBuffer {
+    lostSince(cursor: number): boolean;
+}
+/**
+ * Did the EVENT STORE lose scarce evidence from a window opened at `cursor`? The input to whether a
+ * verdict's capture was clean — see `RingBuffer.lostSince`, and never the raw drop counter, which
+ * moves for the age and churn evictions that every live page produces continuously. The journal is
+ * the other half of that store, so a durable read that could not reach back to `cursor` lost
+ * exactly what an eviction would have. Both boundaries are INCLUSIVE (`t` is a millisecond many
+ * records share) and an absent `lostThroughT` impeaches every window rather than none — the
+ * conservative direction, both times.
+ */
+export declare function windowLost(reader: JournalReader | undefined, buffer: LossBuffer, cursor: number): boolean;
 /** Apply since/until/actionId bounds to an event list. */
 export declare function filterEvents(events: readonly ReticleEvent[], options: EventQueryOptions): ReticleEvent[];

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

@@ -90,6 +90,21 @@ export async function readJournalWriteLoss(reader, buffer) {
         return undefined;
     return (await reader?.readWriteLoss?.()) ?? undefined;
 }
+/**
+ * Did the EVENT STORE lose scarce evidence from a window opened at `cursor`? The input to whether a
+ * verdict's capture was clean — see `RingBuffer.lostSince`, and never the raw drop counter, which
+ * moves for the age and churn evictions that every live page produces continuously. The journal is
+ * the other half of that store, so a durable read that could not reach back to `cursor` lost
+ * exactly what an eviction would have. Both boundaries are INCLUSIVE (`t` is a millisecond many
+ * records share) and an absent `lostThroughT` impeaches every window rather than none — the
+ * conservative direction, both times.
+ */
+export function windowLost(reader, buffer, cursor) {
+    if (buffer.lostSince(cursor))
+        return true;
+    const lost = reader?.readLoss?.();
+    return lost !== undefined && (lost.lostThroughT === undefined || lost.lostThroughT >= cursor);
+}
 /** Apply since/until/actionId bounds to an event list. */
 export function filterEvents(events, options) {
     return events.filter((event) => (options.since === undefined || event.t >= options.since) &&

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,3 +1,38 @@
+import { type ProjectCandidate } from '@reticlehq/core/artifacts';
 import { type ProjectId } from '@reticlehq/core';
 import { type ArtifactRoot } from './artifact-root.js';
-export declare function artifactRootResolver(daemonRoot: string): (projectId: ProjectId | undefined, origin?: string) => ArtifactRoot;
+/**
+ * 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.
+ *
+ * A daemon is shared: started from `$HOME`, a monorepo root, or another project's MCP client, its
+ * cwd is often not the app that sent the HELLO. The version-skew remedy read `package.json` from
+ * cwd anyway, so it fell back to the generic sensor package and told a Next.js project to install
+ * `@reticlehq/browser` (#1135). This is the same lookup the artifact root uses, keyed by the page's
+ * own project id.
+ */
+export declare function projectDirectoryFor(projectId: string | undefined): string | undefined;
+/** 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;