@staix/agent-hub 0.20.0 → 0.22.0

package/src/hub/peer-doing.ts

@@ -0,0 +1,130 @@
+import { closeSync, constants as fsConstants, fstatSync, openSync, readSync } from "node:fs";
+
+/**
+ * #878: what a peer is doing, derived from signals the hub already receives (a Claude session's title and todo
+ * list, a Codex thread name and plan, an ACP plan). Daemon memory only: never persisted, logged, captured or relayed.
+ */
+export interface PeerDoing { text: string; source: "title" | "todo"; at: number }
+export type DoingKind = "title" | "todo" | "reset";
+
+export const DOING_MAX = 120;
+export const DOING_STUB = "[private]";
+/** At most this much of a transcript is read per signal; lines over TITLE_LINE_MAX are skipped unparsed. */
+export const TITLE_READ_MAX = 1024 * 1024;
+export const TITLE_LINE_MAX = 64 * 1024;
+
+/** One line of display text: controls and line breaks become spaces, cut to DOING_MAX code points. */
+export function doingText(value: unknown): string | undefined {
+  if (typeof value !== "string") return undefined;
+  const text = value.replace(/[\p{Cc}\p{Cf}\p{Zl}\p{Zp}\s]+/gu, " ").trim();
+  return text ? [...text].slice(0, DOING_MAX).join("") : undefined;
+}
+
+type Observed = PeerDoing & { private: boolean };
+
+/** The current item if there is one, else the title. Privacy is decided when a value is observed and again when shown. */
+export class DoingTracker {
+  private title: Observed | undefined;
+  private item: Observed | undefined;
+
+  /** `isPrivate` is the hub's screen at observation time; a throw counts as private. An empty text clears that kind. */
+  observe(kind: "title" | "todo", value: unknown, isPrivate: (text: string) => boolean, at = Date.now()): void {
+    const text = doingText(value);
+    let hidden = true;
+    if (text !== undefined) try { hidden = isPrivate(text); } catch { /* a failed screen is a stub */ }
+    const next = text === undefined ? undefined : { text, source: kind, at, private: hidden };
+    if (kind === "title") this.title = next; else this.item = next;
+  }
+
+  /** `privateNow`: the peer owns or reviews a PII task, or is in a private turn. */
+  view(privateNow: boolean): PeerDoing | undefined {
+    const value = this.item ?? this.title;
+    if (!value) return undefined;
+    return { text: value.private || privateNow ? DOING_STUB : value.text, source: value.source, at: value.at };
+  }
+}
+
+/** Where the last read of a transcript stopped; `skip` drops the rest of a line too long for one read. */
+export interface TitleCursor { path: string; offset: number; skip: boolean }
+
+/**
+ * The latest `{"type":"ai-title","aiTitle":...}` row appended since `cursor`, reading at most TITLE_READ_MAX bytes and
+ * only whole lines. Undefined when none was appended; a missing, foreign or unreadable file reads nothing.
+ */
+export function readAiTitle(cursor: TitleCursor): string | undefined {
+  let fd: number | undefined;
+  try {
+    fd = openSync(cursor.path, fsConstants.O_RDONLY | fsConstants.O_NONBLOCK);
+    const st = fstatSync(fd);
+    if (!st.isFile()) return undefined;
+    if (st.size < cursor.offset) { cursor.offset = 0; cursor.skip = false; } // replaced or truncated: start over
+    const length = Math.min(st.size - cursor.offset, TITLE_READ_MAX);
+    if (length <= 0) return undefined;
+    const buf = Buffer.alloc(length);
+    const read = readSync(fd, buf, 0, length, cursor.offset);
+    // Lines end at a newline byte: decoding first would misplace the offset after a split multi-byte character.
+    const end = buf.subarray(0, read).lastIndexOf(10);
+    if (end === -1) {
+      if (read === TITLE_READ_MAX) { cursor.offset += read; cursor.skip = true; } // inside a line longer than one read
+      return undefined;
+    }
+    let at = cursor.skip ? buf.indexOf(10) + 1 : 0, title: string | undefined;
+    cursor.skip = false;
+    while (at <= end) {
+      const next = buf.indexOf(10, at);
+      if (next - at <= TITLE_LINE_MAX) {
+        const line = buf.subarray(at, next).toString("utf8");
+        if (line.includes("\"ai-title\"")) {
+          try {
+            const row = JSON.parse(line);
+            if (row?.type === "ai-title" && typeof row.aiTitle === "string") title = row.aiTitle;
+          } catch { /* a partial or foreign line */ }
+        }
+      }
+      at = next + 1;
+    }
+    cursor.offset += end + 1;
+    return title;
+  } catch { return undefined; }
+  finally { if (fd !== undefined) closeSync(fd); }
+}
+
+const SUBJECT_CAP = 256;
+
+/**
+ * One Claude session's current item, from the tool input its PreToolUse hook already sends: TodoWrite's in-progress
+ * todo, or the task TaskUpdate puts in progress. Answers undefined for no change, null for no current item. A cached
+ * subject keeps the privacy verdict it was learned with (`isPrivate(subject)`, asked for every cached subject; a throw is
+ * private), so one learned during PII work, or refused by the screen then, stays private when a later TaskUpdate selects it.
+ */
+export type ClaudeTodoItem = { text: string; private: boolean };
+export class ClaudeTodoSource {
+  private readonly subjects = new Map<string, ClaudeTodoItem>();
+  private task: string | undefined;
+
+  item(tool: string, input: Record<string, unknown>, isPrivate: (subject: string) => boolean): ClaudeTodoItem | null | undefined {
+    if (tool === "TodoWrite") {
+      if (!Array.isArray(input.todos)) return undefined;
+      this.task = undefined;
+      const todo = input.todos.find((t: unknown) => (t as { status?: unknown } | null)?.status === "in_progress") as { activeForm?: unknown; content?: unknown } | undefined;
+      const text = doingText(todo?.activeForm) ?? doingText(todo?.content);
+      return text ? { text, private: false } : null;
+    }
+    if (tool !== "TaskUpdate" || (typeof input.taskId !== "string" && typeof input.taskId !== "number")) return undefined;
+    const id = String(input.taskId), subject = doingText(input.subject);
+    if (subject) {
+      let hidden = true;
+      try { hidden = isPrivate(subject); } catch { /* unknown verdict: private */ }
+      this.subjects.delete(id); this.subjects.set(id, { text: subject, private: hidden });
+      if (this.subjects.size > SUBJECT_CAP) this.subjects.delete(this.subjects.keys().next().value as string);
+    }
+    // ponytail: a task's subject is known only from a TaskUpdate that names it (TaskCreate's id is in its result, which
+    // the hook does not send); an unknown one shows no current item. Forward the PostToolUse result if that matters.
+    const text = (): ClaudeTodoItem | null => { const form = doingText(input.activeForm); return form ? { text: form, private: false } : this.subjects.get(id) ?? null; };
+    if (input.status === "in_progress") { this.task = id; return text(); }
+    if (id !== this.task) return undefined;
+    if (input.status === undefined) return text();
+    this.task = undefined;
+    return null;
+  }
+}

package/src/hub/peers.ts

@@ -1,6 +1,7 @@
 import type { Envelope, EnvelopeOpts, PeerId, PeerState } from "./envelope.ts";
 import type { PermissionMode } from "./permission-mode.ts";
 import type { StartForm } from "../adapters/registry-types.ts";
+import type { DoingKind } from "./peer-doing.ts";
 
 export interface DeliveryReceipt {
   id: string;
@@ -26,6 +27,14 @@ export interface FrontendProxyPort {
 
 export interface PeerAdapter {
   readonly id: PeerId;
+  /** Host-owned room transport binding; remote ids never gain local role/console authority. */
+  readonly remoteRoom?: string;
+  /** Verified roster fingerprint, pinned separately from the reusable display label. */
+  readonly remoteMember?: string;
+  /** Host arrival TTL for queued room traffic, default 24 hours. */
+  readonly remoteQueueTtlMs?: number;
+  /** Host-only original enqueue deadline, handed over before one remote transport call. */
+  setRemoteDeadline?(envelopeId: string, expiresAt: number): void;
   ownedTools?(launchId: unknown): OwnedToolsLaunch | undefined;
   keepApprovalAlive?(): void;
   readonly state: PeerState;
@@ -79,6 +88,8 @@ export interface PeerAdapter {
   onFailed?: (envs: Envelope[], failure?: { quota?: true }) => void;
   /** Correlated durable-delivery lifecycle, emitted only when the bus supplied an id. */
   onDelivery?: (receipt: DeliveryReceipt) => void;
+  /** Set by the bus (#878): a native session title or current plan item the adapter observed; `reset` on a new session. */
+  onDoing?: (kind: DoingKind, text?: unknown) => void;
   /** Safe restart metadata only: ids and launch parameters, never prompt/message text. */
   recoveryMetadata?(): Record<string, unknown>;
   /** Current native TUI ownership, correlated to one launcher. A start acknowledgement is never evidence. */
@@ -94,6 +105,7 @@ export abstract class BasePeer implements PeerAdapter {
   onState?: (state: PeerState) => void;
   onFailed?: (envs: Envelope[], failure?: { quota?: true }) => void;
   onDelivery?: (receipt: DeliveryReceipt) => void;
+  onDoing?: (kind: DoingKind, text?: unknown) => void;
   private _state: PeerState = "offline";
   private timer: ReturnType<typeof setTimeout> | undefined;
   private nextWatchdogMs: number | undefined;

package/src/hub/queue-backpressure.ts

@@ -0,0 +1,58 @@
+/** Opt-in admission data only. This module never reads a queue, clock or delivery body. */
+export interface QueueBackpressurePolicy { max_queued: number; max_oldest_s: number }
+export interface QueuePressure {
+  queued: number;
+  /** null proves an empty queue; absent means the oldest pending timestamp is unknown. */
+  oldestQueuedAt?: number | null;
+}
+export type QueueBackpressureCode = "queue-count" | "queue-age" | "queue-age-unknown";
+export interface QueueBackpressureRefusal { peer: string; code: QueueBackpressureCode; reason: string }
+export interface QueuePressurePeerStatus {
+  queued: number | null;
+  oldestQueuedAt: number | null;
+  oldestAgeMs: number | null;
+  blocked: boolean;
+  code?: QueueBackpressureCode;
+  reason?: string;
+}
+export interface QueueBackpressureStatus {
+  policy: QueueBackpressurePolicy;
+  peers: Record<string, QueuePressurePeerStatus>;
+  truncated?: true;
+}
+export const QUEUE_BACKPRESSURE_LIMITS = Object.freeze({ max_queued: 10_000, max_oldest_s: 604_800 });
+const DEFAULT_POLICY: Readonly<QueueBackpressurePolicy> = Object.freeze({ max_queued: 0, max_oldest_s: 0 });
+const validLimit = (value: unknown, max: number): value is number => typeof value === "number" && Number.isSafeInteger(value) && value >= 0 && value <= max;
+
+/** Config owns validation; omission and each zero preserve the existing disabled behaviour. */
+export function queueBackpressurePolicy(raw: unknown): QueueBackpressurePolicy {
+  if (raw === undefined) return { ...DEFAULT_POLICY };
+  if (!raw || typeof raw !== "object" || Array.isArray(raw) || ![Object.prototype, null].includes(Object.getPrototypeOf(raw))) throw new Error("tasks.queue_backpressure must be a bounded policy object");
+  const row = raw as Record<string, unknown>;
+  if (Object.keys(row).some(key => !Object.hasOwn(DEFAULT_POLICY, key))) throw new Error("tasks.queue_backpressure contains an unknown field");
+  const result = { ...DEFAULT_POLICY };
+  for (const key of ["max_queued", "max_oldest_s"] as const) {
+    if (!Object.hasOwn(row, key)) continue;
+    const value = row[key];
+    if (!validLimit(value, QUEUE_BACKPRESSURE_LIMITS[key])) throw new Error(`tasks.queue_backpressure.${key} must be an integer from 0 to ${QUEUE_BACKPRESSURE_LIMITS[key]}`);
+    result[key] = value;
+  }
+  return result;
+}
+
+/** A pure admission verdict: thresholds are exceeded strictly; unknown never becomes age zero. */
+export function queueBackpressure(peer: string, policy: QueueBackpressurePolicy | undefined, queue: QueuePressure | undefined, now: number): QueueBackpressureRefusal | undefined {
+  if (policy === undefined) return undefined;
+  const refuse = (code: QueueBackpressureCode, reason: string): QueueBackpressureRefusal => ({ peer, code, reason: `queue backpressure: ${reason}` });
+  if (!validLimit(policy.max_queued, QUEUE_BACKPRESSURE_LIMITS.max_queued) || !validLimit(policy.max_oldest_s, QUEUE_BACKPRESSURE_LIMITS.max_oldest_s)) return refuse("queue-count", "policy unavailable");
+  if (policy.max_queued === 0 && policy.max_oldest_s === 0) return undefined;
+  if (!queue || !Number.isSafeInteger(queue.queued) || queue.queued < 0) return refuse("queue-count", "queued count unknown");
+  if (policy.max_queued > 0 && queue.queued > policy.max_queued) return refuse("queue-count", `queued ${queue.queued} exceeds max ${policy.max_queued}`);
+  if (policy.max_oldest_s === 0) return undefined;
+  if (queue.queued === 0 && queue.oldestQueuedAt === null) return undefined;
+  const oldest = queue.oldestQueuedAt;
+  if (queue.queued === 0 || typeof oldest !== "number" || !Number.isSafeInteger(oldest) || oldest < 0 || !Number.isSafeInteger(now) || now < oldest) return refuse("queue-age-unknown", "oldest queued age unknown");
+  const age = now - oldest, maxAge = policy.max_oldest_s * 1000;
+  if (age > maxAge) return refuse("queue-age", `oldest queued age ${age}ms exceeds max ${maxAge}ms`);
+  return undefined;
+}

package/src/hub/read-tools.ts

@@ -143,3 +143,5 @@ export function memoryRead(store: MemoryStore | undefined, project: string, scre
     return finish(out);
   } catch { return JSON.stringify({ error: REFUSAL }); }
 }
+
+export { sourceRead, validateSourceRead } from "./source-read.ts";

package/src/hub/recovery-authority.ts

@@ -0,0 +1,151 @@
+/** Host-only conductor continuity. Public operation JSON, actor labels and audits grant nothing.
+ * The pin is this registered project's canonical host-owned private key, never a key carried
+ * by a record. Like existing host state, it does not resist a same-OS-user process able to
+ * replace both key and record. Fresh host policy/privacy proof remains mandatory per effect.
+ */
+import { createHmac, randomBytes, randomUUID, timingSafeEqual } from "node:crypto";
+import { closeSync, constants, fstatSync, linkSync, lstatSync, openSync, readSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { isAbsolute, join } from "node:path";
+import { realPath } from "./project.ts";
+
+export interface ConductorRecoveryBinding {
+  schema: 1; operationId: string; peer: string; kind: "restart" | "upgrade";
+  projectId: string; projectRoot: string; stateDir: string; sourceInstanceId: string;
+  targetRoot: string; targetDigest: string; planFingerprint: string; policyDigest: string; boardDigest: string;
+}
+export interface VerifiedRecoveryAuthority { readonly binding: Readonly<ConductorRecoveryBinding> }
+export class RecoveryAuthorityError extends Error {
+  readonly code = "AHUB_RECOVERY_AUTHORITY";
+  constructor() { super("conductor recovery authority unavailable; the person runs it in ahub console or a terminal"); this.name = "RecoveryAuthorityError"; }
+}
+type Current = (binding: Readonly<ConductorRecoveryBinding>) => boolean;
+type PrivateRecord = { binding: Readonly<ConductorRecoveryBinding>; retired: boolean; seal: string };
+type FileRead = { bytes: Buffer; identity: string };
+type Grant = { stateDir: string; directory: string; key: string; record: string; current: Current };
+const grants = new WeakMap<VerifiedRecoveryAuthority, Grant>();
+const KEYS: readonly (keyof ConductorRecoveryBinding)[] = ["schema", "operationId", "peer", "kind", "projectId", "projectRoot", "stateDir", "sourceInstanceId", "targetRoot", "targetDigest", "planFingerprint", "policyDigest", "boardDigest"];
+const UUID = /^[a-f0-9]{8}-[a-f0-9]{4}-[1-8][a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$/;
+const HASH = /^[a-f0-9]{64}$/;
+const MAX_RECORD = 16 * 1024;
+function refuse(): never { throw new RecoveryAuthorityError(); }
+function guarded<T>(work: () => T): T { try { return work(); } catch { return refuse(); } }
+function object(value: unknown, keys: readonly string[]): Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value) || Object.getPrototypeOf(value) !== Object.prototype) refuse();
+  const fields = Object.getOwnPropertyDescriptors(value);
+  if (Reflect.ownKeys(fields).length !== keys.length || keys.some(key => !fields[key] || !Object.hasOwn(fields[key]!, "value"))) refuse();
+  return value as Record<string, unknown>;
+}
+function binding(value: unknown): Readonly<ConductorRecoveryBinding> {
+  const row = object(value, KEYS);
+  if (row.schema !== 1 || typeof row.operationId !== "string" || !UUID.test(row.operationId) || typeof row.peer !== "string" || !/^[a-z][a-z0-9-]{0,31}$/.test(row.peer)
+    || ["user", "hub", "digest"].includes(row.peer) || row.kind !== "restart" && row.kind !== "upgrade") refuse();
+  for (const key of ["projectId", "sourceInstanceId"] as const) if (typeof row[key] !== "string" || !/^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/.test(row[key])) refuse();
+  for (const key of ["projectRoot", "stateDir", "targetRoot"] as const) {
+    const value = row[key]; if (typeof value !== "string" || value.length > 4096 || !isAbsolute(value) || /[\p{Cc}]/u.test(value) || realPath(value) !== value) refuse();
+  }
+  for (const key of ["targetDigest", "planFingerprint", "policyDigest", "boardDigest"] as const) if (typeof row[key] !== "string" || !HASH.test(row[key])) refuse();
+  return Object.freeze(Object.fromEntries(KEYS.map(key => [key, row[key]])) as unknown as ConductorRecoveryBinding);
+}
+function identity(stat: NonNullable<ReturnType<typeof lstatSync>>): string {
+  return JSON.stringify([stat.dev, stat.ino, stat.mode, stat.uid, stat.nlink, stat.size, stat.mtimeMs, stat.ctimeMs]);
+}
+function directory(stateDir: string): string {
+  if (!isAbsolute(stateDir) || realPath(stateDir) !== stateDir) refuse();
+  const stat = lstatSync(stateDir);
+  if (!stat.isDirectory() || stat.isSymbolicLink() || !process.getuid || stat.uid !== process.getuid() || (stat.mode & 0o022) !== 0) refuse();
+  // Directory contents change during publication; pin its inode, owner and permission, not mtime.
+  return JSON.stringify([stat.dev, stat.ino, stat.uid, stat.mode]);
+}
+function readPrivate(file: string, maximum: number, exact?: number): FileRead {
+  const fd = openSync(file, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+  try {
+    const before = fstatSync(fd);
+    if (!before.isFile() || before.nlink !== 1 || (before.mode & 0o777) !== 0o600 || !process.getuid || before.uid !== process.getuid()
+      || before.size < 1 || before.size > maximum || exact !== undefined && before.size !== exact) refuse();
+    const bytes = Buffer.alloc(before.size + 1); let size = 0;
+    while (size < bytes.length) { const n = readSync(fd, bytes, size, bytes.length - size, null); if (!n) break; size += n; }
+    if (size !== before.size || identity(fstatSync(fd)) !== identity(before) || identity(lstatSync(file)) !== identity(before) || realPath(file) !== file) refuse();
+    return { bytes: bytes.subarray(0, size), identity: identity(before) };
+  } finally { closeSync(fd); }
+}
+const keyPath = (stateDir: string) => join(stateDir, "conductor-recovery.key");
+const recordPath = (stateDir: string, operationId: string) => join(stateDir, `conductor-recovery.${operationId}.json`);
+function seal(key: Buffer, value: Omit<PrivateRecord, "seal">): string {
+  return createHmac("sha256", key).update("agent-hub/conductor-recovery/v1\n").update(JSON.stringify(value)).digest("hex");
+}
+function encodeRecord(key: Buffer, value: Omit<PrivateRecord, "seal">): Buffer {
+  const bytes = Buffer.from(JSON.stringify({ ...value, seal: seal(key, value) })); if (bytes.length > MAX_RECORD) refuse(); return bytes;
+}
+function checkRecord(stateDir: string, expected: Readonly<ConductorRecoveryBinding>): { key: FileRead; record: FileRead; value: PrivateRecord } {
+  const key = readPrivate(keyPath(stateDir), 32, 32), record = readPrivate(recordPath(stateDir, expected.operationId), MAX_RECORD);
+  const row = object(JSON.parse(record.bytes.toString("utf8")), ["binding", "retired", "seal"]), bound = binding(row.binding);
+  if (typeof row.retired !== "boolean" || typeof row.seal !== "string" || !HASH.test(row.seal) || JSON.stringify(bound) !== JSON.stringify(expected)) refuse();
+  const computed = seal(key.bytes, { binding: bound, retired: row.retired });
+  if (!timingSafeEqual(Buffer.from(row.seal, "hex"), Buffer.from(computed, "hex"))) refuse();
+  return { key, record, value: { binding: bound, retired: row.retired, seal: row.seal } };
+}
+function fresh(current: Current, value: Readonly<ConductorRecoveryBinding>): void { if (current(value) !== true) refuse(); }
+function stillPrivate(file: string, stamp: string): void { if (identity(lstatSync(file)) !== stamp || realPath(file) !== file) refuse(); }
+/** Publish a whole private file, never an empty capability visible to another reader. */
+function publishNew(stateDir: string, file: string, bytes: Buffer): void {
+  const temporary = join(stateDir, `.conductor-recovery.${randomUUID()}.tmp`);
+  try { writeFileSync(temporary, bytes, { flag: "wx", mode: 0o600 }); linkSync(temporary, file); }
+  finally { try { unlinkSync(temporary); } catch (error) { if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error; } }
+}
+
+/** Call only at the authenticated source's current-conductor boundary. A verifier never creates a key. */
+export function issueConductorRecoveryAuthority(stateDir: string, input: ConductorRecoveryBinding, current: () => boolean): void {
+  return guarded(() => {
+    const value = binding(input), pin = directory(stateDir); if (value.stateDir !== stateDir) refuse(); fresh(current, value);
+    try { readPrivate(keyPath(stateDir), 32, 32); }
+    catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+      fresh(current, value); publishNew(stateDir, keyPath(stateDir), randomBytes(32));
+    }
+    const key = readPrivate(keyPath(stateDir), 32, 32);
+    try {
+      const existing = checkRecord(stateDir, value); if (existing.value.retired) refuse();
+      fresh(current, value); stillPrivate(keyPath(stateDir), key.identity); stillPrivate(recordPath(stateDir, value.operationId), existing.record.identity);
+      if (directory(stateDir) !== pin) refuse(); return;
+    } catch (error) { if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error; }
+    fresh(current, value); if (directory(stateDir) !== pin) refuse(); stillPrivate(keyPath(stateDir), key.identity);
+    publishNew(stateDir, recordPath(stateDir, value.operationId), encodeRecord(key.bytes, { binding: value, retired: false }));
+    fresh(current, value); if (directory(stateDir) !== pin) refuse();
+  });
+}
+/** The host supplies expected registry/package binding and a fresh live-RPC or conservative offline policy check. */
+export function authorizeConductorRecovery(stateDir: string, expected: ConductorRecoveryBinding, current: Current): VerifiedRecoveryAuthority {
+  return guarded(() => {
+    const value = binding(expected), pin = directory(stateDir); if (value.stateDir !== stateDir) refuse();
+    const proof = checkRecord(stateDir, value); if (proof.value.retired) refuse(); fresh(current, value);
+    stillPrivate(keyPath(stateDir), proof.key.identity); stillPrivate(recordPath(stateDir, value.operationId), proof.record.identity); if (directory(stateDir) !== pin) refuse();
+    const authority = Object.freeze({ binding: value });
+    grants.set(authority, { stateDir, directory: pin, key: proof.key.identity, record: proof.record.identity, current });
+    return authority;
+  });
+}
+/** Recheck immediately before every host effect, and after any awaited work. */
+export function assertConductorRecovery(authority: VerifiedRecoveryAuthority): void {
+  return guarded(() => {
+    const grant = grants.get(authority); if (!grant) refuse();
+    if (directory(grant.stateDir) !== grant.directory) refuse();
+    const proof = checkRecord(grant.stateDir, authority.binding);
+    if (proof.value.retired || proof.key.identity !== grant.key || proof.record.identity !== grant.record) refuse();
+    fresh(grant.current, authority.binding);
+    stillPrivate(keyPath(grant.stateDir), grant.key); stillPrivate(recordPath(grant.stateDir, authority.binding.operationId), grant.record); if (directory(grant.stateDir) !== grant.directory) refuse();
+  });
+}
+/** Root calls only at an authorized terminal phase. A sealed retirement never reactivates through issuance. */
+export function retireConductorRecovery(authority: VerifiedRecoveryAuthority): void {
+  return guarded(() => {
+    assertConductorRecovery(authority);
+    const grant = grants.get(authority)!;
+    const key = readPrivate(keyPath(grant.stateDir), 32, 32), file = recordPath(grant.stateDir, authority.binding.operationId);
+    const temporary = join(grant.stateDir, `.conductor-recovery.${randomUUID()}.tmp`);
+    try {
+      writeFileSync(temporary, encodeRecord(key.bytes, { binding: authority.binding, retired: true }), { flag: "wx", mode: 0o600 });
+      assertConductorRecovery(authority); renameSync(temporary, file);
+    } finally { try { unlinkSync(temporary); } catch (error) { if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error; } }
+    grants.delete(authority);
+  });
+}

package/src/hub/recovery-policy.ts

@@ -0,0 +1,220 @@
+/** Fresh, read-only privacy and policy proof for a host-sealed conductor recovery.
+ * This does not reconstruct the daemon's memory-only private-turn flag: the live
+ * admission path must also refuse contextPii before minting a recovery authority.
+ */
+import { Database } from "bun:sqlite";
+import { createHash } from "node:crypto";
+import { closeSync, constants, fstatSync, lstatSync, openSync, readSync } from "node:fs";
+import { isAbsolute, join, resolve } from "node:path";
+import { types } from "node:util";
+import { definitionOf } from "../adapters/registry.ts";
+import type { HubConfig } from "./daemon.ts";
+import type { ConfigSourceTexts } from "./config-reload.ts";
+import { conductorPeer } from "./conductor.ts";
+import { DEFAULT_ROLES } from "./hub-tools.ts";
+import { HUB_DB_BUSY_TIMEOUT_MS } from "./db-timeout.ts";
+import { readInstanceConfig, type InstanceConfigLayer } from "./instance-config.ts";
+import { effectiveInstanceRoles } from "./instances.ts";
+import { realPath } from "./project.ts";
+import { RecoveryAuthorityError } from "./recovery-authority.ts";
+import { peerRosterConfig, rosterAllows } from "./roster.ts";
+import { parseOverlay, parseRouting, type Routing } from "./routing.ts";
+
+export interface RecoveryPolicyProject { root: string; id: string; stateDir: string }
+export interface RecoveryPolicyCapture { policyDigest: string; boardDigest: string }
+/** Host-captured inputs, shared with loadConfig before any module evaluation. */
+export interface RecoveryPolicyInputs { layers: InstanceConfigLayer[]; routing: Routing; texts?: ConfigSourceTexts; routingFallback?: string }
+const MAX_POLICY_BYTES = 1024 * 1024;
+const MAX_ACTOR_TASKS = 4096;
+const MAX_SIGNALS_BYTES = 65536;
+function refuse(): never { throw new RecoveryAuthorityError(); }
+const hash = (text: string): string => createHash("sha256").update(text).digest("hex");
+const stamp = (s: NonNullable<ReturnType<typeof lstatSync>>): string => JSON.stringify([s.dev, s.ino, s.size, s.mode, s.nlink, s.mtimeMs, s.ctimeMs]);
+
+/** Only bounded, regular, stable files; an absent optional policy is different from an unreadable one. */
+function boundedText(file: string, optional = false): string | undefined {
+  let fd: number;
+  try { fd = openSync(file, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK); }
+  catch (error) { if (optional && (error as NodeJS.ErrnoException).code === "ENOENT") return undefined; throw error; }
+  try {
+    const before = fstatSync(fd);
+    if (!before.isFile() || before.nlink !== 1 || before.size > MAX_POLICY_BYTES || realPath(file) !== file) refuse();
+    const bytes = Buffer.alloc(before.size + 1);
+    let length = 0;
+    while (length < bytes.length) { const n = readSync(fd, bytes, length, bytes.length - length, null); if (!n) break; length += n; }
+    if (length !== before.size || stamp(before) !== stamp(fstatSync(fd)) || stamp(before) !== stamp(lstatSync(file))) refuse();
+    return new TextDecoder("utf-8", { fatal: true }).decode(bytes.subarray(0, length));
+  } finally { closeSync(fd); }
+}
+
+/** Derive compatibility from the verified target bytes, never the caller's mutable feature claim. */
+export function readRecoveryTargetFeatures(targetRoot: string): readonly string[] {
+  try {
+    const source = boundedText(join(targetRoot, "src/hub/control-client.ts"))!;
+    // ponytail: one literal array, at most 128 fixed labels. A computed export needs a versioned target manifest.
+    const declarations = [...source.matchAll(/export const DAEMON_FEATURES\s*=\s*(\[[^\]]*\])(?:\s+as const)?\s*;/g)];
+    if (declarations.length !== 1) refuse();
+    const values: unknown = JSON.parse(declarations[0]![1]!);
+    if (!Array.isArray(values) || !values.length || values.length > 128 || values.some(value => typeof value !== "string" || !/^[a-z][a-z0-9_]{0,63}$/.test(value))
+      || new Set(values).size !== values.length || !values.includes("conductor_recovery")) refuse();
+    return Object.freeze([...values]);
+  } catch { return refuse(); }
+}
+
+/** Stable semantic encoding; never evaluate config accessors or serialize runtime objects. */
+function canonical(value: unknown, depth = 0): string {
+  if (depth > 32) refuse();
+  if (value === null || typeof value === "boolean" || typeof value === "string") return JSON.stringify(value);
+  if (typeof value === "number" && Number.isFinite(value)) return JSON.stringify(value);
+  if (types.isProxy(value)) refuse();
+  if (Array.isArray(value)) {
+    if (Object.getPrototypeOf(value) !== Array.prototype || value.length > MAX_POLICY_BYTES) refuse();
+    const fields = Object.getOwnPropertyDescriptors(value);
+    if (Reflect.ownKeys(value).length !== value.length + 1 || Object.values(fields).some(field => !Object.hasOwn(field, "value"))) refuse();
+    const parts: string[] = [];
+    for (let index = 0; index < value.length; index++) {
+      const field = fields[String(index)]; if (!field) refuse();
+      parts.push(canonical(field.value, depth + 1));
+    }
+    return `[${parts.join(",")}]`;
+  }
+  if (!value || typeof value !== "object" || ![Object.prototype, null].includes(Object.getPrototypeOf(value))) refuse();
+  const fields = Object.getOwnPropertyDescriptors(value);
+  if (Reflect.ownKeys(value).some(key => typeof key !== "string") || Object.values(fields).some(field => !Object.hasOwn(field, "value"))) refuse();
+  return `{${Object.keys(fields).sort().filter(key => fields[key]!.value !== undefined).map(key => `${JSON.stringify(key)}:${canonical(fields[key]!.value, depth + 1)}`).join(",")}}`;
+}
+
+function freshRoles(layers: readonly InstanceConfigLayer[], scope: ReturnType<typeof readInstanceConfig>): Record<string, string[]> {
+  const roles = structuredClone(DEFAULT_ROLES);
+  for (const { raw } of layers) if (raw.roles !== undefined) {
+    conductorPeer(raw.roles);
+    for (const [id, list] of Object.entries(raw.roles as Record<string, string[]>)) {
+      const definition = definitionOf(id), ceiling = definition?.routing?.allowedRoles;
+      roles[id] = (ceiling ? list.filter(role => ceiling.includes(role)) : list).filter(role => role !== "planner" || !definition || definition.projection?.plannerEligible === true);
+    }
+  }
+  const configured = Object.fromEntries(scope.catalog.definitions.filter(d => !definitionOf(d.kind)).map(d => [d.kind, [...d.roles]]));
+  const extras = Object.fromEntries(Object.keys(scope.instances ?? {}).map(id => [id, effectiveInstanceRoles(id, scope.instances, roles, scope.catalog)]));
+  return { ...configured, ...roles, ...extras };
+}
+
+function publicActorBoard(stateDir: string, peer: string, routing: Routing): string {
+  const file = join(stateDir, "hub.db"), before = lstatSync(file);
+  if (!before.isFile() || before.isSymbolicLink() || before.nlink !== 1 || realPath(file) !== file) refuse();
+  const db = new Database(file, { readonly: true });
+  db.run(`PRAGMA busy_timeout = ${HUB_DB_BUSY_TIMEOUT_MS}`);
+  try {
+    db.run("BEGIN");
+    // Metadata only. In particular no unrelated task titles, bodies, history or refs are read.
+    const rows = db.query(`SELECT id, state, owner, reviewer,
+      CASE WHEN typeof(signals) = 'text' AND length(CAST(signals AS BLOB)) <= ${MAX_SIGNALS_BYTES} THEN signals ELSE NULL END AS signals
+      FROM tasks WHERE (owner = ? OR reviewer = ?) AND (state NOT IN ('approved', 'cancelled') OR state IS NULL)
+      ORDER BY id LIMIT ${MAX_ACTOR_TASKS + 1}`).all(peer, peer) as { id: number; state: string; owner: string | null; reviewer: string | null; signals: string | null }[];
+    if (rows.length > MAX_ACTOR_TASKS) refuse();
+    let total = 0;
+    for (const row of rows) {
+      if (!Number.isSafeInteger(row.id) || row.id <= 0 || !["proposed", "in_progress", "in_review", "changes_requested"].includes(row.state)
+        || row.signals === null || (total += Buffer.byteLength(row.signals)) > MAX_POLICY_BYTES) refuse();
+      const signals: unknown = JSON.parse(row.signals);
+      if (!Array.isArray(signals) || signals.length > 1024 || signals.some(signal => typeof signal !== "string" || signal.length > 1024)) refuse();
+      if (signals.includes("pii_path") || signals.includes("pii") && routing.constraints.pii === "local_only") refuse();
+    }
+    db.run("COMMIT");
+    const after = lstatSync(file);
+    if (after.dev !== before.dev || after.ino !== before.ino || realPath(file) !== file) refuse();
+    // Unrelated public board activity must not revoke a public conductor's offline continuity.
+    return hash(canonical({ schema: 1, peer, private: false }));
+  } finally { db.close(); }
+}
+
+/** A protected pending edit is not authorization to apply it through a restart. */
+export function assertRecoveryConfiguration(accepted: HubConfig, candidate: HubConfig): void {
+  try {
+    const previous = canonical(accepted), next = canonical(candidate);
+    if (Buffer.byteLength(previous) > 8 * MAX_POLICY_BYTES || Buffer.byteLength(next) > 8 * MAX_POLICY_BYTES || previous !== next) refuse();
+  } catch { return refuse(); }
+}
+
+export function assertRecoveryRouting(accepted: Routing, candidate: Routing): void {
+  try { if (canonical(accepted) !== canonical(candidate)) refuse(); }
+  catch { refuse(); }
+}
+
+/** Unknown future keys are still protected inputs; an older source may not silently authorize a pending edit. */
+export function assertRecoverySourceInputs(accepted: readonly { name: string; raw: Record<string, unknown> }[], candidate: RecoveryPolicyInputs): void {
+  try {
+    const actual: { name: string; raw: Record<string, unknown> }[] = [...candidate.layers];
+    for (const name of ["routing.toml", "routing.local.toml"] as const) {
+      const text = candidate.texts?.[name];
+      if (text != null) {
+        const raw = Bun.TOML.parse(text);
+        if (!raw || typeof raw !== "object" || Array.isArray(raw)) refuse();
+        actual.push({ name, raw: raw as Record<string, unknown> });
+      }
+    }
+    const projection = (rows: readonly { name: string; raw: Record<string, unknown> }[]) => Object.fromEntries(rows.filter(row => Object.keys(row.raw).length > 0).map(row => [row.name, row.raw]));
+    if (canonical(projection(accepted)) !== canonical(projection(actual))) refuse();
+  } catch { refuse(); }
+}
+
+/** One bounded source capture feeds both loadConfig and the recovery proof. No module is evaluated. */
+export function recoveryRoutingFallback(): string {
+  try { return boundedText(resolve(import.meta.dir, "..", "..", "templates", "routing.toml"))!; } catch { return refuse(); }
+}
+
+export function readRecoveryPolicyInputs(root: string, fallback?: string): RecoveryPolicyInputs {
+  try {
+    if (!isAbsolute(root) || realPath(root) !== root) refuse();
+    const layers: InstanceConfigLayer[] = [];
+    const texts: ConfigSourceTexts = { "config.json": null, "config.local.json": null, "routing.toml": null, "routing.local.toml": null };
+    for (const name of ["config.json", "config.local.json"] as const) {
+      const text = boundedText(join(root, ".agenthub", name), true);
+      texts[name] = text ?? null;
+      if (text === undefined) continue;
+      const raw: unknown = JSON.parse(text);
+      if (!raw || typeof raw !== "object" || Array.isArray(raw)) refuse();
+      layers.push({ name, raw: raw as Record<string, unknown> });
+    }
+    const ownMain = boundedText(join(root, ".agenthub", "routing.toml"), true);
+    const main = ownMain ?? fallback ?? recoveryRoutingFallback();
+    if (Buffer.byteLength(main) > MAX_POLICY_BYTES) refuse();
+    const overlay = boundedText(join(root, ".agenthub", "routing.local.toml"), true);
+    texts["routing.toml"] = ownMain ?? null; texts["routing.local.toml"] = overlay ?? null;
+    return { layers, routing: parseRouting(main, overlay === undefined ? undefined : parseOverlay(overlay)), texts, ...(ownMain === undefined ? { routingFallback: main } : {}) };
+  } catch { return refuse(); }
+}
+
+/** currentConfig must be host-loaded from these exact inputs and compared with the running accepted config.
+ * Supplied inputs are never reread from raw config/routing files. Board privacy is always fresh.
+ */
+export function captureRecoveryPolicy(project: RecoveryPolicyProject, peer: string, currentConfig: HubConfig, inputs?: RecoveryPolicyInputs): RecoveryPolicyCapture {
+  try {
+    if (!project.id || !isAbsolute(project.root) || !isAbsolute(project.stateDir) || realPath(project.root) !== project.root || realPath(project.stateDir) !== project.stateDir) refuse();
+    const snapshot = canonical(inputs ?? readRecoveryPolicyInputs(project.root));
+    if (Buffer.byteLength(snapshot) > 8 * MAX_POLICY_BYTES) refuse();
+    // Copy host own-data fields once, so proof evaluation cannot run callbacks or observe mutation mid-capture.
+    const captured = JSON.parse(snapshot) as RecoveryPolicyInputs;
+    const { layers, routing } = captured;
+    if (!Array.isArray(layers) || layers.length > 2 || new Set(layers.map(layer => layer.name)).size !== layers.length
+      || layers.some(layer => !["config.json", "config.local.json"].includes(layer.name) || !layer.raw || typeof layer.raw !== "object" || Array.isArray(layer.raw))) refuse();
+    // Explicit empty runtime definitions: never import a module or trust a retained display catalog.
+    const scope = readInstanceConfig(project.root, layers, []);
+    if (scope.adapter_modules?.length || scope.declaredExternalInstances?.length || currentConfig.adapter_modules?.length) refuse();
+    const roles = freshRoles(layers, scope);
+    if (conductorPeer(roles) !== peer || conductorPeer(currentConfig.roles) !== peer || canonical(roles) !== canonical(currentConfig.roles)
+      || canonical(scope.instances ?? {}) !== canonical(currentConfig.instances ?? {}) || scope.instances?.[peer]?.readOnly === true
+      || !scope.catalog.definitionOf(peer, scope.instances)) refuse();
+    // roster is merged key by key by loadConfig; independently refresh the exact fields that admit the actor.
+    const rawRoster = Object.assign({}, ...layers.map(layer => layer.raw.roster ?? {}));
+    const roster = peerRosterConfig(rawRoster, scope.instances, scope.catalog);
+    if (canonical(roster) !== canonical(currentConfig.roster) || !rosterAllows(roster, peer, currentConfig.pi.enabled, scope.instances, scope.catalog)) refuse();
+    // ponytail: at most 2 MiB config, 2 MiB routing and 4096 actor-bound open rows (1 MiB signals).
+    // A larger board fails closed; the upgrade path is an indexed durable per-actor privacy generation.
+    // Seal version-neutral inputs and the fresh actor decision. Defaults and registry projections may evolve in the verified target.
+    const policy = canonical({ schema: 1, project: { root: project.root, id: project.id, stateDir: project.stateDir }, peer,
+      actor: { conductor: true, rostered: true, writable: true }, sources: layers, texts: captured.texts ?? null,
+      routingFallback: captured.routingFallback ?? null });
+    if (Buffer.byteLength(policy) > 8 * MAX_POLICY_BYTES) refuse();
+    return { policyDigest: hash(policy), boardDigest: publicActorBoard(project.stateDir, peer, routing) };
+  } catch { return refuse(); }
+}