@staix/agent-hub 0.29.0 → 0.31.0

package/src/ui/needs.ts

@@ -1,4 +1,4 @@
-export type NeedKind = "approval" | "default" | "storage" | "recovery" | "delivery" | "review" | "message" | "budget" | "offline" | "stall" | "offer";
+export type NeedKind = "approval" | "default" | "storage" | "recovery" | "delivery" | "review" | "message" | "budget" | "offline" | "stall" | "offer" | "question" | "result";
 export interface NeedItem { kind: NeedKind; level: "act" | "watch"; peer?: string; id?: string | number; until?: number; since?: number; }
 export interface NeedsInput {
   approvals?: readonly { id: string; peer?: string; expiresAt: number; since?: number }[];
@@ -10,6 +10,10 @@ export interface NeedsInput {
   facts?: readonly { kind: "review" | "offline" | "stall" | "offer"; id: number; peer?: string }[];
   messages?: readonly { id?: string; peer?: string; important: boolean; since?: number }[];
   budget?: Readonly<Record<string, { paused?: { since?: number; resetsAt?: number } }>>;
+  /** #1053: the open questions a peer asked the person: the set id, the asking peer and when it was asked, never a prompt or an option. */
+  questions?: readonly { set: string; peer?: string; since?: number }[];
+  /** #1054: unread results, a run a person started that settled and has not been seen: the completion id, the peer and when it settled, never a prompt or a reply. */
+  results?: readonly { id: string; peer?: string; since?: number }[];
 }
 export interface Needs { items: NeedItem[]; act: number; watch: number; state: "waiting" | "blocked" | "review" | "working" | "idle" | "sleeping"; }
 export interface NeedsSummary { act: number; watch: number; state: Needs["state"]; first?: NeedItem }
@@ -22,6 +26,7 @@ export function needs(input: NeedsInput, now: number): Needs {
   const add = (kind: NeedKind, level: "act" | "watch", peer?: unknown, identifier?: unknown, until?: unknown, since?: unknown) => items.push({ kind, level, ...(id(peer) ? { peer } : {}), ...(id(identifier) || typeof identifier === "number" && Number.isSafeInteger(identifier) && identifier > 0 ? { id: identifier } : {}), ...(time(until) ? { until } : {}), ...(time(since) ? { since } : {}) });
   for (const request of input.approvals ?? []) if (id(request.id) && time(request.expiresAt) && request.expiresAt > now) add("approval", "act", request.peer, request.id, request.expiresAt, request.since);
   for (const pending of input.defaults ?? []) if (id(pending.peer)) add("default", "act", pending.peer);
+  for (const question of input.questions ?? []) if (id(question.set)) add("question", "act", question.peer, question.set, undefined, question.since);
   if (input.storageBlocked === true) add("storage", "act");
   if (input.recovery) add("recovery", input.recovery.running === false ? "act" : "watch", undefined, input.recovery.id, undefined, input.recovery.since);
   for (const [peer, status] of Object.entries(input.peers ?? {})) {
@@ -44,17 +49,18 @@ export function needs(input: NeedsInput, now: number): Needs {
     else if (fact.kind === "offline" && agent(fact.peer) && !offline.has(fact.peer)) { offline.add(fact.peer); add("offline", "watch", fact.peer, fact.id); }
   }
   for (const [peer, budget] of Object.entries(input.budget ?? {})) if (budget.paused) add("budget", "watch", peer, undefined, budget.paused.resetsAt, budget.paused.since);
-  const order: Record<NeedKind, number> = { approval: 0, default: 1, storage: 2, recovery: 3, delivery: 4, review: 5, stall: 6, offer: 7, message: 8, budget: 9, offline: 10 };
+  for (const result of input.results ?? []) if (id(result.id)) add("result", "watch", result.peer, result.id, undefined, result.since);
+  const order: Record<NeedKind, number> = { approval: 0, default: 1, question: 2, storage: 3, recovery: 4, delivery: 5, review: 6, stall: 7, offer: 8, message: 9, result: 10, budget: 11, offline: 12 };
   items.sort((a,b) => (a.level === "act" ? 0 : 1) - (b.level === "act" ? 0 : 1) || order[a.kind] - order[b.kind] || (a.kind === "approval" ? (a.until ?? Infinity) - (b.until ?? Infinity) : 0) || (a.since ?? 0) - (b.since ?? 0));
   const act = items.filter(item => item.level === "act").length, watch = items.length - act;
   const peers = Object.values(input.peers ?? {}), attached = peers.some(peer => peer.attached !== false && ["idle", "busy", "paused"].includes(peer.state ?? ""));
-  const state: Needs["state"] = items.some(item => item.kind === "approval" || item.kind === "default") ? "waiting" : items.some(item => item.level === "act" && ["storage", "delivery", "recovery", "stall"].includes(item.kind)) ? "blocked" : act ? "review" : peers.some(peer => peer.attached !== false && peer.state === "busy") ? "working" : attached ? "idle" : "sleeping";
+  const state: Needs["state"] = items.some(item => item.kind === "approval" || item.kind === "default" || item.kind === "question") ? "waiting" : items.some(item => item.level === "act" && ["storage", "delivery", "recovery", "stall"].includes(item.kind)) ? "blocked" : act ? "review" : peers.some(peer => peer.attached !== false && peer.state === "busy") ? "working" : attached ? "idle" : "sleeping";
   return { items, act, watch, state };
 }
 
 /** Global status never reads console-local unread messages or source text. */
 export function summarizeNeeds(input: Omit<NeedsInput, "messages">, now: number): NeedsSummary {
   const value = needs({ approvals: input.approvals, defaults: input.defaults, peers: input.peers,
-    storageBlocked: input.storageBlocked, recovery: input.recovery, tasks: input.tasks, facts: input.facts, budget: input.budget }, now);
+    storageBlocked: input.storageBlocked, recovery: input.recovery, tasks: input.tasks, facts: input.facts, budget: input.budget, questions: input.questions, results: input.results }, now);
   return { act: value.act, watch: value.watch, state: value.state, ...(value.items[0] ? { first: value.items[0] } : {}) };
 }

package/src/ui/office-model.ts

@@ -33,6 +33,16 @@ export interface OfficeTaskInput {
   deps?: readonly number[];
   /** Optional (phase 3): the task's check is running; the task stays in_progress meanwhile. */
   checking?: boolean;
+  rank?: number | null;
+  priority?: number | null;
+  reserved?: string | null;
+  release?: number | null;
+  pinned?: boolean;
+  plannedStart?: number | null;
+}
+export interface OfficeReleaseInput {
+  id: number; name?: string; state?: string; order?: number; cut?: number | null;
+  tasks?: readonly { id: number; state?: string; deps?: readonly number[] }[];
 }
 /** Optional (phase 3): a warning line between desks. Task and peer ids only, never paths or symbols. */
 export interface OfficeLinkInput {
@@ -55,7 +65,8 @@ export interface OfficeEventInput {
   };
 }
 export interface OfficeSnapshotInput {
-  status?: { peers?: Record<string, OfficePeerInput> };
+  status?: { peers?: Record<string, OfficePeerInput>; roleInfo?: Record<string, { flowRoles?: readonly string[] }> };
+  releases?: readonly OfficeReleaseInput[];
   tasks?: readonly OfficeTaskInput[];
   permissions?: readonly { peer?: string }[];
   budget?: Record<string, { paused?: { reason?: string; resetsAt?: number | null } | null; [key: string]: unknown }>;
@@ -84,6 +95,10 @@ export interface OfficeCard {
   rework: boolean;
   /** The task's check is running; the card stays at its owner's desk. */
   checking: boolean;
+  reserved: string;
+  pinned: boolean;
+  plannedDate: string;
+  releaseTag?: { ordinal: number; name: string };
   /** Visible text: "#id public title". */
   label: string;
   /** Accessible name: "#id class: public title (state)", plus waiting/rework/review marks. */
@@ -114,6 +129,8 @@ export interface OfficeDesk {
   breakResetsAt: number | null;
   cards: OfficeCard[];
   extraCards: number;
+  planner: boolean;
+  unplanned: number;
 }
 export interface OfficeRoom {
   id: string;
@@ -123,6 +140,12 @@ export interface OfficeRoom {
   count: number;
   cards: OfficeCard[];
   overflow: number;
+  unplanned?: number;
+  x: number; y: number; w: number; h: number;
+}
+export interface OfficeDock {
+  id: number; name: string; state: string; ordinal: number;
+  approved: number; scope: number; ratio: number; cut: string;
   x: number; y: number; w: number; h: number;
 }
 export interface OfficeTransitions {
@@ -158,6 +181,8 @@ export interface OfficeScene {
   desks: OfficeDesk[];
   extraPeers: number;
   rooms: OfficeRoom[];
+  docks: OfficeDock[];
+  extraReleases: number;
   counts: OfficeCounts;
   transitions: OfficeTransitions;
   links: OfficeLink[];
@@ -168,7 +193,7 @@ export interface OfficeScene {
    * every `cards` list. Zero geometry: the dashboard never draws it, acon Space maps it. Same allowlisted fields as `cards`.
    */
   attributedCards: OfficeCard[];
-  /** Task id -> placement ("room:todo" | "room:work" | "room:review" | "shelf:done" | "desk:<peer>" | "counted:unknown"). */
+  /** Task id -> placement ("room:backlog" | "room:todo" | "room:work" | "room:review" | "shelf:done" | "desk:<peer>" | "counted:unknown"). */
   placed: Record<string, string>;
   arcs: OfficeArc[];
   alerts: OfficeAlert[];
@@ -204,6 +229,17 @@ export function officeModel(snapshot: OfficeSnapshotInput, previous: OfficeScene
   const tasks = Array.isArray(snapshot?.tasks) ? snapshot.tasks.filter((task) => task && typeof task.id === "number") : [];
   const permissions = Array.isArray(snapshot?.permissions) ? snapshot.permissions : [];
   const budget = snapshot?.budget && typeof snapshot.budget === "object" ? snapshot.budget : {};
+  const date = (value: unknown) => {
+    if (typeof value !== "number" || !Number.isFinite(value) || value <= 0 || value > 8_640_000_000_000_000) return "";
+    const local = new Date(value);
+    return `${local.getFullYear()}-${String(local.getMonth() + 1).padStart(2, "0")}-${String(local.getDate()).padStart(2, "0")}`;
+  };
+  const rank = (value: unknown) => typeof value === "number" && Number.isFinite(value) ? value : Infinity;
+  const backlog = tasks.filter(task => task.state === "backlog").sort((a, b) => (rank(a.rank) - rank(b.rank)) || (rank(a.priority) - rank(b.priority)) || a.id - b.id);
+  const unplanned = backlog.filter(task => rank(task.rank) === Infinity && !text(task.reserved)).length;
+  const releases: OfficeReleaseInput[] = (Array.isArray(snapshot?.releases) ? snapshot.releases : []).filter(row => row && Number.isSafeInteger(row.id) && row.id > 0 && ["planning", "active", "frozen"].includes(text(row.state)))
+    .sort((a, b) => (rank(a.order) - rank(b.order)) || a.id - b.id);
+  const docked = releases.slice(0, 3);
 
   // State counts mirror taskProgress (src/ui/task-progress.ts) exactly, including the waiting
   // rule on deps; test/office-model.test.ts pins the equality so a drift fails there.
@@ -272,17 +308,24 @@ export function officeModel(snapshot: OfficeSnapshotInput, previous: OfficeScene
   const card = (task: OfficeTaskInput, x: number, y: number, w: number, h: number): OfficeCard => {
     const state = text(task.state) || "unknown";
     const taskClass = text(task.class) || "task";
-    const waiting = waitingById.get(task.id) === true;
+    const plannedDate = state === "backlog" && date(task.plannedStart) && task.plannedStart! > now ? date(task.plannedStart) : "";
+    const waiting = waitingById.get(task.id) === true || state === "backlog" && ((task.deps ?? []).some(id => states.get(id) !== "approved") || !!plannedDate);
     const rework = state === "changes_requested";
     const checking = task.checking === true;
     const owner = text(task.owner);
     const reviewer = text(task.reviewer);
+    const reserved = state === "backlog" ? text(task.reserved) : "", pinned = state === "backlog" && task.pinned === true;
+    const releaseIndex = docked.findIndex(row => row.id === task.release);
+    const releaseTag = releaseIndex < 0 ? undefined : { ordinal: releaseIndex + 1, name: text(docked[releaseIndex]!.name) || "[withheld]" };
     let name = `#${task.id} ${taskClass}: ${text(task.title)} (${state.replaceAll("_", " ")})`;
-    if (waiting) name += ", waiting on dependencies";
+    if (waiting) name += state === "backlog" ? ", waits" + (plannedDate ? ` until ${plannedDate}` : "") : ", waiting on dependencies";
+    if (reserved) name += `, reserved for ${reserved}`;
+    if (pinned) name += ", pinned";
+    if (releaseTag) name += `, release ${releaseTag.ordinal}: ${releaseTag.name}`;
     if (rework) name += ", rework";
     if (checking) name += ", check running";
     if (state === "in_review") name += `, ${owner || "unassigned"} reviewed by ${reviewer || "unassigned"}`;
-    return { id: task.id, taskClass, state, owner, reviewer, waiting, rework, checking, label: `#${task.id} ${text(task.title)}`, name, x, y, w, h };
+    return { id: task.id, taskClass, state, owner, reviewer, waiting, rework, checking, reserved, pinned, plannedDate, ...(releaseTag ? { releaseTag } : {}), label: `#${task.id} ${text(task.title)}`, name, x, y, w, h };
   };
 
   const desks: OfficeDesk[] = shownIds.map((id) => {
@@ -320,6 +363,8 @@ export function officeModel(snapshot: OfficeSnapshotInput, previous: OfficeScene
     if (finishing) parts.push("finishing a turn");
     if (condition !== "waiting" && count > 0) parts.push(`${count} approval${count === 1 ? "" : "s"} waiting`);
     if (!attached) parts.push("disconnected, work retained");
+    const planner = Array.isArray(snapshot.status?.roleInfo?.[id]?.flowRoles) && snapshot.status!.roleInfo![id]!.flowRoles!.includes("planner");
+    if (planner) parts.push(`planner, ${unplanned} unplanned backlog cards`);
     // An over-full desk shows two chips and a "+N more" line in the third slot.
     const shown = work.length > DESK_CARDS ? work.slice(0, DESK_CARDS - 1) : work;
     return {
@@ -331,12 +376,14 @@ export function officeModel(snapshot: OfficeSnapshotInput, previous: OfficeScene
       finishing,
       cards: shown.map((task, index) => card(task, x + 0.8, y + 8.5 + index * 2.5, DESK_W - 1.6, 2)),
       extraCards: work.length - shown.length,
+      planner, unplanned: planner ? unplanned : 0,
     };
   });
 
   const desksBottom = Math.max(0, ...desks.map(desk => desk.y + desk.h));
   const roomsY = desksBottom ? desksBottom + 2 : 0;
   const roomDefs = [
+    { id: "backlog", label: "Backlog", filterState: "backlog", list: backlog, count: counts.backlog ?? 0 },
     { id: "todo", label: "To do", filterState: "proposed", list: todo, count: counts.proposed + counts.waiting },
     { id: "work", label: "Work floor", filterState: "work", list: workUnplaced, count: counts.in_progress + counts.changes_requested },
     { id: "review", label: "Review", filterState: "in_review", list: review, count: counts.in_review },
@@ -347,12 +394,20 @@ export function officeModel(snapshot: OfficeSnapshotInput, previous: OfficeScene
     const y = roomsY + Math.floor(index / cols) * ROOM_DY;
     return {
       id: def.id, label: def.label, filterState: def.filterState, count: def.count,
+      ...(def.id === "backlog" && !desks.some(desk => desk.planner) ? { unplanned } : {}),
       // One column at 12 px per unit: 28 px cards, 6 px gaps, eight cards at most.
       cards: def.list.slice(0, ROOM_CARDS).map((task, row) => card(task, x + 1, y + 3.4 + row * (ROOM_CARD_H + ROOM_CARD_GAP), ROOM_W - 2, ROOM_CARD_H)),
       overflow: Math.max(0, def.list.length - ROOM_CARDS),
       x, y, w: ROOM_W, h: ROOM_H,
     };
   });
+  const docks: OfficeDock[] = docked.map((row, index) => {
+    const scope: NonNullable<OfficeReleaseInput["tasks"]> = Array.isArray(row.tasks) ? row.tasks.filter((task: NonNullable<OfficeReleaseInput["tasks"]>[number]) => task && Number.isSafeInteger(task.id) && task.id > 0) : [];
+    const approved = scope.filter(task => task.state === "approved").length, position = roomDefs.length + index;
+    return { id: row.id, name: text(row.name) || "[withheld]", state: text(row.state), ordinal: index + 1, approved, scope: scope.length,
+      ratio: scope.length ? approved / scope.length : 0, cut: date(row.cut), x: (position % cols) * ROOM_DX,
+      y: roomsY + Math.floor(position / cols) * ROOM_DY, w: ROOM_W, h: ROOM_H };
+  });
 
   const placed: Record<string, string> = {};
   for (const task of tasks) {    const state = text(task.state);
@@ -362,7 +417,7 @@ export function officeModel(snapshot: OfficeSnapshotInput, previous: OfficeScene
       : state === "approved" ? "shelf:done"
       : state === "cancelled" ? "counted:cancelled"
       : state === "in_progress" || state === "changes_requested" ? (owner && shownSet.has(owner) ? `desk:${owner}` : "room:work")
-      : state === "backlog" ? "counted:backlog" : "counted:unknown";
+      : state === "backlog" ? "room:backlog" : "counted:unknown";
   }
   // A bubble's attributed task may sit past the rendering cut; keep its public card so a consumer that draws more cards than the page can.
   const drawn = new Set<number>([...desks.flatMap((desk) => desk.cards), ...rooms.flatMap((room) => room.cards)].map((entry) => entry.id));
@@ -454,9 +509,10 @@ export function officeModel(snapshot: OfficeSnapshotInput, previous: OfficeScene
   }
   return {
     cols,
-    width: Math.max(desksWidth, ...rooms.map(room => room.x + room.w), 1),
-    height: Math.max(desksBottom, ...rooms.map(room => room.y + room.h), 1),
+    width: Math.max(desksWidth, ...[...rooms, ...docks].map(room => room.x + room.w), 1),
+    height: Math.max(desksBottom, ...[...rooms, ...docks].map(room => room.y + room.h), 1),
     desks, extraPeers, rooms, counts, transitions, slots, placed, attributedCards,
+    docks, extraReleases: Math.max(0, releases.length - docks.length),
     links,
     arcs: keptArcs, alerts: keptAlerts, latched, settle, at, eventTime, lastSeq,
   };

package/src/ui/office-space.ts

@@ -21,6 +21,7 @@ export interface SpaceScene {
 }
 
 const ZONES: Record<string, { kind: ZoneKind; title: string }> = {
+  backlog: { kind: "queue", title: "Backlog" },
   todo: { kind: "queue", title: "To do" }, work: { kind: "work", title: "Work floor" },
   review: { kind: "review", title: "Review" }, done: { kind: "done", title: "Done" },
 };

package/src/ui/plugin-questions.ts

@@ -0,0 +1,56 @@
+/**
+ * #1053 T5: the acon inbox side of a question a peer asked with hub_ask. Pure: it builds the inbox item from the stored row the hub reports and checks the
+ * person evidence an answer needs; `plugin.ts` owns the transport. No text here is logged.
+ *
+ * Authority: an answer is accepted only when the console advertises `action.meta` and `action()` received the console's own `meta` (`via: "console"`, a verified
+ * `identity`), which the page cannot set (agent-console `action(input, meta?)`). An answer without it is refused before any request reaches the hub.
+ */
+
+import type { ActionMeta, InboxAnswers, InboxVerb, VerbForm } from "@staix/agent-console/contract";
+
+// The acon types come only through the generated bridge (`scripts/acon-review-types.ts`, regenerated and compared by its check), so a drift of the form or of the answer it
+// submits fails there and not at a user's console. Type-only: agent-hub keeps zero runtime dependencies.
+export type { ActionMeta, InboxAnswers };
+export interface QuestionRowView {
+  set: string; peer: string; created: number; private?: boolean;
+  questions: { id: string; prompt: string; options: { id: string; label: string; description?: string }[]; multi?: boolean; allowOther?: boolean }[];
+}
+type FormQuestion = VerbForm["questions"][number];
+export interface QuestionItem {
+  id: string; group: "decision"; kind: string; title: string; actor: string; project: string; at: string; chip: { text: string; tone: "warn" };
+  verbs: InboxVerb[];
+  link: { panel: string; params: Record<string, string> };
+}
+
+/** Both features are needed: `inbox.form` renders the form, `action.meta` gives the answer its person evidence. One alone is the plain item. */
+export const canAnswerInInbox = (features: readonly string[] | undefined): boolean => !!features?.includes("inbox.form") && features.includes("action.meta");
+
+const flat = (text: string, max: number) => Array.from(text.replace(/[\u0000-\u001f\u007f-\u009f\u2028\u2029\s]+/g, " ").trim()).slice(0, max).join("");
+export const questionItemId = (project: string, set: string) => `question:${project}:${set}`;
+export const QUESTION_ITEM = /^question:([^:]+):(qs-[a-f0-9]{12})$/;
+
+/**
+ * The inbox item. A private question (asked in a PII turn or about a PII task) gets a stub title and no detail: its text is in the form only, which is the person's
+ * own answer surface. Without the two features the item is a plain decision with an `open` verb that links to the agents panel.
+ */
+export function questionItem(row: QuestionRowView, project: { id: string; name: string }, features: readonly string[] | undefined): QuestionItem {
+  const head = row.private ? "a question" : `: ${flat(row.questions[0]?.prompt ?? "", 80)}`;
+  const title = (row.private ? `${row.peer} asks ${head}` : `${row.peer} asks${head}`).slice(0, 200);
+  const link = { panel: "agents", params: { project: project.id } };
+  const base = { id: questionItemId(project.id, row.set), group: "decision" as const, title, actor: row.peer, project: project.name, at: new Date(row.created).toISOString(), chip: { text: "question", tone: "warn" as const }, link };
+  if (!canAnswerInInbox(features)) return { ...base, kind: "decision", verbs: [{ id: "open", label: "Open Agents", primary: true }] };
+  const form = { questions: row.questions.map<FormQuestion>(question => ({ id: question.id, prompt: question.prompt, options: question.options.map(option => ({ id: option.id, label: option.label, ...(option.description ? { description: option.description } : {}) })),
+    ...(question.multi === true ? { multiple: true } : {}), ...(question.allowOther === true ? { other: { maxLength: 500 } } : {}) })) };
+  return { ...base, kind: "question", verbs: [{ id: "answer", label: "Answer", primary: true, form }, { id: "open", label: "Open Agents" }] };
+}
+
+/** The console's evidence, or the refusal that tells the person how to get it. Page-supplied fields that would stand in for it are refused too. */
+export function personEvidence(features: readonly string[] | undefined, meta: ActionMeta | undefined, input: Record<string, unknown>): { ok: true; identity: string } | { ok: false; error: string } {
+  if (!features?.includes("action.meta") || !meta || typeof meta !== "object") return { ok: false, error: "Answering needs a console with verified person identity; update acon and reopen this panel, or answer with ahub answer." };
+  const value = meta as unknown as Record<string, unknown>;
+  if (value.via !== "console" || typeof value.identity !== "string" || !value.identity.trim() || typeof value.node !== "string" || !value.node.trim())
+    return { ok: false, error: "Answering needs a console with verified person identity; update acon and reopen this panel, or answer with ahub answer." };
+  if (["author", "meta", "personMeta", "person", "identity", "surface", "questionSet", "projectId", "instanceId"].some(key => Object.hasOwn(input, key)))
+    return { ok: false, error: "The person's identity and the target come from the console; remove those fields and retry." };
+  return { ok: true, identity: value.identity.trim().slice(0, 200) };
+}

package/src/ui/plugin-results.ts

@@ -0,0 +1,81 @@
+/**
+ * #1054 T6: the acon inbox side of a result: a run a person started that settled and has not been seen. Pure: it builds the inbox item from the row the hub reports and checks the
+ * person evidence a receipt needs; `plugin.ts` owns the transport. No text here is logged.
+ *
+ * Publication: an item is published only to a console that advertises BOTH `inbox.result` (it renders the group) and `action.meta` (a receipt then has person evidence). One alone,
+ * or neither, and results stay in the ahub panel, `ahub console`, `ahub status` and `ahub results`: nothing is published that the console could not render or that the person
+ * could not mark read with evidence.
+ *
+ * Authority: `result_seen`, `results_read_all` and `results_unread_last` are accepted only when the console advertises `action.meta` and `action()` received the console's own
+ * `meta` (`via: "console"`, a verified `identity`), which the page cannot set (agent-console `action(input, meta?)`). They never go through the dashboard's forwarding list. The
+ * acon "seeing" rule (a focused, visible window, the result's end in view for a second, the latest edge) is agent-console#27 and is not decided here: this only accepts the receipt.
+ * Mark unread is NOT an inbox verb: a read item leaves the inbox, so mark-unread lives in the ahub panel (this plugin's dashboard) and in `ahub results --unread-last`.
+ */
+
+import type { ActionMeta } from "@staix/agent-console/contract";
+
+export type { ActionMeta };
+export type ResultOutcome = "done" | "failed" | "limit" | "interrupted";
+/** The detail the hub built at display (`completion-detail.ts`): a head of the request, a stub, or nothing. */
+export type ResultDetailView = { kind: "head" | "stub"; text: string } | { kind: "none" };
+/** One row of the hub's `results` snapshot field. */
+export interface ResultRowView {
+  id: string; peer: string; outcome: ResultOutcome; settledAt: number; ms?: number; private?: boolean; title?: string; detail?: ResultDetailView;
+}
+export interface ResultItem {
+  id: string; group: "result"; kind: "result"; title: string; detail?: string; actor: string; project: string; at: string; chip: { text: string; tone: "ok" | "warn" | "err" | "neutral" };
+  verbs: { id: string; label: string; primary?: boolean }[];
+  link: { panel: string; params: Record<string, string> };
+  seen: { action: "result_seen" };
+}
+
+/**
+ * The receipt actions this plugin advertises (so acon lets the page and the inbox send them), and answers itself with the console's person meta: never in the dashboard's forwarding
+ * list. `result_seen` and `results_read_all` come from the inbox (acon's seeing rule and its "Mark all read") and from the panel; `results_unread_last` only from the panel, because a
+ * read item has left the inbox: there is no inbox verb for it. All three are the person's writes, so all three need the same evidence.
+ */
+export const RESULT_ACTIONS = ["result_seen", "results_read_all", "results_unread_last"] as const;
+export type ResultAction = (typeof RESULT_ACTIONS)[number];
+
+/** Both features are needed. One alone is not enough: no group to render, or no person evidence for the receipt. */
+export const canPublishResults = (features: readonly string[] | undefined): boolean => !!features?.includes("inbox.result") && features.includes("action.meta");
+
+export const resultItemId = (project: string, id: string) => `result:${project}:${id}`;
+export const RESULT_ITEM = /^result:([^:]+):(cmp-[a-f0-9]{12})$/;
+const OUTCOME_WORD: Record<ResultOutcome, string> = { done: "finished", failed: "failed", limit: "stopped at a limit", interrupted: "interrupted" };
+const CHIP: Record<ResultOutcome, { text: string; tone: "ok" | "warn" | "err" | "neutral" }> = {
+  done: { text: "done", tone: "ok" }, failed: { text: "failed", tone: "err" }, limit: { text: "limit", tone: "warn" }, interrupted: { text: "interrupted", tone: "warn" },
+};
+const flat = (text: string, max: number) => Array.from(text.replace(/[\u0000-\u001f\u007f-\u009f\u2028\u2029\s]+/g, " ").trim()).slice(0, max).join("");
+
+/**
+ * The inbox item. The title is `<peer>: <outcome word>`, computed here from the row's peer and outcome and never taken from the row's own title text; a private result is a stub
+ * (`<peer>: a private result`) with no detail. The detail is whatever the hub built at display, or none: this never reads a prompt itself. `at` is the settle time, stable
+ * across snapshots, which is what acon's snooze and oldest-first order key on.
+ */
+export function resultItem(row: ResultRowView, project: { id: string; name: string }): ResultItem {
+  const outcome: ResultOutcome = row.outcome in OUTCOME_WORD ? row.outcome : "interrupted";
+  const title = (row.private ? `${row.peer}: a private result` : `${row.peer}: ${OUTCOME_WORD[outcome]}`).slice(0, 200);
+  const detail = !row.private && row.detail && row.detail.kind !== "none" && typeof row.detail.text === "string" ? flat(row.detail.text, 200) : row.private ? "a private request" : "";
+  return {
+    id: resultItemId(project.id, row.id), group: "result", kind: "result", title, ...(detail ? { detail } : {}), actor: row.peer, project: project.name,
+    at: new Date(row.settledAt).toISOString(), chip: CHIP[outcome], verbs: [{ id: "open", label: "Open Agents", primary: true }],
+    link: { panel: "agents", params: { project: project.id } }, seen: { action: "result_seen" },
+  };
+}
+
+const REFUSAL = "Marking a result read needs a console with verified person identity; update acon and reopen this panel, or use ahub results.";
+/**
+ * The console's evidence, or the refusal that tells the person how to get it. Page-supplied fields that would stand in for the person (`author`, `meta`, `identity`, `surface`) or
+ * name a completion by another key are refused too. `projectId` is allowed: the panel names the project it is showing, as every dashboard action does, and it only picks WHICH running
+ * project's receipt this is; the daemon instance is never taken from the page (`receiptVerb` resolves it from the running listing), and the person evidence is the console's alone.
+ */
+export function receiptEvidence(features: readonly string[] | undefined, meta: ActionMeta | undefined, input: Record<string, unknown>): { ok: true } | { ok: false; error: string } {
+  if (!features?.includes("action.meta") || !meta || typeof meta !== "object") return { ok: false, error: REFUSAL };
+  const value = meta as unknown as Record<string, unknown>;
+  if (value.via !== "console" || typeof value.identity !== "string" || !value.identity.trim() || typeof value.node !== "string" || !value.node.trim()) return { ok: false, error: REFUSAL };
+  // `seenAt` and `explicit` are acon's own (the shell sends them with the seeing rule): the hub stamps its own time, so they are accepted and ignored, never trusted.
+  if (["author", "meta", "personMeta", "person", "identity", "surface", "completion", "completionId", "seen"].some(key => Object.hasOwn(input, key)))
+    return { ok: false, error: "The person's identity and the target come from the console; remove those fields and retry." };
+  return { ok: true };
+}