pi-ui-extension 1.1.11 → 1.2.0

package/README.md

@@ -34,9 +34,18 @@ The `SESSIONS` panel provides quick access to recent sessions:
 - Click a session to switch to it.
 - Rename a non-current session.
 - Delete a non-current session.
-- Use the `⊗` action to remove all other sessions.
+- Use `⊗` to move other unpinned sessions to trash while keeping the current and pinned sessions.
 - Click `SESSIONS ↻` to refresh the session list.
 
+**Advanced Sessions management (v1.2.0+)**: click `≡` on the Sessions header or run `/sessions-manager`.
+
+- Browse all saved sessions for the current project in **8-item pages**, with previous/next navigation and refresh.
+- Search session titles or IDs case-insensitively, and sort by latest update, oldest update, message count, or title.
+- Switch, rename, pin/unpin, or move an individual session to trash. Deletions require confirmation and the active session cannot be deleted.
+- Pinned sessions (`★`) appear first, including in the five-session quick sidebar. Pins persist as IDs (no session content) in `pi-ui-extension/session-pins.json` under Pi's agent directory.
+- Each session row has a quick pin button: `☆` means unpinned and `★` means pinned; clicking it toggles pinning without opening the manager. The existing `✎` rename and `×` delete controls are unchanged. On narrow sidebars, the pin action hides to preserve the existing controls.
+- The `⊗` bulk cleanup now **protects both the active session and all pinned sessions**. Explicit single-session deletion still requires confirmation.
+
 To avoid corrupting active agent state, switching, renaming, deleting, and bulk cleanup are only allowed while Pi is idle. The current session cannot be deleted.
 
 ### 3. Resource shortcuts
@@ -180,7 +189,7 @@ Example configuration:
 To pin a specific version:
 
 ```bash
-pi install npm:pi-ui-extension@1.1.11
+pi install npm:pi-ui-extension@1.2.0
 ```
 
 or:
@@ -188,7 +197,7 @@ or:
 ```json
 {
   "packages": [
-    "npm:pi-ui-extension@1.1.11"
+    "npm:pi-ui-extension@1.2.0"
   ]
 }
 ```
@@ -216,7 +225,7 @@ Configuration form:
 Pin to a Git tag:
 
 ```bash
-pi install git:github.com/1993yihuan/pi-ui-extension@v1.1.11
+pi install git:github.com/1993yihuan/pi-ui-extension@v1.2.0
 ```
 
 ### Temporary local-source testing
@@ -390,12 +399,14 @@ Checkout
 → npm pack --dry-run
 → npm Trusted Publishing (OIDC)
 → npm publish
-→ verify npm Registry visibility (with retries)
+→ verify npm Registry visibility (up to ~10 minutes of retries)
 → GitHub Release
 ```
 
 npm publishing uses GitHub Actions OIDC Trusted Publishing, so no long-lived `NPM_TOKEN` is required in the repository.
 
+Because npm can accept a publication before the new version becomes searchable, the release workflow waits up to approximately 10 minutes for registry indexing. If that verification times out, check the package on npm before retrying: a successful publish cannot be repeated for the same version.
+
 ## Compatibility and design principles
 
 - Does not modify Pi Core.

package/README.zh-CN.md

@@ -34,9 +34,19 @@ Sidebar 支持鼠标交互、滚轮滚动和终端尺寸变化。终端高度不
 - 点击会话切换到对应 Session。
 - 重命名非当前 Session。
 - 删除非当前 Session。
-- 使用右上角 `⊗` 清理除当前 Session 外的其他会话。
+- 使用右上角 `⊗` 清理其他未置顶会话（保留当前和置顶 Session）。
 - 点击 `SESSIONS ↻` 刷新会话列表。
 
+**Sessions 高级管理（v1.2.0 起）**：点击标题右侧的 `≡`，或输入 `/sessions-manager` 打开完整会话管理器。
+
+- 全量浏览当前项目的历史 Session，**每页 8 条**，可向前 / 向后翻页和手动刷新。
+- 按会话标题或 Session ID 搜索（不区分大小写），支持最近更新、最早更新、消息数量和标题排序。
+- 单独查看会话操作：切换、重命名、置顶 / 取消置顶、移到回收站。删除前有确认，当前 Session 不允许删除。
+- 置顶会话始终优先排序，并使用 `★` 标记，优先显示在 Sidebar 的最近 5 条会话中。
+- Sidebar 每条会话右侧新增快捷置顶按钮：`☆` 表示未置顶，`★` 表示已置顶，点击立即切换；与 `✎` 重命名、`×` 删除互不影响。Sidebar 较窄时优先保留原有操作按钮。
+- 置顶 ID 持久保存在 Pi 的 agent 目录下 `pi-ui-extension/session-pins.json`，不保存会话内容。
+- 使用 `⊗` 批量清理时，**保留当前会话及所有置顶会话**；显式删除单条置顶会话仍需确认。
+
 为避免正在执行中的 Agent 状态被破坏，会话切换、重命名、删除和批量清理只会在 Pi 空闲时执行；当前正在使用的 Session 不允许删除。
 
 ### 3. 资源快速查看
@@ -180,7 +190,7 @@ Pi 会安装 package，并将声明写入个人配置：
 如果希望固定版本：
 
 ```bash
-pi install npm:pi-ui-extension@1.1.11
+pi install npm:pi-ui-extension@1.2.0
 ```
 
 或者：
@@ -188,7 +198,7 @@ pi install npm:pi-ui-extension@1.1.11
 ```json
 {
   "packages": [
-    "npm:pi-ui-extension@1.1.11"
+    "npm:pi-ui-extension@1.2.0"
   ]
 }
 ```
@@ -216,7 +226,7 @@ pi install git:github.com/1993yihuan/pi-ui-extension
 固定到 Git tag：
 
 ```bash
-pi install git:github.com/1993yihuan/pi-ui-extension@v1.1.11
+pi install git:github.com/1993yihuan/pi-ui-extension@v1.2.0
 ```
 
 ### 临时加载本地源码
@@ -390,12 +400,14 @@ Checkout
 → npm pack --dry-run
 → npm Trusted Publishing (OIDC)
 → npm publish
-→ 重试检查 npm Registry 已可查询新版本
+→ 重试检查 npm Registry 已可查询新版本（最多约 10 分钟）
 → GitHub Release
 ```
 
 npm 发布使用 GitHub Actions OIDC Trusted Publishing，不需要在 GitHub Repository 中保存长期 `NPM_TOKEN`。
 
+npm 可能先接受发布请求，再经过一段时间才能查询到新版本。Release 工作流会等待最多约 10 分钟让 Registry 完成索引。如果检查超时，请先核对 npm 上的实际版本再决定如何处理，避免对已发布的同一个版本重复执行 `npm publish`。
+
 ## 兼容性与设计原则
 
 - 不修改 Pi Core。

package/extensions/index.ts

@@ -8,6 +8,7 @@ import {
   SettingsManager,
   SessionManager,
   type ExtensionAPI,
+  type ExtensionContext,
 } from "@earendil-works/pi-coding-agent";
 import { installContextEstimates } from "./ctx/data.ts";
 import { createActivityTracker, type ActivityTracker } from "./ctx/activity.ts";
@@ -20,6 +21,7 @@ import {
 import type { ResourceButtonId } from "./session/panel.ts";
 import { installSidebar, type SidebarController } from "./sidebar/index.ts";
 import { deleteSessionFile } from "./session/mutations.ts";
+import { openSessionManager, readSessionPins, sessionsEligibleForClear, sortedSessions, toggleSessionPin } from "./session/manager.ts";
 import type { SessionListItem } from "./session/panel.ts";
 import { installToolViewController } from "./tool-view/controller.ts";
 import type { ToolViewMode } from "./tool-view/types.ts";
@@ -32,6 +34,8 @@ const SESSION_SWITCH_COMMAND = "sidebar-session-switch";
 const SESSION_RENAME_COMMAND = "sidebar-session-rename";
 const SESSION_DELETE_COMMAND = "sidebar-session-delete";
 const SESSION_CLEAR_COMMAND = "sidebar-session-clear-others";
+const SESSION_MANAGER_COMMAND = "sessions-manager";
+const SESSION_PINS_FILE = join(getAgentDir(), "pi-ui-extension", "session-pins.json");
 
 export type ResourceEntry = { name: string; description: string; content?: string };
 
@@ -208,12 +212,8 @@ export async function loadResourceEntries(
  */
 async function clearOtherSessions(
   pi: ExtensionAPI,
-  cwd: string,
-  sessionDir: string,
-  keepId: string,
+  targets: readonly { readonly path: string }[],
 ): Promise<{ readonly deleted: number; readonly failed: number; readonly firstError?: string }> {
-  const sessions = await SessionManager.list(cwd, sessionDir);
-  const targets = sessions.filter((session) => session.id !== keepId);
   let deleted = 0;
   let firstError: string | undefined;
   for (const target of targets) {
@@ -264,6 +264,65 @@ export default async function piUiExtension(pi: ExtensionAPI): Promise<void> {
     }
   };
   let switchRequested = false;
+  let sessionManagerOpen = false;
+  const safeReadPins = (): ReadonlySet<string> => {
+    try { return readSessionPins(SESSION_PINS_FILE); }
+    catch { return new Set(); } // Broken preferences must not hide saved sessions.
+  };
+  const loadSessionRows = async (ctx: ExtensionContext): Promise<readonly SessionListItem[]> => {
+    const currentId = ctx.sessionManager.getSessionId();
+    const pinned = safeReadPins();
+    const sessions = await SessionManager.list(ctx.cwd, ctx.sessionManager.getSessionDir());
+    return sortedSessions(sessions.map((session) => ({
+      id: session.id,
+      title: session.name ?? session.firstMessage,
+      modified: session.modified,
+      messageCount: session.messageCount,
+      current: session.id === currentId,
+      pinned: pinned.has(session.id),
+    })), "recent");
+  };
+  const canManageSessions = (ctx: ExtensionContext): boolean => {
+    if (ctx.isIdle()) return true;
+    ctx.ui.notify("Wait for the current run to finish before managing sessions", "warning");
+    return false;
+  };
+  const selectSession = (ctx: ExtensionContext, session: SessionListItem): void => {
+    if (session.current || switchRequested || !canManageSessions(ctx)) return;
+    switchRequested = true;
+    pi.sendUserMessage(`/${SESSION_SWITCH_COMMAND} ${session.id}`, { expandPromptTemplates: true });
+  };
+  const renameSession = (ctx: ExtensionContext, session: SessionListItem): void => {
+    if (!canManageSessions(ctx)) return;
+    pi.sendUserMessage(`/${SESSION_RENAME_COMMAND} ${session.id}`, { expandPromptTemplates: true });
+  };
+  const deleteSession = (ctx: ExtensionContext, session: SessionListItem): void => {
+    if (session.current) {
+      ctx.ui.notify("Cannot delete the currently active session", "warning");
+      return;
+    }
+    if (!canManageSessions(ctx)) return;
+    pi.sendUserMessage(`/${SESSION_DELETE_COMMAND} ${session.id}`, { expandPromptTemplates: true });
+  };
+  const launchSessionManager = async (ctx: ExtensionContext): Promise<void> => {
+    if (sessionManagerOpen || !canManageSessions(ctx)) return;
+    sessionManagerOpen = true;
+    try {
+      await openSessionManager({
+        ui: ctx.ui,
+        loadSessions: () => loadSessionRows(ctx),
+        togglePin: (id) => toggleSessionPin(SESSION_PINS_FILE, id),
+        onPinChanged: () => refreshSessions(),
+        onSwitch: (session) => selectSession(ctx, session),
+        onRename: (session) => renameSession(ctx, session),
+        onDelete: (session) => deleteSession(ctx, session),
+      });
+    } catch (error) {
+      ctx.ui.notify(`Failed to open Sessions manager: ${error instanceof Error ? error.message : String(error)}`, "error");
+    } finally {
+      sessionManagerOpen = false;
+    }
+  };
   const getMcpServerNames = () => mcpResources.map((server) => server.name);
   const updateMcpStatus = (): void => {
     mcpStatus = buildMcpStatusSnapshot(getAgentDir(), mcpCwd, mcpTrusted, registeredServers, liveMcpServers);
@@ -285,6 +344,11 @@ export default async function piUiExtension(pi: ExtensionAPI): Promise<void> {
     updateMcpStatus();
   });
 
+  pi.registerCommand(SESSION_MANAGER_COMMAND, {
+    description: "Search, sort, page, pin, switch, rename and delete saved sessions",
+    handler: async (_args, ctx) => launchSessionManager(ctx),
+  });
+
   pi.registerCommand(SESSION_RENAME_COMMAND, {
     description: "Rename a saved session selected from the sidebar",
     handler: async (args, ctx) => {
@@ -357,23 +421,24 @@ export default async function piUiExtension(pi: ExtensionAPI): Promise<void> {
   });
 
   pi.registerCommand(SESSION_CLEAR_COMMAND, {
-    description: "Move every saved session except the active one to trash",
+    description: "Move unpinned saved sessions except the active one to trash",
     handler: async (_args, ctx) => {
       try {
         const currentSessionId = ctx.sessionManager.getSessionId();
+        const pinnedIds = readSessionPins(SESSION_PINS_FILE);
         const sessions = await SessionManager.list(ctx.cwd, ctx.sessionManager.getSessionDir());
-        const others = sessions.filter((session) => session.id !== currentSessionId);
+        const others = sessionsEligibleForClear(sessions, currentSessionId, pinnedIds);
         if (others.length === 0) {
-          ctx.ui.notify("No other sessions to clear", "info");
+          ctx.ui.notify("No unpinned sessions to clear", "info");
           return;
         }
         const confirmed = await ctx.ui.confirm(
           "Clear other sessions",
-          `Move ${others.length} other session(s) to trash? The active session is kept.`,
+          `Move ${others.length} unpinned session(s) to trash? The active and pinned sessions are kept.`,
         );
         if (!confirmed) return;
 
-        const result = await clearOtherSessions(pi, ctx.cwd, ctx.sessionManager.getSessionDir(), currentSessionId);
+        const result = await clearOtherSessions(pi, others);
         refreshSessions();
         if (result.failed > 0) {
           ctx.ui.notify(
@@ -541,44 +606,20 @@ export default async function piUiExtension(pi: ExtensionAPI): Promise<void> {
           onSelectToolViewMode: (mode): void => {
             void toolView.setMode(mode, ctx);
           },
-          loadSessions: async (): Promise<readonly SessionListItem[]> => {
-            const currentSessionId = ctx.sessionManager.getSessionId();
-            const sessions = await SessionManager.list(ctx.cwd, ctx.sessionManager.getSessionDir());
-            return sessions.map((session) => ({
-              id: session.id,
-              title: session.name ?? session.firstMessage,
-              modified: session.modified,
-              messageCount: session.messageCount,
-              current: session.id === currentSessionId,
-            }));
-          },
-          onSelectSession: (session): void => {
-            if (session.current || switchRequested) return;
-            if (!ctx.isIdle()) {
-              ctx.ui.notify("Wait for the current run to finish before switching sessions", "warning");
-              return;
-            }
-            switchRequested = true;
-            pi.sendUserMessage(`/${SESSION_SWITCH_COMMAND} ${session.id}`, { expandPromptTemplates: true });
-          },
-          onRenameSession: (session): void => {
-            if (!ctx.isIdle()) {
-              ctx.ui.notify("Wait for the current run to finish before renaming sessions", "warning");
-              return;
-            }
-            pi.sendUserMessage(`/${SESSION_RENAME_COMMAND} ${session.id}`, { expandPromptTemplates: true });
-          },
-          onDeleteSession: (session): void => {
-            if (session.current) {
-              ctx.ui.notify("Cannot delete the currently active session", "warning");
-              return;
-            }
-            if (!ctx.isIdle()) {
-              ctx.ui.notify("Wait for the current run to finish before deleting sessions", "warning");
-              return;
+          loadSessions: () => loadSessionRows(ctx),
+          onSelectSession: (session): void => selectSession(ctx, session),
+          onRenameSession: (session): void => renameSession(ctx, session),
+          onDeleteSession: (session): void => deleteSession(ctx, session),
+          onTogglePinSession: (session): void => {
+            try {
+              const pinned = toggleSessionPin(SESSION_PINS_FILE, session.id);
+              refreshSessions();
+              ctx.ui.notify(pinned ? "会话已置顶" : "已取消置顶", "info");
+            } catch (error) {
+              ctx.ui.notify(`保存置顶失败：${error instanceof Error ? error.message : String(error)}`, "error");
             }
-            pi.sendUserMessage(`/${SESSION_DELETE_COMMAND} ${session.id}`, { expandPromptTemplates: true });
           },
+          onOpenSessionManager: (): void => { void launchSessionManager(ctx); },
           onDeleteOthers: (): void => {
             if (!ctx.isIdle()) {
               ctx.ui.notify("Wait for the current run to finish before clearing sessions", "warning");

package/extensions/session/manager.test.ts

@@ -0,0 +1,141 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync, statSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  getSessionPage, openSessionManager, readSessionPins, sessionsEligibleForClear, sortedSessions, toggleSessionPin,
+  type SessionManagerUI,
+} from "./manager.ts";
+import type { SessionListItem } from "./panel.ts";
+
+function session(id: string, modified: number, title = `Session ${id}`, messages = 1): SessionListItem {
+  return { id, title, modified: new Date(modified), messageCount: messages, current: id === "id-0" };
+}
+
+test("sorting, searching and pagination scale to hundreds of sessions with pinned first", () => {
+  const many = Array.from({ length: 105 }, (_, index) => session(`id-${index}`, index * 1000, `Branch ${index}`, index));
+  many[0] = { ...many[0]!, pinned: true };
+  assert.equal(sortedSessions(many, "recent")[0]!.id, "id-0");
+  assert.deepEqual(getSessionPage(many, "", "recent", 0).items.map((s) => s.id).slice(0, 3),
+    ["id-0", "id-104", "id-103"]);
+  assert.equal(getSessionPage(many, "", "recent", 0).pages, 14);
+  assert.equal(getSessionPage(many, "", "recent", 100).page, 13);
+  assert.equal(getSessionPage(many, "", "recent", -10).page, 0);
+  assert.equal(getSessionPage(many, "BRANCH 1", "recent", 0).total, 16);
+  assert.equal(getSessionPage(many, "id-60", "recent", 0).items[0]!.id, "id-60");
+  assert.equal(getSessionPage(many, "not found", "title", 0).total, 0);
+  assert.equal(sortedSessions(many, "messages")[1]!.id, "id-104");
+  assert.equal(sortedSessions(many, "oldest")[1]!.id, "id-1");
+  assert.equal(sortedSessions(many, "title")[1]!.id, "id-1");
+  assert.deepEqual(sortedSessions([session("b", 0), session("a", 0)], "recent").map((s) => s.id), ["a", "b"]);
+});
+
+test("bulk clear excludes current and pinned sessions", () => {
+  const sessions = [session("current", 0), session("pinned", 1), session("ordinary", 2)];
+  assert.deepEqual(sessionsEligibleForClear(sessions, "current", new Set(["pinned"])).map((s) => s.id), ["ordinary"]);
+});
+
+test("pins persist atomically with private permissions and invalid contents are not overwritten", () => {
+  const root = mkdtempSync(join(tmpdir(), "pi-session-pin-"));
+  const path = join(root, "preferences", "pins.json");
+  try {
+    assert.deepEqual([...readSessionPins(path)], []);
+    assert.equal(toggleSessionPin(path, "some-id"), true);
+    assert.equal(toggleSessionPin(path, "next-id"), true);
+    assert.deepEqual([...readSessionPins(path)], ["some-id", "next-id"]);
+    assert.equal(statSync(path).mode & 0o777, 0o600);
+    assert.equal(toggleSessionPin(path, "some-id"), false);
+    assert.deepEqual([...readSessionPins(path)], ["next-id"]);
+    assert.deepEqual(JSON.parse(readFileSync(path, "utf8")), ["next-id"]);
+    assert.deepEqual(readdirSync(join(root, "preferences")).filter((name) => name.endsWith(".tmp")), []);
+    assert.throws(() => toggleSessionPin(path, "../../oops"), /Invalid session identifier/);
+    writeFileSync(path, "{not-valid}");
+    assert.throws(() => toggleSessionPin(path, "good-id"));
+    assert.equal(readFileSync(path, "utf8"), "{not-valid}");
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+type Choice = (title: string, choices: string[]) => string | undefined;
+function scriptedUI(steps: Choice[]) {
+  const viewed: Array<{ title: string; choices: string[] }> = [];
+  const notices: string[] = [];
+  const ui: SessionManagerUI = {
+    async select(title, choices) {
+      viewed.push({ title, choices });
+      const choose = steps.shift();
+      if (!choose) throw new Error(`Unexpected selector: ${title}`);
+      const choice = choose(title, choices);
+      if (choice !== undefined) assert.ok(choices.includes(choice), `missing option: ${choice}`);
+      return choice;
+    },
+    async input() { return ""; },
+    async confirm() { return true; },
+    notify(message) { notices.push(message); },
+  };
+  return { ui, viewed, notices };
+}
+
+test("manager can navigate pages, pin and unpin, and switch using the selected session", async () => {
+  const root = mkdtempSync(join(tmpdir(), "pi-session-modal-"));
+  const path = join(root, "pins.json");
+  let switched = "";
+  let changes = 0;
+  const all = Array.from({ length: 21 }, (_, index) => session(`id-${index}`, index * 1000));
+  const { ui, viewed, notices } = scriptedUI([
+    (_title, choices) => choices.find((item) => item === "下一页 →"),
+    (_title, choices) => choices.find((item) => item === "下一页 →"),
+    (_title, choices) => choices.find((item) => item.startsWith("1. ")),
+    (_title, choices) => choices.find((item) => item === "置顶会话"),
+    (_title, choices) => choices.find((item) => item.startsWith("1. ★")),
+    (_title, choices) => choices.find((item) => item === "取消置顶"),
+    (_title, choices) => choices.find((item) => item.startsWith("1. ")),
+    (_title, choices) => choices.find((item) => item === "切换到此会话"),
+  ]);
+  try {
+    await openSessionManager({
+      ui,
+      loadSessions: async () => all.map((item) => ({ ...item, pinned: readSessionPins(path).has(item.id) })),
+      togglePin: (id) => toggleSessionPin(path, id),
+      onPinChanged() { changes++; },
+      onSwitch(item) { switched = item.id; },
+      onRename() { throw new Error("unexpected rename"); },
+      onDelete() { throw new Error("unexpected delete"); },
+    });
+    assert.equal(changes, 2);
+    assert.ok(switched.length > 0);
+    assert.deepEqual([...readSessionPins(path)], []);
+    assert.match(viewed[2]!.title, /3\/3/);
+    assert.match(viewed[4]!.choices[0]!, /★/);
+    assert.deepEqual(notices, ["会话已置顶", "已取消置顶"]);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("manager searches, sorts, and requires confirmation to delete noncurrent sessions", async () => {
+  const names = [session("a", 1, "alpha"), session("b", 2, "Beta"), session("c", 3, "gamma")];
+  const { ui, viewed } = scriptedUI([
+    (_title, choices) => choices.find((item) => item.startsWith("⌕ ")), // Search
+    (_title, choices) => choices.find((item) => item.startsWith("↕ ")), // Sort
+    (_title, choices) => choices.find((item) => item.includes("会话标题")),
+    (_title, choices) => choices.find((value) => value.startsWith("1. ")),
+    (_title, choices) => choices.find((value) => value === "移到回收站"),
+  ]);
+  let confirmed = false;
+  let deleted = "";
+  ui.input = async () => "BETA";
+  ui.confirm = async () => { confirmed = true; return true; };
+  await openSessionManager({
+    ui, loadSessions: async () => names,
+    togglePin: () => false, onPinChanged() {},
+    onSwitch() {}, onRename() {},
+    onDelete(item) { deleted = item.id; },
+  });
+  assert.equal(confirmed, true);
+  assert.equal(deleted, "b");
+  assert.match(viewed[3]!.title, /1\/3/);
+  assert.ok(!viewed[3]!.choices.some((value) => value.includes("gamma")));
+});

package/extensions/session/manager.ts

@@ -0,0 +1,183 @@
+import { mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { stripTerminalSequences, truncateToWidth } from "@earendil-works/pi-tui";
+import type { SessionListItem } from "./panel.ts";
+
+export type SessionSort = "recent" | "oldest" | "messages" | "title";
+export const SESSION_PAGE_SIZE = 8;
+
+/** Store only opaque session ids; session contents and titles never leave Pi. */
+export function readSessionPins(path: string): ReadonlySet<string> {
+  let text: string;
+  try {
+    text = readFileSync(path, "utf8");
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return new Set();
+    throw error;
+  }
+  if (text.length > 128_000) throw new Error("Session pins file is too large");
+  const parsed: unknown = JSON.parse(text);
+  if (!Array.isArray(parsed) || parsed.length > 2000 ||
+      !parsed.every((id) => typeof id === "string" && /^[a-zA-Z0-9._-]{1,128}$/.test(id))) {
+    throw new Error("Invalid session pins file");
+  }
+  return new Set(parsed as string[]);
+}
+
+/** Atomic, user-private persistence. Never write back a corrupt pins file. */
+export function toggleSessionPin(path: string, id: string): boolean {
+  if (!/^[a-zA-Z0-9._-]{1,128}$/.test(id)) throw new Error("Invalid session identifier");
+  const pins = new Set(readSessionPins(path));
+  const pinned = !pins.has(id);
+  if (pinned) pins.add(id);
+  else pins.delete(id);
+  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+  const temporary = `${path}.${process.pid}.${Date.now()}.tmp`;
+  try {
+    writeFileSync(temporary, JSON.stringify([...pins]), { encoding: "utf8", mode: 0o600 });
+    renameSync(temporary, path);
+  } finally {
+    rmSync(temporary, { force: true });
+  }
+  return pinned;
+}
+
+export function sortedSessions(sessions: readonly SessionListItem[], sort: SessionSort): SessionListItem[] {
+  return [...sessions].sort((a, b) => {
+    if (Boolean(a.pinned) !== Boolean(b.pinned)) return a.pinned ? -1 : 1;
+    const diff = sort === "recent" ? b.modified.getTime() - a.modified.getTime()
+      : sort === "oldest" ? a.modified.getTime() - b.modified.getTime()
+        : sort === "messages" ? b.messageCount - a.messageCount
+          : a.title.localeCompare(b.title);
+    return (Number.isFinite(diff) ? diff : 0) || a.id.localeCompare(b.id);
+  });
+}
+
+/** Pinned and active sessions are protected from the bulk-clear operation. */
+export function sessionsEligibleForClear<T extends { readonly id: string }>(
+  sessions: readonly T[], activeId: string, pins: ReadonlySet<string>,
+): T[] {
+  return sessions.filter((session) => session.id !== activeId && !pins.has(session.id));
+}
+
+export function getSessionPage(
+  sessions: readonly SessionListItem[], query: string, sort: SessionSort, requestedPage: number,
+  pageSize = SESSION_PAGE_SIZE,
+): { readonly items: readonly SessionListItem[]; readonly total: number; readonly page: number; readonly pages: number } {
+  const q = query.trim().toLocaleLowerCase();
+  const filtered = sortedSessions(sessions.filter((session) =>
+    !q || session.title.toLocaleLowerCase().includes(q) || session.id.toLocaleLowerCase().includes(q),
+  ), sort);
+  const pages = Math.max(1, Math.ceil(filtered.length / Math.max(1, pageSize)));
+  const page = Math.max(0, Math.min(Number.isFinite(requestedPage) ? Math.floor(requestedPage) : 0, pages - 1));
+  return {
+    items: filtered.slice(page * pageSize, (page + 1) * pageSize),
+    total: filtered.length, page, pages,
+  };
+}
+
+export type SessionManagerUI = {
+  select(title: string, choices: string[]): Promise<string | undefined>;
+  input(title: string, placeholder?: string): Promise<string | undefined>;
+  confirm(title: string, message: string): Promise<boolean>;
+  notify(message: string, level: "info" | "warning" | "error"): void;
+};
+
+export type SessionManagerOptions = {
+  readonly ui: SessionManagerUI;
+  readonly loadSessions: () => Promise<readonly SessionListItem[]>;
+  readonly togglePin: (id: string) => boolean;
+  readonly onPinChanged: () => void;
+  readonly onSwitch: (session: SessionListItem) => void;
+  readonly onRename: (session: SessionListItem) => void;
+  readonly onDelete: (session: SessionListItem) => void;
+};
+
+const SORT_CHOICES: ReadonlyArray<{ sort: SessionSort; label: string }> = [
+  { sort: "recent", label: "最近更新" },
+  { sort: "oldest", label: "最早更新" },
+  { sort: "messages", label: "消息数量" },
+  { sort: "title", label: "会话标题" },
+];
+
+function safeLabel(title: string): string {
+  const cleaned = stripTerminalSequences(title).replace(/[\u0000-\u001f\u007f]/g, " ")
+    .replace(/\s+/g, " ").trim() || "(未命名会话)";
+  return truncateToWidth(cleaned, 65, "…");
+}
+
+/** Modal, bounded page of sessions; never executes destructive operations without confirmation. */
+export async function openSessionManager(options: SessionManagerOptions): Promise<void> {
+  const { ui } = options;
+  let query = "";
+  let sort: SessionSort = "recent";
+  let page = 0;
+  let sessions = await options.loadSessions();
+  for (;;) {
+    const current = getSessionPage(sessions, query, sort, page);
+    page = current.page;
+    const labels = current.items.map((session, index) =>
+      `${index + 1}. ${session.pinned ? "★ " : ""}${session.current ? "● " : ""}${safeLabel(session.title)} · ${session.messageCount} 条消息`,
+    );
+    const actions = [
+      "⌕ 搜索 / 清除搜索",
+      `↕ 排序：${SORT_CHOICES.find((choice) => choice.sort === sort)!.label}`,
+      ...(page > 0 ? ["← 上一页"] : []),
+      ...(page + 1 < current.pages ? ["下一页 →"] : []),
+      "↻ 刷新列表",
+      "关闭",
+    ];
+    const choice = await ui.select(
+      `Sessions · ${current.total}/${sessions.length} · ${page + 1}/${current.pages}${query ? ` · 搜索：${safeLabel(query)}` : ""}`,
+      [...labels, ...actions],
+    );
+    if (!choice || choice === "关闭") return;
+    if (choice === actions[0]) {
+      const next = await ui.input("搜索会话标题或 ID（留空清除搜索）", query);
+      if (next !== undefined) { query = next.trim(); page = 0; }
+    } else if (choice === actions[1]) {
+      const names = SORT_CHOICES.map(({ label, sort: key }) => `${key === sort ? "● " : "○ "}${label}`);
+      const selection = await ui.select("会话排序（置顶始终优先）", names);
+      const index = names.indexOf(selection ?? "");
+      if (index >= 0) { sort = SORT_CHOICES[index]!.sort; page = 0; }
+    } else if (choice === "← 上一页") {
+      page--;
+    } else if (choice === "下一页 →") {
+      page++;
+    } else if (choice === "↻ 刷新列表") {
+      sessions = await options.loadSessions();
+    } else {
+      const index = labels.indexOf(choice);
+      const session = current.items[index];
+      if (index < 0 || !session) continue;
+      const menu = [
+        ...(session.current ? [] : ["切换到此会话"]),
+        "重命名",
+        session.pinned ? "取消置顶" : "置顶会话",
+        ...(session.current ? [] : ["移到回收站"]),
+        "返回列表",
+      ];
+      const action = await ui.select(`${safeLabel(session.title)} · 管理`, menu);
+      if (action === "置顶会话" || action === "取消置顶") {
+        try {
+          const pinned = options.togglePin(session.id);
+          ui.notify(pinned ? "会话已置顶" : "已取消置顶", "info");
+          options.onPinChanged();
+          sessions = await options.loadSessions();
+          page = 0;
+        } catch (error) {
+          ui.notify(`保存置顶失败：${error instanceof Error ? error.message : String(error)}`, "error");
+        }
+      } else if (action === "移到回收站") {
+        const confirmed = await ui.confirm("删除会话", `将“${safeLabel(session.title)}”移到回收站？`);
+        if (confirmed) { options.onDelete(session); return; }
+      } else if (action === "切换到此会话") {
+        options.onSwitch(session);
+        return;
+      } else if (action === "重命名") {
+        options.onRename(session);
+        return;
+      }
+    }
+  }
+}

package/extensions/session/panel.test.ts

@@ -1,6 +1,6 @@
 import assert from "node:assert/strict";
 import test from "node:test";
-import type { TuiInputListener } from "@earendil-works/pi-tui";
+import { stripTerminalSequences, type TuiInputListener } from "@earendil-works/pi-tui";
 import { SessionPanel, type SessionListItem } from "./panel.ts";
 
 const theme = { fg: (_color: string, text: string) => text } as any;
@@ -236,3 +236,197 @@ test("hides ⊗ on narrow panels", async () => {
   assert.doesNotMatch(panel.render(16)[0]!, /⊗/);
   panel.dispose();
 });
+
+test("opens advanced manager from ≡ without triggering refresh or bulk trash", async () => {
+  let listener: TuiInputListener | undefined;
+  let opened = 0;
+  let cleared = 0;
+  let loads = 0;
+  const tui = {
+    addInputListener(next: TuiInputListener) { listener = next; return () => {}; },
+    requestRender() {},
+    currentLayout: undefined as any,
+  } as any;
+  const panel = new SessionPanel(theme, {
+    tui,
+    getDesiredWidth: () => 40,
+    loadSessions: async () => { loads++; return [session("one", "One session")]; },
+    onSelect() {}, onRename() {}, onDelete() {},
+    onDeleteOthers() { cleared++; },
+    onOpenResources() {},
+    onOpenManager() { opened++; },
+  });
+  tui.currentLayout = {
+    root: { component: panel, rect: { x: 10, y: 5, width: 40, height: 5 },
+      clip: { x: 10, y: 5, width: 40, height: 5 }, children: [] },
+  };
+  panel.refresh();
+  await flushAsync();
+  const header = panel.render(40)[0]!;
+  const managerColumn = header.indexOf("≡");
+  assert.ok(managerColumn > 0, "≡ must be present in the session header");
+  const x = 10 + managerColumn + 1;
+  assert.deepEqual(listener?.(`\u001b[<0;${x};6M`), { consume: true });
+  assert.deepEqual(listener?.(`\u001b[<0;${x};6m`), { consume: true });
+  await flushAsync();
+  assert.equal(opened, 1);
+  assert.equal(cleared, 0);
+  assert.equal(loads, 1);
+  panel.dispose();
+});
+
+test("pinned session remains visible ahead of the five-item sidebar limit", async () => {
+  const tui = { addInputListener: () => () => {}, requestRender() {} } as any;
+  const panel = new SessionPanel(theme, {
+    tui, getDesiredWidth: () => 42,
+    loadSessions: async () => [
+      { ...session("starred", "Important"), pinned: true },
+      ...Array.from({ length: 15 }, (_, index) => session(`other-${index}`, `Recent ${index}`)),
+    ],
+    onSelect() {}, onRename() {}, onDelete() {},
+    onDeleteOthers() {}, onOpenResources() {},
+  });
+  panel.refresh();
+  await flushAsync();
+  const output = panel.render(42).join("\n");
+  assert.match(output, /★○ Important/);
+  assert.match(output, /Recent 3/);
+  assert.doesNotMatch(output, /Recent 4/);
+  panel.dispose();
+});
+
+test("session row ☆/★ toggles pin in place without invoking rename, delete or switch", async () => {
+  let listener: TuiInputListener | undefined;
+  const calls: string[] = [];
+  let pinned = false;
+  const tui = {
+    addInputListener(next: TuiInputListener) { listener = next; return () => {}; },
+    requestRender() {},
+    currentLayout: undefined as any,
+  } as any;
+  const panel = new SessionPanel(theme, {
+    tui, getDesiredWidth: () => 40,
+    loadSessions: async () => [{ ...session("one", "Important session"), pinned }],
+    onSelect() { calls.push("select"); },
+    onRename() { calls.push("rename"); },
+    onDelete() { calls.push("delete"); },
+    onTogglePin(item) {
+      assert.equal(item.id, "one");
+      calls.push("pin");
+      pinned = !pinned;
+      panel.refresh();
+    },
+    onDeleteOthers() {}, onOpenResources() {}, now: () => 0,
+  });
+  tui.currentLayout = {
+    root: {
+      component: panel, rect: { x: 10, y: 5, width: 40, height: 5 },
+      clip: { x: 10, y: 5, width: 40, height: 5 }, children: [],
+    },
+  };
+  const click = (text: string) => {
+    const row = panel.render(40)[1]!;
+    const column = row.lastIndexOf(text);
+    assert.ok(column > 0, `missing button ${text}: ${row}`);
+    const x = 10 + column + 1;
+    assert.deepEqual(listener?.(`\u001b[<0;${x};7M`), { consume: true });
+    assert.deepEqual(listener?.(`\u001b[<0;${x};7m`), { consume: true });
+  };
+  panel.refresh();
+  await flushAsync();
+  assert.match(panel.render(40)[1]!, /☆ ✎ ×/);
+  click("☆");
+  await flushAsync();
+  assert.equal(pinned, true);
+  assert.match(panel.render(40)[1]!, /★ ✎ ×/);
+  assert.match(panel.render(40)[1]!, /★○ Important/);
+  click("★");
+  await flushAsync();
+  assert.equal(pinned, false);
+  assert.match(panel.render(40)[1]!, /☆ ✎ ×/);
+  assert.deepEqual(calls, ["pin", "pin"]);
+
+  click("✎");
+  await flushAsync();
+  click("×");
+  await flushAsync();
+  assert.deepEqual(calls, ["pin", "pin", "rename", "delete"]);
+  panel.dispose();
+});
+
+test("session pin hit area is distinct from rename/delete and cancelled on off-target release", async () => {
+  let listener: TuiInputListener | undefined;
+  const calls: string[] = [];
+  const tui = {
+    addInputListener(next: TuiInputListener) { listener = next; return () => {}; },
+    requestRender() {},
+    currentLayout: undefined as any,
+  } as any;
+  const panel = new SessionPanel(theme, {
+    tui, getDesiredWidth: () => 40,
+    loadSessions: async () => [{ ...session("active", "Current session"), current: true }],
+    onSelect() { calls.push("select"); }, onRename() { calls.push("rename"); },
+    onDelete() { calls.push("delete"); }, onTogglePin() { calls.push("pin"); },
+    onDeleteOthers() {}, onOpenResources() {}, now: () => 0,
+  });
+  tui.currentLayout = {
+    root: {
+      component: panel, rect: { x: 10, y: 5, width: 40, height: 5 },
+      clip: { x: 10, y: 5, width: 40, height: 5 }, children: [],
+    },
+  };
+  panel.refresh();
+  await flushAsync();
+  const line = panel.render(40)[1]!;
+  assert.match(line, /☆ ✎ ·/);
+  const pinX = 10 + line.indexOf("☆") + 1;
+  const renameX = 10 + line.indexOf("✎") + 1;
+  const endX = 10 + line.lastIndexOf("·") + 1;
+  listener?.(`\u001b[<0;${pinX};7M`);
+  listener?.(`\u001b[<0;${renameX};7m`);
+  await flushAsync();
+  assert.deepEqual(calls, []);
+  listener?.(`\u001b[<0;${endX};7M`);
+  listener?.(`\u001b[<0;${endX};7m`);
+  await flushAsync();
+  assert.deepEqual(calls, [], "current session cannot be deleted");
+  listener?.(`\u001b[<0;${pinX};7M`);
+  listener?.(`\u001b[<0;${pinX};7m`);
+  await flushAsync();
+  assert.deepEqual(calls, ["pin"], "current session can still be pinned");
+  panel.dispose();
+});
+
+test("narrow sidebar keeps prior rename/delete actions without showing a truncated pin button", async () => {
+  let listener: TuiInputListener | undefined;
+  const actions: string[] = [];
+  const tui = {
+    addInputListener(next: TuiInputListener) { listener = next; return () => {}; },
+    requestRender() {},
+    currentLayout: undefined as any,
+  } as any;
+  const panel = new SessionPanel(theme, {
+    tui, getDesiredWidth: () => 21,
+    loadSessions: async () => [session("one", "Short")],
+    onSelect() { actions.push("select"); }, onRename() { actions.push("rename"); },
+    onDelete() { actions.push("delete"); }, onTogglePin() { actions.push("pin"); },
+    onDeleteOthers() {}, onOpenResources() {}, now: () => 0,
+  });
+  tui.currentLayout = {
+    root: {
+      component: panel, rect: { x: 3, y: 2, width: 21, height: 5 },
+      clip: { x: 3, y: 2, width: 21, height: 5 }, children: [],
+    },
+  };
+  panel.refresh();
+  await flushAsync();
+  const line = stripTerminalSequences(panel.render(21)[1]!);
+  assert.match(line, / ✎ ×/);
+  assert.doesNotMatch(line, /☆/);
+  const pencilX = 3 + line.indexOf("✎") + 1;
+  assert.deepEqual(listener?.(`\u001b[<0;${pencilX};4M`), { consume: true }, `press at ${pencilX}: ${line}`);
+  assert.deepEqual(listener?.(`\u001b[<0;${pencilX};4m`), { consume: true }, `release at ${pencilX}: ${line}`);
+  await flushAsync();
+  assert.deepEqual(actions, ["rename"]);
+  panel.dispose();
+});

package/extensions/session/panel.ts

@@ -12,8 +12,11 @@ import { installPriorityInputListener, parseSgrMouseEvent } from "../sidebar/res
 
 const MAX_VISIBLE_SESSIONS = 5;
 const SESSION_ACTION_WIDTH = 4;
+const SESSION_PIN_ACTION_WIDTH = 2;
+const MIN_SUMMARY_WIDTH_WITH_PIN = 12;
 const SESSION_TITLE_CELLS = " SESSIONS ↻ ".length;
 const CLEAR_OTHERS_CELL = " ⊗ ";
+const MANAGE_SESSIONS_CELL = " ≡ ";
 
 export type SessionListItem = {
   readonly id: string;
@@ -21,6 +24,7 @@ export type SessionListItem = {
   readonly modified: Date;
   readonly messageCount: number;
   readonly current: boolean;
+  readonly pinned?: boolean;
 };
 
 export type ResourceButtonId = "agents" | "skills" | "extensions" | "mcp";
@@ -32,7 +36,9 @@ export type SessionPanelOptions = {
   readonly onSelect: (session: SessionListItem) => void;
   readonly onRename: (session: SessionListItem) => void;
   readonly onDelete: (session: SessionListItem) => void;
+  readonly onTogglePin?: (session: SessionListItem) => void;
   readonly onDeleteOthers: () => void;
+  readonly onOpenManager?: () => void;
   readonly onOpenResources: (button: ResourceButtonId) => void;
   readonly now?: () => number;
 };
@@ -44,7 +50,7 @@ const RESOURCE_BUTTONS: ReadonlyArray<{ id: ResourceButtonId; label: string }> =
   { id: "mcp", label: "MCP" },
 ];
 
-type SessionRowAction = "select" | "rename" | "delete";
+type SessionRowAction = "select" | "pin" | "rename" | "delete";
 type SessionActionTarget = {
   readonly session: SessionListItem;
   readonly action: SessionRowAction;
@@ -102,23 +108,32 @@ function clearOthersSpan(renderWidth: number): { readonly start: number; readonl
   return { start: glyphStart - 1, end: glyphStart + CLEAR_OTHERS_CELL.length - 2 };
 }
 
-/** Title row with a right-aligned ⊗ button that trashes every other session. */
-function renderSessionTitleRow(theme: Theme, title: string, renderWidth: number, clearPressed: boolean): string {
+function manageSessionsSpan(renderWidth: number): { readonly start: number; readonly end: number } | undefined {
+  const clear = clearOthersSpan(renderWidth);
+  const innerWidth = Math.max(1, renderWidth - 2);
+  if (!clear || innerWidth < SESSION_TITLE_CELLS + CLEAR_OTHERS_CELL.length + MANAGE_SESSIONS_CELL.length + 4) return undefined;
+  return { start: clear.start - MANAGE_SESSIONS_CELL.length, end: clear.start - 1 };
+}
+
+/** Title row with a right-aligned manager (≡) and clear-others (⊗) buttons. */
+function renderSessionTitleRow(theme: Theme, title: string, renderWidth: number, clearPressed: boolean, managePressed: boolean, showManager: boolean): string {
   const innerWidth = Math.max(1, renderWidth - 2);
   const span = clearOthersSpan(renderWidth);
-  const reserved = span ? CLEAR_OTHERS_CELL.length + 1 : 0;
+  const manager = showManager ? manageSessionsSpan(renderWidth) : undefined;
+  const reserved = span ? CLEAR_OTHERS_CELL.length + 1 + (manager ? MANAGE_SESSIONS_CELL.length : 0) : 0;
   const borderWidth = Math.max(0, innerWidth - SESSION_TITLE_CELLS - reserved);
   const left = Math.floor(borderWidth / 2);
   const right = borderWidth - left;
   const border = theme.fg("accent", `╭${"─".repeat(left)} ${title} ${"─".repeat(right)}`);
   if (!span) return `${border}${theme.fg("accent", "╮")}`;
   return border +
+    (manager ? theme.fg(managePressed ? "warning" : "accent", MANAGE_SESSIONS_CELL) : "") +
     theme.fg(clearPressed ? "warning" : "accent", CLEAR_OTHERS_CELL) +
     theme.fg("accent", "─╮");
 }
 
 function formatSessionSummary(session: SessionListItem, width: number, now: number): string {
-  const marker = session.current ? "● " : "○ ";
+  const marker = `${session.pinned ? "★" : ""}${session.current ? "● " : "○ "}`;
   const metadata = `${session.messageCount} · ${formatRelativeTime(session.modified, now)}`;
   const fixedWidth = visibleWidth(marker) + visibleWidth(metadata) + 1;
   if (fixedWidth >= width) {
@@ -130,23 +145,29 @@ function formatSessionSummary(session: SessionListItem, width: number, now: numb
   return `${marker}${padToWidth(title, titleWidth)} ${metadata}`;
 }
 
-function formatSessionRow(session: SessionListItem, contentWidth: number, now: number): string {
+function showPinButton(contentWidth: number, enabled: boolean): boolean {
+  return enabled && contentWidth >= SESSION_ACTION_WIDTH + SESSION_PIN_ACTION_WIDTH + MIN_SUMMARY_WIDTH_WITH_PIN;
+}
+
+function formatSessionRow(session: SessionListItem, contentWidth: number, now: number, enablePin: boolean): string {
   if (contentWidth <= SESSION_ACTION_WIDTH) {
     return formatSessionSummary(session, contentWidth, now);
   }
-  const summaryWidth = contentWidth - SESSION_ACTION_WIDTH;
+  const pinVisible = showPinButton(contentWidth, enablePin);
+  const summaryWidth = contentWidth - SESSION_ACTION_WIDTH - (pinVisible ? SESSION_PIN_ACTION_WIDTH : 0);
   const summary = padToWidth(formatSessionSummary(session, summaryWidth, now), summaryWidth);
-  return `${summary} ✎ ${session.current ? "·" : "×"}`;
+  return `${summary}${pinVisible ? ` ${session.pinned ? "★" : "☆"}` : ""} ✎ ${session.current ? "·" : "×"}`;
 }
 
 function sameTarget(left: SessionActionTarget | undefined, right: SessionActionTarget | undefined): boolean {
   return Boolean(left && right && left.session.id === right.session.id && left.action === right.action);
 }
 
-/** Recent-session panel: click the title to refresh, a row to switch, ✎ to rename, × to delete, or ⊗ to trash every other session. */
+/** Recent sessions: click to switch, ☆/★ to pin, ✎ to rename, × to delete, or ⊗ to bulk trash. */
 export class SessionPanel implements Component {
   private pressedResource: ResourceButtonId | undefined;
   private clearPressed = false;
+  private managePressed = false;
 
   private sessions: readonly SessionListItem[] = [];
   private loading = true;
@@ -202,9 +223,14 @@ export class SessionPanel implements Component {
     const contentWidth = Math.max(1, renderWidth - 4);
     const contentColumn = x - box.rect.x - 2;
     if (contentColumn < 0 || contentColumn >= contentWidth) return undefined;
-    if (contentWidth <= SESSION_ACTION_WIDTH || contentColumn < contentWidth - SESSION_ACTION_WIDTH) {
+    const pinVisible = showPinButton(contentWidth, Boolean(this.options.onTogglePin));
+    if (contentWidth <= SESSION_ACTION_WIDTH ||
+        contentColumn < contentWidth - SESSION_ACTION_WIDTH - (pinVisible ? SESSION_PIN_ACTION_WIDTH : 0)) {
       return { session, action: "select" };
     }
+    if (pinVisible && contentColumn < contentWidth - SESSION_ACTION_WIDTH) {
+      return { session, action: "pin" };
+    }
     if (contentColumn < contentWidth - 2) return { session, action: "rename" };
     return session.current ? undefined : { session, action: "delete" };
   }
@@ -221,7 +247,8 @@ export class SessionPanel implements Component {
       contains(box.clip, x, y) &&
       contains(box.rect, x, y) &&
       y === box.rect.y &&
-      !this.isClearOthersTarget(x, y),
+      !this.isClearOthersTarget(x, y) &&
+      !this.isManageSessionsTarget(x, y),
     );
   }
 
@@ -236,11 +263,23 @@ export class SessionPanel implements Component {
     return contentColumn >= span.start && contentColumn <= span.end;
   }
 
+  private isManageSessionsTarget(x: number, y: number): boolean {
+    if (!this.options.onOpenManager) return false;
+    const box = this.getLayoutBox();
+    if (!box || !contains(box.clip, x, y) || !contains(box.rect, x, y) || y !== box.rect.y) return false;
+    const span = manageSessionsSpan(Math.max(1, Math.min(box.rect.width, this.options.getDesiredWidth())));
+    const column = x - box.rect.x - 2;
+    return Boolean(span && column >= span.start && column <= span.end);
+  }
+
   private invoke(target: SessionActionTarget): void {
     switch (target.action) {
       case "select":
         if (!target.session.current) this.options.onSelect(target.session);
         return;
+      case "pin":
+        this.options.onTogglePin?.(target.session);
+        return;
       case "rename":
         this.options.onRename(target.session);
         return;
@@ -261,6 +300,14 @@ export class SessionPanel implements Component {
     const isLeft = (mouse.button & 3) === 0;
 
     if (mouse.release) {
+      if (this.managePressed) {
+        this.managePressed = false;
+        if (this.isManageSessionsTarget(x, y)) {
+          queueMicrotask(() => { if (!this.disposed) this.options.onOpenManager?.(); });
+        }
+        this.options.tui.requestRender();
+        return { consume: true };
+      }
       if (this.pressedResource) {
         const pressed = this.pressedResource;
         this.pressedResource = undefined;
@@ -309,6 +356,13 @@ export class SessionPanel implements Component {
     }
 
     if (mouse.motion) {
+      if (this.managePressed) {
+        if (!this.isManageSessionsTarget(x, y)) {
+          this.managePressed = false;
+          this.options.tui.requestRender();
+        }
+        return { consume: true };
+      }
       if (this.refreshPressed) {
         if (!this.isRefreshTarget(x, y)) {
           this.refreshPressed = false;
@@ -344,6 +398,12 @@ export class SessionPanel implements Component {
     if (isWheel) return { consume: true };
     if (!isLeft) return undefined;
 
+    if (this.isManageSessionsTarget(x, y)) {
+      this.managePressed = true;
+      this.options.tui.requestRender();
+      return { consume: true };
+    }
+
     if (this.isClearOthersTarget(x, y)) {
       this.clearPressed = true;
       this.options.tui.requestRender();
@@ -408,7 +468,7 @@ export class SessionPanel implements Component {
     const body = this.sessions.length > 0
       ? this.sessions.map((session) => panelContent(
           this.theme,
-          formatSessionRow(session, contentWidth, now),
+          formatSessionRow(session, contentWidth, now, Boolean(this.options.onTogglePin)),
           this.pressedTarget?.session.id === session.id
             ? "warning"
             : session.current
@@ -439,7 +499,7 @@ export class SessionPanel implements Component {
 
     const divider = this.theme.fg("dim", `├${"─".repeat(Math.max(1, renderWidth - 2))}┤`);
     return [
-      renderSessionTitleRow(this.theme, this.loading || this.loadInFlight ? "SESSIONS …" : "SESSIONS ↻", renderWidth, this.clearPressed),
+      renderSessionTitleRow(this.theme, this.loading || this.loadInFlight ? "SESSIONS …" : "SESSIONS ↻", renderWidth, this.clearPressed, this.managePressed, Boolean(this.options.onOpenManager)),
       ...body,
       divider,
       resourceRow,
@@ -454,6 +514,7 @@ export class SessionPanel implements Component {
     this.disposed = true;
     this.refreshPressed = false;
     this.clearPressed = false;
+    this.managePressed = false;
     this.pressedResource = undefined;
     this.pressedTarget = undefined;
     this.uninstallInput();

package/extensions/sidebar/default-panels.ts

@@ -69,7 +69,9 @@ export type DefaultSidebarPanelOptions = {
   readonly onSelectSession: (session: SessionListItem) => void;
   readonly onRenameSession: (session: SessionListItem) => void;
   readonly onDeleteSession: (session: SessionListItem) => void;
+  readonly onTogglePinSession?: (session: SessionListItem) => void;
   readonly onDeleteOthers: () => void;
+  readonly onOpenSessionManager?: () => void;
   readonly onOpenResources: (button: ResourceButtonId) => void;
 };
 
@@ -94,7 +96,9 @@ export function createDefaultSidebarPanels(
         onSelect: options.onSelectSession,
         onRename: options.onRenameSession,
         onDelete: options.onDeleteSession,
+        onTogglePin: options.onTogglePinSession,
         onDeleteOthers: options.onDeleteOthers,
+        onOpenManager: options.onOpenSessionManager,
         onOpenResources: options.onOpenResources,
       });
       panel.refresh();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-ui-extension",
-  "version": "1.1.11",
+  "version": "1.2.0",
   "type": "module",
   "description": "Pi terminal UI extension with session management, context inspection, Tool/MCP usage tracking, sidebar panels, and a compact footer",
   "keywords": [