talon-agent 3.16.0 → 3.17.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "talon-agent",
-  "version": "3.16.0",
+  "version": "3.17.0",
   "description": "Multi-frontend AI agent with full tool access, streaming, cron jobs, and plugin system",
   "author": "Dylan Neve",
   "license": "MIT",

package/src/app.ts

@@ -11,6 +11,7 @@ import { startUploadCleanup, stopUploadCleanup } from "./util/workspace.js";
 import { flushDatabase } from "./storage/db.js";
 import { getActiveCount } from "./core/engine/dispatcher.js";
 import { startPulseTimer, stopPulseTimer } from "./core/background/pulse.js";
+import { stopPlanAlerts } from "./core/background/plan-alerts.js";
 import {
   startHeartbeatTimer,
   stopHeartbeatTimer,
@@ -179,6 +180,7 @@ async function gracefulShutdown(signal: string): Promise<void> {
     await awaitHeartbeat();
   });
   await shutdownStep("cron timer", stopCronTimer);
+  await shutdownStep("plan alerts", stopPlanAlerts);
   await shutdownStep("trigger prune timer", () => {
     if (triggerPruneTimer) clearInterval(triggerPruneTimer);
     triggerPruneTimer = null;

package/src/backend/codex/factory.ts

@@ -16,7 +16,9 @@ import {
   type ChatBackend,
   type BackgroundRunner,
   type ModelCatalog,
+  type UsageTelemetry,
 } from "../../core/agent-runtime/capabilities.js";
+import { getPlanUsage as getCodexPlanUsage } from "./plan-usage.js";
 
 import { initCodexAgent, getCodexAuthInfo } from "./init.js";
 import { handleMessage as codexHandleMessage } from "./handler/index.js";
@@ -77,6 +79,12 @@ const codexFactory: BackendFactory = {
     // the per-chat thread lifecycle directly via `setSessionId` on
     // `storage/sessions.ts`. No `sessions` slot needed; `/reset`
     // clears the stored thread id through the storage path.
+    // No per-session snapshot to offer, but a ChatGPT-plan install can
+    // report its rate-limit windows.
+    const usage: UsageTelemetry = {
+      getPlanUsage: () => getCodexPlanUsage(),
+    };
+
     const backend = composeBackend({
       id: "codex",
       label: "Codex",
@@ -84,6 +92,7 @@ const codexFactory: BackendFactory = {
       chat,
       background,
       models,
+      usage,
     });
 
     return {

package/src/backend/codex/plan-usage.ts

@@ -0,0 +1,160 @@
+/**
+ * ChatGPT subscription rate-limit windows for the Codex backend.
+ *
+ * The Codex CLI reads these from an endpoint on the ChatGPT backend and
+ * caches the result in its session transcripts; `/status` renders that cache
+ * rather than re-fetching. Talon queries the endpoint directly so `/usage`
+ * reports the current state instead of whatever the last turn happened to
+ * see, using the OAuth token `codex login` already stored.
+ *
+ * Degrades to `undefined` for API-key installs (no plan to report), a
+ * missing or expired token, or any transport failure.
+ */
+
+import { readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { logWarn } from "../../util/log.js";
+import type {
+  PlanUsage,
+  PlanWindow,
+} from "../../core/agent-runtime/capabilities.js";
+
+const USAGE_ENDPOINT = "https://chatgpt.com/backend-api/wham/usage";
+const REQUEST_TIMEOUT_MS = 5_000;
+const CACHE_TTL_MS = 60_000;
+
+let cache: { value: PlanUsage; fetchedAt: number } | undefined;
+let inFlight: Promise<PlanUsage | undefined> | undefined;
+
+function authPath(): string {
+  const home = process.env.CODEX_HOME?.trim();
+  return home && home.length > 0
+    ? join(home, "auth.json")
+    : join(homedir(), ".codex", "auth.json");
+}
+
+interface CodexAuth {
+  accessToken: string;
+  accountId?: string;
+}
+
+async function readAuth(): Promise<CodexAuth | undefined> {
+  try {
+    const parsed = JSON.parse(await readFile(authPath(), "utf8")) as {
+      auth_mode?: string;
+      tokens?: { access_token?: string; account_id?: string };
+    };
+    const token = parsed.tokens?.access_token;
+    if (!token) return undefined;
+    return {
+      accessToken: token,
+      ...(parsed.tokens?.account_id
+        ? { accountId: parsed.tokens.account_id }
+        : {}),
+    };
+  } catch {
+    return undefined;
+  }
+}
+
+interface RawWindow {
+  used_percent?: number;
+  limit_window_seconds?: number;
+  reset_at?: number;
+}
+
+/**
+ * Window label from its length. The plan exposes a weekly window and,
+ * historically, a shorter one; naming them by duration keeps the label
+ * right whichever windows the account actually has.
+ */
+function windowLabel(seconds: number | undefined): string {
+  if (!seconds || !Number.isFinite(seconds)) return "limit";
+  const hours = Math.round(seconds / 3600);
+  if (hours % 24 === 0 && hours >= 24) return `${hours / 24}d`;
+  return `${hours}h`;
+}
+
+function toWindow(raw: RawWindow | null | undefined): PlanWindow | undefined {
+  if (!raw || typeof raw.used_percent !== "number") return undefined;
+  return {
+    label: windowLabel(raw.limit_window_seconds),
+    percent: Math.max(0, Math.min(100, Math.round(raw.used_percent))),
+    // `reset_at` is unix seconds; the shared shape speaks ISO.
+    ...(typeof raw.reset_at === "number" && raw.reset_at > 0
+      ? { resetsAt: new Date(raw.reset_at * 1000).toISOString() }
+      : {}),
+  };
+}
+
+export function parseCodexUsage(body: unknown): PlanUsage | undefined {
+  const data = body as {
+    plan_type?: string;
+    rate_limit?: {
+      primary_window?: RawWindow | null;
+      secondary_window?: RawWindow | null;
+    };
+  } | null;
+  const limit = data?.rate_limit;
+  if (!limit) return undefined;
+
+  const windows = [
+    toWindow(limit.primary_window),
+    toWindow(limit.secondary_window),
+  ].filter((w): w is PlanWindow => Boolean(w));
+  if (windows.length === 0) return undefined;
+
+  return {
+    ...(data?.plan_type ? { plan: data.plan_type } : {}),
+    windows,
+    fetchedAt: Date.now(),
+  };
+}
+
+async function load(): Promise<PlanUsage | undefined> {
+  const auth = await readAuth();
+  if (!auth) return undefined;
+
+  try {
+    const res = await fetch(USAGE_ENDPOINT, {
+      headers: {
+        Authorization: `Bearer ${auth.accessToken}`,
+        ...(auth.accountId ? { "chatgpt-account-id": auth.accountId } : {}),
+        Accept: "application/json",
+      },
+      signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+    });
+    if (!res.ok) {
+      logWarn("agent", `codex usage: endpoint returned ${res.status}`);
+      return undefined;
+    }
+    return parseCodexUsage(await res.json());
+  } catch (err) {
+    logWarn(
+      "agent",
+      `codex usage: ${err instanceof Error ? err.message : String(err)}`,
+    );
+    return undefined;
+  }
+}
+
+/**
+ * Plan windows for `/usage`, cached for a minute. A failed refresh keeps
+ * serving the last known values — `fetchedAt` lets the caller age them.
+ */
+export async function getPlanUsage(): Promise<PlanUsage | undefined> {
+  if (cache && Date.now() - cache.fetchedAt < CACHE_TTL_MS) return cache.value;
+
+  inFlight ??= load().finally(() => {
+    inFlight = undefined;
+  });
+  const loaded = await inFlight;
+  if (loaded) cache = { value: loaded, fetchedAt: loaded.fetchedAt };
+  return loaded ?? cache?.value;
+}
+
+export function resetCodexPlanUsageForTest(): void {
+  cache = undefined;
+  inFlight = undefined;
+}

package/src/bootstrap.ts

@@ -26,6 +26,7 @@ import { bus } from "./core/bus/index.js";
 import { appendToJournal } from "./storage/journal.js";
 import { initPulse, resetPulseTimer } from "./core/background/pulse.js";
 import { initCron } from "./core/background/cron.js";
+import { initPlanAlerts } from "./core/background/plan-alerts.js";
 import {
   initTriggers,
   resumeAfterRestart as resumeTriggersAfterRestart,
@@ -420,6 +421,19 @@ export async function initBackendAndDispatcher(
     log("triggers", `resumeAfterRestart failed: ${err}`),
   );
 
+  initPlanAlerts({
+    sendMessage: async (chatId: number, text: string, stringId?: string) =>
+      resolveFrontendByNumericId(chatId, stringId, frontends).sendMessage(
+        chatId,
+        text,
+      ),
+    enabled: config.planAlerts,
+    threshold: config.planAlertThreshold,
+    chatId:
+      config.planAlertChatId ??
+      (config.adminUserId ? String(config.adminUserId) : undefined),
+  });
+
   // Soul — initialize the identity kernel singleton from config so the prompt
   // injection / dream hooks see the right enabled state. Off by default; a
   // failure here must never block startup.

package/src/cli/doctor.ts

@@ -25,9 +25,19 @@ export async function runDoctor(): Promise<void> {
     config: hasConfigFile ? loadConfig() : undefined,
     hasConfigFile,
   });
-  for (const check of report.checks) {
+  const print = (check: (typeof report.checks)[number]): void => {
     const detail = check.detail ? ` ${pc.dim(`(${check.detail})`)}` : "";
     console.log(`  ${DOCTOR_ICONS[check.status]} ${check.label}${detail}`);
+  };
+  for (const check of report.checks.filter((c) => !c.inactive)) print(check);
+
+  // Configured-but-idle backends describe what a switch would run into,
+  // not the state of the running deployment.
+  const idle = report.checks.filter((c) => c.inactive);
+  if (idle.length > 0) {
+    console.log(`\n  ${pc.bold("Other backends")}\n`);
+    for (const check of idle) print(check);
+    console.log();
   }
   // Native plane, one line per embedded module with provenance.
   for (const mod of report.native) {

package/src/core/background/plan-alerts.ts

@@ -0,0 +1,115 @@
+/**
+ * Plan rate-limit warnings.
+ *
+ * Off unless `planAlerts` is enabled. Polls the subscription's windows on a
+ * timer and messages the admin chat the first time one crosses the
+ * threshold, so a long background run doesn't walk into the ceiling
+ * unannounced.
+ *
+ * One message per window per reset cycle: the reset timestamp identifies the
+ * cycle, and a window that drops back under the threshold re-arms (which is
+ * also what covers windows the plan reports no reset for).
+ */
+
+import { getPooledBackend } from "../engine/backend-controller/index.js";
+import { log, logWarn } from "../../util/log.js";
+import { formatSmartTimestamp } from "../../util/time.js";
+
+const CHECK_INTERVAL_MS = 5 * 60_000;
+
+export interface PlanAlertDeps {
+  sendMessage: (
+    chatId: number,
+    text: string,
+    stringId?: string,
+  ) => Promise<void>;
+  enabled: boolean;
+  threshold: number;
+  /** Chat the warnings go to. Callers resolve the admin default. */
+  chatId: string | undefined;
+}
+
+let deps: PlanAlertDeps | undefined;
+let timer: ReturnType<typeof setInterval> | null = null;
+
+/** Window label → the reset cycle it was last warned about. */
+const warned = new Map<string, string>();
+
+export function initPlanAlerts(d: PlanAlertDeps): void {
+  deps = d;
+  stopPlanAlerts();
+  warned.clear();
+  if (!d.enabled) return;
+  if (!d.chatId) {
+    logWarn(
+      "bot",
+      "planAlerts is on but no chat to warn — set planAlertChatId or adminUserId",
+    );
+    return;
+  }
+  timer = setInterval(() => {
+    void checkPlanAlerts();
+  }, CHECK_INTERVAL_MS);
+  timer.unref?.();
+  log("bot", `Plan alerts: on (threshold ${d.threshold}%)`);
+}
+
+export function stopPlanAlerts(): void {
+  if (timer) {
+    clearInterval(timer);
+    timer = null;
+  }
+}
+
+function warningText(
+  label: string,
+  percent: number,
+  resetsAt: string | undefined,
+): string {
+  const ts = resetsAt ? Date.parse(resetsAt) : NaN;
+  const reset = Number.isFinite(ts)
+    ? `, resets ${formatSmartTimestamp(Math.round(ts / 60_000) * 60_000)}`
+    : "";
+  return `⚠️ Plan limit — ${label} at ${percent}% used${reset}.`;
+}
+
+/** One pass. Exported so the timer isn't the only way to drive it. */
+export async function checkPlanAlerts(): Promise<void> {
+  const d = deps;
+  if (!d?.enabled || !d.chatId) return;
+
+  const usage = await getPooledBackend("claude")
+    ?.usage?.getPlanUsage?.()
+    .catch(() => undefined);
+  if (!usage) return;
+
+  for (const window of usage.windows) {
+    // An unwarned window that is back under the threshold re-arms.
+    if (window.percent < d.threshold) {
+      warned.delete(window.label);
+      continue;
+    }
+    const cycle = window.resetsAt ?? "";
+    if (warned.get(window.label) === cycle) continue;
+    warned.set(window.label, cycle);
+
+    const text = warningText(window.label, window.percent, window.resetsAt);
+    try {
+      await d.sendMessage(Number(d.chatId), text, d.chatId);
+      log("bot", `Plan alert sent: ${window.label} at ${window.percent}%`);
+    } catch (err) {
+      // Keep it marked as warned — a frontend that can't deliver now won't
+      // deliver on the next tick either, and retrying would spam on recovery.
+      logWarn(
+        "bot",
+        `Plan alert delivery failed: ${err instanceof Error ? err.message : err}`,
+      );
+    }
+  }
+}
+
+export function resetPlanAlertsForTest(): void {
+  stopPlanAlerts();
+  deps = undefined;
+  warned.clear();
+}

package/src/core/doctor.ts

@@ -29,6 +29,12 @@ export interface DoctorCheck {
    * starts but a backend won't work.
    */
   issue?: boolean;
+  /**
+   * A backend that is configured but not serving chats. Renderers group
+   * these away from the environment so a handful of idle providers can't
+   * bury the checks that describe the running deployment.
+   */
+  inactive?: boolean;
 }
 
 /** One embedded native module: provenance plus a live self-test result. */
@@ -59,6 +65,8 @@ export interface DoctorReport {
 export interface DoctorConfigSlice {
   frontend: string | string[];
   backend?: string;
+  /** Backends config exposes. Empty / absent means every registered one. */
+  enabledBackends?: string[];
   model?: string;
   heartbeatModel?: string;
   heartbeatBackend?: string;
@@ -284,12 +292,55 @@ async function checkClaudeConfiguredModels(
   return checks;
 }
 
-/** Binary / auth checks for the active backend only. */
+/** Every backend id doctor knows how to inspect. */
+const KNOWN_BACKENDS = [
+  "claude",
+  "codex",
+  "kilo",
+  "opencode",
+  "openai-agents",
+] as const;
+
+/**
+ * Binary / auth checks across every backend the config exposes.
+ *
+ * Only the active one counts toward the issue total; the rest are reported
+ * so a switch doesn't have to be the thing that discovers a backend can't
+ * run. That distinction matters now that a chat can be rebound at runtime —
+ * a report of all-green while two backends are one click from failing is
+ * worse than no report.
+ */
 async function checkBackend(
   config: DoctorConfigSlice | undefined,
+): Promise<DoctorCheck[]> {
+  const active = config?.backend ?? "claude";
+  const exposed = config?.enabledBackends?.length
+    ? config.enabledBackends
+    : [...KNOWN_BACKENDS];
+
+  const checks = await checkOneBackend(active, config, true);
+  for (const id of exposed) {
+    if (id === active || !KNOWN_BACKENDS.includes(id as never)) continue;
+    // An idle backend's missing binary is a heads-up, not a fault of this
+    // deployment: downgrade it and keep it out of the issue count.
+    for (const check of await checkOneBackend(id, config, false)) {
+      checks.push({
+        ...check,
+        status: check.status === "fail" ? "warn" : check.status,
+        issue: false,
+        inactive: true,
+      });
+    }
+  }
+  return checks;
+}
+
+async function checkOneBackend(
+  backend: string,
+  config: DoctorConfigSlice | undefined,
+  isActive: boolean,
 ): Promise<DoctorCheck[]> {
   const checks: DoctorCheck[] = [];
-  const backend = config?.backend ?? "claude";
 
   if (backend === "claude") {
     if (config?.claudeBinary) {
@@ -313,7 +364,9 @@ async function checkBackend(
           : { label: "Claude Code not found", status: "fail" },
       );
     }
-    checks.push(...(await checkClaudeConfiguredModels(config)));
+    // Model resolution spawns a probe — worth it for the backend actually
+    // serving chats, wasteful for one nobody is using.
+    if (isActive) checks.push(...(await checkClaudeConfiguredModels(config)));
   } else if (backend === "codex") {
     if (!binaryOnPath("codex")) {
       checks.push({
@@ -349,11 +402,21 @@ async function checkBackend(
       });
     }
   } else if (backend === "kilo" || backend === "opencode") {
-    // Bundled as npm deps — no external binary to check.
-    checks.push({
-      label: `${backend === "kilo" ? "Kilo" : "OpenCode"} SDK bundled`,
-      status: "ok",
-    });
+    // The SDK ships as an npm dep but only talks to a server it spawns from
+    // the CLI of the same name (`cross-spawn` → PATH lookup). A present
+    // package with an absent binary fails at the first turn with a bare
+    // ENOENT, so check what actually gets executed.
+    const label = backend === "kilo" ? "Kilo" : "OpenCode";
+    checks.push(
+      binaryOnPath(backend)
+        ? { label: `${label} CLI installed`, status: "ok" }
+        : {
+            label: `${label} CLI not found`,
+            status: "fail",
+            detail: `the ${label} SDK spawns \`${backend}\` — install it or this backend cannot start`,
+            issue: true,
+          },
+    );
   } else if (backend === "openai-agents") {
     checks.push({ label: "OpenAI Agents SDK bundled", status: "ok" });
     const hasEnvKey = Boolean(process.env.OPENAI_API_KEY);

package/src/frontend/discord/callbacks/components.ts

@@ -68,6 +68,7 @@ import {
   DISCORD_MAX_TEXT,
 } from "../formatting.js";
 import { chatIdFromInteraction, type ComponentInteraction } from "./shared.js";
+import { metricsViewRow, renderMetricsView } from "../commands/admin.js";
 
 export async function handleComponentInteraction(
   interaction: ComponentInteraction,
@@ -352,6 +353,21 @@ export async function handleComponentInteraction(
     return;
   }
 
+  // ── /metrics today ↔ all-time toggle ────────────────────────────────────
+  if (customId === "metrics:today" || customId === "metrics:all") {
+    const view = customId === "metrics:all" ? "all" : "today";
+    const messages = renderMetricsView(view);
+    try {
+      await interaction.update({
+        content: messages[0]!,
+        components: [metricsViewRow(view).toJSON()],
+      });
+    } catch {
+      /* ignore */
+    }
+    return;
+  }
+
   // ── AI-generated buttons (prefixed `ai:`) → forward to agent ──────────
   if (customId.startsWith("ai:")) {
     await forwardToAgent(interaction, gateway);

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

@@ -3,16 +3,37 @@
  * All gate on `isAdmin`.
  */
 
-import { type ChatInputCommandInteraction, MessageFlags } from "discord.js";
+import {
+  type ChatInputCommandInteraction,
+  ActionRowBuilder,
+  ButtonBuilder,
+  ButtonStyle,
+  MessageFlags,
+} from "discord.js";
 import type { TalonConfig } from "../../../util/config.js";
 import type { Gateway } from "../../../core/engine/gateway.js";
 import { respawnSelf } from "../../../util/respawn.js";
 import { forceDream } from "../../../core/background/dream.js";
-import { formatDuration, renderMetricsMessages } from "../helpers.js";
+import {
+  formatDuration,
+  renderMetricsMessages,
+  renderDoctorMessages,
+} from "../helpers.js";
+import { collectDoctorReport } from "../../../core/doctor.js";
+import { getSoul } from "../../../core/soul/service.js";
 import { getMetrics, getTodayMetrics } from "../../../storage/metrics.js";
 import { handleAdminSubcommand } from "../admin.js";
 import { isAdmin } from "../handlers/index.js";
-import { suppressMentions, DISCORD_MAX_TEXT } from "../formatting.js";
+import {
+  suppressMentions,
+  DISCORD_MAX_TEXT,
+  safeSlice,
+  escapeForCodeBlock,
+} from "../formatting.js";
+import {
+  getRepoRoot,
+  runSelfUpdate,
+} from "../../../core/update/self-update.js";
 import { reply } from "./shared.js";
 
 export async function handleRestart(
@@ -34,18 +55,112 @@ export async function handleMetrics(
     return;
   }
   // Ephemeral — admin counters (token usage, latencies, errors) shouldn't leak
-  // into a public channel where non-admins can read them.
-  const messages = [
-    ...renderMetricsMessages(getMetrics()),
-    ...renderMetricsMessages(
-      getTodayMetrics(),
-      undefined,
-      "📊 Metrics — today (UTC)",
-    ),
-  ];
-  for (const m of messages) {
-    await reply(i, m, true);
+  // into a public channel where non-admins can read them. Both views are one
+  // button apart rather than two bursts of messages.
+  await i.deferReply({ flags: MessageFlags.Ephemeral });
+  const messages = renderMetricsMessages(
+    getTodayMetrics(),
+    undefined,
+    "📊 Metrics — today (UTC)",
+  );
+  await i.editReply({
+    content: messages[0]!,
+    components: [metricsViewRow("today").toJSON()],
+  });
+  for (const extra of messages.slice(1)) {
+    await i.followUp({ content: extra, flags: MessageFlags.Ephemeral });
+  }
+}
+
+/** Today / all-time toggle under the metrics panel. */
+export function metricsViewRow(
+  view: MetricsView,
+): ActionRowBuilder<ButtonBuilder> {
+  return new ActionRowBuilder<ButtonBuilder>().addComponents(
+    new ButtonBuilder()
+      .setCustomId("metrics:today")
+      .setLabel("Today")
+      .setStyle(view === "today" ? ButtonStyle.Primary : ButtonStyle.Secondary)
+      .setDisabled(view === "today"),
+    new ButtonBuilder()
+      .setCustomId("metrics:all")
+      .setLabel("All time")
+      .setStyle(view === "all" ? ButtonStyle.Primary : ButtonStyle.Secondary)
+      .setDisabled(view === "all"),
+  );
+}
+
+export type MetricsView = "today" | "all";
+
+/** Panel body for one view — shared by the command and the toggle. */
+export function renderMetricsView(view: MetricsView): string[] {
+  return view === "today"
+    ? renderMetricsMessages(
+        getTodayMetrics(),
+        undefined,
+        "📊 Metrics — today (UTC)",
+      )
+    : renderMetricsMessages(getMetrics(), undefined, "📊 Metrics — all time");
+}
+
+export async function handleDoctor(
+  i: ChatInputCommandInteraction,
+  config: TalonConfig,
+): Promise<void> {
+  if (!isAdmin(i.user.id)) {
+    await reply(i, "Not authorized.", true);
+    return;
+  }
+  await i.deferReply({ flags: MessageFlags.Ephemeral });
+  await i.editReply("🩺 Running checks...");
+  try {
+    // Same checks as `talon doctor` — config exists by definition when the
+    // bot is processing this command.
+    const report = await collectDoctorReport({ config, hasConfigFile: true });
+    const messages = renderDoctorMessages(report);
+    await i.editReply(messages[0]!);
+    for (const extra of messages.slice(1))
+      await i.followUp({
+        content: extra,
+        flags: MessageFlags.Ephemeral,
+      });
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    await i.editReply(`🩺 Doctor failed: ${msg}`);
+  }
+}
+
+/**
+ * /soul — read-only introspection of the compiled identity. `action:dream`
+ * runs the organic maintenance pass and is admin-only. Inert while the soul
+ * is disabled, so it is safe to ship dormant.
+ */
+export async function handleSoul(
+  i: ChatInputCommandInteraction,
+): Promise<void> {
+  const soul = getSoul();
+  if (!soul.enabled) {
+    await reply(
+      i,
+      "Soul is disabled (set TALON_SOUL_ENABLED to enable).",
+      true,
+    );
+    return;
+  }
+  if (i.options.getString("action") === "dream") {
+    if (!isAdmin(i.user.id)) {
+      await reply(i, "Not authorized.", true);
+      return;
+    }
+    await i.deferReply({ flags: MessageFlags.Ephemeral });
+    await i.editReply("🧠 Soul dreaming...");
+    soul
+      .dream()
+      .then(() => i.editReply("🧠 Soul dream complete."))
+      .catch(() => undefined);
+    return;
   }
+  await reply(i, suppressMentions(soul.introspect()), true);
 }
 
 export async function handleDream(
@@ -71,6 +186,65 @@ export async function handleDream(
     });
 }
 
+/**
+ * /update — pull, reinstall, run setup, restart. Only reachable on developer
+ * builds running from a git checkout; the command is not registered at all
+ * otherwise (see buildCommandDefinitions).
+ */
+export async function handleUpdate(
+  i: ChatInputCommandInteraction,
+  config: TalonConfig,
+): Promise<void> {
+  if (!isAdmin(i.user.id)) {
+    await reply(i, "Not authorized.", true);
+    return;
+  }
+  const repoRoot = config.devBuild ? getRepoRoot() : null;
+  if (!repoRoot) {
+    await reply(i, "Update is only available on developer builds.", true);
+    return;
+  }
+  const remote = config.update?.remote ?? "origin";
+  const branch = config.update?.branch ?? "main";
+  await i.deferReply({ flags: MessageFlags.Ephemeral });
+  await i.editReply(`⏳ Updating from \`${remote}/${branch}\`…`);
+  const edit = (text: string) => i.editReply(safeSlice(text, DISCORD_MAX_TEXT));
+
+  // Fire-and-forget so the gateway keeps processing other interactions.
+  runSelfUpdate({
+    remote,
+    branch,
+    setup: config.update?.setup,
+    repoRoot,
+  })
+    .then(async (res) => {
+      if (!res.ok) {
+        const tail = res.steps[res.steps.length - 1]?.output ?? "";
+        await edit(
+          `⚠️ Update failed: ${res.error ?? "unknown error"}` +
+            (tail
+              ? `\n\`\`\`\n${escapeForCodeBlock(tail.slice(-1200))}\n\`\`\``
+              : ""),
+        );
+        return;
+      }
+      if (!res.changed) {
+        await edit(
+          `✅ Already up to date at \`${res.before ?? "?"}\` — no restart needed.`,
+        );
+        return;
+      }
+      await edit(
+        `✅ Updated \`${res.before ?? "?"}\` → \`${res.after ?? "?"}\`. ♻️ Restarting…`,
+      );
+      respawnSelf("discord /update");
+    })
+    .catch(async (err: unknown) => {
+      const msg = err instanceof Error ? err.message : String(err);
+      await edit(`⚠️ Update crashed: ${msg}`);
+    });
+}
+
 export async function handleAdmin(
   i: ChatInputCommandInteraction,
   config: TalonConfig,

package/src/frontend/discord/commands/definitions.ts

@@ -15,8 +15,9 @@
 import { type Client, REST, Routes, SlashCommandBuilder } from "discord.js";
 import type { TalonConfig } from "../../../util/config.js";
 import { log, logError, logWarn } from "../../../util/log.js";
+import { getRepoRoot } from "../../../core/update/self-update.js";
 
-export function buildCommandDefinitions(): unknown[] {
+export function buildCommandDefinitions(devBuild = false): unknown[] {
   return [
     new SlashCommandBuilder()
       .setName("start")
@@ -97,6 +98,40 @@ export function buildCommandDefinitions(): unknown[] {
       .setName("plugins")
       .setDescription("List loaded plugins")
       .toJSON(),
+    new SlashCommandBuilder()
+      .setName("usage")
+      .setDescription("Plan limits across every backend")
+      .toJSON(),
+    new SlashCommandBuilder()
+      .setName("doctor")
+      .setDescription("Environment and native-module health (admin)")
+      .toJSON(),
+    new SlashCommandBuilder()
+      .setName("mesh")
+      .setDescription("Ping and list mesh devices")
+      .toJSON(),
+    new SlashCommandBuilder()
+      .setName("soul")
+      .setDescription("Inspect the compiled identity")
+      .addStringOption((o) =>
+        o
+          .setName("action")
+          .setDescription("Leave empty to introspect")
+          .setRequired(false)
+          .addChoices({ name: "dream", value: "dream" }),
+      )
+      .toJSON(),
+    // /update only exists on developer builds running from a git checkout —
+    // a packaged binary has no source tree to pull into, so the command is
+    // never registered there (same gate as the Telegram handler).
+    ...(devBuild && getRepoRoot()
+      ? [
+          new SlashCommandBuilder()
+            .setName("update")
+            .setDescription("Pull latest, reinstall, restart (admin)")
+            .toJSON(),
+        ]
+      : []),
     new SlashCommandBuilder()
       .setName("admin")
       .setDescription("Admin operations (admin only)")
@@ -128,7 +163,7 @@ export async function registerCommandsForGuilds(
 ): Promise<void> {
   const dc = config.discord!;
   const rest = new REST({ version: "10" }).setToken(dc.botToken);
-  const definitions = buildCommandDefinitions();
+  const definitions = buildCommandDefinitions(config.devBuild);
 
   // Step 1: clear or set global commands depending on DM setting.
   try {

package/src/frontend/discord/commands/info.ts

@@ -7,8 +7,16 @@ import {
   type Client,
   MessageFlags,
 } from "discord.js";
-import { formatDuration } from "../helpers.js";
+import {
+  formatDuration,
+  renderMeshReport,
+  renderUsageMessage,
+} from "../helpers.js";
+import type { TalonConfig } from "../../../util/config.js";
+import { collectPlanUsage } from "../../shared/plan-usage-report.js";
 import { getLoadedPlugins } from "../../../core/plugin/index.js";
+import { getMeshService } from "../../../core/mesh/index.js";
+import type { MeshPingResult } from "../../../core/mesh/service.js";
 import { reply } from "./shared.js";
 
 export async function handleStart(
@@ -67,6 +75,35 @@ export async function handleHelp(
   );
 }
 
+/**
+ * /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.
+ */
+export async function handleUsage(
+  i: ChatInputCommandInteraction,
+  config: TalonConfig,
+): Promise<void> {
+  await i.deferReply({ flags: MessageFlags.Ephemeral });
+  const entries = await collectPlanUsage(config);
+  await i.editReply(renderUsageMessage(entries));
+}
+
+export async function handleMesh(
+  i: ChatInputCommandInteraction,
+): Promise<void> {
+  await i.deferReply({ flags: MessageFlags.Ephemeral });
+  await i.editReply("Pinging mesh devices…");
+  let results: MeshPingResult[];
+  try {
+    results = await getMeshService().pingAll();
+  } catch {
+    await i.editReply("Could not reach the mesh service.");
+    return;
+  }
+  await i.editReply(renderMeshReport(results));
+}
+
 export async function handlePing(
   i: ChatInputCommandInteraction,
 ): Promise<void> {

package/src/frontend/discord/commands/router.ts

@@ -22,7 +22,14 @@ import {
   handleModalSubmit,
 } from "../callbacks/index.js";
 import { chatIdFromInteraction, reply, client } from "./shared.js";
-import { handleStart, handleHelp, handlePing, handlePlugins } from "./info.js";
+import {
+  handleStart,
+  handleHelp,
+  handlePing,
+  handlePlugins,
+  handleMesh,
+  handleUsage,
+} from "./info.js";
 import { handleReset, handleStatus } from "./session.js";
 import {
   handleModel,
@@ -35,6 +42,9 @@ import {
   handleMetrics,
   handleDream,
   handleAdmin,
+  handleDoctor,
+  handleSoul,
+  handleUpdate,
 } from "./admin.js";
 
 export function registerInteractionRouter(
@@ -141,6 +151,16 @@ async function routeSlashCommand(
       return handleDream(interaction);
     case "plugins":
       return handlePlugins(interaction);
+    case "usage":
+      return handleUsage(interaction, config);
+    case "doctor":
+      return handleDoctor(interaction, config);
+    case "mesh":
+      return handleMesh(interaction);
+    case "soul":
+      return handleSoul(interaction);
+    case "update":
+      return handleUpdate(interaction, config);
     case "admin":
       return handleAdmin(interaction, config, gateway);
     default:

package/src/frontend/discord/helpers.ts

@@ -8,10 +8,18 @@
  */
 
 import { REASONING_LEVEL_DESCRIPTIONS } from "../../core/models/reasoning-levels.js";
-import { DISCORD_MAX_TEXT, DISCORD_SAFE_RESERVE } from "./formatting.js";
+import {
+  DISCORD_MAX_TEXT,
+  DISCORD_SAFE_RESERVE,
+  splitMessage,
+} from "./formatting.js";
+import type { DoctorReport } from "../../core/doctor.js";
+import type { MeshPingResult } from "../../core/mesh/service.js";
+import type { BackendUsageEntry } from "../shared/plan-usage-report.js";
 import {
   DEFAULT_PULSE_INTERVAL_MS,
   formatDuration,
+  formatBytes,
   formatModelLabel,
 } from "../shared/format.js";
 
@@ -157,6 +165,145 @@ export function renderMetricsMessages(
   return chunks;
 }
 
+const DOCTOR_ICONS: Record<string, string> = {
+  ok: "✅",
+  warn: "⚠️",
+  fail: "❌",
+  info: "▫️",
+};
+
+/**
+ * Render a DoctorReport as Discord markdown, split to fit the message cap.
+ * Same data as `talon doctor` and Telegram's /doctor.
+ */
+export function renderDoctorMessages(
+  report: DoctorReport,
+  maxLen = DEFAULT_METRICS_MESSAGE_MAX,
+): string[] {
+  const lines = ["**🩺 Talon Doctor**", "", "**Environment**"];
+
+  const render = (check: DoctorReport["checks"][number]): string =>
+    `${DOCTOR_ICONS[check.status]} ${check.label}${check.detail ? ` (${check.detail})` : ""}`;
+
+  for (const check of report.checks.filter((c) => !c.inactive)) {
+    lines.push(render(check));
+  }
+
+  // Configured-but-idle backends get their own block: they describe what a
+  // switch would run into, not the state of the running deployment.
+  const idle = report.checks.filter((c) => c.inactive);
+  if (idle.length > 0) {
+    lines.push("", "**Other backends**", ...idle.map(render));
+  }
+
+  lines.push("", "**Native modules**");
+  for (const mod of report.native) {
+    const size =
+      mod.sizeBytes !== undefined ? ` · ${formatBytes(mod.sizeBytes)}` : "";
+    const note = mod.note ? ` (${mod.note})` : "";
+    lines.push(
+      `${mod.ok ? DOCTOR_ICONS.ok : DOCTOR_ICONS.fail} \`${mod.name}\` — ${mod.language} → ${mod.target}${size}${note}`,
+    );
+  }
+
+  lines.push(
+    "",
+    "**Process**",
+    `Uptime ${formatDuration(process.uptime() * 1000)} · PID ${process.pid} · Node ${process.versions.node}`,
+    "",
+    report.issues === 0
+      ? `${DOCTOR_ICONS.ok} All checks passed.`
+      : `${DOCTOR_ICONS.warn} ${report.issues} issue(s) found.`,
+  );
+
+  return splitMessage(lines.join("\n"), maxLen);
+}
+
+function meshDeviceLine(r: MeshPingResult, now: number): string {
+  const d = r.device;
+  const bits: string[] = [d.platform];
+  if (r.reachable && typeof r.latencyMs === "number") {
+    bits.push(`${r.latencyMs} ms`);
+  } else if (d.online && r.error) {
+    bits.push(r.error);
+  } else if (!d.online) {
+    bits.push(`last seen ${formatDuration(now - d.lastSeen)} ago`);
+  }
+  if (typeof d.battery === "number") {
+    bits.push(`${d.battery}%${d.charging ? " charging" : ""}`);
+  }
+  return `  **${d.name}** — ${bits.join(" · ")}`;
+}
+
+/**
+ * Render the /mesh fleet report as Discord markdown. Devices group under a
+ * state heading; empty groups are omitted.
+ */
+export function renderMeshReport(
+  results: MeshPingResult[],
+  now = Date.now(),
+): string {
+  if (results.length === 0) {
+    return "**Mesh**\n\n_No devices have registered yet._";
+  }
+
+  const responding = results
+    .filter((r) => r.reachable)
+    .sort((a, b) => (a.latencyMs ?? Infinity) - (b.latencyMs ?? Infinity));
+  const unreachable = results
+    .filter((r) => !r.reachable && r.device.online)
+    .sort((a, b) => a.device.name.localeCompare(b.device.name));
+  const offline = results
+    .filter((r) => !r.reachable && !r.device.online)
+    .sort((a, b) => b.device.lastSeen - a.device.lastSeen);
+
+  const summary = [
+    `${results.length} device${results.length === 1 ? "" : "s"}`,
+    `${responding.length} responding`,
+    ...(unreachable.length > 0 ? [`${unreachable.length} unreachable`] : []),
+    ...(offline.length > 0 ? [`${offline.length} offline`] : []),
+  ].join(" · ");
+
+  const lines = ["**Mesh**", summary];
+  const section = (title: string, entries: MeshPingResult[]): void => {
+    if (entries.length === 0) return;
+    lines.push(
+      "",
+      `**${title}**`,
+      ...entries.map((r) => meshDeviceLine(r, now)),
+    );
+  };
+  section("Responding", responding);
+  section("Unreachable", unreachable);
+  section("Offline", offline);
+
+  return lines.join("\n");
+}
+
+/** Render the `/usage` report — one block per exposed backend. */
+export function renderUsageMessage(entries: BackendUsageEntry[]): string {
+  const lines = ["**📊 Plan usage**"];
+
+  for (const entry of entries) {
+    const name = entry.label || entry.id;
+    if (!entry.plan) {
+      lines.push("", `**${name}** — _${entry.note ?? ""}_`);
+      continue;
+    }
+    const age = entry.plan.ageLabel ? ` *(${entry.plan.ageLabel})*` : "";
+    const plan = entry.plan.plan ? ` · ${entry.plan.plan}` : "";
+    lines.push("", `**${name}**${plan}${age}`);
+    for (const w of entry.plan.windows) {
+      const reset = w.resetLabel ? ` reset ${w.resetLabel}` : "";
+      lines.push(
+        `  \`${w.label.padEnd(6)}${w.bar} ${String(w.percent).padStart(3)}%\`${reset}`,
+      );
+    }
+  }
+
+  return lines.join("\n");
+}
+
 /** Settings panel: build the markdown body. */
 export function renderSettingsText(
   model: string,

package/src/frontend/discord/index.ts

@@ -73,8 +73,17 @@ export function createDiscordFrontend(
       GatewayIntentBits.MessageContent,
       GatewayIntentBits.DirectMessages,
       GatewayIntentBits.GuildMessageReactions,
+      GatewayIntentBits.DirectMessageReactions,
+    ],
+    // Partials.Reaction is what makes reactions on messages that predate the
+    // current cache arrive at all — without it the soul's reaction tap only
+    // ever sees freshly-cached messages.
+    partials: [
+      Partials.Channel,
+      Partials.Message,
+      Partials.User,
+      Partials.Reaction,
     ],
-    partials: [Partials.Channel, Partials.Message, Partials.User],
     allowedMentions: { parse: [] }, // never ping anyone unless we explicitly opt in
   });
 

package/src/frontend/discord/middleware.ts

@@ -21,6 +21,7 @@ import { pushMessage } from "../../storage/history.js";
 import { registerChat } from "../../core/background/pulse.js";
 import { deriveNumericChatId } from "../../util/chat-id.js";
 import { handleMessage, getSenderName } from "./handlers/index.js";
+import { recordReactionToBot } from "../../core/soul/taps.js";
 
 export function registerMiddleware(client: Client, config: TalonConfig): void {
   client.on("messageCreate", (msg: Message) => {
@@ -85,4 +86,27 @@ export function registerMiddleware(client: Client, config: TalonConfig): void {
       /* logged inside */
     });
   });
+
+  // ── Reaction tap — feed reactions on Talon's own messages to the soul ────
+  // The gateway records outgoing message ids as `Number(snowflake)`, so the
+  // lookup here must use the same conversion to match. Inert unless the soul
+  // is enabled.
+  client.on("messageReactionAdd", async (reaction, user) => {
+    if (user.id === client.user?.id) return;
+    try {
+      // A partial arrives when the message predates the cache; the chat id
+      // can't be built without the channel/guild it belongs to.
+      if (reaction.partial) await reaction.fetch();
+    } catch {
+      return;
+    }
+    const msg = reaction.message;
+    const emoji = reaction.emoji.name;
+    if (!emoji) return;
+    const chatId =
+      msg.channel.type === ChannelType.DM
+        ? `discord_dm_${msg.author?.id ?? user.id}`
+        : `discord_guild_${msg.guildId}_${msg.channelId}`;
+    recordReactionToBot(chatId, Number(msg.id), [emoji]);
+  });
 }

package/src/frontend/shared/plan-usage-report.ts

@@ -0,0 +1,72 @@
+/**
+ * `/usage` data gathering — plan limits across every backend the config
+ * exposes, not just the one serving this chat.
+ *
+ * Most backends have no plan to report: a gateway (Kilo, OpenCode) bills
+ * through whichever provider it fronts, and an API-key install pays per
+ * token with no window to be near the end of. Those are listed with a
+ * reason rather than omitted, so the answer to "am I close to a limit?" is
+ * never silence.
+ */
+
+import type { TalonConfig } from "../../util/config.js";
+import type { PlanUsage } from "../../core/agent-runtime/capabilities.js";
+import {
+  listAvailableBackends,
+  getPooledBackend,
+} from "../../core/engine/backend-controller/index.js";
+import { buildPlanDisplay, type PlanDisplay } from "./status-context.js";
+
+export interface BackendUsageEntry {
+  id: string;
+  label: string;
+  /** Rendered windows, or null when this backend reported nothing. */
+  plan: PlanDisplay | null;
+  /** Why there is nothing to show. Absent when `plan` is set. */
+  note?: string;
+}
+
+/**
+ * One entry per exposed backend, in config order.
+ *
+ * Only backends already running are queried — booting one to read a
+ * number would spawn a subprocess or a server per idle provider, which is
+ * far more than a status command should cost.
+ */
+export async function collectPlanUsage(
+  config: TalonConfig,
+): Promise<BackendUsageEntry[]> {
+  const entries: BackendUsageEntry[] = [];
+
+  for (const { id, label } of listAvailableBackends(config)) {
+    const backend = getPooledBackend(id);
+    if (!backend) {
+      entries.push({ id, label, plan: null, note: "not running" });
+      continue;
+    }
+    if (!backend.usage?.getPlanUsage) {
+      entries.push({
+        id,
+        label,
+        plan: null,
+        note: "no plan limits on this backend",
+      });
+      continue;
+    }
+
+    let usage: PlanUsage | undefined;
+    try {
+      usage = await backend.usage.getPlanUsage();
+    } catch {
+      usage = undefined;
+    }
+    const plan = buildPlanDisplay(usage);
+    entries.push(
+      plan
+        ? { id, label, plan }
+        : { id, label, plan: null, note: "no usage information available" },
+    );
+  }
+
+  return entries;
+}

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

@@ -21,7 +21,9 @@ import {
   renderDoctorMessage,
   renderMetricsKeyboard,
   renderMetricsPanel,
+  renderUsageMessage,
 } from "../helpers/index.js";
+import { collectPlanUsage } from "../../shared/plan-usage-report.js";
 import { collectDoctorReport } from "../../../core/doctor.js";
 import { handleAdminCommand } from "../admin.js";
 import { getTodayMetrics } from "../../../storage/metrics.js";
@@ -53,6 +55,14 @@ export function registerAdminCommands(
     });
   });
 
+  // /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.
+  bot.command("usage", async (ctx) => {
+    const entries = await collectPlanUsage(config);
+    await ctx.reply(renderUsageMessage(entries), { parse_mode: "HTML" });
+  });
+
   bot.command("doctor", async (ctx) => {
     if (!isAuthorizedAdmin(ctx)) {
       await ctx.reply("Not authorized.");

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

@@ -28,6 +28,7 @@ export const TELEGRAM_COMMANDS: ReadonlyArray<{
   { command: "pulse", description: "Conversation engagement settings" },
   { command: "reset", description: "Clear session and start fresh" },
   { command: "restart", description: "Restart the bot (admin)" },
+  { command: "usage", description: "Plan limits across every backend" },
   { command: "metrics", description: "Aggregate performance metrics" },
   {
     command: "doctor",

package/src/frontend/telegram/helpers/diagnostics.ts

@@ -5,6 +5,7 @@
 import { escapeHtml } from "../formatting.js";
 import type { DoctorReport } from "../../../core/doctor.js";
 import type { MeshPingResult } from "../../../core/mesh/service.js";
+import type { BackendUsageEntry } from "../../shared/plan-usage-report.js";
 import type { SettingsButton } from "./menu.js";
 import { formatDuration, formatBytes } from "./format.js";
 
@@ -208,14 +209,47 @@ const DOCTOR_ICONS: Record<string, string> = {
  * when this renders, the bot is by definition running, so the CLI's
  * "is the bot up" probe becomes an uptime line instead.
  */
+/** Render the `/usage` report — one block per exposed backend. */
+export function renderUsageMessage(entries: BackendUsageEntry[]): string {
+  const lines = ["<b>📊 Plan usage</b>"];
+
+  for (const entry of entries) {
+    const name = escapeHtml(entry.label || entry.id);
+    if (!entry.plan) {
+      lines.push("", `<b>${name}</b> — <i>${escapeHtml(entry.note ?? "")}</i>`);
+      continue;
+    }
+    const age = entry.plan.ageLabel ? ` <i>(${entry.plan.ageLabel})</i>` : "";
+    const plan = entry.plan.plan ? ` · ${escapeHtml(entry.plan.plan)}` : "";
+    lines.push("", `<b>${name}</b>${plan}${age}`);
+    for (const w of entry.plan.windows) {
+      const reset = w.resetLabel ? ` reset ${w.resetLabel}` : "";
+      lines.push(
+        `  <code>${escapeHtml(w.label.padEnd(6))}${w.bar} ${String(w.percent).padStart(3)}%</code>${reset}`,
+      );
+    }
+  }
+
+  return lines.join("\n");
+}
+
 export function renderDoctorMessage(report: DoctorReport): string {
   const lines = ["<b>🩺 Talon Doctor</b>", "", "<b>Environment</b>"];
 
-  for (const check of report.checks) {
+  const render = (check: DoctorReport["checks"][number]): string => {
     const detail = check.detail ? ` (${escapeHtml(check.detail)})` : "";
-    lines.push(
-      `${DOCTOR_ICONS[check.status]} ${escapeHtml(check.label)}${detail}`,
-    );
+    return `${DOCTOR_ICONS[check.status]} ${escapeHtml(check.label)}${detail}`;
+  };
+
+  for (const check of report.checks.filter((c) => !c.inactive)) {
+    lines.push(render(check));
+  }
+
+  // Configured-but-idle backends get their own block: they describe what a
+  // switch would run into, not the state of the running deployment.
+  const idle = report.checks.filter((c) => c.inactive);
+  if (idle.length > 0) {
+    lines.push("", "<b>Other backends</b>", ...idle.map(render));
   }
 
   lines.push("", "<b>Native modules</b>");

package/src/util/config.ts

@@ -340,6 +340,16 @@ const configSchema = z.object({
   allowedUsers: z.array(z.number().int()).optional(), // Whitelist of user IDs allowed to DM the bot
   pulse: z.boolean().default(true),
   pulseIntervalMs: z.number().int().min(60000).default(300000),
+  /**
+   * Warn the admin chat when a subscription rate-limit window crosses
+   * `planAlertThreshold`. Off by default. Needs a backend that reports plan
+   * limits (Claude on a subscription); one message per window per reset
+   * cycle.
+   */
+  planAlerts: z.boolean().default(false),
+  planAlertThreshold: z.number().int().min(1).max(100).default(80),
+  /** Chat that receives plan warnings. Defaults to `adminUserId`. */
+  planAlertChatId: z.string().optional(),
   /** Background memory-consolidation (dream) runs. Mirrors `pulse`/`heartbeat`. */
   dream: z.boolean().default(true),
   /**