@staix/agent-hub 0.16.0 → 0.18.0

package/src/adapters/reviewer-mcp.ts

@@ -10,6 +10,8 @@ export interface ReviewerMcpOptions {
   tools: readonly HubTool[];
   /** Fixed host port; the host still applies Tasks' role, privacy, head and running-child fences. */
   call(name: ReviewerToolName, args: Record<string, unknown>): Promise<string>;
+  /** Diagnostic metadata only; never tool arguments or successful result text. */
+  onTool?(name: ReviewerToolName, refusal?: string): void;
 }
 const NAMES: readonly ReviewerToolName[] = ["hub_review", "hub_task_show"];
 const BODY_CAP = 256 * 1024, RESULT_CAP = 4 * 1024 * 1024;
@@ -60,20 +62,24 @@ export function createReviewerMcpSession(options: ReviewerMcpOptions): ReviewerM
       if (!record(body.params)) return error("tool parameters required");
       const name = body.params.name;
       if (name !== "hub_review" && name !== "hub_task_show") return error("tool unavailable");
+      const observe = (refusal?: string) => { try { options.onTool?.(name, refusal); } catch { /* Diagnostics never change tool authority or results. */ } };
+      const refuse = (message: string, code?: number) => { observe(message); return error(message, code); };
+      observe();
       let args = body.params.arguments;
-      if (typeof args === "string") { try { args = JSON.parse(args); } catch { return error("invalid tool arguments"); } }
-      if (!record(args) || args.id !== options.task || !Number.isSafeInteger(args.id)) return error("tool is bound to its review task");
-      if (++calls > 64) return error("review tool call limit", -32002);
-      if (!current()) return error("review authority ended", -32001);
+      if (typeof args === "string") { try { args = JSON.parse(args); } catch { return refuse("invalid tool arguments"); } }
+      if (!record(args) || args.id !== options.task || !Number.isSafeInteger(args.id)) return refuse("tool is bound to its review task");
+      if (++calls > 64) return refuse("review tool call limit", -32002);
+      if (!current()) return refuse("review authority ended", -32001);
       try {
         const result = await options.call(name, args);
         // Tasks.review rechecks its captured authority through its final write. A successful verdict
         // ends that in_review binding itself; acknowledge its committed result, never fresh reads.
-        if (name !== "hub_review" && !current()) return error("review authority ended", -32001);
-        if (Buffer.byteLength(result) > RESULT_CAP) return error("tool result exceeds review limit");
+        if (name !== "hub_review" && !current()) return refuse("review authority ended", -32001);
+        if (Buffer.byteLength(result) > RESULT_CAP) return refuse("tool result exceeds review limit");
         return reply({ content: [{ type: "text", text: result }] });
       } catch (failure) {
         // The same host tool boundary supplies refusals to the released MCP transport.
+        observe(failure instanceof Error ? failure.message : "review tool refused");
         const message = failure instanceof Error ? sanitize(failure.message).slice(0, 4000) : "review tool refused";
         return reply({ isError: true, content: [{ type: "text", text: message }] });
       }

package/src/adapters/reviewer-print.ts

@@ -1,10 +1,10 @@
 import type { ChildProcess } from "node:child_process";
 import { OwnedPrintChild, PrintChildCleanupError } from "./claude-print-child.ts";
 import { randomUUID } from "node:crypto";
-import { HUB, frame } from "../hub/envelope.ts";
+import { HUB, frame, sanitize } from "../hub/envelope.ts";
 import { BasePeer } from "../hub/peers.ts";
 import type { Envelope } from "../hub/envelope.ts";
-import type { ReviewerMcpSession } from "./reviewer-mcp.ts";
+import type { ReviewerMcpSession, ReviewerToolName } from "./reviewer-mcp.ts";
 
 /** #722: the closed list of legs a reviewer's per-review start can fail on. A class names a leg, never a path, content or token. */
 export const REVIEWER_CAUSE_CLASSES = ["version", "binary", "mcp_inventory", "plugins_hooks_apps", "sandbox_proof", "credential_root", "timeout", "unknown"] as const;
@@ -27,6 +27,10 @@ export function reviewerUnavailableReason(cause: ReviewerCauseClass, detail?: st
 export class ReviewerUnavailableError extends Error {
   constructor(message: string, readonly causeClass: ReviewerCauseClass, readonly detail?: string) { super(message); }
 }
+/** A refused request says nothing about the reviewer's native isolation or ability to start. */
+class ReviewerAdmissionError extends Error {
+  constructor(readonly reason: "stale_binding" | "policy_changed") { super("review admission changed"); }
+}
 
 export interface ReviewerPrintUsage { input_tokens?: number; output_tokens?: number; cache_creation_input_tokens?: number; cache_read_input_tokens?: number }
 export interface ReviewerIsolationReceipt {
@@ -76,6 +80,31 @@ export interface ReviewerBackend {
   prepare(context: ReviewerPrepareContext): Promise<ReviewerLaunch | { unavailable: string; causeClass?: ReviewerCauseClass; detail?: string }>;
   usage?(event: unknown): ReviewerPrintUsage | undefined;
   failure?(event: unknown): "quota" | undefined;
+  /** Structured native MCP events only, never model messages or tool arguments. */
+  toolTrace?(event: unknown): ReviewerToolTrace | undefined;
+}
+export interface ReviewerToolTrace { tool: ReviewerToolName; refusal?: string }
+export interface ReviewerNoVerdict extends ReviewerReviewBinding {
+  task: number;
+  exitCode: number | null;
+  reviewCalled: boolean;
+  lastTool?: ReviewerToolName;
+  refusal?: string;
+  /** Preserve the first full host error across later truncated native echoes; differing host errors stay uncertain. */
+  hostRefusal?: string;
+  refusalUncertain?: true;
+}
+type ReviewerTraceState = Pick<ReviewerNoVerdict, "reviewCalled" | "lastTool" | "refusal" | "hostRefusal" | "refusalUncertain">;
+/** Host-produced receipt reason: an unconfirmed normal review fallback still needs a person's settlement. */
+export const REVIEWER_FALLBACK_UNCONFIRMED = "reviewer fallback unconfirmed: ";
+/** `safeRefusal` must have passed the host's complete privacy/secret screen before truncation. */
+export function reviewerNoVerdictLine(peer: string, diagnostic: ReviewerNoVerdict, safeRefusal?: string, withheld = false): string {
+  const prefix = `[${peer}] review of task #${diagnostic.task}: no verdict exit=${diagnostic.exitCode ?? "unknown"}; `;
+  if (withheld) return prefix + "diagnostic withheld";
+  const detail = diagnostic.lastTool ? `last hub tool ${diagnostic.lastTool}; ${diagnostic.reviewCalled ? "hub_review called" : "no hub_review call"}` : "no hub_review call";
+  const line = safeRefusal === undefined ? undefined : Array.from(sanitize(safeRefusal).replace(/\s+/g, " "))
+    .filter(char => !/\p{C}/u.test(char)).slice(0, 240).join("");
+  return prefix + detail + (diagnostic.refusal === undefined && diagnostic.hostRefusal === undefined ? "" : `; refusal: ${line ?? "withheld"}`);
 }
 export interface ReviewerFailure {
   task: number;
@@ -99,7 +128,9 @@ export interface ReviewerPrintOptions {
   facts?(env: Envelope): string | undefined;
   verdictSince(task: number, since: number): boolean;
   onUsage?(usage: ReviewerPrintUsage, task: number): void;
-  onUnavailable?(failure: ReviewerFailure, current: () => boolean): void | Promise<void>;
+  /** True confirms that the host re-offered the current review; void/false retains uncertainty. */
+  onUnavailable?(failure: ReviewerFailure, current: () => boolean): boolean | void | Promise<boolean | void>;
+  onNoVerdict?(diagnostic: ReviewerNoVerdict, current: () => boolean): void;
   log?(line: string): void;
   taskMcp?(task: number, current: () => boolean): ReviewerMcpSession;
   /** Synchronous host task/privacy/policy fence, checked again after awaited preparation. */
@@ -139,6 +170,24 @@ export class ReviewerPrintPeer extends BasePeer {
   reviewing: number | undefined;
   private reviewSeq = 0;
   private runningBinding: { task: number; binding: ReviewerReviewBinding } | undefined;
+  private activeTrace: { task: number; generation: number; value: ReviewerTraceState } | undefined;
+  /** Host observations are diagnostic data and never grant tool or verdict authority. */
+  recordToolTrace(task: number, trace: ReviewerToolTrace): void {
+    if (trace.tool !== "hub_review" && trace.tool !== "hub_task_show") return;
+    const active = this.activeTrace, binding = this.runningBinding;
+    if (!active || active.task !== task || active.generation !== this.generation || this.reviewing !== task || binding?.task !== task || this.opts.bindingCurrent?.(task, binding.binding) === false) return;
+    if (typeof trace.refusal === "string") {
+      if (active.value.hostRefusal === undefined) active.value.hostRefusal = trace.refusal;
+      else if (active.value.hostRefusal !== trace.refusal) active.value.refusalUncertain = true;
+    }
+    this.observeTool(active.value, trace);
+  }
+  private observeTool(value: ReviewerTraceState, trace: ReviewerToolTrace): void {
+    if (trace.tool !== "hub_review" && trace.tool !== "hub_task_show") return;
+    value.lastTool = trace.tool;
+    value.refusal = typeof trace.refusal === "string" ? trace.refusal : undefined;
+    if (trace.tool === "hub_review") value.reviewCalled = true;
+  }
   /** Immutable envelope identity of this running child, never the board's later head. */
   reviewBinding(task: number): ReviewerReviewBinding | undefined {
     return this.reviewing === task && this.runningBinding?.task === task ? this.runningBinding.binding : undefined;
@@ -234,10 +283,20 @@ export class ReviewerPrintPeer extends BasePeer {
       if (task === undefined) continue; // a withdrawal or other notice: nothing to review
       if (env.private) { failure = { state: "needs_review", reason: "a private review is the person's, never a cloud reviewer's" }; break; }
       const since = Date.now();
-      let result: { code: number | null; quota: boolean };
+      let result: { code: number | null; quota: boolean; trace: ReviewerTraceState };
       try { result = await this.review(env, task, generation); }
       catch (error) {
         if (generation !== this.generation) return;
+        if (error instanceof ReviewerAdmissionError) {
+          this.opts.log?.(`[${this.id}] review of task #${task} skipped: ${error.reason === "stale_binding" ? "stale binding" : "review policy changed"}`);
+          if (error.reason === "policy_changed") {
+            missing.push(task);
+            const target = batch.targets[index];
+            if (target) reroute.push({ ...target, cause: "no_verdict" });
+          }
+          batch.next = index + 1;
+          continue;
+        }
         if (error instanceof PrintChildCleanupError) {
           // Unavailable until a stop confirms the group gone: no new review runs beside the survivors.
           this.opts.log?.(`[${this.id}] review of task #${task}: ${error.message}`);
@@ -259,6 +318,11 @@ export class ReviewerPrintPeer extends BasePeer {
       if (!recorded) {
         missing.push(task);
         const target = batch.targets[index];
+        const diagnostic = { ...target, task, exitCode: result.code, ...result.trace };
+        try {
+          if (this.opts.onNoVerdict) this.opts.onNoVerdict(diagnostic, () => generation === this.generation);
+          else this.opts.log?.(reviewerNoVerdictLine(this.id, diagnostic));
+        } catch { this.opts.log?.(reviewerNoVerdictLine(this.id, { task, exitCode: result.code, reviewCalled: false }, undefined, true)); }
         if (target) reroute.push({ ...target, cause: result.quota ? "quota" : "no_verdict" });
         if (result.quota) {
           reroute.push(...remainingFailures(batch, index + 1, "quota"));
@@ -267,25 +331,30 @@ export class ReviewerPrintPeer extends BasePeer {
         }
       }
       batch.next = index + 1;
-      if (result.code !== 0) this.opts.log?.(`[${this.id}] review of task #${task} exited ${result.code}`);
+      if (recorded && result.code !== 0) this.opts.log?.(`[${this.id}] review of task #${task} exited ${result.code}`);
     }
     if (generation !== this.generation) return;
     this.clearWatchdog(); // the child is gone; keep busy while the host settles the remaining walk
-    this.settle(failure?.state ?? (missing.length ? "needs_review" : "completed"), failure?.reason ?? (missing.length ? `no verdict recorded for task ${missing.map(id => `#${id}`).join(", ")}` : undefined));
-    await this.reportFailures(reroute, generation);
+    const reoffered = await this.reportFailures(reroute, generation);
+    if (generation !== this.generation) return;
+    const unresolved = missing.length > 0 && !reoffered;
+    const normalNoVerdict = !failure && reroute.length > 0 && reroute.every(value => value.cause === "no_verdict");
+    this.settle(failure?.state ?? (unresolved ? "needs_review" : "completed"), failure?.reason ?? (unresolved ? `${normalNoVerdict ? REVIEWER_FALLBACK_UNCONFIRMED : ""}no verdict recorded for task ${missing.map(id => `#${id}`).join(", ")}` : undefined));
     if (generation === this.generation) { this.batch = undefined; this.setState("idle"); }
   }
 
-  private async reportFailures(failures: readonly ReviewerFailure[], generation: number): Promise<void> {
+  private async reportFailures(failures: readonly ReviewerFailure[], generation: number): Promise<boolean> {
     const seen = new Set<string>();
+    let reoffered = true;
     for (const failed of failures) {
-      if (generation !== this.generation) return;
+      if (generation !== this.generation) return false;
       const identity = JSON.stringify([failed.task, failed.head, failed.flowRevision]);
       if (seen.has(identity)) continue;
       seen.add(identity);
-      try { await this.opts.onUnavailable?.(failed, () => generation === this.generation); }
-      catch { this.opts.log?.(`[${this.id}] reviewer fallback could not be recorded; inspect the task`); }
+      try { if (await this.opts.onUnavailable?.(failed, () => generation === this.generation) !== true) reoffered = false; }
+      catch { reoffered = false; this.opts.log?.(`[${this.id}] reviewer fallback could not be recorded; inspect the task`); }
     }
+    return reoffered;
   }
 
   private prepare(sessionId: string, input?: string, task?: number, mcpConfig?: string): Promise<ReviewerLaunch> {
@@ -313,14 +382,21 @@ export class ReviewerPrintPeer extends BasePeer {
     return done;
   }
 
-  private async review(env: Envelope, task: number, generation: number): Promise<{ code: number | null; quota: boolean }> {
-    if (this.opts.admit?.(env) === false) throw new Error("review admission changed");
+  private assertAdmission(env: Envelope, task: number, binding: ReviewerReviewBinding): void {
+    if (this.opts.bindingCurrent?.(task, binding) === false) throw new ReviewerAdmissionError("stale_binding");
+    if (this.opts.admit?.(env) === false) throw new ReviewerAdmissionError(this.opts.bindingCurrent?.(task, binding) === false ? "stale_binding" : "policy_changed");
+  }
+
+  private async review(env: Envelope, task: number, generation: number): Promise<{ code: number | null; quota: boolean; trace: ReviewerTraceState }> {
+    const revision=Number(env.refs?.reviewRevision);
+    const binding: ReviewerReviewBinding=Object.freeze({head:env.refs?.commit,flowRevision:Number.isSafeInteger(revision)&&revision>0?revision:undefined});
+    this.assertAdmission(env, task, binding);
     let facts: string | undefined;
     try { facts = this.opts.facts?.(env); } catch (error) { this.opts.log?.(`[${this.id}] review facts for task #${task} failed: ${(error as Error).message}`); }
     const input = `${frame(env)}${facts ? `\n\n${facts}` : ""}`;
     let launch: ReviewerLaunch | undefined;
-    const revision=Number(env.refs?.reviewRevision);
-    const binding: ReviewerReviewBinding=Object.freeze({head:env.refs?.commit,flowRevision:Number.isSafeInteger(revision)&&revision>0?revision:undefined});
+    const trace: ReviewerTraceState = { reviewCalled: false };
+    this.activeTrace = { task, generation, value: trace };
     const mcp = this.opts.backend.taskMcp ? this.opts.taskMcp?.(task, () => generation === this.generation && this.reviewToken(task) !== undefined && this.opts.bindingCurrent?.(task,binding) !== false) : undefined;
     let mcpClosed=false;
     const closeMcp=()=>{ if(mcpClosed)return; mcpClosed=true; mcp?.close(); if(this.reviewMcpClose===closeMcp)this.reviewMcpClose=undefined; };
@@ -330,7 +406,9 @@ export class ReviewerPrintPeer extends BasePeer {
     const release = () => releasing ??= Promise.resolve().then(() => launch?.cleanup?.()).then(() => {});
     try {
     launch = await this.prepare(randomUUID(), input, task, mcp?.config);
-    if (generation !== this.generation || this.opts.admit?.(env) === false || launch.current?.() === false) throw new ReviewerUnavailableError("reviewer isolation or admission changed before child spawn", launch.current?.() === false ? "binary" : "unknown");
+    if (generation !== this.generation) throw new ReviewerAdmissionError("stale_binding");
+    this.assertAdmission(env, task, binding);
+    if (launch.current?.() === false) throw new ReviewerUnavailableError("reviewer isolation changed before child spawn", "binary");
     this.receipt = launch.isolation;
     let quota = false;
     const child = new OwnedPrintChild({ peer: this.id, command: launch.command, args: launch.args,
@@ -343,6 +421,10 @@ export class ReviewerPrintPeer extends BasePeer {
         if (this.childCurrent) policyTimer = setInterval(() => { this.reviewToken(task); }, 100);
       },
       onFrame: event => {
+        try {
+          const observed = this.opts.backend.toolTrace?.(event);
+          if (observed && generation === this.generation) this.observeTool(trace, observed);
+        } catch { /* Optional trace metadata never changes review execution. */ }
         const usage = this.opts.backend.usage?.(event);
         if (usage) this.opts.onUsage?.(usage, task);
         if (this.opts.backend.failure?.(event) === "quota") quota = true;
@@ -359,8 +441,9 @@ export class ReviewerPrintPeer extends BasePeer {
     this.childCurrent = launch.watchCurrent ? launch.current : undefined;
     const code = await child.done;
     if (this.child === child) this.child = undefined;
-    return { code, quota };
+    return { code, quota, trace };
     } finally {
+      if (this.activeTrace?.value === trace) this.activeTrace = undefined;
       closeMcp();
       if (policyTimer) clearInterval(policyTimer);
       try { if (!ownedChild || this.child !== ownedChild) { await release(); if (this.childCleanup === release) this.childCleanup = undefined; } }

package/src/cli/console-state.ts

@@ -47,7 +47,8 @@ export interface ConsoleState {
   autoSelected?: boolean;
   input: string; editing: boolean; history: string[]; historyIndex: number;
   approvals: Approval[]; events: ConsoleEvent[]; peers: Record<string, any>; budget: Record<string, any>;
-  taskWip?: Record<string, { wip: number; wipLimit: number }>;
+  /** #784 AC3: the split of `wip` (active, review-wait, reserved); absent from an older hub. */
+  taskWip?: Record<string, { wip: number; wipLimit: number; active?: number; reviewWait?: number; reserved?: number }>;
   backlogView?: boolean;
   tasks: any[]; tasksKnown?: boolean; taskCounts?: Record<string, number>; queue: any[]; detail?: Detail; detailOffset: number; help: boolean; notice: string; noticeAt?: number; noticeTone?: Tone;
   peerFilter?: string; kindFilter?: string; project?: string;
@@ -348,6 +349,12 @@ export function budgetFields(budget: any, now: number): [string, unknown][] {
   });
   return [["quota", lines.length ? lines : typeof budget.note === "string" ? budget.note : "no reading"], ...(lines.length && typeof budget.note === "string" ? [["quota note", budget.note] as [string, unknown]] : [])];
 }
+/** #784 AC3: the Peers detail carries the planner WIP split as one line (`1 of 2: active 1, review-wait 0, reserved 0`); a hub that sends none adds nothing. */
+function peerDetailRow(s: ConsoleState, row: any): Record<string, unknown> {
+  const wip = s.taskWip?.[row.id];
+  const split = wip && [wip.active, wip.reviewWait, wip.reserved].every(n => Number.isSafeInteger(n)) ? `${wip.wip} of ${wip.wipLimit}: active ${wip.active}, review-wait ${wip.reviewWait}, reserved ${wip.reserved}` : undefined;
+  return { ...row, ...(split ? { "planner WIP": split } : {}) };
+}
 const detailLines = (detail: Detail, columns: number, now: number, task = false): Span[][] => {
   if (typeof detail === "string") return wrap(detail, columns).map(text => [span(text)]);
   const { budget, ...rest } = detail as Record<string, unknown>;
@@ -794,7 +801,7 @@ export function reduceConsole(state: ConsoleState, key: string, now = Date.now()
     if (s.panel === 3 || s.panel === 4) effects.push({ type: "show", panel: s.panel, id: String(row.id) });
     else if (s.panel === 2) { s.requestDetail = row.id; s.detailOffset = 0; } // the row is the selected request
     else if (s.panel === 7) { s.detail = { usagePeer: row.id }; s.detailOffset = 0; } // rendered live from s.usage, so a refresh updates it
-    else { s.detail = s.panel === 5 ? String(row.text) : { ...row }; s.detailOffset = 0; }
+    else { s.detail = s.panel === 5 ? String(row.text) : s.panel === 1 ? peerDetailRow(s, row) : { ...row }; s.detailOffset = 0; }
     return done();
   }
   if (s.mode === "panels" && item !== undefined && item !== null) {

package/src/cli/help.ts

@@ -8,7 +8,7 @@ export interface HelpEntry { section: string; usage: string; description: string
 const SECTIONS: [string, [usage: string, description: string][]][] = [
   ["Projects", [
     ["ahub --project <path|id> <command>", "select a repository or worktree explicitly"],
-    ["ahub projects [--json] [--color=auto|always|never]", "list registered projects and live status"],
+    ["ahub projects [--json] [--full] [--color=auto|always|never]", "list registered projects and live status"],
     ["ahub projects remove <id>", "forget a stopped registration (keeps project files)"],
     ["ahub setup [--yes]", "install or update the Claude Code channel plugin from this package, then run doctor"],
     ["ahub init [--profile dev|research|writing|general] [--shadow] [--release-guard] [--dry-run --json]", "preview or write .agenthub/config.json and the AGENTS.md marker block (drops a legacy CLAUDE.md block)"],
@@ -24,9 +24,10 @@ const SECTIONS: [string, [usage: string, description: string][]][] = [
     ["ahub pet --window [--close]", "start or close the macOS floating window, from a person's terminal"],
     ["ahub pet [--short]", "read attention without connecting; --short prints ahub!N only when action is needed"],
     ["ahub pet --palette <blue|teal|violet|ochre>", "save the floating window's base color to pet.palette in .agenthub/config.local.json"],
-    ["ahub sdlc status [task] | explain <task> | export <task> | record <task> <receipt-json>", "read head-bound lifecycle gates and the next actor/action (person only)"],
-    ["ahub sdlc queue <owner/repo> | release <owner/repo> [live-issue...]", "read-only merge and release evidence (person only)"],
-    ["ahub sdlc authorize-release <version>", "approve this daemon checkout commit, version and fresh docs (person only; restart revokes)"],
+    ["ahub sdlc status [task] | explain <task> [--json] [--color=auto|always|never] | export <task> | record <task> <receipt-json>", "read head-bound lifecycle gates and the next actor/action; status and explain are open to any agent as a public view (private tasks stay stubs), export and record are person only; export stays JSON"],
+    ["ahub sdlc queue <owner/repo> | release <owner/repo> [live-issue...] [--json] [--color=auto|always|never]", "read-only merge and release evidence; open to any agent as public readback of the checkout's repositories, never an authorization"],
+    ["ahub sdlc merge <task> [--dry-run]", "guarded squash merge of an approved task at its approved head after every gate is re-read; follows sdlc.toml auto_merge (off, dry-run, on); --dry-run only reports (person or conductor)"],
+    ["ahub sdlc authorize-release <version> [--json] [--color=auto|always|never]", "approve this daemon checkout commit, version and fresh docs (person only; restart revokes)"],
     ["ahub sdlc release-guard -- <literal git push|gh release create|npm publish argv>", "read-only authorization preflight; init --release-guard installs the tag pre-push hook"],
     ["ahub sdlc release-guard-hook <remote-name> <remote-url>", "internal pre-push readback; validates version tags and forwards exact stdin on success"],
     ["ahub sdlc accept <task> --issue <n> [--repo owner/repo]", "accept the task's spec issue at its current body; build entry needs it in enforce (person only)"],
@@ -34,22 +35,22 @@ const SECTIONS: [string, [usage: string, description: string][]][] = [
     ["ahub sdlc plan-review <task> <revision> <reason...> [--review full|delta|none --reviewers N] [--ci full|focused|reuse]", "record planner review, scope and host-read issue metadata"],
     ["ahub sdlc train report|configure|cut <release-id> [revision] [json]", "plan a release and freeze its approved scope after resource/quota admission"],
     ["ahub sdlc release-assign <task> <revision> <release-id|none> <reason...>", "assign approved/in-flight work without changing execution"],
-    ["ahub sdlc costs [owner/repo]", "read bounded planner cost metrics for linked merged PRs"],
-    ["ahub sdlc metrics [--since <YYYY-MM-DD|ISO time>]", "read SDLC metrics and control band tiers from board history (planner or person; read-only)"],
-    ["ahub backlog groom | return <task> <revision> <reason...>", "read grooming findings or return accepted untouched work to backlog (planner/person)"],
+    ["ahub sdlc costs [owner/repo] [--json] [--color=auto|always|never]", "read bounded planner cost metrics for linked merged PRs"],
+    ["ahub sdlc metrics [--since <YYYY-MM-DD|ISO time>] [--json] [--color=auto|always|never]", "read SDLC metrics and control band tiers from board history (planner or person; read-only)"],
+    ["ahub backlog groom | return <task> <revision> <reason...> [--json] [--color=auto|always|never]", "read grooming findings or return accepted untouched work to backlog (planner/person)"],
     ["ahub status [--json] [--full] [--color=auto|always|never]", "the hub, its peers, model backends and task counts"],
     ["ahub status --all [--json] [--color=auto|always|never]", "show every registered project"],
-    ["ahub logs [-f]", "the last 100 lines of hub.log; -f shows the last 10 and follows it"],
+    ["ahub logs [-f]", "person: last 100 hub.log lines (-f starts at 10); conductor: bounded public lines and follow while authority remains"],
     ["ahub doctor [--json] [--full] [--color=auto|always|never]", "check the tools, daemon, plugin, gateway, models and memory library this project uses"],
     ["ahub doctor --stale-anchors [--json]", "read-only bounded report of public memory symbol anchors at current HEAD; private or unavailable evidence stays unknown"],
-    ["ahub doctor --orphans [--kill] [--json] [--color=auto|always|never]", "list registrations whose project root is gone; --kill stops their daemons (SIGTERM, then SIGKILL) only after the process identity checks out"],
+    ["ahub doctor --orphans [--kill] [--json] [--color=auto|always|never]", "person: inspect missing-root registrations; conductor --kill: selected project only; signed hub ownership is required before any stop"],
     ["ahub agents [--json]", "show each gated agent CLI's installed version and verdict (verified, in-line, trusted, refused or unknown)"],
     ["ahub agents trust <id> <version> [--revoke]", "accept an untested agent CLI version on this machine (person only; runtime proofs still run)"],
     ["ahub kill", "stop this project's hub"],
     ["ahub reset [--all] [--yes]", "list, then with --yes stop the hub and discard every queued and needs_review delivery, clear holds and pauses and drop session pointers; --all moves the state directory to .agenthub/archive instead"],
     ["ahub restart [--dry-run] [--yes] [--json] [--verbose] [--color=auto|always|never]", "recover this project's runtime; on a terminal without a flag it reviews the plan with you, follows the progress and offers the next steps"],
     ["ahub upgrade [--to <version>] [--dry-run] [--yes] [--json] [--verbose] [--color=auto|always|never]", "review and upgrade running projects; --to defaults to the latest release (--yes needs it), and a newer release's own coordinator takes over; on a terminal without --dry-run or --yes: review, end agents first if you choose, apply, follow, and resume, cancel, end or reset on the spot"],
-    ["ahub recovery [status|resume|abort] [<operation-id>]", "inspect, resume or cancel a preflight; status names the next actions; without an id, the operation that holds the lock, and with nothing else on a terminal its screen"],
+    ["ahub recovery [status|resume|abort] [<operation-id>] [--json] [--color=auto|always|never]", "inspect, resume or cancel a preflight; status names the next actions; without an id, the operation that holds the lock, and with nothing else on a terminal its screen"],
     ["ahub recovery reattach <operation-id> codex|claude|pi", "person only: repair that blocked peer with its recorded session; leaves the rest for recovery resume"],
     ["ahub recovery dispose [<operation-id>] --fresh-session codex|claude --reason <text>", "end a partial operation by starting that peer as a new session, recording the lost conversation"],
     ["ahub recovery dispose [<operation-id>] --stop-and-archive --reason <text>", "end a partial operation: stop its own targets, archive its snapshot and release the lock; the upgrade is abandoned, not completed"],
@@ -60,9 +61,9 @@ const SECTIONS: [string, [usage: string, description: string][]][] = [
     ["ahub <configured-kind> [--mode headless] [--as <instance>] [--session-id <id>] [--print-command | --dry-run]", "start a trusted config.local.json ACP kind (default off roster); native argv is withheld in previews"],
     ["ahub role list [--group <group>] | show <id>", "read bounded catalog guidance with layer and content hash"],
     ["ahub role assign <peer> <id> | clear <peer> [<id>]", "person only: add or clear catalog guidance, applied at the next peer start"],
-    ["ahub stop <peer>", "human only: stop a hub-owned headless peer; end TUI agents in their terminals"],
+    ["ahub stop <peer>", "person or configured conductor: stop a hub-owned headless peer; end TUI agents in their terminals"],
     ["ahub models status [--json] [--color=auto|always|never]", "inspect local model state as labelled fields"],
-    ["ahub models setup|start|stop", "prepare or inspect local Ollama MLX (legacy stop is explicit)"],
+    ["ahub models setup|start [--json] [--color=auto|always|never] | stop", "prepare or inspect local Ollama MLX; setup and start print the model state like status (legacy stop is explicit)"],
   ]],
   ["Messages and approvals", [
     ["ahub say [@peer ...] <text>", "send as the console user (no @peer = broadcast); delivered at once, start the text with [STATUS] to let it batch or [FYI] for the record only"],
@@ -70,32 +71,32 @@ const SECTIONS: [string, [usage: string, description: string][]][] = [
     ["ahub tail", "live stream of messages, states and permission requests"],
     ["ahub permission [<peer> [ask|ask-when-needed|never-ask]] [--yes]", "human only: inspect or set a running peer mode; never-ask requires --yes; config never-ask waits for console y"],
     ["ahub permit <id> <option>", "answer a permission request shown by tail (\"deny\" cancels)"],
-    ["ahub roster [--json] [--color=auto|always|never]", "human only: every known peer, participation, start mode and retained work"],
-    ["ahub roster add <peer> | remove <peer> [--yes] [--now]", "human only: change live participation through settings; removal previews retained messages and task handoff; remove also deletes the roster key of an instance no longer declared"],
-    ["ahub settings [list] [--json] | get <key> [--json]", "human only: the settings the dashboard can change, each with its value, the file it comes from and when it applies"],
-    ["ahub settings set <key> <value|inherit> [--yes] [--preview] [--now] | undo | reload", "human only: change or reload validated settings, written to .agenthub/config.local.json or routing.local.toml (never a tracked file); --preview shows the effect and saves nothing; undo puts back the last write"],
+    ["ahub roster [--json] [--color=auto|always|never]", "every known peer, participation, start mode and retained work"],
+    ["ahub roster add <peer> | remove <peer> [--yes] [--now]", "person or configured conductor: change live participation through settings; removal previews retained messages and task handoff; remove also deletes the roster key of an instance no longer declared"],
+    ["ahub settings [list] [--json] | get <key> [--json]", "the settings the dashboard can change, each with its value, the file it comes from and when it applies"],
+    ["ahub settings set <key> <value|inherit> [--yes] [--preview] [--now] | undo | reload", "validated settings: conductor set is limited to exact live operational keys; undo/reload and other keys are person only; --preview saves nothing; conductor writes keep the person undo record"],
     ["ahub settings edit <config.local.json|sdlc.toml> (set <path> <json> | remove <path>)... [--reason <text>] [--preview] [--yes] | backups [--json]", "human only: structural config (instances, review, snapshots, approvals, context.gate, sdlc.toml mode and required_checks) validated by the hub's own loaders, previewed as a diff and written with a backup; a key that runs code or locates secrets needs its name typed, never --yes"],
     ["ahub pause|resume <peer>", "hold a peer's deliveries in its queue / release them"],
-    ["ahub queue list [--peer <id>] [--json] [--color=auto|always|never]", "inspect durable deliveries"],
-    ["ahub queue show <delivery-id> [--json] [--color=auto|always|never]", "inspect one delivery and revision"],
-    ["ahub queue resolve <delivery-id> --action completed|retry|discard --reason <text> [--revision N]", "resolve a queued or needs_review delivery; --revision binds the displayed row instead of a fresh show; a queued delivery can be discarded while its peer is busy, and a refusal names its cause"],
-    ["ahub queue discard --peer <id> --reason <text> [--state queued|needs_review] [--yes] [--json]", "person only: without --yes count one peer's queued (default) deliveries; with --yes discard them all with the reason, one recorded discard each; other peers' queues are untouched"],
+    ["ahub queue list [--peer <id>] [--json] [--full] [--color=auto|always|never]", "inspect durable deliveries; open to any agent as public queue metadata, held bodies stay with the person or conductor"],
+    ["ahub queue show <delivery-id> [--json] [--color=auto|always|never]", "person or configured conductor: inspect one delivery and revision; agent output uses the public view"],
+    ["ahub queue resolve <delivery-id> --action completed|retry|discard --reason <text> [--revision N] [--json] [--color=auto|always|never]", "person or configured conductor: resolve a queued or needs_review delivery; --revision binds the displayed row instead of a fresh show; a queued delivery can be discarded while its peer is busy, and a refusal names its cause"],
+    ["ahub queue discard --peer <id> --reason <text> [--state queued|needs_review] [--yes] [--json]", "person or configured conductor: without --yes count one peer's queued (default) deliveries; with --yes discard them all with the reason, one recorded discard each; other peers' queues are untouched"],
   ]],
   ["Tasks and review", [
     ["ahub board import github --label <label> [--milestone <milestone>] [--repo <owner/repo>]", "person only: read bounded open issues into deduplicated Backlog; never writes GitHub"],
     ["ahub board [state | --ready] [--columns] [--release <name> | --release-id <id>] [--json] [--full] [--color=auto|always|never]", "the task board, one line per task at a terminal width; --full: whole titles and SDLC advice; --ready: proposed tasks with nothing left to wait for"],
     ["ahub task propose [--class <c> | <class>] <title...> [--owner <peer>] [--path <p>]... [--after <id>]... [--urgent] [--backlog] [--detail <text>]", "put a task on the board; a first word that names a class is taken as the class; while a task named by --after is not approved yet, --owner reserves the task for that peer, offered to it first once it is ready; otherwise --owner assigns it now"],
-    ["ahub backlog list [--json] [--full] [--color=auto|always|never] | add <class> <title...> | plan <id> <revision> <fields-json> <reason...> | pin <id> <revision> true|false <reason...> | undo <id> <revision>", "person only: plan work with a reason; {} records a note-only revision, fields.sdlc sets backlog repo/issue identity and clears old spec acceptance; preserve pins/frozen scope and refuse stale edits; list is by rank (--json: raw listing)"],
-    ["ahub release new <name> <goal> <order> | list | show <name> | plan <name> <revision> <dates-json> | activate|freeze|ship|drop <name> <revision>", "person only: planned UTC millisecond dates and phased scope; ship records a time after approval, never tags or publishes"],
-    ["ahub backlog split <id> <revision> <parts-json> <reason...>", "person only: stage2..8 child prerequisites; original task retains integration, undo refuses used or changed children"],
-    ["ahub backlog pull-ready <id> <revision> <reason...>", "person only: reserve an eligible WIP slot before routing; pending unowned work can be undone"],
+    ["ahub backlog list [--json] [--full] [--color=auto|always|never] | add <class> <title...> | plan <id> <revision> <fields-json> <reason...> | pin <id> <revision> true|false <reason...> | undo <id> <revision> [--json] [--color=auto|always|never]", "person only: plan work with a reason; {} records a note-only revision, fields.sdlc sets backlog repo/issue identity and clears old spec acceptance; preserve pins/frozen scope and refuse stale edits; list is by rank (--json: raw listing)"],
+    ["ahub release new <name> <goal> <order> | list | show <name> | plan <name> <revision> <dates-json> | activate|freeze|ship|drop <name> <revision> [--json] [--color=auto|always|never]", "person only, except show (any agent, public metadata): planned UTC millisecond dates and phased scope; ship records a time after approval, never tags or publishes"],
+    ["ahub backlog split <id> <revision> <parts-json> <reason...> [--json] [--color=auto|always|never]", "person only: stage2..8 child prerequisites; original task retains integration, undo refuses used or changed children"],
+    ["ahub backlog pull-ready <id> <revision> <reason...> [--json] [--color=auto|always|never]", "person only: reserve an eligible WIP slot before routing; pending unowned work can be undone"],
     ["ahub backlog pull|return <id>", "person only: pull backlog into To Do or return ownerless proposed work; --backlog on task propose stages unoffered work"],
     ["ahub deliverables [--task <id>] [--approved] [--check] [--json] [--color=auto|always|never]", "person only: what each task delivered and a reviewer approved, by id, hash and size (a path only where the PII screen allows); --check measures the files now and marks one changed since review"],
-    ["ahub task show|escalate <id>", "full task with history (PII text included) / hand it to the next peer in escalate_to"],
+    ["ahub task show <id> [--json] [--full] [--color=auto|always|never] | escalate <id>", "full task with history (the person sees PII text, an agent the public view) / hand it to the next peer in escalate_to (person or configured conductor)"],
     ["ahub task role <id> <role|none>", "person only: change bounded catalog guidance on an open task; routing and authority are unchanged"],
     ["ahub task assign <id> <peer> [--role owner|reviewer|planner] [--revision N]", "name the owner (default), reviewer or person-only planner; a task that still waits reserves its owner; a peer that cannot take it is refused with the reason; --revision refuses stale console actions"],
     ["ahub task unassign <id> [--role owner|reviewer] [--revision N]", "person only: remove the owner/reservation or reviewer without routing a replacement or stopping native work"],
-    ["ahub task cancel <id> --reason <text> [--superseded-by <ref>] [--revision N]", "person only: close obsolete work with a reason; retain its history without stopping native work or releasing dependents"],
+    ["ahub task cancel <id> --reason <text> [--superseded-by <ref>] [--revision N] [--json] [--color=auto|always|never]", "person only, plus the configured conductor: close obsolete work with a reason; retain its history without stopping native work or releasing dependents; eligibility follows the task-board policy"],
     ["ahub task label <id> ok|regressed|reverted|incomplete|wrong|abandoned [--created <time>]", "your later verdict on an approved task, kept in the research records (research must be on)"],
     ["ahub review <id> approved|changes_requested [note...] [--unmet <item>]... [--head <sha>] [--findings <json>]", "give a review verdict on a task; the person can do the same in ahub console: Tasks, select the task, r, then a (approve) or c (request changes, with a note)"],
     ["ahub review brief <id>", "print the review brief of a task's commit: reviewable and excluded files, rules, coverage to account for"],
@@ -109,7 +110,7 @@ const SECTIONS: [string, [usage: string, description: string][]][] = [
     ["ahub budget set <peer> <0..1> [--resets-in 30m] [--window 5h|week]", "feed a reading by hand (also: test the relay)"],
     ["ahub budget resume <peer>", "override a budget pause; readings are ignored for that peer until the window resets"],
     ["ahub budget execution status [id] [--json] [--color=auto|always|never]", "read execution counters and limits"],
-    ["ahub budget execution configure <config.json> | disable <id>", "opt-in limits on model calls, tool calls, time and tokens for pi and local"],
+    ["ahub budget execution configure <config.json> | disable <id> [--json] [--color=auto|always|never]", "opt-in limits on model calls, tool calls, time and tokens for pi and local"],
   ]],
   ["History and reports", [
     ["ahub turns [peer] [--limit N] [--json] [--color=auto|always|never]", "recent turns and the files each changed (a git work tree only)"],
@@ -119,7 +120,7 @@ const SECTIONS: [string, [usage: string, description: string][]][] = [
     ["ahub usage [--since 7d|<iso>] [--by peer|task|issue|pr|release|day|model] [--json] [--color=auto|always|never]", "tokens per group from the incremental roll-up: the provider's total with and without cache reads, input, output, reasoning and the hub's own count; each number names its source, unknown is never 0"],
     ["ahub usage limits [--peer <id>] [--limit <n>] [--json] [--color=auto|always|never]", "current quota windows and the history of pauses, resumes and resets"],
     ["ahub usage total [--json] [--color=auto|always|never]", "lifetime development tokens since the first event, per peer and overall"],
-    ["ahub export [--since 7d|<iso>]", "structured events (events.jsonl) as JSON lines; never message bodies"],
+    ["ahub export [--since 7d|<iso>]", "structured events (events.jsonl) as JSON lines; never message bodies; the configured conductor gets a bounded projection (last 1000 events)"],
     ["ahub research [--since 30d] [--all] [--json]", "success, first-pass, rework and check-failure rates, tokens and wall time per approved task, from the opt-in research records"],
     ["ahub research addons [--since 30d] [--all] [--json]", "approved tasks with each add-on (claude-mem, ponytail, ripwire, ...) on against off, with intervals; association, not cause"],
     ["ahub research export [--format jsonl|csv] [--since 30d] [--all]", "the research records for outside analysis: ids, counts and tokens, never text"],

package/src/cli/identity.ts

@@ -1,3 +1,4 @@
+import { conductorOperation, OPERATIONAL_PERSON_GUIDANCE } from "../hub/operational-authority.ts";
 import { nativeCliMarkerPeer } from "../adapters/definitions/native-identity-defaults.ts";
 import { recoveryPresentationFlag } from "./recovery-presentation-options.ts";
 import { definitionOf, kindOf, type KindMap, type ProjectAdapterCatalog } from "../adapters/registry.ts";
@@ -14,7 +15,7 @@ export const LIVE_TEST_PERSON_REFUSAL = "live-test cannot write person-attribute
 
 /** Person verdicts and user-authored workflow content are never delegated. */
 export function liveTestRefusal(command: string, args: readonly string[], context: { repairedFresh?: boolean } = {}): boolean {
-  if (command === "sdlc" && (args[0] === "authorize-release" || args[0] === "plan-review" || args[0] === "release-assign" || args[0] === "train" && args[1] !== "report")) return true;
+  if (command === "sdlc" && (args[0] === "authorize-release" || args[0] === "plan-review" || args[0] === "release-assign" || args[0] === "merge" || args[0] === "train" && args[1] !== "report")) return true;
   if (args.some(arg => arg === "--as-user" || arg.startsWith("--as-user="))) return true;
   const sub = command === "recovery" ? recoveryAction(args) : args.find(arg => arg !== "--json");
   return ["task", "role", "goal", "deliverables"].includes(command)
@@ -53,15 +54,85 @@ export function detectCliIdentity(env: Readonly<Record<string, string | undefine
 
 export type PeerCommandAccess = "allowed" | "conductor" | "console";
 
-/** A closed list: unknown commands cannot acquire console authority through an agent shell. */
+/** Flags the read-only forms of #812 accept: display options that change no behaviour. */
+const peerReadFlags = (args: readonly string[]): boolean =>
+  args.every((arg) => ["--json", "--full", "--verbose", "--color=always", "--color=never", "--color=auto"].includes(arg) || arg.startsWith("--color="));
+
+/**
+ * The read-only command forms #812 makes Allowed: command -> subcommand -> what the rest of argv may hold.
+ * positional: bare words naming what to read (an operation id, a task, a release, a repo);
+ * valueFlags: options consuming one value an agent may name (--peer, --to, --since).
+ * A subcommand of "" is the bare form: display flags only. dryRun is checked separately for upgrade and restart.
+ */
+interface PeerReadForm {
+  positional?: number;
+  minimum?: number;
+  valueFlags?: readonly string[];
+  displayFlags?: readonly string[];
+}
+const publicReadDisplayFlags = ["--json", "--full", "--color=auto", "--color=always", "--color=never"] as const;
+const sdlcReadDisplayFlags = ["--json", "--color=auto", "--color=always", "--color=never"] as const;
+const peerReadForms: Readonly<Record<string, Readonly<Record<string, PeerReadForm>>>> = {
+  queue: { list: { valueFlags: ["--peer"], displayFlags: publicReadDisplayFlags } },
+  roster: { "": { displayFlags: publicReadDisplayFlags } },
+  settings: { "": { displayFlags: ["--json"] }, list: { displayFlags: ["--json"] }, get: { positional: 1, minimum: 1, displayFlags: ["--json"] } },
+  // #814 renders these reads for people and keeps JSON as an explicit data format.
+  sdlc: { status: { positional: 1, displayFlags: sdlcReadDisplayFlags }, explain: { positional: 1, displayFlags: sdlcReadDisplayFlags }, queue: { positional: 1, minimum: 1, displayFlags: sdlcReadDisplayFlags }, release: { positional: 33, minimum: 1, displayFlags: sdlcReadDisplayFlags } },
+  release: { show: { positional: 1, minimum: 1, displayFlags: [] } },
+  projects: { "": {} },
+  models: { status: {} },
+  recovery: { status: { positional: 1 } },
+};
+
+/** Whether argv matches one Allowed read-form of this command: display flags, the subcommand shape's values only. */
+const readFormArgs = (args: readonly string[], { valueFlags = [], positional = 0, minimum = 0, displayFlags }: PeerReadForm = {}): boolean => {
+  let positionals = 0;
+  let expectValue: string | undefined;
+  for (const arg of args) {
+    if (expectValue !== undefined) {
+      if (arg.startsWith("-")) return false;
+      expectValue = undefined;
+    } else if (valueFlags.includes(arg)) {
+      expectValue = arg;
+    } else if (arg.startsWith("--")) {
+      if (displayFlags === undefined ? !peerReadFlags([arg]) : !displayFlags.includes(arg)) return false;
+    } else if (positionals >= positional) {
+      return false;
+    } else {
+      positionals++;
+    }
+  }
+  return expectValue === undefined && positionals >= minimum;
+};
+
+const isPeerReadForm = (command: string, args: readonly string[]): boolean => {
+  const subs = peerReadForms[command];
+  if (subs === undefined) return false;
+  // The bare form ("") carries no subcommand: args empty or all display flags; otherwise args[0] is the subcommand.
+  const first = args[0];
+  const bare = first === undefined || first.startsWith("--");
+  const sub = bare ? "" : first;
+  if (!Object.hasOwn(subs, sub)) return false;
+  return readFormArgs(bare ? args : args.slice(1), subs[sub]!);
+};
+
+/**
+ * A closed list: unknown commands cannot acquire console authority through an agent shell.
+ * #812: the read-only forms matched by the branches just above the catch-alls are Allowed for any agent.
+ * The branches above them are the older authority rules and stay unchanged.
+ */
 export function classifyPeerCommand(command: string, args: readonly string[], catalog?: ProjectAdapterCatalog): PeerCommandAccess {
   if (command === "recovery" && recoveryAction(args) === "reattach") return "console";
   const native = catalog?.definitionOf(command) ?? definitionOf(command);
   if (native?.cli.personOnlyFlags?.some(flag => args.includes(flag))) return "console";
   if (command === "pet" && args.includes("--window")) return "console";
-  if (command === "permission" || command === "stop" || command === "watch") return "console";
+  if (command === "permission" || command === "watch") return "console";
   if (args.some((arg) => arg === "--as-user" || arg.startsWith("--as-user="))) return "console";
+  if (conductorOperation(command,args)) return "conductor";
+  if (command === "stop") return "console";
   if (command === "sdlc" && ["release-guard", "release-guard-hook"].includes(args[0] ?? "")) return "allowed";
+  // #786: the guarded merge is the person's or the configured conductor's; the daemon refuses any other peer by role.
+  if (command === "sdlc" && args[0] === "merge") return "conductor";
   if (command === "role") return ["list", "show"].includes(args[0] ?? "") ? "allowed" : "console";
   if (command === "task") {
     if (["propose", "show"].includes(args[0] ?? "")) return "allowed";
@@ -82,6 +153,16 @@ export function classifyPeerCommand(command: string, args: readonly string[], ca
   // The subcommand is the first argument that is not --json, which the command accepts anywhere.
   if (command === "bench") return args.find((arg) => arg !== "--json") === "run" ? "console" : "allowed";
   if (command === "budget") return !args.length || args.every((arg) => arg === "--json" || arg === "--full" || arg.startsWith("--color=")) ? "allowed" : "console";
+  // #812 Allowed: the read-only forms below print what the person sees and change nothing. Each command's
+  // other forms fall to the existing rules underneath, so every older branch above and below keeps its class.
+  if (command === "doctor") {
+    if (peerReadFlags(args)) return "allowed"; // no args, or only --json, --full, --color=...
+    if (args[0] === "--stale-anchors" && peerReadFlags(args.slice(1))) return "allowed"; // a bounded read-only anchor report
+    // --orphans (it can kill) and anything else stay as today.
+  }
+  if ((command === "upgrade" || command === "restart") && !args.includes("--yes") && args.includes("--dry-run")
+    && readFormArgs(args.filter((arg) => arg !== "--dry-run"), { valueFlags: ["--to"] })) return "allowed"; // a preview that applies nothing; --yes stays console
+  if (isPeerReadForm(command, args)) return "allowed"; // exact read forms; every mutating neighbour remains below its existing authority gate
   if (native?.cli.authority === "person") return "console";
   if (native || ["pause", "resume"].includes(command)) return "conductor";
   if (command === "board" && args[0] === "import") return "console";
@@ -95,9 +176,9 @@ export function cliCommandLabel(command: string, args: readonly string[], catalo
   if (command === "board" && args[0] === "import") return "board import";
   if (command === "release") return ["new", "list", "show", "plan", "activate", "freeze", "ship", "drop"].includes(args[0] ?? "") ? `release ${args[0]}` : "release";
   if (!(catalog?.definitionOf(command) ?? definitionOf(command)) && !["upgrade", "restart", "recovery", "recovery-run", "help", "--help", "--version", "version", "completion", "projects", "ui", "manager", "setup", "init", "daemon", "up", "console", "stop", "models", "say", "queue", "tail", "watch", "budget", "board", "task", "review", "remember", "ask", "route", "pause", "resume", "permit", "permission", "settings", "roster", "status", "pet", "logs", "export", "report", "research", "memory", "goal", "bench", "sdlc", "role", "facts", "check-path", "turns", "undo", "kill", "reset", "doctor", "agents"].includes(command)) return "unknown";
-  if (["task", "queue", "budget", "route", "recovery", "models", "projects", "research", "memory", "goal", "bench", "agents"].includes(command)) {
+  if (["task", "queue", "budget", "route", "recovery", "models", "projects", "research", "memory", "goal", "bench", "agents", "roster", "settings"].includes(command)) {
     const sub = command === "bench" || command === "memory" || command === "goal" ? args.find((arg) => arg !== "--json") : args[0];
-    if (sub && ["propose", "show", "assign", "unassign", "escalate", "label", "list", "resolve", "resume", "set", "execution", "explain", "status", "abort", "dispose", "reattach", "setup", "start", "stop", "remove", "discard", "export", "backfill", "addons", "run", "report", "compare", "search", "graph", "promote", "demote", "forget", "supersede", "dedupe", "decay", "rebuild", "sync", "machine", "import", "suggestions", "confirm", "reject", "new", "link", "state", "done", "take", "trust"].includes(sub)) return `${command} ${sub}`;
+    if (sub && ["propose", "show", "assign", "unassign", "escalate", "cancel", "label", "list", "add", "resolve", "resume", "set", "execution", "explain", "status", "abort", "dispose", "reattach", "setup", "start", "stop", "remove", "discard", "export", "backfill", "addons", "run", "report", "compare", "search", "graph", "promote", "demote", "forget", "supersede", "dedupe", "decay", "rebuild", "sync", "machine", "import", "suggestions", "confirm", "reject", "new", "link", "state", "done", "take", "trust"].includes(sub)) return `${command} ${sub}`;
   }
   return (/^[a-z][a-z0-9-]*$/.test(command) && !/\s/.test(command)) || ["--help", "--version"].includes(command) ? command : "unknown";
 }
@@ -122,5 +203,5 @@ export function agentShellCause(identity: CliIdentity, error: string, env: Reado
 
 export function peerCommandRefusal(peer: string, command: string, env: Readonly<Record<string, string | undefined>> = process.env): string {
   const markers = ["CLAUDECODE", "CLAUDE_CODE_SESSION_ID", "AGENTHUB_PEER_ID", "CODEX_THREAD_ID"].filter(name => env[name] !== undefined);
-  return `${peer} cannot run ahub ${command}; the person runs it in ahub console or a terminal. Refused because inherited agent markers${markers.length ? ` (${markers.join(", ")})` : ""} identify this shell as an agent. A ! command in an agent session runs as that agent; use a separate terminal outside the agent session`;
+  return `${peer} cannot run ahub ${command}; ${OPERATIONAL_PERSON_GUIDANCE}. Refused because inherited agent markers${markers.length ? ` (${markers.join(", ")})` : ""} identify this shell as an agent. A ! command in an agent session runs as that agent; use a separate terminal outside the agent session`;
 }