pi-lxmf 0.1.1 → 0.1.3

package/CHANGELOG.md

@@ -7,6 +7,57 @@ 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
+
+- Multi-repo support via `/cd` (work doc #2): one bridge can serve every
+  repo under the daemon's start folder. `/cd <path>` switches the
+  supervised Pi at runtime through a deliberate supervised respawn in the
+  new cwd (no backoff, no crash-loop counting; `--model` carried across,
+  the target repo's per-workdir session pointer applied via `--session`, so
+  revisiting a repo resumes its conversation and a new repo starts fresh).
+  Mid-run switches close the open exchange without empty-tail recovery.
+  Boundary: only paths that resolve under the daemon `workdir` — the
+  trust root — are accepted (`..` traversal, outside absolute paths,
+  missing or non-directory targets are refused without touching the child);
+  `resolveCwdTarget` in `src/commands.js` is the single choke point, kept
+  ready for future DACAR per-subtree identity checks. The active cwd is
+  persisted (`dataDir/cwd.json`) and revalidated at startup so restarts
+  resume in the last repo. `/cd` without arguments lists the current and
+  recently used repos (per-workdir session pointers now record their
+  workdir), and `/status` shows the current `cwd` and `workdir`.
+
 ## [0.1.1] - 2026-09-24
 
 ### Added

package/SPEC.md

@@ -123,6 +123,9 @@ agent.
   respawns it after a short backoff, re-applies `--session` from the last
   persisted pointer, and notifies the owner over LXMF. Repeated crashes
   (e.g. 3 within a minute) stop the respawn loop and report to the owner.
+  A `/cd` switch (§6.6) respawns *deliberately* — the old child is killed,
+  the replacement spawned immediately (no backoff, no crash-loop counting)
+  in the new cwd, carrying `--model` and the target repo's session pointer.
 - **Shutdown:** SIGINT/SIGTERM or `/quit` → best-effort `get_state` to
   persist the session pointer, SIGINT to Pi (hard kill after 3 s), stop
   announcing, exit.
@@ -268,7 +271,41 @@ answered with `{"type":"extension_ui_response","id":…,"cancelled":true}`
 and the owner is informed: `⛔ dialog dismissed: <title>`. Fire-and-forget
 UI methods (`notify`, `setStatus`, `setWidget`, …) are ignored.
 
-### 6.5 z.ai GLM quota watcher and peak-hours warning
+### 6.6 Multi-repo: `/cd`
+
+One bridge can serve every repo under the daemon's start folder. `/cd
+<path>` switches the supervised Pi into another directory at runtime — a
+supervised respawn, not an in-process `chdir`: the child is killed (pending
+requests failed, any open exchange closed without empty-tail recovery —
+the killed run never settles), respawned with the new `cwd` (carrying
+`--model`; applying the target repo's per-workdir session pointer via
+`--session`, §8 — so revisiting a repo resumes its conversation and a new
+repo starts fresh), and probed until ready; inbound messages queue during
+the switch. Pi therefore discovers the new repo's `AGENTS.md`/`.pi` and
+re-evaluates project trust exactly as a manual restart would.
+
+**Boundary:** `/cd` accepts only paths that resolve under the daemon's
+`workdir` (the folder `pi-lxmf` was started under — the trust root for
+switchable repos). `..` traversal and absolute paths outside the tree, and
+missing or non-directory targets, are refused without ever touching the
+child. The path resolution in `resolveCwdTarget` (`src/commands.js`) is the
+single choke point — the same check is applied to the persisted active
+cwd at startup — so a future DACAR per-subtree identity check can sit in
+the same place: DACAR's per-folder ACLs may *narrow* which identities may
+enter a given subtree, and the daemon-wide `owner` must not `/cd` past
+such a restriction. When DACAR also brings per-ACL-group LXMF
+identities, `/cd` may evolve from "one child, switch cwd" to a pool of
+children keyed by (identity, repo); the command and its boundary stay
+valid under either model.
+
+The active cwd is persisted (`dataDir/cwd.json`, §8) and revalidated at
+startup (still under `workdir`, still an existing directory — otherwise
+fall back to `workdir`), so a daemon restart resumes in the last repo the
+owner switched into. `/cd` without arguments lists the current repo and
+the recently used ones (derived from the per-workdir session pointers);
+`/status` shows the current `cwd` and `workdir`.
+
+### 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
@@ -303,6 +340,7 @@ in one place so it can be retargeted per subtree.
 | `/status` | model, thinking level, busy state, session name/file, bridge uptime, node identity hashes | no |
 | `/session` | `get_session_stats` — message counts, tokens, cost, context usage | no |
 | `/new` | `new_session`, persist the new session pointer | no |
+| `/cd <path>` | switch the supervised Pi to another repo under `workdir` (supervised respawn, §6.6); without an argument, list the current and recent repos | no |
 | `/name [name]` | `set_session_name`, or show current name | no |
 | `/compact [instructions]` | `compact` (custom instructions appended) | summarizer only |
 | `/model [query]` | no arg: list models (`get_available_models`, current marked); with arg: fuzzy-match `provider/id` or name, then `set_model` | no |
@@ -342,7 +380,8 @@ JSON, `0600`, unknown keys rejected with a warning.
 - `storage/` — Reticulum persistence (identity, known destinations,
   ratchets) via `FileStorageAdapter`.
 - `sessions/<key>.json` — per-workdir Pi session pointers
-  (`{ "sessionFile": … }`), keyed by the first 16 hex chars of
+  (`{ "workdir": …, "sessionFile": … }` — the `workdir` field feeds the
+  `/cd` recent-repos list), keyed by the first 16 hex chars of
   `SHA-256(workdir)` so distinct repos keep distinct sessions (the session
   is the conversation; switching models mid-session keeps the same pointer).
   Written on `new_session`, on graceful shutdown, and whenever
@@ -351,6 +390,9 @@ JSON, `0600`, unknown keys rejected with a warning.
   missing/empty pointer starts a fresh session). One-time migration: a
   pre-scoping legacy `session` file is adopted for the first workdir that
   reads it, then removed, so the adoption runs exactly once.
+- `cwd.json` — the active cwd (`{ "cwd": … }`): the repo the owner last
+  `/cd`'ed into (§6.6). Revalidated at startup against the `workdir`
+  boundary and the filesystem; unusable values fall back to `workdir`.
 
 **Operational note:** Pi's project trust is not prompted for over LXMF.
 Operators run Pi interactively once in `workdir` (or preconfigure trust) so
@@ -462,7 +504,10 @@ an actual mesh is the remaining manual step.
   owner (pi-telegram's "connected companion projection").
 - **DACAR-based permissions** (../dacar): replace the single `owner`
   identity with grants/revocations synced over the mesh, keyed by identity
-  hash as v1 already is.
+  hash as v1 already is. Per-subtree ACLs will narrow which identities may
+  enter a given subtree — the `/cd` boundary (§6.6) is the choke point where
+  that check slots in — and per-ACL-group LXMF identities may turn the
+  single supervised child into a pool keyed by (identity, repo).
 - **Multiple owners.**
 - **`/export` → LXMF attachment** of the rendered HTML session.
 - **Propagation-node role** for the bridge itself, serving its owner's

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-lxmf",
-  "version": "0.1.1",
+  "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/bin.js

@@ -8,11 +8,16 @@
  * signalled or told to quit over LXMF.
  */
 
+import { statSync } from "node:fs";
 import { basename } from "node:path";
 import { Bridge } from "./bridge.js";
+import { isUnderWorkdir } from "./commands.js";
 import {
+  listSessionPointers,
   loadConfig,
+  readActiveCwd,
   readSessionPointer,
+  writeActiveCwd,
   writeSessionPointer,
 } from "./config.js";
 import { deriveLxmfDestinationHash } from "./identity.js";
@@ -99,8 +104,9 @@ function gracefulShutdown(reason, parts) {
     parts.mesh?.stop();
     process.exit(0);
   };
-  // Best effort: persist the current session pointer so the next start
-  // resumes this session.
+  // Best effort: persist the current session pointer (under the repo the
+  // supervised Pi currently runs in — it may have moved via /cd) so the
+  // next start resumes this session.
   const persist =
     parts.bridge && parts.rpc && parts.config
       ? parts.rpc
@@ -109,7 +115,7 @@ function gracefulShutdown(reason, parts) {
             if (state?.sessionFile) {
               writeSessionPointer(
                 parts.config?.dataDir ?? "",
-                parts.config?.workdir ?? "",
+                parts.rpc?.cwd ?? parts.config?.workdir ?? "",
                 state.sessionFile,
               );
             }
@@ -158,7 +164,34 @@ async function main() {
 
   bannerLine("owner (identity)", config.owner);
 
-  const sessionPointer = readSessionPointer(config.dataDir, config.workdir);
+  // The last repo the owner /cd'ed into, if it is still usable: under the
+  // daemon workdir (the trust root) and still an existing directory.
+  // Otherwise fall back to the workdir itself.
+  /** @type {string} */
+  let startCwd = config.workdir;
+  const persistedCwd = readActiveCwd(config.dataDir);
+  if (persistedCwd && persistedCwd !== config.workdir) {
+    let usable = isUnderWorkdir(config.workdir, persistedCwd);
+    if (usable) {
+      try {
+        usable = statSync(persistedCwd).isDirectory();
+      } catch {
+        usable = false;
+      }
+    }
+    if (usable) {
+      startCwd = persistedCwd;
+    } else {
+      console.log(
+        `pi-lxmf: persisted cwd ${persistedCwd} is no longer under workdir — starting in workdir`,
+      );
+    }
+  }
+  if (startCwd !== config.workdir) {
+    bannerLine("cwd", startCwd);
+  }
+
+  const sessionPointer = readSessionPointer(config.dataDir, startCwd);
   if (sessionPointer) {
     bannerLine("resume", basename(sessionPointer.sessionFile));
   }
@@ -173,7 +206,7 @@ async function main() {
   rpc = new PiRpcClient({
     piBin: config.piBin,
     model: config.model,
-    cwd: config.workdir,
+    cwd: startCwd,
     sessionPath: sessionPointer?.sessionFile ?? null,
   });
 
@@ -182,9 +215,11 @@ async function main() {
     rpc,
     mesh,
     state: {
-      loadSession: () => readSessionPointer(config.dataDir, config.workdir),
-      saveSession: (file) =>
-        writeSessionPointer(config.dataDir, config.workdir, file),
+      loadSession: (workdir) => readSessionPointer(config.dataDir, workdir),
+      saveSession: (workdir, file) =>
+        writeSessionPointer(config.dataDir, workdir, file),
+      saveCwd: (cwd) => writeActiveCwd(config.dataDir, cwd),
+      listSessions: () => listSessionPointers(config.dataDir),
     },
     quotaWatcher: new GlmQuotaWatcher({
       ownerDestinationHash: deriveLxmfDestinationHash(config.owner),

package/src/bridge.js

@@ -13,10 +13,11 @@
  * before falling back to a "done (no reply)" nudge.
  */
 
-import { basename } from "node:path";
+import { basename, relative } from "node:path";
 import {
   bridgeCommands,
   EMPTY_REPLY_RECOVERY_PROMPT,
+  isUnderWorkdir,
   parseCommand,
 } from "./commands.js";
 import { deriveLxmfDestinationHash } from "./identity.js";
@@ -41,11 +42,14 @@ const REACTION_DEBOUNCE_MS = 2000;
  */
 
 /**
- * Machine-managed state persistence (session pointer).
+ * Machine-managed state persistence (per-workdir session pointers, the
+ * active cwd).
  *
  * @typedef {object} BridgeState
- * @property {() => {sessionFile: string}|null} loadSession
- * @property {(file: string) => void} saveSession
+ * @property {(workdir: string) => {sessionFile: string}|null} loadSession
+ * @property {(workdir: string, file: string) => void} saveSession
+ * @property {(cwd: string) => void} [saveCwd] - Persist the active cwd (the `/cd` target).
+ * @property {() => Array<{workdir: string|null, sessionFile: string, mtimeMs: number}>} [listSessions] - Per-workdir pointers, recent first.
  */
 
 /**
@@ -99,6 +103,8 @@ export class Bridge {
     this.ownerIdentity = options.config.owner;
     /** The owner's derived lxmf.delivery destination hash (wire form). */
     this.ownerDestinationHash = deriveLxmfDestinationHash(options.config.owner);
+    /** The repo the supervised Pi currently runs in (moves via `/cd`). */
+    this.currentCwd = options.rpc?.cwd || options.config.workdir || null;
     /** @type {string|null} */
     this.sessionName = null;
     /** @type {string|null} */
@@ -160,6 +166,16 @@ export class Bridge {
         `⚠️ pi exited unexpectedly (code ${code ?? "?"} signal ${signal ?? "?"}) — restarting…`,
       );
     });
+    this.rpc.addEventListener("switching", () => {
+      // A `/cd` respawn begins: the old child is about to be killed and its
+      // run will never settle — close any open exchange (without recovery)
+      // and stop considering the client ready until the replacement answers.
+      this.setRpcReady(false);
+      this.clearReaction();
+      this.busy = false;
+      this.exchangeActive = false;
+      this.sentThisExchange = 0;
+    });
     this.rpc.addEventListener("dead", (/** @type {any} */ event) => {
       this.setRpcReady(false);
       const reason = event.detail?.reason ?? "unknown reason";
@@ -497,10 +513,12 @@ export class Bridge {
     const file = state.sessionFile;
     if (typeof file === "string" && file && file !== this.lastSessionFile) {
       this.lastSessionFile = file;
-      try {
-        this.state.saveSession(file);
-      } catch (e) {
-        this.log.error(`pi-lxmf: could not persist session pointer: ${e}`);
+      if (this.currentCwd) {
+        try {
+          this.state.saveSession(this.currentCwd, file);
+        } catch (e) {
+          this.log.error(`pi-lxmf: could not persist session pointer: ${e}`);
+        }
       }
       this.rpc.setSessionPath(file);
     }
@@ -518,16 +536,94 @@ export class Bridge {
   commandContext() {
     return {
       rpc: this.rpc,
+      workdir: this.config.workdir,
+      /** @param {string} absPath */
+      changeWorkdir: (absPath) => this.changeWorkdir(absPath),
+      /** @param {string} msg */
+      log: (msg) => this.log.log(msg),
       getTitle: () => this.replyTitle(),
       getBridgeInfo: () => ({
         identityHash: this.mesh.identityHash,
         deliveryHash: this.mesh.deliveryHash,
         owner: this.ownerIdentity,
         uptimeMs: Date.now() - this.startedAt,
+        workdir: this.config.workdir,
+        cwd: this.currentCwd,
+        recentWorkdirs: this.recentWorkdirs(),
       }),
     };
   }
 
+  /**
+   * Recently used repos under the daemon workdir (most recent first,
+   * excluding the current one), derived from the per-workdir session
+   * pointers. Best-effort: unreadable state lists as empty.
+   *
+   * @returns {string[]}
+   */
+  recentWorkdirs() {
+    if (!this.currentCwd || typeof this.state.listSessions !== "function") {
+      return [];
+    }
+    /** @type {string[]} */
+    const out = [];
+    try {
+      for (const entry of this.state.listSessions()) {
+        if (typeof entry.workdir !== "string") continue;
+        if (entry.workdir === this.currentCwd) continue;
+        if (!isUnderWorkdir(this.config.workdir, entry.workdir)) continue;
+        out.push(entry.workdir);
+      }
+    } catch {
+      return [];
+    }
+    return out;
+  }
+
+  /**
+   * Switches the supervised Pi into another repo under the daemon workdir
+   * (the `/cd` command): resumes the target repo's session pointer (when
+   * one exists — the per-workdir keying of SPEC §8), respawns the child
+   * there via `rpc.setCwd()`, persists the active cwd, and returns the
+   * reply text. `absPath` must already be validated (`resolveCwdTarget`).
+   *
+   * @param {string} absPath - Absolute directory under `config.workdir`.
+   * @returns {Promise<string>} Reply text for the owner.
+   */
+  async changeWorkdir(absPath) {
+    const pointer = this.state.loadSession(absPath);
+    // Session observations from the previous repo are stale: reset before
+    // the respawn so observeState() persists the new session under the
+    // new workdir's key.
+    this.sessionName = null;
+    this.lastSessionFile = pointer?.sessionFile ?? null;
+    this.rpc.setSessionPath(pointer?.sessionFile ?? null);
+    this.currentCwd = absPath;
+    try {
+      this.state.saveCwd?.(absPath);
+    } catch (e) {
+      this.log.error(`pi-lxmf: could not persist active cwd: ${e}`);
+    }
+    await this.rpc.setCwd(absPath);
+    // Observe (and persist) the new repo's session — resumed or fresh.
+    try {
+      this.observeState(await this.rpc.getState());
+    } catch {
+      /* switch reply still goes out; the next prompt re-observes */
+    }
+    const rel = relative(this.config.workdir, absPath) || ".";
+    // 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");
+  }
+
   /**
    * @returns {string} Title for the first chunk of a reply.
    */

package/src/commands.js

@@ -8,9 +8,52 @@
  * text (or a `{ text, shutdown }` action).
  */
 
-import { basename } from "node:path";
+import { statSync } from "node:fs";
+import { basename, relative, resolve, sep } from "node:path";
 import { formatDuration, formatTokens } from "./text.js";
 
+/**
+ * Whether `candidate` is the workdir itself or nested beneath it
+ * (normalized absolute paths). The multi-repo trust boundary: everything
+ * `/cd`-switchable must stay under the daemon's start folder.
+ *
+ * @param {string} workdir - The daemon's configured workdir (trust root).
+ * @param {string} candidate - Absolute path to check.
+ * @returns {boolean}
+ */
+export function isUnderWorkdir(workdir, candidate) {
+  const root = resolve(workdir);
+  const abs = resolve(candidate);
+  return abs === root || abs.startsWith(`${root}${sep}`);
+}
+
+/**
+ * Resolves a `/cd` target to an absolute directory under `workdir` — the
+ * single choke point for the multi-repo boundary (also applied to the
+ * persisted active cwd at daemon startup, so a future DACAR per-subtree
+ * identity check can sit in the same place). `target` is resolved against
+ * `workdir`; anything that escapes the tree (`..` traversal, absolute
+ * paths outside it), does not exist, or is not a directory is refused
+ * with `null`.
+ *
+ * @param {string} workdir - The daemon's configured workdir (trust root).
+ * @param {string} target - User-supplied path (relative to workdir or absolute).
+ * @param {(path: string) => {isDirectory: () => boolean}} [statFn] - Injectable for tests.
+ * @returns {string|null} The validated absolute path, or `null` when refused.
+ */
+export function resolveCwdTarget(workdir, target, statFn = statSync) {
+  const trimmed = (target ?? "").trim();
+  if (!trimmed) return null;
+  const abs = resolve(workdir, trimmed);
+  if (!isUnderWorkdir(workdir, abs)) return null;
+  try {
+    if (!statFn(abs).isDirectory()) return null;
+  } catch {
+    return null;
+  }
+  return abs;
+}
+
 /**
  * Parses bridge-command syntax out of a chat message.
  *
@@ -83,6 +126,8 @@ export function formatModelList(models, current) {
  * @param {string} bridgeInfo.deliveryHash - This node's `lxmf.delivery` destination hash.
  * @param {string|null} bridgeInfo.owner - Paired owner hash.
  * @param {number} bridgeInfo.uptimeMs
+ * @param {string} [bridgeInfo.workdir] - The daemon's configured workdir.
+ * @param {string|null} [bridgeInfo.cwd] - The repo the supervised Pi currently runs in.
  * @returns {string}
  */
 export function formatStatus(state, bridgeInfo) {
@@ -97,6 +142,8 @@ export function formatStatus(state, bridgeInfo) {
     `thinking: ${state?.thinkingLevel ?? "off"}`,
     `busy: ${state?.isStreaming ? "yes" : "no"}`,
     `session: ${session}`,
+    `cwd: ${bridgeInfo.cwd ?? "?"}`,
+    `workdir: ${bridgeInfo.workdir ?? "?"}`,
     `node: ${bridgeInfo.identityHash}`,
     `lxmf: ${bridgeInfo.deliveryHash}`,
     `owner (identity): ${bridgeInfo.owner ?? "?"}`,
@@ -104,6 +151,30 @@ export function formatStatus(state, bridgeInfo) {
   ].join("\n");
 }
 
+/**
+ * Formats the `/cd` (no arguments) reply: the current repo and the
+ * recently used repos under the daemon workdir.
+ *
+ * @param {object} bridgeInfo
+ * @param {string} bridgeInfo.workdir
+ * @param {string|null} [bridgeInfo.cwd]
+ * @param {string[]} [bridgeInfo.recentWorkdirs]
+ * @returns {string}
+ */
+export function formatRepoList(bridgeInfo) {
+  const workdir = bridgeInfo.workdir;
+  const cwd = bridgeInfo.cwd ?? workdir;
+  const lines = [`cwd: ${relative(workdir, cwd) || "."} (${cwd})`];
+  const recent = bridgeInfo.recentWorkdirs ?? [];
+  if (recent.length === 0) {
+    lines.push("recent: (none)");
+  } else {
+    lines.push("recent:");
+    for (const w of recent) lines.push(`  ${relative(workdir, w) || "."}`);
+  }
+  return lines.join("\n");
+}
+
 /**
  * Formats `get_session_stats` data as the `/session` reply.
  *
@@ -123,8 +194,11 @@ export function formatSessionStats(stats) {
 /**
  * @typedef {object} CommandContext
  * @property {import("./rpc.js").PiRpcClient} rpc
+ * @property {string} workdir - The daemon's configured workdir (trust root for `/cd`).
+ * @property {(absPath: string) => Promise<string>} changeWorkdir - Switch the supervised Pi into a validated repo; resolves to the reply text.
  * @property {() => string} getTitle - Reply title (session name or node name).
- * @property {() => {identityHash: string, deliveryHash: string, owner: string, uptimeMs: number}} getBridgeInfo
+ * @property {() => {identityHash: string, deliveryHash: string, owner: string, uptimeMs: number, workdir: string, cwd: string|null, recentWorkdirs: string[]}} getBridgeInfo
+ * @property {(msg: string) => void} [log] - Diagnostic sink for refusals.
  */
 
 /**
@@ -193,6 +267,22 @@ export const bridgeCommands = {
     },
   },
 
+  cd: {
+    description: "Switch repo: /cd <path under workdir>, or list repos",
+    async run(ctx, args) {
+      if (!args) return formatRepoList(ctx.getBridgeInfo());
+      const target = resolveCwdTarget(ctx.workdir, args);
+      if (!target) {
+        ctx.log?.(`pi-lxmf: /cd refused: ${args} not under workdir`);
+        return `⚠️ /cd refused: "${args}" is not a directory under ${ctx.workdir}.`;
+      }
+      if (target === ctx.getBridgeInfo().cwd) {
+        return `Already in ${target}.`;
+      }
+      return ctx.changeWorkdir(target);
+    },
+  },
+
   name: {
     description: "Show or set the session display name",
     async run(ctx, args) {

package/src/config.js

@@ -19,8 +19,10 @@ import { createHash } from "node:crypto";
 import {
   existsSync,
   mkdirSync,
+  readdirSync,
   readFileSync,
   rmSync,
+  statSync,
   writeFileSync,
 } from "node:fs";
 import { homedir } from "node:os";
@@ -368,7 +370,7 @@ export function readSessionPointer(dataDir, workdir) {
   const legacyPath = join(dataDir, LEGACY_SESSION_FILE);
   const legacy = readStateFile(legacyPath);
   if (legacy?.sessionFile && typeof legacy.sessionFile === "string") {
-    writeStateFile(path, { sessionFile: legacy.sessionFile });
+    writeStateFile(path, { workdir, sessionFile: legacy.sessionFile });
     try {
       rmSync(legacyPath, { force: true });
     } catch {
@@ -382,12 +384,82 @@ export function readSessionPointer(dataDir, workdir) {
 /**
  * Persists the Pi session pointer for `workdir` (the JSONL file `pi
  * --session` resumes), keyed by the workdir so distinct repos keep distinct
- * sessions.
+ * sessions. The workdir is stored alongside the pointer so the recently
+ * used repos can be listed for `/cd` (see {@link listSessionPointers}).
  *
  * @param {string} dataDir
  * @param {string} workdir - The resolved workdir the pointer is scoped to.
  * @param {string} sessionFile - Absolute path to the session file.
  */
 export function writeSessionPointer(dataDir, workdir, sessionFile) {
-  writeStateFile(sessionPointerPath(dataDir, workdir), { sessionFile });
+  writeStateFile(sessionPointerPath(dataDir, workdir), {
+    workdir,
+    sessionFile,
+  });
+}
+
+/**
+ * The persisted active cwd (the last repo the owner `/cd`'ed into).
+ */
+const ACTIVE_CWD_FILE = "cwd.json";
+
+/**
+ * Loads the persisted active cwd — the repo a daemon restart should resume
+ * in. Callers must revalidate it against the daemon workdir (still beneath
+ * it, still an existing directory) before use; `isUnderWorkdir` in
+ * `src/commands.js` is the shared boundary check.
+ *
+ * @param {string} dataDir
+ * @returns {string|null}
+ */
+export function readActiveCwd(dataDir) {
+  const state = readStateFile(join(dataDir, ACTIVE_CWD_FILE));
+  return typeof state?.cwd === "string" && state.cwd ? state.cwd : null;
+}
+
+/**
+ * Persists the active cwd so a daemon restart resumes in the last repo the
+ * owner switched into.
+ *
+ * @param {string} dataDir
+ * @param {string} cwd - Absolute path under the daemon workdir.
+ */
+export function writeActiveCwd(dataDir, cwd) {
+  writeStateFile(join(dataDir, ACTIVE_CWD_FILE), { cwd });
+}
+
+/**
+ * Lists the per-workdir session pointers, most recently modified first —
+ * the "recently used repos" shown by `/cd`. Entries written before the
+ * workdir was stored alongside the pointer report `workdir: null`.
+ *
+ * @param {string} dataDir
+ * @returns {Array<{workdir: string|null, sessionFile: string, mtimeMs: number}>}
+ */
+export function listSessionPointers(dataDir) {
+  const dir = join(dataDir, SESSIONS_DIR);
+  if (!existsSync(dir)) return [];
+  /** @type {Array<{workdir: string|null, sessionFile: string, mtimeMs: number}>} */
+  const out = [];
+  for (const entry of readdirSync(dir)) {
+    if (!entry.endsWith(".json")) continue;
+    const path = join(dir, entry);
+    const data = readStateFile(path);
+    if (!data || typeof data.sessionFile !== "string" || !data.sessionFile) {
+      continue;
+    }
+    let mtimeMs = 0;
+    try {
+      mtimeMs = statSync(path).mtimeMs;
+    } catch {
+      /* deleted between readdir and stat: entry is stale anyway */
+    }
+    out.push({
+      workdir: typeof data.workdir === "string" ? data.workdir : null,
+      sessionFile: data.sessionFile,
+      mtimeMs,
+    });
+  }
+  out.sort((a, b) => b.mtimeMs - a.mtimeMs);
+  return out;
 }

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/rpc.js

@@ -112,6 +112,7 @@ export function assistantText(message) {
  * - `"event"`    — `{ detail: event }` for every non-response Pi event.
  * - `"ready"`    — the child is accepting commands (initially and after restarts).
  * - `"restarting"` — `{ detail: { code, signal, attempt } }` unexpected exit; respawn scheduled.
+ * - `"switching"` — `{ detail: { cwd } }` a `setCwd()` respawn starts; the old child is about to be killed.
  * - `"dead"`     — `{ detail: { reason } }` no more respawns will be attempted.
  *
  * @fires PiRpcClient#event
@@ -145,6 +146,8 @@ export class PiRpcClient extends EventTarget {
     this.pending = new Map();
     this.nextId = 0;
     this.stopped = false;
+    /** Set while a `setCwd()` respawn is pending: the old child's exit is expected, not a crash. */
+    this.intentionalRespawn = false;
     /** @type {number[]} */
     this.restartTimestamps = [];
     this.ready = false;
@@ -316,6 +319,16 @@ export class PiRpcClient extends EventTarget {
 
     if (this.stopped) return;
 
+    if (this.intentionalRespawn) {
+      // A setCwd() switch: the exit was expected. Spawn the replacement in
+      // the new cwd immediately — no backoff, no crash-loop counting.
+      this.intentionalRespawn = false;
+      this.log(`pi-lxmf: respawning pi in ${this.cwd} (cwd switch)`);
+      this.spawnChild();
+      this.probeUntilReady();
+      return;
+    }
+
     const now = Date.now();
     this.restartTimestamps = this.restartTimestamps.filter(
       (t) => now - t < 60000,
@@ -395,6 +408,77 @@ export class PiRpcClient extends EventTarget {
     this.sessionPath = path;
   }
 
+  /**
+   * Switches the child's working directory by respawning it — a supervised
+   * restart in the new cwd (the `/cd` path): the current child is killed
+   * (pending requests failed) and the replacement spawned immediately (no
+   * backoff, no crash-loop counting), carrying `--model` and whatever
+   * session path `setSessionPath()` last set. Pi therefore discovers the
+   * new repo's `AGENTS.md`/`.pi` and re-evaluates project trust fresh,
+   * exactly as a manual restart would. Resolves once the replacement
+   * answers commands; rejects on timeout or when restarting is given up.
+   *
+   * @param {string} absPath - Absolute directory to run Pi in.
+   * @param {object} [options]
+   * @param {number} [options.readyTimeoutMs=30000] - Budget for the replacement's first answer.
+   * @returns {Promise<void>}
+   */
+  async setCwd(absPath, options = {}) {
+    if (absPath === this.cwd) return;
+    if (this.stopped) throw new RpcError("PiRpcClient is stopped");
+    const readyTimeoutMs = options.readyTimeoutMs ?? 30000;
+    this.cwd = absPath;
+    if (!this.child && this.firstReady === null) {
+      // Never started: start() picks the new cwd up.
+      return;
+    }
+    this.intentionalRespawn = true;
+    this.dispatchEvent(
+      new CustomEvent("switching", { detail: { cwd: absPath } }),
+    );
+    const switched = new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        cleanup();
+        reject(
+          new RpcError(
+            `pi not ready in ${absPath} within ${readyTimeoutMs} ms`,
+            "setCwd",
+          ),
+        );
+      }, readyTimeoutMs);
+      const onReady = () => {
+        cleanup();
+        resolve(undefined);
+      };
+      const onDead = (/** @type {any} */ e) => {
+        cleanup();
+        reject(
+          new RpcError(
+            `pi in ${absPath} is not recovering: ${e.detail?.reason ?? "unknown reason"}`,
+            "setCwd",
+          ),
+        );
+      };
+      const cleanup = () => {
+        clearTimeout(timer);
+        this.removeEventListener("ready", onReady);
+        this.removeEventListener("dead", onDead);
+      };
+      this.addEventListener("ready", onReady);
+      this.addEventListener("dead", onDead);
+    });
+    if (this.child) {
+      // handleExit() sees the intentional flag and spawns the replacement
+      // as soon as the killed child reports its exit.
+      this.child.kill("SIGTERM");
+    } else {
+      // Between restarts: spawn the replacement directly.
+      this.spawnChild();
+      this.probeUntilReady();
+    }
+    await switched;
+  }
+
   /**
    * Writes one JSON command as a line to pi's stdin.
    *