@oisin-ee/pi-dogsled 0.0.0-stage → 0.13.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Oisín
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,523 @@
-# Temporary Holding Version
+# dogsled
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Host status and placement for coding agents across [Herdr](https://herdr.dev) hosts.
+
+Dogsled measures hosts, starts Pi, Claude, and Codex children and jobs on the host with room, queues work when every host is full, and carries every message between agents through an inbox. Nothing types into an agent's terminal.
+
+## Install
+
+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
+```
+
+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
+```
+
+At session start the extension compares its version with `dogsled --version` and warns when they differ.
+
+Claude Code (hooks, tools, and skill):
+
+```sh
+claude plugin marketplace add oisin-ee/dogsled#v0.13.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 add dogsled@dogsled
+```
+
+Codex requires review and trust before it runs plugin hooks. See the [Codex hooks documentation](https://developers.openai.com/codex/hooks#plugin-hooks).
+The [Codex CLI reference](https://developers.openai.com/codex/cli/reference#codex-plugin) describes plugin installation.
+
+Herdr (status-board popup):
+
+```sh
+herdr plugin install oisin-ee/dogsled --ref v0.13.0 --yes
+```
+
+Harness plugins use the binary on `PATH`. They do not install it or start host services.
+
+## Commands
+
+```sh
+dogsled serve                     # local measurements every 10 seconds
+dogsled serve --interval 20        # change the interval, in seconds
+dogsled serve --once               # publish and run each action lane once
+dogsled status                    # hosts, agents, and reservations
+dogsled status --json
+dogsled status --line              # one line for the tab row
+dogsled status --brief             # at most six lines for prompt hooks
+dogsled status --watch             # refresh until interrupted
+dogsled place --json               # reserve the host with the most headroom
+dogsled place --host netcup --json # pin by host id or label
+dogsled place --branch feat/unit-a --base main --repo /path/to/repo --json
+```
+
+Exit codes: 0 success, 1 queued without waiting, 2 error. Job waits return the job's exit code.
+When every host is full, `place`, `agent`, and `run` print `{"queued":true,"ticket":"…"}`.
+`--wait --max 30m` waits for admission. A wait that reaches its deadline prints `still running` and exits 124.
+
+## Jobs, agents, and owners
+
+```sh
+dogsled run --wait -- sh -c 'echo hi; exit 3'
+dogsled run --host netcup --cwd /tmp --timeout 1h --idle-timeout 10m -- make test
+dogsled run --branch feat/job --base main --cwd /path/to/repo -- cargo test
+dogsled ps --all
+dogsled logs JOB --follow
+dogsled stop JOB
+dogsled wait JOB --max 30m
+dogsled agent --kind codex --name reviewer --message 'Review the change' --branch feat/review --base main
+dogsled agent --profile general --name api-dups --message-file task.md --branch feat/api-dups
+dogsled board
+dogsled read api-dups
+dogsled send api-dups --message 'Also cover the empty case.'
+dogsled track netcup w1:p2 --name child
+dogsled items --owner "$HERDR_PANE_ID" --json
+dogsled cancel TICKET
+```
+
+Jobs use a new tab in the caller's workspace. With `--branch`, an agent uses the pane of the worktree's new Herdr workspace.
+Remote work uses a workspace with the same name as the caller's workspace, creating it when absent.
+Without a branch, a remote non-repository `--cwd` must exist there.
+Repository directories map to the same path relative to home. A linked-worktree caller needs `--branch` to preserve its branch remotely.
+
+The pane runs `dogsled exec ID -- COMMAND`. Output goes to the pane and `jobs/ID.log` on that host.
+If the pane output closes, capture continues to the log and preserves the child exit code.
+The atomic `jobs/ID.json` contains the command, directory, host, owner, exit code, signal, reason, and millisecond timestamps.
+After the job ends, `exec` saves this final record, reports completion, then closes its own pane and tab.
+`wait` reads the final record, and `logs` reads the saved output after the tab closes.
+If the close fails, `exec` logs the error to stderr without changing the result. Prune can close the ended job tab later.
+`host.json` includes job records. `ps --all` includes completed jobs and reads remote records through the snapshot cache.
+`logs`, `stop`, and `wait` use the configured SSH transport for remote jobs.
+`stop` requests a process-group kill. Timeouts and wrapper termination also kill the process group.
+Both timeout defaults are unlimited. Durations accept integer `ms`, `s`, `m`, and `h` suffixes.
+The sidebar shows `working`, then `idle` for success or `blocked` for failure, with a `dogsled` exit or timeout token.
+
+`--max` sets one deadline from command startup, including discovery, placement, admission, and job completion. It defaults to 30 minutes.
+Operations use the remaining command budget, capped at 30 seconds for routine calls and locks, or 10 minutes for setup.
+Setup includes worktree creation and `setup` commands, repository clones, mise trust checks, and agent startup, locally and through SSH.
+A non-waiting action reports the operation that exceeded its deadline.
+`logs --follow` can continue indefinitely, but each remote read has a 30-second limit.
+Run long waits through the harness's background-task facility.
+A wait deadline does not cancel its job or ticket. `cancel` only cancels pending tickets.
+
+### Agents and profiles
+
+`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.
+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.
+
+`--profile NAME` (Pi only) reads `~/.config/dogsled/profiles/NAME/profile.json` on the host that runs the child:
+
+```json
+{"description": "Ordinary units", "model": "alias/sol", "thinking": "medium", "prompt": "prompt.md", "role": "writer", "pi_args": []}
+```
+
+The child gets `--model`, `--thinking`, `--append-system-prompt <prompt>`, then `pi_args`. Unknown keys are ignored, so Shepherdr profiles load as they are.
+`role` is `reader` or `writer`. Without it, a child with `--branch` is a writer, and any other child a reader.
+`dogsled profiles` lists them; a broken profile shows as `broken: <reason>`.
+
+### Items and closing
+
+The owner's host stores locked `items.json` and `queue.json` files.
+An item records its host, pane, owner pane, creation time, closure time, and for an agent its harness, profile, model, role, and captured final reply.
+`items --json` returns `{items,queue}`. `--owner` filters both collections.
+The service closes a job item after job completion, and any item after pane removal.
+
+Closing is driven by events. When a child's turn completes (Herdr's `completion_seq` goes up) and it is `idle` or `done`, the sweep:
+
+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.
+
+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.
+
+`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.
+
+```sh
+dogsled close w2:p1
+dogsled close w9:p1 --host netcup --json
+```
+
+`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.
+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.
+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.
+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.
+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.
+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.
+`status` lists open items per owner and pending tickets. `--brief` includes their counts. Prompt context adds the caller's own `To land:` line.
+
+## Inbox
+
+Every message to an agent goes through one inbox on the agent's host: a child's final reply, a blocked report, an admitted ticket, a launch failure, and a message from another agent.
+
+```sh
+dogsled send api-dups --message 'Also cover the empty case.'
+dogsled send w9:p1 --host netcup --kind task --message-file note.md
+dogsled inbox list
+```
+
+`send` resolves a name or pane on any host and writes the record there, over SSH for a peer. A target with no inbox reader fails at once, and the sender hears so; a record never waits where nothing reads it.
+Records live in `inbox/<terminal>.json`, keyed by Herdr's terminal id, so a record follows the terminal and not a reused pane id.
+A reader claims records with `inbox claim`, which is a lease. A claimed record is offered again with backoff until `inbox ack` marks it delivered. When the terminal is gone, the record fails and the sender's own inbox says so.
+
+Readers:
+
+- **Pi:** the extension watches its inbox file, injects each batch as one `dogsled` message (`steer` while the agent runs, a new turn when it is idle), and acknowledges it when Pi has written the message to the session.
+- **Claude Code and Codex:** `dogsled hook inbox --harness claude|codex --event Stop|UserPromptSubmit`, registered by the plugin. The first hook run registers the reader. At `Stop`, records continue the turn as `{"decision":"block","reason":…}`; at `UserPromptSubmit`, they go beside the user's text as `additionalContext`. Records printed are acknowledged. At `Stop`, the same response also includes a new reminder about finished children with work to land. It prints nothing when neither is pending.
+
+A hook runs only when its harness acts, so an idle Claude Code or Codex agent sees a record at its next prompt or stop. Pi has no such delay.
+
+`inbox list --json` gives `{pane,terminal,received,sent,lines}`; `lines` is the display form the Pi panel shows.
+
+### Backoff
+
+One schedule is used for inbox leases, the sender's follow-up, peer reads, and launch retries: 10 seconds, doubling with jitter, capped at 5 minutes.
+A host that cannot be read shows `retry in 40s` on the board. `dogsled retry HOST` reads it again now.
+
+## Host service and status
+
+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.
+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.
+Transcript paths come from Herdr path sessions. Exact Claude and Codex session IDs also resolve against their standard session directories.
+Ambiguous, absent, or unreadable transcripts remain unstalled. Modification times use Unix milliseconds.
+Each pane also has `stalled_since_ms` and `state_since_ms`. The latter records the start of the observed state.
+The service stops with an error if a measurement fails. The last complete snapshot remains available.
+
+On Linux, the smallest finite `memory.max` from the process cgroup through its ancestors governs memory.
+Used memory is that scope's `memory.current` minus `inactive_file` from `memory.stat`.
+Without a finite limit, memory comes from `/proc/meminfo`: total minus `MemAvailable`.
+With a finite limit, the probe measures both and reports the scope with less free memory.
+On macOS, memory comes from `vm_stat` and `sysctl hw.memsize`, and `pressure_level` from `sysctl kern.memorystatus_vm_pressure_level` (1 normal, 2 warn, 4 critical).
+
+CPU busy is the fraction of the last interval that the CPUs were not idle.
+On Linux the probe records cumulative `/proc/stat` ticks (`cpu_ticks`); the service derives `busy` from the previous snapshot, so the first tick after start has no sample and admits nothing.
+On macOS `busy` comes from a one-second `iostat -c 2 -w 1` window.
+`load1` stays in the probe for display. It no longer takes part in admission.
+
+Every tick appends one line to `~/.local/state/dogsled/samples.jsonl`: time, cores, busy, load1, memory, pressure level, disk, reservations, live agents, free cores, and the admission verdict. Lines older than seven days are dropped on append.
+
+`status` reads the local snapshot and each enabled Herdr peer's snapshot.
+Peer reads run in parallel through SSH and the configured `remote_command`.
+A shared, locked cache permits at most one read per peer per ten seconds, including concurrent callers.
+Status never probes peers itself.
+
+A missing snapshot, failed read, or snapshot older than 30 seconds shows `service: down`.
+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.
+
+```sh
+dogsled machine list
+dogsled machine rename ID LABEL
+dogsled machine disable ID
+dogsled machine reconnect ID   # a new tab, for SSH prompts
+dogsled machine add user@host --label name
+```
+
+Hosts are Herdr's saved machines. `machine` runs the matching `herdr machine` command; `reconnect` and `add` run it in a new focused tab, so the user can answer SSH prompts.
+
+Example tab-row output:
+
+```text
+local 11/12 ▲ · netcup 3/16 · momokaya-2 1/7
+```
+
+`▲` means not eligible. `?` means the snapshot is missing, stale, or unavailable.
+A host without measurements prints `momokaya-2 ?`. A stale host keeps its last numbers, followed by ` ?`.
+The numbers are busy cores over cores. A host without a CPU sample shows `load N/cores` instead.
+`--brief` includes busy/cores, memory, disk, agent counts, and a hint to run `dogsled status`.
+Fleets larger than five hosts share lines to preserve both the six-line limit and visibility of every host.
+`--watch --interval N` changes the refresh interval. Its default is five seconds.
+
+## Stalls and check-ins
+
+A `working` or `unknown` agent stalls after ten minutes without a transcript change. Screen redraws do not reset this clock.
+An agent without a readable transcript never stalls. Recovery clears its `$dogsled` sidebar token.
+Status lists stalled panes. Brief status and prompt context include a stall count within six lines.
+
+The owner's service checks every minute. It checks in only with `idle` or `done` owners, never `working` or `blocked` owners.
+A check-in is a `check-in` record in the owner's inbox. An owner without an inbox reader gets none; a due check-in stays due until it has one.
+A stall or a completed job makes a check-in due. Other open work gets a check-in after 30 minutes without a check-in or lifecycle event. A finished child's reply comes from the sweep, not a check-in.
+Transcript writes alone do not postpone regular check-ins. Pending job-completion events survive item closure.
+The note includes names, hosts, states, ages, transcript silence, and bounded recent activity.
+Known Pi, Claude, and Codex transcripts supply the latest tool call or message. Unknown formats fall back to plain pane text.
+Job notes use the last five log lines. All note content has terminal escape codes removed.
+It asks the owner to wait, message a child with `dogsled send`, close it, or stop a job. Output in the note is untrusted data.
+A stalled top-level pane gets one Herdr notification per stall episode.
+
+Locked `watchdog.json` records events and last check-ins. `parents.json` identifies tracked children on their own host.
+A normal service restart does not repeat a delivered check-in. The inbox lease carries delivery from there.
+Notification attempts are recorded before delivery and never repeat within that stall; a crash can lose that notification.
+
+For authorized live tests only, `DOGSLED_TEST_STALL_MS` overrides the ten-minute threshold with a positive millisecond value.
+It does not shorten check-in cadence. Use private `DOGSLED_STATE` and stop the test service afterward.
+Debug binaries also accept `DOGSLED_TEST_NOW_MS` for deterministic integration tests. Release binaries ignore this test clock.
+
+## Cleanup
+
+```sh
+dogsled doctor --json
+dogsled doctor --host netcup
+dogsled prune worktrees jobs
+dogsled prune --host netcup --yes panes
+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.
+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.
+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.
+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.
+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/`.
+It is removable when no Herdr workspace shows the checkout and no pane or process works in it. Work in a linked worktree inside the main checkout uses that worktree, not the main checkout.
+Prune removes it after it checks the tag again. A worktree that the same plan removes takes its build output with it, so that output is not listed.
+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.
+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.
+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.
+### 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:
+
+- `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`.
+
+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.
+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.
+
+## Placement
+
+Headroom is free cores, the smaller of the measured and the declared value:
+
+```text
+measured = cores × (1 − busy) − reservation_load × reservations
+declared = cores − reservation_load × (active agents + reservations)
+```
+
+An active agent is a live agent that is not `idle`.
+It holds its demand while it waits on its model, because its next build starts within minutes.
+The measured value counts work that dogsled does not know about.
+
+A host is eligible when all of these hold:
+
+- a fresh service snapshot with a CPU sample;
+- at least `disk_free_min_percent` free on the home filesystem;
+- on macOS, memory pressure below critical;
+- free memory of at least `memory_reserve_bytes × (reservations + 1)`;
+- total memory of at least `memory_reserve_bytes × (active agents + reservations + 1)`;
+- free cores of at least `free_core_fraction_min × cores`.
+
+The host with most free cores wins. Ties use fewer live agents, then host id.
+The reasons for each refusal appear in `status --json` under `headroom.reason`.
+The thresholds come from the fleet measurements in `docs/research/2026-10-15-admission-metric.md`.
+The selected host rechecks reservations under its own lock before it accepts the placement.
+
+`place` writes a reservation with a default TTL of 90 seconds.
+It returns the host id and label. JSON also includes the reservation id.
+With `--branch`, it creates or reuses the branch's worktree on that host and returns its `path` and `pane_id` (see [Repository configuration](#repository-configuration)).
+`place` does not start an agent. `run` and `agent` perform placement and launch together.
+
+A reservation ends only at its TTL, which covers the time until the new agent appears in `herdr agent list`.
+Until the TTL ends, the new agent counts twice: as its reservation and as an active agent.
+Agent discovery and worktree failures do not end it early.
+
+## Configuration
+
+The optional host policy lives in `~/.config/dogsled/config.toml`.
+`--config PATH` or `$DOGSLED_CONFIG` selects another file.
+Unknown keys are errors.
+
+```toml
+free_core_fraction_min = 0.25
+memory_reserve_bytes = 3221225472
+disk_free_min_percent = 15
+reservation_load = 1.0
+reservation_ttl_ms = 90000
+remote_command = ["mise", "x", "--", "dogsled"]
+
+[cleanup]
+repositories = []  # for example "~/.config/mise"; `~/` is the home directory
+```
+
+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.
+
+### Repository configuration
+
+An optional `dogsled.toml` at the root of the repository's main checkout configures its worktrees. Without the file, the defaults apply.
+Unknown keys are errors.
+
+```toml
+[worktree]
+dir = ".worktrees"  # relative to the main checkout
+setup = []          # run in a new worktree after creation, in order
+teardown = []       # run in a worktree before removal, in order
+```
+
+Each command runs with `sh -c` in the worktree. `{main}` is the main checkout, `{path}` the worktree, and `{branch}` its branch (empty for a detached worktree).
+Dogsled quotes each value as one shell word. Any other `{…}` is an error, so the command text cannot use braces for anything else.
+Dogsled reads `dogsled.toml` from the main checkout, also for a worktree on an older branch.
+
+With `--branch`, `place`, `agent`, and `run` use the branch's worktree on the selected host:
+
+1. Dogsled refuses an invalid branch name, `--base` for a branch that exists, a branch checked out in the main checkout, and a worktree that has another lock. It needs a reachable Herdr server.
+2. A branch that has a worktree reuses it without `setup`. Otherwise `git worktree add` makes `<dir>/<branch>` with each `/` as `-`. A new branch starts from `--base`, else the remote default branch's local name (else `main`).
+3. The worktree is locked with the reason `agent:worktree`. The lock marks it as agent-owned, and `git worktree remove` refuses it until close or prune unlocks it.
+4. `setup` runs in a new worktree. If a command fails, dogsled removes the new worktree and the branch it made, and placement fails. The reservation stays.
+5. `herdr worktree open --no-focus` opens the worktree as a Herdr workspace linked to the repository. When the main checkout had no open workspace, Herdr opens one as the anchor, and dogsled records its id in the Git common directory as `agent-worktree-anchor`. A workspace that already showed the worktree may belong to a running child, so that is an error.
+
+Before repository work, dogsled verifies the selected host's checkout against the caller's `git remote get-url origin`.
+If the host has no checkout of the repository, dogsled clones it from the caller's origin into the same path relative to home first.
+An existing path with a different origin, or a non-repository path, is an error. Dogsled does not overwrite it.
+Clone errors identify the host and origin. Dogsled does not silently move the work elsewhere.
+After a fresh clone, dogsled checks mise configuration. If mise reports missing trust, dogsled trusts only that new checkout's configuration.
+For peers, a checkout under the local home maps to the same relative path under the peer's home.
+The peer reads its own host policy.
+Checkouts outside the home keep their absolute path.
+Hooks substitute `{branch}` and `{base}` literally, without interpreting placeholders inside their values.
+When `--base` is absent, a word that is only `{base}` is omitted. Other placeholders produce an error that names them.
+Prefer an argument list over shell interpolation.
+
+The hook must print JSON with `pane_id`, `path`, or both. `workspace_id` is optional.
+Progress text can precede a final JSON line.
+
+State defaults to `$XDG_STATE_HOME/dogsled`, or `~/.local/state/dogsled`.
+`$DOGSLED_STATE` selects a complete state-directory path.
+Host snapshots use `host.json`. New placement reservations use `placements.json`.
+Jobs use `jobs/`, owner items use `items.json`, and FIFO tickets use `queue.json`.
+The removed lead ledger and event log are not read or migrated.
+
+## Prompt context and integrations
+
+`dogsled hook context --harness claude|codex|pi` leads with your own children and jobs, then shows the fleet totals from `status --brief`.
+The owner summary separates work to land, attention, idle, done, running, and queued work.
+The `To land:` line names finished children with unmerged commits or uncommitted changes.
+Claude Code and Codex register `SessionStart` and `UserPromptSubmit` context hooks, and `UserPromptSubmit` and `Stop` inbox hooks (see [Inbox](#inbox)), in `plugins/dogsled`.
+Each registration supplies `--event`. The default context event is `UserPromptSubmit`.
+The CLI never reads stdin. Claude Code and Codex receive `hookSpecificOutput` JSON with `hookEventName` and `additionalContext`.
+Pi receives plain text through its `before_agent_start` extension. All three use the same snapshot reader and formatter.
+
+Before an orchestrator stops, the stop gate checks its own TO LAND children.
+Pi calls `dogsled hook gate` from `agent_before_settle` and adds a visible message that continues the run.
+Claude Code and Codex include the reminder in their existing `Stop` inbox response.
+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 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.
+Pi skips the gate on errors, aborts, and boundaries that already request continuation.
+This is a bounded reminder, not a permanent prohibition on stopping.
+
+Without `HERDR_ENV`, service snapshots, or a usable binary, the hooks add nothing.
+A hook has a five-second command budget. Hook failures exit successfully without output.
+Plugin commands end with `|| true`. Pi also leaves the prompt unchanged if the binary fails.
+
+### Tools
+
+`dogsled mcp` serves the dogsled commands as MCP tools over stdio: `status`, `spawn`, `run`, `send`, `inbox`, `read`, `close`, `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.
+
+### Pi
+
+The extension adds host status before each prompt, registers the tools, and draws:
+
+- **The board widget** above the editor shows host meters, the current task, and agents and jobs grouped TO LAND, ATTENTION, RUNNING, and WAITING. Agent/job data refreshes every ten seconds. Compatible pi-todo snapshots update immediately. Empty providers hide the widget. Unavailable providers show an error.
+- **Alt+W or `/work`** expands or collapses that 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.
+- **`/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.
+- **The inbox reader** and a renderer that shows each record's kind, sender, and text, folded past twelve lines.
+
+Without `HERDR_PANE_ID`, the extension starts no Dogsled polling or jobs. The shared display can still show todos and reports Dogsled unavailable. `$DOGSLED_BIN` selects the binary.
+
+Todos follow the active Pi session branch. Agents and jobs follow the calling Herdr owner pane, including after a Pi session change. `/todos` and Alt+T open the Todos view when compatible pi-todo is active. `/todos list` remains a plain readout. The [display contract](docs/pi-work.md) keeps task state and reminders in pi-todo. Dogsled retains execution, logs, cancellation, and completion delivery.
+
+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.
+
+The Herdr plugin keeps only the status-board popup:
+
+```sh
+herdr plugin pane open --plugin dogsled --entrypoint board
+```
+
+The popup runs `dogsled status --watch`. The pane-close release hooks and sidebar token configuration are removed.
+All three harness packages share `plugins/dogsled/skills/dogsled/SKILL.md`. It describes delegation, jobs, messages, and the queue.
+
+## Build and development
+
+Build this branch with the repository's pinned Rust toolchain:
+
+```sh
+cargo build --release
+npm ci
+```
+
+The executable is `target/release/dogsled`.
+Release archives include the binary, `dogsled.service`, and `dev.dogsled.plist` from `plugin/services/`.
+Harness installers read their manifests and skill from Git, not the binary archive. The skill move does not change the archive contents.
+Both run `dogsled serve` through `~/.local/bin/mise`, restart on failure, and log to the dogsled state directory.
+Dotfiles installs the systemd user unit or renders the launchd template with an absolute, XML-escaped `@HOME@` path.
+For launchd, dotfiles creates `~/.local/state/dogsled` before loading the agent. Systemd creates it through `StateDirectory`.
+If mise has a different installation path, dotfiles adjusts the executable path.
+Install the same release on every host before enabling its service. This PR does not install or start host services.
+
+The pre-commit hook runs `mise run check`: Rust format, Clippy, Rust tests, TypeScript typecheck, and Pi extension tests.
+CLI behavior tests use private state and fake Herdr/SSH executables. Time-sensitive unit tests inject timestamps.
+See [the design](docs/design.md) for watchdog delivery guarantees and cleanup scope.

package/package.json

@@ -1,6 +1,56 @@
 {
   "name": "@oisin-ee/pi-dogsled",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.13.1",
+  "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",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/oisin-ee/dogsled.git"
+  },
+  "homepage": "https://github.com/oisin-ee/dogsled#readme",
+  "files": [
+    "pi/",
+    "!pi/**/*.test.ts",
+    "plugins/dogsled/skills/",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "pi",
+    "herdr",
+    "agents",
+    "orchestration"
+  ],
+  "engines": {
+    "node": ">=20.6.0"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "node --test \"pi/**/*.test.ts\""
+  },
+  "pi": {
+    "extensions": [
+      "./pi/index.ts"
+    ],
+    "skills": [
+      "./plugins/dogsled/skills/dogsled"
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "1.0.4",
+    "@earendil-works/pi-tui": "1.0.4",
+    "@types/node": "26.6.4",
+    "typescript": "7.0.2"
+  }
+}