test(mmc-trajectory): ship the regression guards that were only on one machine

plugins/avatasia/mmc-trajectory/.gitattributes

@@ -0,0 +1,25 @@
+# The working tree of this plugin must be byte-identical to what is committed.
+#
+# Without this file, core.autocrlf=true rewrites every LF blob to CRLF on checkout — and git then
+# reports the result as *clean*, because it normalises line endings when it compares. The rewrite is
+# invisible to `git status` while it is happening, and it cost this plugin specifically:
+#
+#   1. Two working copies of the same file compared unequal, so a byte-for-byte check between the
+#      ship source and the local package reported a difference that was not one.
+#   2. `git checkout` of any path silently rewrote it. That is how `tests/fixtures/` landed CRLF on
+#      disk while its blobs are LF, and why verifying the fixture meant knowing which copy was which.
+#   3. Every mutation harness that anchors on a line ending has to guess which ending the checkout
+#      produced. `mutate-review16.py` did guess, and that was a bug waiting to fire the moment the
+#      ending moved. The anchors there no longer contain newlines for the same reason.
+#
+# `text=auto` leaves git free to keep deciding for itself which files are binary; `eol=lf` is the
+# part that pins the result. Every blob here is already LF, so adding this changes no committed
+# content — it only stops the working tree from disagreeing with it.
+#
+# This file lives in the plugin directory, not the repository root. At the root it would rewrite
+# line endings for every other plugin in the repo, and this is a single-plugin change.
+* text=auto eol=lf
+
+# The one file in this plugin that is not text. `text=auto` would sniff it correctly on its own, but
+# naming it keeps the intent visible next to the rule that would otherwise be the only one.
+*.png binary

plugins/avatasia/mmc-trajectory/.gitignore

@@ -0,0 +1,14 @@
+# Python bytecode caches from running the mutation harnesses.
+#
+# tests/ has 25+ .py files and they run on every `node tests/run.mjs`, so CPython drops a
+# __pycache__/ into the package directory every time. It is not tracked and must never be: it is
+# machine-specific, it changes shape between Python versions, and the plugin directory is the
+# package that ships. The repository root .gitignore does not cover it.
+__pycache__/
+*.pyc
+
+# tests/run.mjs hashes the shipped files before the mutation controls rewrite them, so a run killed
+# mid-mutation is caught on the next one instead of being inferred from whatever the source looks
+# like afterwards. The snapshot is machine-specific bookkeeping and this directory is the package
+# that ships to readers, so it must never be tracked.
+tests/.shipped-snapshot.json

plugins/avatasia/mmc-trajectory/.minimax-plugin/plugin.json

@@ -2,7 +2,7 @@
   "schemaVersion": 1,
   "name": "mmc-trajectory",
   "displayName": "会话轨迹",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "按轮次浏览当前会话的模型轨迹：消息流、思考过程、工具调用与结果、token 与耗时统计。",
   "author": "avatasia",
   "icon": "icon.png",

plugins/avatasia/mmc-trajectory/README.md

@@ -4,7 +4,20 @@ English | [简体中文](README.zh-CN.md)
 
 Browse the model trajectory of a MiniMax Code conversation: messages, reasoning, tool calls and their results, Token usage, and per-turn timing.
 
-Author: [avatasia](https://github.com/avatasia) · Version: `1.0.0`
+Author: [avatasia](https://github.com/avatasia) · Version: `1.1.0`
+
+### Before you change this page
+
+New features on this page grew one at a time, and most of the defects that survived review came from the same place: a control added without asking which layer it belongs to. So answer four questions in writing before writing any code.
+
+1. **Layer** — which functional layer does this belong to, and which layer's state does it write?
+2. **Relation** — beside, mutually exclusive with, or subordinate to which existing controls of that same layer?
+3. **Layout** — which container holds it? Does it need a new sticky region, panel, or layer?
+4. **Contract** — does it change a number another part of the page already promises? If yes, list every place that reads that number before you change it.
+
+The fourth is where the coordination bugs come from: one feature changed a number and every other surface kept speaking the old one. Mutual exclusion belongs in one place — one writer per state field — never as a convention spread across functions.
+
+`tests/` carries the regression guards for all of this; `npm test` runs them.
 
 ## Install and use
 
@@ -18,11 +31,15 @@ The author directory is only used to group contributions in the community reposi
 
 The page follows the most recent conversation by default and re-reads it every 2.5 seconds, so it stays live while you work; it pauses while the page is hidden. Each read is validated with an HTTP `ETag`: when the session file has not grown, the service answers `304 Not Modified` with no body and the page keeps what it already rendered. An idle tab therefore costs a few bytes per poll instead of the whole trajectory. Use the session picker to switch to any other conversation. No API key and no dependency installation are required — the package is dependency-free and needs no build step.
 
+When the session *has* grown, the poll carries `?since=<cursor>` alongside its validator and the service answers with the tail instead of the whole session: a payload of the same shape plus a `delta` marker, with `turns` holding only the turns that gained records. On a session of 21,000 records that is roughly 20 KB instead of 43 MB. The cursor is the highest `record.index` the page already holds — the same key `raw?index=` answers on — and it travels only with the validator it was taken against, so a session switch or a manual refresh sends the whole payload instead. `stats` and `session` travel whole in every tail: `stats` is an accumulator over all rows, so a tail cannot be added to it. A page that is ahead of the service (which is what a context-generation switch looks like from here) is answered with the whole payload, since a tail from there is empty and an empty tail is indistinguishable from "nothing to add". This saves transfer and the page's parsing, not the service's work — it still reads, parses and serializes the whole session to build the cache entry and to answer `raw`.
+
 ## What it shows
 
 The ledger groups records by turn, following the `turn_id` recorded in the session file. Each record is classified as user, answer, narration, thinking, tool call, tool result, system, or compaction, and each turn header carries that turn's own Token counts and elapsed time. Selecting a record opens a detail panel with summary, raw JSON, tool arguments, tool result, and reasoning, plus a button that hands the record to the Agent's chat input.
 
-**The type chips are the only filter over kinds.** One thing is being filtered — which record kinds are visible — and it is one array in the client, written from exactly three controls: the eight kind buttons, 全部, and 清除筛选. An earlier version also had a row of layer buttons (turn / thinking / call) sitting above the list as presets over those same chips. They were removed, because any preset a reader outgrows becomes a button that contradicts the chips it was supposed to summarise: untick 问答 while leaving 用户 ticked, and the turn button goes dark and claims the conversation is hidden when in fact it was narrowed. One control that cannot drift is worth more than three convenient ones that can. Two further controls cut across kinds instead of over them: a time range, which bounds the ledger to a wall-clock window, and an anomaly filter, whose rules pick out records that are wrong — a failed tool call, a compaction, a turn that never got an answer, an answer that came back empty — rather than records of a particular kind. Neither rewrites the kind array, so every kind chip still answers exactly one question.
+**The type chips are the only filter over kinds.** One thing is being filtered — which record kinds are visible — and it is one array in the client, written from exactly four controls: the eight kind buttons, 全部, 清除筛选, and the anomaly filter. An earlier version also had a row of layer buttons (turn / thinking / call) sitting above the list as presets over those same chips. They were removed, because any preset a reader outgrows becomes a button that contradicts the chips it was supposed to summarise: untick 问答 while leaving 用户 ticked, and the turn button goes dark and claims the conversation is hidden when in fact it was narrowed. One control that cannot drift is worth more than three convenient ones that can. Two further controls cut across kinds instead of over them: a time range, which bounds the ledger to a wall-clock window, and an anomaly filter, whose rules pick out records that are wrong — a failed tool call, a compaction, a turn that never got an answer, an answer that came back empty — rather than records of a particular kind.
+
+**The anomaly filter is the one cut-across control that also rewrites the kind array**, and deliberately so: ticking an anomaly rule calls the same `resetBaseFilters()` the 清除筛选 button calls, which returns kinds to all, clears the search box, drops any brush on the overview strip, and clears the time range. Without that, a reader could tick 工具失败 with 问答 unticked, see nothing, and have no way back except hunting for which of five controls to undo. The cost is stated here because it is a real cost: the chips stop being a filter you keep while you narrow by error — so 「只回答一个问题」 holds for the chips only outside anomaly mode, which is also when they are the only thing still in play. A time range and a search term still never rewrite the kind array.
 
 Naming kinds directly costs one extra click and reaches everything a preset did — tick 用户 *and* 答复 for the conversation, untick both for its absence, and any scattered subset in between, such as only the user's questions or only system records.
 

plugins/avatasia/mmc-trajectory/README.zh-CN.md

@@ -4,7 +4,20 @@
 
 按轮次浏览一段 MiniMax Code 对话的模型轨迹：消息流、思考过程、工具调用与结果、token 消耗与每轮耗时。
 
-作者：[avatasia](https://github.com/avatasia) · 版本：`1.0.0`
+作者：[avatasia](https://github.com/avatasia) · 版本：`1.1.0`
+
+### 动手改这个页面前
+
+这个页面的功能是一次加一个长出来的，而活到 review 之后的缺陷大多来自同一个地方：加控件时没先问它属于哪一层。所以实现之前，先用文字答完四个问题。
+
+1. **归层** — 它属于哪一层，改的是哪一层的状态？
+2. **关联** — 和同层已有控件是并列、互斥，还是从属？
+3. **布局** — 放进哪个已有容器？需不需要新的 sticky 区域、面板或层？
+4. **口径** — 它是否改变了页面上其他部分已经承诺的数字？若是，先列出**所有**读这个数字的地方，再动手。
+
+联动异常出在第四问：一个新功能改了一个数字，而别处仍在说旧的那个。互斥要写在**一处** —— 一个状态字段一个写者 —— 而不是变成散落在各函数间的约定。
+
+`tests/` 里是这些规则的回归守卫，`npm test` 跑它们。
 
 ## 安装与使用
 
@@ -22,7 +35,9 @@
 
 台账按 `turn_id` 把记录分组，轮次划分完全依据会话文件中记录的 `turn_id`。每条记录被归类为用户、答复、过程、思考、工具调用、工具结果、系统或压缩；每个轮次表头带该轮自己的 token 计数与耗时。选中任意记录会打开详情面板，含摘要、原始 JSON、工具入参、工具结果与思考内容，并提供一个把该记录内容送回 Agent 对话输入框的按钮。
 
-**类型选项是唯一针对「类型」的筛选。** 被过滤的始终只有一件事——哪些记录类型可见——客户端里它是同一个数组，只由三个控件写入：八个类型按钮、「全部」和「清除筛选」。早期版本在列表上方还排了一行图层按钮（轮次 / 思考 / 调用），作为同一批类型选项的快捷预设，已经删除。任何读者能走偏的预设，最终都会变成一个与它本该概括的选项自相矛盾的按钮：只取消「过程」而保留「用户」，轮次按钮就熄灭并声称整个对话已隐藏，而实际上你只是收窄了它。一个不会跑偏的控件，比三个方便的控件更值钱。 另外两个控件并不在类型之上做筛选，而是横跨类型：时间区间把台账限制在一个墙上时钟窗口内；异常筛选挑出的是「出了问题的记录」—— 工具失败、上下文压缩、整轮没有答复、答复是空的 —— 而不是某一类记录。两者都不改写类型数组，所以每个类型选项始终只回答一个问题。
+**类型选项是唯一针对「类型」的筛选。** 被过滤的始终只有一件事——哪些记录类型可见——客户端里它是同一个数组，只由四个控件写入：八个类型按钮、「全部」、「清除筛选」，以及异常筛选。早期版本在列表上方还排了一行图层按钮（轮次 / 思考 / 调用），作为同一批类型选项的快捷预设，已经删除。任何读者能走偏的预设，最终都会变成一个与它本该概括的选项自相矛盾的按钮：只取消「过程」而保留「用户」，轮次按钮就熄灭并声称整个对话已隐藏，而实际上你只是收窄了它。一个不会跑偏的控件，比三个方便的控件更值钱。 另外两个控件并不在类型之上做筛选，而是横跨类型：时间区间把台账限制在一个墙上时钟窗口内；异常筛选挑出的是「出了问题的记录」—— 工具失败、上下文压缩、整轮没有答复、答复是空的 —— 而不是某一类记录。
+
+**异常筛选是唯一一个会改写类型数组的横跨控件，而且是故意的**：勾选任一异常规则时，它调用的是「清除筛选」按钮调的那个 `resetBaseFilters()`，把类型恢复为全选、清空搜索框、丢掉总览条上的刷选、并清掉时间区间。否则读者会勾上「工具失败」而「问答」还取消着，看到一片空白，却不知道该回去改哪一个——一共五个控件可以撤销。代价必须写出来，因为它是真代价：异常模式下类型选项就不再是「一边保留一边按错误收窄」的筛选器 —— 所以「每个类型选项只回答一个问题」这句话只在异常模式之外成立，而异常模式之外也正是类型选项唯一还在起作用的时候。时间区间和搜索词仍然不改写类型数组。
 
 直接点名类型只多花一次点击，却能到达预设原本覆盖的全部范围：勾选「用户」**和**「答复」就是对话，两个都取消就是没有对话，中间任意散落的子集（只看用户提问、只看系统记录）同样可以。