pi-lxmf 0.1.0 → 0.1.2

package/CHANGELOG.md

@@ -5,6 +5,40 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+## [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
+
+- Startup notification to the owner (work doc #5): once the daemon is
+  fully available (LXMF destination announcing, `pi --mode rpc` ready), it
+  sends `🟢 pi-lxmf ready — listening for messages.` to the configured
+  owner — plus a `Resuming session <file>.` line when a session pointer
+  was resumed. Best-effort: a failed delivery is noted and carried by the
+  next successful reply.
+
 ## [0.1.0] - 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.0",
+  "version": "0.1.2",
   "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),
@@ -210,6 +245,10 @@ async function main() {
   process.on("SIGINT", () => shutdown("SIGINT"));
   process.on("SIGTERM", () => shutdown("SIGTERM"));
 
+  // The daemon is fully available: tell the owner (they may be waiting on
+  // a restart). Delivery failures are noted, not fatal.
+  await bridge.notifyStartup(sessionPointer?.sessionFile ?? null);
+
   // Run until signalled or shut down over LXMF.
   await new Promise(() => {});
 }

package/src/bridge.js

@@ -13,9 +13,11 @@
  * before falling back to a "done (no reply)" nudge.
  */
 
+import { basename, relative } from "node:path";
 import {
   bridgeCommands,
   EMPTY_REPLY_RECOVERY_PROMPT,
+  isUnderWorkdir,
   parseCommand,
 } from "./commands.js";
 import { deriveLxmfDestinationHash } from "./identity.js";
@@ -40,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.
  */
 
 /**
@@ -98,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} */
@@ -159,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";
@@ -496,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);
     }
@@ -517,16 +536,87 @@ 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) || ".";
+    return pointer
+      ? `Switched to ${rel}. Resuming session ${basename(pointer.sessionFile)}.`
+      : `Switched to ${rel}. Fresh session.`;
+  }
+
   /**
    * @returns {string} Title for the first chunk of a reply.
    */
@@ -554,6 +644,23 @@ 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.
+   *
+   * @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}`);
+  }
+
   /**
    * @param {string} reason
    */

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