dsh-better-debug 0.0.0-stage → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Leonlee114514
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.en.md ADDED
@@ -0,0 +1,358 @@
1
+ # dsh-better-debug
2
+
3
+ Turn a "stuck gate" from prompt text into a **code gate** for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness).
4
+
5
+ The five checks in `AGENTS.md` — and any `stuck-gate` skill — live in the **prompt layer**: the model has to *notice* it is stuck before the rules start applying. The characteristic symptom of being stuck is precisely that it does not notice. So it writes a third "let me try once more", eats the same error for the fourth time, or edits code and runs nothing.
6
+
7
+ This plugin does not read the model's mind. It watches what the model **does**, and when the behaviour matches "going in circles", it inserts one short user message **before the next step**:
8
+
9
+ ```
10
+ [better-debug] 观察到的重复动作(只是观察,不是结论):
11
+ - 同一个文件连续改了 3 次,中间没有任何测量。
12
+ 下一步(挑一条就够):
13
+ 1) 建一条几秒能跑完、能给出数字或事实的回路(失败测试 / 复现命令 / 一条断言 / lsp_diagnostics);建不出来就停下要现场产物。
14
+ 恢复条件:拿到一条新的测量结果或一条外部事实后,继续动手即可。
15
+ 完整五条:skill `stuck-gate`。
16
+ ```
17
+
18
+ (The injected text is Chinese to match the `AGENTS.md` it enforces; change `assets/stuck-gate/SKILL.md` and `lib/text.js` for other languages.)
19
+
20
+ ## Three signals (v0.2 semantics)
21
+
22
+ | Signal | Trigger | Default | Why |
23
+ | --- | --- | --- | --- |
24
+ | **A** same file, edited **with no measurement in between** | `fs/write-intent` per absolute path; the streak clears only **after a real measurement returns a result**, and only for that directory | 3rd time | Grinding on one point with no new facts is "guessing without a loop" |
25
+ | **B** same **operation** failing again | `tool/result` counted per episode keyed on `tool \| target \| fingerprint`; immune only if that episode was followed by a search | 2nd time | Twice means the first read didn't stick; per-episode, so a search about something else no longer exempts it |
26
+ | **C** edited, then **acted again** with no loop | N steps after a write with no measurement → **arm only**; the reminder comes **before the next write** | 2 steps | "Change and move on" is the most common missing check — but reading code must not be interrupted |
27
+
28
+ All three rest on the concept of a **measurement**, not on "some tool was called".
29
+
30
+ ### What counts as a measurement
31
+
32
+ "Tool was called" ≠ "measurement completed". That was v0.1's biggest hole: in `edit → ls → edit → edit`, the `ls` whitewashed the blind-edit streak, so real circling did not fire.
33
+
34
+ v0.2 splits it into two states: **measurement intent** (decided at `tool/call` from the arguments) and **measurement result** (booked when `tool/result` comes back). Only a returned result clears a streak, and only for the files related to that command's directory — running `npm test` in `C:/other` must not clear the streak on `C:/work/src/target.js`.
35
+
36
+ | Class | Tools | Criterion |
37
+ | --- | --- | --- |
38
+ | Hard measurement | `lsp_diagnostics` `verify` `run_tests` `run_test` | always a measurement |
39
+ | Soft measurement | `ops_bash` `bash` `shell` `pwsh` | command matches `measureCommands`, or the description matches `measureIntent` while the command does not start with `ls/dir/cat/type/head/tail` |
40
+ | Search | `web_search` `research` `advanced_search` `multi_search` `platform_search` `domain_search` `cache_search` `video_search` | a hit counts as new external facts |
41
+ | Method | `skill` | loading methodology is a real turn of action; counted separately, not folded into `other` |
42
+ | Edit | `edit` `write` `ops_write` `str_replace` `apply_patch` `notebook_edit` | |
43
+
44
+ **A failing test is still a valid measurement**: it tells you which line broke. `[exit code: 1]` clears the streak and counts as a loop just the same; the panel merely records `ok=false`.
45
+
46
+ `DEFAULT_MEASURE_COMMANDS` covers `npm/pnpm/yarn/bun` + `test|verify|check|lint|typecheck|build`, `node --test`, `pytest`, `vitest`, `jest`, `mocha`, `go test`, `cargo test`, `dotnet test`, `tsc`, `eslint`, `ruff check`, `mypy`, `git diff --stat`. For non-code tasks, override `measureCommands` with your own regex (word counts, section counts, anything that yields a number or a fact).
47
+
48
+ **Generated files do not count as blind edits**: `node_modules`, `dist`, `build`, `out`, `coverage`, `.git`, `.next`, `.cache`, lock files, `*.log` / `*.map` / `*.min.js` are excluded via `excludePaths`.
49
+
50
+ ### Error episodes (B's key)
51
+
52
+ ```
53
+ tool name | target | error fingerprint
54
+ ```
55
+
56
+ - **target** is the first path-like token in the error text (`C:/work/a.js`), with numbers normalised to `<n>`;
57
+ - **fingerprint** is the first 16 hex chars of a sha256 over the normalised first 6 lines / 300 chars, with `0x1f3a2b9c`→`<hex>`, paths→`<path>`, `42`→`<n>`.
58
+
59
+ So an error whose line number moved but whose class did not is the same episode, while **two different files each failing ENOENT once are not**.
60
+
61
+ ## What it deliberately does not do
62
+
63
+ - **No "I guess it's…" phrasing detection.** The plugin cannot see the model's inner monologue. That check stays in the `stuck-gate` skill, where self-detection belongs.
64
+ - **No no-op write detection.** `fs/write-intent` only carries a freshness token (`FsVersion` or `createIfAbsent`), never the content, so the plugin layer cannot diff.
65
+ - **No probe cleanup at turn end.** That belongs to a turn-cleanup plugin.
66
+ - **Never `reject`.** Rejecting turns the whole turn into a no-op. The plugin only appends one user message to the tail of `messages`.
67
+ - **Never fires in subagent sessions.** `header.origin === 'subagent'` or `delegationDepth > 0` is skipped: their cwd may be someone else's workspace and their counters are not comparable.
68
+
69
+ ## The "don't search, just fix it" exception
70
+
71
+ When the user explicitly says *don't search, just make the change, just try it quickly*, the gate must stand down. The plugin implements this by scanning this turn's **user** messages for `别搜|不要搜|不用搜|先别搜|直接改|快速试|别折腾|先试试` and going silent for the whole turn. Only `source.kind === 'user'` counts — the plugin's own injected message is ignored.
72
+
73
+ ## Idempotence and re-arming
74
+
75
+ Not "each signal once per turn" — that would leave the second phase of a long turn unattended. v0.2 is **once per stuck episode**:
76
+
77
+ - the same situation is not repeated (`lastFireMark`'s write and error sequence numbers both unchanged → stay quiet);
78
+ - **a valid measurement re-arms it**: `fired.A/C` reset to zero, so a new bout of blind editing later in the same turn can be flagged again;
79
+ - **a per-turn budget** `maxInjectsPerTurn` (default 3) keeps it from becoming a drumbeat.
80
+
81
+ When A or B fires, C is marked as already fired too: A/B already describe the situation, and adding "and you didn't verify" is just a restatement.
82
+
83
+ ## Trigger preconditions
84
+
85
+ The gate governs **before the next attempt**, not after delivery. Three checks run first:
86
+
87
+ 1. **done-state**: a `present` call that **succeeded** (`isError !== true`) happened this turn → **no injection**; a `suppress … reason=done` line is written. **A failed `present` does not sleep the gate** — the deliverable never went out, so the gate stays awake. The next `fs/write-intent` re-arms it. Switch: `doneOnPresent: false`.
88
+ 2. **Loop-driven convergence**: see "what counts as a measurement" above. Switch: `decayEditsOnVerify: false`.
89
+ 3. **Task type**: writing, word-count calibration and layout convergence have no errors and no failing tests; their loop is a command that yields a number. The injected text is task-neutral.
90
+
91
+ Boundary: the code layer can only recognise the `present` *action*. **Plain-text final answers (no `present`)** are covered only by the done-state self-check inside the `stuck-gate` skill — the two layers complement each other; don't expect the plugin to read minds.
92
+
93
+ ## The injected text
94
+
95
+ Three rules:
96
+
97
+ 1. **State the observation, don't diagnose.** The old first line ("检测到你在原地打转" — "you are going in circles") labelled the model. Now it reads "观察到的重复动作(只是观察,不是结论)" — "observed repeated actions (an observation, not a conclusion)".
98
+ 2. **At most two actions.** More than that is the same as none.
99
+ 3. **Always give a recovery condition.** "How to continue" is more useful than "you're wrong".
100
+
101
+ The single source for this text is `lib/text.js`, shared by `index.js` (injection) and `panel.js` (back-filling character counts for old logs), so the panel's length estimate cannot drift from the real text.
102
+
103
+ ## Response protocol (prompt layer, `stuck-gate` skill)
104
+
105
+ After the gate fires, run verification / search / cleanup / context compression **silently, in one pass**, emit no final-answer phrasing during it, then give **one** conclusion. The inverted pattern — conclusion → a run of tool calls → another conclusion — is forbidden. `[better-debug]` is a reminder; it does not need a prose reply first.
106
+
107
+ ## Bundled skill
108
+
109
+ The package ships `assets/stuck-gate/SKILL.md` and registers it as a **bundled skill** via `inject: ["skills"]` (`source: "bundled"`, `rank: 600`) — it appears in the model-visible skill catalogue after install, no file copying needed.
110
+
111
+ The reminder ends with "完整五条:skill `stuck-gate`", pointing at this one.
112
+
113
+ **Rank order** (lower wins):
114
+
115
+ | rank | source | who speaks |
116
+ | --- | --- | --- |
117
+ | 100–200 | project `.dsh/skills`, `.agents/skills` | project override |
118
+ | 300 | `custom` | |
119
+ | 400 | `~/.dsh/skills` (user global) | **your own copy beats the plugin's** |
120
+ | 500 | `~/.agents/skills` | |
121
+ | 600 | this plugin's `assets/` | default text |
122
+
123
+ So changing the gate wording needs no code change: drop a copy at `~/.dsh/skills/stuck-gate/SKILL.md` and it takes effect. Editing the copy inside the plugin applies to everyone (the file is re-read on every `get()`, no restart needed).
124
+
125
+ If the host has no `skills` service (older DSH), registration is skipped with one log line and **the gate itself keeps working**.
126
+
127
+ ## The observation panel
128
+
129
+ Logs are only loved by the person who wrote them. The panel turns them into something you can read at a glance: **Settings → better-debug**, an iframe view, 5-second auto-refresh, read-only, it never changes plugin behaviour.
130
+
131
+ Four cards:
132
+
133
+ | Card | Source | What it can tell you |
134
+ | --- | --- | --- |
135
+ | Gate fires | every `inject` line | how many reminders were spoken, grouped by `A/B/C` and combinations |
136
+ | Sessions covered | distinct `session=` on `inject` lines | how many sessions, turns, characters and tokens of injected text |
137
+ | **First action after a reminder** | `class=` on `outcome` lines | what class the first `tool/call` after a reminder was. **Descriptive. Proves no causation.** |
138
+ | **Measurement loops (hard evidence)** | `measure` lines | how many real measurements happened, how many passed, how many failed, how many streaks were cleared |
139
+
140
+ Plus three distributions: signals, first-action class (six), and **whether it actually turned to obtain new facts within the window** (`change` lines, with a real median step count).
141
+
142
+ ### Metric naming discipline
143
+
144
+ This is where v0.1's panel was most misleading; v0.2 splits it apart:
145
+
146
+ - The name **"reaction rate" is gone**. It computed "the first tool after a reminder was verify/search", which cannot prove the reminder caused the change, let alone that it helped find a defect — the model might have done that next anyway. It is now **"first action after a reminder"**, field `firstAction`.
147
+ - To know whether it turned to new facts within a window, read `turned` (computed only from `change` lines, with a genuine median). That median has samples only here — v0.1's `medianSteps` was always `null` because the outcome line was written on the very next step, so the step delta was always 0.
148
+ - **Old logs are never counted as "0% turned".** v0.1's `inject` lines carry no `inj=`, so they cannot have `change` / `measure` lines either; "0 turns" there means **not measured**, not "measured as zero". `turned.observed` is the denominator and counts only injections after the instrumentation landed; `rate` is `null` when `observed = 0`, and the panel says "this log predates the v0.2 instrumentation". In the real log all 55 injections are in the old format, so `observed = 0` — the panel now says exactly that instead of reporting 0% over 49 outcome lines.
149
+ - "What these numbers do not prove" is printed in the footer: proving a gain needs a control group or historical replay, and the panel does neither.
150
+ - **No estimate of "tokens saved".** The plugin's job is to record what is observable and leave judgement to the reader.
151
+
152
+ ### Instrumentation added for the panel
153
+
154
+ Every injection gets an `inj=` (8-hex) id that later lines carry, so one reminder's whole life is traceable:
155
+
156
+ ```
157
+ inject session=… turn=39 step=88 signals=A inj=78ed6bc3 chars=309 tokens=271 files=1 worstEdits=3 worstStreak=3 worstErrors=0 searched=false measured=no
158
+ arm session=… turn=39 gap=2
159
+ outcome session=… turn=39 inj=78ed6bc3 after=A first=ops_bash class=verify steps=1 before=write
160
+ measure session=… turn=39 tool=ops_bash ok=false exit=1 cleared=1
161
+ change session=… turn=39 inj=78ed6bc3 after=A tool=ops_bash class=verify steps=1
162
+ suppress session=… turn=39 reason=done
163
+ ```
164
+
165
+ - `outcome` records only the **first** subsequent `tool/call`: a late verification must not whitewash earlier circling. `before=` is the action preceding the reminder (writes count, so the common value is `write`).
166
+ - `change` is written only within `changedWindow` (default 6) steps of an injection; outside the window it is discarded.
167
+ - `measure` is written for every measurement result, with `ok` / `exit` / `cleared` (how many files' streaks were cleared).
168
+ - For old logs with no `chars=`, the parser recomputes the text length through `charsFor(signals)` from `lib/text.js`. v0.1's hard-coded table (`A=254` etc., off by ~50 characters) is deleted.
169
+
170
+ ### Turning the panel off
171
+
172
+ `config: { panel: false }`. The route is not mounted, `/better-debug` returns 404, the gate is unaffected.
173
+
174
+ The route is mounted via `ctx.inject(['webServer'], …)` — a **dynamic injection**, not part of `export const inject`. Adding it there is a structural change that breaks hot reload and would stop the gate from installing on hosts without a `webServer`. When the host lacks one, the log gets `panel unavailable: …`; when mounting throws, `panel register failed: …` — and the panel displays it.
175
+
176
+ ## Install
177
+
178
+ **Quick (Release tarball; pnpm treats it as a normal package):**
179
+
180
+ ```bash
181
+ dsh plugin add https://github.com/Leonlee114514/dsh-better-debug/releases/download/v0.2.0/dsh-better-debug-0.2.0.tgz
182
+ ```
183
+
184
+ (This package is **not** published to the npm registry, so `dsh plugin add dsh-better-debug` will 404. Use the tarball URL above, or link manually as below.)
185
+
186
+ **Manual link (use this if you want to change the code):**
187
+
188
+ ```bash
189
+ # 1. Put it somewhere permanent. Not a temp dir, not inside node_modules.
190
+ # (~/dsh-plugins/dsh-better-debug is used below as an example.)
191
+ mkdir -p ~/dsh-plugins
192
+ cp -r dsh-better-debug ~/dsh-plugins/
193
+
194
+ # 2. Add the link dependency to your profile
195
+ cd ~/.dsh/profiles/desktop
196
+ # package.json → dependencies, one line (path relative to .dsh/profiles/desktop):
197
+ # "dsh-better-debug": "link:../../../dsh-plugins/dsh-better-debug"
198
+ # An absolute path works too:
199
+ # "dsh-better-debug": "link:D:/code/dsh-better-debug"
200
+ # package.json → dsh.profile.bundles, append:
201
+ # "dsh-better-debug"
202
+
203
+ # 3. Let the bundle patch mount it (if bundles already lists it, dsh applies the
204
+ # package's cordis.patch.yml automatically), or write your own row in the
205
+ # profile's cordis.patch.yml:
206
+ # - id: better-debug
207
+ # name: dsh-better-debug
208
+ # Note: do **not** add `inject: [skills]` — see "Why no static inject" below.
209
+ # The package's own row also carries **no config** — see "Why the bundle patch
210
+ # has no config".
211
+
212
+ # 4. Restart DSH.
213
+ ```
214
+
215
+ > **Do not use both mounting paths.** The package's `cordis.patch.yml` already contains a `- id: better-debug` row. Writing the same id again in your profile makes cordis reject the duplicate. Two rows with **different** ids pointing at the same package name are worse: the plugin mounts twice, every reminder is injected twice, every log line is written twice.
216
+
217
+ ### Why no static inject
218
+
219
+ `export const inject` is empty, and `cordis.patch.yml` declares no `inject:` — both on purpose.
220
+
221
+ cordis's `Fiber._refresh()` takes the whole fiber INACTIVE and **skips `apply()` entirely** when any declared service is unavailable: no error, no log line, the panel looks installed while not a single line of plugin code ever ran. The loader also merges the YAML entry's `inject:` into that dependency set (`cordis-plugin-loader`: `Inject.resolve(entry.options.inject, fiber.inject)`), so fixing the code alone is not enough — the config row would still wedge it.
222
+
223
+ `skills` is provided by `@deepseek-ai/dsh-skill`. A trimmed profile, another distribution, or simply not enabling that package leaves it absent — and the gate does not need it. Both optional services (`skills` / `webServer`) are therefore subscribed dynamically with `ctx.inject(['skills'], cb)`: present, they attach; absent, you lose one optional feature and the gate keeps working.
224
+
225
+ The panel follows the same rule: `client.js` skips registration when `slots` is absent. Open **Settings → better-debug**, or visit `http://<web-origin>/better-debug`.
226
+
227
+ ### Why the bundle patch has no config
228
+
229
+ The package's `cordis.patch.yml` is two lines — `id` and `name` — with no configuration key at all. The reason is that DshMarket's hot mount replays **plain insert rows only**:
230
+
231
+ ```js
232
+ // dshmarket/lib/hot.js
233
+ export function parseSimplePatch(patchText) {
234
+ const scan = scanPatch(patchText)
235
+ return scan.blocker === null ? scan.rows : null // any other key → null
236
+ }
237
+ ```
238
+
239
+ `scanPatch()` stops at `config:` and marks the whole patch `blocker: 'config'`, and the market then tells the user "the bundle patch has a config block; hot-mount replays plain insert rows only — a restart loads the bundle as written". In other words: with a config block, clicking **Enable** in the market does nothing until DSH restarts, which is exactly where a new user concludes the plugin is broken.
240
+
241
+ Every default already lives in `normalizeConfig()` in `lib/index.js`. The config block bought only self-documentation, at the price of a silent no-op for newcomers. So the defaults stay in code, and a config block belongs in your profile row — that row is not part of the package's hot mount.
242
+
243
+ ## Configuration
244
+
245
+ All defaults live in `normalizeConfig()` in `lib/index.js`; it runs as installed. To change one, write the same id (`- id: better-debug`) into **your own profile's** `cordis.patch.yml` with a `config:` block — do not edit the package's copy (an upgrade overwrites it, and a config block there breaks the market's hot mount):
246
+
247
+ ```yaml
248
+ - id: better-debug
249
+ name: dsh-better-debug
250
+ config:
251
+ enabled: true
252
+ repeatEditThreshold: 3 # A: consecutive edits to one file
253
+ repeatErrorThreshold: 2 # B: repeats of one error episode
254
+ noVerifySteps: 2 # C: steps without measurement before arming
255
+ maxInjectsPerTurn: 3 # reminders per turn, maximum
256
+ changedWindow: 6 # steps after an injection that count as "turned"
257
+ decayEditsOnVerify: true # a measurement clears the blind-edit streak (false = old behaviour)
258
+ doneOnPresent: true # a successful present sleeps the gate; next write re-arms (false = old behaviour)
259
+ measureCommands: "" # regex overriding "what command is a measurement"; empty = built-in list
260
+ measureIntent: "" # regex overriding "what description signals measurement intent"
261
+ excludePaths: "" # regex overriding "which paths never count as blind edits"
262
+ logFile: "~/.dsh/logs/better-debug.log" # `~` is expanded; omit the key to get this default
263
+ panel: true # mount the read-only /better-debug panel; false = no route
264
+ ```
265
+
266
+ Tighter (fires more) → smaller numbers; looser → larger. With `enabled: false` not even a listener is registered. A bad regex in the three regex keys **falls back to the built-in default** and logs a warning; it never kills the plugin.
267
+
268
+ `logFile` has four forms:
269
+
270
+ | Value | Where it goes |
271
+ | --- | --- |
272
+ | key omitted | `$DSH_HOME/logs/better-debug.log` (`~/.dsh/logs/better-debug.log` when `DSH_HOME` is unset) |
273
+ | `"~/my.log"` | expanded to `my.log` under your home dir (`~`, `~/x` and `~\x` all work) |
274
+ | `"C:/x.log"` / `"/var/log/x.log"` | used verbatim |
275
+ | `""` or `false` | **explicitly disables the file**. `ctx.logger` only reaches Electron stdout and cannot be grepped later, so the panel then has nothing to show |
276
+
277
+ Not writing a file was the v0.1 default, and the cost was new users installing it, opening the panel, seeing four empty cards and concluding the plugin was broken. It now writes out of the box.
278
+
279
+ ## Verifying it really works
280
+
281
+ 1. After installing and restarting, the log is already at `$DSH_HOME/logs/better-debug.log` — no configuration needed. Set `logFile` to move it.
282
+ 2. Loading writes one `apply pid=… logFile=… A=3 B=2 C=2 budget=3 window=6 panel=true` line — **the only proof the plugin loaded at all** (`ctx.logger` only reaches Electron stdout and cannot be grepped later). No `apply` line means it is not mounted.
283
+ 3. Work normally; a hit looks like:
284
+ ```
285
+ inject session=… turn=32 step=98 signals=A inj=78ed6bc3 chars=309 tokens=271 files=1 worstEdits=3 worstStreak=3 worstErrors=0 searched=false measured=no
286
+ ```
287
+ `signals` lists the fired signals (`A`/`B`/`C`, `+`-joined); `files` is the number of **distinct** files touched this turn; `worstEdits` is the cumulative count; **`worstStreak` is the criterion A actually uses** (consecutive blind edits since the last measurement). Read all three together: `files=1 worstEdits=3 worstStreak=1` means a measurement happened in between and it should not have fired. `suppress … reason=done` means the gate is awake but in delivery state and deliberately silent. `arm … gap=2` means C only armed — it is waiting for your next write.
288
+ 4. Do **not** judge it by "was the next action a verify". Look at two things: whether `measure` lines appear at all (hard evidence that a measurement happened), and the `steps=` on `change` lines (how many steps later it turned to new facts). If there are `outcome` lines but no `measure` lines, the model merely switched tools without building a loop.
289
+
290
+ ## Local verification
291
+
292
+ ```bash
293
+ node --check lib/index.js && node --check lib/panel.js && node --check lib/text.js && node --check client.js
294
+ node test/sim.mjs # 37 cases: gate semantics + portability
295
+ node test/panel.mjs # 32 cases: log parsing, aggregation, instrumentation
296
+ npm run test:posix # re-runs both suites under POSIX path semantics
297
+ npm run verify # all of the above (with syntax checks)
298
+ ```
299
+
300
+ `test/sim.mjs` uses a fake ctx that replicates agent-loop call order (`emitPlain` / `emitWaterfall`) and covers **37 cases**.
301
+
302
+ Semantics (each with a positive and a negative):
303
+
304
+ - **Intent vs. result**: `edit → ls → edit → edit` still fires; a call with no result does not clear; a failing test is not a blind edit; a measurement in an unrelated directory does not clear the target file's streak.
305
+ - **B's episodes**: only the same target and fingerprint accumulate; two different files each failing ENOENT once do not fire; a search after that episode grants immunity (a search *before* it does not).
306
+ - **C's two stages**: after an edit, reading code alone does not interrupt; arming followed by another write does.
307
+ - **Re-arming**: A fires → a valid measurement restores → a new bout of blind edits may fire a second time; the per-turn budget applies.
308
+ - **Delivery state**: no injection after a successful `present`; **a failed `present` does not sleep the gate**.
309
+ - Observation-only wording, lock files excluded, the "just fix it" exception, subagent skip, adjustable thresholds, `decayEditsOnVerify: false` restoring old behaviour, `enabled: false`, bundled-skill registration and de-privatised content, no `skills` service not throwing, export shape, plus 13 classification/criterion/fingerprint unit assertions.
310
+
311
+ **No DSH runtime required** — run it first after any change.
312
+
313
+ ### Why there is a `test:posix` pass
314
+
315
+ Every path in `test/sim.mjs` is written in Windows dialect (`C:/work/...`). The suite still
316
+ runs on a Linux box, but it exercises a *different* set of semantics — which was exactly a
317
+ real incident before v0.2:
318
+
319
+ `node:path`'s `isAbsolute` is platform-dependent: `isAbsolute('C:/work/a.js')` returns
320
+ `false` on Linux/macOS. The entry gate used it to filter write paths, so on those machines
321
+ **every write was silently dropped**, signals A and C stopped working entirely, and a Windows
322
+ dev machine stayed green. The fix is to stop asking the OS "does this root look like mine"
323
+ and only ask "does it start at a root" (`isAbsPath`).
324
+
325
+ `test/posix` uses a `node --import` resolve hook to swap `node:path` for `node:path/posix`
326
+ and then **re-runs both suites unchanged** — so a Windows dev machine reproduces Linux path
327
+ semantics. CI runs `npm run verify` on ubuntu / windows / macos × node 20 / 22, so this
328
+ cannot quietly regress.
329
+
330
+ Three more of the same family, all fixed in v0.2:
331
+
332
+ | Symptom | Root cause | Now |
333
+ | --- | --- | --- |
334
+ | The gate never fires on Linux/macOS | `isAbsolute` is platform-dependent | `isAbsPath` accepts both dialects |
335
+ | Panel shows four empty cards right after install | default `logFile: ""` wrote nothing | defaults to `$DSH_HOME/logs/better-debug.log` |
336
+ | Plugin silently not loaded — no error, no log line | static `inject: ['skills']` makes `apply()` never run when the service is missing | `inject = []`, dynamic `ctx.inject` |
337
+ | Clicking "enable" in the market does nothing | bundle patch carried a `config:` block | patch keeps only `id` + `name` |
338
+
339
+ **Case folding is decided per platform** (`CASE_INSENSITIVE`): only on `win32` / `darwin`.
340
+ The cost of folding wrong is asymmetric — not folding when you should under-reports, folding
341
+ when you should not **over-reports** (crying wolf), and over-reporting is the one failure this
342
+ gate must not make. A case-sensitive APFS volume on macOS under-reports a little, which is
343
+ still the safe direction.
344
+
345
+ `test/panel.mjs` covers **32 cases**: quoted and escaped field splitting; six line kinds (`inject` / `outcome` / `change` / `measure` / `arm` / `panel-failed`); zero drift between `charsFor` and the real text length across 6 signal combinations; `worstStreak` preserved along log→parse→aggregate→panel; `suppress` and `arm` lines parsed and not counted as fires; the aggregated `firstAction` / `turned` / `measures`; **assertions that v0.1's field names `changed` / `changedRate` / `outcomes` must not come back**; thresholds from the last `apply`; empty logs and bad lines not throwing; and an end-to-end run that really calls `apply()`, walks one turn, and reads the log back to assert `inject` carries `inj=`, `outcome` carries `before=write`, `measure ok=false exit=1`, and `change` is written and aggregated.
346
+
347
+ ## Known boundaries
348
+
349
+ - "Same file" is decided by **absolute path**. Delete and recreate the same name and it still counts as the same place — usually correct (you are circling one concept), but if you keep rewriting generated files, exclude them via `excludePaths` or raise `repeatEditThreshold`.
350
+ - **The measurement criterion is heuristic**: whether `ops_bash` runs a real measurement is guessed from a `measureCommands` / `measureIntent` regex pair. The cost of guessing wrong is now asymmetric — treating a non-measurement as a measurement under-reports, treating a measurement as a non-measurement over-reports. The default list leans toward "over-report rather than under-report", because acting on a false reminder costs you little.
351
+ - `done-state` recognises a **successfully returned** `present` call, not "the model said a closing sentence". Plain-text final answers rely on the done-state self-check in the `stuck-gate` skill; if some task type never calls `present`, switch `doneOnPresent: false`.
352
+ - Only **main sessions** are covered. In multi-agent runs each subagent can circle without being stopped — but their output flows to the lead, and the lead's counters still apply.
353
+ - The panel is a **read-only log view**, not monitoring: it writes nothing and never changes gate decisions. Only when you explicitly set `logFile: ""` (no file) does it have nothing to show and report zeros.
354
+ - `firstAction`'s denominator is "injections that were observed". An injection followed by the turn ending (no further `tool/call`) is not counted, so the ratio swings a lot on small samples — read the magnitude, don't treat it as a KPI.
355
+
356
+ ## License
357
+
358
+ MIT