@staix/agent-hub 0.12.21 → 0.12.23

package/src/hub/start-mode.ts

@@ -0,0 +1,48 @@
+/**
+ * #269: how a peer comes up when the hub starts it: its own TUI in a terminal, or headless. A person who types
+ * `ahub <peer>` gets the same default and can override it with a flag.
+ */
+/** Shared terminal-start guard and dashboard retry hold after an unconfirmed response. */
+export const PEER_START_RETRY_MS = 30_000;
+export const START_MODES = ["tui", "headless"] as const;
+export type StartMode = typeof START_MODES[number];
+/** The peers with both forms. Claude has only a TUI; Kimi (ACP) and the local worker have none the hub attaches to. */
+export const START_MODE_PEERS = ["pi", "codex"] as const;
+/** Every peer the hub can start itself. */
+export const STARTABLE_PEERS = ["claude", "codex", "kimi", "pi", "local"] as const;
+export type StartablePeer = typeof STARTABLE_PEERS[number];
+export const isStartablePeer = (value: unknown): value is StartablePeer => typeof value === "string" && (STARTABLE_PEERS as readonly string[]).includes(value);
+
+export type PeerStartConfig = Record<string, { start_mode?: StartMode }>;
+/** The checked `peers` block of the config; throws on anything but `{ pi|codex: { start_mode: "tui"|"headless" } }`. */
+export function peerStartConfig(value: unknown): PeerStartConfig {
+  if (value === undefined) return {};
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("peers must be an object of per-peer settings");
+  const result: PeerStartConfig = {};
+  for (const [peer, block] of Object.entries(value)) {
+    if (!(START_MODE_PEERS as readonly string[]).includes(peer)) throw new Error(`peers.${peer}: only ${START_MODE_PEERS.join(" and ")} have a start mode`);
+    if (!block || typeof block !== "object" || Array.isArray(block)) throw new Error(`peers.${peer} must be an object`);
+    const mode = (block as { start_mode?: unknown }).start_mode;
+    if (mode !== undefined && !(START_MODES as readonly unknown[]).includes(mode)) throw new Error(`peers.${peer}.start_mode must be tui or headless`);
+    result[peer] = mode === undefined ? {} : { start_mode: mode as StartMode };
+  }
+  return result;
+}
+
+/** The mode a start of `peer` takes when nothing more specific was asked: `tui` wherever the peer has one. */
+export function startModeOf(peers: PeerStartConfig | undefined, peer: string): StartMode {
+  if (peer === "claude") return "tui";
+  if ((START_MODE_PEERS as readonly string[]).includes(peer)) return peers?.[peer]?.start_mode ?? "tui";
+  return "headless";
+}
+
+/**
+ * The checked `terminal.open` template: an argv in which exactly one element contains `{command}` (replaced by the
+ * shell-quoted command the hub assembled); `{title}` and `{cwd}` are replaced too. Empty means no template.
+ */
+export function terminalTemplate(value: unknown): string[] {
+  if (value === undefined || value === null) return [];
+  if (!Array.isArray(value) || value.some((part) => typeof part !== "string" || !part)) throw new Error("terminal.open must be a list of non-empty strings (an argv with a {command} placeholder)");
+  if (value.length && value.filter((part: string) => part.includes("{command}")).length !== 1) throw new Error("terminal.open needs {command} in exactly one element");
+  return [...value];
+}

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;
   }
 
@@ -920,9 +973,30 @@ 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 */ }
+    }
+  }
+
+  /**
+   * 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
@@ -947,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;
@@ -957,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) {
@@ -1125,7 +1202,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 +1332,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 +1356,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 +1435,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;
     }
@@ -1367,14 +1446,27 @@ 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.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;
   }
 
@@ -1389,12 +1481,28 @@ 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) {
-      this.d.notify(`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"}`);
+      // The move is on the board (#243): review() reaches here after its changes_requested write.
+      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)!;
   }
 
@@ -1404,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;
   }
 
@@ -1425,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) });
@@ -1475,7 +1590,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/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() {