@oisin-ee/pi-dogsled 0.13.1 → 0.15.0

package/README.md

@@ -11,13 +11,13 @@ Install the binary on each Herdr host. Use the same release tag in each command.
 Binary:
 
 ```sh
-mise use github:oisin-ee/dogsled@v0.13.0
+mise use github:oisin-ee/dogsled@v0.15.0
 ```
 
 Pi (extension, tools, and skill), from npm or as part of `@oisin-ee/oisinpi`:
 
 ```sh
-pi install npm:@oisin-ee/pi-dogsled@0.13.0
+pi install npm:@oisin-ee/pi-dogsled@0.15.0
 ```
 
 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
 Claude Code (hooks, tools, and skill):
 
 ```sh
-claude plugin marketplace add oisin-ee/dogsled#v0.13.0
+claude plugin marketplace add oisin-ee/dogsled#v0.15.0
 claude plugin install dogsled@dogsled
 ```
 
 Codex (hooks, tools, and skill):
 
 ```sh
-codex plugin marketplace add oisin-ee/dogsled --ref v0.13.0
+codex plugin marketplace add oisin-ee/dogsled --ref v0.15.0
 codex plugin add dogsled@dogsled
 ```
 
@@ -42,7 +42,7 @@ The [Codex CLI reference](https://developers.openai.com/codex/cli/reference#code
 Herdr (status-board popup):
 
 ```sh
-herdr plugin install oisin-ee/dogsled --ref v0.13.0 --yes
+herdr plugin install oisin-ee/dogsled --ref v0.15.0 --yes
 ```
 
 Harness plugins use the binary on `PATH`. They do not install it or start host services.
@@ -118,6 +118,7 @@ A wait deadline does not cancel its job or ticket. `cancel` only cancels pending
 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.
 `--message-file PATH` (or `-` for stdin) reads the task from a file.
 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.
+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.
 
 `--profile NAME` (Pi only) reads `~/.config/dogsled/profiles/NAME/profile.json` on the host that runs the child:
 
@@ -140,10 +141,13 @@ Closing is driven by events. When a child's turn completes (Herdr's `completion_
 
 1. reads its final reply from the transcript and keeps it in the item;
 2. puts the reply in the owner's inbox (see [Inbox](#inbox));
-3. closes a reader whose worktree is clean with no commits outside the default branch, and any child whose branch has landed.
+3. if the child called `done` during that turn, closes it when it is a reader whose worktree is clean with no commits outside the default branch, or when its branch has landed.
+
+Herdr's `idle` and `done` only mean that the agent is ready for input. A child that asks a question, or that waits for its own children, is idle too. So a child says it has finished with the `done` MCP tool or `dogsled done`, in the turn that completes its task. Dogsled tells each child this at launch: Pi and Claude through `--append-system-prompt`, Codex through `-c developer_instructions`. The mark lives in the host's `done.json`, keyed by the Herdr terminal. A later turn, or an inbox record delivered to the child, ends it. `done` is refused while the caller owns open items or queued tickets.
+A child that ends a turn without `done` stays open, and its reply tells the owner it waits for input.
 
 A child with commits to land stays open and shows under TO LAND on the board, and the prompt line says `To land: web-tests (+2)`. Merge or drop the branch; the next sweep closes it.
-A `blocked` child stays open, and the owner's inbox gets one `blocked` record per episode. A `working` child, or one that has never completed a turn, is never closed. Nothing closes on a timer.
+A `blocked` child stays open, and the owner's inbox gets one `blocked` record per episode. A `working` child, one that has never completed a turn, and one that has not called `done` are never closed automatically. Nothing closes on a timer.
 
 `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.
 `dogsled read TARGET [--host H]` shows a child's or job's newest output and the captured final reply.
@@ -151,12 +155,13 @@ A `blocked` child stays open, and the owner's inbox gets one `blocked` record pe
 ```sh
 dogsled close w2:p1
 dogsled close w9:p1 --host netcup --json
+dogsled done                       # as a child: my whole task is complete
 ```
 
 `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.
 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)).
 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.
-It deletes the branch only when dogsled's integration check finds it integrated (see [Cleanup](#cleanup)). An unmerged branch, or a branch still at the base tip, stays.
+Close uses the same loss rule as cleanup: a clean checkout 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.
 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.
 A pane outside a worktree, or in an unlocked worktree (someone's own checkout), is closed alone; the checkout stays.
 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.
@@ -166,6 +171,7 @@ After removal, close drops the worktree's registration, as prune does.
 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.
 
 The service admits tickets in FIFO order using the same placement policy.
+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.
 It records an admission error rather than silently choosing another host after a clone, prepare, or launch failure.
 A service interruption during admission leaves an explicit failed ticket for inspection, not an automatic duplicate launch.
 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.
@@ -204,7 +210,7 @@ A host that cannot be read shows `retry in 40s` on the board. `dogsled retry HOS
 Run `dogsled serve` on every host. Dotfiles owns launchd and systemd user-service installation.
 The measurement step uses no SSH. It reads CPU busy time, cores, memory, home disk space, Herdr agents, and Herdr panes.
 When it has owned items or tickets, the service reads peers through the status cache and can launch admitted work through SSH.
-Separate watchdog, admission, sweep, and inbox workers keep check-ins, slow setup, cleanup, and delivery independent from snapshot publication. Routine calls and lock waits have 30-second limits. Setup calls have a 10-minute limit.
+Separate watchdog, admission, child-completion, inbox, and requested-cleanup workers keep slow actions independent from snapshot publication. Routine calls and lock waits have 30-second limits. Setup calls have a 10-minute limit.
 An admission timeout records a failed ticket. The service continues publication and later actions.
 It writes `~/.local/state/dogsled/host.json` through atomic replacement.
 Each `probe.agent_panes` entry contains `pane`, `agent`, `state`, `name`, `transcript`, `transcript_modified`, `terminal_id`, `completion_seq`, `cwd`, the session's model and latest activity, and the worktree's branch, commits ahead, dirty state, and whether it landed.
@@ -232,6 +238,7 @@ A shared, locked cache permits at most one read per peer per ten seconds, includ
 Status never probes peers itself.
 
 A missing snapshot, failed read, or snapshot older than 30 seconds shows `service: down`.
+When a snapshot exists, the host's reason gives its age, such as `service: down (last snapshot 44s ago)`. A slow tick on a loaded host is tens of seconds old. A stopped service gets older on every read.
 The last peer measurement remains visible when available. Every discovered host stays in the output.
 The JSON output contains `hosts`, with service state, reachability, sample time, probe, headroom, errors, and `retry_ms` while a peer read backs off.
 
@@ -294,21 +301,25 @@ dogsled prune targets
 
 Doctor changes no candidates. It reports `worktrees`, `branches`, `workspaces`, `panes`, `jobs`, `targets`, `disk`, `processes`, and `repositories`.
 Doctor lists linked worktrees on a branch and detached ones.
-A removable worktree has a HEAD that has not moved more than 24 hours after Git made it and no commits beyond the base, or an integrated branch.
-A detached worktree is removable when it is clean, no pane holds it, and a remote branch holds its HEAD. Otherwise doctor reports its commits on no remote. A worktree whose HEAD has not moved is not integrated, even when its base moved past it. It also needs a clean tree, no foreign lock, and no pane that uses it.
-A worktree whose branch has unmerged commits and that no pane uses is report-only. Doctor shows the commits ahead, how many are on no remote, and the age of the last commit.
+One loss rule in `src/loss.rs` governs worktrees, detached HEADs, branches, close, and board facts.
+A checkout must have no tracked or untracked changes. Ignored files do not count. A ref without a checkout skips this condition.
+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.
+A failed fetch produces a repository warning. Only the default branch counts for that repository. Deleted upstream branches receive no special treatment.
 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.
 The branch's commits split into consecutive runs, and each run needs one commit that applies it. A commit applies a run when it changes every path the run changed, and merging the run into the commit's parent gives the commit's content on those paths.
 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.
 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.
 Results use the remote-tracking branch, so `git fetch` keeps them current.
 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.
-A pane holds a worktree when it works in it or sits in its workspace. A shell with no foreground command does not hold it.
-An agent holds it until it has been `idle` or `done` for 24 hours. Before that, the sweep closes a finished child that has nothing left to land.
-Held, dirty, and locked integrated worktrees are reported with the reason and are not removed.
+Prune and the sweep share the same holds: active panes or processes, the caller, an unreadable process table, and pending preparations or launches.
+An unfinished launch holds its checkout while its pane exists, because an interrupted start can still bring up an agent there. When its pane is gone, it holds nothing.
+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.
+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.
+A dirty checkout whose commits are in the default branch gets a `landed_dirty` finding when no hold applies.
+The finding includes the repository, checkout, branch or HEAD, dirty-path count, and up to ten paths. It is never removable.
 A registered worktree whose directory is gone is a stale registration. Prune drops the record only.
 A shell with no foreground command in an ended job's tab is idle at once: the job log keeps its output. So is a shell whose directory no longer exists.
-Other panes need more than 24 hours continuously idle or done, based on service observations and a fresh snapshot.
+Other panes need more than 24 hours continuously idle or done, based on service observations and a fresh snapshot. An agent pane also needs a `done` mark.
 A shell pane is idle when the service found no foreground command at each sample for more than 24 hours, and it still has none. Herdr reports no activity time, so a command that starts and ends between samples does not count.
 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.
 Ended jobs expire after 24 hours, together with their logs. Disk usage above 90% lists the largest known dogsled-owned paths.
@@ -318,30 +329,39 @@ Prune removes it after it checks the tag again. A worktree that the same plan re
 Processes above 100% CPU outside Herdr pane ancestry are report-only. Prune never kills processes or frees arbitrary disk paths.
 
 Prune displays a plan and asks before removal. `--yes` skips that question, not safety checks.
-Each removal rechecks current state. Working or blocked panes, held worktrees, dirty worktrees, and unintegrated branches remain untouched.
+Each removal rechecks current state. Working or blocked panes, held worktrees, dirty worktrees, and local-only commits remain untouched.
 Removal rechecks Git path, branch, HEAD, and repository against the approved plan. Any identity change stops removal.
-Worktree removal is the same as `close`: `teardown`, the panes and workspace, unlock, `git worktree remove`, the branch when integrated, and the idle anchor. Dogsled checks that the worktree is gone afterwards.
+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.
 Each entry is independent. A failed or refused entry does not stop the others; prune reports each failure, then exits with status 2.
 `--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.
 
 Placement records repositories in `repositories.json`, independently of `worktrees.json`. Repository registrations survive the last worktree removal.
 Doctor also discovers repositories from the caller, live pane directories, Herdr workspaces, and `cleanup.repositories`. It never scans the whole home directory.
-A configured path that is not a Git checkout is a report-only `repositories` entry.
+A missing or unreadable repository produces a report-only `repositories` warning. The warning names its registration or configuration, and the survey continues.
+Repository registrations stay unchanged.
 ### The sweep in `serve`
 
 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.
 The sweep catches what a broken loop leaves behind: a crashed owner, a killed process, or a worktree that something else made.
-On each pass, the service's sweep worker builds the doctor plan in sweep scope. It applies only entries whose removal loses nothing:
+The Stop gate writes `sweep-request.json` and wakes the local service through `sweep.sock`. It never runs the survey inside the hook.
+The service checks the durable request at startup, on notification, and on each publication iteration. No request means no survey.
+The socket is optional. A bind failure produces a warning, and pending requests still reach the worker on the publication interval.
+A Stop request failure produces a warning without preventing existing gate or inbox messages from reaching the agent.
+Each requested pass builds the doctor plan in sweep scope. It applies only entries whose removal loses nothing:
 
 - `panes` and `workspaces`: a shell at an empty prompt in an ended job's tab, or in a directory that no longer exists. A workspace closes whole when every pane in it is one of these.
-- `worktrees`: a clean worktree whose branch is integrated, or a clean detached worktree whose HEAD is on a remote branch. Nothing may hold it: no pane works in it, no workspace shows it, and no process works in it. An idle shell holds it too.
-- `branches`: a local branch with no worktree whose every commit is on a remote ref. An integrated branch with commits on no remote waits for `prune`.
-- Orphaned children: an open agent item whose owner pane no longer exists, whose child is `idle` or `done`, whose worktree is clean, and whose every commit is on a remote ref. The sweep closes it as `dogsled close` does: `teardown`, the workspace, the worktree, and the item. A remote child closes over SSH with `host close --pushed`.
+- `worktrees` and `branches`: the shared loss rule and holds described above, identical to prune.
+- 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.
 
 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.
-Each removal is a `dogsled sweep:` line on stderr, the service journal.
+The service keeps seven days of completed passes in `sweeps.jsonl` and the latest pass in `sweep.json`.
+Each history entry has a `ts_ms` timestamp; each new pass removes entries older than seven days.
+The report includes start and finish times, removals, failures, repository warnings, and landed-dirty findings.
+`dogsled status` and `status --json` show the latest pass. Prompt context adds one summary line when that pass has errors or warnings.
+The service also writes removals, failures, and repository warnings to stderr.
+Child completion and orphan checks remain independent of requested doctor cleanup.
 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.
-Everything else is for a confirmed `prune`: idle shells and agents after a day, a worktree with no commits a day after it was made, integrated branches with unpushed commits, ended jobs, stale registrations, and `targets`. Disk, process, and repository findings are report-only.
+Prune also handles idle panes after a day, ended jobs, stale registrations, and `targets`. Disk, process, and repository findings are report-only.
 
 ## Placement
 
@@ -460,6 +480,14 @@ Claude Code and Codex include the reminder in their existing `Stop` inbox respon
 The reminder requests a review, a commit from dirty children, integration, or an explicit blocker or deferral.
 It never commits, merges, closes, or discards work itself. Clean readers and working children do not trigger it.
 
+The gate reports failures, repository warnings, and landed-dirty findings from the latest completed pass, without waiting for the requested pass.
+Successful removals remain in status and the journal; they do not continue an agent turn.
+Repository warnings name the repository and state entries, and request delegation to a dogsled agent instead of manual state edits.
+Landed-dirty findings reach only panes in the same main repository, including linked worktrees and symlink paths.
+The message asks the owner to read and preserve wanted changes, or obtain user approval before discarding abandoned work.
+It forbids forced worktree removal, `git clean`, and `rm -rf` on the checkout.
+Cleanup reminders use separate, once-per-set histories in `gate.json`, so an unchanged warning cannot cause a continuation loop.
+
 The gate records each set of child item IDs, commit counts, and dirty states in `gate.json`.
 It continues once per distinct set, across process restarts. Row order and idle/done transitions do not cause another reminder.
 New states can trigger another reminder. Closing all owner items clears the history.
@@ -472,7 +500,7 @@ Plugin commands end with `|| true`. Pi also leaves the prompt unchanged if the b
 
 ### Tools
 
-`dogsled mcp` serves the dogsled commands as MCP tools over stdio: `status`, `spawn`, `run`, `send`, `inbox`, `read`, `close`, `stop`, `cancel`, and `place`.
+`dogsled mcp` serves the dogsled commands as MCP tools over stdio: `status`, `spawn`, `run`, `send`, `inbox`, `read`, `close`, `done`, `stop`, `cancel`, and `place`.
 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.
 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.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oisin-ee/pi-dogsled",
-  "version": "0.13.1",
+  "version": "0.15.0",
   "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.",
   "type": "module",
   "license": "MIT",

package/plugins/dogsled/skills/dogsled/SKILL.md

@@ -5,7 +5,7 @@ description: Start Pi, Claude, and Codex children and jobs on the Herdr host wit
 
 # Dogsled: children, jobs, and messages
 
-Use dogsled to delegate, run jobs, and message other agents. Prefer the tools (`status`, `spawn`, `run`, `send`, `inbox`, `read`, `close`, `stop`, `cancel`, `place`); each matches a CLI command and returns the same JSON. In Pi they are `mcp__dogsled__<tool>`.
+Use dogsled to delegate, run jobs, and message other agents. Prefer the tools (`status`, `spawn`, `run`, `send`, `inbox`, `read`, `close`, `done`, `stop`, `cancel`, `place`); each matches a CLI command and returns the same JSON. In Pi they are `mcp__dogsled__<tool>`.
 
 Never type into another agent's terminal (`herdr agent prompt`, `herdr pane send-text`, `send-keys`): it mixes your text into the user's draft. Use `send`.
 
@@ -52,18 +52,21 @@ dogsled inbox list
 
 ## Closing
 
-Dogsled closes a finished child for you, after it captures the reply:
+A child is finished when it calls the `done` tool (or `dogsled done`) during its last turn. Dogsled tells each child this at launch. Dogsled then closes the finished child for you, after it captures the reply:
 
-- a reader (no commits outside the default branch, clean tree) closes when it is idle or done;
+- a reader (no commits outside the default branch, clean tree) closes when that turn ends;
 - a writer closes once its branch has landed. Until then it shows under TO LAND: merge or drop the branch.
 
-Blocked and working children never close, and nothing closes on a timer. To end a child now:
+A child that ends a turn without `done` waits for input, for example after a question: its reply reaches your inbox, and it stays open. Answer it with `send`. Blocked and working children never close, and nothing closes on a timer.
+
+When you are a child, call `done` once, in the turn that completes your whole task, then end the turn with your final reply. Do not call it when you ask a question or wait for your own children; `done` is refused while you own open children or queued work. To end a child now:
 
 ```sh
 dogsled close PANE [--host HOST]
 ```
 
-It runs the repository's `teardown`, closes the panes and workspace that use the worktree, removes the worktree, and ends the item. It deletes the branch only when it is integrated. A child in an unlocked checkout loses only its pane.
+Close, prune, and the sweep use one loss rule: a clean checkout and every commit held by the default branch or freshly fetched remote refs. Ignored files do not count. A failed fetch disables remote-ref evidence for that repository.
+Close runs `teardown`, closes the panes and workspace, removes the checkout, and ends the item. The same loss rule governs branch deletion. A child in an unlocked checkout loses only its pane.
 It refuses, before it changes anything, a busy agent, a dirty or detached worktree, a foreign lock, your own pane, and a worktree you work in. Report a refusal; do not remove a worktree by hand.
 
 ## Run a job
@@ -100,8 +103,10 @@ dogsled doctor --host HOST --json
 dogsled prune --host HOST worktrees jobs
 ```
 
-Doctor is read-only. Prune shows candidates and asks; `--yes` skips only the question. Never use cleanup to close working or blocked agents.
-`serve` sweeps only what loses nothing: ended job tabs, shells in deleted directories, clean integrated worktrees that nothing holds, fully pushed branches, and orphaned children (owner gone, idle or done, clean, pushed).
+Doctor removes nothing, but refreshes remote refs. Prune shows candidates and asks. `--yes` skips only the question. Never close working or blocked agents through cleanup.
+Worktrees, detached HEADs, branches, and orphan close use the loss rule in Closing. Prune and the sweep use identical worktree and branch decisions.
+Holds protect active panes or processes, the caller, open agent items (only `close` ends them; a live owner also holds until landing), and pending preparations or launches. An unreadable process table also holds worktrees. An idle shell, an idle agent's own processes, or a workspace alone does not.
+Doctor reports unheld dirty checkouts whose work is in the default branch as `landed_dirty`, with up to ten dirty paths. Missing repositories produce warnings, and the survey continues.
 
 ## Hosts