@staix/agent-hub 0.12.22 → 0.12.23

package/src/hub/tasks.ts

@@ -92,6 +92,24 @@ const OPEN: Task["state"][] = ["proposed", "in_progress", "changes_requested"];
 /** Board events that leave a task where its completion check found it; any other event means it moved on meanwhile. */
 const QUIET_EVENTS = new Set(["answer", "reviewer changed", "idle sweep"]);
 
+/**
+ * Thrown when an assignment's board write is saved but a publish or notify after it failed (#297): the move is
+ * fact, the delivery is unconfirmed. Callers decide by this type, never by comparing owners or reading history.
+ * It stays a plain Error subclass, so the preEffect rule and the #231 ready-offer contract are unchanged.
+ * `task` and `cause` are non-enumerable: a PII task's title and detail must not reach a JSON.stringify of the error.
+ */
+export class AssignmentUndeliveredError extends Error {
+  /** The task as the board has it after the write. */
+  declare readonly task: Task;
+  declare readonly cause: unknown;
+  constructor(task: Task, cause: unknown) {
+    super(`task #${task.id}: the assignment to ${task.owner} is saved, but its delivery is not confirmed: ${cause instanceof Error ? cause.message : String(cause)}`);
+    this.name = "AssignmentUndeliveredError";
+    Object.defineProperty(this, "task", { value: task, enumerable: false });
+    Object.defineProperty(this, "cause", { value: cause, enumerable: false });
+  }
+}
+
 /** A project path as one spelling (#67): no leading `./`, no repeated or trailing `/`; the root is `.`. */
 export const normPath = (p: string) => p.replace(/^(\.\/)+/, "").replace(/\/{2,}/g, "/").replace(/\/+$/, "") || ".";
 
@@ -242,7 +260,13 @@ export class Tasks {
           this.passedOver(task, a);
           this.d.notify(`${message} ${reviewer ? "Reviewer" : "Owner"} reassignment suggestion: ${candidate ?? "no eligible peer"}.`);
           if (!reviewer && candidate && this.sweepConfig.auto_reassign && this.sweepAvailable(candidate)) {
-            await this.assignOwner(this.d.board.get(task.id)!, HUB, { candidates: [candidate], exclude: [responsible], event: "reassigned", reason: "idle", note: `idle sweep: ${finding.kind}; from ${responsible}` });
+            try {
+              await this.assignOwner(this.d.board.get(task.id)!, HUB, { candidates: [candidate], exclude: [responsible], event: "reassigned", reason: "idle", note: `idle sweep: ${finding.kind}; from ${responsible}` });
+            } catch (e) {
+              // A saved move whose delivery failed: the console notice was printed where the error was thrown, and
+              // the sweep goes on (#297).
+              if (!(e instanceof AssignmentUndeliveredError)) throw e;
+            }
           }
         }
       }
@@ -569,7 +593,12 @@ export class Tasks {
     this.d.notify(`task ${this.publicTitle(lifted)}: the PII screen cleared it on a second look; it is routed as usual`);
     const still = this.waitsFor(lifted);
     if (still.length) return void this.d.board.update(lifted.id, HUB, "blocked", {}, `waits for ${still.map((id) => `#${id}`).join(", ")}`);
-    await this.assignOwner(lifted, HUB);
+    try {
+      await this.assignOwner(lifted, HUB);
+    } catch (e) {
+      // A saved move whose delivery failed: the console notice was printed where the error was thrown (#297).
+      if (!(e instanceof AssignmentUndeliveredError)) throw e;
+    }
   }
 
   /**
@@ -757,7 +786,12 @@ export class Tasks {
           // The gone owner hears it on its next delivery, if it comes back mid-work.
           if (next.owner && next.owner !== peer) this.d.tell?.(peer, noteLine(HUB, "decision", `task #${task.id} moved to ${next.owner} while you were offline; stop working on it`));
         } catch (e) {
-          this.d.notify(`task ${this.publicTitle(task)}: could not be released from ${peer}: ${(e as Error).message}`);
+          if (e instanceof AssignmentUndeliveredError) {
+            // The move is fact for the board, so it is fact here too: record it, and tell the gone owner to stop
+            // (the console notice was printed where the error was thrown) (#297).
+            moved.push({ id: task.id, title: this.publicTitle(task), to: e.task.owner });
+            if (e.task.owner && e.task.owner !== peer) this.d.tell?.(peer, noteLine(HUB, "decision", `task #${task.id} moved to ${e.task.owner} while you were offline; stop working on it`));
+          } else this.d.notify(`task ${this.publicTitle(task)}: could not be released from ${peer}: ${(e as Error).message}`);
         }
       }
     } finally {
@@ -766,9 +800,8 @@ export class Tasks {
     return moved;
   }
 
-  /** Same code as assignment, without doing it. */
-  explain(target: number | { title: string; detail?: string; class: TaskClass; refs?: TaskRefs }): string[] {
-    const routing = this.d.routing();
+  /** Same code as assignment, without doing it. `routing`: a candidate policy to explain under (the settings preview, #269). */
+  explain(target: number | { title: string; detail?: string; class: TaskClass; refs?: TaskRefs }, routing: Routing = this.d.routing()): string[] {
     if (typeof target === "number") {
       const task = this.d.board.get(target);
       if (!task) throw new Error(`no task #${target}`);
@@ -784,8 +817,8 @@ export class Tasks {
   }
 
   /** Public read path: every generated line is screened, including profile/config-derived trace fields. */
-  publicExplain(target: number | { title: string; detail?: string; class: TaskClass; refs?: TaskRefs }): string[] {
-    return this.explain(target).map(line => this.nameable(line) ? line : "[routing explanation withheld: it matches a PII pattern]");
+  publicExplain(target: number | { title: string; detail?: string; class: TaskClass; refs?: TaskRefs }, routing?: Routing): string[] {
+    return this.explain(target, routing).map(line => this.nameable(line) ? line : "[routing explanation withheld: it matches a PII pattern]");
   }
 
   /**
@@ -801,7 +834,8 @@ export class Tasks {
    */
   private passedOver(task: Task, a: Assignment): string {
     if (!a.unreserved || task.reserved === task.owner || this.excluded(task).includes(task.reserved!)) return "";
-    this.d.notify(`task ${this.publicTitle(task)}: its reserved owner ${task.reserved} is passed over (${a.unreserved}); routing proceeds`);
+    // Before the write, but after the caller's own (a decline's, say): a throwing console fails nothing (#297).
+    this.releaseNotice(`task ${this.publicTitle(task)}: its reserved owner ${task.reserved} is passed over (${a.unreserved}); routing proceeds`);
     return `; reserved owner ${task.reserved} passed over: ${a.unreserved}`;
   }
 
@@ -826,12 +860,12 @@ export class Tasks {
     const a = assign(task, this.states(), this.d.routing(), { exclude: [...(opts.override ? [] : this.excluded(task)), ...(opts.exclude ?? []), ...(opts.event === "escalated" && task.owner ? [task.owner] : [])], ...(opts.candidates ? { candidates: opts.candidates } : {}), waitsFor: waits, ...this.weights(task.class) });
 
     if (waits.length) {
-      this.d.notify(`task ${this.publicTitle(task)} waits for ${waits.map((id) => `#${id}`).join(", ")}; it is offered once they are approved`);
+      this.releaseNotice(`task ${this.publicTitle(task)} waits for ${waits.map((id) => `#${id}`).join(", ")}; it is offered once they are approved`);
       return task;
     }
     const passed = this.passedOver(task, a);
     if (!a.owner) {
-      this.d.notify(`task ${this.publicTitle(task)}: no peer can take it (${a.trace.filter((l) => l.includes("skipped")).length} skipped); assign with: ahub task assign ${task.id} <peer>`);
+      this.releaseNotice(`task ${this.publicTitle(task)}: no peer can take it (${a.trace.filter((l) => l.includes("skipped")).length} skipped); assign with: ahub task assign ${task.id} <peer>`);
       // Only a decline takes the task away from its owner; a failed console assign or escalation leaves it where it was.
       if (opts.clearOnFail && task.owner) {
         this.cohorts.leave(task.id);
@@ -856,19 +890,38 @@ export class Tasks {
     // A claim is its own hand-over: the claimant took the task in the turn it is in, so it is taking it, not busy elsewhere.
     // The cohort record formed just below reads it, and so does `route explain` while that turn lasts.
     if (opts.claim && a.owner === by && this.d.bus.peers.get(by)?.state === "busy") this.sent.set(handOver(next, by), by);
-    const hits = this.overlapHits(next);
-    this.formCohort(next, hits);
-    if (hits.length) {
-      this.announceOverlap(next, hits);
-      this.tellEarlierOwners(next, hits);
+    try {
+      const hits = this.overlapHits(next);
+      this.formCohort(next, hits);
+      if (hits.length) {
+        this.announceOverlap(next, hits);
+        this.tellEarlierOwners(next, hits);
+      }
+      this.announceRouting(next, a);
+      if (!opts.claim || a.owner !== by) await this.sendTask(next, a, opts.context, this.overlaps(next, true, hits), opts.contextWithheld);
+    } catch (e) {
+      // Everything between the write and the end of the delivery is in here: the move is fact, and a failure is a
+      // delivery failure (#297). The one console notice is printed here, once, for every caller; callers decide
+      // control flow by the error type.
+      let saved = next;
+      try {
+        saved = this.d.board.get(task.id) ?? next;
+      } catch { /* the write's row is still true */ }
+      // Superseded means a later entry that moves or settles the task: another assignment, an unassign, the
+      // owner's accept, done, approval, close. Entries that do neither (the hub's quiet bookkeeping, a check
+      // result landing during the brief) leave the assignment exactly as undelivered as before: the notice and
+      // the typed error stand (#297 Decisions).
+      const moves = (entries: Task["history"]) => entries.filter((h) => !QUIET_EVENTS.has(h.event) && !h.event.startsWith("check "));
+      if (moves(saved.history).length !== moves(next.history).length) throw e;
+      this.releaseNotice(this.undeliveredNotice(saved, e));
+      throw new AssignmentUndeliveredError(saved, e);
     }
-    this.announceRouting(next, a);
+    // A claim is its own hand-over, with no delivery: its accepted write and its line stay as they were (#297).
     if (opts.claim && a.owner === by) {
       const claimed = this.d.board.update(next.id, by, "accepted", { state: "in_progress" });
-      this.d.notify(`task ${this.publicTitle(claimed)} claimed by ${by}`);
+      this.releaseNotice(`task ${this.publicTitle(claimed)} claimed by ${by}`);
       return claimed;
     }
-    await this.sendTask(next, a, opts.context, this.overlaps(next, true, hits), opts.contextWithheld);
     return next;
   }
 
@@ -936,6 +989,16 @@ export class Tasks {
     }
   }
 
+  /**
+   * The one text for a saved assignment whose delivery is unconfirmed (#297), built through publicTitle (a PII task
+   * shows nothing more than it does today): what to check, and how to send it again. No automatic resend: a blind
+   * resend can duplicate a publish that did leave (the #276 decision).
+   */
+  undeliveredNotice(task: Task, cause: unknown): string {
+    const owner = task.owner ?? "its owner";
+    return `task ${this.publicTitle(task)}: the move to ${owner} is saved, but its assignment's delivery is not confirmed (${cause instanceof Error ? cause.message : String(cause)}); look for a queued or needs_review delivery with ahub queue list --peer ${owner} (then ahub queue show <id>), or the accepted entry in ahub task show ${task.id} if the journal is down; send it again with: ahub task assign ${task.id} ${owner}`;
+  }
+
   private readonly offered = new Set<number>(); // assignments in this hub run, including offers still in flight
   private readonly sent = new Map<string, PeerId>(); // hand-over (`handOver`) -> owner, for the owner's current turn: its task envelope started it, or it claimed the task in it
 
@@ -958,7 +1021,7 @@ export class Tasks {
 
   /** Callers hold a list read before an await: re-read, or a task the other caller offered meanwhile is offered twice. */
   private async offerReady(stale: Task, why: string): Promise<void> {
-    let offering = false;
+    let offering = false, undelivered: AssignmentUndeliveredError | undefined;
     try {
       const t = this.d.board.get(stale.id);
       if (!t || t.state !== "proposed" || t.owner || this.offered.has(t.id)) return;
@@ -968,9 +1031,12 @@ export class Tasks {
       this.releaseNotice(`task ${this.publicTitle(ready)} is ready: what it waited for is approved`);
       await this.assignOwner(ready, HUB);
     } catch (e) {
-      this.releaseNotice(`task ${this.publicTitle(stale)}: could not be assigned: ${e instanceof Error ? e.message : String(e)}`);
+      // A saved move whose delivery failed is not "could not be assigned" (#297); the console notice was printed
+      // where the error was thrown. The offer stays consumed by the error's own evidence, without the readback.
+      if (e instanceof AssignmentUndeliveredError) undelivered = e;
+      else this.releaseNotice(`task ${this.publicTitle(stale)}: could not be assigned: ${e instanceof Error ? e.message : String(e)}`);
     } finally {
-      if (offering) {
+      if (offering && !undelivered) {
         try {
           if (!this.d.board.get(stale.id)?.owner) this.offered.delete(stale.id);
         } catch (e) {
@@ -1380,7 +1446,18 @@ export class Tasks {
     this.contradict(rejected);
     this.note(rejected, by, "decision", `Task #${rejected.id} changes requested by ${by}: ${rejected.title}\n${note ?? ""}`, withheld);
     if (rejected.rejections >= ESCALATE_AFTER) {
-      const moved = await this.escalate(HUB, rejected.id, `${rejected.rejections} consecutive changes_requested`, "rejections");
+      let moved: Task;
+      try {
+        moved = await this.escalate(HUB, rejected.id, `${rejected.rejections} consecutive changes_requested`, "rejections");
+      } catch (e) {
+        // The verdict is saved. If the escalation's move was saved too, only its delivery is unconfirmed, and the
+        // error carries the saved task (#297); the console notice was printed where the error was thrown. The
+        // reviewer gets the saved task back, never a failed tool call (#276). Anything else (the task closed
+        // meanwhile (#254), a failed board write, a superseded move) still throws. assignOwner keeps throwing for
+        // the ready offer's retry (#231).
+        if (!(e instanceof AssignmentUndeliveredError)) throw e;
+        return e.task;
+      }
       if (moved.owner !== rejected.owner) return moved;
       // Nobody to escalate to: the owner still has to hear the verdict and the note.
       this.releaseNotice(`task ${this.publicTitle(moved)}: could not tell ${moved.owner ?? "its owner"} changes were requested again`, () =>
@@ -1404,13 +1481,27 @@ export class Tasks {
     if (from && by !== HUB) this.d.board.recordOutcome(from, task.class, false);
     // Only a reviewer that asked for changes on this work saw it fail: not an escalation of unreviewed work (a Pi failure).
     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 });
+    // The guarded tail of a landed move: the console notice, the decision note and the old owner's stop message,
+    // each behind its own releaseNotice. It runs on the success path and on a saved move whose delivery failed.
+    const tail = (moved: Task) => {
+      this.releaseNotice(`task ${this.publicTitle(moved)} escalated from ${from} to ${moved.owner} (${why})`);
+      this.note(moved, by, "decision", `Task #${moved.id} escalated from ${from} to ${moved.owner}: ${why}`);
+      if (from) this.releaseNotice(`task ${this.publicTitle(moved)}: could not tell ${from} it moved to ${moved.owner}`, () =>
+        this.tell({ ...moved, owner: from }, `Task #${moved.id} moved to ${moved.owner} (${why}). Stop working on it.`, this.isPii(moved)));
+    };
+    let next: Task;
+    try {
+      next = await this.assignOwner(task, by, { candidates: list, event: "escalated", reason, note: `${why}; from ${from ?? "none"}`, context: why });
+    } catch (e) {
+      // A saved move whose delivery failed arrives as AssignmentUndeliveredError carrying the saved task (#297);
+      // the tail still runs on it (its parts are guarded), and the caller still gets the throw. Anything before
+      // the write gets neither.
+      if (e instanceof AssignmentUndeliveredError) tail(e.task);
+      throw e;
+    }
     if (next.owner && next.owner !== from) {
       // 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.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)));
+      tail(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)!;
   }
@@ -1421,7 +1512,7 @@ export class Tasks {
     // Work that waits is handed to nobody yet (issue #207): the peer becomes its reserved owner instead.
     if (!this.waitsFor(task).length) return this.assignOwner(task, by, { candidates: [peer], event: "reassigned", reason: "manual", override: by === USER });
     const next = this.d.board.update(task.id, by, "reserved", { reserved: peer }, `for ${peer}`, { reason: "manual" });
-    this.d.notify(`task ${this.publicTitle(next)} reserved for ${peer} by ${by}; it is offered to ${peer} first once what it waits for is approved`);
+    this.releaseNotice(`task ${this.publicTitle(next)} reserved for ${peer} by ${by}; it is offered to ${peer} first once what it waits for is approved`);
     return next;
   }
 
@@ -1442,8 +1533,15 @@ export class Tasks {
         const pii = this.isPii(task);
         const candidates = [pii ? LOCAL : PI, pii ? undefined : LOCAL, ...(routing.classes[task.class]?.peers ?? []).filter((p) => p !== LOCAL && p !== PI)].filter((p): p is PeerId => !!p);
         const back = task.state === "in_progress" ? this.d.board.update(task.id, HUB, "released", { state: "proposed" }, `budget pause of ${peer}`) : task;
-        const next = await this.assignOwner(back, HUB, { candidates, exclude: [peer], event: "reassigned", reason: "budget", note: `budget pause of ${peer}`, clearOnFail: true, ...(context ? { context, contextWithheld } : {}) });
-        moved.push({ id: task.id, title: this.publicTitle(task), to: next.owner, role: "owner" });
+        try {
+          const next = await this.assignOwner(back, HUB, { candidates, exclude: [peer], event: "reassigned", reason: "budget", note: `budget pause of ${peer}`, clearOnFail: true, ...(context ? { context, contextWithheld } : {}) });
+          moved.push({ id: task.id, title: this.publicTitle(task), to: next.owner, role: "owner" });
+        } catch (e) {
+          // A saved move whose delivery failed: the console notice was printed where the error was thrown; the
+          // task counts as moved and the relay goes on (#297). No retry is needed for it: the notice already spoke.
+          if (!(e instanceof AssignmentUndeliveredError)) throw e;
+          moved.push({ id: task.id, title: this.publicTitle(task), to: e.task.owner, role: "owner" });
+        }
       } else if (task.reviewer === peer && task.state !== "approved") {
         // No owner candidates: only the reviewer is wanted, and it must be neither the paused peer nor the task's owner.
         const a = assign(task, this.states(), routing, { exclude: [peer], candidates: [], ...(task.owner ? { notReviewer: task.owner } : {}), ...this.weights(task.class) });

package/src/hub/terminal-open.ts

@@ -0,0 +1,64 @@
+import { spawn } from "node:child_process";
+import { personEnv } from "./child-process.ts";
+import { openStartTerminal, orcaExecutable, shellQuote, startTerminalWorktree, type CommandRunner } from "../cli/terminal-recovery.ts";
+
+/** #269: where a terminal for a hub-made start comes from, or why there is none. */
+export type TerminalOpened = { ok: true; via: string } | { ok: false; why: string; detail?: string };
+export interface TerminalOpener {
+  /** Whether a start could open a terminal now; opens nothing. */
+  available(): TerminalOpened;
+  /** A terminal running `argv`, which the caller assembled from fixed words: nothing here adds to it. */
+  open(title: string, argv: readonly string[]): Promise<TerminalOpened>;
+}
+
+// ponytail: a template command still running after this long is taken to be the terminal itself, so one that fails
+// later is reported as opened; a provider-specific readiness check (as recovery has for Orca) if that ever misleads.
+const SETTLE_MS = 1500;
+const PLACEHOLDER = /\{(command|title|cwd)\}/g;
+
+/**
+ * The providers, in order: the machine-local `terminal.open` command template, then Orca (the path recovery uses)
+ * when this project has an Orca worktree. `run` replaces the Orca CLI in tests.
+ */
+export function terminalOpener(opts: { template: string[]; cwd: string; stateDir: string; env?: NodeJS.ProcessEnv; run?: CommandRunner }): TerminalOpener {
+  const env = opts.env ?? process.env;
+  const worktree = () => startTerminalWorktree(opts.cwd, opts.stateDir, env);
+  const available = (): TerminalOpened => {
+    if (opts.template.length) return { ok: true, via: "terminal.open" };
+    if (!worktree()) return { ok: false, why: "no terminal.open command is configured and this project has no Orca worktree on record" };
+    if (!opts.run && !Bun.which(orcaExecutable())) return { ok: false, why: `the ${orcaExecutable()} command is not on PATH` };
+    return { ok: true, via: "orca" };
+  };
+  return {
+    available,
+    async open(title, argv) {
+      const can = available();
+      if (!can.ok) return can;
+      // One command line, each word quoted for a POSIX shell: the terminal's shell runs exactly these words.
+      const command = argv.map(shellQuote).join(" ");
+      try {
+        if (can.via === "orca") {
+          await openStartTerminal(worktree()!, command, title, opts.run ? { runner: opts.run } : undefined);
+          return can;
+        }
+        // One pass with a function: a placeholder inside a substituted value (a project path that contains "{cwd}")
+        // is not expanded again, and "$" in a path is not a replacement pattern. Only {command} is shell-quoted;
+        // {title} and {cwd} are raw text for an argv element of their own.
+        const values: Record<string, string> = { command, title, cwd: opts.cwd };
+        const [bin, ...args] = opts.template.map((part) => part.replace(PLACEHOLDER, (_, name: string) => values[name]!));
+        // Detached and unwatched: the terminal is the person's and outlives the hub.
+        const child = spawn(bin!, args, { cwd: opts.cwd, env: personEnv(env), stdio: "ignore", detached: true });
+        const failed = await new Promise<string | undefined>((resolve) => {
+          const timer = setTimeout(() => resolve(undefined), SETTLE_MS); // still running: it is the terminal itself
+          child.once("error", (error) => { clearTimeout(timer); resolve(`terminal.open could not start (${(error as NodeJS.ErrnoException).code ?? "error"})`); });
+          child.once("exit", (code, signal) => { clearTimeout(timer); resolve(code === 0 ? undefined : `terminal.open exited ${signal ?? code}`); });
+        });
+        child.unref();
+        return failed ? { ok: false, why: failed } : can;
+      } catch (error) {
+        // The provider's own text can name paths and its stderr: it goes to the hub's log, not to the caller.
+        return { ok: false, why: can.via === "orca" ? "Orca could not create the terminal" : "terminal.open could not be run", detail: (error as Error).message };
+      }
+    },
+  };
+}

package/src/hub/ui.ts

@@ -1,10 +1,13 @@
+import { PEER_START_RETRY_MS } from "./start-mode.ts";
 import { taskProgress } from "../ui/task-progress.ts";
 import { createHash, randomBytes } from "node:crypto";
 import { readFileSync } from "node:fs";
 
+/** What a request's session may do (#269): `settings` while a session opened by `ahub ui --settings` is inside its window. */
+export interface DashboardSession { settings: boolean; settingsUntil?: number }
 export interface DashboardOptions {
-  snapshot: (after: number, input?: Record<string, unknown>) => unknown | Promise<unknown>;
-  action: (input: Record<string, unknown>) => unknown | Promise<unknown>;
+  snapshot: (after: number, input?: Record<string, unknown>, session?: DashboardSession) => unknown | Promise<unknown>;
+  action: (input: Record<string, unknown>, session?: DashboardSession) => unknown | Promise<unknown>;
   projects?: () => unknown | Promise<unknown>;
   selectedProjectId?: string;
   /** Injectable clock for expiry tests; production uses wall time. */
@@ -13,17 +16,20 @@ export interface DashboardOptions {
 
 const TICKET_MS = 60_000;
 const SESSION_MS = 60 * 60_000;
+/** How long a session opened by `ahub ui --settings` may change settings that raise authority; it stays an ordinary session after. */
+export const SETTINGS_MS = 15 * 60_000;
 const LIMIT = 64;
 const secret = () => randomBytes(32).toString("hex");
 
 /** Separate browser surface. Only the authenticated control console may construct it and issue tickets. */
 export function startDashboard(options: DashboardOptions) {
   const now = options.now ?? Date.now;
-  const tickets = new Map<string, number>();
-  const sessions = new Map<string, number>();
+  const tickets = new Map<string, { expires: number; settings: boolean }>();
+  const sessions = new Map<string, { expires: number; settingsUntil?: number }>();
   // Inject the same pure public-board model used by the console before computing CSP hashes.
   const html = readFileSync(new URL("../ui/index.html", import.meta.url), "utf8")
-    .replace("/* TASK_PROGRESS_MODEL */", () => `const taskProgress = ${taskProgress.toString()};`);
+    .replace("/* TASK_PROGRESS_MODEL */", () => `const taskProgress = ${taskProgress.toString()};`)
+    .replace("/* PEER_START_RETRY_MS */", () => `const PEER_START_RETRY_MS = ${PEER_START_RETRY_MS};`);
   const hashes = (tag: string) => [...html.matchAll(new RegExp(`<${tag}>([\\s\\S]*?)</${tag}>`, "g"))]
     .map((m) => `'sha256-${createHash("sha256").update(m[1]!).digest("base64")}'`).join(" ");
   const headers = {
@@ -36,9 +42,13 @@ export function startDashboard(options: DashboardOptions) {
   const json = (body: unknown, status = 200, extra: Record<string, string> = {}) =>
     new Response(JSON.stringify(body), { status, headers: { ...headers, "Content-Type": "application/json", ...extra } });
   const reject = (status: number, error: string) => json({ ok: false, error }, status);
-  function prune(map: Map<string, number>) {
-    for (const [key, expires] of map) if (expires <= now()) map.delete(key);
+  function prune(map: Map<string, { expires: number }>) {
+    for (const [key, entry] of map) if (entry.expires <= now()) map.delete(key);
   }
+  const sessionOf = (cookie: string | undefined): DashboardSession => {
+    const until = cookie ? sessions.get(cookie)?.settingsUntil : undefined;
+    return until !== undefined && until > now() ? { settings: true, settingsUntil: until } : { settings: false };
+  };
   const server = Bun.serve({
     hostname: "127.0.0.1",
     port: 0,
@@ -75,10 +85,11 @@ export function startDashboard(options: DashboardOptions) {
       if (path !== "/session" && (!cookie || !sessions.has(cookie))) return reject(401, "session expired; run ahub ui");
       if (path === "/session") {
         const ticket = typeof input.ticket === "string" ? input.ticket : "";
-        if (!tickets.delete(ticket)) return reject(401, "ticket expired or used; run ahub ui");
+        const issued = tickets.get(ticket);
+        if (!issued || !tickets.delete(ticket)) return reject(401, "ticket expired or used; run ahub ui");
         if (sessions.size >= LIMIT) return reject(429, "too many sessions; try later");
         const session = secret();
-        sessions.set(session, now() + SESSION_MS);
+        sessions.set(session, { expires: now() + SESSION_MS, ...(issued.settings ? { settingsUntil: now() + SETTINGS_MS } : {}) });
         return json({ ok: true }, 200, { "Set-Cookie": `${cookieName}=${session}; HttpOnly; SameSite=Strict; Path=/; Max-Age=${SESSION_MS / 1000}` });
       }
       if (path === "/projects") {
@@ -97,7 +108,7 @@ export function startDashboard(options: DashboardOptions) {
         const after = input.after ?? 0;
         if (typeof after !== "number" || !Number.isSafeInteger(after) || after < 0) return reject(400, "invalid cursor");
         try {
-          const result = await options.snapshot(after, input);
+          const result = await options.snapshot(after, input, sessionOf(cookie));
           if (!result || typeof result !== "object" || Array.isArray(result)) return json(result);
           const response = { ...(result as Record<string, unknown>) };
           if (typeof response.projectId === "string" && typeof input.projectId === "string" && response.projectId !== input.projectId) return reject(409, "snapshot project changed; refresh the dashboard");
@@ -110,7 +121,7 @@ export function startDashboard(options: DashboardOptions) {
         }
       }
       try {
-        return json(await options.action(input));
+        return json(await options.action(input, sessionOf(cookie)));
       } catch {
         // Exceptions may quote private task text or backend details. Never echo them to the page.
         return reject(400, "action failed; check its inputs and the terminal");
@@ -125,11 +136,12 @@ export function startDashboard(options: DashboardOptions) {
   const cookieName = `ahub_ui_${server.port}`;
   return {
     origin,
-    issue(): string {
+    /** `settings`: the ticket of `ahub ui --settings`, whose session may raise authority for SETTINGS_MS (#269). */
+    issue(settings = false): string {
       prune(tickets);
       if (tickets.size >= LIMIT) tickets.delete(tickets.keys().next().value!);
       const ticket = secret();
-      tickets.set(ticket, now() + TICKET_MS);
+      tickets.set(ticket, { expires: now() + TICKET_MS, settings });
       return `${origin}/#${ticket}`;
     },
     stop() {

package/src/local/deny.ts

@@ -1,4 +1,4 @@
-import { basename, sep } from "node:path";
+import { basename, dirname, sep } from "node:path";
 
 /**
  * The one denylist. tools.ts checks paths against it, sandbox.ts turns it into seatbelt rules, capture.ts keeps
@@ -50,13 +50,23 @@ const hfsFoldedName = (name: string) => `${HFS_IGNORABLE}*${[...name].map((c) =>
  * 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.
+ * submodules. A submodule's git dir under `.git/modules/` gets the same `config`/`hooks` refusal at whatever depth
+ * submodules nest (a nested one lives under `.git/modules/<a>/modules/<b>`, #281), anchored at the discovered
+ * modules root so a directory named `refs`, `config` or `hooks` ABOVE the project neither disables the rule nor
+ * trips it; a `/refs/` or `/logs/` segment below the root keeps a branch or tag named `config` or `hooks` writable
+ * (the round-3 regression of #277), at the price of leaving a submodule whose own path holds a `refs` or `logs`
+ * segment unprotected. The basenames are folded; a folded INTERMEDIATE component on HFS+ (a spelling of `modules`)
+ * is a known residual, the same one the external git dir rules carry. The directory entries above those files are
+ * protected as the `.git` name is: the discovered git dirs, the modules root and every component in between are
+ * refused as targets (rename, replace, symlink, recreate). 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. ponytail: the modules rules do contain the (plain) modules root; a project path
+ * over roughly 600 bytes with submodules would exceed the limit — fold the root's segments if one ever shows up.
  */
-export function hubWriteRegexes(root: string, gitDirs: string[] = []): string[] {
+export function hubWriteRegexes(root: string, gitDirs: string[] = [], moduleGit?: { root: string; entries: string[] }): string[] {
   const git = hfsFoldedName(".git");
   const re = (s: string) => `(regex ${sbplString(s)})`;
   const external = gitDirs.flatMap((d) => [
@@ -64,12 +74,24 @@ export function hubWriteRegexes(root: string, gitDirs: string[] = []): string[]
     `(subpath ${sbplString(`${d}/hooks`)})`,
     `(require-all (subpath ${sbplString(d)}) ${re(`^.*/${hfsFoldedName("commondir")}$`)})`,
   ]);
+  const modules = moduleGit
+    ? [
+        // Every name matches whole components only: `(.*/)?` forces a boundary, so a submodule named `catalogs`
+        // or `prefs` keeps the refusal and one named `webhooks` keeps its ordinary writes (#281 round 2).
+        `(require-all ${re(`^${sbplEscape(moduleGit.root)}/(.*/)?${hfsFoldedName("config")}$`)} (require-not ${re(`^${sbplEscape(moduleGit.root)}/(.*/)?(refs|logs)/`)}))`,
+        `(require-all ${re(`^${sbplEscape(moduleGit.root)}/(.*/)?${hfsFoldedName("hooks")}(/|$)`)} (require-not ${re(`^${sbplEscape(moduleGit.root)}/(.*/)?(refs|logs)/`)}))`,
+        // A submodule git dir as a directory entry: no rename, replace, symlink or recreate. The basename is
+        // folded (HFS+ opens the folded spelling as the real entry); the plain prefix is the path as discovered.
+        ...moduleGit.entries.map((d) => re(`^${sbplEscape(dirname(d))}/${hfsFoldedName(basename(d))}$`)),
+      ]
+    : [];
   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")}$`)})`,
+    ...modules,
     ...external,
   ];
 }

package/src/local/sandbox.ts

@@ -1,8 +1,9 @@
 import { spawn, spawnSync } from "node:child_process";
-import { existsSync, mkdtempSync, rmSync } from "node:fs";
+import { existsSync, mkdtempSync, readdirSync, rmSync, type Dirent } from "node:fs";
 import { homedir, tmpdir } from "node:os";
-import { join, resolve } from "node:path";
+import { dirname, join, resolve } from "node:path";
 import { realPath } from "../hub/project.ts";
+import { hubGitSync } from "../hub/git.ts";
 import { denyRegexes, hubWriteRegexes, sbplString } from "./deny.ts";
 
 const SANDBOX_EXEC = "/usr/bin/sandbox-exec";
@@ -40,12 +41,47 @@ function developerDir(): string | undefined {
 
 /** A submodule or worktree keeps its git dir outside the project; git needs it, minus the parts that execute or reconfigure. */
 function externalGitDirs(root: string): string[] {
-  const out = spawnSync("git", ["-C", root, "rev-parse", "--absolute-git-dir", "--git-common-dir"], { encoding: "utf8" });
+  // Runs in the hub process, outside the sandbox: the hardened helper keeps the repo's config from naming a program (#281).
+  const out = hubGitSync(["-C", root, "rev-parse", "--absolute-git-dir", "--git-common-dir"], { encoding: "utf8" });
   if (out.status !== 0) return [];
   const dirs = out.stdout.trim().split("\n").map((d) => resolve(root, d));
   return [...new Set(dirs)].filter((d) => !d.startsWith(`${root}/`));
 }
 
+/**
+ * The project's submodule git directories live under the common dir's `modules/` tree (the worktree case included:
+ * it is the main repo's `.git/modules`). Returns the modules root and every directory entry that must not be
+ * renamed, replaced, symlinked or recreated: each discovered git dir (a directory holding HEAD and config) and
+ * every component between it and the modules root (#281). Discovered in the hub process, outside the sandbox.
+ */
+function moduleGitDirs(root: string): { root: string; entries: string[] } | undefined {
+  const out = hubGitSync(["-C", root, "rev-parse", "--git-common-dir"], { encoding: "utf8" });
+  if (out.status !== 0) return undefined;
+  const modulesRoot = join(resolve(root, out.stdout.trim()), "modules");
+  const dirs: string[] = [];
+  const walk = (dir: string, depth: number): void => {
+    if (depth > 8) return; // submodules do not nest deeper in practice; the regex rules still cover the names
+    let entries: Dirent[];
+    try {
+      entries = readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return; // no modules tree (no submodules): nothing to discover
+    }
+    const names = new Set(entries.map((e) => e.name));
+    if (names.has("HEAD") && names.has("config")) {
+      dirs.push(dir);
+      const nested = join(dir, "modules");
+      if (names.has("modules")) walk(nested, depth + 1); // a submodule of a submodule
+      return;
+    }
+    for (const e of entries) if (e.isDirectory()) walk(join(dir, e.name), depth + 1);
+  };
+  walk(modulesRoot, 0);
+  const entries = new Set<string>([modulesRoot]);
+  for (const d of dirs) for (let p = d; p.length > modulesRoot.length; p = dirname(p)) entries.add(p);
+  return { root: modulesRoot, entries: [...entries] };
+}
+
 /** The system directories a deny-default profile lets commands read and run from: dyld, frameworks, toolchains. */
 const SYSTEM_READABLE = ["/usr", "/bin", "/sbin", "/System", "/Library", "/opt", "/private/etc", "/private/var/db/timezone", "/private/var/db/dyld"];
 /**
@@ -74,6 +110,7 @@ export function profile(cwd: string, network: SandboxNetwork, readAllow: string[
   const inHome = (p: string) => (p.startsWith("~/") ? join(home, p.slice(2)) : p);
   const root = realPath(cwd);
   const gitDirs = externalGitDirs(root);
+  const moduleGit = moduleGitDirs(root);
   const creds = [".ssh", ".aws", ".gnupg", ".config/gh", ".config/gcloud", ".kube", ".docker", ".netrc", ".npmrc", ".omniroute", ".claude", ".codex", ".kimi-code", "Library/Keychains"];
   const dev = developerDir();
   const readable = [root, ...HOME_READABLE.map((p) => join(home, p)), ...readAllow.map(inHome), ...gitDirs, ...(dev ? [dev] : [])];
@@ -104,9 +141,10 @@ export function profile(cwd: string, network: SandboxNetwork, readAllow: string[
     `(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. 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(" ")})`,
+    // at any depth (creation, rename, symlink, gitfile), a submodule git dir's config and hooks under
+    // .git/modules/ are refused at the depth submodules nest (#281), 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, moduleGit).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/memory/recall.ts

@@ -1,7 +1,7 @@
-import { spawnSync } from "node:child_process";
 import { basename, dirname, resolve } from "node:path";
 import { readFileSync } from "node:fs";
 import type { PeerId } from "../hub/envelope.ts";
+import { hubGitSync } from "../hub/git.ts";
 import type { MemoryClient } from "./client.ts";
 
 const PLATFORMS = ["claude", "codex", "kimi", "agent-hub"];
@@ -14,7 +14,7 @@ const HEADER =
 
 /** Project names from the outermost superproject down to this repo. */
 export function projectChain(cwd: string): string[] {
-  const git = (dir: string, arg: string) => spawnSync("git", ["-C", dir, "rev-parse", arg], { encoding: "utf8" }).stdout?.trim() ?? "";
+  const git = (dir: string, arg: string) => hubGitSync(["-C", dir, "rev-parse", arg], { encoding: "utf8" }).stdout?.trim() ?? "";
   const top = git(cwd, "--show-toplevel");
   if (!top) return [basename(cwd)];