@staix/agent-hub 0.13.0 → 0.15.0

package/src/hub/deliverable-files.ts

@@ -0,0 +1,131 @@
+import { constants, lstatSync, type Stats } from "node:fs";
+import { open } from "node:fs/promises";
+import { createHash } from "node:crypto";
+import { relative } from "node:path";
+import { guardPath } from "../local/tools.ts";
+import { isHubWritePath } from "./permission-mode.ts";
+import { realPath } from "./project.ts";
+import { DELIVERABLE_LIMITS, deliverableId, type DeliverableClaim, type DeliverableRecord, type DeliverableState } from "./deliverables.ts";
+
+/**
+ * The only code that opens a deliverable (#509a). The hub hashes the bytes itself; nothing an agent says about a file is used.
+ *
+ * - Containment: `guardPath` (read mode) resolves the path with `realPath`, refuses anything outside the project, on the secrets denylist or
+ *   through a dangling link, and returns the resolved path. The file is then opened without following a final link and its identity
+ *   (device, inode, size and mtime: Linux reuses an inode number at once) is compared with what was checked, so a path swapped between the check and the open is refused, not read.
+ * - Plain folders: nothing here needs git, a PR, a snapshot or a lifecycle receipt.
+ * - Bounded and non-blocking: a regular file only, at most `fileBytes` each and `totalBytes` per call, read in 1 MiB chunks with an await
+ *   between them so a large file never stalls the daemon. A file that changes while it is read is refused, never recorded half-read.
+ */
+
+export interface DeliverablePorts {
+  cwd: string;
+  /** The project's secrets denylist (`local.deny`). */
+  deny: readonly string[];
+  /** Whether a file belongs to a PII task or matches `pii.paths`: its record is private. */
+  private(path: string): boolean;
+}
+
+const CHUNK = 1024 * 1024;
+const NOFOLLOW = constants.O_NOFOLLOW ?? 0;
+
+export class DeliverableRefusal extends Error {}
+
+/**
+ * Test seam: runs between vetting a path and opening it, the window a swapped file would use. Never set outside tests; no config or tool reaches it.
+ * ponytail: a hook, not a lock. The open uses O_NOFOLLOW and a device/inode comparison, which is what this seam lets a test attack.
+ */
+export const deliverableHooks: { beforeOpen?: (path: string) => void } = {};
+const refuse = (path: string, why: string): never => { throw new DeliverableRefusal(`deliverable ${path}: ${why}`); };
+
+interface Located { real: string; stat: Stats }
+
+/** Resolve and vet one path. Throws `DeliverableRefusal` with a reason that names the given relative path, never a resolved one. */
+function locate(path: string, ports: DeliverablePorts): Located {
+  let real: string;
+  try { real = guardPath({ cwd: ports.cwd, deny: [...ports.deny], readOnly: [] }, path, "read"); }
+  catch (error) { return refuse(path, (error as Error).message.replace(path, "the path").slice(0, 160)); }
+  // guardPath's read mode keeps secrets out but not the hub's own state: `.agenthub` and `.git` are refused here, so no hash of a config, token or
+  // git file ever reaches a record (a hash of a low-entropy file confirms guesses). Compared on the resolved path, folded like the write guard.
+  let root: string;
+  try { root = realPath(ports.cwd); } catch { return refuse(path, "the project root cannot be resolved"); }
+  if (isHubWritePath(relative(root, real))) return refuse(path, "the hub's own state is not a deliverable");
+  let stat: Stats;
+  try { stat = lstatSync(real); }
+  catch (error) { return refuse(path, (error as NodeJS.ErrnoException).code === "ENOENT" ? "the file does not exist" : "the file cannot be read"); }
+  if (!stat.isFile()) return refuse(path, "not a regular file");
+  if (stat.size > DELIVERABLE_LIMITS.fileBytes) return refuse(path, `larger than ${DELIVERABLE_LIMITS.fileBytes / (1024 * 1024)} MiB`);
+  return { real, stat };
+}
+
+const sameFile = (a: Pick<Stats, "dev" | "ino">, b: Pick<Stats, "dev" | "ino">) => a.dev === b.dev && a.ino === b.ino;
+
+/** sha256 and size of one vetted file, or a refusal. */
+async function digest(path: string, found: Located): Promise<{ sha256: string; bytes: number }> {
+  let handle;
+  deliverableHooks.beforeOpen?.(path);
+  try { handle = await open(found.real, constants.O_RDONLY | NOFOLLOW); }
+  catch { return refuse(path, "the file cannot be opened"); }
+  try {
+    const before = await handle.stat();
+    if (!before.isFile() || !sameFile(before, found.stat) || before.size !== found.stat.size || before.mtimeMs !== found.stat.mtimeMs) return refuse(path, "the file changed while it was being checked");
+    const hash = createHash("sha256"), buffer = Buffer.allocUnsafe(CHUNK);
+    let bytes = 0;
+    for (;;) {
+      const { bytesRead } = await handle.read(buffer, 0, CHUNK, bytes);
+      if (!bytesRead) break;
+      bytes += bytesRead;
+      if (bytes > DELIVERABLE_LIMITS.fileBytes) return refuse(path, "larger than the size limit");
+      hash.update(buffer.subarray(0, bytesRead));
+    }
+    const after = await handle.stat();
+    if (after.size !== bytes || after.size !== before.size || after.mtimeMs !== before.mtimeMs) return refuse(path, "the file changed while it was being read");
+    return { sha256: hash.digest("hex"), bytes };
+  } finally { await handle.close().catch(() => {}); }
+}
+
+/** Refuse a bad claim before any effect, without hashing: the path must be inside the project, allowed, and a regular file of a usable size. */
+export function vetDeliverables(claims: readonly DeliverableClaim[], ports: DeliverablePorts): void {
+  let total = 0;
+  for (const claim of claims) total += locate(claim.path, ports).stat.size;
+  if (total > DELIVERABLE_LIMITS.totalBytes) throw new DeliverableRefusal(`deliverables: together larger than ${DELIVERABLE_LIMITS.totalBytes / (1024 * 1024)} MiB`);
+}
+
+/** Hash the claimed files now. Any refusal refuses the whole call: there is no partial record. */
+export async function hashDeliverables(claims: readonly DeliverableClaim[], ports: DeliverablePorts): Promise<DeliverableRecord[]> {
+  const found = claims.map(claim => ({ claim, at: locate(claim.path, ports) }));
+  if (found.reduce((sum, row) => sum + row.at.stat.size, 0) > DELIVERABLE_LIMITS.totalBytes) throw new DeliverableRefusal(`deliverables: together larger than ${DELIVERABLE_LIMITS.totalBytes / (1024 * 1024)} MiB`);
+  const records: DeliverableRecord[] = [];
+  for (const { claim, at } of found) {
+    const { sha256, bytes } = await digest(claim.path, at);
+    records.push({ id: deliverableId(claim.path, claim.format), path: claim.path, format: claim.format, ...(claim.version !== undefined ? { version: claim.version } : {}), sha256, bytes, ...(ports.private(claim.path) ? { private: true as const } : {}) });
+  }
+  return records;
+}
+
+export interface DeliverableCheck { record: DeliverableRecord; state: DeliverableState; why?: string }
+
+/**
+ * Compare recorded deliverables with the files as they are now. `unchanged` and `changed` are measurements; `missing` is a file that is gone;
+ * `unknown` is a file the hub cannot vouch for (outside the project, denied, too large, unreadable, or changing while read): never `unchanged`.
+ */
+export async function checkDeliverables(records: readonly DeliverableRecord[], ports: DeliverablePorts): Promise<DeliverableCheck[]> {
+  const out: DeliverableCheck[] = [];
+  // The files may have grown since delivery: the aggregate bound holds for a read as for a delivery, so an over-large set is read as unknown, not hashed.
+  let total = 0;
+  for (const record of records) { try { if (record.path) total += locate(record.path, ports).stat.size; } catch { /* reported per file below */ } }
+  const tooLarge = total > DELIVERABLE_LIMITS.totalBytes;
+  for (const record of records) {
+    if (!record.path) { out.push({ record, state: "unknown", why: "no path recorded" }); continue; }
+    if (tooLarge) { out.push({ record, state: "unknown", why: `the files together are now larger than ${DELIVERABLE_LIMITS.totalBytes / (1024 * 1024)} MiB` }); continue; }
+    try {
+      const found = locate(record.path, ports);
+      const now = await digest(record.path, found);
+      out.push({ record, state: now.sha256 === record.sha256 ? "unchanged" : "changed" });
+    } catch (error) {
+      const why = error instanceof DeliverableRefusal ? error.message : "unreadable";
+      out.push({ record, state: /does not exist/.test(why) ? "missing" : "unknown", why });
+    }
+  }
+  return out;
+}

package/src/hub/deliverables.ts

@@ -0,0 +1,125 @@
+import { createHash } from "node:crypto";
+
+/**
+ * Deliverable records (#509a): which bytes a task delivered, bound to content hashes the hub computed itself. A claim names a file and its
+ * format; the hub opens the file (`deliverable-files.ts`), hashes what it finds and records that. A hash an agent supplies is never read:
+ * `parseDeliverableClaims` refuses any field it does not own, so a claimed `sha256` is a refusal, not an input.
+ *
+ * Pure: no filesystem, clock or config. Plain folders work because nothing here (or in the file reader) needs git, a PR or a snapshot.
+ */
+
+export const DELIVERABLE_LIMITS = Object.freeze({
+  /** Records on one task. */
+  count: 16,
+  /** One file the hub will hash: larger is refused, never hashed in part. */
+  fileBytes: 256 * 1024 * 1024,
+  /** All files of one call. */
+  totalBytes: 512 * 1024 * 1024,
+  pathChars: 512,
+  formatChars: 32,
+  versionChars: 64,
+});
+
+/** What an agent may say about a deliverable. The hash, the size and the id are the hub's. */
+export interface DeliverableClaim { path: string; format: string; version?: string }
+
+/**
+ * What the board stores: the claim plus what the hub measured. The board keeps the path of every record, because "changed since review" needs
+ * it to find the file again (a PII task's row holds its full text there too). `private` marks a record whose path no other peer, log, event or
+ * memory may see: every view goes through `publicDeliverables`, which shows a private record by id, hash and size only.
+ */
+export interface DeliverableRecord {
+  id: string;
+  /** Project-relative, forward slashes. Absent only in a public view of a private record. */
+  path?: string;
+  format: string;
+  version?: string;
+  sha256: string;
+  bytes: number;
+  private?: true;
+}
+
+export type DeliverableState = "unchanged" | "changed" | "missing" | "unknown";
+export interface DeliverableStatus { id: string; sha256: string; state: DeliverableState; path?: string; format: string; version?: string; private?: true }
+
+const FORMAT = /^[a-z0-9][a-z0-9.+-]{0,31}$/;
+const VERSION = /^[A-Za-z0-9][A-Za-z0-9._+-]{0,63}$/;
+const SHA256 = /^[0-9a-f]{64}$/;
+const ID = /^d-[0-9a-f]{12}$/;
+
+const own = (value: unknown, keys: readonly string[], label: string): Record<string, unknown> => {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`${label}: expected an object`);
+  const extra = Object.keys(value).filter(key => !keys.includes(key));
+  if (extra.length) throw new Error(`${label}: unsupported field ${extra[0]!.slice(0, 32)}${extra.includes("sha256") || extra.includes("hash") || extra.includes("bytes") ? " (the hub hashes the file itself; a claimed hash is not used)" : ""}`);
+  return value as Record<string, unknown>;
+};
+
+/** A project-relative spelling: forward slashes, no `.` or `..` segments, no NUL or control characters, not empty, not absolute. */
+export function deliverablePath(value: unknown): string {
+  if (typeof value !== "string" || !value || value.length > DELIVERABLE_LIMITS.pathChars) throw new Error("deliverable path: expected 1 to 512 characters");
+  if (/[\u0000-\u001f\u007f\\]/.test(value) || value.startsWith("/") || /^[A-Za-z]:/.test(value)) throw new Error("deliverable path: expected a relative path with forward slashes");
+  const parts = value.split("/");
+  if (parts.some(part => !part || part === "." || part === "..")) throw new Error("deliverable path: no empty, . or .. segments");
+  return parts.join("/");
+}
+
+/** The claims of a `hub_task_done` or `hub_sdlc_record` call. A bad claim is refused whole: no partial record. */
+export function parseDeliverableClaims(value: unknown): DeliverableClaim[] {
+  if (!Array.isArray(value)) throw new Error("deliverables: expected a list");
+  if (!value.length || value.length > DELIVERABLE_LIMITS.count) throw new Error(`deliverables: 1 to ${DELIVERABLE_LIMITS.count} entries`);
+  const seen = new Set<string>();
+  return value.map((raw, index) => {
+    const claim = own(raw, ["path", "format", "version"], `deliverables[${index}]`);
+    const path = deliverablePath(claim.path);
+    if (typeof claim.format !== "string" || !FORMAT.test(claim.format)) throw new Error(`deliverables[${index}].format: expected a lowercase label such as md, pdf, docx or csv`);
+    if (claim.version !== undefined && (typeof claim.version !== "string" || !VERSION.test(claim.version))) throw new Error(`deliverables[${index}].version: expected a short label such as v2 or 2026-10`);
+    if (seen.has(path)) throw new Error(`deliverables[${index}]: ${path} is named twice`);
+    seen.add(path);
+    return { path, format: claim.format, ...(claim.version !== undefined ? { version: claim.version } : {}) };
+  });
+}
+
+/** An opaque stable id for a deliverable: its path and format, so a changed file keeps its id and an unrelated one never shares it. */
+export function deliverableId(path: string, format: string): string {
+  return `d-${createHash("sha256").update(`${format}\0${path}`).digest("hex").slice(0, 12)}`;
+}
+
+/** Records read back from the board: the same bounds, so a damaged row is refused rather than trusted. */
+export function parseDeliverableRecords(value: unknown): DeliverableRecord[] {
+  if (!Array.isArray(value) || !value.length || value.length > DELIVERABLE_LIMITS.count) throw new Error("deliverable records: 1 to 16 entries");
+  const ids = new Set<string>();
+  return value.map((raw, index) => {
+    const row = own(raw, ["id", "path", "format", "version", "sha256", "bytes", "private"], `deliverable record ${index}`);
+    if (typeof row.id !== "string" || !ID.test(row.id) || ids.has(row.id)) throw new Error(`deliverable record ${index}: expected a distinct hub id`);
+    ids.add(row.id);
+    if (typeof row.sha256 !== "string" || !SHA256.test(row.sha256)) throw new Error(`deliverable record ${index}: expected a sha256`);
+    if (typeof row.bytes !== "number" || !Number.isSafeInteger(row.bytes) || row.bytes < 0 || row.bytes > DELIVERABLE_LIMITS.fileBytes) throw new Error(`deliverable record ${index}: expected a bounded size`);
+    if (typeof row.format !== "string" || !FORMAT.test(row.format)) throw new Error(`deliverable record ${index}: expected a format label`);
+    if (row.version !== undefined && (typeof row.version !== "string" || !VERSION.test(row.version))) throw new Error(`deliverable record ${index}: expected a version label`);
+    if (row.private !== undefined && row.private !== true) throw new Error(`deliverable record ${index}: private is true or absent`);
+    const path = deliverablePath(row.path);
+    if (row.id !== deliverableId(path, row.format)) throw new Error(`deliverable record ${index}: the id does not match its path and format`);
+    return { id: row.id, path, format: row.format, ...(row.version !== undefined ? { version: row.version } : {}), sha256: row.sha256, bytes: row.bytes, ...(row.private === true ? { private: true as const } : {}) };
+  });
+}
+
+/** The records as another peer may see them: a private record, or one whose path matches a PII pattern, shows no path, whatever else is shown. */
+export function publicDeliverables(records: readonly DeliverableRecord[] | undefined, screen: (text: string) => boolean): DeliverableRecord[] | undefined {
+  if (!records?.length) return undefined;
+  return records.map(record => {
+    const { path, ...rest } = record;
+    return path !== undefined && !record.private && screen(path) ? { ...rest, path } : { ...rest, private: true as const };
+  });
+}
+
+type Entry = { event: string; deliverables?: DeliverableRecord[] };
+/** What the newest `done`, `done (checking)` or lifecycle record said was delivered. An approval's own copy is not a delivery. */
+export function latestDeliverables(history: readonly Entry[]): DeliverableRecord[] | undefined {
+  for (let i = history.length - 1; i >= 0; i--) if (history[i]!.event !== "approved" && history[i]!.deliverables?.length) return history[i]!.deliverables;
+  return undefined;
+}
+/** What the newest approval bound: the bytes that were reviewed and approved. */
+export function approvedDeliverables(history: readonly Entry[]): DeliverableRecord[] | undefined {
+  for (let i = history.length - 1; i >= 0; i--) if (history[i]!.event === "approved" && history[i]!.deliverables?.length) return history[i]!.deliverables;
+  return undefined;
+}

package/src/hub/delivery-journal.ts

@@ -335,6 +335,7 @@ export class DeliveryJournal {
       if (!resolutionColumns.some((column) => column.name === "original_ids")) this.db.run("ALTER TABLE resolution_history ADD COLUMN original_ids TEXT NOT NULL DEFAULT '[]'");
       this.db.run("CREATE INDEX IF NOT EXISTS resolution_retry_peer ON resolution_history(project_id, peer, action)");
       this.db.run("CREATE INDEX IF NOT EXISTS deliveries_peer ON deliveries(project_id, peer, state)");
+      this.db.run("CREATE INDEX IF NOT EXISTS deliveries_pending ON deliveries(project_id, created_at, id, peer) WHERE state IN ('queued', 'dispatching', 'accepted', 'needs_review')");
     })();
   }
   private recoverRetryHistory(meta: Record<string, unknown>): void {
@@ -740,6 +741,19 @@ export class DeliveryJournal {
       .get(id, this.projectId) as Record<string, unknown> | null;
     return row ? parseDelivery(row) : undefined;
   }
+  /** Hot roster reads never materialize completed envelope history. */
+  pendingPeers(): string[] {
+    this.ensureOpen();
+    const rows = this.db.query("SELECT DISTINCT peer FROM deliveries WHERE project_id = ? AND state IN ('queued', 'dispatching', 'accepted', 'needs_review') ORDER BY peer").all(this.projectId) as { peer: unknown }[];
+    return rows.map(row => text(row.peer, "delivery peer", 256));
+  }
+  /** The queue needs a current revision, not the recovery snapshot's payloads. */
+  revision(): number {
+    this.ensureOpen();
+    const row = this.db.query("SELECT revision FROM delivery_meta WHERE project_id = ?").get(this.projectId) as { revision: unknown } | null;
+    if (!row) throw new Error("delivery journal metadata missing");
+    return integer(row.revision, "revision");
+  }
   list(peer?: string): JournalDelivery[] {
     this.ensureOpen();
     const rows = (
@@ -757,9 +771,11 @@ export class DeliveryJournal {
     ) as Record<string, unknown>[];
     return rows.map(parseDelivery);
   }
-  unresolved(peer: string): JournalDelivery[] {
+  unresolved(peer?: string): JournalDelivery[] {
     this.ensureOpen();
-    const rows = this.db.query("SELECT * FROM deliveries WHERE project_id = ? AND peer = ? AND state IN ('queued', 'dispatching', 'accepted', 'needs_review') ORDER BY created_at, id").all(this.projectId, peer) as Record<string, unknown>[];
+    const rows = (peer === undefined
+      ? this.db.query("SELECT * FROM deliveries WHERE project_id = ? AND state IN ('queued', 'dispatching', 'accepted', 'needs_review') ORDER BY created_at, id").all(this.projectId)
+      : this.db.query("SELECT * FROM deliveries WHERE project_id = ? AND peer = ? AND state IN ('queued', 'dispatching', 'accepted', 'needs_review') ORDER BY created_at, id").all(this.projectId, peer)) as Record<string, unknown>[];
     return rows.map(parseDelivery);
   }
   heldDeliveryHints(peer: string) {

package/src/hub/events.ts

@@ -18,6 +18,8 @@ export type HubEvent =
   | { type: "role"; peer?: string; task?: number; actor: string; stage: "prepared" | "assigned"; roles: { id: string; layer: "shipped" | "project"; hash: string }[] }
   /** A settings change (#269): the registry key, the bounded registry values before/after and their source; an optional person reason is sanitized and capped at 400 UTF-8 bytes. */
   | { type: "settings"; key: string; from: import("./settings.ts").SettingValue; to: import("./settings.ts").SettingValue; source: "dashboard" | "terminal"; undo?: boolean; reason?: string }
+  /** A structural config edit (#689): the file, key paths with short hashes of their values before and after (never a value), the file revisions and the person who made it. */
+  | { type: "config_edit"; file: "config.local.json" | "sdlc.toml"; paths: { path: string; before: string | null; after: string | null }[]; fileBefore: string; fileAfter: string; tier: 2 | 3; by: "person"; source: "dashboard" | "terminal"; backup?: string; reason?: string }
   | { type: "envelope"; id: string; from: string; to?: string[]; priority: string; hop: number; kind?: string; task?: string; bytes?: number; private?: boolean; dropped?: string }
   | { type: "overflow" | "undeliverable"; id: string; from: string; peer: string }
   | { type: "stale"; id: string; from: string; peer: string; task?: string }
@@ -51,7 +53,7 @@ export type HubEvent =
   | { type: "hook_stats"; peer: string; n: number; startupMs: number; hubMs: number; maxStartupMs: number }
   | { type: "cohort"; id: number; event: "formed" | "joined" | "lifted"; silent: boolean; tasks: number[]; owners: string[] }
   | ({ type: "tokens"; peer: string; n: number } & Partial<TaskAttribution>)
-  | ({ type: "usage"; peer: string; source: "omniroute" | "claude_transcript" | "codex_appserver"; id: string; reasoningTokens?: number; measuredAt?: string; requestedModel?: string; servedModel?: string; provider?: string; inputTokens?: number; outputTokens?: number; cacheReadTokens?: number; cacheWriteTokens?: number; totalTokens?: number } & Partial<TaskAttribution>)
+  | ({ type: "usage"; peer: string; source: "omniroute" | "claude_transcript" | "claude_result" | "codex_appserver" | "kimi_wire"; id: string; reasoningTokens?: number; measuredAt?: string; requestedModel?: string; servedModel?: string; provider?: string; inputTokens?: number; outputTokens?: number; cacheReadTokens?: number; cacheWriteTokens?: number; totalTokens?: number } & Partial<TaskAttribution>)
   | { type: "planning"; by: string; task?: number; release?: number; fields: string[]; revision: number }
   | { type: "task"; id: number; event: string; by: string; state: string; owner: string | null; reviewer: string | null; class: string; profile?: string; profileClass?: string; role?: string; roleIdentity?: { id: string; layer: "shipped" | "project"; hash: string }; pii: boolean; reason?: string; release?: number | null; priority?: number | null; plannedStart?: number | null; due?: number | null }
   | { type: "overlap"; task: number; owner: string; others: { task: number; owner: string; paths: string[]; symbols?: string[] }[] }

package/src/hub/hub-tools.ts

@@ -6,6 +6,16 @@ import { CONDUCTOR_START_PEERS, defaultPeerRoles } from "../adapters/registry.ts
 // The hub's task tools, defined once: the MCP server (Claude plugin, Kimi, Codex) and the local worker both read this.
 import { NOTE_KINDS } from "./envelope.ts";
 
+/** Restricted to the fixed current-child tools server, never an ordinary peer tool. */
+/** The fixed MCP surface of a current owned implementer child; independent of broader project roles. */
+export const IMPLEMENTER_HUB_TOOL_NAMES: readonly string[] = Object.freeze(["hub_task_accept", "hub_task_decline", "hub_task_done", "hub_checkpoint", "hub_send", "hub_task_show", "hub_task_propose", "hub_remember", "hub_inbox", "hub_permission_request"]);
+
+export const IMPLEMENTER_PERMISSION_TOOL = {
+  name: "hub_permission_request",
+  description: "Native permission prompt for this current owned child. The person allows once or denies; failure is deny.",
+  inputSchema: { type: "object", properties: { tool_name: { type: "string", maxLength: 128 }, input: { type: "object" }, tool_use_id: { type: "string", maxLength: 256 } }, required: ["tool_name", "input", "tool_use_id"], additionalProperties: false },
+};
+
 /** Shared communication rule for channel and tool-only sessions. */
 export const ACTIONABLE_MESSAGE_INSTRUCTION = "Do not use [FYI] for PR ready, done, submitted, ruling needed, blocker, or changed contract or path messages: each requires action from the recipient. Use [FYI] only for progress or information that needs no action. hub_task_done and hub_review already notify the assigned recipients; no duplicate hub_send chat is needed.";
 
@@ -18,6 +28,12 @@ const refs = {
   additionalProperties: false,
 } as const;
 const list = (description: string) => ({ type: "array", items: str, description }) as const;
+/** #509a: files a task delivered. The hub hashes them itself; there is no hash field, and one is refused. */
+const deliverablesSchema = {
+  type: "array", minItems: 1, maxItems: 16,
+  description: "files you delivered, as paths inside the project: the hub reads and hashes each file itself when you call this, a claimed hash is refused, and approval binds those hashes so a later edit reads as \"deliverable changed since review\". Works in a plain folder without git or a PR.",
+  items: { type: "object", properties: { path: { type: "string", description: "project-relative path, forward slashes" }, format: { type: "string", description: "lowercase label such as md, pdf, docx, csv" }, version: { type: "string", description: "optional label such as v2" } }, required: ["path", "format"], additionalProperties: false },
+} as const;
 const reviewFindings = {
   type: "array", maxItems: 64,
   description: "Head-bound findings; open Important findings carry across heads until explicitly fixed, false_positive or person-accepted; omission never settles them. Nits stay on their head. accepted is person-only and requires rationale. Nit count is capped by sdlc.max_nits (default 5).",
@@ -89,10 +105,10 @@ export const TASK_TOOLS: HubTool[] = [
   tool("hub_task_accept", "Take a task that was assigned to you, with your plan for it. Set refs.repo for work in another repository; acceptance may correct only that repository metadata.", { id, plan: acceptPlan, refs: { ...refs, properties: { repo: refs.properties.repo } } }, ["id"]),
   tool("hub_task_cancel", "Cancel unaccepted proposed/backlog work you proposed as its configured planner; accepted work is person-only. Keeps history and does not stop a native turn or delete files.", { id, reason: str, superseded_by: str, revision: { type: "integer", minimum: 0 } }, ["id", "reason"]),
   tool("hub_task_decline", "Pass on a task assigned to you; the hub offers it to the next peer. A plain decline is a lasting refusal: you are never offered this task again. Pass capacity: true when you only have no room right now: you are skipped for this move only, and a later reroute or planner pull may offer it to you again.", { id, reason: str, capacity: { type: "boolean" } }, ["id"]),
-  tool("hub_task_done", "Mark your task finished. It goes to its reviewer with your summary and refs; no duplicate hub_send chat is needed. When the project configures a check for its class, the hub runs it first and the result comes as a task message: a failed check keeps the task with you.", { id, summary: { type: "string", description: "what changed, why, and the check you ran with its result" }, refs }, ["id", "summary"]),
-  tool("hub_sdlc_record", "Record artifact ids or claimed local checks on your task. This grants no authority or external-check evidence. Only its owner/reviewer or the person may record; only its reviewer/person may name a reviewed head or phase checklist. Phase evidence refs are content hashes, not external verification.", { id, receipt: { type: "object", properties: { stage: { type: "string", enum: ["spec", "plan", "implement", "review", "verify", "merge", "release"] }, repo: str, issue: id, pr: id, localHead: str, localResult: { type: "string", enum: ["passed", "failed", "unknown"] }, reviewedHead: str, phase: { type: "object", properties: { id: str, head: str, tasks: { type: "array", maxItems: 64, items: { type: "object", properties: { id, after: { type: "array", maxItems: 16, items: id } }, required: ["id", "after"], additionalProperties: false } }, criteria: { type: "array", maxItems: 32, items: { type: "object", properties: { id: str, required: { type: "boolean" }, result: { type: "string", enum: ["verified", "failed", "unverified"] }, refs: { type: "array", maxItems: 8, items: str } }, required: ["id", "required", "result", "refs"], additionalProperties: false } } }, required: ["id", "tasks", "criteria"], additionalProperties: false } }, additionalProperties: false } }, ["id", "receipt"]),
+  tool("hub_task_done", "Mark your task finished. It goes to its reviewer with your summary and refs; no duplicate hub_send chat is needed. When the project configures a check for its class, the hub runs it first and the result comes as a task message: a failed check keeps the task with you.", { id, summary: { type: "string", description: "what changed, why, and the check you ran with its result" }, refs, deliverables: deliverablesSchema }, ["id", "summary"]),
+  tool("hub_sdlc_record", "Record artifact ids or claimed local checks on your task. This grants no authority or external-check evidence. Only its owner/reviewer or the person may record; only its reviewer/person may name a reviewed head or phase checklist. Phase evidence refs are content hashes, not external verification.", { id, receipt: { type: "object", properties: { deliverables: deliverablesSchema, stage: { type: "string", enum: ["spec", "plan", "implement", "review", "verify", "merge", "release"] }, repo: str, issue: id, pr: id, localHead: str, localResult: { type: "string", enum: ["passed", "failed", "unknown"] }, reviewedHead: str, phase: { type: "object", properties: { id: str, head: str, tasks: { type: "array", maxItems: 64, items: { type: "object", properties: { id, after: { type: "array", maxItems: 16, items: id } }, required: ["id", "after"], additionalProperties: false } }, criteria: { type: "array", maxItems: 32, items: { type: "object", properties: { id: str, required: { type: "boolean" }, result: { type: "string", enum: ["verified", "failed", "unverified"] }, refs: { type: "array", maxItems: 8, items: str } }, required: ["id", "required", "result", "refs"], additionalProperties: false } } }, required: ["id", "tasks", "criteria"], additionalProperties: false } }, additionalProperties: false } }, ["id", "receipt"]),
   tool("hub_task_list", "The task board. PII tasks show as [pii].", { state: { type: "string", enum: ["proposed", "in_progress", "in_review", "approved", "changes_requested", "cancelled"] }, ready: { type: "boolean", description: "only proposed tasks with nothing left to wait for" } }),
-  tool("hub_review", "Give your verdict on a task you were asked to review: map the changed signatures and call sites to the task's plan or detail, read the check result (hub_task_show has it, with the done summary), and list what is unmet. The verdict notifies the task owner; no duplicate hub_send chat is needed. Consecutive changes_requested verdicts (three by default, `tasks.escalate_after`) move the task to another peer.", { id, head: { type: "string", description: "full SHA actually reviewed; enforce binds approval to the current PR head" }, findings: reviewFindings, verdict: { type: "string", enum: ["approved", "changes_requested"] }, note: str, unmet: { type: "array", items: str, description: "each requirement of the plan or detail that the change does not meet" }, coverage: { type: "object", description: "the review brief's reviewable paths you read (reviewed) and any you did not (skipped, each with a reason); in enforce an approval must account for every one", properties: { reviewed: { type: "array", items: str }, skipped: { type: "array", items: { type: "object", properties: { path: str, reason: str }, required: ["path", "reason"] } } } } }, ["id", "verdict"]),
+  tool("hub_review", "Give your verdict on a task you were asked to review: map the changed signatures and call sites to the task's plan or detail, read the check result (hub_task_show has it, with the done summary), and list what is unmet. The verdict notifies the task owner; no duplicate hub_send chat is needed. Consecutive changes_requested verdicts (three by default, `tasks.escalate_after`) move the task to another peer.", { id, head: { type: "string", description: "full SHA actually reviewed; enforce binds approval to the current PR head" }, findings: reviewFindings, verdict: { type: "string", enum: ["approved", "changes_requested"] }, note: str, unmet: { type: "array", items: str, description: "each requirement of the plan or detail that the change does not meet; when the review request lists acceptance criteria, start an item with its id (\"AC1: what is missing\") so the verdict names it" }, coverage: { type: "object", description: "the review brief's reviewable paths you read (reviewed) and any you did not (skipped, each with a reason); in enforce an approval must account for every one", properties: { reviewed: { type: "array", items: str }, skipped: { type: "array", items: { type: "object", properties: { path: str, reason: str }, required: ["path", "reason"] } } } } }, ["id", "verdict"]),
   tool("hub_checkpoint", "Answer a checkpoint request from the hub (quota or context window pressure): what you were doing, what is half done, what whoever continues must know. Write the same to .agenthub/checkpoint.md first if you can.", { summary: str, request_id: { type: "string", description: "The request id supplied by a context checkpoint request; required for context checkpoints" } }, ["summary"]),
   tool("hub_memory_search", "Search daemon-scoped visible memory, fails first. Query <=200 UTF-8 bytes; default 8, max 20 lines; whole output <=4 KB. Incomplete excerpts are marked. No project argument.", { query: { type: "string", maxLength: 200, description: "At most 200 UTF-8 bytes, enforced by the daemon" }, limit: { type: "integer", minimum: 1, maximum: 20 } }, ["query"]),
   tool("hub_memory_show", "Read up to 8 visible memory ids or unique prefixes (6..64 UTF-8 bytes each). Original ids redirect; unavailable ids share one refusal. Whole output <=8 KB.", { ids: { type: "array", minItems: 1, maxItems: 8, items: { type: "string", minLength: 6, maxLength: 64, description: "6 to 64 UTF-8 bytes" } } }, ["ids"]),
@@ -104,7 +120,8 @@ export const TASK_TOOLS: HubTool[] = [
 export const PLANNER_REVIEW_TOOLS: HubTool[] = [
   tool("hub_planner_groom", "Read a bounded planner grooming digest of dependencies, repository-scoped overlaps, WIP and blockers. No board change; unavailable evidence stays unknown.", {}),
   tool("hub_plan_review", "Record a planner review against the task planning revision and host-read issue edit time. Configured planner or person only; never accepts caller issue timestamps.", { id, revision: { type: "integer", minimum: 0 }, reason: { ...str, maxLength: 1000 }, ...costPlanProperties }, ["id", "revision", "reason"]),
-  tool("hub_sdlc_costs", "Read bounded review and CI cost metrics for linked merged PRs. Planner/person only; metadata only, no board writes. S7 owns automatic band proposals.", { repo: str }),
+  tool("hub_sdlc_costs", "Read bounded review and CI cost metrics for linked merged PRs. Planner/person only; metadata only, no board writes.", { repo: str }),
+  tool("hub_sdlc_metrics", "Read SDLC metrics from board history: time from acceptance to plan, first review and merge, first-pass approval and rework rounds, first-pass CI and same-head reruns, stale-head re-reviews, stalls, and the control band tiers when sdlc.toml sets [bands]. Planner/person only; read-only, no model and no GitHub issue.", { since: str }),
   tool("hub_backlog_return_untouched", "Return accepted but untouched work to the backlog with its history and planning retained. Refuses execution/branch/commit evidence; planner or person only.", { id, revision: { type: "integer", minimum: 0 }, reason: { ...str, maxLength: 1000 } }, ["id", "revision", "reason"]),
 ];
 TASK_TOOLS.push(...PLANNER_REVIEW_TOOLS);

package/src/hub/instances.ts

@@ -146,19 +146,30 @@ export function validateInstances(raw: unknown, catalog: ProjectAdapterCatalog):
     if (freshReviewer && entry.permission_mode) return fail(`${path}.permission_mode`, "a fresh reviewer has a fixed read-only policy");
     // An external instance runs only in the person's terminal; its definition bounds the declared roles.
     const external = definition.instances?.mode === "external";
-    const runtime = freshReviewer ? definition.reviewerVariant ?? definition : definition;
+    const headlessWriter = entry.start_mode?.value === "headless" && !!definition.headlessVariant && declaredRoles.includes("implementer") && declaredRoles.every(role => role === "implementer" || role === "verifier");
+    if (headlessWriter && !entry.worktree) return fail(`${path}.worktree`, "a headless implementer needs its own worktree");
+    if (headlessWriter && entry.permission_mode && entry.permission_mode.value !== "ask" && entry.permission_mode.value !== "ask-when-needed") return fail(`${path}.permission_mode`, "a headless implementer permits only ask or ask-when-needed");
+    const runtime = freshReviewer ? definition.reviewerVariant ?? definition : headlessWriter ? definition.headlessVariant! : definition;
     const unavailableReviewer = freshReviewer && !!(definition.reviewerVariant ?? definition).reviewer?.unavailable;
     if (!unavailableReviewer && runtime.instances?.mode !== "external" && !supportsHeadlessInstances(runtime)) return fail(`${path}.kind`, definition.reviewerVariant ? 'unsupported; this kind only declares headless reviewer instances with roles exactly ["reviewer"]' : "unsupported; explicit external instance policy or a headless instance policy with a headless factory is required");
+    if (declaredRoles.includes("planner") && definition.projection?.plannerEligible !== true) return fail(`${path}.roles`, "this kind cannot plan");
     if (external) {
       const declared = entry.roles ? roles(entry.roles.value, `${path}.roles`) : [];
       // #223: a headless one is the kind's reviewer variant, one fresh hub-run session per review request.
-      if (entry.start_mode && definition.reviewerVariant) {
+      if (headlessWriter) {
+        // Runtime policy and worktree/permission checks above govern this builtin-only writer variant.
+      } else if (entry.start_mode && definition.reviewerVariant) {
+        const reviewerRoles = declared.length === 1 && declared[0] === "reviewer";
+        if (!reviewerRoles) return fail(`${path}.roles`, "a headless channel-kind instance is a reviewer: roles must be exactly [\"reviewer\"]");
         if (entry.worktree) return fail(path, "a headless reviewer reads the project checkout: worktree is not supported");
-        if (declared.length !== 1 || declared[0] !== "reviewer") return fail(`${path}.roles`, "a headless channel-kind instance is a reviewer: roles must be exactly [\"reviewer\"]");
       } else {
-        if (entry.start_mode || entry.worktree) return fail(path, "a channel instance starts only from the person's terminal (ahub <kind> --as <id>): start_mode and worktree are not supported; a headless reviewer declares roles [\"reviewer\"] and start_mode \"headless\"");
+        if (entry.start_mode) return fail(`${path}.start_mode`, "a channel instance starts only from the person's terminal (ahub <kind> --as <id>); a headless reviewer declares roles [\"reviewer\"] and start_mode \"headless\"");
         const allowed = definition.instances?.roles ?? definition.roles;
-        if (!declared.length || declared.some(role => !allowed.includes(role))) return fail(`${path}.roles`, "a channel instance must declare its roles: reviewer and/or planner");
+        if (!declared.length || declared.some(role => !allowed.includes(role))) return fail(`${path}.roles`, `a channel instance must declare its roles within: ${allowed.join(", ")}`);
+        // #525 R1: an implementer or verifier writes, so it needs its own worktree; a planner or reviewer reads the project checkout.
+        const writes = declared.includes("implementer") || declared.includes("verifier");
+        if (writes && !entry.worktree) return fail(`${path}.worktree`, "an implementer or verifier channel instance needs its own worktree");
+        if (!writes && entry.worktree) return fail(`${path}.worktree`, "a planner or reviewer channel instance reads the project checkout: worktree is not supported");
       }
     } else {
       const allowed = runtime.instances?.roles;
@@ -217,5 +228,7 @@ export function effectiveInstanceRoles(id: string, declarations: InstancesConfig
   if (!definition) throw new Error(`${id}: no declared native instance`);
   const declaration = declarations && Object.hasOwn(declarations, id) ? declarations[id] : undefined;
   const ownRoles = (key: string): readonly string[] | undefined => Object.hasOwn(policyRoles, key) ? policyRoles[key] : undefined;
-  return [...(declaration?.roles ?? ownRoles(id) ?? ownRoles(definition.kind) ?? definition.roles)];
+  const roles = declaration?.roles ?? ownRoles(id) ?? ownRoles(definition.kind) ?? definition.roles;
+  // #525 R1: a roles entry keyed by an instance id skips loadConductorPolicy's kind check, so planner is gated here too.
+  return roles.filter(role => role !== "planner" || definition.projection?.plannerEligible === true);
 }

package/src/hub/kimi-usage.ts

@@ -0,0 +1,144 @@
+import { KimiWireReader, kimiCountedTokens, type KimiWireReason, type KimiWireRow } from "../adapters/kimi-wire-usage.ts";
+import { TokenWindow } from "./token-window.ts";
+
+/**
+ * The hub's own count of Kimi's consumption (#285 phase 2): the wire-log rows of the session the adapter owns become `usage` and
+ * `tokens` events and a rolling 5 h window against `budget.kimi_tokens_5h`. Read at a turn end and when a `usage_update` arrives:
+ * no watcher, no timer. The ports keep the event log, the budget and the clock in the daemon.
+ */
+export const KIMI_WINDOW_MS = 5 * 3_600_000;
+/** A turn's rows are written after it starts: a row older than the hub's first sight of the session (less this slack) is history. */
+const FLOOR_SLACK_MS = 1000;
+const PASSES = 16;
+/** Failures a retry can cure: the log was not there yet, or was cut mid-write. Anything else says the count no longer matches the log. */
+const TRANSIENT: ReadonlySet<KimiWireReason> = new Set(["no-index", "io-error", "partial-line"]);
+
+export interface KimiUsagePorts {
+  /** Kimi's data home. */
+  home: string;
+  /** Per-call byte bound of the reader (its default otherwise); a test shrinks it to force several passes. */
+  maxBytes?: number;
+  now(): number;
+  /** `budget.kimi_tokens_5h`, read live: 0 turns the window off, never the events. */
+  ceiling(): number;
+  /** The adapter's own session id, undefined when none is bound. */
+  session(peer: string): string | undefined;
+  /** One usage event and its counted tokens (`counted` is the one rule in `kimiCountedTokens`). */
+  record(peer: string, row: KimiWireRow, counted: number): void;
+  /** The window as a reading: `used` is not clamped here. */
+  report(peer: string, window: { used: number; resetsAt: number; ceiling: number }): void;
+  /** The count cannot be trusted now: the peer's `tokens` reading is dropped, so it shows unknown rather than a short number. */
+  forget(peer: string): void;
+  /** One line per peer and reason; carries no path, id or text from the log. */
+  notice(line: string): void;
+}
+
+interface Bound { session: string; reader: KimiWireReader; floor: number; unknown?: KimiWireReason; noticed?: KimiWireReason }
+
+export class KimiUsage {
+  private readonly bound = new Map<string, Bound>();
+  private readonly window = new TokenWindow(KIMI_WINDOW_MS);
+  private readonly seen = new Set<string>();
+  /** A log that stopped matching the count leaves the window short of the truth until its rows age out. */
+  private readonly taintedUntil = new Map<string, number>();
+
+  constructor(private readonly ports: KimiUsagePorts) {}
+
+  /** Rows an earlier hub run already recorded: never counted twice, and still inside the window. */
+  seed(rows: { id: string; at: number; counted: number }[]): void {
+    for (const row of rows) {
+      this.seen.add(row.id);
+      if (row.counted > 0 && this.ports.now() - row.at <= KIMI_WINDOW_MS) this.window.add(row.at, row.counted);
+    }
+  }
+
+  /** The peer went offline: its log is no longer read, so an unreadable state of it must not hold the other peers' figure unknown. */
+  drop(peer: string): void { this.bound.delete(peer); }
+
+  /** A new window: the old counts would pause the peer again at once (after a budget resume). */
+  reset(): void { this.window.reset(); this.taintedUntil.clear(); }
+
+  /** Called when a turn starts. It only binds the session and fixes the history floor: nothing is read here, and what the log already holds is not this hub's to count. */
+  turnStarted(peer: string): void { this.bind(peer); }
+
+  private bind(peer: string): Bound | undefined {
+    const session = this.ports.session(peer);
+    if (!session) return undefined;
+    const held = this.bound.get(peer);
+    if (held?.session === session) return held;
+    const next: Bound = { session, reader: new KimiWireReader({ home: this.ports.home, sessionId: session, ...(this.ports.maxBytes ? { maxBytes: this.ports.maxBytes } : {}) }), floor: this.ports.now() - FLOOR_SLACK_MS };
+    this.bound.set(peer, next);
+    return next;
+  }
+
+  collect(peer: string): void {
+    const bound = this.bind(peer);
+    if (!bound) return;
+    let added = 0, more = false;
+    for (let pass = 0; pass < PASSES; pass++) {
+      const read = bound.reader.read();
+      // Each successful pass has already moved the reader's offsets: its rows are recorded now, before a later pass can fail, or they would
+      // never be read again and the count would be short.
+      if (read.status === "unknown") { this.unknown(peer, bound, read.reason); return; }
+      added += this.record(peer, bound, read.rows);
+      more = read.more;
+      if (!more) break;
+    }
+    const recovered = bound.unknown !== undefined;
+    bound.unknown = undefined;
+    // ponytail: PASSES x the reader's per-call bound. A longer unread backlog (a resumed session with a huge log) is finished by the next
+    // call, and no figure is reported until it is: a window that is still catching up would be short. Upgrade: seek to the end at bind.
+    if (!more && (added > 0 || recovered)) this.report(peer);
+  }
+
+  private record(peer: string, bound: Bound, rows: KimiWireRow[]): number {
+    let added = 0;
+    const now = this.ports.now();
+    for (const row of rows) {
+      if (this.seen.has(row.id) || row.at < bound.floor) continue;
+      this.seen.add(row.id);
+      const counted = kimiCountedTokens(row);
+      this.ports.record(peer, row, counted);
+      this.window.add(Math.min(row.at, now), counted);
+      added += counted;
+    }
+    return added;
+  }
+
+  private unknown(peer: string, bound: Bound, reason: KimiWireReason): void {
+    bound.unknown = reason;
+    try { this.ports.forget(peer); } catch { /* the reading ages out on its own */ }
+    if (!TRANSIENT.has(reason)) this.taintedUntil.set(peer, this.ports.now() + KIMI_WINDOW_MS);
+    if (bound.noticed === reason) return;
+    bound.noticed = reason;
+    try { this.ports.notice(`kimi usage unknown (${reason}): the hub counts no Kimi tokens it cannot read cleanly`); } catch { /* a notice never costs a turn */ }
+  }
+
+  /** The window as a reading, only while every Kimi peer's log reads cleanly: otherwise the figure is unknown, never a short count. */
+  private report(peer: string): void {
+    const ceiling = this.ports.ceiling(), now = this.ports.now();
+    if (!ceiling) return;
+    for (const state of this.bound.values()) if (state.unknown) return;
+    for (const until of this.taintedUntil.values()) if (now < until) return;
+    const oldest = this.window.oldest(now);
+    this.ports.report(peer, { used: this.window.sum(now) / ceiling, resetsAt: (oldest ?? now) + KIMI_WINDOW_MS, ceiling });
+  }
+}
+
+/**
+ * The rows an earlier run recorded, from its `usage` events: their ids are never counted again, and the recent ones refill the window.
+ * Only rows recorded after the last `resumedAt` (the newest `budget_resume` of a soft-token peer) refill it: a resume starts a new window
+ * (`reset`), and that is not persisted anywhere else, so a restart would otherwise bring the pre-resume rows back and pause the peer again.
+ */
+export function kimiSeedRows(events: readonly { type: string; source?: unknown; id?: unknown; measuredAt?: unknown; at?: unknown; inputTokens?: unknown; cacheWriteTokens?: unknown; outputTokens?: unknown }[], resumedAt = 0): { id: string; at: number; counted: number }[] {
+  const n = (value: unknown): number => typeof value === "number" && Number.isSafeInteger(value) && value >= 0 ? value : 0;
+  return events.flatMap(e => {
+    if (e.type !== "usage" || e.source !== "kimi_wire" || typeof e.id !== "string") return [];
+    const measured = Date.parse(typeof e.measuredAt === "string" ? e.measuredAt : typeof e.at === "string" ? e.at : "");
+    const recorded = Date.parse(typeof e.at === "string" ? e.at : "");
+    if (!Number.isFinite(measured)) return [];
+    // A row before the resume keeps its id (never recounted) and counts for nothing: `counted: 0` leaves the window alone.
+    const counted = Number.isFinite(recorded) && recorded <= resumedAt ? 0 : kimiCountedTokens({ inputOther: n(e.inputTokens), inputCacheCreation: n(e.cacheWriteTokens), output: n(e.outputTokens) });
+    return [{ id: e.id, at: measured, counted }];
+  });
+}

package/src/hub/manager.ts

@@ -8,7 +8,7 @@ import { spawn } from "node:child_process";
 import { ControlClient, PROTOCOL, RECOVERY_SOURCE_PROTOCOLS } from "./control-client.ts";
 import { Registry, type Project } from "./registry.ts";
 import { hubHome } from "./project.ts";
-import { startDashboard } from "./ui.ts";
+import { startDashboard, dashboardView } from "./ui.ts";
 import { projectChain } from "@staix/agent-mem";
 import type { ProjectInspection } from "./lifecycle.ts";
 import { MAX_COMMAND_MS } from "../cli/terminal-recovery.ts";
@@ -155,7 +155,7 @@ export async function startManager(options: ManagerOptions = {}): Promise<Manage
           return { ok: true };
         }
         // The settings actions (#269) reach the project hub as an ordinary session's: this dashboard opens no settings session.
-        if (!["snapshot", "send", "pause", "resume", "permit", "propose", "assign", "backlog_pull", "backlog_return", "planning", "planning_undo", "planner_pull", "backlog_split", "release_new", "release_change", "setting", "setting_undo", "setting_preview", "setting_reload", "start_peer", "sdlc_queue", "sdlc_release"].includes(String(input.action))) return { ok: false, error: "invalid dashboard action" };
+        if (!["snapshot", "send", "pause", "resume", "permit", "propose", "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"].includes(String(input.action))) return { ok: false, error: "invalid dashboard action" };
         client = await ControlClient.connect(project.stateDir, { role: "console", projectId: project.id, projectRoot: project.root, instanceId: input.instanceId });
         const deliveryRead = input.action === "sdlc_queue" || input.action === "sdlc_release";
         let nominalMs = 10_000;
@@ -164,7 +164,7 @@ export async function startManager(options: ManagerOptions = {}): Promise<Manage
         else if (deliveryRead) nominalMs = 30_000;
         const timeoutMs = options.forwardTimeoutMs?.(String(input.action), nominalMs) ?? nominalMs;
         const result = await client.request(input.action === "snapshot"
-          ? { t: "ui_snapshot", after: input.after ?? 0, ...(input.memory !== undefined ? { memory: input.memory } : {}) }
+          ? { t: "ui_snapshot", after: input.after ?? 0, ...(input.memory !== undefined ? { memory: input.memory } : {}), ...(dashboardView(input.view) ? { view: input.view } : {}) }
           : { t: "ui_action", action: input, instanceId: input.instanceId }, timeoutMs);
         // ControlClient resolves its deadline as this exact sentinel; a hub refusal stays a known failure.
         if (["start_peer", "backlog_split"].includes(String(input.action)) && result.ok === false && result.error === `no answer from the hub within ${Math.round(timeoutMs / 1000)} s`) {