@staix/agent-hub 0.30.0 → 0.32.0

package/src/adapters/registry.ts

@@ -241,6 +241,8 @@ export function assertNativeCapabilityScope(definition: AdapterDefinition): void
   const restricted: [string, boolean][] = [
     ["title", definition.title !== undefined],
     ["titlePersistence", definition.titlePersistence !== undefined],
+    ["questionWaitMs", definition.questionWaitMs !== undefined],
+    ["settle", definition.settle !== undefined],
     ["start.acpCommand", declared(definition.start, "acpCommand")],
     ["attach.admission", declared(definition.attach, "admission")],
     ["budget.resetSoftTokensOnResume", declared(definition.budget, "resetSoftTokensOnResume")],

package/src/adapters/reviewer-print.ts

@@ -1,8 +1,9 @@
 import type { ChildProcess } from "node:child_process";
-import { OwnedPrintChild, PrintChildCleanupError } from "./claude-print-child.ts";
+import { OwnedPrintChild, PrintChildCleanupError, type OwnedInputContext, type OwnedInputObserver } from "./claude-print-child.ts";
 import { randomUUID } from "node:crypto";
 import { HUB, frame, sanitize } from "../hub/envelope.ts";
 import { BasePeer } from "../hub/peers.ts";
+import type { DeliveryFailureCause } from "../hub/delivery-failure.ts";
 import type { Envelope } from "../hub/envelope.ts";
 import type { ReviewerMcpSession, ReviewerToolName } from "./reviewer-mcp.ts";
 
@@ -31,6 +32,7 @@ export class ReviewerUnavailableError extends Error {
 class ReviewerAdmissionError extends Error {
   constructor(readonly reason: "stale_binding" | "policy_changed") { super("review admission changed"); }
 }
+class ReviewerInputAdmissionError extends Error {}
 
 export interface ReviewerPrintUsage { input_tokens?: number; output_tokens?: number; cache_creation_input_tokens?: number; cache_read_input_tokens?: number }
 export interface ReviewerIsolationReceipt {
@@ -136,6 +138,13 @@ export interface ReviewerPrintOptions {
   /** Synchronous host task/privacy/policy fence, checked again after awaited preparation. */
   admit?(env: Envelope): boolean;
   bindingCurrent?(task: number, binding: ReviewerReviewBinding): boolean;
+  /** Private-profile observer input provenance only; never a native resume or budget identity. */
+  beforeInput?: OwnedInputObserver;
+  inputReleased?: OwnedInputObserver;
+  /** Host privacy state for the currently attached reviewer input, read only for diagnostics. */
+  reviewObserverHeld?(): boolean;
+  /** Runs after this fresh child group, task MCP and launch cleanup are confirmed closed. */
+  inputFinished?: OwnedInputObserver;
 }
 
 type ReviewTarget = Omit<ReviewerFailure, "cause">;
@@ -166,9 +175,13 @@ export class ReviewerPrintPeer extends BasePeer {
   private batch: ReviewBatch | undefined;
   private preparation: { abort: AbortController; done: Promise<ReviewerLaunch> } | undefined;
   private receipt: ReviewerIsolationReceipt | undefined;
+  private observerSessionIdValue: string | undefined;
   get isolationReceipt(): ReviewerIsolationReceipt | undefined { return this.receipt; }
+  reviewObserverInputHeld(): boolean { return this.opts.reviewObserverHeld?.() ?? false; }
   /** The task whose review the running child was started for (R4: the hub records `fresh` for its verdict). */
   reviewing: number | undefined;
+  /** Privacy-only identity for a fresh review profile; never part of resume or budget authority. */
+  get observerSessionId(): string | undefined { return this.observerSessionIdValue; }
   private reviewSeq = 0;
   private runningBinding: { task: number; binding: ReviewerReviewBinding } | undefined;
   private activeTrace: { task: number; generation: number; value: ReviewerTraceState } | undefined;
@@ -234,16 +247,16 @@ export class ReviewerPrintPeer extends BasePeer {
     this.setState("offline");
   }
 
-  protected override onWatchdog(): void { this.abortReview("review watchdog timeout"); }
+  protected override onWatchdog(): void { this.abortReview("review watchdog timeout", "timeout"); }
 
-  private abortReview(reason: "review watchdog timeout" | "review output limit exceeded" | "review policy changed"): void {
+  private abortReview(reason: "review watchdog timeout" | "review output limit exceeded" | "review policy changed", failureCause?: DeliveryFailureCause): void {
     const generation = ++this.generation, batch = this.batch, preparation = this.preparation;
     this.reviewing = undefined;
     this.reviewMcpClose?.();
     this.receipt = undefined;
     this.clearWatchdog();
     preparation?.abort.abort();
-    this.settle("needs_review", reason);
+    this.settle("needs_review", reason, failureCause);
     // Revoke first, then confirm both preparation and the model's whole group are gone before fallback.
     void (async () => {
       if (preparation) await preparation.done.catch(() => {});
@@ -288,6 +301,11 @@ export class ReviewerPrintPeer extends BasePeer {
       try { result = await this.review(env, task, generation); }
       catch (error) {
         if (generation !== this.generation) return;
+        if (error instanceof ReviewerInputAdmissionError) {
+          failure = { state: started ? "needs_review" : "failed_safe", reason: "review input provenance unavailable" };
+          batch.next = envs.length;
+          break;
+        }
         if (error instanceof ReviewerAdmissionError) {
           this.opts.log?.(`[${this.id}] review of task #${task} skipped: ${error.reason === "stale_binding" ? "stale binding" : "review policy changed"}`);
           if (error.reason === "policy_changed") {
@@ -395,18 +413,30 @@ export class ReviewerPrintPeer extends BasePeer {
     let facts: string | undefined;
     try { facts = this.opts.facts?.(env); } catch (error) { this.opts.log?.(`[${this.id}] review facts for task #${task} failed: ${(error as Error).message}`); }
     const input = `${frame(env)}${facts ? `\n\n${facts}` : ""}`;
+    const sessionId = randomUUID();
+    const inputContext: OwnedInputContext = Object.freeze({ sessionId, inputId: randomUUID() });
+    this.observerSessionIdValue = sessionId;
+    try { this.opts.beforeInput?.(inputContext, [env]); }
+    catch { this.observerSessionIdValue = undefined; throw new ReviewerInputAdmissionError(); }
     let launch: ReviewerLaunch | undefined;
     const trace: ReviewerTraceState = { reviewCalled: false };
     this.activeTrace = { task, generation, value: trace };
     const mcp = this.opts.backend.taskMcp ? this.opts.taskMcp?.(task, () => generation === this.generation && this.reviewToken(task) !== undefined && this.opts.bindingCurrent?.(task,binding) !== false) : undefined;
-    let mcpClosed=false;
-    const closeMcp=()=>{ if(mcpClosed)return; mcpClosed=true; mcp?.close(); if(this.reviewMcpClose===closeMcp)this.reviewMcpClose=undefined; };
+    let mcpClosed = false, mcpCloseConfirmed = false;
+    const closeMcp = () => {
+      if (mcpClosed) return;
+      mcpClosed = true;
+      try { mcp?.close(); mcpCloseConfirmed = true; }
+      catch { this.opts.log?.(`[${this.id}] reviewer task MCP cleanup incomplete`); }
+      if (this.reviewMcpClose === closeMcp) this.reviewMcpClose = undefined;
+    };
     this.reviewMcpClose=closeMcp;
     let ownedChild: OwnedPrintChild | undefined, releasing: Promise<void> | undefined;
+    let inputReleased = false, childClosed = false, launchCleanupConfirmed = false;
     let policyTimer: ReturnType<typeof setInterval> | undefined;
     const release = () => releasing ??= Promise.resolve().then(() => launch?.cleanup?.()).then(() => {});
     try {
-    launch = await this.prepare(randomUUID(), input, task, mcp?.config);
+    launch = await this.prepare(sessionId, input, task, mcp?.config);
     if (generation !== this.generation) throw new ReviewerAdmissionError("stale_binding");
     this.assertAdmission(env, task, binding);
     if (launch.current?.() === false) throw new ReviewerUnavailableError("reviewer isolation changed before child spawn", "binary");
@@ -415,6 +445,7 @@ export class ReviewerPrintPeer extends BasePeer {
     const child = new OwnedPrintChild({ peer: this.id, command: launch.command, args: launch.args,
       cwd: launch.cwd ?? this.opts.cwd, env: launch.env, envMode: launch.envMode, input,
       current: () => generation === this.generation, stop: launch.stop,
+      onInputReleased: () => { inputReleased = true; this.opts.inputReleased?.(inputContext, [env]); },
       onError: () => { if (this.child === child) this.child = undefined; },
       onSpawn: () => {
         this.runningBinding={task,binding};
@@ -441,21 +472,29 @@ export class ReviewerPrintPeer extends BasePeer {
     this.childCleanup = release;
     this.childCurrent = launch.watchCurrent ? launch.current : undefined;
     const code = await child.done;
+    childClosed = true;
     if (this.child === child) this.child = undefined;
     return { code, quota, trace };
     } finally {
       if (this.activeTrace?.value === trace) this.activeTrace = undefined;
       closeMcp();
       if (policyTimer) clearInterval(policyTimer);
-      try { if (!ownedChild || this.child !== ownedChild) { await release(); if (this.childCleanup === release) this.childCleanup = undefined; } }
-      catch { this.opts.log?.(`[${this.id}] reviewer isolation cleanup incomplete`); }
+      try {
+        if (!ownedChild || this.child !== ownedChild) {
+          await release(); if (this.childCleanup === release) this.childCleanup = undefined;
+          launchCleanupConfirmed = true;
+        }
+      } catch { this.opts.log?.(`[${this.id}] reviewer isolation cleanup incomplete`); }
+      const closedWithoutChild = !ownedChild || ownedChild.process.pid === undefined;
+      if (mcpCloseConfirmed && launchCleanupConfirmed && (closedWithoutChild || inputReleased && childClosed))
+        try { this.opts.inputFinished?.(inputContext, [env]); } catch { /* receipt cleanup never changes the review verdict */ }
     }
   }
 
-  private settle(state: "completed" | "failed_safe" | "needs_review", reason?: string): void {
+  private settle(state: "completed" | "failed_safe" | "needs_review", reason?: string, failureCause?: DeliveryFailureCause): void {
     const id = this.activeDeliveryId;
     this.activeDeliveryId = undefined;
-    if (id) this.delivery({ id, state, ...(reason ? { reason } : {}) });
+    if (id) this.delivery({ id, state, ...(reason ? { reason } : {}), ...(failureCause ? { failureCause } : {}) });
   }
 
   /** Revokes the verdict authority at once, then stops the child; on failure the handle is kept and the error thrown. */

package/src/broker/server.ts

@@ -25,6 +25,7 @@ export interface BrokerOptions {
 interface Client {
   ws?: ServerWebSocket<Client>;
   room: string;
+  ephemeral: boolean;
   challenge: BrokerChallenge;
   phase: "challenge" | "authenticating" | "roster" | "ready" | "closed";
   busy: boolean;
@@ -35,6 +36,9 @@ interface Client {
   rosterDigest?: string;
   rosterDeadline?: number;
   inFlight?: string;
+  inFlightEphemeral?: boolean;
+  inFlightExpiresAt?: number;
+  inFlightEpoch?: string;
 }
 export interface BrokerRuntime {
   readonly port: number;
@@ -104,8 +108,12 @@ export async function startBroker(options: BrokerOptions, ports: BrokerPorts = {
   function close(client: Client, code: string): void {
     if (client.phase === "closed") return;
     client.phase = "closed";
+    client.inFlight = undefined; client.inFlightEphemeral = undefined; client.inFlightExpiresAt = undefined; client.inFlightEpoch = undefined;
     queuedBytes -= client.inboxBytes; client.inboxBytes = 0; client.inbox.length = 0;
-    if (client.member && members.get(memberKey(client)) === client) members.delete(memberKey(client));
+    if (client.member && members.get(memberKey(client)) === client) {
+      members.delete(memberKey(client));
+      try { store.disconnect(client.room, client.member); } catch { emit("refused", client, "state_unavailable"); }
+    }
     if (client.ws) { try { client.ws.close(4403, code); } catch { /* already closed */ } }
     else clients.delete(client);
   }
@@ -117,9 +125,9 @@ export async function startBroker(options: BrokerOptions, ports: BrokerPorts = {
     close(client, "backpressure"); return false;
   }
   const control = (client: Client, value: unknown) => send(client, canonicalBytes(value));
-  function refused(client: Client, code: string, terminal = true): void {
+  function refused(client: Client, code: string, terminal = true, digest?: string): void {
     emit("refused", client, code);
-    control(client, { v: 1, type: "error", code });
+    control(client, { v: 1, type: "error", code, ...(code === "queue_full" && digest ? { digest } : {}) });
     if (terminal) close(client, code);
   }
   function active(client: Client): VerifiedPublicRoster {
@@ -133,16 +141,29 @@ export async function startBroker(options: BrokerOptions, ports: BrokerPorts = {
     const roster = active(client);
     client.phase = "roster"; client.rosterDigest = roster.digest;
     client.rosterDeadline = now() + BROKER_SOCKET_LIMITS.rosterAckMs;
-    if (send(client, publicRosterWire(roster))) control(client, { v: 1, type: "ready", room: client.room, member: client.member, epoch: roster.epoch, digest: roster.digest });
+    // Legacy hubs have a closed ready grammar; advertise only after HTTP opt-in.
+    if (send(client, publicRosterWire(roster))) control(client, { v: 1, type: "ready", room: client.room, member: client.member, epoch: roster.epoch, digest: roster.digest, ...(client.ephemeral ? { ephemeral: true } : {}) });
   }
   function pump(client: Client): void {
     if (stopping || client.phase === "closed" || !client.member) return;
-    active(client);
+    const roster = active(client);
     const next = store.next(client.room, client.member);
-    if (client.inFlight && next?.digest === client.inFlight) return;
-    client.inFlight = undefined; // the previous packet may have expired or been purged.
+    if (client.inFlightEphemeral && client.inFlightEpoch !== roster.epoch) {
+      const previous = store.current(client.room)?.previous;
+      client.inFlightExpiresAt = previous && previous.roster.epoch === client.inFlightEpoch
+        ? Math.min(client.inFlightExpiresAt ?? 0, previous.expiresAt) : 0;
+    }
+    // Replacement retires an ephemeral queue row, not the packet already handed
+    // to this socket. Keep its slot until ACK or its original TTL/grace deadline.
+    if (client.inFlight && (client.inFlightEphemeral && now() < (client.inFlightExpiresAt ?? 0) || next?.digest === client.inFlight)) return;
+    client.inFlight = undefined; client.inFlightEphemeral = undefined; client.inFlightExpiresAt = undefined; client.inFlightEpoch = undefined; // durable expiry/purge still releases its slot.
     if (client.phase !== "ready" || !next) return;
-    if (send(client, next.wire)) client.inFlight = next.digest;
+    if (send(client, next.wire)) {
+      client.inFlight = next.digest;
+      const frame = decodeFrame(next.wire);
+      client.inFlightEphemeral = frame.ephemeral === true;
+      client.inFlightExpiresAt = next.expiresAt; client.inFlightEpoch = frame.epoch;
+    }
   }
   function safePump(client: Client): void {
     try { pump(client); } catch (error) { refused(client, errorCode(error)); }
@@ -195,9 +216,19 @@ export async function startBroker(options: BrokerOptions, ports: BrokerPorts = {
       const selected = state && (header.epoch === state.current.epoch ? state.current : state.previous?.roster);
       if (!selected) throw new BrokerServerError("wrong_epoch");
       const proof = await (ports.verifyFrame ?? verifyPublicFrame)({ wire: bytes, roster: selected });
-      active(client);
-      const result = store.enqueue(proof, client.member!); // latest membership/grace/caps checked transactionally.
-      control(client, { v: 1, type: "stored", digest: result.digest, seq: proof.seq, duplicate: result.duplicate });
+      const onlineRecipients = proof.recipients.filter(recipient => {
+        const target = members.get(`${client.room}|${recipient}`);
+        return target?.phase === "ready" && (!proof.ephemeral || target.ephemeral);
+      });
+      try {
+        active(client);
+        const result = store.enqueue(proof, client.member!, onlineRecipients); // latest membership/grace/caps checked transactionally.
+        control(client, { v: 1, type: "stored", digest: result.digest, seq: proof.seq, duplicate: result.duplicate });
+      } catch (error) {
+        if (errorCode(error) !== "queue_full") throw error;
+        refused(client, "queue_full", false, client.ephemeral ? proof.digest : undefined);
+        return;
+      }
       for (const recipient of proof.recipients) {
         const target = members.get(`${client.room}|${recipient}`);
         if (target) safePump(target);
@@ -215,7 +246,7 @@ export async function startBroker(options: BrokerOptions, ports: BrokerPorts = {
     if (packet.digest !== client.inFlight) { refused(client, "unexpected_ack", false); return; }
     active(client);
     store.ack(client.room, client.member!, packet.digest);
-    client.inFlight = undefined;
+    client.inFlight = undefined; client.inFlightEphemeral = undefined; client.inFlightExpiresAt = undefined; client.inFlightEpoch = undefined;
     control(client, { v: 1, type: "queue_ack", digest: packet.digest });
     safePump(client);
   }
@@ -259,7 +290,7 @@ export async function startBroker(options: BrokerOptions, ports: BrokerPorts = {
           const room = roomId(url.pathname.slice("/v1/rooms/".length));
           if (clients.size >= BROKER_SOCKET_LIMITS.connections) return new Response("busy", { status: 503 });
           const current = store.current(room)?.current;
-          const client: Client = { room, challenge: { v: 1, type: "challenge", room, broker: publicUrl, nonce: encodeBase64url(randomBytes(32)), expiresAt: now() + BROKER_SOCKET_LIMITS.authMs, rosterDigest: current?.digest ?? null }, phase: "challenge", busy: false, inbox: [], inboxBytes: 0 };
+          const client: Client = { room, ephemeral: req.headers.get("x-agent-hub-ephemeral") === "1", challenge: { v: 1, type: "challenge", room, broker: publicUrl, nonce: encodeBase64url(randomBytes(32)), expiresAt: now() + BROKER_SOCKET_LIMITS.authMs, rosterDigest: current?.digest ?? null }, phase: "challenge", busy: false, inbox: [], inboxBytes: 0 };
           clients.add(client);
           if (host.upgrade(req, { data: client })) return;
           clients.delete(client); return new Response("websocket required", { status: 400 });

package/src/broker/store.ts

@@ -303,6 +303,8 @@ export class BrokerStore {
         fail("corrupt");
       }
     }
+    // No recipient is connected when a broker opens. Ephemeral presence never survives that boundary.
+    this.transaction(() => { this.removeEphemeral(); });
     // Recover only structurally valid public/ciphertext queue rows, then enforce the current caps.
     this.sweep();
     const stats = this.stats();
@@ -358,7 +360,7 @@ export class BrokerStore {
     return { changed: true, revoked };
   }
 
-  enqueue(proof: VerifiedPublicFrame, authorizedSender: string): { digest: string; duplicate: boolean } {
+  enqueue(proof: VerifiedPublicFrame, authorizedSender: string, onlineRecipients: readonly string[] = []): { digest: string; duplicate: boolean } {
     this.assertOpen();
     const wire = checkedProofFrame(proof);
     if (authorizedSender !== proof.sender) fail("untrusted");
@@ -402,16 +404,24 @@ export class BrokerStore {
         }
         if (order < 0n) fail("conflict");
       }
+      if (proof.ephemeral) {
+        // ponytail: while A awaits C, A's broadcast reply to B may replace C's request;
+        // C waits for A's next state change/reconnect. Task #736 idle refresh or
+        // per-(sender,recipient) coalescing closes this latest-per-sender ceiling.
+        this.removeEphemeral(proof.room, proof.sender);
+        const connected = new Set(onlineRecipients);
+        recipients = recipients.filter(recipient => connected.has(recipient));
+      }
       const counts = this.db.query<{ count: number; bytes: number }, []>("SELECT COUNT(*) AS count, COALESCE(SUM(length(wire)),0) AS bytes FROM queued_frames").get();
       const room = this.db.query<{ count: number; bytes: number }, [string]>("SELECT COUNT(*) AS count, COALESCE(SUM(length(wire)),0) AS bytes FROM queued_frames WHERE room=?").get(proof.room);
-      if (byteLength > this.limits.packetBytes || byteLength > this.limits.queuedBytesPerRoom || (room?.count ?? 0) >= this.limits.queuedPerRoom ||
+      if (byteLength > this.limits.packetBytes || byteLength > this.limits.queuedBytesPerRoom || recipients.length > 0 && ((room?.count ?? 0) >= this.limits.queuedPerRoom ||
           (room?.bytes ?? 0) + byteLength > this.limits.queuedBytesPerRoom || (counts?.count ?? 0) >= this.limits.queuedGlobal ||
-          (counts?.bytes ?? 0) + byteLength > this.limits.packetBytes) fail("full");
+          (counts?.bytes ?? 0) + byteLength > this.limits.packetBytes)) fail("full");
       const expiresAt = writeNow + this.limits.queueTtlMs;
       if (!Number.isSafeInteger(expiresAt)) fail("invalid");
       this.db.query("INSERT INTO sender_floors(room,sender,seq,digest) VALUES(?,?,?,?) ON CONFLICT(room,sender) DO UPDATE SET seq=excluded.seq,digest=excluded.digest")
         .run(proof.room, proof.sender, proof.seq, proof.digest);
-      this.db.query("INSERT INTO queued_frames(room,sender,seq,digest,wire,recipients,created_at,expires_at,epoch) VALUES(?,?,?,?,?,?,?,?,?)")
+      if (recipients.length) this.db.query("INSERT INTO queued_frames(room,sender,seq,digest,wire,recipients,created_at,expires_at,epoch) VALUES(?,?,?,?,?,?,?,?,?)")
         .run(proof.room, proof.sender, proof.seq, proof.digest, wire, JSON.stringify(recipients), writeNow, expiresAt, proof.epoch);
       result = { digest: proof.digest, duplicate: false };
     });
@@ -423,7 +433,24 @@ export class BrokerStore {
     return fail("invalid");
   }
 
-  next(room: string, recipient: string): { digest: string; wire: Uint8Array } | undefined {
+  /** A disconnected member never retains ephemeral presence, while durable work stays queued. */
+  disconnect(room: string, recipient: string): void {
+    this.transaction(() => { this.removeEphemeral(room, undefined, recipient); });
+  }
+
+  private removeEphemeral(room?: string, sender?: string, recipient?: string): void {
+    const rows = this.db.query<{ rowid: number; wire: Uint8Array; recipients: string }, [string | null, string | null, string | null, string | null]>(
+      "SELECT rowid,wire,recipients FROM queued_frames WHERE (? IS NULL OR room=?) AND (? IS NULL OR sender=?)",
+    ).all(room ?? null, room ?? null, sender ?? null, sender ?? null);
+    for (const row of rows) {
+      if (!decodeFrame(row.wire).ephemeral) continue;
+      const remaining = recipient === undefined ? [] : parseRecipients(row.recipients).filter(id => id !== recipient);
+      if (remaining.length) this.db.query("UPDATE queued_frames SET recipients=? WHERE rowid=?").run(JSON.stringify(remaining), row.rowid);
+      else this.db.query("DELETE FROM queued_frames WHERE rowid=?").run(row.rowid);
+    }
+  }
+
+  next(room: string, recipient: string): { digest: string; wire: Uint8Array; expiresAt: number } | undefined {
     this.assertOpen(); let now = 0;
     let state = this.rooms.get(room);
     if (!state) return undefined;
@@ -431,13 +458,16 @@ export class BrokerStore {
     if (state) this.rooms.set(room, state);
     if (!state?.current.members.some(member => member.fingerprint === recipient)) return undefined;
     const previous = state.previous && state.previous.expiresAt > now ? state.previous.roster.epoch : state.current.epoch;
-    const rows = this.db.query<{ id: number; digest: string; recipients: string }, [string, number, string, string]>(
-      "SELECT rowid AS id,digest,recipients FROM queued_frames WHERE room=? AND expires_at>? AND epoch IN (?,?) ORDER BY rowid",
+    const rows = this.db.query<{ id: number; digest: string; recipients: string; epoch: string; expiresAt: number }, [string, number, string, string]>(
+      "SELECT rowid AS id,digest,recipients,epoch,expires_at AS expiresAt FROM queued_frames WHERE room=? AND expires_at>? AND epoch IN (?,?) ORDER BY rowid",
     ).all(room, now, state.current.epoch, previous);
     for (const row of rows) {
       if (!parseRecipients(row.recipients).includes(recipient)) continue;
       const packet = this.db.query<{ wire: Uint8Array }, [number]>("SELECT wire FROM queued_frames WHERE rowid=?").get(row.id);
-      if (packet?.wire instanceof Uint8Array) return { digest: row.digest, wire: new Uint8Array(packet.wire) };
+      if (packet?.wire instanceof Uint8Array) {
+        const expiresAt = row.epoch === state.current.epoch ? row.expiresAt : Math.min(row.expiresAt, state.previous!.expiresAt);
+        return { digest: row.digest, wire: new Uint8Array(packet.wire), expiresAt };
+      }
     }
     return undefined;
   }

package/src/cli/answer-args.ts

@@ -0,0 +1,50 @@
+import { QUESTION_SET } from "../hub/questions.ts";
+
+/**
+ * #1053 T4: `ahub answer <set> <question>=<option>[,<option>]... [--other <text>]...`. Pure: it turns argv into the `answers` list the hub validates
+ * against the stored row, and never decides whether an answer is valid (the store does, with a reason that names a question by position).
+ *
+ * `--other <text>` is the free text of the one question named, or `--other <question>=<text>` when several are named; a question named with no options
+ * (`extras=`) answers with its other text alone. The question ids are the agent's, bounded by the same pattern the store uses.
+ */
+
+const ID = /^[A-Za-z0-9_.-]{1,64}$/;
+export interface ParsedAnswer { set: string; answers: { questionId: string; optionIds: string[]; other?: string }[] }
+export type AnswerArgs = { ok: true; value: ParsedAnswer } | { ok: false; error: string };
+export const ANSWER_USAGE = "usage: ahub answer <set> <question>=<option>[,<option>] [--other <text>]   (ahub answer lists the open questions)";
+
+export function parseAnswerArgs(args: readonly string[]): AnswerArgs {
+  const fail = (error: string): { ok: false; error: string } => ({ ok: false, error });
+  const [set, ...rest] = args;
+  if (!set || !QUESTION_SET.test(set)) return fail(`${ANSWER_USAGE}; the set looks like qs-0123456789ab`);
+  const picks = new Map<string, string[]>(), others: string[] = [];
+  for (let index = 0; index < rest.length; index++) {
+    const word = rest[index]!;
+    if (word === "--other" || word.startsWith("--other=")) {
+      const value = word === "--other" ? rest[++index] : word.slice("--other=".length);
+      if (value === undefined || value === "") return fail("--other needs the text to give");
+      others.push(value);
+      continue;
+    }
+    if (word.startsWith("--")) return fail(`${ANSWER_USAGE}; unknown flag ${word.split("=")[0]}`);
+    const at = word.indexOf("=");
+    if (at < 1) return fail(`${ANSWER_USAGE}; "${word.slice(0, 40)}" is not <question>=<option>`);
+    const question = word.slice(0, at);
+    if (!ID.test(question)) return fail("a question id is 1 to 64 characters of letters, digits, dot, dash or underscore");
+    if (picks.has(question)) return fail(`question ${question} is answered twice`);
+    const options = word.slice(at + 1).split(",").filter(Boolean);
+    if (options.some(option => !ID.test(option))) return fail(`question ${question}: an option id is 1 to 64 characters of letters, digits, dot, dash or underscore`);
+    picks.set(question, options);
+  }
+  if (!picks.size) return fail(`${ANSWER_USAGE}; name at least one question`);
+  const other = new Map<string, string>();
+  for (const text of others) {
+    const at = text.indexOf("=");
+    const named = at > 0 && picks.has(text.slice(0, at)) ? text.slice(0, at) : undefined;
+    const target = named ?? (picks.size === 1 ? [...picks.keys()][0]! : undefined);
+    if (target === undefined) return fail("with several questions, give --other <question>=<text>");
+    if (other.has(target)) return fail(`question ${target} has two --other texts`);
+    other.set(target, named ? text.slice(at + 1) : text);
+  }
+  return { ok: true, value: { set, answers: [...picks].map(([questionId, optionIds]) => ({ questionId, optionIds, ...(other.has(questionId) ? { other: other.get(questionId)! } : {}) })) } };
+}

package/src/cli/attention.ts

@@ -10,11 +10,15 @@ export interface AttentionState {
   recoveryNeed?: { id?: string; running: boolean; since?: number };
   queue?: readonly { id: string; peer?: string; state: string }[];
   attentionFacts?: { kind: "review" | "offline" | "stall" | "offer"; id: number; peer?: string }[];
+  /** #1053: open questions; only the set, the peer and the time reach the model. */
+  questions?: readonly { set: string; peer: string; created: number }[];
+  /** #1054: unread results from the hub (ids, peers and settle times only). */
+  results?: readonly { id: string; peer?: string; since?: number }[];
 }
 /** Allowlisted adapter between console-owned facts and the shared body-free model. */
 export function consoleNeeds(state: AttentionState, now: number): Needs {
-  const input: NeedsInput = { approvals: state.approvals.map(row => ({ id: row.id, peer: row.peer, expiresAt: row.expiresAt })), defaults: state.permissionDefaults.map(row => ({ peer: row.peer })), peers: Object.fromEntries(Object.entries(state.peers).map(([peer,row]) => [peer,{ state: row.state, attached: row.attached, needsReview: row.needsReview, heldBy: row.heldBy }])), budget: Object.fromEntries(Object.entries(state.budget).map(([peer,row]) => [peer,{ ...(row.paused ? { paused: { since: row.paused.since, resetsAt: row.paused.resetsAt } } : {}) }])), messages: (state.attentionMessages ?? []).map(row => ({ id: row.id, peer: row.peer, important: row.important, since: row.since })), storageBlocked: state.storageBlocked, recovery: state.recoveryNeed };
-  const result = needs({ ...input, facts: state.attentionFacts }, now);
+  const input: NeedsInput = { approvals: state.approvals.map(row => ({ id: row.id, peer: row.peer, expiresAt: row.expiresAt })), defaults: state.permissionDefaults.map(row => ({ peer: row.peer })), peers: Object.fromEntries(Object.entries(state.peers).map(([peer,row]) => [peer,{ state: row.state, attached: row.attached, needsReview: row.needsReview, heldBy: row.heldBy }])), budget: Object.fromEntries(Object.entries(state.budget).map(([peer,row]) => [peer,{ ...(row.paused ? { paused: { since: row.paused.since, resetsAt: row.paused.resetsAt } } : {}) }])), messages: (state.attentionMessages ?? []).map(row => ({ id: row.id, peer: row.peer, important: row.important, since: row.since })), storageBlocked: state.storageBlocked, recovery: state.recoveryNeed, questions: (state.questions ?? []).map(row => ({ set: row.set, peer: row.peer, since: row.created })) };
+  const result = needs({ ...input, facts: state.attentionFacts, results: state.results }, now);
   // Panel snapshots know each held row; enrich only ids, without changing the status-derived count.
   const used = new Set<string | number>();
   for (const item of result.items) if (item.kind === "delivery") {
@@ -50,7 +54,17 @@ export function attentionFacts(raw: unknown): NonNullable<AttentionState["attent
   });
 }
 
+/** The unread results in the authenticated status reply's attention items: a `result` item at level `watch` with a completion id, never any text. */
+export function attentionResults(raw: unknown): NonNullable<AttentionState["results"]> {
+  if (!Array.isArray(raw)) return [];
+  return raw.flatMap<NonNullable<AttentionState["results"]>[number]>(row => {
+    if (!row || typeof row !== "object" || row.kind !== "result" || row.level !== "watch" || typeof row.id !== "string" || !/^cmp-[a-f0-9]{12}$/.test(row.id)) return [];
+    return [{ id: row.id, ...(typeof row.peer === "string" && /^[A-Za-z0-9_.:-]{1,128}$/.test(row.peer) ? { peer: row.peer } : {}), ...(Number.isSafeInteger(row.since) && row.since >= 0 ? { since: row.since } : {}) }];
+  });
+}
+
 export function attentionCommand(item: NeedItem): string {
+  if (item.kind === "result") return `ahub results${item.id ? ` --read ${item.id}` : ""}`;
   if (item.kind === "offer") return `open ${item.peer}: task #${item.id} is waiting for it; ahub task show ${item.id}`;
   if (item.kind === "stall") return `ahub task show ${item.id}; configure the peer or ahub task assign ${item.id} <peer>, or ahub task cancel ${item.id} --reason <text>`;
   if (item.kind === "delivery") return `ahub queue list${item.id ? `; ahub queue show ${item.id}` : ""}`;
@@ -60,5 +74,6 @@ export function attentionCommand(item: NeedItem): string {
   if (item.kind === "recovery") return `ahub recovery status${item.id ? ` ${item.id}` : ""}`;
   if (item.kind === "budget") return "ahub budget";
   if (item.kind === "default") return "ahub permission";
+  if (item.kind === "question") return `A answers it here; ahub answer lists it and ${item.id ? `ahub answer ${item.id} <question>=<option>` : "ahub answer <set> <question>=<option>"} answers`;
   return item.peer ? `ahub say @${item.peer} <message>` : "ahub console";
 }

package/src/cli/backlog-return-args.ts

@@ -0,0 +1,37 @@
+/**
+ * #1177: `ahub backlog return <task> <revision> <reason...> [--reserved <peer> | --unreserve]`. Pure: argv to the `hub_backlog_return_untouched` arguments, and never a
+ * decision about whether the return applies (the hub checks authority, the revision and the reservation). With neither flag the arguments are exactly what the command
+ * sent before, so today's behaviour is unchanged.
+ *
+ * The flags are the two reservation edits the tool already takes as `fields.reserved` (a peer id, or null to clear). They are read wherever they stand among the reason's
+ * words, are removed from the reason, and at most one of them may be given: a reason is free text, so the only way to tell a flag from a word of it is that it is one of
+ * these exact tokens. `--reserved=<peer>` is the same as `--reserved <peer>`.
+ */
+const PEER = /^[a-z][a-z0-9-]{0,31}$/;
+export type BacklogReturn = { ok: true; value: { reason: string; fields?: { reserved: string | null } } } | { ok: false; error: string };
+export const BACKLOG_RETURN_USAGE = "usage: ahub backlog return <task> <revision> <reason...> [--reserved <peer> | --unreserve]";
+
+export function parseBacklogReturn(words: readonly string[]): BacklogReturn {
+  const fail = (error: string): { ok: false; error: string } => ({ ok: false, error: `${BACKLOG_RETURN_USAGE}; ${error}` });
+  const reason: string[] = [];
+  let reserved: string | null | undefined;
+  for (let index = 0; index < words.length; index++) {
+    const word = words[index]!;
+    if (word === "--unreserve") {
+      if (reserved !== undefined) return fail("give one of --reserved and --unreserve, once");
+      reserved = null;
+      continue;
+    }
+    if (word === "--reserved" || word.startsWith("--reserved=")) {
+      if (reserved !== undefined) return fail("give one of --reserved and --unreserve, once");
+      const peer = word === "--reserved" ? words[++index] : word.slice("--reserved=".length);
+      if (peer === undefined || !PEER.test(peer)) return fail("--reserved needs a peer id like codex");
+      reserved = peer;
+      continue;
+    }
+    reason.push(word);
+  }
+  const text = reason.join(" ").trim();
+  if (!text) return fail("a reason is required");
+  return { ok: true, value: { reason: text, ...(reserved !== undefined ? { fields: { reserved } } : {}) } };
+}

package/src/cli/console-question.ts

@@ -0,0 +1,110 @@
+/**
+ * #1053 T4: answering a question a peer asked with hub_ask, with the console's keys. Pure: the reducer passes it the open rows and a key, and it answers with the
+ * next flow state, the answers once the last question is done, or nothing. The hub validates every answer against the stored row; this only builds them.
+ *
+ * One question at a time, the oldest open set first: a digit picks that option (single choice) or toggles it (multi, Enter moves on), `o` types free text where the
+ * question allows it (Enter keeps it, Esc stops typing), Esc leaves the flow. Answering is neither outward nor destructive, so the last answer is sent with no confirm.
+ */
+import { MAX_OTHER, type AskQuestion } from "../hub/questions.ts";
+
+/** What the hub's `questions` read returns for one open set. The text is the person's: it is shown here and never logged. */
+export interface QuestionView { set: string; peer: string; created: number; private?: boolean; questions: AskQuestion[] }
+/** `picks` and `others` are Maps, never plain objects: a question id is the agent's (`constructor`, `toString` and `__proto__` are valid ids), and an object lookup would find an inherited member. */
+export interface QuestionFlow { set: string; index: number; picks: Map<string, string[]>; others: Map<string, string>; typing?: string }
+export interface FlowAnswer { questionId: string; optionIds: string[]; other?: string }
+export interface FlowStep { flow?: QuestionFlow; answers?: FlowAnswer[]; notice?: string }
+
+/** Rows from the hub's reply, copied by shape so a malformed row is dropped rather than rendered. */
+export function questionRows(raw: unknown): QuestionView[] {
+  if (!Array.isArray(raw)) return [];
+  return raw.flatMap<QuestionView>(row => {
+    if (!row || typeof row !== "object" || typeof row.set !== "string" || typeof row.peer !== "string" || !Array.isArray(row.questions) || !row.questions.length) return [];
+    return [{ set: row.set, peer: row.peer, created: Number.isSafeInteger(row.created) ? row.created : 0, ...(row.private === true ? { private: true } : {}), questions: row.questions as AskQuestion[] }];
+  }).sort((a, b) => a.created - b.created || a.set.localeCompare(b.set));
+}
+
+export const startFlow = (row: QuestionView): QuestionFlow => ({ set: row.set, index: 0, picks: new Map(), others: new Map() });
+
+const printable = (key: string) => key.length > 0 && !key.startsWith("\x1b") && ![...key].some(char => char < " " || char === "\x7f");
+
+export function stepFlow(flow: QuestionFlow, row: QuestionView, key: string): FlowStep {
+  const question = row.questions[flow.index];
+  if (!question) return { notice: "that question has no more parts" };
+  const next: QuestionFlow = { ...flow, picks: new Map(flow.picks), others: new Map(flow.others) };
+  const advance = (): FlowStep => {
+    next.index = flow.index + 1; next.typing = undefined;
+    if (next.index < row.questions.length) return { flow: next };
+    return { answers: row.questions.map(item => ({ questionId: item.id, optionIds: next.picks.get(item.id) ?? [], ...(next.others.get(item.id) ? { other: next.others.get(item.id)! } : {}) })) };
+  };
+  if (flow.typing !== undefined) {
+    if (key === "\x1b") { next.typing = undefined; return { flow: next }; }
+    if (key === "\r" || key === "\n") {
+      const text = flow.typing.trim();
+      if (!text) { next.typing = undefined; return { flow: next }; }
+      next.others.set(question.id, text);
+      if (question.multi !== true) next.picks.set(question.id, []);
+      return advance();
+    }
+    if (key === "\x7f" || key === "\b") { next.typing = Array.from(flow.typing).slice(0, -1).join(""); return { flow: next }; }
+    if (printable(key)) next.typing = Array.from(flow.typing + key).slice(0, MAX_OTHER).join("");
+    return { flow: next };
+  }
+  if (key === "\x1b") return { notice: "answer cancelled; the question stays open" };
+  if (key === "o" && question.allowOther === true) { next.typing = ""; return { flow: next }; }
+  if (/^[1-9]$/.test(key)) {
+    const option = question.options[Number(key) - 1];
+    if (!option) return { flow: next };
+    if (question.multi === true) {
+      const chosen = new Set(next.picks.get(question.id) ?? []);
+      if (chosen.has(option.id)) chosen.delete(option.id); else chosen.add(option.id);
+      next.picks.set(question.id, question.options.filter(item => chosen.has(item.id)).map(item => item.id));
+      return { flow: next };
+    }
+    next.picks.set(question.id, [option.id]); next.others.delete(question.id);
+    return advance();
+  }
+  if ((key === "\r" || key === "\n") && question.multi === true && ((next.picks.get(question.id)?.length ?? 0) > 0 || next.others.get(question.id))) return advance();
+  return { flow: next };
+}
+
+/**
+ * A pasted chunk while the person is typing an `o` answer: its printable characters join the text, bounded as typed keys are. A paste is only ever text here: a newline
+ * in it is a space and an escape or control character is dropped, so a pasted Enter or Esc can never keep, send or leave the answer. Outside text entry it changes nothing.
+ */
+export function pasteFlow(flow: QuestionFlow, pasted: string): QuestionFlow {
+  if (flow.typing === undefined) return flow;
+  const text = [...pasted.replace(/[\r\n]+/g, " ")].filter(char => printable(char)).join("");
+  return { ...flow, typing: Array.from(flow.typing + text).slice(0, MAX_OTHER).join("") };
+}
+
+/**
+ * The question as lines to show in a wrapped area, never the one-line footer: the head, the prompt, then every option numbered with the chosen ones marked. The footer
+ * clips a long line, and a digit submits at once, so an option that is not on screen must never be one a key can pick. `text` flattens agent text for a terminal.
+ */
+export function flowBody(flow: QuestionFlow, row: QuestionView, text: (value: unknown) => string): { head: string; prompt: string; options: string[] } | undefined {
+  const question = row.questions[flow.index];
+  if (!question) return undefined;
+  const chosen = new Set(flow.picks.get(question.id) ?? []);
+  return {
+    head: `${row.peer} asks ${flow.index + 1}/${row.questions.length}`,
+    prompt: text(question.prompt),
+    options: question.options.map((option, index) => `${index + 1}${question.multi === true ? (chosen.has(option.id) ? "*" : " ") : ""} ${text(option.label)}`),
+  };
+}
+
+/**
+ * The footer line while a flow is open: only the keys that act, and the text being typed (its tail, so the cursor stays in view). It names no option and no prompt: those
+ * are in `flowBody`'s wrapped area, where they cannot be cut off.
+ */
+export function flowPrompt(flow: QuestionFlow, row: QuestionView, text: (value: unknown) => string, columns = 80): string {
+  const question = row.questions[flow.index];
+  if (!question) return "";
+  const head = `${row.peer} asks ${flow.index + 1}/${row.questions.length}`;
+  if (flow.typing !== undefined) {
+    const tail = Array.from(text(flow.typing)), room = Math.max(8, columns - 32);
+    return `${head}  other: ${tail.length > room ? "..." + tail.slice(-room).join("") : tail.join("")}_  Enter keeps  Esc back`;
+  }
+  const chosen = new Set(flow.picks.get(question.id) ?? []);
+  const marked = question.multi === true ? question.options.flatMap((option, index) => chosen.has(option.id) ? [String(index + 1)] : []) : [];
+  return `${head}  number picks${question.allowOther === true ? "  o other" : ""}${question.multi === true ? `${marked.length ? `  chosen ${marked.join(",")}` : ""}  Enter done` : ""}  Esc cancel`;
+}