@wrongstack/core 0.296.4 → 0.298.0

package/dist/coordination/mailbox-project-server.js

@@ -1,10 +1,11 @@
 #!/usr/bin/env node
 
 // src/coordination/mailbox-project-server.ts
-import * as fs4 from "node:fs";
+import { randomBytes as randomBytes2 } from "node:crypto";
+import * as fs5 from "node:fs";
 import * as fsPromises from "node:fs/promises";
 import * as net from "node:net";
-import * as path4 from "node:path";
+import * as path7 from "node:path";
 
 // src/kernel/events.ts
 var MAX_WILDCARDS = 500;
@@ -250,12 +251,899 @@ function makePatternMatcher(pattern) {
   return (e) => e === pattern;
 }
 
+// src/utils/atomic-write.ts
+import {
+  createPersistencePrimitives
+} from "@wrongstack/persistence";
+
+// src/types/errors.ts
+var ERROR_CODES = {
+  // Provider
+  PROVIDER_RATE_LIMITED: "PROVIDER_RATE_LIMITED",
+  PROVIDER_AUTH_FAILED: "PROVIDER_AUTH_FAILED",
+  PROVIDER_OVERLOADED: "PROVIDER_OVERLOADED",
+  PROVIDER_INVALID_REQUEST: "PROVIDER_INVALID_REQUEST",
+  PROVIDER_SERVER_ERROR: "PROVIDER_SERVER_ERROR",
+  PROVIDER_NETWORK_ERROR: "PROVIDER_NETWORK_ERROR",
+  PROVIDER_CONTEXT_OVERFLOW: "PROVIDER_CONTEXT_OVERFLOW",
+  // Tool
+  TOOL_NOT_FOUND: "TOOL_NOT_FOUND",
+  TOOL_PERMISSION_DENIED: "TOOL_PERMISSION_DENIED",
+  TOOL_EXECUTION_FAILED: "TOOL_EXECUTION_FAILED",
+  TOOL_TIMEOUT: "TOOL_TIMEOUT",
+  TOOL_INPUT_INVALID: "TOOL_INPUT_INVALID",
+  // Config
+  CONFIG_INVALID: "CONFIG_INVALID",
+  CONFIG_NOT_FOUND: "CONFIG_NOT_FOUND",
+  CONFIG_PARSE_FAILED: "CONFIG_PARSE_FAILED",
+  CONFIG_MIGRATION_NEEDED: "CONFIG_MIGRATION_NEEDED",
+  // Plugin
+  PLUGIN_LOAD_FAILED: "PLUGIN_LOAD_FAILED",
+  PLUGIN_API_MISMATCH: "PLUGIN_API_MISMATCH",
+  PLUGIN_MISSING_DEPENDENCY: "PLUGIN_MISSING_DEPENDENCY",
+  // Agent
+  AGENT_ITERATION_LIMIT: "AGENT_ITERATION_LIMIT",
+  AGENT_CONTEXT_OVERFLOW: "AGENT_CONTEXT_OVERFLOW",
+  AGENT_ABORTED: "AGENT_ABORTED",
+  AGENT_RUN_FAILED: "AGENT_RUN_FAILED",
+  // Session
+  SESSION_NOT_FOUND: "SESSION_NOT_FOUND",
+  SESSION_CORRUPTED: "SESSION_CORRUPTED",
+  SESSION_WRITE_FAILED: "SESSION_WRITE_FAILED",
+  // Container / Registry
+  CONTAINER_TOKEN_ALREADY_BOUND: "CONTAINER_TOKEN_ALREADY_BOUND",
+  CONTAINER_TOKEN_NOT_BOUND: "CONTAINER_TOKEN_NOT_BOUND",
+  CONTAINER_CIRCULAR_DEPENDENCY: "CONTAINER_CIRCULAR_DEPENDENCY",
+  REGISTRY_DUPLICATE: "REGISTRY_DUPLICATE",
+  REGISTRY_NOT_FOUND: "REGISTRY_NOT_FOUND",
+  REGISTRY_INVALID: "REGISTRY_INVALID",
+  // File system
+  FS_READ_FAILED: "FS_READ_FAILED",
+  FS_WRITE_FAILED: "FS_WRITE_FAILED",
+  FS_MKDIR_FAILED: "FS_MKDIR_FAILED",
+  FS_DELETE_FAILED: "FS_DELETE_FAILED",
+  FS_ATOMIC_WRITE_FAILED: "FS_ATOMIC_WRITE_FAILED",
+  // SDD (Spec-Driven Development)
+  SDD_VALIDATION_FAILED: "SDD_VALIDATION_FAILED",
+  SDD_PARSE_FAILED: "SDD_PARSE_FAILED",
+  SDD_INVALID_STATE: "SDD_INVALID_STATE",
+  SDD_NOT_READY: "SDD_NOT_READY",
+  // General
+  VALIDATION_ERROR: "VALIDATION_ERROR",
+  PARSE_FAILED: "PARSE_FAILED",
+  UNKNOWN: "UNKNOWN"
+};
+var WrongStackError = class extends Error {
+  code;
+  subsystem;
+  severity;
+  recoverable;
+  context;
+  constructor(opts) {
+    super(opts.message, { cause: opts.cause });
+    this.name = "WrongStackError";
+    this.code = opts.code;
+    this.subsystem = opts.subsystem;
+    this.severity = opts.severity ?? "error";
+    this.recoverable = opts.recoverable ?? false;
+    this.context = opts.context;
+  }
+  /**
+   * Render a one-line user-facing description.
+   * Subclasses should override for domain-specific formatting.
+   */
+  describe() {
+    const ctx = this.context ? ` ${formatContext(this.context)}` : "";
+    return `${this.code}: ${this.message}${ctx}`;
+  }
+};
+function formatContext(ctx) {
+  const parts = Object.entries(ctx).filter(([, v]) => v !== void 0).slice(0, 3).map(([k, v]) => `${k}=${String(v)}`);
+  return parts.length > 0 ? `[${parts.join(" ")}]` : "";
+}
+var FsError = class extends WrongStackError {
+  path;
+  constructor(opts) {
+    super({
+      message: opts.message,
+      code: opts.code,
+      subsystem: "fs",
+      severity: "error",
+      recoverable: opts.code !== ERROR_CODES.FS_READ_FAILED,
+      context: { path: opts.path, ...opts.context },
+      cause: opts.cause
+    });
+    this.name = "FsError";
+    this.path = opts.path;
+  }
+};
+
+// src/utils/atomic-write.ts
+var primitives = createPersistencePrimitives({
+  createLockTimeoutError: ({ targetPath, timeoutMs }) => new FsError({
+    message: `Timed out waiting for file lock: ${targetPath}`,
+    code: "FS_ATOMIC_WRITE_FAILED",
+    path: targetPath,
+    context: { timeoutMs }
+  })
+});
+var atomicWrite = primitives.atomicWrite;
+var atomicReplaceWithWriter = primitives.atomicReplaceWithWriter;
+var ensureDir = primitives.ensureDir;
+var withFileLock = primitives.withFileLock;
+
+// src/utils/heap-watchdog.ts
+import * as fs from "node:fs";
+import * as fsp2 from "node:fs/promises";
+import * as path3 from "node:path";
+import { PerformanceObserver, constants as performanceConstants } from "node:perf_hooks";
+import * as v8 from "node:v8";
+
+// src/utils/memory-flight-recorder.ts
+import * as fsp from "node:fs/promises";
+import * as path2 from "node:path";
+
+// src/utils/continuous-memory-profiler.ts
+import { Session } from "node:inspector/promises";
+var DEFAULT_SAMPLE_INTERVAL_BYTES = 512 * 1024;
+var DEFAULT_STACK_DEPTH = 64;
+var MAX_SUMMARY_STACKS = 20;
+var MAX_FRAMES_PER_STACK = 12;
+function errorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+function numeric(value) {
+  if (typeof value === "bigint") return Number(value);
+  return typeof value === "number" && Number.isFinite(value) ? value : 0;
+}
+function summarizePprof(profile) {
+  const strings = profile.stringTable.strings;
+  const functions = new Map(profile.function.map((entry) => [numeric(entry.id), entry]));
+  const locations = new Map(profile.location.map((entry) => [numeric(entry.id), entry]));
+  const stacks = /* @__PURE__ */ new Map();
+  let sampledBytes = 0;
+  let sampledObjects = 0;
+  for (const sample of profile.sample) {
+    const objects = numeric(sample.value[0]);
+    const bytes = numeric(sample.value[1]);
+    sampledObjects += objects;
+    sampledBytes += bytes;
+    const frames = sample.locationId.slice(0, MAX_FRAMES_PER_STACK).flatMap((locationId) => {
+      const location = locations.get(numeric(locationId));
+      const line = location?.line[0];
+      const fn = line ? functions.get(numeric(line.functionId)) : void 0;
+      if (!fn) return [];
+      const name = strings[numeric(fn.name)] || "(anonymous)";
+      const filename = strings[numeric(fn.filename)] || "";
+      const lineNumber = numeric(line?.line);
+      return [filename ? `${name} (${filename}${lineNumber > 0 ? `:${lineNumber}` : ""})` : name];
+    });
+    if (frames.length === 0) frames.push("(unknown)");
+    const key = frames.join("\n");
+    const existing = stacks.get(key);
+    if (existing) {
+      existing.bytes += bytes;
+      existing.objects += objects;
+    } else {
+      stacks.set(key, { bytes, objects, frames });
+    }
+  }
+  return {
+    sampledBytes,
+    sampledObjects,
+    sampleCount: profile.sample.length,
+    topStacks: [...stacks.values()].sort((left, right) => right.bytes - left.bytes).slice(0, MAX_SUMMARY_STACKS)
+  };
+}
+async function startDatadogProfiler() {
+  const pprof = await import("@datadog/pprof");
+  pprof.heap.start(DEFAULT_SAMPLE_INTERVAL_BYTES, DEFAULT_STACK_DEPTH);
+  let stopped = false;
+  return {
+    backend: "datadog-pprof",
+    capture: async () => {
+      if (stopped) throw new Error("Continuous memory profiler is stopped");
+      const profile = pprof.heap.profile();
+      return {
+        backend: "datadog-pprof",
+        data: await pprof.encode(profile),
+        extension: ".pb.gz",
+        summary: summarizePprof(profile)
+      };
+    },
+    stop: async () => {
+      if (stopped) return;
+      stopped = true;
+      pprof.heap.stop();
+    }
+  };
+}
+async function startInspectorProfiler() {
+  const session = new Session();
+  session.connect();
+  try {
+    await session.post("HeapProfiler.enable");
+    await session.post("HeapProfiler.startSampling", {
+      samplingInterval: DEFAULT_SAMPLE_INTERVAL_BYTES,
+      includeObjectsCollectedByMajorGC: false,
+      includeObjectsCollectedByMinorGC: false
+    });
+  } catch (error) {
+    try {
+      session.disconnect();
+    } catch {
+    }
+    throw error;
+  }
+  let stopped = false;
+  return {
+    backend: "node-inspector",
+    capture: async () => {
+      if (stopped) throw new Error("Continuous memory profiler is stopped");
+      const result = await session.post("HeapProfiler.stopSampling");
+      await session.post("HeapProfiler.startSampling", {
+        samplingInterval: DEFAULT_SAMPLE_INTERVAL_BYTES,
+        includeObjectsCollectedByMajorGC: false,
+        includeObjectsCollectedByMinorGC: false
+      });
+      return {
+        backend: "node-inspector",
+        data: JSON.stringify(result.profile),
+        extension: ".heapprofile"
+      };
+    },
+    stop: async () => {
+      if (stopped) return;
+      stopped = true;
+      try {
+        await session.post("HeapProfiler.disable");
+      } catch {
+      }
+      try {
+        session.disconnect();
+      } catch {
+      }
+    }
+  };
+}
+async function startContinuousMemoryProfiler() {
+  try {
+    return { profiler: await startDatadogProfiler() };
+  } catch (error) {
+    const fallbackReason = errorMessage(error);
+    return {
+      profiler: await startInspectorProfiler(),
+      fallbackReason
+    };
+  }
+}
+
+// src/utils/wstack-paths.ts
+import * as os from "node:os";
+import * as path from "node:path";
+function wstackGlobalRoot() {
+  const fromEnv = process.env["WRONGSTACK_HOME"];
+  if (fromEnv && fromEnv.trim().length > 0) return path.resolve(fromEnv);
+  return path.join(os.homedir(), ".wrongstack");
+}
+
+// src/utils/memory-flight-recorder.ts
+var MB = 1024 * 1024;
+var HOUR_MS = 60 * 60 * 1e3;
+var DEFAULT_WINDOW_MS = 5 * 60 * 1e3;
+var DEFAULT_MINIMUM_WINDOW_MS = 2 * 60 * 1e3;
+var DEFAULT_COOLDOWN_MS = 15 * 60 * 1e3;
+var DEFAULT_CONTINUOUS_CAPTURE_MS = 5 * 60 * 1e3;
+var MAX_OBSERVATIONS = 24;
+var MAX_CAPTURE_SESSIONS = 12;
+var MAX_CAPTURES_PER_SESSION = 6;
+var SESSION_MAX_AGE_MS = 7 * 24 * HOUR_MS;
+function timestampSlug(date = /* @__PURE__ */ new Date()) {
+  return date.toISOString().replaceAll(":", "").replaceAll(".", "-");
+}
+async function pruneCaptureFiles(artifactDir) {
+  const entries = await fsp.readdir(artifactDir, { withFileTypes: true });
+  const captures = entries.filter(
+    (entry) => entry.isFile() && entry.name.startsWith("event-") && entry.name.endsWith(".json")
+  ).map((entry) => entry.name).sort();
+  const remove = captures.slice(0, Math.max(0, captures.length - MAX_CAPTURES_PER_SESSION));
+  await Promise.all(
+    remove.flatMap((eventName) => {
+      const stem = eventName.slice("event-".length, -".json".length);
+      return [
+        fsp.rm(path2.join(artifactDir, eventName), { force: true }),
+        fsp.rm(path2.join(artifactDir, `allocations-${stem}.heapprofile`), { force: true }),
+        fsp.rm(path2.join(artifactDir, `allocations-${stem}.pb.gz`), { force: true })
+      ];
+    })
+  );
+}
+async function pruneOldSessions(root, currentDir) {
+  const entries = await fsp.readdir(root, { withFileTypes: true });
+  const sessions = await Promise.all(
+    entries.filter((entry) => entry.isDirectory() && entry.name !== path2.basename(currentDir)).map(async (entry) => {
+      const fullPath = path2.join(root, entry.name);
+      const stat2 = await fsp.stat(fullPath);
+      return { fullPath, mtimeMs: stat2.mtimeMs };
+    })
+  );
+  sessions.sort((a, b) => b.mtimeMs - a.mtimeMs);
+  const now = Date.now();
+  await Promise.all(
+    sessions.filter(
+      (session, index) => now - session.mtimeMs > SESSION_MAX_AGE_MS || index >= MAX_CAPTURE_SESSIONS && now - session.mtimeMs > 24 * HOUR_MS
+    ).map((session) => fsp.rm(session.fullPath, { recursive: true, force: true }))
+  );
+}
+var ContinuousMemoryCaptureWriter = class {
+  artifactDir;
+  root;
+  ready;
+  profiler;
+  profilerBackend = "initializing";
+  fallbackReason;
+  startError;
+  lastSummary;
+  stopped = false;
+  constructor(root) {
+    this.root = root;
+    this.artifactDir = path2.join(root, `${timestampSlug()}-pid-${process.pid}`);
+    this.ready = this.start().catch((error) => {
+      this.startError = error instanceof Error ? error.message : String(error);
+      this.profilerBackend = "unavailable";
+    });
+  }
+  async start() {
+    const started = await startContinuousMemoryProfiler();
+    this.profiler = started.profiler;
+    this.profilerBackend = started.profiler.backend;
+    this.fallbackReason = started.fallbackReason;
+  }
+  diagnostics() {
+    return {
+      memoryProfilerBackend: this.profilerBackend,
+      ...this.fallbackReason ? { memoryProfilerFallbackReason: this.fallbackReason } : {},
+      ...this.startError ? { memoryProfilerStartError: this.startError } : {},
+      ...this.lastSummary ? {
+        memoryProfileSampledBytes: this.lastSummary.sampledBytes,
+        memoryProfileSampledObjects: this.lastSummary.sampledObjects,
+        memoryProfileSampleCount: this.lastSummary.sampleCount,
+        memoryProfileTopStack: this.lastSummary.topStack,
+        memoryProfileTopStackBytes: this.lastSummary.topStackBytes
+      } : {}
+    };
+  }
+  async capture(event) {
+    await this.ready;
+    if (this.stopped) return;
+    let profile;
+    let captureError = this.startError;
+    if (!captureError && this.profiler) {
+      try {
+        profile = await this.profiler.capture();
+        const top = profile.summary?.topStacks[0];
+        if (profile.summary) {
+          this.lastSummary = {
+            sampledBytes: profile.summary.sampledBytes,
+            sampledObjects: profile.summary.sampledObjects,
+            sampleCount: profile.summary.sampleCount,
+            topStack: top?.frames.join(" <- "),
+            topStackBytes: top?.bytes
+          };
+        }
+      } catch (error) {
+        captureError = error instanceof Error ? error.message : String(error);
+      }
+    }
+    await fsp.mkdir(this.artifactDir, { recursive: true });
+    const stem = `${timestampSlug(new Date(event.capturedAt))}-${event.reason}`;
+    await fsp.writeFile(
+      path2.join(this.artifactDir, `event-${stem}.json`),
+      `${JSON.stringify(
+        {
+          ...event,
+          profilerBackend: profile?.backend ?? this.profilerBackend,
+          ...profile?.summary ? { allocationSummary: profile.summary } : {},
+          ...this.fallbackReason ? { profilerFallbackReason: this.fallbackReason } : {},
+          ...captureError ? { captureError } : {}
+        },
+        null,
+        2
+      )}
+`,
+      "utf8"
+    );
+    if (profile) {
+      await fsp.writeFile(
+        path2.join(this.artifactDir, `allocations-${stem}${profile.extension}`),
+        profile.data
+      );
+    }
+    await Promise.all([
+      pruneCaptureFiles(this.artifactDir),
+      fsp.mkdir(this.root, { recursive: true }).then(() => pruneOldSessions(this.root, this.artifactDir))
+    ]);
+  }
+  async stop() {
+    if (this.stopped) return;
+    this.stopped = true;
+    await this.ready;
+    await this.profiler?.stop();
+  }
+};
+function disabledWriter(artifactDir) {
+  return {
+    artifactDir,
+    capture: async () => void 0,
+    stop: async () => void 0
+  };
+}
+function createMemoryFlightRecorder(options = {}) {
+  const now = options.now ?? Date.now;
+  const startedAt2 = now();
+  const root = options.diagnosticsRoot ?? path2.join(wstackGlobalRoot(), "diagnostics", "memory");
+  const enabled = options.enabled ?? (process.env["WRONGSTACK_MEMORY_FLIGHT_RECORDER"] !== "0" && process.env["NODE_ENV"] !== "test");
+  const writer = options.captureWriter ?? (enabled ? new ContinuousMemoryCaptureWriter(root) : disabledWriter(path2.join(root, `${timestampSlug()}-pid-${process.pid}`)));
+  const observations = [];
+  const windowMs = options.windowMs ?? DEFAULT_WINDOW_MS;
+  const minimumWindowMs = options.minimumWindowMs ?? DEFAULT_MINIMUM_WINDOW_MS;
+  const cooldownMs = options.cooldownMs ?? DEFAULT_COOLDOWN_MS;
+  const continuousCaptureMs = options.continuousCaptureMs ?? DEFAULT_CONTINUOUS_CAPTURE_MS;
+  const warmupMs = options.warmupMs ?? 6e4;
+  let lastSignalCaptureAt = Number.NEGATIVE_INFINITY;
+  let lastContinuousCaptureAt = startedAt2;
+  let captureInFlight = false;
+  let capturePromise;
+  const observe = (sample, stats) => {
+    const at = now();
+    const postGcHeapUsed = typeof stats["postGcHeapUsed"] === "number" ? stats["postGcHeapUsed"] : 0;
+    const postMajorGcHeapUsed = typeof stats["postMajorGcHeapUsed"] === "number" ? stats["postMajorGcHeapUsed"] : 0;
+    const lastGcAgoMs = typeof stats["lastGcAgoMs"] === "number" ? stats["lastGcAgoMs"] : -1;
+    const lastMajorGcAgoMs = typeof stats["lastMajorGcAgoMs"] === "number" ? stats["lastMajorGcAgoMs"] : -1;
+    const retainedHeapUsed = postMajorGcHeapUsed > 0 && lastMajorGcAgoMs >= 0 && lastMajorGcAgoMs <= windowMs ? postMajorGcHeapUsed : postGcHeapUsed > 0 && lastGcAgoMs >= 0 && lastGcAgoMs <= minimumWindowMs ? postGcHeapUsed : sample.heapUsed;
+    observations.push({
+      at,
+      heapUsed: retainedHeapUsed,
+      rss: sample.rss,
+      nativeResidual: sample.nativeResidual ?? 0
+    });
+    while (observations.length > MAX_OBSERVATIONS || observations.length > 1 && at - (observations[0]?.at ?? at) > windowMs) {
+      observations.shift();
+    }
+    const first = observations[0] ?? observations.at(-1);
+    const elapsedMs = first ? Math.max(0, at - first.at) : 0;
+    const heapGrowthBytes = first ? retainedHeapUsed - first.heapUsed : 0;
+    const rssGrowthBytes = first ? sample.rss - first.rss : 0;
+    const nativeGrowthBytes = first ? (sample.nativeResidual ?? 0) - first.nativeResidual : 0;
+    const heapGrowthBytesPerHour = elapsedMs > 0 ? Math.round(heapGrowthBytes / elapsedMs * HOUR_MS) : 0;
+    const rssGrowthBytesPerHour = elapsedMs > 0 ? Math.round(rssGrowthBytes / elapsedMs * HOUR_MS) : 0;
+    const nativeGrowthBytesPerHour = elapsedMs > 0 ? Math.round(nativeGrowthBytes / elapsedMs * HOUR_MS) : 0;
+    let signal = "stable";
+    if ((sample.detachedContexts ?? 0) > 0) signal = "detached-contexts";
+    else if (heapGrowthBytes >= 32 * MB && heapGrowthBytesPerHour > 0) signal = "js-retention";
+    else if (nativeGrowthBytes >= 64 * MB && nativeGrowthBytesPerHour > 0) signal = "native-rss";
+    const diagnosis = {
+      memorySignal: signal,
+      memoryWindowMs: elapsedMs,
+      retainedHeapUsed,
+      transientHeapBytes: Math.max(0, sample.heapUsed - retainedHeapUsed),
+      heapGrowthBytes,
+      rssGrowthBytes,
+      nativeGrowthBytes,
+      heapGrowthBytesPerHour,
+      rssGrowthBytesPerHour,
+      nativeGrowthBytesPerHour,
+      memoryArtifactDir: writer.artifactDir,
+      ...writer.diagnostics?.() ?? {}
+    };
+    let reason;
+    if (at - startedAt2 >= warmupMs) {
+      if ((sample.detachedContexts ?? 0) > 0) reason = "detached-contexts";
+      else if (sample.load >= 0.45) reason = "heap-load";
+      else if (sample.heapUsed >= (options.absoluteHeapBytes ?? 768 * MB)) {
+        reason = "absolute-heap";
+      } else if (elapsedMs >= minimumWindowMs && heapGrowthBytes >= (options.heapGrowthBytes ?? 32 * MB) && heapGrowthBytesPerHour >= (options.heapGrowthBytesPerHour ?? 192 * MB)) {
+        reason = "heap-growth";
+      } else if (elapsedMs >= minimumWindowMs && nativeGrowthBytes >= (options.nativeGrowthBytes ?? 128 * MB) && nativeGrowthBytesPerHour >= (options.nativeGrowthBytesPerHour ?? 256 * MB)) {
+        reason = "native-rss-growth";
+      }
+    }
+    const signalCaptureDue = reason !== void 0 && at - lastSignalCaptureAt >= cooldownMs;
+    const intervalCaptureDue = at - lastContinuousCaptureAt >= continuousCaptureMs;
+    const captureReason = signalCaptureDue ? reason : intervalCaptureDue ? "interval" : void 0;
+    if (enabled && captureReason && !captureInFlight) {
+      if (captureReason !== "interval") lastSignalCaptureAt = at;
+      lastContinuousCaptureAt = at;
+      captureInFlight = true;
+      diagnosis["memoryCaptureReason"] = captureReason;
+      capturePromise = writer.capture({
+        reason: captureReason,
+        capturedAt: new Date(at).toISOString(),
+        pid: process.pid,
+        sample,
+        stats,
+        diagnosis: { ...diagnosis },
+        observations: observations.map((observation) => ({ ...observation }))
+      }).catch(() => {
+      }).finally(() => {
+        captureInFlight = false;
+        capturePromise = void 0;
+      });
+    }
+    return diagnosis;
+  };
+  return {
+    artifactDir: writer.artifactDir,
+    observe,
+    stop: async () => {
+      await capturePromise;
+      await writer.stop();
+    }
+  };
+}
+
+// src/utils/heap-watchdog.ts
+var MB2 = 1024 * 1024;
+function defaultHeapLogPath() {
+  const override = process.env["WRONGSTACK_HEAP_LOG_PATH"]?.trim();
+  if (override) return path3.resolve(override);
+  return path3.join(wstackGlobalRoot(), "logs", "heap.jsonl");
+}
+function takeHeapSample() {
+  const m = process.memoryUsage();
+  const heap = v8.getHeapStatistics();
+  const spaces = v8.getHeapSpaceStatistics();
+  const spaceUsed = (name) => spaces.find((space) => space.space_name === name)?.space_used_size ?? 0;
+  const limit = heap.heap_size_limit || 0;
+  let activeResources = 0;
+  let activeResourceTypes = "";
+  try {
+    const resources = process.getActiveResourcesInfo?.() ?? [];
+    activeResources = resources.length;
+    const counts = /* @__PURE__ */ new Map();
+    for (const resource of resources) counts.set(resource, (counts.get(resource) ?? 0) + 1);
+    activeResourceTypes = [...counts].sort(([left], [right]) => left.localeCompare(right)).map(([resource, count]) => `${resource}=${count}`).join(",");
+  } catch {
+  }
+  return {
+    ts: (/* @__PURE__ */ new Date()).toISOString(),
+    rss: m.rss,
+    heapUsed: m.heapUsed,
+    heapTotal: m.heapTotal,
+    external: m.external,
+    arrayBuffers: m.arrayBuffers,
+    nativeResidual: Math.max(0, m.rss - m.heapTotal - m.external),
+    oldSpaceUsed: spaceUsed("old_space"),
+    newSpaceUsed: spaceUsed("new_space"),
+    largeObjectSpaceUsed: spaceUsed("large_object_space"),
+    codeSpaceUsed: spaceUsed("code_space"),
+    mallocedMemory: heap.malloced_memory,
+    peakMallocedMemory: heap.peak_malloced_memory,
+    nativeContexts: heap.number_of_native_contexts,
+    detachedContexts: heap.number_of_detached_contexts,
+    activeResources,
+    activeResourceTypes,
+    heapLimit: limit,
+    load: limit > 0 ? m.heapUsed / limit : 0
+  };
+}
+function startHeapWatchdog(opts = {}) {
+  const profileMode = process.env["WRONGSTACK_MEMORY_PROFILE"] === "1";
+  const sampleEveryMs = opts.sampleEveryMs ?? (profileMode ? 5e3 : 3e4);
+  const logEveryMs = opts.logEveryMs ?? (profileMode ? 5e3 : 6e4);
+  const logPath = opts.logPath ?? defaultHeapLogPath();
+  const warnAt = opts.warnAt ?? 0.6;
+  const criticalAt = opts.criticalAt ?? 0.85;
+  const REARM_MARGIN = 0.05;
+  let warnArmed = true;
+  let criticalArmed = true;
+  let lastLogAt = 0;
+  let writeInFlight = false;
+  let pendingLine;
+  let drainPromise;
+  let stopped = false;
+  let dirReady = false;
+  const flightRecorder = createMemoryFlightRecorder();
+  let gcMajorCount = 0;
+  let gcMinorCount = 0;
+  let gcIncrementalCount = 0;
+  let gcWeakCallbackCount = 0;
+  let gcDurationMs = 0;
+  let postGcHeapUsed = 0;
+  let postMajorGcHeapUsed = 0;
+  let lastGcAt = 0;
+  let lastMajorGcAt = 0;
+  const gcObserver = new PerformanceObserver((list) => {
+    for (const entry of list.getEntries()) {
+      const kind = entry.detail?.kind ?? 0;
+      if ((kind & performanceConstants.NODE_PERFORMANCE_GC_MAJOR) !== 0) gcMajorCount++;
+      if ((kind & performanceConstants.NODE_PERFORMANCE_GC_MINOR) !== 0) gcMinorCount++;
+      if ((kind & performanceConstants.NODE_PERFORMANCE_GC_INCREMENTAL) !== 0) {
+        gcIncrementalCount++;
+      }
+      if ((kind & performanceConstants.NODE_PERFORMANCE_GC_WEAKCB) !== 0) gcWeakCallbackCount++;
+      gcDurationMs += entry.duration;
+      postGcHeapUsed = process.memoryUsage().heapUsed;
+      if ((kind & performanceConstants.NODE_PERFORMANCE_GC_MAJOR) !== 0) {
+        postMajorGcHeapUsed = postGcHeapUsed;
+        lastMajorGcAt = Date.now();
+      }
+      lastGcAt = Date.now();
+    }
+  });
+  try {
+    gcObserver.observe({ entryTypes: ["gc"] });
+  } catch {
+  }
+  const collectRuntimeStats = () => ({
+    gcMajorCount,
+    gcMinorCount,
+    gcIncrementalCount,
+    gcWeakCallbackCount,
+    gcDurationMs: Math.round(gcDurationMs),
+    postGcHeapUsed,
+    postMajorGcHeapUsed,
+    lastGcAgoMs: lastGcAt > 0 ? Date.now() - lastGcAt : -1,
+    lastMajorGcAgoMs: lastMajorGcAt > 0 ? Date.now() - lastMajorGcAt : -1
+  });
+  const writeDiagnosticLine = opts.writeDiagnosticLine ?? (async (targetPath, line) => {
+    if (!dirReady) {
+      await fsp2.mkdir(path3.dirname(targetPath), { recursive: true });
+      dirReady = true;
+    }
+    await fsp2.appendFile(targetPath, `${line}
+`, { encoding: "utf8", mode: 384 });
+  });
+  const drainWrites = async (firstLine) => {
+    let line = firstLine;
+    while (line !== void 0) {
+      try {
+        await writeDiagnosticLine(logPath, line);
+      } catch {
+      }
+      line = pendingLine;
+      pendingLine = void 0;
+    }
+    writeInFlight = false;
+  };
+  const append = (line) => {
+    if (stopped) return;
+    if (writeInFlight) {
+      pendingLine = line;
+      return;
+    }
+    writeInFlight = true;
+    drainPromise = drainWrites(line);
+  };
+  const appendTerminalSample = (event, error, origin) => {
+    if (stopped) return;
+    let extras = {};
+    try {
+      extras = opts.collectStats?.() ?? {};
+    } catch {
+    }
+    try {
+      const sample = takeHeapSample();
+      const runtimeStats = collectRuntimeStats();
+      fs.mkdirSync(path3.dirname(logPath), { recursive: true });
+      fs.appendFileSync(
+        logPath,
+        `${JSON.stringify({
+          ...extras,
+          ...runtimeStats,
+          event,
+          ...origin ? { crashOrigin: origin } : {},
+          ...error instanceof Error ? { errorName: error.name, errorMessage: error.message.slice(0, 1e3) } : {},
+          pid: process.pid,
+          ...sample,
+          exitCode: process.exitCode
+        })}
+`,
+        "utf8"
+      );
+    } catch {
+    }
+  };
+  const onUncaughtException = (error, origin) => {
+    appendTerminalSample("memory.flight_recorder.crash", error, origin);
+  };
+  const onProcessExit = () => {
+    appendTerminalSample("memory.flight_recorder.exit");
+  };
+  process.on("uncaughtExceptionMonitor", onUncaughtException);
+  process.on("exit", onProcessExit);
+  const tick = () => {
+    let userTimings = 0;
+    try {
+      userTimings = performance.getEntriesByType("mark").length + performance.getEntriesByType("measure").length;
+      if (userTimings > 0) {
+        performance.clearMarks();
+        performance.clearMeasures();
+      }
+    } catch {
+    }
+    const s = takeHeapSample();
+    let extras = {};
+    try {
+      extras = opts.collectStats?.() ?? {};
+    } catch {
+    }
+    const runtimeStats = collectRuntimeStats();
+    const diagnosticStats = { ...extras, ...runtimeStats };
+    const memoryDiagnosis = flightRecorder.observe(s, diagnosticStats);
+    if (s.load >= criticalAt && criticalArmed) {
+      criticalArmed = false;
+      warnArmed = false;
+      opts.onWarn?.(
+        "critical",
+        `Heap critical: ${Math.round(s.heapUsed / MB2)} MB of ~${Math.round(s.heapLimit / MB2)} MB V8 limit (${Math.round(s.load * 100)}%). An out-of-memory crash is likely soon \u2014 finish/checkpoint work and restart the session. Diagnostics: ${logPath}`,
+        s
+      );
+    } else if (s.load >= warnAt && warnArmed) {
+      warnArmed = false;
+      opts.onWarn?.(
+        "warn",
+        `Heap high: ${Math.round(s.heapUsed / MB2)} MB of ~${Math.round(s.heapLimit / MB2)} MB V8 limit (${Math.round(s.load * 100)}%). Memory diagnostics are being recorded to ${logPath}`,
+        s
+      );
+    }
+    if (!warnArmed && s.load < warnAt - REARM_MARGIN) warnArmed = true;
+    if (!criticalArmed && s.load < criticalAt - REARM_MARGIN) criticalArmed = true;
+    const due = Date.now() - lastLogAt >= logEveryMs;
+    const crossed = s.load >= warnAt;
+    const captured = typeof memoryDiagnosis["memoryCaptureReason"] === "string";
+    if (due || crossed || captured) {
+      lastLogAt = Date.now();
+      append(
+        JSON.stringify({
+          ...extras,
+          ...runtimeStats,
+          ...memoryDiagnosis,
+          pid: process.pid,
+          ...s,
+          userTimings
+        })
+      );
+    }
+  };
+  const timer = setInterval(tick, sampleEveryMs);
+  timer.unref?.();
+  tick();
+  return async () => {
+    stopped = true;
+    clearInterval(timer);
+    gcObserver.disconnect();
+    process.removeListener("uncaughtExceptionMonitor", onUncaughtException);
+    process.removeListener("exit", onProcessExit);
+    await drainPromise;
+    await flightRecorder.stop();
+  };
+}
+var sharedContributors = /* @__PURE__ */ new Map();
+var nextSharedContributorId = 1;
+var sharedSamplerActive = false;
+var stopSharedSampler;
+function collectSharedStats() {
+  const merged = {};
+  for (const contributor of sharedContributors.values()) {
+    try {
+      Object.assign(merged, contributor.collectStats?.() ?? {});
+    } catch {
+    }
+  }
+  return merged;
+}
+function warnSharedContributors(level, message, sample) {
+  for (const contributor of sharedContributors.values()) {
+    try {
+      contributor.onWarn?.(level, message, sample);
+    } catch {
+    }
+  }
+}
+function startSharedHeapWatchdog(opts = {}) {
+  if (process.env["NODE_ENV"] === "test" && !sharedSamplerActive && opts.logPath === void 0 && opts.writeDiagnosticLine === void 0) {
+    return async () => void 0;
+  }
+  const id = nextSharedContributorId++;
+  sharedContributors.set(id, {
+    collectStats: opts.collectStats,
+    onWarn: opts.onWarn
+  });
+  if (!sharedSamplerActive) {
+    sharedSamplerActive = true;
+    stopSharedSampler = startHeapWatchdog({
+      ...opts,
+      collectStats: collectSharedStats,
+      onWarn: warnSharedContributors
+    });
+  }
+  let stopped = false;
+  return async () => {
+    if (stopped) return;
+    stopped = true;
+    sharedContributors.delete(id);
+    if (sharedContributors.size > 0 || !sharedSamplerActive) return;
+    const stop2 = stopSharedSampler;
+    if (!stop2) return;
+    sharedSamplerActive = false;
+    stopSharedSampler = void 0;
+    await stop2();
+  };
+}
+
 // src/utils/perf-profile.ts
 var daemonDefaults = false;
 function useDaemonPerfDefaults() {
   daemonDefaults = true;
 }
 
+// src/coordination/mailbox-credential-store.ts
+import * as crypto from "node:crypto";
+var CREDENTIAL_STORE_FILE = "_mailbox_credentials.json";
+var MAX_CREDENTIAL_TTL = {
+  agent: 7 * 24 * 60 * 60 * 1e3,
+  // 7 days
+  operator: 24 * 60 * 60 * 1e3,
+  // 24 hours
+  service: 30 * 24 * 60 * 60 * 1e3
+  // 30 days
+};
+var ROTATION_OVERLAP_MS = 60 * 60 * 1e3;
+function createMailboxCredential(opts, now = Date.now()) {
+  const ttlMs = Math.min(opts.ttlMs, MAX_CREDENTIAL_TTL[opts.kind]);
+  const credentialId = crypto.randomUUID();
+  const secret = crypto.randomBytes(32).toString("hex");
+  const verifierKey = crypto.createHash("sha256").update(secret).digest();
+  const verifier = crypto.createHmac("sha256", verifierKey).update(credentialId).digest("hex");
+  return {
+    credential: {
+      credentialId,
+      verifier,
+      verifierAlgorithm: "hmac-sha256",
+      principalId: opts.principalId,
+      projectId: opts.projectId,
+      capabilities: opts.capabilities,
+      kind: opts.kind,
+      issuedAt: new Date(now).toISOString(),
+      expiresAt: new Date(now + ttlMs).toISOString(),
+      notBefore: opts.notBefore?.toISOString(),
+      status: "active",
+      statusChangedAt: new Date(now).toISOString(),
+      supersedes: opts.supersedes,
+      lastModifiedBy: opts.issuedBy
+    },
+    secret
+  };
+}
+function redactMailboxCredential(credential) {
+  const { verifier: _verifier, verifierAlgorithm: _algorithm, ...rest } = credential;
+  return rest;
+}
+function verifyMailboxCredential(credential, secret, now = Date.now()) {
+  if (credential === void 0) {
+    return { valid: false, reason: "credential not found" };
+  }
+  const rotationStillValid = credential.status === "rotated_out" && credential.rotationValidUntil !== void 0 && new Date(credential.rotationValidUntil).getTime() >= now;
+  if (credential.status !== "active" && !rotationStillValid) {
+    return { valid: false, reason: `credential is ${credential.status}`, credential };
+  }
+  if (new Date(credential.expiresAt).getTime() <= now) {
+    return { valid: false, reason: "credential expired", credential };
+  }
+  if (credential.notBefore !== void 0 && new Date(credential.notBefore).getTime() > now) {
+    return { valid: false, reason: "credential not yet valid", credential };
+  }
+  const verifierKey = crypto.createHash("sha256").update(secret).digest();
+  const expected = crypto.createHmac("sha256", verifierKey).update(credential.credentialId).digest("hex");
+  const actualBytes = Buffer.from(credential.verifier, "hex");
+  const expectedBytes = Buffer.from(expected, "hex");
+  if (actualBytes.length !== expectedBytes.length || !crypto.timingSafeEqual(actualBytes, expectedBytes)) {
+    return { valid: false, reason: "invalid secret" };
+  }
+  return { valid: true, credential };
+}
+
 // src/coordination/mailbox-events.ts
 var MailboxEventEmitter = class {
   listeners = /* @__PURE__ */ new Set();
@@ -284,10 +1172,10 @@ var MailboxEventEmitter = class {
 };
 
 // src/coordination/mailbox-project-server-endpoint.ts
-import { createHash } from "node:crypto";
-import * as fs from "node:fs";
-import * as os from "node:os";
-import * as path from "node:path";
+import { createHash as createHash2 } from "node:crypto";
+import * as fs2 from "node:fs";
+import * as os2 from "node:os";
+import * as path4 from "node:path";
 
 // src/utils/socket-path.ts
 import {
@@ -297,7 +1185,7 @@ import {
 } from "@wrongstack/persistence";
 
 // src/coordination/mailbox-project-server-protocol.ts
-var MAILBOX_PROJECT_SERVER_PROTOCOL_VERSION = 3;
+var MAILBOX_PROJECT_SERVER_PROTOCOL_VERSION = 4;
 var MAILBOX_PROJECT_SERVER_MAX_FRAME_CHARS = 16 * 1024 * 1024;
 var MAILBOX_SERVER_OPERATION_NAMES = {
   ping: true,
@@ -409,50 +1297,37 @@ function encodeMailboxProjectServerMessage(message) {
 // src/coordination/mailbox-project-server-endpoint.ts
 var MAILBOX_PROJECT_SERVER_METADATA_FILE = ".mailbox-server.json";
 function normalizeLocalPath(value) {
-  const resolved = path.resolve(value);
+  const resolved = path4.resolve(value);
   return process.platform === "win32" ? resolved.toLowerCase() : resolved;
 }
 function mailboxProjectServerKey(projectDir2) {
-  return createHash("sha256").update(normalizeLocalPath(projectDir2)).digest("hex").slice(0, 24);
+  return createHash2("sha256").update(normalizeLocalPath(projectDir2)).digest("hex").slice(0, 24);
 }
 function mailboxProjectServerEndpoint(projectDir2) {
   const key = mailboxProjectServerKey(projectDir2);
   if (process.platform === "win32") {
     return `\\\\.\\pipe\\wrongstack-mailbox-v${MAILBOX_PROJECT_SERVER_PROTOCOL_VERSION}-${key}`;
   }
-  return path.join(
-    os.tmpdir(),
+  return path4.join(
+    os2.tmpdir(),
     `wsmb-v${MAILBOX_PROJECT_SERVER_PROTOCOL_VERSION}`,
     `${key}.sock`
   );
 }
 function mailboxProjectServerMetadataPath(projectDir2) {
-  return path.join(path.resolve(projectDir2), MAILBOX_PROJECT_SERVER_METADATA_FILE);
+  return path4.join(path4.resolve(projectDir2), MAILBOX_PROJECT_SERVER_METADATA_FILE);
 }
 function ensureMailboxProjectServerSocketDirectory(endpoint2) {
   if (process.platform !== "win32") {
     assertUnixSocketPathWithinLimit(endpoint2, "mailbox");
-    fs.mkdirSync(path.dirname(endpoint2), { recursive: true, mode: 448 });
+    fs2.mkdirSync(path4.dirname(endpoint2), { recursive: true, mode: 448 });
   }
 }
 
 // src/coordination/sqlite-mailbox.ts
 import { randomUUID as randomUUID2 } from "node:crypto";
-import * as fs3 from "node:fs";
-import * as path3 from "node:path";
-
-// src/coordination/mailbox-constants.ts
-var AGENT_STALE_MS = 6e4;
-var CLIENT_STALE_MS = 6e4;
-var HEARTBEAT_THROTTLE_MS = 5e3;
-var LINE_SEPARATOR = "\n";
-var AUTO_COMPACT_INTERVAL_MS = 3e5;
-var AUTO_COMPACT_READ_MAX_AGE_MS = 6e5;
-var AUTO_COMPACT_DEFAULT_TTL_MS = 864e5;
-var AUTO_COMPACT_TYPE_TTL_MS = {
-  status: 18e5
-  // 30 min
-};
+import * as fs4 from "node:fs";
+import * as path6 from "node:path";
 
 // src/coordination/global-mailbox-completion.ts
 function isMailboxMessageProjection(msg) {
@@ -471,6 +1346,19 @@ function isMessageCompletedForActor(msg, actorId) {
   return msg.completed === true;
 }
 
+// src/coordination/mailbox-constants.ts
+var AGENT_STALE_MS = 6e4;
+var CLIENT_STALE_MS = 6e4;
+var HEARTBEAT_THROTTLE_MS = 5e3;
+var LINE_SEPARATOR = "\n";
+var AUTO_COMPACT_INTERVAL_MS = 3e5;
+var AUTO_COMPACT_READ_MAX_AGE_MS = 6e5;
+var AUTO_COMPACT_DEFAULT_TTL_MS = 864e5;
+var AUTO_COMPACT_TYPE_TTL_MS = {
+  status: 18e5
+  // 30 min
+};
+
 // src/coordination/mailbox-types.ts
 function mailboxIdentityBase(agentId) {
   return agentId.split(/[@#]/, 1)[0].trim().toLowerCase();
@@ -517,169 +1405,14 @@ function normalizeRecipient(to, sessionId) {
 function isMailboxReceiptRecordV2(value) {
   if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
   const v = value;
-  if (v["__mailboxReceipt"] !== 2) return false;
-  if (typeof v["messageId"] !== "string" || v["messageId"].length === 0) return false;
-  if (typeof v["actorId"] !== "string" || v["actorId"].length === 0) return false;
-  if (typeof v["timestamp"] !== "string" || v["timestamp"].length === 0) return false;
-  if ("read" in v && typeof v["read"] !== "boolean") return false;
-  if ("completed" in v && typeof v["completed"] !== "boolean") return false;
-  if ("outcome" in v && v["outcome"] !== void 0 && typeof v["outcome"] !== "string") return false;
-  return true;
-}
-
-// src/coordination/mailbox-receipt-folding.ts
-function isFanOutRecipient(to) {
-  if (to === "*") return true;
-  if (to.startsWith("@session:")) return true;
-  return !to.includes("@") && !to.includes("#");
-}
-function materializeMessage(msg, msgReceipts) {
-  const recipientState = foldRecipientState(msg, msgReceipts);
-  const legacyGlobalCompletion = classifyLegacyCompletion(msg, msgReceipts);
-  return {
-    ...msg,
-    recipientState,
-    ...legacyGlobalCompletion ? { legacyGlobalCompletion: true } : {}
-  };
-}
-function foldRecipientState(msg, v2Receipts) {
-  const state = {};
-  for (const [actorId, readAt] of Object.entries(msg.readBy)) {
-    state[actorId] = { actorId, readAt };
-  }
-  if (msg.completed && msg.completedBy && !isFanOutRecipient(msg.to)) {
-    const existing = state[msg.completedBy] ?? { actorId: msg.completedBy };
-    state[msg.completedBy] = {
-      ...existing,
-      completedAt: msg.completedAt ?? msg.timestamp,
-      completedBy: msg.completedBy,
-      ...msg.outcome !== void 0 ? { outcome: msg.outcome } : {}
-    };
-  }
-  const sorted = [...v2Receipts].sort((a, b) => a.timestamp.localeCompare(b.timestamp));
-  for (const receipt of sorted) {
-    const actorId = receipt.actorId;
-    const existing = state[actorId] ?? { actorId };
-    const readAt = existing.readAt ?? (receipt.read === true ? receipt.timestamp : void 0);
-    let completedAt = existing.completedAt;
-    let completedBy = existing.completedBy;
-    if (receipt.completed === true) {
-      completedAt = receipt.timestamp;
-      completedBy = actorId;
-    } else if (receipt.completed === false) {
-      completedAt = void 0;
-      completedBy = void 0;
-    }
-    const outcome = receipt.outcome !== void 0 ? receipt.outcome : existing.outcome;
-    state[actorId] = { actorId, readAt, completedAt, completedBy, outcome };
-  }
-  return state;
-}
-function classifyLegacyCompletion(msg, v2Receipts) {
-  if (!msg.completed) return false;
-  if (v2Receipts.some((r) => r.completed === true)) return false;
-  return isFanOutRecipient(msg.to);
-}
-
-// src/coordination/mailbox-retention-state.ts
-function resolveMailboxRetentionState(message, agentStatuses) {
-  const projection = message;
-  if (projection.legacyGlobalCompletion) {
-    return { completed: true, completedAt: message.completedAt ?? message.timestamp };
-  }
-  const recipientState = projection.recipientState;
-  if (recipientState === void 0) {
-    return message.completed ? { completed: true, completedAt: message.completedAt ?? message.timestamp } : { completed: false };
-  }
-  const relevantRecipients = resolveRelevantRecipients(message, recipientState, agentStatuses);
-  if (relevantRecipients.length === 0) return { completed: false };
-  const completionTimes = [];
-  for (const actorId of relevantRecipients) {
-    const completedAt = recipientState[actorId]?.completedAt;
-    if (completedAt === void 0) return { completed: false };
-    completionTimes.push(completedAt);
-  }
-  return {
-    completed: true,
-    // Retention starts only after the last intended recipient completed.
-    completedAt: completionTimes.reduce((latest, time) => time > latest ? time : latest)
-  };
-}
-function projectMailboxCompletion(message, actorId, agentStatuses) {
-  const projection = message;
-  let state;
-  if (actorId === void 0) {
-    state = resolveMailboxRetentionState(message, agentStatuses);
-  } else if (projection.legacyGlobalCompletion) {
-    state = { completed: true, completedAt: message.completedAt ?? message.timestamp };
-  } else if (projection.recipientState !== void 0) {
-    const completedAt = projection.recipientState[actorId]?.completedAt;
-    state = completedAt === void 0 ? { completed: false } : { completed: true, completedAt };
-  } else {
-    state = message.completed ? { completed: true, completedAt: message.completedAt ?? message.timestamp } : { completed: false };
-  }
-  const result = {
-    ...projection,
-    completed: state.completed,
-    readBy: { ...message.readBy }
-  };
-  if (state.completedAt === void 0) delete result.completedAt;
-  else result.completedAt = state.completedAt;
-  return result;
-}
-function resolveRelevantRecipients(message, recipientState, agentStatuses) {
-  const statuses = agentStatuses ?? [];
-  const receiptActors = Object.keys(recipientState);
-  if (message.to === "*") {
-    if (statuses.length === 0) return [];
-    const registeredRecipients = statuses.filter((status) => isMailboxMessageVisibleTo(message, status.agentId, status.role)).map((status) => status.agentId);
-    return [.../* @__PURE__ */ new Set([...registeredRecipients, ...receiptActors])];
-  }
-  if (message.to.startsWith("@session:")) {
-    if (statuses.length === 0) return [];
-    const sessionId = message.to.slice("@session:".length);
-    const registeredRecipients = statuses.filter(
-      (status) => status.sessionId === sessionId && isMailboxMessageVisibleTo(message, status.agentId, status.role)
-    ).map((status) => status.agentId);
-    return [.../* @__PURE__ */ new Set([...registeredRecipients, ...receiptActors])];
-  }
-  if (message.to.includes("@")) return [message.to];
-  if (statuses.length === 0) return [];
-  const aliasRecipients = statuses.filter(
-    (status) => (status.role?.toLowerCase() === message.to.toLowerCase() || mailboxIdentityBase(status.agentId) === message.to.toLowerCase()) && isMailboxMessageVisibleTo(message, status.agentId, status.role)
-  ).map((status) => status.agentId);
-  return [.../* @__PURE__ */ new Set([...aliasRecipients, ...receiptActors])];
-}
-
-// src/coordination/mailbox-status-mappers.ts
-function mapRegisteredAgentsToStatuses(registry, now, staleMs) {
-  return Array.from(registry.values()).map((agent) => ({
-    agentId: agent.agentId,
-    name: agent.name,
-    role: agent.role,
-    sessionId: agent.sessionId,
-    status: agent.status,
-    currentTool: agent.currentTool,
-    currentTask: agent.currentTask,
-    iterations: agent.iterations,
-    toolCalls: agent.toolCalls,
-    lastActivityAt: agent.lastSeenAt,
-    lastSeenAt: agent.lastSeenAt,
-    online: now - new Date(agent.lastSeenAt).getTime() < staleMs,
-    pid: agent.pid,
-    source: agent.source
-  })).sort((a, b) => b.lastSeenAt.localeCompare(a.lastSeenAt));
-}
-function mapRegisteredClientsToStatuses(registry, now, staleMs) {
-  return Array.from(registry.values()).map((client) => ({
-    clientId: client.clientId,
-    name: client.name,
-    source: client.source,
-    sessionId: client.sessionId,
-    lastSeenAt: client.lastSeenAt,
-    online: now - new Date(client.lastSeenAt).getTime() < staleMs,
-    pid: client.pid
-  })).sort((a, b) => b.lastSeenAt.localeCompare(a.lastSeenAt));
+  if (v["__mailboxReceipt"] !== 2) return false;
+  if (typeof v["messageId"] !== "string" || v["messageId"].length === 0) return false;
+  if (typeof v["actorId"] !== "string" || v["actorId"].length === 0) return false;
+  if (typeof v["timestamp"] !== "string" || v["timestamp"].length === 0) return false;
+  if ("read" in v && typeof v["read"] !== "boolean") return false;
+  if ("completed" in v && typeof v["completed"] !== "boolean") return false;
+  if ("outcome" in v && v["outcome"] !== void 0 && typeof v["outcome"] !== "string") return false;
+  return true;
 }
 
 // src/coordination/mailbox-message-codec.ts
@@ -844,6 +1577,161 @@ function applyAckToMessage(msg, ack) {
   }
 }
 
+// src/coordination/mailbox-receipt-folding.ts
+function isFanOutRecipient(to) {
+  if (to === "*") return true;
+  if (to.startsWith("@session:")) return true;
+  return !to.includes("@") && !to.includes("#");
+}
+function materializeMessage(msg, msgReceipts) {
+  const recipientState = foldRecipientState(msg, msgReceipts);
+  const legacyGlobalCompletion = classifyLegacyCompletion(msg, msgReceipts);
+  return {
+    ...msg,
+    recipientState,
+    ...legacyGlobalCompletion ? { legacyGlobalCompletion: true } : {}
+  };
+}
+function foldRecipientState(msg, v2Receipts) {
+  const state = {};
+  for (const [actorId, readAt] of Object.entries(msg.readBy)) {
+    state[actorId] = { actorId, readAt };
+  }
+  if (msg.completed && msg.completedBy && !isFanOutRecipient(msg.to)) {
+    const existing = state[msg.completedBy] ?? { actorId: msg.completedBy };
+    state[msg.completedBy] = {
+      ...existing,
+      completedAt: msg.completedAt ?? msg.timestamp,
+      completedBy: msg.completedBy,
+      ...msg.outcome !== void 0 ? { outcome: msg.outcome } : {}
+    };
+  }
+  const sorted = [...v2Receipts].sort((a, b) => a.timestamp.localeCompare(b.timestamp));
+  for (const receipt of sorted) {
+    const actorId = receipt.actorId;
+    const existing = state[actorId] ?? { actorId };
+    const readAt = existing.readAt ?? (receipt.read === true ? receipt.timestamp : void 0);
+    let completedAt = existing.completedAt;
+    let completedBy = existing.completedBy;
+    if (receipt.completed === true) {
+      completedAt = receipt.timestamp;
+      completedBy = actorId;
+    } else if (receipt.completed === false) {
+      completedAt = void 0;
+      completedBy = void 0;
+    }
+    const outcome = receipt.outcome !== void 0 ? receipt.outcome : existing.outcome;
+    state[actorId] = { actorId, readAt, completedAt, completedBy, outcome };
+  }
+  return state;
+}
+function classifyLegacyCompletion(msg, v2Receipts) {
+  if (!msg.completed) return false;
+  if (v2Receipts.some((r) => r.completed === true)) return false;
+  return isFanOutRecipient(msg.to);
+}
+
+// src/coordination/mailbox-retention-state.ts
+function resolveMailboxRetentionState(message, agentStatuses) {
+  const projection = message;
+  if (projection.legacyGlobalCompletion) {
+    return { completed: true, completedAt: message.completedAt ?? message.timestamp };
+  }
+  const recipientState = projection.recipientState;
+  if (recipientState === void 0) {
+    return message.completed ? { completed: true, completedAt: message.completedAt ?? message.timestamp } : { completed: false };
+  }
+  const relevantRecipients = resolveRelevantRecipients(message, recipientState, agentStatuses);
+  if (relevantRecipients.length === 0) return { completed: false };
+  const completionTimes = [];
+  for (const actorId of relevantRecipients) {
+    const completedAt = recipientState[actorId]?.completedAt;
+    if (completedAt === void 0) return { completed: false };
+    completionTimes.push(completedAt);
+  }
+  return {
+    completed: true,
+    // Retention starts only after the last intended recipient completed.
+    completedAt: completionTimes.reduce((latest, time) => time > latest ? time : latest)
+  };
+}
+function projectMailboxCompletion(message, actorId, agentStatuses) {
+  const projection = message;
+  let state;
+  if (actorId === void 0) {
+    state = resolveMailboxRetentionState(message, agentStatuses);
+  } else if (projection.legacyGlobalCompletion) {
+    state = { completed: true, completedAt: message.completedAt ?? message.timestamp };
+  } else if (projection.recipientState !== void 0) {
+    const completedAt = projection.recipientState[actorId]?.completedAt;
+    state = completedAt === void 0 ? { completed: false } : { completed: true, completedAt };
+  } else {
+    state = message.completed ? { completed: true, completedAt: message.completedAt ?? message.timestamp } : { completed: false };
+  }
+  const result = {
+    ...projection,
+    completed: state.completed,
+    readBy: { ...message.readBy }
+  };
+  if (state.completedAt === void 0) delete result.completedAt;
+  else result.completedAt = state.completedAt;
+  return result;
+}
+function resolveRelevantRecipients(message, recipientState, agentStatuses) {
+  const statuses = agentStatuses ?? [];
+  const receiptActors = Object.keys(recipientState);
+  if (message.to === "*") {
+    if (statuses.length === 0) return [];
+    const registeredRecipients = statuses.filter((status) => isMailboxMessageVisibleTo(message, status.agentId, status.role)).map((status) => status.agentId);
+    return [.../* @__PURE__ */ new Set([...registeredRecipients, ...receiptActors])];
+  }
+  if (message.to.startsWith("@session:")) {
+    if (statuses.length === 0) return [];
+    const sessionId = message.to.slice("@session:".length);
+    const registeredRecipients = statuses.filter(
+      (status) => status.sessionId === sessionId && isMailboxMessageVisibleTo(message, status.agentId, status.role)
+    ).map((status) => status.agentId);
+    return [.../* @__PURE__ */ new Set([...registeredRecipients, ...receiptActors])];
+  }
+  if (message.to.includes("@")) return [message.to];
+  if (statuses.length === 0) return [];
+  const aliasRecipients = statuses.filter(
+    (status) => (status.role?.toLowerCase() === message.to.toLowerCase() || mailboxIdentityBase(status.agentId) === message.to.toLowerCase()) && isMailboxMessageVisibleTo(message, status.agentId, status.role)
+  ).map((status) => status.agentId);
+  return [.../* @__PURE__ */ new Set([...aliasRecipients, ...receiptActors])];
+}
+
+// src/coordination/mailbox-status-mappers.ts
+function mapRegisteredAgentsToStatuses(registry, now, staleMs) {
+  return Array.from(registry.values()).map((agent) => ({
+    agentId: agent.agentId,
+    name: agent.name,
+    role: agent.role,
+    sessionId: agent.sessionId,
+    status: agent.status,
+    currentTool: agent.currentTool,
+    currentTask: agent.currentTask,
+    iterations: agent.iterations,
+    toolCalls: agent.toolCalls,
+    lastActivityAt: agent.lastSeenAt,
+    lastSeenAt: agent.lastSeenAt,
+    online: now - new Date(agent.lastSeenAt).getTime() < staleMs,
+    pid: agent.pid,
+    source: agent.source
+  })).sort((a, b) => b.lastSeenAt.localeCompare(a.lastSeenAt));
+}
+function mapRegisteredClientsToStatuses(registry, now, staleMs) {
+  return Array.from(registry.values()).map((client) => ({
+    clientId: client.clientId,
+    name: client.name,
+    source: client.source,
+    sessionId: client.sessionId,
+    lastSeenAt: client.lastSeenAt,
+    online: now - new Date(client.lastSeenAt).getTime() < staleMs,
+    pid: client.pid
+  })).sort((a, b) => b.lastSeenAt.localeCompare(a.lastSeenAt));
+}
+
 // src/coordination/sqlite-mailbox-compaction.ts
 async function purgeStale(ctx, options) {
   const completedMaxAgeMs = options?.completedMaxAgeMs ?? 864e5;
@@ -927,67 +1815,63 @@ async function autoCompact(ctx, options) {
   };
 }
 
-// src/coordination/mailbox-credential-store.ts
-import * as crypto from "node:crypto";
-var CREDENTIAL_STORE_FILE = "_mailbox_credentials.json";
-var MAX_CREDENTIAL_TTL = {
-  agent: 7 * 24 * 60 * 60 * 1e3,
-  // 7 days
-  operator: 24 * 60 * 60 * 1e3,
-  // 24 hours
-  service: 30 * 24 * 60 * 60 * 1e3
-  // 30 days
-};
-var ROTATION_OVERLAP_MS = 60 * 60 * 1e3;
-function createMailboxCredential(opts, now = Date.now()) {
-  const ttlMs = Math.min(opts.ttlMs, MAX_CREDENTIAL_TTL[opts.kind]);
-  const credentialId = crypto.randomUUID();
-  const secret = crypto.randomBytes(32).toString("hex");
-  const verifierKey = crypto.createHash("sha256").update(secret).digest();
-  const verifier = crypto.createHmac("sha256", verifierKey).update(credentialId).digest("hex");
-  return {
-    credential: {
-      credentialId,
-      verifier,
-      verifierAlgorithm: "hmac-sha256",
-      principalId: opts.principalId,
-      projectId: opts.projectId,
-      capabilities: opts.capabilities,
-      kind: opts.kind,
-      issuedAt: new Date(now).toISOString(),
-      expiresAt: new Date(now + ttlMs).toISOString(),
-      notBefore: opts.notBefore?.toISOString(),
-      status: "active",
-      statusChangedAt: new Date(now).toISOString(),
-      supersedes: opts.supersedes,
-      lastModifiedBy: opts.issuedBy
-    },
-    secret
-  };
-}
-function verifyMailboxCredential(credential, secret, now = Date.now()) {
-  if (credential === void 0) {
-    return { valid: false, reason: "credential not found" };
-  }
-  const rotationStillValid = credential.status === "rotated_out" && credential.rotationValidUntil !== void 0 && new Date(credential.rotationValidUntil).getTime() >= now;
-  if (credential.status !== "active" && !rotationStillValid) {
-    return { valid: false, reason: `credential is ${credential.status}`, credential };
+// src/coordination/mailbox-credential-throttle.ts
+var CREDENTIAL_VERIFY_MAX_FAILURES = 10;
+var CREDENTIAL_VERIFY_WINDOW_MS = 6e4;
+var CREDENTIAL_VERIFY_COOLDOWN_MS = 6e4;
+var MAX_TRACKED_IDS = 4096;
+var CredentialVerifyThrottle = class {
+  constructor(maxFailures = CREDENTIAL_VERIFY_MAX_FAILURES, windowMs = CREDENTIAL_VERIFY_WINDOW_MS, cooldownMs = CREDENTIAL_VERIFY_COOLDOWN_MS) {
+    this.maxFailures = maxFailures;
+    this.windowMs = windowMs;
+    this.cooldownMs = cooldownMs;
+  }
+  maxFailures;
+  windowMs;
+  cooldownMs;
+  records = /* @__PURE__ */ new Map();
+  /** Is this credential id allowed another attempt right now? */
+  check(credentialId, now = Date.now()) {
+    const record = this.records.get(credentialId);
+    if (record === void 0) return { allowed: true, retryAfterMs: 0 };
+    if (record.blockedUntil > now) {
+      return { allowed: false, retryAfterMs: record.blockedUntil - now };
+    }
+    return { allowed: true, retryAfterMs: 0 };
+  }
+  /** Record a failed verification. Starts the cooldown once the limit is hit. */
+  recordFailure(credentialId, now = Date.now()) {
+    const record = this.records.get(credentialId);
+    if (record === void 0 || now - record.windowStartedAt > this.windowMs) {
+      this.evictIfFull();
+      this.records.set(credentialId, { failures: 1, windowStartedAt: now, blockedUntil: 0 });
+      return;
+    }
+    record.failures += 1;
+    if (record.failures >= this.maxFailures) {
+      record.blockedUntil = now + this.cooldownMs;
+      record.failures = 0;
+      record.windowStartedAt = now;
+    }
   }
-  if (new Date(credential.expiresAt).getTime() <= now) {
-    return { valid: false, reason: "credential expired", credential };
+  /**
+   * Clear the counter after a successful verification. A legitimate holder who
+   * fluffed a few attempts is not left in a cooldown they cannot exit.
+   */
+  recordSuccess(credentialId) {
+    this.records.delete(credentialId);
   }
-  if (credential.notBefore !== void 0 && new Date(credential.notBefore).getTime() > now) {
-    return { valid: false, reason: "credential not yet valid", credential };
+  /** Test seam. */
+  reset() {
+    this.records.clear();
   }
-  const verifierKey = crypto.createHash("sha256").update(secret).digest();
-  const expected = crypto.createHmac("sha256", verifierKey).update(credential.credentialId).digest("hex");
-  const actualBytes = Buffer.from(credential.verifier, "hex");
-  const expectedBytes = Buffer.from(expected, "hex");
-  if (actualBytes.length !== expectedBytes.length || !crypto.timingSafeEqual(actualBytes, expectedBytes)) {
-    return { valid: false, reason: "invalid secret", credential };
+  evictIfFull() {
+    if (this.records.size < MAX_TRACKED_IDS) return;
+    const oldest = this.records.keys().next();
+    if (!oldest.done) this.records.delete(oldest.value);
   }
-  return { valid: true, credential };
-}
+};
+var credentialVerifyThrottle = new CredentialVerifyThrottle();
 
 // src/coordination/sqlite-mailbox-rows.ts
 var MALFORMED_TIMESTAMP = "last_seen_at NOT GLOB '[0-9][0-9][0-9][0-9]-[0-9][0-9]-[0-9][0-9]T*'";
@@ -1267,7 +2151,17 @@ function credentialIssue(db, transaction, options) {
   return issued;
 }
 function credentialVerify(db, credentialId, secret) {
-  return verifyMailboxCredential(credentialGet(db, credentialId) ?? void 0, secret);
+  const decision = credentialVerifyThrottle.check(credentialId);
+  if (!decision.allowed) {
+    return {
+      valid: false,
+      reason: `too many failed verification attempts \u2014 retry in ${Math.ceil(decision.retryAfterMs / 1e3)}s`
+    };
+  }
+  const result = verifyMailboxCredential(credentialGet(db, credentialId) ?? void 0, secret);
+  if (result.valid) credentialVerifyThrottle.recordSuccess(credentialId);
+  else credentialVerifyThrottle.recordFailure(credentialId);
+  return result;
 }
 function credentialRevoke(db, credentialId, reason, by) {
   const credential = credentialGet(db, credentialId);
@@ -1288,15 +2182,16 @@ function credentialRotate(db, transaction, credentialId, options) {
     kind: old.kind,
     capabilities: options?.capabilities ?? old.capabilities,
     ttlMs: options?.ttlMs ?? MAX_CREDENTIAL_TTL[old.kind],
+    notBefore: options?.notBefore,
     supersedes: credentialId,
     issuedBy: options?.issuedBy
   });
 }
 
 // src/coordination/sqlite-mailbox-schema.ts
-import * as fs2 from "node:fs";
+import * as fs3 from "node:fs";
 import { createRequire } from "node:module";
-import * as path2 from "node:path";
+import * as path5 from "node:path";
 
 // src/utils/sqlite-warning.ts
 var SQLITE_EXPERIMENTAL_WARNING_RE = /sqlite is an experimental feature/i;
@@ -1546,10 +2441,10 @@ function migrateLegacyCredentials(ctx) {
   const { db } = ctx;
   const marker = db.prepare("SELECT value FROM mailbox_meta WHERE key = ?").get("legacy_credentials_imported");
   if (marker !== void 0) return;
-  const legacyPath = path2.join(ctx.projectDir, CREDENTIAL_STORE_FILE);
+  const legacyPath = path5.join(ctx.projectDir, CREDENTIAL_STORE_FILE);
   const credentials = [];
   try {
-    for (const line of fs2.readFileSync(legacyPath, "utf8").split(/\r?\n/u)) {
+    for (const line of fs3.readFileSync(legacyPath, "utf8").split(/\r?\n/u)) {
       if (!line.trim()) continue;
       try {
         const credential = JSON.parse(line);
@@ -1576,11 +2471,11 @@ function migrateLegacyFiles(ctx) {
   if (marker !== void 0) return;
   const messages = readLegacyMessages(ctx.projectDir);
   const agents = readLegacyRegistry(
-    path2.join(ctx.projectDir, "_mailbox.registry.json"),
+    path5.join(ctx.projectDir, "_mailbox.registry.json"),
     parseAgentRegistryEntry
   );
   const clients2 = readLegacyRegistry(
-    path2.join(ctx.projectDir, GLOBAL_MAILBOX_CLIENT_REGISTRY_FILE),
+    path5.join(ctx.projectDir, GLOBAL_MAILBOX_CLIENT_REGISTRY_FILE),
     parseClientRegistryEntry
   );
   ctx.transaction(() => {
@@ -1602,7 +2497,7 @@ function migrateLegacyFiles(ctx) {
 function readLegacyMessages(projectDir2) {
   try {
     return parseMailboxFile(
-      fs2.readFileSync(path2.join(projectDir2, GLOBAL_MAILBOX_FILE), "utf8")
+      fs3.readFileSync(path5.join(projectDir2, GLOBAL_MAILBOX_FILE), "utf8")
     );
   } catch (error) {
     if (error.code === "ENOENT") return [];
@@ -1611,7 +2506,7 @@ function readLegacyMessages(projectDir2) {
 }
 function readLegacyRegistry(filePath, parseEntry) {
   try {
-    const raw = JSON.parse(fs2.readFileSync(filePath, "utf8"));
+    const raw = JSON.parse(fs3.readFileSync(filePath, "utf8"));
     const result = /* @__PURE__ */ new Map();
     for (const [id, value] of Object.entries(raw)) {
       const parsed = parseEntry(value);
@@ -1631,8 +2526,8 @@ var HEARTBEAT_TRACKING_TTL_MS = 30 * 6e4;
 var SqliteMailbox = class {
   constructor(projectDir2, events2, eventEmitter2) {
     this.projectDir = projectDir2;
-    fs3.mkdirSync(projectDir2, { recursive: true });
-    this.databasePath = path3.join(projectDir2, SQLITE_MAILBOX_FILE);
+    fs4.mkdirSync(projectDir2, { recursive: true });
+    this.databasePath = path6.join(projectDir2, SQLITE_MAILBOX_FILE);
     this.messagePath = this.databasePath;
     this.events = events2;
     this.eventEmitter = eventEmitter2;
@@ -1781,7 +2676,41 @@ var SqliteMailbox = class {
       where.push("reply_to = ?");
       params.push(query.replyTo);
     }
-    const canPreLimit = query.unreadBy === void 0 && !query.incompleteOnly;
+    if (query.unreadBy !== void 0) {
+      if (!isMailboxLeader(query.unreadBy, query.readerRole)) {
+        where.push("COALESCE(json_extract(data, '$.audience'), 'all') <> 'leaders'");
+      }
+      if (!query.incompleteOnly) {
+        where.push(`NOT EXISTS (
+          SELECT 1 FROM message_receipts AS unread_receipt
+          WHERE unread_receipt.message_id = messages.id
+            AND unread_receipt.actor_id = ?
+            AND unread_receipt.read_at IS NOT NULL
+        )`);
+        params.push(query.unreadBy);
+        where.push(`NOT EXISTS (
+          SELECT 1 FROM json_each(json_extract(data, '$.readBy')) AS legacy_read
+          WHERE legacy_read.key = ?
+        )`);
+        params.push(query.unreadBy);
+      } else {
+        where.push("legacy_global_completion = 0");
+        where.push(`NOT EXISTS (
+          SELECT 1 FROM message_receipts AS completed_receipt
+          WHERE completed_receipt.message_id = messages.id
+            AND completed_receipt.actor_id = ?
+            AND completed_receipt.completed_at IS NOT NULL
+        )`);
+        params.push(query.unreadBy);
+        where.push(`(
+          completed = 0 OR EXISTS (
+            SELECT 1 FROM message_receipts AS any_receipt
+            WHERE any_receipt.message_id = messages.id
+          )
+        )`);
+      }
+    }
+    const canPreLimit = !query.incompleteOnly || query.unreadBy !== void 0;
     let sql = "SELECT id, data, legacy_global_completion FROM messages";
     if (where.length > 0) sql += ` WHERE ${where.join(" AND ")}`;
     sql += " ORDER BY timestamp DESC, rowid DESC";
@@ -1793,10 +2722,14 @@ var SqliteMailbox = class {
     const messages = this.materializeMessageRows(rows).filter((message) => {
       if (query.to !== void 0 && message.to !== query.to && message.to !== "*") return false;
       if (query.from !== void 0 && message.from !== query.from) return false;
-      if (query.sessionId !== void 0 && message.senderSessionId !== query.sessionId) return false;
-      if (query.unreadBy !== void 0 && !isMailboxMessageVisibleTo(message, query.unreadBy, query.readerRole)) return false;
-      if (!query.incompleteOnly && query.unreadBy !== void 0 && query.unreadBy in message.readBy) return false;
-      if (query.incompleteOnly && (query.unreadBy === void 0 ? projectMailboxCompletion(message, void 0, statuses).completed : isMessageCompletedForActor(message, query.unreadBy))) return false;
+      if (query.sessionId !== void 0 && message.senderSessionId !== query.sessionId)
+        return false;
+      if (query.unreadBy !== void 0 && !isMailboxMessageVisibleTo(message, query.unreadBy, query.readerRole))
+        return false;
+      if (!query.incompleteOnly && query.unreadBy !== void 0 && query.unreadBy in message.readBy)
+        return false;
+      if (query.incompleteOnly && (query.unreadBy === void 0 ? projectMailboxCompletion(message, void 0, statuses).completed : isMessageCompletedForActor(message, query.unreadBy)))
+        return false;
       if (type !== void 0 && message.type !== type) return false;
       if (priorityRank[message.priority] < minimumRank) return false;
       if (query.since !== void 0 && message.timestamp <= query.since) return false;
@@ -2161,7 +3094,7 @@ function parseArgs(argv) {
     if (argv[index] === "--project-dir") projectDir2 = argv[++index];
   }
   if (!projectDir2) throw new Error("mailbox project server requires --project-dir");
-  return { projectDir: path4.resolve(projectDir2) };
+  return { projectDir: path7.resolve(projectDir2) };
 }
 useDaemonPerfDefaults();
 var { projectDir } = parseArgs(process.argv.slice(2));
@@ -2181,6 +3114,18 @@ var pendingRequests = 0;
 var idleTimer;
 var stopping = false;
 var stopAutoCompact;
+var stopMemoryWatchdog = startSharedHeapWatchdog({
+  collectStats: () => ({
+    surface: "mailbox-project-server",
+    clients: clients.size,
+    pendingRequests
+  })
+});
+var authToken = randomBytes2(16).toString("hex");
+var markMetadataWritten;
+var metadataWritten = new Promise((resolve5) => {
+  markMetadataWritten = resolve5;
+});
 var serverInfo = {
   protocolVersion: MAILBOX_PROJECT_SERVER_PROTOCOL_VERSION,
   pid: process.pid,
@@ -2210,7 +3155,7 @@ events.onAny((event, payload) => {
 });
 eventEmitter.subscribe((event) => broadcast({ type: "mailbox-event", event }));
 function serverStatus() {
-  const databasePath = mailbox?.databasePath ?? path4.join(projectDir, SQLITE_MAILBOX_FILE);
+  const databasePath = mailbox?.databasePath ?? path7.join(projectDir, SQLITE_MAILBOX_FILE);
   return {
     ...serverInfo,
     clients: clients.size,
@@ -2220,6 +3165,18 @@ function serverStatus() {
     storageKind: "sqlite"
   };
 }
+function reviveCredentialOptions(options) {
+  const wireNotBefore = options.notBefore;
+  if (wireNotBefore === void 0 || wireNotBefore instanceof Date) return options;
+  if (typeof wireNotBefore !== "string") {
+    throw new Error("Credential notBefore must be an ISO date-time string");
+  }
+  const notBefore = new Date(wireNotBefore);
+  if (!Number.isFinite(notBefore.getTime())) {
+    throw new Error("Credential notBefore must be an ISO date-time string");
+  }
+  return { ...options, notBefore };
+}
 async function dispatch(op, rawArgs) {
   const activeMailbox = mailbox;
   if (activeMailbox === void 0) throw new Error("Mailbox SQLite owner is not initialized");
@@ -2306,11 +3263,18 @@ async function dispatch(op, rawArgs) {
     }
     case "credentialIssue": {
       const args = rawArgs;
-      return activeMailbox.credentialIssue(args.options);
+      return activeMailbox.credentialIssue(
+        reviveCredentialOptions(args.options)
+      );
     }
     case "credentialVerify": {
       const args = rawArgs;
-      return activeMailbox.credentialVerify(args.credentialId, args.secret);
+      return Promise.resolve(activeMailbox.credentialVerify(args.credentialId, args.secret)).then(
+        (result) => result.valid ? {
+          ...result,
+          credential: result.credential ? redactMailboxCredential(result.credential) : void 0
+        } : { valid: false, reason: result.reason }
+      );
     }
     case "credentialRevoke": {
       const args = rawArgs;
@@ -2318,20 +3282,40 @@ async function dispatch(op, rawArgs) {
     }
     case "credentialRotate": {
       const args = rawArgs;
-      return activeMailbox.credentialRotate(args.credentialId, args.options);
+      return activeMailbox.credentialRotate(
+        args.credentialId,
+        args.options === void 0 ? void 0 : reviveCredentialOptions(args.options)
+      );
     }
     case "credentialGet": {
       const args = rawArgs;
-      return activeMailbox.credentialGet(args.credentialId);
+      return Promise.resolve(activeMailbox.credentialGet(args.credentialId)).then(
+        (credential) => credential ? redactMailboxCredential(credential) : null
+      );
     }
     case "credentialList":
-      return activeMailbox.credentialList();
+      return Promise.resolve(activeMailbox.credentialList()).then(
+        (credentials) => credentials.map(redactMailboxCredential)
+      );
     case "credentialStatusCounts":
       return activeMailbox.credentialStatusCounts();
   }
 }
+function checkAuthToken(state, message) {
+  if (message.type === "heartbeat") return true;
+  if (message.authToken === authToken) return true;
+  send(state, {
+    type: "response",
+    id: message.id,
+    ok: false,
+    error: "Mailbox IPC request rejected: missing or invalid authToken. Reconnect to refresh metadata (.mailbox-server.json#authToken).",
+    errorName: "UnauthorizedMailboxRequest"
+  });
+  return false;
+}
 function handleMessage(state, message) {
   state.lastSeenAt = Date.now();
+  if (!checkAuthToken(state, message)) return;
   if (message.type === "heartbeat") return;
   if (message.type === "shutdown") {
     send(state, {
@@ -2399,18 +3383,9 @@ function scheduleIdleStop() {
 }
 async function writeMetadata() {
   await fsPromises.mkdir(projectDir, { recursive: true });
-  const temporary = `${metadataPath}.${process.pid}.tmp`;
-  await fsPromises.writeFile(temporary, `${JSON.stringify(serverStatus(), null, 2)}
-`, {
-    encoding: "utf8",
-    mode: 384
-  });
-  try {
-    await fsPromises.rename(temporary, metadataPath);
-  } catch {
-    await fsPromises.rm(metadataPath, { force: true });
-    await fsPromises.rename(temporary, metadataPath);
-  }
+  const metadata = { ...serverStatus(), authToken };
+  await atomicWrite(metadataPath, `${JSON.stringify(metadata, null, 2)}
+`, { mode: 384 });
 }
 async function removeOwnedMetadata() {
   try {
@@ -2426,7 +3401,8 @@ async function stop(_reason) {
   idleTimer = void 0;
   clearInterval(leaseSweep);
   stopAutoCompact?.();
-  const serverClosed = new Promise((resolve3) => server.close(() => resolve3()));
+  await removeOwnedMetadata();
+  const serverClosed = new Promise((resolve5) => server.close(() => resolve5()));
   for (const state of clients) state.socket.end();
   const forceCloseTimer = setTimeout(() => {
     for (const state of clients) state.socket.destroy();
@@ -2439,11 +3415,11 @@ async function stop(_reason) {
   await mailbox?.close().catch(() => {
   });
   mailbox = void 0;
-  await removeOwnedMetadata();
   if (process.platform !== "win32") {
     await fsPromises.rm(endpoint, { force: true }).catch(() => {
     });
   }
+  await stopMemoryWatchdog();
 }
 ensureMailboxProjectServerSocketDirectory(endpoint);
 var server = net.createServer((socket) => {
@@ -2456,7 +3432,9 @@ var server = net.createServer((socket) => {
   socket.setEncoding("utf8");
   const state = { socket, buffer: "", lastSeenAt: Date.now() };
   clients.add(state);
-  send(state, { type: "hello", ...serverInfo });
+  void metadataWritten.then(() => {
+    if (!socket.destroyed) send(state, { type: "hello", ...serverInfo });
+  });
   socket.on("data", (chunk) => onData(state, chunk));
   socket.on("error", () => {
   });
@@ -2492,7 +3470,7 @@ server.on("error", (error) => {
     probe.once("error", () => {
       probe.destroy();
       try {
-        fs4.rmSync(endpoint, { force: true });
+        fs5.rmSync(endpoint, { force: true });
       } catch {
       }
       probingExistingEndpoint = false;
@@ -2505,7 +3483,7 @@ server.on("error", (error) => {
 server.on("listening", () => {
   if (process.platform !== "win32") {
     try {
-      fs4.chmodSync(endpoint, 384);
+      fs5.chmodSync(endpoint, 384);
     } catch {
     }
   }
@@ -2518,7 +3496,10 @@ server.on("listening", () => {
     return;
   }
   stopAutoCompact = mailbox.startAutoCompactTimer();
-  void writeMetadata().then(() => scheduleIdleStop()).catch(() => {
+  void writeMetadata().then(() => {
+    markMetadataWritten?.();
+    scheduleIdleStop();
+  }).catch(() => {
     void stop("metadata-write-failed").finally(() => {
       process.exitCode = 1;
     });