pi-resume 1.0.2 → 1.2.0

package/README.md

@@ -12,7 +12,9 @@ Commands that use `stat()` + lazy partial reads:
 
 | Command | What it does | Speed |
 |---------|-------------|-------|
-| `/r1` … `/r5` | Instantly switch to the N-th most recent session (`/r1` = latest) | <50ms (stat-only) |
+| `/r1` / `/r2` | Instantly switch to the latest / 2nd most recent session | <50ms (stat-only) |
+| `pi --r N` / `--r1` / `--r2` / `--rn` | Startup flag: open pi and immediately resume the N-th most recent session | <50ms (stat-only) |
+| `/rn` / `/rp` | Step to the next (older) / previous (newer) session relative to the current one | <50ms (stat-only) |
 | `/rs` | Paginated picker: last 20, with tier navigation | <200ms first page |
 | `/rds` | Delete subagent session trees for the current project (with confirmation) | — |
 
@@ -24,18 +26,46 @@ pi install npm:pi-fast-resume
 
 ## Commands
 
-### `/r1` … `/r5` — Instant Ranked Resume
+### `/r1` / `/r2` — Instant Ranked Resume
 
 Switch to the N-th most recent session (by mtime) in one step. No picker, no parsing.
 
 - `/r1` — most recent session
 - `/r2` — 2nd most recent
-- … up to `/r5` — 5th most recent
+
+For anything further back use `/rn` / `/rp` — the rank changes every time you
+switch (the current session is excluded), so deep ranks are more confusing
+than stepping.
 
 The current session is always excluded from the ranking, so `/r1` reliably jumps
 to the previous session. If fewer sessions exist than the requested rank, a
 notice is shown and nothing is switched.
 
+### `pi --r N` — Resume at Startup
+
+Start pi and immediately switch to the N-th most recent session (1-2):
+
+```bash
+pi --r1    # open pi in the latest session
+pi --rn    # same (alias for --r1)
+pi --r2    # open pi in the 2nd most recent
+pi --r 2   # same, numeric form
+```
+
+Same ranking as `/r1`/`/r2`. Invalid values show an error and start a normal
+new session. Interactive mode only (ignored with `-p`).
+
+### `/rn` / `/rp` — Step Navigation
+
+Walk the mtime-sorted session list relative to the **current** session:
+
+- `/rn` — next session (one step **older**)
+- `/rp` — previous session (one step **newer**)
+
+Useful after `/r1` lands on the wrong session: keep pressing `/rn` to walk back
+in time instead of recalculating ranks. A `(pos/total)` indicator is shown on
+each switch. At the ends of the list a notice is shown and nothing is switched.
+
 ### `/rs` — Smart Resume
 
 Shows a paginated list of recent sessions:
@@ -50,8 +80,9 @@ Auto-escalates: if 7d is empty, jumps to 14d, then all.
 ### Configuration
 
 ```
-/rs set page 30    # Sessions per page (1-50, default: 20)
-/rs set days 14    # Day filter for first tier (0-30, 0 = no filter, default: 7)
+/rs set            # Show current settings
+/rs set page 30    # Sessions per page (1-50, default: 20; out-of-range values are clamped)
+/rs set days 14    # Day filter for first tier (0-30, 0 = no filter, default: 7; clamped)
 ```
 
 Config is stored in `~/.pi/agent/extensions/pi-fast-resume/config.json`.
@@ -66,11 +97,32 @@ by hundreds of MB.
 `/rds` scans the **current project only**, shows how many trees / runs / MB
 would be freed, asks for **confirmation**, then recursively deletes just those
 subagent tree subdirectories. Your real top-level `*.jsonl` sessions (the ones
-`/r1`…`/r5` and `/rs` list) are never touched.
+`/r1`/`/r2` and `/rs` list) are never touched.
+
+### Sessions open in another pi are skipped
+
+Each pi instance with this extension records its current session file in
+`~/.pi/agent/extensions/pi-fast-resume/active/<pid>.json` (removed on exit;
+dead pids are ignored). `/r1`, `/r2`, `/rn`, `/rp`, `/rs` and `--r` never land
+on a chat you have open in another terminal.
+
+### Legacy subagent forks are tidied up once
+
+pi-subagents < 0.53 stored forked child sessions **loose** in the project
+sessions dir — same filename shape and `parentSession` header as your own
+`/fork`s, so they polluted `/resume` and every navigation command. Since 0.53
+the canonical place is `<parent>/forks/<file>.jsonl`.
+
+On startup this extension moves such files there (detached, in the background,
+one time per file). A file is moved only if it has a `parentSession` header
+**and** contains the delegated-subagent task prompt or a `subagent-*` session
+name; manual `/fork`s are untouched. The current session and sessions open in
+other pi instances are skipped; existing targets are never overwritten. After
+that, nothing needs filtering and every command is stat-only again.
 
 ## How it works
 
-1. **`/r1`…`/r5`**: `readdir` → `stat` each `.jsonl` → sort by mtime → exclude current → `switchSession(others[rank-1])`
+1. **`/r1`/`/r2`**: `readdir` → `stat` each `.jsonl` → sort by mtime → exclude current + open elsewhere → `switchSession(others[rank-1])`
 2. **`/rs`**: Same stat scan, then read only the **first ~50 lines** of each file on the current page to extract session name and first user message
 
 No full file parsing. No `buildSessionInfo()`. No reading message content beyond the first user message.

package/extensions/index.ts

@@ -2,16 +2,31 @@
  * pi-fast-resume — fast session resume without reading all .jsonl files.
  *
  * Commands:
- *   /r1 .. /r5       — instantly switch to the N-th most recent session
- *                      (stat-only; /r1 = latest, /r5 = 5th, current excluded)
+ *   /r1 .. /r2       — instantly switch to the N-th most recent session
+ *                      (stat-only; /r1 = latest, /r2 = 2nd, current excluded)
+ *   pi --r N         — same as /rN but at startup (pi --r 1 = resume latest)
+ *   pi --r1 .. --r2  — boolean form of the same (pi --r1 = resume latest)
+ *   pi --rn          — alias for --r1 (mirrors /rn from a fresh session)
+ *   /rn / /rp        — step to the next (older) / previous (newer) session
+ *                      relative to the current one (by mtime)
  *   /rs              — paginated session picker (last 20, "Load more", tier filter)
  *   /rs set page N   — set page size (1-50)
  *   /rs set days N   — set maxDays filter (0-30, 0 = no limit)
  *   /rds             — delete all subagent session trees for the current project
  *                      (asks for confirmation; top-level sessions untouched)
+ *
+ * All navigation skips sessions currently open in another live pi process
+ * (src/active.ts). At startup, legacy subagent fork sessions left loose by
+ * pi-subagents < 0.53 are moved once into `<parent>/forks/` (src/migrate.ts),
+ * so afterwards nothing needs filtering and every command stays stat-only.
  */
 
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type {
+  ExtensionAPI,
+  ExtensionContext,
+  ExtensionCommandContext,
+  SessionStartEvent,
+} from "@earendil-works/pi-coding-agent";
 import {
   statScan,
   scanPage,
@@ -20,13 +35,17 @@ import {
   deleteSubagentTrees,
 } from "../src/scanner.ts";
 import { formatEntry, truncate, sessionLabel, formatSize } from "../src/format.ts";
-import { loadConfig, saveConfig } from "../src/config.ts";
+import { loadConfig, saveConfig, clampPage, clampDays } from "../src/config.ts";
 import { getSessionDir } from "../src/session-dir.ts";
+import { rankTarget, navTarget, parseRankFlag, type Hidden } from "../src/nav.ts";
+import { buildPickerItems, resolveChoice } from "../src/picker.ts";
+import { markActive, unmarkActive, activeElsewhere } from "../src/active.ts";
+import { findLegacyForks, migrateLegacyForks } from "../src/migrate.ts";
 
 const DAY_TIERS = [7, 14, 0] as const;
 
 // How many ranked instant-resume commands to register: /r1 .. /rN.
-const MAX_RANK = 5;
+const MAX_RANK = 2;
 
 const ordinal = (n: number): string => {
   if (n === 1) return "most recent";
@@ -34,49 +53,183 @@ const ordinal = (n: number): string => {
   return `${n}${suffix} most recent`;
 };
 
+/** Report a scan error to the user (used as statScan/scanPage onError). */
+const scanErrorNotifier = (ctx: ExtensionContext) => (message: string) =>
+  ctx.ui.notify(message, "error");
+
+const sessionDirFor = (ctx: ExtensionContext): string =>
+  getSessionDir(ctx.cwd, ctx.sessionManager.getSessionFile() ?? undefined);
+
+/** Hidden-file predicate: sessions open in another live pi (one readdir). */
+async function hiddenPredicate(): Promise<Hidden<{ file: string }>> {
+  const elsewhere = await activeElsewhere();
+  return async (f) => elsewhere.has(f.file);
+}
+
+/**
+ * Move legacy loose subagent forks into `<parent>/forks/`. Runs detached in
+ * the background at startup; only reports when something actually moved.
+ * Skips the current session and sessions held by other live pi processes.
+ */
+async function migrateForksInBackground(ctx: ExtensionContext): Promise<void> {
+  const sessionDir = sessionDirFor(ctx);
+  const files = await statScan(sessionDir);
+  const skip = await activeElsewhere();
+  const current = ctx.sessionManager.getSessionFile();
+  if (current) skip.add(current);
+  const forks = await findLegacyForks(files, skip);
+  if (forks.length === 0) return;
+  const moved = await migrateLegacyForks(forks);
+  if (moved > 0) {
+    ctx.ui.notify(`Moved ${moved} legacy subagent fork session${moved === 1 ? "" : "s"} into <parent>/forks/`, "info");
+  }
+}
+
+/** Switch to a session file with a "Resumed: <label>" notice. */
+async function switchTo(
+  ctx: ExtensionCommandContext,
+  target: { file: string; mtime: Date; size: number },
+  prefix = "Resumed",
+): Promise<void> {
+  const meta = await readSessionMeta(target.file, target);
+  await ctx.switchSession(target.file, {
+    withSession: async (newCtx) => {
+      newCtx.ui.notify(`${prefix}: ${truncate(sessionLabel(meta), 50)}`, "info");
+    },
+  });
+}
+
+/**
+ * Guard: session switching needs a command-capable interactive context.
+ * session_start receives a plain ExtensionContext; in TUI mode the runtime
+ * context also carries switchSession, in -p/json modes it does not.
+ */
+function asSwitchable(ctx: ExtensionContext): ExtensionCommandContext | undefined {
+  if (typeof (ctx as ExtensionCommandContext).switchSession === "function") {
+    return ctx as ExtensionCommandContext;
+  }
+  ctx.ui.notify("Session resume is only available in interactive mode", "error");
+  return undefined;
+}
+
+/** Resume the rank-th most recent session (1 = latest, current excluded). */
+async function resumeRank(rank: number, baseCtx: ExtensionContext): Promise<void> {
+  const ctx = asSwitchable(baseCtx);
+  if (!ctx) return;
+
+  const files = await statScan(sessionDirFor(ctx), scanErrorNotifier(ctx));
+  if (files.length === 0) {
+    ctx.ui.notify("No sessions found", "error");
+    return;
+  }
+
+  const currentFile = ctx.sessionManager.getSessionFile() ?? undefined;
+  const hidden = await hiddenPredicate();
+  const { target, othersCount } = await rankTarget(files, currentFile, rank, hidden);
+
+  if (!target) {
+    ctx.ui.notify(
+      othersCount === 0
+        ? "No other sessions to resume"
+        : `Only ${othersCount} other session${othersCount === 1 ? "" : "s"} available`,
+      "info",
+    );
+    return;
+  }
+
+  await switchTo(ctx, target);
+}
+
 export default function (pi: ExtensionAPI) {
-  // Register /r1 .. /rN — each jumps to the rank-th most recent session
-  // (by mtime, current session excluded). /r1 = latest, /r2 = 2nd, etc.
+  // /r1 .. /rN — jump to the rank-th most recent session.
   for (let rank = 1; rank <= MAX_RANK; rank++) {
     pi.registerCommand(`r${rank}`, {
       description: `Instantly resume the ${ordinal(rank)} session`,
-      handler: async (_args: string, ctx: any) => {
-        const sessionDir = getSessionDir(ctx.cwd);
-        const files = await statScan(sessionDir);
+      handler: async (_args, ctx) => resumeRank(rank, ctx),
+    });
+  }
+
+  // Startup flags: pi --r N, pi --r1 .. --r2, pi --rn (alias for --r1).
+  pi.registerFlag("r", {
+    description: `Resume the N-th most recent session at startup (1-${MAX_RANK}, 1 = latest)`,
+    type: "string",
+  });
+  for (let rank = 1; rank <= MAX_RANK; rank++) {
+    pi.registerFlag(`r${rank}`, {
+      description: `Resume the ${ordinal(rank)} session at startup`,
+      type: "boolean",
+    });
+  }
+  pi.registerFlag("rn", {
+    description: "Resume the most recent session at startup (alias for --r1)",
+    type: "boolean",
+  });
 
+  /** Resolve requested startup rank from flags, or undefined if none set. */
+  const startupRank = (ctx: ExtensionContext): number | undefined => {
+    const parsed = parseRankFlag(pi.getFlag("r"), MAX_RANK);
+    if (parsed) {
+      if ("error" in parsed) {
+        ctx.ui.notify(parsed.error, "error");
+        return undefined;
+      }
+      return parsed.rank;
+    }
+    for (let rank = 1; rank <= MAX_RANK; rank++) {
+      if (pi.getFlag(`r${rank}`) === true) return rank;
+    }
+    if (pi.getFlag("rn") === true) return 1;
+    return undefined;
+  };
+
+  pi.on("session_start", async (event: SessionStartEvent, ctx) => {
+    // Advertise which session this pi holds so other instances skip it.
+    await markActive(ctx.sessionManager.getSessionFile() ?? undefined);
+    if (event.reason !== "startup") return;
+    void migrateForksInBackground(ctx).catch(() => {});
+    const rank = startupRank(ctx);
+    if (rank !== undefined) await resumeRank(rank, ctx);
+  });
+
+  // Fires on switch (followed by session_start) and on exit.
+  pi.on("session_shutdown", async () => {
+    await unmarkActive();
+  });
+
+  // /rn — step to the next OLDER session; /rp — step to the next NEWER one.
+  const NAV = [
+    { cmd: "rn", dir: 1, desc: "Resume the next (older) session", edge: "Already at the oldest session" },
+    { cmd: "rp", dir: -1, desc: "Resume the previous (newer) session", edge: "Already at the newest session" },
+  ] as const;
+
+  for (const { cmd, dir, desc, edge } of NAV) {
+    pi.registerCommand(cmd, {
+      description: desc,
+      handler: async (_args, ctx) => {
+        const files = await statScan(sessionDirFor(ctx), scanErrorNotifier(ctx));
         if (files.length === 0) {
           ctx.ui.notify("No sessions found", "error");
           return;
         }
 
         const currentFile = ctx.sessionManager.getSessionFile() ?? undefined;
-        const others = files.filter((f: { file: string }) => f.file !== currentFile);
+        const hidden = await hiddenPredicate();
+        const { target, pos, total } = await navTarget(files, currentFile, dir, hidden);
 
-        const target = others[rank - 1];
         if (!target) {
-          ctx.ui.notify(
-            others.length === 0
-              ? "No other sessions to resume"
-              : `Only ${others.length} other session${others.length === 1 ? "" : "s"} available`,
-            "info",
-          );
+          ctx.ui.notify(edge, "info");
           return;
         }
 
-        const meta = await readSessionMeta(target.file, target);
-        await ctx.switchSession(target.file, {
-          withSession: async (newCtx: any) => {
-            newCtx.ui.notify(`Resumed: ${truncate(sessionLabel(meta), 50)}`, "info");
-          },
-        });
+        await switchTo(ctx, target, `Resumed (${pos}/${total})`);
       },
     });
   }
 
   pi.registerCommand("rds", {
     description: "Delete subagent session trees for the current project (with confirmation)",
-    handler: async (_args: string, ctx: any) => {
-      const sessionDir = getSessionDir(ctx.cwd);
+    handler: async (_args, ctx) => {
+      const sessionDir = sessionDirFor(ctx);
       const trees = await scanSubagentTrees(sessionDir);
 
       if (trees.length === 0) {
@@ -112,34 +265,55 @@ export default function (pi: ExtensionAPI) {
 
   pi.registerCommand("rs", {
     description: "Smart resume: paginated session picker (last 20, Load more, tier filter)",
-    handler: async (args: string, ctx: any) => {
+    handler: async (args, ctx) => {
       const parts = (args || "").trim().split(/\s+/);
       const cfg = loadConfig();
 
-      // /rs set page N | /rs set days N
+      // /rs set                → show current config
+      // /rs set page N | days N → update (out-of-range values are clamped)
       if (parts[0] === "set") {
         const key = parts[1];
-        const val = parseInt(parts[2], 10);
+        const val = parseInt(parts[2] ?? "", 10);
 
-        if (key === "page" && !isNaN(val) && val >= 1 && val <= 50) {
-          cfg.pageSize = val;
-          saveConfig(cfg);
-          ctx.ui.notify(`Page size set to ${val}`, "info");
+        if (!key) {
+          ctx.ui.notify(
+            `Current: page ${cfg.pageSize}, days ${cfg.maxDays || "off"} — /rs set page N | /rs set days N`,
+            "info",
+          );
           return;
         }
-        if (key === "days" && !isNaN(val) && val >= 0 && val <= 30) {
-          cfg.maxDays = val;
-          saveConfig(cfg);
-          ctx.ui.notify(val === 0 ? "Day filter disabled" : `Max days set to ${val}`, "info");
+
+        let applied: string | undefined;
+        if (key === "page" && !isNaN(val)) {
+          cfg.pageSize = clampPage(val);
+          applied =
+            cfg.pageSize === val
+              ? `Page size set to ${val}`
+              : `Page size clamped to ${cfg.pageSize} (valid: 1-50)`;
+        } else if (key === "days" && !isNaN(val)) {
+          cfg.maxDays = clampDays(val);
+          applied =
+            cfg.maxDays === 0
+              ? "Day filter disabled"
+              : cfg.maxDays === val
+                ? `Max days set to ${val}`
+                : `Max days clamped to ${cfg.maxDays} (valid: 0-30)`;
+        }
+
+        if (!applied) {
+          ctx.ui.notify("Usage: /rs set page N (1-50) | /rs set days N (0-30)", "error");
           return;
         }
 
-        ctx.ui.notify("Usage: /rs set page N (1-50) | /rs set days N (0-30)", "error");
+        const saveError = saveConfig(cfg);
+        ctx.ui.notify(saveError ?? applied, saveError ? "error" : "info");
         return;
       }
 
-      const sessionDir = getSessionDir(ctx.cwd);
+      const sessionDir = sessionDirFor(ctx);
       const currentFile = ctx.sessionManager.getSessionFile() ?? undefined;
+      const onError = scanErrorNotifier(ctx);
+      const hidden = await hiddenPredicate();
 
       let tierIndex = 0;
       let offset = 0;
@@ -154,6 +328,8 @@ export default function (pi: ExtensionAPI) {
           cfg.pageSize,
           currentDays > 0 ? currentDays : undefined,
           currentFile,
+          onError,
+          hidden,
         );
 
         if (entries.length === 0 && offset === 0) {
@@ -165,58 +341,46 @@ export default function (pi: ExtensionAPI) {
           return;
         }
 
-        const items: string[] = entries.map((e) => formatEntry(e));
-
-        if (hasMore) {
-          const remaining = total - offset - entries.length;
-          items.push(`▼ Load more... (${remaining} remaining)`);
-        }
-
-        if (nextTierDays !== undefined) {
-          const tierLabel = nextTierDays > 0 ? `${nextTierDays}d` : "all";
-          items.push(`▼ Show ${tierLabel}`);
-        }
+        const termWidth = process.stdout.columns || 80;
+        const items = buildPickerItems(
+          entries.map((e) => formatEntry(e, termWidth)),
+          {
+            remaining: hasMore ? total - offset - entries.length : undefined,
+            nextTierLabel:
+              nextTierDays !== undefined ? (nextTierDays > 0 ? `${nextTierDays}d` : "all") : undefined,
+          },
+        );
 
         const filterLabel = currentDays > 0 ? ` (last ${currentDays}d)` : "";
-        const rangeLabel =
-          offset === 0
-            ? `Sessions 1-${entries.length} of ${total}${filterLabel}`
-            : `Sessions ${offset + 1}-${offset + entries.length} of ${total}${filterLabel}`;
+        const rangeLabel = `Sessions ${offset + 1}-${offset + entries.length} of ${total}${filterLabel}`;
 
         const choice = await ctx.ui.select(rangeLabel, items);
+        const action = resolveChoice(items, choice, entries.length);
 
-        if (choice === undefined || choice === null) return;
-
-        const choiceIndex = items.indexOf(choice);
-
-        if (hasMore && choiceIndex === entries.length) {
-          offset += cfg.pageSize;
-          continue;
-        }
-
-        if (choice.startsWith("▼ Show ") && nextTierDays !== undefined) {
-          tierIndex++;
-          offset = 0;
-          continue;
-        }
-
-        if (choiceIndex >= 0 && choiceIndex < entries.length) {
-          const selected = entries[choiceIndex];
-          if (!selected) return;
-
-          const result = await ctx.switchSession(selected.file, {
-            withSession: async (newCtx: any) => {
-              newCtx.ui.notify(`Resumed: ${truncate(sessionLabel(selected), 50)}`, "info");
-            },
-          });
-
-          if (result.cancelled) {
-            ctx.ui.notify("Session switch was cancelled", "info");
+        switch (action.kind) {
+          case "more":
+            offset += cfg.pageSize;
+            continue;
+          case "tier":
+            tierIndex++;
+            offset = 0;
+            continue;
+          case "entry": {
+            const selected = entries[action.index];
+            if (!selected) return;
+            const result = await ctx.switchSession(selected.file, {
+              withSession: async (newCtx) => {
+                newCtx.ui.notify(`Resumed: ${truncate(sessionLabel(selected), 50)}`, "info");
+              },
+            });
+            if (result.cancelled) {
+              ctx.ui.notify("Session switch was cancelled", "info");
+            }
+            return;
           }
-          return;
+          case "cancel":
+            return;
         }
-
-        return;
       }
     },
   });

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-resume",
-  "version": "1.0.2",
-  "description": "Fast session resume for pi coding agent — /r1../r5 ranked instant resume, /rs paginated picker, /rds subagent session cleanup",
+  "version": "1.2.0",
+  "description": "Fast session resume for pi coding agent — /r1,/r2 ranked resume, /rn and /rp step navigation, pi --r1/--rn startup flags, /rs paginated picker, /rds subagent session cleanup; skips sessions open in other pi instances, tidies legacy subagent forks",
   "type": "module",
   "license": "MIT",
   "keywords": [

package/src/active.ts

@@ -0,0 +1,77 @@
+/**
+ * Registry of sessions currently open in live pi processes on this machine.
+ *
+ * Every pi instance that loads this extension writes
+ * `<pi-agent-dir>/extensions/pi-fast-resume/active/<pid>.json` = { file }
+ * on session_start and removes it on session_shutdown. Readers skip records
+ * whose pid is dead (crash / kill -9), so stale files are harmless and are
+ * cleaned up opportunistically.
+ */
+
+import { readdir, readFile, writeFile, mkdir, unlink } from "node:fs/promises";
+import { join } from "node:path";
+import { getPiAgentDir } from "./pi-dir.ts";
+
+const activeDir = (): string => join(getPiAgentDir(), "extensions", "pi-fast-resume", "active");
+const recordPath = (pid: number): string => join(activeDir(), `${pid}.json`);
+
+function pidAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err: any) {
+    // EPERM = exists but not ours; still alive.
+    return err?.code === "EPERM";
+  }
+}
+
+/** Record that this process has `file` open. No-op for unsaved sessions. */
+export async function markActive(file: string | undefined, pid = process.pid): Promise<void> {
+  if (!file) {
+    await unmarkActive(pid);
+    return;
+  }
+  try {
+    await mkdir(activeDir(), { recursive: true });
+    await writeFile(recordPath(pid), JSON.stringify({ file }));
+  } catch {}
+}
+
+/** Remove this process's record (session closed / pi exiting). */
+export async function unmarkActive(pid = process.pid): Promise<void> {
+  try {
+    await unlink(recordPath(pid));
+  } catch {}
+}
+
+/**
+ * Session files held open by OTHER live processes. Stale records (dead pid)
+ * are deleted as a side effect.
+ */
+export async function activeElsewhere(selfPid = process.pid): Promise<Set<string>> {
+  const result = new Set<string>();
+  let names: string[];
+  try {
+    names = await readdir(activeDir());
+  } catch {
+    return result;
+  }
+  await Promise.all(
+    names.map(async (name) => {
+      const pid = parseInt(name, 10);
+      if (!name.endsWith(".json") || isNaN(pid) || pid === selfPid) return;
+      const path = join(activeDir(), name);
+      if (!pidAlive(pid)) {
+        try {
+          await unlink(path);
+        } catch {}
+        return;
+      }
+      try {
+        const rec = JSON.parse(await readFile(path, "utf8"));
+        if (typeof rec?.file === "string") result.add(rec.file);
+      } catch {}
+    }),
+  );
+  return result;
+}

package/src/config.ts

@@ -5,12 +5,9 @@
 
 import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
 import { join } from "node:path";
+import { getPiAgentDir } from "./pi-dir.ts";
 
-const CONFIG_DIR = join(
-  process.env.PI_CODING_AGENT_DIR || join(process.env.HOME || "~", ".pi", "agent"),
-  "extensions",
-  "pi-fast-resume",
-);
+const CONFIG_DIR = join(getPiAgentDir(), "extensions", "pi-fast-resume");
 const CONFIG_PATH = join(CONFIG_DIR, "config.json");
 
 export interface Config {
@@ -45,7 +42,13 @@ export function loadConfig(): Config {
   return { ...DEFAULTS };
 }
 
-export function saveConfig(cfg: Config): void {
-  if (!existsSync(CONFIG_DIR)) mkdirSync(CONFIG_DIR, { recursive: true });
-  writeFileSync(CONFIG_PATH, JSON.stringify(cfg, null, 2) + "\n");
+/** Save config. Returns an error message on failure instead of throwing. */
+export function saveConfig(cfg: Config): string | undefined {
+  try {
+    if (!existsSync(CONFIG_DIR)) mkdirSync(CONFIG_DIR, { recursive: true });
+    writeFileSync(CONFIG_PATH, JSON.stringify(cfg, null, 2) + "\n");
+    return undefined;
+  } catch (err) {
+    return `Failed to save config: ${err instanceof Error ? err.message : String(err)}`;
+  }
 }

package/src/format.ts

@@ -29,6 +29,19 @@ export function sessionLabel(e: SessionEntry): string {
   return e.name || e.firstMessage || e.id || "untitled";
 }
 
-export function formatEntry(e: SessionEntry): string {
-  return `${formatAge(e.mtime).padEnd(10)} ${formatSize(e.size).padEnd(8)} ${truncate(sessionLabel(e), 60)}`;
+/**
+ * Format one picker row, fitting into `maxWidth` columns (terminal width).
+ * Reserves space for the age/size columns and the picker's cursor/indent
+ * so rows never wrap (wrapped rows break selection navigation in the TUI).
+ */
+// Columns the TUI select list draws around each row (cursor arrow, indent,
+// uniquify suffix like " (12)"). Keeping rows shorter than
+// terminal width minus this margin prevents line wrapping, which would
+// break cursor navigation in the picker.
+const PICKER_ROW_MARGIN = 6;
+
+export function formatEntry(e: SessionEntry, maxWidth = 80): string {
+  const prefix = `${formatAge(e.mtime).padEnd(10)} ${formatSize(e.size).padEnd(8)} `;
+  const labelMax = Math.max(10, maxWidth - prefix.length - PICKER_ROW_MARGIN);
+  return prefix + truncate(sessionLabel(e), labelMax);
 }

package/src/migrate.ts

@@ -0,0 +1,128 @@
+/**
+ * One-time migration of legacy subagent fork sessions.
+ *
+ * pi-subagents < 0.53 wrote forked child sessions loose in the project
+ * sessions dir, so they show up in /resume and in every navigation command.
+ * Since 0.53 the canonical location is `<parent-basename>/forks/<file>.jsonl`
+ * (nested under the parent's session tree, invisible to top-level listings,
+ * removed together with the tree by /rds).
+ *
+ * This module finds loose files that (a) carry a `parentSession` header and
+ * (b) contain the delegated-subagent task prompt or a `subagent-*` session
+ * name, and renames them into the canonical location. Manual /fork sessions
+ * have (a) but not (b) and are left alone. After one run there is nothing
+ * left to scan, so navigation stays stat-only.
+ */
+
+import { open, rename, mkdir, access } from "node:fs/promises";
+import { createReadStream } from "node:fs";
+import { join, dirname, basename } from "node:path";
+import type { StatResult } from "./scanner.ts";
+
+const HEAD_BYTES = 2048;
+const TAIL_BYTES = 4096;
+const TASK_MARKER = "You are a delegated subagent";
+const NAME_MARKER = '"name":"subagent-';
+
+async function readSlice(file: string, position: number, length: number): Promise<string> {
+  const fh = await open(file, "r");
+  try {
+    const buf = Buffer.alloc(length);
+    const { bytesRead } = await fh.read(buf, 0, length, position);
+    return buf.subarray(0, bytesRead).toString("utf8");
+  } finally {
+    await fh.close();
+  }
+}
+
+/** Streamed substring search; never buffers the whole file. */
+function streamContains(file: string, marker: string): Promise<boolean> {
+  return new Promise((resolve) => {
+    const stream = createReadStream(file, { encoding: "utf8", highWaterMark: 1 << 20 });
+    let carry = "";
+    const keep = marker.length - 1;
+    stream.on("data", (chunk) => {
+      const text = carry + chunk;
+      if (text.includes(marker)) {
+        stream.destroy();
+        resolve(true);
+        return;
+      }
+      carry = text.slice(-keep);
+    });
+    stream.on("end", () => resolve(false));
+    stream.on("error", () => resolve(false));
+  });
+}
+
+/** Parent session path from the header line, or undefined if not a fork. */
+async function parentOf(ref: StatResult): Promise<string | undefined> {
+  if (ref.size === 0) return undefined;
+  let head: string;
+  try {
+    head = await readSlice(ref.file, 0, Math.min(HEAD_BYTES, ref.size));
+  } catch {
+    return undefined;
+  }
+  const firstLine = head.split("\n", 1)[0] ?? "";
+  if (!firstLine.includes('"parentSession"')) return undefined;
+  try {
+    const parent = JSON.parse(firstLine)?.parentSession;
+    return typeof parent === "string" && parent ? parent : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Is this fork a subagent child (vs. a manual /fork)? */
+async function isSubagentChild(ref: StatResult): Promise<boolean> {
+  try {
+    const len = Math.min(TAIL_BYTES, ref.size);
+    const tail = await readSlice(ref.file, ref.size - len, len);
+    if (tail.includes(NAME_MARKER)) return true;
+  } catch {}
+  return streamContains(ref.file, TASK_MARKER);
+}
+
+export interface LegacyFork {
+  file: string;
+  target: string;
+}
+
+/**
+ * Canonical nested location for a fork: next to the parent's session tree,
+ * inside the child's own sessions dir.
+ */
+export function forkTarget(file: string, parentSession: string): string {
+  return join(dirname(file), basename(parentSession, ".jsonl"), "forks", basename(file));
+}
+
+/** Find loose subagent fork sessions among `files`, skipping `skip` paths. */
+export async function findLegacyForks(files: StatResult[], skip: Set<string> = new Set()): Promise<LegacyFork[]> {
+  const out: LegacyFork[] = [];
+  for (const ref of files) {
+    if (skip.has(ref.file)) continue;
+    const parent = await parentOf(ref);
+    if (!parent) continue;
+    if (!(await isSubagentChild(ref))) continue;
+    out.push({ file: ref.file, target: forkTarget(ref.file, parent) });
+  }
+  return out;
+}
+
+/** Rename each fork into place. Existing targets are never overwritten. Returns moved count. */
+export async function migrateLegacyForks(forks: LegacyFork[]): Promise<number> {
+  let moved = 0;
+  for (const { file, target } of forks) {
+    try {
+      await access(target);
+      continue; // already there — leave both untouched, never clobber
+    } catch {}
+    try {
+      await mkdir(dirname(target), { recursive: true });
+      await rename(file, target);
+      moved++;
+    } catch {}
+  }
+  return moved;
+}

package/src/nav.ts

@@ -0,0 +1,81 @@
+/**
+ * Pure session-navigation logic: ranked resume (/r1../rN, --r) and
+ * step navigation (/rn, /rp). No pi SDK dependency.
+ *
+ * All walkers take an async `hidden` predicate and skip files it rejects.
+ * The predicate is evaluated lazily, only for files actually visited, so a
+ * costly check (e.g. scanning a fork file) is paid per candidate, not per
+ * directory.
+ */
+
+export interface FileRef {
+  file: string;
+}
+
+export type Hidden<T extends FileRef> = (f: T) => Promise<boolean>;
+
+const never = async () => false;
+
+/**
+ * Rank-th most recent visible session, current excluded (rank 1 = latest).
+ * Returns the target or undefined, plus how many visible candidates were seen.
+ */
+export async function rankTarget<T extends FileRef>(
+  files: T[],
+  currentFile: string | undefined,
+  rank: number,
+  hidden: Hidden<T> = never,
+): Promise<{ target?: T; othersCount: number }> {
+  let seen = 0;
+  for (const f of files) {
+    if (f.file === currentFile || (await hidden(f))) continue;
+    seen++;
+    if (seen === rank) return { target: f, othersCount: seen };
+  }
+  return { target: undefined, othersCount: seen };
+}
+
+/**
+ * Step relative to the current session in the mtime-sorted list, skipping
+ * hidden files. dir = 1 → older, dir = -1 → newer. An unsaved current session
+ * (not in the list) is treated as the newest. `pos`/`total` are raw list
+ * indices (1-based) for the on-screen indicator.
+ */
+export async function navTarget<T extends FileRef>(
+  files: T[],
+  currentFile: string | undefined,
+  dir: 1 | -1,
+  hidden: Hidden<T> = never,
+): Promise<{ target?: T; pos: number; total: number }> {
+  const idx = files.findIndex((f) => f.file === currentFile);
+  let i = idx === -1 ? (dir === 1 ? 0 : -1) : idx + dir;
+  while (i >= 0 && i < files.length) {
+    const f = files[i]!;
+    if (!(await hidden(f))) return { target: f, pos: i + 1, total: files.length };
+    i += dir;
+  }
+  return { target: undefined, pos: 0, total: files.length };
+}
+
+/** Keep only visible files (order preserved). */
+export async function filterVisible<T extends FileRef>(files: T[], hidden: Hidden<T>): Promise<T[]> {
+  const out: T[] = [];
+  for (const f of files) if (!(await hidden(f))) out.push(f);
+  return out;
+}
+
+/**
+ * Parse the --r startup flag value.
+ * Returns a rank, an error message, or undefined when the flag is unset.
+ */
+export function parseRankFlag(
+  raw: unknown,
+  maxRank: number,
+): { rank: number } | { error: string } | undefined {
+  if (raw === undefined || raw === null || raw === false) return undefined;
+  const rank = parseInt(String(raw), 10);
+  if (isNaN(rank) || rank < 1 || rank > maxRank) {
+    return { error: `--r expects a number 1-${maxRank} (got "${raw}")` };
+  }
+  return { rank };
+}

package/src/pi-dir.ts

@@ -0,0 +1,11 @@
+/**
+ * Single source of truth for the pi agent base directory.
+ * Mirrors pi's own resolution: $PI_CODING_AGENT_DIR or ~/.pi/agent.
+ */
+
+import { join } from "node:path";
+import { homedir } from "node:os";
+
+export function getPiAgentDir(): string {
+  return process.env.PI_CODING_AGENT_DIR || join(process.env.HOME || homedir(), ".pi", "agent");
+}

package/src/picker.ts

@@ -0,0 +1,58 @@
+/**
+ * Pure picker-menu logic for /rs. No pi SDK dependency.
+ *
+ * ctx.ui.select() returns the chosen STRING, so every menu item must be
+ * unique — otherwise resolving the string back to an index picks the wrong
+ * session (first duplicate wins). uniquify() guarantees uniqueness.
+ */
+
+export const LOAD_MORE_PREFIX = "▼ Load more...";
+export const SHOW_TIER_PREFIX = "▼ Show ";
+
+export type PickerAction =
+  | { kind: "entry"; index: number }
+  | { kind: "more" }
+  | { kind: "tier" }
+  | { kind: "cancel" };
+
+/** Make labels unique by suffixing duplicates with ` (2)`, ` (3)`, … */
+export function uniquify(labels: string[]): string[] {
+  const seen = new Map<string, number>();
+  return labels.map((label) => {
+    const count = (seen.get(label) ?? 0) + 1;
+    seen.set(label, count);
+    return count === 1 ? label : `${label} (${count})`;
+  });
+}
+
+/** Build the full item list: unique entry rows + optional action rows. */
+export function buildPickerItems(
+  entryLabels: string[],
+  opts: { remaining?: number; nextTierLabel?: string } = {},
+): string[] {
+  const items = uniquify(entryLabels);
+  if (opts.remaining !== undefined) {
+    items.push(`${LOAD_MORE_PREFIX} (${opts.remaining} remaining)`);
+  }
+  if (opts.nextTierLabel !== undefined) {
+    items.push(`${SHOW_TIER_PREFIX}${opts.nextTierLabel}`);
+  }
+  return items;
+}
+
+/** Resolve a select() result back to an action. */
+export function resolveChoice(
+  items: string[],
+  choice: string | undefined | null,
+  entryCount: number,
+): PickerAction {
+  if (choice === undefined || choice === null) return { kind: "cancel" };
+
+  const index = items.indexOf(choice);
+  if (index >= 0 && index < entryCount) return { kind: "entry", index };
+
+  if (choice.startsWith(LOAD_MORE_PREFIX)) return { kind: "more" };
+  if (choice.startsWith(SHOW_TIER_PREFIX)) return { kind: "tier" };
+
+  return { kind: "cancel" };
+}

package/src/scanner.ts

@@ -6,7 +6,7 @@
  * - First ~50 lines for header, session_info, first user message
  */
 
-import { readdir, stat, rm } from "node:fs/promises";
+import { readdir, stat, rm, open } from "node:fs/promises";
 import { createReadStream } from "node:fs";
 import { createInterface } from "node:readline";
 import { join } from "node:path";
@@ -31,12 +31,22 @@ export interface StatResult {
 /**
  * Fast stat-only scan: readdir + stat, sorted by mtime desc.
  * No file content is read.
+ *
+ * A missing directory (no sessions yet) returns []. Other readdir errors
+ * (permissions, I/O) are surfaced via onError so callers can distinguish
+ * "no sessions" from "could not read sessions".
  */
-export async function statScan(sessionDir: string): Promise<StatResult[]> {
+export async function statScan(
+  sessionDir: string,
+  onError?: (message: string) => void,
+): Promise<StatResult[]> {
   let entries: string[];
   try {
     entries = await readdir(sessionDir);
-  } catch {
+  } catch (err: any) {
+    if (err?.code !== "ENOENT" && onError) {
+      onError(`Cannot read sessions dir: ${err?.message ?? err}`);
+    }
     return [];
   }
 
@@ -60,9 +70,20 @@ export async function statScan(sessionDir: string): Promise<StatResult[]> {
   return valid;
 }
 
+// Metadata cache keyed by file path, validated by (mtime, size). A session
+// file only changes by appending (mtime+size change), so a hit is always
+// fresh. Keeps /rs "Load more" and repeated opens I/O-free for known files.
+const metaCache = new Map<string, { mtimeMs: number; size: number; entry: SessionEntry }>();
+
+/** Test-only: clear the metadata cache. */
+export function clearMetaCache(): void {
+  metaCache.clear();
+}
+
 /**
  * Read session metadata from first ~50 lines of a .jsonl file.
  * Caller provides mtime/size from prior stat() to avoid double-stat.
+ * Results are cached by (file, mtime, size).
  */
 export async function readSessionMeta(
   filePath: string,
@@ -82,6 +103,12 @@ export async function readSessionMeta(
     } catch {}
   }
 
+  const cached = metaCache.get(filePath);
+  if (cached && cached.mtimeMs === entry.mtime.getTime() && cached.size === entry.size) {
+    // Return a copy with the caller-provided mtime/size (identical anyway).
+    return { ...cached.entry, mtime: entry.mtime, size: entry.size };
+  }
+
   const MAX_LINES = 50;
   let lineCount = 0;
 
@@ -131,9 +158,60 @@ export async function readSessionMeta(
     rl.close();
   } catch {}
 
+  // Session renames APPEND a session_info entry at the end of the file, so
+  // a name found in the tail overrides whatever the head scan saw.
+  const tailName = await readTailName(filePath, entry.size);
+  if (tailName) entry.name = tailName;
+
+  metaCache.set(filePath, { mtimeMs: entry.mtime.getTime(), size: entry.size, entry: { ...entry } });
   return entry;
 }
 
+// How many bytes of the file tail to inspect for a trailing session_info.
+const TAIL_BYTES = 4096;
+
+/**
+ * Read the last TAIL_BYTES of a session file and return the name from the
+ * LAST parseable session_info line, if any. Cheap: one small read.
+ */
+async function readTailName(filePath: string, size: number): Promise<string | undefined> {
+  if (size <= 0) return undefined;
+
+  const readLen = Math.min(TAIL_BYTES, size);
+  const position = size - readLen;
+
+  let text: string;
+  try {
+    const fh = await open(filePath, "r");
+    try {
+      const buf = Buffer.alloc(readLen);
+      const { bytesRead } = await fh.read(buf, 0, readLen, position);
+      text = buf.subarray(0, bytesRead).toString("utf8");
+    } finally {
+      await fh.close();
+    }
+  } catch {
+    return undefined;
+  }
+
+  const lines = text.split("\n");
+  // When reading mid-file, the first line is likely a partial record — skip it.
+  const firstValid = position > 0 ? 1 : 0;
+  for (let i = lines.length - 1; i >= firstValid; i--) {
+    const line = lines[i]?.trim();
+    if (!line) continue;
+    try {
+      const parsed = JSON.parse(line);
+      if (parsed.type === "session_info" && typeof parsed.name === "string" && parsed.name.trim()) {
+        return parsed.name.trim();
+      }
+    } catch {
+      // partial or non-JSON line — keep walking up
+    }
+  }
+  return undefined;
+}
+
 /**
  * Scan a page of sessions with metadata.
  * Pass known mtime/size from statScan to avoid double stat().
@@ -144,8 +222,10 @@ export async function scanPage(
   limit: number,
   maxDays?: number,
   excludeFile?: string,
+  onError?: (message: string) => void,
+  hidden?: (f: StatResult) => Promise<boolean>,
 ): Promise<{ entries: SessionEntry[]; total: number; hasMore: boolean }> {
-  const all = await statScan(sessionDir);
+  const all = await statScan(sessionDir, onError);
 
   let filtered = all;
   if (maxDays && maxDays > 0) {
@@ -157,6 +237,12 @@ export async function scanPage(
     filtered = filtered.filter((f) => f.file !== excludeFile);
   }
 
+  if (hidden) {
+    const kept: StatResult[] = [];
+    for (const f of filtered) if (!(await hidden(f))) kept.push(f);
+    filtered = kept;
+  }
+
   const total = filtered.length;
   const page = filtered.slice(offset, offset + limit);
   const hasMore = offset + limit < total;

package/src/session-dir.ts

@@ -1,15 +1,16 @@
 /**
  * Resolve the pi session directory for a given cwd.
- * Mirrors pi's internal encoding: --<path-with-dashes>--
+ *
+ * Preferred: derive it from the current session file (authoritative —
+ * survives changes to pi's internal path encoding). Fallback: mirror
+ * pi's encoding of cwd → `--<path-with-dashes>--`.
  */
 
-import { join } from "node:path";
+import { join, dirname } from "node:path";
+import { getPiAgentDir } from "./pi-dir.ts";
 
-export function getSessionDir(cwd: string): string {
+export function getSessionDir(cwd: string, currentSessionFile?: string): string {
+  if (currentSessionFile) return dirname(currentSessionFile);
   const resolved = cwd.replace(/^\//, "").replace(/[/\\:]/g, "-");
-  return join(
-    process.env.PI_CODING_AGENT_DIR || join(process.env.HOME || "~", ".pi", "agent"),
-    "sessions",
-    `--${resolved}--`,
-  );
+  return join(getPiAgentDir(), "sessions", `--${resolved}--`);
 }