@piagent/platform 1.6.0 → 1.7.1

package/packages/piagent-core/runtime/hooks/tool-result-retrieval.ts

@@ -0,0 +1,42 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+import {
+  RetrievalEvidenceRuntime,
+  type RetrievalEvidenceCheckpoint,
+  type RetrievalEvidenceObservation
+} from "../session/retrieval-evidence-runtime.ts";
+import { appendToolResultText, isPlainRecord } from "./tool-result-value-helpers.ts";
+
+export function observeRetrievalResult(input: {
+  runtime: RetrievalEvidenceRuntime;
+  ctx: ExtensionContext;
+  observation: RetrievalEvidenceObservation;
+  turnId?: string;
+}): RetrievalEvidenceCheckpoint | undefined {
+  return input.runtime.observe(input.ctx, input.observation, input.turnId);
+}
+
+export function attachRetrievalCheckpoint(input: {
+  checkpoint?: RetrievalEvidenceCheckpoint;
+  content: unknown;
+  details: unknown;
+  ctx: ExtensionContext;
+  turnId?: string;
+  telemetry: (ctx: ExtensionContext, payload: Record<string, unknown>) => void;
+}): { content: unknown; details: unknown; changed: boolean } {
+  if (!input.checkpoint) return { content: input.content, details: input.details, changed: false };
+  const details = isPlainRecord(input.details)
+    ? { ...input.details, piagentRetrievalCheckpoint: input.checkpoint }
+    : { ...(input.details === undefined ? {} : { value: input.details }), piagentRetrievalCheckpoint: input.checkpoint };
+  input.telemetry(input.ctx, {
+    event: "retrieval_evidence_checkpoint",
+    turnId: input.turnId,
+    ...input.checkpoint,
+    text: undefined
+  });
+  return {
+    content: appendToolResultText(input.content, input.checkpoint.text),
+    details,
+    changed: true
+  };
+}

package/packages/piagent-core/runtime/hooks/tool-result-value-helpers.ts

@@ -0,0 +1,66 @@
+import { redactSensitiveText } from "../../extensions/redaction-core.js";
+
+export function isPlainRecord(value: unknown): value is Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+
+export function numericExitCode(value: unknown): number | undefined {
+  if (typeof value === "number" && Number.isInteger(value)) return value;
+  if (typeof value === "string" && /^-?\d+$/.test(value.trim())) return Number.parseInt(value, 10);
+  return undefined;
+}
+
+export function successfulToolResult(event: { isError?: boolean; details?: unknown }): boolean {
+  if (event.isError === true) return false;
+  const details = isPlainRecord(event.details) ? event.details : {};
+  const exitCode = numericExitCode(details.exitCode ?? details.status);
+  return exitCode === undefined || exitCode === 0;
+}
+
+export function boundedToolResultText(content: unknown): string {
+  const text = typeof content === "string"
+    ? content
+    : Array.isArray(content)
+      ? content
+          .filter((block) => block && typeof block === "object" && (block as { type?: unknown }).type === "text")
+          .map((block) => String((block as { text?: unknown }).text ?? ""))
+          .join("\n")
+      : "";
+  return text.slice(-20_000);
+}
+
+export function countChangedStringLeaves(before: unknown, after: unknown): number {
+  if (typeof before === "string" && typeof after === "string") return before === after ? 0 : 1;
+  if (Array.isArray(before) && Array.isArray(after)) {
+    return before.reduce((total, item, index) => total + countChangedStringLeaves(item, after[index]), 0);
+  }
+  if (!before || !after || typeof before !== "object" || typeof after !== "object") return 0;
+  return Object.entries(before as Record<string, unknown>).reduce(
+    (total, [key, value]) => total + countChangedStringLeaves(value, (after as Record<string, unknown>)[key]),
+    0
+  );
+}
+
+export function redactToolResultTextContent(content: unknown): { content: unknown; redacted: number } {
+  if (!Array.isArray(content)) return { content, redacted: 0 };
+  let redacted = 0;
+  const safeContent = content.map((block) => {
+    if (!block || typeof block !== "object") return block;
+    const typed = block as { type?: unknown; text?: unknown };
+    if (typed.type !== "text" || typeof typed.text !== "string") return block;
+    const safeText = redactSensitiveText(typed.text);
+    if (!safeText.redacted) return block;
+    redacted += 1;
+    return { ...block, text: safeText.text };
+  });
+  return { content: safeContent, redacted };
+}
+
+export function appendToolResultText(content: unknown, text: string): unknown[] {
+  const block = { type: "text", text };
+  if (Array.isArray(content)) return [...content, block];
+  if (typeof content === "string" && content) return [{ type: "text", text: content }, block];
+  return [block];
+}

package/packages/piagent-core/runtime/input/chat-images.ts

@@ -105,7 +105,7 @@ function normalizeImagePathCandidate(candidate: string, cwd: string, options: {
   return path.isAbsolute(raw) ? raw : path.resolve(cwd, raw);
 }
 
-function extractLocalImagePathCandidates(text: string, cwd: string): string[] {
+export function extractLocalImagePathCandidates(text: string, cwd: string): string[] {
   const candidates = new Set<string>();
   const imageExt = "(?:png|jpe?g|gif|webp|bmp)";
   const wholeTextPath = normalizeImagePathCandidate(text, cwd, { allowBareRelative: false });

package/packages/piagent-core/runtime/inspection/activity-event-adapter.ts

@@ -54,7 +54,7 @@ export function adaptActivityTelemetryEvent(input: ActivityEventAdapterInput): R
   const toolCallRef = hasOperation ? opaque("tool", rawToolCall) : null;
   const activityType = hasOperation ? "tool" : ["bash", "shell", "exec"].includes(toolName) ? "command" : "other";
   const resultFailure = eventName === "tool_result" && (event.isError === true || typeof event.exitCode === "number" && event.exitCode !== 0);
-  const failed = resultFailure && !handledToolFailure(event.reasonCode);
+  const failed = resultFailure && !handledToolFailure(event.reasonCode, toolName);
   const blocked = eventName === "tool_decision";
   // `tool_call` is emitted before policy authorization. Calling it "started"
   // made the Dashboard claim a command was running while it was still waiting

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/same-process-bridge-proof.ts

@@ -1,6 +1,6 @@
 import { createHash } from "node:crypto";
 
-export const PINNED_BRIDGE_HOST_VERSION = "0.84.1" as const;
+export const PINNED_BRIDGE_HOST_VERSION = "0.86.1" as const;
 export const SAME_PROCESS_BRIDGE_PROOF_VERSION = "piagent-webui-same-process-bridge-v1" as const;
 
 const HOST_EVENTS = Object.freeze([

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

@@ -1,7 +1,7 @@
 import { createHash } from "node:crypto";
 
 import { redactSensitiveText } from "../../extensions/redaction-core.js";
-import { readHandoffProjection } from "../recovery/handoff-projection.ts";
+import { handoffIdentityMatchesTask, readHandoffProjection } from "../recovery/handoff-projection.ts";
 import { inspectTaskResumeState } from "../recovery/resume-state.ts";
 import { inspectBoundedContextTelemetry } from "./context-telemetry-inspection.ts";
 import { taskRunOpaqueRef } from "./task-run-index.ts";
@@ -34,7 +34,7 @@ function nextAction(cwd: string, task: Task) {
 
 function currentHandoff(cwd: string, task: Task) {
   const handoff = readHandoffProjection(cwd, task.taskRunId); if (!handoff) return null;
-  if (handoff.identity.taskId !== task.taskId || handoff.identity.taskRunId !== task.taskRunId) throw new Error("handoff-identity-conflict");
+  if (!handoffIdentityMatchesTask(handoff.identity, task as any)) throw new Error("handoff-identity-conflict");
   return { handoffRef: opaque("handoff", `${task.taskRunId}\0${handoff.generatedAt}\0${handoff.tree.currentDigest ?? "none"}`),
     generatedAt: handoff.generatedAt, phase: display(handoff.state.phase, 64) || null, taskOutcome: handoff.state.taskOutcome,
     gateDecision: handoff.state.gateDecision, completionApproved: handoff.state.completionApproved,

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." }