@staix/agent-hub 0.12.21 → 0.12.23

package/src/cli/upgrade.ts

@@ -1,8 +1,9 @@
+import { databaseBusySite, isDatabaseBusy, RecoveryDatabaseBusy } from "../hub/recovery-error.ts";
 import { Database } from "bun:sqlite";
 import { createHash, randomUUID } from "node:crypto";
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
-import { PROJECT_COLUMNS, projectFromRow, type Project } from "../hub/registry.ts";
+import { REGISTRY_DB_BUSY_TIMEOUT_MS, PROJECT_COLUMNS, projectFromRow, type Project } from "../hub/registry.ts";
 import { hubHome } from "../hub/project.ts";
 import { acquireRecoveryLock, claimRunner, coordinatorCurrent, readOperation, recoveryCommand, recoveryLock, releaseRecoveryLock, writeOperation } from "../hub/recovery-store.ts";
 
@@ -20,7 +21,8 @@ export interface Inspection {
   version?: string;
   protocol?: number;
   peers: RecoveryPeer[];
-  recovery?: { operationId?: string; phase?: string; ready?: boolean };
+  /** `waiting` (#272): what the running hub says keeps it from being quiet (busy peers, pending approvals); display only. */
+  recovery?: { operationId?: string; phase?: string; ready?: boolean; waiting?: string[] };
   blockers: string[];
   /** #215: for a stopped runtime, the operation whose committed restart snapshot its state dir holds (unreleased). */
   snapshot?: string;
@@ -81,6 +83,7 @@ export interface RecoveryOperation {
   pluginInstalled?: boolean;
   globalInstalled?: boolean;
   error?: string;
+  failure?: { code: "database_busy"; retryable: true; site?: string[] };
   /** #215: every human disposition, in order. Operator reasons only; never task or message text. */
   audit?: { at: number; action: "fresh-session" | "stop-and-archive"; reason: string; peer?: string; projects: string[] }[];
   disposition?: { choice: "stop-and-archive"; at: number; projects: Record<string, string> };
@@ -202,32 +205,48 @@ export function disposeRefusal(op: RecoveryOperation, live: Record<string, Inspe
   return unsettled ? { project: unsettled.id, reads: live[unsettled.id]?.state ?? "not inspected" } : undefined;
 }
 
+/** #272: one entry of `next`. `text` is the line status prints; a screen runs `kind` through `recoveryArgv`. */
+export interface NextChoice {
+  kind: "resume" | "abort" | "fresh" | "stop" | "wait";
+  /** `fresh` only: the peer that starts as a new session. */
+  peer?: string;
+  text: string;
+}
+
 /**
  * #215: what the person can do now, in the receipt table's order: resume (it also launches a failed peer again),
  * abort where it can succeed, a fresh session for a failed Codex or Claude restoration, and stop-and-archive last.
- * `status` and every error that names choices use this one list.
+ * `status`, every error that names choices and the interactive screen (#272) use this one list.
  */
-export function nextActions(receipt: RecoveryOperation, runner?: number | "unknown", live: Record<string, Inspection | undefined> = {}): string[] {
+export function nextChoices(receipt: RecoveryOperation, runner?: number | "unknown", live: Record<string, Inspection | undefined> = {}): NextChoice[] {
   // A receipt read without its project lists (never written so by a coordinator) still gets the general choices.
   const op: RecoveryOperation = receipt.projects ? receipt : { ...receipt, projects: [], plan: { ...receipt.plan, projects: receipt.plan?.projects ?? [] } };
   if (op.phase === "completed" || op.phase === "cancelled") return [];
   // claimRunner refuses an owner it cannot read, so resume, abort and dispose are all refused until the record reads.
-  if (runner === "unknown") return [`${recoveryCommand(op, "status")} again: whether a runner holds the operation could not be read (resume, abort and dispose are refused until it can)`];
-  if (runner) return [`wait: runner ${runner} is working; ${recoveryCommand(op, "status")}`];
+  if (runner === "unknown") return [{ kind: "wait", text: `${recoveryCommand(op, "status")} again: whether a runner holds the operation could not be read (resume, abort and dispose are refused until it can)` }];
+  if (runner) return [{ kind: "wait", text: `wait: runner ${runner} is working; ${recoveryCommand(op, "status")}` }];
   const unsettled = disposeRefusal(op, live);
-  const stop = unsettled ? `wait until ${unsettled.project}'s hub settles, then ${recoveryCommand(op, "status")}` : recoveryCommand(op, "dispose", STOP);
-  if (op.disposition) return [unsettled ? stop : `rerun ${stop}`];
+  const stop: NextChoice = unsettled ? { kind: "wait", text: `wait until ${unsettled.project}'s hub settles, then ${recoveryCommand(op, "status")}` } : { kind: "stop", text: recoveryCommand(op, "dispose", STOP) };
+  if (op.disposition) return [unsettled ? stop : { kind: "stop", text: `rerun ${stop.text}` }];
   const failed = [...new Set(op.projects.flatMap((p) => failedPeers(op, p, live)))];
   const old = !!op.sourceRoot && !coordinatorCurrent(op.sourceRoot);
   const abortable = !abortRefusal(op, live);
   const stuck = resumeBlocked(op, live);
   return [
-    ...(stuck ? [] : [`${recoveryCommand(op, "resume")}${op.error ? " (after the next action in error)" : ""}${old ? ` (runs the coordinator that started this operation, which cannot re-prepare an expired hold: if it reports "source is no longer prepared", use ${abortable ? "abort or " : ""}stop-and-archive)` : ""}`]),
-    ...(abortable ? [recoveryCommand(op, "abort")] : []),
-    ...(targetReadsWaivers(op) && !stuck ? failed.map((peer) => recoveryCommand(op, "dispose", `--fresh-session ${peer} --reason <text>`)) : []),
+    ...(stuck ? [] : [{ kind: "resume" as const, text: `${recoveryCommand(op, "resume")}${op.error ? " (after the next action in error)" : ""}${old ? ` (runs the coordinator that started this operation, which cannot re-prepare an expired hold: if it reports "source is no longer prepared", use ${abortable ? "abort or " : ""}stop-and-archive)` : ""}` }]),
+    ...(abortable ? [{ kind: "abort" as const, text: recoveryCommand(op, "abort") }] : []),
+    ...(targetReadsWaivers(op) && !stuck ? failed.map((peer) => ({ kind: "fresh" as const, peer, text: recoveryCommand(op, "dispose", `--fresh-session ${peer} --reason <text>`) })) : []),
     stop,
   ];
 }
+export const nextActions = (receipt: RecoveryOperation, runner?: number | "unknown", live: Record<string, Inspection | undefined> = {}): string[] => nextChoices(receipt, runner, live).map((c) => c.text);
+
+/**
+ * #272: a runner that only waits for its source to get quiet can be stopped and the operation aborted: nothing was
+ * closed, stopped or asked to commit. Abort decides again on what is live, so a runner that moved on meanwhile is
+ * refused there, never here.
+ */
+export const cancellableWait = (op: RecoveryOperation): boolean => op.phase === "running" && op.step.startsWith("prepare:") && !op.disposition && !hasEffects(op) && !op.projects.some((p) => p.commitSent);
 
 /**
  * "next actions: ..." from nextActions, with the inspections the caller holds. Every error that lists choices ends with
@@ -271,6 +290,7 @@ export function registeredProjects(home = hubHome()): Project[] {
   if (!existsSync(path)) return [];
   const db = new Database(path, { readonly: true });
   try {
+    db.run(`PRAGMA busy_timeout = ${REGISTRY_DB_BUSY_TIMEOUT_MS}`);
     // #226: a registry no current release opened yet has no signature column, and this read never migrates.
     const signed = (db.query("PRAGMA table_info(projects)").all() as { name: string }[]).some((c) => c.name === "pid_signature");
     return (db.query(`SELECT ${PROJECT_COLUMNS}${signed ? ", pid_signature" : ""} FROM projects ORDER BY root`).all() as Record<string, unknown>[]).map(projectFromRow);
@@ -416,10 +436,11 @@ export async function runRecovery(id: string, driver: RecoveryDriver, home = hub
     if (op.disposition) {
       // The stop-and-archive in progress keeps its own cause; resume never runs an operation being abandoned.
       op.error ??= `a stop-and-archive of this operation is partway; ${nextActionsText(op, await liveProjects(op, driver.inspect))}`;
+      delete op.failure;
       op.phase = "blocked"; save();
       return op;
     }
-    op.phase = "running"; delete op.error; save();
+    op.phase = "running"; delete op.error; delete op.failure; save();
     step("stage");
     const target = await driver.stage(op);
     if (op.targetDigest && (target.root !== op.targetRoot || target.digest !== op.targetDigest)) throw new FinalRefusal("staged target changed since operation started");
@@ -477,7 +498,13 @@ export async function runRecovery(id: string, driver: RecoveryDriver, home = hub
           await driver.commit(project, id, planned.source.instanceId!);
           const deadline = driver.now() + 30_000;
           do {
-            live = await driver.inspect(project);
+            try { live = await driver.inspect(project); }
+            catch (error) {
+              if (!isDatabaseBusy(error)) throw error;
+              // A committed source may still be stopping. Contention is an
+              // unconfirmed read here, not a refusal; keep the existing bound.
+              live = { state: "unavailable", peers: [], blockers: ["database_busy"] };
+            }
             if (live.state === "stopped") break;
             if (live.instanceId && live.instanceId !== planned.source.instanceId) throw new Error(`${project.id}: another daemon started during shutdown`);
             await driver.sleep(100);
@@ -539,6 +566,7 @@ export async function runRecovery(id: string, driver: RecoveryDriver, home = hub
     releaseRecoveryLock(id, home); op.phase = "completed"; step("completed");
   } catch (error) {
     // #215: every runner error ends with the choices status shows, read from every open source, never only this one.
+    if (isDatabaseBusy(error)) { op.failure = { code: "database_busy", retryable: true, site: databaseBusySite(error) }; error = new RecoveryDatabaseBusy(); }
     if (error instanceof FinalRefusal) op.final = true;
     const next = nextActionsText(op, await liveProjects(op, driver.inspect));
     op.phase = "blocked"; op.error = `${error instanceof Error ? error.message : "recovery failed"}; ${next}`; save();
@@ -558,7 +586,7 @@ export function publicOperation(op: RecoveryOperation, runnerPid?: number | "unk
       ...(p.restarts?.length ? { restarts: p.restarts.length } : {}) })),
     pluginInstalled: !!op.pluginInstalled, globalInstalled: !!op.globalInstalled,
     ...(!targetReadsWaivers(op) && op.projects.some((p) => failedPeers(op, p).length) ? { freshSession: `not offered: target ${op.plan.version} cannot read recovery waivers, so it could not release a new session` } : {}),
-    ...(op.error ? { error: op.error } : {}), ...(op.disposition ? { disposition: op.disposition } : {}), ...(op.audit ? { audit: op.audit } : {}), next };
+    ...(op.error ? { error: op.error } : {}), ...(op.failure ? { failure: op.failure } : {}), ...(op.disposition ? { disposition: op.disposition } : {}), ...(op.audit ? { audit: op.audit } : {}), next };
 }
 
 /** Escape a blocked preflight without abandoning a stopped runtime or an uncertain terminal mutation. */
@@ -588,8 +616,12 @@ export async function abortRecovery(id: string, driver: RecoveryDriver, home = h
       const state = live[planned.project.id];
       if (state?.recovery?.operationId === id && state.recovery.phase !== "released") await driver.abort(planned.project, id, planned.source.instanceId!);
     }
+    delete op.error; delete op.failure;
     op.phase = "cancelled"; op.step = "cancelled"; op.updatedAt = driver.now();
     writeOperation(id, op, home); releaseRecoveryLock(id, home);
+  } catch (error) {
+    if (isDatabaseBusy(error)) throw new RecoveryDatabaseBusy();
+    throw error;
   } finally { releaseRunner(); }
 }
 
@@ -641,6 +673,7 @@ export async function disposeRecovery(id: string, choice: { fresh: string } | {
         (progress.fresh ??= {})[peer] = { lost: binding.sessionId, reason, at };
       }
       (op.audit ??= []).push({ at, action: "fresh-session", reason, peer, projects: failed.map((p) => p.id) });
+      delete op.error; delete op.failure;
       op.updatedAt = at; writeOperation(id, op, home);
       return op;
     }
@@ -670,6 +703,7 @@ export async function disposeRecovery(id: string, choice: { fresh: string } | {
     abandoned(op); // #227: in the same write as the disposition
     (op.audit ??= []).push({ at, action: "stop-and-archive", reason, projects: acts.map((a) => a.planned.project.id) });
     // Recorded before the first act: a crash inside a stop leaves a disposition that resume refuses to override.
+    delete op.failure;
     op.updatedAt = driver.now(); writeOperation(id, op, home);
     try {
       for (const { planned, live, act } of acts) {
@@ -682,12 +716,13 @@ export async function disposeRecovery(id: string, choice: { fresh: string } | {
         op.updatedAt = driver.now(); writeOperation(id, op, home);
       }
     } catch (error) {
+      if (isDatabaseBusy(error)) { op.failure = { code: "database_busy", retryable: true, site: databaseBusySite(error) }; error = new RecoveryDatabaseBusy(); }
       op.phase = "blocked"; op.updatedAt = driver.now();
       op.error = `stop-and-archive stopped partway and keeps the lock: ${error instanceof Error ? error.message : "disposition failed"} (a committed source stops by itself); ${nextActionsText(op, await liveProjects(op, driver.inspect))}`;
       writeOperation(id, op, home);
       throw error;
     }
-    delete op.error;
+    delete op.error; delete op.failure;
     op.phase = "cancelled"; op.step = "disposed: stop-and-archive (abandoned, not completed)"; op.updatedAt = driver.now();
     writeOperation(id, op, home); releaseRecoveryLock(id, home);
     return op;

package/src/hub/board.ts

@@ -1,6 +1,7 @@
 import { Database } from "bun:sqlite";
 import type { PeerId } from "./envelope.ts";
 import type { SweepRecord } from "./task-sweep.ts";
+import { HUB_DB_BUSY_TIMEOUT_MS } from "./db-timeout.ts";
 
 export const CLASSES = ["plan", "implement", "bulk_edit", "test", "review", "summarize", "triage"] as const;
 export type TaskClass = (typeof CLASSES)[number];
@@ -83,6 +84,7 @@ export class Board {
 
   constructor(path: string) {
     this.db = new Database(path, { create: true });
+    this.db.run(`PRAGMA busy_timeout = ${HUB_DB_BUSY_TIMEOUT_MS}`);
     this.db.run("PRAGMA journal_mode = WAL");
     this.db.run(`CREATE TABLE IF NOT EXISTS tasks (
       id INTEGER PRIMARY KEY AUTOINCREMENT, title TEXT NOT NULL, detail TEXT NOT NULL DEFAULT '', class TEXT NOT NULL,

package/src/hub/budget.ts

@@ -1,5 +1,6 @@
 import { Database } from "bun:sqlite";
 import type { PeerId } from "./envelope.ts";
+import { HUB_DB_BUSY_TIMEOUT_MS } from "./db-timeout.ts";
 
 export interface UsageWindow {
   id: "5h" | "week" | "tokens";
@@ -80,10 +81,12 @@ const EXEMPT = new Set<PeerId>(["local", "user", "hub"]);
 export class Budget {
   private readonly db: Database;
   private readonly readings = new Map<PeerId, Map<string, Reading>>();
-  private readonly pausing = new Set<PeerId>();
+  private readonly pausing = new Map<PeerId, object>();
   private readonly handingOff = new Set<PeerId>();
   /** `ahub budget resume`: the owner overrode a pause; readings over the gate are ignored for that peer until then. */
   private readonly ignoreUntil = new Map<PeerId, number>();
+  /** Chosen fallback bounds belong to a window, never to every window of the peer. */
+  private readonly resetBounds = new Map<PeerId, Map<string, { at: number; explicit: boolean }>>();
   private closed = false;
   private recoveryHeld = false;
   private deferred = false;
@@ -96,6 +99,7 @@ export class Budget {
     private readonly now: () => number = Date.now,
   ) {
     this.db = new Database(dbPath, { create: true });
+    this.db.run(`PRAGMA busy_timeout = ${HUB_DB_BUSY_TIMEOUT_MS}`);
     this.db.run(`CREATE TABLE IF NOT EXISTS budget_pauses (peer TEXT PRIMARY KEY, since INTEGER NOT NULL, resets_at INTEGER NOT NULL,
       reason TEXT NOT NULL, summary TEXT, handed_off INTEGER NOT NULL DEFAULT 0, moved TEXT NOT NULL DEFAULT '[]')`);
   }
@@ -153,6 +157,10 @@ export class Budget {
   /** `at`: when the numbers were measured, for sources that arrive through a file (a leftover file is not a fresh reading). */
   report(peer: PeerId, windows: UsageWindow[], hard = false, at = this.now()): void {
     if (EXEMPT.has(peer) || this.closed) return;
+    // An override ignores soft readings, not a provider that has actually refused another turn.
+    if (hard && this.ignoreUntil.delete(peer)) {
+      try { this.hooks.notify(`budget: ${peer} provider refused again; budget override ended`); } catch { /* a notice cannot prevent the hard pause */ }
+    }
     try { this.hooks.reading?.(peer, windows, hard, at); } catch { /* telemetry never costs a reading */ }
     const mine = this.readings.get(peer) ?? new Map<string, Reading>();
     this.readings.set(peer, mine);
@@ -172,7 +180,10 @@ export class Budget {
     const open = this.record(peer);
     if (!open) return false;
     this.ignoreUntil.set(peer, open.resetsAt);
+    const bounds = this.resetBounds.get(peer);
     this.resume(peer, "overridden by the console user");
+    // A new refusal may end the override before this same window has reset.
+    if (bounds) this.resetBounds.set(peer, bounds);
     return true;
   }
 
@@ -181,8 +192,14 @@ export class Budget {
     const fresh = this.fresh(peer);
     const over = fresh.filter((r) => r.used >= this.cfg.gate);
     const open = this.record(peer);
-    if (open) {
+    // An expired restored record may be waiting for attachment on an unpaused bus. A new hard refusal
+    // starts a fresh pause immediately, retaining its list of moved tasks for the eventual resume notice.
+    if (open && !(hard && this.now() >= open.resetsAt)) {
+      if (hard && over.length) this.hooks.pause(peer); // confirm the persisted pause on the live bus, too
       // A later reading may finally carry the reset time the first one lacked.
+      const bounds = this.resetBounds.get(peer) ?? new Map<string, { at: number; explicit: boolean }>();
+      this.resetBounds.set(peer, bounds);
+      for (const reading of over) if (reading.resetsAt !== undefined) bounds.set(reading.id, { at: reading.resetsAt, explicit: true });
       const known = Math.max(0, ...over.map((r) => r.resetsAt ?? 0));
       if (known && known !== open.resetsAt) {
         // A wait was decided against the old reset (#36). If the new one is past wait_max_min (a week window crossed
@@ -199,22 +216,36 @@ export class Budget {
       if (newer.length && fresh.every((r) => r.used < this.cfg.gate - HYSTERESIS)) this.resume(peer, "usage is back under the gate");
       return;
     }
-    if (!over.length || this.pausing.has(peer) || this.now() < (this.ignoreUntil.get(peer) ?? 0)) return;
-    this.pausing.add(peer);
+    if (!over.length || (this.pausing.has(peer) && !hard) || this.now() < (this.ignoreUntil.get(peer) ?? 0)) return;
+    // A hard refusal supersedes a soft evaluation still awaiting its checkpoint.
+    const evaluation = {};
+    this.pausing.set(peer, evaluation);
     try {
       const worst = over.reduce((a, b) => (b.used > a.used ? b : a));
-      const resetsAt = Math.max(...over.map((r) => r.resetsAt ?? this.now() + (r.windowMins ?? FALLBACK_WINDOW_MINS) * 60_000));
+      const bounds = this.resetBounds.get(peer) ?? new Map<string, { at: number; explicit: boolean }>();
+      this.resetBounds.set(peer, bounds);
+      const resetsAt = Math.max(...over.map((r) => {
+        const fallback = this.now() + (r.windowMins ?? FALLBACK_WINDOW_MINS) * 60_000;
+        const prior = bounds.get(r.id);
+        // Preserve an earlier future fallback for this window after an override.
+        // A provider's explicit reset, including a later one, remains authoritative.
+        const retained = prior !== undefined && prior.at > this.now() ? prior : undefined;
+        const reset = r.resetsAt ?? (retained ? retained.explicit ? retained.at : Math.min(retained.at, fallback) : fallback);
+        bounds.set(r.id, { at: reset, explicit: r.resetsAt !== undefined || retained?.explicit === true });
+        return reset;
+      }));
       const reason = `${worst.id} window at ${Math.round(worst.used * 100)}% (${worst.source})`;
       // Checkpoint first, pause second: a paused peer receives nothing, and a turn in flight is never cut by the coordinator.
       const summary = hard ? undefined : await this.hooks.requestCheckpoint(peer).catch(() => undefined);
+      if (this.pausing.get(peer) !== evaluation) return; // a later hard evaluation owns this pause
       if (this.recoveryHeld) { this.deferred = true; return; }
       if (this.closed) return; // the hub is shutting down: nothing is recorded, the next run sees the reading again
-      this.db.query("INSERT OR REPLACE INTO budget_pauses (peer, since, resets_at, reason, summary) VALUES (?, ?, ?, ?, ?)").run(peer, this.now(), resetsAt, reason, summary ?? null);
+      this.db.query("INSERT OR REPLACE INTO budget_pauses (peer, since, resets_at, reason, summary, moved) VALUES (?, ?, ?, ?, ?, ?)").run(peer, this.now(), resetsAt, reason, summary ?? null, JSON.stringify(open?.moved ?? []));
       this.hooks.pause(peer);
       this.hooks.notify(`budget: ${peer} paused, ${reason}; resumes ${new Date(resetsAt).toLocaleTimeString()}${summary ? "; checkpoint received" : hard ? "; hard limit, no checkpoint" : "; no checkpoint"}`);
       await this.finishHandoff(peer, summary);
     } finally {
-      this.pausing.delete(peer);
+      if (this.pausing.get(peer) === evaluation) this.pausing.delete(peer);
     }
   }
 
@@ -285,6 +316,7 @@ export class Budget {
     if (!record) return;
     this.db.query("DELETE FROM budget_pauses WHERE peer = ?").run(peer);
     this.readings.get(peer)?.clear(); // the old numbers describe the window that just ended
+    this.resetBounds.delete(peer);
     // The notice is queued while the peer is still paused, so it leads the first delivery: the peer learns what moved
     // before it touches anything that was waiting for it.
     this.hooks.resumed(record);

package/src/hub/bus.ts

@@ -1,12 +1,8 @@
 import { appendNote, DIGEST, HUB, keepNotes, MAX_HOP, newEnvelope, noteLine, parseMarker, quoteNotes, replyAudience, type Envelope, type EnvelopeOpts, type PeerId, type PeerState, type Priority } from "./envelope.ts";
-import type { PeerAdapter } from "./peers.ts";
+import type { PeerAdapter, DeliveryReceipt } from "./peers.ts";
 import { DeliveryJournal, type JournalDelivery, type JournalDeliveryState } from "./delivery-journal.ts";
 
-export interface DeliveryReceipt {
-  id: string;
-  state: "accepted" | "completed" | "failed_safe" | "needs_review";
-  reason?: string;
-}
+export type { DeliveryReceipt } from "./peers.ts";
 
 export type BusEvent =
   | { t: "envelope"; env: Envelope; dropped?: "hop" | "fyi" }
@@ -17,6 +13,8 @@ export type BusEvent =
   | { t: "state"; peer: PeerId; state: PeerState };
 
 export interface BusOptions {
+  /** Transient owner lifecycle fence: retain new work without changing console/budget pauses. */
+  deliveryHeld?: (peer: PeerId) => boolean;
   /** Observe original envelopes immediately before a transport starts its turn. */
   onDeliver?: (peer: PeerId, originals: Envelope[]) => void;
   retryMs: number;
@@ -193,7 +191,7 @@ export class Bus {
       if (hushed.length) this.note(peer.id, noteLine(HUB, "decision", `your message was not delivered to ${hushed.map((h) => h.peer).join(", ")}: ${hushed[0]!.reason}`));
       return heldBack ? hushed[0]!.reason : undefined;
     };
-    peer.onFailed = (envs) => {
+    peer.onFailed = (envs, failure) => {
       // The adapter got the condensed list; what has to come back is what that list replaced.
       const last = this.lastDelivery.get(peer.id);
       const same = !!last && envs.length === last.out.length && envs.every((e, i) => e.id === last.out[i]!.id);
@@ -205,7 +203,7 @@ export class Bus {
             this.deliveryReceipt(peer.id, { id: deliveryId, state: "needs_review", reason: "adapter reported delivery failure without safe-failure evidence" });
           }
         }
-      } else this.failed(peer.id, same ? last.originals : envs);
+      } else this.failed(peer.id, same ? last.originals : envs, undefined, failure?.quota === true);
     };
     peer.onState = () => {
       if (this.closed) return;
@@ -421,7 +419,7 @@ export class Bus {
     this.journal.transition(id, state, receipt.reason);
     if (before?.state === "dispatching" && (state === "accepted" || state === "completed")) this.delivered(peer, before.originals);
     if (state === "failed") {
-      if (before) this.failed(peer, before.originals, before.originals.some((e) => e.private) ? "private delivery failed" : receipt.reason);
+      if (before) this.failed(peer, before.originals, before.originals.some((e) => e.private) ? "private delivery failed" : receipt.reason, receipt.quota === true && before.state === "dispatching");
     }
     if (state === "completed") { this.failureStreak.delete(peer); this.lastFailure.delete(peer); }
     if (state === "completed" || state === "failed" || state === "needs_review") this.activeDeliveries.delete(id);
@@ -548,7 +546,7 @@ export class Bus {
     try { for (const id of targets) {
       const peer = this.peers.get(id);
       if (!peer) { this.enqueue(id, env); continue; }
-      if (!this.journal && !this.recoveryHeld && !this.recoveryHeldPeers.has(id) && env.priority === "important" && peer.steer && this.stateOf(id) === "busy") {
+      if (!this.journal && !this.recoveryHeld && !this.recoveryHeldPeers.has(id) && !this.opts.deliveryHeld?.(id) && env.priority === "important" && peer.steer && this.stateOf(id) === "busy") {
         // Not queued while the steer is in flight, or an idle transition would deliver it a second time.
         this.steering++;
         const deliveryId = crypto.randomUUID();
@@ -568,7 +566,7 @@ export class Bus {
       this.onQueues?.();
       for (const id of targets) {
         const peer = this.peers.get(id);
-        if (!this.recoveryHeld && !this.recoveryHeldPeers.has(id) && env.priority === "important" && peer?.steer && this.stateOf(id) === "busy") void this.steerQueued(id, env);
+        if (!this.recoveryHeld && !this.recoveryHeldPeers.has(id) && !this.opts.deliveryHeld?.(id) && env.priority === "important" && peer?.steer && this.stateOf(id) === "busy") void this.steerQueued(id, env);
         else void this.drain(id);
       }
     }
@@ -732,7 +730,7 @@ export class Bus {
 
   /** Holds on a peer's queue, for a drain and a pull alike: recovery, an uncertain delivery, a pause (console, budget, conductor). */
   private held(id: PeerId): boolean {
-    return this.recoveryHeld || this.recoveryHeldPeers.has(id) || this.paused.has(id);
+    return this.recoveryHeld || this.recoveryHeldPeers.has(id) || this.paused.has(id) || this.opts.deliveryHeld?.(id) === true;
   }
 
   /** What a peer was just handed stays resolvable for `reply_to`: moved to the newest end, the stored envelope kept. */
@@ -904,10 +902,12 @@ export class Bus {
     return [...this.activeDeliveries.values()].includes(peer) || this.draining.has(peer);
   }
 
-  private failed(id: PeerId, envs: Envelope[], reason = "delivery failed without an error detail"): void {
+  private failed(id: PeerId, envs: Envelope[], reason = "delivery failed without an error detail", quota = false): void {
     if (!this.journal) this.deliveryFailed(id);
+    // A quota refusal ran no work. The budget pause fences retries until reset; it is not a poison attempt.
+    const quotaPaused = quota && this.paused.has(id);
     this.lastFailure.set(id, reason.replace(/\s+/g, " ").slice(0, 300));
-    if (envs.some((env) => !(env.from === HUB && env.kind === "presence") && (this.attempts.get(`${id}:${env.id}`) ?? 0) + 1 >= MAX_ATTEMPTS)) {
+    if (!quotaPaused && envs.some((env) => !(env.from === HUB && env.kind === "presence") && (this.attempts.get(`${id}:${env.id}`) ?? 0) + 1 >= MAX_ATTEMPTS)) {
       this.failureStreak.set(id, (this.failureStreak.get(id) ?? 0) + 1);
     }
     const keep = envs.filter((env) => {
@@ -916,6 +916,7 @@ export class Bus {
         this.restorePreface(id, env); // rides again on the next delivery, without counting as a failed envelope
         return false;
       }
+      if (quotaPaused) return true;
       const key = `${id}:${env.id}`;
       const n = (this.attempts.get(key) ?? 0) + 1;
       if (n < MAX_ATTEMPTS) return this.attempts.set(key, n);

package/src/hub/child-process.ts

@@ -11,6 +11,17 @@ export function childEnv(source: NodeJS.ProcessEnv = process.env): NodeJS.Proces
   return env;
 }
 
+/**
+ * #269: the environment of a terminal the hub opens for a person: no agent marker and no hub-run flag, so `ahub`
+ * typed or started there has the console's identity, whatever started the hub.
+ */
+export function personEnv(source: NodeJS.ProcessEnv = process.env): NodeJS.ProcessEnv {
+  const env = childEnv(source);
+  // The Orca terminal the hub itself was started in is not this new terminal: a launch there must not record it as its own.
+  for (const name of ["CLAUDECODE", "CLAUDE_CODE_SESSION_ID", "CODEX_THREAD_ID", "AGENTHUB_CHANNEL", "AGENTHUB_PEER_ID", "AGENTHUB_UNATTENDED", "ORCA_TERMINAL_HANDLE", "ORCA_WORKTREE_ID"]) delete env[name];
+  return env;
+}
+
 /** Every native child owns its marker; caller vendor markers must not leak across peers (#193). */
 export function peerChildEnv(peer: string, source: NodeJS.ProcessEnv = process.env): NodeJS.ProcessEnv {
   const env = childEnv(source);

package/src/hub/conductor.ts

@@ -4,9 +4,11 @@ import { CONDUCTOR_TOOL_NAMES } from "./hub-tools.ts";
 import { HUB, USER } from "./envelope.ts";
 import { OWNERSHIP_EVENTS } from "./tasks.ts";
 import { PreEffectToolRefusal } from "./tool-refusal.ts";
+import { isStartablePeer, type StartablePeer, type StartMode } from "./start-mode.ts";
 import type { HubEvent } from "./events.ts";
 import type { SupervisionFeed } from "./supervision.ts";
 import type { Budget } from "./budget.ts";
+import { HUB_DB_BUSY_TIMEOUT_MS } from "./db-timeout.ts";
 
 /** The production ProgressObserver sink forwards structured verdicts, never its observations/reasoning. */
 export function conductorProgressSink(record: (event: HubEvent) => void, feed: Pick<SupervisionFeed, "milestone">): (event: HubEvent) => void {
@@ -65,6 +67,7 @@ export class ConductorHolds {
   private readonly db: Database;
   constructor(dbPath: string, private readonly now: () => number = Date.now) {
     this.db = new Database(dbPath, { create: true });
+    this.db.run(`PRAGMA busy_timeout = ${HUB_DB_BUSY_TIMEOUT_MS}`);
     this.db.run("CREATE TABLE IF NOT EXISTS conductor_holds (peer TEXT PRIMARY KEY, actor TEXT NOT NULL, since INTEGER NOT NULL)");
     this.db.run("CREATE TABLE IF NOT EXISTS supervision_rounds (peer TEXT PRIMARY KEY, signature TEXT NOT NULL)");
   }
@@ -100,13 +103,18 @@ export class ConductorHolds {
   close(): void { this.db.close(); }
 }
 
-export type ConductorStart = { peer: "local" | "kimi" | "pi"; mode: "headless" } | { peer: "claude" | "codex" | "pi"; mode: "tui"; command: string };
-/** Preview commands come from the same launch planner the CLI uses, never caller-supplied shell text. */
-export function conductorStart(peer: unknown, mode: unknown, preview: (peer: "claude" | "codex" | "pi") => string, preEffect = false): ConductorStart {
-  if (mode !== undefined && mode !== "headless" && mode !== "tui") throw new (preEffect ? PreEffectToolRefusal : Error)("mode must be headless or tui");
-  if (peer === "claude" || peer === "codex" || (peer === "pi" && mode === "tui")) return { peer, mode: "tui", command: preview(peer) };
-  if ((peer === "local" || peer === "kimi" || peer === "pi") && mode !== "tui") return { peer, mode: "headless" };
-  throw new (preEffect ? PreEffectToolRefusal : Error)("only local, kimi and headless pi may be started by the conductor");
+export type ConductorStart = { peer: StartablePeer; mode: "headless" } | { peer: "claude" | "codex" | "pi"; mode: "tui"; command: string };
+/**
+ * What a conductor's start of `peer` is (#269): the peer's own start mode, which a person sets. A `mode` argument may
+ * only repeat it. Preview commands come from the same launch planner the CLI uses, never caller-supplied shell text.
+ */
+export function conductorStart(peer: unknown, mode: unknown, preview: (peer: "claude" | "codex" | "pi") => string, preEffect: boolean, startMode: (peer: StartablePeer) => StartMode): ConductorStart {
+  const refuse = (text: string) => new (preEffect ? PreEffectToolRefusal : Error)(text);
+  if (mode !== undefined && mode !== "headless" && mode !== "tui") throw refuse("mode must be headless or tui");
+  if (!isStartablePeer(peer)) throw refuse("only claude, codex, kimi, pi and local may be started by the conductor");
+  const own = startMode(peer);
+  if (mode !== undefined && mode !== own) throw refuse(`${peer} starts ${own} here; a person sets a start mode (ahub settings), the conductor cannot choose one`);
+  return own === "tui" ? { peer: peer as "claude" | "codex" | "pi", mode: "tui", command: preview(peer as "claude" | "codex" | "pi") } : { peer, mode: "headless" };
 }
 
 const numberOrNull = (v: unknown): number | null => typeof v === "number" && Number.isFinite(v) && v >= 0 ? v : null;
@@ -151,7 +159,10 @@ export interface ConductorHooks {
   assign(actor: string, id: number, peer: string): Promise<unknown>;
   escalate(actor: string, id: number): Promise<unknown>;
   preview(peer: "claude" | "codex" | "pi"): string;
-  start(peer: "local" | "kimi" | "pi"): Promise<unknown>;
+  /** The mode a start of this peer takes: a person's setting. */
+  startMode(peer: StartablePeer): StartMode;
+  /** Starts the peer in that mode: headless at once, or its fixed command in a terminal; throws with the command to run by hand when no terminal can be opened. */
+  start(peer: StartablePeer): Promise<unknown>;
   known(peer: string): boolean;
   pause(peer: string): void;
   validateRelease?(peer: string): Promise<void>;
@@ -211,9 +222,10 @@ export class Conductor {
       return updated ? publicConductorTask(updated, this.hooks.publicView) : { id: task.id };
     }
     if (tool === "hub_peer_start") {
-      const start = conductorStart(args.peer, args.mode, this.hooks.preview, true);
-      if (start.mode === "headless") await this.hooks.start(start.peer);
-      emit({ peer: start.peer }); return start;
+      const start = conductorStart(args.peer, args.mode, this.hooks.preview, true, this.hooks.startMode);
+      const result = await this.hooks.start(start.peer);
+      const opened = result && typeof result === "object" && typeof (result as { opened?: unknown }).opened === "string" ? { opened: (result as { opened: string }).opened } : {};
+      emit({ peer: start.peer }); return { ...start, ...opened };
     }
     const peer = peerId(args.peer, true);
     if (!this.hooks.known(peer)) throw new PreEffectToolRefusal(`unknown peer: ${peer}`);

package/src/hub/config-trust.ts

@@ -1,7 +1,7 @@
-import { spawnSync } from "node:child_process";
 import { statSync } from "node:fs";
 import { join } from "node:path";
 import { childEnv } from "./child-process.ts";
+import { hubGitSync } from "./git.ts";
 
 /**
  * Fields of the project config that choose what the hub runs, which files it sends as credentials, where task text
@@ -26,6 +26,7 @@ export const MACHINE_LOCAL = [
   "local.read_allow",
   "local.bash_network",
   "local.network_allow", // the hosts the egress proxy opens (#65)
+  "terminal.open", // the command a hub-made TUI start runs to open a terminal (#269)
 ] as const;
 
 /**
@@ -35,17 +36,28 @@ export const MACHINE_LOCAL = [
  * spellings git keeps apart (letter case, and folds such as "ſ" for "s").
  */
 export function configRefusal(cwd: string, name: string): string | undefined {
-  const r = spawnSync("git", ["-C", cwd, "ls-files", "-s", "-z", "--", ":(icase).agenthub"], { encoding: "utf8", env: childEnv(process.env) });
-  if (r.status !== 0) return `git could not confirm that .agenthub/${name} is untracked`;
+  const tracked = configTracked(cwd, name);
+  return tracked === undefined ? `git could not confirm that .agenthub/${name} is untracked` : tracked ? `.agenthub/${name} is committed to git` : undefined;
+}
+
+/** Whether git tracks `.agenthub/<name>` (or `.agenthub` itself); undefined when git cannot say. */
+export function configTracked(cwd: string, name: string): boolean | undefined {
+  const r = hubGitSync(["-C", cwd, "ls-files", "-s", "-z", "--", ":(icase).agenthub"], { encoding: "utf8", env: childEnv(process.env) });
+  if (r.status !== 0) return undefined;
   let opened: { dev: number; ino: number } | undefined;
   try {
     opened = statSync(join(cwd, ".agenthub", name));
   } catch {
     // not there: only the directory entry can still matter
   }
-  const tracked = r.stdout.split("\0").filter(Boolean).some((row) => {
+  return r.stdout.split("\0").filter(Boolean).some((row) => {
     const path = row.slice(row.indexOf("\t") + 1);
     if (path.toLowerCase() === ".agenthub") return true;
+    // A file that is not there has no identity to match: the index entry of this exact name is the one a write would
+    // change. Another spelling is another file where the disk keeps them apart.
+    // ponytail: on a disk that folds names, an entry tracked under another spelling and deleted from the work tree is
+    // not seen here; probe the disk's folding and compare folded names if that case ever matters.
+    if (!opened) return path === `.agenthub/${name}`;
     try {
       const s = statSync(join(cwd, path));
       return !!opened && s.dev === opened.dev && s.ino === opened.ino;
@@ -53,7 +65,6 @@ export function configRefusal(cwd: string, name: string): string | undefined {
       return false;
     }
   });
-  return tracked ? `.agenthub/${name} is committed to git` : undefined;
 }
 
 const valueAt = (o: unknown, path: string): unknown => path.split(".").reduce<unknown>((v, k) => (v && typeof v === "object" ? (v as Record<string, unknown>)[k] : undefined), o);

package/src/hub/conflicts.ts

@@ -2,6 +2,7 @@ import { Database } from "bun:sqlite";
 import { existsSync } from "node:fs";
 import type { Task } from "./board.ts";
 import { samePlace } from "./tasks.ts";
+import { HUB_DB_BUSY_TIMEOUT_MS } from "./db-timeout.ts";
 
 /** A file an owner's open task changed, as the turn snapshots saw it (issue #32). */
 export interface Touch {
@@ -39,6 +40,7 @@ export function pathWarnings(dbFile: string, peer: string, file: { project: stri
   if (!existsSync(dbFile)) return [];
   const db = new Database(dbFile, { readonly: true });
   try {
+    db.run(`PRAGMA busy_timeout = ${HUB_DB_BUSY_TIMEOUT_MS}`);
     const rows = db.query("SELECT * FROM tasks WHERE owner IS NOT NULL AND owner != ? AND state IN ('proposed', 'in_progress', 'in_review', 'changes_requested') ORDER BY id").all(peer) as Record<string, string | number | null>[];
     let touches: Touch[] = [];
     try {

package/src/hub/context-window.ts

@@ -1,6 +1,6 @@
 /** Native active-context occupancy, separate from accumulated billable usage (#185). */
 export interface ContextReading {
-  source: "claude_statusline" | "codex_token_usage";
+  source: "claude_statusline" | "codex_token_usage" | "acp_usage_update";
   sessionId: string;
   measuredAt: number;
   tokens: number | null;
@@ -37,6 +37,13 @@ export function codexContext(value: unknown, sessionId: string, measuredAt: numb
   const tokens = nonnegative(last.totalTokens) ? last.totalTokens : null;
   return { source: "codex_token_usage", sessionId, measuredAt, tokens, window, used: tokens !== null && window !== null ? Math.min(1, tokens / window) : null };
 }
+/** An ACP `usage_update` of the `{ used, size }` shape (Kimi 2.x): context occupancy, not consumption (#167, #285). */
+export function acpContext(usage: { used: number; size: number }, sessionId: string, measuredAt: number): ContextReading {
+  const window = positive(usage.size) ? usage.size : null;
+  const tokens = nonnegative(usage.used) ? usage.used : null;
+  // If a report ever shows used > size, the fraction clamps so a bar renders; tokens keeps the reported number.
+  return { source: "acp_usage_update", sessionId, measuredAt, tokens, window, used: tokens !== null && window !== null ? Math.min(1, tokens / window) : null };
+}
 export const unknownContext = (): ContextView => ({ source: null, measuredAt: null, tokens: null, window: null, used: null, freshness: "unknown" });
 /** Invalid/stale readings hide the value but never rearm a threshold already crossed. */
 export class ContextWindows {

package/src/hub/crash.ts

@@ -72,7 +72,8 @@ export function crashPlan(records: SessionRecord[]): { peer: string; resume?: Re
         const fresh: Record<string, string> = {};
         for (const k of ["backend", "model"] as const) if (str(launch[k])) fresh[k] = str(launch[k])!;
         const sessionFile = str(meta.sessionFile) ?? str(launch.sessionFile);
-        if (!sessionFile) return { peer, fresh, how: "pi: no session file was recorded; start it again with ahub pi" };
+        // #269: a terminal Pi stays marked as one without a session file too, so nothing headless is started in its place.
+        if (!sessionFile) return { peer, fresh, ...(str(launch.mode) === "tui" ? { tui: true } : {}), how: "pi: no session file was recorded; start it again with ahub pi" };
         // A terminal Pi is run by the CLI that launched it, not by the hub: nothing here could start it again.
         if (str(launch.mode) === "tui") return { peer, fresh, tui: true, how: `pi: it ran in a terminal; start it again with ahub pi --mode tui --session-file ${sessionFile}` };
         const args: Record<string, string> = { sessionFile };