@xiangyixie/dsh-superagent 0.10.0 → 0.12.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/README.md CHANGED
@@ -1,4 +1,4 @@
1
- # dsh-superagent
1
+ # dsh-superagent
2
2
 
3
3
  Long-horizon runs for [DeepSeek Harness](https://dshai.org): one goal in,
4
4
  model-planned parallel subtasks, one merged report — and the run survives a host
@@ -17,14 +17,15 @@ prints the cost once you give it a price for the route.
17
17
  planner and an aggregator on top. It is also the wrong tool for work that must
18
18
  finish inside a single turn, for a step that needs human approval in the middle,
19
19
  for anything that needs nested delegation (child depth is capped at 1), and for
20
- anyone who wants an in-host panel — this adds no UI, only six tools. Children run
21
- with the host's credentials and filesystem; this is not a sandbox.
20
+ anyone who wants an in-host panel — the optional workspace panel below is a
21
+ loopback page, not host UI. Children run with the host's credentials and
22
+ filesystem; this is not a sandbox.
22
23
 
23
24
  **Install and run.** Node `>= 24.9.0`, a tool-calling route, and that route's key
24
25
  in the environment:
25
26
 
26
27
  ```bash
27
- dsh plugin --profile web add @xiangyixie/dsh-superagent@0.10.0
28
+ dsh plugin --profile web add @xiangyixie/dsh-superagent@0.12.0
28
29
  ```
29
30
 
30
31
  Then ask the session for a run — a real call, not a sketch:
@@ -36,9 +37,10 @@ The reply ends `completed` with the merged report, or with
36
37
  covers the path from an empty machine, including the reason not to install npm's
37
38
  unrelated `dsh` package by name.
38
39
 
39
- It adds no in-host UI and patches no host code: the six `superagent_*` tools are
40
- the surface, plus two optional operator utilities (a terminal panel and an HTML
41
- report) that read the same run files.
40
+ It adds no in-host UI (the opt-in workspace panel is a loopback page) and patches
41
+ no host code: the eleven `superagent_*` tools are the surface, plus six optional
42
+ operator utilities (a terminal panel, an HTML report, an install doctor, a run
43
+ archive, git sync, and the workspace panel) that read the same run files.
42
44
 
43
45
  Personal project, not affiliated with DeepSeek or the harness maintainers. MIT
44
46
  licensed, © 2026 Admire (LittleChenLiya); details in [License](#license).
@@ -73,7 +75,7 @@ your `PATH`, use `npx @deepseek-ai/dsh@0.2.2-rc.1` instead.
73
75
 
74
76
  ```bash
75
77
  # 1. install the plugin into a profile (web, headless, ... whatever you run)
76
- dsh plugin --profile web add @xiangyixie/dsh-superagent@0.10.0
78
+ dsh plugin --profile web add @xiangyixie/dsh-superagent@0.12.0
77
79
 
78
80
  # 2. confirm the bundle row exists in the merged config
79
81
  dsh --profile web --dump-config
@@ -204,7 +206,10 @@ Row config in `<profile>/cordis.patch.yml`:
204
206
  | `maxSubagentDepth` | `1` | How deep children may delegate. `1` forbids grandchildren; `provider-managed` leaves it to the backend. |
205
207
  | `maxSubtasks` | `8` | Cap on planned subtasks. A tool argument can only lower it, never raise it; hard max 16. |
206
208
  | `maxParallel` | `3` | Subtasks executing at once. A tool argument can only lower it; hard max 8. |
207
- | `maxActiveRuns` | `2` | Active runs per state directory, across profiles and hosts that share it; further `superagent_start` calls are rejected. `superagent_resume` is not counted and works when the cap is full, because it only finishes work that already exists. |
209
+ | `maxActiveRuns` | `2` | Active runs per state directory, across profiles and hosts that share it. A further `superagent_start` is rejected unless it passes `queue: true`, in which case it waits for a slot instead. `superagent_resume` is not counted and works when the cap is full, because it only finishes work that already exists. |
210
+ | `maxQueuedRuns` | `5` | Runs allowed to wait for a free slot at once; hard max 32. `0` turns queueing off, so every start over `maxActiveRuns` is rejected again. |
211
+ | `queueTimeoutMinutes` | `30` | How long a queued run waits before it fails without ever starting; nothing is spent. |
212
+ | `queueOnFull` | `false` | Queue every start that exceeds `maxActiveRuns`, not only the ones that pass `queue: true`. |
208
213
  | `attempts` | `2` | Attempts per subtask before it is marked failed. A failure that looks transient (quota, rate limit, timeout, 5xx) waits 2s, then 4s, then 8s before the next attempt. |
209
214
  | `deadlineMinutes` | `120` | Wall-clock budget; on expiry the run ends `partial` or `failed`. |
210
215
  | `maxModelCallsPerRun` | `80` | Hard cap on child model calls per run; `0` disables. |
@@ -212,8 +217,8 @@ Row config in `<profile>/cordis.patch.yml`:
212
217
  | `pricing` | empty | Per-1M-token prices, keyed exactly as the usage log names the model (`provider/model`). Nothing is priced out of the box. |
213
218
  | `resultCapBytes` | `32768` | Bytes kept per subtask report. |
214
219
  | `notifyOnComplete` | `true` | Master switch for proactive messages. Off means the plugin never wakes the session. |
215
- | `maxNotificationsPerHour` | `3` | Proactive messages allowed per hour. Runs above the cap are folded into one summary; `0` disables the cap. |
216
- | `notifyRetries` | `2` | Extra delivery attempts when the host refuses a wake-up; messages for one session are delivered in order. |
220
+ | `maxNotificationsPerHour` | `3` | Proactive messages allowed per hour. Runs above the cap are folded into one summary; `0` disables the cap. |
221
+ | `notifyRetries` | `2` | Extra delivery attempts when the host refuses a wake-up; messages for one session are delivered in order. |
217
222
  | `notifyRetryDelayMs` | `2000` | First delay between those attempts; it doubles per attempt, capped at 60s. |
218
223
  | `autoResumeRounds` | `1` | Extra rounds that retry subtasks which failed in a way that looks transient, before the failure is reported; `0` disables. |
219
224
  | `childModelFallback` | none | Model used on such a retry (quota, rate limit, timeout). Unset keeps the configured route. |
@@ -224,7 +229,15 @@ Row config in `<profile>/cordis.patch.yml`:
224
229
  | `memoryDigestEntries` | `12` | Notes injected into a prompt. |
225
230
  | `memoryDigestChars` | `1600` | Character budget for the note part of that prompt. |
226
231
  | `keepRuns` | `0` | Delete terminal runs older than this many days at mount; `0` keeps everything. |
232
+ | `guard` | on | Worker path and command policy. See [Worker safety guard](#worker-safety-guard) for every default and the reason behind it. |
233
+ | `audit` | `true` | Append-only audit trail. It only observes; turning it off removes the trail, never the run behaviour. |
234
+ | `policyFile` | `<stateDir>/policy.json` when it exists | Permission policy. Unset and absent means no policy, i.e. the old behaviour. |
235
+ | `auditDir` | `<stateDir>/audit` | Where `audit.jsonl` and its exports live. |
227
236
  | `controlPort` | off | Loopback port for the embedding surface; `0` picks a free one. See [docs/embedding.md](https://github.com/LittleChenLiya/dsh-superagent/blob/main/docs/embedding.md). |
237
+ | `workspaceIsolation` | `false` | Give every worker its own git worktree so parallel workers cannot overwrite each other. See [Per-worker workspace isolation](#per-worker-workspace-isolation). |
238
+ | `workspaceRoot` | host cwd | Repository the workers are isolated in when `workspaceIsolation` is on. Must be a git working tree with at least one commit. |
239
+ | `workbenchPort` | off | Loopback port for the local workspace panel; `0` picks a free one. The panel reads and edits files itself, without a host API. |
240
+ | `workbenchRoot` | `process.cwd()` | Directory the panel may browse and edit. Every path outside it is refused. |
228
241
 
229
242
  ### Switching models
230
243
 
@@ -262,8 +275,142 @@ subagent start request has no tool filter, and its own `subagent` tool rejects a
262
275
  `toolFilter` config and points at agent presets. `childPreset` is therefore the
263
276
  supported way to narrow a child's tools; without a dedicated preset, workers
264
277
  inherit the session's tools. The `superagent_*` tools still exist in their tool
265
- list, but `superagent_start`, `superagent_resume`, and `superagent_cancel`
266
- refuse to run from a worker session; only the top-level agent manages runs.
278
+ list, but the run tools (`superagent_start`, `superagent_resume`, `superagent_cancel`,
279
+ `superagent_followup`, `superagent_inject`, `superagent_answer`) refuse to run from a worker session;
280
+ only the top-level agent manages runs.
281
+
282
+ ### Per-worker workspace isolation
283
+
284
+ Parallel workers are independent agents, but by default they share one working
285
+ directory: two subtasks that edit the same file overwrite each other, and the
286
+ last writer wins. `workspaceIsolation` fixes that by giving each worker its own
287
+ checkout.
288
+
289
+ ```yaml
290
+ - id: superagent
291
+ config:
292
+ workspaceIsolation: true
293
+ workspaceRoot: /home/me/projects/api # or C:\work\api on Windows
294
+ ```
295
+
296
+ **Why git worktrees rather than a directory copy.** The hard half of isolation
297
+ is merging the results back. A worktree gives that for free: a real three-way
298
+ merge with conflict detection, both sides preserved as refs, and one command the
299
+ user can run to finish by hand. A recursive copy would either need a diff3
300
+ engine (a dependency this package does not have) or overwrite the main checkout,
301
+ which is the bug the feature exists to prevent. A worktree also shares the object
302
+ database and ignore rules, so a worker sees the real repository without a full
303
+ copy of it. Worktrees live under `<stateDir>/workspaces/<runId>/w<n>`; that
304
+ directory carries its own `.gitignore`, so a state directory inside a repository
305
+ does not leak worker checkouts into the user's next commit.
306
+
307
+ **What happens during a run.** Each worker is given
308
+ `superagent/<runId>-w<n>`, a branch created from the main checkout's `HEAD`. Its
309
+ prompt names the absolute path and forbids touching anything else, switching
310
+ branches, committing, merging, or pushing. When the worker finishes, the run
311
+ commits whatever it left in the checkout (so a model that forgot to commit still
312
+ loses nothing; git hooks are skipped so a pre-commit hook cannot block the merge)
313
+ and then merges the branches into the main checkout **one at a time**, after all
314
+ subtasks are done.
315
+
316
+ **What you see when a merge conflicts.** The merge is aborted, so the main
317
+ checkout is restored exactly as it was and no conflict markers are left in it.
318
+ The outcome is recorded on the run and printed by `superagent_status`:
319
+
320
+ ```
321
+ workspace conflict: [2] src/routes.js, src/index.js — branch superagent/20261115T101500-ab12-w2
322
+ kept at <stateDir>/workspaces/20261115T101500-ab12/w2; the main checkout was restored, so nothing
323
+ was lost. Resolve with: git -C "/home/me/projects/api" merge superagent/20261115T101500-ab12-w2
324
+ ```
325
+
326
+ The wake-up message for the run says the same in one line, because a conflict is
327
+ the one outcome that needs the user even when the run itself "completed". Nothing
328
+ is discarded: the branch and its checkout are kept until you merge or delete
329
+ them. Two more cases are reported the same way rather than silently dropped:
330
+
331
+ - the main checkout has uncommitted changes when the merge is due — every
332
+ branch is left unmerged, since merging into a dirty tree would mix your edits
333
+ with the workers' and make an abort restore the wrong state;
334
+ - the run was cancelled or hit its deadline before merging — the branches are
335
+ kept and a resume reuses the same worktrees.
336
+
337
+ **When isolation is not possible.** If `workspaceRoot` is not a git working tree,
338
+ git is not on `PATH`, or the repository has no commit yet, the run does not fail.
339
+ It falls back to the shared directory (the previous behaviour) and both
340
+ `superagent_status` and the notification say so:
341
+
342
+ ```
343
+ workspace: isolation was requested but is unavailable — /tmp/notes is not a git working tree,
344
+ so a per-worker worktree cannot be created; workers shared /tmp/notes, so their edits can
345
+ overwrite each other
346
+ ```
347
+
348
+ **Limits, stated plainly.** `dsh@0.2.2-rc.1` gives a child agent no `cwd` field,
349
+ so the plugin cannot hand a worker a directory at spawn time. Isolation is a
350
+ prompt contract plus a real branch: a worker that ignores the prompt can still
351
+ edit the main checkout, but that shows up in `git status` before any merge and
352
+ cannot damage a sibling's branch. With isolation off, behaviour is exactly what
353
+ it was before this option existed.
354
+
355
+ ### Worker safety guard
356
+
357
+ Workers inherit the session's filesystem and credentials, so every tool call a
358
+ superagent child makes passes through a guard mounted on the host's
359
+ `tools/pre-execute` path (`ctx.tools.guard` when available). The guard only
360
+ policies children this plugin spawned; the parent session is untouched.
361
+
362
+ ```yaml
363
+ - id: superagent
364
+ config:
365
+ guard:
366
+ enabled: true
367
+ allowWriteRoots: [] # extra writable roots, absolute or ~-relative
368
+ denyPaths: [] # extra read+write denials
369
+ denyCommands: [] # [{ id, pattern, reason }] extra regex denials
370
+ allowCommands: # explicit overrides; every use is recorded
371
+ - id: clean-build
372
+ pattern: '^rm -rf build$'
373
+ reason: clean build output
374
+ maxEvents: 50
375
+ ```
376
+
377
+ Defaults, and why they are set that way:
378
+
379
+ | Rule | Default | Why |
380
+ | --- | --- | --- |
381
+ | Write roots | The child session's working directory plus the OS temp directory | A worker needs its own workspace and a scratch area. Everything else is outside the job, so it is refused. The state directory is deliberately **not** writable: a worker must not rewrite run records or reports. |
382
+ | Always denied (read and write) | `~/.ssh`, `~/.aws`, `~/.gnupg`, `~/.netrc`, `~/.npmrc`, `~/.yarnrc`, `~/.pypirc`, `~/.git-credentials`, `~/.docker/config.json`, `~/.kube/config`, `~/.config/gcloud`, `~/.config/gh/hosts.yml`, `~/.azure`, any `.git/config` and `.git/hooks` | These are credentials or code-execution vectors. A broader workspace never opens them. |
383
+ | System directories | Writable by nobody (`C:\Windows`, `C:\Program Files`, `C:\ProgramData`, `/etc`, `/usr`, `/bin`, `/boot`, `/dev`, `/System`, `/Library`, …), except the OS temp directory | Reading them is normal (`win.ini`, `/etc/hosts`); writing them is not a development task. The temp exception exists because `%TEMP%` can live under `C:\Windows\TEMP` for service accounts, and workers must still be able to write scratch files there. |
384
+ | `cmd/recursive-force-delete` | Denied when the target is `/`, a drive root, `~`, `.`, `..`, `*`, outside the write roots, or contains one | `rm -rf build` and `rm -rf node_modules` are normal; `rm -rf /` and `rm -rf .` are not. Blanket-blocking every `rm -rf` would make ordinary cleanup impossible, so the target decides. |
385
+ | `cmd/disk-format` | `mkfs`, `diskpart`, `wipefs`, `format X:`, `dd of=/dev/sd*` | Never a development action. |
386
+ | `cmd/system-scheduler` | `schtasks /create`, `Register-ScheduledTask`, `crontab -r`, `systemctl enable\|disable\|mask`, `launchctl load` | Persistence outside the workspace. |
387
+ | `cmd/system-registry` | `reg add/delete` on `HKLM`/`HKCR`, and any `\Run` key | Machine-wide or auto-start changes. |
388
+ | `cmd/system-write` | A redirection or write cmdlet whose target is a system directory, including `%SystemRoot%`/`$env:SystemRoot` | Catches writes that hide behind a variable. |
389
+ | `cmd/permission-nuke` | `chmod -R 777 /`, recursive `chown` of `/`, `icacls … /grant Everyone /t` | Destroys the access model of the machine. |
390
+ | `cmd/credential-access` | A shell command that names one of the credential locations above, `id_rsa`, `id_ed25519`, … | A worker reading a key is as harmful as writing one. |
391
+
392
+ A denial is a real tool error, not a silent failure: the worker receives
393
+ `[guard] blocked <tool>: rule <id> — <reason>. The call did not run.`, and the
394
+ event is added to the run. `superagent_status` prints
395
+ `guard: N tool call(s) blocked; M explicit allow(s) recorded (rule ×count)`
396
+ plus up to three blocked commands, and the finished report gains a
397
+ `## Safety guard` section listing every kept event. Counters cover all events
398
+ even when `maxEvents` stops the list.
399
+
400
+ `allowCommands` is the only override. It wins over a denial, but every match is
401
+ recorded as `decision: allowed` with the rule it overrode, so an override is
402
+ never invisible. Credential, `.git` control, and system-directory denials are
403
+ not overridable; to permit a legitimate build directory outside the workspace,
404
+ add it to `allowWriteRoots`. The guard is lexical and realpath based, so a
405
+ symlink inside the workspace that points at a denied path is still caught.
406
+
407
+ The guard is a policy layer over tool arguments, not an OS sandbox. A command
408
+ that delegates the write to a program (`node build.js`, a compiler) can still
409
+ write wherever that program runs; blocking that requires a host-level sandbox,
410
+ which `dsh@0.2.2-rc.1` does not expose. The guard stops direct `write`/`edit`/
411
+ `apply_patch` targets, shell redirections, and the destructive command classes
412
+ above, which covers the accidental `rm` and "write into `C:\Windows`" cases a
413
+ wandering worker actually produces.
267
414
 
268
415
  ### Spending limits and prices
269
416
 
@@ -315,8 +462,24 @@ cost: at least ¥0.0041 (estimate; no price for haoduo/gpt-6.1-sol)
315
462
 
316
463
  ## Tools
317
464
 
318
- - `superagent_start(goal, max_subtasks?, max_parallel?, deadline_minutes?, allow_duplicate?, wait_seconds?)`
319
- starts a run and returns immediately with a run id. Starting a goal that an
465
+ - `superagent_start(goal, mode?, queue?, max_subtasks?, max_parallel?, deadline_minutes?, allow_duplicate?, wait_seconds?)`
466
+ starts a run and returns immediately with a run id. `mode: "direct"` runs the
467
+ goal on one worker with no planner and no aggregator, and returns that worker's
468
+ reply as the report unchanged — right for one self-contained lookup, edit,
469
+ query, or short piece of writing, wrong for a goal with parts that can run in
470
+ parallel. The default, `mode: "planned"`, does the full planner → workers →
471
+ merged report pipeline. A planned subtask may declare `dependsOn` another
472
+ subtask: the dependent waits for it and gets its report in its prompt, while
473
+ independent subtasks still run in parallel. A dependency cycle rejects the
474
+ plan before any work starts, and a dependency on a task the plan never
475
+ declared is skipped with the reason. Both modes produce the same run record,
476
+ quota, deadline, cancel, and usage accounting.
477
+ `queue: true` makes a start wait for a free slot when `maxActiveRuns` is in use
478
+ instead of failing: it returns `status: "queued"` with `queue.position` /
479
+ `queue.of`, starts automatically when an active run finishes, and fails after
480
+ `queueTimeoutMinutes` if no slot frees. At most `maxQueuedRuns` waits; a queued
481
+ run does not count against `maxActiveRuns` while it waits, and cancelling it
482
+ removes it from the line cleanly. Starting a goal that an
320
483
  active run in the same session already covers returns that run id marked
321
484
  `deduped: true` instead of paying for a second plan: the goal is compared after
322
485
  trimming, collapsing runs of whitespace, and ignoring case, and the check runs
@@ -337,12 +500,84 @@ cost: at least ¥0.0041 (estimate; no price for haoduo/gpt-6.1-sol)
337
500
  are told what failed and to check what the earlier attempt already did. Only
338
501
  the session that started the run may resume it. A resume is not counted
339
502
  against `maxActiveRuns`, so it works when the cap is full; `force` is still
340
- accepted but no longer needed.
341
- - `superagent_memory(action, key?, kind?, text?, scope?, limit?)` lists, adds,
342
- corrects, or forgets notebook notes. `set` with an existing key supersedes it;
343
- `forget` retracts it. `scope` addresses `rules` (project rules), `profile`
344
- (user preferences), or the run scope. The tool is additive: the five run tools
345
- keep their arguments and output.
503
+ accepted but no longer needed. A `completed` run stays completed unless it
504
+ holds an answer that never reached a prompt — then resume reopens it, because
505
+ otherwise that decision would be stranded.
506
+ - `superagent_followup(run_id, message)` adds an instruction to a run that is
507
+ already executing, instead of starting a second run. This tool is explicitly
508
+ next-prompt: the instruction is queued on the run and the next prompt built for
509
+ it carries it — the next worker spawn or the aggregation, whichever comes
510
+ first. Subtasks that are already running or finished keep their results and
511
+ never see it. The reply names that boundary, and status shows the same thing;
512
+ an instruction that arrives after the last boundary is recorded as
513
+ `never took effect` rather than looking delivered. A paused run
514
+ (`interrupted`, `failed`, `partial`, `cancelled`) keeps the instruction for
515
+ the next round, which starts when it is resumed; a `completed` run refuses it.
516
+ A run owned by another process is refused, because that owner's next save
517
+ would overwrite it. Only the session that started the run may add to it. Use
518
+ `superagent_inject` when the running workers must read the instruction now.
519
+ - `superagent_inject(run_id, message, subtask_index?, wait_seconds?)` delivers
520
+ one instruction into the workers that are running right now. It uses the
521
+ host's live steering channel (`subagents.sendMessage`, the same inbox the
522
+ agent loop drains at its next pre-step), so the message is part of the child's
523
+ next model request. It does not interrupt a model call already in flight: the
524
+ delay is the remainder of the step that is running (that model response plus
525
+ its tool batch). A live child that had already decided to stop runs one more
526
+ turn to read it, so an uncancelled child consumes it. The reply reports the
527
+ measured delay from acceptance to the child's next request, and marks a
528
+ message as `missed` — never as delivered — when the child is cancelled,
529
+ disposed, or finishes before another boundary. Worst case measured on a real
530
+ `dsh@0.2.2-rc.1` host: **6978 ms** with an 8 s child step and **2986 ms** with
531
+ a 4 s step, i.e. the bound tracks the step, not the plugin. With a host that
532
+ exposes no live channel, the tool degrades to the followup queue and says so
533
+ in the reply; it never calls that live.
534
+ - `superagent_answer(run_id, attention_id?, answer, wait_seconds?)` answers one
535
+ structured attention item so that run continues with the decision. An active
536
+ run applies the answer at its next boundary; a finished run is reopened and
537
+ only its aggregation runs again, now with the answer in the prompt, so the
538
+ report reflects the decision instead of the user starting a new run.
539
+ `attention_id` is required when more than one question is open. An answer is
540
+ matched to the id, not to the array position: an id that was never asked, a
541
+ question already answered, and a question retired by a later resume are all
542
+ refused, and an answer whose text is another question's option names that
543
+ other id instead of guessing.
544
+ - `superagent_memory(action, key?, kind?, text?, scope?, query?, tags?, limit?)`
545
+ lists, searches, adds, corrects, or forgets notebook notes. `set` with an
546
+ existing key supersedes it; `forget` retracts it. `scope` addresses `rules`
547
+ (project rules), `profile` (user preferences), or the run scope. `search`
548
+ ranks notes against `query` (the current goal works well) and/or exact `tags`,
549
+ so a relevant old note is found instead of only the newest ones; notes can
550
+ carry `tags` when set. The tool is additive: the ten other tools keep their
551
+ arguments and output.
552
+ - `superagent_template(action, id?, params?, template?, limit?)` lists, shows,
553
+ expands, saves, or deletes a workflow template: a fixed goal skeleton with
554
+ required parameters, when it fits, and when it does not. `expand` returns one
555
+ ordinary goal string, which `superagent_start` plans exactly like a typed goal;
556
+ a missing or empty parameter is refused by name instead of defaulted. A
557
+ template cannot set limits, budgets, a mode, or an override, so using one never
558
+ widens what a run may do. Built-in ids are read-only; custom ones live under
559
+ the template directory in the state directory, and a failure there is logged
560
+ without disabling the run tools.
561
+ - `superagent_inject(run_id, message, subtask_index?, wait_seconds?)` delivers
562
+ one instruction into the workers that are running right now. It uses the
563
+ host's live steering channel (`subagents.sendMessage`, the same inbox the
564
+ agent loop drains at its next pre-step), so the message is part of the child's
565
+ next model request. It does not interrupt a model call already in flight: the
566
+ delay is the remainder of the step that is running (that model response plus
567
+ its tool batch). A live child that had already decided to stop runs one more
568
+ turn to read it, so an uncancelled child consumes it. The reply reports the
569
+ measured delay from acceptance to the child's next request, and marks a
570
+ message as `missed` — never as delivered — when the child is cancelled,
571
+ disposed, or finishes before another boundary. Worst case measured on a real
572
+ `dsh@0.2.2-rc.1` host: **6978 ms** with an 8 s child step and **2986 ms** with
573
+ a 4 s step, i.e. the bound tracks the step, not the plugin. With a host that
574
+ exposes no live channel, the tool degrades to the followup queue and says so
575
+ in the reply; it never calls that live.
576
+ - `superagent_audit(run_id?, subtask_id?, kind?, decision?, result?, target?,
577
+ since?, until?, limit?, order?, format?, out_path?)` reads the audit trail, or
578
+ exports the matching events as one JSONL or CSV file. See
579
+ [Permissions and audit](#permissions-and-audit).
580
+
346
581
 
347
582
  ## Progress, decisions, and artifacts
348
583
 
@@ -352,15 +587,110 @@ cost: at least ¥0.0041 (estimate; no price for haoduo/gpt-6.1-sol)
352
587
  - **Attention.** A worker or the aggregator may append one fenced `attention`
353
588
  block with a question that only the user can answer. It is stripped from the
354
589
  report, stored on the run as `attention.items`, shown as `needs your decision:`
355
- in status, and leads the notification when the run finishes. The question,
356
- options, and reason are collapsed to one line and capped at 500 / 200 / 300
357
- characters, so the block cannot inject a forged status or notification line.
358
- A block that is not valid JSON or has no question is kept in the report, and
359
- status prints `attention: <reason>` instead of hiding the request.
590
+ in status, and leads the notification when the run finishes. Every item gets a
591
+ stable id (`q1`, `q2`, …) from a counter on the run, so a question means the
592
+ same thing across saves and resumes. The question, options, and reason are
593
+ collapsed to one line and capped at 500 / 200 / 300 characters, so the block
594
+ cannot inject a forged status or notification line. A block that is not valid
595
+ JSON or has no question is kept in the report, and status prints
596
+ `attention: <reason>` instead of hiding the request.
597
+ - **Answering.** `superagent_answer` records the decision on that item and lets
598
+ the run continue: an active run carries it into its next prompt, a terminal
599
+ run is reopened so the aggregation runs again with the answer. The question is
600
+ archived (not deleted) when a resume retires it, which is what lets a late
601
+ answer be refused with `expired at <time>` instead of being attached to
602
+ whatever is open now.
603
+ - **Instructions during a run.** Two boundaries, kept distinct.
604
+ `superagent_followup` appends to the dialog log and is carried by the next
605
+ prompt built for the run: each instruction records `appliedAt` /
606
+ `appliedAtStage` when a prompt first carries it, or `missedAt` when the run
607
+ settled first. `superagent_inject` instead steers a live child's inbox and is
608
+ claimed at its next pre-step; its receipt records `latencyMs` measured from
609
+ acceptance to that claim, or `missedReason` when the child left first. Status
610
+ prints both, so a queued instruction and a live one are never confused.
360
611
  - **Report file.** A terminal run writes its report to
361
612
  `<stateDir>/reports/<runId>.md` with an atomic rename, so the outcome has a
362
613
  path that can be opened or attached. The directory carries a `.gitignore` with
363
614
  `*`, and the path is recorded in `run.artifacts` and shown in status.
615
+ - **Dependencies between subtasks.** The planner may give a subtask an id and a
616
+ `dependsOn` list; the dependent then waits (`waiting`) instead of starting,
617
+ and its prompt carries the finished dependency's report. Independent subtasks
618
+ still run in parallel. An unknown reference is `skipped` with the reason, a
619
+ failure skips everything downstream rather than reporting it as done, and a
620
+ cycle rejects the plan before any subtask starts. Status and the report show
621
+ waiting separately from running.
622
+
623
+ ## Permissions and audit
624
+
625
+ Two independent layers sit around a run. A **policy** decides whether an action
626
+ may happen; an **audit trail** records what was decided and what followed. The
627
+ trail is on by default because it only observes. A policy changes nothing until
628
+ one exists, and it can only tighten what the plugin does on its own.
629
+
630
+ ### Policy
631
+
632
+ Copy [docs/policy.example.json](https://github.com/LittleChenLiya/dsh-superagent/blob/main/docs/policy.example.json) to
633
+ `<stateDir>/policy.json`, or name another file with `policyFile`. Rules are
634
+ matched in this order:
635
+
636
+ 1. a `paths.deny` / `commands.deny` pattern -> `deny` (deny always wins);
637
+ 2. an explicit `paths.allow` / `commands.allow` entry -> `allow`;
638
+ 3. the action kind listed under `confirm.actions` -> `confirm`;
639
+ 4. the run's `runs.<id>.level`, else `defaultLevel`.
640
+
641
+ An allow entry that beats a `confirm` or a per-run `deny` is recorded with
642
+ `meta.relaxedFrom`, so a person can always see where the policy was opened up.
643
+ Relative path patterns match at any directory boundary (`src/**` covers
644
+ `/anywhere/repo/src/a.js`) but not a sibling that merely ends the same way
645
+ (`xsrc/a.js`). A command entry without `*` is a prefix on whole tokens
646
+ (`git status` permits `git status --short`, not `git statusx`); a composite line
647
+ (`git status && curl ...`) can never be lifted above `confirm` by a prefix.
648
+
649
+ `policy.json` may contain `//`, `#`, and `/* */` comments. A schema problem is
650
+ reported with the file, line, and column:
651
+
652
+ ```
653
+ policy.json: 1 problem in the permission policy
654
+ policy.json:3:19 [defaultLevel] must be one of allow | confirm | deny
655
+ "defaultLevel": "maybe",
656
+ ^
657
+ ```
658
+
659
+ An unreadable or invalid policy **fails closed**: governed actions are denied and
660
+ `superagent_audit` prints the problem. A start or resume that is denied is
661
+ refused before any state changes; one held for `confirm` needs
662
+ `approve_policy: true` on the next call, and that approval is written as an
663
+ `approved` event naming the held event. An approval cannot release a `deny`.
664
+
665
+ ### Audit
666
+
667
+ `<stateDir>/audit/audit.jsonl`, one JSON object per event:
668
+
669
+ ```json
670
+ {"v":1,"id":"evt_...","at":"2026-11-15T10:04:11.238Z","runId":"20261115T100400-ab12cd34","subtaskId":"subtask-2","actor":"session:9f3c","kind":"path.write","action":"path.write","target":"C:/work/app/src/db.js","decision":"allow","result":"ok","durationMs":4,"rule":"paths.allow[0]","source":"policy","meta":{"relaxedFrom":"confirm","reason":"..."}}
671
+ ```
672
+
673
+ Every event carries the run, the subtask, the actor, a timestamp, the decision,
674
+ the result, and how long the check took. Higher layers may add `tool.call` and
675
+ `command.exec` events. Triggered by the plugin itself: `run.start`, `run.resume`,
676
+ `run.cancel`, `run.finish`, `attention`, plus `blocked` when a policy denies and
677
+ `approved` when a person releases a held action.
678
+
679
+ Appends are serialized inside the process and guarded by a `wx` lock file across
680
+ processes, and each event is written with one append, so two workers finishing at
681
+ the same moment cannot splice a line. A trailing fragment left by a crash is
682
+ reported as `torn` and skipped; a damaged line is counted as `invalid` and does
683
+ not hide the rest.
684
+
685
+ `superagent_audit` reads by run, subtask, kind, decision, result, target text, and
686
+ time window. With `format: "jsonl"` or `format: "csv"` it writes one deliverable
687
+ file (default `<stateDir>/audit/audit-export-<time>.<ext>`) and returns its path.
688
+
689
+ A path/command guard can be attached without the audit layer knowing its rules:
690
+ `createAuditor({ dir, policyFile }).attachGuard(request => ({ decision, reason }))`.
691
+ The guard may only tighten the decision the policy produced; a guard that throws
692
+ is treated as a block. A guard that answers `{ blocked, rule, reason }` — the
693
+ shape a tool-call guard already produces — is understood as well.
364
694
 
365
695
  ## Cross-run memory
366
696
 
@@ -416,6 +746,12 @@ file, and a truncated last line from a killed process is skipped. Two runs
416
746
  finishing at once cannot overwrite each other's notes; a line may land in a
417
747
  different order, and resolution is by timestamp, never by position.
418
748
 
749
+ **Search.** `superagent_memory` with `action: "search"` ranks notes by `query`
750
+ keywords and exact `tags` instead of returning the newest ones, and the planner
751
+ digest uses the same ranking against the run's goal. A relevant note from weeks
752
+ ago therefore still reaches the prompt when it matches, while unrelated notes do
753
+ not crowd out the budget. Notes can carry `tags` when set.
754
+
419
755
  **Correction.** A newer note with the same key supersedes the old one. An
420
756
  explicit `forget` writes a tombstone. Notes older than `memoryMaxAgeDays` stop
421
757
  being injected and are dropped at the next compaction. Every note is shown with
@@ -440,8 +776,9 @@ _Top of a report rendered from 40 real host runs. The full page — timeline,
440
776
  swimlanes, call and cost curves, failure annotations, run table — is
441
777
  [docs/report-sample.html](https://github.com/LittleChenLiya/dsh-superagent/blob/main/docs/report-sample.html)._
442
778
 
443
- Two operator utilities ship with the package. They read the same durable run
444
- files as the tools, need no session, and add no runtime dependency.
779
+ Five operator utilities ship with the package, need no session, and add no
780
+ runtime dependency. `watch`, `report`, `archive`, and `sync` read the same
781
+ durable run files as the tools; `doctor` inspects the install itself.
445
782
 
446
783
  Run them from the installed copy inside the profile:
447
784
 
@@ -452,16 +789,22 @@ node "$PKG/bin/report.js" --out report.html # self-contained HTML page
452
789
  ```
453
790
 
454
791
  If the profile's linker created bin links (npm does), the same commands are
455
- `node_modules/.bin/dsh-superagent-watch` and `node_modules/.bin/dsh-superagent-report`.
792
+ `node_modules/.bin/dsh-superagent-watch`, `node_modules/.bin/dsh-superagent-report`,
793
+ and `node_modules/.bin/dsh-superagent-doctor`.
456
794
 
457
- Both accept `--state-dir <path>`; it defaults to `$DSH_HOME/state/superagent`.
458
- Pass it when the plugin config sets a custom `stateDir`.
795
+ `watch`, `report`, and `archive` all accept `--state-dir <path>`; it defaults to
796
+ `$DSH_HOME/state/superagent`. Pass it when the plugin config sets a custom
797
+ `stateDir`.
459
798
 
460
799
  **`watch`** draws one line per run — id, status, calls used against the cap,
461
800
  elapsed time, what it is doing right now, and the parent session — in the
462
801
  alternate screen, and restores the cursor on Ctrl-C, SIGTERM, or a closed pipe.
463
802
  A status change repaints immediately; an idle panel reads one small file per
464
- second. `--once` prints a single plain frame, which is what
803
+ second. Runs alive at the same moment share a numbered gutter, so parallel work
804
+ is visible as a group instead of unrelated rows. A waiting row leads with the
805
+ run holding its slot, then the queue position, because a narrow cell clips from
806
+ the right and the holder is the actionable part. `--once` prints a single plain
807
+ frame, which is what
465
808
  [docs/e2e/transcripts/watch-panel.log](https://github.com/LittleChenLiya/dsh-superagent/blob/main/docs/e2e/transcripts/watch-panel.log)
466
809
  captures from 40 real runs.
467
810
 
@@ -469,16 +812,116 @@ captures from 40 real runs.
469
812
  no script, no font, no image, no network. It has a timeline with each run's
470
813
  start, end, and derived planning/work/merge phases; a swimlane chart whose lane
471
814
  count is the peak concurrency; cumulative model-call and cost curves; explicit
472
- failure, cancellation, and interruption annotations; and a run table.
815
+ failure, cancellation, and interruption annotations; and a run table. Each
816
+ worker's retry chain and its share of the run's wall clock are listed next to
817
+ its outcome, so an expensive flaky subtask is visible instead of only its final
818
+ failure.
473
819
  [docs/report-sample.html](https://github.com/LittleChenLiya/dsh-superagent/blob/main/docs/report-sample.html)
474
820
  is the 40-run report from the host e2e — open it directly, nothing is fetched —
475
821
  and
476
822
  [docs/e2e/transcripts/report-cli.log](https://github.com/LittleChenLiya/dsh-superagent/blob/main/docs/e2e/transcripts/report-cli.log)
477
823
  records the command plus a zero-external-reference audit.
478
824
 
479
- Neither utility is the install path: the plugin is installed with
825
+ **`doctor`** answers "it installed, why does nothing work?" before the host
826
+ does. It reads only: no install, no mount, no edit to the profile. One block per
827
+ check — imported files against the `files` whitelist, declared files against
828
+ what is on disk, the installed copy against the published tarball for its
829
+ version, the profile's bundle registration, and the eleven registered tools — each
830
+ failure followed by the command that fixes it.
831
+
832
+ ```bash
833
+ PKG="${DSH_HOME:-$HOME/.dsh}/profiles/web/node_modules/@xiangyixie/dsh-superagent"
834
+ node "$PKG/bin/doctor.js" --profile web
835
+ node "$PKG/bin/doctor.js" --profile web --offline # skip the registry hash check
836
+ ```
837
+
838
+ Exit code is `0` when no check fails, `1` when one does, so it can gate a
839
+ deploy. `npm test` runs the same pack guard as
840
+ [`scripts/check-pack.mjs`](scripts/check-pack.mjs): every file reachable from
841
+ the entry points must appear in `npm pack --dry-run`, which is the check the
842
+ 0.9.x release lacked.
843
+
844
+ None of these utilities is the install path: the plugin is installed with
480
845
  `dsh plugin add`, never with `npm i -g`.
481
846
 
847
+ **`archive`** is the fourth utility. It prunes terminal runs and exports or
848
+ imports one run as a self-contained archive; see [Retention](#retention) and
849
+ [Archives](#archives).
850
+ ## Syncing one state directory across machines
851
+
852
+ There is no server and no account. The state directory is a directory of files,
853
+ so a git remote can carry it: `dsh-superagent-sync` makes that directory a
854
+ repository, keeps the machine-local files out, and gives you `pull`, `push`, and
855
+ `status`. `git` is the only requirement — the command has no dependency of its
856
+ own.
857
+
858
+ ```bash
859
+ PKG="${DSH_HOME:-$HOME/.dsh}/profiles/web/node_modules/@xiangyixie/dsh-superagent"
860
+ node "$PKG/bin/sync.js" init git@github.com:me/superagent-state.git # once per machine
861
+ node "$PKG/bin/sync.js" push # after runs finish
862
+ node "$PKG/bin/sync.js" pull # before starting work
863
+ node "$PKG/bin/sync.js" status
864
+ ```
865
+
866
+ Or `node_modules/.bin/dsh-superagent-sync`. All four accept `--state-dir
867
+ <path>` (default `$DSH_HOME/state/superagent`), and `--json` prints the raw
868
+ result.
869
+
870
+ **`init <remote>`** creates the repository, writes a managed block into
871
+ `.gitignore`, sets `origin`, and makes the first commit. Re-running it refreshes
872
+ the remote URL and that block without touching entries you added yourself. A
873
+ machine with no `~/.gitconfig` gets a repository-local commit identity, so the
874
+ first commit cannot fail on that alone.
875
+
876
+ **`pull`** fetches `origin`, then merges. Uncommitted local changes are stashed
877
+ first (`stash@{0}`, subject `dsh-sync auto-stash …`) and reapplied after the
878
+ merge, so a pull never silently overwrites an edit. A conflict stops the merge
879
+ with both sides still in the files: the paths are printed, nothing is chosen,
880
+ and the stash is left unapplied with a line saying so.
881
+
882
+ **`push`** commits everything and pushes the current branch, setting its
883
+ upstream on the first push. A rejected push is reported, not forced and not
884
+ auto-merged: run `pull`, resolve what it reports, then push again.
885
+
886
+ **`status`** prints ahead/behind counts, uncommitted files, stashes, and the
887
+ conflicted paths waiting for a decision.
888
+
889
+ ### What never leaves the machine
890
+
891
+ `.owner`, `control.json` (a bearer token), `notifications.json`, `*.lock`,
892
+ `*.cancel`, `*.corrupt-*`, `*.tmp`, `*.log`, and `.env` / key material. The
893
+ notebook is the one exception worth knowing: `memory/.gitignore` normally holds
894
+ a bare `*`, which would keep every note local, so `init` rewrites that one
895
+ default to allow `<scope>.jsonl`. A file you customized is left alone.
896
+
897
+ ### When it conflicts
898
+
899
+ Run records are one file per run (`runs/<runId>.json`), so ordinary concurrent
900
+ work on two machines — different runs — never touches the same path. A conflict
901
+ needs one of these:
902
+
903
+ - the same run id written on both machines: a resume or cancel on the second
904
+ machine before pulling the first machine's state;
905
+ - the same memory scope appended to on both machines (`memory/<scope>.jsonl` is
906
+ append-only, and two different tails collide);
907
+ - the same `reports/<runId>.md` regenerated with different content;
908
+ - `.gitignore` edited by hand on both machines.
909
+
910
+ While a run file still contains conflict markers it is not valid JSON, and the
911
+ plugin quarantines it at mount as `<runId>.json.corrupt-<ts>`. Resolve it before
912
+ starting the host: keep the side you want, `git add` it, `git commit`.
913
+
914
+ ### Why this is approximate
915
+
916
+ - Two machines writing at the same moment can conflict. The merge stops and you
917
+ decide; nothing is merged behind your back.
918
+ - There is no live sync and no cross-machine lock. A machine sees another
919
+ machine's run only after `pull`, and `push` does not know what the other
920
+ machine is doing right now. Run one host per state directory at a time.
921
+ - Keys are not distributed: each machine still needs its own model credential.
922
+ - `keepRuns` pruning deletes files, and a deletion reaches the other machine
923
+ only on the next `pull`.
924
+
482
925
  ## Embedding over local HTTP
483
926
 
484
927
  The tools require a session. If another UI or script must start and watch runs
@@ -511,12 +954,52 @@ The full contract — routes, error ids, security model, lifecycle, client
511
954
  examples — is [docs/embedding.md](https://github.com/LittleChenLiya/dsh-superagent/blob/main/docs/embedding.md). It is opt-in, loopback
512
955
  only, and there is no remote or unauthenticated mode.
513
956
 
957
+ ## Workspace panel
958
+
959
+ `workbenchPort` adds a local, IDE-shaped panel over one directory. It has its
960
+ own file tree, editor, diff preview, and run change view; nothing is proxied
961
+ through the host.
962
+
963
+ ```bash
964
+ npx dsh-superagent-workbench --root /path/to/project --port 8787
965
+ ```
966
+
967
+ The same server can run inside the host, with its Runs view wired to the plugin
968
+ state directory:
969
+ - id: superagent
970
+ config:
971
+ workbenchPort: 0 # off by default; 0 = OS picks a free loopback port
972
+ workbenchRoot: /path/to/project
973
+ ```
974
+
975
+ The standalone command serves the same page and defaults its run state to
976
+ `<root>/.dsh-workbench`; pass `--state-dir <plugin state directory>` to read
977
+ existing runs. Neither form opens a socket unless you ask for it.
978
+
979
+ The bound URL and a fresh per-process token are written to
980
+ `<stateDir>/workbench.json` (mode `0600`). Open `http://127.0.0.1:<port>/?token=<token>`
981
+ once; the page keeps the token in `sessionStorage` and strips it from the
982
+ address bar. Without the token every route answers `401`.
983
+
984
+ The panel can list, read, and edit regular text files under `workbenchRoot`. It
985
+ refuses absolute paths, `..` traversal, symlinks that leave the root, the plugin
986
+ state directory, binary files, and files above 512 KB. Saving sends the hash and
987
+ mtime the editor read; if either changed on disk, the save is refused with
988
+ `external-change` instead of overwriting another process's work. Before a save
989
+ is confirmed the page shows a unified diff.
990
+
991
+ When `workbenchPort` is on, the plugin records the files each run changed into
992
+ that run's JSON record (`run.changes`), so the Runs view can show those files and
993
+ their diff against `git HEAD` later.
994
+
514
995
  ## State and recovery
515
996
 
516
997
  One file per run: `$DSH_HOME/state/superagent/runs/<runId>.json`, written with a
517
998
  temp file plus rename, so a kill during a save cannot leave a half-written run.
518
999
  Statuses: `queued`, `planning`, `running`, `aggregating`, `completed`,
519
- `partial`, `failed`, `cancelled`, `interrupted`.
1000
+ `partial`, `failed`, `cancelled`, `interrupted`. A run that is waiting for a free
1001
+ slot also has `queued` as its status but carries `queue.waiting: true` with its
1002
+ position in line; it is not active and does not count against `maxActiveRuns`.
520
1003
 
521
1004
  At mount the plugin marks a run as `interrupted` **only when it has no live
522
1005
  owner** (see below) and resets its in-flight subtasks to `pending`.
@@ -545,6 +1028,7 @@ Three side files live next to the run:
545
1028
  | `<runId>.cancel` | A cancel was requested by some process. The owner polls it once per second and stops its children. Removed when the run ends. |
546
1029
  | `<runId>.lock` | The process that is allowed to schedule this run. Created with `wx`, so exactly one process wins. A lock left by a dead local pid is broken immediately; a live local pid keeps it however long it has held it; a lock from another machine is broken once it is older than 10 minutes, since its pid cannot be checked. |
547
1030
  | `<runId>.json.corrupt-<ts>` | The state file was not valid JSON and was moved aside, not deleted. The run is skipped by `superagent_list` and reported by id with this path. |
1031
+ | `workspaces/<runId>/w<n>/` | A worker's git worktree when `workspaceIsolation` is on. Removed once its branch is merged or it produced no change; kept when a conflict left it for the user to merge. |
548
1032
 
549
1033
  If a run's file is damaged, nothing else breaks: other runs list normally, and
550
1034
  starting a new run works. Inspect the `.corrupt-` file, then delete it. A file
@@ -629,6 +1113,49 @@ removed ids are logged, and the matching `reports/<runId>.md` artifact is
629
1113
  removed with its run. `superagent_list` prints the current file count and size,
630
1114
  so growth is visible before it becomes a problem.
631
1115
 
1116
+ To clean up on demand, `dsh-superagent-archive prune` plans first and deletes
1117
+ second:
1118
+
1119
+ ```bash
1120
+ node "$PKG/bin/archive.js" prune --older-than 30 # dry run
1121
+ node "$PKG/bin/archive.js" prune --older-than 30 --status failed # dry run, one status
1122
+ node "$PKG/bin/archive.js" prune --older-than 30 --confirm # delete
1123
+ ```
1124
+
1125
+ The plan prints each run id, status, finish time, and the bytes it holds; the
1126
+ summary gives the run, file, and byte totals. Without `--confirm` nothing is
1127
+ deleted. Only terminal runs (`completed`, `partial`, `failed`, `cancelled`,
1128
+ `interrupted`) are ever candidates: a run that is still active, or whose
1129
+ `.lock` is held by another process, is listed as skipped and left alone. A run
1130
+ inside the window, a run with no parsable timestamp, and a quarantined
1131
+ `*.corrupt-*` file are kept as well.
1132
+
1133
+ ## Archives
1134
+
1135
+ `archive export` turns one run into evidence another person can open offline —
1136
+ no host, no plugin, no network:
1137
+
1138
+ ```bash
1139
+ node "$PKG/bin/archive.js" export <run-id> --out ./run-archive # directory
1140
+ node "$PKG/bin/archive.js" export <run-id> --out ./run.html --format html # one page
1141
+ node "$PKG/bin/archive.js" export <run-id> --out ./run.json --format bundle
1142
+ ```
1143
+
1144
+ The directory contains `README.md` (summary, the merged report, a subtask
1145
+ table, and a file index), `report.md` (the report as markdown), `run.json` (the
1146
+ full durable record), `subtasks/` (one markdown page and one JSON file per
1147
+ subtask), `guards.json` / `guards.md` (every decision a worker or the
1148
+ aggregator stopped on), `usage.json` (token totals per child plus the cost the
1149
+ operator prices produce), and `manifest.json` (archive metadata, sizes, and a
1150
+ SHA-256 per file). `--format html` writes the same content as one self-contained
1151
+ page with the bundle embedded; `--format bundle` writes only that JSON.
1152
+
1153
+ `archive import <path>` reads any of the three back into the local store for
1154
+ review, restoring the run record and its report artifact. It never overwrites:
1155
+ when a local run has the same id, the command fails before writing anything and
1156
+ says so. An imported run is terminal, so it is listed and readable but never
1157
+ resumed.
1158
+
632
1159
  ## Cancelling from another process
633
1160
 
634
1161
  `superagent_cancel` works even when the run was started by a different host
@@ -659,14 +1186,14 @@ appears to "hang" until the ignored-abort child returns.
659
1186
 
660
1187
  | What you see | What it means | What to do |
661
1188
  | --- | --- | --- |
662
- | `superagent_*` tools do not exist | The bundle row is not mounted, or the host refused to load the plugin. | Run `--dump-config` and check for the `@xiangyixie/dsh-superagent` block; reinstall with `dsh plugin --profile <p> add @xiangyixie/dsh-superagent@0.10.0` and read the host log for `[dsh-superagent]` lines. |
663
- | `Cannot find module .../lib/control.js` (or `watch.js` / `report.js`) and the plugin never activates | The copy in that profile is incomplete — an `add` that was interrupted leaves a partial extraction. The published package is not the cause: every version ships all eleven `lib/` files. | Delete the plugin's directory under the profile's `node_modules` (scoped `@xiangyixie/dsh-superagent`, or unscoped `dsh-superagent` from an older tarball install) and run the same `add` command again, with the version number. Do not copy files in by hand. |
1189
+ | `superagent_*` tools do not exist | The bundle row is not mounted, or the host refused to load the plugin. | Run `--dump-config` and check for the `@xiangyixie/dsh-superagent` block; reinstall with `dsh plugin --profile <p> add @xiangyixie/dsh-superagent@0.12.0` and read the host log for `[dsh-superagent]` lines. |
1190
+ | `Cannot find module .../lib/control.js` (or `watch.js` / `report.js`) and the plugin never activates | The copy in that profile is incomplete — an `add` that was interrupted leaves a partial extraction. The published package is not the cause: every version ships all twenty-two `lib/` files. | Delete the plugin's directory under the profile's `node_modules` (scoped `@xiangyixie/dsh-superagent`, or unscoped `dsh-superagent` from an older tarball install) and run the same `add` command again, with the version number. Do not copy files in by hand. |
664
1191
  | `[error] the model provider rejected the API key` | The key env var is missing in the process that started the host. | Export `DEEPSEEK_API_KEY` (the default route) or the variable your route names, then restart `dsh`. |
665
1192
  | `MISSING_CREDENTIAL ... no API key for provider route "..."` | The profile's route has no credential in the environment. | Set the env var named for that route and restart. The error line names the route, so use that, not this page. |
666
1193
  | `[error] the subagent service is unavailable` | The profile has no `subagents` service, so the plugin has nothing to spawn. | Use a profile built on the base bundle (`web` or `headless` from the stock image), or add the subagent plugin to the profile. |
667
1194
  | `error: subagent provider "..." cannot enforce maxSubagentDepth` | The route's subagent backend cannot cap delegation. | Keep `provider: spawn`, or set `maxSubagentDepth: provider-managed` if you accept the backend's own limit. |
668
1195
  | `error: the Windows file sandbox could not start a child process` | Host sandbox launcher failure (`windows-acl-run: ...`), not your goal or key. The subtask is retried once. | Retry the run; if it repeats, restart the host, or disable the Windows ACL sandbox in the profile, then run the `diagnose-windows-sandbox-acl` skill. |
669
- | `error: the run was not started because the active-run limit is already in use` | `maxActiveRuns` is full, including runs from another profile that shares the state directory. | Wait, cancel one, or raise `maxActiveRuns`. |
1196
+ | `error: the run was not started because the active-run limit is already in use` | `maxActiveRuns` is full, including runs from another profile that shares the state directory, and the start did not ask to queue (or the queue itself is full). | Retry with `queue: true`, wait, cancel one, or raise `maxActiveRuns` / `maxQueuedRuns`. |
670
1197
  | `error: the run stopped because it reached its spending cap` | `maxModelCallsPerRun` or `maxTokensPerRun` was hit. | Read the partial report; raise the cap in the config, then `superagent_resume` continues with the new limits. |
671
1198
  | `usage: not recorded` | The run finished and no child session log could be read (moved `sessions` directory, or a run created before accounting). | Nothing to fix on old runs; new runs record usage. While a run is still active the line says accounting is pending instead. |
672
1199
  | `usage note: N child session log(s) could not be read` | Part of the usage was unreadable; the token figures are a lower bound. The call budget still counted those children. | Check that `$DSH_HOME/sessions` exists and is readable by the host process. |
@@ -701,11 +1228,16 @@ A run that fails *after* it was accepted keeps its report and shows `error:`
701
1228
  subtask's text under the goal heading) and falls back to a deterministic merge
702
1229
  when the aggregator fails or the budget is exhausted.
703
1230
  - Retention is opt-in (`keepRuns`); by default state accumulates, at up to
704
- 32 KB per subtask plus the report per run.
1231
+ 32 KB per subtask plus the report per run. `archive prune` removes terminal
1232
+ runs on demand, as a dry run unless `--confirm` is given.
705
1233
  - The HTTP embedding surface is loopback-only, opt-in, and token-authenticated;
706
1234
  it cannot be exposed remotely, and there is no MCP server. A local process
707
1235
  running as the same user can read the token, which is the same trust boundary
708
1236
  as writing run files.
1237
+ - Cross-machine sync is a git repository, not a service: it is offline-first,
1238
+ conflict-stop rather than conflict-free, has no realtime channel, and does
1239
+ not move credentials between machines. Two hosts actively writing one state
1240
+ directory on two machines still need a `pull` between them.
709
1241
 
710
1242
  ## Naming
711
1243