dsh-report-ledger 0.1.0 → 0.2.0

package/lib/index.js

@@ -1,8 +1,10 @@
 import { createRequire } from "node:module";
 import { randomBytes, randomUUID } from "node:crypto";
-import { appendFile, mkdir, readFile, readdir, rename, writeFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { appendFile, mkdir, readFile, readdir, rename, unlink, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
-import { join } from "node:path";
+import { basename, dirname, join, normalize, resolve } from "node:path";
+import { execFile } from "node:child_process";
 import { defineTool } from "@deepseek-ai/dsh-tools";
 //#region \0rolldown/runtime.js
 var __commonJSMin = (cb, mod) => () => (mod || (cb((mod = { exports: {} }).exports, mod), cb = null), mod.exports);
@@ -149,10 +151,16 @@ const PROTOCOL = [
 	"- report_list —— 只列缩略；用 session 过滤看某位同伴相关的全部汇报，用 task 把同一次协作跨会话拉到一起（部分匹配、不区分大小写）。",
 	"- report_ack —— 回执：确认已收到并处理，让发送方看到闭环（事情仍在进行时用它）。",
 	"- report_amend —— 修正：改错的主题／任务标签／产物，或更正正文。**只有发起者或共写者**能改；正文默认是**追加**一段更正，明确要求（replace_body）才会整段替换，两种都会在传递路径里留下记录。",
-	"- report_close —— 结案：事情做完了才用它，且**只有发起者或共写者**能关；之后任何贡献／主送／抄送／转呈都会自动重开并记录。",
+	"- report_close —— 结案：事情做完了才用它，且**只有发起者或共写者**能关；之后任何贡献／主送／抄送／转呈都会自动重开并记录。结案同时**释放**它持有的工作区（见下）。",
+	"- report_release —— 交还工作区：工作做完了但对话没结束、想让出检出时用它。检出原样留在磁盘上，结束的只是\"占用\"。",
+	"- report_lease —— 认领一个**已存在**的检出（人手建的、上一份汇报留下的、或你要接手的）：与 report_release 互为反向。分支从检出本身读出，所以只有想强制校验时才传 branch。",
 	"- peer_list —— 列出你能对话的代理（上级、下属、兄弟、你开启的同伴、账本里有往来的联系人），并标注谁此刻在线。",
 	"- peer_start —— 开启一个**独立同伴会话**（不是下属）：它有自己的生命周期、比你活得更久；任务会作为一份汇报交给它。",
 	"",
+	"工作区（若本部署启用）：peer_start / report_author 加 worktree:true，会为该汇报分配一个**独立的 git 检出**，分支名形如 dsh/R-0007-<主题>。",
+	"独立的只有**工作目录与索引**；config、hooks、对象库、以及机器上一切检出之外的东西都是**共享**的——装一个 hook 或改一项配置，会影响所有检出里每一次提交。",
+	"一个分支同一时刻只能被一个检出占用，所以它同时也是一把锁：认领已有检出用 report_lease，交还用 report_release，结案会自动交还。被占用时会明确告诉你占用者是谁。",
+	"",
 	"五条行为约定：",
 	"1. 收件方不在线不是错误。投递由账本持有，等该会话重新驻留时自动送达；不要因为对方此刻不在就放弃交接、或改为自己扛下。",
 	"2. 传递路径（含每一份抄送与副本）由账本自动记录，不需要你手工维护——但每一步都必须经工具完成，绕过工具的口信不会进入路径。",
@@ -6788,7 +6796,7 @@ var require_public_api = /* @__PURE__ */ __commonJSMin(((exports) => {
 	exports.stringify = stringify;
 }));
 //#endregion
-//#region src/report/frontmatter.ts
+//#region src/report/types.ts
 var import_dist = (/* @__PURE__ */ __commonJSMin(((exports) => {
 	var composer = require_composer();
 	var Document = require_Document();
@@ -6835,14 +6843,58 @@ var import_dist = (/* @__PURE__ */ __commonJSMin(((exports) => {
 	exports.visit = visit.visit;
 	exports.visitAsync = visit.visitAsync;
 })))();
-/** The front-matter fence. */
-const FENCE = "---";
-const STATUSES = [
+/**
+* The report model.
+*
+* A report is the plugin's first-class interaction primitive between agents. It
+* is deliberately two-layered:
+*
+*  - the FRONT MATTER is the digest — a bounded flat mapping that can enter a
+*    model context, an index, or a timeline card without dragging the body in;
+*  - the BODY is the detail, stored out of context and read on demand.
+*
+* The transfer path is a third, append-only stream (see {@link RouteHop}): every
+* hop — authoring, contribution, send, delivery, CC, forwarding, copying, read,
+* acknowledgement — is recorded with its actor and time, so the complete route
+* including every copy survives independently of the report text.
+*
+* @module dsh-report-ledger/report/types
+*/
+/**
+* Every report status, as both the runtime list and the source of
+* {@link ReportStatus}.
+*
+* A union type and a validator array are two spellings of one fact, and two
+* spellings drift. The parser falls back to `open` for anything it does not
+* recognize, so a status that existed in the type but not in the array would
+* quietly rewrite itself on the next read.
+*/
+const REPORT_STATUSES = [
 	"open",
 	"acked",
 	"closed"
 ];
-const ACTIONS = [
+/**
+* One recorded hop in a report's transfer path.
+*
+* `authored` and `contributed` establish co-authorship; `sent`/`delivered` are
+* the addressed hand-off and its arrival; `cc` is a quiet copy; `forwarded` and
+* `copied` are onward transfer and duplication; `read`/`acked` close the loop for
+* one reader; `leased`/`released` bracket a claim on a working tree, and
+* `reclaimed` records that the ledger cleared a checkout away — whether to stay
+* within its retained budget or because the owner asked for it at closing time;
+* `amended` records a correction to the digest or the body; `closed` concludes
+* the matter, and `reopened` records that fresh activity brought it back to life.
+*
+* Declared as a value and derived into a type on purpose. The parser validates
+* each record against this list and **drops** one it does not recognize, so a
+* union that named an action this array omitted would lose those hops from the
+* audit trail without a word — the single failure a ledger must not have.
+* Deriving the type from the value makes that drift impossible rather than
+* merely unlikely; it happened once already, when `leased` and `released`
+* reached the union before the array.
+*/
+const HOP_ACTIONS = [
 	"authored",
 	"contributed",
 	"sent",
@@ -6852,10 +6904,31 @@ const ACTIONS = [
 	"copied",
 	"read",
 	"acked",
+	"leased",
+	"released",
+	"reclaimed",
 	"amended",
 	"closed",
 	"reopened"
 ];
+//#endregion
+//#region src/report/frontmatter.ts
+/**
+* The report file codec: YAML front matter plus a Markdown body.
+*
+* The format deliberately mirrors what this harness already uses for its own
+* documents (skills, package READMEs): an opening `---` line, a flat YAML
+* mapping, a closing `---` line, then free text. The parser below is a
+* reimplementation of the shipped skills parser
+* (`@deepseek-ai/dsh-skill-filesystem`, whose `parseFrontmatter` is module
+* private and not re-exported), tuned for the report schema: it tolerates a
+* hand-edited ledger by normalizing whatever it finds instead of throwing, so a
+* human can correct a report file without breaking the ledger.
+*
+* @module dsh-report-ledger/report/frontmatter
+*/
+/** The front-matter fence. */
+const FENCE = "---";
 /**
 * Split a document into its YAML front matter and body.
 *
@@ -6921,6 +6994,33 @@ function time(value, fallback) {
 	return parsed === void 0 || parsed < 0 ? fallback : parsed;
 }
 /**
+* Read a working-tree binding, tolerating the hand-edited short form.
+*
+* A human who wants to point a report at a checkout should be able to write
+* `worktree: /path/to/tree` and have it mean what it looks like, so a bare
+* scalar is normalized to a path-only binding. A mapping with no usable path is
+* dropped whole rather than half-read: a binding with a branch but no path would
+* claim a branch the ledger cannot locate, which is worse than no binding.
+* @param value - the raw front-matter value.
+* @returns the binding, or `undefined` when there is no usable path.
+*/
+function toWorktree(value) {
+	if (value === void 0 || value === null) return void 0;
+	const record = typeof value === "object" && !Array.isArray(value) ? value : { path: value };
+	const path = str$2(record.path);
+	if (path === void 0) return void 0;
+	const branch = str$2(record.branch);
+	const head = str$2(record.head);
+	const repo = str$2(record.repo);
+	return {
+		path,
+		...branch === void 0 ? {} : { branch },
+		...head === void 0 ? {} : { head },
+		...repo === void 0 ? {} : { repo },
+		...typeof record.allocated === "boolean" ? { allocated: record.allocated } : {}
+	};
+}
+/**
 * Normalize a raw front-matter mapping into the report schema.
 *
 * Every field is optional on the way in: a missing recipient list becomes empty,
@@ -6933,15 +7033,16 @@ function toFrontMatter(data) {
 	const report = str$2(data.report) ?? str$2(data.id);
 	if (report === void 0) return void 0;
 	const statusText = str$2(data.status);
-	const status = STATUSES.find((candidate) => candidate === statusText) ?? "open";
+	const status = REPORT_STATUSES.find((candidate) => candidate === statusText) ?? "open";
 	const created = time(data.created, 0);
 	const updated = time(data.updated, created);
+	const worktree = toWorktree(data.worktree);
 	const lastRaw = data.last;
 	let last;
 	if (lastRaw !== null && typeof lastRaw === "object" && !Array.isArray(lastRaw)) {
 		const record = lastRaw;
 		const actionText = str$2(record.action);
-		const action = ACTIONS.find((candidate) => candidate === actionText);
+		const action = HOP_ACTIONS.find((candidate) => candidate === actionText);
 		const actor = str$2(record.actor);
 		if (action !== void 0 && actor !== void 0) last = {
 			at: time(record.at, updated),
@@ -6963,6 +7064,7 @@ function toFrontMatter(data) {
 		...str$2(data.parent) === void 0 ? {} : { parent: str$2(data.parent) },
 		children: strList(data.children),
 		...str$2(data.task) === void 0 ? {} : { task: str$2(data.task) },
+		...worktree === void 0 ? {} : { worktree },
 		artifacts: strList(data.artifacts),
 		hops: num(data.hops) ?? 0,
 		...last === void 0 ? {} : { last },
@@ -7008,6 +7110,13 @@ function frontMatterYaml(front) {
 	if (front.parent !== void 0) ordered.parent = front.parent;
 	ordered.children = [...front.children];
 	if (front.task !== void 0) ordered.task = front.task;
+	if (front.worktree !== void 0) ordered.worktree = {
+		path: front.worktree.path,
+		...front.worktree.branch === void 0 ? {} : { branch: front.worktree.branch },
+		...front.worktree.head === void 0 ? {} : { head: front.worktree.head },
+		...front.worktree.repo === void 0 ? {} : { repo: front.worktree.repo },
+		...front.worktree.allocated === void 0 ? {} : { allocated: front.worktree.allocated }
+	};
 	ordered.artifacts = [...front.artifacts];
 	ordered.hops = front.hops;
 	if (front.last !== void 0) ordered.last = {
@@ -7051,7 +7160,7 @@ function parseHop(raw) {
 	if (value === null || typeof value !== "object" || Array.isArray(value)) return void 0;
 	const record = value;
 	const actionText = str$2(record.action);
-	const action = ACTIONS.find((candidate) => candidate === actionText);
+	const action = HOP_ACTIONS.find((candidate) => candidate === actionText);
 	const actor = str$2(record.actor);
 	if (action === void 0 || actor === void 0) return void 0;
 	const from = str$2(record.from);
@@ -7280,6 +7389,793 @@ async function listReports() {
 	digests.sort((left, right) => right.updated - left.updated || right.report.localeCompare(left.report));
 	return digests;
 }
+/**
+* Whether a report document exists on disk.
+* @param id - report identifier.
+* @returns true when the document exists.
+*/
+function reportExists(id) {
+	return isValidReportId(id) && existsSync(reportPath(id));
+}
+/**
+* Give back an id that was claimed but never became a report.
+*
+* {@link allocateId} claims a name by creating an empty document, which is what
+* makes a concurrent claim lose cleanly. When the work that needed the id then
+* fails — a working tree that could not be created, a peer that never started —
+* the claim would otherwise leave an empty file behind forever, burning the
+* number and showing up in no listing.
+*
+* Only an **empty** document is removed. A report with any content is kept, so a
+* misuse of this function can cost at most a placeholder, never a record.
+* @param id - the claimed identifier.
+* @returns true when an empty claim was removed.
+*/
+async function discardUnwrittenId(id) {
+	if (!isValidReportId(id)) return false;
+	const path = reportPath(id);
+	try {
+		if (await readFile(path, "utf8") !== "") return false;
+	} catch {
+		return false;
+	}
+	try {
+		await unlink(path);
+		return true;
+	} catch {
+		return false;
+	}
+}
+//#endregion
+//#region src/report/worktree.ts
+/**
+* Git worktree adapter.
+*
+* The ledger records *intent*; git records *reality*. This module is the whole
+* of the second half: it shells out to `git`, reads `git worktree list`, and
+* decides nothing. Every policy question — which report may hold a branch, when
+* a lease may be reclaimed, what to do when the two layers disagree — belongs to
+* the service layer, because answering it needs the ledger. This module must
+* stay usable and testable without one.
+*
+* Four deliberate choices:
+*
+*  - **Shell out, never reimplement.** Git's occupancy check, its refusal to
+*    remove an unclean tree, and its `repair` are the authority. A weaker
+*    reimplementation in TypeScript would be a second source of truth about the
+*    same bytes, which is the exact failure this plugin exists to avoid.
+*  - **No `--force`, anywhere.** Neither {@link addWorktree} nor
+*    {@link removeWorktree} exposes a force flag, so no caller can acquire the
+*    ability to discard uncommitted work or to claim a branch git says is taken.
+*    A safeguard can only be overridden by a human running git, deliberately.
+*  - **`--porcelain -z` for parsing.** The non-`-z` form escapes unusual
+*    characters and quotes paths containing them, so a parser for it must
+*    reimplement git's C-style quoting. The `-z` form emits raw NUL-separated
+*    fields, which makes parsing a split rather than an unescape.
+*  - **Paths stay native, comparison normalizes.** Git prints forward slashes
+*    even on Windows while the harness hands us backslashes. Rather than pick a
+*    dialect everywhere, stored paths keep the form the OS uses and
+*    {@link compareKey} is the single place that decides when two spellings name
+*    one file.
+*
+* @module dsh-report-ledger/report/worktree
+*/
+/** Directory name, under a repository's parent, that holds ledger-allocated worktrees. */
+const WORKTREE_DIR = ".dsh-worktrees";
+/** Default timeout for one git invocation. */
+const GIT_TIMEOUT_MS = 3e4;
+/** Exit status used for a failure that never reached git (a missing binary). */
+const NOT_EXECUTED = -1;
+/**
+* Recognized refusals, most specific first.
+*
+* Every pattern is copied from a message observed from git 2.49 on Windows.
+* Matching on prose is brittle by nature, so the classifier exists only to let
+* the caller choose a *remedy*; the raw stderr is always passed through
+* unchanged, and `unknown` is a correct answer rather than a failure.
+*
+* Order carries meaning. `a branch named 'x' already exists` and `'<path>'
+* already exists` are different problems with different remedies — reuse or
+* rename the branch, versus choose another directory — and git words both with
+* "already exists", so the branch form has to be recognized before the generic
+* one or every name collision looks like a full directory.
+*/
+const REFUSALS = [
+	["branch-in-use", /is already used by worktree at/i],
+	["branch-exists", /a branch named .* already exists/i],
+	["missing-but-registered", /is a missing but already registered worktree/i],
+	["main-working-tree", /is a main working tree|cannot be locked or unlocked/i],
+	["locked", /cannot remove a locked working tree/i],
+	["unclean", /contains modified or untracked files/i],
+	["path-exists", /already exists/i]
+];
+/**
+* Run one git command and capture its result without throwing.
+*
+* The ledger treats a git refusal as information, not as an exception: "this
+* branch is taken" is a normal answer that has to reach a model as a sentence.
+* So this returns the exit status instead of rejecting, and a binary that cannot
+* be run at all is reported the same way rather than as a crash.
+* @param cwd - directory to run in.
+* @param args - arguments after the program name.
+* @returns the exit status and both streams.
+*/
+async function runGit(cwd, args) {
+	return await new Promise((settle) => {
+		execFile("git", [...args], {
+			cwd,
+			encoding: "utf8",
+			timeout: GIT_TIMEOUT_MS,
+			maxBuffer: 8 * 1024 * 1024,
+			windowsHide: true
+		}, (error, stdout, stderr) => {
+			const raw = error?.code;
+			const out = typeof stdout === "string" ? stdout : "";
+			const err = typeof stderr === "string" ? stderr : "";
+			settle({
+				ok: error === null,
+				code: error === null ? 0 : typeof raw === "number" ? raw : NOT_EXECUTED,
+				stdout: out,
+				stderr: err === "" ? error?.message ?? "" : err
+			});
+		});
+	});
+}
+/**
+* Locate the repository a directory belongs to.
+*
+* Answers `undefined` rather than throwing when the directory is not in a
+* repository, because "not a repository" is the ordinary answer for the many
+* sessions that never touch one, and the caller must be able to ask cheaply.
+* @param cwd - a directory inside the repository (or the repository itself).
+* @returns the location, or `undefined` when this is not a git repository.
+*/
+async function resolveRepo(cwd) {
+	if (cwd.trim() === "") return void 0;
+	const common = await runGit(cwd, ["rev-parse", "--git-common-dir"]);
+	if (!common.ok) return void 0;
+	const reported = common.stdout.trim();
+	if (reported === "") return void 0;
+	const commonDir = normalize(resolve(cwd, reported));
+	const bare = (await runGit(cwd, ["rev-parse", "--is-bare-repository"])).stdout.trim() === "true";
+	const repoRoot = bare ? commonDir : dirname(commonDir);
+	const repoParent = dirname(repoRoot);
+	const repoName = basename(repoRoot).replace(/\.git$/i, "") || "repo";
+	return {
+		commonDir,
+		repoRoot,
+		repoParent,
+		repoName,
+		bare,
+		worktreeRoot: join(repoParent, WORKTREE_DIR, repoName)
+	};
+}
+/** Strip `refs/heads/` so a branch is named the way every other layer names it. */
+function shortBranch(ref) {
+	return ref.startsWith("refs/heads/") ? ref.slice(11) : ref;
+}
+/**
+* Parse `git worktree list --porcelain -z` output.
+*
+* In the `-z` form every field is NUL-terminated and a record ends at an empty
+* field, so a record boundary is a split on `\0` that yields `''`. Fields are
+* `key value`, or a bare `key` for a boolean one (`detached`, `bare`) and for a
+* flag whose reason is optional (`locked`, `prunable`).
+* @param raw - the command's standard output.
+* @returns one entry per record that carried a path.
+*/
+function parseWorktreeList(raw) {
+	const entries = [];
+	let fields = /* @__PURE__ */ new Map();
+	const flush = () => {
+		const path = fields.get("worktree");
+		if (path !== void 0 && path !== "") {
+			const head = fields.get("HEAD");
+			const branchRef = fields.get("branch");
+			const lockReason = fields.get("locked");
+			const prunableReason = fields.get("prunable");
+			entries.push({
+				path: normalize(path),
+				detached: fields.has("detached"),
+				bare: fields.has("bare"),
+				locked: fields.has("locked"),
+				prunable: fields.has("prunable"),
+				...head === void 0 || head === "" ? {} : { head },
+				...branchRef === void 0 || branchRef === "" ? {} : { branch: shortBranch(branchRef) },
+				...lockReason === void 0 || lockReason === "" ? {} : { lockReason },
+				...prunableReason === void 0 || prunableReason === "" ? {} : { prunableReason }
+			});
+		}
+		fields = /* @__PURE__ */ new Map();
+	};
+	for (const field of raw.split("\0")) {
+		if (field === "") {
+			flush();
+			continue;
+		}
+		const space = field.indexOf(" ");
+		if (space < 0) fields.set(field, "");
+		else fields.set(field.slice(0, space), field.slice(space + 1));
+	}
+	flush();
+	return entries;
+}
+/**
+* List every working tree of a repository.
+* @param repo - the repository.
+* @returns one entry per working tree, main worktree first.
+* @throws when git itself cannot be asked.
+*/
+async function listWorktrees(repo) {
+	const result = await runGit(repo.commonDir, [
+		"worktree",
+		"list",
+		"--porcelain",
+		"-z"
+	]);
+	if (!result.ok) throw new Error(`report-ledger: git worktree list failed: ${result.stderr.trim() || `exit ${result.code}`}`);
+	return parseWorktreeList(result.stdout);
+}
+/**
+* Map each branch to the entry currently holding it.
+*
+* Prunable entries are skipped deliberately. Their working tree is gone, so they
+* do not actually hold anything — which is precisely why a stale entry must not
+* be allowed to block reuse forever, and why the same list yields two different
+* answers depending on the question being asked.
+* @param entries - entries from {@link listWorktrees}.
+* @returns branch name to holding entry.
+*/
+function branchHolders(entries) {
+	const holders = /* @__PURE__ */ new Map();
+	for (const entry of entries) {
+		if (entry.branch === void 0 || entry.prunable) continue;
+		if (!holders.has(entry.branch)) holders.set(entry.branch, entry);
+	}
+	return holders;
+}
+/**
+* Whether a working tree has no modification, no staged change and no untracked
+* file.
+*
+* Untracked files count as dirty on purpose: they are exactly what `git worktree
+* remove` refuses to delete, so a check that ignored them would authorize a
+* removal git then rejects.
+* @param worktreePath - the working tree to inspect.
+* @returns true only when git confirms a clean tree; a failure to ask answers
+* false, because an unreadable tree must never be treated as safe to delete.
+*/
+async function isWorktreeClean(worktreePath) {
+	const result = await runGit(worktreePath, ["status", "--porcelain"]);
+	if (!result.ok) return false;
+	return result.stdout.trim() === "";
+}
+/**
+* Read the commit a working tree is on.
+* @param worktreePath - the working tree to inspect.
+* @returns the object id, or `undefined` for an unborn branch or a failure.
+*/
+async function headOf(worktreePath) {
+	const result = await runGit(worktreePath, ["rev-parse", "HEAD"]);
+	if (!result.ok) return void 0;
+	const sha = result.stdout.trim();
+	return /^[0-9a-f]{40,64}$/.test(sha) ? sha : void 0;
+}
+/**
+* Whether a repository uses submodules.
+*
+* Git's own manual is explicit that multiple checkouts are experimental and that
+* support for submodules is incomplete — a linked worktree containing submodules
+* cannot even be moved. So this is a gate the caller is expected to consult
+* before allocating, not a warning to print afterwards.
+*
+* A bare repository answers false: the answer is derived from the working tree's
+* `.gitmodules`, which a bare repository does not have.
+* @param repo - the repository.
+* @returns true when `.gitmodules` exists in the main working tree.
+*/
+function hasSubmodules(repo) {
+	if (repo.bare) return false;
+	return existsSync(join(repo.repoRoot, ".gitmodules"));
+}
+/**
+* Attach a linked working tree.
+*
+* There is no force flag: git's occupancy check and its refusal of an unclean
+* path are returned to the caller as results, never overridden. A refusal is
+* data the ledger turns into a sentence naming a remedy.
+* @param input - what to create or check out.
+* @returns the git result; the caller decides whether a refusal is fatal.
+*/
+async function addWorktree(input) {
+	const args = ["worktree", "add"];
+	if (input.relativePaths === true) args.push("--relative-paths");
+	if (input.checkoutExisting === true) args.push(input.path, input.branch);
+	else args.push("-b", input.branch, input.path, input.base);
+	return await runGit(input.repo.commonDir, args);
+}
+/**
+* Remove a linked working tree.
+*
+* Deliberately without a force option. Git refuses when the tree is unclean or
+* locked, and that refusal is the last line of defence for work no one has
+* committed; exposing `--force` here would turn a policy mistake in the ledger
+* into silent data loss. A human who truly wants the tree gone can run the
+* command themselves, which is the correct amount of friction.
+* @param repo - the repository the tree belongs to.
+* @param worktreePath - the working tree to remove.
+* @returns the git result; a refusal is data, not an exception.
+*/
+async function removeWorktree(repo, worktreePath) {
+	return await runGit(repo.commonDir, [
+		"worktree",
+		"remove",
+		worktreePath
+	]);
+}
+/**
+* Classify a git refusal so the caller can name a remedy.
+* @param stderr - the command's standard error.
+* @returns the recognized kind, or `'unknown'`.
+*/
+function classifyGitRefusal(stderr) {
+	for (const [kind, pattern] of REFUSALS) if (pattern.test(stderr)) return kind;
+	return "unknown";
+}
+/** Strip a trailing separator without ever eating a root. */
+function stripTrailingSeparators(path) {
+	if (/^[a-zA-Z]:[\\/]$/.test(path)) return path;
+	if (/^[\\/]{1,2}$/.test(path)) return path;
+	return path.replace(/[\\/]+$/, "");
+}
+/**
+* Reduce a path to the string two spellings are compared by.
+*
+* The single place that decides when two paths name one file. Windows compares
+* case-insensitively and treats either separator as a separator; a POSIX host
+* does neither, so the rule is the host's rather than a lowest common
+* denominator — comparing case-insensitively on Linux would merge two directories
+* git considers distinct.
+* @param path - a path, absolute or relative to the current directory.
+* @returns the comparison key.
+*/
+function compareKey(path) {
+	const absolute = stripTrailingSeparators(normalize(resolve(path)));
+	return process.platform === "win32" ? absolute.toLowerCase() : absolute;
+}
+/**
+* Whether two paths name the same file.
+* @param left - one path.
+* @param right - another path.
+* @returns true when they share a comparison key.
+*/
+function samePath(left, right) {
+	return compareKey(left) === compareKey(right);
+}
+//#endregion
+//#region src/report/lease.ts
+/**
+* The working-tree lease referee.
+*
+* A lease answers one question: may *this* report work in *that* checkout? The
+* answer needs two authorities, and this module consults both.
+*
+*  - **The ledger knows intent.** It can say which report claims a branch, and
+*    therefore name the agent to talk to. Git cannot: it reports a path, and a
+*    path is not a colleague.
+*  - **Git knows reality.** It can say which working tree actually has a branch
+*    checked out. The ledger cannot: a checkout a human made by hand never
+*    appears in it.
+*
+* Neither is sufficient, and when they disagree the disagreement is reported
+* rather than resolved — a ledger that silently overrode git would be lying
+* about the filesystem, and one that silently deferred to git would lose the
+* only party who can be asked to let go.
+*
+* **Lease liveness is derived from the hop stream, never stored as a flag.** The
+* digest is a cache of current state, and `leased`/`released` hops are the
+* authority for whether a claim is still held — the same shape as
+* `pendingTargets`, which derives the durable mailbox from hops rather than
+* recording it. The binding itself *does* persist in the digest after release,
+* because a working tree kept on disk must still be traceable back to the report
+* that made it.
+*
+* @module dsh-report-ledger/report/lease
+*/
+/**
+* Derive lease liveness from the authoritative hop stream.
+* @param hops - a report's hops, oldest first.
+* @returns the current lease state.
+*/
+function leaseState(hops) {
+	let state = "none";
+	for (const hop of hops) if (hop.action === "leased") state = "held";
+	else if (hop.action === "released") state = "released";
+	else if (hop.action === "reclaimed") state = "reclaimed";
+	return state;
+}
+/**
+* Whether two bindings name the same claim.
+*
+* A branch, when both sides name one, is the claim's identity: two reports bound
+* to the same branch are claiming one thing however differently they spell the
+* path. With no branch on one side there is nothing but the path to compare,
+* which is what a detached tree has instead of a name.
+* @param left - one binding.
+* @param right - another binding.
+* @returns true when they are the same claim.
+*/
+function sameClaim(left, right) {
+	if (left.branch !== void 0 && right.branch !== void 0) return left.branch === right.branch;
+	return samePath(left.path, right.path);
+}
+/** The claimed name in prose: the branch when there is one, else the path. */
+function claimName(binding) {
+	return binding.branch ?? `${binding.path} (detached)`;
+}
+/**
+* Decide whether a claim may be taken.
+*
+* Git is consulted before the ledger on purpose. Accusing a colleague of holding
+* something that turns out not to exist is a worse answer than "there is no such
+* checkout", and the ledger layer is only meaningful once the thing being
+* claimed is real.
+* @param query - the claim and the authorities to check it against.
+* @returns the refusal, or `undefined` when the claim may be taken.
+* @throws when git cannot be asked at all.
+*/
+async function evaluateLease(query) {
+	const { binding, repo } = query;
+	const refuse = (refusal) => ({
+		kind: "refused",
+		refusal
+	});
+	if (repo === void 0) return refuse({
+		kind: "no-repository",
+		message: `${binding.path} is not inside a git repository, so there is no working tree to claim. Bind a checkout that exists, or let the ledger allocate one.`
+	});
+	const entries = await listWorktrees(repo);
+	const entry = entries.find((candidate) => samePath(candidate.path, binding.path));
+	if (entry === void 0) return refuse({
+		kind: "not-a-worktree",
+		message: `${binding.path} is not a working tree of ${repo.commonDir}. An existing checkout can be listed with git worktree list.`
+	});
+	if (entry.prunable) return refuse({
+		kind: "not-a-worktree",
+		message: `${binding.path} is registered but its working tree is gone, so git reports it prunable${entry.prunableReason === void 0 ? "" : ` (${entry.prunableReason})`}. If it was moved by hand, run git worktree repair from the new location; otherwise remove the stale entry first.`
+	});
+	if (binding.branch !== void 0) {
+		const actual = entry.branch;
+		if (actual !== binding.branch) return refuse({
+			kind: "branch-mismatch",
+			message: `${binding.path} is on ${actual === void 0 ? "a detached HEAD" : `'${actual}'`}, not '${binding.branch}', so the binding no longer describes the checkout.`
+		});
+		const holder = branchHolders(entries).get(binding.branch);
+		if (holder !== void 0 && !samePath(holder.path, binding.path)) return refuse({
+			kind: "checked-out",
+			heldAt: holder.path,
+			message: `'${binding.branch}' is checked out at ${holder.path}, and a branch is held by exactly one working tree. Claim ${holder.path} instead, or use a different branch.`
+		});
+	}
+	for (const front of query.digests) {
+		if (front.report === query.report) continue;
+		if (front.worktree === void 0) continue;
+		if (!sameClaim(front.worktree, binding)) continue;
+		if (front.status === "closed") continue;
+		if (leaseState(await query.hopsOf(front.report)) !== "held") continue;
+		const holders = [.../* @__PURE__ */ new Set([front.from, ...front.authors])];
+		return refuse({
+			kind: "held-by-report",
+			heldBy: front.report,
+			heldByActor: front.from,
+			message: `${front.report} (opened by ${front.from}) already holds ${claimName(binding)}. A claim is held by one report at a time. Ask it to release with report_release, or to close — closing releases the claim. Its authors are ${holders.join(", ")}.`
+		});
+	}
+	return {
+		kind: "granted",
+		binding: {
+			path: binding.path,
+			...entry.branch === void 0 ? {} : { branch: entry.branch },
+			...entry.head === void 0 ? {} : { head: entry.head },
+			repo: repo.commonDir,
+			...binding.allocated === void 0 ? {} : { allocated: binding.allocated }
+		}
+	};
+}
+/** Longest slug kept in a branch and directory name. */
+const SLUG_LIMIT = 40;
+/**
+* Reduce a subject to a ref-safe slug.
+*
+* The output alphabet is `[a-z0-9-]`, a subset of what git accepts in a ref
+* name, so nothing needs escaping afterwards. That narrowness is the point: git
+* forbids `~^:?*[`, `..`, `@{`, spaces, control characters, and a leading or
+* trailing `.`, and a slug that can only hold lower-case letters, digits and
+* interior hyphens cannot spell any of them. A subject in a non-Latin script
+* reduces to nothing, which is why a name without a slug exists too.
+* @param subject - the report subject.
+* @returns the slug, possibly empty.
+*/
+function slugify(subject) {
+	return subject.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, SLUG_LIMIT).replace(/-+$/g, "");
+}
+/**
+* The name a report's checkout goes by, in both its branch and its directory.
+*
+* A report id is always part of it, so a checkout traces back to its report from
+* `git branch` alone, and the report id is recoverable from a directory listing
+* without consulting the ledger.
+* @param report - report identifier.
+* @param subject - the report subject, for the readable suffix.
+* @returns the name.
+*/
+function worktreeName(report, subject) {
+	const slug = slugify(subject);
+	return slug === "" ? report : `${report}-${slug}`;
+}
+/**
+* The branch a report's checkout is on.
+* @param report - report identifier.
+* @param subject - the report subject.
+* @returns the branch name.
+*/
+function worktreeBranch(report, subject) {
+	return `dsh/${worktreeName(report, subject)}`;
+}
+/**
+* Where a report's checkout is created.
+*
+* The repository name is always a path component, so two repositories sharing a
+* parent — the ordinary case for anyone with several projects — cannot allocate
+* into each other's directory.
+* @param repo - the repository.
+* @param report - report identifier.
+* @param subject - the report subject.
+* @param base - base directory override, when configured.
+* @returns the absolute path.
+*/
+function worktreePath(repo, report, subject, base) {
+	const name = worktreeName(report, subject);
+	return base === void 0 ? join(repo.worktreeRoot, name) : join(base, repo.repoName, name);
+}
+/**
+* Fill in the defaults for working-tree support.
+* @param config - the plugin configuration, when one was supplied.
+* @returns the resolved runtime.
+*/
+function resolveWorktree(config) {
+	return {
+		enabled: config?.enabled === true,
+		settings: {
+			maxActive: config?.maxActive ?? 4,
+			maxRetained: config?.maxRetained ?? 4,
+			reclaim: config?.reclaim ?? "never",
+			relativePaths: config?.relativePaths === true,
+			...config?.root === void 0 ? {} : { base: config.root }
+		},
+		onClose: config?.onClose ?? "keep"
+	};
+}
+/** When a claim ended, from the hop that ended it. */
+function lastReleaseAt(hops) {
+	let at = 0;
+	for (const hop of hops) if (hop.action === "released") at = hop.at;
+	return at;
+}
+/**
+* The message shown when the active budget is full.
+*
+* "Wait" is useless advice unless it says for whom, and the ledger already knows
+* both the holders and whether each is around — so the refusal names them, and
+* names the two ways out that do not involve waiting.
+* @param held - the reports currently holding a checkout.
+* @param limit - the configured cap.
+* @returns the refusal message.
+*/
+function budgetMessage(held, limit) {
+	const holders = held.map((holder) => `${holder.report} -> ${holder.actor} (${holder.live ? "live" : "absent"})`).join(", ");
+	return `the working-tree budget is full (${held.length} of ${limit} held). Held by: ${holders}. Wait for one of these to finish, hand one back with report_release, or close its report — closing releases the claim.`;
+}
+/**
+* Decide what to allocate, or refuse.
+*
+* One pass over the ledger yields both answers: which checkouts are held now,
+* and which ended claims left one behind. The budget is then checked against the
+* held set alone and refuses without an override; reclamation runs afterwards,
+* for the disk limit, and can only reach checkouts whose claim already ended.
+* @param query - the allocation and the ledger it must fit into.
+* @param settings - the resolved settings.
+* @returns the plan, or the refusal.
+*/
+async function planAllocation(query, settings) {
+	if (hasSubmodules(query.repo)) return {
+		kind: "submodules",
+		message: `${query.repo.repoRoot} uses submodules (it has a .gitmodules file). Git does not recommend multiple checkouts of a superproject, and a linked worktree containing submodules cannot be moved, so the ledger will not allocate one here.`
+	};
+	const held = [];
+	const reclaimable = [];
+	const stale = [];
+	for (const front of query.digests) {
+		if (front.report === query.report) continue;
+		const binding = front.worktree;
+		if (binding === void 0) continue;
+		const hops = await query.hopsOf(front.report);
+		const state = leaseState(hops);
+		if (state === "held") {
+			held.push({
+				report: front.report,
+				actor: front.from,
+				live: query.isLive(front.from)
+			});
+			continue;
+		}
+		if (state !== "released" || front.status !== "closed" || binding.allocated !== true) continue;
+		if (!existsSync(binding.path)) {
+			stale.push({
+				report: front.report,
+				path: binding.path
+			});
+			continue;
+		}
+		reclaimable.push({
+			report: front.report,
+			path: binding.path,
+			...binding.branch === void 0 ? {} : { branch: binding.branch },
+			releasedAt: lastReleaseAt(hops)
+		});
+	}
+	if (held.length >= settings.maxActive) return {
+		kind: "budget",
+		message: budgetMessage(held, settings.maxActive)
+	};
+	reclaimable.sort((left, right) => left.releasedAt - right.releasedAt || left.report.localeCompare(right.report));
+	let reclaimed;
+	const reclaimSkipped = [];
+	if (settings.reclaim === "oldest-closed" && reclaimable.length > settings.maxRetained) for (const candidate of reclaimable) {
+		if (!await isWorktreeClean(candidate.path)) {
+			reclaimSkipped.push(`${candidate.report} (uncommitted changes at ${candidate.path})`);
+			continue;
+		}
+		reclaimed = {
+			report: candidate.report,
+			path: candidate.path,
+			...candidate.branch === void 0 ? {} : { branch: candidate.branch }
+		};
+		break;
+	}
+	return {
+		binding: {
+			path: worktreePath(query.repo, query.report, query.subject, settings.base),
+			branch: worktreeBranch(query.report, query.subject),
+			repo: query.repo.commonDir,
+			allocated: true
+		},
+		retained: reclaimable.length - (reclaimed === void 0 ? 0 : 1),
+		...reclaimed === void 0 ? {} : { reclaimed },
+		reclaimSkipped,
+		stale
+	};
+}
+//#endregion
+//#region src/report/maintenance.ts
+/**
+* The maintenance view: what the ledger thinks it owns, and what is true of it.
+*
+* This exists because of an asymmetry the design accepts deliberately. A working
+* tree is not a first-class object in the ledger — it is a field on a report plus
+* a directory on disk — so there is no index to consult when an operator asks
+* "what checkouts are out there, and is any of it broken?". The answer has to be
+* assembled from the reports and from git, every time, and that is what this
+* module does.
+*
+* It **reports and never repairs**. Nothing here removes, prunes or reclaims: a
+* checkout moved by hand still works from its own side while git calls it
+* dangling, so an automatic prune destroys live work, and the whole point of a
+* maintenance view is to let a human decide with the facts in front of them.
+*
+* @module dsh-report-ledger/report/maintenance
+*/
+/**
+* Assemble the maintenance view.
+*
+* Two passes, because they cost different things: the first asks the ledger what
+* it believes (cheap), the second asks git what is true (one `worktree list` per
+* repository, plus one `status` per checkout that is actually on disk).
+* @param deps - the ledger readers.
+* @param settings - the configured limits.
+* @param enabled - whether allocation is on in this deployment.
+* @returns the view.
+*/
+async function buildWorktreeReport(deps, settings, enabled) {
+	const digests = await deps.listReports();
+	const records = [];
+	for (const front of digests) {
+		const binding = front.worktree;
+		if (binding === void 0) continue;
+		const onDisk = existsSync(binding.path);
+		records.push({
+			report: front.report,
+			subject: front.subject,
+			status: front.status,
+			path: binding.path,
+			...binding.branch === void 0 ? {} : { branch: binding.branch },
+			...binding.head === void 0 ? {} : { head: binding.head },
+			...binding.repo === void 0 ? {} : { repo: binding.repo },
+			allocated: binding.allocated === true,
+			state: leaseState(await deps.readHops(front.report)),
+			onDisk,
+			...onDisk ? { clean: await isWorktreeClean(binding.path) } : {},
+			prunable: false
+		});
+	}
+	const byRepo = /* @__PURE__ */ new Map();
+	for (const record of records) {
+		const key = record.repo ?? record.path;
+		const bucket = byRepo.get(key);
+		if (bucket === void 0) byRepo.set(key, [record]);
+		else bucket.push(record);
+	}
+	const warnings = [];
+	const unmanaged = [];
+	const dangling = [];
+	const prunable = /* @__PURE__ */ new Set();
+	for (const bucket of byRepo.values()) {
+		const first = bucket[0];
+		if (first === void 0) continue;
+		const repo = await resolveRepo(first.path) ?? (first.repo === void 0 ? void 0 : await resolveRepo(first.repo));
+		if (repo === void 0) {
+			warnings.push(`the repository holding ${bucket.map((record) => record.report).join(", ")} could not be resolved, so those checkouts were not inspected`);
+			continue;
+		}
+		let entries;
+		try {
+			entries = await listWorktrees(repo);
+		} catch (error) {
+			warnings.push(`git could not list the working trees of ${repo.commonDir}: ${error instanceof Error ? error.message : String(error)}`);
+			continue;
+		}
+		for (const entry of entries) if (entry.prunable) {
+			prunable.add(entry.path);
+			dangling.push(entry.path);
+		}
+		for (const entry of entries) {
+			if (entry.bare || entry.prunable || samePath(entry.path, repo.repoRoot)) continue;
+			if (records.some((record) => samePath(record.path, entry.path))) continue;
+			unmanaged.push(entry.path);
+		}
+	}
+	const resolved = records.map((record) => prunable.has(record.path) ? {
+		...record,
+		prunable: true
+	} : record);
+	const active = resolved.filter((record) => record.state === "held").length;
+	const retained = resolved.filter((record) => record.state === "released" && record.onDisk).length;
+	for (const record of resolved) {
+		if (record.state === "held" && !record.onDisk) warnings.push(`${record.report} holds a claim on ${record.path}, and that checkout is no longer on disk. Release the claim, or close the report — closing releases it.`);
+		if (record.state === "released" && !record.onDisk) warnings.push(`${record.report}'s bound checkout at ${record.path} is gone, and the ledger still records the claim as released rather than reclaimed. The next allocation will note that it is gone.`);
+		if (record.clean === false && record.state !== "held") warnings.push(`the kept checkout at ${record.path} (${record.report}) has uncommitted work, so it will never be reclaimed automatically.`);
+	}
+	if (retained > settings.maxRetained && settings.reclaim === "never") warnings.push(`${retained} checkouts are kept on disk past the retained limit of ${settings.maxRetained}, and automatic reclamation is off, so they will accumulate. Close reports with worktree:"remove-if-clean", or set worktree.reclaim to "oldest-closed".`);
+	const uniqueDangling = [...new Set(dangling)].sort();
+	for (const path of uniqueDangling) warnings.push(`git reports the worktree entry at ${path} as dangling. If it was moved by hand, run git worktree repair from the new location; otherwise prune the stale entry.`);
+	for (const path of unmanaged) warnings.push(`git has a working tree no report is bound to: ${path}. A report can adopt it with report_lease.`);
+	resolved.sort((left, right) => left.report.localeCompare(right.report));
+	return {
+		generatedAt: Date.now(),
+		enabled,
+		limits: {
+			maxActive: settings.maxActive,
+			maxRetained: settings.maxRetained,
+			reclaim: settings.reclaim
+		},
+		active,
+		retained,
+		records: resolved,
+		unmanaged: [...new Set(unmanaged)].sort(),
+		dangling: uniqueDangling,
+		warnings
+	};
+}
 //#endregion
 //#region src/report/roster.ts
 /**
@@ -7529,6 +8425,8 @@ function holdsChannelTo(input, target) {
 	if (byId.get(target)?.header.parentSession === input.self) return true;
 	return input.peers.some((peer) => peer.startedBy === input.self && peer.sessionId === target);
 }
+/** How long a caller waits for evidence about a peer's first turn, by default. */
+const DEFAULT_RECEIPT_MS = 1500;
 /** The peer service. */
 var PeerService = class {
 	#host;
@@ -7602,6 +8500,19 @@ var PeerService = class {
 		return holdsChannelTo(await this.#inputs(self), target);
 	}
 	/**
+	* Observe what became of a peer's first turn.
+	*
+	* Not a status check: it is the honest answer to "did the thing I just handed
+	* this peer actually start working?" — the question a bare `delivered` cannot
+	* answer. Call it after the assignment report has been delivered.
+	* @param sessionId - the peer session to observe.
+	* @param timeoutMs - how long a still-running turn is awaited before being reported as running.
+	* @returns the observation, or `undefined` when the peer is not resident.
+	*/
+	async receipt(sessionId, timeoutMs = DEFAULT_RECEIPT_MS) {
+		return await this.#host.confirmPeer(sessionId, timeoutMs);
+	}
+	/**
 	* Open one independent peer session.
 	*
 	* The peer is recorded before it is returned, so the relationship survives even
@@ -7619,10 +8530,11 @@ var PeerService = class {
 		if (name !== void 0 && name.length > 60) throw new Error("report-ledger: peer_start name must be 60 characters or fewer");
 		const already = await this.startedCount(self);
 		if (already >= this.#maxPeers) throw new Error(`report-ledger: this session already started ${already} peers (limit ${this.#maxPeers}); reuse an existing peer, or report to one you already hold a channel to instead of opening another`);
-		const cwd = this.#host.selfCwd(self);
+		const cwd = input.cwd ?? this.#host.selfCwd(self);
 		const sessionId = `session-${randomUUID()}`;
 		const created = await this.#host.createPeer({
 			sessionId,
+			startedBy: self,
 			...cwd === void 0 ? {} : { cwd }
 		});
 		await appendPeer({
@@ -7646,6 +8558,14 @@ var PeerService = class {
 const TIMELINE_PATH = "/api/report-ledger/timeline";
 /** Path of one report's detail. */
 const REPORT_PATH = "/api/report-ledger/report";
+/**
+* Path of the working-tree maintenance view.
+*
+* Registered whatever the feature's state, so an operator asking "is anything
+* out there?" gets an answer even when the answer is "nothing, and allocation is
+* off". A 404 would be indistinguishable from a typo.
+*/
+const WORKTREES_PATH = "/api/report-ledger/worktrees";
 /** Longest accepted root session id. */
 const MAX_ID_LENGTH = 200;
 /** Conservative session-id shape: no separators that could escape a query. */
@@ -7773,6 +8693,23 @@ function createTimelineHandler(deps) {
 	});
 }
 /**
+* Build the working-tree maintenance handler.
+*
+* Read-only and unparameterised: it answers one question — what checkouts does
+* the ledger know about, and what is true of them — with no way to change any of
+* it. Repair stays a human decision made from these facts.
+* @param deps - data sources.
+* @returns the route handler.
+*/
+function createWorktreesHandler(deps) {
+	return guarded(async (_url, response) => {
+		writeJson(response, 200, {
+			ok: true,
+			value: await deps.worktrees()
+		});
+	});
+}
+/**
 * Build the single-report handler.
 * @param deps - data sources.
 * @returns the route handler.
@@ -7820,8 +8757,21 @@ function createReportHandler(deps) {
 const BODY_INLINE_LIMIT = 8e3;
 /** How many characters of a body are shown when it exceeds the inline limit. */
 const BODY_HEAD_LIMIT = 1200;
-/** Serialize one report for model-facing output. */
-function renderFrontLine(front) {
+/**
+* One token naming a bound working tree.
+*
+* The branch is the lease's identity, so it is what a listing shows; a detached
+* tree has none, and there the directory name is the only stable handle. The
+* full path stays in the digest for anyone who needs to act on it.
+* @param worktree - the binding.
+* @returns the label.
+*/
+function worktreeLabel(worktree) {
+	if (worktree.branch !== void 0) return worktree.branch;
+	return basename(worktree.path) || worktree.path;
+}
+/** Serialize one report for model-facing output. */
+function renderFrontLine(front) {
 	const parts = [
 		`${front.report} [${front.status}] ${front.subject}`,
 		`from=${front.from}`,
@@ -7832,6 +8782,7 @@ function renderFrontLine(front) {
 		`updated=${new Date(front.updated).toISOString()}`
 	];
 	if (front.task !== void 0) parts.push(`task=${front.task}`);
+	if (front.worktree !== void 0) parts.push(`worktree=${worktreeLabel(front.worktree)}@${front.worktree.path}`);
 	if (front.parent !== void 0) parts.push(`parent=${front.parent}`);
 	if (front.children.length > 0) parts.push(`children=${front.children.join(",")}`);
 	if (front.last !== void 0) parts.push(`last=${front.last.action}@${front.last.actor}`);
@@ -7871,31 +8822,55 @@ var ReportService = class ReportService {
 	#host;
 	#locks = /* @__PURE__ */ new Map();
 	/**
+	* Mutexes keyed by shared git directory, for decisions that span reports.
+	*
+	* A per-report mutex cannot serialize two *different* reports racing for one
+	* branch, and claiming a working tree is exactly that decision. The key is the
+	* repository rather than a checkout, because a branch is held by a repository
+	* — keying by path would leave two checkouts of one repository mutually
+	* invisible, which is the race the lock exists to stop. Their order is fixed;
+	* see {@link ReportService.lease}.
+	*/
+	#repoLocks = /* @__PURE__ */ new Map();
+	/**
 	* @param host - host capabilities (agent lookup, display names).
 	*/
 	constructor(host) {
 		this.#host = host;
 	}
+	/** Run one task under a key's mutex. */
+	async #serialize(map, key, work) {
+		const next = (map.get(key) ?? Promise.resolve()).then(work, work);
+		map.set(key, next.then(() => void 0, () => void 0));
+		return next;
+	}
 	/** Run one mutation under the report's mutex. */
 	async #withLock(report, work) {
-		const next = (this.#locks.get(report) ?? Promise.resolve()).then(work, work);
-		this.#locks.set(report, next.then(() => void 0, () => void 0));
-		return next;
+		return await this.#serialize(this.#locks, report, work);
+	}
+	/** Run one decision under the repository's mutex. */
+	async #withRepoLock(key, work) {
+		return await this.#serialize(this.#repoLocks, key, work);
 	}
 	/** Append one hop, then refresh the derived digest fields. */
-	async #record(report, hop) {
+	async #record(report, hop, options = {}) {
 		await appendHop(report, hop);
-		return this.#sync(report);
+		return await this.#sync(report, options);
 	}
-	/** Recompute the derived front-matter fields from the hop stream. */
-	async #sync(report) {
+	/**
+	* Recompute the derived front-matter fields from the hop stream.
+	* @param report - report identifier.
+	* @param options - `touch: false` keeps the digest's `updated` stamp, for an
+	* administrative hop that must not make a concluded report look active again.
+	*/
+	async #sync(report, options = {}) {
 		const current = await readReport(report);
 		if (current === void 0) throw new Error(`report-ledger: report ${report} does not exist`);
 		const projected = projectRoute(await readHops(report));
 		const front = {
 			...current.front,
 			...projected,
-			updated: Date.now()
+			updated: options.touch === false ? current.front.updated : Date.now()
 		};
 		await writeReport({
 			front,
@@ -7933,7 +8908,8 @@ var ReportService = class ReportService {
 	async author(input) {
 		const subject = input.subject.trim();
 		if (subject === "") throw new Error("report-ledger: report_author requires a non-empty subject");
-		const report = await allocateId();
+		const report = input.reportId ?? await allocateId();
+		if (!isValidReportId(report)) throw new Error(`report-ledger: ${JSON.stringify(report)} is not a usable report id (expected the form R-0001)`);
 		const now = Date.now();
 		const fromName = await this.#host.describe(input.actor);
 		await writeReport({
@@ -7952,7 +8928,8 @@ var ReportService = class ReportService {
 				artifacts: [...input.artifacts ?? []],
 				hops: 0,
 				...input.parent === void 0 ? {} : { parent: input.parent },
-				...input.task === void 0 ? {} : { task: input.task }
+				...input.task === void 0 ? {} : { task: input.task },
+				...input.worktree === void 0 ? {} : { worktree: input.worktree }
 			},
 			body: input.body
 		});
@@ -7962,6 +8939,13 @@ var ReportService = class ReportService {
 			action: "authored",
 			to: []
 		});
+		if (input.worktree !== void 0) await this.#record(report, {
+			at: Date.now(),
+			actor: input.actor,
+			action: "leased",
+			to: [],
+			note: `${input.worktree.branch ?? "(detached HEAD)"} @ ${input.worktree.path}`
+		});
 		if (input.parent !== void 0) {
 			if (await readReport(input.parent) !== void 0) await this.#withLock(input.parent, async () => {
 				const latest = await this.#require(input.parent);
@@ -8015,6 +8999,27 @@ var ReportService = class ReportService {
 		return actor === front.from || front.authors.includes(actor);
 	}
 	/**
+	* Throw unless the actor owns the report.
+	*
+	* Correcting, concluding and claiming a checkout are all the owner's acts, and
+	* they are refused the same way — by naming who may do it instead. A refusal
+	* that only says "no" makes the model guess; naming the authors turns it into
+	* a hand-off.
+	*
+	* The gerund is passed rather than derived, because the derivation is wrong:
+	* `close` + `ing` is not a word, and a refusal that reads like a bug invites a
+	* model to route around it.
+	* @param front - the report's digest.
+	* @param actor - the session attempting the act.
+	* @param verb - the act, in the imperative, for the sentence.
+	* @param gerund - the same act as a noun phrase.
+	*/
+	#assertOwner(front, actor, verb, gerund) {
+		if (ReportService.owns(front, actor)) return;
+		const owners = [.../* @__PURE__ */ new Set([front.from, ...front.authors])];
+		throw new Error(`report-ledger: ${actor} may not ${verb} ${front.report} — ${gerund} is the owner's act, not a reader's. Ask one of its authors to do it: ${owners.join(", ")}`);
+	}
+	/**
 	* Return a closed report to life because fresh activity arrived.
 	*
 	* `closed` is a state, not a lock. If someone contributes to, sends, copies, or
@@ -8181,8 +9186,11 @@ var ReportService = class ReportService {
 			return `  ${new Date(hop.at).toISOString()}  ${hop.action.padEnd(11)} by ${hop.actor}${targets}${note}`;
 		}).join("\n");
 		const pending = pendingTargets(hops);
+		const worktree = found.front.worktree;
+		const lease = worktree === void 0 ? [] : [`lease=${leaseState(hops)} ${worktree.branch ?? "(detached HEAD)"} @ ${worktree.path} (${worktree.allocated === true ? "allocated by the ledger" : "adopted"})`];
 		return [
 			renderFrontLine(found.front),
+			...lease,
 			`body=${path}`,
 			"",
 			"## transfer path",
@@ -8202,9 +9210,14 @@ var ReportService = class ReportService {
 		const all = await listReports();
 		const session = filter.session;
 		const task = filter.task?.trim().toLowerCase();
+		const worktree = filter.worktree?.trim().toLowerCase();
 		const matching = all.filter((front) => {
 			if (filter.status !== void 0 && front.status !== filter.status) return false;
 			if (task !== void 0 && task !== "" && !(front.task ?? "").toLowerCase().includes(task)) return false;
+			if (worktree !== void 0 && worktree !== "") {
+				if (front.worktree === void 0) return false;
+				if (!`${front.worktree.branch ?? ""} ${front.worktree.path}`.toLowerCase().includes(worktree)) return false;
+			}
 			if (session === void 0) return true;
 			return front.from === session || front.to.includes(session) || front.cc.includes(session) || front.authors.includes(session);
 		});
@@ -8218,6 +9231,7 @@ var ReportService = class ReportService {
 			cc: front.cc,
 			hops: front.hops,
 			...front.task === void 0 ? {} : { task: front.task },
+			...front.worktree === void 0 ? {} : { worktree: worktreeLabel(front.worktree) },
 			...front.last === void 0 ? {} : { last: `${front.last.action}@${front.last.actor}` },
 			updated: front.updated
 		}));
@@ -8263,22 +9277,53 @@ var ReportService = class ReportService {
 	* @param report - report identifier.
 	* @param actor - the session concluding it.
 	* @param note - optional note.
-	* @returns the refreshed digest.
+	* @param options - what to do with a bound working tree on disk.
+	* @returns the refreshed digest, and what happened to the working tree.
 	* @throws when the actor is neither the originator nor a co-author.
 	*/
-	async close(report, actor, note) {
+	async close(report, actor, note, options = {}) {
 		return this.#withLock(report, async () => {
 			const current = await this.#require(report);
-			if (!ReportService.owns(current.front, actor)) {
-				const owners = [.../* @__PURE__ */ new Set([current.front.from, ...current.front.authors])];
-				throw new Error(`report-ledger: ${actor} may not close ${report} — closing is the owner's act, not a reader's. Ask one of its authors to close it: ${owners.join(", ")}`);
+			this.#assertOwner(current.front, actor, "close", "closing");
+			const binding = current.front.worktree;
+			if (binding !== void 0 && leaseState(await readHops(report)) === "held") await this.#record(report, {
+				at: Date.now(),
+				actor,
+				action: "released",
+				to: [],
+				note: "released by closing the report"
+			});
+			let outcome;
+			if (binding !== void 0) if (options.worktree !== "remove-if-clean") outcome = { action: "kept" };
+			else {
+				const repo = await resolveRepo(binding.path);
+				if (repo === void 0) outcome = {
+					action: "refused",
+					detail: `${binding.path} is no longer inside a git repository`
+				};
+				else {
+					const removed = await removeWorktree(repo, binding.path);
+					outcome = removed.ok ? { action: "removed" } : {
+						action: "refused",
+						detail: removed.stderr.trim()
+					};
+				}
 			}
+			const disposition = outcome === void 0 ? void 0 : outcome.action === "removed" ? "working tree removed" : outcome.action === "kept" ? "working tree kept" : `working tree kept: ${outcome.detail ?? "removal refused"}`;
+			if (outcome?.action === "removed") await this.#record(report, {
+				at: Date.now(),
+				actor,
+				action: "reclaimed",
+				to: [],
+				note: `checkout ${binding?.path ?? ""} removed at the owner's request`
+			});
+			const closedNote = [note, disposition].filter((part) => part !== void 0 && part !== "").join("; ");
 			await this.#record(report, {
 				at: Date.now(),
 				actor,
 				action: "closed",
 				to: [],
-				...note === void 0 ? {} : { note }
+				...closedNote === "" ? {} : { note: closedNote }
 			});
 			const fresh = await this.#require(report);
 			await writeReport({
@@ -8291,11 +9336,305 @@ var ReportService = class ReportService {
 			});
 			return {
 				front: (await this.#require(report)).front,
+				outcomes: [],
+				...outcome === void 0 ? {} : { worktree: outcome }
+			};
+		});
+	}
+	/**
+	* Claim a working tree for a report.
+	*
+	* The decision runs under two mutexes, outer first: the working tree's,
+	* because two reports racing for one branch is exactly what a per-report mutex
+	* cannot see, and then the report's, because writing the digest still races
+	* other mutations of the same report. Only this method nests them —
+	* {@link ReportService.release} takes the report lock alone, since giving a
+	* claim up needs no atomicity against the filesystem — so the order is fixed
+	* and cannot form the cycle that would deadlock.
+	*
+	* Re-claiming is allowed and is how a binding is refreshed (a new head, a
+	* corrected path): the report already holding it is skipped by the referee, so
+	* refreshing needs no release first. It is still recorded, because the audit
+	* is the product.
+	* @param report - report identifier.
+	* @param actor - the claiming session; must own the report.
+	* @param binding - the working tree to claim.
+	* @returns the refreshed digest.
+	* @throws when git or the ledger refuses the claim.
+	*/
+	async lease(report, actor, binding) {
+		const repo = await resolveRepo(binding.path) ?? (binding.repo === void 0 ? void 0 : await resolveRepo(binding.repo));
+		const key = compareKey(repo?.commonDir ?? binding.path);
+		return await this.#withRepoLock(key, async () => await this.#withLock(report, async () => {
+			const current = await this.#require(report);
+			this.#assertOwner(current.front, actor, "lease", "leasing");
+			const verdict = await evaluateLease({
+				binding,
+				repo,
+				report,
+				digests: await listReports(),
+				hopsOf: async (id) => await readHops(id)
+			});
+			if (verdict.kind === "refused") throw new Error(`report-ledger: ${verdict.refusal.message}`);
+			const claim = verdict.binding;
+			await writeReport({
+				front: {
+					...current.front,
+					worktree: claim,
+					updated: Date.now()
+				},
+				body: current.body
+			});
+			return {
+				front: await this.#record(report, {
+					at: Date.now(),
+					actor,
+					action: "leased",
+					to: [],
+					note: `${claim.branch ?? "(detached HEAD)"} @ ${claim.path}`
+				}),
 				outcomes: []
 			};
+		}));
+	}
+	/**
+	* Give up a report's claim on its working tree, without touching the disk.
+	*
+	* The binding stays in the digest on purpose. A checkout kept on disk must
+	* remain traceable to the report that made it — otherwise the ledger forgets
+	* which working trees it is responsible for, and a later cleanup could not
+	* tell its own from a stranger's. What ended is the claim, and the hop stream
+	* is where that is recorded.
+	* @param report - report identifier.
+	* @param actor - the releasing session; must own the report.
+	* @param note - optional note.
+	* @returns the refreshed digest.
+	* @throws when the report holds nothing, or the actor is not an owner.
+	*/
+	async release(report, actor, note) {
+		return await this.#withLock(report, async () => {
+			const current = await this.#require(report);
+			this.#assertOwner(current.front, actor, "release", "releasing");
+			if (current.front.worktree === void 0) throw new Error(`report-ledger: ${report} is not bound to a working tree, so there is nothing to release`);
+			if (leaseState(await readHops(report)) !== "held") throw new Error(`report-ledger: ${report} does not currently hold its working tree, so there is nothing to release (a claim is released once; closing a report releases it too)`);
+			return {
+				front: await this.#record(report, {
+					at: Date.now(),
+					actor,
+					action: "released",
+					to: [],
+					...note === void 0 ? {} : { note }
+				}),
+				outcomes: []
+			};
+		});
+	}
+	/**
+	* Create the working tree a report is about to be given, and clear room for it.
+	*
+	* Separate from {@link ReportService.lease} because it runs *before* the
+	* report exists: a working tree's name is derived from the report id, and the
+	* caller needs the checkout's path to hand a peer its working directory. So
+	* the order is claim the id, provision the checkout, then author — and this is
+	* the middle step.
+	*
+	* Runs under the repository mutex, because the budget it consults and the
+	* branch it takes are both repository-wide facts that two concurrent
+	* allocations would otherwise read at the same moment.
+	* @param input - what to provision, and for whom.
+	* @returns the binding to record, plus what housekeeping happened.
+	* @throws when a gate refuses the allocation or git cannot create the tree.
+	*/
+	async prepareWorktree(input) {
+		return await this.#withRepoLock(compareKey(input.repo.commonDir), async () => {
+			const plan = await planAllocation({
+				report: input.report,
+				subject: input.subject,
+				repo: input.repo,
+				digests: await listReports(),
+				hopsOf: async (id) => await readHops(id),
+				isLive: (sessionId) => this.#host.getAgent(sessionId) !== void 0
+			}, input.settings);
+			if ("kind" in plan) throw new Error(`report-ledger: ${plan.message}`);
+			for (const gone of plan.stale) await this.#recordVanished(input.actor, gone);
+			if (plan.reclaimed !== void 0) await this.#reclaim(input.actor, plan.reclaimed);
+			const created = await this.#createWorktree(input.repo, plan.binding, input.base, input.settings.relativePaths);
+			if (!created.ok) throw new Error(`report-ledger: ${created.reason}`);
+			const head = await headOf(plan.binding.path);
+			return {
+				binding: {
+					...plan.binding,
+					...head === void 0 ? {} : { head }
+				},
+				retained: plan.retained,
+				reclaimSkipped: plan.reclaimSkipped,
+				stale: plan.stale,
+				...plan.reclaimed === void 0 ? {} : { reclaimed: plan.reclaimed }
+			};
+		});
+	}
+	/**
+	* Attach the linked working tree, recovering from a branch left by a crash.
+	*
+	* A previous attempt can have created the branch and then failed before the
+	* checkout existed, which leaves `-b` permanently refused on that name. Falling
+	* back to checking the existing branch out is what makes the retry work rather
+	* than dead-end, and it cannot take a live claim: git still refuses a branch
+	* another working tree holds.
+	*/
+	async #createWorktree(repo, binding, base, relativePaths) {
+		const first = await addWorktree({
+			repo,
+			path: binding.path,
+			branch: binding.branch,
+			base,
+			relativePaths
+		});
+		if (first.ok) return { ok: true };
+		if (classifyGitRefusal(first.stderr) !== "branch-exists") return {
+			ok: false,
+			reason: `could not create a working tree at ${binding.path}: ${first.stderr.trim()}`
+		};
+		const retry = await addWorktree({
+			repo,
+			path: binding.path,
+			branch: binding.branch,
+			checkoutExisting: true,
+			relativePaths
+		});
+		if (retry.ok) return { ok: true };
+		return {
+			ok: false,
+			reason: `the branch ${binding.branch} already existed and could not be checked out at ${binding.path}: ${retry.stderr.trim()}`
+		};
+	}
+	/**
+	* Record that a checkout the ledger believed it owned has already vanished.
+	*
+	* Nothing is removed — there is nothing left to remove — so this exists purely
+	* because leaving the belief in place is not free: the binding would be
+	* re-examined as a reclamation candidate on every later allocation, and a
+	* candidate whose directory is missing fails the cleanliness check, so it
+	* would be reported as having uncommitted changes. That sentence is wrong, and
+	* it is the kind of wrong that sends a reader looking for work nobody left.
+	*
+	* The hop is administrative, recorded with `touch: false` for the same reason
+	* a reclamation is: a vanished checkout is not a concluded report becoming
+	* active again.
+	*/
+	async #recordVanished(actor, gone) {
+		await this.#withLock(gone.report, async () => {
+			if (!reportExists(gone.report)) return;
+			await this.#record(gone.report, {
+				at: Date.now(),
+				actor,
+				action: "reclaimed",
+				to: [],
+				note: `checkout ${gone.path} was already gone; nothing to remove`
+			}, { touch: false });
+		});
+	}
+	/**
+	* Clear a checkout whose claim already ended, and record that it happened.
+	*
+	* Removal goes through git without a force flag, so an unclean tree refuses
+	* here exactly as it would for a human — and that refusal aborts the
+	* allocation rather than being stepped over, because taking something away is
+	* never the safe default.
+	*
+	* The hop is recorded with `touch: false`: clearing litter must not make a
+	* concluded report look like it just became active and float it to the top of
+	* every listing. It is still recorded, because taking something away from
+	* another report is precisely the act an audit exists for.
+	*/
+	async #reclaim(actor, target) {
+		const repo = await resolveRepo(target.path);
+		if (repo !== void 0) {
+			const removed = await removeWorktree(repo, target.path);
+			if (!removed.ok) throw new Error(`report-ledger: refusing to reclaim ${target.path} from ${target.report} — ${removed.stderr.trim()}`);
+		}
+		await this.#withLock(target.report, async () => {
+			if (!reportExists(target.report)) return;
+			await this.#record(target.report, {
+				at: Date.now(),
+				actor,
+				action: "reclaimed",
+				to: [],
+				note: `checkout ${target.path} cleared to stay within the retained budget`
+			}, { touch: false });
 		});
 	}
 	/**
+	* Undo a provisioning that a later step could not use.
+	*
+	* Deliberately without a force flag: a checkout that something has already
+	* modified refuses to go, and it should — the failure that triggered the
+	* rollback is not a licence to discard work. The caller is told whether the
+	* cleanup happened rather than being left to assume it did.
+	* @param binding - the binding whose checkout should go.
+	* @returns true when the checkout was removed.
+	*/
+	async discardWorktree(binding) {
+		const repo = await resolveRepo(binding.path);
+		if (repo === void 0) return false;
+		return (await removeWorktree(repo, binding.path)).ok;
+	}
+	/**
+	* Claim an id and provision a working tree for a report that does not exist yet.
+	*
+	* The two halves of a checkout's identity are circular: its branch and
+	* directory are named after the report, and the caller needs its path *before*
+	* the report is authored — a peer has to be created in it. This breaks the
+	* circle by claiming the id first, and gives the claim back if provisioning
+	* fails, so a failure does not burn a number.
+	* @param input - what to provision, and for whom.
+	* @returns the claimed id and the provisioned checkout.
+	* @throws when the session has no directory, is not in a repository, is in one
+	* with no commit, or a gate refuses the allocation.
+	*/
+	async provision(input) {
+		const cwd = this.#host.selfCwd?.(input.actor);
+		if (cwd === void 0) throw new Error(`report-ledger: cannot allocate a working tree for ${input.actor} — the session has no working directory, so there is no repository to allocate one in`);
+		const repo = await resolveRepo(cwd);
+		if (repo === void 0) throw new Error(`report-ledger: ${cwd} is not inside a git repository, so there is no repository to allocate a working tree in`);
+		const base = await headOf(cwd);
+		if (base === void 0) throw new Error(`report-ledger: ${cwd} has no commit yet, so there is nothing to branch a working tree from`);
+		const report = await allocateId();
+		try {
+			return {
+				report,
+				prepared: await this.prepareWorktree({
+					report,
+					subject: input.subject,
+					actor: input.actor,
+					repo,
+					base,
+					settings: input.settings
+				})
+			};
+		} catch (error) {
+			await discardUnwrittenId(report);
+			throw error;
+		}
+	}
+	/**
+	* Undo a provisioning whose report never got authored.
+	*
+	* A step after provisioning can fail — a peer that cannot be created, an
+	* authoring error — and without this the caller would leave a checkout and a
+	* burned number behind. Both halves are best-effort and reported rather than
+	* assumed: a checkout refuses to go once anything has touched it, and that
+	* refusal is the correct outcome, not an error to swallow.
+	* @param provisioned - what {@link ReportService.provision} returned.
+	* @returns what was actually undone.
+	*/
+	async rollbackProvision(provisioned) {
+		return {
+			worktree: await this.discardWorktree(provisioned.prepared.binding),
+			id: await discardUnwrittenId(provisioned.report)
+		};
+	}
+	/**
 	* Correct a report: the digest fields and/or the body, as the owner's act.
 	*
 	* The tension this resolves is real. A ledger's value comes from history being
@@ -8419,11 +9758,49 @@ var ReportService = class ReportService {
 function renderRow(row) {
 	const last = row.last === void 0 ? "-" : row.last;
 	const task = row.task === void 0 ? "" : ` task=${row.task}`;
-	return `${row.report} [${row.status}] ${row.subject}${task} | from=${row.from} to=${row.to.length === 0 ? "-" : row.to.join(",")} cc=${row.cc.length === 0 ? "-" : row.cc.join(",")} hops=${row.hops} last=${last}`;
+	const worktree = row.worktree === void 0 ? "" : ` wt=${row.worktree}`;
+	return `${row.report} [${row.status}] ${row.subject}${task}${worktree} | from=${row.from} to=${row.to.length === 0 ? "-" : row.to.join(",")} cc=${row.cc.length === 0 ? "-" : row.cc.join(",")} hops=${row.hops} last=${last}`;
 }
 //#endregion
 //#region src/report/timeline.ts
 /**
+* Timeline assembly: the recursive session subtree plus the reports that touch it.
+*
+* Kept free of any harness object so the whole thing is unit-testable: the
+* caller adapts `ctx.sessionQuery` and the ledger into the small structural
+* shapes below, and this module turns them into the JSON the tab renders.
+*
+* Ordering is DFS pre-order with siblings sorted by creation time, which is both
+* hierarchical and chronological — a child is always created after its parent,
+* so "top to bottom" reads as the collaboration actually unfolded.
+*
+* @module dsh-report-ledger/report/timeline
+*/
+/**
+* Collect the checkouts a set of reports is bound to.
+*
+* Only a report that carries a binding costs a hop read, so a ledger with no
+* working trees in play pays one pass over the digests and nothing more.
+* @param reports - the report digests in play.
+* @param readHops - read one report's hops.
+* @returns one lane per bound report.
+*/
+async function worktreeLanes(reports, readHops) {
+	const lanes = [];
+	for (const front of reports) {
+		const binding = front.worktree;
+		if (binding === void 0) continue;
+		lanes.push({
+			report: front.report,
+			path: binding.path,
+			...binding.branch === void 0 ? {} : { branch: binding.branch },
+			allocated: binding.allocated === true,
+			state: leaseState(await readHops(front.report))
+		});
+	}
+	return lanes.sort((left, right) => (left.branch ?? left.path).localeCompare(right.branch ?? right.path) || left.report.localeCompare(right.report));
+}
+/**
 * Build the subtree rooted at one session.
 *
 * A record is included only when its parent chain reaches the root, so a session
@@ -8520,11 +9897,13 @@ async function buildTimeline(deps, root) {
 	const bare = buildSubtree(await deps.listSessionRecords(), root);
 	const sessions = withTitles(bare, bare.length === 0 ? /* @__PURE__ */ new Map() : await deps.readTitles(bare.map((node) => node.id)));
 	const reports = reportsForSubtree(await deps.listReports(), sessions);
+	const worktrees = await worktreeLanes(reports, deps.readHops);
 	return {
 		root,
 		generatedAt: Date.now(),
 		sessions,
-		reports
+		reports,
+		worktrees
 	};
 }
 //#endregion
@@ -8539,6 +9918,57 @@ async function buildTimeline(deps, root) {
 *
 * @module dsh-report-ledger/report/tools
 */
+/**
+* The `worktree` parameter a tool advertises, or nothing at all.
+*
+* With the feature off the parameter does not exist, so a model cannot ask for
+* something the deployment will not do. That is a better answer than a parameter
+* that is always refused, and it keeps the promise that a deployment which does
+* not want working trees pays nothing for them.
+* @param runtime - the resolved feature state.
+* @param description - what the parameter does, for this tool.
+* @returns the parameter map to spread into a tool's parameters.
+*/
+function worktreeParam(runtime, description) {
+	return runtime.enabled ? { worktree: {
+		type: "boolean",
+		description
+	} } : {};
+}
+/** Provision a checkout, or explain that this deployment does not offer one. */
+async function requireWorktree(runtime, service, input) {
+	if (!runtime.enabled) throw new Error("report-ledger: this deployment has not enabled git worktree support, so no checkout can be allocated (the composition row sets worktree.enabled)");
+	return await service.provision({
+		subject: input.subject,
+		actor: input.actor,
+		settings: runtime.settings
+	});
+}
+/**
+* The lines describing a checkout that was just provisioned.
+*
+* The sharing sentence is not boilerplate. "Its own checkout" reads naturally as
+* "its own environment", and the difference becomes real the moment an agent
+* installs a hook or changes a setting — both of which reach every other
+* checkout, because only the working directory and index are private.
+* @param prepared - what provisioning produced.
+* @returns the lines to append to the tool output.
+*/
+function renderProvision(prepared) {
+	const lines = [`worktree=${prepared.binding.path} branch=${prepared.binding.branch}`];
+	if (prepared.reclaimed !== void 0) lines.push(`reclaimed ${prepared.reclaimed.report}'s checkout at ${prepared.reclaimed.path} to stay within the retained budget; that report remains closed`);
+	for (const skipped of prepared.reclaimSkipped) lines.push(`kept a checkout the budget would otherwise have cleared: ${skipped}`);
+	for (const gone of prepared.stale) lines.push(`recorded that ${gone.report}'s checkout at ${gone.path} was already gone — nothing to remove`);
+	lines.push("private: working directory and index. shared: config, hooks, the object store, and everything outside the checkouts.");
+	return lines;
+}
+/** The line describing what a mutation did with a checkout on disk. */
+function renderWorktreeOutcome(outcome, canRemove) {
+	if (outcome === void 0) return void 0;
+	if (outcome.action === "removed") return "working tree removed";
+	if (outcome.action === "kept") return canRemove ? "working tree kept (close with worktree:\"remove-if-clean\" to remove it)" : "working tree kept";
+	return `working tree NOT removed — git refused: ${outcome.detail ?? "unknown reason"}`;
+}
 /** Every tool's output is one compact text rendering of its canonical string value. */
 const stringOutput = {
 	schema: { type: "string" },
@@ -8561,7 +9991,7 @@ function actorOf(exec) {
 	return agent.id;
 }
 /** Render a mutation result as a compact model-facing report. */
-function renderMutation(front, outcomes) {
+function renderMutation(front, outcomes, prepared) {
 	const lines = [`${front.report} [${front.status}] ${front.subject}`, `authors=${front.authors.join(",")} to=${front.to.length === 0 ? "-" : front.to.join(",")} cc=${front.cc.length === 0 ? "-" : front.cc.join(",")} hops=${front.hops}`];
 	if (outcomes.length > 0) {
 		const delivered = outcomes.filter((outcome) => outcome.status === "delivered").map((outcome) => outcome.targetId);
@@ -8569,6 +9999,7 @@ function renderMutation(front, outcomes) {
 		if (delivered.length > 0) lines.push(`delivered to: ${delivered.join(", ")}`);
 		if (queued.length > 0) lines.push(`held for absent recipient (delivered automatically when it becomes resident): ${queued.join(", ")}`);
 	}
+	if (prepared !== void 0) lines.push(...renderProvision(prepared));
 	return lines.join("\n");
 }
 /** Derive a concise report subject from a task description. */
@@ -8578,13 +10009,34 @@ function subjectFrom(task, name) {
 	return name === void 0 ? trimmed : `${name}: ${trimmed}`;
 }
 /**
+* Render what was observed about a peer's first turn.
+*
+* A delivery certifies one thing only: the digest reached a live agent. It says
+* nothing about whether a turn opened, and a turn that dies at step 1 — an
+* unresolvable prompt variable, no model route, no composition — leaves exactly
+* the same `delivered` hop and the same `live` roster row as a peer that is hard
+* at work. This line is the difference between those two, and it exists because
+* the difference cost a real caller a long, silent wait.
+* @param receipt - the observation, or `undefined` when the host could not make one.
+* @param windowMs - the observation window the receipt was bounded by.
+* @returns one line for the tool output, or `undefined` when there is nothing to say.
+*/
+function describeReceipt(receipt, windowMs) {
+	if (receipt === void 0) return void 0;
+	if (receipt.kind === "running") return `the peer's first turn is running (observed for ${windowMs} ms after the assignment landed)`;
+	if (receipt.kind === "failed") return `⚠ the peer's first turn FAILED before doing any work: ${receipt.error ?? receipt.reason ?? "unknown error"}`;
+	if (receipt.kind === "unstarted") return "⚠ the assignment is in the peer's inbox but no turn opened — nothing is working on it";
+	if (receipt.reason === "completed") return `the peer's first turn completed within ${windowMs} ms — read the report for its answer`;
+	return `the peer's first turn ended within ${windowMs} ms (${receipt.reason ?? "settled"}) — nothing is working on it now`;
+}
+/**
 * Register the report and peer tools on the tools registry.
 * @param ctx - the plugin context (`tools` injected).
 * @param service - the report service backing the tools.
 * @param peers - the peer service backing discovery and creation.
 * @returns a disposer removing every registration.
 */
-function registerReportTools(ctx, service, peers) {
+function registerReportTools(ctx, service, peers, worktree) {
 	const disposers = [];
 	disposers.push(ctx.tools.register(defineTool({
 		name: "report_author",
@@ -8622,22 +10074,37 @@ function registerReportTools(ctx, service, peers) {
 			parent: {
 				type: "string",
 				description: "Report id this one answers, linking it into the thread."
-			}
+			},
+			...worktreeParam(worktree, "Allocate this report its own git checkout, on a branch named after the report. Only the working directory and index are private; config, hooks and the object store are shared with every other checkout.")
 		},
 		output: stringOutput,
 		execute: async (args, exec) => {
 			const input = args;
-			const result = await service.author({
+			const actor = actorOf(exec);
+			const provisioned = input.worktree === true ? await requireWorktree(worktree, service, {
 				subject: input.subject,
-				body: input.body,
-				actor: actorOf(exec),
-				...input.to === void 0 ? {} : { to: input.to },
-				...input.cc === void 0 ? {} : { cc: input.cc },
-				...input.task === void 0 ? {} : { task: input.task },
-				...input.artifacts === void 0 ? {} : { artifacts: input.artifacts },
-				...input.parent === void 0 ? {} : { parent: input.parent }
-			});
-			return renderMutation(result.front, result.outcomes);
+				actor
+			}) : void 0;
+			try {
+				const result = await service.author({
+					subject: input.subject,
+					body: input.body,
+					actor,
+					...input.to === void 0 ? {} : { to: input.to },
+					...input.cc === void 0 ? {} : { cc: input.cc },
+					...input.task === void 0 ? {} : { task: input.task },
+					...input.artifacts === void 0 ? {} : { artifacts: input.artifacts },
+					...input.parent === void 0 ? {} : { parent: input.parent },
+					...provisioned === void 0 ? {} : {
+						reportId: provisioned.report,
+						worktree: provisioned.prepared.binding
+					}
+				});
+				return renderMutation(result.front, result.outcomes, provisioned?.prepared);
+			} catch (error) {
+				if (provisioned !== void 0) await service.rollbackProvision(provisioned);
+				throw error;
+			}
 		}
 	})));
 	disposers.push(ctx.tools.register(defineTool({
@@ -8769,7 +10236,7 @@ function registerReportTools(ctx, service, peers) {
 	})));
 	disposers.push(ctx.tools.register(defineTool({
 		name: "report_list",
-		description: "List report digests from the ledger — no bodies, so this is the cheap way to survey a long-running collaboration. Filter by `session` to see every report that touches one agent (authored, addressed, copied, or contributed to), by `status`, or by `task` to pull up one collaboration across every session it touched. The task label is matched case-insensitively and partially, so \"payments\" finds \"payments-rework\". Use it to find the report id you need before reading it, or to check what a teammate is still waiting on.",
+		description: "List report digests from the ledger — no bodies, so this is the cheap way to survey a long-running collaboration. Filter by `session` to see every report that touches one agent (authored, addressed, copied, or contributed to), by `status`, or by `task` to pull up one collaboration across every session it touched. The task label is matched case-insensitively and partially, so \"payments\" finds \"payments-rework\". `worktree` matches a bound working tree by branch or path, which is the way to find out who is working in which checkout. Use it to find the report id you need before reading it, or to check what a teammate is still waiting on.",
 		parameters: {
 			session: {
 				type: "string",
@@ -8788,6 +10255,10 @@ function registerReportTools(ctx, service, peers) {
 				type: "string",
 				description: "Only reports carrying this collaboration label (partial match, case-insensitive)."
 			},
+			worktree: {
+				type: "string",
+				description: "Only reports bound to a working tree whose branch or path contains this text (partial match, case-insensitive)."
+			},
 			limit: {
 				type: "integer",
 				description: "Maximum rows (default 50, capped at 200)."
@@ -8800,9 +10271,13 @@ function registerReportTools(ctx, service, peers) {
 				...input.session === void 0 ? {} : { session: input.session },
 				...input.status === void 0 ? {} : { status: input.status },
 				...input.task === void 0 ? {} : { task: input.task },
+				...input.worktree === void 0 ? {} : { worktree: input.worktree },
 				...input.limit === void 0 ? {} : { limit: input.limit }
 			});
-			if (rows.length === 0) return input.task === void 0 ? "no reports match" : `no reports carry a task matching ${JSON.stringify(input.task)}`;
+			if (rows.length === 0) {
+				if (input.worktree !== void 0 && input.worktree.trim() !== "") return `no reports are bound to a working tree matching ${JSON.stringify(input.worktree)}`;
+				return input.task === void 0 ? "no reports match" : `no reports carry a task matching ${JSON.stringify(input.task)}`;
+			}
 			const lines = [`${rows.length} report(s):`, ...rows.map(renderRow)];
 			const taskFilter = input.task?.trim();
 			if (taskFilter !== void 0 && taskFilter !== "") {
@@ -8850,13 +10325,74 @@ function registerReportTools(ctx, service, peers) {
 			note: {
 				type: "string",
 				description: "Why it is finished, or what concluded it. Recorded on the hop."
+			},
+			...worktree.enabled ? { worktree: {
+				type: "string",
+				enum: ["keep", "remove-if-clean"],
+				description: "What to do with a bound git checkout. keep (the default) leaves it exactly as it is; remove-if-clean deletes it only if it has no uncommitted work, and reports git's refusal otherwise."
+			} } : {}
+		},
+		output: stringOutput,
+		execute: async (args, exec) => {
+			const input = args;
+			const result = await service.close(input.report, actorOf(exec), input.note, { worktree: input.worktree ?? worktree.onClose });
+			return [
+				renderMutation(result.front, result.outcomes),
+				renderWorktreeOutcome(result.worktree, worktree.enabled),
+				"closed — later activity on this report reopens it automatically"
+			].filter((line) => line !== void 0).join("\n");
+		}
+	})));
+	disposers.push(ctx.tools.register(defineTool({
+		name: "report_release",
+		description: "Hand back a report's claim on its git checkout without concluding the report. Use it when the work in that checkout is done but the conversation is not: the checkout stays on disk exactly as you left it, and the claim — which is what stops another agent from taking the same branch — ends. A claim is released once; closing a report releases it too, so this is only needed while the report stays open.",
+		parameters: {
+			report: {
+				type: "string",
+				required: true,
+				description: "Report id whose checkout claim should end."
+			},
+			note: {
+				type: "string",
+				description: "Why the claim is being handed back. Recorded on the hop."
 			}
 		},
 		output: stringOutput,
 		execute: async (args, exec) => {
 			const input = args;
-			const result = await service.close(input.report, actorOf(exec), input.note);
-			return `${renderMutation(result.front, result.outcomes)}\nclosed — later activity on this report reopens it automatically`;
+			const result = await service.release(input.report, actorOf(exec), input.note);
+			const binding = result.front.worktree;
+			return [renderMutation(result.front, result.outcomes), binding === void 0 ? "claim released" : `claim released; the checkout at ${binding.path} is untouched and stays traceable to ${result.front.report}`].join("\n");
+		}
+	})));
+	if (worktree.enabled) disposers.push(ctx.tools.register(defineTool({
+		name: "report_lease",
+		description: "Claim an EXISTING git checkout for a report — the counterpart to report_release. Use it to pick up a checkout that already exists: one a human made, one a previous report left behind, or one a report released earlier. A branch is held by exactly one live report at a time, so a competing claim is refused and the refusal names the holder and its authors. The branch is read from the checkout itself, so pass one only to require it.",
+		parameters: {
+			report: {
+				type: "string",
+				required: true,
+				description: "Report id that will hold the checkout. Only its owners may claim on its behalf."
+			},
+			path: {
+				type: "string",
+				required: true,
+				description: "Absolute path of the checkout to claim."
+			},
+			branch: {
+				type: "string",
+				description: "The branch the checkout must be on. Omit to take whichever branch it is really on."
+			}
+		},
+		output: stringOutput,
+		execute: async (args, exec) => {
+			const input = args;
+			const result = await service.lease(input.report, actorOf(exec), {
+				path: input.path,
+				...input.branch === void 0 ? {} : { branch: input.branch }
+			});
+			const binding = result.front.worktree;
+			return [renderMutation(result.front, result.outcomes), binding === void 0 ? "claimed" : `claimed ${binding.branch ?? "(detached HEAD)"} at ${binding.path}${binding.head === void 0 ? "" : ` @ ${binding.head.slice(0, 12)}`}`].join("\n");
 		}
 	})));
 	disposers.push(ctx.tools.register(defineTool({
@@ -8950,7 +10486,7 @@ function registerReportTools(ctx, service, peers) {
 	})));
 	disposers.push(ctx.tools.register(defineTool({
 		name: "peer_start",
-		description: "Open a new independent agent session — a peer, not a subordinate. A peer is a root session with its own lifecycle that outlives this turn, so it is the right move when the work is long-running, when you want a partner that keeps its own context across days, or when a task should not be nested under you. This creates the session, records that you started it (which is what later lets you address it directly), and hands it the task as a REPORT — so the assignment is durable and traceable, and the peer can answer by contributing to that same report. Do not use it as a cheaper subagent: for a bounded subtask, delegation is the right tool.",
+		description: "Open a new independent agent session — a peer, not a subordinate. A peer is a root session with its own lifecycle that outlives this turn, so it is the right move when the work is long-running, when you want a partner that keeps its own context across days, or when a task should not be nested under you. This creates the session, records that you started it (which is what later lets you address it directly), and hands it the task as a REPORT — so the assignment is durable and traceable, and the peer can answer by contributing to that same report. The output also reports what became of the peer's first turn (running, already ended, or failed): a delivered digest proves only that the peer is resident, never that work started. Do not use this as a cheaper subagent: for a bounded subtask, delegation is the right tool.",
 		parameters: {
 			task: {
 				type: "string",
@@ -8960,36 +10496,62 @@ function registerReportTools(ctx, service, peers) {
 			name: {
 				type: "string",
 				description: "Optional short display name for the peer (60 characters or fewer)."
-			}
+			},
+			...worktreeParam(worktree, "Give the peer its own git checkout, on a branch named after the assignment report, and start it there instead of in your directory. Only the working directory and index are private; config, hooks and the object store are shared with every other checkout.")
 		},
 		output: stringOutput,
 		execute: async (args, exec) => {
 			const input = args;
 			const actor = actorOf(exec);
-			const started = await peers.start(actor, {
-				task: input.task,
-				...input.name === void 0 ? {} : { name: input.name }
-			});
-			const result = await service.author({
-				subject: subjectFrom(input.task, started.name),
-				body: [
-					`本会话由 ${actor} 开启，你是它的**同伴**而非下属：你有自己的生命周期，会比这一轮活得更久。`,
-					"",
-					`要回复或继续这个话题，用 report_contribute 追加到本汇报——它会成为我们之间的线程；需要直接交代新事情时用 report_author 并 to=[${actor}]。`,
-					"",
-					"## 任务",
-					input.task
-				].join("\n"),
-				actor,
-				to: [started.sessionId],
-				task: started.name
-			});
+			const subject = subjectFrom(input.task, input.name);
+			const provisioned = input.worktree === true ? await requireWorktree(worktree, service, {
+				subject,
+				actor
+			}) : void 0;
+			let started;
+			let result;
+			try {
+				started = await peers.start(actor, {
+					task: input.task,
+					...input.name === void 0 ? {} : { name: input.name },
+					...provisioned === void 0 ? {} : { cwd: provisioned.prepared.binding.path }
+				});
+				result = await service.author({
+					subject,
+					body: [
+						`本会话由 ${actor} 开启，你是它的**同伴**而非下属：你有自己的生命周期，会比这一轮活得更久。`,
+						...provisioned === void 0 ? [] : [
+							"",
+							`你的工作目录是一个**独立的 git 检出**：${provisioned.prepared.binding.path}（分支 ${provisioned.prepared.binding.branch}）。`,
+							"独立的是工作目录与索引；config、hooks、对象库与其它检出共享，所以装 hook 或改配置会影响所有检出。"
+						],
+						"",
+						`要回复或继续这个话题，用 report_contribute 追加到本汇报——它会成为我们之间的线程；需要直接交代新事情时用 report_author 并 to=[${actor}]。`,
+						"",
+						"## 任务",
+						input.task
+					].join("\n"),
+					actor,
+					to: [started.sessionId],
+					task: started.name,
+					...provisioned === void 0 ? {} : {
+						reportId: provisioned.report,
+						worktree: provisioned.prepared.binding
+					}
+				});
+			} catch (error) {
+				if (provisioned !== void 0) await service.rollbackProvision(provisioned);
+				throw error;
+			}
+			const receipt = describeReceipt(await peers.receipt(started.sessionId, DEFAULT_RECEIPT_MS), DEFAULT_RECEIPT_MS);
 			return [
 				`opened peer ${started.sessionId}${started.name === void 0 ? "" : ` (name=${started.name})`}`,
 				started.cwd === void 0 ? "" : `cwd=${started.cwd}`,
 				`peers you have started: ${started.started}`,
 				`assignment report: ${result.front.report}`,
+				...provisioned === void 0 ? [] : renderProvision(provisioned.prepared),
 				renderMutation(result.front, result.outcomes),
+				receipt === void 0 ? "" : receipt,
 				`Address this peer later with report_send / report_cc to=${started.sessionId}, or see everyone with peer_list.`
 			].filter((line) => line !== "").join("\n");
 		}
@@ -9048,6 +10610,107 @@ function toSessionRecord(entry) {
 	};
 }
 /**
+* Resolve the model route a peer is created with.
+*
+* This is the difference between a peer that works and a peer that dies silently:
+* an agent with no route cannot resolve `{{model}}` while its prompt is
+* assembled, so its first turn ends at step 1 with an `error` reason — before a
+* single tool call, which is why the ledger's `delivered` and the roster's `live`
+* both stay perfectly green while nothing whatsoever happens.
+*
+* The starter's live route is the right source, in the same order the harness's
+* own delegation uses: the session's request header records the route actually in
+* force after request-time selection, creation options are the fallback before
+* the first request, and only a starter carrying neither falls through to the
+* deployment default. When even that is absent the peer is refused rather than
+* created doomed.
+* @param caller - the live starter agent, when it is resident.
+* @param fallback - the deployment default model service, when it is mounted.
+* @returns the route fields to pass as creation options.
+* @throws when no source can name a provider and model.
+*/
+function peerRoute(caller, fallback) {
+	const fromHeader = caller?.session.requestHeader()?.config;
+	const created = caller?.options;
+	const selection = fallback?.currentSelection();
+	const provider = fromHeader?.provider ?? created?.provider ?? selection?.provider;
+	const model = fromHeader?.model ?? created?.model ?? selection?.model;
+	if (provider === void 0 || model === void 0) throw new Error("report-ledger: cannot start a peer — no model route could be resolved for it. The starting session carries no provider/model and this deployment exposes no default model selection, so the peer would be created unable to assemble a prompt (its first turn would fail).");
+	const reasoningEffort = fromHeader?.reasoningEffort ?? created?.reasoningEffort ?? selection?.reasoningEffort;
+	return {
+		provider,
+		model,
+		...reasoningEffort === void 0 ? {} : { reasoningEffort },
+		...created?.maxTokens === void 0 ? {} : { maxTokens: created.maxTokens }
+	};
+}
+/**
+* Whether a session's log already records an opened turn.
+* @param session - the live session.
+* @returns true when at least one `turn/start` was appended.
+*/
+function hasOpenedTurn(session) {
+	return session.snapshotEvents().some((event) => event !== null && typeof event === "object" && event.type === "turn/start");
+}
+/**
+* Read the last turn's stop reason out of a session log.
+* @param session - the live session.
+* @returns the reason kind and, for an error, its message.
+*/
+function lastTurnReason(session) {
+	const events = session.snapshotEvents();
+	for (let index = events.length - 1; index >= 0; index -= 1) {
+		const event = events[index];
+		if (event === null || typeof event !== "object") continue;
+		const record = event;
+		if (record.type !== "turn/end") continue;
+		const data = record.data;
+		if (data === null || typeof data !== "object") return {};
+		const reason = data.reason;
+		if (reason === null || typeof reason !== "object") return {};
+		const fields = reason;
+		const error = fields.error;
+		const message = error === null || typeof error !== "object" ? void 0 : str(error, "message");
+		return {
+			...typeof fields.kind === "string" ? { kind: fields.kind } : {},
+			...message === void 0 ? {} : { message }
+		};
+	}
+	return {};
+}
+/**
+* Wait for one agent to reach quiescence, bounded.
+*
+* The bound is what makes the answer usable: a peer that opened a turn and is
+* still working after it elapses is reported as running, while a turn that dies
+* (the silent failure mode this exists to expose) settles in milliseconds. The
+* timer is an observation window only — it is unref'd, so it can never be a
+* reason for the host to stay alive.
+* @param agent - the agent to observe.
+* @param timeoutMs - the window length.
+* @returns true when quiescence came first, false when the window closed first.
+*/
+function settledWithin(agent, timeoutMs) {
+	return new Promise((resolve) => {
+		let finished = false;
+		const finish = (settled) => {
+			if (finished) return;
+			finished = true;
+			clearTimeout(timer);
+			resolve(settled);
+		};
+		const timer = setTimeout(() => {
+			finish(false);
+		}, Math.max(timeoutMs, 0));
+		timer.unref?.();
+		agent.whenIdle().then(() => {
+			finish(true);
+		}, () => {
+			finish(true);
+		});
+	});
+}
+/**
 * Build every host capability this plugin consumes.
 *
 * Agent lookup goes through `ctx.agents`, and delivery uses the `Agent`'s own
@@ -9093,6 +10756,10 @@ function buildHost(ctx) {
 		async describe(sessionId) {
 			return (await readTitles([sessionId])).get(sessionId);
 		},
+		selfCwd(sessionId) {
+			const cwd = (ctx.agents.get(sessionId)?.session?.header)?.cwd;
+			return typeof cwd === "string" && cwd !== "" ? cwd : void 0;
+		},
 		readTitles,
 		async listSessionRecords() {
 			const query = sessionQuery();
@@ -9128,11 +10795,32 @@ async function readDetail(id) {
 * gate, {@link Config.maxPeersPerAgent} bounds the blast radius, the peer
 * inherits the caller's own working directory (so it cannot be pointed at an
 * unrelated tree), and every creation is attributed in the roster log.
+*
+* It is also the only place that must supply what a fresh agent cannot supply
+* itself. A root session is born with no composition and no model route:
+*
+*  - **Composition.** The peer joins the starter's standing preset
+*    (`composeFrom`), which is a bind to the SAME generation the starter runs —
+*    not a re-resolution of the preset by id, so a preset edited or deleted since
+*    cannot hand the peer a different world than its starter's. A deployment with
+*    no roster yields no join and no error, exactly like a delegated child.
+*  - **Route.** The peer inherits the starter's provider/model/reasoning effort.
+*    Without it, prompt assembly cannot resolve `{{model}}` and every turn of the
+*    peer dies at step 1 before its first tool call.
+*  - **Preset identity.** The joined preset is recorded in the durable session
+*    header, so a cold read of the peer's log rebuilds the composition it
+*    actually ran under instead of the deployment default.
+*
+* `confirmPeer` closes the other half of the same problem: a peer that turns out
+* to be unable to run must be visible to the agent that just started it, rather
+* than reported as a successful hand-off.
 * @param ctx - the plugin context.
 * @param host - the session-reading bundle.
 * @returns the peer host capability.
 */
 function buildPeerHost(ctx, host) {
+	const presets = () => ctx.get("agentPresets");
+	const defaultModel = () => ctx.get("agentDefaultModel");
 	return {
 		selfCwd(sessionId) {
 			const cwd = ((ctx.agents.get(sessionId)?.session)?.header)?.cwd;
@@ -9147,9 +10835,21 @@ function buildPeerHost(ctx, host) {
 		readTitles: (ids) => host.readTitles(ids),
 		listReports: () => listReports(),
 		async createPeer(input) {
+			const caller = ctx.agents.get(input.startedBy);
+			if (caller === void 0) throw new Error(`report-ledger: cannot start a peer from ${input.startedBy} — the starting session is not resident, so the peer has no composition and no model route to inherit`);
+			const agentOptions = peerRoute(caller, defaultModel());
+			const agentPreset = presets()?.composedPreset(caller.ctx);
+			const meta = {
+				...input.cwd === void 0 ? {} : { cwd: input.cwd },
+				...agentPreset === void 0 ? {} : { agentPreset }
+			};
 			const handle = await ctx.agents.create({
 				sessionId: input.sessionId,
-				...input.cwd === void 0 ? {} : { meta: { cwd: input.cwd } }
+				...Object.keys(meta).length === 0 ? {} : { meta },
+				agentOptions,
+				setup: (agentCtx) => {
+					presets()?.composeFrom(agentCtx, caller.ctx);
+				}
 			});
 			return {
 				id: String(handle.agent.id),
@@ -9157,6 +10857,22 @@ function buildPeerHost(ctx, host) {
 					handle.agent.steer(message);
 				}
 			};
+		},
+		async confirmPeer(sessionId, timeoutMs) {
+			const agent = ctx.agents.get(sessionId);
+			if (agent === void 0) return void 0;
+			if (!hasOpenedTurn(agent.session)) return { kind: "unstarted" };
+			if (!await settledWithin(agent, timeoutMs)) return { kind: "running" };
+			const reason = lastTurnReason(agent.session);
+			if (reason.kind === "error") return {
+				kind: "failed",
+				reason: "error",
+				...reason.message === void 0 ? {} : { error: reason.message }
+			};
+			return {
+				kind: "settled",
+				...reason.kind === void 0 ? {} : { reason: reason.kind }
+			};
 		}
 	};
 }
@@ -9169,10 +10885,11 @@ function apply(ctx, config) {
 	const host = buildHost(ctx);
 	const service = new ReportService(host);
 	const peers = new PeerService(buildPeerHost(ctx, host), config?.maxPeersPerAgent ?? 8);
-	ctx.effect(() => registerReportTools(ctx, service, peers), "report-ledger: model tools");
+	const worktree = resolveWorktree(config?.worktree);
+	ctx.effect(() => registerReportTools(ctx, service, peers, worktree), "report-ledger: model tools");
 	ctx.on("agent/created", (payload) => {
 		const sessionId = String(payload?.agent?.id ?? "");
-		if (sessionId === "") return;
+		if (sessionId === "") return void 0;
 		service.flushForAgent(sessionId).catch((error) => {
 			ctx.logger?.warn?.(`report-ledger: deferred delivery to ${sessionId} failed: ${String(error)}`);
 		});
@@ -9184,9 +10901,14 @@ function apply(ctx, config) {
 			timeline: async (root) => buildTimeline({
 				listSessionRecords: () => host.listSessionRecords(),
 				readTitles: (ids) => host.readTitles(ids),
-				listReports: () => listReports()
+				listReports: () => listReports(),
+				readHops: (report) => readHops(report)
 			}, root),
-			report: readDetail
+			report: readDetail,
+			worktrees: async () => buildWorktreeReport({
+				listReports: () => listReports(),
+				readHops: (report) => readHops(report)
+			}, worktree.settings, worktree.enabled)
 		};
 		scoped.effect(() => {
 			const disposeReport = webServer.register({
@@ -9199,7 +10921,13 @@ function apply(ctx, config) {
 				path: TIMELINE_PATH,
 				handler: createTimelineHandler(deps)
 			});
+			const disposeWorktrees = webServer.register({
+				kind: "exact",
+				path: WORKTREES_PATH,
+				handler: createWorktreesHandler(deps)
+			});
 			return () => {
+				disposeWorktrees();
 				disposeTimeline();
 				disposeReport();
 			};