@xiangyixie/dsh-superagent 0.9.1 → 0.9.3

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/CHANGELOG.md CHANGED
@@ -1,244 +1,281 @@
1
- # Changelog
2
-
3
- ## 0.9.1 — 2026-11-14
4
-
5
- Metadata-only release. No code or behaviour change; the only file contents that
6
- differ are `package.json`, `README.md`, and this changelog.
7
-
8
- - Added the `author` field (`Admire (LittleChenLiya)`), matching the copyright
9
- line in `LICENSE`. npm shows it on the package page from this version on;
10
- 0.9.0 shipped without it.
11
- - The README "License" section now names the copyright holder, links
12
- `LICENSE`, and says that the npm scope `@xiangyixie` and the GitHub account
13
- `LittleChenLiya` are the same author.
14
-
15
- ## 0.9.0 — 2026-11-14
16
-
17
- Hardening pass before the first publish. No behaviour change for the happy
18
- path except the new spending caps, the cost line, and two operator utilities.
19
-
20
- ### Published as `@xiangyixie/dsh-superagent`
21
-
22
- - npm already carries a `dsh-super-agent` that its similarity check treats as
23
- the same name as the unscoped one, so the first release goes out under the
24
- author scope. The project, the repository, the plugin row id (`superagent`),
25
- the five tools (`superagent_*`), the state directory, and both bin names are
26
- unchanged; only the install specifier differs:
27
- `dsh plugin --profile web add @xiangyixie/dsh-superagent`.
28
-
29
- ### Watch panel and HTML report
30
-
31
- - `dsh-superagent-watch` draws one line per run — id, status, calls used against
32
- the cap, elapsed, current activity, parent session — in the alternate screen.
33
- A status change repaints within 200 ms; an idle panel costs one small file
34
- read per second. Ctrl-C, SIGTERM, and a closed pipe restore the cursor and
35
- leave the alternate screen; `--once` prints one plain frame and never takes
36
- over the screen.
37
- - `dsh-superagent-report` renders recorded runs into one self-contained HTML
38
- file: inline CSS and inline SVG, no script, no font, no image, no network. It
39
- contains a timeline with each run's start, end, and derived
40
- planning/work/merge phases; swimlanes whose count is the peak concurrency;
41
- cumulative model-call and cost curves; explicit failure, cancellation, and
42
- interruption annotations; and a run table.
43
- - Neither utility adds a dependency. The package is still `dependencies: {}`;
44
- the tarball grows from 11 to 15 files (73.4 kB packed, 240.7 kB unpacked).
45
-
46
- ### Embedding surface (local HTTP)
47
-
48
- - New opt-in `controlPort` exposes the five operations as JSON over loopback:
49
- `GET /`, `GET /health`, `GET /runs`, `GET /runs/:id`, `POST /runs`,
50
- `POST /runs/:id/cancel`, `POST /runs/:id/resume`. Off by default; `0` picks a
51
- free port. Another UI can start and watch runs without importing `lib/`.
52
- - Bound to `127.0.0.1` only, with a per-process bearer token written to
53
- `<stateDir>/control.json` (mode `0600`), a `Host` check that blocks DNS
54
- rebinding, no CORS headers, a 64 KB body cap, and a 60 s limit on receiving a
55
- request (a 300 s long poll is unaffected: the wait happens while the response
56
- is produced).
57
- - Every route goes through the same orchestrator as the tools: quota, budgets,
58
- run locks, cross-process cancel, and recovery behave identically. `POST /runs`
59
- requires `session_id` of a live session; a run still needs a real parent agent
60
- for its children, and a missing session is refused as `no-session` rather than
61
- started without an owner.
62
- - Replies carry the same `text` as the tool result, plus the stored run object
63
- (`schemaVersion: 1`). Transport errors have their own ids (`unauthorized`,
64
- `forbidden-host`, `no-session`, `body-too-large`, …) so a client can tell a
65
- bad token from a broken run.
66
- - The contract, security model, and client examples are in
67
- [docs/embedding.md](https://github.com/LittleChenLiya/dsh-superagent/blob/main/docs/embedding.md);
68
- verified against real `dsh@0.2.2-rc.1` with 17 checks in
69
- `docs/e2e/transcripts/control-plane.log`, plus a two-host cross-process cancel
70
- run in `docs/e2e/transcripts/cross-cancel.log`.
71
- - Review fixes before release: a dispose that lands while the port is still
72
- binding now closes it instead of leaving an orphaned listener; a failed
73
- discovery write closes the server instead of running unreachable; `/health`
74
- does no state work, so a liveness probe cannot reclaim runs; a blank goal is
75
- a 400 `no-goal` and a profile without a subagent service is a 503
76
- `no-subagents` instead of a 500.
77
- - A second review pass added: the plane starts only after the state directory
78
- exists (a fresh `DSH_HOME` used to leave it off for the whole host lifetime);
79
- discovery files carry a per-plane `instanceId`, so a reloaded plugin does not
80
- delete the newer plane's file; a concurrent `start()` shares one listener;
81
- `GET /runs?limit` also limits the returned array; a missing goal is reported
82
- before a missing session; a worker session is refused by `superagent_cancel`
83
- as well; and a malformed `controlPort` (`""`, `" "`, `true`) can no longer
84
- coerce to an accidental listener.
85
-
86
- ### Renamed to `dsh-superagent`
87
-
88
- - The package, repository, plugin row id (`superagent`), default state
89
- directory (`state/superagent`), log prefix, and all five tools
90
- (`superagent_*`) moved from the working name `dsh-longhaul`.
91
- - Nothing was ever published under the old name, so there is no migration and
92
- no compatibility alias: `longhaul_*` calls simply do not exist. A run started
93
- under the old default state directory is still readable by pointing
94
- `stateDir` at it.
95
-
96
- ### Cancellation
97
-
98
- - `superagent_cancel` now stops the run when it is called from a different
99
- process. The caller writes a `<runId>.cancel` marker; the owning process polls
100
- it once per second, aborts its children, disposes their activations, and
101
- records `cancelled`. The caller waits up to 5 s and reports
102
- `cancel requested ... not confirmed` instead of claiming a success it cannot
103
- observe.
104
- - Recovery converts a marked run to `cancelled` rather than `interrupted`, and
105
- `superagent_resume` clears a stale marker.
106
-
107
- ### Spending
108
-
109
- - New hard budgets `maxModelCallsPerRun` (80) and `maxTokensPerRun` (2,000,000),
110
- checked before every child spawn. Hitting one stops spawning: the run ends
111
- `partial` when at least one subtask finished and `failed` when none did, keeps
112
- the reports that did finish, and leaves the rest `pending` for a resume.
113
- - A tool's `max_subtasks` / `max_parallel` / `deadline_minutes` can narrow the
114
- configured cap but never widen it: the config stays the operator's control.
115
- - New `pricing` table (per 1M tokens, per model) and a `cost` field on every
116
- run. Unpriced models are named and excluded instead of being estimated.
117
- - `usage: not recorded` now explains why instead of printing two bare words.
118
-
119
- ### Robustness
120
-
121
- - A run file that is not valid JSON is quarantined as
122
- `<runId>.json.corrupt-<ts>` and skipped by listings; asking for it by id
123
- reports the quarantine path. Stale `.tmp` files (over 10 minutes) and cancel
124
- markers for terminal runs are removed at mount.
125
- - Orphaned runs no longer hold the active-run quota: a run with a heartbeat
126
- older than 90 s is reclaimed, using the owner pid only when the state
127
- directory belongs to this machine, and recording the exact basis on the run.
128
- - Tool errors are now `[error] <sentence>` / `hint: <next step>` /
129
- `detail: <untouched host message>`, covering 19 known failure shapes,
130
- including the Windows ACL sandbox launcher.
131
-
132
- ### Notifications and retention
133
-
134
- - The notify outcome is recorded on the run (`delivered`, `reason`) and shown
135
- by `superagent_status` / `superagent_list` when a finished run could not reach its
136
- session.
137
- - New opt-in `keepRuns` deletes terminal runs older than N days at mount.
138
- `superagent_list` prints the state directory's file count and size.
139
-
140
- ### Concurrency and recovery
141
-
142
- - Mount-time recovery no longer rewrites a run that another process is still
143
- running. Ownership is decided once, in `ownership()`: a fresh heartbeat, a
144
- live local pid, or a live local process holding the run lock all veto
145
- reclamation. Two profiles can share one state directory without overwriting
146
- each other's runs.
147
- - `superagent_resume` is now exclusive. It takes the same serial gate as
148
- `superagent_start`, claims `<runId>.lock` atomically, re-reads the run under
149
- that lock, refuses a run that still has a live owner, and applies the
150
- `maxActiveRuns` check. Two concurrent resumes, or a resume in a second
151
- process, can no longer run the same subtasks twice.
152
- - A lock left by a dead process on this machine is broken immediately; a live
153
- local process keeps its lock however long the run takes; a lock from another
154
- machine is broken after 10 minutes, because its pid cannot be checked.
155
- - `maxActiveRuns` is clamped to an integer (1–8), so a config value such as
156
- `"abc"` falls back to the default instead of making the quota `NaN`.
157
- - A cancel from another process is reported by `superagent_status` as
158
- `cancel requested ... not confirmed` (read from the marker) instead of being
159
- invisible until the owner saves.
160
- - A child whose provider never answers can no longer pin a run in
161
- `planning`/`running`: the spawn is abortable, so cancel and the deadline take
162
- effect, and a child that appears after the abort is disposed at once.
163
- - The terminal status and its notify outcome are written in a single save, so a
164
- reader never sees a finished run without its notify row. Waking the session is
165
- bounded (15 s) and the heartbeat keeps running until the terminal write lands,
166
- so a slow wake-up cannot make another process reclaim a live run.
167
- - Resuming a run now rebuilds `limits` from the current config while keeping
168
- the spend so far, so raising a cap and resuming actually works.
169
- - `runtime`, `saveChains`, and remembered child ids are released when a run
170
- ends instead of growing for the life of the host.
171
-
172
- ### Child safety
173
-
174
- - Children are capped with `maxSubagentDepth: 1` by default (passed to the host
175
- as `maxDepth`); a provider that cannot enforce it fails the start with an
176
- explicit error rather than running unbounded. `childPreset` is the supported
177
- way to narrow a child's tools. dsh 0.2.2-rc.1 has no per-run tool allowlist —
178
- its start request has no tool filter — so the plugin documents that limit
179
- instead of pretending to enforce one.
180
-
181
- ### Real-host end-to-end (2026-11-14)
182
-
183
- The first run against a real `dsh@0.2.2-rc.1` host (keyless stub model, full
184
- record in `docs/e2e-2026-11-14.md`) found four behaviours that the offline
185
- suite could not see:
186
-
187
- - **A graceful host shutdown buried resumable work as `failed`.** When the
188
- `subagents` service disappears mid-run (a one-shot headless turn ends),
189
- children throw "service unavailable". That used to burn both attempts and
190
- settle the run `failed`. It is now recognised as the host going away: the
191
- unfinished subtasks stay `pending`, no attempts are spent, and the run
192
- settles `interrupted` with `note: the host shut down while this run was
193
- active`. `superagent_resume` picks it up in the next host.
194
- - **A dead pid was ignored for 90 s.** `ownership()` trusted a fresh heartbeat
195
- before checking the owner pid, so a `kill -9` left the run `running` for a
196
- minute and a half on the very machine that could prove the pid was gone. On
197
- a run written by this machine, a dead pid now wins over the heartbeat; a run
198
- from another machine on a shared directory still trusts the heartbeat.
199
- - **A reclaimed run claimed its cost was unknown.** Recovery now republishes
200
- `run.usage` from `usageByChild` and recomputes `cost`, so an interrupted run
201
- shows the money already spent instead of "not computed".
202
- - **Per-subtask usage was often `null` after a normal run.** The read at child
203
- completion can race the log flush; the settle pass now writes the final
204
- per-child snapshot back onto each subtask.
205
-
206
- Also: the plugin no longer ships a price for `qwen-flash` (the README already
207
- promised that nothing is priced out of the box); the table is empty unless the
208
- profile configures one.
209
-
210
-
211
- ### Install and first run
212
-
213
- - Requirements corrected to what `dsh@0.2.2-rc.1` needs: Node `>=24.9.0`, and
214
- the default route's `DEEPSEEK_API_KEY` (not a DashScope key).
215
- - Quickstart no longer tells people to `npm i -g dsh` (that is an unrelated
216
- package); it uses `npx @deepseek-ai/dsh@0.2.2-rc.1` and
217
- `dsh plugin --profile web add @xiangyixie/dsh-superagent`.
218
- - `usage: accounting pending` while a run is active; `usage: not recorded` only
219
- on a finished run whose logs are unreadable. `interrupted` runs print the
220
- `superagent_resume` next step, cancelled runs show unstarted subtasks as
221
- `skipped`, and elapsed time separates running time from downtime.
222
- - Pricing keys match `provider/model` exactly, then by bare model name, so a
223
- `qwen-flash` entry also prices `dashscope/qwen-flash`.
224
- - An unusable state directory is reported by every tool instead of appearing as
225
- an empty run list; `ENOENT`/`ENOTDIR` are classified as filesystem errors.
226
- - Missing credentials and unknown model ids have their own classifications and
227
- hints. The auth hint names the default route's key first.
228
- - The plugin mounts even without the `subagents` service (that dependency is
229
- optional), and `superagent_start` then explains what is missing instead of the
230
- five tools silently disappearing.
231
- - `exports` only advertises the plugin entry point; the undocumented internal
232
- subpaths that shipped without types are gone.
233
-
234
- ### Tests
235
-
236
- - 86 offline tests (`npm test`): fake store, fake child spawner, no network, no
237
- API key. Covers cross-process cancel, orphan reclamation in both local and
238
- shared modes, concurrent and cross-process resume, resume quotas and limit
239
- rebuilding, budgets with and without readable usage logs, pricing keys, a
240
- child that ignores abort, notify ordering, corrupted state, a missing state
241
- directory, retention, error text, usage-log reading, the HTTP control plane
242
- (auth, transport errors, discovery lifecycle, start/stop races), and a full
243
- plugin mount. Polling-based tests were rewritten around event gates; five
244
- consecutive full runs pass.
1
+ # Changelog
2
+
3
+ Doc-only releases: npm serves the README from the tarball, so a README edit is
4
+ invisible on the package page until something is published. When the edit
5
+ changes what a reader would do — install commands, limits, troubleshooting
6
+ steps — it gets its own patch version (0.9.2, 0.9.3). Typos and wording ride
7
+ along with the next code release. A doc-only version leaves `lib/` and `bin/`
8
+ byte-identical to the version before it, and the pinned install line in the
9
+ README is updated to the version being released.
10
+
11
+ ## 0.9.3 — 2026-11-14
12
+
13
+ Documentation only; no code change.
14
+
15
+ - Both install commands name the version (`@xiangyixie/dsh-superagent@0.9.3`),
16
+ and the Quickstart explains why: pnpm's minimum release age skips packages
17
+ published in the last few hours, so a bare `add` installs an older version and
18
+ still reports success. A bare install here resolved 0.9.0 while 0.9.2 was
19
+ current.
20
+ - Added the command that reports what actually landed:
21
+ `npm ls --prefix <DSH_HOME>/profiles/web @xiangyixie/dsh-superagent`.
22
+ - The troubleshooting rows for a missing tool and for
23
+ `Cannot find module .../lib/control.js` now carry the pinned reinstall command.
24
+
25
+ ## 0.9.2 — 2026-11-14
26
+
27
+ Documentation only; no code change. npm renders the README from the tarball, so
28
+ this version exists to put the rewritten opening on the package page.
29
+
30
+ - The first screen now answers three questions in order: what the plugin is for,
31
+ when it is the wrong tool, and the first command to run after installing.
32
+ - `Naming` moved from the top to just above `Development`. The copyright line
33
+ and the "personal project, not affiliated with DeepSeek" statement moved to
34
+ the top, where they are read.
35
+ - `Known limits` gained the isolation boundary: children use the host's
36
+ credentials and filesystem and are only as sandboxed as the host makes them.
37
+
38
+ ## 0.9.1 — 2026-11-14
39
+
40
+ Metadata-only release. No code or behaviour change; the only file contents that
41
+ differ are `package.json`, `README.md`, and this changelog.
42
+
43
+ - Added the `author` field (`Admire (LittleChenLiya)`), matching the copyright
44
+ line in `LICENSE`. The registry metadata carries it from this version on
45
+ (`npm view @xiangyixie/dsh-superagent author`); the npmjs.com package page has
46
+ no separate Author row in its current layout — it lists Collaborators — so the
47
+ visible credit is the copyright line in the README's License section.
48
+ - The README "License" section now names the copyright holder, links
49
+ `LICENSE`, and says that the npm scope `@xiangyixie` and the GitHub account
50
+ `LittleChenLiya` are the same author.
51
+
52
+ ## 0.9.0 — 2026-11-14
53
+
54
+ Hardening pass before the first publish. No behaviour change for the happy
55
+ path except the new spending caps, the cost line, and two operator utilities.
56
+
57
+ ### Published as `@xiangyixie/dsh-superagent`
58
+
59
+ - npm already carries a `dsh-super-agent` that its similarity check treats as
60
+ the same name as the unscoped one, so the first release goes out under the
61
+ author scope. The project, the repository, the plugin row id (`superagent`),
62
+ the five tools (`superagent_*`), the state directory, and both bin names are
63
+ unchanged; only the install specifier differs:
64
+ `dsh plugin --profile web add @xiangyixie/dsh-superagent`.
65
+
66
+ ### Watch panel and HTML report
67
+
68
+ - `dsh-superagent-watch` draws one line per run — id, status, calls used against
69
+ the cap, elapsed, current activity, parent session — in the alternate screen.
70
+ A status change repaints within 200 ms; an idle panel costs one small file
71
+ read per second. Ctrl-C, SIGTERM, and a closed pipe restore the cursor and
72
+ leave the alternate screen; `--once` prints one plain frame and never takes
73
+ over the screen.
74
+ - `dsh-superagent-report` renders recorded runs into one self-contained HTML
75
+ file: inline CSS and inline SVG, no script, no font, no image, no network. It
76
+ contains a timeline with each run's start, end, and derived
77
+ planning/work/merge phases; swimlanes whose count is the peak concurrency;
78
+ cumulative model-call and cost curves; explicit failure, cancellation, and
79
+ interruption annotations; and a run table.
80
+ - Neither utility adds a dependency. The package is still `dependencies: {}`;
81
+ the tarball grows from 11 to 15 files (73.4 kB packed, 240.7 kB unpacked).
82
+
83
+ ### Embedding surface (local HTTP)
84
+
85
+ - New opt-in `controlPort` exposes the five operations as JSON over loopback:
86
+ `GET /`, `GET /health`, `GET /runs`, `GET /runs/:id`, `POST /runs`,
87
+ `POST /runs/:id/cancel`, `POST /runs/:id/resume`. Off by default; `0` picks a
88
+ free port. Another UI can start and watch runs without importing `lib/`.
89
+ - Bound to `127.0.0.1` only, with a per-process bearer token written to
90
+ `<stateDir>/control.json` (mode `0600`), a `Host` check that blocks DNS
91
+ rebinding, no CORS headers, a 64 KB body cap, and a 60 s limit on receiving a
92
+ request (a 300 s long poll is unaffected: the wait happens while the response
93
+ is produced).
94
+ - Every route goes through the same orchestrator as the tools: quota, budgets,
95
+ run locks, cross-process cancel, and recovery behave identically. `POST /runs`
96
+ requires `session_id` of a live session; a run still needs a real parent agent
97
+ for its children, and a missing session is refused as `no-session` rather than
98
+ started without an owner.
99
+ - Replies carry the same `text` as the tool result, plus the stored run object
100
+ (`schemaVersion: 1`). Transport errors have their own ids (`unauthorized`,
101
+ `forbidden-host`, `no-session`, `body-too-large`, …) so a client can tell a
102
+ bad token from a broken run.
103
+ - The contract, security model, and client examples are in
104
+ [docs/embedding.md](https://github.com/LittleChenLiya/dsh-superagent/blob/main/docs/embedding.md);
105
+ verified against real `dsh@0.2.2-rc.1` with 17 checks in
106
+ `docs/e2e/transcripts/control-plane.log`, plus a two-host cross-process cancel
107
+ run in `docs/e2e/transcripts/cross-cancel.log`.
108
+ - Review fixes before release: a dispose that lands while the port is still
109
+ binding now closes it instead of leaving an orphaned listener; a failed
110
+ discovery write closes the server instead of running unreachable; `/health`
111
+ does no state work, so a liveness probe cannot reclaim runs; a blank goal is
112
+ a 400 `no-goal` and a profile without a subagent service is a 503
113
+ `no-subagents` instead of a 500.
114
+ - A second review pass added: the plane starts only after the state directory
115
+ exists (a fresh `DSH_HOME` used to leave it off for the whole host lifetime);
116
+ discovery files carry a per-plane `instanceId`, so a reloaded plugin does not
117
+ delete the newer plane's file; a concurrent `start()` shares one listener;
118
+ `GET /runs?limit` also limits the returned array; a missing goal is reported
119
+ before a missing session; a worker session is refused by `superagent_cancel`
120
+ as well; and a malformed `controlPort` (`""`, `" "`, `true`) can no longer
121
+ coerce to an accidental listener.
122
+
123
+ ### Renamed to `dsh-superagent`
124
+
125
+ - The package, repository, plugin row id (`superagent`), default state
126
+ directory (`state/superagent`), log prefix, and all five tools
127
+ (`superagent_*`) moved from the working name `dsh-longhaul`.
128
+ - Nothing was ever published under the old name, so there is no migration and
129
+ no compatibility alias: `longhaul_*` calls simply do not exist. A run started
130
+ under the old default state directory is still readable by pointing
131
+ `stateDir` at it.
132
+
133
+ ### Cancellation
134
+
135
+ - `superagent_cancel` now stops the run when it is called from a different
136
+ process. The caller writes a `<runId>.cancel` marker; the owning process polls
137
+ it once per second, aborts its children, disposes their activations, and
138
+ records `cancelled`. The caller waits up to 5 s and reports
139
+ `cancel requested ... not confirmed` instead of claiming a success it cannot
140
+ observe.
141
+ - Recovery converts a marked run to `cancelled` rather than `interrupted`, and
142
+ `superagent_resume` clears a stale marker.
143
+
144
+ ### Spending
145
+
146
+ - New hard budgets `maxModelCallsPerRun` (80) and `maxTokensPerRun` (2,000,000),
147
+ checked before every child spawn. Hitting one stops spawning: the run ends
148
+ `partial` when at least one subtask finished and `failed` when none did, keeps
149
+ the reports that did finish, and leaves the rest `pending` for a resume.
150
+ - A tool's `max_subtasks` / `max_parallel` / `deadline_minutes` can narrow the
151
+ configured cap but never widen it: the config stays the operator's control.
152
+ - New `pricing` table (per 1M tokens, per model) and a `cost` field on every
153
+ run. Unpriced models are named and excluded instead of being estimated.
154
+ - `usage: not recorded` now explains why instead of printing two bare words.
155
+
156
+ ### Robustness
157
+
158
+ - A run file that is not valid JSON is quarantined as
159
+ `<runId>.json.corrupt-<ts>` and skipped by listings; asking for it by id
160
+ reports the quarantine path. Stale `.tmp` files (over 10 minutes) and cancel
161
+ markers for terminal runs are removed at mount.
162
+ - Orphaned runs no longer hold the active-run quota: a run with a heartbeat
163
+ older than 90 s is reclaimed, using the owner pid only when the state
164
+ directory belongs to this machine, and recording the exact basis on the run.
165
+ - Tool errors are now `[error] <sentence>` / `hint: <next step>` /
166
+ `detail: <untouched host message>`, covering 19 known failure shapes,
167
+ including the Windows ACL sandbox launcher.
168
+
169
+ ### Notifications and retention
170
+
171
+ - The notify outcome is recorded on the run (`delivered`, `reason`) and shown
172
+ by `superagent_status` / `superagent_list` when a finished run could not reach its
173
+ session.
174
+ - New opt-in `keepRuns` deletes terminal runs older than N days at mount.
175
+ `superagent_list` prints the state directory's file count and size.
176
+
177
+ ### Concurrency and recovery
178
+
179
+ - Mount-time recovery no longer rewrites a run that another process is still
180
+ running. Ownership is decided once, in `ownership()`: a fresh heartbeat, a
181
+ live local pid, or a live local process holding the run lock all veto
182
+ reclamation. Two profiles can share one state directory without overwriting
183
+ each other's runs.
184
+ - `superagent_resume` is now exclusive. It takes the same serial gate as
185
+ `superagent_start`, claims `<runId>.lock` atomically, re-reads the run under
186
+ that lock, refuses a run that still has a live owner, and applies the
187
+ `maxActiveRuns` check. Two concurrent resumes, or a resume in a second
188
+ process, can no longer run the same subtasks twice.
189
+ - A lock left by a dead process on this machine is broken immediately; a live
190
+ local process keeps its lock however long the run takes; a lock from another
191
+ machine is broken after 10 minutes, because its pid cannot be checked.
192
+ - `maxActiveRuns` is clamped to an integer (1–8), so a config value such as
193
+ `"abc"` falls back to the default instead of making the quota `NaN`.
194
+ - A cancel from another process is reported by `superagent_status` as
195
+ `cancel requested ... not confirmed` (read from the marker) instead of being
196
+ invisible until the owner saves.
197
+ - A child whose provider never answers can no longer pin a run in
198
+ `planning`/`running`: the spawn is abortable, so cancel and the deadline take
199
+ effect, and a child that appears after the abort is disposed at once.
200
+ - The terminal status and its notify outcome are written in a single save, so a
201
+ reader never sees a finished run without its notify row. Waking the session is
202
+ bounded (15 s) and the heartbeat keeps running until the terminal write lands,
203
+ so a slow wake-up cannot make another process reclaim a live run.
204
+ - Resuming a run now rebuilds `limits` from the current config while keeping
205
+ the spend so far, so raising a cap and resuming actually works.
206
+ - `runtime`, `saveChains`, and remembered child ids are released when a run
207
+ ends instead of growing for the life of the host.
208
+
209
+ ### Child safety
210
+
211
+ - Children are capped with `maxSubagentDepth: 1` by default (passed to the host
212
+ as `maxDepth`); a provider that cannot enforce it fails the start with an
213
+ explicit error rather than running unbounded. `childPreset` is the supported
214
+ way to narrow a child's tools. dsh 0.2.2-rc.1 has no per-run tool allowlist —
215
+ its start request has no tool filter — so the plugin documents that limit
216
+ instead of pretending to enforce one.
217
+
218
+ ### Real-host end-to-end (2026-11-14)
219
+
220
+ The first run against a real `dsh@0.2.2-rc.1` host (keyless stub model, full
221
+ record in `docs/e2e-2026-11-14.md`) found four behaviours that the offline
222
+ suite could not see:
223
+
224
+ - **A graceful host shutdown buried resumable work as `failed`.** When the
225
+ `subagents` service disappears mid-run (a one-shot headless turn ends),
226
+ children throw "service unavailable". That used to burn both attempts and
227
+ settle the run `failed`. It is now recognised as the host going away: the
228
+ unfinished subtasks stay `pending`, no attempts are spent, and the run
229
+ settles `interrupted` with `note: the host shut down while this run was
230
+ active`. `superagent_resume` picks it up in the next host.
231
+ - **A dead pid was ignored for 90 s.** `ownership()` trusted a fresh heartbeat
232
+ before checking the owner pid, so a `kill -9` left the run `running` for a
233
+ minute and a half on the very machine that could prove the pid was gone. On
234
+ a run written by this machine, a dead pid now wins over the heartbeat; a run
235
+ from another machine on a shared directory still trusts the heartbeat.
236
+ - **A reclaimed run claimed its cost was unknown.** Recovery now republishes
237
+ `run.usage` from `usageByChild` and recomputes `cost`, so an interrupted run
238
+ shows the money already spent instead of "not computed".
239
+ - **Per-subtask usage was often `null` after a normal run.** The read at child
240
+ completion can race the log flush; the settle pass now writes the final
241
+ per-child snapshot back onto each subtask.
242
+
243
+ Also: the plugin no longer ships a price for `qwen-flash` (the README already
244
+ promised that nothing is priced out of the box); the table is empty unless the
245
+ profile configures one.
246
+
247
+
248
+ ### Install and first run
249
+
250
+ - Requirements corrected to what `dsh@0.2.2-rc.1` needs: Node `>=24.9.0`, and
251
+ the default route's `DEEPSEEK_API_KEY` (not a DashScope key).
252
+ - Quickstart no longer tells people to `npm i -g dsh` (that is an unrelated
253
+ package); it uses `npx @deepseek-ai/dsh@0.2.2-rc.1` and
254
+ `dsh plugin --profile web add @xiangyixie/dsh-superagent`.
255
+ - `usage: accounting pending` while a run is active; `usage: not recorded` only
256
+ on a finished run whose logs are unreadable. `interrupted` runs print the
257
+ `superagent_resume` next step, cancelled runs show unstarted subtasks as
258
+ `skipped`, and elapsed time separates running time from downtime.
259
+ - Pricing keys match `provider/model` exactly, then by bare model name, so a
260
+ `qwen-flash` entry also prices `dashscope/qwen-flash`.
261
+ - An unusable state directory is reported by every tool instead of appearing as
262
+ an empty run list; `ENOENT`/`ENOTDIR` are classified as filesystem errors.
263
+ - Missing credentials and unknown model ids have their own classifications and
264
+ hints. The auth hint names the default route's key first.
265
+ - The plugin mounts even without the `subagents` service (that dependency is
266
+ optional), and `superagent_start` then explains what is missing instead of the
267
+ five tools silently disappearing.
268
+ - `exports` only advertises the plugin entry point; the undocumented internal
269
+ subpaths that shipped without types are gone.
270
+
271
+ ### Tests
272
+
273
+ - 86 offline tests (`npm test`): fake store, fake child spawner, no network, no
274
+ API key. Covers cross-process cancel, orphan reclamation in both local and
275
+ shared modes, concurrent and cross-process resume, resume quotas and limit
276
+ rebuilding, budgets with and without readable usage logs, pricing keys, a
277
+ child that ignores abort, notify ordering, corrupted state, a missing state
278
+ directory, retention, error text, usage-log reading, the HTTP control plane
279
+ (auth, transport errors, discovery lifecycle, start/stop races), and a full
280
+ plugin mount. Polling-based tests were rewritten around event gates; five
281
+ consecutive full runs pass.