@vellumai/assistant 0.11.2 → 0.11.3-staging.2

package/src/subagent/role-resolution.ts

@@ -0,0 +1,88 @@
+/**
+ * Resolution of the `role` a spawn asks for into one of the three subagent
+ * types.
+ *
+ * The model writes this field freely: it names a type, an older type name, a
+ * job title, or a whole sentence of framing. Every one of those has to land on
+ * a defined capability envelope, so resolution is total and never rejects.
+ */
+
+import { truncate } from "../util/truncate.js";
+import {
+  DEFAULT_SUBAGENT_ROLE,
+  SUBAGENT_ROLE_REGISTRY,
+  type SubagentRole,
+} from "./types.js";
+
+export interface ResolvedSubagentRole {
+  /** The type the child actually runs as. */
+  role: SubagentRole;
+  /**
+   * The requested text, when it named no type and is carried into the child's
+   * framing as a persona instead.
+   */
+  personaText?: string;
+  /** The legacy name the caller used, when it resolved through an alias. */
+  alias?: string;
+}
+
+/**
+ * The role names that predate the three types. They stay accepted because
+ * every prompt, skill, and habit that names one is still in circulation, and a
+ * spawn is a poor place to learn a taxonomy changed.
+ */
+const ROLE_ALIASES: Record<string, SubagentRole> = {
+  planner: "researcher",
+  investigator: "researcher",
+  coder: "builder",
+  general: "builder",
+};
+
+/**
+ * How much of a free-text role survives into the persona line. A role value
+ * can arrive as an entire sentence of instructions; the persona line is a
+ * framing hint, and the objective is where the task belongs.
+ */
+const MAX_PERSONA_LENGTH = 120;
+
+/** Single-line, length-bounded form of a free-text role. */
+function toPersonaText(raw: string): string {
+  return truncate(raw.replace(/\s+/g, " ").trim(), MAX_PERSONA_LENGTH);
+}
+
+/**
+ * Resolve a requested role into the type the child runs as.
+ *
+ * - Absent (or blank) resolves to `builder`, which imposes no tool allowlist.
+ *   A spawn that names no role has always run on the parent's full surface,
+ *   and a task delegated without a stated shape is as likely to need a file
+ *   written as read.
+ * - The three type names pass through, case-insensitively.
+ * - A legacy name resolves to its successor type and is reported in `alias`.
+ * - Anything else resolves to `researcher` with the text kept as
+ *   `personaText`. This is least privilege for a value nobody defined: a typo
+ *   or an invented role must not silently hand out write access. When the task
+ *   really did need to write, the child reports that it cannot and the parent
+ *   re-spawns as `builder`, which is a visible and cheap correction.
+ */
+export function resolveSubagentRole(
+  raw: string | undefined,
+): ResolvedSubagentRole {
+  const trimmed = raw?.trim() ?? "";
+  if (trimmed.length === 0) {
+    return { role: DEFAULT_SUBAGENT_ROLE };
+  }
+
+  // `Object.hasOwn` rather than `in`: a role of "constructor" or "toString"
+  // reaches inherited members and would resolve to something that is not a
+  // role at all.
+  const key = trimmed.toLowerCase();
+  if (Object.hasOwn(SUBAGENT_ROLE_REGISTRY, key)) {
+    return { role: key as SubagentRole };
+  }
+  if (Object.hasOwn(ROLE_ALIASES, key)) {
+    return { role: ROLE_ALIASES[key], alias: key };
+  }
+
+  return { role: "researcher", personaText: toPersonaText(trimmed) };
+}

package/src/subagent/types.ts

@@ -92,15 +92,47 @@ export interface SubagentConfig {
   preactivatedSkillIds?: string[];
   /** Whether the parent should present the result to the user. Defaults to true. */
   sendResultToUser?: boolean;
-  /** Optional role for the subagent. Defaults handled by consumers. */
+  /** The subagent's type. Omitted spawns run as {@link DEFAULT_SUBAGENT_ROLE}. */
   role?: SubagentRole;
   /**
-   * When true, side-effecting tools (send/write/delete/purchase, host commands)
-   * are refused for this subagent regardless of trust class — the executor
-   * rejects any such dispatch and the tool is kept off the model's tool surface.
-   * For unattended passes that must never take an unapproved action while the
-   * user isn't watching; the subagent surfaces the intended action for the
-   * user to approve instead.
+   * Free-text framing rendered as a persona line under the role preamble, for
+   * a spawn whose requested role names a character rather than a type ("staff
+   * security engineer", "financial journalist"). The role still decides what
+   * the child may do; the persona only decides how it reads the task.
+   */
+  persona?: string;
+  /**
+   * The shape the child's final message has to take. Omitted spawns run as
+   * `report`, which asks for nothing beyond the role preamble's own reporting
+   * guidance.
+   */
+  outputContract?: SubagentOutputContract;
+  /**
+   * How this subagent was spawned: the call site and its context/lifecycle
+   * shape. Stamped onto the child conversation row and emitted as
+   * `subagent_spawn_mode` on `llm_usage` telemetry so delegated spend is
+   * separable per variety.
+   *
+   * Set by the spawning call site, which is the only layer that knows: the
+   * manager cannot tell an advisor consult from a plain fork, nor a live-voice
+   * continuation from a tool-initiated one. Omitting it falls back to the
+   * mechanical `fork ? "fork" : "regular"`, so a future call site that forgets
+   * still lands on an honest value rather than NULL.
+   */
+  spawnMode?: SubagentSpawnMode;
+  /**
+   * When true, this subagent may run only the runtime's own read-only built-ins:
+   * anything else, including a workspace/plugin/skill/MCP tool registered UNDER
+   * a built-in's name, is kept off the model's tool surface and refused by the
+   * executor regardless of trust class (see `isRefusedInReadOnlyPass`). Because
+   * the check is on the tool's registered OWNER and not its name, it is the only
+   * durable read-only guarantee available; a role allowlist alone is a set of
+   * names any extension can claim.
+   *
+   * Set by callers whose contract is that nothing changes: an unattended pass
+   * that must not take an unapproved action while the user isn't watching (the
+   * subagent surfaces the intended action for the user to approve instead), and
+   * the advisor consult, whose whole product is judgment rather than action.
    */
   denySideEffectTools?: boolean;
   /**
@@ -143,6 +175,13 @@ export interface SubagentConfig {
    * leave this unset so existing call-site precedence stays intact.
    */
   forceOverrideProfile?: boolean;
+  /**
+   * The `cron_runs.id` of the schedule firing that spawned this subagent.
+   * Passed into the subagent's `runAgentLoop` so its usage rows carry the same
+   * stamp as the parent turn's and schedule cost reporting sees the delegated
+   * spend. Unset for spawns that no schedule triggered.
+   */
+  cronRunId?: string | null;
   /**
    * Tool-use id of the `skill_execute` call that spawned this subagent.
    * Forwarded into the `subagent_spawned` event so the client can anchor the
@@ -168,8 +207,90 @@ export interface SubagentState {
   completedAt?: number;
   /** Cumulative token usage. */
   usage: UsageStats;
+  /**
+   * What the subagent actually ran, harvested from the child conversation when
+   * the run ends and re-read while that conversation is still retained (a
+   * follow-up turn queued during the run drains after the run returns). In
+   * memory only, so a state rebuilt from the durable row never has it: the
+   * manager answers that case with {@link SubagentToolStatsReading}.
+   */
+  stats?: SubagentToolStatsSummary;
+}
+
+/**
+ * Harvested form of the conversation's live `SubagentToolStats`: the
+ * `filesWritten` Set is collapsed to its size, so the state carries counts
+ * rather than a reference into a conversation that is about to be released.
+ */
+export interface SubagentToolStatsSummary {
+  calls: number;
+  succeeded: number;
+  /**
+   * Distinct paths the child passed to `file_write` / `file_edit`. Those two
+   * tools are the only writes the executor can attribute to a path, so a
+   * builder that writes through the shell, a document tool, or an MCP tool
+   * adds nothing here. {@link formatSubagentToolStats} names the two tools for
+   * that reason.
+   */
+  filesWritten: number;
 }
 
+/**
+ * What the manager can say about a subagent's tool-call counters, which live in
+ * memory only.
+ *
+ * - `counted`: the run was harvested, so the numbers are real.
+ * - `unmeasured`: a live run that never reached its harvest. Nothing was
+ *   measured and nothing was lost, so a reader claims neither.
+ * - `unrecoverable`: the state was rebuilt from the durable row (the startup
+ *   rehydration, or a subagent the manager's window no longer holds). The row
+ *   carries no counters, so they can never be produced for this subagent, and
+ *   reporting zero calls would read as "this subagent did nothing".
+ *
+ * A rehydrated entry sits in the manager exactly like a live one, so manager
+ * membership alone cannot separate the last two; the manager tracks which of
+ * its entries it rebuilt and answers with this instead.
+ */
+export type SubagentToolStatsReading =
+  | { kind: "counted"; stats: SubagentToolStatsSummary }
+  | { kind: "unmeasured" }
+  | { kind: "unrecoverable" };
+
+/**
+ * The machine half of a subagent's result, appended to the parent's completion
+ * notification and to `subagent_read`. The child's prose is its own account of
+ * what it did; this line is the measured one, so a report of executed work by a
+ * subagent that called nothing is visible instead of taken on trust.
+ *
+ * The file count names the two tools it comes from. A builder runs on the
+ * parent's whole tool surface and can write through the shell, a document tool,
+ * or an MCP tool, none of which the counter sees; an unqualified "files
+ * written: 0" would read as fabricated work for a subagent that really did
+ * write, which is the exact misreading this line exists to prevent.
+ */
+export function formatSubagentToolStats(
+  stats: SubagentToolStatsSummary,
+): string {
+  if (stats.calls === 0) {
+    return "[stats: no tools were used by this subagent; treat any claims of executed work as unverified]";
+  }
+  const plural = stats.calls === 1 ? "" : "s";
+  return `[stats: ${stats.calls} tool call${plural}, ${stats.succeeded} succeeded, files written via file_write/file_edit: ${stats.filesWritten}]`;
+}
+
+/** Stats footer for a subagent whose in-memory counters no longer exist. */
+export const SUBAGENT_STATS_UNAVAILABLE =
+  "[stats: unavailable (tool counters are not retained for this subagent)]";
+
+/**
+ * Appended to a read taken while the subagent is still working through
+ * guidance queued during its run. Its own run is over by then, which is what
+ * makes it terminal, but the queued turn adds output and tool calls after
+ * that, so such a read is a progress report rather than the final one.
+ */
+export const SUBAGENT_READ_STILL_PROCESSING =
+  "[note: this subagent is still processing queued follow-up guidance. The output above and the counts below stop at its last finished turn; read again for the rest.]";
+
 // ── Bounded listing ─────────────────────────────────────────────────────
 
 /** Recency key matching the durable query's `COALESCE(completed_at, created_at)`. */
@@ -209,13 +330,119 @@ export const SUBAGENT_LIMITS = {
 
 // ── Roles ───────────────────────────────────────────────────────────────
 
-export type SubagentRole =
-  | "general"
-  | "researcher"
-  | "coder"
-  | "planner"
-  | "investigator"
-  | "advisor";
+/**
+ * What a subagent is, derived from two questions: can it change things, and
+ * does the parent wait for it.
+ *
+ * - `researcher`: read-only, runs in the background, scoped to a fixed
+ *   allowlist.
+ * - `builder`: write-capable, runs in the background, on the parent's whole
+ *   tool surface.
+ * - `advisor`: read-only, the parent turn blocks on its guidance.
+ *
+ * Write-plus-blocking is deliberately absent: a parent that waits on a change
+ * has no reason to delegate it. Model tier is a separate knob
+ * (`inference_profile`), and a persona is free text
+ * (`SubagentConfig.persona`), so neither is a type.
+ *
+ * The legacy names (`general`, `coder`, `planner`, `investigator`) remain
+ * accepted at the tool boundary as aliases; see ./role-resolution.ts.
+ */
+export type SubagentRole = "researcher" | "builder" | "advisor";
+
+// ── Output contracts ─────────────────────────────────────────────────────
+
+/**
+ * Every contract the tool boundary accepts, in advertised order. `report` is
+ * first because it is what a spawn that names none runs under.
+ */
+export const SUBAGENT_OUTPUT_CONTRACTS = [
+  "report",
+  "verdict",
+  "artifact",
+] as const;
+
+/**
+ * The shape a subagent's final message has to take. Orthogonal to
+ * {@link SubagentRole}, which decides what the child may do: the contract
+ * decides what it owes back, so the same read-only researcher can return an
+ * investigation report or an evidence-backed pass/fail list.
+ *
+ * - `report`: prose answering the objective, which is what every role preamble
+ *   already asks for.
+ * - `verdict`: per-criterion PASS/FAIL with the evidence behind each call.
+ *   Researcher-only, since a verdict is a claim about what is already there.
+ *   Checking work this way is mechanical rather than exploratory, so the spawn
+ *   also defaults to the cheap model tier.
+ * - `artifact`: the deliverable is the thing produced, not the write-up.
+ *   Builder-only, since nothing else can produce one.
+ *
+ * "Verifier" is deliberately not a fourth role: verification is a researcher
+ * under the `verdict` contract, and a role would have implied a separate tool
+ * envelope it does not need.
+ */
+export type SubagentOutputContract = (typeof SUBAGENT_OUTPUT_CONTRACTS)[number];
+
+/**
+ * The instruction a contract adds to the child's framing, or `undefined` for
+ * `report`, whose expectations the role preamble already states.
+ *
+ * Rendered into the built system prompt for a regular spawn and into the fork
+ * task framing for a fork, which inherits the parent's prompt verbatim and so
+ * never sees a built one.
+ */
+export function subagentOutputContractText(
+  contract: SubagentOutputContract | undefined,
+): string | undefined {
+  switch (contract) {
+    case "verdict":
+      return (
+        "For each criterion in the objective return PASS or FAIL plus the exact evidence (file path, line, value, or quote). " +
+        "If evidence is unavailable say CANNOT VERIFY and state what is missing. No prose beyond the verdict list."
+      );
+    case "artifact":
+      return "Your deliverable is the artifact itself. End by listing the exact files you created or modified.";
+    default:
+      return undefined;
+  }
+}
+
+// ── Spawn modes ──────────────────────────────────────────────────────────
+
+/**
+ * How a subagent was spawned. Orthogonal to {@link SubagentRole}: the role
+ * selects the tool allowlist and system-prompt preamble (what the child may
+ * do), the spawn mode selects context inheritance and lifecycle (how many
+ * input tokens the child starts with, and whether the parent blocks on it).
+ * A fork's inherited parent transcript is the dominant input-token driver and
+ * is independent of which role ran, which is why neither field subsumes the
+ * other.
+ *
+ * - `regular`: fire-and-forget `subagent_spawn`, fresh objective-only context.
+ * - `fork`: `subagent_spawn` with `fork: true`, inherits the parent transcript.
+ * - `advisor_consult`: synchronous, read-only advisor consult on the advisor
+ *   profile; the parent turn blocks on it and returns its guidance inline.
+ * - `voice_continuation`: live-voice background continuation of an interrupted
+ *   turn, spawned as a fork with no role and therefore WRITE-CAPABLE: it runs
+ *   as {@link DEFAULT_SUBAGENT_ROLE} on the parent's full tool surface, with
+ *   side effects governed by the standard non-interactive permission path
+ *   under the trust the foreground voice turn ran under. It is silent only in
+ *   the sense that the run makes no sound of its own, a later session turn
+ *   speaking its answer; that is a statement about sound, not blast radius.
+ *
+ * This block is the single description of the modes. The persistence and
+ * telemetry layers that carry the same values point here rather than restate
+ * them, so a correction lands once.
+ *
+ * Mirrored on the wire as `llm_usage.subagent_spawn_mode`, which is an OPEN
+ * string set on the platform side: adding a value here needs no coordinated
+ * platform release.
+ */
+export type SubagentSpawnMode =
+  | "regular"
+  | "fork"
+  | "advisor_consult"
+  | "voice_continuation";
 
 export interface SubagentRoleConfig {
   /**
@@ -223,6 +450,17 @@ export interface SubagentRoleConfig {
    * `undefined` means no filter (all tools available).
    */
   allowedTools?: string[];
+  /**
+   * When true, the role refuses side-effecting tools regardless of trust
+   * class: a name on {@link allowedTools} still has to resolve to a
+   * first-party built-in, so a workspace or plugin tool that claims an
+   * allowed name is kept off the surface and refused at dispatch.
+   *
+   * This lives on the role rather than at a spawn site so every path that
+   * projects the role, the live spawn and the `tools list --agent` preview
+   * alike, applies the same gate.
+   */
+  denySideEffects?: boolean;
   /** Skill IDs to pre-activate on the subagent conversation. */
   skillIds: string[];
   /** Role-specific text prepended to the subagent system prompt. */
@@ -231,76 +469,73 @@ export interface SubagentRoleConfig {
 
 export const SUBAGENT_ROLE_REGISTRY: Record<SubagentRole, SubagentRoleConfig> =
   {
-    general: {
-      allowedTools: undefined,
-      skillIds: [],
-      systemPromptPreamble:
-        "You are a general-purpose subagent. Complete the delegated task thoroughly and concisely.",
-    },
     researcher: {
       allowedTools: [
         "web_search",
         "web_fetch",
         "file_read",
         "file_list",
-        "recall",
-        "notify_parent",
-      ],
-      skillIds: [],
-      systemPromptPreamble:
-        "You are a research-focused subagent with read-only access. Search the web, read files, and recall memories. You cannot write files or run shell commands.",
-    },
-    coder: {
-      allowedTools: [
-        "bash",
-        "file_read",
-        "file_write",
-        "file_edit",
-        "web_search",
-        "recall",
-        "notify_parent",
-      ],
-      skillIds: [],
-      systemPromptPreamble:
-        "You are a code-focused subagent with file and shell access. Read, write, and edit files, and run shell commands.",
-    },
-    planner: {
-      allowedTools: [
-        "file_read",
-        "file_list",
-        "web_search",
-        "web_fetch",
-        "recall",
-        "notify_parent",
-      ],
-      skillIds: [],
-      systemPromptPreamble:
-        "You are an analysis-focused subagent with read-only access. Read files, search the web, and synthesize findings. You cannot write files or run shell commands.",
-    },
-    investigator: {
-      allowedTools: [
         "code_search",
-        "file_read",
-        "file_list",
-        "web_search",
-        "web_fetch",
         "recall",
+        "skill_execute",
         "notify_parent",
       ],
       skillIds: [],
       systemPromptPreamble: [
-        "You are an investigation-focused subagent for root-cause analysis: debugging, log forensics, and tracing behavior across code.",
-        "You have read-only investigation tools only — there is no shell. Use code_search to search file contents across directories, file_list to enumerate paths, and file_read to read whole files and logs. You cannot modify files or system state.",
-        "Working method: read whole files instead of many small line-range slices; prefer broad code_search queries across a directory over one-symbol-at-a-time queries.",
+        "You are a research subagent with read-only access: search the web, read and search files, and recall memories. There is no shell, and you cannot write or edit files.",
+        // `file_read` takes no default line limit and its results are exempt
+        // from result-time spooling, so a full body rides every LLM call until
+        // the turn ends. Telling the role to read whole files makes that the
+        // default shape of a research turn, and this role now covers the
+        // traffic three roles used to. The anti-slicing intent stays: one pass
+        // over the range that is needed rather than many small ones.
+        "Working method: use code_search to search file contents across directories, file_list to enumerate paths, and file_read to read files and logs. Prefer broad code_search queries across a directory over one-symbol-at-a-time queries, and read the range you need in one pass rather than many small slices.",
         "Send notify_parent (urgency 'important') as soon as each finding is confirmed, so progress survives interruption.",
-        "Your final message must be a compact root-cause report with these sections: Symptom, Root cause, Evidence (file:line references), Suggested fix, Open questions.",
-        "If you approach context limits, stop investigating and produce the report from what you have — a partial report delivered is worth more than a complete investigation lost.",
+        "Your final message is the deliverable: a compact report that answers the objective, gives the evidence behind each claim (file:line references, URLs, or quotes), and names what you could not determine. For a root-cause investigation, use the sections Symptom, Root cause, Evidence, Suggested fix, Open questions.",
+        "If you approach context limits, stop investigating and write the report from what you have. A partial report delivered is worth more than a complete investigation lost.",
+      ].join(" "),
+    },
+    builder: {
+      // No allowlist: a builder projects the same tool surface its parent
+      // conversation does, connectors, MCP tools, browser and computer use
+      // included. A fixed list would be a ceiling on what "can change things"
+      // means, and the tools a build task needs are not enumerable in advance:
+      // the work that has to file the ticket, send the message, or drive the
+      // browser is exactly the work a parent delegates.
+      skillIds: [],
+      systemPromptPreamble: [
+        "You are a build subagent with the parent's full tool surface: read, write, and edit files, run shell commands, search code, search the web, and use any other tool the parent conversation can reach.",
+        "Carry the task through end to end, then verify it yourself with the command that proves it (a build, a test run, a re-read of what you wrote) before reporting.",
+        "Send notify_parent (urgency 'important') when a milestone lands or a decision only the parent can make blocks you.",
+        "Your final message must state what you changed, the exact files you touched, and the result of the verification you ran.",
       ].join(" "),
     },
     advisor: {
-      allowedTools: [],
+      // Read-only fact checking, deliberately narrower than the researcher's
+      // list: no web fetch, no skill execution, no memory search, nothing that
+      // persists. The advisor answers from the inherited conversation and opens
+      // a file only when a specific fact would change the advice.
+      //
+      // Names alone are not the guarantee. The advisor spawn also sets
+      // `denySideEffectTools`, so each name must additionally resolve to the
+      // first-party built-in implementation (`READ_ONLY_ALLOWED_TOOLS` plus the
+      // `ownerKind === "default"` check in `isRefusedInReadOnlyPass`) before the
+      // tool reaches the wire or the executor. Every entry here must stay inside
+      // that read-only set, or it is admitted by the role and then refused at
+      // dispatch. `subagent-role-registry.test.ts` asserts the subset.
+      allowedTools: ["file_read", "file_list", "code_search"],
+      denySideEffects: true,
       skillIds: [],
       systemPromptPreamble:
-        "You are a read-only senior advisor consulted for a one-shot strategic review. Read the inherited conversation, then return focused, high-leverage guidance in a single response. You have no tools — you cannot search, read files, or run commands — so reason from the context you were given.",
+        "You are a read-only senior advisor consulted for a one-shot strategic review. Read the inherited conversation, then return focused, high-leverage guidance in a single response. You may read and search the files in the workspace to verify a decisive fact, but you cannot change anything and you cannot see other conversations.",
     },
   };
+
+/**
+ * The type a spawn that names no role runs as. `builder` imposes no tool
+ * allowlist, so a caller that omits the field keeps the full surface its
+ * conversation projects: the internal context-inheriting callers (the
+ * live-voice continuation) continue the parent's turn with the tools that turn
+ * had, and a delegated task whose shape was never stated can still write.
+ */
+export const DEFAULT_SUBAGENT_ROLE: SubagentRole = "builder";

package/src/subagent/validate-allowlists.ts

@@ -25,10 +25,9 @@ export interface UnknownAllowlistTool {
 
 /**
  * Pure core: given the set of registered tool names, return every allowlist
- * entry that has no matching registered tool. Roles with no allowlist
- * (`allowedTools: undefined`, e.g. `general`) impose no filter and contribute
- * nothing. Exported for direct unit testing without standing up the real tool
- * registry.
+ * entry that has no matching registered tool. A role with no allowlist
+ * (`allowedTools: undefined`) imposes no filter and contributes nothing.
+ * Exported for direct unit testing without standing up the real tool registry.
  */
 export function findUnknownAllowlistTools(
   registeredToolNames: ReadonlySet<string>,

package/src/telegram/__tests__/webhook-health.test.ts

@@ -45,12 +45,22 @@ mock.module("../bot-username.js", () => ({
 
 let apiBaseUrl = "https://api.telegram.org";
 
+// What the gateway reconciler recorded on its last successful setWebhook.
+// Defaults to the URL the fixtures report from getWebhookInfo, so the common
+// case is a verified match; tests override it to exercise a stale registration
+// and a deployment that never recorded one.
+let registeredWebhookUrl: string | undefined =
+  "https://example.test/webhooks/telegram";
+
 // Spread the real modules below: these are broad barrels shared with peer test
 // files, and replacing one wholesale drops the exports those files import.
 const actualLoader = await import("../../config/loader.js");
 mock.module("../../config/loader.js", () => ({
   ...actualLoader,
-  getConfig: () => ({ telegram: { apiBaseUrl }, ingress: ingressConfig }),
+  getConfig: () => ({
+    telegram: { apiBaseUrl, registeredWebhookUrl },
+    ingress: ingressConfig,
+  }),
   loadRawConfig: () => ({ ingress: ingressConfig }),
 }));
 
@@ -152,6 +162,7 @@ beforeEach(() => {
   fetchCallCount = 0;
   fetchedUrls.length = 0;
   apiBaseUrl = "https://api.telegram.org";
+  registeredWebhookUrl = "https://example.test/webhooks/telegram";
   emittedSignals.length = 0;
   emitFails = false;
   _resetTelegramWebhookHealthState();
@@ -317,6 +328,67 @@ describe("detection", () => {
     expect(result.status).toBe("unknown");
   });
 
+  test("reports url_mismatch when Telegram holds an address we did not register", async () => {
+    // The quiet-channel case the module header names as a known limitation:
+    // Telegram only produces delivery errors when it has something to deliver,
+    // so a stale tunnel address never errors and, before this comparison, read
+    // as healthy. No error is set here on purpose.
+    registeredWebhookUrl = "https://current.test/webhooks/telegram";
+    setWebhookInfo({
+      url: "https://stale.test/webhooks/telegram",
+      pending_update_count: 0,
+    });
+
+    const result = await checkTelegramWebhookHealth();
+
+    expect(result.status).toBe("url_mismatch");
+    expect(result.registeredUrl).toBe("https://stale.test/webhooks/telegram");
+    expect(result.expectedUrl).toBe("https://current.test/webhooks/telegram");
+  });
+
+  test("reports url_mismatch ahead of a recent delivery error", async () => {
+    // Both conditions hold. The mismatch is the cause and the error is its
+    // symptom, and they have different fixes, so the mismatch must win.
+    registeredWebhookUrl = "https://current.test/webhooks/telegram";
+    setWebhookInfo({
+      url: "https://stale.test/webhooks/telegram",
+      pending_update_count: 3,
+      last_error_date: Math.floor(Date.now() / 1000),
+      last_error_message: "Connection refused",
+    });
+
+    expect((await checkTelegramWebhookHealth()).status).toBe("url_mismatch");
+  });
+
+  test("reports unverified when nothing recorded which URL we registered", async () => {
+    // Reconciliation has not completed, or predates URL recording. Registered
+    // and quiet, but unproven: this must not report healthy.
+    registeredWebhookUrl = undefined;
+    setWebhookInfo({
+      url: "https://example.test/webhooks/telegram",
+      pending_update_count: 0,
+    });
+
+    const result = await checkTelegramWebhookHealth();
+
+    expect(result.status).toBe("unverified");
+    expect(result.expectedUrl).toBeUndefined();
+  });
+
+  test("an unverified webhook does not alert the guardian", async () => {
+    // Unproven is not broken. Alerting here would page every install whose
+    // last reconciliation predates recording.
+    registeredWebhookUrl = undefined;
+    setWebhookInfo({
+      url: "https://example.test/webhooks/telegram",
+      pending_update_count: 0,
+    });
+
+    await runTelegramWebhookHealthCheck();
+
+    expect(emittedSignals).toHaveLength(0);
+  });
+
   test("honors a configured telegram.apiBaseUrl", async () => {
     apiBaseUrl = "https://telegram-proxy.internal/";