@staix/agent-hub 0.30.0 → 0.31.0

package/src/cli/main.ts

@@ -3,6 +3,7 @@ import { assertConductorOperationLocal, authorizeConductorOperation, authorizeCo
 import { runtimePruneHealth } from "../hub/runtime-prune-health.ts";
 import { conductorLocalOperation, conductorOperation, OPERATIONAL_PERSON_GUIDANCE } from "../hub/operational-authority.ts";
 import { sayRecipients } from "./say-input.ts";
+import { parseAnswerArgs } from "./answer-args.ts";
 import type { DeliverableRow } from "../hub/tasks.ts";
 import { kimiSourceRow } from "../hub/budget-notes.ts";
 import { hubGitSync, hubGitEnv } from "../hub/git.ts";
@@ -30,6 +31,8 @@ import { renderIntake, renderIntakeChange } from "./intake-output.ts";
 import { renderLearnChange, renderLearnList } from "./learn-output.ts";
 import { renderCapabilities } from "./capabilities-output.ts";
 import { parseStudyArgs } from "./study.ts";
+import { parseBacklogReturn } from "./backlog-return-args.ts";
+import { parseResultsArgs } from "./results-args.ts";
 import { renderExperiments, renderStudyList, renderStudyReceipt, renderStudyShow } from "./study-output.ts";
 import { renderHandoffReceipt, renderHandoffs } from "./handoff-output.ts";
 import { parseHandoffArgs } from "./handoff-args.ts";
@@ -44,8 +47,8 @@ import { discoverClaudeHomes } from "./claude-homes.ts";
 import { setupClaudeHomes } from "./setup-homes.ts";
 import { registerAconPlugin } from "./acon-register.ts";
 import { petView, readPet, renderPet } from "./pet.ts";
-import { startPetWindow, closePetWindow } from "../pet/window.ts";
-import { loadPetConfig, savePetPalette } from "./pet-config.ts";
+import { PET_WINDOW_RETIRED_NOTICE, petPalette } from "../pet/config.ts";
+import { loadPetConfig } from "./pet-config.ts";
 import { projectProfile, resolveProfile } from "../hub/profiles.ts";
 import { catalogAssignments, loadRoleCatalog, selectedRoles } from "../hub/roles.ts";
 import { attachWatch } from "./watch.ts";
@@ -88,7 +91,7 @@ import { childEnv, personEnv } from "../hub/child-process.ts";
 import { abortRecovery, createOperation, disposeRecovery, recordRecoveryDelegation, repairedFreshSession, reattachRecovery, liveProjects, nextChoices, nextActionsText, publicOperation, recoveryCommand, registeredProjects, runRecovery, type RecoveryOperation, type Inspection } from "./upgrade.ts";
 import { endPlannedPeer, makeRecoveryDriver, makeUpgradePlan, preserveSource } from "./upgrade-runtime.ts";
 import { exactVersion, latestRelease, newerVersion } from "./recovery-package.ts";
-import { runtimeVersionWarnings } from "./runtime-version-warning.ts";
+import { globalUpdateAdvice, runtimeVersionWarnings } from "./runtime-version-warning.ts";
 import { operationScreen, planScreen, type ScreenIO, type UpgradeHost } from "./upgrade-interactive.ts";
 import { readRecoveryPresentationFlags } from "./upgrade-presentation-flags.ts";
 import { renderOperation, renderBlocked, renderSummary, type RecoveryPresentationOptions } from "./upgrade-presentation.ts";
@@ -717,6 +720,7 @@ function upgradeHost(kind: "restart" | "upgrade", version: string): UpgradeHost
     runner: recoveryRunner,
     live: (op) => liveProjects(op, makeRecoveryDriver(undefined, delegatedPeer, undefined, conductorPeer).inspect),
     endInspection: recoveryEndInspection,
+    afterCompleted: (op) => globalUpdateLines(op.plan.version),
     endPeer: (planned, peer) => endPlannedPeer(planned, peer),
     runnerStoppable: (id) => signedRunner(id) !== undefined,
     stopRunner: (id) => stopSignedRunner(id),
@@ -725,6 +729,16 @@ function upgradeHost(kind: "restart" | "upgrade", version: string): UpgradeHost
   };
 }
 
+/**
+ * #718 (#1179): the step for the global CLI and the shared Claude plugin, when either is older than the daemon `target` installs. The plugin version comes from the same `claude plugin list`
+ * probe `ahub doctor` reads (10 s, no shell); a missing `claude`, a failure or an unreadable list is an unknown plugin, which is never a claim. The CLI is this process, or, when an older CLI handed the
+ * upgrade to this release's own coordinator (`AGENTHUB_UPGRADE_HANDOVER=1`), the older one that started it. Advice only: nothing here can fail an upgrade.
+ */
+function globalUpdateLines(target: string): string[] {
+  return globalUpdateAdvice({ target, cli: VERSION, handedOver: process.env.AGENTHUB_UPGRADE_HANDOVER === "1", packageRoot: join(import.meta.dir, "..", ".."),
+    probe: () => spawnSync(DOCTOR_PLUGIN_PROBE.command, [...DOCTOR_PLUGIN_PROBE.argv], { encoding: "utf8", timeout: 10_000 }) });
+}
+
 async function upgrade(kind: "restart" | "upgrade"): Promise<void> {
   const display = recoveryDisplay();
   const { one, rest } = takeFlags(display.args, ["--to"], []);
@@ -799,7 +813,11 @@ async function upgrade(kind: "restart" | "upgrade"): Promise<void> {
     writeOperation(id, operation);
   } else operation = createOperation(plan, sourceRoot, undefined, delegatedPeer ? { peer: delegatedPeer, command: kind } : undefined);
   if (display.json) { spawnRecovery(operation, true); console.log(JSON.stringify(publicOperation(operation), null, 2)); }
-  else spawnRecovery(operation, false, humanRecovery(false) ? display.options : undefined);
+  else {
+    spawnRecovery(operation, false, humanRecovery(false) ? display.options : undefined);
+    // #718: the upgrade is only scheduled here, but the step is already known: the CLI and the plugin are compared with the daemon this upgrade installs. Never in --json, which stays the raw document.
+    if (kind === "upgrade") printRecovery(globalUpdateLines(plan.version));
+  }
 }
 
 /** Strict person command: recorded identity only, no session or terminal overrides. */
@@ -1162,8 +1180,6 @@ const commands: Record<string, () => Promise<void> | void> = {
     const status = await startProject(registeredProject(), { unattended, liveTest, ...(recoveryLauncherCurrent ? { current: recoveryLauncherCurrent, env: { ...personEnv(process.env), AGENTHUB_RECOVERY_OPERATION: continuationId, AGENTHUB_PEER_ID: continuationPeer, AGENTHUB_RECOVERY_CONDUCTOR: continuationPeer, AGENTHUB_RECOVERY_CONTINUATION: continuationId } } : {}) });
     console.log(`ahub up (ws://127.0.0.1:${status.controlPort}), state in ${stateDir}`);
     if (recoveryLauncherCurrent) { recoveryLauncherCurrent(); return; }
-    try { if (loadPetConfig(cwd).window) console.log(await startPetWindow(stateDir, cwd)); }
-    catch { console.error("Pet window was not started; run ahub pet --window to inspect it."); }
     // #608: the default agent set, only for a person's own `ahub up` (never an agent's, a live test's, or an upgrade or recovery relaunch, which set AGENTHUB_RECOVERY_OPERATION).
     if (!args.includes("--no-agents") && !liveTest && caller.role === "console" && identity.role === "console" && !process.env.AGENTHUB_RECOVERY_OPERATION) {
       try {
@@ -1410,7 +1426,10 @@ const commands: Record<string, () => Promise<void> | void> = {
     }
     if (sub === "groom" && operands.length === 1) return shown(renderGroom)(taskOp("hub_planner_groom", {}));
     if (["return", "return-untouched"].includes(sub ?? "") && /^[1-9]\d*$/.test(id ?? "") && /^\d+$/.test(revision ?? "") && operands.length >= 4) {
-      return shown((data, columns, now) => renderBacklogResult("return-untouched", data, columns, now))(taskOp("hub_backlog_return_untouched", { id: Number(id), revision: Number(revision), reason: operands.slice(3).join(" ") }));
+      // #1177: `--reserved <peer>` / `--unreserve` edit the reservation atomically with the return (fields.reserved); with neither, the arguments are what they always were.
+      const returned = parseBacklogReturn(operands.slice(3));
+      if (!returned.ok) return fail(returned.error);
+      return shown((data, columns, now) => renderBacklogResult("return-untouched", data, columns, now))(taskOp("hub_backlog_return_untouched", { id: Number(id), revision: Number(revision), reason: returned.value.reason, ...(returned.value.fields ? { fields: returned.value.fields } : {}) }));
     }
     if (sub === "add" && args.length >= 3) return console.log(await taskOp("hub_task_propose", { class: id, title: args.slice(2).join(" "), backlog: true }));
     if (!/^[1-9]\d*$/.test(id ?? "")) fail("usage: ahub backlog list|add <class> <title...>|pull|return <id>|plan|pin <id> <revision> <value> <reason...>|undo <id> <revision>");
@@ -1422,12 +1441,12 @@ const commands: Record<string, () => Promise<void> | void> = {
       return shown((data, columns, now) => renderBacklogResult("split", data, columns, now))(taskOp("hub_backlog_split", { id: Number(id), revision: Number(revision), parts, reason: reason.join(" ") }));
     }
     if (sub === "undo" && operands.length === 3) return shown((data, columns, now) => renderBacklogResult("undo", data, columns, now))(taskOp("hub_backlog_undo", { id: Number(id), revision: Number(revision) }));
-    if (!["plan", "pin"].includes(sub ?? "") || !value || !reason.length) fail("planning needs fields and a reason");
+    if (!["plan", "pin", "person"].includes(sub ?? "") || !value || !reason.length) fail("planning needs fields and a reason");
     let fields: unknown;
-    try { fields = sub === "pin" ? { pinned: value === "true" ? true : value === "false" ? false : undefined } : JSON.parse(value); }
+    try { fields = sub === "pin" ? { pinned: value === "true" ? true : value === "false" ? false : undefined } : sub === "person" ? { needsPerson: value === "true" ? true : value === "false" ? false : undefined } : JSON.parse(value); }
     catch { return fail("planning fields must be JSON"); }
-    if (sub === "pin" && value !== "true" && value !== "false") fail("pin must be true or false");
-    return shown((data, columns, now) => renderBacklogResult(sub as "plan" | "pin", data, columns, now))(taskOp("hub_backlog_plan", { id: Number(id), revision: Number(revision), fields, reason: reason.join(" ") }));
+    if ((sub === "pin" || sub === "person") && value !== "true" && value !== "false") fail(`${sub} must be true or false`);
+    return shown((data, columns, now) => renderBacklogResult(sub === "person" ? "plan" : sub as "plan" | "pin", data, columns, now))(taskOp("hub_backlog_plan", { id: Number(id), revision: Number(revision), fields, reason: reason.join(" ") }));
   },
 
   release: async () => {
@@ -1927,9 +1946,11 @@ const commands: Record<string, () => Promise<void> | void> = {
     if (sub === "handoff") {
       // #604: work that belongs to ANOTHER project that runs agent-hub goes onto that project's board. The person's form (a console command: the classifier gives an agent `console` for it, and an
       // agent uses hub_task_handoff); the hub resolves the target, asks its daemon and records the answer. Nothing is queued: a target that is not running is named with the action.
-      const present = outputOptions(splitPresentation(rest, { valueFlags: ["--project", "--path", "--issue", "--task", "--detail"], edges: true }).flags);
-      const parsed = parseHandoffArgs(splitPresentation(rest, { valueFlags: ["--project", "--path", "--issue", "--task", "--detail"], edges: true }).operands);
+      const present = outputOptions(splitPresentation(rest, { valueFlags: ["--project", "--path", "--issue", "--task", "--detail", "--duplicate-ok", "--key"], edges: true }).flags);
+      const parsed = parseHandoffArgs(splitPresentation(rest, { valueFlags: ["--project", "--path", "--issue", "--task", "--detail", "--duplicate-ok", "--key"], edges: true }).operands);
       if ("usage" in parsed) return fail(parsed.usage);
+      // #734: the person's list (age and reachability of each target) and sync (ask the targets now); both read the same rows `ahub board --handoffs` shows.
+      if ("view" in parsed) return showToolText(data => renderHandoffs(data, present.columns), await taskOp(parsed.view === "sync" ? "hub_task_handoff_sync" : "hub_task_handoffs", {}), present);
       const text = await taskOp("hub_task_handoff", { ...parsed });
       return showToolText(data => renderHandoffReceipt(data, present.columns), text, present);
     }
@@ -2005,6 +2026,35 @@ const commands: Record<string, () => Promise<void> | void> = {
     } finally { hub.close(); }
   },
 
+  peer: async () => {
+    const options = outputOptions();
+    const { operands, flags } = splitPresentation(args);
+    const usage = "usage: ahub peer takeover <peer> [standby-id] [--json] [--color=auto|always|never]";
+    const [sub, peer, standbyId, ...extra] = operands;
+    const uuid = (value: string | undefined): value is string => typeof value === "string" && /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(value);
+    if (sub !== "takeover" || !peer || !/^[a-z][a-z0-9-]{0,31}$/.test(peer) || extra.length || standbyId !== undefined && !uuid(standbyId)
+      || flags.some(flag => flag !== "--json" && !flag.startsWith("--color="))) fail(usage);
+    const hub = await connect();
+    try {
+      if (!hub.features.includes("peer_takeover")) fail("running hub lacks peer_takeover; upgrade and restart the running hub first");
+      let reply: any;
+      try { reply = await hub.request({ t: "peer_takeover", peer, ...(standbyId ? { standbyId } : {}) }, 5000); }
+      catch (error) {
+        const message = String((error as Error).message ?? "");
+        if (/unknown (?:control )?(?:message|request|command)(?:\b|:)|this hub does not know \"peer_takeover\"/i.test(message)) fail(`${message}; upgrade and restart the running hub to use ahub peer takeover`);
+        fail(`${message || "peer takeover result is unconfirmed"}; inspect ahub status before retrying; takeover may already have started`);
+      }
+      const transportError = String(reply.error ?? "");
+      if (reply.ok === false && (transportError === "hub connection closed" || transportError === "hub request could not be sent" || /^no answer from the hub within \d+ s$/.test(transportError))) {
+        fail(`${transportError}; inspect ahub status before retrying; takeover may already have started`);
+      }
+      if (reply.ok !== true) fail(String(reply.error ?? "peer takeover was refused"), reply.refusalAudited === true, reply.authorityRefused);
+      if (reply.outcome !== "requested" || !uuid(reply.standbyId) || standbyId !== undefined && reply.standbyId !== standbyId) fail("peer takeover result was not confirmed; refresh ahub status");
+      if (options.json) console.log(JSON.stringify(reply, null, 2));
+      else console.log(`${peer}: old session detached; standby attachment requested`);
+    } finally { hub.close(); }
+  },
+
   title: async () => {
     const [peer, ...words] = args;
     if (!peer || !words.length) fail("usage: ahub title <peer> <text...>");
@@ -2274,15 +2324,77 @@ const commands: Record<string, () => Promise<void> | void> = {
     hub.close();
   },
 
+  // #1053 T4: the person's answer to a question a peer asked with hub_ask. No operands lists the open questions; `<set> <question>=<option>[,<option>] [--other <text>]` answers one.
+  // The hub validates every answer against the stored row and names a refusal by position, never by the offered text. Console role only (classifyPeerCommand's default).
+  answer: async () => {
+    const options = outputOptions();
+    const operands = args.filter(arg => arg !== "--json" && !arg.startsWith("--color=") && arg !== "--full");
+    const hub = await connect();
+    try {
+      if (!operands.length) {
+        const reply = await hub.request({ t: "questions" });
+        if (reply.ok === false) return fail(String(reply.error ?? "questions are unavailable"));
+        const rows = Array.isArray(reply.questions) ? reply.questions : [];
+        if (options.json) return console.log(JSON.stringify(rows, null, 2));
+        if (!rows.length) return console.log("no open questions");
+        for (const row of rows) {
+          console.log(`${row.set}  ${row.peer} asks${row.private ? " (private)" : ""}`);
+          for (const question of row.questions) {
+            console.log(`  ${question.id}: ${terminalText(String(question.prompt))}${question.multi ? "  (choose any)" : ""}${question.allowOther ? "  (or --other <text>)" : ""}`);
+            for (const option of question.options) console.log(`    ${option.id}  ${terminalText(String(option.label))}${option.description ? `  - ${terminalText(String(option.description))}` : ""}`);
+          }
+          console.log(`  answer with: ahub answer ${row.set} ${row.questions.map((question: { id: string; options: { id: string }[] }) => `${question.id}=${question.options[0]?.id ?? "<option>"}`).join(" ")}`);
+        }
+        return;
+      }
+      const parsed = parseAnswerArgs(operands);
+      if (!parsed.ok) return fail(parsed.error);
+      const reply = await hub.request({ t: "answer", surface: "terminal", questionSet: parsed.value.set, answers: parsed.value.answers });
+      if (reply.ok === false) return fail(String(reply.error ?? "the answer was refused"));
+      if (options.json) return console.log(JSON.stringify({ ok: true, questionSet: reply.questionSet, state: reply.state }));
+      console.log(`answered ${reply.questionSet ?? parsed.value.set}`);
+    } finally { hub.close(); }
+  },
+
+  // #1054 T4: the results a run a person started left behind. A person's command (an agent shell is refused before the hub); reads change nothing, and only an explicit flag writes a receipt.
+  results: async () => {
+    const options = outputOptions();
+    const parsed = parseResultsArgs(args.filter(arg => arg !== "--json" && !arg.startsWith("--color=") && arg !== "--full"));
+    if (!parsed.ok) return fail(parsed.error);
+    const request = parsed.value;
+    const hub = await connect();
+    try {
+      if (request.action === "read") {
+        const reply = await hub.request({ t: "result_seen", id: request.id, surface: "terminal" });
+        if (reply.ok === false) return fail(String(reply.error ?? "the result could not be marked read"));
+        return options.json ? console.log(JSON.stringify({ ok: true, id: request.id, read: true })) : console.log(`marked ${request.id} read`);
+      }
+      if (request.action === "read-all" || request.action === "unread-last") {
+        const reply = await hub.request({ t: "results", action: request.action, surface: "terminal" });
+        if (reply.ok === false) return fail(String(reply.error ?? "the receipt could not be written"));
+        if (options.json) return console.log(JSON.stringify(request.action === "read-all" ? { ok: true, marked: reply.marked } : { ok: true, unread: reply.unread }));
+        return console.log(request.action === "read-all" ? `marked ${reply.marked} ${reply.marked === 1 ? "result" : "results"} read` : `marked ${reply.unread} unread again`);
+      }
+      const reply = await hub.request({ t: "results", unread: request.unread });
+      if (reply.ok === false) return fail(String(reply.error ?? "results are unavailable"));
+      const rows = Array.isArray(reply.results) ? reply.results : [];
+      if (options.json) return console.log(JSON.stringify(rows, null, 2));
+      if (!rows.length) return console.log(request.unread ? "no unread results" : "no results");
+      for (const row of rows) console.log(`${row.read ? " " : "*"} ${row.id}  ${terminalText(String(row.title))}  ${new Date(Number(row.settledAt)).toISOString().replace("T", " ").slice(0, 16)}  ${Math.round(Number(row.ms) / 1000)}s${row.read ? "" : `  ahub results --read ${row.id}`}`);
+      // The listing holds the newest 100. Unread results are never pruned, so when more exist than shown, say how many and how to reach them (status still counts every one).
+      if (Number(reply.more) > 0) console.log(`... and ${Number(reply.more)} older unread; ahub results --read-all marks them all, or read the newest ones first`);
+    } finally { hub.close(); }
+  },
+
   pet: async () => {
     if (args.includes("--window")) {
       if (args.some(arg => !["--window", "--close"].includes(arg))) return fail("usage: ahub pet --window [--close]");
-      return console.log(await (args.includes("--close") ? closePetWindow(stateDir) : startPetWindow(stateDir, cwd)));
+      return console.log(PET_WINDOW_RETIRED_NOTICE);
     }
     if (args.includes("--palette")) {
       if (args.length !== 2 || args[0] !== "--palette") return fail("usage: ahub pet [--short] | --window [--close] | --palette <blue|teal|violet|ochre>");
-      try { return console.log(savePetPalette(cwd, args[1]!)); }
-      catch (error) { return fail((error as Error).message); }
+      if (!petPalette(args[1])) return fail("Unknown pet palette; use blue, teal, violet or ochre (a/b/c/d).");
+      return console.log(PET_WINDOW_RETIRED_NOTICE);
     }
     if (args.some(arg => arg !== "--short")) return fail("usage: ahub pet [--short] | --window [--close] | --palette <blue|teal|violet|ochre>");
     const short = args.includes("--short");

package/src/cli/memory.ts

@@ -14,7 +14,7 @@ import { memoryAnchorTaskIdentity, memoryStaleAnchors, unavailableMemoryStaleAnc
 import { MEMORY_SYMBOL_START_BUDGET_MS } from "../hub/memory-symbols.ts";
 import { detectCliIdentity } from "./identity.ts";
 import { createStalenessProbe } from "../hub/memory-staleness.ts";
-import { looksSecret, memoryProjectKey, pathCandidates, readProfileJSON, resolveShardProfile, type MemoryStore } from "@staix/agent-mem";
+import { looksSecret, memoryHome, memoryProjectKey, pathCandidates, readProfileJSON, resolveShardProfile, type MemoryStore } from "@staix/agent-mem";
 import type { SyncOptions } from "@staix/agent-mem";
 import { memoryUsage, goalUsage, rawMemoryCommand, rawGoalCommand } from "@staix/agent-mem";
 
@@ -24,9 +24,10 @@ import { mentionsPrivatePath, promotionScreen, withoutPii } from "../hub/memory-
 import { currentRouting, detectSignals } from "../hub/routing.ts";
 import { loadConfig } from "../hub/daemon.ts";
 import { bindProfileMemory, memoryProjectFor, memoryProjectForStore, openProfileMemory, MemoryProfileBinding, MEMORY_PROFILE_UNAVAILABLE, MEMORY_SPLIT_INCOMPLETE, type MemoryProfileReceipt, type ProfileMemoryOptions } from "../hub/memory-profile.ts";
+import { createMemorySyncPolicy, inspectDeclinedMemoryRows, projectMemorySyncText } from "../hub/memory-sync-policy.ts";
 
 export const GOAL_USAGE = goalUsage(AHUB_NAMES.goal);
-export const MEMORY_USAGE = `${memoryUsage(AHUB_NAMES.memory)} | decay [--days N] [--json] | profile-check [--json]`;
+export const MEMORY_USAGE = `${memoryUsage(AHUB_NAMES.memory)} | decay [--days N] [--json] | declined [--json] | profile-check [--json]`;
 
 const fail = (message: string): never => { throw new Error(message); };
 /** The project's config, or none when there is no valid one (reading memory needs none). */
@@ -36,6 +37,75 @@ const loadConfigSafe = (cwd: string) => { try { return loadConfig(cwd); } catch
 /** The project key: an injected store resolves the alias in its own home, the default open in the ambient one (#240). */
 const projectOf = (cwd: string, provided: MemoryStore | undefined): string => provided ? memoryProjectForStore(provided, cwd) : memoryProjectFor(cwd);
 
+/** Bounded, read-only lookup of current task paths that the daemon's promotion screen also considers. */
+function memoryTaskPaths(cwd: string, boundProject: string, rowProject: string, key: string): string[] | undefined {
+  if (rowProject !== boundProject) return [];
+  const identity = memoryAnchorTaskIdentity(key, boundProject);
+  if (!identity) return [];
+  let db: Database | undefined;
+  try {
+    const file = join(stateDirFor(cwd), "hub.db");
+    let stat;
+    try { stat = lstatSync(file); } catch (error) { if ((error as NodeJS.ErrnoException).code === "ENOENT") return []; throw error; }
+    if (!stat.isFile() || stat.isSymbolicLink()) return undefined;
+    db = new Database(file, { readonly: true, create: false });
+    db.run(`PRAGMA busy_timeout = ${HUB_DB_BUSY_TIMEOUT_MS}`);
+    const row = db.query(`SELECT id,created,length(refs) AS refsLength,length(plan) AS planLength,
+      CASE WHEN length(refs)<=65536 THEN refs END AS refs,CASE WHEN length(plan)<=65536 THEN plan END AS plan
+      FROM tasks WHERE id=? AND created=?`).get(identity.id, identity.created) as { id: number; created: number; refsLength: number; planLength: number; refs: string | null; plan: string | null } | null;
+    if (!row || row.id !== identity.id || row.created !== identity.created) return [];
+    if (row.refsLength > 65536 || row.planLength > 65536 || typeof row.refs !== "string" || typeof row.plan !== "string") return undefined;
+    const refs: unknown = JSON.parse(row.refs), plan: unknown = JSON.parse(row.plan);
+    if (!refs || typeof refs !== "object" || Array.isArray(refs) || !plan || typeof plan !== "object" || Array.isArray(plan)) return undefined;
+    const refPaths = (refs as TaskRefs).paths ?? [], planPaths = (plan as TaskPlan).paths ?? [];
+    if (!Array.isArray(refPaths) || !refPaths.every(path => typeof path === "string") || !Array.isArray(planPaths) || !planPaths.every(path => typeof path === "string")) return undefined;
+    return [...refPaths, ...planPaths];
+  } catch { return undefined; }
+  finally { db?.close(); }
+}
+
+function hostSyncPolicyInputs(cwd: string, home: string, boundProject: string, profile?: MemoryProfileReceipt): { version: string; denyPaths: string[]; piiPaths: string[]; piiPatterns: string[]; routing: ReturnType<typeof currentRouting> } {
+  const config = loadConfig(cwd), routing = currentRouting(cwd);
+  const denyPaths = [...config.local.deny], piiPaths = [...(config.pii?.paths ?? [])], piiPatterns = [...routing.signals.pii_patterns];
+  return { version: JSON.stringify({ home, boundProject, profile: profile ? { profile: profile.profile, generation: profile.generation, selectorRevision: profile.selectorRevision } : null, denyPaths, piiPaths, piiPatterns }), denyPaths, piiPaths, piiPatterns, routing };
+}
+function createHubMemorySyncPolicy(cwd: string, home: string, boundProject: string, profile?: MemoryProfileReceipt) {
+  const inputs = hostSyncPolicyInputs(cwd, home, boundProject, profile);
+  const policy = createMemorySyncPolicy({
+    home, cwd, denyPaths: inputs.denyPaths, piiPatterns: inputs.piiPatterns,
+    hostScreen: row => {
+      const task = typeof row.task === "string" ? row.task : "";
+      const project = typeof row.project === "string" ? row.project : "";
+      const about = Array.isArray(row.about) ? row.about.filter((node): node is string => typeof node === "string") : [];
+      const taskPaths = memoryTaskPaths(cwd, boundProject, project, task);
+      if (task && taskPaths === undefined) return { ok: false, rule: "hub privacy policy unavailable" };
+      const enrichedAbout = [...about, ...(taskPaths ?? []).map(path => `path:${path}`)];
+      const visible = withoutPii([{
+        title: typeof row.title === "string" ? row.title : null,
+        text: JSON.stringify(row), about: enrichedAbout,
+        ...(task ? { task } : {}), ...(project ? { project } : {}),
+      }], inputs.routing, cwd, inputs.piiPaths).length > 0;
+      return visible ? { ok: true } : { ok: false, rule: "hub privacy policy: PII pattern or private path" };
+    },
+  });
+  return { policy, version: inputs.version };
+}
+
+/** Preserve any trusted caller's stricter sync screen and bind its epoch into the host policy stamp. */
+export function composeMemorySyncOptions(host: Pick<SyncOptions, "screen" | "policyVersion">, caller?: Omit<SyncOptions, "remote">, canonical = false): Omit<SyncOptions, "remote"> {
+  return {
+    ...caller,
+    screen: row => {
+      try {
+        const content = projectMemorySyncText(row, canonical);
+        return host.screen?.(content) === true && (caller?.screen ? caller.screen(content) === true : true);
+      }
+      catch { return false; }
+    },
+    policyVersion: () => JSON.stringify([host.policyVersion?.() ?? null, caller?.policyVersion?.() ?? null]),
+  };
+}
+
 /** Bind each command at entry; the CLI closes default opens and injected stores remain caller-owned. */
 function commandStores(provided: MemoryStore | undefined, options: ProfileMemoryOptions, cwd: string) {
   try { return { ...(provided ? bindProfileMemory(provided, undefined, memoryProjectKey(cwd)) : openProfileMemory(options)), owned: !provided }; }
@@ -86,13 +156,47 @@ export async function memoryCommand(args: string[], cwd: string, opts: { store?:
       return profileOutput(text, false, profile, person);
     } finally { if (context.owned) store.close(); }
   }
+  if (rest[0] === "declined") {
+    if (!person) fail("memory declined requires person authority");
+    if (rest.length !== 1) fail("usage: ahub memory declined [--json]");
+    const project = projectOf(cwd, opts.store);
+    const context = commandStores(opts.store, { project, deferPromotions: true, now: opts.now }, cwd);
+    try {
+      context.binding.assertCurrent();
+      const boundPolicy = createHubMemorySyncPolicy(cwd, context.binding.home, project, context.binding.status(context.store));
+      const result = inspectDeclinedMemoryRows(context.store, { screen: (row, canonical) => {
+        const content = projectMemorySyncText(row, canonical);
+        const host = boundPolicy.policy.screen(content, true);
+        if (!host.ok) return host;
+        try { return opts.sync?.screen ? (opts.sync.screen(content) === true ? { ok: true } : { ok: false, rule: "caller sync policy" }) : { ok: true }; }
+        catch { return { ok: false, rule: "caller sync policy" }; }
+      } }, () => JSON.stringify([boundPolicy.version, opts.sync?.policyVersion?.() ?? null]));
+      context.binding.assertCurrent();
+      const profile = context.binding.status(context.store);
+      if (hostSyncPolicyInputs(cwd, context.binding.home, project, profile).version !== boundPolicy.version)
+        fail("memory declined policy changed during inspection; retry with stable privacy policy");
+      if (args.includes("--json")) return JSON.stringify({ rows: result.rows, complete: result.complete, ...(result.reason ? { reason: result.reason } : {}), memoryProfile: profile });
+      const text = result.complete
+        ? result.rows.length
+          ? [`${result.rows.length} declined physical outbound row${result.rows.length === 1 ? "" : "s"}:`, ...result.rows.map(row => `mem:${row.id} ${row.rule}`), "Review the source or approved policy, then run `ahub memory sync`. `forget` does not remove append-only physical rows."].join("\n")
+          : "no declined physical outbound rows; inspection complete"
+        : [`declined-row inspection incomplete: ${result.reason ?? "physical memory rows could not be inspected"}`, ...(result.rows.length ? [`${result.rows.length} declined row${result.rows.length === 1 ? "" : "s"} found before inspection stopped:`, ...result.rows.map(row => `mem:${row.id} ${row.rule}`)] : []), "No complete result is available; resolve the inspection issue before treating the list as empty."].join("\n");
+      return text;
+    } finally { if (context.owned) context.store.close(); }
+  }
   let showStale = false;
   const project = projectOf(cwd, opts.store);
+  let policyHome = opts.store?.profile.home ?? memoryHome();
   const context = commandStores(opts.store, { project, ttlMs: (loadConfigSafe(cwd)?.memory.short_ttl_days ?? 14) * 24 * 3600_000,
-    screen: promotionScreen(project, cwd, () => currentRouting(cwd), privatePaths) }, cwd);
+    screen: promotionScreen(project, cwd, () => currentRouting(cwd), privatePaths, task => memoryTaskPaths(cwd, project, project, task) ?? [], () => createHubMemorySyncPolicy(cwd, policyHome, project).policy) }, cwd);
+  policyHome = context.binding.home;
   try {
     context.binding.assertCurrent();
+    let boundSyncPolicy: ReturnType<typeof createHubMemorySyncPolicy> | undefined;
+    const syncPolicy = () => boundSyncPolicy ??= createHubMemorySyncPolicy(cwd, context.binding.home, project, context.binding.status(context.store));
     const text = await rawMemoryCommand(args, cwd, { ...opts, names: AHUB_NAMES, project, store: context.store, open: () => context.store,
+      sync: composeMemorySyncOptions({ screen: row => syncPolicy().policy.screen(row, true).ok,
+        policyVersion: () => { context.binding.assertCurrent(); return hostSyncPolicyInputs(cwd, context.binding.home, project, context.binding.status(context.store)).version; } }, opts.sync, true),
       readable: notes => {
       const paths = privatePaths(), visible = withoutPii(notes, currentRouting(cwd), cwd, paths);
       if (args[0] !== "show" || args.includes("--json")) return visible;

package/src/cli/output.ts

@@ -5,7 +5,7 @@ import { boardColumns, type BoardPeerInput } from "../ui/task-board.ts";
 import { peerStyle } from "../ui/peer-palette.ts";
 import { cells, TABLES, table, fitLine, wrap, duration, relative, plural, terminalText, initialConsoleState, stateTone, type Span, type Tone } from "./console-state.ts";
 import { taskProgress } from "../ui/task-progress.ts";
-import { backendLabel } from "./status-lines.ts";
+import { backendLabel, memorySyncLine, reviewInputHealthLine } from "./status-lines.ts";
 import { ownerIsolationText } from "./role-holders.ts";
 import { schedulePeriodText, scheduleWhen } from "../hub/schedules.ts";
 import { formatReport, formatTaskReport, type Report, type TaskReport } from "../hub/report.ts";
@@ -17,6 +17,8 @@ export interface StatusOutput {
   controlWriteTiming?: { active: number; slowRequests: number; blockedLoopSamples: number; droppedActive: number; droppedRecent: number; droppedLogs: number; droppedSpans?: number; droppedMetadata?: number; expiredRequests?: number };
   specs?: SpecsStatus & { missingBlockHint?: boolean };
   queueBackpressure?: QueueBackpressureStatus;
+  /** Unresolved failed delivery counts, absent when an older hub or storage cannot answer. */
+  deliveryFailures?: Record<string, number>;
   pendingRestart?: readonly { key: string; reason: string }[];
   retainedConfig?: readonly { key: string; reason: string }[];
   /** #572 AC3: advisory, present while the project root checkout is on a branch other than the default. */
@@ -29,12 +31,12 @@ export interface StatusOutput {
   pendingTaskOffers?: readonly { task: number; peer: string }[];
   isolatedChecks?: { pending?: number; orphans?: string[]; unknownReceipts?: readonly string[]; maintenanceUnavailable?: boolean };
   memoryRead?: { truncated: boolean; scanned: number; limit: number };
-  memoryProfile?: { profile?: string; generation?: string; state?: string; agentMemVersion?: string; skippedRows?: number; error?: string };
+  memoryProfile?: { profile?: string; generation?: string; state?: string; agentMemVersion?: string; skippedRows?: number; error?: string; sync?: { state: "disabled" | "unavailable" | "notrun" | "not-configured" | "stopped" | "ok" | "failed" | "unknown"; at?: number; cause?: string; declinedCount?: number; declinedIdsKnown?: false; withheldCount?: number; exportedCount?: number; placementActive?: false; nextStep?: string } };
   /** #784 AC3: `active`, `reviewWait` and `reserved` add up to `wip`; absent from an older hub. */
   taskWip?: Record<string, { wip: number; wipLimit: number; active?: number; reviewWait?: number; reserved?: number }>;
   pid?: number; controlPort?: number; cwd?: string; version?: string; peers: Record<string, any>; roleInfo?: Record<string, any>; actionPolicyInfo?: Record<string, { note: string; enforceable: boolean }>; budget?: Record<string, any>; planner?: { peers?: string[]; source?: string };
   ownerIsolation?: Record<string, boolean>; ownerIsolationNotes?: Record<string, string>;
-  tasks?: Record<string, number>; models?: { backends?: any[] }; permissionDefaults?: any[]; deliveryError?: string; crash?: string[];
+  tasks?: Record<string, number>; personRun?: number[]; models?: { backends?: any[] }; permissionDefaults?: any[]; deliveryError?: string; reviewInputHealth?: { state?: string; cause?: string | null }; crash?: string[];
 }
 /** `peers`: one note per peer that shows no number, and why (no quota, nothing read yet); absent from an older hub. */
 export interface BudgetOutput { budget: Record<string, any>; gate?: number; peers?: { peer: string; kind?: string; note: string }[] }
@@ -252,6 +254,8 @@ export function renderStatus(data: StatusOutput, columns?: number, now = Date.no
     const memory = data.memoryProfile;
     const profile = memory.profile === "generation" ? `generation ${memory.generation?.slice(0, 8) ?? "unknown"}` : memory.profile ?? "unbound";
     out.push(...detail("memory", `${profile}; ${memory.state ?? "unknown"}; agent-mem ${memory.agentMemVersion ?? "unknown"}${memory.skippedRows ? `; malformed legacy rows skipped: ${memory.skippedRows}` : ""}${memory.error ? `; ${memory.error}` : ""}`, columns, memory.state === "unavailable" ? "attention" : undefined));
+    const sync = memory.sync;
+    out.push(...detail("memory sync", memorySyncLine(sync ?? { state: "unknown" }), columns, sync?.state === "failed" ? "attention" : undefined));
   }
   if (data.memoryRead?.truncated) out.push(...detail("memory view", `truncated: newest ${data.memoryRead.limit} project candidates considered`, columns, "attention"));
   if (data.planner) out.push(...detail("planner", `${data.planner.peers?.join(", ") || "nobody"} (${data.planner.source ?? "unknown"})${data.planner.source === "automatic" || data.planner.source === "none" ? "; pin it with ahub settings set planner <peer>" : ""}`, columns, data.planner.source === "none" ? "attention" : undefined));
@@ -260,6 +264,13 @@ export function renderStatus(data: StatusOutput, columns?: number, now = Date.no
     if (text) out.push(...detail(`${id} owner isolation`, text, columns, isolated ? undefined : "attention"));
   }
   if (data.deliveryError) out.push(...detail("delivery storage", `${data.deliveryError}; dispatch is stopped`, columns, "failure"));
+  for (const [peer, count] of Object.entries(data.deliveryFailures ?? {})) {
+    if (Number.isSafeInteger(count) && count > 0) out.push(...detail(`${peer} failed deliveries`, `${count}; next: ahub queue discard --peer ${peer} --state failed`, columns, "attention"));
+  }
+  if (data.reviewInputHealth) {
+    const health = reviewInputHealthLine(data.reviewInputHealth);
+    if (health) out.push(...detail("review input provenance", health, columns, data.reviewInputHealth.state === "corrupt" ? "failure" : "attention"));
+  }
   for (const pending of data.permissionDefaults ?? []) out.push(...detail("permission default", `${pending.peer}: never-ask from ${pending.source}, stays ask until a person confirms in ahub console`, columns, "attention"));
   for (const crash of data.crash ?? []) out.push(...detail("crash recovery", crash, columns, "attention"));
   for (const warning of data.isolatedChecks?.orphans ?? []) out.push(...detail("isolated check warning", warning, columns, "attention"));
@@ -275,11 +286,18 @@ export function renderStatus(data: StatusOutput, columns?: number, now = Date.no
   let settling = false;
   const peerDetails = Object.entries(data.peers).map(([id, p]) => {
     const out: Span[][] = [];
+    for (const session of Array.isArray(p.standbySessions) ? p.standbySessions : []) {
+      if (!session || typeof session.id !== "string" || !/^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(session.id)) continue;
+      const pid = Number.isSafeInteger(session.pid) && session.pid > 0 ? String(session.pid) : "unknown";
+      const since = Number.isFinite(session.since) ? `; waiting ${relative(session.since, now)}` : "";
+      out.push(...detail(`${id} standby`, `pid ${pid}; session ${session.id}${since}; ahub peer takeover ${id} ${session.id}`, columns, "attention"));
+    }
     if (typeof p.form === "string") out.push(...detail(`${id} form`, p.form, columns));
     if (Array.isArray(p.capableRoles)) out.push(...detail(`${id} capable roles`, p.capableRoles.join(", ") || "none", columns));
     if (p.flowRoles) out.push(...detail(`${id} flow roles`, p.flowRoles.join(", ") || "none", columns));
     if (p.catalogRoles) { out.push(...detail(`${id} catalog roles`, Array.isArray(p.catalogRoles.value) ? p.catalogRoles.value.join(", ") || "none" : "unconfirmed", columns)); if (p.catalogRoles.pending !== undefined) out.push(...detail(`${id} pending roles`, p.catalogRoles.pending.join(", ") || "none", columns, "attention")); }
     if (p.liveAccepted?.length) { settling = true; out.push(...detail("settling", p.liveAccepted.map((v: string) => shortId(v, columns, full)).join(", "), columns, "attention")); }
+    if (typeof p.reviewObserverHoldNote === "string" && p.reviewObserverHoldNote) out.push(...detail(`${id} review input`, p.reviewObserverHoldNote, columns, "attention"));
     if (p.heldRows?.length) {
       for (const row of p.heldRows) out.push(...detail("held", `${id}: needs_review ${shortId(row.id, columns, full)}; from ${row.senders.join(",")}; kind ${row.kinds.join(",")}; age ${duration(Math.max(0, now - row.createdAt))}${row.context ? `; ${row.context}` : ""}; ahub queue show ${row.id}`, columns, "failure"));
     } else if (p.heldBy) {
@@ -297,6 +315,7 @@ export function renderStatus(data: StatusOutput, columns?: number, now = Date.no
         : flat(p.paused).replace(/^(budget: .*), resets .+$/, "$1; reset unknown");
       out.push(...detail("paused", pauseText, columns, "attention"));
     }
+    if (p.attachMode === "channel" || p.attachMode === "tools-only") out.push(...detail("attach", `${p.attachMode}; evidence: ${flat(p.attachEvidence ?? "unknown")}`, columns, p.attachMode === "channel" ? "muted" : "attention"));
     if (p.toolsOnly) out.push(...detail(definitionOf(id)?.attach?.pullOnlyForms?.includes("tui") && p.pullOnly ? "pull-only" : "tools-only", flat(p.toolsOnly).replace(/^(?:tools-only|pull-only):\s*/, ""), columns, "attention"));
     if (p.pullOnly && definitionOf(id)?.attach?.pullOnlyForms?.includes("tui")) out.push(...detail(`${id} last read`, typeof p.lastInboxAt === "number" ? relative(p.lastInboxAt, now) : "never", columns, "muted"));
     const actionPolicy = data.actionPolicyInfo?.[id];
@@ -322,6 +341,7 @@ export function renderStatus(data: StatusOutput, columns?: number, now = Date.no
   }
   const counts = Object.entries(data.tasks ?? {}).map(([state, count]) => `${count} ${state}`).join(", ");
   if (counts) out.push([], ...lines(`TASKS  ${counts} (ahub board)`, columns));
+  if (data.personRun?.length) out.push(...lines(`WAITING ON YOU  ${data.personRun.map(id => `#${id}`).join(", ")} (person-run: no agent is offered it; ahub backlog list)`, columns, "attention"));
   return out;
 }
 // #724: short next-step codes for the compact board, keyed on the blocker texts of src/hub/sdlc.ts; the full advice stays in --full and ahub task show.
@@ -345,7 +365,7 @@ export function renderBacklog(cards: any[], columns?: number, now = Date.now(),
   let table: OutputCell[][] = sorted.map(card => {
     const deps: number[] = Array.isArray(card.deps) ? card.deps : [];
     return [span(typeof card.rank === "number" ? card.rank : "-", "muted", true), span(`#${card.id}`, "info", true), span(typeof card.priority === "number" ? `P${card.priority}` : "-", undefined, true),
-      span(card.reserved ?? "-", peerTone(card.reserved ?? ""), true), span(deps.length ? (full || columns === undefined ? deps.map(id => `#${id}`).join(",") : `#${deps[0]}${deps.length > 1 ? `,+${deps.length - 1}` : ""}`) : "-", undefined, true), span(card.class ?? "-", undefined, true),
+      span(card.needsPerson === true ? `${card.reserved ?? ""}${card.reserved ? " " : ""}(person)` : card.reserved ?? "-", card.needsPerson === true ? "attention" : peerTone(card.reserved ?? ""), true), span(deps.length ? (full || columns === undefined ? deps.map(id => `#${id}`).join(",") : `#${deps[0]}${deps.length > 1 ? `,+${deps.length - 1}` : ""}`) : "-", undefined, true), span(card.class ?? "-", undefined, true),
       span(typeof card.created === "number" ? duration(now - card.created) : "-", "muted", true), span(flat(card.title))];
   });
   if (!full && columns !== undefined) {
@@ -357,8 +377,10 @@ export function renderBacklog(cards: any[], columns?: number, now = Date.now(),
     table = table.map(row => [...row.slice(0, -1), { ...row[row.length - 1]!, text: ellipsis(row[row.length - 1]!.text, titleRoom) }]);
   }
   const owners = new Map<string, number>();
-  for (const card of sorted) owners.set(card.reserved ?? "unreserved", (owners.get(card.reserved ?? "unreserved") ?? 0) + 1);
-  const summary = `${plural(sorted.length, "backlog card")}; reserved: ${[...owners].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0])).map(([owner, n]) => `${owner} ${n}`).join(", ")}`;
+  const person = sorted.filter(card => card.needsPerson === true);
+  for (const card of sorted.filter(card => card.needsPerson !== true)) owners.set(card.reserved ?? "unreserved", (owners.get(card.reserved ?? "unreserved") ?? 0) + 1);
+  const summary = `${plural(sorted.length, "backlog card")}; reserved: ${[...owners].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0])).map(([owner, n]) => `${owner} ${n}`).join(", ") || "none"}`
+    + (person.length ? `; waiting on you: ${person.map(card => `#${card.id}`).join(", ")} (a person-run leg; no agent is offered it)` : "");
   return [...rows(names, table, columns), [], ...lines(summary, columns)];
 }
 /** #724: one line per task. TITLE goes last and is cut to the room left; at a narrow width REVIEWER, CLASS and AGE give way first. */
@@ -545,6 +567,7 @@ function fields(value: unknown, columns: number | undefined, now: number, prefix
 }
 export function renderQueueShow(delivery: any, columns?: number, now = Date.now()): Span[][] {
   const out = [...lines("Delivery", columns, "strong"), ...fields(delivery, columns, now)];
+  if (delivery?.state === "failed" && delivery.failureCause === undefined) out.push(...detail("failure cause", "unknown (not recorded by this hub version)", columns, "muted"));
   if (delivery?.state === "needs_review" && delivery.id) out.push([], ...detail("resolve", `ahub queue resolve ${delivery.id} --action completed|retry|discard --reason <text>`, columns, "failure"));
   // #1096: a failed row that no one has settled can be cleared by the person or the conductor; one a resolution already settled says what is left (nothing).
   else if (delivery?.state === "failed" && delivery.id) {

package/src/cli/pet.ts

@@ -18,7 +18,7 @@ export function parseNeedsSummary(raw: unknown): NeedsSummary | undefined {
   if (row.first !== undefined) {
     if (!row.first || typeof row.first !== "object" || Array.isArray(row.first)) return;
     const item = row.first as Record<string, unknown>;
-    if (typeof item.kind !== "string" || typeof item.level !== "string" || !["approval", "default", "storage", "recovery", "delivery", "review", "budget", "offline"].includes(item.kind) || !["act", "watch"].includes(item.level)) return;
+    if (typeof item.kind !== "string" || typeof item.level !== "string" || !["approval", "default", "question", "storage", "recovery", "delivery", "review", "result", "budget", "offline"].includes(item.kind) || !["act", "watch"].includes(item.level)) return;
     if (item.peer !== undefined && !id(item.peer)) return;
     if (item.id !== undefined && !id(item.id) && !(count(item.id) && item.id > 0)) return;
     if (item.until !== undefined && !count(item.until) || item.since !== undefined && !count(item.since)) return;
@@ -29,8 +29,8 @@ export function parseNeedsSummary(raw: unknown): NeedsSummary | undefined {
   if ((row.act + row.watch > 0) !== !!first) return;
   if (row.act > 0 && first?.level !== "act" || row.act === 0 && first?.level === "act") return;
   if (row.act === 0 && ["waiting", "blocked", "review"].includes(row.state) || row.act > 0 && ["working", "idle", "sleeping"].includes(row.state)) return;
-  if (first?.level === "watch" && !["recovery", "budget", "offline"].includes(first.kind) || first?.level === "act" && ["budget", "offline"].includes(first.kind)) return;
-  if (row.state === "waiting" && !["approval", "default"].includes(first?.kind ?? "")) return;
+  if (first?.level === "watch" && !["recovery", "result", "budget", "offline"].includes(first.kind) || first?.level === "act" && ["budget", "offline"].includes(first.kind)) return;
+  if (row.state === "waiting" && !["approval", "default", "question"].includes(first?.kind ?? "")) return;
   if (row.state === "blocked" && !["storage", "recovery", "delivery"].includes(first?.kind ?? "")) return;
   if (row.state === "review" && first?.kind !== "review") return;
   return { act: row.act, watch: row.watch, state: row.state as NeedsSummary["state"], ...(first ? { first } : {}) };
@@ -57,7 +57,7 @@ export function petView(status: unknown, reader: PetRecoveryReader = recoveryRea
   const included = base && reported && typeof reported === "object" && (reported as Record<string, unknown>).operationId === operation && base.watch > 0 ? 1 : 0;
   const act = (base?.act ?? 0) + (active ? 0 : 1), watch = (base?.watch ?? 0) - included + (active ? 1 : 0);
   const first = base?.first;
-  const precedes = !active && (!first || first.level === "watch" || !["approval", "default", "storage"].includes(first.kind));
+  const precedes = !active && (!first || first.level === "watch" || !["approval", "default", "question", "storage"].includes(first.kind));
   const selected = precedes || first?.kind === "recovery" && first.id === operation ? item : first ?? item;
   const state = !active && base?.state !== "waiting" ? "blocked" : base?.state ?? "sleeping";
   return { summary: { act, watch, state, first: selected }, unavailable: !base, ...(runner === "unknown" ? { runnerUnknown: true } : {}) };

package/src/cli/results-args.ts

@@ -0,0 +1,30 @@
+/**
+ * #1054 T4: `ahub results [--unread] [--read <id> | --read-all | --unread-last]`. Pure: argv to one closed request, never a decision about whether it applies (the hub checks
+ * that a result exists and is unread). At most one action flag; `--unread` only narrows the list and takes no action.
+ */
+export const RESULT_ID = /^cmp-[a-f0-9]{12}$/;
+export type ResultsRequest = { action: "list"; unread: boolean } | { action: "read"; id: string } | { action: "read-all" } | { action: "unread-last" };
+export type ResultsArgs = { ok: true; value: ResultsRequest } | { ok: false; error: string };
+export const RESULTS_USAGE = "usage: ahub results [--unread] [--read <id> | --read-all | --unread-last] [--json] [--color=auto|always|never]";
+
+export function parseResultsArgs(args: readonly string[]): ResultsArgs {
+  const fail = (error: string): { ok: false; error: string } => ({ ok: false, error: `${RESULTS_USAGE}; ${error}` });
+  let unread = false;
+  const actions: ResultsRequest[] = [];
+  for (let index = 0; index < args.length; index++) {
+    const word = args[index]!;
+    if (word === "--unread") { unread = true; continue; }
+    if (word === "--read-all") { actions.push({ action: "read-all" }); continue; }
+    if (word === "--unread-last") { actions.push({ action: "unread-last" }); continue; }
+    if (word === "--read" || word.startsWith("--read=")) {
+      const id = word === "--read" ? args[++index] : word.slice("--read=".length);
+      if (id === undefined || !RESULT_ID.test(id)) return fail("--read needs a result id like cmp-0123456789ab (ahub results lists them)");
+      actions.push({ action: "read", id });
+      continue;
+    }
+    return fail(word.startsWith("--") ? `unknown flag ${word.split("=")[0]}` : `unexpected operand ${word.slice(0, 40)}`);
+  }
+  if (actions.length > 1) return fail("give one of --read, --read-all and --unread-last");
+  if (actions.length === 1) { if (unread) return fail("--unread only narrows the list; it does not combine with an action"); return { ok: true, value: actions[0]! }; }
+  return { ok: true, value: { action: "list", unread } };
+}