@rk0429/agentic-relay 1.1.1 → 1.3.0

package/dist/relay.mjs

@@ -46,6 +46,120 @@ var init_logger = __esm({
   }
 });
 
+// src/core/metadata-validation.ts
+function isPlainObject(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return false;
+  }
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+function utf8Size(value) {
+  return new TextEncoder().encode(value).length;
+}
+function validateMetadataKey(key) {
+  if (DANGEROUS_METADATA_KEYS.has(key)) {
+    throw new Error(`metadata key "${key}" is not allowed`);
+  }
+  if (key.length > MAX_METADATA_KEY_LENGTH) {
+    throw new Error(
+      `metadata key "${key}" exceeds ${MAX_METADATA_KEY_LENGTH} chars`
+    );
+  }
+}
+function validateMetadataValue(value, path2, depth) {
+  if (depth > MAX_METADATA_NESTING_DEPTH) {
+    throw new Error(
+      `metadata nesting depth exceeds ${MAX_METADATA_NESTING_DEPTH} at "${path2}"`
+    );
+  }
+  if (typeof value === "string") {
+    if (value.length > MAX_METADATA_STRING_VALUE_LENGTH) {
+      throw new Error(
+        `metadata string at "${path2}" exceeds ${MAX_METADATA_STRING_VALUE_LENGTH} chars`
+      );
+    }
+    return;
+  }
+  if (value === null || value === void 0 || typeof value === "number" || typeof value === "boolean") {
+    return;
+  }
+  if (Array.isArray(value)) {
+    for (let index = 0; index < value.length; index += 1) {
+      validateMetadataValue(value[index], `${path2}[${index}]`, depth + 1);
+    }
+    return;
+  }
+  if (typeof value === "object") {
+    if (!isPlainObject(value)) {
+      throw new Error(`metadata value at "${path2}" must be a plain object`);
+    }
+    for (const [key, nestedValue] of Object.entries(value)) {
+      validateMetadataKey(key);
+      validateMetadataValue(nestedValue, `${path2}.${key}`, depth + 1);
+    }
+    return;
+  }
+  throw new Error(`metadata value at "${path2}" has unsupported type`);
+}
+function validateMetadata(raw) {
+  if (raw === void 0 || raw === null) {
+    return {};
+  }
+  if (!isPlainObject(raw)) {
+    throw new Error("metadata must be a plain object");
+  }
+  let serialized;
+  try {
+    serialized = JSON.stringify(raw);
+  } catch {
+    throw new Error("metadata must be JSON-serializable");
+  }
+  if (utf8Size(serialized) > MAX_METADATA_SIZE_BYTES) {
+    throw new Error(`metadata exceeds ${MAX_METADATA_SIZE_BYTES} bytes`);
+  }
+  const entries = Object.entries(raw);
+  if (entries.length > MAX_METADATA_KEY_COUNT) {
+    throw new Error(`metadata has ${entries.length} keys, max is ${MAX_METADATA_KEY_COUNT}`);
+  }
+  for (const [key, value] of entries) {
+    validateMetadataKey(key);
+    validateMetadataValue(value, key, 1);
+  }
+  const typed = raw;
+  if (typed.taskId !== void 0 && typeof typed.taskId !== "string") {
+    throw new Error("metadata.taskId must be a string");
+  }
+  if (typed.taskId !== void 0 && typeof typed.taskId === "string" && !TASK_ID_PATTERN.test(typed.taskId)) {
+    throw new Error("metadata.taskId must match ^(TASK|GOAL)-\\d{3,}$");
+  }
+  if (typed.agentType !== void 0 && typeof typed.agentType !== "string") {
+    throw new Error("metadata.agentType must be a string");
+  }
+  if (typed.label !== void 0 && typeof typed.label !== "string") {
+    throw new Error("metadata.label must be a string");
+  }
+  if (typed.tags !== void 0) {
+    if (!Array.isArray(typed.tags) || !typed.tags.every((tag) => typeof tag === "string")) {
+      throw new Error("metadata.tags must be string[]");
+    }
+  }
+  return typed;
+}
+var DANGEROUS_METADATA_KEYS, TASK_ID_PATTERN, MAX_METADATA_SIZE_BYTES, MAX_METADATA_KEY_COUNT, MAX_METADATA_KEY_LENGTH, MAX_METADATA_STRING_VALUE_LENGTH, MAX_METADATA_NESTING_DEPTH;
+var init_metadata_validation = __esm({
+  "src/core/metadata-validation.ts"() {
+    "use strict";
+    DANGEROUS_METADATA_KEYS = /* @__PURE__ */ new Set(["__proto__", "constructor", "prototype"]);
+    TASK_ID_PATTERN = /^(TASK|GOAL)-\d{3,}$/;
+    MAX_METADATA_SIZE_BYTES = 8 * 1024;
+    MAX_METADATA_KEY_COUNT = 20;
+    MAX_METADATA_KEY_LENGTH = 64;
+    MAX_METADATA_STRING_VALUE_LENGTH = 1024;
+    MAX_METADATA_NESTING_DEPTH = 3;
+  }
+});
+
 // src/mcp-server/deferred-cleanup-task-store.ts
 import { isTerminal } from "@modelcontextprotocol/sdk/experimental/tasks/interfaces.js";
 import { randomBytes } from "crypto";
@@ -169,6 +283,424 @@ var init_deferred_cleanup_task_store = __esm({
   }
 });
 
+// src/core/agent-event-store.ts
+import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { join as join6 } from "path";
+import { homedir as homedir5 } from "os";
+import { nanoid as nanoid2 } from "nanoid";
+function getRelayHome2() {
+  return process.env["RELAY_HOME"] ?? join6(homedir5(), ".relay");
+}
+function isValidEventType(type) {
+  return type === "session-start" || type === "session-complete" || type === "session-error" || type === "session-stale" || type === "context-threshold";
+}
+var DEFAULT_CONFIG2, AgentEventStore;
+var init_agent_event_store = __esm({
+  "src/core/agent-event-store.ts"() {
+    "use strict";
+    init_logger();
+    DEFAULT_CONFIG2 = {
+      maxEvents: 1e3,
+      ttlMs: 36e5,
+      backend: "jsonl",
+      sessionDir: join6(getRelayHome2(), "sessions"),
+      eventsFileName: "events.jsonl"
+    };
+    AgentEventStore = class {
+      config;
+      eventsFilePath;
+      cleanupTimer = null;
+      events = [];
+      constructor(config) {
+        const ttlMs = config?.ttlMs ?? (config?.ttlSec ?? 3600) * 1e3;
+        this.config = {
+          ...DEFAULT_CONFIG2,
+          ...config,
+          ttlMs
+        };
+        this.eventsFilePath = this.config.backend === "jsonl" ? join6(this.config.sessionDir, this.config.eventsFileName) : null;
+        if (this.eventsFilePath) {
+          mkdirSync(this.config.sessionDir, { recursive: true });
+          this.restoreFromJsonl();
+        }
+        this.cleanupTimer = setInterval(() => {
+          this.prune();
+        }, 6e4);
+        this.cleanupTimer.unref();
+      }
+      restoreFromJsonl() {
+        if (!this.eventsFilePath || !existsSync(this.eventsFilePath)) {
+          return;
+        }
+        let malformedCount = 0;
+        try {
+          const raw = readFileSync(this.eventsFilePath, "utf-8");
+          const lines = raw.split("\n").filter((line) => line.trim().length > 0);
+          for (const line of lines) {
+            try {
+              const parsed = JSON.parse(line);
+              if (typeof parsed.eventId !== "string" || typeof parsed.timestamp !== "string" || !isValidEventType(parsed.type) || typeof parsed.sessionId !== "string" || typeof parsed.backendId !== "string" || typeof parsed.metadata !== "object" || parsed.metadata === null || typeof parsed.data !== "object" || parsed.data === null) {
+                malformedCount += 1;
+                continue;
+              }
+              this.events.push({
+                eventId: parsed.eventId,
+                timestamp: parsed.timestamp,
+                type: parsed.type,
+                sessionId: parsed.sessionId,
+                parentSessionId: parsed.parentSessionId,
+                backendId: parsed.backendId,
+                metadata: parsed.metadata,
+                data: parsed.data
+              });
+            } catch {
+              malformedCount += 1;
+            }
+          }
+          this.events.sort((a, b) => {
+            const diff = new Date(a.timestamp).getTime() - new Date(b.timestamp).getTime();
+            return diff !== 0 ? diff : 0;
+          });
+          this.prune();
+        } catch (error) {
+          logger.warn(
+            `Failed to restore event store from JSONL: ${error instanceof Error ? error.message : String(error)}`
+          );
+          return;
+        }
+        if (malformedCount > 0) {
+          logger.warn(
+            `Skipped ${malformedCount} malformed event line(s) while restoring ${this.eventsFilePath}`
+          );
+        }
+      }
+      record(event) {
+        const fullEvent = {
+          ...event,
+          eventId: `evt-${nanoid2()}`,
+          timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+          metadata: event.metadata ?? {},
+          data: event.data ?? {}
+        };
+        this.events.push(fullEvent);
+        if (this.eventsFilePath) {
+          try {
+            appendFileSync(
+              this.eventsFilePath,
+              `${JSON.stringify(fullEvent)}
+`,
+              "utf-8"
+            );
+          } catch (error) {
+            logger.warn(
+              `Failed to append event JSONL: ${error instanceof Error ? error.message : String(error)}`
+            );
+          }
+        }
+        this.prune();
+        return fullEvent;
+      }
+      query(params) {
+        this.prune();
+        const limit = Math.max(1, Math.min(200, params.limit));
+        let candidates = this.events;
+        if (params.afterEventId) {
+          const index = candidates.findIndex((e) => e.eventId === params.afterEventId);
+          if (index < 0) {
+            throw new Error(
+              `RELAY_INVALID_CURSOR: cursor "${params.afterEventId}" was not found`
+            );
+          }
+          candidates = candidates.slice(index + 1);
+        }
+        if (params.types && params.types.length > 0) {
+          const wanted = new Set(params.types);
+          candidates = candidates.filter((event) => wanted.has(event.type));
+        }
+        if (params.sessionId) {
+          candidates = candidates.filter((event) => event.sessionId === params.sessionId);
+        }
+        if (params.parentSessionId) {
+          if (params.recursive) {
+            const descendants = /* @__PURE__ */ new Set();
+            const queue = [params.parentSessionId];
+            while (queue.length > 0) {
+              const parent = queue.shift();
+              const children = this.events.filter((event) => event.parentSessionId === parent).map((event) => event.sessionId);
+              for (const child of children) {
+                if (!descendants.has(child)) {
+                  descendants.add(child);
+                  queue.push(child);
+                }
+              }
+            }
+            candidates = candidates.filter((event) => descendants.has(event.sessionId));
+          } else {
+            candidates = candidates.filter(
+              (event) => event.parentSessionId === params.parentSessionId
+            );
+          }
+        }
+        const events = candidates.slice(0, limit);
+        return {
+          events,
+          hasMore: candidates.length > events.length
+        };
+      }
+      prune() {
+        const now = Date.now();
+        const ttlCutoff = now - this.config.ttlMs;
+        let nextEvents = this.events.filter((event) => {
+          const ts = new Date(event.timestamp).getTime();
+          return !Number.isNaN(ts) && ts >= ttlCutoff;
+        });
+        if (nextEvents.length > this.config.maxEvents) {
+          nextEvents = nextEvents.slice(nextEvents.length - this.config.maxEvents);
+        }
+        if (nextEvents.length !== this.events.length) {
+          this.events = nextEvents;
+          if (this.eventsFilePath) {
+            try {
+              const serialized = this.events.length > 0 ? `${this.events.map((event) => JSON.stringify(event)).join("\n")}
+` : "";
+              writeFileSync(this.eventsFilePath, serialized, "utf-8");
+            } catch (error) {
+              logger.warn(
+                `Failed to prune event JSONL file: ${error instanceof Error ? error.message : String(error)}`
+              );
+            }
+          }
+        }
+      }
+      cleanup() {
+        if (this.cleanupTimer) {
+          clearInterval(this.cleanupTimer);
+          this.cleanupTimer = null;
+        }
+        this.events = [];
+      }
+    };
+  }
+});
+
+// src/core/session-health-monitor.ts
+var DEFAULT_CONFIG3, SessionHealthMonitor;
+var init_session_health_monitor = __esm({
+  "src/core/session-health-monitor.ts"() {
+    "use strict";
+    init_logger();
+    DEFAULT_CONFIG3 = {
+      enabled: true,
+      heartbeatIntervalSec: 300,
+      staleThresholdSec: 300,
+      cleanupAfterSec: 3600,
+      maxActiveSessions: 20,
+      checkIntervalSec: 60,
+      memoryDir: "./memory"
+    };
+    SessionHealthMonitor = class {
+      constructor(config, sessionManager2, hooksEngine2, contextMonitor2, agentEventStore) {
+        this.sessionManager = sessionManager2;
+        this.hooksEngine = hooksEngine2;
+        this.contextMonitor = contextMonitor2;
+        this.agentEventStore = agentEventStore;
+        this.config = { ...DEFAULT_CONFIG3, ...config };
+        this.staleThresholdMs = this.config.staleThresholdSec * 1e3;
+        this.cleanupAfterMs = this.config.cleanupAfterSec * 1e3;
+        this.checkIntervalMs = this.config.checkIntervalSec * 1e3;
+      }
+      config;
+      staleThresholdMs;
+      cleanupAfterMs;
+      checkIntervalMs;
+      timer = null;
+      isChecking = false;
+      start() {
+        if (!this.config.enabled || this.timer) {
+          return;
+        }
+        this.timer = setInterval(() => {
+          void this.checkHealthLoop();
+        }, this.checkIntervalMs);
+        this.timer.unref();
+      }
+      stop() {
+        if (this.timer) {
+          clearInterval(this.timer);
+          this.timer = null;
+        }
+      }
+      async checkHealth(options) {
+        let sessions;
+        if (options?.sessionId) {
+          const session = await this.sessionManager.get(options.sessionId);
+          if (!session) {
+            throw new Error(`Session not found: ${options.sessionId}`);
+          }
+          sessions = [session];
+        } else if (options?.includeCompleted) {
+          sessions = await this.sessionManager.list();
+        } else {
+          sessions = await this.sessionManager.list({ status: "active" });
+        }
+        const now = Date.now();
+        const statuses = sessions.map(
+          (session) => this.buildHealthStatus(session, now)
+        );
+        const staleSessions = statuses.filter((status) => status.isStale).map((status) => status.relaySessionId);
+        return {
+          sessions: statuses,
+          staleSessions,
+          summary: {
+            total: statuses.length,
+            active: statuses.filter((s) => s.status === "active").length,
+            stale: staleSessions.length,
+            completed: statuses.filter((s) => s.status === "completed").length,
+            error: statuses.filter((s) => s.status === "error").length
+          }
+        };
+      }
+      isStale(session) {
+        if (session.status !== "active") {
+          return false;
+        }
+        return this.getLastActivityAtMs(session) + this.staleThresholdMs < Date.now();
+      }
+      async handleStaleSession(session) {
+        if (session.status !== "active") {
+          return;
+        }
+        if (session.staleNotifiedAt) {
+          return;
+        }
+        const now = /* @__PURE__ */ new Date();
+        const staleSinceMs = now.getTime() - this.getLastActivityAtMs(session);
+        const errorMessage = `Session stale: no activity for ${staleSinceMs}ms`;
+        const contextUsage = this.contextMonitor?.getUsage(session.relaySessionId);
+        await this.sessionManager.update(session.relaySessionId, {
+          status: "error",
+          errorCode: "RELAY_SESSION_STALE",
+          errorMessage,
+          staleNotifiedAt: now
+        });
+        this.agentEventStore.record({
+          type: "session-stale",
+          sessionId: session.relaySessionId,
+          parentSessionId: session.parentSessionId ?? void 0,
+          backendId: session.backendId,
+          metadata: session.metadata,
+          data: {
+            lastHeartbeatAt: session.lastHeartbeatAt.toISOString(),
+            staleSinceMs,
+            taskId: session.metadata.taskId,
+            label: session.metadata.label,
+            agentType: session.metadata.agentType,
+            contextUsage: contextUsage ? {
+              usagePercent: contextUsage.usagePercent,
+              estimatedTokens: contextUsage.estimatedTokens,
+              contextWindow: contextUsage.contextWindow
+            } : void 0
+          }
+        });
+        if (this.hooksEngine) {
+          await this.hooksEngine.emit("on-session-stale", {
+            event: "on-session-stale",
+            sessionId: session.relaySessionId,
+            backendId: session.backendId,
+            timestamp: now.toISOString(),
+            data: {
+              lastHeartbeatAt: session.lastHeartbeatAt.toISOString(),
+              staleSinceMs,
+              taskId: session.metadata.taskId,
+              label: session.metadata.label,
+              agentType: session.metadata.agentType,
+              contextUsage: contextUsage ? {
+                usagePercent: contextUsage.usagePercent,
+                estimatedTokens: contextUsage.estimatedTokens
+              } : void 0,
+              memoryDir: this.config.memoryDir ?? "./memory"
+            }
+          });
+        }
+      }
+      async cleanupOldSessions() {
+        const { deletedSessionIds } = await this.sessionManager.cleanup(
+          this.cleanupAfterMs
+        );
+        if (this.contextMonitor) {
+          for (const sessionId of deletedSessionIds) {
+            this.contextMonitor.removeSession(sessionId);
+          }
+        }
+      }
+      async checkHealthLoop() {
+        if (this.isChecking) return;
+        this.isChecking = true;
+        try {
+          const health = await this.checkHealth({ includeCompleted: false });
+          for (const staleId of health.staleSessions) {
+            const session = await this.sessionManager.get(staleId);
+            if (!session || !this.isStale(session)) {
+              continue;
+            }
+            await this.handleStaleSession(session);
+          }
+          await this.cleanupOldSessions();
+          const activeHealthyCount = health.sessions.filter(
+            (session) => session.status === "active" && !session.isStale
+          ).length;
+          const warnThreshold = Math.ceil(this.config.maxActiveSessions * 0.8);
+          if (activeHealthyCount >= warnThreshold) {
+            logger.warn(
+              `Active session usage high: ${activeHealthyCount}/${this.config.maxActiveSessions}`
+            );
+          }
+        } catch (error) {
+          logger.warn(
+            `Session health check failed: ${error instanceof Error ? error.message : String(error)}`
+          );
+        } finally {
+          this.isChecking = false;
+        }
+      }
+      buildHealthStatus(session, now) {
+        const lastActivityAtMs = this.getLastActivityAtMs(session);
+        const isStale = session.status === "active" && lastActivityAtMs + this.staleThresholdMs < now;
+        const issues = [];
+        if (isStale) {
+          issues.push("stale");
+        }
+        const usage = this.contextMonitor?.getUsage(session.relaySessionId);
+        if (usage && usage.usagePercent >= 95) {
+          issues.push("high_context_usage");
+        }
+        return {
+          relaySessionId: session.relaySessionId,
+          status: session.status,
+          backendId: session.backendId,
+          healthy: issues.length === 0,
+          issues,
+          staleSince: isStale ? new Date(lastActivityAtMs + this.staleThresholdMs).toISOString() : void 0,
+          isStale,
+          lastHeartbeatAt: session.lastHeartbeatAt.toISOString(),
+          metadata: session.metadata,
+          contextUsage: usage ? {
+            usagePercent: usage.usagePercent,
+            estimatedTokens: usage.estimatedTokens,
+            contextWindow: usage.contextWindow
+          } : void 0
+        };
+      }
+      getLastActivityAtMs(session) {
+        return Math.max(
+          session.lastHeartbeatAt.getTime(),
+          session.updatedAt.getTime()
+        );
+      }
+    };
+  }
+});
+
 // src/mcp-server/recursion-guard.ts
 import { createHash } from "crypto";
 var RecursionGuard;
@@ -288,9 +820,9 @@ var init_recursion_guard = __esm({
 
 // src/mcp-server/tools/spawn-agent.ts
 import { z as z2 } from "zod";
-import { nanoid as nanoid2 } from "nanoid";
-import { existsSync, readFileSync } from "fs";
-import { join as join6, normalize, resolve, sep } from "path";
+import { nanoid as nanoid3 } from "nanoid";
+import { existsSync as existsSync2, readFileSync as readFileSync2 } from "fs";
+import { join as join7, normalize, resolve, sep } from "path";
 function buildContextInjection(metadata) {
   const parts = [];
   if (metadata.stateContent && typeof metadata.stateContent === "string") {
@@ -309,9 +841,9 @@ ${formatted}
 }
 function readPreviousState(dailynoteDir) {
   try {
-    const statePath = join6(dailynoteDir, "_state.md");
-    if (existsSync(statePath)) {
-      return readFileSync(statePath, "utf-8");
+    const statePath = join7(dailynoteDir, "_state.md");
+    if (existsSync2(statePath)) {
+      return readFileSync2(statePath, "utf-8");
     }
     return null;
   } catch (error) {
@@ -336,11 +868,11 @@ function validatePathWithinProject(filePath, projectRoot) {
 function readAgentDefinition(definitionPath, projectRoot = process.cwd()) {
   try {
     const safeDefinitionPath = validatePathWithinProject(definitionPath, projectRoot);
-    if (!existsSync(safeDefinitionPath)) {
+    if (!existsSync2(safeDefinitionPath)) {
       logger.warn(`Agent definition file not found at ${safeDefinitionPath}`);
       return null;
     }
-    const content = readFileSync(safeDefinitionPath, "utf-8");
+    const content = readFileSync2(safeDefinitionPath, "utf-8");
     if (content.trim().length === 0) {
       logger.warn(`Agent definition file is empty at ${safeDefinitionPath}`);
       return null;
@@ -356,25 +888,25 @@ function readAgentDefinition(definitionPath, projectRoot = process.cwd()) {
 function readSkillContext(skillContext, projectRoot = process.cwd()) {
   try {
     const safeSkillPath = validatePathWithinProject(skillContext.skillPath, projectRoot);
-    const skillMdPath = validatePathWithinProject(join6(safeSkillPath, "SKILL.md"), projectRoot);
-    if (!existsSync(skillMdPath)) {
+    const skillMdPath = validatePathWithinProject(join7(safeSkillPath, "SKILL.md"), projectRoot);
+    if (!existsSync2(skillMdPath)) {
       logger.warn(
         `SKILL.md not found at ${skillMdPath}`
       );
       return null;
     }
     const parts = [];
-    const skillContent = readFileSync(skillMdPath, "utf-8");
+    const skillContent = readFileSync2(skillMdPath, "utf-8");
     parts.push(skillContent);
     if (skillContext.subskill) {
-      const subskillPath = validatePathWithinProject(join6(
+      const subskillPath = validatePathWithinProject(join7(
         safeSkillPath,
         "subskills",
         skillContext.subskill,
         "SUBSKILL.md"
       ), projectRoot);
-      if (existsSync(subskillPath)) {
-        const subskillContent = readFileSync(subskillPath, "utf-8");
+      if (existsSync2(subskillPath)) {
+        const subskillContent = readFileSync2(subskillPath, "utf-8");
         parts.push(subskillContent);
       } else {
         logger.warn(
@@ -393,11 +925,11 @@ function readSkillContext(skillContext, projectRoot = process.cwd()) {
 function readProjectMcpJson(cwd) {
   try {
     const dir = cwd ?? process.cwd();
-    const mcpJsonPath = join6(dir, ".mcp.json");
-    if (!existsSync(mcpJsonPath)) {
+    const mcpJsonPath = join7(dir, ".mcp.json");
+    if (!existsSync2(mcpJsonPath)) {
       return {};
     }
-    const raw = readFileSync(mcpJsonPath, "utf-8");
+    const raw = readFileSync2(mcpJsonPath, "utf-8");
     const parsed = JSON.parse(raw);
     const servers = parsed.mcpServers;
     if (!servers || typeof servers !== "object") {
@@ -438,6 +970,17 @@ function buildChildMcpServers(parentMcpServers, childHttpUrl) {
   }
   return result;
 }
+function resolveValidatedSessionMetadata(input) {
+  const validated = validateMetadata(input.metadata);
+  const mergedMetadata = { ...validated };
+  if (mergedMetadata.agentType === void 0 && input.agent !== void 0) {
+    mergedMetadata.agentType = input.agent;
+  }
+  if (mergedMetadata.label === void 0 && input.label !== void 0) {
+    mergedMetadata.label = input.label;
+  }
+  return validateMetadata(mergedMetadata);
+}
 function inferFailureReason(stderr, stdout, sdkErrorMetadata) {
   if (sdkErrorMetadata) {
     if (sdkErrorMetadata.subtype === "error_max_turns") return "max_turns_exhausted";
@@ -449,13 +992,42 @@ function inferFailureReason(stderr, stdout, sdkErrorMetadata) {
   if (combined.includes("429") || combined.includes("capacity_exhausted") || combined.includes("model_capacity_exhausted") || combined.includes("ratelimitexceeded") || combined.includes("resource_exhausted")) return "rate_limit";
   return "adapter_error";
 }
+function failureReasonToErrorCode(reason) {
+  switch (reason) {
+    case "recursion_blocked":
+      return "RELAY_RECURSION_BLOCKED";
+    case "metadata_validation":
+      return "RELAY_METADATA_VALIDATION";
+    case "backend_unavailable":
+      return "RELAY_BACKEND_UNAVAILABLE";
+    case "instruction_file_error":
+      return "RELAY_INSTRUCTION_FILE_ERROR";
+    case "session_continuation_unsupported":
+      return "RELAY_SESSION_CONTINUATION_UNSUPPORTED";
+    case "session_not_found":
+      return "RELAY_SESSION_NOT_FOUND";
+    case "timeout":
+      return "RELAY_TIMEOUT";
+    case "max_turns_exhausted":
+      return "RELAY_MAX_TURNS_EXHAUSTED";
+    case "rate_limit":
+      return "RELAY_RATE_LIMIT";
+    case "adapter_error":
+      return "RELAY_ADAPTER_ERROR";
+    case "unknown":
+      return "RELAY_UNKNOWN_ERROR";
+  }
+}
+function isShortCircuitSpawnResult(value) {
+  return "_noSession" in value;
+}
 function buildContextFromEnv() {
-  const traceId = process.env["RELAY_TRACE_ID"] ?? `trace-${nanoid2()}`;
+  const traceId = process.env["RELAY_TRACE_ID"] ?? `trace-${nanoid3()}`;
   const parentSessionId = process.env["RELAY_PARENT_SESSION_ID"] ?? null;
   const depth = Number(process.env["RELAY_DEPTH"] ?? "0");
   return { traceId, parentSessionId, depth };
 }
-async function executeSpawnAgent(input, registry2, sessionManager2, guard, hooksEngine2, contextMonitor2, backendSelector, childHttpUrl, onProgress) {
+async function executeSpawnAgent(input, registry2, sessionManager2, guard, hooksEngine2, contextMonitor2, backendSelector, childHttpUrl, onProgress, agentEventStore, hookMemoryDir = "./memory") {
   onProgress?.({ stage: "initializing", percent: 0 });
   let effectiveBackend;
   let selectionReason;
@@ -509,16 +1081,55 @@ async function executeSpawnAgent(input, registry2, sessionManager2, guard, hooks
     };
   }
   const spawnStartedAt = (/* @__PURE__ */ new Date()).toISOString();
-  const session = await sessionManager2.create({
+  let validatedMetadata;
+  try {
+    validatedMetadata = resolveValidatedSessionMetadata(input);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return {
+      sessionId: "",
+      exitCode: 1,
+      stdout: "",
+      stderr: `RELAY_METADATA_VALIDATION: ${message}`,
+      failureReason: "metadata_validation"
+    };
+  }
+  let session;
+  try {
+    session = await sessionManager2.create({
+      backendId: effectiveBackend,
+      parentSessionId: envContext.parentSessionId ?? void 0,
+      depth: envContext.depth + 1,
+      metadata: validatedMetadata
+    });
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return {
+      sessionId: "",
+      exitCode: 1,
+      stdout: "",
+      stderr: message,
+      failureReason: "unknown"
+    };
+  }
+  agentEventStore?.record({
+    type: "session-start",
+    sessionId: session.relaySessionId,
+    parentSessionId: session.parentSessionId ?? void 0,
     backendId: effectiveBackend,
-    parentSessionId: envContext.parentSessionId ?? void 0,
-    depth: envContext.depth + 1
+    metadata: session.metadata,
+    data: {
+      taskId: session.metadata.taskId,
+      label: session.metadata.label,
+      agentType: session.metadata.agentType,
+      selectedBackend: effectiveBackend
+    }
   });
   let collectedMetadata = {};
   if (hooksEngine2 && !input.resumeSessionId) {
     try {
       const cwd = process.cwd();
-      const dailynoteDir = join6(cwd, "daily_note");
+      const dailynoteDir = join7(cwd, "daily_note");
       const hookInput = {
         schemaVersion: "1.0",
         event: "session-init",
@@ -528,7 +1139,7 @@ async function executeSpawnAgent(input, registry2, sessionManager2, guard, hooks
         data: {
           workingDirectory: cwd,
           dailynoteDir,
-          isFirstSession: !existsSync(join6(dailynoteDir, "_state.md")),
+          isFirstSession: !existsSync2(join7(dailynoteDir, "_state.md")),
           previousState: readPreviousState(dailynoteDir)
         }
       };
@@ -592,7 +1203,7 @@ ${wrapped}` : wrapped;
     try {
       const projectRoot = process.cwd();
       const safePath = validatePathWithinProject(input.taskInstructionPath, projectRoot);
-      if (!existsSync(safePath)) {
+      if (!existsSync2(safePath)) {
         return {
           sessionId: "",
           exitCode: 1,
@@ -601,7 +1212,7 @@ ${wrapped}` : wrapped;
           failureReason: "instruction_file_error"
         };
       }
-      const instructionContent = readFileSync(safePath, "utf-8");
+      const instructionContent = readFileSync2(safePath, "utf-8");
       effectivePrompt = `${instructionContent}
 
 ${input.prompt}`;
@@ -617,6 +1228,14 @@ ${input.prompt}`;
     }
   }
   onProgress?.({ stage: "spawning", percent: 10 });
+  const heartbeatTimer = setInterval(() => {
+    void sessionManager2.updateHeartbeat(session.relaySessionId).catch((heartbeatError) => {
+      logger.warn(
+        `Internal heartbeat update failed: ${heartbeatError instanceof Error ? heartbeatError.message : String(heartbeatError)}`
+      );
+    });
+  }, 3e4);
+  heartbeatTimer.unref();
   try {
     const executePromise = (async () => {
       if (input.resumeSessionId) {
@@ -678,17 +1297,30 @@ ${input.prompt}`;
         });
       }
     })();
-    const result = await executePromise;
-    if (result && "_noSession" in result) {
-      return {
-        sessionId: session.relaySessionId,
-        exitCode: result.exitCode,
-        stdout: result.stdout,
-        stderr: result.stderr,
-        ..."_failureReason" in result ? { failureReason: result._failureReason } : {}
-      };
+    let rawResult;
+    try {
+      rawResult = await executePromise;
+    } finally {
+      clearInterval(heartbeatTimer);
     }
     onProgress?.({ stage: "executing", percent: 50 });
+    let isShortCircuit = false;
+    let failureReasonFromShortCircuit;
+    let result;
+    if (isShortCircuitSpawnResult(rawResult)) {
+      isShortCircuit = true;
+      failureReasonFromShortCircuit = rawResult._failureReason;
+      result = {
+        exitCode: rawResult.exitCode,
+        stdout: rawResult.stdout,
+        stderr: rawResult.stderr,
+        nativeSessionId: void 0,
+        tokenUsage: void 0,
+        sdkErrorMetadata: void 0
+      };
+    } else {
+      result = rawResult;
+    }
     if (contextMonitor2) {
       const estimatedTokens = Math.ceil(
         (result.stdout.length + result.stderr.length) / 4
@@ -696,16 +1328,28 @@ ${input.prompt}`;
       contextMonitor2.updateUsage(
         session.relaySessionId,
         effectiveBackend,
-        estimatedTokens
+        estimatedTokens,
+        session.metadata
       );
+      await sessionManager2.updateHeartbeat(session.relaySessionId).catch(() => void 0);
+    }
+    if (!isShortCircuit) {
+      guard.recordSpawn(context);
     }
-    guard.recordSpawn(context);
     const status = result.exitCode === 0 ? "completed" : "error";
-    const failureReason = result.exitCode !== 0 ? inferFailureReason(result.stderr, result.stdout, result.sdkErrorMetadata) : void 0;
+    const failureReason = result.exitCode !== 0 ? failureReasonFromShortCircuit ?? inferFailureReason(result.stderr, result.stdout, result.sdkErrorMetadata) : void 0;
     await sessionManager2.update(session.relaySessionId, {
       status,
-      ...result.nativeSessionId ? { nativeSessionId: result.nativeSessionId } : {}
+      ...result.nativeSessionId ? { nativeSessionId: result.nativeSessionId } : {},
+      ...status === "error" ? {
+        errorMessage: result.stderr.slice(0, 500),
+        errorCode: failureReason ? failureReasonToErrorCode(failureReason) : "RELAY_UNKNOWN_ERROR"
+      } : {
+        errorMessage: void 0,
+        errorCode: void 0
+      }
     });
+    contextMonitor2?.removeSession(session.relaySessionId);
     const completedAt = (/* @__PURE__ */ new Date()).toISOString();
     const metadata = {
       durationMs: new Date(completedAt).getTime() - new Date(spawnStartedAt).getTime(),
@@ -716,6 +1360,103 @@ ${input.prompt}`;
       completedAt,
       ...result.tokenUsage ? { tokenUsage: result.tokenUsage } : {}
     };
+    if (status === "completed") {
+      agentEventStore?.record({
+        type: "session-complete",
+        sessionId: session.relaySessionId,
+        parentSessionId: session.parentSessionId ?? void 0,
+        backendId: effectiveBackend,
+        metadata: session.metadata,
+        data: {
+          exitCode: result.exitCode,
+          durationMs: metadata.durationMs,
+          taskId: session.metadata.taskId,
+          label: session.metadata.label,
+          agentType: session.metadata.agentType,
+          nativeSessionId: result.nativeSessionId,
+          selectedBackend: effectiveBackend,
+          tokenUsage: result.tokenUsage
+        }
+      });
+      if (hooksEngine2) {
+        try {
+          await hooksEngine2.emit("on-session-complete", {
+            event: "on-session-complete",
+            sessionId: session.relaySessionId,
+            backendId: effectiveBackend,
+            timestamp: completedAt,
+            data: {
+              exitCode: result.exitCode,
+              durationMs: metadata.durationMs,
+              taskId: session.metadata.taskId,
+              label: session.metadata.label,
+              agentType: session.metadata.agentType,
+              nativeSessionId: result.nativeSessionId,
+              selectedBackend: effectiveBackend,
+              tokenUsage: result.tokenUsage,
+              memoryDir: hookMemoryDir
+            }
+          });
+        } catch (hookError) {
+          logger.debug(
+            `on-session-complete hook error: ${hookError instanceof Error ? hookError.message : String(hookError)}`
+          );
+        }
+      }
+    } else if (failureReason) {
+      const retryableReasons = [
+        "timeout",
+        "rate_limit",
+        "adapter_error",
+        "unknown"
+      ];
+      const isRetryable = retryableReasons.includes(failureReason);
+      const errorMessage = result.stderr.slice(0, 500);
+      agentEventStore?.record({
+        type: "session-error",
+        sessionId: session.relaySessionId,
+        parentSessionId: session.parentSessionId ?? void 0,
+        backendId: effectiveBackend,
+        metadata: session.metadata,
+        data: {
+          exitCode: result.exitCode,
+          failureReason,
+          errorMessage,
+          durationMs: metadata.durationMs,
+          taskId: session.metadata.taskId,
+          label: session.metadata.label,
+          agentType: session.metadata.agentType,
+          selectedBackend: effectiveBackend,
+          isRetryable
+        }
+      });
+      if (hooksEngine2) {
+        try {
+          await hooksEngine2.emit("on-session-error", {
+            event: "on-session-error",
+            sessionId: session.relaySessionId,
+            backendId: effectiveBackend,
+            timestamp: completedAt,
+            data: {
+              exitCode: result.exitCode,
+              failureReason,
+              errorMessage,
+              durationMs: metadata.durationMs,
+              taskId: session.metadata.taskId,
+              label: session.metadata.label,
+              agentType: session.metadata.agentType,
+              selectedBackend: effectiveBackend,
+              isRetryable,
+              memoryDir: hookMemoryDir
+            }
+          });
+        } catch (hookError) {
+          logger.debug(
+            `on-session-error hook error: ${hookError instanceof Error ? hookError.message : String(hookError)}`
+          );
+        }
+      }
+    }
     onProgress?.({ stage: "completed", percent: 100 });
     if (hooksEngine2) {
       try {
@@ -758,9 +1499,69 @@ ${input.prompt}`;
       ...failureReason ? { failureReason } : {}
     };
   } catch (error) {
-    await sessionManager2.update(session.relaySessionId, { status: "error" });
+    clearInterval(heartbeatTimer);
     const message = error instanceof Error ? error.message : String(error);
     const catchFailureReason = message.toLowerCase().includes("timed out") || message.toLowerCase().includes("timeout") ? "timeout" : "unknown";
+    await sessionManager2.update(session.relaySessionId, {
+      status: "error",
+      errorMessage: message.slice(0, 500),
+      errorCode: failureReasonToErrorCode(catchFailureReason)
+    });
+    contextMonitor2?.removeSession(session.relaySessionId);
+    const completedAt = (/* @__PURE__ */ new Date()).toISOString();
+    const durationMs = new Date(completedAt).getTime() - new Date(spawnStartedAt).getTime();
+    const errorMessage = message.slice(0, 500);
+    const retryableReasons = [
+      "timeout",
+      "rate_limit",
+      "adapter_error",
+      "unknown"
+    ];
+    const isRetryable = retryableReasons.includes(catchFailureReason);
+    agentEventStore?.record({
+      type: "session-error",
+      sessionId: session.relaySessionId,
+      parentSessionId: session.parentSessionId ?? void 0,
+      backendId: effectiveBackend,
+      metadata: session.metadata,
+      data: {
+        exitCode: 1,
+        failureReason: catchFailureReason,
+        errorMessage,
+        durationMs,
+        taskId: session.metadata.taskId,
+        label: session.metadata.label,
+        agentType: session.metadata.agentType,
+        selectedBackend: effectiveBackend,
+        isRetryable
+      }
+    });
+    if (hooksEngine2) {
+      try {
+        await hooksEngine2.emit("on-session-error", {
+          event: "on-session-error",
+          sessionId: session.relaySessionId,
+          backendId: effectiveBackend,
+          timestamp: completedAt,
+          data: {
+            exitCode: 1,
+            failureReason: catchFailureReason,
+            errorMessage,
+            durationMs,
+            taskId: session.metadata.taskId,
+            label: session.metadata.label,
+            agentType: session.metadata.agentType,
+            selectedBackend: effectiveBackend,
+            isRetryable,
+            memoryDir: hookMemoryDir
+          }
+        });
+      } catch (hookError) {
+        logger.debug(
+          `on-session-error hook error: ${hookError instanceof Error ? hookError.message : String(hookError)}`
+        );
+      }
+    }
     return {
       sessionId: session.relaySessionId,
       exitCode: 1,
@@ -776,6 +1577,7 @@ var init_spawn_agent = __esm({
     "use strict";
     init_recursion_guard();
     init_logger();
+    init_metadata_validation();
     spawnAgentInputSchema = z2.object({
       fallbackBackend: z2.enum(["claude", "codex", "gemini"]).optional().describe(
         "Optional fallback backend. Used only when BackendSelector is not active or cannot determine a backend. When BackendSelector is active, backend is auto-selected by priority: preferredBackend > agentType mapping > taskType mapping > default (claude)."
@@ -811,7 +1613,14 @@ var init_spawn_agent = __esm({
       taskInstructionPath: z2.string().optional().describe(
         "Path to a file containing task instructions. Content is prepended to the prompt. Path is resolved relative to the project root and validated against path traversal."
       ),
-      label: z2.string().optional().describe("Human-readable label for identifying this agent in parallel results and logs.")
+      label: z2.string().optional().describe("Human-readable label for identifying this agent in parallel results and logs."),
+      metadata: z2.object({
+        taskId: z2.string().regex(TASK_ID_PATTERN).optional(),
+        agentType: z2.string().optional(),
+        label: z2.string().optional(),
+        parentTaskId: z2.string().optional(),
+        tags: z2.array(z2.string()).optional()
+      }).catchall(z2.unknown()).optional().describe("Session metadata for task linkage and orchestration context.")
     });
   }
 });
@@ -908,7 +1717,31 @@ var init_conflict_detector = __esm({
 });
 
 // src/mcp-server/tools/spawn-agents-parallel.ts
-async function executeSpawnAgentsParallel(agents, registry2, sessionManager2, guard, hooksEngine2, contextMonitor2, backendSelector, childHttpUrl, onProgress) {
+async function executeSpawnAgentsParallel(agents, registry2, sessionManager2, guard, hooksEngine2, contextMonitor2, backendSelector, childHttpUrl, onProgress, agentEventStore, hookMemoryDir = "./memory") {
+  for (let index = 0; index < agents.length; index += 1) {
+    try {
+      resolveValidatedSessionMetadata(agents[index]);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      const reason = `RELAY_METADATA_VALIDATION: agent index ${index}: ${message}`;
+      return {
+        results: agents.map((agent, resultIndex) => ({
+          index: resultIndex,
+          sessionId: "",
+          exitCode: 1,
+          stdout: "",
+          stderr: reason,
+          error: reason,
+          failureReason: "metadata_validation",
+          ...agent.label ? { label: agent.label } : {},
+          originalInput: agent
+        })),
+        totalCount: agents.length,
+        successCount: 0,
+        failureCount: agents.length
+      };
+    }
+  }
   const envContext = buildContextFromEnv();
   if (envContext.depth >= guard.getConfig().maxDepth) {
     const reason = `Max depth exceeded: ${envContext.depth} >= ${guard.getConfig().maxDepth}`;
@@ -964,7 +1797,10 @@ async function executeSpawnAgentsParallel(agents, registry2, sessionManager2, gu
         hooksEngine2,
         contextMonitor2,
         backendSelector,
-        childHttpUrl
+        childHttpUrl,
+        void 0,
+        agentEventStore,
+        hookMemoryDir
       ).then((result) => {
         completedCount++;
         onProgress?.({
@@ -1034,17 +1870,35 @@ var init_spawn_agents_parallel = __esm({
 
 // src/mcp-server/tools/list-sessions.ts
 import { z as z3 } from "zod";
-async function executeListSessions(input, sessionManager2) {
+async function executeListSessions(input, sessionManager2, options) {
+  const validatedInput = listSessionsInputSchema.parse(input);
+  const normalizedBackendId = validatedInput.backendId ?? validatedInput.backend;
+  if (validatedInput.backendId && validatedInput.backend && validatedInput.backendId !== validatedInput.backend) {
+    logger.warn(
+      `list_sessions: both backendId and backend were provided; backendId="${validatedInput.backendId}" is used`
+    );
+  }
+  const staleThresholdMs = (options?.staleThresholdSec ?? 300) * 1e3;
   const sessions = await sessionManager2.list({
-    backendId: input.backend,
-    limit: input.limit
+    backendId: normalizedBackendId,
+    limit: validatedInput.limit,
+    status: validatedInput.staleOnly ? "active" : validatedInput.status,
+    taskId: validatedInput.taskId,
+    label: validatedInput.label,
+    tags: validatedInput.tags,
+    staleOnly: validatedInput.staleOnly ?? false,
+    staleThresholdMs
   });
   return {
     sessions: sessions.map((s) => ({
       relaySessionId: s.relaySessionId,
       backendId: s.backendId,
       status: s.status,
-      createdAt: s.createdAt.toISOString()
+      createdAt: s.createdAt.toISOString(),
+      updatedAt: s.updatedAt.toISOString(),
+      lastHeartbeatAt: s.lastHeartbeatAt.toISOString(),
+      isStale: s.status === "active" && s.lastHeartbeatAt.getTime() + staleThresholdMs < Date.now(),
+      metadata: s.metadata
     }))
   };
 }
@@ -1052,15 +1906,82 @@ var listSessionsInputSchema;
 var init_list_sessions = __esm({
   "src/mcp-server/tools/list-sessions.ts"() {
     "use strict";
+    init_logger();
+    init_metadata_validation();
     listSessionsInputSchema = z3.object({
+      backendId: z3.enum(["claude", "codex", "gemini"]).optional(),
       backend: z3.enum(["claude", "codex", "gemini"]).optional(),
-      limit: z3.number().optional().default(10)
+      limit: z3.number().int().min(1).max(100).optional().default(10),
+      status: z3.enum(["active", "completed", "error"]).optional(),
+      taskId: z3.string().regex(TASK_ID_PATTERN).optional(),
+      label: z3.string().optional(),
+      tags: z3.array(z3.string()).optional(),
+      staleOnly: z3.boolean().optional().default(false)
     });
   }
 });
 
-// src/mcp-server/tools/get-context-status.ts
+// src/mcp-server/tools/check-session-health.ts
 import { z as z4 } from "zod";
+async function executeCheckSessionHealth(input, sessionHealthMonitor) {
+  return sessionHealthMonitor.checkHealth({
+    sessionId: input.sessionId,
+    includeCompleted: input.includeCompleted ?? false
+  });
+}
+var checkSessionHealthInputSchema;
+var init_check_session_health = __esm({
+  "src/mcp-server/tools/check-session-health.ts"() {
+    "use strict";
+    checkSessionHealthInputSchema = z4.object({
+      sessionId: z4.string().optional().describe("Specific session to inspect. Omit to check all sessions."),
+      includeCompleted: z4.boolean().optional().default(false).describe("When true, include completed/error sessions in addition to active ones.")
+    });
+  }
+});
+
+// src/mcp-server/tools/poll-agent-events.ts
+import { z as z5 } from "zod";
+function executePollAgentEvents(input, agentEventStore) {
+  const limit = input.limit ?? 50;
+  const result = agentEventStore.query({
+    afterEventId: input.cursor,
+    types: input.types,
+    sessionId: input.sessionId,
+    parentSessionId: input.parentSessionId,
+    recursive: false,
+    limit
+  });
+  const lastEventId = result.events.length > 0 ? result.events[result.events.length - 1].eventId : input.cursor ?? null;
+  return {
+    events: result.events,
+    lastEventId,
+    hasMore: result.hasMore
+  };
+}
+var EVENT_TYPE_VALUES, pollAgentEventsInputSchema;
+var init_poll_agent_events = __esm({
+  "src/mcp-server/tools/poll-agent-events.ts"() {
+    "use strict";
+    EVENT_TYPE_VALUES = [
+      "session-start",
+      "session-complete",
+      "session-error",
+      "session-stale",
+      "context-threshold"
+    ];
+    pollAgentEventsInputSchema = z5.object({
+      cursor: z5.string().optional().describe("Exclusive cursor (previous lastEventId). Omit to start from oldest."),
+      types: z5.array(z5.enum(EVENT_TYPE_VALUES)).optional().describe("Filter by event types."),
+      sessionId: z5.string().optional().describe("Filter by session ID."),
+      parentSessionId: z5.string().optional().describe("Filter to direct child sessions of this parent session."),
+      limit: z5.number().int().min(1).max(200).optional().default(50).describe("Maximum number of events to return.")
+    });
+  }
+});
+
+// src/mcp-server/tools/get-context-status.ts
+import { z as z6 } from "zod";
 async function executeGetContextStatus(input, sessionManager2, contextMonitor2) {
   const session = await sessionManager2.get(input.sessionId);
   if (!session) {
@@ -1092,8 +2013,8 @@ var getContextStatusInputSchema;
 var init_get_context_status = __esm({
   "src/mcp-server/tools/get-context-status.ts"() {
     "use strict";
-    getContextStatusInputSchema = z4.object({
-      sessionId: z4.string()
+    getContextStatusInputSchema = z6.object({
+      sessionId: z6.string()
     });
   }
 });
@@ -1366,7 +2287,7 @@ import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/
 import { InMemoryTaskMessageQueue } from "@modelcontextprotocol/sdk/experimental/tasks/stores/in-memory.js";
 import { createServer } from "http";
 import { randomUUID } from "crypto";
-import { z as z5 } from "zod";
+import { z as z7 } from "zod";
 function createMcpServerOptions() {
   const taskStore = new DeferredCleanupTaskStore();
   return {
@@ -1381,41 +2302,79 @@ var init_server = __esm({
   "src/mcp-server/server.ts"() {
     "use strict";
     init_deferred_cleanup_task_store();
+    init_agent_event_store();
+    init_session_health_monitor();
     init_recursion_guard();
     init_spawn_agent();
     init_spawn_agents_parallel();
     init_list_sessions();
+    init_check_session_health();
+    init_poll_agent_events();
     init_get_context_status();
     init_list_available_backends();
     init_backend_selector();
+    init_metadata_validation();
     init_logger();
     init_types();
     init_response_formatter();
     spawnAgentsParallelInputShape = {
-      agents: z5.array(spawnAgentInputSchema).min(1).max(10).describe(
+      agents: z7.array(spawnAgentInputSchema).min(1).max(10).describe(
         "Array of agent configurations to execute in parallel (1-10 agents)"
       )
     };
     MAX_CHILD_HTTP_SESSIONS = 100;
     RelayMCPServer = class {
-      constructor(registry2, sessionManager2, guardConfig, hooksEngine2, contextMonitor2, inlineSummaryLength, responseOutputDir) {
+      constructor(registry2, sessionManager2, guardConfig, hooksEngine2, contextMonitor2, inlineSummaryLength, responseOutputDir, relayConfig) {
         this.registry = registry2;
         this.sessionManager = sessionManager2;
         this.hooksEngine = hooksEngine2;
         this.contextMonitor = contextMonitor2;
         this.inlineSummaryLength = inlineSummaryLength;
         this.responseOutputDir = responseOutputDir;
+        this.relayConfig = relayConfig;
         this.guard = new RecursionGuard(guardConfig);
         this.backendSelector = new BackendSelector();
+        this.staleThresholdSec = relayConfig?.sessionHealth?.staleThresholdSec ?? 300;
+        this.hookMemoryDir = relayConfig?.hooks?.memoryDir ?? "./memory";
+        this.agentEventStore = new AgentEventStore({
+          backend: relayConfig?.eventStore?.backend,
+          maxEvents: relayConfig?.eventStore?.maxEvents,
+          ttlSec: relayConfig?.eventStore?.ttlSec,
+          sessionDir: relayConfig?.eventStore?.sessionDir ?? this.sessionManager.getSessionsDir(),
+          eventsFileName: relayConfig?.eventStore?.eventsFileName
+        });
+        if (this.contextMonitor) {
+          this.contextMonitor.setAgentEventStore(this.agentEventStore);
+        }
+        this.sessionHealthMonitor = new SessionHealthMonitor(
+          {
+            enabled: relayConfig?.sessionHealth?.enabled,
+            heartbeatIntervalSec: relayConfig?.sessionHealth?.heartbeatIntervalSec,
+            staleThresholdSec: relayConfig?.sessionHealth?.staleThresholdSec,
+            cleanupAfterSec: relayConfig?.sessionHealth?.cleanupAfterSec,
+            maxActiveSessions: relayConfig?.sessionHealth?.maxActiveSessions,
+            checkIntervalSec: relayConfig?.sessionHealth?.checkIntervalSec,
+            memoryDir: this.hookMemoryDir
+          },
+          this.sessionManager,
+          this.hooksEngine ?? null,
+          this.contextMonitor ?? null,
+          this.agentEventStore
+        );
         this.server = new McpServer(
-          { name: "agentic-relay", version: "1.1.1" },
+          { name: "agentic-relay", version: "1.3.0" },
           createMcpServerOptions()
         );
         this.registerTools(this.server);
+        this.sessionHealthMonitor.start();
       }
       server;
       guard;
       backendSelector;
+      agentEventStore;
+      sessionHealthMonitor;
+      staleThresholdSec;
+      hookMemoryDir;
       _childHttpServer;
       _childHttpUrl;
       /** URL for child agents to connect via HTTP. Available after start() in stdio mode. */
@@ -1441,7 +2400,10 @@ var init_server = __esm({
               this.hooksEngine,
               this.contextMonitor,
               this.backendSelector,
-              this._childHttpUrl
+              this._childHttpUrl,
+              void 0,
+              this.agentEventStore,
+              this.hookMemoryDir
             );
             const controlOptions = {
               inlineSummaryLength: this.inlineSummaryLength ?? DEFAULT_INLINE_SUMMARY_LENGTH,
@@ -1493,7 +2455,10 @@ var init_server = __esm({
               this.hooksEngine,
               this.contextMonitor,
               this.backendSelector,
-              this._childHttpUrl
+              this._childHttpUrl,
+              void 0,
+              this.agentEventStore,
+              this.hookMemoryDir
             );
             const controlOptions = {
               inlineSummaryLength: this.inlineSummaryLength ?? DEFAULT_INLINE_SUMMARY_LENGTH,
@@ -1586,12 +2551,12 @@ var init_server = __esm({
           "retry_failed_agents",
           "Retry only the failed agents from a previous spawn_agents_parallel call. Pass the failed results array (with originalInput) directly.",
           {
-            failedResults: z5.array(z5.object({
-              index: z5.number(),
+            failedResults: z7.array(z7.object({
+              index: z7.number(),
               originalInput: spawnAgentInputSchema
             })).min(1).describe("Array of failed results with their original input configurations"),
-            overrides: z5.object({
-              preferredBackend: z5.enum(["claude", "codex", "gemini"]).optional()
+            overrides: z7.object({
+              preferredBackend: z7.enum(["claude", "codex", "gemini"]).optional()
             }).optional().describe("Parameter overrides applied to all retried agents")
           },
           async (params) => {
@@ -1611,7 +2576,10 @@ var init_server = __esm({
                 this.hooksEngine,
                 this.contextMonitor,
                 this.backendSelector,
-                this._childHttpUrl
+                this._childHttpUrl,
+                void 0,
+                this.agentEventStore,
+                this.hookMemoryDir
               );
               const controlOptions = {
                 inlineSummaryLength: this.inlineSummaryLength ?? DEFAULT_INLINE_SUMMARY_LENGTH,
@@ -1635,14 +2603,93 @@ var init_server = __esm({
           "list_sessions",
           "List relay sessions, optionally filtered by backend.",
           {
-            backend: z5.enum(["claude", "codex", "gemini"]).optional().describe("Filter sessions by backend type."),
-            limit: z5.number().optional().describe("Maximum number of sessions to return. Default: 10.")
+            backendId: z7.enum(["claude", "codex", "gemini"]).optional().describe("Filter sessions by backend type."),
+            backend: z7.enum(["claude", "codex", "gemini"]).optional().describe("Filter sessions by backend type."),
+            limit: z7.number().int().min(1).max(100).optional().describe("Maximum number of sessions to return. Default: 10."),
+            status: z7.enum(["active", "completed", "error"]).optional().describe("Filter sessions by status."),
+            taskId: z7.string().regex(TASK_ID_PATTERN).optional().describe("Filter by metadata.taskId."),
+            label: z7.string().optional().describe("Case-insensitive partial match for metadata.label."),
+            tags: z7.array(z7.string()).optional().describe("Filter sessions containing all provided tags."),
+            staleOnly: z7.boolean().optional().describe("When true, return only stale active sessions.")
           },
           async (params) => {
             try {
               const result = await executeListSessions(
-                { backend: params.backend, limit: params.limit ?? 10 },
-                this.sessionManager
+                {
+                  backendId: params.backendId,
+                  backend: params.backend,
+                  limit: params.limit ?? 10,
+                  status: params.status,
+                  taskId: params.taskId,
+                  label: params.label,
+                  tags: params.tags,
+                  staleOnly: params.staleOnly ?? false
+                },
+                this.sessionManager,
+                { staleThresholdSec: this.staleThresholdSec }
+              );
+              return {
+                content: [
+                  {
+                    type: "text",
+                    text: JSON.stringify(result, null, 2)
+                  }
+                ]
+              };
+            } catch (error) {
+              const message = error instanceof Error ? error.message : String(error);
+              return {
+                content: [{ type: "text", text: `Error: ${message}` }],
+                isError: true
+              };
+            }
+          }
+        );
+        server.tool(
+          "check_session_health",
+          "Check relay session health without side effects.",
+          checkSessionHealthInputSchema.shape,
+          async (params) => {
+            try {
+              const result = await executeCheckSessionHealth(
+                {
+                  sessionId: params.sessionId,
+                  includeCompleted: params.includeCompleted ?? false
+                },
+                this.sessionHealthMonitor
+              );
+              return {
+                content: [
+                  {
+                    type: "text",
+                    text: JSON.stringify(result, null, 2)
+                  }
+                ]
+              };
+            } catch (error) {
+              const message = error instanceof Error ? error.message : String(error);
+              return {
+                content: [{ type: "text", text: `Error: ${message}` }],
+                isError: true
+              };
+            }
+          }
+        );
+        server.tool(
+          "poll_agent_events",
+          "Poll agent lifecycle events using a cursor.",
+          pollAgentEventsInputSchema.shape,
+          async (params) => {
+            try {
+              const result = executePollAgentEvents(
+                {
+                  cursor: params.cursor,
+                  types: params.types,
+                  sessionId: params.sessionId,
+                  parentSessionId: params.parentSessionId,
+                  limit: params.limit ?? 50
+                },
+                this.agentEventStore
               );
               return {
                 content: [
@@ -1665,7 +2712,7 @@ var init_server = __esm({
           "get_context_status",
           "Get the context usage status of a relay session. Returns usage data from ContextMonitor when available, otherwise estimated values.",
           {
-            sessionId: z5.string().describe("Relay session ID to query context usage for.")
+            sessionId: z7.string().describe("Relay session ID to query context usage for.")
           },
           async (params) => {
             try {
@@ -1753,6 +2800,8 @@ var init_server = __esm({
         await new Promise((resolve3) => {
           httpServer.on("close", resolve3);
         });
+        this._httpServer = void 0;
+        await this.close();
       }
       /**
        * Start an HTTP server for child agents.
@@ -1781,7 +2830,7 @@ var init_server = __esm({
             sessionIdGenerator: () => randomUUID()
           });
           const server = new McpServer(
-            { name: "agentic-relay", version: "1.1.1" },
+            { name: "agentic-relay", version: "1.3.0" },
             createMcpServerOptions()
           );
           this.registerTools(server);
@@ -1826,6 +2875,17 @@ var init_server = __esm({
           });
         });
       }
+      async close() {
+        this.sessionHealthMonitor.stop();
+        this.agentEventStore.cleanup();
+        if (this._childHttpServer) {
+          await new Promise((resolve3) => {
+            this._childHttpServer.close(() => resolve3());
+          });
+          this._childHttpServer = void 0;
+          this._childHttpUrl = void 0;
+        }
+      }
       /** Exposed for testing and graceful shutdown */
       get httpServer() {
         return this._httpServer;
@@ -1837,8 +2897,8 @@ var init_server = __esm({
 
 // src/bin/relay.ts
 import { defineCommand as defineCommand10, runMain } from "citty";
-import { join as join10 } from "path";
-import { homedir as homedir6 } from "os";
+import { join as join11 } from "path";
+import { homedir as homedir7 } from "os";
 
 // src/infrastructure/process-manager.ts
 init_logger();
@@ -3179,7 +4239,9 @@ ${prompt}`;
 };
 
 // src/core/session-manager.ts
-import { readFile as readFile4, writeFile as writeFile4, readdir, mkdir as mkdir4, chmod } from "fs/promises";
+init_logger();
+init_metadata_validation();
+import { readFile as readFile4, writeFile as writeFile4, readdir, mkdir as mkdir4, chmod, rename, unlink } from "fs/promises";
 import { join as join4 } from "path";
 import { homedir as homedir4 } from "os";
 import { nanoid } from "nanoid";
@@ -3193,22 +4255,41 @@ function toSessionData(session) {
   return {
     ...session,
     createdAt: session.createdAt.toISOString(),
-    updatedAt: session.updatedAt.toISOString()
+    updatedAt: session.updatedAt.toISOString(),
+    lastHeartbeatAt: session.lastHeartbeatAt.toISOString(),
+    staleNotifiedAt: session.staleNotifiedAt?.toISOString() ?? null
   };
 }
 function fromSessionData(data) {
+  const createdAt = new Date(data.createdAt);
+  const updatedAt = new Date(data.updatedAt);
+  const fallbackHeartbeat = data.lastHeartbeatAt ?? data.createdAt ?? data.updatedAt;
+  const lastHeartbeatAt = new Date(fallbackHeartbeat);
+  const staleNotifiedAt = data.staleNotifiedAt ? new Date(data.staleNotifiedAt) : null;
   return {
     ...data,
-    createdAt: new Date(data.createdAt),
-    updatedAt: new Date(data.updatedAt)
+    createdAt,
+    updatedAt,
+    lastHeartbeatAt: Number.isNaN(lastHeartbeatAt.getTime()) ? updatedAt : lastHeartbeatAt,
+    staleNotifiedAt: staleNotifiedAt && !Number.isNaN(staleNotifiedAt.getTime()) ? staleNotifiedAt : null,
+    metadata: data.metadata && typeof data.metadata === "object" ? data.metadata : {}
   };
 }
 var SessionManager = class _SessionManager {
   static SESSION_ID_PATTERN = /^relay-[A-Za-z0-9_-]+$/;
+  static DEFAULT_STALE_THRESHOLD_MS = 3e5;
+  static PROTECTED_METADATA_KEYS = /* @__PURE__ */ new Set([
+    "taskId",
+    "parentTaskId",
+    "agentType"
+  ]);
   sessionsDir;
   constructor(sessionsDir) {
     this.sessionsDir = sessionsDir ?? getSessionsDir(getRelayHome());
   }
+  getSessionsDir() {
+    return this.sessionsDir;
+  }
   /** Ensure the sessions directory exists. */
   async ensureDir() {
     await mkdir4(this.sessionsDir, { recursive: true });
@@ -3219,6 +4300,54 @@ var SessionManager = class _SessionManager {
     }
     return join4(this.sessionsDir, `${relaySessionId}.json`);
   }
+  async writeSession(session) {
+    const filePath = this.sessionPath(session.relaySessionId);
+    const tempPath = `${filePath}.${nanoid()}.tmp`;
+    try {
+      await writeFile4(tempPath, JSON.stringify(toSessionData(session), null, 2), "utf-8");
+      await chmod(tempPath, 384);
+      await rename(tempPath, filePath);
+    } catch (error) {
+      await unlink(tempPath).catch(() => void 0);
+      throw error;
+    }
+  }
+  ensureValidTransition(currentStatus, nextStatus) {
+    if (currentStatus === nextStatus) {
+      return;
+    }
+    if (currentStatus === "completed" || currentStatus === "error") {
+      throw new Error(
+        `RELAY_INVALID_TRANSITION: ${currentStatus} -> ${nextStatus}`
+      );
+    }
+    if (currentStatus === "active" && nextStatus !== "completed" && nextStatus !== "error") {
+      throw new Error(
+        `RELAY_INVALID_TRANSITION: ${currentStatus} -> ${nextStatus}`
+      );
+    }
+  }
+  getLastActivityAtMs(session) {
+    return Math.max(
+      session.lastHeartbeatAt.getTime(),
+      session.updatedAt.getTime()
+    );
+  }
+  isStale(session, staleThresholdMs, now = Date.now()) {
+    if (session.status !== "active") return false;
+    return this.getLastActivityAtMs(session) + staleThresholdMs < now;
+  }
+  mergeMetadata(existing, updates) {
+    const merged = { ...existing };
+    for (const [key, value] of Object.entries(updates)) {
+      if (_SessionManager.PROTECTED_METADATA_KEYS.has(key) && Object.prototype.hasOwnProperty.call(existing, key)) {
+        logger.warn(`Attempted to overwrite protected metadata key: ${key}`);
+        continue;
+      }
+      merged[key] = value;
+    }
+    return merged;
+  }
   /** Create a new relay session. */
   async create(params) {
     await this.ensureDir();
@@ -3231,15 +4360,12 @@ var SessionManager = class _SessionManager {
       depth: params.depth ?? 0,
       createdAt: now,
       updatedAt: now,
-      status: "active"
+      status: "active",
+      lastHeartbeatAt: now,
+      staleNotifiedAt: null,
+      metadata: validateMetadata(params.metadata)
     };
-    const sessionFilePath = this.sessionPath(session.relaySessionId);
-    await writeFile4(
-      sessionFilePath,
-      JSON.stringify(toSessionData(session), null, 2),
-      "utf-8"
-    );
-    await chmod(sessionFilePath, 384);
+    await this.writeSession(session);
     return session;
   }
   /** Update an existing session. */
@@ -3248,18 +4374,38 @@ var SessionManager = class _SessionManager {
     if (!session) {
       throw new Error(`Session not found: ${relaySessionId}`);
     }
+    if (updates.status) {
+      this.ensureValidTransition(session.status, updates.status);
+    }
     const updated = {
       ...session,
       ...updates,
+      metadata: validateMetadata(
+        updates.metadata ? this.mergeMetadata(session.metadata, updates.metadata) : session.metadata
+      ),
       updatedAt: /* @__PURE__ */ new Date()
     };
-    const updateFilePath = this.sessionPath(relaySessionId);
-    await writeFile4(
-      updateFilePath,
-      JSON.stringify(toSessionData(updated), null, 2),
-      "utf-8"
-    );
-    await chmod(updateFilePath, 384);
+    await this.writeSession(updated);
+  }
+  /** Update heartbeat timestamp for an active session. */
+  async updateHeartbeat(relaySessionId) {
+    const session = await this.get(relaySessionId);
+    if (!session) {
+      throw new Error(`Session not found: ${relaySessionId}`);
+    }
+    if (session.status !== "active") {
+      throw new Error(
+        `RELAY_INVALID_TRANSITION: ${session.status} -> active`
+      );
+    }
+    const now = /* @__PURE__ */ new Date();
+    const updated = {
+      ...session,
+      lastHeartbeatAt: now,
+      staleNotifiedAt: null,
+      updatedAt: now
+    };
+    await this.writeSession(updated);
   }
   /** Get a session by relay session ID. */
   async get(relaySessionId) {
@@ -3294,6 +4440,31 @@ var SessionManager = class _SessionManager {
         if (filter?.backendId && session.backendId !== filter.backendId) {
           continue;
         }
+        if (filter?.status && session.status !== filter.status) {
+          continue;
+        }
+        if (filter?.taskId && session.metadata.taskId !== filter.taskId) {
+          continue;
+        }
+        if (filter?.label && filter.label.trim().length > 0) {
+          const target = (session.metadata.label ?? "").toLowerCase();
+          if (!target.includes(filter.label.toLowerCase())) {
+            continue;
+          }
+        }
+        if (filter?.tags && filter.tags.length > 0) {
+          const sessionTags = Array.isArray(session.metadata.tags) ? session.metadata.tags : [];
+          const hasAllTags = filter.tags.every((tag) => sessionTags.includes(tag));
+          if (!hasAllTags) {
+            continue;
+          }
+        }
+        if (filter?.staleOnly) {
+          const threshold = filter.staleThresholdMs ?? _SessionManager.DEFAULT_STALE_THRESHOLD_MS;
+          if (!this.isStale(session, threshold)) {
+            continue;
+          }
+        }
         sessions.push(session);
       } catch {
       }
@@ -3306,6 +4477,41 @@ var SessionManager = class _SessionManager {
     }
     return sessions;
   }
+  async listStale(thresholdMs) {
+    const activeSessions = await this.list({ status: "active" });
+    const now = Date.now();
+    return activeSessions.filter((session) => this.isStale(session, thresholdMs, now));
+  }
+  async delete(relaySessionId) {
+    const filePath = this.sessionPath(relaySessionId);
+    try {
+      await unlink(filePath);
+    } catch (error) {
+      if (error.code === "ENOENT") {
+        return;
+      }
+      throw error;
+    }
+  }
+  async cleanup(olderThanMs) {
+    const sessions = await this.list();
+    const now = Date.now();
+    const deletedSessionIds = [];
+    for (const session of sessions) {
+      if (session.status !== "completed" && session.status !== "error") {
+        continue;
+      }
+      if (session.updatedAt.getTime() + olderThanMs >= now) {
+        continue;
+      }
+      await this.delete(session.relaySessionId);
+      deletedSessionIds.push(session.relaySessionId);
+    }
+    return {
+      deletedCount: deletedSessionIds.length,
+      deletedSessionIds
+    };
+  }
 };
 
 // src/core/config-manager.ts
@@ -3328,7 +4534,10 @@ var hookEventSchema = z.enum([
   "on-error",
   "on-context-threshold",
   "pre-spawn",
-  "post-spawn"
+  "post-spawn",
+  "on-session-complete",
+  "on-session-error",
+  "on-session-stale"
 ]);
 var hookDefinitionSchema = z.object({
   event: hookEventSchema,
@@ -3350,7 +4559,8 @@ var hookChainSchema = z.object({
 });
 var hooksConfigSchema = z.object({
   definitions: z.array(hookDefinitionSchema),
-  chains: z.array(hookChainSchema).optional()
+  chains: z.array(hookChainSchema).optional(),
+  memoryDir: z.string().optional()
 });
 var backendContextConfigSchema = z.object({
   contextWindow: z.number().positive().optional(),
@@ -3365,18 +4575,38 @@ var relayConfigSchema = z.object({
     gemini: z.record(z.unknown()).optional()
   }).optional(),
   hooks: hooksConfigSchema.optional(),
+  sessionHealth: z.object({
+    enabled: z.boolean().optional(),
+    heartbeatIntervalSec: z.number().positive().optional(),
+    staleThresholdSec: z.number().positive().optional(),
+    cleanupAfterSec: z.number().positive().optional(),
+    maxActiveSessions: z.number().int().positive().optional(),
+    checkIntervalSec: z.number().positive().optional()
+  }).optional(),
   contextMonitor: z.object({
     enabled: z.boolean().optional(),
     thresholdPercent: z.number().min(0).max(100).optional(),
     notifyThreshold: z.number().positive().optional(),
     notifyPercent: z.number().min(0).max(100).optional(),
     notifyMethod: z.enum(["stderr", "hook"]).optional(),
+    thresholdLevels: z.object({
+      warning: z.number().min(0).max(100).optional(),
+      critical: z.number().min(0).max(100).optional(),
+      emergency: z.number().min(0).max(100).optional()
+    }).optional(),
     backends: z.object({
       claude: backendContextConfigSchema,
       codex: backendContextConfigSchema,
       gemini: backendContextConfigSchema
     }).optional()
   }).optional(),
+  eventStore: z.object({
+    backend: z.enum(["memory", "jsonl"]).optional(),
+    maxEvents: z.number().int().positive().optional(),
+    ttlSec: z.number().positive().optional(),
+    sessionDir: z.string().optional(),
+    eventsFileName: z.string().optional()
+  }).optional(),
   mcpServerMode: z.object({
     maxDepth: z.number().int().positive(),
     maxCallsPerSession: z.number().int().positive(),
@@ -3397,7 +4627,7 @@ function deepMerge(target, source) {
   for (const key of Object.keys(source)) {
     const sourceVal = source[key];
     const targetVal = result[key];
-    if (isPlainObject(sourceVal) && isPlainObject(targetVal)) {
+    if (isPlainObject2(sourceVal) && isPlainObject2(targetVal)) {
       result[key] = deepMerge(
         targetVal,
         sourceVal
@@ -3408,14 +4638,14 @@ function deepMerge(target, source) {
   }
   return result;
 }
-function isPlainObject(value) {
+function isPlainObject2(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value) && Object.getPrototypeOf(value) === Object.prototype;
 }
 function getByPath(obj, path2) {
   const parts = path2.split(".");
   let current = obj;
   for (const part of parts) {
-    if (!isPlainObject(current)) return void 0;
+    if (!isPlainObject2(current)) return void 0;
     current = current[part];
   }
   return current;
@@ -3425,7 +4655,7 @@ function setByPath(obj, path2, value) {
   let current = obj;
   for (let i = 0; i < parts.length - 1; i++) {
     const part = parts[i];
-    if (!isPlainObject(current[part])) {
+    if (!isPlainObject2(current[part])) {
       current[part] = {};
     }
     current = current[part];
@@ -3534,7 +4764,7 @@ var ConfigManager = class {
     try {
       const raw = await readFile5(filePath, "utf-8");
       const parsed = JSON.parse(raw);
-      if (!isPlainObject(parsed)) return {};
+      if (!isPlainObject2(parsed)) return {};
       return parsed;
     } catch {
       return {};
@@ -3678,7 +4908,7 @@ var HooksEngine = class _HooksEngine {
   }
   /** Load hook definitions from config and register listeners on EventBus */
   loadConfig(config) {
-    this.definitions = config.definitions.filter((def) => {
+    this.definitions = (config.definitions ?? []).filter((def) => {
       if (def.enabled === false) return false;
       try {
         this.validateCommand(def.command);
@@ -3906,13 +5136,17 @@ var DEFAULT_BACKEND_CONTEXT = {
   gemini: { contextWindow: 1048576, compactThreshold: 524288 }
 };
 var DEFAULT_NOTIFY_PERCENT = 70;
+var DEFAULT_CRITICAL_PERCENT = 85;
+var DEFAULT_EMERGENCY_PERCENT = 95;
 var DEFAULT_CONFIG = {
   enabled: true,
-  notifyMethod: "hook"
+  notifyMethod: "hook",
+  memoryDir: "./memory"
 };
 var ContextMonitor = class {
-  constructor(hooksEngine2, config) {
+  constructor(hooksEngine2, config, agentEventStore) {
     this.hooksEngine = hooksEngine2;
+    this.agentEventStore = agentEventStore;
     this.config = { ...DEFAULT_CONFIG, ...config };
     if (this.config.thresholdPercent !== void 0 && this.config.notifyPercent === void 0 && this.config.notifyThreshold === void 0) {
       this.config.notifyPercent = this.config.thresholdPercent;
@@ -3920,6 +5154,7 @@ var ContextMonitor = class {
   }
   config;
   usageMap = /* @__PURE__ */ new Map();
+  agentEventStore;
   /** Get backend context config, merging user overrides with defaults */
   getBackendConfig(backendId) {
     const defaults = DEFAULT_BACKEND_CONTEXT[backendId];
@@ -3935,19 +5170,60 @@ var ContextMonitor = class {
       return this.config.notifyThreshold;
     }
     const backendConfig = this.getBackendConfig(backendId);
-    const notifyPercent = this.config.notifyPercent ?? DEFAULT_NOTIFY_PERCENT;
+    const notifyPercent = this.config.thresholdLevels?.warning ?? this.config.notifyPercent ?? DEFAULT_NOTIFY_PERCENT;
     return Math.round(backendConfig.contextWindow * notifyPercent / 100);
   }
+  getWarningPercent(backendId) {
+    if (this.config.thresholdLevels?.warning !== void 0) {
+      return this.config.thresholdLevels.warning;
+    }
+    if (this.config.notifyThreshold !== void 0) {
+      const backendConfig = this.getBackendConfig(backendId);
+      if (backendConfig.contextWindow <= 0) return DEFAULT_NOTIFY_PERCENT;
+      return Math.round(
+        this.config.notifyThreshold / backendConfig.contextWindow * 100
+      );
+    }
+    return this.config.notifyPercent ?? DEFAULT_NOTIFY_PERCENT;
+  }
+  getThresholdLevels(backendId, contextWindow) {
+    const warningPercent = this.getWarningPercent(backendId);
+    const warningTokens = this.getNotifyThreshold(backendId);
+    const criticalPercent = this.config.thresholdLevels?.critical ?? DEFAULT_CRITICAL_PERCENT;
+    const emergencyPercent = this.config.thresholdLevels?.emergency ?? DEFAULT_EMERGENCY_PERCENT;
+    return [
+      ["warning", warningPercent, warningTokens],
+      [
+        "critical",
+        criticalPercent,
+        Math.round(contextWindow * criticalPercent / 100)
+      ],
+      [
+        "emergency",
+        emergencyPercent,
+        Math.round(contextWindow * emergencyPercent / 100)
+      ]
+    ];
+  }
+  isNotified(sessionId, level) {
+    const entry = this.usageMap.get(sessionId);
+    return entry?.notifiedLevels.has(level) ?? false;
+  }
+  markNotified(sessionId, level) {
+    const entry = this.usageMap.get(sessionId);
+    if (!entry) return;
+    entry.notifiedLevels.add(level);
+  }
   /** Update token usage for a session and check threshold */
-  updateUsage(sessionId, backendId, estimatedTokens) {
+  updateUsage(sessionId, backendId, estimatedTokens, sessionMetadata) {
     if (!this.config.enabled) return;
     const backendConfig = this.getBackendConfig(backendId);
     const contextWindow = backendConfig.contextWindow;
     const usagePercent = contextWindow > 0 ? Math.round(estimatedTokens / contextWindow * 100) : 0;
     const existing = this.usageMap.get(sessionId);
-    let wasNotified = existing?.notified ?? false;
+    let notifiedLevels = existing?.notifiedLevels ?? /* @__PURE__ */ new Set();
     if (existing && estimatedTokens < existing.estimatedTokens * 0.7) {
-      wasNotified = false;
+      notifiedLevels = /* @__PURE__ */ new Set();
     }
     this.usageMap.set(sessionId, {
       estimatedTokens,
@@ -3955,19 +5231,27 @@ var ContextMonitor = class {
       compactThreshold: backendConfig.compactThreshold,
       usagePercent,
       backendId,
-      notified: wasNotified
+      notifiedLevels,
+      sessionMetadata: sessionMetadata ?? existing?.sessionMetadata
     });
-    const notifyAt = this.getNotifyThreshold(backendId);
-    if (estimatedTokens >= notifyAt && !wasNotified) {
-      const entry = this.usageMap.get(sessionId);
-      entry.notified = true;
-      this.notify(
+    const levels = this.getThresholdLevels(backendId, contextWindow);
+    for (const [level, _thresholdPercent, thresholdTokens] of levels) {
+      if (estimatedTokens < thresholdTokens) {
+        continue;
+      }
+      if (this.isNotified(sessionId, level)) {
+        continue;
+      }
+      this.markNotified(sessionId, level);
+      this.notifyLevel(
         sessionId,
         backendId,
+        level,
         usagePercent,
         estimatedTokens,
         contextWindow,
-        backendConfig.compactThreshold
+        backendConfig.compactThreshold,
+        this.usageMap.get(sessionId)?.sessionMetadata
       );
     }
   }
@@ -3993,15 +5277,93 @@ var ContextMonitor = class {
   removeSession(sessionId) {
     this.usageMap.delete(sessionId);
   }
-  notify(sessionId, backendId, usagePercent, currentTokens, contextWindow, compactThreshold) {
+  setAgentEventStore(agentEventStore) {
+    this.agentEventStore = agentEventStore;
+  }
+  parseSaveResult(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+      return null;
+    }
+    const candidate = value;
+    if (typeof candidate.saved !== "boolean") {
+      return null;
+    }
+    const saveResult = { saved: candidate.saved };
+    if (typeof candidate.snapshotPath === "string") {
+      saveResult.snapshotPath = candidate.snapshotPath;
+    }
+    if (typeof candidate.error === "string") {
+      saveResult.error = candidate.error;
+    }
+    return saveResult;
+  }
+  extractSaveResult(results) {
+    for (let index = results.length - 1; index >= 0; index -= 1) {
+      const metadata = results[index]?.output.metadata;
+      const nested = this.parseSaveResult(
+        metadata?.saveResult
+      );
+      if (nested) {
+        return nested;
+      }
+      const topLevel = this.parseSaveResult(metadata);
+      if (topLevel) {
+        return topLevel;
+      }
+    }
+    const failed = results.find(
+      (result) => result.exitCode !== 0 || (result.stderr?.trim().length ?? 0) > 0
+    );
+    if (failed) {
+      return {
+        saved: false,
+        error: failed.stderr || `hook exited with code ${failed.exitCode}`
+      };
+    }
+    return { saved: false };
+  }
+  recordThresholdEvent(sessionId, backendId, level, usagePercent, currentTokens, contextWindow, compactThreshold, remainingBeforeCompact, saveResult, sessionMetadata) {
+    this.agentEventStore?.record({
+      type: "context-threshold",
+      sessionId,
+      backendId,
+      parentSessionId: void 0,
+      metadata: sessionMetadata ?? {},
+      data: {
+        usagePercent,
+        currentTokens,
+        contextWindow,
+        compactThreshold,
+        remainingBeforeCompact,
+        level,
+        thresholdLevel: level,
+        saveResult,
+        taskId: sessionMetadata?.taskId
+      }
+    });
+  }
+  notifyLevel(sessionId, backendId, level, usagePercent, currentTokens, contextWindow, compactThreshold, sessionMetadata) {
     const remainingBeforeCompact = Math.max(
       0,
       compactThreshold - currentTokens
     );
-    const warningMessage = `${backendId} session ${sessionId} at ${usagePercent}% (${currentTokens}/${contextWindow} tokens). Compact in ~${remainingBeforeCompact} tokens. Save your work state now.`;
+    const initialSaveResult = { saved: false };
+    const warningMessage = `${backendId} session ${sessionId} level=${level} at ${usagePercent}% (${currentTokens}/${contextWindow} tokens). Compact in ~${remainingBeforeCompact} tokens. Save your work state now.`;
     if (this.config.notifyMethod === "stderr") {
+      this.recordThresholdEvent(
+        sessionId,
+        backendId,
+        level,
+        usagePercent,
+        currentTokens,
+        contextWindow,
+        compactThreshold,
+        remainingBeforeCompact,
+        initialSaveResult,
+        sessionMetadata
+      );
       process.stderr.write(
-        `[relay] Context warning: ${warningMessage}
+        `[relay] Context ${level}: ${warningMessage}
 `
       );
     } else if (this.config.notifyMethod === "hook" && this.hooksEngine) {
@@ -4015,11 +5377,60 @@ var ContextMonitor = class {
           currentTokens,
           contextWindow,
           compactThreshold,
-          remainingBeforeCompact
+          remainingBeforeCompact,
+          level,
+          thresholdLevel: level,
+          taskId: sessionMetadata?.taskId,
+          label: sessionMetadata?.label,
+          agentType: sessionMetadata?.agentType,
+          saveResult: initialSaveResult,
+          memoryDir: this.config.memoryDir ?? "./memory"
         }
       };
-      void this.hooksEngine.emit("on-context-threshold", hookInput).catch(
-        (e) => logger.debug("Context threshold hook error:", e)
+      void this.hooksEngine.emit("on-context-threshold", hookInput).then((results) => {
+        const saveResult = this.extractSaveResult(results);
+        this.recordThresholdEvent(
+          sessionId,
+          backendId,
+          level,
+          usagePercent,
+          currentTokens,
+          contextWindow,
+          compactThreshold,
+          remainingBeforeCompact,
+          saveResult,
+          sessionMetadata
+        );
+      }).catch(
+        (e) => {
+          const errorMessage = e instanceof Error ? e.message : String(e);
+          this.recordThresholdEvent(
+            sessionId,
+            backendId,
+            level,
+            usagePercent,
+            currentTokens,
+            contextWindow,
+            compactThreshold,
+            remainingBeforeCompact,
+            { saved: false, error: errorMessage },
+            sessionMetadata
+          );
+          logger.debug("Context threshold hook error:", e);
+        }
+      );
+    } else {
+      this.recordThresholdEvent(
+        sessionId,
+        backendId,
+        level,
+        usagePercent,
+        currentTokens,
+        contextWindow,
+        compactThreshold,
+        remainingBeforeCompact,
+        initialSaveResult,
+        sessionMetadata
       );
     }
   }
@@ -4615,16 +6026,17 @@ function createMCPCommand(configManager2, registry2, sessionManager2, hooksEngin
           let guardConfig;
           let inlineSummaryLength;
           let responseOutputDir;
+          let relayConfig;
           try {
-            const config = await configManager2.getConfig();
-            if (config.mcpServerMode) {
+            relayConfig = await configManager2.getConfig();
+            if (relayConfig.mcpServerMode) {
               guardConfig = {
-                maxDepth: config.mcpServerMode.maxDepth ?? 5,
-                maxCallsPerSession: config.mcpServerMode.maxCallsPerSession ?? 20,
-                timeoutSec: config.mcpServerMode.timeoutSec ?? 86400
+                maxDepth: relayConfig.mcpServerMode.maxDepth ?? 5,
+                maxCallsPerSession: relayConfig.mcpServerMode.maxCallsPerSession ?? 20,
+                timeoutSec: relayConfig.mcpServerMode.timeoutSec ?? 86400
               };
-              inlineSummaryLength = config.mcpServerMode.inlineSummaryLength;
-              responseOutputDir = config.mcpServerMode.responseOutputDir;
+              inlineSummaryLength = relayConfig.mcpServerMode.inlineSummaryLength;
+              responseOutputDir = relayConfig.mcpServerMode.responseOutputDir;
             }
           } catch {
           }
@@ -4637,7 +6049,8 @@ function createMCPCommand(configManager2, registry2, sessionManager2, hooksEngin
             hooksEngine2,
             contextMonitor2,
             inlineSummaryLength,
-            responseOutputDir
+            responseOutputDir,
+            relayConfig
           );
           await server.start({ transport, port });
         }
@@ -4799,7 +6212,7 @@ function createVersionCommand(registry2) {
       description: "Show relay and backend versions"
     },
     async run() {
-      const relayVersion = "1.1.1";
+      const relayVersion = "1.3.0";
       console.log(`agentic-relay v${relayVersion}`);
       console.log("");
       console.log("Backends:");
@@ -4824,8 +6237,8 @@ function createVersionCommand(registry2) {
 // src/commands/doctor.ts
 import { defineCommand as defineCommand8 } from "citty";
 import { access, constants, readdir as readdir2 } from "fs/promises";
-import { join as join8 } from "path";
-import { homedir as homedir5 } from "os";
+import { join as join9 } from "path";
+import { homedir as homedir6 } from "os";
 import { execFile as execFile2 } from "child_process";
 import { promisify as promisify2 } from "util";
 var execFileAsync2 = promisify2(execFile2);
@@ -4885,8 +6298,8 @@ async function checkConfig(configManager2) {
   }
 }
 async function checkSessionsDir() {
-  const relayHome2 = process.env["RELAY_HOME"] ?? join8(homedir5(), ".relay");
-  const sessionsDir = join8(relayHome2, "sessions");
+  const relayHome2 = process.env["RELAY_HOME"] ?? join9(homedir6(), ".relay");
+  const sessionsDir = join9(relayHome2, "sessions");
   try {
     await access(sessionsDir, constants.W_OK);
     return {
@@ -4999,8 +6412,8 @@ async function checkBackendAuthEnv() {
   return results;
 }
 async function checkSessionsDiskUsage() {
-  const relayHome2 = process.env["RELAY_HOME"] ?? join8(homedir5(), ".relay");
-  const sessionsDir = join8(relayHome2, "sessions");
+  const relayHome2 = process.env["RELAY_HOME"] ?? join9(homedir6(), ".relay");
+  const sessionsDir = join9(relayHome2, "sessions");
   try {
     const entries = await readdir2(sessionsDir);
     const fileCount = entries.length;
@@ -5074,8 +6487,8 @@ function createDoctorCommand(registry2, configManager2) {
 init_logger();
 import { defineCommand as defineCommand9 } from "citty";
 import { mkdir as mkdir6, writeFile as writeFile6, access as access2, readFile as readFile6 } from "fs/promises";
-import { join as join9 } from "path";
-var DEFAULT_CONFIG2 = {
+import { join as join10 } from "path";
+var DEFAULT_CONFIG4 = {
   defaultBackend: "claude",
   backends: {},
   mcpServers: {}
@@ -5088,8 +6501,8 @@ function createInitCommand() {
     },
     async run() {
       const projectDir = process.cwd();
-      const relayDir = join9(projectDir, ".relay");
-      const configPath = join9(relayDir, "config.json");
+      const relayDir = join10(projectDir, ".relay");
+      const configPath = join10(relayDir, "config.json");
       try {
         await access2(relayDir);
         logger.info(
@@ -5101,11 +6514,11 @@ function createInitCommand() {
       await mkdir6(relayDir, { recursive: true });
       await writeFile6(
         configPath,
-        JSON.stringify(DEFAULT_CONFIG2, null, 2) + "\n",
+        JSON.stringify(DEFAULT_CONFIG4, null, 2) + "\n",
         "utf-8"
       );
       logger.success(`Created ${configPath}`);
-      const gitignorePath = join9(projectDir, ".gitignore");
+      const gitignorePath = join10(projectDir, ".gitignore");
       try {
         const gitignoreContent = await readFile6(gitignorePath, "utf-8");
         if (!gitignoreContent.includes(".relay/config.local.json")) {
@@ -5131,8 +6544,8 @@ registry.registerLazy("claude", () => new ClaudeAdapter(processManager));
 registry.registerLazy("codex", () => new CodexAdapter(processManager));
 registry.registerLazy("gemini", () => new GeminiAdapter(processManager));
 var sessionManager = new SessionManager();
-var relayHome = process.env["RELAY_HOME"] ?? join10(homedir6(), ".relay");
-var projectRelayDir = join10(process.cwd(), ".relay");
+var relayHome = process.env["RELAY_HOME"] ?? join11(homedir7(), ".relay");
+var projectRelayDir = join11(process.cwd(), ".relay");
 var configManager = new ConfigManager(relayHome, projectRelayDir);
 var authManager = new AuthManager(registry);
 var eventBus = new EventBus();
@@ -5143,13 +6556,16 @@ void configManager.getConfig().then((config) => {
     hooksEngine.loadConfig(config.hooks);
   }
   if (config.contextMonitor) {
-    contextMonitor = new ContextMonitor(hooksEngine, config.contextMonitor);
+    contextMonitor = new ContextMonitor(hooksEngine, {
+      ...config.contextMonitor,
+      memoryDir: config.hooks?.memoryDir
+    });
   }
 }).catch((e) => logger.debug("Config load failed:", e));
 var main = defineCommand10({
   meta: {
     name: "relay",
-    version: "1.1.1",
+    version: "1.3.0",
     description: "Unified CLI proxy for Claude Code, Codex CLI, and Gemini CLI"
   },
   subCommands: {