pikiloom 0.4.15 → 0.4.17

package/dist/agent/artifacts.js

@@ -0,0 +1,160 @@
+/**
+ * artifacts.ts — delivered-artifact manifest (the single source of truth for
+ * "files the agent handed to the user during a session").
+ *
+ * When the agent calls `im_send_file`, the bot materializes the file into the
+ * session attachments dir and appends a record here. IM channels additionally
+ * push the bytes to their chat; the dashboard serves the materialized copy over
+ * HTTP and renders it. Recording is terminal-agnostic, so a session watched
+ * from BOTH a chat and the dashboard shows the same deliveries on either side,
+ * and they survive a page reload / workspace cleanup.
+ *
+ * The manifest lives next to the MCP-buffered image attachments
+ * (`sessionAttachmentsDir`), which is already an allowlist root for the
+ * dashboard attachment endpoint — so materialized artifacts are servable with
+ * no new trust boundary.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { sessionAttachmentsDir } from './images.js';
+import { agentWarn } from './utils.js';
+const PHOTO_EXTS = new Set(['.jpg', '.jpeg', '.png', '.gif', '.webp', '.svg']);
+const MIME_BY_EXT = {
+    '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.gif': 'image/gif',
+    '.webp': 'image/webp', '.svg': 'image/svg+xml',
+    '.pdf': 'application/pdf', '.txt': 'text/plain; charset=utf-8', '.md': 'text/markdown; charset=utf-8',
+    '.csv': 'text/csv; charset=utf-8', '.json': 'application/json', '.xml': 'application/xml',
+    '.html': 'text/html; charset=utf-8', '.zip': 'application/zip', '.gz': 'application/gzip',
+    '.tar': 'application/x-tar', '.mp4': 'video/mp4', '.mov': 'video/quicktime', '.webm': 'video/webm',
+    '.mp3': 'audio/mpeg', '.wav': 'audio/wav', '.log': 'text/plain; charset=utf-8',
+};
+/** Best-effort MIME for a delivered artifact; `application/octet-stream` when unknown. */
+export function mimeForArtifact(filePath) {
+    return MIME_BY_EXT[path.extname(filePath).toLowerCase()] || 'application/octet-stream';
+}
+function manifestPath(agent, sessionId) {
+    return path.join(sessionAttachmentsDir(agent, sessionId), 'delivered.jsonl');
+}
+function deliveredDir(agent, sessionId) {
+    return path.join(sessionAttachmentsDir(agent, sessionId), 'delivered');
+}
+function sanitizeName(name) {
+    return (name || 'file').replace(/[/\\\0]+/g, '_').replace(/^\.+/, '').slice(0, 200) || 'file';
+}
+/**
+ * Materialize `srcPath` into the session's delivered-artifacts dir so it is
+ * (a) servable by the dashboard attachment endpoint (the dir is an allowlist
+ * root) and (b) durable across workspace cleanup. Hardlinks when possible,
+ * falling back to a copy across filesystems. The on-disk name is stamped to
+ * avoid collisions; the pristine basename travels in the manifest.
+ */
+export function stageDeliveredArtifact(agent, sessionId, srcPath) {
+    const fileName = sanitizeName(path.basename(srcPath));
+    const stat = fs.statSync(srcPath);
+    const dir = deliveredDir(agent, sessionId);
+    fs.mkdirSync(dir, { recursive: true });
+    const stamp = Date.now().toString(36) + Math.random().toString(36).slice(2, 6);
+    const dest = path.join(dir, `${stamp}-${fileName}`);
+    try {
+        fs.linkSync(srcPath, dest);
+    }
+    catch {
+        fs.copyFileSync(srcPath, dest);
+    }
+    return { path: dest, fileName, fileSize: stat.size, fileMime: mimeForArtifact(fileName) };
+}
+/** Append a record to the session's delivered-artifact manifest. */
+export function recordDeliveredArtifact(agent, sessionId, entry) {
+    try {
+        const file = manifestPath(agent, sessionId);
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        fs.appendFileSync(file, JSON.stringify(entry) + '\n');
+    }
+    catch (e) {
+        agentWarn(`[artifacts] record failed: ${e?.message || e}`);
+    }
+}
+/**
+ * Materialize + record a delivered artifact in one step. Best-effort: returns
+ * the stored record (with the materialized path), or null on failure — delivery
+ * must never crash the stream.
+ */
+export function deliverArtifact(agent, sessionId, srcPath, opts) {
+    try {
+        const staged = stageDeliveredArtifact(agent, sessionId, srcPath);
+        const record = {
+            ts: Date.now(),
+            ...(opts.taskId ? { taskId: opts.taskId } : {}),
+            path: staged.path,
+            fileName: staged.fileName,
+            fileMime: staged.fileMime,
+            fileSize: staged.fileSize,
+            kind: opts.kind,
+            ...(opts.caption ? { caption: opts.caption } : {}),
+        };
+        recordDeliveredArtifact(agent, sessionId, record);
+        return record;
+    }
+    catch (e) {
+        agentWarn(`[artifacts] deliver failed for ${srcPath}: ${e?.message || e}`);
+        return null;
+    }
+}
+/** Read the delivered-artifact manifest for a session (tolerant of partial lines). */
+export function readDeliveredArtifacts(agent, sessionId) {
+    const file = manifestPath(agent, sessionId);
+    let raw;
+    try {
+        raw = fs.readFileSync(file, 'utf-8');
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const line of raw.split('\n')) {
+        const t = line.trim();
+        if (!t)
+            continue;
+        try {
+            const rec = JSON.parse(t);
+            if (rec && typeof rec.path === 'string' && rec.fileName)
+                out.push(rec);
+        }
+        catch { /* skip malformed line */ }
+    }
+    return out;
+}
+/**
+ * Project the delivered-artifact manifest into pre-transport MessageBlocks
+ * (content = `file://<abs>`). The dashboard read path rewrites these to
+ * attachment HTTP URLs via `rewriteAttachmentBlocksForTransport`. Records whose
+ * file no longer exists on disk are dropped.
+ */
+export function deliveredArtifactBlocks(agent, sessionId) {
+    const blocks = [];
+    for (const a of readDeliveredArtifacts(agent, sessionId)) {
+        if (!fs.existsSync(a.path))
+            continue;
+        if (a.kind === 'photo' && PHOTO_EXTS.has(path.extname(a.fileName).toLowerCase())) {
+            blocks.push({
+                type: 'image',
+                content: `file://${a.path}`,
+                imagePath: a.path,
+                imageMime: a.fileMime,
+                ...(a.caption ? { imageCaption: a.caption } : {}),
+            });
+        }
+        else {
+            blocks.push({
+                type: 'file',
+                content: `file://${a.path}`,
+                filePath: a.path,
+                fileMime: a.fileMime,
+                fileName: a.fileName,
+                fileSize: a.fileSize,
+                ...(a.caption ? { fileCaption: a.caption } : {}),
+            });
+        }
+    }
+    return blocks;
+}

package/dist/agent/images.js

@@ -1,10 +1,13 @@
 /**
- * images.ts — unified image pipeline for the agent layer.
+ * images.ts — unified image (and on-disk attachment) pipeline for the agent
+ * layer.
  *
  * Every driver produces image blocks through `attachAgentImage`, every IM
  * channel consumes them through `materializeImage`, and every dashboard
- * response routes large images through the attachment HTTP endpoint via
- * `rewriteImageBlocksForTransport`. The shape isolates *where the bytes live*
+ * response routes on-disk image/file blocks through the attachment HTTP
+ * endpoint via `rewriteAttachmentBlocksForTransport` (delivered non-image files
+ * — see agent/artifacts.ts — ride the same transport). The shape isolates
+ * *where the bytes live*
  * from *how a renderer wants to consume them*, so adding a new driver source
  * (Codex `image_generation_call`, Claude MCP `tool_result` image, Gemini Imagen,
  * future) or a new transport (a fourth IM channel, a CLI exporter, an OG-image
@@ -25,7 +28,7 @@
  *  - `content` always carries a directly-renderable reference: a `data:` URL
  *    for inline bytes, or an attachment HTTP URL for files on disk.
  *  - Below `INLINE_THRESHOLD_BYTES`, drivers may inline as `data:`. Above the
- *    threshold, `rewriteImageBlocksForTransport` substitutes a relative
+ *    threshold, `rewriteAttachmentBlocksForTransport` substitutes a relative
  *    `/api/sessions/:agent/:id/attachment?...` URL — keeps RichMessage
  *    payloads small even when a session has many large images.
  *  - IM channels prefer `imagePath` over decoding `content`, avoiding wasted
@@ -192,7 +195,7 @@ export function attachAgentImage(opts) {
     }
     else {
         // Sentinel: the transport layer rewrites this into an HTTP URL with the
-        // right session context. Renderers that bypass `rewriteImageBlocksForTransport`
+        // right session context. Renderers that bypass `rewriteAttachmentBlocksForTransport`
         // see a `file://` URL and can still resolve it via `materializeImage` since
         // `imagePath` is also populated.
         content = `file://${abs}`;
@@ -321,29 +324,53 @@ export function decodeAttachmentPathParam(value) {
     return Buffer.from(normalized, 'base64').toString('utf-8');
 }
 /**
- * Rewrite a block array for transport: any image block whose `content` is a
- * `file://` sentinel becomes an attachment HTTP URL, and any inline `data:`
- * URL above the threshold is also promoted to an HTTP URL (keeping the
- * RichMessage payload compact even when a session has many large images).
+ * Build the dashboard attachment URL that serves `absPath` for a given session.
+ * Single source for the `/api/sessions/:agent/:id/attachment?p=…` shape so the
+ * transport rewrite, live stream snapshots, and any future caller stay in sync.
+ * `downloadName` is carried as an opaque `&n=` hint the endpoint uses for the
+ * Content-Disposition filename (the pristine basename, not the on-disk one).
+ */
+export function attachmentUrl(agent, sessionId, absPath, opts = {}) {
+    const base = (opts.apiBase || '/api/sessions').replace(/\/+$/, '');
+    const encoded = encodePathForUrl(absPath);
+    const name = opts.downloadName ? `&n=${encodeURIComponent(opts.downloadName)}` : '';
+    return `${base}/${encodeURIComponent(agent)}/${encodeURIComponent(sessionId)}/attachment?p=${encoded}${name}`;
+}
+/**
+ * Rewrite a block array for transport. Image and file blocks whose `content`
+ * is a `file://` sentinel (or which carry an on-disk `imagePath`/`filePath`)
+ * become attachment HTTP URLs; inline `data:` image URLs are left untouched so
+ * the dashboard renders them directly. Keeps RichMessage payloads compact even
+ * when a session delivered many large artifacts.
  *
  * Pure: returns a new array; the input is not mutated.
  */
-export function rewriteImageBlocksForTransport(blocks, ctx) {
-    const base = (ctx.apiBase || '/api/sessions').replace(/\/+$/, '');
+export function rewriteAttachmentBlocksForTransport(blocks, ctx) {
     return blocks.map(block => {
-        if (block.type !== 'image')
-            return block;
-        const sourcePath = block.imagePath
-            || (block.content?.startsWith('file://') ? block.content.slice('file://'.length) : '');
-        if (!sourcePath)
-            return block;
-        // Inline content under the threshold: leave the data URL alone — the
-        // dashboard renders it directly, no extra request.
-        if (block.content?.startsWith('data:'))
-            return block;
-        const encoded = encodePathForUrl(sourcePath);
-        const url = `${base}/${encodeURIComponent(ctx.agent)}/${encodeURIComponent(ctx.sessionId)}/attachment?p=${encoded}`;
-        return { ...block, content: url, imagePath: sourcePath };
+        if (block.type === 'image') {
+            const sourcePath = block.imagePath
+                || (block.content?.startsWith('file://') ? block.content.slice('file://'.length) : '');
+            if (!sourcePath)
+                return block;
+            // Inline content under the threshold: leave the data URL alone — the
+            // dashboard renders it directly, no extra request.
+            if (block.content?.startsWith('data:'))
+                return block;
+            const url = attachmentUrl(ctx.agent, ctx.sessionId, sourcePath, { apiBase: ctx.apiBase });
+            return { ...block, content: url, imagePath: sourcePath };
+        }
+        if (block.type === 'file') {
+            const sourcePath = block.filePath
+                || (block.content?.startsWith('file://') ? block.content.slice('file://'.length) : '');
+            if (!sourcePath)
+                return block;
+            const url = attachmentUrl(ctx.agent, ctx.sessionId, sourcePath, {
+                apiBase: ctx.apiBase,
+                downloadName: block.fileName || undefined,
+            });
+            return { ...block, content: url, filePath: sourcePath };
+        }
+        return block;
     });
 }
 // ---------------------------------------------------------------------------

package/dist/agent/index.js

@@ -18,8 +18,10 @@ import './drivers/codex.js';
 import './drivers/gemini.js';
 import './drivers/hermes.js';
 export { IMAGE_EXTS } from './types.js';
-// ── Re-export: image pipeline ──────────────────────────────────────────────
-export { attachAgentImage, attachInlineImage, materializeImage, rewriteImageBlocksForTransport, resolveAllowedAttachmentPath, allowedAttachmentRoots, decodeAttachmentPathParam, sessionAttachmentsDir, codexHome, } from './images.js';
+// ── Re-export: attachment pipeline (images + delivered files) ───────────────
+export { attachAgentImage, attachInlineImage, materializeImage, rewriteAttachmentBlocksForTransport, attachmentUrl, resolveAllowedAttachmentPath, allowedAttachmentRoots, decodeAttachmentPathParam, sessionAttachmentsDir, codexHome, } from './images.js';
+// ── Re-export: delivered-artifact manifest ──────────────────────────────────
+export { deliverArtifact, readDeliveredArtifacts, deliveredArtifactBlocks, mimeForArtifact, } from './artifacts.js';
 // ── Re-export: utilities ────────────────────────────────────────────────────
 export { Q, agentLog, agentWarn, agentError, dedupeStrings, numberOrNull, normalizeStreamPreviewPlan, parseTodoWriteAsPlan, normalizeActivityLine, pushRecentActivity, detectClaudeApiError, isRetryableClaudeApiError, detectClaudeModelError, claudeModelErrorMessage, firstNonEmptyLine, shortValue, normalizeErrorMessage, joinErrorMessages, appendSystemPrompt, mimeForExt, computeContext, buildStreamPreviewMeta, summarizeClaudeToolUse, summarizeClaudeToolResult, previewToolCallInput, previewToolCallResult, roundPercent, toIsoFromEpochSeconds, normalizeUsageStatus, labelFromWindowMinutes, usageWindowFromRateLimit, parseJsonTail, modelFamily, normalizeClaudeModelId, emptyUsage, readTailLines, stripInjectedPrompts, sanitizeSessionUserPreviewText, SESSION_PREVIEW_IMAGE_PLACEHOLDER_RE, CLAUDE_AT_MENTION_IMAGE_RE, extractClaudeAtMentionImagePaths, stripClaudeAtMentionImages, isPendingSessionId, emitSessionIdUpdate, sessionListDisplayTitle, } from './utils.js';
 // ── Re-export: session management ───────────────────────────────────────────

package/dist/agent/mcp/bridge.js

@@ -110,6 +110,58 @@ export const PEEKABOO_MCP_ARGV = ['-y', '-p', PEEKABOO_NPX_PACKAGE, 'peekaboo-mc
  */
 export const PEEKABOO_WARM_ARGV = ['-y', '-p', PEEKABOO_NPX_PACKAGE, 'peekaboo', '--version'];
 let peekabooWarmStarted = false;
+const PEEKABOO_ENV_ALLOWLIST = [
+    'HOME',
+    'PATH',
+    'USER',
+    'LOGNAME',
+    'SHELL',
+    'TMPDIR',
+    'TEMP',
+    'TMP',
+    'LANG',
+    'LC_ALL',
+    'LC_CTYPE',
+];
+const PEEKABOO_DEFAULT_PATH = '/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin';
+function cleanEnvString(value) {
+    if (typeof value !== 'string')
+        return null;
+    const trimmed = value.trim();
+    if (!trimmed || trimmed.includes('\0'))
+        return null;
+    return trimmed;
+}
+/**
+ * Peekaboo only needs a normal user shell environment so npx can resolve/cache
+ * the package. Do not inherit the full pikiloom/agent environment here: it may
+ * contain provider API keys, channel tokens, OAuth bearer values, or database
+ * URLs that a GUI MCP server has no reason to see.
+ */
+export function buildPeekabooChildEnv(env = process.env) {
+    const safe = {};
+    for (const key of PEEKABOO_ENV_ALLOWLIST) {
+        const value = cleanEnvString(env[key]);
+        if (value)
+            safe[key] = value;
+    }
+    safe.PATH ||= PEEKABOO_DEFAULT_PATH;
+    safe.HOME ||= os.homedir();
+    safe.PIKILOOM_MCP_SERVER = 'peekaboo';
+    safe.npm_config_yes = 'true';
+    return safe;
+}
+function peekabooEnvArgs(env) {
+    return Object.entries(env).map(([key, value]) => `${key}=${value}`);
+}
+function buildPeekabooMcpServer() {
+    const safeEnv = buildPeekabooChildEnv();
+    return {
+        name: 'peekaboo',
+        command: '/usr/bin/env',
+        args: ['-i', ...peekabooEnvArgs(safeEnv), 'npx', ...PEEKABOO_MCP_ARGV],
+    };
+}
 /**
  * Pre-warm the Peekaboo npx package so the agent's MCP server connects instantly.
  *
@@ -132,7 +184,11 @@ export function ensurePeekabooWarm() {
         return;
     peekabooWarmStarted = true;
     try {
-        const child = spawn('npx', PEEKABOO_WARM_ARGV, { stdio: 'ignore', detached: true });
+        const child = spawn('npx', PEEKABOO_WARM_ARGV, {
+            stdio: 'ignore',
+            detached: true,
+            env: buildPeekabooChildEnv(),
+        });
         // npx missing / spawn failure: clear the latch so a later call can retry.
         child.on('error', () => { peekabooWarmStarted = false; });
         child.unref();
@@ -159,11 +215,7 @@ export function buildSupplementalMcpServers(gui = resolveGuiIntegrationConfig(),
     if (gui.peekabooEnabled && process.platform === 'darwin') {
         // Peekaboo — native macOS GUI automation via Accessibility + ScreenCaptureKit.
         // Run the dedicated MCP bin from the multi-bin @steipete/peekaboo package.
-        servers.push({
-            name: 'peekaboo',
-            command: 'npx',
-            args: [...PEEKABOO_MCP_ARGV],
-        });
+        servers.push(buildPeekabooMcpServer());
     }
     return servers;
 }
@@ -235,6 +287,33 @@ function codexBearerEnvName(serverName) {
     const safe = serverName.toUpperCase().replace(/[^A-Z0-9]+/g, '_').replace(/^_+|_+$/g, '');
     return `PIKILOOM_MCP_BEARER_${safe || 'UNNAMED'}`;
 }
+const REDACTED = '[REDACTED]';
+const SENSITIVE_CONFIG_KEY_RE = /(authorization|bearer|token|secret|password|passwd|api[_-]?key|credential|cookie|session|connection[_-]?string|dsn)/i;
+const URL_PASSWORD_RE = /([a-z][a-z0-9+.-]*:\/\/)([^/\s:@]+):([^@\s/]+)@/gi;
+const QUERY_SECRET_RE = /([?&](?:access_token|api[_-]?key|key|token|secret|password|passwd)=)[^&\s]+/gi;
+function redactStringForLog(key, value) {
+    if (SENSITIVE_CONFIG_KEY_RE.test(key)) {
+        const bearer = /^\s*Bearer\s+/i.test(value);
+        return bearer ? `Bearer ${REDACTED}` : REDACTED;
+    }
+    return value
+        .replace(URL_PASSWORD_RE, `$1$2:${REDACTED}@`)
+        .replace(QUERY_SECRET_RE, `$1${REDACTED}`);
+}
+function redactForLog(value, key = '') {
+    if (typeof value === 'string')
+        return redactStringForLog(key, value);
+    if (Array.isArray(value))
+        return value.map(item => redactForLog(item, key));
+    if (!value || typeof value !== 'object')
+        return value;
+    return Object.fromEntries(Object.entries(value)
+        .map(([childKey, childValue]) => [childKey, redactForLog(childValue, childKey)]));
+}
+export function redactMcpConfigForLog(configPath) {
+    const parsed = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+    return JSON.stringify(redactForLog(parsed), null, 2);
+}
 export function buildGeminiMcpConfig(servers) {
     return {
         // Session attachments live under .pikiloom/... and should remain readable to
@@ -383,6 +462,116 @@ function reapStalePlaywrightMcpProcesses(cdpEndpoint) {
     }
     return { reaped, spared };
 }
+// ---------------------------------------------------------------------------
+// Stale peekaboo-mcp reaper
+// ---------------------------------------------------------------------------
+function commandTokenBase(token) {
+    return path.basename(token.replace(/^"+|"+$/g, '')).replace(/\.(?:cmd|exe)$/i, '').toLowerCase();
+}
+/**
+ * Pure matcher for stale-process hygiene. It intentionally targets the
+ * long-running MCP server only, not the quick cache warm (`peekaboo --version`).
+ */
+export function _matchPeekabooMcpProcessCommand(command) {
+    if (!command || !command.includes('peekaboo-mcp'))
+        return false;
+    const tokens = command.split(/\s+/).filter(Boolean);
+    if (!tokens.length)
+        return false;
+    if (commandTokenBase(tokens[0]) === 'node' && (tokens[1] === '-e' || tokens[1] === '--eval'))
+        return false;
+    const hasMcpBin = tokens.some(token => token === 'peekaboo-mcp'
+        || /(?:^|[\\/])peekaboo-mcp(?:$|\s)/.test(token)
+        || /(?:^|[\\/])peekaboo-mcp$/.test(token));
+    if (!hasMcpBin)
+        return false;
+    const hasPackage = command.includes('@steipete/peekaboo')
+        || command.includes('@steipete\\peekaboo')
+        || command.includes('/@steipete/peekaboo/');
+    const launcher = commandTokenBase(tokens[0]);
+    const knownLauncher = launcher === 'env' || launcher === 'npx' || launcher === 'npm' || launcher === 'node' || launcher === 'peekaboo-mcp';
+    return hasPackage || knownLauncher;
+}
+function commandLooksLikeLiveMcpController(command) {
+    if (!command)
+        return false;
+    const text = command.toLowerCase();
+    if (/\bpikiloom\b/.test(text) || text.includes('pikiloom@'))
+        return true;
+    const first = commandTokenBase(command.split(/\s+/)[0] || '');
+    return first === 'claude' || first === 'codex' || first === 'gemini' || first === 'hermes';
+}
+const PEEKABOO_REAP_THROTTLE_MS = 30_000;
+const PEEKABOO_REAP_FORCE_AFTER_MS = 2_000;
+let lastPeekabooReapAt = 0;
+function reapStalePeekabooMcpProcesses() {
+    const reaped = [];
+    const spared = [];
+    if (process.platform !== 'darwin')
+        return { reaped, spared };
+    if (Date.now() - lastPeekabooReapAt < PEEKABOO_REAP_THROTTLE_MS)
+        return { reaped, spared };
+    lastPeekabooReapAt = Date.now();
+    const result = spawnSync('ps', ['-axo', 'pid=,ppid=,command='], { encoding: 'utf8' });
+    if (result.status !== 0)
+        return { reaped, spared };
+    const ppidByPid = new Map();
+    const commandByPid = new Map();
+    const candidates = [];
+    const lines = String(result.stdout || '').split(/\r?\n/).map(l => l.trim()).filter(Boolean);
+    for (const line of lines) {
+        const m = line.match(/^(\d+)\s+(\d+)\s+(.*)$/);
+        if (!m)
+            continue;
+        const pid = Number(m[1]);
+        const ppid = Number(m[2]);
+        if (!Number.isFinite(pid) || !Number.isFinite(ppid))
+            continue;
+        const command = m[3] || '';
+        ppidByPid.set(pid, ppid);
+        commandByPid.set(pid, command);
+        if (pid === process.pid)
+            continue;
+        if (_matchPeekabooMcpProcessCommand(command))
+            candidates.push(pid);
+    }
+    const hasProtectedAncestor = (pid) => {
+        let cur = pid;
+        for (let depth = 0; depth < 40 && cur != null && cur > 1; depth++) {
+            if (cur === process.pid)
+                return true;
+            const command = commandByPid.get(cur) || '';
+            if (cur !== pid && commandLooksLikeLiveMcpController(command))
+                return true;
+            cur = ppidByPid.get(cur);
+        }
+        return false;
+    };
+    for (const pid of candidates) {
+        if (hasProtectedAncestor(pid)) {
+            spared.push(pid);
+            continue;
+        }
+        try {
+            process.kill(pid, 'SIGTERM');
+            const forceTimer = setTimeout(() => {
+                try {
+                    process.kill(pid, 0);
+                    process.kill(pid, 'SIGKILL');
+                }
+                catch {
+                    // Process already exited or cannot be signalled — no-op.
+                }
+            }, PEEKABOO_REAP_FORCE_AFTER_MS);
+            forceTimer.unref?.();
+            reaped.push(pid);
+        }
+        catch {
+            // Already dead — no-op.
+        }
+    }
+    return { reaped, spared };
+}
 /**
  * Decide which CDP endpoint the per-session playwright/mcp should attach to.
  *
@@ -514,8 +703,13 @@ export async function startMcpBridge(opts) {
     // Peekaboo ships a native binary behind npx; warm its cache out-of-band so the
     // agent's MCP server connects instantly instead of hanging at "Still
     // connecting" on a cold first-run download (see ensurePeekabooWarm).
-    if (gui.peekabooEnabled)
+    if (gui.peekabooEnabled) {
         ensurePeekabooWarm();
+        const { reaped, spared } = reapStalePeekabooMcpProcesses();
+        if (reaped.length) {
+            opts.onLog?.(`reaped ${reaped.length} stale peekaboo-mcp process(es): pid=${reaped.join(',')}${spared.length ? ` (spared active: ${spared.join(',')})` : ''}`);
+        }
+    }
     // Lazy browser lifecycle: probe an already-running managed Chrome via
     // <profileDir>/DevToolsActivePort and attach if reachable; otherwise leave
     // Chrome unlaunched and let playwright/mcp launch it with `--user-data-dir`

package/dist/agent/mcp/extensions.js

@@ -17,6 +17,7 @@ import os from 'node:os';
 import path from 'node:path';
 import { spawn } from 'node:child_process';
 import { loadUserConfig, saveUserConfig } from '../../core/config/user-config.js';
+import { terminateProcessTree } from '../../core/process-control.js';
 import { getRecommendedMcpServers, } from './registry.js';
 import { hasValidMcpToken, injectOAuthHeaders } from './oauth.js';
 // ---------------------------------------------------------------------------
@@ -548,6 +549,7 @@ export async function checkMcpHealth(config, timeoutMs = 10_000) {
     return new Promise((resolve) => {
         const start = Date.now();
         let checkInterval = null;
+        let settled = false;
         const cleanup = () => {
             if (checkInterval) {
                 clearInterval(checkInterval);
@@ -555,20 +557,29 @@ export async function checkMcpHealth(config, timeoutMs = 10_000) {
             }
             clearTimeout(timer);
         };
+        const stopChildTree = () => {
+            terminateProcessTree(child, { signal: 'SIGTERM', forceSignal: 'SIGKILL', forceAfterMs: 1500 });
+        };
+        const finish = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            resolve(result);
+        };
         const child = spawn(config.command, config.args || [], {
             stdio: ['pipe', 'pipe', 'pipe'],
             env: { ...process.env, ...config.env },
+            detached: process.platform !== 'win32',
         });
         const timer = setTimeout(() => {
-            cleanup();
-            child.kill();
-            resolve({ ok: false, error: `timeout after ${timeoutMs}ms`, elapsedMs: Date.now() - start });
+            stopChildTree();
+            finish({ ok: false, error: `timeout after ${timeoutMs}ms`, elapsedMs: Date.now() - start });
         }, timeoutMs);
         let stdout = '';
         child.stdout?.on('data', (data) => { stdout += data.toString(); });
         child.on('error', (err) => {
-            cleanup();
-            resolve({ ok: false, error: err.message, elapsedMs: Date.now() - start });
+            finish({ ok: false, error: err.message, elapsedMs: Date.now() - start });
         });
         const initRequest = JSON.stringify({
             jsonrpc: '2.0',
@@ -585,8 +596,8 @@ export async function checkMcpHealth(config, timeoutMs = 10_000) {
             child.stdin?.write(header + initRequest);
         }
         catch {
-            cleanup();
-            resolve({ ok: false, error: 'failed to write to stdin', elapsedMs: Date.now() - start });
+            stopChildTree();
+            finish({ ok: false, error: 'failed to write to stdin', elapsedMs: Date.now() - start });
             return;
         }
         checkInterval = setInterval(() => {
@@ -606,7 +617,7 @@ export async function checkMcpHealth(config, timeoutMs = 10_000) {
             }
             catch { /* best-effort */ }
             setTimeout(() => {
-                child.kill();
+                stopChildTree();
                 const tools = [];
                 try {
                     const jsonMatches = stdout.match(/\{[^{}]*"tools"\s*:\s*\[[\s\S]*?\]\s*[^{}]*\}/g);
@@ -630,7 +641,7 @@ export async function checkMcpHealth(config, timeoutMs = 10_000) {
                     }
                 }
                 catch { /* best effort */ }
-                resolve({ ok: true, tools: tools.length ? tools : undefined, elapsedMs: Date.now() - start });
+                finish({ ok: true, tools: tools.length ? tools : undefined, elapsedMs: Date.now() - start });
             }, 1500);
         }, 100);
     });

package/dist/agent/mcp/tools/workspace.js

@@ -1,8 +1,9 @@
 /**
  * tools/workspace.ts — Workspace file tools.
  *
- *   workspace_list_files — returns workspace path, staged files, and directory listing
- *   workspace_send_file  — sends a file back to the IM chat
+ *   im_list_files — returns workspace path, staged files, and directory listing
+ *   im_send_file  — delivers a file to the user via the active terminal
+ *                   (IM chat push and/or the dashboard attachment endpoint)
  */
 import fs from 'node:fs';
 import path from 'node:path';
@@ -28,7 +29,7 @@ const tools = [
     },
     {
         name: 'im_send_file',
-        description: 'Send a file to the user in IM.',
+        description: 'Send a file to the user through the active terminal (IM chat or web dashboard). Use this to hand over screenshots, reports, archives, or generated assets — the file is delivered and stays retrievable even when the user is connected remotely. Prefer this over printing a local filesystem path, which a remote user cannot open.',
         inputSchema: {
             type: 'object',
             properties: {

package/dist/agent/stream.js

@@ -473,7 +473,7 @@ export async function doStream(opts) {
     // Start MCP bridge for IM tools (when sendFile is available) and/or supplemental servers (browser, etc.)
     let bridge = null;
     try {
-        const { startMcpBridge } = await import('./mcp/bridge.js');
+        const { startMcpBridge, redactMcpConfigForLog } = await import('./mcp/bridge.js');
         const sessionDir = path.dirname(session.workspacePath);
         bridge = await startMcpBridge({
             sessionDir,
@@ -498,7 +498,8 @@ export async function doStream(opts) {
             else
                 agentLog('[mcp] bridge registered with codex');
             try {
-                agentLog(`[mcp] config content:\n${fs.readFileSync(bridge.configPath, 'utf-8')}`);
+                if (bridge.configPath)
+                    agentLog(`[mcp] config content:\n${redactMcpConfigForLog(bridge.configPath)}`);
             }
             catch { }
             ;