@oisin-ee/pi-dogsled 0.26.1 → 0.28.1

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.
Files changed (44) hide show
  1. package/README.md +138 -29
  2. package/package.json +18 -7
  3. package/pi/board.ts +17 -10
  4. package/pi/index.ts +33 -5
  5. package/pi/interview.ts +112 -141
  6. package/pi/plan-mode.ts +7 -7
  7. package/pi/todo/CHANGELOG.md +133 -0
  8. package/pi/todo/README.md +133 -0
  9. package/pi/todo/src/contract-fixture.ts +103 -0
  10. package/pi/todo/src/display.ts +78 -0
  11. package/pi/todo/src/embedded.ts +105 -0
  12. package/pi/todo/src/gate.ts +89 -0
  13. package/pi/todo/src/generated/todo_core.d.ts +573 -0
  14. package/pi/todo/src/generated/todo_core.js +970 -0
  15. package/pi/todo/src/generated/todo_core_bg.wasm +0 -0
  16. package/pi/todo/src/generated/todo_core_bg.wasm.d.ts +22 -0
  17. package/pi/todo/src/guidance.ts +16 -0
  18. package/pi/todo/src/handoff.ts +91 -0
  19. package/pi/todo/src/import-fixture.ts +63 -0
  20. package/pi/todo/src/index.ts +100 -0
  21. package/pi/todo/src/lease-fixture.ts +95 -0
  22. package/pi/todo/src/lifecycle.ts +105 -0
  23. package/pi/todo/src/plan-approved.ts +78 -0
  24. package/pi/todo/src/presentation.ts +70 -0
  25. package/pi/todo/src/provider-fixture.ts +50 -0
  26. package/pi/todo/src/provider.ts +289 -0
  27. package/pi/todo/src/registration-fixture.ts +126 -0
  28. package/pi/todo/src/reminder.ts +30 -0
  29. package/pi/todo/src/repository.ts +31 -0
  30. package/pi/todo/src/runtime-fixture.ts +255 -0
  31. package/pi/todo/src/schema.ts +99 -0
  32. package/pi/todo/src/source.ts +51 -0
  33. package/pi/todo/src/state.ts +105 -0
  34. package/pi/todo/src/tool.ts +60 -0
  35. package/pi/todo/src/wasm.ts +64 -0
  36. package/pi/todo/src/widget.ts +77 -0
  37. package/pi/todo/src/work.ts +180 -0
  38. package/pi/unit-bridge.ts +29 -16
  39. package/pi/unit-protocol.ts +35 -16
  40. package/pi/unit-worker.ts +7 -11
  41. package/pi/work-panel.ts +9 -8
  42. package/pi/work-todo.ts +30 -88
  43. package/plugins/dogsled/skills/dogsled/SKILL.md +2 -2
  44. package/plugins/dogsled/skills/dogsled/references/review.md +2 -3
package/README.md CHANGED
@@ -13,13 +13,13 @@ Install the binary on each Herdr host. Use the same release tag in each command.
13
13
  Binary:
14
14
 
15
15
  ```sh
16
- mise use github:oisin-ee/dogsled@v0.26.1
16
+ mise use github:oisin-ee/dogsled@v0.28.0
17
17
  ```
18
18
 
19
- Pi (extension, tools, and skill), from npm or as part of `@oisin-ee/oisinpi`:
19
+ Pi (extension, tools, the `todo` tool, and skill), from npm:
20
20
 
21
21
  ```sh
22
- pi install npm:@oisin-ee/pi-dogsled@0.26.1
22
+ pi install npm:@oisin-ee/pi-dogsled@0.28.1
23
23
  ```
24
24
 
25
25
  At session start the extension compares its version with `dogsled --version` and warns when they differ.
@@ -27,14 +27,14 @@ At session start the extension compares its version with `dogsled --version` and
27
27
  Claude Code (hooks, tools, and skill):
28
28
 
29
29
  ```sh
30
- claude plugin marketplace add oisin-ee/dogsled#v0.26.1
30
+ claude plugin marketplace add oisin-ee/dogsled#v0.28.0
31
31
  claude plugin install dogsled@dogsled
32
32
  ```
33
33
 
34
34
  Codex (hooks, tools, and skill):
35
35
 
36
36
  ```sh
37
- codex plugin marketplace add oisin-ee/dogsled --ref v0.26.1
37
+ codex plugin marketplace add oisin-ee/dogsled --ref v0.28.0
38
38
  codex plugin add dogsled@dogsled
39
39
  ```
40
40
 
@@ -44,7 +44,7 @@ The [Codex CLI reference](https://developers.openai.com/codex/cli/reference#code
44
44
  Herdr (left-docked work board):
45
45
 
46
46
  ```sh
47
- herdr plugin install oisin-ee/dogsled --ref v0.26.1 --yes
47
+ herdr plugin install oisin-ee/dogsled --ref v0.28.0 --yes
48
48
  ```
49
49
 
50
50
  The Claude and Codex plugins use the binary on `PATH`. The Herdr plugin's build step (`plugin/fetch.sh`) installs its own binary at `bin/dogsled`: the release archive for the manifest version, checked against its published SHA-256. When that release has no archive for the platform, it runs `cargo build --release --locked` instead, which needs Rust at the crate's `rust-version` or newer. A checksum mismatch stops the install. `DOGSLED_RELEASES` replaces the download base, such as a mirror. `herdr plugin link` skips build steps, so run `sh plugin/fetch.sh` in a linked checkout. No plugin starts host services.
@@ -79,6 +79,7 @@ dogsled status --watch # refresh until interrupted
79
79
  dogsled place --json # reserve the host with the most headroom
80
80
  dogsled place --host netcup --json # pin by host id or label
81
81
  dogsled place --branch feat/unit-a --base main --repo /path/to/repo --json
82
+ dogsled place --resume REQUEST_ID --json # replay the original placement request
82
83
  ```
83
84
 
84
85
  Exit codes: 0 success, 1 queued without waiting, 2 error. Job waits return the job's exit code.
@@ -132,7 +133,9 @@ Setup includes worktree creation and removal, `setup` and `teardown` commands, r
132
133
  A non-waiting action reports the operation that exceeded its deadline.
133
134
  `logs --follow` can continue indefinitely, but each remote read has a 30-second limit.
134
135
  Run long waits through the harness's background-task facility.
135
- A wait deadline does not cancel its job or ticket. `cancel` only cancels pending tickets.
136
+ A wait deadline does not cancel its job or ticket.
137
+ `cancel` records intent under the admission lock. After admission, it returns `too_late` with the saved result.
138
+ Cancellation never stops a process. An unreachable host leaves preparation release pending.
136
139
 
137
140
  ### Agents and profiles
138
141
 
@@ -145,7 +148,14 @@ Herdr refuses a start before it types into the pane, for example `agent_pane_bus
145
148
  `--profile NAME` (Pi only) reads `~/.config/dogsled/profiles/NAME/profile.json` on the host that runs the child:
146
149
 
147
150
  ```json
148
- {"description": "Ordinary units", "model": "alias/sol", "thinking": "medium", "prompt": "prompt.md", "role": "writer", "pi_args": []}
151
+ {
152
+ "description": "Ordinary units",
153
+ "model": "alias/sol",
154
+ "thinking": "medium",
155
+ "prompt": "prompt.md",
156
+ "role": "writer",
157
+ "pi_args": []
158
+ }
149
159
  ```
150
160
 
151
161
  The child gets `--model`, `--thinking`, `--append-system-prompt <prompt>`, then `pi_args`. Unknown keys are ignored, so Shepherdr profiles load as they are.
@@ -168,43 +178,129 @@ Marks in `done.json` use the launch/item id, pane, and `agent_session.value`, no
168
178
 
169
179
  New inbox work accepted during that same working turn cancels its mark. After that turn ends, the mark is terminal. Senders receive `<name> finished; start a new child for more work`.
170
180
 
171
- A child without its own `done` stays open, including a child that asks a question or orchestrates other children. Automatic closure never closes the caller or a busy pane. Shared worktrees remain, and only the finished child pane closes. A last primary pane stays while closing it would close linked workspaces.
172
-
173
- Closed children retain TO LAND rows: `<child>: branch <b> +N to land`. These rows come from durable items and branch observations, not live panes. Integration or branch deletion removes the row.
174
-
175
- `dogsled board` groups an owner's children, jobs, and queued tickets by what the owner must do: TO LAND, ATTENTION, RUNNING, and WAITING. Each agent row names the harness and model; each job row names its command. `--json` is what the Pi widget draws.
181
+ End each turn with native `done`, `ask`, or `blocked`, or wait for owned child work.
182
+ `ask` sends a question to the owner. `blocked` records an external blocker. Neither completes the task.
183
+ Dogsled derives `waiting` from open items and pending or admitting child tickets. There is no `waiting` command.
184
+ Identical same-turn signals replay successfully. Conflicting signals refuse without a change.
185
+ The next positively identified turn clears a visible question or blocker, but not its pending delivery.
186
+
187
+ Dogsled derives one agent state: `queued`, `starting`, `working`, `waiting`, `asking`, `blocked`, `finishing`, `done`, `stopped`, `lost`, or `unknown`.
188
+ Herdr `done` means that a turn ended, not that the task completed.
189
+ An accepted native `done` remains `finishing` until the required final handoff evidence exists.
190
+
191
+ A stopped child receives a recorded prompt to signal or wait for its children.
192
+ With a live owner, it remains under NEEDS YOU.
193
+ If its custodian is gone, the sweep records the last reply and can close a positively identified stopped orphan.
194
+ A unit-bound orphan receives resource-only closure. Its task binding remains unresolved.
195
+ Owner close and stopped-orphan close save supported uncommitted work in pinned recovery snapshots before checkout removal.
196
+ Unsupported content or an incomplete preservation keeps the checkout.
197
+ Automatic closure never closes the caller or a busy pane. Shared checkouts remain while other work uses them.
198
+
199
+ Closed children with retained branches appear under READY TO MERGE.
200
+ These rows describe results, not agent states. A missing branch does not prove a merge.
201
+
202
+ `dogsled board` groups work under NEEDS YOU, READY TO MERGE, WORKING, and QUEUED.
203
+ Each agent row names the harness and model. Each job row names its command.
204
+ `--json` supplies the Pi widget.
205
+ See [Agent lifecycle and recovery](docs/lifecycle.md) for the state signals and safety rules.
176
206
  `dogsled read TARGET [--host H]` shows a child's or job's newest output and the captured final reply.
177
207
 
178
208
  ```sh
179
209
  dogsled close w2:p1
180
210
  dogsled close w9:p1 --host netcup --json
181
211
  dogsled drop <item-id> --host netcup
182
- dogsled done # as a child: my whole task is complete
212
+ dogsled done # CLI completion signal; managed agents use the native tool
213
+ dogsled ask "Which API owns this operation?"
214
+ dogsled blocked "The required host is unavailable."
183
215
  ```
184
216
 
185
217
  `drop` deletes a closed child's retained local and origin branches, including unmerged commits. Only the item's owner can use it, except on an orphan: when the origin's evidence proves the owner pane is gone or its session ended, any session can drop it. It refuses a branch checked out in a worktree. Already absent branches count as success. The item and its done mark stay settled and leave the board.
186
218
 
219
+ ### Claim custody and accept a result
220
+
221
+ ```sh
222
+ dogsled claim <item-id> --revision 0 --json
223
+ dogsled accept <item-id> --result <result-id> --evidence "Reviewed the exact returned result" --json
224
+ ```
225
+
226
+ `claim` takes custody of an orphaned child recorded on this host. Dogsled uses the caller's live pane and harness session. The original owner, task, reply, and result do not change. `--revision` names the expected custody revision. Without it, Dogsled reads the current revision before the atomic claim. A repeated claim by the current custodian returns `held` without another transfer.
227
+
228
+ A claim refuses a wrong host, a live custodian, an unproven orphan, a stale revision, or custody that moved during the claim. Refusals include a typed reason.
229
+
230
+ `accept` records the custodian's review of the exact saved result from a unit request. The caller must hold a custody claim. The receipt names the claim, revision, execution, result, reviewer, and review evidence. The original task stays open. Acceptance does not prove original task completion. An identical acceptance returns the same review without another write. A different review for the same claim is refused.
231
+
232
+ Both commands support `--json`. MCP exposes `claim` and `accept`, named `mcp__dogsled__claim` and `mcp__dogsled__accept` in Pi. Pi stores successful receipts with the custom type `dogsled.custody.v1`. These entries are audit receipts only. They do not call todo or its provider, and they do not change task state.
233
+
187
234
  `close` ends a child now, for an owner who does not want to wait for the sweep. `--host` defaults to the host of the pane's open item, else local.
188
235
 
189
236
  For an interrupted launch with no final receipt, explicit `close` can retire its exact idle shell under the request and pane locks. This closes **only the pane**, retaining the checkout, preparation holds, and unknown launch evidence. It does not report that the task never started. Competing launch records, a changed terminal, any agent, or incomplete foreground evidence refuse recovery. Automatic cleanup never uses this recovery path; normal cleanup can assess the retained checkout after its holds are resolved.
190
237
  In an agent worktree (locked `agent:worktree`, as dogsled makes them), it runs the repository's `teardown` commands in the worktree (see [Repository configuration](#repository-configuration)).
191
238
  Then it closes every pane that uses the worktree and the Herdr workspace that shows it, unlocks the worktree, and runs `git worktree remove` without force.
192
- Close uses the same loss rule as cleanup: no unique checkout content and every commit held by the default branch or freshly fetched remote refs. It deletes the branch under that same rule. Local-only work refuses close, including an explicit owner close.
239
+ Normal handoff and cleanup require no unique checkout content and every commit held by the default branch or freshly fetched remote refs.
240
+ Explicit owner close and stopped-orphan close can save supported dirty content and local-only commits in pinned recovery snapshots.
241
+ They report `saved (recovery <id>)` and retain unmerged branches for integration or explicit drop.
242
+ These resource results do not settle the original task.
193
243
  When `place` opened the main checkout's workspace as the anchor and no linked worktree is open in Herdr any more, close closes that anchor too. It does so only while the anchor is unfocused, is not the caller's, and has one pane with no agent.
194
244
  A pane outside a worktree, or in an unlocked worktree (someone's own checkout), is closed alone; the checkout stays.
195
245
  A pane in a checkout that another agent, an open item, or a busy pane still uses is closed alone too, even by an explicit close: close never closes agents it was not asked to close, and never removes a checkout they use. The last pane in the checkout takes the checkout with it.
196
- A child tab in the caller's own workspace is closed. Close refuses a missing pane, the caller's own pane, a worktree the caller works in or whose workspace is the caller's, a worktree outside the repository's worktree directory, a dirty or detached worktree, and any other lock.
246
+ A child tab in the caller's own workspace closes.
247
+ Close refuses the caller's pane, checkout, or workspace, a checkout outside the configured worktree directory, unsaved content, and foreign locks.
248
+ A clean detached checkout can close when the default branch or freshly fetched remote refs protect its HEAD.
249
+ Dogsled does not create a branch implicitly for a detached checkout.
250
+ The repository lifecycle lock protects the final identity decision through record reconciliation.
251
+ A replacement checkout at the same path stays. Verified prior removal permits record reconciliation.
197
252
  It also refuses a busy target or a busy pane that uses the worktree: an agent that is not `idle` or `done`, or a shell with a foreground command.
198
- Each refusal happens before a change. If a `teardown` command fails, the worktree, its panes, its lock, and the item stay, and the error shows the command's last lines of output.
253
+ Preservation saves initial content before teardown and saves changed content again after successful teardown.
254
+ It verifies the pinned snapshot before normalization and unforced removal.
255
+ A failed or unknown teardown keeps the checkout, its panes, its lock, and the item.
256
+ Dogsled does not automatically repeat an entered teardown with an unknown outcome.
257
+ An interrupted normalization also keeps the checkout for inspection.
199
258
  After removal, close drops the worktree's registration, as prune does.
200
- The JSON result is `{pane,worktree:{path,branch,workspace,branch_deleted,anchor_closed?}|null,pane_closed}`. A remote host runs the same steps over SSH.
259
+ The JSON result includes `pane`, `worktree`, and `pane_closed`, with optional `retained_branch` and `recovery` metadata.
260
+ A remote host uses the same operations over SSH.
201
261
 
202
262
  The service admits tickets in FIFO order using the same placement policy.
203
263
  The order holds per host. A ticket waits only behind earlier tickets that could take one of its hosts. A full host does not hold back a ticket that is pinned to another host with room.
204
264
  It records an admission error rather than silently choosing another host after a clone, prepare, or launch failure.
205
265
  A service interruption during admission leaves an explicit failed ticket for inspection, not an automatic duplicate launch.
206
266
  For non-waiting callers, admission tells the owner through its inbox. An owner without an inbox reader hears once it has one; nothing is typed into its terminal.
207
- `status` lists open items per owner and pending tickets. `--brief` includes their counts. Prompt context adds the caller's own `To land:` line.
267
+ `status` lists open items per owner and pending tickets. `--brief` includes their counts.
268
+ Prompt context includes the caller's retained branches under `Ready to merge:`.
269
+
270
+ ### Recovery and preparation holds
271
+
272
+ ```sh
273
+ dogsled recovery list --repo /path/to/repo
274
+ dogsled recovery show RECOVERY_ID --repo /path/to/repo
275
+ dogsled recovery restore RECOVERY_ID --repo /path/to/repo --to /path/to/new-checkout --branch recovered/work
276
+ dogsled retire-preparation REQUEST_ID --host HOST --reason "Historical claim no longer has an owner."
277
+ ```
278
+
279
+ Recovery refs stay local and do not expire.
280
+ Restore creates an independent checkout. It does not resume the original task, preparation, grant, or pane.
281
+ There is no separate snapshot-creation command.
282
+ Owner close and stopped-orphan close create snapshots through durable preservation operations.
283
+ Failed or unsupported preservation keeps the live checkout and reports its blocker.
284
+
285
+ Preparation dispositions validate the exact claim, persist a startup fence, then release only that claim.
286
+ Placement retains its host grant and saves its result before release.
287
+ `place --resume REQUEST_ID` replays the original journal without another grant, completed setup, or pane.
288
+
289
+ `retire-preparation` prohibits future dispatch for one historical request claim. It does not remove a checkout or settle a task.
290
+ After acknowledgement, it reports unknown execution outcome and released ownership. Claims without request IDs are unsupported.
291
+ The separately authorized `--cleanup` override is CLI-only. MCP does not expose it.
292
+
293
+ Preparation, placement, agent dispatch, and jobs retain one immutable request creation time.
294
+ Missing, changed, unsupported, expired, or excessive future-dated validity refuses new execution.
295
+ A refusal does not release an unresolved preparation claim.
296
+ Owner-local completion times are write-once and require terminal evidence, not startup confirmation.
297
+
298
+ `status`, the board, and MCP show each retained resource, its owner, its reason, and an exact next command.
299
+ JSON also supplies `command_host` and `command_argv`.
300
+ Validity refusals, completion-time gaps, preservation blockers, and undelivered child events remain visible.
301
+ These reports do not change release decisions.
302
+
303
+ See [Agent lifecycle and recovery](docs/lifecycle.md) for command limits, custody, origin release certificates, and migration.
208
304
 
209
305
  ## Inbox
210
306
 
@@ -349,7 +445,9 @@ A local branch with no worktree is removable when it is integrated or every comm
349
445
  Prune and the sweep share the same holds: active panes or processes, the caller, an unreadable process table, and pending preparations or launches.
350
446
  An unfinished launch holds its checkout before pane allocation completes, or while its attempted start has the matching agent. An empty shell from a final launch holds nothing.
351
447
  An open agent item holds its checkout in prune and the sweep; `close` ends it and keeps the reply. Within `close`, a live owner holds the checkout until the default branch holds its work.
352
- An idle or done agent that has not called `dogsled done` holds its checkout in prune, the sweep, and an automatic close; only an explicit `dogsled close` takes it. An idle shell, a done agent without an open item, and a workspace alone are not holds. The processes of an idle agent pane are not holds, but a background job that a shell started is. Foreign locks still prevent removal.
448
+ An agent without native `done` normally holds its checkout.
449
+ The sweep can close a clean stopped orphan after it proves that the custodian is gone.
450
+ Explicit `dogsled close` still requires the safety and loss checks. An idle shell, a done agent without an open item, and a workspace alone are not holds. The processes of an idle agent pane are not holds, but a background job that a shell started is. Foreign locks still prevent removal.
353
451
  A dirty checkout whose commits are in the default branch gets a `landed_dirty` finding when no hold applies.
354
452
  The finding includes the repository, checkout, branch or HEAD, dirty-path count, and up to ten paths. It is never removable.
355
453
  Before it reads checkout changes, the loss rule requires the checkout's own `.git` and a matching Git top-level path.
@@ -366,7 +464,15 @@ A shell without a Dogsled record closes after 15 minutes continuously at an empt
366
464
  A pane is an empty prompt only when its root process is a shell that waits there. A shell that runs a command, such as `sh -c "..."`, a shell that runs a script, and a shell with an unknown option all keep the pane. A report names the program of a running command, never its arguments.
367
465
  An agent pane still needs more than 24 hours continuously idle or done and a `done` mark. An agent with open children stays open.
368
466
  A workspace whose every pane is idle is one `workspaces` entry, and prune closes it whole. The caller's workspace stays, and so does a workspace that a worktree removal closes.
369
- Ended jobs expire after 24 hours, together with their logs. Disk usage above 90% lists the largest known dogsled-owned paths.
467
+ The service timer removes job output after more than 24 hours from `ended_ms`. The remaining log marker says `output expired`.
468
+ It removes conclusively terminal Job records and the remaining log marker after more than 30 days.
469
+ A stale owner item or unread result does not extend retention. Running, pending, and uncertain jobs stay.
470
+ Current readers report `output expired` for expired output, including deleted records with a retained job item.
471
+ Explicit `prune jobs` currently removes conclusively terminal records and output after more than 24 hours.
472
+ Alignment with the service record window remains pending.
473
+ The planned `result unavailable: expired or unknown` message is not yet released.
474
+ See [Retention](docs/lifecycle.md#retention) for the current rules and pending record expiry.
475
+ Disk usage above 90% lists the largest known Dogsled-owned paths.
370
476
  A `targets` entry is build output: a directory with a `CACHEDIR.TAG` that starts with the cache-directory signature, directly under a main checkout or a linked worktree, such as Rust's `target/`.
371
477
  It is removable when no Herdr workspace shows the checkout and no pane or process works in it. Work in a linked worktree inside the main checkout uses that worktree, not the main checkout.
372
478
  Prune removes it after it checks the tag again. A worktree that the same plan removes takes its build output with it, so that output is not listed.
@@ -385,6 +491,7 @@ Placement records repositories in `repositories.json`, independently of `worktre
385
491
  Doctor also discovers repositories from the caller, live pane directories, Herdr workspaces, and `cleanup.repositories`. It never scans the whole home directory.
386
492
  An absent remembered repository produces a removable `repositories` entry. Prune and the sweep recheck absence under the registry locks, then remove only stale records.
387
493
  Existing worktree records stay. Configured paths, discovered paths, unreadable paths, and dangling symlinks remain report-only. Doctor changes no registrations.
494
+
388
495
  ### The sweep in `serve`
389
496
 
390
497
  The sweep closes finished children (see [Items and closing](#items-and-closing)), and a job closes its own tab. That closed loop ends most work.
@@ -407,7 +514,7 @@ The report includes start and finish times, removals, failures, repository warni
407
514
  `dogsled status` and `status --json` show the latest pass. Prompt context adds one summary line when that pass has errors or warnings.
408
515
  The service also writes removals, failures, repository warnings, and holds to stderr.
409
516
  Child completion and orphan checks remain independent of requested doctor cleanup.
410
- An orphan that is dirty, unpushed, `working`, `blocked`, or on an unreachable host stays open. Status shows `orphaned:` and the reason on its item line, the brief counts it, and every check-in on the host lists it.
517
+ An orphan that is dirty, unpushed, `working`, `blocked`, or on an unreachable host stays open. `dogsled status` lists each item once as `orphaned (unclaimed)`, `orphaned (claimed)`, or `unknown`. Check-ins no longer repeat orphan notices.
411
518
  Prune also handles ended jobs and `targets`. Disk and process findings are report-only. Repository findings remain report-only except for absent remembered paths.
412
519
 
413
520
  ## Placement
@@ -576,14 +683,14 @@ The removed lead ledger and event log are not read or migrated.
576
683
  ## Prompt context and integrations
577
684
 
578
685
  `dogsled hook context --harness claude|codex|pi` leads with your own children and jobs, then shows the fleet totals from `status --brief`.
579
- The owner summary separates work to land, attention, idle, done, running, and queued work.
580
- The `To land:` line names finished children with unmerged commits or uncommitted changes.
686
+ The owner summary separates retained results, attention, active work, and queued work.
687
+ The `Ready to merge:` line names retained branches that await integration.
581
688
  Claude Code and Codex register `SessionStart` and `UserPromptSubmit` context hooks, and `UserPromptSubmit` and `Stop` inbox hooks (see [Inbox](#inbox)), in `plugins/dogsled`.
582
689
  Each registration supplies `--event`. The default context event is `UserPromptSubmit`.
583
690
  The CLI never reads stdin. Claude Code and Codex receive `hookSpecificOutput` JSON with `hookEventName` and `additionalContext`.
584
691
  Pi receives plain text through its `before_agent_start` extension. All three use the same snapshot reader and formatter.
585
692
 
586
- Before an orchestrator stops, the stop gate checks its own TO LAND children.
693
+ Before an orchestrator stops, the stop gate checks its own children with retained results or unfinished work.
587
694
  Pi calls `dogsled hook gate` from `agent_before_settle` on every completed stop, which also requests a cleanup pass. A reminder is added as a visible message that continues the run.
588
695
  Claude Code and Codex include the reminder in their existing `Stop` inbox response.
589
696
  The reminder requests a review, a commit from dirty children, integration, or an explicit blocker or deferral.
@@ -610,7 +717,7 @@ Plugin commands end with `|| true`. Pi also leaves the prompt unchanged if the b
610
717
 
611
718
  ### Tools
612
719
 
613
- `dogsled mcp` serves the dogsled commands as MCP tools over stdio: `status`, `spawn`, `run`, `send`, `inbox`, `read`, `close`, `drop`, `done`, `stop`, `cancel`, and `place`.
720
+ `dogsled mcp` serves the dogsled commands as MCP tools over stdio: `status`, `spawn`, `run`, `send`, `inbox`, `read`, `close`, `drop`, `done`, `ask`, `blocked`, `stop`, `cancel`, and `place`.
614
721
  Tools share the CLI action code. `spawn` returns a durable queued ticket, even when a host has room.
615
722
  The service owns startup confirmation outside the MCP call budget. `dogsled agent` still starts synchronously under `--max`.
616
723
  Startup errors include recent pane output in the launch record and ticket when the pane read succeeds.
@@ -659,11 +766,13 @@ All three harness packages share `plugins/dogsled/skills/dogsled/SKILL.md`. It d
659
766
 
660
767
  ## Build and development
661
768
 
769
+ The shell does not activate Proto, so a bare `moon`, `pnpm`, or `node` does not use the version that `.prototools` pins. Run a pinned tool with `proto run <tool> -- <arguments>`. Every `moon run` and `moon ci` in this README means `proto run moon -- run` and `proto run moon -- ci`. Run any other command that needs the pinned tools with `proto exec --tools-from-config -- <command>`.
770
+
662
771
  Build this branch with the repository's pinned Rust toolchain:
663
772
 
664
773
  ```sh
665
774
  cargo build --release
666
- npm ci
775
+ proto run pnpm -- install --frozen-lockfile
667
776
  ```
668
777
 
669
778
  The server embeds the Dioxus portal UI, so the web bundle must exist before the binary builds.
@@ -671,7 +780,7 @@ The server embeds the Dioxus portal UI, so the web bundle must exist before the
671
780
  Run it before a plain `cargo build`:
672
781
 
673
782
  ```sh
674
- moon run :web-build
783
+ proto run moon -- run :web-build
675
784
  cargo build --release
676
785
  ```
677
786
 
@@ -679,7 +788,7 @@ Proto and moon own the development tooling. `proto install` installs the version
679
788
 
680
789
  ```sh
681
790
  proto install
682
- moon run :fmt-check :lint :test :typecheck :test-shim
791
+ proto run moon -- run :fmt-check :lint :test :typecheck :test-shim
683
792
  ```
684
793
 
685
794
  The `lint` and `test` tasks build the web bundle first, so they work in a fresh checkout.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@oisin-ee/pi-dogsled",
3
- "version": "0.26.1",
3
+ "version": "0.28.1",
4
4
  "description": "Pi extension for dogsled: the board, the /dogsled panel, the inbox reader, and the dogsled tools. Needs the dogsled binary of the same version.",
5
5
  "type": "module",
6
6
  "license": "MIT",
@@ -12,6 +12,9 @@
12
12
  "files": [
13
13
  "pi/",
14
14
  "!pi/**/*.test.ts",
15
+ "!pi/todo/moon.yml",
16
+ "!pi/todo/tsconfig.json",
17
+ "!pi/todo/node_modules/",
15
18
  "plugins/dogsled/skills/",
16
19
  "README.md",
17
20
  "LICENSE"
@@ -31,10 +34,6 @@
31
34
  "engines": {
32
35
  "node": ">=22.19.0"
33
36
  },
34
- "scripts": {
35
- "typecheck": "tsc --noEmit -p tsconfig.json",
36
- "test": "node --test \"pi/**/*.test.ts\""
37
- },
38
37
  "pi": {
39
38
  "extensions": [
40
39
  "./pi/index.ts"
@@ -44,13 +43,25 @@
44
43
  ]
45
44
  },
46
45
  "peerDependencies": {
46
+ "@earendil-works/pi-ai": "*",
47
+ "typebox": "*",
47
48
  "@earendil-works/pi-coding-agent": "^1.3.0",
48
49
  "@earendil-works/pi-tui": "^1.3.0"
49
50
  },
50
51
  "devDependencies": {
52
+ "oxfmt": "^0.65.0",
53
+ "oxlint": "1.82.0",
54
+ "oxlint-tsgolint": "7.0.2001",
55
+ "vitest": "^5.0.1",
56
+ "@earendil-works/pi-ai": "1.3.0",
51
57
  "@earendil-works/pi-coding-agent": "1.3.0",
52
58
  "@earendil-works/pi-tui": "1.3.0",
53
59
  "@types/node": "26.6.4",
54
- "typescript": "7.0.2"
60
+ "typescript": "7.0.2",
61
+ "typebox": "1.3.27"
62
+ },
63
+ "scripts": {
64
+ "typecheck": "tsc --noEmit -p tsconfig.json",
65
+ "test": "node --test \"pi/*.test.ts\""
55
66
  }
56
- }
67
+ }
package/pi/board.ts CHANGED
@@ -20,7 +20,7 @@ export async function herdrAvailable(env: NodeJS.ProcessEnv = process.env): Prom
20
20
  export type Group = "to_land" | "attention" | "running" | "waiting";
21
21
 
22
22
  export interface Row {
23
- group: Group;
23
+ group: string;
24
24
  kind: string;
25
25
  id: string;
26
26
  name: string;
@@ -57,11 +57,16 @@ export interface Paint {
57
57
  bold(text: string): string;
58
58
  }
59
59
 
60
- const TITLES: Record<Group, string> = { to_land: "TO LAND", attention: "ATTENTION", running: "RUNNING", waiting: "WAITING" };
60
+ const TITLES: Record<Group, string> = { to_land: "READY TO MERGE", attention: "NEEDS YOU", running: "WORKING", waiting: "QUEUED" };
61
61
  /** Groups in action order: what the owner must do first comes first. */
62
62
  export const GROUPS: readonly Group[] = ["to_land", "attention", "running", "waiting"];
63
63
  const ORDER = GROUPS;
64
- const COUNTS: Record<Group, string> = { to_land: "to land", attention: "need attention", running: "running", waiting: "waiting" };
64
+ const COUNTS: Record<Group, string> = { to_land: "ready to merge", attention: "needs you", running: "working", waiting: "queued" };
65
+
66
+ /** Unknown evidence stays visible in the group that needs the owner. */
67
+ export function boardGroup(group: string): Group {
68
+ return GROUPS.find(known => known === group) ?? "attention";
69
+ }
65
70
 
66
71
  export function parseBoard(value: unknown): Board {
67
72
  const data = value as Partial<Board> | null;
@@ -84,9 +89,10 @@ export function clean(text: string): string {
84
89
  }
85
90
 
86
91
  function icon(row: Row): [string, ThemeColor] {
87
- if (row.group === "to_land") return ["●", "success"];
88
- if (row.group === "attention") return ["!", "warning"];
89
- if (row.group === "waiting") return ["⋯", "muted"];
92
+ const group = boardGroup(row.group);
93
+ if (group === "to_land") return ["●", "success"];
94
+ if (group === "attention") return ["!", "warning"];
95
+ if (group === "waiting") return ["⋯", "muted"];
90
96
  if (row.kind === "job") return ["▸", "accent"];
91
97
  return row.state === "working" ? ["◐", "accent"] : ["○", "muted"];
92
98
  }
@@ -108,7 +114,7 @@ function pad(text: string, width: number): string {
108
114
 
109
115
  /** A row whose transcript text is safe to draw. */
110
116
  export function cleanRow(row: Row): Row {
111
- return { ...row, name: clean(row.name), what: clean(row.what), host: clean(row.host), state: clean(row.state), activity: clean(row.activity || row.state) };
117
+ return { ...row, group: boardGroup(row.group), name: clean(row.name), what: clean(row.what), host: clean(row.host), state: clean(row.state), activity: clean(row.activity || row.state) };
112
118
  }
113
119
 
114
120
  /** Column widths shared by every row drawn together, so the columns line up. */
@@ -141,7 +147,7 @@ export function boardColumns(rows: Row[], width: number): Columns {
141
147
 
142
148
  /** `dogsled <counts>` on the left and one load meter per host on the right. */
143
149
  export function boardHeader(board: Board, width: number, paint: Paint): string {
144
- const counts = ORDER.map(g => [g, board.rows.filter(r => r.group === g).length] as const)
150
+ const counts = ORDER.map(g => [g, board.rows.filter(r => boardGroup(r.group) === g).length] as const)
145
151
  .filter(([, n]) => n > 0)
146
152
  .map(([g, n]) => `${n} ${COUNTS[g]}`)
147
153
  .join(" · ");
@@ -151,8 +157,9 @@ export function boardHeader(board: Board, width: number, paint: Paint): string {
151
157
  return truncateToWidth(gap >= 2 ? `${left}${" ".repeat(gap)}${meters}` : left, width);
152
158
  }
153
159
 
154
- export function groupTitle(group: Group, paint: Paint): string {
155
- return ` ${paint.fg(group === "attention" ? "warning" : "muted", TITLES[group])}`;
160
+ export function groupTitle(group: string, paint: Paint): string {
161
+ const known = boardGroup(group);
162
+ return ` ${paint.fg(known === "attention" ? "warning" : "muted", TITLES[known])}`;
156
163
  }
157
164
 
158
165
  /** One cleaned row. `prefix` is two columns wide: blank, or a selection marker. */
package/pi/index.ts CHANGED
@@ -12,6 +12,7 @@ import { WorkPanel, WorkDetail, runWorkAction, type WorkAction, type WorkCursor,
12
12
  import { registerInterview } from "./interview.ts";
13
13
  import { registerPlanMode } from "./plan-mode.ts";
14
14
  import { PortalClient } from "./portal-client.ts";
15
+ import { createTodo } from "./todo/src/index.ts";
15
16
 
16
17
  const REFRESH_MS = 10_000;
17
18
 
@@ -26,6 +27,10 @@ export function versionMismatch(output: string): string | undefined {
26
27
  }
27
28
 
28
29
  export default function dogsled(pi: ExtensionAPI) {
30
+ const todo = createTodo(pi, { seedPath: () => {
31
+ const value = pi.getFlag("todo-unit-file");
32
+ return typeof value === "string" ? value : undefined;
33
+ } });
29
34
  const binary = process.env["DOGSLED_BIN"] ?? "dogsled";
30
35
  const owner = process.env["HERDR_PANE_ID"];
31
36
  let timer: ReturnType<typeof setInterval> | undefined;
@@ -40,7 +45,7 @@ export default function dogsled(pi: ExtensionAPI) {
40
45
  command: binary,
41
46
  args: ["mcp"],
42
47
  exposure: "direct",
43
- description: "Spawn Pi, Claude, and Codex children and jobs on Herdr hosts, and message any agent through its inbox.",
48
+ description: "Use the native done, ask, and blocked tools for turn signals. End every turn with exactly one of: done (whole task complete), ask (you need an answer from your owner), blocked (you cannot continue), or waiting for your own open children. Spawn Pi, Claude, and Codex children and jobs on Herdr hosts, and message any agent through its inbox.",
44
49
  });
45
50
 
46
51
  async function exec(args: string[]) {
@@ -50,10 +55,10 @@ export default function dogsled(pi: ExtensionAPI) {
50
55
  }
51
56
 
52
57
  const inbox = new InboxReader(pi, exec);
53
- const units = new UnitBridge(pi, binary);
58
+ const units = new UnitBridge(pi, binary, todo.tasks);
54
59
  // The portal owns the interactive parts of Pi: the interview form and the plan review.
55
60
  const portal = new PortalClient();
56
- const planMode = registerPlanMode(pi, portal);
61
+ const planMode = registerPlanMode(pi, todo.approve, portal);
57
62
  const interviews = registerInterview(pi, portal);
58
63
  // One handler owns the tool call: the unit bridge first, then the plan-mode gate.
59
64
  pi.on("tool_call", async (event, ctx) => {
@@ -63,6 +68,28 @@ export default function dogsled(pi: ExtensionAPI) {
63
68
  });
64
69
  pi.on("tool_execution_end", (event, ctx) => units.ended(event.toolCallId, ctx));
65
70
 
71
+ // Custody receipts are audit facts only. They never call todo or its provider.
72
+ pi.on("tool_result", event => {
73
+ const kind = event.toolName === "mcp__dogsled__claim" ? "claim"
74
+ : event.toolName === "mcp__dogsled__accept" ? "accept" : undefined;
75
+ if (!kind || event.isError) return;
76
+ for (const block of event.content) {
77
+ if (block.type !== "text") continue;
78
+ let receipt: unknown;
79
+ try { receipt = JSON.parse(block.text); } catch { continue; }
80
+ if (!receipt || typeof receipt !== "object"
81
+ || !("kind" in receipt) || receipt.kind !== kind
82
+ || !("item" in receipt) || typeof receipt.item !== "string"
83
+ || !("revision" in receipt) || typeof receipt.revision !== "number") continue;
84
+ if (kind === "claim") {
85
+ if (!("outcome" in receipt) || !["claimed", "held"].includes(String(receipt.outcome))
86
+ || !("custodianPane" in receipt) || typeof receipt.custodianPane !== "string") continue;
87
+ } else if (!("resultId" in receipt) || typeof receipt.resultId !== "string"
88
+ || !("reviewId" in receipt) || typeof receipt.reviewId !== "string") continue;
89
+ pi.appendEntry("dogsled.custody.v1", receipt);
90
+ }
91
+ });
92
+
66
93
  pi.registerMessageRenderer<Details>(MESSAGE_TYPE, (message, { expanded, outputPad }, theme) => {
67
94
  const records = message.details?.records ?? [];
68
95
  const box = new Box(outputPad, 1, text => theme.bg("customMessageBg", text));
@@ -89,7 +116,7 @@ export default function dogsled(pi: ExtensionAPI) {
89
116
  let sideDisplay = false;
90
117
  let publicationFailure: string | undefined;
91
118
  const publisher = new TodoPublisher(owner ?? "", error => context?.ui.notify(`Todo publication failed: ${String(error)}`, "error"));
92
- const todos = new WorkTodo(pi.events, () => {
119
+ const todos = new WorkTodo(todo.work, () => {
93
120
  if (context) { publishTodos(context); draw(context); }
94
121
  }, () => {
95
122
  if (context) void openWork(context, "todos").catch(error => context?.ui.notify(String(error), "error"));
@@ -286,7 +313,8 @@ export default function dogsled(pi: ExtensionAPI) {
286
313
  units.stop();
287
314
  planMode.stop();
288
315
  planMode.stopWatching();
289
- interviews.close();
316
+ try { await interviews.close(); }
317
+ catch (error) { ctx.ui.notify(`Interview cleanup failed: ${String(error)}`, "error"); }
290
318
  workPanel?.dispose();
291
319
  generation++;
292
320
  workAbort?.abort();