pisesh 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [0.1.0] — 2026-05-31
+
+Initial release.
+
+### Added
+- `pisesh` CLI binary — keyboard-driven TUI that lists every pi session under `~/.pi/agent/sessions/`
+- Tabs: **★ Favorites**, **Today**, **All**
+- Star / unstar with `f` or Space; favorites persist to `~/.pi/agent/favorites.json`
+- Search across id / project / first user prompt with `/`
+- Session details view (`d`): full prompt, file path, byte size, timestamps
+- `Enter` resumes the selected session via `pi --session <id> --session-dir <dir>` in the original cwd
+- `[NOW]` badge marks the session belonging to the pi instance that spawned pisesh (set via `PISESH_CURRENT_SESSION` env var)
+- Alternate screen buffer (`\x1b[?1049h`) — exit restores terminal byte-for-byte; no scrollback pollution
+- CJK-aware truncation and padding (Hangul / CJK ideographs / emoji counted as 2 cells)
+- Signal handlers (`SIGINT`, `SIGTERM`, `exit`) restore cursor + main buffer on unexpected exit
+- Non-TUI CLI: `--list`, `--json`, `--star <id>`, `--unstar <id>`, `--help`
+- Pi extension at `extensions/sesh.ts` — registers `/sesh` slash command which spawns pisesh inside pi via `ui.custom` + `tui.stop()`

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Blue-B
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,255 @@
+# pisesh
+
+[![npm](https://img.shields.io/npm/v/pisesh?style=for-the-badge&logo=npm&color=CB3837&logoColor=white)](https://www.npmjs.com/package/pisesh)
+[![ci](https://img.shields.io/github/actions/workflow/status/Blue-B/pisesh/ci.yml?branch=main&style=for-the-badge&logo=github-actions&logoColor=white&label=CI)](https://github.com/Blue-B/pisesh/actions/workflows/ci.yml)
+[![license](https://img.shields.io/github/license/Blue-B/pisesh?style=for-the-badge&color=blue)](LICENSE)
+[![node](https://img.shields.io/badge/node-%E2%89%A518-339933?style=for-the-badge&logo=node.js&logoColor=white)](https://nodejs.org/)
+[![deps](https://img.shields.io/badge/dependencies-0-brightgreen?style=for-the-badge)](package.json)
+
+**Bookmark, search, and resume [pi coding-agent](https://github.com/earendil-works/pi-coding-agent) sessions with a fast keyboard-driven TUI.**
+
+> `pi --resume` lists every session you ever started. After a week that's 50+ entries with no titles, no tags, no order — just scroll and pray. **pisesh** adds the one thing that was missing: ⭐ favorites, instant search, and a `[NOW]` badge for the session you're attached to.
+
+## Preview
+
+<p align="center">
+  <img src="assets/preview.png" alt="pisesh — Favorites tab in a real Windows Terminal session" width="100%">
+</p>
+
+<p align="center"><sub>Real capture: ★ starred session at the top, the rest available behind the <b>Today</b> and <b>All</b> tabs. <code>Tab</code> cycles. <code>f</code> stars. <code>Enter</code> resumes.</sub></p>
+
+## Why pisesh
+
+Pi accumulates sessions across many working directories — your home, several project dirs, scratch tmux panes. The built-in resume picker is alphabetical-ish and forgets context. After a few weeks:
+
+- You can't tell which session was "the one where you fixed the auth bug"
+- You can't pin the 3-4 long-running threads you keep going back to
+- You re-open the wrong session and pollute it with unrelated context
+- You waste time searching by timestamp guessing
+
+pisesh is a **single-file Node script** (no dependencies, ~600 LoC) that gives you everything `pi --resume` doesn't.
+
+### Value at a glance
+
+| Need                                       | What you get                                                                 |
+| ------------------------------------------ | ---------------------------------------------------------------------------- |
+| Mark important sessions                    | ⭐ Star/unstar with one keystroke; favorites persist to one global JSON       |
+| Find a session by what you said            | `/` searches id + project + first user prompt                                |
+| Know which session you're attached to      | `[NOW]` badge on the live session (passed from pi via env var)               |
+| Keep your terminal clean                   | Alt-screen buffer — exit restores your terminal byte-for-byte (like vim)     |
+| Read Korean / Chinese / Japanese prompts   | Display-width-aware truncation; columns never blow up on CJK                 |
+| Open from anywhere                         | Run as standalone `pisesh` shell command, or `/sesh` inside pi               |
+| Zero install pain                          | No build step, no native deps, runs on Node 18+ everywhere                   |
+| Trust it with your history                 | pisesh only writes one favorites file; session jsonl files are read-only     |
+
+## Getting started
+
+### Quick install (recommended)
+
+```bash
+# Install both the CLI and the /sesh slash command in one go
+pi install npm:pisesh
+```
+
+This registers pisesh as a pi extension. Inside any pi session, type `/sesh`.
+
+### Standalone CLI only
+
+```bash
+npm install -g pisesh
+pisesh
+```
+
+Use this if you want pisesh as a separate shell command and don't need the pi slash binding.
+
+### From source (developers)
+
+```bash
+git clone https://github.com/Blue-B/pisesh.git
+cd pisesh
+npm link            # symlink ./bin/pisesh into your global PATH
+pisesh --help
+```
+
+Pi-extension side: drop `extensions/sesh.ts` into `~/.pi/agent/extensions/` and run `/reload` inside pi.
+
+## Keys
+
+| Key                          | Action                                                       |
+| ---------------------------- | ------------------------------------------------------------ |
+| `↑` `↓` / `j` `k`            | move cursor                                                  |
+| `Tab` / `h` / `l`            | switch tab (`★ Favorites` → `Today` → `All`)                 |
+| `f` / `Space`                | star / unstar the selected session                           |
+| `Enter`                      | resume — spawns `pi --session <id> --session-dir <dir>`      |
+| `d`                          | session details (full prompt, file, byte size, timestamps)   |
+| `/`                          | search by id / project / first user prompt                   |
+| `Esc`                        | clear search first, then quit                                |
+| `q` / `Ctrl-C`               | quit (terminal restored)                                     |
+| `r`                          | rescan session files (after pi starts a new session)         |
+| `c` (in details view)        | copy session id to clipboard (clip.exe / pbcopy / xclip)     |
+| `Home` `End` `PgUp` `PgDn`   | jump to top / bottom / ±10                                   |
+
+## CLI (non-TUI) usage
+
+For scripts and automation:
+
+```bash
+pisesh --list                  # print starred session IDs (one per line)
+pisesh --json                  # full favorites file as JSON
+pisesh --star <partial-uuid>   # star a session from a script
+pisesh --unstar <partial-uuid> # unstar
+pisesh --help
+```
+
+## Tech Stack
+
+[![Node.js](https://img.shields.io/badge/Node.js-339933?style=for-the-badge&logo=node.js&logoColor=white)](https://nodejs.org/) [![JavaScript](https://img.shields.io/badge/JavaScript-F7DF1E?style=for-the-badge&logo=javascript&logoColor=000)](https://developer.mozilla.org/docs/Web/JavaScript) [![TypeScript](https://img.shields.io/badge/TypeScript-3178C6?style=for-the-badge&logo=typescript&logoColor=white)](https://www.typescriptlang.org/) [![pi](https://img.shields.io/badge/pi--coding--agent-5C4EE5?style=for-the-badge)](https://github.com/earendil-works/pi-coding-agent)
+
+| Area                | Details                                                                                          |
+| ------------------- | ------------------------------------------------------------------------------------------------ |
+| Runtime             | Node.js ≥ 18 (uses only built-in modules: `fs`, `path`, `os`, `child_process`, `readline`)       |
+| TUI rendering       | Raw ANSI escape sequences (no `blessed` / `ink` / `chalk` dependency)                            |
+| Alt screen buffer   | `\x1b[?1049h` / `\x1b[?1049l` — same primitive as `vim`, `less`, `htop`, droid CLI               |
+| Input               | Node's `readline.emitKeypressEvents` in raw mode                                                 |
+| Width calculation   | UAX #11 East Asian Width ranges, compressed to ~10 inline range checks                           |
+| Pi extension        | TypeScript factory using `@earendil-works/pi-coding-agent` extension API (`ui.custom`, `tui.stop`) |
+| Storage             | Single JSON file at `~/.pi/agent/favorites.json` (`{ ids: [...], updated: "iso" }`)              |
+| Session discovery   | Direct filesystem scan of `~/.pi/agent/sessions/<projectSlug>/*.jsonl`; first 96 KB parsed       |
+| Process model       | Slash command pauses pi's TUI, spawns pisesh with inherited stdio, restarts pi on exit           |
+
+### What it explicitly does **not** depend on
+
+- No `npm install` for the bundled CLI runtime — true zero-dep
+- No native binaries / GPU / ffmpeg / database
+- No network calls, no telemetry, no analytics
+- No daemon / background process
+
+## How resume works
+
+```text
+pi (session A)  ── /sesh ──▶  ui.custom + tui.stop()
+                              │
+                              └─▶ spawn pisesh  (PISESH_CURRENT_SESSION=A)
+                                    │  ↑↓ Tab f / Enter on session B
+                                    │
+                                    └─▶ spawn  pi --session B --session-dir <dir>
+                                          │
+                                          │  user works in B …
+                                          │  user types q / ^D
+                                          │
+                                    ◀─── inner pi exits, pisesh exits
+                              │
+                ◀─── tui.start() + requestRender(true)
+pi (session A) continues exactly where it was
+```
+
+The current pi session is paused, not lost. When you finish with the resumed session, you pop back to A with full state intact.
+
+## Storage
+
+| What       | Where                                                       |
+| ---------- | ----------------------------------------------------------- |
+| Favorites  | `~/.pi/agent/favorites.json`                                |
+| Sessions   | `~/.pi/agent/sessions/<projectSlug>/<timestamp>_<uuid>.jsonl` (pi's native layout — pisesh never writes here) |
+
+Favorites file shape:
+
+```json
+{
+  "ids": [
+    "019e79b9-d2c1-741f-81ea-1dcad9a2d712",
+    "019e6355-9957-7a30-b4ce-b9db5e3c9ac6"
+  ],
+  "updated": "2026-05-31T01:33:21.234Z"
+}
+```
+
+It's a single global file (not per-project). Back it up by syncing one file.
+
+## CJK-aware rendering
+
+Korean / Chinese / Japanese / fullwidth characters render **2 cells wide** in terminals; pisesh measures display width (not JavaScript code-unit length) when truncating and padding. Korean prompts never wrap, columns stay aligned, and the layout looks identical whether the prompt is `hello world` or `안녕하세요 세상`.
+
+```text
+✓ aitapps         지금 디렉토리에 앱인토스 제출용앱을 만들었는데…
+✓ 공모전          신소재 공학 관련 졸업과제 도와줘…
+✓ WhisperSubTrans 이슈 #26 이전 버전 아닌가 확인…
+```
+
+(Previously: Korean prompts overflowed to a second line and broke the table.)
+
+## Requirements
+
+- **Node.js ≥ 18** (uses optional chaining, `for…of` on strings — no transpile needed)
+- A terminal with ANSI escape + alternate screen buffer support — basically every modern emulator:
+  - Windows: **Windows Terminal**, **WezTerm**, **Alacritty** ✅
+  - macOS: **iTerm2**, **Terminal.app**, **WezTerm**, **Alacritty**, **Kitty** ✅
+  - Linux: **GNOME Terminal**, **Konsole**, **xterm**, **Alacritty**, **Kitty** ✅
+- [`pi`](https://www.npmjs.com/package/@earendil-works/pi-coding-agent) on `$PATH` for the `Enter`-to-resume action
+
+## Roadmap
+
+| Status | Item                                                                            |
+| ------ | ------------------------------------------------------------------------------- |
+| ✅     | Tabs, star/unstar, search, alt-screen, CJK width, `[NOW]` badge, pi `/sesh`     |
+| 🚧     | `n` / `N` jump to next / previous search match (less-style)                     |
+| 🚧     | Highlight matched substring in yellow                                           |
+| 🚧     | Filter by `today/yesterday/this-week`                                           |
+| 🧠     | Optional summarize first-N user prompts via local model for richer titles       |
+| 🧠     | Export starred sessions as a single bundle (share / archive)                    |
+| 🧠     | Inline rename / label (`n` to add a custom title that overrides first prompt)   |
+
+PRs welcome for anything in the 🚧 lane.
+
+## Contributing
+
+```bash
+git clone https://github.com/Blue-B/pisesh.git
+cd pisesh
+npm link
+npm test        # node --check + smoke test
+```
+
+Branching: short-lived `feature/<scope>` or `fix/<scope>` → squash-merge into `main`.
+Commits: [Conventional Commits](https://www.conventionalcommits.org/) style (`feat:`, `fix:`, `docs:`, `chore:`).
+
+Open a PR — the CI matrix runs on Ubuntu / macOS / Windows × Node 18 / 20 / 22.
+
+## Support
+
+If pisesh saves you context-switching time or just makes pi nicer to live in, supporting it directly accelerates development:
+
+- Your support helps: bug fixes, new keybindings, more search modes, integration with other pi extensions.
+- Transparency: I don't sell data; funds go to development time and a coffee or two.
+- One-time sponsors are credited in README and release notes (opt-out available).
+- Monthly sponsors ($3/mo via GitHub Sponsors) get best-effort priority triage for "Sponsor Request" issues.
+
+[![GitHub Sponsors](https://img.shields.io/badge/Sponsor-GitHub-EA4AAA?style=for-the-badge&logo=github-sponsors&logoColor=white)](https://github.com/sponsors/Blue-B) [![Buy Me A Coffee](https://img.shields.io/badge/One%E2%80%91time_$3-Buy_Me_A_Coffee-FFDD00?style=for-the-badge&logo=buy-me-a-coffee&logoColor=000)](https://buymeacoffee.com/beckycode7h) [![PayPal](https://img.shields.io/badge/Donate-PayPal-00457C?style=for-the-badge&logo=paypal&logoColor=white)](https://www.paypal.com/ncp/payment/ZEWFKDX595ESJ)
+
+## Acknowledgments
+
+- [pi-coding-agent](https://github.com/earendil-works/pi-coding-agent) by [@mariozechner](https://github.com/mariozechner) — the agent and its extension API that make `/sesh` possible.
+- [interactive-shell example extension](https://github.com/earendil-works/pi-coding-agent/blob/main/examples/extensions/interactive-shell.ts) — pattern reference for `ui.custom` + `tui.stop` TTY handoff.
+- Inspiration for the favorites + tabs UX: [droid CLI](https://github.com/factory-ai/droid) and tmux's [sesh](https://github.com/joshmedeski/sesh).
+
+## Contributors
+
+Thanks to everyone who helps make pisesh better! 🙏
+
+<a href="https://github.com/Blue-B"><img src="https://github.com/Blue-B.png?size=80" width="80" alt="Blue-B" title="Blue-B" /></a>
+
+## Repository activity
+
+![Repobeats analytics image](https://repobeats.axiom.co/api/embed/blue-b-pisesh.svg "Repobeats analytics image")
+
+## Star History
+
+<a href="https://star-history.com/#Blue-B/pisesh&Date">
+  <img src="https://api.star-history.com/svg?repos=Blue-B/pisesh&type=Date" alt="Star History Chart" width="600" />
+</a>
+
+## License
+
+MIT © [Blue-B](https://github.com/Blue-B). See [LICENSE](LICENSE).
+
+The pi extension uses the `@earendil-works/pi-coding-agent` API; check pi's own license for that side. The CLI binary is pure Node and has no other licenses to worry about.

package/bin/pisesh

@@ -0,0 +1,644 @@
+#!/usr/bin/env node
+// pisesh — pi session bookmark & resume TUI
+// Tabs: ★ Favorites / Today / All
+// Storage: ~/.pi/agent/favorites.json
+// Sessions: ~/.pi/agent/sessions/<projectSlug>/<ts>_<uuid>.jsonl
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { spawn } = require('child_process');
+const readline = require('readline');
+
+// ── Paths ─────────────────────────────────────────────
+const HOME = os.homedir();
+const SESSIONS_ROOT = path.join(HOME, '.pi/agent/sessions');
+const FAV_FILE = path.join(HOME, '.pi/agent/favorites.json');
+
+// Current session id (set by the /sesh extension before spawning). Lets us
+// flag the currently-attached session in the list with a [NOW] badge.
+const CURRENT_SESSION_ID = (process.env.PISESH_CURRENT_SESSION || '').trim();
+
+// ── ANSI ──────────────────────────────────────────────
+const A = {
+  clr: '\x1b[2J\x1b[H',
+  // Alternate screen buffer: draws into a separate buffer so tab-switching
+  // never pushes prior renders into terminal scrollback. On exit the user's
+  // pre-pisesh terminal content is restored byte-for-byte. Same trick as
+  // less/vim/htop/droid-cli.
+  enterAlt: '\x1b[?1049h',
+  exitAlt: '\x1b[?1049l',
+  hideC: '\x1b[?25l',
+  showC: '\x1b[?25h',
+  R: '\x1b[0m',
+  B: '\x1b[1m',
+  D: '\x1b[2m',
+  I: '\x1b[7m',
+  yel: '\x1b[33m',
+  cyn: '\x1b[36m',
+  grn: '\x1b[32m',
+  mag: '\x1b[35m',
+  red: '\x1b[31m',
+  gry: '\x1b[90m',
+  bgBlu: '\x1b[44m',
+};
+
+// ── Persistence ───────────────────────────────────────
+function loadFavorites() {
+  try {
+    const raw = fs.readFileSync(FAV_FILE, 'utf8');
+    const data = JSON.parse(raw);
+    return new Set(data.ids || []);
+  } catch { return new Set(); }
+}
+
+function saveFavorites(set) {
+  const data = { ids: [...set], updated: new Date().toISOString() };
+  try {
+    fs.mkdirSync(path.dirname(FAV_FILE), { recursive: true });
+    fs.writeFileSync(FAV_FILE, JSON.stringify(data, null, 2));
+  } catch (e) {
+    console.error('save favorites failed:', e.message);
+  }
+}
+
+let favorites = loadFavorites();
+
+// ── Project slug decode ───────────────────────────────
+// pi encodes cwd by replacing '/' with '-' and wrapping in '--…--'
+// "--mnt-c-Users-root--"                       → "/mnt/c/Users/root"
+// "--mnt-c-Users-root-Downloads-instareal--"   → "/mnt/c/Users/root/Downloads/instareal"
+// "--home-shell--"                             → "/home/shell"
+function decodeProjectSlug(slug) {
+  let s = slug;
+  if (s.startsWith('--')) s = '/' + s.slice(2);
+  if (s.endsWith('--')) s = s.slice(0, -2);
+  return s.replace(/-/g, '/');
+}
+
+function shortCwd(cwd, max = 18) {
+  const parts = cwd.split('/').filter(Boolean);
+  if (parts.length === 0) return cwd;
+  const last = parts[parts.length - 1];
+  // Use display-cell truncation so CJK project names don't blow up the column.
+  return trunc(last, max);
+}
+
+// ── Scan sessions ─────────────────────────────────────
+function readSessionMeta(file) {
+  // Read up to 96 KB to find session line + first user prompt
+  let buf;
+  try {
+    const fd = fs.openSync(file, 'r');
+    const tmp = Buffer.alloc(96 * 1024);
+    const n = fs.readSync(fd, tmp, 0, tmp.length, 0);
+    fs.closeSync(fd);
+    buf = tmp.slice(0, n).toString('utf8');
+  } catch { return null; }
+
+  const lines = buf.split('\n');
+  let session = null;
+  let firstPrompt = '';
+  for (const line of lines) {
+    if (!line.trim()) continue;
+    let obj;
+    try { obj = JSON.parse(line); }
+    catch { continue; } // truncated last line is fine
+
+    if (!session && obj.type === 'session') session = obj;
+
+    if (!firstPrompt && obj.type === 'message' && obj.message && obj.message.role === 'user') {
+      const content = obj.message.content;
+      let text = '';
+      if (Array.isArray(content)) {
+        for (const c of content) {
+          if (c && c.type === 'text' && c.text) { text = c.text; break; }
+        }
+      } else if (typeof content === 'string') text = content;
+      if (text.trim()) firstPrompt = text.trim();
+    }
+
+    if (session && firstPrompt) break;
+  }
+  if (!session) return null;
+  session.firstPrompt = firstPrompt;
+  return session;
+}
+
+function scanSessions() {
+  let projectDirs;
+  try {
+    projectDirs = fs.readdirSync(SESSIONS_ROOT, { withFileTypes: true })
+      .filter(d => d.isDirectory());
+  } catch { return []; }
+
+  const results = [];
+  for (const d of projectDirs) {
+    const projectPath = path.join(SESSIONS_ROOT, d.name);
+    const projectLabel = decodeProjectSlug(d.name);
+    let files;
+    try { files = fs.readdirSync(projectPath).filter(f => f.endsWith('.jsonl')); }
+    catch { continue; }
+
+    for (const f of files) {
+      const full = path.join(projectPath, f);
+      let st;
+      try { st = fs.statSync(full); } catch { continue; }
+      const meta = readSessionMeta(full);
+      if (!meta || !meta.id) continue;
+      results.push({
+        id: meta.id,
+        ts: meta.timestamp,
+        mtime: st.mtime,
+        cwd: meta.cwd || projectLabel,
+        project: projectLabel,
+        projectSlug: d.name,
+        file: full,
+        prompt: meta.firstPrompt || '',
+        size: st.size,
+        get favored() { return favorites.has(this.id); },
+        get isCurrent() { return CURRENT_SESSION_ID !== '' && this.id === CURRENT_SESSION_ID; },
+      });
+    }
+  }
+  results.sort((a, b) => b.mtime - a.mtime);
+  return results;
+}
+
+// ── State ─────────────────────────────────────────────
+let sessions = [];
+let tabs = ['★ Favorites', 'Today', 'All'];
+let tabIdx = 0;
+let cursor = 0;
+let filter = '';
+let mode = 'list';      // list | filter | details
+
+// ── Filtering by tab ──────────────────────────────────
+function visibleSessions() {
+  let list = sessions;
+  const tab = tabs[tabIdx];
+
+  if (tab.startsWith('★')) {
+    list = list.filter(s => s.favored);
+  } else if (tab === 'Today') {
+    const today = new Date().toLocaleDateString('sv-SE'); // YYYY-MM-DD
+    list = list.filter(s => new Date(s.mtime).toLocaleDateString('sv-SE') === today);
+  }
+
+  if (filter) {
+    const q = filter.toLowerCase();
+    list = list.filter(s =>
+      s.id.toLowerCase().includes(q) ||
+      s.project.toLowerCase().includes(q) ||
+      s.prompt.toLowerCase().includes(q)
+    );
+  }
+  return list;
+}
+
+// ── Format helpers ────────────────────────────────────
+function fmtTs(d) {
+  const x = new Date(d);
+  const m = String(x.getMonth() + 1).padStart(2, '0');
+  const day = String(x.getDate()).padStart(2, '0');
+  const hh = String(x.getHours()).padStart(2, '0');
+  const mm = String(x.getMinutes()).padStart(2, '0');
+  return `${m}/${day} ${hh}:${mm}`;
+}
+
+function fmtSize(n) {
+  if (n < 1024) return n + 'B';
+  if (n < 1024 * 1024) return (n / 1024).toFixed(0) + 'K';
+  return (n / 1024 / 1024).toFixed(1) + 'M';
+}
+
+// Returns the visible cell width of a character. CJK ideographs,
+// Hangul syllables, fullwidth forms, and most emoji render 2 cells wide
+// in modern terminals; everything else is 1. Without this every row that
+// contains Korean/Chinese/Japanese text would silently wrap, breaking the
+// fixed-column TUI layout. Based on the East Asian Width property
+// (UAX #11) compressed to the ranges that actually appear in practice.
+function charWidth(cp) {
+  if (cp < 0x1100) return 1;
+  if (
+    (cp >= 0x1100 && cp <= 0x115f) ||                 // Hangul Jamo
+    cp === 0x2329 || cp === 0x232a ||
+    (cp >= 0x2e80 && cp <= 0x303e) ||                 // CJK Radicals/Kangxi
+    (cp >= 0x3041 && cp <= 0x33ff) ||                 // Hiragana/Katakana/CJK Symbols
+    (cp >= 0x3400 && cp <= 0x4dbf) ||                 // CJK Ext A
+    (cp >= 0x4e00 && cp <= 0x9fff) ||                 // CJK Unified
+    (cp >= 0xa000 && cp <= 0xa4cf) ||                 // Yi
+    (cp >= 0xac00 && cp <= 0xd7a3) ||                 // Hangul Syllables
+    (cp >= 0xf900 && cp <= 0xfaff) ||                 // CJK Compat
+    (cp >= 0xfe30 && cp <= 0xfe4f) ||                 // CJK Compat Forms
+    (cp >= 0xff00 && cp <= 0xff60) ||                 // Fullwidth ASCII
+    (cp >= 0xffe0 && cp <= 0xffe6) ||                 // Fullwidth signs
+    (cp >= 0x1f300 && cp <= 0x1f64f) ||               // Emoji symbols
+    (cp >= 0x1f680 && cp <= 0x1f6ff) ||               // Transport/map
+    (cp >= 0x1f900 && cp <= 0x1f9ff) ||               // Supplemental symbols
+    (cp >= 0x20000 && cp <= 0x2fffd)                  // CJK Ext B-F
+  ) return 2;
+  return 1;
+}
+
+function displayWidth(s) {
+  if (!s) return 0;
+  let w = 0;
+  for (const ch of s) w += charWidth(ch.codePointAt(0));
+  return w;
+}
+
+// Pad `s` to exactly `n` display cells. If wider, truncate; if narrower,
+// right-pad with spaces. Operates on cells, not code units.
+function pad(s, n) {
+  if (!s) s = '';
+  const w = displayWidth(s);
+  if (w === n) return s;
+  if (w < n) return s + ' '.repeat(n - w);
+  // Wider than n — truncate character-by-character.
+  let out = '', cur = 0;
+  for (const ch of s) {
+    const cw = charWidth(ch.codePointAt(0));
+    if (cur + cw > n) break;
+    out += ch; cur += cw;
+  }
+  if (cur < n) out += ' '.repeat(n - cur);
+  return out;
+}
+
+// Truncate `s` so that displayWidth(out) ≤ maxWidth, appending '…' when
+// truncated. Whitespace runs (including newlines) collapse to one space.
+function trunc(s, maxWidth) {
+  if (!s) return '';
+  s = s.replace(/\s+/g, ' ').trim();
+  if (displayWidth(s) <= maxWidth) return s;
+  let out = '', cur = 0;
+  for (const ch of s) {
+    const cw = charWidth(ch.codePointAt(0));
+    if (cur + cw > maxWidth - 1) break;     // reserve 1 cell for the …
+    out += ch; cur += cw;
+  }
+  return out + '…';
+}
+
+function visLen(s) {
+  // strip ANSI escapes, then measure in display cells
+  return displayWidth(s.replace(/\x1b\[[0-9;]*m/g, ''));
+}
+
+// ── Render ────────────────────────────────────────────
+function render() {
+  if (mode === 'details') return renderDetails();
+  renderList();
+}
+
+function renderList() {
+  const W = process.stdout.columns || 100;
+  const H = process.stdout.rows || 30;
+  let out = A.clr;
+
+  // Header
+  out += ' ' + A.B + A.cyn + 'pisesh' + A.R + A.D + '  pi session bookmarks  ' + A.R;
+  out += A.gry + `${sessions.length} sessions · ${favorites.size} starred` + A.R + '\n\n';
+
+  // Tabs
+  let tabLine = ' ';
+  tabs.forEach((t, i) => {
+    if (i === tabIdx) tabLine += A.I + A.B + ' ' + t + ' ' + A.R + '  ';
+    else tabLine += A.D + ' ' + t + ' ' + A.R + '  ';
+  });
+  out += tabLine + '\n';
+  out += A.gry + '─'.repeat(Math.max(1, W - 1)) + A.R + '\n';
+
+  // Filter line
+  if (mode === 'filter' || filter) {
+    const caret = mode === 'filter' ? A.I + ' ' + A.R : '';
+    out += ' ' + A.cyn + '/' + A.R + ' ' + filter + caret + '\n';
+    out += A.gry + '─'.repeat(Math.max(1, W - 1)) + A.R + '\n';
+  }
+
+  // List
+  const list = visibleSessions();
+  if (cursor >= list.length) cursor = Math.max(0, list.length - 1);
+
+  const headerH = (mode === 'filter' || filter) ? 7 : 5;
+  const footerH = 4;
+  const usable = Math.max(3, H - headerH - footerH);
+  const start = Math.max(0, Math.min(cursor - Math.floor(usable / 2), list.length - usable));
+  const end = Math.min(list.length, start + usable);
+
+  if (list.length === 0) {
+    let hint;
+    if (filter) {
+      hint = '(no matches — Esc clears filter)';
+    } else if (tabs[tabIdx].startsWith('★')) {
+      hint = '(no favorites yet — press f on any session to star it)';
+    } else if (tabs[tabIdx] === 'Today') {
+      hint = '(no sessions today — Tab to see All)';
+    } else {
+      hint = '(no sessions in this view)';
+    }
+    out += '\n ' + A.D + hint + A.R + '\n';
+  } else {
+    for (let i = start; i < end; i++) {
+      const s = list[i];
+      const sel = i === cursor;
+      const star = s.favored ? A.yel + '★' + A.R : ' ';
+      const arrow = sel ? A.cyn + '▶' + A.R : ' ';
+      const ts = A.gry + fmtTs(s.mtime) + A.R;
+      const cwd = A.mag + pad(shortCwd(s.cwd), 14) + A.R;
+      const badge = s.isCurrent ? A.grn + A.B + '[NOW]' + A.R + ' ' : '';
+      const promptMax = Math.max(20, W - 38 - (s.isCurrent ? 7 : 0));
+      const prompt = trunc(s.prompt || `(no prompt) ${s.id.slice(0, 8)}`, promptMax);
+      const rowText = ` ${arrow} ${star} ${ts}  ${cwd}  ${badge}${prompt}`;
+      if (sel) {
+        const pad2 = ' '.repeat(Math.max(0, W - visLen(rowText) - 1));
+        out += A.bgBlu + rowText + pad2 + A.R + '\n';
+      } else {
+        out += rowText + '\n';
+      }
+    }
+  }
+
+  // Pad bottom to push footer down
+  const linesUsed = (end - start) || 1;
+  for (let i = 0; i < usable - linesUsed; i++) out += '\n';
+
+  // Footer
+  out += A.gry + '─'.repeat(Math.max(1, W - 1)) + A.R + '\n';
+  out += ' ' + A.D + '↑↓' + A.R + ' move  '
+      + A.D + 'Tab' + A.R + ' next tab  '
+      + A.D + 'f' + A.R + ' star  '
+      + A.D + 'Enter' + A.R + ' resume  '
+      + A.D + 'd' + A.R + ' details  '
+      + A.D + '/' + A.R + ' search  '
+      + A.D + 'r' + A.R + ' refresh  '
+      + A.D + 'q/Esc' + A.R + ' quit' + '\n';
+
+  process.stdout.write(out);
+}
+
+function renderDetails() {
+  const W = process.stdout.columns || 100;
+  const list = visibleSessions();
+  const s = list[cursor];
+  let out = A.clr;
+  out += ' ' + A.B + A.cyn + 'pisesh' + A.R + A.D + '  session details' + A.R + '\n\n';
+  if (!s) { out += ' (no session)\n'; process.stdout.write(out); return; }
+
+  const row = (k, v, color = A.R) => ` ${A.D}${pad(k, 11)}${A.R} ${color}${v}${A.R}\n`;
+  out += row('id', s.id, A.cyn);
+  if (s.isCurrent) out += row('current', '● this is the attached pi session', A.grn);
+  out += row('starred', s.favored ? '★ yes' : '☆ no', s.favored ? A.yel : A.gry);
+  out += row('started', new Date(s.ts).toLocaleString());
+  out += row('updated', new Date(s.mtime).toLocaleString());
+  out += row('cwd', s.cwd, A.mag);
+  out += row('project', s.project);
+  out += row('size', fmtSize(s.size));
+  out += row('file', s.file, A.gry);
+  out += '\n ' + A.D + 'first prompt:' + A.R + '\n';
+  const prompt = s.prompt || '(no user prompt found in first 96KB)';
+  const wrapped = wrap(prompt, W - 4);
+  for (const line of wrapped) out += '   ' + line + '\n';
+
+  out += '\n' + A.gry + '─'.repeat(Math.max(1, W - 1)) + A.R + '\n';
+  out += ' ' + A.D + 'Enter' + A.R + ' resume  '
+      + A.D + 'f' + A.R + ' star  '
+      + A.D + 'c' + A.R + ' copy id  '
+      + A.D + 'Esc/d/q' + A.R + ' back' + '\n';
+
+  process.stdout.write(out);
+}
+
+function wrap(text, width) {
+  if (!text) return [''];
+  const out = [];
+  let line = '';
+  for (const word of text.split(/\s+/)) {
+    if ((line + ' ' + word).trim().length > width) {
+      if (line) out.push(line);
+      line = word;
+    } else line = (line + ' ' + word).trim();
+  }
+  if (line) out.push(line);
+  return out.slice(0, 10); // cap at 10 lines
+}
+
+// ── Input ─────────────────────────────────────────────
+function setupInput() {
+  readline.emitKeypressEvents(process.stdin);
+  if (process.stdin.isTTY) process.stdin.setRawMode(true);
+  process.stdin.resume();
+  // Enter alt screen FIRST, then hide cursor. The terminal saves the user's
+  // visible buffer + cursor position; we restore both on exit.
+  process.stdout.write(A.enterAlt + A.hideC);
+
+  process.stdin.on('keypress', (str, key) => {
+    try {
+      if (mode === 'filter') handleFilter(str, key);
+      else if (mode === 'details') handleDetails(str, key);
+      else handleList(str, key);
+      render();
+    } catch (e) {
+      process.stdout.write(A.showC);
+      console.error('input error:', e);
+    }
+  });
+
+  process.stdout.on('resize', render);
+  // Safety net: even on unexpected exit (uncaught error, signal), leave alt
+  // screen and re-show the hardware cursor so the user's terminal isn't
+  // left in a broken state.
+  process.on('exit', () => process.stdout.write(A.exitAlt + A.showC));
+  process.on('SIGINT', () => quit());
+  process.on('SIGTERM', () => quit());
+}
+
+function handleList(str, key) {
+  const list = visibleSessions();
+  const k = key.name;
+
+  if (key.ctrl && k === 'c') return quit();
+  if (k === 'q') return quit();
+  // Esc: clears filter first (one-step back-out), otherwise quits.
+  // Matches `q` so muscle memory works either way.
+  if (k === 'escape') {
+    if (filter) { filter = ''; cursor = 0; return; }
+    return quit();
+  }
+  if (k === 'up' || k === 'k') cursor = Math.max(0, cursor - 1);
+  else if (k === 'down' || k === 'j') cursor = Math.min(list.length - 1, cursor + 1);
+  else if (k === 'tab' || (k === 'right' && !filter) || k === 'l') {
+    tabIdx = (tabIdx + 1) % tabs.length;
+    cursor = 0;
+  }
+  else if ((k === 'left' && !filter) || k === 'h') {
+    tabIdx = (tabIdx - 1 + tabs.length) % tabs.length;
+    cursor = 0;
+  }
+  else if (k === 'f' || str === ' ') {
+    const s = list[cursor];
+    if (s) {
+      if (s.favored) favorites.delete(s.id);
+      else favorites.add(s.id);
+      saveFavorites(favorites);
+    }
+  }
+  else if (k === 'return') resumeSession(list[cursor]);
+  else if (k === 'd') { if (list[cursor]) mode = 'details'; }
+  else if (str === '/') { mode = 'filter'; }
+  else if (k === 'r') { sessions = scanSessions(); cursor = 0; }
+  else if (k === 'home') cursor = 0;
+  else if (k === 'end') cursor = list.length - 1;
+  else if (k === 'pageup') cursor = Math.max(0, cursor - 10);
+  else if (k === 'pagedown') cursor = Math.min(list.length - 1, cursor + 10);
+}
+
+function handleFilter(str, key) {
+  const k = key.name;
+  if (k === 'return' || k === 'escape') { mode = 'list'; return; }
+  if (k === 'backspace') { filter = filter.slice(0, -1); cursor = 0; return; }
+  if (key.ctrl && k === 'c') return quit();
+  if (key.ctrl && k === 'u') { filter = ''; cursor = 0; return; }
+  if (str && str.length === 1 && !key.ctrl) { filter += str; cursor = 0; }
+}
+
+function handleDetails(str, key) {
+  const k = key.name;
+  const s = visibleSessions()[cursor];
+  if (k === 'escape' || k === 'q' || k === 'd') { mode = 'list'; return; }
+  if (key.ctrl && k === 'c') return quit();
+  if (k === 'return') return resumeSession(s);
+  if (k === 'f' && s) {
+    if (s.favored) favorites.delete(s.id); else favorites.add(s.id);
+    saveFavorites(favorites);
+  }
+  if (k === 'c' && s) {
+    // Try clipboard via clip.exe (WSL) or pbcopy/xclip
+    tryCopy(s.id);
+  }
+}
+
+function tryCopy(text) {
+  const tryCmd = (cmd, args) => {
+    try {
+      const p = spawn(cmd, args, { stdio: ['pipe', 'ignore', 'ignore'] });
+      p.stdin.end(text);
+      return true;
+    } catch { return false; }
+  };
+  // WSL clip.exe first, then pbcopy, then xclip
+  tryCmd('clip.exe', []) || tryCmd('pbcopy', []) || tryCmd('xclip', ['-selection', 'clipboard']);
+}
+
+// ── Actions ───────────────────────────────────────────
+function resumeSession(s) {
+  if (!s) return;
+  // Leave alt screen + show cursor so the spawned pi takes over a clean
+  // main-buffer terminal (it will manage its own alt screen).
+  process.stdout.write(A.exitAlt + A.showC);
+  if (process.stdin.isTTY) process.stdin.setRawMode(false);
+  process.stdin.pause();
+
+  const projectDir = path.dirname(s.file);
+  // Spawn pi in the original cwd with the session restored
+  const child = spawn('pi', ['--session', s.id, '--session-dir', projectDir], {
+    stdio: 'inherit',
+    cwd: fs.existsSync(s.cwd) ? s.cwd : process.cwd(),
+  });
+  child.on('exit', code => process.exit(code || 0));
+  child.on('error', err => {
+    console.error('Failed to spawn pi:', err.message);
+    process.exit(1);
+  });
+}
+
+function quit() {
+  // Restore user's pre-pisesh terminal (alt screen exits + cursor back).
+  // No explicit clear needed — the terminal restoration handles it and the
+  // jump back to the previous prompt feels instant.
+  process.stdout.write(A.exitAlt + A.showC);
+  if (process.stdin.isTTY) process.stdin.setRawMode(false);
+  process.exit(0);
+}
+
+// ── Main ──────────────────────────────────────────────
+function printHelp() {
+  console.log(`pisesh — pi session bookmarks & resume TUI
+
+Usage:
+  pisesh                 Open interactive TUI
+  pisesh --list, -l      List starred session IDs (one per line)
+  pisesh --json          Dump favorites file as JSON
+  pisesh --star <id>     Add a session id (partial UUID ok) to favorites
+  pisesh --unstar <id>   Remove a session id from favorites
+  pisesh --help, -h      This help
+
+TUI keys:
+  ↑↓ / j k         move cursor
+  Tab / h l        switch tab  (★ Favorites → Today → All)
+  f / Space        toggle favorite
+  Enter            resume session (spawns 'pi --session …')
+  d                show details
+  /                search (id / project / prompt; Esc clears first, then quits)
+  r                rescan session files
+  q / Esc / Ctrl-C quit
+
+Files:
+  Favorites: ${FAV_FILE}
+  Sessions : ${SESSIONS_ROOT}/<project>/<ts>_<uuid>.jsonl`);
+}
+
+function findIdMatch(prefix) {
+  sessions = scanSessions();
+  const matches = sessions.filter(s => s.id.startsWith(prefix) || s.id.includes(prefix));
+  return matches.map(s => s.id);
+}
+
+function main() {
+  const argv = process.argv.slice(2);
+
+  if (argv.includes('-h') || argv.includes('--help')) { printHelp(); return; }
+  if (argv.includes('-l') || argv.includes('--list')) {
+    [...favorites].forEach(id => console.log(id));
+    return;
+  }
+  if (argv.includes('--json')) {
+    console.log(JSON.stringify({ ids: [...favorites], updated: new Date().toISOString() }, null, 2));
+    return;
+  }
+
+  const starIdx = argv.indexOf('--star');
+  if (starIdx >= 0 && argv[starIdx + 1]) {
+    const ids = findIdMatch(argv[starIdx + 1]);
+    if (ids.length === 0) { console.error('no matching session'); process.exit(2); }
+    if (ids.length > 1) { console.error('ambiguous:'); ids.forEach(i => console.error(' ', i)); process.exit(2); }
+    favorites.add(ids[0]); saveFavorites(favorites);
+    console.log('★ starred', ids[0]); return;
+  }
+  const unstarIdx = argv.indexOf('--unstar');
+  if (unstarIdx >= 0 && argv[unstarIdx + 1]) {
+    const ids = findIdMatch(argv[unstarIdx + 1]);
+    if (ids.length === 0) { console.error('no matching session'); process.exit(2); }
+    if (ids.length > 1) { console.error('ambiguous:'); ids.forEach(i => console.error(' ', i)); process.exit(2); }
+    favorites.delete(ids[0]); saveFavorites(favorites);
+    console.log('☆ unstarred', ids[0]); return;
+  }
+
+  if (!process.stdin.isTTY) {
+    console.error('pisesh: stdin is not a TTY (use a terminal to run the TUI). Try --list or --help.');
+    process.exit(1);
+  }
+
+  sessions = scanSessions();
+  if (sessions.length === 0) {
+    console.error('pisesh: no sessions found under', SESSIONS_ROOT);
+    process.exit(1);
+  }
+  setupInput();
+  render();
+}
+
+main();

package/extensions/sesh.ts

@@ -0,0 +1,83 @@
+/**
+ * pisesh slash command
+ *
+ * Registers `/sesh` inside pi.
+ *
+ * Behavior:
+ *   1. Pauses pi's TUI (releases the terminal)
+ *   2. Spawns the external `pisesh` TUI (bookmark/resume picker)
+ *   3. When pisesh exits — whether the user resumed a nested session and quit it,
+ *      or just pressed `q` — control returns to the original pi session and the
+ *      TUI is restored.
+ *
+ * Companion CLI tool: ~/.pi/bin/pisesh   (single-file Node TUI, no deps)
+ * Favorites file:     ~/.pi/agent/favorites.json
+ */
+
+import { spawn } from "node:child_process";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+function runPisesh(currentSessionId: string | undefined): Promise<number | null> {
+  return new Promise((resolve) => {
+    // stdio:"inherit" hands the real TTY to pisesh. pi's tui.stop() has
+    // already detached so this is safe.
+    // PISESH_CURRENT_SESSION lets pisesh flag the row that belongs to the
+    // pi instance that just spawned it (rendered with a [NOW] badge).
+    const child = spawn("pisesh", [], {
+      stdio: "inherit",
+      env: {
+        ...process.env,
+        ...(currentSessionId ? { PISESH_CURRENT_SESSION: currentSessionId } : {}),
+      },
+    });
+    child.on("exit", (code) => resolve(code));
+    child.on("error", (err) => {
+      // Surface a readable error in the terminal before we re-render.
+      process.stdout.write(`\x1b[31mpisesh failed to launch: ${err.message}\x1b[0m\n`);
+      resolve(127);
+    });
+  });
+}
+
+export default function (pi: ExtensionAPI) {
+  pi.registerCommand("sesh", {
+    description: "Browse, star, and resume pi sessions (opens pisesh TUI)",
+    handler: async (_args, ctx) => {
+      if (!ctx.hasUI) {
+        ctx.ui?.notify?.("/sesh requires interactive UI", "warning");
+        return;
+      }
+
+      let currentId: string | undefined;
+      try {
+        currentId = ctx.sessionManager?.getSessionId?.();
+      } catch {
+        currentId = undefined;
+      }
+
+      const code = await ctx.ui.custom<number | null>((tui, _theme, _kb, done) => {
+        // Hand over the terminal
+        tui.stop();
+        process.stdout.write("\x1b[2J\x1b[H");
+
+        runPisesh(currentId).then((exitCode) => {
+          // Restore pi's TUI
+          tui.start();
+          tui.requestRender(true);
+          done(exitCode);
+        });
+
+        // Return a no-op component (custom() requires one synchronously)
+        return { render: () => [], invalidate: () => {} };
+      });
+
+      if (code === 0 || code === null) {
+        ctx.ui.notify("Returned from pisesh", "info");
+      } else if (code === 127) {
+        ctx.ui.notify("pisesh not found on PATH", "error");
+      } else {
+        ctx.ui.notify(`pisesh exited with code ${code}`, "warning");
+      }
+    },
+  });
+}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "pisesh",
+  "version": "0.1.0",
+  "description": "Bookmark, search, and resume pi coding-agent sessions with a fast keyboard-driven TUI.",
+  "keywords": [
+    "pi",
+    "pi-coding-agent",
+    "session",
+    "bookmark",
+    "tui",
+    "cli",
+    "ai",
+    "coding-agent",
+    "resume",
+    "favorites"
+  ],
+  "homepage": "https://github.com/Blue-B/pisesh#readme",
+  "bugs": {
+    "url": "https://github.com/Blue-B/pisesh/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Blue-B/pisesh.git"
+  },
+  "license": "MIT",
+  "author": "Blue-B <source_vs@naver.com>",
+  "type": "commonjs",
+  "bin": {
+    "pisesh": "./bin/pisesh"
+  },
+  "files": [
+    "bin/",
+    "extensions/",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "pi": {
+    "extensions": [
+      "./extensions/sesh.ts"
+    ]
+  },
+  "scripts": {
+    "test": "node --check bin/pisesh && echo 'pisesh: syntax OK'",
+    "prepublishOnly": "npm test"
+  }
+}