@roodriigoooo/pi-docket 0.4.0

package/extensions/worker-commands.ts

@@ -0,0 +1,251 @@
+import { workerLaunchDetail, workerLaunchSubject, workerQuestions, workerShortLabel, workerSummaryName, type WorkerStatus } from "./background-work.js";
+import { readGitSnapshot } from "./git-context.js";
+import type { LoadedArtifactContext } from "./loaded-artifact-context.js";
+import type { ArtifactKind } from "./types.js";
+import type { WorkerKindRegistry, WorkerKind } from "./worker-kinds.js";
+import { workerProjectKey, type WorkerStore } from "./worker-store.js";
+
+export type WorkerCompletionCandidate = { value: string; label: string };
+
+type NotifyLevel = "info" | "warning" | "error";
+type DocketMessageKind = "list" | "success" | "action";
+
+type WorkerCommandsDeps = {
+	store: WorkerStore;
+	loadedArtifacts: Pick<LoadedArtifactContext, "loadSource" | "unloadSource">;
+	cwd: string;
+	projectRoot?: string;
+	parentSession?: string;
+	kinds: WorkerKindRegistry;
+	maxActive(): number;
+	captureTerminal(): boolean;
+	notify(text: string, level: NotifyLevel): void;
+	announce(subject: string, detail?: string, kind?: DocketMessageKind, docket?: { kind: ArtifactKind; title: string; subtitle?: string }, meta?: { workerId: string }): void;
+	emitText(text: string, kind: "list", heading: string): void;
+};
+
+export type WorkerCommands = {
+	spawn(task: string, options?: { worktree?: boolean; fresh?: boolean; as?: string; parentWorkerId?: string; depth?: number; layout?: "single" | "split-events"; captureTerminal?: boolean }): Promise<WorkerStatus | undefined>;
+	tell(ref: string, text: string): Promise<void>;
+	list(options?: { allProjects?: boolean }): Promise<void>;
+	listKinds(): Promise<void>;
+	delete(ref: string | undefined): Promise<void>;
+	respawn(target: string): Promise<void>;
+	load(ref: string | undefined): Promise<void>;
+	unload(ref: string): Promise<void>;
+	completionCandidates(): Promise<WorkerCompletionCandidate[]>;
+};
+
+export function workerAge(updatedAt: string): string {
+	const ageMs = Date.now() - Date.parse(updatedAt);
+	if (!Number.isFinite(ageMs) || ageMs < 0) return updatedAt;
+	const seconds = Math.round(ageMs / 1000);
+	if (seconds < 60) return `${seconds}s ago`;
+	const minutes = Math.round(seconds / 60);
+	if (minutes < 60) return `${minutes}m ago`;
+	const hours = Math.round(minutes / 60);
+	return `${hours}h ago`;
+}
+
+export async function workerCompletionCandidates(store: WorkerStore, options: { projectRoot?: string } = {}): Promise<WorkerCompletionCandidate[]> {
+	try {
+		const workers = await store.list(options);
+		return workers.slice(-10).reverse().map((w) => ({
+			value: workerShortLabel(w.index),
+			label: `${workerShortLabel(w.index)}  ${w.state}  ${workerSummaryName(w, 40)}`,
+		}));
+	} catch {
+		return [];
+	}
+}
+
+function formatWorkerTell(worker: WorkerStatus, text: string): string {
+	const questions = workerQuestions(worker);
+	if (questions.length === 0) return `Parent message: ${text}`;
+	const questionList = questions.map((question, index) => `${index + 1}) ${question.text}`).join(" ");
+	return `Parent message for ${questions.length} question${questions.length === 1 ? "" : "s"}: ${questionList} Message: ${text}`;
+}
+
+function formatWorkerList(workers: WorkerStatus[], options: { groupByProject?: boolean } = {}): string {
+	if (workers.length === 0) return "No Docket workers";
+	const lineFor = (w: WorkerStatus) => {
+		const label = workerShortLabel(w.index).padEnd(4);
+		const state = (w.state ?? "?").padEnd(8);
+		const kind = (w.kind ?? "default").padEnd(8);
+		const artifacts = `${w.artifactCount ?? "?"} artifacts`.padEnd(14);
+		const age = workerAge(w.updatedAt).padEnd(8);
+		const parentTag = w.parentWorkerId ? ` ↳w${workers.find((p) => p.id === w.parentWorkerId)?.index ?? "?"}` : "";
+		return `${label}  ${state}  ${kind}  ${artifacts}  ${age}  ${workerSummaryName(w, 40)}${parentTag}`;
+	};
+	if (!options.groupByProject) return workers.map(lineFor).join("\n");
+	const groups = new Map<string, WorkerStatus[]>();
+	for (const worker of workers) {
+		const key = workerProjectKey(worker);
+		groups.set(key, [...(groups.get(key) ?? []), worker]);
+	}
+	return [...groups.entries()].sort(([a], [b]) => a.localeCompare(b)).flatMap(([project, entries]) => [`project: ${project}`, ...entries.map(lineFor)]).join("\n");
+}
+
+function formatKindList(kinds: WorkerKind[]): string {
+	if (kinds.length === 0) return "No Docket worker kinds registered";
+	return kinds.map((k) => {
+		const ro = k.readOnly ? "ro" : "rw";
+		const seed = k.parentSeedPolicy === "none" ? "fresh" : "seeded";
+		const spawn = k.canSpawn.length ? `spawn:${k.canSpawn.join(",")}` : "no-spawn";
+		const src = `[${k.source}]`;
+		const desc = k.description ? ` — ${k.description}` : "";
+		return `${k.name.padEnd(12)} ${ro} ${seed} ${spawn} ${src}${desc}`;
+	}).join("\n");
+}
+
+export function createWorkerCommands(deps: WorkerCommandsDeps): WorkerCommands {
+	const loadWorker = async (worker: WorkerStatus): Promise<void> => {
+		const result = await deps.loadedArtifacts.loadSource({ kind: "worker", worker });
+		deps.announce(
+			`loaded ${result.slot.slot} · ${result.slot.artifacts.length} artifact${result.slot.artifacts.length === 1 ? "" : "s"}`,
+			`${workerSummaryName(worker)}\nattach: @${result.slot.slot}.<id>`,
+			"success",
+		);
+	};
+
+	return {
+		async spawn(task: string, options: { worktree?: boolean; fresh?: boolean; as?: string; parentWorkerId?: string; depth?: number; layout?: "single" | "split-events"; captureTerminal?: boolean } = {}): Promise<WorkerStatus | undefined> {
+			try {
+				const requestedName = options.as?.trim();
+				if (requestedName) {
+					const known = deps.kinds.names();
+					if (!known.includes(requestedName)) {
+						deps.notify(`Docket: unknown worker kind "${requestedName}". Try /docket kinds. Falling back to default.`, "warning");
+					}
+				}
+				const kind = deps.kinds.get(requestedName);
+				const max = deps.maxActive();
+				if (max > 0) {
+					const active = await deps.store.countActive();
+					if (active >= max) {
+						deps.notify(`Docket: fleet cap reached (${active}/${max} active). Resolve or delete a worker before spawning another.`, "error");
+						return undefined;
+					}
+				}
+				const git = readGitSnapshot(deps.cwd);
+				const seedSource = options.fresh === true || kind.parentSeedPolicy === "none" ? undefined : deps.parentSession;
+				const useWorktree = options.worktree === true || kind.defaultWorktree;
+				const worker = await deps.store.spawn({
+					task,
+					cwd: deps.cwd,
+					...(seedSource ? { parentSession: seedSource } : {}),
+					worktree: useWorktree,
+					...(options.fresh ? { fresh: true } : {}),
+					...(git ? { git } : {}),
+					kind: kind.name,
+					...(kind.canSpawn.length > 0 ? { canSpawn: kind.canSpawn } : {}),
+					...(options.parentWorkerId ? { parentWorkerId: options.parentWorkerId } : {}),
+					...(typeof options.depth === "number" ? { depth: options.depth } : {}),
+					layout: options.layout ?? kind.layout,
+					...(options.captureTerminal || deps.captureTerminal() ? { captureTerminal: true } : {}),
+				});
+				const now = Date.parse(worker.createdAt);
+				deps.announce(
+					workerLaunchSubject(worker, { now }),
+					workerLaunchDetail(worker, { now }),
+					"action",
+					undefined,
+					{ workerId: worker.id },
+				);
+				return worker;
+			} catch (err) {
+				deps.notify(`Docket spawn failed: ${String(err)}`, "error");
+				return undefined;
+			}
+		},
+		async tell(ref: string, text: string): Promise<void> {
+			const worker = await deps.store.find(ref);
+			if (!worker) {
+				deps.notify("Docket worker not found", "error");
+				return;
+			}
+			const sent = await deps.store.sendInput(worker.id, formatWorkerTell(worker, text));
+			if (sent) deps.announce(
+				`told ${workerShortLabel(worker.index)}`,
+				text,
+				"success",
+				{ kind: "prompt", title: `tell ${workerShortLabel(worker.index)}`, subtitle: workerSummaryName(worker) },
+			);
+			else deps.notify(`Docket could not send message to ${workerShortLabel(worker.index)}`, "error");
+		},
+		async list(options: { allProjects?: boolean } = {}): Promise<void> {
+			const projectRoot = options.allProjects ? undefined : deps.projectRoot;
+			deps.emitText(formatWorkerList(await deps.store.list({ ...(projectRoot ? { projectRoot } : {}) }), { groupByProject: options.allProjects === true }), "list", "docket · workers");
+		},
+		async listKinds(): Promise<void> {
+			deps.emitText(formatKindList(deps.kinds.list()), "list", "docket · worker kinds");
+		},
+		async delete(ref: string | undefined): Promise<void> {
+			if (!ref) {
+				deps.notify("Usage: /docket delete w<N>", "error");
+				return;
+			}
+			const worker = await deps.store.find(ref);
+			if (!worker) {
+				deps.notify("Docket worker not found", "error");
+				return;
+			}
+			deps.loadedArtifacts.unloadSource("worker", worker.id);
+			const purged = await deps.store.purge(worker.id, { cascade: true });
+			const childCount = Math.max(0, purged.length - 1);
+			const cascadeNote = childCount > 0 ? `\ncascade: purged ${childCount} child worker${childCount === 1 ? "" : "s"}` : "";
+			deps.announce(`worker ${workerShortLabel(worker.index)} killed`, `${workerSummaryName(worker)}\nid: ${worker.id}${worker.worktree ? `\nremoved workspace: ${worker.worktree.path}` : ""}${cascadeNote}`);
+		},
+		async respawn(target: string): Promise<void> {
+			const ALL = target.toLowerCase() === "all";
+			const candidates = ALL
+				? (await deps.store.list()).filter((w) => ["ended", "error", "failed"].includes(w.state))
+				: await (async () => {
+					const w = await deps.store.find(target);
+					return w ? [w] : [];
+				})();
+			if (candidates.length === 0) {
+				deps.notify(ALL ? "Docket: no relaunch-eligible workers" : "Docket worker not found", "warning");
+				return;
+			}
+			const ok: string[] = [];
+			const failed: { label: string; error: string }[] = [];
+			for (const worker of candidates) {
+				try {
+					const result = await deps.store.respawn(worker.id);
+					if (result) ok.push(workerShortLabel(result.index));
+					else failed.push({ label: workerShortLabel(worker.index), error: "no status" });
+				} catch (err) {
+					failed.push({ label: workerShortLabel(worker.index), error: String(err) });
+				}
+			}
+			if (ok.length > 0) deps.announce(`respawned ${ok.length} worker${ok.length === 1 ? "" : "s"}`, ok.join(", "), "success");
+			if (failed.length > 0) deps.notify(`Docket respawn failed for: ${failed.map((entry) => `${entry.label} (${entry.error})`).join(", ")}`, "error");
+		},
+		async load(ref: string | undefined): Promise<void> {
+			if (!ref) {
+				deps.notify("Usage: /docket load w<N>", "error");
+				return;
+			}
+			try {
+				const worker = await deps.store.find(ref);
+				if (!worker) {
+					deps.notify("Docket worker not found", "error");
+					return;
+				}
+				await loadWorker(worker);
+			} catch (err) {
+				deps.notify(`Docket load failed: ${String(err)}`, "error");
+			}
+		},
+		async unload(ref: string): Promise<void> {
+			const worker = await deps.store.find(ref);
+			const removed = worker ? deps.loadedArtifacts.unloadSource("worker", worker.id) : undefined;
+			if (removed) deps.announce(`unloaded ${removed.slot}`, worker ? workerSummaryName(worker) : undefined);
+			else deps.notify("Docket worker not loaded", "warning");
+		},
+		completionCandidates(): Promise<WorkerCompletionCandidate[]> {
+			return workerCompletionCandidates(deps.store, { ...(deps.projectRoot ? { projectRoot: deps.projectRoot } : {}) });
+		},
+	};
+}

package/extensions/worker-dock-cache.ts

@@ -0,0 +1,147 @@
+import fs from "node:fs/promises";
+import fsSync from "node:fs";
+import path from "node:path";
+import type { Artifact } from "./types.js";
+import type { WorkerStatus } from "./background-work.js";
+import { tailWorkerEvents, type WorkerEvent } from "./worker-events.js";
+
+export const DOCK_RECENT_EVENT_CAP = 16;
+
+type Entry = {
+	id: string;
+	statusMtime: number;
+	artifactsMtime: number;
+	status: WorkerStatus | undefined;
+	artifacts: Artifact[];
+	eventOffset: number;
+	recentEvents: WorkerEvent[];
+};
+
+export type WorkerSnapshot = {
+	workers: WorkerStatus[];
+	artifactsByWorker: Map<string, Artifact[]>;
+	/** Sticky ring of the last DOCK_RECENT_EVENT_CAP events per worker; safe to render. */
+	eventsByWorker: Map<string, WorkerEvent[]>;
+	/** Only events read this tick. Use for one-shot emit/subscribe; rendering should use eventsByWorker. */
+	newEventsByWorker: Map<string, WorkerEvent[]>;
+};
+
+async function safeStat(file: string): Promise<fsSync.Stats | undefined> {
+	try {
+		return await fs.stat(file);
+	} catch {
+		return undefined;
+	}
+}
+
+export class WorkerSnapshotCache {
+	private entries = new Map<string, Entry>();
+
+	constructor(private root: string) {}
+
+	async snapshot(): Promise<WorkerSnapshot> {
+		let names: string[];
+		try {
+			names = await fs.readdir(this.root);
+		} catch {
+			this.entries.clear();
+			return { workers: [], artifactsByWorker: new Map(), eventsByWorker: new Map(), newEventsByWorker: new Map() };
+		}
+		const active = new Set(names);
+		for (const id of [...this.entries.keys()]) if (!active.has(id)) this.entries.delete(id);
+
+		const workers: WorkerStatus[] = [];
+		const artifactsByWorker = new Map<string, Artifact[]>();
+		const eventsByWorker = new Map<string, WorkerEvent[]>();
+		const newEventsByWorker = new Map<string, WorkerEvent[]>();
+		await Promise.all(names.map(async (id) => {
+			const dir = path.join(this.root, id);
+			const statusFile = path.join(dir, "status.json");
+			const artifactsFile = path.join(dir, "artifacts.json");
+			const [statusStat, artifactsStat] = await Promise.all([safeStat(statusFile), safeStat(artifactsFile)]);
+			if (!statusStat) {
+				this.entries.delete(id);
+				return;
+			}
+			const existing = this.entries.get(id);
+			const entry: Entry = existing ?? { id, statusMtime: -1, artifactsMtime: -1, status: undefined, artifacts: [], eventOffset: 0, recentEvents: [] };
+			if (entry.statusMtime !== statusStat.mtimeMs) {
+				try {
+					entry.status = JSON.parse(await fs.readFile(statusFile, "utf8")) as WorkerStatus;
+				} catch {
+					entry.status = undefined;
+				}
+				entry.statusMtime = statusStat.mtimeMs;
+			}
+			if (artifactsStat) {
+				if (entry.artifactsMtime !== artifactsStat.mtimeMs) {
+					try {
+						entry.artifacts = JSON.parse(await fs.readFile(artifactsFile, "utf8")) as Artifact[];
+					} catch {
+						entry.artifacts = [];
+					}
+					entry.artifactsMtime = artifactsStat.mtimeMs;
+				}
+			} else {
+				entry.artifacts = [];
+				entry.artifactsMtime = -1;
+			}
+			const tail = await tailWorkerEvents(this.root, id, { offset: entry.eventOffset });
+			entry.eventOffset = tail.offset;
+			if (tail.rotated) entry.recentEvents = [];
+			if (tail.events.length) {
+				entry.recentEvents = [...entry.recentEvents, ...tail.events].slice(-DOCK_RECENT_EVENT_CAP);
+			}
+			this.entries.set(id, entry);
+			if (entry.status) {
+				workers.push(entry.status);
+				artifactsByWorker.set(entry.status.id, entry.artifacts);
+				if (entry.recentEvents.length) eventsByWorker.set(entry.status.id, entry.recentEvents);
+				if (tail.events.length) newEventsByWorker.set(entry.status.id, tail.events);
+			}
+		}));
+		workers.sort((a, b) => a.createdAt.localeCompare(b.createdAt));
+		return { workers, artifactsByWorker, eventsByWorker, newEventsByWorker };
+	}
+
+	invalidate(id?: string): void {
+		if (id) this.entries.delete(id);
+		else this.entries.clear();
+	}
+
+	size(): number {
+		return this.entries.size;
+	}
+}
+
+export type Unwatcher = () => void;
+
+export function watchWorkersRoot(
+	root: string,
+	onChange: () => void,
+	options: { fallbackMs?: number; debounceMs?: number } = {},
+): Unwatcher {
+	const debounceMs = options.debounceMs ?? 150;
+	const fallbackMs = options.fallbackMs ?? 3000;
+	let timer: NodeJS.Timeout | undefined;
+	const fire = (): void => {
+		if (timer) clearTimeout(timer);
+		timer = setTimeout(() => onChange(), debounceMs);
+		timer.unref?.();
+	};
+	let watcher: fsSync.FSWatcher | undefined;
+	try {
+		fsSync.mkdirSync(root, { recursive: true });
+		watcher = fsSync.watch(root, { recursive: true }, () => fire());
+	} catch {
+		// fall back to polling-only
+	}
+	const fallback = setInterval(fire, fallbackMs);
+	fallback.unref?.();
+	fire();
+	return () => {
+		watcher?.close();
+		clearInterval(fallback);
+		if (timer) clearTimeout(timer);
+	};
+}

package/extensions/worker-events.ts

@@ -0,0 +1,87 @@
+import fsSync from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+
+export const WORKER_EVENT_FILE = "events.ndjson";
+export const WORKER_EVENT_ROTATE_BYTES = 5 * 1024 * 1024;
+
+export type WorkerEventKind = "state" | "todo" | "tool" | "artifact" | "message";
+
+export type WorkerEvent = {
+	ts: number;
+	kind: WorkerEventKind;
+	payload: Record<string, unknown>;
+};
+
+export function workerEventFilePath(root: string, id: string): string {
+	return path.join(root, id, WORKER_EVENT_FILE);
+}
+
+function rotateIfNeeded(file: string): void {
+	try {
+		const stat = fsSync.statSync(file);
+		if (stat.size > WORKER_EVENT_ROTATE_BYTES) {
+			const rotated = `${file}.1`;
+			try {
+				fsSync.rmSync(rotated, { force: true });
+			} catch {
+				// best-effort
+			}
+			fsSync.renameSync(file, rotated);
+		}
+	} catch {
+		// file may not exist yet
+	}
+}
+
+export function appendWorkerEventSync(root: string, id: string, event: { kind: WorkerEventKind; payload: Record<string, unknown>; ts?: number }): void {
+	const file = workerEventFilePath(root, id);
+	try {
+		fsSync.mkdirSync(path.dirname(file), { recursive: true });
+		rotateIfNeeded(file);
+		const payload: WorkerEvent = { ts: event.ts ?? Date.now(), kind: event.kind, payload: event.payload };
+		fsSync.appendFileSync(file, `${JSON.stringify(payload)}\n`, "utf8");
+	} catch {
+		// best-effort: never crash the worker because of event logging
+	}
+}
+
+export type WorkerEventTailerState = { offset: number };
+
+export type TailResult = { events: WorkerEvent[]; rotated: boolean; offset: number };
+
+export async function tailWorkerEvents(root: string, id: string, state: WorkerEventTailerState): Promise<TailResult> {
+	const file = workerEventFilePath(root, id);
+	let stat: fsSync.Stats;
+	try {
+		stat = await fs.stat(file);
+	} catch {
+		return { events: [], rotated: false, offset: state.offset };
+	}
+	let offset = state.offset;
+	let rotated = false;
+	if (stat.size < offset) {
+		offset = 0;
+		rotated = true;
+	}
+	if (stat.size === offset) return { events: [], rotated, offset };
+	const handle = await fs.open(file, "r");
+	try {
+		const buf = Buffer.alloc(stat.size - offset);
+		await handle.read(buf, 0, buf.length, offset);
+		const chunk = buf.toString("utf8");
+		const events: WorkerEvent[] = [];
+		for (const line of chunk.split("\n")) {
+			const trimmed = line.trim();
+			if (!trimmed) continue;
+			try {
+				events.push(JSON.parse(trimmed) as WorkerEvent);
+			} catch {
+				// drop malformed line
+			}
+		}
+		return { events, rotated, offset: stat.size };
+	} finally {
+		await handle.close();
+	}
+}

package/extensions/worker-eviction.ts

@@ -0,0 +1,55 @@
+import type { WorkerStatus } from "./background-work.js";
+
+/**
+ * States that count as "the worker is done". Auto-hide and auto-prune only
+ * apply to these; in-progress, waiting, ready, and failed workers stay
+ * visible so the user can still act on them.
+ */
+const TERMINAL_DOCK_STATES = new Set<WorkerStatus["state"]>(["ended"]);
+
+function workerAgeMs(worker: WorkerStatus, now: number): number {
+	const ts = Date.parse(worker.updatedAt);
+	if (!Number.isFinite(ts)) return 0;
+	return Math.max(0, now - ts);
+}
+
+export type EvictionConfig = {
+	dockIdleHideMinutes?: number;
+	pruneAfterHours?: number;
+};
+
+export function dockIdleHideMs(config: EvictionConfig | undefined): number {
+	const minutes = config?.dockIdleHideMinutes;
+	if (typeof minutes !== "number" || !Number.isFinite(minutes) || minutes <= 0) return 0;
+	return minutes * 60_000;
+}
+
+export function pruneAfterMs(config: EvictionConfig | undefined): number {
+	const hours = config?.pruneAfterHours;
+	if (typeof hours !== "number" || !Number.isFinite(hours) || hours <= 0) return 0;
+	return hours * 3_600_000;
+}
+
+export function isDockIdleEvictable(worker: WorkerStatus, now: number, idleHideMs: number): boolean {
+	if (idleHideMs <= 0) return false;
+	if (!TERMINAL_DOCK_STATES.has(worker.state)) return false;
+	return workerAgeMs(worker, now) >= idleHideMs;
+}
+
+export function shouldPruneWorker(worker: WorkerStatus, now: number, pruneMs: number): boolean {
+	if (pruneMs <= 0) return false;
+	if (!TERMINAL_DOCK_STATES.has(worker.state)) return false;
+	return workerAgeMs(worker, now) >= pruneMs;
+}
+
+export function selectEvictableWorkerIds(workers: WorkerStatus[], now: number, idleHideMs: number): Set<string> {
+	const out = new Set<string>();
+	for (const worker of workers) {
+		if (isDockIdleEvictable(worker, now, idleHideMs)) out.add(worker.id);
+	}
+	return out;
+}
+
+export function selectPrunableWorkers(workers: WorkerStatus[], now: number, pruneMs: number): WorkerStatus[] {
+	return workers.filter((worker) => shouldPruneWorker(worker, now, pruneMs));
+}

package/extensions/worker-guardrails.md

@@ -0,0 +1,125 @@
+# Docket worker protocol
+
+You are a Docket worker: a background Pi session spawned by a parent session to investigate or implement one focused task. The parent reviews your output and decides what to act on.
+
+## Source of truth
+
+- Your task lives in `task.md` inside your worker directory. Read it first.
+- Your artifacts (commands, file reads/edits, code blocks, responses) are snapshotted automatically to `artifacts.json`. You do not need to copy them anywhere.
+- The parent reads your `status.json` on a heartbeat. Status transitions happen only through the protocol tools below.
+
+## Default posture
+
+- **Read-only by default.** Do not edit files unless the task explicitly asks for edits. Reading, grepping, listing, running non-mutating commands, and reasoning are always fine.
+- If the task does ask for edits, prefer minimal, scoped changes. Summarize changed files and likely conflict risks in your final `docket_done` call.
+- You run in a worker workspace seeded from the parent's current repo state. If the task asks for adoptable output, edit the intended project files in that workspace; the parent reviews and promotes the whole change set. Do not hide adoptable work in scratch files.
+- Never push, force-push, or run destructive git operations (`reset --hard`, `clean -fd`, `checkout .`) without an explicit instruction in `task.md`.
+
+## Shared tmux session
+
+- You are running as one window inside a tmux session named `docket-workers`. Sibling workers are other windows in the same session. This is deliberate: one tmux server hosts the fleet so the parent's dock stays cheap.
+- **Never invoke `tmux` directly.** Do not run `tmux kill-server`, `tmux kill-session -t docket-workers`, `tmux kill-window -t docket-workers:wN`, or any other write-side tmux command. `kill-server` ends every worker. `kill-session` on the shared session ends every worker. The parent owns this lifecycle.
+- Read-side tmux inspection (`tmux list-windows`, `tmux display-message -p`) is fine but rarely useful; the parent already surfaces what you would learn from it.
+- If you genuinely think a tmux operation is required, stop and call `docket_wait` to ask the parent first.
+
+## Required protocol tools
+
+You have four tools the parent uses to track you. Calling them is part of doing the task, not optional ceremony. Do not write `/docket wait`, `/docket done`, or `/docket fail` as bash commands — those are intercepted as a safety net, but the tool path is the contract.
+
+### `docket_todos` — publish a small ordered checklist
+
+**Call when:** the task is multi-step (more than ~2 distinct moves) and a parent would benefit from seeing your plan.
+
+**How:**
+- Keep it short: 3–8 items, ordered.
+- States: `pending`, `in_progress`, `completed`.
+- Replace the full list on each update; do not append.
+- Re-publish whenever you complete an item or change the plan.
+
+**Do not** use this as a durable task manager. It is a visibility board for the parent.
+
+### `docket_wait` — ask the parent for input and pause
+
+**Call when ANY of these are true:**
+- The task is ambiguous in a way that meaningfully changes your output (path choice, format choice, scope, naming).
+- You hit a credentials, secret, or auth wall and cannot proceed.
+- You are about to make an irreversible or expensive call (destructive command, paid API, schema migration) that was not explicitly authorized in `task.md`.
+- You believe the task description contains a contradiction or a wrong assumption.
+- You are about to abandon the task or change its scope.
+
+**Heuristic:** if a reasonable engineer would stop and ask, call `docket_wait`. Do not assume. A short, concrete question costs the parent seconds. A wrong assumption costs them a re-run.
+
+For vague search/discovery tasks, do cheap discovery before asking: at most ~5 read-only operations or ~60 seconds. If that finds no relevant signal, call `docket_wait` instead of `docket_done`. Example: `find the bear...` plus no repo hits should ask what bear/scope the parent means.
+
+**How:** one concise question per call. If multiple questions, list them as `1) … 2) …` inside one call. Then stop and wait. Do not continue working speculatively after calling `docket_wait`.
+
+When the decision has discrete answers, pass them as `options` (2–4 concrete choices) and `recommend` the one you would pick — the parent then gets a one-keystroke card with your proposed branches instead of a freeform reply, and the choice is sent back to you verbatim. When the action is irreversible or unauthorized, set `risk` to a one-line statement of the stakes (e.g. `drops the sessions table`). These fields are status-only and cost the parent zero tokens to review.
+
+**Do not** call `docket_wait` for trivial style/aesthetic preferences you can answer reasonably yourself.
+
+### `docket_done` — mark output ready for parent review
+
+**Call when:**
+- The task is complete, OR
+- You produced findings or recommendations that are useful even though the task is not fully done (e.g. investigation tasks that surface dead ends).
+
+**How:**
+- Set `outcome` to one of `completed`, `findings`, `proposal`, or `no_evidence`.
+- Set `scopeConfidence` to `clear` only when the task had enough scope to finish without parent input; otherwise use `unclear` and prefer `docket_wait`.
+- Include short `evidence` entries: searched paths, commands run, files read/changed, artifact refs, or concrete observations.
+- One- or two-sentence `summary` of what you produced. Plain prose.
+- Put action bullets in `recommended` (or under a `Recommended:` heading in `summary` for compatibility). Keep each bullet short, action-oriented, and self-contained.
+- Do not paste full file contents or large code blocks into `summary`; those already live in your artifacts. Reference them by what they are ("see edited src/auth.ts") if needed.
+
+**Example `docket_done.summary`:**
+
+```
+Reviewed README for command accuracy and onboarding.
+Recommended:
+- Sync README commands with current behavior
+- Add a short quickstart near the top
+- Add a compact workflow-oriented table of contents
+```
+
+**Heuristic:** if you would have nothing useful to hand a colleague reviewing your work, you are not done — keep investigating or call `docket_wait`.
+
+If `outcome` is `no_evidence` and the original task was vague, do not mark done. Ask for scope with `docket_wait`. `no_evidence` is ready only when the task scope was clear (for example, "find bear references in this repo").
+
+### `docket_fail` — mark cannot-continue
+
+**Call when:**
+- You hit a blocker that `docket_wait` cannot resolve (environment missing, permissions, network).
+- The task is impossible as stated and you have no useful partial output.
+- Tools you need are not available and no reasonable substitute exists.
+
+**How:** one-sentence reason. Be specific: `Migration command exited 1: missing DATABASE_URL` is useful; `failed` is not.
+
+**Do not** call `docket_fail` when you have partial useful findings. Use `docket_done` with a summary that explicitly says what is done vs blocked.
+
+## Choosing between `docket_wait`, `docket_done`, and `docket_fail`
+
+| Situation | Tool |
+|---|---|
+| Need parent input to proceed correctly | `docket_wait` |
+| Done, output is useful | `docket_done` |
+| Done partially, the partial output is still useful | `docket_done` (note what is partial) |
+| Cannot continue, nothing useful to hand back | `docket_fail` |
+| Hit a tool/permission wall, parent could fix it | `docket_wait` first; `docket_fail` only if the wall is structural |
+
+## Avoiding common drift
+
+- Do not finish the task silently. Always end with `docket_done` or `docket_fail`. If you end a turn without calling any protocol tool, Docket marks you `idle` and sends you a one-time reminder. After that the parent has to decide manually whether you are done; ambiguity hurts the loop.
+- Do not call `docket_done` then keep working. The parent treats `docket_done` as a checkpoint; further output may be missed.
+- Do not embed protocol questions in artifact text ("By the way, should I also do X?"). The parent reads `status.json`, not free text. Use `docket_wait`.
+- Do not run `/docket wait`, `/docket done`, `/docket fail` as bash. Use the tools.
+- If you publish `docket_todos`, complete or remove items before calling `docket_done`. The parent sees a `ready / open todos` warning when you mark done with open items.
+
+## Parent visibility recap
+
+The parent sees a card for you in their inbox:
+- **Outcome** — your `docket_done.summary` (or `docket_wait` question, or `docket_fail` reason).
+- **Recommendations** — bullets parsed from your summary's `Recommended:` block.
+- **Useful references** — your artifacts (responses, code, files, commands) by `@<your-label>.<id>`.
+- **Progress** — your `docket_todos` board.
+
+The cleaner your protocol calls, the cleaner the parent's decision card. That is the whole loop.