@wrongstack/core 0.155.0 → 0.250.0

package/dist/storage/index.js

@@ -8,7 +8,9 @@ import { hostname } from 'os';
 // src/utils/expect-defined.ts
 function expectDefined(value, label) {
   if (value === null || value === void 0) {
-    throw new Error("Expected value to be defined");
+    const err = new Error("Expected value to be defined");
+    err.name = "ExpectDefinedError";
+    throw err;
   }
   return value;
 }
@@ -80,7 +82,7 @@ async function withFileLock(targetPath, fn, opts = {}) {
       if (Date.now() - started >= timeoutMs) {
         throw new Error(`Timed out waiting for file lock: ${targetPath}`);
       }
-      await new Promise((resolve4) => setTimeout(resolve4, 25));
+      await new Promise((resolve5) => setTimeout(resolve5, 25));
     }
   }
   try {
@@ -114,7 +116,7 @@ async function renameWithRetry(from, to) {
       if (!code || !TRANSIENT_RENAME_CODES.has(code) || i === delays.length) {
         throw err;
       }
-      await new Promise((resolve4) => setTimeout(resolve4, delays[i]));
+      await new Promise((resolve5) => setTimeout(resolve5, delays[i]));
     }
   }
   throw lastErr;
@@ -272,7 +274,12 @@ var DefaultSessionStore = class _DefaultSessionStore {
         onClose: (s) => this.appendToIndex(s)
       });
     } catch (err) {
-      await handle.close().catch((e) => console.warn(`[session-store] handle.close() failed: ${e}`));
+      await handle.close().catch((e) => console.warn(JSON.stringify({
+        level: "warn",
+        event: "session_store.handle_close_failed",
+        message: e instanceof Error ? e.message : String(e),
+        timestamp: (/* @__PURE__ */ new Date()).toISOString()
+      })));
       throw err;
     }
   }
@@ -299,11 +306,25 @@ var DefaultSessionStore = class _DefaultSessionStore {
           provider: data.metadata.provider
         },
         this.events,
-        { resumed: true, dir: this.dir, filePath: file, secretScrubber: this.secretScrubber, onClose: (s) => this.appendToIndex(s) }
+        {
+          resumed: true,
+          // Shard directory (sessions/<date>/) — must match create() so the
+          // .summary.json sidecar lands next to the JSONL instead of the
+          // sessions root (where summaryFor() would never find it).
+          dir: path13.dirname(file),
+          filePath: file,
+          secretScrubber: this.secretScrubber,
+          onClose: (s) => this.appendToIndex(s)
+        }
       );
       return { writer, data };
     } catch (err) {
-      await handle.close().catch((e) => console.warn(`[session-store] handle.close() failed: ${e}`));
+      await handle.close().catch((e) => console.warn(JSON.stringify({
+        level: "warn",
+        event: "session_store.handle_close_failed",
+        message: e instanceof Error ? e.message : String(e),
+        timestamp: (/* @__PURE__ */ new Date()).toISOString()
+      })));
       throw err;
     }
   }
@@ -323,7 +344,8 @@ var DefaultSessionStore = class _DefaultSessionStore {
     }
     const meta = this.metaFromEvents(id, events);
     const { messages, usage } = this.replay(events, id);
-    return { metadata: meta, events, messages, usage };
+    const toolCallEnds = extractToolCallEnds(events);
+    return { metadata: meta, events, messages, usage, toolCallEnds };
   }
   async list(limit = 20) {
     try {
@@ -479,10 +501,13 @@ var DefaultSessionStore = class _DefaultSessionStore {
       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) => {
-        console.warn(
-          `[session-store] Failed to write manifest for "${id}":`,
-          err instanceof Error ? err.message : String(err)
-        );
+        console.warn(JSON.stringify({
+          level: "warn",
+          event: "session_store.manifest_write_failed",
+          sessionId: id,
+          message: err instanceof Error ? err.message : String(err),
+          timestamp: (/* @__PURE__ */ new Date()).toISOString()
+        }));
       });
       return summary;
     }
@@ -490,17 +515,48 @@ var DefaultSessionStore = class _DefaultSessionStore {
   /**
    * Delete a session and all associated files: JSONL, summary, plan/todos
    * sidecars, and the session directory (fleet.json, shared/, subagents/).
+   *
+   * Individual file deletions are best-effort (logged as structured warnings),
+   * but a tombstone is always written so readIndex() filters this session out.
+   * If the session directory itself can't be removed, the error is surfaced
+   * to the caller so prune() can report it.
    */
   async deleteSession(id) {
-    await fsp.unlink(this.sessionPath(id, ".jsonl")).catch((err) => console.warn(`[session-store] delete .jsonl failed: ${err}`));
-    await fsp.unlink(this.sessionPath(id, ".summary.json")).catch((err) => console.warn(`[session-store] delete .summary.json failed: ${err}`));
+    const jsonlPath = this.sessionPath(id, ".jsonl");
+    const summaryPath = this.sessionPath(id, ".summary.json");
     const shardDir = path13.dirname(path13.join(this.dir, id));
     const base = path13.basename(id);
-    for (const ext of [".plan.json", ".todos.json"]) {
-      await fsp.unlink(path13.join(shardDir, `${base}${ext}`)).catch((err) => console.warn(`[session-store] delete ${ext} failed: ${err}`));
-    }
     const sessDir = path13.join(shardDir, base);
-    await fsp.rm(sessDir, { recursive: true, force: true }).catch((err) => console.warn(`[session-store] delete session dir failed: ${err}`));
+    const deletions = [
+      fsp.unlink(jsonlPath),
+      fsp.unlink(summaryPath),
+      fsp.unlink(path13.join(shardDir, `${base}.plan.json`)),
+      fsp.unlink(path13.join(shardDir, `${base}.todos.json`))
+    ];
+    const results = await Promise.allSettled(deletions);
+    for (const r of results) {
+      if (r.status === "rejected") {
+        const msg = r.reason instanceof Error ? r.reason.message : String(r.reason);
+        if (r.reason?.code !== "ENOENT") {
+          console.warn(JSON.stringify({
+            level: "warn",
+            event: "session_store.delete_failed",
+            sessionId: id,
+            message: msg,
+            timestamp: (/* @__PURE__ */ new Date()).toISOString()
+          }));
+        }
+      }
+    }
+    await fsp.rm(sessDir, { recursive: true, force: true }).catch((err) => {
+      console.warn(JSON.stringify({
+        level: "warn",
+        event: "session_store.rmdir_failed",
+        sessionId: id,
+        message: err instanceof Error ? err.message : String(err),
+        timestamp: (/* @__PURE__ */ new Date()).toISOString()
+      }));
+    });
     await this.writeTombstone(id);
   }
   async delete(id) {
@@ -516,24 +572,33 @@ var DefaultSessionStore = class _DefaultSessionStore {
       activeSessionId = active.sessionId ?? null;
     } catch {
     }
+    const isPrunableJsonl = (name) => name.endsWith(".jsonl") && name !== "_index.jsonl" && name !== "_mailbox.jsonl" && !name.endsWith(".replay.jsonl") && !name.endsWith(".audit.jsonl");
+    const pruneFile = async (dir, name, prefix) => {
+      const jsonlPath = path13.join(dir, name);
+      try {
+        const stat5 = await fsp.stat(jsonlPath);
+        if (stat5.mtimeMs >= cutoff) return;
+      } catch {
+        return;
+      }
+      const base = name.replace(/\.jsonl$/, "");
+      const id = prefix ? `${prefix}/${base}` : base;
+      if (activeSessionId && id === activeSessionId) return;
+      await this.deleteSession(id);
+      deleted++;
+    };
     const entries = await fsp.readdir(this.dir, { withFileTypes: true }).catch(() => []);
     for (const entry of entries) {
+      if (entry.isFile()) {
+        if (isPrunableJsonl(entry.name)) await pruneFile(this.dir, entry.name, "");
+        continue;
+      }
       if (!entry.isDirectory()) continue;
       const dateDir = path13.join(this.dir, entry.name);
       const files = await fsp.readdir(dateDir, { withFileTypes: true }).catch(() => []);
       for (const file of files) {
-        if (!file.isFile() || !file.name.endsWith(".jsonl")) continue;
-        const jsonlPath = path13.join(dateDir, file.name);
-        try {
-          const stat5 = await fsp.stat(jsonlPath);
-          if (stat5.mtimeMs >= cutoff) continue;
-        } catch {
-          continue;
-        }
-        const id = `${entry.name}/${file.name.replace(/\.jsonl$/, "")}`;
-        if (activeSessionId && id === activeSessionId) continue;
-        await this.deleteSession(id);
-        deleted++;
+        if (!file.isFile() || !isPrunableJsonl(file.name)) continue;
+        await pruneFile(dateDir, file.name, entry.name);
       }
     }
     if (deleted > 0) {
@@ -622,7 +687,7 @@ var DefaultSessionStore = class _DefaultSessionStore {
   }
   metaFromEvents(id, events) {
     const start = events.find((e) => e.type === "session_start");
-    const end = events.find((e) => e.type === "session_end");
+    const end = events.findLast((e) => e.type === "session_end");
     return {
       id,
       startedAt: start?.ts ?? (/* @__PURE__ */ new Date(0)).toISOString(),
@@ -639,9 +704,9 @@ var DefaultSessionStore = class _DefaultSessionStore {
     for (const e of events) {
       if (e.type === "user_input") {
         openToolUses.clear();
-        messages.push({ role: "user", content: e.content });
+        messages.push({ role: "user", content: e.content, ts: e.ts });
       } else if (e.type === "llm_response") {
-        messages.push({ role: "assistant", content: e.content });
+        messages.push({ role: "assistant", content: e.content, ts: e.ts });
         for (const b of e.content) {
           if (b.type === "tool_use") openToolUses.add(b.id);
         }
@@ -660,25 +725,18 @@ var DefaultSessionStore = class _DefaultSessionStore {
           continue;
         }
         openToolUses.delete(e.id);
-        const content = [
-          {
-            type: "tool_result",
-            tool_use_id: e.id,
-            content: typeof e.content === "string" ? e.content : JSON.stringify(e.content),
-            is_error: e.isError
-          }
-        ];
+        const resultBlock = {
+          type: "tool_result",
+          tool_use_id: e.id,
+          content: typeof e.content === "string" ? e.content : JSON.stringify(e.content),
+          is_error: e.isError
+        };
         const last = messages[messages.length - 1];
-        if (last && last.role === "user") {
-          if (Array.isArray(last.content)) {
-            last.content.push(...content);
-          } else if (typeof last.content === "string") {
-            last.content = [{ type: "text", text: last.content }, ...content];
-          } else {
-            messages.push({ role: "user", content });
-          }
+        const lastIsToolResultUser = last?.role === "user" && Array.isArray(last.content) && last.content.every((b) => b.type === "tool_result");
+        if (lastIsToolResultUser && Array.isArray(last.content)) {
+          last.content.push(resultBlock);
         } else {
-          messages.push({ role: "user", content });
+          messages.push({ role: "user", content: [resultBlock], ts: e.ts });
         }
       }
     }
@@ -698,7 +756,24 @@ var DefaultSessionStore = class _DefaultSessionStore {
     return { messages: repaired.messages, usage };
   }
 };
-var FileSessionWriter = class {
+function extractToolCallEnds(events) {
+  const result = [];
+  for (const e of events) {
+    if (e.type === "tool_call_end") {
+      result.push({
+        name: e.name,
+        id: e.id,
+        durationMs: e.durationMs,
+        ok: e.ok ?? false,
+        outputBytes: e.outputBytes,
+        outputTokens: e.outputTokens,
+        outputLines: e.outputLines
+      });
+    }
+  }
+  return result;
+}
+var FileSessionWriter = class _FileSessionWriter {
   constructor(id, handle, startedAt, meta, events, opts = {}) {
     this.id = id;
     this.handle = handle;
@@ -725,7 +800,7 @@ var FileSessionWriter = class {
   meta;
   events;
   closed = false;
-  closing = false;
+  closePromise = null;
   manifestFile;
   summary;
   tokenIn = 0;
@@ -734,12 +809,51 @@ var FileSessionWriter = class {
   get transcriptPath() {
     return this.filePath || void 0;
   }
-  initDone = false;
+  /**
+   * Lazy session_start/session_resumed init, shared by all appenders.
+   * A single promise (not a boolean) so a second append racing the first
+   * can't push its event into the buffer BEFORE the first append's event —
+   * every appender awaits the same init and resumes in FIFO call order.
+   */
+  initPromise = null;
+  ensureInit() {
+    if (!this.initPromise) this.initPromise = this.writeSessionStartLazy();
+    return this.initPromise;
+  }
   resumed;
   appendFailCount = 0;
   lastAppendWarnAt = 0;
   secretScrubber;
   onCloseCb;
+  // ── Write buffer — batches events to reduce per-event disk I/O ─────────
+  //
+  // Every append() pushes the scrubbed event into an in-memory buffer instead
+  // of calling handle.appendFile() synchronously. The buffer flushes to disk
+  // when it reaches FLUSH_SIZE events OR after FLUSH_INTERVAL_MS of inactivity.
+  // This cuts the number of disk writes by ~95% without changing the on-disk
+  // format — the JSONL is still one JSON object per line.
+  writeBuffer = [];
+  flushTimer = null;
+  static FLUSH_INTERVAL_MS = 500;
+  static FLUSH_SIZE = 50;
+  // ── Write serialization ─────────────────────────────────────────────────
+  //
+  // All disk writes are funneled through a FIFO promise chain. Without it,
+  // a timer-driven flush racing an explicit flush()/close() issues two
+  // concurrent appendFile() calls on the shared O_APPEND handle — the kernel
+  // may complete them out of order (chronology breaks) or, for large
+  // batches, interleave partial writes (torn JSONL lines). The chain keeps
+  // exactly one write in flight; failures don't break the chain.
+  writeChain = Promise.resolve();
+  /** Enqueue a write on the FIFO chain. Resolves/rejects with that write. */
+  enqueueWrite(data) {
+    const write = this.writeChain.then(() => this.handle.appendFile(data, "utf8"));
+    this.writeChain = write.then(
+      () => void 0,
+      () => void 0
+    );
+    return write;
+  }
   // ── Enriched summary tracking ──────────────────────────────────────────
   iterationCount = 0;
   toolCallCount = 0;
@@ -789,31 +903,91 @@ var FileSessionWriter = class {
     })}
 `;
     try {
-      if (this.filePath) {
-        await fsp.writeFile(this.filePath, record, { flag: "a", mode: 384 });
-      }
+      await this.enqueueWrite(record);
     } catch {
     }
   }
   async append(event) {
     if (this.closed) return;
-    if (!this.initDone) {
-      this.initDone = true;
-      await this.writeSessionStartLazy();
-    }
+    await this.ensureInit();
     const scrubbed = this.scrubEvent(event);
     this.observeForSummary(scrubbed);
+    this.writeBuffer.push(scrubbed);
+    if (this.writeBuffer.length >= _FileSessionWriter.FLUSH_SIZE) {
+      if (this.flushTimer) {
+        clearTimeout(this.flushTimer);
+        this.flushTimer = null;
+      }
+      await this.flushBuffer();
+    } else {
+      this.scheduleFlush();
+    }
+  }
+  async appendBatch(events) {
+    if (this.closed || events.length === 0) return;
+    await this.ensureInit();
+    for (const event of events) {
+      const scrubbed = this.scrubEvent(event);
+      this.observeForSummary(scrubbed);
+      this.writeBuffer.push(scrubbed);
+    }
+    if (this.writeBuffer.length >= _FileSessionWriter.FLUSH_SIZE) {
+      if (this.flushTimer) {
+        clearTimeout(this.flushTimer);
+        this.flushTimer = null;
+      }
+      await this.flushBuffer();
+    } else {
+      this.scheduleFlush();
+    }
+  }
+  /**
+   * Flush buffered events to disk immediately. Critical events
+   * (user_input, llm_response) call this so they survive SIGKILL/crash
+   * instead of sitting in the in-memory buffer for up to 500ms.
+   *
+   * Idempotent — cancels any pending timer and writes whatever has
+   * accumulated in the buffer. Safe to call even when the buffer
+   * is empty (no-op).
+   */
+  async flush() {
+    if (this.flushTimer) {
+      clearTimeout(this.flushTimer);
+      this.flushTimer = null;
+    }
+    await this.flushBuffer();
+  }
+  /** Schedule a deferred flush. No-op if a timer is already pending. */
+  scheduleFlush() {
+    if (this.flushTimer) return;
+    this.flushTimer = setTimeout(() => {
+      this.flushTimer = null;
+      this.flushBuffer().catch(() => {
+      });
+    }, _FileSessionWriter.FLUSH_INTERVAL_MS);
+  }
+  /**
+   * Flush all buffered events to disk as a single appendFile call.
+   * Errors use the same throttled-warning pattern the old per-event
+   * append path used — one warning every 5s with a suppressed count.
+   * On failure the buffer is cleared (events are best-effort, same as
+   * the old per-event path where a failed write was silently dropped).
+   */
+  async flushBuffer() {
+    if (this.writeBuffer.length === 0) return;
+    const eventCount = this.writeBuffer.length;
+    const batch = this.writeBuffer.map((e) => JSON.stringify(e)).join("\n") + "\n";
+    this.writeBuffer = [];
     try {
-      await this.handle.appendFile(`${JSON.stringify(scrubbed)}
-`, "utf8");
+      await this.enqueueWrite(batch);
     } catch (err) {
-      this.appendFailCount++;
+      this.appendFailCount += eventCount;
       const now = Date.now();
       if (now - this.lastAppendWarnAt > 5e3) {
         const suppressed = this.appendFailCount - 1;
         const tail = suppressed > 0 ? ` (+${suppressed} suppressed)` : "";
         console.warn(
-          "[session] append failed:",
+          "[session] flush failed:",
           err instanceof Error ? err.message : String(err),
           tail
         );
@@ -823,6 +997,11 @@ var FileSessionWriter = class {
     }
   }
   observeForSummary(event) {
+    if (event.type === "llm_response") {
+      for (const block of event.content) {
+        if (block.type === "tool_use") this.openToolUses.add(block.id);
+      }
+    }
     if (event.type === "tool_use") {
       this.openToolUses.add(event.id);
     } else if (event.type === "tool_call_start") {
@@ -856,9 +1035,18 @@ var FileSessionWriter = class {
     }
   }
   async close() {
-    if (this.closing) return;
-    this.closing = true;
+    if (this.closePromise) return this.closePromise;
+    this.closePromise = this.doClose();
+    return this.closePromise;
+  }
+  async doClose() {
     this.closed = true;
+    if (this.flushTimer) {
+      clearTimeout(this.flushTimer);
+      this.flushTimer = null;
+    }
+    await this.flushBuffer();
+    await this.writeChain;
     this.summary = {
       ...this.summary,
       endedAt: (/* @__PURE__ */ new Date()).toISOString(),
@@ -914,6 +1102,12 @@ var FileSessionWriter = class {
   }
   async truncateToCheckpoint(targetPromptIndex) {
     if (!this.filePath) return 0;
+    if (this.flushTimer) {
+      clearTimeout(this.flushTimer);
+      this.flushTimer = null;
+    }
+    await this.flushBuffer();
+    await this.writeChain;
     const raw = await fsp.readFile(this.filePath, "utf8");
     const lines = raw.split("\n");
     const kept = [];
@@ -976,6 +1170,12 @@ var FileSessionWriter = class {
   }
   async clearSession() {
     if (!this.filePath) return;
+    if (this.flushTimer) {
+      clearTimeout(this.flushTimer);
+      this.flushTimer = null;
+    }
+    this.writeBuffer = [];
+    await this.writeChain;
     const record = `${JSON.stringify({
       type: "session_start",
       ts: (/* @__PURE__ */ new Date()).toISOString(),
@@ -1042,7 +1242,13 @@ var QueueStore = class {
     } catch (err) {
       const code = err.code;
       if (code === "ENOENT") return [];
-      console.warn(`[QueueStore] failed to read queue file "${this.file}":`, err instanceof Error ? err.message : String(err));
+      console.warn(JSON.stringify({
+        level: "warn",
+        event: "queue_store.read_failed",
+        path: this.file,
+        message: err instanceof Error ? err.message : String(err),
+        timestamp: (/* @__PURE__ */ new Date()).toISOString()
+      }));
       return [];
     }
     let parsed;
@@ -1064,7 +1270,13 @@ var QueueStore = class {
     } catch (err) {
       const code = err.code;
       if (code === "ENOENT") return;
-      console.warn(`QueueStore.clear() failed for ${this.file}: ${err.message}`);
+      console.warn(JSON.stringify({
+        level: "warn",
+        event: "queue_store.clear_failed",
+        path: this.file,
+        message: err.message,
+        timestamp: (/* @__PURE__ */ new Date()).toISOString()
+      }));
     }
   }
 };
@@ -1483,10 +1695,9 @@ var DefaultMemoryStore = class {
   }
   async runSerialized(scope, work) {
     const prior = this.writeChain.get(scope) ?? Promise.resolve();
-    prior.catch((err) => {
+    const next = prior.catch((err) => {
       this.writeErrors.set(scope, err);
-    });
-    const next = prior.catch(() => void 0).then(work);
+    }).then(() => work());
     this.writeChain.set(scope, next);
     try {
       return await next;
@@ -1716,9 +1927,9 @@ ${body.trim()}`);
     if (!this.persistBackup || scope === "project-agents") return;
     try {
       const content = await this.backend.readAll(scope, this.files[scope]);
-      const { writeFile: writeFile6, mkdir: mkdir6 } = await import('fs/promises');
-      await mkdir6(this.backupDir, { recursive: true });
-      await writeFile6(`${this.backupDir}/${scope}.md`, content, "utf8");
+      const { writeFile: writeFile7, mkdir: mkdir7 } = await import('fs/promises');
+      await mkdir7(this.backupDir, { recursive: true });
+      await writeFile7(`${this.backupDir}/${scope}.md`, content, "utf8");
     } catch {
     }
   }
@@ -2112,6 +2323,97 @@ var SessionMemoryConsolidator = class {
   };
 };
 
+// src/types/errors.ts
+var ERROR_CODES = {
+  // Config
+  CONFIG_INVALID: "CONFIG_INVALID",
+  // Session
+  SESSION_NOT_FOUND: "SESSION_NOT_FOUND",
+  SESSION_CORRUPTED: "SESSION_CORRUPTED",
+  SESSION_WRITE_FAILED: "SESSION_WRITE_FAILED",
+  // File system
+  FS_READ_FAILED: "FS_READ_FAILED",
+  FS_DELETE_FAILED: "FS_DELETE_FAILED",
+  FS_ATOMIC_WRITE_FAILED: "FS_ATOMIC_WRITE_FAILED",
+  // General
+  VALIDATION_ERROR: "VALIDATION_ERROR",
+  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 ConfigError = class extends WrongStackError {
+  constructor(opts) {
+    super({
+      message: opts.message,
+      code: opts.code,
+      subsystem: "config",
+      severity: "fatal",
+      recoverable: false,
+      context: opts.context,
+      cause: opts.cause
+    });
+    this.name = "ConfigError";
+  }
+};
+var SessionError = class extends WrongStackError {
+  sessionId;
+  constructor(opts) {
+    super({
+      message: opts.message,
+      code: opts.code,
+      subsystem: "session",
+      severity: opts.code === ERROR_CODES.SESSION_WRITE_FAILED ? "error" : "warning",
+      recoverable: opts.code !== ERROR_CODES.SESSION_CORRUPTED,
+      context: { sessionId: opts.sessionId, ...opts.context },
+      cause: opts.cause
+    });
+    this.name = "SessionError";
+    this.sessionId = opts.sessionId;
+  }
+};
+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/storage/config-store.ts
 function stripEphemeralFields(cfg) {
   const env = cfg._envSource;
@@ -2143,7 +2445,11 @@ var DefaultConfigStore = class {
     const scrubbed = stripEphemeralFields(partial);
     const next = deepFreeze(structuredClone({ ...this.current, ...scrubbed }));
     if (next.version !== 1) {
-      throw new Error(`ConfigStore.update: version must remain 1, got ${String(next.version)}`);
+      throw new ConfigError({
+        message: `ConfigStore.update: version must remain 1, got ${String(next.version)}`,
+        code: ERROR_CODES.CONFIG_INVALID,
+        context: { field: "version", actual: next.version }
+      });
     }
     const prev = this.current;
     this.current = next;
@@ -2151,7 +2457,12 @@ var DefaultConfigStore = class {
       try {
         w(next, prev);
       } catch (err) {
-        console.error("[config-store] watcher threw:", err);
+        console.error(JSON.stringify({
+          level: "error",
+          event: "config_store.watcher_threw",
+          message: err instanceof Error ? err.message : String(err),
+          timestamp: (/* @__PURE__ */ new Date()).toISOString()
+        }));
       }
     }
     return next;
@@ -2496,7 +2807,13 @@ var DefaultConfigLoader = class {
           cfg = deepMerge2(cfg, patch);
         }
       } catch (err) {
-        console.warn(`Config source "${src.name}" failed`, err);
+        console.warn(JSON.stringify({
+          level: "warn",
+          event: "config.source_load_failed",
+          source: src.name,
+          message: err instanceof Error ? err.message : String(err),
+          timestamp: (/* @__PURE__ */ new Date()).toISOString()
+        }));
       }
     }
     if (opts.cliFlags) {
@@ -2559,7 +2876,12 @@ var DefaultConfigLoader = class {
       return parsed.value;
     } catch (err) {
       if (err.code === "ENOENT") return null;
-      console.warn("[config] Failed to load sync config:", err);
+      console.warn(JSON.stringify({
+        level: "warn",
+        event: "config.sync_load_failed",
+        message: err instanceof Error ? err.message : String(err),
+        timestamp: (/* @__PURE__ */ new Date()).toISOString()
+      }));
       return null;
     }
   }
@@ -2569,33 +2891,63 @@ var DefaultConfigLoader = class {
       raw = await fsp.readFile(file, "utf8");
     } catch (err) {
       if (err.code !== "ENOENT") {
-        console.warn(`[config] Failed to read "${file}":`, err);
+        console.warn(JSON.stringify({
+          level: "warn",
+          event: "config.read_failed",
+          path: file,
+          message: err instanceof Error ? err.message : String(err),
+          timestamp: (/* @__PURE__ */ new Date()).toISOString()
+        }));
       }
       return {};
     }
     const parsed = safeParse(raw);
     if (!parsed.ok || !parsed.value) {
-      console.warn(
-        `[config] Failed to parse "${file}": invalid JSON. Falling back to defaults for this layer.`
-      );
+      console.warn(JSON.stringify({
+        level: "warn",
+        event: "config.parse_failed",
+        path: file,
+        message: "invalid JSON \u2014 falling back to defaults for this layer",
+        timestamp: (/* @__PURE__ */ new Date()).toISOString()
+      }));
       return {};
     }
     return parsed.value;
   }
   validateBehavior(cfg) {
-    if (cfg.version === void 0) throw new Error("Config: missing version field");
-    if (cfg.version !== 1) throw new Error(`Config: unsupported version ${cfg.version}`);
+    if (cfg.version === void 0) throw new ConfigError({
+      message: "Config: missing version field",
+      code: ERROR_CODES.CONFIG_INVALID,
+      context: { field: "version" }
+    });
+    if (cfg.version !== 1) throw new ConfigError({
+      message: `Config: unsupported version ${cfg.version}`,
+      code: ERROR_CODES.CONFIG_INVALID,
+      context: { field: "version", actual: cfg.version }
+    });
     const c = cfg.context;
-    if (!c) throw new Error("Config: missing context section");
+    if (!c) throw new ConfigError({
+      message: "Config: missing context section",
+      code: ERROR_CODES.CONFIG_INVALID,
+      context: { field: "context" }
+    });
     const fields = ["warnThreshold", "softThreshold", "hardThreshold"];
     for (const f of fields) {
       const v = c[f];
       if (typeof v !== "number" || !Number.isFinite(v)) {
-        throw new Error(`Config: context.${String(f)} must be a finite number (got ${typeof v})`);
+        throw new ConfigError({
+          message: `Config: context.${String(f)} must be a finite number (got ${typeof v})`,
+          code: ERROR_CODES.CONFIG_INVALID,
+          context: { field: `context.${String(f)}`, actualType: typeof v }
+        });
       }
     }
     if (c.warnThreshold >= c.softThreshold || c.softThreshold >= c.hardThreshold) {
-      throw new Error("Config: context thresholds must satisfy warn < soft < hard");
+      throw new ConfigError({
+        message: "Config: context thresholds must satisfy warn < soft < hard",
+        code: ERROR_CODES.CONFIG_INVALID,
+        context: { warn: c.warnThreshold, soft: c.softThreshold, hard: c.hardThreshold }
+      });
     }
     if (c.mode !== void 0 && !isContextWindowModeId(c.mode)) {
       const known = listContextWindowModes().map((m) => m.id).join(", ");
@@ -2607,12 +2959,18 @@ var DefaultConfigLoader = class {
   }
   validateIdentity(cfg) {
     if (!cfg.provider) {
-      throw new Error(
-        "Config: no provider configured. Run `wstack init` or set WRONGSTACK_PROVIDER."
-      );
+      throw new ConfigError({
+        message: "Config: no provider configured. Run `wstack init` or set WRONGSTACK_PROVIDER.",
+        code: ERROR_CODES.CONFIG_INVALID,
+        context: { field: "provider" }
+      });
     }
     if (!cfg.model) {
-      throw new Error("Config: no model configured. Run `wstack init` or set WRONGSTACK_MODEL.");
+      throw new ConfigError({
+        message: "Config: no model configured. Run `wstack init` or set WRONGSTACK_MODEL.",
+        code: ERROR_CODES.CONFIG_INVALID,
+        context: { field: "model" }
+      });
     }
   }
 };
@@ -2710,7 +3068,10 @@ var RecoveryLock = class {
     if (this.sessionStore) {
       try {
         const data = await this.sessionStore.load(lock.sessionId);
-        const closed = data.events.some((e) => e.type === "session_end");
+        const lastEnd = data.events.findLastIndex((e) => e.type === "session_end");
+        const closed = lastEnd >= 0 && !data.events.slice(lastEnd + 1).some(
+          (e) => e.type === "user_input" || e.type === "llm_response" || e.type === "in_flight_start"
+        );
         if (closed) return null;
         messageCount = data.messages.length;
       } catch {
@@ -3114,6 +3475,27 @@ function renderPlainText(meta, events) {
   }
   return lines.join("\n");
 }
+function sessionScopedPath(dir, sessionId, suffix) {
+  if (!sessionId || sessionId.includes("\\") || sessionId.includes("..")) {
+    throw invalid(sessionId);
+  }
+  const resolved = path13.resolve(dir, `${sessionId}${suffix}`);
+  const rel = path13.relative(path13.resolve(dir), resolved);
+  if (rel.startsWith("..") || path13.isAbsolute(rel)) {
+    throw invalid(sessionId);
+  }
+  return resolved;
+}
+function invalid(sessionId) {
+  return new FsError({
+    message: `Invalid sessionId: ${sessionId}`,
+    code: ERROR_CODES.FS_DELETE_FAILED,
+    path: sessionId,
+    context: { reason: "path_traversal" }
+  });
+}
+
+// src/storage/annotations-store.ts
 var FILE_VERSION = 1;
 var MAX_TEXT_LENGTH = 2e3;
 var MAX_ANNOTATIONS = 1e3;
@@ -3151,13 +3533,28 @@ var AnnotationsStore = class {
   async add(input) {
     const text = input.text.trim();
     if (text.length === 0) {
-      throw new Error("Annotation text must be non-empty");
+      throw new WrongStackError({
+        message: "Annotation text must be non-empty",
+        code: ERROR_CODES.VALIDATION_ERROR,
+        subsystem: "general",
+        context: { field: "text", sessionId: input.sessionId }
+      });
     }
     if (text.length > MAX_TEXT_LENGTH) {
-      throw new Error(`Annotation text exceeds ${MAX_TEXT_LENGTH} chars (got ${text.length})`);
+      throw new WrongStackError({
+        message: `Annotation text exceeds ${MAX_TEXT_LENGTH} chars (got ${text.length})`,
+        code: ERROR_CODES.VALIDATION_ERROR,
+        subsystem: "general",
+        context: { field: "text", maxLength: MAX_TEXT_LENGTH, actualLength: text.length }
+      });
     }
     if (!Number.isInteger(input.atEventIndex) || input.atEventIndex < 0) {
-      throw new Error("atEventIndex must be a non-negative integer");
+      throw new WrongStackError({
+        message: "atEventIndex must be a non-negative integer",
+        code: ERROR_CODES.VALIDATION_ERROR,
+        subsystem: "general",
+        context: { field: "atEventIndex", value: input.atEventIndex }
+      });
     }
     const annotation = {
       id: randomUUID(),
@@ -3220,10 +3617,7 @@ var AnnotationsStore = class {
   }
   // ── Internals ──────────────────────────────────────────────────────────
   filePath(sessionId) {
-    if (!sessionId || sessionId.includes("/") || sessionId.includes("\\") || sessionId.includes("..")) {
-      throw new Error(`Invalid sessionId: ${sessionId}`);
-    }
-    return path13.join(this.dir, `${sessionId}.annotations.json`);
+    return sessionScopedPath(this.dir, sessionId, ".annotations.json");
   }
   async readFile(sessionId) {
     const fp = this.filePath(sessionId);
@@ -3365,32 +3759,46 @@ var ReplayLogStore = class {
    * by sessionId for stable output. Used by `wstack replay --list`.
    */
   async list() {
-    let entries;
-    try {
-      entries = await fsp.readdir(this.dir);
-    } catch (err) {
-      if (err.code === "ENOENT") return [];
-      return [];
-    }
     const out = [];
-    for (const name of entries) {
-      if (!name.endsWith(".replay.jsonl")) continue;
-      const sessionId = name.slice(0, -".replay.jsonl".length);
-      const all = await this.load(sessionId);
-      out.push({
-        sessionId,
-        entryCount: all.length,
-        path: path13.join(this.dir, name)
-      });
-    }
+    const scan = async (dir, prefix, depth) => {
+      let entries;
+      try {
+        entries = await fsp.readdir(dir, { withFileTypes: true });
+      } catch (err) {
+        if (depth === 0 && err.code !== "ENOENT") {
+          console.warn(JSON.stringify({
+            level: "warn",
+            event: "replay_log_store.list_readdir_failed",
+            dir,
+            message: err instanceof Error ? err.message : String(err),
+            timestamp: (/* @__PURE__ */ new Date()).toISOString()
+          }));
+        }
+        return;
+      }
+      for (const entry of entries) {
+        if (entry.name.startsWith(".")) continue;
+        if (entry.isDirectory()) {
+          if (depth === 0) await scan(path13.join(dir, entry.name), entry.name, depth + 1);
+          continue;
+        }
+        if (!entry.isFile() || !entry.name.endsWith(".replay.jsonl")) continue;
+        const base = entry.name.slice(0, -".replay.jsonl".length);
+        const sessionId = prefix ? `${prefix}/${base}` : base;
+        const all = await this.load(sessionId);
+        out.push({
+          sessionId,
+          entryCount: all.length,
+          path: path13.join(dir, entry.name)
+        });
+      }
+    };
+    await scan(this.dir, "", 0);
     return out.sort((a, b) => a.sessionId.localeCompare(b.sessionId));
   }
   // ── Internals ───────────────────────────────────────────────────────────
   filePath(sessionId) {
-    if (!sessionId || sessionId.includes("/") || sessionId.includes("\\") || sessionId.includes("..")) {
-      throw new Error(`Invalid sessionId: ${sessionId}`);
-    }
-    return path13.join(this.dir, `${sessionId}.replay.jsonl`);
+    return sessionScopedPath(this.dir, sessionId, ".replay.jsonl");
   }
   async readAll(sessionId) {
     const fp = this.filePath(sessionId);
@@ -3557,29 +3965,40 @@ var SessionRecovery = class {
    * recent crash first.
    */
   async listResumable() {
-    let entries;
-    try {
-      entries = await fsp.readdir(this.dir);
-    } catch (err) {
-      if (err.code === "ENOENT") return [];
-      return [];
-    }
     const out = [];
-    for (const name of entries) {
-      if (!name.endsWith(".jsonl")) continue;
-      const sessionId = name.slice(0, -".jsonl".length);
-      if (sessionId.includes(".replay") || sessionId.includes(".annotations")) continue;
-      const stale = await this.detectStale(sessionId);
-      if (stale) out.push(stale);
-    }
+    const collect = async (dir, prefix, depth) => {
+      let entries;
+      try {
+        entries = await fsp.readdir(dir, { withFileTypes: true });
+      } catch {
+        return;
+      }
+      for (const entry of entries) {
+        if (entry.name.startsWith(".")) continue;
+        if (entry.name === "shared" || entry.name === "subagents" || entry.name === "attachments")
+          continue;
+        if (entry.isDirectory()) {
+          if (depth === 0) {
+            await collect(path13.join(dir, entry.name), entry.name, depth + 1);
+          }
+          continue;
+        }
+        if (!entry.isFile() || !entry.name.endsWith(".jsonl")) continue;
+        if (entry.name === "_index.jsonl" || entry.name === "_mailbox.jsonl") continue;
+        const base = entry.name.slice(0, -".jsonl".length);
+        if (base.includes(".replay") || base.includes(".annotations") || base.includes(".audit"))
+          continue;
+        const sessionId = prefix ? `${prefix}/${base}` : base;
+        const stale = await this.detectStale(sessionId);
+        if (stale) out.push(stale);
+      }
+    };
+    await collect(this.dir, "", 0);
     return out.sort((a, b) => b.lastEventTs.localeCompare(a.lastEventTs));
   }
   // ── Internals ──────────────────────────────────────────────────────────
   filePath(sessionId) {
-    if (!sessionId || sessionId.includes("/") || sessionId.includes("\\") || sessionId.includes("..")) {
-      throw new Error(`Invalid sessionId: ${sessionId}`);
-    }
-    return path13.join(this.dir, `${sessionId}.jsonl`);
+    return sessionScopedPath(this.dir, sessionId, ".jsonl");
   }
 };
 var GENESIS_PREV = "0".repeat(64);
@@ -3605,7 +4024,7 @@ var ToolAuditLog = class {
    * intentional: the audit log is a record, not a cache.
    */
   async record(input) {
-    let entry = null;
+    let entry;
     await this.enqueue(input.sessionId, async () => {
       await withFileLock(this.filePath(input.sessionId), async () => {
         const entries = await this.readAll(input.sessionId);
@@ -3699,10 +4118,7 @@ var ToolAuditLog = class {
   }
   // ── Internals ────────────────────────────────────────────────────────────
   filePath(sessionId) {
-    if (!sessionId || sessionId.includes("/") || sessionId.includes("\\") || sessionId.includes("..")) {
-      throw new Error(`Invalid sessionId: ${sessionId}`);
-    }
-    return path13.join(this.dir, `${sessionId}.audit.jsonl`);
+    return sessionScopedPath(this.dir, sessionId, ".audit.jsonl");
   }
   async readAll(sessionId) {
     const fp = this.filePath(sessionId);
@@ -3879,6 +4295,387 @@ var SessionAnalyzer = class {
     return last - first;
   }
 };
+var REGISTRY_FILE = "session-registry.json";
+var HEARTBEAT_INTERVAL_MS = 5e3;
+var STALE_TIMEOUT_MS = 3e4;
+function pidAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+var SessionRegistry = class {
+  filePath;
+  heartbeatTimer = null;
+  currentSessionId = null;
+  constructor(globalRoot) {
+    this.filePath = path13.join(globalRoot, REGISTRY_FILE);
+  }
+  // ── Public API ──────────────────────────────────────────────────────────
+  /**
+   * Register the current session. Call once on session start.
+   * Starts the heartbeat timer.
+   */
+  async register(entry) {
+    this.currentSessionId = entry.sessionId;
+    const full = {
+      ...entry,
+      status: "active",
+      lastHeartbeatAt: (/* @__PURE__ */ new Date()).toISOString(),
+      agentCount: entry.agents?.length ?? 0,
+      agents: entry.agents ?? []
+    };
+    await this.atomicUpdate((registry) => {
+      const now = Date.now();
+      for (const [id, existing] of Object.entries(registry)) {
+        if (existing.pid === entry.pid) continue;
+        const heartbeatAge = now - new Date(existing.lastHeartbeatAt).getTime();
+        if (heartbeatAge > STALE_TIMEOUT_MS && !pidAlive(existing.pid)) {
+          delete registry[id];
+        }
+      }
+      registry[entry.sessionId] = full;
+    });
+    this.heartbeatTimer = setInterval(() => {
+      void this.heartbeat();
+    }, HEARTBEAT_INTERVAL_MS);
+    if (this.heartbeatTimer.unref) this.heartbeatTimer.unref();
+  }
+  /**
+   * Update agent status for the current session. Call on every
+   * significant status change (agent start, tool start, user wait, error).
+   */
+  async updateAgents(agents) {
+    if (!this.currentSessionId) return;
+    await this.atomicUpdate((registry) => {
+      const entry = registry[this.currentSessionId];
+      if (!entry) return;
+      entry.agents = agents;
+      entry.agentCount = agents.length;
+      const hasRunning = agents.some((a) => a.status === "running" || a.status === "streaming");
+      const hasWaiting = agents.some((a) => a.status === "waiting_user");
+      const hasError = agents.some((a) => a.status === "error");
+      entry.status = hasRunning ? "active" : hasWaiting ? "active" : hasError ? "active" : "idle";
+      entry.lastHeartbeatAt = (/* @__PURE__ */ new Date()).toISOString();
+    });
+  }
+  /**
+   * Mark the session as closing. Called during shutdown.
+   * Stops the heartbeat timer.
+   */
+  async markClosing() {
+    if (this.heartbeatTimer) {
+      clearInterval(this.heartbeatTimer);
+      this.heartbeatTimer = null;
+    }
+    if (!this.currentSessionId) return;
+    await this.atomicUpdate((registry) => {
+      const entry = registry[this.currentSessionId];
+      if (!entry) return;
+      entry.status = "closing";
+      entry.lastHeartbeatAt = (/* @__PURE__ */ new Date()).toISOString();
+    });
+  }
+  /**
+   * Remove the current session from the registry. Call on clean exit.
+   */
+  async unregister() {
+    if (this.heartbeatTimer) {
+      clearInterval(this.heartbeatTimer);
+      this.heartbeatTimer = null;
+    }
+    if (!this.currentSessionId) return;
+    const sid = this.currentSessionId;
+    this.currentSessionId = null;
+    await this.atomicUpdate((registry) => {
+      delete registry[sid];
+    });
+  }
+  /**
+   * List all non-stale sessions. Prunes stale entries automatically.
+   */
+  async list() {
+    const registry = await this.readAndPrune();
+    return Object.values(registry);
+  }
+  /**
+   * Get a single session entry by ID. Returns undefined if not found or stale.
+   */
+  async get(sessionId) {
+    const registry = await this.readAndPrune();
+    return registry[sessionId];
+  }
+  /**
+   * List all sessions for a specific project (by slug).
+   */
+  async listByProject(projectSlug2) {
+    const all = await this.list();
+    return all.filter((e) => e.projectSlug === projectSlug2);
+  }
+  /**
+   * Return the registry file path. Useful for WebUI to watch/read.
+   */
+  get registryPath() {
+    return this.filePath;
+  }
+  // ── Internal ────────────────────────────────────────────────────────────
+  async heartbeat() {
+    if (!this.currentSessionId) return;
+    try {
+      const raw = await fsp.readFile(this.filePath, "utf8").catch(() => "{}");
+      const registry = JSON.parse(raw);
+      const entry = registry[this.currentSessionId];
+      if (entry) {
+        entry.lastHeartbeatAt = (/* @__PURE__ */ new Date()).toISOString();
+        if (entry.status !== "closing") {
+          const hasRunning = (entry.agents ?? []).some(
+            (a) => a.status === "running" || a.status === "streaming"
+          );
+          entry.status = hasRunning ? "active" : "idle";
+        }
+        await this.writeAtomic(registry);
+      }
+    } catch {
+    }
+  }
+  async readAndPrune() {
+    try {
+      const raw = await fsp.readFile(this.filePath, "utf8");
+      const registry = JSON.parse(raw);
+      const now = Date.now();
+      let pruned = false;
+      for (const [id, entry] of Object.entries(registry)) {
+        const heartbeatAge = now - new Date(entry.lastHeartbeatAt).getTime();
+        if (heartbeatAge > STALE_TIMEOUT_MS && !pidAlive(entry.pid)) {
+          entry.status = "stale";
+          const startedAge = now - new Date(entry.startedAt).getTime();
+          if (startedAge > 5 * 6e4) {
+            delete registry[id];
+            pruned = true;
+          }
+        }
+      }
+      if (pruned) {
+        await this.writeAtomic(registry).catch(() => void 0);
+      }
+      return registry;
+    } catch {
+      return {};
+    }
+  }
+  async atomicUpdate(fn) {
+    const lockPath = `${this.filePath}.lock`;
+    const maxRetries = 5;
+    const retryDelayMs = 20;
+    for (let attempt = 0; attempt < maxRetries; attempt++) {
+      try {
+        await fsp.mkdir(path13.dirname(this.filePath), { recursive: true });
+        const lockHandle = await fsp.open(lockPath, "wx").catch(() => null);
+        if (!lockHandle) {
+          await new Promise((r) => setTimeout(r, retryDelayMs * (attempt + 1)));
+          continue;
+        }
+        try {
+          const raw = await fsp.readFile(this.filePath, "utf8").catch(() => "{}");
+          const registry = JSON.parse(raw);
+          fn(registry);
+          await this.writeAtomicLocked(registry);
+          return;
+        } finally {
+          await lockHandle.close();
+          await fsp.unlink(lockPath).catch(() => void 0);
+        }
+      } catch {
+        return;
+      }
+    }
+  }
+  async writeAtomicLocked(registry) {
+    const tmp = `${this.filePath}.${randomUUID().slice(0, 8)}.tmp`;
+    await fsp.writeFile(tmp, JSON.stringify(registry, null, 2), "utf8");
+    await fsp.rename(tmp, this.filePath);
+  }
+  /** Legacy write without lock — used by heartbeat for performance. */
+  async writeAtomic(registry) {
+    const tmp = `${this.filePath}.${randomUUID().slice(0, 8)}.tmp`;
+    await fsp.writeFile(tmp, JSON.stringify(registry, null, 2), "utf8");
+    await fsp.rename(tmp, this.filePath);
+  }
+};
+var _instance = null;
+function getSessionRegistry(globalRoot) {
+  if (!_instance && globalRoot) {
+    _instance = new SessionRegistry(globalRoot);
+  }
+  if (!_instance) {
+    throw new Error("SessionRegistry not initialized. Call getSessionRegistry(globalRoot) first.");
+  }
+  return _instance;
+}
+function hasSessionRegistry() {
+  return _instance !== null;
+}
+
+// src/agent-status-tracker.ts
+var AgentStatusTracker = class {
+  events;
+  registry;
+  leaderName;
+  // Live agent map: agentId → AgentEntry
+  agents = /* @__PURE__ */ new Map();
+  // Leader tracking
+  leaderStatus = "idle";
+  leaderCurrentTool;
+  leaderIterations = 0;
+  leaderToolCalls = 0;
+  unsubscribers = [];
+  constructor(opts) {
+    this.events = opts.events;
+    this.registry = opts.registry;
+    this.leaderName = opts.leaderName ?? "leader";
+  }
+  start() {
+    this.unsubscribers.push(
+      this.events.onPattern("agent.run.started", () => {
+        this.leaderStatus = "running";
+        this.leaderIterations++;
+        this.flush();
+      })
+    );
+    this.unsubscribers.push(
+      this.events.onPattern("agent.run.completed", () => {
+        this.leaderStatus = "idle";
+        this.leaderCurrentTool = void 0;
+        this.flush();
+      })
+    );
+    this.unsubscribers.push(
+      this.events.onPattern("agent.run.error", () => {
+        this.leaderStatus = "error";
+        this.leaderCurrentTool = void 0;
+        this.flush();
+      })
+    );
+    this.unsubscribers.push(
+      this.events.onPattern("tool.started", (_event, payload) => {
+        const p = payload;
+        if (p?.name) {
+          this.leaderCurrentTool = p.name;
+          this.leaderToolCalls++;
+        }
+        this.leaderStatus = "running";
+        this.flush();
+      })
+    );
+    this.unsubscribers.push(
+      this.events.onPattern("tool.executed", () => {
+        this.leaderCurrentTool = void 0;
+        this.flush();
+      })
+    );
+    this.unsubscribers.push(
+      this.events.onPattern("brain.ask_human", () => {
+        this.leaderStatus = "waiting_user";
+        this.flush();
+      })
+    );
+    this.unsubscribers.push(
+      this.events.onPattern("llm.stream_started", () => {
+        this.leaderStatus = "streaming";
+        this.flush();
+      })
+    );
+    this.unsubscribers.push(
+      this.events.onPattern("fleet.subagent.spawned", (_event, payload) => {
+        const p = payload;
+        if (p?.subagentId) {
+          this.agents.set(p.subagentId, {
+            id: p.subagentId,
+            name: p.name ?? p.subagentId,
+            status: "idle",
+            iterations: 0,
+            toolCalls: 0,
+            lastActivityAt: (/* @__PURE__ */ new Date()).toISOString()
+          });
+          this.flush();
+        }
+      })
+    );
+    this.unsubscribers.push(
+      this.events.onPattern("fleet.subagent.task_started", (_event, payload) => {
+        const p = payload;
+        if (p?.subagentId) {
+          const entry = this.agents.get(p.subagentId);
+          if (entry) {
+            entry.status = "running";
+            entry.iterations++;
+            entry.lastActivityAt = (/* @__PURE__ */ new Date()).toISOString();
+            this.flush();
+          }
+        }
+      })
+    );
+    this.unsubscribers.push(
+      this.events.onPattern("fleet.subagent.task_completed", (_event, payload) => {
+        const p = payload;
+        if (p?.subagentId) {
+          const entry = this.agents.get(p.subagentId);
+          if (entry) {
+            entry.status = "idle";
+            entry.lastActivityAt = (/* @__PURE__ */ new Date()).toISOString();
+            this.flush();
+          }
+        }
+      })
+    );
+    this.unsubscribers.push(
+      this.events.onPattern("fleet.subagent.error", (_event, payload) => {
+        const p = payload;
+        if (p?.subagentId) {
+          const entry = this.agents.get(p.subagentId);
+          if (entry) {
+            entry.status = "error";
+            entry.lastActivityAt = (/* @__PURE__ */ new Date()).toISOString();
+            this.flush();
+          }
+        }
+      })
+    );
+    this.unsubscribers.push(
+      this.events.onPattern("fleet.subagent.stopped", (_event, payload) => {
+        const p = payload;
+        if (p?.subagentId) {
+          this.agents.delete(p.subagentId);
+          this.flush();
+        }
+      })
+    );
+  }
+  stop() {
+    for (const unsub of this.unsubscribers) {
+      try {
+        unsub();
+      } catch {
+      }
+    }
+    this.unsubscribers = [];
+  }
+  flush() {
+    const leaderEntry = {
+      id: "leader",
+      name: this.leaderName,
+      status: this.leaderStatus,
+      currentTool: this.leaderCurrentTool,
+      iterations: this.leaderIterations,
+      toolCalls: this.leaderToolCalls,
+      lastActivityAt: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    const allAgents = [leaderEntry, ...this.agents.values()];
+    this.registry.updateAgents(allAgents).catch(() => void 0);
+  }
+};
 var DefaultSessionRewinder = class {
   constructor(sessionsDir, projectRoot) {
     this.sessionsDir = sessionsDir;
@@ -3927,7 +4724,11 @@ var DefaultSessionRewinder = class {
       }
     }
     if (targetIdx === -1) {
-      throw new Error(`Checkpoint ${checkpointIndex} not found`);
+      throw new SessionError({
+        message: `Checkpoint ${checkpointIndex} not found`,
+        code: ERROR_CODES.SESSION_NOT_FOUND,
+        context: { checkpointIndex }
+      });
     }
     const snapshotsToRevert = [];
     for (let i = targetIdx + 1; i < events.length; i++) {
@@ -4067,10 +4868,12 @@ async function saveTodosCheckpoint(filePath, sessionId, todos) {
   try {
     await atomicWrite(filePath, JSON.stringify(payload, null, 2), { mode: 384 });
   } catch (err) {
-    console.warn(
-      "[todos-checkpoint] save failed:",
-      err instanceof Error ? err.message : String(err)
-    );
+    console.warn(JSON.stringify({
+      level: "warn",
+      event: "todos_checkpoint.save_failed",
+      message: err instanceof Error ? err.message : String(err),
+      timestamp: (/* @__PURE__ */ new Date()).toISOString()
+    }));
   }
 }
 function attachTodosCheckpoint(state, filePath, sessionId) {
@@ -4080,7 +4883,13 @@ function attachTodosCheckpoint(state, filePath, sessionId) {
   const enqueueWrite = (todos) => {
     writeChain = writeChain.then(() => saveTodosCheckpoint(filePath, sessionId, todos)).catch((err) => {
       const msg = err instanceof Error ? err.message : String(err);
-      console.error(`[TodosCheckpoint] save failed for session ${sessionId}: ${msg}`);
+      console.error(JSON.stringify({
+        level: "error",
+        event: "todos_checkpoint.write_chain_failed",
+        sessionId,
+        message: msg,
+        timestamp: (/* @__PURE__ */ new Date()).toISOString()
+      }));
     });
     return writeChain;
   };
@@ -4216,19 +5025,29 @@ function deriveTodosFromPlanItem(plan, idOrIndex, subtasks) {
     id: `todo_${Date.now()}_plan`,
     content: item.title,
     status: "in_progress",
-    activeForm: item.title
+    activeForm: item.title,
+    promotedFromPlan: item.id
   });
   if (subtasks && subtasks.length > 0) {
     for (const st of subtasks) {
       todos.push({
         id: `todo_${Date.now()}_${randomUUID().slice(0, 6)}`,
         content: st,
-        status: "pending"
+        status: "pending",
+        promotedFromPlan: item.id
       });
     }
   }
   return { plan: updatedPlan, todos };
 }
+async function mutatePlan(filePath, sessionId, fn) {
+  return withFileLock(filePath, async () => {
+    const plan = await loadPlan(filePath) ?? emptyPlan(sessionId);
+    const updated = await fn(plan);
+    await savePlan(filePath, updated);
+    return updated;
+  });
+}
 function attachPlanCheckpoint(_state, _filePath, _sessionId) {
   return () => void 0;
 }
@@ -4379,6 +5198,14 @@ async function saveTasks(filePath, tasks) {
     );
   }
 }
+async function mutateTasks(filePath, sessionId, fn) {
+  return withFileLock(filePath, async () => {
+    const file = await loadTasks(filePath) ?? emptyTaskFile(sessionId);
+    const updated = await fn(file);
+    await saveTasks(filePath, updated);
+    return updated;
+  });
+}
 async function loadDirectorState(filePath) {
   let raw;
   try {
@@ -4576,7 +5403,7 @@ function envFlag(value) {
   return !/^(0|false|no|off)$/i.test(value.trim());
 }
 var COLOR = isColorTty();
-var wrap = (open5, close) => (s) => COLOR ? `\x1B[${open5}m${s}\x1B[${close}m` : s;
+var wrap = (open6, close) => (s) => COLOR ? `\x1B[${open6}m${s}\x1B[${close}m` : s;
 var color = {
   reset: wrap("0", "0"),
   bold: wrap("1", "22"),
@@ -4606,9 +5433,13 @@ function projectSlug(absRoot) {
 function slugify(name) {
   return name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 40) || "project";
 }
+function wstackGlobalRoot() {
+  const fromEnv = process.env["WRONGSTACK_HOME"];
+  if (fromEnv && fromEnv.trim().length > 0) return path13.resolve(fromEnv);
+  return path13.join(os.homedir(), ".wrongstack");
+}
 function resolveWstackPaths(opts) {
-  const home = opts.userHome ?? os.homedir();
-  const globalRoot = opts.globalRoot ?? path13.join(home, ".wrongstack");
+  const globalRoot = opts.globalRoot ?? (opts.userHome ? path13.join(opts.userHome, ".wrongstack") : wstackGlobalRoot());
   const hash = projectHash(opts.projectRoot);
   const slug = projectSlug(opts.projectRoot);
   const projectDir = path13.join(globalRoot, "projects", slug);
@@ -4648,56 +5479,6 @@ function resolveWstackPaths(opts) {
   };
 }
 
-// src/types/errors.ts
-var ERROR_CODES = {
-  // File system
-  FS_READ_FAILED: "FS_READ_FAILED",
-  FS_ATOMIC_WRITE_FAILED: "FS_ATOMIC_WRITE_FAILED"};
-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/storage/goal-store.ts
 var MAX_JOURNAL_ENTRIES = 500;
 function goalFilePath(projectRoot) {
@@ -4715,12 +5496,24 @@ async function loadGoal(filePath) {
   try {
     const parsed = JSON.parse(raw);
     if (parsed?.version !== 1 || typeof parsed.goal !== "string" || !Array.isArray(parsed.journal)) {
-      console.warn(`[goal-store] Corrupt goal.json at ${filePath} \u2014 invalid schema. Consider deleting it and re-creating.`);
+      console.warn(JSON.stringify({
+        level: "warn",
+        event: "goal_store.invalid_schema",
+        path: filePath,
+        message: "invalid schema \u2014 consider deleting and re-creating",
+        timestamp: (/* @__PURE__ */ new Date()).toISOString()
+      }));
       return null;
     }
     return parsed;
   } catch {
-    console.warn(`[goal-store] Corrupt goal.json at ${filePath} \u2014 JSON parse failed. Consider deleting it and re-creating.`);
+    console.warn(JSON.stringify({
+      level: "warn",
+      event: "goal_store.parse_failed",
+      path: filePath,
+      message: "JSON parse failed \u2014 consider deleting and re-creating",
+      timestamp: (/* @__PURE__ */ new Date()).toISOString()
+    }));
     return null;
   }
 }
@@ -5112,7 +5905,12 @@ var CloudSync = class {
     const res = await fetch(url, init);
     if (!res.ok) {
       const errText = await res.text();
-      throw new Error(`GitHub API ${method} ${pathSegment} failed (${res.status}): ${errText}`);
+      throw new WrongStackError({
+        message: `GitHub API ${method} ${pathSegment} failed (${res.status}): ${errText}`,
+        code: ERROR_CODES.UNKNOWN,
+        subsystem: "general",
+        context: { method, pathSegment, status: res.status, repo: `${owner}/${repo}` }
+      });
     }
     const text = await res.text();
     return text ? JSON.parse(text) : {};
@@ -5237,20 +6035,35 @@ var CloudSync = class {
 function resolvePulledCategoryPath(cat, localPath, rel, remotePath) {
   const directoryBacked = cat === "skills" || cat === "prompts";
   if (!directoryBacked) {
-    if (rel) throw new Error(`Refusing nested CloudSync path for file category: ${remotePath}`);
+    if (rel) throw new FsError({
+      message: `Refusing nested CloudSync path for file category: ${remotePath}`,
+      code: ERROR_CODES.FS_DELETE_FAILED,
+      path: remotePath,
+      context: { reason: "nested_file_category", category: cat }
+    });
     return localPath;
   }
   if (!rel) return localPath;
   const normalizedRel = path13.normalize(rel);
   const traversesUp = normalizedRel === ".." || normalizedRel.startsWith(`..${path13.sep}`);
   if (path13.isAbsolute(normalizedRel) || traversesUp) {
-    throw new Error(`Refusing CloudSync path traversal: ${remotePath}`);
+    throw new FsError({
+      message: `Refusing CloudSync path traversal: ${remotePath}`,
+      code: ERROR_CODES.FS_DELETE_FAILED,
+      path: remotePath,
+      context: { reason: "path_traversal", normalizedRel }
+    });
   }
   const dest = path13.resolve(localPath, normalizedRel);
   const root = path13.resolve(localPath);
-  const relative3 = path13.relative(root, dest);
-  if (relative3.startsWith("..") || path13.isAbsolute(relative3)) {
-    throw new Error(`Refusing CloudSync path outside category root: ${remotePath}`);
+  const relative4 = path13.relative(root, dest);
+  if (relative4.startsWith("..") || path13.isAbsolute(relative4)) {
+    throw new FsError({
+      message: `Refusing CloudSync path outside category root: ${remotePath}`,
+      code: ERROR_CODES.FS_DELETE_FAILED,
+      path: remotePath,
+      context: { reason: "outside_category_root", category: cat }
+    });
   }
   return dest;
 }
@@ -5305,6 +6118,7 @@ function isAllowed(type, level) {
 }
 function createSessionEventBridge(writer, level = "standard", options = {}) {
   const normalizedLevel = level ?? "standard";
+  const resolveWriter = typeof writer === "function" ? writer : () => writer;
   const progressCounters = /* @__PURE__ */ new Map();
   const toolProgressConfig = options.sampling?.toolProgress ?? {};
   const TOOL_PROGRESS_SAMPLE_RATE = toolProgressConfig.sampleRate ?? 8;
@@ -5329,13 +6143,26 @@ function createSessionEventBridge(writer, level = "standard", options = {}) {
       return isAllowed(type, normalizedLevel);
     },
     async append(event) {
-      if (!writer) return;
+      const target = resolveWriter();
+      if (!target) return;
       if (!isAllowed(event.type, normalizedLevel)) return;
       if (!shouldSample(event)) return;
       try {
-        await writer.append(event);
+        await target.append(event);
       } catch (err) {
       }
+    },
+    async appendBatch(events) {
+      const target = resolveWriter();
+      if (!target || events.length === 0) return;
+      const allowed = events.filter(
+        (e) => isAllowed(e.type, normalizedLevel) && shouldSample(e)
+      );
+      if (allowed.length === 0) return;
+      try {
+        await target.appendBatch(allowed);
+      } catch {
+      }
     }
   };
 }
@@ -5360,6 +6187,6 @@ function resolveSessionLoggingConfig(cfg) {
   };
 }
 
-export { ALL_SYNC_CATEGORIES, AnnotationsStore, CORE_RECONSTRUCT_EVENTS, CloudSync, ConfigMigrationError, DEFAULT_CONFIG_MIGRATIONS, DefaultAttachmentStore, DefaultConfigLoader, DefaultConfigStore, DefaultMemoryStore, DefaultPromptStore, DefaultSessionReader, DefaultSessionRewinder, DefaultSessionStore, DirectorStateCheckpoint, FileMemoryBackend, GraphMemoryBackend, MAX_JOURNAL_ENTRIES, MAX_PROGRESS_HISTORY, QueueStore, RecoveryLock, ReplayLogStore, STANDARD_AUDIT_EVENTS, SessionAnalyzer, SessionMemoryConsolidator, SessionRecovery, ToolAuditLog, addPlanItem, appendJournal, attachPlanCheckpoint, attachTodosCheckpoint, clearPlan, createSessionEventBridge, deriveTodosFromPlanItem, emptyGoal, emptyPlan, emptyTaskFile, formatGoal, formatPlan, formatPlanTemplates, getPlanTemplate, goalFilePath, listPlanTemplates, loadDirectorState, loadGoal, loadPlan, loadTasks, loadTodosCheckpoint, parseEntries, parseProgressFromText, recordProgress, removePlanItem, resolveAuditLevel, resolveSessionLoggingConfig, runConfigMigrations, saveGoal, savePlan, saveTasks, saveTodosCheckpoint, setPlanItemStatus, setProgress, summarizeUsage };
+export { ALL_SYNC_CATEGORIES, AgentStatusTracker, AnnotationsStore, CORE_RECONSTRUCT_EVENTS, CloudSync, ConfigMigrationError, DEFAULT_CONFIG_MIGRATIONS, DefaultAttachmentStore, DefaultConfigLoader, DefaultConfigStore, DefaultMemoryStore, DefaultPromptStore, DefaultSessionReader, DefaultSessionRewinder, DefaultSessionStore, DirectorStateCheckpoint, FileMemoryBackend, GraphMemoryBackend, MAX_JOURNAL_ENTRIES, MAX_PROGRESS_HISTORY, QueueStore, RecoveryLock, ReplayLogStore, STANDARD_AUDIT_EVENTS, SessionAnalyzer, SessionMemoryConsolidator, SessionRecovery, SessionRegistry, ToolAuditLog, addPlanItem, appendJournal, attachPlanCheckpoint, attachTodosCheckpoint, clearPlan, createSessionEventBridge, deriveTodosFromPlanItem, emptyGoal, emptyPlan, emptyTaskFile, formatGoal, formatPlan, formatPlanTemplates, getPlanTemplate, getSessionRegistry, goalFilePath, hasSessionRegistry, listPlanTemplates, loadDirectorState, loadGoal, loadPlan, loadTasks, loadTodosCheckpoint, mutatePlan, mutateTasks, parseEntries, parseProgressFromText, recordProgress, removePlanItem, resolveAuditLevel, resolveSessionLoggingConfig, runConfigMigrations, saveGoal, savePlan, saveTasks, saveTodosCheckpoint, setPlanItemStatus, setProgress, summarizeUsage };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map