pi-lxmf 0.1.2 → 0.2.0

package/CHANGELOG.md

@@ -7,6 +7,58 @@ 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
+
+- The successful `/cd` reply is now a visually distinct banner (divider
+  line, 📂/🔁/✨ emoji) so project change boundaries are easy to spot when
+  scrolling back through the message history.
+
+### Fixed
+
+- Startup notification lost to the announce race: reticulum-js keeps the
+  destination→identity mapping in memory, so right after a daemon restart
+  the owner's `lxmf.delivery` hash is unknown and the router fails the
+  "🟢 ready" send instantly (its path request only happens once the
+  identity is known). `sendWithRetry` now recognises that failure, sends a
+  path request (which solicits an announce from the peer or a node holding
+  its path) and waits up to 30s for the announce before retrying — instead
+  of burning two hopeless immediate retries and parking the text in the
+  next reply's delivery-failure note.
+- Configured propagation node was never used for outbound: reticulum-js's
+  `lxmf.send` never consults the outbound propagation node on its own
+  (unlike Python's `LXMRouter`), so despite `setOutboundPropagationNode`
+  being called, replies to an off-mesh owner were simply lost. The retry
+  chain now escalates to `submitToPropagationNode` (store-and-forward,
+  delivered on the owner's next sync) after direct and opportunistic
+  delivery both fail — including waiting for the node's own announce on a
+  fresh start. The chain lives in the exported `createRetrySender`
+  (unit-tested against a fake router) instead of a closure inside
+  `startLxmf`.
+
 ## [0.1.2] - 2026-09-27
 
 ### Added

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.2",
+  "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) {
@@ -612,9 +632,16 @@ export class Bridge {
       /* switch reply still goes out; the next prompt re-observes */
     }
     const rel = relative(this.config.workdir, absPath) || ".";
-    return pointer
-      ? `Switched to ${rel}. Resuming session ${basename(pointer.sessionFile)}.`
-      : `Switched to ${rel}. Fresh session.`;
+    // A visually loud banner: project changes are the main boundaries
+    // in the message history, so they must be easy to spot while
+    // scrolling back.
+    const lines = ["📂 ───────────────────", `📂 Switched to ${rel}`];
+    lines.push(
+      pointer
+        ? `🔁 Resuming session ${basename(pointer.sessionFile)}`
+        : "✨ Fresh session",
+    );
+    return lines.join("\n");
   }
 
   /**
@@ -648,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/lxmf.js

@@ -22,6 +22,244 @@ import {
 import { createBz2 } from "./bz2.js";
 import { chunkText } from "./text.js";
 
+/**
+ * The LXMRouter's failure when the destination's identity has not been
+ * learned yet (no announce heard): `send` declines instantly — no link can
+ * be established and opportunistic encryption is impossible without the
+ * recipient's public key.
+ */
+const UNKNOWN_IDENTITY_MESSAGE =
+  /^Cannot deliver: identity for [0-9a-f]+ is unknown$/;
+
+/**
+ * How long {@link waitForPeerIdentity} waits for a solicited announce
+ * before giving up (and `sendWithRetry` falling back to its plain retries).
+ * Generous on purpose: the peer may be several slow mesh hops away, and the
+ * common trigger (the startup notification racing the owner's first
+ * announce after a daemon restart) is worth waiting for — the alternative
+ * parks the message in the bridge's `failedNote` until the *next* reply.
+ */
+const PEER_DISCOVERY_WAIT_MS = 30_000;
+
+/**
+ * Whether `e` is the router's unknown-destination failure — the caller
+ * should solicit the peer (path request + announce) instead of retrying
+ * blind, since the retry cannot succeed until the announce lands.
+ *
+ * @param {unknown} e
+ * @returns {e is Error}
+ */
+export function isUnknownIdentityError(e) {
+  return e instanceof Error && UNKNOWN_IDENTITY_MESSAGE.test(e.message);
+}
+
+/**
+ * Waits until `transport` can recall the identity for `destinationHash`,
+ * soliciting it first: a path request makes the destination itself (or any
+ * transport node holding its path) announce, and the ingested announce
+ * populates the destination→identity mapping. Resolves early once an
+ * announce for the exact destination arrives, `false` on timeout.
+ *
+ * Closes the restart gap the router leaves open: `_establishDirectLink`
+ * only requests-and-awaits a path once the identity is *known*, so an
+ * unknown identity fails the whole `send` without any mesh solicitation.
+ * reticulum-js keeps `knownDestinations` in memory, so every daemon restart
+ * re-enters that state until the owner's next announce.
+ *
+ * @param {any} transport - `rns.transport` (EventTarget with
+ *   `recallIdentity`, `requestPath`; tolerates missing methods for test
+ *   doubles).
+ * @param {Uint8Array} destinationHash
+ * @param {number} timeoutMs
+ * @returns {Promise<boolean>} `true` when the identity is recallable on return.
+ */
+export async function waitForPeerIdentity(
+  transport,
+  destinationHash,
+  timeoutMs,
+) {
+  const destHex = toHex(destinationHash);
+  const recall = () =>
+    Promise.resolve()
+      .then(() => transport?.recallIdentity(destinationHash))
+      .catch(() => null);
+  if (await recall()) return true;
+  try {
+    await transport?.requestPath?.(destinationHash);
+  } catch {
+    /* best effort — a late announce still has the timeout window */
+  }
+  if (await recall()) return true;
+  return new Promise((resolve) => {
+    let settled = false;
+    /** @type {NodeJS.Timeout|null} */
+    let timer = null;
+    const finish = (/** @type {boolean} */ ok) => {
+      if (settled) return;
+      settled = true;
+      if (timer) clearTimeout(timer);
+      transport.removeEventListener("announce", onAnnounce);
+      resolve(ok);
+    };
+    // The transport dispatches "announce" only after `rememberIdentity`
+    // completed, so a matching event implies a recallable identity; the
+    // re-check is belt-and-braces against half-fakes in tests.
+    const onAnnounce = (/** @type {any} */ ev) => {
+      const announced = ev?.detail?.destinationHash;
+      if (!announced || toHex(announced) !== destHex) return;
+      void recall().then((identity) => finish(Boolean(identity)));
+    };
+    timer = setTimeout(() => finish(false), timeoutMs);
+    transport.addEventListener("announce", onAnnounce);
+  });
+}
+
+/**
+ * Builds the outbound retry chain behind `sendText`/`sendReaction`:
+ *
+ * 1. `lxmf.send` over the given link (DIRECT; the router falls back to an
+ *    opportunistic packet internally when no link can be established),
+ * 2. on the router's unknown-identity failure: solicit the destination
+ *    (path request → announce) and wait for its announce — the restart
+ *    race, since reticulum-js keeps the destination→identity map in
+ *    memory and an immediate retry cannot succeed,
+ * 3. retry over the same link, then once more without it (the arrival
+ *    link is usually gone by reply time on battery-conscious clients),
+ * 4. store-and-forward via the configured propagation node — the owner is
+ *    likely off-mesh entirely; their next sync picks the message up.
+ *
+ * The same `LXMessage` object flows through every attempt so all wire
+ * copies share one message id and a deduplicating client renders the
+ * reply once. Factored out of `startLxmf` with injected dependencies so
+ * the chain is testable against a fake router.
+ *
+ * @param {object} deps
+ * @param {LXMRouter} deps.lxmf - Initialised router.
+ * @param {Identity} deps.identity - The node's LXMF identity (signs sends).
+ * @param {string|null} [deps.propagationNodeHex] - Configured propagation
+ *   node's `lxmf.propagation` hash; enables the store-and-forward fallback
+ *   (reticulum-js's `send` never consults the outbound node on its own).
+ * @param {(msg: string) => void} [deps.log] - Diagnostic sink.
+ * @param {number} [deps.peerWaitMs] - Per-peer announce wait (overridable in tests).
+ * @returns {{sendWithRetry: (message: LXMessage, link?: any) => Promise<void>}}
+ */
+export function createRetrySender({
+  lxmf,
+  identity,
+  propagationNodeHex = null,
+  log = () => {},
+  peerWaitMs = PEER_DISCOVERY_WAIT_MS,
+}) {
+  const propagationNodeHash = propagationNodeHex
+    ? fromHex(propagationNodeHex)
+    : null;
+
+  /**
+   * Last-resort store-and-forward through the configured propagation
+   * node, reached from `sendWithRetry` after direct and opportunistic
+   * delivery both failed — typically the owner being off-mesh entirely
+   * (the mobile case). The propagated form is encrypted to the *recipient's*
+   * public key (`dest_hash ‖ E(src‖sig‖payload)`), so it needs their
+   * identity (by then known — the earlier sends failed on reachability,
+   * not identity) but **no live path**: the node holds the message until
+   * the owner's next sync. A node whose announce hasn't been heard yet
+   * (fresh start) is solicited and waited for like unknown recipients are.
+   *
+   * @param {LXMessage} message
+   * @param {Uint8Array} nodeHash - The configured node's `lxmf.propagation`
+   *   hash (callers guarantee it is set).
+   */
+  async function submitViaPropagationNode(message, nodeHash) {
+    const describe = (/** @type {unknown} */ e) =>
+      e instanceof Error ? e.message : String(e);
+    const nodeHex = toHex(nodeHash);
+    try {
+      try {
+        await lxmf.submitToPropagationNode(message, identity);
+      } catch (e) {
+        if (!/Propagation node identity unknown/.test(describe(e))) throw e;
+        log(
+          `pi-lxmf: propagation node ${nodeHex} unknown — requesting path, ` +
+            `waiting up to ${Math.round(peerWaitMs / 1000)}s for its announce`,
+        );
+        const learned = await waitForPeerIdentity(
+          lxmf.rns.transport,
+          nodeHash,
+          peerWaitMs,
+        );
+        if (!learned) throw e;
+        await lxmf.submitToPropagationNode(message, identity);
+      }
+      log(
+        "pi-lxmf: owner unreachable directly — submitted via propagation " +
+          "node (delivered on their next sync)",
+      );
+    } catch (e) {
+      log(`pi-lxmf: propagation submit failed (${describe(e)})`);
+      throw e;
+    }
+  }
+
+  /**
+   * @param {LXMessage} message
+   * @param {any} [link]
+   */
+  async function sendWithRetry(message, link) {
+    try {
+      await lxmf.send(message, identity, link);
+    } catch (e) {
+      log(
+        `pi-lxmf: LXMF send failed (${e instanceof Error ? e.message : e}), retrying once`,
+      );
+      // The destination's identity is unknown (typically: the startup
+      // notification racing the owner's first announce after a restart —
+      // `knownDestinations` is in-memory in reticulum-js, so every restart
+      // forgets it). An immediate retry cannot succeed; solicit the peer
+      // and give its announce time to land first.
+      if (isUnknownIdentityError(e)) {
+        const destHex = toHex(message.destinationHash);
+        log(
+          `pi-lxmf: identity for ${destHex} unknown — requesting path, waiting up to ${Math.round(peerWaitMs / 1000)}s for its announce`,
+        );
+        const learned = await waitForPeerIdentity(
+          lxmf.rns.transport,
+          message.destinationHash,
+          peerWaitMs,
+        );
+        log(
+          learned
+            ? `pi-lxmf: learned ${destHex} — retrying delivery`
+            : `pi-lxmf: no announce from ${destHex} in ${Math.round(peerWaitMs / 1000)}s — retrying anyway`,
+        );
+      }
+      try {
+        await lxmf.send(message, identity, link);
+      } catch (e2) {
+        // The arrival link is likely gone (the peer closed it after its
+        // message was acknowledged). Retry without it: `LXMRouter.send`
+        // then establishes a fresh DIRECT link, falling back to an
+        // opportunistic packet. Same message object → same message id, so
+        // a deduplicating client renders the reply once.
+        log(
+          `pi-lxmf: link retry failed (${e2 instanceof Error ? e2.message : e2}), retrying without link`,
+        );
+        try {
+          await lxmf.send(message, identity, null);
+        } catch (e3) {
+          // Direct and opportunistic both failed: the owner is likely
+          // off-mesh. Store-and-forward via the configured propagation
+          // node instead of losing the reply (their next sync picks it
+          // up); without a configured node the failure stands.
+          if (!propagationNodeHash) throw e3;
+          await submitViaPropagationNode(message, propagationNodeHash);
+        }
+      }
+    }
+  }
+
+  return { sendWithRetry };
+}
+
 /**
  * Attaches diagnostic logging to the inbound LXMF choke points that the
  * bridge itself can't see: packets that decrypt but never dispatch.
@@ -216,10 +454,17 @@ export async function startLxmf(config, options = {}) {
   log(`pi-lxmf: announcing as "${config.name}"`);
 
   // Optional propagation-node integration: outbound submits go through the
-  // node when a direct link cannot be established, and a periodic sync
-  // pulls messages that arrived while this daemon was down.
-  if (config.propagationNode) {
-    lxmf.setOutboundPropagationNode(fromHex(config.propagationNode));
+  // node when neither a direct link nor opportunistic delivery can be
+  // established, and a periodic sync pulls messages that arrived while
+  // this daemon was down. (reticulum-js's `send` never consults the
+  // outbound node on its own — `submitToPropagationNode` is an explicit
+  // call — so the store-and-forward fallback in `sendWithRetry` below is
+  // what makes the config effective.)
+  const propagationNodeHash = config.propagationNode
+    ? fromHex(config.propagationNode)
+    : null;
+  if (propagationNodeHash) {
+    lxmf.setOutboundPropagationNode(propagationNodeHash);
     log(`pi-lxmf: outbound propagation node ${config.propagationNode}`);
   }
   /** @type {NodeJS.Timeout|null} */
@@ -243,15 +488,26 @@ export async function startLxmf(config, options = {}) {
     log(`pi-lxmf: propagation sync every ${config.syncIntervalSec}s`);
   }
 
+  // The outbound retry chain shared by sendText/sendReaction (see
+  // createRetrySender for the escalation order).
+  const { sendWithRetry } = createRetrySender({
+    lxmf,
+    identity,
+    propagationNodeHex: config.propagationNode ?? null,
+    log,
+  });
+
   /**
    * Sends `text` to `destinationHex` (a 32-hex lxmf.delivery source hash),
    * chunked to `chunkChars`, titled on the first chunk. A failed send is
    * retried once over the same path, then once more opportunistically
-   * (without the link) — battery-conscious mobile clients tear their link
-   * down right after their message is acknowledged, so the arrival link can
-   * be gone by reply time; the same `LXMessage` object is re-sent so both
-   * wire copies share one message id and a deduplicating client shows the
-   * reply once (learned in signalk-reticulum's deliverer).
+   * (without the link), and finally submitted to the configured
+   * propagation node for store-and-forward — see {@link createRetrySender}
+   * for the full escalation order. Battery-conscious mobile clients tear
+   * their link down right after their message is acknowledged, so the
+   * arrival link can be gone by reply time; the same `LXMessage` object is
+   * re-sent so all wire copies share one message id and a deduplicating
+   * client shows the reply once (learned in signalk-reticulum's deliverer).
    *
    * @param {string} destinationHex
    * @param {string} text
@@ -312,33 +568,6 @@ export async function startLxmf(config, options = {}) {
     await sendWithRetry(message, sendOptions.link);
   }
 
-  /**
-   * @param {LXMessage} message
-   * @param {any} [link]
-   */
-  async function sendWithRetry(message, link) {
-    try {
-      await lxmf.send(message, identity, link);
-    } catch (e) {
-      log(
-        `pi-lxmf: LXMF send failed (${e instanceof Error ? e.message : e}), retrying once`,
-      );
-      try {
-        await lxmf.send(message, identity, link);
-      } catch (e2) {
-        // The arrival link is likely gone (the peer closed it after its
-        // message was acknowledged). Retry without it: `LXMRouter.send`
-        // then establishes a fresh DIRECT link, falling back to an
-        // opportunistic packet. Same message object → same message id, so
-        // a deduplicating client renders the reply once.
-        log(
-          `pi-lxmf: link retry failed (${e2 instanceof Error ? e2.message : e2}), retrying without link`,
-        );
-        await lxmf.send(message, identity, null);
-      }
-    }
-  }
-
   /**
    * Verifies the signature of an inbound `message` against the sender's
    * recalled identity. The router verifies signatures on the direct-delivery

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 */