pisesh 0.1.13 → 0.2.0

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.2.0] - 2026-08-01
+
+### Added
+- Add background LLM title generation: `g` queues a session using the saved model and effort, while `G` opens generation settings. Up to three titles generate concurrently. Based on #2 by @ahoereth.
+
+### Fixed
+- Keep extension-backed model providers available while disabling context files, skills, prompt templates, and tools for title generation.
+- Preserve manual titles during queued generation, reject malformed or control-sequence output, and report generation failures visibly.
+- Forward custom agent directories to spawned pi processes and terminate cancelled generation processes safely.
+
 ## [0.1.13] - 2026-08-01
 
 ### Added

package/README.md

@@ -45,14 +45,14 @@ Pi accumulates sessions across many working directories: your home, several proj
 - 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, ~1,100 LoC) that gives you everything `pi --resume` doesn't.
+pisesh is a **single-file Node script** (no dependencies, ~1,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       |
-| Give a thread a real name                  | `e` sets a custom title (marked `✎`); overrides the first-prompt label        |
+| Give a thread a real name                  | `e` sets one manually; `g` generates one with a model you choose             |
 | See only the current project's sessions    | `Here` tab filters to sessions whose cwd matches where you launched pisesh   |
 | Fix where a session resumes                | `p` opens an arrow-key directory browser; sets the cwd pi `cd`s into         |
 | Find a session by what you said            | `/` searches id + project + first user prompt + custom title                 |
@@ -104,15 +104,19 @@ For local pi testing, run `pi install .` from the cloned repository so the exten
 | `Enter`                      | resume using the current default model and thinking settings  |
 | `o`                          | resume using the model and thinking recorded in the session   |
 | `e`                          | edit name: set a custom display title, shown with `✎` in the list |
+| `g`                          | queue title generation with the saved model and effort; clear a manual title with `e` first |
+| `G`                          | open title-generation settings to choose the saved model + effort |
 | `p`                          | edit cwd with an arrow-key directory browser; sets the resume / `Here` dir |
 | `d`                          | session details (full prompt, file, byte size, timestamps)   |
 | `/`                          | search by id / project / first user prompt / custom title    |
-| `Esc`                        | clear search first, then quit                                |
-| `q` / `Ctrl-C`               | quit (terminal restored)                                     |
+| `Esc` / `q`                  | cancel generation or clear search first; press again to quit |
+| `Ctrl-C`                     | cancel generation and quit immediately                       |
 | `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                                   |
 
+Title generation sends up to 16 KB of session text to the selected model provider and may incur provider charges. It excludes tool results and disables context files, skills, prompt templates, and tools.
+
 ## CLI (non-TUI) usage
 
 For scripts and automation:
@@ -139,17 +143,18 @@ pisesh --help
 | 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             | Two JSON files: `~/.pi/agent/favorites.json` (starred ids) + `~/.pi/agent/pisesh-meta.json` (per-session title / cwd overrides) |
+| Storage             | Two JSON files under `$PI_AGENT_DIR`: `favorites.json` and `pisesh-meta.json`                 |
 | 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           |
 | Resume settings     | `Enter` uses current defaults; `o` preserves the model and thinking recorded in the session         |
 | Custom paths        | Honors `PI_AGENT_DIR` and `PI_SESSION_DIR`, including a flat custom session directory                |
+| Title generation    | Ephemeral `pi --print --no-session` call using the model and effort selected in pisesh            |
 
 ### What it explicitly does **not** depend on
 
 - No `npm install` for the bundled CLI runtime; it's genuinely zero-dependency
 - No native binaries / GPU / ffmpeg / database
-- No network calls, no telemetry, no analytics
+- No telemetry or analytics; title generation contacts only the provider for the model you select
 - No daemon / background process
 
 ## Storage
@@ -157,7 +162,7 @@ pisesh --help
 | What       | Where                                                       |
 | ---------- | ----------------------------------------------------------- |
 | Favorites  | `$PI_AGENT_DIR/favorites.json` (defaults to `~/.pi/agent/favorites.json`) |
-| Overrides  | `$PI_AGENT_DIR/pisesh-meta.json` (per-session custom title / cwd, keyed by session id) |
+| Overrides  | `$PI_AGENT_DIR/pisesh-meta.json` (per-session title / cwd plus the saved title model + effort preset) |
 | Sessions   | `$PI_SESSION_DIR`, or `$PI_AGENT_DIR/sessions` by default (repaired only when an orphaned tool call would break resume) |
 
 Favorites file shape:

package/bin/pisesh

@@ -15,11 +15,15 @@ const readline = require('readline');
 
 // ── Paths ─────────────────────────────────────────────
 const HOME = os.homedir();
-const AGENT_DIR = path.resolve(process.env.PI_AGENT_DIR || path.join(HOME, '.pi/agent'));
-const SESSIONS_ROOT = path.resolve(process.env.PI_SESSION_DIR || path.join(AGENT_DIR, 'sessions'));
+const AGENT_DIR = path.resolve(process.env.PI_AGENT_DIR || process.env.PI_CODING_AGENT_DIR || path.join(HOME, '.pi/agent'));
+const SESSIONS_ROOT = path.resolve(process.env.PI_SESSION_DIR || process.env.PI_CODING_AGENT_SESSION_DIR || path.join(AGENT_DIR, 'sessions'));
 const FAV_FILE = path.join(AGENT_DIR, 'favorites.json');
 const META_FILE = path.join(AGENT_DIR, 'pisesh-meta.json');
 const SETTINGS_FILE = path.join(AGENT_DIR, 'settings.json');
+function piAgentEnv(baseEnv = process.env, agentDir = AGENT_DIR) {
+  return { ...baseEnv, PI_CODING_AGENT_DIR: agentDir };
+}
+const PI_ENV = piAgentEnv();
 const VERSION = (() => {
   for (const file of [
     path.resolve(__dirname, '../package.json'),
@@ -91,12 +95,15 @@ let favorites = loadFavorites();
 function loadMeta() {
   try {
     const data = JSON.parse(fs.readFileSync(META_FILE, 'utf8'));
-    return (data && typeof data.overrides === 'object' && data.overrides) || {};
-  } catch { return {}; }
+    return {
+      overrides: (data && typeof data.overrides === 'object' && data.overrides) || {},
+      settings: (data && typeof data.settings === 'object' && data.settings) || {},
+    };
+  } catch { return { overrides: {}, settings: {} }; }
 }
 
-function saveMeta(overrides) {
-  const data = { overrides, updated: new Date().toISOString() };
+function saveMeta() {
+  const data = { settings: metaSettings, overrides: meta, updated: new Date().toISOString() };
   try {
     fs.mkdirSync(path.dirname(META_FILE), { recursive: true });
     fs.writeFileSync(META_FILE, JSON.stringify(data, null, 2));
@@ -105,7 +112,9 @@ function saveMeta(overrides) {
   }
 }
 
-let meta = loadMeta();
+const loadedMeta = loadMeta();
+let meta = loadedMeta.overrides;
+let metaSettings = loadedMeta.settings;
 
 // Override record for one session id (always returns an object, never null).
 // Used by the per-session getters, which can't read the global `meta`
@@ -123,7 +132,32 @@ function setOverride(id, field, value) {
   else delete entry[field];
   if (Object.keys(entry).length) meta[id] = entry;
   else delete meta[id];
-  saveMeta(meta);
+  saveMeta();
+}
+
+function saveTitle(id, value, source, model, thinkingLevel) {
+  if (!id) return;
+  const v = (value || '').trim();
+  const entry = meta[id] || {};
+  if (v) {
+    entry.title = v;
+    entry.titleSource = source;
+    if (source === 'llm' && model) {
+      entry.titleModel = model;
+      entry.titleThinkingLevel = thinkingLevel || 'off';
+    } else {
+      delete entry.titleModel;
+      delete entry.titleThinkingLevel;
+    }
+  } else {
+    delete entry.title;
+    delete entry.titleSource;
+    delete entry.titleModel;
+    delete entry.titleThinkingLevel;
+  }
+  if (Object.keys(entry).length) meta[id] = entry;
+  else delete meta[id];
+  saveMeta();
 }
 
 // ── Project slug decode ───────────────────────────────
@@ -235,6 +269,9 @@ function scanSessions() {
         get isCurrent() { return CURRENT_SESSION_ID !== '' && this.id === CURRENT_SESSION_ID; },
         // User overrides (sidecar meta). cwd: from is the original recorded cwd.
         get titleOverride() { return (overridesFor(this.id).title || '').trim(); },
+        get titleSource() { return overridesFor(this.id).titleSource || (this.titleOverride ? 'manual' : ''); },
+        get titleModel() { return overridesFor(this.id).titleModel || ''; },
+        get titleThinkingLevel() { return overridesFor(this.id).titleThinkingLevel || ''; },
         get cwdOverride() { return (overridesFor(this.id).cwd || '').trim(); },
         // Name shown in the list: custom title > first prompt > id fallback.
         get title() {
@@ -266,7 +303,7 @@ let tabIdx = 0;
 let cursor = 0;
 let filter = '';
 let notice = '';
-let mode = 'list';      // list | filter | details | edit | browse
+let mode = 'list';      // list | filter | details | edit | browse | model
 // edit mode state (title text editor)
 let editField = '';     // 'title' | 'cwd'
 let editBuffer = '';
@@ -276,6 +313,185 @@ let editTarget = null;  // the session being edited
 let browseDir = '';        // directory currently being browsed (absolute)
 let browseEntries = [];    // [{ label, kind:'use'|'up'|'dir', path }]
 let browseSel = 0;         // selected row in browseEntries
+// LLM title generation state
+let models = [];
+let modelSel = 0;
+let modelFilter = '';
+let modelStatus = '';
+let modelRequestId = 0;
+let modelThinking = new Set();
+let modelEffort = 'off';
+const EFFORT_LEVELS = ['off', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max'];
+const TITLE_GENERATION_CONCURRENCY = 3;
+let generationChildren = new Map(); // target id -> ChildProcess
+let generationCancelled = false;
+let settingsPendingTarget = null;
+let generationJobs = []; // queued [{ target, model, effort }]
+let generationActive = false;
+let handingOff = false;
+
+function configuredPiModel() {
+  try {
+    const settings = JSON.parse(fs.readFileSync(SETTINGS_FILE, 'utf8'));
+    if (settings.defaultProvider && settings.defaultModel) {
+      return `${settings.defaultProvider}/${settings.defaultModel}`;
+    }
+  } catch {}
+  return '';
+}
+
+function parseModelEntries(output) {
+  return output.split(/\r?\n/).slice(1).map(line => {
+    const cols = line.trim().split(/\s+/);
+    return cols.length >= 6 ? { id: `${cols[0]}/${cols[1]}`, thinking: cols[4] === 'yes' } : null;
+  }).filter(Boolean);
+}
+
+function parseModelList(output) {
+  return parseModelEntries(output).map(entry => entry.id);
+}
+
+function textFromContent(content) {
+  if (typeof content === 'string') return content.trim();
+  if (!Array.isArray(content)) return '';
+  return content.filter(x => x && x.type === 'text' && x.text).map(x => x.text.trim()).filter(Boolean).join('\n');
+}
+
+const TITLE_PROMPT = `Generate a durable, factual topic label for this coding session.
+Describe what the session is about, not what the assistant completed or reported.
+Do not summarize or quote the conversation.
+
+Output exactly one line:
+<3-8 word title>: <6-14 word subtitle>
+
+Title requirements (highest priority):
+- The title must stand alone because the subtitle may be truncated in the session list
+- Use a base-form action such as Review, Rebase, Refactor, Resolve, Fix, Add, Remove, or Investigate
+- Put the core subject, action, exact target, and distinguishing scope in the title
+- Name human-readable identifiers whenever available: PR number or name, branch, class, function, filename, package, command, or issue
+- Describe the central task or topic independent of its progress or completion state
+- Never encode status or bookkeeping such as completed, done, finished, committed, updated, tests passed, or test counts
+- Use factual, impersonal wording; never use I, we, you, I'll, I will, let's, or going to
+- Never describe the assistant's plan, promise, tool usage, response, next step, or accomplishments
+- Never copy a sentence from the conversation
+- Omit commit hashes; unlike PR numbers, they are not useful human-readable identifiers
+- When referring to a path, prefer the filename alone; include directories only when needed to disambiguate
+- Count every slash-separated path component as one word toward the 3-8 word limit (for example, src/auth/Login.ts counts as three words)
+- Prefer specific technical nouns over generic descriptions
+
+Subtitle requirements:
+- Use 6-14 words in one concise, factual imperative sentence
+- Begin with a base-form action verb such as Add, Apply, Check, Extract, Implement, Inspect, Preserve, or Remove
+- Use parallel imperative verb phrases when naming multiple actions
+- Describe technical scope, constraints, or subject matter not already in the title
+- Avoid report-style verbs such as covers, adds, identifies, resolves, or completed
+- Do not report progress, completion, commit history, todo updates, or test counts unless testing is the session's central topic
+- Use assistant evidence only to clarify the topic, target, and scope; ignore its status and process wording
+- Do not repeat or rephrase the title
+
+Examples:
+Resolve sample-service Audit Findings: Apply focused refactors, tighten authorization, and bound cache growth.
+Review desktop-client Concurrency Changes: Check lifecycle, thread safety, and event ownership.
+Review PR #42 Token Refresh: Inspect refresh concurrency and add regression coverage.
+Rebase feature/auth onto main: Resolve middleware conflicts and preserve session handling compatibility.
+Refactor SessionManager Retry Logic: Extract backoff policy and remove duplicated state transitions.
+
+General requirements:
+- Use exactly one colon to separate the title and subtitle
+- No quotation marks
+- Output only the title and subtitle`;
+
+function boundTitleContext(text, maxChars) {
+  if (text.length <= maxChars) return text;
+  const marker = '\n\n[earlier context omitted]\n\n';
+  if (maxChars <= marker.length) return text.slice(0, maxChars);
+  const available = maxChars - marker.length;
+  const head = Math.floor(available * 0.4);
+  return text.slice(0, head) + marker + text.slice(-(available - head));
+}
+
+function buildTitlePrompt(file, maxChars = 16000) {
+  const userRequests = [];
+  const assistantReports = [];
+  let sessionCwd = '';
+  try {
+    for (const line of fs.readFileSync(file, 'utf8').split('\n')) {
+      if (!line.trim()) continue;
+      let obj;
+      try { obj = JSON.parse(line); } catch { continue; }
+      if (obj.type === 'session' && !sessionCwd && typeof obj.cwd === 'string') {
+        sessionCwd = obj.cwd.trim();
+        continue;
+      }
+      if (obj.type !== 'message' || !obj.message) continue;
+      const { role, content, stopReason } = obj.message;
+      if (role !== 'user' && role !== 'assistant') continue;
+      const text = textFromContent(content);
+      if (!text) continue;
+      if (role === 'user') {
+        userRequests.push(`User request ${userRequests.length + 1}: ${text}`);
+        continue;
+      }
+      const hasToolCall = Array.isArray(content) && content.some(x => x && x.type === 'toolCall');
+      if (!hasToolCall && stopReason !== 'error' && stopReason !== 'aborted') {
+        assistantReports.push(`Assistant evidence ${assistantReports.length + 1}: ${text}`);
+      }
+    }
+  } catch (e) { throw new Error(`could not read session: ${e.message}`); }
+  if (!userRequests.length && !assistantReports.length) throw new Error('no conversation text found');
+
+  const userText = userRequests.join('\n\n');
+  const assistantText = assistantReports.join('\n\n');
+  const totalBudget = Math.max(0, maxChars);
+  let userBudget = Math.min(userText.length, Math.floor(totalBudget * 0.7));
+  let assistantBudget = Math.min(assistantText.length, totalBudget - userBudget);
+  let remaining = totalBudget - userBudget - assistantBudget;
+  const extraUser = Math.min(remaining, userText.length - userBudget);
+  userBudget += extraUser;
+  remaining -= extraUser;
+  assistantBudget += Math.min(remaining, assistantText.length - assistantBudget);
+
+  const sections = [];
+  const cwdParts = sessionCwd.replace(/[\\/]+$/, '').split(/[\\/]/).filter(Boolean);
+  if (cwdParts.length) sections.push(`Session context:\nWorking directory: ${cwdParts[cwdParts.length - 1]}`);
+  if (userText) sections.push(`User requests (authoritative task context):\n${boundTitleContext(userText, userBudget)}`);
+  if (assistantText) sections.push(`Assistant evidence (use only for topic, target, and scope; ignore completion and process wording):\n${boundTitleContext(assistantText, assistantBudget)}`);
+  return `${TITLE_PROMPT}\n\nConversation evidence:\n${sections.join('\n\n')}`;
+}
+
+function cleanGeneratedTitle(output) {
+  const safeOutput = String(output || '')
+    .replace(/\u001b\[[0-?]*[ -/]*[@-~]/g, '')
+    .replace(/\u001b\][^\u0007]*(?:\u0007|\u001b\\)/g, '');
+  const lines = safeOutput.split(/\r?\n/)
+    .map(line => line.replace(/[\u0000-\u001f\u007f-\u009f]/g, ' ').replace(/\s+/g, ' ').trim())
+    .filter(Boolean);
+  if (lines.length !== 1) throw new Error('model must return exactly one line');
+  const title = lines[0]
+    .replace(/^title\s*:\s*/i, '')
+    .replace(/^["'“”‘’`]+|["'“”‘’`]+$/g, '')
+    .trim();
+  const separator = title.indexOf(':');
+  if (separator <= 0 || separator !== title.lastIndexOf(':') || separator === title.length - 1) {
+    throw new Error('model must return one title and subtitle separated by a colon');
+  }
+  return [...title].slice(0, 200).join('');
+}
+
+function titleGenerationArgs(model, effort, prompt) {
+  return [
+    '--print', '--no-session', '--no-context-files',
+    '--no-skills', '--no-prompt-templates', '--no-tools',
+    '--system-prompt', 'You generate durable factual topic labels, not completion reports or conversation summaries. Use base-form imperative actions in both the title and subtitle. Describe the session’s central task independent of progress, using assistant evidence only for the topic, target, and scope. Never copy status, process, accomplishments, plans, promises, tool usage, first-person wording, or report-style phrasing. Follow the user instructions exactly and output only the requested single-line title and subtitle.',
+    '--model', model, '--thinking', effort, prompt,
+  ];
+}
+
+function titleGenerationBlocker(target) {
+  return target && target.titleSource === 'manual'
+    ? 'manual title exists; clear it with e before generating'
+    : '';
+}
 
 // ── Filtering by tab ──────────────────────────────────
 function visibleSessions() {
@@ -400,6 +616,7 @@ function visLen(s) {
 function render() {
   if (mode === 'edit') return renderEdit();
   if (mode === 'browse') return renderBrowse();
+  if (mode === 'model') return renderModelPicker();
   if (mode === 'details') return renderDetails();
   renderList();
 }
@@ -411,7 +628,8 @@ function renderList() {
 
   // 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';
+  out += A.gry + `${sessions.length} sessions · ${favorites.size} starred` + A.R;
+  out += '\n\n';
 
   // Tabs
   let tabLine = ' ';
@@ -459,14 +677,22 @@ function renderList() {
       const sel = i === cursor;
       const star = s.favored ? A.yel + '★' + A.R : ' ';
       const arrow = sel ? A.cyn + '▶' + A.R : ' ';
+      const currentJob = generationActive && generationChildren.has(s.id);
+      const queuedJob = generationActive && generationJobs.some(job => job.target.id === s.id);
       const ts = A.gry + fmtTs(s.mtime) + A.R;
       const cwd = A.mag + pad(shortCwd(s.effectiveCwd), 14) + A.R;
       const badge = s.isCurrent ? A.grn + A.B + '[NOW]' + A.R + ' ' : '';
-      // ✎ marks a user-renamed session so it's clear the label isn't the prompt.
-      const pen = s.titleOverride ? A.cyn + '✎' + A.R + ' ' : '';
-      const titleMax = Math.max(20, W - 38 - (s.isCurrent ? 7 : 0) - (s.titleOverride ? 2 : 0));
+      // Generation state and title provenance share one stable marker column.
+      const marker = currentJob
+        ? A.yel + '↻' + A.R + ' '
+        : queuedJob
+          ? A.gry + '…' + A.R + ' '
+          : s.titleOverride
+            ? A.cyn + (s.titleSource === 'llm' ? '◆' : '✎') + A.R + ' '
+            : '';
+      const titleMax = Math.max(20, W - 38 - (s.isCurrent ? 7 : 0) - (marker ? 2 : 0));
       const title = trunc(s.title, titleMax);
-      const rowText = ` ${arrow} ${star} ${ts}  ${cwd}  ${badge}${pen}${title}`;
+      const rowText = ` ${arrow} ${star} ${ts}  ${cwd}  ${badge}${marker}${title}`;
       if (sel) {
         const pad2 = ' '.repeat(Math.max(0, W - visLen(rowText) - 1));
         out += A.bgBlu + rowText + pad2 + A.R + '\n';
@@ -489,6 +715,8 @@ function renderList() {
       + A.D + 'Enter' + A.R + ' current  '
       + A.D + 'o' + A.R + ' original  '
       + A.D + 'e' + A.R + ' edit name  '
+      + A.D + 'g' + A.R + ' queue title  '
+      + A.D + 'G' + A.R + ' settings  '
       + A.D + 'p' + A.R + ' edit cwd  '
       + A.D + 'd' + A.R + ' details  '
       + A.D + '/' + A.R + ' search  '
@@ -498,6 +726,207 @@ function renderList() {
   process.stdout.write(out);
 }
 
+function filteredModels() {
+  const q = modelFilter.toLowerCase();
+  return q ? models.filter(m => m.toLowerCase().includes(q)) : models;
+}
+
+function renderModelPicker() {
+  const W = process.stdout.columns || 100;
+  const H = process.stdout.rows || 30;
+  const list = filteredModels();
+  if (modelSel >= list.length) modelSel = Math.max(0, list.length - 1);
+  let out = A.clr;
+  out += ' ' + A.B + A.cyn + 'pisesh' + A.R + A.D + '  title generation settings' + A.R + '\n\n';
+  if (settingsPendingTarget) out += ' ' + A.D + 'generate' + A.R + '  ' + trunc(settingsPendingTarget.title, W - 14) + '\n';
+  out += ' ' + A.D + 'filter ' + A.R + A.cyn + modelFilter + A.R + (modelFilter ? A.I + ' ' + A.R : '') + '\n';
+  out += A.gry + '─'.repeat(Math.max(1, W - 1)) + A.R + '\n';
+  if (modelStatus) out += '\n ' + A.D + modelStatus + A.R + '\n';
+  else if (!list.length) out += '\n ' + A.D + '(no matching models)' + A.R + '\n';
+  else {
+    const effortWidths = EFFORT_LEVELS.map(level => level.length + 2);
+    const effortTotal = effortWidths.reduce((sum, width) => sum + width, 0);
+    const modelWidth = Math.max(12, W - effortTotal - 5);
+    out += '   ' + A.D + pad('model', modelWidth) + pad('effort', effortTotal) + A.R + '\n';
+    const usable = Math.max(3, H - 10);
+    const start = Math.max(0, Math.min(modelSel - Math.floor(usable / 2), list.length - usable));
+    for (let i = start; i < Math.min(list.length, start + usable); i++) {
+      const selected = i === modelSel;
+      const supportsEffort = modelThinking.has(list[i]);
+      let row = ' ' + (selected ? A.cyn + '▶' + A.R : ' ') + ' ';
+      row += (selected ? A.B : '') + pad(trunc(list[i], modelWidth), modelWidth) + (selected ? A.R : '');
+      for (let j = 0; j < EFFORT_LEVELS.length; j++) {
+        const level = EFFORT_LEVELS[j];
+        const available = supportsEffort || level === 'off';
+        const cell = pad(available ? level : '—', effortWidths[j]);
+        if (selected && level === modelEffort) row += A.bgBlu + A.B + cell + A.R;
+        else row += available ? A.D + cell + A.R : A.gry + cell + A.R;
+      }
+      out += row + '\n';
+    }
+  }
+  out += '\n' + A.gry + '─'.repeat(Math.max(1, W - 1)) + A.R + '\n';
+  out += ' ' + A.yel + 'Sends up to 16 KB of session text; provider charges may apply.' + A.R + '\n';
+  out += ' ' + A.D + '↑↓' + A.R + ' model  ' + A.D + '←→' + A.R + ' effort  '
+      + A.D + 'type' + A.R + ' filter  ' + A.grn + A.B + 'Enter' + A.R + ' save  '
+      + A.D + 'Esc' + A.R + ' cancel\n';
+  process.stdout.write(out);
+}
+
+function openGenerationSettings(pendingTarget = null) {
+  settingsPendingTarget = pendingTarget;
+  modelFilter = '';
+  modelSel = 0;
+  mode = 'model';
+  modelStatus = 'Loading models from pi…';
+  render();
+  let stdout = '', stderr = '';
+  const requestId = ++modelRequestId;
+  const child = spawn('pi', ['--list-models'], {
+    stdio: ['ignore', 'pipe', 'pipe'],
+    env: PI_ENV,
+  });
+  child.stdout.on('data', d => { stdout += d; });
+  child.stderr.on('data', d => { stderr += d; });
+  child.on('error', e => {
+    if (mode === 'model' && requestId === modelRequestId) {
+      modelStatus = `Could not run pi: ${e.message}`;
+      render();
+    }
+  });
+  child.on('close', code => {
+    if (mode !== 'model' || requestId !== modelRequestId) return;
+    const entries = code === 0 ? parseModelEntries(stdout) : [];
+    models = entries.map(entry => entry.id);
+    modelThinking = new Set(entries.filter(entry => entry.thinking).map(entry => entry.id));
+    modelStatus = models.length ? '' : `Could not list models${stderr.trim() ? `: ${stderr.trim()}` : ''}`;
+    const preferred = [metaSettings.titleModel, configuredPiModel()].filter(Boolean);
+    const idx = preferred.map(m => models.indexOf(m)).find(i => i >= 0);
+    modelSel = idx !== undefined ? idx : 0;
+    modelEffort = EFFORT_LEVELS.includes(metaSettings.titleThinkingLevel) ? metaSettings.titleThinkingLevel : 'off';
+    if (!modelThinking.has(models[modelSel])) modelEffort = 'off';
+    render();
+  });
+}
+
+function takeGenerationBatch(queue, activeCount, limit = TITLE_GENERATION_CONCURRENCY) {
+  const available = Math.max(0, limit - activeCount);
+  return queue.splice(0, available);
+}
+
+function enqueueTitle(target) {
+  if (!target) return;
+  const blocked = titleGenerationBlocker(target);
+  if (blocked) { notice = blocked; return; }
+  if (!metaSettings.titleModel) return openGenerationSettings(target);
+  if (generationChildren.has(target.id) || generationJobs.some(job => job.target.id === target.id)) return;
+
+  generationJobs.push({
+    target,
+    model: metaSettings.titleModel,
+    effort: metaSettings.titleThinkingLevel || 'off',
+  });
+  if (!generationActive) {
+    generationCancelled = false;
+    generationActive = true;
+  }
+  pumpTitleGeneration();
+}
+
+function finishGeneration() {
+  generationActive = false;
+  generationJobs = [];
+  generationChildren.clear();
+  generationCancelled = false;
+  if (!handingOff) render();
+}
+
+function terminateChild(child) {
+  child.kill('SIGTERM');
+  const force = setTimeout(() => {
+    if (child.exitCode === null && child.signalCode === null) child.kill('SIGKILL');
+  }, 1000);
+  force.unref();
+}
+
+function cancelGeneration() {
+  if (!generationActive) return false;
+  generationCancelled = true;
+  generationJobs = [];
+  notice = 'title generation cancelled';
+  for (const child of generationChildren.values()) terminateChild(child);
+  if (generationChildren.size === 0) finishGeneration();
+  else if (!handingOff) render();
+  return true;
+}
+
+function pumpTitleGeneration() {
+  if (generationCancelled) {
+    if (generationChildren.size === 0) finishGeneration();
+    return;
+  }
+
+  while (generationJobs.length && generationChildren.size < TITLE_GENERATION_CONCURRENCY) {
+    const batch = takeGenerationBatch(generationJobs, generationChildren.size);
+    for (const job of batch) startTitleGeneration(job);
+  }
+
+  if (generationJobs.length === 0 && generationChildren.size === 0) finishGeneration();
+  else if (!handingOff) render();
+}
+
+function startTitleGeneration(job) {
+  let prompt;
+  try { prompt = buildTitlePrompt(job.target.file); }
+  catch (e) { notice = `title generation failed: ${e.message}`; return; }
+
+  let stdout = '', settled = false, timedOut = false;
+  const child = spawn('pi', titleGenerationArgs(job.model, job.effort, prompt), {
+    stdio: ['ignore', 'pipe', 'pipe'],
+    env: PI_ENV,
+  });
+  generationChildren.set(job.target.id, child);
+  const timer = setTimeout(() => {
+    if (!settled) { timedOut = true; terminateChild(child); }
+  }, 120000);
+  child.stdout.on('data', d => { stdout += d; });
+  child.stderr.resume();
+  const complete = () => {
+    if (settled) return;
+    settled = true;
+    clearTimeout(timer);
+    if (generationChildren.get(job.target.id) === child) generationChildren.delete(job.target.id);
+    pumpTitleGeneration();
+  };
+  child.on('error', () => {
+    notice = 'title generation failed: could not start pi';
+    complete();
+  });
+  child.on('close', code => {
+    if (settled) return;
+    if (code === 0 && !generationCancelled) {
+      try {
+        const title = cleanGeneratedTitle(stdout);
+        const current = overridesFor(job.target.id);
+        if (current.title && current.titleSource !== 'llm') {
+          notice = 'generated title discarded: manual title now exists';
+          return complete();
+        }
+        saveTitle(job.target.id, title, 'llm', job.model, job.effort);
+        notice = `generated title: ${trunc(title, 72)}`;
+        return complete();
+      } catch {
+        notice = 'title generation failed: model returned no usable title';
+      }
+    } else if (!generationCancelled) {
+      notice = timedOut
+        ? 'title generation timed out after 120 seconds'
+        : `title generation failed: pi exited ${code ?? 'without a status'}`;
+    }
+    complete();
+  });
+}
+
 // Inline editor for a session's title or cwd. Renders a small focused panel
 // so the user always sees which session + field they're changing.
 function renderEdit() {
@@ -556,7 +985,11 @@ function renderDetails() {
   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('title', s.title + (s.titleOverride ? A.cyn + '  (custom)' + A.R : ''));
+  out += row('title', s.title + (s.titleOverride ? A.cyn + `  (${s.titleSource === 'llm' ? 'generated' : 'custom'})` + A.R : ''));
+  if (s.titleModel) {
+    out += row('title model', s.titleModel, A.cyn);
+    out += row('title effort', s.titleThinkingLevel || 'off', A.cyn);
+  }
   out += row('started', new Date(s.ts).toLocaleString());
   out += row('updated', new Date(s.mtime).toLocaleString());
   out += row('cwd', s.effectiveCwd + (s.cwdOverride ? A.cyn + '  (custom)' + A.R : ''), A.mag);
@@ -579,6 +1012,7 @@ function renderDetails() {
       + A.D + 'o' + A.R + ' original settings  '
       + A.D + 'f' + A.R + ' star  '
       + A.D + 'e' + A.R + ' edit name  '
+      + A.D + 'g' + A.R + ' generate title  '
       + A.D + 'p' + A.R + ' edit cwd  '
       + A.D + 'c' + A.R + ' copy id  '
       + A.D + 'Esc/d/q' + A.R + ' back' + A.R + '\n';
@@ -611,9 +1045,16 @@ function setupInput() {
 
   process.stdin.on('keypress', (str, key) => {
     try {
+      if (generationActive && key.ctrl && key.name === 'c') return quit();
+      if (generationActive && (mode === 'list' || mode === 'details') && (key.name === 'escape' || key.name === 'q')) {
+        if (generationCancelled) return quit();
+        cancelGeneration();
+        return;
+      }
       if (mode === 'filter') handleFilter(str, key);
       else if (mode === 'edit') handleEdit(str, key);
       else if (mode === 'browse') handleBrowse(str, key);
+      else if (mode === 'model') handleModelPicker(str, key);
       else if (mode === 'details') handleDetails(str, key);
       else handleList(str, key);
       render();
@@ -637,7 +1078,10 @@ function handleList(str, key) {
   const k = key.name;
 
   if (key.ctrl && k === 'c') return quit();
-  if (k === 'q') return quit();
+  if (k === 'q') {
+    if (filter) { filter = ''; cursor = 0; return; }
+    return quit();
+  }
   // Esc: clears filter first (one-step back-out), otherwise quits.
   // Matches `q` so muscle memory works either way.
   if (k === 'escape') {
@@ -670,6 +1114,8 @@ function handleList(str, key) {
   }
   else if (k === 'd') { if (list[cursor]) mode = 'details'; }
   else if (k === 'e') startEdit(list[cursor], 'title');
+  else if (k === 'g' && (str === 'G' || key.shift)) openGenerationSettings();
+  else if (k === 'g') enqueueTitle(list[cursor]);
   else if (k === 'p') startBrowse(list[cursor]);
   else if (str === '/') { mode = 'filter'; }
   else if (k === 'r') { sessions = scanSessions(); cursor = 0; }
@@ -681,7 +1127,8 @@ function handleList(str, key) {
 
 function handleFilter(str, key) {
   const k = key.name;
-  if (k === 'return' || k === 'escape') { mode = 'list'; return; }
+  if (k === 'return') { mode = 'list'; return; }
+  if (k === 'escape' || k === 'q') { filter = ''; cursor = 0; 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; }
@@ -704,9 +1151,52 @@ function handleDetails(str, key) {
     tryCopy(s.id);
   }
   if (k === 'e' && s) startEdit(s, 'title');
+  if (k === 'g' && (str === 'G' || key.shift)) openGenerationSettings();
+  else if (k === 'g' && s) enqueueTitle(s);
   if (k === 'p' && s) startBrowse(s);
 }
 
+function handleModelPicker(str, key) {
+  const k = key.name;
+  const list = filteredModels();
+  if (key.ctrl && k === 'c') return quit();
+  if (k === 'escape' || k === 'q') {
+    modelRequestId++;
+    mode = 'list'; settingsPendingTarget = null; modelStatus = ''; return;
+  }
+  if (k === 'up' || k === 'k') {
+    modelSel = Math.max(0, modelSel - 1);
+    if (!modelThinking.has(list[modelSel])) modelEffort = 'off';
+    return;
+  }
+  if (k === 'down' || k === 'j') {
+    modelSel = Math.min(list.length - 1, modelSel + 1);
+    if (!modelThinking.has(list[modelSel])) modelEffort = 'off';
+    return;
+  }
+  if ((k === 'left' || k === 'right') && modelThinking.has(list[modelSel])) {
+    const delta = k === 'right' ? 1 : -1;
+    const idx = EFFORT_LEVELS.indexOf(modelEffort);
+    modelEffort = EFFORT_LEVELS[(idx + delta + EFFORT_LEVELS.length) % EFFORT_LEVELS.length];
+    return;
+  }
+  if (k === 'return') {
+    if (!modelStatus.startsWith('Loading') && list[modelSel]) {
+      metaSettings.titleModel = list[modelSel];
+      metaSettings.titleThinkingLevel = modelEffort;
+      saveMeta();
+      const pending = settingsPendingTarget;
+      settingsPendingTarget = null;
+      mode = 'list';
+      if (pending) enqueueTitle(pending);
+    }
+    return;
+  }
+  if (k === 'backspace') { modelFilter = modelFilter.slice(0, -1); modelSel = 0; return; }
+  if (key.ctrl && k === 'u') { modelFilter = ''; modelSel = 0; return; }
+  if (str && str.length === 1 && !key.ctrl) { modelFilter += str; modelSel = 0; }
+}
+
 // Open the inline editor for a session's title or cwd, seeded with the
 // current override (or recorded cwd, so the user can tweak rather than retype).
 function startEdit(s, field) {
@@ -723,7 +1213,10 @@ function handleEdit(str, key) {
   if (key.ctrl && k === 'c') return quit();
   if (k === 'escape') { mode = 'list'; editTarget = null; return; }
   if (k === 'return') {
-    if (editTarget) setOverride(editTarget.id, editField, editBuffer);
+    if (editTarget) {
+      if (editField === 'title') saveTitle(editTarget.id, editBuffer, 'manual');
+      else setOverride(editTarget.id, editField, editBuffer);
+    }
     mode = 'list';
     editTarget = null;
     return;
@@ -994,6 +1487,10 @@ function buildResumeArgs(s, useCurrentDefaults = true, settingsFile = SETTINGS_F
 
 function resumeSession(s, useCurrentDefaults = true) {
   if (!s) return;
+  // A resumed pi takes over this terminal, so stop background title work first
+  // and suppress any final render from its asynchronous close handler.
+  handingOff = true;
+  cancelGeneration();
   // Heal orphaned tool calls before handing off, so resume can't crash the
   // spawned pi (see healOrphanedToolCalls).
   let repaired;
@@ -1019,6 +1516,7 @@ function resumeSession(s, useCurrentDefaults = true) {
   const child = spawn('pi', buildResumeArgs(s, useCurrentDefaults), {
     stdio: 'inherit',
     cwd: targetCwd && fs.existsSync(targetCwd) ? targetCwd : process.cwd(),
+    env: PI_ENV,
   });
   child.on('exit', code => process.exit(code || 0));
   child.on('error', err => {
@@ -1028,6 +1526,8 @@ function resumeSession(s, useCurrentDefaults = true) {
 }
 
 function quit() {
+  handingOff = true;
+  for (const child of generationChildren.values()) child.kill('SIGKILL');
   // 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.
@@ -1058,13 +1558,17 @@ TUI keys:
   Enter            resume with current default model and thinking settings
   o                resume with the session-recorded model and thinking settings
   e                edit name (custom display title)
+  g                queue title generation with the saved model + effort
+                   (first use opens settings; active/queued threads are ignored)
+  G                open title generation model + effort settings
   p                edit cwd — arrow-key directory browser
                    (↑↓ move, →/Enter open dir, ← parent, s select, Esc cancel)
                    sets the working directory used on resume / "Here" tab
   d                show details
   /                search (id / project / prompt / title)
   r                rescan session files
-  q / Esc / Ctrl-C quit
+  q / Esc          cancel generation / clear search first; press again to quit
+  Ctrl-C           cancel generation and quit immediately
 
 Tabs:
   Here             only sessions whose cwd matches the directory pisesh was
@@ -1134,4 +1638,17 @@ function main() {
 }
 
 if (require.main === module) main();
-else module.exports = { buildResumeArgs, cleanStaleFavorites, healOrphanedToolCalls, loadResumeDefaults };
+else module.exports = {
+  buildResumeArgs,
+  buildTitlePrompt,
+  cleanGeneratedTitle,
+  cleanStaleFavorites,
+  healOrphanedToolCalls,
+  loadResumeDefaults,
+  parseModelEntries,
+  parseModelList,
+  piAgentEnv,
+  takeGenerationBatch,
+  titleGenerationArgs,
+  titleGenerationBlocker,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pisesh",
-  "version": "0.1.13",
+  "version": "0.2.0",
   "description": "Bookmark, search, and resume pi coding-agent sessions with a fast keyboard-driven TUI.",
   "keywords": [
     "pi-package",