@oisin-ee/pi-dogsled 0.13.0 → 0.14.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.14.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.14.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.14.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.14.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.14.0 --yes
 ```
 
 Harness plugins use the binary on `PATH`. They do not install it or start host services.
@@ -156,7 +156,7 @@ 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.
+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.
@@ -188,7 +188,7 @@ A reader claims records with `inbox claim`, which is a lease. A claimed record i
 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. An empty inbox prints nothing, so a stop ends as usual.
+- **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.
 
@@ -204,7 +204,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.
@@ -294,18 +294,21 @@ 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 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 shell, an idle or 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.
@@ -318,30 +321,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: an idle or done child 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
 
@@ -446,12 +458,34 @@ The removed lead ledger and event log are not read or migrated.
 
 ## Prompt context and integrations
 
-`dogsled hook context --harness claude|codex|pi` formats the same text as `status --brief`.
+`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 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.
+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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oisin-ee/pi-dogsled",
-  "version": "0.13.0",
+  "version": "0.14.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/pi/index.ts

@@ -240,12 +240,23 @@ export default function dogsled(pi: ExtensionAPI) {
 	// A delivered message is in the transcript once Pi ends it: only then is it acknowledged.
 	pi.on("message_end", async event => { await inbox.ended(event.message); });
 	pi.on("agent_settled", () => { inbox.settled(); });
+	pi.on("agent_before_settle", async event => {
+		if (!owner || event.outcome !== "completed" || !event.context.canContinue || event.continue) return;
+		// The Rust gate owns selection and durable deduplication across all harnesses.
+		const result = await pi.exec(binary, ["hook", "gate"], { timeout: 6_000 });
+		if (result.code !== 0) throw new Error(`dogsled stop gate failed: ${result.stderr.trim() || `exit ${result.code}`}`);
+		if (!result.stdout.trim()) return;
+		return {
+			entries: [...event.entries, { type: "custom_message" as const, customType: MESSAGE_TYPE, content: result.stdout.trim(), display: true }],
+			continue: true,
+		};
+	});
 	pi.on("before_agent_start", async (event) => {
 		// Context is optional, including when the binary is absent or fails.
 		try {
 			const result = await pi.exec(binary, ["hook", "context", "--harness", "pi"], { timeout: 6_000 });
 			if (result.code !== 0 || !result.stdout.trim()) return;
-			return { systemPrompt: `${event.systemPrompt}\n\n## Host status\n${result.stdout.trim()}\n` };
+			return { systemPrompt: `${event.systemPrompt}\n\n## Your work and fleet status\n${result.stdout.trim()}\n` };
 		} catch {
 			return;
 		}

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

@@ -18,7 +18,10 @@ dogsled read NAME_OR_PANE [--host H]
 ```
 
 The board groups what you started by what you must do: TO LAND (a finished child with commits), ATTENTION (blocked, stalled, failed), RUNNING, and WAITING (queued for a host). Each agent row shows its harness and model; each job row its command.
-Your prompt context carries host status and a `To land:` line. In Pi, the board widget above the editor shows host meters, the current task, and grouped agents and jobs. Alt+W or `/work` expands it in place. Work inspection stays inline, not in a popup. Todos follow the Pi branch; agents and jobs follow the owner pane. `/dogsled` retains host, profile, and inbox administration.
+Your prompt context leads with your own children and jobs, then a `To land:` line, then fleet status.
+Before you stop, a gate reminds you once per distinct set of finished children with unmerged commits or uncommitted changes.
+Read each result. Ask dirty children to finish and commit. Integrate approved work, or report its blocker or deferral.
+Never discard dirty work to satisfy the reminder. The gate does not close or merge anything. In Pi, the board widget above the editor shows host meters, the current task, and grouped agents and jobs. Alt+W or `/work` expands it in place. Work inspection stays inline, not in a popup. Todos follow the Pi branch; agents and jobs follow the owner pane. `/dogsled` retains host, profile, and inbox administration.
 
 ## Delegate
 
@@ -60,7 +63,8 @@ Blocked and working children never close, and nothing closes on a timer. To end
 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
@@ -97,8 +101,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