@staix/agent-hub 0.12.22 → 0.12.24

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" }
@@ -14,9 +10,12 @@ export type BusEvent =
   | { t: "undeliverable"; env: Envelope; peer: PeerId; reason?: string }
   | { t: "stale"; env: Envelope; peer: PeerId; reason: string }
   | { t: "quiet"; env: Envelope; peers: PeerId[]; reason: string }
+  | { t: "off_roster"; env: Envelope; peers: PeerId[] }
   | { t: "state"; peer: PeerId; state: PeerState };
 
 export interface BusOptions {
+  /** Live project membership; absent preserves the existing audience and delivery behaviour. */
+  rostered?: (peer: PeerId) => boolean;
   /** 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. */
@@ -159,6 +158,7 @@ export class Bus {
     if (!this.queues.has(peer.id)) this.queues.set(peer.id, []);
     peer.onDelivery = (receipt) => this.deliveryReceipt(peer.id, receipt);
     peer.onMessage = (text, opts) => {
+      if (!this.isRostered(peer.id)) return `off roster: ${peer.id}`;
       const { priority, body } = parseMarker(text);
       if (!body) return;
       // What the peer was handed differs from what it stands for once a delivery was condensed; both the audience
@@ -171,15 +171,22 @@ export class Bus {
       const audienceOriginals = originals ?? (opts?.to?.includes(DIGEST) && condensed ? last?.originals : undefined);
       const to = opts?.to?.length ? resolveTo(opts.to, audienceOriginals) : undefined;
       let env = newEnvelope(peer.id, body, { ...opts, ...(to ? { to } : {}), priority: opts?.priority ?? capPriority(peer, priority, opts?.inReplyTo, originals) });
+      const offRoster = this.offRosterRecipients(env);
+      if (offRoster.length && offRoster.length === new Set(env.to?.filter(id => id !== env.from)).size) {
+        const reason = `off roster: ${offRoster.join(", ")}`;
+        this.note(peer.id, noteLine(HUB, "decision", `your message was not delivered: ${reason}`));
+        return reason; // no publication and no limiter spend for an entirely refused audience
+      }
+      const admittedEnv = offRoster.length ? { ...env, to: env.to!.filter(id => !offRoster.includes(id)) } : env;
       // Limits count what is sent: the envelope as built (a reply goes to its parent's sender, `digest` is resolved,
       // the priority is capped), never the raw `to`.
       const parent = opts?.inReplyTo?.id;
       // Held back from every recipient (issue #107): nothing goes out, so nothing counts against the sender's limits.
       const hushed = this.hushed(env);
       const heldBack = hushed.length > 0 && hushed.length === this.audience(env).length;
-      let refused = heldBack ? undefined : this.opts.admit?.(env, parent);
+      let refused = heldBack ? undefined : this.opts.admit?.(admittedEnv, parent);
       // A turn answer has no caller to refuse: over its important budget it goes out as status, not at all.
-      if (refused && env.priority === "important" && !this.opts.admit?.({ ...env, priority: "status" }, parent)) {
+      if (refused && env.priority === "important" && !this.opts.admit?.({ ...admittedEnv, priority: "status" }, parent)) {
         // It went out, so the advice on how to send it does not apply.
         this.note(peer.id, noteLine(HUB, "decision", `your [IMPORTANT] message went out as status: ${refused.replace(/[;:] (retry after \d+ s, or )?send it without \[IMPORTANT\]$/, "")}`));
         env = { ...env, priority: "status" };
@@ -190,12 +197,13 @@ export class Bus {
         return refused;
       }
       this.publish(env);
+      if (offRoster.length) this.note(peer.id, noteLine(HUB, "decision", `your message is retained off roster for ${offRoster.join(", ")}; delivered to the other recipients`));
       // The sender's result (issue #107): a turn answer has no caller, so it hears it on its next delivery. It counts as
       // not sent only when nobody got it.
       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);
@@ -207,7 +215,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;
@@ -423,7 +431,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);
@@ -470,6 +478,17 @@ export class Bus {
     return (this.queues.get(id) ?? []).map((e) => e.id);
   }
 
+  queuedBacklogIds(id: PeerId): Set<number> {
+    const ids = new Set<number>();
+    const retained = [...(this.queues.get(id) ?? []), ...(this.journal?.unresolved(id).filter(row => row.state !== "queued").flatMap(row => row.originals) ?? [])];
+    for (const env of retained) {
+      const backlog = env.refs?.backlog;
+      if (env.from !== HUB || env.kind !== "task" || !Array.isArray(backlog) || backlog.length > 64) continue;
+      for (const task of backlog) if (Number.isSafeInteger(task) && task > 0) ids.add(task);
+    }
+    return ids;
+  }
+
   attemptState(): Record<string, number> {
     return Object.fromEntries(this.attempts);
   }
@@ -545,12 +564,12 @@ export class Bus {
 
     const hushed = this.hushed(env);
     if (hushed.length) this.emit({ t: "quiet", env, peers: hushed.map((h) => h.peer), reason: hushed[0]!.reason });
-    const targets = this.audience(env).filter((id) => !hushed.some((h) => h.peer === id));
+    const targets = this.audience(env).filter((id) => !hushed.some((h) => h.peer === id) || !this.isRostered(id));
     this.suppressDrain = !!this.journal;
     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) && !this.opts.deliveryHeld?.(id) && env.priority === "important" && peer.steer && this.stateOf(id) === "busy") {
+      if (!this.journal && !this.held(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();
@@ -570,23 +589,39 @@ export class Bus {
       this.onQueues?.();
       for (const id of targets) {
         const peer = this.peers.get(id);
-        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);
+        if (!this.held(id) && env.priority === "important" && peer?.steer && this.stateOf(id) === "busy") void this.steerQueued(id, env);
         else void this.drain(id);
       }
     }
+    const offRoster = targets.filter(id => !this.isRostered(id));
+    if (offRoster.length) this.emit({ t: "off_roster", env, peers: offRoster });
     return targets;
   }
 
+  isRostered(peer: PeerId): boolean { return this.opts.rostered?.(peer) ?? true; }
+
+  /** Explicit off-roster recipients, including unattached retained targets; broadcasts have none. */
+  offRosterRecipients(env: Envelope): PeerId[] {
+    return [...new Set(env.to ?? [])].filter(peer => peer !== env.from && !this.isRostered(peer));
+  }
+
+  /** Membership changed externally: reconsider delivery, keeping every independent hold intact. */
+  rosterChanged(peer: PeerId): void {
+    if (this.closed) return;
+    this.onQueues?.();
+    void this.drain(peer);
+  }
+
   /** Who an envelope is queued for: its `to`, or every peer but its sender. */
   audience(env: Envelope): PeerId[] {
     const known = new Set([...this.peers.keys(), ...this.queues.keys(), ...(this.journal?.list().map((d) => d.peer) ?? [])]);
-    return (env.to ?? [...this.peers.keys()]).filter((id) => id !== env.from && known.has(id));
+    return (env.to ?? [...this.peers.keys()]).filter((id) => id !== env.from && (known.has(id) || !this.isRostered(id)) && (env.to !== undefined || this.isRostered(id)));
   }
 
   /** The recipients of `env` that the silence policy holds it back from, each with why (issue #107). */
   hushed(env: Envelope): { peer: PeerId; reason: string }[] {
     if (!this.opts.silence || env.hop > MAX_HOP || env.priority === "fyi") return [];
-    return this.audience(env).flatMap((peer) => {
+    return this.audience(env).filter(peer => this.isRostered(peer)).flatMap((peer) => {
       const reason = this.opts.silence!(env, peer);
       return reason ? [{ peer, reason }] : [];
     });
@@ -732,9 +767,9 @@ export class Bus {
     finally { this.steering--; this.onQueues?.(); }
   }
 
-  /** Holds on a peer's queue, for a drain and a pull alike: recovery, an uncertain delivery, a pause (console, budget, conductor). */
+  /** Holds on a peer's queue, for a drain and a pull alike: off roster, 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) || this.opts.deliveryHeld?.(id) === true;
+    return !this.isRostered(id) || 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. */
@@ -906,10 +941,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) => {
@@ -918,6 +955,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/citations.ts

@@ -0,0 +1,7 @@
+/** Bounded Markdown [@key] and BibTeX entry-key example check, no fetching or model verdict. */
+export function citationKeys(markdown: string, bibliography: string): { cited: string[]; missing: string[] } {
+  if (Buffer.byteLength(markdown) > 256 * 1024 || Buffer.byteLength(bibliography) > 4 * 1024 * 1024) throw new Error("citation inputs exceed example check limits");
+  const known = new Set([...bibliography.matchAll(/@[a-zA-Z]+\s*\{\s*([^,\s{}]+)\s*,/g)].map(m => m[1]!));
+  const cited = [...new Set([...markdown.matchAll(/\[@[A-Za-z0-9_:./-]+(?:\s*;\s*@[A-Za-z0-9_:./-]+)*\]/g)].flatMap(m => [...m[0].matchAll(/@([A-Za-z0-9_:./-]+)/g)].map(k => k[1]!)))].sort();
+  return { cited, missing: cited.filter(key => !known.has(key)) };
+}

package/src/hub/conductor.ts

@@ -2,11 +2,13 @@ import { Database } from "bun:sqlite";
 import type { Task } from "./board.ts";
 import { CONDUCTOR_TOOL_NAMES } from "./hub-tools.ts";
 import { HUB, USER } from "./envelope.ts";
-import { OWNERSHIP_EVENTS } from "./tasks.ts";
+import { OWNERSHIP_EVENTS, type TaskAssignmentRole } 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, plus opt-in qwen/jcode, 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;
@@ -148,10 +156,13 @@ export interface ConductorHooks {
   task(id: number): Task | undefined;
   publicView(task: Task): Record<string, unknown>;
   /** These callbacks must call Tasks, never Board.update. */
-  assign(actor: string, id: number, peer: string): Promise<unknown>;
+  assign(actor: string, id: number, peer: string, role?: TaskAssignmentRole): 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>;
@@ -171,18 +182,20 @@ export class Conductor {
   constructor(private readonly holds: ConductorHolds, private readonly hooks: ConductorHooks) {}
   async execute(actor: string, tool: string, args: Record<string, unknown>): Promise<unknown> {
     if (!CONDUCTOR_TOOL_NAMES.has(tool)) throw new PreEffectToolRefusal("unknown conductor tool");
+    const role = args.role ?? "owner";
+    if (tool === "hub_task_assign" && role !== "owner" && role !== "reviewer") throw new PreEffectToolRefusal("role must be owner or reviewer");
     if ((tool === "hub_task_show" || tool === "hub_task_assign") && conductorPeer(this.hooks.roles()) !== actor) {
       const id = taskId(args.id);
       const task = id === undefined ? undefined : this.hooks.task(id);
       // A task's current owner and reviewer read its public view without the role (#208); nobody else does.
-      if (task && tool === "hub_task_show" && (task.owner === actor || task.reviewer === actor)) return publicConductorTask(task, this.hooks.publicView);
+      if (task && task.state !== "backlog" && tool === "hub_task_show" && (task.owner === actor || task.reviewer === actor)) return publicConductorTask(task, this.hooks.publicView);
       // Its proposer (the first history entry) redirects it while nobody ever accepted it (#207: a decline or a release puts
       // worked tasks back in proposed); work that waits gets a reserved owner. Never over the person: a console assign or
       // reservation stands until the conductor or the console moves it, also once the hub carried it out (the hub's own
       // moves are not decisions).
-      const moved = task?.history.findLast((h) => h.by !== HUB && (OWNERSHIP_EVENTS.has(h.event) || h.event === "reserved"));
+      const moved = task?.history.findLast((h) => h.by !== HUB && (OWNERSHIP_EVENTS.has(h.event) || h.event === "reserved" || h.planning?.fields.includes("reserved")));
       const accepted = task?.history.some((h) => h.event === "accepted");
-      if (task && tool === "hub_task_assign" && task.history[0]?.by === actor && task.state === "proposed" && !accepted && moved?.by !== USER) {
+      if (task && tool === "hub_task_assign" && role === "owner" && task.history[0]?.by === actor && task.state === "proposed" && !accepted && moved?.by !== USER) {
         const peer = peerId(args.peer, true);
         if (peer !== actor) requireAssign(actor, this.hooks.capabilities(), true);
         await this.hooks.assign(actor, task.id, peer);
@@ -201,19 +214,23 @@ export class Conductor {
       if (id === undefined) throw new PreEffectToolRefusal("id must be a positive integer");
       const task = this.hooks.task(id);
       if (!task) throw new PreEffectToolRefusal(`no task #${args.id}`);
+      if (task.state === "backlog") throw new PreEffectToolRefusal("backlog is read through planner tools, not conductor task tools");
       if (tool === "hub_task_show") { const result = publicConductorTask(task, this.hooks.publicView); emit({ task: task.id }); return result; }
       if (tool === "hub_task_assign") {
         const peer = peerId(args.peer, true);
-        await this.hooks.assign(actor, task.id, peer); emit({ task: task.id, peer });
+        if (role === "reviewer") await this.hooks.assign(actor, task.id, peer, role);
+        else await this.hooks.assign(actor, task.id, peer);
+        emit({ task: task.id, peer });
       } else { await this.hooks.escalate(actor, task.id); emit({ task: task.id }); }
       // Task callbacks may return raw objects; always re-read and apply the public view.
       const updated = this.hooks.task(task.id);
       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,7 +26,10 @@ 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;
+/** Legacy exported field list stays compatible; new policies use the complete list below. */
+export const ALL_MACHINE_LOCAL = [...MACHINE_LOCAL, "protect_instruction_files", "qwen_cmd", "jcode_cmd", "jcode_home", "jcode_provider_profile", "text_projection"] as const;
 
 /**
  * Why `.agenthub/<name>` must not set machine-local fields, or undefined when git confirms nobody committed it.
@@ -35,17 +38,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 +67,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);
@@ -73,8 +86,8 @@ const drop = (file: Record<string, unknown>, path: string) => {
  * once resolved to the project root). A committed copy of the template sets them to defaults and asks git nothing.
  */
 export function stripUntrusted(file: Record<string, unknown>, defaults: object, cwd: string, name: string): string | undefined {
-  for (const p of MACHINE_LOCAL) if (valueAt(file, p) !== undefined && !chooses(valueAt(file, p))) drop(file, p);
-  const set = MACHINE_LOCAL.filter((p) => {
+  for (const p of ALL_MACHINE_LOCAL) if (valueAt(file, p) !== undefined && !chooses(valueAt(file, p))) drop(file, p);
+  const set = ALL_MACHINE_LOCAL.filter((p) => {
     const v = valueAt(file, p);
     return v !== undefined && JSON.stringify(v) !== JSON.stringify(valueAt(defaults, p));
   });

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

@@ -47,6 +47,8 @@ export function removeSessions(stateDir: string, instanceId?: string): void {
   if (instanceId === undefined || readSessions(stateDir)?.instanceId === instanceId) rmSync(fileOf(stateDir), { force: true });
 }
 
+export const qwenSessionId = (value: unknown): value is string => typeof value === "string" && /^[A-Za-z0-9][A-Za-z0-9._:-]{0,255}$/.test(value);
+
 const str = (v: unknown) => (typeof v === "string" && v ? v : undefined);
 
 /**
@@ -62,6 +64,13 @@ export function crashPlan(records: SessionRecord[]): { peer: string; resume?: Re
         return { peer, how: "claude: the Claude Code plugin reconnects by itself while that session is still open" };
       case "codex":
         return { peer, how: `codex: its app-server died with the hub; run ahub codex again${str(meta.threadId) ? ` (its conversation was thread ${meta.threadId})` : ""}` };
+      case "jcode":
+        return { peer, how: "jcode: native 0.94.0 load does not prove the restored id; reopen the original conversation with its native client, no automatic fresh replacement" };
+      case "qwen": {
+        const sessionId = meta.sessionId;
+        if (!qwenSessionId(sessionId)) return { peer, how: "qwen: saved ACP session identity unavailable; start it deliberately with ahub qwen" };
+        return { peer, resume: { sessionId, ...(model ? { model } : {}) }, how: "qwen: the recorded conversation can be loaded again (ACP session/load)" };
+      }
       case "kimi": {
         const sessionId = str(meta.sessionId);
         if (!sessionId) return { peer, how: "kimi: no session id was recorded; start it again with ahub kimi" };
@@ -72,7 +81,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 };