pi-lxmf 0.1.2 → 0.1.3

package/CHANGELOG.md

@@ -7,6 +7,36 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-lxmf",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "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

@@ -612,9 +612,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");
   }
 
   /**

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