claude-code-session-manager 0.13.1 → 0.15.0

package/src/main/index.cjs

@@ -9,6 +9,7 @@ const { cleanChildEnv } = require('./lib/cleanEnv.cjs');
 const { manager: ptyManager, registerPtyHandlers } = require('./pty.cjs');
 const configMgr = require('./config.cjs');
 const transcripts = require('./transcripts.cjs');
+const usageMatrix = require('./usageMatrix.cjs');
 const sessionsStore = require('./sessionsStore.cjs');
 const billing = require('./usage.cjs');
 const logs = require('./logs.cjs');
@@ -34,7 +35,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 +83,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)}`,
@@ -186,6 +188,7 @@ async function rebootApp() {
     ptyManager.attachWindow(mainWindow);
     configMgr.attachWindow(mainWindow);
     transcripts.attachWindow(mainWindow);
+    usageMatrix.attachWindow(mainWindow);
     voiceHotkey.init(mainWindow).catch((e) => {
       logs.writeLine({ scope: 'voice-hotkey', level: 'error', message: 'reinit failed', meta: { error: e?.message } });
     });
@@ -464,12 +467,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,156 +477,78 @@ 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();
 transcripts.registerTranscriptHandlers();
+usageMatrix.registerHandlers();
 sessionsStore.registerSessionsHandlers();
 billing.registerBillingHandlers();
 logs.registerLogHandlers();
@@ -738,7 +660,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`);
   }
@@ -858,6 +780,7 @@ app.whenReady().then(async () => {
   ptyManager.attachWindow(mainWindow);
   configMgr.attachWindow(mainWindow);
   transcripts.attachWindow(mainWindow);
+  usageMatrix.attachWindow(mainWindow);
   voiceHotkey.init(mainWindow).catch((e) => {
     logs.writeLine({ scope: 'voice-hotkey', level: 'error', message: 'init failed', meta: { error: e?.message } });
   });

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 };

package/src/main/lib/insideHome.cjs

@@ -1,16 +1,25 @@
 /**
- * insideHome.cjs — security invariant: every renderer-controlled cwd must
- * resolve (after realpath, symlink-safe) to a path inside the user's home
- * directory. Four call sites used to reimplement this: pty.cjs spawn,
- * watchers.cjs add, index.cjs checkInsideHome, ipcSchemas.cjs setConfigSchema
- * defaultCwd refine. The check is a single chokepoint here.
+ * insideHome.cjs — single chokepoint for "is this renderer-controlled path
+ * inside $HOME?" Security boundary: bare `startsWith(home)` matches
+ * `/home/bilkoEVIL` when home=`/home/bilko` (the classic prefix-trap). Both
+ * the target and the home directory are resolved via realpath, and the
+ * boundary is either exact equality or a path-separator boundary.
  *
- * Returns { ok: true, realCwd } on success or { ok: false, error } on rejection.
- * Realpath of the cwd is returned so callers can use it without recomputing.
+ * Two exports, two policies:
+ *   assertInsideHome(p) → { realPath }                — throws on failure
+ *   checkInsideHome(p)  → { ok, realPath } | { ok, error }  — never throws
  *
- * NOTE: schemas can't easily call this (zod refines are inline); they retain
- * a simpler `startsWith` check that does NOT symlink-resolve. The runtime
- * resolution here is the authoritative one — schemas are belt-and-suspenders.
+ * Both follow the same algorithm:
+ *   1. realpath the target. On ENOENT, fall back to path.resolve(p) so callers
+ *      can validate "this is where I'm about to write" before the file exists.
+ *   2. Compare against the cached realpath of os.homedir() with the
+ *      equality-or-separator boundary check.
+ *
+ * The cached home realpath is computed once at module load. If $HOME can't be
+ * resolved at startup we keep going with the literal value — boot-time
+ * self-check in index.cjs surfaces that to the user.
+ *
+ * Linux + darwin only. No Windows path handling.
  */
 'use strict';
 
@@ -18,21 +27,65 @@ const fs = require('node:fs');
 const path = require('node:path');
 const os = require('node:os');
 
-function assertCwdInsideHome(cwd) {
-  if (typeof cwd !== 'string' || !cwd) {
-    return { ok: false, error: 'cwd must be a non-empty string' };
+// Resolve home once. Falls back to literal homedir if realpath fails
+// (which would be a misconfigured system; boot self-check in index.cjs
+// surfaces it). Cached for the lifetime of the process — home doesn't
+// move under us at runtime.
+const HOME_LITERAL = os.homedir();
+let HOME_REAL;
+try {
+  HOME_REAL = fs.realpathSync(HOME_LITERAL);
+} catch {
+  HOME_REAL = HOME_LITERAL;
+}
+
+function resolveTarget(p) {
+  // realpath fails with ENOENT for paths that don't exist yet (writes,
+  // mkdir destinations). Fall through to lexical resolve so the containment
+  // check still applies — prevents info-disclosure via stat probes on
+  // /etc/secrets/... that would be rejected later but reveal existence first.
+  try {
+    return fs.realpathSync(p);
+  } catch (err) {
+    if (err && err.code === 'ENOENT') return path.resolve(p);
+    throw err;
+  }
+}
+
+function isContained(realPath) {
+  return realPath === HOME_REAL || realPath.startsWith(HOME_REAL + path.sep);
+}
+
+function assertInsideHome(p) {
+  if (typeof p !== 'string' || !p) {
+    throw new Error('path outside home');
+  }
+  let realPath;
+  try {
+    realPath = resolveTarget(p);
+  } catch {
+    throw new Error('path outside home');
+  }
+  if (!isContained(realPath)) {
+    throw new Error('path outside home');
+  }
+  return { realPath };
+}
+
+function checkInsideHome(p) {
+  if (typeof p !== 'string' || !p) {
+    return { ok: false, error: 'path outside home' };
   }
-  const home = os.homedir();
-  let realCwd;
+  let realPath;
   try {
-    realCwd = fs.realpathSync(cwd);
+    realPath = resolveTarget(p);
   } catch {
-    realCwd = path.resolve(cwd);
+    return { ok: false, error: 'path outside home' };
   }
-  if (realCwd !== home && !realCwd.startsWith(home + path.sep)) {
-    return { ok: false, error: `cwd outside home directory: ${realCwd}` };
+  if (!isContained(realPath)) {
+    return { ok: false, error: 'path outside home' };
   }
-  return { ok: true, realCwd };
+  return { ok: true, realPath };
 }
 
-module.exports = { assertCwdInsideHome };
+module.exports = { assertInsideHome, checkInsideHome };