@staix/agent-hub 0.28.0 → 0.30.0

package/src/hub/worktree-shelf.ts

@@ -0,0 +1,246 @@
+import { execFile } from "node:child_process";
+import { stat } from "node:fs/promises";
+import { basename, join, relative, sep } from "node:path";
+import { childEnv } from "./child-process.ts";
+import { hubGitArgv, hubGitEnv } from "./git.ts";
+import { HUB } from "./envelope.ts";
+import { realPath } from "./project.ts";
+import type { Task } from "./board.ts";
+
+/**
+ * #1057 worktree shelf. Which worktrees are finished is DERIVED at read time from facts and two person overrides, never stored as a flag.
+ * This module reads facts and computes the partition. It never deletes a worktree or a local branch: removal exists only in the person's
+ * CLI process (`worktree-tidy.ts`, a later change), and `test/worktree-shelf.test.ts` greps the daemon-reachable modules for any removal argv.
+ */
+
+export type PrState = "open" | "merged" | "closed" | "unknown";
+/** `settled` is what a PII-bound row says in a reply for a merged or closed PR: the reason is real on the host, but a reply carries no PR state of a private task. */
+export type SettledReason = "merged" | "closed" | "quiet" | "parked" | "settled";
+export type OverrideValue = "settled" | "active";
+export interface WorktreeOverride { path: string; value: OverrideValue; at: number }
+
+export interface WorktreeFact {
+  /** Absolute, host-only. A row shown to a person is displayed through `displayPath`. */
+  path: string;
+  branch: string | null;
+  head: string;
+  locked: boolean;
+  prunable: boolean;
+  /** The project's main checkout: never shelved. */
+  main: boolean;
+  /** A configured instance worktree (`.worktrees/<instance>`): never shelved. */
+  instance: boolean;
+  /** Max of the HEAD commit time, the worktree index mtime and the latest time someone other than the hub wrote to the bound task. 0 when none could be read. */
+  lastActiveAt: number;
+  /** False when the commit time or the index could not be read (a failed git call or a spent budget): such a row is never settled by a PR or by quiet time, because 'no newer work' is unknown. */
+  activityKnown?: boolean;
+  /** `private`: the bound task is a PII task. The binding still drives the partition and tidy's refusals on the host, but `row()` never puts its id, PR or state in a reply. */
+  task?: { id: number; state: string; pr?: number; repo?: string; private?: true };
+  pr: { state: PrState; changedAt?: number };
+}
+/** A row built for a reply. A PII-bound row carries `private: true` and `taskState: "private"` and no task id or PR. This is the one place a reply row is made, so redaction happens here (AGENTS.md), never at a call site. */
+export interface ShelfRow { path: string; branch: string | null; reason?: SettledReason; task?: number; taskState?: string; pr?: number; private?: true; /** The main checkout or a declared instance worktree: never shelved, so a panel offers no Park for it. */ fixed?: true; lastActiveAt: number }
+export interface Partition { live: ShelfRow[]; settled: ShelfRow[] }
+
+const DAY_MS = 86_400_000;
+const row = (fact: WorktreeFact, reason?: SettledReason): ShelfRow => ({
+  path: fact.path, branch: fact.branch, lastActiveAt: fact.lastActiveAt, ...(fact.main || fact.instance ? { fixed: true as const } : {}),
+  ...(reason ? { reason: fact.task?.private && (reason === "merged" || reason === "closed") ? "settled" as const : reason } : {}),
+  ...(fact.task?.private ? { private: true as const, taskState: "private" }
+    : { ...(fact.task ? { task: fact.task.id, taskState: fact.task.state } : {}), ...(fact.task?.pr !== undefined ? { pr: fact.task.pr } : {}) }),
+});
+
+/** An override counts only while no newer activity exists: `lastActiveAt <= at` (D2). Newer activity makes it inert. */
+export const overrideInForce = (override: WorktreeOverride | undefined, lastActiveAt: number): override is WorktreeOverride =>
+  !!override && lastActiveAt <= override.at;
+
+/**
+ * D3, pure. A row whose activity is unknown (`activityKnown === false`) is live: every settling rule compares with `lastActiveAt`, which is then not a fact.
+ * Rules in order: (1) the main checkout and instance worktrees are never shelved; (2) an effective override wins; (3) a merged or
+ * closed PR with `lastActiveAt <= changedAt` is settled; (4) `quietDays > 0` and a quiet span of at least that long is settled; (5) live.
+ * `now`, the facts and the overrides are arguments: no clock, no I/O.
+ */
+export function partition(facts: readonly WorktreeFact[], overrides: readonly WorktreeOverride[], now: number, quietDays: number): Partition {
+  const byPath = new Map(overrides.map(o => [o.path, o]));
+  const out: Partition = { live: [], settled: [] };
+  for (const fact of facts) {
+    if (fact.main || fact.instance || fact.activityKnown === false) { out.live.push(row(fact)); continue; }
+    const override = byPath.get(fact.path);
+    if (overrideInForce(override, fact.lastActiveAt)) {
+      if (override.value === "settled") out.settled.push(row(fact, "parked")); else out.live.push(row(fact));
+      continue;
+    }
+    if ((fact.pr.state === "merged" || fact.pr.state === "closed") && fact.pr.changedAt !== undefined && fact.lastActiveAt <= fact.pr.changedAt) {
+      out.settled.push(row(fact, fact.pr.state)); continue;
+    }
+    if (quietDays > 0 && fact.lastActiveAt > 0 && now - fact.lastActiveAt >= quietDays * DAY_MS) { out.settled.push(row(fact, "quiet")); continue; }
+    out.live.push(row(fact));
+  }
+  return out;
+}
+
+/** Project-relative inside the root (the root itself is `.`), otherwise the basename only: paths stay host-only, as in `snapshots.ts`. */
+export function displayPath(root: string, path: string): string {
+  if (path === root) return ".";
+  const rel = relative(root, path);
+  return rel && !rel.startsWith("..") && !rel.startsWith(sep) && rel !== path ? rel : basename(path);
+}
+
+/** Whether a path is the root or below it, so a row can be resolved against the project root and one outside it cannot. */
+export const shelfInsideRoot = (root: string, path: string): boolean => path === root || (!relative(root, path).startsWith("..") && !relative(root, path).startsWith(sep) && relative(root, path) !== path);
+
+/**
+ * The latest time anyone but the hub wrote to a task: its work, not its bookkeeping. The hub's own entries (the merge result, the owner notice,
+ * sweeps) follow the event they record, so counting them would put `lastActiveAt` after a merge's `changedAt` and a merged task could never settle (#1057 D1/D3).
+ */
+export const taskWorkAt = (task: Pick<Task, "history" | "created">): number =>
+  Math.max(task.created, ...task.history.filter(h => h.by !== HUB && Number.isFinite(h.at)).map(h => h.at));
+
+/** The task a worktree branch belongs to: the open task, else the most recently updated one, whose `refs.branch` equals the branch. */
+export function boundTask(tasks: readonly Pick<Task, "id" | "state" | "refs" | "sdlc" | "updated" | "created" | "history">[], branch: string | null): WorktreeFact["task"] & { workAt: number } | undefined {
+  if (!branch) return undefined;
+  const matching = tasks.filter(t => t.refs.branch === branch);
+  if (!matching.length) return undefined;
+  const closed = (state: string) => state === "approved" || state === "cancelled";
+  const pick = [...matching].sort((a, b) => Number(closed(a.state)) - Number(closed(b.state)) || b.updated - a.updated)[0]!;
+  const pr = pick.sdlc?.pr, repo = pick.sdlc?.repo;
+  return { id: pick.id, state: pick.state, ...(typeof pr === "number" ? { pr } : {}), ...(typeof repo === "string" && typeof pr === "number" ? { repo } : {}), workAt: taskWorkAt(pick) };
+}
+
+/**
+ * PR state from evidence already on the board (D1): only the guarded merge's own record says `merged`. A cancelled task says nothing about its PR (`Tasks.cancel`
+ * touches only the board, so the PR can still be open on GitHub), and a task with no record says nothing either: both are `unknown`. Only the explicit refresh
+ * action, which reads GitHub, may learn `closed` or `open` (a later change).
+ */
+export function prFromTask(task: Pick<Task, "state" | "sdlc" | "history"> | undefined, observed?: PrObserver): WorktreeFact["pr"] {
+  const merge = task?.sdlc?.merge;
+  if (merge && merge.state === "merged" && Number.isFinite(merge.at)) return { state: "merged", changedAt: merge.at };
+  // A PR state the person asked the hub to read (the explicit refresh action) is a stored fact, never fetched here: this module has no GitHub access (AC5).
+  const repo = task?.sdlc?.repo, pr = task?.sdlc?.pr;
+  const seen = typeof repo === "string" && typeof pr === "number" ? observed?.(repo, pr) : undefined;
+  if (seen) return { state: seen.state, ...(seen.changedAt !== undefined && seen.state !== "open" ? { changedAt: seen.changedAt } : {}) };
+  return { state: "unknown" };
+}
+/** The stored result of an explicit PR refresh for one repository and PR number, or undefined when none was read. */
+export type PrObserver = (repo: string, pr: number) => { state: "open" | "merged" | "closed"; changedAt?: number } | undefined;
+
+export interface RawWorktree { path: string; branch: string | null; head: string; locked: boolean; prunable: boolean }
+/** `git worktree list --porcelain -z`: one NUL-separated field per attribute, an empty field ends a record. Bounded. */
+export function parseWorktreeList(stdout: string, limit = 256): { rows: RawWorktree[]; complete: boolean } {
+  const rows: RawWorktree[] = [];
+  let current: Partial<RawWorktree> | undefined;
+  const flush = () => { if (current?.path) rows.push({ path: current.path, branch: current.branch ?? null, head: current.head ?? "", locked: !!current.locked, prunable: !!current.prunable }); current = undefined; };
+  for (const field of stdout.split("\0")) {
+    if (field === "") { flush(); continue; }
+    if (field.startsWith("worktree ")) { flush(); current = { path: field.slice(9) }; continue; }
+    if (!current) continue;
+    if (field.startsWith("HEAD ")) current.head = field.slice(5);
+    else if (field.startsWith("branch refs/heads/")) current.branch = field.slice("branch refs/heads/".length);
+    else if (field === "locked" || field.startsWith("locked ")) current.locked = true;
+    else if (field === "prunable" || field.startsWith("prunable ")) current.prunable = true;
+  }
+  flush();
+  return { rows: rows.slice(0, limit), complete: rows.length <= limit };
+}
+
+export interface ShelfGitPort {
+  /** Read-only git, bounded by `timeoutMs`, never blocking the event loop. `undefined` is a failed or timed-out read, never an empty answer. */
+  run(cwd: string, args: string[], timeoutMs: number): Promise<{ status: number | null; stdout: string } | undefined>;
+}
+/** One git call's ceiling, and the whole read's: a slow repository answers `complete: false` after this, never a stalled hub (D1's snapshot-budget pattern). */
+export const READ_TIMEOUT_MS = 5_000, TOTAL_BUDGET_MS = 3_000, READ_CONCURRENCY = 4;
+export const realShelfGit: ShelfGitPort = {
+  async run(cwd, args, timeoutMs) {
+    if (!shelfReadAllowed(args)) throw new Error("the worktree shelf runs read-only git commands only");
+    const argv = hubGitArgv(["-C", cwd, "-c", "gc.auto=0", "-c", "maintenance.auto=false", ...args]);
+    return await new Promise(resolve => {
+      execFile(argv[0]!, argv.slice(1), { encoding: "utf8", timeout: Math.max(1, Math.min(READ_TIMEOUT_MS, timeoutMs)), killSignal: "SIGKILL", maxBuffer: 1024 * 1024, env: hubGitEnv(childEnv(), { repositoryIsolation: true }) }, (error, stdout) => {
+        const code = (error as (Error & { code?: unknown }) | null)?.code;
+        // a non-zero exit is an answer (status), a spawn failure, timeout or overflow is not
+        resolve(error && typeof code !== "number" ? undefined : { status: typeof code === "number" ? code : 0, stdout: String(stdout ?? "") });
+      });
+    });
+  },
+};
+/**
+ * The only git argv shapes the shelf runs, all reads. `realShelfGit.run` refuses anything else before spawning, so no removal, branch, ref or
+ * prune argv can reach git from the daemon (AC4); the boundary test also greps the module text for them.
+ */
+export const SHELF_GIT_READS: readonly (readonly string[])[] = [
+  ["worktree", "list", "--porcelain", "-z"],
+  ["log", "-1", "--format=%ct", "HEAD"],
+  ["rev-parse", "--absolute-git-dir"],
+];
+export const shelfReadAllowed = (args: readonly string[]): boolean => SHELF_GIT_READS.some(shape => shape.length === args.length && shape.every((word, i) => word === args[i]));
+
+export interface ShelfInput {
+  root: string;
+  /** Called AFTER the git reads, so the board is read once and fresh, never held across an await. */
+  tasks: () => readonly Pick<Task, "id" | "state" | "refs" | "sdlc" | "updated" | "created" | "history">[];
+  /** Whether a task is a PII task (`Tasks.isPii`). Its binding is kept for the partition and the refusals and redacted in the reply row. A host that does not pass it treats no task as private. */
+  isPrivate?: (taskId: number) => boolean;
+  /** Resolved instance worktree paths (`.worktrees/<instance>`): never shelved. */
+  instancePaths: readonly string[];
+  /** Stored PR observations (D1); called after the git reads, in the same synchronous segment as `tasks`. */
+  observed?: PrObserver;
+  git?: ShelfGitPort;
+  now?: () => number;
+  budgetMs?: number;
+}
+export interface ShelfFacts { facts: WorktreeFact[]; complete: boolean; available: boolean }
+
+/** The worktree's own index mtime (D1: it covers uncommitted editing). `undefined` is unknown; a missing index file is a known 0. */
+async function indexMtime(git: ShelfGitPort, path: string, timeoutMs: number): Promise<number | undefined> {
+  const dir = await git.run(path, ["rev-parse", "--absolute-git-dir"], timeoutMs);
+  if (!dir || dir.status !== 0) return undefined;
+  try { const info = await stat(join(dir.stdout.trim(), "index")); return info.isFile() ? info.mtimeMs : 0; }
+  catch (error) { return (error as NodeJS.ErrnoException).code === "ENOENT" ? 0 : undefined; }
+}
+
+interface Probe { commitAt: number; touched: number; known: boolean }
+
+/**
+ * D1: facts per worktree. One `worktree list`, then a commit-time read and an index read per worktree, at most `READ_CONCURRENCY` at a time and all under one
+ * total budget. Asynchronous throughout: the daemon's event loop is never held. When the budget is spent, the rows not yet read are still listed, with unknown
+ * activity (live, never settled), and the result says `complete: false`. Never writes.
+ */
+export async function readWorktreeFacts(input: ShelfInput): Promise<ShelfFacts> {
+  const git = input.git ?? realShelfGit, now = input.now ?? Date.now, deadline = now() + (input.budgetMs ?? TOTAL_BUDGET_MS);
+  const left = () => Math.max(0, deadline - now());
+  let root: string;
+  try { root = realPath(input.root); } catch { return { facts: [], complete: false, available: false }; }
+  const listed = await git.run(root, ["worktree", "list", "--porcelain", "-z"], left());
+  if (!listed || listed.status !== 0) return { facts: [], complete: false, available: false };
+  const parsed = parseWorktreeList(listed.stdout);
+  const paths = parsed.rows.map(raw => { try { return realPath(raw.path); } catch { return raw.path; } }); // a prunable worktree's directory is gone: keep the registered path
+  const probes: (Probe | undefined)[] = parsed.rows.map(() => undefined);
+  let next = 0, cut = false;
+  const worker = async () => {
+    for (;;) {
+      const i = next++;
+      if (i >= paths.length) return;
+      if (left() <= 0) { cut = true; return; }
+      const stamp = await git.run(paths[i]!, ["log", "-1", "--format=%ct", "HEAD"], left());
+      const text = stamp && stamp.status === 0 ? stamp.stdout.trim() : "";
+      const touched = left() > 0 ? await indexMtime(git, paths[i]!, left()) : undefined;
+      if (!/^\d{1,12}$/.test(text) || touched === undefined) { probes[i] = { commitAt: 0, touched: 0, known: false }; cut = cut || left() <= 0; continue; }
+      probes[i] = { commitAt: Number(text) * 1000, touched, known: true };
+    }
+  };
+  await Promise.all(Array.from({ length: Math.min(READ_CONCURRENCY, paths.length) }, worker));
+  // From here to the return nothing is awaited: the board is read once, synchronously, so it is current for every row.
+  const tasks = input.tasks(), instances = new Set(input.instancePaths), facts: WorktreeFact[] = [];
+  let unread = false;
+  parsed.rows.forEach((raw, i) => {
+    const path = paths[i]!, probe = probes[i], task = boundTask(tasks, raw.branch), bound = task ? tasks.find(t => t.id === task.id) : undefined;
+    if (!probe?.known) unread = true;
+    facts.push({
+      path, branch: raw.branch, head: raw.head, locked: raw.locked, prunable: raw.prunable,
+      main: path === root, instance: instances.has(path),
+      lastActiveAt: Math.max(probe?.commitAt ?? 0, probe?.touched ?? 0, task?.workAt ?? 0), activityKnown: probe?.known === true,
+      ...(task ? { task: { id: task.id, state: task.state, ...(task.pr !== undefined ? { pr: task.pr } : {}), ...(task.repo !== undefined ? { repo: task.repo } : {}), ...(input.isPrivate?.(task.id) ? { private: true as const } : {}) } } : {}),
+      pr: prFromTask(bound, input.observed),
+    });
+  });
+  return { facts, complete: parsed.complete && !cut && !unread, available: true };
+}

package/src/local/deny.ts

@@ -77,6 +77,54 @@ const hooksUnder = (parent: string): string => {
   return depth > MAX_ANCHOR_DEPTH ? `^.*/${hfsFoldedName("hooks")}(/|$)` : `^${"/[^/]+".repeat(depth)}/${hfsFoldedName("hooks")}(/|$)`;
 };
 
+/**
+ * #1123: a sandboxed command may not move what a branch, HEAD or a linked worktree points at. `refs/**` (branches, tags, `refs/stash`), `packed-refs*`, `HEAD*` (its lock too) and
+ * `worktrees/**` (a linked worktree's admin dir: its HEAD, index, logs) are refused directly under every plain `.git` and under each external git dir (the common dir and a linked
+ * worktree's own, whatever they are named). The hub's own git runs outside the sandbox and is unaffected, so #1115's hub commit still lands.
+ *
+ * Every name must sit DIRECTLY under its git dir. An unanchored `refs` or `worktrees` filter would also match an ANCESTOR of the project with that name, and a project under
+ * `~/worktrees/` would lose every `.git` write (the #520 `hooks` lesson). So each rule is adjacent by construction: one literal for `.git` + a short name, or, for the long names
+ * (`worktrees`, `packed-refs`, where `.git` + name would pass the 1024-byte literal limit), a front half and a back half that must both match, or a depth anchor for an external dir.
+ * A submodule's git dir (`.git/modules/<name>`, nested ones, and `.git/worktrees/<wt>/modules/<name>` for a linked worktree) is covered the same way (`subDirs`, the discovered
+ * ones: a git dir that is not discovered is refused whole by the #518/#520 rules), per the person's "deny .git writes" decision: nothing is listed as a residual.
+ */
+const refDepth = (d: string): number => d.split("/").filter(Boolean).length;
+/**
+ * `^(/[^/]+){depth}/<name>(/|$)`: `name` as the entry directly under `d`, the depth written out because seatbelt ignores `{n}`. The folded names cost (measured, bytes of regex): `refs` 334,
+ * `worktrees` 669, so past the depth where the path plus the name would near 1024 it falls back to the unanchored name, which over-refuses only under an ancestor with that name and
+ * never under-protects.
+ */
+const refUnder = (d: string, name: string): string => {
+  const depth = refDepth(d), cost = Buffer.byteLength(hfsFoldedName(name)) + depth * 6 + 8;
+  return cost > 1000 ? `^.*/${hfsFoldedName(name)}(/|$)` : `^${"/[^/]+".repeat(depth)}/${hfsFoldedName(name)}(/|$)`;
+};
+function gitRefRules(gitDirs: string[], subDirs: string[] = []): string[] {
+  const git = hfsFoldedName(".git");
+  const re = (s: string) => `(regex ${sbplString(s)})`;
+  const name = (n: string) => hfsFoldedName(n);
+  // A linked worktree's own submodule git dirs (`worktrees/<wt>/modules/**`) are governed by the #518/#520 rules, not these.
+  const plainSub = `(require-not ${re(`^.*/${git}/worktrees/[^/]+/modules(/|$)`)})`;
+  const plain = [
+    // `.git` (335 bytes) + `HEAD` or `refs` (334) fit one literal: adjacent by construction. `HEAD.lock` goes with `HEAD`.
+    re(`^.*/${git}/${name("HEAD")}(\\.lock)?$`),
+    re(`^.*/${git}/${name("refs")}(/|$)`),
+    // `.git` + `packed-refs` (803) and `.git` + `worktrees` (669) do not fit one literal. The front literal pins the start of the name right under a `.git`, and for `worktrees` the
+    // back literal pins its end; `packed` alone covers `packed-refs` and its lock/new files, which is the intent.
+    re(`^.*/${git}/${name("packed")}`),
+    `(require-all ${re(`^.*/${git}/${name("work")}`)} ${re(`^.*${name("trees")}(/|$)`)} ${plainSub})`,
+  ];
+  const external = [...gitDirs, ...subDirs].flatMap((d) => {
+    const own = sbplString(d), direct = re(`^${sbplEscape(d)}/[^/]+$`);
+    return [
+      `(require-all ${direct} ${re(`^.*/${name("HEAD")}(\\.lock)?$`)})`,
+      `(require-all ${direct} ${re(`^.*/${name("packed")}`)})`,
+      `(require-all (subpath ${own}) ${re(refUnder(d, "refs"))})`,
+      `(require-all (subpath ${own}) ${re(refUnder(d, "worktrees"))} (require-not ${re(`^${sbplEscape(d)}/worktrees/[^/]+/modules(/|$)`)}))`,
+    ];
+  });
+  return [...plain, ...external];
+}
+
 export function hubWriteRegexes(root: string, gitDirs: string[] = [], moduleGit: readonly { root: string; entries: string[]; dirs?: string[] }[] = [], worktreesRoot?: string): string[] {
   const git = hfsFoldedName(".git");
   const re = (s: string) => `(regex ${sbplString(s)})`;
@@ -157,6 +205,7 @@ export function hubWriteRegexes(root: string, gitDirs: string[] = [], moduleGit:
     `(require-all ${re(`^.*/${git}/[^/]+$`)} ${CONFIG_WORKTREE_NAME.map(re).join(" ")})`,
     re(`^.*/${git}/${hfsFoldedName("hooks")}(/|$)`),
     `(require-all ${re(`^.*/${git}/.*$`)} ${re(`^.*/${hfsFoldedName("commondir")}$`)})`,
+    ...gitRefRules(gitDirs, allDirs),
     ...modules,
     ...siblings,
     ...external,

package/src/local/tools.ts

@@ -117,7 +117,7 @@ export const TOOL_SCHEMAS = [
   fn("write", "Create or overwrite a file inside the project. Needs the user's approval.", { path: str, content: str }, ["path", "content"]),
   fn("edit", "Replace one exact, unique occurrence of `old` with `new` in a file. Needs the user's approval.", { path: str, old: str, new: str }, ["path", "old", "new"]),
   fn("bash", "Run a shell command in the project directory, sandboxed: no writes outside the project, no credential reads, no network unless the hub enables it. Follows hub permission policy: proven bounded read-only commands may run automatically in ask-when-needed; other commands ask.", { command: str, timeout_s: { type: "integer", minimum: 1, maximum: 600 } }, ["command"]),
-  fn("git", "Run git in the project. status, diff, log, show, ls-files, blame, rev-parse run freely; add, commit, restore, checkout, switch, stash, mv, rm, branch, merge, rebase, cherry-pick, revert, tag need approval; everything else (push, fetch, config, remote ...) is refused.", { args: { type: "array", items: str, minItems: 1 } }, ["args"]),
+  fn("git", "Run git in the project. status, diff, log, show, ls-files, blame, rev-parse run freely; add, commit, restore, checkout, switch, stash, mv, rm, branch, merge, rebase, cherry-pick, revert, tag need approval; everything else (push, fetch, config, remote ...) is refused. The sandbox does not let you move a branch, tag or HEAD anywhere (commit, branch, tag, stash, switch, merge, rebase and reset fail, submodules included), nor stage with add inside a linked worktree: edit files, and the hub commits and pushes them when you call hub_task_done.", { args: { type: "array", items: str, minItems: 1 } }, ["args"]),
   fn("hub_send", "Send a message to the other agents now, before your turn ends. Conclusions only. Your final answer is shared anyway; use this for something that cannot wait.", { text: str, to: { type: "array", items: str } }, ["text"]),
 ];
 
@@ -235,7 +235,9 @@ export async function runTool(name: string, rawArgs: string, ctx: ToolContext):
         // Sandboxed like bash: flags such as --output or an editor cannot write outside the project or reach the network.
         const res = await sandboxedExec(["git", "--no-pager", ...args], { cwd: ctx.cwd, profile: ctx.sandboxProfile, readOnlyData: !!ctx.readOnly?.length, ...(ctx.sandboxEnv ? { env: ctx.sandboxEnv } : {}), ...(ctx.signal ? { signal: ctx.signal } : {}) });
         try { ctx.onProcessExit?.(res.code); } catch { /* optional status observer never changes a tool result */ }
-        return `${res.output}\n(exit ${res.code})`;
+        // #1123: the profile refuses writes to refs, HEAD, packed-refs and a linked worktree's admin dir, so a commit, branch, tag, stash or switch cannot succeed here. Say so, with the next step.
+        const refused = res.code !== 0 && /(?:\.git\/(?:refs|HEAD|packed-refs|worktrees)\b|cannot lock ref|index\.lock)[^\n]*(?:Operation not permitted|not permitted)/i.test(res.output);
+        return `${res.output}${refused ? "\nnote: the sandbox does not let you move a branch, tag or HEAD, or stage inside a linked worktree (#1123). Leave your edits in the working tree and finish with hub_task_done. For implementation work the hub stages, commits and pushes them for you; for work that changes no files, or a private task, there is nothing for it to commit, so do not try to commit it yourself." : ""}\n(exit ${res.code})`;
       }
       case "doc_read": {
         if (!ctx.docRead) return "error: doc_read is not enabled for this project (local.doc_read in .agenthub/config.local.json)";

package/src/memory/brief.ts

@@ -1,4 +1,5 @@
 import { buildIntentBrief, type IntentBriefOptions, type IntentBriefSource } from "@staix/agent-mem";
+import { controlWriteSpan } from "../hub/control-write-trace.ts";
 import type { PeerId } from "../hub/envelope.ts";
 import type { MemoryClient } from "./client.ts";
 
@@ -70,6 +71,10 @@ export class Briefs {
   ) {}
 
   async forTask(peer: PeerId, task: BriefTask, priority: readonly NativeItem[] = []): Promise<string | undefined> {
+    return controlWriteSpan("memory", () => this.forTaskBody(peer, task, priority));
+  }
+
+  private async forTaskBody(peer: PeerId, task: BriefTask, priority: readonly NativeItem[]): Promise<string | undefined> {
     // A brief snapshots its configured cap once, before either optional source is selected.
     const maximum = typeof this.maxItems === "function" ? this.maxItems() : this.maxItems;
     let corpusRevision: string | undefined;

package/src/memory/capture.ts

@@ -38,7 +38,7 @@ export class Capture {
   }
 
   observe(call: { tool: string; args: string; output: string; id: string; paths: string[]; sourceId?: string }): void {
-    if (!this.sessionId || ((MEMORY_READ_TOOLS.has(call.tool.replace(/^mcp__[^ ]+__/, "")) || BOUNDED_TASK_TOOLS.has(call.tool.replace(/^mcp__[^ ]+__/, "")) || CAPABILITY_TOOLS.has(call.tool.replace(/^mcp__[^ ]+__/, "")) || STUDY_TOOLS.has(call.tool.replace(/^mcp__[^ ]+__/, "")) || HANDOFF_TOOLS.has(call.tool.replace(/^mcp__[^ ]+__/, ""))) || call.tool.replace(/^mcp__[^ ]+__/, "") === "hub_memory_correct") || call.tool.replace(/^mcp__[^ ]+__/, "") === "hub_source_read" || this.opts.skip?.includes(call.tool)) return;
+    if (!this.sessionId || ((MEMORY_READ_TOOLS.has(call.tool.replace(/^mcp__[^ ]+__/, "")) || BOUNDED_TASK_TOOLS.has(call.tool.replace(/^mcp__[^ ]+__/, "")) || CAPABILITY_TOOLS.has(call.tool.replace(/^mcp__[^ ]+__/, "")) || STUDY_TOOLS.has(call.tool.replace(/^mcp__[^ ]+__/, "")) || HANDOFF_TOOLS.has(call.tool.replace(/^mcp__[^ ]+__/, ""))) || call.tool.replace(/^mcp__[^ ]+__/, "") === "hub_memory_correct") || call.tool.replace(/^mcp__[^ ]+__/, "") === "hub_source_read" || call.tool.replace(/^mcp__[^ ]+__/, "") === "hub_set_title" || this.opts.skip?.includes(call.tool)) return;
     // Anything that names a denylisted path is kept out of memory entirely, input and output alike.
     if (call.paths.some((p) => isDenied(p, this.opts.deny) || p.split(/\s+/).some((word) => isDenied(word, this.opts.deny)))) return;
     // ponytail: legacy callers without a host sourceId dedupe native ids within a summary interval; all live LocalPeer calls supply invocation identity. Require that port for other hosts.

package/src/memory/client.ts

@@ -1,5 +1,6 @@
 import packageJson from "../../package.json";
 import { createHash } from "node:crypto";
+import { controlWriteSpan } from "../hub/control-write-trace.ts";
 import { CaptureStore, SearchIndex, looksSecret, memoryBase, readCaptureConfig, type CaptureOptions as StoreCaptureOptions, type MemoryStore, type CandidateStore, type View } from "@staix/agent-mem";
 
 export interface CaptureEvent {
@@ -54,8 +55,10 @@ export class MemoryClient {
   }
   close(): void { this.closed = true; this.releaseCapture(); }
   private run<T>(work: (o: MemoryClientOptions) => T): T | undefined {
-    try { if (!this.options || this.closed) return undefined; this.options.check(); return work(this.options); }
-    catch { this.releaseCapture(); this.options?.log?.("amem operation unavailable"); return undefined; }
+    return controlWriteSpan("memory", () => {
+      try { if (!this.options || this.closed) return undefined; this.options.check(); return work(this.options); }
+      catch { this.releaseCapture(); this.options?.log?.("amem operation unavailable"); return undefined; }
+    });
   }
   private rows(o: MemoryClientOptions): View[] {
     const store = o.store;

package/src/pi/extension.ts

@@ -23,6 +23,8 @@ let shellSeq = 0;
 let forcedFailure = "";
 let turnGeneration = 0;
 let sessionId = "";
+let titleRevision = 0;
+let titleEpoch = "";
 let pendingPromptId: string | undefined;
 let activePromptId: string | undefined;
 let settlement: Promise<void> | undefined;
@@ -93,11 +95,36 @@ async function poll(pi: ExtensionAPI): Promise<void> {
             await post("/ack", { id: command.id, ok: false, error: "Pi prompt insertion did not synchronously claim a native turn", refusal: { kind: "prompt_uncertain", promptId: command.id, sessionId, generation: turnGeneration } });
             continue;
           }
+        } else if (command.type === "set_session_title") {
+          const refuse = (cause: string, error: string) => post("/ack", { id: command.id, ok: true, result: { ok: false, reason: "invalid", cause, error, sessionId, titleEpoch, titleRevision } });
+          const nativeId = runtimeCtx?.sessionManager?.getHeader?.()?.id;
+          if (command.sessionId !== sessionId || nativeId !== sessionId || command.titleEpoch !== undefined && command.titleEpoch !== titleEpoch) {
+            await refuse("session", "Pi native session changed before the title write; check ahub status and reconnect the current session before retrying."); continue;
+          }
+          if (command.generation !== turnGeneration) {
+            await refuse("generation", "Pi native turn changed before the title write; wait for the current turn and check ahub status before retrying."); continue;
+          }
+          if (typeof command.title !== "string" || !command.title.trim() || [...command.title].length > 80 || typeof command.onlyIfUnnamed !== "boolean") {
+            await refuse("arguments", "Pi title command arguments are invalid; use a 1-80 character normalized title and a conditional-write flag before retrying."); continue;
+          }
+          if (typeof pi.getSessionName !== "function" || typeof pi.setSessionName !== "function") {
+            await refuse("native_unavailable", "Pi native title API is unavailable; restart Pi with the supported hub extension and check ahub status before retrying."); continue;
+          }
+          // The native read and synchronous write share one JS turn: a manual rename always wins against the agent.
+          const before = pi.getSessionName() ?? "";
+          if (command.onlyIfUnnamed && before) {
+            await post("/ack", { id: command.id, ok: true, result: { ok: false, reason: "already_named", error: "This session already has a title; keep it or ask the person to rename it with ahub title.", sessionId, titleEpoch, titleRevision, sessionName: before } }); continue;
+          }
+          pi.setSessionName(command.title);
+          const sessionName = pi.getSessionName() ?? "";
+          await post("/ack", { id: command.id, ok: true, result: { ok: sessionName === command.title, ...(sessionName === command.title ? {} : { reason: "invalid", cause: "native_readback", mayHaveApplied: true, error: "Pi native title readback did not confirm the write; the title may have been applied; check ahub status before retrying." }), sessionId, titleEpoch, titleRevision, sessionName } });
+          continue;
         } else if (command.type === "get_session_state") {
           const entries = runtimeCtx.sessionManager.getEntries();
           await post("/ack", { id: command.id, ok: true, result: {
             sessionId: runtimeCtx.sessionManager.getHeader()?.id,
             sessionFile: runtimeCtx.sessionManager.getSessionFile(),
+            ...(typeof pi.getSessionName === "function" ? { sessionName: pi.getSessionName() ?? "", titleEpoch, titleRevision } : {}),
             idle: runtimeCtx.isIdle() === true,
             empty: entries.every((entry: any) => ["model_change", "thinking_level_change"].includes(entry.type)),
           } });
@@ -120,7 +147,14 @@ async function poll(pi: ExtensionAPI): Promise<void> {
           }
         }
         await post("/ack", { id: command.id, ok: true });
-      } catch (error) { if (pendingPromptId === command.id) pendingPromptId = undefined; await post("/ack", { id: command.id, ok: false, error: (error as Error).message }); }
+      } catch (error) {
+        if (command.type === "set_session_title") {
+          await post("/ack", { id: command.id, ok: true, result: { ok: false, reason: "invalid", cause: "native_failed", mayHaveApplied: true, error: "Pi native title API failed without confirming the write; the title may have been applied; check ahub status before retrying.", sessionId, titleEpoch, titleRevision } });
+          continue;
+        }
+        if (pendingPromptId === command.id) pendingPromptId = undefined;
+        await post("/ack", { id: command.id, ok: false, error: (error as Error).message });
+      }
     } catch { await new Promise((resolve) => setTimeout(resolve, 250)); }
   }
 }
@@ -142,8 +176,9 @@ export default function(pi: ExtensionAPI): void {
     shutdown = ctx.shutdown;
     const state = ctx.sessionManager.getHeader();
     sessionId = String(state?.id ?? "");
+    titleRevision = 0; titleEpoch = crypto.randomUUID();
     try {
-      const claimed = await post("/event", { type: "session_start", ownerToken, pid: process.pid, signature: processSignature(process.pid), sessionId: state?.id, sessionFile: ctx.sessionManager.getSessionFile(), approvalTurnAbort: typeof ctx.abort === "function", fencedPrompt: true });
+      const claimed = await post("/event", { type: "session_start", ownerToken, pid: process.pid, signature: processSignature(process.pid), ...(typeof pi.getSessionName === "function" ? { sessionName: pi.getSessionName() ?? "", titleEpoch, titleRevision } : {}), sessionId: state?.id, sessionFile: ctx.sessionManager.getSessionFile(), approvalTurnAbort: typeof ctx.abort === "function", fencedPrompt: true });
       if (claimed?.ok === false) { ctx.shutdown?.(); return; }
     } catch (error) { ctx.shutdown?.(); throw error; }
     if (!pollStarted) { pollStarted = true; void poll(pi); }
@@ -168,8 +203,13 @@ export default function(pi: ExtensionAPI): void {
     lastActivity = now;
     try { await post("/event", { type: "activity" }); } catch { /* shutdown owns bridge cleanup */ }
   });
+  pi.on("session_info_changed", async () => {
+    if (runtimeCtx?.sessionManager?.getHeader?.()?.id !== sessionId || typeof pi.getSessionName !== "function") return;
+    try { await post("/event", { type: "session_title", sessionId, titleEpoch, titleRevision: ++titleRevision, sessionName: pi.getSessionName() ?? "" }); }
+    catch { /* title observation must not disrupt the native session */ }
+  });
   // Native retries/continuations emit more starts before the one logical agent_settled.
-  pi.on("agent_start", async () => { toolSteps = 0; forcedFailure = ""; turnGeneration++; activePromptId = pendingPromptId ?? activePromptId; pendingPromptId = undefined; await post("/event", { type: "agent_start", generation: turnGeneration, ...(activePromptId ? { promptId: activePromptId } : {}) }); });
+  pi.on("agent_start", async () => { toolSteps = 0; forcedFailure = ""; turnGeneration++; activePromptId = pendingPromptId ?? activePromptId; pendingPromptId = undefined; await post("/event", { type: "agent_start", sessionId, ...(typeof pi.getSessionName === "function" ? { sessionName: pi.getSessionName() ?? "", titleEpoch, titleRevision } : {}), generation: turnGeneration, ...(activePromptId ? { promptId: activePromptId } : {}) }); });
   pi.on("model_select", async (_event: any, ctx: any) => { if (ctx.model?.provider && ctx.model.provider !== "agent-hub-local") ctx.shutdown?.(); });
   pi.on("before_agent_start", async (event: any, ctx: any) => {
     if (ctx.model?.provider && ctx.model.provider !== "agent-hub-local") { ctx.abort?.(); return { systemPrompt: event.systemPrompt }; }