@staix/agent-hub 0.19.0 → 0.21.0

package/src/cli/output.ts

@@ -1,3 +1,4 @@
+import type { QueueBackpressureStatus } from "../hub/queue-backpressure.ts";
 import { definitionOf } from "../adapters/registry.ts";
 import { windowKind } from "../hub/window-kind.ts";
 import { boardColumns, type BoardPeerInput } from "../ui/task-board.ts";
@@ -5,17 +6,21 @@ import { peerStyle } from "../ui/peer-palette.ts";
 import { cells, TABLES, table, fitLine, wrap, duration, relative, plural, terminalText, initialConsoleState, stateTone, type Span, type Tone } from "./console-state.ts";
 import { taskProgress } from "../ui/task-progress.ts";
 import { backendLabel } from "./status-lines.ts";
+import { ownerIsolationText } from "./role-holders.ts";
 import { formatReport, formatTaskReport, type Report, type TaskReport } from "../hub/report.ts";
 import type { Counter, LimitsResult, TotalResult, UsageResult } from "../hub/usage-rollup.ts";
 
 export interface DoctorCheck { section: "Tools" | "Hub" | "Config" | "Models" | "Memory"; level: "ok" | "warn" | "fail" | "unknown"; name: string; detail: string }
 export interface StatusOutput {
+  queueBackpressure?: QueueBackpressureStatus;
   pendingRestart?: readonly { key: string; reason: string }[];
   retainedConfig?: readonly { key: string; reason: string }[];
   /** #572 AC3: advisory, present while the project root checkout is on a branch other than the default. */
   mainCheckout?: string;
   /** #843 AC3: installed agent CLIs not on a verified version; ids, version, state and a receipt path only. */
   agentDrift?: readonly { id: string; version: string; state: string; receipt: string }[];
+  /** #512a: one row per machine-local schedule; ids, times and a state only, never task text. */
+  schedules?: readonly { id: string; every: string; class: string; queue: string; next: number; last?: number; task?: number; state: string; coalesced?: number; error?: string }[];
   taskStalls?: readonly { task: number; cause: { kind: string; peer?: string; dependency?: number; code: string } }[];
   pendingTaskOffers?: readonly { task: number; peer: string }[];
   isolatedChecks?: { pending?: number; orphans?: string[]; unknownReceipts?: readonly string[]; maintenanceUnavailable?: boolean };
@@ -24,6 +29,7 @@ export interface StatusOutput {
   /** #784 AC3: `active`, `reviewWait` and `reserved` add up to `wip`; absent from an older hub. */
   taskWip?: Record<string, { wip: number; wipLimit: number; active?: number; reviewWait?: number; reserved?: number }>;
   pid?: number; controlPort?: number; cwd?: string; version?: string; peers: Record<string, any>; roleInfo?: Record<string, any>; actionPolicyInfo?: Record<string, { note: string; enforceable: boolean }>; budget?: Record<string, any>; planner?: { peers?: string[]; source?: string };
+  ownerIsolation?: Record<string, boolean>; ownerIsolationNotes?: Record<string, string>;
   tasks?: Record<string, number>; models?: { backends?: any[] }; permissionDefaults?: any[]; deliveryError?: string; crash?: string[];
 }
 /** `peers`: one note per peer that shows no number, and why (no quota, nothing read yet); absent from an older hub. */
@@ -211,6 +217,20 @@ export function renderStatus(data: StatusOutput, columns?: number, now = Date.no
     out.push(...detail("config retained", `${data.retainedConfig.map(row => row.key).join(", ")}; run ahub settings reload`, columns, "attention"));
     for (const pending of data.retainedConfig) out.push(...detail("retained reason", `${pending.key}: ${pending.reason}`, columns, "attention"));
   }
+  for (const row of data.schedules ?? []) {
+    const when = (at: number) => new Date(at).toISOString().replace("T", " ").slice(0, 16) + "Z";
+    const text = `${row.state === "paused" ? `paused (ahub schedule resume ${row.id}); would be next ${when(row.next)}` : row.state === "scheduled" ? `next ${when(row.next)}` : row.state === "due" ? "due now" : row.state === "waiting" ? `due, waiting for task #${row.task} to close` : "due, held (the hub is stopping or recovering)"}; every ${row.every}; ${row.class} to ${row.queue}${row.last ? `; last ${when(row.last)}${row.task ? ` as task #${row.task}` : ""}` : "; never run"}${row.coalesced ? `; ${row.coalesced} skipped run${row.coalesced === 1 ? "" : "s"} coalesced` : ""}${row.error ? `; last error: ${row.error}` : ""}`;
+    out.push(...detail(`schedule ${row.id}`, text, columns, row.error ? "attention" : undefined));
+  }
+  if (data.queueBackpressure) {
+    const pressure = data.queueBackpressure, policy = pressure.policy;
+    out.push(...detail("queue backpressure", `max queued ${policy.max_queued || "disabled"}; max oldest age ${policy.max_oldest_s ? `${policy.max_oldest_s}s` : "disabled"}; explicit assignment overrides only that role`, columns));
+    for (const [peer, row] of Object.entries(pressure.peers)) {
+      if (row.queued === 0 && !row.blocked) continue;
+      const age = typeof row.oldestAgeMs === "number" && Number.isFinite(row.oldestAgeMs) && row.oldestAgeMs >= 0 ? duration(row.oldestAgeMs) : "unknown";
+      out.push(...detail(`${peer} queue pressure`, `queued ${row.queued ?? "unknown"}; oldest ${age}${row.blocked ? `; automatic offers held: ${row.reason ?? row.code ?? "unknown"}` : ""}`, columns, row.blocked ? "attention" : undefined));
+    }
+  }
   for (const stall of data.taskStalls ?? []) out.push(...detail(`task #${stall.task} stalled`, `${stall.cause.kind}${stall.cause.peer ? ` ${stall.cause.peer}` : ""}${stall.cause.dependency ? ` #${stall.cause.dependency}` : ""}: ${stall.cause.code}; configure the peer, ahub task assign ${stall.task} <peer>, or ahub task cancel ${stall.task} --reason <text>`, columns, "attention"));
   for (const offer of data.pendingTaskOffers ?? []) out.push(...detail("task offer", `open ${offer.peer}: task #${offer.task} is waiting for it`, columns, "attention"));
   if (data.memoryProfile) {
@@ -220,6 +240,10 @@ export function renderStatus(data: StatusOutput, columns?: number, now = Date.no
   }
   if (data.memoryRead?.truncated) out.push(...detail("memory view", `truncated: newest ${data.memoryRead.limit} project candidates considered`, columns, "attention"));
   if (data.planner) out.push(...detail("planner", `${data.planner.peers?.join(", ") || "nobody"} (${data.planner.source ?? "unknown"})${data.planner.source === "automatic" || data.planner.source === "none" ? "; pin it with ahub settings set planner <peer>" : ""}`, columns, data.planner.source === "none" ? "attention" : undefined));
+  for (const [id, isolated] of Object.entries(data.ownerIsolation ?? {})) {
+    const text = ownerIsolationText(isolated, data.ownerIsolationNotes?.[id]);
+    if (text) out.push(...detail(`${id} owner isolation`, text, columns, isolated ? undefined : "attention"));
+  }
   if (data.deliveryError) out.push(...detail("delivery storage", `${data.deliveryError}; dispatch is stopped`, columns, "failure"));
   for (const pending of data.permissionDefaults ?? []) out.push(...detail("permission default", `${pending.peer}: never-ask from ${pending.source}, stays ask until a person confirms in ahub console`, columns, "attention"));
   for (const crash of data.crash ?? []) out.push(...detail("crash recovery", crash, columns, "attention"));
@@ -236,6 +260,8 @@ export function renderStatus(data: StatusOutput, columns?: number, now = Date.no
   let settling = false;
   const peerDetails = Object.entries(data.peers).map(([id, p]) => {
     const out: Span[][] = [];
+    if (typeof p.form === "string") out.push(...detail(`${id} form`, p.form, columns));
+    if (Array.isArray(p.capableRoles)) out.push(...detail(`${id} capable roles`, p.capableRoles.join(", ") || "none", columns));
     if (p.flowRoles) out.push(...detail(`${id} flow roles`, p.flowRoles.join(", ") || "none", columns));
     if (p.catalogRoles) { out.push(...detail(`${id} catalog roles`, Array.isArray(p.catalogRoles.value) ? p.catalogRoles.value.join(", ") || "none" : "unconfirmed", columns)); if (p.catalogRoles.pending !== undefined) out.push(...detail(`${id} pending roles`, p.catalogRoles.pending.join(", ") || "none", columns, "attention")); }
     if (p.liveAccepted?.length) { settling = true; out.push(...detail("settling", p.liveAccepted.map((v: string) => shortId(v, columns, full)).join(", "), columns, "attention")); }
@@ -448,8 +474,11 @@ export function renderTurns(turns: any[], columns?: number, now = Date.now()): S
   return rows(["TURN", "PEER", "STARTED", "STATE", "FILES"], turns.map(turn => {
     const state = !turn.ended ? "running" : !turn.end_tree ? "no end snapshot" : "completed";
     const files = turn.changed ?? [];
+    // #798 D2: a dirty submodule is listed beside the files, tagged, so a turn that edited only a submodule never reads "0 files".
+    const unobserved: string[] = Array.isArray(turn.unobserved) ? turn.unobserved.filter((path: unknown): path is string => typeof path === "string") : [];
+    const shown = [...files, ...unobserved.map(path => `${path} (changed, contents unobserved)`)];
     return [span(turn.id, "info"), span(turn.peer ?? "unknown", peerTone(turn.peer)), span(moment(turn.started, now), "muted"),
-      span(state, state === "running" ? "attention" : state === "no end snapshot" ? "failure" : "success"), { ...span(`${plural(files.length, "file")}${files.length ? `: ${files.join(", ")}` : ""}`), ...(files.length ? { items: files, pathItems: true, prefix: `${plural(files.length, "file")}:` } : {}) }];
+      span(state, state === "running" ? "attention" : state === "no end snapshot" ? "failure" : "success"), { ...span(`${plural(files.length, "file")}${shown.length ? `: ${shown.join(", ")}` : ""}`), ...(shown.length ? { items: shown, pathItems: true, prefix: `${plural(files.length, "file")}:` } : {}) }];
   }), columns);
 }
 export function renderOrphans(orphans: { project: any; pids: number[] }[], columns?: number, _now = Date.now(), killing = false): Span[][] {
@@ -459,6 +488,17 @@ export function renderOrphans(orphans: { project: any; pids: number[] }[], colum
     ...(killing ? [] : [[], ...lines("kill live orphans with ahub doctor --orphans --kill", columns)]),
     ...orphans.flatMap(({ project }) => detail("forget", `ahub projects remove ${project.id}`, columns))];
 }
+/** `ahub doctor --orphans --kill` from the conductor's shell (#812, #899): the hub inspects and stops only its own positively identified process; the shell prints what it answered. */
+export function renderOrphanCleanup(result: unknown, columns?: number, _now = Date.now()): Span[][] {
+  const r = result as any;
+  const stopped: number[] | undefined = Array.isArray(r?.stopped) ? r.stopped.filter((pid: unknown) => typeof pid === "number") : undefined;
+  const out = stopped === undefined ? lines("stopped processes unknown", columns, "attention")
+    : stopped.length ? lines(`stopped ${stopped.length} orphaned hub process${stopped.length === 1 ? "" : "es"}: ${stopped.join(", ")}`, columns, "success")
+    : lines("no orphaned hub process to stop", columns, "muted");
+  if (r?.self === true) out.push(...lines("this hub was itself an orphan and is stopping", columns, "attention"));
+  if (r?.unknown === true) out.push(...lines("a candidate could not be confirmed stopped; a person can inspect it with ahub doctor --orphans", columns, "attention"));
+  return out;
+}
 const TIME_FIELD = /^(?:at|ts|started|ended|created|updated|expires)$|(?:At|Until)$/;
 const ID_FIELD = /^(?:id|trace|previousId|sessionId|threadId|operationId|turnId|envelopeIds)$/;
 /** Labelled scalar leaves preserve the daemon's public view without a raw document or inferred privacy changes. */

package/src/cli/recovery-package.ts

@@ -1,7 +1,7 @@
 import { spawn } from "node:child_process";
 import { createHash, randomUUID } from "node:crypto";
 import { cpSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { dirname, join, resolve } from "node:path";
 import { createRequire } from "node:module";
 import { hubHome, realPath } from "../hub/project.ts";
 
@@ -105,6 +105,23 @@ export function verifyPackage(root: string, version: string, options: { ownDepen
   return packageDigest(root, options);
 }
 
+/** Preserved restart coordinators own their dependency; staged upgrades use the install's hoisted dependency. */
+export function recoveryPackageOptions(kind: "restart" | "upgrade", root: string): { ownDependencies?: boolean; dependencyRoot?: string } {
+  if (kind === "restart") return { ownDependencies: true };
+  if (kind !== "upgrade") throw new Error("unsupported recovery package kind");
+  const canonical = realPath(root), dependencyRoot = resolve(canonical, "../../..");
+  if (canonical !== root || canonical !== join(dependencyRoot, "node_modules", "@staix", "agent-hub")) throw new Error("invalid staged recovery package path");
+  return { dependencyRoot };
+}
+
+export function recoveryTargetDigest(kind: "restart" | "upgrade", root: string): string {
+  return packageDigest(root, recoveryPackageOptions(kind, root));
+}
+
+export function verifyRecoveryTarget(kind: "restart" | "upgrade", root: string, version: string): string {
+  return verifyPackage(root, version, recoveryPackageOptions(kind, root));
+}
+
 export async function registryRelease(version: string, run: RunCommand = runCommand): Promise<{ version: string; integrity: string }> {
   exactVersion(version);
   const result = await run(["npm", "view", `@staix/agent-hub@${version}`, "version", "dist.integrity", "--json"], { timeoutMs: 30_000 });

package/src/cli/role-holders.ts

@@ -0,0 +1,35 @@
+/** Read recorded task-holder metadata only; presentation never chooses a holder or parses note text. */
+export type TaskHolderRole = "planner" | "owner" | "reviewer";
+const word = (value: unknown): string | undefined => typeof value === "string" && value ? value : undefined;
+const entries = (task: any): Record<string, unknown>[] => Array.isArray(task?.history)
+  ? task.history.filter((entry: unknown): entry is Record<string, unknown> => !!entry && typeof entry === "object" && !Array.isArray(entry)) : [];
+
+export function taskHolderText(task: any, role: TaskHolderRole): string {
+  const holder = word(task?.[role]);
+  if (!holder) return role === "owner" && word(task?.reserved) ? `${task.reserved} (reserved)` : "-";
+  const history = entries(task);
+  const reasons: string[] = [];
+  if (role === "planner") {
+    const recorded = history.findLast(entry => entry.planner === holder && word(entry.plannerReason));
+    const reason = word(task?.plannerReason) ?? word(recorded?.plannerReason);
+    if (reason) reasons.push(reason);
+  } else if (role === "reviewer") {
+    const recorded = history.findLast(entry => ["assigned", "reassigned", "escalated", "done", "reviewer changed", "reviewer unavailable"].includes(String(entry.event)));
+    const reason = word(task?.reviewerReason) ?? word(recorded?.reviewerReason) ?? (recorded?.event === "reviewer changed" && recorded.reason === "manual" ? "named" : undefined);
+    if (reason) reasons.push(reason);
+    if (task?.sameFamilyFallback === true && !reasons.includes("same-family fallback")) reasons.push("same-family fallback");
+  } else {
+    const recorded = history.findLast(entry => entry.owner === holder && ["assigned", "reassigned", "escalated", "backlog pulled"].includes(String(entry.event)));
+    const reason = word(task?.ownerReason) ?? (recorded?.reason === "manual" && recorded.event === "reassigned" && word(recorded.by) && recorded.by !== "hub" ? "named" : word(recorded?.reason));
+    if (reason) reasons.push(reason);
+    if (task?.reserved === holder && !reasons.includes("reserved")) reasons.push("reserved");
+  }
+  return `${holder}${reasons.length ? ` (${reasons.join("; ")})` : ""}`;
+}
+
+/** The daemon's per-extra boolean stays boolean on the wire; an absent proof is not a false proof. */
+export function ownerIsolationText(isolated: unknown, reason?: unknown): string | undefined {
+  if (isolated === true) return "isolated";
+  if (isolated === false) return `not isolated: ${word(reason) ?? "execution root not verified"}`;
+  return undefined;
+}

package/src/cli/room.ts

@@ -0,0 +1,304 @@
+import { decodeBase64url } from "../rooms/crypto.ts";
+import { roomReceiptReasonText, type RoomReceiptReason } from "../rooms/application.ts";
+import { frame, type Envelope } from "../hub/envelope.ts";
+import { terminalText } from "./console-state.ts";
+import type { RoomPersonInboxMeta, RoomPersonInboxItem } from "../rooms/store.ts";
+/** Membership mutations and inbox forms are person-only; main.ts refuses agent/live-test calls before importing this module. */
+export const ROOM_USAGE = "usage: ahub room create <name> --broker <url> [--label <id>] | invite <name> [--accept <request>] | join <token> [--name <name>] [--label <id>] | join <name> --roster <signed-roster> | leave <name> | revoke <name> <fingerprint> | expose <name> [<peer>...] | resolve <name> --frame <digest> --action accept|discard (membership mutations and resolve require TTY y/N or --confirm <member-fingerprint-prefix>, 16..64 lowercase hex) | list [--json] | status [<name>] [--json] | inbox [<name>] [--json] | inbox show|done|discard <id>";
+
+type RoomAction = "create" | "invite" | "join" | "leave" | "revoke" | "expose" | "resolve";
+export type RoomCliCommand =
+  | { op: "list" | "status"; input: Record<string, unknown>; json: boolean }
+  | { op: "inbox"; action: "list"; input: { name?: string }; json: boolean }
+  | { op: "inbox"; action: "show" | "done" | "discard"; input: { id: string } }
+  | { op: "mutation"; action: RoomAction; input: Record<string, unknown>; confirm?: string };
+export type RoomRequest = (message: Record<string, unknown>) => Promise<any>;
+/** Fixed host/test I/O only, never a callback selected by project configuration. */
+export interface RoomConfirmationIO { isTTY(): boolean; answer(prompt: string): Promise<string> }
+
+export class RoomCliError extends Error {
+  constructor(readonly code: "usage" | "refused" | "invalid_reply" | "inbox_list_limit" | "confirmation_required" | "not_confirmed" | "confirmation_mismatch") {
+    const message = { refused: "operation refused", invalid_reply: "invalid control reply", inbox_list_limit: "inbox list exceeds the limit; choose a room name", confirmation_required: "confirmation required; use a TTY or --confirm with the member fingerprint prefix", not_confirmed: "not confirmed; nothing executed", confirmation_mismatch: "confirmation does not match the member fingerprint; nothing executed" };
+    super(code === "usage" ? ROOM_USAGE : `room: ${message[code]}`);
+    this.name = "RoomCliError";
+  }
+}
+function fail(code: ConstructorParameters<typeof RoomCliError>[0] = "usage"): never { throw new RoomCliError(code); }
+const ID = /^[a-z][a-z0-9-]{0,31}$/;
+const FP = /^[0-9a-f]{64}$/;
+const B64 = /^[A-Za-z0-9_-]+$/;
+function id(value: string | undefined): string { if (!value || !ID.test(value)) fail(); return value; }
+function artifact(value: string | undefined): string {
+  if (!value || value.length > 699_051 || !B64.test(value) || value.length % 4 === 1) fail();
+  return value;
+}
+function flags(args: readonly string[], allowed: readonly string[], dashValues: readonly string[] = []): Map<string, string> {
+  const result = new Map<string, string>();
+  for (let i = 0; i < args.length; i += 2) {
+    const key = args[i], value = args[i + 1];
+    if (!key || !allowed.includes(key) || !value || value.startsWith("--") && !dashValues.includes(key) || result.has(key)) fail();
+    result.set(key, value);
+  }
+  return result;
+}
+
+/** The parser carries no authorization, filesystem or network effects. The daemon validates every value again. */
+function parseRoomInput(args: readonly string[]): RoomCliCommand {
+  const [action, operand, ...rest] = args;
+  if (action === "list" || action === "status") {
+    const json = args.includes("--json"), values = args.slice(1).filter(value => value !== "--json");
+    if (args.filter(value => value === "--json").length > 1 || values.length > (action === "status" ? 1 : 0)) fail();
+    return { op: action, input: values.length ? { name: id(values[0]) } : {}, json };
+  }
+  if (args.includes("--json")) fail(); // Invitation secrets are never a JSON data format.
+  if (action === "resolve") {
+    const name = id(operand), options = flags(rest, ["--frame", "--action"], ["--frame"]), frame = options.get("--frame"), choice = options.get("--action");
+    if (!frame || frame.length !== 43 || (choice !== "accept" && choice !== "discard")) fail();
+    try { decodeBase64url(frame, 32); } catch { fail(); }
+    return { op: "mutation", action, input: { name, frame, action: choice } };
+  }
+  if (action === "create") {
+    const name = id(operand), options = flags(rest, ["--broker", "--label"]), broker = options.get("--broker");
+    if (!broker || broker.length > 2048) fail();
+    return { op: "mutation", action, input: { name, broker, ...(options.has("--label") ? { label: id(options.get("--label")) } : {}) } };
+  }
+  if (action === "invite") {
+    const name = id(operand), options = flags(rest, ["--accept"]);
+    return { op: "mutation", action, input: { name, ...(options.has("--accept") ? { request: artifact(options.get("--accept")) } : {}) } };
+  }
+  if (action === "join") {
+    const options = flags(rest, ["--roster", "--name", "--label"]);
+    if (options.has("--roster")) {
+      if (options.size !== 1) fail();
+      return { op: "mutation", action, input: { name: id(operand), roster: artifact(options.get("--roster")) } };
+    }
+    return { op: "mutation", action, input: { token: artifact(operand), ...(options.has("--name") ? { name: id(options.get("--name")) } : {}), ...(options.has("--label") ? { label: id(options.get("--label")) } : {}) } };
+  }
+  if (action === "leave") {
+    if (rest.length) fail();
+    return { op: "mutation", action, input: { name: id(operand) } };
+  }
+  if (action === "revoke") {
+    if (rest.length !== 1 || !FP.test(rest[0]!)) fail();
+    return { op: "mutation", action, input: { name: id(operand), member: rest[0] } };
+  }
+  if (action === "expose") {
+    const peers = rest.map(value => id(value));
+    if (peers.length > 64 || new Set(peers).size !== peers.length) fail();
+    return { op: "mutation", action, input: { name: id(operand), peers } };
+  }
+  return fail();
+}
+
+export function parseRoomCommand(args: readonly string[]): RoomCliCommand {
+  if (args[0] === "inbox") {
+    const values = args.slice(1).filter(value => value !== "--json"), json = args.includes("--json");
+    if (args.filter(value => value === "--json").length > 1) fail();
+    if (values.length === 2) {
+      const [action, value] = values;
+      if (json || (action !== "show" && action !== "done" && action !== "discard") || !value || value.length !== 36 || !UUID.test(value)) fail();
+      return { op: "inbox", action, input: { id: value } };
+    }
+    if (values.length > 1) fail();
+    return { op: "inbox", action: "list", input: values.length ? { name: id(values[0]) } : {}, json };
+  }
+  if (args[0] === "list" || args[0] === "status") return parseRoomInput(args);
+  let confirm: string | undefined;
+  const input: string[] = [];
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] !== "--confirm") { input.push(args[i]!); continue; }
+    const value = args[++i];
+    if (confirm !== undefined || !value || !/^[0-9a-f]{16,64}$/.test(value)) fail();
+    confirm = value;
+  }
+  const command = parseRoomInput(input);
+  if (command.op !== "mutation") return fail();
+  return { ...command, ...(confirm !== undefined ? { confirm } : {}) };
+}
+
+const confirmationIO: RoomConfirmationIO = {
+  isTTY: () => process.stdin.isTTY === true && process.stdout.isTTY === true,
+  answer: async prompt => {
+    const { createInterface } = await import("node:readline/promises");
+    const terminal = createInterface({ input: process.stdin, output: process.stdout });
+    const controller = new AbortController(), abort = () => controller.abort();
+    terminal.once("close", abort); terminal.once("SIGINT", abort);
+    try { return await terminal.question(prompt, { signal: controller.signal }); }
+    finally { terminal.off("close", abort); terminal.off("SIGINT", abort); terminal.close(); }
+  },
+};
+async function confirmMember(member: string, explicit: string | undefined, io: RoomConfirmationIO): Promise<string> {
+  if (explicit !== undefined) {
+    if (!member.startsWith(explicit)) fail("confirmation_mismatch");
+    return explicit;
+  }
+  if (!io.isTTY()) fail("confirmation_required");
+  let answer: string;
+  try { answer = await io.answer("Compare both fingerprints out of band. Proceed with this member? [y/N] "); }
+  catch { return fail("not_confirmed"); }
+  if (answer.trim().toLowerCase() !== "y") fail("not_confirmed");
+  return member;
+}
+
+type DeliveryState = "pending" | "dispatching" | "accepted" | "completed" | "completed (admitted)" | "completed (inbox)" | "failed_safe" | "needs_review" | "disposed" | "disposed (accept, by person)" | "disposed (discard, by person)";
+interface DeliveryRow { direction: "inbound" | "outbound"; id: string; application: string; peer: string; state: DeliveryState; disposition?: "accept" | "completed" | "retry" | "discard"; lateReceipt?: "completed (admitted)" | "completed (inbox)" | "failed_safe"; refusalReason?: RoomReceiptReason }
+interface DeliverySummary { direction: "inbound"; pending: number; needsReview: number; truncated: boolean }
+interface RemotePeerRow { id: string; state: "idle" | "busy" | "paused" | "offline" }
+interface RoomRow { name: string; room: string; owner: string; member: string; epoch: string; state: string; deliveries?: (DeliveryRow | DeliverySummary)[]; remotePeers?: RemotePeerRow[] }
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+const REMOTE_ID = /^[a-z][a-z0-9-]{0,31}@[a-z][a-z0-9-]{0,31}$/;
+const REFUSAL_REASONS: readonly RoomReceiptReason[] = ["admitted", "not_exposed", "boundary_refused", "invalid_message", "rate_limited", "hop", "person_inbox_unsupported", "inbox_admitted", "inbox_full", "inbox_oversize", "inbox_expired", "inbox_age_unavailable"];
+const DELIVERY_STATES: readonly string[] = ["pending", "dispatching", "accepted", "completed", "completed (admitted)", "completed (inbox)", "failed_safe", "needs_review", "disposed", "disposed (accept, by person)", "disposed (discard, by person)"];
+function digestId(value: unknown): value is string {
+  if (typeof value !== "string" || value.length !== 43) return false;
+  try { decodeBase64url(value, 32); return true; } catch { return false; }
+}
+function deliveryRows(value: unknown): (DeliveryRow | DeliverySummary)[] {
+  if (!Array.isArray(value) || value.length > 401) return fail("invalid_reply");
+  return value.map<DeliveryRow | DeliverySummary>(item => {
+    const row = record(item);
+    if (row.direction !== "inbound" && row.direction !== "outbound") return fail("invalid_reply");
+    if (row.id === undefined) {
+      if (row.direction !== "inbound" || typeof row.pending !== "number" || !Number.isSafeInteger(row.pending) || row.pending < 0 || row.pending > 10000
+        || typeof row.needsReview !== "number" || !Number.isSafeInteger(row.needsReview) || row.needsReview < 0 || row.needsReview > 10000
+        || typeof row.truncated !== "boolean") return fail("invalid_reply");
+      return { direction: "inbound", pending: row.pending, needsReview: row.needsReview, truncated: row.truncated };
+    }
+    if (typeof row.id !== "string" || !(UUID.test(row.id) || digestId(row.id)) || typeof row.application !== "string" || !UUID.test(row.application)
+      || typeof row.peer !== "string" || !(ID.test(row.peer) || REMOTE_ID.test(row.peer))
+      || typeof row.state !== "string" || !DELIVERY_STATES.includes(row.state)) return fail("invalid_reply");
+    if (row.disposition !== undefined && (typeof row.disposition !== "string" || (row.direction === "inbound" ? !["accept", "discard"].includes(row.disposition) : !["completed", "retry", "discard"].includes(row.disposition)))) return fail("invalid_reply");
+    if (row.lateReceipt !== undefined && row.lateReceipt !== "completed (admitted)" && row.lateReceipt !== "completed (inbox)" && row.lateReceipt !== "failed_safe") return fail("invalid_reply");
+    if (row.refusalReason !== undefined && (typeof row.refusalReason !== "string" || !REFUSAL_REASONS.includes(row.refusalReason as RoomReceiptReason))) return fail("invalid_reply");
+    if (row.direction === "outbound" && row.state.startsWith("disposed")) return fail("invalid_reply");
+    const state = row.state === "completed" ? row.refusalReason === "inbox_admitted" ? "completed (inbox)" : "completed (admitted)" : row.state === "disposed" && row.disposition !== undefined ? `disposed (${row.disposition}, by person)` as DeliveryState : row.state as DeliveryState;
+    return { direction: row.direction, id: row.id, application: row.application, peer: row.peer, state,
+      ...(row.disposition !== undefined ? { disposition: row.disposition as DeliveryRow["disposition"] } : {}), ...(row.lateReceipt !== undefined ? { lateReceipt: row.lateReceipt as DeliveryRow["lateReceipt"] } : {}), ...(row.refusalReason !== undefined ? { refusalReason: row.refusalReason as RoomReceiptReason } : {}) };
+  });
+}
+function remotePeerRows(value: unknown): RemotePeerRow[] {
+  if (!Array.isArray(value) || value.length > 4096) return fail("invalid_reply");
+  return value.map<RemotePeerRow>(item => {
+    const row = record(item);
+    if (typeof row.id !== "string" || !REMOTE_ID.test(row.id) || typeof row.state !== "string" || !["idle", "busy", "paused", "offline"].includes(row.state)) return fail("invalid_reply");
+    return { id: row.id, state: row.state as RemotePeerRow["state"] };
+  });
+}
+function record(value: unknown): Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return fail("invalid_reply");
+  return value as Record<string, unknown>;
+}
+function success(value: unknown): Record<string, unknown> {
+  const row = record(value);
+  if (row.ok !== true) fail("refused");
+  return row;
+}
+function roomRows(value: unknown): RoomRow[] {
+  if (!Array.isArray(value) || value.length > 64) return fail("invalid_reply");
+  return value.map(item => {
+    const row = record(item);
+    if (typeof row.name !== "string" || !ID.test(row.name) || typeof row.room !== "string" || row.room.length !== 43 || !B64.test(row.room)
+      || typeof row.owner !== "string" || !FP.test(row.owner) || typeof row.member !== "string" || !FP.test(row.member)
+      || typeof row.epoch !== "string" || !/^(0|[1-9][0-9]{0,19})$/.test(row.epoch)
+      || typeof row.state !== "string" || !/^[a-z][a-z_-]{0,31}$/.test(row.state)) return fail("invalid_reply");
+    // Ignore all other fields, even from a newer daemon: read output never grows into room bodies or secrets.
+    return { name: row.name, room: row.room, owner: row.owner, member: row.member, epoch: row.epoch, state: row.state,
+      ...(row.deliveries !== undefined ? { deliveries: deliveryRows(row.deliveries) } : {}), ...(row.remotePeers !== undefined ? { remotePeers: remotePeerRows(row.remotePeers) } : {}) };
+  });
+}
+
+const INBOX_LIST_LIMIT = 1100, INBOX_BODY_BYTES = 65536;
+function inboxMeta(value: unknown): RoomPersonInboxMeta {
+  const row = record(value);
+  if (typeof row.id !== "string" || row.id.length !== 36 || !UUID.test(row.id)
+    || typeof row.name !== "string" || row.name.length > 32 || ID.exec(row.name)?.[0] !== row.name
+    || !digestId(row.room) || typeof row.sender !== "string" || row.sender.length !== 64 || !FP.test(row.sender)
+    || typeof row.from !== "string" || row.from.length > 65 || REMOTE_ID.exec(row.from)?.[0] !== row.from
+    || typeof row.receivedAt !== "number" || !Number.isSafeInteger(row.receivedAt) || row.receivedAt < 0
+    || typeof row.expiresAt !== "number" || !Number.isSafeInteger(row.expiresAt) || row.expiresAt < row.receivedAt
+    || typeof row.bytes !== "number" || !Number.isSafeInteger(row.bytes) || row.bytes < 0 || row.bytes > INBOX_BODY_BYTES
+    || (row.state !== "unread" && row.state !== "done" && row.state !== "discarded" && row.state !== "expired")) fail("invalid_reply");
+  // Deliberately never read body, title, debug or other fields on metadata paths.
+  return { id: row.id, name: row.name, room: row.room, sender: row.sender, from: row.from, receivedAt: row.receivedAt,
+    expiresAt: row.expiresAt, bytes: row.bytes, state: row.state };
+}
+function inboxItem(value: unknown, expectedId: string): RoomPersonInboxItem {
+  const meta = inboxMeta(value);
+  if (meta.id !== expectedId) fail("invalid_reply");
+  if (meta.state !== "unread") return meta; // Purged stubs never render an injected body.
+  const body = record(value).body;
+  if (typeof body !== "string" || body.length > INBOX_BODY_BYTES) fail("invalid_reply");
+  const bytes = new TextEncoder().encode(body).byteLength;
+  if (bytes > INBOX_BODY_BYTES || bytes !== meta.bytes) fail("invalid_reply");
+  return { ...meta, body };
+}
+
+async function runInboxCommand(options: Extract<RoomCliCommand, { op: "inbox" }>, request: RoomRequest): Promise<void> {
+  if (options.action === "list") {
+    const reply = record(await request({ t: "room", op: "inbox_list", input: options.input }));
+    if (reply.ok !== true && reply.code === "inbox_list_limit") fail("inbox_list_limit");
+    const value = success(reply).inbox;
+    if (!Array.isArray(value)) fail("invalid_reply");
+    if (value.length > INBOX_LIST_LIMIT) fail("inbox_list_limit");
+    const rows = value.map(inboxMeta);
+    if (new Set(rows.map(row => row.id)).size !== rows.length || options.input.name !== undefined && rows.some(row => row.name !== options.input.name)) fail("invalid_reply");
+    if (options.json) return console.log(JSON.stringify(rows));
+    console.log(`Room inbox (${rows.length})`);
+    for (const row of rows) console.log(`${row.id} ${row.name} ${row.from} ${row.state}; received ${row.receivedAt}; expires ${row.expiresAt}; ${row.bytes} bytes\n  sender ${row.sender}`);
+    return;
+  }
+  const reply = success(await request({ t: "room", op: `inbox_${options.action}`, input: options.input }));
+  if (options.action !== "show") {
+    const item = inboxMeta(reply.item);
+    if (item.id !== options.input.id || item.state === "unread") fail("invalid_reply");
+    console.log(`Room inbox ${item.id}: ${item.state}`);
+    return;
+  }
+  const item = inboxItem(reply.item, options.input.id);
+  if (item.body === undefined) { console.log(`Room inbox ${item.id}: ${item.state} (body unavailable)`); return; }
+  const env: Envelope = { id: item.id, trace: item.id, hop: 0, from: item.from, to: ["user"], kind: "chat", priority: "status", ts: item.receivedAt, body: terminalText(item.body) };
+  console.log(frame(env));
+}
+
+/** Uses one already authenticated control connection so an ephemeral preview ticket cannot cross callers. */
+export async function runRoomCommand(args: readonly string[], request: RoomRequest, io: RoomConfirmationIO = confirmationIO): Promise<void> {
+  const command = parseRoomCommand(args);
+  if (command.op === "inbox") return runInboxCommand(command, request);
+  if (command.op !== "mutation") {
+    const result = success(await request({ t: "room", op: command.op, input: command.input })), rows = roomRows(result.rooms);
+    if (args.includes("--json")) return console.log(JSON.stringify(rows));
+    console.log(`Rooms (${rows.length})`);
+    for (const row of rows) {
+      console.log(`${row.name} ${row.room} epoch ${row.epoch} ${row.state}\n  owner ${row.owner}\n  member ${row.member}`);
+      for (const peer of row.remotePeers ?? []) console.log(`  peer ${peer.id}: ${peer.state}`);
+      for (const delivery of row.deliveries ?? []) {
+        if (!("id" in delivery)) console.log(`  inbound: pending ${delivery.pending}, needs_review ${delivery.needsReview}${delivery.truncated ? "; truncated" : ""}`);
+        else console.log(`  ${delivery.direction} ${delivery.id}: ${delivery.state}; application ${delivery.application}; peer ${delivery.peer}${delivery.disposition ? `; person disposition ${delivery.disposition}` : ""}${delivery.lateReceipt ? `; late receipt evidence ${delivery.lateReceipt}` : ""}${delivery.refusalReason ? `; refusal ${roomReceiptReasonText(delivery.refusalReason)}` : ""}`);
+      }
+    }
+    return;
+  }
+  const preview = success(await request({ t: "room", op: "preview", action: command.action, input: command.input }));
+  if (typeof preview.owner !== "string" || !FP.test(preview.owner) || typeof preview.member !== "string" || !FP.test(preview.member)
+    || typeof preview.ticket !== "string" || !/^[A-Za-z0-9_-]{16,128}$/.test(preview.ticket)) fail("invalid_reply");
+  console.log(`Owner fingerprint: ${preview.owner}`);
+  console.log(`Member fingerprint: ${preview.member}`);
+  const confirm = await confirmMember(preview.member, command.confirm, io);
+  const result = success(await request({ t: "room", op: "execute", ticket: preview.ticket, confirm }));
+  if (result.name !== undefined) {
+    if (typeof result.name !== "string" || !ID.test(result.name)) fail("invalid_reply");
+    console.log(`Room: ${result.name}`);
+  }
+  if (result.artifact !== undefined) {
+    if (typeof result.artifact !== "string") fail("invalid_reply");
+    let encoded: string;
+    try { encoded = artifact(result.artifact); } catch { return fail("invalid_reply"); }
+    console.log("Room artifact (share out of band):");
+    console.log(encoded);
+  } else console.log(command.action === "resolve" && result.kind === "disposed" ? "room resolve: disposed" : `room ${command.action}: complete`);
+}
+
+/** Never echo tokens, broker URLs, daemon payloads or native diagnostics on refusal. */
+export function roomCommandError(error: unknown): string {
+  return error instanceof RoomCliError ? error.message : "room: operation failed";
+}

package/src/cli/say-input.ts

@@ -0,0 +1,16 @@
+import { parseRemotePeerId } from "../rooms/application.ts";
+
+/** Leading @tokens are addresses; malformed remote addresses must never become a broadcast body. */
+export function sayRecipients(args: readonly string[]): { to: string[]; text: string[] } {
+  const to: string[] = [];
+  let count = 0;
+  for (const arg of args) {
+    if (/^@[a-z][a-z0-9-]*$/.test(arg)) { to.push(arg.slice(1)); count++; continue; }
+    if (arg.startsWith("@") && arg.slice(1).includes("@")) {
+      if (!parseRemotePeerId(arg.slice(1))) throw new Error("invalid remote peer address; expected @peer@label");
+      to.push(arg.slice(1)); count++; continue;
+    }
+    break;
+  }
+  return { to, text: args.slice(count) };
+}

package/src/cli/schedule-output.ts

@@ -0,0 +1,49 @@
+// Human output for `ahub schedule list|run|pause|resume` (#335). Pure: parsed hub JSON in, spans out, no I/O. `--json` is the caller's branch and prints the same text.
+// Titles and details are task text and never appear here: a schedule is named by its id, period, class and queue.
+import { blank, grid, heading, pair, s } from "./sdlc-output.ts";
+import { moment } from "./sdlc-output.ts";
+import type { Span, Tone } from "./console-state.ts";
+
+const list = (value: unknown): any[] => Array.isArray(value) ? value : [];
+const TONE: Record<string, Tone | undefined> = { due: "attention", waiting: "attention", held: "attention", paused: "muted", scheduled: undefined };
+const WHEN: Record<string, string> = { scheduled: "next", due: "due now", waiting: "due, waiting for its task to close", held: "due, held (the hub is stopping or recovering)", paused: "paused" };
+
+/** The next run, as the person reads it: a paused schedule says so and what it would have been. */
+export const nextText = (row: any, now: number): string =>
+  row?.state === "paused" ? `paused (would be ${moment(row.next, now)})` : row?.state === "scheduled" ? moment(row.next, now) : WHEN[row?.state] ?? "unknown";
+
+/** `ahub schedule list`: one row per configured schedule with its next run. */
+export function renderScheduleList(rows: unknown, columns?: number, now = Date.now()): Span[][] {
+  const schedules = list(rows);
+  if (!schedules.length) return [[s("no schedules configured; add them under `schedules` in .agenthub/config.local.json", "muted")]];
+  const out: Span[][] = [...heading(`Schedules (${schedules.length})`, columns)];
+  out.push(...grid(["ID", "EVERY", "CLASS", "QUEUE", "STATE", "NEXT RUN", "LAST RUN", "TASK"], schedules.map((row: any) => [
+    s(row.id, "issueRef"), s(row.every), s(row.class), s(row.queue), s(row.state, TONE[row.state]), s(nextText(row, now), TONE[row.state]),
+    s(row.last ? moment(row.last, now) : "never", "muted"), s(row.task === undefined ? "-" : `#${row.task}`, "taskRef"),
+  ]), columns));
+  for (const row of schedules) {
+    if (row.coalesced) out.push(blank, ...pair(row.id, `${row.coalesced} due tick${row.coalesced === 1 ? "" : "s"} skipped; one run follows when it can`, columns, 12, "muted"));
+    if (row.error) out.push(blank, ...pair(row.id, `last run failed: ${row.error}`, columns, 12, "attention"));
+  }
+  return out;
+}
+
+const RESULT: Record<string, string> = { changed: "not run: it was paused or resumed meanwhile", ran: "ran", held: "not run: the hub is held (stopping or recovering)", waiting: "not run: the task its last run made is still open", failed: "failed" };
+
+/** `ahub schedule run <id>`: what the run did. */
+export function renderScheduleRun(result: unknown, columns?: number): Span[][] {
+  const r = result as any;
+  const out: Span[][] = [...heading(`Schedule ${r?.id ?? "?"}: ${RESULT[r?.outcome] ?? "unknown outcome"}`, columns)];
+  if (r?.task !== undefined) out.push(...pair("task", `#${r.task}`, columns, 8, "taskRef"));
+  if (r?.reason) out.push(...pair("because", String(r.reason), columns, 8, "attention"));
+  if (r?.outcome === "ran") out.push(...pair("next", "its period restarts now", columns, 8, "muted"));
+  return out;
+}
+
+/** `ahub schedule pause|resume <id>`: the schedule as the hub now holds it. */
+export function renderScheduleChange(op: "pause" | "resume", rows: unknown, columns?: number, now = Date.now()): Span[][] {
+  const row = list(rows)[0];
+  const out: Span[][] = [...heading(`Schedule ${row?.id ?? "?"} ${op === "pause" ? "paused" : "resumed"}`, columns)];
+  if (row) out.push(...pair("state", row.state, columns, 8, TONE[row.state]), ...pair("next run", nextText(row, now), columns, 8));
+  return out;
+}