@oisin-ee/pi-dogsled 0.14.0 → 0.16.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.14.0
+mise use github:oisin-ee/dogsled@v0.16.0
 ```
 
 Pi (extension, tools, and skill), from npm or as part of `@oisin-ee/oisinpi`:
 
 ```sh
-pi install npm:@oisin-ee/pi-dogsled@0.14.0
+pi install npm:@oisin-ee/pi-dogsled@0.16.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.14.0
+claude plugin marketplace add oisin-ee/dogsled#v0.16.0
 claude plugin install dogsled@dogsled
 ```
 
 Codex (hooks, tools, and skill):
 
 ```sh
-codex plugin marketplace add oisin-ee/dogsled --ref v0.14.0
+codex plugin marketplace add oisin-ee/dogsled --ref v0.16.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.14.0 --yes
+herdr plugin install oisin-ee/dogsled --ref v0.16.0 --yes
 ```
 
 Harness plugins use the binary on `PATH`. They do not install it or start host services.
@@ -87,8 +87,10 @@ 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.
+With `--branch`, an agent uses the pane of the worktree's new Herdr workspace.
+Other work in a repository opens a new tab where that repository is shown: the workspace of its worktree, else the main checkout's workspace.
+When no workspace shows the repository, dogsled opens a new workspace for it.
+Work outside any repository uses a new tab in the caller's workspace. On a remote host, that is the workspace with the caller's workspace name, created 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.
 
@@ -118,6 +120,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 +143,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,6 +157,7 @@ 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.
@@ -166,6 +173,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.
@@ -232,6 +240,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.
 
@@ -305,13 +314,14 @@ Each path merges on its own. An addition, deletion, or mode change on a path the
 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.
 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 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.
+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.
@@ -343,7 +353,7 @@ Each requested pass builds the doctor plan in sweep scope. It applies only entri
 
 - `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` 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.
+- 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.
 The service keeps seven days of completed passes in `sweeps.jsonl` and the latest pass in `sweep.json`.
@@ -492,7 +502,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.14.0",
+  "version": "0.16.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",
@@ -29,7 +29,7 @@
     "orchestration"
   ],
   "engines": {
-    "node": ">=20.6.0"
+    "node": ">=22.19.0"
   },
   "scripts": {
     "typecheck": "tsc --noEmit -p tsconfig.json",
@@ -44,12 +44,12 @@
     ]
   },
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": "*",
-    "@earendil-works/pi-tui": "*"
+    "@earendil-works/pi-coding-agent": "^1.3.0",
+    "@earendil-works/pi-tui": "^1.3.0"
   },
   "devDependencies": {
-    "@earendil-works/pi-coding-agent": "1.0.4",
-    "@earendil-works/pi-tui": "1.0.4",
+    "@earendil-works/pi-coding-agent": "1.3.0",
+    "@earendil-works/pi-tui": "1.3.0",
     "@types/node": "26.6.4",
     "typescript": "7.0.2"
   }

package/pi/index.ts

@@ -3,6 +3,7 @@ import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-a
 import { Box, Text, Key } from "@earendil-works/pi-tui";
 import { type Board, clean, parseBoard } from "./board.ts";
 import { WorkTodo } from "./work-todo.ts";
+import { UnitBridge } from "./unit-bridge.ts";
 import { workBoard, workText, type WorkState } from "./work.ts";
 import { type Details, InboxReader, MESSAGE_TYPE } from "./inbox.ts";
 import { openPanel } from "./panel.ts";
@@ -46,6 +47,9 @@ export default function dogsled(pi: ExtensionAPI) {
 	}
 
 	const inbox = new InboxReader(pi, exec);
+	const units = new UnitBridge(pi, binary);
+	pi.on("tool_call", (event, ctx) => units.call(event, ctx));
+	pi.on("tool_execution_end", (event, ctx) => units.ended(event.toolCallId, ctx));
 
 	pi.registerMessageRenderer<Details>(MESSAGE_TYPE, (message, { expanded, outputPad }, theme) => {
 		const records = message.details?.records ?? [];
@@ -168,6 +172,7 @@ export default function dogsled(pi: ExtensionAPI) {
 		const current = generation;
 		refresh = (async () => {
 			await inbox.drain(ctx);
+			try { await units.ready(ctx); await units.drain(ctx); } catch (error) { ctx.ui.notify(`Dogsled settlement delivery pending: ${String(error)}`, "warning"); }
 			if (ctx.mode !== "tui") return;
 			try {
 				const next = parseBoard(JSON.parse(await exec(["board", "--json"])));
@@ -192,7 +197,8 @@ export default function dogsled(pi: ExtensionAPI) {
 		return refresh;
 	}
 
-	pi.on("session_start", async (_event, ctx) => {
+	pi.on("session_start", async (event, ctx) => {
+		units.start(event.reason);
 		if (ctx.mode === "tui") ctx.ui.setWidget("dogsled", undefined);
 		requestWorkRender = undefined;
 		workPanel?.dispose();
@@ -222,6 +228,7 @@ export default function dogsled(pi: ExtensionAPI) {
 		await update(ctx);
 	});
 	pi.on("session_shutdown", (_event, ctx) => {
+		units.stop();
 		workPanel?.dispose();
 		generation++;
 		workAbort?.abort();
@@ -239,7 +246,10 @@ 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_settled", async (_event, ctx) => {
+		inbox.settled();
+		try { await units.settled(ctx); } catch (error) { ctx.ui.notify(`Dogsled unit acknowledgement pending: ${String(error)}`, "warning"); }
+	});
 	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.
@@ -251,7 +261,9 @@ export default function dogsled(pi: ExtensionAPI) {
 			continue: true,
 		};
 	});
-	pi.on("before_agent_start", async (event) => {
+	pi.on("before_agent_start", async (event, ctx) => {
+		if (!units.guard(ctx)) return;
+		try { await units.ready(ctx); } catch (error) { ctx.ui.notify(`Dogsled preparation recovery pending: ${String(error)}`, "warning"); }
 		// 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 });

package/pi/unit-bridge.ts

@@ -0,0 +1,174 @@
+import type { ExtensionAPI, ExtensionContext, ToolCallEvent, ToolCallEventResult, SessionStartEvent } from "@earendil-works/pi-coding-agent";
+import { acquire, execution, prepared, record, reference, repositoryIdentity, sameExecution, sameRef, unitInput, unwrap, type Execution, type Prepared, type UnitRef } from "./unit-protocol.ts";
+import { UnitWorker, type UnitExec } from "./unit-worker.ts";
+
+interface Invocation { origin: UnitRef; execution?: Execution; cwd: string; prepared?: Prepared; ended: boolean }
+const SPAWN = "mcp__dogsled__spawn";
+
+/** Execution bookkeeping stays in Dogsled; the task provider owns all task state. */
+export class UnitBridge {
+	private readonly calls = new Map<string, Invocation>();
+	private epoch = 0;
+	private draining: Promise<void> | undefined;
+	private recovery: Promise<void> | undefined;
+	private recovered = false;
+	private readonly worker: UnitWorker;
+	private readonly exec: UnitExec;
+	private readonly pi: Pick<ExtensionAPI, "events" | "exec" | "getFlag" | "registerFlag">;
+	constructor(pi: Pick<ExtensionAPI, "events" | "exec" | "getFlag" | "registerFlag">, binary: string) {
+		this.pi = pi;
+		this.exec = async (args, cwd) => {
+			const result = await pi.exec(binary, args, cwd === undefined ? undefined : { cwd });
+			if (result.code !== 0) throw new Error(`dogsled ${args.slice(0, 2).join(" ")} failed: ${result.stderr.trim() || result.stdout.trim() || result.code}`);
+			return JSON.parse(result.stdout);
+		};
+		this.worker = new UnitWorker(pi, this.exec);
+	}
+	start(reason: SessionStartEvent["reason"] = "startup"): void { this.epoch++; this.recovered = false; this.worker.start(reason); }
+	stop(): void { this.epoch++; }
+	guard(ctx: ExtensionContext): boolean { return this.worker.guard(ctx); }
+
+	/** Startup handlers have completed before this boundary; no registration-order race. */
+	ready(ctx: ExtensionContext): Promise<void> {
+		if (this.recovered || !acquire(this.pi.events)) return Promise.resolve();
+		if (this.recovery) return this.recovery;
+		const epoch = this.epoch;
+		this.recovery = this.resume(ctx).then(() => { if (epoch === this.epoch) this.recovered = true; }).finally(() => { this.recovery = undefined; });
+		return this.recovery;
+	}
+
+	/** A completed runtime startup establishes that untracked prior invocations cannot execute here. */
+	async resume(ctx: ExtensionContext): Promise<void> {
+		if (!acquire(this.pi.events)) return;
+		const epoch = this.epoch, session = ctx.sessionManager.getSessionId();
+		const pending = await this.exec(["unit", "prepared"], ctx.cwd);
+		if (!Array.isArray(pending)) throw new Error("LAUNCH_UNRESOLVED: prepared listing returned no list");
+		for (const item of pending) {
+			this.current(epoch, session, ctx);
+			if (!record(item) || !execution(item.execution) || !reference(item.origin) || typeof item.toolCallId !== "string") throw new Error("LAUNCH_UNRESOLVED: invalid preparation identity");
+			if (item.origin.sessionId !== session) continue;
+			const executionRef = item.execution, origin = item.origin;
+			if ([...this.calls.values()].some(call => !call.ended && sameRef(call.origin, origin))) continue;
+			await this.exec(["unit", "abandon-prepared", "--input", JSON.stringify({ execution: executionRef })], ctx.cwd);
+		}
+		await this.drain(ctx);
+	}
+
+	async call(event: ToolCallEvent, ctx: ExtensionContext): Promise<ToolCallEventResult | undefined> {
+		if (event.toolName !== SPAWN) return;
+		const input: unknown = event.input;
+		if (!record(input)) return { block: true, reason: "REQUEST_CONFLICT: spawn input must be an object" };
+		try {
+			if ("preparedUnit" in input) {
+				const owned = this.calls.get(event.toolCallId)?.prepared;
+				if (!owned || Object.keys(input).length !== 1 || JSON.stringify(owned) !== JSON.stringify(input.preparedUnit)) {
+					throw new Error("REQUEST_CONFLICT: preparedUnit is reserved for this invocation's mechanical handoff");
+				}
+				return;
+			}
+			if (!("unit" in input)) return;
+			const request = unitInput(input), epoch = this.epoch, session = ctx.sessionManager.getSessionId();
+			await this.ready(ctx);
+			this.current(epoch, session, ctx);
+			const provider = acquire(this.pi.events);
+			if (!provider) throw new Error("PROVIDER_UNAVAILABLE: pi-todo capability is unavailable or ambiguous");
+			const contract = unwrap(provider.inspect(request.id));
+			if (!record(contract) || !reference(contract.ref) || !record(contract.scope) || typeof contract.scope.repositoryId !== "string") {
+				throw new Error("PROVIDER_UNAVAILABLE: invalid inspected contract");
+			}
+			if (contract.ref.sessionId !== session) throw new Error("STALE_ORIGIN: task belongs to another session");
+			const origin = await this.pi.exec("git", ["remote", "get-url", "origin"], { cwd: ctx.cwd });
+			if (origin.code !== 0 || repositoryIdentity(origin.stdout) !== contract.scope.repositoryId) throw new Error("REQUEST_CONFLICT: checkout origin differs from repositoryId");
+			this.current(epoch, session, ctx);
+			// Retain the origin before I/O: prepare may persist while its response is lost.
+			const invocation: Invocation = { origin: contract.ref, cwd: ctx.cwd, ended: false };
+			this.calls.set(event.toolCallId, invocation);
+			const result = await this.exec(["unit", "prepare", "--input", JSON.stringify({ origin: contract.ref, placement: request.placement }), "--tool-call-id", event.toolCallId], ctx.cwd);
+			if (!execution(result)) throw new Error("LAUNCH_UNRESOLVED: prepare returned invalid execution");
+			invocation.execution = result;
+			this.current(epoch, session, ctx);
+			// Reacquire after I/O so shutdown and ownership changes cannot revive old authority.
+			const current = acquire(this.pi.events);
+			if (!current) throw new Error("PROVIDER_UNAVAILABLE: task provider disappeared before claim");
+			const claim = unwrap(current.claim({ expected: contract.ref, execution: result }));
+			const enriched = record(claim) ? { execution: result, binding: claim.binding, exported: claim.exported } : null;
+			if (!prepared(enriched) || !sameRef(enriched.binding.contract, contract.ref) || !sameExecution(enriched.execution, result)) throw new Error("PROVIDER_UNAVAILABLE: claim returned mismatched export");
+			invocation.prepared = enriched;
+			for (const key of Object.keys(input)) delete input[key];
+			input.preparedUnit = enriched;
+			return;
+		} catch (error) {
+			// This hook never committed. Its own failure proves this invocation did not launch.
+			const invocation = this.calls.get(event.toolCallId);
+			if (invocation?.execution) { invocation.ended = true; await this.recover(event.toolCallId, invocation, ctx); }
+			return { block: true, reason: String(error) };
+		}
+	}
+
+	private current(epoch: number, session: string, ctx: ExtensionContext): void {
+		if (epoch !== this.epoch || session !== ctx.sessionManager.getSessionId() || ctx.signal?.aborted) throw new Error("STALE_ORIGIN: session changed or invocation aborted during handoff");
+	}
+	async ended(id: string, ctx: ExtensionContext): Promise<void> {
+		const invocation = this.calls.get(id);
+		if (!invocation) return;
+		invocation.ended = true;
+		await this.recover(id, invocation, ctx);
+	}
+	private async recover(id: string, invocation: Invocation, ctx: ExtensionContext): Promise<void> {
+		try {
+			if (!invocation.ended) return;
+			if ([...this.calls.values()].some(other => other !== invocation && !other.ended && sameRef(other.origin, invocation.origin))) return;
+			if (!invocation.execution) {
+				const pending = await this.exec(["unit", "prepared"], invocation.cwd);
+				if (!Array.isArray(pending)) throw new Error("LAUNCH_UNRESOLVED: invalid prepared listing");
+				for (const item of pending) {
+					if (!record(item) || !execution(item.execution) || !reference(item.origin) || typeof item.toolCallId !== "string") throw new Error("LAUNCH_UNRESOLVED: invalid preparation identity");
+					// Prepare deduplicates by full origin and retains the first invocation ID on retries.
+					if (sameRef(item.origin, invocation.origin)) invocation.execution = item.execution;
+				}
+				if (!invocation.execution) { this.calls.delete(id); await this.drain(ctx); return; }
+			}
+			const state = await this.exec(["unit", "observe", "--input", JSON.stringify({ execution: invocation.execution })], invocation.cwd);
+			if (!record(state) || !execution(state.execution) || !sameExecution(state.execution, invocation.execution)) throw new Error("LAUNCH_UNRESOLVED: invalid observation");
+			if (state.phase === "prepared" && invocation.ended) {
+				await this.exec(["unit", "abandon-prepared", "--input", JSON.stringify({ execution: invocation.execution })], invocation.cwd);
+			} else if (state.phase === "prepared") return;
+			this.calls.delete(id);
+			await this.drain(ctx);
+		} catch (error) {
+			// Unknown outcome keeps the durable claim and in-memory recovery intent.
+			ctx.ui.notify(`Dogsled unit recovery pending: ${String(error)}`, "warning");
+		}
+	}
+
+	/** Provider settlement acknowledgements are independent of inbox text acknowledgements. */
+	drain(ctx: ExtensionContext): Promise<void> {
+		if (this.draining) return this.draining;
+		const epoch = this.epoch;
+		this.draining = (async () => {
+			if (!acquire(this.pi.events)) return;
+			const pending = await this.exec(["unit", "settlements"], ctx.cwd);
+			if (!Array.isArray(pending)) throw new Error("LAUNCH_UNRESOLVED: settlements returned no list");
+			for (const event of pending) {
+				if (epoch !== this.epoch) return;
+				if (!record(event) || typeof event.eventId !== "string") throw new Error("LAUNCH_UNRESOLVED: invalid settlement identity");
+				const owner = record(event.binding) ? event.binding.execution : event.execution;
+				if (!execution(owner)) throw new Error("LAUNCH_UNRESOLVED: missing settlement execution");
+				const provider = acquire(this.pi.events);
+				if (!provider) return;
+				const result = provider.settle(event);
+				if (!result.ok) continue; // Wrong branch or revision stays pending in Dogsled.
+				if (!record(result.value) || typeof result.value.applied !== "boolean") throw new Error("PROVIDER_UNAVAILABLE: invalid settlement acknowledgement");
+				await this.exec(["unit", "ack-settlement", "--input", JSON.stringify({ execution: owner, eventId: event.eventId })], ctx.cwd);
+			}
+		})().finally(() => { this.draining = undefined; });
+		return this.draining;
+	}
+	async settled(ctx: ExtensionContext): Promise<void> {
+		for (const [id, invocation] of this.calls) {
+			if (invocation.ended) await this.recover(id, invocation, ctx);
+		}
+		await this.worker.settled(ctx);
+		await this.drain(ctx);
+	}
+}

package/pi/unit-protocol.ts

@@ -0,0 +1,85 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+export interface UnitRef { sessionId: string; unitId: string; revision: number; contractEntryId: string }
+export interface Execution { executor: string; ownerId: string; requestId: string }
+export interface Binding { contract: UnitRef; execution: Execution; exportDigest: string }
+export interface Exported { version: number; provider: string; contract: { ref: UnitRef; scope: { repositoryId: string } }; digest: string; [key: string]: unknown }
+export interface Prepared { execution: Execution; binding: Binding; exported: Exported }
+export interface Receipt { version: number; execution: Execution; unitRef: UnitRef; digest: string; localSessionId: string; seal: { entryId: string; disposition: "completed" | "abandoned" } | null }
+export type Result = { ok: true; value: unknown } | { ok: false; error: { code: string; message: string } };
+export interface TaskProvider {
+	inspect(id: string): Result;
+	claim(input: { expected: UnitRef; execution: Execution }): Result;
+	settle(input: unknown): Result;
+	imported(): Result;
+}
+export type Placement = { host?: string; branch?: string; base?: string };
+export function record(value: unknown): value is Record<string, unknown> { return typeof value === "object" && value !== null && !Array.isArray(value); }
+function text(value: unknown): value is string { return typeof value === "string" && value.trim().length > 0; }
+export function reference(value: unknown): value is UnitRef {
+	return record(value) && text(value.sessionId) && text(value.unitId) && Number.isSafeInteger(value.revision) && Number(value.revision) > 0 && text(value.contractEntryId);
+}
+export function execution(value: unknown): value is Execution {
+	return record(value) && value.executor === "dogsled" && text(value.ownerId) && text(value.requestId);
+}
+export function sameRef(a: UnitRef, b: UnitRef): boolean {
+	return a.sessionId === b.sessionId && a.unitId === b.unitId && a.revision === b.revision && a.contractEntryId === b.contractEntryId;
+}
+export function sameExecution(a: Execution, b: Execution): boolean {
+	return a.executor === b.executor && a.ownerId === b.ownerId && a.requestId === b.requestId;
+}
+export function binding(value: unknown): value is Binding {
+	return record(value) && reference(value.contract) && execution(value.execution) && typeof value.exportDigest === "string" && /^[a-f0-9]{64}$/.test(value.exportDigest);
+}
+export function exported(value: unknown): value is Exported {
+	return record(value) && value.version === 1 && value.provider === "pi-todo" && record(value.contract)
+		&& reference(value.contract.ref) && record(value.contract.scope) && text(value.contract.scope.repositoryId)
+		&& typeof value.digest === "string" && /^[a-f0-9]{64}$/.test(value.digest);
+}
+export function prepared(value: unknown): value is Prepared {
+	return record(value) && execution(value.execution) && binding(value.binding) && exported(value.exported)
+		&& sameExecution(value.execution, value.binding.execution) && sameRef(value.binding.contract, value.exported.contract.ref)
+		&& value.binding.exportDigest === value.exported.digest;
+}
+export function receipt(value: unknown): value is Receipt {
+	return record(value) && value.version === 1 && execution(value.execution) && reference(value.unitRef)
+		&& typeof value.digest === "string" && /^[a-f0-9]{64}$/.test(value.digest) && text(value.localSessionId)
+		&& (value.seal === null || (record(value.seal) && text(value.seal.entryId) && ["completed", "abandoned"].includes(String(value.seal.disposition))));
+}
+function provider(value: unknown): value is TaskProvider {
+	return record(value) && ["inspect", "claim", "settle", "imported"].every(key => typeof value[key] === "function");
+}
+export function acquire(events: ExtensionAPI["events"]): TaskProvider | undefined {
+	const replies: unknown[] = [];
+	events.emit("oisin.tasks.acquire.v1", { version: 1, reply: (value: unknown) => { replies.push(value); } });
+	if (replies.length !== 1 || !provider(replies[0])) return undefined;
+	return replies[0];
+}
+export function unwrap(result: Result): unknown {
+	if (!record(result) || typeof result.ok !== "boolean") throw new Error("PROVIDER_UNAVAILABLE: invalid capability result");
+	if (!result.ok) throw new Error(`${result.error.code}: ${result.error.message}`);
+	return result.value;
+}
+export function unitInput(input: Record<string, unknown>): { id: string; placement: Placement } {
+	if (Object.keys(input).some(key => !["unit", "host", "branch", "base"].includes(key)) || !record(input.unit)
+		|| Object.keys(input.unit).length !== 1 || !text(input.unit.id)) throw new Error("REQUEST_CONFLICT: unit spawn cannot include a brief, profile, cwd, or prepared envelope");
+	const placement: Placement = {};
+	for (const key of ["host", "branch", "base"] as const) {
+		if (input[key] === undefined) continue;
+		if (!text(input[key])) throw new Error(`REQUEST_CONFLICT: ${key} must be a nonempty string`);
+		placement[key] = input[key];
+	}
+	if (placement.base && !placement.branch) throw new Error("REQUEST_CONFLICT: base requires branch");
+	return { id: input.unit.id, placement };
+}
+
+/** Clone transport is not repository identity. Keep path case; do not accept local paths. */
+export function repositoryIdentity(origin: string): string {
+	const value = origin.trim();
+	const scp = value.includes("://") ? null : /^(?:[^/@:\s]+@)?(?<host>[^/:\s]+):(?<path>[^\s]+)$/.exec(value);
+	const url = new URL(scp?.groups ? `ssh://${scp.groups["host"]}/${scp.groups["path"]}` : value);
+	const path = url.pathname.replace(/^\//, "").replace(/\/$/, "").replace(/\.git$/, "");
+	if (!["ssh:", "https:", "http:", "git:"].includes(url.protocol) || !url.hostname || !path || url.search || url.hash
+		|| path.split("/").some(part => !part || part === "." || part === "..")) throw new Error("REQUEST_CONFLICT: origin must identify a remote repository host/path");
+	return `${url.hostname.toLowerCase()}/${path}`;
+}

package/pi/unit-worker.ts

@@ -0,0 +1,93 @@
+import { closeSync, constants, fstatSync, openSync, readFileSync } from "node:fs";
+import type { ExtensionAPI, ExtensionContext, SessionStartEvent } from "@earendil-works/pi-coding-agent";
+import { acquire, prepared, receipt, record, sameExecution, sameRef, unwrap, type Prepared, type Receipt } from "./unit-protocol.ts";
+
+/** Read transport correlation, not task semantics; pi-todo validates the actual contract. */
+function seedFile(path: string): Prepared {
+	const fd = openSync(path, constants.O_RDONLY | constants.O_NONBLOCK);
+	try {
+		const stat = fstatSync(fd);
+		if (!stat.isFile() || stat.size > 1_048_576) throw new Error("invalid seed artifact");
+		const bytes = readFileSync(fd);
+		if (bytes.length > 1_048_576) throw new Error("seed artifact too large");
+		const value: unknown = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+		if (!record(value) || value.version !== 1 || !prepared(value)) throw new Error("invalid seed correlation");
+		return value;
+	} finally { closeSync(fd); }
+}
+
+export type UnitExec = (args: string[], cwd?: string) => Promise<unknown>;
+
+/** The loaded guard enforces fresh-session startup, not resume-time compaction. */
+export class UnitWorker {
+	private seed: Prepared | undefined;
+	private failure: string | undefined;
+	private managed = false;
+	private reason: SessionStartEvent["reason"] = "startup";
+	private readonly pi: Pick<ExtensionAPI, "events" | "getFlag" | "registerFlag">;
+	private readonly exec: UnitExec;
+	constructor(pi: Pick<ExtensionAPI, "events" | "getFlag" | "registerFlag">, exec: UnitExec) {
+		this.pi = pi; this.exec = exec;
+		// Dogsled alone owns the launch flag and supplies its path over the event bus.
+		// Register it even without pi-todo so the loaded guard can reject missing import.
+		pi.registerFlag("todo-unit-file", { type: "string", description: "Executor-owned worker task seed" });
+		// Register during extension loading, before any session_start import handler.
+		pi.events.on("oisin.tasks.seed-source.v1", input => {
+			if (!record(input) || input.version !== 1 || typeof input.reply !== "function") return;
+			input.reply({ version: 1, path: pi.getFlag("todo-unit-file") ?? null });
+		});
+	}
+	start(reason: SessionStartEvent["reason"] = "startup"): void {
+		this.reason = reason;
+		this.seed = undefined;
+		this.failure = undefined;
+		const path = this.pi.getFlag("todo-unit-file");
+		this.managed = path !== undefined;
+		if (!this.managed) return;
+		try {
+			if (typeof path !== "string" || !path) throw new Error("missing seed path");
+			this.seed = seedFile(path);
+		} catch (error) { this.failure = String(error); }
+	}
+	private imported(ctx: ExtensionContext): Receipt | null {
+		const provider = acquire(this.pi.events);
+		if (!provider) {
+			if (this.managed) throw new Error("task provider unavailable");
+			return null;
+		}
+		const value = unwrap(provider.imported());
+		if (value === null && !this.managed) return null;
+		if (!receipt(value) || value.localSessionId !== ctx.sessionManager.getSessionId()
+			|| value.localSessionId !== value.execution.requestId) throw new Error("missing or mismatched import acknowledgement");
+		const recorded = this.reason === "reload" || this.reason === "resume"
+			|| ctx.sessionManager.getEntries().some(entry => entry.type === "message");
+		if (!recorded) {
+			if (!this.seed || this.failure) throw new Error(this.failure ?? "missing seed");
+			if (!sameExecution(value.execution, this.seed.execution) || !sameRef(value.unitRef, this.seed.binding.contract)
+				|| value.digest !== this.seed.binding.exportDigest) throw new Error("mismatched seed acknowledgement");
+		}
+		return value;
+	}
+	/** Called synchronously before any other before-agent-start await. */
+	guard(ctx: ExtensionContext): boolean {
+		try {
+			const imported = this.imported(ctx);
+			if (imported?.seal) throw new Error("worker execution is sealed");
+			return true;
+		} catch (error) {
+			ctx.abort();
+			ctx.ui.notify(`IMPORT_FAILED: ${String(error)}`, "error");
+			return false;
+		}
+	}
+	async settled(ctx: ExtensionContext): Promise<void> {
+		const imported = this.imported(ctx);
+		if (!imported?.seal) return;
+		const leaf = ctx.sessionManager.getLeafId();
+		if (!leaf) throw new Error("IMPORT_FAILED: sealed session has no final leaf");
+		await this.exec(["unit", "terminal-ack", "--input", JSON.stringify({
+			execution: imported.execution, unitRef: imported.unitRef, digest: imported.digest,
+			sealEntryId: imported.seal.entryId, sessionLeafId: leaf,
+		})], ctx.cwd);
+	}
+}

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,12 +52,14 @@ 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]