@staix/agent-hub 0.30.0 → 0.31.0

package/src/hub/memory-sync-policy.ts

@@ -0,0 +1,109 @@
+import { configuredPolicy, inspectSyncPolicy, looksSecret, memoryPolicySnapshot, type MemoryStore } from "@staix/agent-mem";
+import { createHash } from "node:crypto";
+import { types } from "node:util";
+
+/** Fields produced by agent-mem itself. Every other field is outbound text, including fields this hub has not seen yet. */
+// ponytail: preserve #1189 write-input metadata stripping. SDK-canonical callbacks bypass it; migrate write inputs to syncOutboundContent only after a note-input compatibility proof.
+const GENERATED = new Set(["id", "schema", "op", "at", "machine", "actor", "target", "promotedFrom", "supersedes", "expires", "by", "tier", "scope", "kind", "source"]);
+const hostRule = (value: string | undefined): string => value === "hub privacy policy: PII pattern or private path"
+  ? value : "hub privacy policy";
+
+export function projectMemorySyncText(row: Record<string, unknown>, canonical = false): Record<string, unknown> {
+  if (!row || typeof row !== "object" || Array.isArray(row) || types.isProxy(row)) throw new Error("invalid memory sync row");
+  const prototype = Object.getPrototypeOf(row);
+  if (prototype !== Object.prototype && prototype !== null || Object.getOwnPropertySymbols(row).length) throw new Error("invalid memory sync row");
+  const descriptors = Object.getOwnPropertyDescriptors(row);
+  const text = Object.create(null) as Record<string, unknown>;
+  for (const [key, descriptor] of Object.entries(descriptors)) {
+    if (!descriptor.enumerable || !("value" in descriptor)) throw new Error("invalid memory sync row");
+    if (canonical || !GENERATED.has(key)) Object.defineProperty(text, key, { value: descriptor.value, enumerable: true, configurable: true, writable: true });
+  }
+  return text;
+}
+
+export type MemorySyncHostScreen = (row: Record<string, unknown>) => { ok: boolean; rule?: string };
+export type MemorySyncPolicyResult = { ok: true } | { ok: false; rule: string };
+
+export interface MemorySyncPolicyOptions {
+  home: string;
+  cwd?: string;
+  /** Additional host deny paths and patterns. Machine and repository policy is always loaded and retained. */
+  denyPaths?: readonly string[];
+  piiPatterns?: readonly string[];
+  /** Hub-owned narrowing policy (routing PII and project-private paths). */
+  hostScreen?: MemorySyncHostScreen;
+}
+
+/**
+ * The outbound screen used by agent-mem sync, plus the hub's narrower privacy rules.
+ * Machine and repository policy remains authoritative through the public configuredPolicy API.
+ */
+export function createMemorySyncPolicy(options: MemorySyncPolicyOptions): { screen(row: Record<string, unknown>, canonical?: boolean): MemorySyncPolicyResult } {
+  const standalone = configuredPolicy(options.home, options.cwd, { denyPaths: options.denyPaths, piiPatterns: options.piiPatterns });
+  return {
+    screen(row, canonical = false) {
+      let text: Record<string, unknown>;
+      try { text = projectMemorySyncText(row, canonical); } catch { return { ok: false, rule: "configured standalone policy: invalid input" }; }
+      let accepted: boolean;
+      try { accepted = standalone.screenStandalone(text); } catch { return { ok: false, rule: "configured standalone policy: invalid input" }; }
+      if (!accepted) {
+        const safe = memoryPolicySnapshot(text);
+        const serialized = safe === undefined ? undefined : safeJson(safe);
+        const rule = serialized !== undefined && looksSecret(serialized)
+          ? "configured standalone policy: secret"
+          : standalone.declinesPersonal(serialized ?? "")
+            ? "configured standalone policy: personal data, configured pattern, or deny path"
+            : "configured standalone policy: privacy rule";
+        return { ok: false, rule };
+      }
+      if (options.hostScreen) {
+        let host: unknown;
+        try { host = options.hostScreen(text); } catch { return { ok: false, rule: "hub privacy policy unavailable" }; }
+        const result = safeHostResult(host);
+        if (!result) return { ok: false, rule: "hub privacy policy unavailable" };
+        if (result.ok !== true) return { ok: false, rule: hostRule(result.rule) };
+      }
+      return { ok: true };
+    },
+  };
+}
+
+function safeJson(value: unknown): string | undefined {
+  try { return JSON.stringify(value); } catch { return undefined; }
+}
+
+function safeHostResult(value: unknown): { ok: boolean; rule?: string } | undefined {
+  if (!value || typeof value !== "object" || Array.isArray(value) || types.isProxy(value)) return undefined;
+  const prototype = Object.getPrototypeOf(value);
+  if (prototype !== Object.prototype && prototype !== null || Object.getOwnPropertySymbols(value).length) return undefined;
+  const descriptors = Object.getOwnPropertyDescriptors(value);
+  if (Object.keys(descriptors).some(key => !["ok", "rule"].includes(key))) return undefined;
+  for (const descriptor of Object.values(descriptors)) if (!descriptor.enumerable || !("value" in descriptor)) return undefined;
+  const ok = descriptors.ok?.value;
+  const rule = descriptors.rule?.value;
+  if (typeof ok !== "boolean" || rule !== undefined && typeof rule !== "string") return undefined;
+  return { ok, ...(typeof rule === "string" ? { rule } : {}) };
+}
+
+/** Project the package's bounded physical-row inspection into IDs and public rule categories only. */
+export function inspectDeclinedMemoryRows(store: MemoryStore, policy: ReturnType<typeof createMemorySyncPolicy>, policyVersion?: () => string): {
+  rows: { id: string; rule: string }[];
+  declinedIdsFingerprint: string;
+  complete: boolean;
+  reason?: string;
+} {
+  const report = inspectSyncPolicy(store, {
+    screen: row => policy.screen(row, true).ok,
+    ...(policyVersion ? { policyVersion } : {}),
+  });
+  if (!report.complete) return { rows: [], declinedIdsFingerprint: fingerprint([]), complete: false, reason: report.reason };
+  return {
+    rows: report.declined.map(row => ({ id: row.id, rule: row.categories.join(", ") })),
+    declinedIdsFingerprint: report.fingerprint,
+    complete: true,
+  };
+}
+
+function fingerprint(rows: readonly { id: string }[]): string {
+  return createHash("sha256").update([...rows.map(row => row.id)].sort().join("\n")).digest("hex");
+}

package/src/hub/memory-sync-state.ts

@@ -0,0 +1,145 @@
+import { createHash } from "node:crypto";
+
+/** Safe, process-local view of the most recent machine memory sync. */
+export type MemorySyncCause = "declined" | "remote" | "binding" | "stopped" | "transport" | "unknown";
+export interface MemorySyncPlacementCounts { withheldCount: number; exportedCount: number }
+export type MemorySyncOutcome =
+  | { state: "notrun" }
+  | { state: "not-configured"; at: number }
+  | { state: "stopped"; at: number }
+  | { state: "ok"; at: number; withheldCount?: number; exportedCount?: number }
+  | { state: "failed"; at: number; cause: MemorySyncCause; declinedCount?: number; declinedIdsKnown?: false; placementActive?: false };
+
+export interface MemorySyncState {
+  outcome: MemorySyncOutcome;
+  /** Private dedupe key: never include this in a status or log line. */
+  failureSignature?: string;
+}
+
+export type MemorySyncEvent =
+  | { type: "success"; at: number; withheldCount?: number; exportedCount?: number }
+  | { type: "quiet"; at: number; state: "not-configured" | "stopped" }
+  | { type: "failure"; at: number; cause: MemorySyncCause; declinedCount?: number; declinedIdsFingerprint?: string; declinedIdsKnown?: false; failureDetailHash?: string; placementActive?: false };
+
+export const initialMemorySyncState = (): MemorySyncState => ({ outcome: { state: "notrun" } });
+const MAX_DECLINED_ROWS = 20_000;
+
+function placementCounts(withheldCount: unknown, exportedCount: unknown): MemorySyncPlacementCounts | undefined {
+  if (typeof withheldCount !== "number" || !Number.isSafeInteger(withheldCount) || withheldCount < 0
+    || typeof exportedCount !== "number" || !Number.isSafeInteger(exportedCount) || exportedCount < 0) return undefined;
+  return { withheldCount, exportedCount };
+}
+
+/** Project only public counts from a completed placement publication, never its retained hashes or policy metadata. */
+export function memorySyncPlacementCounts(value: unknown): MemorySyncPlacementCounts | undefined {
+  try {
+    if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype !== Object.prototype && prototype !== null) return undefined;
+    const read = (key: string): unknown => {
+      const field = Object.getOwnPropertyDescriptor(value, key);
+      return field?.enumerable && "value" in field ? field.value : undefined;
+    };
+    const outcome = read("outcome");
+    if (outcome !== "committed" && outcome !== "not-needed") return undefined;
+    return placementCounts(read("withheld"), read("exported"));
+  } catch { return undefined; }
+}
+
+/** Reduces one completed sync. The boolean says whether this failure is a new loggable episode. */
+export function reduceMemorySync(state: MemorySyncState, event: MemorySyncEvent): { state: MemorySyncState; logFailure: boolean } {
+  if (event.type === "success") return { state: { outcome: { state: "ok", at: event.at, ...placementCounts(event.withheldCount, event.exportedCount) } }, logFailure: false };
+  if (event.type === "quiet") return { state: { outcome: { state: event.state, at: event.at } }, logFailure: false };
+  const signature = [event.cause, event.declinedCount ?? "", event.declinedIdsFingerprint ?? (event.declinedIdsKnown === false ? "ids-unknown" : ""), event.failureDetailHash ?? ""].join("\0");
+  const changed = state.failureSignature !== signature;
+  return {
+    state: { outcome: { state: "failed", at: event.at, cause: event.cause, ...(event.declinedCount === undefined ? {} : { declinedCount: event.declinedCount }), ...(event.declinedIdsKnown === false ? { declinedIdsKnown: false as const } : {}), ...(event.cause === "declined" && event.placementActive === false ? { placementActive: false as const } : {}) }, failureSignature: signature },
+    logFailure: changed,
+  };
+}
+
+export interface MemorySyncView {
+  state: "disabled" | "unavailable" | "notrun" | "not-configured" | "stopped" | "ok" | "failed" | "unknown";
+  at?: number;
+  cause?: MemorySyncCause;
+  declinedCount?: number;
+  declinedIdsKnown?: false;
+  withheldCount?: number;
+  exportedCount?: number;
+  placementActive?: false;
+  nextStep?: string;
+}
+
+export function memorySyncNextStep(cause: MemorySyncCause): string {
+  return cause === "declined" ? "ahub memory declined"
+    : cause === "remote" ? "configure a private sync remote"
+    : cause === "binding" ? "ahub memory profile-check"
+    : cause === "stopped" ? "retry after hub restart"
+    : "run ahub memory sync as a person";
+}
+
+/** Public status projection. It never includes an id, error string, path, home or fingerprint. */
+export function memorySyncView(state: MemorySyncState, availability: "enabled" | "disabled" | "unavailable" | "unknown"): MemorySyncView {
+  if (availability !== "enabled") return { state: availability };
+  const outcome = state.outcome;
+  if (outcome.state === "notrun") return { state: "notrun" };
+  if (outcome.state === "not-configured") return { state: "not-configured", at: outcome.at, nextStep: memorySyncNextStep("remote") };
+  if (outcome.state === "stopped") return { state: "stopped", at: outcome.at, nextStep: memorySyncNextStep("stopped") };
+  if (outcome.state === "ok") return { state: "ok", at: outcome.at, ...placementCounts(outcome.withheldCount, outcome.exportedCount) };
+  return {
+    state: "failed", at: outcome.at, cause: outcome.cause,
+    ...(outcome.declinedCount === undefined ? {} : { declinedCount: outcome.declinedCount }),
+    ...(outcome.declinedIdsKnown === false ? { declinedIdsKnown: false } : {}),
+    ...(outcome.cause === "declined" && outcome.placementActive === false ? { placementActive: false } : {}),
+    nextStep: memorySyncNextStep(outcome.cause),
+  };
+}
+
+/** Map the upstream free-form reason into a closed, non-sensitive status cause. */
+export function classifyMemorySyncFailure(error: unknown): { cause: "declined"; declinedCount: number } | { cause: Exclude<MemorySyncCause, "declined">; declinedCount?: never } {
+  const text = typeof error === "string" ? error : "";
+  const declined = /^the configured privacy policy declines (\d+) long-term entr(y|ies) \([^()\r\n]*\); fix the entry or the policy, then sync again$/.exec(text);
+  if (declined) {
+    const count = Number(declined[1]);
+    const singular = declined[2] === "y";
+    if (Number.isSafeInteger(count) && count > 0 && count <= MAX_DECLINED_ROWS && (count === 1) === singular)
+      return { cause: "declined", declinedCount: count };
+    return { cause: "unknown" };
+  }
+  if (text === "stopped") return { cause: "stopped" };
+  if (text === "no sync remote: a person sets one with `amem sync --remote <private git url>`"
+    || text === "no generation sync remote configured"
+    || text === "the sync remote is public; memory syncs only to a private remote"
+    || text === "generation sync remote is invalid"
+    || text === "generation sync requires positively verified private remote visibility"
+    || text === "generation remote lookup failed"
+    || text === "generation remote branch identity mismatch") return { cause: "remote" };
+  if (text === "binding changed" || text === "sharded sync binding or policy unavailable or changed"
+    || text === "generation profile unavailable") return { cause: "binding" };
+  if (["git init failed: ", "the remote could not be set: ", "git add failed: ", "commit failed: ", "fetch failed: ", "checkout failed: ", "merge failed: ", "push failed: ",
+    "generation staging failed", "generation commit failed", "generation fetch failed", "generation push failed"].some(prefix => text.startsWith(prefix))) return { cause: "transport" };
+  return { cause: "unknown" };
+}
+export function memorySyncFailureDetailHash(error: unknown): string {
+  const canonical = typeof error === "string" ? error : "<missing-or-non-string-error>";
+  return createHash("sha256").update(canonical).digest("hex");
+}
+
+export interface DeclinedMemoryInspection {
+  rows: readonly { id: string }[];
+  declinedIdsFingerprint: string;
+  complete: boolean;
+}
+
+/** Use complete all-target inspection when available; otherwise keep the package's first-target count and say ids are unknown. */
+export function memorySyncDeclinedDetails(
+  canonical: { cause: "declined"; declinedCount: number },
+  inspection?: DeclinedMemoryInspection,
+): { cause: "declined"; declinedCount: number; declinedIdsFingerprint?: string; declinedIdsKnown?: false } {
+  const fingerprintValid = /^[a-f0-9]{64}$/.test(inspection?.declinedIdsFingerprint ?? "");
+  const idsAvailable = !!inspection && inspection.rows.every(row => typeof row.id === "string" && row.id !== "(no id)");
+  if (inspection?.complete && inspection.rows.length > 0 && inspection.rows.length <= MAX_DECLINED_ROWS && fingerprintValid && idsAvailable) {
+    return { cause: "declined", declinedCount: inspection.rows.length, declinedIdsFingerprint: inspection.declinedIdsFingerprint };
+  }
+  return { ...canonical, declinedIdsKnown: false };
+}

package/src/hub/no-writes.ts

@@ -37,7 +37,7 @@ export class NoWriteTurns {
 }
 
 
-const OWNER_TOOL_EFFECTS = new Set(["hub_task_propose", "hub_task_decline", "hub_task_done", "hub_task_cancel", "hub_task_assign", "hub_task_escalate", "hub_review", "hub_checkpoint", "hub_remember", "hub_memory_correct", "hub_check_start", "hub_check_cancel", "hub_sdlc_record", "hub_plan_review", "hub_backlog_plan", "hub_backlog_pull", "hub_backlog_undo", "hub_backlog_split", "hub_backlog_return_untouched", "hub_release_new", "hub_release_configure", "hub_release_assign", "hub_release_cut", "hub_study_handoff", "hub_experiment_record"]);
+const OWNER_TOOL_EFFECTS = new Set(["hub_task_propose", "hub_task_decline", "hub_task_done", "hub_task_cancel", "hub_task_assign", "hub_task_escalate", "hub_review", "hub_checkpoint", "hub_remember", "hub_memory_correct", "hub_check_start", "hub_check_cancel", "hub_sdlc_record", "hub_plan_review", "hub_backlog_plan", "hub_backlog_pull", "hub_backlog_undo", "hub_backlog_split", "hub_backlog_return_untouched", "hub_release_new", "hub_release_configure", "hub_release_assign", "hub_release_cut", "hub_study_handoff", "hub_experiment_record", "hub_evidence_record"]);
 /** A read does not prove progress; failed/pending mutations are handled conservatively by the host. */
 export function ownerToolEffect(op: string, input: Record<string, unknown> | undefined): boolean {
   return OWNER_TOOL_EFFECTS.has(op) || op === "hub_task_accept" && !!input?.plan && typeof input.plan === "object" && Object.keys(input.plan).length > 0;

package/src/hub/operational-settings.ts

@@ -79,6 +79,14 @@ export const BUS_TERMINAL_HISTORY_LIMIT_SETTING = busNumber({
   key: "bus.terminal_history_limit", path: ["bus", "terminal_history_limit"], label: "Unprotected terminal delivery history target",
   max: 2048, defaultValue: 2048, unit: "rows", inventory: "src/hub/delivery-journal.ts:TERMINAL_CAP",
 });
+/** #1172: bounded wait for a push channel's explicit native delivery confirmation. */
+export const BUS_ACCEPTED_SETTLE_MS_SETTING = {
+  ...busNumber({
+    key: "bus.accepted_settle_ms", path: ["bus", "accepted_settle_ms"], label: "Accepted channel delivery confirmation timeout",
+    max: 86_400_000, defaultValue: 600_000, unit: "milliseconds", inventory: "src/hub/operational-settings.ts:BUS_ACCEPTED_SETTLE_MS_SETTING.defaultValue",
+  }),
+  min: 1000,
+} as const satisfies OperationalNumberSetting;
 
 /**
  * #489 H4, recovery and upgrade waits. These are read by the upgrade coordinator (a CLI process) from the project's own config at the START of each wait, so a change applies at the next wait and a wait
@@ -178,7 +186,7 @@ export const CONSOLE_ATTENTION_SETTING = consoleNumber({
 
 /** 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,
-  BUS_MAX_ATTEMPTS_SETTING, BUS_DIGEST_MAX_SETTING, BUS_PULL_BUDGET_BYTES_SETTING, BUS_NOTES_KEPT_SETTING, BUS_TERMINAL_HISTORY_LIMIT_SETTING,
+  BUS_MAX_ATTEMPTS_SETTING, BUS_DIGEST_MAX_SETTING, BUS_PULL_BUDGET_BYTES_SETTING, BUS_NOTES_KEPT_SETTING, BUS_TERMINAL_HISTORY_LIMIT_SETTING, BUS_ACCEPTED_SETTLE_MS_SETTING,
   RECOVERY_RECONNECT_WAIT_SETTING, RECOVERY_UNMANAGED_RECONNECT_WAIT_SETTING, RECOVERY_CONTROL_TIMEOUT_SETTING, RECOVERY_SHUTDOWN_WAIT_SETTING, RECOVERY_TERMINAL_IDLE_WAIT_SETTING,
   ACP_TOOL_CEILING_SETTING, ACP_ACTIVITY_BATCH_SETTING, JCODE_STEER_TIMEOUT_SETTING,
   MODEL_COOLDOWN_FAILURES_SETTING, MODEL_COOLDOWN_SETTING, MODEL_COOLDOWN_CAP_SETTING, MODEL_TERMINAL_HISTORY_SETTING, INFERENCE_BACKOFF_SETTING, INFERENCE_DIGEST_ITEMS_SETTING, INFERENCE_DIGEST_CHARS_SETTING,
@@ -197,7 +205,7 @@ export const taskOperationalReaders = (config: () => TaskOperationalConfig) => (
   splitMinObservations: () => config().tasks.split_min_observations ?? SPLIT_MIN_SETTING.defaultValue,
   splitMaxFailureShare: () => config().tasks.split_max_failure_share ?? SPLIT_FAILURE_SHARE_SETTING.defaultValue,
 });
-export interface BusOperationalConfig { bus?: { max_attempts?: number; digest_max?: number; pull_budget_bytes?: number; notes_kept?: number; terminal_history_limit?: number } }
+export interface BusOperationalConfig { bus?: { max_attempts?: number; digest_max?: number; pull_budget_bytes?: number; notes_kept?: number; terminal_history_limit?: number; accepted_settle_ms?: number } }
 /** Read accepted configuration at the next operation; a reload itself never trims or retries work. */
 export const busOperationalReaders = (config: () => BusOperationalConfig) => ({
   maxAttempts: () => config().bus?.max_attempts ?? BUS_MAX_ATTEMPTS_SETTING.defaultValue,
@@ -205,6 +213,7 @@ export const busOperationalReaders = (config: () => BusOperationalConfig) => ({
   pullBudgetBytes: () => config().bus?.pull_budget_bytes ?? BUS_PULL_BUDGET_BYTES_SETTING.defaultValue,
   notesKept: () => config().bus?.notes_kept ?? BUS_NOTES_KEPT_SETTING.defaultValue,
   terminalHistoryLimit: () => config().bus?.terminal_history_limit ?? BUS_TERMINAL_HISTORY_LIMIT_SETTING.defaultValue,
+  acceptedSettleMs: () => config().bus?.accepted_settle_ms ?? BUS_ACCEPTED_SETTLE_MS_SETTING.defaultValue,
 });
 export interface RecoveryOperationalConfig { recovery?: { reconnect_wait_s?: unknown; unmanaged_reconnect_wait_s?: unknown; control_timeout_s?: unknown; shutdown_wait_s?: unknown; terminal_idle_wait_s?: unknown } }
 export interface RecoveryWaits { reconnectWaitMs: number; unmanagedReconnectWaitMs: number; controlTimeoutMs: number; shutdownWaitMs: number; terminalIdleWaitMs: number }

package/src/hub/operational-view.ts

@@ -1,3 +1,4 @@
+import { isReviewObserverExcluded } from "./memory-policy.ts";
 import { sanitize } from "./envelope.ts";
 import type { BusEvent } from "./bus.ts";
 import { CLASSES, type Task } from "./board.ts";
@@ -77,7 +78,17 @@ function metadataValue(type:string,key:string,value:unknown):boolean {
 
 /** Shared by the daemon's existing console stream and operational projection tests. */
 export function redactBusEvent(e:BusEvent):BusEvent {
-  if (!("env" in e) || !e.env.private) return e;
+  if (!("env" in e)) return e;
+  if (isReviewObserverExcluded(e.env)) {
+    const { refs, ...env } = e.env;
+    return { ...e, env: { ...env, refs: { ...(refs?.reviewPackage ? { reviewPackage: refs.reviewPackage } : {}), ...(refs?.reviewResponse ? { reviewResponse: refs.reviewResponse } : {}), ...(refs?.task && /^[0-9]+$/.test(refs.task) ? { task: refs.task } : {}) }, body: "[review package: inspect task review comments]" } };
+  }
+  // #1053: the person's answer to a question is theirs and the asking peer's: the console tail and the dashboard feed show a stub, whoever the envelope is private for.
+  if (e.env.kind === "answer" || e.env.refs?.question) {
+    const set = e.env.refs?.question;
+    return { ...e, env: { ...e.env, refs: set ? { question: set } : undefined, body: `[question ${set ?? "answer"}: body shown only to its peer]` } };
+  }
+  if (!e.env.private) return e;
   const {refs,...env}=e.env;
   const task=refs?.task && /^[0-9]+$/.test(refs.task)?refs.task:undefined;
   return {...e,env:{...env,...(task?{refs:{task}}:{}),body:`[private${task?`: task #${task}, see ahub task show ${task}`:""}]`}};

package/src/hub/peers.ts

@@ -1,3 +1,4 @@
+import type { DeliveryFailureCause } from "./delivery-failure.ts";
 import type { Envelope, EnvelopeOpts, PeerId, PeerState } from "./envelope.ts";
 import type { PermissionMode } from "./permission-mode.ts";
 import type { StartForm } from "../adapters/registry-types.ts";
@@ -9,6 +10,8 @@ export interface DeliveryReceipt {
   id: string;
   state: "accepted" | "completed" | "failed_safe" | "needs_review";
   reason?: string;
+  /** Public-safe transport cause only, never native error text. */
+  failureCause?: DeliveryFailureCause;
   /** A provider refused before acceptance for quota; requeue without spending poison retries while paused. */
   quota?: true;
 }
@@ -18,6 +21,18 @@ export interface OwnedToolsLaunch {
   launchId: string; generation: string; sessionId: string; signal: AbortSignal; task?: number; permissionHook: true;
 }
 
+/** Display-only identity for a live channel connection waiting for a person's handover. */
+export interface PeerStandbySession { id: string; pid?: number; since: number; }
+
+/** Opaque, generation-fenced claim produced by a peer's person-requested takeover port. */
+export interface PeerTakeoverClaim {
+  standbyId: string;
+  socket: object;
+  generation: string | number;
+  isCurrent(): boolean;
+  attach(): boolean;
+}
+
 export interface FrontendProxyPort {
   readonly url: string;
   readonly attached: boolean;
@@ -29,6 +44,14 @@ export interface FrontendProxyPort {
 
 export interface PeerAdapter {
   readonly id: PeerId;
+  /** Live waiting sessions, for display only; ids and pids grant no native identity or authority. */
+  readonly standbySessions?: readonly PeerStandbySession[];
+  /** Person-authorized takeover port. The host still performs its own admission and claim fences. */
+  takeover?(standbyId: string | undefined, eligible: (socket: object) => boolean): PeerTakeoverClaim | undefined;
+  /** Exact transport ownership check for guarding a selected standby through its asynchronous preface. */
+  ownsSocket?(socket: object): boolean;
+  /** The explicit own-delivery settlement surface; only a live push channel session opts in. */
+  readonly acceptedSettlement?: "explicit";
   /** 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. */
@@ -95,7 +118,7 @@ export interface PeerAdapter {
   /** Set by the bus. */
   onState?: (state: PeerState) => void;
   /** Set by the bus. A delivery that had resolved turned out not to reach the agent: put it back. */
-  onFailed?: (envs: Envelope[], failure?: { quota?: true }) => void;
+  onFailed?: (envs: Envelope[], failure?: { quota?: true; failureCause?: DeliveryFailureCause }) => 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. */
@@ -113,7 +136,7 @@ export abstract class BasePeer implements PeerAdapter {
   /** Returns a reason (a string) when the hub refused the message (issue #38). */
   onMessage?: (body: string, opts?: EnvelopeOpts) => unknown;
   onState?: (state: PeerState) => void;
-  onFailed?: (envs: Envelope[], failure?: { quota?: true }) => void;
+  onFailed?: (envs: Envelope[], failure?: { quota?: true; failureCause?: DeliveryFailureCause }) => void;
   onDelivery?: (receipt: DeliveryReceipt) => void;
   onDoing?: (kind: DoingKind, text?: unknown) => void;
   private _state: PeerState = "offline";

package/src/hub/planning.ts

@@ -4,7 +4,7 @@ import type { Task } from "./board.ts";
 
 export const BACKLOG_SPLIT_SCREEN_TIMEOUT_MS = 8000;
 
-export const PLANNING_FIELDS = ["rank", "priority", "release", "plannedStart", "due", "pinned", "deps", "reserved", "sdlc"] as const;
+export const PLANNING_FIELDS = ["rank", "priority", "release", "plannedStart", "due", "pinned", "needsPerson", "deps", "reserved", "sdlc"] as const;
 export interface PlanningFields {
   rank?: number | null;
   priority?: number | null;
@@ -12,6 +12,8 @@ export interface PlanningFields {
   plannedStart?: number | null;
   due?: number | null;
   pinned?: boolean;
+  /** #1176: a leg only the person can run (live receipts, their accounts, machines or approvals). It keeps its reservation as the "who will run it" hint, but no agent is ever offered it. */
+  needsPerson?: boolean;
   deps?: number[];
   reserved?: string | null;
   sdlc?: PlanningIssueIdentity;
@@ -61,6 +63,9 @@ export function planningPatch(input: unknown = {}): PlanningPatch {
     } else if (key === "pinned") {
       if (typeof value !== "boolean") throw new Error("pinned must be a boolean");
       result.pinned = value;
+    } else if (key === "needsPerson") {
+      if (typeof value !== "boolean") throw new Error("needsPerson must be a boolean");
+      result.needsPerson = value;
     } else {
       if (value !== null && (typeof value !== "number" || !Number.isSafeInteger(value) || value < (key === "release" || key === "plannedStart" || key === "due" ? 1 : 0) || (key === "priority" && value > 3) || (["plannedStart", "due"].includes(key) && value > 8_640_000_000_000_000))) throw new Error(`invalid planning field ${key}`);
       result[key] = value as number | null;

package/src/hub/question-desk.ts

@@ -0,0 +1,201 @@
+import { HUB, newEnvelope, USER, type Envelope, type PeerId } from "./envelope.ts";
+import { PreEffectToolRefusal } from "./tool-refusal.ts";
+import { QuestionWaitDetached } from "./question-detach.ts";
+import { parseAsk, QUESTION_SET, type AnswerResult, type QuestionAnswer, type QuestionReason, type QuestionRow, type QuestionStore, type QuestionSurface } from "./questions.ts";
+
+/**
+ * #1053 T3: what `hub_ask` does with the store. The store owns the row and its one terminal transition; this desk owns the waiting call (in memory, never
+ * persisted), the person's supersede, the cancel on stop or abort, the expiry sweep and the hub-built envelope a late answer needs. It reaches the rest of the
+ * daemon only through `DeskPorts`, so a fake peer and a fake bus exercise every path. Nothing here logs: question and answer text stay in the store and in the
+ * envelope addressed to the asking peer.
+ */
+
+export type AskResult =
+  | { status: "answered"; questionSet: string; answers: QuestionAnswer[]; answeredBy: "person"; surface: QuestionSurface }
+  | { status: "pending"; questionSet: string }
+  | { status: "superseded"; questionSet: string }
+  | { status: "cancelled"; questionSet: string; reason: QuestionReason }
+  | { status: "unavailable"; reason: QuestionReason };
+
+/** The events the desk reports: ids, peers, counts and a closed reason, never a prompt, an option or an answer. */
+export interface QuestionEvent {
+  type: "question";
+  set: string;
+  peer: string;
+  event: "asked" | "answered" | "pending" | "superseded" | "cancelled" | "expired" | "unavailable";
+  latencyMs?: number;
+  surface?: QuestionSurface;
+  reason?: QuestionReason;
+  questions?: number;
+  private?: boolean;
+}
+
+export interface DeskPorts {
+  store: QuestionStore;
+  now(): number;
+  /** How long a `hub_ask` call of this peer waits before it answers `pending`. */
+  waitMs(peer: PeerId): number;
+  ttlMs(): number;
+  /** The peer's native session id; "" when the adapter reports none or the peer is offline: unknown never cancels. */
+  session(peer: PeerId): string;
+  unattended(peer: PeerId): boolean;
+  /** The peer's current turn is a PII turn (`piiTurn`, from the tool call), or it holds an open PII task, or `task` is one. */
+  isPrivate(peer: PeerId, task: number | undefined, piiTurn?: boolean): boolean;
+  /** The hub is stopping or in recovery: a new question is refused before any row exists. */
+  held(): boolean;
+  /** Publish a hub-built envelope; throws when the bus refuses it (the row keeps its owed flag and the sweep retries). */
+  publish(env: Envelope): void;
+  event(e: QuestionEvent): void;
+  /** Peers whose queue can still take an envelope; an unknown peer id never gets a row. */
+  peerKnown(peer: PeerId): boolean;
+}
+
+interface Waiter { resolve(result: AskResult): void; timer: ReturnType<typeof setTimeout>; detach(): void }
+/** Settled rows are kept this long for `ahub` readbacks, then pruned; an open row or an owed envelope is never pruned. */
+const KEEP_SETTLED_MS = 7 * 86_400_000;
+
+/** The late-answer envelope. `from` is the person, `kind` is `answer`, and the set rides in `refs.question` and as the body's first line `reply_to: <set>` (an envelope has no reply field of its own: `reply_to` is the `hub_send` argument that resolves an envelope id). The id is derived from the set so a republish after a crash is dropped by the bus's own dedupe. */
+export function answerEnvelope(row: QuestionRow): Envelope {
+  const result: AskResult = { status: "answered", questionSet: row.set, answers: row.answers ?? [], answeredBy: "person", surface: row.surface ?? "console" };
+  const body = `reply_to: ${row.set}\nYour question ${row.set} was answered by the person${row.surface ? ` (${row.surface})` : ""}. Use this answer; do not ask it again.\n${JSON.stringify(result)}`;
+  return { ...newEnvelope(USER, body, { to: [row.peer], kind: "answer", priority: "important", refs: { question: row.set }, ...(row.private ? { private: true } : {}) }), id: `answer-${row.set}` };
+}
+/** The expiry notice. A hub notice of kind `status`, never an answer: the agent decides for itself. */
+export function expiryEnvelope(row: QuestionRow, ttlMs: number): Envelope {
+  const hours = Math.max(1, Math.round(ttlMs / 3_600_000));
+  const body = `Your question ${row.set} expired unanswered after about ${hours} hour${hours === 1 ? "" : "s"}. This is not an answer: decide yourself and say so.`;
+  return { ...newEnvelope(HUB, body, { to: [row.peer], kind: "status", priority: "status", refs: { question: row.set }, ...(row.private ? { private: true } : {}) }), id: `question-expired-${row.set}` };
+}
+
+export class QuestionDesk {
+  private readonly waiters = new Map<string, Waiter>();
+  private closed = false;
+  constructor(private readonly p: DeskPorts) {}
+
+  /** The waiting calls right now (a row without one is orphaned: its answer takes the late path). */
+  waiting(): number { return this.waiters.size; }
+
+  async ask(peer: PeerId, raw: unknown, ctx: { signal?: AbortSignal; piiTurn?: boolean } = {}): Promise<AskResult> {
+    if (this.closed || this.p.held()) throw new PreEffectToolRefusal("the hub is stopping or recovering; ask again once it is back");
+    if (peer === USER || peer === HUB || !this.p.peerKnown(peer)) throw new PreEffectToolRefusal("hub_ask is for the agents of this project; the person answers with the console");
+    const parsed = parseAsk(raw);
+    if (!parsed.ok) throw new PreEffectToolRefusal(parsed.error);
+    // `--unattended` means nobody is watching: no row, no wait. The agent decides and says so.
+    if (this.p.unattended(peer)) {
+      this.p.event({ type: "question", set: "-", peer, event: "unavailable", reason: "unattended", questions: parsed.value.questions.length });
+      return { status: "unavailable", reason: "unattended" };
+    }
+    if (ctx.signal?.aborted) throw new PreEffectToolRefusal("the turn was aborted before the question was asked");
+    const created = this.p.store.ask({ peer, session: this.p.session(peer), ...(parsed.value.task !== undefined ? { task: parsed.value.task } : {}), private: this.p.isPrivate(peer, parsed.value.task, ctx.piiTurn === true), questions: parsed.value.questions }, this.p.now());
+    if ("error" in created) throw new PreEffectToolRefusal(created.error);
+    const row = created;
+    this.p.event({ type: "question", set: row.set, peer, event: "asked", questions: row.questions.length, private: row.private });
+    return new Promise<AskResult>(resolve => {
+      const waitMs = Math.max(1000, this.p.waitMs(peer));
+      const onAbort = () => {
+        if (!this.waiters.has(row.set)) return;
+        if (ctx.signal?.reason instanceof QuestionWaitDetached) { this.p.event({ type: "question", set: row.set, peer, event: "pending", latencyMs: this.p.now() - row.created, private: row.private }); this.settleWait(row.set, { status: "pending", questionSet: row.set }); }
+        else this.cancelRow(row.set, "turn_aborted");
+      };
+      const timer = setTimeout(() => {
+        // The window ended: the row stays open and its answer arrives as an envelope.
+        if (!this.waiters.has(row.set)) return;
+        this.p.event({ type: "question", set: row.set, peer, event: "pending", latencyMs: this.p.now() - row.created, private: row.private });
+        this.settleWait(row.set, { status: "pending", questionSet: row.set });
+      }, waitMs);
+      timer.unref?.();
+      ctx.signal?.addEventListener("abort", onAbort, { once: true });
+      this.waiters.set(row.set, { resolve, timer, detach: () => ctx.signal?.removeEventListener("abort", onAbort) });
+    });
+  }
+
+  /**
+   * The person's answer, from the console role only (the daemon checks the role before it calls this). Of any number of concurrent answers, stops and expiries,
+   * the store's compare-and-set lets exactly one win; a loser is told the row's real terminal state. An answer to a row with no waiting call is the late path.
+   */
+  answer(set: unknown, raw: unknown, surface: QuestionSurface, person?: string): AnswerResult {
+    if (typeof set !== "string" || !QUESTION_SET.test(set)) return { ok: false, error: "no such question" };
+    const current = this.p.store.get(set);
+    if (current?.state === "open" && this.sessionChanged(current)) {
+      this.cancelRow(set, "session_changed");
+      return { ok: false, error: "question is already cancelled", state: "cancelled" };
+    }
+    const late = !this.waiters.has(set);
+    const result = this.p.store.answer(set, raw, surface, this.p.now(), late, person);
+    if (!result.ok) return result;
+    this.p.event({ type: "question", set, peer: result.row.peer, event: "answered", latencyMs: this.p.now() - result.row.created, surface, ...(person ? { person } : {}), private: result.row.private });
+    if (late) this.publishOwed(result.row);
+    else this.settleWait(set, { status: "answered", questionSet: set, answers: result.row.answers ?? [], answeredBy: "person", surface });
+    return result;
+  }
+
+  /** The person sent these peers a normal message: every open question of each is superseded and its waiting call told. That message is delivered as usual. */
+  supersede(peers: readonly PeerId[]): void {
+    for (const peer of new Set(peers)) for (const row of this.p.store.settleFor(peer, "superseded", "superseded", this.p.now())) {
+      this.p.event({ type: "question", set: row.set, peer, event: "superseded", latencyMs: this.p.now() - row.created, private: row.private });
+      this.settleWait(row.set, { status: "superseded", questionSet: row.set });
+    }
+  }
+  /** A stop of the peer: its open questions are cancelled and its waiting calls told. */
+  cancelPeer(peer: PeerId, reason: QuestionReason): void {
+    for (const row of this.p.store.settleFor(peer, "cancelled", reason, this.p.now())) this.announceCancel(row, reason);
+  }
+  /** Peers with at least one open row, for a broadcast from the person. */
+  openPeers(): PeerId[] { return [...new Set(this.p.store.list({ state: "open" }, 200).map(row => row.peer))]; }
+
+  /** Expiry, session changes, envelopes still owed and old settled rows. Run on a timer and once at start. */
+  sweep(): void {
+    if (this.closed) return;
+    const now = this.p.now();
+    for (const row of this.p.store.expireDue(now, this.p.ttlMs())) {
+      this.p.event({ type: "question", set: row.set, peer: row.peer, event: "expired", latencyMs: now - row.created, reason: "expired", private: row.private });
+      // A waiting call carries the result itself, so no envelope is owed; an orphaned row gets the hub notice.
+      if (this.waiters.has(row.set)) { this.p.store.published(row.set); this.settleWait(row.set, { status: "cancelled", questionSet: row.set, reason: "expired" }); }
+      else this.publishOwed(row);
+    }
+    for (const row of this.p.store.list({ state: "open" }, 200)) if (this.sessionChanged(row)) this.cancelRow(row.set, "session_changed");
+    for (const row of this.p.store.owed()) this.publishOwed(row);
+    this.p.store.prune(now, KEEP_SETTLED_MS);
+  }
+  /** Start repair: a row whose session changed is cancelled, every other open row stays open for the late path, and an owed envelope goes out. */
+  repair(): void { this.sweep(); }
+
+  /** Shutdown: waiting calls end `pending` (their rows stay open and survive the restart); nothing new is admitted. */
+  close(): void {
+    this.closed = true;
+    this.endWaits();
+  }
+  /** Recovery `prepare`: waiting calls end `pending` now, so a restart never waits out a person's window; every row stays open for the late path. */
+  endWaits(): void {
+    for (const [set, waiter] of [...this.waiters]) { if (this.waiters.get(set) === waiter) this.settleWait(set, { status: "pending", questionSet: set }); }
+  }
+
+  private sessionChanged(row: QuestionRow): boolean {
+    if (!row.session) return false;
+    const now = this.p.session(row.peer);
+    return now !== "" && now !== row.session;
+  }
+  private cancelRow(set: string, reason: QuestionReason): void {
+    const row = this.p.store.settle(set, "cancelled", reason, this.p.now());
+    if (row) this.announceCancel(row, reason);
+  }
+  private announceCancel(row: QuestionRow, reason: QuestionReason): void {
+    this.p.event({ type: "question", set: row.set, peer: row.peer, event: "cancelled", latencyMs: this.p.now() - row.created, reason, private: row.private });
+    this.settleWait(row.set, { status: "cancelled", questionSet: row.set, reason });
+  }
+  private settleWait(set: string, result: AskResult): void {
+    const waiter = this.waiters.get(set);
+    if (!waiter) return;
+    this.waiters.delete(set);
+    clearTimeout(waiter.timer);
+    waiter.detach();
+    waiter.resolve(result);
+  }
+  /** Publish the envelope a row owes its peer, then mark it published. A refusal leaves the flag, and the sweep tries again. */
+  private publishOwed(row: QuestionRow): void {
+    try {
+      this.p.publish(row.state === "answered" ? answerEnvelope(row) : expiryEnvelope(row, this.p.ttlMs()));
+      this.p.store.published(row.set);
+    } catch { /* the bus refused it (recovery hold, storage error): the row still owes it */ }
+  }
+}

package/src/hub/question-detach.ts

@@ -0,0 +1,6 @@
+/**
+ * #1053: the abort reason a transport gives when only the CLIENT of a waiting `hub_ask` is gone (Pi's bridge connection dropped), not the turn. The desk ends that wait
+ * `pending` and keeps the row open, so a later answer takes the late-envelope path instead of going to a dead response; any other abort cancels the row (`turn_aborted`).
+ * Its own file so an adapter can name it without importing the desk.
+ */
+export class QuestionWaitDetached extends Error { constructor() { super("the client of a waiting question went away"); this.name = "QuestionWaitDetached"; } }