@staix/agent-hub 0.29.0 → 0.31.0

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/autonomy.ts

@@ -1,3 +1,7 @@
+import { homedir } from "node:os";
+import type { AutonomyPeerStatus } from "../hub/autonomy.ts";
+import type { ClaudeHomeCheck } from "./claude-homes.ts";
+
 export { autonomyEnvironment } from "../hub/autonomy.ts";
 export const AUTONOMY_USAGE = "usage: ahub autonomy on [--all-projects] [--yes] | off [--all-projects] | status [--json]";
 export interface AutonomyCliPorts {
@@ -40,5 +44,66 @@ export async function runAutonomy(args: string[], ports: AutonomyCliPorts): Prom
   }
   if (action === "status" && ports.decorateStatus) reply = await ports.decorateStatus(reply);
   if (action === "status" && args.includes("--json")) ports.print(JSON.stringify(reply.status));
-  else for (const line of Array.isArray(reply.lines) ? reply.lines : typeof reply.text === "string" ? [reply.text] : []) if (typeof line === "string") ports.print(line);
+  else {
+    const lines = action === "status" && reply.status && typeof reply.status === "object"
+      ? renderAutonomyStatus(reply.status as Record<string, unknown>) : null;
+    for (const line of lines ?? (Array.isArray(reply.lines) ? reply.lines : typeof reply.text === "string" ? [reply.text] : [])) if (typeof line === "string") ports.print(line);
+  }
+}
+
+/** Human presentation only; the daemon report and JSON wire output stay unchanged. */
+export function renderAutonomyStatus(status: Record<string, unknown>, home = homedir()): string[] | null {
+  if (!Array.isArray(status.peers)) return null;
+  const peers = status.peers as AutonomyPeerStatus[];
+  const machine = status.machineDefault as { enabled: boolean; notice?: string } | undefined;
+  const lines = [`Project autonomy · environment ${status.environment}${machine ? ` · machine default ${machine.enabled ? "on" : "off"}` : ""}`];
+  if (status.runtime === "stopped") lines.push("The hub is stopped; effective runtime modes and retained consent are unknown.");
+  lines.push("");
+  if (peers.length) {
+    const rows = [["PEER", "NOW", "NEXT START"], ...peers.map(peer => [peer.id, peer.effectiveMode, peer.nextMode ?? "unmanaged"])];
+    const widths = rows[0]!.map((_, column) => Math.max(...rows.map(row => row[column]!.length)));
+    for (const row of rows) lines.push(row.map((value, column) => column < row.length - 1 ? value.padEnd(widths[column]!) : value).join("  "));
+  } else lines.push("No peers were inspected.");
+
+  const floors = new Map<string, { row: AutonomyPeerStatus["floor"][number]; peers: Set<string> }>();
+  const classes = new Set<string>(), enforced = new Set<string>();
+  const unknowns = new Map<string, Set<string>>();
+  for (const peer of peers) {
+    for (const row of peer.floor ?? []) {
+      classes.add(row.class);
+      if (row.status === "hub-enforced" || row.status === "structural-guard") enforced.add(row.class);
+      const key = JSON.stringify([row.class, row.status, row.reason]);
+      let group = floors.get(key);
+      if (!group) { group = { row, peers: new Set() }; floors.set(key, group); }
+      group.peers.add(peer.id);
+    }
+    for (const text of peer.missing ?? []) {
+      if ((peer.floor ?? []).some(row => text.startsWith(`${row.class}: `))) continue;
+      let group = unknowns.get(text);
+      if (!group) { group = new Set(); unknowns.set(text, group); }
+      group.add(peer.id);
+    }
+  }
+  if (peers.length) lines.push("", `Guarded actions (${classes.size} classes; ${enforced.size} enforced for at least one peer)`);
+  for (const { row, peers: members } of floors.values()) {
+    lines.push(`  ${row.class} · ${row.status} · ${members.size === peers.length ? "all peers" : [...members].join(", ")}`, `    ${row.reason}`);
+  }
+  const projectMissing = Array.isArray(status.missing) ? status.missing.filter((text): text is string => typeof text === "string") : [];
+  if (unknowns.size || projectMissing.length) {
+    lines.push("", "Unknowns");
+    for (const text of projectMissing) lines.push(`  project: ${text}`);
+    for (const [text, members] of unknowns) lines.push(`  ${[...members].join(", ")}: ${text}`);
+  }
+  if (machine?.notice) lines.push("", machine.notice);
+  const notices = status.claudeHomeNotices as string[] | undefined;
+  if (Array.isArray(status.claudeHomes) || notices?.length) {
+    lines.push("", "Claude homes");
+    for (const notice of notices ?? []) lines.push(`  ${notice}`);
+    for (const profile of (status.claudeHomes ?? []) as ClaudeHomeCheck[]) {
+      const path = profile.home.path;
+      const display = path === home ? "~" : path.startsWith(`${home}/`) ? `~${path.slice(home.length)}` : path;
+      lines.push(`  ${display}: plugin ${profile.plugin.state}; hook ${profile.hook.state}. ${profile.hook.reason}`);
+    }
+  }
+  return lines;
 }

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