@app-vitals/agent-admin 0.0.1 → 0.1.1

package/src/trial-expiry-warning-sweeper.ts

@@ -0,0 +1,447 @@
+/**
+ * admin/src/trial-expiry-warning-sweeper.ts
+ *
+ * TrialExpiryWarningSweeper (ATE-2.1) — one of the admin service's background
+ * loops, alongside session-alert-sweeper.ts and trial-expiry-sweeper.ts.
+ *
+ * Deliberately a separate module from trial-expiry-sweeper.ts, which owns the
+ * *lockdown* half of trial expiry (ATE-3.1: disabling an expired agent's crons
+ * once `trialExpiresAt` has passed). The two are sequential halves of the same
+ * lifecycle but share no state and run on different cadences — this one fires
+ * once per agent *before* expiry (hourly ticks, dedup'd via
+ * `trialExpiryWarnedAt`), the lockdown sweeper fires continuously *after* it
+ * (minutely ticks, idempotent by construction). Keeping them apart keeps each
+ * one's failure modes, counters, and log prefix
+ * (`[trial-expiry-warning-sweeper]` vs `[trial-expiry-sweeper]`) distinct.
+ *
+ * Every tick it:
+ *
+ *   1. Finds Agent rows with `trialExpiresAt` set and `trialExpiryWarnedAt`
+ *      still null (an unset `trialExpiresAt` — the ATE-1.1 default — is never
+ *      considered; see isDueForWarning below).
+ *   2. For each candidate whose `trialExpiresAt` falls within the configured
+ *      warning band — up to `warningDays` ahead (default 3) and no more than
+ *      `graceDays` behind (defaults to the same 3, so a trial that lapsed
+ *      long ago is never retroactively alerted) — looks up that agent's
+ *      own `SLACK_BOT_TOKEN` / `SLACK_ALERT_CHANNEL` (AgentEnv rows, decrypted
+ *      via AgentEnvService.getConfigBundle) and posts one Slack warning
+ *      naming the expiry date.
+ *   3. On a successful send, stamps `trialExpiryWarnedAt = now` via
+ *      AgentService.updateFields so the same agent is never warned twice.
+ *
+ * Structure mirrors session-alert-sweeper.ts: an injected Clock, a narrow
+ * *PrismaLike interface for the one read this sweeper does directly, a
+ * per-agent try/catch so one bad row can never abort the sweep, an in-flight
+ * `sweeping` guard on tick(), and registration via `setInterval` in
+ * admin/src/main.ts (NEVER inside an app factory, which must stay
+ * side-effect-free).
+ *
+ * Unlike session-alert-sweeper.ts, the write path reuses AgentService's
+ * existing updateFields() rather than a raw Prisma call — admin/src/agents.ts
+ * already owns "generic partial-field update for an agent" and ATE-2.1 is one
+ * more field on that same whitelist (see UpdateAgentFieldsInput).
+ *
+ * Admin has no bot-token WebClient of its own: each tenant agent's Slack
+ * credentials are its own AgentEnv rows, not a shared admin-side secret. So
+ * `sendSlackMessage` is injected (defaulting to sendTrialExpiryWarning, which
+ * constructs a fresh @slack/web-api WebClient per call using *that agent's*
+ * token) rather than a single shared client living on the sweeper.
+ *
+ * Failed-send / missing-config policy (see sweepAgent below): neither case
+ * stamps `trialExpiryWarnedAt`. A missing SLACK_BOT_TOKEN/SLACK_ALERT_CHANNEL
+ * or a failed postMessage both leave the dedup gate open so the next tick
+ * retries — silently stamping over an alert nobody received would satisfy
+ * "never warn twice" at the cost of "never warn at all" for a
+ * misconfigured/flaky tenant, which is worse. Both cases are logged (not
+ * swallowed) each tick so a persistently failing agent stays visible in the
+ * admin service's logs rather than silently going dark forever.
+ */
+
+import { WebClient } from "@slack/web-api";
+import type { AgentEnvBundle, AgentEnvService } from "./agent-envs.ts";
+import type { AgentService } from "./agents.ts";
+import { type Clock, SystemClock } from "./clock.ts";
+
+// ─── Types ──────────────────────────────────────────────────────────────────
+
+/** The slice of an Agent row this sweeper's candidate query needs. */
+export interface TrialExpiryAgentRow {
+  id: string;
+  name: string;
+  trialExpiresAt: Date | null;
+  trialExpiryWarnedAt: Date | null;
+}
+
+/**
+ * The narrow slice of PrismaClient this sweeper touches directly — same
+ * *PrismaLike pattern as session-alert-sweeper.ts's SessionAlertPrismaLike,
+ * so tests inject a plain object double instead of a real client. The write
+ * path (stamping trialExpiryWarnedAt) goes through AgentService.updateFields
+ * instead, so this interface only needs the one read.
+ */
+export interface TrialExpiryPrismaLike {
+  agent: {
+    findMany(args: {
+      where: { trialExpiresAt: { not: null }; trialExpiryWarnedAt: null };
+    }): Promise<TrialExpiryAgentRow[]>;
+  };
+}
+
+/** Params passed to the injected Slack-sending function. */
+export interface SendSlackWarningParams {
+  botToken: string;
+  channel: string;
+  text: string;
+}
+
+/**
+ * Sends one Slack message and reports whether it actually went out. Returns
+ * `false` (never throws) on any failure so a Slack outage can't abort the
+ * sweep — see the header comment for why a failed send does not stamp
+ * `trialExpiryWarnedAt`.
+ */
+export type SendSlackWarning = (
+  params: SendSlackWarningParams,
+) => Promise<boolean>;
+
+export interface TrialExpirySweeperDeps {
+  prisma: TrialExpiryPrismaLike;
+  agentService: Pick<AgentService, "updateFields">;
+  agentEnvService: Pick<AgentEnvService, "getConfigBundle">;
+  /**
+   * Injected so tests substitute a double instead of constructing a real
+   * @slack/web-api WebClient / hitting a real Slack API. Defaults to
+   * sendTrialExpiryWarning (the production implementation) when omitted.
+   */
+  sendSlackMessage?: SendSlackWarning;
+  clock?: Clock;
+  /** How many days out from `trialExpiresAt` the warning should fire. */
+  warningDays?: number;
+  /**
+   * How many days *past* `trialExpiresAt` the warning still fires. Defaults
+   * to `warningDays` (a symmetric band around expiry) — see isDueForWarning.
+   */
+  graceDays?: number;
+  /** Line logger for per-agent outcomes; defaults to `console.log`. */
+  log?: (line: string) => void;
+}
+
+/** Per-tick counters, also the value `tick()` resolves to. */
+export interface TrialExpirySweepResult {
+  /** Warning sent and trialExpiryWarnedAt stamped. */
+  warned: number;
+  /** Due for a warning, but the agent has no usable Slack config. */
+  skipped: number;
+  /** Due for a warning, Slack config present, but the send itself failed. */
+  failed: number;
+  /**
+   * Never warned, and `trialExpiresAt` is now more than `graceDays` in the
+   * past — deliberately not alerted (see isPastWarningGrace), counted so the
+   * decision stays visible in the per-tick summary instead of being silent.
+   */
+  stale: number;
+}
+
+/** Matches the task description's default warning window. */
+export const DEFAULT_TRIAL_EXPIRY_WARNING_DAYS = 3;
+
+const MS_PER_DAY = 24 * 60 * 60 * 1000;
+
+// ─── Pure helpers ───────────────────────────────────────────────────────────
+
+/**
+ * Whether an agent's `trialExpiresAt` is so far in the past that a warning is
+ * no longer worth sending. `trialExpiresAt` is freely admin-settable to an
+ * arbitrary past date (PATCH /agents/:id applies no future-only validation),
+ * and has been since ATE-1.1 — without this bound the first tick after this
+ * sweeper deploys would Slack-warn *every* long-lapsed trial agent at once,
+ * with wording about an expiry that came and went months ago.
+ *
+ * Exported so the sweeper can count (and surface) these rather than dropping
+ * them silently.
+ */
+export function isPastWarningGrace(
+  trialExpiresAt: Date,
+  now: Date,
+  graceDays: number,
+): boolean {
+  return trialExpiresAt.getTime() - now.getTime() < -graceDays * MS_PER_DAY;
+}
+
+/**
+ * Whether an agent is due for a trial-expiry warning right now, given only
+ * the two schema fields (trialExpiresAt, trialExpiryWarnedAt) plus the
+ * current time and the configured window:
+ *
+ *   - `trialExpiresAt` unset (ATE-1.1 default)      → never due
+ *   - `trialExpiryWarnedAt` already set              → never due (dedup —
+ *     acceptance criterion 2: a warned agent is never warned twice)
+ *   - `trialExpiresAt` more than `graceDays` in the past → never due (see
+ *     isPastWarningGrace: no retroactive alert burst for trials that lapsed
+ *     long before this sweeper existed)
+ *   - otherwise due once `trialExpiresAt` is at most `windowDays` away —
+ *     still including a *recently*-past `trialExpiresAt` (a trial that
+ *     expired days ago before anyone noticed deserves exactly one warning,
+ *     not silence — the message reads "expired on", see
+ *     buildTrialExpiryWarningMessage)
+ *
+ * `graceDays` defaults to `windowDays`, making the firing band symmetric
+ * around expiry: the same number of days of lateness the sweeper is willing
+ * to warn early about, it is willing to warn late about.
+ */
+export function isDueForWarning(
+  trialExpiresAt: Date | null,
+  trialExpiryWarnedAt: Date | null,
+  now: Date,
+  windowDays: number = DEFAULT_TRIAL_EXPIRY_WARNING_DAYS,
+  graceDays: number = windowDays,
+): boolean {
+  if (!trialExpiresAt) return false;
+  if (trialExpiryWarnedAt) return false;
+  if (trialExpiresAt.getTime() - now.getTime() > windowDays * MS_PER_DAY) {
+    return false;
+  }
+  return !isPastWarningGrace(trialExpiresAt, now, graceDays);
+}
+
+/**
+ * The Slack warning text for a given agent + expiry date. Explicitly does
+ * NOT say "deprovisioned" — ATE-3.1 was corrected (same planning session,
+ * same day) from auto-deprovisioning to lockdown-only: crons disabled and
+ * Slack access blocked, agent never deleted. Naming the actual date (rather
+ * than "in N days") matters because the sweeper's own dedup means this is
+ * often the *only* warning an operator gets before lockdown.
+ *
+ * Two tenses, because the sweeper deliberately still fires for a trial that
+ * lapsed within the grace window (see isDueForWarning): "expires on ..." for
+ * a future date, "expired on ..." for a past one. Same lockdown consequence
+ * either way — only the tense changes, so a late alert doesn't read as if
+ * the deadline were still ahead.
+ */
+export function buildTrialExpiryWarningMessage(
+  agentName: string,
+  trialExpiresAt: Date,
+  now: Date,
+): string {
+  const dateStr = trialExpiresAt.toISOString().slice(0, 10);
+  const alreadyExpired = trialExpiresAt.getTime() <= now.getTime();
+  if (alreadyExpired) {
+    return (
+      `:warning: Trial for agent \`${agentName}\` expired on ${dateStr}. ` +
+      `This agent's crons will be disabled and its Slack access will be ` +
+      `blocked until the trial is renewed.`
+    );
+  }
+  return (
+    `:warning: Trial for agent \`${agentName}\` expires on ${dateStr}. ` +
+    `After that date this agent's crons will be disabled and its Slack ` +
+    `access will be blocked until the trial is renewed.`
+  );
+}
+
+// ─── Production Slack sender ────────────────────────────────────────────────
+
+/**
+ * The slice of @slack/web-api's WebClient this module actually calls. Narrow
+ * on purpose so tests can inject a typed double covering the real send path
+ * (same approach as agent/src/runtime/startup-dm.ts's injected WebClient).
+ */
+export type SlackPostMessageClient = Pick<WebClient, "chat">;
+
+/** Builds a Slack client for one agent's bot token. */
+type SlackClientFactory = (botToken: string) => SlackPostMessageClient;
+
+/**
+ * The production factory: a fresh @slack/web-api WebClient per call, built
+ * from *the target agent's own* bot token — mirrors (not reuses, since it's
+ * cross-service) the alert-posting pattern in agent/src/runtime/cron-handler.ts.
+ * There is no long-lived client to share/cache: every tenant agent has a
+ * distinct token, and posting is infrequent (at most once per agent, ever,
+ * thanks to the dedup gate).
+ */
+export const defaultSlackClientFactory: SlackClientFactory = (botToken) =>
+  new WebClient(botToken);
+
+/**
+ * Production implementation of SendSlackWarning: posts one message through a
+ * real @slack/web-api client and converts any throw into `false` so a Slack
+ * outage can never abort the sweep.
+ *
+ * `createClient` is injected (defaulting to defaultSlackClientFactory) purely
+ * so tests can exercise this function's own send + try/catch path against a
+ * typed WebClient double instead of a live Slack workspace.
+ */
+export async function sendTrialExpiryWarning(
+  params: SendSlackWarningParams,
+  createClient: SlackClientFactory = defaultSlackClientFactory,
+): Promise<boolean> {
+  try {
+    const client = createClient(params.botToken);
+    await client.chat.postMessage({
+      channel: params.channel,
+      text: params.text,
+    });
+    return true;
+  } catch (err) {
+    console.error(
+      "[trial-expiry-warning-sweeper] Slack chat.postMessage failed:",
+      err,
+    );
+    return false;
+  }
+}
+
+// ─── Sweeper ────────────────────────────────────────────────────────────────
+
+export class TrialExpiryWarningSweeper {
+  private readonly clock: Clock;
+  private readonly warningDays: number;
+  private readonly graceDays: number;
+  private readonly sendSlackMessage: SendSlackWarning;
+  private readonly log: (line: string) => void;
+  /** True while a sweep is running — mirrors SessionAlertSweeper's guard. */
+  private sweeping = false;
+
+  constructor(private readonly deps: TrialExpirySweeperDeps) {
+    this.clock = deps.clock ?? SystemClock();
+    this.warningDays = deps.warningDays ?? DEFAULT_TRIAL_EXPIRY_WARNING_DAYS;
+    this.graceDays = deps.graceDays ?? this.warningDays;
+    this.sendSlackMessage = deps.sendSlackMessage ?? sendTrialExpiryWarning;
+    this.log = deps.log ?? ((line) => console.log(line));
+  }
+
+  /**
+   * One sweep. Never throws: a candidate-fetch failure short-circuits to an
+   * all-zero result, and every per-agent step is individually try/caught so
+   * one bad row can't abort the rest.
+   *
+   * Not re-entrant by design, for the same reason as SessionAlertSweeper: the
+   * dedup check-then-write straddles network I/O (Slack + Prisma), so two
+   * overlapping ticks could both observe `trialExpiryWarnedAt = null` and
+   * both send. If a previous tick is still in flight this returns an
+   * all-zero result immediately rather than racing it.
+   */
+  async tick(): Promise<TrialExpirySweepResult> {
+    if (this.sweeping) {
+      console.warn(
+        "[trial-expiry-warning-sweeper] previous tick still in flight — skipping",
+      );
+      return { warned: 0, skipped: 0, failed: 0, stale: 0 };
+    }
+    this.sweeping = true;
+    try {
+      return await this.sweep();
+    } finally {
+      this.sweeping = false;
+    }
+  }
+
+  private async sweep(): Promise<TrialExpirySweepResult> {
+    const result: TrialExpirySweepResult = {
+      warned: 0,
+      skipped: 0,
+      failed: 0,
+      stale: 0,
+    };
+
+    let candidates: TrialExpiryAgentRow[];
+    try {
+      candidates = await this.deps.prisma.agent.findMany({
+        where: { trialExpiresAt: { not: null }, trialExpiryWarnedAt: null },
+      });
+    } catch (err) {
+      console.error(
+        "[trial-expiry-warning-sweeper] candidate fetch failed:",
+        err,
+      );
+      return result;
+    }
+
+    const now = this.clock.now();
+    for (const agent of candidates) {
+      try {
+        await this.sweepAgent(agent, now, result);
+      } catch (err) {
+        console.error(
+          `[trial-expiry-warning-sweeper] agent ${agent.id} failed:`,
+          err,
+        );
+      }
+    }
+
+    const acted = result.warned + result.skipped + result.failed + result.stale;
+    if (acted > 0) {
+      console.log(
+        `[trial-expiry-warning-sweeper] warned=${result.warned} skipped=${result.skipped} failed=${result.failed} stale=${result.stale}`,
+      );
+    }
+
+    return result;
+  }
+
+  private async sweepAgent(
+    agent: TrialExpiryAgentRow,
+    now: Date,
+    result: TrialExpirySweepResult,
+  ): Promise<void> {
+    if (
+      !isDueForWarning(
+        agent.trialExpiresAt,
+        agent.trialExpiryWarnedAt,
+        now,
+        this.warningDays,
+        this.graceDays,
+      )
+    ) {
+      // Distinguish "not due yet / already warned" (nothing to say) from
+      // "expired too long ago to be worth warning about" — the latter is a
+      // deliberate non-alert, so count it rather than letting a long-lapsed
+      // trial disappear from the sweep with no trace.
+      if (
+        agent.trialExpiresAt &&
+        !agent.trialExpiryWarnedAt &&
+        isPastWarningGrace(agent.trialExpiresAt, now, this.graceDays)
+      ) {
+        result.stale++;
+      }
+      return;
+    }
+
+    const bundle: AgentEnvBundle | null =
+      await this.deps.agentEnvService.getConfigBundle(agent.id);
+    const botToken = bundle?.env.SLACK_BOT_TOKEN;
+    const channel = bundle?.env.SLACK_ALERT_CHANNEL;
+    if (!botToken || !channel) {
+      this.log(
+        `[trial-expiry-warning-sweeper] skip ${agent.id} (${agent.name}): missing SLACK_BOT_TOKEN or SLACK_ALERT_CHANNEL — will retry next tick`,
+      );
+      result.skipped++;
+      return;
+    }
+
+    // trialExpiresAt is guaranteed non-null here (isDueForWarning returned
+    // true), but TypeScript can't see through that without a cast.
+    const trialExpiresAt = agent.trialExpiresAt as Date;
+    const text = buildTrialExpiryWarningMessage(
+      agent.name,
+      trialExpiresAt,
+      now,
+    );
+    const sent = await this.sendSlackMessage({ botToken, channel, text });
+    if (!sent) {
+      console.error(
+        `[trial-expiry-warning-sweeper] failed to post trial-expiry warning for agent ${agent.id} (${agent.name}) — will retry next tick`,
+      );
+      result.failed++;
+      return;
+    }
+
+    await this.deps.agentService.updateFields(agent.id, {
+      trialExpiryWarnedAt: now,
+    });
+    result.warned++;
+    this.log(
+      `[trial-expiry-warning-sweeper] warned ${agent.id} (${agent.name}): trial expires ${trialExpiresAt.toISOString()}`,
+    );
+  }
+}

package/src/trial-expiry-warning-sweeper.unit.test.ts

@@ -0,0 +1,148 @@
+/**
+ * admin/src/trial-expiry-warning-sweeper.unit.test.ts
+ * Unit tests for the pure warning-window / dedup logic behind
+ * TrialExpiryWarningSweeper (ATE-2.1). No I/O, no doubles — just the exported
+ * pure functions.
+ */
+
+import { describe, expect, it } from "bun:test";
+import {
+  buildTrialExpiryWarningMessage,
+  DEFAULT_TRIAL_EXPIRY_WARNING_DAYS,
+  isDueForWarning,
+  isPastWarningGrace,
+} from "./trial-expiry-warning-sweeper.ts";
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+const NOW = new Date("2026-09-25T12:00:00.000Z");
+
+function daysFromNow(days: number): Date {
+  return new Date(NOW.getTime() + days * DAY_MS);
+}
+
+describe("isDueForWarning", () => {
+  it("is never due when trialExpiresAt is unset (ATE-1.1 agents)", () => {
+    expect(isDueForWarning(null, null, NOW, 3)).toBe(false);
+  });
+
+  it("is due when trialExpiresAt falls inside the warning window and never warned", () => {
+    expect(isDueForWarning(daysFromNow(2), null, NOW, 3)).toBe(true);
+  });
+
+  it("is not due when trialExpiresAt is further away than the warning window", () => {
+    expect(isDueForWarning(daysFromNow(10), null, NOW, 3)).toBe(false);
+  });
+
+  it("is due exactly at the window boundary (<=)", () => {
+    expect(isDueForWarning(daysFromNow(3), null, NOW, 3)).toBe(true);
+  });
+
+  it("is not due just past the window boundary", () => {
+    expect(isDueForWarning(daysFromNow(3.01), null, NOW, 3)).toBe(false);
+  });
+
+  it("is due for a recently-expired trial that was never warned", () => {
+    expect(isDueForWarning(daysFromNow(-1), null, NOW, 3)).toBe(true);
+  });
+
+  it("is still due exactly at the grace boundary behind expiry", () => {
+    expect(isDueForWarning(daysFromNow(-3), null, NOW, 3)).toBe(true);
+  });
+
+  it("is not due for a trial that lapsed further back than the grace window", () => {
+    // Without this bound the first tick after deploy would Slack-warn every
+    // long-lapsed trial agent at once — trialExpiresAt is freely settable to
+    // any past date via PATCH /agents/:id.
+    expect(isDueForWarning(daysFromNow(-3.01), null, NOW, 3)).toBe(false);
+    expect(isDueForWarning(daysFromNow(-180), null, NOW, 3)).toBe(false);
+  });
+
+  it("honours an explicit graceDays wider than the warning window", () => {
+    expect(isDueForWarning(daysFromNow(-10), null, NOW, 3, 14)).toBe(true);
+    expect(isDueForWarning(daysFromNow(-20), null, NOW, 3, 14)).toBe(false);
+  });
+
+  it("is never due once trialExpiryWarnedAt is set, no matter how close expiry is (dedup)", () => {
+    expect(isDueForWarning(daysFromNow(1), NOW, NOW, 3)).toBe(false);
+  });
+
+  it("is never due once warned even if the trial later gets pushed back out and back in the window", () => {
+    // Re-running the check after the alert has fired must never re-send for the
+    // same agent — trialExpiryWarnedAt gates it regardless of the current gap
+    // to trialExpiresAt (acceptance criterion 2).
+    const warnedAt = daysFromNow(-1);
+    expect(isDueForWarning(daysFromNow(2), warnedAt, NOW, 3)).toBe(false);
+  });
+
+  it("defaults the window to 3 days when not passed explicitly", () => {
+    expect(isDueForWarning(daysFromNow(2), null, NOW)).toBe(true);
+    expect(DEFAULT_TRIAL_EXPIRY_WARNING_DAYS).toBe(3);
+  });
+
+  it("defaults graceDays to the warning window (symmetric band)", () => {
+    expect(isDueForWarning(daysFromNow(-2), null, NOW)).toBe(true);
+    expect(isDueForWarning(daysFromNow(-4), null, NOW)).toBe(false);
+  });
+});
+
+describe("isPastWarningGrace", () => {
+  it("is false for a future expiry", () => {
+    expect(isPastWarningGrace(daysFromNow(1), NOW, 3)).toBe(false);
+  });
+
+  it("is false inside the grace window and true beyond it", () => {
+    expect(isPastWarningGrace(daysFromNow(-3), NOW, 3)).toBe(false);
+    expect(isPastWarningGrace(daysFromNow(-3.01), NOW, 3)).toBe(true);
+  });
+});
+
+describe("buildTrialExpiryWarningMessage", () => {
+  it("names the agent and the actual expiry date", () => {
+    const text = buildTrialExpiryWarningMessage(
+      "acme-agent",
+      new Date("2026-09-28T00:00:00.000Z"),
+      NOW,
+    );
+    expect(text).toContain("acme-agent");
+    expect(text).toContain("2026-09-28");
+  });
+
+  it("uses future tense for an expiry that has not happened yet", () => {
+    const text = buildTrialExpiryWarningMessage(
+      "acme-agent",
+      daysFromNow(2),
+      NOW,
+    );
+    expect(text).toContain("expires on");
+    expect(text).not.toContain("expired on");
+    expect(text).toContain("After that date");
+  });
+
+  it("uses past tense for a trial that already lapsed (grace-window alert)", () => {
+    // The sweeper still fires for a trial that lapsed within the grace
+    // window; "will be locked down after <date in the past>" would read as if
+    // the deadline were still ahead.
+    const text = buildTrialExpiryWarningMessage(
+      "acme-agent",
+      daysFromNow(-2),
+      NOW,
+    );
+    expect(text).toContain("expired on");
+    expect(text).not.toContain("expires on");
+    expect(text).not.toContain("After that date");
+    // Same lockdown consequence either way.
+    expect(text).toContain("crons will be disabled");
+  });
+
+  it("describes lockdown (crons disabled + Slack blocked), never deprovisioning", () => {
+    const text = buildTrialExpiryWarningMessage(
+      "acme-agent",
+      new Date("2026-09-28T00:00:00.000Z"),
+      NOW,
+    );
+    // ATE-3.1 was corrected to lockdown-only (crons disabled, Slack blocked) —
+    // it never deletes the agent. The warning text must not claim otherwise.
+    expect(text.toLowerCase()).not.toContain("deprovision");
+    expect(text.toLowerCase()).not.toContain("deleted");
+  });
+});

package/src/voice-contract.unit.test.ts

@@ -0,0 +1,102 @@
+/**
+ * admin/src/voice-contract.unit.test.ts
+ *
+ * Locks the voice WIRE CONTRACT at the admin layer — the env var NAMES the admin
+ * provisioner stamps onto provisioned agent pods — and documents the Whisper
+ * image ⇄ agent client contract so the two halves never drift.
+ *
+ * ── Whisper image vs agent client contract (CV-1.1) ─────────────────────────
+ * The chart's `provider=whisper` pod runs `onerahmet/openai-whisper-asr-webservice`.
+ * That image exposes a SINGLE ASR endpoint:
+ *
+ *     POST /asr?encode=true&task=transcribe&output=txt
+ *
+ * with the audio attached as the multipart field `audio_file`, returning the
+ * transcription as a PLAIN-TEXT body (with output=txt) — NOT the OpenAI
+ * `POST /v1/audio/transcriptions` JSON contract, and NOT a custom `/transcribe`
+ * JSON endpoint. The agent's `makeWhisperSvcClient` (agent/src/runtime/voice.ts) targets
+ * exactly that endpoint; the contract is exercised end-to-end in
+ * agent/src/runtime/voice.unit.test.ts and agent/src/runtime/voice.integration.test.ts.
+ *
+ * The admin's only responsibility is to hand the agent the Whisper Service URL
+ * under the agreed env var name `WHISPER_SERVICE_URL` (read in agent/src/runtime/config.ts).
+ * This file pins that name — and the ElevenLabs/Groq names — against the manifest
+ * builder so a rename on either side fails loudly here. No agent code is imported
+ * (admin must not couple to the agent package); the assertion is against the wire
+ * shape the admin emits.
+ */
+
+import { describe, expect, it } from "bun:test";
+import {
+  type AgentDeploymentOpts,
+  buildAgentDeploymentManifest,
+} from "./agent-manifest.ts";
+
+const baseOpts: AgentDeploymentOpts = {
+  agentId: "agent_42",
+  namespace: "shipwright",
+  image: "ghcr.io/app-vitals/shipwright-agent",
+  imageTag: "v1.2.3",
+  apiUrl: "http://shipwright-admin.shipwright.svc:3001",
+  pvcName: "agent-42-home",
+  secretName: "agent-42-token",
+};
+
+/** The exact env var the agent reads for the self-hosted Whisper Service URL. */
+const WHISPER_SERVICE_URL_ENV = "WHISPER_SERVICE_URL";
+
+describe("voice wire contract — env var names the admin stamps onto agent pods", () => {
+  it("uses the env var name WHISPER_SERVICE_URL (onerahmet /asr service URL)", () => {
+    const d = buildAgentDeploymentManifest({
+      ...baseOpts,
+      voice: { whisperServiceUrl: "http://r-shipwright-whisper:9000" },
+    });
+    const env = d.spec.template.spec.containers[0].env ?? [];
+    const names = env.map((e) => e.name);
+
+    // The agent's config.ts reads exactly this key; the onerahmet image is
+    // reached at `${WHISPER_SERVICE_URL}/asr?...` by makeWhisperSvcClient.
+    expect(names).toContain(WHISPER_SERVICE_URL_ENV);
+    const whisper = env.find((e) => e.name === WHISPER_SERVICE_URL_ENV);
+    expect(whisper?.value).toBe("http://r-shipwright-whisper:9000");
+  });
+
+  it("passes the Whisper URL as a plain value, never a secretKeyRef (the URL is not a secret)", () => {
+    const d = buildAgentDeploymentManifest({
+      ...baseOpts,
+      voice: { whisperServiceUrl: "http://r-shipwright-whisper:9000" },
+    });
+    const whisper = (d.spec.template.spec.containers[0].env ?? []).find(
+      (e) => e.name === WHISPER_SERVICE_URL_ENV,
+    );
+    expect(whisper?.value).toBeDefined();
+    expect(whisper?.valueFrom).toBeUndefined();
+  });
+
+  it("uses the conventional third-party env var names for keys (ELEVENLABS_API_KEY, GROQ_API_KEY)", () => {
+    const whisperMode = buildAgentDeploymentManifest({
+      ...baseOpts,
+      voice: {
+        whisperServiceUrl: "http://w:9000",
+        elevenLabsApiKey: "el",
+      },
+    });
+    const whisperNames = (
+      whisperMode.spec.template.spec.containers[0].env ?? []
+    ).map((e) => e.name);
+    expect(whisperNames).toContain("ELEVENLABS_API_KEY");
+    // whisper STT never flows a Groq key
+    expect(whisperNames).not.toContain("GROQ_API_KEY");
+
+    const groqMode = buildAgentDeploymentManifest({
+      ...baseOpts,
+      voice: { groqApiKey: "g", elevenLabsApiKey: "el" },
+    });
+    const groqNames = (groqMode.spec.template.spec.containers[0].env ?? []).map(
+      (e) => e.name,
+    );
+    expect(groqNames).toContain("GROQ_API_KEY");
+    // groq STT never points at a self-hosted Whisper pod
+    expect(groqNames).not.toContain(WHISPER_SERVICE_URL_ENV);
+  });
+});