u-foo 2.5.5 → 2.5.7

package/src/code/taskDecomposer.js

@@ -12,8 +12,9 @@ function decomposeBugFixTask(task) {
   const steps = [];
   const taskContext = String(task || "");
 
-  // Analyze task to determine if it's a bug fix
-  const isBugFix = /fix|bug|issue|problem|error|broken|doesn't work|not work/i.test(task);
+  // Analyze task to determine if it's a bug fix. Word boundaries keep
+  // substrings like "fixture"/"prefix"/"debug" from false-matching.
+  const isBugFix = /\b(?:fix(?:es|ed|ing)?|bugs?|issues?|problems?|errors?|broken)\b|doesn't work|not work/i.test(taskContext);
 
   if (isBugFix) {
     steps.push({
@@ -67,6 +68,17 @@ function clipStepOutput(value = "", maxChars = 2000) {
   return `${text.slice(0, maxChars)}\n...[truncated]`;
 }
 
+// Progress callbacks are user-supplied; a throwing callback must not abort
+// the task (mirrors nativeRunner's emitToolEvent/emitPhase policy).
+function reportProgress(callback, event = {}) {
+  if (typeof callback !== "function") return;
+  try {
+    callback(event);
+  } catch {
+    // ignore callback failures
+  }
+}
+
 function buildStepPrompt(step, previousResults = []) {
   const basePrompt = String(step && step.prompt ? step.prompt : "");
   const prior = Array.isArray(previousResults) ? previousResults : [];
@@ -111,7 +123,6 @@ function shouldEarlyExitStep(step, stepResult = {}) {
  */
 async function runDecomposedTask({
   task,
-  state,
   onProgress,
   onToolEvent,
   signal,
@@ -143,15 +154,13 @@ async function runDecomposedTask({
     }
 
     // Report progress
-    if (onProgress) {
-      onProgress({
-        type: "step_start",
-        step: step.id,
-        name: step.name,
-        current: steps.indexOf(step) + 1,
-        total: steps.length,
-      });
-    }
+    reportProgress(onProgress, {
+      type: "step_start",
+      step: step.id,
+      name: step.name,
+      current: steps.indexOf(step) + 1,
+      total: steps.length,
+    });
 
     try {
       // Run the step with its own timeout
@@ -176,14 +185,12 @@ async function runDecomposedTask({
       });
 
       // Report step completion
-      if (onProgress) {
-        onProgress({
-          type: "step_complete",
-          step: step.id,
-          name: step.name,
-          success: stepResult.ok,
-        });
-      }
+      reportProgress(onProgress, {
+        type: "step_complete",
+        step: step.id,
+        name: step.name,
+        success: stepResult.ok,
+      });
 
       // Early exit if solution found
       if (shouldEarlyExitStep(step, stepResult)) {
@@ -202,14 +209,12 @@ async function runDecomposedTask({
 
     } catch (err) {
       // Report step error
-      if (onProgress) {
-        onProgress({
-          type: "step_error",
-          step: step.id,
-          name: step.name,
-          error: err.message,
-        });
-      }
+      reportProgress(onProgress, {
+        type: "step_error",
+        step: step.id,
+        name: step.name,
+        error: err.message,
+      });
 
       return {
         ok: false,
@@ -280,11 +285,22 @@ function compileSummary(results) {
   return summaryParts.join("\n\n");
 }
 
+/**
+ * Quote a value for safe inclusion in a shell command (single-quote style).
+ * Kept local to avoid a circular dependency with agent.js.
+ */
+function shellQuote(value = "") {
+  const text = String(value == null ? "" : value);
+  return `'${text.replace(/'/g, `'\"'\"'`)}'`;
+}
+
 /**
  * Create a progress reporter that sends updates via bus
  */
 function createBusProgressReporter(shell, publisher) {
-  let lastReportTime = Date.now();
+  // Start at 0 so the first event reports immediately instead of being
+  // swallowed by the throttle window.
+  let lastReportTime = 0;
   const MIN_REPORT_INTERVAL = 5000; // Report at most every 5 seconds
 
   return (progress) => {
@@ -297,10 +313,10 @@ function createBusProgressReporter(shell, publisher) {
 
     if (progress.type === "step_start") {
       const message = `⏳ ${progress.name} (${progress.current}/${progress.total})`;
-      shell(`ufoo bus send ${publisher} ${JSON.stringify(message)}`);
+      shell(`ufoo bus send ${shellQuote(publisher)} ${shellQuote(JSON.stringify(message))}`);
     } else if (progress.type === "step_complete" && progress.success) {
       const message = `✅ ${progress.name} completed`;
-      shell(`ufoo bus send ${publisher} ${JSON.stringify(message)}`);
+      shell(`ufoo bus send ${shellQuote(publisher)} ${shellQuote(JSON.stringify(message))}`);
     }
   };
 }

package/src/code/tools/bash.js

@@ -1,6 +1,8 @@
 const { spawnSync } = require("child_process");
 const { normalizeWorkspaceRoot } = require("./common");
 
+const MAX_TIMEOUT_MS = 600000;
+
 function runBashTool(input = {}, options = {}) {
   try {
     const command = String(input.command || "").trim();
@@ -11,7 +13,9 @@ function runBashTool(input = {}, options = {}) {
       };
     }
     const workspaceRoot = normalizeWorkspaceRoot(options.workspaceRoot, options.cwd);
-    const timeoutMs = Number.isFinite(input.timeoutMs) ? Math.max(100, Math.floor(input.timeoutMs)) : 60000;
+    const timeoutMs = Number.isFinite(input.timeoutMs)
+      ? Math.min(MAX_TIMEOUT_MS, Math.max(100, Math.floor(input.timeoutMs)))
+      : 60000;
     const result = spawnSync(command, {
       cwd: workspaceRoot,
       shell: true,
@@ -25,13 +29,26 @@ function runBashTool(input = {}, options = {}) {
         ok: false,
         workspaceRoot,
         code: typeof result.status === "number" ? result.status : -1,
+        signal: result.signal || "",
         stdout: String(result.stdout || ""),
         stderr: String(result.stderr || ""),
         error: result.error.message || "bash failed",
       };
     }
 
-    const code = typeof result.status === "number" ? result.status : 0;
+    if (typeof result.status !== "number") {
+      return {
+        ok: false,
+        workspaceRoot,
+        code: -1,
+        signal: result.signal || "",
+        stdout: String(result.stdout || ""),
+        stderr: String(result.stderr || ""),
+        error: `command killed by signal ${result.signal || "unknown"}`,
+      };
+    }
+
+    const code = result.status;
     return {
       ok: code === 0,
       workspaceRoot,

package/src/code/tools/common.js

@@ -13,6 +13,28 @@ function isPathInside(root, target) {
   return normalizedTarget.startsWith(`${normalizedRoot}${path.sep}`);
 }
 
+function realpathOrNull(value) {
+  try {
+    return fs.realpathSync(value);
+  } catch {
+    return null;
+  }
+}
+
+// Realpath the nearest existing ancestor of a path (the path itself when it
+// exists). The workspace root always exists by the time tools run, so the
+// walk terminates there at the latest.
+function realpathNearestExisting(value) {
+  let current = value;
+  for (;;) {
+    const real = realpathOrNull(current);
+    if (real) return real;
+    const parent = path.dirname(current);
+    if (parent === current) return null;
+    current = parent;
+  }
+}
+
 function resolveWorkspacePath(workspaceRoot = "", targetPath = "", cwd = process.cwd()) {
   const root = normalizeWorkspaceRoot(workspaceRoot, cwd);
   const requested = String(targetPath || "").trim();
@@ -23,6 +45,18 @@ function resolveWorkspacePath(workspaceRoot = "", targetPath = "", cwd = process
   if (!isPathInside(root, resolved)) {
     throw new Error("path escapes workspace root");
   }
+  // Lexical checks alone let a symlink inside the workspace point outside
+  // (e.g. link -> /etc). Re-validate with real paths: realpath the root too
+  // so legit roots behind symlinks (macOS /tmp -> /private/tmp) still pass.
+  // For missing files, checking the nearest existing ancestor is enough —
+  // the not-yet-created tail cannot contain a symlink.
+  const realRoot = realpathOrNull(root);
+  if (realRoot) {
+    const realTarget = realpathNearestExisting(resolved);
+    if (!realTarget || !isPathInside(realRoot, realTarget)) {
+      throw new Error("path escapes workspace root");
+    }
+  }
   return {
     workspaceRoot: root,
     requested,

package/src/code/tools/edit.js

@@ -47,14 +47,22 @@ function runEditTool(input = {}, options = {}) {
       ? replaceAll(original, find, replace)
       : replaceOnce(original, find, replace);
     const changed = applied.count > 0;
-    if (changed) {
-      fs.writeFileSync(resolved, applied.next, "utf8");
+    if (!changed) {
+      return {
+        ok: false,
+        workspaceRoot,
+        path: resolved,
+        changed: false,
+        replacements: 0,
+        error: `find pattern not found in ${resolved}`,
+      };
     }
+    fs.writeFileSync(resolved, applied.next, "utf8");
     return {
       ok: true,
       workspaceRoot,
       path: resolved,
-      changed,
+      changed: true,
       replacements: applied.count,
     };
   } catch (err) {

package/src/code/tools/read.js

@@ -1,6 +1,23 @@
 const fs = require("fs");
 const { resolveWorkspacePath } = require("./common");
 
+const MAX_FULL_READ_BYTES = 4 * 1024 * 1024;
+
+function readFileBounded(resolved) {
+  const stat = fs.statSync(resolved);
+  if (stat.size <= MAX_FULL_READ_BYTES) {
+    return { raw: fs.readFileSync(resolved, "utf8"), partial: false };
+  }
+  const fd = fs.openSync(resolved, "r");
+  try {
+    const buffer = Buffer.alloc(MAX_FULL_READ_BYTES);
+    const bytesRead = fs.readSync(fd, buffer, 0, MAX_FULL_READ_BYTES, 0);
+    return { raw: buffer.slice(0, bytesRead).toString("utf8"), partial: true };
+  } finally {
+    fs.closeSync(fd);
+  }
+}
+
 function runReadTool(input = {}, options = {}) {
   try {
     const filePath = String(input.path || input.file || "").trim();
@@ -9,13 +26,13 @@ function runReadTool(input = {}, options = {}) {
     const endLine = Number.isFinite(input.endLine) ? Math.max(startLine, Math.floor(input.endLine)) : 0;
     const maxBytes = Number.isFinite(input.maxBytes) ? Math.max(256, Math.floor(input.maxBytes)) : 200000;
 
-    const raw = fs.readFileSync(resolved, "utf8");
+    const { raw, partial } = readFileBounded(resolved);
     const lines = raw.split(/\r?\n/);
     const from = startLine - 1;
     const to = endLine > 0 ? endLine : lines.length;
     const selected = lines.slice(from, to);
     let content = selected.join("\n");
-    let truncated = false;
+    let truncated = partial;
     if (Buffer.byteLength(content, "utf8") > maxBytes) {
       content = Buffer.from(content, "utf8").slice(0, maxBytes).toString("utf8");
       truncated = true;
@@ -41,4 +58,5 @@ function runReadTool(input = {}, options = {}) {
 
 module.exports = {
   runReadTool,
+  MAX_FULL_READ_BYTES,
 };

package/src/coordination/bus/inject.js

@@ -12,6 +12,22 @@ const logInject = (message) => {
   }
 };
 
+// osascript 遇到权限弹窗或 System Events 挂起时会永不退出；tmux 客户端
+// 卡死时同样不退出。daemon 的 DeliveryScheduler 会 await 这些 Promise，
+// 没有超时就会永久持有该 subscriber 的推送锁，只能重启 daemon 恢复。
+const SPAWN_TIMEOUT_MS = 10000;
+
+function killAfterTimeout(proc, cmd, onTimeout) {
+  return setTimeout(() => {
+    try {
+      proc.kill("SIGKILL");
+    } catch {
+      // 进程已退出，无需处理
+    }
+    onTimeout(new Error(`${cmd} timeout after ${SPAWN_TIMEOUT_MS}ms`));
+  }, SPAWN_TIMEOUT_MS);
+}
+
 function escapeAppleScriptString(value) {
   return String(value).replace(/\\/g, "\\\\").replace(/"/g, '\\"');
 }
@@ -28,6 +44,8 @@ function runAppleScript(lines = []) {
     let stderr = "";
     let stdout = "";
 
+    const timeout = killAfterTimeout(proc, "osascript", reject);
+
     proc.stdout.on("data", (data) => {
       stdout += data.toString("utf8");
     });
@@ -35,13 +53,17 @@ function runAppleScript(lines = []) {
       stderr += data.toString("utf8");
     });
     proc.on("close", (code) => {
+      clearTimeout(timeout);
       if (code === 0) {
         resolve(stdout.trim());
       } else {
         reject(new Error(stderr.trim() || "AppleScript failed"));
       }
     });
-    proc.on("error", reject);
+    proc.on("error", (err) => {
+      clearTimeout(timeout);
+      reject(err);
+    });
   });
 }
 
@@ -109,15 +131,18 @@ class Injector {
    * 检查 tmux pane 是否存在
    */
   async checkTmuxPane(paneId) {
-    return new Promise((resolve) => {
+    return new Promise((resolve, reject) => {
       const proc = spawn("tmux", ["list-panes", "-a", "-F", "#{pane_id}"]);
       let output = "";
 
+      const timeout = killAfterTimeout(proc, "tmux list-panes", reject);
+
       proc.stdout.on("data", (data) => {
         output += data.toString();
       });
 
       proc.on("close", (code) => {
+        clearTimeout(timeout);
         if (code !== 0) {
           resolve(false);
           return;
@@ -126,7 +151,10 @@ class Injector {
         resolve(panes.includes(paneId));
       });
 
-      proc.on("error", () => resolve(false));
+      proc.on("error", () => {
+        clearTimeout(timeout);
+        resolve(false);
+      });
     });
   }
 
@@ -134,15 +162,18 @@ class Injector {
    * 根据 tty 查找 tmux pane
    */
   async findTmuxPaneByTty(tty) {
-    return new Promise((resolve) => {
+    return new Promise((resolve, reject) => {
       const proc = spawn("tmux", ["list-panes", "-a", "-F", "#{pane_id} #{pane_tty}"]);
       let output = "";
 
+      const timeout = killAfterTimeout(proc, "tmux list-panes", reject);
+
       proc.stdout.on("data", (data) => {
         output += data.toString();
       });
 
       proc.on("close", (code) => {
+        clearTimeout(timeout);
         if (code !== 0) {
           resolve(null);
           return;
@@ -158,7 +189,10 @@ class Injector {
         resolve(null);
       });
 
-      proc.on("error", () => resolve(null));
+      proc.on("error", () => {
+        clearTimeout(timeout);
+        resolve(null);
+      });
     });
   }
 
@@ -186,11 +220,14 @@ class Injector {
     const textProc = spawn("tmux", ["send-keys", "-t", paneId, command]);
     let stderr = "";
 
+    const textTimeout = killAfterTimeout(textProc, "tmux send-keys", reject);
+
     textProc.stderr.on("data", (data) => {
       stderr += data.toString();
     });
 
     textProc.on("close", (code) => {
+      clearTimeout(textTimeout);
       if (code !== 0) {
         reject(new Error(stderr || "tmux send-keys failed"));
         return;
@@ -198,15 +235,23 @@ class Injector {
       // Delay before sending Enter — gives the target app time to process input
       setTimeout(() => {
         const enterProc = spawn("tmux", ["send-keys", "-t", paneId, "Enter"]);
+        const enterTimeout = killAfterTimeout(enterProc, "tmux send-keys Enter", reject);
         enterProc.on("close", (enterCode) => {
+          clearTimeout(enterTimeout);
           if (enterCode === 0) resolve();
           else reject(new Error("tmux send-keys Enter failed"));
         });
-        enterProc.on("error", reject);
+        enterProc.on("error", (err) => {
+          clearTimeout(enterTimeout);
+          reject(err);
+        });
       }, 150);
     });
 
-    textProc.on("error", reject);
+    textProc.on("error", (err) => {
+      clearTimeout(textTimeout);
+      reject(err);
+    });
   }
 
   /**

package/src/coordination/bus/subscriber.js

@@ -1,4 +1,5 @@
 const fs = require("fs");
+const path = require("path");
 const { getTimestamp, isAgentPidAlive, isMetaActive, isValidTty, getTtyProcessInfo } = require("./utils");
 const NicknameManager = require("./nickname");
 const { spawnSync } = require("child_process");
@@ -113,8 +114,29 @@ class SubscriberManager {
     appendAgentRegistryDiagnostic(this.agentsFile, event, payload);
   }
 
+  /**
+   * 检查订阅者的 pending.jsonl 中是否仍有未投递消息
+   * 读取失败时保守返回 true，避免误删未投递消息
+   */
+  hasUndeliveredPending(subscriber) {
+    try {
+      const pendingPath = this.queueManager.getPendingPath
+        ? this.queueManager.getPendingPath(subscriber)
+        : (this.queueManager.getQueueDir
+          ? path.join(this.queueManager.getQueueDir(subscriber), "pending.jsonl")
+          : "");
+      if (!pendingPath || !fs.existsSync(pendingPath)) return false;
+      return fs.readFileSync(pendingPath, "utf8").trim().length > 0;
+    } catch {
+      return true;
+    }
+  }
+
   cleanupSubscriberArtifacts(subscriber) {
     if (!subscriber || !this.queueManager) return;
+    // pending.jsonl 里还有未投递消息时绝不能删队列目录和 offset 文件，
+    // 保留给订阅者复活或重新激活后继续投递；长期清理由其他机制负责。
+    if (this.hasUndeliveredPending(subscriber)) return;
     try {
       const queueDir = this.queueManager.getQueueDir
         ? this.queueManager.getQueueDir(subscriber)
@@ -168,16 +190,21 @@ class SubscriberManager {
           nickname: meta?.nickname || "",
         });
         delete this.busData.agents[id];
+        // Migrate undelivered messages to the replacement subscriber before
+        // removing the stale queue, so a tty takeover does not drop them.
         try {
-          const queueDir = this.queueManager.getQueueDir(id);
-          if (queueDir) {
-            fs.rmSync(queueDir, { recursive: true, force: true });
+          const dq = this.queueManager.getDeliveryQueue && this.queueManager.getDeliveryQueue(id);
+          const undelivered = dq && typeof dq.readPending === "function" ? dq.readPending() : [];
+          for (const event of undelivered) {
+            await this.queueManager.appendPending(currentSubscriber, event);
+          }
+          if (undelivered.length > 0 && typeof this.queueManager.clearPending === "function") {
+            await this.queueManager.clearPending(id);
           }
-          const offsetPath = this.queueManager.getOffsetPath(id);
-          if (offsetPath) fs.rmSync(offsetPath, { force: true });
         } catch {
-          // ignore cleanup errors
+          // best-effort migration; the guard below keeps the queue if it failed
         }
+        this.cleanupSubscriberArtifacts(id);
       }
     }
     return inheritedNickname;

package/src/runtime/daemon/deliveryScheduler.js

@@ -15,6 +15,20 @@ function isDeliverableActivityState(value = "") {
   return state === "idle" || state === "ready";
 }
 
+// Warn once a subscriber has been continuously gate-deferred for this long.
+const DEFAULT_DEFER_WARN_AFTER_MS = 60 * 1000;
+// Minimum interval between repeated defer/lock warnings for the same subscriber.
+const DEFAULT_WARN_INTERVAL_MS = 60 * 1000;
+// After this long stuck in waiting_input/blocked, deliver anyway (better a
+// message in a stuck terminal than a lost one). Env UFOO_DELIVERY_BLOCKED_GRACE_MS overrides.
+const DEFAULT_BLOCKED_GRACE_MS = 15 * 60 * 1000;
+// Warn when an inject lock is held longer than this (usually means a stuck inject).
+const DEFAULT_LOCKED_WARN_AFTER_MS = 60 * 1000;
+
+function positiveMs(value, fallback) {
+  return Number.isFinite(value) && value > 0 ? value : fallback;
+}
+
 function readAgentsFile(agentsFile) {
   try {
     if (!agentsFile || !fs.existsSync(agentsFile)) return { agents: {} };
@@ -45,15 +59,70 @@ class DeliveryScheduler {
       ? options.emitDelivery
       : async () => {};
     this.log = typeof options.log === "function" ? options.log : () => {};
+    this.now = typeof options.now === "function" ? options.now : () => Date.now();
+    this.deferWarnAfterMs = positiveMs(options.deferWarnAfterMs, DEFAULT_DEFER_WARN_AFTER_MS);
+    this.warnIntervalMs = positiveMs(options.warnIntervalMs, DEFAULT_WARN_INTERVAL_MS);
+    this.blockedGraceMs = positiveMs(
+      options.blockedGraceMs,
+      positiveMs(Number(process.env.UFOO_DELIVERY_BLOCKED_GRACE_MS), DEFAULT_BLOCKED_GRACE_MS),
+    );
+    this.lockedWarnAfterMs = positiveMs(options.lockedWarnAfterMs, DEFAULT_LOCKED_WARN_AFTER_MS);
     this.intervalMs = Number.isFinite(options.intervalMs) && options.intervalMs > 0
       ? options.intervalMs
       : 1000;
     this.adapterRouter = options.adapterRouter || createTerminalAdapterRouter();
-    this.locks = new Set();
+    this.locks = new Map();
+    this.deferrals = new Map();
+    this.blockedStateSeen = new Map();
+    this.graceWarned = new Map();
     this.timer = null;
     this.running = false;
   }
 
+  pendingCount(subscriber) {
+    try {
+      const queue = this.queueFactory(subscriber);
+      if (queue && typeof queue.readPending === "function") return queue.readPending().length;
+    } catch {
+      // logging must never break delivery
+    }
+    return "unknown";
+  }
+
+  noteDeferral(subscriber, reason) {
+    const now = this.now();
+    const prev = this.deferrals.get(subscriber);
+    if (!prev || prev.reason !== reason) {
+      // Log once per reason change instead of on every 1s tick.
+      this.deferrals.set(subscriber, { reason, sinceMs: now, lastWarnAtMs: 0 });
+      this.log(`delivery deferred subscriber=${subscriber} reason=${reason} pending=${this.pendingCount(subscriber)}`);
+      return;
+    }
+    if (now - prev.sinceMs >= this.deferWarnAfterMs && now - prev.lastWarnAtMs >= this.warnIntervalMs) {
+      prev.lastWarnAtMs = now;
+      this.log(`WARN delivery still deferred subscriber=${subscriber} reason=${reason} pending=${this.pendingCount(subscriber)} deferred_ms=${now - prev.sinceMs}`);
+    }
+  }
+
+  clearDeferral(subscriber) {
+    this.deferrals.delete(subscriber);
+  }
+
+  noteGraceOverride(subscriber, activityState) {
+    if (this.graceWarned.get(subscriber) === activityState) return;
+    this.graceWarned.set(subscriber, activityState);
+    this.log(`WARN delivery grace override subscriber=${subscriber} activity_state=${activityState} pending=${this.pendingCount(subscriber)} grace_ms=${this.blockedGraceMs} - agent stuck, delivering anyway`);
+  }
+
+  noteLocked(subscriber, lock) {
+    const now = this.now();
+    const lockedMs = now - lock.sinceMs;
+    if (lockedMs >= this.lockedWarnAfterMs && now - lock.lastWarnAtMs >= this.warnIntervalMs) {
+      lock.lastWarnAtMs = now;
+      this.log(`WARN delivery lock held subscriber=${subscriber} locked_ms=${lockedMs} pending=${this.pendingCount(subscriber)} - previous inject may be stuck, daemon restart may be required`);
+    }
+  }
+
   getAgentMeta(subscriber) {
     const data = this.readAgents() || { agents: {} };
     const agents = data.agents && typeof data.agents === "object" ? data.agents : {};
@@ -75,23 +144,52 @@ class DeliveryScheduler {
     }
     const activityState = asState(meta.activity_state);
     if (!isDeliverableActivityState(activityState)) {
+      if (activityState === "waiting_input" || activityState === "blocked") {
+        const sinceMs = this.resolveBlockedStateSinceMs(subscriber, meta, activityState);
+        if (this.now() - sinceMs >= this.blockedGraceMs) {
+          return { ok: true, reason: "deliverable", graceOverride: activityState };
+        }
+      } else {
+        this.blockedStateSeen.delete(subscriber);
+      }
       return { ok: false, reason: activityState || "unknown_activity_state" };
     }
+    this.blockedStateSeen.delete(subscriber);
     return { ok: true, reason: "deliverable" };
   }
 
+  // Prefer meta.activity_since (written on state change); fall back to the
+  // first time this scheduler observed the state when the field is missing.
+  resolveBlockedStateSinceMs(subscriber, meta, activityState) {
+    const parsed = Date.parse(meta && meta.activity_since != null ? String(meta.activity_since) : "");
+    if (Number.isFinite(parsed)) return parsed;
+    const seen = this.blockedStateSeen.get(subscriber);
+    if (seen && seen.state === activityState) return seen.sinceMs;
+    const now = this.now();
+    this.blockedStateSeen.set(subscriber, { state: activityState, sinceMs: now });
+    return now;
+  }
+
   async deliverSubscriber(subscriber) {
     if (!subscriber) return { ok: false, delivered: 0, reason: "missing_subscriber" };
     if (this.locks.has(subscriber)) {
+      this.noteLocked(subscriber, this.locks.get(subscriber));
       return { ok: true, delivered: 0, deferred: true, reason: "locked" };
     }
 
-    this.locks.add(subscriber);
+    this.locks.set(subscriber, { sinceMs: this.now(), lastWarnAtMs: 0 });
     try {
       const gate = this.shouldDeliver(subscriber);
       if (!gate.ok) {
+        this.noteDeferral(subscriber, gate.reason);
         return { ok: true, delivered: 0, deferred: true, reason: gate.reason };
       }
+      if (gate.graceOverride) {
+        this.noteGraceOverride(subscriber, gate.graceOverride);
+      } else {
+        this.graceWarned.delete(subscriber);
+      }
+      this.clearDeferral(subscriber);
 
       const queue = this.queueFactory(subscriber);
       const claim = queue.claimNext();
@@ -114,9 +212,11 @@ class DeliveryScheduler {
       if (delivery.gate === "idle") {
         const secondGate = this.shouldDeliver(subscriber);
         if (!secondGate.ok) {
+          this.noteDeferral(subscriber, secondGate.reason);
           queue.restoreClaim(claim);
           return { ok: true, delivered: 0, deferred: true, reason: secondGate.reason };
         }
+        if (secondGate.graceOverride) this.noteGraceOverride(subscriber, secondGate.graceOverride);
       }
 
       const { agents } = this.getAgentMeta(subscriber);