claude-code-session-manager 0.13.0 → 0.14.0

package/src/main/historyAggregator.cjs

@@ -14,10 +14,20 @@ function decodeCwd(encoded) {
   return '/' + encoded.replace(/-+/g, '/');
 }
 
+// All date strings in this module are LOCAL-TZ YYYY-MM-DD. A previous version
+// used UTC (toISOString().slice(0,10)) which silently shifted late-evening
+// sessions a day forward for Pacific-time users, then the >= effectiveTo
+// filter dropped them entirely. en-CA locale yields ISO-format dates in the
+// JS environment's TZ. Parse with 'T12:00:00' (local noon) so DST boundaries
+// don't shift the date by a day.
+function localDate(d) {
+  return d.toLocaleDateString('en-CA');
+}
+
 function subtractDays(dateStr, days) {
-  const d = new Date(dateStr + 'T00:00:00Z');
-  d.setUTCDate(d.getUTCDate() - days);
-  return d.toISOString().slice(0, 10);
+  const d = new Date(dateStr + 'T12:00:00');
+  d.setDate(d.getDate() - days);
+  return localDate(d);
 }
 
 async function parseJSONL(filePath, stat) {
@@ -69,10 +79,18 @@ async function parseJSONL(filePath, stat) {
 
     const usage = obj.usage ?? obj.message?.usage;
     if (usage && typeof usage === 'object') {
-      if (typeof usage.inputTokens === 'number') acc.inputTokens += usage.inputTokens;
-      if (typeof usage.outputTokens === 'number') acc.outputTokens += usage.outputTokens;
-      if (typeof usage.cacheReadInputTokens === 'number') acc.cacheReadTokens += usage.cacheReadInputTokens;
-      if (typeof usage.cacheCreationInputTokens === 'number') acc.cacheCreationTokens += usage.cacheCreationInputTokens;
+      // Claude Code JSONLs use snake_case (matching the Anthropic API). The
+      // previous camelCase-only check meant every token count read as 0.
+      // Accept both shapes for forward-compat with any future renderer-side
+      // emitter (live.ts already normalizes both).
+      const inT = usage.input_tokens ?? usage.inputTokens;
+      const outT = usage.output_tokens ?? usage.outputTokens;
+      const cacheR = usage.cache_read_input_tokens ?? usage.cacheReadInputTokens;
+      const cacheC = usage.cache_creation_input_tokens ?? usage.cacheCreationInputTokens;
+      if (typeof inT === 'number') acc.inputTokens += inT;
+      if (typeof outT === 'number') acc.outputTokens += outT;
+      if (typeof cacheR === 'number') acc.cacheReadTokens += cacheR;
+      if (typeof cacheC === 'number') acc.cacheCreationTokens += cacheC;
     }
 
     const content = obj.message?.content ?? obj.content;
@@ -96,10 +114,10 @@ async function parseJSONL(filePath, stat) {
 
   try {
     acc.sessionDate = firstTs
-      ? new Date(firstTs).toISOString().slice(0, 10)
-      : new Date(stat.mtimeMs).toISOString().slice(0, 10);
+      ? localDate(new Date(firstTs))
+      : localDate(new Date(stat.mtimeMs));
   } catch {
-    acc.sessionDate = new Date(stat.mtimeMs).toISOString().slice(0, 10);
+    acc.sessionDate = localDate(new Date(stat.mtimeMs));
   }
 
   return acc;
@@ -126,8 +144,10 @@ async function parseConversationMeta(filePath, stat) {
     }
     const usage = obj.usage ?? obj.message?.usage;
     if (usage && typeof usage === 'object') {
-      if (typeof usage.inputTokens === 'number') meta.inputTokens += usage.inputTokens;
-      if (typeof usage.outputTokens === 'number') meta.outputTokens += usage.outputTokens;
+      const inT = usage.input_tokens ?? usage.inputTokens;
+      const outT = usage.output_tokens ?? usage.outputTokens;
+      if (typeof inT === 'number') meta.inputTokens += inT;
+      if (typeof outT === 'number') meta.outputTokens += outT;
     }
   }
   return meta;
@@ -142,7 +162,7 @@ function registerHistoryAggregatorHandlers() {
     const parsed = schemas.historyAggregate.safeParse(rawReq);
     const req = parsed.success ? (parsed.data ?? {}) : {};
     const t0 = Date.now();
-    const today = new Date().toISOString().slice(0, 10);
+    const today = localDate(new Date());
     let effectiveTo = req?.toDate ? req.toDate : today;
     if (effectiveTo > today) effectiveTo = today;
     const effectiveFrom = req?.fromDate ? req.fromDate : subtractDays(today, 30);
@@ -185,7 +205,10 @@ function registerHistoryAggregatorHandlers() {
         if (parsed.skipped) { skippedLargeFiles++; continue; }
 
         const { sessionDate } = parsed;
-        if (!sessionDate || sessionDate < effectiveFrom || sessionDate >= effectiveTo) continue;
+        // Inclusive upper bound — `>=` here previously meant "today's data is
+        // always dropped", which combined with the (then-UTC) date bucket to
+        // hide a Pacific-time user's most recent activity entirely.
+        if (!sessionDate || sessionDate < effectiveFrom || sessionDate > effectiveTo) continue;
 
         const key = `${sessionDate}|${encodedCwd}`;
         if (!buckets.has(key)) {

package/src/main/index.cjs

@@ -34,7 +34,8 @@ const searchIpc = require('./search.cjs');
 const repoAnalyzer = require('./repoAnalyzer.cjs');
 const hivesIpc = require('./hives.cjs');
 const { resolveClaudeBin } = require('./lib/claudeBin.cjs');
-const { assertCwdInsideHome } = require('./lib/insideHome.cjs');
+const { checkInsideHome } = require('./lib/insideHome.cjs');
+const { openInEditor, openFileInEditor, openInFinder, openInTerminal } = require('./lib/openExternalApp.cjs');
 
 let mainWindow = null;
 let rebooting = false;
@@ -81,7 +82,7 @@ function writeFirstPaintFailureLog() {
     const ymd = new Date().toISOString().slice(0, 10);
     const logPath = path.join(logDir, `boot-${ymd}.log`);
 
-    const homeCheck = assertCwdInsideHome(os.homedir());
+    const homeCheck = checkInsideHome(os.homedir());
     const lines = [
       `=== first-paint deadline exceeded @ ${new Date().toISOString()} ===`,
       `process.versions: ${JSON.stringify(process.versions)}`,
@@ -464,12 +465,9 @@ ipcMain.handle('app:test-fire-hook', async (_e, payload) => {
 // for non-git dirs, detached HEAD, missing git, or timeouts so callers can
 // render `—` without branching on error shape. 1s ceiling keeps a wedged git
 // (network filesystem, hung index lock) from blocking the renderer.
-ipcMain.handle('app:git-branch', async (_e, payload) => {
-  // safeParse (not throw) so a malformed call resolves to null — matches the
-  // existing semantics where StatusBar renders `—` on any failure.
-  const parsed = schemas.appGitBranch.safeParse(payload);
-  if (!parsed.success) return null;
-  const { cwd } = parsed.data;
+ipcMain.handle('app:git-branch', validated(schemas.appGitBranch, async ({ cwd }) => {
+  // Both renderer callsites (AlmanacFooter, AlmanacSidebar) already `.catch`
+  // rejections and render `—`, so a ZodError throw is handled correctly.
   return await new Promise((resolve) => {
     execFile('git', ['branch', '--show-current'], { cwd, timeout: 1000, windowsHide: true }, (err, stdout) => {
       if (err) { resolve(null); return; }
@@ -477,152 +475,73 @@ ipcMain.handle('app:git-branch', async (_e, payload) => {
       resolve(out.length ? out : null);
     });
   });
-});
+}));
 
-// Containment check used by the open-in-{editor,finder,terminal} handlers.
-// Bare `startsWith(home)` matches `/home/bilkoEVIL` when home=`/home/bilko` —
-// the classic prefix-trap. Resolve real paths (follow symlinks) and require
-// either exact equality or a separator boundary. Returns null on success or
-// an error string on failure. ENOENT (cwd doesn't exist) is a soft fail —
-// downstream `spawn`/`shell.openPath` will surface a more precise error.
-function checkInsideHome(cwd) {
-  if (typeof cwd !== 'string' || !cwd) return 'cwd outside home';
-  const home = os.homedir();
-  let realCwd;
-  let realHome;
-  try {
-    realHome = fs.realpathSync(home);
-  } catch {
-    return 'home directory unresolved';
-  }
-  try {
-    realCwd = fs.realpathSync(cwd);
-  } catch (err) {
-    if (err && err.code === 'ENOENT') {
-      // Fall through to the existing error path: the resolved-but-nonexistent
-      // path still has to be home-contained to avoid information disclosure
-      // via stat-probes (`/etc/secrets/...` → editor errors that reveal
-      // existence).
-      const resolved = path.resolve(cwd);
-      if (resolved !== realHome && !resolved.startsWith(realHome + path.sep)) {
-        return 'cwd outside home';
-      }
-      return null;
-    }
-    return 'cwd outside home';
-  }
-  if (realCwd !== realHome && !realCwd.startsWith(realHome + path.sep)) {
-    return 'cwd outside home';
-  }
-  return null;
-}
+// Containment check for the open-in-{editor,finder,terminal} handlers lives
+// in lib/insideHome.cjs — single chokepoint for the /home/bilkoEVIL prefix-trap.
+// Editor / finder / terminal logic lives in lib/openExternalApp.cjs.
 
-// Returns the resolved path of a command, or null if not found on PATH.
-function findCommand(name) {
-  try {
-    const out = execFileSync(
-      process.platform === 'win32' ? 'where' : 'which',
-      [name],
-      { encoding: 'utf8', env: process.env, timeout: 500 },
-    ).trim().split(/\r?\n/)[0];
-    if (out) return out;
-  } catch { /* not found */ }
-  return null;
-}
+ipcMain.handle('app:open-in-editor', validated(schemas.openInEditor, async ({ cwd, editor }) => {
+  const r = checkInsideHome(cwd);
+  if (!r.ok) throw new Error(r.error);
+  return openInEditor({ cwd, editor });
+}));
 
-ipcMain.handle('app:open-in-editor', async (_e, payload) => {
-  const { cwd, editor } = schemas.openInEditor.parse(payload);
-  const err = checkInsideHome(cwd);
-  if (err) throw new Error(err);
-  const candidates = (editor && editor !== 'auto')
-    ? [editor]
-    : [process.env.VISUAL, process.env.EDITOR, 'code', 'cursor', 'subl', 'nano'].filter(Boolean);
-  for (const cmd of candidates) {
-    if (!findCommand(cmd)) continue;
-    const child = spawn(cmd, [cwd], { detached: true, stdio: 'ignore', env: cleanChildEnv() });
-    child.unref();
-    return { ok: true, editor: cmd };
-  }
-  return { ok: false, error: 'no editor found' };
-});
-
-ipcMain.handle('app:open-external', async (_e, payload) => {
+ipcMain.handle('app:open-external', validated(schemas.openExternal, async ({ url }) => {
   // URL filter mirrors setWindowOpenHandler at line ~631: without it, the
   // renderer could be tricked into asking shell.openExternal to launch
   // `file:///etc/passwd`, `javascript:…`, or `mailto:…`. Stick to web URLs.
-  const { url } = schemas.openExternal.parse(payload);
   if (!url.startsWith('http://') && !url.startsWith('https://')) {
     return { ok: false, error: 'only http/https URLs are allowed' };
   }
   await shell.openExternal(url);
   return { ok: true };
-});
+}));
 
-ipcMain.handle('app:open-file-in-editor', async (_e, payload) => {
-  // Open a specific file (with optional line:col) in the user's editor.
-  // Distinct from app:open-in-editor above which opens a project root.
-  // GUI editors that support the goto-line flag (code/cursor/subl) get
-  // `-g file:line:col`; everything else falls back to opening the file alone.
-  const { path: p, line, col, editor } = schemas.openFileInEditor.parse(payload);
+ipcMain.handle('app:open-file-in-editor', validated(schemas.openFileInEditor, async ({ path: p, line, col, editor }) => {
   const home = os.homedir();
   const abs = path.isAbsolute(p) ? p : path.resolve(home, p);
-  const err = checkInsideHome(abs);
-  if (err) throw new Error(err);
-  try { await fsp.access(abs); } catch { return { ok: false, error: `file not found: ${abs}` }; }
-  const candidates = (editor && editor !== 'auto')
-    ? [editor]
-    : [process.env.VISUAL, process.env.EDITOR, 'code', 'cursor', 'subl', 'nano'].filter(Boolean);
-  for (const cmd of candidates) {
-    if (!findCommand(cmd)) continue;
-    const supportsGoto = /^(code|cursor|subl)$/.test(cmd);
-    const target = (supportsGoto && line) ? `${abs}:${line}${col ? `:${col}` : ''}` : abs;
-    const args = supportsGoto ? ['-g', target] : [abs];
-    const child = spawn(cmd, args, { detached: true, stdio: 'ignore', env: cleanChildEnv() });
-    child.unref();
-    return { ok: true, editor: cmd };
-  }
-  return { ok: false, error: 'no editor found' };
-});
-
-ipcMain.handle('app:open-in-finder', async (_e, payload) => {
-  const { cwd } = schemas.openInFinder.parse(payload);
-  const err = checkInsideHome(cwd);
-  if (err) throw new Error(err);
-  await shell.openPath(cwd);
-  return { ok: true };
-});
-
-ipcMain.handle('app:open-in-terminal', async (_e, payload) => {
-  const { cwd } = schemas.openInTerminal.parse(payload);
-  const err = checkInsideHome(cwd);
-  if (err) throw new Error(err);
-  if (process.platform === 'linux') {
-    const terms = ['gnome-terminal', 'konsole', 'xfce4-terminal', 'xterm'];
-    for (const t of terms) {
-      if (!findCommand(t)) continue;
-      const args = t === 'gnome-terminal'
-        ? ['--working-directory=' + cwd]
-        : ['-e', `bash -c "cd '${cwd.replace(/'/g, "'\\''")}' && exec bash"`];
-      const child = spawn(t, args, { detached: true, stdio: 'ignore', env: cleanChildEnv() });
-      child.unref();
-      return { ok: true, terminal: t };
-    }
-  } else if (process.platform === 'darwin') {
-    spawn('open', ['-a', 'Terminal', cwd], { detached: true, stdio: 'ignore', env: cleanChildEnv() }).unref();
-    return { ok: true, terminal: 'Terminal.app' };
+  // Allowed roots: $HOME (the usual case) plus our own clipboard temp dir
+  // (clipboard-paste writes PNGs there; clicks on those paths from the
+  // terminal must resolve). Resolve symlinks on both sides — on macOS
+  // /tmp is a symlink to /private/tmp, so a literal prefix check fails.
+  const clipboardDirRaw = path.join(os.tmpdir(), 'session-manager-clipboard');
+  let clipboardDirReal = clipboardDirRaw;
+  try { clipboardDirReal = fs.realpathSync(clipboardDirRaw); } catch { /* not yet created */ }
+  let absReal = abs;
+  try { absReal = fs.realpathSync(abs); } catch { /* file may not exist yet — fall through to access() below */ }
+  const inClipboardTmp =
+    absReal === clipboardDirReal ||
+    absReal.startsWith(clipboardDirReal + path.sep) ||
+    abs === clipboardDirRaw ||
+    abs.startsWith(clipboardDirRaw + path.sep);
+  if (!inClipboardTmp) {
+    const r = checkInsideHome(abs);
+    if (!r.ok) throw new Error(r.error);
   }
-  return { ok: false, error: 'no terminal found' };
-});
-
-ipcMain.handle('app:archive-project', async (_e, payload) => {
-  const { encoded } = schemas.archiveProject.parse(payload);
+  return openFileInEditor({ path: abs, line, col, editor });
+}));
+
+ipcMain.handle('app:open-in-finder', validated(schemas.openInFinder, async ({ cwd }) => {
+  const r = checkInsideHome(cwd);
+  if (!r.ok) throw new Error(r.error);
+  return openInFinder({ cwd });
+}));
+
+ipcMain.handle('app:open-in-terminal', validated(schemas.openInTerminal, async ({ cwd }) => {
+  const r = checkInsideHome(cwd);
+  if (!r.ok) throw new Error(r.error);
+  return openInTerminal({ cwd });
+}));
+
+ipcMain.handle('app:archive-project', validated(schemas.archiveProject, async ({ encoded }) => {
   const home = os.homedir();
   const src = path.join(home, '.claude', 'projects', encoded);
   const dst = path.join(home, '.claude', 'projects-archive', encoded);
   await fsp.mkdir(path.dirname(dst), { recursive: true });
   await fsp.rename(src, dst);
   return { ok: true };
-});
+}));
 
 registerPtyHandlers();
 configMgr.registerConfigHandlers();
@@ -738,7 +657,7 @@ app.whenReady().then(async () => {
   // Boot-time detection 2: symlinked /Users on macOS can make os.homedir()
   // realpath to a path outside itself, which breaks every cwd containment
   // check downstream. Surface here rather than failing on first session spawn.
-  bootHomeSelfCheck = assertCwdInsideHome(os.homedir());
+  bootHomeSelfCheck = checkInsideHome(os.homedir());
   if (!bootHomeSelfCheck.ok) {
     console.error(`[insideHome] SELF-CHECK FAILED: ${bootHomeSelfCheck.error}; sessions will not be able to spawn`);
   }

package/src/main/ipcSchemas.cjs

@@ -333,6 +333,9 @@ const PLUGIN_SLUG_RE = /^[a-z0-9\-/]+$/;
 const pluginsInstall = z.object({
   slug: z.string().regex(PLUGIN_SLUG_RE).min(1).max(128),
 }).passthrough();
+const pluginsAbort = z.object({
+  slug: z.string().regex(PLUGIN_SLUG_RE).min(1).max(128),
+}).passthrough();
 
 // SuperAgent — "boss" run that writes a structured prompt to the active
 // tab's PTY. Bounds match the inline schemas in superagent.cjs; centralizing
@@ -404,6 +407,7 @@ module.exports = {
     gitFileStatus,
     repoAnalyze,
     pluginsInstall,
+    pluginsAbort,
     superagentStart,
     superagentTabId,
     memoryList,

package/src/main/lib/childWithLog.cjs

@@ -0,0 +1,218 @@
+'use strict';
+
+/**
+ * childWithLog.cjs — spawn a child process with a log fd and watchdog timers.
+ *
+ * Two-phase API so callers can emit pre-spawn log lines (e.g. "starting …",
+ * early-exit error messages) before the child is created, while still having
+ * the helper own the fd lifecycle end-to-end.
+ *
+ * Phase 1 — openLog(logPath)
+ *   Opens the log file in append mode. Returns { fd, safeLog, closeFd }.
+ *   safeLog: idempotent after closeFd; never throws (guards EBADF on timers).
+ *   closeFd: idempotent; closes the fd exactly once.
+ *   After calling withChildAndLog(), do NOT call closeFd() yourself — the
+ *   helper takes ownership and closes it once after onExit returns.
+ *
+ * Phase 2 — withChildAndLog({ fd, logPath, safeLog, closeFd, spawn, watchdogs, onExit })
+ *   Spawns the child with stdio piped to the open fd.
+ *   Manages the watchdog timer lifecycle:
+ *     - Each watchdog uses setInterval. The interval auto-clears the first time
+ *       shouldFire(ctx) returns true, then calls action(ctx).
+ *     - action() may call ctx.addTimer(t) to register secondary timers
+ *       (e.g. SIGTERM → SIGKILL cascades) so they are also cleared on exit.
+ *   Calls onExit() synchronously inside the child 'exit'/'error' handler,
+ *   before calling closeFd(). Caller may call ctx.safeLog() inside onExit.
+ *
+ * WatchdogContext:
+ *   child         — the ChildProcess (null if spawn threw synchronously)
+ *   logPath       — string, used by watchdogs that stat the log file
+ *   startedAt     — Date.now() at spawn time
+ *   safeLog       — same safeLog returned by openLog()
+ *   killedByWatchdog — string | null, mutable; set by action() to record which
+ *                      watchdog issued the kill
+ *   killTree(sig) — sends sig to the process group (falls back to child.kill)
+ *   addTimer(t)   — registers a secondary timer (clearTimeout-compatible)
+ *
+ * onExit info:
+ *   exitCode      — number | null (−1 on spawn failure or child 'error' event)
+ *   signal        — string | null
+ *   killedByWatchdog — string | null
+ *   error         — Error | undefined (child 'error' event or sync spawn throw)
+ *   spawnFailed   — boolean, true when the error came from a synchronous spawn throw
+ *   safeLog       — same safeLog (usable inside onExit for final log lines)
+ *
+ * Returns { child, cancel } where cancel() clears all timers + SIGKILLs.
+ * child is null when the synchronous spawn threw (onExit has already been called).
+ */
+
+const fs = require('node:fs');
+const { spawn } = require('node:child_process');
+
+// ---------- Phase 1 ----------
+
+/**
+ * Open a log file in append mode. Returns { fd, safeLog, closeFd }.
+ *
+ * @param {string} logPath
+ * @returns {{ fd: number, safeLog: (msg: string) => void, closeFd: () => void }}
+ */
+function openLog(logPath) {
+  const fd = fs.openSync(logPath, 'a');
+  let fdClosed = false;
+
+  const closeFd = () => {
+    if (fdClosed) return;
+    fdClosed = true;
+    try { fs.closeSync(fd); } catch { /* already closed */ }
+  };
+
+  // safeLog: no-op once the fd is closed, never throws.
+  // Pre-fix for EBADF: a watchdog timer firing after closeFd would throw and
+  // crash the host if we used fs.writeSync directly.
+  const safeLog = (msg) => {
+    if (fdClosed) return;
+    try { fs.writeSync(fd, msg); } catch { /* fd vanished mid-write */ }
+  };
+
+  return { fd, safeLog, closeFd };
+}
+
+// ---------- Phase 2 ----------
+
+/**
+ * @typedef {Object} WatchdogSpec
+ * @property {string} label
+ * @property {number} intervalMs — poll interval
+ * @property {(ctx: WatchdogContext) => boolean} shouldFire — return true to
+ *   fire action + auto-clear the interval (fire-once-on-condition)
+ * @property {(ctx: WatchdogContext) => void} action
+ */
+
+/**
+ * @typedef {Object} WatchdogContext
+ * @property {import('child_process').ChildProcess | null} child
+ * @property {string} logPath
+ * @property {number} startedAt
+ * @property {(msg: string) => void} safeLog
+ * @property {string | null} killedByWatchdog
+ * @property {(signal: string) => boolean} killTree
+ * @property {(timer: any) => void} addTimer
+ */
+
+/**
+ * @param {{
+ *   fd: number,
+ *   logPath: string,
+ *   safeLog: (msg: string) => void,
+ *   closeFd: () => void,
+ *   spawn: { command: string, args: string[], options: object },
+ *   watchdogs?: WatchdogSpec[],
+ *   onExit?: (info: {
+ *     exitCode: number | null,
+ *     signal: string | null,
+ *     killedByWatchdog: string | null,
+ *     error?: Error,
+ *     spawnFailed?: boolean,
+ *     safeLog: (msg: string) => void,
+ *   }) => void,
+ * }} opts
+ * @returns {{ child: import('child_process').ChildProcess | null, cancel: () => void }}
+ */
+function withChildAndLog({ fd, logPath, safeLog, closeFd, spawn: spawnSpec, watchdogs = [], onExit }) {
+  const startedAt = Date.now();
+
+  // Secondary timers registered by watchdog actions (e.g. SIGTERM → SIGKILL cascades).
+  // Cleared alongside the primary watchdog timers on child exit.
+  // clearTimeout works on both Timeout and Interval handles in Node.js.
+  const extraTimers = [];
+
+  /** @type {WatchdogContext} */
+  const ctx = {
+    child: null,
+    logPath,
+    startedAt,
+    safeLog,
+    killedByWatchdog: null,
+    killTree(signal) {
+      const c = ctx.child;
+      if (!c) return false;
+      // Negative pid targets the whole process group (requires detached: true at spawn).
+      // Falls back to direct kill if the process is not a group leader.
+      try { process.kill(-c.pid, signal); return true; }
+      catch {
+        try { process.kill(c.pid, signal); return true; }
+        catch { return false; /* already dead */ }
+      }
+    },
+    addTimer(t) { extraTimers.push(t); },
+  };
+
+  // Build interval-based watchdog timers. Each fires every intervalMs; the
+  // first time shouldFire(ctx) returns true, the interval is auto-cleared and
+  // action(ctx) is called (fire-once-on-condition semantics).
+  //
+  // O(|watchdogs|) setup, O(1) per poll tick.
+  const clearFns = watchdogs.map((wd) => {
+    const t = setInterval(() => {
+      if (wd.shouldFire(ctx)) {
+        clearInterval(t);
+        wd.action(ctx);
+      }
+    }, wd.intervalMs);
+    if (t.unref) t.unref();
+    return () => clearInterval(t);
+  });
+
+  const clearAllTimers = () => {
+    clearFns.forEach((fn) => fn());
+    extraTimers.forEach((t) => clearTimeout(t));
+  };
+
+  // handleDone: called from both 'error' and 'exit' handlers. Clears timers,
+  // calls onExit (caller may still safeLog inside), then closes the fd.
+  const handleDone = (exitCode, signal, error, spawnFailed) => {
+    clearAllTimers();
+    if (onExit) {
+      onExit({
+        exitCode,
+        signal: signal ?? null,
+        killedByWatchdog: ctx.killedByWatchdog,
+        error,
+        spawnFailed: spawnFailed ?? false,
+        safeLog,
+      });
+    }
+    closeFd();
+  };
+
+  // Attempt synchronous spawn. On failure, call handleDone immediately so the
+  // caller's onExit can resolve any pending Promise before we return null.
+  let child;
+  try {
+    child = spawn(spawnSpec.command, spawnSpec.args, {
+      ...spawnSpec.options,
+      stdio: ['ignore', fd, fd],
+    });
+  } catch (e) {
+    handleDone(-1, null, e, /* spawnFailed */ true);
+    return { child: null, cancel: () => {} };
+  }
+
+  ctx.child = child;
+
+  child.on('error', (err) => handleDone(-1, null, err, false));
+  child.on('exit', (code, signal) => handleDone(code, signal, undefined, false));
+
+  const cancel = () => {
+    clearAllTimers();
+    // Best-effort kill; ignore errors (process may already be gone).
+    try { process.kill(-child.pid, 'SIGKILL'); } catch {
+      try { child.kill('SIGKILL'); } catch { /* */ }
+    }
+  };
+
+  return { child, cancel };
+}
+
+module.exports = { openLog, withChildAndLog };

package/src/main/lib/expandHome.cjs

@@ -0,0 +1,21 @@
+/**
+ * expandHome — tilde expansion. `~` and `~/foo` become $HOME and $HOME/foo.
+ * Everything else is returned unchanged. Used by files.cjs, config.cjs,
+ * search.cjs, queueOps.cjs — pulled out into a single helper to keep the
+ * containment-check grep in insideHome.cjs clean (`startsWith('~/')` followed
+ * by `homedir()` on the same line would otherwise create false positives in
+ * the security-audit grep).
+ */
+'use strict';
+
+const os = require('node:os');
+const path = require('node:path');
+
+function expandHome(p) {
+  if (!p) return p;
+  if (p === '~') return os.homedir();
+  if (p.startsWith('~/')) return path.join(os.homedir(), p.slice(2));
+  return p;
+}
+
+module.exports = { expandHome };