pi-extensions 0.1.33 → 0.1.35

package/README.md

@@ -13,6 +13,7 @@ Personal extensions for the [Pi coding agent](https://github.com/badlogic/pi-mon
 | [/usage](usage-extension/) | 📊 Usage statistics dashboard. See cost, tokens, and messages by provider/model across Today, This Week, Last Week, and All Time — with a compact view for narrow terminals |
 | [/paste](raw-paste/) | Paste editable text, not [paste #1 +21 lines]. Running `/paste` with optional keybinding |
 | [/code](code-actions/) | Pick code blocks or inline snippets from assistant messages to copy, insert, or run with `/code` |
+| [session-recap](session-recap/) | One-line recap above the editor when you refocus the terminal (or after idle). Keeps you in flow while multi-clauding |
 | [arcade](arcade/) | Play minigames while your tests run: 👾 sPIce-invaders, 👻 picman, 🏓 ping, 🧩 tetris, 🍄 mario-not |
 
 ## Skills
@@ -60,6 +61,7 @@ If you keep a local clone, add extensions to your `~/.pi/agent/settings.json`:
     "~/pi-extensions/agent-guidance/agent-guidance.ts",
     "~/pi-extensions/raw-paste",
     "~/pi-extensions/code-actions",
+    "~/pi-extensions/session-recap",
     "~/pi-extensions/usage-extension"
   ]
 }

package/files-widget/CHANGELOG.md

@@ -4,6 +4,19 @@ All notable changes to this extension will be documented in this file.
 
 ## [Unreleased]
 
+## [0.1.18] - 2026-04-19
+
+### Changed
+- Show symlinks with a `↗` marker in the `/readfiles` tree.
+
+### Fixed
+- Let `/readfiles` navigate into directory symlinks in both non-git folders and git repos instead of rendering them as inert files or empty directories.
+- Guard symlink directory scanning against ancestor cycles so links like `foo -> .` or `foo -> ..` don't recurse forever.
+- Treat git-tracked and untracked directory symlinks as lazily scannable directories rather than plain files.
+
+### Thanks
+- Thanks to @xapids for reporting the original macOS symlink navigation issue ([#9](https://github.com/tmustier/pi-extensions/issues/9)).
+
 ## [0.1.17] - 2026-04-19
 
 ### Changed

package/files-widget/README.md

@@ -2,6 +2,8 @@
 
 In-terminal file browser and diff viewer widget for Pi. Navigate files, view diffs, select code, and send comments to the agent without leaving the terminal and without interrupting your agent.
 
+Directory symlinks are shown with a `↗` marker and can be expanded like normal folders.
+
 <video controls autoplay loop muted playsinline>
   <source src="demo.mp4" type="video/mp4" />
 </video>

package/files-widget/browser.ts

@@ -1,6 +1,7 @@
 import type { Theme } from "@mariozechner/pi-coding-agent";
 import { Key, matchesKey, truncateToWidth } from "@mariozechner/pi-tui";
-import { readdir, readFile, stat } from "node:fs/promises";
+import { lstatSync, realpathSync, statSync } from "node:fs";
+import { readdir, readFile, realpath, stat } from "node:fs/promises";
 import { homedir } from "node:os";
 import { basename, join, relative, resolve, sep } from "node:path";
 
@@ -104,6 +105,51 @@ function getNodeDepth(node: FileNode, cwd: string): number {
   return rel.split(sep).length;
 }
 
+function safeRealPathSync(path: string): string {
+  try {
+    return realpathSync(path);
+  } catch {
+    return resolve(path);
+  }
+}
+
+function getPathInfoSync(path: string): { isDirectory: boolean; isSymlink: boolean; realPath?: string } {
+  try {
+    const linkStat = lstatSync(path);
+    const isSymlink = linkStat.isSymbolicLink();
+    const targetStat = isSymlink ? statSync(path) : linkStat;
+    return {
+      isDirectory: targetStat.isDirectory(),
+      isSymlink,
+      realPath: targetStat.isDirectory() ? safeRealPathSync(path) : undefined,
+    };
+  } catch {
+    return { isDirectory: false, isSymlink: false };
+  }
+}
+
+async function getPathInfo(path: string, isSymlink: boolean): Promise<{ isDirectory: boolean; isSymlink: boolean; realPath?: string }> {
+  try {
+    const targetStat = await stat(path);
+    return {
+      isDirectory: targetStat.isDirectory(),
+      isSymlink,
+      realPath: targetStat.isDirectory() ? await realpath(path).catch(() => resolve(path)) : undefined,
+    };
+  } catch {
+    return { isDirectory: false, isSymlink };
+  }
+}
+
+function hasAncestorRealPath(node: FileNode | undefined, realPath: string): boolean {
+  let current = node;
+  while (current) {
+    if (current.realPath === realPath) return true;
+    current = current.parent;
+  }
+  return false;
+}
+
 function shouldSafeMode(cwd: string): boolean {
   const resolved = resolve(cwd);
   const home = resolve(homedir());
@@ -183,14 +229,19 @@ function formatNodeMeta(node: FileNode, theme: Theme): string {
   return parts.length > 0 ? ` ${parts.join(" ")}` : "";
 }
 
+function withSymlinkMarker(label: string, node: FileNode, theme: Theme): string {
+  return node.isSymlink ? `${label}${theme.fg("dim", " ↗")}` : label;
+}
+
 function formatNodeName(node: FileNode, theme: Theme): string {
-  if (isIgnoredStatus(node.gitStatus)) return theme.fg("dim", node.name);
+  if (isIgnoredStatus(node.gitStatus)) return withSymlinkMarker(theme.fg("dim", node.name), node, theme);
   if (node.isDirectory) {
     const label = node.hasChangedChildren ? theme.fg("warning", node.name) : theme.fg("accent", node.name);
-    return node.loading ? `${label}${theme.fg("dim", " ⏳")}` : label;
+    const rendered = withSymlinkMarker(label, node, theme);
+    return node.loading ? `${rendered}${theme.fg("dim", " ⏳")}` : rendered;
   }
-  if (node.gitStatus) return theme.fg("warning", node.name);
-  return node.name;
+  if (node.gitStatus) return withSymlinkMarker(theme.fg("warning", node.name), node, theme);
+  return withSymlinkMarker(node.name, node, theme);
 }
 
 function collapseAllExcept(node: FileNode, keep: Set<FileNode>): void {
@@ -227,6 +278,7 @@ export function createFileBrowser(
       name: ".",
       path: cwd,
       isDirectory: true,
+      realPath: safeRealPathSync(cwd),
       children: undefined,
       expanded: true,
       hasChangedChildren: false,
@@ -350,6 +402,14 @@ export function createFileBrowser(
   }
 
   function shouldAutoScan(depth: number): boolean {
+    // In git repos the main tree comes from git file lists, not from filesystem
+    // crawling. If the user expands a symlinked directory inside that tree, only
+    // scan one level on demand; nested directories stay lazy until explicitly
+    // expanded so links into large trees (iCloud/Drive/$HOME) don't trigger a
+    // broad recursive crawl.
+    if (repo) {
+      return false;
+    }
     if (browser.scanState.mode === "safe") {
       return depth <= 0;
     }
@@ -399,31 +459,74 @@ export function createFileBrowser(
       for (const entry of sorted) {
         if (ignored.has(entry.name) || entry.name.startsWith(".")) continue;
         const fullPath = join(node.path, entry.name);
+        const childDepth = depth + 1;
+
         if (entry.isDirectory()) {
           const dirNode: FileNode = {
             name: entry.name,
             path: fullPath,
             isDirectory: true,
+            realPath: await realpath(fullPath).catch(() => resolve(fullPath)),
+            parent: node,
             children: undefined,
-            expanded: depth + 1 < 1,
+            expanded: childDepth < 1,
             hasChangedChildren: false,
           };
           dirs.push(dirNode);
           browser.nodeByPath.set(fullPath, dirNode);
-          if (shouldAutoScan(depth + 1)) {
-            enqueueScan(dirNode, depth + 1);
+          if (shouldAutoScan(childDepth)) {
+            enqueueScan(dirNode, childDepth);
           }
-        } else {
-          const fileNode: FileNode = {
+          continue;
+        }
+
+        if (entry.isSymbolicLink()) {
+          const pathInfo = await getPathInfo(fullPath, true);
+          if (pathInfo.isDirectory) {
+            const isCycle = pathInfo.realPath ? hasAncestorRealPath(node, pathInfo.realPath) : false;
+            const dirNode: FileNode = {
+              name: entry.name,
+              path: fullPath,
+              isDirectory: true,
+              isSymlink: true,
+              realPath: pathInfo.realPath,
+              parent: node,
+              children: isCycle ? [] : undefined,
+              expanded: childDepth < 1,
+              hasChangedChildren: false,
+            };
+            dirs.push(dirNode);
+            browser.nodeByPath.set(fullPath, dirNode);
+            if (!isCycle && shouldAutoScan(childDepth)) {
+              enqueueScan(dirNode, childDepth);
+            }
+            continue;
+          }
+
+          const symlinkFileNode: FileNode = {
             name: entry.name,
             path: fullPath,
             isDirectory: false,
+            isSymlink: true,
+            parent: node,
             agentModified: agentModifiedFiles.has(fullPath),
           };
-          files.push(fileNode);
-          browser.nodeByPath.set(fullPath, fileNode);
-          queueLineCount(fileNode);
+          files.push(symlinkFileNode);
+          browser.nodeByPath.set(fullPath, symlinkFileNode);
+          queueLineCount(symlinkFileNode);
+          continue;
         }
+
+        const fileNode: FileNode = {
+          name: entry.name,
+          path: fullPath,
+          isDirectory: false,
+          parent: node,
+          agentModified: agentModifiedFiles.has(fullPath),
+        };
+        files.push(fileNode);
+        browser.nodeByPath.set(fullPath, fileNode);
+        queueLineCount(fileNode);
       }
 
       node.children = [...dirs, ...files];
@@ -483,14 +586,13 @@ export function createFileBrowser(
 
   function applyGitUpdates(): void {
     for (const node of browser.nodeByPath.values()) {
-      if (node.isDirectory) continue;
       const relPath = normalizeGitPath(relative(cwd, node.path));
       node.gitStatus = gitStatus.get(relPath);
       node.diffStats = diffStats.get(relPath);
     }
   }
 
-  function ensureFileNode(relPath: string): FileNode | null {
+  function ensureNode(relPath: string): FileNode | null {
     if (!browser.root) return null;
     let normalized = relPath.trim();
     if (!normalized) return null;
@@ -517,6 +619,8 @@ export function createFileBrowser(
           name: part,
           path: dirPath,
           isDirectory: true,
+          realPath: safeRealPathSync(dirPath),
+          parent: current,
           children: [],
           expanded: depth < 1,
           hasChangedChildren: false,
@@ -536,10 +640,36 @@ export function createFileBrowser(
     const existing = browser.nodeByPath.get(filePath);
     if (existing) return existing;
 
+    const pathInfo = getPathInfoSync(filePath);
+    if (pathInfo.isDirectory) {
+      const isCycle = pathInfo.realPath ? hasAncestorRealPath(current, pathInfo.realPath) : false;
+      const dirNode: FileNode = {
+        name: fileName,
+        path: filePath,
+        isDirectory: true,
+        isSymlink: pathInfo.isSymlink,
+        realPath: pathInfo.realPath ?? safeRealPathSync(filePath),
+        parent: current,
+        children: pathInfo.isSymlink && !isCycle ? undefined : [],
+        expanded: false,
+        hasChangedChildren: false,
+        gitStatus: gitStatus.get(normalized),
+        diffStats: diffStats.get(normalized),
+      };
+
+      current.children ??= [];
+      current.children.push(dirNode);
+      sortChildren(current);
+      browser.nodeByPath.set(filePath, dirNode);
+      return dirNode;
+    }
+
     const fileNode: FileNode = {
       name: fileName,
       path: filePath,
       isDirectory: false,
+      isSymlink: pathInfo.isSymlink,
+      parent: current,
       gitStatus: gitStatus.get(normalized),
       agentModified: agentModifiedFiles.has(filePath),
       diffStats: diffStats.get(normalized),
@@ -555,11 +685,13 @@ export function createFileBrowser(
   function addUntrackedNodes(): void {
     for (const [relPath, status] of gitStatus.entries()) {
       if (!isUntrackedStatus(status)) continue;
-      const node = ensureFileNode(relPath);
+      const node = ensureNode(relPath);
       if (node) {
         node.gitStatus = status;
         node.diffStats = diffStats.get(relPath);
-        queueLineCount(node, true);
+        if (!node.isDirectory) {
+          queueLineCount(node, true);
+        }
       }
     }
   }
@@ -673,7 +805,7 @@ export function createFileBrowser(
   function toggleDir(node: FileNode): void {
     if (node.isDirectory) {
       node.expanded = !node.expanded;
-      if (!repo && node.expanded && node.children === undefined) {
+      if (node.expanded && node.children === undefined) {
         enqueueScan(node, getNodeDepth(node, cwd), true);
       }
       refreshLists();

package/files-widget/file-tree.ts

@@ -1,4 +1,4 @@
-import { statSync } from "node:fs";
+import { lstatSync, realpathSync, statSync } from "node:fs";
 import { join } from "node:path";
 
 import { MAX_TREE_DEPTH } from "./constants";
@@ -6,11 +6,26 @@ import type { DiffStats, FileNode, FlatNode } from "./types";
 
 const collator = new Intl.Collator(undefined, { sensitivity: "base" });
 
-function isDirectoryPath(path: string): boolean {
+function safeRealPathSync(path: string): string {
   try {
-    return statSync(path).isDirectory();
+    return realpathSync(path);
   } catch {
-    return false;
+    return path;
+  }
+}
+
+function getPathInfo(path: string): { isDirectory: boolean; isSymlink: boolean; realPath?: string } {
+  try {
+    const linkStat = lstatSync(path);
+    const isSymlink = linkStat.isSymbolicLink();
+    const targetStat = isSymlink ? statSync(path) : linkStat;
+    return {
+      isDirectory: targetStat.isDirectory(),
+      isSymlink,
+      realPath: targetStat.isDirectory() ? safeRealPathSync(path) : undefined,
+    };
+  } catch {
+    return { isDirectory: false, isSymlink: false };
   }
 }
 
@@ -105,6 +120,7 @@ export function buildFileTreeFromPaths(
     name: ".",
     path: cwd,
     isDirectory: true,
+    realPath: safeRealPathSync(cwd),
     children: [],
     expanded: true,
     hasChangedChildren: false,
@@ -145,6 +161,8 @@ export function buildFileTreeFromPaths(
           name: part,
           path: join(cwd, relPath),
           isDirectory: true,
+          realPath: safeRealPathSync(join(cwd, relPath)),
+          parent: current,
           children: [],
           expanded: depth < 1,
           hasChangedChildren: false,
@@ -178,14 +196,18 @@ export function buildFileTreeFromPaths(
       continue;
     }
 
-    const isDirEntry = normalized.endsWith("/") || isDirectoryPath(filePath);
+    const pathInfo = getPathInfo(filePath);
+    const isDirEntry = normalized.endsWith("/") || pathInfo.isDirectory;
     if (isDirEntry) {
       const depth = parts.length;
       const dirNode: FileNode = {
         name: fileName,
         path: filePath,
         isDirectory: true,
-        children: [],
+        isSymlink: pathInfo.isSymlink,
+        realPath: pathInfo.realPath ?? safeRealPathSync(filePath),
+        parent: current,
+        children: pathInfo.isSymlink ? undefined : [],
         expanded: depth < 1,
         hasChangedChildren: false,
         gitStatus: fileGitStatus,
@@ -202,6 +224,8 @@ export function buildFileTreeFromPaths(
       name: fileName,
       path: filePath,
       isDirectory: false,
+      isSymlink: pathInfo.isSymlink,
+      parent: current,
       gitStatus: fileGitStatus,
       agentModified: agentModified.has(filePath),
       diffStats: fileDiffStats,

package/files-widget/index.ts

@@ -70,7 +70,7 @@ export default function editorExtension(pi: ExtensionAPI): void {
     },
   });
 
-  pi.registerCommand("review", {
+  pi.registerCommand("readfiles-review", {
     description: "Open tuicr to review changes and send feedback to agent",
     handler: async (_args, ctx) => {
       if (!hasCommand("tuicr")) {
@@ -105,7 +105,7 @@ export default function editorExtension(pi: ExtensionAPI): void {
     },
   });
 
-  pi.registerCommand("diff", {
+  pi.registerCommand("readfiles-diff", {
     description: "Open critique to view diffs",
     handler: async (args, ctx) => {
       if (!hasCommand("bun")) {

package/files-widget/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tmustier/pi-files-widget",
-  "version": "0.1.17",
+  "version": "0.1.18",
   "description": "In-terminal file browser and viewer for Pi.",
   "license": "MIT",
   "author": "Thomas Mustier",

package/files-widget/types.ts

@@ -7,6 +7,9 @@ export interface FileNode {
   name: string;
   path: string;
   isDirectory: boolean;
+  isSymlink?: boolean;
+  realPath?: string;
+  parent?: FileNode;
   children?: FileNode[];
   expanded?: boolean;
   gitStatus?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-extensions",
-  "version": "0.1.33",
+  "version": "0.1.35",
   "license": "MIT",
   "private": false,
   "keywords": [
@@ -18,6 +18,7 @@
       "./files-widget/index.ts",
       "./raw-paste/index.ts",
       "./pi-ralph-wiggum/index.ts",
+      "./session-recap/index.ts",
       "./tab-status/tab-status.ts",
       "./usage-extension/index.ts"
     ],

package/session-recap/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+## v0.1.0
+
+- Initial release.
+- Two triggers: DECSET `?1004` focus reporting + idle fallback on `turn_end`.
+- Auto-recap on `/resume` and `/fork`.
+- `/recap` command for manual generation.
+- Defaults to the user's active model with `reasoning: "minimal"` when supported, for zero-auth-surprise behaviour across built-in and custom providers.
+- Flags: `--recap-idle-seconds`, `--recap-focus-min-seconds`, `--recap-disable-focus`, `--recap-disable`, `--recap-model`.
+- Draft stamping by branch-leaf id to avoid regenerating on focus-out/in churn without new session activity.
+- Idle fallback armed on `turn_end` rather than `agent_end` so errored/aborted turns still get a recap.
+- Robust focus-event parser that advances through its buffer so completed sequences never fire twice across chunk boundaries.
+- Per-call `AbortController` ownership so late-completing aborted requests can't clear state for a newer in-flight request.
+- Quick refocus (< `--recap-focus-min-seconds`) now also cancels any in-flight focus draft, preventing a slow model response from bypassing the suppression.

package/session-recap/DESIGN.md

@@ -0,0 +1,173 @@
+# session-recap — design & plan
+
+> Status: **v0.1.0 — initial release**  ·  Lives in `tmustier/pi-extensions/session-recap/`
+> Mirrors the [Claude Code session recap feature](https://x.com/ClaudeDevs) for Pi.
+
+## Summary
+
+When you switch focus away from a Pi session and come back, Pi drops a one-line
+recap above the editor so you can re-enter flow without re-reading scrollback.
+Targets the "multi-clauding / multi-pi" workflow where several agent sessions
+run in parallel tabs.
+
+```
+✦ recap
+recap: Migrated 4 of 7 billing tables to the v2 schema; invoices.ts still fails
+its FK constraint. Next: fix the foreign key on line 142.
+```
+
+## Triggers
+
+| Trigger | Detection | Behaviour |
+|---|---|---|
+| Terminal focus out → in | DECSET `?1004` → `ESC[O` / `ESC[I` on stdin | Draft a recap in background on focus-out; reveal on focus-in if the out-duration ≥ `--recap-focus-min-seconds` (default 3s). |
+| Idle after turn ends | `setTimeout(idleMs)` armed on `turn_end` | Generate and immediately show after `--recap-idle-seconds` (default 45s) of no user input. Idle path is the fallback for terminals without focus reporting. |
+| `/resume` (and `/fork`) | `session_start { reason: "resume" \| "fork" }` | Auto-recap the prior session so you know where you left off. |
+| Manual | `/recap` command | Generate now, bypass the activity gate. |
+
+All four cancel each other cleanly via an `AbortController`; the next `input`,
+`agent_start`, or new turn clears the widget.
+
+## Display
+
+- `ctx.ui.setWidget("session-recap", [...], { placement: "aboveEditor" })`
+- Two lines: accent-bold `✦ recap` header + dim one-liner body.
+- Cleared on: user input, new turn start, session reload, session shutdown.
+- **No session persistence.** Recap lives only in the widget for the active session.
+
+## Model selection — decision
+
+Default must not surprise users with auth/login issues.
+
+**Decision:** default to the **currently active model** with **`reasoning: "minimal"`** where supported. Trust the user's model choice — no auto-fallback to a cheap tier. If they're on Opus 4-7 the recap uses Opus 4-7. It's the only way to guarantee reliable generation across built-in + custom providers.
+
+- Primary: `ctx.model` (whatever the user is running right now).
+- Reasoning: pass `reasoningEffort: "minimal"` when `model.reasoning === true`; omit entirely otherwise.
+  - Pi's own `setThinkingLevel` already clamps to model capabilities — we follow the same rule.
+  - Some custom providers may not honour `reasoningEffort`; that's fine, they'll ignore it.
+- Auth: `ctx.modelRegistry.getApiKeyAndHeaders(ctx.model)` — same primitive as every other pi call, so any OAuth / env-var / custom-provider credential the user already set up just works.
+- Custom / local models (via `pi.registerProvider`): same path. If the provider is registered and has a key, recap works. If not, we skip silently — never fail loudly.
+- No active model / no API key → skip silently, log to `console.error` for debugging.
+
+**Escape hatch flag**
+
+- `--recap-model "<provider>/<id>"` — force a specific model (e.g. if the user wants Sonnet 4-6 for speed regardless of what they're chatting with).
+
+**Trade-off we're accepting**
+
+- If the user is on a heavy model (Opus 4-7, GPT-5.4), each recap uses that model for a small one-liner task. Still cheap in absolute terms because the prompt is capped at ~12k chars and the output is one line, but not the cheapest option. We prefer "no auth surprise" over "always-cheapest".
+
+## Context fed to the model
+
+**Current (v0.1):** transcript of the branch since the last user prompt:
+- User text (trimmed to 1200 chars)
+- Assistant text (trimmed to 1200 chars)
+- Tool calls as `- <name>(<JSON args, ≤280 chars>)`
+- Tool results as `Result(<name>): <text, ≤400 chars>`
+- Whole transcript capped at 12,000 chars.
+
+**TODO (v0.2+):** smarter context extraction. Options to explore:
+- [ ] User prompt + file diffs (from edit/write tool calls) only — compact, factual.
+- [ ] Tool-call list + brief summaries (skip raw file content).
+- [ ] Structured "files touched + what changed" block pre-built before the model call.
+- [ ] Keep last N message entries instead of trimming each.
+
+Trigger to revisit: recaps feel shallow, OR costs creep up on long sessions, OR we want to support much longer running tasks without a summariser pass.
+
+## Prompt
+
+One user message, no system prompt, no tools. Verbatim:
+
+```
+You produce a single-line recap of what the coding agent just did, so the user
+can re-enter flow after switching focus back to this session.
+
+Rules:
+- Output ONE line, no preamble, no markdown.
+- Format: `recap: <what happened, past tense, concrete>. Next: <one-line next step>.`
+- If there is no meaningful next step, omit the `Next:` clause.
+- Use file/function names where relevant. Be concrete, not vague.
+- Max ~220 characters.
+
+<transcript>
+…
+</transcript>
+```
+
+Post-processing: keep only the first line of the response as a belt-and-braces
+guard against multi-line outputs.
+
+## Edge cases
+
+### 1. Focus → defocus → focus again without user input
+
+**Current behaviour:** `handleFocusOut` re-enters `generateAndShow` if there is no in-flight request and no `draftingForFocus` flag, even if `pendingRecap` is still a perfectly valid recap for the same session state. Wasteful, and may overwrite a good recap with an identical one.
+
+**Fix (planned):**
+- Stamp each drafted recap with the current branch leaf id via `ctx.sessionManager.getLeafId()`.
+- On focus-out: if `pendingRecap` exists AND its stamp matches the current leaf, skip regen entirely.
+- Any new `turn_end` (or `input` / `agent_start`) invalidates the stamp.
+
+**Related:** also gate on "has any activity happened since the previous draft?" — if nothing, reuse; if yes, regenerate.
+
+### 2. Agent turn ends in error or abort
+
+**Question:** does `agent_end` fire reliably on user-Escape abort and on model/transport errors? Need to verify against pi's current behaviour. `turn_end` is documented as per-turn and should fire even on partial completion.
+
+**Fix (planned):**
+- Switch the idle-timer arming from `agent_end` → **`turn_end`**. `turn_end` fires after every turn regardless of outcome and is overwritten/cleared by the next `turn_start` or by `input`. This makes the idle fallback robust to errors and aborts without needing a separate error signal.
+- Focus-out path already works: `hasMeaningfulActivity` counts assistant words and tool calls, independent of success/failure. An aborted turn with partial work still qualifies.
+- Add a note in the recap prompt encouraging the model to mention "aborted" / "failed" state explicitly when present in the transcript, so the one-liner is honest (e.g. `recap: Started refactor of auth.ts; aborted before tests ran. Next: resume from middleware split.`).
+
+### 3. Terminal doesn't support DECSET ?1004
+
+Idle fallback covers it. `--recap-disable-focus` lets the user opt out explicitly (in case the escape sequences cause weird ghost characters in a less-compliant terminal).
+
+### 4. tmux without `focus-events on`
+
+tmux swallows focus events unless `set -g focus-events on` is set. Document in README. Idle fallback still works.
+
+### 5. Aborted-in-flight recap request
+
+Already handled: `AbortController` on every `complete()` call; cancelled on input / agent_start / session_shutdown / next trigger.
+
+### 6. Multiple pi sessions in the same terminal process
+
+Not applicable — pi is one process per terminal tab. The stdin listener we add is scoped to the process and cleaned up on `session_shutdown`.
+
+## Non-goals
+
+- Session persistence of recap history (not needed — the widget is transient by design).
+- Multi-recap / rolling summary across many focus cycles.
+- Recap UI beyond the widget (no modal, no notifications by default).
+
+## Release checklist — v0.1.0
+
+### Code
+- [x] Extension lives at `session-recap/index.ts`.
+- [x] Default model = `ctx.model` with `reasoning: "minimal"` via `completeSimple()` when the model advertises reasoning; `--recap-model` override.
+- [x] Idle timer armed on `turn_end` (not `agent_end`) so error/abort turns still get a recap.
+- [x] `pendingRecap` + `lastDraftedLeafId` stamping; skip regen on focus-out if branch leaf hasn't changed.
+- [x] Prompt explicitly asks the model to mention aborted/errored turn state when present.
+- [x] `--recap-disable-focus` escape hatch in case DECSET `?1004` misbehaves.
+- [x] Cleanup: `\x1b[?1004l` + listener removal on `session_shutdown`.
+
+### Packaging
+- [x] `session-recap/package.json` (`@tmustier/pi-session-recap` v0.1.0).
+- [x] Added `./session-recap/index.ts` to root `package.json` → `pi.extensions`.
+- [x] Root version bumped.
+
+### Docs
+- [x] `session-recap/README.md` — features, install, flags, terminal compatibility table.
+- [x] `session-recap/CHANGELOG.md`.
+- [x] Row added to repo-root `README.md`.
+- [x] `DESIGN.md` retained as design-of-record.
+
+### Release
+- [ ] Follow `RELEASING.md`: commit, tag `session-recap/v0.1.0`, publish `@tmustier/pi-session-recap` + repo `pi-extensions`, push tag, GitHub release.
+
+## Follow-ups (v0.2+)
+
+- [ ] **Smarter context feeding**: try feeding user prompt + file diffs (from `edit`/`write` tool-call args) only, instead of the full trimmed transcript. Simpler, factual, likely cheaper. Alternative: pre-build a structured "files touched + what changed" block.
+- [ ] **Verify `turn_end` really fires on every abort path** (user Escape mid-stream, provider errors, transport failures). If there's a gap, add a belt-and-braces `session_before_compact` / `session_shutdown` fallback.
+- [ ] Optional: small e2e test harness to trigger fake `turn_end` / focus-in/out sequences and assert widget state transitions.

package/session-recap/README.md

@@ -0,0 +1,101 @@
+# session-recap
+
+Claude-Code-style session recap for Pi. When you switch focus away from a Pi session and come back, a one-line recap appears above the editor so you can re-enter flow without re-reading scrollback.
+
+![session-recap widget in a live Pi session](./assets/recap.png)
+
+Built for multi-clauding / multi-pi workflows where several agent sessions run in parallel tabs.
+
+## How it triggers
+
+Two complementary triggers. You get whichever fires first.
+
+1. **Terminal focus reporting (DECSET `?1004`).** The extension enables focus events on session start and listens for `ESC[O` (focus-out) and `ESC[I` (focus-in). On focus-out it drafts a recap in the background; on focus-in it reveals the recap above the editor, as long as you were away for at least `--recap-focus-min-seconds` (default 3s — suppresses quick glances).
+2. **Idle fallback.** After the last `turn_end`, if you don't type for `--recap-idle-seconds` (default 45s), the recap is generated and shown anyway. This covers terminals that don't report focus events.
+
+Also fires automatically on `/resume` and `/fork` so you know where the prior session left off.
+
+Clears cleanly on: next user input, new turn start, session reload, or session shutdown.
+
+## Terminal compatibility
+
+| Terminal | Focus reporting | Notes |
+|---|---|---|
+| iTerm2, Ghostty, Alacritty, Kitty, WezTerm, xterm | ✅ | Works out of the box. |
+| VS Code integrated terminal, Warp | ✅ | Works. |
+| Apple Terminal | ⚠️ Partial | Idle fallback covers it. |
+| tmux | ✅ (with config) | Add `set -g focus-events on` to `~/.tmux.conf`, then `tmux source-file ~/.tmux.conf`. |
+
+If focus events cause any weirdness in your terminal, run with `--recap-disable-focus` and the idle fallback still works.
+
+## Model
+
+Defaults to the **currently active model** in your Pi session with `reasoning: "minimal"` where the model supports it. This piggybacks on whatever auth you already have (including custom providers registered via `pi.registerProvider`), so there are no login surprises.
+
+- Reasoning-capable model (Opus 4-7, GPT-5.4, etc.) → runs at minimal thinking for speed/cost.
+- Non-reasoning model → no reasoning params passed.
+- No active model or missing API key → the recap is skipped silently.
+
+Override with `--recap-model "<provider>/<id>"` if you want a specific model regardless of the session's active one.
+
+## Install
+
+### Pi package manager
+
+```bash
+pi install git:github.com/tmustier/pi-extensions
+```
+
+Filter to just this extension in `~/.pi/agent/settings.json`:
+
+```json
+{
+  "packages": [
+    {
+      "source": "git:github.com/tmustier/pi-extensions",
+      "extensions": ["session-recap/index.ts"]
+    }
+  ]
+}
+```
+
+### Local clone
+
+```json
+{
+  "extensions": [
+    "~/pi-extensions/session-recap/index.ts"
+  ]
+}
+```
+
+## Flags
+
+| Flag | Default | Description |
+|---|---|---|
+| `--recap-idle-seconds <n>` | `45` | Seconds after `turn_end` before the idle-fallback recap fires. |
+| `--recap-focus-min-seconds <n>` | `3` | Minimum focus-out duration before a recap is revealed on refocus. |
+| `--recap-disable-focus` | `false` | Disable DECSET `?1004` focus reporting. Idle fallback still runs. |
+| `--recap-disable` | `false` | Disable the automatic recap entirely. `/recap` still works. |
+| `--recap-model "<p/id>"` | (active model) | Override the default, e.g. `anthropic/claude-sonnet-4-6`. |
+
+## Command
+
+| Command | Description |
+|---|---|
+| `/recap` | Force-generate a recap right now, bypassing the activity gate. |
+
+## Behaviour notes
+
+- **Uses `turn_end`, not `agent_end`**, so a turn that errors or is aborted still gets recapped.
+- **No duplicate drafts**: the last-drafted branch-leaf is stamped; if you focus out / in repeatedly without any new session activity, the recap is reused rather than regenerated.
+- **Aborts on new input**: any in-flight recap request is cancelled when you start typing or a new turn begins.
+- **No session persistence**: the recap lives only in the widget for the active session — nothing is stored.
+
+## Design
+
+See [DESIGN.md](./DESIGN.md) for the design-of-record and open questions.
+
+## License
+
+MIT

package/session-recap/index.ts

@@ -0,0 +1,567 @@
+/**
+ * session-recap
+ *
+ * Claude-Code-style session recap for pi. Two complementary triggers:
+ *
+ *   1) True terminal focus reporting via DECSET ?1004. When the terminal
+ *      loses focus we start drafting a recap in the background; when it
+ *      regains focus we reveal it in a widget above the editor. Mirrors
+ *      Claude Code's "refocus the tab" moment.
+ *
+ *   2) Idle-return fallback: if the terminal doesn't support focus events,
+ *      or the user stays in the same window, we still generate a recap N
+ *      seconds after the last `turn_end` so something is waiting above the
+ *      editor when they look back at the session. `turn_end` (not
+ *      `agent_end`) is used so the fallback fires even when a turn ends
+ *      in an error or is aborted by the user.
+ *
+ * Also fires on `/resume` (session_start reason="resume") to recap where
+ * the prior session left off.
+ *
+ * Model: defaults to the user's currently active model with
+ * `reasoning: "minimal"` when the model advertises reasoning support. This
+ * piggybacks on whatever auth the user already has configured (including
+ * custom providers) so there are no login surprises. Override explicitly
+ * with `--recap-model "<provider>/<id>"` if you want a specific model.
+ *
+ * Flags:
+ *   --recap-idle-seconds <n>      Seconds after turn_end for idle recap (default 45)
+ *   --recap-focus-min-seconds <n> Min focus-out duration to show a recap (default 3)
+ *   --recap-disable-focus         Disable DECSET ?1004 focus reporting
+ *   --recap-disable               Disable the automatic recap entirely
+ *   --recap-model <p/id>          Override the default (active) model
+ *
+ * Command:
+ *   /recap                        Force-generate a recap right now
+ */
+
+import { completeSimple, getModel } from "@mariozechner/pi-ai";
+import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent";
+
+type ContentBlock = {
+	type?: string;
+	text?: string;
+	name?: string;
+	arguments?: Record<string, unknown>;
+};
+
+type Entry = {
+	id?: string;
+	type: string;
+	message?: {
+		role?: string;
+		content?: unknown;
+		toolName?: string;
+	};
+};
+
+type Model = Parameters<typeof completeSimple>[0];
+
+type RecapReason = "idle" | "manual" | "resume" | "focus";
+
+const WIDGET_KEY = "session-recap";
+const STATUS_KEY = "session-recap";
+
+const DEFAULT_IDLE_SECONDS = 45;
+const DEFAULT_FOCUS_MIN_SECONDS = 3;
+
+// DECSET 1004 focus reporting — https://invisible-island.net/xterm/ctlseqs/ctlseqs.html
+const FOCUS_ENABLE = "\x1b[?1004h";
+const FOCUS_DISABLE = "\x1b[?1004l";
+const FOCUS_IN_SEQ = "\x1b[I";
+const FOCUS_OUT_SEQ = "\x1b[O";
+
+// --- helpers -----------------------------------------------------------------
+
+function splitModel(spec: string): { provider: string; id: string } | undefined {
+	const idx = spec.indexOf("/");
+	if (idx <= 0) return undefined;
+	return { provider: spec.slice(0, idx), id: spec.slice(idx + 1) };
+}
+
+function extractText(content: unknown): string {
+	if (typeof content === "string") return content;
+	if (!Array.isArray(content)) return "";
+	const parts: string[] = [];
+	for (const part of content) {
+		if (!part || typeof part !== "object") continue;
+		const b = part as ContentBlock;
+		if (b.type === "text" && typeof b.text === "string") parts.push(b.text);
+	}
+	return parts.join("\n");
+}
+
+function extractToolCalls(content: unknown): string[] {
+	if (!Array.isArray(content)) return [];
+	const out: string[] = [];
+	for (const part of content) {
+		if (!part || typeof part !== "object") continue;
+		const b = part as ContentBlock;
+		if (b.type !== "toolCall" || typeof b.name !== "string") continue;
+		const args = b.arguments ?? {};
+		const summary = JSON.stringify(args).slice(0, 280);
+		out.push(`- ${b.name}(${summary})`);
+	}
+	return out;
+}
+
+/**
+ * Compact transcript of the assistant's activity since the last user message.
+ * For `resume`, we pass the whole branch instead so the summariser has context.
+ */
+function buildRecentTranscript(entries: Entry[], fromLastUser = true): string {
+	let slice = entries;
+	if (fromLastUser) {
+		let lastUserIdx = -1;
+		for (let i = entries.length - 1; i >= 0; i--) {
+			const e = entries[i];
+			if (e.type === "message" && e.message?.role === "user") {
+				lastUserIdx = i;
+				break;
+			}
+		}
+		if (lastUserIdx >= 0) slice = entries.slice(lastUserIdx);
+	}
+
+	const lines: string[] = [];
+	for (const e of slice) {
+		if (e.type !== "message" || !e.message?.role) continue;
+		const role = e.message.role;
+		if (role === "user") {
+			const t = extractText(e.message.content).trim();
+			if (t) lines.push(`User: ${t.slice(0, 1200)}`);
+		} else if (role === "assistant") {
+			const t = extractText(e.message.content).trim();
+			if (t) lines.push(`Assistant: ${t.slice(0, 1200)}`);
+			const calls = extractToolCalls(e.message.content);
+			if (calls.length) lines.push(...calls);
+		} else if (role === "toolResult") {
+			const t = extractText(e.message.content).trim();
+			const name = e.message.toolName ?? "tool";
+			if (t) lines.push(`Result(${name}): ${t.slice(0, 400)}`);
+		}
+	}
+	return lines.join("\n");
+}
+
+/**
+ * Only draft a recap if there has been real agent activity since the last user
+ * message: at least one tool call, or ~30+ words of assistant text.
+ */
+function hasMeaningfulActivity(entries: Entry[]): boolean {
+	let lastUserIdx = -1;
+	for (let i = entries.length - 1; i >= 0; i--) {
+		const e = entries[i];
+		if (e.type === "message" && e.message?.role === "user") {
+			lastUserIdx = i;
+			break;
+		}
+	}
+	const tail = lastUserIdx >= 0 ? entries.slice(lastUserIdx + 1) : entries;
+	let assistantWords = 0;
+	let toolCalls = 0;
+	for (const e of tail) {
+		if (e.type !== "message") continue;
+		if (e.message?.role === "assistant") {
+			const t = extractText(e.message.content);
+			assistantWords += t.split(/\s+/).filter(Boolean).length;
+			toolCalls += extractToolCalls(e.message.content).length;
+		}
+	}
+	return toolCalls > 0 || assistantWords >= 30;
+}
+
+async function generateRecap(
+	transcript: string,
+	ctx: ExtensionContext,
+	overrideSpec: string | undefined,
+	signal: AbortSignal | undefined,
+): Promise<string | undefined> {
+	// Prefer explicit override flag; otherwise use the active model.
+	let model: Model | undefined = ctx.model;
+	if (overrideSpec) {
+		const parsed = splitModel(overrideSpec);
+		if (parsed) {
+			const found = (getModel as (provider: string, id: string) => Model | undefined)(
+				parsed.provider,
+				parsed.id,
+			);
+			if (found) model = found;
+		}
+	}
+	if (!model) return undefined;
+
+	const auth = await ctx.modelRegistry.getApiKeyAndHeaders(model);
+	if (!auth?.ok || !auth.apiKey) return undefined;
+
+	const prompt =
+		"You produce a single-line recap of what the coding agent just did, " +
+		"so the user can re-enter flow after switching focus back to this session.\n\n" +
+		"Rules:\n" +
+		"- Output ONE line, no preamble, no markdown.\n" +
+		"- Format: `recap: <what happened, past tense, concrete>. Next: <one-line next step>.`\n" +
+		"- If there is no meaningful next step, omit the `Next:` clause.\n" +
+		"- If the transcript shows the turn was aborted or errored, say so explicitly " +
+		'(e.g. "aborted during X", "errored at Y").\n' +
+		"- Use file/function names where relevant. Be concrete, not vague.\n" +
+		"- Max ~220 characters.\n\n" +
+		"<transcript>\n" +
+		transcript.slice(0, 12000) +
+		"\n</transcript>";
+
+	const response = await completeSimple(
+		model,
+		{
+			messages: [
+				{
+					role: "user",
+					content: [{ type: "text", text: prompt }],
+					timestamp: Date.now(),
+				},
+			],
+		},
+		{
+			apiKey: auth.apiKey,
+			headers: auth.headers,
+			signal,
+			// Only request reasoning on reasoning-capable models. Non-reasoning
+			// models ignore unknown params but we keep this clean.
+			...(model.reasoning ? { reasoning: "minimal" as const } : {}),
+		},
+	);
+
+	const text = response.content
+		.filter((c): c is { type: "text"; text: string } => c.type === "text")
+		.map((c) => c.text)
+		.join("\n")
+		.trim();
+
+	return text ? text.split(/\r?\n/, 1)[0].trim() : undefined;
+}
+
+function showRecap(ctx: ExtensionContext, recap: string) {
+	if (!ctx.hasUI) return;
+	const theme = ctx.ui.theme;
+	const header = theme.fg("accent", theme.bold("✦ recap"));
+	ctx.ui.setWidget(WIDGET_KEY, [header, theme.fg("dim", recap)], { placement: "aboveEditor" });
+}
+
+function clearRecap(ctx: ExtensionContext) {
+	if (!ctx.hasUI) return;
+	ctx.ui.setWidget(WIDGET_KEY, undefined);
+	ctx.ui.setStatus(STATUS_KEY, undefined);
+}
+
+// --- extension ---------------------------------------------------------------
+
+export default function (pi: ExtensionAPI) {
+	pi.registerFlag("recap-idle-seconds", {
+		description: "Seconds after turn_end before the session recap is generated",
+		type: "string",
+		default: String(DEFAULT_IDLE_SECONDS),
+	});
+	pi.registerFlag("recap-focus-min-seconds", {
+		description: "Minimum focus-out duration (seconds) before showing a recap on refocus",
+		type: "string",
+		default: String(DEFAULT_FOCUS_MIN_SECONDS),
+	});
+	pi.registerFlag("recap-disable-focus", {
+		description: "Disable DECSET ?1004 focus reporting (idle fallback still runs)",
+		type: "boolean",
+		default: false,
+	});
+	pi.registerFlag("recap-disable", {
+		description: "Disable the automatic session recap",
+		type: "boolean",
+		default: false,
+	});
+	pi.registerFlag("recap-model", {
+		description: "Override the default (active) model, e.g. anthropic/claude-sonnet-4-6",
+		type: "string",
+		default: "",
+	});
+
+	let idleTimer: NodeJS.Timeout | undefined;
+
+	// Active recap request state. Only one request is ever in flight; starting
+	// a new one aborts the previous. We track both the controller and the
+	// reason so we can ask questions like "is there a focus draft running?"
+	// without a separate boolean that can go out of sync on late completions.
+	let activeController: AbortController | undefined;
+	let activeReason: RecapReason | undefined;
+
+	// Focus reporting state.
+	let focusListener: ((chunk: Buffer) => void) | undefined;
+	let focusEnabled = false;
+	let focusedOutAt: number | undefined;
+	let pendingRecap: string | undefined; // drafted while away, shown on refocus
+
+	// Leaf-id of the branch state we last drafted for. Lets us skip regen on
+	// refocus churn when nothing has happened in the session.
+	let lastDraftedLeafId: string | undefined;
+
+	const idleMs = (): number => {
+		const n = Number(pi.getFlag("--recap-idle-seconds") ?? DEFAULT_IDLE_SECONDS);
+		return Math.max(5, Number.isFinite(n) ? n : DEFAULT_IDLE_SECONDS) * 1000;
+	};
+	const focusMinMs = (): number => {
+		const n = Number(pi.getFlag("--recap-focus-min-seconds") ?? DEFAULT_FOCUS_MIN_SECONDS);
+		return Math.max(0, Number.isFinite(n) ? n : DEFAULT_FOCUS_MIN_SECONDS) * 1000;
+	};
+	const isDisabled = (): boolean => Boolean(pi.getFlag("--recap-disable"));
+	const isFocusDisabled = (): boolean => Boolean(pi.getFlag("--recap-disable-focus"));
+	const modelOverride = (): string | undefined => {
+		const v = String(pi.getFlag("--recap-model") ?? "").trim();
+		return v.length > 0 ? v : undefined;
+	};
+
+	const clearTimer = () => {
+		if (idleTimer) {
+			clearTimeout(idleTimer);
+			idleTimer = undefined;
+		}
+	};
+
+	const cancelActive = () => {
+		if (activeController) {
+			activeController.abort();
+			activeController = undefined;
+			activeReason = undefined;
+		}
+	};
+
+	const scheduleRecap = (ctx: ExtensionContext) => {
+		clearTimer();
+		if (isDisabled() || !ctx.hasUI) return;
+		idleTimer = setTimeout(() => {
+			idleTimer = undefined;
+			void generateAndShow(ctx, { reason: "idle" });
+		}, idleMs());
+	};
+
+	const getLeafId = (ctx: ExtensionContext): string | undefined => {
+		try {
+			return ctx.sessionManager.getLeafId();
+		} catch {
+			return undefined;
+		}
+	};
+
+	const generateAndShow = async (ctx: ExtensionContext, opts: { reason: RecapReason }) => {
+		const entries = ctx.sessionManager.getBranch() as Entry[];
+		if (!hasMeaningfulActivity(entries) && opts.reason !== "manual") return;
+
+		const transcript = buildRecentTranscript(entries, opts.reason !== "resume");
+		if (!transcript.trim()) return;
+
+		// Snapshot the leaf we're summarising BEFORE we await. If the branch
+		// advances while the model call is in flight, the recap reflects stale
+		// content — we must discard it rather than stamp the wrong leaf.
+		const startLeaf = getLeafId(ctx);
+
+		// Take ownership of the active-request slot. Any prior request is
+		// cancelled; we'll only clear shared state in the finally if we're
+		// still the current owner, so a late-completing aborted call can't
+		// stomp on a newer in-flight request.
+		cancelActive();
+		const controller = new AbortController();
+		activeController = controller;
+		activeReason = opts.reason;
+
+		const showStatus = opts.reason !== "resume" && opts.reason !== "focus";
+		if (showStatus && ctx.hasUI)
+			ctx.ui.setStatus(STATUS_KEY, ctx.ui.theme.fg("dim", "✦ drafting recap…"));
+
+		try {
+			const recap = await generateRecap(transcript, ctx, modelOverride(), controller.signal);
+			if (!recap || controller.signal.aborted) return;
+			// Discard the recap if the branch moved on while we were drafting.
+			if (getLeafId(ctx) !== startLeaf) return;
+
+			// Stamp with the leaf we actually summarised, not the live one.
+			lastDraftedLeafId = startLeaf;
+			// Another trigger has now produced a recap for this leaf — kill the
+			// idle fallback so we don't issue a second call 45s later.
+			clearTimer();
+
+			if (opts.reason === "focus") {
+				if (focusedOutAt === undefined) showRecap(ctx, recap);
+				else pendingRecap = recap;
+			} else {
+				showRecap(ctx, recap);
+			}
+		} catch (err) {
+			if (!controller.signal.aborted) console.error("[session-recap] failed:", err);
+		} finally {
+			if (activeController === controller) {
+				activeController = undefined;
+				activeReason = undefined;
+				if (showStatus && ctx.hasUI) ctx.ui.setStatus(STATUS_KEY, undefined);
+			}
+		}
+	};
+
+	// --- focus reporting wiring -------------------------------------------
+
+	const handleFocusOut = (ctx: ExtensionContext) => {
+		focusedOutAt = Date.now();
+		if (isDisabled() || activeController) return;
+
+		// Skip regen if we already have a fresh recap for the current session
+		// state — regardless of whether it's still parked in pendingRecap or
+		// already shown in the widget. The stamp is invalidated on any new
+		// turn_end / input / agent_start.
+		const leaf = getLeafId(ctx);
+		if (lastDraftedLeafId && leaf === lastDraftedLeafId) return;
+
+		const entries = ctx.sessionManager.getBranch() as Entry[];
+		if (!hasMeaningfulActivity(entries)) return;
+		void generateAndShow(ctx, { reason: "focus" });
+	};
+
+	const handleFocusIn = (ctx: ExtensionContext) => {
+		const outAt = focusedOutAt;
+		focusedOutAt = undefined;
+		if (outAt === undefined) return; // spurious focus-in before we saw focus-out
+		const duration = Date.now() - outAt;
+		if (duration < focusMinMs()) {
+			// Quick glance — discard any parked recap AND cancel an in-flight
+			// focus draft so a slow model response can't bypass min-seconds.
+			// Also clear the leaf stamp, otherwise a later real absence at the
+			// same leaf would skip regen and never surface a recap.
+			pendingRecap = undefined;
+			lastDraftedLeafId = undefined;
+			if (activeReason === "focus") cancelActive();
+			return;
+		}
+		if (pendingRecap) {
+			const recap = pendingRecap;
+			pendingRecap = undefined;
+			showRecap(ctx, recap);
+		}
+		// Still drafting? generateAndShow's success-path will reveal it when done.
+	};
+
+	const attachFocusReporting = (ctx: ExtensionContext) => {
+		if (focusEnabled || isFocusDisabled() || !ctx.hasUI) return;
+		if (!process.stdout.isTTY || !process.stdin.isTTY) return;
+
+		try {
+			process.stdout.write(FOCUS_ENABLE);
+		} catch {
+			return;
+		}
+
+		// Scan stdin for ESC[I / ESC[O. Sequences can straddle chunks, so we
+		// keep unconsumed trailing bytes in `buf` between calls. Consume each
+		// match by advancing `i`, so a completed sequence never fires twice.
+		// Adding a 'data' listener is safe: Node dispatches to all listeners
+		// and pi is already in flowing mode — we don't steal bytes from the
+		// TUI's input layer.
+		const MAX_SEQ = Math.max(FOCUS_IN_SEQ.length, FOCUS_OUT_SEQ.length);
+		let buf = "";
+		const listener = (chunk: Buffer) => {
+			try {
+				buf += chunk.toString("binary");
+				let i = 0;
+				while (i + MAX_SEQ <= buf.length) {
+					if (buf.startsWith(FOCUS_IN_SEQ, i)) {
+						handleFocusIn(ctx);
+						i += FOCUS_IN_SEQ.length;
+					} else if (buf.startsWith(FOCUS_OUT_SEQ, i)) {
+						handleFocusOut(ctx);
+						i += FOCUS_OUT_SEQ.length;
+					} else {
+						i++;
+					}
+				}
+				buf = buf.slice(i);
+				// Safety net — never let buf grow unbounded if we're reading a
+				// long non-escape stream on a terminal that streams ahead of us.
+				if (buf.length > 64) buf = buf.slice(-(MAX_SEQ - 1));
+			} catch {
+				/* best-effort */
+			}
+		};
+		process.stdin.on("data", listener);
+		focusListener = listener;
+		focusEnabled = true;
+	};
+
+	const detachFocusReporting = () => {
+		if (focusListener) {
+			try {
+				process.stdin.off("data", focusListener);
+			} catch {
+				/* noop */
+			}
+			focusListener = undefined;
+		}
+		if (focusEnabled) {
+			try {
+				process.stdout.write(FOCUS_DISABLE);
+			} catch {
+				/* noop */
+			}
+			focusEnabled = false;
+		}
+		focusedOutAt = undefined;
+		pendingRecap = undefined;
+	};
+
+	// Lifecycle: idle timer arms on turn_end (fires even on error/abort),
+	// and is cleared on anything that indicates new activity or input.
+
+	pi.on("turn_end", async (_event, ctx) => {
+		// A new turn (successful or not) invalidates any prior draft.
+		lastDraftedLeafId = undefined;
+		scheduleRecap(ctx);
+	});
+
+	pi.on("turn_start", async () => {
+		// Another turn is starting in the same agent loop — clear the idle timer
+		// we armed on the previous turn_end; it'll re-arm on the next turn_end.
+		clearTimer();
+	});
+
+	pi.on("input", async (_event, ctx) => {
+		clearTimer();
+		cancelActive();
+		pendingRecap = undefined;
+		lastDraftedLeafId = undefined;
+		clearRecap(ctx);
+	});
+
+	pi.on("agent_start", async (_event, ctx) => {
+		clearTimer();
+		cancelActive();
+		pendingRecap = undefined;
+		lastDraftedLeafId = undefined;
+		clearRecap(ctx);
+	});
+
+	pi.on("session_shutdown", async () => {
+		clearTimer();
+		cancelActive();
+		detachFocusReporting();
+	});
+
+	// Session start: wire up focus reporting; on resume, show a recap.
+	pi.on("session_start", async (event, ctx) => {
+		attachFocusReporting(ctx);
+		if (isDisabled()) return;
+		if (event.reason === "resume" || event.reason === "fork") {
+			setTimeout(() => {
+				void generateAndShow(ctx, { reason: "resume" });
+			}, 300);
+		}
+	});
+
+	// Manual command.
+	pi.registerCommand("recap", {
+		description: "Generate a one-line recap of recent session activity",
+		handler: async (_args, ctx) => {
+			await generateAndShow(ctx, { reason: "manual" });
+		},
+	});
+}

package/session-recap/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@tmustier/pi-session-recap",
+  "version": "0.1.0",
+  "description": "One-line recap above the editor when you refocus a Pi session. Keeps you in flow when multi-agenting.",
+  "license": "MIT",
+  "author": "Thomas Mustier",
+  "keywords": [
+    "pi-package"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tmustier/pi-extensions.git",
+    "directory": "session-recap"
+  },
+  "bugs": "https://github.com/tmustier/pi-extensions/issues",
+  "homepage": "https://github.com/tmustier/pi-extensions/tree/main/session-recap",
+  "pi": {
+    "extensions": [
+      "index.ts"
+    ],
+    "image": "https://raw.githubusercontent.com/tmustier/pi-extensions/main/session-recap/assets/recap.png"
+  }
+}