@wrongstack/core 0.148.0 → 0.236.0

package/dist/defaults/index.js

@@ -3,7 +3,7 @@ import { randomBytes, createCipheriv, createDecipheriv, randomUUID, createHash }
 import * as fsp from 'fs/promises';
 import * as path11 from 'path';
 import { isAbsolute, resolve } from 'path';
-import * as fs4 from 'fs';
+import * as fs from 'fs';
 import * as os from 'os';
 import { hostname } from 'os';
 import { execFile } from 'child_process';
@@ -204,21 +204,27 @@ var COLORS = {
   trace: color.dim
 };
 var LOG_LEVELS = /* @__PURE__ */ new Set(["error", "warn", "info", "debug", "trace"]);
+var LOG_FORMATS = /* @__PURE__ */ new Set(["pretty", "json"]);
 var DefaultLogger = class _DefaultLogger {
+  /** How many file writes between rotation size checks (statSync is not free). */
+  static ROTATE_CHECK_EVERY = 100;
   level;
   file;
   bindings;
-  pretty;
+  format;
   stderr;
+  maxFileBytes;
+  writesSinceRotateCheck = 0;
   constructor(opts = {}) {
     this.level = opts.level ?? parseLogLevel(process.env.WRONGSTACK_LOG_LEVEL);
     this.file = opts.file;
     this.bindings = opts.bindings ?? {};
-    this.pretty = opts.pretty ?? true;
+    this.format = opts.format ?? parseLogFormat(process.env.WRONGSTACK_LOG_FORMAT);
     this.stderr = opts.stderr !== false;
+    this.maxFileBytes = opts.maxFileBytes ?? 10 * 1024 * 1024;
     if (this.file) {
       try {
-        fs4.mkdirSync(path11.dirname(this.file), { recursive: true });
+        fs.mkdirSync(path11.dirname(this.file), { recursive: true });
       } catch {
       }
     }
@@ -242,11 +248,30 @@ var DefaultLogger = class _DefaultLogger {
     return new _DefaultLogger({
       level: this.level,
       file: this.file,
-      pretty: this.pretty,
+      format: this.format,
       stderr: this.stderr,
+      maxFileBytes: this.maxFileBytes,
       bindings: { ...this.bindings, ...bindings }
     });
   }
+  /**
+   * Size-based rotation: when the file outgrows `maxFileBytes`, rename it to
+   * `<file>.1` (dropping the previous `.1`) so the live file restarts empty.
+   * Checked on the first write and every ROTATE_CHECK_EVERY writes after.
+   * Best-effort: a rename can fail on Windows while another process holds
+   * the file — the next check retries. Multiple processes appending to the
+   * same log all run this check; whoever crosses the threshold first wins.
+   */
+  maybeRotate(file) {
+    if (this.writesSinceRotateCheck++ % _DefaultLogger.ROTATE_CHECK_EVERY !== 0) return;
+    try {
+      const st = fs.statSync(file);
+      if (st.size < this.maxFileBytes) return;
+      fs.rmSync(`${file}.1`, { force: true });
+      fs.renameSync(file, `${file}.1`);
+    } catch {
+    }
+  }
   log(level, msg, ctx) {
     const r = LEVEL_RANK[level];
     const allowed = LEVEL_RANK[this.level];
@@ -258,13 +283,17 @@ var DefaultLogger = class _DefaultLogger {
     }
     if (this.file) {
       try {
-        fs4.appendFileSync(this.file, `${JSON.stringify(entry)}
+        this.maybeRotate(this.file);
+        fs.appendFileSync(this.file, `${JSON.stringify(entry)}
 `);
       } catch {
       }
     }
     if (!this.stderr) return;
-    if (r <= LEVEL_RANK.warn || this.level === "debug" || this.level === "trace") {
+    if (this.format === "json") {
+      writeErr(`${JSON.stringify(entry)}
+`);
+    } else {
       const head = `${color.dim(ts)} ${COLORS[level](level.toUpperCase().padEnd(5))} ${msg}`;
       if (ctx !== void 0) {
         writeErr(`${head} ${formatCtx(ctx)}
@@ -279,6 +308,9 @@ var DefaultLogger = class _DefaultLogger {
 function parseLogLevel(raw) {
   return raw && LOG_LEVELS.has(raw) ? raw : "info";
 }
+function parseLogFormat(raw) {
+  return raw && LOG_FORMATS.has(raw) ? raw : "pretty";
+}
 function formatCtx(ctx) {
   if (ctx instanceof Error) return color.dim(ctx.message);
   if (typeof ctx === "string") return color.dim(ctx);
@@ -292,7 +324,9 @@ function formatCtx(ctx) {
 // 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;
 }
@@ -452,7 +486,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;
     }
   }
@@ -479,11 +518,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: path11.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;
     }
   }
@@ -503,7 +556,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 {
@@ -659,10 +713,13 @@ var DefaultSessionStore = class _DefaultSessionStore {
       const stat6 = await fsp.stat(full);
       const summary = await this.summarize(id, stat6.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;
     }
@@ -670,17 +727,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 = path11.dirname(path11.join(this.dir, id));
     const base = path11.basename(id);
-    for (const ext of [".plan.json", ".todos.json"]) {
-      await fsp.unlink(path11.join(shardDir, `${base}${ext}`)).catch((err) => console.warn(`[session-store] delete ${ext} failed: ${err}`));
-    }
     const sessDir = path11.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(path11.join(shardDir, `${base}.plan.json`)),
+      fsp.unlink(path11.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) {
@@ -696,24 +784,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 = path11.join(dir, name);
+      try {
+        const stat6 = await fsp.stat(jsonlPath);
+        if (stat6.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 = path11.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 = path11.join(dateDir, file.name);
-        try {
-          const stat6 = await fsp.stat(jsonlPath);
-          if (stat6.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) {
@@ -802,7 +899,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(),
@@ -819,9 +916,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);
         }
@@ -840,25 +937,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 });
         }
       }
     }
@@ -878,7 +968,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;
@@ -905,7 +1012,7 @@ var FileSessionWriter = class {
   meta;
   events;
   closed = false;
-  closing = false;
+  closePromise = null;
   manifestFile;
   summary;
   tokenIn = 0;
@@ -914,12 +1021,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;
@@ -969,31 +1115,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
         );
@@ -1003,6 +1209,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") {
@@ -1036,9 +1247,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(),
@@ -1094,6 +1314,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 = [];
@@ -1156,6 +1382,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(),
@@ -1225,7 +1457,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;
@@ -1247,7 +1485,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()
+      }));
     }
   }
 };
@@ -1502,7 +1746,7 @@ var FileMemoryBackend = class {
     const line = `
 - [${entry.ts}] ${id}${meta} ${entry.text.replace(/\n/g, " ")}
 `;
-    const next = existing.trim() ? existing.replace(/\n+$/, "") + line : `# WrongStack Memory
+    const next = existing.trim() ? existing.replace(/\n+$/, "") + line : `# Agent Memory
 ${line}`;
     await atomicWrite(file, next);
   }
@@ -1670,10 +1914,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;
@@ -1921,6 +2164,158 @@ function labelOf(scope) {
   }
 }
 
+// src/types/errors.ts
+var ERROR_CODES = {
+  // Provider
+  PROVIDER_RATE_LIMITED: "PROVIDER_RATE_LIMITED",
+  PROVIDER_AUTH_FAILED: "PROVIDER_AUTH_FAILED",
+  PROVIDER_OVERLOADED: "PROVIDER_OVERLOADED",
+  PROVIDER_INVALID_REQUEST: "PROVIDER_INVALID_REQUEST",
+  PROVIDER_SERVER_ERROR: "PROVIDER_SERVER_ERROR",
+  PROVIDER_NETWORK_ERROR: "PROVIDER_NETWORK_ERROR",
+  PROVIDER_CONTEXT_OVERFLOW: "PROVIDER_CONTEXT_OVERFLOW",
+  // Tool
+  TOOL_NOT_FOUND: "TOOL_NOT_FOUND",
+  TOOL_PERMISSION_DENIED: "TOOL_PERMISSION_DENIED",
+  TOOL_EXECUTION_FAILED: "TOOL_EXECUTION_FAILED",
+  TOOL_TIMEOUT: "TOOL_TIMEOUT",
+  TOOL_INPUT_INVALID: "TOOL_INPUT_INVALID",
+  // Config
+  CONFIG_INVALID: "CONFIG_INVALID",
+  CONFIG_NOT_FOUND: "CONFIG_NOT_FOUND",
+  CONFIG_PARSE_FAILED: "CONFIG_PARSE_FAILED",
+  CONFIG_MIGRATION_NEEDED: "CONFIG_MIGRATION_NEEDED",
+  // Plugin
+  PLUGIN_LOAD_FAILED: "PLUGIN_LOAD_FAILED",
+  PLUGIN_API_MISMATCH: "PLUGIN_API_MISMATCH",
+  PLUGIN_MISSING_DEPENDENCY: "PLUGIN_MISSING_DEPENDENCY",
+  // Agent
+  AGENT_ITERATION_LIMIT: "AGENT_ITERATION_LIMIT",
+  AGENT_CONTEXT_OVERFLOW: "AGENT_CONTEXT_OVERFLOW",
+  AGENT_ABORTED: "AGENT_ABORTED",
+  AGENT_RUN_FAILED: "AGENT_RUN_FAILED",
+  // Session
+  SESSION_NOT_FOUND: "SESSION_NOT_FOUND",
+  SESSION_CORRUPTED: "SESSION_CORRUPTED",
+  SESSION_WRITE_FAILED: "SESSION_WRITE_FAILED",
+  // Container / Registry
+  CONTAINER_TOKEN_ALREADY_BOUND: "CONTAINER_TOKEN_ALREADY_BOUND",
+  CONTAINER_TOKEN_NOT_BOUND: "CONTAINER_TOKEN_NOT_BOUND",
+  CONTAINER_CIRCULAR_DEPENDENCY: "CONTAINER_CIRCULAR_DEPENDENCY",
+  REGISTRY_DUPLICATE: "REGISTRY_DUPLICATE",
+  REGISTRY_NOT_FOUND: "REGISTRY_NOT_FOUND",
+  REGISTRY_INVALID: "REGISTRY_INVALID",
+  // File system
+  FS_READ_FAILED: "FS_READ_FAILED",
+  FS_WRITE_FAILED: "FS_WRITE_FAILED",
+  FS_MKDIR_FAILED: "FS_MKDIR_FAILED",
+  FS_DELETE_FAILED: "FS_DELETE_FAILED",
+  FS_ATOMIC_WRITE_FAILED: "FS_ATOMIC_WRITE_FAILED",
+  // SDD (Spec-Driven Development)
+  SDD_VALIDATION_FAILED: "SDD_VALIDATION_FAILED",
+  SDD_PARSE_FAILED: "SDD_PARSE_FAILED",
+  SDD_INVALID_STATE: "SDD_INVALID_STATE",
+  SDD_NOT_READY: "SDD_NOT_READY",
+  // General
+  VALIDATION_ERROR: "VALIDATION_ERROR",
+  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 AgentError = class extends WrongStackError {
+  constructor(opts) {
+    super({
+      message: opts.message,
+      code: opts.code,
+      subsystem: "agent",
+      severity: opts.code === ERROR_CODES.AGENT_ABORTED ? "warning" : "error",
+      recoverable: opts.recoverable ?? opts.code === ERROR_CODES.AGENT_ITERATION_LIMIT,
+      context: opts.context,
+      cause: opts.cause
+    });
+    this.name = "AgentError";
+  }
+};
+function toWrongStackError(err, code = ERROR_CODES.AGENT_RUN_FAILED) {
+  if (err instanceof WrongStackError) return err;
+  const message = err instanceof Error ? err.message : String(err);
+  return new AgentError({
+    message,
+    code: code === "UNKNOWN" ? ERROR_CODES.AGENT_RUN_FAILED : code,
+    cause: err
+  });
+}
+var SddError = class extends WrongStackError {
+  constructor(opts) {
+    super({
+      message: opts.message,
+      code: opts.code,
+      subsystem: "sdd",
+      severity: opts.code === ERROR_CODES.SDD_PARSE_FAILED ? "warning" : "error",
+      recoverable: opts.code === ERROR_CODES.SDD_NOT_READY,
+      context: opts.context,
+      cause: opts.cause
+    });
+    this.name = "SddError";
+  }
+};
+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;
@@ -1952,7 +2347,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;
@@ -1960,7 +2359,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;
@@ -1988,10 +2392,91 @@ var ENCRYPTED_PREFIX = "enc:v1:";
 
 // src/security/secret-vault.ts
 init_atomic_write();
+
+// src/utils/deep-merge.ts
+var FORBIDDEN_PROTO_KEYS = /* @__PURE__ */ new Set([
+  "__proto__",
+  "constructor",
+  "prototype",
+  "__defineGetter__",
+  "__defineSetter__",
+  "__lookupGetter__",
+  "__lookupSetter__"
+]);
+function isPrimitiveArray(a) {
+  return a.every((v) => v === null || typeof v !== "object" && typeof v !== "function");
+}
+function deepMerge(base, patch, options = {}) {
+  const {
+    conflictResolution = "prefer-patch",
+    arrayMode = "replace",
+    protectProto = true,
+    onNonPrimitiveArrayReplace
+  } = options;
+  if (typeof base !== "object" || base === null) {
+    return conflictResolution === "prefer-patch" ? patch : base;
+  }
+  if (typeof patch !== "object" || patch === null) {
+    return conflictResolution === "prefer-patch" ? patch : base;
+  }
+  if (Array.isArray(base) && Array.isArray(patch)) {
+    if (arrayMode === "concat-primitives" && isPrimitiveArray(base) && isPrimitiveArray(patch)) {
+      return [.../* @__PURE__ */ new Set([...base, ...patch])];
+    }
+    return conflictResolution === "prefer-patch" ? patch : base;
+  }
+  if (Array.isArray(base) || Array.isArray(patch)) {
+    return conflictResolution === "prefer-patch" ? patch : base;
+  }
+  const baseObj = base;
+  const patchObj = patch;
+  const out = { ...baseObj };
+  for (const [k, v] of Object.entries(patchObj)) {
+    if (protectProto && FORBIDDEN_PROTO_KEYS.has(k)) continue;
+    const existing = out[k];
+    if (v !== null && typeof v === "object" && !Array.isArray(v) && existing !== null && typeof existing === "object" && !Array.isArray(existing)) {
+      out[k] = deepMerge(existing, v, options);
+    } else if (Array.isArray(v) && Array.isArray(existing)) {
+      if (onNonPrimitiveArrayReplace && !isPrimitiveArray(v)) {
+        onNonPrimitiveArrayReplace(k, existing.length, v.length);
+      }
+      out[k] = deepMerge(existing, v, options);
+    } else if (v !== void 0) {
+      if (onNonPrimitiveArrayReplace && Array.isArray(v) && !isPrimitiveArray(v)) {
+        const existingLen = Array.isArray(existing) ? existing.length : 0;
+        onNonPrimitiveArrayReplace(k, existingLen, v.length);
+      }
+      out[k] = v;
+    }
+  }
+  return out;
+}
+
+// src/security/secret-vault.ts
 var KEY_BYTES = 32;
 var IV_BYTES = 12;
 var TAG_BYTES = 16;
 var ALGO = "aes-256-gcm";
+var KEY_FILE_MODE = 384;
+function checkKeyFilePermissions(keyFile) {
+  if (process.platform === "win32") return;
+  try {
+    const stat6 = fs.statSync(keyFile);
+    const actualMode = stat6.mode & 511;
+    if (actualMode !== KEY_FILE_MODE) {
+      console.warn(JSON.stringify({
+        level: "warn",
+        event: "vault.key_file_wrong_permissions",
+        message: `Key file ${keyFile} has mode ${actualMode.toString(8)} \u2014 expected ${KEY_FILE_MODE.toString(8)}. Run: chmod ${KEY_FILE_MODE.toString(8)} ${keyFile}`,
+        keyFile,
+        expectedMode: KEY_FILE_MODE,
+        actualMode,
+        timestamp: (/* @__PURE__ */ new Date()).toISOString()
+      }));
+    }
+  } catch {
+  }
+}
 var DefaultSecretVault = class {
   keyFile;
   key;
@@ -2015,14 +2500,26 @@ var DefaultSecretVault = class {
     const rest = value.slice(ENCRYPTED_PREFIX.length);
     const parts = rest.split(":");
     if (parts.length !== 3) {
-      throw new Error("SecretVault: malformed encrypted value");
+      throw new ConfigError({
+        message: "SecretVault: malformed encrypted value",
+        code: ERROR_CODES.CONFIG_PARSE_FAILED,
+        context: { field: "encrypted_value" }
+      });
     }
     const [ivB64, tagB64, ctB64] = parts;
     const iv = Buffer.from(ivB64, "base64");
     const tag = Buffer.from(tagB64, "base64");
     const ct = Buffer.from(ctB64, "base64");
-    if (iv.length !== IV_BYTES) throw new Error("SecretVault: bad IV length");
-    if (tag.length !== TAG_BYTES) throw new Error("SecretVault: bad tag length");
+    if (iv.length !== IV_BYTES) throw new ConfigError({
+      message: "SecretVault: bad IV length",
+      code: ERROR_CODES.CONFIG_PARSE_FAILED,
+      context: { expected: IV_BYTES, actual: iv.length }
+    });
+    if (tag.length !== TAG_BYTES) throw new ConfigError({
+      message: "SecretVault: bad tag length",
+      code: ERROR_CODES.CONFIG_PARSE_FAILED,
+      context: { expected: TAG_BYTES, actual: tag.length }
+    });
     const key = this.loadOrCreateKey();
     const decipher = createDecipheriv(ALGO, key, iv);
     decipher.setAuthTag(tag);
@@ -2032,30 +2529,36 @@ var DefaultSecretVault = class {
   loadOrCreateKey() {
     if (this.key) return this.key;
     try {
-      const buf = fs4.readFileSync(this.keyFile);
+      const buf = fs.readFileSync(this.keyFile);
       if (buf.length !== KEY_BYTES) {
-        throw new Error(
-          `SecretVault: key file ${this.keyFile} is ${buf.length} bytes (expected ${KEY_BYTES}). Remove it manually to generate a new key.`
-        );
+        throw new ConfigError({
+          message: `SecretVault: key file ${this.keyFile} is ${buf.length} bytes (expected ${KEY_BYTES}). Remove it manually to generate a new key.`,
+          code: ERROR_CODES.CONFIG_INVALID,
+          context: { keyFile: this.keyFile, expectedBytes: KEY_BYTES, actualBytes: buf.length }
+        });
       }
       this.key = buf;
+      checkKeyFilePermissions(this.keyFile);
       return this.key;
     } catch (err) {
       if (err.code !== "ENOENT") throw err;
     }
-    fs4.mkdirSync(path11.dirname(this.keyFile), { recursive: true });
+    fs.mkdirSync(path11.dirname(this.keyFile), { recursive: true });
     const key = randomBytes(KEY_BYTES);
     try {
-      fs4.writeFileSync(this.keyFile, key, { mode: 384, flag: "wx" });
+      fs.writeFileSync(this.keyFile, key, { mode: 384, flag: "wx" });
     } catch (err) {
       if (err.code !== "EEXIST") throw err;
-      const buf = fs4.readFileSync(this.keyFile);
+      const buf = fs.readFileSync(this.keyFile);
       if (buf.length !== KEY_BYTES) {
-        throw new Error(
-          `SecretVault: key file ${this.keyFile} is ${buf.length} bytes (expected ${KEY_BYTES}). Remove it manually to generate a new key.`
-        );
+        throw new ConfigError({
+          message: `SecretVault: key file ${this.keyFile} is ${buf.length} bytes (expected ${KEY_BYTES}). Remove it manually to generate a new key.`,
+          code: ERROR_CODES.CONFIG_INVALID,
+          context: { keyFile: this.keyFile, expectedBytes: KEY_BYTES, actualBytes: buf.length }
+        });
       }
       this.key = buf;
+      checkKeyFilePermissions(this.keyFile);
       return this.key;
     }
     this.key = key;
@@ -2116,7 +2619,7 @@ async function rewriteConfigEncrypted(configPath, vault, patch) {
   await atomicWrite(configPath, JSON.stringify(encrypted, null, 2), { mode: 384 });
   await restrictFilePermissions(configPath);
 }
-async function migratePlaintextSecrets(configPath, vault) {
+async function migratePlaintextSecrets(configPath, vault, logger) {
   let raw;
   try {
     raw = await fsp.readFile(configPath, "utf8");
@@ -2133,11 +2636,14 @@ async function migratePlaintextSecrets(configPath, vault) {
   const migrated = walkCount(parsed, vault, counter);
   if (counter.n === 0) return { migrated: 0, file: configPath };
   await atomicWrite(configPath, JSON.stringify(migrated, null, 2), { mode: 384 });
-  await restrictFilePermissions(configPath);
+  await restrictFilePermissions(
+    configPath,
+    logger ? { warn: (msg) => logger.warn(msg) } : void 0
+  );
   return { migrated: counter.n, file: configPath };
 }
 async function restrictFilePermissions(filePath, opts) {
-  const warn = ((msg) => console.warn(msg));
+  const warn = opts?.warn ?? ((msg) => console.warn(msg));
   if (process.platform === "win32") {
     try {
       const { execFile: execFile2 } = await import('child_process');
@@ -2189,28 +2695,6 @@ function walkCount(node, vault, counter) {
   }
   return out;
 }
-var FORBIDDEN_PROTO_KEYS = /* @__PURE__ */ new Set([
-  "__proto__",
-  "constructor",
-  "prototype",
-  "__defineGetter__",
-  "__defineSetter__",
-  "__lookupGetter__",
-  "__lookupSetter__"
-]);
-function deepMerge(a, b) {
-  const out = { ...a };
-  for (const [k, v] of Object.entries(b)) {
-    if (FORBIDDEN_PROTO_KEYS.has(k)) continue;
-    const existing = out[k];
-    if (v !== null && typeof v === "object" && !Array.isArray(v) && existing !== null && typeof existing === "object" && !Array.isArray(existing)) {
-      out[k] = deepMerge(existing, v);
-    } else {
-      out[k] = v;
-    }
-  }
-  return out;
-}
 
 // src/storage/config-loader.ts
 init_atomic_write();
@@ -2393,43 +2877,16 @@ var defaultIndexing = {
   watchExternal: true,
   debounceMs: 400
 };
-function isPrimitiveArray(a) {
-  return a.every((v) => v === null || typeof v !== "object");
-}
-var FORBIDDEN_PROTO_KEYS2 = /* @__PURE__ */ new Set([
-  "__proto__",
-  "constructor",
-  "prototype",
-  "__defineGetter__",
-  "__defineSetter__",
-  "__lookupGetter__",
-  "__lookupSetter__"
-]);
 function deepMerge2(base, patch) {
-  if (typeof base !== "object" || base === null) return patch ?? base;
-  if (typeof patch !== "object" || patch === null) return base;
-  const out = { ...base };
-  for (const [k, v] of Object.entries(patch)) {
-    if (FORBIDDEN_PROTO_KEYS2.has(k)) continue;
-    const existing = out[k];
-    if (Array.isArray(v)) {
-      if (Array.isArray(existing) && isPrimitiveArray(v) && isPrimitiveArray(existing)) {
-        out[k] = [.../* @__PURE__ */ new Set([...existing, ...v])];
-      } else {
-        out[k] = v;
-        if (envBoolOptional(process.env.WRONGSTACK_DEBUG_CONFIG)) {
-          console.warn(
-            `[config] Non-primitive array for "${k}" replaced (global + local config merge). Global entries: ${existing?.length ?? 0}, local entries: ${v.length}.`
-          );
-        }
-      }
-    } else if (typeof v === "object" && v !== null && typeof existing === "object" && existing !== null) {
-      out[k] = deepMerge2(existing, v);
-    } else if (v !== void 0) {
-      out[k] = v;
-    }
+  const opts = { arrayMode: "concat-primitives" };
+  if (envBoolOptional(process.env.WRONGSTACK_DEBUG_CONFIG)) {
+    opts.onNonPrimitiveArrayReplace = (key, existingLen, patchLen) => {
+      console.warn(
+        `[config] Non-primitive array for "${key}" replaced (global + local config merge). Global entries: ${existingLen}, local entries: ${patchLen}.`
+      );
+    };
   }
-  return out;
+  return deepMerge(base, patch, opts);
 }
 var DefaultConfigLoader = class {
   paths;
@@ -2468,7 +2925,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) {
@@ -2531,7 +2994,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;
     }
   }
@@ -2541,33 +3009,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(", ");
@@ -2579,12 +3077,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" }
+      });
     }
   }
 };
@@ -2685,7 +3189,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 {
@@ -3230,6 +3737,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;
@@ -3254,13 +3762,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 {
+      }
     }
   };
 }
@@ -3314,10 +3835,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) {
@@ -3327,7 +3850,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;
   };
@@ -3466,14 +3995,16 @@ 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
       });
     }
   }
@@ -4378,91 +4909,6 @@ var AutoApprovePermissionPolicy = class _AutoApprovePermissionPolicy {
   }
 };
 
-// src/types/errors.ts
-var ERROR_CODES = {
-  // Provider
-  PROVIDER_RATE_LIMITED: "PROVIDER_RATE_LIMITED",
-  PROVIDER_AUTH_FAILED: "PROVIDER_AUTH_FAILED",
-  PROVIDER_OVERLOADED: "PROVIDER_OVERLOADED",
-  PROVIDER_INVALID_REQUEST: "PROVIDER_INVALID_REQUEST",
-  PROVIDER_SERVER_ERROR: "PROVIDER_SERVER_ERROR",
-  PROVIDER_NETWORK_ERROR: "PROVIDER_NETWORK_ERROR",
-  // Agent
-  AGENT_ITERATION_LIMIT: "AGENT_ITERATION_LIMIT",
-  AGENT_CONTEXT_OVERFLOW: "AGENT_CONTEXT_OVERFLOW",
-  AGENT_ABORTED: "AGENT_ABORTED",
-  AGENT_RUN_FAILED: "AGENT_RUN_FAILED",
-  // 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 AgentError = class extends WrongStackError {
-  constructor(opts) {
-    super({
-      message: opts.message,
-      code: opts.code,
-      subsystem: "agent",
-      severity: opts.code === ERROR_CODES.AGENT_ABORTED ? "warning" : "error",
-      recoverable: opts.recoverable ?? opts.code === ERROR_CODES.AGENT_ITERATION_LIMIT,
-      context: opts.context,
-      cause: opts.cause
-    });
-    this.name = "AgentError";
-  }
-};
-function toWrongStackError(err, code = ERROR_CODES.AGENT_RUN_FAILED) {
-  if (err instanceof WrongStackError) return err;
-  const message = err instanceof Error ? err.message : String(err);
-  return new AgentError({
-    message,
-    code: code === "UNKNOWN" ? ERROR_CODES.AGENT_RUN_FAILED : code,
-    cause: err
-  });
-}
-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/types/provider.ts
 var ProviderError = class extends WrongStackError {
   status;
@@ -5018,8 +5464,9 @@ function handleMessageStop(state, ev) {
   state.stopReason = ev.stopReason ?? "end_turn";
   state.usage = ev.usage ?? { input: 0, output: 0 };
 }
-async function streamProviderToResponse(provider, req, signal, ctx, events) {
+async function streamProviderToResponse(provider, req, signal, ctx, events, logger) {
   const state = createStreamingState(req.model);
+  logger.debug("Stream started", { providerId: provider.id, model: req.model });
   const iter = provider.stream(req, { signal })[Symbol.asyncIterator]();
   try {
     for (; ; ) {
@@ -5074,20 +5521,42 @@ async function streamProviderToResponse(provider, req, signal, ctx, events) {
           case "message_stop":
             handleMessageStop(state, ev);
             break;
-          default:
+          default: {
+            const unknownEv = ev;
+            logger.warn(`Stream received unknown event type: "${String(unknownEv.type)}"`, {
+              providerId: provider.id,
+              model: req.model,
+              eventType: String(unknownEv.type)
+            });
             break;
+          }
         }
       } catch (handlerErr) {
+        const errMsg = handlerErr instanceof Error ? handlerErr.message : String(handlerErr);
+        const evAny = ev;
+        logger.warn(`Stream handler error for event type "${String(evAny.type)}": ${errMsg}`, {
+          providerId: provider.id,
+          model: req.model,
+          eventType: String(evAny.type),
+          errorMessage: errMsg
+        });
         events.emit("provider.stream_error", {
           ctx,
-          eventType: ev.type,
-          msg: handlerErr instanceof Error ? handlerErr.message : String(handlerErr)
+          eventType: String(evAny.type),
+          msg: errMsg
         });
       }
     }
   } catch (err) {
     if (signal.aborted) {
       state.stopReason = "end_turn";
+      logger.debug("Stream aborted \u2014 returning partial state", {
+        providerId: provider.id,
+        model: req.model,
+        textBlockCount: state.textBuffers.length,
+        toolBlockCount: state.tools.size,
+        thinkingBlockCount: state.thinking.length
+      });
       return buildResponse(state);
     }
     throw err;
@@ -5109,10 +5578,29 @@ async function streamProviderToResponse(provider, req, signal, ctx, events) {
     } catch {
     }
   }
+  logger.debug("Stream completed", {
+    providerId: provider.id,
+    model: req.model,
+    stopReason: state.stopReason,
+    textBlockCount: state.textBuffers.length,
+    toolBlockCount: state.tools.size,
+    thinkingBlockCount: state.thinking.length,
+    usageInput: state.usage.input,
+    usageOutput: state.usage.output
+  });
   return buildResponse(state);
 }
 
 // src/core/provider-runner.ts
+function providerLogCtx(p, r) {
+  return {
+    providerId: p.id,
+    model: r.model,
+    streaming: p.capabilities.streaming,
+    msgCount: r.messages.length,
+    toolCount: r.tools?.length ?? 0
+  };
+}
 async function runProviderWithRetry(opts) {
   const { provider, request, signal, ctx, events, retry, logger, tracer } = opts;
   let attempt = 0;
@@ -5123,12 +5611,22 @@ async function runProviderWithRetry(opts) {
       "provider.streaming": provider.capabilities.streaming,
       "provider.attempt": attempt
     });
+    logger.debug(`Provider attempt ${attempt + 1} starting`, providerLogCtx(provider, request));
     try {
-      const res = provider.capabilities.streaming ? await streamProviderToResponse(provider, request, signal, ctx, events) : await provider.complete(request, { signal });
+      const res = provider.capabilities.streaming ? await streamProviderToResponse(provider, request, signal, ctx, events, logger) : await provider.complete(request, { signal });
       span?.setAttribute("provider.stopReason", res.stopReason);
       span?.setAttribute("provider.usage_in", res.usage.input);
       span?.setAttribute("provider.usage_out", res.usage.output);
       span?.end();
+      logger.info("Provider call succeeded", {
+        ...providerLogCtx(provider, request),
+        stopReason: res.stopReason,
+        usageInput: res.usage.input,
+        usageOutput: res.usage.output,
+        cacheRead: res.usage.cacheRead,
+        cacheWrite: res.usage.cacheWrite,
+        attempts: attempt + 1
+      });
       return res;
     } catch (err) {
       if (err instanceof Error) span?.recordError(err);
@@ -5147,11 +5645,27 @@ async function runProviderWithRetry(opts) {
             retryable: false
           });
         }
-        throw err;
+        logger.error(`Provider call failed after ${attempt + 1} attempt(s) \u2014 ${description}`, {
+          ...providerLogCtx(provider, request),
+          attempts: attempt + 1,
+          errorDescription: description,
+          status: isProviderErr ? err.status : void 0,
+          errorName: err instanceof Error ? err.name : void 0,
+          errorStack: err instanceof Error ? err.stack?.split("\n").slice(0, 3).join("\n") : void 0
+        });
+        throw toWrongStackError(err);
       }
       const delay = Math.round(retry.delayMs(attempt));
       const attemptNum = attempt + 1;
-      logger.warn(`Provider retry ${attemptNum} in ${delay}ms \u2014 ${description}`);
+      const maxAttempts = retry.maxAttempts(isProviderErr ? err : errAsErr);
+      logger.warn(`Provider retry ${attemptNum}/${maxAttempts} in ${delay}ms \u2014 ${description}`, {
+        ...providerLogCtx(provider, request),
+        attempt: attemptNum,
+        maxAttempts,
+        delayMs: delay,
+        errorDescription: description,
+        status: isProviderErr ? err.status : void 0
+      });
       if (isProviderErr) {
         events.emit("provider.retry", {
           providerId: err.providerId,
@@ -5238,22 +5752,31 @@ function estimateToolResultTokens(content) {
 function estimateTextTokens(text) {
   return RoughTokenEstimate(text);
 }
+function computeMessageTokens(msg) {
+  if (typeof msg.content === "string") return estimateTextTokens(msg.content);
+  let total = 0;
+  for (const b of msg.content) {
+    if (b.type === "text") total += estimateTextTokens(b.text);
+    else if (b.type === "tool_use") total += estimateToolInputTokens(b.input);
+    else if (b.type === "tool_result") total += estimateToolResultTokens(b.content);
+    else total += RoughTokenEstimate(JSON.stringify(b));
+  }
+  return total;
+}
 function estimateMessageTokens(messages) {
   let total = 0;
   for (const m of messages) {
-    if (typeof m.content === "string") {
-      total += estimateTextTokens(m.content);
-    } else {
-      for (const b of m.content) {
-        if (b.type === "text") total += estimateTextTokens(b.text);
-        else if (b.type === "tool_use") total += estimateToolInputTokens(b.input);
-        else if (b.type === "tool_result") total += estimateToolResultTokens(b.content);
-      }
+    if (typeof m._estTokens === "number" && m._estTokens > 0) {
+      total += m._estTokens;
+      continue;
     }
+    total += computeMessageTokens(m);
   }
   return total;
 }
 function estimateToolDefTokens(tool) {
+  const cached = tool._estDefTokens;
+  if (typeof cached === "number" && cached > 0) return cached;
   return RoughTokenEstimate(tool.name) + RoughTokenEstimate(tool.description ?? "") + RoughTokenEstimate(JSON.stringify(tool.inputSchema));
 }
 function estimateRequestTokens(messages, systemPrompt, tools, calibrationKey = CALIBRATION_GLOBAL_KEY) {
@@ -5263,6 +5786,11 @@ function estimateRequestTokens(messages, systemPrompt, tools, calibrationKey = C
   } else if (Array.isArray(messages)) {
     for (const m of messages) {
       if (typeof m === "object" && m !== null && "content" in m) {
+        const cached = m._estTokens;
+        if (typeof cached === "number" && cached > 0) {
+          messagesTokens += cached;
+          continue;
+        }
         const content = m.content;
         if (typeof content === "string") {
           messagesTokens += RoughTokenEstimate(content);
@@ -5355,6 +5883,18 @@ function findPreserveStart(messages, preserveK) {
 }
 function eliseOldToolResults(messages, opts) {
   const preserveStart = findPreserveStart(messages, opts.preserveK);
+  let hasOversized = false;
+  for (let i = 0; i < preserveStart && !hasOversized; i++) {
+    const msg = messages[i];
+    if (!msg || !Array.isArray(msg.content)) continue;
+    for (const b of msg.content) {
+      if (b.type === "tool_result" && estimateToolResultTokens(b.content) >= opts.eliseThreshold) {
+        hasOversized = true;
+        break;
+      }
+    }
+  }
+  if (!hasOversized) return { messages, saved: 0, changed: false };
   let saved = 0;
   let changed = false;
   const next = new Array(messages.length);
@@ -6248,6 +6788,15 @@ var AutoCompactionMiddleware = class _AutoCompactionMiddleware {
   static NOOP_RETRY_DELTA_TOKENS = 2e3;
   /** Tracks the most recent no-op attempt so we can avoid re-firing per turn. */
   lastNoopAttempt = null;
+  /**
+   * Cached token estimate from the last handler() invocation. When the
+   * message count and tool count haven't changed since the last estimate
+   * (autonomous idle loops), we skip the expensive O(n) token estimation
+   * and reuse this value. Reset to -1 when the context changes.
+   */
+  _cachedTokens = -1;
+  _cachedMsgCount = -1;
+  _cachedToolCount = -1;
   /**
    * @param compactor        Compactor to use for compaction.
    * @param maxContext Provider's max context window in tokens.
@@ -6283,12 +6832,24 @@ var AutoCompactionMiddleware = class _AutoCompactionMiddleware {
   }
   handler() {
     return async (ctx, next) => {
-      const tokens = this._estimator ? this._estimator(ctx) : estimateRequestTokensCalibrated(
-        ctx.messages,
-        ctx.systemPrompt,
-        ctx.tools ?? [],
-        `${ctx.provider?.id ?? "unknown"}/${ctx.model}`
-      ).total;
+      const msgCount = ctx.messages.length;
+      const toolCount = (ctx.tools ?? []).length;
+      let tokens;
+      if (this._estimator) {
+        tokens = this._estimator(ctx);
+      } else if (msgCount === this._cachedMsgCount && toolCount === this._cachedToolCount && this._cachedTokens >= 0) {
+        tokens = this._cachedTokens;
+      } else {
+        tokens = estimateRequestTokensCalibrated(
+          ctx.messages,
+          ctx.systemPrompt,
+          ctx.tools ?? [],
+          `${ctx.provider?.id ?? "unknown"}/${ctx.model}`
+        ).total;
+        this._cachedTokens = tokens;
+        this._cachedMsgCount = msgCount;
+        this._cachedToolCount = toolCount;
+      }
       const load = tokens / this._maxContext;
       const policy = this.policyProvider?.(ctx);
       const thresholds = policy?.thresholds ?? {
@@ -6525,7 +7086,7 @@ function createToolOutputSerializer(opts = {}) {
 }
 
 // src/execution/tool-executor.ts
-var ToolExecutor = class {
+var ToolExecutor = class _ToolExecutor {
   constructor(registry, opts) {
     this.registry = registry;
     this.opts = opts;
@@ -6537,6 +7098,10 @@ var ToolExecutor = class {
   }
   registry;
   opts;
+  /** Minimum gap between coalesced `partial_output` tool.progress emits. */
+  static PROGRESS_EMIT_INTERVAL_MS = 100;
+  /** Max chars of accumulated stream text carried per coalesced emit. */
+  static PROGRESS_TAIL_CHARS = 16384;
   serializer;
   iterationTimeoutMs;
   maxToolTimeoutMs;
@@ -6582,9 +7147,6 @@ Please call the tool again with arguments that match its inputSchema. You can us
         return { result, tool, durationMs: Date.now() - start };
       }
       const toolDangerousCaps = getDangerousCapabilities(tool);
-      if (toolDangerousCaps.length > 0) {
-        if (this.opts.events) ;
-      }
       if (hasMalformedArguments(use.input)) {
         const result = this.malformedInputResult(use, extractMalformedRaw(use.input));
         budget = this.decrementBudget(result, budget);
@@ -6822,17 +7384,48 @@ ${post.additionalContext}` };
       throw new Error(`Tool "${tool.name}" does not support streaming execution`);
     }
     const stream = tool.executeStream(input, ctx, { signal });
-    for await (const ev of stream) {
-      if (ev.type === "final") {
-        finalOutput = ev.output;
-        sawFinal = true;
-        break;
-      }
+    const iter = stream[Symbol.asyncIterator]();
+    let progressTail = "";
+    let lastProgressEmitAt = 0;
+    const emitProgress = (ev) => {
       this.opts.events?.emit("tool.progress", {
         name: tool.name,
         id: toolUseId ?? "<unknown>",
         event: ev
       });
+    };
+    const flushProgressTail = (force) => {
+      if (progressTail.length === 0) return;
+      const now = Date.now();
+      if (!force && now - lastProgressEmitAt < _ToolExecutor.PROGRESS_EMIT_INTERVAL_MS) return;
+      const text = progressTail;
+      progressTail = "";
+      lastProgressEmitAt = now;
+      emitProgress({ type: "partial_output", text });
+    };
+    try {
+      while (true) {
+        const { done, value: ev } = await iter.next();
+        if (done) break;
+        if (ev.type === "final") {
+          finalOutput = ev.output;
+          sawFinal = true;
+          break;
+        }
+        if (ev.type === "partial_output" && typeof ev.text === "string") {
+          progressTail += ev.text;
+          if (progressTail.length > _ToolExecutor.PROGRESS_TAIL_CHARS) {
+            progressTail = progressTail.slice(-_ToolExecutor.PROGRESS_TAIL_CHARS);
+          }
+          flushProgressTail(false);
+          continue;
+        }
+        flushProgressTail(true);
+        emitProgress(ev);
+      }
+      flushProgressTail(true);
+    } finally {
+      await iter.return?.(void 0);
     }
     if (!sawFinal) {
       throw new Error(`tool "${tool.name}" executeStream completed without a 'final' event`);
@@ -6943,9 +7536,11 @@ function extractMalformedRaw(input) {
 
 // src/utils/assert-never.ts
 function assertNever(x, message) {
-  throw new Error(
+  const err = new Error(
     `Unhandled case: ${JSON.stringify(x)}`
   );
+  err.name = "AssertNeverError";
+  throw err;
 }
 
 // src/execution/autonomous-runner.ts
@@ -6956,7 +7551,13 @@ var DoneConditionChecker = class {
       const result = compileUserRegex(condition.pattern, "");
       this.compiledRegex = result.ok ? result.regex : null;
       if (!result.ok) {
-        console.warn(`[DoneConditionChecker] Invalid regex pattern "${condition.pattern}": ${result.reason}`);
+        console.warn(JSON.stringify({
+          level: "warn",
+          event: "autonomous.done_condition_invalid_regex",
+          pattern: condition.pattern,
+          reason: result.reason,
+          timestamp: (/* @__PURE__ */ new Date()).toISOString()
+        }));
       }
     } else {
       this.compiledRegex = null;
@@ -7132,9 +7733,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 path11.resolve(fromEnv);
+  return path11.join(os.homedir(), ".wrongstack");
+}
 function resolveWstackPaths(opts) {
-  const home = opts.userHome ?? os.homedir();
-  const globalRoot = opts.globalRoot ?? path11.join(home, ".wrongstack");
+  const globalRoot = opts.globalRoot ?? (opts.userHome ? path11.join(opts.userHome, ".wrongstack") : wstackGlobalRoot());
   const hash = projectHash(opts.projectRoot);
   const slug = projectSlug(opts.projectRoot);
   const projectDir = path11.join(globalRoot, "projects", slug);
@@ -7191,12 +7796,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;
   }
 }
@@ -7310,7 +7927,14 @@ var EternalAutonomyEngine = class {
   stop() {
     this.stopRequested = true;
     this.currentCtrl?.abort();
-    void this.persistEngineState("stopped").catch(() => {
+    void this.persistEngineState("stopped").catch((err) => {
+      console.error(JSON.stringify({
+        level: "error",
+        event: "engine.persist_state_failed",
+        message: err instanceof Error ? err.message : String(err),
+        context: { expectedState: "stopped" },
+        timestamp: (/* @__PURE__ */ new Date()).toISOString()
+      }));
     });
     this.state = "stopped";
   }
@@ -8277,6 +8901,7 @@ var SubagentBudget = class _SubagentBudget {
 function makeAgentSubagentRunner(opts) {
   const format = opts.formatTaskInput ?? defaultFormatTaskInput;
   return async (task, ctx) => {
+    const taskStartedAt = Date.now();
     const factoryResult = await opts.factory(ctx.config);
     const { agent, events } = factoryResult;
     const detachFleet = opts.fleetBus?.attach(ctx.subagentId, events, task.id);
@@ -8373,7 +8998,7 @@ function makeAgentSubagentRunner(opts) {
       }),
       events.on("provider.text_delta", (e) => {
         ctx.budget.markActivity();
-        streamingTextAcc = (streamingTextAcc + e.text).slice(-200);
+        streamingTextAcc = (streamingTextAcc + e.text).slice(-2e3);
       })
     );
     const onParentAbort = () => aborter.abort();
@@ -8381,6 +9006,15 @@ function makeAgentSubagentRunner(opts) {
     let result;
     try {
       result = await agent.run(format(task, ctx.config), { signal: aborter.signal });
+      events.emit("subagent.task_completed", {
+        subagentId: ctx.subagentId,
+        taskId: task.id,
+        status: result.status === "done" ? "success" : "failed",
+        iterations: result.iterations,
+        toolCalls: ctx.budget.usage().toolCalls,
+        durationMs: Date.now() - taskStartedAt,
+        finalText: result.finalText?.trim() || void 0
+      });
     } finally {
       detachFleet?.();
       ctx.signal.removeEventListener("abort", onParentAbort);
@@ -8416,21 +9050,40 @@ function makeAgentSubagentRunner(opts) {
       if (budgetError) throw budgetError;
     }
     if (result.status === "failed") {
-      throw result.error instanceof Error ? result.error : new Error(String(result.error ?? "agent failed"));
+      throw result.error instanceof AgentError ? result.error : new AgentError({
+        message: result.error instanceof Error ? result.error.message : String(result.error ?? "agent failed"),
+        code: ERROR_CODES.AGENT_RUN_FAILED,
+        cause: result.error
+      });
     }
     if (result.status === "aborted") {
-      throw new Error("agent aborted");
+      throw new AgentError({
+        message: "agent aborted",
+        code: ERROR_CODES.AGENT_ABORTED
+      });
     }
     if (result.status === "max_iterations") {
-      throw new Error("agent exhausted iteration limit");
+      throw new AgentError({
+        message: "agent exhausted iteration limit",
+        code: ERROR_CODES.AGENT_ITERATION_LIMIT,
+        recoverable: true
+      });
     }
     const usage = ctx.budget.usage();
     const finalText = (result.finalText ?? "").trim();
     if (finalText.length === 0 && usage.toolCalls === 0) {
-      throw new Error("empty response");
+      throw new AgentError({
+        message: "empty response \u2014 agent produced no text and no tool calls",
+        code: ERROR_CODES.AGENT_RUN_FAILED,
+        context: { iterations: result.iterations }
+      });
     }
     if (finalText.length === 0 && lastToolFailed !== null) {
-      throw new Error(`tool failed: ${lastToolFailed}`);
+      throw new AgentError({
+        message: `unrecovered tool failure: ${lastToolFailed} \u2014 agent ended turn without acknowledging the error`,
+        code: ERROR_CODES.AGENT_RUN_FAILED,
+        context: { tool: lastToolFailed, iterations: result.iterations }
+      });
     }
     return {
       result: result.finalText,
@@ -8462,11 +9115,11 @@ var HEAVY_BUDGET = {
 };
 var TOOLS = {
   /** Pure read/inspect — safe for analysis and review agents. */
-  read: ["read", "grep", "glob", "search", "tree"],
+  read: ["read", "grep", "glob", "search", "tree", "mailbox"],
   /** Read + structured inspection (logs, diffs, json, dependency audit). */
-  inspect: ["read", "grep", "glob", "search", "tree", "json", "diff", "logs", "audit"],
+  inspect: ["read", "grep", "glob", "search", "tree", "json", "diff", "logs", "audit", "mailbox"],
   /** Read + edit (no shell). For agents that write code/docs but don't run it. */
-  write: ["read", "grep", "glob", "search", "tree", "write", "edit", "replace", "patch"],
+  write: ["read", "grep", "glob", "search", "tree", "write", "edit", "replace", "patch", "mailbox"],
   /** Full build loop: edit + run (lint/format/typecheck/test/bash). */
   build: [
     "read",
@@ -8483,16 +9136,17 @@ var TOOLS = {
     "lint",
     "format",
     "typecheck",
-    "test"
+    "test",
+    "mailbox"
   ],
   /** Version control. */
   vcs: ["read", "grep", "glob", "git", "diff"],
   /** Dependency management + CVE audit. */
-  deps: ["read", "grep", "glob", "install", "outdated", "audit", "json"],
+  deps: ["read", "grep", "glob", "install", "outdated", "audit", "json", "mailbox"],
   /** Documentation authoring. */
-  docs: ["read", "grep", "glob", "search", "tree", "write", "edit", "document"],
+  docs: ["read", "grep", "glob", "search", "tree", "write", "edit", "document", "mailbox"],
   /** Web research. */
-  research: ["read", "grep", "glob", "search", "fetch"]
+  research: ["read", "grep", "glob", "search", "fetch", "mailbox"]
 };
 
 // src/coordination/agents/phase1-discovery.ts
@@ -9290,15 +9944,44 @@ Working rules:
       id: "e2e",
       name: "E2E",
       role: "e2e",
-      tools: [...TOOLS.build, "fetch"],
+      tools: [
+        ...TOOLS.build,
+        "fetch",
+        "playwright_navigate",
+        "playwright_screenshot",
+        "playwright_click",
+        "playwright_type",
+        "playwright_evaluate",
+        "playwright_select_option",
+        "playwright_hover",
+        "playwright_fill_form",
+        "playwright_wait_for",
+        "playwright_press_key",
+        "playwright_drag"
+      ],
       prompt: `You are the E2E agent. Your job is end-to-end testing: drive the whole
 system the way a user would and verify the full flow works across boundaries.
 
 Scope:
 - Author end-to-end scenarios that exercise real user journeys
 - Drive UI/CLI/API across process and network boundaries
+- Use Playwright browser tools (navigate, click, type, screenshot, evaluate)
+  to automate web UI flows \u2014 open pages, interact with forms, capture evidence
 - Set up and tear down realistic test state
-- Capture failures with enough detail to reproduce (screenshots, logs)
+- Capture failures with enough detail to reproduce (screenshots, logs, page HTML)
+
+Playwright tools available (require the "playwright" MCP server to be enabled):
+  playwright_navigate(url)     \u2014 open a page at the given URL
+  playwright_screenshot()      \u2014 capture a full-page or viewport screenshot
+  playwright_click(selector)   \u2014 click on an element matching a CSS selector
+  playwright_type(selector, text) \u2014 type text into a focused input element
+  playwright_evaluate(script)  \u2014 run arbitrary JavaScript in the page context
+  playwright_select_option(selector, value) \u2014 pick a <select> dropdown option
+  playwright_hover(selector)   \u2014 hover the mouse over an element
+  playwright_fill_form(fields) \u2014 fill multiple form fields in one call
+  playwright_wait_for(selector) \u2014 block until an element appears on the page
+  playwright_press_key(key)    \u2014 press a keyboard key (Enter, Tab, Escape, \u2026)
+  playwright_drag(from, to)    \u2014 drag an element from one selector to another
 
 Input format you accept:
 { "task": "scenario | smoke | journey", "flow": "<user journey>", "surface": "ui | cli | api" }
@@ -9312,8 +9995,10 @@ Output: Markdown e2e report:
 Working rules:
 - Test the real flow end to end; don't stub the thing under test
 - Make scenarios deterministic \u2014 control time, randomness, and external state
-- On failure, capture artifacts (logs/screenshots) for reproduction
-- Keep scenarios independent so one failure doesn't cascade`
+- On failure, capture artifacts (screenshots, page HTML, logs) for reproduction
+- Keep scenarios independent so one failure doesn't cascade
+- For browser tests: playwright_navigate first, then interact, then playwright_screenshot as evidence
+- If playwright tools are unavailable, report it and fall back to API/CLI testing`
     },
     budget: HEAVY_BUDGET,
     capability: {
@@ -9326,10 +10011,106 @@ Working rules:
         "user journey",
         "smoke test",
         "playwright",
+        "browser",
+        "screenshot",
+        "web ui",
+        "headless",
         "cypress",
         "full flow",
         "browser test",
-        "acceptance test"
+        "acceptance test",
+        "navigate",
+        "click",
+        "form fill",
+        "dom",
+        "page load"
+      ]
+    }
+  },
+  {
+    config: {
+      id: "browser",
+      name: "Browser",
+      role: "browser",
+      tools: [
+        ...TOOLS.read,
+        "fetch",
+        "playwright_navigate",
+        "playwright_screenshot",
+        "playwright_click",
+        "playwright_type",
+        "playwright_evaluate",
+        "playwright_select_option",
+        "playwright_hover",
+        "playwright_fill_form",
+        "playwright_wait_for",
+        "playwright_press_key",
+        "playwright_drag"
+      ],
+      prompt: `You are the Browser agent. Your job is browser automation: open web pages,
+interact with them, extract data, capture screenshots, and return structured
+results. You are a read-focused agent \u2014 you drive the browser, not the filesystem.
+
+Scope:
+- Navigate to URLs and wait for pages to load
+- Take full-page or element screenshots as evidence
+- Click buttons, fill forms, select options, type text \u2014 full user simulation
+- Extract page content: text, HTML, element attributes, data tables
+- Evaluate JavaScript in the page context to extract structured data
+- Verify visual state (element visibility, text content, attribute values)
+
+Playwright tools available (require the "playwright" MCP server to be enabled):
+  playwright_navigate(url)          \u2014 open a page at the given URL
+  playwright_screenshot()           \u2014 capture a full-page or viewport screenshot
+  playwright_click(selector)        \u2014 click on an element matching a CSS selector
+  playwright_type(selector, text)   \u2014 type text into a focused input element
+  playwright_evaluate(script)       \u2014 run arbitrary JavaScript in the page context
+  playwright_select_option(selector, value) \u2014 pick a <select> dropdown option
+  playwright_hover(selector)        \u2014 hover the mouse over an element
+  playwright_fill_form(fields)      \u2014 fill multiple form fields in one call
+  playwright_wait_for(selector)     \u2014 block until an element appears on the page
+  playwright_press_key(key)         \u2014 press a keyboard key (Enter, Tab, Escape, \u2026)
+  playwright_drag(from, to)         \u2014 drag an element from one selector to another
+
+Input format you accept:
+{ "task": "navigate | screenshot | extract | interact | verify", "url": "<url>", "steps": ["step1", "step2"] }
+
+Output: Structured markdown report:
+- ## Page (URL, title, load status)
+- ## Actions Taken (step-by-step with timestamps)
+- ## Results (extracted data, element states, verification results)
+- ## Screenshots (list attached screenshot references)
+- ## Errors (any failures with stack traces)
+
+Working rules:
+- Always playwright_navigate first before any interaction
+- Always playwright_wait_for after navigation to ensure the page is ready
+- playwright_screenshot is your primary evidence \u2014 use it before and after interactions
+- Use playwright_evaluate for structured data extraction (JSON, text content)
+- If a selector fails, try alternative selectors before giving up
+- Report exact CSS selectors used \u2014 they're part of the evidence
+- If playwright tools are unavailable, report the error immediately \u2014 do not guess`
+    },
+    budget: MEDIUM_BUDGET,
+    capability: {
+      phase: "verify",
+      summary: "Browser automation: opens pages, clicks, types, screenshots, extracts data via Playwright headless Chromium.",
+      keywords: [
+        "browser",
+        "screenshot",
+        "navigate",
+        "web page",
+        "scrape",
+        "crawl",
+        "headless",
+        "chrome",
+        "open url",
+        "capture",
+        "page title",
+        "extract data",
+        "fill form",
+        "click button",
+        "take screenshot"
       ]
     }
   },
@@ -10778,7 +11559,7 @@ Working rules:
       id: "tech-stack",
       name: "Tech Stack Validator",
       role: "tech-stack",
-      tools: ["search", "fetch", "read", "grep", "glob", "outdated", "audit", "json"],
+      tools: ["search", "fetch", "read", "grep", "glob", "outdated", "audit", "json", "mailbox"],
       prompt: `You are the Tech Stack Validator \u2014 a single-shot validation agent that fires
 before any package, library, or framework choice is committed.
 
@@ -10786,6 +11567,16 @@ Your ONLY job: verify that a technology choice is current, real, and not obsolet
 You are the "this isn't code, this is 10-year-old technology" agent. Intervene
 hard when the LLM hallucinates a version number or suggests dead tech.
 
+## Before you begin
+
+Check the inter-agent mailbox for pending tasks. Other agents or the file-watcher
+may have left assign messages with dependency files to audit:
+- mailbox action=check
+
+If you find an assign message, use the specified file path and packages.
+When done, post results back:
+- mailbox action=send to=<sender> type=result subject="Tech stack audit results" body="..."
+
 ## Critical rules
 
 1. **Verify existence.** Search npm registry (fetch https://registry.npmjs.org/<pkg>/latest)
@@ -10844,11 +11635,11 @@ When APPROVED:
 **Install**: pnpm add <name>@^<major>.<minor>.0`
     },
     budget: {
-      timeoutMs: 6e4,
-      maxIterations: 5,
-      maxToolCalls: 20,
-      maxTokens: 4e4,
-      maxCostUsd: 0.1
+      timeoutMs: 12e4,
+      maxIterations: 10,
+      maxToolCalls: 40,
+      maxTokens: 6e4,
+      maxCostUsd: 0.25
     },
     capability: {
       phase: "meta",
@@ -11049,6 +11840,9 @@ Do not add prose, markdown, or code fences.`;
 
 // src/coordination/coordinator/error-classifier.ts
 function classifySubagentError(err, hints = {}) {
+  if (err instanceof AgentError && err.cause) {
+    return classifySubagentError(err.cause, hints);
+  }
   const cause = err instanceof Error ? { name: err.name, message: err.message, stack: err.stack } : void 0;
   if (err instanceof ProviderError) {
     const baseMessage2 = err.describe();
@@ -11081,7 +11875,7 @@ function classifySubagentError(err, hints = {}) {
   if (/agent exhausted iteration limit$/i.test(baseMessage)) {
     return { kind: "budget_iterations", message: baseMessage, retryable: false, cause };
   }
-  if (/empty response$/i.test(baseMessage)) {
+  if (/empty response/i.test(baseMessage)) {
     return { kind: "empty_response", message: baseMessage, retryable: false, cause };
   }
   if (/^tool failed: /i.test(baseMessage)) {
@@ -12245,7 +13039,14 @@ var ParallelEternalEngine = class {
   }
   stop() {
     this.stopRequested = true;
-    void this.persistState("stopped").catch(() => {
+    void this.persistState("stopped").catch((err) => {
+      console.error(JSON.stringify({
+        level: "error",
+        event: "engine.persist_state_failed",
+        message: err instanceof Error ? err.message : String(err),
+        context: { expectedState: "stopped" },
+        timestamp: (/* @__PURE__ */ new Date()).toISOString()
+      }));
     });
     this.state = "stopped";
   }
@@ -12845,24 +13646,36 @@ var InMemoryAgentBridge = class {
     return () => this.subscriptions.delete(handler);
   }
   async request(msg, timeoutMs) {
-    if (this.stopped) throw new Error("Bridge is stopped");
+    if (this.stopped) throw new AgentError({
+      message: "Bridge is stopped",
+      code: ERROR_CODES.AGENT_ABORTED
+    });
     const timeout = timeoutMs ?? this.timeoutMs;
     const correlationId = msg.id;
     if (this.inflightGuards.has(correlationId)) {
-      throw new Error(
-        `Bridge request id "${correlationId}" collides with an in-flight request \u2014 caller is reusing message ids`
-      );
+      throw new AgentError({
+        message: `Bridge request id "${correlationId}" collides with an in-flight request \u2014 caller is reusing message ids`,
+        code: ERROR_CODES.AGENT_RUN_FAILED,
+        context: { correlationId }
+      });
     }
     this.inflightGuards.add(correlationId);
     return new Promise((resolve5, reject) => {
       const timer = setTimeout(() => {
         this.inflightGuards.delete(correlationId);
         this.pendingRequests.delete(correlationId);
-        reject(new Error(`Request ${correlationId} timed out after ${timeout}ms`));
+        reject(new AgentError({
+          message: `Request ${correlationId} timed out after ${timeout}ms`,
+          code: ERROR_CODES.AGENT_RUN_FAILED,
+          context: { correlationId, timeoutMs: timeout }
+        }));
       }, timeout);
       if (!this.inflightGuards.has(correlationId)) {
         clearTimeout(timer);
-        reject(new Error("Bridge stopped"));
+        reject(new AgentError({
+          message: "Bridge stopped",
+          code: ERROR_CODES.AGENT_ABORTED
+        }));
         return;
       }
       this.pendingRequests.set(correlationId, {
@@ -12883,7 +13696,10 @@ var InMemoryAgentBridge = class {
     this.stopped = true;
     for (const [, p] of this.pendingRequests) {
       clearTimeout(p.timer);
-      p.reject(new Error("Bridge stopped"));
+      p.reject(new AgentError({
+        message: "Bridge stopped",
+        code: ERROR_CODES.AGENT_ABORTED
+      }));
     }
     this.pendingRequests.clear();
     this.inflightGuards.clear();
@@ -13654,7 +14470,23 @@ Bridge contract:
     subagents' context. Those are not yours to read.
   - Your final task output is what the Director sees. Be concise,
     structured, and self-contained \u2014 assume the Director will paste your
-    output into its own context.`;
+    output into its own context.
+
+Inter-agent mailbox (if you have the \`mail_send\`/\`mail_inbox\`/\`mailbox\` tools):
+  - You are part of a project-wide fleet that may span other terminals and
+    WebUIs. Your mailbox identity is \`<your-name>@<session-tag>\` (unique
+    per session); mail addressed to you, to your bare name, or broadcast
+    to \`*\` is injected into your conversation automatically before each
+    step \u2014 read it once, it is marked read.
+  - Broadcast milestones: when you complete a significant piece of work,
+    \`mail_send to="*"\` a one-line summary so parallel agents don't collide
+    with or duplicate it.
+  - Hand off matching work: if another online agent's role fits a follow-up
+    better (e.g. a reviewer while you just wrote code), \`mail_send\` it to
+    their exact id instead of doing everything yourself. Discover ids with
+    \`mailbox action=online\`.
+  - Answer your mail: reply to the sender's exact \`from\` id. When done with
+    an assigned task, post a \`result\` back to whoever assigned it.`;
 function composeDirectorPrompt(parts = {}) {
   const sections = [];
   const preamble = parts.directorPreamble ?? DEFAULT_DIRECTOR_PREAMBLE;
@@ -16704,6 +17536,77 @@ Remember: your job is to make the user a better developer, not just to complete
     tags: ["teaching", "mentor", "learning"],
     toolPreferences: ["read", "edit", "explain"],
     suggestedSkills: ["prompt-engineering", "skill-creator", "node-modern", "typescript-strict"]
+  },
+  {
+    id: "research-web",
+    name: "Research Web",
+    description: "Current-data research \u2014 search web, verify, inject findings into context",
+    prompt: `## Research Web Mode
+
+You are in research mode. Your role: find, verify, and incorporate
+current web data. Your training data is stale \u2014 every factual claim
+about version numbers, API surfaces, package status, or ecosystem
+changes must be verified against live sources.
+
+### When to research
+- The user asks "is this still the case?", "what's current?", "latest version?"
+- You're about to claim a version number, deprecation, or API change
+- You're comparing tools, packages, or approaches released in the last 12 months
+- You realize your knowledge may be >6 months old on a fast-moving topic
+
+### Research methodology
+1. **Search first, fetch selectively.** Use web_search with 5-8 results for
+   broad queries. Then web_fetch the 1-2 most authoritative results for detail.
+   Don't fetch every result \u2014 you'll burn tokens on noise.
+2. **Cross-reference.** One source is a data point. Two sources that agree
+   is a signal. Three is confirmation. Flag single-source claims as tentative.
+3. **Cite sources.** Every factual claim from web data must include where it
+   came from: domain name, and date if visible on the page.
+4. **Know when to stop.** 2-3 searches + 1-2 fetches is usually sufficient.
+   If you're on your 5th search without a clear answer, pause and tell the user
+   what you've found and what's still unclear \u2014 let them decide to dig deeper.
+5. **Inject findings for reuse.** After gathering current data, use
+   context_manager with add_note to inject a structured "Research Findings"
+   block into the conversation. Future turns see this and don't re-search.
+
+### Self-injection pattern
+When you discover current data mid-research, inject it so subsequent turns
+benefit without re-searching:
+
+web_search("Next.js middleware breaking changes 2025")
+  \u2192 Surfaced: Next.js 15.2 changed middleware runtime from edge to node
+web_fetch("https://nextjs.org/docs/messages/middleware-upgrade-guide")
+  \u2192 Confirmed: middleware now runs on Node.js runtime by default
+context_manager: add_note(
+  "## Research: Next.js middleware
+   - Next.js 15.2: middleware defaults to Node.js runtime (was edge)
+   - Breaking: edge-only APIs (crypto.subtle, WebSocket) no longer available
+   - Migration: use node:* equivalents or set runtime: 'edge' explicitly
+   - Source: nextjs.org/docs/messages/middleware-upgrade-guide"
+)
+
+The add_note persists in conversation \u2014 you won't re-search on the next turn.
+
+### Anti-patterns
+- Don't research things already in the conversation context (including
+  earlier add_note blocks you injected)
+- Don't treat a single web search result as ground truth \u2014 cross-reference
+- Don't inject raw JSON or search result dumps via add_note \u2014 summarize
+- Don't research while the user is waiting for a quick code edit \u2014 toggle
+  research-web mode only during analysis/discussion phases
+- Don't research-loop: 5+ searches on one topic \u2192 stop and ask the user
+
+### Exiting research mode
+When the user no longer needs current-data research, suggest switching back
+to the previous mode. You stay in research mode until explicitly told to
+switch \u2014 but don't force web searches on every turn. The methodology rules
+above already gate when to actually search.
+
+When you're done with research: suggest the user run \`/mode default\` or
+their previous mode.`,
+    tags: ["research", "web", "current-data", "up-to-date"],
+    toolPreferences: ["web_search", "web_fetch", "search", "fetch", "context_manager"],
+    suggestedSkills: ["research-web", "tech-stack", "node-modern", "security-scanner", "react-modern"]
   }
 ];
 
@@ -17329,7 +18232,10 @@ var TaskTracker = class {
     return this.graph;
   }
   addNode(node) {
-    if (!this.graph) throw new Error("No graph loaded");
+    if (!this.graph) throw new SddError({
+      message: "No graph loaded",
+      code: ERROR_CODES.SDD_INVALID_STATE
+    });
     const now = Date.now();
     const newNode = {
       ...node,
@@ -17347,7 +18253,10 @@ var TaskTracker = class {
     return newNode;
   }
   addEdge(from, to, type = "depends_on") {
-    if (!this.graph) throw new Error("No graph loaded");
+    if (!this.graph) throw new SddError({
+      message: "No graph loaded",
+      code: ERROR_CODES.SDD_INVALID_STATE
+    });
     this.graph.edges.push({
       id: crypto.randomUUID(),
       from,
@@ -17358,9 +18267,16 @@ var TaskTracker = class {
     this.persist();
   }
   updateNodeStatus(id, status, reason) {
-    if (!this.graph) throw new Error("No graph loaded");
+    if (!this.graph) throw new SddError({
+      message: "No graph loaded",
+      code: ERROR_CODES.SDD_INVALID_STATE
+    });
     const node = this.graph.nodes.get(id);
-    if (!node) throw new Error(`Node ${id} not found`);
+    if (!node) throw new SddError({
+      message: `Node ${id} not found`,
+      code: ERROR_CODES.SDD_NOT_READY,
+      context: { nodeId: id }
+    });
     const from = node.status;
     const now = Date.now();
     node.status = status;
@@ -17383,9 +18299,16 @@ var TaskTracker = class {
     this.persist();
   }
   updateNode(id, patch) {
-    if (!this.graph) throw new Error("No graph loaded");
+    if (!this.graph) throw new SddError({
+      message: "No graph loaded",
+      code: ERROR_CODES.SDD_INVALID_STATE
+    });
     const node = this.graph.nodes.get(id);
-    if (!node) throw new Error(`Node ${id} not found`);
+    if (!node) throw new SddError({
+      message: `Node ${id} not found`,
+      code: ERROR_CODES.SDD_NOT_READY,
+      context: { nodeId: id }
+    });
     if (patch.title !== void 0) node.title = patch.title;
     if (patch.description !== void 0) node.description = patch.description;
     if (patch.priority !== void 0) node.priority = patch.priority;
@@ -17504,7 +18427,12 @@ var TaskTracker = class {
   persist() {
     if (!this.graph) return;
     this.opts.store.saveGraph(this.graph).catch((err) => {
-      this.opts.onPersistError ? this.opts.onPersistError(err) : console.warn("[task-tracker] saveGraph failed:", err instanceof Error ? err.message : String(err));
+      this.opts.onPersistError ? this.opts.onPersistError(err) : console.warn(JSON.stringify({
+        level: "warn",
+        event: "task_tracker.save_graph_failed",
+        message: err instanceof Error ? err.message : String(err),
+        timestamp: (/* @__PURE__ */ new Date()).toISOString()
+      }));
     });
   }
 };
@@ -17557,12 +18485,14 @@ var TaskFlow = class {
     const analysis = parser.analyze(this.spec);
     this.emit("spec.analyzed", { analysis });
     if (analysis.completeness < 50) {
-      this.emit("error", {
-        phase: "analyzing",
-        error: new Error(`Spec completeness too low: ${analysis.completeness}%`)
+      const err = new SddError({
+        message: `Spec completeness too low: ${analysis.completeness}%`,
+        code: ERROR_CODES.SDD_VALIDATION_FAILED,
+        context: { completeness: analysis.completeness }
       });
+      this.emit("error", { phase: "analyzing", error: err });
       this.setPhase("failed");
-      throw new Error("Spec too incomplete");
+      throw err;
     }
     this.setPhase("generating");
     const generator = new TaskGenerator({ taskTracker: this.opts.tracker });
@@ -17570,7 +18500,11 @@ var TaskFlow = class {
     return this.graph;
   }
   async execute(ctx) {
-    if (!this.graph) throw new Error("No graph loaded. Call fromSpec first.");
+    if (!this.graph) throw new SddError({
+      message: "No graph loaded. Call fromSpec first.",
+      code: ERROR_CODES.SDD_INVALID_STATE,
+      context: { phase: this.phase }
+    });
     this.setPhase("executing");
     this.stopped = false;
     const pendingTasks = this.getExecutableTasks();
@@ -17610,7 +18544,11 @@ var TaskFlow = class {
   }
   async reviewTask(taskId, approved, comment) {
     const task = this.opts.tracker.getNode(taskId);
-    if (!task) throw new Error(`Task ${taskId} not found`);
+    if (!task) throw new SddError({
+      message: `Task ${taskId} not found`,
+      code: ERROR_CODES.SDD_NOT_READY,
+      context: { taskId }
+    });
     if (approved) {
       this.opts.tracker.updateNodeStatus(taskId, "completed", comment);
       this.emit("task.completed", { taskId });
@@ -18254,7 +19192,11 @@ var AISpecBuilder = class {
     switch (this.session.phase) {
       case "questioning":
         if (!this.session.spec) {
-          throw new Error("Cannot approve: no spec generated yet.");
+          throw new SddError({
+            message: "Cannot approve: no spec generated yet.",
+            code: ERROR_CODES.SDD_INVALID_STATE,
+            context: { phase: "questioning", sessionId: this.session.id }
+          });
         }
         this.session.phase = "spec_review";
         break;
@@ -18312,7 +19254,11 @@ var AISpecBuilder = class {
    */
   async saveSpec() {
     if (!this.session.spec) {
-      throw new Error("No spec to save.");
+      throw new SddError({
+        message: "No spec to save.",
+        code: ERROR_CODES.SDD_NOT_READY,
+        context: { sessionId: this.session.id }
+      });
     }
     await this.store.save(this.session.spec);
     return this.session.spec;
@@ -18327,17 +19273,30 @@ var AISpecBuilder = class {
     try {
       parsed = JSON.parse(jsonStr);
     } catch (e) {
-      throw new Error(`Invalid JSON for spec: ${e instanceof Error ? e.message : "parse error"}`);
+      throw new SddError({
+        message: "Invalid JSON for spec",
+        code: ERROR_CODES.SDD_PARSE_FAILED,
+        cause: e,
+        context: { detail: e instanceof Error ? e.message : "parse error" }
+      });
     }
     if (!parsed || typeof parsed !== "object") {
-      throw new Error("Spec JSON must be an object.");
+      throw new SddError({
+        message: "Spec JSON must be an object",
+        code: ERROR_CODES.SDD_VALIDATION_FAILED,
+        context: { actualType: typeof parsed }
+      });
     }
     const raw = parsed;
     const now = Date.now();
     const title = String(raw.title ?? this.session.title ?? "Untitled");
     const overview = String(raw.overview ?? "");
     if (!overview || overview === "undefined") {
-      throw new Error("Spec must have an overview.");
+      throw new SddError({
+        message: "Spec must have an overview",
+        code: ERROR_CODES.SDD_VALIDATION_FAILED,
+        context: { field: "overview", title }
+      });
     }
     const rawSections = Array.isArray(raw.sections) ? raw.sections : [];
     const sections = rawSections.filter((s) => s && typeof s === "object").map((s) => ({
@@ -19405,7 +20364,10 @@ var SddParallelRun = class {
       "\u2022 Do not ask before routine in-project tool use; if a permission gate appears, wait for that flow.",
       "\u2022 Keep output concise \u2014 summarize changes, do not transcribe files."
     ].join("\n");
-    if (!this.coordinator) throw new Error("SDD parallel runner requires a coordinator");
+    if (!this.coordinator) throw new SddError({
+      message: "SDD parallel runner requires a coordinator",
+      code: ERROR_CODES.SDD_INVALID_STATE
+    });
     const coordinator = this.coordinator;
     const spawns = subagentIds.map(
       (subagentId) => coordinator.spawn({
@@ -19417,7 +20379,10 @@ var SddParallelRun = class {
     );
     const spawnResults = await Promise.all(spawns);
     if (!spawnResults.every((r) => Boolean(r.subagentId))) {
-      throw new Error("One or more subagent spawns failed");
+      throw new SddError({
+        message: "One or more subagent spawns failed",
+        code: ERROR_CODES.SDD_INVALID_STATE
+      });
     }
     const assignPromises = tasks.map((task, i) => {
       const spec = {
@@ -20533,6 +21498,14 @@ var zaiVisionServer = () => ({
   ],
   permission: "auto"
 });
+var playwrightServer = () => ({
+  name: "playwright",
+  description: "Browser automation \u2014 navigate, screenshot, click, type, evaluate JS (headless Chromium)",
+  transport: "stdio",
+  command: "npx",
+  args: ["-y", "@modelcontextprotocol/server-playwright"],
+  permission: "confirm"
+});
 var miniMaxVisionServer = () => ({
   name: "minimax-vision",
   description: "MiniMax MCP \u2014 image understanding via understand_image",
@@ -20559,7 +21532,8 @@ var allServers = () => ({
   "google-maps": { ...googleMapsServer(), enabled: false },
   sentinel: { ...sentinelServer(), enabled: false },
   "zai-vision": { ...zaiVisionServer(), enabled: false },
-  "minimax-vision": { ...miniMaxVisionServer(), enabled: false }
+  "minimax-vision": { ...miniMaxVisionServer(), enabled: false },
+  playwright: { ...playwrightServer(), enabled: false }
 });
 
 export { AGENTS_BY_PHASE, AGENT_CATALOG, AISpecBuilder, ALL_AGENT_DEFINITIONS, ALL_FLEET_AGENTS, AUDIT_LOG_AGENT, AutoApprovePermissionPolicy, AutoCompactionMiddleware, AutoExecutor, AutonomousRunner, BUG_HUNTER_AGENT, BudgetExceededError, ConfigMigrationError, DEFAULT_AUTONOMY_CONFIG, DEFAULT_CONFIG_MIGRATIONS, DEFAULT_CONTEXT_CONFIG, DEFAULT_DIRECTOR_PREAMBLE, DEFAULT_DISPATCH_ROLE, DEFAULT_SUBAGENT_BASELINE, DEFAULT_TOOLS_CONFIG, DefaultAttachmentStore, DefaultConfigLoader, DefaultConfigStore, DefaultErrorHandler, DefaultHealthRegistry, DefaultLogger, DefaultMemoryStore, DefaultModeStore, DefaultModelsRegistry, DefaultMultiAgentCoordinator, DefaultPermissionPolicy, DefaultProviderRunner, DefaultRetryPolicy, DefaultSecretScrubber, DefaultSecretVault, DefaultSessionReader, DefaultSessionStore, DefaultSkillLoader, DefaultTaskStore, Director, DirectorStateCheckpoint, DoneConditionChecker, EternalAutonomyEngine, FLEET_ROSTER, FLEET_ROSTER_BUDGETS, FleetBus, FleetSpawnBudgetError, FleetUsageAggregator, HybridCompactor, InMemoryAgentBridge, InMemoryBridgeTransport, InMemoryMetricsSink, IntelligentCompactor, LLMSelector, NULL_FLEET_BUS, NoopMetricsSink, NoopTracer, OTelTracer, PROMETHEUS_CONTENT_TYPE, ParallelEternalEngine, QueueStore, REFACTOR_PLANNER_AGENT, RecoveryLock, SECURITY_SCANNER_AGENT, SPEC_TEMPLATES, SddParallelRun, SddTaskDecomposer, SelectiveCompactor, SessionAnalyzer, SpecDrivenDev, SpecParser, SpecStore, SpecVersioning, SubagentBudget, TaskFlow, TaskGenerator, TaskGraphStore, TaskTracker, ToolExecutor, addPlanItem, allServers, analyzeCriticalPath, applyRosterBudget, attachAutoExtend, attachPlanCheckpoint, attachTodosCheckpoint, awsServer, blockServer, braveSearchServer, buildGoalPreamble, buildOtlpMetricsRequest, buildOtlpTracesRequest, classifyFamily, clearPlan, composeDirectorPrompt, composeSubagentPrompt, context7Server, contextManagerTool, createAutoExecutor, createContextManagerTool, createDelegateTool, createMessage, createSessionEventBridge, createStrategyCompactor, decryptConfigSecrets, deriveTodosFromPlanItem, dispatchAgent, emptyPlan, encryptConfigSecrets, everArtServer, filesystemServer, formatPlan, formatPlanTemplates, getAgentDefinition, getPlanTemplate, getTemplate, githubServer, googleMapsServer, listPlanTemplates, listTemplates, loadDirectorState, loadPlan, loadProjectModes, loadTodosCheckpoint, loadUserModes, makeAgentSubagentRunner, makeAskTool, makeAssignTool, makeAutonomyPromptContributor, makeAwaitTasksTool, makeCollabDebugTool, makeDirectorSessionFactory, makeFleetEmitTool, makeFleetHealthTool, makeFleetSessionTool, makeFleetStatusTool, makeFleetUsageTool, makeLLMClassifier, makeRollUpTool, makeSpawnTool, makeTerminateTool, migratePlaintextSecrets, miniMaxVisionServer, removePlanItem, renderProgress, renderPrometheus, renderSpecAnalysis, renderTaskGraph, renderTaskList, resolveAuditLevel, resolveSessionLoggingConfig, rewriteConfigEncrypted, rosterSummaryFromConfigs, runConfigMigrations, savePlan, saveTodosCheckpoint, scoreAgents, sentinelServer, setPlanItemStatus, slackServer, startMetricsServer, startOtlpMetricsExporter, startOtlpTraceExporter, templateToMarkdown, wireMetricsToEvents, zaiVisionServer };