claude-code-session-manager 0.86.0 → 0.88.0

package/src/main/lib/prdLocations.cjs

@@ -12,12 +12,22 @@
  * live. Active-project discovery reuses activeSessions.cjs's
  * activeProjectCwds (the same discovery watchdogHelpers.cjs's sweep() uses)
  * rather than re-implementing transcript scanning here.
+ *
+ * CACHING NOTE (PRD adding mtime-keyed memoization to this module): what's
+ * cached here is only WHICH DIRECTORIES EXIST, never their CONTENTS. A new
+ * PRD .md file dropped into an already-known `prds/` dir does not change
+ * that dir's own existence, so it needs no cache invalidation here at all —
+ * `schedule:rescan` (scheduler.cjs's `ipcMain.handle('schedule:rescan', …)`)
+ * still reports it because the actual file-listing happens one layer down,
+ * in scheduler/prdParser.cjs's `listPrdFiles(dir)`, which has its OWN
+ * separate mtime cache keyed on that specific dir's mtime (bumped by the new
+ * file) and is unaffected by anything cached in this module.
  */
 'use strict';
 
 const fs = require('node:fs');
 const path = require('node:path');
-const { activeProjectCwds, allProjectCwds } = require('../../../scripts/lib/activeSessions.cjs');
+const { activeProjectCwds, allProjectCwds } = require('./activeSessions.cjs');
 
 const { opsPath, OPS_ROOT_DIR } = require('./opsOwnership.cjs');
 
@@ -53,18 +63,49 @@ function resolveEpicPrdWriteDir(cwd, epicId) {
   return path.join(resolveEpicsRoot(cwd), epicId, 'prds');
 }
 
+// listEpicPrdDirs' readdir-the-Epics-root-plus-existsSync-per-subdir walk is
+// the expensive half of prdLocations' per-reconcile()-pass cost (159/166
+// dirs, ~430ms/~400ms measured). A new Epic's prds/ dir is always created in
+// the SAME recursive mkdirSync call that creates `epics/<newId>/` itself
+// (epicMint.cjs's ensureEpic, both the mint branch and the join branch's
+// belt-and-suspenders mkdirSync) — so a brand-new `epics/<id>/prds` dir
+// first coming into existence always bumps the Epics root's OWN mtime (a
+// new directory entry under it), never just an existing subdir's mtime.
+// Cache keyed on that mtime, same dir-mtime idiom as
+// scheduler/prdParser.cjs's dirCache — no TTL, so the very next call after a
+// mint sees the new dir with no wait.
+const epicPrdDirsCache = new Map(); // epicsRootPath -> { mtimeMs, result }
+
 /** Enumerate every existing `epics/<id>/prds` dir under one project cwd. */
 function listEpicPrdDirs(cwd) {
   let root;
   try { root = resolveEpicsRoot(cwd); } catch { return []; }
+  let mtimeMs;
+  try {
+    mtimeMs = fs.statSync(root).mtimeMs;
+  } catch {
+    // Missing/unreadable root: nothing to scan, and any prior cache entry
+    // must not survive to be handed back once the dir later appears.
+    epicPrdDirsCache.delete(root);
+    return [];
+  }
+  const cached = epicPrdDirsCache.get(root);
+  if (cached && cached.mtimeMs === mtimeMs) return cached.result;
+
   let entries;
-  try { entries = fs.readdirSync(root, { withFileTypes: true }); } catch { return []; }
+  try {
+    entries = fs.readdirSync(root, { withFileTypes: true });
+  } catch {
+    epicPrdDirsCache.delete(root);
+    return [];
+  }
   const dirs = [];
   for (const ent of entries) {
     if (!ent.isDirectory()) continue;
     const prdDir = path.join(root, ent.name, 'prds');
     if (fs.existsSync(prdDir)) dirs.push(prdDir);
   }
+  epicPrdDirsCache.set(root, { mtimeMs, result: dirs });
   return dirs;
 }
 
@@ -101,6 +142,85 @@ function resolvePrdWriteDir(cwd) {
   return opsPath(cwd, ...PRD_SUBPATH);
 }
 
+// resolvePrdsDirs/resolveArchivedPrdsDirs each redo a fs.existsSync(dir) +
+// listEpicPrdDirs(cwd) walk across EVERY project on every call, and
+// reconcile() calls each of them once per pass. Cache the assembled result
+// keyed on the caller's own (maxAgeMin, opts) tuple — a call with an
+// explicit `{ projectsDir }` opts object is a DIFFERENT key from the
+// no-opts default, so the two never read or write each other's entry — PLUS
+// a freshness key built from every visited project's Epics-root mtimeMs,
+// same composite-mtime-key idiom as queueHistory.cjs's historyCacheKey. The
+// freshness key is cheap to rebuild every call (one statSync per project,
+// far cheaper than the readdir+existsSync-per-Epic walk it guards), so a
+// cache hit still costs O(projects) stats but skips the expensive walk
+// entirely — "one filesystem walk" per reconcile() pass, not the full
+// listEpicPrdDirs cost N times over.
+//
+// The Epics-root mtime alone has a real blind spot: `prds-archived/` is
+// created (archiveCompletedPrd, scheduler.cjs) as a NEW entry INSIDE an
+// ALREADY-EXISTING `epics/<id>/` dir — unlike a brand-new Epic's `prds/`,
+// which is always created in the SAME mkdirSync call as `epics/<id>/`
+// itself (see listEpicPrdDirs's header), that does not bump the Epics
+// root's own mtime. Re-stating every Epic subdirectory's own mtime on every
+// call to close that gap would cost about what the walk itself costs,
+// defeating the cache — so this cache pairs the mtime key (instant
+// invalidation for the case the non-negotiable freshness test covers: a
+// brand-new Epic's `prds/` dir) with the SAME short TTL backstop
+// src/main/lib/activeSessions.cjs's cwdScanCache already established for
+// this exact module chain, bounding the archived-dir blind spot to one
+// TTL window instead of leaving it stale indefinitely. Nothing reads
+// resolveArchivedPrdsDirs off the dispatch-correctness path — the
+// archived-twin stale-queue-row guard (scheduler.cjs's archivedTwinExists)
+// calls listArchivedPrdDirs directly, uncached — so this is purely a
+// reporting-freshness bound (schedule:list-prds's per-Epic PRD/run counts).
+// Above the 60 s dispatch-loop interval (scheduler POLL_INTERVAL_MS).
+const ASSEMBLED_DIRS_CACHE_TTL_MS = 120_000;
+const assembledPrdsDirsCache = new Map(); // callerKey -> { freshnessKey, cachedAt, result }
+const assembledArchivedPrdsDirsCache = new Map();
+
+// Sorted-keys JSON.stringify: a plain JSON.stringify(opts) would key
+// { a: 1, b: 2 } and { b: 2, a: 1 } as two different cache entries — a real
+// (if currently latent, since every caller today passes at most one opts
+// key) correctness trap for a cache key.
+function stableStringify(obj) {
+  return JSON.stringify(obj, Object.keys(obj).sort());
+}
+
+function callerOptsKey(maxAgeMin, opts) {
+  return `${maxAgeMin}::${opts ? stableStringify(opts) : ''}`;
+}
+
+// mtimeMs of each visited project's Epics root, joined into one string. Any
+// project whose root doesn't exist/isn't readable contributes a stable
+// sentinel so the key still changes the moment that root is created.
+function epicsRootsFreshnessKey(cwds) {
+  return cwds
+    .map((cwd) => {
+      let root;
+      try { root = resolveEpicsRoot(cwd); } catch { return `${cwd}:noroot`; }
+      try { return `${root}:${fs.statSync(root).mtimeMs}`; } catch { return `${root}:-1`; }
+    })
+    .join('|');
+}
+
+function memoizedAssembledDirs(cache, maxAgeMin, opts, compute) {
+  const callerKey = callerOptsKey(maxAgeMin, opts);
+  const allCwds = allProjectCwds(opts);
+  const activeCwds = activeProjectCwds(maxAgeMin, opts);
+  const cwdUnion = [...new Set([...allCwds, ...activeCwds])];
+  const freshnessKey = `${allCwds.join(',')}#${activeCwds.join(',')}#${epicsRootsFreshnessKey(cwdUnion)}`;
+
+  const cached = cache.get(callerKey);
+  if (cached && cached.freshnessKey === freshnessKey && Date.now() - cached.cachedAt < ASSEMBLED_DIRS_CACHE_TTL_MS) {
+    return cached.result;
+  }
+
+  const result = compute(allCwds, activeCwds);
+  if (Array.isArray(result)) Object.freeze(result);
+  cache.set(callerKey, { freshnessKey, cachedAt: Date.now(), result });
+  return result;
+}
+
 /**
  * resolvePrdsDirs(maxAgeMin?, opts?) → string[]
  *
@@ -122,34 +242,36 @@ function resolvePrdWriteDir(cwd) {
  * underlying scan (e.g. `projectsDir` override for tests).
  */
 function resolvePrdsDirs(maxAgeMin, opts) {
-  const dirs = [];
-  const seen = new Set();
-  const add = (dir) => {
-    if (seen.has(dir)) return;
-    seen.add(dir);
-    dirs.push(dir);
-  };
-
-  // Every historical project that has a PRD dir on disk — the set that
-  // matters for discovery, regardless of when it was last touched.
-  for (const cwd of allProjectCwds(opts)) {
-    let dir;
-    try { dir = resolvePrdWriteDir(cwd); } catch { continue; }
-    if (fs.existsSync(dir)) add(dir);
-    // Epic-scoped dirs (the write layout for all new PRDs) are first-class
-    // scan sources alongside the legacy flat dir.
-    for (const epicDir of listEpicPrdDirs(cwd)) add(epicDir);
-  }
+  return memoizedAssembledDirs(assembledPrdsDirsCache, maxAgeMin, opts, (allCwds, activeCwds) => {
+    const dirs = [];
+    const seen = new Set();
+    const add = (dir) => {
+      if (seen.has(dir)) return;
+      seen.add(dir);
+      dirs.push(dir);
+    };
 
-  // Active projects are added unconditionally: a brand-new project has no
-  // prds/ dir yet, and callers that resolve a write destination must still
-  // find it. Scans over a non-existent dir are a harmless ENOENT no-op.
-  for (const cwd of activeProjectCwds(maxAgeMin, opts)) {
-    try { add(resolvePrdWriteDir(cwd)); } catch { /* unusable cwd */ }
-    for (const epicDir of listEpicPrdDirs(cwd)) add(epicDir);
-  }
+    // Every historical project that has a PRD dir on disk — the set that
+    // matters for discovery, regardless of when it was last touched.
+    for (const cwd of allCwds) {
+      let dir;
+      try { dir = resolvePrdWriteDir(cwd); } catch { continue; }
+      if (fs.existsSync(dir)) add(dir);
+      // Epic-scoped dirs (the write layout for all new PRDs) are first-class
+      // scan sources alongside the legacy flat dir.
+      for (const epicDir of listEpicPrdDirs(cwd)) add(epicDir);
+    }
 
-  return dirs;
+    // Active projects are added unconditionally: a brand-new project has no
+    // prds/ dir yet, and callers that resolve a write destination must still
+    // find it. Scans over a non-existent dir are a harmless ENOENT no-op.
+    for (const cwd of activeCwds) {
+      try { add(resolvePrdWriteDir(cwd)); } catch { /* unusable cwd */ }
+      for (const epicDir of listEpicPrdDirs(cwd)) add(epicDir);
+    }
+
+    return dirs;
+  });
 }
 
 /**
@@ -163,26 +285,28 @@ function resolvePrdsDirs(maxAgeMin, opts) {
  * history, not something list-prds should stop counting.
  */
 function resolveArchivedPrdsDirs(maxAgeMin, opts) {
-  const dirs = [];
-  const seen = new Set();
-  const add = (dir) => {
-    if (seen.has(dir)) return;
-    seen.add(dir);
-    dirs.push(dir);
-  };
-
-  for (const cwd of allProjectCwds(opts)) {
-    for (const dir of listArchivedPrdDirs(cwd)) {
-      if (fs.existsSync(dir)) add(dir);
+  return memoizedAssembledDirs(assembledArchivedPrdsDirsCache, maxAgeMin, opts, (allCwds, activeCwds) => {
+    const dirs = [];
+    const seen = new Set();
+    const add = (dir) => {
+      if (seen.has(dir)) return;
+      seen.add(dir);
+      dirs.push(dir);
+    };
+
+    for (const cwd of allCwds) {
+      for (const dir of listArchivedPrdDirs(cwd)) {
+        if (fs.existsSync(dir)) add(dir);
+      }
     }
-  }
-  for (const cwd of activeProjectCwds(maxAgeMin, opts)) {
-    for (const dir of listArchivedPrdDirs(cwd)) {
-      if (fs.existsSync(dir)) add(dir);
+    for (const cwd of activeCwds) {
+      for (const dir of listArchivedPrdDirs(cwd)) {
+        if (fs.existsSync(dir)) add(dir);
+      }
     }
-  }
 
-  return dirs;
+    return dirs;
+  });
 }
 
 /**
@@ -216,6 +340,50 @@ function deriveEpicIdFromPrdPath(filePath) {
   return epicId;
 }
 
+/**
+ * deriveProjectCwdFromPrdPath(filePath) → projectCwd | null
+ *
+ * The inverse of resolvePrdWriteDir/resolveEpicPrdWriteDir: given an absolute
+ * PRD file path (flat `prds/`, Epic-scoped `epics/<id>/prds/`, or either's
+ * `prds-archived/` sibling), returns the project root it was discovered
+ * under — by finding the `session-manager-operations` segment and validating
+ * the path round-trips back through the same resolver it walked up from.
+ * Returns null for anything that doesn't match one of those shapes (never
+ * guesses). Used by reconcile()'s fresh-discovery path so a PRD file with no
+ * `cwd:` frontmatter still gets a real project cwd instead of null (which
+ * would otherwise fall through to schedulerBatch.js's DEFAULT_PROJECT_CWD
+ * and relocate the row into the wrong project's queue.json shard).
+ */
+function deriveProjectCwdFromPrdPath(filePath) {
+  if (!filePath || typeof filePath !== 'string' || !path.isAbsolute(filePath)) return null;
+  const segments = filePath.split(path.sep);
+  const opsIdx = segments.lastIndexOf(OPS_ROOT_DIR);
+  if (opsIdx <= 0) return null;
+  const projectCwd = segments.slice(0, opsIdx).join(path.sep);
+  const prdsDir = path.dirname(filePath);
+  const dirName = path.basename(prdsDir);
+  if (dirName !== 'prds' && dirName !== 'prds-archived') return null;
+  if (dirName === 'prds') {
+    try {
+      if (resolvePrdWriteDir(projectCwd) === prdsDir) return projectCwd;
+    } catch { /* fall through to the Epic-scoped check below */ }
+  }
+  if (dirName === 'prds-archived') {
+    // Flat legacy archive sibling of resolvePrdWriteDir's flat `prds/` (see
+    // listArchivedPrdDirs' first entry: opsPath(cwd, ...PRD_SUBPATH, '..',
+    // 'prds-archived')) — round-trip it the same way the flat `prds` branch
+    // above does, before falling through to the Epic-scoped check (which
+    // can never match a flat path: deriveEpicIdFromPrdPath requires an
+    // `epics/<id>/` segment a flat archive dir doesn't have).
+    try {
+      if (opsPath(projectCwd, ...PRD_SUBPATH, '..', 'prds-archived') === prdsDir) return projectCwd;
+    } catch { /* fall through to the Epic-scoped check below */ }
+  }
+  const epicId = deriveEpicIdFromPrdPath(filePath);
+  if (epicId) return projectCwd;
+  return null;
+}
+
 module.exports = {
   resolvePrdWriteDir,
   resolvePrdsDirs,
@@ -225,6 +393,7 @@ module.exports = {
   listEpicPrdDirs,
   listArchivedPrdDirs,
   deriveEpicIdFromPrdPath,
+  deriveProjectCwdFromPrdPath,
   PRD_SUBPATH,
   EPICS_SUBPATH,
 };

package/src/main/lib/procIdentity.cjs

@@ -0,0 +1,126 @@
+/**
+ * procIdentity.cjs — fail-closed process identity, so a recycled pid can
+ * never be mistaken for the process that originally held it.
+ *
+ * identity(pid) reads /proc/<pid>/stat field 22 (starttime) — located AFTER
+ * the last ')', because `comm` (field 2) can itself contain spaces or
+ * parens — plus /proc/<pid>/cmdline. On a platform with no /proc (macOS),
+ * falls back to `ps -o lstart=,command=` (lstart has only second
+ * granularity, which is the known limit of that path).
+ *
+ * isDifferentProcess(recorded, live) is the ONLY decision function callers
+ * should use, and it is deliberately fail-closed in the SAFE direction: it
+ * returns true — "safe to treat the recorded holder as gone" — ONLY when
+ * BOTH sides are a complete identity AND they differ. An unreadable /proc
+ * entry, a missing live probe, or a legacy record with no identity fields at
+ * all all read as "not different" — i.e. today's pid-only behaviour, never a
+ * false positive that could wrongly break a live lock or veto a real kill.
+ *
+ * SM_PROC_ROOT overrides the /proc root — tests only, so stat/cmdline
+ * fixtures can be written under a temp dir instead of touching real /proc.
+ */
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+
+const MONTHS = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
+
+function procRoot() {
+  return process.env.SM_PROC_ROOT || '/proc';
+}
+
+function hasProc() {
+  try {
+    return fs.existsSync(procRoot());
+  } catch {
+    return false;
+  }
+}
+
+/** Field 22 (starttime) sits AFTER the last ')' — comm can hold spaces/parens. */
+function parseStatStartTicks(raw) {
+  const lastParen = raw.lastIndexOf(')');
+  if (lastParen === -1) return null;
+  const rest = raw.slice(lastParen + 1).trim();
+  if (!rest) return null;
+  const fields = rest.split(/\s+/);
+  // `rest[0]` is field 3 (state); field N sits at index (N - 3), so field 22
+  // (starttime) is index 19.
+  const startTicksStr = fields[19];
+  if (startTicksStr === undefined) return null;
+  const startTicks = Number(startTicksStr);
+  return Number.isFinite(startTicks) ? startTicks : null;
+}
+
+function readCmdlineFile(pid) {
+  const raw = fs.readFileSync(path.join(procRoot(), String(pid), 'cmdline'), 'utf8');
+  const cmd = raw.replace(/\0+$/, '').split('\0').join(' ').trim();
+  return cmd.length > 0 ? cmd : null;
+}
+
+function identityFromProc(pid) {
+  let startTicks = null;
+  let cmdline = null;
+  try {
+    const raw = fs.readFileSync(path.join(procRoot(), String(pid), 'stat'), 'utf8');
+    startTicks = parseStatStartTicks(raw);
+  } catch { /* unreadable stat (dead pid, hidepid, race) — leave null */ }
+  try {
+    cmdline = readCmdlineFile(pid);
+  } catch { /* unreadable cmdline — leave null */ }
+  return { pid, startTicks, cmdline, complete: startTicks !== null && cmdline !== null };
+}
+
+function parseLstart(lstart) {
+  const m = /^\w{3}\s+(\w{3})\s+(\d{1,2})\s+(\d{2}):(\d{2}):(\d{2})\s+(\d{4})$/.exec(lstart.trim());
+  if (!m) return null;
+  const monthIdx = MONTHS.indexOf(m[1]);
+  if (monthIdx === -1) return null;
+  const ms = Date.UTC(Number(m[6]), monthIdx, Number(m[2]), Number(m[3]), Number(m[4]), Number(m[5]));
+  return Number.isFinite(ms) ? ms : null;
+}
+
+function identityFromPs(pid) {
+  let out;
+  try {
+    out = execFileSync('ps', ['-p', String(pid), '-o', 'lstart=,command='], { encoding: 'utf8' });
+  } catch {
+    return { pid, startTicks: null, cmdline: null, complete: false };
+  }
+  const trimmed = out.replace(/\n$/, '');
+  const m = /^(\w{3}\s+\w{3}\s+\d{1,2}\s+\d{2}:\d{2}:\d{2}\s+\d{4})\s(.*)$/.exec(trimmed);
+  if (!m) return { pid, startTicks: null, cmdline: null, complete: false };
+  const startTicks = parseLstart(m[1]);
+  const cmdline = m[2].trim() || null;
+  return { pid, startTicks, cmdline, complete: startTicks !== null && cmdline !== null };
+}
+
+/** identity(pid) → {pid, startTicks, cmdline, complete}. Never throws. */
+function identity(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) {
+    return { pid, startTicks: null, cmdline: null, complete: false };
+  }
+  try {
+    return hasProc() ? identityFromProc(pid) : identityFromPs(pid);
+  } catch {
+    return { pid, startTicks: null, cmdline: null, complete: false };
+  }
+}
+
+/**
+ * isDifferentProcess(recorded, live) — true ONLY when both sides are a
+ * COMPLETE identity and differ. Every other case (missing side, incomplete
+ * side, a legacy record with no identity fields) is "not different", i.e.
+ * today's pid-only behaviour — the fail-closed default.
+ */
+function isDifferentProcess(recorded, live) {
+  if (!recorded || !live) return false;
+  if (!recorded.complete || !live.complete) return false;
+  return recorded.pid !== live.pid
+    || recorded.startTicks !== live.startTicks
+    || recorded.cmdline !== live.cmdline;
+}
+
+module.exports = { identity, isDifferentProcess };

package/src/main/lib/procName.cjs

@@ -0,0 +1,98 @@
+/**
+ * procName.cjs — make Session Manager's spawned processes distinguishable in
+ * GNOME System Monitor / ps / htop.
+ *
+ *  - aliasBinFor(realBin, alias): the kernel sets `comm` (the "Process Name"
+ *    column) to the basename of the path handed to execve, capped at 15 chars
+ *    (TASK_COMM_LEN 16 incl. NUL). argv0 does NOT affect it, so we exec a
+ *    symlink named `alias` that points at the real binary.
+ *  - smArgv0(role, detail): a bounded argv0 label for /proc/pid/cmdline. It
+ *    ALWAYS contains `claude` as a word — /\bclaude\b/ gates killOrphanClaudePid
+ *    (scheduler.cjs), claudePidAlive and findLiveProcessForJob (reaperHelpers.cjs).
+ *
+ * Fail-open is absolute: any error returns the ORIGINAL bin. Naming must never
+ * stop a job from launching.
+ *
+ * DELIBERATE exceptions to CLAUDE.md laws (do not "fix"):
+ *  - The tmp+rename symlink primitive below is NOT config.cjs writeJson /
+ *    writeTextAtomic: those write file contents and cannot create symlinks.
+ *  - procnamesRoot() is intentionally NOT registered with config.cjs validateWrite /
+ *    addAllowedRoot: that containment governs IPC-reachable writes; this is a
+ *    main-process-internal write.
+ *
+ * Not to be confused with procIdentity.cjs (pid-recycling fingerprint).
+ */
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { procnamesRoot } = require('./schedulerPaths.cjs');
+const MAX_ALIAS_LEN = 15; // Linux TASK_COMM_LEN (16) minus NUL
+const MAX_LABEL_LEN = 120;
+
+let tmpSeq = 0;
+
+function resolveBare(bin) {
+  if (path.isAbsolute(bin)) return bin;
+  try {
+    // Lazy: openExternalApp requires 'electron', unavailable outside the app.
+    const { findCommand } = require('./openExternalApp.cjs');
+    const found = findCommand(bin);
+    return found && path.isAbsolute(found) ? found : null;
+  } catch { return null; }
+}
+
+/** O(1) fs ops. Returns alias path on success, else `realBin` unchanged. */
+function aliasBinFor(realBin, alias) {
+  if (typeof alias !== 'string' || !alias || alias.length > MAX_ALIAS_LEN || /[\\/\0]/.test(alias) || alias === '.' || alias === '..') {
+    throw new Error(`procName: alias "${alias}" must be 1-${MAX_ALIAS_LEN} chars (Linux TASK_COMM_LEN) with no path separators`);
+  }
+  try {
+    if (typeof realBin !== 'string' || !realBin) return realBin;
+    const target = resolveBare(realBin);
+    if (!target) return realBin;
+    const aliasPath = path.join(procnamesRoot(), alias);
+    let current = null;
+    try { current = fs.readlinkSync(aliasPath); } catch { /* absent or not a link */ }
+    if (current !== target) {
+      fs.mkdirSync(procnamesRoot(), { recursive: true });
+      const tmp = path.join(procnamesRoot(), `.${alias}.${process.pid}.${Date.now()}.${tmpSeq++}.tmp`);
+      try {
+        fs.symlinkSync(target, tmp);
+        fs.renameSync(tmp, aliasPath); // atomic replace; never unlink-then-symlink
+      } catch (err) {
+        try { fs.unlinkSync(tmp); } catch { /* nothing to clean */ }
+        if (err && err.code !== 'EEXIST') throw err; // losing racer: swallow
+      }
+    }
+    fs.accessSync(aliasPath, fs.constants.X_OK); // noexec / dangling probe
+    return aliasPath;
+  } catch {
+    return realBin;
+  }
+}
+
+/** `sm-claude-<role>:<detail>`, sanitised to [A-Za-z0-9._-], <= 120 chars. Always contains word `claude`. */
+function smArgv0(role, detail) {
+  const clean = (v) => String(v == null ? '' : v).replace(/[^A-Za-z0-9._-]/g, '');
+  const r = clean(role) || 'proc';
+  const d = clean(detail);
+  return `sm-claude-${r}${d ? `:${d}` : ''}`.slice(0, MAX_LABEL_LEN);
+}
+
+/** Remove alias entries whose target no longer resolves to an executable. Never throws. O(entries). */
+function pruneStaleAliases() {
+  try {
+    for (const name of fs.readdirSync(procnamesRoot())) {
+      const p = path.join(procnamesRoot(), name);
+      try {
+        fs.accessSync(p, fs.constants.X_OK);
+      } catch {
+        try { fs.unlinkSync(p); } catch { /* best effort */ }
+      }
+    }
+  } catch { /* root absent/unreadable */ }
+}
+
+module.exports = { aliasBinFor, smArgv0, procnamesRoot, pruneStaleAliases };