claude-code-session-manager 0.86.0 → 0.88.0

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

@@ -7,12 +7,17 @@
 
 'use strict';
 
-import { test, expect, afterEach } from 'vitest';
+import { test, expect, afterEach, vi } from 'vitest';
 const fs = require('node:fs');
 const fsp = require('node:fs/promises');
 const os = require('node:os');
 const path = require('node:path');
-const { resolvePrdWriteDir, resolvePrdsDirs } = require('../lib/prdLocations.cjs');
+const {
+  resolvePrdWriteDir,
+  resolvePrdsDirs,
+  resolveEpicPrdWriteDir,
+  listEpicPrdDirs,
+} = require('../lib/prdLocations.cjs');
 
 const tmpDirs = [];
 afterEach(async () => {
@@ -95,3 +100,96 @@ test('resolvePrdsDirs returns [] when no project has a recent transcript', () =>
   const dirs = resolvePrdsDirs(90, { projectsDir: '/nonexistent-projects-dir' });
   expect(dirs).toEqual([]);
 });
+
+test('listEpicPrdDirs memoizes on the Epics-root mtime: no readdir on a repeat call, but a freshly minted Epic prds dir is picked up on the very next call', async () => {
+  const cwd = await fsp.mkdtemp(path.join(os.tmpdir(), 'sm-prdloc-memo-cwd-'));
+  tmpDirs.push(cwd);
+  fs.mkdirSync(resolveEpicPrdWriteDir(cwd, 'epic-1'), { recursive: true });
+
+  const first = listEpicPrdDirs(cwd);
+  expect(first).toEqual([resolveEpicPrdWriteDir(cwd, 'epic-1')]);
+
+  const readdirSpy = vi.spyOn(fs, 'readdirSync');
+  try {
+    // Nothing under the Epics root changed — the cached result comes back
+    // without a fresh readdir of the Epics root.
+    const second = listEpicPrdDirs(cwd);
+    expect(second).toEqual(first);
+    expect(readdirSpy).not.toHaveBeenCalled();
+  } finally {
+    readdirSpy.mockRestore();
+  }
+
+  // A brand-new Epic's prds/ dir is a NEW entry under the Epics root, which
+  // bumps the root's own mtime — no TTL wait required to see it.
+  fs.mkdirSync(resolveEpicPrdWriteDir(cwd, 'epic-2'), { recursive: true });
+  const third = listEpicPrdDirs(cwd);
+  expect(third).toEqual(
+    expect.arrayContaining([resolveEpicPrdWriteDir(cwd, 'epic-1'), resolveEpicPrdWriteDir(cwd, 'epic-2')]),
+  );
+});
+
+test('listEpicPrdDirs: an unreadable Epics root does not write a poisoned entry that survives the dir becoming readable', async () => {
+  const cwd = await fsp.mkdtemp(path.join(os.tmpdir(), 'sm-prdloc-unreadable-cwd-'));
+  tmpDirs.push(cwd);
+
+  // No Epics root at all yet.
+  expect(listEpicPrdDirs(cwd)).toEqual([]);
+
+  // The root now exists, with a real Epic prds dir inside it.
+  fs.mkdirSync(resolveEpicPrdWriteDir(cwd, 'epic-1'), { recursive: true });
+  expect(listEpicPrdDirs(cwd)).toEqual([resolveEpicPrdWriteDir(cwd, 'epic-1')]);
+});
+
+test('resolvePrdsDirs EDGE (non-negotiable): a new epics/<id>/prds dir created after a prior call is visible on the VERY NEXT call, no TTL wait', async () => {
+  const projectsDir = await fsp.mkdtemp(path.join(os.tmpdir(), 'sm-prdloc-freshness-projects-'));
+  tmpDirs.push(projectsDir);
+  const projectCwd = await fsp.mkdtemp(path.join(os.tmpdir(), 'sm-prdloc-freshness-cwd-'));
+  tmpDirs.push(projectCwd);
+
+  const projDir = path.join(projectsDir, 'freshness-project');
+  fs.mkdirSync(projDir, { recursive: true });
+  fs.writeFileSync(path.join(projDir, 'session1.jsonl'), `${JSON.stringify({ cwd: projectCwd })}\n`);
+
+  const before = resolvePrdsDirs(90, { projectsDir });
+  const newEpicPrdDir = resolveEpicPrdWriteDir(projectCwd, 'freshly-minted-epic');
+  expect(before).not.toContain(newEpicPrdDir);
+
+  fs.mkdirSync(newEpicPrdDir, { recursive: true });
+
+  const after = resolvePrdsDirs(90, { projectsDir });
+  expect(after).toContain(newEpicPrdDir);
+});
+
+test('resolvePrdsDirs: calls with an explicit { projectsDir } opts are keyed separately per projectsDir and never share a stale cache entry', async () => {
+  const projectsDirA = await fsp.mkdtemp(path.join(os.tmpdir(), 'sm-prdloc-keyed-a-'));
+  tmpDirs.push(projectsDirA);
+  const projectsDirB = await fsp.mkdtemp(path.join(os.tmpdir(), 'sm-prdloc-keyed-b-'));
+  tmpDirs.push(projectsDirB);
+  const cwdA = await fsp.mkdtemp(path.join(os.tmpdir(), 'sm-prdloc-keyed-cwd-a-'));
+  tmpDirs.push(cwdA);
+  const cwdB = await fsp.mkdtemp(path.join(os.tmpdir(), 'sm-prdloc-keyed-cwd-b-'));
+  tmpDirs.push(cwdB);
+
+  const projDirA = path.join(projectsDirA, 'proj-a');
+  fs.mkdirSync(projDirA, { recursive: true });
+  fs.writeFileSync(path.join(projDirA, 'session1.jsonl'), `${JSON.stringify({ cwd: cwdA })}\n`);
+  fs.mkdirSync(resolvePrdWriteDir(cwdA), { recursive: true });
+
+  const projDirB = path.join(projectsDirB, 'proj-b');
+  fs.mkdirSync(projDirB, { recursive: true });
+  fs.writeFileSync(path.join(projDirB, 'session1.jsonl'), `${JSON.stringify({ cwd: cwdB })}\n`);
+  fs.mkdirSync(resolvePrdWriteDir(cwdB), { recursive: true });
+
+  const dirsA = resolvePrdsDirs(90, { projectsDir: projectsDirA });
+  const dirsB = resolvePrdsDirs(90, { projectsDir: projectsDirB });
+
+  expect(dirsA).toContain(resolvePrdWriteDir(cwdA));
+  expect(dirsA).not.toContain(resolvePrdWriteDir(cwdB));
+  expect(dirsB).toContain(resolvePrdWriteDir(cwdB));
+  expect(dirsB).not.toContain(resolvePrdWriteDir(cwdA));
+
+  // Re-querying A after B was resolved must still reflect A's own state, not
+  // B's — proof the two opts objects never shared one cache key.
+  expect(resolvePrdsDirs(90, { projectsDir: projectsDirA })).toEqual(dirsA);
+});

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

@@ -21,7 +21,7 @@
 
 'use strict';
 
-import { test, expect, afterEach } from 'vitest';
+import { test, expect, afterEach, vi } from 'vitest';
 const fs = require('node:fs');
 const fsp = require('node:fs/promises');
 const os = require('node:os');
@@ -150,3 +150,52 @@ test('scheduler.cjs exports candidateArchivedPrdsDirs alongside candidatePrdsDir
   expect(Array.isArray(candidatePrdsDirs())).toBe(true);
   expect(Array.isArray(candidateArchivedPrdsDirs())).toBe(true);
 });
+
+test('resolveArchivedPrdsDirs: a prds-archived/ dir created inside an ALREADY-EXISTING Epic (the archiveCompletedPrd shape — does not bump the Epics root mtime) is bounded-stale, not stale forever', async () => {
+  // archiveCompletedPrd (scheduler.cjs) creates `epics/<id>/prds-archived/`
+  // as a new entry INSIDE an already-existing `epics/<id>/` dir — unlike a
+  // brand-new Epic's `prds/` (created in the same mkdirSync call as
+  // `epics/<id>/` itself), this does NOT bump the Epics root's own mtime,
+  // 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.
+  //
+  // 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 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');
+    expect(before).not.toContain(path.resolve(epicArchiveDir));
+
+    // The archiveCompletedPrd shape: a NEW prds-archived/ dir appears inside
+    // the ALREADY-EXISTING epic dir. This does not change the Epics root's
+    // own mtime.
+    fs.mkdirSync(epicArchiveDir, { recursive: true });
+
+    // Bounded staleness is acceptable — but it must actually be bounded.
+    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 {
+    vi.useRealTimers();
+  }
+});

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

@@ -0,0 +1,222 @@
+/**
+ * prdSetDisposition.test.cjs — scheduler wave-disposition PRD:
+ * scheduler.remote.setPrdDisposition (backing the renderer's
+ * `schedule:set-prd-disposition` IPC action) is how a human changes an
+ * already-written PRD's disposition from the Scheduler UI — promoting an
+ * appended wave to its own head, or re-attaching a head behind another
+ * chain. Validates via prdDisposition.cjs's computeDispositionRewrite
+ * (cycle-safety, running/completed rows untouched) before delegating the
+ * actual write to the SAME remote.updatePrd every other PRD edit path uses.
+ *
+ * Mirrors prdUpdateDependsOn.test.cjs's HOME-isolation fixture.
+ *
+ * Run: timeout 120 npx vitest run src/main/__tests__/prdSetDisposition.test.cjs
+ */
+
+'use strict';
+
+import { test, expect, beforeAll, afterAll } from 'vitest';
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+let tmpHome;
+let originalHome;
+let scheduler;
+let queueStore;
+let config;
+
+beforeAll(() => {
+  originalHome = process.env.HOME;
+  tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), 'sm-set-disposition-home-'));
+  process.env.HOME = tmpHome;
+
+  scheduler = require('../scheduler.cjs');
+  queueStore = require('../lib/queueStore.cjs');
+  config = require('../config.cjs');
+
+  if (!scheduler.PRDS_DIR.startsWith(tmpHome)) {
+    throw new Error(`refusing to run: PRDS_DIR (${scheduler.PRDS_DIR}) is not under the temp HOME (${tmpHome})`);
+  }
+});
+
+afterAll(() => {
+  process.env.HOME = originalHome;
+  fs.rmSync(tmpHome, { recursive: true, force: true });
+});
+
+function registerActiveProject(cwd) {
+  const projectsDir = path.join(tmpHome, '.claude', 'projects');
+  const slugDir = path.join(projectsDir, `fake-project-slug-${path.basename(cwd)}`);
+  fs.mkdirSync(slugDir, { recursive: true });
+  fs.writeFileSync(path.join(slugDir, 'transcript.jsonl'), JSON.stringify({ cwd }) + '\n');
+}
+
+function makeFixtureProject(prefix) {
+  const cwd = fs.mkdtempSync(path.join(os.tmpdir(), prefix));
+  registerActiveProject(cwd);
+  config.addAllowedRoot(cwd);
+  const opsRoot = path.join(cwd, 'session-manager-operations');
+  const prdsDir = path.join(opsRoot, 'scheduler', 'epics', 'test-epic-1', 'prds');
+  const stateDir = path.join(opsRoot, 'scheduler', 'state');
+  fs.mkdirSync(prdsDir, { recursive: true });
+  fs.mkdirSync(stateDir, { recursive: true });
+  fs.writeFileSync(path.join(stateDir, 'queue.json'), JSON.stringify({ jobs: [] }, null, 2), 'utf8');
+  queueStore.bustCwdCache();
+  return { cwd, prdsDir, stateDir };
+}
+
+function writePrd(prdsDir, filename, cwd, extraFrontmatter = '') {
+  fs.writeFileSync(
+    path.join(prdsDir, filename),
+    `---\ntitle: ${filename}\ncwd: ${cwd}\nestimateMinutes: 10\ncreatedVia: scheduler-api\n${extraFrontmatter}---\n\n# Goal\nDo the thing.\n`,
+    'utf8',
+  );
+}
+
+/** Seeds a queue.json row for `slug` with the given status — setPrdDisposition
+ *  (like updatePrd) reads job status off the live queue, not the PRD file. */
+function seedQueueJob(stateDir, slug, status) {
+  fs.writeFileSync(
+    path.join(stateDir, 'queue.json'),
+    JSON.stringify({ jobs: [{ slug, status, title: slug, cwd: '' }] }, null, 2),
+    'utf8',
+  );
+  queueStore.bustCwdCache();
+}
+
+test('append sets the expected edges', async () => {
+  const { cwd, prdsDir } = makeFixtureProject('sm-set-disposition-append-');
+  try {
+    writePrd(prdsDir, '3-wave1-tail.md', cwd);
+    writePrd(prdsDir, '4-wave2-root.md', cwd);
+
+    const result = await scheduler.remote.setPrdDisposition({
+      slug: '4-wave2-root',
+      cwd,
+      disposition: 'append',
+      dependsOn: ['3-wave1-tail'],
+    });
+
+    expect(result.ok).toBe(true);
+    const written = fs.readFileSync(path.join(prdsDir, '4-wave2-root.md'), 'utf8');
+    expect(written).toMatch(/^dependsOn: \[3-wave1-tail\]$/m);
+    expect(written).toMatch(/^disposition: append$/m);
+  } finally {
+    fs.rmSync(cwd, { recursive: true, force: true });
+  }
+});
+
+test('new-head sets none', async () => {
+  const { cwd, prdsDir } = makeFixtureProject('sm-set-disposition-new-head-');
+  try {
+    writePrd(prdsDir, '3-wave1-tail.md', cwd);
+    writePrd(prdsDir, '4-wave2-root.md', cwd, 'dependsOn: [wave1-tail]\ndisposition: append\n');
+
+    const result = await scheduler.remote.setPrdDisposition({
+      slug: '4-wave2-root',
+      cwd,
+      disposition: 'new-head',
+    });
+
+    expect(result.ok).toBe(true);
+    const written = fs.readFileSync(path.join(prdsDir, '4-wave2-root.md'), 'utf8');
+    expect(written).not.toContain('dependsOn');
+    expect(written).toMatch(/^disposition: new-head$/m);
+  } finally {
+    fs.rmSync(cwd, { recursive: true, force: true });
+  }
+});
+
+test('promoting a wave to a head removes exactly its root edges', async () => {
+  const { cwd, prdsDir } = makeFixtureProject('sm-set-disposition-promote-');
+  try {
+    writePrd(prdsDir, '3-wave1-tail.md', cwd);
+    writePrd(prdsDir, '5-other-head.md', cwd);
+    writePrd(prdsDir, '4-wave2-root.md', cwd, 'dependsOn: [wave1-tail]\ndisposition: append\n');
+
+    const result = await scheduler.remote.setPrdDisposition({
+      slug: '4-wave2-root',
+      cwd,
+      disposition: 'new-head',
+    });
+
+    expect(result.ok).toBe(true);
+    const promoted = fs.readFileSync(path.join(prdsDir, '4-wave2-root.md'), 'utf8');
+    expect(promoted).not.toContain('dependsOn');
+    // The unrelated sibling head is untouched by this call.
+    const other = fs.readFileSync(path.join(prdsDir, '5-other-head.md'), 'utf8');
+    expect(other).not.toContain('dependsOn');
+  } finally {
+    fs.rmSync(cwd, { recursive: true, force: true });
+  }
+});
+
+test('a change that would create a cycle is rejected, and nothing is written', async () => {
+  const { cwd, prdsDir } = makeFixtureProject('sm-set-disposition-cycle-');
+  try {
+    writePrd(prdsDir, '3-a.md', cwd, 'dependsOn: [b]\n');
+    writePrd(prdsDir, '4-b.md', cwd);
+    const before = fs.readFileSync(path.join(prdsDir, '4-b.md'), 'utf8');
+
+    const result = await scheduler.remote.setPrdDisposition({
+      slug: '4-b',
+      cwd,
+      disposition: 'append',
+      dependsOn: ['3-a'],
+    });
+
+    expect(result.ok).toBe(false);
+    expect(result.error).toMatch(/cycle/i);
+    const after = fs.readFileSync(path.join(prdsDir, '4-b.md'), 'utf8');
+    expect(after).toBe(before);
+  } finally {
+    fs.rmSync(cwd, { recursive: true, force: true });
+  }
+});
+
+test('running rows are untouched', async () => {
+  const { cwd, prdsDir, stateDir } = makeFixtureProject('sm-set-disposition-running-');
+  try {
+    writePrd(prdsDir, '3-wave1-tail.md', cwd);
+    writePrd(prdsDir, '4-wave2-root.md', cwd, 'dependsOn: [wave1-tail]\ndisposition: append\n');
+    seedQueueJob(stateDir, '4-wave2-root', 'running');
+    const before = fs.readFileSync(path.join(prdsDir, '4-wave2-root.md'), 'utf8');
+
+    const result = await scheduler.remote.setPrdDisposition({
+      slug: '4-wave2-root',
+      cwd,
+      disposition: 'new-head',
+    });
+
+    expect(result.ok).toBe(false);
+    expect(result.error).toMatch(/running/i);
+    const after = fs.readFileSync(path.join(prdsDir, '4-wave2-root.md'), 'utf8');
+    expect(after).toBe(before);
+  } finally {
+    fs.rmSync(cwd, { recursive: true, force: true });
+  }
+});
+
+test('completed rows are untouched', async () => {
+  const { cwd, prdsDir, stateDir } = makeFixtureProject('sm-set-disposition-completed-');
+  try {
+    writePrd(prdsDir, '3-wave1-tail.md', cwd);
+    writePrd(prdsDir, '4-wave2-root.md', cwd, 'dependsOn: [wave1-tail]\ndisposition: append\n');
+    seedQueueJob(stateDir, '4-wave2-root', 'completed');
+    const before = fs.readFileSync(path.join(prdsDir, '4-wave2-root.md'), 'utf8');
+
+    const result = await scheduler.remote.setPrdDisposition({
+      slug: '4-wave2-root',
+      cwd,
+      disposition: 'new-head',
+    });
+
+    expect(result.ok).toBe(false);
+    expect(result.error).toMatch(/completed/i);
+    const after = fs.readFileSync(path.join(prdsDir, '4-wave2-root.md'), 'utf8');
+    expect(after).toBe(before);
+  } finally {
+    fs.rmSync(cwd, { recursive: true, force: true });
+  }
+});

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