pi-better-subagents 0.16.0 → 0.17.0

package/failures.ts

@@ -4,6 +4,17 @@ import { logPathFor, runDir, taskRuntimeTrust } from "./registry.ts";
 import { activeFailures, actionableFailures, disposeIncidents, failureIdentity, findIncident, formatFailureSummary, formatTerminalFailureFacts, markFailureAttentionDelivered,
     observeFailures, pendingFailureAttention, readFailureState, type FailureState } from "./shared-failure-observations.ts";
 import { evidenceText, foldToolEnd, foldToolStart, newIncidentModel, toolOperation, type IncidentModel, type IncidentSink } from "./incident-model.ts";
+import { SandboxDiagnostics, isDiagnosticReport } from "./shared-sandbox-diagnostics.ts";
+
+
+let diagnosticsWarned = false;
+const workerDiagnostics = new SandboxDiagnostics({ context: "worker",
+    version: "unknown", policy: () => undefined, backend: () => undefined,
+    onError: () => {
+        if (!diagnosticsWarned) process.stderr.write("Sandbox diagnostics collection gap; enforcement unchanged.\n");
+        diagnosticsWarned = true;
+    },
+});
 
 export { formatFailureSummary, pendingFailureAttention, markFailureAttentionDelivered, toolOperation };
 export const failurePath = (id: string) => join(runDir(id), "failures.jsonl");
@@ -230,7 +241,11 @@ export function collectRunFailures(id: string, cwd: string, terminal = false): F
                     if (line.startsWith("{")) {
                         try {
                             const row = JSON.parse(line);
-                            if (["tool_execution_start", "tool_execution_end", "message_end", "auto_retry_start", "auto_retry_end"].includes(row?.type)) {
+                            // Separate sampling from the incident model. Even a trusted worker log
+                            // only supplies agent-reported evidence, never a policy decision.
+                            if (row?.type === "sandbox_diagnostic_report") {
+                                if (taskRuntimeTrust(id) === "trusted" && isDiagnosticReport(row)) workerDiagnostics.observeReport(row, id);
+                            } else if (["tool_execution_start", "tool_execution_end", "message_end", "auto_retry_start", "auto_retry_end"].includes(row?.type)) {
                                 if ((row.type.startsWith("tool_execution_") &&
                                     (typeof row.toolCallId !== "string" || !row.toolCallId || typeof row.toolName !== "string")) ||
                                     (row.type === "tool_execution_end" && typeof row.isError !== "boolean" && typeof row.result?.isError !== "boolean" && typeof row.result?.exitCode !== "number") ||

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-better-subagents",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "description": "Pi extension for detached, sandboxed subagent runs that keep the foreground session free.",
   "license": "MIT",
   "type": "module",

package/shared-sandbox-diagnostics.ts

@@ -0,0 +1,491 @@
+// Generated from packages/sandbox-diagnostics/index.ts. Do not edit directly.
+import {
+  chmodSync, closeSync, constants, fstatSync, lstatSync, mkdirSync, openSync,
+  readFileSync, realpathSync, renameSync, rmSync, rmdirSync, writeFileSync,
+} from "node:fs";
+import { createHmac, randomBytes, timingSafeEqual } from "node:crypto";
+
+import { join } from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { harnessSettingsPath, readHarnessSetting, updateHarnessSetting } from "./shared-harness-settings.ts";
+import { isPermissionResource, type PermissionResource } from "./shared-permission-blocker.ts";
+
+export type DiagnosticResource = PermissionResource | "tool-admission" | "sandbox-backend";
+export type DiagnosticContext = "foreground" | "worker" | "background";
+type Basis = "policy-refusal" | "os-permission-error" | "agent-reported";
+export interface DiagnosticsSeams { agentDir?: () => string }
+export interface DiagnosticObservation {
+  tool: string; operation: unknown; resource: DiagnosticResource; basis: Basis;
+  outcome: "denied" | "succeeded";
+}
+/** Redacted transport only: a worker log is never policy authority. */
+export interface DiagnosticReport {
+  schema: 1; type: "sandbox_diagnostic_report"; tool: string; resource: DiagnosticResource;
+  version: string; platform: string; backend: string;
+  outcome: "denied" | "succeeded";
+  operationFingerprint: string; policyFingerprint: string; idFingerprint: string;
+}
+export interface DiagnosticRecord {
+  schema: 1; timestamp: number; version: string; platform: string; backend: string;
+  tool: string; resource: DiagnosticResource; basis: Basis; outcome: "denied" | "succeeded";
+  context: DiagnosticContext; operationFingerprint: string; policyFingerprint: string;
+  fingerprint: string; recoveryOf?: string;
+}
+export interface DiagnosticLosses { age: number; count: number; bytes: number; malformed: number; tampered: number }
+export type DiagnosticIssue = "retention-loss" | "malformed-data" | "tampered-data" | "unsafe-storage" | "unavailable";
+export interface DiagnosticsData {
+  schema: 1; enabled: boolean; records: DiagnosticRecord[]; losses: DiagnosticLosses; issues: DiagnosticIssue[];
+}
+export interface DiagnosticGroup {
+  version: string; backend: string; tool: string; resource: DiagnosticResource; basis: Basis;
+  policyFingerprint: string; denied: number; succeeded: number;
+}
+export interface DiagnosticsAnalysis {
+  groups: DiagnosticGroup[]; observedOperations: number; recovered: number; outstanding: number;
+}
+
+const MAX_BYTES = 1024 * 1024;
+const MAX_ENTRIES = 2000;
+const MAX_AGE = 30 * 24 * 60 * 60 * 1000;
+const TOOLS = new Set([
+  "read", "write", "edit", "bash", "grep", "find", "ls", "process_list", "powershell", "remote_bash",
+  "subagent", "subagent_spawn", "subagent_spawn_batch", "bg_task", "bg_status", "bg_task_spawn", "bg_task_watch",
+  "apply_patch", "failure_disposition", "extension-tool",
+]);
+const BACKENDS = new Set(["macos-seatbelt", "linux-bubblewrap", "unknown", "unavailable"]);
+const PLATFORMS = new Set(["aix", "android", "darwin", "freebsd", "linux", "openbsd", "sunos", "win32", "unknown"]);
+const CONTEXTS = new Set(["foreground", "worker", "background"]);
+const BASES = new Set(["policy-refusal", "os-permission-error", "agent-reported"]);
+// Do not accept arbitrary prerelease/build labels: they can contain paths or caller IDs.
+const VERSION = /^\d{1,6}(?:\.\d{1,6}){0,2}(?:-(?:alpha|beta|rc)(?:\.\d{1,6})?)?$/;
+const FP = /^[A-Za-z0-9_-]{43}$/;
+const REPORT_FIELDS = ["schema", "type", "tool", "resource", "version", "platform", "backend", "outcome", "operationFingerprint", "policyFingerprint", "idFingerprint"];
+const RECORD_FIELDS = ["schema", "timestamp", "version", "platform", "backend", "tool", "resource", "basis", "outcome", "context", "operationFingerprint", "policyFingerprint", "fingerprint", "recoveryOf"];
+const LOSS_FIELDS = ["age", "count", "bytes", "malformed", "tampered"] as const;
+
+class UnsafeStorage extends Error { constructor() { super("Unsafe diagnostics storage."); } }
+const emptyLosses = (): DiagnosticLosses => ({ age: 0, count: 0, bytes: 0, malformed: 0, tampered: 0 });
+const missing = (error: unknown) => (error as NodeJS.ErrnoException)?.code === "ENOENT";
+function plain(value: unknown): value is Record<string, unknown> {
+  return !!value && typeof value === "object" && !Array.isArray(value) &&
+    [Object.prototype, null].includes(Object.getPrototypeOf(value));
+}
+function fields(value: unknown, allowed: readonly string[]): value is Record<string, unknown> {
+  return plain(value) && Reflect.ownKeys(value).every(key => typeof key === "string" && allowed.includes(key));
+}
+function resource(value: unknown): value is DiagnosticResource {
+  return isPermissionResource(value) || value === "tool-admission" || value === "sandbox-backend";
+}
+function integer(value: unknown): value is number { return Number.isSafeInteger(value) && (value as number) >= 0; }
+function digest(key: Buffer, domain: string, value: string): string {
+  return createHmac("sha256", key).update(domain).update("\0").update(value).digest("base64url");
+}
+function authentic(key: Buffer, domain: string, value: string, mac: unknown): boolean {
+  return typeof mac === "string" && FP.test(mac) && timingSafeEqual(Buffer.from(mac), Buffer.from(digest(key, domain, value)));
+}
+
+// Canonicalize only data, without invoking getters/toJSON or persisting any of it.
+function identity(value: unknown): string {
+  const seen = new Set<object>();
+  let nodes = 0;
+  function visit(v: unknown, depth: number): unknown {
+    if (++nodes > 10000 || depth > 32) throw new Error("Diagnostics identity is too large.");
+    if (v === undefined) return ["undefined"];
+    if (v === null || typeof v === "boolean" || typeof v === "string") return [typeof v, v];
+    if (typeof v === "number" && Number.isFinite(v)) return ["number", v];
+    if (!Array.isArray(v) && !plain(v)) throw new Error("Unsupported diagnostics identity.");
+    if (seen.has(v as object)) throw new Error("Cyclic diagnostics identity.");
+    seen.add(v as object);
+    const descriptors = Object.getOwnPropertyDescriptors(v);
+    if (Reflect.ownKeys(v as object).some(k => typeof k !== "string")) throw new Error("Unsupported diagnostics identity.");
+    const keys = Object.keys(descriptors).filter(k => !(Array.isArray(v) && k === "length")).sort();
+    const result = [Array.isArray(v) ? "array" : "object", Array.isArray(v) ? v.length : null, keys.map(k => {
+      const d = descriptors[k];
+      if (!d || !Object.hasOwn(d, "value")) throw new Error("Unsupported diagnostics identity.");
+      return [k, visit(d.value, depth + 1)];
+    })];
+    seen.delete(v as object);
+    return result;
+  }
+  const result = JSON.stringify(visit(value, 0));
+  if (Buffer.byteLength(result) > MAX_BYTES) throw new Error("Diagnostics identity is too large.");
+  return result;
+}
+
+export function diagnosticsEnabled(seams: DiagnosticsSeams = {}): boolean {
+  const value = readHarnessSetting("sandboxDiagnostics", seams);
+  return fields(value, ["version", "enabled"]) && value.version === 1 && value.enabled === true;
+}
+export function diagnosticPackageVersion(manifest: URL): string {
+  try {
+    const value: unknown = JSON.parse(readFileSync(manifest, "utf8"));
+    return plain(value) && typeof value.version === "string" && VERSION.test(value.version) ? value.version : "unknown";
+  } catch { return "unknown"; }
+}
+// Settings are atomically replaced by the parent. Workers must not acquire a writable settings lock.
+function relayEnabled(seams: DiagnosticsSeams): boolean {
+  let settings: unknown;
+  try { settings = JSON.parse(readFileSync(harnessSettingsPath(seams), "utf8")); }
+  catch (error) { if (missing(error)) return false; throw error; }
+  if (!plain(settings) || (Object.hasOwn(settings, "piBetterHarness") && !plain(settings.piBetterHarness))) {
+    throw new Error("Invalid diagnostics settings.");
+  }
+  const value = (settings.piBetterHarness as Record<string, unknown> | undefined)?.sandboxDiagnostics;
+  return fields(value, ["version", "enabled"]) && value.version === 1 && value.enabled === true;
+}
+export function isDiagnosticReport(value: unknown): value is DiagnosticReport {
+  if (!fields(value, REPORT_FIELDS) || Reflect.ownKeys(value).length !== REPORT_FIELDS.length ||
+    Object.values(Object.getOwnPropertyDescriptors(value)).some(d => !Object.hasOwn(d, "value"))) return false;
+  return value.schema === 1 && value.type === "sandbox_diagnostic_report" && TOOLS.has(value.tool as string) &&
+    typeof value.version === "string" && (VERSION.test(value.version) || value.version === "unknown") &&
+    PLATFORMS.has(value.platform as string) && BACKENDS.has(value.backend as string) &&
+    resource(value.resource) && ["denied", "succeeded"].includes(value.outcome as string) &&
+    [value.operationFingerprint, value.policyFingerprint, value.idFingerprint].every(f => typeof f === "string" && FP.test(f));
+}
+export function setDiagnosticsEnabled(enabled: boolean, seams: DiagnosticsSeams = {}): void {
+  if (typeof enabled !== "boolean") throw new TypeError("Diagnostics enabled must be boolean.");
+  updateHarnessSetting("sandboxDiagnostics", () => ({ version: 1, enabled }), seams);
+}
+
+function stat(path: string) {
+  try { return lstatSync(path); } catch (error) { if (missing(error)) return undefined; throw error; }
+}
+function safeFile(path: string): void {
+  const s = stat(path);
+  if (s && (!s.isFile() || s.isSymbolicLink() || s.nlink !== 1)) throw new UnsafeStorage();
+}
+function directory(seams: DiagnosticsSeams, create: boolean): string | undefined {
+  let root = (seams.agentDir ?? getAgentDir)();
+  if (create && !stat(root)) mkdirSync(root, { recursive: true, mode: 0o700 });
+  const s = stat(root);
+  if (!s) return undefined;
+  if (!s.isDirectory() || s.isSymbolicLink()) throw new UnsafeStorage();
+  root = realpathSync(root);
+  for (const component of ["diagnostics", "sandbox"]) {
+    root = join(root, component);
+    if (create && !stat(root)) {
+      try { mkdirSync(root, { mode: 0o700 }); } catch (error) { if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error; }
+    }
+    const entry = stat(root);
+    if (!entry) return undefined;
+    if (!entry.isDirectory() || entry.isSymbolicLink()) throw new UnsafeStorage();
+    if (create) chmodSync(root, 0o700);
+  }
+  return root;
+}
+function readSafe(path: string, bound: number): string {
+  safeFile(path);
+  const fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+  try {
+    const s = fstatSync(fd);
+    if (!s.isFile() || s.nlink !== 1) throw new UnsafeStorage();
+    if (s.size > bound) throw new Error("Diagnostics file exceeds its bound.");
+    return readFileSync(fd, "utf8");
+  } finally { closeSync(fd); }
+}
+function atomic(path: string, contents: string): void {
+  safeFile(path);
+  const pending = `${path}.${randomBytes(16).toString("hex")}.tmp`;
+  try {
+    writeFileSync(pending, contents, { mode: 0o600, flag: "wx" });
+    safeFile(path);
+    renameSync(pending, path);
+  } finally { rmSync(pending, { force: true }); }
+}
+function locked<T>(dir: string, action: () => T): T {
+  const path = join(dir, "events.jsonl");
+  const lockPath = `${path}.lock`;
+  for (let attempt = 0; attempt < 500; attempt++) {
+    // A stopped synchronous writer cannot renew a lease. Never evict by age:
+    // an orphan blocks sampling until the human removes it with collectors stopped.
+    try { mkdirSync(lockPath, { mode: 0o700 }); }
+    catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+      const s = stat(lockPath);
+      if (s && (!s.isDirectory() || s.isSymbolicLink())) throw new UnsafeStorage();
+      if (attempt === 499) throw Object.assign(new Error("Diagnostics storage is locked."), { code: "ELOCKED" });
+      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 10);
+      continue;
+    }
+    try {
+      const lock = lstatSync(lockPath);
+      if (!lock.isDirectory() || lock.isSymbolicLink()) throw new UnsafeStorage();
+      for (const name of ["events.jsonl", "installation.key", "export.json"]) safeFile(join(dir, name));
+      return action();
+    } finally { rmdirSync(lockPath); }
+  }
+  throw new Error("Cannot lock diagnostics.");
+}
+function installationKey(dir: string, create: boolean): Buffer {
+  const path = join(dir, "installation.key");
+  safeFile(path);
+  if (!stat(path)) {
+    if (!create || stat(join(dir, "events.jsonl"))) throw new Error("Missing diagnostics installation key.");
+    atomic(path, `${randomBytes(32).toString("hex")}\n`);
+  }
+  const raw = readSafe(path, 65);
+  if (!/^[a-f0-9]{64}\n$/.test(raw)) throw new Error("Invalid diagnostics installation key.");
+  chmodSync(path, 0o600);
+  return Buffer.from(raw.trim(), "hex");
+}
+function selectRecord(v: Record<string, unknown>): DiagnosticRecord | undefined {
+  if (!fields(v, [...RECORD_FIELDS, "mac"]) || v.schema !== 1 || !integer(v.timestamp) ||
+    typeof v.version !== "string" || !(VERSION.test(v.version) || v.version === "unknown") ||
+    !PLATFORMS.has(v.platform as string) || !BACKENDS.has(v.backend as string) || !TOOLS.has(v.tool as string) ||
+    !resource(v.resource) || !BASES.has(v.basis as string) || !CONTEXTS.has(v.context as string) ||
+    !["denied", "succeeded"].includes(v.outcome as string) ||
+    ![v.operationFingerprint, v.policyFingerprint, v.fingerprint].every(f => typeof f === "string" && FP.test(f)) ||
+    (v.outcome === "denied" ? Object.hasOwn(v, "recoveryOf") : typeof v.recoveryOf !== "string" || !FP.test(v.recoveryOf))) return undefined;
+  const record: DiagnosticRecord = {
+    schema: 1, timestamp: v.timestamp, version: v.version, platform: v.platform as string,
+    backend: v.backend as string, tool: v.tool as string, resource: v.resource,
+    basis: v.basis as Basis, outcome: v.outcome as DiagnosticRecord["outcome"], context: v.context as DiagnosticContext,
+    operationFingerprint: v.operationFingerprint as string, policyFingerprint: v.policyFingerprint as string, fingerprint: v.fingerprint as string,
+  };
+  if (record.outcome === "succeeded") record.recoveryOf = v.recoveryOf as string;
+  return record;
+}
+function sameOperation(a: DiagnosticRecord, b: DiagnosticRecord): boolean {
+  return a.context === b.context && a.tool === b.tool && a.operationFingerprint === b.operationFingerprint;
+}
+interface Journal { records: DiagnosticRecord[]; losses: DiagnosticLosses }
+function load(dir: string, key: Buffer): Journal {
+  const path = join(dir, "events.jsonl");
+  if (!stat(path)) return { records: [], losses: emptyLosses() };
+  chmodSync(path, 0o600);
+  const raw = readSafe(path, MAX_BYTES);
+  const lines = raw.split("\n");
+  if (lines.at(-1) === "") lines.pop();
+  const first = lines.shift();
+  const losses = emptyLosses();
+  let header: Record<string, unknown> | undefined;
+  try {
+    const v: unknown = JSON.parse(first ?? "");
+    const candidateLosses = plain(v) ? v.losses : undefined;
+    if (fields(v, ["schema", "kind", "losses", "count", "digest", "mac"]) && v.schema === 1 && v.kind === "journal" &&
+      fields(candidateLosses, LOSS_FIELDS) && LOSS_FIELDS.every(k => integer(candidateLosses[k])) && integer(v.count) &&
+      typeof v.digest === "string" && FP.test(v.digest)) {
+      const l = candidateLosses;
+      const selected = { schema: 1, kind: "journal", losses: { age: l.age, count: l.count, bytes: l.bytes, malformed: l.malformed, tampered: l.tampered }, count: v.count, digest: v.digest };
+      if (authentic(key, "header", JSON.stringify(selected), v.mac)) {
+        header = v;
+        for (const k of LOSS_FIELDS) losses[k] = l[k] as number;
+      } else losses.tampered++;
+    } else losses.malformed++;
+  } catch { losses.malformed++; }
+  if (header && (header.count !== lines.length || header.digest !== digest(key, "journal", lines.join("\n")))) losses.tampered++;
+  const records: DiagnosticRecord[] = [];
+  const seen = new Set<string>();
+  const denied = new Map<string, DiagnosticRecord>();
+  for (const line of lines) {
+    let v: unknown;
+    try { v = JSON.parse(line); } catch { losses.malformed++; continue; }
+    const record = plain(v) ? selectRecord(v) : undefined;
+    if (!record) { losses.malformed++; continue; }
+    if (!authentic(key, "event", JSON.stringify(record), (v as Record<string, unknown>).mac) || seen.has(record.fingerprint)) {
+      losses.tampered++; continue;
+    }
+    if (record.outcome === "succeeded") {
+      const prior = denied.get(record.recoveryOf!);
+      if (!prior || !sameOperation(prior, record) || prior.timestamp > record.timestamp) { losses.tampered++; continue; }
+      denied.delete(prior.fingerprint);
+    } else denied.set(record.fingerprint, record);
+    seen.add(record.fingerprint);
+    records.push(record);
+  }
+  return { records, losses };
+}
+function encode(journal: Journal, key: Buffer): string {
+  const lines = journal.records.map(record => JSON.stringify({ ...record, mac: digest(key, "event", JSON.stringify(record)) }));
+  const header = { schema: 1, kind: "journal", losses: journal.losses, count: lines.length, digest: digest(key, "journal", lines.join("\n")) };
+  return `${JSON.stringify({ ...header, mac: digest(key, "header", JSON.stringify(header)) })}\n${lines.length ? `${lines.join("\n")}\n` : ""}`;
+}
+function retain(journal: Journal, key: Buffer, now: number): boolean {
+  let changed = false;
+  function remove(index: number, reason: "age" | "count" | "bytes") {
+    const [removed] = journal.records.splice(index, 1);
+    if (!removed) return;
+    journal.losses[reason]++;
+    // Recovery cannot outlive its evidence; count both discarded records.
+    if (removed.outcome === "denied") {
+      const recovery = journal.records.findIndex(r => r.recoveryOf === removed.fingerprint);
+      if (recovery !== -1) { journal.records.splice(recovery, 1); journal.losses[reason]++; }
+    }
+    changed = true;
+  }
+  for (let i = 0; i < journal.records.length;) {
+    if (journal.records[i]!.timestamp < now - MAX_AGE) remove(i, "age"); else i++;
+  }
+  while (journal.records.length > MAX_ENTRIES) remove(0, "count");
+  // The full signed header and UTF-8 newlines count towards the byte limit.
+  while (Buffer.byteLength(encode(journal, key)) > MAX_BYTES && journal.records.length) remove(0, "bytes");
+  return changed;
+}
+function issues(losses: DiagnosticLosses): DiagnosticIssue[] {
+  const result: DiagnosticIssue[] = [];
+  if (losses.age || losses.count || losses.bytes) result.push("retention-loss");
+  if (losses.malformed) result.push("malformed-data");
+  if (losses.tampered) result.push("tampered-data");
+  return result;
+}
+
+export class SandboxDiagnostics {
+  constructor(private readonly options: {
+    context: DiagnosticContext; version: string; policy: () => unknown; backend: () => string | undefined;
+    agentDir?: () => string; onError?: (error: unknown) => void; now?: () => number;
+    relay?: (report: DiagnosticReport) => void;
+  }) {}
+  private relayKey?: Buffer;
+  private readonly pending = new Map<string, DiagnosticResource>();
+  private report(error: unknown): void { try { this.options.onError?.(error); } catch { /* Diagnostics never change tool outcomes. */ } }
+  observe(input: DiagnosticObservation): void {
+    this.collect(input);
+  }
+  /** Caller must gate this on parent-authored task runtime provenance, not a claim in the log. */
+  observeReport(value: unknown, runIdentity: string): void {
+    try {
+      if (!isDiagnosticReport(value) || typeof runIdentity !== "string" || !runIdentity || this.options.context !== "worker" || this.options.relay) return;
+      this.collect({ tool: value.tool, resource: value.resource, basis: "agent-reported", outcome: value.outcome,
+        operation: { run: runIdentity, fingerprint: value.operationFingerprint } }, { value, runIdentity });
+    } catch { this.report(new Error("Diagnostics collection has gaps.")); }
+  }
+  private emit(input: DiagnosticObservation, tool: string, operation: string): void {
+    const key = this.relayKey ??= randomBytes(32);
+    const operationFingerprint = digest(key, "operation", operation);
+    const prior = this.pending.get(operationFingerprint);
+    if (input.outcome === "succeeded" && !prior) return;
+    const backend = this.options.backend();
+    const report: DiagnosticReport = {
+      schema: 1, type: "sandbox_diagnostic_report", tool, resource: prior && input.outcome === "succeeded" ? prior : input.resource,
+      version: typeof this.options.version === "string" && VERSION.test(this.options.version) ? this.options.version : "unknown",
+      platform: PLATFORMS.has(process.platform) ? process.platform : "unknown",
+      backend: typeof backend === "string" && BACKENDS.has(backend) ? backend : "unknown",
+      outcome: input.outcome, operationFingerprint, policyFingerprint: digest(key, "policy", identity(this.options.policy())),
+      idFingerprint: digest(key, "report-identity", randomBytes(32).toString("hex")),
+    };
+    this.options.relay!(report);
+    if (input.outcome === "succeeded") this.pending.delete(operationFingerprint);
+    else {
+      this.pending.delete(operationFingerprint);
+      this.pending.set(operationFingerprint, input.resource);
+      while (this.pending.size > MAX_ENTRIES) this.pending.delete(this.pending.keys().next().value!);
+    }
+  }
+  private collect(input: DiagnosticObservation, imported?: { value: DiagnosticReport; runIdentity: string }): void {
+    try {
+      if (!(this.options.relay ? relayEnabled(this.options) : diagnosticsEnabled(this.options))) return;
+      if (!CONTEXTS.has(this.options.context) || !resource(input.resource) || !BASES.has(input.basis) ||
+        !["denied", "succeeded"].includes(input.outcome)) throw new Error("Invalid diagnostic observation.");
+      const now = (this.options.now ?? Date.now)();
+      if (!integer(now)) throw new Error("Invalid diagnostics clock.");
+      const tool = TOOLS.has(input.tool) ? input.tool : "extension-tool";
+      const operation = identity({ tool: input.tool, input: input.operation });
+      if (this.options.relay) { this.emit(input, tool, operation); return; }
+      // Unrelated successes must not initialize diagnostics storage or evaluate policy.
+      const dir = directory(this.options, input.outcome === "denied");
+      if (!dir) return;
+      if (input.outcome === "succeeded" && !stat(join(dir, "events.jsonl"))) return;
+      locked(dir, () => {
+        const key = installationKey(dir, input.outcome === "denied");
+        const journal = load(dir, key);
+        const before = JSON.stringify(journal.losses);
+        const pruned = retain(journal, key, now);
+        const fingerprint = imported ? digest(key, "relay-event-identity", identity([imported.runIdentity, imported.value.idFingerprint])) :
+          digest(key, "event-identity", randomBytes(32).toString("hex"));
+        // Signed record identities survive parent reloads and full log rescans.
+        if (imported && journal.records.some(r => r.fingerprint === fingerprint)) {
+          if (pruned || journal.losses.malformed || journal.losses.tampered) atomic(join(dir, "events.jsonl"), encode(journal, key));
+          if (issues(journal.losses).length) this.report(new Error("Diagnostics collection has gaps."));
+          return;
+        }
+        const operationFingerprint = digest(key, "operation", operation);
+        const recovered = new Set(journal.records.flatMap(r => r.recoveryOf ? [r.recoveryOf] : []));
+        const prior = [...journal.records].reverse().find(r => r.outcome === "denied" && r.context === this.options.context &&
+          r.tool === tool && r.operationFingerprint === operationFingerprint && r.timestamp <= now);
+        if (input.outcome === "succeeded" && (!prior || recovered.has(prior.fingerprint))) {
+          if (pruned || issues(journal.losses).some(i => i !== "retention-loss")) atomic(join(dir, "events.jsonl"), encode(journal, key));
+          if (issues(journal.losses).length) this.report(new Error("Diagnostics collection has gaps."));
+          return;
+        }
+        const backend = imported?.value.backend ?? this.options.backend();
+        const version = imported?.value.version ?? this.options.version;
+        const record: DiagnosticRecord = {
+          schema: 1, timestamp: now,
+          version: typeof version === "string" && VERSION.test(version) ? version : "unknown",
+          platform: imported?.value.platform ?? (PLATFORMS.has(process.platform) ? process.platform : "unknown"),
+          backend: typeof backend === "string" && BACKENDS.has(backend) ? backend : "unknown",
+          tool, resource: input.outcome === "succeeded" && prior ? prior.resource : input.resource,
+          basis: input.outcome === "succeeded" && prior ? prior.basis : input.basis,
+          outcome: input.outcome, context: this.options.context,
+          operationFingerprint, policyFingerprint: imported ? digest(key, "relay-policy", identity([imported.runIdentity, imported.value.policyFingerprint])) :
+            digest(key, "policy", identity(this.options.policy())),
+          fingerprint,
+        };
+        if (prior && input.outcome === "succeeded") record.recoveryOf = prior.fingerprint;
+        journal.records.push(record);
+        retain(journal, key, now);
+        atomic(join(dir, "events.jsonl"), encode(journal, key));
+        if (before !== JSON.stringify(journal.losses) || journal.losses.malformed || journal.losses.tampered) this.report(new Error("Diagnostics collection has gaps."));
+      });
+    } catch (error) { this.report(this.options.relay || imported ? new Error("Diagnostics collection has gaps.") : error); }
+  }
+}
+
+export function readDiagnostics(seams: DiagnosticsSeams = {}): DiagnosticsData {
+  const data: DiagnosticsData = { schema: 1, enabled: false, records: [], losses: emptyLosses(), issues: [] };
+  try { data.enabled = diagnosticsEnabled(seams); } catch { data.issues.push("unavailable"); }
+  try {
+    const dir = directory(seams, false);
+    if (!dir || !stat(join(dir, "events.jsonl"))) return data;
+    locked(dir, () => {
+      const key = installationKey(dir, false);
+      const journal = load(dir, key);
+      if (retain(journal, key, Date.now())) atomic(join(dir, "events.jsonl"), encode(journal, key));
+      data.records = journal.records;
+      data.losses = journal.losses;
+      data.issues.push(...issues(journal.losses));
+    });
+  } catch (error) { data.issues.push(error instanceof UnsafeStorage ? "unsafe-storage" : "unavailable"); }
+  return data;
+}
+export function analyzeDiagnostics(data: DiagnosticsData): DiagnosticsAnalysis {
+  const groups = new Map<string, DiagnosticGroup>();
+  const operations = new Map<string, { latestDenial: string; recovered: boolean }>();
+  for (const r of data.records) {
+    const key = JSON.stringify([r.version, r.backend, r.tool, r.resource, r.basis, r.policyFingerprint]);
+    let group = groups.get(key);
+    if (!group) {
+      group = { version: r.version, backend: r.backend, tool: r.tool, resource: r.resource, basis: r.basis, policyFingerprint: r.policyFingerprint, denied: 0, succeeded: 0 };
+      groups.set(key, group);
+    }
+    if (r.outcome === "denied") group.denied++; else group.succeeded++;
+    const opKey = JSON.stringify([r.context, r.tool, r.operationFingerprint]);
+    if (r.outcome === "denied") operations.set(opKey, { latestDenial: r.fingerprint, recovered: false });
+    else {
+      const operation = operations.get(opKey);
+      if (operation && operation.latestDenial === r.recoveryOf) operation.recovered = true;
+    }
+  }
+  const recovered = [...operations.values()].filter(op => op.recovered).length;
+  return { groups: [...groups.values()], observedOperations: operations.size, recovered, outstanding: operations.size - recovered };
+}
+export function formatDiagnosticsSummary(data: DiagnosticsData): string {
+  const analysis = analyzeDiagnostics(data);
+  const l = data.losses;
+  const lines = [
+    `Sandbox diagnostics: ${data.enabled ? "enabled" : "disabled"}; ${data.records.length} retained observations.`,
+    `Observed operations: ${analysis.observedOperations}; recovered: ${analysis.recovered}; outstanding: ${analysis.outstanding}.`,
+    `Journal gaps: ${data.issues.length ? data.issues.join(", ") : "none recorded"}. Losses: age=${l.age}, count=${l.count}, bytes=${l.bytes}, malformed=${l.malformed}, tampered=${l.tampered}.`,
+    "Observations only; not a security verdict. Collection errors may not persist; shell output is not classified.",
+  ];
+  for (const g of analysis.groups.slice(0, 20)) lines.push(`${g.version} ${g.backend} ${g.tool} ${g.resource} ${g.basis} policy=${g.policyFingerprint.slice(0, 12)}: denied=${g.denied}, succeeded=${g.succeeded}`);
+  if (analysis.groups.length > 20) lines.push(`${analysis.groups.length - 20} additional groups in the local JSON export.`);
+  return lines.join("\n");
+}
+export function exportDiagnostics(seams: DiagnosticsSeams = {}): string {
+  const data = readDiagnostics(seams);
+  const dir = directory(seams, true)!;
+  const path = join(dir, "export.json");
+  locked(dir, () => atomic(path, `${JSON.stringify({ schema: 1, enabled: data.enabled, records: data.records, losses: data.losses, issues: data.issues, coverage: { sampling: true, shellOutputClassified: false, collectionErrorsMayNotPersist: true }, analysis: analyzeDiagnostics(data) }, null, 2)}\n`));
+  return path;
+}

package/shared-task-files.ts

@@ -6,6 +6,7 @@ import { constants, realpathSync } from "node:fs";
 import { access, lstat, mkdir, open, readFile, stat, unlink, writeFile } from "node:fs/promises";
 import { basename, dirname, join } from "node:path";
 import type { ReadOperations, WriteOperations, EditOperations } from "@earendil-works/pi-coding-agent";
+import type { SandboxDiagnostics, DiagnosticResource } from "./shared-sandbox-diagnostics.ts";
 import {
     canonicalizePath, compileWritePolicy, evaluateDeleteAccess, evaluateReadAccess, evaluateWriteAccess, maybeBuildSandboxCommand,
     type CompiledSandboxWritePolicy, type SandboxSeams, type SandboxWritePolicy, type WriteAccessDecision,
@@ -161,10 +162,29 @@ function mimeType(data: Buffer): string | null {
     return null;
 }
 
-export function createTaskFileOperations(controller: TaskFileController): {
+export function createTaskFileOperations(controller: TaskFileController, diagnostics?: Pick<SandboxDiagnostics, "observe">, toolOverride?: string): {
     read: ReadOperations; write: WriteOperations; edit: EditOperations; remove: TaskRemoveOperations; check: TaskAccessChecks;
 } {
-    async function run(operation: Operation, path: string, content?: string): Promise<Buffer | void> {
+    function resource(path: string, policy: CompiledSandboxWritePolicy): DiagnosticResource {
+        path = canonicalizePath(path);
+        const inside = (root: string) => path === root || path.startsWith(root.endsWith("/") ? root : `${root}/`);
+        if (policy.credentialPaths?.some(inside)) return "credential-files";
+        return inside(policy.writableRoot) ? "project-files" : "outside-project-files";
+    }
+    const observe = (tool: string, operation: Operation | "remove", path: string, policy: CompiledSandboxWritePolicy,
+        basis: "policy-refusal" | "os-permission-error", outcome: "denied" | "succeeded") =>
+        { try { diagnostics?.observe({ tool, operation: { operation, path }, resource: resource(path, policy), basis, outcome }); }
+          catch { /* Diagnostics must never change the operation's outcome. */ } };
+
+    async function run(operation: Operation, path: string, content?: string, tool = "read"): Promise<Buffer | void> {
+        tool = toolOverride ?? tool;
+        const result = await perform(operation, path, content, tool);
+        try { diagnostics?.observe({ tool, operation: { operation, path }, resource: "unknown",
+            basis: "os-permission-error", outcome: "succeeded" }); } catch { /* Observation is nonfatal. */ }
+        return result;
+    }
+
+    async function perform(operation: Operation, path: string, content?: string, tool = "read"): Promise<Buffer | void> {
         const plan = controller.requireLaunchPlan();
         if (!plan.confined) {
             switch (operation) {
@@ -193,7 +213,10 @@ export function createTaskFileOperations(controller: TaskFileController): {
         const policy = compileWritePolicy(plan.policy);
         if (operation === "unlink") {
             const decision = removeDecision(path, policy);
-            if (!decision.allowed) throw refusal("remove", decision);
+            if (!decision.allowed) {
+                observe(tool, operation, path, policy, "policy-refusal", "denied");
+                throw refusal("remove", decision);
+            }
         }
         const writing = operation === "write" || operation === "mkdir" || operation === "access-edit" || operation === "unlink";
         const decision = writing ? evaluateWriteAccess(path, policy) : evaluateReadAccess(path, policy);
@@ -201,14 +224,18 @@ export function createTaskFileOperations(controller: TaskFileController): {
             if (operation === "mkdir" && decision.reason === "permission-denied") {
                 // SDK write prepares the parent even when it already exists.
                 // Confirm that no-op inside confinement; never grant mkdir.
-                try { await run("existing-directory", path); return; } catch { /* Preserve the original refusal. */ }
+                try { await run("existing-directory", path, undefined, tool); return; } catch { /* Preserve the original refusal. */ }
             }
             const detail = "deniedBy" in decision ? ` (protected by ${decision.deniedBy})` : "";
+            observe(tool, operation, path, policy, "policy-refusal", "denied");
             throw new Error(`Task sandbox refused to ${writing ? "write" : "read"} ${decision.path}: ${decision.reason}${detail}.`);
         }
         if (operation === "access-edit") {
             const readable = evaluateReadAccess(path, policy);
-            if (!readable.allowed) throw new Error(`Task sandbox refused to read ${readable.path}: ${readable.reason}.`);
+            if (!readable.allowed) {
+                observe(tool, operation, path, policy, "policy-refusal", "denied");
+                throw new Error(`Task sandbox refused to read ${readable.path}: ${readable.reason}.`);
+            }
         }
         if (content !== undefined && Buffer.byteLength(content, "utf8") > MAX_FILE_BYTES) {
             throw new Error("File exceeds 8 MiB operation limit");
@@ -256,6 +283,9 @@ export function createTaskFileOperations(controller: TaskFileController): {
             child.stderr.on("data", (chunk: Buffer) => { stderr = (stderr + chunk.toString()).slice(-2048); });
             child.stdin.on("error", () => {}); // An early sandbox failure may close stdin.
             child.on("error", (error) => {
+                if (["EACCES", "EPERM"].includes((error as NodeJS.ErrnoException).code ?? "")) {
+                    observe(tool, operation, path, policy, "os-permission-error", "denied");
+                }
                 if (!finished) { finished = true; clearTimeout(timer); void unlink(profilePath).catch(() => {}); reject(error); }
             });
             child.on("close", (code) => {
@@ -270,6 +300,7 @@ export function createTaskFileOperations(controller: TaskFileController): {
                 if (!result.ok) {
                     const error = new Error(result.error ?? `Task file sandbox failed (${code})`) as NodeJS.ErrnoException;
                     error.code = result.code;
+                    if (["EACCES", "EPERM"].includes(result.code ?? "")) observe(tool, operation, path, policy, "os-permission-error", "denied");
                     return reject(error);
                 }
                 if (code !== 0) return reject(new Error(`Task file sandbox exited ${code}: ${stderr}`));
@@ -284,11 +315,14 @@ export function createTaskFileOperations(controller: TaskFileController): {
         if (!plan.confined) return;
         const policy = compileWritePolicy(plan.policy);
         const decision = verb === "write" ? evaluateWriteAccess(path, policy) : removeDecision(path, policy);
-        if (!decision.allowed) throw refusal(verb, decision);
+        if (!decision.allowed) {
+            observe("apply_patch", verb === "remove" ? "unlink" : "write", path, policy, "policy-refusal", "denied");
+            throw refusal(verb, decision);
+        }
     };
 
     return {
-        remove: { remove: (path) => run("unlink", path) as Promise<void> },
+        remove: { remove: (path) => run("unlink", path, undefined, "apply_patch") as Promise<void> },
         check: { write: check("write"), remove: check("remove") },
         read: {
             readFile: (path) => run("read", path) as Promise<Buffer>,
@@ -296,13 +330,13 @@ export function createTaskFileOperations(controller: TaskFileController): {
             detectImageMimeType: async (path) => mimeType(await run("mime", path) as Buffer),
         },
         write: {
-            mkdir: (path) => run("mkdir", path) as Promise<void>,
-            writeFile: (path, content) => run("write", path, content) as Promise<void>,
+            mkdir: (path) => run("mkdir", path, undefined, "write") as Promise<void>,
+            writeFile: (path, content) => run("write", path, content, "write") as Promise<void>,
         },
         edit: {
-            readFile: (path) => run("read", path) as Promise<Buffer>,
-            access: (path) => run("access-edit", path) as Promise<void>,
-            writeFile: (path, content) => run("write", path, content) as Promise<void>,
+            readFile: (path) => run("read", path, undefined, "edit") as Promise<Buffer>,
+            access: (path) => run("access-edit", path, undefined, "edit") as Promise<void>,
+            writeFile: (path, content) => run("write", path, content, "edit") as Promise<void>,
         },
     };
 }

package/shared-task-sandbox.ts

@@ -15,6 +15,7 @@ import { canonicalizePath, compileWritePolicy, isRemovableUnderWrite, maybeBuild
 import { createTaskFileOperations, type TaskFileController } from "./shared-task-files.ts";
 import { APPLY_PATCH_TOOL, createApplyPatchToolDefinition } from "./shared-task-apply-patch.ts";
 import { createProcessListToolDefinition, PROCESS_LIST_TOOL } from "./shared-task-process-list.ts";
+import type { SandboxDiagnostics, DiagnosticResource } from "./shared-sandbox-diagnostics.ts";
 
 export const TASK_BUILTINS = Object.freeze(["read", "write", "edit", "bash", PROCESS_LIST_TOOL] as const);
 /** Harness adapters that follow the file rules; each is a task builtin only when the profile enables it. */
@@ -103,14 +104,26 @@ export function createTaskScratch(): { path: string; anchor: string } {
 export function createTaskBashOperations(
     controller: TaskFileController,
     shellPath: () => string | undefined = () => undefined,
+    diagnostics?: Pick<SandboxDiagnostics, "observe">,
 ): BashOperations {
     return {
         async exec(command, cwd, options) {
+            const observed = (basis: "policy-refusal" | "os-permission-error", outcome: "denied" | "succeeded") => {
+                try { diagnostics?.observe({ tool: "bash", operation: { command, cwd }, resource: "command-execution", basis, outcome }); }
+                catch { /* Observation is nonfatal. */ }
+            };
             const configuredShell = shellPath();
             const local = createLocalBashOperations(configuredShell ? { shellPath: configuredShell } : {});
             const plan = controller.requireLaunchPlan();
-            if (!plan.confined) return local.exec(command, cwd, options);
-            if (plan.policy.permissions?.commands === false) throw new Error("Sandbox: Run commands & applications is Off.");
+            if (!plan.confined) {
+                const result = await local.exec(command, cwd, options);
+                if (result.exitCode === 0) observed("os-permission-error", "succeeded");
+                return result;
+            }
+            if (plan.policy.permissions?.commands === false) {
+                observed("policy-refusal", "denied");
+                throw new Error("Sandbox: Run commands & applications is Off.");
+            }
             // An explicit path avoids SDK fallback spawning PATH-resolved `which`.
             const shell = getShellConfig(configuredShell ?? "/bin/bash");
             const sdkUtils = join(PiCodingAgent.getPackageDir(), "dist", "utils");
@@ -158,9 +171,18 @@ export function createTaskBashOperations(
                         cleanup();
                         if (options.signal?.aborted) reject(new Error("aborted"));
                         else if (timedOut) reject(new Error(`timeout:${options.timeout}`));
-                        else resolve({ exitCode });
-                    }, (error: unknown) => { cleanup(); reject(error); });
+                        else {
+                            if (exitCode === 0) observed("os-permission-error", "succeeded");
+                            resolve({ exitCode });
+                        }
+                    }, (error: unknown) => {
+                        cleanup();
+                        reject(error);
+                    });
                 });
+            } catch (error) {
+                if (["EACCES", "EPERM"].includes((error as NodeJS.ErrnoException)?.code ?? "")) observed("os-permission-error", "denied");
+                throw error;
             } finally {
                 await unlink(profilePath).catch((error: NodeJS.ErrnoException) => {
                     if (error.code !== "ENOENT") throw error;
@@ -188,13 +210,14 @@ export function installTaskTools(pi: ExtensionAPI, options: {
     processAccess?: () => "off" | "read";
     /** Build the admitted bash definition from the confined operations (default: the SDK bash tool). */
     bashDefinition?: (cwd: string, operations: BashOperations) => ReturnType<typeof createBashToolDefinition>;
+    diagnostics?: Pick<SandboxDiagnostics, "observe">;
 }) {
     const { controller } = options;
     const sourceKey = (path: string) => path.startsWith("<") ? path : canonicalizePath(path);
     const trustedSources = new Set(options.trustedSources.map(sourceKey));
     const trustedSource = (path: string | undefined) => path !== undefined && trustedSources.has(sourceKey(path));
-    const files = createTaskFileOperations(controller);
-    const bash = createTaskBashOperations(controller, options.shellPath);
+    const files = createTaskFileOperations(controller, options.diagnostics);
+    const bash = createTaskBashOperations(controller, options.shellPath, options.diagnostics);
     const schemas = new Map<string, unknown>();
     let currentCwd: string | undefined;
     const register = (cwd: string) => {
@@ -211,37 +234,48 @@ export function installTaskTools(pi: ExtensionAPI, options: {
         pi.registerTool(own(options.bashDefinition ? options.bashDefinition(cwd, bash) : createBashToolDefinition(cwd, { operations: bash })));
         pi.registerTool(own(createProcessListToolDefinition(cwd, controller, options.processAccess ?? (() => "off"))) as any);
         if (options.applyPatch) {
+            const patchFiles = createTaskFileOperations(controller, options.diagnostics, "apply_patch");
             pi.registerTool(own(createApplyPatchToolDefinition(cwd, {
-                readFile: files.read.readFile, writeFile: files.write.writeFile, mkdir: files.write.mkdir,
-                remove: files.remove.remove, checkWrite: files.check.write, checkRemove: files.check.remove,
+                readFile: patchFiles.read.readFile, writeFile: patchFiles.write.writeFile, mkdir: patchFiles.write.mkdir,
+                remove: patchFiles.remove.remove, checkWrite: patchFiles.check.write, checkRemove: patchFiles.check.remove,
             }, PiCodingAgent.withFileMutationQueue)) as any);
         }
     };
     register(options.cwd);
     pi.on("user_bash", () => ({ operations: bash }));
-    pi.on("tool_call", (event) => {
+    pi.on("tool_call", (event, ctx) => {
+        const blocked = (reason: string, resource: DiagnosticResource) => {
+            try { options.diagnostics?.observe({ tool: event.toolName, operation: { input: event.input, cwd: ctx?.cwd ?? currentCwd }, resource,
+                basis: "policy-refusal", outcome: "denied" }); } catch { /* Observation is nonfatal. */ }
+            return { block: true, reason };
+        };
         try {
             const plan = controller.requireLaunchPlan();
             if (!plan.confined) return;
             const tool = pi.getAllTools().find((candidate) => candidate.name === event.toolName);
             if (schemas.has(event.toolName)) {
                 if (!tool || tool.parameters !== schemas.get(event.toolName) || !trustedSource(tool.sourceInfo?.path)) {
-                    return { block: true, reason: `Sandbox: ${event.toolName} was replaced by an unverified implementation.` };
+                    return blocked(`Sandbox: ${event.toolName} was replaced by an unverified implementation.`, "tool-admission");
                 }
                 if (event.toolName === "bash" && plan.policy.permissions?.commands === false) {
-                    return { block: true, reason: "Sandbox: Run commands & applications is Off." };
+                    return blocked("Sandbox: Run commands & applications is Off.", "command-execution");
                 }
                 if (event.toolName === PROCESS_LIST_TOOL && options.processAccess?.() !== "read") {
-                    return { block: true, reason: "Sandbox: Process access is Off. Enable Read in /sandbox." };
+                    return blocked("Sandbox: Process access is Off. Enable Read in /sandbox.", "process-inspection");
                 }
                 return;
             }
             if (options.admitExtensionTool?.(event.toolName, event.input, tool?.sourceInfo?.path)) return;
-            return { block: true, reason: `Sandbox: ${event.toolName} has no verified task execution adapter. Use a guarded file tool or confined bash command.` };
+            return blocked(`Sandbox: ${event.toolName} has no verified task execution adapter. Use a guarded file tool or confined bash command.`, "tool-admission");
         } catch (error) {
-            return { block: true, reason: error instanceof Error ? error.message : String(error) };
+            return blocked(error instanceof Error ? error.message : String(error), "sandbox-backend");
         }
     });
+    if (options.diagnostics) pi.on("tool_result", (event, ctx) => {
+        if (event.isError) return;
+        try { options.diagnostics?.observe({ tool: event.toolName, operation: { input: event.input, cwd: ctx?.cwd ?? currentCwd }, resource: "unknown",
+            basis: "policy-refusal", outcome: "succeeded" }); } catch { /* Observation is nonfatal. */ }
+    });
     return { register, bash, assertInstalled(names: readonly string[]) {
         const inventory = pi.getAllTools();
         for (const name of names) {

package/task-guard.ts

@@ -6,6 +6,7 @@ import { parseTaskPolicy, type TaskPolicy } from "./task-policy.ts";
 import { SANDBOX_POLICY_CHANNEL, SANDBOX_POLICY_REQUEST_CHANNEL } from "./permission-policy.ts";
 import { failureDispositionTool, intentBashDefinition } from "./child-incidents.ts";
 import { DISPOSITION_TOOL } from "./incident-model.ts";
+import { SandboxDiagnostics, diagnosticPackageVersion } from "./shared-sandbox-diagnostics.ts";
 
 const TRUSTED_INLINE_SOURCE = "<inline:task-sandbox>";
 
@@ -42,7 +43,19 @@ export default function taskGuard(pi: ExtensionAPI, input: unknown, fatal: (erro
     const controller = Object.freeze({ requireLaunchPlan: () => plan });
     let shellPath: string | undefined;
     let currentCwd = process.cwd();
+    let diagnosticsWarned = false;
+    const diagnostics = new SandboxDiagnostics({ context: "worker", agentDir: () => policy.agentDir,
+        relay: (report) => { process.stdout.write(`${JSON.stringify(report)}\n`); },
+        version: diagnosticPackageVersion(new URL("./package.json", import.meta.url)),
+        policy: () => ({ permissions: policy.permissions, denyWrite: policy.denyWrite, root: policy.root }),
+        backend: () => support.backend,
+        onError: () => {
+            if (!diagnosticsWarned) process.stderr.write("Sandbox diagnostics collection gap; enforcement unchanged.\n");
+            diagnosticsWarned = true;
+        },
+    });
     const boundary = installTaskTools(pi, { controller, cwd: process.cwd(), shellPath: () => shellPath,
+        diagnostics,
         trustedSources: [TRUSTED_INLINE_SOURCE],
         // Structured command intent (#315): validated before the confined command runs.
         bashDefinition: (cwd, operations) => intentBashDefinition(cwd, operations) as any,