@oisin-ee/pi-dogsled 0.19.0 → 0.21.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.
Files changed (2) hide show
  1. package/README.md +38 -24
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -11,13 +11,13 @@ Install the binary on each Herdr host. Use the same release tag in each command.
11
11
  Binary:
12
12
 
13
13
  ```sh
14
- mise use github:oisin-ee/dogsled@v0.19.0
14
+ mise use github:oisin-ee/dogsled@v0.21.0
15
15
  ```
16
16
 
17
17
  Pi (extension, tools, and skill), from npm or as part of `@oisin-ee/oisinpi`:
18
18
 
19
19
  ```sh
20
- pi install npm:@oisin-ee/pi-dogsled@0.19.0
20
+ pi install npm:@oisin-ee/pi-dogsled@0.21.0
21
21
  ```
22
22
 
23
23
  At session start the extension compares its version with `dogsled --version` and warns when they differ.
@@ -25,27 +25,27 @@ At session start the extension compares its version with `dogsled --version` and
25
25
  Claude Code (hooks, tools, and skill):
26
26
 
27
27
  ```sh
28
- claude plugin marketplace add oisin-ee/dogsled#v0.19.0
28
+ claude plugin marketplace add oisin-ee/dogsled#v0.21.0
29
29
  claude plugin install dogsled@dogsled
30
30
  ```
31
31
 
32
32
  Codex (hooks, tools, and skill):
33
33
 
34
34
  ```sh
35
- codex plugin marketplace add oisin-ee/dogsled --ref v0.19.0
35
+ codex plugin marketplace add oisin-ee/dogsled --ref v0.21.0
36
36
  codex plugin add dogsled@dogsled
37
37
  ```
38
38
 
39
39
  Codex requires review and trust before it runs plugin hooks. See the [Codex hooks documentation](https://developers.openai.com/codex/hooks#plugin-hooks).
40
40
  The [Codex CLI reference](https://developers.openai.com/codex/cli/reference#codex-plugin) describes plugin installation.
41
41
 
42
- Herdr (right-side work board):
42
+ Herdr (left-docked work board):
43
43
 
44
44
  ```sh
45
- herdr plugin install oisin-ee/dogsled --ref v0.19.0 --yes
45
+ herdr plugin install oisin-ee/dogsled --ref v0.21.0 --yes
46
46
  ```
47
47
 
48
- Harness plugins use the binary on `PATH`. They do not install it or start host services.
48
+ 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.
49
49
 
50
50
  ## Commands
51
51
 
@@ -117,7 +117,7 @@ A wait deadline does not cancel its job or ticket. `cancel` only cancels pending
117
117
  ### Agents and profiles
118
118
 
119
119
  `dogsled agent` starts a child with `herdr agent start <name> --kind pi|claude|codex --pane <pane> -- <args>`. The task is a launch argument, so nothing is typed into the new pane.
120
- A task with a newline, a leading `-` or `@`, or more than 4000 characters goes to `launches/<id>.task.md`. Pi reads it as `@<file>`; Claude and Codex get a one-line pointer to it.
120
+ Herdr types the launch as one terminal line of at most 1024 bytes, so no task text goes on it. The task is always `launches/<id>.task.md` on the host that runs the child; Pi reads it as `@<file>`, and Claude and Codex get a one-line pointer to it. Pi and Claude read the child contract from `launches/<id>.contract.md` (Codex has no file form, so its fixed contract stays inline). The host that runs the child refuses a name, profile or state path that makes the line over 960 bytes, before it creates a pane.
121
121
  `--message-file PATH` (or `-` for stdin) reads the task from a file.
122
122
  A failed `herdr agent start` is retried with backoff, three tries in all. After the last, the ticket fails and the owner's inbox says so. A refusal or a deadline fails at once.
123
123
  Herdr refuses a start before it types into the pane, for example `agent_pane_busy` or `agent_name_taken`. That refusal is final: dogsled records it as the launch result, closes the empty pane it created, and does not retry. Any other failure leaves the outcome unknown, so dogsled keeps the pane and reconciles it on the next try.
@@ -169,6 +169,7 @@ Then it closes every pane that uses the worktree and the Herdr workspace that sh
169
169
  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.
170
170
  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.
171
171
  A pane outside a worktree, or in an unlocked worktree (someone's own checkout), is closed alone; the checkout stays.
172
+ 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.
172
173
  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.
173
174
  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.
174
175
  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.
@@ -242,7 +243,7 @@ Peer reads run in parallel through SSH and the configured `remote_command`.
242
243
  A shared, locked cache permits at most one read per peer per ten seconds, including concurrent callers.
243
244
  Status never probes peers itself.
244
245
 
245
- `service: up` means a process holds the host's service lock. A free lock or unreachable peer means `service: down`.
246
+ `service: up` means a process holds the host's service lock. A free lock on a host that answers means `service: down`. A peer that SSH cannot read shows `unreachable: <category>` (for example `timeout` or `connection refused`, never the raw SSH text) instead, with the age of its last snapshot when one exists.
246
247
  Status shows snapshot age separately, including when the service runs. Peers without the liveness field retain the 30-second age fallback during upgrades.
247
248
  Admission still requires a snapshot no older than 30 seconds. Finished-child cleanup can use an older snapshot from a running service.
248
249
  Close rechecks the live pane, the child's `done` mark, and the loss guard before it acts.
@@ -328,7 +329,13 @@ An open agent item holds its checkout in prune and the sweep; `close` ends it an
328
329
  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.
329
330
  A dirty checkout whose commits are in the default branch gets a `landed_dirty` finding when no hold applies.
330
331
  The finding includes the repository, checkout, branch or HEAD, dirty-path count, and up to ten paths. It is never removable.
332
+ Before it reads checkout changes, the loss rule requires the checkout's own `.git` and a matching Git top-level path.
333
+ A missing or mismatched identity refuses the check. It never counts as clean or inherits a parent checkout's dirt.
331
334
  A registered worktree whose path is absent is a stale registration. Prune and the sweep remove the record only.
335
+ A planned worktree that something else removes before its removal runs is not a failure. When Git no longer lists it and its path is absent, the pass drops its registration and reports it as already removed. When Git no longer lists it but its path still exists, the removal is refused.
336
+ A worktree whose directory remains but that Git can no longer remove is an `unlinked` hold. This happens when Git does not list it (for example after `git worktree prune`), calls it prunable, or its `.git` file is gone.
337
+ Prune and the sweep never run `git worktree remove` on it, never delete it, and never fail on it. `close` refuses it before it closes or unlocks anything.
338
+ The hold names the reason and the path, for example `worktree unregistered by git; directory remains: <path>`. The owner checks the directory and moves or deletes it. The next pass then drops the registration as stale.
332
339
  Prune and the sweep use one pane rule. Both keep the caller's pane and focused panes.
333
340
  An empty shell closes when its job ended, its directory disappeared, its launch is final, or its agent item closed.
334
341
  A final launch was refused, never attempted, or has an unknown outcome with no agent in its terminal. Cleanup preserves launch receipts and checks terminal ownership under the launch locks.
@@ -343,10 +350,12 @@ Processes above 100% CPU outside Herdr pane ancestry are report-only. Prune neve
343
350
 
344
351
  Prune displays a plan and asks before removal. `--yes` skips that question, not safety checks.
345
352
  Each removal rechecks current state. Working or blocked panes, held worktrees, dirty worktrees, and local-only commits remain untouched.
346
- Removal rechecks Git path, branch, HEAD, and repository against the approved plan. Any identity change stops removal.
353
+ Removal rechecks Git path, branch, HEAD, and repository against the approved plan. Any change stops removal. A changed repository, path, or branch is an identity change and a failure. A HEAD that moved because of a new commit is live work and a skip.
347
354
  Worktree removal is the same as `close`: `teardown`, the panes and workspace, unlock, `git worktree remove`, the branch when its commits are held, and the idle anchor. Dogsled checks that the worktree is gone afterwards.
348
- Each entry is independent. A failed or refused entry does not stop the others; prune reports each failure, then exits with status 2.
349
- `--json` returns `{results,failures}`. A result names the removed path and the closed panes. A failed `teardown` command's error includes its last lines of output.
355
+ Each entry is independent. A failed or refused entry does not stop the others.
356
+ A recheck can refuse an entry because its state changed after the plan: the worktree is now dirty, held, or not landed, the pane is now busy, or a new commit moved HEAD after the plan. Prune keeps that entry and reports it as `skipped:` with the reason. A skip is not a failure.
357
+ An identity change (repository, path, or branch), a missing entry, a command error, or unreadable evidence is a failure. Prune reports each failure, then exits with status 2.
358
+ `--json` returns `{results,skipped,failures}`. A result names the removed path and the closed panes. A failed `teardown` command's error includes its last lines of output.
350
359
 
351
360
  Placement records repositories in `repositories.json`, independently of `worktrees.json`. Repository registrations survive the last worktree removal.
352
361
  Doctor also discovers repositories from the caller, live pane directories, Herdr workspaces, and `cleanup.repositories`. It never scans the whole home directory.
@@ -367,12 +376,12 @@ Each requested pass builds the doctor plan in sweep scope. It applies only entri
367
376
  - Stale repository and worktree registrations: remove only records whose paths are absent, with the same locked recheck as prune.
368
377
  - Orphaned children: a child that called `done`, whose owner is gone, and whose checkout passes the shared loss rule. Close runs teardown and removes its workspace, checkout, and item.
369
378
 
370
- The sweep runs the same checks as `close` and `prune`. It never closes the service's own pane or workspace, or a worktree that the service works in. It skips a worktree it cannot check, and a failure on one entry does not stop the others.
379
+ The sweep runs the same checks as `close` and `prune`. It never closes the service's own pane or workspace, or a worktree that the service works in. It skips a worktree it cannot check, and a failure on one entry does not stop the others. An entry that its recheck refuses because live work changed it after the survey is a skip, not a failure: the pass lists it as `skipped:`, and the stop gate ignores it.
371
380
  The service keeps seven days of completed passes in `sweeps.jsonl` and the latest pass in `sweep.json`.
372
381
  Each history entry has a `ts_ms` timestamp; each new pass removes entries older than seven days.
373
- The report includes start and finish times, removals, failures, repository warnings, and landed-dirty findings.
382
+ The report includes start and finish times, removals, failures, repository warnings, landed-dirty findings, and `unlinked` holds.
374
383
  `dogsled status` and `status --json` show the latest pass. Prompt context adds one summary line when that pass has errors or warnings.
375
- The service also writes removals, failures, and repository warnings to stderr.
384
+ The service also writes removals, failures, repository warnings, and holds to stderr.
376
385
  Child completion and orphan checks remain independent of requested doctor cleanup.
377
386
  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.
378
387
  Prune also handles ended jobs and `targets`. Disk and process findings are report-only. Repository findings remain report-only except for absent remembered paths.
@@ -548,10 +557,11 @@ Claude Code and Codex include the reminder in their existing `Stop` inbox respon
548
557
  The reminder requests a review, a commit from dirty children, integration, or an explicit blocker or deferral.
549
558
  It never commits, merges, closes, or discards work itself. Clean readers and working children do not trigger it.
550
559
 
551
- The gate reports failures, repository warnings, and landed-dirty findings from the latest completed pass, without waiting for the requested pass.
552
- Successful removals remain in status and the journal; they do not continue an agent turn.
553
- Repository warnings name the repository and state entries, and request delegation to a dogsled agent instead of manual state edits.
554
- Landed-dirty findings reach only panes in the same main repository, including linked worktrees and symlink paths.
560
+ The gate reports failures, `unlinked` holds, and landed-dirty findings from the latest completed pass, without waiting for the requested pass.
561
+ A finding reaches only the agent that created its work. That agent owns an open item whose pane holds the worktree or pane, or its launch record started a child in the worktree.
562
+ An agent that created nothing there hears nothing, whether Dogsled launched it or not. A research agent in the same repository gets no cleanup message.
563
+ Host-level failures and repository warnings have no creator. They stay in `dogsled status` and `status --brief` and reach no agent.
564
+ Prompt context shows the same owner-scoped counts. Successful removals remain in status and the journal; they do not continue an agent turn.
555
565
  The message asks the owner to read and preserve wanted changes, or obtain user approval before discarding abandoned work.
556
566
  It forbids forced worktree removal, `git clean`, and `rm -rf` on the checkout.
557
567
  Cleanup reminders use separate, once-per-set histories in `gate.json`, so an unchanged warning cannot cause a continuation loop.
@@ -569,14 +579,18 @@ Plugin commands end with `|| true`. Pi also leaves the prompt unchanged if the b
569
579
  ### Tools
570
580
 
571
581
  `dogsled mcp` serves the dogsled commands as MCP tools over stdio: `status`, `spawn`, `run`, `send`, `inbox`, `read`, `close`, `done`, `stop`, `cancel`, and `place`.
572
- Each tool calls the same code as its CLI command and returns the same JSON. No tool waits: `spawn` and `run` return the item or the queued ticket at once.
582
+ Tools share the CLI action code. `spawn` returns a durable queued ticket, even when a host has room.
583
+ The service owns startup confirmation outside the MCP call budget. `dogsled agent` still starts synchronously under `--max`.
584
+ Startup errors include recent pane output in the launch record and ticket when the pane read succeeds.
585
+ A failed pane read preserves the original error. Native refusals and unknown startup outcomes keep their existing recovery rules.
586
+ `run` returns the item or queued ticket at once.
573
587
  The caller is the harness's `HERDR_PANE_ID`. Pi registers the server from its extension (tools `mcp__dogsled__*`); Claude Code reads `plugins/dogsled/.mcp.json`; Codex reads `plugins/dogsled/codex-mcp.json`, which forwards the Herdr and `DOGSLED_*` variables.
574
588
 
575
589
  ### Pi
576
590
 
577
591
  The extension adds host status before each prompt, registers the tools, and draws:
578
592
 
579
- - **The right-side board** shows cached quotas, agents, jobs, and todos when `HERDR_ENV=1` and `HERDR_SOCKET_PATH` accepts a connection. Pi opens or reuses the tab’s split and sets no above-editor widget. Without Herdr, the existing widget shows host meters, the current task, and work groups. Agent/job data refreshes every ten seconds. Compatible pi-todo snapshots update immediately in the widget.
593
+ - **The right-side board** shows cached quotas, agents, jobs, and todos when `HERDR_ENV=1` and `HERDR_SOCKET_PATH` accepts a connection. Pi opens or reuses the tab’s board, docked at the left edge beside Herdr’s own sidebar at 38 cells, and sets no above-editor widget. Without Herdr, the existing widget shows host meters, the current task, and work groups. Agent/job data refreshes every ten seconds. Compatible pi-todo snapshots update immediately in the widget.
580
594
  - **Alt+W or `/work`** opens or reuses the Herdr split. Without Herdr, it expands or collapses the widget in place, without a popup or editor replacement. Alt+J/K moves selection, Alt+] changes views, and Alt+I shows inline details. Typing stays in the editor. Alt+S stops jobs, Alt+C cancels queued work, and Alt+M sends agent messages. Stop and cancel require confirmation. Completed job history starts collapsed.
581
595
  - **`/dogsled`**, the control panel, with four tabs: Status (hosts with their retry state, then your rows; Enter on a host reads it again now), Hosts (reconnect, rename, enable, disable, add), Profiles (Enter edits `prompt.md`), and Inbox. The widget steps aside while the panel is open.
582
596
  - **The inbox reader** and a renderer that shows each record's kind, sender, and text, folded past twelve lines.
@@ -587,15 +601,15 @@ Todos follow the active Pi session branch. Agents and jobs follow the calling He
587
601
 
588
602
  The Jobs view joins retained records to the current owner's ledger by host and job ID. It does not show unrelated fleet jobs. Job inspection uses `dogsled read` for a bounded log tail and shows the `dogsled logs` command for full output. Expired records and unavailable hosts produce explicit errors. The panel never starts a new process manager, edits todos, or writes into an agent terminal.
589
603
 
590
- The Herdr plugin opens the right-side work board:
604
+ The Herdr plugin docks the work board at the left edge of the tab, 38 cells wide. Its `toggle` action closes or reopens it:
591
605
 
592
606
  ```sh
593
- dogsled board --open # open or reuse the caller’s tab split
607
+ dogsled board --open # open or reuse the caller’s docked board (`--toggle` closes it)
594
608
  dogsled board --side --owner "$HERDR_PANE_ID" # print once
595
609
  herdr plugin pane open --plugin dogsled --entrypoint board --direction right --no-focus
596
610
  ```
597
611
 
598
- The split runs `dogsled board --side --watch` and refreshes every ten seconds. `--owner` defaults to the opening pane from Herdr’s plugin context.
612
+ The split runs the plugin's own `bin/dogsled board --side --watch` and refreshes every ten seconds. `--owner` defaults to the opening pane from Herdr’s plugin context.
599
613
  Quotas come only from `quota.json`; the board never calls a provider or reads credentials. The heading shows cache age and `STALE` after fifteen minutes.
600
614
 
601
615
  Pi renders each new todo revision through pi-todo’s `display.createView(host).render(width)`. Dogsled never reads or copies task state.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@oisin-ee/pi-dogsled",
3
- "version": "0.19.0",
3
+ "version": "0.21.0",
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",