@staix/agent-hub 0.28.0 → 0.30.0

package/src/cli/main.ts

@@ -105,6 +105,8 @@ import { benchPreflight, defaultIo, runBench } from "./bench.ts";
 import { ADDONS, isAddon, type AddonName } from "../hub/tooling.ts";
 import { goalCommand, memoryCommand, memoryStaleAnchorsCommand } from "./memory.ts";
 import { runSpecs, runSpecsStamp } from "./specs.ts";
+import { confirmTidy, planTidy, realTidyGit, rowsFromReply, type TidyGit } from "./worktree-tidy.ts";
+import { renderTidyPreview, renderTidyResult, renderWorktrees } from "./worktrees-output.ts";
 import { formatMemoryStaleAnchors } from "../hub/memory-stale-anchors.ts";
 import { AGENT_MEM_VERSION, assertAgentMemVersion, selectedMemoryProfile } from "../hub/memory-profile.ts";
 import { checkMemoryProfiles, formatMemoryProfileCheck } from "../hub/memory-profile-check.ts";
@@ -2003,6 +2005,18 @@ const commands: Record<string, () => Promise<void> | void> = {
     } finally { hub.close(); }
   },
 
+  title: async () => {
+    const [peer, ...words] = args;
+    if (!peer || !words.length) fail("usage: ahub title <peer> <text...>");
+    const hub = await connect();
+    try {
+      const reply = await hub.request({ t: "title", peer, title: words.join(" ") }, 35_000).catch(() => ({ ok: false, error: "session title result is unconfirmed; the title may have been applied; check ahub status before retrying" }));
+      if (reply.ok === false && reply.error === "no answer from the hub within 35 s") fail("session title request timed out; the title may have been applied; check ahub status before retrying");
+      if (reply.ok !== true) fail(String(reply.error ?? `session title refused: ${String(reply.reason ?? "invalid")}; refresh ahub status, then retry`));
+      console.log(`${peer}: session title updated`);
+    } finally { hub.close(); }
+  },
+
   permission: async () => {
     const positional = args.filter(arg => arg !== "--yes");
     const [peer, mode] = positional;
@@ -2444,6 +2458,31 @@ const commands: Record<string, () => Promise<void> | void> = {
       process.exitCode = await runSpecsStamp(args.slice(1), cwd, loadConfig(cwd).specs, { isTTY: !!rl, ask: async question => /^y(es)?$/i.test((await rl!.question(`${question} [y/N] `)).trim()) });
     } finally { rl?.close(); }
   },
+  // #1057: `ahub worktrees [--json]` lists live and settled worktrees; `tidy` previews what is safe to remove; `tidy --confirm <fingerprint>` removes it, in THIS process,
+  // never the daemon's. `--confirm` is console class (classifyPeerCommand) and refused under --live-test, so an agent can only list and preview.
+  worktrees: async () => {
+    const options = outputOptions();
+    const rest = outputArguments();
+    const sub = rest[0] === "tidy" ? "tidy" : undefined;
+    const flags = sub ? rest.slice(1) : rest;
+    const at = flags.indexOf("--confirm");
+    const fingerprint = at >= 0 ? flags[at + 1] : undefined;
+    const known = flags.every((arg, i) => arg === "--confirm" || i === at + 1 && at >= 0);
+    if ((rest.length && !sub && rest.some(arg => !arg.startsWith("--"))) || !known || (at >= 0 && (!sub || fingerprint === undefined || fingerprint.startsWith("--"))) || (sub === undefined && at >= 0)) fail("usage: ahub worktrees [--json] | tidy [--json] | tidy --confirm <fingerprint>");
+    const hub = await connect();
+    const reply = await hub.request({ t: "worktrees" }, 20_000);
+    hub.close();
+    if (!reply.ok) return fail(String(reply.error ?? "the worktree shelf is unavailable"));
+    if (!sub) return options.json ? console.log(JSON.stringify({ live: reply.live, settled: reply.settled, complete: reply.complete }, null, 2)) : printOutput(renderWorktrees(reply, options.columns, Date.now()), options.color);
+    // tidy: read-only git in this process to decide what is safe; the daemon only said which rows are settled.
+    const git: TidyGit = realTidyGit((argv, dir) => { const run = hubGitSync(argv, { cwd: dir, encoding: "utf8", timeout: 20_000, maxBuffer: 4 * 1024 * 1024, env: hubGitEnv(process.env, { repositoryIsolation: true }) }); return run.error ? undefined : { status: run.status, stdout: String(run.stdout ?? "") }; });
+    const plan = planTidy(rowsFromReply(reply.settled ?? [], cwd, git), cwd, git);
+    if (at < 0) return options.json ? console.log(JSON.stringify({ entries: plan.entries, removable: plan.removable, fingerprint: plan.fingerprint }, null, 2)) : printOutput(renderTidyPreview(plan, options.columns), options.color);
+    const result = confirmTidy(plan, fingerprint!, cwd, git);
+    if (!result.ok) return fail(result.error);
+    if (options.json) return console.log(JSON.stringify({ outcomes: result.outcomes }, null, 2));
+    printOutput(renderTidyResult(result.outcomes, options.columns), options.color);
+  },
   usage: async () => {
     const options = outputOptions();
     const rest = outputArguments();

package/src/cli/output.ts

@@ -14,6 +14,7 @@ import type { SpecsStatus } from "../hub/specs-task.ts";
 
 export interface DoctorCheck { section: "Tools" | "Hub" | "Config" | "Models" | "Memory"; level: "ok" | "warn" | "fail" | "unknown"; name: string; detail: string }
 export interface StatusOutput {
+  controlWriteTiming?: { active: number; slowRequests: number; blockedLoopSamples: number; droppedActive: number; droppedRecent: number; droppedLogs: number; droppedSpans?: number; droppedMetadata?: number; expiredRequests?: number };
   specs?: SpecsStatus & { missingBlockHint?: boolean };
   queueBackpressure?: QueueBackpressureStatus;
   pendingRestart?: readonly { key: string; reason: string }[];
@@ -213,6 +214,10 @@ export function renderStatus(data: StatusOutput, columns?: number, now = Date.no
   if (data.roleInfo) data = { ...data, peers: Object.fromEntries(Object.entries(data.peers).map(([peer, value]) => [peer, { ...value, ...data.roleInfo?.[peer] }])) };
   const out = lines(`agent-hub${data.version ? ` ${data.version}` : ""}  pid ${data.pid ?? "unknown"}  control 127.0.0.1:${data.controlPort ?? "unknown"}`, columns, "info");
   if (data.cwd) out.push(...lines(data.cwd, columns));
+  const timing = data.controlWriteTiming;
+  if (full && timing && Object.values(timing).every(value => Number.isSafeInteger(value) && value >= 0)) {
+    out.push(...lines(`control writes: active ${timing.active}, slow ${timing.slowRequests}, loop delays ${timing.blockedLoopSamples}, dropped ${timing.droppedActive + timing.droppedLogs + (timing.droppedSpans ?? 0) + (timing.droppedMetadata ?? 0)}, expired ${timing.expiredRequests ?? 0}; timings in hub.log`, columns, timing.slowRequests || timing.blockedLoopSamples ? "attention" : undefined));
+  }
   const specs = data.specs;
   if (specs && [specs.specCount, specs.documents, specs.errors, specs.stale].every(value => Number.isSafeInteger(value) && value >= 0)
     && (specs.specCount > 0 || specs.documents > 0 || specs.errors > 0)) {

package/src/cli/recovery-package.ts

@@ -127,6 +127,9 @@ export function verifyRecoveryTarget(kind: "restart" | "upgrade", root: string,
   return verifyPackage(root, version, recoveryPackageOptions(kind, root));
 }
 
+/** #1120: the documentation checker that `ahub sdlc authorize-release` and release readiness spawn. A capture without it can never record release consent. */
+export const RELEASE_CHECKER = "scripts/check-docs.mjs";
+// ponytail: the checker is copied and kept by prune, but is not in packageDigest. Widening the digest would make every release staged before this change refuse as "cached release changed". Ceiling: a tampered checker in a capture is not detected by the digest. Upgrade path: fold it into packageDigest with a digest-version bump once no pre-#1120 capture or cached release remains.
 const RUNTIME_ASSETS = ["src", "plugins", "templates", ".claude-plugin", "package.json", "README.md", "LICENSE", "CHANGELOG.md"] as const;
 function runtimeDirectory(directory: string): void {
   let info;
@@ -159,6 +162,12 @@ function preserveRuntimeAssets(sourceRoot: string, destination: string, expected
   mkdirSync(temporary, { mode: 0o700 });
   try {
     for (const name of RUNTIME_ASSETS) cpSync(join(sourceRoot, name), join(temporary, name), { recursive: true, dereference: false });
+    // Absent in a source that predates the checker (a registry package before #1120 ships it): the capture then reports the checker as unavailable, never a stale document.
+    if (existsSync(join(sourceRoot, RELEASE_CHECKER))) {
+      if (!lstatSync(join(sourceRoot, RELEASE_CHECKER)).isFile()) throw new Error(`${RELEASE_CHECKER} must be a regular file to be preserved in a runtime capture; replace it with a regular file`);
+      mkdirSync(join(temporary, dirname(RELEASE_CHECKER)), { recursive: true });
+      cpSync(join(sourceRoot, RELEASE_CHECKER), join(temporary, RELEASE_CHECKER), { dereference: false });
+    }
     preserveRuntimeDependencies(sourceRoot, temporary);
     if (digest(temporary, true) !== expectedDigest || digest(sourceRoot) !== expectedDigest)
       throw new Error("source package changed while being preserved");

package/src/cli/worktree-tidy.ts

@@ -0,0 +1,158 @@
+import { createHash } from "node:crypto";
+import { statSync } from "node:fs";
+import { join, resolve } from "node:path";
+
+/**
+ * #1057 D5: `ahub worktrees tidy`. This module is the ONLY place a worktree or a local branch is removed, and it runs in the person's own CLI
+ * process: the daemon never imports it (a test greps for that). A preview reads facts and runs read-only git; `--confirm <fingerprint>` re-reads
+ * everything, refuses the whole run if the row set changed, and otherwise runs exactly two argv shapes per row:
+ *
+ *   git -C <root> worktree remove <path>        (no --force: git itself refuses a dirty or locked tree)
+ *   git -C <root> branch -d <branch>            (never -D: git itself refuses an unmerged branch)
+ *
+ * No other removal argv exists here, `--force` and `-D` appear in no argv, and `assertRemovalArgv` checks the shape right before each call.
+ */
+
+/** One settled row from the hub's `worktrees` reply, resolved against the project root by `rowFromReply`; `head` and `locked` come from git here, never from the daemon. */
+export interface TidyRow { path: string; shown: string; branch: string | null; head: string; locked: boolean; reason: string; instance: boolean; taskState?: string;
+  /** The branch THIS process read from git's own list (`null` when detached), as opposed to `branch`, which is the daemon's word. They must agree or the row is refused. */
+  liveBranch?: string | null }
+export type RefusalReason = "branch changed since preview; run tidy again" | "main checkout" | "instance worktree" | "dirty" | "locked" | "no branch" | "unpushed commits" | "no upstream" | "branch not merged into the default branch" | "task not approved or cancelled" | "path missing" | "outside the project" | "git could not tell";
+export interface TidyEntry { path: string; shown: string; branch: string | null; reason: string; refused: RefusalReason[] }
+export interface TidyPlan { entries: TidyEntry[]; removable: TidyEntry[]; fingerprint: string }
+
+/** Read-only and removal git, bounded. `undefined` is a failed or timed-out call, never an empty answer. */
+export interface TidyGit { run(cwd: string, args: string[]): { status: number | null; stdout: string } | undefined }
+
+/** The only two removal argv shapes. A word outside them, a flag, or a path that starts with `-` refuses before git runs. */
+export function removalArgv(root: string, path: string, branch: string): [string[], string[]] {
+  return [["-C", root, "worktree", "remove", path], ["-C", root, "branch", "-d", branch]];
+}
+export function assertRemovalArgv(argv: readonly string[]): void {
+  const [, , verb, action, target] = argv;
+  const worktree = argv.length === 5 && argv[0] === "-C" && verb === "worktree" && action === "remove";
+  const branch = argv.length === 5 && argv[0] === "-C" && verb === "branch" && action === "-d";
+  if (!(worktree || branch) || !target || target.startsWith("-") || argv.some(word => word === "--force" || word === "-f" || word === "-D" || word === "--delete")) throw new Error("refused: not one of the two tidy removal commands");
+  if (!argv[1] || argv[1].startsWith("-")) throw new Error("refused: the project root is not a path");
+}
+
+const branchOk = (branch: string): boolean => /^[A-Za-z0-9][A-Za-z0-9._/-]{0,200}$/.test(branch) && !branch.includes("..") && !branch.endsWith("/") && !branch.endsWith(".lock");
+const out = (r: { status: number | null; stdout: string } | undefined): string | undefined => r && r.status === 0 ? r.stdout.trim() : undefined;
+const raw = (r: { status: number | null; stdout: string } | undefined): string | undefined => r && r.status === 0 ? r.stdout : undefined;
+
+/**
+ * The refusal reasons for one settled row, from read-only git. Every check that cannot be answered refuses ("git could not tell"): unknown is never safe.
+ * Rows the daemon already shelved as `parked` still pass through these checks: parking is the person's wish to hide a row, not proof it is safe to delete.
+ */
+export function refusals(row: TidyRow, root: string, git: TidyGit, defaultBranch: string | undefined, exists: (path: string) => boolean = p => { try { return statSync(p).isDirectory(); } catch { return false; } }): RefusalReason[] {
+  const why: RefusalReason[] = [];
+  if (row.path === root) return ["main checkout"];
+  if (row.instance) return ["instance worktree"];
+  if (!row.path.startsWith(root + "/")) why.push("outside the project");
+  if (row.locked) why.push("locked");
+  if (!row.branch || !branchOk(row.branch)) why.push("no branch");
+  // The daemon named a branch and git, read here and now, says another (or none): the checks below would inspect the wrong branch and `branch -d` would target a stale name.
+  if (row.liveBranch !== undefined && row.liveBranch !== row.branch) why.push("branch changed since preview; run tidy again");
+  if (row.taskState !== undefined && row.taskState !== "approved" && row.taskState !== "cancelled") why.push("task not approved or cancelled");
+  if (!exists(row.path)) { why.push("path missing"); return why; }
+  const status = git.run(row.path, ["status", "--porcelain", "--untracked-files=all"]);
+  if (!status || status.status !== 0) why.push("git could not tell"); else if (status.stdout.trim() !== "") why.push("dirty");
+  if (row.branch && branchOk(row.branch)) {
+    const upstream = git.run(row.path, ["rev-parse", "--abbrev-ref", `${row.branch}@{upstream}`]);
+    if (!upstream) why.push("git could not tell");
+    else if (upstream.status !== 0) why.push("no upstream");
+    else {
+      const ahead = out(git.run(row.path, ["rev-list", "--count", `${upstream.stdout.trim()}..${row.branch}`]));
+      if (ahead === undefined) why.push("git could not tell"); else if (ahead !== "0") why.push("unpushed commits");
+    }
+    if (!defaultBranch) why.push("git could not tell");
+    else {
+      const merged = git.run(row.path, ["merge-base", "--is-ancestor", row.branch, defaultBranch]);
+      if (!merged) why.push("git could not tell"); else if (merged.status === 1) why.push("branch not merged into the default branch"); else if (merged.status !== 0) why.push("git could not tell");
+    }
+  }
+  return [...new Set(why)];
+}
+
+/** The repository's default branch from its origin HEAD, else `main` or `master` when exactly one exists locally. Read-only. */
+export function defaultBranchOf(root: string, git: TidyGit): string | undefined {
+  const head = out(git.run(root, ["symbolic-ref", "--quiet", "--short", "refs/remotes/origin/HEAD"]));
+  if (head && /^[A-Za-z0-9._-]+\/[A-Za-z0-9._/-]+$/.test(head)) return head;
+  const local = ["main", "master"].filter(name => git.run(root, ["rev-parse", "--verify", "--quiet", `refs/heads/${name}`])?.status === 0);
+  return local.length === 1 ? local[0] : undefined;
+}
+
+/** The fingerprint covers every row's path, branch, HEAD and refusals, in path order: any change to the set or to a row changes it. */
+export function fingerprintOf(entries: readonly { path: string; branch: string | null; head: string; refused: readonly string[]; liveBranch?: string | null }[]): string {
+  const hash = createHash("sha256");
+  for (const e of [...entries].sort((a, b) => a.path.localeCompare(b.path))) hash.update(JSON.stringify([e.path, e.branch, e.liveBranch ?? null, e.head, [...e.refused].sort()])).update("\n");
+  return hash.digest("hex").slice(0, 16);
+}
+
+/**
+ * The daemon shows project-relative paths and never an absolute one outside the project. A settled row whose path is outside the project (`outside: true`)
+ * or that names `..` cannot be resolved safely, so it becomes a refused row with no path to operate on.
+ */
+export function rowsFromReply(settled: readonly { path?: unknown; branch?: unknown; reason?: unknown; outside?: unknown; taskState?: unknown }[], root: string, git: TidyGit): TidyRow[] {
+  const inventory = raw(git.run(root, ["worktree", "list", "--porcelain", "-z"]));
+  const listed = new Map<string, { head: string; locked: boolean; branch: string | null }>();
+  let current: { path: string; head: string; locked: boolean; branch: string | null } | undefined;
+  for (const field of (inventory ?? "").split("\0")) {
+    if (field === "") { if (current) listed.set(current.path, current); current = undefined; continue; }
+    if (field.startsWith("worktree ")) { if (current) listed.set(current.path, current); current = { path: field.slice(9), head: "", locked: false, branch: null }; }
+    else if (current && field.startsWith("HEAD ")) current.head = field.slice(5);
+    else if (current && field.startsWith("branch refs/heads/")) current.branch = field.slice(18);   // `detached` has no branch field: it stays null
+    else if (current && (field === "locked" || field.startsWith("locked "))) current.locked = true;
+  }
+  if (current) listed.set(current.path, current);
+  return settled.flatMap(row => {
+    if (typeof row.path !== "string" || row.outside === true || row.path.includes("\0") || row.path.split("/").includes("..")) return [];
+    const absolute = row.path === "." ? root : resolve(join(root, row.path));
+    const fact = listed.get(absolute);
+    // Only a path git itself lists is operated on: the daemon's word alone never names a directory to remove.
+    if (!fact) return [];
+    return [{ path: absolute, shown: row.path, branch: typeof row.branch === "string" ? row.branch : null, head: fact.head, locked: fact.locked, liveBranch: fact.branch, reason: String(row.reason ?? ""), instance: false, ...(typeof row.taskState === "string" ? { taskState: row.taskState } : {}) }];
+  });
+}
+
+export function planTidy(rows: readonly TidyRow[], root: string, git: TidyGit): TidyPlan {
+  const defaultBranch = defaultBranchOf(root, git);
+  const detailed = rows.map(row => ({ row, refused: refusals(row, root, git, defaultBranch) }));
+  const entries: TidyEntry[] = detailed.map(({ row, refused }) => ({ path: row.path, shown: row.shown, branch: row.branch, reason: row.reason, refused }));
+  return { entries, removable: entries.filter(e => e.refused.length === 0), fingerprint: fingerprintOf(detailed.map(({ row, refused }) => ({ path: row.path, branch: row.branch, ...(row.liveBranch !== undefined ? { liveBranch: row.liveBranch } : {}), head: row.head, refused }))) };
+}
+
+export interface TidyOutcome { path: string; shown: string; branch: string; worktreeRemoved: boolean; branchDeleted: boolean; note?: string }
+/**
+ * Re-read, compare, then remove. `fresh` is a second `planTidy` the caller took AFTER the person typed the fingerprint, so a worktree that
+ * changed in between refuses the whole run before anything is removed. Each removal is read back; a failed `worktree remove` skips its branch.
+ */
+export function confirmTidy(fresh: TidyPlan, fingerprint: string, root: string, git: TidyGit): { ok: false; error: string } | { ok: true; outcomes: TidyOutcome[] } {
+  if (!/^[0-9a-f]{16}$/.test(fingerprint)) return { ok: false, error: "the fingerprint is 16 hex digits, from the preview line `fingerprint`" };
+  if (fresh.fingerprint !== fingerprint) return { ok: false, error: "the worktrees changed since the preview, so nothing was removed; run ahub worktrees tidy again and confirm the new fingerprint" };
+  if (!fresh.removable.length) return { ok: false, error: "nothing is safe to remove; see the refusals in the preview" };
+  const outcomes: TidyOutcome[] = [];
+  for (const entry of fresh.removable) {
+    const branch = entry.branch!;
+    const [removeWorktree, deleteBranch] = removalArgv(root, entry.path, branch);
+    assertRemovalArgv(removeWorktree); assertRemovalArgv(deleteBranch);
+    const removed = git.run(root, removeWorktree.slice(2));
+    const gone = removed?.status === 0 && git.run(root, ["worktree", "list", "--porcelain", "-z"])?.stdout.split("\0").every(field => field !== `worktree ${entry.path}`) === true;
+    if (!gone) { outcomes.push({ path: entry.path, shown: entry.shown, branch, worktreeRemoved: false, branchDeleted: false, note: "git refused or did not confirm removing the worktree; it and its branch were kept" }); continue; }
+    const deleted = git.run(root, deleteBranch.slice(2));
+    const branchGone = deleted?.status === 0 && git.run(root, ["rev-parse", "--verify", "--quiet", `refs/heads/${branch}`])?.status === 1;
+    outcomes.push({ path: entry.path, shown: entry.shown, branch, worktreeRemoved: true, branchDeleted: branchGone, ...(branchGone ? {} : { note: "the worktree was removed; git kept the branch (not fully merged), which is safe" }) });
+  }
+  return { ok: true, outcomes };
+}
+
+/** Real git, bounded, run in this CLI process. Only the removal argv of `removalArgv` and the read shapes the checks above use reach it. */
+export const realTidyGit = (spawn: (argv: string[], cwd: string) => { status: number | null; stdout: string } | undefined): TidyGit => ({
+  run(cwd, args) {
+    const write = args[0] === "worktree" && args[1] === "remove" || args[0] === "branch" && args[1] === "-d";
+    if (write) assertRemovalArgv(["-C", cwd, ...args]); // a removal always runs in the project root, with the worktree path or branch as its operand
+    // `--no-optional-locks`: a plain `git status` rewrites the worktree's own index file, which is exactly what the shelf reads as activity (D1). Without it a tidy
+    // preview would make every settled worktree look freshly edited, and it would leave the shelf on the next read. The preview must not change what it measures.
+    return spawn(["--no-optional-locks", "-C", cwd, "-c", "gc.auto=0", "-c", "maintenance.auto=false", ...args], cwd);
+  },
+});

package/src/cli/worktrees-output.ts

@@ -0,0 +1,43 @@
+// Human output for `ahub worktrees` and `ahub worktrees tidy` (#1057). Pure: data in, spans out, no I/O. `--json` is the caller's branch and prints the same data.
+import { blank, grid, heading, pair, s } from "./sdlc-output.ts";
+import { moment } from "./sdlc-output.ts";
+import type { Span } from "./console-state.ts";
+
+const list = (value: unknown): any[] => Array.isArray(value) ? value : [];
+const reasonLabel = (row: any): string => row?.reason === "merged" ? "PR merged" : row?.reason === "closed" ? "PR closed" : row?.reason === "quiet" ? "quiet" : row?.reason === "parked" ? "parked" : row?.reason === "settled" ? "settled" : "";
+const taskLabel = (row: any): string => row?.private === true ? "task: private" : typeof row?.task === "number" ? `#${row.task}${typeof row.pr === "number" ? ` PR ${row.pr}` : ""}` : "";
+
+/** `ahub worktrees`: live rows, then the shelf with each settled row's reason. */
+export function renderWorktrees(reply: unknown, columns?: number, now = Date.now()): Span[][] {
+  const r = reply as any, live = list(r?.live), settled = list(r?.settled);
+  const rows = (items: any[], withReason: boolean) => items.map((row: any) => [
+    s(row.path), s(row.branch ?? "(detached)", "muted"), s(taskLabel(row), "issueRef"), ...(withReason ? [s(reasonLabel(row), "attention")] : []), s(moment(row.lastActiveAt, now), "muted"),
+  ]);
+  const out: Span[][] = [...heading(`Worktrees: ${live.length} live, ${settled.length} settled`, columns)];
+  if (live.length) out.push(...grid(["PATH", "BRANCH", "TASK", "ACTIVE"], rows(live, false), columns));
+  if (settled.length) out.push(blank, ...heading("Shelf (settled)", columns), ...grid(["PATH", "BRANCH", "TASK", "WHY", "ACTIVE"], rows(settled, true), columns));
+  if (!live.length && !settled.length) out.push([s("no worktrees", "muted")]);
+  if (r?.complete === false) out.push(blank, [s("the list was cut off at its bound; some worktrees are not shown", "attention")]);
+  if (settled.length) out.push(blank, [s("preview what could be removed with ahub worktrees tidy; nothing is removed until you confirm", "muted")]);
+  return out;
+}
+
+/** `ahub worktrees tidy`: each settled row that is safe to remove, each refused row with its reasons, and the fingerprint to confirm. */
+export function renderTidyPreview(plan: unknown, columns?: number): Span[][] {
+  const p = plan as any, entries = list(p?.entries), removable = list(p?.removable), refused = entries.filter((e: any) => list(e.refused).length);
+  const out: Span[][] = [...heading(`Tidy preview: ${removable.length} safe to remove, ${refused.length} refused`, columns)];
+  if (removable.length) out.push(...grid(["PATH", "BRANCH", "WHY SETTLED"], removable.map((e: any) => [s(e.shown), s(e.branch ?? ""), s(reasonLabel(e))]), columns));
+  if (refused.length) out.push(blank, ...heading("Refused", columns), ...grid(["PATH", "BRANCH", "REFUSED BECAUSE"], refused.map((e: any) => [s(e.shown), s(e.branch ?? ""), s(list(e.refused).join("; "), "attention")]), columns));
+  if (!entries.length) out.push([s("nothing is on the shelf", "muted")]);
+  if (removable.length) out.push(blank, ...pair("fingerprint", String(p.fingerprint), columns, 12), [s(`confirm with: ahub worktrees tidy --confirm ${p.fingerprint}`, "muted")], [s("each removal runs git worktree remove and git branch -d, without force; git keeps anything it considers unsafe", "muted")]);
+  return out;
+}
+
+/** `ahub worktrees tidy --confirm`: what happened to each row. */
+export function renderTidyResult(outcomes: unknown, columns?: number): Span[][] {
+  const rows = list(outcomes);
+  const out: Span[][] = [...heading(`Tidy: ${rows.filter((o: any) => o.worktreeRemoved).length} of ${rows.length} removed`, columns)];
+  out.push(...grid(["PATH", "BRANCH", "WORKTREE", "BRANCH"], rows.map((o: any) => [s(o.shown), s(o.branch), s(o.worktreeRemoved ? "removed" : "kept", o.worktreeRemoved ? "muted" : "attention"), s(o.branchDeleted ? "deleted" : "kept", o.branchDeleted ? "muted" : "attention")]), columns));
+  for (const o of rows.filter((x: any) => x.note)) out.push([s(`${o.shown}: ${o.note}`, "muted")]);
+  return out;
+}

package/src/hub/board.ts

@@ -11,6 +11,7 @@ import type { ReviewerPoolReason } from "./reviewer-pool.ts";
 import type { GitHubSource } from "./github-import.ts";
 import type { Database } from "./db-schema.ts";
 import { openHubDatabase, advanceHubDbSchema } from "./db-schema.ts";
+import { controlWriteSpan } from "./control-write-trace.ts";
 import { planningPatch, type PlanningFields, type Release, type ReleaseState } from "./planning.ts";
 import { HUB, USER, type PeerId } from "./envelope.ts";
 import type { SweepRecord } from "./task-sweep.ts";
@@ -431,11 +432,11 @@ export class Board {
 
   /** Keep the generation and business write atomic without changing Bun's reported row count. */
   private taskWrite<T extends { changes: number }>(write: () => T): T {
-    return this.db.transaction(() => {
+    return controlWriteSpan("board-write", () => this.db.transaction(() => {
       const result = { ...write() };
       if (result.changes) this.db.run("UPDATE board_status_revision SET revision=revision+1 WHERE id=1");
       return result;
-    })();
+    })());
   }
 
   statusRevision(): number {
@@ -473,6 +474,8 @@ export class Board {
     this.db.run("CREATE TABLE IF NOT EXISTS security_scans (id INTEGER PRIMARY KEY AUTOINCREMENT, at INTEGER NOT NULL, repo TEXT NOT NULL, sources TEXT NOT NULL, counts TEXT NOT NULL, total INTEGER)");
     // #843 AC3: one row per (agent id, installed version, planner) already queued, so a restart never repeats it.
     this.db.run("CREATE TABLE IF NOT EXISTS agent_drift_notices (marker TEXT PRIMARY KEY, at INTEGER NOT NULL)");
+    // #1057 D2: the person's park or pin of one worktree. Facts only: whether a worktree is settled is derived at read time and never stored here.
+    this.db.run("CREATE TABLE IF NOT EXISTS worktree_override (path TEXT PRIMARY KEY, value TEXT NOT NULL CHECK(value IN ('settled','active')), at INTEGER NOT NULL)");
     // Derived status-cache generation: only Board task/stall writes advance it, never journal writes.
     this.db.run("CREATE TABLE IF NOT EXISTS board_status_revision (id INTEGER PRIMARY KEY CHECK(id=1), revision INTEGER NOT NULL)");
     this.db.run("INSERT OR IGNORE INTO board_status_revision VALUES (1,0)");
@@ -1473,6 +1476,26 @@ export class Board {
     return this.db.query("INSERT OR IGNORE INTO agent_drift_notices(marker, at) VALUES(?, ?)").run(marker, Date.now()).changes > 0;
   }
   forgetAgentDriftNotice(marker: string): void { this.db.query("DELETE FROM agent_drift_notices WHERE marker=?").run(marker); }
+  /** #1057 D2: every override, newest first, bounded. Rows made inert by later activity are removed lazily by the next write (`setWorktreeOverride`). */
+  worktreeOverrides(): { path: string; value: "settled" | "active"; at: number }[] {
+    return this.db.query("SELECT path, value, at FROM worktree_override ORDER BY at DESC LIMIT 1024").all() as { path: string; value: "settled" | "active"; at: number }[];
+  }
+  /** One override per path; a new write replaces the old. `path` is the absolute host path the shelf listed, never a name a request invented. */
+  setWorktreeOverride(path: string, value: "settled" | "active", at: number): void {
+    if (typeof path !== "string" || !path.startsWith("/") || path.length > 4096 || path.includes("\0")) throw new Error("invalid worktree path");
+    if (value !== "settled" && value !== "active") throw new Error("invalid worktree override");
+    if (!Number.isFinite(at) || at <= 0) throw new Error("invalid worktree override time");
+    this.db.query("INSERT INTO worktree_override(path, value, at) VALUES(?,?,?) ON CONFLICT(path) DO UPDATE SET value=excluded.value, at=excluded.at").run(path, value, at);
+  }
+  clearWorktreeOverride(path: string): boolean {
+    return this.db.query("DELETE FROM worktree_override WHERE path=?").run(path).changes > 0;
+  }
+  /** The lazy removal D2 names: an override whose worktree has newer activity is inert, so a write deletes it. `active` maps path to its lastActiveAt. */
+  pruneInertWorktreeOverrides(activity: ReadonlyMap<string, number>): number {
+    let removed = 0;
+    for (const row of this.worktreeOverrides()) { const last = activity.get(row.path); if (last !== undefined && last > row.at) removed += this.clearWorktreeOverride(row.path) ? 1 : 0; }
+    return removed;
+  }
   clearStall(task: number): void { this.taskWrite(() => this.db.query("DELETE FROM task_stalls WHERE task=?").run(task)); }
   /** One bounded primary-key metadata read for a retry's saved replacement cause. */
   stall(task: number): TaskStall | undefined {
@@ -1511,6 +1534,9 @@ export class Board {
     if (expectedFlowRevision !== undefined && (!Number.isSafeInteger(expectedFlowRevision) || expectedFlowRevision < 0 || task.history.length !== expectedFlowRevision)) throw new Error("task flow revision changed");
     const untouchedReturn = event === "backlog returned untouched" && patch.state === "backlog" && patch.owner === null && patch.reviewer === null
       && ["proposed", "in_progress"].includes(task.state) && expectedFlowRevision !== undefined && !!note?.trim() && !taskHasWorkEvidence(task);
+    const returnPlanning: HistoryEntry["planning"] = untouchedReturn && Object.hasOwn(patch, "reserved")
+      ? { revision: (task.planningRevision ?? 0) + 1, fields: ["reserved"], previous: { reserved: task.reserved ?? null } } : undefined;
+    if (returnPlanning) patch = { ...patch, reserved: planningPatch({ reserved: patch.reserved }).reserved };
     // A new delivered head with a configured check is owner work again until that check finishes.
     const reviewCheck = task.sdlc?.merge?.state !== "merged" && event === "done (checking)" && ["in_review", "approved"].includes(task.state) && patch.state === "in_progress"
       && expectedFlowRevision !== undefined && (by === task.owner || by === "user") && patch.owner === undefined && (patch.reviewer === undefined || task.state === "approved" && !task.reviewer && patch.reviewer === "user")
@@ -1586,10 +1612,10 @@ export class Board {
       && priorHead !== undefined && /^[a-f0-9]{40}$/.test(priorHead);
     const previousHistory = backfill ? task.history.map((entry, index) => index === priorApproval && !entry.reviewedHead
       ? { ...entry, reviewedHead: entry.reviewFindings?.head ?? priorHead } : entry) : task.history;
-    const history = [...previousHistory, { at: Date.now(), by, event, ...(extra.invocation ? { invocation: extra.invocation } : {}), ...plannerHistory, ...authorHistory, ...(extra.selfReview === true ? { selfReview: true as const } : {}), ...(planRevision ? { planRevision } : {}), ...(extra.planObservation ? { planObservation: extra.planObservation } : {}), ...(extra.planDeparture ? { planDeparture: extra.planDeparture } : {}), ...(departureInvalidated ? { planDepartureInvalidated: true as const } : {}), ...reviewMetadata, ...specMetadata, ...(note ? { note } : {}), ...(patch.cancelled?.supersededBy ? { supersededBy: patch.cancelled.supersededBy } : {}), ...("owner" in patch ? { owner: next.owner } : {}), ...(extra.profile ? { profile: extra.profile } : {}), ...(extra.sweep ? { sweep: extra.sweep } : {}), ...(extra.reason && TASK_MOVE_REASONS.includes(extra.reason) ? { reason: extra.reason } : {}), ...(extra.from ? { from: extra.from } : {}), ...(extra.capacity === true ? { capacity: true as const } : {}), ...(extra.conductorManual === true ? { conductorManual: true as const } : {}), ...(extra.withheld && (note || reviewFindings) ? { withheld: true as const } : {}), ...(reviewFindings ? { reviewFindings } : {}), ...(extra.reviewedHead ? { reviewedHead: extra.reviewedHead } : {}), ...(unmetCriteria?.length ? { unmetCriteria } : {}), ...(deliverables ? { deliverables } : {}), ...(extra.reviewContext === "fresh" || extra.reviewContext === "continuing" ? { reviewContext: extra.reviewContext } : {}), ...(extra.reviewScope === "code" ? { reviewScope: "code" as const } : {}), ...(extra.evidenceOnly === true && event === "changes_requested" ? { evidenceOnly: true as const } : {}), ...(extra.reviewCost ? { reviewCost: extra.reviewCost } : {}), ...(event === "done" && extra.noWrites === true ? { noWrites: true as const } : {}), ...(["check passed", "check failed"].includes(event) && typeof extra.checkKey === "string" && /^[a-z][a-z0-9_]{0,47}$/.test(extra.checkKey) ? { checkKey: extra.checkKey } : {}), ...(["check passed", "check failed"].includes(event) && Number.isSafeInteger(extra.missingKeys) && extra.missingKeys! >= 0 && extra.missingKeys! <= 100_000 ? { missingKeys: extra.missingKeys } : {}), ...(event === "claim verdict" && extra.claim ? { claim: extra.claim } : {}) }];
+    const history = [...previousHistory, { at: Date.now(), by, event, ...(returnPlanning ? { planning: returnPlanning } : {}), ...(extra.invocation ? { invocation: extra.invocation } : {}), ...plannerHistory, ...authorHistory, ...(extra.selfReview === true ? { selfReview: true as const } : {}), ...(planRevision ? { planRevision } : {}), ...(extra.planObservation ? { planObservation: extra.planObservation } : {}), ...(extra.planDeparture ? { planDeparture: extra.planDeparture } : {}), ...(departureInvalidated ? { planDepartureInvalidated: true as const } : {}), ...reviewMetadata, ...specMetadata, ...(note ? { note } : {}), ...(patch.cancelled?.supersededBy ? { supersededBy: patch.cancelled.supersededBy } : {}), ...("owner" in patch ? { owner: next.owner } : {}), ...(extra.profile ? { profile: extra.profile } : {}), ...(extra.sweep ? { sweep: extra.sweep } : {}), ...(extra.reason && TASK_MOVE_REASONS.includes(extra.reason) ? { reason: extra.reason } : {}), ...(extra.from ? { from: extra.from } : {}), ...(extra.capacity === true ? { capacity: true as const } : {}), ...(extra.conductorManual === true ? { conductorManual: true as const } : {}), ...(extra.withheld && (note || reviewFindings) ? { withheld: true as const } : {}), ...(reviewFindings ? { reviewFindings } : {}), ...(extra.reviewedHead ? { reviewedHead: extra.reviewedHead } : {}), ...(unmetCriteria?.length ? { unmetCriteria } : {}), ...(deliverables ? { deliverables } : {}), ...(extra.reviewContext === "fresh" || extra.reviewContext === "continuing" ? { reviewContext: extra.reviewContext } : {}), ...(extra.reviewScope === "code" ? { reviewScope: "code" as const } : {}), ...(extra.evidenceOnly === true && event === "changes_requested" ? { evidenceOnly: true as const } : {}), ...(extra.reviewCost ? { reviewCost: extra.reviewCost } : {}), ...(event === "done" && extra.noWrites === true ? { noWrites: true as const } : {}), ...(["check passed", "check failed"].includes(event) && typeof extra.checkKey === "string" && /^[a-z][a-z0-9_]{0,47}$/.test(extra.checkKey) ? { checkKey: extra.checkKey } : {}), ...(["check passed", "check failed"].includes(event) && Number.isSafeInteger(extra.missingKeys) && extra.missingKeys! >= 0 && extra.missingKeys! <= 100_000 ? { missingKeys: extra.missingKeys } : {}), ...(event === "claim verdict" && extra.claim ? { claim: extra.claim } : {}) }];
     this.taskWrite(() => {
-      const result = this.db.query("UPDATE tasks SET state = ?, owner = ?, reviewer = ?, reserved = ?, refs = ?, plan = ?, rejections = ?, signals = ?, history = ?, sdlc = ?, task_role = ?, cancelled = ?, updated = ?, planner = ? WHERE id = ?")
-        .run(next.state, next.owner, next.reviewer, next.reserved ?? null, JSON.stringify(next.refs), JSON.stringify(next.plan ?? {}), next.rejections, JSON.stringify(next.signals), JSON.stringify(history), next.sdlc ? JSON.stringify(next.sdlc) : null, next.role ?? null, next.cancelled ? JSON.stringify(next.cancelled) : null, Date.now(), planner, id);
+      const result = this.db.query("UPDATE tasks SET state = ?, owner = ?, reviewer = ?, reserved = ?, refs = ?, plan = ?, rejections = ?, signals = ?, history = ?, sdlc = ?, task_role = ?, cancelled = ?, updated = ?, planner = ?, planning_revision = ? WHERE id = ?")
+        .run(next.state, next.owner, next.reviewer, next.reserved ?? null, JSON.stringify(next.refs), JSON.stringify(next.plan ?? {}), next.rejections, JSON.stringify(next.signals), JSON.stringify(history), next.sdlc ? JSON.stringify(next.sdlc) : null, next.role ?? null, next.cancelled ? JSON.stringify(next.cancelled) : null, Date.now(), planner, returnPlanning?.revision ?? task.planningRevision ?? 0, id);
       if (result.changes) {
         if (next.codeSymbols) this.db.query("INSERT INTO task_code_symbols(task,payload) VALUES(?,?) ON CONFLICT(task) DO UPDATE SET payload=excluded.payload").run(id, JSON.stringify(next.codeSymbols));
         else this.db.query("DELETE FROM task_code_symbols WHERE task=?").run(id);

package/src/hub/bus.ts

@@ -218,7 +218,7 @@ export class Bus {
   }
 
   /** Actual transport admission, using originals even when a digest was condensed. Never an enqueue metric. */
-  onDelivered?: (peer: PeerId, originals: Envelope[]) => void;
+  onDelivered?: (peer: PeerId, originals: Envelope[], deliveryId?: string) => void;
   /** Before deliver's synchronous busy transition, with originals rather than a condensed digest. */
   onDeliver?: (peer: PeerId, originals: Envelope[]) => void;
   /** Final rendered journal payload, and its first positive acknowledgement. Observation cannot alter settlement. */
@@ -777,7 +777,7 @@ export class Bus {
     else this.journal.transition(id, state, receipt.reason);
     if (before?.state === "dispatching" && (state === "accepted" || state === "completed")) {
       this.memoryDelivery(peer, id, before.out, "delivered", before.originals);
-      this.delivered(peer, before.originals);
+      this.delivered(peer, before.originals, id);
     }
     if (state === "failed") {
       if (before) this.failed(peer, before.originals, before.originals.some((e) => e.private) ? "private delivery failed" : receipt.reason, receipt.quota === true && before.state === "dispatching");
@@ -1258,8 +1258,8 @@ export class Bus {
     try { this.onMemoryDelivery?.(peer, id, out, field); } catch { /* optional telemetry never alters delivery */ }
   }
 
-  private delivered(peer: PeerId, originals: Envelope[]): void {
-    try { this.onDelivered?.(peer, originals); } catch { /* observation must never affect delivery settlement */ }
+  private delivered(peer: PeerId, originals: Envelope[], deliveryId?: string): void {
+    try { this.onDelivered?.(peer, originals, deliveryId); } catch { /* observation must never affect delivery settlement */ }
   }
 
   private deliveryFailed(peer: PeerId): void {

package/src/hub/conductor.ts

@@ -9,7 +9,7 @@ import { PreEffectToolRefusal } from "./tool-refusal.ts";
 import type { StartMode } from "./start-mode.ts";
 import type { HubEvent } from "./events.ts";
 import type { SupervisionFeed } from "./supervision.ts";
-import { DOING_STUB, type PeerDoing } from "./peer-doing.ts";
+import { DOING_STUB, INCOMING_LABEL_NOTE, type PeerDoing } from "./peer-doing.ts";
 import type { Budget } from "./budget.ts";
 import { windowKind, type WindowKind } from "./window-kind.ts";
 import { supportsHeadlessInstances } from "./instances.ts";
@@ -144,11 +144,12 @@ export function publicConductorStatus(input: ConductorStatusInput, now = Date.no
       conductorHold: p.hold ? { actor: p.hold.actor, since: numberOrNull(p.hold.since) } : null,
       budgetPause: p.budgetPause ? { since: numberOrNull(p.budgetPause.since), resetsAt: numberOrNull(p.budgetPause.resetsAt) } : null,
       windows: p.windows === undefined ? null : p.windows.map((w) => ({ id: w.id, used: numberOrNull(w.used), resetsAt: numberOrNull(w.resetsAt), at: numberOrNull(w.at), source: w.source ?? null })),
-      // #878: screened by the daemon, but written by the peer itself: framed as untrusted for the conductor agent.
+      // Native reports retain peer authorship; incoming message labels carry their own display provenance.
       doing: !p.doing ? null : p.doing.text === DOING_STUB ? { text: DOING_STUB, source: p.doing.source, at: numberOrNull(p.doing.at) }
+        : p.doing.source === "label" ? { text: sanitize(p.doing.text), source: "label", at: numberOrNull(p.doing.at), note: INCOMING_LABEL_NOTE, untrusted: true }
         : { text: sanitize(p.doing.text), source: p.doing.source, at: numberOrNull(p.doing.at), from: p.peer, untrusted: true },
     })),
-    ...(input.peers.some(p => p.doing && p.doing.text !== DOING_STUB) ? { doingNote: DOING_NOTE } : {}),
+    ...(input.peers.some(p => p.doing && p.doing.source !== "label" && p.doing.text !== DOING_STUB) ? { doingNote: DOING_NOTE } : {}),
     taskCounts: Object.fromEntries(Object.entries(input.taskCounts).map(([state, count]) => [state, numberOrNull(count)])),
     approvals: input.approvals.map((a) => ({ peer: a.peer, tool: a.tool ?? null, ageMs: a.at === undefined || !Number.isFinite(a.at) ? null : Math.max(0, now - a.at) })),
   };

package/src/hub/config-apply.ts

@@ -227,6 +227,7 @@ const schema: Record<string, Check> = {
     else if (/^[a-z][a-z0-9_]{0,47}$/.test(key)) text(value, `${k}.${key}`); else fail(`${k}.${key}`, "unknown key");
   } },
   snapshots: block({ enabled: bool, keep: number(1, 1_000_000, true) }), research: block({ enabled: bool, runners: researchRunners }), bench: block({ enabled: bool }),
+  worktrees: block({ quiet_days: number(0, 3650, true), alert_over: number(0, 100_000, true) }),
   peers: (v, k) => { map(block({ start_mode: words(["tui", "headless"]) }), START_MODE_PEERS)(v, k); peerStartConfig(v); },
   terminal: (v, k) => { block({ open: strings })(v, k); terminalTemplate(object(v, k).open); },
   start: (v, k) => { block({ agents: strings })(v, k); if (object(v, k).agents !== undefined) checkStartAgents(object(v, k).agents, `${k}.agents`); },
@@ -273,7 +274,7 @@ const restart: Record<string, string> = {
   profile: "Session tool schemas and profile contracts are bound at startup", profile_overrides: "Session tool schemas and profile contracts are bound at startup",
   text_projection: "Converter and cache ownership are bound at startup", corpus: "The corpus index is bound to its roots at startup", terminal: "Terminal provider is supplied by the daemon lifecycle", bench: "Benchmark execution environment is selected before work starts",
 };
-const live = new Set(["action_policy", "permission", "roster", "roles", "planner", "conductor", "protect_instruction_files", "task_sweep", "capabilities", "invocation", "research", "snapshots", "tasks.wip_limits", "tasks.escalate_after", "tasks.auto_pull", "tasks.queue_backpressure", "schedules", "approvals.notify", "pet", "specs"]);
+const live = new Set(["action_policy", "permission", "roster", "roles", "planner", "conductor", "protect_instruction_files", "task_sweep", "capabilities", "invocation", "research", "snapshots", "worktrees", "tasks.wip_limits", "tasks.escalate_after", "tasks.auto_pull", "tasks.queue_backpressure", "schedules", "approvals.notify", "pet", "specs"]);
 const nextMemory = new Set(["memory.inject_tokens", "memory.brief_items", "memory.suggest_edges"]);
 /** Closed top-level schema; leaf overrides retain the existing session/runtime boundaries. */
 export function configApply(key: string, scopes: readonly ConfigIdentityScope[] = []): ApplyRule {

package/src/hub/control-client.ts

@@ -4,6 +4,13 @@ import { projectContext } from "./project.ts";
 import { newToolRequestId, TOOL_WRITE_FEATURE, toolWriteOperation, toolWriteUnknownReply, toolWriteRefusedReply } from "./tool-request.ts";
 import { externalAdapterMetadata, externalInstanceCatalog, type ExternalInstanceCatalog, type ExternalAdapterMetadata } from "../adapters/external-metadata.ts";
 import { negotiateProtocol, protocolWindow, type ProtocolWindow } from "./protocol-window.ts";
+import { ControlWriteTelemetry, controlWriteMetadata, controlWriteSpan } from "./control-write-trace.ts";
+
+// The client has no authoritative task privacy view. Keep kind/timing only, never its args or task id.
+const clientWriteTelemetry = new ControlWriteTelemetry({ emit: line => {
+  if (process.env.AHUB_CONTROL_WRITE_TIMING === "1") console.error(`[agent-hub] ${line}`);
+} });
+const publicClientTiming = () => true;
 
 export function stateDirFor(cwd: string): string {
   return projectContext(cwd).stateDir;
@@ -221,6 +228,14 @@ export class ControlClient {
 
   /** `timeoutMs`: for calls a person waits on. The hub has its own budget; this one only makes sure the CLI never hangs. */
   request(msg: Record<string, unknown>, timeoutMs = 30_000, signal?: AbortSignal): Promise<any> {
+    if (process.env.AHUB_CONTROL_WRITE_TIMING !== "1") return this.requestBody(msg, timeoutMs, signal);
+    const metadata = controlWriteMetadata(msg);
+    if (!metadata) return this.requestBody(msg, timeoutMs, signal);
+    return clientWriteTelemetry.run({ kind: metadata.kind }, publicClientTiming, () => controlWriteSpan("client-wait", () =>
+      this.requestBody(msg, timeoutMs, signal)));
+  }
+
+  private requestBody(msg: Record<string, unknown>, timeoutMs: number, signal?: AbortSignal): Promise<any> {
     if (this.ws.readyState !== WebSocket.OPEN || this.closing && msg.t !== "request_cancel") return Promise.resolve({ ok: false, error: "hub connection is not open" });
     const invocation = msg.t === "task" && msg.op === "hub_invoke";
     const operation = toolWriteOperation(msg), write = operation !== undefined;
@@ -266,7 +281,7 @@ export class ControlClient {
       signal?.addEventListener("abort", aborted, { once: true });
       if (signal?.aborted) { aborted(); return; }
       timer = timeoutMs ? setTimeout(() => abandon(`no answer from the hub within ${Math.round(timeoutMs / 1000)} s`), timeoutMs) : undefined;
-      try { this.ws.send(JSON.stringify({ ...wire, rid })); }
+      try { controlWriteSpan("client-send", () => this.ws.send(JSON.stringify({ ...wire, rid }))); }
       catch { abandon("hub request could not be sent"); }
     });
   }