@staix/agent-hub 0.12.35 → 0.12.37

package/src/hub/bus.ts

@@ -40,9 +40,9 @@ export interface BusOptions {
   /**
    * Optional: does a queued envelope still matter to this recipient (issue #106)? Asked per recipient when a delivery is
    * built and again right before it is handed over, after condensation. False drops it unsent: the journal records it
-   * as discarded and taps see a `stale` event.
+   * as discarded and taps see a `stale` event. A string is false with its own reason (#223, a review-only peer).
    */
-  relevant?: (peer: PeerId, env: Envelope) => boolean;
+  relevant?: (peer: PeerId, env: Envelope) => boolean | string;
   /**
    * Optional: why this recipient does not get this envelope (issue #107, a turn-free cohort). Asked per recipient once
    * the audience is final (implicit replies and `digest` resolved), so the other recipients still get it, unchanged;
@@ -1088,7 +1088,13 @@ export class Bus {
   }
 
   private isRelevant(id: PeerId, env: Envelope): boolean {
-    return !this.withdrawn.has(env.id) && (this.opts.relevant?.(id, env) ?? true);
+    return this.irrelevance(id, env) === undefined;
+  }
+
+  /** Why a queued envelope no longer goes to `id`, or undefined when it still does. */
+  private irrelevance(id: PeerId, env: Envelope): string | undefined {
+    const verdict = this.withdrawn.has(env.id) ? false : this.opts.relevant?.(id, env) ?? true;
+    return verdict === true ? undefined : typeof verdict === "string" ? verdict : `stale: task #${env.refs?.task ?? "?"} is no longer open for ${id}`;
   }
 
   /**
@@ -1101,8 +1107,8 @@ export class Bus {
     let dropped = false;
     for (let i = queue.length - 1; i >= 0; i--) {
       const env = queue[i]!;
-      if (this.isRelevant(id, env)) continue;
-      const reason = `stale: task #${env.refs?.task ?? "?"} is no longer open for ${id}`;
+      const reason = this.irrelevance(id, env);
+      if (reason === undefined) continue;
       queue.splice(i, 1);
       dropped = true;
       if (this.journal) this.pendingOutcomes.push({ id: crypto.randomUUID(), peer: id, state: "discarded", createdAt: Date.now(), originals: [env], out: [], reason });

package/src/hub/claude-state.ts

@@ -0,0 +1,37 @@
+// No imports: the statusline tee and the CLI load this without the daemon (#450 I3).
+const PEER = /^[a-z][a-z0-9-]{0,31}$/;
+
+/** The peer a Claude process writes for: its AGENTHUB_PEER_ID when well formed, otherwise the builtin claude peer. */
+export function claudePeer(value: string | undefined): string {
+  return value !== undefined && PEER.test(value) ? value : "claude";
+}
+
+/** Per-peer Claude state file names. The builtin claude peer keeps its original names, so nothing migrates. */
+export function claudeStateFile(base: "claude-launch" | "claude-session" | "claude-context", peer: string): string {
+  // Instance ids are always <kind>-<name>; a builtin id has no hyphen.
+  return peer.includes("-") && PEER.test(peer) ? `${base}.${peer}.json` : `${base}.json`;
+}
+
+/** A Claude peer's own row in terminal-recovery.json for this daemon, never a sibling instance's (row order is arbitrary). */
+export function ownTerminalRow(records: unknown, peer: string, projectRoot: string, instanceId: string): { launchId?: unknown } | undefined {
+  if (!Array.isArray(records)) return undefined;
+  return records.find((row) => row?.peer === peer && row?.projectRoot === projectRoot && row?.instanceId === instanceId);
+}
+
+/**
+ * Whether a Claude session's transcript exists: the path the peer's own status line reported for that session, else
+ * the builtin's default location. An instance may run under its own CLAUDE_CONFIG_DIR, which the hub cannot see:
+ * without its reported path the answer is unknown, and unknown counts as persisted (it never waives session identity).
+ */
+export function transcriptPersisted(reported: { sessionId?: string; transcriptPath?: string }, sessionId: string, instance: boolean, fallbackPath: string, exists: (path: string) => boolean | "unknown"): boolean {
+  // Only a positive "missing" (ENOENT) is not persisted; an unreadable path is unknown and keeps the identity strict.
+  const found = (path: string) => exists(path) !== false;
+  if (reported.sessionId === sessionId && reported.transcriptPath) return found(reported.transcriptPath);
+  return instance || found(fallbackPath);
+}
+
+/** lstat evidence: true when present, false only on ENOENT/ENOTDIR, "unknown" for any other failure (EACCES included). */
+export function pathEvidence(path: string, lstat: (path: string) => unknown): boolean | "unknown" {
+  try { lstat(path); return true; }
+  catch (error) { const code = (error as { code?: string }).code; return code === "ENOENT" || code === "ENOTDIR" ? false : "unknown"; }
+}

package/src/hub/config-apply.ts

@@ -1,6 +1,7 @@
+import { reviewerPoolConfig } from "./reviewer-pool-config.ts";
 import type { HubConfig } from "./daemon.ts";
 import { ALL_MACHINE_LOCAL, configRepositoryPresent, configTracked } from "./config-trust.ts";
-import { ADAPTERS, SUPPORTED_PEERS, PLANNER_PEERS, START_MODE_PEERS } from "../adapters/registry.ts";
+import { ADAPTERS, DEFAULT_REVIEW_POOL, REVIEW_POOL_KINDS, SUPPORTED_PEERS, PLANNER_PEERS, START_MODE_PEERS } from "../adapters/registry.ts";
 import { CLASSES } from "./board.ts";
 import { permissionDefaults } from "./permission-mode.ts";
 import { peerStartConfig, terminalTemplate } from "./start-mode.ts";
@@ -138,7 +139,7 @@ const schema: Record<string, Check> = {
   peers: (v, k) => { map(block({ start_mode: words(["tui", "headless"]) }), START_MODE_PEERS)(v, k); peerStartConfig(v); },
   terminal: (v, k) => { block({ open: strings })(v, k); terminalTemplate(object(v, k).open); },
   limits: block({ sender_per_min: number(0), pair_per_min: number(0), important_per_hour: number(0), repeat_window_s: number(0) }),
-  review: block({ adaptive: bool, min_reviews: number(1, Number.MAX_SAFE_INTEGER, true) }), recovery: block({ auto_resume_after_crash: bool }),
+  review: block({ adaptive: bool, min_reviews: number(1, Number.MAX_SAFE_INTEGER, true), pool: v => { reviewerPoolConfig({ pool: v }, DEFAULT_REVIEW_POOL, REVIEW_POOL_KINDS); }, rerotate: bool }), recovery: block({ auto_resume_after_crash: bool }),
   capabilities: map(strings), coordination: words(["advisory", "turn-free"]), experiments: block({ stale_notices: words(["drop", "deliver"]) }),
 };
 export function validateRawConfig(raw: unknown, declarations?: InstancesConfig): asserts raw is Record<string, unknown> {

package/src/hub/control-client.ts

@@ -8,7 +8,7 @@ export function stateDirFor(cwd: string): string {
 
 /** Control WS wire version. 2 = `deliver` carries `envs` (digests); 3 = `tools` role and task messages; 4 = budget messages and `hub_checkpoint`; 5 = `ask`; 6 = console-only `ui` session bootstrap; 8 = controlled recovery; 9 = Pi bridge metadata; 10 = durable delivery receipts; 11 = queue hold diagnostics; 12 = generation-bound channel settlement and execution budgets; 13 = turn-free facts (`facts` with tool, session and transcript binding, `silenced`) and per-recipient send results (issue #108). 14 = native context-window status and session-bound context checkpoint request ids (issue #185). 15 = conductor tools and permission deadlines/closed events (issues #190, #194). 16 = a Claude session without channel evidence: hello `channel: false` and `inbox` (issue #205). The plugin is installed apart from the daemon, so they can drift. */
 export const PROTOCOL = 16;
-export const DAEMON_FEATURES = ["task_cancel", "recovery_deferred_hub", "peer_instances"] as const;
+export const DAEMON_FEATURES = ["task_cancel", "recovery_deferred_hub", "peer_instances", "release_trains", "reviewer_pool"] as const;
 /** Protocols a current coordinator may authenticate while upgrading a running source. */
 export const RECOVERY_SOURCE_PROTOCOLS = [9, 10, 11, 12, 13, 14, 15, PROTOCOL] as const;
 

package/src/hub/cost-governance.ts

@@ -0,0 +1,76 @@
+/** S10 cost evidence is metadata only. Legacy scope and incomplete readback remain unknown. */
+export interface ReviewScope { scope: "none" | "delta" | "full"; reviewers: number }
+export interface CostPlan { review?: ReviewScope; ci?: "focused" | "full" | "reuse" }
+export interface ReviewCost extends CostPlan { head?: string }
+export interface CostTask { repo: string; pr: number; private?: boolean; history: { event: string; at: number; reviewCost?: ReviewCost }[] }
+export interface CostPr { repo: string; pr: number; state: "OPEN" | "CLOSED" | "MERGED"; mergedAt?: number; complete: boolean; ciRuns?: { id: number; attempt: number }[]; reviews?: number }
+export interface CostRow { repo: string; pr: number; reviewRounds: number; ciRuns: number | null; ciReruns: number | null; fullReReviews: number; deltaReviews: number; reviewMs: number | null; unknownReviewScopes: number; githubReviews: number | null; complete: boolean }
+export interface CostReport { rows: CostRow[]; truncated: boolean }
+export function cleanCostPlan(input: unknown): CostPlan {
+  if (!input || typeof input !== "object" || Array.isArray(input)) throw new Error("invalid cost scope");
+  const value = input as Record<string, unknown>;
+  const result: CostPlan = {};
+  if (value.review !== undefined) {
+    const review = value.review as Record<string, unknown>;
+    if (!review || typeof review !== "object" || Array.isArray(review) || Object.keys(review).some(key => !["scope", "reviewers"].includes(key))
+      || !["none", "delta", "full"].includes(review.scope as string) || !Number.isSafeInteger(review.reviewers)
+      || (review.scope === "none" ? review.reviewers !== 0 : (review.reviewers as number) < 1 || (review.reviewers as number) > 8)) throw new Error("invalid review cost scope");
+    result.review = { scope: review.scope as ReviewScope["scope"], reviewers: review.reviewers as number };
+  }
+  if (value.ci !== undefined) {
+    if (!["focused", "full", "reuse"].includes(value.ci as string)) throw new Error("invalid CI cost scope");
+    result.ci = value.ci as CostPlan["ci"];
+  }
+  return result;
+}
+const validRepo = (repo: string) => /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(repo) && !repo.startsWith("-");
+const key = (repo: string, pr: number) => `${repo.toLowerCase()}#${pr}`;
+/** One round is a board review handoff, not one reviewer in a multi-reviewer round. CI attempts share a run id. */
+export function costMetrics(tasks: CostTask[], prs: CostPr[]): CostReport {
+  const withheld = new Set(tasks.filter(task => task.private).map(task => key(task.repo, task.pr)));
+  const rows: CostRow[] = [];
+  let truncated = tasks.length > 500 || prs.length > 200, historyLeft = 10_000;
+  const seen = new Set<string>();
+  for (const pr of prs.slice(0, 200)) {
+    const identity = key(pr.repo, pr.pr);
+    if (!validRepo(pr.repo) || !Number.isSafeInteger(pr.pr) || pr.pr < 1 || pr.state !== "MERGED" || withheld.has(identity) || seen.has(identity)) continue;
+    if (!tasks.some(task => !task.private && key(task.repo, task.pr) === identity)) continue;
+    seen.add(identity);
+    const rounds: { at: number; scope?: ReviewScope["scope"]; elapsed?: number }[] = [];
+    let complete = pr.complete && Number.isFinite(pr.mergedAt);
+    for (const task of tasks.slice(0, 500).filter(task => key(task.repo, task.pr) === identity)) {
+      const history = task.history.slice(0, Math.max(0, historyLeft)); historyLeft -= history.length;
+      if (history.length < task.history.length) { complete = false; truncated = true; }
+      let pending: typeof rounds[number] | undefined;
+      for (const event of [...history].sort((a, b) => a.at - b.at)) {
+        if (!Number.isFinite(event.at) || event.at < 0 || !Number.isFinite(pr.mergedAt) || event.at > pr.mergedAt!) continue;
+        if (event.event === "done") {
+          pending = { at: event.at, scope: event.reviewCost?.review?.scope }; rounds.push(pending);
+        } else if (pending && ["approved", "changes_requested"].includes(event.event)) { pending.elapsed = event.at - pending.at; pending = undefined; }
+      }
+    }
+    rounds.sort((a, b) => a.at - b.at);
+    const attempts = new Map<number, number>();
+    if (pr.ciRuns) for (const run of pr.ciRuns.slice(0, 100)) {
+      if (!Number.isSafeInteger(run.id) || run.id < 1 || !Number.isSafeInteger(run.attempt) || run.attempt < 1 || run.attempt > 10_000) { complete = false; continue; }
+      attempts.set(run.id, Math.max(attempts.get(run.id) ?? 0, run.attempt));
+    }
+    if (pr.ciRuns && pr.ciRuns.length > 100) { complete = false; truncated = true; }
+    if (!pr.ciRuns || pr.reviews === undefined || rounds.some(round => round.elapsed === undefined || round.scope === undefined)) complete = false;
+    rows.push({ repo: pr.repo.toLowerCase(), pr: pr.pr, reviewRounds: rounds.length,
+      ciRuns: pr.ciRuns ? attempts.size : null, ciReruns: pr.ciRuns ? [...attempts.values()].reduce((sum, n) => sum + n - 1, 0) : null,
+      fullReReviews: rounds.filter((round, index) => index > 0 && round.scope === "full").length,
+      deltaReviews: rounds.filter(round => round.scope === "delta").length,
+      reviewMs: rounds.every(round => round.elapsed !== undefined) ? rounds.reduce((sum, round) => sum + round.elapsed!, 0) : null,
+      unknownReviewScopes: rounds.filter(round => round.scope === undefined).length, githubReviews: pr.reviews ?? null, complete });
+  }
+  return { rows: rows.sort((a, b) => a.repo.localeCompare(b.repo) || a.pr - b.pr), truncated };
+}
+export function costBandProposals(report: CostReport, upper: Partial<Record<"reviewRounds" | "ciRuns" | "ciReruns" | "fullReReviews" | "deltaReviews" | "reviewMs", number>>): { repo: string; pr: number; metric: string; observed: number; upper: number }[] {
+  if (report.truncated) return [];
+  return report.rows.filter(row => row.complete).flatMap(row => Object.entries(upper).flatMap(([metric, limit]) => {
+    if (!["reviewRounds", "ciRuns", "ciReruns", "fullReReviews", "deltaReviews", "reviewMs"].includes(metric) || !Number.isFinite(limit) || limit! < 0) return [];
+    const observed = row[metric as keyof CostRow];
+    return typeof observed === "number" && observed > limit! ? [{ repo: row.repo, pr: row.pr, metric, observed, upper: limit! }] : [];
+  }));
+}