talon-agent 5.11.0 → 5.13.0

package/package.json

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

package/src/backend/claude-sdk/factory.ts

@@ -30,6 +30,7 @@ import {
   evictOrphanSubprocesses as claudeEvictOrphanSubprocesses,
 } from "./index.js";
 import { createInProcessAgentHost } from "./host/in-process.js";
+import { claimBankedReset, getBankedResetOffer } from "./usage/banked-reset.js";
 
 import * as modelProvider from "./model-provider.js";
 import { claudeDoctorChecks } from "./doctor.js";
@@ -105,6 +106,10 @@ const claudeSdkFactory: BackendFactory = {
     // but the subscription's rate-limit windows are readable.
     const usage: UsageTelemetry = {
       getPlanUsage: () => host.planUsage(),
+      bankedResets: {
+        getOffer: () => getBankedResetOffer(),
+        claim: (grantId, requestId) => claimBankedReset(grantId, requestId),
+      },
     };
 
     const backend = composeBackend({

package/src/backend/claude-sdk/handler.ts

@@ -38,7 +38,7 @@ import { applyRetryDecisionStream } from "../runtime/turn/handle-retry.js";
 import { getConfig } from "./state.js";
 import { buildSdkOptions, getActiveFrontends } from "./options.js";
 import { waitForMcpServersReady } from "./mcp-ready.js";
-import { invalidatePlanUsage } from "./plan-usage.js";
+import { invalidatePlanUsage } from "./usage/plan-usage.js";
 import { frontendsForChat } from "../runtime/frontends.js";
 import { rollUpTurnCache } from "../runtime/cache/cache-metrics.js";
 import {

package/src/backend/claude-sdk/host/in-process.ts

@@ -39,7 +39,7 @@ import {
 } from "../handler.js";
 import { waitForMcpServersReady } from "../mcp-ready.js";
 import { listModels as claudeListModels } from "../model-provider.js";
-import { getPlanUsage } from "../plan-usage.js";
+import { getPlanUsage } from "../usage/plan-usage.js";
 
 /**
  * Install an MCP server set on the chat's live query. `null` when the

package/src/backend/claude-sdk/usage/banked-reset.ts

@@ -0,0 +1,304 @@
+/**
+ * Spending a banked Claude usage-limit reset (the claude.ai "Reset for free"
+ * grants, program `cedar_ember`).
+ *
+ * The same OAuth usage endpoint `/usage` reads lists the grants; a claim is a
+ * POST to the organization's `reset_rate_limits` route, the one Claude Code's
+ * own `/limit-reset` uses. The request and response shapes mirror the CLI:
+ *
+ *   POST /api/organizations/<org>/reset_rate_limits
+ *   { program: "cedar_ember", grant_id, request_id }
+ *   → { result, reason?, resets_left?, cleared?, weekly_resets_at?, cooldown_until? }
+ *
+ * `request_id` is an idempotency key. A retry of the same user action must
+ * reuse it, so a claim whose answer was lost can't spend a second reset.
+ *
+ * A reset is one-off and irreversible. Nothing here is reachable from an
+ * agent tool; the only caller is a confirm button a human presses.
+ */
+
+import { randomUUID } from "node:crypto";
+import { logWarn } from "../../../util/log.js";
+import type {
+  BankedResetClaim,
+  BankedResetGrant,
+  BankedResetOffer,
+  BankedResetResult,
+} from "../../../core/agent-runtime/capabilities.js";
+import {
+  CLI_USER_AGENT,
+  USAGE_ENDPOINT,
+  invalidatePlanUsage,
+  readCredentials,
+} from "./plan-usage.js";
+
+const API_BASE = "https://api.anthropic.com";
+const PROFILE_ENDPOINT = `${API_BASE}/api/oauth/profile`;
+const PROGRAM = "cedar_ember";
+const READ_TIMEOUT_MS = 5_000;
+// The CLI allows a claim 25s; the server may do real work before answering.
+const CLAIM_TIMEOUT_MS = 25_000;
+
+// Same patterns the CLI enforces before it will send a claim.
+const GRANT_ID = /^[a-z0-9_-]{1,40}$/;
+const REQUEST_ID = /^[A-Za-z0-9_-]{1,64}$/;
+const ORG_ID = /^[A-Za-z0-9-]{1,64}$/;
+
+const SERVER_RESULTS: ReadonlySet<string> = new Set([
+  "reset",
+  "already_used",
+  "not_limited",
+  "cooldown",
+  "ineligible",
+  "unavailable",
+]);
+
+export function isValidGrantId(id: string): boolean {
+  return GRANT_ID.test(id);
+}
+
+export function isValidRequestId(id: string): boolean {
+  return REQUEST_ID.test(id);
+}
+
+/** A fresh idempotency key for one user action. */
+export function newResetRequestId(): string {
+  return randomUUID().replace(/-/g, "");
+}
+
+export interface ResetStatus {
+  atLimit: boolean;
+  cooldownUntil?: string;
+  nextGrantId?: string;
+  grants: Array<BankedResetGrant & { paused: boolean; usableNow: boolean }>;
+}
+
+function str(v: unknown): string | undefined {
+  return typeof v === "string" && v.length > 0 ? v : undefined;
+}
+
+function strings(v: unknown): string[] {
+  return Array.isArray(v)
+    ? v.filter((x): x is string => typeof x === "string")
+    : [];
+}
+
+function percents(v: unknown): Record<string, number> {
+  const out: Record<string, number> = {};
+  if (!v || typeof v !== "object") return out;
+  for (const [k, p] of Object.entries(v as Record<string, unknown>)) {
+    if (typeof p === "number" && Number.isFinite(p))
+      out[k] = Math.max(0, Math.min(100, Math.round(p)));
+  }
+  return out;
+}
+
+/** The `cedar_ember` block of a usage response, or undefined without one. */
+export function parseResetStatus(body: unknown): ResetStatus | undefined {
+  const raw = (body as { cedar_ember?: unknown } | null)?.cedar_ember as
+    Record<string, unknown> | null | undefined;
+  if (!raw || typeof raw !== "object" || raw.eligible === false)
+    return undefined;
+  const grants: ResetStatus["grants"] = [];
+  for (const g of Array.isArray(raw.grants) ? raw.grants : []) {
+    if (!g || typeof g !== "object") continue;
+    const r = g as Record<string, unknown>;
+    const id = str(r.id);
+    // A malformed id is one the CLI would refuse to claim; skip it here too.
+    if (!id || !isValidGrantId(id)) continue;
+    const left = r.resets_left;
+    const endsAt = str(r.ends_at);
+    grants.push({
+      id,
+      label: str(r.label) ?? id,
+      resetsLeft:
+        typeof left === "number" && Number.isFinite(left)
+          ? Math.max(0, Math.floor(left))
+          : 0,
+      ...(endsAt ? { endsAt } : {}),
+      clears: strings(r.clears),
+      percentUsed: percents(r.percent_used),
+      // The CLI defaults an absent flag to the cautious reading.
+      useRequiresLimit: r.use_requires_limit !== false,
+      paused: r.paused === true,
+      usableNow: r.usable_now === true,
+    });
+  }
+  const cooldownUntil = str(raw.cooldown_until);
+  const nextGrantId = str(raw.next_grant_id);
+  return {
+    atLimit: raw.at_limit === true,
+    ...(cooldownUntil ? { cooldownUntil } : {}),
+    ...(nextGrantId ? { nextGrantId } : {}),
+    grants,
+  };
+}
+
+function usable(grant: ResetStatus["grants"][number], now: number): boolean {
+  if (!grant.usableNow || grant.paused || grant.resetsLeft <= 0) return false;
+  const ends = grant.endsAt ? Date.parse(grant.endsAt) : NaN;
+  return !(Number.isFinite(ends) && ends <= now);
+}
+
+/**
+ * The grant a claim should spend: the server's `next_grant_id` when that
+ * grant is usable, else the usable grant that expires soonest (a grant with
+ * no deadline goes last).
+ */
+export function pickGrant(
+  status: ResetStatus,
+  now = Date.now(),
+): ResetStatus["grants"][number] | undefined {
+  const candidates = status.grants.filter((g) => usable(g, now));
+  const next = candidates.find((g) => g.id === status.nextGrantId);
+  if (next) return next;
+  const deadline = (g: { endsAt?: string }) => {
+    const t = g.endsAt ? Date.parse(g.endsAt) : NaN;
+    return Number.isFinite(t) ? t : Infinity;
+  };
+  return candidates.sort((a, b) => deadline(a) - deadline(b))[0];
+}
+
+function authHeaders(token: string): Record<string, string> {
+  return {
+    Authorization: `Bearer ${token}`,
+    "anthropic-beta": "oauth-2025-04-20",
+    "User-Agent": CLI_USER_AGENT,
+  };
+}
+
+async function oauthToken(): Promise<string | undefined> {
+  // An API-key session isn't on the subscription whose resets these are.
+  if (process.env.ANTHROPIC_API_KEY) return undefined;
+  return (await readCredentials())?.accessToken;
+}
+
+/** What a claim would spend right now, or undefined when there's nothing. */
+export async function getBankedResetOffer(
+  now = Date.now(),
+): Promise<BankedResetOffer | undefined> {
+  const token = await oauthToken();
+  if (!token) return undefined;
+  try {
+    const res = await fetch(USAGE_ENDPOINT, {
+      headers: authHeaders(token),
+      signal: AbortSignal.timeout(READ_TIMEOUT_MS),
+    });
+    if (!res.ok) {
+      logWarn("agent", `banked resets: usage returned ${res.status}`);
+      return undefined;
+    }
+    const status = parseResetStatus(await res.json());
+    if (!status) return undefined;
+    const grant = pickGrant(status, now);
+    if (!grant) return undefined;
+    const { paused: _p, usableNow: _u, ...clean } = grant;
+    const totalResetsLeft = status.grants
+      .filter((g) => usable(g, now))
+      .reduce((n, g) => n + g.resetsLeft, 0);
+    return {
+      grant: clean,
+      atLimit: status.atLimit,
+      ...(status.cooldownUntil ? { cooldownUntil: status.cooldownUntil } : {}),
+      totalResetsLeft,
+    };
+  } catch (err) {
+    logWarn(
+      "agent",
+      `banked resets: ${err instanceof Error ? err.message : String(err)}`,
+    );
+    return undefined;
+  }
+}
+
+async function organizationId(token: string): Promise<string | undefined> {
+  const res = await fetch(PROFILE_ENDPOINT, {
+    headers: authHeaders(token),
+    signal: AbortSignal.timeout(READ_TIMEOUT_MS),
+  });
+  if (!res.ok) return undefined;
+  const body = (await res.json()) as { organization?: { uuid?: unknown } };
+  const id = body?.organization?.uuid;
+  return typeof id === "string" && ORG_ID.test(id) ? id : undefined;
+}
+
+const failed = (result: BankedResetResult): BankedResetClaim => ({
+  result,
+  cleared: [],
+});
+
+/** Map a claim response body onto a result; unknown results read as unavailable. */
+export function parseClaimResponse(body: unknown): BankedResetClaim {
+  const r = (body && typeof body === "object" ? body : {}) as Record<
+    string,
+    unknown
+  >;
+  const result =
+    typeof r.result === "string" && SERVER_RESULTS.has(r.result)
+      ? (r.result as BankedResetResult)
+      : "unavailable";
+  const reason = str(r.reason);
+  const left = r.resets_left;
+  const weeklyResetsAt = str(r.weekly_resets_at);
+  const cooldownUntil = str(r.cooldown_until);
+  return {
+    result,
+    ...(reason ? { reason } : {}),
+    ...(typeof left === "number" && Number.isInteger(left) && left >= 0
+      ? { resetsLeft: left }
+      : {}),
+    cleared: strings(r.cleared),
+    ...(weeklyResetsAt ? { weeklyResetsAt } : {}),
+    ...(cooldownUntil ? { cooldownUntil } : {}),
+  };
+}
+
+/**
+ * Spend one reset from `grantId`. Never throws: every failure comes back as
+ * a result the caller can put into words.
+ */
+export async function claimBankedReset(
+  grantId: string,
+  requestId: string = newResetRequestId(),
+): Promise<BankedResetClaim> {
+  if (!isValidGrantId(grantId) || !isValidRequestId(requestId)) {
+    logWarn("agent", "banked resets: refusing a malformed grant or request id");
+    return failed("error");
+  }
+  const token = await oauthToken();
+  if (!token) return failed("auth_error");
+
+  try {
+    const org = await organizationId(token);
+    if (!org) return failed("auth_error");
+    const res = await fetch(
+      `${API_BASE}/api/organizations/${org}/reset_rate_limits`,
+      {
+        method: "POST",
+        headers: { ...authHeaders(token), "Content-Type": "application/json" },
+        body: JSON.stringify({
+          program: PROGRAM,
+          grant_id: grantId,
+          request_id: requestId,
+        }),
+        signal: AbortSignal.timeout(CLAIM_TIMEOUT_MS),
+      },
+    );
+    if (res.status === 429) return failed("rate_limited");
+    if (res.status === 401 || res.status === 403) return failed("auth_error");
+    if (!res.ok) {
+      logWarn("agent", `banked resets: claim returned ${res.status}`);
+      return failed("error");
+    }
+    const claim = parseClaimResponse(await res.json().catch(() => null));
+    // Any settled answer changes what /usage should say; re-read next time.
+    if (claim.result !== "unavailable") invalidatePlanUsage();
+    return claim;
+  } catch (err) {
+    logWarn(
+      "agent",
+      `banked resets: claim failed: ${err instanceof Error ? err.message : String(err)}`,
+    );
+    return failed("error");
+  }
+}

package/src/backend/claude-sdk/{plan-usage.ts → usage/plan-usage.ts}

@@ -15,20 +15,20 @@
 import { readFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { join } from "node:path";
-import { logWarn } from "../../util/log.js";
+import { logWarn } from "../../../util/log.js";
 import type {
   PlanUsage,
   PlanWindow,
-} from "../../core/agent-runtime/capabilities.js";
+} from "../../../core/agent-runtime/capabilities.js";
 
 // `cedar_ember=1` asks the endpoint to include banked limit resets (the
 // claude.ai "Reset for free" grants); `skip_spend=1` drops the spend block we
 // don't render. Resets are only reported to the CLI surface — any other
 // user agent gets `ineligible_reason: "surface"` — so the request identifies
 // as the CLI, which is what the Agent SDK runs anyway.
-const USAGE_ENDPOINT =
+export const USAGE_ENDPOINT =
   "https://api.anthropic.com/api/oauth/usage?cedar_ember=1&skip_spend=1";
-const CLI_USER_AGENT = "claude-cli/2.1.280 (external, cli)";
+export const CLI_USER_AGENT = "claude-cli/2.1.280 (external, cli)";
 const REQUEST_TIMEOUT_MS = 5_000;
 const CACHE_TTL_MS = 60_000;
 
@@ -48,7 +48,7 @@ interface OAuthCredentials {
   subscriptionType?: string;
 }
 
-async function readCredentials(): Promise<OAuthCredentials | undefined> {
+export async function readCredentials(): Promise<OAuthCredentials | undefined> {
   try {
     const parsed = JSON.parse(await readFile(credentialsPath(), "utf8")) as {
       claudeAiOauth?: OAuthCredentials;

package/src/cli/config.ts

@@ -87,18 +87,124 @@ export const DEFAULTS: Config = {
   maxMessageLength: 4000,
 };
 
+/**
+ * A config.json that exists but can't be used — unreadable, not valid
+ * JSON, or not a JSON object. Thrown instead of silently falling back to
+ * defaults: `loadConfig` backs both read-only commands (`status`,
+ * `config`, `doctor`, the main menu's "is this configured?" check) and
+ * load → edit → save commands (`setup`, `plugin`), so treating a broken
+ * file as `{}` used to let the latter write those empty defaults straight
+ * back over — destroying — the user's real config. Mirrors
+ * core/config/index.ts's `ConfigFileError` in shape and wording (#1031)
+ * without importing across the CLI/daemon boundary; unlike that one, the
+ * CLI's `Config` type has no runtime schema, so there's no per-key
+ * validation to report here, only "can this be read as a JSON object".
+ */
+export class ConfigFileError extends Error {
+  constructor(
+    message: string,
+    readonly path: string,
+  ) {
+    super(message);
+    this.name = "ConfigFileError";
+  }
+}
+
+/**
+ * Append a line/column hint to a JSON.parse error message. Recent V8
+ * already includes "(line L column C)"; older runtimes only report
+ * "at position N", so derive it from the raw text in that case.
+ */
+function describeJsonError(err: unknown, raw: string): string {
+  const message = err instanceof Error ? err.message : String(err);
+  if (/\(line \d+ column \d+\)/.test(message)) return message;
+  const match = /at position (\d+)/.exec(message);
+  if (!match) return message;
+  const before = raw.slice(0, Number(match[1]));
+  const line = before.split("\n").length;
+  const column = before.length - before.lastIndexOf("\n");
+  return `${message} (line ${line} column ${column})`;
+}
+
+/** Parse `raw` as a config object, or describe in one phrase why it isn't one. */
+function parseConfigJson(
+  raw: string,
+):
+  { ok: true; data: Record<string, unknown> } | { ok: false; problem: string } {
+  let data: unknown;
+  try {
+    data = JSON.parse(raw);
+  } catch (err) {
+    return {
+      ok: false,
+      problem: `invalid JSON — ${describeJsonError(err, raw)}`,
+    };
+  }
+  if (data === null || typeof data !== "object" || Array.isArray(data)) {
+    return { ok: false, problem: "the top level must be a JSON object" };
+  }
+  return { ok: true, data: data as Record<string, unknown> };
+}
+
+/**
+ * Load ~/.talon/config.json. A missing file is first run: defaults apply.
+ * A present file that can't be read or isn't a valid JSON object throws
+ * `ConfigFileError` — see the class comment for why this must not fall
+ * back to defaults instead.
+ */
 export function loadConfig(): Config {
+  if (!existsSync(CONFIG_FILE)) return { ...DEFAULTS };
+  let raw: string;
   try {
-    if (existsSync(CONFIG_FILE)) {
-      return { ...DEFAULTS, ...JSON.parse(readFileSync(CONFIG_FILE, "utf-8")) };
-    }
-  } catch {
-    /* corrupt */
+    raw = readFileSync(CONFIG_FILE, "utf-8");
+  } catch (err) {
+    throw new ConfigFileError(
+      `Cannot read ${CONFIG_FILE}: ${err instanceof Error ? err.message : err}`,
+      CONFIG_FILE,
+    );
+  }
+  const result = parseConfigJson(raw);
+  if (!result.ok) {
+    throw new ConfigFileError(
+      `Invalid config in ${CONFIG_FILE}: ${result.problem}. ` +
+        `The file was left untouched — fix it and try again.`,
+      CONFIG_FILE,
+    );
   }
-  return { ...DEFAULTS };
+  return { ...DEFAULTS, ...result.data };
 }
 
+/**
+ * Save ~/.talon/config.json. Refuses to overwrite an existing file that
+ * isn't valid JSON. The normal caller shape is load → edit → save, and
+ * `loadConfig` above already throws before such a caller ever reaches
+ * this point — this check is the backstop for any caller that saves
+ * without a fresh load, or for the file changing under us between the
+ * two calls: writing `config` in either case would silently replace
+ * whatever is actually on disk with the caller's best guess.
+ */
 export function saveConfig(config: Config): void {
+  if (existsSync(CONFIG_FILE)) {
+    let raw: string;
+    try {
+      raw = readFileSync(CONFIG_FILE, "utf-8");
+    } catch (err) {
+      throw new ConfigFileError(
+        `Refusing to write ${CONFIG_FILE}: cannot read the existing file ` +
+          `(${err instanceof Error ? err.message : err}). It was left untouched.`,
+        CONFIG_FILE,
+      );
+    }
+    const result = parseConfigJson(raw);
+    if (!result.ok) {
+      throw new ConfigFileError(
+        `Refusing to write ${CONFIG_FILE}: the existing file is invalid ` +
+          `(${result.problem}). It was left untouched — fix it manually, ` +
+          `or delete it to start over.`,
+        CONFIG_FILE,
+      );
+    }
+  }
   if (!existsSync(dirs.root)) mkdirSync(dirs.root, { recursive: true });
   const clean = Object.fromEntries(
     Object.entries(config).filter(([, v]) => v !== undefined),

package/src/cli/index.ts

@@ -24,7 +24,7 @@ import pc from "picocolors";
 // inlines the JSON at compile time; tsx/node resolve it from the package.
 import pkg from "../../package.json" with { type: "json" };
 import { PKG_ROOT } from "./context.js";
-import { printBanner } from "./config.js";
+import { printBanner, ConfigFileError } from "./config.js";
 import { runSetup } from "./setup.js";
 import { showStatus } from "./status.js";
 import { viewConfig } from "./config-view.js";
@@ -121,84 +121,86 @@ function printHelp(): void {
 /** Route a `talon <command>` invocation. Called by the entry point. */
 export async function runCli(): Promise<void> {
   const command = process.argv[2];
-  switch (command) {
-    case "setup":
-      runSetup();
-      break;
-    case "status":
-      showStatus();
-      break;
-    case "config":
-      viewConfig();
-      break;
-    case "logs":
-      tailLogs();
-      break;
-    case "start":
-      printBanner();
-      await daemonStart();
-      break;
-    case "stop":
-      printBanner();
-      await daemonStop();
-      break;
-    case "restart":
-      printBanner();
-      await daemonRestart();
-      break;
-    case "run":
-      process.chdir(PKG_ROOT);
-      import("../index.js");
-      break;
-    case "chat":
-      process.chdir(PKG_ROOT);
-      startChat();
-      break;
-    case "doctor":
-      runDoctor();
-      break;
-    case "ps":
-      await showTasks(process.argv[3] === "--all" || process.argv[3] === "-a");
-      break;
-    case "kill":
-      await killTask(process.argv[3]);
-      break;
-    case "events":
-      await showEvents(eventsOptions(process.argv.slice(3)));
-      break;
-    case "backup":
-      await runBackupCommand(process.argv.slice(3));
-      break;
-    case "plugin":
-      await runPluginCommand(process.argv.slice(3));
-      break;
-    case "skill":
-      await runSkillCommand(process.argv.slice(3));
-      break;
-    case "memory":
-      runMemoryCommand(process.argv.slice(3));
-      break;
-    case "--version":
-    case "-v": {
-      console.log(pkg.version);
-      break;
-    }
-    case "--help":
-    case "-h":
-      printHelp();
-      break;
-    case undefined:
-      mainMenu();
-      break;
-    default: {
-      // "did you mean ...?" via the native similarity core (native/strsim-wasm).
-      const { closestMatch } = await import("../native/strsim.js");
-      const suggestion = closestMatch(command, CLI_COMMANDS);
-      const hint = suggestion
-        ? `Did you mean ${pc.cyan(`talon ${suggestion.value}`)}?`
-        : `Run ${pc.cyan("talon --help")} for usage.`;
-      console.error(`  Unknown command: ${command}\n  ${hint}\n`);
-      process.exit(1);
+  try {
+    await dispatch(command);
+  } catch (err) {
+    // A present-but-invalid config.json: every command below that reads
+    // config (directly, or via `mainMenu`'s "is this configured?" check)
+    // is async but was previously invoked without `await`, so this throw
+    // would otherwise surface as a bare unhandled-rejection stack trace —
+    // or, worse for the main menu, never happen at all, because the old
+    // loader swallowed the error and returned defaults, sending a broken
+    // install into the first-run wizard, which then saves over the file.
+    if (err instanceof ConfigFileError) {
+      console.error(`\n  ${pc.red("✖")} ${err.message}\n`);
+      process.exitCode = 1;
+      return;
     }
+    throw err;
+  }
+}
+
+type CommandHandler = (args: string[]) => void | Promise<void>;
+
+/** Every `talon <command>`, keyed by name. Handlers get the argv after the command. */
+const COMMANDS: Record<string, CommandHandler> = {
+  setup: () => runSetup(),
+  status: () => showStatus(),
+  config: () => viewConfig(),
+  logs: () => tailLogs(),
+  start: async () => {
+    printBanner();
+    await daemonStart();
+  },
+  stop: async () => {
+    printBanner();
+    await daemonStop();
+  },
+  restart: async () => {
+    printBanner();
+    await daemonRestart();
+  },
+  run: () => {
+    process.chdir(PKG_ROOT);
+    void import("../index.js");
+  },
+  chat: () => {
+    process.chdir(PKG_ROOT);
+    startChat();
+  },
+  doctor: () => runDoctor(),
+  ps: (args) => showTasks(args[0] === "--all" || args[0] === "-a"),
+  kill: (args) => killTask(args[0]),
+  events: (args) => showEvents(eventsOptions(args)),
+  backup: (args) => runBackupCommand(args),
+  plugin: (args) => runPluginCommand(args),
+  skill: (args) => runSkillCommand(args),
+  memory: (args) => runMemoryCommand(args),
+  "--version": () => console.log(pkg.version),
+  "-v": () => console.log(pkg.version),
+  "--help": () => printHelp(),
+  "-h": () => printHelp(),
+};
+
+async function unknownCommand(command: string): Promise<never> {
+  // "did you mean ...?" via the native similarity core (native/strsim-wasm).
+  const { closestMatch } = await import("../native/strsim.js");
+  const suggestion = closestMatch(command, CLI_COMMANDS);
+  const hint = suggestion
+    ? `Did you mean ${pc.cyan(`talon ${suggestion.value}`)}?`
+    : `Run ${pc.cyan("talon --help")} for usage.`;
+  console.error(`  Unknown command: ${command}\n  ${hint}\n`);
+  process.exit(1);
+}
+
+async function dispatch(command: string | undefined): Promise<void> {
+  if (command === undefined) {
+    await mainMenu();
+    return;
   }
+  const handler = Object.hasOwn(COMMANDS, command)
+    ? COMMANDS[command]
+    : undefined;
+  if (!handler) return unknownCommand(command);
+  await handler(process.argv.slice(3));
 }

package/src/core/agent-runtime/capabilities.ts

@@ -243,6 +243,67 @@ export interface UsageTelemetry {
    * plan concept; resolves `undefined` when the data can't be read.
    */
   getPlanUsage?(): Promise<PlanUsage | undefined>;
+  /**
+   * Banked one-shot limit resets, where the plan has them. Spending one is
+   * irreversible, so this is reachable only from a human-pressed confirm
+   * button — never exposed as an agent tool.
+   */
+  bankedResets?: BankedResetControl;
+}
+
+/** One banked reset grant, as the plan reports it. */
+export interface BankedResetGrant {
+  id: string;
+  label: string;
+  resetsLeft: number;
+  /** ISO deadline, when the grant has one. */
+  endsAt?: string;
+  /** Plan windows the reset clears (`five_hour`, `seven_day`, …). */
+  clears: string[];
+  /** Current utilisation per cleared window, 0-100. */
+  percentUsed: Record<string, number>;
+  /** The reset can only be spent while the account is at a limit. */
+  useRequiresLimit: boolean;
+}
+
+/** The grant a claim would spend, plus the account state around it. */
+export interface BankedResetOffer {
+  grant: BankedResetGrant;
+  atLimit: boolean;
+  /** ISO end of a post-claim cooldown, while one is running. */
+  cooldownUntil?: string;
+  /** Resets left across every usable grant. */
+  totalResetsLeft: number;
+}
+
+export type BankedResetResult =
+  | "reset"
+  | "already_used"
+  | "not_limited"
+  | "cooldown"
+  | "ineligible"
+  | "unavailable"
+  | "rate_limited"
+  | "auth_error"
+  | "error";
+
+export interface BankedResetClaim {
+  result: BankedResetResult;
+  /** Server-side reason code, when it gave one. */
+  reason?: string;
+  resetsLeft?: number;
+  cleared: string[];
+  weeklyResetsAt?: string;
+  cooldownUntil?: string;
+}
+
+export interface BankedResetControl {
+  getOffer(): Promise<BankedResetOffer | undefined>;
+  /**
+   * Spend one reset from `grantId`. `requestId` is the idempotency key:
+   * reuse it when retrying the same user action so a retry can't spend twice.
+   */
+  claim(grantId: string, requestId: string): Promise<BankedResetClaim>;
 }
 
 /** One subscription rate-limit window, as `/status` renders it. */

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/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 };