@oisin-ee/pi-dogsled 0.16.4 → 0.17.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 +79 -19
- package/package.json +1 -1
- package/pi/index.ts +4 -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.17.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.17.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.
|
|
28
|
+
claude plugin marketplace add oisin-ee/dogsled#v0.17.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.17.0
|
|
36
36
|
codex plugin add dogsled@dogsled
|
|
37
37
|
```
|
|
38
38
|
|
|
@@ -42,7 +42,7 @@ The [Codex CLI reference](https://developers.openai.com/codex/cli/reference#code
|
|
|
42
42
|
Herdr (status-board popup):
|
|
43
43
|
|
|
44
44
|
```sh
|
|
45
|
-
herdr plugin install oisin-ee/dogsled --ref v0.
|
|
45
|
+
herdr plugin install oisin-ee/dogsled --ref v0.17.0 --yes
|
|
46
46
|
```
|
|
47
47
|
|
|
48
48
|
Harness plugins use the binary on `PATH`. They do not install it or start host services.
|
|
@@ -108,7 +108,7 @@ The sidebar shows `working`, then `idle` for success or `blocked` for failure, w
|
|
|
108
108
|
|
|
109
109
|
`--max` sets one deadline from command startup, including discovery, placement, admission, and job completion. It defaults to 30 minutes.
|
|
110
110
|
Operations use the remaining command budget, capped at 30 seconds for routine calls and locks, or 10 minutes for setup.
|
|
111
|
-
Setup includes worktree creation and `setup` commands, repository clones, mise trust checks, and agent startup, locally and through SSH.
|
|
111
|
+
Setup includes worktree creation and removal, `setup` and `teardown` commands, repository clones, mise trust checks, and agent startup, locally and through SSH.
|
|
112
112
|
A non-waiting action reports the operation that exceeded its deadline.
|
|
113
113
|
`logs --follow` can continue indefinitely, but each remote read has a 30-second limit.
|
|
114
114
|
Run long waits through the harness's background-task facility.
|
|
@@ -129,6 +129,7 @@ Herdr refuses a start before it types into the pane, for example `agent_pane_bus
|
|
|
129
129
|
```
|
|
130
130
|
|
|
131
131
|
The child gets `--model`, `--thinking`, `--append-system-prompt <prompt>`, then `pi_args`. Unknown keys are ignored, so Shepherdr profiles load as they are.
|
|
132
|
+
`prompt` can also be a list, such as `["../_shared/lead.md", "prompt.md"]`. Each file becomes its own `--append-system-prompt`, in order, so profiles can share one prompt. A directory without `profile.json`, such as `_shared`, is not a profile. The profile panel edits the last file.
|
|
132
133
|
`role` is `reader` or `writer`. Without it, a child with `--branch` is a writer, and any other child a reader.
|
|
133
134
|
`dogsled profiles` lists them; a broken profile shows as `broken: <reason>`.
|
|
134
135
|
|
|
@@ -165,7 +166,7 @@ dogsled done # as a child: my whole task is complete
|
|
|
165
166
|
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.
|
|
166
167
|
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)).
|
|
167
168
|
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.
|
|
168
|
-
Close uses the same loss rule as cleanup:
|
|
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.
|
|
169
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.
|
|
170
171
|
A pane outside a worktree, or in an unlocked worktree (someone's own checkout), is closed alone; the checkout stays.
|
|
171
172
|
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.
|
|
@@ -241,8 +242,11 @@ Peer reads run in parallel through SSH and the configured `remote_command`.
|
|
|
241
242
|
A shared, locked cache permits at most one read per peer per ten seconds, including concurrent callers.
|
|
242
243
|
Status never probes peers itself.
|
|
243
244
|
|
|
244
|
-
|
|
245
|
-
|
|
245
|
+
`service: up` means a process holds the host's service lock. A free lock or unreachable peer means `service: down`.
|
|
246
|
+
Status shows snapshot age separately, including when the service runs. Peers without the liveness field retain the 30-second age fallback during upgrades.
|
|
247
|
+
Admission still requires a snapshot no older than 30 seconds. Finished-child cleanup can use an older snapshot from a running service.
|
|
248
|
+
Close rechecks the live pane, the child's `done` mark, and the loss guard before it acts.
|
|
249
|
+
Each tick observes a shared checkout once. Independent checkout and shell-pane reads use at most one worker per available CPU.
|
|
246
250
|
The last peer measurement remains visible when available. Every discovered host stays in the output.
|
|
247
251
|
The JSON output contains `hosts`, with service state, reachability, sample time, probe, headroom, errors, and `retry_ms` while a peer read backs off.
|
|
248
252
|
|
|
@@ -262,7 +266,7 @@ Example tab-row output:
|
|
|
262
266
|
local 11/12 ▲ · netcup 3/16 · momokaya-2 1/7
|
|
263
267
|
```
|
|
264
268
|
|
|
265
|
-
`▲` means not eligible. `?` means the
|
|
269
|
+
`▲` means not eligible, including a stale snapshot from a running service. `?` means the service is down or unavailable, or no snapshot exists.
|
|
266
270
|
A host without measurements prints `momokaya-2 ?`. A stale host keeps its last numbers, followed by ` ?`.
|
|
267
271
|
The numbers are busy cores over cores. A host without a CPU sample shows `load N/cores` instead.
|
|
268
272
|
`--brief` includes busy/cores, memory, disk, agent counts, and a hint to run `dogsled status`.
|
|
@@ -306,25 +310,30 @@ dogsled prune targets
|
|
|
306
310
|
Doctor changes no candidates. It reports `worktrees`, `branches`, `workspaces`, `panes`, `jobs`, `targets`, `disk`, `processes`, and `repositories`.
|
|
307
311
|
Doctor lists linked worktrees on a branch and detached ones.
|
|
308
312
|
One loss rule in `src/loss.rs` governs worktrees, detached HEADs, branches, close, and board facts.
|
|
309
|
-
A checkout must have no tracked or untracked
|
|
313
|
+
A checkout must have no unique tracked or untracked content. Ignored files do not count. A ref without a checkout skips this condition.
|
|
314
|
+
Deleted tracked files alone (` D` or `D `) lose nothing when the tip is held. Other changes still prevent removal.
|
|
315
|
+
Before removal, dogsled restores only those deleted paths from the held HEAD, including staged deletions. It then removes the checkout without force.
|
|
310
316
|
Every commit must be held by the default branch or remote-tracking refs. Each cleanup pass runs `git fetch --all --prune` before remote refs count.
|
|
311
317
|
A failed fetch produces a repository warning. Only the default branch counts for that repository. Deleted upstream branches receive no special treatment.
|
|
312
318
|
A branch is integrated when it is deleted, when it is an ancestor of Git's remote default branch (local `main` is the fallback), or when commits on that branch apply it.
|
|
313
|
-
The branch's commits split into consecutive runs, and each run needs one commit that applies it.
|
|
319
|
+
The branch's commits split into consecutive runs, and each run needs one commit that applies it. Each run uses its net diff, including paths and before/after objects, rather than the union of paths from its commits. Merges from main and reverted edits therefore do not enlarge the whole branch's required path set. A candidate must change every net path. The exact three-way merge into its parent must reproduce its content on those paths.
|
|
314
320
|
One run is a merge, squash, or cherry-pick of the whole branch. Several runs are a stack: the branch holds an earlier branch's commits, and each branch landed as its own squash. Git alone decides this.
|
|
315
321
|
Each path merges on its own. An addition, deletion, or mode change on a path the base also changed differently is a conflict, and renames are not followed, so a doubtful run is not applied.
|
|
322
|
+
A tip also counts as integrated when a local or remote-tracking ref contains it and that ref is integrated. This proof names the containing ref. The search considers only containing refs and checks each directly, without recursive alias loops.
|
|
316
323
|
Results use the remote-tracking branch, so `git fetch` keeps them current.
|
|
317
324
|
A local branch with no worktree is removable when it is integrated or every commit is on a remote branch. Other branches are report-only. The default branch is never a candidate. Prune deletes a branch with `git branch -D` after it rechecks the planned commit.
|
|
318
325
|
Prune and the sweep share the same holds: active panes or processes, the caller, an unreadable process table, and pending preparations or launches.
|
|
319
|
-
An unfinished launch holds its checkout
|
|
326
|
+
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.
|
|
320
327
|
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.
|
|
321
328
|
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.
|
|
322
329
|
A dirty checkout whose commits are in the default branch gets a `landed_dirty` finding when no hold applies.
|
|
323
330
|
The finding includes the repository, checkout, branch or HEAD, dirty-path count, and up to ten paths. It is never removable.
|
|
324
331
|
A registered worktree whose directory is gone is a stale registration. Prune drops the record only.
|
|
325
|
-
|
|
326
|
-
|
|
327
|
-
A
|
|
332
|
+
Prune and the sweep use one pane rule. Both keep the caller's pane and focused panes.
|
|
333
|
+
An empty shell closes when its job ended, its directory disappeared, its launch is final, or its agent item closed.
|
|
334
|
+
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.
|
|
335
|
+
A shell without a Dogsled record closes after 15 minutes continuously at an empty prompt, based on service observations and a fresh check. Herdr reports no activity time, so a command that starts and ends between samples does not count.
|
|
336
|
+
An agent pane still needs more than 24 hours continuously idle or done and a `done` mark. An agent with open children stays open.
|
|
328
337
|
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.
|
|
329
338
|
Ended jobs expire after 24 hours, together with their logs. Disk usage above 90% lists the largest known dogsled-owned paths.
|
|
330
339
|
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/`.
|
|
@@ -353,7 +362,7 @@ The socket is optional. A bind failure produces a warning, and pending requests
|
|
|
353
362
|
A Stop request failure produces a warning without preventing existing gate or inbox messages from reaching the agent.
|
|
354
363
|
Each requested pass builds the doctor plan in sweep scope. It applies only entries whose removal loses nothing:
|
|
355
364
|
|
|
356
|
-
- `panes` and `workspaces`:
|
|
365
|
+
- `panes` and `workspaces`: the shared pane rule above. A workspace closes whole only when every pane qualifies. Final launch panes close separately under their launch locks.
|
|
357
366
|
- `worktrees` and `branches`: the shared loss rule and holds described above, identical to prune.
|
|
358
367
|
- 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.
|
|
359
368
|
|
|
@@ -365,7 +374,7 @@ The report includes start and finish times, removals, failures, repository warni
|
|
|
365
374
|
The service also writes removals, failures, and repository warnings to stderr.
|
|
366
375
|
Child completion and orphan checks remain independent of requested doctor cleanup.
|
|
367
376
|
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.
|
|
368
|
-
Prune also handles
|
|
377
|
+
Prune also handles ended jobs, stale registrations, and `targets`. Disk, process, and repository findings are report-only.
|
|
369
378
|
|
|
370
379
|
## Placement
|
|
371
380
|
|
|
@@ -423,6 +432,57 @@ repositories = [] # for example "~/.config/mise"; `~/` is the home directory
|
|
|
423
432
|
|
|
424
433
|
Host policy has no worktree hooks. A `[hooks]` table is an unknown key, so it is an error. Worktree setup and teardown belong to each repository.
|
|
425
434
|
|
|
435
|
+
### Quota snapshots
|
|
436
|
+
|
|
437
|
+
```toml
|
|
438
|
+
[quota]
|
|
439
|
+
management_url = "https://cliproxy-admin.tail10e7b9.ts.net"
|
|
440
|
+
```
|
|
441
|
+
|
|
442
|
+
The URL is an HTTPS origin, without a path or credentials. No management key belongs in configuration.
|
|
443
|
+
Only macOS collects quota, and only when this Keychain lookup succeeds:
|
|
444
|
+
|
|
445
|
+
```sh
|
|
446
|
+
security find-generic-password -s dogsled -a cliproxy-management -w
|
|
447
|
+
```
|
|
448
|
+
|
|
449
|
+
This command prints the key. Dogsled captures it internally and never logs it.
|
|
450
|
+
Create the generic-password item through Keychain Access, with service `dogsled` and account `cliproxy-management`.
|
|
451
|
+
The collector passes the key to curl through stdin, never command arguments or a file.
|
|
452
|
+
Linux hosts never read the key. A missing URL or unreadable Keychain item makes quota commands use the local cache.
|
|
453
|
+
|
|
454
|
+
```sh
|
|
455
|
+
dogsled quota
|
|
456
|
+
dogsled quota --json
|
|
457
|
+
dogsled quota --json --cached
|
|
458
|
+
dogsled quota --refresh
|
|
459
|
+
```
|
|
460
|
+
|
|
461
|
+
`--cached` reads only `$DOGSLED_STATE/quota.json`, even when it is older than 15 minutes.
|
|
462
|
+
Without `--cached`, the collector refreshes snapshots older than five minutes. `--refresh` forces collection.
|
|
463
|
+
The service also refreshes every five minutes. A shared lock prevents concurrent collection, and failed collection backs off.
|
|
464
|
+
Each successful collection pushes the snapshot to enabled Herdr peers over SSH. Failed pushes retry with backoff.
|
|
465
|
+
Peers need a dogsled version that supports quota storage. No management credential leaves the collector.
|
|
466
|
+
|
|
467
|
+
The version-1 contract contains `version`, `fetched_ms`, `source`, and `pools`.
|
|
468
|
+
`source` identifies the collector by hostname. Each row contains these fields:
|
|
469
|
+
|
|
470
|
+
- `pool`: `claude`, `codex`, or `minimax`.
|
|
471
|
+
- `account` and `window`: the account label and provider window name.
|
|
472
|
+
- `used_pct`: a number from 0 to 100.
|
|
473
|
+
- `resets_ms`: Unix milliseconds, or `null` when unavailable.
|
|
474
|
+
- `error`: a safe error description, or `null`.
|
|
475
|
+
|
|
476
|
+
Claude windows are `five_hour`, `seven_day`, `seven_day_opus`, and `seven_day_sonnet`.
|
|
477
|
+
Codex windows are `primary` and `secondary`. MiniMax windows are `interval` and `weekly`.
|
|
478
|
+
MiniMax account labels use `minimax-N`, where N is the position in the configured API-key list.
|
|
479
|
+
A failed account has error rows with zero usage and no reset time. Consumers must treat these rows as unknown, not available quota.
|
|
480
|
+
A pool is exhausted when every account has a window at 100% with a reset time in the future.
|
|
481
|
+
Human output shows each window, reset time, and snapshot age. No snapshot produces an empty version-1 snapshot with `fetched_ms: 0`.
|
|
482
|
+
|
|
483
|
+
The hidden `quota --store` command accepts one validated snapshot on stdin and writes it atomically.
|
|
484
|
+
Older pushed snapshots cannot replace newer snapshots. The SSH transport uses the same writer through `host quota-store`.
|
|
485
|
+
|
|
426
486
|
### Repository configuration
|
|
427
487
|
|
|
428
488
|
An optional `dogsled.toml` at the root of the repository's main checkout configures its worktrees. Without the file, the defaults apply.
|
|
@@ -479,7 +539,7 @@ The CLI never reads stdin. Claude Code and Codex receive `hookSpecificOutput` JS
|
|
|
479
539
|
Pi receives plain text through its `before_agent_start` extension. All three use the same snapshot reader and formatter.
|
|
480
540
|
|
|
481
541
|
Before an orchestrator stops, the stop gate checks its own TO LAND children.
|
|
482
|
-
Pi calls `dogsled hook gate` from `agent_before_settle`
|
|
542
|
+
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.
|
|
483
543
|
Claude Code and Codex include the reminder in their existing `Stop` inbox response.
|
|
484
544
|
The reminder requests a review, a commit from dirty children, integration, or an explicit blocker or deferral.
|
|
485
545
|
It never commits, merges, closes, or discards work itself. Clean readers and working children do not trigger it.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@oisin-ee/pi-dogsled",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.17.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",
|
package/pi/index.ts
CHANGED
|
@@ -251,7 +251,10 @@ export default function dogsled(pi: ExtensionAPI) {
|
|
|
251
251
|
try { await units.settled(ctx); } catch (error) { ctx.ui.notify(`Dogsled unit acknowledgement pending: ${String(error)}`, "warning"); }
|
|
252
252
|
});
|
|
253
253
|
pi.on("agent_before_settle", async event => {
|
|
254
|
-
|
|
254
|
+
// `context.canContinue` describes the transcript before this handler's entries. A normal stop
|
|
255
|
+
// ends on the assistant, so it is false; the appended reminder is user context and makes the
|
|
256
|
+
// continuation valid. The gate must run on every completed stop: it also requests the sweep.
|
|
257
|
+
if (!owner || event.outcome !== "completed" || event.continue) return;
|
|
255
258
|
// The Rust gate owns selection and durable deduplication across all harnesses.
|
|
256
259
|
const result = await pi.exec(binary, ["hook", "gate"], { timeout: 6_000 });
|
|
257
260
|
if (result.code !== 0) throw new Error(`dogsled stop gate failed: ${result.stderr.trim() || `exit ${result.code}`}`);
|