@wrongstack/core 0.257.0 → 0.260.0

package/dist/storage/index.js

@@ -234,6 +234,40 @@ var DefaultSessionStore = class _DefaultSessionStore {
     this.events = opts.events;
     this.secretScrubber = opts.secretScrubber;
   }
+  // ── Storage event helpers ───────────────────────────────────────────────────
+  emitRead(sessionId, filePath, operation, outcome, durationMs, error) {
+    this.events?.emit("storage.read", {
+      sessionId,
+      store: "session",
+      filePath,
+      operation,
+      outcome,
+      durationMs,
+      ...error !== void 0 ? { error } : {}
+    });
+  }
+  emitWrite(sessionId, filePath, operation, outcome, durationMs, eventCount, error) {
+    this.events?.emit("storage.write", {
+      sessionId,
+      store: "session",
+      filePath,
+      operation,
+      outcome,
+      durationMs,
+      ...eventCount !== void 0 ? { eventCount } : {},
+      ...error !== void 0 ? { error } : {}
+    });
+  }
+  emitError(sessionId, filePath, operation, error, recoverable) {
+    this.events?.emit("storage.error", {
+      sessionId,
+      store: "session",
+      filePath,
+      operation,
+      error,
+      recoverable
+    });
+  }
   /** Absolute path to the session index file. */
   get indexFile() {
     return path13.join(this.dir, "_index.jsonl");
@@ -257,22 +291,26 @@ var DefaultSessionStore = class _DefaultSessionStore {
     const id = meta.id && meta.id.length > 0 ? meta.id : generateSessionId(startedAt, meta.model ?? meta.provider);
     const shardDir = await this.ensureShardDir(id);
     const file = path13.join(shardDir, `${path13.basename(id)}.jsonl`);
+    const t0 = Date.now();
     let handle;
     try {
       handle = await fsp.open(file, "a", 384);
     } catch (err) {
+      this.emitError(id, file, "create", err instanceof Error ? err.message : String(err), false);
       throw new Error(
         `Failed to open session file: ${err instanceof Error ? err.message : String(err)}`,
         { cause: err }
       );
     }
     try {
-      return new FileSessionWriter(id, handle, startedAt, meta, this.events, {
+      const writer = new FileSessionWriter(id, handle, startedAt, meta, this.events, {
         dir: shardDir,
         filePath: file,
         secretScrubber: this.secretScrubber,
         onClose: (s) => this.appendToIndex(s)
       });
+      this.emitWrite(id, file, "create", "success", Date.now() - t0);
+      return writer;
     } catch (err) {
       await handle.close().catch((e) => console.warn(JSON.stringify({
         level: "warn",
@@ -280,16 +318,19 @@ var DefaultSessionStore = class _DefaultSessionStore {
         message: e instanceof Error ? e.message : String(e),
         timestamp: (/* @__PURE__ */ new Date()).toISOString()
       })));
+      this.emitError(id, file, "create", err instanceof Error ? err.message : String(err), true);
       throw err;
     }
   }
   async resume(id) {
     const file = this.sessionPath(id, ".jsonl");
+    const t0 = Date.now();
     const data = await this.load(id);
     let handle;
     try {
       handle = await fsp.open(file, "a", 384);
     } catch (err) {
+      this.emitError(id, file, "resume", err instanceof Error ? err.message : String(err), false);
       throw new Error(
         `Failed to open session "${id}" for append: ${err instanceof Error ? err.message : String(err)}`,
         { cause: err }
@@ -317,6 +358,7 @@ var DefaultSessionStore = class _DefaultSessionStore {
           onClose: (s) => this.appendToIndex(s)
         }
       );
+      this.emitWrite(id, file, "resume", "success", Date.now() - t0);
       return { writer, data };
     } catch (err) {
       await handle.close().catch((e) => console.warn(JSON.stringify({
@@ -325,27 +367,39 @@ var DefaultSessionStore = class _DefaultSessionStore {
         message: e instanceof Error ? e.message : String(e),
         timestamp: (/* @__PURE__ */ new Date()).toISOString()
       })));
+      this.emitError(id, file, "resume", err instanceof Error ? err.message : String(err), true);
       throw err;
     }
   }
   async load(id) {
     const file = this.sessionPath(id, ".jsonl");
-    const raw = await fsp.readFile(file, "utf8");
-    const lines = raw.split("\n").filter((l) => l.trim());
-    const events = [];
-    for (const line of lines) {
-      try {
-        const parsed = JSON.parse(line);
-        if (parsed !== null && typeof parsed === "object" && typeof parsed.type === "string" && typeof parsed.ts === "string") {
-          events.push(parsed);
+    const t0 = Date.now();
+    let outcome = "success";
+    let errorMsg;
+    try {
+      const raw = await fsp.readFile(file, "utf8");
+      const lines = raw.split("\n").filter((l) => l.trim());
+      const events = [];
+      for (const line of lines) {
+        try {
+          const parsed = JSON.parse(line);
+          if (parsed !== null && typeof parsed === "object" && typeof parsed.type === "string" && typeof parsed.ts === "string") {
+            events.push(parsed);
+          }
+        } catch {
         }
-      } catch {
       }
+      const meta = this.metaFromEvents(id, events);
+      const { messages, usage } = this.replay(events, id);
+      const toolCallEnds = extractToolCallEnds(events);
+      return { metadata: meta, events, messages, usage, toolCallEnds };
+    } catch (err) {
+      outcome = "failure";
+      errorMsg = err instanceof Error ? err.message : String(err);
+      throw err;
+    } finally {
+      this.emitRead(id, file, "load", outcome, Date.now() - t0, errorMsg);
     }
-    const meta = this.metaFromEvents(id, events);
-    const { messages, usage } = this.replay(events, id);
-    const toolCallEnds = extractToolCallEnds(events);
-    return { metadata: meta, events, messages, usage, toolCallEnds };
   }
   async list(limit = 20) {
     try {
@@ -412,12 +466,22 @@ var DefaultSessionStore = class _DefaultSessionStore {
    * (keep latest per session), and rewrite. Atomic via temp+rename.
    */
   async compactIndex() {
-    const entries = await this.readIndex();
-    if (entries.length === 0) return;
-    const tmp = `${this.indexFile}.compact.tmp`;
-    const lines = entries.map((s) => JSON.stringify(s)).join("\n") + "\n";
-    await fsp.writeFile(tmp, lines, "utf8");
-    await fsp.rename(tmp, this.indexFile);
+    const t0 = Date.now();
+    let outcome = "success";
+    let errorMsg;
+    try {
+      const entries = await this.readIndex();
+      if (entries.length === 0) return;
+      const tmp = `${this.indexFile}.compact.tmp`;
+      const lines = entries.map((s) => JSON.stringify(s)).join("\n") + "\n";
+      await fsp.writeFile(tmp, lines, "utf8");
+      await fsp.rename(tmp, this.indexFile);
+    } catch (err) {
+      outcome = "failure";
+      errorMsg = err instanceof Error ? err.message : String(err);
+    } finally {
+      this.emitWrite("~compact~", this.indexFile, "compact", outcome, Date.now() - t0, void 0, errorMsg);
+    }
   }
   /**
    * Read the index file and return deduplicated session summaries.
@@ -493,22 +557,31 @@ var DefaultSessionStore = class _DefaultSessionStore {
   }
   async summaryFor(id) {
     const manifest = this.sessionPath(id, ".summary.json");
+    const t0 = Date.now();
+    let outcome = "success";
+    let errorMsg;
     try {
       const raw = await fsp.readFile(manifest, "utf8");
+      this.emitRead(id, manifest, "summary", "success", Date.now() - t0);
       return JSON.parse(raw);
     } catch {
       const full = this.sessionPath(id, ".jsonl");
       const stat5 = await fsp.stat(full);
       const summary = await this.summarize(id, stat5.mtime.toISOString());
       await atomicWrite(manifest, JSON.stringify(summary), { mode: 384 }).catch((err) => {
+        const msg = err instanceof Error ? err.message : String(err);
+        this.emitError(id, manifest, "summary_fallback", msg, true);
         console.warn(JSON.stringify({
           level: "warn",
           event: "session_store.manifest_write_failed",
           sessionId: id,
-          message: err instanceof Error ? err.message : String(err),
+          message: msg,
           timestamp: (/* @__PURE__ */ new Date()).toISOString()
         }));
       });
+      outcome = "failure";
+      errorMsg = "summary fallback \u2014 manifest rebuilt";
+      this.emitRead(id, manifest, "summary", outcome, Date.now() - t0, errorMsg);
       return summary;
     }
   }
@@ -774,7 +847,7 @@ function extractToolCallEnds(events) {
   return result;
 }
 var FileSessionWriter = class _FileSessionWriter {
-  constructor(id, handle, startedAt, meta, events, opts = {}) {
+  constructor(id, handle, startedAt, meta, events, opts = {}, traceId) {
     this.id = id;
     this.handle = handle;
     this.startedAt = startedAt;
@@ -793,6 +866,7 @@ var FileSessionWriter = class _FileSessionWriter {
       provider: meta.provider ?? "unknown",
       tokenTotal: 0
     };
+    this.traceId = traceId;
   }
   id;
   handle;
@@ -825,6 +899,8 @@ var FileSessionWriter = class _FileSessionWriter {
   lastAppendWarnAt = 0;
   secretScrubber;
   onCloseCb;
+  /** Implements SessionWriter.traceId — propagated from ContextInit.traceId. */
+  traceId;
   // ── Write buffer — batches events to reduce per-event disk I/O ─────────
   //
   // Every append() pushes the scrubbed event into an in-memory buffer instead
@@ -978,9 +1054,14 @@ var FileSessionWriter = class _FileSessionWriter {
     const eventCount = this.writeBuffer.length;
     const batch = this.writeBuffer.map((e) => JSON.stringify(e)).join("\n") + "\n";
     this.writeBuffer = [];
+    const t0 = Date.now();
+    let outcome = "success";
+    let errorMsg;
     try {
       await this.enqueueWrite(batch);
     } catch (err) {
+      outcome = "failure";
+      errorMsg = err instanceof Error ? err.message : String(err);
       this.appendFailCount += eventCount;
       const now = Date.now();
       if (now - this.lastAppendWarnAt > 5e3) {
@@ -994,6 +1075,18 @@ var FileSessionWriter = class _FileSessionWriter {
         this.lastAppendWarnAt = now;
         this.appendFailCount = 0;
       }
+    } finally {
+      this.events?.emit("storage.write", {
+        sessionId: this.id,
+        store: "session",
+        filePath: this.filePath,
+        operation: "flush",
+        outcome,
+        durationMs: Date.now() - t0,
+        ...errorMsg !== void 0 ? { error: errorMsg } : {},
+        ...eventCount !== void 0 ? { eventCount } : {},
+        ...this.traceId !== void 0 ? { traceId: this.traceId } : {}
+      });
     }
   }
   observeForSummary(event) {
@@ -1059,14 +1152,46 @@ var FileSessionWriter = class _FileSessionWriter {
       outcome: this.outcome ?? "completed"
     };
     if (this.manifestFile) {
+      const t0 = Date.now();
+      let outcome = "success";
+      let errorMsg;
       try {
         await atomicWrite(this.manifestFile, JSON.stringify(this.summary), { mode: 384 });
-      } catch {
+      } catch (err) {
+        outcome = "failure";
+        errorMsg = err instanceof Error ? err.message : String(err);
+      } finally {
+        this.events?.emit("storage.write", {
+          sessionId: this.id,
+          store: "session",
+          filePath: this.manifestFile,
+          operation: "close",
+          outcome,
+          durationMs: Date.now() - t0,
+          ...errorMsg !== void 0 ? { error: errorMsg } : {},
+          ...this.traceId !== void 0 ? { traceId: this.traceId } : {}
+        });
       }
     }
+    const idxT0 = Date.now();
+    let idxOutcome = "success";
+    let idxError;
     try {
       await this.onCloseCb?.(this.summary);
-    } catch {
+    } catch (err) {
+      idxOutcome = "failure";
+      idxError = err instanceof Error ? err.message : String(err);
+    } finally {
+      this.events?.emit("storage.write", {
+        sessionId: this.summary.id,
+        store: "session",
+        filePath: this.filePath,
+        operation: "index_append",
+        outcome: idxOutcome,
+        durationMs: Date.now() - idxT0,
+        ...idxError !== void 0 ? { error: idxError } : {},
+        ...this.traceId !== void 0 ? { traceId: this.traceId } : {}
+      });
     }
     try {
       await this.handle.close();
@@ -1225,23 +1350,81 @@ function userInputTitle(content) {
 }
 var QueueStore = class {
   file;
+  // Use `| undefined` (not `?`) so exactOptionalPropertyTypes doesn't
+  // reject assigning an optional constructor parameter to these fields.
+  events;
+  traceId;
   constructor(opts) {
     this.file = path13.join(opts.dir, "queue.json");
+    this.events = opts.events;
+    this.traceId = opts.traceId;
   }
   async write(items) {
+    const t0 = Date.now();
     if (items.length === 0) {
       await this.clear();
       return;
     }
-    await atomicWrite(this.file, JSON.stringify(items), { mode: 384 });
+    try {
+      await atomicWrite(this.file, JSON.stringify(items), { mode: 384 });
+      this.events?.emit("storage.write", {
+        sessionId: this.traceId ?? "~boot~",
+        store: "queue",
+        filePath: this.file,
+        operation: "write",
+        outcome: "success",
+        durationMs: Date.now() - t0,
+        ...this.traceId !== void 0 && { traceId: this.traceId }
+      });
+    } catch (err) {
+      this.events?.emit("storage.error", {
+        sessionId: this.traceId ?? "~boot~",
+        store: "queue",
+        filePath: this.file,
+        operation: "write",
+        outcome: "failure",
+        error: err instanceof Error ? err.message : String(err),
+        recoverable: false,
+        ...this.traceId !== void 0 && { traceId: this.traceId }
+      });
+      console.warn(JSON.stringify({
+        level: "warn",
+        event: "queue_store.write_failed",
+        path: this.file,
+        message: err instanceof Error ? err.message : String(err),
+        timestamp: (/* @__PURE__ */ new Date()).toISOString()
+      }));
+    }
   }
   async read() {
+    const t0 = Date.now();
     let raw;
     try {
       raw = await fsp.readFile(this.file, "utf8");
     } catch (err) {
       const code = err.code;
-      if (code === "ENOENT") return [];
+      if (code === "ENOENT") {
+        this.events?.emit("storage.read", {
+          sessionId: this.traceId ?? "~boot~",
+          store: "queue",
+          filePath: this.file,
+          operation: "read",
+          outcome: "success",
+          durationMs: Date.now() - t0,
+          ...this.traceId !== void 0 && { traceId: this.traceId }
+        });
+        return [];
+      }
+      this.events?.emit("storage.error", {
+        sessionId: this.traceId ?? "~boot~",
+        store: "queue",
+        filePath: this.file,
+        operation: "read",
+        outcome: "failure",
+        error: err instanceof Error ? err.message : String(err),
+        recoverable: true,
+        ...this.traceId !== void 0 && { traceId: this.traceId }
+      });
       console.warn(JSON.stringify({
         level: "warn",
         event: "queue_store.read_failed",
@@ -1255,9 +1438,40 @@ var QueueStore = class {
     try {
       parsed = JSON.parse(raw);
     } catch {
+      this.events?.emit("storage.read", {
+        sessionId: this.traceId ?? "~boot~",
+        store: "queue",
+        filePath: this.file,
+        operation: "read",
+        outcome: "failure",
+        durationMs: Date.now() - t0,
+        error: "parse_failed",
+        ...this.traceId !== void 0 && { traceId: this.traceId }
+      });
       return [];
     }
-    if (!Array.isArray(parsed)) return [];
+    if (!Array.isArray(parsed)) {
+      this.events?.emit("storage.read", {
+        sessionId: this.traceId ?? "~boot~",
+        store: "queue",
+        filePath: this.file,
+        operation: "read",
+        outcome: "failure",
+        durationMs: Date.now() - t0,
+        error: "invalid_schema",
+        ...this.traceId !== void 0 && { traceId: this.traceId }
+      });
+      return [];
+    }
+    this.events?.emit("storage.read", {
+      sessionId: this.traceId ?? "~boot~",
+      store: "queue",
+      filePath: this.file,
+      operation: "read",
+      outcome: "success",
+      durationMs: Date.now() - t0,
+      ...this.traceId !== void 0 && { traceId: this.traceId }
+    });
     const out = [];
     for (const v of parsed) {
       if (isPersistedQueueItem(v)) out.push(v);
@@ -1265,11 +1479,31 @@ var QueueStore = class {
     return out;
   }
   async clear() {
+    const t0 = Date.now();
     try {
       await fsp.unlink(this.file);
+      this.events?.emit("storage.write", {
+        sessionId: this.traceId ?? "~boot~",
+        store: "queue",
+        filePath: this.file,
+        operation: "clear",
+        outcome: "success",
+        durationMs: Date.now() - t0,
+        ...this.traceId !== void 0 && { traceId: this.traceId }
+      });
     } catch (err) {
       const code = err.code;
       if (code === "ENOENT") return;
+      this.events?.emit("storage.error", {
+        sessionId: this.traceId ?? "~boot~",
+        store: "queue",
+        filePath: this.file,
+        operation: "clear",
+        outcome: "failure",
+        error: err instanceof Error ? err.message : String(err),
+        recoverable: true,
+        ...this.traceId !== void 0 && { traceId: this.traceId }
+      });
       console.warn(JSON.stringify({
         level: "warn",
         event: "queue_store.clear_failed",
@@ -1652,6 +1886,7 @@ var MAX_BYTES_TOTAL = 32e3;
 var DefaultMemoryStore = class {
   files;
   events;
+  traceId;
   backend;
   /**
    * Per-scope serialization queue. `remember` / `forget` / `consolidate` /
@@ -1717,15 +1952,70 @@ var DefaultMemoryStore = class {
       if (writeErr) {
         parts.push(`> \u26A0\uFE0F Memory write error (${labelOf(scope)}): ${writeErr.message}`);
       }
-      const body = await this.backend.readAll(scope, this.files[scope]);
-      if (body.trim()) parts.push(`## ${labelOf(scope)}
+      const t0 = Date.now();
+      const filePath = this.files[scope];
+      try {
+        const body = await this.backend.readAll(scope, filePath);
+        const dur = Date.now() - t0;
+        this.events?.emit("storage.read", {
+          sessionId: "~memory~",
+          store: "memory",
+          filePath,
+          operation: "readAll",
+          outcome: "success",
+          durationMs: dur,
+          ...this.traceId !== void 0 && { traceId: this.traceId }
+        });
+        if (body.trim()) parts.push(`## ${labelOf(scope)}
 
 ${body.trim()}`);
+      } catch (err) {
+        const dur = Date.now() - t0;
+        this.events?.emit("storage.read", {
+          sessionId: "~memory~",
+          store: "memory",
+          filePath,
+          operation: "readAll",
+          outcome: "failure",
+          durationMs: dur,
+          error: err instanceof Error ? err.message : String(err),
+          ...this.traceId !== void 0 && { traceId: this.traceId }
+        });
+        throw err;
+      }
     }
     return parts.join("\n\n");
   }
   async read(scope) {
-    return this.backend.readAll(scope, this.files[scope]);
+    const t0 = Date.now();
+    const filePath = this.files[scope];
+    try {
+      const body = await this.backend.readAll(scope, filePath);
+      const dur = Date.now() - t0;
+      this.events?.emit("storage.read", {
+        sessionId: "~memory~",
+        store: "memory",
+        filePath,
+        operation: "read",
+        outcome: "success",
+        durationMs: dur,
+        ...this.traceId !== void 0 && { traceId: this.traceId }
+      });
+      return body;
+    } catch (err) {
+      const dur = Date.now() - t0;
+      this.events?.emit("storage.read", {
+        sessionId: "~memory~",
+        store: "memory",
+        filePath,
+        operation: "read",
+        outcome: "failure",
+        durationMs: dur,
+        error: err instanceof Error ? err.message : String(err),
+        ...this.traceId !== void 0 && { traceId: this.traceId }
+      });
+      throw err;
+    }
   }
   /**
    * List entries from a scope, newest first. Delegates to the backend
@@ -1751,7 +2041,34 @@ ${body.trim()}`);
     const ts = (/* @__PURE__ */ new Date()).toISOString();
     return this.runSerialized(scope, async () => {
       const entry = { scope, text, ts, ...metadata };
-      await this.backend.remember(scope, entry, this.files[scope]);
+      const filePath = this.files[scope];
+      const t0 = Date.now();
+      try {
+        await this.backend.remember(scope, entry, filePath);
+        const dur = Date.now() - t0;
+        this.events?.emit("storage.write", {
+          sessionId: "~memory~",
+          store: "memory",
+          filePath,
+          operation: "remember",
+          outcome: "success",
+          durationMs: dur,
+          ...this.traceId !== void 0 && { traceId: this.traceId }
+        });
+      } catch (err) {
+        const dur = Date.now() - t0;
+        this.events?.emit("storage.write", {
+          sessionId: "~memory~",
+          store: "memory",
+          filePath,
+          operation: "remember",
+          outcome: "failure",
+          durationMs: dur,
+          error: err instanceof Error ? err.message : String(err),
+          ...this.traceId !== void 0 && { traceId: this.traceId }
+        });
+        throw err;
+      }
       const raw = await this.backend.readAll(scope, this.files[scope]);
       if (Buffer.byteLength(raw, "utf8") > MAX_BYTES_TOTAL) {
         const removed = await this.backend.consolidate(scope, this.files[scope]);
@@ -1879,7 +2196,35 @@ ${body.trim()}`);
   }
   async forget(query, scope = "project-memory") {
     return this.runSerialized(scope, async () => {
-      const removed = await this.backend.forget(scope, query, this.files[scope]);
+      const filePath = this.files[scope];
+      const t0 = Date.now();
+      let removed = 0;
+      try {
+        removed = await this.backend.forget(scope, query, filePath);
+        const dur = Date.now() - t0;
+        this.events?.emit("storage.write", {
+          sessionId: "~memory~",
+          store: "memory",
+          filePath,
+          operation: "forget",
+          outcome: "success",
+          durationMs: dur,
+          ...this.traceId !== void 0 && { traceId: this.traceId }
+        });
+      } catch (err) {
+        const dur = Date.now() - t0;
+        this.events?.emit("storage.write", {
+          sessionId: "~memory~",
+          store: "memory",
+          filePath,
+          operation: "forget",
+          outcome: "failure",
+          durationMs: dur,
+          error: err instanceof Error ? err.message : String(err),
+          ...this.traceId !== void 0 && { traceId: this.traceId }
+        });
+        throw err;
+      }
       if (removed > 0) {
         this.events?.emit("memory.forgotten", {
           scope,
@@ -1893,7 +2238,35 @@ ${body.trim()}`);
   }
   async consolidate(scope) {
     return this.runSerialized(scope, async () => {
-      const removed = await this.backend.consolidate(scope, this.files[scope]);
+      const filePath = this.files[scope];
+      const t0 = Date.now();
+      let removed = 0;
+      try {
+        removed = await this.backend.consolidate(scope, filePath);
+        const dur = Date.now() - t0;
+        this.events?.emit("storage.write", {
+          sessionId: "~memory~",
+          store: "memory",
+          filePath,
+          operation: "consolidate",
+          outcome: "success",
+          durationMs: dur,
+          ...this.traceId !== void 0 && { traceId: this.traceId }
+        });
+      } catch (err) {
+        const dur = Date.now() - t0;
+        this.events?.emit("storage.write", {
+          sessionId: "~memory~",
+          store: "memory",
+          filePath,
+          operation: "consolidate",
+          outcome: "failure",
+          durationMs: dur,
+          error: err instanceof Error ? err.message : String(err),
+          ...this.traceId !== void 0 && { traceId: this.traceId }
+        });
+        throw err;
+      }
       if (removed > 0) {
         this.events?.emit("memory.consolidated", {
           scope,
@@ -1906,7 +2279,34 @@ ${body.trim()}`);
   async clear(scope) {
     if (scope) {
       await this.runSerialized(scope, async () => {
-        await this.backend.clear(scope, this.files[scope]);
+        const filePath = this.files[scope];
+        const t0 = Date.now();
+        try {
+          await this.backend.clear(scope, filePath);
+          const dur = Date.now() - t0;
+          this.events?.emit("storage.write", {
+            sessionId: "~memory~",
+            store: "memory",
+            filePath,
+            operation: "clear",
+            outcome: "success",
+            durationMs: dur,
+            ...this.traceId !== void 0 && { traceId: this.traceId }
+          });
+        } catch (err) {
+          const dur = Date.now() - t0;
+          this.events?.emit("storage.write", {
+            sessionId: "~memory~",
+            store: "memory",
+            filePath,
+            operation: "clear",
+            outcome: "failure",
+            durationMs: dur,
+            error: err instanceof Error ? err.message : String(err),
+            ...this.traceId !== void 0 && { traceId: this.traceId }
+          });
+          throw err;
+        }
         this.events?.emit("memory.cleared", { scope });
         await this.mirrorBackup(scope);
       });
@@ -1914,15 +2314,54 @@ ${body.trim()}`);
     }
     await Promise.all(
       ["project-agents", "project-memory", "user-memory"].map(
-        (s) => this.runSerialized(s, async () => {
-          await this.backend.clear(s, this.files[s]);
+        async (s) => this.runSerialized(s, async () => {
+          const filePath = this.files[s];
+          const t0 = Date.now();
+          try {
+            await this.backend.clear(s, filePath);
+            const dur = Date.now() - t0;
+            this.events?.emit("storage.write", {
+              sessionId: "~memory~",
+              store: "memory",
+              filePath,
+              operation: "clear",
+              outcome: "success",
+              durationMs: dur,
+              ...this.traceId !== void 0 && { traceId: this.traceId }
+            });
+          } catch (err) {
+            const dur = Date.now() - t0;
+            this.events?.emit("storage.write", {
+              sessionId: "~memory~",
+              store: "memory",
+              filePath,
+              operation: "clear",
+              outcome: "failure",
+              durationMs: dur,
+              error: err instanceof Error ? err.message : String(err),
+              ...this.traceId !== void 0 && { traceId: this.traceId }
+            });
+            throw err;
+          }
           this.events?.emit("memory.cleared", { scope: s });
           await this.mirrorBackup(s);
         })
       )
     );
   }
-  /** Mirror current memory content to the persistent backup directory. */
+  /**
+   * Return a new MemoryStore proxy that carries `traceId` on every storage
+   * event. The original store is left unchanged — callers that need a
+   * trace-decorated view (e.g. session-run tools) receive the proxy while
+   * the singleton remains trace-free for boot-time use.
+   *
+   * The proxy implements the full `MemoryStore` interface; all other
+   * properties (backend, etc.) are delegated to the original store.
+   */
+  withTraceId(traceId) {
+    this.traceId = traceId;
+    return this;
+  }
   async mirrorBackup(scope) {
     if (!this.persistBackup || scope === "project-agents") return;
     try {
@@ -2673,6 +3112,13 @@ var DEFAULT_SESSION_LOGGING_CONFIG = Object.freeze({
 });
 
 // src/storage/config-loader.ts
+function storageErrorString(err) {
+  if (err instanceof Error) {
+    const code = err.code;
+    return code ? `${code}: ${err.message}` : err.message;
+  }
+  return String(err);
+}
 var BEHAVIOR_DEFAULTS = {
   version: 1,
   context: {
@@ -2775,11 +3221,15 @@ var DefaultConfigLoader = class {
   strict;
   vault;
   extraSources;
+  events;
+  traceId;
   constructor(opts) {
     this.paths = opts.paths;
     this.strict = opts.strict ?? false;
     this.vault = opts.vault;
     this.extraSources = opts.sources ?? [];
+    this.events = opts.events;
+    this.traceId = opts.traceId;
   }
   async load(opts = {}) {
     let cfg = { ...BEHAVIOR_DEFAULTS };
@@ -2856,7 +3306,33 @@ var DefaultConfigLoader = class {
     if (this.vault && toWrite.githubToken && !toWrite.githubToken.startsWith("enc:")) {
       toWrite = { ...toWrite, githubToken: this.vault.encrypt(toWrite.githubToken) };
     }
-    await atomicWrite(this.paths.syncConfig, JSON.stringify(toWrite, null, 2), { mode: 384 });
+    const fp = this.paths.syncConfig;
+    const t0 = Date.now();
+    try {
+      await atomicWrite(fp, JSON.stringify(toWrite, null, 2), { mode: 384 });
+      this.events?.emit("storage.write", {
+        sessionId: "~config~",
+        store: "config",
+        filePath: fp,
+        operation: "persist_sync",
+        outcome: "success",
+        durationMs: Date.now() - t0,
+        ...this.traceId !== void 0 ? { traceId: this.traceId } : {}
+      });
+    } catch (err) {
+      this.events?.emit("storage.error", {
+        sessionId: "~config~",
+        store: "config",
+        filePath: fp,
+        operation: "persist_sync",
+        outcome: "failure",
+        error: storageErrorString(err),
+        recoverable: false,
+        durationMs: Date.now() - t0,
+        ...this.traceId !== void 0 ? { traceId: this.traceId } : {}
+      });
+      throw err;
+    }
   }
   /**
    * Read ~/.wrongstack/sync.json (encrypted GitHub token storage) and decrypt
@@ -2865,17 +3341,60 @@ var DefaultConfigLoader = class {
    * isolated — it should never be part of project-local or env-driven config.
    */
   async loadSyncConfig() {
+    const fp = this.paths.syncConfig;
+    const t0 = Date.now();
     try {
-      const raw = await fsp.readFile(this.paths.syncConfig, "utf8");
+      const raw = await fsp.readFile(fp, "utf8");
       const parsed = safeParse(raw);
-      if (!parsed.ok || !parsed.value) return null;
+      if (!parsed.ok || !parsed.value) {
+        this.events?.emit("storage.read", {
+          sessionId: "~config~",
+          store: "config",
+          filePath: fp,
+          operation: "load_sync",
+          outcome: "failure",
+          durationMs: Date.now() - t0,
+          error: "parse error or empty file",
+          ...this.traceId !== void 0 ? { traceId: this.traceId } : {}
+        });
+        return null;
+      }
       if (this.vault) {
         const decrypted = decryptConfigSecrets({ sync: parsed.value }, this.vault);
-        return decrypted.sync ?? null;
+        const result = decrypted.sync ?? null;
+        this.events?.emit("storage.read", {
+          sessionId: "~config~",
+          store: "config",
+          filePath: fp,
+          operation: "load_sync",
+          outcome: "success",
+          durationMs: Date.now() - t0,
+          ...this.traceId !== void 0 ? { traceId: this.traceId } : {}
+        });
+        return result;
       }
+      this.events?.emit("storage.read", {
+        sessionId: "~config~",
+        store: "config",
+        filePath: fp,
+        operation: "load_sync",
+        outcome: "success",
+        durationMs: Date.now() - t0,
+        ...this.traceId !== void 0 ? { traceId: this.traceId } : {}
+      });
       return parsed.value;
     } catch (err) {
       if (err.code === "ENOENT") return null;
+      this.events?.emit("storage.read", {
+        sessionId: "~config~",
+        store: "config",
+        filePath: fp,
+        operation: "load_sync",
+        outcome: "failure",
+        durationMs: Date.now() - t0,
+        error: storageErrorString(err),
+        ...this.traceId !== void 0 ? { traceId: this.traceId } : {}
+      });
       console.warn(JSON.stringify({
         level: "warn",
         event: "config.sync_load_failed",
@@ -2887,10 +3406,21 @@ var DefaultConfigLoader = class {
   }
   async readJson(file) {
     let raw;
+    const t0 = Date.now();
     try {
       raw = await fsp.readFile(file, "utf8");
     } catch (err) {
       if (err.code !== "ENOENT") {
+        this.events?.emit("storage.read", {
+          sessionId: "~config~",
+          store: "config",
+          filePath: file,
+          operation: "read_json",
+          outcome: "failure",
+          durationMs: Date.now() - t0,
+          error: storageErrorString(err),
+          ...this.traceId !== void 0 ? { traceId: this.traceId } : {}
+        });
         console.warn(JSON.stringify({
           level: "warn",
           event: "config.read_failed",
@@ -2903,6 +3433,16 @@ var DefaultConfigLoader = class {
     }
     const parsed = safeParse(raw);
     if (!parsed.ok || !parsed.value) {
+      this.events?.emit("storage.read", {
+        sessionId: "~config~",
+        store: "config",
+        filePath: file,
+        operation: "read_json",
+        outcome: "failure",
+        durationMs: Date.now() - t0,
+        error: "parse error or empty file",
+        ...this.traceId !== void 0 ? { traceId: this.traceId } : {}
+      });
       console.warn(JSON.stringify({
         level: "warn",
         event: "config.parse_failed",
@@ -3501,20 +4041,53 @@ var MAX_TEXT_LENGTH = 2e3;
 var MAX_ANNOTATIONS = 1e3;
 var AnnotationsStore = class {
   dir;
+  events;
+  traceId;
   /** Per-session write queue. Created lazily on first add. */
   writeChains = /* @__PURE__ */ new Map();
   constructor(opts) {
     this.dir = opts.dir;
+    this.events = opts.events;
+    this.traceId = opts.traceId;
   }
   // ── Reads ──────────────────────────────────────────────────────────────
   /**
    * Return all annotations for `sessionId` in insertion order
    * (oldest first). Returns an empty array when no file exists
-   * yet (the normal case for a fresh session).
+   * yet (the normal case for a fresh session) and also degrades
+   * gracefully to `[]` on a read error (permissions, corruption) —
+   * the failure is still surfaced via a `storage.read` event so it
+   * never silently hides I/O problems from observers.
    */
   async list(sessionId) {
-    const file = await this.readFile(sessionId);
-    return file ? file.annotations : [];
+    const t0 = Date.now();
+    const fp = this.filePath(sessionId);
+    try {
+      const file = await this.readFile(sessionId);
+      const durationMs = Date.now() - t0;
+      this.events?.emit("storage.read", {
+        sessionId,
+        store: "annotations",
+        filePath: fp,
+        operation: "list",
+        outcome: "success",
+        durationMs,
+        ...this.traceId !== void 0 ? { traceId: this.traceId } : {}
+      });
+      return file ? file.annotations : [];
+    } catch (err) {
+      this.events?.emit("storage.read", {
+        sessionId,
+        store: "annotations",
+        filePath: fp,
+        operation: "list",
+        outcome: "failure",
+        durationMs: Date.now() - t0,
+        error: err instanceof Error ? err.message : String(err),
+        ...this.traceId !== void 0 ? { traceId: this.traceId } : {}
+      });
+      return [];
+    }
   }
   /**
    * Convenience: only unresolved annotations, newest first — the
@@ -3566,25 +4139,62 @@ var AnnotationsStore = class {
       createdAt: (/* @__PURE__ */ new Date()).toISOString(),
       resolved: false
     };
-    await this.enqueue(input.sessionId, async () => {
-      await withFileLock(this.filePath(input.sessionId), async () => {
-        const all = await this.list(input.sessionId);
-        all.push(annotation);
-        if (all.length > MAX_ANNOTATIONS) {
-          const sorted = all.map((a, i) => ({ a, i })).sort((x, y) => {
-            if (x.a.resolved !== y.a.resolved) return x.a.resolved ? 1 : -1;
-            return x.a.createdAt.localeCompare(y.a.createdAt);
-          });
-          const evictCount = all.length - MAX_ANNOTATIONS;
-          const toEvict = new Set(sorted.slice(0, evictCount).map((s) => s.a.id));
-          const kept = all.filter((a) => !toEvict.has(a.id));
-          await this.writeFile(input.sessionId, { version: FILE_VERSION, annotations: kept });
-        } else {
-          await this.writeFile(input.sessionId, { version: FILE_VERSION, annotations: all });
-        }
+    const fp = this.filePath(input.sessionId);
+    const t0 = Date.now();
+    try {
+      await this.enqueue(input.sessionId, async () => {
+        await withFileLock(fp, async () => {
+          const all = await this.list(input.sessionId);
+          all.push(annotation);
+          if (all.length > MAX_ANNOTATIONS) {
+            const sorted = all.map((a, i) => ({ a, i })).sort((x, y) => {
+              if (x.a.resolved !== y.a.resolved) return x.a.resolved ? 1 : -1;
+              return x.a.createdAt.localeCompare(y.a.createdAt);
+            });
+            const evictCount = all.length - MAX_ANNOTATIONS;
+            const toEvict = new Set(sorted.slice(0, evictCount).map((s) => s.a.id));
+            const kept = all.filter((a) => !toEvict.has(a.id));
+            await this.writeFile(input.sessionId, { version: FILE_VERSION, annotations: kept });
+            const durationMs = Date.now() - t0;
+            this.events?.emit("storage.write", {
+              sessionId: input.sessionId,
+              store: "annotations",
+              filePath: fp,
+              operation: "evict",
+              outcome: "success",
+              durationMs,
+              ...this.traceId !== void 0 ? { traceId: this.traceId } : {}
+            });
+          } else {
+            await this.writeFile(input.sessionId, { version: FILE_VERSION, annotations: all });
+            const durationMs = Date.now() - t0;
+            this.events?.emit("storage.write", {
+              sessionId: input.sessionId,
+              store: "annotations",
+              filePath: fp,
+              operation: "add",
+              outcome: "success",
+              durationMs,
+              ...this.traceId !== void 0 ? { traceId: this.traceId } : {}
+            });
+          }
+        });
       });
-    });
-    return annotation;
+      return annotation;
+    } catch (err) {
+      this.events?.emit("storage.error", {
+        sessionId: input.sessionId,
+        store: "annotations",
+        filePath: fp,
+        operation: "add",
+        outcome: "failure",
+        error: err instanceof Error ? err.message : String(err),
+        recoverable: false,
+        durationMs: Date.now() - t0,
+        ...this.traceId !== void 0 ? { traceId: this.traceId } : {}
+      });
+      throw err;
+    }
   }
   /**
    * Mark an annotation as resolved. Returns the updated record, or
@@ -3594,26 +4204,53 @@ var AnnotationsStore = class {
    */
   async resolve(input) {
     let updated = null;
-    await this.enqueue(input.sessionId, async () => {
-      await withFileLock(this.filePath(input.sessionId), async () => {
-        const all = await this.list(input.sessionId);
-        const idx = all.findIndex((a) => a.id === input.annotationId);
-        if (idx === -1) {
-          updated = null;
-          return;
-        }
-        const next = {
-          ...expectDefined(all[idx]),
-          resolved: true,
-          resolvedAt: (/* @__PURE__ */ new Date()).toISOString(),
-          resolvedBy: input.resolvedBy
-        };
-        all[idx] = next;
-        await this.writeFile(input.sessionId, { version: FILE_VERSION, annotations: all });
-        updated = next;
+    const fp = this.filePath(input.sessionId);
+    const t0 = Date.now();
+    try {
+      await this.enqueue(input.sessionId, async () => {
+        await withFileLock(fp, async () => {
+          const all = await this.list(input.sessionId);
+          const idx = all.findIndex((a) => a.id === input.annotationId);
+          if (idx === -1) {
+            updated = null;
+            return;
+          }
+          const next = {
+            ...expectDefined(all[idx]),
+            resolved: true,
+            resolvedAt: (/* @__PURE__ */ new Date()).toISOString(),
+            resolvedBy: input.resolvedBy
+          };
+          all[idx] = next;
+          await this.writeFile(input.sessionId, { version: FILE_VERSION, annotations: all });
+          updated = next;
+          const durationMs = Date.now() - t0;
+          this.events?.emit("storage.write", {
+            sessionId: input.sessionId,
+            store: "annotations",
+            filePath: fp,
+            operation: "resolve",
+            outcome: "success",
+            durationMs,
+            ...this.traceId !== void 0 ? { traceId: this.traceId } : {}
+          });
+        });
       });
-    });
-    return updated;
+      return updated;
+    } catch (err) {
+      this.events?.emit("storage.error", {
+        sessionId: input.sessionId,
+        store: "annotations",
+        filePath: fp,
+        operation: "resolve",
+        outcome: "failure",
+        error: err instanceof Error ? err.message : String(err),
+        recoverable: false,
+        durationMs: Date.now() - t0,
+        ...this.traceId !== void 0 ? { traceId: this.traceId } : {}
+      });
+      throw err;
+    }
   }
   // ── Internals ──────────────────────────────────────────────────────────
   filePath(sessionId) {
@@ -3621,16 +4258,21 @@ var AnnotationsStore = class {
   }
   async readFile(sessionId) {
     const fp = this.filePath(sessionId);
+    let raw;
+    try {
+      raw = await fsp.readFile(fp, "utf8");
+    } catch (err) {
+      if (err.code === "ENOENT") return null;
+      throw err;
+    }
     try {
-      const raw = await fsp.readFile(fp, "utf8");
       const parsed = JSON.parse(raw);
       if (parsed.version !== FILE_VERSION) {
         return { version: FILE_VERSION, annotations: [] };
       }
       return parsed;
-    } catch (err) {
-      if (err.code === "ENOENT") return null;
-      return { version: FILE_VERSION, annotations: [] };
+    } catch {
+      return null;
     }
   }
   async writeFile(sessionId, file) {
@@ -3684,9 +4326,20 @@ function hashRequest(request) {
   const digest = createHash("sha256").update(json, "utf8").digest("hex");
   return `sha256:${digest}`;
 }
+
+// src/storage/replay-log-store.ts
+function storageErrorString2(err) {
+  if (err instanceof Error) {
+    const code = err.code;
+    return code ? `${code}: ${err.message}` : err.message;
+  }
+  return String(err);
+}
 var DEFAULT_MAX_ENTRIES = 1e3;
 var ReplayLogStore = class {
   dir;
+  events;
+  traceId;
   writeChains = /* @__PURE__ */ new Map();
   /** Per-session hash → entry index, kept in memory after the first load. */
   cache = /* @__PURE__ */ new Map();
@@ -3695,6 +4348,8 @@ var ReplayLogStore = class {
   maxEntries;
   constructor(opts) {
     this.dir = opts.dir;
+    this.events = opts.events;
+    this.traceId = opts.traceId;
     this.maxEntries = opts.maxEntries ?? DEFAULT_MAX_ENTRIES;
   }
   // ── Writes ──────────────────────────────────────────────────────────────
@@ -3705,38 +4360,43 @@ var ReplayLogStore = class {
    */
   async record(input) {
     const hash = hashRequest(input.request);
-    await this.enqueue(input.sessionId, async () => {
-      await withFileLock(this.filePath(input.sessionId), async () => {
-        const entries = await this.readAll(input.sessionId);
-        if (entries.some((entry2) => entry2.hash === hash)) return;
-        const entry = {
-          hash,
-          ts: (/* @__PURE__ */ new Date()).toISOString(),
-          request: input.request,
-          response: input.response
-        };
-        entries.push(entry);
-        const keep = entries.slice(-this.maxEntries);
-        const cache = /* @__PURE__ */ new Map();
-        for (const e of keep) cache.set(e.hash, e);
-        this.cache.set(input.sessionId, cache);
-        await this.rewriteCache(input.sessionId, cache);
+    const fp = this.filePath(input.sessionId);
+    const t0 = Date.now();
+    try {
+      await this.enqueue(input.sessionId, async () => {
+        await withFileLock(this.filePath(input.sessionId), async () => {
+          const entries = await this.readAll(input.sessionId);
+          if (entries.some((entry2) => entry2.hash === hash)) return;
+          const entry = {
+            hash,
+            ts: (/* @__PURE__ */ new Date()).toISOString(),
+            request: input.request,
+            response: input.response
+          };
+          entries.push(entry);
+          const keep = entries.slice(-this.maxEntries);
+          const didEvict = keep.length < entries.length;
+          const cache = /* @__PURE__ */ new Map();
+          for (const e of keep) cache.set(e.hash, e);
+          this.cache.set(input.sessionId, cache);
+          await this.writeAll(input.sessionId, keep, didEvict ? "compact" : "record");
+        });
       });
-    });
-    return hash;
-  }
-  /**
-   * Compact the replay log to keep only the most recent maxEntries.
-   * Called when entry count exceeds the cap. Rewrites the entire file
-   * but only happens O(n / maxEntries) times per session.
-   */
-  async rewriteCache(sessionId, cache) {
-    const all = [...cache.values()];
-    const keep = all.slice(-this.maxEntries);
-    await this.writeAll(sessionId, keep);
-    cache.clear();
-    for (const e of keep) cache.set(e.hash, e);
-    this.diskCount.set(sessionId, keep.length);
+      return hash;
+    } catch (err) {
+      this.events?.emit("storage.error", {
+        sessionId: input.sessionId,
+        store: "replay",
+        filePath: fp,
+        operation: "record",
+        outcome: "failure",
+        error: storageErrorString2(err),
+        recoverable: false,
+        durationMs: Date.now() - t0,
+        ...this.traceId !== void 0 ? { traceId: this.traceId } : {}
+      });
+      throw err;
+    }
   }
   // ── Reads ───────────────────────────────────────────────────────────────
   /**
@@ -3745,13 +4405,65 @@ var ReplayLogStore = class {
    * per session (in-memory cache).
    */
   async lookup(sessionId, hash) {
-    const cache = await this.ensureCache(sessionId);
-    return cache.get(hash) ?? null;
+    const fp = this.filePath(sessionId);
+    const t0 = Date.now();
+    try {
+      const cache = await this.ensureCache(sessionId);
+      this.events?.emit("storage.read", {
+        sessionId,
+        store: "replay",
+        filePath: fp,
+        operation: "lookup",
+        outcome: "success",
+        durationMs: Date.now() - t0,
+        ...this.traceId !== void 0 ? { traceId: this.traceId } : {}
+      });
+      return cache.get(hash) ?? null;
+    } catch (err) {
+      this.events?.emit("storage.read", {
+        sessionId,
+        store: "replay",
+        filePath: fp,
+        operation: "lookup",
+        outcome: "failure",
+        durationMs: Date.now() - t0,
+        error: storageErrorString2(err),
+        ...this.traceId !== void 0 ? { traceId: this.traceId } : {}
+      });
+      throw err;
+    }
   }
   /** All recorded entries for a session, in insertion order. */
   async load(sessionId) {
-    const cache = await this.ensureCache(sessionId);
-    return [...cache.values()];
+    const fp = this.filePath(sessionId);
+    const t0 = Date.now();
+    try {
+      const cache = await this.ensureCache(sessionId);
+      const durationMs = Date.now() - t0;
+      this.events?.emit("storage.read", {
+        sessionId,
+        store: "replay",
+        filePath: fp,
+        operation: "load",
+        outcome: "success",
+        durationMs,
+        ...this.traceId !== void 0 ? { traceId: this.traceId } : {}
+      });
+      return [...cache.values()];
+    } catch (err) {
+      const durationMs = Date.now() - t0;
+      this.events?.emit("storage.read", {
+        sessionId,
+        store: "replay",
+        filePath: fp,
+        operation: "load",
+        outcome: "failure",
+        durationMs,
+        error: storageErrorString2(err),
+        ...this.traceId !== void 0 ? { traceId: this.traceId } : {}
+      });
+      throw err;
+    }
   }
   /**
    * List every session id that has a replay log in the store dir.
@@ -3821,13 +4533,24 @@ var ReplayLogStore = class {
       return out;
     } catch (err) {
       if (err.code === "ENOENT") return [];
-      return [];
+      throw err;
     }
   }
-  async writeAll(sessionId, entries) {
+  async writeAll(sessionId, entries, operation = "record") {
     const fp = this.filePath(sessionId);
+    const t0 = Date.now();
     const body = entries.map((e) => JSON.stringify(e)).join("\n") + (entries.length ? "\n" : "");
     await atomicWrite(fp, body);
+    const durationMs = Date.now() - t0;
+    this.events?.emit("storage.write", {
+      sessionId,
+      store: "replay",
+      filePath: fp,
+      operation,
+      outcome: "success",
+      durationMs,
+      ...this.traceId !== void 0 ? { traceId: this.traceId } : {}
+    });
   }
   async ensureCache(sessionId) {
     let cache = this.cache.get(sessionId);
@@ -4005,6 +4728,8 @@ var GENESIS_PREV = "0".repeat(64);
 var DEFAULT_FSYNC_EVERY = 100;
 var ToolAuditLog = class {
   dir;
+  events;
+  traceId;
   /** In-memory cache of the last entry's hash (per session), to compute chains efficiently. */
   tailHash = /* @__PURE__ */ new Map();
   /** In-memory counter for entry indices — avoids re-reading the file on every write. */
@@ -4015,6 +4740,8 @@ var ToolAuditLog = class {
   fsyncEvery;
   constructor(opts) {
     this.dir = opts.dir;
+    this.events = opts.events;
+    this.traceId = opts.traceId;
     this.fsyncEvery = opts.fsyncEvery ?? DEFAULT_FSYNC_EVERY;
   }
   /**
@@ -4025,96 +4752,180 @@ var ToolAuditLog = class {
    */
   async record(input) {
     let entry;
-    await this.enqueue(input.sessionId, async () => {
-      await withFileLock(this.filePath(input.sessionId), async () => {
-        const entries = await this.readAll(input.sessionId);
-        const prev = entries.at(-1);
-        const prevHash = prev?.hash ?? GENESIS_PREV;
-        const index = prev ? prev.index + 1 : 0;
-        const id = randomUUID();
-        const ts = (/* @__PURE__ */ new Date()).toISOString();
-        const content = {
-          id,
-          ts,
-          prevHash,
-          toolName: input.toolName,
-          toolUseId: input.toolUseId,
-          input: input.input,
-          output: input.output,
-          isError: input.isError,
-          index
-        };
-        const hash = createHash("sha256").update(stableStringify2(content), "utf8").digest("hex");
-        entry = {
-          id,
-          ts,
-          prevHash,
-          hash,
-          toolName: input.toolName,
-          toolUseId: input.toolUseId,
-          input: input.input,
-          output: input.output,
-          isError: input.isError,
-          index
-        };
-        entries.push(entry);
-        await this.writeAll(input.sessionId, entries);
-        this.tailHash.set(input.sessionId, hash);
-        this.tailIndex.set(input.sessionId, index + 1);
+    const fp = this.filePath(input.sessionId);
+    const t0 = Date.now();
+    try {
+      await this.enqueue(input.sessionId, async () => {
+        await withFileLock(fp, async () => {
+          const entries = await this.readAll(input.sessionId);
+          const prev = entries.at(-1);
+          const prevHash = prev?.hash ?? GENESIS_PREV;
+          const index = prev ? prev.index + 1 : 0;
+          const id = randomUUID();
+          const ts = (/* @__PURE__ */ new Date()).toISOString();
+          const content = {
+            id,
+            ts,
+            prevHash,
+            toolName: input.toolName,
+            toolUseId: input.toolUseId,
+            input: input.input,
+            output: input.output,
+            isError: input.isError,
+            index
+          };
+          const hash = createHash("sha256").update(stableStringify2(content), "utf8").digest("hex");
+          entry = {
+            id,
+            ts,
+            prevHash,
+            hash,
+            toolName: input.toolName,
+            toolUseId: input.toolUseId,
+            input: input.input,
+            output: input.output,
+            isError: input.isError,
+            index
+          };
+          entries.push(entry);
+          await this.writeAll(input.sessionId, entries);
+          this.tailHash.set(input.sessionId, hash);
+          this.tailIndex.set(input.sessionId, index + 1);
+          const durationMs = Date.now() - t0;
+          this.events?.emit("storage.write", {
+            sessionId: input.sessionId,
+            store: "audit",
+            filePath: fp,
+            operation: "record",
+            outcome: "success",
+            durationMs,
+            ...this.traceId !== void 0 ? { traceId: this.traceId } : {}
+          });
+        });
       });
-    });
-    return entry;
+      return entry;
+    } catch (err) {
+      this.events?.emit("storage.error", {
+        sessionId: input.sessionId,
+        store: "audit",
+        filePath: fp,
+        operation: "record",
+        outcome: "failure",
+        error: err instanceof Error ? err.message : String(err),
+        recoverable: false,
+        durationMs: Date.now() - t0,
+        ...this.traceId !== void 0 ? { traceId: this.traceId } : {}
+      });
+      throw err;
+    }
   }
   /**
    * Walk the chain and verify every entry's hash and prevHash.
    * Returns a structured verdict — never throws.
    */
   async verify(sessionId) {
-    const entries = await this.readAll(sessionId);
-    if (entries.length === 0) return { ok: true, entries: 0 };
-    if (entries[0]?.prevHash !== GENESIS_PREV) {
-      return {
-        ok: false,
-        brokenAt: 0,
-        reason: "first entry is not the genesis (prevHash != 0\u20260)"
-      };
+    const fp = this.filePath(sessionId);
+    const t0 = Date.now();
+    let entries;
+    try {
+      entries = await this.readAll(sessionId);
+    } catch (err) {
+      this.events?.emit("storage.read", {
+        sessionId,
+        store: "audit",
+        filePath: fp,
+        operation: "verify",
+        outcome: "failure",
+        durationMs: Date.now() - t0,
+        error: err instanceof Error ? err.message : String(err),
+        ...this.traceId !== void 0 ? { traceId: this.traceId } : {}
+      });
+      return { ok: true, entries: 0 };
     }
-    let prevHash = GENESIS_PREV;
-    for (let i = 0; i < entries.length; i++) {
-      const e = expectDefined(entries[i]);
-      if (e.prevHash !== prevHash) {
+    const verdict = (() => {
+      if (entries.length === 0) return { ok: true, entries: 0 };
+      if (entries[0]?.prevHash !== GENESIS_PREV) {
         return {
           ok: false,
-          brokenAt: i,
-          reason: `prevHash mismatch at entry ${i} (expected ${prevHash.slice(0, 8)}\u2026, got ${e.prevHash.slice(0, 8)}\u2026)`
+          brokenAt: 0,
+          reason: "first entry is not the genesis (prevHash != 0\u20260)"
         };
       }
-      const content = {
-        id: e.id,
-        ts: e.ts,
-        prevHash: e.prevHash,
-        toolName: e.toolName,
-        toolUseId: e.toolUseId,
-        input: e.input,
-        output: e.output,
-        isError: e.isError,
-        index: e.index
-      };
-      const expectedHash = createHash("sha256").update(stableStringify2(content), "utf8").digest("hex");
-      if (expectedHash !== e.hash) {
-        return {
-          ok: false,
-          brokenAt: i,
-          reason: `hash mismatch at entry ${i} (entry content was modified)`
+      let prevHash = GENESIS_PREV;
+      for (let i = 0; i < entries.length; i++) {
+        const e = expectDefined(entries[i]);
+        if (e.prevHash !== prevHash) {
+          return {
+            ok: false,
+            brokenAt: i,
+            reason: `prevHash mismatch at entry ${i} (expected ${prevHash.slice(0, 8)}\u2026, got ${e.prevHash.slice(0, 8)}\u2026)`
+          };
+        }
+        const content = {
+          id: e.id,
+          ts: e.ts,
+          prevHash: e.prevHash,
+          toolName: e.toolName,
+          toolUseId: e.toolUseId,
+          input: e.input,
+          output: e.output,
+          isError: e.isError,
+          index: e.index
         };
+        const expectedHash = createHash("sha256").update(stableStringify2(content), "utf8").digest("hex");
+        if (expectedHash !== e.hash) {
+          return {
+            ok: false,
+            brokenAt: i,
+            reason: `hash mismatch at entry ${i} (entry content was modified)`
+          };
+        }
+        prevHash = e.hash;
       }
-      prevHash = e.hash;
-    }
-    return { ok: true, entries: entries.length };
+      return { ok: true, entries: entries.length };
+    })();
+    this.events?.emit("storage.read", {
+      sessionId,
+      store: "audit",
+      filePath: fp,
+      operation: "verify",
+      outcome: verdict.ok ? "success" : "failure",
+      durationMs: Date.now() - t0,
+      ...this.traceId !== void 0 ? { traceId: this.traceId } : {}
+    });
+    return verdict;
   }
   /** All entries for a session, in insertion order. */
   async load(sessionId) {
-    return this.readAll(sessionId);
+    const fp = this.filePath(sessionId);
+    const t0 = Date.now();
+    try {
+      const entries = await this.readAll(sessionId);
+      const durationMs = Date.now() - t0;
+      this.events?.emit("storage.read", {
+        sessionId,
+        store: "audit",
+        filePath: fp,
+        operation: "load",
+        outcome: "success",
+        durationMs,
+        ...this.traceId !== void 0 ? { traceId: this.traceId } : {}
+      });
+      return entries;
+    } catch (err) {
+      const durationMs = Date.now() - t0;
+      this.events?.emit("storage.read", {
+        sessionId,
+        store: "audit",
+        filePath: fp,
+        operation: "load",
+        outcome: "failure",
+        durationMs,
+        error: err instanceof Error ? err.message : String(err),
+        ...this.traceId !== void 0 ? { traceId: this.traceId } : {}
+      });
+      throw err;
+    }
   }
   // ── Internals ────────────────────────────────────────────────────────────
   filePath(sessionId) {
@@ -4136,7 +4947,7 @@ var ToolAuditLog = class {
       return out;
     } catch (err) {
       if (err.code === "ENOENT") return [];
-      return [];
+      throw err;
     }
   }
   async writeAll(sessionId, entries) {
@@ -4848,24 +5659,66 @@ async function revertSnapshots(snapshots, projectRoot) {
   }
   return { revertedFiles, errors };
 }
-async function loadTodosCheckpoint(filePath) {
+async function loadTodosCheckpoint(filePath, events, traceId) {
+  const t0 = Date.now();
   let raw;
   try {
     raw = await fsp.readFile(filePath, "utf8");
-  } catch {
+  } catch (err) {
+    events?.emit("storage.error", {
+      sessionId: traceId ?? "~boot~",
+      store: "todos",
+      filePath,
+      operation: "load",
+      outcome: "failure",
+      error: err instanceof Error ? err.message : String(err),
+      recoverable: true
+    });
     return null;
   }
   try {
     const parsed = JSON.parse(raw);
-    if (parsed?.version !== 1 || !Array.isArray(parsed.todos)) return null;
+    if (parsed?.version !== 1 || !Array.isArray(parsed.todos)) {
+      events?.emit("storage.read", {
+        sessionId: traceId ?? "~boot~",
+        store: "todos",
+        filePath,
+        operation: "load",
+        outcome: "failure",
+        durationMs: Date.now() - t0,
+        error: "invalid_schema",
+        ...traceId !== void 0 && { traceId }
+      });
+      return null;
+    }
+    events?.emit("storage.read", {
+      sessionId: traceId ?? "~boot~",
+      store: "todos",
+      filePath,
+      operation: "load",
+      outcome: "success",
+      durationMs: Date.now() - t0,
+      ...traceId !== void 0 && { traceId }
+    });
     return parsed.todos.filter(
       (t) => !!t && typeof t.id === "string" && typeof t.content === "string" && typeof t.status === "string" && (t.activeForm === void 0 || typeof t.activeForm === "string")
     );
   } catch {
+    events?.emit("storage.read", {
+      sessionId: traceId ?? "~boot~",
+      store: "todos",
+      filePath,
+      operation: "load",
+      outcome: "failure",
+      durationMs: Date.now() - t0,
+      error: "parse_failed",
+      ...traceId !== void 0 && { traceId }
+    });
     return null;
   }
 }
-async function saveTodosCheckpoint(filePath, sessionId, todos) {
+async function saveTodosCheckpoint(filePath, sessionId, todos, events, traceId) {
+  const t0 = Date.now();
   const payload = {
     version: 1,
     sessionId,
@@ -4874,7 +5727,25 @@ async function saveTodosCheckpoint(filePath, sessionId, todos) {
   };
   try {
     await atomicWrite(filePath, JSON.stringify(payload, null, 2), { mode: 384 });
+    events?.emit("storage.write", {
+      sessionId: traceId ?? sessionId,
+      store: "todos",
+      filePath,
+      operation: "save",
+      outcome: "success",
+      durationMs: Date.now() - t0,
+      ...traceId !== void 0 && { traceId }
+    });
   } catch (err) {
+    events?.emit("storage.error", {
+      sessionId: traceId ?? sessionId,
+      store: "todos",
+      filePath,
+      operation: "save",
+      outcome: "failure",
+      error: err instanceof Error ? err.message : String(err),
+      recoverable: false
+    });
     console.warn(JSON.stringify({
       level: "warn",
       event: "todos_checkpoint.save_failed",
@@ -4883,12 +5754,12 @@ async function saveTodosCheckpoint(filePath, sessionId, todos) {
     }));
   }
 }
-function attachTodosCheckpoint(state, filePath, sessionId) {
+function attachTodosCheckpoint(state, filePath, sessionId, events, traceId) {
   let timer = null;
   let pending = null;
   let writeChain = Promise.resolve();
   const enqueueWrite = (todos) => {
-    writeChain = writeChain.then(() => saveTodosCheckpoint(filePath, sessionId, todos)).catch((err) => {
+    writeChain = writeChain.then(() => saveTodosCheckpoint(filePath, sessionId, todos, events, traceId)).catch((err) => {
       const msg = err instanceof Error ? err.message : String(err);
       console.error(JSON.stringify({
         level: "error",
@@ -4927,25 +5798,79 @@ function attachTodosCheckpoint(state, filePath, sessionId) {
     }
   };
 }
-async function loadPlan(filePath) {
+async function loadPlan(filePath, events) {
+  const t0 = Date.now();
   let raw;
   try {
     raw = await fsp.readFile(filePath, "utf8");
-  } catch {
+  } catch (err) {
+    events?.emit("storage.error", {
+      sessionId: "~boot~",
+      store: "plan",
+      filePath,
+      operation: "load",
+      error: err instanceof Error ? err.message : String(err),
+      recoverable: true
+    });
     return null;
   }
   try {
     const parsed = JSON.parse(raw);
-    if (parsed?.version !== 1 || !Array.isArray(parsed.items)) return null;
+    if (parsed?.version !== 1 || !Array.isArray(parsed.items)) {
+      events?.emit("storage.read", {
+        sessionId: "~boot~",
+        store: "plan",
+        filePath,
+        operation: "load",
+        outcome: "failure",
+        durationMs: Date.now() - t0,
+        error: "invalid_schema"
+      });
+      return null;
+    }
+    events?.emit("storage.read", {
+      sessionId: "~boot~",
+      store: "plan",
+      filePath,
+      operation: "load",
+      outcome: "success",
+      durationMs: Date.now() - t0
+    });
     return parsed;
   } catch {
+    events?.emit("storage.read", {
+      sessionId: "~boot~",
+      store: "plan",
+      filePath,
+      operation: "load",
+      outcome: "failure",
+      durationMs: Date.now() - t0,
+      error: "parse_failed"
+    });
     return null;
   }
 }
-async function savePlan(filePath, plan) {
+async function savePlan(filePath, plan, events) {
+  const t0 = Date.now();
   try {
     await atomicWrite(filePath, JSON.stringify(plan, null, 2), { mode: 384 });
+    events?.emit("storage.write", {
+      sessionId: "~boot~",
+      store: "plan",
+      filePath,
+      operation: "save",
+      outcome: "success",
+      durationMs: Date.now() - t0
+    });
   } catch (err) {
+    events?.emit("storage.error", {
+      sessionId: "~boot~",
+      store: "plan",
+      filePath,
+      operation: "save",
+      error: err instanceof Error ? err.message : String(err),
+      recoverable: false
+    });
     console.warn(
       "[plan-store] save failed:",
       err instanceof Error ? err.message : String(err)
@@ -5179,37 +6104,98 @@ function emptyTaskFile(sessionId) {
     tasks: []
   };
 }
-async function loadTasks(filePath) {
+async function loadTasks(filePath, events, traceId) {
+  const t0 = Date.now();
   let raw;
   try {
     raw = await fsp.readFile(filePath, "utf8");
-  } catch {
+  } catch (err) {
+    events?.emit("storage.error", {
+      sessionId: traceId ?? "~boot~",
+      store: "tasks",
+      filePath,
+      operation: "load",
+      outcome: "failure",
+      error: err instanceof Error ? err.message : String(err),
+      recoverable: true
+    });
     return null;
   }
   try {
     const parsed = JSON.parse(raw);
-    if (parsed?.version !== 1 || !Array.isArray(parsed.tasks)) return null;
+    if (parsed?.version !== 1 || !Array.isArray(parsed.tasks)) {
+      events?.emit("storage.read", {
+        sessionId: traceId ?? "~boot~",
+        store: "tasks",
+        filePath,
+        operation: "load",
+        outcome: "failure",
+        durationMs: Date.now() - t0,
+        error: "invalid_schema",
+        ...traceId !== void 0 && { traceId }
+      });
+      return null;
+    }
+    events?.emit("storage.read", {
+      sessionId: traceId ?? "~boot~",
+      store: "tasks",
+      filePath,
+      operation: "load",
+      outcome: "success",
+      durationMs: Date.now() - t0,
+      ...traceId !== void 0 && { traceId }
+    });
     return parsed;
   } catch {
+    events?.emit("storage.read", {
+      sessionId: traceId ?? "~boot~",
+      store: "tasks",
+      filePath,
+      operation: "load",
+      outcome: "failure",
+      durationMs: Date.now() - t0,
+      error: "parse_failed",
+      ...traceId !== void 0 && { traceId }
+    });
     return null;
   }
 }
-async function saveTasks(filePath, tasks) {
+async function saveTasks(filePath, tasks, events, traceId) {
+  const t0 = Date.now();
   try {
     tasks.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
     await atomicWrite(filePath, JSON.stringify(tasks, null, 2), { mode: 384 });
+    events?.emit("storage.write", {
+      sessionId: traceId ?? "~boot~",
+      store: "tasks",
+      filePath,
+      operation: "save",
+      outcome: "success",
+      durationMs: Date.now() - t0,
+      ...traceId !== void 0 && { traceId }
+    });
   } catch (err) {
+    events?.emit("storage.error", {
+      sessionId: traceId ?? "~boot~",
+      store: "tasks",
+      filePath,
+      operation: "save",
+      outcome: "failure",
+      error: err instanceof Error ? err.message : String(err),
+      recoverable: false,
+      ...traceId !== void 0 && { traceId }
+    });
     console.warn(
       "[task-store] save failed:",
       err instanceof Error ? err.message : String(err)
     );
   }
 }
-async function mutateTasks(filePath, sessionId, fn) {
+async function mutateTasks(filePath, sessionId, fn, events, traceId) {
   return withFileLock(filePath, async () => {
-    const file = await loadTasks(filePath) ?? emptyTaskFile(sessionId);
+    const file = await loadTasks(filePath, events, traceId) ?? emptyTaskFile(sessionId);
     const updated = await fn(file);
-    await saveTasks(filePath, updated);
+    await saveTasks(filePath, updated, events, traceId);
     return updated;
   });
 }
@@ -5491,13 +6477,32 @@ var MAX_JOURNAL_ENTRIES = 500;
 function goalFilePath(projectRoot) {
   return resolveWstackPaths({ projectRoot }).projectGoal;
 }
-async function loadGoal(filePath) {
+async function loadGoal(filePath, events) {
+  const t0 = Date.now();
   let raw;
   try {
     raw = await fsp.readFile(filePath, "utf8");
   } catch (err) {
     const code = err.code;
-    if (code === "ENOENT") return null;
+    if (code === "ENOENT") {
+      events?.emit("storage.read", {
+        sessionId: "~boot~",
+        store: "goal",
+        filePath,
+        operation: "load",
+        outcome: "success",
+        durationMs: Date.now() - t0
+      });
+      return null;
+    }
+    events?.emit("storage.error", {
+      sessionId: "~boot~",
+      store: "goal",
+      filePath,
+      operation: "load",
+      error: err instanceof Error ? err.message : String(err),
+      recoverable: false
+    });
     throw err;
   }
   try {
@@ -5510,8 +6515,25 @@ async function loadGoal(filePath) {
         message: "invalid schema \u2014 consider deleting and re-creating",
         timestamp: (/* @__PURE__ */ new Date()).toISOString()
       }));
+      events?.emit("storage.read", {
+        sessionId: "~boot~",
+        store: "goal",
+        filePath,
+        operation: "load",
+        outcome: "failure",
+        durationMs: Date.now() - t0,
+        error: "invalid_schema"
+      });
       return null;
     }
+    events?.emit("storage.read", {
+      sessionId: "~boot~",
+      store: "goal",
+      filePath,
+      operation: "load",
+      outcome: "success",
+      durationMs: Date.now() - t0
+    });
     return parsed;
   } catch {
     console.warn(JSON.stringify({
@@ -5521,13 +6543,39 @@ async function loadGoal(filePath) {
       message: "JSON parse failed \u2014 consider deleting and re-creating",
       timestamp: (/* @__PURE__ */ new Date()).toISOString()
     }));
+    events?.emit("storage.read", {
+      sessionId: "~boot~",
+      store: "goal",
+      filePath,
+      operation: "load",
+      outcome: "failure",
+      durationMs: Date.now() - t0,
+      error: "parse_failed"
+    });
     return null;
   }
 }
-async function saveGoal(filePath, goal) {
+async function saveGoal(filePath, goal, events) {
+  const t0 = Date.now();
   try {
     await atomicWrite(filePath, JSON.stringify(goal, null, 2), { mode: 384 });
+    events?.emit("storage.write", {
+      sessionId: "~boot~",
+      store: "goal",
+      filePath,
+      operation: "save",
+      outcome: "success",
+      durationMs: Date.now() - t0
+    });
   } catch (err) {
+    events?.emit("storage.error", {
+      sessionId: "~boot~",
+      store: "goal",
+      filePath,
+      operation: "save",
+      error: err instanceof Error ? err.message : String(err),
+      recoverable: false
+    });
     throw new FsError({
       message: err instanceof Error ? err.message : String(err),
       code: ERROR_CODES.FS_ATOMIC_WRITE_FAILED,