claude-code-session-manager 0.87.0 → 0.88.0

package/src/main/__tests__/prdLocationsArchived.test.cjs

@@ -159,21 +159,28 @@ test('resolveArchivedPrdsDirs: a prds-archived/ dir created inside an ALREADY-EX
   // so the mtime-keyed freshness key alone would never invalidate. The
   // short TTL backstop (same idiom as activeSessions.cjs's cwdScanCache)
   // bounds that blind spot instead of leaving it stale indefinitely.
-  vi.useFakeTimers();
-  try {
-    const projectsDir = await fsp.mkdtemp(path.join(os.tmpdir(), 'sm-prdloc-blindspot-projects-'));
-    tmpDirs.push(projectsDir);
-    const projectCwd = await mkEpicProject();
-    tmpDirs.push(projectCwd);
+  //
+  // Why this test is sensitive to the process environment: the code under test
+  // keys its cache on REAL directory mtimes and expires it via Date.now(); the
+  // fixtures are mkdtemp'd under os.tmpdir(), which a TMPDIR override moves.
+  // Installing fake timers BEFORE the async fs fixture setup let the fake timer
+  // queue interleave with real fs completions. Build every fixture on the real
+  // clock first, then fake ONLY Date — the sole clock the TTL reads.
+  const projectsDir = await fsp.mkdtemp(path.join(os.tmpdir(), 'sm-prdloc-blindspot-projects-'));
+  tmpDirs.push(projectsDir);
+  const projectCwd = await mkEpicProject();
+  tmpDirs.push(projectCwd);
 
-    const epicId = `blindspot-epic-${process.pid}`;
-    const epicPrdsDir = resolveEpicPrdWriteDir(projectCwd, epicId);
-    fs.mkdirSync(epicPrdsDir, { recursive: true }); // Epic already exists, well before archiving.
+  const epicId = `blindspot-epic-${process.pid}`;
+  const epicPrdsDir = resolveEpicPrdWriteDir(projectCwd, epicId);
+  fs.mkdirSync(epicPrdsDir, { recursive: true }); // Epic already exists, well before archiving.
 
-    const projDir = path.join(projectsDir, 'blindspot-project');
-    fs.mkdirSync(projDir, { recursive: true });
-    fs.writeFileSync(path.join(projDir, 'session1.jsonl'), `${JSON.stringify({ cwd: projectCwd })}\n`);
+  const projDir = path.join(projectsDir, 'blindspot-project');
+  fs.mkdirSync(projDir, { recursive: true });
+  fs.writeFileSync(path.join(projDir, 'session1.jsonl'), `${JSON.stringify({ cwd: projectCwd })}\n`);
 
+  vi.useFakeTimers({ toFake: ['Date'] });
+  try {
     // Prime the cache — no prds-archived/ dir exists yet.
     const before = resolveArchivedPrdsDirs(90, { projectsDir });
     const epicArchiveDir = path.join(epicPrdsDir, '..', 'prds-archived');
@@ -185,7 +192,7 @@ test('resolveArchivedPrdsDirs: a prds-archived/ dir created inside an ALREADY-EX
     fs.mkdirSync(epicArchiveDir, { recursive: true });
 
     // Bounded staleness is acceptable — but it must actually be bounded.
-    vi.advanceTimersByTime(31_000);
+    vi.advanceTimersByTime(121_000); // TTL is 120 s — above the 60 s dispatch-loop interval
     const after = resolveArchivedPrdsDirs(90, { projectsDir });
     expect(after.map((d) => path.resolve(d))).toContain(path.resolve(epicArchiveDir));
   } finally {

package/src/main/__tests__/proc-role-env.test.cjs

@@ -0,0 +1,125 @@
+/**
+ * proc-role-env.test.cjs — SM_PROC_ROLE attribution env + scripts/sm-ps.cjs.
+ *
+ * Run: timeout 120 npx vitest run src/main/__tests__/proc-role-env.test.cjs
+ */
+'use strict';
+
+import { test, expect, describe, beforeEach, afterEach } from 'vitest';
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { spawn, spawnSync } = require('node:child_process');
+
+const { cleanChildEnv, withProcRole, inferProcRole } = require('../lib/cleanEnv.cjs');
+const { runClaudeP } = require('../lib/runClaudeP.cjs');
+const { runDocEdit } = require('../docEdit.cjs');
+
+const SM_PS = path.join(__dirname, '..', '..', '..', 'scripts', 'sm-ps.cjs');
+
+let tmp;
+let savedBin;
+beforeEach(() => {
+  tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'sm-proc-role-'));
+  savedBin = process.env.SM_CLAUDE_BIN;
+});
+afterEach(() => {
+  if (savedBin === undefined) delete process.env.SM_CLAUDE_BIN; else process.env.SM_CLAUDE_BIN = savedBin;
+  fs.rmSync(tmp, { recursive: true, force: true });
+});
+
+/** Stub `claude` that prints {"after":"<SM_PROC_ROLE>"} — valid for both runClaudeP and docEdit. */
+function writeStub() {
+  const bin = path.join(tmp, 'claude-stub.sh');
+  fs.writeFileSync(bin, '#!/bin/sh\nprintf \'{"after":"%s"}\' "$SM_PROC_ROLE"\n', { mode: 0o755 });
+  return bin;
+}
+
+describe('cleanChildEnv role stamping', () => {
+  test('explicit role wins; inference from existing attribution vars; default aux', () => {
+    expect(cleanChildEnv({ SM_PROC_ROLE: 'shell' }).SM_PROC_ROLE).toBe('shell');
+    expect(inferProcRole({ SM_SCHEDULER_JOB_SLUG: 's' })).toBe('job');
+    expect(inferProcRole({ SM_CHAT_SESSION_ID: 'c' })).toBe('chat');
+    expect(inferProcRole({ SM_CHAT_SESSION_ID: 'c', SESSION_MANAGER_TAB_ID: 'c' })).toBe('shell');
+    expect(cleanChildEnv().SM_PROC_ROLE).toBe('aux');
+  });
+
+  test('is additive: existing attribution vars survive and SM_PROC_ROOT is untouched', () => {
+    const env = cleanChildEnv({ SM_SCHEDULER_JOB_SLUG: 'slug-1', SM_CHAT_SESSION_ID: 'chat-1', SM_PROJECT_ROOT: '/p' });
+    expect(env).toMatchObject({ SM_PROC_ROLE: 'job', SM_SCHEDULER_JOB_SLUG: 'slug-1', SM_CHAT_SESSION_ID: 'chat-1', SM_PROJECT_ROOT: '/p' });
+    expect('SM_PROC_ROOT' in env).toBe(process.env.SM_PROC_ROOT !== undefined);
+  });
+
+  test('withProcRole returns a copy and does not mutate its input', () => {
+    const base = { A: '1' };
+    expect(withProcRole(base, 'aux')).toEqual({ A: '1', SM_PROC_ROLE: 'aux' });
+    expect(base).toEqual({ A: '1' });
+  });
+});
+
+describe('real spawn paths carry SM_PROC_ROLE', () => {
+  test('runClaudeP (bypasses cleanChildEnv)', async () => {
+    process.env.SM_CLAUDE_BIN = writeStub();
+    const r = await runClaudeP('hi');
+    expect(r.ok).toBe(true);
+    expect(JSON.parse(r.out).after).toBe('aux');
+  });
+
+  test('docEdit runClaude (bypasses cleanChildEnv)', async () => {
+    process.env.SM_CLAUDE_BIN = writeStub();
+    const r = await runDocEdit({ path: path.join(os.homedir(), 'x.md'), before: 'a', instruction: 'b', documentText: '' });
+    expect(r).toEqual({ ok: true, after: 'aux' });
+  });
+
+  test('cleanChildEnv-built env reaches a spawned child', async () => {
+    const out = await new Promise((resolve) => {
+      const c = spawn('/bin/sh', ['-c', 'printf %s "$SM_PROC_ROLE"'], { env: cleanChildEnv({ SM_SCHEDULER_JOB_SLUG: 'x' }) });
+      let s = '';
+      c.stdout.on('data', (d) => { s += d; });
+      c.on('close', () => resolve(s));
+    });
+    expect(out).toBe('job');
+  });
+});
+
+describe('scripts/sm-ps.cjs', () => {
+  test('--json lists a tagged stub child (and its descendant) with role, slug, project root', async () => {
+    const env = cleanChildEnv({ SM_SCHEDULER_JOB_SLUG: 'fixture-slug', SM_PROJECT_ROOT: '/fixture/root' });
+    // outer sh forks an inner sleep, so we also assert descendants are included
+    const child = spawn('/bin/sh', ['-c', 'sleep 30 & wait'], { env, stdio: 'ignore' });
+    try {
+      await new Promise((r) => setTimeout(r, 300));
+      const res = spawnSync(process.execPath, [SM_PS, '--json'], { encoding: 'utf8', timeout: 20000 });
+      expect(res.status).toBe(0);
+      const { processes } = JSON.parse(res.stdout);
+      const hit = processes.find((p) => p.pid === child.pid);
+      expect(hit).toMatchObject({ role: 'job', slug: 'fixture-slug', projectRoot: '/fixture/root', attributed: true });
+      expect(processes.some((p) => p.ppid === child.pid)).toBe(true);
+    } finally {
+      try { process.kill(-child.pid); } catch { /* */ }
+      child.kill('SIGKILL');
+    }
+  });
+
+  test('exits 0 with an empty result set when nothing is running (empty proc root)', () => {
+    const root = path.join(tmp, 'proc');
+    fs.mkdirSync(root);
+    const res = spawnSync(process.execPath, [SM_PS, '--json', '--proc-root', root], { encoding: 'utf8' });
+    expect(res.status).toBe(0);
+    expect(JSON.parse(res.stdout)).toEqual({ processes: [] });
+  });
+
+  test('degrades without attribution on unreadable environ / mid-scan exit, never crashes', () => {
+    const root = path.join(tmp, 'proc');
+    fs.mkdirSync(path.join(root, '100'), { recursive: true }); // comm-named ours, environ absent
+    fs.writeFileSync(path.join(root, '100', 'stat'), '100 (sm-watchdog) S 1 0 0');
+    fs.writeFileSync(path.join(root, '100', 'cmdline'), 'node\0x.js\0');
+    fs.mkdirSync(path.join(root, '101')); // vanished: no stat at all
+    const res = spawnSync(process.execPath, [SM_PS, '--json', '--proc-root', root], { encoding: 'utf8' });
+    expect(res.status).toBe(0);
+    const { processes } = JSON.parse(res.stdout);
+    expect(processes).toHaveLength(1);
+    expect(processes[0]).toMatchObject({ pid: 100, comm: 'sm-watchdog', role: null, attributed: false });
+  });
+});

package/src/main/__tests__/procname-claude-spawn-sites.test.cjs

@@ -0,0 +1,304 @@
+/**
+ * procname-claude-spawn-sites.test.cjs — PRD pn-02: every `claude` spawn site
+ * execs a role alias (sm-claude-job/-chat/-aux) with a labelled argv0, WITHOUT
+ * breaking the four /\bclaude\b/ cmdline gates the reapers depend on.
+ *
+ * HOME is redirected BEFORE procName/claudeBin/scheduler load (ALIAS_ROOT is
+ * computed at require time) — never the real ~/.claude. Linux-only for the
+ * /proc readbacks; the stubs never touch process.cwd().
+ *
+ * Run: timeout 300 npx vitest run src/main/__tests__/procname-claude-spawn-sites.test.cjs
+ */
+'use strict';
+
+import { describe, it, expect, beforeAll, afterAll, afterEach } from 'vitest';
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { spawn } = require('node:child_process');
+
+const HAS_PROC = process.platform === 'linux' && fs.existsSync('/proc/self/comm');
+
+let tmpHome;
+let realHome;
+let realClaudeBin;
+let procName;
+let claudeBin;
+let scheduler;
+let reaper;
+let cr;
+let childWithLog;
+let procIdentity;
+
+beforeAll(() => {
+  realHome = process.env.HOME;
+  realClaudeBin = process.env.SM_CLAUDE_BIN;
+  tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), 'sm-pn02-'));
+  process.env.HOME = tmpHome;
+  for (const m of ['procName', 'claudeBin']) {
+    delete require.cache[require.resolve(`../lib/${m}.cjs`)];
+  }
+  procName = require('../lib/procName.cjs');
+  claudeBin = require('../lib/claudeBin.cjs');
+  scheduler = require('../scheduler.cjs');
+  reaper = require('../lib/reaperHelpers.cjs');
+  cr = require('../chatRunner.cjs');
+  childWithLog = require('../lib/childWithLog.cjs');
+  procIdentity = require('../lib/procIdentity.cjs');
+});
+
+afterAll(() => {
+  process.env.HOME = realHome;
+  if (realClaudeBin === undefined) delete process.env.SM_CLAUDE_BIN;
+  else process.env.SM_CLAUDE_BIN = realClaudeBin;
+  fs.rmSync(tmpHome, { recursive: true, force: true });
+});
+
+afterEach(() => {
+  delete process.env.SM_CLAUDE_BIN;
+  if (cr) { cr.__resetQueueForTests(); cr.attachWindow(null); }
+});
+
+// Stub `claude`: reports its OWN comm + cmdline (+ prompt) to `capturePath`,
+// emits one stream-json result and exits 0. With `linger` it stays alive so a
+// test can inspect it from outside.
+function writeStub({ capturePath, linger = false } = {}) {
+  const stubPath = path.join(tmpHome, `stub-${Math.floor(Math.random() * 1e9)}.cjs`);
+  const body = `
+    const fs = require('fs');
+    ${capturePath ? `fs.writeFileSync(${JSON.stringify(capturePath)}, JSON.stringify({
+      comm: fs.readFileSync('/proc/self/comm', 'utf8').trim(),
+      cmdline: fs.readFileSync('/proc/self/cmdline', 'utf8').replace(/\\0/g, ' ').trim(),
+    }));` : ''}
+    process.stdout.write(JSON.stringify({ type: 'result', subtype: 'success', result: 'ok' }) + '\\n');
+    ${linger ? 'setTimeout(() => process.exit(0), 30000);' : 'process.exit(0);'}
+  `;
+  fs.writeFileSync(stubPath, `#!${process.execPath}\n${body}\n`, { mode: 0o755 });
+  return stubPath;
+}
+
+async function waitFor(fn, timeoutMs = 8000) {
+  const start = Date.now();
+  for (;;) {
+    const v = fn();
+    if (v) return v;
+    if (Date.now() - start > timeoutMs) throw new Error('waitFor timed out');
+    await new Promise((r) => setTimeout(r, 25));
+  }
+}
+
+function setupProject() {
+  const projectCwd = fs.mkdtempSync(path.join(os.tmpdir(), 'sm-pn02-project-'));
+  fs.mkdirSync(path.join(tmpHome, '.claude'), { recursive: true });
+  const runDir = fs.mkdtempSync(path.join(tmpHome, '.claude', 'pn02-run-'));
+  return { projectCwd, runDir };
+}
+
+function writePrd(projectCwd, slug) {
+  const dir = path.join(projectCwd, 'session-manager-operations', 'scheduler', 'prds');
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(path.join(dir, `${slug}.md`), 'do the thing', 'utf8');
+}
+
+// Regexes replicated from the live gates; the reaperHelpers functions are ALSO
+// exercised for real below.
+const GATE = /\bclaude\b/;
+
+describe('claudeSpawnTarget', () => {
+  it('skips aliasing entirely and returns the raw value when SM_CLAUDE_BIN is set', () => {
+    process.env.SM_CLAUDE_BIN = '/tmp/some stub/with spaces';
+    expect(claudeBin.claudeSpawnTarget('job', 'slug')).toEqual({ command: '/tmp/some stub/with spaces' });
+  });
+
+  it('aliases each role to its comm and labels argv0 (SM_CLAUDE_BIN unset)', () => {
+    const real = writeStub();
+    for (const [role, alias] of [['job', 'sm-claude-job'], ['chat', 'sm-claude-chat'], ['aux', 'sm-claude-aux']]) {
+      const t = claudeBin.claudeSpawnTarget(role, 'abc', real);
+      expect(path.basename(t.command)).toBe(alias);
+      expect(t.argv0).toBe(`sm-claude-${role}:abc`);
+      expect(fs.readlinkSync(t.command)).toBe(real);
+    }
+  });
+
+  it('every real alias name and argv0 label satisfies /\\bclaude\\b/ (round-trip)', () => {
+    for (const alias of ['sm-claude-job', 'sm-claude-chat', 'sm-claude-aux']) {
+      expect(GATE.test(alias)).toBe(true);
+      expect(GATE.test(path.join(procName.procnamesRoot(), alias))).toBe(true);
+    }
+    for (const role of ['job', 'chat', 'aux']) {
+      expect(GATE.test(procName.smArgv0(role, 'a-slug'))).toBe(true);
+      expect(GATE.test(procName.smArgv0(role, undefined))).toBe(true);
+    }
+  });
+
+  it('falls back to the unchanged bin with NO argv0 when aliasing fails open', () => {
+    expect(claudeBin.claudeSpawnTarget('job', 's', 'definitely-not-a-real-cmd-xyz')).toEqual({ command: 'definitely-not-a-real-cmd-xyz' });
+  });
+});
+
+describe.skipIf(!HAS_PROC)('real aliased processes vs the reaper gates', () => {
+  const kids = [];
+  afterAll(() => { for (const k of kids) { try { process.kill(-k.pid, 'SIGKILL'); } catch { /* gone */ } } });
+
+  function spawnAliased(role, detail, { detached = true } = {}) {
+    const real = writeStub({ linger: true });
+    const t = claudeBin.claudeSpawnTarget(role, detail, real);
+    const child = spawn(t.command, ['-p', `prompt mentioning ${detail}`], {
+      cwd: os.tmpdir(), stdio: 'ignore', detached, ...(t.argv0 ? { argv0: t.argv0 } : {}),
+    });
+    kids.push(child);
+    return child;
+  }
+
+  const comm = (pid) => { try { return fs.readFileSync(`/proc/${pid}/comm`, 'utf8').trim(); } catch { return null; } };
+  const cmdline = (pid) => fs.readFileSync(`/proc/${pid}/cmdline`, 'utf8').replace(/\0/g, ' ');
+
+  it('kernel comm is the alias, cmdline carries the label + slug, and all four gates match', async () => {
+    const slug = `pn02-slug-${process.pid}-${Date.now()}`;
+    const child = spawnAliased('job', slug);
+    await waitFor(() => comm(child.pid) === 'sm-claude-job');
+    const cmd = cmdline(child.pid);
+    // A shebang stub's cmdline[0] is the interpreter and [1] the ALIAS PATH (the
+    // kernel rewrites argv for scripts, so argv0 is not visible); a native
+    // binary shows the label instead — see the ELF test below.
+    expect(cmd.includes(path.join(procName.procnamesRoot(), 'sm-claude-job'))).toBe(true);
+    expect(cmd.includes(slug)).toBe(true);
+    // scheduler.cjs killOrphanClaudePid + reaperHelpers.cjs:31 / :105 / :107 regexes
+    expect(GATE.test(cmd)).toBe(true);
+    expect(reaper.claudePidAlive(child.pid)).toBe(true);
+    expect(reaper.findLiveProcessForJob({ slug })).toBe(child.pid);
+  });
+
+  it('a native (ELF) binary shows the smArgv0 label as cmdline[0] and passes every gate', async () => {
+    const sleepBin = ['/bin/sleep', '/usr/bin/sleep'].find((p) => fs.existsSync(p));
+    if (!sleepBin) return;
+    const slug = `pn02-elf-${process.pid}-${Date.now()}`;
+    const t = claudeBin.claudeSpawnTarget('job', slug, sleepBin);
+    const child = spawn(t.command, ['30'], { cwd: os.tmpdir(), stdio: 'ignore', detached: true, argv0: t.argv0 });
+    kids.push(child);
+    await waitFor(() => comm(child.pid) === 'sm-claude-job');
+    const cmd = cmdline(child.pid);
+    expect(cmd.startsWith(`sm-claude-job:${slug}`)).toBe(true);
+    expect(GATE.test(cmd)).toBe(true);
+    expect(reaper.claudePidAlive(child.pid)).toBe(true);
+    expect(reaper.findLiveProcessForJob({ slug })).toBe(child.pid);
+    expect(scheduler.killOrphanClaudePid(child.pid)).toBe('killed');
+  });
+
+  it('findLiveProcessForJob still finds the job by slug when the argv0 label is absent (fail-open path)', async () => {
+    const slug = 'pn02-noargv0-slug';
+    const real = writeStub({ linger: true });
+    const child = spawn(real, ['-p', `claude prompt ${slug}`], { cwd: os.tmpdir(), stdio: 'ignore', detached: true });
+    kids.push(child);
+    await waitFor(() => { try { return cmdline(child.pid).includes(slug); } catch { return false; } });
+    expect(reaper.findLiveProcessForJob({ slug })).toBe(child.pid);
+  });
+
+  it('killOrphanClaudePid kills an aliased process group', async () => {
+    const child = spawnAliased('job', 'pn02-kill');
+    await waitFor(() => comm(child.pid) === 'sm-claude-job');
+    expect(scheduler.killOrphanClaudePid(child.pid)).toBe('killed');
+    await waitFor(() => child.exitCode !== null || child.signalCode !== null);
+  });
+
+  it('pid-recycling migration: identity recorded pre-alias OR post-alias for the same pid never vetoes its own kill', async () => {
+    // Legacy (unaliased) process, identity recorded "before", kill compared "after".
+    const legacyReal = writeStub({ linger: true });
+    const legacy = spawn(legacyReal, ['-p', 'claude legacy'], { cwd: os.tmpdir(), stdio: 'ignore', detached: true });
+    kids.push(legacy);
+    await waitFor(() => { try { return cmdline(legacy.pid).includes('legacy'); } catch { return false; } });
+    const recordedLegacy = procIdentity.identity(legacy.pid);
+    expect(recordedLegacy.complete).toBe(true);
+    expect(scheduler.killOrphanClaudePid(legacy.pid, recordedLegacy)).toBe('killed');
+
+    const aliased = spawnAliased('job', 'pn02-mig');
+    await waitFor(() => comm(aliased.pid) === 'sm-claude-job');
+    const recorded = procIdentity.identity(aliased.pid);
+    expect(procIdentity.isDifferentProcess(recorded, procIdentity.identity(aliased.pid))).toBe(false);
+    expect(scheduler.killOrphanClaudePid(aliased.pid, recorded)).toBe('killed');
+    // A genuinely recycled pid (different cmdline/starttime) is still vetoed.
+    expect(procIdentity.isDifferentProcess({ ...recorded, cmdline: '/usr/bin/claude -p old' }, { ...recorded, cmdline: 'sm-claude-job:new' })).toBe(true);
+  });
+
+  it('process-group semantics unchanged: detached child leads its own group; killTree/cancel reaps it', async () => {
+    const real = writeStub({ linger: true });
+    const t = claudeBin.claudeSpawnTarget('job', 'pn02-pgid', real);
+    const fd = fs.openSync(path.join(tmpHome, 'pgid.log'), 'a');
+    let exit = null;
+    const { child } = childWithLog.withChildAndLog({
+      fd, logPath: path.join(tmpHome, 'pgid.log'), safeLog() {}, closeFd() { try { fs.closeSync(fd); } catch { /* */ } },
+      spawn: { command: t.command, args: ['-p', 'claude x'], options: { cwd: os.tmpdir(), detached: true, ...(t.argv0 ? { argv0: t.argv0 } : {}) } },
+      onExit(info) { exit = info; },
+    });
+    await waitFor(() => comm(child.pid) === 'sm-claude-job');
+    const stat = fs.readFileSync(`/proc/${child.pid}/stat`, 'utf8');
+    const pgrp = Number(stat.slice(stat.lastIndexOf(')') + 2).split(' ')[2]);
+    expect(pgrp).toBe(child.pid);
+    process.kill(-child.pid, 'SIGTERM');
+    await waitFor(() => exit);
+    expect(exit.signal).toBe('SIGTERM');
+    expect(exit.leakedDescendants).toEqual([]);
+  });
+});
+
+describe.skipIf(!HAS_PROC)('comm assertions through the real runners', () => {
+  it('executeJob: the spawned claude has comm sm-claude-job', async () => {
+    const { projectCwd, runDir } = setupProject();
+    try {
+      const slug = `pn02-comm-${process.pid}-${Math.floor(Math.random() * 1e6)}`;
+      writePrd(projectCwd, slug);
+      const capturePath = path.join(runDir, 'cap.json');
+      const stub = writeStub({ capturePath });
+      // SM_CLAUDE_BIN skips aliasing by design; the test aliases explicitly.
+      process.env.SM_CLAUDE_BIN = procName.aliasBinFor(stub, 'sm-claude-job');
+      expect(path.basename(process.env.SM_CLAUDE_BIN)).toBe('sm-claude-job');
+      const result = await scheduler.executeJob({ slug, cwd: projectCwd }, runDir, projectCwd, () => Promise.resolve());
+      expect(result.exitCode).toBe(0);
+      expect(JSON.parse(fs.readFileSync(capturePath, 'utf8')).comm).toBe('sm-claude-job');
+    } finally {
+      fs.rmSync(projectCwd, { recursive: true, force: true });
+      fs.rmSync(runDir, { recursive: true, force: true });
+    }
+  });
+
+  it('chatRunner: the spawned claude has comm sm-claude-chat', async () => {
+    const cwd = fs.mkdtempSync(path.join(os.tmpdir(), 'sm-pn02-chat-'));
+    try {
+      const capturePath = path.join(tmpHome, 'chat-cap.json');
+      const stub = writeStub({ capturePath });
+      process.env.SM_CLAUDE_BIN = procName.aliasBinFor(stub, 'sm-claude-chat');
+      cr.run({ tabId: 'pn02-tab', sessionId: `pn02-sess-${process.pid}`, prompt: 'hello', cwd, resume: false });
+      await waitFor(() => fs.existsSync(capturePath));
+      expect(JSON.parse(fs.readFileSync(capturePath, 'utf8')).comm).toBe('sm-claude-chat');
+    } finally {
+      fs.rmSync(cwd, { recursive: true, force: true });
+    }
+  });
+
+  it('fail-open: an unusable ALIAS_ROOT still lets the job run to completion', async () => {
+    const { projectCwd, runDir } = setupProject();
+    fs.rmSync(procName.procnamesRoot(), { recursive: true, force: true });
+    fs.mkdirSync(path.dirname(procName.procnamesRoot()), { recursive: true });
+    fs.writeFileSync(procName.procnamesRoot(), 'not a directory'); // mkdir/symlink under it must fail
+    try {
+      const slug = `pn02-failopen-${process.pid}`;
+      writePrd(projectCwd, slug);
+      const capturePath = path.join(runDir, 'cap.json');
+      const stub = writeStub({ capturePath });
+      const aliased = procName.aliasBinFor(stub, 'sm-claude-job');
+      expect(aliased).toBe(stub); // failed open
+      process.env.SM_CLAUDE_BIN = aliased;
+      const result = await scheduler.executeJob({ slug, cwd: projectCwd }, runDir, projectCwd, () => Promise.resolve());
+      expect(result.exitCode).toBe(0);
+      // Unaliased: comm is the stub's own basename, not an sm-claude-* name.
+      expect(JSON.parse(fs.readFileSync(capturePath, 'utf8')).comm).not.toMatch(/^sm-claude-/);
+      // And the target helper degrades to the raw bin with no argv0.
+      delete process.env.SM_CLAUDE_BIN;
+      expect(claudeBin.claudeSpawnTarget('job', slug, stub)).toEqual({ command: stub });
+    } finally {
+      fs.rmSync(procName.procnamesRoot(), { force: true });
+      fs.rmSync(projectCwd, { recursive: true, force: true });
+      fs.rmSync(runDir, { recursive: true, force: true });
+    }
+  });
+});

package/src/main/__tests__/procname-sm-processes.test.cjs

@@ -0,0 +1,127 @@
+/**
+ * procname-sm-processes.test.cjs — PRD pn-03: Session Manager's own processes
+ * (main, MCP server, watchdog, inhibit holder, terminal shells) get
+ * self-describing kernel `comm` names. Headless: reads /proc/<pid>/comm.
+ * HOME is redirected BEFORE procName loads (ALIAS_ROOT is fixed at require time).
+ *
+ * Run: timeout 300 npx vitest run src/main/__tests__/procname-sm-processes.test.cjs
+ */
+'use strict';
+
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { spawn, spawnSync, execFileSync } = require('node:child_process');
+
+const LINUX = process.platform === 'linux' && fs.existsSync('/proc/self/comm');
+const REPO = path.resolve(__dirname, '..', '..', '..');
+const sleepMs = (ms) => new Promise((r) => setTimeout(r, ms));
+const commOf = (pid) => fs.readFileSync(`/proc/${pid}/comm`, 'utf8').trim();
+
+let tmpHome; let realHome; let names; let procName;
+
+beforeAll(() => {
+  realHome = process.env.HOME;
+  tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), 'sm-pn03-'));
+  process.env.HOME = tmpHome;
+  for (const m of ['procName', 'smProcNames']) delete require.cache[require.resolve(`../lib/${m}.cjs`)];
+  procName = require('../lib/procName.cjs');
+  names = require('../lib/smProcNames.cjs');
+});
+afterAll(() => {
+  process.env.HOME = realHome;
+  fs.rmSync(tmpHome, { recursive: true, force: true });
+});
+
+async function waitComm(pid, want, ms = 8000) {
+  const end = Date.now() + ms;
+  let last = '';
+  while (Date.now() < end) {
+    try { last = commOf(pid); if (last === want) return last; } catch { /* not yet */ }
+    await sleepMs(50);
+  }
+  return last;
+}
+
+describe('names', () => {
+  it('every name is <= 15 chars and distinct', () => {
+    const vals = Object.values(names.PROC_NAMES);
+    for (const v of vals) expect(v.length).toBeLessThanOrEqual(15);
+    expect(new Set(vals).size).toBe(vals.length);
+    expect(names.PROC_NAMES.main).toBe('session-manager');
+    expect(names.PROC_NAMES.main.length).toBe(15);
+  });
+});
+
+describe.skipIf(!LINUX)('process.title', () => {
+  it('sets comm and does not disturb process.argv', () => {
+    const out = execFileSync(process.execPath, ['-e', `
+      const n = require(${JSON.stringify(path.join(REPO, 'src/main/lib/smProcNames.cjs'))});
+      n.setProcessTitle(n.PROC_NAMES.main);
+      console.log(require('fs').readFileSync('/proc/self/comm','utf8').trim() + '|' + process.argv.slice(1).join(','));
+    `, 'a', '--simple'], { encoding: 'utf8', env: { ...process.env, HOME: tmpHome } }).trim();
+    expect(out).toBe('session-manager|a,--simple');
+  });
+
+  it('scheduler-mcp-server.cjs reports sm-mcp-server', async () => {
+    const child = spawn(process.execPath, [path.join(REPO, 'scripts/scheduler-mcp-server.cjs')], { stdio: ['pipe', 'ignore', 'ignore'], env: { ...process.env, HOME: tmpHome } });
+    try { expect(await waitComm(child.pid, 'sm-mcp-server')).toBe('sm-mcp-server'); } finally { child.kill('SIGKILL'); }
+  });
+
+  it('scheduler-watchdog.cjs names itself before any other work (static) and the setter yields sm-watchdog', async () => {
+    // Not spawned for real: a stale-heartbeat run relaunches the app via npx.
+    const src = fs.readFileSync(path.join(REPO, 'scripts/scheduler-watchdog.cjs'), 'utf8');
+    const first = src.indexOf('setProcessTitle(PROC_NAMES.watchdog)');
+    expect(first).toBeGreaterThan(-1);
+    expect(first).toBeLessThan(src.indexOf("require('node:fs')"));
+    const child = spawn(process.execPath, ['-e', `require(${JSON.stringify(path.join(REPO, 'src/main/lib/smProcNames.cjs'))}).setProcessTitle('sm-watchdog'); setTimeout(()=>{},20000)`], { stdio: 'ignore', env: { ...process.env, HOME: tmpHome } });
+    try { expect(await waitComm(child.pid, 'sm-watchdog')).toBe('sm-watchdog'); } finally { child.kill('SIGKILL'); }
+  });
+
+  it('inhibit holder shell aliased to sm-inhibit-hold runs the poll loop', async () => {
+    const child = spawn(names.inhibitHolderShell(), ['-c', `while kill -0 ${process.pid} 2>/dev/null; do sleep 1; done`], { stdio: 'ignore' });
+    try { expect(await waitComm(child.pid, 'sm-inhibit-hold')).toBe('sm-inhibit-hold'); } finally { child.kill('SIGKILL'); }
+  });
+
+  it('bash login shell via sm-shell still sources rc files and keeps $SHELL', () => {
+    const bash = ['/bin/bash', '/usr/bin/bash'].find((p) => fs.existsSync(p));
+    if (!bash) return;
+    const bin = names.aliasedShellBin(bash);
+    expect(path.basename(bin)).toBe('sm-shell');
+    fs.writeFileSync(path.join(tmpHome, '.bash_profile'), 'export SM_RC_MARK=sourced\n');
+    fs.writeFileSync(path.join(tmpHome, '.bashrc'), 'export SM_RC_MARK=sourced\n');
+    const r = spawnSync(bin, ['-il', '-c', 'echo "$SM_RC_MARK|$SHELL|$(cat /proc/$$/comm)"'], { encoding: 'utf8', env: { HOME: tmpHome, SHELL: bash, PATH: process.env.PATH } });
+    expect(r.stdout.trim().split('\n').pop()).toBe(`sourced|${bash}|sm-shell`);
+  });
+
+  it('loadGate top-CPU line (ps comm) shows an aliased process', async () => {
+    const child = spawn(names.inhibitHolderShell(), ['-c', 'while :; do :; done'], { stdio: 'ignore' });
+    try {
+      await waitComm(child.pid, 'sm-inhibit-hold');
+      const out = execFileSync('ps', ['-eo', 'pid,pcpu,comm', '--sort=-pcpu'], { encoding: 'utf8' });
+      expect(out).toMatch(new RegExp(`^\\s*${child.pid}\\s+\\S+\\s+sm-inhibit-hold$`, 'm'));
+    } finally { child.kill('SIGKILL'); }
+  });
+});
+
+describe('shell aliasing rules', () => {
+  it('skips non-bash/zsh shells (fish, nu, unknown) and non-strings', () => {
+    for (const s of ['/usr/bin/fish', '/usr/bin/nu', '/opt/weird/xsh', '', undefined]) expect(names.aliasedShellBin(s)).toBe(s);
+  });
+  it('aliases zsh by path basename', () => {
+    const fake = path.join(tmpHome, 'zsh');
+    fs.writeFileSync(fake, '#!/bin/sh\n', { mode: 0o755 });
+    expect(path.basename(names.aliasedShellBin(fake))).toBe('sm-shell');
+  });
+  it('fails open when ALIAS_ROOT is unwritable', () => {
+    fs.rmSync(procName.procnamesRoot(), { recursive: true, force: true });
+    fs.mkdirSync(path.dirname(procName.procnamesRoot()), { recursive: true });
+    fs.writeFileSync(procName.procnamesRoot(), 'a file, so mkdir/symlink under it fails');
+    try {
+      expect(names.inhibitHolderShell()).toBe('/bin/sh');
+      const bash = ['/bin/bash', '/usr/bin/bash'].find((p) => fs.existsSync(p));
+      if (bash) expect(names.aliasedShellBin(bash)).toBe(bash);
+    } finally { fs.rmSync(procName.procnamesRoot(), { force: true }); }
+  });
+});