@wrongstack/core 0.296.4 → 0.298.0

package/dist/chronicle/project-server.js

@@ -1,10 +1,832 @@
 #!/usr/bin/env node
 
 // src/chronicle/project-server.ts
-import * as fs8 from "node:fs";
-import * as fsp2 from "node:fs/promises";
+import { randomBytes } from "node:crypto";
+import * as fs9 from "node:fs";
+import * as fsp4 from "node:fs/promises";
 import * as net from "node:net";
-import * as path12 from "node:path";
+import * as path15 from "node:path";
+
+// 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 stat5 = await fsp.stat(fullPath);
+      return { fullPath, mtimeMs: stat5.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;
@@ -23,8 +845,8 @@ function createChronicleContext(scope, traceId = randomUUID()) {
 
 // src/chronicle/file-observer.ts
 import { createHash } from "node:crypto";
-import * as fsp from "node:fs/promises";
-import * as path2 from "node:path";
+import * as fsp3 from "node:fs/promises";
+import * as path5 from "node:path";
 
 // src/storage/storage-concurrency.ts
 async function mapWithConcurrency(items, concurrency, mapper) {
@@ -46,14 +868,14 @@ async function mapWithConcurrency(items, concurrency, mapper) {
 }
 
 // src/utils/project-watch.ts
-import * as fs from "node:fs";
-import * as path from "node:path";
+import * as fs2 from "node:fs";
+import * as path4 from "node:path";
 var REGISTRY_KEY = /* @__PURE__ */ Symbol.for("wrongstack.projectWatchRegistry");
 var globalScope = globalThis;
 if (!globalScope[REGISTRY_KEY]) globalScope[REGISTRY_KEY] = /* @__PURE__ */ new Map();
 var registry = globalScope[REGISTRY_KEY];
 function registryKey(root) {
-  const resolved = path.resolve(root);
+  const resolved = path4.resolve(root);
   return process.platform === "win32" ? resolved.toLowerCase() : resolved;
 }
 function watchProjectTree(root, listener, opts) {
@@ -61,8 +883,8 @@ function watchProjectTree(root, listener, opts) {
   let entry = registry.get(key);
   if (!entry || entry.dead) {
     const subscribers = /* @__PURE__ */ new Set();
-    const watcher2 = fs.watch(
-      path.resolve(root),
+    const watcher2 = fs2.watch(
+      path4.resolve(root),
       { recursive: true, persistent: false },
       (eventType, filename) => {
         const event = {
@@ -146,7 +968,7 @@ var SCAN_HASH_CONCURRENCY = 32;
 var DEFAULT_FULL_RESCAN_MIN_INTERVAL_MS = 3e4;
 var MAX_RECENT_TOOL_MUTATIONS = 500;
 async function startChronicleFileObserver(options) {
-  const root = path2.resolve(options.projectRoot);
+  const root = path5.resolve(options.projectRoot);
   const excluded = new Set(options.excludedDirectories ?? DEFAULT_EXCLUDED);
   const excludedPaths = normalizeExcludedPaths(root, options.excludedPaths ?? []);
   const debounceMs = options.debounceMs ?? 120;
@@ -154,8 +976,8 @@ async function startChronicleFileObserver(options) {
   const known = (await scanProject(root, excluded, excludedPaths, maxHashBytes, options.onError)).files;
   const recentToolMutations = /* @__PURE__ */ new Map();
   const noteToolMutation = (hint) => {
-    const absolute = path2.isAbsolute(hint.path) ? path2.normalize(hint.path) : path2.resolve(root, hint.path);
-    const relative4 = normalizeRelative(path2.relative(root, absolute));
+    const absolute = path5.isAbsolute(hint.path) ? path5.normalize(hint.path) : path5.resolve(root, hint.path);
+    const relative4 = normalizeRelative(path5.relative(root, absolute));
     if (relative4.startsWith("../") || isExcluded(relative4, excluded, excludedPaths)) return;
     recentToolMutations.set(relative4, {
       at: hint.at ?? Date.now(),
@@ -235,7 +1057,7 @@ async function startChronicleFileObserver(options) {
     for (const relative4 of candidates) {
       const before = known.get(relative4);
       const cached = fullScan?.files.get(relative4);
-      const after = cached ?? (fullScan?.complete ? void 0 : await fingerprint(path2.join(root, relative4), maxHashBytes));
+      const after = cached ?? (fullScan?.complete ? void 0 : await fingerprint(path5.join(root, relative4), maxHashBytes));
       if (sameFingerprint(before, after)) continue;
       changes.push({ relative: relative4, before, after });
     }
@@ -375,7 +1197,7 @@ async function recordMutation(options, eventType, relativePath, state, attribute
   const context = typeof options.context === "function" ? options.context() : options.context;
   const operation = attributes["operation"];
   options.events?.emit("file.activity", {
-    filePath: path2.join(options.projectRoot, relativePath),
+    filePath: path5.join(options.projectRoot, relativePath),
     operation,
     phase: "changed",
     source: attribution ? "tool" : "external",
@@ -428,10 +1250,10 @@ async function scanProject(root, excluded, excludedPaths, maxHashBytes, onError,
   while (dirs.length > 0) {
     const relativeDir = dirs.pop();
     try {
-      const entries = await fsp.readdir(path2.join(root, relativeDir), { withFileTypes: true });
+      const entries = await fsp3.readdir(path5.join(root, relativeDir), { withFileTypes: true });
       const filePaths = [];
       for (const entry of entries) {
-        const relative4 = normalizeRelative(path2.join(relativeDir, entry.name));
+        const relative4 = normalizeRelative(path5.join(relativeDir, entry.name));
         if (isExcluded(relative4, excluded, excludedPaths)) continue;
         if (entry.isDirectory()) {
           dirs.push(relative4);
@@ -445,7 +1267,7 @@ async function scanProject(root, excluded, excludedPaths, maxHashBytes, onError,
         async (relative4) => {
           try {
             const value = await fingerprint(
-              path2.join(root, relative4),
+              path5.join(root, relative4),
               maxHashBytes,
               previous?.get(relative4)
             );
@@ -469,15 +1291,15 @@ async function scanProject(root, excluded, excludedPaths, maxHashBytes, onError,
 }
 async function fingerprint(filePath, maxHashBytes, previous) {
   try {
-    const stat4 = await fsp.stat(filePath);
-    if (!stat4.isFile()) return void 0;
-    const base = { size: stat4.size, mtimeMs: stat4.mtimeMs };
-    if (previous?.hash !== void 0 && previous.size === stat4.size && previous.mtimeMs === stat4.mtimeMs) {
+    const stat5 = await fsp3.stat(filePath);
+    if (!stat5.isFile()) return void 0;
+    const base = { size: stat5.size, mtimeMs: stat5.mtimeMs };
+    if (previous?.hash !== void 0 && previous.size === stat5.size && previous.mtimeMs === stat5.mtimeMs) {
       base.hash = previous.hash;
       return base;
     }
-    if (stat4.size <= maxHashBytes) {
-      base.hash = createHash("sha256").update(await fsp.readFile(filePath)).digest("hex");
+    if (stat5.size <= maxHashBytes) {
+      base.hash = createHash("sha256").update(await fsp3.readFile(filePath)).digest("hex");
     }
     return base;
   } catch (error) {
@@ -502,7 +1324,7 @@ function isExcluded(relative4, excluded, excludedPaths) {
 function normalizeExcludedPaths(root, values) {
   const result = /* @__PURE__ */ new Set();
   for (const value of values) {
-    const relative4 = path2.isAbsolute(value) ? path2.relative(root, path2.resolve(value)) : value;
+    const relative4 = path5.isAbsolute(value) ? path5.relative(root, path5.resolve(value)) : value;
     const normalized = normalizeRelative(relative4).replace(/\/+$/u, "");
     if (!normalized || normalized === "." || normalized.startsWith("../")) continue;
     result.add(normalized);
@@ -521,15 +1343,15 @@ function unionKeys(a, b) {
 
 // src/chronicle/identity.ts
 import { createHash as createHash2 } from "node:crypto";
-import * as os from "node:os";
-import * as path3 from "node:path";
+import * as os2 from "node:os";
+import * as path6 from "node:path";
 function resolveChronicleRuntimeLocation(input) {
   const day = (input.now ?? /* @__PURE__ */ new Date()).toISOString().slice(0, 10);
   return {
-    installationId: stableId("installation", path3.resolve(input.globalRoot)),
-    machineId: stableId("machine", `${os.hostname()}\0${os.platform()}\0${os.arch()}`),
+    installationId: stableId("installation", path6.resolve(input.globalRoot)),
+    machineId: stableId("machine", `${os2.hostname()}\0${os2.platform()}\0${os2.arch()}`),
     projectId: input.projectId,
-    chronicleDirectory: path3.join(input.projectDir, "chronicle"),
+    chronicleDirectory: path6.join(input.projectDir, "chronicle"),
     day
   };
 }
@@ -540,130 +1362,12 @@ function stableId(prefix, value) {
 // src/chronicle/journal.ts
 import { randomUUID as randomUUID2 } from "node:crypto";
 import { createReadStream } from "node:fs";
-import * as fs2 from "node:fs/promises";
-import * as path5 from "node:path";
+import * as fs3 from "node:fs/promises";
+import * as path8 from "node:path";
 import { createInterface } from "node:readline";
 
-// 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/security/file-permissions.ts
+var SECRET_FILE_MODE = 384;
 
 // src/chronicle/event-hash.ts
 import { createHash as createHash3 } from "node:crypto";
@@ -685,14 +1389,14 @@ function chronicleEventHash(event) {
 }
 
 // src/chronicle/partition-filename.ts
-import * as path4 from "node:path";
+import * as path7 from "node:path";
 var PARTITION_FILE_PATTERN = /^(.*\.events)(?:\.(\d{5}))?\.jsonl$/;
 function partitionFamily(filePath) {
-  const match = PARTITION_FILE_PATTERN.exec(path4.basename(filePath));
-  return path4.join(path4.dirname(filePath), match?.[1] ?? path4.basename(filePath));
+  const match = PARTITION_FILE_PATTERN.exec(path7.basename(filePath));
+  return path7.join(path7.dirname(filePath), match?.[1] ?? path7.basename(filePath));
 }
 function partitionSequence(filePath) {
-  const match = PARTITION_FILE_PATTERN.exec(path4.basename(filePath));
+  const match = PARTITION_FILE_PATTERN.exec(path7.basename(filePath));
   return Number(match?.[2] ?? 0);
 }
 function comparePartitionPaths(left, right) {
@@ -722,7 +1426,16 @@ var ChronicleJournal = class {
   drainPromise;
   drainScheduled = false;
   drainTimer;
-  counters = { acceptedEvents: 0, persistedEvents: 0, rejectedEvents: 0, failedEvents: 0, batches: 0, maxObservedPending: 0, largestBatch: 0, partitionRolls: 0 };
+  counters = {
+    acceptedEvents: 0,
+    persistedEvents: 0,
+    rejectedEvents: 0,
+    failedEvents: 0,
+    batches: 0,
+    maxObservedPending: 0,
+    largestBatch: 0,
+    partitionRolls: 0
+  };
   lastBatchDurationMs;
   partitionIndex = 0;
   partitionStartedAt;
@@ -732,7 +1445,7 @@ var ChronicleJournal = class {
   lastHash = GENESIS_HASH;
   lastAutoPurgeAt = 0;
   constructor(options) {
-    this.basePath = path5.resolve(options.filePath);
+    this.basePath = path8.resolve(options.filePath);
     this.now = options.now ?? (() => /* @__PURE__ */ new Date());
     this.monotonicNow = options.monotonicNow ?? (() => process.hrtime.bigint());
     this.idFactory = options.idFactory ?? randomUUID2;
@@ -748,18 +1461,27 @@ var ChronicleJournal = class {
     return this.partitionIndex === 0 ? this.basePath : rotatedPath(this.basePath, this.partitionIndex);
   }
   stats() {
-    return { ...this.counters, pendingEvents: this.pending.length, ...this.lastBatchDurationMs !== void 0 ? { lastBatchDurationMs: this.lastBatchDurationMs } : {} };
+    return {
+      ...this.counters,
+      pendingEvents: this.pending.length,
+      ...this.lastBatchDurationMs !== void 0 ? { lastBatchDurationMs: this.lastBatchDurationMs } : {}
+    };
   }
   append(input) {
     if (this.pending.length >= this.maxPending) {
       this.counters.rejectedEvents++;
-      return Promise.reject(new Error(`Chronicle backpressure limit reached (${this.maxPending} pending events)`));
+      return Promise.reject(
+        new Error(`Chronicle backpressure limit reached (${this.maxPending} pending events)`)
+      );
     }
-    const promise = new Promise((resolve10, reject) => {
-      this.pending.push({ input, resolve: resolve10, reject });
+    const promise = new Promise((resolve12, reject) => {
+      this.pending.push({ input, resolve: resolve12, reject });
     });
     this.counters.acceptedEvents++;
-    this.counters.maxObservedPending = Math.max(this.counters.maxObservedPending, this.pending.length);
+    this.counters.maxObservedPending = Math.max(
+      this.counters.maxObservedPending,
+      this.pending.length
+    );
     this.scheduleDrain();
     return promise;
   }
@@ -785,7 +1507,8 @@ var ChronicleJournal = class {
     await this.flush();
     const files = await collectPartitions(this.basePath);
     const checkpointResult = await readRetentionCheckpoint(this.basePath);
-    if (checkpointResult.error) return { ok: false, entries: 0, brokenAt: 0, reason: checkpointResult.error };
+    if (checkpointResult.error)
+      return { ok: false, entries: 0, brokenAt: 0, reason: checkpointResult.error };
     return verifyPartitionFiles(files, checkpointResult.checkpoint);
   }
   async purge(options) {
@@ -795,15 +1518,18 @@ var ChronicleJournal = class {
     }
     await this.refreshStateFromDisk();
     const cutoff = Date.now() - options.retentionDays * 864e5;
-    const activePath = path5.resolve(this.path);
+    const activePath = path8.resolve(this.path);
     const errors = [];
     let dc = 0, db = 0, sc = 0;
     const suppliedFiles = options.files === void 0 ? await collectJournalPartitions(this.basePath) : [...options.files];
     const eligible = /* @__PURE__ */ new Set();
     for (const suppliedPath of new Set(suppliedFiles)) {
-      const file = path5.resolve(suppliedPath);
-      if (!isJournalPartition(file, path5.dirname(this.basePath), this.basePath)) {
-        errors.push({ file: suppliedPath, reason: "not a Chronicle journal partition in this journal directory" });
+      const file = path8.resolve(suppliedPath);
+      if (!isJournalPartition(file, path8.dirname(this.basePath), this.basePath)) {
+        errors.push({
+          file: suppliedPath,
+          reason: "not a Chronicle journal partition in this journal directory"
+        });
         sc++;
         continue;
       }
@@ -813,7 +1539,7 @@ var ChronicleJournal = class {
       }
       let mtimeMs;
       try {
-        const fileStat = await fs2.lstat(file);
+        const fileStat = await fs3.lstat(file);
         if (!fileStat.isFile()) {
           sc++;
           continue;
@@ -821,7 +1547,7 @@ var ChronicleJournal = class {
         mtimeMs = fileStat.mtimeMs;
       } catch (error) {
         if (isNotFound(error)) continue;
-        errors.push({ file, reason: errorMessage(error) });
+        errors.push({ file, reason: errorMessage2(error) });
         sc++;
         continue;
       }
@@ -847,18 +1573,22 @@ var ChronicleJournal = class {
           const familyBase = partitionFamilyBase(file);
           let deletedBytes;
           await withFileLock(familyBase, async () => {
-            const fileStat = await fs2.lstat(file);
+            const fileStat = await fs3.lstat(file);
             if (!fileStat.isFile() || fileStat.mtimeMs > cutoff) return;
             const checkpointResult = await readRetentionCheckpoint(familyBase);
             if (checkpointResult.error) throw new Error(checkpointResult.error);
             const checkpoint = checkpointResult.checkpoint;
-            const nextCheckpoint = await verifyRetainedPrefix(streamEntriesStrict(file), checkpoint);
-            if (!nextCheckpoint) throw new Error("partition does not extend the trusted Chronicle chain");
+            const nextCheckpoint = await verifyRetainedPrefix(
+              streamEntriesStrict(file),
+              checkpoint
+            );
+            if (!nextCheckpoint)
+              throw new Error("partition does not extend the trusted Chronicle chain");
             if (nextCheckpoint.sequence > (checkpoint?.sequence ?? 0)) {
               await writeRetentionCheckpoint(familyBase, nextCheckpoint);
             }
             deletedBytes = fileStat.size;
-            await fs2.unlink(file);
+            await fs3.unlink(file);
           });
           if (deletedBytes === void 0) {
             sc++;
@@ -867,13 +1597,19 @@ var ChronicleJournal = class {
           db += deletedBytes;
           dc++;
         } catch (error) {
-          errors.push({ file, reason: errorMessage(error) });
+          errors.push({ file, reason: errorMessage2(error) });
           sc++;
           break;
         }
       }
     }
-    return { deletedCount: dc, deletedBytes: db, skippedCount: sc, errors, ...options.dryRun ? { candidates } : {} };
+    return {
+      deletedCount: dc,
+      deletedBytes: db,
+      skippedCount: sc,
+      errors,
+      ...options.dryRun ? { candidates } : {}
+    };
   }
   async maybeAutoPurge() {
     if (this.retentionDays <= 0) return;
@@ -929,11 +1665,11 @@ var ChronicleJournal = class {
     if (!this.stateInitialized) return false;
     const nextPartition = rotatedPath(this.basePath, this.partitionIndex + 1);
     const [currentStat, nextExists] = await Promise.all([
-      fs2.stat(this.path).catch((error) => {
+      fs3.stat(this.path).catch((error) => {
         if (isNotFound(error)) return void 0;
         throw error;
       }),
-      fs2.access(nextPartition).then(
+      fs3.access(nextPartition).then(
         () => true,
         (error) => {
           if (isNotFound(error)) return false;
@@ -949,7 +1685,8 @@ var ChronicleJournal = class {
       this.rotate();
       return;
     }
-    if (Number.isFinite(this.maxPartitionSizeBytes) && this.partitionSizeBytes >= this.maxPartitionSizeBytes) this.rotate();
+    if (Number.isFinite(this.maxPartitionSizeBytes) && this.partitionSizeBytes >= this.maxPartitionSizeBytes)
+      this.rotate();
   }
   rotate() {
     this.partitionIndex++;
@@ -970,13 +1707,23 @@ var ChronicleJournal = class {
         let prev = this.lastSequence > 0 ? { sequence: this.lastSequence, hash: this.lastHash } : void 0;
         recorded = batch.map(({ input }) => {
           const instant = this.now().toISOString();
-          const uh = { ...input, occurredAt: input.occurredAt ?? instant, monotonicNs: input.monotonicNs ?? this.monotonicNow().toString(), schemaVersion: CHRONICLE_SCHEMA_VERSION, eventId: this.idFactory(), observedAt: instant, persistedAt: instant, sequence: (prev?.sequence ?? 0) + 1, previousHash: prev?.hash ?? GENESIS_HASH };
+          const uh = {
+            ...input,
+            occurredAt: input.occurredAt ?? instant,
+            monotonicNs: input.monotonicNs ?? this.monotonicNow().toString(),
+            schemaVersion: CHRONICLE_SCHEMA_VERSION,
+            eventId: this.idFactory(),
+            observedAt: instant,
+            persistedAt: instant,
+            sequence: (prev?.sequence ?? 0) + 1,
+            previousHash: prev?.hash ?? GENESIS_HASH
+          };
           const event = { ...uh, hash: hashValue(uh) };
           prev = event;
           return event;
         });
         const serialized = recorded.map((e) => JSON.stringify(e)).join("\n") + "\n";
-        await fs2.appendFile(cp, serialized, "utf8");
+        await fs3.appendFile(cp, serialized, { encoding: "utf8", mode: SECRET_FILE_MODE });
         this.partitionSizeBytes += Buffer.byteLength(serialized);
       });
       const last = recorded[recorded.length - 1];
@@ -999,33 +1746,34 @@ var ChronicleJournal = class {
   }
 };
 function rotatedPath(basePath, index) {
-  const dir = path5.dirname(basePath);
-  const ext = path5.extname(basePath);
-  const base = path5.basename(basePath, ext);
-  return path5.join(dir, `${base}.${String(index).padStart(5, "0")}${ext}`);
+  const dir = path8.dirname(basePath);
+  const ext = path8.extname(basePath);
+  const base = path8.basename(basePath, ext);
+  return path8.join(dir, `${base}.${String(index).padStart(5, "0")}${ext}`);
 }
 async function collectPartitions(basePath) {
-  const dir = path5.dirname(basePath);
-  const ext = path5.extname(basePath);
-  const base = path5.basename(basePath, ext);
+  const dir = path8.dirname(basePath);
+  const ext = path8.extname(basePath);
+  const base = path8.basename(basePath, ext);
   const pattern = new RegExp(`^${escapeRegex(base)}(?:\\.\\d{5})?${escapeRegex(ext)}$`);
   const result = [];
   try {
-    const entries = await fs2.readdir(dir, { withFileTypes: true });
-    for (const entry of entries) if (entry.isFile() && pattern.test(entry.name)) result.push(path5.join(dir, entry.name));
+    const entries = await fs3.readdir(dir, { withFileTypes: true });
+    for (const entry of entries)
+      if (entry.isFile() && pattern.test(entry.name)) result.push(path8.join(dir, entry.name));
   } catch {
   }
-  const baseFile = path5.join(dir, base + ext);
+  const baseFile = path8.join(dir, base + ext);
   const rotated = result.filter((file) => file !== baseFile).sort((left, right) => parseIndex(left, base, ext) - parseIndex(right, base, ext));
   return [baseFile, ...rotated];
 }
 async function collectJournalPartitions(basePath) {
-  const directory = path5.dirname(basePath);
+  const directory = path8.dirname(basePath);
   const result = [];
   try {
-    const entries = await fs2.readdir(directory, { withFileTypes: true });
+    const entries = await fs3.readdir(directory, { withFileTypes: true });
     for (const entry of entries) {
-      const file = path5.join(directory, entry.name);
+      const file = path8.join(directory, entry.name);
       if (entry.isFile() && isJournalPartition(file, directory, basePath)) result.push(file);
     }
   } catch {
@@ -1033,13 +1781,13 @@ async function collectJournalPartitions(basePath) {
   return result.sort(comparePartitionPaths);
 }
 function isJournalPartition(filePath, directory, basePath) {
-  if (path5.dirname(path5.resolve(filePath)) !== path5.resolve(directory)) return false;
-  const fileName = path5.basename(filePath);
+  if (path8.dirname(path8.resolve(filePath)) !== path8.resolve(directory)) return false;
+  const fileName = path8.basename(filePath);
   if (!basePath) return false;
-  const baseName = path5.basename(basePath);
+  const baseName = path8.basename(basePath);
   const dailyFamily = /^\d{4}-\d{2}-\d{2}\.events(?:\.\d{5})?\.jsonl$/;
   if (/^\d{4}-\d{2}-\d{2}\.events\.jsonl$/.test(baseName)) return dailyFamily.test(fileName);
-  return partitionFamilyBase(path5.resolve(filePath)) === partitionFamilyBase(path5.resolve(basePath));
+  return partitionFamilyBase(path8.resolve(filePath)) === partitionFamilyBase(path8.resolve(basePath));
 }
 function groupPartitionsByFamily(files) {
   const groups = /* @__PURE__ */ new Map();
@@ -1087,28 +1835,47 @@ async function verifyPartitionFiles(files, checkpoint) {
       for await (const entry of streamEntriesStrict(file)) {
         const { hash: recordedHash, ...content } = entry;
         if (entry.sequence <= checkpointSequence) {
-          if (hashValue(content) !== recordedHash) return { ok: false, entries, brokenAt: entries, reason: "entry hash mismatch" };
+          if (hashValue(content) !== recordedHash)
+            return { ok: false, entries, brokenAt: entries, reason: "entry hash mismatch" };
           if (coveredPrevious && entry.sequence !== coveredPrevious.sequence + 1) {
-            return { ok: false, entries, brokenAt: entries, reason: `sequence ${entry.sequence} is not ${coveredPrevious.sequence + 1}` };
+            return {
+              ok: false,
+              entries,
+              brokenAt: entries,
+              reason: `sequence ${entry.sequence} is not ${coveredPrevious.sequence + 1}`
+            };
           }
           if (coveredPrevious && entry.previousHash !== coveredPrevious.hash) {
             return { ok: false, entries, brokenAt: entries, reason: "previous hash mismatch" };
           }
           if (entry.sequence === checkpointSequence && recordedHash !== checkpoint?.hash) {
-            return { ok: false, entries, brokenAt: entries, reason: "retention checkpoint hash mismatch" };
+            return {
+              ok: false,
+              entries,
+              brokenAt: entries,
+              reason: "retention checkpoint hash mismatch"
+            };
           }
           coveredPrevious = entry;
           continue;
         }
         const index = entries++;
-        if (entry.sequence !== lastSequence + 1) return { ok: false, entries, brokenAt: index, reason: `sequence ${entry.sequence} is not ${lastSequence + 1}` };
-        if (entry.previousHash !== previousHash) return { ok: false, entries, brokenAt: index, reason: "previous hash mismatch" };
-        if (hashValue(content) !== recordedHash) return { ok: false, entries, brokenAt: index, reason: "entry hash mismatch" };
+        if (entry.sequence !== lastSequence + 1)
+          return {
+            ok: false,
+            entries,
+            brokenAt: index,
+            reason: `sequence ${entry.sequence} is not ${lastSequence + 1}`
+          };
+        if (entry.previousHash !== previousHash)
+          return { ok: false, entries, brokenAt: index, reason: "previous hash mismatch" };
+        if (hashValue(content) !== recordedHash)
+          return { ok: false, entries, brokenAt: index, reason: "entry hash mismatch" };
         previousHash = recordedHash;
         lastSequence = entry.sequence;
       }
     } catch (error) {
-      return { ok: false, entries, brokenAt: entries, reason: errorMessage(error) };
+      return { ok: false, entries, brokenAt: entries, reason: errorMessage2(error) };
     }
   }
   if (coveredPrevious && (coveredPrevious.sequence !== checkpointSequence || coveredPrevious.hash !== checkpoint?.hash)) {
@@ -1120,9 +1887,9 @@ async function readRetentionCheckpoint(basePath) {
   const checkpointPath = retentionCheckpointPath(basePath);
   let raw;
   try {
-    raw = await fs2.readFile(checkpointPath, "utf8");
+    raw = await fs3.readFile(checkpointPath, "utf8");
   } catch (error) {
-    return isNotFound(error) ? {} : { error: `cannot read retention checkpoint: ${errorMessage(error)}` };
+    return isNotFound(error) ? {} : { error: `cannot read retention checkpoint: ${errorMessage2(error)}` };
   }
   try {
     const parsed2 = JSON.parse(raw);
@@ -1136,18 +1903,20 @@ async function readRetentionCheckpoint(basePath) {
 }
 async function writeRetentionCheckpoint(basePath, checkpoint) {
   await atomicWrite(retentionCheckpointPath(basePath), `${JSON.stringify(checkpoint)}
-`, { mode: 384 });
+`, {
+    mode: 384
+  });
 }
 function isHash(value) {
   return typeof value === "string" && /^[a-f0-9]{64}$/.test(value);
 }
 function parseIndex(filePath, base, ext) {
-  const suffix = path5.basename(filePath).slice(base.length + 1, -ext.length);
+  const suffix = path8.basename(filePath).slice(base.length + 1, -ext.length);
   return suffix ? parseInt(suffix, 10) : 0;
 }
 function partitionIndex(filePath, basePath) {
-  const ext = path5.extname(basePath);
-  return parseIndex(filePath, path5.basename(basePath, ext), ext);
+  const ext = path8.extname(basePath);
+  return parseIndex(filePath, path8.basename(basePath, ext), ext);
 }
 function escapeRegex(text) {
   return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
@@ -1155,14 +1924,14 @@ function escapeRegex(text) {
 async function readLastEntryState(filePath) {
   let handle;
   try {
-    handle = await fs2.open(filePath, "r");
+    handle = await fs3.open(filePath, "r");
   } catch (error) {
     if (isNotFound(error)) return { size: 0 };
     throw error;
   }
   try {
-    const stat4 = await handle.stat();
-    const size = stat4.size;
+    const stat5 = await handle.stat();
+    const size = stat5.size;
     let position = size, suffix = "";
     while (position > 0) {
       const length = Math.min(65536, position);
@@ -1176,13 +1945,17 @@ async function readLastEntryState(filePath) {
         const trimmed = lines[i].trim();
         if (!trimmed) continue;
         try {
-          return { entry: JSON.parse(trimmed), size, birthtimeMs: stat4.birthtimeMs };
+          return {
+            entry: JSON.parse(trimmed),
+            size,
+            birthtimeMs: stat5.birthtimeMs
+          };
         } catch {
         }
       }
       suffix = lines[0] ?? "";
     }
-    return { size, birthtimeMs: stat4.birthtimeMs };
+    return { size, birthtimeMs: stat5.birthtimeMs };
   } finally {
     await handle.close();
   }
@@ -1200,7 +1973,7 @@ async function* streamEntriesStrict(filePath) {
       try {
         entry = JSON.parse(trimmed);
       } catch {
-        throw new Error(`invalid JSON at line ${lineNumber} in ${path5.basename(filePath)}`);
+        throw new Error(`invalid JSON at line ${lineNumber} in ${path8.basename(filePath)}`);
       }
       yield entry;
     }
@@ -1217,13 +1990,13 @@ async function readEntriesStrict(filePath) {
 function isNotFound(error) {
   return typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT";
 }
-function errorMessage(error) {
+function errorMessage2(error) {
   return error instanceof Error ? error.message : String(error);
 }
 
 // src/chronicle/legacy-journal-import.ts
-import * as fs3 from "node:fs/promises";
-import * as path6 from "node:path";
+import * as fs4 from "node:fs/promises";
+import * as path9 from "node:path";
 var ChronicleImportError = class extends Error {
   constructor(message, day, sequence) {
     super(message);
@@ -1237,7 +2010,7 @@ var ChronicleImportError = class extends Error {
 async function discoverFamilies(directory) {
   let entries;
   try {
-    entries = await fs3.readdir(directory);
+    entries = await fs4.readdir(directory);
   } catch {
     return [];
   }
@@ -1266,7 +2039,7 @@ async function importLegacyChronicleJournal(journal, directory) {
   let importedFamilies = 0;
   for (const familyBase of families) {
     const day = dayOfFamily(familyBase);
-    const basePath = path6.join(directory, `${familyBase}.jsonl`);
+    const basePath = path9.join(directory, `${familyBase}.jsonl`);
     let familyEvents = 0;
     if (journal.hasImportedDay(day)) continue;
     try {
@@ -1329,9 +2102,9 @@ async function importLegacyChronicleJournal(journal, directory) {
 }
 
 // src/chronicle/metrics-store.ts
-import * as fs6 from "node:fs/promises";
+import * as fs7 from "node:fs/promises";
 import { createRequire } from "node:module";
-import * as path9 from "node:path";
+import * as path12 from "node:path";
 
 // src/utils/sqlite-warning.ts
 var SQLITE_EXPERIMENTAL_WARNING_RE = /sqlite is an experimental feature/i;
@@ -1359,13 +2132,13 @@ function withSqliteExperimentalWarningSuppressed(run) {
 // src/chronicle/query.ts
 import { createHash as createHash4 } from "node:crypto";
 import { createReadStream as createReadStream2 } from "node:fs";
-import * as fs5 from "node:fs/promises";
-import * as path8 from "node:path";
+import * as fs6 from "node:fs/promises";
+import * as path11 from "node:path";
 import { createInterface as createInterface2 } from "node:readline";
 
 // src/chronicle/partition-range-cache.ts
-import * as fs4 from "node:fs/promises";
-import * as path7 from "node:path";
+import * as fs5 from "node:fs/promises";
+import * as path10 from "node:path";
 var CACHE_VERSION = 1;
 function isRange(value) {
   if (!value || typeof value !== "object") return false;
@@ -1375,20 +2148,20 @@ function isRange(value) {
 var ChroniclePartitionRangeCache = class {
   constructor(directory) {
     this.directory = directory;
-    this.cachePath = path7.join(directory, "range-cache.json");
+    this.cachePath = path10.join(directory, "range-cache.json");
   }
   directory;
   cachePath;
   entries;
   dirty = false;
   toKey(filePath) {
-    return path7.relative(this.directory, filePath).split(path7.sep).join("/");
+    return path10.relative(this.directory, filePath).split(path10.sep).join("/");
   }
   async load() {
     if (this.entries) return this.entries;
     const entries = /* @__PURE__ */ new Map();
     try {
-      const raw = await fs4.readFile(this.cachePath, "utf8");
+      const raw = await fs5.readFile(this.cachePath, "utf8");
       const parsed2 = JSON.parse(raw);
       if (parsed2.version === CACHE_VERSION && parsed2.entries && typeof parsed2.entries === "object") {
         for (const [key, range] of Object.entries(parsed2.entries)) {
@@ -1483,7 +2256,7 @@ var ChronicleQueryEngine = class _ChronicleQueryEngine {
   /** The one file (if any) that could still be actively appended to — never cache-checked or skipped. */
   activeFile;
   static async fromDirectory(directory, options) {
-    const resolved = path8.resolve(directory);
+    const resolved = path11.resolve(directory);
     const files = await findPartitions(resolved);
     const rangeCache2 = options?.rangeCache ?? new ChroniclePartitionRangeCache(resolved);
     return new _ChronicleQueryEngine(
@@ -1701,7 +2474,7 @@ async function* reverseLines(filePath, maxBytes) {
   const NEWLINE = 10;
   let handle;
   try {
-    handle = await fs5.open(filePath, "r");
+    handle = await fs6.open(filePath, "r");
   } catch {
     return;
   }
@@ -1875,12 +2648,12 @@ async function findPartitions(root) {
   const visit = async (directory) => {
     let entries;
     try {
-      entries = await fs5.readdir(directory, { withFileTypes: true });
+      entries = await fs6.readdir(directory, { withFileTypes: true });
     } catch {
       return;
     }
     for (const entry of entries) {
-      const full = path8.join(directory, entry.name);
+      const full = path11.join(directory, entry.name);
       if (entry.isDirectory()) await visit(full);
       else if (entry.isFile() && PARTITION_FILE_PATTERN.test(entry.name)) result.push(full);
     }
@@ -2045,7 +2818,7 @@ async function captureSnapshot(files) {
   return Promise.all(files.map(async (file) => {
     let size = 0;
     try {
-      size = (await fs5.stat(file)).size;
+      size = (await fs6.stat(file)).size;
     } catch {
     }
     return { file, id: fileId(file), size };
@@ -2058,7 +2831,7 @@ async function resolveSnapshotFiles(files, snapshot) {
     if (!file) throw new Error("Chronicle cursor snapshot has expired");
     let currentSize;
     try {
-      currentSize = (await fs5.stat(file)).size;
+      currentSize = (await fs6.stat(file)).size;
     } catch {
       throw new Error("Chronicle cursor snapshot has expired");
     }
@@ -2067,7 +2840,7 @@ async function resolveSnapshotFiles(files, snapshot) {
   }));
 }
 function fileId(file) {
-  return createHash4("sha256").update(path8.resolve(file), "utf8").digest("base64url");
+  return createHash4("sha256").update(path11.resolve(file), "utf8").digest("base64url");
 }
 function stableStringify2(value) {
   if (value === null || typeof value !== "object") return JSON.stringify(value);
@@ -2179,8 +2952,8 @@ var ChronicleMetricsStore = class _ChronicleMetricsStore {
   directory;
   dbPath;
   constructor(directory) {
-    this.directory = path9.resolve(directory);
-    this.dbPath = path9.join(this.directory, "metrics.db");
+    this.directory = path12.resolve(directory);
+    this.dbPath = path12.join(this.directory, "metrics.db");
     const Database = loadDatabaseSync();
     this.db = new Database(this.dbPath);
     this.db.exec("PRAGMA journal_mode = WAL");
@@ -2205,7 +2978,7 @@ var ChronicleMetricsStore = class _ChronicleMetricsStore {
       const files = await findChroniclePartitions(this.directory);
       const offsets = this.loadOffsets();
       for (const file of files) {
-        const key = normalizeKey(path9.relative(this.directory, file));
+        const key = normalizeKey(path12.relative(this.directory, file));
         const consumed = offsets.get(key) ?? 0;
         const ingested = await this.ingestFile(file, key, consumed, result);
         if (ingested) result.sourceFiles++;
@@ -2575,7 +3348,7 @@ var ChronicleMetricsStore = class _ChronicleMetricsStore {
   }
   pruneOffsets(existingFiles) {
     const keep = new Set(
-      existingFiles.map((file) => normalizeKey(path9.relative(this.directory, file)))
+      existingFiles.map((file) => normalizeKey(path12.relative(this.directory, file)))
     );
     for (const row of this.db.prepare("SELECT file FROM ingest_state").all()) {
       if (!keep.has(row.file))
@@ -2588,7 +3361,7 @@ var ChronicleMetricsStore = class _ChronicleMetricsStore {
   async ingestFile(file, key, consumed, result) {
     let handle;
     try {
-      handle = await fs6.open(file, "r");
+      handle = await fs7.open(file, "r");
     } catch {
       return false;
     }
@@ -2872,9 +3645,9 @@ function normalizePathKey(value) {
 
 // src/chronicle/project-server-endpoint.ts
 import { createHash as createHash5 } from "node:crypto";
-import * as fs7 from "node:fs";
-import * as os2 from "node:os";
-import * as path10 from "node:path";
+import * as fs8 from "node:fs";
+import * as os3 from "node:os";
+import * as path13 from "node:path";
 
 // src/utils/socket-path.ts
 import {
@@ -2894,37 +3667,37 @@ function encodeChronicleProjectServerMessage(message) {
 // src/chronicle/project-server-endpoint.ts
 var CHRONICLE_PROJECT_SERVER_METADATA_FILE = "server.json";
 function normalizedPath(value) {
-  const resolved = path10.resolve(value);
+  const resolved = path13.resolve(value);
   return process.platform === "win32" ? resolved.toLowerCase() : resolved;
 }
 function chronicleProjectServerKey(projectDir) {
-  return createHash5("sha256").update(normalizedPath(path10.join(projectDir, "chronicle"))).digest("hex").slice(0, 24);
+  return createHash5("sha256").update(normalizedPath(path13.join(projectDir, "chronicle"))).digest("hex").slice(0, 24);
 }
 function chronicleProjectServerEndpoint(projectDir) {
   const key = chronicleProjectServerKey(projectDir);
   if (process.platform === "win32") {
     return `\\\\.\\pipe\\wrongstack-chronicle-v${CHRONICLE_PROJECT_SERVER_PROTOCOL_VERSION}-${key}`;
   }
-  return path10.join(
-    os2.tmpdir(),
+  return path13.join(
+    os3.tmpdir(),
     `wsch-v${CHRONICLE_PROJECT_SERVER_PROTOCOL_VERSION}`,
     `${key}.sock`
   );
 }
 function chronicleProjectServerMetadataPath(projectDir) {
-  return path10.join(projectDir, "chronicle", CHRONICLE_PROJECT_SERVER_METADATA_FILE);
+  return path13.join(projectDir, "chronicle", CHRONICLE_PROJECT_SERVER_METADATA_FILE);
 }
 function ensureChronicleProjectServerSocketDirectory(endpoint2) {
   if (process.platform !== "win32") {
     assertUnixSocketPathWithinLimit(endpoint2, "chronicle");
-    fs7.mkdirSync(path10.dirname(endpoint2), { recursive: true, mode: 448 });
+    fs8.mkdirSync(path13.dirname(endpoint2), { recursive: true, mode: 448 });
   }
 }
 
 // src/chronicle/sqlite-journal.ts
 import { randomUUID as randomUUID3 } from "node:crypto";
 import { createRequire as createRequire2 } from "node:module";
-import * as path11 from "node:path";
+import * as path14 from "node:path";
 
 // src/chronicle/sqlite-query.ts
 var MAX_LIMIT = 1e4;
@@ -3207,7 +3980,7 @@ var ChronicleSqliteJournal = class {
   };
   lastBatchDurationMs;
   constructor(options) {
-    this.dbPath = path11.join(path11.resolve(options.directory), CHRONICLE_SQLITE_FILE);
+    this.dbPath = path14.join(path14.resolve(options.directory), CHRONICLE_SQLITE_FILE);
     this.now = options.now ?? (() => /* @__PURE__ */ new Date());
     this.monotonicNow = options.monotonicNow ?? (() => process.hrtime.bigint());
     this.idFactory = options.idFactory ?? (() => randomUUID3());
@@ -3673,22 +4446,27 @@ function parseArgs(argv) {
   }
   const retentionInput = Number(values.get("--retention-days"));
   return {
-    projectRoot: path12.resolve(values.get("--project-root")),
-    globalRoot: path12.resolve(values.get("--global-root")),
+    projectRoot: path15.resolve(values.get("--project-root")),
+    globalRoot: path15.resolve(values.get("--global-root")),
     projectId: values.get("--project-id"),
-    projectDir: path12.resolve(values.get("--project-dir")),
+    projectDir: path15.resolve(values.get("--project-dir")),
     workspaceId: values.get("--workspace-id"),
     retentionDays: Number.isFinite(retentionInput) && retentionInput >= 0 ? retentionInput : 30
   };
 }
 useDaemonPerfDefaults();
 var parsed = parseArgs(process.argv.slice(2));
-var chronicleDirectory = path12.join(parsed.projectDir, "chronicle");
+var chronicleDirectory = path15.join(parsed.projectDir, "chronicle");
 var endpoint = chronicleProjectServerEndpoint(parsed.projectDir);
 var metadataPath = chronicleProjectServerMetadataPath(parsed.projectDir);
 var idleInput = Number(process.env["WRONGSTACK_CHRONICLE_SERVER_IDLE_MS"]);
 var idleMs = Number.isFinite(idleInput) && idleInput >= 100 ? idleInput : DEFAULT_IDLE_MS;
 var startedAt = (/* @__PURE__ */ new Date()).toISOString();
+var authToken = randomBytes(16).toString("hex");
+var markMetadataWritten;
+var metadataWritten = new Promise((resolve12) => {
+  markMetadataWritten = resolve12;
+});
 var serverInfo = {
   protocolVersion: CHRONICLE_PROJECT_SERVER_PROTOCOL_VERSION,
   pid: process.pid,
@@ -3698,7 +4476,7 @@ var serverInfo = {
   endpoint,
   startedAt
 };
-process.title = `wrongstack-chronicle:${path12.basename(parsed.projectRoot)}`;
+process.title = `wrongstack-chronicle:${path15.basename(parsed.projectRoot)}`;
 var clients = /* @__PURE__ */ new Set();
 var journals = /* @__PURE__ */ new Map();
 var activeRequests = 0;
@@ -3712,6 +4490,17 @@ var metricsStore;
 var partitionRangeCache;
 var metricsRefresh;
 var pendingMutationHints = [];
+var stopMemoryWatchdog = startSharedHeapWatchdog({
+  collectStats: () => ({
+    surface: "chronicle-project-server",
+    clients: clients.size,
+    journals: journals.size,
+    activeRequests,
+    pendingMutationHints: pendingMutationHints.length,
+    queryGeneration,
+    cachedQuery: cachedQuery !== void 0
+  })
+});
 var MAX_OPEN_JOURNAL_DAYS = 2;
 function pruneJournals(currentDay) {
   if (journals.size <= MAX_OPEN_JOURNAL_DAYS) return;
@@ -3725,7 +4514,7 @@ function pruneJournals(currentDay) {
   }
 }
 function legacyPartitionPath(location) {
-  return path12.join(location.chronicleDirectory, `${location.day}.events.jsonl`);
+  return path15.join(location.chronicleDirectory, `${location.day}.events.jsonl`);
 }
 function useSqliteStore() {
   return process.env["WRONGSTACK_CHRONICLE_STORE"] !== "jsonl";
@@ -3734,7 +4523,7 @@ var sqliteStore;
 var quarantinedFamilies = [];
 function store() {
   sqliteStore ??= (async () => {
-    await fsp2.mkdir(chronicleDirectory, { recursive: true });
+    await fsp4.mkdir(chronicleDirectory, { recursive: true });
     const journal = new ChronicleSqliteJournal({ directory: chronicleDirectory });
     try {
       const result = await importLegacyChronicleJournal(journal, chronicleDirectory);
@@ -3959,6 +4748,16 @@ function send(state, message) {
   state.socket.write(encoded);
 }
 async function handleMessage(state, message) {
+  if (message.authToken !== authToken) {
+    send(state, {
+      type: "response",
+      id: message.id,
+      ok: false,
+      error: "Chronicle IPC request rejected: missing or invalid authToken. Reconnect to refresh metadata (server.json#authToken).",
+      errorName: "UnauthorizedChronicleRequest"
+    });
+    return;
+  }
   if (message.type === "shutdown") {
     send(state, { type: "response", id: message.id, ok: true, result: { stopped: true } });
     await stop(message.reason ?? "client request");
@@ -4012,24 +4811,15 @@ function scheduleIdleStop() {
   idleTimer.unref?.();
 }
 async function writeMetadata() {
-  await fsp2.mkdir(path12.dirname(metadataPath), { recursive: true });
-  const temporary = `${metadataPath}.${process.pid}.tmp`;
-  await fsp2.writeFile(temporary, `${JSON.stringify(serverInfo, null, 2)}
-`, {
-    encoding: "utf8",
-    mode: 384
-  });
-  try {
-    await fsp2.rename(temporary, metadataPath);
-  } catch {
-    await fsp2.rm(metadataPath, { force: true });
-    await fsp2.rename(temporary, metadataPath);
-  }
+  await fsp4.mkdir(path15.dirname(metadataPath), { recursive: true });
+  const metadata = { ...serverInfo, authToken };
+  await atomicWrite(metadataPath, `${JSON.stringify(metadata, null, 2)}
+`, { mode: 384 });
 }
 async function removeOwnedMetadata() {
   try {
-    const current = JSON.parse(await fsp2.readFile(metadataPath, "utf8"));
-    if (current.pid === process.pid) await fsp2.rm(metadataPath, { force: true });
+    const current = JSON.parse(await fsp4.readFile(metadataPath, "utf8"));
+    if (current.pid === process.pid) await fsp4.rm(metadataPath, { force: true });
   } catch {
   }
 }
@@ -4038,7 +4828,8 @@ async function stop(_reason) {
   stopping = true;
   if (idleTimer) clearTimeout(idleTimer);
   idleTimer = void 0;
-  await new Promise((resolve10) => server.close(() => resolve10()));
+  await removeOwnedMetadata();
+  await new Promise((resolve12) => server.close(() => resolve12()));
   for (const state of clients) state.socket.destroy();
   clients.clear();
   await watcher?.close().catch(() => {
@@ -4048,9 +4839,9 @@ async function stop(_reason) {
   });
   metricsStore?.close();
   metricsStore = void 0;
-  await removeOwnedMetadata();
-  if (process.platform !== "win32") await fsp2.rm(endpoint, { force: true }).catch(() => {
+  if (process.platform !== "win32") await fsp4.rm(endpoint, { force: true }).catch(() => {
   });
+  await stopMemoryWatchdog();
 }
 ensureChronicleProjectServerSocketDirectory(endpoint);
 var server = net.createServer((socket) => {
@@ -4063,7 +4854,9 @@ var server = net.createServer((socket) => {
   socket.setEncoding("utf8");
   const state = { socket, buffer: "" };
   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("close", () => {
     clients.delete(state);
@@ -4089,7 +4882,7 @@ server.on("error", (error) => {
     probe.once("error", () => {
       probe.destroy();
       try {
-        fs8.rmSync(endpoint, { force: true });
+        fs9.rmSync(endpoint, { force: true });
       } catch {
       }
       probingExistingEndpoint = false;
@@ -4102,11 +4895,11 @@ server.on("error", (error) => {
 server.on("listening", () => {
   if (process.platform !== "win32") {
     try {
-      fs8.chmodSync(endpoint, 384);
+      fs9.chmodSync(endpoint, 384);
     } catch {
     }
   }
-  void writeMetadata();
+  void writeMetadata().then(() => markMetadataWritten?.());
   void startChronicleFileObserver({
     projectRoot: parsed.projectRoot,
     journal: watcherSink,