@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.
- package/README.md +38 -24
- 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.
|
|
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.
|
|
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.
|
|
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.
|
|
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 (
|
|
42
|
+
Herdr (left-docked work board):
|
|
43
43
|
|
|
44
44
|
```sh
|
|
45
|
-
herdr plugin install oisin-ee/dogsled --ref v0.
|
|
45
|
+
herdr plugin install oisin-ee/dogsled --ref v0.21.0 --yes
|
|
46
46
|
```
|
|
47
47
|
|
|
48
|
-
|
|
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
|
-
|
|
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
|
|
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
|
|
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
|
|
349
|
-
|
|
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,
|
|
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,
|
|
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,
|
|
552
|
-
|
|
553
|
-
|
|
554
|
-
|
|
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
|
-
|
|
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
|
|
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
|
|
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
|
|
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.
|
|
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",
|