pi-lxmf 0.1.3 → 0.2.0

package/CHANGELOG.md

@@ -7,6 +7,28 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-09-27
+
+### Added
+
+- **Quota exhaustion and 90% warnings** (work doc #3): the GLM quota
+  watcher now samples the z.ai quota API continuously while a GLM model
+  is active (not just after a run fails) and notifies the owner when a
+  bucket (5h or weekly) hits 100% — including at startup, when the daemon
+  starts mid-outage — and when one crosses 90%. The startup check runs
+  immediately on enable, so no error is needed to detect an exhausted
+  bucket.
+- The startup notification now names the active model (fresh `get_state`
+  observation) — the model isn't visible anywhere else over LXMF.
+- `/model` and `/think` re-observe state right away, so the quota watcher
+  gate follows the switch immediately instead of on the next prompt.
+
+### Fixed
+
+- A run that failed after delivering partial output silently trailed
+  off: the error is now reported as a "run ended early" message and no
+  longer leaks into a later exchange's failure reply.
+
 ## [0.1.3] - 2026-09-27
 
 ### Changed

package/README.md

@@ -88,9 +88,10 @@ node src/bin.js --help
 |---|---|
 | plain text | a prompt to the agent (steered into a running turn by default) |
 | `/help` | bridge commands + Pi commands available via prompt |
-| `/status` | model, thinking, session, uptime, node + owner identity hashes |
+| `/status` | model, thinking, session, uptime, cwd + workdir, node + owner identity hashes |
 | `/session` | message counts, tokens, cost, context usage |
 | `/new` | fresh Pi session |
+| `/cd [path]` | switch the supervised Pi to another repo under `workdir`; bare `/cd` lists current + recent repos |
 | `/name [name]` | show / set the session display name |
 | `/compact [instructions]` | compact the conversation context |
 | `/model [query]` | list models, or switch (`/model sonnet`) |
@@ -105,6 +106,15 @@ Replies are delivered per finished assistant message, chunked to fit
 then a `✅ done (no reply)` nudge. Extension dialogs raised inside Pi are
 auto-declined (nobody is at a terminal) and reported to you.
 
+`/cd` makes one bridge serve every repo under `workdir`: switching is a
+supervised respawn in the target directory (messages queue during the switch),
+each repo keeps its own Pi session — revisiting one resumes its conversation —
+and the active repo is remembered across daemon restarts. Targets must resolve
+under `workdir` (no `..` traversal, nothing outside the tree); anything else
+is refused without touching the child. `/status` shows the current `cwd` and
+`workdir`, and each switched-to project must be trusted once (see step 4
+above) for its local `.pi` resources to load.
+
 ## Configuration
 
 `~/.config/pi-lxmf/config.json` (XDG env vars respected). A missing file runs
@@ -114,7 +124,7 @@ on defaults.
 |---|---|---|
 | `owner` | *(required)* | the owner's 32-hex **Reticulum identity hash** (not the LXMF address); the daemon derives the `lxmf.delivery` destination hash for wire comparison |
 | `name` | `pi-lxmf <version>` | announce display name |
-| `workdir` | daemon cwd | project directory Pi runs in (also where `AGENTS.md` is found) |
+| `workdir` | daemon cwd | project directory Pi runs in (also where `AGENTS.md` is found); the trust root `/cd` cannot escape |
 | `model` | Pi default | `--model` pattern passed to Pi |
 | `piBin` | `pi` | Pi binary |
 | `dataDir` | `~/.local/share/pi-lxmf` | state root (see below) |

package/SPEC.md

@@ -308,19 +308,30 @@ the recently used ones (derived from the per-workdir session pointers);
 ### 6.7 z.ai GLM quota watcher and peak-hours warning
 
 When the active model is a z.ai GLM model (`provider === "zai"`), the bridge
-runs a `GlmQuotaWatcher` (`src/quota.js`) that does two things, both gated
-on the active model being GLM — nothing fires for non-z.ai providers (e.g.
-Cortecs, Anthropic):
-
-- **Quota-recovery notification.** When a run fails with a z.ai
-  quota-exhausted error (matched from `auto_retry_end`/`compaction_end`
-  error messages), the watcher polls the same z.ai quota endpoint
-  `pi-glm-usage` uses (`https://api.z.ai/api/monitor/usage/quota/limit`,
-  Bearer `~/.pi/agent/auth.json` → `zai.key`, honouring `PI_AUTH_DIR`) every
-  60s and delivers **exactly one** LXMF message to the owner the moment
-  the 5h bucket drops below 100%. One notification per exhausted episode;
-  rate-limit-only errors (transient, retried by Pi) do not arm it. A
-  missing `zai.key` disables the watcher gracefully (logged once).
+runs a `GlmQuotaWatcher` (`src/quota.js`), gated on the active model being
+GLM — nothing fires for non-z.ai providers (e.g. Cortecs, Anthropic). The
+gate is (re-)evaluated on every `get_state` observation: prompts, the
+startup observation, and after `/model`/`/think` commands.
+
+- **Continuous quota sampling.** While enabled, the watcher polls the
+  same z.ai quota endpoint `pi-glm-usage` uses
+  (`https://api.z.ai/api/monitor/usage/quota/limit`, Bearer
+  `~/.pi/agent/auth.json` → `zai.key`, honouring `PI_AUTH_DIR`) every 60s
+  (first sample immediately on enable — so a daemon that starts mid-outage
+  detects and reports it right away). From those samples the owner is
+  notified of:
+  - **Exhaustion** — a bucket (5h or weekly) reaching 100%: once per
+    episode, with the reset time when the API reports one.
+  - **90% warning** — a bucket at or above 90% while below 100%: once
+    per window (a dip below the threshold re-arms it).
+  - **Recovery** — the 5h bucket dropping below 100% after an exhausted
+    episode: once per episode.
+  A quota-looking Pi error (`auto_retry_end`/`compaction_end`) forces an
+  immediate fresh sample; rate-limit-only errors (transient, retried by
+  Pi) are ignored. Per-sample notices are joined into one LXMF message
+  and — when an owner-triggered run is live — deferred to `agent_settled`
+  so they never interleave with a reply. A missing `zai.key` disables the
+  watcher gracefully (logged once).
 - **Peak-hours warning.** z.ai charges 3× tokens Mon–Fri 14:00–18:00
   Singapore Standard Time (UTC+8). The owner is warned when an
   owner-triggered run starts inside that window, and when the window

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-lxmf",
-  "version": "0.1.3",
+  "version": "0.2.0",
   "description": "Drive the Pi coding agent over LXMF messaging (Reticulum mesh) from a headless server.",
   "license": "EUPL-1.2",
   "author": "Henri Bergius <henri.bergius@iki.fi>",

package/src/bridge.js

@@ -315,6 +315,18 @@ export class Bridge {
         this.log.log(`pi-lxmf: inbound from owner: command /${parsed.name}`);
         try {
           const result = await command.run(this.commandContext(), parsed.args);
+          // /model and /think change pi state the bridge tracks through
+          // `get_state` observations — re-observe so the active model (and
+          // the GLM watcher gate) follow immediately instead of on the
+          // next prompt. Other commands manage their own observations
+          // (e.g. /cd) or don't affect tracked state.
+          if (parsed.name === "model" || parsed.name === "think") {
+            try {
+              this.observeState(await this.rpc.getState());
+            } catch {
+              /* keep stale observations; next prompt re-observes */
+            }
+          }
           const text = typeof result === "string" ? result : result?.text;
           if (text) await this.deliver(text);
           if (result && typeof result === "object" && result.shutdown) {
@@ -466,6 +478,14 @@ export class Bridge {
 
     if (sent > 0) {
       this.recovering = false;
+      // The owner already got (partial) output. A trailing failure means
+      // the run died mid-reply: say so — otherwise the exchange just
+      // trails off — and never let the error leak into a later exchange.
+      if (this.lastError) {
+        const error = this.lastError;
+        this.lastError = null;
+        await this.deliver(`⚠️ run ended early: ${error}`);
+      }
       return;
     }
     if (this.lastError) {
@@ -655,17 +675,29 @@ export class Bridge {
    * Tells the owner the bridge has started and is accepting messages
    * (the startup case of SPEC §13 proactive notifications). Called by the
    * daemon once the mesh side is announcing and the RPC child is ready.
-   * Best-effort via {@link deliver}: a failure is noted and carried by
-   * the next successful delivery instead of being lost.
+   * The active model is included (fresh `get_state` observation) — the
+   * owner can't see the TUI footer over LXMF, so the startup message is
+   * the only place the model is announced proactively. Best-effort via
+   * {@link deliver}: a failure is noted and carried by the next
+   * successful delivery instead of being lost.
    *
    * @param {string|null} [resumedSessionFile] - Absolute path of the
    *   session resumed from the persisted pointer, when one exists.
    */
   async notifyStartup(resumedSessionFile = null) {
-    const resumed = resumedSessionFile
-      ? `\nResuming session ${basename(resumedSessionFile)}.`
-      : "";
-    await this.deliver(`🟢 pi-lxmf ready — listening for messages.${resumed}`);
+    try {
+      this.observeState(await this.rpc.getState());
+    } catch {
+      /* RPC child is ready (checked by the caller); keep the old model */
+    }
+    const lines = ["🟢 pi-lxmf ready — listening for messages."];
+    if (typeof this.activeModel?.name === "string" && this.activeModel.name) {
+      lines.push(`Model: ${this.activeModel.name}`);
+    }
+    if (resumedSessionFile) {
+      lines.push(`Resuming session ${basename(resumedSessionFile)}.`);
+    }
+    await this.deliver(lines.join("\n"));
   }
 
   /**

package/src/quota.js

@@ -3,15 +3,27 @@
  *
  * z.ai (GLM Coding Plan) quota watcher + peak-hours warning (work doc #3).
  *
- * Two related behaviours, both gated on the active model being a z.ai GLM
+ * Three related behaviours, all gated on the active model being a z.ai GLM
  * model (`provider === "zai"`):
  *
- * 1. **Quota-recovery notification.** When a run fails with a z.ai
- *    quota-exhausted error, poll the z.ai quota endpoint and push exactly
- *    one LXMF message to the owner the moment the 5h bucket becomes
- *    available again, so the owner can resume work without babysitting it.
+ * 1. **Continuous quota sampling.** While a GLM model is active, the same
+ *    z.ai quota endpoint `pi-glm-usage` uses is polled every 60s. From
+ *    those samples the owner is notified of:
+ *    - **Exhaustion** (once per episode): a bucket (5h or weekly) reaches
+ *      100% — including at startup, when a daemon restarts mid-outage.
+ *    - **90% warning** (once per bucket window): a bucket crosses 90%,
+ *      while still below 100%.
+ *    - **Recovery** (once per episode): the 5h bucket drops below 100%
+ *      after an exhausted episode.
+ *    Per-sample notifications are joined into a single LXMF message and
+ *    deferred to `agent_settled` while an owner-triggered run is live.
  *
- * 2. **Peak-hours warning.** z.ai charges 3× tokens during peak hours
+ * 2. **Quota-error arming.** A Pi error that looks like a z.ai
+ *    quota-exhausted failure (`auto_retry_end`/`compaction_end`) arms the
+ *    poller immediately, even when the live fetch is momentarily
+ *    inconclusive — the authoritative answer is the next sample.
+ *
+ * 3. **Peak-hours warning.** z.ai charges 3× tokens during peak hours
  *    (Mon–Fri 14:00–18:00 Singapore Standard Time, UTC+8). Warn the owner
  *    when an owner-triggered run starts inside that window, and when the
  *    window opens mid-run, so they can decide whether to stop or continue.
@@ -30,7 +42,7 @@ import { join } from "node:path";
 const QUOTA_URL = "https://api.z.ai/api/monitor/usage/quota/limit";
 /** Fetch timeout for the quota endpoint (ms). */
 const FETCH_TIMEOUT_MS = 5000;
-/** Poll cadence while the 5h bucket is exhausted (ms). */
+/** Sampling cadence while a GLM model is active (ms). */
 const POLL_INTERVAL_MS = 60_000;
 
 /**
@@ -56,9 +68,11 @@ const Unit = {
 };
 
 /**
- * The 5h bucket is treated as exhausted at-or-above this percentage.
+ * A bucket is treated as exhausted at-or-above this percentage.
  */
 const EXHAUSTED_PERCENTAGE = 100;
+/** Warning threshold (crossing upward, while not exhausted). */
+const WARN_PERCENTAGE = 90;
 
 /** z.ai provider id (and its `z.ai` alias, defensively). */
 const ZAI_PROVIDERS = new Set(["zai", "z.ai"]);
@@ -196,7 +210,6 @@ export function isPeakTime(epochMs) {
  */
 export function msUntilPeakOpen(fromMs) {
   if (isPeakTime(fromMs)) return 0;
-  const from = new Date(fromMs);
   // Walk forward hour by hour (max ~7 days) to the first peak hour.
   for (let h = 0; h < 24 * 7; h++) {
     const probe = new Date(fromMs + h * 3_600_000);
@@ -222,11 +235,35 @@ export function msUntilPeakOpen(fromMs) {
   return Number.POSITIVE_INFINITY;
 }
 
+/**
+ * A live or pinned quota sample for one bucket. `percentage` may exceed
+ * `WARN_PERCENTAGE`/`EXHAUSTED_PERCENTAGE` by z.ai's rounding; comparisons
+ * are inclusive.
+ *
+ * @typedef {{percentage: number, nextResetMs: number}} BucketSample
+ */
+
 /**
  * The z.ai quota watcher + peak-hours warner. Construct one per bridge;
  * drive it with {@link GlmQuotaWatcher.setEnabled} (gated on the active
- * model) and {@link GlmQuotaWatcher.onAgentStart} / {@link
- * GlmQuotaWatcher.onAgentSettled} / {@link GlmQuotaWatcher.onError}.
+ * model) and {@link GlmQuotaWatcher.onAgentStart} /
+ * {@link GlmQuotaWatcher.onAgentSettled} / {@link GlmQuotaWatcher.onError}.
+ *
+ * While enabled, a single sampler polls the quota endpoint every
+ * `pollIntervalMs` (first sample immediately). Each sample can queue at
+ * most one joined notice:
+ * - a bucket crossing `WARN_PERCENTAGE` (once per bucket window) queues
+ *   a "90%" warning line;
+ * - a bucket reaching `EXHAUSTED_PERCENTAGE` (once per bucket episode)
+ *   queues an "exhausted" line with the reset time;
+ * - the 5h bucket recovering from an exhausted episode (once per episode)
+ *   queues a "recovered" line.
+ *
+ * A run-triggered error ({@link GlmQuotaWatcher.onError}) additionally
+ * forces an immediate sample (fresh state over stale-sampler lag).
+ * Notices are delivered as one LXMF message per emission — immediately
+ * when the bridge is idle, or when the live owner-triggered run settles
+ * (so they never interleave with a reply mid-run).
  */
 export class GlmQuotaWatcher {
   /**
@@ -238,6 +275,7 @@ export class GlmQuotaWatcher {
    * @param {typeof fetch} [options.fetchImpl] - Injectable fetch (tests).
    * @param {() => number} [options.now] - Injectable clock (tests).
    * @param {number} [options.pollIntervalMs]
+   * @param {number} [options.warnPercentage] - Warning threshold (tests).
    */
   constructor(options) {
     this.ownerDestinationHash = options.ownerDestinationHash;
@@ -247,6 +285,7 @@ export class GlmQuotaWatcher {
     this.fetchImpl = options.fetchImpl || fetch;
     this.now = options.now || (() => Date.now());
     this.pollIntervalMs = options.pollIntervalMs ?? POLL_INTERVAL_MS;
+    this.warnPercentage = options.warnPercentage ?? WARN_PERCENTAGE;
 
     /** Whether the active model is a z.ai GLM model (the master gate). */
     this.enabled = false;
@@ -254,15 +293,28 @@ export class GlmQuotaWatcher {
     this.runActive = false;
     /** Whether the current run is owner-triggered (not recovery). */
     this.ownerTriggered = false;
-    /** Single active quota poller (idempotent start). */
+    /** Single active sampler (idempotent start). */
     /** @type {NodeJS.Timeout|null} */
     this.pollTimer = null;
-    /** Whether the 5h bucket was exhausted when the poller last sampled. */
+    /** Whether the 5h bucket was exhausted in the last sample. */
     this.wasExhausted = false;
-    /** Whether a recovery notification has already been sent for this episode. */
-    this.notifiedThisEpisode = false;
     /** Epoch (ms) the exhaustion episode started, for the human-readable delta. */
     this.exhaustedSinceMs = 0;
+    /**
+     * Whether the 90% warning already fired for each bucket in its current
+     * window (a window is any contiguous below-100% stretch — a reset to
+     * below-warn clears it, an exhausted episode ends it).
+     * @type {{fiveHour: boolean, weekly: boolean}}
+     */
+    this.warned = { fiveHour: false, weekly: false };
+    /** Whether an exhausted episode per bucket already notified (its
+     * "exhausted" notice is once per episode).
+     * @type {{fiveHour: boolean, weekly: boolean}}
+     */
+    this.exhaustionNotified = { fiveHour: false, weekly: false };
+    /** Notices queued while a run is live, delivered on `onAgentSettled`. */
+    /** @type {string[]} */
+    this.pendingNotices = [];
     /** Whether we've already warned about peak for the current run. */
     this.peakWarnedThisRun = false;
     /** Timer for the "run ran into peak" boundary warning. */
@@ -276,7 +328,12 @@ export class GlmQuotaWatcher {
 
   /**
    * Master gate: enable/disable based on whether the active model is z.ai.
-   * Disabling stops any active poller and clears run state.
+   * Enabling starts the sampler immediately (first sample right away), so
+   * an exhausted state at startup or model switch is detected and
+   * notified without waiting for a run or an error. Disabling stops all
+   * timers, clears run state, and (best-effort) delivers anything already
+   * queued — losing queued notices on shutdown is acceptable, but losing
+   * them on a model switch is not.
    *
    * @param {boolean} enabled
    */
@@ -289,10 +346,9 @@ export class GlmQuotaWatcher {
       this.runActive = false;
       this.ownerTriggered = false;
       this.peakWarnedThisRun = false;
+      this.flushNotices();
     } else {
-      // Gated on at startup: do one quota fetch so a daemon that restarted
-      // mid-outage arms the watcher immediately.
-      void this.checkAndMaybeArm(false);
+      this.startPoller(true);
     }
   }
 
@@ -315,11 +371,14 @@ export class GlmQuotaWatcher {
     this.ownerTriggered = false;
     this.peakWarnedThisRun = false;
     this.clearPeakOpenTimer();
+    this.flushNotices();
   }
 
   /**
    * Called when a Pi error event (`auto_retry_end`/`compaction_end`) looks
-   * like a quota failure. Arms the poller (idempotent) when enabled.
+   * like a quota failure. Ensures the sampler is running (idempotent) and
+   * forces an immediate sample so the exhaustion notice is driven by the
+   * authoritative API state, not the sampler's cadence.
    *
    * @param {string} errorMessage
    */
@@ -329,7 +388,8 @@ export class GlmQuotaWatcher {
     this.log.log(
       `pi-lxmf: GLM quota error detected, polling for recovery: ${errorMessage}`,
     );
-    void this.checkAndMaybeArm(true);
+    this.startPoller();
+    void this.tick();
   }
 
   /**
@@ -341,114 +401,144 @@ export class GlmQuotaWatcher {
   }
 
   /**
-   * Fetches the quota once and arms the poller if the 5h bucket is
-   * exhausted. When `fromError` is true (we were tipped off by a Pi error),
-   * arm even if the first fetch is inconclusive (transient API failure).
+   * Starts the sampler if not already running. `immediate` also fires one
+   * sample right away (startup, model switch, quota error) instead of
+   * waiting a full interval.
    *
-   * @param {boolean} fromError
-   * @returns {Promise<void>}
+   * @param {boolean} [immediate]
+   * @private
    */
-  async checkAndMaybeArm(fromError) {
+  startPoller(immediate) {
+    if (this.pollTimer || !this.enabled || !this.apiKey) return;
+    this.pollTimer = setInterval(() => void this.tick(), this.pollIntervalMs);
+    if (typeof this.pollTimer.unref === "function") this.pollTimer.unref();
+    if (immediate) void this.tick();
+  }
+
+  /**
+   * One sampler tick: fetch quota, evaluate bucket transitions, queue
+   * notices for anything new.
+   *
+   * @private
+   */
+  async tick() {
     if (!this.enabled || !this.apiKey) return;
     let quota = null;
     try {
       quota = await fetchQuota(this.apiKey, { fetchImpl: this.fetchImpl });
-    } catch (e) {
-      if (fromError) {
-        // A Pi error said quota-exhausted; trust it and arm, polling will
-        // confirm the recovery transition.
-        this.log.log(
-          `pi-lxmf: GLM quota fetch failed (${e instanceof Error ? e.message : e}); arming watcher on Pi error signal`,
-        );
-        this.armWatcher(0);
-      }
+    } catch {
+      /* transient — retry on the next tick */
       return;
     }
-    const pct = quota.fiveHour?.percentage ?? 0;
-    if (pct >= EXHAUSTED_PERCENTAGE) {
-      this.armWatcher(pct);
-    } else if (this.wasExhausted) {
-      // Recovered between fetches (e.g. daemon was away): notify now.
-      this.notifyRecovered(quota);
-    }
+    this.evaluateSample(quota);
   }
 
   /**
-   * Arms the single poller (idempotent). Records the episode start time on
-   * the first arm of an episode and resets the per-episode notification flag.
+   * Turns a fresh quota sample into (at most one) queued notice, based on
+   * per-bucket window/episode transitions.
    *
-   * @param {number} percentage
+   * @param {{fiveHour?: BucketSample|null, weekly?: BucketSample|null}} quota
+   * @private
    */
-  armWatcher(percentage) {
-    if (!this.wasExhausted) {
-      this.wasExhausted = true;
-      this.exhaustedSinceMs = this.now();
-      this.notifiedThisEpisode = false;
-      this.log.log(
-        `pi-lxmf: GLM 5h quota exhausted (${percentage}%) — will notify on recovery`,
-      );
+  evaluateSample(quota) {
+    const pct = quota.fiveHour?.percentage ?? 0;
+    const weeklyPct = quota.weekly?.percentage ?? 0;
+    const exhausted = pct >= EXHAUSTED_PERCENTAGE;
+    const weeklyExhausted = weeklyPct >= EXHAUSTED_PERCENTAGE;
+
+    /** @type {string[]} */
+    const lines = [];
+
+    // --- 5h bucket ------------------------------------------------------
+    if (exhausted) {
+      if (!this.wasExhausted) {
+        // New exhausted episode: stamp it, re-arm its notices.
+        this.wasExhausted = true;
+        this.exhaustedSinceMs = this.now();
+        this.exhaustionNotified.fiveHour = false;
+        // Suppress the 90% warning for the rest of this window: the
+        // exhaustion (and its recovery) notices say everything already.
+        this.warned.fiveHour = true;
+      }
+      if (!this.exhaustionNotified.fiveHour) {
+        this.exhaustionNotified.fiveHour = true;
+        lines.push(
+          `⚠️ GLM 5h quota exhausted (100%)${resetSuffix(quota.fiveHour?.nextResetMs, this.now())}`,
+        );
+      }
+    } else {
+      if (this.wasExhausted) {
+        // Recovered below 100% after an exhausted episode (once per episode).
+        this.wasExhausted = false;
+        const elapsed = this.exhaustedSinceMs
+          ? this.now() - this.exhaustedSinceMs
+          : 0;
+        lines.push(
+          `✅ GLM 5h quota available again${elapsed > 0 ? ` (was exhausted for ~${formatElapsed(elapsed)})` : ""}. Weekly: ${weeklyPct}%.`,
+        );
+      }
+      if (pct < this.warnPercentage) {
+        // Below the threshold: re-arm the warning for the next window.
+        this.warned.fiveHour = false;
+      } else if (!this.warned.fiveHour) {
+        // At-or-above the threshold but not exhausted: warn once per window
+        // (a dip below the threshold re-arms the warning).
+        this.warned.fiveHour = true;
+        lines.push(`⚠️ GLM 5h quota at ${pct}% — getting close.`);
+      }
     }
-    this.startPoller();
-  }
 
-  /** Starts the poller if not already running. */
-  startPoller() {
-    if (this.pollTimer || !this.enabled || !this.apiKey) return;
-    const apiKey = this.apiKey;
-    const tick = async () => {
-      try {
-        const quota = await fetchQuota(apiKey, {
-          fetchImpl: this.fetchImpl,
-        });
-        const pct = quota.fiveHour?.percentage ?? 0;
-        if (pct < EXHAUSTED_PERCENTAGE && this.wasExhausted) {
-          this.notifyRecovered(quota);
-        }
-      } catch {
-        /* transient — retry on the next tick */
+    // --- weekly bucket ----------------------------------------------------
+    if (weeklyExhausted) {
+      if (!this.exhaustionNotified.weekly) {
+        this.exhaustionNotified.weekly = true;
+        this.warned.weekly = false;
+        lines.push(
+          `⚠️ GLM weekly quota exhausted (100%)${resetSuffix(quota.weekly?.nextResetMs, this.now())}`,
+        );
       }
-    };
-    this.pollTimer = setInterval(() => void tick(), this.pollIntervalMs);
-    if (typeof this.pollTimer.unref === "function") this.pollTimer.unref();
-  }
+    } else if (weeklyPct >= this.warnPercentage && !this.warned.weekly) {
+      this.warned.weekly = true;
+      lines.push(`⚠️ GLM weekly quota at ${weeklyPct}% — getting close.`);
+    } else if (weeklyPct < this.warnPercentage) {
+      this.warned.weekly = false;
+    }
 
-  /** Stops the poller. */
-  stopPoller() {
-    if (this.pollTimer) {
-      clearInterval(this.pollTimer);
-      this.pollTimer = null;
+    if (lines.length > 0) {
+      this.log.log(`pi-lxmf: GLM quota notice: ${lines.join(" | ")}`);
+      this.queueNotice(lines.join("\n"));
     }
   }
 
   /**
-   * Delivers the one-shot recovery notification and stops the poller.
+   * Queues a notice; queued notices are delivered when the bridge is idle
+   * or, during a live owner-triggered run, on `agent_settled` (never
+   * interleaving with a reply mid-run).
    *
-   * @param {{fiveHour?: {percentage: number}|null, weekly?: {percentage: number}|null, level?: string|null}} quota
+   * @param {string} text
+   * @private
    */
-  async notifyRecovered(quota) {
-    if (this.notifiedThisEpisode) return;
-    this.notifiedThisEpisode = true;
-    this.wasExhausted = false;
-    this.stopPoller();
-    const elapsed = this.exhaustedSinceMs
-      ? this.now() - this.exhaustedSinceMs
-      : 0;
-    const weeklyPct = quota.weekly?.percentage;
-    const level = quota.level ? `GLM ${quota.level}` : "GLM";
-    const parts = [`${level} 5h quota available again`];
-    if (elapsed > 0) {
-      parts.push(`(was exhausted for ~${formatElapsed(elapsed)})`);
-    }
-    if (typeof weeklyPct === "number") {
-      parts.push(`Weekly: ${weeklyPct}%`);
-    }
-    try {
-      await this.sendText(this.ownerDestinationHash, parts.join(" "));
-    } catch (e) {
+  queueNotice(text) {
+    this.pendingNotices.push(text);
+    this.flushNotices();
+  }
+
+  /**
+   * Delivers queued notices as one message, when no owner-triggered run
+   * is live. Delivery is best-effort; a failure is logged once.
+   *
+   * @private
+   */
+  flushNotices() {
+    if (this.pendingNotices.length === 0) return;
+    if (this.runActive && this.ownerTriggered) return;
+    const text = this.pendingNotices.join("\n\n");
+    this.pendingNotices = [];
+    this.sendText(this.ownerDestinationHash, text).catch((e) => {
       this.log.error(
         `pi-lxmf: GLM quota notification delivery failed: ${e instanceof Error ? e.message : e}`,
       );
-    }
+    });
   }
 
   /**
@@ -500,6 +590,27 @@ export class GlmQuotaWatcher {
       this.peakOpenTimer = null;
     }
   }
+
+  /** Stops the sampler. */
+  stopPoller() {
+    if (this.pollTimer) {
+      clearInterval(this.pollTimer);
+      this.pollTimer = null;
+    }
+  }
+}
+
+/**
+ * Human-readable "resets in" suffix from a bucket's `nextResetMs`.
+ *
+ * @param {number|undefined} nextResetMs
+ * @param {number} nowMs
+ * @returns {string}
+ */
+function resetSuffix(nextResetMs, nowMs) {
+  if (!nextResetMs || nextResetMs <= nowMs) return "";
+  const ms = nextResetMs - nowMs;
+  return ` — resets in ~${formatElapsed(ms)}`;
 }
 
 /** @param {number} ms */