@reticlehq/server 3.5.0 → 3.7.0

package/dist/memory/impact/impact-store.js

@@ -1,23 +1,27 @@
 import { mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { SyncStatus, dashboardRunUrl, describeSync, keyRefusalAtLastSync, overallStatus, readSyncSummary, } from '../project/sync-status.js';
+import { describeUnsynced, unsentFlowCount, unsentRunCount, } from '../cloud/unsynced-roots.js';
+import { readDashboardUrl } from '../project/sync-status.js';
 import { dirname, join } from 'node:path';
 import { homedir } from 'node:os';
 import { readAccountState } from '../cloud/account-state.js';
-import { harnessOfferSource } from '../cloud/harness-offer.js';
+import { configForHud } from '../cloud/harness-config.js';
+import { hudNoticesSource } from '../cloud/hud-notices-source.js';
+import { selectNotices } from '@reticlehq/core/hud';
 import { ReticleDir, IMPACT_DAILY_BUCKETS, IMPACT_DEFECT_LIMIT, IMPACT_SCHEMA_VERSION, ImpactScopeSchema, addImpactCounts, emptyImpactCounts, emptyImpactRecords, estimateImpactSavings, } from '@reticlehq/core';
 /**
  * Where Reticle keeps the record of what it has done for you.
  *
- * Two scopes, two files, both local and never uploaded: the project's own `.reticle/impact.json`,
- * and a machine-wide `~/.reticle/impact.json` that answers "what has Reticle done for me overall"
- * across every app you have instrumented.
+ * Two scopes, two files: the project's own `.reticle/impact.json`, and a machine-wide
+ * `~/.reticle/impact.json` that answers "what has Reticle done for me overall" across every app you
+ * have instrumented.
  *
- * This is NOT telemetry. Telemetry answers our questions about the product and leaves the machine;
- * this answers the user's question about their own work and never does.
+ * This is NOT telemetry. Telemetry answers our questions about the product; this answers the user's
+ * question about their own work. A linked project's record syncs to that user's own dashboard (the
+ * sync cycle's `impact` kind); the machine-wide record never leaves the machine.
  */
 /** Writes are debounced: a verification loop is 50-200 calls, and each one is a counter bump. */
 const WRITE_DEBOUNCE_MS = 800;
-/** The project's cloud binding, written by `reticle link`. Absent for an unlinked project. */
-const CLOUD_LINK_FILE = 'cloud.json';
 /**
  * `reticleRoot` is the project's own `.reticle` directory (what every other store here is handed);
  * the global scope lives beside the daemon's own state in `~/.reticle`.
@@ -32,26 +36,6 @@ function impactPaths(reticleRoot, globalRoot) {
         global: join(globalRoot, ReticleDir.ROOT, ReticleDir.IMPACT_FILE),
     };
 }
-/**
- * Where this project's dashboard lives, if `reticle link` recorded one.
- *
- * Read from the link file rather than derived from the API url, because the API origin and the
- * console origin are different hosts in every deployment that is not a laptop. Synchronous and
- * best-effort, like every other read in this file: a missing or malformed link file means no link
- * in the HUD, never a failed tool call.
- */
-function readDashboardUrl(reticleRoot) {
-    try {
-        const raw = JSON.parse(readFileSync(join(reticleRoot, CLOUD_LINK_FILE), 'utf8'));
-        if ('object' !== typeof raw || null === raw)
-            return undefined;
-        const value = raw['dashboardUrl'];
-        return 'string' === typeof value && value.length > 0 ? value : undefined;
-    }
-    catch {
-        return undefined;
-    }
-}
 function emptyScope(now) {
     const counts = emptyImpactCounts();
     return {
@@ -92,6 +76,12 @@ function writeScope(path, scope) {
         // memory and the next write attempt carries them.
     }
 }
+/** The daemon's cached copy of the HUD notices file, beside the machine-wide impact record. */
+const HUD_NOTICES_CACHE_FILE = 'hud-notices.json';
+/** How long a sync status is reused before it is read again. */
+const SYNC_STATUS_EVERY_MS = 10_000;
+/** When the caller did not say which build this is: matches only notices with no `minSdk`. */
+const UNKNOWN_SDK_VERSION = '0.0.0';
 /** YYYY-MM-DD in local time - the day boundary a person recognises, not UTC's. */
 export function isoDay(now) {
     const d = new Date(now);
@@ -105,33 +95,55 @@ function isNextDay(a, b) {
     const next = new Date(`${b}T00:00:00`);
     return 1 === Math.round((next.getTime() - prev.getTime()) / 86_400_000);
 }
+/**
+ * Consecutive days ending at the newest recorded day, read from the days themselves.
+ *
+ * It was a counter bumped when a fold opened a new day and compared only with the bucket before it,
+ * so one stray day in between (a late flush from another daemon, a writer with a frozen clock) reset
+ * it to 1. Counting back from the newest date means no out-of-order write can shorten it.
+ */
+function streakEndingAtLatest(sortedDates) {
+    let streak = 0;
+    let later;
+    for (let i = sortedDates.length - 1; i >= 0; i -= 1) {
+        const date = sortedDates[i];
+        if (date === undefined)
+            break;
+        if (later !== undefined && !isNextDay(date, later))
+            break;
+        streak += 1;
+        later = date;
+    }
+    return streak;
+}
 /** Fold one delta into a scope: totals, today's bucket, records and streak. Pure. */
 export function applyDelta(scope, delta, now, meta = {}) {
     const today = isoDay(now);
     const counts = addImpactCounts(scope.counts, delta);
-    const days = scope.days.slice();
-    const last = days[days.length - 1];
-    if (last !== undefined && last.date === today) {
-        days[days.length - 1] = { date: today, counts: addImpactCounts(last.counts, delta) };
-    }
-    else {
-        days.push({ date: today, counts: addImpactCounts(emptyImpactCounts(), delta) });
+    // One bucket per date, wherever the delta's date falls. The machine-wide record has many writers
+    // and a late flush carries an older date, so "the last bucket is today" is not something a fold
+    // may assume — appending on that assumption duplicated dates and put them out of order.
+    const byDate = new Map();
+    for (const day of scope.days) {
+        byDate.set(day.date, addImpactCounts(byDate.get(day.date) ?? emptyImpactCounts(), day.counts));
     }
+    const todayCounts = addImpactCounts(byDate.get(today) ?? emptyImpactCounts(), delta);
+    byDate.set(today, todayCounts);
+    const dates = [...byDate.keys()].sort();
+    const days = dates.map((date) => ({ date, counts: byDate.get(date) ?? emptyImpactCounts() }));
     while (days.length > IMPACT_DAILY_BUCKETS)
         days.shift();
-    const todayCounts = days[days.length - 1]?.counts ?? emptyImpactCounts();
-    const previousDay = days[days.length - 2];
     const records = { ...scope.records };
     records.bestVerdictDay = Math.max(records.bestVerdictDay, todayCounts.verdicts);
     records.bestDefectDay = Math.max(records.bestDefectDay, todayCounts.failed);
-    if (last === undefined || last.date !== today) {
-        // A new day joins the streak only if it follows yesterday; otherwise it starts a new one.
-        records.streakDays =
-            previousDay !== undefined && isNextDay(previousDay.date, today) ? records.streakDays + 1 : 1;
-    }
-    else if (0 === records.streakDays) {
-        records.streakDays = 1;
-    }
+    // The window keeps IMPACT_DAILY_BUCKETS days, so a streak longer than it cannot be read off the
+    // dates alone: when the whole window is one unbroken run, it continues the streak already held.
+    const inWindow = streakEndingAtLatest(dates);
+    const unbroken = inWindow === dates.length && scope.days.length >= IMPACT_DAILY_BUCKETS;
+    const newDay = !scope.days.some((day) => day.date === today);
+    records.streakDays = unbroken
+        ? Math.max(inWindow, scope.records.streakDays + (newDay ? 1 : 0))
+        : inWindow;
     records.bestStreakDays = Math.max(records.bestStreakDays, records.streakDays);
     records.longestRunMs = Math.max(records.longestRunMs, meta.runMs ?? 0);
     /*
@@ -150,6 +162,41 @@ export function applyDelta(scope, delta, now, meta = {}) {
         defects,
     };
 }
+/** The larger of two counters, key by key. */
+function maxEach(a, b) {
+    const out = { ...a };
+    for (const key of Object.keys(b))
+        out[key] = Math.max(a[key] ?? 0, b[key] ?? 0);
+    return out;
+}
+/**
+ * All time, never smaller than the project being looked at.
+ *
+ * The two scopes live in different files: the project's in its `.reticle`, the machine's in the
+ * home directory. A project whose history began before this machine's ledger (an upgrade, a new
+ * laptop, a moved checkout) showed more under "This project" than under "All time", which no reader
+ * can believe. The machine has done at least what any one of its projects has.
+ */
+export function atLeastProject(global, project) {
+    // The earlier of the two starts; zero is "never recorded", not the epoch.
+    const starts = [global.since, project.since].filter((t) => 0 < t);
+    return {
+        ...global,
+        counts: maxEach(global.counts, project.counts),
+        records: maxEach(global.records, project.records),
+        savings: {
+            tokens: {
+                ...global.savings.tokens,
+                value: Math.max(global.savings.tokens.value, project.savings.tokens.value),
+            },
+            minutes: {
+                ...global.savings.minutes,
+                value: Math.max(global.savings.minutes.value, project.savings.minutes.value),
+            },
+        },
+        since: 0 === starts.length ? 0 : Math.min(...starts),
+    };
+}
 /**
  * The live impact record for one project.
  *
@@ -158,6 +205,9 @@ export function applyDelta(scope, delta, now, meta = {}) {
  */
 export class ImpactStore {
     #paths;
+    #root;
+    /** The sync status, re-read at most every SYNC_STATUS_EVERY_MS: it reads every run file. */
+    #sync;
     #now;
     #projectName;
     #dashboardUrl;
@@ -175,10 +225,12 @@ export class ImpactStore {
     #timer;
     #onChange;
     #account;
-    /** Where this workspace stands with the free harness offer. Cached; see harness-offer.ts. */
-    #offer;
     #config;
+    #notices;
+    #sdkVersion;
+    #coverage;
     constructor(opts) {
+        this.#coverage = opts.coverage;
         this.#paths = impactPaths(opts.reticleRoot, opts.globalRoot ?? homedir());
         // Resolved per snapshot, not cached: a user who runs `reticle login` in another terminal must
         // see the HUD change without restarting the daemon that is watching their app.
@@ -186,9 +238,13 @@ export class ImpactStore {
         this.#now = opts.now ?? (() => Date.now());
         this.#projectName = opts.projectName;
         this.#dashboardUrl = readDashboardUrl(opts.reticleRoot);
-        // The claim happens in the console, so the link this project was linked to IS the claim link —
-        // built here rather than in the HUD, which has no way to know where this project points.
-        this.#offer = opts.offer ?? harnessOfferSource(process.env, () => this.#dashboardUrl);
+        this.#root = opts.reticleRoot;
+        this.#notices =
+            opts.notices ??
+                hudNoticesSource({
+                    cacheFile: join(opts.globalRoot ?? homedir(), ReticleDir.ROOT, HUD_NOTICES_CACHE_FILE),
+                });
+        this.#sdkVersion = opts.sdkVersion ?? UNKNOWN_SDK_VERSION;
         // No default: the loader lives in `features/harness` and this file may not reach for it.
         // A store built without one simply reports no harness config, which the HUD renders as no row.
         this.#config = opts.config ?? { read: () => undefined };
@@ -196,6 +252,46 @@ export class ImpactStore {
         this.#project = readScope(this.#paths.project, now);
         this.#global = readScope(this.#paths.global, now);
     }
+    #syncStatus(dashboardUrl) {
+        const now = this.#now();
+        if (this.#sync !== undefined && now - this.#sync.at < SYNC_STATUS_EVERY_MS)
+            return this.#sync.value;
+        // Not linked: one line when runs or flows sit here that nothing will send, and nothing otherwise.
+        // `pending` counts both, so the HUD's existing "N not sent" includes a flow saved with no run.
+        if (dashboardUrl === undefined) {
+            const runs = unsentRunCount(this.#root);
+            const flows = unsentFlowCount(this.#root, false);
+            const value = 0 === runs + flows
+                ? undefined
+                : {
+                    status: SyncStatus.LOCAL_ONLY,
+                    pending: runs + flows,
+                    runs,
+                    flows,
+                    said: describeUnsynced({ root: this.#root, runs, flows, linked: false }, dirname(this.#root)),
+                };
+            this.#sync = { at: now, value };
+            return value;
+        }
+        const summary = readSyncSummary(this.#root, true);
+        const refusal = keyRefusalAtLastSync(this.#root);
+        const latest = summary.latestOnPlatform;
+        const value = {
+            status: overallStatus(summary),
+            runs: summary.runs,
+            onPlatform: summary.onPlatform,
+            pending: summary.pending,
+            refused: summary.refused.length + summary.refusedMore,
+            ...(summary.lastPushAt === undefined ? {} : { lastPushAt: summary.lastPushAt }),
+            // The run that just synced, on its own page — the HUD's "see it in your dashboard".
+            ...(latest === undefined ? {} : { runUrl: dashboardRunUrl(dashboardUrl, latest) }),
+            said: describeSync(summary, now),
+            // The HUD's chip: a refused key is not "0 waiting".
+            ...(refusal === undefined ? {} : { keyRefused: refusal }),
+        };
+        this.#sync = { at: now, value };
+        return value;
+    }
     /** Notified after every fold, so the HUD can be pushed a fresh snapshot. */
     onChange(fn) {
         this.#onChange = fn;
@@ -214,28 +310,38 @@ export class ImpactStore {
         const snap = {
             schemaVersion: IMPACT_SCHEMA_VERSION,
             project: this.#project,
-            global: this.#global,
+            global: atLeastProject(this.#global, this.#project),
         };
         if (this.#projectName !== undefined)
             snap.projectName = this.#projectName;
+        // Re-read, like the account: `reticle link` runs in another terminal while this store lives as
+        // long as the daemon, so a construction-time read said "Not linked" until a restart.
+        this.#dashboardUrl = readDashboardUrl(this.#root);
         if (this.#dashboardUrl !== undefined)
             snap.dashboardUrl = this.#dashboardUrl;
         snap.account = this.#account();
-        const cfgForOffer = this.#config.read();
-        const offer = this.#offer.read();
-        // Joined here because this is the one place that holds BOTH the offer and the platform config.
-        // The card reads the offer, so readiness has to travel on it rather than being re-derived in a
-        // presenter that has no business knowing what a provider key is.
-        if (offer !== undefined && cfgForOffer !== undefined)
-            offer.drivable = cfgForOffer.providerReady;
-        // Absent means "we have not heard", which the HUD renders as nothing at all. Never defaulted to
-        // `{claimed:false}`: that would advertise the offer to everyone who is offline.
-        if (offer !== undefined)
-            snap.harnessOffer = offer;
         // Absent stays absent: the HUD reads that as "we have not heard" and renders no control.
         const cfg = this.#config.read();
         if (cfg !== undefined)
-            snap.harnessConfig = cfg;
+            snap.harnessConfig = configForHud(cfg, this.#now());
+        // Chosen here, where the account and the entitlement are both known. Absent when nothing applies,
+        // so the HUD falls back to the slides bundled with the SDK.
+        const notices = selectNotices(this.#notices.read(), {
+            signedIn: snap.account?.signedIn,
+            entitled: cfg?.harnessEntitled,
+            sdkVersion: this.#sdkVersion,
+            now: this.#now(),
+        });
+        if (0 < notices.length)
+            snap.notices = notices;
+        const coverage = this.#coverage?.();
+        if (coverage !== undefined)
+            snap.coverage = coverage;
+        // Only for a linked project: an unlinked one has nothing on the platform, and the HUD already
+        // offers the way to link it.
+        const sync = this.#syncStatus(this.#dashboardUrl);
+        if (sync !== undefined)
+            snap.sync = sync;
         return snap;
     }
     /** Write now (process exit, tests). */

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

@@ -55,6 +55,7 @@ export declare function dischargeInlineIntent(deps: ToolDeps, sessionId: string
     verdictId: string;
     grade: string;
     at: number;
+    runId?: string;
 }, 
 /** `file:line` of the element this verdict acted on, when there was one. */
 sourceLabel?: string): Promise<void>;

package/dist/memory/intent/intent-shard-store.js

@@ -25,7 +25,7 @@ import { IntentFileSchema, IntentState, amendIntent, isActionLabel, } from '@ret
 import { IntentDir, ReticleDir } from '@reticlehq/core';
 import { reticleDirPaths } from '../project/dir/reticle-dir.js';
 import { withFileLock } from '../project/file-lock.js';
-import { subjectFor } from './intent-subject.js';
+import { subjectFor, UNSORTED_SUBJECT } from './intent-subject.js';
 import { emptyShard, indexFrom, IntentShardSchema, IntentStatus, recordFromIntent, serialise, shardsFrom, statusFromState, } from './intent-shard.js';
 import { writeFileAtomic } from '../project/fs/write-atomic.js';
 const JSON_SUFFIX = '.json';
@@ -199,13 +199,25 @@ export class IntentShardStore {
         const subject = flow !== undefined
             ? subjectFor({ surface: { flow } })
             : (facts.subject ??
-                existing?.subject ??
+                // `unsorted` is the absence of a subject, so new evidence may still file the record.
+                (UNSORTED_SUBJECT === existing?.subject ? undefined : existing?.subject) ??
                 subjectFor({ surface: next.surface, binding: next.binding }));
         const why = facts.why ?? existing?.why;
         const source = facts.source ?? existing?.source;
+        // New words keep no check bound to the old ones: a later green on it would "prove" words it
+        // never tested. A binding the change brings with it stands.
+        const kept = existing !== undefined && existing.statement !== next.statement
+            ? { ...existing, binding: undefined }
+            : existing;
+        // Bound only while a check is bound: a record whose check was taken off (new words, a decision)
+        // said `bound` with none, and a check naming it then proved nothing and said nothing.
+        const merged = { ...kept, ...next };
+        const state = IntentState.BOUND === merged.state && merged.binding === undefined
+            ? IntentState.DECLARED
+            : merged.state;
         return {
-            ...existing,
-            ...next,
+            ...merged,
+            state,
             subject,
             status: this.#statusOf(next, existing, facts.status),
             updatedAt: this.#clock.now(),

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

@@ -63,14 +63,17 @@ declare const IntentRecordSchema: z.ZodObject<{
         verdictId: z.ZodString;
         grade: z.ZodString;
         at: z.ZodNumber;
+        runId: z.ZodOptional<z.ZodString>;
     }, "strip", z.ZodTypeAny, {
         at: number;
         grade: string;
         verdictId: string;
+        runId?: string | undefined;
     }, {
         at: number;
         grade: string;
         verdictId: string;
+        runId?: string | undefined;
     }>>;
     amended: z.ZodOptional<z.ZodArray<z.ZodObject<{
         statement: z.ZodString;
@@ -112,6 +115,7 @@ declare const IntentRecordSchema: z.ZodObject<{
         at: number;
         grade: string;
         verdictId: string;
+        runId?: string | undefined;
     } | undefined;
     amended?: {
         at: number;
@@ -137,6 +141,7 @@ declare const IntentRecordSchema: z.ZodObject<{
         at: number;
         grade: string;
         verdictId: string;
+        runId?: string | undefined;
     } | undefined;
     amended?: {
         at: number;
@@ -170,14 +175,17 @@ export declare const IntentShardSchema: z.ZodObject<{
             verdictId: z.ZodString;
             grade: z.ZodString;
             at: z.ZodNumber;
+            runId: z.ZodOptional<z.ZodString>;
         }, "strip", z.ZodTypeAny, {
             at: number;
             grade: string;
             verdictId: string;
+            runId?: string | undefined;
         }, {
             at: number;
             grade: string;
             verdictId: string;
+            runId?: string | undefined;
         }>>;
         amended: z.ZodOptional<z.ZodArray<z.ZodObject<{
             statement: z.ZodString;
@@ -219,6 +227,7 @@ export declare const IntentShardSchema: z.ZodObject<{
             at: number;
             grade: string;
             verdictId: string;
+            runId?: string | undefined;
         } | undefined;
         amended?: {
             at: number;
@@ -244,6 +253,7 @@ export declare const IntentShardSchema: z.ZodObject<{
             at: number;
             grade: string;
             verdictId: string;
+            runId?: string | undefined;
         } | undefined;
         amended?: {
             at: number;
@@ -252,7 +262,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";
@@ -273,15 +282,16 @@ export declare const IntentShardSchema: z.ZodObject<{
             at: number;
             grade: string;
             verdictId: string;
+            runId?: string | undefined;
         } | undefined;
         amended?: {
             at: number;
             statement: string;
         }[] | undefined;
     }>;
+    subject: string;
 }, {
     version: 1;
-    subject: string;
     intents: Record<string, {
         status: "proved" | "proposed" | "agreed" | "stale";
         state: "proved" | "declared" | "bound";
@@ -302,12 +312,14 @@ export declare const IntentShardSchema: z.ZodObject<{
             at: number;
             grade: string;
             verdictId: string;
+            runId?: string | undefined;
         } | undefined;
         amended?: {
             at: number;
             statement: string;
         }[] | undefined;
     }>;
+    subject: string;
 }>;
 export type IntentShard = z.infer<typeof IntentShardSchema>;
 export declare const IntentIndexSchema: z.ZodObject<{

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

@@ -48,5 +48,6 @@ export declare class IntentStore {
         verdictId: string;
         grade: string;
         at: number;
+        runId?: string;
     }): Promise<boolean>;
 }

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

@@ -1,8 +1,14 @@
+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 { UNSORTED_SUBJECT } from './intent-subject.js';
+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 +38,7 @@ const MIGRATE = 'migrate';
 export const INTENT_TOOLS = [
     {
         name: ReticleTool.INTENT,
-        description: 'Record what a change is SUPPOSED to make true, as a durable statement ABOUT THE PRODUCT that a teammate who was not here will understand in six months — name the behaviour, not this run or its step number, and never "renders cleanly", which nothing can check. It is SHARED memory: pooled per project and read back by later agents. Capture it while you still know — then verification does not have to re-derive it from the DOM later. { action:"declare", intents:[{ id, statement, surface? }] } takes prose and needs NO predicate: at declare time there is often no route, no ref and no code yet, and a predicate demanded there is just a mechanism. Declare EARLY (as you build) and batch them — one call per feature is the whole budget. { action:"bind", id, binding } attaches the predicate that would prove it once you know how; an intent with no binding is not a failure, it is the most interesting row in the ledger — something meant that nothing can currently prove. { action:"list" } returns what is still open. Stored in .reticle/intent/<subject>/intent.json (a flow name is its subject), git-checked so a human sees in review if an intent was later narrowed to match what was easy to prove.',
+        description: 'Record what a change is SUPPOSED to make true, as a durable statement ABOUT THE PRODUCT that a teammate who was not here will understand in six months — name the behaviour, not this run or its step number, and never "renders cleanly", which nothing can check. It is SHARED memory: pooled per project and read back by later agents. Capture it while you still know — then verification does not have to re-derive it from the DOM later. { action:"declare", intents:[{ id, statement, surface? }] } takes prose and needs NO predicate: at declare time there is often no route, no ref and no code yet, and a predicate demanded there is just a mechanism. Declare EARLY (as you build) and batch them — one call per feature is the whole budget. { action:"bind", id, binding } attaches the predicate that would prove it once you know how; an intent with no binding is not a failure, it is the most interesting row in the ledger — something meant that nothing can currently prove. { action:"list" } returns what is still open. Pass `request` (what the user asked, verbatim) once per task. Stored in .reticle/intent/, git-checked.',
         example: {
             action: DECLARE,
             intents: [
@@ -74,6 +80,7 @@ export const INTENT_TOOLS = [
                 .min(1)
                 .optional()
                 .describe('declare only. Batchable — declare every intent for a feature in one call.'),
+            request: z.string().optional().describe("declare: the user's words, verbatim."),
             id: z.string().optional().describe('bind only: which intent the predicate proves.'),
             /*
              * The predicate schema, not `unknown`.
@@ -101,6 +108,11 @@ export const INTENT_TOOLS = [
                 .optional()
                 .describe('declare only: statements not stored, and why.'),
             path: z.string().optional().describe('Where the ledger was written.'),
+            filesNotFound: z.array(z.string()).optional().describe('surface.files not in the project'),
+            noSubject: z
+                .object({ ids: z.array(z.string()), fix: z.string() })
+                .optional()
+                .describe('declare only: intents filed under nothing, and how to file them'),
             entries: z
                 .array(z.unknown())
                 .optional()
@@ -155,19 +167,125 @@ export const INTENT_TOOLS = [
                 return { intents: await store.open() };
             }
             const raw = args['intents'];
+            const request = asString(args['request']);
+            if (request !== undefined && 0 < request.trim().length) {
+                await recordRequest(deps, root, request, Array.isArray(raw) ? raw : []);
+                if (!Array.isArray(raw) || 0 === raw.length)
+                    return { request: 'recorded', path: root };
+            }
             // Refused, not read as an empty list: `declare` with nothing to declare stored nothing and
             // answered `{ intents: [] }`, which an agent reads as a declaration that worked (#1118).
             if (!Array.isArray(raw) || 0 === raw.length) {
                 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 { entries, missing } = await withExistingFiles(deps, dirname(root), 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.
             const refused = entries
                 .filter((entry) => isActionLabel(entry.statement))
                 .map((entry) => ({ id: entry.id, reason: STEP_LABEL_REFUSAL }));
-            return { intents: declared, ...(0 === refused.length ? {} : { refused }), path: root };
+            // Asked, not refused: prose with nowhere to live is still worth keeping, but an agent
+            // looking for it later finds it by its subject, and the Memory page warns about these.
+            const unsorted = declared
+                .filter((intent) => UNSORTED_SUBJECT === intent.subject)
+                .map((intent) => intent.id);
+            return {
+                intents: declared,
+                ...(0 === refused.length ? {} : { refused }),
+                // Named, never kept as a fact's source: a path that is not in the project is a guess.
+                ...(0 === missing.length ? {} : { filesNotFound: missing }),
+                ...(0 === unsorted.length ? {} : { noSubject: { ids: unsorted, fix: NO_SUBJECT_FIX } }),
+                path: root,
+            };
         },
     },
 ];
+/**
+ * The entries with each `surface.files` path that is not in the project left out, and those paths.
+ * An agent declared `src/pages/SavedItems.tsx` for `src/views/SavedItems.tsx`, and the dashboard
+ * showed the wrong file as the fact's source.
+ */
+async function withExistingFiles(deps, projectDir, entries) {
+    const missing = [];
+    const kept = await Promise.all(entries.map(async (entry) => {
+        const surface = entry.surface;
+        if (!Array.isArray(surface?.files))
+            return entry;
+        const files = [];
+        for (const file of surface.files)
+            if ('string' === typeof file && (await deps.fs.exists(join(projectDir, file))))
+                files.push(file);
+            else if ('string' === typeof file)
+                missing.push(file);
+        return { ...entry, surface: { ...surface, files } };
+    }));
+    return { entries: kept, missing };
+}
+const NO_SUBJECT_FIX = 'Nothing says what these are about, so an agent looking for them cannot find them: declare each again with surface.route (the page it is about) or surface.flow.';
+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`);
+}