@wrongstack/core 0.1.2 → 0.1.3

package/dist/index.js

@@ -1,17 +1,155 @@
 import * as fsp from 'fs/promises';
 import * as path2 from 'path';
+import * as crypto2 from 'crypto';
 import { randomBytes, createHash, createCipheriv, createDecipheriv, randomUUID } from 'crypto';
 import * as os3 from 'os';
-import * as fs4 from 'fs';
+import * as fs5 from 'fs';
 import { EventEmitter } from 'events';
 import { spawn } from 'child_process';
 
+// src/types/errors.ts
+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 ToolError = class extends WrongStackError {
+  toolName;
+  constructor(opts) {
+    super({
+      message: opts.message,
+      code: opts.code,
+      subsystem: "tool",
+      recoverable: opts.recoverable,
+      context: { tool: opts.toolName, ...opts.context },
+      cause: opts.cause
+    });
+    this.name = "ToolError";
+    this.toolName = opts.toolName;
+  }
+};
+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 PluginError = class extends WrongStackError {
+  pluginName;
+  constructor(opts) {
+    super({
+      message: opts.message,
+      code: opts.code,
+      subsystem: "plugin",
+      severity: "error",
+      recoverable: opts.code === "PLUGIN_MISSING_DEPENDENCY",
+      context: { plugin: opts.pluginName, ...opts.context },
+      cause: opts.cause
+    });
+    this.name = "PluginError";
+    this.pluginName = opts.pluginName;
+  }
+};
+var AgentError = class extends WrongStackError {
+  constructor(opts) {
+    super({
+      message: opts.message,
+      code: opts.code,
+      subsystem: "agent",
+      severity: opts.code === "AGENT_ABORTED" ? "warning" : "error",
+      recoverable: opts.recoverable ?? opts.code === "AGENT_ITERATION_LIMIT",
+      context: opts.context,
+      cause: opts.cause
+    });
+    this.name = "AgentError";
+  }
+};
+function toWrongStackError(err, code = "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" ? "AGENT_RUN_FAILED" : code,
+    cause: err
+  });
+}
+var SessionError = class extends WrongStackError {
+  sessionId;
+  constructor(opts) {
+    super({
+      message: opts.message,
+      code: opts.code,
+      subsystem: "session",
+      severity: opts.code === "SESSION_WRITE_FAILED" ? "error" : "warning",
+      recoverable: opts.code !== "SESSION_CORRUPTED",
+      context: { sessionId: opts.sessionId, ...opts.context },
+      cause: opts.cause
+    });
+    this.name = "SessionError";
+    this.sessionId = opts.sessionId;
+  }
+};
+function isWrongStackError(err) {
+  return err instanceof WrongStackError;
+}
+function isToolError(err) {
+  return err instanceof ToolError;
+}
+function isConfigError(err) {
+  return err instanceof ConfigError;
+}
+function isPluginError(err) {
+  return err instanceof PluginError;
+}
+function isSessionError(err) {
+  return err instanceof SessionError;
+}
+function isAgentError(err) {
+  return err instanceof AgentError;
+}
+
 // src/kernel/container.ts
 var Container = class {
   entries = /* @__PURE__ */ new Map();
   bind(token, factory, opts = {}) {
     if (this.entries.has(token)) {
-      throw new Error(`Container: token "${token.description ?? "unknown"}" already bound`);
+      throw new WrongStackError({
+        message: `Container: token "${token.description ?? "unknown"}" already bound`,
+        code: "CONTAINER_TOKEN_ALREADY_BOUND",
+        subsystem: "container",
+        context: { token: token.description }
+      });
     }
     this.entries.set(token, {
       factory,
@@ -23,9 +161,12 @@ var Container = class {
   override(token, factory, opts = {}) {
     const existing = this.entries.get(token);
     if (!existing) {
-      throw new Error(
-        `Container: cannot override "${token.description ?? "unknown"}" \u2014 not bound`
-      );
+      throw new WrongStackError({
+        message: `Container: cannot override "${token.description ?? "unknown"}" \u2014 not bound`,
+        code: "CONTAINER_TOKEN_NOT_BOUND",
+        subsystem: "container",
+        context: { token: token.description }
+      });
     }
     this.entries.set(token, {
       factory,
@@ -37,9 +178,12 @@ var Container = class {
   decorate(token, decorator, owner = "core") {
     const existing = this.entries.get(token);
     if (!existing) {
-      throw new Error(
-        `Container: cannot decorate "${token.description ?? "unknown"}" \u2014 not bound`
-      );
+      throw new WrongStackError({
+        message: `Container: cannot decorate "${token.description ?? "unknown"}" \u2014 not bound`,
+        code: "CONTAINER_TOKEN_NOT_BOUND",
+        subsystem: "container",
+        context: { token: token.description }
+      });
     }
     existing.decorators.push(decorator);
     existing.cache = void 0;
@@ -48,9 +192,12 @@ var Container = class {
   resolve(token) {
     const entry = this.entries.get(token);
     if (!entry) {
-      throw new Error(
-        `Container: token "${token.description ?? "unknown"}" not bound`
-      );
+      throw new WrongStackError({
+        message: `Container: token "${token.description ?? "unknown"}" not bound`,
+        code: "CONTAINER_TOKEN_NOT_BOUND",
+        subsystem: "container",
+        context: { token: token.description }
+      });
     }
     if (entry.singleton && entry.cache !== void 0) {
       return entry.cache;
@@ -114,6 +261,20 @@ var Container = class {
 // src/kernel/pipeline.ts
 var Pipeline = class {
   chain = [];
+  errorHandler;
+  /**
+   * Install an error boundary. When a middleware throws or rejects, the
+   * handler is called and decides whether to swallow (continue with the
+   * pre-handler value) or rethrow. Without a handler, errors propagate.
+   *
+   * Wire one per pipeline at boot — the host CLI typically installs a
+   * single boundary that logs to the operational log and emits a
+   * `pipeline.error` event for /diag.
+   */
+  setErrorHandler(handler) {
+    this.errorHandler = handler;
+    return this;
+  }
   use(mw) {
     this.ensureUnique(mw.name);
     this.chain.push(mw);
@@ -198,6 +359,7 @@ var Pipeline = class {
   async run(input) {
     let index = -1;
     const chain = this.chain;
+    const errorHandler = this.errorHandler;
     const dispatch = async (i, value) => {
       if (i <= index) {
         throw new Error(`Pipeline: next() called multiple times in "${chain[index]?.name}"`);
@@ -205,7 +367,14 @@ var Pipeline = class {
       index = i;
       const mw = chain[i];
       if (!mw) return value;
-      return mw.handler(value, (v) => dispatch(i + 1, v));
+      try {
+        return await mw.handler(value, (v) => dispatch(i + 1, v));
+      } catch (err) {
+        if (!errorHandler) throw err;
+        const policy = await errorHandler({ middleware: mw.name, owner: mw.owner, err });
+        if (policy === "rethrow") throw err;
+        return value;
+      }
     };
     return dispatch(0, input);
   }
@@ -266,6 +435,17 @@ var EventBus = class {
   clear() {
     this.listeners.clear();
   }
+  /**
+   * V2-D: introspection helper. Pass an `event` to count handlers for a
+   * single key, or omit to get the total across every event. Used by the
+   * leak-detection smoke test to flag handler accumulation across runs.
+   */
+  listenerCount(event) {
+    if (event !== void 0) return this.listeners.get(event)?.size ?? 0;
+    let total = 0;
+    for (const set of this.listeners.values()) total += set.size;
+    return total;
+  }
 };
 
 // src/kernel/tokens.ts
@@ -279,6 +459,7 @@ var TOKENS = {
   Compactor: t("Compactor"),
   PathResolver: t("PathResolver"),
   ConfigLoader: t("ConfigLoader"),
+  ConfigStore: t("ConfigStore"),
   Renderer: t("Renderer"),
   InputReader: t("InputReader"),
   ErrorHandler: t("ErrorHandler"),
@@ -388,20 +569,26 @@ function asText(content) {
 }
 
 // src/types/provider.ts
-var ProviderError = class extends Error {
+var ProviderError = class extends WrongStackError {
   status;
   retryable;
   providerId;
   body;
-  cause;
   constructor(message, status, retryable, providerId, opts = {}) {
-    super(message);
+    super({
+      message,
+      code: providerStatusToCode(status, opts.body?.type),
+      subsystem: "provider",
+      severity: status >= 500 ? "error" : "warning",
+      recoverable: retryable,
+      context: { providerId, status },
+      cause: opts.cause
+    });
     this.name = "ProviderError";
     this.status = status;
     this.retryable = retryable;
     this.providerId = providerId;
     this.body = opts.body;
-    this.cause = opts.cause;
   }
   /**
    * Render a one-line, user-facing description. Designed for the CLI/TUI
@@ -442,6 +629,16 @@ function describeStatus(status, type) {
 function truncate(s, n) {
   return s.length <= n ? s : `${s.slice(0, n - 1)}\u2026`;
 }
+function providerStatusToCode(status, type) {
+  if (status === 0) return "PROVIDER_NETWORK_ERROR";
+  if (type === "rate_limit_error" || status === 429) return "PROVIDER_RATE_LIMITED";
+  if (type === "authentication_error" || status === 401) return "PROVIDER_AUTH_FAILED";
+  if (type === "overloaded_error" || status === 529) return "PROVIDER_OVERLOADED";
+  if (type === "invalid_request_error" || status === 400) return "PROVIDER_INVALID_REQUEST";
+  if (status === 408) return "PROVIDER_NETWORK_ERROR";
+  if (status >= 500) return "PROVIDER_SERVER_ERROR";
+  return "PROVIDER_INVALID_REQUEST";
+}
 
 // src/types/secret-vault.ts
 var ENCRYPTED_PREFIX = "enc:v1:";
@@ -668,8 +865,11 @@ async function atomicWrite(targetPath, content, opts = {}) {
     }
     try {
       const fh = await fsp.open(tmp, "r+");
-      await fh.sync();
-      await fh.close();
+      try {
+        await fh.sync();
+      } finally {
+        await fh.close();
+      }
     } catch {
     }
     let mode;
@@ -1107,6 +1307,122 @@ function createToolOutputSerializer(opts = {}) {
   }
   return { serialize, enforceCap, capBytes };
 }
+
+// src/utils/token-estimate.ts
+var RoughTokenEstimate = (text) => Math.max(1, Math.ceil(text.length / 4));
+function estimateToolInputTokens(input) {
+  if (typeof input === "string") return RoughTokenEstimate(input);
+  if (input !== null && typeof input === "object" && "__tokenEstimate" in input) {
+    return input.__tokenEstimate;
+  }
+  const str = typeof input === "object" ? JSON.stringify(input) : String(input);
+  const estimate = RoughTokenEstimate(str);
+  if (input !== null && typeof input === "object" && !Array.isArray(input)) {
+    input.__tokenEstimate = estimate;
+  }
+  return estimate;
+}
+function estimateToolResultTokens(content) {
+  if (typeof content === "string") return RoughTokenEstimate(content);
+  return RoughTokenEstimate(JSON.stringify(content));
+}
+function estimateTextTokens(text) {
+  return RoughTokenEstimate(text);
+}
+
+// src/utils/json-schema-validate.ts
+function validateAgainstSchema(value, schema) {
+  const errors = [];
+  walk(value, schema, "", errors);
+  return { ok: errors.length === 0, errors };
+}
+function walk(value, schema, path15, errors) {
+  if (schema.enum !== void 0) {
+    if (!schema.enum.some((e) => deepEqual(e, value))) {
+      errors.push({
+        path: path15 || "<root>",
+        message: `expected one of ${JSON.stringify(schema.enum)}, got ${JSON.stringify(value)}`
+      });
+      return;
+    }
+  }
+  if (typeof schema.type === "string") {
+    if (!checkType(value, schema.type)) {
+      errors.push({
+        path: path15 || "<root>",
+        message: `expected ${schema.type}, got ${describeType(value)}`
+      });
+      return;
+    }
+  }
+  if (schema.type === "object" && isPlainObject(value)) {
+    const obj = value;
+    for (const req of schema.required ?? []) {
+      if (!(req in obj)) {
+        errors.push({ path: joinPath(path15, req), message: "required property missing" });
+      }
+    }
+    if (schema.properties) {
+      for (const [key, subSchema] of Object.entries(schema.properties)) {
+        if (key in obj) {
+          walk(obj[key], subSchema, joinPath(path15, key), errors);
+        }
+      }
+    }
+  }
+  if (schema.type === "array" && Array.isArray(value) && schema.items) {
+    value.forEach((item, i) => walk(item, schema.items, `${path15}[${i}]`, errors));
+  }
+}
+function checkType(value, type) {
+  switch (type) {
+    case "string":
+      return typeof value === "string";
+    case "number":
+      return typeof value === "number" && !Number.isNaN(value);
+    case "integer":
+      return typeof value === "number" && Number.isInteger(value);
+    case "boolean":
+      return typeof value === "boolean";
+    case "null":
+      return value === null;
+    case "array":
+      return Array.isArray(value);
+    case "object":
+      return isPlainObject(value);
+    default:
+      return true;
+  }
+}
+function isPlainObject(v) {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function describeType(v) {
+  if (v === null) return "null";
+  if (Array.isArray(v)) return "array";
+  return typeof v;
+}
+function joinPath(parent, key) {
+  if (!parent) return key;
+  return `${parent}.${key}`;
+}
+function deepEqual(a, b) {
+  if (a === b) return true;
+  if (typeof a !== typeof b) return false;
+  if (a === null || b === null) return a === b;
+  if (Array.isArray(a) && Array.isArray(b)) {
+    return a.length === b.length && a.every((v, i) => deepEqual(v, b[i]));
+  }
+  if (typeof a === "object" && typeof b === "object") {
+    const ak = Object.keys(a);
+    const bk = Object.keys(b);
+    if (ak.length !== bk.length) return false;
+    return ak.every(
+      (k) => deepEqual(a[k], b[k])
+    );
+  }
+  return false;
+}
 var LEVEL_RANK = {
   error: 0,
   warn: 1,
@@ -1133,7 +1449,7 @@ var DefaultLogger = class _DefaultLogger {
     this.pretty = opts.pretty ?? true;
     if (this.file) {
       try {
-        fs4.mkdirSync(path2.dirname(this.file), { recursive: true });
+        fs5.mkdirSync(path2.dirname(this.file), { recursive: true });
       } catch {
       }
     }
@@ -1172,7 +1488,7 @@ var DefaultLogger = class _DefaultLogger {
     }
     if (this.file) {
       try {
-        fs4.appendFileSync(this.file, `${JSON.stringify(entry)}
+        fs5.appendFileSync(this.file, `${JSON.stringify(entry)}
 `);
       } catch {
       }
@@ -1220,7 +1536,7 @@ var DefaultPathResolver = class {
     while (dir !== root) {
       for (const marker of PROJECT_MARKERS) {
         try {
-          fs4.accessSync(path2.join(dir, marker));
+          fs5.accessSync(path2.join(dir, marker));
           return dir;
         } catch {
         }
@@ -1235,7 +1551,7 @@ var DefaultPathResolver = class {
     const abs = path2.isAbsolute(input) ? input : path2.resolve(this.cwd, input);
     let real;
     try {
-      real = fs4.realpathSync(abs);
+      real = fs5.realpathSync(abs);
     } catch {
       real = path2.normalize(abs);
     }
@@ -1259,267 +1575,81 @@ var DefaultPathResolver = class {
   }
 };
 
-// src/defaults/secret-scrubber.ts
-var PATTERNS = [
-  // Anchored at the start where possible so partial matches inside larger
-  // strings don't trigger false positives.
-  { type: "anthropic_key", regex: /(?<![A-Za-z0-9])sk-ant-api\d+-[A-Za-z0-9_-]{20,}(?![A-Za-z0-9])/g },
-  { type: "openai_key", regex: /(?<![A-Za-z0-9])sk-(?:proj-)?[A-Za-z0-9_-]{20,}(?![A-Za-z0-9])/g },
-  { type: "github_pat", regex: /(?<![A-Za-z0-9])ghp_[A-Za-z0-9]{36,}(?![A-Za-z0-9])/g },
-  { type: "github_pat_v2", regex: /(?<![A-Za-z0-9])github_pat_[A-Za-z0-9_]{50,}(?![A-Za-z0-9])/g },
-  { type: "aws_access_key", regex: /(?<![A-Za-z0-9])AKIA[0-9A-Z]{16}(?![A-Za-z0-9])/g },
-  { type: "gcp_key", regex: /(?<![A-Za-z0-9])AIza[0-9A-Za-z_-]{35}(?![A-Za-z0-9])/g },
-  { type: "slack_token", regex: /(?<![A-Za-z0-9-])xox[abpos]-[A-Za-z0-9-]{10,}(?![A-Za-z0-9-])/g },
-  { type: "stripe_key", regex: /(?<![A-Za-z0-9])sk_(?:live|test)_[A-Za-z0-9]{24,}(?![A-Za-z0-9])/g },
-  { type: "twilio_sid", regex: /(?<![A-Za-z0-9])AC[a-f0-9]{32}(?![A-Za-z0-9])/g },
-  {
-    type: "jwt",
-    // Anchored: look for literal "eyJ" which is unambiguous for JWT header
-    regex: /(?<![A-Za-z0-9/+=])eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}(?![A-Za-z0-9/+=])/g
-  },
-  {
-    type: "private_key",
-    // Anchored: start must be BEGIN, end must be END with no extra dashes after END
-    regex: /(?:^|\n)-----BEGIN (?:RSA|EC|OPENSSH|DSA|PGP)? ?PRIVATE KEY-----[\s\S]*?-----END[^-]*-----(?:\n|$)/g
-  },
-  { type: "mongodb_uri", regex: /mongodb(?:\+srv)?:\/\/[^\s"'`]+/g },
-  { type: "postgres_uri", regex: /postgres(?:ql)?:\/\/[^\s"'`]+/g },
-  { type: "mysql_uri", regex: /mysql:\/\/[^\s"'`]+/g },
-  { type: "redis_uri", regex: /redis:\/\/[^\s"'`]+/g },
-  { type: "bearer_token", regex: /(?<![A-Za-z0-9_.~+/-])Bearer\s+[A-Za-z0-9._~+/-]{20,}=*(?![A-Za-z0-9_.~+/-])/g },
-  {
-    type: "high_entropy_env",
-    // Value-side word boundary + length gate to avoid matching short random strings
-    regex: /\b([A-Z_]{4,}(?:KEY|TOKEN|SECRET|PASSWORD|PWD))\s*[:=]\s*['"]?([A-Za-z0-9_/+=-]{20,})['"]?(?!\s*[A-Za-z_]{4,}(?:KEY|TOKEN|SECRET|PASSWORD|PWD))/g
+// src/defaults/token-counter.ts
+var DefaultTokenCounter = class {
+  input = 0;
+  output = 0;
+  cacheRead = 0;
+  cacheWrite = 0;
+  costInput = 0;
+  costOutput = 0;
+  registry;
+  providerId;
+  events;
+  priceCache = /* @__PURE__ */ new Map();
+  constructor(opts = {}) {
+    this.registry = opts.registry;
+    this.providerId = opts.providerId;
+    this.events = opts.events;
   }
-];
-var DefaultSecretScrubber = class {
-  scrub(text) {
-    if (!text) return text;
-    let out = text;
-    for (const p of PATTERNS) {
-      out = out.replace(p.regex, (_match, group1, group2) => {
-        if (p.type === "high_entropy_env" && group1 && group2) {
-          return `${group1}=[REDACTED:${p.type}]`;
+  account(usage, model) {
+    this.input += usage.input;
+    this.output += usage.output;
+    this.cacheRead += usage.cacheRead ?? 0;
+    this.cacheWrite += usage.cacheWrite ?? 0;
+    const price = model ? this.priceCache.get(model) : void 0;
+    if (price) {
+      this.applyPrice(usage, price);
+    } else if (this.registry && this.providerId && model) {
+      void this.registry.getModel(this.providerId, model).then((m) => {
+        if (m) {
+          const p = priceFromModel(m);
+          this.priceCache.set(model, p);
+          this.applyPrice(usage, p);
         }
-        return `[REDACTED:${p.type}]`;
+      }).catch(() => {
+        this.events?.emit("token.cost_estimate_unavailable", { model: model ?? "<unknown>" });
+        return void 0;
       });
     }
-    return out;
   }
-  scrubObject(obj) {
-    const seen = /* @__PURE__ */ new WeakSet();
-    const visit = (v) => {
-      if (typeof v === "string") return this.scrub(v);
-      if (v === null || typeof v !== "object") return v;
-      if (seen.has(v)) return v;
-      seen.add(v);
-      if (Array.isArray(v)) return v.map(visit);
-      const out = {};
-      for (const [k, val] of Object.entries(v)) {
-        out[k] = visit(val);
-      }
-      return out;
+  /** Synchronous variant for code paths that have already resolved the model. */
+  accountWithModel(usage, resolved) {
+    this.input += usage.input;
+    this.output += usage.output;
+    this.cacheRead += usage.cacheRead ?? 0;
+    this.cacheWrite += usage.cacheWrite ?? 0;
+    const price = priceFromModel(resolved);
+    this.priceCache.set(resolved.modelId, price);
+    this.applyPrice(usage, price);
+  }
+  total() {
+    return {
+      input: this.input,
+      output: this.output,
+      cacheRead: this.cacheRead,
+      cacheWrite: this.cacheWrite
     };
-    return visit(obj);
   }
-};
-
-// src/defaults/retry-policy.ts
-var DefaultRetryPolicy = class {
-  shouldRetry(err, attempt) {
-    if (err instanceof ProviderError) {
-      if (!err.retryable) return false;
-      return attempt < this.maxAttempts(err);
-    }
-    const msg = err.message ?? "";
-    const isNetwork = /ECONN|ETIMEDOUT|ETIME|ENOTFOUND|EAI_AGAIN|fetch failed/i.test(msg);
-    if (isNetwork) return attempt < 2;
-    return false;
+  estimateCost() {
+    return {
+      input: round4(this.costInput),
+      output: round4(this.costOutput),
+      total: round4(this.costInput + this.costOutput),
+      currency: "USD"
+    };
   }
-  maxAttempts(err) {
-    if (err instanceof ProviderError) {
-      if (err.status === 429) return 5;
-      if (err.status === 529) return 3;
-      if (err.status >= 500) return 3;
-      return 0;
-    }
-    return 2;
+  cacheStats() {
+    const denom = this.cacheRead + this.input;
+    return {
+      readTokens: this.cacheRead,
+      writeTokens: this.cacheWrite,
+      hitRatio: denom === 0 ? 0 : this.cacheRead / denom
+    };
   }
-  delayMs(attempt) {
-    const base = 1e3;
-    const exp = base * 2 ** attempt;
-    const jitter = Math.random() * base;
-    return Math.min(3e4, exp + jitter);
-  }
-};
-
-// src/defaults/error-handler.ts
-function buildRecoveryStrategies(opts) {
-  return [
-    {
-      label: "context_overflow_reduce",
-      compactor: opts?.compactor,
-      async attempt(err, ctx) {
-        if (err instanceof ProviderError && (err.status === 413 || /context|too long|tokens/i.test(err.message))) {
-          if (this.compactor) {
-            try {
-              const report = await this.compactor.compact(ctx, { aggressive: true });
-              if (report.after < report.before) {
-                return {
-                  content: [{ type: "text", text: "[context compacted automatically \u2014 please retry]" }],
-                  stopReason: "end_turn",
-                  usage: { input: 0, output: 0 },
-                  model: ctx.model
-                };
-              }
-            } catch {
-            }
-          }
-          return null;
-        }
-        return null;
-      }
-    },
-    {
-      label: "rate_limit_backoff",
-      async attempt(err, ctx) {
-        if (err instanceof ProviderError && err.status === 429) {
-          const delayMs = err.body?.retryAfterMs ?? 5e3;
-          const delay = Math.max(1e3, Math.min(delayMs, 6e4));
-          await new Promise((r) => setTimeout(r, delay));
-          return {
-            content: [{ type: "text", text: "[rate limit backoff applied \u2014 please retry]" }],
-            stopReason: "end_turn",
-            usage: { input: 0, output: 0 },
-            model: ctx.model
-          };
-        }
-        return null;
-      }
-    },
-    {
-      label: "downgrade_model",
-      async attempt(err, ctx) {
-        if (err instanceof ProviderError && (err.status === 429 || err.status === 529 || err.status >= 500)) {
-          return null;
-        }
-        return null;
-      }
-    }
-  ];
-}
-var DEFAULT_RECOVERY_STRATEGIES = buildRecoveryStrategies();
-var DefaultErrorHandler = class {
-  strategies;
-  constructor(strategies = DEFAULT_RECOVERY_STRATEGIES) {
-    this.strategies = strategies;
-  }
-  classify(err) {
-    if (err instanceof DOMException && err.name === "AbortError") {
-      return { kind: "abort", retryable: false };
-    }
-    if (err instanceof Error && err.name === "AbortError") {
-      return { kind: "abort", retryable: false };
-    }
-    if (err instanceof ProviderError) {
-      if (err.status === 429) return { kind: "rate_limit", retryable: true };
-      if (err.status === 529) return { kind: "overloaded", retryable: true };
-      if (err.status >= 500) return { kind: "server", retryable: true };
-      if (err.status === 413 || /context|too long|tokens/i.test(err.message)) {
-        return { kind: "context_overflow", retryable: false };
-      }
-      if (err.status >= 400) return { kind: "client", retryable: false };
-    }
-    if (err instanceof Error && /ECONN|ETIMEDOUT|ETIME|ENOTFOUND|EAI_AGAIN|fetch failed/i.test(err.message)) {
-      return { kind: "network", retryable: true };
-    }
-    return { kind: "unknown", retryable: false };
-  }
-  async recover(err, ctx) {
-    for (const strategy of this.strategies) {
-      const result = await strategy.attempt(err, ctx);
-      if (result !== null) return result;
-    }
-    return null;
-  }
-};
-
-// src/defaults/token-counter.ts
-var DefaultTokenCounter = class {
-  input = 0;
-  output = 0;
-  cacheRead = 0;
-  cacheWrite = 0;
-  costInput = 0;
-  costOutput = 0;
-  registry;
-  providerId;
-  events;
-  priceCache = /* @__PURE__ */ new Map();
-  constructor(opts = {}) {
-    this.registry = opts.registry;
-    this.providerId = opts.providerId;
-    this.events = opts.events;
-  }
-  account(usage, model) {
-    this.input += usage.input;
-    this.output += usage.output;
-    this.cacheRead += usage.cacheRead ?? 0;
-    this.cacheWrite += usage.cacheWrite ?? 0;
-    const price = model ? this.priceCache.get(model) : void 0;
-    if (price) {
-      this.applyPrice(usage, price);
-    } else if (this.registry && this.providerId && model) {
-      void this.registry.getModel(this.providerId, model).then((m) => {
-        if (m) {
-          const p = priceFromModel(m);
-          this.priceCache.set(model, p);
-          this.applyPrice(usage, p);
-        }
-      }).catch(() => {
-        this.events?.emit("token.cost_estimate_unavailable", { model: model ?? "<unknown>" });
-        return void 0;
-      });
-    }
-  }
-  /** Synchronous variant for code paths that have already resolved the model. */
-  accountWithModel(usage, resolved) {
-    this.input += usage.input;
-    this.output += usage.output;
-    this.cacheRead += usage.cacheRead ?? 0;
-    this.cacheWrite += usage.cacheWrite ?? 0;
-    const price = priceFromModel(resolved);
-    this.priceCache.set(resolved.modelId, price);
-    this.applyPrice(usage, price);
-  }
-  total() {
-    return {
-      input: this.input,
-      output: this.output,
-      cacheRead: this.cacheRead,
-      cacheWrite: this.cacheWrite
-    };
-  }
-  estimateCost() {
-    return {
-      input: round4(this.costInput),
-      output: round4(this.costOutput),
-      total: round4(this.costInput + this.costOutput),
-      currency: "USD"
-    };
-  }
-  cacheStats() {
-    const denom = this.cacheRead + this.input;
-    return {
-      readTokens: this.cacheRead,
-      writeTokens: this.cacheWrite,
-      hitRatio: denom === 0 ? 0 : this.cacheRead / denom
-    };
-  }
-  /** Invalidate cached prices so the next account() call fetches fresh data. */
-  invalidateCache() {
-    this.priceCache.clear();
+  /** Invalidate cached prices so the next account() call fetches fresh data. */
+  invalidateCache() {
+    this.priceCache.clear();
   }
   reset() {
     this.input = 0;
@@ -1840,151 +1970,28 @@ function userInputTitle(content) {
   const text = content.filter((b) => b.type === "text").map((b) => b.text).join(" ");
   return (text || "(non-text input)").slice(0, 60);
 }
-var LOCK_FILE = "active.json";
-var DEFAULT_MAX_AGE_MS = 24 * 60 * 60 * 1e3;
-var RecoveryLock = class {
+var QueueStore = class {
   file;
-  pid;
-  hostname;
-  maxAgeMs;
-  sessionStore;
-  probe;
   constructor(opts) {
-    this.file = path2.join(opts.dir, LOCK_FILE);
-    this.pid = opts.pid ?? process.pid;
-    this.hostname = opts.hostname ?? os3.hostname();
-    this.maxAgeMs = opts.maxAgeMs ?? DEFAULT_MAX_AGE_MS;
-    this.sessionStore = opts.sessionStore;
-    this.probe = opts.isPidAlive ?? defaultIsPidAlive;
-  }
-  /**
-   * Examine the lockfile and decide whether it represents an abandoned
-   * session. Returns `null` if the file is missing, points to a live
-   * instance, references a clean-closed session, is too old, or is
-   * malformed. Otherwise returns enough detail to prompt the user.
-   *
-   * Important: this is a read-only check. We never delete an active
-   * lock from here — if another wstack instance is alive, the caller
-   * should bail or run with a fresh session instead.
-   */
-  async checkAbandoned() {
-    const lock = await this.readLock();
-    if (!lock) return null;
-    const ageMs = Date.now() - new Date(lock.startedAt).getTime();
-    if (Number.isNaN(ageMs) || ageMs < 0) {
-      return null;
-    }
-    if (ageMs > this.maxAgeMs) return null;
-    if (lock.hostname === this.hostname && this.probe(lock.pid)) {
-      return null;
-    }
-    let messageCount = 0;
-    if (this.sessionStore) {
-      try {
-        const data = await this.sessionStore.load(lock.sessionId);
-        const closed = data.events.some((e) => e.type === "session_end");
-        if (closed) return null;
-        messageCount = data.messages.length;
-      } catch {
-        return null;
-      }
-    }
-    return {
-      sessionId: lock.sessionId,
-      pid: lock.pid,
-      startedAt: lock.startedAt,
-      ageMs,
-      messageCount
-    };
-  }
-  /**
-   * Claim the lock for the given session. Overwrites any existing lock
-   * — the caller should have already handled abandonment (via
-   * `checkAbandoned`) before calling this.
-   */
-  async write(sessionId) {
-    await ensureDir(path2.dirname(this.file));
-    const lock = {
-      v: 1,
-      sessionId,
-      pid: this.pid,
-      hostname: this.hostname,
-      startedAt: (/* @__PURE__ */ new Date()).toISOString()
-    };
-    const tmp = `${this.file}.tmp`;
-    await fsp.writeFile(tmp, JSON.stringify(lock), { mode: 384 });
-    await fsp.rename(tmp, this.file);
+    this.file = path2.join(opts.dir, "queue.json");
   }
-  /**
-   * Release the lock. Idempotent — silently succeeds if the file is
-   * already gone (e.g. someone else cleared it, or the directory was
-   * wiped).
-   */
-  async clear() {
-    try {
-      await fsp.unlink(this.file);
-    } catch (err) {
-      const code = err.code;
-      if (code === "ENOENT") return;
-      throw err;
+  async write(items) {
+    if (items.length === 0) {
+      await this.clear();
+      return;
     }
+    await atomicWrite(this.file, JSON.stringify(items), { mode: 384 });
   }
-  async readLock() {
+  async read() {
     let raw;
     try {
       raw = await fsp.readFile(this.file, "utf8");
     } catch (err) {
       const code = err.code;
-      if (code === "ENOENT") return null;
-      return null;
+      if (code === "ENOENT") return [];
+      return [];
     }
-    try {
-      const parsed = JSON.parse(raw);
-      if (!isLockFile(parsed)) return null;
-      return parsed;
-    } catch {
-      return null;
-    }
-  }
-};
-function isLockFile(v) {
-  if (typeof v !== "object" || v === null) return false;
-  const o = v;
-  return o["v"] === 1 && typeof o["sessionId"] === "string" && typeof o["pid"] === "number" && typeof o["hostname"] === "string" && typeof o["startedAt"] === "string";
-}
-function defaultIsPidAlive(pid) {
-  if (!Number.isInteger(pid) || pid <= 0) return false;
-  try {
-    process.kill(pid, 0);
-    return true;
-  } catch (err) {
-    const code = err.code;
-    if (code === "EPERM") return true;
-    return false;
-  }
-}
-var QueueStore = class {
-  file;
-  constructor(opts) {
-    this.file = path2.join(opts.dir, "queue.json");
-  }
-  async write(items) {
-    if (items.length === 0) {
-      await this.clear();
-      return;
-    }
-    await atomicWrite(this.file, JSON.stringify(items), { mode: 384 });
-  }
-  async read() {
-    let raw;
-    try {
-      raw = await fsp.readFile(this.file, "utf8");
-    } catch (err) {
-      const code = err.code;
-      if (code === "ENOENT") return [];
-      return [];
-    }
-    let parsed;
+    let parsed;
     try {
       parsed = JSON.parse(raw);
     } catch {
@@ -2125,6 +2132,205 @@ function mergeAdjacentText(blocks) {
   }
   return out;
 }
+var MAX_BYTES_TOTAL = 32e3;
+var DefaultMemoryStore = class {
+  files;
+  constructor(opts) {
+    this.files = {
+      "project-agents": opts.paths.inProjectAgentsFile,
+      "project-memory": opts.paths.projectMemory,
+      "user-memory": opts.paths.globalMemory
+    };
+  }
+  async readAll() {
+    const parts = [];
+    for (const scope of ["project-agents", "project-memory", "user-memory"]) {
+      const body = await this.read(scope);
+      if (body.trim()) parts.push(`## ${labelOf(scope)}
+
+${body.trim()}`);
+    }
+    return parts.join("\n\n");
+  }
+  async read(scope) {
+    try {
+      return await fsp.readFile(this.files[scope], "utf8");
+    } catch {
+      return "";
+    }
+  }
+  async remember(text, scope = "project-memory") {
+    const file = this.files[scope];
+    await ensureDir(path2.dirname(file));
+    let existing = "";
+    try {
+      existing = await fsp.readFile(file, "utf8");
+    } catch {
+    }
+    const ts = (/* @__PURE__ */ new Date()).toISOString();
+    const id = `mem_${Date.now()}_${Math.random().toString(36).slice(2, 9)}`;
+    const entry = `
+- [${ts}] ${id} ${text.replace(/\n/g, " ")}
+`;
+    const next = existing.trim() ? existing.replace(/\n+$/, "") + entry : `# WrongStack Memory
+${entry}`;
+    await atomicWrite(file, next);
+    const buf = Buffer.byteLength(next, "utf8");
+    if (buf > MAX_BYTES_TOTAL) {
+      await this.consolidate(scope);
+    }
+  }
+  async forget(query, scope = "project-memory") {
+    const file = this.files[scope];
+    let existing;
+    try {
+      existing = await fsp.readFile(file, "utf8");
+    } catch {
+      return 0;
+    }
+    const needle = query.toLowerCase();
+    const idMatcher = /mem_\d+_\w+/;
+    let removed = 0;
+    const lines = existing.split("\n").filter((line) => {
+      const trimmed = line.trim();
+      if (!trimmed.startsWith("- ")) return true;
+      if (idMatcher.test(query)) {
+        const afterBracket = trimmed.indexOf("] ");
+        if (afterBracket !== -1) {
+          const afterTs = trimmed.slice(afterBracket + 2);
+          const entryIdMatch = /^mem_\d+_\w+/.exec(afterTs);
+          if (entryIdMatch && entryIdMatch[0] === query) {
+            removed++;
+            return false;
+          }
+        }
+      }
+      if (trimmed.toLowerCase().includes(needle)) {
+        removed++;
+        return false;
+      }
+      return true;
+    });
+    if (removed > 0) {
+      await atomicWrite(file, lines.join("\n"));
+    }
+    return removed;
+  }
+  async consolidate(scope) {
+    const file = this.files[scope];
+    let existing;
+    try {
+      existing = await fsp.readFile(file, "utf8");
+    } catch {
+      return;
+    }
+    const seen = /* @__PURE__ */ new Set();
+    const lines = existing.split("\n").filter((line) => {
+      const trimmed = line.trim();
+      if (!trimmed.startsWith("- ")) return true;
+      const norm = trimmed.replace(/\[[^\]]+\]/, "").replace(/\bmem_\d+_\w+\s*/, "").trim().toLowerCase();
+      if (seen.has(norm)) return false;
+      seen.add(norm);
+      return true;
+    });
+    const next = lines.join("\n");
+    try {
+      await atomicWrite(file, next);
+    } catch {
+      return;
+    }
+    const backup = `${file}.bak.${Date.now()}`;
+    try {
+      await fsp.copyFile(file, backup);
+    } catch {
+    }
+  }
+  async clear(scope) {
+    if (scope) {
+      await atomicWrite(this.files[scope], "");
+    } else {
+      for (const s of ["project-agents", "project-memory", "user-memory"]) {
+        await atomicWrite(this.files[s], "");
+      }
+    }
+  }
+};
+function labelOf(scope) {
+  switch (scope) {
+    case "project-agents":
+      return "Project AGENTS.md";
+    case "project-memory":
+      return "Project memory";
+    case "user-memory":
+      return "User memory";
+  }
+}
+
+// src/defaults/secret-scrubber.ts
+var PATTERNS = [
+  // Anchored at the start where possible so partial matches inside larger
+  // strings don't trigger false positives.
+  { type: "anthropic_key", regex: /(?<![A-Za-z0-9])sk-ant-api\d+-[A-Za-z0-9_-]{20,}(?![A-Za-z0-9])/g },
+  { type: "openai_key", regex: /(?<![A-Za-z0-9])sk-(?:proj-)?[A-Za-z0-9_-]{20,}(?![A-Za-z0-9])/g },
+  { type: "github_pat", regex: /(?<![A-Za-z0-9])ghp_[A-Za-z0-9]{36,}(?![A-Za-z0-9])/g },
+  { type: "github_pat_v2", regex: /(?<![A-Za-z0-9])github_pat_[A-Za-z0-9_]{50,}(?![A-Za-z0-9])/g },
+  { type: "aws_access_key", regex: /(?<![A-Za-z0-9])AKIA[0-9A-Z]{16}(?![A-Za-z0-9])/g },
+  { type: "gcp_key", regex: /(?<![A-Za-z0-9])AIza[0-9A-Za-z_-]{35}(?![A-Za-z0-9])/g },
+  { type: "slack_token", regex: /(?<![A-Za-z0-9-])xox[abpos]-[A-Za-z0-9-]{10,}(?![A-Za-z0-9-])/g },
+  { type: "stripe_key", regex: /(?<![A-Za-z0-9])sk_(?:live|test)_[A-Za-z0-9]{24,}(?![A-Za-z0-9])/g },
+  { type: "twilio_sid", regex: /(?<![A-Za-z0-9])AC[a-f0-9]{32}(?![A-Za-z0-9])/g },
+  {
+    type: "jwt",
+    // Anchored: look for literal "eyJ" which is unambiguous for JWT header
+    regex: /(?<![A-Za-z0-9/+=])eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}(?![A-Za-z0-9/+=])/g
+  },
+  {
+    type: "private_key",
+    // Anchored: start must be BEGIN, end must be END with no extra dashes after END
+    regex: /(?:^|\n)-----BEGIN (?:RSA|EC|OPENSSH|DSA|PGP)? ?PRIVATE KEY-----[\s\S]*?-----END[^-]*-----(?:\n|$)/g
+  },
+  { type: "mongodb_uri", regex: /mongodb(?:\+srv)?:\/\/[^\s"'`]+/g },
+  { type: "postgres_uri", regex: /postgres(?:ql)?:\/\/[^\s"'`]+/g },
+  { type: "mysql_uri", regex: /mysql:\/\/[^\s"'`]+/g },
+  { type: "redis_uri", regex: /redis:\/\/[^\s"'`]+/g },
+  { type: "bearer_token", regex: /(?<![A-Za-z0-9_.~+/-])Bearer\s+[A-Za-z0-9._~+/-]{20,}=*(?![A-Za-z0-9_.~+/-])/g },
+  {
+    type: "high_entropy_env",
+    // Value-side word boundary + length gate to avoid matching short random strings
+    regex: /\b([A-Z_]{4,}(?:KEY|TOKEN|SECRET|PASSWORD|PWD))\s*[:=]\s*['"]?([A-Za-z0-9_/+=-]{20,})['"]?(?!\s*[A-Za-z_]{4,}(?:KEY|TOKEN|SECRET|PASSWORD|PWD))/g
+  }
+];
+var DefaultSecretScrubber = class {
+  scrub(text) {
+    if (!text) return text;
+    let out = text;
+    for (const p of PATTERNS) {
+      out = out.replace(p.regex, (_match, group1, group2) => {
+        if (p.type === "high_entropy_env" && group1 && group2) {
+          return `${group1}=[REDACTED:${p.type}]`;
+        }
+        return `[REDACTED:${p.type}]`;
+      });
+    }
+    return out;
+  }
+  scrubObject(obj) {
+    const seen = /* @__PURE__ */ new WeakSet();
+    const visit = (v) => {
+      if (typeof v === "string") return this.scrub(v);
+      if (v === null || typeof v !== "object") return v;
+      if (seen.has(v)) return v;
+      seen.add(v);
+      if (Array.isArray(v)) return v.map(visit);
+      const out = {};
+      for (const [k, val] of Object.entries(v)) {
+        out[k] = visit(val);
+      }
+      return out;
+    };
+    return visit(obj);
+  }
+};
 var KEY_BYTES = 32;
 var IV_BYTES = 12;
 var TAG_BYTES = 16;
@@ -2169,7 +2375,7 @@ var DefaultSecretVault = class {
   loadOrCreateKey() {
     if (this.key) return this.key;
     try {
-      const buf = fs4.readFileSync(this.keyFile);
+      const buf = fs5.readFileSync(this.keyFile);
       if (buf.length !== KEY_BYTES) {
         throw new Error(`SecretVault: key file ${this.keyFile} has wrong size`);
       }
@@ -2178,13 +2384,13 @@ var DefaultSecretVault = class {
     } catch (err) {
       if (err.code !== "ENOENT") throw err;
     }
-    fs4.mkdirSync(path2.dirname(this.keyFile), { recursive: true });
+    fs5.mkdirSync(path2.dirname(this.keyFile), { recursive: true });
     const key = randomBytes(KEY_BYTES);
     try {
-      fs4.writeFileSync(this.keyFile, key, { mode: 384, flag: "wx" });
+      fs5.writeFileSync(this.keyFile, key, { mode: 384, flag: "wx" });
     } catch (err) {
       if (err.code !== "EEXIST") throw err;
-      const buf = fs4.readFileSync(this.keyFile);
+      const buf = fs5.readFileSync(this.keyFile);
       if (buf.length !== KEY_BYTES) {
         throw new Error(`SecretVault: key file ${this.keyFile} has wrong size`);
       }
@@ -2196,23 +2402,23 @@ var DefaultSecretVault = class {
   }
 };
 function decryptConfigSecrets(cfg, vault) {
-  return walk(cfg, vault, (v) => vault.decrypt(v));
+  return walk2(cfg, vault, (v) => vault.decrypt(v));
 }
 function encryptConfigSecrets(cfg, vault) {
-  return walk(cfg, vault, (v) => vault.encrypt(v));
+  return walk2(cfg, vault, (v) => vault.encrypt(v));
 }
-function walk(node, vault, transform) {
+function walk2(node, vault, transform) {
   if (node === null || node === void 0) return node;
   if (typeof node !== "object") return node;
   if (Array.isArray(node)) {
-    return node.map((item) => walk(item, vault, transform));
+    return node.map((item) => walk2(item, vault, transform));
   }
   const out = {};
   for (const [k, v] of Object.entries(node)) {
     if (typeof v === "string" && isSecretField(k)) {
       out[k] = transform(v);
     } else if (typeof v === "object" && v !== null) {
-      out[k] = walk(v, vault, transform);
+      out[k] = walk2(v, vault, transform);
     } else {
       out[k] = v;
     }
@@ -2296,145 +2502,12 @@ function deepMerge(a, b) {
   }
   return out;
 }
-var MAX_BYTES_TOTAL = 32e3;
-var DefaultMemoryStore = class {
-  files;
-  constructor(opts) {
-    this.files = {
-      "project-agents": opts.paths.inProjectAgentsFile,
-      "project-memory": opts.paths.projectMemory,
-      "user-memory": opts.paths.globalMemory
-    };
-  }
-  async readAll() {
-    const parts = [];
-    for (const scope of ["project-agents", "project-memory", "user-memory"]) {
-      const body = await this.read(scope);
-      if (body.trim()) parts.push(`## ${labelOf(scope)}
-
-${body.trim()}`);
-    }
-    return parts.join("\n\n");
-  }
-  async read(scope) {
-    try {
-      return await fsp.readFile(this.files[scope], "utf8");
-    } catch {
-      return "";
-    }
-  }
-  async remember(text, scope = "project-memory") {
-    const file = this.files[scope];
-    await ensureDir(path2.dirname(file));
-    let existing = "";
-    try {
-      existing = await fsp.readFile(file, "utf8");
-    } catch {
-    }
-    const ts = (/* @__PURE__ */ new Date()).toISOString();
-    const id = `mem_${Date.now()}_${Math.random().toString(36).slice(2, 9)}`;
-    const entry = `
-- [${ts}] ${id} ${text.replace(/\n/g, " ")}
-`;
-    const next = existing.trim() ? existing.replace(/\n+$/, "") + entry : `# WrongStack Memory
-${entry}`;
-    await atomicWrite(file, next);
-    const buf = Buffer.byteLength(next, "utf8");
-    if (buf > MAX_BYTES_TOTAL) {
-      await this.consolidate(scope);
-    }
-  }
-  async forget(query, scope = "project-memory") {
-    const file = this.files[scope];
-    let existing;
-    try {
-      existing = await fsp.readFile(file, "utf8");
-    } catch {
-      return 0;
-    }
-    const needle = query.toLowerCase();
-    const idMatcher = /mem_\d+_\w+/;
-    let removed = 0;
-    const lines = existing.split("\n").filter((line) => {
-      const trimmed = line.trim();
-      if (!trimmed.startsWith("- ")) return true;
-      if (idMatcher.test(query)) {
-        const afterBracket = trimmed.indexOf("] ");
-        if (afterBracket !== -1) {
-          const afterTs = trimmed.slice(afterBracket + 2);
-          const entryIdMatch = /^mem_\d+_\w+/.exec(afterTs);
-          if (entryIdMatch && entryIdMatch[0] === query) {
-            removed++;
-            return false;
-          }
-        }
-      }
-      if (trimmed.toLowerCase().includes(needle)) {
-        removed++;
-        return false;
-      }
-      return true;
-    });
-    if (removed > 0) {
-      await atomicWrite(file, lines.join("\n"));
-    }
-    return removed;
-  }
-  async consolidate(scope) {
-    const file = this.files[scope];
-    let existing;
-    try {
-      existing = await fsp.readFile(file, "utf8");
-    } catch {
-      return;
-    }
-    const seen = /* @__PURE__ */ new Set();
-    const lines = existing.split("\n").filter((line) => {
-      const trimmed = line.trim();
-      if (!trimmed.startsWith("- ")) return true;
-      const norm = trimmed.replace(/\[[^\]]+\]/, "").replace(/\bmem_\d+_\w+\s*/, "").trim().toLowerCase();
-      if (seen.has(norm)) return false;
-      seen.add(norm);
-      return true;
-    });
-    const next = lines.join("\n");
-    try {
-      await atomicWrite(file, next);
-    } catch {
-      return;
-    }
-    const backup = `${file}.bak.${Date.now()}`;
-    try {
-      await fsp.copyFile(file, backup);
-    } catch {
-    }
-  }
-  async clear(scope) {
-    if (scope) {
-      await atomicWrite(this.files[scope], "");
-    } else {
-      for (const s of ["project-agents", "project-memory", "user-memory"]) {
-        await atomicWrite(this.files[s], "");
-      }
-    }
-  }
-};
-function labelOf(scope) {
-  switch (scope) {
-    case "project-agents":
-      return "Project AGENTS.md";
-    case "project-memory":
-      return "Project memory";
-    case "user-memory":
-      return "User memory";
-  }
-}
-var DefaultPermissionPolicy = class {
-  policy = {};
-  loaded = false;
-  trustFile;
-  yolo;
-  promptDelegate;
+var DefaultPermissionPolicy = class {
+  policy = {};
+  loaded = false;
+  trustFile;
+  yolo;
+  promptDelegate;
   constructor(opts) {
     this.trustFile = opts.trustFile;
     this.yolo = opts.yolo ?? false;
@@ -2530,6 +2603,126 @@ var DefaultPermissionPolicy = class {
     return void 0;
   }
 };
+
+// src/defaults/retry-policy.ts
+var DefaultRetryPolicy = class {
+  shouldRetry(err, attempt) {
+    if (err instanceof ProviderError) {
+      if (!err.retryable) return false;
+      return attempt < this.maxAttempts(err);
+    }
+    const msg = err.message ?? "";
+    const isNetwork = /ECONN|ETIMEDOUT|ETIME|ENOTFOUND|EAI_AGAIN|fetch failed/i.test(msg);
+    if (isNetwork) return attempt < 2;
+    return false;
+  }
+  maxAttempts(err) {
+    if (err instanceof ProviderError) {
+      if (err.status === 429) return 5;
+      if (err.status === 529) return 3;
+      if (err.status >= 500) return 3;
+      return 0;
+    }
+    return 2;
+  }
+  delayMs(attempt) {
+    const base = 1e3;
+    const exp = base * 2 ** attempt;
+    const jitter = Math.random() * base;
+    return Math.min(3e4, exp + jitter);
+  }
+};
+
+// src/defaults/error-handler.ts
+function buildRecoveryStrategies(opts) {
+  return [
+    {
+      label: "context_overflow_reduce",
+      compactor: opts?.compactor,
+      async attempt(err, ctx) {
+        if (err instanceof ProviderError && (err.status === 413 || /context|too long|tokens/i.test(err.message))) {
+          if (this.compactor) {
+            try {
+              const report = await this.compactor.compact(ctx, { aggressive: true });
+              if (report.after < report.before) {
+                return {
+                  content: [{ type: "text", text: "[context compacted automatically \u2014 please retry]" }],
+                  stopReason: "end_turn",
+                  usage: { input: 0, output: 0 },
+                  model: ctx.model
+                };
+              }
+            } catch {
+            }
+          }
+          return null;
+        }
+        return null;
+      }
+    },
+    {
+      label: "rate_limit_backoff",
+      async attempt(err, ctx) {
+        if (err instanceof ProviderError && err.status === 429) {
+          const delayMs = err.body?.retryAfterMs ?? 5e3;
+          const delay = Math.max(1e3, Math.min(delayMs, 6e4));
+          await new Promise((r) => setTimeout(r, delay));
+          return {
+            content: [{ type: "text", text: "[rate limit backoff applied \u2014 please retry]" }],
+            stopReason: "end_turn",
+            usage: { input: 0, output: 0 },
+            model: ctx.model
+          };
+        }
+        return null;
+      }
+    },
+    {
+      label: "downgrade_model",
+      async attempt(err, ctx) {
+        if (err instanceof ProviderError && (err.status === 429 || err.status === 529 || err.status >= 500)) {
+          return null;
+        }
+        return null;
+      }
+    }
+  ];
+}
+var DEFAULT_RECOVERY_STRATEGIES = buildRecoveryStrategies();
+var DefaultErrorHandler = class {
+  strategies;
+  constructor(strategies = DEFAULT_RECOVERY_STRATEGIES) {
+    this.strategies = strategies;
+  }
+  classify(err) {
+    if (err instanceof DOMException && err.name === "AbortError") {
+      return { kind: "abort", retryable: false };
+    }
+    if (err instanceof Error && err.name === "AbortError") {
+      return { kind: "abort", retryable: false };
+    }
+    if (err instanceof ProviderError) {
+      if (err.status === 429) return { kind: "rate_limit", retryable: true };
+      if (err.status === 529) return { kind: "overloaded", retryable: true };
+      if (err.status >= 500) return { kind: "server", retryable: true };
+      if (err.status === 413 || /context|too long|tokens/i.test(err.message)) {
+        return { kind: "context_overflow", retryable: false };
+      }
+      if (err.status >= 400) return { kind: "client", retryable: false };
+    }
+    if (err instanceof Error && /ECONN|ETIMEDOUT|ETIME|ENOTFOUND|EAI_AGAIN|fetch failed/i.test(err.message)) {
+      return { kind: "network", retryable: true };
+    }
+    return { kind: "unknown", retryable: false };
+  }
+  async recover(err, ctx) {
+    for (const strategy of this.strategies) {
+      const result = await strategy.attempt(err, ctx);
+      if (result !== null) return result;
+    }
+    return null;
+  }
+};
 var DefaultSkillLoader = class {
   dirs;
   cache;
@@ -2747,8 +2940,22 @@ var DefaultConfigLoader = class {
     if (this.vault) {
       cfg = decryptConfigSecrets(cfg, this.vault);
     }
-    this.validateBehavior(cfg);
-    if (this.strict) this.validateIdentity(cfg);
+    if (cfg.providers) {
+      for (const pcfg of Object.values(cfg.providers)) {
+        if (!pcfg || typeof pcfg !== "object") continue;
+        const keys = pcfg.apiKeys;
+        if (!Array.isArray(keys) || keys.length === 0) continue;
+        const existing = pcfg.apiKey;
+        if (existing && existing.length > 0) continue;
+        const activeLabel = pcfg.activeKey;
+        const chosen = activeLabel ? keys.find((k) => k.label === activeLabel) ?? keys[0] : keys[0];
+        if (chosen?.apiKey) {
+          pcfg.apiKey = chosen.apiKey;
+        }
+      }
+    }
+    this.validateBehavior(cfg);
+    if (this.strict) this.validateIdentity(cfg);
     return Object.freeze(cfg);
   }
   async readJson(file) {
@@ -2783,6 +2990,110 @@ var DefaultConfigLoader = class {
   }
 };
 
+// src/defaults/config-store.ts
+var DefaultConfigStore = class {
+  current;
+  watchers = /* @__PURE__ */ new Set();
+  constructor(initial) {
+    this.current = deepFreeze(structuredClone(initial));
+  }
+  get() {
+    return this.current;
+  }
+  getSection(key) {
+    return this.current[key];
+  }
+  getExtension(pluginName) {
+    const ext = this.current.extensions?.[pluginName];
+    return ext ? ext : FROZEN_EMPTY;
+  }
+  update(partial) {
+    const next = deepFreeze(
+      structuredClone({ ...this.current, ...partial })
+    );
+    if (next.version !== 1) {
+      throw new Error(`ConfigStore.update: version must remain 1, got ${String(next.version)}`);
+    }
+    const prev = this.current;
+    this.current = next;
+    for (const w of this.watchers) {
+      try {
+        w(next, prev);
+      } catch {
+      }
+    }
+    return next;
+  }
+  watch(cb) {
+    this.watchers.add(cb);
+    return () => this.watchers.delete(cb);
+  }
+};
+var FROZEN_EMPTY = Object.freeze({});
+function deepFreeze(obj) {
+  if (obj === null || typeof obj !== "object") return obj;
+  if (Object.isFrozen(obj)) return obj;
+  for (const key of Object.keys(obj)) {
+    const v = obj[key];
+    if (v !== null && typeof v === "object" && !Object.isFrozen(v)) {
+      deepFreeze(v);
+    }
+  }
+  return Object.freeze(obj);
+}
+
+// src/defaults/config-migration.ts
+var ConfigMigrationError = class extends Error {
+  fromVersion;
+  targetVersion;
+  missingStep;
+  constructor(opts) {
+    super(opts.message);
+    this.name = "ConfigMigrationError";
+    this.fromVersion = opts.fromVersion;
+    this.targetVersion = opts.targetVersion;
+    this.missingStep = opts.missingStep;
+  }
+};
+function runConfigMigrations(input, targetVersion, migrations) {
+  const initial = typeof input["version"] === "number" ? input["version"] : 1;
+  let current = { ...input };
+  let currentVersion = initial;
+  const applied = [];
+  let shouldPersist = false;
+  let guard = 0;
+  while (currentVersion !== targetVersion) {
+    if (++guard > 100) {
+      throw new ConfigMigrationError({
+        message: `Config migration looped past 100 steps (from v${initial} toward v${targetVersion})`,
+        fromVersion: initial,
+        targetVersion,
+        missingStep: currentVersion
+      });
+    }
+    const step = migrations.find((m) => m.from === currentVersion);
+    if (!step) {
+      throw new ConfigMigrationError({
+        message: `No migration registered from config v${currentVersion} (target v${targetVersion}). Update the framework or revert the config file.`,
+        fromVersion: initial,
+        targetVersion,
+        missingStep: currentVersion
+      });
+    }
+    const ctx = { fromVersion: currentVersion, shouldPersist: false };
+    const next = step.migrate(current, ctx);
+    if (typeof next["version"] !== "number" || next["version"] !== step.to) {
+      next["version"] = step.to;
+    }
+    current = next;
+    currentVersion = step.to;
+    applied.push(`v${step.from}\u2192v${step.to}`);
+    shouldPersist = shouldPersist || ctx.shouldPersist || step.from < step.to;
+  }
+  return { config: current, applied, shouldPersist };
+}
+var DEFAULT_CONFIG_MIGRATIONS = [];
+
 // src/defaults/compactor.ts
 var HybridCompactor = class {
   preserveK;
@@ -2791,7 +3102,7 @@ var HybridCompactor = class {
   constructor(opts = {}) {
     this.preserveK = opts.preserveK ?? 10;
     this.eliseThreshold = opts.eliseThreshold ?? 2e3;
-    this.estimator = opts.estimator ?? roughTokenEstimate;
+    this.estimator = opts.estimator ?? estimateTextTokens;
   }
   async compact(ctx, opts = {}) {
     const beforeTokens = this.estimateMessages(ctx.messages);
@@ -2823,8 +3134,7 @@ var HybridCompactor = class {
       if (!msg || !Array.isArray(msg.content)) continue;
       const newContent = msg.content.map((b) => {
         if (b.type !== "tool_result") return b;
-        const text = typeof b.content === "string" ? b.content : JSON.stringify(b.content);
-        const tokens = this.estimator(text);
+        const tokens = estimateToolResultTokens(b.content);
         if (tokens < this.eliseThreshold) return b;
         saved += tokens;
         const elided = {
@@ -2862,23 +3172,20 @@ var HybridCompactor = class {
       },
       { role: "assistant", content: "Continuing from compacted context." }
     ];
-    ctx.messages.splice(0, boundary, ...summary);
+    const tail = ctx.messages.slice(boundary);
+    ctx.state.replaceMessages([...summary, ...tail]);
     return Math.max(0, removedTokens - this.estimateMessages(summary));
   }
   estimateMessages(messages) {
     let total = 0;
     for (const m of messages) {
       if (typeof m.content === "string") {
-        total += this.estimator(m.content);
+        total += estimateTextTokens(m.content);
       } else {
         for (const b of m.content) {
-          if (b.type === "text") total += this.estimator(b.text);
-          else if (b.type === "tool_use") total += this.estimator(JSON.stringify(b.input));
-          else if (b.type === "tool_result") {
-            total += this.estimator(
-              typeof b.content === "string" ? b.content : JSON.stringify(b.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);
         }
       }
     }
@@ -2889,9 +3196,6 @@ function hasTextContent(m) {
   if (typeof m.content === "string") return m.content.trim().length > 0;
   return m.content.some((b) => b.type === "text" && b.text.trim().length > 0);
 }
-function roughTokenEstimate(text) {
-  return Math.max(1, Math.ceil(text.length / 4));
-}
 
 // src/defaults/intelligent-compactor.ts
 var IntelligentCompactor = class {
@@ -2951,7 +3255,8 @@ var IntelligentCompactor = class {
       content: `[prior_turns_summary: ${summaryText}]`
     };
     const summaryTokens = this.estimateTokens([summaryMsg]);
-    ctx.messages.splice(0, boundary, summaryMsg);
+    const tail = ctx.messages.slice(boundary);
+    ctx.state.replaceMessages([summaryMsg, ...tail]);
     return Math.max(0, removedTokens - summaryTokens);
   }
   findSafeBoundary(messages, from, to) {
@@ -3032,8 +3337,7 @@ var IntelligentCompactor = class {
       if (!msg || !Array.isArray(msg.content)) continue;
       const newContent = msg.content.map((b) => {
         if (b.type !== "tool_result") return b;
-        const text = typeof b.content === "string" ? b.content : JSON.stringify(b.content);
-        const tokens = this.roughTokenEstimate(text);
+        const tokens = estimateToolResultTokens(b.content);
         if (tokens < this.eliseThreshold) return b;
         saved += tokens;
         return {
@@ -3055,24 +3359,17 @@ var IntelligentCompactor = class {
     let total = 0;
     for (const m of messages) {
       if (typeof m.content === "string") {
-        total += this.roughTokenEstimate(m.content);
+        total += estimateTextTokens(m.content);
       } else {
         for (const b of m.content) {
-          if (b.type === "text") total += this.roughTokenEstimate(b.text);
-          else if (b.type === "tool_use") total += this.roughTokenEstimate(JSON.stringify(b.input));
-          else if (b.type === "tool_result") {
-            total += this.roughTokenEstimate(
-              typeof b.content === "string" ? b.content : JSON.stringify(b.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);
         }
       }
     }
     return total;
   }
-  roughTokenEstimate(text) {
-    return Math.max(1, Math.ceil(text.length / 4));
-  }
 };
 
 // src/defaults/llm-selector.ts
@@ -3295,8 +3592,8 @@ var SelectiveCompactor = class {
    * insert summaries where the selector provided them.
    */
   async executePlan(ctx, plan) {
-    const messages = ctx.messages;
-    if (messages.length === 0) return;
+    if (ctx.messages.length === 0) return;
+    const messages = [...ctx.messages];
     const sortedCollapsed = [...plan.collapsed].sort((a, b) => b.from - a.from);
     for (const range of sortedCollapsed) {
       if (range.from < 0 || range.to >= messages.length || range.from > range.to) continue;
@@ -3311,6 +3608,7 @@ var SelectiveCompactor = class {
       };
       messages.splice(range.from, range.to - range.from + 1, summaryMsg);
     }
+    ctx.state.replaceMessages(messages);
   }
   async summarizeRange(messages, ctx) {
     const systemText = `${this.summarizerPrompt}
@@ -3357,7 +3655,8 @@ Summarize the following message range:`;
       role: "system",
       content: `[${removed.length} earlier turns trimmed \u2014 see session log for details]`
     };
-    messages.splice(0, boundary, summaryMsg);
+    const tail = messages.slice(boundary);
+    ctx.state.replaceMessages([summaryMsg, ...tail]);
     return Math.max(0, removedTokens - this.estimateTokens([summaryMsg]));
   }
   computeTargetBudget(load, aggressive) {
@@ -3747,44 +4046,128 @@ async function loadUserModes(modesDir) {
   }
   return modes;
 }
+
+// src/defaults/subagent-budget.ts
+var BudgetExceededError = class extends Error {
+  kind;
+  limit;
+  observed;
+  constructor(kind, limit, observed) {
+    super(`Budget exceeded: ${kind} (limit=${limit}, observed=${observed})`);
+    this.name = "BudgetExceededError";
+    this.kind = kind;
+    this.limit = limit;
+    this.observed = observed;
+  }
+};
+var SubagentBudget = class {
+  limits;
+  iterations = 0;
+  toolCalls = 0;
+  tokenInput = 0;
+  tokenOutput = 0;
+  costUsd = 0;
+  startTime = null;
+  constructor(limits = {}) {
+    this.limits = Object.freeze({ ...limits });
+  }
+  start() {
+    this.startTime = Date.now();
+  }
+  recordIteration() {
+    this.iterations++;
+    if (this.limits.maxIterations !== void 0 && this.iterations > this.limits.maxIterations) {
+      throw new BudgetExceededError("iterations", this.limits.maxIterations, this.iterations);
+    }
+  }
+  recordToolCall() {
+    this.toolCalls++;
+    if (this.limits.maxToolCalls !== void 0 && this.toolCalls > this.limits.maxToolCalls) {
+      throw new BudgetExceededError("tool_calls", this.limits.maxToolCalls, this.toolCalls);
+    }
+  }
+  recordUsage(usage, costUsd = 0) {
+    this.tokenInput += usage.input;
+    this.tokenOutput += usage.output;
+    this.costUsd += costUsd;
+    const totalTokens = this.tokenInput + this.tokenOutput;
+    if (this.limits.maxTokens !== void 0 && totalTokens > this.limits.maxTokens) {
+      throw new BudgetExceededError("tokens", this.limits.maxTokens, totalTokens);
+    }
+    if (this.limits.maxCostUsd !== void 0 && this.costUsd > this.limits.maxCostUsd) {
+      throw new BudgetExceededError("cost", this.limits.maxCostUsd, this.costUsd);
+    }
+  }
+  /**
+   * Throws if the wall-clock budget is exhausted. Call this from the iteration
+   * loop so a hung tool can't keep a subagent running past its deadline.
+   */
+  checkTimeout() {
+    if (this.startTime === null || this.limits.timeoutMs === void 0) return;
+    const elapsed = Date.now() - this.startTime;
+    if (elapsed > this.limits.timeoutMs) {
+      throw new BudgetExceededError("timeout", this.limits.timeoutMs, elapsed);
+    }
+  }
+  /** Returns true if a timeout has occurred without throwing. Useful for races. */
+  isTimedOut() {
+    if (this.startTime === null || this.limits.timeoutMs === void 0) return false;
+    return Date.now() - this.startTime > this.limits.timeoutMs;
+  }
+  usage() {
+    return {
+      iterations: this.iterations,
+      toolCalls: this.toolCalls,
+      tokens: {
+        input: this.tokenInput,
+        output: this.tokenOutput,
+        total: this.tokenInput + this.tokenOutput
+      },
+      costUsd: this.costUsd,
+      elapsedMs: this.startTime === null ? 0 : Date.now() - this.startTime
+    };
+  }
+};
+
+// src/defaults/multi-agent-coordinator.ts
 var DefaultMultiAgentCoordinator = class extends EventEmitter {
   coordinatorId;
   config;
+  runner;
   subagents = /* @__PURE__ */ new Map();
   pendingTasks = [];
   completedResults = [];
   totalIterations = 0;
-  constructor(config) {
+  inFlight = 0;
+  constructor(config, options = {}) {
     super();
     this.coordinatorId = config.coordinatorId;
     this.config = config;
+    this.runner = options.runner;
   }
   async spawn(subagent) {
     const id = subagent.id || randomUUID();
     const context = {
       subagentId: id,
       tasks: [],
+      // parentBridge: wired by the caller via setSubagentBridge() once the
+      // bidirectional bridge is created. Reads gated by hasParentBridge().
       parentBridge: null,
       doneCondition: this.config.doneCondition,
       maxConcurrent: this.config.maxConcurrent ?? 4
     };
     this.subagents.set(id, {
-      config: subagent,
+      config: { ...subagent, id },
       context,
-      status: "idle"
+      status: "idle",
+      abortController: new AbortController()
     });
     this.emit("subagent.started", { subagent: { ...subagent, id } });
-    return {
-      subagentId: id,
-      agentId: id
-    };
+    return { subagentId: id, agentId: id };
   }
   async assign(task) {
     this.pendingTasks.push(task);
-    const available = this.getAvailableSubagent();
-    if (available) {
-      await this.dispatch(available, task);
-    }
+    this.tryDispatchNext();
   }
   async delegate(to, msg) {
     const subagent = this.subagents.get(to);
@@ -3795,8 +4178,8 @@ var DefaultMultiAgentCoordinator = class extends EventEmitter {
     await subagent.context.parentBridge.send(msg);
   }
   /**
-   * Wire up the communication bridge for a subagent. Call this after `spawn()`
-   * once the caller has created the bidirectional bridge connection.
+   * Wire up the communication bridge for a subagent. Call after spawn() once
+   * the caller has created the bidirectional connection.
    */
   setSubagentBridge(subagentId, bridge) {
     const subagent = this.subagents.get(subagentId);
@@ -3806,6 +4189,7 @@ var DefaultMultiAgentCoordinator = class extends EventEmitter {
   async stop(subagentId) {
     const subagent = this.subagents.get(subagentId);
     if (!subagent) return;
+    subagent.abortController.abort();
     subagent.status = "stopped";
     subagent.currentTask = void 0;
     subagent.context.parentBridge = null;
@@ -3831,71 +4215,234 @@ var DefaultMultiAgentCoordinator = class extends EventEmitter {
       done: this.isDone()
     };
   }
-  getAvailableSubagent() {
+  /** Expose snapshot of completed results — useful for callers awaiting all done. */
+  results() {
+    return this.completedResults;
+  }
+  /**
+   * Manual completion — for callers that drive subagents without a runner
+   * (e.g. external orchestrators). When a runner is configured the coordinator
+   * calls this itself.
+   */
+  completeTask(result) {
+    this.recordCompletion(result);
+  }
+  // --- internal dispatching ---------------------------------------------
+  tryDispatchNext() {
+    while (this.canDispatch()) {
+      const subagentId = this.findIdleSubagent();
+      if (!subagentId) return;
+      const task = this.pendingTasks.shift();
+      if (!task) return;
+      void this.runDispatched(subagentId, task);
+    }
+  }
+  canDispatch() {
+    const max = this.config.maxConcurrent ?? 4;
+    return this.inFlight < max && this.pendingTasks.length > 0;
+  }
+  findIdleSubagent() {
     for (const [id, s] of this.subagents) {
       if (s.status === "idle") return id;
     }
     return null;
   }
-  async dispatch(subagentId, task) {
+  async runDispatched(subagentId, task) {
     const subagent = this.subagents.get(subagentId);
     if (!subagent) return;
     subagent.status = "running";
     subagent.currentTask = task.id;
     task.subagentId = subagentId;
     subagent.context.tasks.push(task);
-    if (!subagent.context.parentBridge) {
-      this.emit("task.assigned", { task, subagentId });
+    this.inFlight++;
+    this.emit("task.assigned", { task, subagentId });
+    const budget = new SubagentBudget({
+      maxIterations: subagent.config.maxIterations ?? this.config.defaultBudget?.maxIterations,
+      maxToolCalls: task.maxToolCalls ?? subagent.config.maxToolCalls ?? this.config.defaultBudget?.maxToolCalls,
+      maxTokens: subagent.config.maxTokens ?? this.config.defaultBudget?.maxTokens,
+      maxCostUsd: subagent.config.maxCostUsd ?? this.config.defaultBudget?.maxCostUsd,
+      timeoutMs: task.timeoutMs ?? subagent.config.timeoutMs ?? this.config.defaultBudget?.timeoutMs
+    });
+    subagent.activeBudget = budget;
+    const startTime = Date.now();
+    const runCtx = {
+      subagentId,
+      config: subagent.config,
+      budget,
+      signal: subagent.abortController.signal,
+      bridge: subagent.context.parentBridge || null
+    };
+    let result;
+    if (!this.runner) {
       return;
     }
-    await subagent.context.parentBridge.send({
-      id: randomUUID(),
-      type: "task",
-      from: this.coordinatorId,
-      to: subagentId,
-      payload: task,
-      timestamp: Date.now()
-    });
-    this.emit("task.assigned", { task, subagentId });
-  }
-  isDone() {
-    if (this.config.doneCondition.type === "all_tasks_done") {
-      return this.pendingTasks.length === 0 && this.completedResults.every((r) => r.status === "success");
+    budget.start();
+    try {
+      const outcome = await this.executeWithTimeout(this.runner, task, runCtx, budget);
+      result = {
+        subagentId,
+        taskId: task.id,
+        status: "success",
+        result: outcome.result,
+        iterations: outcome.iterations,
+        toolCalls: outcome.toolCalls,
+        durationMs: Date.now() - startTime
+      };
+    } catch (err) {
+      const status = err instanceof BudgetExceededError && err.kind === "timeout" ? "timeout" : subagent.abortController.signal.aborted ? "stopped" : "failed";
+      result = {
+        subagentId,
+        taskId: task.id,
+        status,
+        error: err instanceof Error ? err.message : String(err),
+        iterations: budget.usage().iterations,
+        toolCalls: budget.usage().toolCalls,
+        durationMs: Date.now() - startTime
+      };
     }
-    if (this.config.doneCondition.maxIterations && this.totalIterations >= this.config.doneCondition.maxIterations) {
-      return true;
+    this.recordCompletion(result);
+  }
+  async executeWithTimeout(runner, task, ctx, budget) {
+    const timeoutMs = budget.limits.timeoutMs;
+    if (timeoutMs === void 0) return runner(task, ctx);
+    let timer = null;
+    const timeoutPromise = new Promise((_, reject) => {
+      timer = setTimeout(() => {
+        this.subagents.get(ctx.subagentId)?.abortController.abort();
+        reject(new BudgetExceededError("timeout", timeoutMs, Date.now()));
+      }, timeoutMs);
+    });
+    try {
+      return await Promise.race([runner(task, ctx), timeoutPromise]);
+    } finally {
+      if (timer) clearTimeout(timer);
     }
-    return false;
   }
-  completeTask(result) {
+  recordCompletion(result) {
     this.completedResults.push(result);
     this.totalIterations += result.iterations;
+    this.inFlight = Math.max(0, this.inFlight - 1);
     const subagent = this.subagents.get(result.subagentId);
-    if (subagent) {
-      subagent.status = "idle";
+    if (subagent && subagent.status !== "stopped") {
+      subagent.status = result.status === "failed" || result.status === "timeout" ? "error" : "idle";
       subagent.currentTask = void 0;
+      if (subagent.status === "error") {
+        queueMicrotask(() => {
+          if (subagent.status === "error") subagent.status = "idle";
+          this.tryDispatchNext();
+        });
+      }
     }
     this.emit("task.completed", {
-      task: this.pendingTasks.shift(),
+      task: subagent?.context.tasks.find((t2) => t2.id === result.taskId) ?? { id: result.taskId },
       result
     });
-    if (this.pendingTasks.length > 0) {
-      const available = this.getAvailableSubagent();
-      if (available) {
-        const nextTask = this.pendingTasks.shift();
-        this.dispatch(available, nextTask);
-      }
-    } else if (this.isDone()) {
+    this.tryDispatchNext();
+    if (this.isDone()) {
       this.emit("done", {
         results: this.completedResults,
         totalIterations: this.totalIterations
       });
     }
   }
+  isDone() {
+    if (this.config.doneCondition.type === "all_tasks_done") {
+      return this.pendingTasks.length === 0 && this.inFlight === 0;
+    }
+    if (this.config.doneCondition.maxIterations !== void 0 && this.totalIterations >= this.config.doneCondition.maxIterations) {
+      return true;
+    }
+    return false;
+  }
 };
+
+// src/defaults/agent-subagent-runner.ts
+function makeAgentSubagentRunner(opts) {
+  const format = opts.formatTaskInput ?? defaultFormatTaskInput;
+  return async (task, ctx) => {
+    const { agent, events } = await opts.factory(ctx.config);
+    const aborter = new AbortController();
+    const onBudgetError = (err) => {
+      if (err instanceof BudgetExceededError) {
+        aborter.abort();
+        budgetError = err;
+      } else {
+        throw err;
+      }
+    };
+    let budgetError = null;
+    const unsub = [];
+    unsub.push(
+      events.on("tool.started", () => {
+        try {
+          ctx.budget.recordToolCall();
+        } catch (e) {
+          onBudgetError(e);
+        }
+      }),
+      events.on("provider.response", (e) => {
+        try {
+          ctx.budget.recordUsage(e.usage);
+        } catch (e2) {
+          onBudgetError(e2);
+        }
+      }),
+      events.on("iteration.started", () => {
+        try {
+          ctx.budget.recordIteration();
+          ctx.budget.checkTimeout();
+        } catch (e) {
+          onBudgetError(e);
+        }
+      })
+    );
+    const onParentAbort = () => aborter.abort();
+    ctx.signal.addEventListener("abort", onParentAbort);
+    let result;
+    try {
+      result = await agent.run(format(task, ctx.config), { signal: aborter.signal });
+    } finally {
+      ctx.signal.removeEventListener("abort", onParentAbort);
+      for (const u of unsub) u();
+    }
+    if (budgetError) throw budgetError;
+    if (result.status === "failed") {
+      throw result.error instanceof Error ? result.error : new Error(String(result.error ?? "agent failed"));
+    }
+    if (result.status === "aborted") {
+      throw new Error("agent aborted");
+    }
+    if (result.status === "max_iterations") {
+      throw new Error("agent exhausted iteration limit");
+    }
+    const usage = ctx.budget.usage();
+    return {
+      result: result.finalText,
+      iterations: result.iterations,
+      toolCalls: usage.toolCalls
+    };
+  };
+}
+function defaultFormatTaskInput(task) {
+  return task.description ?? "";
+}
+
+// src/defaults/transport/in-memory-transport.ts
 var InMemoryBridgeTransport = class {
   subs = /* @__PURE__ */ new Map();
   send(msg, to) {
+    if (to === "*") {
+      for (const [id, handlers2] of this.subs) {
+        if (id === msg.from) continue;
+        for (const h of handlers2) {
+          try {
+            h(msg);
+          } catch {
+          }
+        }
+      }
+      return Promise.resolve();
+    }
     const handlers = this.subs.get(to);
     if (handlers) {
       for (const h of handlers) {
@@ -3917,6 +4464,8 @@ var InMemoryBridgeTransport = class {
     return Promise.resolve();
   }
 };
+
+// src/defaults/agent-bridge.ts
 var InMemoryAgentBridge = class {
   agentId;
   coordinatorId;
@@ -4083,7 +4632,7 @@ var AutonomousRunner = class {
         if (e.message.includes("timeout")) {
           const timeoutResult = {
             status: "failed",
-            error: e,
+            error: toWrongStackError(e),
             iterations: this.iterations,
             toolCalls: this.toolCalls,
             reason: "iteration timeout"
@@ -4897,95 +5446,239 @@ var SpecDrivenDev = class {
     }));
   }
 };
-
-// src/defaults/tool-executor.ts
-var ToolExecutor = class {
-  constructor(registry, opts) {
-    this.registry = registry;
-    this.opts = opts;
-    this.iterationTimeoutMs = opts.iterationTimeoutMs ?? 3e5;
-    this.serializer = createToolOutputSerializer({
-      perIterationOutputCapBytes: opts.perIterationOutputCapBytes ?? 1e5
-    });
+var LOCK_FILE = "active.json";
+var DEFAULT_MAX_AGE_MS = 24 * 60 * 60 * 1e3;
+var RecoveryLock = class {
+  file;
+  pid;
+  hostname;
+  maxAgeMs;
+  sessionStore;
+  probe;
+  constructor(opts) {
+    this.file = path2.join(opts.dir, LOCK_FILE);
+    this.pid = opts.pid ?? process.pid;
+    this.hostname = opts.hostname ?? os3.hostname();
+    this.maxAgeMs = opts.maxAgeMs ?? DEFAULT_MAX_AGE_MS;
+    this.sessionStore = opts.sessionStore;
+    this.probe = opts.isPidAlive ?? defaultIsPidAlive;
   }
-  registry;
-  opts;
-  serializer;
-  iterationTimeoutMs;
   /**
-   * Execute a batch of tool uses using the configured strategy.
-   * Returns the execution results and the remaining output budget.
+   * Examine the lockfile and decide whether it represents an abandoned
+   * session. Returns `null` if the file is missing, points to a live
+   * instance, references a clean-closed session, is too old, or is
+   * malformed. Otherwise returns enough detail to prompt the user.
+   *
+   * Important: this is a read-only check. We never delete an active
+   * lock from here — if another wstack instance is alive, the caller
+   * should bail or run with a fresh session instead.
    */
-  async executeBatch(toolUses, ctx, strategy) {
-    let budget = this.opts.perIterationOutputCapBytes ?? 1e5;
-    const runOne = async (use, index) => {
-      const start = Date.now();
-      const tool = this.registry.get(use.name);
-      let result;
-      if (!tool) {
-        result = this.unknownToolResult(use, () => this.registry.list().map((t2) => t2.name));
-      } else {
-        const decision = await this.opts.permissionPolicy.evaluate(tool, use.input, ctx);
-        if (decision.permission === "deny") {
-          result = this.deniedResult(use, decision.reason);
-        } else if (decision.permission === "confirm") {
-          result = this.confirmResult(use);
-        } else {
-          try {
-            result = await this.executeTool(tool, use, ctx, budget);
-          } catch (err) {
-            const msg = err instanceof Error ? err.message : String(err);
-            const scrubbed = this.opts.secretScrubber.scrub(msg);
-            this.opts.renderer?.writeToolResult(tool.name, scrubbed, true);
-            result = {
-              type: "tool_result",
-              tool_use_id: use.id,
-              content: `Tool "${use.name}" threw: ${scrubbed}`,
-              is_error: true
-            };
-          }
-        }
-      }
-      const contentBytes = typeof result.content === "string" ? Buffer.byteLength(result.content, "utf8") : Buffer.byteLength(JSON.stringify(result.content), "utf8");
-      budget = Math.max(0, budget - contentBytes);
-      return { result, tool, durationMs: Date.now() - start };
-    };
-    if (strategy === "sequential") {
-      const outputs = [];
-      for (let i = 0; i < toolUses.length; i++) {
-        const use = toolUses[i];
-        if (use) outputs.push(await runOne(use));
-      }
-      return { outputs, remainingBudget: budget };
-    }
-    if (strategy === "parallel") {
-      const outputs = await Promise.all(toolUses.map((use, i) => runOne(use)));
-      return { outputs, remainingBudget: budget };
+  async checkAbandoned() {
+    const lock = await this.readLock();
+    if (!lock) return null;
+    const ageMs = Date.now() - new Date(lock.startedAt).getTime();
+    if (Number.isNaN(ageMs) || ageMs < 0) {
+      return null;
     }
-    const nonMutating = [];
-    const mutating = [];
-    for (let i = 0; i < toolUses.length; i++) {
-      const use = toolUses[i];
-      if (!use) continue;
-      const tool = this.registry.get(use.name);
-      if (tool?.mutating) mutating.push({ use, index: i });
-      else nonMutating.push({ use, index: i });
+    if (ageMs > this.maxAgeMs) return null;
+    if (lock.hostname === this.hostname && this.probe(lock.pid)) {
+      return null;
     }
-    const firstPass = await Promise.all(nonMutating.map(({ use, index }) => runOne(use)));
-    const secondPass = [];
-    for (const { use, index } of mutating) {
-      secondPass.push(await runOne(use));
+    let messageCount = 0;
+    if (this.sessionStore) {
+      try {
+        const data = await this.sessionStore.load(lock.sessionId);
+        const closed = data.events.some((e) => e.type === "session_end");
+        if (closed) return null;
+        messageCount = data.messages.length;
+      } catch {
+        return null;
+      }
     }
     return {
-      outputs: [...firstPass, ...secondPass],
-      remainingBudget: budget
+      sessionId: lock.sessionId,
+      pid: lock.pid,
+      startedAt: lock.startedAt,
+      ageMs,
+      messageCount
     };
   }
   /**
-   * Execute a single tool with timeout, permission check, and output capping.
-   * Emits `tool.started` via the injected EventBus (if any) right before
-   * invoking the tool — closes the observability gap between "model decided
-   * to call a tool" and "tool.executed".
+   * Claim the lock for the given session. Overwrites any existing lock
+   * — the caller should have already handled abandonment (via
+   * `checkAbandoned`) before calling this.
+   */
+  async write(sessionId) {
+    await ensureDir(path2.dirname(this.file));
+    const lock = {
+      v: 1,
+      sessionId,
+      pid: this.pid,
+      hostname: this.hostname,
+      startedAt: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    const tmp = `${this.file}.tmp`;
+    await fsp.writeFile(tmp, JSON.stringify(lock), { mode: 384 });
+    await fsp.rename(tmp, this.file);
+  }
+  /**
+   * Release the lock. Idempotent — silently succeeds if the file is
+   * already gone (e.g. someone else cleared it, or the directory was
+   * wiped).
+   */
+  async clear() {
+    try {
+      await fsp.unlink(this.file);
+    } catch (err) {
+      const code = err.code;
+      if (code === "ENOENT") return;
+      throw err;
+    }
+  }
+  async readLock() {
+    let raw;
+    try {
+      raw = await fsp.readFile(this.file, "utf8");
+    } catch (err) {
+      const code = err.code;
+      if (code === "ENOENT") return null;
+      return null;
+    }
+    try {
+      const parsed = JSON.parse(raw);
+      if (!isLockFile(parsed)) return null;
+      return parsed;
+    } catch {
+      return null;
+    }
+  }
+};
+function isLockFile(v) {
+  if (typeof v !== "object" || v === null) return false;
+  const o = v;
+  return o["v"] === 1 && typeof o["sessionId"] === "string" && typeof o["pid"] === "number" && typeof o["hostname"] === "string" && typeof o["startedAt"] === "string";
+}
+function defaultIsPidAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    const code = err.code;
+    if (code === "EPERM") return true;
+    return false;
+  }
+}
+
+// src/defaults/tool-executor.ts
+var ToolExecutor = class {
+  constructor(registry, opts) {
+    this.registry = registry;
+    this.opts = opts;
+    this.iterationTimeoutMs = opts.iterationTimeoutMs ?? 3e5;
+    this.serializer = createToolOutputSerializer({
+      perIterationOutputCapBytes: opts.perIterationOutputCapBytes ?? 1e5
+    });
+  }
+  registry;
+  opts;
+  serializer;
+  iterationTimeoutMs;
+  /**
+   * Execute a batch of tool uses using the configured strategy.
+   * Returns the execution results and the remaining output budget.
+   */
+  async executeBatch(toolUses, ctx, strategy) {
+    let budget = this.opts.perIterationOutputCapBytes ?? 1e5;
+    const runOne = async (use) => {
+      const start = Date.now();
+      const tool = this.registry.get(use.name);
+      if (!tool) {
+        const result = this.unknownToolResult(use, () => this.registry.list().map((t2) => t2.name));
+        budget = this.decrementBudget(result, budget);
+        return { result, tool, durationMs: Date.now() - start };
+      }
+      const decision = await this.opts.permissionPolicy.evaluate(tool, use.input, ctx);
+      if (decision.permission === "deny") {
+        const result = this.deniedResult(use, decision.reason);
+        budget = this.decrementBudget(result, budget);
+        return { result, tool, durationMs: Date.now() - start };
+      }
+      if (decision.permission === "confirm") {
+        if (this.opts.confirmAwaiter) {
+          const choice = await this.opts.confirmAwaiter(tool, use.input, use.id, tool.name);
+          if (choice !== "yes" && choice !== "always") {
+            const result = { type: "tool_result", tool_use_id: use.id, content: `Tool "${tool.name}" denied by user.`, is_error: true };
+            budget = this.decrementBudget(result, budget);
+            return { result, tool, durationMs: Date.now() - start };
+          }
+        } else {
+          const suggestedPattern = this.subjectFor(tool.name, use.input) ?? tool.name;
+          const pending = { type: "tool_confirm_pending", toolUseId: use.id, toolName: tool.name, input: use.input, suggestedPattern };
+          return { result: pending, tool, durationMs: Date.now() - start };
+        }
+      }
+      const span = this.opts.tracer?.startSpan(`tool.${tool.name}`, {
+        "tool.name": tool.name,
+        "tool.mutating": tool.mutating,
+        "tool.permission": tool.permission
+      });
+      try {
+        const result = await this.executeTool(tool, use, ctx, budget);
+        budget = this.decrementBudget(result, budget);
+        span?.setAttribute("tool.is_error", !!result.is_error);
+        span?.setAttribute(
+          "tool.output_bytes",
+          typeof result.content === "string" ? result.content.length : 0
+        );
+        return { result, tool, durationMs: Date.now() - start };
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        const scrubbed = this.opts.secretScrubber.scrub(msg);
+        this.opts.renderer?.writeToolResult(tool.name, scrubbed, true);
+        const result = { type: "tool_result", tool_use_id: use.id, content: `Tool "${tool.name}" threw: ${scrubbed}`, is_error: true };
+        budget = this.decrementBudget(result, budget);
+        if (err instanceof Error) span?.recordError(err);
+        span?.setAttribute("tool.is_error", true);
+        return { result, tool, durationMs: Date.now() - start };
+      } finally {
+        span?.end();
+      }
+    };
+    if (strategy === "sequential") {
+      const outputs = [];
+      for (const use of toolUses) {
+        if (use) outputs.push(await runOne(use));
+      }
+      return { outputs, remainingBudget: budget };
+    }
+    if (strategy === "parallel") {
+      const outputs = await Promise.all(toolUses.map((use) => runOne(use)));
+      return { outputs, remainingBudget: budget };
+    }
+    const nonMutating = [];
+    const mutating = [];
+    for (const use of toolUses) {
+      if (!use) continue;
+      const tool = this.registry.get(use.name);
+      if (tool?.mutating) mutating.push(use);
+      else nonMutating.push(use);
+    }
+    const firstPass = await Promise.all(nonMutating.map((use) => runOne(use)));
+    const secondPass = [];
+    for (const use of mutating) {
+      secondPass.push(await runOne(use));
+    }
+    return {
+      outputs: [...firstPass, ...secondPass],
+      remainingBudget: budget
+    };
+  }
+  /**
+   * Execute a single tool with timeout, permission check, and output capping.
+   * Emits `tool.started` via the injected EventBus (if any) right before
+   * invoking the tool — closes the observability gap between "model decided
+   * to call a tool" and "tool.executed".
    */
   async executeTool(tool, use, ctx, budget) {
     this.opts.events?.emit("tool.started", {
@@ -4994,7 +5687,7 @@ var ToolExecutor = class {
       input: use.input
     });
     this.opts.renderer?.writeToolCall(tool.name, use.input);
-    const output = await this.runWithTimeout(tool, use.input, ctx.signal, ctx);
+    const output = await this.runWithTimeout(tool, use.input, ctx.signal, ctx, use.id);
     const text = this.serializer.serialize(output);
     const scrubbed = this.opts.secretScrubber.scrub(text);
     const { text: capped } = this.serializer.enforceCap(scrubbed, budget);
@@ -5007,20 +5700,52 @@ var ToolExecutor = class {
       is_error: false
     };
   }
-  async runWithTimeout(tool, input, parentSignal, ctx) {
+  async runWithTimeout(tool, input, parentSignal, ctx, toolUseId) {
     if (parentSignal.aborted) {
       throw parentSignal.reason instanceof Error ? parentSignal.reason : new Error(typeof parentSignal.reason === "string" ? parentSignal.reason : "aborted");
     }
     const timeoutMs = tool.timeoutMs ?? this.iterationTimeoutMs;
     const ctrl = new AbortController();
     const timer = setTimeout(() => ctrl.abort(new Error("tool timeout")), timeoutMs);
-    const combined = anySignal([parentSignal, ctrl.signal]);
+    const combined = AbortSignal.any([parentSignal, ctrl.signal]);
     try {
+      if (typeof tool.executeStream === "function") {
+        return await this.runStreamedTool(tool, input, ctx, combined, toolUseId);
+      }
       return await tool.execute(input, ctx, { signal: combined });
+    } catch (err) {
+      if (combined.aborted && typeof tool.cleanup === "function") {
+        try {
+          await tool.cleanup(input, ctx);
+        } catch {
+        }
+      }
+      throw err;
     } finally {
       clearTimeout(timer);
     }
   }
+  async runStreamedTool(tool, input, ctx, signal, toolUseId) {
+    let finalOutput;
+    let sawFinal = false;
+    const stream = tool.executeStream(input, ctx, { signal });
+    for await (const ev of stream) {
+      if (ev.type === "final") {
+        finalOutput = ev.output;
+        sawFinal = true;
+        break;
+      }
+      this.opts.events?.emit("tool.progress", {
+        name: tool.name,
+        id: toolUseId ?? "<unknown>",
+        event: ev
+      });
+    }
+    if (!sawFinal) {
+      throw new Error(`tool "${tool.name}" executeStream completed without a 'final' event`);
+    }
+    return finalOutput;
+  }
   unknownToolResult(use, listFns) {
     return {
       type: "tool_result",
@@ -5037,32 +5762,959 @@ var ToolExecutor = class {
       is_error: true
     };
   }
-  confirmResult(use) {
-    return {
-      type: "tool_result",
-      tool_use_id: use.id,
-      content: `Tool "${use.name}" requires user confirmation but no prompt handler was available.`,
-      is_error: true
+  decrementBudget(result, budget) {
+    const contentBytes = typeof result.content === "string" ? Buffer.byteLength(result.content, "utf8") : Buffer.byteLength(JSON.stringify(result.content), "utf8");
+    return Math.max(0, budget - contentBytes);
+  }
+  /**
+   * Compute the suggestedPattern string for a tool+input pair.
+   * Matches the logic in DefaultPermissionPolicy so the TUI shows the
+   * same subject that the trust file would use.
+   */
+  subjectFor(toolName, input) {
+    if (!input || typeof input !== "object") return void 0;
+    const obj = input;
+    const globChars = /[*?\[\]]/g;
+    const escapeGlob = (s) => s.replace(globChars, (c) => `\\${c}`);
+    if (toolName === "bash" && typeof obj.command === "string") {
+      return escapeGlob(obj.command);
+    }
+    if (typeof obj.path === "string") {
+      return escapeGlob(obj.path.replace(/\\/g, "/"));
+    }
+    if (typeof obj.url === "string") {
+      return escapeGlob(obj.url);
+    }
+    if (typeof obj.name === "string") {
+      return escapeGlob(obj.name);
+    }
+    return void 0;
+  }
+};
+
+// src/defaults/session-reader.ts
+var DefaultSessionReader = class {
+  store;
+  constructor(opts) {
+    this.store = opts.store;
+  }
+  async query(q = {}) {
+    const raw = await this.store.list(q.limit ? Math.max(q.limit * 4, 100) : 1e3);
+    const titleNeedle = q.titleContains?.toLowerCase();
+    const filtered = raw.filter((s) => {
+      if (q.since && s.startedAt < q.since) return false;
+      if (q.until && s.startedAt > q.until) return false;
+      if (q.provider && s.provider !== q.provider) return false;
+      if (q.model && s.model !== q.model) return false;
+      if (q.minTokens !== void 0 && s.tokenTotal < q.minTokens) return false;
+      if (titleNeedle && !s.title.toLowerCase().includes(titleNeedle)) return false;
+      return true;
+    });
+    const out = filtered.map((s) => ({
+      id: s.id,
+      title: s.title,
+      startedAt: s.startedAt,
+      provider: s.provider,
+      model: s.model,
+      tokenTotal: s.tokenTotal
+    }));
+    return q.limit ? out.slice(0, q.limit) : out;
+  }
+  async *replay(sessionId) {
+    const data = await this.store.load(sessionId);
+    for (const e of data.events) yield e;
+  }
+  async search(q, sessionId) {
+    const limit = q.limit ?? 100;
+    const matcher = buildMatcher(q);
+    const allowedTypes = q.types ? new Set(q.types) : null;
+    const ids = sessionId ? [sessionId] : (await this.store.list(1e3)).map((s) => s.id);
+    const hits = [];
+    for (const id of ids) {
+      let data;
+      try {
+        data = await this.store.load(id);
+      } catch {
+        continue;
+      }
+      for (let i = 0; i < data.events.length; i++) {
+        const ev = data.events[i];
+        if (allowedTypes && !allowedTypes.has(ev.type)) continue;
+        const text = eventText(ev);
+        if (text === null) continue;
+        const hit = matcher(text);
+        if (!hit) continue;
+        hits.push({
+          sessionId: id,
+          eventIndex: i,
+          ts: ev.ts,
+          type: ev.type,
+          snippet: snippetOf(text, hit.start, hit.end)
+        });
+        if (hits.length >= limit) return hits;
+      }
+    }
+    return hits;
+  }
+  async export(sessionId, opts) {
+    const data = await this.store.load(sessionId);
+    const includeTools = opts.includeTools ?? true;
+    const includeDiagnostics = opts.includeDiagnostics ?? true;
+    const filtered = data.events.filter((e) => {
+      if (!includeTools && (e.type === "tool_use" || e.type === "tool_result" || e.type === "tool_call_start" || e.type === "tool_call_end")) {
+        return false;
+      }
+      if (!includeDiagnostics && (e.type === "error" || e.type === "compaction" || e.type === "message_truncated")) {
+        return false;
+      }
+      return true;
+    });
+    if (opts.format === "json") {
+      return JSON.stringify({ metadata: data.metadata, events: filtered }, null, 2);
+    }
+    if (opts.format === "text") {
+      return renderPlainText(data.metadata, filtered);
+    }
+    return renderMarkdown(data.metadata, filtered);
+  }
+  async metadata(sessionId) {
+    const data = await this.store.load(sessionId);
+    return data.metadata;
+  }
+};
+function buildMatcher(q) {
+  const ci = q.caseInsensitive ?? true;
+  if (q.regex) {
+    const flags = ci ? "i" : "";
+    const re = new RegExp(q.query, flags);
+    return (text) => {
+      const m = re.exec(text);
+      return m ? { start: m.index, end: m.index + m[0].length } : null;
     };
   }
+  const needle = ci ? q.query.toLowerCase() : q.query;
+  return (text) => {
+    const hay = ci ? text.toLowerCase() : text;
+    const idx = hay.indexOf(needle);
+    return idx === -1 ? null : { start: idx, end: idx + needle.length };
+  };
+}
+function eventText(e) {
+  switch (e.type) {
+    case "user_input":
+      return contentToString(e.content);
+    case "llm_response":
+      return contentToString(e.content);
+    case "tool_use":
+      return `${e.name} ${JSON.stringify(e.input)}`;
+    case "tool_result":
+      return typeof e.content === "string" ? e.content : JSON.stringify(e.content);
+    case "error":
+      return `${e.phase}: ${e.message}`;
+    case "session_start":
+    case "session_resumed":
+      return `${e.model}/${e.provider}`;
+    case "task_created":
+    case "task_completed":
+      return e.title;
+    case "task_failed":
+      return `${e.title}: ${e.error}`;
+    case "skill_activated":
+    case "skill_deactivated":
+      return e.skillName;
+    default:
+      return null;
+  }
+}
+function contentToString(content) {
+  if (typeof content === "string") return content;
+  return content.map((b) => {
+    switch (b.type) {
+      case "text":
+        return b.text;
+      case "tool_use":
+        return `[tool_use:${b.name} ${JSON.stringify(b.input)}]`;
+      case "tool_result":
+        return typeof b.content === "string" ? b.content : JSON.stringify(b.content);
+      default:
+        return "";
+    }
+  }).join("\n");
+}
+var SNIPPET_RADIUS = 60;
+function snippetOf(text, start, end) {
+  const from = Math.max(0, start - SNIPPET_RADIUS);
+  const to = Math.min(text.length, end + SNIPPET_RADIUS);
+  const prefix = from > 0 ? "\u2026" : "";
+  const suffix = to < text.length ? "\u2026" : "";
+  return prefix + text.slice(from, to).replace(/\s+/g, " ").trim() + suffix;
+}
+function renderMarkdown(meta, events) {
+  const lines = [];
+  lines.push(`# Session ${meta.id}`);
+  lines.push("");
+  if (meta.model || meta.provider) {
+    lines.push(`- **Model:** ${meta.provider ?? "?"}/${meta.model ?? "?"}`);
+  }
+  lines.push(`- **Started:** ${meta.startedAt}`);
+  if (meta.endedAt) lines.push(`- **Ended:** ${meta.endedAt}`);
+  lines.push("");
+  lines.push("---");
+  lines.push("");
+  for (const e of events) {
+    switch (e.type) {
+      case "user_input": {
+        lines.push(`## User \u2014 ${e.ts}`);
+        lines.push("");
+        lines.push(contentToString(e.content));
+        lines.push("");
+        break;
+      }
+      case "llm_response": {
+        lines.push(`## Assistant \u2014 ${e.ts}`);
+        lines.push("");
+        lines.push(contentToString(e.content));
+        if (e.stopReason && e.stopReason !== "end_turn") {
+          lines.push("");
+          lines.push(`*stop: ${e.stopReason}*`);
+        }
+        lines.push("");
+        break;
+      }
+      case "tool_use": {
+        lines.push(`### Tool call: \`${e.name}\``);
+        lines.push("");
+        lines.push("```json");
+        lines.push(JSON.stringify(e.input, null, 2));
+        lines.push("```");
+        lines.push("");
+        break;
+      }
+      case "tool_result": {
+        const body = typeof e.content === "string" ? e.content : JSON.stringify(e.content, null, 2);
+        lines.push(`### Tool result${e.isError ? " (error)" : ""}`);
+        lines.push("");
+        lines.push("```");
+        lines.push(body);
+        lines.push("```");
+        lines.push("");
+        break;
+      }
+      case "error": {
+        lines.push(`> **Error** (${e.phase}): ${e.message}`);
+        lines.push("");
+        break;
+      }
+      case "compaction": {
+        lines.push(`> **Compaction**: ${e.before} \u2192 ${e.after} tokens`);
+        lines.push("");
+        break;
+      }
+    }
+  }
+  return lines.join("\n");
+}
+function renderPlainText(meta, events) {
+  const lines = [];
+  lines.push(`Session ${meta.id} \u2014 ${meta.provider ?? "?"}/${meta.model ?? "?"} \u2014 started ${meta.startedAt}`);
+  lines.push("".padEnd(72, "-"));
+  for (const e of events) {
+    switch (e.type) {
+      case "user_input":
+        lines.push(`[${e.ts}] USER`);
+        lines.push(contentToString(e.content));
+        lines.push("");
+        break;
+      case "llm_response":
+        lines.push(`[${e.ts}] ASSISTANT`);
+        lines.push(contentToString(e.content));
+        lines.push("");
+        break;
+      case "tool_use":
+        lines.push(`[${e.ts}] TOOL_USE ${e.name} ${JSON.stringify(e.input)}`);
+        break;
+      case "tool_result":
+        lines.push(
+          `[${e.ts}] TOOL_RESULT${e.isError ? " (error)" : ""} ${typeof e.content === "string" ? e.content : JSON.stringify(e.content)}`
+        );
+        break;
+      case "error":
+        lines.push(`[${e.ts}] ERROR (${e.phase}): ${e.message}`);
+        break;
+    }
+  }
+  return lines.join("\n");
+}
+
+// src/defaults/observability/metrics.ts
+var RESERVOIR_SIZE = 1024;
+function labelKey(labels) {
+  if (!labels) return "";
+  const keys = Object.keys(labels).sort();
+  return keys.map((k) => `${k}=${labels[k]}`).join(",");
+}
+function quantile(sorted, q) {
+  if (sorted.length === 0) return 0;
+  const idx = Math.min(sorted.length - 1, Math.floor(q * sorted.length));
+  return sorted[idx] ?? 0;
+}
+var InMemoryMetricsSink = class {
+  counters = /* @__PURE__ */ new Map();
+  gauges = /* @__PURE__ */ new Map();
+  histograms = /* @__PURE__ */ new Map();
+  counter(name, value = 1, labels) {
+    const series = this.getOrCreate(this.counters, name);
+    const key = labelKey(labels);
+    const state = series.get(key) ?? { value: 0 };
+    state.value += value;
+    series.set(key, state);
+  }
+  gauge(name, value, labels) {
+    const series = this.getOrCreate(this.gauges, name);
+    series.set(labelKey(labels), { value });
+  }
+  histogram(name, value, labels) {
+    const series = this.getOrCreate(this.histograms, name);
+    const key = labelKey(labels);
+    let state = series.get(key);
+    if (!state) {
+      state = { count: 0, sum: 0, min: value, max: value, samples: [] };
+      series.set(key, state);
+    }
+    state.count++;
+    state.sum += value;
+    if (value < state.min) state.min = value;
+    if (value > state.max) state.max = value;
+    if (state.samples.length < RESERVOIR_SIZE) {
+      state.samples.push(value);
+    } else {
+      const r = Math.floor(Math.random() * state.count);
+      if (r < RESERVOIR_SIZE) state.samples[r] = value;
+    }
+  }
+  snapshot() {
+    const series = [];
+    for (const [name, byLabel] of this.counters) {
+      for (const [key, state] of byLabel) {
+        series.push({
+          name,
+          type: "counter",
+          labels: parseLabelKey(key),
+          values: { value: state.value }
+        });
+      }
+    }
+    for (const [name, byLabel] of this.gauges) {
+      for (const [key, state] of byLabel) {
+        series.push({
+          name,
+          type: "gauge",
+          labels: parseLabelKey(key),
+          values: { value: state.value }
+        });
+      }
+    }
+    for (const [name, byLabel] of this.histograms) {
+      for (const [key, state] of byLabel) {
+        const sorted = [...state.samples].sort((a, b) => a - b);
+        series.push({
+          name,
+          type: "histogram",
+          labels: parseLabelKey(key),
+          values: {
+            count: state.count,
+            sum: state.sum,
+            min: state.min,
+            max: state.max,
+            p50: quantile(sorted, 0.5),
+            p95: quantile(sorted, 0.95),
+            p99: quantile(sorted, 0.99)
+          }
+        });
+      }
+    }
+    return { timestamp: Date.now(), series };
+  }
+  reset() {
+    this.counters.clear();
+    this.gauges.clear();
+    this.histograms.clear();
+  }
+  getOrCreate(bag, name) {
+    let series = bag.get(name);
+    if (!series) {
+      series = /* @__PURE__ */ new Map();
+      bag.set(name, series);
+    }
+    return series;
+  }
 };
-function anySignal(signals) {
-  if (typeof AbortSignal.any === "function") {
-    return AbortSignal.any(signals);
+function parseLabelKey(key) {
+  if (!key) return {};
+  const labels = {};
+  for (const pair of key.split(",")) {
+    const eq = pair.indexOf("=");
+    if (eq > 0) labels[pair.slice(0, eq)] = pair.slice(eq + 1);
+  }
+  return labels;
+}
+var NoopMetricsSink = class {
+  counter() {
+  }
+  gauge() {
+  }
+  histogram() {
+  }
+  snapshot() {
+    return { timestamp: Date.now(), series: [] };
+  }
+  reset() {
+  }
+};
+
+// src/defaults/observability/health.ts
+var SEVERITY = {
+  healthy: 0,
+  degraded: 1,
+  unhealthy: 2
+};
+var DefaultHealthRegistry = class {
+  checks = /* @__PURE__ */ new Map();
+  timeoutMs;
+  constructor(opts = {}) {
+    this.timeoutMs = opts.timeoutMs ?? 5e3;
+  }
+  register(check) {
+    this.checks.set(check.name, check);
+  }
+  unregister(name) {
+    this.checks.delete(name);
+  }
+  async run() {
+    const results = await Promise.all(
+      Array.from(this.checks.values()).map(async (c) => {
+        const result = await this.runOne(c);
+        return { name: c.name, ...result };
+      })
+    );
+    let status = "healthy";
+    for (const r of results) {
+      if (SEVERITY[r.status] > SEVERITY[status]) status = r.status;
+    }
+    return { status, timestamp: Date.now(), checks: results };
+  }
+  async runOne(check) {
+    const timeout = new Promise((resolve4) => {
+      setTimeout(
+        () => resolve4({ status: "unhealthy", detail: `timeout after ${this.timeoutMs}ms` }),
+        this.timeoutMs
+      );
+    });
+    try {
+      return await Promise.race([check.check(), timeout]);
+    } catch (err) {
+      return { status: "unhealthy", detail: err instanceof Error ? err.message : String(err) };
+    }
+  }
+};
+
+// src/defaults/observability/tracer.ts
+var NoopTracer = class {
+  startSpan() {
+    return NOOP_SPAN;
+  }
+};
+var NOOP_SPAN = {
+  setAttribute() {
+  },
+  recordError() {
+  },
+  end() {
+  }
+};
+
+// src/defaults/observability/otel-tracer.ts
+var OTEL_STATUS_ERROR = 2;
+var OTelTracer = class {
+  constructor(upstream) {
+    this.upstream = upstream;
+  }
+  upstream;
+  startSpan(name, attrs) {
+    const otelSpan = this.upstream.startSpan(name, attrs ? { attributes: attrs } : void 0);
+    return new OTelSpan(otelSpan);
+  }
+};
+var OTelSpan = class {
+  constructor(span) {
+    this.span = span;
+  }
+  span;
+  setAttribute(key, value) {
+    this.span.setAttribute(key, value);
+  }
+  recordError(err) {
+    this.span.recordException(err);
+    this.span.setStatus?.({ code: OTEL_STATUS_ERROR, message: err.message });
+  }
+  end() {
+    this.span.end();
+  }
+};
+
+// src/defaults/observability/event-bridge.ts
+function wireMetricsToEvents(events, sink) {
+  const unsubs = [];
+  unsubs.push(
+    events.on("session.started", () => sink.counter("agent.sessions.started")),
+    events.on("session.ended", (e) => {
+      sink.counter("agent.sessions.ended");
+      sink.histogram("agent.session.tokens.input", e.usage.input);
+      sink.histogram("agent.session.tokens.output", e.usage.output);
+    }),
+    events.on("session.damaged", () => sink.counter("agent.sessions.damaged")),
+    events.on("iteration.completed", () => sink.counter("agent.iterations.total")),
+    events.on("iteration.limit_reached", () => sink.counter("agent.iteration_limit.hit")),
+    events.on("provider.response", (e) => {
+      sink.counter("provider.responses.total", 1, { stop_reason: e.stopReason });
+      sink.counter("provider.tokens.input", e.usage.input);
+      sink.counter("provider.tokens.output", e.usage.output);
+      if (e.usage.cacheRead) sink.counter("provider.tokens.cache_read", e.usage.cacheRead);
+      if (e.usage.cacheWrite) sink.counter("provider.tokens.cache_write", e.usage.cacheWrite);
+    }),
+    events.on(
+      "provider.retry",
+      (e) => sink.counter("provider.retries.total", 1, {
+        provider: e.providerId,
+        status: String(e.status)
+      })
+    ),
+    events.on(
+      "provider.error",
+      (e) => sink.counter("provider.errors.total", 1, {
+        provider: e.providerId,
+        status: String(e.status),
+        retryable: String(e.retryable)
+      })
+    ),
+    events.on("tool.started", (e) => sink.counter("tool.starts.total", 1, { tool: e.name })),
+    events.on("tool.executed", (e) => {
+      sink.counter("tool.executions.total", 1, { tool: e.name, ok: String(e.ok) });
+      sink.histogram("tool.duration_ms", e.durationMs, { tool: e.name });
+    }),
+    events.on("token.threshold", (e) => sink.gauge("agent.tokens.used", e.used)),
+    events.on("compaction.fired", (e) => {
+      sink.counter("compaction.fired.total");
+      sink.histogram("compaction.reduction_tokens", e.before - e.after);
+    }),
+    events.on(
+      "mcp.server.connected",
+      (e) => sink.counter("mcp.connects.total", 1, { server: e.name })
+    ),
+    events.on(
+      "mcp.server.reconnected",
+      (e) => sink.counter("mcp.reconnects.total", 1, { server: e.name })
+    ),
+    events.on(
+      "mcp.server.disconnected",
+      (e) => sink.counter("mcp.disconnects.total", 1, { server: e.name })
+    ),
+    events.on("error", (e) => sink.counter("agent.errors.total", 1, { phase: e.phase }))
+  );
+  return () => {
+    for (const u of unsubs) u();
+  };
+}
+
+// src/defaults/observability/prometheus.ts
+var NUMBER_FORMAT_INFINITY = "NaN";
+function escapeLabelValue(v) {
+  return v.replace(/\\/g, "\\\\").replace(/\n/g, "\\n").replace(/"/g, '\\"');
+}
+function formatLabels(labels) {
+  const keys = Object.keys(labels);
+  if (keys.length === 0) return "";
+  const parts = keys.map((k) => `${k}="${escapeLabelValue(labels[k] ?? "")}"`);
+  return `{${parts.join(",")}}`;
+}
+function formatNumber(n) {
+  if (!Number.isFinite(n)) return NUMBER_FORMAT_INFINITY;
+  return Number.isInteger(n) ? n.toString() : n.toString();
+}
+function joinLabels(base, extra) {
+  return { ...base, ...extra };
+}
+function renderPrometheus(snapshot) {
+  const groups = /* @__PURE__ */ new Map();
+  for (const s of snapshot.series) {
+    let g = groups.get(s.name);
+    if (!g) {
+      g = { type: s.type, rows: [] };
+      groups.set(s.name, g);
+    }
+    g.rows.push({ labels: s.labels, values: s.values });
+  }
+  const lines = [];
+  for (const [name, g] of groups) {
+    const promType = g.type === "histogram" ? "summary" : g.type;
+    lines.push(`# HELP ${name} ${name}`);
+    lines.push(`# TYPE ${name} ${promType}`);
+    if (g.type === "counter" || g.type === "gauge") {
+      for (const row of g.rows) {
+        lines.push(`${name}${formatLabels(row.labels)} ${formatNumber(row.values.value ?? 0)}`);
+      }
+    } else {
+      for (const row of g.rows) {
+        const { count = 0, sum = 0, p50 = 0, p95 = 0, p99 = 0 } = row.values;
+        lines.push(
+          `${name}${formatLabels(joinLabels(row.labels, { quantile: "0.5" }))} ${formatNumber(p50)}`
+        );
+        lines.push(
+          `${name}${formatLabels(joinLabels(row.labels, { quantile: "0.95" }))} ${formatNumber(p95)}`
+        );
+        lines.push(
+          `${name}${formatLabels(joinLabels(row.labels, { quantile: "0.99" }))} ${formatNumber(p99)}`
+        );
+        lines.push(`${name}_sum${formatLabels(row.labels)} ${formatNumber(sum)}`);
+        lines.push(`${name}_count${formatLabels(row.labels)} ${formatNumber(count)}`);
+      }
+    }
+  }
+  return lines.join("\n") + "\n";
+}
+var PROMETHEUS_CONTENT_TYPE = "text/plain; version=0.0.4; charset=utf-8";
+async function startMetricsServer(opts) {
+  const { createServer } = await import('http');
+  const host = opts.host ?? "127.0.0.1";
+  const path15 = opts.path ?? "/metrics";
+  const healthPath = opts.healthPath ?? "/healthz";
+  const healthRegistry = opts.healthRegistry;
+  const server = createServer((req, res) => {
+    if (!req.url || req.method !== "GET") {
+      res.statusCode = req.url ? 405 : 400;
+      res.end();
+      return;
+    }
+    const url = req.url.split("?")[0];
+    if (url === path15) {
+      let body;
+      try {
+        body = renderPrometheus(opts.sink.snapshot());
+      } catch (err) {
+        res.statusCode = 500;
+        res.setHeader("content-type", "text/plain; charset=utf-8");
+        res.end(`metrics render failed: ${err instanceof Error ? err.message : String(err)}`);
+        return;
+      }
+      res.statusCode = 200;
+      res.setHeader("content-type", PROMETHEUS_CONTENT_TYPE);
+      res.end(body);
+      return;
+    }
+    if (healthRegistry && url === healthPath) {
+      healthRegistry.run().then(
+        (agg) => {
+          res.statusCode = agg.status === "unhealthy" ? 503 : 200;
+          res.setHeader("content-type", "application/json; charset=utf-8");
+          res.end(JSON.stringify(agg, null, 2));
+        },
+        (err) => {
+          res.statusCode = 500;
+          res.setHeader("content-type", "text/plain; charset=utf-8");
+          res.end(`health run failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+      );
+      return;
+    }
+    res.statusCode = 404;
+    res.setHeader("content-type", "text/plain; charset=utf-8");
+    res.end("Not Found");
+  });
+  await new Promise((resolve4, reject) => {
+    const onError = (err) => {
+      server.off("listening", onListening);
+      reject(err);
+    };
+    const onListening = () => {
+      server.off("error", onError);
+      resolve4();
+    };
+    server.once("error", onError);
+    server.once("listening", onListening);
+    server.listen(opts.port, host);
+  });
+  const addr = server.address();
+  const boundPort = typeof addr === "object" && addr ? addr.port : opts.port;
+  return {
+    port: boundPort,
+    url: `http://${host}:${boundPort}${path15}`,
+    close: () => new Promise((resolve4, reject) => {
+      server.close((err) => err ? reject(err) : resolve4());
+    })
+  };
+}
+
+// src/defaults/observability/otlp-metrics.ts
+var DEFAULT_INTERVAL_MS = 3e4;
+var DEFAULT_TIMEOUT_MS = 1e4;
+function joinEndpoint(base) {
+  if (/\/v1\/metrics\/?$/.test(base)) return base;
+  return base.replace(/\/$/, "") + "/v1/metrics";
+}
+function attributesFor(labels) {
+  return Object.entries(labels).map(([key, value]) => ({
+    key,
+    value: { stringValue: value }
+  }));
+}
+function buildExportBody(opts) {
+  const metrics = [];
+  for (const s of opts.series) {
+    const dp = {
+      attributes: attributesFor(s.labels),
+      timeUnixNano: opts.timeUnixNano
+    };
+    if (s.type === "counter") {
+      dp.asDouble = s.values.value ?? 0;
+      metrics.push({
+        name: s.name,
+        sum: { dataPoints: [dp], aggregationTemporality: 2, isMonotonic: true }
+      });
+    } else if (s.type === "gauge") {
+      dp.asDouble = s.values.value ?? 0;
+      metrics.push({ name: s.name, gauge: { dataPoints: [dp] } });
+    } else {
+      dp.count = String(s.values.count ?? 0);
+      dp.sum = s.values.sum ?? 0;
+      dp.quantileValues = [
+        { quantile: 0.5, value: s.values.p50 ?? 0 },
+        { quantile: 0.95, value: s.values.p95 ?? 0 },
+        { quantile: 0.99, value: s.values.p99 ?? 0 }
+      ];
+      metrics.push({ name: s.name, summary: { dataPoints: [dp] } });
+    }
   }
-  const ctrl = new AbortController();
-  const abortSources = [];
-  for (const s of signals) {
-    if (s.aborted) {
-      ctrl.abort(s.reason);
-      return ctrl.signal;
+  return {
+    resourceMetrics: [
+      {
+        resource: { attributes: attributesFor(opts.resourceAttributes) },
+        scopeMetrics: [
+          {
+            scope: { name: opts.scopeName },
+            metrics
+          }
+        ]
+      }
+    ]
+  };
+}
+function buildOtlpMetricsRequest(sink, opts = {}) {
+  return buildExportBody({
+    series: sink.snapshot().series,
+    resourceAttributes: opts.resourceAttributes ?? { "service.name": "wrongstack" },
+    scopeName: opts.scopeName ?? "wrongstack",
+    timeUnixNano: String(BigInt(Date.now()) * 1000000n)
+  });
+}
+function startOtlpMetricsExporter(opts) {
+  const url = joinEndpoint(opts.endpoint);
+  const intervalMs = opts.intervalMs ?? DEFAULT_INTERVAL_MS;
+  const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const fetchImpl = opts.fetchImpl ?? globalThis.fetch;
+  const onError = opts.onError ?? (() => {
+  });
+  const resourceAttributes = opts.resourceAttributes ?? { "service.name": "wrongstack" };
+  const scopeName = opts.scopeName ?? "wrongstack";
+  let stopped = false;
+  const headers = {
+    "content-type": "application/json",
+    ...opts.headers ?? {}
+  };
+  if (opts.authorization) headers.authorization = opts.authorization;
+  async function pushOnce() {
+    if (stopped) return;
+    const body = buildExportBody({
+      series: opts.sink.snapshot().series,
+      resourceAttributes,
+      scopeName,
+      timeUnixNano: String(BigInt(Date.now()) * 1000000n)
+    });
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+      const res = await fetchImpl(url, {
+        method: "POST",
+        headers,
+        body: JSON.stringify(body),
+        signal: controller.signal
+      });
+      if (!res.ok) {
+        const text = await res.text().catch(() => "");
+        onError(new Error(`OTLP push failed: ${res.status} ${res.statusText} ${text}`));
+      }
+    } catch (err) {
+      onError(err);
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+  const handle = setInterval(() => {
+    void pushOnce();
+  }, intervalMs);
+  handle.unref?.();
+  return {
+    flush: pushOnce,
+    async stop() {
+      stopped = true;
+      clearInterval(handle);
+      await pushOnce().catch(onError);
+    }
+  };
+}
+var SPAN_STATUS_CODE_UNSET = 0;
+var SPAN_STATUS_CODE_OK = 1;
+var SPAN_STATUS_CODE_ERROR = 2;
+function hex(bytes) {
+  return crypto2.randomBytes(bytes).toString("hex");
+}
+function nowNs() {
+  return BigInt(Date.now()) * 1000000n;
+}
+var CapturingSpan = class {
+  constructor(state, onEnd) {
+    this.state = state;
+    this.onEnd = onEnd;
+  }
+  state;
+  onEnd;
+  setAttribute(key, value) {
+    this.state.attributes[key] = value;
+  }
+  recordError(err) {
+    this.state.status = { code: SPAN_STATUS_CODE_ERROR, message: err.message };
+    this.state.attributes["exception.message"] = err.message;
+    if (err.name) this.state.attributes["exception.type"] = err.name;
+  }
+  end() {
+    if (this.state.endTimeUnixNano !== void 0) return;
+    this.state.endTimeUnixNano = nowNs();
+    if (this.state.status.code === SPAN_STATUS_CODE_UNSET) {
+      this.state.status.code = SPAN_STATUS_CODE_OK;
     }
-    abortSources.push(s);
+    this.onEnd(this.state);
   }
-  for (const s of abortSources) {
-    s.addEventListener("abort", () => ctrl.abort(s.reason), { once: true });
+};
+var DEFAULT_INTERVAL_MS2 = 5e3;
+var DEFAULT_BUFFER_CAP = 2048;
+var DEFAULT_TIMEOUT_MS2 = 1e4;
+function joinEndpoint2(base) {
+  if (/\/v1\/traces\/?$/.test(base)) return base;
+  return base.replace(/\/$/, "") + "/v1/traces";
+}
+function encodeAttr(key, value) {
+  if (typeof value === "boolean") return { key, value: { boolValue: value } };
+  if (typeof value === "number") {
+    return Number.isInteger(value) ? { key, value: { intValue: String(value) } } : { key, value: { doubleValue: value } };
   }
-  return ctrl.signal;
+  return { key, value: { stringValue: value } };
+}
+function buildOtlpTracesRequest(spans, opts = {}) {
+  const resourceAttributes = opts.resourceAttributes ?? { "service.name": "wrongstack" };
+  const scopeName = opts.scopeName ?? "wrongstack";
+  const otlpSpans = spans.map((s) => ({
+    traceId: s.traceId,
+    spanId: s.spanId,
+    name: s.name,
+    kind: 1,
+    // SPAN_KIND_INTERNAL
+    startTimeUnixNano: s.startTimeUnixNano.toString(),
+    endTimeUnixNano: (s.endTimeUnixNano ?? s.startTimeUnixNano).toString(),
+    attributes: Object.entries(s.attributes).map(([k, v]) => encodeAttr(k, v)),
+    status: s.status
+  }));
+  return {
+    resourceSpans: [
+      {
+        resource: {
+          attributes: Object.entries(resourceAttributes).map(
+            ([k, v]) => encodeAttr(k, v)
+          )
+        },
+        scopeSpans: [{ scope: { name: scopeName }, spans: otlpSpans }]
+      }
+    ]
+  };
+}
+function startOtlpTraceExporter(opts) {
+  const url = joinEndpoint2(opts.endpoint);
+  const intervalMs = opts.intervalMs ?? DEFAULT_INTERVAL_MS2;
+  const maxBuffered = opts.maxBufferedSpans ?? DEFAULT_BUFFER_CAP;
+  const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS2;
+  const fetchImpl = opts.fetchImpl ?? globalThis.fetch;
+  const onError = opts.onError ?? (() => {
+  });
+  const resourceAttributes = opts.resourceAttributes ?? { "service.name": "wrongstack" };
+  const scopeName = opts.scopeName ?? "wrongstack";
+  let stopped = false;
+  const buffer = [];
+  const headers = {
+    "content-type": "application/json",
+    ...opts.headers ?? {}
+  };
+  if (opts.authorization) headers.authorization = opts.authorization;
+  const tracer = {
+    startSpan(name, attrs) {
+      const state = {
+        traceId: hex(16),
+        spanId: hex(8),
+        name,
+        startTimeUnixNano: nowNs(),
+        attributes: { ...attrs ?? {} },
+        status: { code: SPAN_STATUS_CODE_UNSET }
+      };
+      return new CapturingSpan(state, (ended) => {
+        if (buffer.length >= maxBuffered) buffer.shift();
+        buffer.push(ended);
+      });
+    }
+  };
+  async function pushOnce() {
+    if (buffer.length === 0) return;
+    const batch = buffer.splice(0, buffer.length);
+    const body = buildOtlpTracesRequest(batch, { resourceAttributes, scopeName });
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+      const res = await fetchImpl(url, {
+        method: "POST",
+        headers,
+        body: JSON.stringify(body),
+        signal: controller.signal
+      });
+      if (!res.ok) {
+        const text = await res.text().catch(() => "");
+        onError(new Error(`OTLP traces push failed: ${res.status} ${res.statusText} ${text}`));
+      }
+    } catch (err) {
+      onError(err);
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+  const handle = setInterval(() => {
+    if (!stopped) void pushOnce();
+  }, intervalMs);
+  handle.unref?.();
+  return {
+    tracer,
+    flush: pushOnce,
+    async stop() {
+      stopped = true;
+      clearInterval(handle);
+      await pushOnce().catch(onError);
+    },
+    buffered: () => [...buffer]
+  };
 }
 
 // src/defaults/context-manager.ts
@@ -5216,18 +6868,370 @@ function createContextManagerTool(opts = {}) {
             summary: summaryText
           };
         }
-        default:
-          return {
-            action: input.action,
-            beforeTokens,
-            messageCount: messages.length,
-            notes: `Unknown action: ${input.action}`
-          };
+        default:
+          return {
+            action: input.action,
+            beforeTokens,
+            messageCount: messages.length,
+            notes: `Unknown action: ${input.action}`
+          };
+      }
+    }
+  };
+}
+var contextManagerTool = createContextManagerTool();
+
+// src/defaults/mcp-servers.ts
+var filesystemServer = () => ({
+  name: "filesystem",
+  description: "Read, write, and navigate the local filesystem (read-heavy tools)",
+  transport: "stdio",
+  command: "npx",
+  args: ["-y", "@modelcontextprotocol/server-filesystem", "."],
+  permission: "confirm"
+});
+var githubServer = () => ({
+  name: "github",
+  description: "GitHub API \u2014 issues, PRs, repos, search, file ops (requires GITHUB_PERSONAL_ACCESS_TOKEN)",
+  transport: "stdio",
+  command: "npx",
+  args: ["-y", "@modelcontextprotocol/server-github"],
+  env: { GITHUB_PERSONAL_ACCESS_TOKEN: process.env.GITHUB_PERSONAL_ACCESS_TOKEN ?? "" },
+  permission: "confirm"
+});
+var context7Server = () => ({
+  name: "context7",
+  description: "Codebase-aware documentation and Q&A (context7.ai)",
+  transport: "streamable-http",
+  url: "https://server.context7.ai/mcp",
+  permission: "confirm"
+});
+var braveSearchServer = () => ({
+  name: "brave-search",
+  description: "Web search (Brave). Requires BRAVE_SEARCH_API_KEY \u2014 free tier 2k queries/month",
+  transport: "stdio",
+  command: "npx",
+  args: ["-y", "@modelcontextprotocol/server-brave-search"],
+  env: { BRAVE_SEARCH_API_KEY: process.env.BRAVE_SEARCH_API_KEY ?? "" },
+  permission: "confirm"
+});
+var blockServer = () => ({
+  name: "block",
+  description: "Postgres database access via SQL (Block MCP server)",
+  transport: "stdio",
+  command: "npx",
+  args: ["-y", "@modelcontextprotocol/server-block"],
+  permission: "confirm"
+});
+var everArtServer = () => ({
+  name: "everart",
+  description: "AI image generation (EverArt). Requires EVERART_API_KEY",
+  transport: "stdio",
+  command: "npx",
+  args: ["-y", "@modelcontextprotocol/server-everart"],
+  env: { EVERART_API_KEY: process.env.EVERART_API_KEY ?? "" },
+  permission: "confirm"
+});
+var slackServer = () => ({
+  name: "slack",
+  description: "Slack \u2014 messaging, channels, search. Requires SLACK_BOT_TOKEN + SLACK_TEAM_ID",
+  transport: "stdio",
+  command: "npx",
+  args: ["-y", "@modelcontextprotocol/server-slack"],
+  env: {
+    SLACK_BOT_TOKEN: process.env.SLACK_BOT_TOKEN ?? "",
+    SLACK_TEAM_ID: process.env.SLACK_TEAM_ID ?? ""
+  },
+  permission: "confirm"
+});
+var awsServer = () => ({
+  name: "aws",
+  description: "AWS \u2014 EC2, S3, Lambda, IAM, CloudFormation, costs. Requires AWS credentials",
+  transport: "stdio",
+  command: "npx",
+  args: ["-y", "@modelcontextprotocol/server-aws"],
+  permission: "confirm"
+});
+var googleMapsServer = () => ({
+  name: "google-maps",
+  description: "Google Maps \u2014 directions, geocoding, places. Requires GOOGLE_MAPS_API_KEY",
+  transport: "stdio",
+  command: "npx",
+  args: ["-y", "@modelcontextprotocol/server-google-maps"],
+  env: { GOOGLE_MAPS_API_KEY: process.env.GOOGLE_MAPS_API_KEY ?? "" },
+  permission: "confirm"
+});
+var sentinelServer = () => ({
+  name: "sentinel",
+  description: "Security vulnerability scanning (Sentinel)",
+  transport: "streamable-http",
+  url: "https://mcp.sentinel.ai",
+  permission: "deny"
+  // security tool — require explicit confirmation
+});
+var allServers = () => ({
+  filesystem: { ...filesystemServer(), enabled: false },
+  github: { ...githubServer(), enabled: false },
+  context7: { ...context7Server(), enabled: false },
+  "brave-search": { ...braveSearchServer(), enabled: false },
+  block: { ...blockServer(), enabled: false },
+  everart: { ...everArtServer(), enabled: false },
+  slack: { ...slackServer(), enabled: false },
+  aws: { ...awsServer(), enabled: false },
+  "google-maps": { ...googleMapsServer(), enabled: false },
+  sentinel: { ...sentinelServer(), enabled: false }
+});
+
+// src/core/streaming-response-builder.ts
+function buildResponse(state) {
+  const content = [];
+  for (const b of state.blockOrder) {
+    if (b.kind === "text") {
+      const txt = state.textBuffers[b.idx] ?? "";
+      if (txt) content.push({ type: "text", text: txt });
+    } else {
+      const tb = state.tools.get(b.id);
+      if (tb) {
+        const block = {
+          type: "tool_use",
+          id: b.id,
+          name: tb.name,
+          input: tb.input ?? {}
+        };
+        if (tb.providerMeta && Object.keys(tb.providerMeta).length > 0) {
+          block.providerMeta = tb.providerMeta;
+        }
+        content.push(block);
+      }
+    }
+  }
+  if (content.length === 0) content.push({ type: "text", text: "" });
+  return { content, stopReason: state.stopReason, usage: state.usage, model: state.model };
+}
+function createStreamingState(model) {
+  return {
+    model,
+    stopReason: "end_turn",
+    usage: { input: 0, output: 0 },
+    textBuffers: [],
+    currentTextIndex: -1,
+    tools: /* @__PURE__ */ new Map(),
+    blockOrder: []
+  };
+}
+function handleMessageStart(state, model) {
+  state.model = model;
+}
+function handleContentBlockStart(state, ev) {
+  const kind = ev.kind ?? "text";
+  if (kind === "text") {
+    state.currentTextIndex = state.textBuffers.length;
+    state.textBuffers.push("");
+    state.blockOrder.push({ kind: "text", idx: state.currentTextIndex });
+  } else if (kind === "tool_use") {
+    const id = ev.id ?? crypto.randomUUID();
+    state.tools.set(id, { name: ev.name ?? "unknown", partial: "" });
+    state.blockOrder.push({ kind: "tool", id });
+    state.currentTextIndex = -1;
+  }
+}
+function handleContentBlockStop(state, ev) {
+}
+function handleTextDelta(state, text) {
+  if (state.currentTextIndex === -1) {
+    state.currentTextIndex = state.textBuffers.length;
+    state.textBuffers.push("");
+    state.blockOrder.push({ kind: "text", idx: state.currentTextIndex });
+  }
+  state.textBuffers[state.currentTextIndex] = (state.textBuffers[state.currentTextIndex] ?? "") + text;
+}
+function handleToolUseStart(state, ev) {
+  state.currentTextIndex = -1;
+  state.tools.set(ev.id, { name: ev.name, partial: "" });
+  state.blockOrder.push({ kind: "tool", id: ev.id });
+}
+function handleToolUseInputDelta(state, ev) {
+  const t2 = state.tools.get(ev.id);
+  if (t2) t2.partial += ev.partial;
+}
+function safeJsonOrRaw(s) {
+  if (!s) return {};
+  try {
+    return JSON.parse(s);
+  } catch {
+    return { _raw: s };
+  }
+}
+function handleToolUseStop(state, ev) {
+  const t2 = state.tools.get(ev.id);
+  if (t2) {
+    t2.input = ev.input !== void 0 ? ev.input : safeJsonOrRaw(t2.partial);
+    if (ev.providerMeta) t2.providerMeta = ev.providerMeta;
+  }
+  state.currentTextIndex = -1;
+}
+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) {
+  const state = createStreamingState(req.model);
+  const iter = provider.stream(req, { signal })[Symbol.asyncIterator]();
+  try {
+    for (; ; ) {
+      const next = await iter.next();
+      if (next.done) break;
+      const ev = next.value;
+      switch (ev.type) {
+        case "message_start":
+          handleMessageStart(state, ev.model);
+          break;
+        case "content_block_start":
+          handleContentBlockStart(state, ev);
+          break;
+        case "content_block_stop":
+          handleContentBlockStop(state, ev);
+          break;
+        case "text_delta":
+          handleTextDelta(state, ev.text);
+          events.emit("provider.text_delta", { ctx, text: ev.text });
+          break;
+        case "tool_use_start":
+          handleToolUseStart(state, ev);
+          events.emit("provider.tool_use_start", { ctx, id: ev.id, name: ev.name });
+          break;
+        case "tool_use_input_delta":
+          handleToolUseInputDelta(state, ev);
+          break;
+        case "tool_use_stop":
+          handleToolUseStop(state, ev);
+          events.emit("provider.tool_use_stop", { ctx, id: ev.id });
+          break;
+        case "message_stop":
+          handleMessageStop(state, ev);
+          break;
+      }
+    }
+  } catch (err) {
+    if (signal.aborted) {
+      state.stopReason = "max_tokens";
+      return buildResponse(state);
+    }
+    throw err;
+  } finally {
+    try {
+      await iter.return?.();
+    } catch {
+    }
+  }
+  return buildResponse(state);
+}
+
+// src/core/provider-runner.ts
+async function runProviderWithRetry(opts) {
+  const { provider, request, signal, ctx, events, retry, logger, tracer } = opts;
+  let attempt = 0;
+  for (; ; ) {
+    const span = tracer?.startSpan("provider.complete", {
+      "provider.id": provider.id,
+      "provider.model": request.model,
+      "provider.streaming": provider.capabilities.streaming,
+      "provider.attempt": attempt
+    });
+    try {
+      const res = provider.capabilities.streaming ? await streamProviderToResponse(provider, request, signal, ctx, events) : 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();
+      return res;
+    } catch (err) {
+      if (err instanceof Error) span?.recordError(err);
+      span?.end();
+      if (signal.aborted) throw err;
+      const isProviderErr = err instanceof ProviderError;
+      const errAsErr = err instanceof Error ? err : new Error(String(err));
+      const canRetry = retry.shouldRetry(isProviderErr ? err : errAsErr, attempt);
+      const description = isProviderErr ? err.describe() : errAsErr.message;
+      if (!canRetry) {
+        if (isProviderErr) {
+          events.emit("provider.error", {
+            providerId: err.providerId,
+            status: err.status,
+            description,
+            retryable: false
+          });
+        }
+        throw err;
+      }
+      const delay = Math.round(retry.delayMs(attempt));
+      const attemptNum = attempt + 1;
+      logger.warn(`Provider retry ${attemptNum} in ${delay}ms \u2014 ${description}`);
+      if (isProviderErr) {
+        events.emit("provider.retry", {
+          providerId: err.providerId,
+          attempt: attemptNum,
+          delayMs: delay,
+          status: err.status,
+          description
+        });
       }
+      await new Promise((resolve4, reject) => {
+        const t2 = setTimeout(resolve4, delay);
+        const onAbort = () => {
+          clearTimeout(t2);
+          reject(new Error("aborted"));
+        };
+        if (signal.aborted) onAbort();
+        signal.addEventListener("abort", onAbort, { once: true });
+      });
+      attempt++;
     }
-  };
+  }
+}
+
+// src/core/iteration-limit.ts
+function requestLimitExtension(opts) {
+  const { events, currentIterations, currentLimit, autoExtend, timeoutMs = 3e4 } = opts;
+  return new Promise((resolve4) => {
+    let resolved = false;
+    const timer = setTimeout(() => {
+      if (!resolved) {
+        resolved = true;
+        resolve4(0);
+      }
+    }, timeoutMs);
+    const deny = () => {
+      if (!resolved) {
+        resolved = true;
+        clearTimeout(timer);
+        resolve4(0);
+      }
+    };
+    const grant = (extra) => {
+      if (!resolved) {
+        resolved = true;
+        clearTimeout(timer);
+        resolve4(Math.max(0, extra));
+      }
+    };
+    events.emit("iteration.limit_reached", {
+      currentIterations,
+      currentLimit,
+      grant,
+      deny
+    });
+    if (autoExtend) {
+      setImmediate(() => {
+        if (!resolved) {
+          resolved = true;
+          clearTimeout(timer);
+          resolve4(100);
+        }
+      });
+    }
+  });
 }
-var contextManagerTool = createContextManagerTool();
 
 // src/core/agent.ts
 var DEFAULT_MAX_ITERATIONS = 100;
@@ -5262,6 +7266,7 @@ var Agent = class {
   plugins = [];
   toolExecutor;
   autoExtendLimit;
+  tracer;
   constructor(init) {
     this.container = init.container;
     this.tools = init.tools;
@@ -5274,13 +7279,16 @@ var Agent = class {
     this.executionStrategy = init.executionStrategy ?? "smart";
     this.perIterationOutputCapBytes = init.perIterationOutputCapBytes ?? 1e5;
     this.autoExtendLimit = init.autoExtendLimit ?? true;
+    this.tracer = init.tracer;
     this.toolExecutor = new ToolExecutor(this.tools, {
       permissionPolicy: this.permission,
       secretScrubber: this.scrubber,
       renderer: this.renderer,
       events: this.events,
+      confirmAwaiter: init.confirmAwaiter,
       iterationTimeoutMs: this.iterationTimeoutMs,
-      perIterationOutputCapBytes: this.perIterationOutputCapBytes
+      perIterationOutputCapBytes: this.perIterationOutputCapBytes,
+      tracer: this.tracer
     });
   }
   get logger() {
@@ -5316,334 +7324,190 @@ var Agent = class {
     const signal = controller.signal;
     this.ctx.signal = signal;
     controller.onAbort(() => this.ctx.drainAbortHooks());
+    const span = this.tracer?.startSpan("agent.run", {
+      "agent.model": opts.model ?? this.ctx.model,
+      "agent.executionStrategy": opts.executionStrategy ?? this.executionStrategy
+    });
     try {
-      return await this.runInner(userInput, opts, controller);
+      const result = await this.runInner(userInput, opts, controller);
+      span?.setAttribute("agent.status", result.status);
+      span?.setAttribute("agent.iterations", result.iterations);
+      return result;
+    } catch (err) {
+      const wse = err instanceof AgentError ? err : toWrongStackError(err);
+      this.events.emit("error", { err: toError(err), phase: "agent" });
+      if (err instanceof Error) span?.recordError(err);
+      span?.setAttribute("agent.status", "failed");
+      return {
+        status: signal.aborted ? "aborted" : "failed",
+        iterations: 0,
+        error: wse
+      };
     } finally {
+      span?.end();
       await controller.dispose();
     }
   }
   async runInner(userInput, opts, controller) {
-    const signal = controller.signal;
-    const { blocks, text } = normalizeInput(userInput);
-    await this.pipelines.userInput.run({ content: blocks, text, ctx: this.ctx });
-    this.ctx.messages.push({ role: "user", content: blocks });
-    await this.ctx.session.append({
-      type: "user_input",
-      ts: (/* @__PURE__ */ new Date()).toISOString(),
-      content: blocks
-    });
+    await this.normalizeAndEmitUserInput(userInput);
     let finalText = "";
     let iterations = 0;
-    let maxIter = opts.maxIterations ?? this.maxIterations;
-    const hasHardLimit = maxIter > 0 && Number.isFinite(maxIter);
+    let effectiveLimit = opts.maxIterations ?? this.maxIterations;
+    const hasHardLimit = effectiveLimit > 0 && Number.isFinite(effectiveLimit);
     for (let i = 0; ; i++) {
       iterations = i + 1;
-      if (signal.aborted) {
+      if (controller.signal.aborted) {
         return { status: "aborted", iterations };
       }
-      if (hasHardLimit && i >= maxIter) {
-        const extendBy = await this.requestLimitExtension(iterations);
-        if (extendBy > 0) {
-          maxIter += extendBy;
-          this.logger.info(`Iteration limit extended by ${extendBy} (new limit: ${maxIter})`);
-        } else {
-          return { status: "max_iterations", iterations, finalText };
-        }
+      const limitCheck = await this.checkIterationLimit(
+        i,
+        effectiveLimit,
+        hasHardLimit,
+        iterations
+      );
+      effectiveLimit = limitCheck.limit;
+      if (limitCheck.exit) {
+        return { ...limitCheck.exit, finalText };
       }
       this.events.emit("iteration.started", { ctx: this.ctx, index: i });
-      const baseReq = {
-        model: opts.model ?? this.ctx.model,
-        system: this.ctx.systemPrompt,
-        messages: this.ctx.messages,
-        tools: this.tools.list(),
-        maxTokens: 8192
-      };
-      const req = await this.pipelines.request.run(baseReq);
+      const req = await this.buildAndRunRequestPipeline(opts);
       let res;
       try {
-        res = await this.callProviderWithRetry(this.ctx.provider, req, signal);
+        res = await runProviderWithRetry({
+          provider: this.ctx.provider,
+          request: req,
+          signal: controller.signal,
+          ctx: this.ctx,
+          events: this.events,
+          retry: this.retry,
+          logger: this.logger,
+          tracer: this.tracer
+        });
       } catch (err) {
-        if (signal.aborted) {
+        if (controller.signal.aborted) {
           this.events.emit("error", { err: toError(err), phase: "provider" });
-          return { status: "aborted", iterations, error: err };
+          return { status: "aborted", iterations, error: toWrongStackError(err, "AGENT_ABORTED") };
         }
         const recovered = await this.errorHandler.recover(err, this.ctx);
         if (!recovered) {
           this.events.emit("error", { err: toError(err), phase: "provider" });
-          return { status: "failed", iterations, error: err };
+          return { status: "failed", iterations, error: toWrongStackError(err) };
         }
         res = recovered;
       }
-      res = await this.pipelines.response.run(res);
-      this.events.emit("provider.response", {
-        ctx: this.ctx,
-        usage: res.usage,
-        stopReason: res.stopReason
-      });
-      this.ctx.tokenCounter.account(res.usage, req.model);
-      this.ctx.messages.push({ role: "assistant", content: res.content });
-      await this.ctx.session.append({
-        type: "llm_response",
-        ts: (/* @__PURE__ */ new Date()).toISOString(),
-        content: res.content,
-        stopReason: res.stopReason,
-        usage: res.usage
-      });
-      if (signal.aborted) {
-        for (const block of res.content) {
-          if (isTextBlock(block)) finalText += block.text;
-        }
-        this.events.emit("iteration.completed", { ctx: this.ctx, index: i });
-        return { status: "aborted", iterations, finalText };
+      const responseResult = await this.processResponse(res, req);
+      if (responseResult.aborted) {
+        return { status: "aborted", iterations, finalText: responseResult.finalText };
       }
-      const streamed = this.ctx.provider.capabilities.streaming;
-      for (const block of res.content) {
-        if (isTextBlock(block)) {
-          const rendered = await this.pipelines.assistantOutput.run(block);
-          finalText += rendered.text;
-          if (!streamed) this.renderer?.write(rendered);
-        }
+      if (responseResult.done) {
+        return { status: "done", iterations, finalText: responseResult.finalText };
       }
+      finalText = responseResult.finalText;
       const toolUses = res.content.filter(isToolUseBlock);
-      if (toolUses.length === 0 || res.stopReason === "end_turn") {
+      if (toolUses.length === 0) {
         this.events.emit("iteration.completed", { ctx: this.ctx, index: i });
         return { status: "done", iterations, finalText };
       }
-      const results = await this.executeTools(toolUses, signal);
-      this.ctx.messages.push({ role: "user", content: results });
+      await this.executeTools(toolUses);
       this.events.emit("iteration.completed", { ctx: this.ctx, index: i });
-      if (this.compactor) {
-        await this.pipelines.contextWindow.run(this.ctx);
-      }
+      await this.compactContextIfNeeded();
     }
-    return { status: "max_iterations", iterations, finalText };
   }
   /**
-   * Emit an event asking listeners (CLI/TUI) whether to extend the iteration
-   * limit. Returns the number of additional iterations granted. If no listener
-   * responds or the user declines, returns 0.
+   * Normalize user input and emit through userInput pipeline + session append.
    */
-  async requestLimitExtension(currentIterations) {
-    return new Promise((resolve4) => {
-      let resolved = false;
-      const timer = setTimeout(() => {
-        if (!resolved) {
-          resolved = true;
-          resolve4(0);
-        }
-      }, 3e4);
-      const wrappedDeny = () => {
-        if (!resolved) {
-          resolved = true;
-          clearTimeout(timer);
-          resolve4(0);
-        }
-      };
-      const wrappedGrant = (extra) => {
-        if (!resolved) {
-          resolved = true;
-          clearTimeout(timer);
-          resolve4(Math.max(0, extra));
-        }
-      };
-      if (this.autoExtendLimit) {
-        this.events.emit("iteration.limit_reached", {
-          currentIterations,
-          currentLimit: this.maxIterations,
-          grant: wrappedGrant,
-          deny: wrappedDeny
-        });
-        setImmediate(() => {
-          if (!resolved) {
-            resolved = true;
-            clearTimeout(timer);
-            resolve4(100);
-          }
-        });
-      } else {
-        this.events.emit("iteration.limit_reached", {
-          currentIterations,
-          currentLimit: this.maxIterations,
-          grant: wrappedGrant,
-          deny: wrappedDeny
-        });
-      }
+  async normalizeAndEmitUserInput(userInput) {
+    const { blocks, text } = normalizeInput(userInput);
+    await this.pipelines.userInput.run({ content: blocks, text, ctx: this.ctx });
+    this.ctx.state.appendMessage({ role: "user", content: blocks });
+    await this.ctx.session.append({
+      type: "user_input",
+      ts: (/* @__PURE__ */ new Date()).toISOString(),
+      content: blocks
     });
   }
   /**
-   * Consume a Provider.stream() into a Response, emitting text_delta and
-   * tool_use lifecycle events to the EventBus as they arrive. This is the
-   * canonical path when the provider declares `capabilities.streaming`;
-   * complete() is only used as a fallback for legacy providers.
+   * Check if iteration limit has been reached and request extension if needed.
+   * Returns the new effective limit (possibly extended) and a RunResult if
+   * the loop should exit. Returns `{ limit }` with no result when the
+   * iteration may proceed.
    */
-  async streamProviderToResponse(provider, req, signal) {
-    let model = req.model;
-    let stopReason = "end_turn";
-    let usage = { input: 0, output: 0 };
-    const textBuffers = [];
-    let currentTextIndex = -1;
-    const tools = /* @__PURE__ */ new Map();
-    const blockOrder = [];
-    const openContentBlocks = /* @__PURE__ */ new Map();
-    const buildResponse = () => {
-      const content = [];
-      for (const b of blockOrder) {
-        if (b.kind === "text") {
-          const txt = textBuffers[b.idx] ?? "";
-          if (txt) content.push({ type: "text", text: txt });
-        } else {
-          const tb = tools.get(b.id);
-          if (tb) {
-            content.push({
-              type: "tool_use",
-              id: b.id,
-              name: tb.name,
-              input: tb.input ?? {}
-            });
-          }
-        }
+  async checkIterationLimit(iterationIndex, limit, hasHardLimit, currentIterations) {
+    if (hasHardLimit && iterationIndex >= limit) {
+      const extendBy = await requestLimitExtension({
+        events: this.events,
+        currentIterations,
+        currentLimit: this.maxIterations,
+        autoExtend: this.autoExtendLimit
+      });
+      if (extendBy > 0) {
+        const newLimit = limit + extendBy;
+        this.logger.info(`Iteration limit extended by ${extendBy} (new limit: ${newLimit})`);
+        return { limit: newLimit };
       }
-      if (content.length === 0) content.push({ type: "text", text: "" });
-      return { content, stopReason, usage, model };
+      return { limit, exit: { status: "max_iterations", iterations: currentIterations } };
+    }
+    return { limit };
+  }
+  /**
+   * Build request and run through request pipeline.
+   */
+  async buildAndRunRequestPipeline(opts) {
+    const baseReq = {
+      model: opts.model ?? this.ctx.model,
+      system: this.ctx.systemPrompt,
+      messages: this.ctx.messages,
+      tools: this.tools.list(),
+      maxTokens: 8192
     };
-    const iter = provider.stream(req, { signal })[Symbol.asyncIterator]();
-    try {
-      for (; ; ) {
-        const next = await iter.next();
-        if (next.done) break;
-        const ev = next.value;
-        switch (ev.type) {
-          case "message_start":
-            model = ev.model;
-            break;
-          case "content_block_start": {
-            const kind = ev.kind ?? "text";
-            if (kind === "text") {
-              currentTextIndex = textBuffers.length;
-              textBuffers.push("");
-              blockOrder.push({ kind: "text", idx: currentTextIndex });
-              openContentBlocks.set(String(currentTextIndex), "text");
-            } else if (kind === "tool_use") {
-              const id = ev.id ?? crypto.randomUUID();
-              tools.set(id, { name: ev.name ?? "unknown", partial: "" });
-              blockOrder.push({ kind: "tool", id });
-              openContentBlocks.set(String(blockOrder.length - 1), "tool");
-            }
-            break;
-          }
-          case "content_block_stop": {
-            const blockIndex = ev.index;
-            if (blockIndex !== void 0) {
-              openContentBlocks.delete(String(blockIndex));
-            }
-            break;
-          }
-          case "text_delta":
-            if (currentTextIndex === -1) {
-              currentTextIndex = textBuffers.length;
-              textBuffers.push("");
-              blockOrder.push({ kind: "text", idx: currentTextIndex });
-            }
-            textBuffers[currentTextIndex] = (textBuffers[currentTextIndex] ?? "") + ev.text;
-            this.events.emit("provider.text_delta", { ctx: this.ctx, text: ev.text });
-            break;
-          case "tool_use_start":
-            currentTextIndex = -1;
-            tools.set(ev.id, { name: ev.name, partial: "" });
-            blockOrder.push({ kind: "tool", id: ev.id });
-            this.events.emit("provider.tool_use_start", {
-              ctx: this.ctx,
-              id: ev.id,
-              name: ev.name
-            });
-            break;
-          case "tool_use_input_delta": {
-            const t2 = tools.get(ev.id);
-            if (t2) t2.partial += ev.partial;
-            break;
-          }
-          case "tool_use_stop": {
-            const t2 = tools.get(ev.id);
-            if (t2) {
-              t2.input = ev.input !== void 0 ? ev.input : safeJsonOrRaw(t2.partial);
-            }
-            currentTextIndex = -1;
-            this.events.emit("provider.tool_use_stop", { ctx: this.ctx, id: ev.id });
-            break;
-          }
-          case "message_stop":
-            stopReason = ev.stopReason;
-            usage = ev.usage;
-            break;
-        }
-      }
-    } catch (err) {
-      if (signal.aborted) {
-        stopReason = "max_tokens";
-        return buildResponse();
-      }
-      throw err;
-    } finally {
-      try {
-        await iter.return?.();
-      } catch {
+    return this.pipelines.request.run(baseReq);
+  }
+  /**
+   * Process the provider response: run response pipeline, emit events,
+   * update session, render text, handle abort.
+   */
+  async processResponse(res, req) {
+    await this.pipelines.response.run(res);
+    this.events.emit("provider.response", {
+      ctx: this.ctx,
+      usage: res.usage,
+      stopReason: res.stopReason
+    });
+    this.ctx.tokenCounter.account(res.usage, req.model);
+    this.ctx.state.appendMessage({ role: "assistant", content: res.content });
+    await this.ctx.session.append({
+      type: "llm_response",
+      ts: (/* @__PURE__ */ new Date()).toISOString(),
+      content: res.content,
+      stopReason: res.stopReason,
+      usage: res.usage
+    });
+    if (this.ctx.signal.aborted) {
+      let finalText2 = "";
+      for (const block of res.content) {
+        if (isTextBlock(block)) finalText2 += block.text;
       }
+      return { finalText: finalText2, aborted: true, done: false };
     }
-    return buildResponse();
-  }
-  async callProviderWithRetry(provider, req, signal) {
-    let attempt = 0;
-    for (; ; ) {
-      try {
-        if (provider.capabilities.streaming) {
-          return await this.streamProviderToResponse(provider, req, signal);
-        }
-        return await provider.complete(req, { signal });
-      } catch (err) {
-        if (signal.aborted) throw err;
-        const isProviderErr = err instanceof ProviderError;
-        const errAsErr = err instanceof Error ? err : new Error(String(err));
-        const canRetry = this.retry.shouldRetry(isProviderErr ? err : errAsErr, attempt);
-        const description = isProviderErr ? err.describe() : errAsErr.message;
-        if (!canRetry) {
-          if (isProviderErr) {
-            this.events.emit("provider.error", {
-              providerId: err.providerId,
-              status: err.status,
-              description,
-              retryable: false
-            });
-          }
-          throw err;
-        }
-        const delay = Math.round(this.retry.delayMs(attempt));
-        const attemptNum = attempt + 1;
-        this.logger.warn(
-          `Provider retry ${attemptNum} in ${delay}ms \u2014 ${description}`
-        );
-        if (isProviderErr) {
-          this.events.emit("provider.retry", {
-            providerId: err.providerId,
-            attempt: attemptNum,
-            delayMs: delay,
-            status: err.status,
-            description
-          });
-        }
-        await new Promise((resolve4, reject) => {
-          const t2 = setTimeout(resolve4, delay);
-          const onAbort = () => {
-            clearTimeout(t2);
-            reject(new Error("aborted"));
-          };
-          if (signal.aborted) onAbort();
-          signal.addEventListener("abort", onAbort, { once: true });
-        });
-        attempt++;
+    let finalText = "";
+    const streamed = this.ctx.provider.capabilities.streaming;
+    for (const block of res.content) {
+      if (isTextBlock(block)) {
+        const rendered = await this.pipelines.assistantOutput.run(block);
+        finalText += rendered.text;
+        if (!streamed) this.renderer?.write(rendered);
       }
     }
+    return { finalText, aborted: false, done: false };
   }
-  async executeTools(toolUses, signal) {
+  /**
+   * Execute tools and append tool results to context.
+   * When a tool returns `tool_confirm_pending` (no confirmAwaiter set),
+   * we pause and emit `tool.confirm_needed`. The run is blocked until
+   * the event listener resolves the confirmation, then we re-run the
+   * single tool.
+   */
+  async executeTools(toolUses) {
     const { outputs } = await this.toolExecutor.executeBatch(
       toolUses,
       this.ctx,
@@ -5651,6 +7515,39 @@ var Agent = class {
     );
     const useById = new Map(toolUses.map((u) => [u.id, u]));
     for (const { result, tool, durationMs } of outputs) {
+      if (result.type === "tool_confirm_pending") {
+        const decision = await this.waitForConfirm({
+          tool,
+          input: result.input,
+          toolUseId: result.toolUseId,
+          suggestedPattern: result.suggestedPattern
+        });
+        const reRunResult = await this.executeSingleWithDecision(
+          tool,
+          { id: result.toolUseId, name: tool.name, input: result.input },
+          decision
+        );
+        const use2 = useById.get(reRunResult.result.tool_use_id);
+        if (use2) {
+          await this.pipelines.toolCall.run({ toolUse: use2, result: reRunResult.result, ctx: this.ctx, tool });
+          await this.ctx.session.append({
+            type: "tool_result",
+            ts: (/* @__PURE__ */ new Date()).toISOString(),
+            id: reRunResult.result.tool_use_id,
+            content: reRunResult.result.content,
+            isError: !!reRunResult.result.is_error
+          });
+          this.events.emit("tool.executed", {
+            name: tool.name,
+            durationMs: reRunResult.durationMs,
+            ok: !reRunResult.result.is_error,
+            input: result.input,
+            output: truncateForEvent(reRunResult.result.content)
+          });
+        }
+        this.ctx.state.appendMessage({ role: "user", content: [reRunResult.result] });
+        continue;
+      }
       const use = useById.get(result.tool_use_id);
       if (!use) continue;
       await this.pipelines.toolCall.run({
@@ -5674,25 +7571,132 @@ var Agent = class {
         output: truncateForEvent(result.content)
       });
     }
-    return outputs.map((o) => o.result);
+    this.ctx.state.appendMessage({ role: "user", content: outputs.map((o) => o.result) });
+  }
+  waitForConfirm(info) {
+    return new Promise((resolve4) => {
+      this.events.emit("tool.confirm_needed", {
+        tool: info.tool,
+        input: info.input,
+        toolUseId: info.toolUseId,
+        suggestedPattern: info.suggestedPattern,
+        resolve: resolve4
+      });
+    });
+  }
+  async executeSingleWithDecision(tool, use, decision) {
+    const start = Date.now();
+    if (decision === "no" || decision === "deny") {
+      return {
+        result: { type: "tool_result", tool_use_id: use.id, content: `Tool "${tool.name}" denied by user.`, is_error: true },
+        durationMs: Date.now() - start
+      };
+    }
+    try {
+      const result = await this.toolExecutor.executeTool(tool, use, this.ctx, this.perIterationOutputCapBytes);
+      return { result, durationMs: Date.now() - start };
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      return {
+        result: { type: "tool_result", tool_use_id: use.id, content: `Tool "${tool.name}" threw: ${msg}`, is_error: true },
+        durationMs: Date.now() - start
+      };
+    }
+  }
+  /**
+   * Run context window pipeline if compactor is present.
+   */
+  async compactContextIfNeeded() {
+    if (this.compactor) {
+      await this.pipelines.contextWindow.run(this.ctx);
+    }
   }
 };
 function toError(err) {
   return err instanceof Error ? err : new Error(String(err));
 }
-function safeJsonOrRaw(s) {
-  if (!s) return {};
-  try {
-    return JSON.parse(s);
-  } catch {
-    return { _raw: s };
-  }
-}
 function truncateForEvent(content, max = 400) {
   if (!content) return "";
   return content.length <= max ? content : `${content.slice(0, max - 1)}\u2026`;
 }
 
+// src/core/conversation-state.ts
+var ConversationState = class {
+  ctx;
+  listeners = /* @__PURE__ */ new Set();
+  constructor(ctx) {
+    this.ctx = ctx;
+  }
+  // ─── Read API ───────────────────────────────────────────────────────
+  get messages() {
+    return this.ctx.messages;
+  }
+  get todos() {
+    return this.ctx.todos;
+  }
+  get meta() {
+    return this.ctx.meta;
+  }
+  /**
+   * Cheap immutable snapshot. Useful for tests and for compaction passes
+   * that need a stable view across an async boundary.
+   */
+  snapshot() {
+    return {
+      messages: [...this.ctx.messages],
+      todos: [...this.ctx.todos],
+      meta: { ...this.ctx.meta }
+    };
+  }
+  // ─── Write API (preferred — fires onChange) ─────────────────────────
+  appendMessage(message) {
+    this.ctx.messages.push(message);
+    this.emit({ kind: "message_appended", message });
+  }
+  replaceMessages(messages) {
+    this.ctx.messages.length = 0;
+    this.ctx.messages.push(...messages);
+    this.emit({ kind: "messages_replaced", messages: [...messages] });
+  }
+  replaceTodos(todos) {
+    this.ctx.todos.length = 0;
+    this.ctx.todos.push(...todos);
+    this.emit({ kind: "todos_replaced", todos: [...todos] });
+  }
+  setMeta(key, value) {
+    this.ctx.meta[key] = value;
+    this.emit({ kind: "meta_set", key, value });
+  }
+  deleteMeta(key) {
+    if (!(key in this.ctx.meta)) return;
+    delete this.ctx.meta[key];
+    this.emit({ kind: "meta_deleted", key });
+  }
+  // ─── Subscription ───────────────────────────────────────────────────
+  /**
+   * Subscribe to mutations that go through this wrapper. Note: mutations
+   * that bypass the wrapper (e.g. `ctx.messages.push(...)` directly) are
+   * NOT observed — by design during migration, since we don't want to
+   * monkey-patch arrays. Migrating call sites to use this API is the
+   * dev-plan #1 work.
+   */
+  onChange(listener) {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  }
+  emit(change) {
+    for (const h of this.listeners) {
+      try {
+        h(change, this);
+      } catch {
+      }
+    }
+  }
+};
+function wrapAsState(ctx) {
+  return new ConversationState(ctx);
+}
+
 // src/core/context.ts
 var Context = class {
   messages = [];
@@ -5720,11 +7724,29 @@ var Context = class {
     this.model = init.model;
     this.tools = init.tools ?? [];
   }
+  /**
+   * Observable wrapper over the mutable conversation state. Lazy so
+   * subsystems that don't subscribe pay nothing. Mutations made directly
+   * on `ctx.messages` / `ctx.todos` are still visible through this
+   * wrapper's read API (it holds a reference, not a copy) but only
+   * mutations that go through `state.appendMessage()` etc. fire
+   * `onChange`. New code should prefer the wrapper API.
+   */
+  _state = null;
+  get state() {
+    if (!this._state) this._state = new ConversationState(this);
+    return this._state;
+  }
   /**
    * Register a teardown hook tied to the current run's abort signal. The
    * hook fires when the run aborts OR ends normally — Agent.run wires
    * this through a RunController. When no run is active the hook fires
    * immediately so callers don't leak resources.
+   *
+   * **Scope:** these hooks fire on the **whole agent run's** abort, not on
+   * an individual tool call. For per-tool teardown of resources owned by
+   * the tool author (child processes, handles), prefer `Tool.cleanup` —
+   * see its JSDoc for the full rule.
    */
   abortHooks = /* @__PURE__ */ new Set();
   registerAbortHook(fn) {
@@ -5756,6 +7778,21 @@ var Context = class {
   }
 };
 
+// src/core/run-env.ts
+function extractRunEnv(ctx) {
+  return Object.freeze({
+    provider: ctx.provider,
+    session: ctx.session,
+    signal: ctx.signal,
+    tokenCounter: ctx.tokenCounter,
+    cwd: ctx.cwd,
+    projectRoot: ctx.projectRoot,
+    model: ctx.model,
+    systemPrompt: ctx.systemPrompt,
+    tools: ctx.tools
+  });
+}
+
 // src/core/input-builder.ts
 var InputBuilder = class {
   store;
@@ -6061,10 +8098,25 @@ var ToolRegistry = class {
   tools = /* @__PURE__ */ new Map();
   register(tool, owner = "core") {
     if (this.tools.has(tool.name)) {
-      throw new Error(`Tool "${tool.name}" already registered`);
+      throw new WrongStackError({
+        message: `Tool "${tool.name}" already registered`,
+        code: "REGISTRY_DUPLICATE",
+        subsystem: "container",
+        context: { tool: tool.name }
+      });
     }
     this.tools.set(tool.name, { tool, owner });
   }
+  /**
+   * Attempt to register a tool. Returns true if successful, false if a tool
+   * with the same name is already registered. Useful in multi-agent or plugin
+   * scenarios where duplicate registration may be intentional.
+   */
+  tryRegister(tool, owner = "core") {
+    if (this.tools.has(tool.name)) return false;
+    this.tools.set(tool.name, { tool, owner });
+    return true;
+  }
   /**
    * Register a tool as a default. If the tool name is already registered,
    * this is a no-op — the existing registration (from core or another
@@ -6083,7 +8135,12 @@ var ToolRegistry = class {
    */
   override(name, tool, owner = "core") {
     if (!this.tools.has(name)) {
-      throw new Error(`Tool "${name}" not registered; cannot override`);
+      throw new WrongStackError({
+        message: `Tool "${name}" not registered; cannot override`,
+        code: "REGISTRY_NOT_FOUND",
+        subsystem: "container",
+        context: { tool: name }
+      });
     }
     this.tools.set(name, { tool, owner });
   }
@@ -6107,9 +8164,25 @@ var ToolRegistry = class {
 // src/registry/provider-registry.ts
 var ProviderRegistry = class {
   factories = /* @__PURE__ */ new Map();
+  /**
+   * Register a provider factory. If a factory with the same type already
+   * exists, it is replaced. Use this for both initial registration and
+   * runtime overrides (e.g. from plugins or CLI flags).
+   */
   register(f) {
     this.factories.set(f.type, f);
   }
+  /**
+   * Override an existing factory. Throws if no factory is registered
+   * for the given type. Use this to safely replace a provider at runtime
+   * (e.g. in tests or when a plugin provides a custom implementation).
+   */
+  override(type, f) {
+    if (!this.factories.has(type)) {
+      throw new Error(`Provider type "${type}" not registered; cannot override`);
+    }
+    this.factories.set(type, f);
+  }
   has(type) {
     return this.factories.has(type);
   }
@@ -6319,20 +8392,23 @@ function parseSemver(v) {
   const parts = v.replace(/^[^0-9]*/, "").split(".").map((s) => Number.parseInt(s, 10) || 0);
   return [parts[0] ?? 0, parts[1] ?? 0, parts[2] ?? 0];
 }
-function satisfies(range, kernelVersion) {
-  const [kMaj, kMin, kPatch] = parseSemver(kernelVersion);
+function satisfies(range, version) {
+  const [vMaj, vMin, vPatch] = parseSemver(version);
   const trimmed = range.trim();
   const op = trimmed.startsWith("^") ? "^" : trimmed.startsWith("~") ? "~" : "=";
   const ver = trimmed.replace(/^[\^~=]/, "");
   const [rMaj, rMin, rPatch] = parseSemver(ver);
   if (op === "^") {
-    if (rMaj === 0) return kMaj === 0 && kMin === rMin && kPatch >= rPatch;
-    return kMaj === rMaj && (kMin > rMin || kMin === rMin && kPatch >= rPatch);
+    if (rMaj === 0) return vMaj === 0 && vMin === rMin && vPatch >= rPatch;
+    return vMaj === rMaj && (vMin > rMin || vMin === rMin && vPatch >= rPatch);
   }
   if (op === "~") {
-    return kMaj === rMaj && kMin === rMin && kPatch >= rPatch;
+    return vMaj === rMaj && vMin === rMin && vPatch >= rPatch;
   }
-  return kMaj === rMaj && kMin === rMin && kPatch === rPatch;
+  return vMaj === rMaj && vMin === rMin && vPatch === rPatch;
+}
+function normalizeDep(d) {
+  return typeof d === "string" ? { name: d } : d;
 }
 function topoSort(plugins) {
   const map = /* @__PURE__ */ new Map();
@@ -6343,19 +8419,48 @@ function topoSort(plugins) {
   const visit = (p, stack) => {
     if (visited.has(p.name)) return;
     if (visiting.has(p.name)) {
-      throw new Error(`Plugin dependency cycle: ${[...stack, p.name].join(" -> ")}`);
+      throw new PluginError({
+        message: `Plugin dependency cycle: ${[...stack, p.name].join(" -> ")}`,
+        code: "PLUGIN_LOAD_FAILED",
+        pluginName: p.name
+      });
     }
     visiting.add(p.name);
-    for (const dep of p.dependsOn ?? []) {
-      const d = map.get(dep);
+    for (const raw of p.dependsOn ?? []) {
+      const dep = normalizeDep(raw);
+      const d = map.get(dep.name);
       if (!d) {
-        throw new Error(`Plugin "${p.name}" depends on missing plugin "${dep}"`);
+        throw new PluginError({
+          message: `Plugin "${p.name}" depends on missing plugin "${dep.name}"`,
+          code: "PLUGIN_MISSING_DEPENDENCY",
+          pluginName: p.name,
+          context: { dependency: dep.name }
+        });
+      }
+      if (dep.version && d.version && !satisfies(dep.version, d.version)) {
+        throw new PluginError({
+          message: `Plugin "${p.name}" requires "${dep.name}@${dep.version}", found ${d.version}`,
+          code: "PLUGIN_LOAD_FAILED",
+          pluginName: p.name,
+          context: { dependency: dep.name, required: dep.version, found: d.version }
+        });
       }
       visit(d, [...stack, p.name]);
     }
-    for (const dep of p.optionalDeps ?? []) {
-      const d = map.get(dep);
-      if (d) visit(d, [...stack, p.name]);
+    for (const raw of p.optionalDeps ?? []) {
+      const dep = normalizeDep(raw);
+      const d = map.get(dep.name);
+      if (d) {
+        if (dep.version && d.version && !satisfies(dep.version, d.version)) {
+          throw new PluginError({
+            message: `Plugin "${p.name}" optional dep "${dep.name}@${dep.version}" found ${d.version}`,
+            code: "PLUGIN_LOAD_FAILED",
+            pluginName: p.name,
+            context: { dependency: dep.name, required: dep.version, found: d.version }
+          });
+        }
+        visit(d, [...stack, p.name]);
+      }
     }
     visiting.delete(p.name);
     visited.add(p.name);
@@ -6372,7 +8477,12 @@ async function loadPlugins(plugins, opts) {
   for (const p of plugins) {
     for (const c of p.conflictsWith ?? []) {
       if (names.has(c)) {
-        throw new Error(`Plugin "${p.name}" conflicts with loaded plugin "${c}"`);
+        throw new PluginError({
+          message: `Plugin "${p.name}" conflicts with loaded plugin "${c}"`,
+          code: "PLUGIN_LOAD_FAILED",
+          pluginName: p.name,
+          context: { conflictsWith: c }
+        });
       }
     }
   }
@@ -6385,15 +8495,38 @@ async function loadPlugins(plugins, opts) {
   }
   for (const plugin of sorted) {
     if (!satisfies(plugin.apiVersion, kernelVersion)) {
-      const err = new Error(
-        `Plugin "${plugin.name}" requires apiVersion ${plugin.apiVersion}; kernel is ${kernelVersion}`
-      );
+      const err = new PluginError({
+        message: `Plugin "${plugin.name}" requires apiVersion ${plugin.apiVersion}; kernel is ${kernelVersion}`,
+        code: "PLUGIN_API_MISMATCH",
+        pluginName: plugin.name,
+        context: { required: plugin.apiVersion, kernel: kernelVersion }
+      });
       opts.log.error(err.message);
       failed.push({ plugin, err });
       continue;
     }
+    if (plugin.configSchema && opts.pluginOptions) {
+      const pluginOpts = opts.pluginOptions[plugin.name];
+      if (pluginOpts !== void 0) {
+        const result = validateAgainstSchema(pluginOpts, plugin.configSchema);
+        if (!result.ok) {
+          const firstErr = result.errors[0];
+          const detail = firstErr ? `${firstErr.path}: ${firstErr.message}` : "config invalid";
+          const err = new PluginError({
+            message: `Plugin "${plugin.name}" config invalid \u2014 ${detail}`,
+            code: "PLUGIN_LOAD_FAILED",
+            pluginName: plugin.name,
+            context: { errors: result.errors }
+          });
+          opts.log.error(err.message);
+          failed.push({ plugin, err });
+          continue;
+        }
+      }
+    }
     try {
-      const api = opts.apiFactory(plugin);
+      const rawApi = opts.apiFactory(plugin);
+      const api = plugin.capabilities ? wrapApiForCapabilityCheck(plugin, rawApi, opts.log) : rawApi;
       await plugin.setup(api);
       loaded.push(plugin);
       opts.log.info(`Plugin "${plugin.name}" loaded`);
@@ -6404,7 +8537,88 @@ async function loadPlugins(plugins, opts) {
   }
   return { loaded, failed };
 }
+async function unloadPlugins(loadedPlugins, opts) {
+  const ordered = [...loadedPlugins].reverse();
+  for (const plugin of ordered) {
+    if (typeof plugin.teardown !== "function") continue;
+    try {
+      const api = opts.apiFactory(plugin);
+      await plugin.teardown(api);
+      opts.log.info(`Plugin "${plugin.name}" torn down`);
+    } catch (err) {
+      opts.log.error(`Plugin "${plugin.name}" teardown failed`, err);
+    }
+  }
+}
+function wrapApiForCapabilityCheck(plugin, api, log) {
+  const caps = plugin.capabilities ?? {};
+  const warn = (subsystem, detail) => {
+    const msg = `Plugin "${plugin.name}" used ${subsystem} without declaring capabilities.${subsystem} \u2014 ${detail}`;
+    if (typeof log.warn === "function") log.warn(msg);
+    else log.error(msg);
+  };
+  const wrappedTools = caps.tools !== false ? api.tools : new Proxy(api.tools, {
+    get(target, prop, receiver) {
+      if (prop === "register") {
+        return (t2) => {
+          warn("tools", `register(${t2?.name ?? "<unknown>"})`);
+          return target.register(t2);
+        };
+      }
+      return Reflect.get(target, prop, receiver);
+    }
+  });
+  const wrappedProviders = caps.providers !== false ? api.providers : new Proxy(api.providers, {
+    get(target, prop, receiver) {
+      if (prop === "register") {
+        return (f) => {
+          warn("providers", `register(${f?.type ?? "<unknown>"})`);
+          return target.register(f);
+        };
+      }
+      return Reflect.get(target, prop, receiver);
+    }
+  });
+  const wrappedSlash = caps.slashCommands !== false ? api.slashCommands : new Proxy(api.slashCommands, {
+    get(target, prop, receiver) {
+      if (prop === "register") {
+        return (c) => {
+          warn("slashCommands", `register(${c?.name ?? "<unknown>"})`);
+          return target.register(c);
+        };
+      }
+      return Reflect.get(target, prop, receiver);
+    }
+  });
+  const wrappedMcp = caps.mcp !== false ? api.mcp : new Proxy(api.mcp, {
+    get(target, prop, receiver) {
+      if (prop === "start") {
+        return (cfg) => {
+          warn("mcp", `start(${cfg?.name ?? "<unknown>"})`);
+          return target.start(cfg);
+        };
+      }
+      return Reflect.get(target, prop, receiver);
+    }
+  });
+  return new Proxy(api, {
+    get(target, prop, receiver) {
+      switch (prop) {
+        case "tools":
+          return wrappedTools;
+        case "providers":
+          return wrappedProviders;
+        case "slashCommands":
+          return wrappedSlash;
+        case "mcp":
+          return wrappedMcp;
+        default:
+          return Reflect.get(target, prop, receiver);
+      }
+    }
+  });
+}
 
-export { Agent, AutoCompactionMiddleware, AutonomousRunner, Container, Context, DEFAULT_MAX_ITERATIONS, DEFAULT_MODES, DEFAULT_SPEC_TEMPLATE, DefaultAttachmentStore, DefaultConfigLoader, DefaultErrorHandler, DefaultLogger, DefaultMemoryStore, DefaultModeStore, DefaultModelsRegistry, DefaultMultiAgentCoordinator, DefaultPathResolver, DefaultPermissionPolicy, DefaultPluginAPI, DefaultRetryPolicy, DefaultSecretScrubber, DefaultSecretVault, DefaultSessionStore, DefaultSkillLoader, DefaultSystemPromptBuilder, DefaultTaskStore, DefaultTokenCounter, DoneConditionChecker, ENCRYPTED_PREFIX, EventBus, HybridCompactor, InMemoryAgentBridge, InMemoryBridgeTransport, InputBuilder, IntelligentCompactor, KERNEL_API_VERSION, LAYER_1_IDENTITY, LLMSelector, Pipeline, ProviderError, ProviderRegistry, QueueStore, RecoveryLock, RunController, SelectiveCompactor, SlashCommandRegistry, SpecDrivenDev, SpecParser, TOKENS, TaskFlow, TaskGenerator, TaskTracker, ToolExecutor, ToolRegistry, asBlocks, asText, atomicWrite, classifyFamily, color, compileGlob, computeTaskProgress, contextManagerTool, createContextManagerTool, createDefaultPipelines, createMessage, createToolOutputSerializer, decryptConfigSecrets, detectNewlineStyle, encryptConfigSecrets, ensureDir, findCriticalPath, isImageBlock, isTextBlock, isToolResultBlock, isToolUseBlock, loadPlugins, loadProjectModes, loadUserModes, matchAny, matchGlob, migratePlaintextSecrets, normalizeToLf, projectHash, resolveWstackPaths, rewriteConfigEncrypted, safeParse, safeStringify, sanitizeJsonString, stripAnsi, toStyle, topologicalSort, unifiedDiff };
+export { Agent, AgentError, AutoCompactionMiddleware, AutonomousRunner, BudgetExceededError, ConfigError, ConfigMigrationError, Container, Context, ConversationState, DEFAULT_CONFIG_MIGRATIONS, DEFAULT_MAX_ITERATIONS, DEFAULT_MODES, DEFAULT_SPEC_TEMPLATE, DefaultAttachmentStore, DefaultConfigLoader, DefaultConfigStore, DefaultErrorHandler, DefaultHealthRegistry, DefaultLogger, DefaultMemoryStore, DefaultModeStore, DefaultModelsRegistry, DefaultMultiAgentCoordinator, DefaultPathResolver, DefaultPermissionPolicy, DefaultPluginAPI, DefaultRetryPolicy, DefaultSecretScrubber, DefaultSecretVault, DefaultSessionReader, DefaultSessionStore, DefaultSkillLoader, DefaultSystemPromptBuilder, DefaultTaskStore, DefaultTokenCounter, DoneConditionChecker, ENCRYPTED_PREFIX, EventBus, HybridCompactor, InMemoryAgentBridge, InMemoryBridgeTransport, InMemoryMetricsSink, InputBuilder, IntelligentCompactor, KERNEL_API_VERSION, LAYER_1_IDENTITY, LLMSelector, NoopMetricsSink, NoopTracer, OTelTracer, PROMETHEUS_CONTENT_TYPE, Pipeline, PluginError, ProviderError, ProviderRegistry, QueueStore, RecoveryLock, RunController, SelectiveCompactor, SessionError, SlashCommandRegistry, SpecDrivenDev, SpecParser, SubagentBudget, TOKENS, TaskFlow, TaskGenerator, TaskTracker, ToolError, ToolExecutor, ToolRegistry, WrongStackError, allServers, asBlocks, asText, atomicWrite, awsServer, blockServer, braveSearchServer, buildOtlpMetricsRequest, buildOtlpTracesRequest, classifyFamily, color, compileGlob, computeTaskProgress, context7Server, contextManagerTool, createContextManagerTool, createDefaultPipelines, createMessage, createToolOutputSerializer, decryptConfigSecrets, detectNewlineStyle, encryptConfigSecrets, ensureDir, estimateTextTokens, estimateToolInputTokens, estimateToolResultTokens, everArtServer, extractRunEnv, filesystemServer, findCriticalPath, githubServer, googleMapsServer, isAgentError, isConfigError, isImageBlock, isPluginError, isSessionError, isTextBlock, isToolError, isToolResultBlock, isToolUseBlock, isWrongStackError, loadPlugins, loadProjectModes, loadUserModes, makeAgentSubagentRunner, matchAny, matchGlob, migratePlaintextSecrets, normalizeToLf, projectHash, renderPrometheus, resolveWstackPaths, rewriteConfigEncrypted, runConfigMigrations, safeParse, safeStringify, sanitizeJsonString, sentinelServer, slackServer, startMetricsServer, startOtlpMetricsExporter, startOtlpTraceExporter, stripAnsi, toStyle, toWrongStackError, topologicalSort, unifiedDiff, unloadPlugins, validateAgainstSchema, wireMetricsToEvents, wrapAsState };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map