@staix/agent-hub 0.16.0 → 0.17.0

package/src/adapters/reviewer-mcp.ts

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

package/src/adapters/reviewer-print.ts

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

package/src/cli/upgrade.ts

@@ -143,8 +143,8 @@ export interface RecoveryOperation {
   /** Positive typed store observation; disposal rechecks it before accepting a repaired-session loss. */
   missingRecordedSession?: { projectId: string; peer: RecoveryNativePeer; sessionId: string; kind: "rollout" | "transcript"; checkedPath?: string };
   freshOverride?: { peer: RecoveryNativePeer; evidence: NonNullable<RecoveryOperation["missingRecordedSession"]>; checked: "missing"; at: number };
-  /** #215: every human disposition, in order. Operator reasons only; never task or message text. */
-  audit?: { at: number; action: "fresh-session" | "stop-and-archive"; reason: string; peer?: string; projects: string[] }[];
+  /** #215: every human disposition, in order. Operator reasons only; never task or message text. #776: `cause` is the operation's own `error` at that moment, the text the receipt already held. */
+  audit?: { at: number; action: "fresh-session" | "stop-and-archive"; reason: string; peer?: string; cause?: string; projects: string[] }[];
   disposition?: { choice: "stop-and-archive"; at: number; projects: Record<string, string>; continuity?: Record<string, "not-archived" | "unavailable"> };
   /** #215: a refusal no resume can get past was recorded (FinalRefusal); `next` no longer offers resume. */
   final?: boolean;
@@ -1070,7 +1070,8 @@ export async function disposeRecovery(id: string, choice: { fresh: string } | {
     delete op.blockedReattachment;
     delete op.presentationCause;
     abandoned(op); // #227: in the same write as the disposition
-    (op.audit ??= []).push({ at, action: "stop-and-archive", reason, projects: acts.map((a) => a.planned.project.id) });
+    // #776: the error that blocked the operation is cleared on disposal, so the audit keeps it.
+    (op.audit ??= []).push({ at, action: "stop-and-archive", reason, ...(op.error ? { cause: op.error } : {}), projects: acts.map((a) => a.planned.project.id) });
     // Recorded before the first act: a crash inside a stop leaves a disposition that resume refuses to override.
     delete op.failure;
     op.updatedAt = driver.now(); writeOperation(id, op, home);