@staix/agent-hub 0.17.0 → 0.19.0

package/src/cli/main.ts

@@ -1,4 +1,5 @@
 #!/usr/bin/env bun
+import { conductorOperation, OPERATIONAL_PERSON_GUIDANCE } from "../hub/operational-authority.ts";
 import type { DeliverableRow } from "../hub/tasks.ts";
 import { kimiSourceRow } from "../hub/budget-notes.ts";
 import { hubGitSync, hubGitEnv } from "../hub/git.ts";
@@ -66,8 +67,8 @@ import { exactVersion, latestRelease, newerVersion } from "./recovery-package.ts
 import { operationScreen, planScreen, type ScreenIO, type UpgradeHost } from "./upgrade-interactive.ts";
 import { readRecoveryPresentationFlags } from "./upgrade-presentation-flags.ts";
 import { renderOperation, renderBlocked, renderSummary, type RecoveryPresentationOptions } from "./upgrade-presentation.ts";
+import { renderBudgetResult, renderRecoveryStatus, renderUpgradePlan } from "./upgrade-output.ts";
 import { recordTerminalLaunch, prepareTerminalLaunch, registerTerminalLaunch, type TerminalPeer } from "./terminal-recovery.ts";
-import { stopAndArchiveSummary } from "./recovery-guidance.ts";
 import { ensureMlx, inspectMlx, stopMlx } from "../models/mlx.ts";
 import { setupOllamaModel } from "./models-setup.ts";
 
@@ -94,6 +95,8 @@ import { runConsole } from "./console.ts";
 import { paint, permissionBoundary, resolveColor, wrap, type Span } from "./console-state.ts";
 import { outputWidth, renderRoster, renderStatus, renderBoard, renderBacklog, renderBoardColumns, boardColumnModel, renderBudget, renderDoctor, renderProjects, renderQueue, renderTurns, renderOrphans, renderQueueShow, renderModelsStatus, renderExecutionBudgetStatus, renderReport, renderUsage, renderLimits, renderTotal, type DoctorCheck } from "./output.ts";
 import { renderHelp, configuredAcpHelp } from "./help.ts";
+import { renderBacklogResult, renderGroom, renderReleaseChange, renderReleaseList, renderReleaseNew, renderReleaseShow, renderTaskCancel, renderTaskShow } from "./task-output.ts";
+import { renderAuthorization, renderSdlcCosts, renderSdlcExplain, renderSdlcMetrics, renderSdlcQueue, renderSdlcRelease, renderSdlcStatus } from "./sdlc-output.ts";
 import { renderTailEvent } from "./tail-render.ts";
 import { archiveProblem, archiveState, damagedState, failureText, MANIFEST, planReset, resetLines, resetRuntime, startState, type ResetPlan } from "./reset.ts";
 
@@ -201,6 +204,7 @@ const projectConfig = () => {
   return config;
 };
 const stateDir = selected.stateDir;
+var operationalAuditReady=false, operationalRefusalRecorded=false;
 const caller = declaredInstances ? detectCliIdentity(process.env, declaredInstances) : unboundCaller;
 const commandLabel = cliCommandLabel(cmd, args, projectCatalog);
 const commandAccess = classifyPeerCommand(cmd, args, projectCatalog);
@@ -208,8 +212,10 @@ const commandAccess = classifyPeerCommand(cmd, args, projectCatalog);
 const delegationRefused = liveTest && caller.role === "tools" && commandAccess !== "allowed" && liveTestRefusal(cmd, args);
 const delegatedPeer = liveTest && caller.role === "tools" && commandAccess !== "allowed" && !delegationRefused ? caller.peer : undefined;
 const identity = delegatedPeer ? { role: "console" as const } : caller;
+operationalAuditReady=identity.role==="tools" && commandAccess==="conductor" && conductorOperation(cmd,args)!==undefined;
 function audit(outcome: "run" | "refused" | "invalid"): void {
   if (caller.role === "console") return;
+  if(outcome==="refused" && operationalAuditReady){if(operationalRefusalRecorded)return;operationalRefusalRecorded=true;}
   try { recordCliAudit(stateDir, caller.role === "tools" ? caller.peer : "unknown", commandLabel, outcome); }
   catch {
     if (delegatedPeer) fail("live-test delegation audit unavailable; nothing was executed");
@@ -249,7 +255,7 @@ if (delegatedPeer && !recoveryAudit && !noAuditConsumer) {
     }
     fail((error as Error).message);
   }
-} else if (identity.role === "tools" || delegatedPeer) audit("run");
+} else if ((identity.role === "tools" || delegatedPeer) && !operationalAuditReady) audit("run");
 function assertDelegatedAuditConsumer(): void {
   if (delegatedAuditHub && ((!delegatedConnectionTaken && !delegatedAuditHub.isOpen) || readControl(stateDir)?.instanceId !== delegatedAuditHub.instanceId)) {
     throw new Error("delegated audit consumer changed; refusing further actions; inspect the result before retrying");
@@ -260,18 +266,52 @@ const liveTestArgs = liveTest ? ["--live-test"] : [];
 const invokedFrom = process.cwd(); // relative paths a person types (a bench suite) are theirs, not the project's
 try { process.chdir(cwd); } catch { fail(`project directory is unavailable: ${cwd}`); }
 /** One-shot output flags do not alter the fetched JSON document. */
-function outputOptions() {
-  const flags = args.filter(arg => arg.startsWith("--color="));
-  if (flags.length > 1 || args.includes("--color")) fail(`usage: ahub ${cmd} [--color=auto|always|never] [--json] [--full]`);
+function outputOptions(source: readonly string[] = args) {
+  const flags = source.filter(arg => arg.startsWith("--color="));
+  if (flags.length > 1 || source.includes("--color")) fail(`usage: ahub ${cmd} [--color=auto|always|never] [--json] [--full]`);
   const color = resolveColor(flags[0]?.slice("--color=".length), { isTTY: !!process.stdout.isTTY, TERM: process.env.TERM, NO_COLOR: process.env.NO_COLOR });
   if (color instanceof Error) fail(`usage: ahub ${cmd} [--color=auto|always|never] [--json] [--full]`);
-  return { color: color === true, json: args.includes("--json"), full: args.includes("--full"),
+  return { color: color === true, json: source.includes("--json"), full: source.includes("--full"),
     columns: outputWidth({ isTTY: !!process.stdout.isTTY, columns: process.stdout.columns, COLUMNS: process.env.COLUMNS }) };
 }
+/**
+ * #814 T2: split `--json`, `--full` and `--color=` from a command that also takes free text. A value flag's value is never a
+ * presentation flag (`task cancel --reason --json` records the reason `--json`), and with `edges` only a leading or trailing run
+ * counts, so a reason that mentions `--json` in the middle of a sentence keeps its words. A reason that ENDS in a bare
+ * presentation flag loses it: the documented cost of accepting the flag after the reason.
+ */
+function splitPresentation(argv: readonly string[], opts: { valueFlags?: readonly string[]; edges?: boolean } = {}): { operands: string[]; flags: string[] } {
+  const isFlag = (arg: string) => arg === "--json" || arg === "--full" || arg.startsWith("--color=");
+  const operands: string[] = [], flags: string[] = [], value = new Set(opts.valueFlags ?? []);
+  let lead = true;
+  const middle: string[] = [];
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i]!;
+    if (value.has(arg)) { (opts.edges ? middle : operands).push(arg); if (i + 1 < argv.length) (opts.edges ? middle : operands).push(argv[++i]!); lead = false; continue; }
+    if (!isFlag(arg)) { (opts.edges ? middle : operands).push(arg); lead = false; continue; }
+    if (!opts.edges || lead) flags.push(arg); else middle.push(arg);
+  }
+  if (!opts.edges) return { operands, flags };
+  // a trailing run of presentation flags moves out of the middle; anything earlier stays operand text
+  let end = middle.length;
+  const trailing: string[] = [];
+  while (end > 0 && isFlag(middle[end - 1]!) && !value.has(middle[end - 2] ?? "")) trailing.unshift(middle[--end]!);
+  return { operands: middle.slice(0, end), flags: [...flags, ...trailing] };
+}
 /** Remove only presentation flags from read-only command positional arguments. */
 function outputArguments(): string[] {
   return args.filter(arg => arg !== "--json" && arg !== "--full" && !arg.startsWith("--color="));
 }
+/** `sdlc` operands: the read subcommands that print for a person (#814) drop `--json`, `--full` and `--color=`; every other subcommand keeps its argv exactly. */
+/** A hub tool answers JSON text. Text that does not parse is printed as it came: a renderer never sees it, so it cannot read as an empty report. */
+function showToolText(render: (data: any, columns?: number, now?: number) => Span[][], text: string, present: ReturnType<typeof outputOptions>): void {
+  let data: unknown;
+  try { data = JSON.parse(text); } catch { return console.log(text); }
+  if (present.json) return console.log(text);
+  printOutput(render(data, present.columns, Date.now()), present.color);
+}
+const SDLC_READ = ["status", "explain", "queue", "release", "metrics", "costs", "authorize-release"];
+function sdlcOperands(): string[] { return SDLC_READ.includes(args[0] ?? "") ? outputArguments() : args; }
 function printOutput(lines: Span[][], color: boolean): void {
   for (const line of lines) console.log(paint(line, color));
 }
@@ -447,11 +487,17 @@ function startupDiagnostic(error: unknown): string {
   return message.replace(/[\p{Cc}\p{Cf}]/gu, " ").replace(/\s+/g, " ").trim().slice(0, 512) || "invalid startup configuration";
 }
 
-function fail(message: string): never {
+function fail(message: string, refusalAudited=false, authorityRefused?:boolean): never {
+  if(operationalAuditReady && authorityRefused!==false){if(refusalAudited)operationalRefusalRecorded=true;if(!operationalRefusalRecorded)audit("refused");}
   console.error(`ahub: ${message}`);
   process.exit(1);
 }
 
+function operationalIncomplete(result: {complete?:boolean;incompleteReason?:unknown;truncated?:boolean}, history: "log"|"event"): void {
+  if(result.complete===false)console.error(`ahub: operational output is incomplete: ${typeof result.incompleteReason==="string"?terminalText(result.incompleteReason).replace(/[\r\n]+/g," ").slice(0,200):"public privacy or history coverage unavailable"}`);
+  else if(result.truncated)console.error(`ahub: operational ${history} history is truncated`);
+}
+
 async function taskOp(op: string, a: Record<string, unknown>, throwOnError = false, connection?: ControlClient, timeoutMs?: number): Promise<string> {
   const hub = connection ?? await connect();
   try {
@@ -459,11 +505,12 @@ async function taskOp(op: string, a: Record<string, unknown>, throwOnError = fal
     const res = await hub.request({ t: "task", op, args: a }, timeoutMs ?? (op === "github_import" ? 60_000 : 30_000));
     if (!res.ok) {
       if (throwOnError) throw new Error(res.error);
-      audit("refused");
+      if(res.refusalAudited===true)operationalRefusalRecorded=true;
+      if(!operationalAuditReady || res.authorityRefused!==false)audit("refused");
       // #711: an agent shell refused something only the person may do is told why it counts as an agent. The refusal and the authority stay as they were.
       const cause = agentShellCause(identity, String(res.error));
       if (cause) console.error(`ahub: ${res.error}\n${cause}`), process.exit(1);
-      fail(res.error);
+      fail(res.error,res.refusalAudited===true,res.authorityRefused);
     }
     return res.text;
   } finally { if (!connection) hub.close(); }
@@ -509,7 +556,9 @@ async function hold(t: "pause" | "resume"): Promise<void> {
 }
 
 function recoveryDisplay() {
-  return readRecoveryPresentationFlags(args, { isTTY: !!process.stdout.isTTY, columns: process.stdout.columns ?? 80, TERM: process.env.TERM, NO_COLOR: process.env.NO_COLOR });
+  // A terminal gives its own width; a pipe gives COLUMNS when set, else 80 (#814: a person reads a pipe too).
+  const width = process.stdout.columns ?? outputWidth({ isTTY: false, COLUMNS: process.env.COLUMNS }) ?? 80;
+  return readRecoveryPresentationFlags(args, { isTTY: !!process.stdout.isTTY, columns: width, TERM: process.env.TERM, NO_COLOR: process.env.NO_COLOR });
 }
 const humanRecovery = (json: boolean) => !json && !!process.stdin.isTTY && !!process.stdout.isTTY;
 const printRecovery = (lines: readonly string[]) => { for (const line of lines) console.log(line); };
@@ -656,12 +705,15 @@ async function upgrade(kind: "restart" | "upgrade"): Promise<void> {
   if (interactive) return onTerminal((io) => planScreen(upgradeHost(kind, to ?? VERSION), io), display.options);
   const plan = await makeUpgradePlan(kind, to ?? VERSION, kind === "restart" ? cwd : undefined);
   const jsonApply = display.json && yes && !dry;
-  if (!jsonApply) console.log(JSON.stringify(plan, null, 2));
-  // #206: name every blocker and reconnect-only session on stderr, not only inside the JSON above.
-  for (const p of plan.projects) for (const peer of p.reconnectOnly ?? []) console.error(`ahub: ${p.project.id}: ${peer} is reconnect-only (unmanaged session): its plugin reattaches to the new hub; no terminal is closed or relaunched`);
-  for (const p of plan.projects) for (const peer of p.freshStart ?? []) console.error(`ahub: ${p.project.id}: ${peer} restarts as a new session: its thread has no rollout and the hub recorded no turn on it, so nothing is lost`);
+  // #814: a person reading a pipe or a dry run gets the plan screen's rows, with every blocker, reconnect-only session and
+  // fresh start in them. `--json` keeps the document and the stderr lines (#206) exactly as they were.
+  if (display.json) {
+    if (!jsonApply) console.log(JSON.stringify(plan, null, 2));
+    for (const p of plan.projects) for (const peer of p.reconnectOnly ?? []) console.error(`ahub: ${p.project.id}: ${peer} is reconnect-only (unmanaged session): its plugin reattaches to the new hub; no terminal is closed or relaunched`);
+    for (const p of plan.projects) for (const peer of p.freshStart ?? []) console.error(`ahub: ${p.project.id}: ${peer} restarts as a new session: its thread has no rollout and the hub recorded no turn on it, so nothing is lost`);
+  } else printRecovery(renderUpgradePlan(plan, VERSION, display.options));
   const blockers = [...plan.blockers, ...plan.projects.flatMap((p) => p.blockers.map((b) => `${p.project.id}: ${b}`))];
-  for (const blocker of blockers) console.error(`ahub: blocker: ${blocker}`);
+  if (display.json) for (const blocker of blockers) console.error(`ahub: blocker: ${blocker}`);
   if (dry) return;
   if (blockers.length) { if (jsonApply) console.log(JSON.stringify(plan, null, 2)); fail("plan has blockers; no runtime was changed"); }
   assertLifecycleAvailable();
@@ -724,14 +776,10 @@ const commands: Record<string, () => Promise<void> | void> = {
         return;
       }
       const result = await reattachRecovery(selected.id, selected.peer, makeRecoveryDriver());
-      if (humanRecovery(display.json)) {
-        printRecovery(renderOperation(result, undefined, display.options));
-        const live = await liveProjects(result, makeRecoveryDriver(undefined, delegatedPeer).inspect);
-        printRecovery(renderBlocked(result, nextChoices(result, undefined, live), display.options));
-      } else {
-        console.log(JSON.stringify(publicOperation(result), null, 2));
-        if (!display.json) console.log(nextActionsText(result));
-      }
+      if (display.json) { console.log(JSON.stringify(publicOperation(result), null, 2)); return; }
+      printRecovery(renderOperation(result, undefined, display.options));
+      const live = await liveProjects(result, makeRecoveryDriver(undefined, delegatedPeer).inspect);
+      printRecovery(renderBlocked(result, nextChoices(result, undefined, live), display.options));
       return;
     }
     // #272: without an id, the operation that holds the machine's lock; bare on a terminal, its screen.
@@ -761,7 +809,8 @@ const commands: Record<string, () => Promise<void> | void> = {
     if (action === "status") {
       // #215: abort and resume are offered by what the open sources show, read as the runner's errors read them.
       const live = runner ? {} : await liveProjects(operation, makeRecoveryDriver(undefined, delegatedPeer).inspect);
-      console.log(JSON.stringify(publicOperation(operation, runner, live), null, 2));
+      if (display.json) console.log(JSON.stringify(publicOperation(operation, runner, live), null, 2));
+      else printRecovery(renderRecoveryStatus(operation, runner, nextChoices(operation, runner, live), display.options));
     }
     else if (action === "abort") {
       await abortRecovery(id, makeRecoveryDriver(undefined, delegatedPeer));
@@ -780,11 +829,8 @@ const commands: Record<string, () => Promise<void> | void> = {
         console.log(`${one["--fresh-session"]}: a fresh session is accepted and the lost one is recorded; resuming`);
         return spawnRecovery(result, false, humanRecovery(false) ? display.options : undefined);
       }
-      if (humanRecovery(display.json)) printRecovery(renderSummary(result, await recoveryEndInspection(result), display.options));
-      else {
-        console.log(JSON.stringify(publicOperation(result), null, 2));
-        if (!display.json) for (const line of stopAndArchiveSummary(result)) console.log(line);
-      }
+      if (display.json) console.log(JSON.stringify(publicOperation(result), null, 2));
+      else printRecovery(renderSummary(result, await recoveryEndInspection(result), display.options));
     }
     else if (["completed", "cancelled"].includes(operation.phase)) console.log(display.json ? JSON.stringify(publicOperation(operation, runner), null, 2) : `recovery is already ${operation.phase}`);
     // #215: an operation being abandoned is never resumed, whichever coordinator started it (an older one would).
@@ -973,7 +1019,7 @@ const commands: Record<string, () => Promise<void> | void> = {
 
   models: async () => {
     const action = outputArguments()[0] ?? "status";
-    const options = action === "status" ? outputOptions() : undefined;
+    const options = ["status", "start", "setup"].includes(action) ? outputOptions() : undefined;
     const showStatus = (data: unknown) => options!.json ? console.log(JSON.stringify(data, null, 2)) : printOutput(renderModelsStatus(data, options!.columns, Date.now()), options!.color);
     const configured = projectConfig().mlx;
     if (configured.enabled === false) {
@@ -985,13 +1031,13 @@ const commands: Record<string, () => Promise<void> | void> = {
     const modelPath = configured.modelPath ? resolve(cwd, configured.modelPath) : join(homedir(), ".agenthub", "models", "qwen3-8b-mlx");
     const mlxOptions = configured.provider === "ollama" ? configured : { ...configured, runtimeDir, modelPath };
     if (action === "status") return showStatus(await inspectMlx(mlxOptions));
-    if (action === "start") { const handle = await ensureMlx(mlxOptions); return console.log(JSON.stringify(handle.status(), null, 2)); }
+    if (action === "start") { const handle = await ensureMlx(mlxOptions); return showStatus(handle.status()); }
     if (action === "stop") { await stopMlx(mlxOptions); return console.log("MLX stopped"); }
     if (action !== "setup") fail("usage: ahub models setup|status|start|stop");
     if (configured.provider === "ollama") {
       await setupOllamaModel(configured);
       const handle = await ensureMlx(configured);
-      return console.log(JSON.stringify(handle.status(), null, 2));
+      return showStatus(handle.status());
     }
     const python = join(runtimeDir, "bin", "python");
     const run = (argv: string[]) => { const result = spawnSync(argv[0]!, argv.slice(1), { cwd, stdio: "inherit" }); if (result.status !== 0) fail(`models setup failed: ${argv.join(" ")}`); };
@@ -1024,7 +1070,7 @@ const commands: Record<string, () => Promise<void> | void> = {
         const { one, rest: flags } = takeFlags(rest, ["--peer"], []);
         if (flags.length) fail("usage: ahub queue list [--peer <id>] [--json] [--full] [--color=auto|always|never]");
         const result = await hub.request({ t: "queue", op: "list", ...(one["--peer"] ? { peer: one["--peer"] } : {}) });
-        if (!result.ok) fail(result.error);
+        if (!result.ok) fail(result.error,result.refusalAudited===true,result.authorityRefused);
         if (options.json) return console.log(JSON.stringify(result.deliveries, null, 2));
         printOutput(renderQueue(result.deliveries, options.columns, Date.now()), options.color);
         return;
@@ -1036,7 +1082,7 @@ const commands: Record<string, () => Promise<void> | void> = {
         if (others.length || !one["--peer"] || (one["--state"] !== undefined && !["queued", "needs_review"].includes(one["--state"]))) fail("usage: ahub queue discard --peer <id> --reason <text> [--state queued|needs_review] [--yes]");
         if (yes && !one["--reason"]?.trim()) fail("ahub queue discard needs --reason <text> with --yes: it is recorded on every discarded delivery");
         const result = await hub.request({ t: "queue", op: "discard", peer: one["--peer"], ...(one["--state"] ? { state: one["--state"] } : {}), ...(yes ? { confirmed: true, reason: one["--reason"] } : {}) }, 60_000);
-        if (!result.ok) fail(result.error);
+        if (!result.ok) fail(result.error,result.refusalAudited===true,result.authorityRefused);
         if (options.json) return console.log(JSON.stringify(result, null, 2));
         if (!yes) return console.log(`${result.count} ${result.state} deliver${result.count === 1 ? "y" : "ies"} for ${result.peer}; nothing discarded. Run again with --reason <text> --yes to discard them.`);
         console.log(`discarded ${result.discarded} of ${result.count} ${result.state} deliver${result.count === 1 ? "y" : "ies"} for ${result.peer}${result.refused ? `; ${result.refused} refused (${Object.entries(result.refusedBy ?? {}).map(([why, n]) => `${why} ${n}`).join(", ")})` : ""}`);
@@ -1047,7 +1093,7 @@ const commands: Record<string, () => Promise<void> | void> = {
       if (operation === "show") {
         if (flags.length) fail("usage: ahub queue show <id>");
         const shown = await hub.request({ t: "queue", op: "show", id });
-        if (!shown.ok) fail(shown.error);
+        if (!shown.ok) fail(shown.error,shown.refusalAudited===true,shown.authorityRefused);
         if (options.json) return console.log(JSON.stringify(shown.delivery, null, 2));
         return printOutput(renderQueueShow(shown.delivery, options.columns, Date.now()), options.color);
       }
@@ -1057,12 +1103,13 @@ const commands: Record<string, () => Promise<void> | void> = {
       let revision = parsedRevision;
       if (revision === undefined) {
         const shown = await hub.request({ t: "queue", op: "show", id });
-        if (!shown.ok) fail(shown.error);
+        if (!shown.ok) fail(shown.error,shown.refusalAudited===true,shown.authorityRefused);
         revision = shown.delivery.revision;
       }
       const result = await hub.request({ t: "queue", op: "resolve", id, revision, action: one["--action"], reason: one["--reason"] });
-      if (!result.ok) fail(result.error);
-      console.log(JSON.stringify(result.delivery, null, 2));
+      if (!result.ok) fail(result.error,result.refusalAudited===true,result.authorityRefused);
+      if (options.json) console.log(JSON.stringify(result.delivery, null, 2));
+      else printOutput(renderQueueShow(result.delivery, options.columns, Date.now()), options.color);
     } finally { hub.close(); }
   },
 
@@ -1120,7 +1167,8 @@ const commands: Record<string, () => Promise<void> | void> = {
       const result = await hub.request(request); hub.close();
       if (!result.ok) fail(result.error);
       const data = result.budgets ?? result.budget ?? { disabled: result.disabled };
-      if (op !== "status" || options.json) return console.log(JSON.stringify(data, null, 2));
+      if (options.json) return console.log(JSON.stringify(data, null, 2));
+      if (op === "configure" || op === "disable") return printOutput(renderBudgetResult(op, op === "configure" ? result.budget : result, options.columns, Date.now()), options.color);
       return printOutput(renderExecutionBudgetStatus(result.budgets, options.columns, Date.now()), options.color);
     }
     let set: Record<string, unknown> | undefined;
@@ -1148,7 +1196,10 @@ const commands: Record<string, () => Promise<void> | void> = {
   },
 
   backlog: async () => {
-    const [sub, id, revision, value, ...reason] = args;
+    const split = splitPresentation(args, { edges: true }), operands = split.operands;
+    const [sub, id, revision, value, ...reason] = operands;
+    const present = outputOptions(split.flags); // before any request: an invalid --color must refuse before a mutation is sent
+    const shown = (render: (data: any, columns?: number, now?: number) => Span[][]) => async (text: Promise<string>) => showToolText(render, await text, present);
     if (sub === "list" && outputArguments().length === 1) {
       // #399: a table by default; --json prints the hub's listing unchanged, and a refusal is printed as it came.
       const options = outputOptions(), raw = await taskOp("hub_backlog_list", {});
@@ -1158,43 +1209,44 @@ const commands: Record<string, () => Promise<void> | void> = {
       if (!Array.isArray(cards)) return console.log(raw);
       return printOutput(renderBacklog(cards, options.columns, Date.now(), options.full), options.color);
     }
-    if (sub === "groom" && args.length === 1) return console.log(await taskOp("hub_planner_groom", {}));
-    if (["return", "return-untouched"].includes(sub ?? "") && /^[1-9]\d*$/.test(id ?? "") && /^\d+$/.test(revision ?? "") && args.length >= 4) {
-      return console.log(await taskOp("hub_backlog_return_untouched", { id: Number(id), revision: Number(revision), reason: args.slice(3).join(" ") }));
+    if (sub === "groom" && operands.length === 1) return shown(renderGroom)(taskOp("hub_planner_groom", {}));
+    if (["return", "return-untouched"].includes(sub ?? "") && /^[1-9]\d*$/.test(id ?? "") && /^\d+$/.test(revision ?? "") && operands.length >= 4) {
+      return shown((data, columns, now) => renderBacklogResult("return-untouched", data, columns, now))(taskOp("hub_backlog_return_untouched", { id: Number(id), revision: Number(revision), reason: operands.slice(3).join(" ") }));
     }
     if (sub === "add" && args.length >= 3) return console.log(await taskOp("hub_task_propose", { class: id, title: args.slice(2).join(" "), backlog: true }));
     if (!/^[1-9]\d*$/.test(id ?? "")) fail("usage: ahub backlog list|add <class> <title...>|pull|return <id>|plan|pin <id> <revision> <value> <reason...>|undo <id> <revision>");
-    if (["pull", "return"].includes(sub ?? "") && args.length === 2) return console.log(await taskOp(sub === "pull" ? "backlog_pull" : "backlog_return", { id }));
+    if (["pull", "return"].includes(sub ?? "") && operands.length === 2) return console.log(await taskOp(sub === "pull" ? "backlog_pull" : "backlog_return", { id }));
     if (!/^\d+$/.test(revision ?? "")) fail("planning revision is required");
-    if (sub === "pull-ready" && args.length >= 4) return console.log(await taskOp("hub_backlog_pull", { id: Number(id), revision: Number(revision), reason: args.slice(3).join(" ") }));
+    if (sub === "pull-ready" && operands.length >= 4) return shown((data, columns, now) => renderBacklogResult("pull-ready", data, columns, now))(taskOp("hub_backlog_pull", { id: Number(id), revision: Number(revision), reason: operands.slice(3).join(" ") }));
     if (sub === "split" && value && reason.length) {
       let parts: unknown;try { parts=JSON.parse(value); } catch { return fail("split parts must be JSON"); }
-      return console.log(await taskOp("hub_backlog_split", { id: Number(id), revision: Number(revision), parts, reason: reason.join(" ") }));
+      return shown((data, columns, now) => renderBacklogResult("split", data, columns, now))(taskOp("hub_backlog_split", { id: Number(id), revision: Number(revision), parts, reason: reason.join(" ") }));
     }
-    if (sub === "undo" && args.length === 3) return console.log(await taskOp("hub_backlog_undo", { id: Number(id), revision: Number(revision) }));
+    if (sub === "undo" && operands.length === 3) return shown((data, columns, now) => renderBacklogResult("undo", data, columns, now))(taskOp("hub_backlog_undo", { id: Number(id), revision: Number(revision) }));
     if (!["plan", "pin"].includes(sub ?? "") || !value || !reason.length) fail("planning needs fields and a reason");
     let fields: unknown;
     try { fields = sub === "pin" ? { pinned: value === "true" ? true : value === "false" ? false : undefined } : JSON.parse(value); }
     catch { return fail("planning fields must be JSON"); }
     if (sub === "pin" && value !== "true" && value !== "false") fail("pin must be true or false");
-    console.log(await taskOp("hub_backlog_plan", { id: Number(id), revision: Number(revision), fields, reason: reason.join(" ") }));
+    return shown((data, columns, now) => renderBacklogResult(sub as "plan" | "pin", data, columns, now))(taskOp("hub_backlog_plan", { id: Number(id), revision: Number(revision), fields, reason: reason.join(" ") }));
   },
 
   release: async () => {
-    const [sub, name, revision, value] = args;
-    if (sub === "list" && args.length === 1) return console.log(await taskOp("hub_release_list", {}));
-    if (sub === "show" && name && args.length === 2) {
-      return console.log(await taskOp("release_show", { name }));
-    }
-    if (sub === "new" && name && revision && args.length === 4 && /^\d+$/.test(value ?? "")) return console.log(await taskOp("release_new", { name, goal: revision, order: Number(value) }));
+    const split = splitPresentation(args, { edges: true }), operands = split.operands;
+    const [sub, name, revision, value] = operands;
+    const present = outputOptions(split.flags); // before any request: an invalid --color must refuse before a mutation is sent
+    const shown = (render: (data: any, columns?: number, now?: number) => Span[][]) => async (text: Promise<string>) => showToolText(render, await text, present);
+    if (sub === "list" && operands.length === 1) return shown(renderReleaseList)(taskOp("hub_release_list", {}));
+    if (sub === "show" && name && operands.length === 2) return shown(renderReleaseShow)(taskOp("release_show", { name }));
+    if (sub === "new" && name && revision && operands.length === 4 && /^\d+$/.test(value ?? "")) return shown(renderReleaseNew)(taskOp("release_new", { name, goal: revision, order: Number(value) }));
     if (!name || !/^\d+$/.test(revision ?? "")) fail("usage: ahub release new <name> <goal> <order>|list|show <name>|plan <name> <revision> <dates-json>|activate|freeze|ship|drop <name> <revision>");
     const states: Record<string, string> = { activate: "active", freeze: "frozen", ship: "shipped", drop: "dropped" };
     let fields: unknown;
-    if (sub === "plan" && value && args.length === 4) {
+    if (sub === "plan" && value && operands.length === 4) {
       try { fields = JSON.parse(value); } catch { return fail("release dates must be JSON"); }
-    } else if (sub && Object.hasOwn(states, sub) && args.length === 3) fields = { state: states[sub] };
+    } else if (sub && Object.hasOwn(states, sub) && operands.length === 3) fields = { state: states[sub] };
     else return fail("invalid release command");
-    console.log(await taskOp("release_change", { name, revision: Number(revision), fields }));
+    return shown(renderReleaseChange)(taskOp("release_change", { name, revision: Number(revision), fields }));
   },
 
   deliverables: async () => {
@@ -1256,6 +1308,9 @@ const commands: Record<string, () => Promise<void> | void> = {
   },
 
   sdlc: async () => {
+    const args = sdlcOperands(), present = SDLC_READ.includes(args[0] ?? "") ? outputOptions() : undefined;
+    /** The human form (#814). Each site keeps its own `if (present.json) console.log(JSON.stringify(...))`, so the JSON branch stays visible to the guard test. */
+    const human = (render: (data: any, columns?: number, now?: number) => Span[][], data: unknown) => printOutput(render(data, present!.columns, Date.now()), present!.color);
     const sub = args[0], id = args[1] === undefined ? undefined : Number(args[1]);
     if (sub === "authorize-release") {
       if (args.length !== 2 || !validReleaseVersion(args[1])) fail("usage: ahub sdlc authorize-release <version>");
@@ -1263,7 +1318,7 @@ const commands: Record<string, () => Promise<void> | void> = {
       const commit = result.stdout?.trim();
       if (result.status !== 0 || !commit || !/^[a-f0-9]{40}$/.test(commit)) fail("candidate commit unavailable");
       const hub = await connect();
-      try { const reply = await hub.request({ t: "sdlc", op: sub, version: args[1], commit }, 30_000); if (!reply.ok) fail(reply.error); console.log(JSON.stringify(reply.authorization, null, 2)); }
+      try { const reply = await hub.request({ t: "sdlc", op: sub, version: args[1], commit }, 30_000); if (!reply.ok) fail(reply.error); if (present!.json) console.log(JSON.stringify(reply.authorization, null, 2)); else human(renderAuthorization, reply.authorization); }
       finally { hub.close(); }
       return;
     }
@@ -1305,7 +1360,7 @@ const commands: Record<string, () => Promise<void> | void> = {
       const repo = args[1], liveIssues = args.slice(2).map(Number);
       if (!repo || args.length > 34 || (sub === "queue" && args.length !== 2) || liveIssues.some(id => !Number.isSafeInteger(id) || id <= 0)) fail("usage: ahub sdlc queue <owner/repository> | release <owner/repository> [live-issue...]");
       const hub = await connect();
-      try { const reply = await hub.request({ t: "sdlc", op: sub, repo, liveIssues }, 30_000); if (!reply.ok) fail(reply.error); console.log(JSON.stringify(reply, null, 2)); }
+      try { const reply = await hub.request({ t: "sdlc", op: sub, repo, liveIssues }, 30_000); if (!reply.ok) fail(reply.error); if (present!.json) console.log(JSON.stringify(reply, null, 2)); else human(sub === "queue" ? renderSdlcQueue : renderSdlcRelease, reply); }
       finally { hub.close(); }
       return;
     }
@@ -1330,12 +1385,14 @@ const commands: Record<string, () => Promise<void> | void> = {
     }
     if (sub === "costs") {
       if (args.length > 2) fail("usage: ahub sdlc costs [owner/repository]");
-      return console.log(await taskOp("hub_sdlc_costs", { ...(args[1] ? { repo: args[1] } : {}) }));
+      const text = await taskOp("hub_sdlc_costs", { ...(args[1] ? { repo: args[1] } : {}) });
+      return showToolText(renderSdlcCosts, text, present!);
     }
     if (sub === "metrics") {
       const flags = takeFlags(args.slice(1), ["--since"], []);
       if (flags.rest.length) fail("usage: ahub sdlc metrics [--since <YYYY-MM-DD|ISO time>]");
-      return console.log(await taskOp("hub_sdlc_metrics", { ...(flags.one["--since"] !== undefined ? { since: flags.one["--since"] } : {}) }));
+      const text = await taskOp("hub_sdlc_metrics", { ...(flags.one["--since"] !== undefined ? { since: flags.one["--since"] } : {}) });
+      return showToolText(renderSdlcMetrics, text, present!);
     }
     if (sub === "plan-review") {
       const revision = Number(args[2]);
@@ -1356,6 +1413,20 @@ const commands: Record<string, () => Promise<void> | void> = {
       } finally { hub.close(); }
       return;
     }
+    if (sub === "merge") {
+      // #786 T1: the guarded merge of one approved task; a person or the configured conductor asks, the daemon re-reads every gate.
+      const flags = takeFlags(args.slice(2), [], []);
+      const dryRun = flags.rest.includes("--dry-run");
+      if (flags.rest.some(arg => arg !== "--dry-run") || !Number.isSafeInteger(id) || id! <= 0) fail("usage: ahub sdlc merge <task> [--dry-run]");
+      const hub = await connect();
+      try {
+        const reply = await hub.request({ t: "sdlc", op: "merge", id, ...(dryRun ? { dryRun: true } : {}) }, 60_000);
+        if (!reply.ok) fail(reply.error);
+        console.log(JSON.stringify({ task: reply.task, mode: reply.mode, ran: reply.ran, decision: reply.decision, ...(reply.argv ? { argv: reply.argv } : {}), ...(reply.refused ? { refused: reply.refused } : {}), ...(reply.result ? { result: reply.result } : {}) }, null, 2));
+        if (reply.decision === "refused" || reply.ran && reply.result?.state !== "merged") process.exitCode = 1;
+      } finally { hub.close(); }
+      return;
+    }
     if (sub === "accept") {
       // #481 S1: the person accepts the task's spec issue at its current body; agent shells are refused before this runs.
       const flags = takeFlags(args.slice(2), ["--issue", "--repo"], []);
@@ -1379,12 +1450,19 @@ const commands: Record<string, () => Promise<void> | void> = {
     try {
       const reply = await hub.request({ t: "sdlc", op: sub, ...(id === undefined ? {} : { id }) }, 30_000);
       if (!reply.ok) fail(reply.error);
-      console.log(JSON.stringify(reply, null, 2));
+      // `sdlc export` is a data format by purpose (#814): it stays JSON and never reaches a renderer.
+      if (sub === "export") console.log(JSON.stringify(reply, null, 2));
+      else if (present!.json) console.log(JSON.stringify(reply, null, 2));
+      else human(sub === "explain" ? renderSdlcExplain : renderSdlcStatus, reply);
     } finally { hub.close(); }
   },
 
   task: async () => {
-    const [sub, ...rest] = args;
+    const presentation = splitPresentation(args, { valueFlags: ["--reason", "--superseded-by", "--revision"], edges: true });
+    const shownTask = (render: (data: any, columns?: number, now?: number) => Span[][]) => async (text: Promise<string>) => showToolText(render, await text, outputOptions(presentation.flags));
+    // task show and task cancel read their presentation options before the request goes out (a refusal after a cancel would invite a retry of work already done)
+    if (["show", "cancel"].includes(args[0] ?? "")) outputOptions(presentation.flags);
+    const [sub, ...rest] = ["show", "cancel"].includes(args[0] ?? "") ? presentation.operands : args;
     if (sub === "role") {
       if (rest.length !== 2 || !/^[1-9]\d*$/.test(rest[0]!)) fail("usage: ahub task role <id> <role|none>");
       const hub = await connect();
@@ -1396,9 +1474,13 @@ const commands: Record<string, () => Promise<void> | void> = {
       const { one, rest: positional } = takeFlags(rest, ["--reason", "--superseded-by", "--revision"], []);
       const revision = one["--revision"] === undefined ? undefined : Number(one["--revision"]);
       if (positional.length !== 1 || !/^[1-9]\d*$/.test(positional[0]!) || !one["--reason"]?.trim() || (revision !== undefined && (!/^\d+$/.test(one["--revision"]!) || !Number.isSafeInteger(revision)))) fail("usage: ahub task cancel <id> --reason <text> [--superseded-by <ref>] [--revision N]");
-      return console.log(await taskOp("hub_task_cancel", { id: Number(positional[0]), reason: one["--reason"], ...(one["--superseded-by"] === undefined ? {} : { superseded_by: one["--superseded-by"] }), ...(revision === undefined ? {} : { revision }) }));
+      return shownTask(renderTaskCancel)(taskOp("hub_task_cancel", { id: Number(positional[0]), reason: one["--reason"], ...(one["--superseded-by"] === undefined ? {} : { superseded_by: one["--superseded-by"] }), ...(revision === undefined ? {} : { revision }) }));
+    }
+    if (sub === "show") {
+      // a stray operand (for example the value of a `--color always` that is not the `--color=` form) is a usage error, never silently ignored
+      if (rest.length !== 1) fail("usage: ahub task show <id> [--json] [--full] [--color=auto|always|never]");
+      return shownTask(renderTaskShow)(taskOp("task_show", { id: rest[0] }));
     }
-    if (sub === "show") return console.log(await taskOp("task_show", { id: rest[0] }));
     if (sub === "escalate") return console.log(await taskOp("task_escalate", { id: rest[0] }));
     if (sub === "assign") {
       const { one, rest: positional } = takeFlags(rest, ["--role", "--revision"], []);
@@ -1489,7 +1571,7 @@ const commands: Record<string, () => Promise<void> | void> = {
       const reply = await hub.request({ t: "peer_stop", peer }, 35_000);
       if (reply.ok !== true) {
         const error = String(reply.error ?? "peer stop request refused");
-        fail(/unknown (?:control )?(?:message|request|command)(?:\b|:)|this hub does not know "peer_stop"/i.test(error) ? `${error}; upgrade the running hub to use ahub stop` : error);
+        fail(/unknown (?:control )?(?:message|request|command)(?:\b|:)|this hub does not know "peer_stop"/i.test(error) ? `${error}; upgrade the running hub to use ahub stop` : error,reply.refusalAudited===true,reply.authorityRefused);
       }
       console.log(`${peer}: ${reply.state}`);
     } finally { hub.close(); }
@@ -1525,7 +1607,7 @@ const commands: Record<string, () => Promise<void> | void> = {
     const hub = await connect();
     try {
       requireNamedPeerFeature(hub, peer);
-      const request = async (message: Record<string, unknown>) => { const reply = await hub.request(message, 35_000); if (reply.ok !== true) fail(String(reply.error ?? "roster request refused")); return reply; };
+      const request = async (message: Record<string, unknown>) => { const reply = await hub.request(message, 35_000); if (reply.ok !== true) fail(String(reply.error ?? "roster request refused"),reply.refusalAudited===true,reply.authorityRefused); return reply; };
       if (sub === "list") {
         const view = await request({ t: "settings_get" });
         if (!Array.isArray(view.roster)) fail("upgrade the running hub to use ahub roster");
@@ -1591,7 +1673,7 @@ const commands: Record<string, () => Promise<void> | void> = {
         const reply = await hub.request(message, 35_000);
         if (reply.ok !== true) {
           const error = String(reply.error ?? "settings request refused");
-          fail(/unknown (?:control )?(?:message|request|command)(?:\b|:)|this hub does not know "settings_/i.test(error) ? `${error}; upgrade the running hub to use ahub settings` : error);
+          fail(/unknown (?:control )?(?:message|request|command)(?:\b|:)|this hub does not know "settings_/i.test(error) ? `${error}; upgrade the running hub to use ahub settings` : error,reply.refusalAudited===true,reply.authorityRefused);
         }
         return reply;
       };
@@ -1719,8 +1801,29 @@ const commands: Record<string, () => Promise<void> | void> = {
     } finally { hub.close(); }
   },
 
-  logs: () => exec("tail", [args.includes("-f") ? "-f" : "-n100", join(stateDir, "hub.log")]),
-  export: () => {
+  logs: async () => {
+    if (identity.role !== "tools") return exec("tail", [args.includes("-f") ? "-f" : "-n100", join(stateDir, "hub.log")]);
+    const hub=await connect();const pending:string[]=[];let ready=false,incompleteShown=false;
+    hub.onPush=message=>{if(message.t==="operational_log" && typeof message.line==="string"){if(message.complete===false && !incompleteShown){operationalIncomplete(message,"log");incompleteShown=true;}if(ready)console.log(message.line);else if(pending.length<100)pending.push(message.line);}};
+    try {
+      const result=await hub.request({t:"conductor_operational",op:"logs",follow:args.includes("-f")});
+      if(result.ok!==true)fail(String(result.error??"operational logs unavailable"),result.refusalAudited===true,result.authorityRefused);
+      for(const line of result.lines??[])console.log(line);
+      ready=true;for(const line of pending)console.log(line);
+      if(!incompleteShown){operationalIncomplete(result,"log");if(result.complete===false)incompleteShown=true;}
+      if(args.includes("-f"))await new Promise<void>(resolve=>{
+        const finish=()=>{process.off("SIGINT",finish);resolve();};
+        hub.onClose=finish;process.once("SIGINT",finish);
+      });
+    } finally {hub.close();}
+  },
+  export: async () => {
+    if(identity.role==="tools") {
+      const hub=await connect();
+      try {const result=await hub.request({t:"conductor_operational",op:"export",since:since()});if(result.ok!==true)fail(String(result.error??"operational export unavailable"),result.refusalAudited===true,result.authorityRefused);for(const row of result.events??[])console.log(JSON.stringify(row));operationalIncomplete(result,"event");}
+      finally {hub.close();}
+      return;
+    }
     for (const e of readEvents(join(stateDir, "events.jsonl"), since())) console.log(JSON.stringify(e));
   },
   bench: async () => {
@@ -2130,7 +2233,12 @@ const commands: Record<string, () => Promise<void> | void> = {
       console.log(options.json ? JSON.stringify(report, null, 2) : formatMemoryStaleAnchors(report));
       return;
     }
-    if (args.includes("--orphans")) return orphanDoctor(args.includes("--kill"), options);
+    if (args.includes("--orphans")) {
+      if(identity.role==="tools" && args.includes("--kill")) {
+        const hub=await connect();try {const result=await hub.request({t:"conductor_operational",op:"orphans"},10_000);if(result.ok!==true)fail(String(result.error??"orphan inspection unavailable"),result.refusalAudited===true,result.authorityRefused);console.log(JSON.stringify(result,null,2));}finally{hub.close();}return;
+      }
+      return orphanDoctor(args.includes("--kill"), options);
+    }
     const version = (bin: string) => {
       const res = spawnSync(bin, ["--version"], { encoding: "utf8" });
       return res.status === 0 ? res.stdout.trim().split("\n")[0]! : undefined;
@@ -2287,8 +2395,27 @@ function inspectDoctorRouting(cwd: string): { routing?: Routing; errors: string[
 }
 
 async function runConductorCommand(): Promise<void> {
+  const operation=conductorOperation(cmd,args);
+  if(operation) {
+    const unavailable=`conductor authorization unavailable; nothing was executed; ${OPERATIONAL_PERSON_GUIDANCE}`;
+    const descriptor=readControl(stateDir);
+    if(!descriptor?.instanceId || !descriptor.projectId || !descriptor.pid || !descriptor.pidSignature || processLiveness(descriptor.pid,descriptor.pidSignature)!=="live")fail(unavailable);
+    let hub:ControlClient;
+    try {hub=await connect(3000);} catch {fail(unavailable);}
+    let release:(()=>void)|undefined;
+    try {
+      let result:any;
+      try {result=await hub.request({t:"conductor_operational",op:"authorize",command:operation},3000);} catch {fail(unavailable);}
+      if(result.ok!==true)fail(result.authorityRefused===true || result.authorityRefused===false?String(result.error??unavailable):unavailable,result.refusalAudited===true,result.authorityRefused);
+      if(!hub.instanceId)fail(unavailable);
+      release=ControlClient.pinInstance(stateDir,hub.instanceId);
+      await commands[cmd]!();
+    } finally {release?.();hub.close();}
+    return;
+  }
   let op: string;
   let input: Record<string, unknown>;
+  if (cmd === "sdlc") return commands.sdlc!(); // #786: `sdlc merge` is the one conductor-class sdlc subcommand; the daemon checks the role.
   if (cmd === "task") {
     op = args[0] === "assign" ? "hub_task_assign" : "hub_task_escalate";
     const { one, rest: positional } = takeFlags(args.slice(1), args[0] === "assign" ? ["--role"] : [], []);