@staix/agent-hub 0.30.0 → 0.32.0

package/src/ui/plugin.ts

@@ -8,22 +8,27 @@
  *
  * Contract: @staix/agent-console api 1, declared structurally below so agent-hub keeps zero runtime dependencies.
  */
+import type { ActionMeta } from "@staix/agent-console/contract";
 import { createHash } from "node:crypto";
 import { join } from "node:path";
 import { Registry } from "../hub/registry.ts";
-import { projectConsole, type Lifecycle } from "../hub/manager.ts";
+import { projectConsole, type Lifecycle, type ManagerOptions } from "../hub/manager.ts";
 // lifecycle.ts reaches the whole daemon; it is imported only when a project is inspected, started or stopped.
 import { DASHBOARD_VIEWS, renderDashboard } from "../hub/ui.ts";
 import { officeModel, type OfficeScene } from "./office-model.ts";
+import { personEvidence, questionItem, QUESTION_ITEM, type InboxAnswers, type QuestionRowView } from "./plugin-questions.ts";
+import { canPublishResults, receiptEvidence, resultItem, RESULT_ACTIONS, RESULT_ITEM, type ResultAction, type ResultRowView } from "./plugin-results.ts";
 import { mergeSpaces, officeSpace } from "./office-space.ts";
 import { VERSION as version } from "../version.ts";
 
 type Tone = "ok" | "warn" | "err" | "neutral";
 interface InboxItem {
-  id: string; group: "decision" | "review" | "candidate" | "alert"; kind: string; title: string; detail?: string; actor?: string; project?: string;
+  id: string; group: "decision" | "review" | "result" | "candidate" | "alert"; kind: string; title: string; detail?: string; actor?: string; project?: string;
   at: string; chip?: { text: string; tone: Tone };
   verbs: { id: string; label: string; primary?: boolean; destructive?: boolean; reason?: "optional" | "required" }[];
   link: { panel: string; params?: Record<string, string> };
+  /** #1054: a `result` item carries the action acon runs once the person has seen it. */
+  seen?: { action: string };
 }
 type ActionResult =
   | ({ ok: true } & Record<string, unknown>)
@@ -32,7 +37,7 @@ type ActionResult =
 export interface ConsoleProvider {
   assets: { js: string; css?: string };
   snapshot(input: { after: number; panel: string } & Record<string, unknown>): Promise<Record<string, unknown>>;
-  action(input: { action: string; confirmed?: true; fingerprint?: string } & Record<string, unknown>): Promise<ActionResult>;
+  action(input: { action: string; confirmed?: true; fingerprint?: string } & Record<string, unknown>, meta?: ActionMeta): Promise<ActionResult>;
   close?(): Promise<void>;
 }
 export interface ConsolePlugin {
@@ -41,15 +46,20 @@ export interface ConsolePlugin {
     panels: { id: string; title: string; order?: number }[];
     capabilities?: { actions?: string[]; confirm?: boolean; multiProject?: boolean; inbox?: boolean; space?: boolean };
   };
-  open(ctx: { home: string; log(line: string): void }): Promise<ConsoleProvider>;
+  open(ctx: { home: string; log(line: string): void; features?: readonly string[] }): Promise<ConsoleProvider>;
 }
 
 const TITLES: Record<(typeof DASHBOARD_VIEWS)[number], string> = { board: "Board", office: "Office", stream: "Stream", agents: "Agents", message: "Message", memory: "Memory", settings: "Settings" };
 /** The dashboard's own actions plus the inbox verbs; the manager whitelist is still applied to each forwarded call. */
 const FORWARDED = ["start", "stop", "send", "pause", "resume", "permit", "propose", "intake", "assign", "backlog_pull", "backlog_return", "planning", "planning_undo", "planner_pull", "backlog_split", "release_new", "release_change", "setting", "setting_undo", "setting_preview", "setting_reload", "config_edit_preview", "config_edit_apply", "start_peer", "sdlc_queue", "sdlc_release", "worktree_override_set", "worktree_override_clear", "worktrees_refresh_prs"] as const;
+/** Advertised so acon lets the page send it, never forwarded: `action()` answers it through its own port (`answerVerb`), after the console's person meta is checked (#1053 T5). */
+const QUESTION_ACTIONS = ["answer"] as const;
+/** #1054 T6: the receipt actions, advertised so acon lets the inbox and the page send them, never forwarded: `action()` checks the console's person meta, then calls the dedicated `projectConsole(...).receipt` port (`receiptVerb`). */
+const RESULT_ADVERTISED = RESULT_ACTIONS;
+const REVIEW_ACTIONS = ["review_comment_put", "review_comment_delete", "review_comment_send"] as const;
 const INBOX_VERBS = ["approve", "deny", "open"] as const;
 /** Outward or destructive: answered needsConfirm first (agent-console AGENTS.md); previews are read-only and stay direct. */
-const CONFIRMED = new Set(["stop", "permit", "setting", "setting_undo", "setting_reload", "config_edit_apply", "start_peer", "backlog_split", "send", "approve", "deny", "worktree_override_set", "worktrees_refresh_prs"]);
+const CONFIRMED = new Set(["review_comment_delete", "review_comment_send", "stop", "permit", "setting", "setting_undo", "setting_reload", "config_edit_apply", "start_peer", "backlog_split", "send", "approve", "deny", "worktree_override_set", "worktrees_refresh_prs"]);
 const fingerprintOf = (input: Record<string, unknown>) => {
   const { confirmed: _c, fingerprint: _f, reason: _r, ...rest } = input;
   return createHash("sha256").update(JSON.stringify(Object.keys(rest).sort().map((key) => [key, rest[key]]))).digest("hex");
@@ -72,6 +82,7 @@ export function panelAssets(): { js: string; css: string } {
   body = swap(body, "let ticket = location.hash.slice(1);\nhistory.replaceState(null, '', location.pathname);", "let ticket = '';");
   body = swap(body, "const apply = () => { document.documentElement.dataset.theme = choice; };", "const apply = () => {};");
   body = swap(body, "const $ = (id) => $$(id);", "const $ = $$;");
+  body = swap(body, "const reviewKit = null;", "const reviewKit = typeof host.ui.review === 'function' ? {render:host.ui.review.bind(host.ui),snapshot:input=>host.snapshot(input)} : null;");
   // post() goes to the host: /projects is the manager listing, /snapshot and /action are the plugin's panel calls.
   body = swap(body, "async function post(path, body) {\n  const response = await fetch(path, {method:'POST', credentials:'same-origin', headers:{'Content-Type':'application/json'}, body:JSON.stringify(body)});\n  if (response.status === 401) { expire(); throw new Error('Run ahub ui to start a new session.'); }\n  const result = await response.json();",
     "async function post(path, body) {\n  const result = path === '/projects' ? await host.snapshot({ panel: 'board' }) : path === '/snapshot' ? await host.snapshot({ ...body, panel: 'board' }) : await host.action(body);\n  if (!result) { expire(); throw new Error('The console session ended.'); }\n  const response = { ok: result.ok !== false, status: 200 };");
@@ -135,6 +146,10 @@ ${body}
 }
 
 interface ProjectRow { id: string; root: string; state: string; instanceId: string | null }
+/** #727: the inbox reply is bounded; `more` counts what was left out. Most urgent first: a decision waits on the person, then a review, a result, a candidate, an alert. */
+const INBOX_MAX_ITEMS = 50;
+const INBOX_GROUP_RANK: Record<InboxItem["group"], number> = { decision: 0, review: 1, result: 2, candidate: 3, alert: 4 };
+interface InboxReply { items: InboxItem[]; more: number }
 
 /** lifecycle.ts reaches the whole daemon (and files acon's import scan cannot parse); load it on first use only. */
 function lazyLifecycle(): Lifecycle {
@@ -147,11 +162,11 @@ function lazyLifecycle(): Lifecycle {
 }
 
 /** Build the provider over an injectable registry and lifecycle (tests use a temp home and fakes). */
-export function createProvider(options: { home: string; registry?: Registry; lifecycle?: Lifecycle; log?: (line: string) => void; spaceBudgetMs?: number }): ConsoleProvider {
+export function createProvider(options: { home: string; registry?: Registry; lifecycle?: Lifecycle; log?: (line: string) => void; spaceBudgetMs?: number; features?: readonly string[]; forwardTimeoutMs?: ManagerOptions["forwardTimeoutMs"]; inboxFreshMs?: number; inboxStaleMs?: number; inboxProjectBudgetMs?: number }): ConsoleProvider {
   const registry = options.registry ?? new Registry(join(options.home, "registry.db"));
   const owned = !options.registry;
   const lifecycle = options.lifecycle ?? lazyLifecycle();
-  const { list, act } = projectConsole({ registry, lifecycle, home: options.home });
+  const { list, act, answer, receipt, consoleControl } = projectConsole({ registry, lifecycle, home: options.home, forwardTimeoutMs: options.forwardTimeoutMs });
   const assets = panelAssets();
   const seen = new Map<string, string>(); // inbox item id -> first-seen ISO time, so `at` stays stable
 
@@ -159,11 +174,57 @@ export function createProvider(options: { home: string; registry?: Registry; lif
     const listing = await list() as { projects: ProjectRow[] };
     return listing.projects.filter((p) => p.state === "running" && p.instanceId);
   }
-  async function inbox(): Promise<InboxItem[]> {
+  /**
+   * #730 r1200-m1: the project listing asks every daemon for its status, so a slow one holds it. `space()` and `inbox()` both bound it to `ms` and fall back to the last listing.
+   * One listing is in flight at a time and both callers join it, so a listing that hangs is asked once, not once per poll. A listing that finishes after its budget still becomes the fallback.
+   */
+  let lastRunning: ProjectRow[] = [];
+  let listingFlight: Promise<ProjectRow[]> | undefined;
+  function runningWithin(ms: number): Promise<ProjectRow[]> {
+    if (!listingFlight) {
+      const flight: Promise<ProjectRow[]> = running().then((rows) => { lastRunning = rows; return rows; }, () => lastRunning)
+        .finally(() => { if (listingFlight === flight) listingFlight = undefined; });
+      listingFlight = flight;
+    }
+    return within(listingFlight, ms).then((rows) => rows ?? lastRunning);
+  }
+  /**
+   * #727: one project's items from its last answer, reused for a project that did not answer in time, so a slow daemon neither blanks its rows nor restarts their `at`.
+   * Fenced by the action generation on both sides: an entry is written only by a computation that no action has overtaken, and read only in the generation it was written in, so an approval
+   * or an answer that has been given never comes back from here (a late project is then simply left out of that poll, which is the safe side).
+   */
+  const lastProjectItems = new Map<string, { generation: number; items: InboxItem[] }>();
+  /**
+   * #730 r1200-m2: a project's `agents` snapshot in flight. `within()` stops waiting at the budget but the snapshot keeps running, so the next refresh joins it while it is pending instead of asking the
+   * same slow project again (one question per slow project, not one per poll). Joined only in the generation it started in, so an answer that began before an action never serves a poll after it.
+   */
+  const projectFlights = new Map<string, { generation: number; instanceId: string | null; promise: Promise<Record<string, unknown> | null> }>();
+  /** The project's `agents` snapshot, or null when it did not answer within the budget or threw: the other projects' rows are never held back by it. */
+  const projectSnapshot = (project: ProjectRow) => {
+    let flight = projectFlights.get(project.id);
+    if (!flight || flight.generation !== inboxGeneration || flight.instanceId !== project.instanceId) {
+      const promise: Promise<Record<string, unknown> | null> = Promise.resolve(act({ action: "snapshot", after: 0, projectId: project.id, instanceId: project.instanceId, view: "agents" }) as Promise<Record<string, unknown>>)
+        .then((snap) => snap, () => null)
+        .finally(() => { if (projectFlights.get(project.id)?.promise === promise) projectFlights.delete(project.id); });
+      flight = { generation: inboxGeneration, instanceId: project.instanceId, promise };
+      projectFlights.set(project.id, flight);
+    }
+    return within(flight.promise, INBOX_PROJECT_BUDGET_MS);
+  };
+  async function inbox(generation: number): Promise<InboxItem[]> {
     const items: InboxItem[] = [];
-    for (const project of await running()) {
-      const snap = await act({ action: "snapshot", after: 0, projectId: project.id, instanceId: project.instanceId, view: "agents" }) as Record<string, unknown>;
-      if (snap.ok === false) continue;
+    const projects = await runningWithin(Math.round(INBOX_PROJECT_BUDGET_MS / 2));
+    // The projects are asked at once: the answer takes as long as the slowest daemon, not the sum of them (#727).
+    const snaps = await Promise.all(projects.map(projectSnapshot));
+    for (const [index, project] of projects.entries()) {
+      const snap = snaps[index];
+      if (snap === null || snap === undefined) {
+        const last = lastProjectItems.get(project.id);
+        if (last && last.generation === inboxGeneration) items.push(...last.items);
+        continue;
+      }
+      if (snap.ok === false) { lastProjectItems.delete(project.id); continue; }
+      const firstItem = items.length;
       const name = project.root.split("/").filter(Boolean).pop() ?? project.id;
       for (const p of (snap.permissions as { id: string; peer: string; title: string; createdAt?: number; terminalOnly?: boolean; options: { optionId: string; kind: string; name: string }[] }[] | undefined) ?? []) {
         const id = `perm:${project.id}:${p.id}`;
@@ -176,6 +237,24 @@ export function createProvider(options: { home: string; registry?: Registry; lif
           verbs: [...(allow ? [{ id: "approve", label: "Allow once", primary: true }] : []), ...(deny ? [{ id: "deny", label: "Deny", destructive: true }] : [])],
           link: { panel: "agents", params: { project: project.id } } });
       }
+      // #1053 T5: the open questions peers asked the person. A private question's title is a stub; the form (the person's own answer surface) carries the text.
+      for (const q of (snap.questions as QuestionRowView[] | undefined) ?? []) {
+        if (!q || typeof q.set !== "string" || !Array.isArray(q.questions) || !q.questions.length) continue;
+        const item = questionItem(q, { id: project.id, name }, options.features);
+        seen.set(item.id, item.at);
+        items.push(item);
+      }
+      // #1054 T6: unread results, only to a console that renders the `result` group AND gives a receipt person evidence. Otherwise they stay in the ahub panel, `ahub console`, `ahub status`
+      // and `ahub results`. A row that is not well formed is dropped, never rendered; the detail is what the hub built at display (a stub when private).
+      if (canPublishResults(options.features)) {
+        const results = (snap.results as { unread?: ResultRowView[] } | undefined)?.unread;
+        for (const row of Array.isArray(results) ? results : []) {
+          if (!row || typeof row.id !== "string" || !/^cmp-[a-f0-9]{12}$/.test(row.id) || typeof row.peer !== "string" || !Number.isSafeInteger(row.settledAt)) continue;
+          const item = resultItem(row, { id: project.id, name });
+          seen.set(item.id, item.at);
+          items.push(item);
+        }
+      }
       // #1057 D4: one alert when the shelf holds more settled worktrees than `worktrees.alert_over` (0 = never). Counts only: no path, branch or title, and no action
       // beyond opening the panel, because removal is the person's `ahub worktrees tidy` and never a button.
       const shelf = snap.worktrees as { settled?: unknown[]; alertOver?: number } | undefined;
@@ -195,13 +274,46 @@ export function createProvider(options: { home: string; registry?: Registry; lif
         items.push({ id, group: "review", kind: "review", title: `#${t.id} ${t.title}`.slice(0, 200), ...(t.owner ? { actor: t.owner } : {}), project: name, at,
           chip: { text: "review", tone: "neutral" }, verbs: [{ id: "open", label: "Open board", primary: true }], link: { panel: "board", params: { project: project.id } } });
       }
+      if (generation === inboxGeneration) lastProjectItems.set(project.id, { generation, items: items.slice(firstItem) });
     }
-    // Forget ids that left the inbox, so `seen` stays the size of what is waiting now.
+    for (const id of lastProjectItems.keys()) if (!projects.some((project) => project.id === id)) lastProjectItems.delete(id);
+    // Forget ids that left the inbox, so `seen` stays the size of what is waiting now. This runs on the whole list, before the cap, so a row below the cap keeps its `at`.
     const current = new Set(items.map((item) => item.id));
     for (const id of seen.keys()) if (!current.has(id)) seen.delete(id);
     return items;
   }
 
+  /**
+   * #727: what acon polls. The expensive part (every running project's `agents` snapshot) is shared and cached:
+   *  - concurrent snapshots join one computation in flight;
+   *  - a result younger than `inboxFreshMs` is served as it is;
+   *  - a result younger than `inboxStaleMs` is served at once while one refresh runs in the background (nothing runs while nobody polls);
+   *  - older, or after any action (an approval or an answer changes what is waiting), the caller waits for a fresh computation.
+   * The reply is bounded: at most INBOX_MAX_ITEMS items, the most urgent first, and `more` says how many were left out.
+   */
+  const INBOX_FRESH_MS = options.inboxFreshMs ?? 1_000, INBOX_STALE_MS = options.inboxStaleMs ?? 10_000, INBOX_PROJECT_BUDGET_MS = options.inboxProjectBudgetMs ?? 2_000;
+  let inboxGeneration = 0, inboxCache: { generation: number; at: number; value: InboxReply } | undefined, inboxFlight: { generation: number; promise: Promise<InboxReply> } | undefined;
+  function inboxComputation(): Promise<InboxReply> {
+    if (inboxFlight && inboxFlight.generation === inboxGeneration) return inboxFlight.promise;
+    const generation = inboxGeneration;
+    const promise: Promise<InboxReply> = inbox(generation).then((all) => {
+      const ordered = [...all].sort((a, b) => INBOX_GROUP_RANK[a.group] - INBOX_GROUP_RANK[b.group] || (a.at < b.at ? -1 : a.at > b.at ? 1 : 0) || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+      const value: InboxReply = { items: ordered.slice(0, INBOX_MAX_ITEMS), more: Math.max(0, ordered.length - INBOX_MAX_ITEMS) };
+      if (!inboxCache || inboxCache.generation <= generation) inboxCache = { generation, at: Date.now(), value };
+      return value;
+    }).finally(() => { if (inboxFlight?.promise === promise) inboxFlight = undefined; });
+    inboxFlight = { generation, promise };
+    return promise;
+  }
+  async function inboxSnapshot(): Promise<InboxReply> {
+    if (inboxCache && inboxCache.generation === inboxGeneration) {
+      const age = Date.now() - inboxCache.at;
+      if (age < INBOX_FRESH_MS) return inboxCache.value;
+      if (age < INBOX_STALE_MS) { void inboxComputation().catch(() => {}); return inboxCache.value; }
+    }
+    return await inboxComputation();
+  }
+
   /**
    * #1012 Part 2: every running project's office as one acon SpaceScene. The office model is kept per project as
    * `previous`, as the dashboard keeps it, so desk slots and message arcs persist across polls. A restarted daemon
@@ -218,11 +330,8 @@ export function createProvider(options: { home: string; registry?: Registry; lif
     const late = new Promise<null>((resolve) => { timer = setTimeout(() => resolve(null), ms); });
     try { return await Promise.race([work, late]); } catch { return null; } finally { clearTimeout(timer); }
   };
-  let lastRunning: ProjectRow[] = [];
   async function space() {
-    // A listing that finishes after its budget still becomes the fallback for the next poll.
-    const listing = running().then((rows) => { lastRunning = rows; return rows; }, () => lastRunning);
-    const projects = await within(listing, Math.round(SPACE_BUDGET_MS / 2)) ?? lastRunning;
+    const projects = await runningWithin(Math.round(SPACE_BUDGET_MS / 2));
     for (const id of offices.keys()) if (!projects.some((p) => p.id === id)) offices.delete(id);
     const scenes = [];
     const snaps = await Promise.all(projects.map((project) =>
@@ -239,10 +348,45 @@ export function createProvider(options: { home: string; registry?: Registry; lif
     return mergeSpaces(scenes);
   }
 
+  /**
+   * #1053 T5: an answer to a question item. Only with the console's own person meta (checked by the caller); the project and set come from the item id, never from the
+   * page. The hub re-validates every answer against the stored row and names a stale or superseded set's terminal state.
+   */
+  async function answerVerb(input: Record<string, unknown>, person: string): Promise<ActionResult> {
+    const m = typeof input.id === "string" ? QUESTION_ITEM.exec(input.id) : null;
+    if (!m) return { ok: false, error: "unknown inbox item" };
+    const project = (await running()).find((p) => p.id === m[1]);
+    if (!project) return { ok: false, error: "project is not running" };
+    const result = await answer({ projectId: project.id, instanceId: project.instanceId }, { questionSet: m[2]!, answers: input.answers as InboxAnswers, person }) as Record<string, unknown>;
+    return result.ok === true ? { ok: true, message: "Answered" } : { ok: false, error: String(result.error ?? "the answer was refused") };
+  }
+
+  /**
+   * #1054 T6: a receipt for the person: one result read (the inbox's `result_seen`, whose item id names the project and the completion; the panel's carries the same ids), all read, or the
+   * last read unread again. Only with the console's own person meta (checked by the caller). The project comes from the item id or, from the panel, from the project it is showing; the
+   * hub re-checks that the result exists and is unread, and names a stale one. `seenAt` and `explicit` are acon's and are not forwarded: the hub stamps its own time.
+   */
+  async function receiptVerb(name: ResultAction, input: Record<string, unknown>): Promise<ActionResult> {
+    let projectId: string | undefined, id: string | undefined;
+    if (name === "result_seen") {
+      const m = typeof input.id === "string" ? RESULT_ITEM.exec(input.id) : null;
+      if (m) { projectId = m[1]; id = m[2]; }
+      else if (typeof input.projectId === "string" && typeof input.id === "string" && /^cmp-[a-f0-9]{12}$/.test(input.id)) { projectId = input.projectId; id = input.id; }
+      if (!projectId || !id) return { ok: false, error: "unknown result" };
+    } else projectId = typeof input.projectId === "string" ? input.projectId : undefined;
+    const project = (await running()).find((p) => p.id === projectId);
+    if (!project) return { ok: false, error: "project is not running" };
+    const target = { projectId: project.id, instanceId: project.instanceId };
+    const result = (name === "result_seen" ? await receipt(target, { op: "result_seen", id: id! })
+      : await receipt(target, { op: "results", action: name === "results_read_all" ? "read-all" : "unread-last" })) as Record<string, unknown>;
+    if (result.ok !== true) return { ok: false, error: String(result.error ?? "the receipt was refused") };
+    return { ok: true, message: name === "result_seen" ? "Marked read" : name === "results_read_all" ? `Marked ${Number(result.marked) || 0} read` : "Marked unread again" };
+  }
+
   /** approve/deny resolve to the hub's own `permit` with the request's option; nothing else is reachable from an item. */
   async function inboxVerb(input: Record<string, unknown>): Promise<ActionResult> {
     const m = typeof input.id === "string" ? /^perm:([^:]+):(.+)$/.exec(input.id) : null;
-    if (input.action === "open") return { ok: true, message: typeof input.id === "string" && input.id.startsWith("worktrees:") ? "Open the Agents panel to review the shelf." : "Open the Board panel to review." };
+    if (input.action === "open") return { ok: true, message: typeof input.id === "string" && (input.id.startsWith("worktrees:") || input.id.startsWith("question:") || input.id.startsWith("result:")) ? `Open the Agents panel to ${input.id.startsWith("question:") ? "answer" : input.id.startsWith("result:") ? "read the result" : "review the shelf"}.` : "Open the Board panel to review." };
     if (!m) return { ok: false, error: "unknown inbox item" };
     const project = (await running()).find((p) => p.id === m[1]);
     if (!project) return { ok: false, error: "project is not running" };
@@ -260,7 +404,11 @@ export function createProvider(options: { home: string; registry?: Registry; lif
   return {
     assets,
     async snapshot(input) {
-      if (input.panel === "inbox") return { items: await inbox() };
+      if (input.panel === "review_blob" || input.panel === "review_comments") {
+        const { panel: _panel, projectId, instanceId, ...payload } = input;
+        return await consoleControl({ projectId, instanceId }, input.panel, payload);
+      }
+      if (input.panel === "inbox") return { ...await inboxSnapshot() };
       if (input.panel === "space") return { scene: await space() };
       const view = (DASHBOARD_VIEWS as readonly string[]).includes(String(input.view)) ? input.view : (DASHBOARD_VIEWS as readonly string[]).includes(input.panel) ? input.panel : undefined;
       if (typeof input.projectId !== "string" || typeof input.instanceId !== "string") {
@@ -271,34 +419,66 @@ export function createProvider(options: { home: string; registry?: Registry; lif
         return { ...listing, ...(live.length === 1 ? { selectedProjectId: live[0]!.id } : {}), panel: input.panel };
       }
       const { panel: _panel, ...rest } = input;
-      return await act({ ...rest, action: "snapshot", ...(view ? { view } : {}) }) as Record<string, unknown>;
+      return { ...await act({ ...rest, action: "snapshot", ...(view ? { view } : {}) }) as Record<string, unknown>, reviewWritable: options.features?.includes("action.meta") === true };
+    },
+    async action(input, meta) {
+      // #727: an action changes what is waiting, so the cached inbox is dropped before it runs and again when it ends (a poll in between must not keep the old answer).
+      inboxGeneration++;
+      try { return await runAction(input, meta); } finally { inboxGeneration++; }
     },
-    async action(input) {
+    async close() { if (owned) registry.close(); },
+  };
+
+    async function runAction(input: Parameters<ConsoleProvider["action"]>[0], meta: ActionMeta | undefined): Promise<ActionResult> {
       const name = String(input.action);
-      if (![...FORWARDED, ...INBOX_VERBS].includes(name as never)) return { ok: false, error: "unknown action" };
+      // #1053 T5: `answer` is accepted only with the console's own verified person meta, and never with page-supplied identity or target fields; anything else is refused before the hub.
+      if (name === "answer") {
+        const evidence = personEvidence(options.features, meta, input);
+        if (!evidence.ok) return { ok: false, error: evidence.error };
+        const { action: _a, confirmed: _c, fingerprint: _f, ...forward } = input;
+        return await answerVerb(forward, evidence.identity);
+      }
+      // #1054 T6: a receipt is accepted only with the console's own verified person meta, and never with page-supplied identity or target fields; anything else is refused before the hub.
+      if ((RESULT_ACTIONS as readonly string[]).includes(name)) {
+        const evidence = receiptEvidence(options.features, meta, input);
+        if (!evidence.ok) return { ok: false, error: evidence.error };
+        const { action: _a, confirmed: _c, fingerprint: _f, seenAt: _s, explicit: _e, ...forward } = input;
+        return await receiptVerb(name as ResultAction, forward);
+      }
+      const review = REVIEW_ACTIONS.includes(name as typeof REVIEW_ACTIONS[number]);
+      if (review && (!options.features?.includes("action.meta") || !meta || meta.via !== "console" || typeof meta.identity !== "string" || !meta.identity.trim() || typeof meta.node !== "string" || !meta.node.trim())) {
+        return { ok: false, error: "Review comments need a console with verified person identity; update acon and reopen this panel." };
+      }
+      if (review && ["author", "meta", "personMeta", "at", "state", "sentAt"].some(key => Object.hasOwn(input, key))) {
+        return { ok: false, error: "Review identity and timestamps are supplied by the console; remove those fields and retry." };
+      }
+      if (![...FORWARDED, ...INBOX_VERBS, ...REVIEW_ACTIONS].includes(name as never)) return { ok: false, error: "unknown action" };
       const fingerprint = fingerprintOf(input);
       if (CONFIRMED.has(name) && !(input.confirmed === true && input.fingerprint === fingerprint)) {
         const target = typeof input.projectId === "string" ? registry.get(input.projectId)?.root.split("/").filter(Boolean).pop() : undefined;
-        const preview = name === "approve" || name === "deny" ? [`${name === "approve" ? "Allow" : "Deny"} this tool request once.`]
+        const preview = name === "review_comment_delete" ? [`Delete or dismiss this review comment on task #${String(input.task ?? "?")}.`]
+          : name === "approve" || name === "deny" ? [`${name === "approve" ? "Allow" : "Deny"} this tool request once.`]
           : name === "send" ? [`Send a message as you${target ? ` in ${target}` : ""}.`]
           : [`Run ${name}${target ? ` in ${target}` : ""}.`];
         return { ok: false, needsConfirm: true, preview, fingerprint, verb: name === "approve" ? "Allow once" : name === "deny" ? "Deny" : name };
       }
+      if (review) {
+        const { action: _action, confirmed: _confirmed, fingerprint: _fingerprint, projectId, instanceId, ...payload } = input;
+        return await consoleControl({ projectId, instanceId }, name as typeof REVIEW_ACTIONS[number], payload, meta) as ActionResult;
+      }
       const { confirmed: _c, fingerprint: _f, ...forward } = input;
       if (name === "approve" || name === "deny" || name === "open") return await inboxVerb(forward);
       const result = await act(forward) as Record<string, unknown>;
       return (result.ok === false ? { ok: false, error: String(result.error ?? "action failed"), ...(result.unconfirmed === true ? { unconfirmed: true as const } : {}) } : { ...result, ok: true }) as ActionResult;
-    },
-    async close() { if (owned) registry.close(); },
-  };
+    }
 }
 
 const plugin: ConsolePlugin = {
   manifest: {
     api: 1, tool: "ahub", version, title: "agent-hub", icon: "agents", pollMs: 2000,
     panels: DASHBOARD_VIEWS.map((id, order) => ({ id, title: TITLES[id], order })),
-    capabilities: { actions: [...FORWARDED, ...INBOX_VERBS], confirm: true, multiProject: true, inbox: true, space: true },
+    capabilities: { actions: [...FORWARDED, ...INBOX_VERBS, ...QUESTION_ACTIONS, ...RESULT_ADVERTISED, ...REVIEW_ACTIONS], confirm: true, multiProject: true, inbox: true, space: true },
   },
-  async open(ctx) { return createProvider({ home: ctx.home, log: ctx.log }); },
+  async open(ctx) { return createProvider({ home: ctx.home, log: ctx.log, features: ctx.features }); },
 };
 export default plugin;

package/src/pet/window.html

@@ -1,114 +0,0 @@
-<!doctype html>
-<html lang="en">
-<meta charset="utf-8">
-<meta name="viewport" content="width=device-width, initial-scale=1">
-<meta http-equiv="Content-Security-Policy" content="default-src 'none'; script-src 'unsafe-inline'; style-src 'unsafe-inline'; connect-src 'none'; base-uri 'none'; form-action 'none'">
-<title>agent-hub pet</title>
-<style>
-:root { color-scheme: dark; font: 12px system-ui, sans-serif; color: #eceef3; }
-html, body { margin: 0; background: transparent; overflow: hidden; }
-body { width: 150px; height: 150px; display: flex; align-items: center; flex-direction: column; justify-content: flex-end; gap: 4px; padding-bottom: 4px; box-sizing: border-box; }
-button { font: inherit; color: inherit; cursor: pointer; border: 0; background: transparent; border-radius: 10px; }
-button:focus-visible, input:focus-visible { outline: 2px solid #79dfb2; outline-offset: 2px; }
-#pet { width: 63px; height: 58px; padding: 0; cursor: grab; touch-action: none; }
-#pet:active { cursor: grabbing; }
-svg { width: 100%; height: 100%; overflow: visible; image-rendering: pixelated; filter: drop-shadow(0 1px 1px #687a78) drop-shadow(0 0 1px #687a78); }
-[data-palette="blue"] svg { filter: drop-shadow(0 1px 1px #64748b) drop-shadow(0 0 1px #64748b); }
-[data-palette="violet"] svg { filter: drop-shadow(0 1px 1px #796d8b) drop-shadow(0 0 1px #796d8b); }
-[data-palette="ochre"] svg { filter: drop-shadow(0 1px 1px #81725f) drop-shadow(0 0 1px #81725f); }
-rect { fill: #168b87; }
-[data-palette="blue"] rect { fill: #3979d6; }
-[data-palette="violet"] rect { fill: #8864cc; }
-[data-palette="ochre"] rect { fill: #be7a22; }
-[data-state="waiting"] rect { fill: #c4880f; }
-[data-state="blocked"] rect { fill: #cf6156; }
-[data-state="review"] rect { fill: #8a6cd8; }
-[data-state="offline"] rect { fill: #6f7787; }
-body[data-state="working"] #frame { animation: working-bob 0.7s steps(3, end) infinite; }
-@keyframes working-bob {
-  0%, 100% { transform: translateY(0); }
-  50% { transform: translateY(-4px); }
-}
-@media (prefers-reduced-motion: reduce) {
-  body[data-state="working"] #frame { animation: none; }
-}
-#pill { display: flex; align-items: center; gap: 4px; border-radius: 14px; padding: 3px 7px; background: #242936ed; font-size: 11px; }
-#pill button { padding: 2px 4px; }
-#composer { width: 100%; background: #242936f5; padding: 4px; border-radius: 10px; box-sizing: border-box; }
-#composer[hidden] { display: none; }
-/* Hidden by opacity only: visibility would drop the #state live region from the a11y tree. */
-#pill { opacity: 0; pointer-events: none; transition: opacity .12s ease; }
-#pet:hover ~ #pill, #pet:focus-visible ~ #pill, #pill:hover, #pill:focus-within, body[data-hover] #pill, body[data-composing] #pill { opacity: 1; pointer-events: auto; }
-input { width: 100%; box-sizing: border-box; border: 1px solid #657081; border-radius: 6px; padding: 5px; background: #111722; color: #eceef3; font: 13px system-ui; }
-#result { margin-top: 2px; min-height: 12px; font-size: 11px; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
-</style>
-<button id="pet" aria-label="Open agent-hub dashboard"><svg id="frame" role="img" aria-label="Pet" viewBox="0 0 60 64"></svg></button>
-<div id="pill"><span id="state" aria-live="polite">Starting</span><button id="pencil" aria-label="Write a console message">✎</button><button id="close" aria-label="Close pet window">×</button></div>
-<div id="composer" hidden><input id="message" aria-label="Console message" placeholder="Message, Enter to send" maxlength="65536"><div id="result" role="status">Esc to cancel</div></div>
-<script>
-const post = body => window.webkit.messageHandlers.pet.postMessage(body);
-const pet = document.getElementById('pet'), frame = document.getElementById('frame'), pill = document.getElementById('pill');
-const state = document.getElementById('state'), composer = document.getElementById('composer'), input = document.getElementById('message'), result = document.getElementById('result');
-let signature = '', drag, sending = false;
-const draw = (x, y, w, h) => {
-  const rect = document.createElementNS('http://www.w3.org/2000/svg', 'rect');
-  rect.setAttribute('x', x); rect.setAttribute('y', y); rect.setAttribute('width', w); rect.setAttribute('height', h);
-  return rect;
-};
-window.update = view => {
-  if (view.offline) {
-    document.body.dataset.state = 'offline'; state.textContent = 'Offline';
-    document.getElementById('pencil').disabled = true; return;
-  }
-  document.getElementById('pencil').disabled = false;
-  document.body.dataset.state = view.state;
-  document.body.dataset.palette = view.palette;
-  state.textContent = view.state + (view.act ? ' · act ' + view.act : '') + (view.watch ? ' · watch ' + view.watch : '');
-  pet.setAttribute('aria-label', 'Open dashboard, ' + state.textContent);
-  const next = JSON.stringify(view.frame);
-  if (signature === next) return;
-  signature = next;
-  frame.setAttribute('viewBox', '0 0 ' + view.frame.width + ' ' + view.frame.height);
-  frame.replaceChildren(...view.frame.pixels.map(([x, y]) => draw(x, y, 1, 1)));
-};
-window.focusInput = () => { document.body.dataset.composing = ''; composer.hidden = false; input.focus(); };
-window.commandResult = ok => { sending = false; input.disabled = false; result.textContent = ok ? 'Sent' : 'Not confirmed; check the dashboard.'; if (ok) { input.value = ''; composer.hidden = true; delete document.body.dataset.composing; } };
-document.getElementById('pencil').addEventListener('click', () => post({ kind: 'pencil' }));
-document.getElementById('close').addEventListener('click', () => post({ kind: 'close' }));
-input.addEventListener('keydown', event => {
-  if (event.key === 'Escape') { composer.hidden = true; delete document.body.dataset.composing; pet.focus(); }
-  if (event.key === 'Enter' && !event.isComposing && input.value.trim() && !sending) {
-    event.preventDefault(); sending = true; input.disabled = true; result.textContent = 'Sending'; post({ kind: 'send', text: input.value });
-  }
-});
-// The native host polls the global mouse position against this rect (pet + pill) and
-// calls hoverChanged, because an inactive accessory panel never fires CSS :hover.
-window.hoverChanged = on => { if (on) document.body.dataset.hover = ''; else delete document.body.dataset.hover; };
-const postHotspot = () => {
-  const a = pet.getBoundingClientRect(), b = pill.getBoundingClientRect();
-  const x = Math.min(a.x, b.x), y = Math.min(a.y, b.y);
-  post({ kind: 'hotspot', x, y, w: Math.max(a.right, b.right) - x, h: Math.max(a.bottom, b.bottom) - y });
-};
-// While the panel is key, 1/2/3/4 switch the palette (blue/teal/violet/ochre) and save it.
-const KEY_PALETTES = { '1': 'blue', '2': 'teal', '3': 'violet', '4': 'ochre' };
-document.addEventListener('keydown', event => {
-  const palette = KEY_PALETTES[event.key];
-  if (!palette || event.target === input) return;
-  document.body.dataset.palette = palette;
-  post({ kind: 'palette', palette });
-});
-pet.addEventListener('pointerdown', event => { drag = { x: event.screenX, y: event.screenY, moved: false }; pet.setPointerCapture(event.pointerId); });
-pet.addEventListener('pointermove', event => {
-  if (!drag) return;
-  const dx = event.screenX - drag.x, dy = event.screenY - drag.y;
-  if (!dx && !dy) return;
-  drag.moved = true; drag.x = event.screenX; drag.y = event.screenY;
-  post({ kind: 'drag', dx, dy });
-});
-pet.addEventListener('pointerup', () => { const moved = drag?.moved; drag = null; if (!moved) post({ kind: 'open' }); });
-pet.addEventListener('pointercancel', () => { drag = null; });
-pet.addEventListener('keydown', event => { if (event.key === 'Enter' || event.key === ' ') { event.preventDefault(); post({ kind: 'open' }); } });
-postHotspot();
-post({ kind: 'ready' });
-</script>
-</html>

package/src/pet/window.jxa.js

@@ -1,122 +0,0 @@
-// Local AppKit/WebKit surface. No shell evaluation or remote content.
-ObjC.import('Cocoa');
-ObjC.import('WebKit');
-var panel, web, app, viewPath, positionPath, readyPath, cliArgv, timer, hoverTimer, bridge;
-var offlineAt = 0, commands = [], exiting = false, hotspot = null, hovering = false;
-function ignoreCompletion(result, error) {}
-function evaluate(source) { web.evaluateJavaScriptCompletionHandler(source, ignoreCompletion); }
-// An inactive accessory panel receives no mouse-moved events, so hover reveal is
-// polled from the global mouse position against the hotspot rect the page posts.
-function pollHover() {
-  if (!hotspot || exiting) return;
-  var mouse = $.NSEvent.mouseLocation, frame = panel.frame;
-  var x = mouse.x - frame.origin.x, y = frame.origin.y + frame.size.height - mouse.y;
-  var inside = x >= hotspot.x && x <= hotspot.x + hotspot.w && y >= hotspot.y && y <= hotspot.y + hotspot.h;
-  if (inside !== hovering) { hovering = inside; evaluate('hoverChanged(' + inside + ')'); }
-}
-function savePosition() {
-  var origin = panel.frame.origin;
-  $(JSON.stringify({ x: origin.x, y: origin.y })).writeToFileAtomicallyEncodingError(positionPath, true, $.NSUTF8StringEncoding, null);
-}
-function quit() { exiting = true; savePosition(); app.terminate(null); }
-function runCommand(command, extra, argv) {
-  if (exiting || commands.length >= 8) return;
-  var task = $.NSTask.alloc.init;
-  task.executableURL = $.NSURL.fileURLWithPath(argv[0]);
-  var args = argv.slice(1).concat([command]).concat(extra);
-  task.arguments = $(args); // argv array only; message text is a single argument.
-  task.standardInput = $.NSFileHandle.fileHandleWithNullDevice;
-  task.standardOutput = $.NSFileHandle.fileHandleWithNullDevice;
-  task.standardError = $.NSFileHandle.fileHandleWithNullDevice;
-  if (task.launchAndReturnError(null)) commands.push({ task: task, command: command });
-  else evaluate('commandResult(false)');
-}
-ObjC.registerSubclass({ name: 'AhubPetPanel', superclass: 'NSPanel', methods: {
-  canBecomeKeyWindow: { types: ['bool', []], implementation: function() { return true; } },
-  canBecomeMainWindow: { types: ['bool', []], implementation: function() { return false; } }
-} });
-// JXA cannot resolve WKScriptMessageHandler by name on some macOS versions;
-// WebKit invokes the exact Objective-C selector on this retained subclass.
-ObjC.registerSubclass({ name: 'AhubPetBridge', superclass: 'NSObject', methods: {
-  'userContentController:didReceiveScriptMessage:': { types: ['void', ['id', 'id']], implementation: function(controller, message) {
-    var body = ObjC.deepUnwrap(message.body);
-    if (!body || typeof body !== 'object' || exiting) return;
-    if (body.kind === 'ready') {
-      tick();
-      $('ready').writeToFileAtomicallyEncodingError(readyPath, true, $.NSUTF8StringEncoding, null);
-    } else if (body.kind === 'pencil') {
-      panel.orderFrontRegardless; panel.makeKeyWindow;
-      evaluate('focusInput()');
-    } else if (body.kind === 'drag' && typeof body.dx === 'number' && typeof body.dy === 'number' && isFinite(body.dx) && isFinite(body.dy) && Math.abs(body.dx) <= 2000 && Math.abs(body.dy) <= 2000) {
-      var origin = panel.frame.origin;
-      panel.setFrameOrigin($.NSMakePoint(origin.x + body.dx, origin.y - body.dy));
-      savePosition();
-    } else if (body.kind === 'hotspot' && typeof body.x === 'number' && typeof body.y === 'number' && typeof body.w === 'number' && typeof body.h === 'number' && isFinite(body.x) && isFinite(body.y) && Math.abs(body.x) <= 500 && Math.abs(body.y) <= 500 && body.w > 0 && body.h > 0 && body.w <= 500 && body.h <= 500) {
-      hotspot = { x: body.x, y: body.y, w: body.w, h: body.h };
-    } else if (body.kind === 'send' && typeof body.text === 'string' && body.text.trim() && body.text.length <= 65536 && body.text.indexOf('\0') === -1) {
-      runCommand('say', ['--', body.text], cliArgv);
-    } else if (body.kind === 'palette' && typeof body.palette === 'string' && /^(blue|teal|violet|ochre)$/.test(body.palette)) {
-      runCommand('pet', ['--palette', body.palette], cliArgv);
-    } else if (body.kind === 'open') runCommand('ui', [], cliArgv);
-    else if (body.kind === 'close') quit();
-  } },
-  'tick:': { types: ['void', ['id']], implementation: function(sender) { tick(); } },
-  'hover:': { types: ['void', ['id']], implementation: function(sender) { pollHover(); } }
-} });
-function tick() {
-  var value;
-  try { value = JSON.parse(ObjC.unwrap($.NSString.stringWithContentsOfFileEncodingError(viewPath, $.NSUTF8StringEncoding, null))); }
-  catch (error) { value = { offline: true }; }
-  evaluate('update(' + JSON.stringify(value) + ')');
-  if (value.offline === true) { if (!offlineAt) offlineAt = Date.now(); if (Date.now() - offlineAt >= 2000) quit(); }
-  else offlineAt = 0;
-  commands = commands.filter(function(item) {
-    if (item.task.isRunning) return true;
-    if (item.command === 'say') evaluate('commandResult(' + (Number(item.task.terminationStatus) === 0) + ')');
-    return false;
-  });
-}
-function run(argv) {
-  if (argv.length !== 3) throw new Error('Invalid pet window arguments');
-  viewPath = argv[0];
-  var htmlPath = argv[1];
-  cliArgv = JSON.parse(argv[2]);
-  if (!Array.isArray(cliArgv) || cliArgv.length !== 4 || cliArgv.some(function(arg) { return typeof arg !== 'string'; }) || cliArgv[2] !== '--project') throw new Error('Invalid CLI argv');
-  var stateDir = ObjC.unwrap($(viewPath).stringByDeletingLastPathComponent);
-  positionPath = stateDir + '/pet-window-pos.json';
-  var owner = JSON.parse(ObjC.unwrap($.NSString.stringWithContentsOfFileEncodingError(stateDir + '/pet-window.pid', $.NSUTF8StringEncoding, null)));
-  readyPath = stateDir + '/pet-window-ready-' + owner.token;
-  app = $.NSApplication.sharedApplication;
-  app.setActivationPolicy($.NSApplicationActivationPolicyAccessory);
-  var screen = $.NSScreen.mainScreen.visibleFrame;
-  var W = 150, H = 150;
-  var origin = { x: screen.origin.x + screen.size.width - (W + 20), y: screen.origin.y + 80 };
-  try {
-    var saved = JSON.parse(ObjC.unwrap($.NSString.stringWithContentsOfFileEncodingError(positionPath, $.NSUTF8StringEncoding, null)));
-    if (typeof saved.x === 'number' && typeof saved.y === 'number' && isFinite(saved.x) && isFinite(saved.y)) origin = saved;
-  } catch (error) {}
-  var screens = $.NSScreen.screens;
-  var visible = false;
-  for (var i = 0; i < screens.count; i++) {
-    var frame = screens.objectAtIndex(i).visibleFrame;
-    if (origin.x >= frame.origin.x && origin.y >= frame.origin.y && origin.x + W <= frame.origin.x + frame.size.width && origin.y + H <= frame.origin.y + frame.size.height) visible = true;
-  }
-  if (!visible) origin = { x: screen.origin.x + screen.size.width - (W + 20), y: screen.origin.y + 80 };
-  panel = $.AhubPetPanel.alloc.initWithContentRectStyleMaskBackingDefer($.NSMakeRect(origin.x, origin.y, W, H), $.NSWindowStyleMaskBorderless | $.NSWindowStyleMaskNonactivatingPanel, $.NSBackingStoreBuffered, false);
-  panel.title = 'agent-hub pet'; panel.opaque = false; panel.backgroundColor = $.NSColor.clearColor;
-  panel.level = $.NSFloatingWindowLevel;
-  panel.collectionBehavior = $.NSWindowCollectionBehaviorCanJoinAllSpaces | $.NSWindowCollectionBehaviorStationary;
-  panel.hidesOnDeactivate = false;
-  panel.acceptsMouseMovedEvents = true; // CSS :hover while key; pollHover() covers the inactive case
-  var config = $.WKWebViewConfiguration.alloc.init;
-  bridge = $.AhubPetBridge.alloc.init;
-  config.userContentController.addScriptMessageHandlerName(bridge, 'pet');
-  web = $.WKWebView.alloc.initWithFrameConfiguration($.NSMakeRect(0, 0, W, H), config);
-  web.setValueForKey(false, 'drawsBackground');
-  panel.contentView = web;
-  web.loadFileURLAllowingReadAccessToURL($.NSURL.fileURLWithPath(htmlPath), $.NSURL.fileURLWithPath(htmlPath));
-  panel.orderFrontRegardless; panel.makeKeyWindow;
-  timer = $.NSTimer.scheduledTimerWithTimeIntervalTargetSelectorUserInfoRepeats(1, bridge, 'tick:', null, true);
-  hoverTimer = $.NSTimer.scheduledTimerWithTimeIntervalTargetSelectorUserInfoRepeats(0.1, bridge, 'hover:', null, true);
-  app.run;
-}