@staix/agent-hub 0.20.0 → 0.21.0

package/src/hub/operational-settings.ts

@@ -0,0 +1,76 @@
+import type { SettingDef } from "./settings.ts";
+
+/** Numeric operational metadata only: existing schema, settings and reload retain all authority. */
+export interface OperationalNumberSetting extends Pick<SettingDef, "key" | "group" | "label" | "path" | "applies" | "restartReason"> {
+  type: "number" | "integer";
+  store: "config";
+  risk: "raises";
+  min: number;
+  max: number;
+  defaultValue: number;
+  unit: string;
+  /** The independently classified H0 item, not a safety floor or wire/storage contract. */
+  inventory: string;
+}
+
+export const GROOM_FYI_WINDOW_SETTING = {
+  key: "tasks.groom_fyi_window_min",
+  path: ["tasks", "groom_fyi_window_min"],
+  group: "Routing",
+  label: "Planner state-update FYI interval (minutes)",
+  type: "number",
+  store: "config",
+  risk: "raises",
+  applies: "live",
+  min: 1,
+  max: 1440,
+  defaultValue: 10,
+  unit: "minutes",
+  inventory: "src/hub/tasks.ts:GROOM_FYI_WINDOW_MS",
+} as const satisfies OperationalNumberSetting;
+
+const taskNumber = <const T extends Omit<OperationalNumberSetting, "group" | "store" | "risk" | "applies">>(def: T) => ({ group: "Routing", store: "config", risk: "raises", applies: "live", ...def }) as const satisfies OperationalNumberSetting;
+
+/** #489 H2, tasks and routing. Each default equals the constant it replaces (pinned in test/operational-settings.test.ts); none is a safety floor or a contract. */
+export const DEMOTE_AT_SETTING = taskNumber({
+  key: "tasks.demote_at", path: ["tasks", "demote_at"], label: "Peer demotion threshold (decayed recent failures)",
+  type: "number", min: 0.5, max: 20, defaultValue: 1.5, unit: "failures", inventory: "src/hub/tasks.ts:DEMOTE_AT",
+});
+export const DEMOTION_HALF_LIFE_SETTING = taskNumber({
+  key: "tasks.demotion_half_life_h", path: ["tasks", "demotion_half_life_h"], label: "Demotion half-life: a failure counts half after (hours)",
+  type: "number", min: 1, max: 168, defaultValue: 24, unit: "hours", inventory: "src/hub/tasks.ts:DEMOTION_HALF_LIFE_MS",
+});
+export const CONTRADICTION_WINDOW_SETTING = taskNumber({
+  key: "tasks.contradiction_window_days", path: ["tasks", "contradiction_window_days"], label: "Approval contradiction window (days)",
+  type: "number", min: 1, max: 90, defaultValue: 7, unit: "days", inventory: "src/hub/tasks.ts:CONTRADICTION_WINDOW_MS",
+});
+export const RESCREEN_MAX_SETTING = taskNumber({
+  key: "tasks.rescreen_max", path: ["tasks", "rescreen_max"], label: "PII re-screen attempts per task in a hub run",
+  type: "integer", min: 1, max: 100, defaultValue: 10, unit: "attempts", inventory: "src/hub/tasks.ts:RESCREEN_MAX",
+});
+export const SPLIT_MIN_SETTING = taskNumber({
+  key: "tasks.split_min_observations", path: ["tasks", "split_min_observations"], label: "Shadow split prediction: measured tasks a peer needs",
+  type: "integer", min: 3, max: 100, defaultValue: 5, unit: "tasks", inventory: "src/hub/routing.ts:SPLIT_MIN",
+});
+export const SPLIT_FAILURE_SHARE_SETTING = taskNumber({
+  key: "tasks.split_max_failure_share", path: ["tasks", "split_max_failure_share"], label: "Shadow split prediction: failed share a history may hold",
+  type: "number", min: 0, max: 1, defaultValue: 0.3, unit: "share", inventory: "src/hub/routing.ts:SPLIT_FAILURE_SHARE",
+});
+
+/** Fixed metadata; never registration from a file, request, adapter or environment variable. */
+export const OPERATIONAL_NUMBERS: readonly OperationalNumberSetting[] = [GROOM_FYI_WINDOW_SETTING, DEMOTE_AT_SETTING, DEMOTION_HALF_LIFE_SETTING, CONTRADICTION_WINDOW_SETTING, RESCREEN_MAX_SETTING, SPLIT_MIN_SETTING, SPLIT_FAILURE_SHARE_SETTING];
+/** The `tasks` leaves the six #489 H2 readers need; `HubConfig.tasks` has them all. */
+export interface TaskOperationalConfig { tasks: { demote_at?: number; demotion_half_life_h?: number; contradiction_window_days?: number; rescreen_max?: number; split_min_observations?: number; split_max_failure_share?: number } }
+/**
+ * The one place the daemon turns the six task settings into `TasksDeps` readers. `config` is asked at every use, so a reload applies at the next demotion read, verdict, re-screen or prediction; an unset leaf is the row's default,
+ * which is the constant it replaced.
+ */
+export const taskOperationalReaders = (config: () => TaskOperationalConfig) => ({
+  demoteAt: () => config().tasks.demote_at ?? DEMOTE_AT_SETTING.defaultValue,
+  demotionHalfLifeH: () => config().tasks.demotion_half_life_h ?? DEMOTION_HALF_LIFE_SETTING.defaultValue,
+  contradictionWindowDays: () => config().tasks.contradiction_window_days ?? CONTRADICTION_WINDOW_SETTING.defaultValue,
+  rescreenMax: () => config().tasks.rescreen_max ?? RESCREEN_MAX_SETTING.defaultValue,
+  splitMinObservations: () => config().tasks.split_min_observations ?? SPLIT_MIN_SETTING.defaultValue,
+  splitMaxFailureShare: () => config().tasks.split_max_failure_share ?? SPLIT_FAILURE_SHARE_SETTING.defaultValue,
+});
+export const operationalNumber = (key: string): OperationalNumberSetting | undefined => OPERATIONAL_NUMBERS.find(def => def.key === key);

package/src/hub/operational-view.ts

@@ -66,7 +66,7 @@ function metadataValue(type:string,key:string,value:unknown):boolean {
   if(key==="item")return oneOf(value,["task","summary","review note","handoff","note"]);
   if(key==="category")return oneOf(value,["name","student_id","phone","address","grade","health","other"]);
   if(key==="miss")return oneOf(value,["too long","off campus","timeout","unreadable","failed"]);
-  if(key==="source")return type==="pii_screen"?oneOf(value,["regex","screen","unknown","inherited"]):type==="usage"?oneOf(value,["omniroute","claude_transcript","claude_result","codex_appserver","kimi_wire"]):identifier(value);
+  if(key==="source")return type==="pii_screen"?oneOf(value,["regex","screen","unknown","inherited"]):type==="usage"?oneOf(value,["omniroute","claude_transcript","claude_result","codex_appserver","kimi_wire","jcode_acp"]):identifier(value);
   if(key==="measuredAt")return type==="context_pressure" || type==="quota_reset"?typeof value==="number"&&Number.isFinite(value):typeof value==="string"&&Number.isFinite(Date.parse(value));
   if(key==="window")return value===null || typeof value==="number"&&Number.isFinite(value)&&value>=0 || identifier(value);
   if(key==="priority")return value===null || typeof value==="number"&&Number.isFinite(value) || oneOf(value,["status","important","fyi"]);

package/src/hub/packs.ts

@@ -0,0 +1,132 @@
+import { closeSync, constants, fstatSync, lstatSync, openSync, readSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { PROFILE_NAMES, resolveProfile, type ProfileName } from "./profiles.ts";
+import { loadRoleCatalog } from "./roles.ts";
+import { SHIPPED_PACKS } from "./shipped-packs.ts";
+import { criterionId } from "./workflow.ts";
+
+/**
+ * A domain pack (#513a): a profile plus the roles it expects, a review rubric and example checks, in one file. It is data, never authority: it selects an
+ * existing profile, names roles that must already be in the catalog, and contributes only `profile_overrides` text (`review_checklist`, `example_checks`)
+ * that `resolveProfile` already bounds. Checks are display text exactly like `example_checks`: nothing here selects or runs a command.
+ * The rubric ids follow #507's criterion ids (`criterionId`), so a reviewer names an unmet item by the same id the task's checklist uses.
+ */
+export interface DomainPack {
+  name: string; profile: ProfileName; summary: string; roles: string[];
+  rubric: { id: string; text: string; required: boolean }[];
+  checks: { id: string; note: string }[];
+  layer: "shipped" | "project";
+}
+export interface PackCatalog { packs: Map<string, DomainPack>; errors: { id: string; reason: string }[] }
+export const PACK_SUFFIX = ".pack.json";
+const NAME = /^[a-z][a-z0-9-]{0,47}$/;
+const MAX_BYTES = 8192, MAX_FILES = 16, MAX_ROLES = 8, MAX_RUBRIC = 12, MAX_CHECKS = 8;
+const KEYS = ["name", "profile", "summary", "roles", "rubric", "checks"];
+
+const plain = (value: unknown, cap: number, what: string): string => {
+  if (typeof value !== "string" || !value.trim() || value.length > cap || value !== value.trim()) throw new Error(`${what} must be trimmed text of at most ${cap} characters`);
+  for (const char of value) if (/[\x00-\x1f\x7f]/.test(char) || (char.codePointAt(0)! > 127 && /[\p{P}\p{S}\p{Z}\p{C}]/u.test(char))) throw new Error(`${what} must use plain punctuation and no control characters`);
+  return value;
+};
+const object = (value: unknown, keys: string[], what: string): Record<string, unknown> => {
+  if (!value || typeof value !== "object" || Array.isArray(value) || Object.keys(value).some(key => !keys.includes(key))) throw new Error(`${what}: unexpected shape or field`);
+  return value as Record<string, unknown>;
+};
+
+/** One pack file. `stem` is the file name without `.pack.json`; the name inside must equal it. */
+export function parsePack(text: string, stem: string, layer: DomainPack["layer"]): DomainPack {
+  if (Buffer.byteLength(text) > MAX_BYTES || text.includes("\r") || !NAME.test(stem)) throw new Error("invalid pack size, encoding or file name");
+  let raw: unknown;
+  try { raw = JSON.parse(text); } catch { throw new Error("pack is not valid JSON"); }
+  const data = object(raw, KEYS, "pack");
+  if (KEYS.some(key => data[key] === undefined)) throw new Error("pack needs name, profile, summary, roles, rubric and checks");
+  if (data.name !== stem) throw new Error("pack name must equal its file name");
+  if ((PROFILE_NAMES as readonly string[]).includes(stem)) throw new Error("a pack cannot take a profile's name");
+  if (typeof data.profile !== "string" || !(PROFILE_NAMES as readonly string[]).includes(data.profile)) throw new Error(`pack profile must be one of ${PROFILE_NAMES.join(", ")}`);
+  const summary = plain(data.summary, 160, "summary");
+  if (!Array.isArray(data.roles) || data.roles.length > MAX_ROLES || new Set(data.roles).size !== data.roles.length || data.roles.some(id => typeof id !== "string" || !NAME.test(id))) throw new Error(`pack roles must be at most ${MAX_ROLES} distinct role ids`);
+  if (!Array.isArray(data.rubric) || !data.rubric.length || data.rubric.length > MAX_RUBRIC) throw new Error(`pack rubric needs 1 to ${MAX_RUBRIC} criteria`);
+  const rubric = data.rubric.map((entry, index) => {
+    const item = object(entry, ["id", "text", "required"], `rubric ${index + 1}`);
+    if (!criterionId(item.id) || typeof item.required !== "boolean") throw new Error(`rubric ${index + 1} needs a criterion id and a required flag`);
+    return { id: item.id, text: plain(item.text, 300, `rubric ${item.id} text`), required: item.required };
+  });
+  if (new Set(rubric.map(item => item.id)).size !== rubric.length) throw new Error("rubric criterion ids must be distinct");
+  if (!Array.isArray(data.checks) || data.checks.length > MAX_CHECKS) throw new Error(`pack checks must be at most ${MAX_CHECKS} entries`);
+  const checks = data.checks.map((entry, index) => {
+    const item = object(entry, ["id", "note"], `check ${index + 1}`);
+    if (typeof item.id !== "string" || !NAME.test(item.id)) throw new Error(`check ${index + 1} needs a check id`);
+    return { id: item.id, note: plain(item.note, 500, `check ${item.id} note`) };
+  });
+  if (new Set(checks.map(item => item.id)).size !== checks.length) throw new Error("check ids must be distinct");
+  return { name: stem, profile: data.profile as ProfileName, summary, roles: [...data.roles as string[]], rubric, checks, layer };
+}
+
+/** Read one bounded regular file without following links, as `loadRoleCatalog` reads a project role. */
+function readPack(file: string): string {
+  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.size > MAX_BYTES) throw new Error("pack must be a bounded regular file");
+    const bytes = Buffer.alloc(MAX_BYTES + 1); let length = 0, n = 0;
+    while ((n = readSync(fd, bytes, length, bytes.length - length, null)) > 0) { length += n; if (length > MAX_BYTES) throw new Error("pack exceeds file cap"); }
+    const after = fstatSync(fd);
+    if (before.size !== after.size || before.mtimeMs !== after.mtimeMs || length !== after.size) throw new Error("pack changed during read");
+    return bytes.subarray(0, length).toString("utf8");
+  } finally { closeSync(fd); }
+}
+
+/**
+ * Project-layer packs, `.agenthub/roles/<name>.pack.json` (#513a AC4): the same directory the role catalog reads, which ignores these files (it takes `.md` only).
+ * A pack whose roles are not all in the catalog (shipped or project) is refused with the reason, never loaded half-usable. Reasons carry ids, never file contents.
+ */
+export function loadPacks(cwd?: string, shippedPacks: Readonly<Record<string, string>> = SHIPPED_PACKS): PackCatalog {
+  const packs = new Map<string, DomainPack>(), errors: PackCatalog["errors"] = [];
+  // The shipped layer comes first and a project pack of the same name replaces it, as a project role replaces a shipped one. Its roles are checked against the shipped catalog only: it must not depend on a project file.
+  const shipped = loadRoleCatalog();
+  for (const [id, text] of Object.entries(shippedPacks)) {
+    try {
+      const pack = parsePack(text, id, "shipped");
+      const missing = pack.roles.filter(role => !shipped.roles.has(role));
+      if (missing.length) throw new Error(`unknown roles: ${missing.join(", ")}`);
+      packs.set(id, pack);
+    } catch { errors.push({ id, reason: "invalid shipped pack" }); }
+  }
+  if (!cwd) return { packs, errors };
+  const catalog = loadRoleCatalog(cwd);
+  try {
+    const config = join(cwd, ".agenthub"), dir = join(config, "roles");
+    // lstat, never stat: a link is not a directory to lstat, so a symlinked `.agenthub` or `roles` is refused before anything is read through it.
+    for (const path of [config, dir]) if (!lstatSync(path).isDirectory()) throw new Error("unsafe role directory");
+    // ponytail: 16 flat pack files, no recursive scan; an explicit pack index before larger collections.
+    const files = readdirSync(dir).filter(name => name.endsWith(PACK_SUFFIX)).sort();
+    if (files.length > MAX_FILES) throw new Error("too many project packs");
+    for (const file of files) {
+      const id = file.slice(0, -PACK_SUFFIX.length);
+      try {
+        const pack = parsePack(readPack(join(dir, file)), id, "project");
+        const missing = pack.roles.filter(role => !catalog.roles.has(role));
+        if (missing.length) throw new Error(`unknown roles: ${missing.join(", ")}`);
+        packs.set(id, pack);
+      } catch (error) { errors.push({ id: NAME.test(id) ? id : "invalid-file-id", reason: (error as Error).message.slice(0, 200) }); }
+    }
+  } catch (error) { if ((error as NodeJS.ErrnoException).code !== "ENOENT") errors.push({ id: "project", reason: "project pack directory unavailable or unsafe" }); }
+  return { packs, errors };
+}
+
+/** A stable text of plain JSON data: object keys sorted at every depth, array order kept (a checklist's order is its meaning). Two values with the same data compare equal whatever order their keys were written in. */
+export function canonicalJson(value: unknown): string {
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
+  if (value && typeof value === "object") return `{${Object.keys(value).sort().map(key => `${JSON.stringify(key)}:${canonicalJson((value as Record<string, unknown>)[key])}`).join(",")}}`;
+  return JSON.stringify(value) ?? "null";
+}
+
+/** What a pack contributes to the project's `profile_overrides`: the rubric as the profile's review checklist, the checks as advisory examples. Validated by `resolveProfile`. */
+export function packOverrides(pack: DomainPack): Record<string, unknown> {
+  const overrides: Record<string, unknown> = {
+    review_checklist: [...pack.rubric.map(item => `${item.id}${item.required ? "" : " (optional)"}: ${item.text}`), "{check}"],
+    ...(pack.checks.length ? { example_checks: pack.checks.map(check => `${check.id}: ${check.note}`) } : {}),
+  };
+  resolveProfile(pack.profile, overrides);
+  return overrides;
+}

package/src/hub/path-policy.ts

@@ -2,6 +2,13 @@ import { accessSync, constants, lstatSync, opendirSync, readlinkSync, statSync }
 import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { realPath } from "./project.ts";
 import { foldSegment } from "./permission-mode.ts";
+/**
+ * Whether `rel`, the result of `relative(root, path)`, names something inside the root: not `..`, not a path that starts with a `..` SEGMENT, and not absolute.
+ * A string prefix test is wrong here: `..ignored/f.txt` is a valid directory named `..ignored` inside the project (#552), while `../f.txt` leaves it.
+ * An empty `rel` is the root itself, which is inside; callers that need a file name check for it themselves.
+ */
+export const insideRoot = (rel: string): boolean => rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel);
+
 /** Bounded project-relative exact paths/subtrees or *, ? and whole-segment ** globs. */
 export function policyPaths(raw: unknown, field: string): string[] {
   if (raw === undefined) return [];

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);
+  });
+}