@agentmonitors/cli 0.4.0 → 0.6.0

package/dist/index.cjs

@@ -1218,7 +1218,7 @@ var require_command = __commonJS({
     init_cjs_shims();
     var EventEmitter2 = require("events").EventEmitter;
     var childProcess = require("child_process");
-    var path12 = require("path");
+    var path13 = require("path");
     var fs = require("fs");
     var process3 = require("process");
     var { Argument: Argument2, humanReadableArgName } = require_argument();
@@ -2231,9 +2231,9 @@ Expecting one of '${allowedValues.join("', '")}'`);
         let launchWithNode = false;
         const sourceExt = [".js", ".ts", ".tsx", ".mjs", ".cjs"];
         function findFile(baseDir, baseName) {
-          const localBin = path12.resolve(baseDir, baseName);
+          const localBin = path13.resolve(baseDir, baseName);
           if (fs.existsSync(localBin)) return localBin;
-          if (sourceExt.includes(path12.extname(baseName))) return void 0;
+          if (sourceExt.includes(path13.extname(baseName))) return void 0;
           const foundExt = sourceExt.find(
             (ext2) => fs.existsSync(`${localBin}${ext2}`)
           );
@@ -2251,17 +2251,17 @@ Expecting one of '${allowedValues.join("', '")}'`);
           } catch {
             resolvedScriptPath = this._scriptPath;
           }
-          executableDir = path12.resolve(
-            path12.dirname(resolvedScriptPath),
+          executableDir = path13.resolve(
+            path13.dirname(resolvedScriptPath),
             executableDir
           );
         }
         if (executableDir) {
           let localFile = findFile(executableDir, executableFile);
           if (!localFile && !subcommand._executableFile && this._scriptPath) {
-            const legacyName = path12.basename(
+            const legacyName = path13.basename(
               this._scriptPath,
-              path12.extname(this._scriptPath)
+              path13.extname(this._scriptPath)
             );
             if (legacyName !== this._name) {
               localFile = findFile(
@@ -2272,7 +2272,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
           }
           executableFile = localFile || executableFile;
         }
-        launchWithNode = sourceExt.includes(path12.extname(executableFile));
+        launchWithNode = sourceExt.includes(path13.extname(executableFile));
         let proc2;
         if (process3.platform !== "win32") {
           if (launchWithNode) {
@@ -3187,7 +3187,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
        * @return {Command}
        */
       nameFromFilename(filename) {
-        this._name = path12.basename(filename, path12.extname(filename));
+        this._name = path13.basename(filename, path13.extname(filename));
         return this;
       }
       /**
@@ -3201,9 +3201,9 @@ Expecting one of '${allowedValues.join("', '")}'`);
        * @param {string} [path]
        * @return {(string|null|Command)}
        */
-      executableDir(path13) {
-        if (path13 === void 0) return this._executableDir;
-        this._executableDir = path13;
+      executableDir(path14) {
+        if (path14 === void 0) return this._executableDir;
+        this._executableDir = path14;
         return this;
       }
       /**
@@ -10226,8 +10226,8 @@ var require_utils2 = __commonJS({
       }
       return ind;
     }
-    function removeDotSegments(path12) {
-      let input = path12;
+    function removeDotSegments(path13) {
+      let input = path13;
       const output = [];
       let nextSlash = -1;
       let len = 0;
@@ -10427,8 +10427,8 @@ var require_schemes = __commonJS({
         wsComponent.secure = void 0;
       }
       if (wsComponent.resourceName) {
-        const [path12, query] = wsComponent.resourceName.split("?");
-        wsComponent.path = path12 && path12 !== "/" ? path12 : void 0;
+        const [path13, query] = wsComponent.resourceName.split("?");
+        wsComponent.path = path13 && path13 !== "/" ? path13 : void 0;
         wsComponent.query = query;
         wsComponent.resourceName = void 0;
       }
@@ -13851,8 +13851,8 @@ var require_dist = __commonJS({
 
 // src/index.ts
 init_cjs_shims();
-var import_node_fs6 = require("fs");
-var import_node_path9 = require("path");
+var import_node_fs7 = require("fs");
+var import_node_path10 = require("path");
 var import_node_url4 = require("url");
 
 // ../../node_modules/.pnpm/commander@14.0.3/node_modules/commander/esm.mjs
@@ -13971,6 +13971,7 @@ Edit the file to configure your monitor, then run:`);
 
 // src/commands/validate.ts
 init_cjs_shims();
+var import_node_fs3 = require("fs");
 
 // ../../libs/core/dist/index.js
 init_cjs_shims();
@@ -14468,8 +14469,8 @@ function getErrorMap() {
 // ../../node_modules/.pnpm/zod@3.25.76/node_modules/zod/v3/helpers/parseUtil.js
 init_cjs_shims();
 var makeIssue = (params) => {
-  const { data, path: path12, errorMaps, issueData } = params;
-  const fullPath = [...path12, ...issueData.path || []];
+  const { data, path: path13, errorMaps, issueData } = params;
+  const fullPath = [...path13, ...issueData.path || []];
   const fullIssue = {
     ...issueData,
     path: fullPath
@@ -14589,11 +14590,11 @@ var errorUtil;
 
 // ../../node_modules/.pnpm/zod@3.25.76/node_modules/zod/v3/types.js
 var ParseInputLazyPath = class {
-  constructor(parent, value, path12, key) {
+  constructor(parent, value, path13, key) {
     this._cachedPath = [];
     this.parent = parent;
     this.data = value;
-    this._path = path12;
+    this._path = path13;
     this._key = key;
   }
   get path() {
@@ -22659,12 +22660,12 @@ var PathBase = class {
   /**
    * Get the Path object referenced by the string path, resolved from this Path
    */
-  resolve(path12) {
-    if (!path12) {
+  resolve(path13) {
+    if (!path13) {
       return this;
     }
-    const rootPath = this.getRootString(path12);
-    const dir = path12.substring(rootPath.length);
+    const rootPath = this.getRootString(path13);
+    const dir = path13.substring(rootPath.length);
     const dirParts = dir.split(this.splitSep);
     const result = rootPath ? this.getRoot(rootPath).#resolveParts(dirParts) : this.#resolveParts(dirParts);
     return result;
@@ -23416,8 +23417,8 @@ var PathWin32 = class _PathWin32 extends PathBase {
   /**
    * @internal
    */
-  getRootString(path12) {
-    return import_node_path2.win32.parse(path12).root;
+  getRootString(path13) {
+    return import_node_path2.win32.parse(path13).root;
   }
   /**
    * @internal
@@ -23463,8 +23464,8 @@ var PathPosix = class _PathPosix extends PathBase {
   /**
    * @internal
    */
-  getRootString(path12) {
-    return path12.startsWith("/") ? "/" : "";
+  getRootString(path13) {
+    return path13.startsWith("/") ? "/" : "";
   }
   /**
    * @internal
@@ -23553,11 +23554,11 @@ var PathScurryBase = class {
   /**
    * Get the depth of a provided path, string, or the cwd
    */
-  depth(path12 = this.cwd) {
-    if (typeof path12 === "string") {
-      path12 = this.cwd.resolve(path12);
+  depth(path13 = this.cwd) {
+    if (typeof path13 === "string") {
+      path13 = this.cwd.resolve(path13);
     }
-    return path12.depth();
+    return path13.depth();
   }
   /**
    * Return the cache of child entries.  Exposed so subclasses can create
@@ -24044,9 +24045,9 @@ var PathScurryBase = class {
     process3();
     return results;
   }
-  chdir(path12 = this.cwd) {
+  chdir(path13 = this.cwd) {
     const oldCwd = this.cwd;
-    this.cwd = typeof path12 === "string" ? this.cwd.resolve(path12) : path12;
+    this.cwd = typeof path13 === "string" ? this.cwd.resolve(path13) : path13;
     this.cwd[setAsCwd](oldCwd);
   }
 };
@@ -24408,8 +24409,8 @@ var MatchRecord = class {
   }
   // match, absolute, ifdir
   entries() {
-    return [...this.store.entries()].map(([path12, n]) => [
-      path12,
+    return [...this.store.entries()].map(([path13, n]) => [
+      path13,
       !!(n & 2),
       !!(n & 1)
     ]);
@@ -24614,9 +24615,9 @@ var GlobUtil = class {
   signal;
   maxDepth;
   includeChildMatches;
-  constructor(patterns, path12, opts) {
+  constructor(patterns, path13, opts) {
     this.patterns = patterns;
-    this.path = path12;
+    this.path = path13;
     this.opts = opts;
     this.#sep = !opts.posix && opts.platform === "win32" ? "\\" : "/";
     this.includeChildMatches = opts.includeChildMatches !== false;
@@ -24635,11 +24636,11 @@ var GlobUtil = class {
       });
     }
   }
-  #ignored(path12) {
-    return this.seen.has(path12) || !!this.#ignore?.ignored?.(path12);
+  #ignored(path13) {
+    return this.seen.has(path13) || !!this.#ignore?.ignored?.(path13);
   }
-  #childrenIgnored(path12) {
-    return !!this.#ignore?.childrenIgnored?.(path12);
+  #childrenIgnored(path13) {
+    return !!this.#ignore?.childrenIgnored?.(path13);
   }
   // backpressure mechanism
   pause() {
@@ -24854,8 +24855,8 @@ var GlobUtil = class {
 };
 var GlobWalker = class extends GlobUtil {
   matches = /* @__PURE__ */ new Set();
-  constructor(patterns, path12, opts) {
-    super(patterns, path12, opts);
+  constructor(patterns, path13, opts) {
+    super(patterns, path13, opts);
   }
   matchEmit(e) {
     this.matches.add(e);
@@ -24892,8 +24893,8 @@ var GlobWalker = class extends GlobUtil {
 };
 var GlobStream = class extends GlobUtil {
   results;
-  constructor(patterns, path12, opts) {
-    super(patterns, path12, opts);
+  constructor(patterns, path13, opts) {
+    super(patterns, path13, opts);
     this.results = new Minipass({
       signal: this.signal,
       objectMode: true
@@ -26401,7 +26402,7 @@ Subquery.prototype.getSQL = function() {
 function mapResultRow(columns, row, joinsNotNullableMap) {
   const nullifyMap = {};
   const result = columns.reduce(
-    (result2, { path: path12, field }, columnIndex) => {
+    (result2, { path: path13, field }, columnIndex) => {
       let decoder;
       if (is(field, Column)) {
         decoder = field;
@@ -26413,8 +26414,8 @@ function mapResultRow(columns, row, joinsNotNullableMap) {
         decoder = field.sql.decoder;
       }
       let node = result2;
-      for (const [pathChunkIndex, pathChunk] of path12.entries()) {
-        if (pathChunkIndex < path12.length - 1) {
+      for (const [pathChunkIndex, pathChunk] of path13.entries()) {
+        if (pathChunkIndex < path13.length - 1) {
           if (!(pathChunk in node)) {
             node[pathChunk] = {};
           }
@@ -26422,8 +26423,8 @@ function mapResultRow(columns, row, joinsNotNullableMap) {
         } else {
           const rawValue = row[columnIndex];
           const value = node[pathChunk] = rawValue === null ? null : decoder.mapFromDriverValue(rawValue);
-          if (joinsNotNullableMap && is(field, Column) && path12.length === 2) {
-            const objectName = path12[0];
+          if (joinsNotNullableMap && is(field, Column) && path13.length === 2) {
+            const objectName = path13[0];
             if (!(objectName in nullifyMap)) {
               nullifyMap[objectName] = value === null ? getTableName(field.table) : false;
             } else if (typeof nullifyMap[objectName] === "string" && nullifyMap[objectName] !== getTableName(field.table)) {
@@ -31375,14 +31376,19 @@ function assertValidSegment(path72, segment) {
     );
   }
 }
-function resolveDottedPath(root, path72) {
-  if (path72 === "$") return root;
-  if (!path72.startsWith("$.")) {
+function normalizeDottedPath(path72) {
+  if (path72 === "$" || path72.startsWith("$.")) return path72;
+  if (path72.startsWith("$")) {
     throw new Error(
-      `Invalid collection path "${path72}": must start with "$." (e.g. "$.tasks")`
+      `Invalid collection path "${path72}": a path beginning with "$" must be explicit-root form ("$" or "$.field"). Write "${path72.slice(1)}" for a bare root-relative path, or "$.${path72.slice(1)}" for explicit-root form.`
     );
   }
-  const segments = path72.slice(2).split(".");
+  return `$.${path72}`;
+}
+function resolveDottedPath(root, path72) {
+  const normalizedPath = normalizeDottedPath(path72);
+  if (normalizedPath === "$") return root;
+  const segments = normalizedPath.slice(2).split(".");
   let current = root;
   for (const segment of segments) {
     if (segment.length === 0) {
@@ -31397,13 +31403,9 @@ function resolveDottedPath(root, path72) {
   return current;
 }
 function removeDottedPath(value, path72) {
-  if (path72 === "$") return;
-  if (!path72.startsWith("$.")) {
-    throw new Error(
-      `Invalid ignore-paths entry "${path72}": must start with "$." (e.g. "$.fetchedAt")`
-    );
-  }
-  const segments = path72.slice(2).split(".");
+  const normalizedPath = normalizeDottedPath(path72);
+  if (normalizedPath === "$") return;
+  const segments = normalizedPath.slice(2).split(".");
   let current = value;
   for (let i = 0; i < segments.length - 1; i++) {
     const segment = segments[i];
@@ -31677,6 +31679,11 @@ function rowToEvent(row) {
     createdAt: row.createdAt
   };
 }
+function deliveryStateForRow(row) {
+  if (row.acknowledgedAt) return "acknowledged";
+  if (row.firstNotifiedAt) return "claimed";
+  return "unread";
+}
 function scopeMatches(eventScope, requested) {
   if (!requested) return true;
   for (const [key, value] of Object.entries(requested)) {
@@ -31844,6 +31851,13 @@ var RuntimeStore = class {
     if (query.objectKey)
       conditions.push(eq(monitorEvents.objectKey, query.objectKey));
     if (query.since) conditions.push(gt(monitorEvents.createdAt, query.since));
+    if (query.workspacePath !== void 0) {
+      const workspaceCondition = or(
+        eq(monitorEvents.workspacePath, query.workspacePath),
+        isNull(monitorEvents.workspacePath)
+      );
+      if (workspaceCondition) conditions.push(workspaceCondition);
+    }
     let rows = query.sessionId ? asInternalDb2(this.db).select({
       event: monitorEvents,
       state: sessionEventState
@@ -31918,6 +31932,37 @@ var RuntimeStore = class {
       createdAt: row.createdAt
     }));
   }
+  listDeliveryProjectionsForMonitor(monitorId, workspacePath) {
+    const conditions = [eq(monitorEvents.monitorId, monitorId)];
+    if (workspacePath !== void 0) {
+      const workspaceCondition = or(
+        eq(agentSessions.workspacePath, workspacePath),
+        isNull(agentSessions.workspacePath)
+      );
+      if (workspaceCondition) conditions.push(workspaceCondition);
+    }
+    const rows = asInternalDb2(this.db).select({
+      event: monitorEvents,
+      state: sessionEventState,
+      session: agentSessions
+    }).from(sessionEventState).innerJoin(monitorEvents, eq(sessionEventState.eventId, monitorEvents.id)).innerJoin(
+      agentSessions,
+      eq(sessionEventState.sessionId, agentSessions.id)
+    ).where(and(...conditions)).orderBy(desc(monitorEvents.createdAt)).all();
+    return rows.map(({ event, state, session }) => ({
+      eventId: event.id,
+      sessionId: session.id,
+      sessionRole: session.role,
+      sessionStatus: session.status,
+      deliveryState: deliveryStateForRow(state),
+      workspacePath: session.workspacePath ?? null,
+      createdAt: state.createdAt,
+      ...state.firstNotifiedAt ? { firstNotifiedAt: state.firstNotifiedAt } : {},
+      ...state.lastClaimAt ? { lastClaimAt: state.lastClaimAt } : {},
+      ...state.lastClaimLifecycle ? { lastClaimLifecycle: state.lastClaimLifecycle } : {},
+      ...state.acknowledgedAt ? { acknowledgedAt: state.acknowledgedAt } : {}
+    }));
+  }
   sessionsForWorkspace(workspacePath) {
     return asInternalDb2(this.db).select().from(agentSessions).where(
       workspacePath == null ? isNull(agentSessions.workspacePath) : or(
@@ -32025,6 +32070,14 @@ var DEFAULT_FILE_FINGERPRINT_POLL_MS = 3e4;
 var DEFAULT_API_POLL_MS = 3e5;
 var DEFAULT_HIGH_URGENCY_SETTLE_MS = 15e3;
 var MAX_RECAP_EVENTS = 10;
+var EXPLAIN_STAGE_LABELS = {
+  definition: "Definition",
+  scheduling: "Scheduling",
+  observation: "Observation",
+  notify: "Notify state",
+  materialization: "Materialization",
+  delivery: "Projection and delivery"
+};
 function watchConfig(watch) {
   const { type: _type, ...config2 } = watch;
   return config2;
@@ -32043,6 +32096,28 @@ function writeJsonAtomic(filePath2, payload) {
   (0, import_fs3.writeFileSync)(tmpPath, JSON.stringify(payload, null, 2), "utf-8");
   (0, import_fs3.renameSync)(tmpPath, filePath2);
 }
+function monitorIdFromFilePath(filePath2) {
+  const base = import_path4.default.basename(filePath2);
+  return base === "MONITOR.md" ? import_path4.default.basename(import_path4.default.dirname(filePath2)) : import_path4.default.parse(filePath2).name;
+}
+function explainStage(id, status, reason, details) {
+  return {
+    id,
+    label: EXPLAIN_STAGE_LABELS[id],
+    status,
+    reason,
+    ...details ? { details } : {}
+  };
+}
+function explainVerdict(stages) {
+  const stopped = stages.find((stage2) => stage2.status !== "ok");
+  const stage = stopped ?? stages[stages.length - 1];
+  return {
+    status: stage?.status ?? "ok",
+    stage: stage?.id ?? "delivery",
+    reason: stage?.reason ?? "Monitor delivered successfully."
+  };
+}
 function serializeObservation(monitor, observation, observedAt) {
   return { monitor, observation, observedAt };
 }
@@ -32157,6 +32232,320 @@ var AgentMonitorRuntime = class {
   listObservationHistory(query = {}) {
     return this.store.listObservationHistory(query);
   }
+  async explainMonitor(input) {
+    const now = input.now ?? /* @__PURE__ */ new Date();
+    const historyLimit = input.historyLimit ?? 10;
+    const eventLimit = input.eventLimit ?? 10;
+    const stages = [];
+    const scan = await scanMonitors(input.monitorsDir);
+    const parseError = scan.errors.find(
+      (error2) => monitorIdFromFilePath(error2.filePath) === input.monitorId
+    );
+    const monitor = scan.monitors.find(
+      (candidate) => candidate.monitor.id === input.monitorId
+    )?.monitor;
+    const duplicate = scan.duplicateIds.find(
+      (candidate) => candidate.id === input.monitorId
+    );
+    if (parseError) {
+      stages.push(
+        explainStage(
+          "definition",
+          "failure",
+          `MONITOR.md failed to parse or validate: ${parseError.error}`,
+          { filePath: parseError.filePath }
+        )
+      );
+      return {
+        monitorId: input.monitorId,
+        generatedAt: now,
+        stages,
+        verdict: explainVerdict(stages),
+        observations: [],
+        events: [],
+        projections: [],
+        leadSessions: []
+      };
+    }
+    if (!monitor) {
+      stages.push(
+        explainStage(
+          "definition",
+          "failure",
+          `Monitor "${input.monitorId}" was not found in ${input.monitorsDir}.`
+        )
+      );
+      return {
+        monitorId: input.monitorId,
+        generatedAt: now,
+        stages,
+        verdict: explainVerdict(stages),
+        observations: [],
+        events: [],
+        projections: [],
+        leadSessions: []
+      };
+    }
+    if (duplicate) {
+      stages.push(
+        explainStage(
+          "definition",
+          "failure",
+          `Monitor id "${input.monitorId}" is duplicated across ${String(duplicate.filePaths.length)} files.`,
+          { filePaths: duplicate.filePaths }
+        )
+      );
+      return {
+        monitorId: input.monitorId,
+        generatedAt: now,
+        monitor: {
+          id: monitor.id,
+          displayName: monitor.displayName,
+          filePath: monitor.filePath,
+          sourceName: monitor.frontmatter.watch.type,
+          urgency: monitor.frontmatter.urgency
+        },
+        stages,
+        verdict: explainVerdict(stages),
+        observations: [],
+        events: [],
+        projections: [],
+        leadSessions: []
+      };
+    }
+    const sourceName = monitor.frontmatter.watch.type;
+    const source6 = this.registry.get(sourceName);
+    const scopeErrors = source6 ? validateScope(
+      watchConfig(monitor.frontmatter.watch),
+      source6.scopeSchema
+    ) : [`Unknown source "${sourceName}".`];
+    if (scopeErrors.length > 0) {
+      stages.push(
+        explainStage(
+          "definition",
+          "failure",
+          `Monitor definition is invalid: ${scopeErrors.join("; ")}`,
+          { filePath: monitor.filePath, sourceName }
+        )
+      );
+      return {
+        monitorId: input.monitorId,
+        generatedAt: now,
+        monitor: {
+          id: monitor.id,
+          displayName: monitor.displayName,
+          filePath: monitor.filePath,
+          sourceName,
+          urgency: monitor.frontmatter.urgency
+        },
+        stages,
+        verdict: explainVerdict(stages),
+        observations: [],
+        events: [],
+        projections: [],
+        leadSessions: []
+      };
+    }
+    stages.push(
+      explainStage("definition", "ok", "Monitor definition is valid.", {
+        filePath: monitor.filePath,
+        sourceName
+      })
+    );
+    const runtimeState = this.store.getMonitorState(input.monitorId);
+    const schedule = this.scheduleForMonitor(monitor, now);
+    const lastObservationAt = runtimeState.lastObservationAt;
+    const nextDueAt = schedule.due ? now : new Date(
+      (lastObservationAt?.getTime() ?? now.getTime()) + schedule.nextPollMs
+    );
+    stages.push(
+      explainStage(
+        "scheduling",
+        "ok",
+        lastObservationAt ? `Last tick completed at ${lastObservationAt.toISOString()}; next due ${schedule.due ? "now" : nextDueAt.toISOString()}.` : "No completed tick is recorded yet; the monitor is due on the next daemon tick.",
+        {
+          due: schedule.due,
+          nextPollMs: schedule.nextPollMs,
+          nextDueAt: nextDueAt.toISOString(),
+          ...lastObservationAt ? { lastObservationAt: lastObservationAt.toISOString() } : {}
+        }
+      )
+    );
+    const observations = this.store.listObservationHistory({
+      monitorId: input.monitorId,
+      limit: historyLimit
+    });
+    const latestObservation = observations[0];
+    if (!latestObservation) {
+      stages.push(
+        explainStage(
+          "observation",
+          "failure",
+          "No observation history has been recorded for this monitor."
+        )
+      );
+    } else if (latestObservation.result === "errored") {
+      stages.push(
+        explainStage(
+          "observation",
+          "failure",
+          "The most recent source observation errored.",
+          latestObservation.observationData
+        )
+      );
+    } else if (latestObservation.result === "no-change") {
+      stages.push(
+        explainStage(
+          "observation",
+          "healthy",
+          "Source ran, observed 0 changes \u2014 your watched target genuinely hasn\u2019t changed (not a bug).",
+          latestObservation.observationData
+        )
+      );
+    } else if (latestObservation.result === "rebaselined") {
+      stages.push(
+        explainStage(
+          "observation",
+          "healthy",
+          "Source rebaselined and emitted no change \u2014 your watched target is being tracked, nothing to report (not a bug).",
+          latestObservation.observationData
+        )
+      );
+    } else {
+      stages.push(
+        explainStage(
+          "observation",
+          "ok",
+          `The latest observation outcome was ${latestObservation.result}.`,
+          latestObservation.observationData
+        )
+      );
+    }
+    const observationHealthy = latestObservation?.result === "no-change" || latestObservation?.result === "rebaselined";
+    const notifyState = runtimeState.notifyState;
+    const pendingDebounce = notifyState.pendingDebounce;
+    const suppressedUntil = notifyState.suppressedUntil ? new Date(notifyState.suppressedUntil) : null;
+    if (pendingDebounce && new Date(pendingDebounce.dueAt) > now) {
+      stages.push(
+        explainStage(
+          "notify",
+          "pending",
+          `debounce is holding ${String(pendingDebounce.observations.length)} observation(s) until ${pendingDebounce.dueAt}.`,
+          {
+            dueAt: pendingDebounce.dueAt,
+            observations: pendingDebounce.observations.length
+          }
+        )
+      );
+    } else if (suppressedUntil && suppressedUntil > now) {
+      stages.push(
+        explainStage(
+          "notify",
+          "pending",
+          `throttle is suppressing new notifications until ${suppressedUntil.toISOString()}.`,
+          { suppressedUntil: suppressedUntil.toISOString() }
+        )
+      );
+    } else {
+      stages.push(
+        explainStage(
+          "notify",
+          "ok",
+          "No debounce or throttle hold is currently active."
+        )
+      );
+    }
+    const events = this.store.listEvents({
+      monitorId: input.monitorId,
+      // Scope to the explained workspace so a same-id monitor in another
+      // workspace cannot leak its events into this report (issue #94 review).
+      ...input.workspacePath !== void 0 ? { workspacePath: input.workspacePath } : {}
+    }).slice(0, eventLimit);
+    if (events.length === 0) {
+      stages.push(
+        observationHealthy ? explainStage(
+          "materialization",
+          "healthy",
+          "No events materialized \u2014 expected, because the source observed no changes (not a bug)."
+        ) : explainStage(
+          "materialization",
+          "failure",
+          "No monitor_events rows exist for this monitor."
+        )
+      );
+    } else {
+      stages.push(
+        explainStage(
+          "materialization",
+          "ok",
+          `${String(events.length)} recent monitor_events row(s) found.`,
+          { eventIds: events.map((event) => event.id) }
+        )
+      );
+    }
+    const projections = this.store.listDeliveryProjectionsForMonitor(
+      input.monitorId,
+      // Scope to the explained workspace's sessions (plus global sessions) so
+      // projections from other workspaces are not overcounted (issue #94 review).
+      input.workspacePath
+    );
+    const leadSessions = this.store.sessionsForWorkspace(input.workspacePath).filter((session) => session.role === "lead");
+    if (events.length > 0 && projections.length === 0) {
+      stages.push(
+        explainStage(
+          "delivery",
+          "failure",
+          leadSessions.length === 0 ? "No lead session is registered for this workspace, so events were not projected." : "No session_event_state projections exist for the materialized events.",
+          { leadSessions: leadSessions.map((session) => session.id) }
+        )
+      );
+    } else if (events.length > 0) {
+      const counts = projections.reduce(
+        (acc, projection) => {
+          acc[projection.deliveryState] = (acc[projection.deliveryState] ?? 0) + 1;
+          return acc;
+        },
+        {}
+      );
+      stages.push(
+        explainStage(
+          "delivery",
+          "ok",
+          `Events are projected to lead sessions (${Object.entries(counts).map(([state, count]) => `${state}: ${String(count)}`).join(", ")}).`,
+          counts
+        )
+      );
+    } else {
+      stages.push(
+        observationHealthy ? explainStage(
+          "delivery",
+          "healthy",
+          "Nothing to deliver \u2014 the source observed no changes, so there is no signal to project (not a bug)."
+        ) : explainStage(
+          "delivery",
+          "pending",
+          "Delivery has not started because no event has materialized yet."
+        )
+      );
+    }
+    return {
+      monitorId: input.monitorId,
+      generatedAt: now,
+      monitor: {
+        id: monitor.id,
+        displayName: monitor.displayName,
+        filePath: monitor.filePath,
+        sourceName,
+        urgency: monitor.frontmatter.urgency
+      },
+      stages,
+      verdict: explainVerdict(stages),
+      observations,
+      events,
+      projections,
+      leadSessions
+    };
+  }
   acknowledgeSession(sessionId, eventIds) {
     const ids = eventIds ?? this.store.unreadEventsForSession(sessionId).map((e) => e.id);
     this.store.acknowledgeEvents(sessionId, ids);
@@ -32301,6 +32690,7 @@ var AgentMonitorRuntime = class {
     const now = /* @__PURE__ */ new Date();
     const emittedEventIds = [];
     const evaluated = [];
+    const erroredObservations = [];
     for (const parsed of result.monitors) {
       const monitor = parsed.monitor;
       const sourceName = monitor.frontmatter.watch.type;
@@ -32325,13 +32715,15 @@ var AgentMonitorRuntime = class {
           }
         );
       } catch (observeError) {
+        const message = observeError instanceof Error ? observeError.message : String(observeError);
+        erroredObservations.push({ monitorId: monitor.id, message });
         try {
           this.store.recordObservationHistory({
             monitorId: monitor.id,
             sourceName,
             result: "errored",
             observationData: {
-              error: observeError instanceof Error ? observeError.message : String(observeError)
+              error: message
             }
           });
         } catch {
@@ -32347,13 +32739,15 @@ var AgentMonitorRuntime = class {
           })
         );
       } catch (ingestError) {
+        const message = ingestError instanceof Error ? ingestError.message : String(ingestError);
+        erroredObservations.push({ monitorId: monitor.id, message });
         try {
           this.store.recordObservationHistory({
             monitorId: monitor.id,
             sourceName,
             result: "errored",
             observationData: {
-              error: ingestError instanceof Error ? ingestError.message : String(ingestError)
+              error: message
             }
           });
         } catch {
@@ -32361,7 +32755,11 @@ var AgentMonitorRuntime = class {
       }
     }
     this.refreshWorkspaceSessions(workspacePath);
-    return { evaluatedMonitors: evaluated, emittedEventIds };
+    return {
+      evaluatedMonitors: evaluated,
+      emittedEventIds,
+      erroredObservations
+    };
   }
   /**
    * Funnel a batch of observations through notify dispatch, persist the updated
@@ -32969,7 +33367,7 @@ var scopeSchema2 = {
           properties: {
             path: {
               type: "string",
-              description: 'Dotted $.-path to the array within the parsed JSON (e.g. "$.tasks")'
+              description: 'Dotted path to the array within the parsed JSON (e.g. "tasks" or "$.tasks")'
             },
             key: {
               type: "string",
@@ -32978,7 +33376,7 @@ var scopeSchema2 = {
             "ignore-paths": {
               type: "array",
               items: { type: "string" },
-              description: "Dotted $.-paths (relative to each element) removed before comparison"
+              description: 'Dotted paths (relative to each element, e.g. "fetchedAt" or "$.fetchedAt") removed before comparison'
             }
           },
           required: ["path", "key"]
@@ -33076,6 +33474,12 @@ function parseScopeConfig3(config2) {
   const cd = config2["change-detection"];
   const rawStrategy = cd?.strategy;
   const strategy = rawStrategy === "json-diff" || rawStrategy === "exit-code" ? rawStrategy : "text-diff";
+  const ignorePaths = parseTopLevelIgnorePaths(cd);
+  if (ignorePaths.length > 0 && strategy !== "json-diff") {
+    throw new Error(
+      "change-detection.ignore-paths requires strategy: json-diff"
+    );
+  }
   const collection = parseKeyedCollectionConfig(config2["change-detection"]);
   if (collection && strategy !== "json-diff") {
     throw new Error("change-detection.collection requires strategy: json-diff");
@@ -33087,7 +33491,16 @@ function parseScopeConfig3(config2) {
   const timeoutMs = typeof rawTimeout === "string" ? parseDuration(rawTimeout) : DEFAULT_TIMEOUT_MS;
   const key = config2["key"];
   const objectKey = typeof key === "string" && key.length > 0 ? key : command.join(" ");
-  return { command, cwd, env, timeoutMs, objectKey, strategy, collection };
+  return {
+    command,
+    cwd,
+    env,
+    timeoutMs,
+    objectKey,
+    strategy,
+    ignorePaths,
+    collection
+  };
 }
 async function runCommand(scope) {
   return new Promise((resolve) => {
@@ -33173,18 +33586,75 @@ function sortKeys3(value) {
   }
   return value;
 }
-function hasChanged2(strategy, prev, curr) {
+function parseTopLevelIgnorePaths(changeDetection) {
+  const rawIgnorePaths = changeDetection?.["ignore-paths"];
+  if (rawIgnorePaths === void 0) return [];
+  if (!Array.isArray(rawIgnorePaths) || !rawIgnorePaths.every((entry) => typeof entry === "string")) {
+    throw new Error(
+      "change-detection.ignore-paths must be an array of strings"
+    );
+  }
+  return rawIgnorePaths;
+}
+function normalizeJsonPath(path13) {
+  if (path13 === "$" || path13.startsWith("$.")) return path13;
+  return `$.${path13}`;
+}
+function assertValidJsonPathSegment(path13, segment) {
+  if (segment.length === 0) {
+    throw new Error(
+      `Invalid change-detection.ignore-paths entry "${path13}": empty path segment`
+    );
+  }
+  if (/[.[\]*?]/.test(segment)) {
+    throw new Error(
+      `Invalid change-detection.ignore-paths entry "${path13}": unsupported path segment "${segment}"`
+    );
+  }
+}
+function stripIgnoredJsonPaths(value, ignorePaths) {
+  if (ignorePaths.length === 0) return value;
+  const cloned = structuredClone(value);
+  for (const path13 of ignorePaths) {
+    removeJsonPath(cloned, path13);
+  }
+  return cloned;
+}
+function removeJsonPath(value, path13) {
+  const normalizedPath = normalizeJsonPath(path13);
+  if (normalizedPath === "$") return;
+  const segments = normalizedPath.slice(2).split(".");
+  let current = value;
+  for (let i = 0; i < segments.length - 1; i++) {
+    const segment = segments[i];
+    assertValidJsonPathSegment(path13, segment ?? "");
+    if (current === null || typeof current !== "object") return;
+    if (!Object.hasOwn(current, segment ?? "")) return;
+    current = current[segment ?? ""];
+  }
+  const last = segments.at(-1) ?? "";
+  assertValidJsonPathSegment(path13, last);
+  if (current !== null && typeof current === "object") {
+    Reflect.deleteProperty(current, last);
+  }
+}
+function hasChanged2(strategy, ignorePaths, prev, curr) {
   switch (strategy) {
     case "exit-code":
       return prev.exitCode !== curr.exitCode;
-    case "json-diff":
+    case "json-diff": {
+      let prevParsed;
+      let currParsed;
       try {
-        const prevJson = JSON.stringify(sortKeys3(JSON.parse(prev.stdout)));
-        const currJson = JSON.stringify(sortKeys3(JSON.parse(curr.stdout)));
-        return prevJson !== currJson;
+        prevParsed = JSON.parse(prev.stdout);
+        currParsed = JSON.parse(curr.stdout);
       } catch {
         return prev.stdout !== curr.stdout;
       }
+      return JSON.stringify(
+        sortKeys3(stripIgnoredJsonPaths(prevParsed, ignorePaths))
+      ) !== JSON.stringify(sortKeys3(stripIgnoredJsonPaths(currParsed, ignorePaths)));
+    }
     case "text-diff":
       return prev.stdout !== curr.stdout;
   }
@@ -33266,7 +33736,7 @@ var scopeSchema3 = {
           properties: {
             path: {
               type: "string",
-              description: 'Dotted $.-path to the array within the parsed JSON (e.g. "$.tasks")'
+              description: 'Dotted path to the array within the parsed JSON (e.g. "tasks" or "$.tasks")'
             },
             key: {
               type: "string",
@@ -33275,20 +33745,38 @@ var scopeSchema3 = {
             "ignore-paths": {
               type: "array",
               items: { type: "string" },
-              description: "Dotted $.-paths (relative to each element) removed before comparison"
+              description: 'Dotted paths (relative to each element, e.g. "fetchedAt" or "$.fetchedAt") removed before comparison'
             }
           },
-          required: ["path", "key"]
+          required: ["path", "key"],
+          additionalProperties: false
+        },
+        "ignore-paths": {
+          type: "array",
+          items: { type: "string" },
+          description: "Dotted paths removed from parsed JSON before plain json-diff comparison"
         }
       },
+      additionalProperties: false,
       // BP3: change-detection.collection requires strategy: json-diff. Under any
       // other strategy (or the defaulted text-diff), presence of `collection` is an
       // authoring-time error.
-      if: { required: ["collection"] },
-      then: {
-        properties: { strategy: { const: "json-diff" } },
-        required: ["strategy"]
-      }
+      allOf: [
+        {
+          if: { required: ["collection"] },
+          then: {
+            properties: { strategy: { const: "json-diff" } },
+            required: ["strategy"]
+          }
+        },
+        {
+          if: { required: ["ignore-paths"] },
+          then: {
+            properties: { strategy: { const: "json-diff" } },
+            required: ["strategy"]
+          }
+        }
+      ]
     }
   },
   required: ["command"]
@@ -33353,7 +33841,7 @@ var source3 = {
       health: "ok",
       baselined: true
     };
-    if (prev !== void 0 && hadBaseline && hasChanged2(scope.strategy, prev, result)) {
+    if (prev !== void 0 && hadBaseline && hasChanged2(scope.strategy, scope.ignorePaths, prev, result)) {
       observations.push(changedObservation(scope, result));
     }
     return { observations, nextState };
@@ -33696,6 +34184,23 @@ function changeDetectionCollectionError(watchConfig2) {
   if (strategy === "json-diff") return void 0;
   return "change-detection.collection requires strategy: json-diff";
 }
+function oldSourceScopeShapeHint(filePath2) {
+  let content;
+  try {
+    content = (0, import_node_fs3.readFileSync)(filePath2, "utf-8");
+  } catch {
+    return null;
+  }
+  const normalised = content.replace(/^\uFEFF/, "").replace(/\r\n/g, "\n");
+  const frontmatter = /^---\n(?<frontmatter>[\s\S]*?)\n---/.exec(normalised)?.groups?.["frontmatter"];
+  if (!frontmatter) return null;
+  const rawSource = /^source:\s*(?<source>[^\n#]+)/m.exec(frontmatter)?.groups?.["source"];
+  const source6 = rawSource?.trim().replace(/^['"]|['"]$/g, "");
+  const hasScope = /^scope\s*:/m.test(frontmatter);
+  const hasWatch = /^watch\s*:/m.test(frontmatter);
+  if (!source6 || !hasScope || hasWatch) return null;
+  return `did you mean to use the current watch shape? Move source/scope into watch:, for example: watch: { type: ${source6}, ... }`;
+}
 var validateCommand = new Command("validate").description("Validate MONITOR.md files in a directory").argument("[path]", "Path to monitors directory", ".claude/monitors").addOption(
   new Option("--format <format>", "Output format").choices(["text", "json"]).default("text")
 ).action(async (monitorPath, options2) => {
@@ -33728,12 +34233,12 @@ var validateCommand = new Command("validate").description("Validate MONITOR.md f
   });
   const duplicateErrors = result.duplicateIds.map((dup) => ({
     filePath: dup.filePaths.join(", "),
-    error: `Duplicate monitor id "${dup.id}" \u2014 ids are derived from folder names and must be unique within a tree`
+    error: `Duplicate monitor id "${dup.id}" -- ids are derived from folder names and must be unique within a tree`
   }));
   const allErrors = [
     ...result.errors.map((e) => ({
       filePath: e.filePath,
-      error: e.error
+      error: [e.error, oldSourceScopeShapeHint(e.filePath)].filter(Boolean).join("; ")
     })),
     ...scopeErrors.map((e) => ({
       filePath: e.id,
@@ -33983,19 +34488,14 @@ inboxCommand.command("archive").description("Archive a completed or failed inbox
 
 // src/commands/monitor-test.ts
 init_cjs_shims();
-var import_node_fs4 = require("fs");
+var import_node_path5 = __toESM(require("path"), 1);
+var import_node_fs5 = require("fs");
 var import_promises4 = require("timers/promises");
 
-// src/runtime-client.ts
-init_cjs_shims();
-
-// src/runtime.ts
-init_cjs_shims();
-
 // src/daemon-ipc.ts
 init_cjs_shims();
 var import_node_crypto = require("crypto");
-var import_node_fs3 = require("fs");
+var import_node_fs4 = require("fs");
 var import_node_os2 = require("os");
 var import_node_path4 = __toESM(require("path"), 1);
 var import_node_net = __toESM(require("net"), 1);
@@ -34018,6 +34518,7 @@ var daemonMethodSchema = external_exports.enum([
   "events.ack",
   "hook.claim",
   "history.list",
+  "monitor.explain",
   "daemon.tick"
 ]);
 var daemonResponseSchema = external_exports.object({
@@ -34066,6 +34567,13 @@ var historyListParamsSchema = external_exports.object({
   monitorId: external_exports.string().optional(),
   limit: external_exports.number().int().positive().optional()
 });
+var monitorExplainParamsSchema = external_exports.object({
+  monitorId: external_exports.string(),
+  monitorsDir: external_exports.string(),
+  workspacePath: external_exports.string().optional(),
+  historyLimit: external_exports.number().int().positive().optional(),
+  eventLimit: external_exports.number().int().positive().optional()
+});
 var daemonTickParamsSchema = external_exports.object({
   monitorsDir: external_exports.string(),
   workspacePath: external_exports.string().optional()
@@ -34075,6 +34583,13 @@ var daemonRequestSchema = external_exports.object({
   method: daemonMethodSchema,
   params: external_exports.record(external_exports.string(), external_exports.unknown())
 });
+var DaemonConnectionError = class extends Error {
+  constructor(message, cause) {
+    super(message);
+    this.cause = cause;
+  }
+  name = "DaemonConnectionError";
+};
 function isErrnoException(error2) {
   return typeof error2 === "object" && error2 !== null && "code" in error2;
 }
@@ -34095,7 +34610,7 @@ function resolveSocketPath(overridePath) {
 }
 function cleanupSocket(socketPath) {
   try {
-    (0, import_node_fs3.rmSync)(socketPath);
+    (0, import_node_fs4.rmSync)(socketPath);
   } catch (error2) {
     const code = isErrnoException(error2) ? String(error2.code) : "";
     if (code !== "ENOENT") throw error2;
@@ -34136,8 +34651,8 @@ function acquireStartupLock(socketPath) {
   const pidFile = import_node_path4.default.join(lock, "pid");
   const tryMkdir = () => {
     try {
-      (0, import_node_fs3.mkdirSync)(lock);
-      (0, import_node_fs3.writeFileSync)(pidFile, String(process.pid), "utf-8");
+      (0, import_node_fs4.mkdirSync)(lock);
+      (0, import_node_fs4.writeFileSync)(pidFile, String(process.pid), "utf-8");
       return true;
     } catch (err) {
       if (!isErrnoException(err) || err.code !== "EEXIST") throw err;
@@ -34147,7 +34662,7 @@ function acquireStartupLock(socketPath) {
   if (tryMkdir()) return true;
   let holderPid;
   try {
-    holderPid = parseInt((0, import_node_fs3.readFileSync)(pidFile, "utf-8"), 10);
+    holderPid = parseInt((0, import_node_fs4.readFileSync)(pidFile, "utf-8"), 10);
   } catch {
     return false;
   }
@@ -34168,11 +34683,11 @@ function acquireStartupLock(socketPath) {
     return false;
   }
   try {
-    (0, import_node_fs3.unlinkSync)(pidFile);
+    (0, import_node_fs4.unlinkSync)(pidFile);
   } catch {
   }
   try {
-    (0, import_node_fs3.rmdirSync)(lock);
+    (0, import_node_fs4.rmdirSync)(lock);
   } catch {
   }
   return tryMkdir();
@@ -34181,11 +34696,11 @@ function releaseStartupLock(socketPath) {
   const lock = lockPath(socketPath);
   const pidFile = import_node_path4.default.join(lock, "pid");
   try {
-    (0, import_node_fs3.unlinkSync)(pidFile);
+    (0, import_node_fs4.unlinkSync)(pidFile);
   } catch {
   }
   try {
-    (0, import_node_fs3.rmdirSync)(lock);
+    (0, import_node_fs4.rmdirSync)(lock);
   } catch {
   }
 }
@@ -34256,6 +34771,16 @@ function handleRequest(runtime, request, stop) {
         })
       );
     }
+    case "monitor.explain": {
+      const params = monitorExplainParamsSchema.parse(request.params);
+      return runtime.explainMonitor({
+        monitorId: params.monitorId,
+        monitorsDir: params.monitorsDir,
+        ...params.workspacePath ? { workspacePath: params.workspacePath } : {},
+        ...params.historyLimit ? { historyLimit: params.historyLimit } : {},
+        ...params.eventLimit ? { eventLimit: params.eventLimit } : {}
+      });
+    }
     case "daemon.tick": {
       const params = daemonTickParamsSchema.parse(request.params);
       return runtime.tick(params.monitorsDir, params.workspacePath);
@@ -34267,7 +34792,7 @@ function createDaemonServer({
   socketPath,
   onStop
 }) {
-  (0, import_node_fs3.mkdirSync)(import_node_path4.default.dirname(socketPath), { recursive: true });
+  (0, import_node_fs4.mkdirSync)(import_node_path4.default.dirname(socketPath), { recursive: true });
   let serverClosed = false;
   const server = import_node_net.default.createServer((socket) => {
     let buffer = "";
@@ -34325,7 +34850,7 @@ function createDaemonServer({
         const live = await probeSocket(socketPath);
         if (!live) {
           try {
-            (0, import_node_fs3.unlinkSync)(socketPath);
+            (0, import_node_fs4.unlinkSync)(socketPath);
           } catch (unlinkErr) {
             const code = isErrnoException(unlinkErr) ? String(unlinkErr.code) : "";
             if (code !== "ENOENT") throw unlinkErr;
@@ -34391,11 +34916,20 @@ async function callDaemon(method, params = {}, options2 = {}) {
       });
     };
     socket.setTimeout(timeoutMs, () => {
-      fail(new Error(`Timed out waiting for AgentMon daemon at ${socketPath}`));
+      fail(
+        new DaemonConnectionError(
+          `Timed out waiting for AgentMon daemon at ${socketPath}`
+        )
+      );
     });
     socket.setEncoding("utf-8");
     socket.on("error", (error2) => {
-      fail(error2);
+      fail(
+        new DaemonConnectionError(
+          error2 instanceof Error ? error2.message : String(error2),
+          error2
+        )
+      );
     });
     socket.on("data", (chunk) => {
       buffer += typeof chunk === "string" ? chunk : chunk.toString("utf-8");
@@ -34436,7 +34970,11 @@ async function daemonAvailable(socketPath) {
   }
 }
 
+// src/runtime-client.ts
+init_cjs_shims();
+
 // src/runtime.ts
+init_cjs_shims();
 function createRuntime(dbPath = resolveDbPath()) {
   const db = createDb(dbPath);
   const registry2 = new SourceRegistry();
@@ -34499,6 +35037,13 @@ async function listObservationHistoryClient(query, socketPath) {
     socketPath ? { socketPath } : {}
   );
 }
+async function explainMonitorClient(input, socketPath) {
+  return await callDaemon(
+    "monitor.explain",
+    input,
+    socketPath ? { socketPath } : {}
+  );
+}
 async function daemonStatusClient(socketPath) {
   return await callDaemon(
     "status",
@@ -34515,6 +35060,127 @@ async function daemonTickClient(monitorsDir, workspacePath) {
 var monitorTestCommand = new Command("monitor").description(
   "Monitor utilities"
 );
+var EXPLAIN_STAGE_LABELS2 = {
+  definition: "Definition",
+  scheduling: "Scheduling",
+  observation: "Observation",
+  notify: "Notify state",
+  materialization: "Materialization",
+  delivery: "Projection and delivery"
+};
+function monitorIdFromFilePath2(filePath2) {
+  const base = import_node_path5.default.basename(filePath2);
+  return base === "MONITOR.md" ? import_node_path5.default.basename(import_node_path5.default.dirname(filePath2)) : import_node_path5.default.parse(filePath2).name;
+}
+function explainStage2(id, status, reason, details) {
+  return {
+    id,
+    label: EXPLAIN_STAGE_LABELS2[id],
+    status,
+    reason,
+    ...details ? { details } : {}
+  };
+}
+function explainVerdict2(stages) {
+  const stopped = stages.find((stage2) => stage2.status !== "ok");
+  const stage = stopped ?? stages[stages.length - 1];
+  return {
+    status: stage?.status ?? "ok",
+    stage: stage?.id ?? "delivery",
+    reason: stage?.reason ?? "Monitor delivered successfully."
+  };
+}
+function statusGlyph(status) {
+  if (status === "ok") return "\u2713";
+  if (status === "pending") return "\u23F3";
+  if (status === "healthy") return "\u25CB";
+  return "\u2717";
+}
+function printExplainText(report) {
+  console.log(`Monitor ${report.monitorId}`);
+  for (const stage of report.stages) {
+    console.log(`${statusGlyph(stage.status)} ${stage.label}: ${stage.reason}`);
+  }
+  console.log(
+    `Verdict: ${report.verdict.status} at ${EXPLAIN_STAGE_LABELS2[report.verdict.stage]} - ${report.verdict.reason}`
+  );
+}
+async function buildDaemonUnavailableReport(input) {
+  const generatedAt = /* @__PURE__ */ new Date();
+  const stages = [];
+  const scan = await scanMonitors(input.monitorsDir);
+  const parseError = scan.errors.find(
+    (error2) => monitorIdFromFilePath2(error2.filePath) === input.monitorId
+  );
+  const monitor = scan.monitors.find(
+    (candidate) => candidate.monitor.id === input.monitorId
+  )?.monitor;
+  if (parseError) {
+    stages.push(
+      explainStage2(
+        "definition",
+        "failure",
+        `MONITOR.md failed to parse or validate: ${parseError.error}`,
+        { filePath: parseError.filePath }
+      )
+    );
+  } else if (!monitor) {
+    stages.push(
+      explainStage2(
+        "definition",
+        "failure",
+        `Monitor "${input.monitorId}" was not found in ${input.monitorsDir}.`
+      )
+    );
+  } else {
+    const registry2 = new SourceRegistry();
+    registerCoreSources(registry2);
+    const sourceName = monitor.frontmatter.watch.type;
+    const source6 = registry2.get(sourceName);
+    const { type: _type, ...monitorWatchConfig } = monitor.frontmatter.watch;
+    const scopeErrors = source6 ? validateScope(monitorWatchConfig, source6.scopeSchema) : [`Unknown source "${sourceName}".`];
+    stages.push(
+      scopeErrors.length === 0 ? explainStage2("definition", "ok", "Monitor definition is valid.", {
+        filePath: monitor.filePath,
+        sourceName
+      }) : explainStage2(
+        "definition",
+        "failure",
+        `Monitor definition is invalid: ${scopeErrors.join("; ")}`,
+        { filePath: monitor.filePath, sourceName }
+      )
+    );
+  }
+  if (stages[0]?.status === "ok") {
+    stages.push(
+      explainStage2(
+        "scheduling",
+        "failure",
+        `The daemon is not running or unreachable: ${input.errorMessage}`,
+        { workspacePath: input.workspacePath }
+      )
+    );
+  }
+  return {
+    monitorId: input.monitorId,
+    generatedAt,
+    ...monitor ? {
+      monitor: {
+        id: monitor.id,
+        displayName: monitor.displayName,
+        filePath: monitor.filePath,
+        sourceName: monitor.frontmatter.watch.type,
+        urgency: monitor.frontmatter.urgency
+      }
+    } : {},
+    stages,
+    verdict: explainVerdict2(stages),
+    observations: [],
+    events: [],
+    projections: [],
+    leadSessions: []
+  };
+}
 function printJsonResult(monitorName, sourceName, baseline, observations) {
   console.log(
     JSON.stringify(
@@ -34598,13 +35264,13 @@ monitorTestCommand.command("test").description("Dry-run a monitor observation so
   new Option("--format <format>", "Output format").choices(["text", "json"]).default("text")
 ).action(async (filePath2, options2) => {
   const json = options2.format === "json";
-  if (!(0, import_node_fs4.existsSync)(filePath2)) {
+  if (!(0, import_node_fs5.existsSync)(filePath2)) {
     reportError(`Monitor file not found: ${filePath2}`, json);
     return;
   }
   let content;
   try {
-    content = (0, import_node_fs4.readFileSync)(filePath2, "utf-8");
+    content = (0, import_node_fs5.readFileSync)(filePath2, "utf-8");
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
     reportError(`Cannot read monitor file: ${msg}`, json);
@@ -34660,6 +35326,55 @@ monitorTestCommand.command("test").description("Dry-run a monitor observation so
     reportError(`Observation failed: ${message}`, json);
   }
 });
+monitorTestCommand.command("explain").description("Explain where a monitor's signal currently stops").argument("<monitorId>", "Monitor id to diagnose").option(
+  "--dir <path>",
+  "Directory containing monitor definitions",
+  ".claude/monitors"
+).option("--workspace <path>", "Workspace path used by the daemon").option("--socket <path>", "Unix domain socket path for the daemon").option("--history-limit <n>", "Observation history rows to include", "10").option("--event-limit <n>", "Materialized event rows to include", "10").addOption(
+  new Option("--format <format>", "Output format").choices(["text", "json"]).default("text")
+).action(
+  async (monitorId, options2) => {
+    const json = options2.format === "json";
+    const monitorsDir = import_node_path5.default.resolve(options2.dir);
+    const workspacePath = import_node_path5.default.resolve(options2.workspace ?? process.cwd());
+    const historyLimit = Number.parseInt(options2.historyLimit, 10);
+    const eventLimit = Number.parseInt(options2.eventLimit, 10);
+    try {
+      const report = await explainMonitorClient(
+        {
+          monitorId,
+          monitorsDir,
+          workspacePath,
+          ...Number.isFinite(historyLimit) && historyLimit > 0 ? { historyLimit } : {},
+          ...Number.isFinite(eventLimit) && eventLimit > 0 ? { eventLimit } : {}
+        },
+        options2.socket
+      );
+      if (json) {
+        console.log(JSON.stringify(report, null, 2));
+        return;
+      }
+      printExplainText(report);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      if (!(err instanceof DaemonConnectionError)) {
+        reportError(`Explain failed: ${message}`, json);
+        return;
+      }
+      const report = await buildDaemonUnavailableReport({
+        monitorId,
+        monitorsDir,
+        workspacePath,
+        errorMessage: message
+      });
+      if (json) {
+        console.log(JSON.stringify(report, null, 2));
+        return;
+      }
+      printExplainText(report);
+    }
+  }
+);
 monitorTestCommand.command("history").description(
   "Show recent observation outcomes per tick (triggered / suppressed / no-change / errored / rebaselined)"
 ).argument("[monitorId]", "Filter to a single monitor id").option("--socket <path>", "Unix domain socket path for the daemon").option("--limit <n>", "Maximum rows to return", "50").addOption(
@@ -34711,9 +35426,11 @@ sourceCommand.command("list").description("List installed observation sources").
     const output = sources.map((source6) => {
       const requiredFields = source6.scopeSchema["required"] ?? [];
       const properties = source6.scopeSchema["properties"] ?? {};
+      const configFields = Object.keys(properties);
       return {
         name: source6.name,
-        scopeFields: Object.keys(properties),
+        configFields,
+        scopeFields: configFields,
         required: requiredFields
       };
     });
@@ -34729,7 +35446,7 @@ sourceCommand.command("list").description("List installed observation sources").
     const requiredFields = source6.scopeSchema["required"] ?? [];
     const properties = source6.scopeSchema["properties"] ?? {};
     console.log(`  ${source6.name}`);
-    console.log(`    Scope fields: ${Object.keys(properties).join(", ")}`);
+    console.log(`    Config fields: ${Object.keys(properties).join(", ")}`);
     console.log(`    Required: ${requiredFields.join(", ") || "(none)"}`);
     console.log("");
   }
@@ -34817,6 +35534,11 @@ function shouldReap(s) {
 
 // src/commands/daemon.ts
 var DEFAULT_REAP_AFTER_MS = 5 * 60 * 1e3;
+function appendErroredLines(summary, errored) {
+  if (errored.length === 0) return summary;
+  const lines = errored.map((e) => `  ${e.monitorId}: ${e.message}`);
+  return [summary, ...lines].join("\n");
+}
 async function runLoop(monitorsDir, workspacePath, pollMs, socketPath, reapAfterMs) {
   const runtime = createRuntime();
   let stopping = false;
@@ -34862,10 +35584,12 @@ async function runLoop(monitorsDir, workspacePath, pollMs, socketPath, reapAfter
     while (!isStoppingRequested()) {
       try {
         const result = await runtime.tick(monitorsDir, workspacePath);
-        if (result.emittedEventIds.length > 0) {
-          console.log(
-            `Emitted ${String(result.emittedEventIds.length)} event(s) from ${String(result.evaluatedMonitors.length)} monitor(s).`
+        if (result.emittedEventIds.length > 0 || result.erroredObservations.length > 0) {
+          const summary = appendErroredLines(
+            `Emitted ${String(result.emittedEventIds.length)} event(s) from ${String(result.evaluatedMonitors.length)} monitor(s)${result.erroredObservations.length > 0 ? `, ${String(result.erroredObservations.length)} errored:` : "."}`,
+            result.erroredObservations
           );
+          console.log(summary);
         }
       } catch (error2) {
         const message = error2 instanceof Error ? error2.message : String(error2);
@@ -34931,9 +35655,9 @@ daemonCommand.command("once").description("Run one runtime observation cycle").a
         console.log(JSON.stringify(result, null, 2));
         return;
       }
-      console.log(
-        `Evaluated ${String(result.evaluatedMonitors.length)} monitor(s), emitted ${String(result.emittedEventIds.length)} event(s).`
-      );
+      const erroredCount = result.erroredObservations.length;
+      const base = `Evaluated ${String(result.evaluatedMonitors.length)} monitor(s), emitted ${String(result.emittedEventIds.length)} event(s)${erroredCount > 0 ? `, ${String(erroredCount)} errored:` : "."}`;
+      console.log(appendErroredLines(base, result.erroredObservations));
     } catch (error2) {
       const message = error2 instanceof Error ? error2.message : String(error2);
       reportError(message, options2.format === "json");
@@ -35026,15 +35750,15 @@ daemonCommand.command("stop").description("Ask the local AgentMon daemon to stop
 
 // src/commands/session.ts
 init_cjs_shims();
-var import_node_path8 = __toESM(require("path"), 1);
+var import_node_path9 = __toESM(require("path"), 1);
 
 // src/local-state.ts
 init_cjs_shims();
-var import_node_fs5 = require("fs");
-var import_node_path5 = __toESM(require("path"), 1);
+var import_node_fs6 = require("fs");
+var import_node_path6 = __toESM(require("path"), 1);
 var DEFAULT_REAP_AFTER_MS2 = 5 * 60 * 1e3;
 function filePath(workspacePath) {
-  return import_node_path5.default.join(workspacePath, ".claude", "agentmonitors.local.md");
+  return import_node_path6.default.join(workspacePath, ".claude", "agentmonitors.local.md");
 }
 function parseFrontmatter(raw) {
   const lines = raw.split("\n");
@@ -35063,7 +35787,7 @@ function parseFrontmatter(raw) {
 function readLocalState(workspacePath) {
   let raw;
   try {
-    raw = (0, import_node_fs5.readFileSync)(filePath(workspacePath), "utf-8");
+    raw = (0, import_node_fs6.readFileSync)(filePath(workspacePath), "utf-8");
   } catch {
     return { enabled: false };
   }
@@ -35084,7 +35808,7 @@ function readLocalState(workspacePath) {
 }
 function writeLocalState(workspacePath, state) {
   const target = filePath(workspacePath);
-  (0, import_node_fs5.mkdirSync)(import_node_path5.default.dirname(target), { recursive: true });
+  (0, import_node_fs6.mkdirSync)(import_node_path6.default.dirname(target), { recursive: true });
   const lines = [
     "---",
     `enabled: ${String(state.enabled)}`,
@@ -35096,25 +35820,25 @@ function writeLocalState(workspacePath, state) {
     "> Local AgentMon coordination state. Gitignored; safe to delete (it is regenerated).",
     ""
   ];
-  (0, import_node_fs5.writeFileSync)(target, lines.join("\n"), "utf-8");
+  (0, import_node_fs6.writeFileSync)(target, lines.join("\n"), "utf-8");
 }
 
 // src/workspace-paths.ts
 init_cjs_shims();
 var import_node_crypto2 = require("crypto");
 var import_node_os3 = __toESM(require("os"), 1);
-var import_node_path6 = __toESM(require("path"), 1);
+var import_node_path7 = __toESM(require("path"), 1);
 function workspacePaths(workspacePath) {
-  const hash = (0, import_node_crypto2.createHash)("sha256").update(import_node_path6.default.resolve(workspacePath)).digest("hex").slice(0, 16);
-  const dataRoot = process.env["XDG_DATA_HOME"] ?? import_node_path6.default.join(import_node_os3.default.homedir(), ".local", "share");
-  const dir = import_node_path6.default.join(dataRoot, "agentmonitors", "workspaces", hash);
+  const hash = (0, import_node_crypto2.createHash)("sha256").update(import_node_path7.default.resolve(workspacePath)).digest("hex").slice(0, 16);
+  const dataRoot = process.env["XDG_DATA_HOME"] ?? import_node_path7.default.join(import_node_os3.default.homedir(), ".local", "share");
+  const dir = import_node_path7.default.join(dataRoot, "agentmonitors", "workspaces", hash);
   return {
     dir,
-    db: import_node_path6.default.join(dir, "inbox.db"),
+    db: import_node_path7.default.join(dir, "inbox.db"),
     // Keep the socket short: a 16-char hash under the data dir stays well under
     // the 100-char limit on most setups; resolveSocketPath's /tmp fallback still
     // applies if a deep home dir pushes it over.
-    socket: import_node_path6.default.join(dir, "agentmonitors.sock")
+    socket: import_node_path7.default.join(dir, "agentmonitors.sock")
   };
 }
 
@@ -35122,15 +35846,15 @@ function workspacePaths(workspacePath) {
 init_cjs_shims();
 var import_node_child_process = require("child_process");
 var import_node_url3 = require("url");
-var import_node_path7 = __toESM(require("path"), 1);
+var import_node_path8 = __toESM(require("path"), 1);
 function cliEntry() {
   const thisFile = (0, import_node_url3.fileURLToPath)(importMetaUrl);
-  const isBundle = import_node_path7.default.basename(import_node_path7.default.dirname(thisFile)) === "dist";
+  const isBundle = import_node_path8.default.basename(import_node_path8.default.dirname(thisFile)) === "dist";
   if (isBundle) {
     return thisFile;
   }
-  const packageRoot = import_node_path7.default.resolve(import_node_path7.default.dirname(thisFile), "..");
-  return import_node_path7.default.join(packageRoot, "dist", "index.cjs");
+  const packageRoot = import_node_path8.default.resolve(import_node_path8.default.dirname(thisFile), "..");
+  return import_node_path8.default.join(packageRoot, "dist", "index.cjs");
 }
 function spawnDetachedDaemon(options2) {
   const args = [
@@ -35337,7 +36061,7 @@ sessionCommand.command("start").description(
   const paths = workspacePaths(workspacePath);
   const socket = resolveSocketPath(state.socket ?? paths.socket);
   const db = state.db ?? paths.db;
-  const monitorsDir = import_node_path8.default.join(workspacePath, ".claude", "monitors");
+  const monitorsDir = import_node_path9.default.join(workspacePath, ".claude", "monitors");
   const BOOT_TIMEOUT_MS = 8e3;
   if (!await daemonAvailable(socket)) {
     spawnDetachedDaemon({
@@ -35771,10 +36495,10 @@ function assignProp(target, prop, value) {
     configurable: true
   });
 }
-function getElementAtPath(obj, path12) {
-  if (!path12)
+function getElementAtPath(obj, path13) {
+  if (!path13)
     return obj;
-  return path12.reduce((acc, key) => acc?.[key], obj);
+  return path13.reduce((acc, key) => acc?.[key], obj);
 }
 function promiseAllObject(promisesObj) {
   const keys = Object.keys(promisesObj);
@@ -36094,11 +36818,11 @@ function aborted(x2, startIndex = 0) {
   }
   return false;
 }
-function prefixIssues(path12, issues) {
+function prefixIssues(path13, issues) {
   return issues.map((iss) => {
     var _a2;
     (_a2 = iss).path ?? (_a2.path = []);
-    iss.path.unshift(path12);
+    iss.path.unshift(path13);
     return iss;
   });
 }
@@ -43007,9 +43731,9 @@ async function runChannelServe(options2) {
 // src/index.ts
 function getVersion() {
   try {
-    const dir = (0, import_node_path9.dirname)((0, import_node_url4.fileURLToPath)(importMetaUrl));
+    const dir = (0, import_node_path10.dirname)((0, import_node_url4.fileURLToPath)(importMetaUrl));
     const pkg = JSON.parse(
-      (0, import_node_fs6.readFileSync)((0, import_node_path9.join)(dir, "..", "package.json"), "utf8")
+      (0, import_node_fs7.readFileSync)((0, import_node_path10.join)(dir, "..", "package.json"), "utf8")
     );
     return typeof pkg.version === "string" ? pkg.version : "0.0.0";
   } catch {