@staix/agent-hub 0.12.21 → 0.12.22

package/src/hub/peers.ts

@@ -18,7 +18,7 @@ export interface PeerAdapter {
   /** Optional: feed envelopes into the turn that is running now. Only called while `state === "busy"`. */
   steer?(envs: Envelope[], deliveryId?: string): Promise<void>;
   start(): Promise<void>;
-  stop(): Promise<void>;
+  stop(reason?: string): Promise<void>;
   /** Set by the bus. The peer said something worth sharing. */
   onMessage?: (body: string, opts?: EnvelopeOpts) => unknown;
   /** Set by the bus. */
@@ -84,5 +84,5 @@ export abstract class BasePeer implements PeerAdapter {
 
   abstract deliver(envs: Envelope[], deliveryId?: string): Promise<void>;
   abstract start(): Promise<void>;
-  abstract stop(): Promise<void>;
+  abstract stop(reason?: string): Promise<void>;
 }

package/src/hub/recovery-store.ts

@@ -74,6 +74,12 @@ export function recoveryCommand(op: { id: string; sourceRoot?: string }, action:
   return `${cli} recovery ${action} ${op.id}${flags ? ` ${flags}` : ""}`;
 }
 
+/** #272: the command above as an argv for `bun`, which a screen runs instead of printing; with no coordinator of its own, this release's. */
+export function recoveryArgv(op: { id: string; sourceRoot?: string }, action: "status" | "resume" | "abort" | "dispose", flags: string[] = []): string[] {
+  const entry = op.sourceRoot && coordinatorCurrent(op.sourceRoot) ? join(op.sourceRoot, "src/cli/main.js") : join(import.meta.dir, "../cli/main.js");
+  return [entry, "recovery", action, op.id, ...flags];
+}
+
 /**
  * Whether a coordinator has the #215 recovery commands (dispose, re-preparation, next actions).
  * ponytail: a text sniff of its upgrade.ts; a rename or re-export reads as an older coordinator (the running release is
@@ -116,6 +122,38 @@ export function recoveryRunner(id: string, home = hubHome()): number | "unknown"
   } catch { return "unknown"; } finally { db?.close(); }
 }
 
+/**
+ * #272: the pid of the runner that holds `id`, only when its claim carries a process signature that still matches.
+ * `recoveryRunner` answers a claim without one (a coordinator of 0.12.20 or older, or a `ps` that failed at claim
+ * time) from its bare pid, which is enough to wait for it and never enough to signal it.
+ */
+export function signedRunner(id: string, home = hubHome()): number | undefined {
+  const path = `${operationPath(id, home)}.runner.db`;
+  if (!existsSync(path)) return undefined;
+  let db: Database | undefined;
+  try {
+    db = new Database(path, { readonly: true });
+    db.run("PRAGMA busy_timeout = 3000");
+    if (!signed(db)) return undefined;
+    const row = db.query("SELECT pid, signature FROM runner WHERE slot = 1").get() as { pid: number; signature: string | null } | null;
+    if (!row?.signature || !Number.isSafeInteger(row.pid) || row.pid < 1) return undefined;
+    return processSignature(row.pid) === row.signature ? row.pid : undefined;
+  } catch { return undefined; } finally { db?.close(); }
+}
+
+/** #272: stop that verified runner and wait until no runner holds the operation. False when one still does, or cannot be verified. */
+export async function stopSignedRunner(id: string, home = hubHome(), waitMs = 5000): Promise<boolean> {
+  if (recoveryRunner(id, home) === undefined) return true;
+  const pid = signedRunner(id, home);
+  if (pid === undefined) return false;
+  try { process.kill(pid, "SIGTERM"); } catch { /* gone meanwhile */ }
+  for (const deadline = Date.now() + waitMs; Date.now() < deadline;) {
+    if (recoveryRunner(id, home) === undefined) return true;
+    await new Promise((resolve) => setTimeout(resolve, 100));
+  }
+  return false;
+}
+
 /** An exclusive runner claim. Never steal a live or uncertain owner on resume. */
 export function claimRunner(id: string, home = hubHome()): () => void {
   const path = `${operationPath(id, home)}.runner.db`;

package/src/hub/tasks.ts

@@ -920,9 +920,20 @@ export class Tasks {
     }
   }
 
-  /** Notifications may read the same unavailable board; they must not undo a saved approval's return. */
-  private releaseNotice(line: string): void {
-    try { this.d.notify(line); } catch { /* best effort; the release timer retries ownerless work */ }
+  /**
+   * The one guard for a publish or notify after a board write (#231, #243): the write took effect, so a failure
+   * never throws back to the caller. A failed publish becomes a console notice naming what was lost; a failed notify
+   * is dropped (a second attempt would fail the same way). A lost publish is not retried here: the delivery
+   * journal's own recovery covers a storage error.
+   */
+  private releaseNotice(line: string, run?: () => unknown): void {
+    if (!run) {
+      try { this.d.notify(line); } catch { /* best effort; the release timer retries ownerless work */ }
+      return;
+    }
+    try { run(); } catch (e) {
+      try { this.d.notify(`${line}: ${e instanceof Error ? e.message : String(e)}`); } catch { /* best effort */ }
+    }
   }
 
   private readonly offered = new Set<number>(); // assignments in this hub run, including offers still in flight
@@ -1125,7 +1136,7 @@ export class Tasks {
     // The tool call returns now; a check can outlast an agent's tool timeout. The result decides what comes next.
     this.checking.set(task.id, task.owner);
     const pending = this.d.board.update(task.id, by, "done (checking)", { refs: cleanRefs(refs) }, summary, { withheld: withheld || undefined });
-    this.d.notify(`task ${this.publicTitle(pending)} done by ${by}; its check is queued or running: ${command}`);
+    this.releaseNotice(`task ${this.publicTitle(pending)} done by ${by}; its check is queued or running: ${command}`);
     const seen = { events: pending.history.length, owner: pending.owner };
     this.pendingChecks++;
     this.checkQueue = this.checkQueue
@@ -1255,11 +1266,11 @@ export class Tasks {
     this.tellCompleted(next, summary, withheld);
     if (!reviewer) {
       if (next.owner) this.d.board.recordOutcome(next.owner, next.class, true); // approved without a review is a success too
-      this.d.notify(`task ${this.publicTitle(next)} done by ${by}, no reviewer: approved`);
+      this.releaseNotice(`task ${this.publicTitle(next)} done by ${by}, no reviewer: approved`);
       await this.releaseDependents(next);
     }
-    else if (reviewer === USER) this.d.notify(`task ${this.publicTitle(next)} done by ${by}: review it with ahub task show ${next.id}, then ahub review ${next.id} approved|changes_requested [note]`);
-    else this.sendReview(next, reviewer);
+    else if (reviewer === USER) this.releaseNotice(`task ${this.publicTitle(next)} done by ${by}: review it with ahub task show ${next.id}, then ahub review ${next.id} approved|changes_requested [note]`);
+    else this.releaseNotice(`task ${this.publicTitle(next)}: could not send the review request to ${reviewer}`, () => this.sendReview(next, reviewer));
     return next;
   }
 
@@ -1279,7 +1290,8 @@ export class Tasks {
         cohort.held.add(task.id);
         continue;
       }
-      this.whileOpen(hit.task.owner!, hit.task.id, this.completedNotice(task, hit, summary, withheld));
+      this.releaseNotice(`task ${this.publicTitle(task)}: could not publish the completed-change notice to ${hit.task.owner}`, () =>
+        this.whileOpen(hit.task.owner!, hit.task.id, this.completedNotice(task, hit, summary, withheld)));
     }
   }
 
@@ -1357,7 +1369,8 @@ export class Tasks {
         }
       }
       this.note(next, by, "decision", `Task #${next.id} approved by ${by}: ${next.title}\n${note ?? ""}`, withheld);
-      this.tell(next, `Task #${next.id} approved by ${by}.${note ? ` ${this.screen(next, note, "review note", next.owner, withheld)}` : ""}`, pii);
+      this.releaseNotice(`task ${this.publicTitle(next)}: could not tell ${next.owner ?? "its owner"} it was approved`, () =>
+        this.tell(next, `Task #${next.id} approved by ${by}.${note ? ` ${this.screen(next, note, "review note", next.owner, withheld)}` : ""}`, pii));
       await this.releaseDependents(next);
       return next;
     }
@@ -1370,11 +1383,13 @@ export class Tasks {
       const moved = await this.escalate(HUB, rejected.id, `${rejected.rejections} consecutive changes_requested`, "rejections");
       if (moved.owner !== rejected.owner) return moved;
       // Nobody to escalate to: the owner still has to hear the verdict and the note.
-      this.tell(moved, `Task #${moved.id}: ${by} requests changes again.${note ? ` ${this.screen(moved, note, "review note", moved.owner, withheld)}` : ""} Nobody else can take it; fix it and call hub_task_done again.`, pii);
+      this.releaseNotice(`task ${this.publicTitle(moved)}: could not tell ${moved.owner ?? "its owner"} changes were requested again`, () =>
+        this.tell(moved, `Task #${moved.id}: ${by} requests changes again.${note ? ` ${this.screen(moved, note, "review note", moved.owner, withheld)}` : ""} Nobody else can take it; fix it and call hub_task_done again.`, pii));
       return moved;
     }
     const reopened = this.d.board.update(rejected.id, HUB, "reopened", { state: "in_progress" });
-    this.tell(reopened, `Task #${reopened.id}: ${by} requests changes.${note ? ` ${this.screen(reopened, note, "review note", reopened.owner, withheld)}` : ""} Fix it and call hub_task_done again.`, pii);
+    this.releaseNotice(`task ${this.publicTitle(reopened)}: could not tell ${reopened.owner ?? "its owner"} changes were requested`, () =>
+      this.tell(reopened, `Task #${reopened.id}: ${by} requests changes.${note ? ` ${this.screen(reopened, note, "review note", reopened.owner, withheld)}` : ""} Fix it and call hub_task_done again.`, pii));
     return reopened;
   }
 
@@ -1391,10 +1406,12 @@ export class Tasks {
     if (from && task.reviewer && task.reviewer !== USER && this.requestedChanges(task).has(task.reviewer)) this.d.board.recordReview({ implementer: from, reviewer: task.reviewer, class: task.class, kind: "escalated", task: task.id });
     const next = await this.assignOwner(task, by, { candidates: list, event: "escalated", reason, note: `${why}; from ${from ?? "none"}`, context: why });
     if (next.owner && next.owner !== from) {
-      this.d.notify(`task ${this.publicTitle(next)} escalated from ${from} to ${next.owner} (${why})`);
+      // The move is on the board (#243): review() reaches here after its changes_requested write.
+      this.releaseNotice(`task ${this.publicTitle(next)} escalated from ${from} to ${next.owner} (${why})`);
       this.note(next, by, "decision", `Task #${next.id} escalated from ${from} to ${next.owner}: ${why}`);
-      if (from) this.tell({ ...next, owner: from }, `Task #${next.id} moved to ${next.owner} (${why}). Stop working on it.`, this.isPii(next));
-    } else this.d.notify(`task ${this.publicTitle(task)}: escalation found nobody in [${list.join(", ")}]; it stays with ${from ?? "nobody"}`);
+      if (from) this.releaseNotice(`task ${this.publicTitle(next)}: could not tell ${from} it moved to ${next.owner}`, () =>
+        this.tell({ ...next, owner: from }, `Task #${next.id} moved to ${next.owner} (${why}). Stop working on it.`, this.isPii(next)));
+    } else this.releaseNotice(`task ${this.publicTitle(task)}: escalation found nobody in [${list.join(", ")}]; it stays with ${from ?? "nobody"}`);
     return this.d.board.get(next.id)!;
   }
 
@@ -1475,7 +1492,7 @@ export class Tasks {
     if (this.isPii(task) || !this.d.memory) return;
     // claude-mem's observer is a cloud model: model-written text that matches a PII pattern, or that the PII screen did
     // not clear (#198), is not sent (#69).
-    if (withheld || !this.nameable(text)) return this.d.notify(`task #${task.id}: a ${kind} note was not saved to shared memory (${this.whyWithheld(text)})`);
+    if (withheld || !this.nameable(text)) return this.releaseNotice(`task #${task.id}: a ${kind} note was not saved to shared memory (${this.whyWithheld(text)})`);
     void this.d.memory.save({ text, title: `agent-hub task #${task.id}: ${task.title}`.slice(0, 120), project: this.d.project, metadata: { peer: by, task: task.id, kind } });
   }
 

package/src/local/deny.ts

@@ -10,7 +10,6 @@ export const DENY_SEGMENTS = [".maru/secrets", ".agenthub/state", ".agenthub/arc
 export const DENY_NAMES = ["^\\.env", "\\.pem$", "\\.key$", "^id_rsa", "^id_ed25519", "^credentials(\\.|$)", "^auth\\.json$", "^\\.netrc$", "^\\.npmrc$", "^\\.pypirc$"];
 
 const hasSegment = (rel: string, seg: string) => `/${rel}/`.includes(`/${seg}/`);
-export { hasSegment };
 
 /** True when a path names something the worker must never read, write or report. `extra`: substrings from `local.deny`. */
 export function isDenied(path: string, extra: string[] = []): boolean {
@@ -27,6 +26,54 @@ const sbplEscape = (s: string) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
  */
 export const sbplString = (s: string) => `"${s.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
 
+/**
+ * The 16 code points HFS+ ignores in file names: U+200C-200F, U+202A-202E, U+206A-206F, U+FEFF (a probe found
+ * case-insensitive APFS ignores none). `mkdir .g<U+200D>it` on HFS+ makes what everything afterwards opens as
+ * `.git` (#270). One source for the seatbelt profile's folded patterns; the file tools' `foldSegment` removes
+ * every default-ignorable, a superset of these.
+ */
+export const HFS_IGNORABLE_POINTS = ["\u200C", "\u200D", "\u200E", "\u200F", "\u202A", "\u202B", "\u202C", "\u202D", "\u202E", "\u206A", "\u206B", "\u206C", "\u206D", "\u206E", "\u206F", "\uFEFF"];
+
+/**
+ * One HFS+-ignorable code point as a seatbelt regex atom. A group alternation, not a character class: the
+ * seatbelt regex engine is byte-oriented, so a quantifier after a multi-byte class member binds to its last
+ * byte and a class never matches the plain name (verified with the real sandbox-exec, #270).
+ */
+const HFS_IGNORABLE = `(${HFS_IGNORABLE_POINTS.join("|")})`;
+
+/** A regex source matching `name` with any number of HFS+-ignorable code points interleaved, at the ends included. */
+const hfsFoldedName = (name: string) => `${HFS_IGNORABLE}*${[...name].map((c) => sbplEscape(c)).join(`${HFS_IGNORABLE}*`)}${HFS_IGNORABLE}*`;
+
+/**
+ * Seatbelt rules for the hub's and git's own names (#270). `.agenthub` is refused anywhere under the project root.
+ * `.git` is refused at any depth, the name itself included, so a planted repository cannot arrive by creation,
+ * rename, symlink or gitfile, and `config` and `hooks` directly under it are folded too; the cost is that
+ * `git init`, `git clone` and `git worktree add` no longer run inside the sandbox. `commondir` is refused at any
+ * depth below a `.git` and below each external git dir: that is where git keeps it for linked worktrees and
+ * submodules. An external git dir's `config`/`hooks` rules cover only its own children (plus the hooks
+ * directory's contents): at any depth they would deny refs named `config` or `hooks` in a worktree or submodule
+ * project (`git branch fix/config` fails on `.git/logs/refs/heads/fix/config`). Every pattern keeps its `^`
+ * anchor (an unanchored starred alternation does not match in this engine) and no folded literal contains the
+ * root: an SBPL string literal dies at 1024 bytes ("Error reading string"), which a long project path would trip.
+ */
+export function hubWriteRegexes(root: string, gitDirs: string[] = []): string[] {
+  const git = hfsFoldedName(".git");
+  const re = (s: string) => `(regex ${sbplString(s)})`;
+  const external = gitDirs.flatMap((d) => [
+    `(require-all ${re(`^${sbplEscape(d)}/[^/]+$`)} ${re(`^.*/(${hfsFoldedName("config")}|${hfsFoldedName("hooks")})$`)})`,
+    `(subpath ${sbplString(`${d}/hooks`)})`,
+    `(require-all (subpath ${sbplString(d)}) ${re(`^.*/${hfsFoldedName("commondir")}$`)})`,
+  ]);
+  return [
+    `(require-all (subpath ${sbplString(root)}) ${re(`^.*/${hfsFoldedName(".agenthub")}(/|$)`)})`,
+    re(`^.*/${git}$`),
+    re(`^.*/${git}/${hfsFoldedName("config")}$`),
+    re(`^.*/${git}/${hfsFoldedName("hooks")}(/|$)`),
+    `(require-all ${re(`^.*/${git}/.*$`)} ${re(`^.*/${hfsFoldedName("commondir")}$`)})`,
+    ...external,
+  ];
+}
+
 /**
  * Seatbelt regex filters equivalent to isDenied. Seatbelt sees absolute paths, so the `local.deny` substrings are
  * anchored under the project root: a bare "private/" would otherwise match /private/var/... and deny the whole temp tree.

package/src/local/sandbox.ts

@@ -3,7 +3,7 @@ import { existsSync, mkdtempSync, rmSync } from "node:fs";
 import { homedir, tmpdir } from "node:os";
 import { join, resolve } from "node:path";
 import { realPath } from "../hub/project.ts";
-import { denyRegexes, sbplString } from "./deny.ts";
+import { denyRegexes, hubWriteRegexes, sbplString } from "./deny.ts";
 
 const SANDBOX_EXEC = "/usr/bin/sandbox-exec";
 export const OUTPUT_CAP = 20_000;
@@ -102,8 +102,11 @@ export function profile(cwd: string, network: SandboxNetwork, readAllow: string[
     ...start,
     "(deny file-write*)",
     `(allow file-write* (subpath ${q(root)}) (regex #"^/dev/") ${gitDirs.map((d) => `(subpath ${q(d)})`).join(" ")})`,
-    // Inside cwd: nothing that runs later outside the sandbox, nothing that reconfigures the hub.
-    `(deny file-write* (subpath ${q(join(root, ".agenthub"))}) ${[join(root, ".git"), ...gitDirs].map((d) => `(subpath ${q(join(d, "hooks"))}) (literal ${q(join(d, "config"))})`).join(" ")})`,
+    // Inside cwd: nothing that runs later outside the sandbox, nothing that reconfigures the hub. The .git and
+    // .agenthub patterns tolerate the code points HFS+ ignores in every segment, the .git name itself is refused
+    // at any depth (creation, rename, symlink, gitfile), and the external git dirs get folded hooks/config rules
+    // (#270). The cost: git init, clone and worktree add no longer run inside the sandbox.
+    `(deny file-write* ${hubWriteRegexes(root, gitDirs).join(" ")})`,
     `(deny file-read* file-write* ${creds.map((c) => `(subpath ${q(join(home, c))})`).join(" ")})`,
     `(deny file-read* file-write* ${denyRegexes(root, deny).join(" ")})`,
     // Python's own CA bundle (certifi, which pip vendors too): pip, requests and httpx read it instead of the system's (#64).

package/src/local/tools.ts

@@ -7,6 +7,15 @@ import { OUTPUT_CAP, sandboxedExec } from "./sandbox.ts";
 
 export { isDenied };
 
+export type ToolApproval = boolean | "expired" | "aborted";
+export interface ApprovalProvenance { source: "person" | "automatic" | "expired" | "aborted"; answerEpoch: number; eligibleExpiry?: boolean; }
+export type ApprovalObserver = (provenance: ApprovalProvenance) => void;
+export const APPROVAL_EXPIRED_TEXT = "error: approval expired: no person answered; do not retry this call; hand the task off or stop";
+export class ApprovalWaitStop extends Error {}
+const approvalError = (picked: ToolApproval, denied: string): string | undefined => picked === true ? undefined
+  : picked === "expired" ? APPROVAL_EXPIRED_TEXT
+  : picked === "aborted" ? "error: approval withdrawn because the turn ended; no operation was executed" : denied;
+
 export interface ToolContext {
   cwd: string;
   /** Extra denylist entries from config: substrings of the project-relative path. */
@@ -17,8 +26,10 @@ export interface ToolContext {
   sandboxEnv?: Record<string, string>;
   /** Turn cancellation signal, including the execution-budget wall cap. */
   signal?: AbortSignal;
-  /** Ask the console. Resolves false on deny or timeout. */
-  permit: (title: string, tool?: string, signal?: AbortSignal, path?: string) => Promise<boolean>;
+  /** Only true permits an effect; expiry and abort remain distinct from a person's denial. */
+  permit: (title: string, tool?: string, signal?: AbortSignal, canonicalTarget?: string, observe?: ApprovalObserver) => Promise<ToolApproval>;
+  /** Trusted process status, independent of what its stdout says. */
+  onProcessExit?: (code: number | null) => void;
   /** Publish a message to other peers mid-turn. Returns a one-line receipt. */
   send: (text: string, to?: string[]) => string;
 }
@@ -131,7 +142,8 @@ export async function runTool(name: string, rawArgs: string, ctx: ToolContext):
         let file = guardPath(ctx, String(a.path), "write");
         const approvedTarget = file;
         const content = String(a.content ?? "");
-        if (!(await ctx.permit(`write ${a.path} (${content.length} chars):\n${preview(content)}`, "write", ctx.signal, file))) return "error: the user did not approve this write";
+        const refused = approvalError(await ctx.permit(`write ${a.path} (${content.length} chars):\n${preview(content)}`, "write", ctx.signal, file), "error: the user did not approve this write");
+        if (refused) return refused;
         if (ctx.signal?.aborted) return "error: turn cancelled before write";
         file = guardPath(ctx, String(a.path), "write");
         if (file !== approvedTarget) return "error: path target changed during approval; inspect before retrying";
@@ -145,7 +157,8 @@ export async function runTool(name: string, rawArgs: string, ctx: ToolContext):
         let text = readFileSync(file, "utf8");
         let count = text.split(String(a.old)).length - 1;
         if (!a.old || count !== 1) return `error: \`old\` must match exactly once, it matched ${count} times`;
-        if (!(await ctx.permit(`edit ${a.path}:\n- ${preview(String(a.old), 600)}\n+ ${preview(String(a.new ?? ""), 600)}`, "edit", ctx.signal, file))) return "error: the user did not approve this edit";
+        const refused = approvalError(await ctx.permit(`edit ${a.path}:\n- ${preview(String(a.old), 600)}\n+ ${preview(String(a.new ?? ""), 600)}`, "edit", ctx.signal, file), "error: the user did not approve this edit");
+        if (refused) return refused;
         if (ctx.signal?.aborted) return "error: turn cancelled before edit";
         // Approval can outlive another peer's edit or a path change. Apply only the approved fragment to current bytes.
         file = guardPath(ctx, String(a.path), "write");
@@ -161,8 +174,10 @@ export async function runTool(name: string, rawArgs: string, ctx: ToolContext):
         if (!command.trim()) return "error: empty command";
         // The approver sees the whole command, not a prefix: what is hidden cannot be approved.
         if (command.length > 4000) return "error: command longer than 4000 characters; put it in a script file with write, then run that";
-        if (!(await ctx.permit(`bash: ${command}`, "bash", ctx.signal))) return "error: the user did not approve this command";
+        const refused = approvalError(await ctx.permit(`bash: ${command}`, "bash", ctx.signal), "error: the user did not approve this command");
+        if (refused) return refused;
         const res = await sandboxedExec(["/bin/bash", "-c", command], { cwd: ctx.cwd, profile: ctx.sandboxProfile, timeoutMs: (Number(a.timeout_s) || 120) * 1000, ...(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})`;
       }
       case "git": {
@@ -171,9 +186,13 @@ export async function runTool(name: string, rawArgs: string, ctx: ToolContext):
         if (!GIT_READ.has(sub) && !GIT_WRITE.has(sub)) return `error: git ${sub} is not available to the local worker`;
         const problem = gitArgsProblem(args, ctx.deny);
         if (problem) return `error: git ${sub}: ${problem}`;
-        if (GIT_WRITE.has(sub) && !(await ctx.permit(`git ${args.join(" ")}`, "git", ctx.signal))) return "error: the user did not approve this git command";
+        if (GIT_WRITE.has(sub)) {
+          const refused = approvalError(await ctx.permit(`git ${args.join(" ")}`, "git", ctx.signal), "error: the user did not approve this git command");
+          if (refused) return refused;
+        }
         // 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, ...(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})`;
       }
       case "hub_send":

package/src/pi/extension.ts

@@ -19,6 +19,7 @@ let pollStopped = false;
 let toolSteps = 0;
 let lastActivity = 0;
 let usageSeq = 0;
+let shellSeq = 0;
 let forcedFailure = "";
 let turnGeneration = 0;
 let sessionId = "";
@@ -33,9 +34,13 @@ async function post(path: string, body: unknown): Promise<any> {
   if (!response.ok) throw new Error(`Pi bridge HTTP ${response.status}`);
   return response.json();
 }
-async function admitBudget(unit: BudgetUnit, idleUserBash = false): Promise<{ allowed: boolean; reservation?: string }> {
+async function admitBudget(unit: BudgetUnit, idleUserBash = false, generation = turnGeneration, callSessionId = sessionId): Promise<{ allowed: boolean; reservation?: string; reason?: string }> {
+  const current = () => generation === turnGeneration && callSessionId === sessionId;
+  const stale = () => ({ allowed: false, reason: "Pi tool lineage ended during admission; do not retry the old call" });
+  if (!current()) return stale();
   try {
-    const result = await post("/budget", { unit, generation: turnGeneration, ...(idleUserBash ? { idleUserBash: true } : {}) });
+    const result = await post("/budget", { unit, generation, ...(idleUserBash ? { idleUserBash: true } : {}) });
+    if (!current()) return stale();
     const decisions = Array.isArray(result?.decisions) ? result.decisions : [];
     const denied = decisions.find((item: any) => item?.allowed === false);
     if (!denied) return { allowed: true, ...(idleUserBash && typeof result?.reservation === "string" ? { reservation: result.reservation } : {}) };
@@ -43,12 +48,14 @@ async function admitBudget(unit: BudgetUnit, idleUserBash = false): Promise<{ al
     if (idleUserBash) return { allowed: false };
     forcedFailure = reason;
   } catch (error) {
+    if (!current()) return stale();
     if (idleUserBash) return { allowed: false };
     forcedFailure = `execution budget admission unavailable: ${(error as Error).message}`;
   }
-  try { await post("/event", { type: "agent_end", generation: turnGeneration, failed: true, error: forcedFailure }); } catch { /* abort remains authoritative when the bridge is unavailable */ }
-  runtimeCtx?.abort?.();
-  return { allowed: false };
+  const reason = forcedFailure;
+  try { await post("/event", { type: "agent_end", generation, failed: true, error: reason }); } catch { /* abort remains authoritative when the bridge is unavailable */ }
+  if (current()) runtimeCtx?.abort?.();
+  return { allowed: false, reason };
 }
 async function poll(pi: ExtensionAPI): Promise<void> {
   while (!pollStopped) {
@@ -77,10 +84,13 @@ async function poll(pi: ExtensionAPI): Promise<void> {
           shutdown?.();
         } else if (command.type === "abort_budget") {
           if (Number.isSafeInteger(command.generation) && command.generation === turnGeneration) {
-            const reason = "execution budget exhausted: elapsed_ms wall cap reached";
+            if (typeof runtimeCtx?.abort !== "function") throw new Error("Pi runtime cannot abort the current turn");
+            const generation = turnGeneration, callSessionId = sessionId;
+            const reason = command.cause === "approval" && typeof command.reason === "string" && command.reason
+              ? command.reason : "execution budget exhausted: elapsed_ms wall cap reached";
             forcedFailure = reason;
-            await post("/event", { type: "agent_end", generation: turnGeneration, failed: true, error: reason });
-            runtimeCtx?.abort?.();
+            await post("/event", { type: "agent_end", generation, failed: true, error: reason });
+            if (generation === turnGeneration && callSessionId === sessionId) runtimeCtx?.abort?.();
           }
         }
         await post("/ack", { id: command.id, ok: true });
@@ -107,7 +117,7 @@ export default function(pi: ExtensionAPI): void {
     const state = ctx.sessionManager.getHeader();
     sessionId = String(state?.id ?? "");
     try {
-      const claimed = await post("/event", { type: "session_start", ownerToken, pid: process.pid, signature: processSignature(process.pid), sessionId: state?.id, sessionFile: ctx.sessionManager.getSessionFile() });
+      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" });
       if (claimed?.ok === false) { ctx.shutdown?.(); return; }
     } catch (error) { ctx.shutdown?.(); throw error; }
     if (!pollStarted) { pollStarted = true; void poll(pi); }
@@ -140,8 +150,10 @@ export default function(pi: ExtensionAPI): void {
   });
   pi.on("before_provider_request", async (_event: any, ctx: any) => {
     if (ctx.model?.provider && ctx.model.provider !== "agent-hub-local") { ctx.abort?.(); return undefined; }
-    try { if (!(await admitBudget("model_calls")).allowed) ctx.abort?.(); }
-    catch (error) { forcedFailure = `execution budget admission failed: ${(error as Error).message}`; ctx.abort?.(); }
+    const generation = turnGeneration, callSessionId = sessionId;
+    const current = () => generation === turnGeneration && callSessionId === sessionId;
+    try { if (!(await admitBudget("model_calls", false, generation, callSessionId)).allowed && current()) ctx.abort?.(); }
+    catch (error) { if (current()) { forcedFailure = `execution budget admission failed: ${(error as Error).message}`; ctx.abort?.(); } }
     return undefined;
   });
   pi.on("agent_settled", async (_event: any, ctx: any) => {
@@ -151,10 +163,11 @@ export default function(pi: ExtensionAPI): void {
     await post("/event", { type: "agent_settled", generation: turnGeneration, ...(text ? { text } : {}) });
   });
   pi.on("user_bash", async (event: any) => {
-    const admission = await admitBudget("tool_calls", true);
+    const generation = turnGeneration, callSessionId = sessionId;
+    const admission = await admitBudget("tool_calls", true, generation, callSessionId);
     if (!admission.allowed || !admission.reservation) return { cancel: true };
-    const result = await post("/tool", { name: "bash", args: { command: event.command, cwd: event.cwd }, toolCallId: `pi-shell-${Date.now()}`, purpose: "idle_user_bash", generation: turnGeneration, reservation: admission.reservation });
-    return { result: { output: String(result.text ?? result), exitCode: 0, cancelled: false, truncated: false } };
+    const result = await post("/tool", { name: "bash", args: { command: event.command, cwd: event.cwd }, toolCallId: `pi-shell-${Date.now()}-${++shellSeq}`, purpose: "idle_user_bash", generation, sessionId: callSessionId, reservation: admission.reservation });
+    return { result: { output: String(result.text ?? result), exitCode: typeof result.exitCode === "number" ? result.exitCode : undefined, cancelled: result.exitCode === null, truncated: false } };
   });
   // Managed sessions may only be handed over by PiPeer after it has fenced the
   // owner and verified the replacement identity. User /fork and /resume would
@@ -164,8 +177,11 @@ export default function(pi: ExtensionAPI): void {
   pi.on("session_shutdown", async () => { pollStopped = true; await post("/event", { type: "session_shutdown" }); });
   for (const raw of (() => { try { return JSON.parse(process.env.AGENTHUB_PI_TOOLS ?? "[]") as any[]; } catch { return []; } })()) {
     if (!raw || typeof raw.name !== "string" || !raw.parameters) continue;
-    pi.registerTool({ name: raw.name, label: raw.name, description: raw.description ?? raw.name, parameters: raw.parameters, async execute(toolCallId: string, params: unknown) {
-      if (!(await admitBudget("tool_calls")).allowed) return { content: [{ type: "text", text: `error: ${forcedFailure}` }], details: {}, isError: true };
+    pi.registerTool({ name: raw.name, label: raw.name, description: raw.description ?? raw.name, parameters: raw.parameters, async execute(toolCallId: string, params: unknown, signal?: AbortSignal) {
+      const generation = turnGeneration, callSessionId = sessionId;
+      if (signal?.aborted) return { content: [{ type: "text", text: "error: tool call cancelled before execution" }], details: {}, isError: true };
+      const admission = await admitBudget("tool_calls", false, generation, callSessionId);
+      if (!admission.allowed) return { content: [{ type: "text", text: `error: ${admission.reason ?? forcedFailure}` }], details: {}, isError: true };
       if (toolSteps++ >= maxSteps) {
         const reason = `Pi tool step limit ${maxSteps} reached`;
         forcedFailure = reason;
@@ -173,12 +189,19 @@ export default function(pi: ExtensionAPI): void {
         // event, so the adapter binds it while the turn still owns it. The counter already counts the
         // rejected pre-effect invocation (toolSteps++ above); its side effect never executes. The
         // reason text stays the failure record; the signal adds the validated counts.
-        try { await post("/event", { type: "ceiling", kind: PI_CEILING_KIND, unit: PI_CEILING_UNIT, count: toolSteps, limit: maxSteps, sessionId, generation: turnGeneration }); } catch { /* the agent_end failure below remains authoritative */ }
-        await post("/event", { type: "agent_end", generation: turnGeneration, failed: true, error: reason });
-        runtimeCtx?.abort?.();
+        try { await post("/event", { type: "ceiling", kind: PI_CEILING_KIND, unit: PI_CEILING_UNIT, count: toolSteps, limit: maxSteps, sessionId: callSessionId, generation }); } catch { /* the agent_end failure below remains authoritative */ }
+        await post("/event", { type: "agent_end", generation, failed: true, error: reason });
+        if (generation === turnGeneration && callSessionId === sessionId) runtimeCtx?.abort?.();
         return { content: [{ type: "text", text: `error: ${reason}` }], details: {}, isError: true };
       }
-      const result = await post("/tool", { name: raw.name, args: params, toolCallId });
+      const aborted = () => { void post("/event", { type: "tool_abort", sessionId: callSessionId, generation, toolCallId }).catch(() => undefined); };
+      if (signal?.aborted) return { content: [{ type: "text", text: "error: tool call cancelled before execution" }], details: {}, isError: true };
+      signal?.addEventListener("abort", aborted, { once: true });
+      let result: any;
+      try {
+        result = await post("/tool", { name: raw.name, args: params, toolCallId, sessionId: callSessionId, generation });
+        if (signal?.aborted) aborted();
+      } finally { signal?.removeEventListener("abort", aborted); }
       const text = String(result.text ?? result);
       // Pi 1.0.1 reads isError === true alone (#181). The bridge computes `failed` with the
       // managed-tool failure contract (toolResultFailed); the extension never re-parses the text.

package/src/pi/tool-receipts.ts

@@ -3,6 +3,22 @@ import { Database } from "bun:sqlite";
 import { createHash } from "node:crypto";
 import { PreEffectToolRefusal } from "../hub/tool-refusal.ts";
 
+export const PI_TOOL_RESULT_CAP = 100_000;
+/** Bound encoded text before wrapping it so escaping never cuts off trusted exit metadata. */
+export function packPiShellResult(text: string, exitCode: number | null): string {
+  const pack = (value: string) => JSON.stringify({ kind: "user-bash-result", text: value, exitCode });
+  const full = pack(text);
+  if (full.length <= PI_TOOL_RESULT_CAP) return full;
+  const suffix = "\n[output truncated]";
+  let low = 0, high = text.length;
+  while (low < high) {
+    const middle = Math.ceil((low + high) / 2);
+    if (pack(text.slice(0, middle) + suffix).length <= PI_TOOL_RESULT_CAP) low = middle;
+    else high = middle - 1;
+  }
+  return pack(text.slice(0, low) + suffix);
+}
+
 /** Private, session-scoped dedupe. An interrupted effect is never automatically repeated. */
 export class PiToolReceipts {
   private readonly db: Database;
@@ -33,7 +49,7 @@ export class PiToolReceipts {
     const claim = this.db.query("INSERT OR IGNORE INTO pi_tool_receipts(session,call_id,fingerprint,state) VALUES(?,?,?,'pending')").run(session, callId, fingerprint);
     if (!claim.changes) return this.execute(session, callId, name, args, run);
     const settle = (result: string): string => {
-      const text = result.slice(0, 100_000);
+      const text = result.slice(0, PI_TOOL_RESULT_CAP);
       this.db.query("UPDATE pi_tool_receipts SET state='done',result=? WHERE session=? AND call_id=?").run(text, session, callId);
       return text;
     };

package/src/ui/index.html

@@ -178,6 +178,20 @@ function renderTaskStage(stage) {
   for (const [index, label] of ['Proposed', 'In progress', 'In review', 'Approved'].entries()) row.append(el('span', `${index < stage.stage ? '[x]' : '[ ]'} ${label}${index < 3 ? ' > ' : ''}`, index < stage.stage ? 'reached' : ''));
   row.append(el('span', ` / Stage ${stage.stage}/4: ${stage.label}`)); return row;
 }
+function renderApprovals(permissions) {
+  const terminalWaiting = permissions.filter((permission) => permission.peer === 'pi' || permission.peer === 'local').length;
+  $('permission-count').textContent = permissions.length + ' waiting' + (terminalWaiting ? ', ' + terminalWaiting + ' Pi/local: answer in the console or ahub tail / ahub permit' : '');
+  update('permissions', permissions, (target) => {
+    if (!permissions.length) return empty(target, 'No approvals waiting.');
+    for (const permission of permissions) {
+      const row = el('div', undefined, 'row'); row.append(el('div', permission.peer, 'label'), el('p', permission.title, 'body'));
+      if (permission.terminalOnly) row.append(el('p', 'Review in the console or ahub tail; answer with ahub permit. You can deny here.', 'meta'));
+      const actions = el('div', undefined, 'actions');
+      for (const option of permission.options) { const deny = option.kind === 'reject_once' || option.kind === 'reject_always'; if (permission.terminalOnly && !deny) continue; actions.append(button(option.name, {action:'permit', id:permission.id, option:option.optionId}, deny ? 'danger' : 'primary')); }
+      row.append(actions); target.append(row);
+    }
+  });
+}
 function render(snapshot) {
   const peers = snapshot.status.peers || {}, ids = Object.keys(peers);
   $('peer-count').textContent = ids.length + ' peers';
@@ -227,17 +241,7 @@ function render(snapshot) {
       target.append(row);
     }
   });
-  $('permission-count').textContent = String(snapshot.permissions.length);
-  update('permissions', snapshot.permissions, (target) => {
-    if (!snapshot.permissions.length) return empty(target, 'No approvals waiting.');
-    for (const permission of snapshot.permissions) {
-      const row = el('div', undefined, 'row'); row.append(el('div', permission.peer, 'label'), el('p', permission.title, 'body'));
-      if (permission.terminalOnly) row.append(el('p', 'Review details and allow in the terminal with ahub tail. You can deny here.', 'meta'));
-      const actions = el('div', undefined, 'actions');
-      for (const option of permission.options) { const deny = option.kind === 'reject_once' || option.kind === 'reject_always'; if (permission.terminalOnly && !deny) continue; actions.append(button(option.name, {action:'permit', id:permission.id, option:option.optionId}, deny ? 'danger' : 'primary')); }
-      row.append(actions); target.append(row);
-    }
-  });
+  renderApprovals(snapshot.permissions);
   update('budget', snapshot.budget, (target) => {
     if (!Object.keys(snapshot.budget).length) return empty(target, 'No usage readings yet. Usage appears when a peer reports it.');
     for (const [peer, budget] of Object.entries(snapshot.budget)) {