@staix/agent-hub 0.12.35 → 0.12.36

package/plugins/agent-hub/server.js

@@ -44,12 +44,35 @@ var __esm = (fn, res, err) => () => {
   return res;
 };
 
+// src/hub/claude-state.ts
+function claudeStateFile(base, peer) {
+  return peer.includes("-") && PEER.test(peer) ? `${base}.${peer}.json` : `${base}.json`;
+}
+var PEER;
+var init_claude_state = __esm(() => {
+  PEER = /^[a-z][a-z0-9-]{0,31}$/;
+});
+
 // src/adapters/definitions/native-cli-entry-claude.ts
 import { readFileSync } from "fs";
 import { join } from "path";
 import { randomUUID } from "crypto";
 async function runClaudeEntry(ctx) {
   const { args, cwd, stateDir, cliDir, unattendedEnv, projectConfig, fail } = ctx;
+  const peer = ctx.instance ?? "claude";
+  if (ctx.hubStarted) {
+    if (args.includes("--print-command") || args.includes("--dry-run"))
+      return console.log(JSON.stringify({ peer, start: "hub", note: "a headless reviewer the hub runs per review" }, null, 2));
+    const hub = await ctx.connect();
+    try {
+      const res = await hub.request({ t: "start", peer, operationId: process.env.AGENTHUB_RECOVERY_OPERATION });
+      if (res.ok !== true)
+        fail(String(res.error ?? `${peer} was not started`));
+    } finally {
+      hub.close();
+    }
+    return console.log(`${peer} started: a headless reviewer the hub runs per review (stop it with ahub stop ${peer})`);
+  }
   const { launcherPreview, readControl, recordTerminalLaunch, claudeObservationHooks, buildLaunch, runClaudeLaunch, processSignature, recordClaudeLaunch, cleanupStaleClaudeSettings, nativeLaunchEnv, childEnv, cleanupClaudeSettings } = ctx.helpers;
   if (args.includes("--print-command") || args.includes("--dry-run")) {
     try {
@@ -61,7 +84,7 @@ async function runClaudeEntry(ctx) {
   const control = readControl(stateDir);
   if (control?.instanceId) {
     process.env.AGENTHUB_INSTANCE_ID = control.instanceId;
-    const terminal = await recordTerminalLaunch("claude", cwd, stateDir, control.instanceId);
+    const terminal = await recordTerminalLaunch(peer, cwd, stateDir, control.instanceId, ctx.instance ? { executionCwd: cwd } : undefined);
     if (!terminal)
       process.env.AGENTHUB_LAUNCH_ID = randomUUID();
   }
@@ -74,20 +97,22 @@ async function runClaudeEntry(ctx) {
   const facts = claudeObservationHooks(projectConfig(), { script: join(cliDir, "facts-hook.ts"), stateDir });
   let previousLaunch;
   try {
-    previousLaunch = JSON.parse(readFileSync(join(stateDir, "claude-launch.json"), "utf8"));
+    previousLaunch = JSON.parse(readFileSync(join(stateDir, claudeStateFile("claude-launch", peer)), "utf8"));
   } catch {}
   const launch = buildLaunch("claude", args, { unattended: unattendedEnv, statusLine: { script: join(cliDir, "statusline-tee.ts"), stateDir, ...original ? { original } : {} }, ...facts ? { facts } : {} });
   let result;
   try {
     let launchRecord;
     if (control?.instanceId) {
-      launchRecord = { instanceId: control.instanceId, launchId: process.env.AGENTHUB_LAUNCH_ID, permissionHook: launch.permissionHook === true, hookPurpose: launch.hookPurpose, settingsFile: launch.settingsFile, launcherPid: process.pid, launcherSignature: processSignature(process.pid), unattended: launch.unattended === true };
+      launchRecord = { ...ctx.instance ? { peer } : {}, instanceId: control.instanceId, launchId: process.env.AGENTHUB_LAUNCH_ID, permissionHook: launch.permissionHook === true, hookPurpose: launch.hookPurpose, settingsFile: launch.settingsFile, launcherPid: process.pid, launcherSignature: processSignature(process.pid), unattended: launch.unattended === true };
       recordClaudeLaunch(stateDir, launchRecord);
       cleanupStaleClaudeSettings(stateDir, previousLaunch);
     }
     if (launch.warning)
       console.error(launch.warning);
     const env = nativeLaunchEnv("claude", childEnv());
+    if (ctx.instance)
+      env.AGENTHUB_PEER_ID = peer;
     result = await runClaudeLaunch(launch, { cwd, stateDir, env: { ...env, AGENTHUB_STATE_DIR: stateDir, AGENTHUB_PROJECT_DIR: cwd }, ...launchRecord ? { record: launchRecord } : {} });
   } finally {
     cleanupClaudeSettings(stateDir, launch.settingsFile);
@@ -96,7 +121,9 @@ async function runClaudeEntry(ctx) {
     fail(`cannot run ${launch.cmd}: ${result.error.message}`);
   process.exit(result.status ?? 1);
 }
-var init_native_cli_entry_claude = () => {};
+var init_native_cli_entry_claude = __esm(() => {
+  init_claude_state();
+});
 
 // src/adapters/definitions/native-cli-entry-codex.ts
 async function runCodexEntry(ctx) {
@@ -142,6 +169,10 @@ function rosterInStatus(status, peer) {
   const row = rows.find((r) => !!r && typeof r === "object" && r.peer === peer);
   return typeof row?.on === "boolean" ? row.on : undefined;
 }
+function bundleInStatus(status) {
+  const value = status?.pluginBundle;
+  return typeof value === "string" && value.startsWith("/") && /[\\/]plugins[\\/]agent-hub[\\/]server\.js$/.test(value) ? value : undefined;
+}
 
 // src/adapters/definitions/native-cli-entry-jcode.ts
 import { resolve } from "path";
@@ -168,7 +199,7 @@ async function runJcodeEntry(ctx) {
       fail("cannot read jcode's roster membership from the running hub; upgrade or restart it, then retry (nothing was started)");
     if (!rostered)
       fail("jcode is off roster; add it with ahub roster add jcode");
-    const written = configureJcodeMcp(cwd, stateDir, resolve(cliDir, "../../plugins/agent-hub/server.js"));
+    const written = configureJcodeMcp(cwd, stateDir, bundleInStatus(snapshot) ?? resolve(cliDir, "../../plugins/agent-hub/server.js"));
     if (written.tracked)
       console.error(".jcode/mcp.json is tracked; review this local machine-path change before committing it");
     const reply = await hub.request({ t: "start", peer: "jcode", args: { mode: "headless", model: one["--model"], providerProfile: one["--provider-profile"], sessionId: one["--session-id"] }, operationId: process.env.AGENTHUB_RECOVERY_OPERATION }, 65000);
@@ -261,7 +292,7 @@ async function runKimiEntry(ctx) {
         fail(admission.error);
       let result;
       try {
-        const written = configureKimiMcp(cwd, stateDir, resolve2(cliDir, "../../plugins/agent-hub/server.js"), "tui");
+        const written = configureKimiMcp(cwd, stateDir, bundleInStatus(snapshot) ?? resolve2(cliDir, "../../plugins/agent-hub/server.js"), "tui");
         if (written.tracked)
           console.error(".kimi-code/mcp.json is tracked; the agent-hub entry contains machine paths. Review this local change before committing it.");
         result = spawnSync(launch.cmd, launch.args, { cwd, stdio: "inherit", env: { ...nativeLaunchEnv("kimi", childEnv()), AGENTHUB_STATE_DIR: stateDir, AGENTHUB_PROJECT_DIR: cwd } });
@@ -6781,7 +6812,7 @@ function catalogAssignments(raw) {
     throw new Error("catalog_roles must be a bounded peer map");
   const out = Object.create(null);
   for (const [peer, ids] of Object.entries(raw)) {
-    if (!PEER.test(peer) || ["user", "hub", "digest"].includes(peer) || !Array.isArray(ids) || ids.length > 2 || new Set(ids).size !== ids.length || ids.some((id) => typeof id !== "string" || !ID.test(id)))
+    if (!PEER2.test(peer) || ["user", "hub", "digest"].includes(peer) || !Array.isArray(ids) || ids.length > 2 || new Set(ids).size !== ids.length || ids.some((id) => typeof id !== "string" || !ID.test(id)))
       throw new Error("catalog_roles takes at most two distinct role ids per peer");
     out[peer] = [...ids];
   }
@@ -6808,7 +6839,7 @@ function catalogSection(roles) {
 
 `);
 }
-var ROLE_SECTIONS, BASES2, CLASSES2, ID, PEER;
+var ROLE_SECTIONS, BASES2, CLASSES2, ID, PEER2;
 var init_roles = __esm(() => {
   init_envelope();
   init_shipped_roles();
@@ -6816,7 +6847,7 @@ var init_roles = __esm(() => {
   BASES2 = ["planner", "implementer", "verifier", "reviewer"];
   CLASSES2 = ["plan", "implement", "bulk_edit", "test", "review", "summarize", "triage"];
   ID = /^[a-z][a-z0-9-]{0,47}$/;
-  PEER = /^[a-z][a-z0-9-]{0,31}$/;
+  PEER2 = /^[a-z][a-z0-9-]{0,31}$/;
 });
 
 // src/hub/profiles.ts
@@ -6934,14 +6965,22 @@ function profileTaskTools(profile = "dev", stages, criteria = false) {
       const selectedPlan = { ...plan, properties: Object.fromEntries(data.plan_keys.map((key) => [key, plan.properties[key] ?? list(key === "sections" ? "document heading anchors, such as report.md#methods" : key === "sources" ? "citation ids, DOI or source URL ids" : "short claim ids to verify")])) };
       properties.parts = { ...parts, items: { ...parts.items, properties: { ...parts.items.properties, plan: selectedPlan } } };
     }
+    if (criteria && properties.plan) {
+      const current = properties.plan;
+      properties.plan = { ...current, properties: { ...current.properties, ...costPlanProperties } };
+    }
+    if (criteria && tool.name === "hub_backlog_split") {
+      const parts = properties.parts;
+      properties.parts = { ...parts, items: { ...parts.items, properties: { ...parts.items.properties, plan: { ...parts.items.properties.plan, properties: { ...parts.items.properties.plan.properties, ...costPlanProperties } } } } };
+    }
     return { ...tool, ...customProfile && tool.name === "hub_task_propose" ? { description: tool.description + ` Selected profile ${data.name}: ${Object.keys(data.classes).join(", ")}. Routing uses their existing base classes.` } : {}, inputSchema: { ...tool.inputSchema, properties } };
   });
 }
-var ACTIONABLE_MESSAGE_INSTRUCTION = "Do not use [FYI] for PR ready, done, submitted, ruling needed, blocker, or changed contract or path messages: each requires action from the recipient. Use [FYI] only for progress or information that needs no action. hub_task_done and hub_review already notify the assigned recipients; no duplicate hub_send chat is needed.", str2, id, refs, list = (description) => ({ type: "array", items: str2, description }), plan, acceptPlan, tool = (name, description, properties, required = []) => ({
+var ACTIONABLE_MESSAGE_INSTRUCTION = "Do not use [FYI] for PR ready, done, submitted, ruling needed, blocker, or changed contract or path messages: each requires action from the recipient. Use [FYI] only for progress or information that needs no action. hub_task_done and hub_review already notify the assigned recipients; no duplicate hub_send chat is needed.", str2, id, refs, list = (description) => ({ type: "array", items: str2, description }), costPlanProperties, plan, acceptPlan, tool = (name, description, properties, required = []) => ({
   name,
   description,
   inputSchema: { type: "object", properties, required, additionalProperties: false }
-}), BOUNDED_TASK_TOOLS, TASK_TOOLS, TASK_TOOL_NAMES, CONDUCTOR_TOOLS, CONDUCTOR_TOOL_NAMES, ROLE_TEXT, DEFAULT_ROLES;
+}), BOUNDED_TASK_TOOLS, TASK_TOOLS, PLANNER_REVIEW_TOOLS, TASK_TOOL_NAMES, CONDUCTOR_TOOLS, CONDUCTOR_TOOL_NAMES, ROLE_TEXT, DEFAULT_ROLES;
 var init_hub_tools = __esm(() => {
   init_sdlc();
   init_profiles();
@@ -6956,6 +6995,10 @@ var init_hub_tools = __esm(() => {
     properties: { branch: str2, commit: str2, paths: { type: "array", items: str2 } },
     additionalProperties: false
   };
+  costPlanProperties = {
+    review: { type: "object", properties: { scope: { type: "string", enum: ["none", "delta", "full"] }, reviewers: { type: "integer", minimum: 0, maximum: 8 } }, required: ["scope", "reviewers"], additionalProperties: false },
+    ci: { type: "string", enum: ["focused", "full", "reuse"] }
+  };
   plan = {
     type: "object",
     description: "what you will change, before you start. Owners of open tasks on the same files or symbols see it, and get a notice when your task is done.",
@@ -6988,7 +7031,7 @@ var init_hub_tools = __esm(() => {
     tool("hub_task_done", "Mark your task finished. It goes to its reviewer with your summary and refs; no duplicate hub_send chat is needed. When the project configures a check for its class, the hub runs it first and the result comes as a task message: a failed check keeps the task with you.", { id, summary: { type: "string", description: "what changed, why, and the check you ran with its result" }, refs }, ["id", "summary"]),
     tool("hub_sdlc_record", "Record artifact ids or claimed local checks on your task. This grants no authority or external-check evidence. Only its owner/reviewer or the person may record; only its reviewer/person may name a reviewed head or phase checklist. Phase evidence refs are content hashes, not external verification.", { id, receipt: { type: "object", properties: { stage: { type: "string", enum: ["spec", "plan", "implement", "review", "verify", "merge", "release"] }, repo: str2, issue: id, pr: id, localHead: str2, localResult: { type: "string", enum: ["passed", "failed", "unknown"] }, reviewedHead: str2, phase: { type: "object", properties: { id: str2, head: str2, tasks: { type: "array", maxItems: 64, items: { type: "object", properties: { id, after: { type: "array", maxItems: 16, items: id } }, required: ["id", "after"], additionalProperties: false } }, criteria: { type: "array", maxItems: 32, items: { type: "object", properties: { id: str2, required: { type: "boolean" }, result: { type: "string", enum: ["verified", "failed", "unverified"] }, refs: { type: "array", maxItems: 8, items: str2 } }, required: ["id", "required", "result", "refs"], additionalProperties: false } } }, required: ["id", "tasks", "criteria"], additionalProperties: false } }, additionalProperties: false } }, ["id", "receipt"]),
     tool("hub_task_list", "The task board. PII tasks show as [pii].", { state: { type: "string", enum: ["proposed", "in_progress", "in_review", "approved", "changes_requested", "cancelled"] }, ready: { type: "boolean", description: "only proposed tasks with nothing left to wait for" } }),
-    tool("hub_review", "Give your verdict on a task you were asked to review: map the changed signatures and call sites to the task's plan or detail, read the check result (hub_task_show has it, with the done summary), and list what is unmet. The verdict notifies the task owner; no duplicate hub_send chat is needed. Consecutive changes_requested verdicts (three by default, `tasks.escalate_after`) move the task to another peer.", { id, head: { type: "string", description: "full SHA actually reviewed; enforce binds approval to the current PR head" }, verdict: { type: "string", enum: ["approved", "changes_requested"] }, note: str2, unmet: { type: "array", items: str2, description: "each requirement of the plan or detail that the change does not meet" } }, ["id", "verdict"]),
+    tool("hub_review", "Give your verdict on a task you were asked to review: map the changed signatures and call sites to the task's plan or detail, read the check result (hub_task_show has it, with the done summary), and list what is unmet. The verdict notifies the task owner; no duplicate hub_send chat is needed. Consecutive changes_requested verdicts (three by default, `tasks.escalate_after`) move the task to another peer.", { id, head: { type: "string", description: "full SHA actually reviewed; enforce binds approval to the current PR head" }, verdict: { type: "string", enum: ["approved", "changes_requested"] }, note: str2, unmet: { type: "array", items: str2, description: "each requirement of the plan or detail that the change does not meet" }, coverage: { type: "object", description: "the review brief's reviewable paths you read (reviewed) and any you did not (skipped, each with a reason); in enforce an approval must account for every one", properties: { reviewed: { type: "array", items: str2 }, skipped: { type: "array", items: { type: "object", properties: { path: str2, reason: str2 }, required: ["path", "reason"] } } } } }, ["id", "verdict"]),
     tool("hub_checkpoint", "Answer a checkpoint request from the hub (quota or context window pressure): what you were doing, what is half done, what whoever continues must know. Write the same to .agenthub/checkpoint.md first if you can.", { summary: str2, request_id: { type: "string", description: "The request id supplied by a context checkpoint request; required for context checkpoints" } }, ["summary"]),
     tool("hub_memory_search", "Search daemon-scoped visible memory, fails first. Query <=200 UTF-8 bytes; default 8, max 20 lines; whole output <=4 KB. Incomplete excerpts are marked. No project argument.", { query: { type: "string", maxLength: 200, description: "At most 200 UTF-8 bytes, enforced by the daemon" }, limit: { type: "integer", minimum: 1, maximum: 20 } }, ["query"]),
     tool("hub_memory_show", "Read up to 8 visible memory ids or unique prefixes (6..64 UTF-8 bytes each). Original ids redirect; unavailable ids share one refusal. Whole output <=8 KB.", { ids: { type: "array", minItems: 1, maxItems: 8, items: { type: "string", minLength: 6, maxLength: 64, description: "6 to 64 UTF-8 bytes" } } }, ["ids"]),
@@ -6996,6 +7039,13 @@ var init_hub_tools = __esm(() => {
     tool("hub_memory_correct", "Propose a correction to a visible memory entry. This creates a machine-local candidate only; a person accepts or rejects it with amem review. It never edits a note. id is an exact id or unique visible prefix; text and reason must each fit 4000 UTF-8 bytes.", { id: str2, text: str2, reason: str2 }, ["id", "text", "reason"]),
     tool("hub_remember", "Save a decision, finding, contract or fail to the memory all agents share (the hub's memory and claude-mem); the other agents also get it with their next message. A fail is an approach you tried that does not work, and why: the most useful note, it stops the others spending their quota on it. Do not retry what a fail note rules out without new evidence. Conclusions worth recalling, not chatter. For kind fail, optional approach, symptom, cause, evidence and retry_when strings compose fixed labeled text; text may be omitted when structured fields are supplied. The complete text must fit 4000 UTF-8 bytes and is refused, never truncated, when oversized. A note on an open task is short-term until the task is approved, when its decisions, contracts and fails become long-term; horizon long keeps it now, scope shared lets the person's other projects find it.", { text: str2, approach: str2, symptom: str2, cause: str2, evidence: str2, retry_when: str2, title: str2, kind: { type: "string", enum: [...NOTE_KINDS] }, task: id, horizon: { type: "string", enum: ["short", "long"] }, scope: { type: "string", enum: ["project", "shared"] } })
   ];
+  PLANNER_REVIEW_TOOLS = [
+    tool("hub_planner_groom", "Read a bounded planner grooming digest of dependencies, repository-scoped overlaps, WIP and blockers. No board change; unavailable evidence stays unknown.", {}),
+    tool("hub_plan_review", "Record a planner review against the task planning revision and host-read issue edit time. Configured planner or person only; never accepts caller issue timestamps.", { id, revision: { type: "integer", minimum: 0 }, reason: { ...str2, maxLength: 1000 }, ...costPlanProperties }, ["id", "revision", "reason"]),
+    tool("hub_sdlc_costs", "Read bounded review and CI cost metrics for linked merged PRs. Planner/person only; metadata only, no board writes. S7 owns automatic band proposals.", { repo: str2 }),
+    tool("hub_backlog_return_untouched", "Return accepted but untouched work to the backlog with its history and planning retained. Refuses execution/branch/commit evidence; planner or person only.", { id, revision: { type: "integer", minimum: 0 }, reason: { ...str2, maxLength: 1000 } }, ["id", "revision", "reason"])
+  ];
+  TASK_TOOLS.push(...PLANNER_REVIEW_TOOLS);
   TASK_TOOL_NAMES = new Set(TASK_TOOLS.map((t) => t.name));
   CONDUCTOR_TOOLS = [
     tool("hub_status", "Inspect public team state, holds, quota windows, task counts and pending approval peer/tool/age. Only the configured conductor may use this tool.", {}),
@@ -7516,6 +7566,246 @@ var init_local_worker = __esm(() => {
   };
 });
 
+// src/hub/review-brief.ts
+var LOCKFILES;
+var init_review_brief = __esm(() => {
+  init_child_process();
+  init_git();
+  LOCKFILES = new Set(["bun.lock", "bun.lockb", "package-lock.json", "yarn.lock", "pnpm-lock.yaml", "Cargo.lock", "poetry.lock", "uv.lock", "go.sum", "composer.lock", "Gemfile.lock"]);
+});
+
+// src/adapters/claude-print.ts
+import { spawn as spawn6 } from "child_process";
+import { randomUUID as randomUUID5 } from "crypto";
+function claudePrintArgs(sessionId, mcpConfig, systemPrompt, privatePaths = []) {
+  return [
+    "-p",
+    "--output-format",
+    "stream-json",
+    "--verbose",
+    "--no-session-persistence",
+    "--session-id",
+    sessionId,
+    "--strict-mcp-config",
+    "--mcp-config",
+    mcpConfig,
+    "--setting-sources",
+    "",
+    "--tools",
+    "Read,Grep,Glob",
+    "--allowedTools",
+    "mcp__agent-hub__hub_review",
+    "mcp__agent-hub__hub_task_show",
+    "Read",
+    "Grep",
+    "Glob",
+    ...privatePaths.length ? ["--disallowedTools", ...readDenyRules(privatePaths)] : [],
+    "--permission-mode",
+    "dontAsk",
+    "--append-system-prompt",
+    systemPrompt
+  ];
+}
+function readDenyRules(paths) {
+  return paths.flatMap((entry) => {
+    const rule = entry.startsWith("/") ? `/${entry}` : `./${entry.replace(/^\.\//, "")}`;
+    return /[*?]/.test(entry) ? [`Read(${rule})`] : [`Read(${rule})`, `Read(${rule.replace(/\/$/, "")}/**)`];
+  });
+}
+var GroupCleanupError, reviewTask = (env) => {
+  if (env.from !== HUB || env.kind !== "review")
+    return;
+  const id = Number(env.refs?.task);
+  return Number.isSafeInteger(id) && id > 0 ? id : undefined;
+}, ClaudePrintPeer;
+var init_claude_print = __esm(() => {
+  init_child_process();
+  init_git();
+  init_review_brief();
+  init_envelope();
+  GroupCleanupError = class GroupCleanupError extends Error {
+  };
+  ClaudePrintPeer = class ClaudePrintPeer extends BasePeer {
+    opts;
+    hubNative = true;
+    generation = 0;
+    child;
+    activeDeliveryId;
+    reviewing;
+    reviewSeq = 0;
+    reviewToken(task) {
+      return this.reviewing === task ? this.reviewSeq : undefined;
+    }
+    constructor(id, opts) {
+      super(id, opts.watchdogMs);
+      this.opts = opts;
+    }
+    recoveryMetadata() {
+      return { launch: { kind: "claude-print", peer: this.id } };
+    }
+    async start() {
+      if (this.child)
+        throw new Error(`${this.id}: an earlier review's process group is still running; stop it first`);
+      this.setState("idle");
+    }
+    async stop(reason) {
+      this.generation++;
+      this.settle("needs_review", reason ?? "review stopped before settlement");
+      if (this.child)
+        this.setState("busy");
+      await this.kill();
+      this.setState("offline");
+    }
+    onWatchdog() {
+      this.generation++;
+      this.settle("needs_review", "review watchdog timeout");
+      this.kill().then(() => {
+        if (this.state === "busy")
+          super.onWatchdog();
+      }, (error) => this.opts.log?.(`[${this.id}] watchdog stop failed, staying busy: ${error.message}`));
+    }
+    async deliver(envs, deliveryId) {
+      if (this.state !== "idle") {
+        if (deliveryId)
+          this.delivery({ id: deliveryId, state: "failed_safe", reason: `${this.id} is ${this.state}` });
+        throw new Error(`${this.id} is ${this.state}`);
+      }
+      const generation = ++this.generation;
+      this.activeDeliveryId = deliveryId;
+      this.setState("busy");
+      if (deliveryId)
+        this.delivery({ id: deliveryId, state: "accepted" });
+      this.run(envs, generation).catch((error) => {
+        if (generation !== this.generation)
+          return;
+        this.settle("needs_review", `claude reviewer failed: ${error.message}`);
+        this.kill().then(() => this.setState("idle"), () => {
+          return;
+        });
+      });
+    }
+    async run(envs, generation) {
+      const missing = [];
+      let started = false;
+      let failure;
+      for (const env of envs) {
+        const task = reviewTask(env);
+        if (task === undefined)
+          continue;
+        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 code;
+        try {
+          code = await this.review(env, task, generation);
+        } catch (error) {
+          if (generation !== this.generation)
+            return;
+          if (error instanceof GroupCleanupError) {
+            this.opts.log?.(`[${this.id}] review of task #${task}: ${error.message}`);
+            this.settle("needs_review", `review process group still running: ${error.message}`);
+            return;
+          }
+          failure = { state: started ? "needs_review" : "failed_safe", reason: `claude reviewer could not start: ${error.message}` };
+          break;
+        }
+        started = true;
+        if (generation !== this.generation)
+          return;
+        let recorded = false;
+        try {
+          recorded = this.opts.verdictSince(task, since);
+        } catch (error) {
+          this.opts.log?.(`[${this.id}] verdict check for task #${task} failed: ${error.message}`);
+        }
+        if (!recorded)
+          missing.push(task);
+        if (code !== 0)
+          this.opts.log?.(`[${this.id}] review of task #${task} exited ${code}`);
+      }
+      if (generation !== this.generation)
+        return;
+      this.settle(failure?.state ?? (missing.length ? "needs_review" : "completed"), failure?.reason ?? (missing.length ? `no verdict recorded for task ${missing.map((id) => `#${id}`).join(", ")}` : undefined));
+      this.setState("idle");
+    }
+    review(env, task, generation) {
+      const [cmd = "claude", ...prefix] = this.opts.command ?? ["claude"];
+      const args = [...prefix, ...claudePrintArgs(randomUUID5(), this.opts.mcpConfig, this.opts.systemPrompt, this.opts.privatePaths)];
+      return new Promise((resolve, reject) => {
+        const child = spawn6(cmd, args, { cwd: this.opts.cwd, detached: true, env: peerChildEnv(this.id), stdio: ["pipe", "pipe", "ignore"] });
+        this.child = child;
+        child.once("error", (error) => {
+          if (this.child === child)
+            this.child = undefined;
+          reject(error);
+        });
+        child.stdin.on("error", () => {});
+        child.once("spawn", () => {
+          trackGroup(child);
+          if (generation !== this.generation) {
+            child.stdin.destroy();
+            return;
+          }
+          this.reviewing = task;
+          this.reviewSeq++;
+          let facts;
+          try {
+            facts = this.opts.facts?.(env);
+          } catch (error) {
+            this.opts.log?.(`[${this.id}] review facts for task #${task} failed: ${error.message}`);
+          }
+          child.stdin.end(`${frame(env)}${facts ? `
+
+${facts}` : ""}`);
+        });
+        let buffer = "";
+        child.stdout.on("data", (chunk) => {
+          if (generation !== this.generation)
+            return;
+          this.touch();
+          buffer += chunk.toString("utf8");
+          for (let i;(i = buffer.indexOf(`
+`)) >= 0; ) {
+            const line = buffer.slice(0, i);
+            buffer = buffer.slice(i + 1);
+            try {
+              const event = JSON.parse(line);
+              if (event.type === "result" && event.usage)
+                this.opts.onUsage?.(event.usage, task);
+            } catch {}
+          }
+        });
+        child.once("exit", (code) => {
+          if (this.child === child)
+            this.reviewing = undefined;
+          stopOwnedProcess(child, { group: true }).then(() => {
+            if (this.child === child)
+              this.child = undefined;
+            resolve(code);
+          }, (error) => reject(new GroupCleanupError(error.message)));
+        });
+      });
+    }
+    settle(state, reason) {
+      const id = this.activeDeliveryId;
+      this.activeDeliveryId = undefined;
+      if (id)
+        this.delivery({ id, state, ...reason ? { reason } : {} });
+    }
+    async kill() {
+      this.reviewing = undefined;
+      const child = this.child;
+      if (!child)
+        return;
+      await stopOwnedProcess(child, { group: true });
+      if (this.child === child)
+        this.child = undefined;
+    }
+  };
+});
+
 // src/adapters/definitions/native-factories.ts
 function createCodex(ctx) {
   if (!("codex" in ctx.daemon))
@@ -7557,6 +7847,12 @@ function createLocal(ctx) {
   init_local_worker();
   return new LocalPeer(ctx.instance, ctx.daemon.local);
 }
+function createClaudeReviewer(ctx) {
+  if (!("claudePrint" in ctx.daemon))
+    throw new Error("Claude reviewer requires its print transport options");
+  init_claude_print();
+  return new ClaudePrintPeer(ctx.instance, ctx.daemon.claudePrint);
+}
 var DAEMON_PORTS;
 var init_native_factories = __esm(() => {
   DAEMON_PORTS = {
@@ -7564,7 +7860,8 @@ var init_native_factories = __esm(() => {
     acp: (options) => ({ acp: options }),
     "owned-acp": (options) => ({ jcode: options }),
     "pi-rpc": (options) => ({ pi: options }),
-    "local-worker": (options) => ({ local: options })
+    "local-worker": (options) => ({ local: options }),
+    "claude-print": (options) => ({ claudePrint: options })
   };
 });
 
@@ -7781,6 +8078,7 @@ function sessionSettings(tee, facts) {
 }
 var CLAUDE_CHANNEL = "plugin:agent-hub@agent-hub", UNATTENDED_WARNING = "WARNING: --unattended disables permission prompts. Other agents' messages are untrusted input and this agent will act on its own judgment without asking you.", sh = (s) => `'${s.replace(/'/g, `'\\''`)}'`;
 var init_launch2 = __esm(() => {
+  init_claude_state();
   init_process_signature();
   init_project();
   init_child_process();
@@ -7812,7 +8110,7 @@ var init_native_cli_launch_common = __esm(() => {
 
 // src/adapters/definitions/native-cli-claude-launch.ts
 import { mkdirSync as mkdirSync4, writeFileSync as writeFileSync2, renameSync, unlinkSync, readFileSync as readFileSync7 } from "fs";
-import { randomUUID as randomUUID5 } from "crypto";
+import { randomUUID as randomUUID6 } from "crypto";
 import { resolve as resolve11, join as join17 } from "path";
 function claudeChannel(userArgs) {
   const bundle = resolve11(import.meta.dir, "../../../plugins/agent-hub/server.js");
@@ -7875,7 +8173,7 @@ function claudeNativeLaunch(ctx) {
       const stateDir = ctx.facts?.stateDir ?? ctx.statusLine?.stateDir;
       if (!stateDir)
         throw new Error("Claude session settings require the hub state directory");
-      const file = join17(stateDir, `claude-settings-${randomUUID5()}.json`);
+      const file = join17(stateDir, `claude-settings-${randomUUID6()}.json`);
       try {
         mkdirSync4(stateDir, { recursive: true, mode: 448 });
         writeFileSync2(`${file}.tmp`, settingsArgs[1], { mode: 384, flag: "wx" });
@@ -8138,7 +8436,7 @@ function sessionId(field) {
     return typeof value === "string" && value ? value : undefined;
   };
 }
-var terminal = (form) => form === "tui", headless = () => false, switches, implementerRoles, dualForms, headlessForms, hubGrants, NATIVE_BUILTIN_DEFINITIONS_WITHOUT_QWEN, palette = (fg) => ({ palette: { fg, bg: "transparent" } }), BUILTIN_DEFINITIONS_WITHOUT_QWEN;
+var terminal = (form) => form === "tui", headless = () => false, switches, implementerRoles, dualForms, headlessForms, hubGrants, CLAUDE_REVIEWER_VARIANT, NATIVE_BUILTIN_DEFINITIONS_WITHOUT_QWEN, palette = (fg) => ({ palette: { fg, bg: "transparent" } }), BUILTIN_DEFINITIONS_WITHOUT_QWEN;
 var init_builtin_metadata = __esm(() => {
   init_native_config_policy();
   init_native_policy_aux();
@@ -8156,6 +8454,27 @@ var init_builtin_metadata = __esm(() => {
     "ask-when-needed": "write and edit inside the project run without asking; shell and git writes still ask",
     "never-ask": "every tool runs without asking, inside the hub sandbox and path guard"
   };
+  CLAUDE_REVIEWER_VARIANT = {
+    api: 1,
+    kind: "claude",
+    displayName: "Claude Code reviewer",
+    family: "claude",
+    transport: "hub-native",
+    roles: Object.freeze(["reviewer"]),
+    defaultOnRoster: true,
+    trust: { onPrem: false, hubSandboxed: false },
+    start: { create: createClaudeReviewer, daemonPort: "claude-print", forms: headlessForms, defaultForm: "headless", ownsTerminal: headless, launch: (ctx) => compatibilityLaunch("claude", ctx), conductorStartable: true, hubSwitches: [], ownedFlags: [] },
+    identity: { mcp: "env" },
+    permission: { modes: {}, unmanaged: "each review runs read-only (Read, Grep, Glob) and may call only hub_review and hub_task_show" },
+    session: { idField: "sessionId", currentId: () => {
+      return;
+    }, freshOnRestore: true, launchKind: "claude-print", crashPlan: () => ({ resume: {}, how: "claude reviewer: starts again; every review runs in a new session" }) },
+    turnEnd: "adapter",
+    budget: { account: "claude" },
+    routing: { reviewOnly: true },
+    cli: { command: "claude", startWords: () => ["claude"] },
+    display: CLAUDE_DISPLAY
+  };
   NATIVE_BUILTIN_DEFINITIONS_WITHOUT_QWEN = Object.freeze([
     {
       api: 1,
@@ -8190,7 +8509,8 @@ var init_builtin_metadata = __esm(() => {
       budget: { account: "claude", checkpoint: true, reader: { source: "claude status line", read: claudeWindows }, context: { source: "claude_statusline", read: claudeContext } },
       cli: { command: "claude", retainedTerminalNotice: claudeRetainedTerminalNotice, stopNotice: () => "this peer belongs to a native terminal; end it in its terminal", startWords: () => ["claude"] },
       display: CLAUDE_DISPLAY,
-      hooks: { recallPlatform: "claude", recallSource: "claude", recallInjected: true, pluginInventory: claudePluginInventory }
+      hooks: { recallPlatform: "claude", recallSource: "claude", recallInjected: true, pluginInventory: claudePluginInventory },
+      reviewerVariant: CLAUDE_REVIEWER_VARIANT
     },
     {
       api: 1,
@@ -8595,6 +8915,12 @@ function immutable(value, seen = new WeakSet) {
     immutable(member, seen);
   return Object.freeze(value);
 }
+function ownField(value, key) {
+  if (!value || typeof value !== "object" || types.isProxy(value) || Array.isArray(value) || ![Object.prototype, null].includes(Object.getPrototypeOf(value)))
+    return;
+  const field = Object.getOwnPropertyDescriptor(value, key);
+  return field && Object.hasOwn(field, "value") && field.enumerable ? field.value : undefined;
+}
 function declaredKind(id, instances) {
   if (!instances || typeof instances !== "object" || types.isProxy(instances) || Array.isArray(instances) || ![Object.prototype, null].includes(Object.getPrototypeOf(instances)))
     return;
@@ -8615,7 +8941,8 @@ function kindOf(id, instances) {
 }
 function definitionOf(id, instances) {
   const kind = kindOf(id, instances);
-  return kind === undefined ? undefined : definitions.get(kind);
+  const definition = kind === undefined ? undefined : definitions.get(kind);
+  return definition?.reviewerVariant && kind !== id && ownField(ownField(instances, id), "start_mode") === "headless" ? definition.reviewerVariant : definition;
 }
 function defaultPeerRoles(includeOptional = false) {
   return Object.fromEntries(ROLE_ORDER.filter((peer) => includeOptional || !definitionOf(peer).optional).map((peer) => [peer, [...definitionOf(peer).roles]]));
@@ -8635,7 +8962,8 @@ function assertNativeCapabilityScope(definition) {
     ["budget.resetSoftTokensOnResume", declared(definition.budget, "resetSoftTokensOnResume")],
     ["session.crashIdentity", declared(definition.session, "crashIdentity")],
     ["start.daemonPort pi-rpc", definition.start.daemonPort === "pi-rpc"],
-    ["routing", definition.routing !== undefined]
+    ["routing", definition.routing !== undefined],
+    ["reviewerVariant", definition.reviewerVariant !== undefined]
   ];
   const field = restricted.find(([, present]) => present)?.[0];
   if (field)
@@ -8655,6 +8983,9 @@ var init_registry = __esm(() => {
   OPTIONAL_PEERS = ["qwen", "jcode"];
   SUPPORTED_PEERS = [...KNOWN_PEERS, ...OPTIONAL_PEERS];
   fixedBuiltinDefinitions = new Set([...NATIVE_BUILTIN_DEFINITIONS_WITHOUT_QWEN, QWEN_DEFINITION]);
+  for (const definition of [...fixedBuiltinDefinitions])
+    if (definition.reviewerVariant)
+      fixedBuiltinDefinitions.add(definition.reviewerVariant);
   ADAPTERS = immutable([
     ...NATIVE_BUILTIN_DEFINITIONS_WITHOUT_QWEN.filter((definition) => definition.kind !== "jcode"),
     QWEN_DEFINITION,
@@ -8664,6 +8995,10 @@ var init_registry = __esm(() => {
   for (const definition of ADAPTERS) {
     assertDaemonEngine(definition);
     assertNativeCapabilityScope(definition);
+    if (definition.reviewerVariant) {
+      assertDaemonEngine(definition.reviewerVariant);
+      assertNativeCapabilityScope(definition.reviewerVariant);
+    }
     if (definition.api !== ADAPTER_API || definitions.has(definition.kind))
       throw new Error("invalid builtin adapter registry");
     definitions.set(definition.kind, definition);
@@ -15779,10 +16114,17 @@ import { join as join22 } from "path";
 init_registry();
 init_hub_tools();
 init_envelope();
+
+// src/hub/spec-read.ts
+init_host_executable();
+init_child_process();
+var BODY_LIMIT = 64 * 1024;
+var RESULT_LIMIT = 80 * 1024;
+var STDOUT_LIMIT = 512 * 1024;
 // package.json
 var package_default = {
   name: "@staix/agent-hub",
-  version: "0.12.35",
+  version: "0.12.36",
   description: "Native multi-agent hub: Claude Code, Codex, Kimi Code, Pi and local inference as peers in one project",
   license: "MIT",
   type: "module",
@@ -15902,13 +16244,6 @@ init_registry();
 init_board();
 import { join as join20, resolve as resolve12 } from "path";
 
-// src/hub/spec-read.ts
-init_host_executable();
-init_child_process();
-var BODY_LIMIT = 64 * 1024;
-var RESULT_LIMIT = 80 * 1024;
-var STDOUT_LIMIT = 512 * 1024;
-
 // src/models/route/config.ts
 var TYPES = new Set(["stage", "plan_execute", "advisor", "escalation"]);
 
@@ -15926,7 +16261,13 @@ init_workflow();
 init_board();
 init_envelope();
 init_project();
+init_review_brief();
 init_registry();
+
+// src/hub/task-sweep.ts
+var GROOMING_CODES = new Set(["tests", "spec", "roster", "pull-only", "not-attached", "excluded", "owner-admission", "offline", "paused", "failing", "pii", "policy", "cancelled", "unavailable", "runner", "approvals", "quota", "dependency"]);
+
+// src/hub/tasks.ts
 init_sdlc();
 var DEMOTION_HALF_LIFE_MS = 24 * 3600000;
 var CONTRADICTION_WINDOW_MS = 7 * 86400000;
@@ -16041,8 +16382,23 @@ function validateInstances(raw) {
       return fail(`${path}.kind`, "unknown native kind");
     if (!id.startsWith(prefix) || !/^[a-z0-9][a-z0-9-]*$/.test(id.slice(prefix.length)))
       return fail(path, "id must be <kind>-<name>");
-    if (!definition.start.create || !definition.start.forms.includes("headless") || !["env", "acp-session"].includes(definition.identity.mcp))
-      return fail(`${path}.kind`, "unsupported in I2; a headless factory with env or ACP-session identity is required, not channel-only or project-file identity");
+    const channel = definition.identity.mcp === "channel-plugin";
+    if (!channel && (!definition.start.create || !definition.start.forms.includes("headless") || !["env", "acp-session"].includes(definition.identity.mcp)))
+      return fail(`${path}.kind`, "unsupported; a headless factory with env or ACP-session identity, or a channel-plugin kind, is required, not project-file identity");
+    if (channel) {
+      const declared = entry.roles ? roles(entry.roles.value, `${path}.roles`) : [];
+      if (entry.start_mode && definition.reviewerVariant) {
+        if (entry.worktree)
+          return fail(path, "a headless reviewer reads the project checkout: worktree is not supported");
+        if (declared.length !== 1 || declared[0] !== "reviewer")
+          return fail(`${path}.roles`, 'a headless channel-kind instance is a reviewer: roles must be exactly ["reviewer"]');
+      } else {
+        if (entry.start_mode || entry.worktree)
+          return fail(path, `a channel instance starts only from the person's terminal (ahub <kind> --as <id>): start_mode and worktree are not supported; a headless reviewer declares roles ["reviewer"] and start_mode "headless"`);
+        if (!declared.length || declared.some((role) => role !== "reviewer" && role !== "planner"))
+          return fail(`${path}.roles`, "a channel instance must declare its roles: reviewer and/or planner");
+      }
+    }
     const value = { kind };
     if (entry.roles) {
       value.roles = roles(entry.roles.value, `${path}.roles`);