talon-agent 5.18.2 → 5.19.0

package/src/core/agent-runtime/model-ref.ts

@@ -102,14 +102,6 @@ export interface ModelRef {
   unavailableReason?: string;
 }
 
-/**
- * Equality on identity only — two refs are the same run if they
- * point at the same backend + id.
- */
-export function sameModelRef(a: ModelRef, b: ModelRef): boolean {
-  return a.backend === b.backend && a.id === b.id;
-}
-
 /**
  * Bare-minimum constructor for tests and adapters that don't yet
  * carry rich metadata. Real catalog code should populate the

package/src/core/agents/registry.ts

@@ -25,6 +25,7 @@ import type { TaskUsage } from "../tasks/types.js";
 import type { AgentSettledEvent, AgentSpawnedEvent } from "../bus/events.js";
 import type { ReasoningEffortLevel } from "../types.js";
 import { bus } from "../bus/index.js";
+import { logWarn } from "../../util/log.js";
 
 /** Settled agents kept for status queries after they leave the live map. */
 const DEFAULT_HISTORY_LIMIT = 100;
@@ -87,6 +88,23 @@ interface LiveAgent {
   killRequested: boolean;
 }
 
+/**
+ * Whether two agents were spawned by the same parent.
+ *
+ * Compared structurally rather than by reference: records come from separate
+ * snapshots, so the parent objects are equal in value and never identical.
+ * The `kind` check is what stops a chat-parented agent matching an
+ * agent-parented one whose id happens to equal a chat key.
+ */
+function sameParent(a: AgentParent, b: AgentParent): boolean {
+  if (a.kind !== b.kind) return false;
+  return a.kind === "chat" && b.kind === "chat"
+    ? a.chatId === b.chatId
+    : a.kind === "agent" && b.kind === "agent"
+      ? a.agentId === b.agentId
+      : false;
+}
+
 function snapshot(entry: LiveAgent): AgentRecord {
   return {
     ...entry.record,
@@ -279,8 +297,13 @@ export class AgentRegistry {
       entry.killRequested = true;
       try {
         entry.abort?.abort();
-      } catch {
-        // An abort hook must not be able to break the kill path.
+      } catch (err) {
+        // An abort hook must not be able to break the kill path — but a
+        // throwing one may leave the agent running, so say so.
+        logWarn(
+          "agents",
+          `Abort hook threw agent=${id}: ${err instanceof Error ? err.message : String(err)}`,
+        );
       }
     }
     return true;
@@ -351,6 +374,30 @@ export class AgentRegistry {
     return children.filter((child) => this.live.has(child));
   }
 
+  /**
+   * An agent's live **peers** — the other agents sharing its parent.
+   *
+   * This is the addressing scope for agent-to-agent messaging, and it is
+   * deliberately narrower than "everything under the same chat". A swarm is
+   * a set of siblings spawned for one job, so siblings are the useful unit;
+   * widening to the whole chat tree would let an agent reach a cousin from an
+   * unrelated piece of work it knows nothing about.
+   *
+   * Live only: a settled agent has no mailbox to deliver into, and offering
+   * it as a peer would only produce a delivery failure one call later.
+   */
+  peersOf(id: string): AgentRecord[] {
+    const self = this.get(id);
+    if (!self) return [];
+    const peers: AgentRecord[] = [];
+    for (const entry of this.live.values()) {
+      const record = snapshot(entry);
+      if (record.id === id) continue;
+      if (sameParent(record.parent, self.parent)) peers.push(record);
+    }
+    return peers.sort((a, b) => a.createdAt - b.createdAt);
+  }
+
   /** Live agents plus the bounded settled ring, oldest first. */
   list(): AgentRecord[] {
     const records = [...this.history];

package/src/core/auth/expiry-monitor.ts

@@ -10,6 +10,7 @@
  */
 
 import { notifyAdmin } from "../frontend-runtime/admin-notify.js";
+import { logWarn } from "../../util/log.js";
 import {
   daysUntil,
   PROVIDER_LABELS,
@@ -75,7 +76,14 @@ export function resetAuthExpiryAnnouncements(): void {
 
 export function startAuthExpiryMonitor(): () => void {
   const tick = (): void => {
-    void runAuthExpiryCheck().catch(() => {});
+    void runAuthExpiryCheck().catch((err: unknown) => {
+      // The alert is already marked announced, so a failed send is not
+      // retried until the status changes — the log is its only trace.
+      logWarn(
+        "notify",
+        `auth expiry check failed: ${err instanceof Error ? err.message : String(err)}`,
+      );
+    });
   };
   // First check shortly after boot so a lapsed login is surfaced right away.
   const first = setTimeout(tick, 30_000);

package/src/core/auth/login-flow.ts

@@ -160,7 +160,15 @@ export function startLogin(
         new Error(outcome.ok ? "no prompt" : outcome.detail || outcome.reason),
       );
     if (tmpHome)
-      await rm(tmpHome, { recursive: true, force: true }).catch(() => {});
+      await rm(tmpHome, { recursive: true, force: true }).catch(
+        (err: unknown) =>
+          // The scratch HOME can hold a fresh credential copy — a leftover
+          // is worth knowing about.
+          logWarn(
+            "notify",
+            `${provider} login cleanup failed dir=${tmpHome}: ${err instanceof Error ? err.message : String(err)}`,
+          ),
+      );
     resolveDone(outcome);
   };
 

package/src/core/auth/status.ts

@@ -15,6 +15,7 @@
 import { readFile, stat } from "node:fs/promises";
 import { homedir } from "node:os";
 import { join } from "node:path";
+import { logWarn } from "../../util/log.js";
 
 export type AuthProvider = "claude" | "codex";
 
@@ -64,6 +65,19 @@ export function clearProviderExpired(provider: AuthProvider): void {
   reportedExpired.delete(provider);
 }
 
+/**
+ * A credentials file that exists but isn't JSON reads as "not signed
+ * in" — indistinguishable from a missing login unless logged. Nothing
+ * from the file goes into the line: JSON.parse's message quotes the
+ * input, and the input is a token.
+ */
+function warnUnparseable(provider: AuthProvider): void {
+  logWarn(
+    "notify",
+    `${provider} credentials file is not valid JSON — reporting not signed in`,
+  );
+}
+
 export function parseClaudeCredentials(raw: string): ProviderAuthStatus {
   const base: ProviderAuthStatus = {
     provider: "claude",
@@ -81,6 +95,7 @@ export function parseClaudeCredentials(raw: string): ProviderAuthStatus {
   try {
     parsed = JSON.parse(raw);
   } catch {
+    warnUnparseable("claude");
     return base;
   }
   const oauth = parsed.claudeAiOauth;
@@ -115,6 +130,7 @@ export function parseCodexAuth(raw: string): ProviderAuthStatus {
   try {
     parsed = JSON.parse(raw);
   } catch {
+    warnUnparseable("codex");
     return base;
   }
   const apiKey =
@@ -136,11 +152,23 @@ export function parseCodexAuth(raw: string): ProviderAuthStatus {
   };
 }
 
-async function readOrEmpty(path: string): Promise<string | undefined> {
+async function readOrEmpty(
+  provider: AuthProvider,
+  path: string,
+): Promise<string | undefined> {
   try {
     await stat(path);
     return await readFile(path, "utf8");
-  } catch {
+  } catch (err) {
+    // Missing is the normal signed-out case; anything else (EACCES,
+    // EISDIR) is a fault that would otherwise read as signed out too.
+    const code = (err as NodeJS.ErrnoException).code;
+    if (code !== "ENOENT") {
+      logWarn(
+        "notify",
+        `${provider} credentials unreadable code=${code ?? "?"} — reporting not signed in`,
+      );
+    }
     return undefined;
   }
 }
@@ -151,7 +179,7 @@ export async function readProviderStatus(
 ): Promise<ProviderAuthStatus> {
   const path =
     provider === "claude" ? claudeCredentialsPath(env) : codexAuthPath(env);
-  const raw = await readOrEmpty(path);
+  const raw = await readOrEmpty(provider, path);
   const status =
     raw === undefined
       ? { provider, loggedIn: false, expired: true }

package/src/core/background/cron/scheduler.ts

@@ -34,6 +34,8 @@ import {
 } from "../../../storage/cron.js";
 import { appendDailyLog } from "../../../storage/daily-log.js";
 import { log, logError, logWarn } from "../../../util/log.js";
+import { raiseAlert, resolveAlert } from "../../frontend-runtime/alerts.js";
+import { faultText } from "../../engine/fault-text.js";
 import { numericChatIdFor } from "../../frontend-runtime/chat-id.js";
 import {
   chooseBackend,
@@ -156,8 +158,12 @@ async function runCronTick(): Promise<void> {
   pruneJobHealth(new Set(jobs.map((j) => j.id)));
 
   let loadShed = false;
-  for (const job of jobs) {
-    if (!job.enabled) continue;
+  for (const listed of jobs) {
+    // Re-read: each run is awaited, so a slow job lets the next tick start
+    // and run later jobs before this loop reaches them. The listing's copy
+    // would carry the pre-run lastRunAt and fire such a job a second time.
+    const job = getCronJob(listed.id);
+    if (!job?.enabled) continue;
     // Expiry takes priority over dueness: a job past its end time is disabled
     // and skipped even if this minute would otherwise match.
     if (expireIfPast(job, nowMs)) continue;
@@ -201,6 +207,10 @@ async function runScheduled(job: CronJob): Promise<void> {
       durationMs: Date.now() - startedAt,
     };
     recordJobSuccess(job.id, Date.now(), JOB_HEALTH);
+    resolveAlert(
+      `cron.job.${job.id}`,
+      `Cron job "${job.name}" is running again.`,
+    );
     recordCronRun(job.id, outcome);
     appendDailyLog(
       "Cron",
@@ -223,12 +233,23 @@ async function runScheduled(job: CronJob): Promise<void> {
       lastError: err instanceof Error ? err.message : String(err),
       lastDurationMs: Date.now() - startedAt,
     });
-    logError("cron", `Job "${job.name}" [${job.id}] failed`, err);
+    logError(
+      "cron",
+      `Job "${job.name}" [${job.id}] failed chat=${job.chatId} type=${job.type} ms=${Date.now() - startedAt}`,
+      err,
+    );
     const cooldown = recordJobFailure(job.id, Date.now(), JOB_HEALTH);
     if (cooldown !== null) {
+      const mins = Math.round(cooldown / 60_000);
       logWarn(
         "cron",
-        `Breaker opened for "${job.name}" [${job.id}] — cooling down ~${Math.round(cooldown / 60_000)}min`,
+        `Breaker opened for "${job.name}" [${job.id}] — cooling down ~${mins}min`,
+      );
+      // The breaker opens at JOB_HEALTH.threshold consecutive failures —
+      // the job is now paused, which the operator should hear about.
+      raiseAlert(
+        `cron.job.${job.id}`,
+        `Cron job "${job.name}" failed ${JOB_HEALTH.threshold} runs in a row: ${faultText(err)}. Paused for ~${mins} min.`,
       );
     }
   } finally {
@@ -461,7 +482,6 @@ function isCronDue(job: CronJob, now: Date, windowStartMs: number): boolean {
 export const _cronInternals = {
   isDue,
   isCronDue,
-  MAX_TICK_LOOKBACK_MS,
 };
 
 /**

package/src/core/background/dream/index.ts

@@ -24,6 +24,7 @@ import type { Backend } from "../../agent-runtime/capabilities.js";
 import { taskTable } from "../../tasks/index.js";
 import { resolveBackgroundEffort } from "../effort.js";
 import { FailureBackoff } from "../failure-backoff.js";
+import { faultText } from "../../engine/fault-text.js";
 
 // ── Types ────────────────────────────────────────────────────────────────────
 
@@ -61,7 +62,10 @@ let dreaming = false; // in-process guard (one dream at a time)
  * every message (observed live: a model outage produced 403 identical
  * consolidation failures). Exported for tests.
  */
-export const dreamFailureBackoff = new FailureBackoff();
+export const dreamFailureBackoff = new FailureBackoff({
+  key: "dream.failing",
+  label: "Dream (memory consolidation)",
+});
 let configRef: {
   model?: string;
   dreamModel?: string;
@@ -141,6 +145,16 @@ export async function forceDream(): Promise<void> {
   await executeDream("forced");
 }
 
+/** Arm the failure backoff so maybeStartDream stays quiet for a while. */
+function backOff(err: unknown): void {
+  const until = dreamFailureBackoff.fail(err);
+  logWarn(
+    "dream",
+    `dream.backoff failures=${dreamFailureBackoff.failures} ` +
+      `until=${new Date(until).toISOString()} error="${faultText(err)}"`,
+  );
+}
+
 /** Shared dream execution — claims lock, runs agent, releases lock. */
 async function executeDream(trigger: "auto" | "forced"): Promise<void> {
   const state = readDreamState();
@@ -153,8 +167,13 @@ async function executeDream(trigger: "auto" | "forced"): Promise<void> {
 
   try {
     const dreamLogPath = await runDreamAgent(state?.last_run ?? 0);
-    writeDreamState({ last_run: Date.now(), status: "idle" });
-    dreamFailureBackoff.succeed();
+    // A run whose last_run didn't stick still looks overdue, and
+    // maybeStartDream would run it all again on the very next message.
+    if (writeDreamState({ last_run: Date.now(), status: "idle" })) {
+      dreamFailureBackoff.succeed();
+    } else {
+      backOff(new Error("dream state was not persisted"));
+    }
     log(
       "dream",
       `Memory consolidation complete (${trigger}), log: ${dreamLogPath}`,
@@ -164,12 +183,7 @@ async function executeDream(trigger: "auto" | "forced"): Promise<void> {
     writeDreamState({ last_run: state?.last_run ?? 0, status: "idle" });
     // A failed dream keeps the old last_run, so it would re-fire on the very
     // next invocation — back off instead (forceDream bypasses the window).
-    const until = dreamFailureBackoff.fail(err);
-    logWarn(
-      "dream",
-      `Backing off until ${new Date(until).toISOString()} ` +
-        `after ${dreamFailureBackoff.failures} consecutive failure(s)`,
-    );
+    backOff(err);
     if (trigger === "forced") throw err;
   } finally {
     dreaming = false;
@@ -427,10 +441,15 @@ function readDreamState(): DreamState | null {
   return parsed;
 }
 
-function writeDreamState(state: DreamState): void {
+/**
+ * Persist the state. Returns whether last_run actually landed: kvSet logs
+ * and swallows a failed write (full disk), so the store is read back.
+ */
+function writeDreamState(state: DreamState): boolean {
   const enriched: DreamState = {
     ...state,
     last_run_at: new Date(state.last_run).toISOString(),
   };
   kvSet(DREAM_STATE_KEY, enriched);
+  return readDreamState()?.last_run === state.last_run;
 }

package/src/core/background/failure-backoff.ts

@@ -15,8 +15,16 @@
  *
  * Backoff state is in-memory only: a process restart forgets it, which is
  * fine — the first post-restart attempt either works or re-arms the window.
+ *
+ * A holder built with an `alert` also tells the operator: once the streak
+ * reaches its threshold (2 by default — one failure is a blip, a second in
+ * a row after the backoff is a broken component) it raises `alert.key`
+ * with the error, and the next success resolves it.
  */
 
+import { faultText } from "../engine/fault-text.js";
+import { raiseAlert, resolveAlert } from "../frontend-runtime/alerts.js";
+
 const FAILURE_BACKOFF_BASE_MS = 5 * 60 * 1000;
 const FAILURE_BACKOFF_MAX_MS = 60 * 60 * 1000;
 /** Safety margin added past a parsed limit-reset time (clock skew, rollout). */
@@ -70,6 +78,16 @@ export function failureBackoffUntil(
   return now + exp;
 }
 
+/** Operator alert a backoff holder raises while its component keeps failing. */
+type BackoffAlert = {
+  /** Stable alert key, e.g. "heartbeat.failing". */
+  key: string;
+  /** What failed, for the message: "The heartbeat", "Dream (memory consolidation)". */
+  label: string;
+  /** Consecutive failures before raising. Default 2. */
+  threshold?: number;
+};
+
 /**
  * Per-component backoff holder. Cadence checks gate on `active()`; run
  * completions call `succeed()` / `fail(err)`.
@@ -78,6 +96,8 @@ export class FailureBackoff {
   private consecutiveFailures = 0;
   private until = 0;
 
+  constructor(private readonly alert?: BackoffAlert) {}
+
   /** True while inside the backoff window — the caller should skip firing. */
   active(now = Date.now()): boolean {
     return now < this.until;
@@ -87,6 +107,14 @@ export class FailureBackoff {
   fail(err: unknown, now = Date.now()): number {
     this.consecutiveFailures += 1;
     this.until = failureBackoffUntil(err, this.consecutiveFailures, now);
+    const alert = this.alert;
+    if (alert && this.consecutiveFailures >= (alert.threshold ?? 2)) {
+      const retryAt = new Date(this.until).toISOString().slice(11, 16);
+      raiseAlert(
+        alert.key,
+        `${alert.label} has failed ${this.consecutiveFailures} times in a row: ${faultText(err)}. Next attempt after ${retryAt} UTC.`,
+      );
+    }
     return this.until;
   }
 
@@ -94,6 +122,8 @@ export class FailureBackoff {
   succeed(): void {
     this.consecutiveFailures = 0;
     this.until = 0;
+    if (this.alert)
+      resolveAlert(this.alert.key, `${this.alert.label} is running again.`);
   }
 
   get failures(): number {

package/src/core/background/heartbeat/agent.ts

@@ -22,6 +22,7 @@ import {
   resolveRoutedModel,
 } from "../../engine/backend-router/index.js";
 import { resolveBackgroundEffort } from "../effort.js";
+import { raceWithTimeout } from "../isolated-agent.js";
 import { hb } from "./state.js";
 
 const DEFAULT_HEARTBEAT_TIMEOUT_MS = 10 * 60 * 1000; // 10-minute soft cap
@@ -88,7 +89,7 @@ export function buildHeartbeatSystemPrompt(): string {
 /**
  * Render the open-goal listing for the heartbeat prompt. Cross-chat by design:
  * the heartbeat is a global agent, so it sees every chat's open goals (with
- * chat ids for routing updates back). Exported for tests.
+ * chat ids for routing updates back).
  */
 function renderGoalsBlock(): { text: string; count: number } {
   let text = "(no open goals)";
@@ -486,32 +487,6 @@ export async function runHeartbeatAgent(
   return heartbeatLogFile;
 }
 
-/**
- * Race a promise against a timeout. Returns the promise's resolved value, or
- * the sentinel `"timed_out"` if the timeout fires first.
- *
- * NOTE: if `p` rejects before the timeout fires, that rejection propagates —
- * callers that need a never-throwing race should `.catch()` the input promise
- * themselves.
- */
-async function raceWithTimeout<T>(
-  p: Promise<T>,
-  ms: number,
-): Promise<T | "timed_out"> {
-  let t: ReturnType<typeof setTimeout> | null = null;
-  try {
-    return await Promise.race([
-      p,
-      new Promise<"timed_out">((resolve) => {
-        t = setTimeout(() => resolve("timed_out"), ms);
-        t.unref();
-      }),
-    ]);
-  } finally {
-    if (t) clearTimeout(t);
-  }
-}
-
 // ── Logging helpers ─────────────────────────────────────────────────────────
 
 async function createHeartbeatLogFile(): Promise<string> {

package/src/core/background/heartbeat/index.ts

@@ -9,8 +9,6 @@
  *   - `state`     — shared run-guard/timers/config + persisted-state I/O
  *   - `agent`     — prompt building + the one-shot agent run + log helpers
  *   - `scheduler` — init, the cadence timer, run guard, force/await/status API
- *
- * Re-exports the same public surface the old single-file module exposed.
  */
 
 export {

package/src/core/background/heartbeat/scheduler.ts

@@ -5,6 +5,7 @@
  */
 
 import { log, logError, logWarn } from "../../../util/log.js";
+import { faultText } from "../../engine/fault-text.js";
 import {
   catchupRunCount,
   missedRunCount,
@@ -147,6 +148,16 @@ export function getHeartbeatStatus(): HeartbeatState | null {
   return readHeartbeatState();
 }
 
+/** Arm the failure backoff so the due check stops re-firing for a while. */
+function backOff(err: unknown): void {
+  const until = hb.failureBackoff.fail(err);
+  logWarn(
+    "heartbeat",
+    `heartbeat.backoff failures=${hb.failureBackoff.failures} ` +
+      `until=${new Date(until).toISOString()} error="${faultText(err)}"`,
+  );
+}
+
 async function executeHeartbeat(trigger: "auto" | "forced"): Promise<void> {
   if (hb.running) return;
 
@@ -175,13 +186,16 @@ async function executeHeartbeat(trigger: "auto" | "forced"): Promise<void> {
         previousRunCount + 1,
       );
       // Only update last_run and increment run_count on success
-      writeHeartbeatState({
+      const persisted = writeHeartbeatState({
         last_run: Date.now(),
         last_started: now,
         status: "idle",
         run_count: previousRunCount + 1,
       });
-      hb.failureBackoff.succeed();
+      // A run whose last_run didn't stick looks overdue to the next due
+      // check, which would run the whole agent again every minute.
+      if (persisted) hb.failureBackoff.succeed();
+      else backOff(new Error("heartbeat state was not persisted"));
       log(
         "heartbeat",
         `Heartbeat #${previousRunCount + 1} complete (${trigger}), log: ${heartbeatLogPath}`,
@@ -197,23 +211,17 @@ async function executeHeartbeat(trigger: "auto" | "forced"): Promise<void> {
       // re-triggering against the same `last_run` forever. Non-timeout errors
       // retry from the previous successful run (no budget consumed).
       const isTimeout = err instanceof HeartbeatTimeoutError;
-      writeHeartbeatState({
+      const persisted = writeHeartbeatState({
         last_run: isTimeout ? Date.now() : previousLastRun,
         last_started: now,
         status: "idle",
         run_count: isTimeout ? previousRunCount + 1 : previousRunCount,
       });
       // Timeouts advance last_run (budget consumed), so the cadence itself
-      // spaces the next attempt. Every other failure retries against the same
-      // last_run — back off so the due check doesn't hammer it every minute.
-      if (!isTimeout) {
-        const until = hb.failureBackoff.fail(err);
-        logWarn(
-          "heartbeat",
-          `Backing off until ${new Date(until).toISOString()} ` +
-            `after ${hb.failureBackoff.failures} consecutive failure(s)`,
-        );
-      }
+      // spaces the next attempt — if that write landed. Every other failure
+      // retries against the same last_run — back off so the due check
+      // doesn't hammer it every minute.
+      if (!isTimeout || !persisted) backOff(err);
       if (trigger === "forced") throw err;
     } finally {
       hb.running = false;

package/src/core/background/heartbeat/state.ts

@@ -100,7 +100,10 @@ export const hb: {
   intervalMinutesRef: 60,
   config: null,
   logFileSequence: 0,
-  failureBackoff: new FailureBackoff(),
+  failureBackoff: new FailureBackoff({
+    key: "heartbeat.failing",
+    label: "The heartbeat",
+  }),
 };
 
 // ── State-file I/O ───────────────────────────────────────────────────────────
@@ -160,7 +163,11 @@ export function readHeartbeatState(): HeartbeatState | null {
   return normalizeHeartbeatState(kvGet(HEARTBEAT_STATE_KEY));
 }
 
-export function writeHeartbeatState(state: HeartbeatState): void {
+/**
+ * Persist the state. Returns whether last_run actually landed: kvSet logs
+ * and swallows a failed write (full disk), so the store is read back.
+ */
+export function writeHeartbeatState(state: HeartbeatState): boolean {
   // Re-derive last_run_at from last_run so the persisted ISO stamp can
   // never drift from the millisecond field; omit it on the sentinel
   // last_run === 0 (never-run) to match the pre-SQLite file format.
@@ -172,4 +179,5 @@ export function writeHeartbeatState(state: HeartbeatState): void {
       : {}),
   };
   kvSet(HEARTBEAT_STATE_KEY, enriched);
+  return readHeartbeatState()?.last_run === state.last_run;
 }

package/src/core/background/isolated-agent.ts

@@ -50,8 +50,12 @@ export interface IsolatedRunOptions {
   readonly logCategory?: LogComponent;
 }
 
-/** Resolves to the value, or the string "timed_out" if `ms` elapses first. */
-async function raceWithTimeout<T>(
+/**
+ * Resolves to the value, or the string "timed_out" if `ms` elapses first.
+ * A rejection of `promise` inside the window propagates — `.catch()` it
+ * first for a never-throwing race.
+ */
+export async function raceWithTimeout<T>(
   promise: Promise<T>,
   ms: number,
 ): Promise<T | "timed_out"> {

package/src/core/background/pulse/pulse.ts

@@ -27,6 +27,8 @@ import { formatSmartTimestamp } from "../../../util/time.js";
 let timer: ReturnType<typeof setInterval> | null = null;
 const registeredChats = new Set<string>();
 const lastCheckMessageId = new Map<string, number>();
+/** Chats whose pulse turn is still queued or running. */
+const inFlight = new Set<string>();
 
 const DEFAULT_INTERVAL_MS = 5 * 60 * 1000; // 5 minutes
 let activeIntervalMs = DEFAULT_INTERVAL_MS;
@@ -126,6 +128,10 @@ async function runPulse(): Promise<void> {
 }
 
 async function pulseChat(chatId: string): Promise<void> {
+  // The pulse turn queues behind the chat's other turns, so it can outlast
+  // the interval. Until it settles the checkpoint hasn't moved, and the next
+  // tick would dispatch the same unread messages a second time.
+  if (inFlight.has(chatId)) return;
   const numericChatId = parseInt(chatId, 10);
   if (isNaN(numericChatId)) {
     logError("pulse", `Invalid chatId: ${chatId}`);
@@ -157,6 +163,7 @@ async function pulseChat(chatId: string): Promise<void> {
     })
     .join("\n");
 
+  inFlight.add(chatId);
   try {
     const prompt =
       `[System: Pulse check — ${unread.length} new message(s) since last check. ` +
@@ -179,5 +186,7 @@ async function pulseChat(chatId: string): Promise<void> {
   } catch (err) {
     logError("pulse", `Chat ${chatId} failed`, err);
     // Don't update lastCheckMessageId — messages will be retried next pulse
+  } finally {
+    inFlight.delete(chatId);
   }
 }