@reticlehq/server 2.12.0 → 2.13.0

package/dist/init/vite-config.js

@@ -8,30 +8,38 @@ import { PatchKind } from './patch-kind.js';
 export const VITE_IMPORT = "import { reticle } from '@reticlehq/vite-plugin';";
 const RETICLE_MARKER = '@reticlehq/vite-plugin';
 /**
- * The `reticle(...)` call — the bridge port so the injected connect targets it, and body capture.
+ * The `reticle(...)` call — the bridge port so the injected connect targets it.
  *
- * `captureNetworkBodies` is here rather than in the SDK's defaults, deliberately. Without it a write
- * that answers 2xx with a body nobody recorded grades `unknown / outcome_unread`, because a 200
- * describes the transport and not the result — so the single bug class this product exists to catch is
- * unreachable on a default install. Measured on a real payments UI: a refund posted rupees into a
- * paise field, the server answered 200 having refunded a hundredth of it, the page rendered the amount
- * the user had typed rather than the amount that came back, and every DOM-level check passed. An agent
- * asked to verify that flow had to edit the app's own vite config mid-task to see the payload, and
- * then tell its human to undo the edit.
+ * **`captureNetworkBodies` is OPT-IN.** It was written in by default, and the argument for that was
+ * a good one: without a body, a write that answers 2xx grades `unknown / outcome_unread`, because a
+ * 200 describes the transport and not the result. Measured on a real payments UI — a refund posted
+ * rupees into a paise field, the server answered 200 having refunded a hundredth of it, the page
+ * rendered the amount the user had typed, and every DOM-level check passed.
  *
- * Written into the USER'S config, not switched on inside the SDK, and the difference is the point. A
- * body is the one part of a request that routinely carries personal data: the credential classes are
- * redacted before anything is journalled — tokens, cookies, card numbers, cvv, ssn — but an address or
- * an email is not, and nothing here should decide that for someone silently. In the config it is one
- * visible line they can read, keep, or delete, and an SDK that updates underneath them never starts
- * recording more than it did yesterday.
+ * That argument justifies the CAPABILITY. It does not justify the default, and the distinction is
+ * what #705 is about. A healthcare workspace proxying authenticated API traffic through Vite ran
+ * `init`, and on the first drive their login tokens and patient payloads were in the daemon's
+ * buffer. The old comment here conceded the exact gap — "the credential classes are redacted ... but
+ * an address or an email is not, and nothing here should decide that for someone silently" — and
+ * then decided it for them, because writing the line into their config IS deciding. `init` is run
+ * unattended by an agent; the person who knows the data is sensitive is not in the room.
+ *
+ * So the default is off and the ways in are all deliberate:
+ *   - `reticle init --capture-bodies` writes the line, for someone who has decided
+ *   - `VITE_RETICLE_CAPTURE_BODIES=1` turns it on for ONE dev-server run, no config edit
+ *   - adding the option by hand, which is what the tools tell you to do
+ *
+ * Nothing goes quiet in exchange. Every tool that needs a body already says so when it is missing
+ * and names the option — see honesty/uncaptured-bodies.ts, honesty/verified.ts, predicate-eval.ts
+ * and reconcile-tools.ts — so the capability is discovered at the moment it is wanted, by the person
+ * who wanted it, instead of being switched on before anyone has asked.
  */
-function reticlePluginCall(port) {
+function reticlePluginCall(port, captureBodies) {
     const options = [
         ...(port === undefined ? [] : [`port: ${String(port)}`]),
-        'captureNetworkBodies: true',
+        ...(captureBodies ? ['captureNetworkBodies: true'] : []),
     ];
-    return `reticle({ ${options.join(', ')} })`;
+    return 0 === options.length ? 'reticle()' : `reticle({ ${options.join(', ')} })`;
 }
 /** Matches the start of a `plugins: [` array literal. */
 const PLUGINS_ARRAY = /plugins\s*:\s*\[/;
@@ -66,35 +74,41 @@ function insertImport(source) {
  * what a formatter rewrites, turning a one-line install into a diff against the user's own style. A
  * single-line array needs the space, or the result reads `[reticle(),react()]`.
  */
-function insertPlugin(source, port) {
+function insertPlugin(source, port, captureBodies) {
     return source.replace(PLUGINS_ARRAY, (match, _g, offset) => {
         const next = source[offset + match.length] ?? '';
         const separator = '' === next || /\s/.test(next) ? '' : ' ';
-        return `${match}${reticlePluginCall(port)},${separator}`;
+        return `${match}${reticlePluginCall(port, captureBodies)},${separator}`;
     });
 }
 /**
  * Add a whole `plugins: [reticle()]` key to a config object that has none, matching the layout of
  * the object it lands in: a multi-line object gets its own indented line, a one-liner stays inline.
  */
-function insertPluginsKey(source, port) {
+function insertPluginsKey(source, port, captureBodies) {
     return source.replace(CONFIG_OBJECT, (_match, prefix, offset) => {
         const rest = source.slice(offset + _match.length);
         const multiline = /^\s*\n/.test(rest);
         const indent = /^\s*\n(\s*)\S/.exec(rest)?.[1] ?? '  ';
-        const key = `plugins: [${reticlePluginCall(port)}],`;
+        const key = `plugins: [${reticlePluginCall(port, captureBodies)}],`;
         return multiline ? `${prefix}{\n${indent}${key}` : `${prefix}{ ${key}`;
     });
 }
-export function patchViteConfig(source, port) {
+export function patchViteConfig(source, port, captureBodies = false) {
     if (source.includes(RETICLE_MARKER)) {
         return { kind: VitePatchKind.ALREADY };
     }
     if (PLUGINS_ARRAY.test(source)) {
-        return { kind: VitePatchKind.APPLY, code: insertImport(insertPlugin(source, port)) };
+        return {
+            kind: VitePatchKind.APPLY,
+            code: insertImport(insertPlugin(source, port, captureBodies)),
+        };
     }
     if (CONFIG_OBJECT.test(source)) {
-        return { kind: VitePatchKind.APPLY, code: insertImport(insertPluginsKey(source, port)) };
+        return {
+            kind: VitePatchKind.APPLY,
+            code: insertImport(insertPluginsKey(source, port, captureBodies)),
+        };
     }
     return { kind: VitePatchKind.MANUAL, reason: NO_PLUGINS_REASON };
 }

package/dist/init/workspace-apps.d.ts

@@ -1,16 +1,14 @@
+import type { InitIo } from './run.js';
 /**
- * Which directories to look in for the app, when `reticle init` runs at a monorepo root.
+ * The file names that say what a directory IS, shared by everything that has to ask.
  *
- * This used to be the literal list `['apps', 'packages']`. Measured on a real repo with three Next
- * apps at `web/`, `admin/` and `space/`, it found none — so the redirect never fired, init ran
- * against the root, and it reported ✓ for writing `app/reticle-dev.tsx` into a directory Next never
- * compiles. A ⚠ tells a human to act; a ✓ tells them it is handled.
- *
- * A workspace DECLARES its packages, so that declaration is used first and directory names are not
- * guessed at all. Where nothing is declared, every top-level directory is a better candidate than two
- * hardcoded ones — filtered by the usual non-source suspects, and still subject to the `looksLikeApp`
- * check that follows, so a wrong guess here costs a `package.json` read.
+ * They lived in run.ts and are read from here now because `findWorkspaceApps` moved and needs them —
+ * one definition, imported in both directions of the question ("is this an app?" and "which app?").
  */
+export declare const PACKAGE_JSON = "package.json";
+export declare const PNPM_WORKSPACE = "pnpm-workspace.yaml";
+export declare const VITE_CONFIG_CANDIDATES: string[];
+export declare const NEXT_CONFIG_CANDIDATES: string[];
 interface WorkspaceSources {
     /** Raw contents of pnpm-workspace.yaml, when present. */
     pnpmWorkspace?: string;
@@ -20,4 +18,13 @@ interface WorkspaceSources {
     topLevelDirs?: readonly string[];
 }
 export declare function workspaceParents(sources: WorkspaceSources): string[];
+/**
+ * App directories under a workspace root.
+ *
+ * Running `reticle init` at the repo root is what people actually do, and in a monorepo the app is a
+ * directory down — so init detected "no framework", printed a wall of manual HTML instructions, and
+ * would have installed the SDK into the ROOT package.json. It already walks UP for the lockfile, so
+ * it knows it is in a workspace; this is the matching walk DOWN.
+ */
+export declare function findWorkspaceApps(io: Pick<InitIo, 'exists' | 'readFile' | 'listDirs'>): string[];
 export {};

package/dist/init/workspace-apps.js

@@ -1,3 +1,24 @@
+import { DEV_SCRIPT_NAMES } from './dev-script.js';
+/**
+ * The file names that say what a directory IS, shared by everything that has to ask.
+ *
+ * They lived in run.ts and are read from here now because `findWorkspaceApps` moved and needs them —
+ * one definition, imported in both directions of the question ("is this an app?" and "which app?").
+ */
+export const PACKAGE_JSON = 'package.json';
+export const PNPM_WORKSPACE = 'pnpm-workspace.yaml';
+export const VITE_CONFIG_CANDIDATES = [
+    'vite.config.ts',
+    'vite.config.js',
+    'vite.config.mjs',
+    'vite.config.mts',
+];
+export const NEXT_CONFIG_CANDIDATES = [
+    'next.config.mjs',
+    'next.config.js',
+    'next.config.ts',
+    'next.config.cjs',
+];
 /**
  * Which directories to look in for the app, when `reticle init` runs at a monorepo root.
  *
@@ -66,3 +87,92 @@ export function workspaceParents(sources) {
         : (sources.topLevelDirs ?? []).filter((d) => !d.startsWith('.') && !NEVER_A_PACKAGE.has(d));
     return [...new Set(candidates)];
 }
+/**
+ * Which directories under this workspace are runnable apps.
+ *
+ * Moved here from run.ts, which was over the 1000-line cap and had carried a note saying it was at
+ * its cohesion limit. `library-path-boundary.test.ts` had already written down that this function
+ * "squats in init/ for historical reasons" — it is a general-purpose question about a repository's
+ * shape, next to `workspaceParents`, which answers the other half of it.
+ */
+/** Deps that mark a directory as a runnable web app even when it has no bundler config file. */
+const APP_DEPS = ['next', 'vite'];
+function hasDevScript(pkgRaw) {
+    try {
+        const parsed = JSON.parse(pkgRaw);
+        const scripts = 'object' === typeof parsed && parsed !== null
+            ? parsed.scripts
+            : undefined;
+        if ('object' !== typeof scripts || null === scripts)
+            return false;
+        const named = scripts;
+        return DEV_SCRIPT_NAMES.some((n) => 'string' === typeof named[n] && '' !== named[n]);
+    }
+    catch {
+        // A manifest that will not parse says nothing either way, and this is a filter, not a verdict.
+        return false;
+    }
+}
+function looksLikeApp(dir, io) {
+    const pkgRaw = io.readFile(`${dir}/${PACKAGE_JSON}`);
+    if (null === pkgRaw)
+        return false;
+    const configs = [...VITE_CONFIG_CANDIDATES, ...NEXT_CONFIG_CANDIDATES];
+    if (configs.some((c) => io.exists(`${dir}/${c}`)))
+        return true;
+    // `next.config` is optional in Next, so the dependency list is the other half of the signal.
+    if (APP_DEPS.some((d) => pkgRaw.includes(`"${d}"`)))
+        return true;
+    // And the honest third: an app somebody can SERVE. Asking only for a bundler missed every app
+    // built on anything else — Remix, Astro, a plain node server — and in a monorepo missing it means
+    // init never redirects, wires the ROOT, and reports ✓ for files nothing compiles.
+    //
+    // A monorepo root has no dev script by design, and a package that can only be BUILT is not the app
+    // somebody is working in, so this stays a filter rather than matching every directory.
+    return hasDevScript(pkgRaw);
+}
+/**
+ * App directories under a workspace root.
+ *
+ * Running `reticle init` at the repo root is what people actually do, and in a monorepo the app is a
+ * directory down — so init detected "no framework", printed a wall of manual HTML instructions, and
+ * would have installed the SDK into the ROOT package.json. It already walks UP for the lockfile, so
+ * it knows it is in a workspace; this is the matching walk DOWN.
+ */
+export function findWorkspaceApps(io) {
+    const found = [];
+    // A workspace DECLARES its packages; `['apps','packages']` was a guess that missed a real repo
+    // with three Next apps at web/, admin/ and space/ — and missing them meant init ran against the
+    // root and reported ✓ for a file Next never compiles. See workspace-apps.
+    const pkgRaw = io.readFile(PACKAGE_JSON);
+    let pkgWorkspaces;
+    try {
+        const parsed = null === pkgRaw ? undefined : JSON.parse(pkgRaw);
+        pkgWorkspaces =
+            'object' === typeof parsed && parsed !== null
+                ? parsed.workspaces
+                : undefined;
+    }
+    catch {
+        pkgWorkspaces = undefined;
+    }
+    const parents = workspaceParents({
+        ...(null === io.readFile(PNPM_WORKSPACE)
+            ? {}
+            : { pnpmWorkspace: io.readFile(PNPM_WORKSPACE) ?? '' }),
+        ...(pkgWorkspaces === undefined ? {} : { pkgWorkspaces }),
+        topLevelDirs: io.listDirs('.'),
+    });
+    // A declared parent can itself BE the app (`workspaces: ["web"]`), so check both the directory and
+    // its children rather than assuming one level of nesting.
+    for (const parent of parents) {
+        if (looksLikeApp(parent, io))
+            found.push(parent);
+        for (const name of io.listDirs(parent)) {
+            const dir = `${parent}/${name}`;
+            if (looksLikeApp(dir, io))
+                found.push(dir);
+        }
+    }
+    return [...new Set(found)];
+}

package/dist/input/network-mock-tools.js

@@ -2,6 +2,7 @@ import { z } from 'zod';
 import { CDP_NO_PROVIDER_REASON, CDP_NO_PROVIDER_RECOMMENDATION } from '@reticlehq/core';
 import { ReticleTool } from '../tools/tool-names.js';
 import { sessionIdShape } from '../tools/tool-kit.js';
+import { delayMsSchema, httpStatusSchema } from '../tools/numeric-bounds.js';
 import { asString } from '../tools/tools-helpers.js';
 function mockProvider(deps) {
     const p = deps.realInput;
@@ -13,14 +14,10 @@ const ruleShape = z.object({
         .min(1)
         .describe('Substring the request URL must contain, e.g. "/api/pay".'),
     method: z.string().optional().describe('Optional method filter (GET/POST/…), case-insensitive.'),
-    status: z.number().int().optional().describe('Fulfill with this HTTP status (default 200).'),
+    status: httpStatusSchema.optional().describe('Fulfill with this HTTP status (default 200).'),
     body: z.string().optional().describe('Response body to fulfill with.'),
     contentType: z.string().optional().describe('Response content type (default application/json).'),
-    delayMs: z
-        .number()
-        .int()
-        .optional()
-        .describe('Delay (ms) before fulfilling — simulate a slow API.'),
+    delayMs: delayMsSchema.optional().describe('Delay (ms) before fulfilling — simulate a slow API.'),
     abort: z
         .boolean()
         .optional()

package/dist/input/real-input.js

@@ -302,8 +302,28 @@ export class LaunchedRealInputProvider {
             // No SDK on the page (or it connected already) — the no-session guard in verify reports it.
         }
     }
-    isAvailableFor(sessionUrl) {
+    /**
+     * The page we own, or undefined once it is gone.
+     *
+     * The handle is cached for the life of the provider and Playwright keeps answering `url()` after
+     * the page has closed, so a closed window read as AVAILABLE and every method below threw
+     * "Target page, context or browser has been closed" — the raw Playwright message, surfaced to the
+     * agent as a tool error, on every call for the rest of the run. A dead page is the same fact as no
+     * page, and every caller already handles that. Only an EXPLICIT `true` drops it, matching
+     * `CdpRealInputProvider`'s `isConnected` check: a test fake without the method is assumed live.
+     */
+    #livePage() {
         const page = this.#page;
+        if (page === undefined)
+            return undefined;
+        if (true === page.isClosed?.()) {
+            this.#page = undefined; // never ask a corpse twice
+            return undefined;
+        }
+        return page;
+    }
+    isAvailableFor(sessionUrl) {
+        const page = this.#livePage();
         if (page === undefined)
             return Promise.resolve(false);
         if (page.url() === sessionUrl)
@@ -311,14 +331,14 @@ export class LaunchedRealInputProvider {
         return Promise.resolve(stripVolatile(page.url()) === stripVolatile(sessionUrl));
     }
     perform(_sessionUrl, action, box, args) {
-        const page = this.#page;
+        const page = this.#livePage();
         if (page === undefined)
             return Promise.resolve({ performed: false, center: boxCenter(box) });
         return performGesture(page, action, box, args, this.#sleep);
     }
     /** PNG of the owned page, or undefined before navigate / after dispose. */
     screenshot(_sessionUrl, opts) {
-        const page = this.#page;
+        const page = this.#livePage();
         if (page === undefined)
             return Promise.resolve(undefined);
         return capturePage(page, opts);
@@ -332,7 +352,7 @@ export class LaunchedRealInputProvider {
      * screenshots the whole time; only these two methods were missing.
      */
     async setViewport(_sessionUrl, size) {
-        const page = this.#page;
+        const page = this.#livePage();
         if (page === undefined)
             return false;
         await page.setViewportSize({ width: size.width, height: size.height });
@@ -340,7 +360,7 @@ export class LaunchedRealInputProvider {
     }
     /** Apply network-mock rules to the owned page; false before navigate / after dispose. */
     async setMocks(_sessionUrl, rules) {
-        const page = this.#page;
+        const page = this.#livePage();
         if (page === undefined)
             return false;
         await installNetworkMocks(page, rules);

package/dist/input/scroll-tools.js

@@ -2,6 +2,7 @@ import { z } from 'zod';
 import { QueryBy } from '@reticlehq/core';
 import { ReticleTool } from '../tools/tool-names.js';
 import { asNumber, asString } from '../tools/tools-helpers.js';
+import { listIndexSchema, scrollCountSchema } from '../tools/numeric-bounds.js';
 import { scrollToFind } from './scroll-find.js';
 /**
  * reticle_scroll_to — the windowed/virtualized-list escape hatch. A plain reticle_query
@@ -30,16 +31,13 @@ export const SCROLL_TOOLS = [
                 .string()
                 .optional()
                 .describe('Element ref for the scrollable container. Omit to scroll the document.'),
-            maxScrolls: z
-                .number()
+            maxScrolls: scrollCountSchema
                 .optional()
                 .describe('Maximum number of scroll steps before giving up. Default: 20.'),
-            targetIndex: z
-                .number()
+            targetIndex: listIndexSchema
                 .optional()
                 .describe('Known row index of the target in the list. Combine with totalCount for bisection — jumps directly to the estimated offset.'),
-            totalCount: z
-                .number()
+            totalCount: listIndexSchema
                 .optional()
                 .describe('Total item count in the virtualized list. Required for bisection with targetIndex.'),
             sessionId: z

package/dist/input/viewport-tools.js

@@ -2,10 +2,11 @@ import { z } from 'zod';
 import { CDP_NO_PROVIDER_REASON, CDP_NO_PROVIDER_RECOMMENDATION } from '@reticlehq/core';
 import { ReticleTool } from '../tools/tool-names.js';
 import { sessionIdShape } from '../tools/tool-kit.js';
+import { MAX_VIEWPORT_PX, MIN_VIEWPORT_PX, viewportPxSchema } from '../tools/numeric-bounds.js';
 import { asString } from '../tools/tools-helpers.js';
 /** Bounds so a viewport request stays sane (and a typo can't ask for a 1px or 100k-px window). */
-const MIN_DIM = 64;
-const MAX_DIM = 10000;
+const MIN_DIM = MIN_VIEWPORT_PX;
+const MAX_DIM = MAX_VIEWPORT_PX;
 function viewportProvider(deps) {
     const p = deps.realInput;
     return p !== undefined && 'function' === typeof p.setViewport
@@ -20,8 +21,8 @@ export const VIEWPORT_TOOLS = [
             'reticle_visual_diff `masks` and a frozen clock (reticle_clock). Set it once before reticle_screenshot / ' +
             'reticle_visual_diff. Returns { applied, width, height } or the no-provider recommendation.',
         inputSchema: {
-            width: z.number().int().describe('Viewport width in CSS px (e.g. 1280).'),
-            height: z.number().int().describe('Viewport height in CSS px (e.g. 800).'),
+            width: viewportPxSchema.describe('Viewport width in CSS px (e.g. 1280).'),
+            height: viewportPxSchema.describe('Viewport height in CSS px (e.g. 800).'),
             ...sessionIdShape,
         },
         outputSchema: {

package/dist/intent/inline-intent.d.ts

@@ -11,24 +11,13 @@ import type { ToolDeps } from '../tools/tool-kit.js';
 export declare function inlineIntentId(statement: string): string;
 /** What `provenBy` records: which tool drew the verdict, and when. */
 export declare function inlineVerdictId(tool: string, at: number): string;
-/**
- * Put an inline intent in the ledger and attach the predicate about to be evaluated. Returns the id
- * the verdict may later discharge, or undefined when there was no intent to record.
- *
- * `intent` carries EITHER prose OR the id of an intent already in the ledger. One field rather than
- * two because the surface is the scarce thing here and the two cases are told apart by the ledger
- * itself: a string that names an existing row is a reference, anything else is prose. A statement
- * that happens to equal an existing id is the same intent said twice, so pointing at the row is the
- * right answer there too, not a collision.
- *
- * A referenced intent is never re-declared, which would overwrite the agent's own words with an id,
- * and its binding is left alone when it already has one — a predicate bound deliberately through
- * `reticle_intent { action: "bind" }` is a stronger statement than whatever this one call asserts,
- * and quietly replacing it is exactly the narrowing the ledger exists to make visible.
- *
- * Best-effort by construction: a ledger that cannot be written is a small problem, and a verdict
- * that fails to return because of one is a large problem.
- */
+export declare function surfaceForInlineIntent(url: string | undefined, flow: string | undefined, 
+/** `file` or `file:line` for the element the verdict acted on, when it had one. */
+sourceLabel?: string): {
+    route?: string;
+    flow?: string;
+    files?: string[];
+} | undefined;
 export declare function linkInlineIntent(deps: ToolDeps, sessionId: string | undefined, intent: string | undefined, 
 /** The predicate this verdict will evaluate, or undefined when it proves nothing (a bare settle). */
 binding: unknown): Promise<string | undefined>;
@@ -43,4 +32,6 @@ export declare function dischargeInlineIntent(deps: ToolDeps, sessionId: string
     verdictId: string;
     grade: string;
     at: number;
-}): Promise<void>;
+}, 
+/** `file:line` of the element this verdict acted on, when there was one. */
+sourceLabel?: string): Promise<void>;

package/dist/intent/inline-intent.js

@@ -64,6 +64,81 @@ export function inlineVerdictId(tool, at) {
  * Best-effort by construction: a ledger that cannot be written is a small problem, and a verdict
  * that fails to return because of one is a large problem.
  */
+/**
+ * The surface an inline intent was captured on, so the store can FILE it.
+ *
+ * Measured on a real corpus: 167 of 173 things a project knew landed in `unsorted`, because
+ * `act_and_wait({ intent })` declared a statement and nothing else. The subject ladder had no flow,
+ * no route and no explicit subject to work from, so every record fell to the bucket of last resort
+ * — and a coverage map that is one pile with six labels tells a manager the team knows nothing,
+ * when the truth is that it knows a great deal and none of it is filed.
+ *
+ * The ROUTE is what makes this work at all, because it is always available: an agent asserting
+ * something is always somewhere. A flow name is better when there is one, and `subjectFor` already
+ * prefers it — this only has to supply both and let that ladder decide.
+ *
+ * Query and hash are dropped. `/issues?category=severe` and `/issues` are the same subject seen
+ * twice; keeping the query would shard one area of the product across every filter anybody used.
+ *
+ * Returns undefined rather than an empty object when there is nothing to record. A surface that
+ * says nothing reads as a capture that looked for a location and found none, rather than one that
+ * never had one — and the second is the truth.
+ */
+/**
+ * Strip a trailing `:line` from a `file:line` label.
+ *
+ * Anchored to the END and to digits, because a Windows path carries its own colon: splitting on the
+ * first one turns `C:\\app\\src\\cart.tsx:12` into `C`, which is a path to nothing and would be
+ * filed as though it were real.
+ */
+const SOURCE_LINE_SUFFIX = /:\d+$/;
+export function surfaceForInlineIntent(url, flow, 
+/** `file` or `file:line` for the element the verdict acted on, when it had one. */
+sourceLabel) {
+    let route;
+    if (url !== undefined) {
+        try {
+            const path = new URL(url).pathname;
+            // A bare origin has no path worth filing under: `/` would put every record in one bucket,
+            // which is the problem this exists to fix rather than a solution to it.
+            if (path.length > 1)
+                route = path;
+        }
+        catch {
+            route = undefined;
+        }
+    }
+    /*
+     * The file, without its line.
+     *
+     * A record is about a FILE; the line is where one verdict happened to touch it, and keeping it
+     * would make the same rule look like a different one every time the file was edited above it.
+     */
+    const file = sourceLabel === undefined || 0 === sourceLabel.length
+        ? undefined
+        : sourceLabel.replace(SOURCE_LINE_SUFFIX, '');
+    if (route === undefined && flow === undefined && file === undefined)
+        return undefined;
+    return {
+        ...(route === undefined ? {} : { route }),
+        ...(flow === undefined ? {} : { flow }),
+        ...(file === undefined ? {} : { files: [file] }),
+    };
+}
+/**
+ * The session's live URL, or undefined when no session can be named.
+ *
+ * `sessions.resolve` throws for every "cannot tell which tab" case, and none of them is a reason to
+ * fail the caller's verdict — a missing surface costs a filing, not a result.
+ */
+function sessionUrl(deps, sessionId) {
+    try {
+        return deps.sessions.resolve(sessionId).url;
+    }
+    catch {
+        return undefined;
+    }
+}
 export async function linkInlineIntent(deps, sessionId, intent, 
 /** The predicate this verdict will evaluate, or undefined when it proves nothing (a bare settle). */
 binding) {
@@ -73,6 +148,8 @@ binding) {
         const store = new IntentStore(deps.fs, sessionRoot(deps, sessionId), { now: deps.now });
         const existing = (await store.read()).find((row) => row.id === intent);
         const id = existing?.id ?? inlineIntentId(intent);
+        // Declared WITHOUT a surface on purpose: see dischargeInlineIntent for why the route that
+        // describes this record only exists after the action it is about.
         if (existing === undefined)
             await store.declare([{ id, statement: intent }]);
         if (binding !== undefined && existing?.binding === undefined)
@@ -90,11 +167,24 @@ binding) {
  * intent declared inline on a wait that asserted no consequence stays open and honest instead of
  * collecting a proof nothing earned.
  */
-export async function dischargeInlineIntent(deps, sessionId, id, proof) {
+export async function dischargeInlineIntent(deps, sessionId, id, proof, 
+/** `file:line` of the element this verdict acted on, when there was one. */
+sourceLabel) {
     if (id === undefined)
         return;
     try {
         const store = new IntentStore(deps.fs, sessionRoot(deps, sessionId), { now: deps.now });
+        /*
+         * File it HERE, not at declaration.
+         *
+         * The intent is declared before the action so a verdict can see it open, and at that instant the
+         * agent is still on the page it is leaving — clicking through to /issues from / would have filed
+         * the record under the page it left, or under nothing at all. The route that describes what the
+         * intent is about is the one that exists once the consequence has landed.
+         */
+        const surface = surfaceForInlineIntent(sessionUrl(deps, sessionId), undefined, sourceLabel);
+        if (surface !== undefined)
+            await store.place(id, surface);
         await store.discharge(id, proof);
     }
     catch {

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

@@ -0,0 +1,72 @@
+/**
+ * Reading and writing the sharded intent store, and migrating the flat one into it.
+ *
+ * The operations an agent actually performs, and what each is allowed to cost:
+ *
+ *   index()            every id + one line, always affordable — the session-start read
+ *   subject(name)      the full records for one subject, when it is about to work on that
+ *   get(id)            one record, via the index rather than by scanning shards
+ *   record()/update()  a write that touches ONE shard file plus the index
+ *
+ * The last one is the reason for the whole design. Under the flat file, changing one intent rewrote
+ * all 141, so two sessions touching unrelated subjects raced each other and the loser's write
+ * vanished. Sharded, they only collide when they genuinely edit the same subject.
+ *
+ * ## Migration is automatic, and it does not delete
+ *
+ * `.reticle/intent.json` is read on every load and folded in when the sharded copy has nothing for
+ * an id. That makes the move invisible: an agent on the new store sees old intents immediately, and
+ * an older build still reading the flat file keeps working, because nothing removes it. Deleting it
+ * is a separate decision somebody can take once they believe the migration.
+ */
+import { type Intent } from '@reticlehq/core';
+import type { FileSystemPort } from '../project/fs-port.js';
+import { IntentStatus, type IntentIndex, type IntentRecord } from './intent-shard.js';
+export interface Clock {
+    now: () => number;
+}
+/** What a caller supplies to write an intent. Everything optional is genuinely optional. */
+export interface IntentInput {
+    id: string;
+    statement: string;
+    subject?: string | undefined;
+    why?: string | undefined;
+    source?: string | undefined;
+    status?: IntentStatus | undefined;
+    surface?: Intent['surface'];
+    binding?: unknown;
+}
+export declare class IntentShardStore {
+    #private;
+    constructor(fs: FileSystemPort, root: string, clock: Clock);
+    /**
+     * The cheap read: one line per intent, and the call an agent makes at the start of a session.
+     *
+     * Includes anything still only in the legacy flat file, so the very first call on an unmigrated
+     * project already answers completely — which is what makes the migration invisible rather than a
+     * step somebody has to remember to run.
+     */
+    index(): Promise<IntentIndex>;
+    /** Every record for one subject — the working read, once an agent knows what it is touching. */
+    subject(name: string): Promise<IntentRecord[]>;
+    /** One record by id, or null. */
+    get(id: string): Promise<IntentRecord | null>;
+    /**
+     * Write one intent, creating or updating it.
+     *
+     * Merges onto whatever is already stored, so a caller adding a `why` to a migrated record does not
+     * have to restate its binding — and cannot silently drop it by omission, which is the failure mode
+     * that makes agents afraid to touch a store.
+     */
+    record(input: IntentInput): Promise<IntentRecord>;
+    /**
+     * Fold the flat file into shards on disk, so the move is visible in a diff rather than implicit.
+     *
+     * Idempotent, and it does not delete `.reticle/intent.json`: an older build still reads it, and a
+     * migration that removes its own source cannot be checked afterwards.
+     */
+    migrate(): Promise<{
+        migrated: number;
+        subjects: string[];
+    }>;
+}