@itookit/dsht 0.5.2 → 0.6.0

package/dist/cost/ledger.js

@@ -1,9 +1,9 @@
-import { chargeFor, costDay, DEFAULT_PRICES, pricesDigest, PRICING_ENGINE_VERSION } from "./pricing.js";
+import { chargeFor, costDay, costMonthStart, costWeekStart, costWindowStart, DEFAULT_PRICES, pricesDigest, PRICING_ENGINE_VERSION } from "./pricing.js";
 import { foldSamples } from "./records.js";
-import { loadLedgers, saveLedger } from "./ledger-files.js";
+import { loadLedgers, pruneLedgers, saveLedger } from "./ledger-files.js";
 /** Reasons one slice keeps at most, so a broken table cannot grow the ledger without bound. */
 const UNPRICED_LIMIT = 8;
-/** Per-origin cache of folded session totals; every scan replaces a session at its cut. */
+/** Per-origin cache of folded session totals and day buckets; every scan replaces a session at its cut. */
 export class CostLedger {
     prices;
     directory;
@@ -34,10 +34,19 @@ export class CostLedger {
             return 'partial';
         return this.scannedAt !== undefined || this.sessions.size > 0 ? 'complete' : 'partial';
     }
-    /** Load the newest cut per session; a stored total is read as it was decided. */
-    async load() {
+    /** Load the newest cut per session; a stored total is read as it was decided.
+     *
+     * Slices and dead files that have left the retention window are deleted in the same pass, so the
+     * directory cannot grow with every session this client has ever seen. A slice is a projection of the
+     * host log, so letting one go costs a rescan of that session, never data.
+     * @param now - Clock that names the window, so a caller or a test can pin the boundary.
+     */
+    async load(now = Date.now()) {
         this.totals.clear();
         this.sessions = await loadLedgers(this.directory);
+        for (const sessionId of await pruneLedgers(this.directory, costWindowStart(now), this.sessions)) {
+            this.sessions.delete(sessionId);
+        }
     }
     /** Replace one session using all billing events through the opening snapshot cut.
      *
@@ -54,16 +63,28 @@ export class CostLedger {
         const current = this.sessions.get(sessionId);
         if ((current?.cut ?? -2) > cut)
             return;
-        const day = costDay(now);
+        const scanDay = costDay(now);
+        const floor = costWindowStart(now);
         const total = { amount: 0, unknown: 0, records: 0 };
-        const today = { day, amount: 0, unknown: 0, records: 0 };
+        const days = new Map();
         const unpriced = new Set();
+        /** The day bucket to add to, created on first use so a session reports only the days it touched. */
+        const dayBucket = (day) => {
+            const found = days.get(day);
+            if (found !== undefined)
+                return found;
+            const created = { day, amount: 0, unknown: 0, records: 0 };
+            days.set(day, created);
+            return created;
+        };
         for (const sample of foldSamples(events)) {
             const decision = chargeFor(this.prices, sample.provider, sample.model, sample.time, sample.usage);
-            // A request belongs to the day it settled on, so the day bucket only counts the requests of
-            // the calendar day this scan is running on; another day reads as nothing spent today. A request
-            // with no settlement time belongs to no day, so it is counted as unknown wherever it is read.
-            const buckets = sample.time === undefined || costDay(sample.time) === day ? [total, today] : [total];
+            // A request belongs to the day it settled on. One with no settlement time is attributed to the
+            // day of this scan, which is the only day it can reach without guessing a tariff band, and is
+            // where a reader looks for what makes today's total inexact.
+            const day = sample.time === undefined ? scanDay : costDay(sample.time);
+            // Only the window is stored, so a session a year old writes days, not a year of them.
+            const buckets = day < floor ? [total] : [total, dayBucket(day)];
             for (const bucket of buckets) {
                 bucket.records++;
                 if (decision.amount === undefined)
@@ -74,8 +95,8 @@ export class CostLedger {
             if (decision.amount === undefined && unpriced.size < UNPRICED_LIMIT)
                 unpriced.add(`${sample.provider}/${sample.model}: ${decision.reason}`);
         }
-        const saved = { version: 3, sessionId, cut, engine: PRICING_ENGINE_VERSION, catalog: this.catalog,
-            total, day: today, unpriced: [...unpriced] };
+        const saved = { version: 4, sessionId, cut, engine: PRICING_ENGINE_VERSION, catalog: this.catalog,
+            total, days: [...days.values()].sort((a, b) => a.day < b.day ? -1 : a.day > b.day ? 1 : 0), unpriced: [...unpriced] };
         // Another process may have persisted a newer cut of this session since it was last read.
         if (this.directory && !await saveLedger(this.directory, saved))
             return;
@@ -117,25 +138,56 @@ export class CostLedger {
     }
     /** Every session's requests on one Beijing calendar day.
      *
-     * A slice keeps only the day its last scan ran on, so another day reads as nothing spent today
-     * rather than as the last day that was scanned.
+     * The day is a real bucket rather than only the day a scan ran on, so asking for another day
+     * reports that day's spend; the retention window is what limits how far back the answer reaches.
      * @param now - Clock that names the day to report.
      * @returns The day's total across cached sessions.
      */
     today(now = Date.now()) {
         const day = costDay(now);
-        const cached = this.totals.get(`d:${day}`);
+        return this.period(day, day);
+    }
+    /** Every session's requests in the natural week containing a day, through that day.
+     * @param now - Clock that names the day to report.
+     * @returns The week-to-date total across cached sessions.
+     */
+    week(now = Date.now()) {
+        const day = costDay(now);
+        return this.period(costWeekStart(day), day);
+    }
+    /** Every session's requests in the natural month containing a day, through that day.
+     * @param now - Clock that names the day to report.
+     * @returns The month-to-date total across cached sessions.
+     */
+    month(now = Date.now()) {
+        const day = costDay(now);
+        return this.period(costMonthStart(day), day);
+    }
+    /** Sum stored day buckets over a Beijing day range, inclusive at both ends.
+     *
+     * Days outside the retention window are absent rather than zero, so a range wider than the window
+     * reports what is still kept — which is why the fold and this sum share one window constant.
+     * @param from - First day to include, YYYY-MM-DD.
+     * @param to - Last day to include, YYYY-MM-DD.
+     * @returns The range's total across cached sessions.
+     */
+    period(from, to) {
+        const key = `p:${from}..${to}`;
+        const cached = this.totals.get(key);
         if (cached)
             return cached;
         const result = { amount: 0, unknown: 0, records: 0 };
         for (const session of this.sessions.values()) {
-            if (session.day.day !== day)
-                continue;
-            result.amount += session.day.amount;
-            result.unknown += session.day.unknown;
-            result.records += session.day.records;
+            for (const day of session.days) {
+                // ISO day strings compare chronologically, so a lexical range is the day range.
+                if (day.day < from || day.day > to)
+                    continue;
+                result.amount += day.amount;
+                result.unknown += day.unknown;
+                result.records += day.records;
+            }
         }
-        this.totals.set(`d:${day}`, result);
+        this.totals.set(key, result);
         return result;
     }
 }

package/dist/cost/pricing.d.ts

@@ -29,6 +29,45 @@ export declare function pricesFrom(value: unknown): PriceVersion[];
  * @returns Beijing calendar date, YYYY-MM-DD.
  */
 export declare function costDay(time: number): string;
+/** Beijing days of cost the ledger keeps, folds and reports.
+ *
+ * One number decides three things that have to agree: how much per-session history a slice stores,
+ * which slices a retention pass may delete, and how far back the day/week/month totals reach. Sixty
+ * days covers a natural month with room to compare it against the previous one.
+ */
+export declare const COST_WINDOW_DAYS = 60;
+/** First millisecond of a Beijing calendar day.
+ *
+ * China has had no daylight saving since 1991, so a Beijing day is exactly 24 hours and an explicit
+ * offset is exact rather than an approximation.
+ * @param day - Beijing calendar date, YYYY-MM-DD.
+ * @returns Epoch milliseconds.
+ */
+export declare function costDayStart(day: string): number;
+/** The Beijing day a whole number of days before another.
+ *
+ * The arithmetic is on the calendar date, not on an instant, so it cannot drift across a month, a
+ * year or a leap day.
+ * @param day - Beijing calendar date, YYYY-MM-DD.
+ * @param days - Days to subtract, zero or more.
+ * @returns Beijing calendar date, YYYY-MM-DD.
+ */
+export declare function costDaysBefore(day: string, days: number): string;
+/** The Monday that begins the natural week containing a Beijing day.
+ * @param day - Beijing calendar date, YYYY-MM-DD.
+ * @returns Beijing calendar date of that week's Monday.
+ */
+export declare function costWeekStart(day: string): string;
+/** The first day of the natural month containing a Beijing day.
+ * @param day - Beijing calendar date, YYYY-MM-DD.
+ * @returns Beijing calendar date, YYYY-MM-01.
+ */
+export declare function costMonthStart(day: string): string;
+/** Oldest Beijing day a ledger still keeps, so every retention decision uses one boundary.
+ * @param now - Clock that names the current day.
+ * @returns Beijing calendar date, YYYY-MM-DD.
+ */
+export declare function costWindowStart(now: number): string;
 /** Canonical form of a model name before matching.
  *
  * The host reports names that differ from the published table by width, case, surrounding space, or

package/dist/cost/pricing.js

@@ -117,6 +117,52 @@ export function pricesFrom(value) {
  * @returns Beijing calendar date, YYYY-MM-DD.
  */
 export function costDay(time) { return new Date(time + 8 * 3600_000).toISOString().slice(0, 10); }
+/** Beijing days of cost the ledger keeps, folds and reports.
+ *
+ * One number decides three things that have to agree: how much per-session history a slice stores,
+ * which slices a retention pass may delete, and how far back the day/week/month totals reach. Sixty
+ * days covers a natural month with room to compare it against the previous one.
+ */
+export const COST_WINDOW_DAYS = 60;
+/** First millisecond of a Beijing calendar day.
+ *
+ * China has had no daylight saving since 1991, so a Beijing day is exactly 24 hours and an explicit
+ * offset is exact rather than an approximation.
+ * @param day - Beijing calendar date, YYYY-MM-DD.
+ * @returns Epoch milliseconds.
+ */
+export function costDayStart(day) { return Date.parse(`${day}T00:00:00+08:00`); }
+/** The Beijing day a whole number of days before another.
+ *
+ * The arithmetic is on the calendar date, not on an instant, so it cannot drift across a month, a
+ * year or a leap day.
+ * @param day - Beijing calendar date, YYYY-MM-DD.
+ * @param days - Days to subtract, zero or more.
+ * @returns Beijing calendar date, YYYY-MM-DD.
+ */
+export function costDaysBefore(day, days) {
+    const [year, month, date] = day.split('-').map(Number);
+    return new Date(Date.UTC(year, month - 1, date - days)).toISOString().slice(0, 10);
+}
+/** The Monday that begins the natural week containing a Beijing day.
+ * @param day - Beijing calendar date, YYYY-MM-DD.
+ * @returns Beijing calendar date of that week's Monday.
+ */
+export function costWeekStart(day) {
+    const [year, month, date] = day.split('-').map(Number);
+    const weekday = new Date(Date.UTC(year, month - 1, date)).getUTCDay();
+    return costDaysBefore(day, (weekday + 6) % 7);
+}
+/** The first day of the natural month containing a Beijing day.
+ * @param day - Beijing calendar date, YYYY-MM-DD.
+ * @returns Beijing calendar date, YYYY-MM-01.
+ */
+export function costMonthStart(day) { return `${day.slice(0, 8)}01`; }
+/** Oldest Beijing day a ledger still keeps, so every retention decision uses one boundary.
+ * @param now - Clock that names the current day.
+ * @returns Beijing calendar date, YYYY-MM-DD.
+ */
+export function costWindowStart(now) { return costDaysBefore(costDay(now), COST_WINDOW_DAYS - 1); }
 /** Canonical form of a model name before matching.
  *
  * The host reports names that differ from the published table by width, case, surrounding space, or

package/dist/cost/types.d.ts

@@ -52,7 +52,7 @@ export interface CostTotal {
     unknown: number;
     records: number;
 }
-/** One Beijing calendar day's requests, kept only for the day a scan ran on. */
+/** One Beijing calendar day's requests, kept for every day inside the retention window. */
 export interface DayTotal extends CostTotal {
     day: string;
 }
@@ -64,14 +64,20 @@ export interface DayTotal extends CostTotal {
  * rules and the table behind these totals, so a process holding an older one cannot overwrite them.
  */
 export interface SavedCost {
-    version: 3;
+    version: 4;
     sessionId: string;
     /** Durable sequence the fold reached; a scan that opened an older cut may not replace this slice. */
     cut: number;
     engine: number;
     catalog: string;
     total: CostTotal;
-    day: DayTotal;
+    /** One entry per Beijing day this session spent inside the retention window, oldest first.
+     *
+     * Days older than the window are dropped as the slice is written, so the file cannot grow with a
+     * session's history. A day a later scan no longer reports is simply gone from the next slice: the
+     * host log, not this file, is what a day's total is re-derived from.
+     */
+    days: DayTotal[];
     /** Distinct reasons an amount is missing, bounded, so a panel can say what makes a total inexact. */
     unpriced: string[];
 }

package/dist/storage/files.d.ts

@@ -3,6 +3,14 @@
  * @returns File contents, or undefined when the file does not exist.
  */
 export declare function readText(path: string): Promise<string | undefined>;
+/** Last modification time of a file, without reading it.
+ *
+ * Used where only a file's age matters, so a file whose contents this build cannot parse is still
+ * judgeable — a generation of ledger written by an older build has to age out like any other.
+ * @param path - Absolute file path.
+ * @returns Epoch milliseconds, or undefined when the file does not exist.
+ */
+export declare function modifiedAt(path: string): Promise<number | undefined>;
 /** Read a user-private file, rejecting a symlink, a foreign owner, or group/other access.
  * @param path - Absolute file path.
  * @param label - Name used in the validation error, such as `Cookie file`.

package/dist/storage/files.js

@@ -1,6 +1,6 @@
 /** Every filesystem read and write the client performs; no other module opens a file. */
 import { constants } from 'node:fs';
-import { open, readFile, rename, unlink, writeFile } from 'node:fs/promises';
+import { open, readFile, rename, stat, unlink, writeFile } from 'node:fs/promises';
 import { randomUUID } from 'node:crypto';
 import { dirname, join } from 'node:path';
 /** Read a UTF-8 file; an absent file is an ordinary result, not a failure.
@@ -17,6 +17,23 @@ export async function readText(path) {
         throw error;
     }
 }
+/** Last modification time of a file, without reading it.
+ *
+ * Used where only a file's age matters, so a file whose contents this build cannot parse is still
+ * judgeable — a generation of ledger written by an older build has to age out like any other.
+ * @param path - Absolute file path.
+ * @returns Epoch milliseconds, or undefined when the file does not exist.
+ */
+export async function modifiedAt(path) {
+    try {
+        return (await stat(path)).mtimeMs;
+    }
+    catch (error) {
+        if (isMissing(error))
+            return undefined;
+        throw error;
+    }
+}
 /** Read a user-private file, rejecting a symlink, a foreign owner, or group/other access.
  * @param path - Absolute file path.
  * @param label - Name used in the validation error, such as `Cookie file`.

package/dist/storage/index.d.ts

@@ -1,4 +1,4 @@
 /** Storage domain: every filesystem operation the client performs. */
-export { appendPrivateFile, createPrivateFile, readPrivateFile, readText, removeFile, renameFile, writeExclusiveStream, writePrivateFile } from './files.ts';
+export { appendPrivateFile, createPrivateFile, modifiedAt, readPrivateFile, readText, removeFile, renameFile, writeExclusiveStream, writePrivateFile } from './files.ts';
 export { ensureDirectory, ensurePrivateDirectory, listEntries } from './directories.ts';
 export { heapSnapshotName, writeHeapSnapshot } from './heap-snapshot.ts';

package/dist/storage/index.js

@@ -1,4 +1,4 @@
 /** Storage domain: every filesystem operation the client performs. */
-export { appendPrivateFile, createPrivateFile, readPrivateFile, readText, removeFile, renameFile, writeExclusiveStream, writePrivateFile } from "./files.js";
+export { appendPrivateFile, createPrivateFile, modifiedAt, readPrivateFile, readText, removeFile, renameFile, writeExclusiveStream, writePrivateFile } from "./files.js";
 export { ensureDirectory, ensurePrivateDirectory, listEntries } from "./directories.js";
 export { heapSnapshotName, writeHeapSnapshot } from "./heap-snapshot.js";

package/dist/ui/app.js

@@ -1029,6 +1029,8 @@ export function App({ controller, panelLifetimeMs = PANEL_LIFETIME_MS, theme = m
         return {
             ...(session === undefined ? {} : { session: line(session) }),
             today: line(ledger.today()),
+            week: line(ledger.week()),
+            month: line(ledger.month()),
             scanning: ledger.scanning, coverage: ledger.coverage,
             ...(ledger.scannedAt === undefined ? {} : { scannedAt: ledger.scannedAt }),
             customPrices: ledger.customPrices,
@@ -1057,5 +1059,5 @@ export function App({ controller, panelLifetimeMs = PANEL_LIFETIME_MS, theme = m
                                                                             ? '↑ ↓ move · Space / 1–9 toggle · Enter confirm · Esc dismisses' : '↑ ↓ / 1–9 select · Enter confirm · Esc dismisses' })] }), _jsx(Text, { dimColor: true, children: question ? options.length > 0
                                                                     ? 'Choose "Other answer" to type · the draft is kept while this is open'
                                                                     : 'Esc dismisses the question · the draft is kept while this is open'
-                                                                    : 'Esc keeps this pending · the draft is kept while this is open' })] })] }) }), !queueOpen && !pending && state.screen === 'chat' && queued.length > 0 && _jsx(QueuedPreview, { queued: queued, width: width }), _jsx(TextInput, { value: input, onChange: setInput, onCursorChange: setCursor, onSubmit: () => { void submit(input); }, reservedKeys: approvalKeysActive ? ['1', '2', '3'] : questionKeysActive ? ['1', '2', '3', '4', '5', '6', '7', '8', '9', ...(question?.multiSelect === true ? [' '] : [])] : !removal && !models && !searchResults && (state.screen === 'workspaces' || state.screen === 'sessions') ? ['d'] : surfaceReservedKeys.length ? surfaceReservedKeys : undefined, width: draftWidth, maxRows: composerRows, promptColor: answerPending ? theme.colors.muted : theme.accent, focus: !copyMode && !answerPending && !loopForm, placeholder: state.screen === 'path' ? 'Absolute directory path on host' : 'Message, @host-file, or /help' }), referenceOpen && _jsx(ReferenceMenu, { matches: matches, index: referenceIndex }), loopMenuOpen && _jsx(LoopMenu, { records: loopCandidates, index: loopMenuCursor })] }), commandSuggestions && _jsx(Text, { dimColor: true, children: commandSuggestions.join('  ') }), commandHint && _jsxs(Text, { dimColor: true, children: [_jsxs(Text, { color: theme.accent, children: [commandHint.command, commandHint.usage === undefined ? '' : ` ${commandHint.usage}`] }), " \u00B7 ", commandHint.description] }), help && _jsx(HelpPanel, { page: currentHelpPage, pages: helpPages, pageSize: helpPageSize }), costExpanded && _jsx(CostPanel, { source: costSource }), _jsx(Frozen, { frozen: statusFrozen, identity: `${width}:${state.sessionId}:${statusExpanded}:${statusScroll}:${pauseReason ?? ''}`, children: _jsx(StatusBar, { source: statusSource, width: width, expanded: statusExpanded, scroll: statusScroll, pageSize: statusViewRows, onScroll: setStatusScroll, onOverflow: setStatusOverflow, onRows: setStatusBarRows, pauseReason: pauseReason, revision: state.version }) })] })] }) }) }) });
+                                                                    : 'Esc keeps this pending · the draft is kept while this is open' })] })] }) }), !queueOpen && !pending && state.screen === 'chat' && queued.length > 0 && _jsx(QueuedPreview, { queued: queued, width: width }), _jsx(TextInput, { value: input, onChange: setInput, onCursorChange: setCursor, onSubmit: () => { void submit(input); }, reservedKeys: approvalKeysActive ? ['1', '2', '3'] : questionKeysActive ? ['1', '2', '3', '4', '5', '6', '7', '8', '9', ...(question?.multiSelect === true ? [' '] : [])] : !removal && !models && !searchResults && (state.screen === 'workspaces' || state.screen === 'sessions') ? ['d'] : surfaceReservedKeys.length ? surfaceReservedKeys : undefined, width: draftWidth, maxRows: composerRows, promptColor: answerPending ? theme.colors.muted : theme.accent, focus: !copyMode && !answerPending && !loopForm, placeholder: state.screen === 'path' ? 'Absolute directory path on host' : 'Message, @host-file, or /help' }), referenceOpen && _jsx(ReferenceMenu, { matches: matches, index: referenceIndex }), loopMenuOpen && _jsx(LoopMenu, { records: loopCandidates, index: loopMenuCursor, source: controller.queries.loopSource })] }), commandSuggestions && _jsx(Text, { dimColor: true, children: commandSuggestions.join('  ') }), commandHint && _jsxs(Text, { dimColor: true, children: [_jsxs(Text, { color: theme.accent, children: [commandHint.command, commandHint.usage === undefined ? '' : ` ${commandHint.usage}`] }), " \u00B7 ", commandHint.description] }), help && _jsx(HelpPanel, { page: currentHelpPage, pages: helpPages, pageSize: helpPageSize }), costExpanded && _jsx(CostPanel, { source: costSource }), _jsx(Frozen, { frozen: statusFrozen, identity: `${width}:${state.sessionId}:${statusExpanded}:${statusScroll}:${pauseReason ?? ''}`, children: _jsx(StatusBar, { source: statusSource, width: width, expanded: statusExpanded, scroll: statusScroll, pageSize: statusViewRows, onScroll: setStatusScroll, onOverflow: setStatusOverflow, onRows: setStatusBarRows, pauseReason: pauseReason, revision: state.version }) })] })] }) }) }) });
 }

package/dist/ui/dialogs/cost.d.ts

@@ -9,6 +9,8 @@ export interface CostLine {
 export interface CostSource {
     session?: CostLine;
     today: CostLine;
+    week: CostLine;
+    month: CostLine;
     scanning: boolean;
     coverage: Coverage;
     scannedAt?: number;
@@ -17,6 +19,10 @@ export interface CostSource {
     missing: readonly string[];
 }
 /** Render cached totals while the independent HTTP cost scan refreshes.
+ *
+ * The three periods are natural Beijing periods counted from their own start through today, not
+ * sliding windows, so "this week" and "this month" match what an invoice would name. They only reach
+ * back as far as the retained ledger does, which is why the panel says how old its cached totals are.
  * @param source - Plain billing summary, absent when this run has no ledger.
  * @returns Billing panel, including unpriced models and refresh errors.
  */

package/dist/ui/dialogs/cost.js

@@ -4,6 +4,10 @@ import { useTheme } from "../theme/index.js";
 import { Box, Text } from 'ink';
 import { safeText } from "../../text.js";
 /** Render cached totals while the independent HTTP cost scan refreshes.
+ *
+ * The three periods are natural Beijing periods counted from their own start through today, not
+ * sliding windows, so "this week" and "this month" match what an invoice would name. They only reach
+ * back as far as the retained ledger does, which is why the panel says how old its cached totals are.
  * @param source - Plain billing summary, absent when this run has no ledger.
  * @returns Billing panel, including unpriced models and refresh errors.
  */
@@ -12,7 +16,7 @@ export function CostPanel({ source }) {
     const costs = source;
     if (!costs)
         return _jsx(Text, { children: "Cost tracking is unavailable" });
-    const rows = [['Session', costs.session], ['Today', costs.today]];
+    const rows = [['Session', costs.session], ['Today', costs.today], ['This week', costs.week], ['This month', costs.month]];
     return _jsxs(Box, { flexDirection: "column", borderStyle: "single", paddingX: 1, children: [_jsx(Text, { bold: true, children: "Cost \u00B7 CNY estimate \u00B7 Asia/Shanghai \u00B7 /cost closes" }), rows.map(([label, total]) => _jsxs(Text, { children: [label, ": ", total ? `${total.text} · ${total.unknown} unpriced / ${total.records} requests` : '?'] }, label)), _jsx(Text, { dimColor: true, children: costs.scanning ? 'Refreshing all visible sessions…'
                     : costs.coverage === 'partial' ? 'Partial totals · awaiting a complete scan'
                         : costs.scannedAt ? `Last refresh: ${new Date(costs.scannedAt).toISOString()}`

package/dist/ui/dialogs/loop.d.ts

@@ -1,4 +1,4 @@
-import type { LoopLimits, LoopRecord } from '../../contracts.ts';
+import type { LoopLimits, LoopRecord, LoopSourceInfo } from '../../contracts.ts';
 /** The numeric fields the form edits, in the order a run reads them. */
 export type LoopField = 'from' | 'to' | 'score' | 'tries';
 /** What the form hands to the runner: the four numbers and the record's variables as confirmed. */
@@ -15,12 +15,13 @@ export declare function loopRecordDefaults(record: LoopRecord): LoopLimits;
  *
  * It offers the same names and defaults the runner reads, so choosing from it cannot start a run
  * other than the one the row describes.
- * @param props - Matching records and the highlighted row.
- * @returns The key line and up to six record rows.
+ * @param props - Matching records, the highlighted row, and where the records came from.
+ * @returns The key line, the source line, any warning, and up to six record rows.
  */
-export declare function LoopMenu({ records, index }: {
+export declare function LoopMenu({ records, index, source }: {
     records: readonly LoopRecord[];
     index: number;
+    source?: LoopSourceInfo;
 }): import("react").JSX.Element;
 /** The loop parameter form: one record's variables and defaults, editable in place, then a Start.
  *

package/dist/ui/dialogs/loop.js

@@ -47,20 +47,28 @@ function labelWidth(rows) {
  *
  * It offers the same names and defaults the runner reads, so choosing from it cannot start a run
  * other than the one the row describes.
- * @param props - Matching records and the highlighted row.
- * @returns The key line and up to six record rows.
+ * @param props - Matching records, the highlighted row, and where the records came from.
+ * @returns The key line, the source line, any warning, and up to six record rows.
  */
-export function LoopMenu({ records, index }) {
+export function LoopMenu({ records, index, source }) {
     const theme = useTheme();
     const start = Math.max(0, index - 5);
-    return _jsxs(Box, { flexDirection: "column", children: [_jsx(Text, { dimColor: true, children: "Loop records \u00B7 \u2191 \u2193 select \u00B7 Enter confirm defaults \u00B7 Tab finish the name \u00B7 Esc close" }), records.slice(start, start + 6).map((record, offset) => {
+    // Records are configuration now: whenever a user file supplied or replaced one, the list says so,
+    // because an operator who overrode a shipped record cannot tell the two apart from the name alone.
+    const origin = source?.file === undefined ? undefined : [
+        `Records from ${source.file}`,
+        ...(source.overridden.length === 0 ? [] : [`replaced: ${source.overridden.join(', ')}`]),
+        ...(source.added.length === 0 ? [] : [`added: ${source.added.join(', ')}`]),
+    ].join(' · ');
+    return _jsxs(Box, { flexDirection: "column", children: [_jsx(Text, { dimColor: true, children: "Loop records \u00B7 \u2191 \u2193 select \u00B7 Enter confirm defaults \u00B7 Tab finish the name \u00B7 Esc close" }), origin !== undefined && _jsx(Text, { dimColor: true, wrap: "truncate-end", children: safeText(origin) }), (source?.warnings ?? []).map(warning => _jsx(Text, { color: theme.colors.error, wrap: "truncate-end", children: safeText(warning) }, warning)), records.slice(start, start + 6).map((record, offset) => {
                 const current = start + offset === index;
                 // The record's own inputs come before the artifact file: they are what the form will edit, and
                 // the first thing a narrow row must not lose.
                 const vars = Object.entries(record.vars).map(([name, value]) => `${name} ${value}`).join(' · ');
                 const target = vars === '' ? '' : ` · ${vars}`;
                 const artifact = record.artifact === undefined ? '' : ` · ${record.artifact}`;
-                return _jsxs(Text, { color: current ? theme.accent : undefined, wrap: "truncate-end", children: [current ? '❯ ' : '  ', record.name, " \u00B7 ", record.title, " \u00B7 ", record.steps, " rounds \u00B7 pass ", record.defaultScore, " \u00B7 \u2264", record.defaultTries, " tries", target, artifact] }, record.name);
+                const mine = record.fromFile === true ? ' · yours' : '';
+                return _jsxs(Text, { color: current ? theme.accent : undefined, wrap: "truncate-end", children: [current ? '❯ ' : '  ', record.name, " \u00B7 ", record.title, " \u00B7 ", record.steps, " rounds \u00B7 pass ", record.defaultScore, " \u00B7 \u2264", record.defaultTries, " tries", target, artifact, mine] }, record.name);
             })] });
 }
 /** The loop parameter form: one record's variables and defaults, editable in place, then a Start.
@@ -207,7 +215,7 @@ export function LoopDialog({ record, enabled, onStart, onBack, onClose }) {
         }
         onStart({ limits: values, vars });
     }, { isActive: !copyMode });
-    return _jsxs(Box, { flexDirection: "column", marginY: 1, children: [_jsxs(Text, { bold: true, children: ["Run loop record \u00B7 ", safeText(record.name), " \u00B7 Esc close"] }), _jsxs(Text, { dimColor: true, wrap: "truncate-end", children: [record.steps, " rounds", record.artifact === undefined ? '' : ` · ${safeText(record.artifact)}`, " \u00B7 \u2191 \u2193 to a row, then type"] }), rows.map((item, index) => {
+    return _jsxs(Box, { flexDirection: "column", marginY: 1, children: [_jsxs(Text, { bold: true, children: ["Run loop record \u00B7 ", safeText(record.name), record.fromFile === true ? ' · your file' : '', " \u00B7 Esc close"] }), _jsxs(Text, { dimColor: true, wrap: "truncate-end", children: [record.steps, " rounds", record.artifact === undefined ? '' : ` · ${safeText(record.artifact)}`, " \u00B7 \u2191 \u2193 to a row, then type"] }), rows.map((item, index) => {
                 const selected = index === row;
                 const cursor = selected ? '❯ ' : '  ';
                 if (item.kind === 'start' || item.kind === 'back')