@itookit/dsht 0.3.2 → 0.3.4

package/dist/cli/index.js

@@ -1,128 +1,18 @@
 #!/usr/bin/env node
-/** Standalone executable entry; connects to an existing host and never launches Harness. */
-import { createHash } from 'node:crypto';
-import { homedir } from 'node:os';
-import { join } from 'node:path';
-import { CostLedger, DEFAULT_PRICES, pricesFrom } from "../cost/index.js";
-import { parseArgs } from 'node:util';
-import { mount } from "../ui/mount.js";
-import { createPrivateFile, ensureDirectory, readText } from "../storage/index.js";
-import { sessionLabel } from "../session/navigation.js";
-import { CookieStore, login } from "../transport/auth.js";
-import { Client } from "../transport/client.js";
-import { historyLimits } from "../session/memory.js";
-import { Controller } from "../controller/controller.js";
-import { endpoint } from "../transport/endpoint.js";
-import { errorText, safeText, string } from "../transport/wire.js";
-const HELP = `Usage: dsht [options] [list workspaces|list sessions]
-
-With no command, choose a workspace and session interactively.
-
-  --url <url>           Host URL, or the dsh web URL with ?token= (DSH_URL)
-  --workspace <id>      Filter list sessions by workspace
-  --session <id>        Open a session directly
-  --auth-dir <path>     Private cookie directory (or DSHT_AUTH_DIR)
-  --history-records <n> Soft history record limit (default 2000)
-  --history-mb <n>      Soft history payload budget in MiB (default 16)
-  --memory-log <path>   Append runtime memory samples; a failing log stops itself
-  --no-memory-log       Disable the runtime memory log (default: enabled)
-  --json               Print machine-readable list output
-  --help               Show this help
-
-The default host is http://127.0.0.1:3080.
-First login: export DSH_TOKEN, or export DSH_URL as the URL printed by dsh web.
-Cookies are saved per server origin and reused on later starts. Tokens are never saved.
-/cost shows session, today and three-day CNY estimates.
-DSHT_CONFIG_DIR overrides the prices.json directory; DSHT_STATE_DIR overrides usage storage.
-The memory log defaults to <state>/memory.log; DSHT_MEMORY_LOG sets another path or 'off'.
-Examples:
-  npx @itookit/dsht
-  dsht list workspaces --json
-  dsht list sessions --workspace <id> --json
-`;
-async function main() {
-    const { values, positionals } = parseArgs({ allowPositionals: true, options: {
-            url: { type: 'string', default: process.env.DSH_URL ?? 'http://127.0.0.1:3080' },
-            'history-records': { type: 'string' }, 'history-mb': { type: 'string' },
-            workspace: { type: 'string' }, session: { type: 'string' }, 'auth-dir': { type: 'string' }, json: { type: 'boolean' }, help: { type: 'boolean' },
-            'memory-log': { type: 'string' }, 'no-memory-log': { type: 'boolean' },
-        } });
-    if (values.help) {
-        process.stdout.write(HELP);
-        return;
-    }
-    const list = positionals[0] === 'list' && ['workspaces', 'sessions'].includes(positionals[1] ?? '') && positionals.length === 2;
-    if (positionals.length && !list)
-        throw new Error('Unknown command. Use --help.');
-    if (!list && (values.json || values.workspace))
-        throw new Error('--json and --workspace apply to list commands');
-    if (list && values.session)
-        throw new Error('--session applies to interactive mode');
-    const limits = historyLimits(values['history-records'], values['history-mb']);
-    const { url, token } = endpoint(values.url, process.env.DSH_TOKEN);
-    const store = new CookieStore(values['auth-dir']);
-    if (list) {
-        const client = new Client(url);
-        try {
-            await login(client, token, store);
-            if (positionals[1] === 'workspaces' || values.workspace)
-                await client.connect();
-            const items = positionals[1] === 'workspaces' ? await client.listWorkspaces() : await client.listSessions(values.workspace);
-            if (values.json)
-                process.stdout.write(`${JSON.stringify({ items }, null, 2)}\n`);
-            else {
-                const lines = items.map(item => positionals[1] === 'workspaces'
-                    ? `${string(item.workspaceId)}\t${string(item.title)}\t${string(item.path)}`
-                    : `${string(item.sessionId)}\t${sessionLabel(item)}\t${item.running ? 'running' : 'idle'}`);
-                process.stdout.write(`${safeText(lines.join('\n'))}${lines.length ? '\n' : ''}`);
-            }
-        }
-        finally {
-            await client.close();
-        }
-        return;
-    }
-    if (!process.stdin.isTTY || !process.stdout.isTTY)
-        throw new Error('Interactive mode requires a terminal. Use list workspaces or list sessions for scripts.');
-    const config = process.env.DSHT_CONFIG_DIR ?? join(process.env.XDG_CONFIG_HOME ?? join(homedir(), '.config'), 'dsht');
-    await ensureDirectory(config);
-    const pricePath = join(config, 'prices.json');
-    await createPrivateFile(pricePath, JSON.stringify(DEFAULT_PRICES, null, 2) + '\n');
-    const raw = await readText(pricePath);
-    if (raw === undefined)
-        throw new Error(`Price configuration disappeared: ${pricePath}`);
-    const prices = pricesFrom(JSON.parse(raw));
-    const stateRoot = process.env.DSHT_STATE_DIR ?? join(process.env.XDG_STATE_HOME ?? join(homedir(), '.local', 'state'), 'dsht');
-    const costDirectory = join(stateRoot, 'cost', createHash('sha256').update(new URL(url).origin).digest('hex'));
-    const costs = new CostLedger(prices, costDirectory);
-    await costs.load();
-    const controller = new Controller(url, token, values.session, undefined, client => login(client, token, store), costs, limits, memoryLogPath(stateRoot, values['memory-log'], values['no-memory-log']));
-    const app = mount(controller);
-    const terminate = () => app.unmount();
-    process.once('SIGTERM', terminate);
-    controller.start();
-    try {
-        await app.waitUntilExit();
-    }
-    finally {
-        process.off('SIGTERM', terminate);
-        await controller.shutdown();
-    }
-}
-/** Resolve the runtime memory log path: an explicit flag wins, then the environment, then the default.
- * @param stateRoot - Application state root used for the default path.
- * @param requested - `--memory-log` value, when given.
- * @param disabled - `--no-memory-log` flag.
- * @returns Absolute log path, or undefined when the log is disabled.
+/**
+ * Executable entry. It must set the React build before anything imports Ink.
+ *
+ * A static `import` is evaluated before this file's body runs, so importing the CLI
+ * directly would let `react-reconciler` resolve to its development build and emit a
+ * `performance.measure()` entry for every render. Node's performance timeline holds
+ * those entries for the life of the process and never trims them, which grew the heap
+ * by roughly 1.2 KB per render until the process was restarted. The dynamic import
+ * below is therefore load-bearing: `NODE_ENV` has to be set first.
+ *
+ * Set `DSHT_REACT_DEV=1` to keep the development build for React warnings and
+ * DevTools performance tracks.
  */
-function memoryLogPath(stateRoot, requested, disabled) {
-    if (requested !== undefined && requested.trim() === '')
-        throw new Error('--memory-log requires a path');
-    if (disabled)
-        return undefined;
-    const chosen = (requested ?? process.env.DSHT_MEMORY_LOG)?.trim();
-    if (chosen === undefined || chosen === '')
-        return join(stateRoot, 'memory.log');
-    return chosen === 'off' ? undefined : chosen;
-}
-main().catch(error => { process.stderr.write(`${errorText(error)}\n`); process.exitCode = 1; });
+if ((process.env.DSHT_REACT_DEV ?? '') === '')
+    process.env.NODE_ENV ??= 'production';
+await import('./dsht.js');
+export {};

package/dist/controller/controller.d.ts

@@ -23,6 +23,8 @@ export declare class Controller implements ControllerStore, ConnectionListener {
     readonly costs?: CostLedger | undefined;
     readonly historyLimits: HistoryLimits;
     readonly memoryLogPath?: string | undefined;
+    /** Directory this client runs in, offered as a workspace when the host has not registered it. */
+    readonly localDirectory: string;
     state: State;
     /** Physical connection, retry loop and projection store. */
     readonly connection: ConnectionController;
@@ -36,7 +38,9 @@ export declare class Controller implements ControllerStore, ConnectionListener {
     readonly memoryLog: MemoryLog | undefined;
     private readonly observers;
     private selector;
-    constructor(base: string, token: string | undefined, initialSession?: string | undefined, makeClient?: () => Client, authenticate?: (client: Client) => Promise<void>, costs?: CostLedger | undefined, historyLimits?: HistoryLimits, memoryLogPath?: string | undefined);
+    constructor(base: string, token: string | undefined, initialSession?: string | undefined, makeClient?: () => Client, authenticate?: (client: Client) => Promise<void>, costs?: CostLedger | undefined, historyLimits?: HistoryLimits, memoryLogPath?: string | undefined, 
+    /** Directory this client runs in, offered as a workspace when the host has not registered it. */
+    localDirectory?: string);
     /** React-compatible state subscription. */
     subscribe: (listener: () => void) => (() => void);
     /** Snapshot identity changes only when the controller publishes. */
@@ -71,6 +75,10 @@ export declare class Controller implements ControllerStore, ConnectionListener {
      * diagram cache — and the work the last cost scan re-read, which is the only timer here whose
      * per-pass work scales with history. With a runtime that exposes `gc`, the sample also reports
      * the heap after a forced collection, so retained state and uncollected garbage stay distinct.
+     *
+     * React's development build appends one performance-timeline entry per rendered component and Node
+     * never trims them, so the sample counts them and then bounds them; `perfMeasuresCleared` separates
+     * entries this sample released from entries the build created since the last one.
      */
     private memorySample;
     /** Collect before reading the heap when the runtime exposes a collection.
@@ -116,6 +124,8 @@ export declare class Controller implements ControllerStore, ConnectionListener {
     get workingSince(): number | undefined;
     /** @returns Sessions accounted to the selected workspace, minus archived identities. */
     get visibleSessions(): ObjectValue[];
+    /** @returns Unanswered interactions by session, for the state each list row reports. */
+    pendingCounts(): ReadonlyMap<string, number>;
     /** Load the optional preset roster once per connection. */
     loadPresetNames(): void;
     /** @returns Host model routes and adapter-owned reasoning choices. */
@@ -219,6 +229,11 @@ export declare class Controller implements ControllerStore, ConnectionListener {
      * @returns Absolute saved filename.
      */
     exportHtml(path: string | undefined, signal: AbortSignal): Promise<string>;
+    /** Write a V8 heap snapshot into this client's working directory; the write pauses the client.
+     * @param tag - Sampling-point label naming the file, such as `after-stress`.
+     * @returns Absolute path of the written snapshot.
+     */
+    heapSnapshot(tag?: string): string;
     /** Admit text once as steering while running, or a new turn while idle.
      * @param text - Composed prompt text.
      */
@@ -255,6 +270,8 @@ export declare class Controller implements ControllerStore, ConnectionListener {
      * @param allowed - Whether the request is approved once.
      */
     approve(allowed: boolean): Promise<void>;
+    /** Dismiss the whole pending question set without answering it, as the Web close button does. */
+    dismissQuestion(): Promise<void>;
 }
 export type { HistorySearch, RemovalTarget } from '../session/types.ts';
 export type { State } from '../state.ts';

package/dist/controller/controller.js

@@ -1,5 +1,6 @@
 /** Application facade: composes the connection, session, catalog and cost domains. */
 import { Client } from "../transport/client.js";
+import { writeHeapSnapshot } from "../storage/index.js";
 import { errorText } from "../transport/wire.js";
 import { DEFAULT_HISTORY_LIMITS } from "../session/memory.js";
 import { layoutStats } from "../session/history.js";
@@ -9,6 +10,7 @@ import { CatalogController } from "../catalog/controller.js";
 import { CostController } from "../cost/controller.js";
 import { ConnectionController } from "./connection.js";
 import { MemoryLog } from "./memory-log.js";
+import { clearReactMeasures, measureCount } from "./perf-measures.js";
 import { initialState } from "../state.js";
 /** Application facade over the domain controllers; the UI owns only this object.
  *
@@ -21,6 +23,7 @@ export class Controller {
     costs;
     historyLimits;
     memoryLogPath;
+    localDirectory;
     state = initialState();
     /** Physical connection, retry loop and projection store. */
     connection;
@@ -34,12 +37,15 @@ export class Controller {
     memoryLog;
     observers = new Set();
     selector = 0;
-    constructor(base, token, initialSession, makeClient = () => new Client(base), authenticate = client => client.authenticate(token ?? ''), costs, historyLimits = DEFAULT_HISTORY_LIMITS, memoryLogPath) {
+    constructor(base, token, initialSession, makeClient = () => new Client(base), authenticate = client => client.authenticate(token ?? ''), costs, historyLimits = DEFAULT_HISTORY_LIMITS, memoryLogPath, 
+    /** Directory this client runs in, offered as a workspace when the host has not registered it. */
+    localDirectory = process.cwd()) {
         this.base = base;
         this.initialSession = initialSession;
         this.costs = costs;
         this.historyLimits = historyLimits;
         this.memoryLogPath = memoryLogPath;
+        this.localDirectory = localDirectory;
         const options = { base, token, initialSession, makeClient, authenticate };
         this.connection = new ConnectionController(this, options, this);
         this.session = new SessionController(this, this.connection, this.connection, historyLimits);
@@ -124,6 +130,10 @@ export class Controller {
      * diagram cache — and the work the last cost scan re-read, which is the only timer here whose
      * per-pass work scales with history. With a runtime that exposes `gc`, the sample also reports
      * the heap after a forced collection, so retained state and uncollected garbage stay distinct.
+     *
+     * React's development build appends one performance-timeline entry per rendered component and Node
+     * never trims them, so the sample counts them and then bounds them; `perfMeasuresCleared` separates
+     * entries this sample released from entries the build created since the last one.
      */
     memorySample() {
         const memory = process.memoryUsage();
@@ -131,11 +141,14 @@ export class Controller {
         const ledger = this.costs?.summary();
         const layout = layoutStats(transcript);
         const markdown = markdownCacheStats();
+        const measuresCleared = clearReactMeasures();
+        const measures = measureCount();
         const gc = this.forcedGc();
         return {
             time: new Date().toISOString(),
             rss: memory.rss, heapTotal: memory.heapTotal, heapUsed: memory.heapUsed,
             external: memory.external, arrayBuffers: memory.arrayBuffers,
+            ...(measures === undefined ? {} : { perfMeasures: measures, perfMeasuresCleared: measuresCleared }),
             ...(gc === undefined ? {} : { heapUsedAfterGc: gc.used, gcMs: gc.ms }),
             online: this.state.online, screen: this.state.screen,
             session: this.state.sessionId ?? null,
@@ -150,7 +163,7 @@ export class Controller {
             scanning: this.costs?.scanning ?? false,
             ...(this.costs?.lastScan === undefined ? {} : { scanSessions: this.costs.lastScan.sessions,
                 scanPages: this.costs.lastScan.pages, scanEvents: this.costs.lastScan.events }),
-            ...(ledger === undefined ? {} : { ledgerSessions: ledger.sessions, ledgerCharges: ledger.charges, ledgerUnpriced: ledger.unpriced }),
+            ...(ledger === undefined ? {} : { ledgerSessions: ledger.sessions, ledgerRecords: ledger.records, ledgerUnpriced: ledger.unpriced }),
         };
     }
     /** Collect before reading the heap when the runtime exposes a collection.
@@ -219,6 +232,8 @@ export class Controller {
     get workingSince() { return this.session.workingSince; }
     /** @returns Sessions accounted to the selected workspace, minus archived identities. */
     get visibleSessions() { return this.session.visibleSessions; }
+    /** @returns Unanswered interactions by session, for the state each list row reports. */
+    pendingCounts() { return this.session.pendingCounts(); }
     /** Load the optional preset roster once per connection. */
     loadPresetNames() { this.catalog.loadPresetNames(); }
     /** @returns Host model routes and adapter-owned reasoning choices. */
@@ -323,6 +338,11 @@ export class Controller {
      * @returns Absolute saved filename.
      */
     async exportHtml(path, signal) { return this.session.exportHtml(path, signal); }
+    /** Write a V8 heap snapshot into this client's working directory; the write pauses the client.
+     * @param tag - Sampling-point label naming the file, such as `after-stress`.
+     * @returns Absolute path of the written snapshot.
+     */
+    heapSnapshot(tag) { return writeHeapSnapshot(process.cwd(), tag); }
     /** Admit text once as steering while running, or a new turn while idle.
      * @param text - Composed prompt text.
      */
@@ -359,4 +379,6 @@ export class Controller {
      * @param allowed - Whether the request is approved once.
      */
     async approve(allowed) { await this.session.approve(allowed); }
+    /** Dismiss the whole pending question set without answering it, as the Web close button does. */
+    async dismissQuestion() { await this.session.dismissQuestion(); }
 }

package/dist/controller/perf-measures.d.ts

@@ -0,0 +1,34 @@
+/** Drop the render measurements React's development build appends to the global performance timeline.
+ *
+ * `react-reconciler` emits one `performance.measure()` entry per rendered component when it resolves
+ * to its development build, and Node keeps every entry for the life of the process because
+ * `performance.clearMeasures()` is the only way to release them. Each entry also carries a
+ * `detail.devtools.properties` payload describing the component's props, which is where the memory
+ * actually goes: roughly 1.2 KB per render once the duplicated property names are counted.
+ *
+ * The production build emits no measurements at all, so `src/cli/index.ts` selects it and this
+ * module is a safety net for `DSHT_REACT_DEV=1`, where the development build is deliberate.
+ */
+/** Measure names the current timeline holds that React created.
+ *
+ * A name only counts when it is exactly one of `REACT_NAMES` or carries React's zero-width prefix,
+ * so entries an application or a library created under its own name are never selected.
+ * @param performance - Timeline to read.
+ * @returns Names React created, without duplicates.
+ */
+export declare function reactMeasureNames(performance: Performance): string[];
+/** Remove React's render measurements, and only those, from the global performance timeline.
+ *
+ * Intended to run on the memory-sampling interval: the development build keeps appending, so one
+ * pass only bounds the total instead of ending it. A failure is not worth propagating, because this
+ * is a bounded diagnostic and a measurement library that rejects input should not stop the client.
+ * @returns How many distinct measure names were cleared.
+ */
+export declare function clearReactMeasures(): number;
+/** How many measure entries the timeline currently holds.
+ *
+ * Recorded next to the heap counters so a memory log shows whether retained growth tracks the
+ * render count. Entries cleared by `clearReactMeasures` leave the count at zero.
+ * @returns Entry count, or undefined on a runtime without a readable timeline.
+ */
+export declare function measureCount(): number | undefined;

package/dist/controller/perf-measures.js

@@ -0,0 +1,78 @@
+/** Drop the render measurements React's development build appends to the global performance timeline.
+ *
+ * `react-reconciler` emits one `performance.measure()` entry per rendered component when it resolves
+ * to its development build, and Node keeps every entry for the life of the process because
+ * `performance.clearMeasures()` is the only way to release them. Each entry also carries a
+ * `detail.devtools.properties` payload describing the component's props, which is where the memory
+ * actually goes: roughly 1.2 KB per render once the duplicated property names are counted.
+ *
+ * The production build emits no measurements at all, so `src/cli/index.ts` selects it and this
+ * module is a safety net for `DSHT_REACT_DEV=1`, where the development build is deliberate.
+ */
+/** Zero-width space React prefixes to a component's own measure name; see `ReactFiberPerformanceTrack` in react-reconciler. */
+const COMPONENT_PREFIX = '\u200b';
+/** Measure names React passes as an explicit update trigger, or as the label for an errored or recovered boundary. */
+const REACT_NAMES = [
+    'Update', 'Cascading Update', 'Update Blocked', 'Update Suspended', 'Mount', 'Unmount',
+    'Reconnect', 'Disconnect', 'Recovered', 'Errored',
+];
+/** Constructors `performance` uses for invalid input, which a measurement library cannot survive. */
+const PROGRAMMING_ERRORS = ['TypeError', 'RangeError', 'SyntaxError'];
+/** The global performance timeline, when the runtime exposes one.
+ * @returns The timeline, or undefined on a runtime without `performance` or `getEntriesByType`.
+ */
+function timeline() {
+    const candidate = globalThis.performance;
+    return typeof candidate?.getEntriesByType === 'function' ? candidate : undefined;
+}
+/** Measure names the current timeline holds that React created.
+ *
+ * A name only counts when it is exactly one of `REACT_NAMES` or carries React's zero-width prefix,
+ * so entries an application or a library created under its own name are never selected.
+ * @param performance - Timeline to read.
+ * @returns Names React created, without duplicates.
+ */
+export function reactMeasureNames(performance) {
+    const names = new Set();
+    for (const entry of performance.getEntriesByType('measure')) {
+        const name = entry.name;
+        if (name.startsWith(COMPONENT_PREFIX))
+            names.add(name);
+        else if (REACT_NAMES.includes(name))
+            names.add(name);
+    }
+    return [...names];
+}
+/** Remove React's render measurements, and only those, from the global performance timeline.
+ *
+ * Intended to run on the memory-sampling interval: the development build keeps appending, so one
+ * pass only bounds the total instead of ending it. A failure is not worth propagating, because this
+ * is a bounded diagnostic and a measurement library that rejects input should not stop the client.
+ * @returns How many distinct measure names were cleared.
+ */
+export function clearReactMeasures() {
+    const performance = timeline();
+    if (performance === undefined)
+        return 0;
+    const names = reactMeasureNames(performance);
+    for (const name of names) {
+        try {
+            performance.clearMeasures(name);
+        }
+        catch (error) {
+            if (!PROGRAMMING_ERRORS.includes(error?.name ?? ''))
+                throw error;
+        }
+    }
+    return names.length;
+}
+/** How many measure entries the timeline currently holds.
+ *
+ * Recorded next to the heap counters so a memory log shows whether retained growth tracks the
+ * render count. Entries cleared by `clearReactMeasures` leave the count at zero.
+ * @returns Entry count, or undefined on a runtime without a readable timeline.
+ */
+export function measureCount() {
+    const performance = timeline();
+    return performance?.getEntriesByType('measure').length;
+}

package/dist/cost/config.d.ts

@@ -0,0 +1,17 @@
+import type { PriceVersion } from './types.ts';
+/** Load the price table, seeding the file on first use and refreshing a copy the user never edited.
+ *
+ * `prices.json` overrides the shipped table, so a correction to the shipped rates would otherwise
+ * never reach an install that already had the file — which is how a superseded Flash table kept
+ * charging 1.5x for input after it was fixed. The stamp records the seeded bytes: while the file
+ * still hashes to them the tool owns it and follows the shipped table, and the first edit makes the
+ * file authoritative, so no rate the user chose is ever overwritten.
+ * @param directory - Configuration directory holding `prices.json`.
+ * @param shipped - Table this build ships, seeded on first use and followed while the file is untouched.
+ * @returns The validated table, and whether it came from a file the user maintains.
+ * @throws when the file exists but is not a valid table.
+ */
+export declare function loadPrices(directory: string, shipped?: PriceVersion[]): Promise<{
+    prices: PriceVersion[];
+    custom: boolean;
+}>;

package/dist/cost/config.js

@@ -0,0 +1,68 @@
+/** Seed, migrate and load the price configuration that overrides the shipped table. */
+import { createHash } from 'node:crypto';
+import { join } from 'node:path';
+import { createPrivateFile, readText, writePrivateFile } from "../storage/index.js";
+import { DEFAULT_PRICES, PRICES_REVISION, isUncorrectedSeed, pricesFrom } from "./pricing.js";
+/** Load the price table, seeding the file on first use and refreshing a copy the user never edited.
+ *
+ * `prices.json` overrides the shipped table, so a correction to the shipped rates would otherwise
+ * never reach an install that already had the file — which is how a superseded Flash table kept
+ * charging 1.5x for input after it was fixed. The stamp records the seeded bytes: while the file
+ * still hashes to them the tool owns it and follows the shipped table, and the first edit makes the
+ * file authoritative, so no rate the user chose is ever overwritten.
+ * @param directory - Configuration directory holding `prices.json`.
+ * @param shipped - Table this build ships, seeded on first use and followed while the file is untouched.
+ * @returns The validated table, and whether it came from a file the user maintains.
+ * @throws when the file exists but is not a valid table.
+ */
+export async function loadPrices(directory, shipped = DEFAULT_PRICES) {
+    const path = join(directory, 'prices.json');
+    const stampPath = join(directory, 'prices.seed.json');
+    const seeded = `${JSON.stringify(shipped, null, 2)}\n`;
+    const raw = await readText(path);
+    if (raw === undefined) {
+        await createPrivateFile(path, seeded);
+        await writePrivateFile(stampPath, stamp(seeded));
+        return { prices: shipped, custom: false };
+    }
+    const prices = pricesFrom(JSON.parse(raw));
+    const recorded = await readStamp(stampPath);
+    // A file without a stamp predates the record; only the superseded shipped seed is recognized there,
+    // because anything else may be a table the user wrote by hand.
+    const owned = recorded === undefined ? isUncorrectedSeed(prices) : recorded === hash(raw);
+    if (!owned)
+        return { prices, custom: true };
+    // Write only what a corrected table actually changed, so an unchanged file needs no write at all
+    // and a read-only configuration directory still starts.
+    if (raw !== seeded)
+        await writePrivateFile(path, seeded);
+    if (recorded !== hash(seeded))
+        await writePrivateFile(stampPath, stamp(seeded));
+    return { prices: shipped, custom: false };
+}
+/** Sha256 of one file's contents.
+ * @param contents - Exact file text.
+ * @returns Lowercase hex digest.
+ */
+function hash(contents) { return createHash('sha256').update(contents).digest('hex'); }
+/** Serialize the stamp written beside a seeded table.
+ * @param contents - Exact seeded text.
+ * @returns Stamp file contents.
+ */
+function stamp(contents) { return `${JSON.stringify({ revision: PRICES_REVISION, hash: hash(contents) }, null, 2)}\n`; }
+/** Read the seed stamp, tolerating a stamp written by another revision.
+ * @param path - Stamp file path.
+ * @returns The digest recorded for the seeded file, or undefined when no stamp applies.
+ */
+async function readStamp(path) {
+    const raw = await readText(path);
+    if (raw === undefined)
+        return;
+    try {
+        const parsed = JSON.parse(raw);
+        return typeof parsed.hash === 'string' ? parsed.hash : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/cost/controller.d.ts

@@ -21,9 +21,16 @@ export declare class CostController {
     private timer;
     private updates;
     constructor(ledger: CostLedger, host: CostHost);
-    /** Scan immediately, then once a minute while online. */
+    /** Scan immediately, then once a minute while online.
+     *
+     * Every generation starts with no skip bookkeeping, because the host keeps running while this
+     * client is not connected: an update time this client already recorded cannot prove that nothing
+     * happened during the gap, so the first scan of the generation reads every session's history
+     * again. Within that generation the recorded times keep the minute timer from re-reading idle
+     * sessions.
+     */
     start(): void;
-    /** Stop the timer and wait for an in-flight scan; the ledger keeps its cached charges. */
+    /** Stop the timer and wait for an in-flight scan; the ledger keeps its folded totals. */
     stop(): Promise<void>;
     /** Refresh after the host reports a turn complete. */
     onTurnIdle(): void;

package/dist/cost/controller.js

@@ -14,15 +14,23 @@ export class CostController {
         this.ledger = ledger;
         this.host = host;
     }
-    /** Scan immediately, then once a minute while online. */
+    /** Scan immediately, then once a minute while online.
+     *
+     * Every generation starts with no skip bookkeeping, because the host keeps running while this
+     * client is not connected: an update time this client already recorded cannot prove that nothing
+     * happened during the gap, so the first scan of the generation reads every session's history
+     * again. Within that generation the recorded times keep the minute timer from re-reading idle
+     * sessions.
+     */
     start() {
         if (this.timer)
             return;
+        this.updates.clear();
         void this.refresh().catch(() => undefined);
         this.timer = setInterval(() => { if (this.host.online())
             void this.refresh().catch(() => undefined); }, REFRESH_INTERVAL_MS);
     }
-    /** Stop the timer and wait for an in-flight scan; the ledger keeps its cached charges. */
+    /** Stop the timer and wait for an in-flight scan; the ledger keeps its folded totals. */
     async stop() {
         clearInterval(this.timer);
         this.timer = undefined;

package/dist/cost/index.d.ts

@@ -1,9 +1,10 @@
-/** Cost domain: price tables, record folding, the immutable ledger, the scanner and its controller. */
+/** Cost domain: price tables, record folding, the folded ledger, the scanner and its controller. */
 export { CostController } from './controller.ts';
 export type { CostHost } from './controller.ts';
 export { CostLedger, costText } from './ledger.ts';
-export { chargeFor, costDay, DEFAULT_PRICES, lowestPrice, priceAt, pricesFrom } from './pricing.ts';
+export { loadPrices } from './config.ts';
+export { candidates, canonicalModel, chargeFor, costDay, DEFAULT_PRICES, isUncorrectedSeed, priceAt, PRICES_REVISION, PRICING_ENGINE_VERSION, pricesDigest, pricesFrom } from './pricing.ts';
 export { costRecords, foldSamples } from './records.ts';
 export { costAddresses, sessionCostHistory } from './scanner.ts';
-export { MISSING_USAGE } from './types.ts';
-export type { Charge, ChargeSample, CostTotal, Coverage, PriceDecision, PriceVersion, Rates, SavedCost, Usage } from './types.ts';
+export { MISSING_TIME, MISSING_USAGE, UNSUPPORTED_USAGE } from './types.ts';
+export type { ChargeSample, CostTotal, Coverage, DayTotal, PriceDecision, PriceVersion, Rates, SavedCost, Usage } from './types.ts';

package/dist/cost/index.js

@@ -1,7 +1,8 @@
-/** Cost domain: price tables, record folding, the immutable ledger, the scanner and its controller. */
+/** Cost domain: price tables, record folding, the folded ledger, the scanner and its controller. */
 export { CostController } from "./controller.js";
 export { CostLedger, costText } from "./ledger.js";
-export { chargeFor, costDay, DEFAULT_PRICES, lowestPrice, priceAt, pricesFrom } from "./pricing.js";
+export { loadPrices } from "./config.js";
+export { candidates, canonicalModel, chargeFor, costDay, DEFAULT_PRICES, isUncorrectedSeed, priceAt, PRICES_REVISION, PRICING_ENGINE_VERSION, pricesDigest, pricesFrom } from "./pricing.js";
 export { costRecords, foldSamples } from "./records.js";
 export { costAddresses, sessionCostHistory } from "./scanner.js";
-export { MISSING_USAGE } from "./types.js";
+export { MISSING_TIME, MISSING_USAGE, UNSUPPORTED_USAGE } from "./types.js";

package/dist/cost/ledger-files.d.ts

@@ -1,18 +1,14 @@
 import type { SavedCost } from './types.ts';
-/** Load every session's newest cut, leaving one fixed file per session.
- *
- * A file of another generation, a file with an unreadable shape, and a cut file superseded by the
- * newer name all describe work the next scan rebuilds, so loading removes them; the newest slice
- * of a superseded name is rewritten under the fixed one first. Files this unit does not own are
- * left where they are.
+/** Load every session's stored totals; a file this build cannot read is left for the next scan.
  * @param directory - Origin-scoped ledger directory, or undefined when persistence is disabled.
  * @returns The newest saved slice per session identity.
  */
 export declare function loadLedgers(directory: string | undefined): Promise<Map<string, SavedCost>>;
-/** Write one session cut unless the directory already holds a newer one.
+/** Write one session's totals unless the directory already holds a newer scan.
  *
  * The file is the system of record across processes, so a scan that opened an older snapshot must
- * not replace a cut another scan already persisted.
+ * not replace a cut another scan already persisted, and a process holding older decision rules must
+ * not seal its totals over newer ones.
  * @param directory - Origin-scoped ledger directory.
  * @param saved - Complete slice to persist.
  * @returns Whether the directory now holds this slice.