talon-agent 5.10.0 → 5.12.0

package/src/core/engine/gateway-actions/triggers.ts

@@ -19,12 +19,12 @@ import {
   validateTimeout,
   writeScriptFile,
   DEFAULT_TIMEOUT_SECONDS,
-  MAX_ACTIVE_PER_CHAT,
   type TriggerLanguage,
 } from "../../../storage/triggers.js";
 import {
   cancelTrigger,
   spawnTrigger,
+  triggerCapError,
 } from "../../background/triggers/index.js";
 import { log } from "../../../util/log.js";
 import { validateJobModelOverride } from "./validation.js";
@@ -61,13 +61,11 @@ export const triggerHandlers: SharedActionHandlers = {
         error: `A trigger named "${name}" already exists in this chat. Cancel it first or pick a different name.`,
       };
     }
-    const active = getActiveTriggersForChat(chatKey);
-    if (active.length >= MAX_ACTIVE_PER_CHAT) {
-      return {
-        ok: false,
-        error: `Per-chat trigger cap reached (${MAX_ACTIVE_PER_CHAT} active). Cancel one before creating another.`,
-      };
-    }
+    const capErr = triggerCapError(
+      getActiveTriggersForChat(chatKey),
+      persistent,
+    );
+    if (capErr) return { ok: false, error: capErr };
 
     // Validate the model up front so a bad id is rejected here instead of
     // silently failing at fire time.

package/src/core/mcp-hub/launcher.ts

@@ -40,7 +40,9 @@
  *   2. `TALON_BRIDGE_URL/health` stops responding for several
  *      consecutive pings — Talon's gateway is gone. Catches the
  *      "kilo serve / opencode serve outlives Talon" case where those
- *      daemons keep our stdin open across Talon restarts.
+ *      daemons keep our stdin open across Talon restarts. A ping that only
+ *      times out (port still bound, gateway busy) is tolerated for minutes,
+ *      not seconds — see BridgeWatchdog.
  */
 
 import crossSpawn from "cross-spawn";
@@ -203,7 +205,75 @@ export function wrapMcpCommand(command: readonly string[]): string[] {
 // within ~1 minute.
 const BRIDGE_PING_INTERVAL_MS = 15_000;
 const BRIDGE_PING_TIMEOUT_MS = 2_000;
-const BRIDGE_FAILURES_BEFORE_EXIT = 4;
+export const BRIDGE_FAILURES_BEFORE_EXIT = 4;
+// A ping that TIMES OUT means the port is still bound — the kernel accepted
+// the connection — but the gateway is too busy to answer within 2s (event
+// loop saturated by a burst of agents, a big synchronous write, …). That is
+// a live Talon, not a dead one, so it gets a much longer budget (~5 min)
+// before the child is evicted. Only a truly wedged daemon reaches it.
+export const BRIDGE_UNRESPONSIVE_BEFORE_EXIT = 20;
+
+/**
+ * Outcome of one bridge health ping:
+ *   - "ok": /health answered 2xx.
+ *   - "unreachable": nothing healthy behind the port (connection refused or
+ *     reset, non-2xx reply) — Talon is gone or restarting.
+ *   - "unresponsive": the request timed out — something holds the port but
+ *     is slow to answer; Talon is alive but busy.
+ */
+export type BridgePingOutcome = "ok" | "unreachable" | "unresponsive";
+
+/** Classify a rejected health fetch. Timeouts/aborts mean "busy", not "gone". */
+export function classifyBridgePingError(
+  err: unknown,
+): Exclude<BridgePingOutcome, "ok"> {
+  const name = (err as { name?: unknown } | null)?.name;
+  return name === "TimeoutError" || name === "AbortError"
+    ? "unresponsive"
+    : "unreachable";
+}
+
+/** Ping `${bridgeUrl}/health` once. Never throws. */
+export async function pingBridge(
+  bridgeUrl: string,
+  timeoutMs: number = BRIDGE_PING_TIMEOUT_MS,
+): Promise<BridgePingOutcome> {
+  try {
+    const resp = await fetch(`${bridgeUrl}/health`, {
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+    // Drain the body so the socket is released promptly.
+    await resp.arrayBuffer().catch(() => undefined);
+    return resp.ok ? "ok" : "unreachable";
+  } catch (err) {
+    return classifyBridgePingError(err);
+  }
+}
+
+/**
+ * Consecutive-failure bookkeeping for the bridge watchdog. `record()`
+ * returns true once the child should be shut down: after
+ * BRIDGE_FAILURES_BEFORE_EXIT failures ending in an "unreachable" ping (the
+ * port is really closed), or after BRIDGE_UNRESPONSIVE_BEFORE_EXIT failures
+ * of any kind (the daemon is wedged, not just busy).
+ */
+export class BridgeWatchdog {
+  consecutiveFailures = 0;
+
+  record(outcome: BridgePingOutcome): boolean {
+    if (outcome === "ok") {
+      this.consecutiveFailures = 0;
+      return false;
+    }
+    this.consecutiveFailures += 1;
+    if (this.consecutiveFailures >= BRIDGE_UNRESPONSIVE_BEFORE_EXIT)
+      return true;
+    return (
+      outcome === "unreachable" &&
+      this.consecutiveFailures >= BRIDGE_FAILURES_BEFORE_EXIT
+    );
+  }
+}
 
 /**
  * Run the supervisor over `argvTail` = [cmd, ...args].
@@ -346,29 +416,19 @@ export function runSupervisor(argvTail: string[]): Promise<never> {
   // (every Talon-spawned MCP server has it; ad-hoc supervisor uses
   // without the env var keep the stdin-EOF-only behavior).
   if (BRIDGE_URL) {
-    let consecutiveFailures = 0;
+    const watchdog = new BridgeWatchdog();
     const tick = async (): Promise<void> => {
       if (terminating) return;
-      try {
-        const resp = await fetch(`${BRIDGE_URL}/health`, {
-          signal: AbortSignal.timeout(BRIDGE_PING_TIMEOUT_MS),
-        });
-        if (resp.ok) {
-          consecutiveFailures = 0;
-          return;
-        }
-        consecutiveFailures += 1;
-      } catch {
-        consecutiveFailures += 1;
-      }
-      if (consecutiveFailures >= BRIDGE_FAILURES_BEFORE_EXIT) {
-        // Talon's gateway is gone. The MCP child has nothing useful to
-        // serve — bridge calls would 404 against a dead port — so shut
-        // down. Kilo/OpenCode notice the stdio close on the next
-        // interaction and drop the registration on their side.
+      const outcome = await pingBridge(BRIDGE_URL);
+      if (terminating) return;
+      if (watchdog.record(outcome)) {
+        // Talon's gateway is gone (or wedged for minutes). The MCP child
+        // has nothing useful to serve — bridge calls would 404 against a
+        // dead port — so shut down. Kilo/OpenCode notice the stdio close
+        // on the next interaction and drop the registration on their side.
         process.stderr.write(
-          `mcp-launcher: bridge ${BRIDGE_URL} unreachable for ${
-            consecutiveFailures * (BRIDGE_PING_INTERVAL_MS / 1000)
+          `mcp-launcher: bridge ${BRIDGE_URL} ${outcome} for ${
+            watchdog.consecutiveFailures * (BRIDGE_PING_INTERVAL_MS / 1000)
           }s; shutting down child\n`,
         );
         terminate(0);

package/src/core/mesh/devices/registry.ts

@@ -205,12 +205,25 @@ export class MeshRegistry {
    * taking their location + history with them (an evicted device leaves no
    * residue). Returns whether anything went, so callers know the location and
    * history sidecars need rewriting too.
+   *
+   * Two devices can legitimately share a `lastSeen` millisecond (a bulk
+   * backfill, or two heartbeats landing in the same event-loop tick) —
+   * ties are broken by registration order (the earlier registration is
+   * treated as staler) so eviction is deterministic rather than depending on
+   * `Array.prototype.sort`'s stability guarantee to preserve the `Map`'s
+   * insertion order.
    */
   private enforceDeviceCap(): boolean {
     if (this.devices.size <= MAX_DEVICES) return false;
     const stalest = [...this.devices.values()]
-      .sort((a, b) => a.lastSeen - b.lastSeen)
-      .slice(0, this.devices.size - MAX_DEVICES);
+      .map((device, insertionIndex) => ({ device, insertionIndex }))
+      .sort(
+        (a, b) =>
+          a.device.lastSeen - b.device.lastSeen ||
+          a.insertionIndex - b.insertionIndex,
+      )
+      .slice(0, this.devices.size - MAX_DEVICES)
+      .map(({ device }) => device);
     for (const device of stalest) {
       this.devices.delete(device.id);
       this.locations.delete(device.id);
@@ -230,12 +243,21 @@ export class MeshRegistry {
    * unknown device ids past MAX_UNREGISTERED_LOCATIONS are dropped
    * stalest-first, with their history. Registered devices are untouched —
    * their entries are already bounded by the device cap.
+   *
+   * Same explicit tie-break as {@link enforceDeviceCap}: fixes with an
+   * identical `ts` fall back to insertion order instead of leaning on sort
+   * stability.
    */
   private enforceOrphanLocationCap(): boolean {
     let dropped = false;
     const orphans = [...this.locations.values()]
       .filter((l) => !this.devices.has(l.deviceId))
-      .sort((a, b) => a.ts - b.ts);
+      .map((location, insertionIndex) => ({ location, insertionIndex }))
+      .sort(
+        (a, b) =>
+          a.location.ts - b.location.ts || a.insertionIndex - b.insertionIndex,
+      )
+      .map(({ location }) => location);
     if (orphans.length > MAX_UNREGISTERED_LOCATIONS) {
       for (const loc of orphans.slice(
         0,

package/src/core/tools/ops/triggers.ts

@@ -57,7 +57,8 @@ shutdown/crash are respawned (not ones that exited on their own), the
 script must be safe to re-run from scratch, and timeout_seconds is ignored
 (persistent triggers run until cancelled or until Talon shuts down).
 
-Per-chat cap of 5 active triggers.`;
+Per-chat cap on active triggers (default 5; config triggers.maxActivePerChat,
+with an optional separate triggers.maxPersistentPerChat budget).`;
 
 export const triggerTools: ToolDefinition[] = [
   {

package/src/frontend/presentation/reports.ts

@@ -462,7 +462,10 @@ export function renderUsageMessage(
     if (entry.plan.resetsAvailable) {
       const n = entry.plan.resetsAvailable;
       const resets = `usage limit reset${n === 1 ? "" : "s"} available`;
-      lines.push(`  • You have ${fmt.bold(String(n))} ${resets}`);
+      const by = entry.plan.resetsExpireLabel
+        ? ` ${fmt.escape(`(use by ${entry.plan.resetsExpireLabel})`)}`
+        : "";
+      lines.push(`  • You have ${fmt.bold(String(n))} ${resets}${by}`);
     }
     for (const w of entry.plan.windows) {
       const reset = w.resetLabel ? ` reset ${w.resetLabel}` : "";

package/src/frontend/presentation/status-context.ts

@@ -404,6 +404,8 @@ export interface PlanDisplay {
   windows: PlanWindowDisplay[];
   /** Set only when the account still has one-shot rate-limit resets left. */
   resetsAvailable: number | undefined;
+  /** Deadline for the soonest-expiring banked reset, when the plan reports one. */
+  resetsExpireLabel?: string;
   /** Set only when the figures have aged, e.g. "12m ago". */
   ageLabel: string | undefined;
 }
@@ -432,6 +434,9 @@ export function buildPlanDisplay(
   return {
     plan: usage.plan,
     resetsAvailable: usage.resetsAvailable,
+    resetsExpireLabel: usage.resetsAvailable
+      ? planResetLabel(usage.resetsExpireAt)
+      : undefined,
     ageLabel:
       age > PLAN_STALE_AFTER_MS
         ? formatRelativeAge(usage.fetchedAt)

package/src/frontend/telegram/callbacks/index.ts

@@ -12,6 +12,7 @@
  *   - `auth`     — `auth:*` (backend sign-in panel, admin only)
  *   - `whatsapp` — `whatsapp:*` (WhatsApp link panel, admin only)
  *   - `backup`   — `backup:*` (restore confirmation, admin only)
+ *   - `usage-reset` — `ureset:*` (spend a banked limit reset, admin DM only)
  *
  * `registerCallbacks` installs one `callback_query:data` listener that
  * dispatches on the data prefix, preserving the original order and the
@@ -31,6 +32,7 @@ import { handleModelCallback } from "./model.js";
 import { handleAuthCallback } from "./auth.js";
 import { handleWhatsAppCallback } from "./whatsapp.js";
 import { handleBackupCallback } from "./backup.js";
+import { handleUsageResetCallback } from "./usage-reset.js";
 
 export { answerCallbackQuerySafe } from "./query.js";
 
@@ -58,6 +60,12 @@ export function registerCallbacks(
       return;
     }
 
+    // Spending a banked limit reset — irreversible, so confirm-gated.
+    if (data.startsWith("ureset:")) {
+      await handleUsageResetCallback(ctx, data);
+      return;
+    }
+
     // Handle pulse callbacks
     if (data.startsWith("pulse:")) {
       await handlePulseCallback(ctx, data, cid);

package/src/frontend/telegram/callbacks/usage-reset.ts

@@ -0,0 +1,333 @@
+/**
+ * `ureset:*` callbacks — spending a banked usage-limit reset from /usage.
+ *
+ *   ureset:ask:<backend>  show the confirmation for that backend's next grant
+ *   ureset:ok:<token>     spend it (or retry an unconfirmed claim)
+ *   ureset:no:<token>     drop the confirmation
+ *
+ * A reset is one-off and belongs to the operator, so every step is gated on
+ * the configured admin in a private chat, and nothing is spent without the
+ * explicit Confirm press. The confirmation's idempotency key is minted once
+ * and reused by every retry of it, and a press that lands while a claim is
+ * in flight is ignored — a double tap can never spend two resets.
+ */
+
+import { randomBytes } from "node:crypto";
+import type { Context } from "grammy";
+import type {
+  BankedResetClaim,
+  BankedResetControl,
+  BankedResetOffer,
+} from "../../../core/agent-runtime/capabilities.js";
+import { getPooledBackend } from "../../../core/engine/backend-controller/index.js";
+import type { BackendUsageEntry } from "../../presentation/plan-usage-report.js";
+import { formatSmartTimestamp } from "../../../util/time.js";
+import { escapeHtml } from "../formatting.js";
+import { isConfiguredAdmin } from "../commands/state.js";
+import { answerCallbackQuerySafe } from "./query.js";
+
+type Button = { text: string; callback_data: string };
+
+const PENDING_TTL_MS = 10 * 60_000;
+const RETRYABLE: ReadonlySet<BankedResetClaim["result"]> = new Set([
+  "unavailable",
+  "rate_limited",
+  "error",
+]);
+
+interface Pending {
+  chatId: number;
+  userId: number;
+  backendId: string;
+  grantId: string;
+  /** Idempotency key: one per confirmation, shared by all its retries. */
+  requestId: string;
+  clears: string[];
+  claiming: boolean;
+  /** A claim was sent and its outcome is unconfirmed. */
+  attempted: boolean;
+  createdAt: number;
+}
+
+const pending = new Map<string, Pending>();
+
+function newToken(): string {
+  return randomBytes(6).toString("hex");
+}
+
+function newRequestId(): string {
+  return randomBytes(16).toString("hex");
+}
+
+/** Test hook: forget every open confirmation. */
+export function resetUsageResetState(): void {
+  pending.clear();
+}
+
+/** Who may spend a reset: the configured admin, in a DM. */
+export function canUseReset(ctx: Context): boolean {
+  return isConfiguredAdmin(ctx) && ctx.chat?.type === "private";
+}
+
+function controlFor(backendId: string): BankedResetControl | undefined {
+  return getPooledBackend(backendId)?.usage?.bankedResets;
+}
+
+/**
+ * The "Use a reset" row for a /usage reply, or undefined when this viewer
+ * mustn't see it or no backend has a reset to spend.
+ */
+export function usageResetKeyboard(
+  ctx: Context,
+  entries: BackendUsageEntry[],
+): Button[][] | undefined {
+  if (!canUseReset(ctx)) return undefined;
+  const offers = entries.filter(
+    (e) => (e.plan?.resetsAvailable ?? 0) > 0 && controlFor(e.id),
+  );
+  if (offers.length === 0) return undefined;
+  return offers.map((e) => [
+    {
+      text: offers.length === 1 ? "Use a reset" : `Use a ${e.label} reset`,
+      callback_data: `ureset:ask:${e.id}`,
+    },
+  ]);
+}
+
+const WINDOW_NAMES: Record<string, string> = {
+  five_hour: "5-hour",
+  seven_day: "weekly",
+  seven_day_overage_included: "weekly (incl. overage)",
+  seven_day_opus: "weekly Opus",
+  seven_day_sonnet: "weekly Sonnet",
+};
+
+function windowName(key: string): string {
+  return WINDOW_NAMES[key] ?? key.replace(/_/g, " ");
+}
+
+function when(iso: string | undefined): string | undefined {
+  const t = iso ? Date.parse(iso) : NaN;
+  return Number.isFinite(t) ? formatSmartTimestamp(t) : undefined;
+}
+
+function plural(n: number): string {
+  return `${n} reset${n === 1 ? "" : "s"}`;
+}
+
+/** The confirmation text for spending `offer`. */
+export function renderResetConfirmation(
+  offer: BankedResetOffer,
+  now = Date.now(),
+): string {
+  const { grant } = offer;
+  const lines = [
+    "<b>Use a usage-limit reset?</b>",
+    `<i>${escapeHtml(grant.label)}</i>`,
+    "",
+  ];
+  if (grant.clears.length > 0) {
+    lines.push(`Clears: ${grant.clears.map(windowName).join(", ")}`);
+    const current = grant.clears
+      .filter((k) => grant.percentUsed[k] !== undefined)
+      .map((k) => `${windowName(k)} ${grant.percentUsed[k]}%`);
+    if (current.length > 0) lines.push(`Right now: ${current.join(" · ")}`);
+  }
+  const by = when(grant.endsAt);
+  if (by) lines.push(`Use by: ${escapeHtml(by)}`);
+  lines.push(`Resets left: ${offer.totalResetsLeft}`);
+
+  const warnings: string[] = [];
+  if (grant.useRequiresLimit && !offer.atLimit)
+    warnings.push(
+      "⚠️ This reset only works while you're at a limit, and you aren't — " +
+        "the claim will be refused and the reset kept.",
+    );
+  const cooldown = offer.cooldownUntil ? Date.parse(offer.cooldownUntil) : NaN;
+  if (Number.isFinite(cooldown) && cooldown > now)
+    warnings.push(
+      `⚠️ A cooldown is running until ${escapeHtml(when(offer.cooldownUntil) ?? "")} — ` +
+        "the claim will likely be refused.",
+    );
+  if (warnings.length > 0) lines.push("", ...warnings);
+  lines.push("", "This spends a one-off reset and can't be undone.");
+  return lines.join("\n");
+}
+
+/** A claim's outcome in plain words. */
+export function describeClaim(
+  claim: BankedResetClaim,
+  clears: string[] = [],
+): string {
+  const left =
+    claim.resetsLeft !== undefined ? ` ${plural(claim.resetsLeft)} left.` : "";
+  const cleared = claim.cleared.length > 0 ? claim.cleared : clears;
+  switch (claim.result) {
+    case "reset":
+      return (
+        "✅ Reset used — " +
+        (cleared.length > 0
+          ? `your ${cleared.map(windowName).join(", ")} limits are clear again.`
+          : "your limits are clear again.") +
+        left
+      );
+    case "already_used":
+      return `That reset was already used, so nothing more was spent.${left}`;
+    case "not_limited":
+      return "Nothing to reset — you aren't at a limit, and this reset only works when you are. It's still banked.";
+    case "cooldown": {
+      const until = when(claim.cooldownUntil);
+      return `A reset was used recently, so this one is on cooldown${until ? ` until ${escapeHtml(until)}` : ""}. Nothing was spent.`;
+    }
+    case "ineligible":
+      return `This account can't use that reset right now${claim.reason ? ` (${escapeHtml(claim.reason)})` : ""}. Nothing was spent.`;
+    case "rate_limited":
+      return "Too many attempts — wait a minute, then tap Retry. The retry reuses this request, so it can't spend twice.";
+    case "auth_error":
+      return "Couldn't sign in to Claude with the stored credentials, so nothing was sent.";
+    default:
+      return "Couldn't confirm whether the reset went through. Tap Retry — it reuses the same request, so it can't spend twice.";
+  }
+}
+
+function confirmKeyboard(token: string, retry = false): Button[][] {
+  return [
+    [
+      {
+        text: retry ? "Retry" : "Confirm",
+        callback_data: `ureset:ok:${token}`,
+      },
+      { text: "Cancel", callback_data: `ureset:no:${token}` },
+    ],
+  ];
+}
+
+/**
+ * Look up what a claim would spend and reply with the confirmation. Shared
+ * by the /usage button and `/usage reset`.
+ */
+export async function sendResetConfirmation(
+  ctx: Context,
+  backendId: string,
+): Promise<void> {
+  const control = controlFor(backendId);
+  const offer = await control?.getOffer().catch(() => undefined);
+  if (!offer) {
+    await ctx.reply("No usage-limit reset is available to use right now.");
+    return;
+  }
+  const chatId = ctx.chat?.id ?? 0;
+  // One open confirmation per chat: a newer one retires the older buttons.
+  for (const [token, p] of pending)
+    if (p.chatId === chatId && !p.claiming) pending.delete(token);
+  const token = newToken();
+  pending.set(token, {
+    chatId,
+    userId: ctx.from?.id ?? 0,
+    backendId,
+    grantId: offer.grant.id,
+    requestId: newRequestId(),
+    clears: offer.grant.clears,
+    claiming: false,
+    attempted: false,
+    createdAt: Date.now(),
+  });
+  await ctx.reply(renderResetConfirmation(offer), {
+    parse_mode: "HTML",
+    reply_markup: { inline_keyboard: confirmKeyboard(token) },
+  });
+}
+
+function live(token: string, ctx: Context): Pending | undefined {
+  const p = pending.get(token);
+  if (!p) return undefined;
+  if (Date.now() - p.createdAt > PENDING_TTL_MS && !p.claiming) {
+    pending.delete(token);
+    return undefined;
+  }
+  if (p.chatId !== ctx.chat?.id || p.userId !== ctx.from?.id) return undefined;
+  return p;
+}
+
+async function confirm(ctx: Context, token: string): Promise<void> {
+  const p = live(token, ctx);
+  if (!p) {
+    await answerCallbackQuerySafe(ctx, {
+      text: "This confirmation has expired — run /usage again.",
+    });
+    return;
+  }
+  if (p.claiming) {
+    await answerCallbackQuerySafe(ctx, { text: "Already on it…" });
+    return;
+  }
+  p.claiming = true;
+  await answerCallbackQuerySafe(ctx, { text: "Using the reset…" });
+  await ctx.editMessageText("⏳ Using the reset…").catch(() => {});
+
+  let claim: BankedResetClaim;
+  try {
+    const control = controlFor(p.backendId);
+    claim = control
+      ? await control.claim(p.grantId, p.requestId)
+      : { result: "error", cleared: [] };
+  } catch {
+    claim = { result: "error", cleared: [] };
+  }
+
+  const text = describeClaim(claim, p.clears);
+  if (RETRYABLE.has(claim.result)) {
+    // Keep the confirmation (and its request id) so Retry is idempotent.
+    p.claiming = false;
+    p.attempted = true;
+    await ctx
+      .editMessageText(text, {
+        parse_mode: "HTML",
+        reply_markup: { inline_keyboard: confirmKeyboard(token, true) },
+      })
+      .catch(() => {});
+    return;
+  }
+  pending.delete(token);
+  await ctx.editMessageText(text, { parse_mode: "HTML" }).catch(() => {});
+}
+
+async function cancel(ctx: Context, token: string): Promise<void> {
+  const p = live(token, ctx);
+  if (p?.claiming) {
+    await answerCallbackQuerySafe(ctx, { text: "Already being claimed." });
+    return;
+  }
+  pending.delete(token);
+  await answerCallbackQuerySafe(ctx, { text: "Cancelled." });
+  await ctx
+    .editMessageText(
+      p?.attempted
+        ? "Closed. If the last attempt went through, /usage will show one reset fewer."
+        : "No reset used.",
+    )
+    .catch(() => {});
+}
+
+export async function handleUsageResetCallback(
+  ctx: Context,
+  data: string,
+): Promise<void> {
+  if (!canUseReset(ctx)) {
+    await answerCallbackQuerySafe(ctx, { text: "Not authorized." });
+    return;
+  }
+  const [, action, arg] = data.split(":");
+  if (!arg || !/^[A-Za-z0-9_-]{1,40}$/.test(arg)) {
+    await answerCallbackQuerySafe(ctx, { text: "Invalid callback data" });
+    return;
+  }
+  if (action === "ask") {
+    await answerCallbackQuerySafe(ctx);
+    await sendResetConfirmation(ctx, arg);
+    return;
+  }
+  if (action === "ok") return confirm(ctx, arg);
+  if (action === "no") return cancel(ctx, arg);
+  await answerCallbackQuerySafe(ctx, { text: "Invalid callback data" });
+}

package/src/frontend/telegram/commands/admin.ts

@@ -25,6 +25,11 @@ import {
   renderUsageMessage,
 } from "../render/reports.js";
 import { collectPlanUsage } from "../../presentation/plan-usage-report.js";
+import {
+  canUseReset,
+  sendResetConfirmation,
+  usageResetKeyboard,
+} from "../callbacks/usage-reset.js";
 import { collectDoctorReport } from "../../../core/doctor/index.js";
 import { handleAdminCommand } from "../admin.js";
 import { getTodayMetrics } from "../../../storage/metrics.js";
@@ -58,11 +63,32 @@ function registerMetricsCommand(bot: Bot): void {
 
 // /usage — plan limits across every exposed backend, not just this
 // chat's. Not admin-gated: it says how close the shared account is to a
-// wall, which is exactly what a user hitting one needs to know.
+// wall, which is exactly what a user hitting one needs to know. Spending a
+// banked reset is: the "Use a reset" button (and `/usage reset`) only ever
+// reach the configured admin in a DM, and both end at a Confirm press.
 function registerUsageCommand(bot: Bot, config: TalonConfig): void {
   bot.command("usage", async (ctx) => {
     const entries = await collectPlanUsage(config);
-    await ctx.reply(renderUsageMessage(entries), { parse_mode: "HTML" });
+    if (ctx.match.trim().toLowerCase() === "reset") {
+      if (!canUseReset(ctx)) {
+        await ctx.reply(
+          "Only the admin can use a usage-limit reset, in a private chat.",
+        );
+        return;
+      }
+      const target = entries.find((e) => (e.plan?.resetsAvailable ?? 0) > 0);
+      if (!target) {
+        await ctx.reply("No usage-limit reset is available to use right now.");
+        return;
+      }
+      await sendResetConfirmation(ctx, target.id);
+      return;
+    }
+    const keyboard = usageResetKeyboard(ctx, entries);
+    await ctx.reply(renderUsageMessage(entries), {
+      parse_mode: "HTML",
+      ...(keyboard ? { reply_markup: { inline_keyboard: keyboard } } : {}),
+    });
   });
 }
 

package/src/frontend/telegram/commands/state.ts

@@ -28,6 +28,17 @@ export function isAuthorizedAdmin(ctx: Context): boolean {
   );
 }
 
+/**
+ * Stricter than `isAuthorizedAdmin`: a configured admin id is required and
+ * must match. For irreversible actions on the operator's own account, where
+ * "no admin configured" must not mean "anyone may".
+ */
+export function isConfiguredAdmin(ctx: Context): boolean {
+  return (
+    adminState.adminUserId !== 0 && ctx.from?.id === adminState.adminUserId
+  );
+}
+
 export type RegisterDeps = {
   config: import("../../../core/config/index.js").TalonConfig;
   gateway?: { backend: Backend | null };