@oisin-ee/pi-dogsled 0.17.0 → 0.18.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -11,13 +11,13 @@ Install the binary on each Herdr host. Use the same release tag in each command.
11
11
  Binary:
12
12
 
13
13
  ```sh
14
- mise use github:oisin-ee/dogsled@v0.17.0
14
+ mise use github:oisin-ee/dogsled@v0.18.0
15
15
  ```
16
16
 
17
17
  Pi (extension, tools, and skill), from npm or as part of `@oisin-ee/oisinpi`:
18
18
 
19
19
  ```sh
20
- pi install npm:@oisin-ee/pi-dogsled@0.17.0
20
+ pi install npm:@oisin-ee/pi-dogsled@0.18.0
21
21
  ```
22
22
 
23
23
  At session start the extension compares its version with `dogsled --version` and warns when they differ.
@@ -25,24 +25,24 @@ At session start the extension compares its version with `dogsled --version` and
25
25
  Claude Code (hooks, tools, and skill):
26
26
 
27
27
  ```sh
28
- claude plugin marketplace add oisin-ee/dogsled#v0.17.0
28
+ claude plugin marketplace add oisin-ee/dogsled#v0.18.0
29
29
  claude plugin install dogsled@dogsled
30
30
  ```
31
31
 
32
32
  Codex (hooks, tools, and skill):
33
33
 
34
34
  ```sh
35
- codex plugin marketplace add oisin-ee/dogsled --ref v0.17.0
35
+ codex plugin marketplace add oisin-ee/dogsled --ref v0.18.0
36
36
  codex plugin add dogsled@dogsled
37
37
  ```
38
38
 
39
39
  Codex requires review and trust before it runs plugin hooks. See the [Codex hooks documentation](https://developers.openai.com/codex/hooks#plugin-hooks).
40
40
  The [Codex CLI reference](https://developers.openai.com/codex/cli/reference#codex-plugin) describes plugin installation.
41
41
 
42
- Herdr (status-board popup):
42
+ Herdr (right-side work board):
43
43
 
44
44
  ```sh
45
- herdr plugin install oisin-ee/dogsled --ref v0.17.0 --yes
45
+ herdr plugin install oisin-ee/dogsled --ref v0.18.0 --yes
46
46
  ```
47
47
 
48
48
  Harness plugins use the binary on `PATH`. They do not install it or start host services.
@@ -140,17 +140,17 @@ An item records its host, pane, owner pane, creation time, closure time, and for
140
140
  `items --json` returns `{items,queue}`. `--owner` filters both collections.
141
141
  The service closes a job item after job completion, and any item after pane removal.
142
142
 
143
- 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:
143
+ `done` hands the task back to the owner. The child host captures the final reply, closes the pane and agent worktree, and keeps the branch. The owner receives the reply and lands the branch without a live child. The sweep remains a backstop.
144
144
 
145
- 1. reads its final reply from the transcript and keeps it in the item;
146
- 2. puts the reply in the owner's inbox (see [Inbox](#inbox));
147
- 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.
145
+ Call `done` during the final working turn, after committing changes. It refuses open children, queued tickets, dirty agent worktrees, and removal that loses content under the shared loss rule. Retaining the local branch protects unlanded commits.
148
146
 
149
- 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.
150
- A child that ends a turn without `done` stays open, and its reply tells the owner it waits for input.
147
+ Marks in `done.json` use the launch/item id, pane, and `agent_session.value`, not the terminal id. Legacy marks migrate without deletion. The first `idle` or `done` observation ends the marked turn, including after restore without a completion counter. Working, blocked, and unknown states never authorize closure.
151
148
 
152
- 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.
153
- 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.
149
+ New inbox work accepted during that same working turn cancels its mark. After that turn ends, the mark is terminal. Senders receive `<name> finished; start a new child for more work`.
150
+
151
+ A child without its own `done` stays open, including a child that asks a question or orchestrates other children. Automatic closure never closes the caller or a busy pane. Shared worktrees remain, and only the finished child pane closes. A last primary pane stays while closing it would close linked workspaces.
152
+
153
+ Closed children retain TO LAND rows: `<child>: branch <b> +N to land`. These rows come from durable items and branch observations, not live panes. Integration or branch deletion removes the row.
154
154
 
155
155
  `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.
156
156
  `dogsled read TARGET [--host H]` shows a child's or job's newest output and the captured final reply.
@@ -572,8 +572,8 @@ The caller is the harness's `HERDR_PANE_ID`. Pi registers the server from its ex
572
572
 
573
573
  The extension adds host status before each prompt, registers the tools, and draws:
574
574
 
575
- - **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.
576
- - **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.
575
+ - **The right-side board** shows cached quotas, agents, jobs, and todos when `HERDR_ENV=1` and `HERDR_SOCKET_PATH` accepts a connection. Pi opens or reuses the tab’s split and sets no above-editor widget. Without Herdr, the existing widget shows host meters, the current task, and work groups. Agent/job data refreshes every ten seconds. Compatible pi-todo snapshots update immediately in the widget.
576
+ - **Alt+W or `/work`** opens or reuses the Herdr split. Without Herdr, it expands or collapses the 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.
577
577
  - **`/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.
578
578
  - **The inbox reader** and a renderer that shows each record's kind, sender, and text, folded past twelve lines.
579
579
 
@@ -583,13 +583,26 @@ Todos follow the active Pi session branch. Agents and jobs follow the calling He
583
583
 
584
584
  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.
585
585
 
586
- The Herdr plugin keeps only the status-board popup:
586
+ The Herdr plugin opens the right-side work board:
587
587
 
588
588
  ```sh
589
- herdr plugin pane open --plugin dogsled --entrypoint board
589
+ dogsled board --open # open or reuse the caller’s tab split
590
+ dogsled board --side --owner "$HERDR_PANE_ID" # print once
591
+ herdr plugin pane open --plugin dogsled --entrypoint board --direction right --no-focus
590
592
  ```
591
593
 
592
- The popup runs `dogsled status --watch`. The pane-close release hooks and sidebar token configuration are removed.
594
+ The split runs `dogsled board --side --watch` and refreshes every ten seconds. `--owner` defaults to the opening pane from Herdr’s plugin context.
595
+ Quotas come only from `quota.json`; the board never calls a provider or reads credentials. The heading shows cache age and `STALE` after fifteen minutes.
596
+
597
+ Pi renders each new todo revision through pi-todo’s `display.createView(host).render(width)`. Dogsled never reads or copies task state.
598
+ The board publishes its width in the ledger; before that, Pi uses 48 columns. Resizing republishes the same provider view at the new width.
599
+ Pi atomically writes `{session, branch, revision, current, pane, width, lines}` to `todo-lines/<pane-hash>.json` in Dogsled’s state directory.
600
+ The service reads files for live agent panes into `todos.json`. Peers expose this presentation through `dogsled host todos --json`.
601
+ The board shows each agent’s current line and prints the owner’s full provider-rendered lines unchanged, including ANSI styles. Missing presentations show as unavailable.
602
+ Session shutdown and provider release remove the pane’s publication. `/dogsled` remains the interactive control panel in both display modes.
603
+
604
+ Herdr 0.9.5 creates a new pane on every plugin open. Dogsled keeps a small `boards/<tab-hash>.json` registry keyed by Herdr tab ID.
605
+ It stores the board pane and terminal IDs, verifies them against live panes before reuse, and removes a stale entry before opening another split.
593
606
  All three harness packages share `plugins/dogsled/skills/dogsled/SKILL.md`. It describes delegation, jobs, messages, and the queue.
594
607
 
595
608
  ## Build and development
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@oisin-ee/pi-dogsled",
3
- "version": "0.17.0",
3
+ "version": "0.18.0",
4
4
  "description": "Pi extension for dogsled: the board, the /dogsled panel, the inbox reader, and the dogsled tools. Needs the dogsled binary of the same version.",
5
5
  "type": "module",
6
6
  "license": "MIT",
package/pi/board.ts CHANGED
@@ -2,6 +2,20 @@
2
2
  // from `dogsled board --json`; this file only lays it out for a terminal width.
3
3
  import type { ThemeColor } from "@earendil-works/pi-coding-agent";
4
4
  import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
5
+ import { createConnection } from "node:net";
6
+
7
+ /** A stale socket path is not a running Herdr session. Never probe outside Herdr. */
8
+ export async function herdrAvailable(env: NodeJS.ProcessEnv = process.env): Promise<boolean> {
9
+ const path = env["HERDR_SOCKET_PATH"];
10
+ if (env["HERDR_ENV"] !== "1" || !path) return false;
11
+ return new Promise(resolve => {
12
+ const socket = createConnection(path);
13
+ const finish = (available: boolean) => { socket.destroy(); resolve(available); };
14
+ socket.once("connect", () => finish(true));
15
+ socket.once("error", () => finish(false));
16
+ socket.setTimeout(1_000, () => finish(false));
17
+ });
18
+ }
5
19
 
6
20
  export type Group = "to_land" | "attention" | "running" | "waiting";
7
21
 
package/pi/inbox.ts CHANGED
@@ -26,6 +26,8 @@ interface Claimed extends Delivered {
26
26
  }
27
27
 
28
28
  type Exec = (args: string[]) => Promise<string>;
29
+ export type WatchDirectory = (dir: string, listener: (event: string, name: string | null) => void) => FSWatcher;
30
+ const watchDirectory: WatchDirectory = (dir, listener) => watch(dir, { persistent: false }, listener);
29
31
 
30
32
  function parseClaimed(stdout: string): Claimed[] {
31
33
  const value: unknown = JSON.parse(stdout);
@@ -58,10 +60,12 @@ export class InboxReader {
58
60
 
59
61
  private readonly pi: Pick<ExtensionAPI, "sendMessage">;
60
62
  private readonly exec: Exec;
63
+ private readonly watchDirectory: WatchDirectory;
61
64
 
62
- constructor(pi: Pick<ExtensionAPI, "sendMessage">, exec: Exec) {
65
+ constructor(pi: Pick<ExtensionAPI, "sendMessage">, exec: Exec, watchInbox: WatchDirectory = watchDirectory) {
63
66
  this.pi = pi;
64
67
  this.exec = exec;
68
+ this.watchDirectory = watchInbox;
65
69
  }
66
70
 
67
71
  /** Register as this pane's reader, deliver what is waiting, and watch for more. */
@@ -74,7 +78,7 @@ export class InboxReader {
74
78
  if (typeof where.dir !== "string" || typeof where.file !== "string") throw new Error("dogsled inbox path returned no dir or file");
75
79
  const file = where.file;
76
80
  // Each write replaces the file, so the directory is watched, not the file.
77
- this.watcher = watch(where.dir, { persistent: false }, (_event, name) => {
81
+ this.watcher = this.watchDirectory(where.dir, (_event, name) => {
78
82
  if (name === file) void this.drain(ctx);
79
83
  });
80
84
  this.watcher.on("error", () => { this.watcher?.close(); this.watcher = undefined; });
package/pi/index.ts CHANGED
@@ -1,8 +1,8 @@
1
1
  import { readFileSync } from "node:fs";
2
2
  import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
3
3
  import { Box, Text, Key } from "@earendil-works/pi-tui";
4
- import { type Board, clean, parseBoard } from "./board.ts";
5
- import { WorkTodo } from "./work-todo.ts";
4
+ import { type Board, clean, parseBoard, herdrAvailable } from "./board.ts";
5
+ import { WorkTodo, TodoPublisher } from "./work-todo.ts";
6
6
  import { UnitBridge } from "./unit-bridge.ts";
7
7
  import { workBoard, workText, type WorkState } from "./work.ts";
8
8
  import { type Details, InboxReader, MESSAGE_TYPE } from "./inbox.ts";
@@ -74,10 +74,30 @@ export default function dogsled(pi: ExtensionAPI) {
74
74
  let workAbort: AbortController | undefined;
75
75
  let context: ExtensionContext | undefined;
76
76
  let requestWorkRender: (() => void) | undefined;
77
- const todos = new WorkTodo(pi.events, () => { if (context) draw(context); }, () => {
77
+ let sideDisplay = false;
78
+ let publicationFailure: string | undefined;
79
+ const publisher = new TodoPublisher(owner ?? "", error => context?.ui.notify(`Todo publication failed: ${String(error)}`, "error"));
80
+ const todos = new WorkTodo(pi.events, () => {
81
+ if (context) { publishTodos(context); draw(context); }
82
+ }, () => {
78
83
  if (context) void openWork(context, "todos").catch(error => context?.ui.notify(String(error), "error"));
79
84
  });
80
85
 
86
+ function publishTodos(ctx: ExtensionContext): void {
87
+ if (!owner) return;
88
+ try { publisher.publish(todos.current, ctx.ui.theme); }
89
+ catch (error) { ctx.ui.notify(`Todo publication failed: ${String(error)}`, "error"); }
90
+ }
91
+
92
+ async function publication(ctx: ExtensionContext): Promise<void> {
93
+ if (!owner) return;
94
+ const current = generation;
95
+ const location: unknown = JSON.parse(await exec(["board", "--todo-path", "--owner", owner, "--json"]));
96
+ if (current !== generation) return;
97
+ publisher.configure(location);
98
+ publishTodos(ctx);
99
+ }
100
+
81
101
  function state(): WorkState {
82
102
  return { board, todo: todos.current, error: failure ?? todos.error };
83
103
  }
@@ -97,6 +117,7 @@ export default function dogsled(pi: ExtensionAPI) {
97
117
  }
98
118
 
99
119
  async function openWork(ctx: ExtensionContext, tab: WorkTab): Promise<void> {
120
+ if (sideDisplay && owner) { await exec(["board", "--open", "--owner", owner, "--json"]); return; }
100
121
  if (ctx.mode !== "tui") { ctx.ui.notify(workText(state()), "info"); return; }
101
122
  if (panelOpen) return;
102
123
  workOpen = true;
@@ -136,7 +157,7 @@ export default function dogsled(pi: ExtensionAPI) {
136
157
  }
137
158
 
138
159
  function draw(ctx: ExtensionContext) {
139
- if (ctx.mode !== "tui") return;
160
+ if (ctx.mode !== "tui" || sideDisplay) return;
140
161
  workPanel?.update(workData());
141
162
  const data = state();
142
163
  if (panelOpen || (!workOpen && !data.board.rows.length && (!data.todo || data.todo.display.empty) && !data.error)) {
@@ -174,6 +195,13 @@ export default function dogsled(pi: ExtensionAPI) {
174
195
  await inbox.drain(ctx);
175
196
  try { await units.ready(ctx); await units.drain(ctx); } catch (error) { ctx.ui.notify(`Dogsled settlement delivery pending: ${String(error)}`, "warning"); }
176
197
  if (ctx.mode !== "tui") return;
198
+ try { await publication(ctx); publicationFailure = undefined; }
199
+ catch (error) {
200
+ const text = `Todo publication unavailable: ${String(error)}`;
201
+ if (text !== publicationFailure) ctx.ui.notify(text, "warning");
202
+ publicationFailure = text;
203
+ }
204
+ if (current !== generation || sideDisplay) return;
177
205
  try {
178
206
  const next = parseBoard(JSON.parse(await exec(["board", "--json"])));
179
207
  if (current !== generation) return;
@@ -197,9 +225,24 @@ export default function dogsled(pi: ExtensionAPI) {
197
225
  return refresh;
198
226
  }
199
227
 
228
+ /** Dogsled answers `skipped` for a pane it launched: a child keeps the widget path. */
229
+ async function openSide(ctx: ExtensionContext): Promise<boolean> {
230
+ if (!owner) return false;
231
+ try {
232
+ const opened: unknown = JSON.parse(await exec(["board", "--open", "--owner", owner, "--json"]));
233
+ return typeof opened === "object" && opened !== null && typeof (opened as Record<string, unknown>)["pane_id"] === "string";
234
+ } catch (error) {
235
+ ctx.ui.notify(`Dogsled side board unavailable: ${String(error)}`, "error");
236
+ return false;
237
+ }
238
+ }
239
+
200
240
  pi.on("session_start", async (event, ctx) => {
201
241
  units.start(event.reason);
202
- if (ctx.mode === "tui") ctx.ui.setWidget("dogsled", undefined);
242
+ const wasSide = sideDisplay;
243
+ sideDisplay = Boolean(owner) && ctx.mode === "tui" && await herdrAvailable() && await openSide(ctx);
244
+ if (ctx.mode === "tui" && (!sideDisplay || (!wasSide && requestWorkRender))) ctx.ui.setWidget("dogsled", undefined);
245
+ await publisher.clear();
203
246
  requestWorkRender = undefined;
204
247
  workPanel?.dispose();
205
248
  if (timer) clearInterval(timer);
@@ -227,7 +270,7 @@ export default function dogsled(pi: ExtensionAPI) {
227
270
  }
228
271
  await update(ctx);
229
272
  });
230
- pi.on("session_shutdown", (_event, ctx) => {
273
+ pi.on("session_shutdown", async (_event, ctx) => {
231
274
  units.stop();
232
275
  workPanel?.dispose();
233
276
  generation++;
@@ -241,8 +284,9 @@ export default function dogsled(pi: ExtensionAPI) {
241
284
  timer = undefined;
242
285
  inbox.stop();
243
286
  todos.stop();
287
+ await publisher.clear();
244
288
  context = undefined;
245
- if (ctx.mode === "tui") ctx.ui.setWidget("dogsled", undefined);
289
+ if (ctx.mode === "tui" && !sideDisplay) ctx.ui.setWidget("dogsled", undefined);
246
290
  });
247
291
  // A delivered message is in the transcript once Pi ends it: only then is it acknowledged.
248
292
  pi.on("message_end", async event => { await inbox.ended(event.message); });
package/pi/work-todo.ts CHANGED
@@ -1,5 +1,6 @@
1
1
  import type { ExtensionAPI, ExtensionContext, Theme } from "@earendil-works/pi-coding-agent";
2
2
  import { randomUUID } from "node:crypto";
3
+ import { rename, rm, writeFile } from "node:fs/promises";
3
4
 
4
5
  /** The provider owns rendering and state interpretation; this is an in-process capability. */
5
6
  export interface TodoViewHost {
@@ -33,6 +34,72 @@ export interface TodoSnapshot {
33
34
  display: TodoDisplay;
34
35
  }
35
36
 
37
+ export interface TodoLines {
38
+ session: string;
39
+ branch: string | null;
40
+ revision: number;
41
+ current: string;
42
+ pane: string;
43
+ width: number;
44
+ lines: string[];
45
+ }
46
+
47
+ /** Serialize only the provider's presentation. Never inspect its opaque state. */
48
+ export function renderTodoLines(next: TodoSnapshot, pane: string, host: TodoViewHost, width = 48): TodoLines {
49
+ const view = next.display.createView(host);
50
+ try {
51
+ const lines = view.render(width);
52
+ if (!Array.isArray(lines) || !lines.every(line => typeof line === "string")) throw new Error("Invalid todo render output");
53
+ return { session: next.session, branch: next.branch, revision: next.revision, current: next.display.current, pane, width, lines };
54
+ } finally { view.dispose(); }
55
+ }
56
+
57
+ /** Atomic per-pane publication into Dogsled's ledger. One ordered writer per Pi session. */
58
+ export class TodoPublisher {
59
+ private path: string | undefined;
60
+ private width = 48;
61
+ private height = 10_000;
62
+ private published: TodoSnapshot | undefined;
63
+ private queue = Promise.resolve();
64
+ private readonly pane: string;
65
+ private readonly failed: (error: unknown) => void;
66
+ constructor(pane: string, failed: (error: unknown) => void) { this.pane = pane; this.failed = failed; }
67
+
68
+ configure(value: unknown): void {
69
+ if (!record(value) || typeof value["path"] !== "string"
70
+ || !Number.isInteger(value["width"]) || Number(value["width"]) < 1 || Number(value["width"]) > 65535
71
+ || !Number.isInteger(value["height"]) || Number(value["height"]) < 1 || Number(value["height"]) > 10_000) throw new Error("Invalid todo publication path");
72
+ if (this.path !== value["path"] || this.width !== value["width"] || this.height !== value["height"]) this.published = undefined;
73
+ this.path = value["path"];
74
+ this.width = Number(value["width"]);
75
+ this.height = Number(value["height"]);
76
+ }
77
+
78
+ publish(next: TodoSnapshot | undefined, theme: TodoViewHost["theme"]): void {
79
+ const path = this.path;
80
+ if (!path || (next && next === this.published)) return;
81
+ // Render now, while this revision still owns the provider capability.
82
+ const payload = next ? renderTodoLines(next, this.pane, { theme, height: () => this.height, requestRender() {} }, this.width) : undefined;
83
+ this.published = next;
84
+ this.queue = this.queue.then(async () => {
85
+ if (!payload) { await rm(path, { force: true }); return; }
86
+ const temporary = `${path}.${randomUUID()}.tmp`;
87
+ try {
88
+ await writeFile(temporary, JSON.stringify(payload), { flag: "wx", mode: 0o600 });
89
+ await rename(temporary, path);
90
+ } finally { await rm(temporary, { force: true }); }
91
+ }).catch(error => { this.published = undefined; this.failed(error); });
92
+ }
93
+
94
+ async clear(): Promise<void> {
95
+ const path = this.path;
96
+ this.published = undefined;
97
+ this.queue = this.queue.then(async () => { if (path) await rm(path, { force: true }); }).catch(this.failed);
98
+ await this.queue;
99
+ }
100
+ async flushed(): Promise<void> { await this.queue; }
101
+ }
102
+
36
103
  type Bus = ExtensionAPI["events"];
37
104
  function record(value: unknown): value is Record<string, unknown> { return typeof value === "object" && value !== null; }
38
105
  function isDisplay(value: unknown): boolean {
@@ -52,12 +52,11 @@ dogsled inbox list
52
52
 
53
53
  ## Closing
54
54
 
55
- 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:
55
+ `done` means your work is finished: hand it back, release your resources, and end your agent. Call it during the final working turn, after committing changes. The child host captures your reply and closes your pane and agent worktree when the turn ends. Your branch stays for the owner to land. Closed children remain under TO LAND until integration or branch deletion.
56
56
 
57
- - a reader (no commits outside the default branch, clean tree) closes when that turn ends;
58
- - a writer closes once its branch has landed. Until then it shows under TO LAND: merge or drop the branch.
57
+ `done` refuses open children, queued tickets, dirty agent worktrees, and removal that loses content with the branch kept. New inbox work during the same working turn cancels the mark. After the turn ends, messages fail with `<name> finished; start a new child for more work`.
59
58
 
60
- 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.
59
+ Without its own `done`, a child stays open. Questions and orchestration do not authorize closure. Busy panes and the caller never close automatically. Shared worktrees stay. A primary pane stays if its closure would close linked workspaces.
61
60
 
62
61
  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:
63
62