pikiloom 0.4.26 → 0.4.27

package/dist/agent/session.js

@@ -1,6 +1,3 @@
-/**
- * Session workspace management, metadata persistence, classification, and export/import.
- */
 import crypto from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
@@ -8,9 +5,6 @@ import { dedupeStrings, shortValue, firstNonEmptyLine, normalizeErrorMessage, no
 import { getDriver } from './driver.js';
 import { collapseSkillPrompt } from './skills.js';
 import { SESSION_RUNNING_THRESHOLD_MS } from '../core/constants.js';
-// ---------------------------------------------------------------------------
-// Private helpers
-// ---------------------------------------------------------------------------
 function ensureDir(dirPath) { fs.mkdirSync(dirPath, { recursive: true }); }
 function readJsonFile(filePath, fallback) {
     try {
@@ -38,19 +32,12 @@ function trimSessionText(value, max = 24_000) {
         return text;
     return `${text.slice(0, Math.max(0, max - 3)).trimEnd()}...`;
 }
-// ---------------------------------------------------------------------------
-// Constants
-// ---------------------------------------------------------------------------
 const PIKILOOM_DIR = '.pikiloom';
 const PIKILOOM_SESSIONS_DIR = path.join(PIKILOOM_DIR, 'sessions');
 const PIKILOOM_SESSION_INDEX = path.join(PIKILOOM_SESSIONS_DIR, 'index.json');
 const PIKILOOM_LEGACY_WORKSPACES_DIR = path.join(PIKILOOM_DIR, 'workspaces');
 const SESSION_WORKSPACE_DIR = 'workspace';
 const SESSION_META_FILE = 'session.json';
-// return.json and artifact constants removed — file return is now handled by MCP bridge
-// ---------------------------------------------------------------------------
-// Path helpers
-// ---------------------------------------------------------------------------
 function sessionIndexPath(workdir) { return path.join(workdir, PIKILOOM_SESSION_INDEX); }
 function sessionDirPath(workdir, agent, sessionId) { return path.join(workdir, PIKILOOM_SESSIONS_DIR, agent, sessionId); }
 function legacySessionWorkspacePath(workdir, agent, sessionId) { return path.join(workdir, PIKILOOM_LEGACY_WORKSPACES_DIR, agent, sessionId); }
@@ -61,19 +48,12 @@ function sessionRootFromWorkspacePath(workspacePath) {
 }
 function sessionMetaPath(workspacePath) { return path.join(sessionRootFromWorkspacePath(workspacePath), SESSION_META_FILE); }
 function legacySessionMetaPath(workspacePath) { return path.join(workspacePath, PIKILOOM_DIR, SESSION_META_FILE); }
-// ---------------------------------------------------------------------------
-// ID helpers
-// ---------------------------------------------------------------------------
-/** Generate a temporary session ID for new sessions before the agent assigns one. */
 function nextPendingSessionId() { return `pending_${crypto.randomBytes(6).toString('hex')}`; }
 function nextThreadId() { return `thread_${crypto.randomBytes(6).toString('hex')}`; }
 function legacyThreadId(agent, sessionId) { return `legacy:${agent}:${sessionId}`; }
 function normalizeThreadId(value) {
     return typeof value === 'string' && value.trim() ? value.trim() : null;
 }
-// ---------------------------------------------------------------------------
-// Run state helpers
-// ---------------------------------------------------------------------------
 function normalizeSessionRunState(rawState) {
     const state = typeof rawState === 'string' ? rawState.trim().toLowerCase() : '';
     if (state === 'completed' || state === 'incomplete' || state === 'running')
@@ -111,11 +91,6 @@ function incompleteRunDetail(result) {
     const message = firstNonEmptyLine(result.message || '');
     return message ? shortValue(message, 180) : 'Last run did not complete.';
 }
-/**
- * Check whether a process is still alive. Returns true when the PID exists and we can
- * signal it, false when the process is definitively gone, and null when we cannot tell
- * (e.g. owned by a different user — permission denied).
- */
 export function isProcessAlive(pid) {
     if (!pid || !Number.isFinite(pid) || pid <= 0)
         return null;
@@ -131,13 +106,6 @@ export function isProcessAlive(pid) {
         return null;
     }
 }
-/**
- * Heuristic staleness check for a session record marked 'running'. Returns true when
- * the record should be downgraded to 'incomplete' — i.e. the owning process is gone,
- * or (if PID is missing) the last update is older than `ageThresholdMs`.
- *
- * Returns false if the session might still be live and should be left alone.
- */
 export function isRunningSessionStale(record, ageThresholdMs) {
     if (record.runState !== 'running')
         return false;
@@ -149,11 +117,6 @@ export function isRunningSessionStale(record, ageThresholdMs) {
     const age = record.runUpdatedAt ? Date.now() - Date.parse(record.runUpdatedAt) : Infinity;
     return age > ageThresholdMs;
 }
-/**
- * Scan the session index for a workdir and downgrade any 'running' record whose
- * owning process is no longer alive (or that has gone stale past `ageThresholdMs`).
- * Returns the number of records downgraded. Safe to call at startup and periodically.
- */
 export function reconcileOrphanedRunningSessions(workdir, ageThresholdMs = 30 * 60_000) {
     const resolvedWorkdir = path.resolve(workdir);
     const index = loadSessionIndex(resolvedWorkdir);
@@ -183,10 +146,8 @@ export function applySessionRunResult(record, result) {
     else {
         setSessionRunState(record, 'incomplete', incompleteRunDetail(result));
     }
-    // Auto-classify the stream result
     const classification = classifySession({ ...result, activity: result.activity ?? null });
     record.classification = classification;
-    // Only set userStatus if not manually overridden by the user
     if (!record.userStatus) {
         record.userStatus = deriveUserStatus(classification.outcome);
     }
@@ -202,7 +163,6 @@ function normalizeHandoverRef(value) {
     return { agent: agent, sessionId };
 }
 function normalizeSessionRecord(raw, workdir) {
-    // Support both new format (sessionId) and legacy format (localSessionId + engineSessionId)
     const sessionId = typeof raw?.sessionId === 'string' ? raw.sessionId.trim()
         : typeof raw?.engineSessionId === 'string' && raw.engineSessionId.trim() ? raw.engineSessionId.trim()
             : typeof raw?.localSessionId === 'string' ? raw.localSessionId.trim()
@@ -246,20 +206,7 @@ function normalizeSessionRecord(raw, workdir) {
         handoverFrom: normalizeHandoverRef(raw?.handoverFrom),
     };
 }
-// ---------------------------------------------------------------------------
-// Index persistence
-// ---------------------------------------------------------------------------
-/**
- * Parsed-index cache keyed by index-file identity (mtime + size). loadSessionIndex
- * sits on the per-turn read path (getSessionStoredConfig), every dashboard session
- * read, and is hit several times within a single save flow — each call otherwise
- * does readFileSync + JSON.parse + a per-record normalize pass. A cache hit costs
- * one statSync. writeSessionIndex invalidates the entry, so a write is always
- * re-read fresh; every writer mutates records then writes, so the shared cache is
- * never left serving a half-mutated record.
- */
 const sessionIndexCache = new Map();
-/** Sort session records newest-first, parsing each `updatedAt` only once. */
 function sortByUpdatedAtDesc(records) {
     const at = new Map(records.map(r => [r, Date.parse(r.updatedAt) || 0]));
     return records.sort((a, b) => at.get(b) - at.get(a));
@@ -278,22 +225,102 @@ function loadSessionIndex(workdir) {
     }
     const parsed = readJsonFile(filePath, { version: 1, sessions: [] });
     const sessions = Array.isArray(parsed?.sessions) ? parsed.sessions : [];
+    const promotions = {};
+    if (parsed?.promotions && typeof parsed.promotions === 'object') {
+        for (const [k, v] of Object.entries(parsed.promotions)) {
+            if (typeof k === 'string' && k && typeof v === 'string' && v && k !== v)
+                promotions[k] = v;
+        }
+    }
     const data = {
         version: 1,
         sessions: sessions
             .map((entry) => normalizeSessionRecord(entry, workdir))
             .filter((entry) => !!entry)
             .filter((entry) => !isPendingSessionId(entry.sessionId) || fs.existsSync(sessionRootFromWorkspacePath(entry.workspacePath))),
+        promotions,
     };
     if (stat)
         sessionIndexCache.set(filePath, { mtimeMs: stat.mtimeMs, size: stat.size, data });
     return data;
 }
-function writeSessionIndex(workdir, sessions) {
+function writeSessionIndex(workdir, sessions, promotionsOverride) {
     const filePath = sessionIndexPath(workdir);
-    writeJsonFile(filePath, { version: 1, sessions });
+    const promotions = promotionsOverride ?? loadSessionIndex(workdir).promotions;
+    const payload = { version: 1, sessions };
+    if (promotions && Object.keys(promotions).length)
+        payload.promotions = promotions;
+    writeJsonFile(filePath, payload);
     sessionIndexCache.delete(filePath);
 }
+function prunePromotionsForDeletedSession(promotions, agent, deletedId) {
+    if (!promotions)
+        return null;
+    const out = {};
+    let changed = false;
+    for (const [key, val] of Object.entries(promotions)) {
+        const ci = key.indexOf(':');
+        const kAgent = ci > 0 ? key.slice(0, ci) : '';
+        const kOld = ci > 0 ? key.slice(ci + 1) : '';
+        if (kAgent === agent && (val === deletedId || kOld === deletedId)) {
+            changed = true;
+            continue;
+        }
+        out[key] = val;
+    }
+    return changed ? out : null;
+}
+export function resolveCanonicalSessionId(workdir, agent, sessionId) {
+    if (!sessionId)
+        return sessionId;
+    const resolvedWorkdir = path.resolve(workdir);
+    const promotions = loadSessionIndex(resolvedWorkdir).promotions;
+    let id = sessionId;
+    const seen = new Set();
+    while (!seen.has(id)) {
+        seen.add(id);
+        let next = promotions?.[`${agent}:${id}`];
+        if (!next && isPendingSessionId(id)) {
+            const aliased = readSessionDirAliasTarget(resolvedWorkdir, agent, id);
+            if (aliased) {
+                recordSessionPromotion(resolvedWorkdir, agent, id, aliased);
+                next = aliased;
+            }
+        }
+        if (!next || next === id)
+            break;
+        id = next;
+    }
+    return id;
+}
+function readSessionDirAliasTarget(workdir, agent, sessionId) {
+    try {
+        const dir = sessionDirPath(workdir, agent, sessionId);
+        if (!fs.lstatSync(dir).isSymbolicLink())
+            return null;
+        const native = path.basename(fs.readlinkSync(dir).replace(/[/\\]+$/, ''));
+        return native && native !== sessionId && !isPendingSessionId(native) ? native : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function getSessionPromotions(workdir) {
+    return { ...loadSessionIndex(path.resolve(workdir)).promotions };
+}
+function recordSessionPromotion(workdir, agent, oldId, newId) {
+    if (!oldId || !newId || oldId === newId)
+        return;
+    const resolvedWorkdir = path.resolve(workdir);
+    const index = loadSessionIndex(resolvedWorkdir);
+    const promotions = { ...index.promotions };
+    for (const k of Object.keys(promotions)) {
+        if (promotions[k] === oldId && k.startsWith(`${agent}:`))
+            promotions[k] = newId;
+    }
+    promotions[`${agent}:${oldId}`] = newId;
+    writeSessionIndex(resolvedWorkdir, index.sessions, promotions);
+}
 function writeSessionMeta(record) {
     writeJsonFile(sessionMetaPath(record.workspacePath), {
         sessionId: record.sessionId, agent: record.agent, workdir: record.workdir,
@@ -317,9 +344,6 @@ function writeSessionMeta(record) {
         handoverFrom: record.handoverFrom ?? null,
     });
 }
-// ---------------------------------------------------------------------------
-// File / directory helpers
-// ---------------------------------------------------------------------------
 function copyPath(sourcePath, targetPath) {
     const stat = fs.statSync(sourcePath);
     if (stat.isDirectory()) {
@@ -339,9 +363,6 @@ function createSessionDirAlias(aliasPath, targetPath) {
     }
     catch { }
 }
-// ---------------------------------------------------------------------------
-// Migration
-// ---------------------------------------------------------------------------
 function migrateSessionLayout(workdir, record) {
     const targetSessionDir = sessionDirPath(workdir, record.agent, record.sessionId);
     const targetWorkspacePath = sessionWorkspacePath(workdir, record.agent, record.sessionId);
@@ -365,9 +386,6 @@ function migrateSessionLayout(workdir, record) {
     record.workspacePath = path.resolve(targetWorkspacePath);
     return record;
 }
-// ---------------------------------------------------------------------------
-// Save / update
-// ---------------------------------------------------------------------------
 export function saveSessionRecord(workdir, record) {
     record = migrateSessionLayout(workdir, record);
     ensureDir(sessionDirPath(workdir, record.agent, record.sessionId));
@@ -385,10 +403,6 @@ export function saveSessionRecord(workdir, record) {
     writeSessionMeta(record);
     return record;
 }
-/**
- * Update mutable session metadata (classification, userStatus, userNote, links, migration)
- * for an existing pikiloom-managed session. Returns true if the record was found and updated.
- */
 export function updateSessionMeta(workdir, agent, sessionId, patch) {
     const resolvedWorkdir = path.resolve(workdir);
     const index = loadSessionIndex(resolvedWorkdir);
@@ -417,10 +431,6 @@ export function updateSessionMeta(workdir, agent, sessionId, patch) {
     writeSessionMeta(record);
     return true;
 }
-/**
- * Promote a pending session to a real session ID. Renames the workspace directory
- * and updates the index. Called after the first stream returns the agent's native ID.
- */
 export function promoteSessionId(workdir, agent, pendingId, nativeId) {
     if (!isPendingSessionId(pendingId) || !nativeId.trim())
         return;
@@ -431,12 +441,11 @@ export function promoteSessionId(workdir, agent, pendingId, nativeId) {
         return;
     const oldDir = sessionDirPath(resolvedWorkdir, agent, pendingId);
     const newDir = sessionDirPath(resolvedWorkdir, agent, nativeId);
-    // Move workspace directory if it exists
     if (fs.existsSync(oldDir) && !fs.existsSync(newDir)) {
         try {
             fs.renameSync(oldDir, newDir);
         }
-        catch { /* cross-device: copy+delete */
+        catch {
             try {
                 fs.cpSync(oldDir, newDir, { recursive: true });
                 fs.rmSync(oldDir, { recursive: true, force: true });
@@ -450,19 +459,6 @@ export function promoteSessionId(workdir, agent, pendingId, nativeId) {
     record.workspacePath = sessionWorkspacePath(resolvedWorkdir, agent, nativeId);
     saveSessionRecord(resolvedWorkdir, record);
 }
-// ---------------------------------------------------------------------------
-// Fork lineage
-// ---------------------------------------------------------------------------
-/**
- * Record a fork relationship between two pikiloom-managed sessions.
- *
- * Sets `migratedFrom` (with kind='fork' + forkedAtTurn) on the child and
- * appends the reverse link on the parent's `linkedSessions`. Both sides also
- * get `migratedTo` set on the parent so the child is a discoverable twin.
- *
- * No-op if either record is missing — call sites are expected to ensure both
- * managed records exist (the child is created via the fork stream completion).
- */
 export function recordFork(workdir, opts) {
     const resolvedWorkdir = path.resolve(workdir);
     const index = loadSessionIndex(resolvedWorkdir);
@@ -488,9 +484,6 @@ export function recordFork(workdir, opts) {
     writeSessionMeta(parent);
     writeSessionMeta(child);
 }
-// ---------------------------------------------------------------------------
-// Identity sync
-// ---------------------------------------------------------------------------
 export function syncManagedSessionIdentity(session, workdir, nativeId) {
     const resolvedId = nativeId.trim();
     if (!resolvedId || session.sessionId === resolvedId)
@@ -498,16 +491,9 @@ export function syncManagedSessionIdentity(session, workdir, nativeId) {
     const resolvedWorkdir = path.resolve(workdir);
     const previousId = session.sessionId;
     if (isPendingSessionId(previousId)) {
-        // Pending → native: move the workspace dir into the native slot and
-        // remove the pending index entry (handled by promoteSessionId).
         promoteSessionId(resolvedWorkdir, session.record.agent, previousId, resolvedId);
     }
     else {
-        // Native → native rotation (Claude `--resume` can rewrite the session id
-        // mid-stream). Drop the old index entry so the dashboard does not show a
-        // stale duplicate; both jsonl files stay on disk and the workspace stays
-        // under its original native id (the next saveSessionRecord will lay down
-        // a fresh dir under the new id).
         const index = loadSessionIndex(resolvedWorkdir);
         const filtered = index.sessions.filter(e => !(e.agent === session.record.agent && e.sessionId === previousId));
         if (filtered.length !== index.sessions.length)
@@ -517,11 +503,9 @@ export function syncManagedSessionIdentity(session, workdir, nativeId) {
     session.workspacePath = sessionWorkspacePath(resolvedWorkdir, session.record.agent, resolvedId);
     session.record.sessionId = resolvedId;
     session.record.workspacePath = session.workspacePath;
+    recordSessionPromotion(resolvedWorkdir, session.record.agent, previousId, resolvedId);
     return true;
 }
-// ---------------------------------------------------------------------------
-// Title / filename helpers
-// ---------------------------------------------------------------------------
 export function summarizePromptTitle(prompt) {
     const raw = String(prompt || '').replace(/\r\n?/g, '\n');
     const text = firstNonEmptyLine(raw).replace(/\s+/g, ' ').trim()
@@ -546,9 +530,6 @@ function uniqueWorkspaceFilename(workspacePath, desiredName) {
     }
     return candidate;
 }
-// ---------------------------------------------------------------------------
-// Workspace file import
-// ---------------------------------------------------------------------------
 export function importFilesIntoWorkspace(workspacePath, files) {
     const imported = [];
     const realWorkspace = fs.realpathSync(workspacePath);
@@ -556,13 +537,6 @@ export function importFilesIntoWorkspace(workspacePath, files) {
         const resolved = path.resolve(filePath);
         if (!fs.existsSync(resolved) || !fs.statSync(resolved).isFile())
             continue;
-        // Resolve symlinks on the source too — realWorkspace is already realpath'd,
-        // so comparing it against a merely path.resolve'd source makes a file that
-        // ALREADY lives in the workspace look "outside" whenever a path component is
-        // a symlink (macOS /tmp → /private/tmp, or an iCloud-synced ~/Desktop). That
-        // mis-detection re-copies an already-staged attachment under a collision
-        // name, so the same image lands in the prompt TWICE and renders twice.
-        // realpath'ing both sides keeps the in-workspace check symlink-safe.
         const sourcePath = fs.realpathSync(resolved);
         const relPath = path.relative(realWorkspace, sourcePath);
         if (relPath && !relPath.startsWith('..') && !path.isAbsolute(relPath)) {
@@ -575,9 +549,6 @@ export function importFilesIntoWorkspace(workspacePath, files) {
     }
     return dedupeStrings(imported);
 }
-// ---------------------------------------------------------------------------
-// Ensure session workspace
-// ---------------------------------------------------------------------------
 export function ensureSessionWorkspace(opts) {
     const workdir = path.resolve(opts.workdir);
     const index = loadSessionIndex(workdir);
@@ -604,7 +575,6 @@ export function ensureSessionWorkspace(opts) {
     }
     if (!record.threadId)
         record.threadId = normalizeThreadId(opts.threadId) || legacyThreadId(record.agent, record.sessionId);
-    // Backfill handoverFrom on first staging only — never overwrite an existing one.
     if (!record.handoverFrom)
         record.handoverFrom = normalizeHandoverRef(opts.handoverFrom);
     if (!record.title && opts.title)
@@ -613,14 +583,7 @@ export function ensureSessionWorkspace(opts) {
     saveSessionRecord(workdir, record);
     return { sessionId: record.sessionId, workspacePath: record.workspacePath, record };
 }
-// ---------------------------------------------------------------------------
-// Record to SessionInfo
-// ---------------------------------------------------------------------------
 export function managedRecordToSessionInfo(record) {
-    // Collapse pre-fix records that stored the canonical skill expansion as the
-    // title / lastQuestion / lastMessageText. New records get collapsed at write
-    // time in `prepareStreamOpts`; this read-time pass keeps existing sessions
-    // from showing the long instruction in the sidebar after the fix lands.
     const title = collapseSkillPrompt(record.title) ?? record.title;
     const lastQuestion = collapseSkillPrompt(record.lastQuestion) ?? record.lastQuestion;
     const lastMessageText = collapseSkillPrompt(record.lastMessageText) ?? record.lastMessageText;
@@ -654,10 +617,6 @@ export function managedRecordToSessionInfo(record) {
         handoverFrom: record.handoverFrom ?? null,
     };
 }
-// ---------------------------------------------------------------------------
-// Public session queries
-// ---------------------------------------------------------------------------
-// Exported for drivers
 export function listPikiloomSessions(workdir, agent, limit) {
     const records = sortByUpdatedAtDesc(loadSessionIndex(path.resolve(workdir)).sessions.filter(entry => entry.agent === agent));
     return typeof limit === 'number' ? records.slice(0, limit) : records;
@@ -665,22 +624,6 @@ export function listPikiloomSessions(workdir, agent, limit) {
 export function findPikiloomSession(workdir, agent, sessionId) {
     return listPikiloomSessions(workdir, agent).find(entry => entry.sessionId === sessionId) || null;
 }
-/**
- * Delete a pikiloom-managed session. Two scopes:
- *   - default: drop the index entry + recursively delete the per-session dir
- *     under `<workdir>/.pikiloom/sessions/<agent>/<sessionId>/` (and the legacy
- *     `workspaces/` path). Native agent transcript is left in place so the
- *     user can still resume the conversation outside pikiloom.
- *   - `purgeNative: true`: also call the driver's `deleteNativeSession` to
- *     remove the underlying jsonl/rollout file.
- *
- * Refuses to delete a session whose record is currently marked running and
- * not stale (active process or recent mtime) — caller should stop the
- * stream first.
- *
- * Sessions that exist only in the agent's native store (no pikiloom record)
- * are still purgeable when `purgeNative` is set.
- */
 export async function deleteAgentSession(opts) {
     const resolvedWorkdir = path.resolve(opts.workdir);
     const { agent, sessionId } = opts;
@@ -700,7 +643,8 @@ export async function deleteAgentSession(opts) {
     }
     if (record) {
         index.sessions.splice(recordIdx, 1);
-        writeSessionIndex(resolvedWorkdir, index.sessions);
+        const prunedPromotions = prunePromotionsForDeletedSession(index.promotions, agent, sessionId);
+        writeSessionIndex(resolvedWorkdir, index.sessions, prunedPromotions ?? undefined);
         result.recordRemoved = true;
     }
     for (const dir of [sessionDirPath(resolvedWorkdir, agent, sessionId), legacySessionWorkspacePath(resolvedWorkdir, agent, sessionId)]) {
@@ -729,11 +673,6 @@ export async function deleteAgentSession(opts) {
     result.ok = true;
     return result;
 }
-/**
- * Look up the persisted model, thinkingEffort, and bound profileId for an
- * existing session. Returns null values when the session is not found or
- * fields are not set.
- */
 export function getSessionStoredConfig(workdir, agent, sessionId) {
     const record = findPikiloomSession(workdir, agent, sessionId);
     return {
@@ -780,7 +719,6 @@ export function stageSessionFiles(opts) {
     const importedFiles = importFilesIntoWorkspace(session.workspacePath, opts.files);
     if (importedFiles.length) {
         session.record.stagedFiles = dedupeStrings([...session.record.stagedFiles, ...importedFiles]);
-        /* title will be set when the first text prompt arrives */
         saveSessionRecord(opts.workdir, session.record);
     }
     return {
@@ -791,9 +729,6 @@ export function stageSessionFiles(opts) {
         handoverFrom: session.record.handoverFrom ?? null,
     };
 }
-// ---------------------------------------------------------------------------
-// Merge managed and native sessions
-// ---------------------------------------------------------------------------
 function sessionTimelineAt(session) {
     const ts = Date.parse(session.runUpdatedAt || session.createdAt || '');
     return Number.isFinite(ts) ? ts : Number.NEGATIVE_INFINITY;
@@ -836,13 +771,6 @@ export function mergeManagedAndNativeSessions(managedSessions, nativeSessions) {
             runUpdatedAt: useNativeTimeline ? (native.runUpdatedAt ?? managed.runUpdatedAt) : (managed.runUpdatedAt ?? native.runUpdatedAt),
             title: native.title || managed.title,
             model: native.model || managed.model,
-            // Pikiloom-owned metadata: the native session file (Claude JSONL etc.)
-            // carries none of these, so the `...native` spread would clobber them with
-            // `undefined`/`null`. The managed record (our centralized index) is the
-            // source of truth — recover each like `model` above. Without this the list
-            // silently drops the user's per-session choices: effort/Workflow fold back
-            // to the global default (per-send `ultra` → `max` after the turn) and the
-            // BYOK Profile binding is lost on resume.
             thinkingEffort: managed.thinkingEffort ?? native.thinkingEffort ?? null,
             workflowEnabled: managed.workflowEnabled ?? native.workflowEnabled ?? null,
             profileId: managed.profileId ?? native.profileId ?? null,
@@ -873,9 +801,6 @@ export function mergeManagedAndNativeSessions(managedSessions, nativeSessions) {
     merged.sort((a, b) => Date.parse(b.createdAt || '') - Date.parse(a.createdAt || ''));
     return merged;
 }
-// ---------------------------------------------------------------------------
-// getSessions / getSessionTail / getSessionMessages
-// ---------------------------------------------------------------------------
 export function getSessions(opts) {
     const workdir = path.resolve(opts.workdir);
     agentLog(`[sessions] request agent=${opts.agent} workdir=${workdir} limit=${opts.limit ?? 'all'}`);
@@ -890,15 +815,11 @@ export function getSessionTail(opts) {
 export function getSessionMessages(opts) {
     return getDriver(opts.agent).getSessionMessages(opts);
 }
-// ---------------------------------------------------------------------------
-// Turn windowing
-// ---------------------------------------------------------------------------
 function normalizeTurnWindowValue(value, fallback) {
     if (!Number.isFinite(value) || value == null)
         return fallback;
     return Math.max(0, Math.floor(value));
 }
-/** Slice messages by turn window and count total turns. Exported for drivers. */
 export function applyTurnWindow(allMsgs, opts = {}, richMsgs) {
     let totalTurns = 0;
     const turnStartIndexes = [];
@@ -908,8 +829,6 @@ export function applyTurnWindow(allMsgs, opts = {}, richMsgs) {
             totalTurns++;
         }
     }
-    // If no rich messages provided, synthesize from plain messages so the
-    // API always returns a consistent richMessages array.
     const rich = richMsgs ?? allMsgs.map(m => ({ role: m.role, text: m.text, blocks: [{ type: 'text', content: m.text }] }));
     if (totalTurns <= 0) {
         return {
@@ -976,13 +895,9 @@ export function applyTurnWindow(allMsgs, opts = {}, richMsgs) {
         error: null,
     };
 }
-/** Filter messages to last N turns and count total turns. Exported for drivers. */
 export function applyTurnFilter(allMsgs, lastNTurns, richMsgs) {
     return applyTurnWindow(allMsgs, { lastNTurns }, richMsgs);
 }
-// ---------------------------------------------------------------------------
-// Session classification
-// ---------------------------------------------------------------------------
 const PROPOSAL_PATTERNS = /方案|option[s ]?[A-C]|plan|approach|建议|recommend|alternatively|trade-?off|pros?\s+(and|&)\s+cons?|选择|比较/i;
 const IMPLEMENTATION_PATTERNS = /已完成|committed|done|implemented|fixed|created|wrote|修复|完成|写入|提交|applied|updated|modified|refactored/i;
 const BLOCKED_PATTERNS = /error|failed|permission denied|cannot|无法|失败|报错|blocked|timed?\s*out/i;
@@ -991,7 +906,6 @@ export function classifySession(result) {
     const message = result.message || '';
     const firstLine = message.split('\n').find(l => l.trim())?.trim() || '';
     const summaryText = firstLine.length > 120 ? firstLine.slice(0, 117) + '...' : firstLine;
-    // 1. Structural signals from StreamResult
     if (result.incomplete) {
         return {
             outcome: 'partial',
@@ -1009,7 +923,6 @@ export function classifySession(result) {
             classifiedAt: now,
         };
     }
-    // 2. Activity signals (tool use indicates implementation)
     const activity = result.activity || '';
     if (/\b(Edit|Write|Bash)\b/.test(activity)) {
         return {
@@ -1019,7 +932,6 @@ export function classifySession(result) {
             classifiedAt: now,
         };
     }
-    // 3. Content-based classification
     if (BLOCKED_PATTERNS.test(message.slice(0, 500))) {
         return {
             outcome: 'blocked',
@@ -1044,7 +956,6 @@ export function classifySession(result) {
             classifiedAt: now,
         };
     }
-    // 4. Default: informational answer
     return {
         outcome: 'answer',
         suggestedNextAction: null,
@@ -1052,7 +963,6 @@ export function classifySession(result) {
         classifiedAt: now,
     };
 }
-/** Derive a default userStatus from classification outcome */
 export function deriveUserStatus(outcome) {
     switch (outcome) {
         case 'answer': return 'done';
@@ -1060,14 +970,8 @@ export function deriveUserStatus(outcome) {
         default: return 'review';
     }
 }
-// ---------------------------------------------------------------------------
-// Session export/import
-// ---------------------------------------------------------------------------
 export async function exportSession(opts) {
     try {
-        // Rich mode so we can include image blocks in the export. The session
-        // pipeline always returns plain messages even when rich is set; rich is
-        // additive.
         const result = await getSessionMessages({ ...opts, agent: opts.agent, rich: true });
         if (!result.ok)
             return { ok: false, content: '', filename: '', error: result.error };
@@ -1078,8 +982,6 @@ export async function exportSession(opts) {
         let ext;
         switch (opts.format) {
             case 'json': {
-                // Materialize image bytes into inline data URLs so the JSON is a
-                // self-contained artefact (no dangling filesystem references).
                 const { materializeImage } = await import('./images.js');
                 const enrichedRichMessages = richMessages?.map(message => ({
                     ...message,
@@ -1122,16 +1024,9 @@ export async function exportSession(opts) {
         return { ok: false, content: '', filename: '', error: e.message };
     }
 }
-/**
- * Render an export-friendly markdown view. Each turn renders the role header,
- * the text body, and (for image blocks) an inlined `![caption](data:…)` ref
- * so the markdown is self-contained and renders correctly in any viewer
- * (VSCode preview, GitHub, etc.) without external file lookups.
- */
 async function renderMarkdownExport(agent, timestamp, messages, richMessages) {
     const lines = [`# Session Export (${agent}, ${timestamp})`, ''];
     const { materializeImage } = await import('./images.js');
-    // Walk by index so we can pair messages[i] with richMessages[i] when present.
     const indexed = richMessages?.length === messages.length ? richMessages : null;
     const sections = [];
     for (let i = 0; i < messages.length; i++) {
@@ -1197,11 +1092,6 @@ function parseMarkdownConversation(content) {
     for (const section of sections) {
         const firstLine = section.split('\n')[0].trim().toLowerCase();
         const role = firstLine.includes('user') ? 'user' : 'assistant';
-        // Strip inlined image data URLs (`![alt](data:image/...;base64,...)`) so
-        // the imported text body stays readable. The base64 payload itself isn't
-        // re-attached as a MessageBlock because the import API returns plain
-        // TailMessages; downstream agents that re-process the export will see the
-        // alt text "[image: alt]" placeholder where the markdown image stood.
         const stripped = section
             .split('\n')
             .slice(1)