pi-resume 1.3.2 → 1.4.0

package/extensions/index.ts

@@ -6,9 +6,9 @@
  *                      (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)
+ *   pi --rn          — alias for --r1
  *   /rn / /rp        — step to the next (older) / previous (newer) session
- *                      relative to the current one (by mtime)
+ *                      relative to the current one (by creation time)
  *   /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)
@@ -19,389 +19,20 @@
  * (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.
+ *
+ * Layout: src/* are pure modules (no pi dependency, unit-tested);
+ * src/ext/* glue them to the pi API, one file per concern.
  */
 
-import type {
-  ExtensionAPI,
-  ExtensionContext,
-  ExtensionCommandContext,
-  SessionStartEvent,
-} from "@earendil-works/pi-coding-agent";
-import {
-  statScan,
-  scanPage,
-  readSessionMeta,
-  scanSubagentTrees,
-  deleteSubagentTrees,
-} from "../src/scanner.ts";
-import { formatEntry, truncate, sessionLabel, formatSize } from "../src/format.ts";
-import { loadConfig, saveConfig, clampPage, clampDays } from "../src/config.ts";
-import { getSessionDir } from "../src/session-dir.ts";
-import { rankTarget, navTarget, sortByCreated, 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 = 2;
-
-const ordinal = (n: number): string => {
-  if (n === 1) return "most recent";
-  const suffix = n === 2 ? "nd" : n === 3 ? "rd" : "th";
-  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);
-}
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { registerResumeCommands } from "../src/ext/resume.ts";
+import { registerPicker } from "../src/ext/picker-command.ts";
+import { registerRds } from "../src/ext/rds.ts";
+import { registerStartup } from "../src/ext/startup.ts";
 
 export default function (pi: ExtensionAPI) {
-  // /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, 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) return;
-    if (!ctx.hasUI) {
-      ctx.ui.notify("--r/--rn: session resume needs interactive mode", "error");
-      return;
-    }
-    // session_start only gets a plain ExtensionContext (no switchSession);
-    // dispatch our own slash command so it runs with a command context.
-    // Switching while a provider refresh is in flight aborts it and crashes
-    // pi (uncaught AbortError from the provider), so wait for it to settle.
-    try {
-      await ctx.modelRegistry.refresh();
-    } catch {}
-    pi.sendUserMessage(`/r${rank}`, { expandPromptTemplates: true });
-  });
-
-  // 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 hidden = await hiddenPredicate();
-        // Walk by creation time: resuming bumps mtime, which would reshuffle
-        // an mtime-ordered walk into a ping-pong between two sessions.
-        const { target, pos, total } = await navTarget(sortByCreated(files), currentFile, dir, hidden);
-
-        if (!target) {
-          ctx.ui.notify(edge, "info");
-          return;
-        }
-
-        await switchTo(ctx, target, `Resumed (${pos}/${total})`);
-      },
-    });
-  }
-
-  pi.registerCommand("rds", {
-    description: "Delete subagent session trees for the current project (with confirmation)",
-    handler: async (_args, ctx) => {
-      const sessionDir = sessionDirFor(ctx);
-      const trees = await scanSubagentTrees(sessionDir);
-
-      if (trees.length === 0) {
-        ctx.ui.notify("No subagent sessions to delete for this project", "info");
-        return;
-      }
-
-      const totalRuns = trees.reduce((s, t) => s + t.runs, 0);
-      const totalBytes = trees.reduce((s, t) => s + t.bytes, 0);
-
-      const summary =
-        `Delete ${trees.length} subagent tree${trees.length === 1 ? "" : "s"} ` +
-        `(${totalRuns} run${totalRuns === 1 ? "" : "s"}, ${formatSize(totalBytes)})?`;
-
-      const choice = await ctx.ui.select(summary, [
-        `Delete ${trees.length} tree${trees.length === 1 ? "" : "s"} (${formatSize(totalBytes)})`,
-        "Cancel",
-      ]);
-
-      if (!choice || choice === "Cancel") {
-        ctx.ui.notify("Cancelled — nothing deleted", "info");
-        return;
-      }
-
-      const removed = await deleteSubagentTrees(sessionDir, trees);
-      ctx.ui.notify(
-        `Deleted ${removed}/${trees.length} subagent tree${removed === 1 ? "" : "s"} ` +
-          `(${formatSize(totalBytes)} freed)`,
-        removed === trees.length ? "info" : "error",
-      );
-    },
-  });
-
-  pi.registerCommand("rs", {
-    description: "Smart resume: paginated session picker (last 20, Load more, tier filter)",
-    handler: async (args, ctx) => {
-      const parts = (args || "").trim().split(/\s+/);
-      const cfg = loadConfig();
-
-      // /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);
-
-        if (!key) {
-          ctx.ui.notify(
-            `Current: page ${cfg.pageSize}, days ${cfg.maxDays || "off"} — /rs set page N | /rs set days N`,
-            "info",
-          );
-          return;
-        }
-
-        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;
-        }
-
-        const saveError = saveConfig(cfg);
-        ctx.ui.notify(saveError ?? applied, saveError ? "error" : "info");
-        return;
-      }
-
-      const sessionDir = sessionDirFor(ctx);
-      const currentFile = ctx.sessionManager.getSessionFile() ?? undefined;
-      const onError = scanErrorNotifier(ctx);
-      // The picker SHOWS sessions open in another pi (marked) instead of hiding
-      // them, so the user can see where a "missing" chat went; selecting one is
-      // refused rather than hijacking the other instance's session.
-      const elsewhere = await activeElsewhere();
-
-      let tierIndex = 0;
-      let offset = 0;
-
-      while (true) {
-        const currentDays = DAY_TIERS[tierIndex] ?? 0;
-        const nextTierDays = DAY_TIERS[tierIndex + 1];
-
-        const { entries, total, hasMore } = await scanPage(
-          sessionDir,
-          offset,
-          cfg.pageSize,
-          currentDays > 0 ? currentDays : undefined,
-          currentFile,
-          onError,
-        );
-
-        if (entries.length === 0 && offset === 0) {
-          if (tierIndex < DAY_TIERS.length - 1) {
-            tierIndex++;
-            continue;
-          }
-          ctx.ui.notify("No sessions found", "info");
-          return;
-        }
-
-        const termWidth = process.stdout.columns || 80;
-        const items = buildPickerItems(
-          entries.map((e) => formatEntry(e, termWidth, elsewhere.has(e.file))),
-          {
-            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 = `Sessions ${offset + 1}-${offset + entries.length} of ${total}${filterLabel}`;
-
-        const choice = await ctx.ui.select(rangeLabel, items);
-        const action = resolveChoice(items, choice, entries.length);
-
-        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;
-            if (elsewhere.has(selected.file)) {
-              ctx.ui.notify("That session is open in another pi — not switching", "info");
-              continue;
-            }
-            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;
-          }
-          case "cancel":
-            return;
-        }
-      }
-    },
-  });
+  registerResumeCommands(pi);
+  registerPicker(pi);
+  registerRds(pi);
+  registerStartup(pi);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-resume",
-  "version": "1.3.2",
+  "version": "1.4.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",

package/src/config.ts

@@ -52,3 +52,36 @@ export function saveConfig(cfg: Config): string | undefined {
     return `Failed to save config: ${err instanceof Error ? err.message : String(err)}`;
   }
 }
+
+/**
+ * Apply `/rs set <key> <value>`. Pure: returns the new config + a message, or
+ * an error string for unknown keys / non-numeric values. Out-of-range values
+ * are clamped and the message says so.
+ */
+export function applySetting(
+  cfg: Config,
+  key: string | undefined,
+  rawValue: string | undefined,
+): { cfg: Config; message: string } | { error: true } {
+  const val = parseInt(rawValue ?? "", 10);
+  if (isNaN(val)) return { error: true };
+
+  if (key === "page") {
+    const pageSize = clampPage(val);
+    return {
+      cfg: { ...cfg, pageSize },
+      message: pageSize === val ? `Page size set to ${val}` : `Page size clamped to ${pageSize} (valid: ${MIN_PAGE}-${MAX_PAGE})`,
+    };
+  }
+  if (key === "days") {
+    const maxDays = clampDays(val);
+    const message =
+      maxDays === 0
+        ? "Day filter disabled"
+        : maxDays === val
+          ? `Max days set to ${val}`
+          : `Max days clamped to ${maxDays} (valid: ${MIN_DAYS}-${MAX_DAYS})`;
+    return { cfg: { ...cfg, maxDays }, message };
+  }
+  return { error: true };
+}

package/src/ext/context.ts

@@ -0,0 +1,65 @@
+/**
+ * Shared glue between pi contexts and the pure src/ modules.
+ * Everything that touches ExtensionContext but isn't a command lives here.
+ */
+
+import type { ExtensionContext, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { statScan, readSessionMeta, type StatResult } from "../scanner.ts";
+import { getSessionDir } from "../session-dir.ts";
+import { activeElsewhere } from "../active.ts";
+import { truncate, sessionLabel } from "../format.ts";
+import type { Hidden } from "../nav.ts";
+import { MSG } from "./messages.ts";
+
+export const LABEL_MAX = 50;
+
+export const currentSessionFile = (ctx: ExtensionContext): string | undefined =>
+  ctx.sessionManager.getSessionFile() ?? undefined;
+
+export const sessionDirFor = (ctx: ExtensionContext): string =>
+  getSessionDir(ctx.cwd, currentSessionFile(ctx));
+
+export const notifyError = (ctx: ExtensionContext) => (message: string) => ctx.ui.notify(message, "error");
+
+export interface SessionSet {
+  files: StatResult[];
+  currentFile: string | undefined;
+  /** Sessions open in another live pi process. */
+  elsewhere: Set<string>;
+  /** Hidden-file predicate for the nav walkers (= open elsewhere). */
+  hidden: Hidden<{ file: string }>;
+}
+
+/**
+ * One stat-only scan + active-registry read, shared by every command.
+ * Returns undefined (after notifying) when there is nothing to navigate.
+ */
+export async function loadSessions(ctx: ExtensionContext): Promise<SessionSet | undefined> {
+  const files = await statScan(sessionDirFor(ctx), notifyError(ctx));
+  if (files.length === 0) {
+    ctx.ui.notify(MSG.noSessions, "error");
+    return undefined;
+  }
+  const elsewhere = await activeElsewhere();
+  return {
+    files,
+    currentFile: currentSessionFile(ctx),
+    elsewhere,
+    hidden: async (f) => elsewhere.has(f.file),
+  };
+}
+
+/** Switch to a session file and announce it in the new session. */
+export async function switchTo(
+  ctx: ExtensionCommandContext,
+  target: StatResult,
+  announce: (label: string) => string = MSG.resumed,
+): Promise<{ cancelled: boolean }> {
+  const meta = await readSessionMeta(target.file, target);
+  const label = truncate(sessionLabel(meta), LABEL_MAX);
+  return ctx.switchSession(target.file, {
+    withSession: async (newCtx) => {
+      newCtx.ui.notify(announce(label), "info");
+    },
+  });
+}

package/src/ext/messages.ts

@@ -0,0 +1,31 @@
+/** All user-facing strings in one place. */
+const plural = (n: number, word: string) => `${n} ${word}${n === 1 ? "" : "s"}`;
+
+export const MSG = {
+  noSessions: "No sessions found",
+  noOtherSessions: "No other sessions to resume",
+  onlyN: (n: number) => `Only ${plural(n, "other session")} available`,
+  resumed: (label: string) => `Resumed: ${label}`,
+  resumedAt: (pos: number, total: number, label: string) => `Resumed (${pos}/${total}): ${label}`,
+  atOldest: "Already at the oldest session",
+  atNewest: "Already at the newest session",
+  openElsewhere: "That session is open in another pi — not switching",
+  switchCancelled: "Session switch was cancelled",
+  startupNeedsUI: "--r/--rn: session resume needs interactive mode",
+  movedForks: (n: number) => `Moved ${plural(n, "legacy subagent fork session")} into <parent>/forks/`,
+  rds: {
+    none: "No subagent sessions to delete for this project",
+    confirm: (trees: number, runs: number, size: string) =>
+      `Delete ${plural(trees, "subagent tree")} (${plural(runs, "run")}, ${size})?`,
+    deleteOption: (trees: number, size: string) => `Delete ${plural(trees, "tree")} (${size})`,
+    cancel: "Cancel",
+    cancelled: "Cancelled — nothing deleted",
+    done: (removed: number, total: number, size: string) =>
+      `Deleted ${removed}/${total} subagent tree${removed === 1 ? "" : "s"} (${size} freed)`,
+  },
+  set: {
+    current: (page: number, days: number) =>
+      `Current: page ${page}, days ${days || "off"} — /rs set page N | /rs set days N`,
+    usage: "Usage: /rs set page N (1-50) | /rs set days N (0-30)",
+  },
+} as const;

package/src/ext/picker-command.ts

@@ -0,0 +1,108 @@
+/** /rs — paginated session picker, plus `/rs set` config. */
+
+import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { scanPage } from "../scanner.ts";
+import { formatEntry } from "../format.ts";
+import { loadConfig, saveConfig, applySetting, type Config } from "../config.ts";
+import { buildPickerItems, resolveChoice } from "../picker.ts";
+import { activeElsewhere } from "../active.ts";
+import { currentSessionFile, sessionDirFor, notifyError, switchTo } from "./context.ts";
+import { MSG } from "./messages.ts";
+
+/** Day-filter tiers the picker escalates through: 7d → 14d → all. */
+const DAY_TIERS = [7, 14, 0] as const;
+
+const tierLabel = (days: number) => (days > 0 ? `${days}d` : "all");
+
+function handleSet(ctx: ExtensionCommandContext, cfg: Config, key?: string, value?: string): void {
+  if (!key) {
+    ctx.ui.notify(MSG.set.current(cfg.pageSize, cfg.maxDays), "info");
+    return;
+  }
+  const res = applySetting(cfg, key, value);
+  if ("error" in res) {
+    ctx.ui.notify(MSG.set.usage, "error");
+    return;
+  }
+  const saveError = saveConfig(res.cfg);
+  ctx.ui.notify(saveError ?? res.message, saveError ? "error" : "info");
+}
+
+async function runPicker(ctx: ExtensionCommandContext, cfg: Config): Promise<void> {
+  const sessionDir = sessionDirFor(ctx);
+  const currentFile = currentSessionFile(ctx);
+  const onError = notifyError(ctx);
+  // The picker SHOWS sessions open in another pi (marked) instead of hiding
+  // them, so the user can see where a "missing" chat went; selecting one is
+  // refused rather than hijacking the other instance's session.
+  const elsewhere = await activeElsewhere();
+  const termWidth = process.stdout.columns || 80;
+
+  let tierIndex = 0;
+  let offset = 0;
+
+  while (true) {
+    const days = DAY_TIERS[tierIndex] ?? 0;
+    const nextTier = DAY_TIERS[tierIndex + 1];
+
+    const { entries, total, hasMore } = await scanPage(
+      sessionDir, offset, cfg.pageSize, days > 0 ? days : undefined, currentFile, onError,
+    );
+
+    if (entries.length === 0 && offset === 0) {
+      if (nextTier !== undefined) {
+        tierIndex++;
+        continue;
+      }
+      ctx.ui.notify(MSG.noSessions, "info");
+      return;
+    }
+
+    const items = buildPickerItems(
+      entries.map((e) => formatEntry(e, termWidth, elsewhere.has(e.file))),
+      {
+        remaining: hasMore ? total - offset - entries.length : undefined,
+        nextTierLabel: nextTier !== undefined ? tierLabel(nextTier) : undefined,
+      },
+    );
+
+    const filter = days > 0 ? ` (last ${days}d)` : "";
+    const title = `Sessions ${offset + 1}-${offset + entries.length} of ${total}${filter}`;
+    const action = resolveChoice(items, await ctx.ui.select(title, items), entries.length);
+
+    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;
+        if (elsewhere.has(selected.file)) {
+          ctx.ui.notify(MSG.openElsewhere, "info");
+          continue;
+        }
+        const result = await switchTo(ctx, selected);
+        if (result.cancelled) ctx.ui.notify(MSG.switchCancelled, "info");
+        return;
+      }
+      case "cancel":
+        return;
+    }
+  }
+}
+
+export function registerPicker(pi: ExtensionAPI): void {
+  pi.registerCommand("rs", {
+    description: "Smart resume: paginated session picker (last 20, Load more, tier filter)",
+    handler: async (args, ctx) => {
+      const [sub, key, value] = (args || "").trim().split(/\s+/);
+      const cfg = loadConfig();
+      if (sub === "set") return handleSet(ctx, cfg, key, value);
+      await runPicker(ctx, cfg);
+    },
+  });
+}

package/src/ext/rds.ts

@@ -0,0 +1,34 @@
+/** /rds — delete subagent session trees for the current project. */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { scanSubagentTrees, deleteSubagentTrees } from "../scanner.ts";
+import { formatSize } from "../format.ts";
+import { sessionDirFor } from "./context.ts";
+import { MSG } from "./messages.ts";
+
+export function registerRds(pi: ExtensionAPI): void {
+  pi.registerCommand("rds", {
+    description: "Delete subagent session trees for the current project (with confirmation)",
+    handler: async (_args, ctx) => {
+      const sessionDir = sessionDirFor(ctx);
+      const trees = await scanSubagentTrees(sessionDir);
+      if (trees.length === 0) {
+        ctx.ui.notify(MSG.rds.none, "info");
+        return;
+      }
+
+      const runs = trees.reduce((s, t) => s + t.runs, 0);
+      const size = formatSize(trees.reduce((s, t) => s + t.bytes, 0));
+      const deleteOption = MSG.rds.deleteOption(trees.length, size);
+
+      const choice = await ctx.ui.select(MSG.rds.confirm(trees.length, runs, size), [deleteOption, MSG.rds.cancel]);
+      if (choice !== deleteOption) {
+        ctx.ui.notify(MSG.rds.cancelled, "info");
+        return;
+      }
+
+      const removed = await deleteSubagentTrees(sessionDir, trees);
+      ctx.ui.notify(MSG.rds.done(removed, trees.length, size), removed === trees.length ? "info" : "error");
+    },
+  });
+}

package/src/ext/resume.ts

@@ -0,0 +1,63 @@
+/**
+ * /r1 .. /rN — ranked resume, and /rn //rp — step navigation.
+ * Both are "pick a target from the scanned list, then switchTo()".
+ */
+
+import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { rankTarget, navTarget, sortByCreated } from "../nav.ts";
+import { loadSessions, switchTo } from "./context.ts";
+import { MSG } from "./messages.ts";
+
+/** How many /rN commands (and --rN flags) to register. */
+export const MAX_RANK = 2;
+
+export const ordinal = (n: number): string => {
+  if (n === 1) return "most recent";
+  const suffix = n === 2 ? "nd" : n === 3 ? "rd" : "th";
+  return `${n}${suffix} most recent`;
+};
+
+/** Resume the rank-th most recent session (1 = latest, current excluded). */
+export async function resumeRank(rank: number, ctx: ExtensionCommandContext): Promise<void> {
+  const s = await loadSessions(ctx);
+  if (!s) return;
+
+  const { target, othersCount } = await rankTarget(s.files, s.currentFile, rank, s.hidden);
+  if (!target) {
+    ctx.ui.notify(othersCount === 0 ? MSG.noOtherSessions : MSG.onlyN(othersCount), "info");
+    return;
+  }
+  await switchTo(ctx, target);
+}
+
+/** Step one session older (dir = 1) or newer (dir = -1) than the current. */
+export async function resumeStep(dir: 1 | -1, ctx: ExtensionCommandContext): Promise<void> {
+  const s = await loadSessions(ctx);
+  if (!s) return;
+
+  // Walk by creation time: resuming bumps mtime, which would reshuffle an
+  // mtime-ordered walk into a ping-pong between two sessions.
+  const { target, pos, total } = await navTarget(sortByCreated(s.files), s.currentFile, dir, s.hidden);
+  if (!target) {
+    ctx.ui.notify(dir === 1 ? MSG.atOldest : MSG.atNewest, "info");
+    return;
+  }
+  await switchTo(ctx, target, (label) => MSG.resumedAt(pos, total, label));
+}
+
+export function registerResumeCommands(pi: ExtensionAPI): void {
+  for (let rank = 1; rank <= MAX_RANK; rank++) {
+    pi.registerCommand(`r${rank}`, {
+      description: `Instantly resume the ${ordinal(rank)} session`,
+      handler: async (_args, ctx) => resumeRank(rank, ctx),
+    });
+  }
+  pi.registerCommand("rn", {
+    description: "Resume the next (older) session",
+    handler: async (_args, ctx) => resumeStep(1, ctx),
+  });
+  pi.registerCommand("rp", {
+    description: "Resume the previous (newer) session",
+    handler: async (_args, ctx) => resumeStep(-1, ctx),
+  });
+}

package/src/ext/startup.ts

@@ -0,0 +1,99 @@
+/**
+ * Startup flags (pi --r N / --rN / --rn), active-session registry hooks and
+ * the one-off legacy fork migration.
+ */
+
+import type { ExtensionAPI, ExtensionContext, SessionStartEvent } from "@earendil-works/pi-coding-agent";
+import { statScan } from "../scanner.ts";
+import { parseRankFlag } from "../nav.ts";
+import { markActive, unmarkActive, activeElsewhere } from "../active.ts";
+import { findLegacyForks, migrateLegacyForks } from "../migrate.ts";
+import { currentSessionFile, sessionDirFor } from "./context.ts";
+import { MAX_RANK, ordinal } from "./resume.ts";
+import { MSG } from "./messages.ts";
+
+export type FlagReader = (name: string) => unknown;
+
+/**
+ * Which rank the startup flags ask for: --r N wins, then --r1..--rN, then --rn.
+ * Pure: takes a flag reader so it can be unit-tested without pi.
+ */
+export function resolveStartupRank(
+  getFlag: FlagReader,
+  maxRank = MAX_RANK,
+): { rank: number } | { error: string } | undefined {
+  const parsed = parseRankFlag(getFlag("r"), maxRank);
+  if (parsed) return parsed;
+  for (let rank = 1; rank <= maxRank; rank++) {
+    if (getFlag(`r${rank}`) === true) return { rank };
+  }
+  if (getFlag("rn") === true) return { rank: 1 };
+  return undefined;
+}
+
+/**
+ * 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 files = await statScan(sessionDirFor(ctx));
+  const skip = await activeElsewhere();
+  const current = currentSessionFile(ctx);
+  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(MSG.movedForks(moved), "info");
+}
+
+async function resumeAtStartup(pi: ExtensionAPI, ctx: ExtensionContext): Promise<void> {
+  const wanted = resolveStartupRank((name) => pi.getFlag(name));
+  if (!wanted) return;
+  if ("error" in wanted) {
+    ctx.ui.notify(wanted.error, "error");
+    return;
+  }
+  if (!ctx.hasUI) {
+    ctx.ui.notify(MSG.startupNeedsUI, "error");
+    return;
+  }
+  // session_start only gets a plain ExtensionContext (no switchSession), so
+  // dispatch our own slash command to run with a command context. Switching
+  // while a provider refresh is in flight aborts it and crashes pi (uncaught
+  // AbortError from the provider), so let the refresh finish first.
+  try {
+    await ctx.modelRegistry.refresh();
+  } catch {}
+  pi.sendUserMessage(`/r${wanted.rank}`, { expandPromptTemplates: true });
+}
+
+export function registerStartup(pi: ExtensionAPI): void {
+  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",
+  });
+
+  pi.on("session_start", async (event: SessionStartEvent, ctx) => {
+    // Advertise which session this pi holds so other instances skip it.
+    await markActive(currentSessionFile(ctx));
+    if (event.reason !== "startup") return;
+    void migrateForksInBackground(ctx).catch(() => {});
+    await resumeAtStartup(pi, ctx);
+  });
+
+  // Fires on switch (followed by session_start) and on exit.
+  pi.on("session_shutdown", async () => {
+    await unmarkActive();
+  });
+}