pikiloom 0.4.26 → 0.4.27

package/dist/bot/session-hub.js

@@ -1,27 +1,7 @@
-/**
- * session-hub.ts — Unified session management service.
- *
- * THE canonical interface for all session operations across pikiloom.
- * Upper-layer code (bot, dashboard, CLI) should import session functions
- * from here, not from code-agent.ts directly.
- *
- * Responsibilities:
- *   - Cross-agent / workspace-scoped session queries
- *   - Session metadata management (status, notes, links, classification)
- *   - Migration, export/import orchestration
- *   - Workspace registry (delegates to user-config)
- */
 import path from 'node:path';
-import { getSessions as _getSessions, getSessionTail as _getSessionTail, getSessionMessages as _getSessionMessages, classifySession as _classifySession, deriveUserStatus as _deriveStatusFromOutcome, exportSession as _exportSession, importSession as _importSession, findPikiloomSession, updateSessionMeta, deleteAgentSession as _deleteAgentSession, collapseSkillPrompt, } from '../agent/index.js';
+import { getSessions as _getSessions, getSessionTail as _getSessionTail, getSessionMessages as _getSessionMessages, classifySession as _classifySession, deriveUserStatus as _deriveStatusFromOutcome, exportSession as _exportSession, importSession as _importSession, findPikiloomSession, updateSessionMeta, resolveCanonicalSessionId, getSessionPromotions, deleteAgentSession as _deleteAgentSession, collapseSkillPrompt, } from '../agent/index.js';
 import { allDriverIds, hasDriver } from '../agent/driver.js';
 import { loadWorkspaces, addWorkspace, removeWorkspace, renameWorkspace, reorderWorkspaces, updateWorkspace, findWorkspace, } from '../core/config/user-config.js';
-// ---------------------------------------------------------------------------
-// Resolve user status
-// ---------------------------------------------------------------------------
-/**
- * Compute the effective user status for a session.
- * Priority: explicit userStatus > derived from classification > inbox.
- */
 export function resolveUserStatus(session) {
     if (session.userStatus)
         return session.userStatus;
@@ -29,21 +9,12 @@ export function resolveUserStatus(session) {
         return _deriveStatusFromOutcome(session.classification.outcome);
     return 'inbox';
 }
-// ---------------------------------------------------------------------------
-// Unified session query
-// ---------------------------------------------------------------------------
 function normalizeAgents(agent) {
     if (!agent)
         return allDriverIds().filter(a => hasDriver(a));
     const list = Array.isArray(agent) ? agent : [agent];
     return list.filter(a => hasDriver(a));
 }
-/**
- * Query sessions — the single entry point for all session listing.
- *
- * Handles single-agent, multi-agent, and all-agent queries with optional
- * status filtering and limits. Returns workspace-enriched results.
- */
 export async function querySessions(opts) {
     const resolvedWorkdir = path.resolve(opts.workdir);
     const ws = findWorkspace(resolvedWorkdir);
@@ -64,22 +35,18 @@ export async function querySessions(opts) {
             allSessions.push({ ...session, workspaceName });
         }
     }
-    // Sort by most recent activity
     allSessions.sort((a, b) => {
         const aTime = a.runUpdatedAt || a.createdAt || '';
         const bTime = b.runUpdatedAt || b.createdAt || '';
         return Date.parse(bTime) - Date.parse(aTime);
     });
-    // Filter by userStatus
     if (opts.userStatus?.length) {
         const allowed = new Set(opts.userStatus);
         allSessions = allSessions.filter(s => allowed.has(resolveUserStatus(s)));
     }
-    // Apply limit
     if (opts.limit && opts.limit > 0) {
         allSessions = allSessions.slice(0, opts.limit);
     }
-    // Count statuses
     const statusCounts = { inbox: 0, active: 0, review: 0, done: 0, parked: 0, unknown: 0 };
     for (const s of allSessions) {
         const status = resolveUserStatus(s);
@@ -93,22 +60,14 @@ export async function querySessions(opts) {
         statusCounts: statusCounts,
         total: allSessions.length,
         errors,
+        promotions: getSessionPromotions(resolvedWorkdir),
     };
 }
-// ---------------------------------------------------------------------------
-// Session detail queries
-// ---------------------------------------------------------------------------
 const IMAGE_EXTENSIONS = new Set(['.png', '.jpg', '.jpeg', '.gif', '.webp', '.bmp', '.svg']);
 const MIME_BY_EXT = {
     '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg',
     '.gif': 'image/gif', '.webp': 'image/webp', '.bmp': 'image/bmp', '.svg': 'image/svg+xml',
 };
-/** Build image MessageBlocks from a session record's `lastUserAttachments`
- *  (relative paths under `workspacePath`). Used by fallback paths so the
- *  dashboard can still render the user's image bubble while the agent CLI
- *  has not yet flushed the turn to its own session file. Non-image
- *  attachments are skipped — the fallback is text-first and doesn't try to
- *  reconstruct generic file references. */
 function imageBlocksFromManagedRecord(record) {
     const attachments = record.lastUserAttachments;
     if (!attachments?.length)
@@ -121,8 +80,6 @@ function imageBlocksFromManagedRecord(record) {
         const abs = path.isAbsolute(rel) ? rel : path.join(record.workspacePath, rel);
         blocks.push({
             type: 'image',
-            // `file://` sentinel — `rewriteAttachmentBlocksForTransport` (dashboard
-            // response layer) converts it to a proper /attachment URL.
             content: `file://${abs}`,
             imagePath: abs,
             imageMime: MIME_BY_EXT[ext] || 'application/octet-stream',
@@ -166,23 +123,20 @@ function managedFallbackContent(opts) {
         return null;
     return { messages, richMessages };
 }
-/** Get recent messages from a session (tail). */
 export async function querySessionTail(opts) {
-    const result = await _getSessionTail(opts);
+    const opts2 = withCanonicalSessionId(opts);
+    const result = await _getSessionTail(opts2);
     if (!result.ok || !result.messages.length) {
-        const fallback = tailFallbackFromManagedRecord(opts);
+        const fallback = tailFallbackFromManagedRecord(opts2);
         if (fallback)
             return fallback;
     }
     return result;
 }
-/**
- * Replace canonical skill-execution expansions in a user message with the
- * `/skillname` shorthand the user originally typed. The expanded text is what
- * the agent CLI consumed and persisted; we collapse on read so the dashboard
- * chat shows the slash command instead of the long instruction we synthesized
- * for dispatch. Non-user messages and non-skill prompts pass through unchanged.
- */
+function withCanonicalSessionId(opts) {
+    const canonical = resolveCanonicalSessionId(opts.workdir, opts.agent, opts.sessionId);
+    return canonical === opts.sessionId ? opts : { ...opts, sessionId: canonical };
+}
 function collapseSkillPromptsInResult(result) {
     if (!result.ok)
         return result;
@@ -198,9 +152,6 @@ function collapseSkillPromptsInResult(result) {
         const collapsed = collapseSkillPrompt(m.text);
         if (!collapsed)
             return m;
-        // The user's text content lives in one or more `text` blocks; collapse any
-        // whose individual content also matches the expansion. Non-text blocks
-        // (images, attachments) pass through untouched.
         const blocks = m.blocks.map(b => {
             if (b.type !== 'text')
                 return b;
@@ -211,22 +162,20 @@ function collapseSkillPromptsInResult(result) {
     });
     return { ...result, messages, richMessages };
 }
-/** Get full session messages (with optional turn filtering). */
 export async function querySessionMessages(opts) {
-    const result = await _getSessionMessages(opts);
+    const opts2 = withCanonicalSessionId(opts);
+    const result = await _getSessionMessages(opts2);
     if (!result.ok || !result.messages.length) {
         const fb = managedFallbackContent({
-            agent: opts.agent,
-            sessionId: opts.sessionId,
-            workdir: opts.workdir,
+            agent: opts2.agent,
+            sessionId: opts2.sessionId,
+            workdir: opts2.workdir,
         });
         if (fb) {
             const totalTurns = fb.messages.filter(m => m.role === 'user').length;
             return collapseSkillPromptsInResult({
                 ok: true,
                 messages: fb.messages.map(m => ({ role: m.role, text: m.text })),
-                // Always emit richMessages so the dashboard can render image blocks
-                // for the first user turn while the agent CLI is still spinning up.
                 richMessages: fb.richMessages,
                 totalTurns,
                 error: null,
@@ -235,16 +184,10 @@ export async function querySessionMessages(opts) {
     }
     return collapseSkillPromptsInResult(result);
 }
-// ---------------------------------------------------------------------------
-// Workspace overviews
-// ---------------------------------------------------------------------------
-/** Overview of all registered workspaces — designed for dashboard sidebar. */
 export async function getWorkspaceOverviews() {
     const workspaces = loadWorkspaces();
     const agents = allDriverIds().filter(a => hasDriver(a));
     return Promise.all(workspaces.map(async (ws) => {
-        // Fan the agents out in parallel — each _getSessions is independent I/O, and
-        // running them serially made one slow agent stall the whole workspace card.
         const summaries = await Promise.all(agents.map(async (agent) => {
             try {
                 const result = await _getSessions({ agent, workdir: ws.path });
@@ -279,22 +222,12 @@ export async function getWorkspaceOverviews() {
         return { workspace: ws, attentionCount, agentSummary, lastActivityAt };
     }));
 }
-// ---------------------------------------------------------------------------
-// Session metadata
-// ---------------------------------------------------------------------------
-/** Update session metadata (status, note, classification, migration links). */
 export function updateSession(workdir, agent, sessionId, patch) {
     return updateSessionMeta(workdir, agent, sessionId, patch);
 }
-/**
- * Delete a session. Re-exports the agent-layer primitive so dashboard routes
- * stay in the bot/ layer for layering consistency. See
- * {@link DeleteAgentSessionOpts}.
- */
 export function deleteSession(opts) {
     return _deleteAgentSession(opts);
 }
-/** Link two sessions together (bidirectional). */
 export function linkSessions(workdir, a, b) {
     const updatedA = updateSessionMeta(workdir, a.agent, a.sessionId, {
         addLink: { agent: b.agent, sessionId: b.sessionId },
@@ -304,23 +237,15 @@ export function linkSessions(workdir, a, b) {
     });
     return updatedA || updatedB;
 }
-// ---------------------------------------------------------------------------
-// Classification
-// ---------------------------------------------------------------------------
-/** Auto-classify a session based on stream result. */
 export function classifySession(result) {
     return _classifySession(result);
 }
-// ---------------------------------------------------------------------------
-// Export / Import / Migration
-// ---------------------------------------------------------------------------
 export function exportSession(opts) {
     return _exportSession(opts);
 }
 export function importSession(opts) {
     return _importSession(opts);
 }
-/** Build migration context from source session for injection into target agent. */
 export async function buildMigrationContext(opts) {
     try {
         const messagesResult = await _getSessionMessages({
@@ -355,7 +280,4 @@ export async function buildMigrationContext(opts) {
         return { ok: false, contextInjected: '', messageCount: 0, error: e.message };
     }
 }
-// ---------------------------------------------------------------------------
-// Workspace registry (delegates to user-config)
-// ---------------------------------------------------------------------------
 export { loadWorkspaces, addWorkspace, removeWorkspace, renameWorkspace, reorderWorkspaces, updateWorkspace, findWorkspace };

package/dist/bot/session-status.js

@@ -1,9 +1,5 @@
-/**
- * Runtime session status helpers for dashboard polling.
- */
 import { isRunningSessionStale } from '../agent/index.js';
-/** Age threshold used when the owning PID is unknown or unverifiable. */
-const STALE_RUNNING_AGE_MS = 30 * 60_000; // 30 minutes
+const STALE_RUNNING_AGE_MS = 30 * 60_000;
 function getSessionRuntime(bot, session) {
     const sessionId = session.sessionId || null;
     if (!sessionId)

package/dist/bot/streaming.js

@@ -1,21 +1,3 @@
-/**
- * Stream preview parsing helpers for live message updates.
- *
- * Used by IM channels (Telegram / Feishu / WeChat). The dashboard reads the
- * raw `StreamSnapshot.activity` string directly and renders independently —
- * none of the compaction in this file flows to it. Keep changes that improve
- * IM legibility free to touch this surface; if a change would also alter what
- * the dashboard ultimately shows, do it in the dashboard layer instead.
- */
-/**
- * Shrink absolute paths that bloat IM cards on small screens. Any absolute
- * path with 4+ segments collapses to `…/<last-two-segments>` so directory
- * context is kept while the leading `/Users/…/long/project/root/` noise is
- * dropped. Length-based gating made the output inconsistent — borderline
- * paths (47 chars) sat next to compacted ones (52 chars), making the activity
- * list look broken. Relative paths and short paths (<4 segments, e.g.
- * `~/foo`, `/tmp/x.log`) are passed through unchanged.
- */
 function compactActivityPath(token) {
     if (!token.includes('/'))
         return token;
@@ -26,9 +8,6 @@ function compactActivityPath(token) {
     return `…/${tail}`;
 }
 function compactPathsInActivityLine(line) {
-    // Conservative: only target obviously absolute paths starting with `/` or
-    // `~/`. Inline file:line references (`foo/bar.ts:42`) keep their structure
-    // since the prefix is short anyway.
     return line.replace(/(^|\s)([~/][^\s]+)/g, (_match, lead, raw) => {
         const trailingPunct = raw.match(/[)\],.;!?]+$/)?.[0] ?? '';
         const path = trailingPunct ? raw.slice(0, -trailingPunct.length) : raw;
@@ -36,11 +15,6 @@ function compactPathsInActivityLine(line) {
     });
 }
 const TOOL_DONE_RE = /^(.+?)\s+(done|failed)$/;
-/** "X -> Y" pattern produced by `summarizeClaudeToolResult` for tools whose
- *  result has body text (im_ask_user, ToolSearch, MCP tools, …). The Y half
- *  is the tool's response — capturing it lets us collapse the pre-event
- *  (`Ask user: q`) and the post-event (`Ask user: q -> A: …`) into a single
- *  line in the narrative instead of leaving both sitting around. */
 const TOOL_ARROW_RE = /^(.+?)\s*->\s*(.+)$/;
 const INJECTED_PROMPT_MARKERS = [
     '\n[Session Workspace]',
@@ -96,10 +70,6 @@ export function parseActivitySummary(activity) {
     let activeCommands = 0;
     let completedCommands = 0;
     const activeClaudeShells = new Map();
-    // Track narrative indices keyed by their normalized start text so a later
-    // "X done" / "X failed" line collapses the prior "X" entry instead of
-    // appending. Avoids the double-line spam in IM cards where each tool call
-    // shows both its in-progress and completed line.
     const pendingNarrative = new Map();
     const pushPending = (key, index) => {
         const slot = pendingNarrative.get(key);
@@ -165,10 +135,6 @@ export function parseActivitySummary(activity) {
             failedCommands++;
             continue;
         }
-        // Pair "X" → "X done"/"X failed": rewrite the prior in-progress entry in
-        // place rather than appending a second line. Falls back to a plain append
-        // when no matching start exists (e.g. the start line was trimmed off by a
-        // history window earlier in the run).
         const doneMatch = line.match(TOOL_DONE_RE);
         if (doneMatch) {
             const baseKey = doneMatch[1].trim();
@@ -181,11 +147,6 @@ export function parseActivitySummary(activity) {
             narrative.push(status === 'failed' ? `${baseKey} failed` : baseKey);
             continue;
         }
-        // Pair "X" → "X -> Y" (im_ask_user, ToolSearch, MCP tools, … — any tool
-        // whose summarizeClaudeToolResult fell into the arrow branch). Without
-        // this, the IM card shows the question and the answered form side by
-        // side. We replace the pending entry with the full arrow form so the
-        // narrative carries the answer in a single line.
         const arrowMatch = line.match(TOOL_ARROW_RE);
         if (arrowMatch) {
             const baseKey = arrowMatch[1].trim();
@@ -203,14 +164,6 @@ export function parseActivitySummary(activity) {
     }
     return { narrative: collapseConsecutiveDuplicates(narrative), failedCommands, completedCommands, activeCommands };
 }
-/**
- * Walk the narrative and collapse runs of identical lines into `X ×N`. The
- * input narrative often contains repeats when the model calls the same tool
- * multiple times in a row (two consecutive `Edit README.md`, three `Read X`,
- * …) — listing them N times wastes IM card real estate without adding
- * information. Non-adjacent duplicates are preserved to keep the temporal
- * order intact.
- */
 function collapseConsecutiveDuplicates(narrative) {
     const out = [];
     let runStart = -1;
@@ -282,15 +235,9 @@ export function renderPlanForPreview(plan) {
     const total = plan.steps.length;
     const completed = plan.steps.filter(step => step.status === 'completed').length;
     const lines = [`Plan ${completed}/${total}`];
-    // Show the most recent / currently-active slice of the plan. Live viewers
-    // care about the in-progress + upcoming steps; the dozen already-completed
-    // ones at the top of the list are just visual ballast (the `completed/total`
-    // header already conveys the overall progress).
     const WINDOW = 4;
     let startIdx = 0;
     if (total > WINDOW) {
-        // Center the window on the in-progress step when one exists; otherwise
-        // anchor to the tail so the next pending steps are visible.
         const inProgressIdx = plan.steps.findIndex(step => step.status === 'inProgress');
         const anchor = inProgressIdx >= 0 ? inProgressIdx : total - 1;
         startIdx = Math.max(0, Math.min(total - WINDOW, anchor - Math.floor(WINDOW / 2)));

package/dist/browser-profile.js

@@ -1,6 +1,3 @@
-/**
- * Managed browser profile directory for Playwright integration.
- */
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
@@ -11,14 +8,6 @@ const MANAGED_BROWSER_SETUP_STATE_FILENAME = 'managed-browser-setup.json';
 const MANAGED_BROWSER_SHUTDOWN_TIMEOUT_MS = 5_000;
 const MANAGED_BROWSER_SHUTDOWN_POLL_MS = 100;
 const require = createRequire(import.meta.url);
-/**
- * Read Chrome's `DevToolsActivePort` file from the managed profile dir.
- * Chrome writes this file when launched with `--remote-debugging-port=<n>`
- * (including `=0`, which lets the OS assign a free port). Format is two lines:
- *   <port>
- *   /devtools/browser/<id>
- * We use it to discover the actual port rather than hard-coding one.
- */
 function readDevToolsActivePort(profileDir) {
     try {
         const raw = fs.readFileSync(path.join(profileDir, 'DevToolsActivePort'), 'utf8');
@@ -40,14 +29,6 @@ function normalizeBrowserCdpEndpoint(endpoint) {
         return '';
     return value.replace(/\/+$/, '');
 }
-/**
- * The external CDP endpoint configured via {@link PIKILOOM_BROWSER_CDP_URL_ENV},
- * normalized (trailing slashes stripped, blank → null). Single source of truth
- * for the remote-browser override: when this returns a value, every browser
- * codepath attaches to it and pikiloom never launches, probes, or kills a local
- * Chrome. Read from `env` (defaults to `process.env`) so callers can inject it
- * in tests.
- */
 export function getConfiguredRemoteCdpUrl(env = process.env) {
     const raw = String(env[PIKILOOM_BROWSER_CDP_URL_ENV] || '').trim();
     if (!raw)
@@ -162,16 +143,6 @@ export function ensureManagedBrowserProfileDir() {
 function getPlaywrightMcpConfigPath(outputDir) {
     return path.join(outputDir, 'playwright-mcp-config.json');
 }
-/**
- * Write the playwright/mcp config JSON used by every spawn. Currently it just
- * strips Playwright's default `--disable-blink-features=AutomationControlled`
- * arg so Chrome doesn't show its "unsupported command-line flag" infobar.
- * Playwright adds that flag to hide `navigator.webdriver`; removing it makes
- * the managed browser look like a normal session, which is what we want for
- * pikiloom's logged-in automation profile.
- *
- * Idempotent: rewrites only when the content drifts.
- */
 export function ensurePlaywrightMcpConfigFile(outputDir = path.dirname(getManagedBrowserProfileDir())) {
     const configPath = getPlaywrightMcpConfigPath(outputDir);
     const desired = JSON.stringify({
@@ -186,7 +157,6 @@ export function ensurePlaywrightMcpConfigFile(outputDir = path.dirname(getManage
             return configPath;
     }
     catch {
-        // File missing or unreadable — fall through to write.
     }
     fs.mkdirSync(outputDir, { recursive: true });
     fs.writeFileSync(configPath, desired, 'utf8');
@@ -240,9 +210,6 @@ export function getManagedBrowserLaunchArgs(profileDir = getManagedBrowserProfil
         : ['--start-maximized'];
     return [
         `--user-data-dir=${profileDir}`,
-        // `=0` makes Chrome pick a free port and write it to <profileDir>/DevToolsActivePort,
-        // which `readDevToolsActivePort` reads back. Hard-coding a port causes collisions
-        // when another Chrome / debugger is already on it.
         '--remote-debugging-port=0',
         '--no-first-run',
         '--no-default-browser-check',
@@ -427,19 +394,6 @@ async function waitForManagedBrowserCdpEndpoint(profileDir, timeoutMs = 6_000) {
     }
     return resolveManagedBrowserCdpEndpoint(profileDir);
 }
-/**
- * Hard-reset the managed browser: SIGKILL every root pid (skipping the SIGTERM
- * grace window) and wipe Chrome's session-restore files so the relaunch comes
- * up with a fresh `about:blank` instead of replaying the tabs that triggered
- * the failure. Used as the reactive recovery path when an agent stream sees an
- * MCP browser error (Connection closed / Frame has been detached) indicating
- * Chrome's CDP layer is wedged; a normal `closeManagedBrowserProcesses`
- * round-trip won't help because it would restore the same poisoned tabs.
- *
- * Trade-off: any unrelated user-opened tabs are dropped. Acceptable here
- * because this is invoked only after observing a real failure — the user has
- * already lost time, and recovery beats perpetuating the wedge.
- */
 export async function forceCloseManagedBrowser(profileDir = getManagedBrowserProfileDir()) {
     const tracked = readManagedBrowserSetupState(profileDir);
     const candidates = new Set(findManagedBrowserRootPids(profileDir));
@@ -487,11 +441,6 @@ async function closeManagedBrowserProcesses(profileDir) {
     return closedPids;
 }
 export async function prepareManagedBrowserForAutomation(profileDir = getManagedBrowserProfileDir(), options = {}) {
-    // CDP probe is the authoritative signal: if the managed Chrome answers on
-    // its debug port, attach to it regardless of what the setup-state file or
-    // the process table say. The ps-based running-state check is heuristic and
-    // can be wrong after a daemon restart, which would otherwise kill the
-    // user's live (and signed-in) browser.
     const reachableEndpoint = await resolveManagedBrowserCdpEndpoint(profileDir);
     if (reachableEndpoint) {
         return {

package/dist/browser-supervisor.js

@@ -1,20 +1,3 @@
-/**
- * Process-level singleton supervisor for the managed browser.
- *
- * Owns the lifecycle decisions for the managed Chrome instance so that all
- * agent streams in this pikiloom process share one browser. Replaces the old
- * per-stream `prepareManagedBrowserForAutomation` call inside the MCP bridge,
- * which was relaunching Chrome at the start of every task.
- *
- * Three operations:
- *   - probe(): non-launching health check; returns the current CDP endpoint
- *     iff a managed Chrome is already reachable.
- *   - ensure(): idempotent prepare with singleflight; launches Chrome only
- *     when no healthy instance is reachable. Caches the result for re-use
- *     across streams.
- *   - invalidate(): drop the cache after a confirmed downstream failure
- *     (e.g. CDP socket closed mid-stream).
- */
 import { forceCloseManagedBrowser, getConfiguredRemoteCdpUrl, getManagedBrowserProfileDir, prepareManagedBrowserForAutomation, } from './browser-profile.js';
 import { PIKILOOM_BROWSER_CDP_URL_ENV } from './core/constants.js';
 import { writeScopedLog } from './core/logging.js';
@@ -25,18 +8,7 @@ let inflight = null;
 function log(message, level = 'debug') {
     writeScopedLog('browser-supervisor', message, { level, stream: 'stderr' });
 }
-/**
- * The user-configured remote endpoint from {@link PIKILOOM_BROWSER_CDP_URL_ENV}.
- * When set, every supervisor codepath bypasses local Chrome launching. Aliased
- * to the shared `getConfiguredRemoteCdpUrl` so the bridge and supervisor read
- * the same normalized value.
- */
 const getRemoteCdpUrl = getConfiguredRemoteCdpUrl;
-/**
- * Snapshot for the remote-CDP path. The URL is taken on trust as configured —
- * health is verified by {@link pingCdpEndpoint} before caching, and by the
- * usual freshness check on every reuse.
- */
 async function snapshotRemote(remoteUrl, now) {
     if (cached?.cdpEndpoint === remoteUrl && now - cached.validatedAt < HEALTH_CACHE_MS) {
         return snapshotFromCache(cached);
@@ -69,21 +41,6 @@ async function fetchWithTimeout(url, timeoutMs) {
         clearTimeout(timer);
     }
 }
-/**
- * Two-stage health check.
- *
- * Stage 1 (`/json/version`) hits Chrome's static info handler — confirms the
- * process is alive and the debug HTTP server is bound. Stage 2 (`/json`) reads
- * from the target manager, exercising the CDP dispatch loop. Chrome can end up
- * in a state where stage 1 still answers but stage 2 hangs, typically after
- * many stale CDP sessions accumulate; treating stage-1-only responses as
- * healthy lets that state poison every subsequent agent run.
- *
- * Both stages share the same `CDP_PROBE_TIMEOUT_MS`. This probe does NOT catch
- * the case where stage 2 succeeds but the *first page target* is itself stuck
- * (e.g. a heavy SPA frozen mid-init); that has to be handled reactively from
- * the MCP-tool-error path.
- */
 async function pingCdpEndpoint(endpoint) {
     if (!endpoint)
         return false;
@@ -113,10 +70,6 @@ async function freshenCacheIfPossible(now) {
     cached = null;
     return null;
 }
-/**
- * Non-launching probe. Returns the current CDP endpoint iff a managed Chrome
- * is already reachable. Never starts a new Chrome process.
- */
 export async function probeManagedBrowser() {
     const remoteUrl = getRemoteCdpUrl();
     if (remoteUrl)
@@ -126,15 +79,6 @@ export async function probeManagedBrowser() {
         return fresh;
     return { cdpEndpoint: null, connectionMode: 'unavailable' };
 }
-/**
- * Idempotent prepare. Returns a healthy CDP endpoint, launching Chrome only
- * when no reachable managed instance is available. Concurrent callers share
- * one in-flight preparation promise (singleflight).
- *
- * When {@link PIKILOOM_BROWSER_CDP_URL_ENV} is set we skip the local-launch
- * branch entirely and just verify the remote endpoint — no `findChromeExecutable`
- * lookup, no SIGKILL of detected pids on restart.
- */
 export async function ensureManagedBrowser(opts = {}) {
     const { headless = false, force = false } = opts;
     const now = Date.now();
@@ -183,19 +127,6 @@ export async function ensureManagedBrowser(opts = {}) {
 const RESTART_COOLDOWN_MS = 30_000;
 let lastRestartAt = 0;
 let restartInflight = null;
-/**
- * Reactive recovery for a confirmed CDP-layer failure: drops the supervisor
- * cache, SIGKILLs Chrome, wipes session-restore. The next `ensureManagedBrowser`
- * will detect no CDP endpoint and relaunch Chrome cold.
- *
- * The current stream is not rescued — its MCP child has already lost stdio,
- * and Claude CLI's MCP client won't reconnect mid-tool-call. The benefit lands
- * on the next agent turn, which will attach to a fresh browser instead of
- * inheriting the wedged one.
- *
- * Cooldown-throttled and singleflight: a single agent run can spit many
- * "Connection closed" lines as the MCP child stays dead; we only act once.
- */
 export function restartManagedBrowser(reason) {
     const now = Date.now();
     if (restartInflight)
@@ -205,9 +136,6 @@ export function restartManagedBrowser(reason) {
         return Promise.resolve();
     }
     lastRestartAt = now;
-    // Remote CDP path: we don't own the Chrome process (it's a sidecar / external
-    // service), so don't SIGKILL anything — just drop the cache so the next
-    // ensure re-probes the endpoint.
     const remoteUrl = getRemoteCdpUrl();
     if (remoteUrl) {
         log(`invalidating remote CDP cache (${remoteUrl}): ${reason}`, 'warn');
@@ -230,17 +158,14 @@ export function restartManagedBrowser(reason) {
     })();
     return restartInflight;
 }
-/** Drop any cached endpoint, e.g. after a confirmed CDP failure mid-stream. */
 export function invalidateManagedBrowser() {
     if (cached)
         log(`invalidating cached endpoint ${cached.cdpEndpoint}`);
     cached = null;
 }
-/** Synchronous accessor for the cached endpoint without any I/O. */
 export function getCachedManagedBrowserEndpoint() {
     return cached?.cdpEndpoint || null;
 }
-/** Test-only: reset module state. */
 export function _resetManagedBrowserSupervisor() {
     cached = null;
     inflight = null;