switchroom 0.18.10 → 0.18.12

package/telegram-plugin/typing-emitter.ts

@@ -0,0 +1,224 @@
+/**
+ * The single gate every `sendChatAction` in the gateway passes through (#3084).
+ *
+ * WHY THIS EXISTS — the 2026-07-11 flood ban
+ * ------------------------------------------
+ * The typing indicator used to be "a 4 s interval", which sounds rate-limited
+ * and is not. Both typing loops (`startTypingLoop` in gateway.ts and the
+ * turn-level `createTurnTypingLoop`) are restart-safe by design: a re-start
+ * clears the old interval and fires ONE action immediately so "typing…" lands
+ * instantly. The tool-use wrapper restarts the loop on every tool call, so the
+ * ping rate tracked the AGENT'S TOOL-CALL RATE, not the 4 s cadence — the
+ * interval was decorative. On 2026-07-11 `overlord` emitted 8,729
+ * sendChatAction calls (55% of all outbound volume, bursting at 200-300/min
+ * into ONE DM) to deliver 203 messages, and earned a per-bot-token flood ban:
+ * `429 retry_after=16739s` — 4.6 hours with every outbound reply rejected.
+ *
+ * The old code comment said the redundant pings were "harmless — same action,
+ * and sendChatAction is cheap." They are not cheap. They spend the per-bot
+ * flood budget the REPLIES need.
+ *
+ * WHAT THIS ENFORCES
+ * ------------------
+ *   1. A per-chat-key emission FLOOR. At most one chat action per key per
+ *      `floorMs` (~4 s refresh window), no matter how many loops restart, from
+ *      which caller, on which surface. Both loops share ONE emitter, so the
+ *      floor holds ACROSS them — they target the same chat key and neither can
+ *      out-shout the other. This is what structurally decouples ping rate from
+ *      tool-call rate.
+ *   2. The UX intent survives: a COLD start (no ping for this key inside the
+ *      floor) still fires immediately, so "typing…" lands the moment a turn
+ *      begins. Only the REDUNDANT restarts are dropped — and a dropped tick is
+ *      never silently lost: it arms a COALESCED catch-up at the instant the
+ *      window opens, so the worst-case gap between two emissions is `floorMs`
+ *      (3.5 s), comfortably inside Telegram's ~5 s action expiry. Without it,
+ *      an eaten tick on a fixed-cadence loop pushes the next emission out to
+ *      `floorMs + refreshMs` = 7.5 s and the chat goes DARK mid-turn — trading
+ *      a flood ban for a dead indicator, which is not a trade we make.
+ *   3. NON-ESSENTIAL by definition: while a flood-wait window is open
+ *      (`isSuppressed`, wired to the #2923 circuit breaker) no typing is
+ *      emitted at all. It cannot succeed, and sending into an open window can
+ *      extend the ban.
+ *
+ * The window is claimed on every attempt that PASSES the floor, including one
+ * suppressed by a flood window. That is deliberate: it bounds the flood-state
+ * read to once per floor per chat instead of once per tool call.
+ *
+ * Pure + injectable (clock, send, chat-key, suppression) so the whole gate is
+ * unit-testable on a fake clock without a bot — `tests/typing-emitter.test.ts`.
+ */
+
+/** Refresh cadence of the typing loops. Telegram's `typing` expires at ~5 s. */
+export const TYPING_REFRESH_MS = 4000
+
+/**
+ * Minimum gap between two chat actions on one chat key. Deliberately a hair
+ * UNDER `TYPING_REFRESH_MS` so a loop's own on-time refresh is never eaten by
+ * timer jitter (a 3999 ms tick would be dropped by a 4000 ms floor, and the
+ * indicator would go dark for a whole window). The gap between successive
+ * emissions therefore stays under Telegram's ~5 s action expiry, while the
+ * worst-case rate falls from the observed ~300/min to ~17/min per chat.
+ */
+export const TYPING_FLOOR_MS = 3500
+
+export interface TypingEmitterDeps {
+  /** Perform the actual chat action. Errors are the caller's concern — the
+   *  emitter never throws and never awaits. */
+  send: (chatId: string, threadId: number | null, action: string) => void
+  /** Canonical chat:thread key (the gateway's `chatKey`) — a supergroup topic
+   *  is its own lane and gets its own floor. */
+  chatKey: (chatId: string, threadId: number | null) => string
+  /** True while a flood-wait window is open. Typing is non-essential: while
+   *  this is true nothing is emitted. Defaults to "never suppressed". */
+  isSuppressed?: () => boolean
+  /** Injected clock (tests pass a fake). */
+  now?: () => number
+  /** Per-key emission floor in ms. */
+  floorMs?: number
+  /** Injected timer for the catch-up (tests pass fake timers). */
+  schedule?: (fn: () => void, ms: number) => unknown
+  /** Cancel a handle returned by `schedule`. */
+  cancel?: (handle: unknown) => void
+  /** Observability hook — fires for each dropped emission. */
+  onDrop?: (info: { key: string; reason: 'floor' | 'flood' }) => void
+}
+
+export interface TypingEmitter {
+  /**
+   * Emit one chat action for (chatId, threadId), subject to the floor and the
+   * flood gate. Returns true iff the action was actually handed to `send`.
+   * A floor-dropped emission arms a coalesced catch-up (see below), so the
+   * caller's cadence is never silently lost.
+   */
+  emit: (chatId: string, threadId?: number | null, action?: string) => boolean
+  /**
+   * Cancel any pending catch-up for a chat key. The canonical turn-end calls
+   * this so a dropped tick can't resurrect "typing…" after the turn is over.
+   * Does NOT clear the floor — the floor must survive loop stops, because the
+   * tool loop stops on every tool result and that is precisely the churn the
+   * floor exists to absorb.
+   */
+  cancelPending: (chatId: string, threadId?: number | null) => void
+  /** Test/observability: number of chat keys currently tracked. */
+  trackedKeys: () => number
+  /** Test/observability: number of catch-ups currently armed (0 ⇒ none leaked). */
+  pendingCatchUps: () => number
+  /** Drop all floor state and cancel every catch-up (shutdown / tests). */
+  reset: () => void
+}
+
+/** Keep the floor map from growing without bound in a long-lived gateway. */
+const PRUNE_AFTER_FACTOR = 10
+const PRUNE_SIZE_THRESHOLD = 64
+
+export function createTypingEmitter(deps: TypingEmitterDeps): TypingEmitter {
+  const floorMs = deps.floorMs ?? TYPING_FLOOR_MS
+  const now = deps.now ?? Date.now
+  const isSuppressed = deps.isSuppressed ?? (() => false)
+  const schedule =
+    deps.schedule ??
+    ((fn: () => void, ms: number) => {
+      const h = setTimeout(fn, ms)
+      ;(h as { unref?: () => void }).unref?.()
+      return h
+    })
+  const cancel =
+    deps.cancel ?? ((h: unknown) => clearTimeout(h as ReturnType<typeof setTimeout>))
+
+  /** chat key → epoch ms at which the current emission window was claimed. */
+  const windowClaimedAt = new Map<string, number>()
+  /** chat key → the single armed catch-up timer (coalesced; never two). */
+  const catchUps = new Map<string, unknown>()
+
+  function prune(t: number): void {
+    if (windowClaimedAt.size <= PRUNE_SIZE_THRESHOLD) return
+    const cutoff = t - floorMs * PRUNE_AFTER_FACTOR
+    for (const [k, ts] of [...windowClaimedAt.entries()]) {
+      if (ts < cutoff && !catchUps.has(k)) windowClaimedAt.delete(k)
+    }
+  }
+
+  function clearCatchUp(key: string): void {
+    const h = catchUps.get(key)
+    if (h !== undefined) {
+      cancel(h)
+      catchUps.delete(key)
+    }
+  }
+
+  /**
+   * A dropped tick MUST NOT become silence. Both loops re-arm a FIXED-cadence
+   * interval, so a tick eaten by the floor is simply lost: the next emission
+   * for that key could land as late as `floorMs + refreshMs` (7.5 s) after the
+   * last one — past Telegram's ~5 s chat-action expiry, and the chat goes dark
+   * mid-turn. That would trade a flood ban for a dead "typing…" indicator,
+   * which breaches `know-what-my-agent-is-doing` ("stays present from receipt
+   * to turn end").
+   *
+   * So a floor drop arms ONE coalesced catch-up at the exact moment the window
+   * opens (`claimedAt + floorMs`). Effect: the worst-case gap between two
+   * emissions is bounded by `floorMs`, while the emission CAP is untouched (the
+   * catch-up fires only once the floor has expired, so it can never emit early).
+   * A second drop inside the same window must not arm a second timer — hence
+   * the coalesce.
+   */
+  function armCatchUp(
+    key: string,
+    chatId: string,
+    threadId: number | null,
+    action: string,
+    delayMs: number,
+  ): void {
+    if (catchUps.has(key)) return // coalesced — one timer per key, always
+    const h = schedule(() => {
+      catchUps.delete(key)
+      // Re-enters `emit`, which re-checks the floor (now expired) and the flood
+      // gate. A send here cancels nothing — there is nothing left to cancel.
+      emit(chatId, threadId, action)
+    }, Math.max(0, delayMs))
+    catchUps.set(key, h)
+  }
+
+  function emit(chatId: string, threadId: number | null = null, action = 'typing'): boolean {
+    const key = deps.chatKey(chatId, threadId ?? null)
+    const t = now()
+    const claimed = windowClaimedAt.get(key)
+    // `t >= claimed` guards a backwards clock step (NTP): a stale future
+    // timestamp must not wedge the indicator off, so treat it as expired.
+    if (claimed != null && t >= claimed && t - claimed < floorMs) {
+      armCatchUp(key, chatId, threadId ?? null, action, claimed + floorMs - t)
+      deps.onDrop?.({ key, reason: 'floor' })
+      return false
+    }
+    // Claim the window BEFORE the flood check so a burst of restarts costs
+    // one flood-state read per floor, not one per restart.
+    windowClaimedAt.set(key, t)
+    prune(t)
+    if (isSuppressed()) {
+      // A flood window is open. Don't arm a catch-up — the goal is silence, not
+      // a deferred ping into the ban.
+      clearCatchUp(key)
+      deps.onDrop?.({ key, reason: 'flood' })
+      return false
+    }
+    // This send satisfies whatever a pending catch-up was going to deliver.
+    // Cancelling it here is what keeps a catch-up from re-arming itself into a
+    // self-sustaining heartbeat after the loops have stopped.
+    clearCatchUp(key)
+    deps.send(chatId, threadId ?? null, action)
+    return true
+  }
+
+  return {
+    emit,
+    cancelPending(chatId, threadId = null) {
+      clearCatchUp(deps.chatKey(chatId, threadId ?? null))
+    },
+    trackedKeys: () => windowClaimedAt.size,
+    pendingCatchUps: () => catchUps.size,
+    reset: () => {
+      for (const key of [...catchUps.keys()]) clearCatchUp(key)
+      windowClaimedAt.clear()
+    },
+  }
+}

package/telegram-plugin/uat/scenarios/jtbd-feel-like-a-colleague-dm.test.ts

@@ -0,0 +1,136 @@
+/**
+ * JTBD scenario — feel like a colleague, not a chatbot (DM).
+ *
+ * Serves: `reference/jobs/feel-like-a-colleague.md`. The colleague posture
+ * is shipped fleet-wide as lane-2 model-visible text (`~/.switchroom/fleet/
+ * CLAUDE.md`, seeded by `renderFleetDefaultsClaudeMd()` in
+ * `src/agents/fleet-defaults.ts`, epic #1850 / issue #1855). One bullet of
+ * "Good looks like" reads:
+ *
+ *   "The agent asks at most one good clarifying question, and skips it when
+ *    intent is clear, stating its assumption inline as it acts."
+ *
+ * This scenario sends a genuinely ambiguous request and asserts the agent
+ * asks EXACTLY ONE clarifying question rather than a question avalanche
+ * (the "Bad looks like" failure) or a confident guess that ignores the
+ * ambiguity.
+ *
+ * Gating: like every file under `telegram-plugin/uat/scenarios/`, this hits
+ * real Telegram + real Claude and only runs under `vitest.uat.config.ts`
+ * (`bun run test:uat`). The default vitest config excludes this directory,
+ * so CI stays green without live credentials.
+ */
+
+import { describe, it, expect } from "vitest";
+import { spinUp } from "../harness.js";
+
+const AGENT = "test-harness";
+
+// Ambiguous on purpose: "the report" has no referent, no format, no
+// destination. A colleague asks which report / what for; it does not
+// silently invent one, and it does not fire three questions.
+const AMBIGUOUS_PROMPT = "can you send over the report when you get a sec?";
+
+/**
+ * Count clarifying questions the agent itself asks. We count sentences
+ * ending in a question mark AFTER stripping spans where a `?` is not a
+ * question the agent is asking: URLs (query strings), inline/fenced code,
+ * and quoted echoes of the user's own words. Rhetorical framing
+ * ("sure, which one?") counts as one question; the invariant is at most one.
+ */
+function countQuestions(text: string): number {
+  const stripped = text
+    // Fenced code blocks, then inline code spans.
+    .replace(/```[\s\S]*?```/g, " ")
+    .replace(/`[^`\n]*`/g, " ")
+    // URLs — `?` here is a query string, not a question.
+    .replace(/\bhttps?:\/\/\S+/gi, " ")
+    .replace(/\bwww\.\S+/gi, " ")
+    // Quoted spans — the agent echoing the user ("you said 'which report?'")
+    // is not the agent asking a question.
+    .replace(/"[^"\n]*"/g, " ")
+    // Single-quoted spans must OPEN at a word boundary so apostrophes in
+    // contractions ("don't", "user's") are not misread as quote delimiters.
+    .replace(/(^|[\s([{])'[^'\n]*'/g, "$1 ")
+    .replace(/[“”][^“”\n]*[“”]/g, " ")
+    // Markdown blockquote lines are quoted material, not the agent's voice.
+    .replace(/^\s*>.*$/gm, " ");
+  const matches = stripped.match(/[^.!?\n]*\?/g);
+  if (matches == null) return 0;
+  // Filter out trivial fragments (a lone "?" or whitespace) that are not
+  // real questions.
+  return matches.filter((m) => m.replace(/[^a-z0-9]/gi, "").length >= 3).length;
+}
+
+/**
+ * `true` for bot messages that are infrastructure cards rather than a
+ * conversational reply: the boot/greeting card (always delivered with the
+ * Telegram `silent` flag — see boot-card.ts "Boot cards are ALWAYS
+ * delivered silently"), edits of earlier messages, and anything matching
+ * the known boot-card header shape (`✅ <agent> back up · <version>`).
+ */
+function isInfrastructureCard(m: {
+  text: string;
+  silent: boolean;
+  edited: boolean;
+}): boolean {
+  if (m.silent || m.edited) return true;
+  return /back up ·|^✅ /u.test(m.text.trim());
+}
+
+describe("uat: feel like a colleague — one clarifying question when ambiguous", () => {
+  it(
+    "ambiguous ask → agent asks exactly one clarifying question",
+    async () => {
+      const sc = await spinUp({ agent: AGENT });
+      try {
+        await sc.sendDM(AMBIGUOUS_PROMPT);
+
+        // Substantive replies only: skip the boot/greeting card and any
+        // silent interim edits so the assertion runs against the agent's
+        // actual conversational answer to the prompt.
+        const reply = await sc.expectMessage(
+          (m) => /\S/.test(m.text) && !isInfrastructureCard(m),
+          {
+            from: "bot",
+            timeout: 90_000,
+          },
+        );
+
+        expect(reply.text.length).toBeGreaterThan(0);
+
+        const questionCount = countQuestions(reply.text);
+
+        // Invariant: at least one clarifying question (it did not guess
+        // blindly) and at most one (no question avalanche).
+        if (questionCount === 0) {
+          throw new Error(
+            `[colleague] ambiguous ask got no clarifying question — the ` +
+            `agent either guessed a referent or ignored the ambiguity. ` +
+            `Reply: ${JSON.stringify(reply.text.slice(0, 300))}`,
+          );
+        }
+        if (questionCount > 1) {
+          throw new Error(
+            `[colleague] question avalanche: ${questionCount} questions ` +
+            `where one would do. Reply: ${JSON.stringify(reply.text.slice(0, 300))}`,
+          );
+        }
+        expect(questionCount).toBe(1);
+
+        // Posture bonus: no sycophantic preamble. A soft forensic warn,
+        // not a hard fail (voice specifics are audited in
+        // fuzz-voice-scrub-dm).
+        if (/^(great question|i'?d be happy to|absolutely!|of course!)/i.test(reply.text.trim())) {
+          console.warn(
+            `[colleague] reply opens with sycophantic preamble: ` +
+            `${JSON.stringify(reply.text.slice(0, 120))}`,
+          );
+        }
+      } finally {
+        await sc.tearDown();
+      }
+    },
+    120_000,
+  );
+});

package/telegram-plugin/welcome-text.ts

@@ -93,6 +93,27 @@ export type AgentMetadata = {
    * asked for current state, so terseness loses to completeness here.
    */
   live?: StatusProbeRow[];
+  /**
+   * Send-gate state (#3084 PR 3, part3-design §6). Present only when the gate
+   * feature flag is ON; omitted entirely when off so `/status` looks exactly
+   * as it did before the gate existed.
+   */
+  sendGate?: SendGateStatus;
+};
+
+/**
+ * `/status` view of the deterministic send gate (#3084). Queued / shed totals
+ * plus any open flood windows with their expiry. Only populated when the gate
+ * is enabled.
+ */
+export type SendGateStatus = {
+  queued: number;
+  shed: number;
+  expired: number;
+  failedFast: number;
+  dropped: number;
+  /** Currently-open flood windows (expired already pruned). */
+  openWindows: { scopeKey: string; untilTs: number }[];
 };
 
 // Markdown escaper for dynamic values interpolated into bold/plain card
@@ -231,6 +252,27 @@ export function statusPairedText(params: {
     }
   }
 
+  // Send-gate block (#3084 PR 3) — only when the gate flag is on, so a fleet
+  // running with the gate OFF sees the identical pre-gate /status.
+  if (meta.sendGate) {
+    const sg = meta.sendGate;
+    lines.push("");
+    lines.push("**Send gate**");
+    lines.push(
+      `queued ${sg.queued} · shed ${sg.shed} · expired ${sg.expired} · ` +
+        `fail-fast ${sg.failedFast} · dropped ${sg.dropped}`,
+    );
+    if (sg.openWindows.length > 0) {
+      const now = Date.now();
+      for (const w of sg.openWindows) {
+        const secs = Math.max(0, Math.round((w.untilTs - now) / 1000));
+        lines.push(`⏳ flood window \`${escapeHtml(w.scopeKey)}\` — clears in ${secs}s`);
+      }
+    } else {
+      lines.push("no open flood windows");
+    }
+  }
+
   const audit = meta.audit;
   if (audit) {
     // Blank separator before the audit block so the reply reads as two

package/vendor/hindsight-memory/scripts/drain_pending.py

@@ -9,15 +9,22 @@ the queue no longer drains it but the operator can still inspect via
 
 Boundaries
 ----------
-* Per-entry HTTP timeout: ``HINDSIGHT_DRAIN_TIMEOUT`` (default 5s).
+* Per-entry HTTP timeout: ``HINDSIGHT_DRAIN_TIMEOUT`` (default 5s), but
+  clamped per entry to the budget still remaining (see below) so a
+  single slow entry can never overshoot the wall-clock cap. The default
+  timeout (5s) intentionally exceeds the default budget (4s): the clamp,
+  not the raw timeout, is what bounds a slow entry.
+* Total wall-clock cap: ``HINDSIGHT_DRAIN_BUDGET_S`` (default 4s) so
+  drain never blocks SessionStart longer than the upstream hook timeout
+  permits. This is the authoritative bound; the per-entry timeout is
+  clamped down to ``max(1, remaining budget)`` before each request, so
+  even one slow upstream entry overshoots the budget by at most the
+  clamp floor (~1s), not by ``HINDSIGHT_DRAIN_TIMEOUT - budget``.
 * Stall guard: if ``STALL_THRESHOLD`` (3) consecutive entries fail with
   the same error class, we stop draining for this session — that's a
   systemic outage, not a transient flake, and continuing would only
   burn the SessionStart timeout budget. The remaining entries stay
   queued for the next session.
-* Total wall-clock cap: ``HINDSIGHT_DRAIN_BUDGET_S`` (default 4s) so
-  drain never blocks SessionStart longer than the upstream
-  hook timeout permits.
 
 Standalone usage::
 
@@ -113,13 +120,22 @@ def drain(config: dict | None = None) -> dict:
     last_error_class: str | None = None
 
     for path, entry in entries:
-        if time.monotonic() - started > budget:
+        elapsed = time.monotonic() - started
+        if elapsed > budget:
             summary["budget_exceeded"] = True
             debug_log(config, "drain_pending: total budget exceeded, stopping")
             break
 
+        # Clamp the per-entry HTTP timeout to the budget still remaining
+        # (#1094 item 2). Without this, a single slow entry using the full
+        # HINDSIGHT_DRAIN_TIMEOUT (default 5s) overshoots the total budget
+        # (default 4s). Floor at 1s so we still give a near-exhausted
+        # budget one bounded shot rather than a 0s (instant-fail) request.
+        remaining = budget - elapsed
+        effective_timeout = max(1, min(timeout, int(remaining) if remaining >= 1 else 1))
+
         try:
-            _retry_one(entry, timeout=timeout)
+            _retry_one(entry, timeout=effective_timeout)
         except Exception as e:
             err_class = type(e).__name__
             if err_class == last_error_class:

package/vendor/hindsight-memory/scripts/lib/client.py

@@ -93,15 +93,22 @@ class HindsightClient:
                 pass
             raise RuntimeError(f"HTTP {e.code} from {url}: {body_text}") from e
 
-    def health_check(self, timeout: int = 5) -> bool:
+    def health_check(self, timeout: int = 5, retries: int = HEALTH_CHECK_RETRIES) -> bool:
         """Check if the Hindsight server is reachable.
 
-        Mirrors Openclaw's checkExternalApiHealth: retries up to 3 times
-        with 2s delay between attempts.
+        Mirrors Openclaw's checkExternalApiHealth: retries up to
+        ``retries`` times (default ``HEALTH_CHECK_RETRIES`` = 3) with
+        ``HEALTH_CHECK_DELAY`` (2s) between attempts.
+
+        Time-budgeted callers (e.g. the SessionStart drain gate,
+        #1094) should pass ``retries=1``: against a HUNG server the
+        default loop costs ~retries*timeout + (retries-1)*delay of wall
+        clock, which blows a 5s hook budget.
         """
         import time
 
-        for attempt in range(1, HEALTH_CHECK_RETRIES + 1):
+        retries = max(1, retries)
+        for attempt in range(1, retries + 1):
             try:
                 url = f"{self.api_url}/health"
                 req = urllib.request.Request(url, headers=self._headers(), method="GET")
@@ -110,7 +117,7 @@ class HindsightClient:
                         return True
             except Exception:
                 pass
-            if attempt < HEALTH_CHECK_RETRIES:
+            if attempt < retries:
                 time.sleep(HEALTH_CHECK_DELAY)
         return False
 

package/vendor/hindsight-memory/scripts/lib/directives.py

@@ -183,6 +183,27 @@ def parse_active_directives_block(text: str) -> list:
     return contents
 
 
+# Length-aware guard for terse rules (#2912). Forward coverage alone
+# (|rule ∩ directive| / |rule|) is easy to satisfy when the rule has only a
+# couple of significant tokens: any long directive that happens to contain
+# those few words scores ~1.0 and silently swallows a genuinely-new short
+# rule, skipping a legitimate re-prompt. For such short rules we additionally
+# require REVERSE coverage — the matched directive's significant-token set must
+# also be substantially covered by the rule's — which is a Jaccard-style
+# bidirectional check. That fails precisely the "few tokens diluted inside a
+# long unrelated directive" case while still passing a terse rule that restates
+# a comparably terse directive.
+#
+# Constants chosen against the real tokenizer output:
+#   - < 4 significant tokens is "short" (1-3 tokens: the regime where a single
+#     incidental word swings forward coverage past 0.6).
+#   - reverse coverage >= 0.5 keeps near-equal-size restatements deduped
+#     (e.g. a 2-token rule vs a 4-token directive → 2/4 = 0.5) but rejects a
+#     2-token rule diluted inside a 6+-token directive (2/6 ≈ 0.33 < 0.5).
+_SHORT_RULE_TOKEN_LIMIT = 4
+_SHORT_RULE_REVERSE_COVERAGE = 0.5
+
+
 def rule_already_captured(
     rule_text: str, directive_contents: list, threshold: float = 0.6
 ) -> bool:
@@ -193,15 +214,29 @@ def rule_already_captured(
     best-matching directive. A high coverage ratio means the restated rule adds
     (almost) no new significant words over one already stored — i.e. a
     duplicate. Deterministic; no model/API call.
+
+    For terse rules (fewer than ``_SHORT_RULE_TOKEN_LIMIT`` significant tokens)
+    forward coverage is not sufficient — see the module comment above — so a
+    reverse-coverage guard is also required before declaring a match.
     """
     rule_tokens = _dedup_tokens(rule_text)
     if not rule_tokens:
         return False
+    is_short_rule = len(rule_tokens) < _SHORT_RULE_TOKEN_LIMIT
     for content in directive_contents:
         d_tokens = _dedup_tokens(content)
         if not d_tokens:
             continue
-        covered = len(rule_tokens & d_tokens) / len(rule_tokens)
-        if covered >= threshold:
-            return True
+        intersection = len(rule_tokens & d_tokens)
+        covered = intersection / len(rule_tokens)
+        if covered < threshold:
+            continue
+        if is_short_rule:
+            # Bidirectional guard: the directive must not be much larger than
+            # the rule, or those few shared tokens are incidental overlap
+            # rather than a true restatement.
+            reverse_covered = intersection / len(d_tokens)
+            if reverse_covered < _SHORT_RULE_REVERSE_COVERAGE:
+                continue
+        return True
     return False

package/vendor/hindsight-memory/scripts/lib/pending.py

@@ -197,22 +197,49 @@ def update_attempt(path: str, entry: dict, error: BaseException) -> bool:
 
 def mark_dead(path: str, entry: dict) -> Optional[str]:
     """Convert an entry that exceeded ``MAX_ATTEMPTS`` into a permanent
-    failure marker. Renames ``<path>`` to ``<path>.dead`` so the queue
-    no longer drains it but operators can still inspect.
-
-    Returns the marker path, or ``None`` if the rename failed.
+    failure marker at ``<path>.dead`` so the queue no longer drains it
+    but operators can still inspect.
+
+    Returns the marker path, or ``None`` if it failed.
+
+    Crash-window invariant (#1094 item 3): **a live ``<path>.json`` entry
+    must never carry a ``dead_at`` stamp.** The old two-step form violated
+    this — it wrote the dead_at-stamped payload back to the *live* path
+    (rename tmp -> path) and only then renamed path -> path.dead, so a
+    crash between the two renames left a live entry with ``dead_at`` set
+    that the drainer would re-enter and re-bump. Here we instead:
+
+      1. write the dead_at-stamped payload to ``<path>.tmp``
+      2. ``os.replace(tmp, dead_path)``  — the .dead marker appears in one
+         atomic step (never drained: the drainer only lists ``*.json``)
+      3. ``os.unlink(path)``            — drop the original live entry
+
+    At every crash point the invariant holds: the ``dead_at`` stamp only
+    ever lands on ``<path>.dead``. A crash after step 2 leaves both the
+    (stale, no-dead_at) live entry and the .dead marker; the next drain
+    re-marks it dead (os.replace overwrites the marker idempotently),
+    never observing a live entry with dead_at.
     """
     entry["dead_at"] = time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())
     dead_path = path + ".dead"
+    tmp = path + ".tmp"
     try:
-        # Best-effort: write the final state first so the marker shows
-        # the death timestamp + last error.
-        tmp = path + ".tmp"
         with open(tmp, "w", encoding="utf-8") as f:
             json.dump(entry, f, ensure_ascii=False)
         os.chmod(tmp, 0o600)
-        os.rename(tmp, path)
-        os.rename(path, dead_path)
+        os.replace(tmp, dead_path)
+        # Marker is durable now; removing the original never resurrects a
+        # dead_at-stamped live entry. Best-effort — a leftover live entry
+        # is self-healing (re-marked dead on the next pass).
+        try:
+            os.unlink(path)
+        except OSError:
+            pass
         return dead_path
     except OSError:
+        # Clean up a possibly-orphaned tmp so it doesn't linger.
+        try:
+            os.unlink(tmp)
+        except OSError:
+            pass
         return None

package/vendor/hindsight-memory/scripts/session_end.py

@@ -40,7 +40,16 @@ from lib.pending import MAX_ENTRIES, count as pending_count, enqueue as pending_
 # Exit codes:
 #   0 — success (or retain skipped for benign reasons)
 #   1 — retain failed AND was queued to pending-retains (recoverable)
-#   2 — retain failed AND the queue rejected it (chronic backlog)
+#   2 — retain failed but nothing was queued — either the queue rejected
+#       it (chronic backlog) or there was no payload to queue (the
+#       failure happened before one was built). Not recoverable via the
+#       pending-retains drain, so it's semantically "dropped", not
+#       "queued".
+# Only the sign of the exit code is load-bearing downstream: Claude
+# Code's hook runner routes any non-zero SessionEnd exit to the issue
+# sink (bin/run-hook.sh / #424); nothing distinguishes 1 from 2
+# programmatically, so this is a correctness/clarity fix, not a
+# contract change.
 EXIT_OK = 0
 EXIT_QUEUED = 1
 EXIT_DROPPED = 2
@@ -98,8 +107,10 @@ def main() -> int:
                     exit_code = EXIT_QUEUED
             else:
                 # No payload to queue — the failure happened before we
-                # finished building one (e.g. URL resolution).
-                exit_code = EXIT_QUEUED
+                # finished building one (e.g. URL resolution). Nothing
+                # landed in pending-retains, so this is a drop, not a
+                # queue (#1094 item 5): EXIT_DROPPED, not EXIT_QUEUED.
+                exit_code = EXIT_DROPPED
 
     # Stop daemon if we started it. Always runs, even on retain failure,
     # so we don't leak a daemon process.