@oisin-ee/pi-dogsled 0.18.1 → 0.20.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 +36 -17
  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.18.1
14
+ mise use github:oisin-ee/dogsled@v0.20.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.18.1
20
+ pi install npm:@oisin-ee/pi-dogsled@0.20.0
21
21
  ```
22
22
 
23
23
  At session start the extension compares its version with `dogsled --version` and warns when they differ.
@@ -25,14 +25,14 @@ 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.18.1
28
+ claude plugin marketplace add oisin-ee/dogsled#v0.20.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.18.1
35
+ codex plugin marketplace add oisin-ee/dogsled --ref v0.20.0
36
36
  codex plugin add dogsled@dogsled
37
37
  ```
38
38
 
@@ -42,10 +42,10 @@ The [Codex CLI reference](https://developers.openai.com/codex/cli/reference#code
42
42
  Herdr (right-side work board):
43
43
 
44
44
  ```sh
45
- herdr plugin install oisin-ee/dogsled --ref v0.18.1 --yes
45
+ herdr plugin install oisin-ee/dogsled --ref v0.20.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
 
@@ -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.
@@ -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.
@@ -345,8 +352,10 @@ Prune displays a plan and asks before removal. `--yes` skips that question, not
345
352
  Each removal rechecks current state. Working or blocked panes, held worktrees, dirty worktrees, and local-only commits remain untouched.
346
353
  Removal rechecks Git path, branch, HEAD, and repository against the approved plan. Any identity change stops removal.
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, or the pane is now busy. Prune keeps that entry and reports it as `skipped:` with the reason. A skip is not a failure.
357
+ An identity change, 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.
@@ -468,15 +477,18 @@ Peers need a dogsled version that supports quota storage. No management credenti
468
477
  The version-1 contract contains `version`, `fetched_ms`, `source`, and `pools`.
469
478
  `source` identifies the collector by hostname. Each row contains these fields:
470
479
 
471
- - `pool`: `claude`, `codex`, or `minimax`.
480
+ - `pool`: the lowercase CLIProxy provider name, such as `claude`, `codex`, or a plugin provider. Consumers must accept any string.
472
481
  - `account` and `window`: the account label and provider window name.
473
482
  - `used_pct`: a number from 0 to 100.
474
483
  - `resets_ms`: Unix milliseconds, or `null` when unavailable.
475
484
  - `error`: a safe error description, or `null`.
476
485
 
477
486
  Claude windows are `five_hour`, `seven_day`, `seven_day_opus`, and `seven_day_sonnet`.
478
- Codex windows are `primary` and `secondary`. MiniMax windows are `interval` and `weekly`.
479
- MiniMax account labels use `minimax-N`, where N is the position in the configured API-key list.
487
+ Codex windows are `primary` and `secondary`.
488
+ Dogsled reads Claude and Codex through CLIProxy `api-call`. For every other enabled credential that CLIProxy marks `supports_quota`, it calls `POST /v0/management/quota/fetch` with the credential's `auth_index`. It needs no change for a new provider.
489
+ Each bucket becomes one row. The window is the bucket window. With more than one group, it is `<group>-<window>`, where the group is its lowercase `[a-z0-9_-]` display name.
490
+ `used_pct` is `(1 - remainingFraction) * 100`, limited to 0..100. `resets_ms` comes from `resetTime`.
491
+ Plugin account labels follow the same redaction as Claude and Codex labels. A failed fetch gives one error row with the window `quota`.
480
492
  A failed account has error rows with zero usage and no reset time. Consumers must treat these rows as unknown, not available quota.
481
493
  A pool is exhausted when every account has a window at 100% with a reset time in the future.
482
494
  Human output shows each window, reset time, and snapshot age. No snapshot produces an empty version-1 snapshot with `fetched_ms: 0`.
@@ -545,7 +557,10 @@ Claude Code and Codex include the reminder in their existing `Stop` inbox respon
545
557
  The reminder requests a review, a commit from dirty children, integration, or an explicit blocker or deferral.
546
558
  It never commits, merges, closes, or discards work itself. Clean readers and working children do not trigger it.
547
559
 
548
- The gate reports failures, repository warnings, and landed-dirty findings from the latest completed pass, without waiting for the requested pass.
560
+ The gate reports failures, repository warnings, `unlinked` holds, and landed-dirty findings from the latest completed pass, without waiting for the requested pass.
561
+ A worktree failure or `unlinked` hold goes to its open item’s owner when that owner exists. Otherwise it goes only to an operator pane.
562
+ Host-level repository warnings also go only to operators: panes Dogsled did not launch. Unrelated children receive neither notice.
563
+ Landed-dirty findings keep their repository-root filter.
549
564
  Successful removals remain in status and the journal; they do not continue an agent turn.
550
565
  Repository warnings name the repository and state entries, and request delegation to a dogsled agent instead of manual state edits.
551
566
  Landed-dirty findings reach only panes in the same main repository, including linked worktrees and symlink paths.
@@ -566,7 +581,11 @@ Plugin commands end with `|| true`. Pi also leaves the prompt unchanged if the b
566
581
  ### Tools
567
582
 
568
583
  `dogsled mcp` serves the dogsled commands as MCP tools over stdio: `status`, `spawn`, `run`, `send`, `inbox`, `read`, `close`, `done`, `stop`, `cancel`, and `place`.
569
- 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.
584
+ Tools share the CLI action code. `spawn` returns a durable queued ticket, even when a host has room.
585
+ The service owns startup confirmation outside the MCP call budget. `dogsled agent` still starts synchronously under `--max`.
586
+ Startup errors include recent pane output in the launch record and ticket when the pane read succeeds.
587
+ A failed pane read preserves the original error. Native refusals and unknown startup outcomes keep their existing recovery rules.
588
+ `run` returns the item or queued ticket at once.
570
589
  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.
571
590
 
572
591
  ### Pi
@@ -592,7 +611,7 @@ dogsled board --side --owner "$HERDR_PANE_ID" # print once
592
611
  herdr plugin pane open --plugin dogsled --entrypoint board --direction right --no-focus
593
612
  ```
594
613
 
595
- The split runs `dogsled board --side --watch` and refreshes every ten seconds. `--owner` defaults to the opening pane from Herdr’s plugin context.
614
+ 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.
596
615
  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.
597
616
 
598
617
  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.18.1",
3
+ "version": "0.20.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",