@monster-orange/den 0.4.6 → 0.4.7

package/src/shared/agents/handback.ts

@@ -0,0 +1,241 @@
+/**
+ * The hand-back check: is a hand-back to a person complete and plain?
+ * `<cli> agents handback-check <file|->` runs it, and so does the Stop hook
+ * Den gives default-pack personas (guardrails/stop-hook.ts). The template
+ * is in guardrails/instructions.md:
+ *
+ *   ## Hand-back
+ *   - URL: <the link to open>
+ *   - Machine: <the machine it runs on>
+ *   - Branch: <the branch>
+ *   - What changed: <what is different now>
+ *   - What to click: <the steps to see it>
+ *   - Decisions:
+ *     1. <a yes/no question>?
+ *
+ * It rejects a hand-back when:
+ *
+ * 1. A part is missing or empty. A part is a line that starts with its
+ *    label and a colon (`URL:`, `- **Branch:** …`) or a heading that is its
+ *    label (`### What changed`). Its content is the rest of the line and
+ *    the lines after it, up to the next part. URL must hold a link (`://`)
+ *    or say `none` (work with no page), optionally with a reason.
+ *    Decisions may say `none`.
+ * 2. It has a bare ID. An ID is `#<digits>` or 1-4 capitals, an optional
+ *    `-`, digits and an optional `.<digits>` (`R12`, `AG-14`, `KB-4.1`).
+ *    URLs, `inline code` and code blocks, and the URL and Branch parts are
+ *    not scanned: they are literal. An ID is glossed (not bare) when:
+ *      a. a parenthetical of at least two words follows it:
+ *         `#5 (the hooks issue)`;
+ *      b. a colon or dash, then at least two words, follows it:
+ *         `R12: plain writing`, `R12 - plain writing`;
+ *      c. it sits inside a parenthetical right after a word, and that
+ *         parenthetical holds no other words: `plain writing (R12)`,
+ *         `the issues (#5, #6)`;
+ *      d. or the same ID was glossed earlier in the text.
+ *    A word is a run of letters (an ID is not a word).
+ * 3. A decision isn't a numbered yes/no question. Each item under
+ *    Decisions must be numbered (`1.` or `1)`), end in `?`, not start
+ *    with a question word (what, which, how, why, when, where, who), and
+ *    not offer a choice (` or `).
+ */
+
+export const HANDBACK_PARTS = [
+  "URL",
+  "Machine",
+  "Branch",
+  "What changed",
+  "What to click",
+  "Decisions",
+] as const;
+export type HandbackPart = (typeof HANDBACK_PARTS)[number];
+
+export interface HandbackResult {
+  ok: boolean;
+  /** One line each, plain, naming what to fix. */
+  problems: string[];
+}
+
+/** The ID patterns the check looks for. */
+export const ID_PATTERNS = [/#\d+/g, /\b[A-Z]{1,4}-?\d+(?:\.\d+)?\b/g];
+
+const LABEL = new RegExp(
+  `^\\s*(?:[-*+]\\s+)?(#{1,6}\\s+)?(?:\\*\\*|__)?(${HANDBACK_PARTS.map((p) =>
+    p.replace(/ /g, "\\s+"),
+  ).join("|")})(?:\\*\\*|__)?\\s*(:)?(?:\\*\\*|__)?\\s*(.*)$`,
+  "i",
+);
+
+/** The hand-back's heading, which marks a message as one. */
+export const HANDBACK_HEADING = /^\s*#{1,6}\s*hand-?\s?back\b/im;
+
+/** Does this message present itself as a hand-back (its heading)? */
+export function looksLikeHandback(text: string): boolean {
+  return HANDBACK_HEADING.test(text);
+}
+
+interface Parts {
+  found: Map<HandbackPart, string[]>;
+  /** Line numbers (0-based) of the URL and Branch parts' content. */
+  literal: Set<number>;
+}
+
+function canonical(label: string): HandbackPart {
+  const l = label.replace(/\s+/g, " ").toLowerCase();
+  return HANDBACK_PARTS.find((p) => p.toLowerCase() === l)!;
+}
+
+function splitParts(lines: string[]): Parts {
+  const found = new Map<HandbackPart, string[]>();
+  const literal = new Set<number>();
+  let cur: HandbackPart | null = null;
+  let fence = false;
+  lines.forEach((line, n) => {
+    if (/^\s*(```|~~~)/.test(line)) fence = !fence;
+    const m = fence ? null : LABEL.exec(line);
+    // A label needs a colon, or to be the whole heading.
+    if (m && (m[3] || (m[1] && !m[4].trim()))) {
+      cur = canonical(m[2]);
+      const body = m[4].trim();
+      found.set(cur, body ? [body] : []);
+      if (cur === "URL" || cur === "Branch") literal.add(n);
+      return;
+    }
+    if (/^\s*#{1,6}\s/.test(line)) {
+      cur = null;
+      return;
+    }
+    if (!cur) return;
+    if (line.trim()) found.get(cur)!.push(line.trim());
+    if (cur === "URL" || cur === "Branch") literal.add(n);
+  });
+  return { found, literal };
+}
+
+/** Text with URLs and code replaced by spaces (offsets kept). */
+function prose(line: string): string {
+  const blank = (s: string) => " ".repeat(s.length);
+  return line
+    .replace(/`[^`]*`/g, blank)
+    .replace(/\b[a-z][a-z0-9+.-]*:\/\/\S+/gi, blank)
+    .replace(/\bwww\.\S+/gi, blank);
+}
+
+const WORD = /[A-Za-z][A-Za-z'’]*(?:-[A-Za-z]+)*/g;
+
+/** Words in s: runs of letters, once the IDs are taken out. */
+function wordCount(s: string): number {
+  let t = s;
+  for (const re of ID_PATTERNS) t = t.replace(new RegExp(re.source, "g"), " ");
+  return (t.match(WORD) ?? []).length;
+}
+
+/** Is the ID at [start, end) in this line glossed (rules a-c)? */
+export function isGlossed(line: string, start: number, end: number): boolean {
+  const after = line.slice(end);
+  // a. "(two or more words)" right after.
+  const paren = /^\s*\(([^)]*)\)/.exec(after);
+  if (paren && wordCount(paren[1]) >= 2) return true;
+  // b. ": two words" or " - two words" right after.
+  const colon = /^\s*(?::|\s[-–—])\s*(.*)$/.exec(after);
+  if (colon && wordCount(colon[1].split(/[.;!?]/)[0]) >= 2) return true;
+  // c. inside "(…)" right after a word, the parenthetical only IDs.
+  const open = line.lastIndexOf("(", start);
+  const close = line.indexOf(")", end);
+  if (open >= 0 && close >= 0 && line.slice(open, start).indexOf(")") < 0) {
+    const inside = line.slice(open + 1, close);
+    const before = line.slice(0, open);
+    if (wordCount(inside) === 0 && /[A-Za-z][A-Za-z'’]*\s*$/.test(before))
+      return true;
+  }
+  return false;
+}
+
+/** Bare IDs in the text, in order, each once. */
+export function bareIds(
+  text: string,
+  skipLines: Set<number> = new Set(),
+): string[] {
+  const glossed = new Set<string>();
+  const bare: string[] = [];
+  let fence = false;
+  text.split(/\r?\n/).forEach((raw, n) => {
+    if (/^\s*(```|~~~)/.test(raw)) {
+      fence = !fence;
+      return;
+    }
+    if (fence || skipLines.has(n)) return;
+    const line = prose(raw);
+    const hits: { id: string; start: number; end: number }[] = [];
+    for (const re of ID_PATTERNS)
+      for (const m of line.matchAll(new RegExp(re.source, "g")))
+        hits.push({ id: m[0], start: m.index!, end: m.index! + m[0].length });
+    hits.sort((a, b) => a.start - b.start);
+    for (const h of hits) {
+      if (glossed.has(h.id)) continue;
+      if (isGlossed(line, h.start, h.end)) glossed.add(h.id);
+      else if (!bare.includes(h.id)) bare.push(h.id);
+    }
+  });
+  return bare;
+}
+
+const QUESTION_WORD = /^(what|which|how|why|when|where|who|whom|whose)\b/i;
+
+/** Problems with the Decisions part's items. */
+function decisionProblems(items: string[]): string[] {
+  if (items.length === 1 && /^(none|no decisions?|nothing)\.?$/i.test(items[0]))
+    return [];
+  if (!items.length)
+    return [
+      "Decisions is empty. List each as a numbered yes/no question, or say none.",
+    ];
+  const out: string[] = [];
+  for (const it of items) {
+    const m = /^(\d+)[.)]\s+(.*)$/.exec(it);
+    const q = (m ? m[2] : it.replace(/^[-*+]\s+/, "")).trim();
+    const show = q.length > 60 ? `${q.slice(0, 57)}...` : q;
+    if (!m)
+      out.push(`Decision "${show}" is not numbered. Number it: 1., 2., …`);
+    else if (!q.endsWith("?"))
+      out.push(`Decision "${show}" is not a question. End it with "?".`);
+    else if (QUESTION_WORD.test(q) || /\sor\s/i.test(q))
+      out.push(
+        `Decision "${show}" is not a yes/no question. Ask it so yes or no answers it.`,
+      );
+  }
+  return out;
+}
+
+/** Check a hand-back. Pure: the text in, the problems out. */
+export function checkHandback(text: string): HandbackResult {
+  const lines = String(text ?? "").split(/\r?\n/);
+  const { found, literal } = splitParts(lines);
+  const problems: string[] = [];
+  for (const part of HANDBACK_PARTS) {
+    const body = found.get(part);
+    if (body === undefined) {
+      problems.push(`Missing "${part}:". Add it.`);
+      continue;
+    }
+    if (part === "Decisions") {
+      problems.push(...decisionProblems(body));
+      continue;
+    }
+    if (!body.join(" ").trim())
+      problems.push(`"${part}:" is empty. Fill it in.`);
+    else if (
+      part === "URL" &&
+      !body.join(" ").includes("://") &&
+      !/^\s*none\b/i.test(body.join(" "))
+    )
+      problems.push(
+        `"URL:" has no link. Give the full address, with http:// or https://, or say none if this work has no page.`,
+      );
+  }
+  for (const id of bareIds(lines.join("\n"), literal))
+    problems.push(
+      `"${id}" is not explained. Say what it is, e.g. "${id} (what it is)".`,
+    );
+  return { ok: problems.length === 0, problems };
+}

package/src/shared/agents/personas.ts

@@ -15,7 +15,9 @@
  * Den's own keys sit beside them: `runtime` (default den-claude),
  * `standing` (starts with its workspace, §5), `context` (what to read
  * first), `argv` (the generic runtime's template), and `permission_mode`
- * (den-claude's Claude Code permission mode; it checks the value). Any other key (a
+ * (den-claude's Claude Code permission mode; it checks the value), and
+ * `den_hooks` / `den_instructions` (true or false: this persona's
+ * guardrails, guardrails.ts, over its pack's). Any other key (a
  * Claude Code `color`) is ignored. A file without front matter (a pack's
  * README) is not a persona.
  */
@@ -24,6 +26,12 @@ import * as path from "path";
 import * as yaml from "yaml";
 import { WORKSPACE_NAME_RE } from "../agent-actor.js";
 import { enginePath } from "../engine.js";
+import {
+  DEFAULT_PACK_GUARDRAILS,
+  PACK_GUARDRAILS,
+  sharedInstructions,
+  type Guardrails,
+} from "./guardrails.js";
 
 export interface Persona {
   id: string;
@@ -45,6 +53,13 @@ export interface Persona {
   argv?: string[];
   /** `permission_mode`: the runtime's permission mode (den-claude checks it). */
   permissionMode?: string;
+  /** `den_hooks` / `den_instructions` as its front matter sets them. */
+  guardrailsSet?: Partial<Guardrails>;
+  /**
+   * Den's guardrails for it (guardrails.ts), resolved by loadPersonas from
+   * its pack and its own front matter. Absent: none.
+   */
+  guardrails?: Guardrails;
   /** The file it came from. */
   source: string;
 }
@@ -133,6 +148,17 @@ export function parsePersona(text: string, file: string): Persona | null {
   const model = optString(f, "model", file);
   const runtime = optString(f, "runtime", file);
   const permissionMode = optString(f, "permission_mode", file);
+  const guardrailsSet: Partial<Guardrails> = {};
+  for (const [key, k] of [
+    ["den_hooks", "hooks"],
+    ["den_instructions", "instructions"],
+  ] as const) {
+    const v = f[key];
+    if (v === undefined || v === null) continue;
+    if (typeof v !== "boolean")
+      throw new Error(`${file}: ${key} must be true or false`);
+    guardrailsSet[k] = v;
+  }
   return {
     id,
     role: optString(f, "role", file) ?? optString(f, "description", file) ?? "",
@@ -144,6 +170,7 @@ export function parsePersona(text: string, file: string): Persona | null {
     context: stringList(f, "context", file),
     ...(argv ? { argv } : {}),
     ...(permissionMode ? { permissionMode } : {}),
+    ...(Object.keys(guardrailsSet).length ? { guardrailsSet } : {}),
     source: file,
   };
 }
@@ -183,23 +210,42 @@ export function resolvePackDirs(packs: string[], distRoot: string): string[] {
   });
 }
 
+/** Each pack's guardrails (guardrails.ts), as agents: configures them. */
+export interface PackGuardrails {
+  /** Den's default pack (default: both on). */
+  defaultPack?: Partial<Guardrails>;
+  /** Each of packDirs, in order (default: both off). */
+  packs?: (Partial<Guardrails> | undefined)[];
+}
+
 /**
  * Every persona: Den's default pack, then each pack in order. A later
- * pack's persona replaces an earlier one of the same id.
+ * pack's persona replaces an earlier one of the same id. Each gets its
+ * guardrails: its own front matter's, else its pack's.
  */
 export function loadPersonas(
   packDirs: string[],
   defaultPack: string = DEFAULT_PACK_DIR,
+  guardrails: PackGuardrails = {},
 ): Map<string, Persona> {
   const all = new Map<string, Persona>();
-  for (const dir of [defaultPack, ...packDirs])
-    for (const p of readPack(dir)) all.set(p.id, p);
+  const packs: [string, Guardrails][] = [
+    [defaultPack, { ...DEFAULT_PACK_GUARDRAILS, ...guardrails.defaultPack }],
+    ...packDirs.map((dir, i): [string, Guardrails] => [
+      dir,
+      { ...PACK_GUARDRAILS, ...guardrails.packs?.[i] },
+    ]),
+  ];
+  for (const [dir, g] of packs)
+    for (const p of readPack(dir))
+      all.set(p.id, { ...p, guardrails: { ...g, ...p.guardrailsSet } });
   return all;
 }
 
 /**
  * The role prompt as an agent gets it: who and where it is, what to read
- * first, then the persona's own prompt. Runtime-neutral; a runtime only
+ * first, the persona's own prompt, then Den's shared instructions
+ * (guardrails/instructions.md) when its guardrails include them. Runtime-neutral; a runtime only
  * chooses how to pass it in.
  */
 export function rolePrompt(
@@ -214,5 +260,8 @@ export function rolePrompt(
   ];
   if (persona.context.length)
     lines.push(`Read first: ${persona.context.join("; ")}.`);
-  return `${lines.join("\n")}\n\n${persona.prompt}`;
+  const shared = persona.guardrails?.instructions
+    ? `\n\n${sharedInstructions()}`
+    : "";
+  return `${lines.join("\n")}\n\n${persona.prompt}${shared}`;
 }

package/src/shared/den-config.ts

@@ -19,6 +19,7 @@ import type { OrgConfig } from "./org.js";
 import { validateOrgSources, type WorkOrgsConfig } from "./org-sources.js";
 import { ConfigError, isConfigError } from "./config-error.js";
 import { validateCatalog, type CatalogEntry } from "./agents/catalog.js";
+import type { Guardrails } from "./agents/guardrails.js";
 import type { TestAccountsConfig } from "./auth/test-accounts.js";
 
 import { product } from "./product.js";
@@ -833,9 +834,16 @@ export interface AgentsConfig {
   /**
    * Persona packs (AG-2a): directories of persona files, relative to the
    * distribution root. Den's default pack is always read first; a pack's
-   * persona replaces one of the same id.
+   * persona replaces one of the same id. An entry may be a mapping,
+   * `{ path, hooks, instructions }`, to turn Den's guardrails on for that
+   * pack (agents/guardrails.ts; off for a distribution's pack by default).
    */
-  persona_packs?: string[];
+  persona_packs?: (string | PersonaPackConfig)[];
+  /**
+   * Den's default pack's guardrails, `{ hooks, instructions }` (both on
+   * by default): false turns that one off for every persona of the pack.
+   */
+  default_pack?: Partial<Guardrails>;
   /**
    * More runtime catalog entries (AG-0.5, agents/catalog.ts): a vendor CLI
    * Den doesn't ship, with the same fields and checks as a built-in one.
@@ -849,6 +857,13 @@ export interface AgentsConfig {
   [agentId: string]: unknown;
 }
 
+/** A `persona_packs` entry written as a mapping. */
+export interface PersonaPackConfig {
+  path: string;
+  hooks?: boolean;
+  instructions?: boolean;
+}
+
 export const DEFAULT_AGENTS_MAX_CONCURRENT = 4;
 
 /** The keys of `agents:` that are not an agent id. */
@@ -856,6 +871,7 @@ export const AGENTS_RESERVED_KEYS = [
   "max_concurrent",
   "persona_packs",
   "runtime_catalog",
+  "default_pack",
 ];
 
 /** One agent's own block, `agents.<id>`. */
@@ -869,6 +885,10 @@ export interface ResolvedAgentsConfig {
   maxConcurrent: number;
   /** As configured (relative to the distribution root). */
   personaPacks: string[];
+  /** Each pack's guardrails as configured, by index of personaPacks. */
+  packGuardrails?: (Partial<Guardrails> | undefined)[];
+  /** agents.default_pack as configured. */
+  defaultPackGuardrails?: Partial<Guardrails>;
   /** `agents.<id>` blocks, by agent id. */
   agents: Record<string, AgentGrantsConfig>;
   /** The distribution's runtime catalog entries (AG-0.5), checked. */
@@ -881,6 +901,36 @@ const AGENT_KEY_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
 const isMapping = (v: unknown): v is Record<string, unknown> =>
   v !== null && typeof v === "object" && !Array.isArray(v);
 
+/**
+ * `{ hooks, instructions }` (agents.default_pack, or a persona_packs
+ * mapping with its `path`): each true or false; any other key throws.
+ */
+function guardrailsBlock(
+  v: unknown,
+  where: string,
+  withPath: boolean,
+): Partial<Guardrails> {
+  if (v === undefined || v === null) return {};
+  if (!isMapping(v))
+    throw new Error(
+      `${where}: must be a mapping ({ hooks: true|false, instructions: true|false })`,
+    );
+  const out: Partial<Guardrails> = {};
+  for (const [k, x] of Object.entries(v)) {
+    if (withPath && k === "path") continue;
+    if (k !== "hooks" && k !== "instructions")
+      throw new Error(
+        `${where}.${k}: unknown key (takes ${withPath ? "path, " : ""}hooks, instructions)`,
+      );
+    if (typeof x !== "boolean")
+      throw new Error(
+        `${where}.${k}: must be true or false (got ${JSON.stringify(x)})`,
+      );
+    out[k] = x;
+  }
+  return out;
+}
+
 /**
  * The effective agents config. Anything malformed throws, naming the key:
  * a typo must not lift the cap, drop a pack or widen a grant.
@@ -894,6 +944,12 @@ export function readAgentsConfig(
   const out: ResolvedAgentsConfig = {
     maxConcurrent: DEFAULT_AGENTS_MAX_CONCURRENT,
     personaPacks: [],
+    packGuardrails: [],
+    defaultPackGuardrails: guardrailsBlock(
+      raw.default_pack,
+      "agents.default_pack",
+      false,
+    ),
     agents: {},
     runtimeCatalog: validateCatalog(
       raw.runtime_catalog,
@@ -915,19 +971,24 @@ export function readAgentsConfig(
         `agents.persona_packs: must be a list of paths (got ${JSON.stringify(packs)})`,
       );
     packs.forEach((p, i) => {
-      if (typeof p !== "string" || !p.trim())
+      const where = `agents.persona_packs[${i}]`;
+      const dir = isMapping(p) ? p.path : p;
+      if (typeof dir !== "string" || !dir.trim())
         throw new Error(
-          `agents.persona_packs[${i}]: must be a non-empty path (got ${JSON.stringify(p)})`,
+          `${where}: must be a non-empty path or { path, hooks, instructions } (got ${JSON.stringify(p)})`,
         );
+      out.personaPacks.push(dir);
+      out.packGuardrails!.push(
+        isMapping(p) ? guardrailsBlock(p, where, true) : undefined,
+      );
     });
-    out.personaPacks = packs as string[];
   }
   for (const [id, block] of Object.entries(raw)) {
     if (AGENTS_RESERVED_KEYS.includes(id)) continue;
     const where = `agents.${id}`;
     if (!AGENT_KEY_RE.test(id) || !isMapping(block))
       throw new Error(
-        `${where}: unknown key (agents: takes max_concurrent, persona_packs, runtime_catalog, ` +
+        `${where}: unknown key (agents: takes max_concurrent, persona_packs, runtime_catalog, default_pack, ` +
           `or an agent id mapping to { grants: [...] })`,
       );
     for (const k of Object.keys(block))

package/src/shared/dev-metrics/emit.ts

@@ -19,6 +19,12 @@
  * else). A DSN, in the env or a synced dev-metrics.config, is where to send
  * once opted in; on its own it never sends.
  *
+ * Each line also has `cwd` (den#5): where the command ran, relative to the
+ * distribution root ("." for the root itself), or "outside" for anywhere
+ * else, never an absolute or home path. `<cli> doctor` reads it to spot
+ * polling loops (polling.ts). Like every field, it is sent only when opted
+ * in; the envelope format is unchanged.
+ *
  * Guarantees: never throws, never blocks the caller (the Sentry ship is
  * fire-and-forget, bounded to ~2s). CI=true / DEV_METRICS_DISABLED=1 suppress
  * shipping but still buffer the JSONL locally.
@@ -115,6 +121,29 @@ function commonFields(event: string, root: string): Record<string, string> {
   };
 }
 
+/** The JSONL file, under the repo root. */
+export function eventsFile(root: string = repoRoot()): string {
+  return path.join(root, ".dev-metrics", "events.jsonl");
+}
+
+/**
+ * `cwd` for a local line: the path from the root to cwd ("." for the root,
+ * "/"-separated), or "outside" when cwd is not under the root.
+ */
+export function cwdField(root: string, cwd: string = process.cwd()): string {
+  const real = (p: string): string => {
+    try {
+      return fs.realpathSync(p);
+    } catch {
+      return path.resolve(p);
+    }
+  };
+  const rel = path.relative(real(root), real(cwd));
+  if (rel === "") return ".";
+  if (rel.startsWith("..") || path.isAbsolute(rel)) return "outside";
+  return rel.split(path.sep).join("/");
+}
+
 function isoNoMillis(): string {
   return new Date().toISOString().replace(/\.\d+Z$/, "Z");
 }
@@ -334,14 +363,12 @@ export function record(
     for (const [k, v] of Object.entries(fields)) {
       obj[k] = v == null ? "" : String(v);
     }
+    obj.cwd = cwdField(root);
 
     try {
       const dir = path.join(root, ".dev-metrics");
       fs.mkdirSync(dir, { recursive: true });
-      fs.appendFileSync(
-        path.join(dir, "events.jsonl"),
-        JSON.stringify(obj) + "\n",
-      );
+      fs.appendFileSync(eventsFile(root), JSON.stringify(obj) + "\n");
     } catch {
       /* non-writable dir → fail-open */
     }

package/src/shared/dev-metrics/polling.ts

@@ -0,0 +1,135 @@
+/**
+ * Polling-loop warning (den#5) for `<cli> doctor`: one command, run from
+ * one place, more than POLL_LIMIT times in any POLL_WINDOW_MS window looks
+ * like an agent polling it. Local only: it reads the tail of the local
+ * .dev-metrics/events.jsonl and sends nothing anywhere.
+ *
+ * A line's place is its `cwd` (emit.ts). An older line has none, so it is
+ * keyed by its `repo` instead.
+ */
+import * as fs from "fs";
+
+/** More calls than this in one window is a polling loop. */
+export const POLL_LIMIT = 600;
+/** The window: an hour. */
+export const POLL_WINDOW_MS = 60 * 60 * 1000;
+/** At most this much of the file's end is read, however big it is. */
+export const TAIL_BYTES = 8 * 1024 * 1024;
+
+/**
+ * The file's last `max` bytes as whole lines: a line cut by the start of
+ * the slice is dropped. A missing or unreadable file is no lines.
+ */
+export function readTailLines(
+  file: string,
+  max: number = TAIL_BYTES,
+): string[] {
+  let fd: number | undefined;
+  try {
+    fd = fs.openSync(file, "r");
+    const size = fs.fstatSync(fd).size;
+    const len = Math.min(size, max);
+    const buf = Buffer.alloc(len);
+    let got = 0;
+    while (got < len) {
+      const n = fs.readSync(fd, buf, got, len - got, size - len + got);
+      if (n <= 0) break;
+      got += n;
+    }
+    const lines = buf.subarray(0, got).toString("utf-8").split("\n");
+    if (len < size) lines.shift();
+    return lines.filter((l) => l.trim());
+  } catch {
+    return [];
+  } finally {
+    if (fd !== undefined) fs.closeSync(fd);
+  }
+}
+
+export interface PollingLoop {
+  command: string;
+  /** Where: the line's cwd, or `repo <name>` for an older line. */
+  where: string;
+  /** Calls in the busiest window. */
+  calls: number;
+  /** The busiest window's first and last call (ISO, no millis). */
+  from: string;
+  to: string;
+}
+
+const iso = (ms: number): string =>
+  new Date(ms).toISOString().replace(/\.\d+Z$/, "Z");
+
+/**
+ * Every command+place with more than `limit` calls in some `windowMs`
+ * window, with its busiest window. Lines that aren't JSON, or have no
+ * command or time, are skipped.
+ */
+export function findPollingLoops(
+  lines: string[],
+  limit: number = POLL_LIMIT,
+  windowMs: number = POLL_WINDOW_MS,
+): PollingLoop[] {
+  const byKey = new Map<
+    string,
+    { command: string; where: string; times: number[] }
+  >();
+  for (const line of lines) {
+    let o: Record<string, unknown>;
+    try {
+      o = JSON.parse(line) as Record<string, unknown>;
+    } catch {
+      continue;
+    }
+    if (!o || typeof o !== "object") continue;
+    const command = typeof o.command === "string" ? o.command : "";
+    const t = typeof o.ts === "string" ? Date.parse(o.ts) : NaN;
+    if (!command || Number.isNaN(t)) continue;
+    const where =
+      typeof o.cwd === "string" && o.cwd
+        ? o.cwd
+        : `repo ${typeof o.repo === "string" && o.repo ? o.repo : "?"}`;
+    const key = `${command}\u0000${where}`;
+    let e = byKey.get(key);
+    if (!e) byKey.set(key, (e = { command, where, times: [] }));
+    e.times.push(t);
+  }
+  const out: PollingLoop[] = [];
+  for (const { command, where, times } of byKey.values()) {
+    if (times.length <= limit) continue;
+    times.sort((a, b) => a - b);
+    let best = 0;
+    let bi = 0;
+    let bj = 0;
+    for (let i = 0, j = 0; j < times.length; j++) {
+      while (times[j] - times[i] >= windowMs) i++;
+      if (j - i + 1 > best) {
+        best = j - i + 1;
+        bi = i;
+        bj = j;
+      }
+    }
+    if (best > limit)
+      out.push({
+        command,
+        where,
+        calls: best,
+        from: iso(times[bi]),
+        to: iso(times[bj]),
+      });
+  }
+  return out.sort((a, b) => b.calls - a.calls);
+}
+
+/** One warning line, as doctor prints it. */
+export function pollingWarning(p: PollingLoop): string {
+  return `looks like a polling loop: ${p.command} in ${p.where}, ${p.calls} calls in an hour (${p.from}–${p.to})`;
+}
+
+/** doctor's warnings for this events file (none when it is fine or absent). */
+export function pollingWarnings(
+  file: string,
+  max: number = TAIL_BYTES,
+): string[] {
+  return findPollingLoops(readTailLines(file, max)).map(pollingWarning);
+}