claude-code-session-manager 0.87.0 → 0.88.0

package/src/main/lib/mcpToolCatalog.cjs

@@ -47,6 +47,24 @@ const MCP_TOOL_CATALOG = [
     exampleArgs: { slug: 'add-mcp-tool-catalog', force: false },
     notes: 'Refuses a job whose status is already "completed" unless force:true is passed — resetting a completed job re-executes already-shipped work.',
   },
+  {
+    name: 'scheduler_pause',
+    group: 'scheduler',
+    purpose: "Pause the scheduler (user-initiated) via the session-manager app's admin API.",
+    whenToUse: 'Use to stop NEW job dispatch on request (e.g. before a risky change). Running jobs are never killed.',
+    whenNotToUse: 'Do not use to cancel a running job (use scheduler_cancel_job) or as a workaround for a stuck queue.',
+    exampleArgs: {},
+    notes: 'A manual pause survives app restart and is never auto-cleared by the rate-limit timer or network recovery — only scheduler_resume clears it.',
+  },
+  {
+    name: 'scheduler_resume',
+    group: 'scheduler',
+    purpose: "Clear any scheduler pause (manual or automatic) via the session-manager app's admin API.",
+    whenToUse: 'Use to restart dispatch after scheduler_pause, or to lift an auto-pause you have judged stale.',
+    whenNotToUse: 'Do not use to retry a parked needs_review job — that is scheduler_reset_job.',
+    exampleArgs: {},
+    notes: null,
+  },
   {
     name: 'scheduler_list_jobs',
     group: 'scheduler',
@@ -224,65 +242,18 @@ const MCP_TOOL_CATALOG = [
       + 'delivered.',
   },
   {
-    name: 'project_home_get_contract',
-    group: 'project-home',
-    purpose: "Fetch the self-sufficient contract for generating this project's Project Home pages via the "
-      + "session-manager app's admin API — the protocol steps, the ProjectPageSummary/ProjectPagePicks JSON "
-      + 'schemas, the component catalog (all 5 lenses: home, marketing, feature, architecture, brief), the '
-      + 'absolute output paths, and the full pipeline spec text. Nothing in the response requires reading '
-      + "session-manager's own repo — this is what makes generation work on a machine with only the npm "
-      + 'package installed.',
-    whenToUse: 'Call this FIRST, before composing any ProjectPageSummary content or picking variants, whenever '
-      + 'a project-home-builder session starts generating Project Home pages for a project.',
-    whenNotToUse: 'Do not begin composing a ProjectPageSummary or choosing variants before calling this — it '
-      + 'must be the FIRST call a project-home-builder session makes; every other project_home_* tool assumes '
-      + "you already have this response's schema/catalog/paths in hand.",
-    exampleArgs: { cwd: '/home/bilko/Projects/session-manager' },
-    notes: "cwd is optional — defaults to the calling session's own project root (SM_PROJECT_ROOT or process.cwd()) when omitted.",
-  },
-  {
-    name: 'project_home_validate_summary',
-    group: 'project-home',
-    purpose: 'Validate a composed ProjectPageSummary against the schema from project_home_get_contract via the '
-      + "session-manager app's admin API, without writing anything to disk.",
-    whenToUse: 'Use after composing (or editing) a ProjectPageSummary and before calling project_home_render — '
-      + 'fix every returned {field, message} error and re-validate until valid:true.',
-    whenNotToUse: 'Do not skip straight to project_home_render on an unvalidated summary — render does '
-      + 're-validate server-side and rejects with no writes on failure, but catching errors here first saves a '
-      + 'round trip and gives per-field detail sooner.',
-    exampleArgs: { cwd: '/home/bilko/Projects/session-manager', summary: { title: 'Example Project' } },
-    notes: "cwd is optional — defaults to the calling session's own project root (SM_PROJECT_ROOT or process.cwd()) when omitted.",
-  },
-  {
-    name: 'project_home_render',
-    group: 'project-home',
-    purpose: 'Render and write all 5 Project Home lenses (home, marketing, feature, architecture, brief) plus '
-      + "summary.json/picks.json/manifest.json via the session-manager app's admin API — the only write path "
-      + 'for Project Home generation.',
-    whenToUse: 'Use once project_home_validate_summary reports valid:true and a variant has been picked for '
-      + "every lens/slot in the contract's catalog.",
-    whenNotToUse: 'Must NOT be used to fabricate summary content — every field of the summary passed here must '
-      + 'trace to something concrete about the real project (an Epic goal, a source file/dir, a convention, a '
-      + 'git log entry). This tool re-validates the summary server-side and rejects with no writes on schema '
-      + 'failure, but it only checks shape, never truthfulness.',
-    exampleArgs: {
-      cwd: '/home/bilko/Projects/session-manager',
-      summary: { title: 'Example Project' },
-      picks: { home: { hero: 'variant-a' } },
-    },
-    notes: "cwd is optional — defaults to the calling session's own project root (SM_PROJECT_ROOT or process.cwd()) when omitted.",
-  },
-  {
-    name: 'project_home_status',
+    name: 'project_home_write',
     group: 'project-home',
-    purpose: "Report what already exists for this project's Project Home generation via the session-manager "
-      + "app's admin API — summary.json/picks.json/each lens file's existence + mtime, and manifest.json's "
-      + 'generatedAt.',
-    whenToUse: 'Use before starting generation to see prior state, and again after project_home_render to '
-      + 'confirm the new files landed.',
-    whenNotToUse: 'Do not treat an all-absent result as an error — a project that has never generated a '
-      + 'Project Home page yet still returns a well-formed status with every exists:false rather than failing.',
-    exampleArgs: { cwd: '/home/bilko/Projects/session-manager' },
+    purpose: "Write this project's Project Home page — ONE self-contained HTML document — to "
+      + "session-manager-operations/project-pages/home.html via the session-manager app's admin API. "
+      + 'The only write path for Project Home.',
+    whenToUse: 'Use when asked to generate or refresh the project home page. Compose the whole page yourself '
+      + '(inline <style>/<script>, data: URIs for assets) from what is really true about the project, then '
+      + 'pass the full document as `html`.',
+    whenNotToUse: 'Never fabricate content — every claim must trace to something concrete in the project. The '
+      + 'document must be self-contained: the call is rejected for empty input, more than 1MB, any '
+      + '<script src>, <link href="http…">, @import, or url(http…) — no network egress.',
+    exampleArgs: { cwd: '/home/bilko/Projects/session-manager', html: '<!DOCTYPE html><html><body><h1>Example</h1></body></html>' },
     notes: "cwd is optional — defaults to the calling session's own project root (SM_PROJECT_ROOT or process.cwd()) when omitted.",
   },
   {
@@ -335,25 +306,6 @@ const MCP_RECIPES = [
       'The call only delivers a PROPOSED session in the receiving project — nothing runs until a human there presses Approve & start; there is no reply channel.',
     ],
   },
-  {
-    id: 'generate-project-home',
-    title: "Generate a project's Project Home pages",
-    steps: [
-      "Call project_home_get_contract to get the protocol, ProjectPageSummary/ProjectPagePicks schemas, "
-        + 'component catalog, absolute output paths, and pipeline spec — the FIRST call any '
-        + 'project-home-builder session makes.',
-      'Author a ProjectPageSummary matching the contract\'s summarySchema — every field must trace to '
-        + 'something concrete about the real project; never fabricate content.',
-      'Call project_home_validate_summary with { cwd, summary } and fix every {field, message} error it '
-        + 'returns, re-validating until valid:true.',
-      "For each lens and slot in the contract's catalog, choose exactly one variant id by judging the "
-        + 'candidate variants against the summary you composed, assembling a ProjectPagePicks object '
-        + '(lensId -> slotId -> variantId).',
-      'Call project_home_render with { cwd, summary, picks } to render all 5 lenses and write '
-        + 'summary.json/picks.json/output files.',
-      "Call project_home_status to confirm the new files landed and read manifest.json's generatedAt.",
-    ],
-  },
 ];
 
 for (const entry of MCP_TOOL_CATALOG) {

package/src/main/lib/opsOwnership.cjs

@@ -48,17 +48,10 @@ const OWNERS = Object.freeze({
   'scheduler': 'scheduler',
   // Project Home owns the synthesized Brief (generate + hand-edit).
   'project-brief': 'project-home',
-  // Project Home also owns the app-side render path for Project Pages
-  // (summary.json/picks.json/output/* written via the
-  // /admin/project-home/render route, config.cjs's writeJson). This is a
-  // NARROWER claim than "project-home owns everything under this folder":
-  // the SAME folder is also written directly by a project-home-builder
-  // Epic's own Write tool, which never goes through config.cjs and so is
-  // NOT governed by this table at all (see
-  // session-manager-operations/project-pages/README.md). Declaring the
-  // namespace here only closes the fail-closed gap for the app's own write
-  // path — it does not claim exclusivity over the agent's Write-tool calls,
-  // which remain outside this law by construction.
+  // Project Home owns project-pages/home.html, written only via the
+  // project_home_write MCP tool -> /admin/project-home/write route
+  // (config.cjs's writeTextAtomic). See
+  // session-manager-operations/project-pages/README.md.
   'project-pages': 'project-home',
   // Structured per-tab error log lines (JSONL), tagged for tracing/analysis.
   'logs': 'logs',
@@ -177,11 +170,13 @@ function assertOpsWrite(absPath, writer) {
   // worktree-cwd hazard (PRD 1082; incidents 2026-08-30, 2026-09-01).
   const { inOps } = parseOpsPath(absPath);
   if (inOps) {
-    const segs = absPath.split(path.sep);
-    const idx = segs.lastIndexOf(OPS_ROOT_DIR);
-    const projectRoot = segs.slice(0, idx).join(path.sep) || path.sep;
-    const { isEphemeralCwd } = require('./ephemeralCwd.cjs');
-    if (isEphemeralCwd(projectRoot)) {
+    // innermostOpsRoot (lastIndexOf) is the fact THIS gate keys on; activeSessions
+    // truncates at the outermost instead — cwdClassify returns both, unified in
+    // neither direction.
+    const { classifyCwd } = require('./cwdClassify.cjs');
+    const projectRoot = path.dirname(classifyCwd(absPath).innermostOpsRoot);
+    const { kind, reason } = classifyCwd(projectRoot);
+    if (kind === 'ephemeral' || kind === 'worktree') {
       const err = new Error(
         `refusing to write ${OPS_ROOT_DIR}/ state under an ephemeral project root `
         + `(tmpdir or linked git worktree): "${projectRoot}" — see lib/opsOwnership.cjs resolveProjectRoot`,
@@ -189,6 +184,17 @@ function assertOpsWrite(absPath, writer) {
       err.ephemeral = true;
       throw err;
     }
+    if (kind === 'unknown') {
+      // Fail closed on the unprovable case (worktree .git file whose admin
+      // back-reference is gone, garbled .git file): the exact shape behind the
+      // lost-Epics incidents. WRITES only — reads and dispatch stay open.
+      const err = new Error(
+        `refusing to write ${OPS_ROOT_DIR}/ state under "${projectRoot}": project identity `
+        + `cannot be proven (${reason}) — see lib/cwdClassify.cjs`,
+      );
+      err.unknownCwd = true;
+      throw err;
+    }
   }
 }
 
@@ -236,10 +242,12 @@ function resolveProjectRoot(cwd, { opsInternal = 'normalize' } = {}) {
       `resolveProjectRoot: cwd must be a project root, not a path inside ${OPS_ROOT_DIR}/, got "${cwd}"`,
     );
   }
-  // Lazy: activeSessions → gitWorktree → (lazily) config.cjs → this module.
-  const { projectRootOf } = require('./activeSessions.cjs');
+  // Lazy: cwdClassify → schedulerPaths; ephemeralCwd → cwdClassify.
+  const { classifyCwd } = require('./cwdClassify.cjs');
   const { isEphemeralCwd } = require('./ephemeralCwd.cjs');
-  const root = projectRootOf(cwd);
+  // `unknown` deliberately does NOT throw here: reads and dispatch must keep
+  // working; assertOpsWrite is the choke point that refuses the WRITE.
+  const root = classifyCwd(cwd).projectRoot;
   if (isEphemeralCwd(root)) {
     const err = new Error(
       `resolveProjectRoot: refusing ephemeral cwd (tmpdir or linked git worktree), got "${cwd}"`,

package/src/main/lib/prdAuthoringSeed.cjs

@@ -0,0 +1,36 @@
+'use strict';
+// Seed-when-the-stamp-differs for the bundled PRD_AUTHORING.md guide.
+// Pure fs + injected writer so it is testable without an Electron app.
+
+const fs = require('fs');
+
+const STAMP_RE = /^<!--\s*PRD_AUTHORING\.md\s+(v\d+)\s*-->/;
+
+/** Version stamp from line 1 of `text`, or null when absent. */
+function readStamp(text) {
+  const first = String(text).split(/\r?\n/, 1)[0];
+  const m = STAMP_RE.exec(first);
+  return m ? m[1] : null;
+}
+
+/** True when dest should be (re)written from src: missing/unstamped/differing stamp. */
+function shouldSeed(srcText, destText) {
+  if (destText == null) return true;
+  const destStamp = readStamp(destText);
+  return destStamp === null || destStamp !== readStamp(srcText);
+}
+
+/**
+ * Overwrite `dest` with `src` when shouldSeed. `write(abs, text)` is the atomic
+ * writer (config.writeTextAtomic). Resolves true when it wrote, false otherwise.
+ */
+async function seedAuthoringGuide({ src, dest, write }) {
+  if (!fs.existsSync(src)) return false;
+  const srcText = fs.readFileSync(src, 'utf8');
+  const destText = fs.existsSync(dest) ? fs.readFileSync(dest, 'utf8') : null;
+  if (!shouldSeed(srcText, destText)) return false;
+  await write(dest, srcText);
+  return true;
+}
+
+module.exports = { readStamp, shouldSeed, seedAuthoringGuide };

package/src/main/lib/prdLocations.cjs

@@ -173,7 +173,8 @@ function resolvePrdWriteDir(cwd) {
 // 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).
-const ASSEMBLED_DIRS_CACHE_TTL_MS = 30_000;
+// 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();
 
@@ -215,6 +216,7 @@ function memoizedAssembledDirs(cache, maxAgeMin, opts, compute) {
   }
 
   const result = compute(allCwds, activeCwds);
+  if (Array.isArray(result)) Object.freeze(result);
   cache.set(callerKey, { freshnessKey, cachedAt: Date.now(), result });
   return result;
 }
@@ -338,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,
@@ -347,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 };