@piagent/platform 1.5.5 → 1.6.1

package/packages/piagent-core/runtime/inspection/bounded-emission-guard.ts

@@ -0,0 +1,286 @@
+import { createHash } from "node:crypto";
+
+export type EmissionSuppressionReason =
+  | "empty"
+  | "filler"
+  | "duplicate-exact"
+  | "duplicate-normalized"
+  | "update-budget";
+
+export type BoundedEmissionCandidate = {
+  channel: string;
+  identityKey: string;
+  updateKey: string;
+  text: string;
+  actionable: boolean;
+  reference: string;
+};
+
+export type EmissionDecision = {
+  accepted: boolean;
+  reason: EmissionSuppressionReason | null;
+  priorReference: string | null;
+};
+
+export type BoundedEmissionTelemetry = {
+  schemaVersion: 1;
+  capacity: number;
+  retained: number;
+  primed: number;
+  accepted: number;
+  suppressed: number;
+  suppressedByReason: Record<EmissionSuppressionReason, number>;
+};
+
+type RetainedEmission = {
+  exactKey: string;
+  normalizedKey: string;
+  updateKey: string | null;
+  reference: string;
+};
+
+const ANSI = /\u001b(?:\[[0-?]*[ -/]*[@-~]|[@-_])/g;
+const DEFAULT_CAPACITY = 512;
+const MIN_CAPACITY = 1;
+const MAX_CAPACITY = 16_384;
+
+const FILLER = new Set([
+  "abort", "all good", "carry on", "complete", "continue", "done", "finished", "halt", "lgtm",
+  "looks good", "no action", "no action needed", "no concern", "no concerns", "no further advice",
+  "no further advice needed", "no further input", "no further input needed", "no issue", "no issues",
+  "no issue continue", "no notes", "nothing to add", "nothing to flag", "nothing to report", "ok", "okay",
+  "stop", "stop here", "stop now", "task complete", "task done",
+  "da xong", "đã xong", "khong can lam gi", "không cần làm gì", "khong co gi de bao cao", "không có gì để báo cáo",
+  "khong co loi", "không có lỗi", "khong co van de", "không có vấn đề", "on", "ổn", "tiep tuc", "tiếp tục", "xong"
+]);
+
+function digest(value: string): string {
+  return createHash("sha256").update(value).digest("hex");
+}
+
+function exactEmissionText(value: string): string {
+  return String(value ?? "")
+    .replace(ANSI, "")
+    .normalize("NFKC")
+    .replace(/[\u0000-\u001f\u007f-\u009f]+/g, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+/** Stable comparison form for reviewer notes and compact runtime event summaries. */
+export function normalizeEmissionText(value: string): string {
+  return exactEmissionText(value)
+    .toLowerCase()
+    .replace(/[^\p{L}\p{N}]+/gu, " ")
+    .trim();
+}
+
+function canonical(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(canonical);
+  if (!value || typeof value !== "object") return value;
+  const prototype = Object.getPrototypeOf(value);
+  if (prototype !== Object.prototype && prototype !== null) return String(value);
+  const record = value as Record<string, unknown>;
+  return Object.fromEntries(Object.keys(record).sort().map((key) => [key, canonical(record[key])]));
+}
+
+function canonicalText(value: unknown): string {
+  return JSON.stringify(canonical(value));
+}
+
+function textField(payload: Record<string, unknown>): string | null {
+  for (const field of ["note", "advice", "finding", "message", "summary"]) {
+    if (typeof payload[field] === "string" && payload[field].trim()) return payload[field];
+  }
+  return null;
+}
+
+function reviewerRole(payload: Record<string, unknown>): string | null {
+  for (const field of ["role", "agentRole", "actorRole", "sourceRole"]) {
+    const value = String(payload[field] ?? "").toLowerCase();
+    if (value === "reviewer" || value === "piagent-reviewer") return value;
+  }
+  const emissionType = String(payload.emissionType ?? "").toLowerCase();
+  return emissionType === "reviewer-note" || emissionType === "review-note" ? "reviewer" : null;
+}
+
+type RuntimeEmissionLike = {
+  kind: string;
+  sessionRef: string;
+  taskRunId: string | null;
+  agentOperationId: string | null;
+  turnIndex: number | null;
+  toolCallId: string | null;
+  revision: object;
+  payload: Record<string, unknown>;
+};
+
+/**
+ * Select only bounded activity, reviewer-note and operation emissions. Message
+ * deltas/completions are deliberately outside this boundary, so a final user-
+ * visible response can never be suppressed by this guard.
+ */
+export function runtimeEventEmissionCandidate(event: RuntimeEmissionLike, reference: string): BoundedEmissionCandidate | null {
+  const payload = event.payload ?? {};
+  const revision = canonicalText(event.revision);
+  // Lifecycle state is authoritative. Classify it before reviewer metadata so
+  // a note attached to a started/finished event can never hide that state.
+  if (event.kind.startsWith("activity.")) {
+    const state = payload.state ?? event.kind.slice("activity.".length);
+    return {
+      channel: "activity",
+      identityKey: canonicalText([event.agentOperationId, event.toolCallId, payload.activityRef, event.kind, state]),
+      updateKey: canonicalText([revision, event.agentOperationId, event.toolCallId, event.kind, state]),
+      text: canonicalText(payload),
+      actionable: false,
+      reference
+    };
+  }
+  if (event.kind.startsWith("agent-operation.")) {
+    const state = payload.state ?? payload.settlement ?? payload.status ?? event.kind.slice("agent-operation.".length);
+    return {
+      channel: "operation",
+      identityKey: canonicalText([event.agentOperationId, event.kind, state]),
+      updateKey: canonicalText([revision, event.agentOperationId, event.kind, state]),
+      text: canonicalText(payload),
+      actionable: false,
+      reference
+    };
+  }
+  const role = reviewerRole(payload), note = role ? textField(payload) : null;
+  if (role && note) {
+    const explicitUpdate = payload.updateRef ?? payload.reviewerRevision ?? payload.revision;
+    return {
+      channel: "reviewer",
+      // A session may host many unrelated tasks. Dedupe reviewer prose across
+      // retries/operations of one durable task, but never across task runs.
+      identityKey: canonicalText([event.sessionRef, event.taskRunId, role]),
+      updateKey: canonicalText([event.sessionRef, event.agentOperationId, event.turnIndex, explicitUpdate ?? revision]),
+      text: note,
+      actionable: true,
+      reference
+    };
+  }
+  return null;
+}
+
+/** A small in-memory policy gate. It stores only hashes, never emitted prose. */
+export class BoundedEmissionGuard {
+  readonly capacity: number;
+  readonly #retained: RetainedEmission[] = [];
+  readonly #exact = new Map<string, string>();
+  readonly #normalized = new Map<string, string>();
+  readonly #updates = new Map<string, string>();
+  #primed = 0;
+  #accepted = 0;
+  readonly #suppressed: Record<EmissionSuppressionReason, number> = {
+    empty: 0,
+    filler: 0,
+    "duplicate-exact": 0,
+    "duplicate-normalized": 0,
+    "update-budget": 0
+  };
+
+  constructor(options: { capacity?: number } = {}) {
+    const candidate = Number.isFinite(options.capacity) ? Math.floor(Number(options.capacity)) : DEFAULT_CAPACITY;
+    this.capacity = Math.max(MIN_CAPACITY, Math.min(MAX_CAPACITY, candidate));
+  }
+
+  #keys(candidate: BoundedEmissionCandidate): { exactKey: string; normalizedKey: string; updateKey: string | null; exact: string; normalized: string } {
+    const exact = exactEmissionText(candidate.text), normalized = normalizeEmissionText(exact);
+    const scope = `${candidate.channel}\0${candidate.identityKey}`;
+    return {
+      exact,
+      normalized,
+      exactKey: digest(`${scope}\0exact\0${exact}`),
+      normalizedKey: digest(`${scope}\0normalized\0${normalized}`),
+      updateKey: candidate.actionable ? digest(`${candidate.channel}\0update\0${candidate.updateKey}`) : null
+    };
+  }
+
+  #reject(reason: EmissionSuppressionReason, priorReference: string | null = null, count = true): EmissionDecision {
+    if (count) this.#suppressed[reason] += 1;
+    return { accepted: false, reason, priorReference };
+  }
+
+  #inspect(candidate: BoundedEmissionCandidate, countSuppression: boolean): EmissionDecision {
+    const keys = this.#keys(candidate);
+    if (candidate.actionable && !keys.exact) return this.#reject("empty", null, countSuppression);
+    if (candidate.actionable && FILLER.has(keys.normalized)) return this.#reject("filler", null, countSuppression);
+    const exact = this.#exact.get(keys.exactKey);
+    if (exact) return this.#reject("duplicate-exact", exact, countSuppression);
+    const normalized = this.#normalized.get(keys.normalizedKey);
+    if (normalized) return this.#reject("duplicate-normalized", normalized, countSuppression);
+    const update = keys.updateKey ? this.#updates.get(keys.updateKey) : undefined;
+    if (update) return this.#reject("update-budget", update, countSuppression);
+    return { accepted: true, reason: null, priorReference: null };
+  }
+
+  inspect(candidate: BoundedEmissionCandidate): EmissionDecision {
+    return this.#inspect(candidate, true);
+  }
+
+  /** Seed retained history without counting old suppression as live telemetry. */
+  prime(candidate: BoundedEmissionCandidate): boolean {
+    if (!this.#inspect(candidate, false).accepted) return false;
+    this.recordAccepted(candidate, { primed: true });
+    return true;
+  }
+
+  recordAccepted(candidate: BoundedEmissionCandidate, options: { primed?: boolean } = {}): void {
+    const keys = this.#keys(candidate);
+    const record = { exactKey: keys.exactKey, normalizedKey: keys.normalizedKey, updateKey: keys.updateKey, reference: candidate.reference };
+    this.#retained.push(record);
+    this.#exact.set(record.exactKey, record.reference);
+    this.#normalized.set(record.normalizedKey, record.reference);
+    if (record.updateKey) this.#updates.set(record.updateKey, record.reference);
+    if (options.primed) this.#primed += 1;
+    else this.#accepted += 1;
+    while (this.#retained.length > this.capacity) {
+      const stale = this.#retained.shift() as RetainedEmission;
+      if (this.#exact.get(stale.exactKey) === stale.reference) this.#exact.delete(stale.exactKey);
+      if (this.#normalized.get(stale.normalizedKey) === stale.reference) this.#normalized.delete(stale.normalizedKey);
+      if (stale.updateKey && this.#updates.get(stale.updateKey) === stale.reference) this.#updates.delete(stale.updateKey);
+    }
+  }
+
+  /** Remove fingerprints when their durable event leaves the retention window. */
+  forget(reference: string): boolean {
+    const kept = this.#retained.filter((record) => record.reference !== reference);
+    if (kept.length === this.#retained.length) return false;
+    this.#retained.length = 0;
+    this.#retained.push(...kept);
+    this.#exact.clear();
+    this.#normalized.clear();
+    this.#updates.clear();
+    for (const record of this.#retained) {
+      this.#exact.set(record.exactKey, record.reference);
+      this.#normalized.set(record.normalizedKey, record.reference);
+      if (record.updateKey) this.#updates.set(record.updateKey, record.reference);
+    }
+    return true;
+  }
+
+  reset(): void {
+    this.#retained.length = 0;
+    this.#exact.clear();
+    this.#normalized.clear();
+    this.#updates.clear();
+    this.#primed = 0;
+    this.#accepted = 0;
+    for (const reason of Object.keys(this.#suppressed) as EmissionSuppressionReason[]) this.#suppressed[reason] = 0;
+  }
+
+  telemetry(): BoundedEmissionTelemetry {
+    const suppressedByReason = { ...this.#suppressed };
+    return {
+      schemaVersion: 1,
+      capacity: this.capacity,
+      retained: this.#retained.length,
+      primed: this.#primed,
+      accepted: this.#accepted,
+      suppressed: Object.values(suppressedByReason).reduce((sum, value) => sum + value, 0),
+      suppressedByReason
+    };
+  }
+}

package/packages/piagent-core/runtime/inspection/runtime-event-store.ts

@@ -3,6 +3,12 @@ import fs from "node:fs";
 import path from "node:path";
 
 import { ensurePrivateStateDirectory, resolveLocalStatePath } from "../../extensions/local-state-path.js";
+import {
+  BoundedEmissionGuard,
+  type BoundedEmissionTelemetry,
+  type EmissionSuppressionReason,
+  runtimeEventEmissionCandidate
+} from "./bounded-emission-guard.ts";
 
 export const RUNTIME_EVENT_SCHEMA_VERSION = 2 as const;
 export type RuntimeEventRevision = {
@@ -57,6 +63,9 @@ export type RuntimeEventReplay = {
   lastAvailableSequence: number | null;
   reasonCode: string | null;
 };
+export type RuntimeEventAppendResult =
+  | { event: RuntimeEventV2; appended: true; suppressionReason: null }
+  | { event: RuntimeEventV2 | null; appended: false; suppressionReason: EmissionSuppressionReason | "event-id-duplicate" };
 
 const EVENT_KINDS = new Set([
   "runtime.started", "runtime.health-changed", "runtime.disconnected", "runtime.resync-required", "runtime.resynced", "runtime.phase-changed",
@@ -158,15 +167,17 @@ function readSegment(root: string, file: string): RuntimeEventV2[] {
 export class RuntimeEventStore {
   readonly directory: string;
   readonly corruptions: string[] = [];
-  readonly options: { projectRoot: string; projectRef: string; runtimeInstanceId: string; sessionRef: string; maxEventsPerSegment?: number; maxSegments?: number };
+  readonly options: { projectRoot: string; projectRef: string; runtimeInstanceId: string; sessionRef: string; maxEventsPerSegment?: number; maxSegments?: number; emissionGuardCapacity?: number };
   private events: RuntimeEventV2[] = [];
   private segments: Array<{ file: string; start: number; count: number }> = [];
   private eventById = new Map<string, RuntimeEventV2>();
+  private readonly emissionGuard: BoundedEmissionGuard;
   private readonly maxEventsPerSegment: number;
   private readonly maxSegments: number;
 
-  constructor(options: { projectRoot: string; projectRef: string; runtimeInstanceId: string; sessionRef: string; maxEventsPerSegment?: number; maxSegments?: number }) {
+  constructor(options: { projectRoot: string; projectRef: string; runtimeInstanceId: string; sessionRef: string; maxEventsPerSegment?: number; maxSegments?: number; emissionGuardCapacity?: number }) {
     this.options = options;
+    this.emissionGuard = new BoundedEmissionGuard({ capacity: options.emissionGuardCapacity });
     this.maxEventsPerSegment = Math.max(2, Math.min(1_000, options.maxEventsPerSegment ?? 500));
     this.maxSegments = Math.max(2, Math.min(20, options.maxSegments ?? 10));
     this.directory = storeDirectory(options.projectRoot, options.runtimeInstanceId, options.sessionRef);
@@ -195,11 +206,13 @@ export class RuntimeEventStore {
           if (previous && record.writerSequence !== previous + 1) throw new Error("event sequence gap");
           if (this.eventById.has(record.eventId)) throw new Error("duplicate event identity");
           previous = record.writerSequence; this.events.push(record); this.eventById.set(record.eventId, record);
+          const candidate = runtimeEventEmissionCandidate(record, record.eventId);
+          if (candidate) this.emissionGuard.prime(candidate);
         }
         this.segments.push({ file: name, start, count: records.length });
       }
     } catch {
-      this.events = []; this.segments = []; this.eventById.clear(); this.corruptions.push("event-store-corrupt");
+      this.events = []; this.segments = []; this.eventById.clear(); this.emissionGuard.reset(); this.corruptions.push("event-store-corrupt");
     }
   }
 
@@ -208,14 +221,27 @@ export class RuntimeEventStore {
   retention(): { eventRetentionCount: number; eventRetentionSeconds: number } {
     return { eventRetentionCount: this.maxEventsPerSegment * this.maxSegments, eventRetentionSeconds: 0 };
   }
+  emissionTelemetry(): BoundedEmissionTelemetry { return this.emissionGuard.telemetry(); }
 
-  append(draft: RuntimeEventDraft, recordedAt = new Date().toISOString()): { event: RuntimeEventV2; appended: boolean } {
+  append(draft: RuntimeEventDraft, recordedAt = new Date().toISOString()): RuntimeEventAppendResult {
     if (this.resyncRequired()) throw new Error("WebUI event store requires resync");
     if (draft.projectRef !== this.options.projectRef || draft.runtimeInstanceId !== this.options.runtimeInstanceId || draft.sessionRef !== this.options.sessionRef) throw new Error("Runtime event identity does not match its store");
     const id = eventId(draft), duplicate = this.eventById.get(id);
-    if (duplicate) return { event: structuredClone(duplicate), appended: false };
+    const candidate = runtimeEventEmissionCandidate(draft, id);
+    if (duplicate) {
+      const decision = candidate ? this.emissionGuard.inspect(candidate) : null;
+      return { event: structuredClone(duplicate), appended: false,
+        suppressionReason: decision?.reason ?? "event-id-duplicate" };
+    }
     const sequence = (this.events.at(-1)?.writerSequence ?? 0) + 1;
     const event = validateRuntimeEventEnvelope({ schemaVersion: 2, eventId: id, eventCursor: eventCursor(sequence, id), writerSequence: sequence, recordedAt, ...structuredClone(draft) });
+    if (candidate) {
+      const decision = this.emissionGuard.inspect(candidate);
+      if (!decision.accepted) {
+        const prior = decision.priorReference ? this.eventById.get(decision.priorReference) ?? null : null;
+        return { event: prior ? structuredClone(prior) : null, appended: false, suppressionReason: decision.reason as EmissionSuppressionReason };
+      }
+    }
     let segment = this.segments.at(-1);
     if (!segment || segment.count >= this.maxEventsPerSegment) {
       segment = { file: segmentName(sequence), start: sequence, count: 0 }; this.segments.push(segment);
@@ -228,8 +254,9 @@ export class RuntimeEventStore {
     const descriptor = fs.openSync(target, flags, 0o600);
     try { fs.writeFileSync(descriptor, `${JSON.stringify(event)}\n`); fs.fsyncSync(descriptor); fs.fchmodSync(descriptor, 0o600); } finally { fs.closeSync(descriptor); }
     segment.count += 1; this.events.push(event); this.eventById.set(event.eventId, event);
+    if (candidate) this.emissionGuard.recordAccepted(candidate);
     try { this.enforceRetention(); } catch { this.corruptions.push("event-retention-failed"); }
-    return { event: structuredClone(event), appended: true };
+    return { event: structuredClone(event), appended: true, suppressionReason: null };
   }
 
   private enforceRetention(): void {
@@ -240,7 +267,10 @@ export class RuntimeEventStore {
       if (!stat.isFile() || stat.isSymbolicLink()) throw new Error("event retention target is unsafe");
       fs.unlinkSync(target);
       const discarded = this.events.splice(0, removed.count);
-      for (const event of discarded) this.eventById.delete(event.eventId);
+      for (const event of discarded) {
+        this.eventById.delete(event.eventId);
+        this.emissionGuard.forget(event.eventId);
+      }
     }
   }
 

package/packages/piagent-core/runtime/inspection/task-compaction-history.ts

@@ -96,7 +96,7 @@ export function projectTaskCompactionHistory(input: {
     let malformed = inspected.corruptions;
     const matching = inspected.records.flatMap((record: any, ordinal: number) => {
       if (record?.taskId !== input.task.taskId || record?.taskRunId !== input.task.taskRunId || record?.sessionId !== input.task.sessionId) return [];
-      if (record.schemaVersion !== 1 || !timestamp(record.recordedAt)) { malformed += 1; return []; }
+      if (![1, 2].includes(record.schemaVersion) || !timestamp(record.recordedAt)) { malformed += 1; return []; }
       if (record.event === "session_compact") {
         if (typeof record.willRetry !== "boolean" || typeof record.fromExtension !== "boolean") { malformed += 1; return []; }
         return [{ ordinal, recordedAt: record.recordedAt, kind: "context-compaction", title: "Context đã được compact",

package/packages/piagent-core/runtime/inspection/task-handoff-history.ts

@@ -60,7 +60,7 @@ export function projectTaskHandoffHistory(input: { cwd: string; task: Task; iden
     const matching = inspected.records.flatMap((record: any, ordinal: number) => {
       if (record?.event !== "handoff_projection_written" || record.taskId !== input.task.taskId
         || record.taskRunId !== input.task.taskRunId || record.sessionId !== input.task.sessionId) return [];
-      if (record.schemaVersion !== 1 || !timestamp(record.recordedAt) || typeof record.completionApproved !== "boolean") { malformed += 1; return []; }
+      if (![1, 2].includes(record.schemaVersion) || !timestamp(record.recordedAt) || typeof record.completionApproved !== "boolean") { malformed += 1; return []; }
       const action = display(record.recoveryAction, 80) || "unknown", phase = display(record.phase, 64) || null;
       return [{ ordinal, recordedAt: record.recordedAt, phase, completionApproved: record.completionApproved, projectedAction: action }];
     });

package/packages/piagent-core/runtime/inspection/task-subagent-tree.ts

@@ -5,7 +5,7 @@ import { inspectOwnedWorkBudget, type OwnedWorkReservation } from "../orchestrat
 import { taskRunOpaqueRef } from "./task-run-index.ts";
 
 type Task = { taskId: string; taskRunId: string; trace?: { outcome?: unknown }; orchestration?: Record<string, unknown>;
-  acceptanceReceipt?: { helperUsage?: { used?: unknown; helpers?: unknown[] } }; [key: string]: any };
+  acceptanceReceipt?: { helperUsage?: { used?: unknown; decision?: unknown; projectedSavingsRatio?: unknown; reasonCodes?: unknown; helpers?: unknown[] } }; [key: string]: any };
 type Identity = { projectRef: string; runtimeInstanceId: string; sessionRef: string; taskId: string; taskRunId: string;
   agentOperationId: null; toolCallId: null };
 
@@ -53,9 +53,32 @@ function orchestration(task: Task) {
   };
 }
 
+function delegation(task: Task) {
+  const usage = task.acceptanceReceipt?.helperUsage;
+  const explicitDecision = usage?.decision;
+  const action = explicitDecision === "dispatch" || explicitDecision === "skip"
+    ? explicitDecision
+    : usage?.used === true ? "dispatch" : "skip";
+  const reasonCodes = Array.isArray(usage?.reasonCodes)
+    ? [...new Set(usage.reasonCodes.map((item) => String(item ?? "").trim()).filter((item) => /^[a-z0-9_.:-]+$/.test(item)).slice(0, 16))]
+    : action === "dispatch" ? ["helper-dispatched"] : ["parent-direct-default", "delegation-evidence-missing"];
+  const projected = usage?.projectedSavingsRatio;
+  return {
+    action,
+    reasonCodes,
+    projectedNetSavingsRatio: typeof projected === "number" && Number.isFinite(projected)
+      ? Math.max(-10, Math.min(1, projected))
+      : null,
+    minimumRequiredNetSavingsRatio: 0.3,
+    budget: { maxConcurrent: 1, maxTotal: 1, maxRetries: 0, maxWriters: 0 }
+  };
+}
+
 function unavailable(identity: Identity, runRef: string, generatedAt: string, reasonCode: string) {
   return { schemaVersion: 1, version: "piagent-webui-subagent-tree-v1", generatedAt, identity: structuredClone(identity), runRef,
     state: "unavailable", treeRevision: null, evidenceState: "unknown", orchestration: { mode: "unknown", subagents: "unknown" },
+    delegation: { action: "unknown", reasonCodes: [reasonCode], projectedNetSavingsRatio: null,
+      minimumRequiredNetSavingsRatio: 0.3, budget: { maxConcurrent: 1, maxTotal: 1, maxRetries: 0, maxWriters: 0 } },
     parent: null, children: [], writer: { state: "unknown", ownerNodeRef: null },
     nestedLineage: { state: "unavailable", reasonCode: "no-durable-nested-lineage" },
     summary: { total: 0, active: 0, completed: 0, staleResults: 0, readOnly: 0, singleWriter: 0 }, warnings: [],
@@ -66,7 +89,7 @@ export function projectTaskSubagentTree(input: { cwd: string; task: Task; identi
   const generatedAt = input.generatedAt ?? new Date().toISOString(), runRef = taskRunOpaqueRef(input.task.taskRunId);
   const inspected = inspectOwnedWorkBudget(input.cwd, input.task.taskId, input.task.taskRunId, generatedAt);
   if (inspected.state === "corrupt") return unavailable(input.identity, runRef, generatedAt, inspected.reasonCode ?? "helper-budget-corrupt");
-  const policy = orchestration(input.task), parentRef = opaque("parent", input.task.taskRunId), receipts = helperReceipts(input.task);
+  const policy = orchestration(input.task), delegationDecision = delegation(input.task), parentRef = opaque("parent", input.task.taskRunId), receipts = helperReceipts(input.task);
   const children = inspected.reservations.map((item) => child(input.task.taskRunId, parentRef, item, receipts.get(item.deduplicationKey)));
   const matchedReceipts = new Set(inspected.reservations.map((item) => item.deduplicationKey).filter((key) => receipts.has(key)));
   const unmatchedReceipts = Math.max(0, receipts.size - matchedReceipts.size);
@@ -90,10 +113,10 @@ export function projectTaskSubagentTree(input: { cwd: string; task: Task; identi
     staleResults: children.filter((item) => item.result.state === "stale-result").length,
     readOnly: children.filter((item) => item.authority === "read-only").length,
     singleWriter: children.filter((item) => item.authority === "single-writer").length };
-  const treeRevision = `subagent-tree.${createHash("sha256").update(JSON.stringify({ policy, parentState, terminal: inspected.terminal,
+  const treeRevision = `subagent-tree.${createHash("sha256").update(JSON.stringify({ policy, delegationDecision, parentState, terminal: inspected.terminal,
     children, writer, evidenceState })).digest("hex")}`;
   return { schemaVersion: 1, version: "piagent-webui-subagent-tree-v1", generatedAt, identity: structuredClone(input.identity), runRef,
-    state: "ready", treeRevision, evidenceState, orchestration: policy,
+    state: "ready", treeRevision, evidenceState, orchestration: policy, delegation: delegationDecision,
     parent: { nodeRef: parentRef, lifecycleState: parentState, budgetTerminal: inspected.terminal, mergeOwner: "parent" }, children, writer,
     nestedLineage: { state: "unavailable", reasonCode: "no-durable-nested-lineage" }, summary, warnings,
     health: warnings.length ? { state: "degraded", reasonCode: "subagent-tree-incomplete", message: "Some helper/subagent evidence is incomplete." }

package/packages/piagent-core/runtime/inspection/tool-failure-classification.ts

@@ -0,0 +1,70 @@
+export type ToolFailureReasonCode =
+  | "target-not-found"
+  | "search-target-missing"
+  | "edit-anchor-not-unique"
+  | "edit-anchor-stale"
+  | "helper-dispatch-rejected"
+  | "helper-insufficient-evidence"
+  | "tool-result-failed";
+
+function boundedText(content: unknown, depth = 0): string {
+  if (depth > 2) return "";
+  const nested = content && typeof content === "object" && !Array.isArray(content)
+    ? (content as { content?: unknown }).content
+    : undefined;
+  const text = typeof content === "string" ? content : Array.isArray(content)
+    ? content.filter((item) => item && typeof item === "object" && (item as { type?: unknown }).type === "text")
+      .map((item) => String((item as { text?: unknown }).text ?? "")).join("\n")
+    : nested !== undefined ? boundedText(nested, depth + 1) : "";
+  return text.slice(0, 8_192);
+}
+
+function commandFromInput(input: unknown): string {
+  if (!input || typeof input !== "object") return "";
+  const direct = (input as { command?: unknown }).command;
+  if (typeof direct === "string") return direct;
+  const args = (input as { args?: unknown }).args;
+  return args && typeof args === "object" && typeof (args as { command?: unknown }).command === "string"
+    ? (args as { command: string }).command : "";
+}
+
+export function classifyToolFailure(toolName: string, isError: boolean, content: unknown, input?: unknown): ToolFailureReasonCode | null {
+  const text = boundedText(content);
+  const subagent = /(?:^|[._-])subagents?(?:$|[._-])/i.test(toolName);
+  // Some subagent providers return a successful tool envelope even though no
+  // child was launched, or a zero-exit child explicitly reports that it could
+  // inspect no evidence. Canonical replay must not turn either outcome into a
+  // green "passed" Activity row merely because `isError` is false.
+  if (subagent && /spawn limit reached|no children were started|declared run cannot fit/i.test(text)) {
+    return "helper-dispatch-rejected";
+  }
+  if (subagent && /scope inspected:[^\n]{0,16}\bnone\b|insufficient-evidence rule|no source (?:content|evidence)[^\n]{0,80}(?:accessible|collected)/i.test(text)) {
+    return "helper-insufficient-evidence";
+  }
+  if (!isError) return null;
+  // Only the registered, policy-governed `edit` tool may receive an automatic
+  // current-file recovery snapshot. A similarly named third-party `replace`
+  // tool is not necessarily covered by Piagent's mutation guard.
+  if (/^edit$/i.test(toolName)) {
+    if (/\b(?:oldtext|old text)\b[^\n]{0,240}\b(?:unique|occurrences?)\b|\bfound\s+\d+\s+occurrences?\b/i.test(text)) {
+      return "edit-anchor-not-unique";
+    }
+    if (/could not find (?:the )?exact text|\b(?:oldtext|old text)\b[^\n]{0,240}\b(?:match|mismatch|stale|changed|find)\b|\b(?:generation|content) drift\b/i.test(text)) {
+      return "edit-anchor-stale";
+    }
+  }
+  const readLike = /(?:^|[._-])(?:read|document[_-]?read)(?:$|[._-])/i.test(toolName);
+  if (readLike && /\bENOENT\b|no such file or directory|file (?:does not exist|not found)|cannot find the (?:file|path)/i.test(text)) {
+    return "target-not-found";
+  }
+  const shellLike = /^(?:bash|shell|exec|command)$/i.test(toolName);
+  const searchCommand = /^\s*(?:rg|grep|git\s+grep)\b/.test(commandFromInput(input));
+  const missingTarget = /no such file or directory|cannot find the (?:file|path)|\bos error 2\b/i.test(text);
+  const usefulMatches = text.split(/\r?\n/).some((line) => !/^\s*(?:rg|grep):/i.test(line) && /^.+?:\d+:/.test(line));
+  if (shellLike && searchCommand && missingTarget && usefulMatches) return "search-target-missing";
+  return "tool-result-failed";
+}
+
+export function handledToolFailure(reasonCode: unknown): boolean {
+  return reasonCode === "search-target-missing";
+}