@staix/agent-hub 0.29.0 → 0.31.0

package/src/cli/results-args.ts

@@ -0,0 +1,30 @@
+/**
+ * #1054 T4: `ahub results [--unread] [--read <id> | --read-all | --unread-last]`. Pure: argv to one closed request, never a decision about whether it applies (the hub checks
+ * that a result exists and is unread). At most one action flag; `--unread` only narrows the list and takes no action.
+ */
+export const RESULT_ID = /^cmp-[a-f0-9]{12}$/;
+export type ResultsRequest = { action: "list"; unread: boolean } | { action: "read"; id: string } | { action: "read-all" } | { action: "unread-last" };
+export type ResultsArgs = { ok: true; value: ResultsRequest } | { ok: false; error: string };
+export const RESULTS_USAGE = "usage: ahub results [--unread] [--read <id> | --read-all | --unread-last] [--json] [--color=auto|always|never]";
+
+export function parseResultsArgs(args: readonly string[]): ResultsArgs {
+  const fail = (error: string): { ok: false; error: string } => ({ ok: false, error: `${RESULTS_USAGE}; ${error}` });
+  let unread = false;
+  const actions: ResultsRequest[] = [];
+  for (let index = 0; index < args.length; index++) {
+    const word = args[index]!;
+    if (word === "--unread") { unread = true; continue; }
+    if (word === "--read-all") { actions.push({ action: "read-all" }); continue; }
+    if (word === "--unread-last") { actions.push({ action: "unread-last" }); continue; }
+    if (word === "--read" || word.startsWith("--read=")) {
+      const id = word === "--read" ? args[++index] : word.slice("--read=".length);
+      if (id === undefined || !RESULT_ID.test(id)) return fail("--read needs a result id like cmp-0123456789ab (ahub results lists them)");
+      actions.push({ action: "read", id });
+      continue;
+    }
+    return fail(word.startsWith("--") ? `unknown flag ${word.split("=")[0]}` : `unexpected operand ${word.slice(0, 40)}`);
+  }
+  if (actions.length > 1) return fail("give one of --read, --read-all and --unread-last");
+  if (actions.length === 1) { if (unread) return fail("--unread only narrows the list; it does not combine with an action"); return { ok: true, value: actions[0]! }; }
+  return { ok: true, value: { action: "list", unread } };
+}

package/src/cli/runtime-version-warning.ts

@@ -1,4 +1,5 @@
 import type { DoctorCheck } from "./output.ts";
+import { parseList, pluginState, type InstalledPlugin } from "./setup.ts";
 
 const VERSION = /^[0-9]+\.[0-9]+\.[0-9]+(?:-[0-9A-Za-z]+(?:[.-][0-9A-Za-z]+)*)?(?:\+[0-9A-Za-z]+(?:[.-][0-9A-Za-z]+)*)?$/;
 const version = (value: unknown): string | undefined => typeof value === "string" && value.length <= 64 && VERSION.exec(value)?.[0] === value ? value : undefined;
@@ -26,3 +27,52 @@ export function runtimeVersionWarnings(daemonVersion: unknown, cliVersion: unkno
   } catch { unknown("plugin versus daemon", "plugin and daemon versions could not be compared"); }
   return rows;
 }
+
+/**
+ * #718 (#1179): the lines `ahub upgrade` ends with when the global CLI or the shared Claude plugin is older than the daemon it upgraded, or none. `ahub upgrade` upgrades one project's daemon
+ * only, so the person must update the CLI and the plugin themselves; without these lines a stale CLI later fails with a message that does not say why.
+ *
+ * It reuses `runtimeVersionWarnings`, the comparison `ahub doctor` prints, so the two never disagree about what is older. The one difference is a handover: when an older CLI hands the upgrade to the
+ * target release's own coordinator (`AGENTHUB_UPGRADE_HANDOVER=1`, set by every release since #272), the process that prints is the target itself and cannot see the CLI that started it, but that
+ * CLI is older by construction (it handed over because the target was newer), so `handedOver` stands for it. An unknown plugin (no `claude`, unreadable inventory) is never a claim.
+ */
+export function globalUpdateAfterUpgrade(target: unknown, cli: unknown, plugin: unknown, handedOver = false): string[] {
+  const running = version(target);
+  if (!running) return [];
+  const warned = new Set(runtimeVersionWarnings(running, handedOver ? undefined : cli, plugin).filter(row => row.level === "warn").map(row => row.name));
+  const cliOlder = handedOver || warned.has("CLI versus daemon"), pluginOlder = warned.has("plugin versus daemon");
+  if (!cliOlder && !pluginOlder) return [];
+  return [
+    "ahub upgrade does not update the global CLI or the shared Claude plugin.",
+    cliOlder
+      ? `${handedOver ? "The CLI that started this upgrade is older than the daemon this upgrade installs" : "The global CLI is older than the daemon this upgrade installs"} (${running}): run \`bun add -g @staix/agent-hub@${running}\` and then \`ahub setup\` yourself.`
+      : `The installed plugin is older than the daemon this upgrade installs (${running}): run \`ahub setup\` yourself.`,
+  ];
+}
+
+export interface GlobalUpdateInputs {
+  /** The daemon this upgrade installs. */
+  target: string;
+  /** This process's own version. */
+  cli: string;
+  /** True when an older CLI handed the upgrade to this release's coordinator (`AGENTHUB_UPGRADE_HANDOVER=1`). */
+  handedOver: boolean;
+  /** Where this release's shipped plugin bundle lives, for `pluginState`. */
+  packageRoot: string;
+  /** The same `claude plugin list --json` probe `ahub doctor` runs. */
+  probe: () => { status: number | null; stdout?: string | null };
+}
+
+/**
+ * #718: `globalUpdateAfterUpgrade` with the plugin version read from the probe. Advice only: a missing `claude`, a probe that throws or times out, a non-zero exit or an unparsable list reads as an
+ * unknown plugin, which is never a claim, and nothing here can fail an upgrade.
+ */
+export function globalUpdateAdvice(input: GlobalUpdateInputs): string[] {
+  let plugin: string | undefined;
+  try {
+    const probed = input.probe();
+    const state = pluginState(parseList<InstalledPlugin>(probed.status === 0 ? probed.stdout ?? "" : ""), input.packageRoot);
+    plugin = state.state === "missing" ? undefined : state.version;
+  } catch { /* an unknown plugin: the CLI half below does not depend on it */ }
+  try { return globalUpdateAfterUpgrade(input.target, input.cli, plugin, input.handedOver); } catch { return []; }
+}

package/src/cli/status-lines.ts

@@ -1,8 +1,11 @@
 import type { ContextView } from "../hub/context-window.ts";
+import { memorySyncNextStep, type MemorySyncCause } from "../hub/memory-sync-state.ts";
 // What `ahub status` prints for a peer and for a model backend, kept pure so it can be checked.
 
-export interface PeerRow { permissionMode?: string; context?: ContextView; state?: string; queued?: number; queuedImportant?: number; needsReview?: number; heldBy?: string; holdNote?: string; liveAccepted?: string[]; oldestQueuedAt?: number; importantWaitingSince?: number; importantWaitingNote?: string; attached?: boolean; toolsOnly?: string; pullOnly?: boolean; lastInboxAt?: number | null; permissionNote?: string; reviewerUnavailable?: string; paused?: string; servedBy?: string; requestedModel?: string }
+export interface PeerRow { permissionMode?: string; context?: ContextView; state?: string; queued?: number; queuedImportant?: number; needsReview?: number; heldBy?: string; holdNote?: string; reviewObserverHoldNote?: string; liveAccepted?: string[]; oldestQueuedAt?: number; importantWaitingSince?: number; importantWaitingNote?: string; attached?: boolean; attachMode?: "channel" | "tools-only"; attachEvidence?: string; toolsOnly?: string; pullOnly?: boolean; lastInboxAt?: number | null; permissionNote?: string; reviewerUnavailable?: string; paused?: string; servedBy?: string; requestedModel?: string }
 export interface BackendRow { kind?: string; alias?: string; state?: string; active?: number; requestedModel?: string; actualModel?: string; provider?: string; coolingUntil?: string; failures?: number; failingUntil?: string }
+export interface MemorySyncRow { state?: string; at?: number; cause?: string; declinedCount?: number; declinedIdsKnown?: false; withheldCount?: number; exportedCount?: number; placementActive?: false; nextStep?: string }
+export interface ReviewInputHealthRow { state?: string; cause?: string | null }
 
 /** Aliases are already namespaced ("dgx/coding"); only an alias that is not gets its kind in front of it. */
 export function backendLabel(backend: BackendRow): string {
@@ -15,3 +18,40 @@ export function backendLabel(backend: BackendRow): string {
 export function contextLine(reading: ContextView, time = (at: number) => new Date(at).toISOString()): string {
   return `context ${reading.used === null ? "unknown" : `${Math.round(reading.used * 100)}%`} (${reading.freshness}${reading.source ? `, ${reading.source}` : ""}${reading.measuredAt !== null ? `, measured ${time(reading.measuredAt)}` : ""})`;
 }
+
+/** Human status copy for machine-local sync; upstream error text never enters this projection. */
+export function memorySyncLine(sync: MemorySyncRow, time = (at: number) => new Date(at).toISOString()): string {
+  const allowedStates = ["disabled", "unavailable", "notrun", "not-configured", "stopped", "ok", "failed", "unknown"];
+  const state = allowedStates.includes(sync.state ?? "") ? sync.state! : "unknown";
+  const hasTimestamp = sync.at !== undefined;
+  const validTimestamp = Number.isSafeInteger(sync.at) && Math.abs(sync.at!) <= 8_640_000_000_000_000;
+  const stamp = hasTimestamp ? `; automatic, last ${validTimestamp ? time(sync.at!) : "unknown"}` : "";
+  if (state === "not-configured" || state === "stopped") return `${state}${stamp}; next: ${memorySyncNextStep(state === "stopped" ? "stopped" : "remote")}`;
+  if (state === "ok" && Number.isSafeInteger(sync.withheldCount) && sync.withheldCount! >= 0
+    && Number.isSafeInteger(sync.exportedCount) && sync.exportedCount! >= 0)
+    return `ok${stamp}; ${sync.withheldCount} row${sync.withheldCount === 1 ? "" : "s"} withheld locally; ${sync.exportedCount} exported`;
+  if (state !== "failed") return `${state}${stamp}`;
+  const causes = ["declined", "remote", "binding", "stopped", "transport", "unknown"];
+  const cause = (causes.includes(sync.cause ?? "") ? sync.cause : "unknown") as MemorySyncCause;
+  if (cause === "declined" && sync.placementActive === false) {
+    const declined = Number.isSafeInteger(sync.declinedCount) && sync.declinedCount! >= 0 ? String(sync.declinedCount) : "unknown";
+    return "machine sync blocked: " + declined + " declined rows; per-row placement is not active on this store (agent-mem has no activation command yet, agent-mem#281). Inspect with `ahub memory declined`.";
+  }
+  const count = Number.isSafeInteger(sync.declinedCount) && sync.declinedCount! >= 0 ? `, ${sync.declinedCount} declined` : "";
+  const ids = cause === "declined" && sync.declinedIdsKnown === false ? "; declined ID set unknown" : "";
+  return `failed (${cause}${count})${stamp}${ids}; next: ${memorySyncNextStep(cause)}`;
+}
+
+/** Public-safe status guidance; never print journal exception text or provenance contents. */
+export function reviewInputHealthLine(health: ReviewInputHealthRow): string | undefined {
+  if (health.state === "healthy") return undefined;
+  const cause = health.state === "corrupt" && ["provenance_corrupt", "provenance_incomplete"].includes(health.cause ?? "") ? health.cause!
+    : health.state === "corrupt" ? "provenance_corrupt"
+    : health.state === "incomplete" && ["provenance_incomplete", "incomplete_markers", "legacy_coverage"].includes(health.cause ?? "") ? health.cause!
+    : "unknown";
+  const next = cause === "incomplete_markers" ? "verify the peer's next ordinary input or confirmed session change"
+    : cause === "legacy_coverage" ? "keep affected work held until review-input coverage is confirmed"
+    : "keep affected work held; inspect or repair only review-input provenance, preserving delivery and task state";
+  const state = health.state === "incomplete" || health.state === "corrupt" ? health.state : "unknown";
+  return `${state} (${cause}); next: ${next}`;
+}

package/src/cli/tail-render.ts

@@ -2,6 +2,7 @@ import type { BusEvent } from "../hub/bus.ts";
 
 export function renderTailEvent(e: BusEvent): string {
   if (e.t === "state") return `  . ${e.peer} is ${e.state}`;
+  if (e.t === "remote_delivery_settled") return `  . remote delivery ${e.deliveryId} settled for ${e.peer} (${e.outcome})`;
   if (e.t === "undeliverable") return `  ! gave up delivering ${e.env.id} (from ${e.env.from}) to ${e.peer}`;
   if (e.t === "envelope" && e.env.from === "hub" && e.env.kind !== "chat") {
     return `${new Date(e.env.ts).toLocaleTimeString()} hub -> ${e.env.to?.join(",")} [${e.env.kind}${e.env.refs?.task ? ` #${e.env.refs.task}` : ""}]\n${e.env.body.split("\n")[0]!.replace(/^/, "    ")}`;

package/src/cli/upgrade-interactive.ts

@@ -51,6 +51,11 @@ export interface UpgradeHost {
   entry: string;
   /** This CLI's version. */
   version: string;
+  /**
+   * #718 (#1179): lines to print after the upgrade completed, under the summary: the global CLI or the shared Claude plugin is older than the upgraded daemon and `ahub upgrade` does not update either.
+   * Never part of a blocked, cancelled or abandoned operation, and empty when nothing is older or the versions are unknown.
+   */
+  afterCompleted?(op: RecoveryOperation): Promise<string[]> | string[];
 }
 
 function emit(io: ScreenIO, lines: readonly string[]): void { for (const line of lines) io.out(line); }
@@ -69,6 +74,13 @@ async function summary(host: UpgradeHost, io: ScreenIO, op: RecoveryOperation):
   const live = await host.endInspection?.(op).catch(() => ({} as Record<string, Inspection | undefined>));
   emit(io, renderSummary(op, live ?? {}, io.presentation));
 }
+/** #718: the update step for the global CLI and plugin, once, after a completed upgrade (both callers have just seen `completed`). A host that cannot read the versions, or a failure reading them, prints nothing: it is advice, never a failure. */
+async function globalUpdate(host: UpgradeHost, io: ScreenIO, op: RecoveryOperation): Promise<void> {
+  if (op.plan.kind !== "upgrade") return;
+  let lines: string[] = [];
+  try { lines = await host.afterCompleted?.(op) ?? []; } catch { /* advice only */ }
+  for (const line of lines) human(io, line);
+}
 const clock = (io: ScreenIO) => io.presentation?.now() ?? Date.now();
 
 const yes = async (io: ScreenIO, question: string): Promise<boolean> => /^y(es)?$/i.test((await ask(io, question)) ?? "");
@@ -236,7 +248,7 @@ export async function operationScreen(host: UpgradeHost, io: ScreenIO, id: strin
   for (let acted = false, reset = false; ;) {
     if (io.interrupted()) return "quit";
     const op = host.read(id), runner = host.runner(id);
-    if (op.phase === "completed") { if (io.presentation) await summary(host, io, op); else human(io, `${op.plan.kind} to ${op.plan.version} completed`); return "completed"; }
+    if (op.phase === "completed") { if (io.presentation) await summary(host, io, op); else human(io, `${op.plan.kind} to ${op.plan.version} completed`); await globalUpdate(host, io, op); return "completed"; }
     if (op.phase === "cancelled") {
       if (io.presentation) await summary(host, io, op);
       else human(io, `operation ${id} is ${op.disposition ? "ended (abandoned, not completed)" : "cancelled"}; the recovery lock is free`);
@@ -351,7 +363,7 @@ export async function planScreen(host: UpgradeHost, io: ScreenIO): Promise<void>
       try { op = await host.apply(plan, () => io.interrupted()); } catch (error) { human(io, `ahub: ${(error as Error).message}`); continue; }
       human(io, `operation ${op.id} started; Enter opens its menu, Ctrl+C leaves, and neither stops the ${plan.kind}`);
       const end = await follow(host, io, op.id);
-      if (end === "completed") { if (io.presentation) await summary(host, io, host.read(op.id)); else human(io, `${plan.kind} to ${plan.version} completed`); return; }
+      if (end === "completed") { if (io.presentation) await summary(host, io, host.read(op.id)); else human(io, `${plan.kind} to ${plan.version} completed`); await globalUpdate(host, io, host.read(op.id)); return; }
       if (end === "left") return;
       // Blocked, cancelled or left to its runner: the lock check above opens its screen, or plans again once it is free.
     }

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/action-class.ts

@@ -171,6 +171,14 @@ function commands(text: string, nest = 0): Command[] | undefined {
 function object(value: unknown): Record<string, unknown> | undefined {
   return value !== null && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : undefined;
 }
+/**
+ * #725 (#1193): the device files a redirect can name without writing any file: `2>/dev/null` is the common case. Matched as the exact literal the command wrote, never as a resolved path, so
+ * `/dev/../tmp/x`, `/dev//null`, `/dev/null/x` and `/dev/sda` stay outputs outside the root. Only `/dev/null` and `/dev/tty` are listed (the person's ruling): no descriptor stands behind either. `/dev/stdout`,
+ * `/dev/stderr`, `/dev/fd/1` and `/dev/fd/2` reopen whatever file fd 1 or 2 already points at, and a `>` truncates it (`sh -c 'echo x >/dev/stdout' >>/tmp/log` truncates /tmp/log on Linux), so they stay
+ * outputs, as does every `/dev/fd/<n>`. The redirect itself is still recorded (`redirected`), so the read-only git fast path stays closed.
+ */
+const DEVICE_OUTPUTS: ReadonlySet<string> = new Set(["/dev/null", "/dev/tty"]);
+const isDeviceOutput = (target: string): boolean => DEVICE_OUTPUTS.has(target);
 function outside(target: string, root: string, cwd: string): boolean {
   if (!isAbsolute(root) || !target || /[$`]/.test(target)) return false;
   if (target.startsWith("~") || !cwd && !isAbsolute(target)) return true;
@@ -646,7 +654,7 @@ function classify(command: Command, root: string, cwd: string[], found: Set<Acti
       if (nested) sequence(nested, root, cwd, found, depth + 1, bare ? floor : undefined);
     }
   }
-  if (command.outputs.some(p => cwd.some(at => outside(p, root, at)))) found.add("destroy");
+  if (command.outputs.some(p => !isDeviceOutput(p) && cwd.some(at => outside(p, root, at)))) found.add("destroy");
   if (program === "git") {
     const heads = commandHeads(words, ["-C", "-c", "--git-dir", "--work-tree", "--namespace", "--config-env"],
       ["-P", "-p", "--no-pager", "--paginate", "--literal-pathspecs", "--bare", "--no-optional-locks", "--no-replace-objects"], ["push", "reset", "clean", "branch"]);