@staix/agent-hub 0.30.0 → 0.31.0

package/src/hub/completion-detail.ts

@@ -0,0 +1,50 @@
+/**
+ * #1054 T6: the detail line of a result, built at DISPLAY and never stored. A completion row keeps envelope ids only (`completions-store.ts`), so the head of the
+ * starting prompt is read from the envelope the bus still holds when the person looks, run through the hub's own screens, and thrown away after it is shown. Nothing here
+ * writes, logs or emits an event.
+ *
+ * Pure: the daemon passes the facts (the envelope it could resolve, whether the run was private, whether the text passed the hub's screens) and this decides what shows.
+ * A result with no readable envelope (the bus cache turned over, or the hub restarted) shows no detail: an honest absence, never a guess.
+ */
+
+/** The longest head of a prompt that is shown: one short line, enough to recognise the request. */
+export const PROMPT_HEAD_MAX = 120;
+
+/** What a detail line is, so a test and the page can tell a stub from a head from an absence. */
+export type ResultDetail =
+  | { kind: "head"; text: string }
+  | { kind: "stub"; text: string }
+  | { kind: "none" };
+
+export const PRIVATE_DETAIL = "a private request";
+export const WITHHELD_DETAIL = "request withheld by the privacy screen";
+
+/**
+ * The head of a prompt as one line: whitespace and control characters collapsed, cut by code point (half an emoji is invalid text), with an ellipsis when it was cut.
+ * A hub header forged in the body is quoted by `sanitize` at the caller, not here: this only shapes text.
+ */
+export function promptHead(body: string, max: number = PROMPT_HEAD_MAX): string {
+  const flat = body.replace(/[\u0000-\u001f\u007f-\u009f\u2028\u2029\s]+/g, " ").trim();
+  const points = Array.from(flat);
+  return points.length > max ? `${points.slice(0, Math.max(0, max - 1)).join("").trimEnd()}\u2026` : flat;
+}
+
+export interface DetailInput {
+  /** The run was private (a PII turn, or the peer held PII): its prompt is never shown. */
+  private: boolean;
+  /** The starting prompt's envelope body, when the bus could still resolve it. Absent: no detail. */
+  body?: string;
+  /** The hub's own screens (`boundedSafe`: secrets, PII patterns, private paths) cleared the head. Only asked for a non-private run with a body. */
+  safe?: (text: string) => boolean;
+}
+
+/** private -> stub (the body is never read); no body -> none; a head the screens refuse -> withheld stub; else the head. */
+export function resultDetail(input: DetailInput): ResultDetail {
+  if (input.private) return { kind: "stub", text: PRIVATE_DETAIL };
+  if (input.body === undefined) return { kind: "none" };
+  const head = promptHead(input.body);
+  if (!head) return { kind: "none" };
+  // Screen the whole bounded head, not a prefix of it: a pattern cut in half by the bound must not slip through as two harmless halves.
+  if (!input.safe || !input.safe(head) || !input.safe(input.body.slice(0, 4000))) return { kind: "stub", text: WITHHELD_DETAIL };
+  return { kind: "head", text: head };
+}

package/src/hub/completions-store.ts

@@ -0,0 +1,168 @@
+/**
+ * #1054 T2: the completions table in hub.db. Ids only, never a prompt or a reply: `prompt_envelope` and `reply_envelope` name envelopes the usual privacy path reads when a
+ * person looks. Three additive tables (no format bump): an older hub ignores them, which `Daemon` guards for recovery with the `completions` feature.
+ *
+ * - `completion_runs`: one row per OPEN run (a person started it, it has not settled). A restart settles each one `interrupted`.
+ * - `completions`: one row per settled run, keyed by the run's first turn id, so a repeated restart or a replayed settle can never make a second.
+ * - `completion_receipts`: created here for the next task (receipts); nothing writes it yet.
+ */
+import { openHubDatabase, type Database } from "./db-schema.ts";
+import { OUTCOMES, type Outcome, type Run } from "./completions.ts";
+
+export interface Completion {
+  id: string;
+  peer: string;
+  runTurn: string;
+  lastTurn: string;
+  outcome: Outcome;
+  settledAt: number;
+  startedAt: number;
+  promptEnvelope?: string;
+  replyEnvelope?: string;
+  private: boolean;
+}
+interface RawCompletion {
+  id: string; peer: string; run_turn: string; last_turn: string; outcome: string; settled_at: number; started_at: number;
+  prompt_envelope: string | null; reply_envelope: string | null; private: number;
+}
+const completionOf = (raw: RawCompletion): Completion => ({
+  id: raw.id, peer: raw.peer, runTurn: raw.run_turn, lastTurn: raw.last_turn, outcome: raw.outcome as Outcome, settledAt: raw.settled_at, startedAt: raw.started_at,
+  ...(raw.prompt_envelope ? { promptEnvelope: raw.prompt_envelope } : {}), ...(raw.reply_envelope ? { replyEnvelope: raw.reply_envelope } : {}), private: raw.private === 1,
+});
+
+/** An open run as the store keeps it: the ids a restart needs to settle it, nothing else. */
+export interface OpenRun { peer: string; runTurn: string; lastTurn: string; startedAt: number; promptEnvelope?: string; private: boolean }
+
+export class CompletionStore {
+  private readonly db: Database;
+  constructor(dbPath: string) {
+    this.db = openHubDatabase(dbPath, { create: true });
+    this.db.run(`CREATE TABLE IF NOT EXISTS completion_runs (
+      run_turn TEXT PRIMARY KEY, peer TEXT NOT NULL, last_turn TEXT NOT NULL, started_at INTEGER NOT NULL, prompt_envelope TEXT, private INTEGER NOT NULL DEFAULT 0)`);
+    this.db.run("CREATE UNIQUE INDEX IF NOT EXISTS completion_runs_by_peer ON completion_runs(peer)");
+    this.db.run(`CREATE TABLE IF NOT EXISTS completions (
+      id TEXT PRIMARY KEY, run_turn TEXT NOT NULL UNIQUE, peer TEXT NOT NULL, last_turn TEXT NOT NULL,
+      outcome TEXT NOT NULL CHECK (outcome IN (${OUTCOMES.map(outcome => `'${outcome}'`).join(",")})),
+      settled_at INTEGER NOT NULL, started_at INTEGER NOT NULL, prompt_envelope TEXT, reply_envelope TEXT, private INTEGER NOT NULL DEFAULT 0)`);
+    this.db.run("CREATE INDEX IF NOT EXISTS completions_by_peer ON completions(peer, settled_at)");
+    // Unread means no receipt. One receipt per completion at most (UNIQUE), so a double mark is one write and a mark-unread has exactly one row to delete.
+    this.db.run("CREATE TABLE IF NOT EXISTS completion_receipts (completion_id TEXT NOT NULL, seen_at INTEGER NOT NULL, surface TEXT NOT NULL)");
+    this.db.run("CREATE UNIQUE INDEX IF NOT EXISTS completion_receipts_by_completion ON completion_receipts(completion_id)");
+  }
+  close(): void { try { this.db.close(); } catch { /* already closed */ } }
+
+  /** Record an open run. One per peer: a second start for the same peer replaces nothing (the first run is still the run). */
+  openRun(run: Run): void {
+    this.db.query("INSERT OR IGNORE INTO completion_runs(run_turn, peer, last_turn, started_at, prompt_envelope, private) VALUES(?, ?, ?, ?, ?, ?)")
+      .run(run.runTurn, run.peer, run.lastTurn, run.startedAt, run.promptEnvelope ?? null, run.private ? 1 : 0);
+  }
+  /** A continuation moved the run's latest turn, or marked it private. */
+  touchRun(run: Run): void {
+    this.db.query("UPDATE completion_runs SET last_turn = ?, private = ? WHERE run_turn = ?").run(run.lastTurn, run.private ? 1 : 0, run.runTurn);
+  }
+  /** A run stopped quietly by the person, or one that never earned a completion: its row goes and nothing is created. */
+  dropRun(runTurn: string): void { this.db.query("DELETE FROM completion_runs WHERE run_turn = ?").run(runTurn); }
+  openRuns(): OpenRun[] {
+    return (this.db.query("SELECT * FROM completion_runs ORDER BY started_at, run_turn").all() as { run_turn: string; peer: string; last_turn: string; started_at: number; prompt_envelope: string | null; private: number }[])
+      .map(row => ({ peer: row.peer, runTurn: row.run_turn, lastTurn: row.last_turn, startedAt: row.started_at, ...(row.prompt_envelope ? { promptEnvelope: row.prompt_envelope } : {}), private: row.private === 1 }));
+  }
+
+  /**
+   * Settle a run: write its completion and remove its open row in one transaction. Keyed by the run's first turn id (`UNIQUE`), so a replay, a second restart or two callers
+   * racing on the same run yield exactly one completion; the loser gets undefined and creates nothing.
+   */
+  settle(run: OpenRun & { replyEnvelope?: string }, outcome: Outcome, now: number, id: string): Completion | undefined {
+    const write = this.db.transaction(() => {
+      const made = this.db.query(`INSERT OR IGNORE INTO completions(id, run_turn, peer, last_turn, outcome, settled_at, started_at, prompt_envelope, reply_envelope, private)
+        VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(id, run.runTurn, run.peer, run.lastTurn, outcome, now, run.startedAt, run.promptEnvelope ?? null, run.replyEnvelope ?? null, run.private ? 1 : 0);
+      this.db.query("DELETE FROM completion_runs WHERE run_turn = ?").run(run.runTurn);
+      return made.changes === 1;
+    });
+    return write() ? this.get(id) : undefined;
+  }
+
+  get(id: string): Completion | undefined {
+    const raw = this.db.query("SELECT * FROM completions WHERE id = ?").get(id) as RawCompletion | null;
+    return raw ? completionOf(raw) : undefined;
+  }
+  byRun(runTurn: string): Completion | undefined {
+    const raw = this.db.query("SELECT * FROM completions WHERE run_turn = ?").get(runTurn) as RawCompletion | null;
+    return raw ? completionOf(raw) : undefined;
+  }
+  /** Newest first, bounded. */
+  list(limit = 100): Completion[] {
+    return (this.db.query("SELECT * FROM completions ORDER BY settled_at DESC, id LIMIT ?").all(limit) as RawCompletion[]).map(completionOf);
+  }
+  /** Completions with no receipt: what the next task shows as unread. */
+  unread(): Completion[] {
+    return (this.db.query("SELECT c.* FROM completions c WHERE NOT EXISTS (SELECT 1 FROM completion_receipts r WHERE r.completion_id = c.id) ORDER BY c.settled_at DESC, c.id").all() as RawCompletion[]).map(completionOf);
+  }
+  /** One completion as the reads show it: the record and whether a receipt exists. Newest first. */
+  listWithState(limit = 100, unreadOnly = false): (Completion & { seenAt?: number; surface?: string })[] {
+    // The unread predicate is part of the query, BEFORE the limit: filtering after a LIMIT would hide an old unread result behind newer read ones while status still counts it.
+    return (this.db.query(`SELECT c.*, r.seen_at AS seen_at, r.surface AS surface FROM completions c LEFT JOIN completion_receipts r ON r.completion_id = c.id ${unreadOnly ? "WHERE r.completion_id IS NULL" : ""} ORDER BY c.settled_at DESC, c.id LIMIT ?`).all(limit) as (RawCompletion & { seen_at: number | null; surface: string | null })[])
+      .map(raw => ({ ...completionOf(raw), ...(raw.seen_at !== null ? { seenAt: raw.seen_at } : {}), ...(raw.surface ? { surface: raw.surface } : {}) }));
+  }
+
+  /** Whether any completion has been read: the one fact the person's mark-unread needs to know it has something to relight. */
+  hasRead(): boolean {
+    return this.db.query("SELECT 1 AS one FROM completion_receipts LIMIT 1").get() !== null;
+  }
+
+  /** How many completions have no receipt: the number status counts, so a listing can say when it showed fewer. */
+  unreadCount(): number {
+    return (this.db.query("SELECT COUNT(*) AS n FROM completions c WHERE NOT EXISTS (SELECT 1 FROM completion_receipts r WHERE r.completion_id = c.id)").get() as { n: number }).n;
+  }
+
+  /**
+   * Mark exactly one completion read. A compare-and-set on "no receipt yet": a completion that does not exist, or is already read, is refused with the reason, and of two callers
+   * racing on one completion exactly one writes. Never infers "seen" from anything but this call.
+   */
+  markSeen(id: string, now: number, surface: string): { ok: true } | { ok: false; error: string } {
+    if (!this.get(id)) return { ok: false, error: "no such result" };
+    const made = this.db.query("INSERT OR IGNORE INTO completion_receipts(completion_id, seen_at, surface) VALUES(?, ?, ?)").run(id, now, surface);
+    return made.changes === 1 ? { ok: true } : { ok: false, error: "that result is already read" };
+  }
+  /** Mark every unread completion of the project read, in one transaction. Returns the ids it marked. */
+  markAllSeen(now: number, surface: string): string[] {
+    const write = this.db.transaction(() => {
+      const ids = (this.db.query("SELECT c.id FROM completions c WHERE NOT EXISTS (SELECT 1 FROM completion_receipts r WHERE r.completion_id = c.id) ORDER BY c.settled_at, c.id").all() as { id: string }[]).map(row => row.id);
+      for (const id of ids) this.db.query("INSERT OR IGNORE INTO completion_receipts(completion_id, seen_at, surface) VALUES(?, ?, ?)").run(id, now, surface);
+      return ids;
+    });
+    return write();
+  }
+  /**
+   * Relight the completion the person read LAST: its receipt, the latest one, is deleted. Ordered by `seen_at`; `markAllSeen` gives many rows one `seen_at`, so settle time and id break the
+   * tie, newest first. Undefined when nothing is read.
+   */
+  unmarkLast(): string | undefined {
+    const write = this.db.transaction(() => {
+      const row = this.db.query("SELECT r.completion_id AS id FROM completion_receipts r JOIN completions c ON c.id = r.completion_id ORDER BY r.seen_at DESC, c.settled_at DESC, c.id DESC LIMIT 1").get() as { id: string } | null;
+      if (!row) return undefined;
+      this.db.query("DELETE FROM completion_receipts WHERE completion_id = ?").run(row.id);
+      return row.id;
+    });
+    return write();
+  }
+
+  /**
+   * Retention (#1054 review nit): the table is bounded. Past `keep` completions the oldest READ ones go, with their receipts; an unread completion is never deleted, so a person who has
+   * not looked yet loses nothing, and neither does an open run. A pruned completion's first-turn id could be settled again only by a replay of a run that ended long ago, which no code path makes.
+   * Returns how many completions it deleted.
+   */
+  prune(keep = 500): number {
+    const write = this.db.transaction(() => {
+      const doomed = (this.db.query(`SELECT c.id FROM completions c JOIN completion_receipts r ON r.completion_id = c.id ORDER BY c.settled_at DESC, c.id DESC LIMIT -1 OFFSET ?`).all(Math.max(0, keep)) as { id: string }[]).map(row => row.id);
+      for (const id of doomed) { this.db.query("DELETE FROM completion_receipts WHERE completion_id = ?").run(id); this.db.query("DELETE FROM completions WHERE id = ?").run(id); }
+      return doomed.length;
+    });
+    return write();
+  }
+
+  /** What an older daemon would silently orphan: an open run, or a completion nobody has seen. */
+  hasPending(): boolean {
+    return (this.db.query(`SELECT (EXISTS(SELECT 1 FROM completion_runs)
+      OR EXISTS(SELECT 1 FROM completions c WHERE NOT EXISTS (SELECT 1 FROM completion_receipts r WHERE r.completion_id = c.id))) AS present`).get() as { present: number }).present === 1;
+  }
+}

package/src/hub/completions.ts

@@ -0,0 +1,120 @@
+/**
+ * #1054 T2: runs a person started, and the completion each one earns when it settles. Pure: the daemon supplies the facts (an adapter signal, the pending-work reads) and the
+ * store, this decides. Ids and counts only: no prompt or reply text is ever passed in, kept or returned.
+ *
+ * A run starts at the `turn_start` that consumes a person-originated delivery. It is settled only when ALL hold for its peer: the adapter's own settle signal fired, no queued
+ * delivery will start a continuation turn, no permission or question is open, and no owned child, running check or held delivery remains. While any is open the run reads as
+ * working (or, for a permission or question, as needing the person), even after a `turn_end`.
+ *
+ * An adapter that declares no `settle` signal creates no completion: nothing here guesses one (owner decision 2026-11-04, issue #1054).
+ *
+ * Restart reconstruction reads the store's open-run rows (`completions-store.ts`), not `events.jsonl`: a `turn_start` event does not say who started the turn, so events alone
+ * would invent completions for runs nobody asked for. A run is recorded, ids only, when it starts and removed when it settles or is stopped quietly.
+ */
+
+/** The facts one settle check reads, all counts the daemon already holds. */
+export interface SettleFacts {
+  /** The adapter's settle signal fired for the run's last turn (a verified native Stop, `turn/completed`, `agent_settled`, a route outcome, a prompt response, `message_stop`). */
+  signal: boolean;
+  /** Deliveries in the peer's queue that will start another turn (task, chat, review, important), never a notice that starts none. */
+  queuedContinuations: number;
+  openPermissions: number;
+  openQuestions: number;
+  /** An owned child process the hub can see (a headless implementer's print child that outlived its turn). */
+  ownedChildren: number;
+  /** Check runs (`src/hub/check-runner.ts`) owned by this peer that are queued or running. */
+  runningChecks: number;
+  /** Rows held or in `needs_review`: uncertain, so never settled. */
+  heldDeliveries: number;
+}
+
+export type RunState = "working" | "needs-input" | "settled";
+
+/** The one rule. A permission or question wins over everything else: the person has to act, so the run is needs-input and never "done". */
+export function settleVerdict(facts: SettleFacts): RunState {
+  if (facts.openPermissions > 0 || facts.openQuestions > 0) return "needs-input";
+  if (!facts.signal || facts.queuedContinuations > 0 || facts.ownedChildren > 0 || facts.runningChecks > 0 || facts.heldDeliveries > 0) return "working";
+  return "settled";
+}
+
+export const OUTCOMES = Object.freeze(["done", "failed", "limit", "interrupted"] as const);
+export type Outcome = (typeof OUTCOMES)[number];
+
+/** What a run saw while it lasted. Closed facts the daemon sets; none carries text. */
+export interface RunEvidence {
+  /** A turn of this run ended in a failure the adapter reported (a prompt that ended without normal completion, a refused turn). */
+  failed?: true;
+  /** A budget, step ceiling or context limit ended it. */
+  limit?: true;
+}
+
+export const outcomeOf = (evidence: RunEvidence): Exclude<Outcome, "interrupted"> => evidence.limit ? "limit" : evidence.failed ? "failed" : "done";
+
+export interface Run {
+  peer: string;
+  /** The turn id of the `turn_start` that began the run: the deduplication key of its completion. */
+  runTurn: string;
+  /** The latest turn of the run (a continuation moves it). */
+  lastTurn: string;
+  startedAt: number;
+  /** Envelope ids only, so a display can read the prompt and the reply later through the usual privacy path. */
+  promptEnvelope?: string;
+  replyEnvelope?: string;
+  private: boolean;
+  evidence: RunEvidence;
+  /** The adapter's settle signal for the latest turn has fired. */
+  signalled: boolean;
+}
+
+/** In-memory runs, one per peer. The store keeps an id-only row for each open run, so a restart can settle it `interrupted`. */
+export class RunTracker {
+  private readonly runs = new Map<string, Run>();
+
+  get(peer: string): Run | undefined { return this.runs.get(peer); }
+  open(): Run[] { return [...this.runs.values()]; }
+
+  /**
+   * A turn started. It begins a run only when `personOriginated` and the peer has none; a turn that starts while a run is open is a continuation and moves `lastTurn`,
+   * whoever started it. Returns the run the turn belongs to, or undefined when it belongs to none (an ordinary agent-to-agent turn).
+   */
+  turnStarted(input: { peer: string; turn: string; at: number; personOriginated: boolean; promptEnvelope?: string; private: boolean }): Run | undefined {
+    const current = this.runs.get(input.peer);
+    if (current) {
+      current.lastTurn = input.turn; current.signalled = false;
+      if (input.private) current.private = true;
+      return current;
+    }
+    if (!input.personOriginated) return undefined;
+    const run: Run = { peer: input.peer, runTurn: input.turn, lastTurn: input.turn, startedAt: input.at, ...(input.promptEnvelope ? { promptEnvelope: input.promptEnvelope } : {}), private: input.private, evidence: {}, signalled: false };
+    this.runs.set(input.peer, run);
+    return run;
+  }
+
+  /** The adapter's settle signal fired for the peer's latest turn. */
+  signalled(peer: string, replyEnvelope?: string): Run | undefined {
+    const run = this.runs.get(peer);
+    if (!run) return undefined;
+    run.signalled = true;
+    if (replyEnvelope) run.replyEnvelope = replyEnvelope;
+    return run;
+  }
+
+  note(peer: string, evidence: RunEvidence): void {
+    const run = this.runs.get(peer);
+    if (!run) return;
+    if (evidence.failed) run.evidence.failed = true;
+    if (evidence.limit) run.evidence.limit = true;
+  }
+
+  /** An explicit stop by the person: the run ends and creates nothing. */
+  quietStop(peer: string): boolean { return this.runs.delete(peer); }
+
+  /** Remove the run once its completion exists. */
+  close(peer: string): void { this.runs.delete(peer); }
+
+  /** The state a settle check reads off a run's own signal plus the pending-work facts. */
+  state(peer: string, pending: Omit<SettleFacts, "signal">): RunState | undefined {
+    const run = this.runs.get(peer);
+    return run ? settleVerdict({ ...pending, signal: run.signalled }) : undefined;
+  }
+}

package/src/hub/config-apply.ts

@@ -26,7 +26,7 @@ import { validateInstances, type InstancesConfig } from "./instances.ts";
 import { peerRosterConfig, staleInstanceKey } from "./roster.ts";
 import { CHARACTER_IDS } from "../pet/characters.ts";
 import { autonomyOwnership, checkSettingValue, settingDef } from "./settings.ts";
-import { petPalette } from "../pet/config.ts";
+import { petPalette, stripLegacyPetWindow, PET_WINDOW_RETIRED_NOTICE } from "../pet/config.ts";
 import { parseSpecsConfig } from "./specs-config.ts";
 
 export type ApplyClass = "live" | "next use" | "restart";
@@ -67,6 +67,7 @@ export function authorizeConfigLeaf(input: ConfigAuthorizationInput): ConfigAuth
   const result = (allowed: boolean, guarded: boolean, reason: string): ConfigAuthorizationDecision => ({ key, allowed, guarded, reason });
   const runners = key === "research.runners" || key.startsWith("research.runners.") || key === "research"
     && [before, after].some(value => !!value && typeof value === "object" && Object.hasOwn(value, "runners"));
+  if (input.source === "config" && key === "pet.window") return result(false, false, PET_WINDOW_RETIRED_NOTICE);
   if (runners) {
     if (input.source !== "config" || input.sourceFile !== "config.local.json" || input.tracked !== false) return result(false, true, "research.runners requires untracked config.local.json");
     if (input.authority === "conductor") return result(false, true, "runner registration is person only");
@@ -176,11 +177,10 @@ const petFields: Record<string, Check> = {
   blink: bool,
   bell: bool,
   palette: (v, k) => { if (!petPalette(v)) fail(k, "unknown choice"); },
-  window: bool,
 };
 export const validatePetConfig: Check = (v, k) => {
   if (v === false) return;
-  block(petFields)(v, k);
+  block(petFields)(stripLegacyPetWindow(v), k);
 };
 shapes.set(validatePetConfig, { fields: petFields });
 const nativeValidators = { bool, text, strings, argv, number, words, block };
@@ -207,7 +207,7 @@ const schema: Record<string, Check> = {
   conductor: block({ feed: words(["own", "all", "off"]), approval_wait_s: number(0, 2_147_483_647 / 1000) }),
   budget: block({ gate: number(0, 1), stale_min: timerMinutes, poll_min: timerMinutes, checkpoint_timeout_s: timerSeconds, kimi_tokens_5h: number(0), wait_max_min: number(0) }),
   context: block({ gate: number(0, 1), stale_min: timerMinutes, max_assignment_used: number(0, 1) }),
-  bus: block({ max_attempts: operationalNumberCheck("bus.max_attempts"), digest_max: operationalNumberCheck("bus.digest_max"), pull_budget_bytes: operationalNumberCheck("bus.pull_budget_bytes"), notes_kept: operationalNumberCheck("bus.notes_kept"), terminal_history_limit: operationalNumberCheck("bus.terminal_history_limit") }),
+  bus: block({ max_attempts: operationalNumberCheck("bus.max_attempts"), digest_max: operationalNumberCheck("bus.digest_max"), pull_budget_bytes: operationalNumberCheck("bus.pull_budget_bytes"), notes_kept: operationalNumberCheck("bus.notes_kept"), terminal_history_limit: operationalNumberCheck("bus.terminal_history_limit"), accepted_settle_ms: operationalNumberCheck("bus.accepted_settle_ms") }),
   adapter_timing: block({ acp_tool_ceiling_min: operationalNumberCheck("adapter_timing.acp_tool_ceiling_min"), acp_activity_batch_ms: operationalNumberCheck("adapter_timing.acp_activity_batch_ms"), jcode_steer_timeout_s: operationalNumberCheck("adapter_timing.jcode_steer_timeout_s") }),
   model_relay: block({ cooldown_failures: operationalNumberCheck("model_relay.cooldown_failures"), cooldown_s: operationalNumberCheck("model_relay.cooldown_s"), cooldown_cap_s: operationalNumberCheck("model_relay.cooldown_cap_s"), terminal_history_limit: operationalNumberCheck("model_relay.terminal_history_limit") }),
   console: block({ poll_ms: operationalNumberCheck("console.poll_ms"), notice_ms: operationalNumberCheck("console.notice_ms"), history_limit: operationalNumberCheck("console.history_limit"), pending_stream_limit: operationalNumberCheck("console.pending_stream_limit"), attention_limit: operationalNumberCheck("console.attention_limit") }),
@@ -228,6 +228,8 @@ const schema: Record<string, Check> = {
   } },
   snapshots: block({ enabled: bool, keep: number(1, 1_000_000, true) }), research: block({ enabled: bool, runners: researchRunners }), bench: block({ enabled: bool }),
   worktrees: block({ quiet_days: number(0, 3650, true), alert_over: number(0, 100_000, true) }),
+  // #1053: how long an unanswered question waits (`ttl_s`, 1 minute to 30 days) and, per adapter kind, how long a `hub_ask` call waits for the person before it answers `pending`.
+  questions: block({ ttl_s: number(60, 2_592_000, true), wait_ms: map(number(1000, 600_000, true)) }),
   peers: (v, k) => { map(block({ start_mode: words(["tui", "headless"]) }), START_MODE_PEERS)(v, k); peerStartConfig(v); },
   terminal: (v, k) => { block({ open: strings })(v, k); terminalTemplate(object(v, k).open); },
   start: (v, k) => { block({ agents: strings })(v, k); if (object(v, k).agents !== undefined) checkStartAgents(object(v, k).agents, `${k}.agents`); },
@@ -274,7 +276,7 @@ const restart: Record<string, string> = {
   profile: "Session tool schemas and profile contracts are bound at startup", profile_overrides: "Session tool schemas and profile contracts are bound at startup",
   text_projection: "Converter and cache ownership are bound at startup", corpus: "The corpus index is bound to its roots at startup", terminal: "Terminal provider is supplied by the daemon lifecycle", bench: "Benchmark execution environment is selected before work starts",
 };
-const live = new Set(["action_policy", "permission", "roster", "roles", "planner", "conductor", "protect_instruction_files", "task_sweep", "capabilities", "invocation", "research", "snapshots", "worktrees", "tasks.wip_limits", "tasks.escalate_after", "tasks.auto_pull", "tasks.queue_backpressure", "schedules", "approvals.notify", "pet", "specs"]);
+const live = new Set(["action_policy", "permission", "roster", "roles", "planner", "conductor", "protect_instruction_files", "task_sweep", "capabilities", "invocation", "research", "snapshots", "worktrees", "tasks.wip_limits", "tasks.escalate_after", "tasks.auto_pull", "tasks.queue_backpressure", "schedules", "approvals.notify", "questions", "pet", "specs"]);
 const nextMemory = new Set(["memory.inject_tokens", "memory.brief_items", "memory.suggest_edges"]);
 /** Closed top-level schema; leaf overrides retain the existing session/runtime boundaries. */
 export function configApply(key: string, scopes: readonly ConfigIdentityScope[] = []): ApplyRule {

package/src/hub/config-reload.ts

@@ -4,6 +4,7 @@ import { createHash } from "node:crypto";
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
 import { validateRawConfig, type ConfigLayer, type ConfigIdentitySnapshot } from "./config-apply.ts";
+import { stripLegacyPetWindow } from "../pet/config.ts";
 import { parseOverlay, parseRouting, type Routing } from "./routing.ts";
 import { CLASSES } from "./board.ts";
 import { readInstanceConfig, withoutInertInstancePolicy, type DeclaredExternalInstance } from "./instance-config.ts";
@@ -125,6 +126,7 @@ export function parseConfigSources(texts: ConfigSourceTexts, fallbackRouting?: R
     const text = texts[name];
     if (text === null) continue;
     let raw: Record<string, unknown>;
+    let trustRaw: Record<string, unknown> | undefined;
     try {
       const value: unknown = name.endsWith(".json") ? JSON.parse(text) : Bun.TOML.parse(text);
       if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error();
@@ -134,7 +136,14 @@ export function parseConfigSources(texts: ConfigSourceTexts, fallbackRouting?: R
       continue;
     }
     if (name === "config.json" || name === "config.local.json") {
+      const pet = stripLegacyPetWindow(raw.pet);
+      if (pet !== raw.pet) {
+        trustRaw = structuredClone(raw);
+        if (pet && typeof pet === "object" && !Object.keys(pet).length) delete raw.pet;
+        else raw.pet = pet;
+      }
       raw = withoutInertInstancePolicy(raw, inertInstances);
+      if (trustRaw) trustRaw = withoutInertInstancePolicy(trustRaw, inertInstances);
       if (!fallbackRouting) {
         try {
           const structural = { ...raw };
@@ -146,7 +155,7 @@ export function parseConfigSources(texts: ConfigSourceTexts, fallbackRouting?: R
       }
       layers.push({ name, raw });
     }
-    trustLayers.push({ name, raw });
+    trustLayers.push({ name, raw: trustRaw ?? raw });
   }
   let routing = fallbackRouting;
   if (!routing) {

package/src/hub/control-client.ts

@@ -21,7 +21,7 @@ export const PROTOCOL = 17;
 /** The descriptor's legacy protocol field remains this floor for previous published clients. */
 export const PROTOCOL_MIN = 16;
 // Literal metadata is read without executing a recovery target; consistency is pinned in tests.
-export const DAEMON_FEATURES = ["project_autonomy", "conductor_recovery", "encrypted_rooms", "external_adapter_instances", "external_adapter_modules", "configured_acp", "native_hook_launch", "task_cancel", "invocation", "recovery_deferred_hub", "peer_instances", "role_stages", "task_planners", "release_trains", "reviewer_pool", "native_tui_launch", "terminal_owner", "cli_audit_delegated", "action_policy_floor", "calendar_schedules", "research_records", "research_dispatch", "research_dropped_offers", "research_experiments", "research_comparisons", "research_runners", "task_handoff", "session_identity", "schema_guard", "design_specs", "queue_discard_states", "tool_write_idempotency"] as const;
+export const DAEMON_FEATURES = ["project_autonomy", "conductor_recovery", "encrypted_rooms", "external_adapter_instances", "external_adapter_modules", "configured_acp", "native_hook_launch", "task_cancel", "invocation", "recovery_deferred_hub", "peer_instances", "role_stages", "task_planners", "release_trains", "reviewer_pool", "native_tui_launch", "terminal_owner", "cli_audit_delegated", "action_policy_floor", "calendar_schedules", "research_records", "research_dispatch", "research_dropped_offers", "research_experiments", "research_comparisons", "research_runners", "task_handoff", "session_identity", "schema_guard", "design_specs", "queue_discard_states", "tool_write_idempotency", "research_evidence", "review_comments", "questions", "accepted_delivery_settlement", "completions", "review_observer_input_state", "task_handoff_key", "task_handoff_seq", "peer_takeover"] as const;
 /** Protocols a current coordinator may authenticate while upgrading a running source. */
 export const RECOVERY_SOURCE_PROTOCOLS = [9, 10, 11, 12, 13, 14, 15, 16, PROTOCOL] as const;
 
@@ -58,6 +58,8 @@ export interface Hello {
   peer?: string;
   /** `peer` only: false when the session cannot show channel pushes; its queue then waits for `inbox` (issue #205). */
   channel?: boolean;
+  /** Closed, display-only evidence for Claude's channel attachment decision. */
+  channelEvidence?: "development-channel-launch" | "inherited-marker" | "launch-unverified" | "unknown" | "unreported";
   /** Managed Claude launch identity; absent for plain or pre-daemon sessions. */
   launchId?: string;
   /** Optional canonical native execution cwd; ownership requires independent host proof. */
@@ -70,6 +72,10 @@ export interface Hello {
   session?: string;
   /** Reclaim after replacement, never an intentional initial takeover. */
   standby?: boolean;
+  /** Opt in to a retained, person-selectable standby connection when another session owns this peer. */
+  retainStandby?: true;
+  /** Display-only process id, never native-session or authorization evidence. */
+  clientPid?: number;
   projectId?: string;
   instanceId?: string;
   projectRoot?: string;
@@ -117,14 +123,36 @@ const instancePins = new Map<string, { instanceId: string }>();
 /** Maximum supported 3600 s approval plus admission/transport margin; applies to every hub_invoke client path. */
 export const INVOCATION_CONTROL_TIMEOUT_MS = 3_665_000;
 export function controlRequestTimeout(msg: Record<string, unknown>, requested = 30_000): number {
+  if (msg.t === "task" && msg.op === "hub_ask" && requested !== 0) return Math.max(Number.isFinite(requested) ? requested : 0, QUESTION_CONTROL_TIMEOUT_MS);
+  if (msg.t === "task" && msg.op === "hub_task_handoff" && requested !== 0) return Math.max(Number.isFinite(requested) ? requested : 0, HANDOFF_CONTROL_TIMEOUT_MS);
   return msg.t === "task" && msg.op === "hub_invoke" && requested !== 0
     ? Math.max(Number.isFinite(requested) ? requested : 0, INVOCATION_CONTROL_TIMEOUT_MS) : requested;
 }
+/**
+ * #731 (agent-hub#1203): `hub_task_handoff` can legitimately take longer than the default 30 s, because the origin's own recovery runs inside it: a connect and a request to the target, the same
+ * again for the resend with the same key, then a connect and a request for the by-key lookup. The caller (the CLI and the MCP path alike) must outlast that, or it reports a generic timeout before
+ * `outcome_unknown` can name the key to retry with. The budgets are shared with `handoffOut`, so changing one moves the deadline with it.
+ */
+export const HANDOFF_CONNECT_MS = 5_000;
+export const HANDOFF_REQUEST_MS = 30_000;
+export const HANDOFF_LOOKUP_CONNECT_MS = 3_000;
+export const HANDOFF_LOOKUP_REQUEST_MS = 5_000;
+/** Two attempts, one by-key lookup, and a margin for the hello and the reply to travel back. */
+export const HANDOFF_CONTROL_TIMEOUT_MS = 2 * (HANDOFF_CONNECT_MS + HANDOFF_REQUEST_MS) + HANDOFF_LOOKUP_CONNECT_MS + HANDOFF_LOOKUP_REQUEST_MS + 12_000;
+/**
+ * #1053: `hub_ask` holds its request open for the daemon's bounded wait (at most `QUESTION_WAIT_MAX_MS`) plus a margin, so the client's own 30 s cap never turns a
+ * working wait into "no answer from the hub". The daemon, not this bound, decides when the wait ends.
+ */
+export const QUESTION_WAIT_MAX_MS = 600_000;
+export const QUESTION_CONTROL_TIMEOUT_MS = QUESTION_WAIT_MAX_MS + 15_000;
 
 
 /** One authenticated control connection. `request` correlates replies by `rid`; everything else goes to `onPush`. */
 export class ControlClient {
   features: readonly string[] = [];
+  /** A retained peer connection awaiting a person-requested takeover. */
+  standby = false;
+  standbyId?: string;
   /** The id the hub minted for a distinct session (agent-hub#1036); absent for every ordinary connection. */
   sessionId?: string;
   /** Selected wire version, checked against the welcome when that legacy-optional field is present. */
@@ -192,7 +220,13 @@ export class ControlClient {
         try { msg = JSON.parse(String(ev.data)); } catch { return refuse(new Error("invalid hub response")); }
         if (!msg || typeof msg !== "object" || Array.isArray(msg)) return refuse(new Error("invalid hub response"));
         const done = msg.rid !== undefined ? client.pending.get(msg.rid) : undefined;
-        if (!done) return client.onPush(msg);
+        if (!done) {
+          if (msg.t === "peer_attached" && msg.standbyId === client.standbyId) {
+            client.standby = false;
+            client.standbyId = undefined;
+          }
+          return client.onPush(msg);
+        }
         client.pending.delete(msg.rid);
         done(msg);
       };
@@ -208,6 +242,8 @@ export class ControlClient {
         client.features = Object.freeze(Array.isArray(reply.features) ? reply.features.filter((feature: unknown): feature is string => typeof feature === "string") : []);
         client.welcomeInstanceId = typeof reply.instanceId === "string" && reply.instanceId ? reply.instanceId : undefined;
         client.sessionId = typeof reply.session === "string" && reply.session.length <= 64 ? reply.session : undefined;
+        client.standby = reply.standby === true;
+        client.standbyId = client.standby && typeof reply.standbyId === "string" ? reply.standbyId : undefined;
         clearTimeout(timer);
         resolve(client);
       });
@@ -237,7 +273,7 @@ export class ControlClient {
 
   private requestBody(msg: Record<string, unknown>, timeoutMs: number, signal?: AbortSignal): Promise<any> {
     if (this.ws.readyState !== WebSocket.OPEN || this.closing && msg.t !== "request_cancel") return Promise.resolve({ ok: false, error: "hub connection is not open" });
-    const invocation = msg.t === "task" && msg.op === "hub_invoke";
+    const invocation = msg.t === "task" && (msg.op === "hub_invoke" || msg.op === "hub_ask");
     const operation = toolWriteOperation(msg), write = operation !== undefined;
     const keyedWrite = write && operation !== "hub_delivery_done";
     if (keyedWrite && msg.args && typeof msg.args === "object" && !Array.isArray(msg.args) && Object.hasOwn(msg.args, "request_id")) {
@@ -273,7 +309,7 @@ export class ControlClient {
         if (invocation && this.ws.readyState === WebSocket.OPEN) {
           try { this.ws.send(JSON.stringify({ t: "request_cancel", request: rid })); } catch { /* Socket close also withdraws admission. */ }
         }
-        done(write ? uncertain(error) : { ok: false, error: invocation ? `${error}; invocation admission unconfirmed, inspect before retrying` : error });
+        done(write ? uncertain(error) : { ok: false, error: invocation ? `${error}; ${msg.op === "hub_ask" ? "the question may still be open: it is answered later as a message of kind answer, or never" : "invocation admission unconfirmed, inspect before retrying"}` : error });
       };
       const aborted = () => abandon("hub request cancelled");
       this.pending.set(rid, done);