@itookit/dsht 0.5.2 → 0.6.0

package/README.md

@@ -345,7 +345,7 @@ Tab completes the leading slash command, extending an ambiguous draft to the sha
 | `/permission [preset]` | View or switch the host sandbox/approval preset |
 | `/feedback TEXT` | Record feedback about the current session |
 | `/handoff` | Delete the local HANDOFF.md, then have the agent write a fresh session handoff |
-| `/loop [name\|stop\|answer] [score] [tries]` | Pick a `loop.yaml` record from a list, edit the inputs and limits it starts from, then run the scored loop; `stop`/`abort` ends the run and `answer TEXT` supplies what a paused verifier asked for |
+| `/loop [name\|stop\|answer] [score] [tries]` | Pick a loop record from a list, edit the inputs and limits it starts from, then run the scored loop; records are the shipped `loop.yaml` with any `loop.yaml` from the config directory merged over it; `stop`/`abort` ends the run and `answer TEXT` supplies what a paused verifier asked for |
 | `/export [local.zip]` | Download the session log ZIP to a new local file |
 | `/export-html [local.html]` | Save the loaded conversation as offline HTML with diagrams and math |
 | `/coredump [tag]` | Write a V8 heap snapshot to the working directory for memory diagnosis |
@@ -374,6 +374,8 @@ A command that would write to the conversation while the agent is working — `/
 
 `/loop [name|stop|answer] [score] [tries]` runs one record from `loop.yaml` as a **client-driven** loop, and it is meant to be chosen rather than typed. Typing `/loop` lists every record under the composer with its rounds, artifact, declared defaults and any input it is pointed at; ↑/↓ selects, Enter confirms the highlighted record, and Tab inserts its name for anyone who wants to add flags. Confirming opens a parameter list pre-filled with that record's own inputs first — for `designdoc-review`, the `path` of the document under review — followed by the shared limits `From`, `To`, `Pass`, `Tries`; a value is replaced by typing over it, the inputs as free text and the limits as numbers checked exactly as the flags are, leaving a row with the arrows or Enter commits what was typed so no box needs its own confirmation, `Start run` launches, and `← Choose another record` goes back; nothing runs until Start is pressed, so a default is always visible before it is spent. Editing a record's input retargets that one run and leaves `loop.yaml` alone, so `designdoc-review` reviews any document and `design-review` is unaffected. Passing any flag on the line (`/loop design-review 9 3`, `--from`, `--to`, `--score`, `--tries`) skips the form and runs exactly what was typed, which keeps scripted and headless use unchanged, and a name that does not exist lists the records that do. The record itself owns the rounds, their checklists, any extra standard, its fixed inputs and the defaults: this client sends the round's brief, an independent `dsht` process verifies the work in a session of its own and writes a verdict file back, and the client decides what comes next — a score at or above the passing mark advances to the next round, a lower score costs one attempt, and a round that exhausts its budget stops the run. The shipped records are `design-review` (ten rounds over the module design) and `designdoc-review` (the same loop over the document named by the record's `vars.path`, keeping one review file per document next to it — `tui-design.md.review.md`, `loop.md.review.md` — so retargeting a run never reads or overwrites another document's rounds; that file is a template in the record, `{{path}}.review.md`, and it is gitignored). `blocked` stops the run at once instead of spending the attempt budget, a verifier that cannot judge asks for a person instead and stops it the same way (headless runs exit 3), a round is only accepted once the client itself has checked that the round's own section reached the artifact file, and `--deadline <minutes>` bounds the whole run. A `passed` run only ever claims the rounds it covered and says which ones (`rounds 1–3/10 · selected range`); a run over the whole record ends on the consolidation round, whose verifier is handed every earlier round's checklist to re-check, so a later round that broke an earlier requirement cannot pass unnoticed. A round that starts by verifying runs inside the forked verifier's own session, so the selected session's conversation stays empty until a round fails and asks the agent to work; the progress line says `verifying step N · attempt M` while that check runs, the status bar reports the same work (`◐` with the loop's step) instead of claiming Ready, and a verifier that cannot produce a verdict reports a structured reason — its exit code plus what the child itself reported (no JSON verdict in the reply, or no reply committed after the turn) rather than the class of its error output alone — instead of waiting in silence, and the verifier is handed the run's own inputs, so it cannot judge a document the artifact only mentions from an earlier run, and `--trace-verbose` adds the sanitized last line. A progress line above the composer shows the round, attempt and best score; sending an ordinary message, `/loop stop`, `/cancel`, Esc, Ctrl+C, switching sessions or losing the connection all stop the loop, which is never persisted. `/loop stop` is a control command, so it is admitted while the run is in flight; with nothing running it says so instead of failing, and the finished run's progress line stays readable — the line that ended it still shows the result, and the next line you run clears it. A verifier that cannot judge *pauses* the run instead of ending it: the progress line and the status bar say `needs you`, `/loop answer TEXT` adds the missing condition and re-judges the current artifact under a new verification identity without spending an attempt or sending the agent anything, and `/loop abort` (the paused spelling of `/loop stop`) ends the run.
 
+The shipped `loop.yaml` is read at startup rather than compiled in, so the records are configuration: the file travels in the package, and a `loop.yaml` in the configuration directory (`$DSHT_CONFIG_DIR`, default `~/.config/dsht`) layers over it. A record with the same name **replaces** the shipped one whole, a new name adds a record, and every record your file does not name keeps following the package — which is why an upgrade still fixes shipped records you did not override. `DSHT_LOOP_FILE` points at another file instead. The record list says so: rows from your file are marked `· yours` and the file is named above them. An invalid file stops the client at startup with the path and the field at fault; a shipped file that cannot be read falls back to the records compiled into the build. Because a record you override can never be updated for you, the shipped definition's digest is stamped under the state directory and the first start after it changes reports that the shipped update is not reaching your copy — your file still wins, and nothing ever rewrites it.
+
 A file reference sends only `@path` in a text block. Harness instructs the model to read the referenced file or list the directory when needed; the TUI does not read local files, upload bytes, or expand contents into the prompt. Referencing an image path does not attach image data. Local attachments, image uploads/previews, and `@` session references are not implemented.
 
 Pending ordinary messages appear inside the composer, with up to two previews. `/queue` opens the full pending-input picker; ↑/↓ selects and Enter, `d`, or the dedicated Delete key removes an item through the host. Esc closes this picker without cancelling the task. A claimed item is no longer removable; the host reports that race instead of resubmitting it. The control stream owns the list, including reconnect replacement and removal when input is claimed; the client does not keep a second submission queue. Questions and approvals take precedence over queue navigation, and their answers never become steering. Slash commands keep their own execution semantics. Queue previews and deletion require the host `session/control` and `session/updateQueue` capabilities.
@@ -434,7 +436,9 @@ The default price validity starts at Beijing midnight on the verification date;
 
 On first interactive launch, the client creates `~/.config/dsht/prices.json` (or `$XDG_CONFIG_HOME/dsht/prices.json`). `DSHT_CONFIG_DIR` overrides that directory. The JSON array contains price versions with `id`, `provider`, `model`, `currency: "CNY"`, `source`, inclusive `from`, optional exclusive `until`, `timezone`, weekday numbers (`0` Sunday), minute-of-day `windows`, and `peak`/`offPeak` rates named `input`, `cacheRead`, `cacheWrite`, `output`, per million tokens. To update prices, close the old interval with `until` and append a new version with a unique ID and matching `from`; overlapping intervals are rejected. Restart to load configuration changes. Price discovery is manual; the TUI does not scrape prices during startup.
 
-Usage files live under `~/.local/state/dsht/cost/<origin-hash>/` (respecting `XDG_STATE_HOME`, or `DSHT_STATE_DIR` for the application state root). Each holds one session's folded totals: the session amount with its request and unpriced counts, the day bucket its last scan ran on, the decision-rules revision and a digest of the price table that produced them, and the reasons a total is inexact. They exclude prompts, tool bodies, credentials, cookies, and every per-request fact. The price file is configuration and these usage files are state, so only the former belongs in a settings backup. Writes use private temporary files and atomic replacement; each session keeps one fixed file whose recorded cut and rules revision are compared before writing, so an older scan cannot displace a newer one. The cache survives restart and does not need access to the host configuration directory. A file of another generation is ignored and rebuilt by the next scan.
+Usage files live under `~/.local/state/dsht/cost/<origin-hash>/` (respecting `XDG_STATE_HOME`, or `DSHT_STATE_DIR` for the application state root). Each holds one session's folded totals: the session amount with its request and unpriced counts, one bucket per Beijing calendar day the session spent inside the retained window, the decision-rules revision and a digest of the price table that produced them, and the reasons a total is inexact. They exclude prompts, tool bodies, credentials, cookies, and every per-request fact. The price file is configuration and these usage files are state, so only the former belongs in a settings backup. Writes use private temporary files and atomic replacement; each session keeps one fixed file whose recorded cut and rules revision are compared before writing, so an older scan cannot displace a newer one. The cache survives restart and does not need access to the host configuration directory. A file of another generation is ignored and rebuilt by the next scan; so is an unreadable one, because a slice is a projection of the host log rather than a system of record.
+
+The window is 60 Beijing days. Days older than that are dropped as a slice is written, and a slice whose newest day has left the window is deleted at startup, as is any ledger file — readable or not — whose file time is older than the window, so the directory cannot grow with every session this client has ever seen; letting one go costs a rescan of that session, never data. `/cost` reports the session, today, this week (from Monday) and this month (from the 1st), each counted through the current Beijing day, and the week and month rows reach back only as far as the retained window. A scan pages a session's history only when it could have spent inside that window — a session that is running, or whose host update time is inside it — plus the session on screen, whose own total the panel always reports. Billable activity moves that update time, so usage recorded while this client was away is still read on the next connection.
 
 ## Client API
 

package/README.zh.md

@@ -345,7 +345,7 @@ Tab 补全开头的 slash 命令，多个候选时补到公共前缀；回车也
 | `/permission [preset]` | 查看或切换服务端沙箱与审批预设 |
 | `/feedback TEXT` | 记录当前会话反馈 |
 | `/handoff` | 先删除本地 HANDOFF.md，再让 agent 写出新的会话交接文档 |
-| `/loop [name\|stop\|answer] [score] [tries]` | 用列表选择 `loop.yaml` 记录，修改它启动时用的输入与限制后再运行评分循环；`stop`／`abort` 结束当前运行，`answer TEXT` 补上验证者要的判断条件 |
+| `/loop [name\|stop\|answer] [score] [tries]` | 用列表选择循环记录（随包 `loop.yaml` 与配置目录中的 `loop.yaml` 合并），修改它启动时用的输入与限制后再运行评分循环；`stop`／`abort` 结束当前运行，`answer TEXT` 补上验证者要的判断条件 |
 | `/export [local.zip]` | 下载会话日志 ZIP 到新的本地文件 |
 | `/export-html [local.html]` | 将已加载会话保存为包含图表和公式的离线 HTML |
 | `/coredump [tag]` | 在当前工作目录写出 V8 堆快照，用于内存诊断 |
@@ -374,6 +374,8 @@ Slash 命令在选择器和对话输入框中均可使用。输入 `/` 会显示
 
 `/loop [name|stop|answer] [score] [tries]` 运行 `loop.yaml` 里的一条记录，是一条**客户端驱动**的循环，并且设计成"选"而不是"敲"。输入 `/loop` 会在输入框下方列出所有记录及其轮数、产出物、自带默认值和它指向的输入；↑/↓ 选择，Enter 确认高亮记录，Tab 则把记录名补进草稿以便继续加旗标。确认后会打开参数列表：**先是该记录自己的输入**（如 `designdoc-review` 的 `path`，即被审查的文档），**再是共享的四个值**（`From`、`To`、`Pass`、`Tries`）；选中某行直接输入即可覆盖——输入按自由文本，四个值按数字、与旗标同一套校验；用方向键或 Enter 离开某行即提交该行的内容，因此不需要在每个框里各按一次回车；`Start run` 开始运行，`← Choose another record` 返回记录列表；只有按下 Start 才会真正启动，因此每个默认值都在被花掉之前可见。改一条记录的输入只作用于本次运行、不改 `loop.yaml`，所以 `designdoc-review` 可以审查任意文档，而 `design-review` 不受影响。若命令行里写了任一旗标（`/loop design-review 9 3`、`--from`、`--to`、`--score`、`--tries`），则跳过表单、按所写的值直接运行，脚本与 headless 用法因此保持不变；名字不存在时会列出可用记录。轮次、每轮检查要点、附加标准、固定输入与默认值都由记录自带：本客户端发出本轮 Brief，由 dsht fork 出的独立进程在自己的 session 里验证并把 verdict 文件写回，客户端据此决定下一步——达到及格线进入下一轮，低于及格线消耗一次尝试，某轮用尽预算则停止。内置记录有 `design-review`（对模块设计做十轮审查）与 `designdoc-review`（同一循环，审查记录 `vars.path` 指定的文档，并**一份文档一个审查文件、就放在它旁边**（`tui-design.md.review.md`、`loop.md.review.md`），所以换文档重跑既不会读到也不会覆盖另一份文档的轮次；这个文件名在记录里是模板 `{{path}}.review.md`，且已被 `.gitignore` 覆盖）。`status` 为 `blocked` 时立即停止、不再消耗尝试预算；验证者无法判断时会要求人工介入并以同样方式停止（headless 退出码 3）；只有客户端自己核对过「本轮小节确实写进了产出物文件」的轮次才算通过；`--deadline <minutes>` 约束整个 run。`passed` 只声称本次 run 覆盖的轮次并写明是哪些（`rounds 1–3/10 · selected range`）；跑完整份记录时最后一轮是收束轮，它的验证者会拿到前面每一轮的检查要点逐轮复核，因此后来某一轮改坏了前序要求不会被放过。以"先验证"开始的一轮（`starts: verify` 且有 forked verifier）跑在独立验证进程自己的 session 里，因此当前会话的 history 不会出现内容，直到某一轮未通过、才要求 agent 去工作；验证进行期间进度行显示 `verifying step N · attempt M`，状态栏也如实显示同一件事（`◐` 加本轮 `review N/M`）而不是 Ready；验证者拿不出 verdict 时会给出结构化原因——退出码 ＋ 子进程自己报告的原因（回复里没有 JSON 判定、或回复在 turn 结束后仍未提交），而不是只给错误输出类别，更不是无声等待；同时验证者会拿到本次 run 自己的输入，因此不会去评审产出物里只属于更早那次 run 的文档，`--trace-verbose` 才会附上脱敏后的最后一行。输入框上方的进度行显示轮次、尝试与最高分；发送普通消息、`/loop stop`、`/cancel`、Esc、Ctrl+C、切换会话或断线都会停止循环，该状态不持久化：`/loop stop` 属于控制泳道，运行期间也允许提交；没有运行时它会直接说明而不是报错，且已结束运行的那行进度会保留可读——结束它的那一行仍然显示结果，而你运行下一行时它就被清掉。验证者无法判决时 run 会**暂停**而不是结束：进度行与状态栏显示 `needs you`，`/loop answer TEXT` 补上缺的判断条件、以新的 verification identity 重新判断当前产出物——不消耗尝试次数，也不给 agent 发任何东西；`/loop abort`（`/loop stop` 在暂停期的拼写）结束它。
 
+随包发布的 `loop.yaml` 在启动时读取，而不是编译期写死，因此记录是配置：文件随包分发，配置目录（`$DSHT_CONFIG_DIR`，默认 `~/.config/dsht`）下的 `loop.yaml` 叠加其上。同名记录**整条替换**内置记录，新名字新增一条记录，你没有点名的记录继续跟随包内版本——这正是升级仍能修好你没覆盖的内置记录的原因。`DSHT_LOOP_FILE` 可改指另一个文件。记录列表会把这件事说出来：来自你的文件的行标 `· yours`，并在上方写明文件名。文件非法时启动即失败，并给出行路径与出错字段；内置文件读不到时回退到编译进包的记录。被你覆盖的那条记录无法再为你自动更新，因此其内置定义的摘要会记在 state 目录下，内置定义变化后的第一次启动会提示"内置更新没有到达你的副本"——你的文件仍然生效，且任何情况下都不会被改写。
+
 文件引用仅在文本块中发送 `@path`。Harness 提示模型按需读取文件或列出目录；TUI 不读取本地文件、不上传字节，也不将文件内容展开进提示词。引用图片路径不会附带图片数据。尚未实现本地附件、图片上传／预览及 `@` 会话引用。
 
 待处理的普通消息显示在输入框内，最多预览两条。`/queue` 打开完整的待处理输入列表，↑／↓ 选择，Enter、`d` 或独立 Delete 键通过服务端删除。Esc 仅关闭此列表，不取消任务。消息已被领取后无法删除，服务端会提示该竞争情况，客户端不会重新发送。控制流负责列表、重连替换及消息领取后的移除，客户端不维护第二份发送队列。问题和审批优先于队列导航，其回答不会成为转向输入；slash 命令仍按各自语义执行。队列预览和删除需要服务端提供 `session/control` 与 `session/updateQueue`。
@@ -434,7 +436,9 @@ Slash 命令在选择器和对话输入框中均可使用。输入 `/` 会显示
 
 首次交互启动会创建 `~/.config/dsht/prices.json`（或 `$XDG_CONFIG_HOME/dsht/prices.json`），可用 `DSHT_CONFIG_DIR` 覆盖目录。JSON 数组中的价格版本包含 `id`、`provider`、`model`、`currency: "CNY"`、`source`、包含起点的 `from`、可选且不含终点的 `until`、`timezone`、星期数字 `weekdays`（`0` 为周日）、日内分钟区间 `windows`，以及 `peak`／`offPeak` 下每百万 token 的 `input`、`cacheRead`、`cacheWrite`、`output` 单价。调价时用 `until` 结束旧区间，再添加唯一 ID 且 `from` 衔接的新版本；程序拒绝重叠区间。重启后读取配置修改；价格由用户维护，启动时不抓取网页价格。
 
-用量文件位于 `~/.local/state/dsht/cost/<origin-hash>/`，遵循 `XDG_STATE_HOME`，也可通过 `DSHT_STATE_DIR` 指定应用状态根目录。每个文件保存一个会话折叠后的总额：会话金额及其请求数与未计价数、最近一次扫描所在自然日的当天分桶、决策规则版本与该次折叠所用价格表的摘要，以及总额不精确的原因。文件不含提示词、工具正文、凭据、cookie，也不含任何逐请求信息。价格文件属于配置，这些用量文件属于状态，因此只有前者需要纳入设置备份。写入使用私有临时文件及原子替换；每个会话一个固定文件，写入前比较文件中记录的 cut 与规则版本，因此旧扫描无法覆盖较新的一次。缓存跨重启保留，不需要访问服务端配置目录。其他代数的文件会被忽略，并由下一次扫描重建。
+用量文件位于 `~/.local/state/dsht/cost/<origin-hash>/`，遵循 `XDG_STATE_HOME`，也可通过 `DSHT_STATE_DIR` 指定应用状态根目录。每个文件保存一个会话折叠后的总额：会话金额及其请求数与未计价数、该会话在保留窗口内每个自然日一个分桶、决策规则版本与该次折叠所用价格表的摘要，以及总额不精确的原因。文件不含提示词、工具正文、凭据、cookie，也不含任何逐请求信息。价格文件属于配置，这些用量文件属于状态，因此只有前者需要纳入设置备份。写入使用私有临时文件及原子替换；每个会话一个固定文件，写入前比较文件中记录的 cut 与规则版本，因此旧扫描无法覆盖较新的一次。缓存跨重启保留，不需要访问服务端配置目录。其他代数的文件会被忽略并由下一次扫描重建；无法解析的文件同样如此，因为切片是服务端日志的投影，而不是账本本身。
+
+保留窗口是 60 个北京自然日。更早的日子在写入切片时被丢弃，最新一天已滑出窗口的切片会在启动时删除；任何账本文件——无论能否解析——只要文件时间早于窗口起点也会一并清掉，因此该目录不会随客户端见过的会话数无限增长；放掉一个切片只会让该会话被重扫一次，不会丢数据。`/cost` 显示会话、今天、本周（周一起算）与本自然月（1 日起算）四项，都统计到当前北京自然日；周与月两行只能回溯到保留窗口能覆盖的范围。扫描只在会话「可能在本窗口内产生过花费」时才翻它的历史——会话正在运行，或其服务端更新时间落在窗口内——外加当前打开的会话（面板总要报它自己的总额）。任何计费活动都会推进该更新时间，因此客户端离线期间产生的用量在下次连接时仍会被读到。
 
 ## 客户端接口
 

package/dist/cli/dsht.js

@@ -15,6 +15,8 @@ import { fileURLToPath } from 'node:url';
 import { historyLimits } from "../session/memory.js";
 import { ProcessVerifier } from "./verifier.js";
 import { Controller } from "../controller/controller.js";
+import { loadLoopSource } from "../controller/loop-source.js";
+import { installLoopSource } from "../controller/loop-prompts.js";
 import { endpoint } from "../transport/endpoint.js";
 import { errorText, object, string } from "../transport/wire.js";
 import { formatTraceSummary, summarizeTrace } from "./trace-summary.js";
@@ -51,10 +53,12 @@ With no command, choose a workspace and session interactively.
 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 the session and today CNY estimates.
+/cost shows the session, day, week and month CNY estimates.
 /prompt lists saved shortcut prompts; /prompt TEXT saves one in <state>/prompts.json.
 !command runs on this machine, not on the host, and prints its output in the transcript.
 DSHT_CONFIG_DIR overrides the prices.json directory; DSHT_STATE_DIR overrides usage storage.
+The shipped loop.yaml is read at startup; a loop.yaml in the config directory adds to it, and a
+record with the same name replaces the shipped one. DSHT_LOOP_FILE names another file instead.
 The memory log defaults to <state>/memory.log; DSHT_MEMORY_LOG sets another path or 'off'.
 The transition trace defaults to <state>/trace.log; DSHT_TRACE sets another path or 'off'.
 prices.json overrides the shipped rates and is seeded on first use; every scan re-decides the
@@ -151,6 +155,15 @@ async function main() {
     await ensureDirectory(config);
     const { prices, custom } = await loadPrices(config);
     const stateRoot = process.env.DSHT_STATE_DIR ?? join(process.env.XDG_STATE_HOME ?? join(homedir(), '.local', 'state'), 'dsht');
+    // The loop records are configuration: the shipped file is read now, a user file layered over it and
+    // the result installed before anything can list or run a record. An invalid user file stops the
+    // client here rather than running shipped records while the operator believes their own are in
+    // force; a shipped file that cannot be read falls back to the compiled-in records with a warning.
+    const loopSource = await loadLoopSource({
+        ...(process.env.DSHT_LOOP_FILE === undefined ? {} : { overlayFile: process.env.DSHT_LOOP_FILE }),
+        configDirectory: config, stateDirectory: stateRoot,
+    });
+    installLoopSource(loopSource.source, loopSource.info);
     const costDirectory = join(stateRoot, 'cost', createHash('sha256').update(new URL(url).origin).digest('hex'));
     const costs = new CostLedger(prices, costDirectory, custom);
     await costs.load();
@@ -202,6 +215,10 @@ async function main() {
         timeoutSeconds: 3600,
     };
     const log = (line) => process.stderr.write(`${line}\n`);
+    // Headless runs have no record list, so the loop source's notes would otherwise never be read.
+    if (values.headless)
+        for (const warning of loopSource.info.warnings)
+            log(warning);
     controller.start();
     if (values.headless) {
         // No renderer: run the plan, follow a started loop to its verdict, and report it as the exit code.

package/dist/contracts.d.ts

@@ -39,6 +39,26 @@ export interface SavedPrompt {
 }
 /** One panel-like surface the reader can see; the application names it, the UI renders it. */
 export type PanelName = 'help' | 'cost' | 'status' | 'queue' | 'prompts' | 'thoughts' | 'history' | 'search' | 'model' | 'removal' | 'loop';
+/** Where the loop records one client runs came from.
+ *
+ * The shipped file travels with the package and a user file may layer over it, so a record list is no
+ * longer one file's content: this says which files were read and which records the user's own file
+ * replaced or added. The warnings are the client's own notes — a shipped file it could not read, or a
+ * record the user overrides that the package has since changed — and the UI shows them rather than
+ * acting on them.
+ */
+export interface LoopSourceInfo {
+    /** Shipped `loop.yaml` that was read; absent when the compiled-in records were used instead. */
+    builtin?: string;
+    /** User file layered over the shipped records; absent when there is none. */
+    file?: string;
+    /** Shipped records the user's file replaced, in that file's order. */
+    overridden: readonly string[];
+    /** Records the user's file added. */
+    added: readonly string[];
+    /** Notes to show the operator, in the order they were discovered. */
+    warnings: readonly string[];
+}
 /** One `loop.yaml` record as the record list offers it.
  *
  * The name is what `/loop` runs; the rest is what a chooser shows about it, plus the defaults a run
@@ -64,6 +84,8 @@ export interface LoopRecord {
      * document under review, a target, a threshold) is retargeted without editing `loop.yaml`.
      */
     vars: Readonly<Record<string, string>>;
+    /** Set when this record came from the user's own file rather than from the shipped one. */
+    fromFile?: true;
 }
 /** The four numbers one loop run uses.
  *

package/dist/controller/controller.d.ts

@@ -15,7 +15,7 @@ import { TraceLog } from './trace-log.ts';
 import { PromptStore } from './prompts.ts';
 import { type LoopLimits, type LoopProtocol } from './loop.ts';
 import type { VerifierPort } from './verifier.ts';
-import type { ClientActivity, ForegroundKind, ForegroundSnapshot, LoopProgress, LoopRecord, OutputSource, PeekSnapshot } from '../contracts.ts';
+import type { ClientActivity, ForegroundKind, ForegroundSnapshot, LoopProgress, LoopRecord, LoopSourceInfo, OutputSource, PeekSnapshot } from '../contracts.ts';
 import { SessionPeek } from '../session/peek.ts';
 import { type ControllerStore, type State } from '../state.ts';
 import { ShellController } from '../shell/index.ts';
@@ -147,6 +147,8 @@ export interface Queries {
     readonly peek: PeekSnapshot | undefined;
     /** Every `loop.yaml` record, so the picker can offer names and their defaults without a lookup. */
     readonly loopRecords: readonly LoopRecord[];
+    /** Where those records came from, so the picker can say which file supplied or replaced them. */
+    readonly loopSource: LoopSourceInfo;
     /** Why the saved prompts could not be read, when the file was malformed. */
     readonly promptsError: string | undefined;
     pendingCounts(): ReadonlyMap<string, number>;

package/dist/controller/controller.js

@@ -17,6 +17,7 @@ import { PromptStore } from "./prompts.js";
 import { latestAssistantText } from "./loop.js";
 import { LoopCoordinator } from "./loop-coordinator.js";
 import { loopRecords as listLoopRecords } from "./loop-protocols.js";
+import { loopSourceInfo } from "./loop-prompts.js";
 import { SessionPeek } from "../session/peek.js";
 import { costAddresses } from "../cost/scanner.js";
 import { sessionLabel } from "../session-title.js";
@@ -172,6 +173,9 @@ export class Controller {
                 online: () => this.state.online,
                 signal: () => this.connection.signal(),
                 publish: () => this.update({}),
+                // The session on screen is scanned whatever its age: `/cost` reports its own total, and the
+                // window filter exists to skip sessions nobody is looking at.
+                selectedSessionId: () => this.state.sessionId,
                 // The scan already reads every session's whole history; handing its pages to the session
                 // domain lets the prompt cache pick them up, so one open does not pay for a second walk.
                 scanPage: (sessionId, records) => this.session.rememberScanPage(sessionId, records),
@@ -388,6 +392,7 @@ export class Controller {
             get peek() { return controller.peekSnapshot(); },
             get activity() { return controller.activity; },
             get loopRecords() { return listLoopRecords(); },
+            get loopSource() { return loopSourceInfo(); },
             pendingCounts: () => controller.pendingCounts(),
             recall: (direction, current) => controller.recall(direction, current),
             references: (query, signal) => controller.references(query, signal),

package/dist/controller/loop-prompts-schema.d.ts

@@ -2,7 +2,11 @@
  *
  * Kept apart from `loop-prompts.ts` so the build script can validate a YAML file before the
  * generated module exists: this module imports nothing, while the renderer imports the generated
- * data. The validator is the single copy of the schema — the generator and the tests both call it.
+ * data. The validator is the single copy of the schema — the generator, the runtime loader and the
+ * tests all call it, so a file that passes here is the one the renderer will read.
+ *
+ * Two entry points share one set of rules: `validateLoopPrompts` checks a whole built-in file, and
+ * `validateLoopOverlayPrompts` checks a user file that may carry only the records it changes.
  */
 /** One round: the label the progress line shows, and the checklist that round is judged against. */
 export interface LoopRoundText {
@@ -34,7 +38,7 @@ export interface LoopProtocolText {
     readonly brief: readonly string[];
     readonly followUp: readonly string[];
 }
-/** The whole document; the generated module is cast to this shape. */
+/** The whole document; the generated module and every parsed file are cast to this shape. */
 export interface LoopPromptSource {
     readonly version: number;
     readonly defaults: {
@@ -54,3 +58,13 @@ export declare const RESERVED_PROTOCOL_NAMES: readonly string[];
  * @returns One message per problem; an empty list means valid.
  */
 export declare function validateLoopPrompts(source: unknown): string[];
+/** Check a user file that layers over the shipped records.
+ *
+ * It is a whole `loop.yaml` in shape, but partial in content: an overlay that only adds one record
+ * or only moves the global defaults is exactly what it is for, so a missing or empty `protocols` is
+ * valid here. Every record it does declare is held to the same rules as a shipped one, because the
+ * renderer cannot tell the two apart once they are merged.
+ * @param source - Parsed overlay file.
+ * @returns One message per problem; an empty list means valid.
+ */
+export declare function validateLoopOverlayPrompts(source: unknown): string[];

package/dist/controller/loop-prompts-schema.js

@@ -2,7 +2,11 @@
  *
  * Kept apart from `loop-prompts.ts` so the build script can validate a YAML file before the
  * generated module exists: this module imports nothing, while the renderer imports the generated
- * data. The validator is the single copy of the schema — the generator and the tests both call it.
+ * data. The validator is the single copy of the schema — the generator, the runtime loader and the
+ * tests all call it, so a file that passes here is the one the renderer will read.
+ *
+ * Two entry points share one set of rules: `validateLoopPrompts` checks a whole built-in file, and
+ * `validateLoopOverlayPrompts` checks a user file that may carry only the records it changes.
  */
 /** Placeholders every template may use; a record's own `vars` add to these. */
 export const LOOP_PLACEHOLDERS = ['from', 'to', 'score', 'tries', 'step', 'attempt', 'title', 'artifact', 'checks'];
@@ -16,18 +20,94 @@ export const RESERVED_PROTOCOL_NAMES = ['answer', 'abort', 'stop'];
  */
 export function validateLoopPrompts(source) {
     const errors = [];
-    const document = source;
-    if (document?.version !== 1)
+    const document = asDocument(source);
+    if (document.version !== 1)
         errors.push('version must be 1');
-    if (!Number.isFinite(document?.defaults?.score))
-        errors.push('defaults.score must be a number');
-    if (!Number.isFinite(document?.defaults?.tries))
-        errors.push('defaults.tries must be a number');
-    const protocols = document?.protocols;
-    if (protocols === null || typeof protocols !== 'object' || Object.keys(protocols ?? {}).length === 0) {
+    validateDefaults(document.defaults, errors, true);
+    const protocols = document.protocols;
+    if (protocols === null || typeof protocols !== 'object' || Array.isArray(protocols) || Object.keys(protocols ?? {}).length === 0) {
         errors.push('protocols must be a non-empty mapping');
         return errors;
     }
+    validateProtocols(protocols, errors);
+    return errors;
+}
+/** Check a user file that layers over the shipped records.
+ *
+ * It is a whole `loop.yaml` in shape, but partial in content: an overlay that only adds one record
+ * or only moves the global defaults is exactly what it is for, so a missing or empty `protocols` is
+ * valid here. Every record it does declare is held to the same rules as a shipped one, because the
+ * renderer cannot tell the two apart once they are merged.
+ * @param source - Parsed overlay file.
+ * @returns One message per problem; an empty list means valid.
+ */
+export function validateLoopOverlayPrompts(source) {
+    const errors = [];
+    const document = asDocument(source);
+    // A version is required even from an overlay: a file written for a later shape must fail loudly
+    // instead of having its fields read as this shape's, which is how a silent misread becomes a run
+    // judged against a rubric nobody wrote.
+    if (document.version !== 1)
+        errors.push('version must be 1');
+    validateDefaults(document.defaults, errors, false);
+    const protocols = document.protocols;
+    if (protocols === undefined || protocols === null)
+        return errors;
+    if (typeof protocols !== 'object' || Array.isArray(protocols)) {
+        errors.push('protocols must be a mapping');
+        return errors;
+    }
+    validateProtocols(protocols, errors);
+    return errors;
+}
+/** A parsed document with every unsafe value normalized to `undefined`.
+ * @param source - Anything a caller parsed out of a file.
+ * @returns The document, or an empty one for a null, scalar or array root.
+ */
+function asDocument(source) {
+    return source !== null && typeof source === 'object' && !Array.isArray(source) ? source : {};
+}
+/** Check the global defaults.
+ *
+ * A shipped file must state them, because every record falls back to them. An overlay may state
+ * neither, one or both, but a value it does state reaches real runs, so it is checked for range
+ * even though the shipped file only has to be numeric.
+ * @param defaults - The `defaults` field as parsed.
+ * @param errors - Collector to append messages to.
+ * @param required - Whether this document must carry both numbers.
+ */
+function validateDefaults(defaults, errors, required) {
+    if (defaults === undefined || defaults === null) {
+        if (required) {
+            errors.push('defaults.score must be a number');
+            errors.push('defaults.tries must be a number');
+        }
+        return;
+    }
+    if (typeof defaults !== 'object' || Array.isArray(defaults)) {
+        errors.push('defaults must be a mapping');
+        return;
+    }
+    const { score, tries } = defaults;
+    if (required) {
+        if (!Number.isFinite(score))
+            errors.push('defaults.score must be a number');
+        if (!Number.isFinite(tries))
+            errors.push('defaults.tries must be a number');
+        return;
+    }
+    if (score !== undefined && (!Number.isFinite(score) || score < 0 || score > 10)) {
+        errors.push('defaults.score must be a number in 0-10');
+    }
+    if (tries !== undefined && (!Number.isInteger(tries) || tries < 1)) {
+        errors.push('defaults.tries must be a positive integer');
+    }
+}
+/** Check every record of one document against the rules the renderer relies on.
+ * @param protocols - The `protocols` mapping.
+ * @param errors - Collector to append messages to.
+ */
+function validateProtocols(protocols, errors) {
     const runtime = new Set(LOOP_PLACEHOLDERS);
     const reserved = new Set(RESERVED_PROTOCOL_NAMES);
     const placeholders = (text) => [...text.matchAll(/\{\{(\w+)\}\}/g)].map(match => match[1]);
@@ -36,7 +116,7 @@ export function validateLoopPrompts(source) {
         if (reserved.has(kind))
             errors.push(`${at} is a reserved name: ${RESERVED_PROTOCOL_NAMES.join(', ')} belong to /loop itself`);
         // A template may name a runtime value or one of this record's own vars, and nothing else.
-        const vars = protocol.vars;
+        const vars = protocol?.vars;
         if (vars !== undefined && (vars === null || typeof vars !== 'object' || Array.isArray(vars))) {
             errors.push(`${at}.vars must be a mapping of names to strings`);
         }
@@ -55,15 +135,15 @@ export function validateLoopPrompts(source) {
                 if (!allowed.has(name))
                     errors.push(`${where}: unknown placeholder {{${name}}}`);
         };
-        checkPlaceholders(typeof protocol.title === 'string' ? protocol.title : '', `${at}.title`);
-        if (typeof protocol.title !== 'string' || protocol.title === '')
+        checkPlaceholders(typeof protocol?.title === 'string' ? protocol.title : '', `${at}.title`);
+        if (typeof protocol?.title !== 'string' || protocol.title === '')
             errors.push(`${at}.title must be a non-empty string`);
-        if (!Number.isInteger(protocol.steps) || (protocol.steps ?? 0) < 1)
+        if (!Number.isInteger(protocol?.steps) || (protocol?.steps ?? 0) < 1)
             errors.push(`${at}.steps must be a positive integer`);
-        if (protocol.artifact !== undefined && (typeof protocol.artifact !== 'string' || protocol.artifact === '')) {
+        if (protocol?.artifact !== undefined && (typeof protocol.artifact !== 'string' || protocol.artifact === '')) {
             errors.push(`${at}.artifact must be a non-empty string when present`);
         }
-        else if (typeof protocol.artifact === 'string') {
+        else if (typeof protocol?.artifact === 'string') {
             // The file name may use the record's vars — that is how one run per input gets its own file —
             // but never a runtime placeholder: the artifact must not move between rounds.
             for (const name of placeholders(protocol.artifact)) {
@@ -72,7 +152,7 @@ export function validateLoopPrompts(source) {
                 }
             }
         }
-        if (protocol.artifactMarker !== undefined) {
+        if (protocol?.artifactMarker !== undefined) {
             if (typeof protocol.artifactMarker !== 'string' || protocol.artifactMarker.trim() === '') {
                 errors.push(`${at}.artifactMarker must be a non-empty string when present`);
             }
@@ -84,28 +164,28 @@ export function validateLoopPrompts(source) {
                 errors.push(`${at}.artifactMarker needs ${at}.artifact: there is no file to look in`);
             }
         }
-        if (typeof protocol.fallbackLabel !== 'string' || protocol.fallbackLabel === '')
+        if (typeof protocol?.fallbackLabel !== 'string' || protocol.fallbackLabel === '')
             errors.push(`${at}.fallbackLabel must be a non-empty string`);
-        if (protocol.standard !== undefined && (typeof protocol.standard !== 'string' || protocol.standard.trim() === '')) {
+        if (protocol?.standard !== undefined && (typeof protocol.standard !== 'string' || protocol.standard.trim() === '')) {
             errors.push(`${at}.standard must be a non-empty string when present`);
         }
-        if (protocol.starts !== undefined && protocol.starts !== 'verify' && protocol.starts !== 'work') {
+        if (protocol?.starts !== undefined && protocol.starts !== 'verify' && protocol.starts !== 'work') {
             errors.push(`${at}.starts must be 'verify' or 'work'`);
         }
-        if (protocol.defaults !== undefined) {
+        if (protocol?.defaults !== undefined) {
             const { score, tries } = protocol.defaults;
             if (score !== undefined && (!Number.isFinite(score) || score < 0 || score > 10))
                 errors.push(`${at}.defaults.score must be a number in 0-10`);
             if (tries !== undefined && (!Number.isInteger(tries) || tries < 1))
                 errors.push(`${at}.defaults.tries must be a positive integer`);
         }
-        const rounds = protocol.rounds;
+        const rounds = protocol?.rounds;
         if (!Array.isArray(rounds)) {
             errors.push(`${at}.rounds must be a list`);
         }
         else {
-            if (rounds.length > 0 && rounds.length !== protocol.steps) {
-                errors.push(`${at}.rounds has ${rounds.length} entries but steps is ${protocol.steps}`);
+            if (rounds.length > 0 && rounds.length !== protocol?.steps) {
+                errors.push(`${at}.rounds has ${rounds.length} entries but steps is ${protocol?.steps}`);
             }
             rounds.forEach((round, index) => {
                 if (typeof round?.title !== 'string' || round.title === '')
@@ -115,7 +195,7 @@ export function validateLoopPrompts(source) {
             });
         }
         for (const key of ['brief', 'followUp']) {
-            const lines = protocol[key];
+            const lines = protocol?.[key];
             if (!Array.isArray(lines) || lines.length === 0) {
                 errors.push(`${at}.${key} must be a non-empty list`);
                 continue;
@@ -128,17 +208,16 @@ export function validateLoopPrompts(source) {
                 checkPlaceholders(line, `${at}.${key}[${index}]`);
             });
         }
-        const checksLines = (protocol.brief ?? []).filter(line => typeof line === 'string' && line.trim() === '{{checks}}');
+        const checksLines = (protocol?.brief ?? []).filter(line => typeof line === 'string' && line.trim() === '{{checks}}');
         if ((rounds?.length ?? 0) > 0 && checksLines.length !== 1)
             errors.push(`${at}.brief must contain exactly one line that is just {{checks}}`);
         if ((rounds?.length ?? 0) === 0 && checksLines.length > 0)
             errors.push(`${at}.brief uses {{checks}} but defines no rounds`);
-        if (protocol.verifyFocus !== undefined) {
+        if (protocol?.verifyFocus !== undefined) {
             if (typeof protocol.verifyFocus !== 'string' || protocol.verifyFocus === '')
                 errors.push(`${at}.verifyFocus must be a non-empty string when present`);
             else
                 checkPlaceholders(protocol.verifyFocus, `${at}.verifyFocus`);
         }
     }
-    return errors;
 }

package/dist/controller/loop-prompts.d.ts

@@ -1,3 +1,5 @@
+import type { LoopSourceInfo } from '../contracts.ts';
+import type { LoopPromptSource } from './loop-prompts-schema.ts';
 export type { LoopPromptSource, LoopProtocolText, LoopRoundText } from './loop-prompts-schema.ts';
 /** Values one render call supplies; a record's `vars` are merged in on top of these. */
 export interface LoopPromptValues {
@@ -49,7 +51,20 @@ export interface LoopPrompts {
     /** One record's declared `vars`, unrendered, so a form can offer them before a run starts. */
     vars(kind: string): Readonly<Record<string, string>>;
 }
-/** The records of loop.yaml.
- * @returns Names, lookups and the declared vars of each record, built once.
+/** Put the records this process runs in place, before any run or record list reads them.
+ *
+ * The files are read and merged at startup rather than at module load, so a bad user file can be
+ * reported and refused before the client opens, and a run keeps the rubric it started with even if
+ * the file is edited underneath it.
+ * @param source - Merged records: shipped ones with the user's file layered on top.
+ * @param sourceInfo - Where they came from, and what the user's file changed.
+ */
+export declare function installLoopSource(source: LoopPromptSource, sourceInfo: LoopSourceInfo): void;
+/** Where the installed records came from.
+ * @returns The installed source info; the compiled-in records are the empty default.
+ */
+export declare function loopSourceInfo(): LoopSourceInfo;
+/** The records in force.
+ * @returns Names, lookups and the declared vars of each record, built once per installed source.
  */
 export declare function loopPrompts(): LoopPrompts;

package/dist/controller/loop-prompts.generated.js

@@ -1,5 +1,6 @@
 // GENERATED FILE — do not edit. Edit loop.yaml and run `npm run build:prompts`.
-// Kept in sync by tests/controller/loop-prompts.test.ts.
+// The fallback table: loop.yaml is read at runtime, and this is what a package whose file is
+// missing or unreadable starts on. Kept in sync by tests/controller/loop-prompts.test.ts.
 export const LOOP_PROMPTS = {
     "version": 1,
     "defaults": {

package/dist/controller/loop-prompts.js

@@ -1,14 +1,19 @@
 /** Typed access to the loop prompts and the placeholder renderer.
  *
- * `loop.yaml` is the editable source; `loop-prompts.generated.ts` is its inlined form and
- * `loop-prompts-schema.ts` holds the shape and the rules. This module turns one record into the
- * strings a protocol needs, so the dynamic parts (this round's title, its checklist, the record's
- * own vars) are filled here and nowhere else. A template may only use placeholders the caller can
- * supply; anything else throws rather than putting a literal `{{name}}` into a prompt.
+ * The loop record is configuration, not code: the shipped `loop.yaml` is read at startup from beside
+ * the package and a user file may be layered over it (`loop-source.ts`), then the merged table is
+ * installed here once. `loop-prompts-schema.ts` holds the shape and the rules, and
+ * `loop-prompts.generated.ts` is the compiled-in fallback for a package whose file is missing. This
+ * module turns one record into the strings a protocol needs, so the dynamic parts (this round's title,
+ * its checklist, the record's own vars) are filled here and nowhere else. A template may only use
+ * placeholders the caller can supply; anything else throws rather than putting a literal `{{name}}`
+ * into a prompt.
  */
 import { LOOP_PROMPTS } from "./loop-prompts.generated.js";
 const PLACEHOLDER = /\{\{(\w+)\}\}/g;
-const SOURCE = LOOP_PROMPTS;
+/** The records in force: the shipped file with the user's layered on top, installed once at startup
+ * and replaced only by another install, never by a reload while a run is in flight. */
+let SOURCE = LOOP_PROMPTS;
 /** Replace every `{{name}}` in one template list.
  * @param lines - Template lines.
  * @param values - Values keyed by placeholder name.
@@ -75,10 +80,31 @@ function render(kind, protocol, overrides) {
         followUp: runtime => fill(protocol.followUp, values(runtime), kind),
     };
 }
-/** All records, rendered once at module load: the config cannot change under a running client. */
+/** All records, rendered when the source is installed: a file edited mid-run cannot change a brief. */
 let cache;
-/** The records of loop.yaml.
- * @returns Names, lookups and the declared vars of each record, built once.
+/** Where the installed records came from, for the record list to show. */
+let info = { overridden: [], added: [], warnings: [] };
+/** Put the records this process runs in place, before any run or record list reads them.
+ *
+ * The files are read and merged at startup rather than at module load, so a bad user file can be
+ * reported and refused before the client opens, and a run keeps the rubric it started with even if
+ * the file is edited underneath it.
+ * @param source - Merged records: shipped ones with the user's file layered on top.
+ * @param sourceInfo - Where they came from, and what the user's file changed.
+ */
+export function installLoopSource(source, sourceInfo) {
+    SOURCE = source;
+    info = { ...sourceInfo, overridden: [...sourceInfo.overridden], added: [...sourceInfo.added], warnings: [...sourceInfo.warnings] };
+    cache = undefined;
+}
+/** Where the installed records came from.
+ * @returns The installed source info; the compiled-in records are the empty default.
+ */
+export function loopSourceInfo() {
+    return info;
+}
+/** The records in force.
+ * @returns Names, lookups and the declared vars of each record, built once per installed source.
  */
 export function loopPrompts() {
     if (cache !== undefined)

package/dist/controller/loop-protocols.d.ts

@@ -5,7 +5,9 @@ export declare function loopProtocolNames(): string[];
 /** Every record `/loop` may run, in file order, with the defaults a run would start from.
  *
  * The list and the run read the same records, so a chooser can show exactly the name, round count,
- * artifact and defaults the runner would use — never a second table that could drift.
+ * artifact and defaults the runner would use — never a second table that could drift. A record the
+ * user's own file supplied is marked, because an operator who overrode a shipped record can no longer
+ * tell the two apart from the name alone.
  * @returns One summary per record.
  */
 export declare function loopRecords(): LoopRecord[];